Encodes an envelope into caller-owned memory, freed with free(bytes.data).
bytes, failure := frame_message(u8.[1, 2]);
assert(failure == .NONE && bytes.count == 7);
free(bytes.data);#import "Extensions/Grpc";
gRPC identity/gzip message framing, metadata and canonical status codecs, plus native TLS HTTP/2 client/server calls with typed Protobuf message helpers.
A call is a stream of length-prefixed messages ended by a status. The framing, metadata and
status codecs work on every target; open_call, serve_call and the rest need fibers,
Extensions/Io and TLS, and are not built for wasm.
Framing a message and reading it back:
wire, _ := frame_message(u8.[1, 2, 3]);
defer free(wire.data);
decoder: Envelope_Decoder;
defer free_decoder(*decoder);
feed_envelope(*decoder, wire);
message := take_message(*decoder);
defer free(message.data);
assert(message.count == 3);A client call (the channel's transport.tls is a configured Tls.Tls_Config with alpn = ["h2"]):
channel: Channel;
channel.transport.base_url = "https://localhost:50051";
defer close_channel(*channel);
call, status := open_call(*channel, Method.{ path = "/echo.Echo/Say" });
assert(status.code == .OK);
defer close(*call);
send_bytes(*call, u8.[1, 2, 3]);
close_send(*call);
message, kind := receive_bytes(*call);
if kind == .MESSAGE free(message.data);
final := finish(*call);
defer free_status(*final);Encodes an envelope into caller-owned memory, freed with free(bytes.data).
bytes, failure := frame_message(u8.[1, 2]);
assert(failure == .NONE && bytes.count == 7);
free(bytes.data);Consumes at most one message, returning the consumed byte count. Callers keep unconsumed input for the next message. The size limit is checked after the prefix, before reserving payload memory; errors remain sticky until the decoder is freed.
decoder: Envelope_Decoder;
defer free_decoder(*decoder);
used, failure := feed_envelope(*decoder, u8.[0, 0, 0, 0, 0]);
assert(used == 5 && failure == .NONE && decoder.ready);Transfers a complete payload to the caller and starts the next envelope.
Returns empty if no message is ready; inspect ready before calling to
distinguish that case from a legitimate zero-byte message.
if decoder.ready { bytes := take_message(*decoder); defer free(bytes.data); }Validates byte EOF. A partial prefix or payload is an error, even if a prior message was valid. This only validates framing; RPC completion requires status.
decoder: Envelope_Decoder;
assert(finish_envelopes(*decoder) == .NONE);Releases partial or unread payload storage. Safe to call repeatedly.
decoder: Envelope_Decoder;
free_decoder(*decoder);Parses authoritative final status; HTTP mapping applies only when grpc-status is missing or invalid. Repeated status fields are a protocol failure. .
Http :: #import "Extensions/Http";
main :: () {
fields := Http.Header_Field.[
.{ name = "grpc-status", value = "5" },
.{ name = "grpc-message", value = "no%20such%20user" },
];
status := parse_status(fields, 200);
defer free_status(*status);
assert(status.code == .NOT_FOUND && status.message == "no such user");
missing := parse_status(.[], 503); // no grpc-status: the HTTP status decides
defer free_status(*missing);
assert(missing.code == .UNAVAILABLE);
}Releases owned status text and metadata. Safe on a cleared status. .
Http :: #import "Extensions/Http";
main :: () {
fields := Http.Header_Field.[.{ name = "grpc-status", value = "3" }];
status := parse_status(fields, 200);
free_status(*status);
free_status(*status); // safe on a cleared status
}Parses grpc-timeout into milliseconds, rounding fractional milliseconds up. Wire values have at most eight digits, so every supported unit fits s64. .
milliseconds, ok := parse_timeout("1S");
assert(ok && milliseconds == 1000);
rounded, _ := parse_timeout("1500u"); // fractions of a millisecond round up
assert(rounded == 2);
_, invalid := parse_timeout("1x");
assert(!invalid);Maps documented HTTP/2 reset codes. STREAM_CLOSED and unknown codes have no open-call mapping and report UNKNOWN. No code authorizes automatic replay. .
assert(http2_reset_status(8) == .CANCELLED);
assert(http2_reset_status(0xffffffff) == .UNKNOWN);Application metadata uses lowercase protocol names; grpc-* names are reserved. .
assert(valid_metadata_name("trace-bin"));
assert(!valid_metadata_name("grpc-status")); // grpc-* is reserved
assert(!valid_metadata_name("Upper"));Encodes application metadata into temporary header storage. Binary values use unpadded Base64; repeated keys retain their order. Fields need no explicit free. .
fields, ok := encode_metadata(Metadata_Entry.[.{ "x-key", "value" }, .{ "x-blob-bin", "\x01\xff" }]);
assert(ok && fields.count == 2);
assert(fields[0].name == "x-key" && fields[1].value == "Af8"); // binary values are Base64Copies application metadata into owned storage. Comma-joined binary values are split before padded/unpadded Base64 decode. Reserved protocol fields are excluded. Release the result with free_metadata, including on an empty result. .
Http :: #import "Extensions/Http";
main :: () {
fields := Http.Header_Field.[
.{ name = "x-key", value = "value" },
.{ name = "grpc-status", value = "0" },
];
entries, ok := decode_metadata(fields);
defer free_metadata(*entries);
assert(ok && entries.count == 1 && entries[0].name == "x-key"); // grpc-* fields are left out
}Releases every entry's owned name/value, then the array; safe repeatedly. .
Http :: #import "Extensions/Http";
main :: () {
fields := Http.Header_Field.[.{ name = "x-key", value = "value" }];
entries, _ := decode_metadata(fields);
free_metadata(*entries);
assert(entries.count == 0);
}Opens an RPC without retry or redirect. The channel and TLS configuration must remain alive until every call and close_channel have completed. .
Sends an owned-by-caller encoded Protobuf message. Framing owns a temporary copy only until this operation returns. One sender may coexist with one receiver. .
channel: Channel; // set transport.base_url and transport.tls before the first call
method := Method.{ path = "/echo.Echo/Say" };
call, status := open_call(*channel, method);
assert(status.code == .OK);
defer close(*call);
status = send_bytes(*call, u8.[10, 3, 65, 100, 97]);
assert(status.code == .OK);Encodes a generated Protobuf value and sends it through the shared framing path. .
Api :: #import "Extensions/Protobuf/Schema"(GRPC = true, TEXT = "syntax='proto3'; package echo; message Say { string text = 1; }");
main :: () {
channel: Channel;
call, status := open_call(*channel, Method.{ path = "/echo.Echo/Say" });
defer close(*call);
status = send(*call, Api.echo.Say.{ text = "hi" });
assert(status.code == .OK);
}Half-closes the client's sending direction. No automatic retry occurs. .
channel: Channel; // set transport.base_url and transport.tls before the first call
method := Method.{ path = "/echo.Echo/Say" };
call, status := open_call(*channel, method);
assert(status.code == .OK);
defer close(*call);
status = close_send(*call); // no more requests
assert(status.code == .OK);Receives one framed message into caller-owned memory. END is a byte-stream event, not application success; always inspect finish's authoritative Status. .
channel: Channel; // set transport.base_url and transport.tls before the first call
method := Method.{ path = "/echo.Echo/Say" };
call, status := open_call(*channel, method);
assert(status.code == .OK);
defer close(*call);
while true {
message, kind := receive_bytes(*call);
if kind != .MESSAGE break;
defer free(message.data);
print("% bytes\n", message.count);
}Decodes into owned Protobuf storage. Release a MESSAGE with Proto.free. .
P :: #import "Extensions/Protobuf";
Api :: #import "Extensions/Protobuf/Schema"(GRPC = true, TEXT = "syntax='proto3'; package echo; message Say { string text = 1; }");
main :: () {
channel: Channel;
call, status := open_call(*channel, Method.{ path = "/echo.Echo/Say" });
defer close(*call);
reply, kind := receive(*call, Api.echo.Say);
if kind == .MESSAGE {
print("%\n", reply.text);
P.free(*reply);
}
}Whether the last MESSAGE received used the negotiated compressed envelope. This describes wire compression, independently of the decoded Protobuf value. .
channel: Channel; // set transport.base_url and transport.tls before the first call
method := Method.{ path = "/echo.Echo/Say" };
call, status := open_call(*channel, method);
assert(status.code == .OK);
defer close(*call);
message, kind := receive_bytes(*call);
if kind == .MESSAGE {
defer free(message.data);
print("gzip: %\n", received_compressed(*call));
}Waits for final status, discarding unread messages one at a time. Returns an independently owned Status, freed with free_status. Non-OK may follow messages. .
channel: Channel; // set transport.base_url and transport.tls before the first call
method := Method.{ path = "/echo.Echo/Say" };
call, status := open_call(*channel, method);
assert(status.code == .OK);
defer close(*call);
status = finish(*call);
defer free_status(*status);
print("%\n", status.code);Explicit cancellation wins if no terminal result has been observed locally. Wakes blocked transport operations; join those fibers before close. .
Releases call storage after sender/receiver fibers return. Idempotent on a cleared handle; received messages and returned statuses remain caller-owned. .
Releases the channel after its calls have ended. .
channel: Channel;
// ... open calls, use them and close each one ...
close_channel(*channel);Initial application metadata borrows call-owned storage until close. On clients it becomes available after the first receive has obtained response headers. .
channel: Channel; // set transport.base_url and transport.tls before the first call
method := Method.{ path = "/echo.Echo/Say" };
call, status := open_call(*channel, method);
assert(status.code == .OK);
defer close(*call);
message, kind := receive_bytes(*call); // response headers arrive with the first receive
if kind == .MESSAGE free(message.data);
for initial_metadata(*call) print("%: %\n", it.name, it.value);The absolute monotonic deadline for explicit child-call budget inheritance. .
channel: Channel; // set transport.base_url and transport.tls before the first call
method := Method.{ path = "/echo.Echo/Say" };
call, status := open_call(*channel, method);
assert(status.code == .OK);
defer close(*call);
child := Call_Options.{ deadline_ms = call_deadline(*call) }; // the child call shares this budgetCooperative cancellation/deadline observation. CPU work must yield to the scheduler and poll; this does not preempt application code. .
Adapts a typed/generated route to the common RPC lifecycle. Identity/gzip Protobuf transport is accepted; malformed media types use HTTP 415, and unsupported compression receives UNIMPLEMENTED. The handler's state belongs to its caller. .
Http :: #import "Extensions/Http";
echo :: (call: *Call, data: *void) -> Status {
while true {
message, kind := receive_bytes(call);
if kind != .MESSAGE break;
defer free(message.data);
status := send_bytes(call, message);
if status.code != .OK return status;
}
return .{};
}
handler :: (request: *Http.Request) -> Http.Response {
return serve_call(request, Method.{ path = "/echo.Echo/Say" }, echo, null);
}The server's observed remote socket address, copied by value. A client call or cleared handle returns an unspecified address; this does not identify a user. .
Io :: #import "Extensions/Io";
log_peer :: (call: *Call, data: *void) -> Status {
print("call from %\n", Io.address_to_string(peer_address(call)));
return .{};
}Replaces application response metadata before the first send or handler return. Entries are copied by the exchange; the caller may immediately release them. Invalid metadata leaves the previous block intact. Client calls and committed response headers return FAILED_PRECONDITION without cancelling the RPC. .
reply :: (call: *Call, data: *void) -> Status {
status := set_initial_metadata(call, Metadata_Entry.[.{ "x-id", "123" }]);
if status.code != .OK return status;
return send_bytes(call, u8.[1]);
}Per-message compression uses the algorithm negotiated by grpc-encoding.
Compression :: enum u8 {
IDENTITY;
GZIP;
}bytes, failure := frame_message(u8.[1, 2, 3], compression = .GZIP);
assert(failure == .NONE);
defer free(bytes.data);
assert(bytes[0] == 1); // the compressed flag of the envelopeEnvelope validation failures. Declared-size rejection precedes payload allocation.
Wire_Error :: enum u8 {
NONE;
TOO_LARGE;
INVALID_FLAG;
UNSUPPORTED_COMPRESSION;
INVALID_COMPRESSION;
TRUNCATED;
}_, failure := frame_message(u8.[1, 2, 3], max_message = 2);
assert(failure == .TOO_LARGE);One in-progress message, with no background message queue. A ready payload is
transferred with take_message; release an abandoned decoder with free_decoder.
Envelope_Decoder :: struct {
max_message := 4 * 1024 * 1024;
max_wire_message := 4 * 1024 * 1024;
compression: Compression;
compressed: bool;
ready: bool;
failure: Wire_Error;
prefix: [5] u8;
prefix_used: int;
length: s64;
payload: [..] u8;
}wire, _ := frame_message(u8.[7, 8, 9]);
defer free(wire.data);
decoder: Envelope_Decoder;
defer free_decoder(*decoder);
used, failure := feed_envelope(*decoder, wire);
assert(failure == .NONE && used == wire.count && decoder.ready);
message := take_message(*decoder);
defer free(message.data);
assert(message.count == 3 && message[0] == 7);Canonical gRPC status numbers, including OK and explicit application errors.
Status_Code :: enum u8 {
OK;
CANCELLED;
UNKNOWN;
INVALID_ARGUMENT;
DEADLINE_EXCEEDED;
NOT_FOUND;
ALREADY_EXISTS;
PERMISSION_DENIED;
RESOURCE_EXHAUSTED;
FAILED_PRECONDITION;
ABORTED;
OUT_OF_RANGE;
UNIMPLEMENTED;
INTERNAL;
UNAVAILABLE;
DATA_LOSS;
UNAUTHENTICATED;
}assert(cast(int) Status_Code.NOT_FOUND == 5);
assert(http2_reset_status(8) == .CANCELLED);Locally observed cancellation, deadline, transport/protocol failure or limit, recorded separately from the RPC status code.
Local_Cause :: enum u8 {
NONE;
CANCELLED;
DEADLINE;
TRANSPORT;
PROTOCOL;
LIMIT;
}Http :: #import "Extensions/Http";
main :: () {
// An invalid grpc-status is a protocol failure, whatever HTTP said.
fields := Http.Header_Field.[.{ name = "grpc-status", value = "00" }];
status := parse_status(fields, 200);
defer free_status(*status);
assert(status.code == .UNKNOWN && status.cause == .PROTOCOL);
}Final application code and independently preserved local failure cause. Returned messages and trailing metadata are owned; release with free_status.
Status :: struct {
code: Status_Code = .OK;
message: string;
status_details: string;
metadata: [..] Metadata_Entry;
cause: Local_Cause;
http2_code: u32;
not_processed: bool;
}status := Status.{ code = .NOT_FOUND, message = "no such user" };
assert(status.code == .NOT_FOUND && status.cause == .NONE);
assert(Status.{}.code == .OK);One ordered application metadata entry. Names may repeat; values for names ending in -bin contain raw bytes rather than Base64 text.
Metadata_Entry :: struct {
name: string;
value: string;
}entry := Metadata_Entry.{ "trace-bin", "\x01\x02" }; // -bin values are raw bytes
assert(valid_metadata_name(entry.name));Method descriptors preserve wire paths independently of generated identifiers.
Method :: struct {
path: string;
client_streaming: bool;
server_streaming: bool;
}echo := Method.{ path = "/echo.Echo/Chat", client_streaming = true, server_streaming = true };
assert(echo.path == "/echo.Echo/Chat");Scheduler-bound RPC scope. Keep its address and TLS configuration stable until all calls and close_channel finish; active call and connection limits bound admission.
Channel :: struct {
transport: Http.Http2_Channel;
max_active_calls := 128;
active_calls: int;
}Tls :: #import "Extensions/Tls";
main :: () {
config: Tls.Tls_Config;
config.alpn = string.["h2"];
Tls.tls_config_init(*config);
defer Tls.tls_config_free(*config);
channel: Channel;
channel.transport.base_url = "https://localhost:50051";
channel.transport.tls = *config;
defer close_channel(*channel);
}Per-call deadlines and message/metadata bounds. Client outgoing metadata is borrowed through open_call; server initial metadata is borrowed through serve_call.
Call_Options :: struct {
deadline_ms: s64;
metadata: [] Metadata_Entry;
max_message := 4 * 1024 * 1024;
max_wire_message := 4 * 1024 * 1024;
compression: Compression;
max_metadata := 64 * 1024;
}options := Call_Options.{
deadline_ms = to_milliseconds(current_time_monotonic()) + 5000, // absolute, monotonic
metadata = Metadata_Entry.[.{ "x-request-id", "42" }],
compression = .GZIP,
};
channel: Channel;
call, status := open_call(*channel, Method.{ path = "/echo.Echo/Say" }, options);
defer close(*call);Per-message override: false uses an identity envelope on a negotiated gzip call.
Send_Options :: struct {
compress := true;
}channel: Channel; // set transport.base_url and transport.tls before the first call
method := Method.{ path = "/echo.Echo/Say" };
call, status := open_call(*channel, method);
assert(status.code == .OK);
defer close(*call);
// The call negotiated gzip; send this one message uncompressed.
status = send_bytes(*call, u8.[1, 2, 3], .{ compress = false });
assert(status.code == .OK);Opaque RPC handle. Join its sender and receiver before close; returned messages and statuses own independent storage.
Call :: struct {
state: *void;
}channel: Channel; // set transport.base_url and transport.tls before the first call
method := Method.{ path = "/echo.Echo/Say" };
call, status := open_call(*channel, method);
assert(status.code == .OK);
defer close(*call);
status = close_send(*call);
status = finish(*call);
defer free_status(*status);MESSAGE carries one owned message. On clients, END and ERROR still require finish to obtain the authoritative RPC status.
Receive_Kind :: enum u8 {
MESSAGE;
END;
ERROR;
}channel: Channel; // set transport.base_url and transport.tls before the first call
method := Method.{ path = "/echo.Echo/Say" };
call, status := open_call(*channel, method);
assert(status.code == .OK);
defer close(*call);
message, kind := receive_bytes(*call);
if kind == .MESSAGE free(message.data);
final := finish(*call); // the authoritative result, also after .END or .ERROR
defer free_status(*final);Handlers run on the request fiber. Join any child sender/receiver fibers before returning. Storage referenced by their returned Status remains borrowed until serve_call returns after encoding it.