# flare.grpc.health

> A module of flare_mlake's API.

``flare.grpc.health`` -- the standard ``grpc.health.v1.Health`` service (Check), implemented as a :trait:`GrpcUnary` handler.

Wire schema (grpc/health/v1/health.proto):

    message HealthCheckRequest  { string service = 1; }
    message HealthCheckResponse { ServingStatus status = 1; }
    enum ServingStatus {
        UNKNOWN = 0; SERVING = 1; NOT_SERVING = 2; SERVICE_UNKNOWN = 3;
    }

``Check`` returns the registered status for the requested service name
(the empty name ``""`` is the conventional "overall server" key). An
unregistered name yields ``SERVICE_UNKNOWN`` per the spec.

Mount it like any unary service (typically behind a router that
dispatches ``/grpc.health.v1.Health/Check`` to this handler)::

    var health = HealthService()
    health.set_status("", HEALTH_SERVING)
    var svc = GrpcService(health)

The streaming ``Watch`` method (:class:`HealthWatchHandler`) is a
server-streaming RPC that replays the current status plus each recorded
status change; mount it via ``GrpcStreamingService(HealthWatchHandler(
health))``.

## Structs

### `HealthService`

```mojo
struct HealthService
```

In-memory ``grpc.health.v1.Health`` Check handler.

Holds a per-service status map; ``set_status`` registers / updates a
service's serving status. An unregistered service name returns
``SERVICE_UNKNOWN``.

Implements: `Copyable`, `GrpcUnary`, `Movable`

Fields:

- `statuses: Dict[String, Int]`
- `history: Dict[String, List[Int]]`: Per-service ordered status-transition log. Every ``set_status`` appends here so :class:`HealthWatchHandler` can replay the current status plus each subsequent change as a Watch stream.

#### `__init__`

```mojo
def __init__(out self)
```

#### `set_status`

```mojo
def set_status(mut self, service: String, status: Int)
```

Register / update ``service``'s serving status. Use the empty name ``""`` for overall server health. Each call records a transition in :attr:`history` for Watch.

#### `status_of`

```mojo
def status_of(self, service: String) -> Int
```

Current serving status for ``service`` (SERVICE_UNKNOWN if never registered).

#### `serve_unary`

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

### `HealthWatchHandler`

```mojo
struct HealthWatchHandler
```

The streaming ``grpc.health.v1.Health/Watch`` RPC.

Watch is a server-streaming RPC: the client sends one
``HealthCheckRequest`` and receives a ``HealthCheckResponse`` for the
current status plus one for every subsequent status change. This
handler replays the recorded transition log (:attr:`HealthService.
history`) as the response stream, framing each transition as its own
DATA frame over the incremental H2 path.

ponytail: the stream terminates after replaying the recorded
transitions rather than staying open forever pushing live changes --
an unbounded live Watch needs a shared cross-connection notify
channel + an async chunk source. Replaying the transition log gives
real status-change delivery within one buffered snapshot; the
upgrade path is a poll/notify AsyncChunkSource.

Implements: `Copyable`, `GrpcServerStreaming`, `Movable`

Fields:

- `health: HealthService`

#### `__init__`

```mojo
def __init__(out self, var health: HealthService)
```

#### `copy`

```mojo
def copy(self) -> Self
```

#### `serve_server_streaming`

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

## Functions

### `decode_health_request`

```mojo
def decode_health_request(payload: Span[UInt8]) -> String
```

Decode a ``HealthCheckRequest`` -> the requested service name (field 1, string). Missing field 1 decodes to the empty name.

### `encode_health_response`

```mojo
def encode_health_response(status: Int) -> List[UInt8]
```

Encode a ``HealthCheckResponse`` carrying ``status`` (field 1, enum). proto3 omits the field when the value is the default ``0`` (UNKNOWN).

## Aliases

### `HEALTH_UNKNOWN`

```mojo
comptime HEALTH_UNKNOWN = Int(0)
```

### `HEALTH_SERVING`

```mojo
comptime HEALTH_SERVING = Int(1)
```

### `HEALTH_NOT_SERVING`

```mojo
comptime HEALTH_NOT_SERVING = Int(2)
```

### `HEALTH_SERVICE_UNKNOWN`

```mojo
comptime HEALTH_SERVICE_UNKNOWN = Int(3)
```

``grpc.health.v1.HealthCheckResponse.ServingStatus`` codepoints.