One model across HTTP, OpenAPI and gRPC

Forward validated HTTP JSON through a Cap’n Proto gRPC service and publish the HTTP contract.

The grpc feature used here is source-only and is not included in the published rydantic = “=0.8.0” package. The capnp, axum, and openapi features are available in 0.8.0.

Run the bridge

Install the official Cap’n Proto compiler, then run the combined example from a source checkout:

cargo run —locked -p rydantic —example protocol_bridge —features “grpc axum openapi”

The example starts a local Tonic backend and an Axum HTTP gateway. It prints the HTTP address and serves:

• POST /greet — validates JSON into the shared Hello model, encodes it as Cap’n Proto, calls the unary gRPC method, then returns the validated Greeting as JSON.
• GET /openapi.json — returns an OpenAPI 3.1 document with input and output schemas generated from those same models.

The OpenAPI operation includes x-rydantic-grpc-method to record the corresponding Tonic method path. The example explicitly wires the HTTP route, Tonic service and OpenAPI operation.

The request path is:

HTTP JSON → Rydantic validation → Cap’n Proto encoding → Tonic unary gRPC ← JSON response ← Rydantic validation ← Cap’n Proto decoding

Try it using the address printed by the example:

curl -H 'content-type: application/json' \
  -d '{"name":" Alice ","context":{"language":"en"}}' \
  http://127.0.0.1:<printed-port>/greet

curl http://127.0.0.1:<printed-port>/openapi.json

Before contacting the backend, the gateway checks the encoded Cap’n Proto request size against its configured gRPC message limit. Oversized HTTP bodies or encoded requests return 413; request validation or local encoding failures return 422. Backend and response failures remain redacted 502 responses, including a backend’s InvalidArgument status.

The example binds both listeners to loopback and runs until stopped. It has no authentication, TLS, rate limiting or deployment configuration.

Wire contract

The gRPC hop uses the existing CapnpModel wire types and Tonic custom codec. Both peers must use the same service method path, Cap’n Proto root type, field ordinals and field types. This is unary Cap’n Proto serialization over gRPC; standard protobuf clients, .proto generation, reflection, streaming, and native Cap’n Proto RPC are not part of this adapter.

The OpenAPI document describes the HTTP gateway operation. Its vendor extension records the gRPC method mapping; it does not create routes or transcode requests by itself. Other-language gRPC peers need a matching Cap’n Proto codec and service implementation.