# flare.grpc.server_stream

> A module of flare_mlake's API.

``flare.grpc.server_stream`` -- server-streaming gRPC adapter.

A server-streaming call maps onto a single HTTP/2 stream that
carries *one* request message and *zero or more* response
messages before the trailing HEADERS:

* Request HEADERS + a single request LPM frame (same shape as a
  unary call -- see :mod:`flare.grpc.server`).
* Response HEADERS: ``:status=200``, ``content-type:
  application/grpc``, optional ``grpc-encoding``.
* Response DATA: one back-to-back LPM frame per yielded message.
* Response trailing HEADERS: ``grpc-status`` (REQUIRED), optional
  ``grpc-message`` + trailing metadata.

The wire shape of N response frames inside one DATA stream is
exactly N LPM frames concatenated, so this adapter reuses the
unary :func:`flare.grpc.server.encode_unary_response` per message
and the unary :func:`_response_from_outcome` glue -- the only new
surface is the handler trait (which yields a *list* of messages)
and the per-message encode loop.

This adapter is *buffered* -- the handler returns the
full message list and the adapter encodes them all into one
:class:`Response` body, which the reactor flushes once at
END_STREAM. That means an unbounded / large stream holds every
message in memory before the first byte ships. A streaming-friendly
variant would write each LPM frame onto the live H2 DATA path via
:mod:`flare.http.streaming_server` and only frame the trailers at the
end.

## Structs

### `GrpcServerStreamReply`

```mojo
struct GrpcServerStreamReply
```

Typed return value for a server-streaming gRPC handler.

``messages`` is the ordered list of response bodies the handler
yields; each becomes one LPM frame on the wire. ``status`` is the
final call outcome (OK or a typed error) carried on the trailers,
and ``trailing_metadata`` is the optional application trailer set.

A non-OK status SHOULD ship an empty ``messages`` list -- a stream
that fails mid-way still carries whatever it already yielded plus
the error trailer, but the two factory methods keep the common
"all messages then OK" / "no messages, just an error" shapes
one-liners.

Implements: `Copyable`, `Movable`

Fields:

- `messages: List[List[UInt8]]`
- `status: GrpcStatus`
- `trailing_metadata: GrpcMetadata`
- `compress: Bool`: Whether these messages may be compressed, when the client accepts it.

#### `ok`

```mojo
def ok(var messages: List[List[UInt8]], var trailing_metadata: GrpcMetadata = GrpcMetadata(), compress: Bool = True) -> Self
```

Build an OK server-streaming reply yielding ``messages``.

#### `err`

```mojo
def err(var status: GrpcStatus, var trailing_metadata: GrpcMetadata = GrpcMetadata()) -> Self
```

Build a non-OK reply: no messages, just the error trailer.

### `GrpcStreamingService`

```mojo
struct GrpcStreamingService[H: GrpcServerStreaming & Copyable & Deinitable]
```

Adapt a :class:`GrpcServerStreaming` handler into a plain :trait:`Handler` so it serves over the unified :class:`flare.http.HttpServer` H2 reactor path.

Mount it like any other handler::

    var svc = GrpcStreamingService(TickHandler())
    server.serve(svc)

One H2 stream maps to one server-streaming call: the reactor hands
the assembled :class:`Request` (HEADERS + the single request DATA
frame), the adapter runs :func:`run_server_streaming_call`, and
returns a :class:`Response` whose body carries every response LPM
frame and whose trailers carry ``grpc-status``.

Deadline enforcement mirrors the unary
:class:`flare.grpc.server.GrpcService`: a post-hoc elapsed check
against ``grpc-timeout``. Same ceiling -- a runaway handler runs to
completion before the status flips.

Implements: `Copyable`, `Handler`, `Movable`

Fields:

- `handler: H`

#### `BodyType`

```mojo
comptime BodyType = InlineBody
```

The ``Body`` impl this handler authors its response with.

Defaults to :struct:`InlineBody` so plain handlers that return
``Response`` conform without declaring it. Override in a handler that
returns a typed ``ResponseImpl[SomeBody]``.

#### `serve`

```mojo
def serve(self, req: Request) -> Response
```

## Traits

### `GrpcServerStreaming`

```mojo
undefined
```

Server-streaming gRPC handler.

The handler receives the decoded request bytes (LPM-stitched +
decompressed, exactly like a unary handler) and returns a
:class:`GrpcServerStreamReply` carrying the ordered list of
response messages + the final status + trailing metadata.

Implements: `Movable`

#### `serve_server_streaming`

```mojo
def serve_server_streaming(mut self, ctx: GrpcCallContext, request_bytes: Span[UInt8]) -> GrpcServerStreamReply
```

## Functions

### `run_server_streaming_call`

```mojo
def run_server_streaming_call[H: GrpcServerStreaming](mut handler: H, headers: GrpcRequestHeaders, request_data: Span[UInt8]) -> GrpcCallOutcome
```

End-to-end (buffered) driver for a server-streaming call.

Same failure folding as :func:`flare.grpc.server.run_unary_call`.
The OK path encodes every yielded message into one response body.
The reactor-mounted service prefers the incremental path
(:func:`_streaming_response_from_reply`); this buffered outcome
remains for direct/unit-test use.