flare.grpc

gRPC is a 4-layer protocol on top of HTTP/2:

1. Length-Prefix-Message (LPM) framing -- every gRPC message on the wire is a 1-byte compression flag + a 4-byte big-endian length + the payload bytes. This module ships that codec in :mod:flare.grpc.framing.
2. Status + Metadata -- the trailer grpc-status, grpc-message, and trailing-metadata header set. Carried in :mod:flare.grpc.status.
3. Call shapes -- unary (this module, via the :mod:flare.grpc.server adapter), and server-streaming / client-streaming / bidirectional (the client side, via :mod:flare.grpc.streaming). Each maps onto a single HTTP/2 stream (request HEADERS + DATA frames carry length-prefixed messages, response HEADERS + DATA + trailing HEADERS carry the reply).
4. Codegen -- proto3 message serialization. The :mod:flare.grpc.proto codec (ProtoWriter / ProtoReader) is the runtime that hand-written message structs and generated code target; a full .proto file compiler is tracked separately.

This module establishes layers 1, 2 and the unary path of layer 3. The HTTP/2 reactor already provides the stream multiplexer the call shapes need; the server adapter mounts on the existing :class:Handler trait via :class:GrpcUnary.

Public re-exports:

• :class:GrpcCompressionFlag -- the LPM frame's flag byte.
• :class:GrpcMessage -- decoded LPM frame (flag + payload).
• :func:encode_grpc_message / :func:decode_grpc_message -- the byte-level codec.
• :class:GrpcStatus + the named status code constants -- trailer carrier + RPC outcome.
• :class:GrpcMetadata, :class:GrpcMetadataEntry -- the initial- and trailing-metadata carrier.
• :class:GrpcUnary -- the per-method handler trait the application implements; receives a decoded request payload and returns either response bytes or a non-OK status.
• :class:GrpcService -- adapts a :class:GrpcUnary handler into a plain :trait:flare.http.Handler so it serves over the unified :class:flare.http.HttpServer H2 reactor with no bespoke glue; carries grpc-status in HTTP/2 trailers and enforces grpc-timeout deadlines.
• :class:GrpcRequestHeaders -- typed carrier for the H2 request-HEADERS field set; Optional[String] covers grpc-timeout / grpc-accept-encoding.
• :class:GrpcCallContext, :class:GrpcCallOutcome -- the per-call inputs and outputs the server adapter threads through the H2 stream.
• :class:GrpcUnaryReply -- typed handler return value with :func:GrpcUnaryReply.ok / :func:GrpcUnaryReply.err factories that fill in the status + default metadata.
• :class:GrpcServerStream, :class:GrpcBidiStream -- the client-side streaming RPC handles returned by :meth:GrpcClient.call_server_streaming / :meth:GrpcClient.call_client_streaming / :meth:GrpcClient.call_bidi; pull reply messages incrementally with recv() and read the final status().
• :func:parse_request_headers, :func:stitch_request_data, :func:encode_unary_response, :func:run_unary_call -- the sans-I/O building blocks of the unary server adapter (H2 headers + DATA → GrpcCallContext → handler → LPM-wrapped response bytes + outcome).