protobuf 0.0.1-preview.1

Protocol Buffers and gRPC

Readme Files Dependencies Versions

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 .proto files to generate from.
  • read: (path: String) => Future<String | null> — returns the .proto text for path, or null if 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 in files is 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 for http://).
  • protobuf/fallback (FallbackTransport): Google's gRPC HTTP/1.1 $rpc fallback 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, and RpcError.
  • protobuf/grpc — GrpcTransport over HTTP/2.
  • protobuf/fallback — FallbackTransport over Google's HTTP/1.1 $rpc fallback protocol.
  • protobuf/generator — generate and GenerateOptions for turning .proto files into Zena source.
  • protobuf/parser and protobuf/lexer — .proto syntax tree and tokenizer (parseProto, Lexer).
  • protobuf/schema and protobuf/emitter — Schema resolution and Zena code emission.
  • protobuf/text — Protobuf text format helpers.

License#

MIT

7.4 KiB Raw
/**
 * 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);
}

none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none