protobuf 0.0.1-preview.1
Protocol Buffers and gRPC
protobuf#
A Protocol Buffers (.proto) code generator, wire-format runtime, and gRPC / gRPC-fallback transports for Zena.
Installation#
zena pkg add @zena/protobuf
Generating Code#
protobuf/generator compiles .proto schemas into Zena source code with no I/O of its own—you supply the entry file paths and a callback that reads imported .proto files:
import { generate } from 'protobuf/generator';
let source = await generate({
files: ['service.proto'],
read: async (path) => readProtoFile(path),
});
Options (GenerateOptions)#
files:Array<String>— entry.protofiles to generate from.read:(path: String) => Future<String | null>— returns the.prototext forpath, ornullif not found.roots:Array<String>(optional) — generate only the named messages, enums, or services (by full name) and the types they transitively reference. When omitted or empty, everything declared infilesis generated.runtimeImport:String(optional) — module specifier that generated code imports runtime helpers from (defaults to'protobuf/runtime').
Using Generated Code#
For each message M, the generator emits a view class M (which reads an encoded message in place without eagerly allocating child objects) and a record type MInit, which M.of encodes:
import { HashMap } from 'zena:collections';
// Decoding wire bytes
let doc = Document.decode(bytes);
let title = doc.fields.getOr('title', Value.of({}));
let text = match (title.valueType) {
case ValueStringValue {value}: value
case _: ''
};
// Encoding a message
let fields = new HashMap<String, Value>();
fields['title'] = Value.of({stringValue: 'Hello'});
let encoded = Document.of({name, fields}).protoView.toByteArray();
A message-typed field accepts the message's class, so nested messages are built inside out with M.of, and a message read from one response can be passed into another message unchanged without re-encoding.
Services and Transports#
For each service in a .proto file, the generator emits a client class over ProtoTransport (protobuf/runtime). Two transports speak over wasi:http, both supporting unary and server-streaming RPCs (and GrpcTransport also supporting client-streaming RPCs):
protobuf/grpc(GrpcTransport): standard gRPC over HTTP/2 (https://via ALPN or cleartext HTTP/2 forhttp://).protobuf/fallback(FallbackTransport): Google's gRPC HTTP/1.1$rpcfallback protocol (binary protobuf posted to/$rpc/<service>/<method>), usable on hosts whose outgoing HTTP is HTTP/1.1 only.
import { GrpcTransport } from 'protobuf/grpc';
let transport = new GrpcTransport('https://example.googleapis.com', credentials);
let client = new MyServiceClient(transport);
let response = await client.getItem({name: 'items/1'});
credentials is any Credentials (protobuf/runtime), which supplies the authorization header before each call. Generated clients also populate the x-goog-request-params routing header from google.api.http and google.api.routing options (AIP-4222). Failed calls throw RpcError (protobuf/runtime) carrying the google.rpc.Code.
Libraries#
protobuf/runtime— Wire-format views and writers (ProtoView,ProtoWriter,ProtoList,ProtoMap,ProtoBytes,ProtoStream),ProtoTransport,Credentials,RpcMetadata,RpcMethod, andRpcError.protobuf/grpc—GrpcTransportover HTTP/2.protobuf/fallback—FallbackTransportover Google's HTTP/1.1$rpcfallback protocol.protobuf/generator—generateandGenerateOptionsfor turning.protofiles into Zena source.protobuf/parserandprotobuf/lexer—.protosyntax tree and tokenizer (parseProto,Lexer).protobuf/schemaandprotobuf/emitter— Schema resolution and Zena code emission.protobuf/text— Protobuf text format helpers.
License#
MIT
/**
* The `wasi:http` plumbing the transports share: where calls go, the
* headers of a call, and one `POST` with its response.
*
* This module imports `wasi:http`, so it compiles for component targets
* only.
*/
import { Completer, release } from 'zena:async';
import { HashMap } from 'zena:collections';
import { Option, Own, Result, Some, unit } from 'zena:core';
import { Stream, bytesStream } from 'zena:stream';
import { URL } from 'zena:url';
import {
ErrorCode, ErrorCodeConnectionReadTimeout, Fields, MethodPost, Request, RequestOptions,
Response as WireResponse, Scheme, SchemeHTTP, SchemeHTTPS
} from 'wasi:http/types';
import { send } from 'wasi:http/client';
import { Credentials, ProtoError, ProtoView, RpcError, RpcMetadata, RpcMethod } from './runtime.zena';
/** `google.rpc.Code` DEADLINE_EXCEEDED, for a server that did not answer in time. */
let CODE_DEADLINE_EXCEEDED = 4;
/** `google.rpc.Code` UNAVAILABLE, for a server that could not be reached. */
let CODE_UNAVAILABLE = 14;
/**
* A response's headers or trailers, copied out of the host's `fields`:
* each field's name and value, in order.
*/
export type HeaderList = Array<(String, FixedArray<u8>)>;
/** A response's trailers, which arrive after its body. */
export type Trailers = Future<Result<Option<HeaderList>, ErrorCode>>;
/** The scheme and authority of an origin such as `https://firestore.googleapis.com`. */
export final class Origin {
scheme: Scheme;
authority: String;
new(this.scheme, this.authority);
/** Parses `origin`; throws a `ProtoError` when it is not a URL. */
static parse(origin: String): Origin {
let url = URL.parse(origin);
if (url == null) {
throw new ProtoError(`not a URL: ${origin}`);
}
let parsed = url;
let scheme: Scheme = if (parsed.protocol == 'http:') new SchemeHTTP() else new SchemeHTTPS();
return new Origin(scheme, parsed.host());
}
}
/**
* The headers of one call: `content-type`, then the transport's own
* `fixed` headers, the call's `metadata`, and the `authorization`
* `credentials` give, when there are any.
*/
export async function callHeaders(
contentType: String,
fixed: HashMap<String, String>,
metadata: RpcMetadata,
credentials: Credentials | null
): Future<Own<Fields>> {
let headers = Fields.create();
headers.append('content-type', contentType.toBytes());
for (let entry in fixed) {
headers.append(entry.key, entry.value.toBytes());
}
for (var i = 0; i < metadata.length; i += 1) {
headers.append(metadata.name(i), metadata.value(i).toBytes());
}
if (credentials != null) {
let authorization = await credentials.authorization();
if (authorization != null) {
headers.append('authorization', authorization.toBytes());
}
}
return headers;
}
/** The first value of header `name` in `fields`, or null. Names match case-insensitively. */
export function headerValue(fields: HeaderList, name: String): String | null {
let wanted = name.asciiLowerCase();
for (let (field, value) in fields) {
if (field.asciiLowerCase() == wanted) {
return String.fromBytes(value);
}
}
return null;
}
/** Whether `fields` has a header `name`. */
export function hasHeader(fields: HeaderList, name: String): boolean {
return headerValue(fields, name) != null;
}
/** The fields the trailers future holds once they arrive, as a list. */
async function trailerList(
trailers: Future<Result<Option<Own<Fields>>, ErrorCode>>
): Future<Result<Option<HeaderList>, ErrorCode>> {
match (await trailers) {
case (true, let fields): {
if (let Some {value} = fields) {
return (true, some(value.copyAll()));
}
return (true, none);
}
case (false, let error): {
return (false, error);
}
}
}
/** The options of a request whose first byte must arrive within `firstByteTimeout`, when it is not negative. */
function optionsFor(firstByteTimeout: i64): Option<Own<RequestOptions>> {
if (firstByteTimeout < 0) {
return none;
}
let options = RequestOptions.create();
options.setFirstByteTimeout(some(firstByteTimeout as u64));
return some(options);
}
/** One response: its status, headers, body, and the trailers after the body. */
export final class Exchange {
status: i32;
headers: HeaderList;
body: Stream<u8>;
trailers: Trailers;
#received: Completer<Result<void, ErrorCode>>;
new(this.status, this.headers, this.body, this.trailers, received: Completer<Result<void, ErrorCode>>)
: #received = received;
/** A response made of the given parts, for reading a body that did not come from `post`. */
static of(status: i32, headers: HeaderList, body: Stream<u8>, trailers: Trailers): Exchange {
return new Exchange(status, headers, body, trailers, new Completer<Result<void, ErrorCode>>());
}
/** Whether the `content-type` header starts with `prefix`. */
contentTypeIs(prefix: String): boolean {
let contentType = headerValue(this.headers, 'content-type');
return contentType != null && contentType.startsWith(prefix);
}
/** Tells the host the body has been read to its end. */
finish(): void {
this.#received.tryComplete((true, unit()));
}
}
/**
* POSTs `body` with `headers` to `path` at `origin`. When
* `firstByteTimeout` is not negative, the response's headers must arrive
* within that many nanoseconds of the request being sent, or the call
* fails with DEADLINE_EXCEEDED. Throws an `RpcError` with code
* UNAVAILABLE, naming `method`, when no response arrives otherwise.
*/
export async function post(
origin: Origin,
path: String,
headers: Own<Fields>,
body: ByteArray,
method: RpcMethod,
firstByteTimeout: i64 = -1
): Future<Exchange> {
// The trailers future is the sender's to settle, and the host does
// not consider the request body finished until it is.
let trailers = Future.of<Result<Option<Own<Fields>>, ErrorCode>>(
(true, none));
let (wire, transmitted) = Request.new_(headers,
some(bytesStream(body as FixedArray<u8>)), trailers, optionsFor(firstByteTimeout));
// Nothing waits on the transmission. Dropping a future of a plain
// value releases nothing, so its end is given up here (TODO(#831)).
transmitted.[release]();
wire.setMethod(new MethodPost());
wire.setScheme(some(origin.scheme));
wire.setAuthority(some(origin.authority));
wire.setPathWithQuery(some(path));
let sent = await send(wire);
let response = match (sent) {
case (true, let value): value
case (false, let error): {
if (error is ErrorCodeConnectionReadTimeout) {
throw new RpcError(
CODE_DEADLINE_EXCEEDED,
`${method.service}/${method.name}: no response from ${origin.authority} within the deadline`,
ProtoView.empty()
);
}
throw new RpcError(
CODE_UNAVAILABLE,
`${method.service}/${method.name}: no response from ${origin.authority}`,
ProtoView.empty()
);
}
};
// Read the status and headers first: `consumeBody` takes the response.
let status = response.getStatusCode() as i32;
let wireHeaders = response.getHeaders();
let responseHeaders = wireHeaders.copyAll();
let received = new Completer<Result<void, ErrorCode>>();
let (responseBody, responseTrailers) = WireResponse.consumeBody(response, received.future);
// Read as they arrive, which is after the body: the reader keeps
// plain data, while the trailers future holds the host's fields.
return new Exchange(status, responseHeaders, responseBody, trailerList(responseTrailers), received);
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|