Esc

Grpc

moduleextensionSource
  • macOS: Everything works on macOS
  • Linux: Everything works on Linux
  • Windows: Everything works on Windows
  • Wasm: Everything works on Wasm
·since 0.36.1

#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:

Example↗
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"]):

Example
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);

Procedures#

Wire#

(message: [] u8, max_message := 4 * 1024 * 1024, compression := Compression.IDENTITY, max_wire_message := 4 * 1024 * 1024) -> ([] u8, Wire_Error)

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);
↗
(decoder: *Envelope_Decoder, bytes: [] u8) -> (used: int, failure: Wire_Error)

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);
↗
take_messagesince 0.36.1Source
(decoder: *Envelope_Decoder) -> [] u8

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); }

Status#

parse_statussince 0.36.1Source
(fields: [] Http.Header_Field, http_status: int, limit := 64 * 1024) -> Status

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);
}
↗
free_statussince 0.36.1Source
(status: *Status)

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
}
↗
(text: string) -> (milliseconds: s64, ok: bool)

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);
↗

Metadata#

(metadata: [] Metadata_Entry, limit := 64 * 1024) -> (fields: [] Http.Header_Field, ok: bool)

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 Base64
↗
(fields: [] Http.Header_Field, limit := 64 * 1024) -> (metadata: [..] Metadata_Entry, ok: bool)

Copies 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
}
↗
(metadata: *[..] Metadata_Entry)

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);
}
↗

Call#

open_callsince 0.36.1Source
(channel: *Channel, method: Method, options := Call_Options.{}) -> (Call, Status)

Opens an RPC without retry or redirect. The channel and TLS configuration must remain alive until every call and close_channel have completed. .

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);
send_bytessince 0.36.1Source
(call: *Call, message: [] u8, options := Send_Options.{}) -> Status

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);
sendsince 0.36.1Source
(call: *Call, message: $T, options := Send_Options.{}) -> Status

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);
}
close_sendsince 0.36.1Source
(call: *Call) -> Status

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);
(call: *Call) -> (message: [] u8, kind: Receive_Kind)

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);
}
receivesince 0.36.1Source
(call: *Call, $T: Type) -> (value: T, kind: Receive_Kind)

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);
    }
}
(call: *Call) -> bool

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));
}
finishsince 0.36.1Source
(call: *Call) -> Status

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);
cancelsince 0.36.1Source
(call: *Call)

Explicit cancellation wins if no terminal result has been observed locally. Wakes blocked transport operations; join those fibers before close. .

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);
cancel(*call); // wakes a blocked sender or receiver; join them before close
closesince 0.36.1Source
(call: *Call)

Releases call storage after sender/receiver fibers return. Idempotent on a cleared handle; received messages and returned statuses remain caller-owned. .

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);
close(*call);
close(*call); // the second call is harmless
(channel: *Channel)

Releases the channel after its calls have ended. .

channel: Channel;
// ... open calls, use them and close each one ...
close_channel(*channel);
(call: *Call) -> [] Metadata_Entry

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);
(call: *Call) -> s64

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 budget
cancelledsince 0.36.1Source
(call: *Call) -> bool

Cooperative cancellation/deadline observation. CPU work must yield to the scheduler and poll; this does not preempt application code. .

handle :: (call: *Call, data: *void) -> Status {
    while !cancelled(call) {
        // ... a unit of work, then yield to the scheduler ...
        break;
    }

    if cancelled(call) return .{ code = .CANCELLED };
    return .{};
}

Server#

serve_callsince 0.36.1Source
(request: *Http.Request, method: Method, handler: Call_Handler, data: *void, options := Call_Options.{}) -> Http.Response

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);
}
peer_addresssince 0.36.1Source
(call: *Call) -> Io.Address

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 .{};
}
(call: *Call, entries: [] Metadata_Entry) -> Status

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]);
}

Types#

Compressionenumsince 0.36.1Source

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 envelope
↗
Wire_Errorenumsince 0.36.1Source

Envelope 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);
↗
Envelope_Decoderstructsince 0.36.1Source

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);
↗
Status_Codeenumsince 0.36.1Source

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);
↗
Local_Causeenumsince 0.36.1Source

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);
}
↗
Statusstructsince 0.36.1Source

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);
↗
Metadata_Entrystructsince 0.36.1Source

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));
↗
Methodstructsince 0.36.1Source

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");
Channelstructsince 0.36.1Source

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);
}
Call_Optionsstructsince 0.36.1Source

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);
Send_Optionsstructsince 0.36.1Source

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);
Callstructsince 0.36.1Source

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);
Receive_Kindenumsince 0.36.1Source

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);
Call_Handlertypesince 0.36.1Source
:: #type (call: *Call, data: *void) -> Status

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.