Skip to content

Sidecar: add gRPC as a third transport alongside stdio and HTTP #611

Description

@thomas-stegemann

Context

Sidecars speak JSON-RPC 2.0 over two transports today: stdio (NDJSON) and
http (POST + SSE). That choice is recorded in
ADR-0001
and stands — the entry barrier for plugin authors is the reason it was made,
and stdio remains the right default.

Two things argue for widening the choice, recorded in
ADR-0002:

  • gRPC is now the default RPC stack in most sidecar languages — first-class
    in Go, mature in Rust (tonic) and Python (grpcio), and @grpc/grpc-js has
    been pure JavaScript with no native build for years.
  • The streaming gap was never closed. Bowire's protocols stream heavily, but
    JSON-RPC has no stream concept, so the host rebuilds one from notifications
    ($/stream/data, $/channel/data) plus SidecarSubscriptionHub — with no
    flow control and no backpressure. ADR-0001's own "use a native .NET plugin
    above ~10k msgs/sec" is that gap stated as a limit.

Scope

Add gRPC as a third ISidecarTransport, selected by "transport": "grpc"
in sidecar.json. JSON-RPC over stdio stays the default — this is
additive, nothing existing changes behaviour.

The host side is cheap: ISidecarTransport already has two implementations
(SidecarJsonRpcTransport, SidecarHttpTransport) and the manifest already
carries a transport field. The cost is in the SDKs.

Blocked by #418

The four language SDKs are already behind the current contract. Adding a
second transport family to SDKs that have not caught up with the first
multiplies a debt that is already due. #418 lands first — this issue should
not start before it closes.

Tasks

  • Proto definition for the sidecar contract (mirrors the JSON-RPC method surface)
  • SidecarGrpcTransport : ISidecarTransport in the host
  • "grpc" accepted in SidecarPluginManifest, discovery guard updated (cf. Sidecar discovery drops HTTP-transport plugins (guard requires executable) #415, which fixed the same class of bug for http)
  • Streaming mapped onto native bidirectional streams rather than notification emulation — this is the whole point of the exercise
  • SDK support per language, opt-in entry point (run_grpc() alongside run() / run_http()), so a plugin's BowirePlugin implementation is untouched
  • Document in docs/architecture/sidecar-plugins.md when it ships, not before; flip ADR-0002 to Accepted
  • Guidance on choosing a transport: stdio by default, http for hosted, grpc for streaming-heavy

Non-goals

  • Replacing JSON-RPC. Rejected in ADR-0002: it breaks every existing sidecar and
    discards the property that a sidecar can be written in anything emitting JSON
    lines — a shell script, an exotic language, a prototype.
  • Making gRPC the default.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    • Status
      Backlog

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions