feat(extension): migrate task transport from gRPC to JSON-RPC over TCP loopback (PR 2/3)

[wenytang-ms]

Migrate task transport from gRPC to JSON-RPC over TCP loopback (PR 2/3)

Companion to #1863 (PR 1/3, gradle-server Java side). Together they replace the gRPC + Netty + HTTP/2 task transport with JSON-RPC (LSP4J wire format) over a plain TCP loopback connection, permanently eliminating the mid-frame race described in #1815.

This PR is the TypeScript extension half of the hard cut-over: it deletes the gRPC client and rebuilds TaskServerClient on top of vscode-jsonrpc. No version ships between PR 1, PR 2 and PR 3.

What changes

New transport package — extension/src/transport/jsonrpc/

File	Role
GradleJsonRpcClient.ts	Typed facade over MessageConnection. Exposes the six gradle/* methods (getBuild, runBuild, getProjectDependencies, cancelBuild, cancelBuilds, executeCommand) and demultiplexes the two streaming gradle/*/reply notifications back to per-call callbacks by streamId.
loopbackServer.ts	Binds 127.0.0.1:0, returns { port, connection: Promise<MessageConnection> }. Accepts a single inbound socket, wraps it with SocketMessageReader/Writer, enforces a 30 s connect timeout (matches TaskSocketServer.CONNECT_TIMEOUT_MS on the Java side).
protoCodec.ts	encodeProto(Uint8Array): string / decodeProto(string): Uint8Array — base64 ↔ proto bytes.
streamId.ts	Monotonic id generator for streaming RPCs.
JsonRpcErrors.ts	Pinned numeric codes (UNKNOWN=-32000, NOT_FOUND=-32001, CANCELLED=-32002, INTERNAL=-32603) + GradleRpcError shape + isNotFound/isCancelled/isUnknown helpers + toGradleRpcError(ResponseError) converter.
types.ts	GradleRequestParams, GradleResponse, GradleStreamPayload — the wire shapes pinned by PR 1.

Architecture flip — extension listens, JVM dials in

PR 1 turned the JVM into a TCP client (TaskSocketServer). PR 2 makes the extension the TCP server:

• GradleServer.start() now calls createLoopbackListener() before spawning the JVM, then passes the bound ephemeral port via the same --port=<n> arg. This eliminates any window where the JVM could try to connect before the extension is ready.
• New GradleServer.awaitTaskConnection(): Promise<MessageConnection> exposes the resulting connection to TaskServerClient.

TaskServerClient.ts — full rewrite

• Drops GrpcClient, grpc.credentials.createInsecure, waitForReady, getChannel().getConnectivityState, and the @grpc/grpc-js/gradle_grpc_pb imports.
• Replaces them with GradleJsonRpcClient wrapping the MessageConnection received from GradleServer.awaitTaskConnection().
• Error branching now uses isNotFound(err) / isCancelled(err) / isUnknown(err) from JsonRpcErrors.
• Drops the retryOnSpuriousCancel wrappers — the Node.js HTTP/2 stream race the helper compensated for cannot occur over plain TCP + LSP4J framing.

GradleRunnerTerminal.ts

• import { ServiceError, status } from "@grpc/grpc-js" → import from transport/jsonrpc.
• err.code === status.UNKNOWN → isUnknown(err).

Cleanup (no compat shims, per the design)

• Delete extension/src/proto/gradle_grpc_pb.{js,d.ts} (no longer generated).
• Delete extension/src/client/retryOnSpuriousCancel.ts and its unit test.
• extension/build.gradle: drop protobuf.plugins.grpc { … }, drop the per-task grpc { … } wiring, drop ts { option 'service=grpc-node,mode=grpc-js' } so protoc-gen-ts stops emitting service stubs. The js builtin + ts plugin remain — gradle_pb.{js,d.ts} are still generated and used for message classes.
• extension/package.json: remove @grpc/grpc-js and grpc-tools from devDependencies; add vscode-jsonrpc: ^6.0.0 to dependencies (was already transitively present via vscode-languageclient, now pinned as a direct dep).
• Extension.ts: drop the now-unused clientLogger (was only used to set the grpc-js global logger).

