# flare.grpc

> A module of flare_mlake's API.

``flare.grpc`` — gRPC primitives on top of the HTTP/2 reactor.

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).