[EXPERIMENTAL][ADR-044] feat(grpc-uds): pure tonic handlers — eliminate Axum dispatch overhead

[gandhipratik203]

Summary

Closes #3730

Experiment to explore the ideas in ADR-044 using a pure tonic dispatch strategy — companion to #3726 which takes the Axum dispatch approach. Together these two PRs represent two different ways of implementing the same gRPC-over-UDS boundary.

This PR's approach:

• McpRuntimeService holds AppState directly and calls rpc_inner, transport_get_inner, transport_delete_inner without re-encoding to HTTP
• Removes the proto→http::Request→Tower/Axum→http::Response→proto round-trip from every RPC call
• Removes explicit tower optional dependency (was redundant via tonic's transitive dep)

ADR-044 Goals — What This Experiment Covers

Click to see which goals this implementation demonstrates, which are partial, and which remain future work.

ADR-044 goal coverage for this approach (pure tonic dispatch)

✅ Demonstrated

Typed contract via protobuf
The .proto file is the single source of truth. Python and Rust both generate stubs from it. If a field is added or a method renamed, both sides fail to compile before anything ships. The HTTP/JSON IPC boundary had no schema — a wrong header name would silently do nothing.

Language-neutral boundary
The McpRuntime proto contract does not care what is on either side. A Go module, a Java module, or a second Rust service could plug into the same contract today without any changes to the Python gateway. The HTTP/JSON IPC was Python-to-Rust only and relied on undocumented internal headers.

Native streaming RPCs
InvokeStream is a proper gRPC server-streaming RPC — not HTTP chunked encoding over a socket. The Python side gets an async iterator, the Rust side yields chunks. Backpressure, framing, and cancellation are handled correctly by construction.

Unix Domain Socket — no TCP overhead
All traffic stays in kernel memory. No TCP handshake, no loopback routing, no port allocation. HTTP/2 multiplexing means multiple concurrent RPCs share one connection rather than opening new connections per request.

Clean process boundary — crash isolation
If the Rust sidecar panics, Python keeps running and the gRPC channel reconnects. The proto contract is the explicit, versioned API surface — not an internal HTTP path that could drift silently.

Aligns with the existing plugin gRPC pattern
The external plugin framework in mcpgateway/plugins/framework/external/grpc/ already uses gRPC. The MCP runtime boundary now uses the same pattern — one mental model for module boundaries across the platform.

---

⚠️ Partially demonstrated

Independent scaling of modules
The process boundary exists — Rust is a separate binary on a separate socket. But in the current container setup they are co-located. The groundwork is there; exploiting it requires running the sidecar as a separate container or pod.

Structured auth context propagation
The AuthContext proto message is a better contract than the x-contextforge-auth-context header string used in HTTP/JSON IPC. The current implementation encodes it as base64 JSON inside the proto field — which works, but does not yet use the proto's ability to carry it as proper typed fields.

---

❌ Not yet demonstrated

Catalog change subscriptions and session broadcast
ADR-044 specifically calls out streaming RPCs for catalog change notifications and session broadcast patterns. InvokeStream currently handles only SSE relay. The push patterns the ADR envisioned are not implemented.

Multi-language beyond Python and Rust
The value of language-neutral codegen becomes concrete when a third language plugs into the same contract. Right now it is two languages that could have communicated over HTTP just fine. The payoff is visible only when a Go or Java module joins.

Approach difference vs #3726

	#3726 (Axum dispatch)	This PR (pure tonic)
McpRuntimeService holds	Router	AppState
Hot path	proto → http::Request → Tower oneshot → Axum → http::Response → proto	proto → HeaderMap + Uri + Bytes → rpc_inner() → proto
proto_to_http_request	exists	removed
router.clone() per call	yes	gone
Tower dispatch	yes	gone

Benchmark (125 users / 60s, same config as #3726)

Metric	Python	HTTP/JSON IPC	gRPC-UDS #3726 (Axum dispatch)	gRPC-UDS this PR (pure tonic)
RPS	512	1,930	1,690	1,778
Avg latency	167ms	2.84ms	11.51ms	8.71ms
p99	610ms	11ms	79ms	37ms
Failures	24	0 ✅	0 ✅	0 ✅

+88 RPS and p99 halved (79ms → 37ms) vs the Axum dispatch approach. HTTP/JSON IPC still leads because Axum speaks HTTP natively — the irreducible cost here is protobuf serialization on both sides of the socket, which is unavoidable in gRPC.

Why HTTP/JSON IPC still leads

The remaining gap is structural to gRPC — protobuf serialization on Python ingress and Rust egress is unavoidable. The value of this transport is the typed contract, language-neutral codegen, and native streaming RPC — not raw single-request throughput. ADR-044 explicitly acknowledges this trade-off.

Flow diagrams: HTTP/JSON IPC vs gRPC-UDS pure tonic

---

HTTP/JSON IPC

Python gateway                  Unix socket              Rust sidecar
─────────────────────────────────────────────────────────────────────

  [incoming MCP request]
        │
        │  Build HTTP request
        │  (headers already exist,
        │   body already bytes)
        │
        ▼
  ┌─────────────┐
  │  httpx      │ ──── raw HTTP bytes ──────────────────► Axum router
  │  AsyncClient│                                              │
  └─────────────┘                                              │
                                                         (Axum speaks
                                                          HTTP natively,
        ◄──────────── raw HTTP response bytes ───────────  no conversion)
        │
  [send response to client]

---

gRPC-UDS IPC (pure tonic — this PR)

Python gateway                  Unix socket              Rust sidecar
─────────────────────────────────────────────────────────────────────

  [incoming MCP request]
        │
        │  1. Serialize to protobuf          ← still needed
        │     (headers map, body bytes,
        │      auth context, session id...)
        │
        ▼
  ┌─────────────┐
  │  grpc.aio   │ ──── protobuf bytes ──────────────────► tonic server
  │  stub       │                                              │
  └─────────────┘                                    2. Deserialize protobuf
                                                        into HeaderMap
                                                        + Uri + Bytes
                                                              │
                                                              │  ← no http::Request
                                                              │  ← no Tower dispatch
                                                              │  ← no router.clone()
                                                              │
                                                              ▼
                                                         rpc_inner()
                                                         directly
                                                              │
                                                     3. Serialize response
                                                        headers + body
                                                        to protobuf
                                                              │
        ◄──────────────── protobuf bytes ─────────────────────
        │
  4. Deserialize protobuf                             ← still needed
        │
  [send response to client]

Old gRPC path had 6 steps with overhead. This has 4. Removed: http::Request construction, Tower oneshot dispatch, router.clone() per call.