Wire contract (pinned by PR 1)

Aspect	Value
Method namespace	gradle/
Methods	getBuild, runBuild, getProjectDependencies, cancelBuild, cancelBuilds, executeCommand
Streaming notifications	gradle/getBuild/reply, gradle/runBuild/reply
Request params	{ request: string | null, streamId: number | null } — request is base64 of proto bytes; streamId set only on streaming RPCs
Response	{ reply: string | null } — base64 of terminal *Reply proto bytes (null for streaming RPCs whose full payload was delivered via notifications)
Notification payload	{ streamId: number, payload: string } — base64 of streamed *Reply proto bytes
Error codes	-32000 UNKNOWN, -32001 NOT_FOUND, -32002 CANCELLED, -32603 INTERNAL

JSON-RPC communication design

Streaming model — request + correlated notifications + terminal reply

gRPC server-streaming (GetBuild, RunBuild) is reshaped onto JSON-RPC's request/notification split:

• The incremental replies arrive as gradle/*/reply notifications, each carrying its streamId.
• The terminal reply rides on the JSON-RPC response to the original request (or reply: null when the full payload was already delivered via notifications).

This split is required because a JSON-RPC notification has no id to await, while only the response can settle the call's promise. Per-call lifecycle in GradleJsonRpcClient: allocate a streamId → register its sink → send the request → each inbound notification is dispatched to the sink keyed by streamId → the response resolves the promise → the sink is removed in a finally. A late notification arriving after the promise settles finds no sink (Map.get → undefined) and is silently dropped, so it can never bleed into another in-flight call.

Cancellation — business-level, not $/cancelRequest

Cancellation does not use JSON-RPC's $/cancelRequest. It keeps the existing business-level contract: a separate cancelBuild RPC carrying the cancellationKey. The streaming request's promise stays open until the server emits a terminal Cancelled reply. This mirrors the previous gRPC behaviour and keeps cancellation semantics identical across the cut-over.

Single connection — strict ordering, deliberate head-of-line tradeoff

All six methods and both notification streams share one TCP socket with LSP4J Content-Length framing, which guarantees strict in-order delivery — this is exactly what makes "all of a stream's notifications arrive before its terminal response" hold, and is the basis of the streaming correctness above. The tradeoff is no multiplexing: concurrent builds are serialized on a single connection. That is intentional — collapsing to one non-multiplexed socket is precisely what removes the HTTP/2 frame race behind #1815.

Connection lifecycle & failure semantics

On socket close/error the MessageConnection fires onClose/onError and any in-flight sendRequest promises reject. There is no auto-reconnect at the transport layer: a dropped connection surfaces as a rejected call, and recovery goes through the existing GradleServer JVM-exit handler + restart() path. This is consistent with dropping retryOnSpuriousCancel — there is no silent retry on the wire.

Security model (current) — and deferred handshake auth

The listener binds 127.0.0.1 only (no remote reachability), accepts only the first inbound connection, and enforces a 30 s connect timeout. The ephemeral port comes from listen(0) (kernel-assigned free port — no port-probe race, no collision-retry needed). A cryptographic handshake nonce to authenticate the connecting JVM (so a same-host process cannot pre-empt the real JVM by connecting to the loopback port first) was considered but is intentionally deferred — not implemented in this PR, tracked as a follow-up. Note: switching ports would not substitute for it, since any loopback port is enumerable and reachable by same-host processes regardless of its number.

Tests

New extension/src/test/unit/transport/GradleJsonRpcClient.test.ts (7 tests, all passing locally):

• Base64 proto codec roundtrip.
• getBuild streaming dispatch — multiple notifications, terminal reply: null response.
• Concurrent streaming calls multiplexed by streamId without cross-pollination.
• runBuild streaming dispatch.
• Unary getProjectDependencies / cancelBuild / cancelBuilds / executeCommand roundtrip.
• ResponseError translation into GradleRpcError for NOT_FOUND / CANCELLED / INTERNAL.

The test wires two MessageConnections back-to-back over PassThrough streams, mirroring the LSP4J piped-streams setup used by PR 1's JsonRpcTransportTest.java.

Existing unit tests: pass (npm run compile, npm run lint:eslint — 0 errors, only pre-existing no-explicit-any warnings unrelated to this PR).

What is intentionally not in this PR

• proto/gradle.proto still defines service Gradle { … } — unused after this PR, removed in PR 3.
• The root build.gradle's grpcVersion, grpc-protobuf-lite, etc. — still referenced by the Java module post-PR 1 cleanup (the Java side keeps the proto message classes generated). Final removal in PR 3.

Risk log

Risk	Mitigation
vscode-jsonrpc major-version mismatch with the one vscode-languageclient already resolves	Pinned to ^6.0.0 matching the resolved transitive; npm dedups to a single instance.
Loopback listener never gets an inbound connect (JVM crashes early)	30 s connect timeout; the existing JVM-process-exit handler in GradleServer.ts continues to handle the failure path.
Removing retryOnSpuriousCancel re-surfaces a transient cancel	The retry only ever masked a Node.js HTTP/2 race that does not exist over plain TCP. PR 1's TaskSocketServer uses a single non-multiplexed TCP socket.

Closes #1815 once PR 1 + PR 2 land together (default branch behavior change ships only after both are merged).

[Copilot]

Pull request overview

This PR migrates the extension-side Gradle task transport from gRPC to JSON-RPC over a TCP loopback listener, matching the Java-side transport cut-over and removing the gRPC client/stub path.

Changes:

• Adds a new transport/jsonrpc package with loopback listener setup, proto/base64 codec, stream ID allocation, JSON-RPC error mapping, and a typed GradleJsonRpcClient.
• Rewires GradleServer, TaskServerClient, and terminal error handling to use the JSON-RPC connection instead of gRPC.
• Removes gRPC code generation/dependencies and deletes the spurious-cancel retry helper/tests.

Reviewed changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
extension/src/transport/jsonrpc/types.ts	Defines JSON-RPC wire DTO shapes.
extension/src/transport/jsonrpc/streamId.ts	Adds stream ID allocation for multiplexed streaming RPCs.
extension/src/transport/jsonrpc/protoCodec.ts	Adds base64 encoding/decoding for protobuf payloads.
extension/src/transport/jsonrpc/loopbackServer.ts	Adds loopback TCP listener for JVM callback connection.
extension/src/transport/jsonrpc/JsonRpcErrors.ts	Adds JSON-RPC error constants and conversion helpers.
extension/src/transport/jsonrpc/index.ts	Exports the new transport package API.
extension/src/transport/jsonrpc/GradleJsonRpcClient.ts	Implements typed JSON-RPC facade for Gradle task operations.
extension/src/test/unit/transport/loopbackServer.test.ts	Tests listener binding, connection resolution, and logger forwarding.
extension/src/test/unit/transport/GradleJsonRpcClient.test.ts	Tests codec, unary RPCs, streaming dispatch, multiplexing, and error translation.
extension/src/test/unit/retryOnSpuriousCancel.test.ts	Removes tests for deleted gRPC retry helper.
extension/src/terminal/GradleRunnerTerminal.ts	Updates task terminal error handling to JSON-RPC errors.
extension/src/server/GradleServer.ts	Creates the loopback listener before spawning the JVM and exposes the accepted connection.
extension/src/Extension.ts	Replaces gRPC client logger wiring with JSON-RPC transport logger wiring.
extension/src/client/TaskServerClient.ts	Rewrites task client calls from gRPC stubs/streams to GradleJsonRpcClient.
extension/src/client/retryOnSpuriousCancel.ts	Deletes the gRPC-specific retry helper.
extension/package.json	Removes gRPC dev dependencies and adds direct vscode-jsonrpc dependency.
extension/package-lock.json	Updates dependency lockfile for gRPC removal and JSON-RPC direct dependency.
extension/build.gradle	Removes gRPC service stub generation while preserving protobuf message generation.

Files not reviewed (1)

• extension/package-lock.json: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.