Road to grpc.v 1.0: call semantics, hardening, conformance, API freeze

[hunterjsb]

Road to grpc.v 1.0 — stability + real-world exposure for the scoped surface, mirroring the protobuf.v roadmap.

Scope of 1.0

Unary gRPC client + Connect unary server, declared stable. Proven today against live grpc-go and connect-go.

Post-1.0, upstream-gated (V stdlib needs HTTP/2 trailer send + h2c): native gRPC server, and streaming (client/server/bidi). Documented as roadmap, not a wart.

Tandem with protobuf.v (structural, not incidental)

The generated gRPC glue (<Svc>Client/Handler/dispatch) is emitted by protobuf.v's gen/grpc.v, and protobuf.v is now 1.0 / SemVer-frozen. So:

• New call-shapes (deadlines, metadata) are protobuf.v codegen changes → additive → protobuf.v minor bumps (1.1, 1.2…), never breaking the frozen message API.
• Hardening/conformance will surface protobuf.v runtime bugs → 1.0.x patches (as the protobuf conformance gate did).
• Discipline: every protobuf.v touch stays backward-compatible, ships tested + released on its own, then grpc.v regenerates its checked-in stubs; both CIs green each step. The generated-stub shape is a shared contract — designed in Gate 1, frozen on both sides in Gate 4.

Gates

Gate 1 — Unary call semantics (both repos)

• grpc.v: grpc-timeout header + client-side deadline/cancellation
• grpc.v: surface response metadata/trailers to the caller (today only Client.metadata goes in)
• grpc.v: decide gzip compression (likely accept-not-require)
• protobuf.v gen/grpc.v: generated client methods take call options (deadline + per-call metadata) and return response metadata — additive (bare form preserved). Ships protobuf.v 1.1.0.
• Done: deadlines + metadata proven end-to-end vs grpc-go/connect-go; stub shape reviewed as the freeze candidate.

Gate 2 — Robustness & hardening (mostly grpc.v)

• Fuzz/adversarial the frame parser + Connect server: truncated/oversized/compressed frames, bad content-types, malformed grpc-status/grpc-timeout, half-closed conns, concurrent calls, cleanup
• Checked-in fuzz/robustness suite in CI; no crash/hang on hostile input
• Any decode/protojson bug found → protobuf.v 1.0.x patch, regen, re-green

Gate 3 — Conformance & interop breadth (mostly grpc.v)

• Run ConnectServer against the official connectconformance suite; reproducible conformance/ harness + failure-list (same pattern as protobuf.v)
• Broaden interop: client vs connect-go (not just grpc-go), all status codes, deadlines end-to-end, large + unicode + binary payloads
• Done: connectconformance passing (documented non-goals only), matrix in CI

Gate 4 — API freeze + CHANGELOG (both repos, together)

• Freeze grpc.v (Client, ConnectServer, StatusError, frame, status) and the generated-stub shape in protobuf.v gen/grpc.v
• CHANGELOG + scope/limitations doc; SemVer; cut grpc.v v1.0.0 (paired with the required protobuf.v minor)

Sequencing

1 → 2 → 3 → 4. The protobuf.v codegen change is front-loaded into Gate 1 (design the call-options shape early; Gate 4 freezes it). Gates 2–3 are mostly grpc.v with opportunistic protobuf.v patch releases.

[hunterjsb]

Gate 1 — client side landed ✅ (both CIs green)

Unary call semantics, client side, via functional options (the Go-gRPC idiom):
client.rpc(msg) stays trivial; client.rpc(msg, grpc.timeout(d), grpc.header(k,v)) for control. Every generated stub now returns grpc.Reply[T]{ msg, metadata }.

• Deadlines: grpc-timeout header + client-side enforcement → deadline_exceeded (elapsed-vs-deadline, not string-matched); other transport failures → unavailable.
• Metadata both directions, surfaced on Reply.metadata.
• Proven e2e vs grpc-go (interop/run.sh): reference server echoes request metadata as response metadata; a short deadline against a slow method returns deadline_exceeded. New call_test for timeout encoding / option composition / metadata filtering / error mapping.

Shipped as protobuf.v v1.1.0 (stub codegen; outside the frozen 1.0 message API) + grpc.v 50d3790.

Remaining in Gate 1

• gzip: deferring to post-1.0 (client rejects compressed responses cleanly, sends uncompressed — spec-valid). Documented non-goal.
• Server-side metadata: the client has first-class metadata; Connect-server handlers do not yet read request / set response metadata. Symmetric next step = a handler context. Tracked here so Gate 1 isn't one-sided.

[hunterjsb]

Gate 2 — robustness & hardening landed ✅ (both CIs green)

Checked-in fuzz/robustness suite; no crash/hang on hostile input.

• frame_fuzz_test: 50k random + adversarial buffers through the frame decoder — no panic/over-alloc, byte-exact roundtrips; proven it never allocates on an unfulfilled length prefix.
• server_test: non-StatusError handler failure → internal 500, missing content-type → 415, explicit identity encoding allowed, query-string stripped from the routed path.
• registry_test: 8k fuzzed proto+JSON bodies through a real generated recursive dispatch, clean.

The fuzzing found a real vuln: a bare-scalar/empty JSON body drove V's json2 past EOF and panicked in its error formatter — a remote DoS via the Connect JSON codec. Fixed in protobuf.v v1.1.1 (json_precheck validates bare scalars before json2); protoc/protojson oracle still byte-identical. Exactly the protobuf.v-patch-surfaced-by-grpc.v-hardening tandem this roadmap anticipated.

Next: Gate 3 — conformance (official connectconformance suite) + interop breadth.

[quaesitor-scientiam]

http/3 will be ready soon