flare.grpc.server

Typed carrier for the H2 request-HEADERS field set the gRPC adapter consumes.

The method / path / content_type / te fields are REQUIRED on every well-formed gRPC call; the optional fields (timeout -- grpc-timeout, accept_encoding -- grpc-accept-encoding) carry the empty :class:Optional when the client omits them. initial_metadata is the application-visible subset (grpc- reserved keys stripped).

The H2 driver builds this carrier from the parsed H2RequestHeaders field set and hands it to :func:parse_request_headers or :func:run_unary_call. The typed shape collapses the prior seven-positional-string signature into a single argument and lets the driver build each field with the right Optional[String] semantics.

View of the per-call HTTP/2 request state visible to the application handler.

The path field is the gRPC method name (/svc/method); the deadline is the absolute microsecond timestamp at which the server should abandon the call (0 means "no deadline specified"). Initial metadata is the application-visible subset of the request HEADERS (grpc- reserved keys are stripped before the handler sees them).

Typed return value for a unary gRPC handler.

Replaces the prior Tuple[List[UInt8], GrpcStatus, GrpcMetadata] so a handler's call site reads as return GrpcUnaryReply.ok(body) or return GrpcUnaryReply.err(GrpcStatus.err(...)) instead of a positional 3-tuple. The :func:run_unary_call driver always emits an empty response body for non-OK replies; body is ignored in that case (the spec carries the status on the trailers, not the payload).

The two factory methods (:func:ok and :func:err) handle the metadata-default ergonomics so a handler that does not attach trailing metadata can omit the argument.

Output of one full unary call -- the bytes the H2 driver queues onto the response stream.

• response_data is the encoded LPM frame for the response body (empty on non-OK status; the trailers carry the status).
• status is the gRPC status code the trailer must carry.
• trailing_metadata is the trailing HEADERS field set excluding grpc-status / grpc-message (those are framework-managed; see :func:emit_trailing_headers).

Adapt a :class:GrpcUnary handler into a plain :trait:Handler so it serves over the unified :class:flare.http.HttpServer H2 reactor path -- no bespoke per-RPC glue.

Mount it like any other handler::

var svc = GrpcService(EchoHandler())
var server = HttpServer.bind(addr)
server.serve(svc)   # over h2c / h2

One H2 stream maps to one unary call: the reactor hands this adapter the assembled :class:Request (HEADERS + DATA), the adapter runs :func:run_unary_call, and returns a :class:Response whose trailers carry grpc-status. The inner handler is copied per call (H: Copyable) so the immutable serve borrow holds while serve_unary mutates its own copy -- unary handlers are config- only in practice, so the copy is cheap.

Deadlines: when the client sends grpc-timeout the adapter enforces it as a wall-clock ceiling on the handler invocation and returns DEADLINE_EXCEEDED if the handler overruns.

Deadline enforcement is a post-hoc elapsed check, not a cooperative mid-call cancel (the handler runs to completion, then we compare elapsed vs budget), so a runaway handler still burns its full time before the status flips. Cancelling it promptly would need a :class:flare.http.Cancel threaded into a cancel-aware GrpcUnary variant and flipped from a deadline timer.

Single-method gRPC handler.

The handler receives the decoded request bytes (already LPM-stitched + decompressed) and returns a typed :class:GrpcUnaryReply carrying the response body + status + trailing metadata. Returning a non-OK reply causes the adapter to emit an empty response body + the trailers; the response bytes are ignored in that case.

Canonical gRPC content-type. The adapter also accepts the flavored variants application/grpc+proto / +json / +thrift -- any string starting with this prefix and an optional +<flavor> segment.

Response payloads at or above this size are eligible for message-level compression when the client advertises a codec via grpc-accept-encoding. Below it the gzip/deflate header overhead outweighs the saving, so the frame ships uncompressed (flag 0). This is a fixed cutoff, not an adaptive ratio probe.