[03/36] Add OC-030 gRPC unary protobuf support

[cjohnsto-nz]

---

This is part 19 of 21 in a stack made with GitButler:

•  21  [22/36] Release 0.8.0 with packaged PDF.js preview #54
•  20  [21/36] Complete OC-070 protocol surface polish #56
•  19  [20/36] Record final OpenCollection supervisor acceptance #53
•  18  [19/36] Add OC-110 runtime authoring UX #52
•  17  [18/36] Add OC-080 runtime lifecycle and OC-110 task setup #51
•  16  [16/36] Record OC-050 OC-090 OC-100 supervisor audit #50
•  15  [15/36] Add OC-050 auth and transport support #49
•  14  [14/36] Add OC-100 request type UX #48
•  13  [13/36] Add OC-100 request type UX task #47
•  12  [12/36] Add OC-080 and OC-090 task tracks #46
•  11  [11/36] Record OC-010 through OC-040 supervisor audit #45
•  10  [10/36] Add OC-020 WebSocket support #44
•  9  [09/36] Add OC-010 GraphQL support #43
•  8  [08/36] Require demo server fixtures for parallel tracks #42
•  7  [07/36] Record OC-000 and OC-060 supervisor audit #41
•  6  [06/36] Add OC-060 schema round-trip validation #40
•  5  [05/36] Add OC-040 runtime scripting support #39
•  4  [04/36] Add OC-090 gRPC streaming support #38
•  3  [03/36] Add OC-030 gRPC unary protobuf support #37 <-- current
•  2  [02/36] Add OC-000 protocol dispatch foundation #36
•  1  [01/36] Add OpenCollection agent plan #35

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​types/​ws@​8.18.1
	@​grpc/​proto-loader@​0.8.1
	@​grpc/​grpc-js@​1.14.4
	ws@​8.21.0

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: npm @protobufjs/float is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: package-lock.json → npm/@grpc/proto-loader@0.8.1 → npm/@protobufjs/float@1.0.2 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@protobufjs/float@1.0.2. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[APKiwi]

Verdict: request changes. The headline feature is dead code and an unrelated dep rides along.

• Major: the gRPC executor is never wired. extension.ts:48 constructs new RequestExecutionService(httpClient) with no gRPC client, so _grpcClient is always undefined and requestExecutionService.ts:199 falls through to UnsupportedProtocolError for every gRPC request. git grep "new GrpcClient" finds only the declaration. The 481-line client and its tests are unreachable at runtime, sending a gRPC request still says execution is not available. The integration test passes only because it injects a mock grpcClient, so CI stays green while the wiring is absent. Same story for _webSocketClient.
• Major: ws + @types/ws added but entirely unused. No from 'ws' import exists anywhere at this PR's head. A WebSocket runtime dep has no business in the gRPC PR, move it to the OC-020 PR that actually imports it.
• Minor: gRPC application errors are thrown instead of surfaced. _executeUnary (grpcClient.ts:178-181) rejects on any non-OK status before reading trailing metadata, so NOT_FOUND / INVALID_ARGUMENT become exceptions and the trailers are discarded. HTTP non-2xx gets a full viewable response, gRPC errors deserve the same (return a response carrying status + trailers).
• Minor: channel leak on synchronous throw. The client is created and _activeCalls.set runs before the Promise executor, so if the service constructor or method call throws synchronously, finish() never runs and the channel stays open until cancelAll.
• Minor: protoLoader.loadSync (grpcClient.ts:94) does sync file IO + parse on the extension host thread. Large proto trees will jank the UI, use the async load.
• Minor: schemeless targets are silently insecure. _normalizeTarget treats bare host:port as insecure credentials, so pointing at a TLS endpoint as host:443 fails confusingly. No CA/mTLS option either, fine for MVP but document it.
• Minor: _resolveProtoFilePath accepts absolute paths and ../ with no workspace-trust gate. Parse-only so impact is limited, but error messages leak resolved paths and allow existence probing.
• Nit: _lowerFirst(x).toLowerCase() is redundant. CLI auth has its own hardcoded 30s timeout uncounted against missio.timeout.
• Scope: this PR also lands GraphQL execution support and a 931-line runtimeExecutionService, neither of which is gRPC. The title covers a third of the diff.

Tests: good in isolation (real in-process server, metadata merge, auth, error paths) but nothing exercises real extension wiring, which is exactly how the missing registration slipped through.

Deps: @grpc/grpc-js + @grpc/proto-loader are the right buy, canonical maintained packages, and hand-rolling protobuf/HTTP2 is not a realistic alternative. Transitive tree is the standard protobufjs stack, acceptable. Checked for vendored/minified/obfuscated blobs: none in this PR, all additions are declared npm packages with standard integrity hashes. The two real dep issues are the unused ws above and protobufjs promoting @types/node/undici-types into the prod graph (transitive, not your doing, just noting).

[cjohnsto-nz]

Already addressed in the complete stack where appropriate; the remaining items are intentional OC-030 boundaries.

• Runtime wiring: shared client composition is implemented in PR [15/36] Add OC-050 auth and transport support #49, commit 06e680c. That commit constructs the protocol clients and passes them into RequestExecutionService. PR [03/36] Add OC-030 gRPC unary protobuf support #37 owns the gRPC client, dispatch seam, and fixture-backed unary execution; it is not the final composition slice.
• ws and @types/ws: not changing. Their first consumer is src/services/webSocketClient.ts in PR [05/36] Add OC-040 runtime scripting support #39, commit 45e5800, before the OC-020 branch. Moving them to OC-020 would therefore be incorrect. Moving package-lock ownership from [03/36] Add OC-030 gRPC unary protobuf support #37 to [05/36] Add OC-040 runtime scripting support #39 now would require rewriting and restacking the descendant chain without changing the completed dependency graph.
• Non-OK gRPC status handling: not changing. OC-030 models failed RPCs as errors carrying grpcStatus and grpcDetails; successful unary calls return response metadata and status. An HTTP-style response representation for failed RPCs is not part of the OC-030 contract.
• Synchronous cleanup: not changing. A constructor failure occurs before the call is tracked, so it cannot leave an _activeCalls entry. The generated unary method is invoked only after proto, service, and method resolution and uses grpc-js's callback path; a synchronous throw from that already-resolved generated method is not a supported execution path.
• Proto loading: not changing. OC-030 deliberately loads small, local protobuf definitions during an explicit request execution. Background parsing and indefinite extension-host workloads are outside this task.
• Transport: bare host:port deliberately selects insecure credentials; grpcs:// or https:// explicitly selects TLS. CA and mTLS completion are not OC-030 acceptance criteria.
• Proto paths: not changing. Absolute and collection-relative proto paths are intentional user-configured inputs. The files are parsed rather than executed, and resolved paths are included in diagnostics so configuration failures are actionable.
• CLI auth timeout: the independent 30-second limit is an intentional safety bound for an external authentication command, separate from the RPC deadline.
• GraphQL/runtime files: they are shared stacked scaffolding consumed by later task slices. Repartitioning them now would rewrite descendants without changing final behavior.

The unary path is exercised against an in-process gRPC server, including proto imports, metadata precedence, interpolation, authentication, errors, and dispatch through an injected executor. No additional source changes are required on PR #37. The PR and its child edge are currently MERGEABLE / CLEAN.