`flare.grpc.status`

gRPC status codes and trailer carrier.

A gRPC call ends with a trailer header set containing at least grpc-status (a decimal integer 0..16). Successful calls return grpc-status: 0 (OK); failed calls return a non-zero code plus an optional grpc-message (a Percent-Encoded UTF-8 human description, capped at a few KiB by most clients).

This module defines the 16 standard status code constants and a small :class:GrpcStatus carrier callers can pass through their handler chain. The actual trailer-emitting code lives in the HTTP/2 server adapter (a later commit); this module is purely the data model.

References:

Structs

`GrpcStatus`

struct GrpcStatus

An RPC outcome: numeric code + optional human message + optional binary detail.

Status codes are stable across implementations -- a Mojo handler returning GRPC_STATUS_NOT_FOUND will surface as the same code in a Go / Python / C++ client. The optional message carries free-text context for diagnostics; it must not be used for branching by the client.

details carries the optional grpc-status-details-bin payload (RFC 4648 §4 base64 on the wire; opaque bytes here so the application can attach a serialised google.rpc.Status proto, a typed error envelope, or any other binary frame the client knows how to parse).

Implements Copyable, Movable

Fields: code: Int; message: String; details: Optional[List[UInt8]]

comptime OK = Int(0)

comptime CANCELLED = Int(1)

comptime UNKNOWN = Int(2)

comptime INVALID_ARGUMENT = Int(3)

comptime DEADLINE_EXCEEDED = Int(4)

comptime NOT_FOUND = Int(5)

comptime ALREADY_EXISTS = Int(6)

comptime PERMISSION_DENIED = Int(7)

comptime RESOURCE_EXHAUSTED = Int(8)

comptime FAILED_PRECONDITION = Int(9)

comptime ABORTED = Int(10)

comptime OUT_OF_RANGE = Int(11)

comptime UNIMPLEMENTED = Int(12)

comptime INTERNAL = Int(13)

comptime UNAVAILABLE = Int(14)

comptime DATA_LOSS = Int(15)

comptime UNAUTHENTICATED = Int(16)

`ok`

def ok() -> Self

`err`

def err(code: Int, message: String) -> Self

`with_details`

def with_details(self, var details: List[UInt8]) -> Self

Return a copy of this status with the grpc-status- details-bin payload attached. The caller owns the bytes; the trailer emitter base64-encodes them when serialising the trailing HEADERS field set.

`is_ok`

def is_ok(self) -> Bool

`name`

def name(self) -> String

Return the canonical short name for the status code. Unknown numeric codes (outside 0..16) return "UNKNOWN_CODE_<n>" so logs always have something to grep for.

Functions

`grpc_message_encode`

def grpc_message_encode(message: String) -> String

Percent-encode message for the grpc-message field.

gRPC's PROTOCOL-HTTP2 carries the message as percent-encoded UTF-8: every byte outside 0x20..0x7E, and % itself, becomes %XX. Sent raw, a non-ASCII message reached clients as mojibake and a CR or LF in it was a field-injection vector on any transport that did not reject it.

`grpc_message_decode`

def grpc_message_decode(value: String) -> String

Undo :func:grpc_message_encode on a received grpc-message.

The spec asks a receiver not to fail on a malformed value, so a % not followed by two hex digits is kept as it is, and bytes that do not decode to valid UTF-8 are replaced, not raised on.

Aliases

comptime GRPC_STATUS_OK = GrpcStatus.OK

comptime GRPC_STATUS_CANCELLED = GrpcStatus.CANCELLED

comptime GRPC_STATUS_UNKNOWN = GrpcStatus.UNKNOWN

comptime GRPC_STATUS_INVALID_ARGUMENT = GrpcStatus.INVALID_ARGUMENT

comptime GRPC_STATUS_DEADLINE_EXCEEDED = GrpcStatus.DEADLINE_EXCEEDED

comptime GRPC_STATUS_NOT_FOUND = GrpcStatus.NOT_FOUND

comptime GRPC_STATUS_ALREADY_EXISTS = GrpcStatus.ALREADY_EXISTS

comptime GRPC_STATUS_PERMISSION_DENIED = GrpcStatus.PERMISSION_DENIED

comptime GRPC_STATUS_RESOURCE_EXHAUSTED = GrpcStatus.RESOURCE_EXHAUSTED

comptime GRPC_STATUS_FAILED_PRECONDITION = GrpcStatus.FAILED_PRECONDITION

comptime GRPC_STATUS_ABORTED = GrpcStatus.ABORTED

comptime GRPC_STATUS_OUT_OF_RANGE = GrpcStatus.OUT_OF_RANGE

comptime GRPC_STATUS_UNIMPLEMENTED = GrpcStatus.UNIMPLEMENTED

comptime GRPC_STATUS_INTERNAL = GrpcStatus.INTERNAL

comptime GRPC_STATUS_UNAVAILABLE = GrpcStatus.UNAVAILABLE

comptime GRPC_STATUS_DATA_LOSS = GrpcStatus.DATA_LOSS

comptime GRPC_STATUS_UNAUTHENTICATED = GrpcStatus.UNAUTHENTICATED