16.3 gRPC and protobuf

import proto "payments.proto" generates an extern service and types; calls are as to ordinary services through connect.
oxl export --proto emits .proto for the services and types of the package per §9.3; oxl export --openapi — a description of the HTTP/JSON gateway.
The HTTP/JSON gateway: POST /api/<Service>/<rpc> with a body of application/json calls a unary rpc of a pub(api) service (not @internal); the body is an object of parameters (canonical protobuf JSON; a missing parameter without a default is a 400 error), the response is {"result": value}, an error is {code, status, message, details}; the HTTP code corresponds to the gRPC code (OK 200, INVALID_ARGUMENT and FAILED_PRECONDITION 400, UNAUTHENTICATED 401, PERMISSION_DENIED 403, NOT_FOUND 404, ALREADY_EXISTS and ABORTED 409, RESOURCE_EXHAUSTED 429, UNAVAILABLE 503, DEADLINE_EXCEEDED 504, …). Authentication, policies, idempotency and deadlines are as for a gRPC call (D-8065; D-8210..D-8213, D-8218).

Implementation-defined. Limits of the gateway (D-8065; DIV-026; D-8210, D-8241). This implementation: the gateway works on the port of the gRPC listener (HTTP/2, h2c or TLS; HTTP/1.1 is not served on this port); streaming rpcs are not served by the gateway (501); GET for @readonly rpcs and NDJSON for server streams, as well as oxl export --openapi (a description of the gateway), are optional features not implemented in 1.0.

oxl gen --ts --py --go --kotlin --cpp generates clients with typed errors and checking of refined types.

Implementation-defined. Client generators (D-8056; DIV-034; D-4756). The set of target languages of oxl gen and the completeness of the clients are implementation-defined (the set is shown by oxl gen --help). This implementation generates clients for Python, TypeScript, Go and Kotlin (the Kotlin output is verified against golden files and structure but has not been compiled); C++ clients are not generated (--cpp, after 1.0); default values of rpc parameters are not generated in clients; @resumable is ignored by the generator.

On proto import: option idempotency_level = IDEMPOTENT is mapped to @idempotent, NO_SIDE_EFFECTS to @readonly; messages with the option (oxl.error) = true become @error types. The client of an external service is Client<S>, usually obtained through provide and dep.

import-skip

16.3 gRPC and protobuf

Related diagnostics

See also