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 runtime that generated protobuf code calls.
*
* A decoded message is a `ProtoView`: the bytes it was received in and the
* range it occupies. Nothing is decoded until a field is read, and each
* read decodes only that field, so a program carries code for the fields
* it reads and no others. Unknown fields are skipped by wire type, which
* needs no schema.
*
* A message to send is encoded by a `ProtoWriter`. Generated code encodes
* a nested message before its parent and embeds the child's bytes, so a
* message's length is always known when it is written.
*
* Wire format: https://protobuf.dev/programming-guides/encoding/
*/
import {AsyncIterable, AsyncIterator, AsyncStep} from 'zena:async';
import {HashMap} from 'zena:collections';
import {
ByteBuffer,
Encoding,
IterableUtils,
Step,
copyBytes,
newByteArray,
readU32,
readU64,
readULEB128_64
} from 'zena:core';
import {
f32_reinterpret_i32,
f64_reinterpret_i64,
i32_reinterpret_f32,
i64_reinterpret_f64
} from 'zena:math';
/** Malformed input: a truncated message, a bad varint, a wire type that does not match the schema. */
export class ProtoError extends Error {
new(message: String) : super(message);
}
/**
* A call that failed, whatever the transport. `code` is a
* `google.rpc.Code`, `message` the server's explanation, and `status` the
* encoded `google.rpc.Status` the server sent, for its details; it is
* empty when the server sent none.
*/
export class RpcError extends Error {
code: i32;
status: ProtoView;
new(code: i32, message: String, status: ProtoView)
: code = code, status = status, super(message);
}
/** The wire type of a varint: `int32`, `int64`, `uint*`, `sint*`, `bool`, enums. */
export let WIRE_VARINT = 0;
/** The wire type of `fixed64`, `sfixed64` and `double`. */
export let WIRE_I64 = 1;
/** The wire type of a length-delimited value: strings, bytes, messages, packed repeated fields. */
export let WIRE_LEN = 2;
/** The wire type of `fixed32`, `sfixed32` and `float`. */
export let WIRE_I32 = 5;
/**
* Field numbers below this are indexed in an array, the rest in a map.
* Messages generated from `.proto` files rarely number fields past a few
* dozen, while the protocol allows up to 2^29 - 1.
*/
let DENSE_LIMIT = 1024;
let EMPTY_BYTES = newByteArray(0);
/**
* The low 32 bits of an i64. Typed so the literal is 2^32 - 1: untyped,
* `0xFFFFFFFF` beside an i64 is the i32 -1, sign-extended.
*/
let MASK32: i64 = 0xFFFFFFFF;
/** `n` zigzag-decoded: 0, -1, 1, -2, ... from 0, 1, 2, 3, ... */
function unzigzag32(n: i32) {
return (n >>> 1) ^ (0 - (n & 1));
}
function unzigzag64(n: i64) {
return (n >>> 1) ^ (0 - (n & 1));
}
/**
* One encoded message, read on demand.
*
* The getters take a field number and return the field's value, or the
* field type's default when the field is absent. Where a field occurs more
* than once the last occurrence wins, except for a message field, whose
* occurrences are merged as the protobuf specification requires.
*
* The first read builds an index of where each field occurs, in one pass
* over the message; every read after that goes straight to its field.
*/
export final class ProtoView {
#bytes: ByteArray;
#start: i32;
#end: i32;
/**
* Per field number below `DENSE_LIMIT`, three entries: the offset of the
* first tag plus one, the offset of the last tag plus one, and the
* number of occurrences. Zero means absent.
*/
var #dense: FixedArray<i32> | null = null;
/** The same three entries, for field numbers at or above `DENSE_LIMIT`. */
var #sparse: HashMap<i32, FixedArray<i32>> | null = null;
/** The position just past the value the last `read*` call decoded. */
var #cursor: i32 = 0;
/** A view of `bytes[start..end]`, which must hold one encoded message. */
new(bytes: ByteArray, start: i32, end: i32) : #bytes = bytes, #start = start, #end = end;
/** A view of all of `bytes`. */
static of(bytes: ByteArray): ProtoView {
return new ProtoView(bytes, 0, bytes.length);
}
/** A view of a message with no fields set. */
static empty(): ProtoView {
return new ProtoView(EMPTY_BYTES, 0, 0);
}
/**
* `parts`, encodings of one message type, concatenated. Protobuf
* defines that as merging them in order: a later singular field
* replaces an earlier one, repeated fields append, and message fields
* merge. Building a message from parts lets each optional field be
* encoded only when it is present.
*/
static merge(parts: Array<ProtoView>): ProtoView {
var total = 0;
for (let part in parts) {
total += part.byteLength;
}
let out = newByteArray(total);
var at = 0;
for (let part in parts) {
copyBytes(out, at, part.buffer, part.start, part.byteLength);
at += part.byteLength;
}
return new ProtoView(out, 0, total);
}
/** The array holding the encoded message. Other data may share it. */
buffer: ByteArray {
get { return this.#bytes; }
}
/** Where the message starts in `buffer`. */
start: i32 {
get { return this.#start; }
}
/** Where the message ends in `buffer`. */
end: i32 {
get { return this.#end; }
}
/** The encoded message's size in bytes. */
byteLength: i32 {
get { return this.#end - this.#start; }
}
/** A copy of the encoded message. */
toByteArray(): ByteArray {
let out = newByteArray(this.#end - this.#start);
copyBytes(out, 0, this.#bytes, this.#start, this.#end - this.#start);
return out;
}
/** The position just past the value the last `read*` or `tagAt` call decoded. */
cursor: i32 {
get { return this.#cursor; }
}
/** Whether field `field` occurs at least once. */
has(field: i32): boolean {
return this.#entry(field, 2) > 0;
}
/** How many times field `field` occurs. A packed repeated field counts once per run. */
count(field: i32): i32 {
return this.#entry(field, 2);
}
/** The offset of field `field`'s first tag, or -1. */
firstTag(field: i32): i32 {
return this.#entry(field, 0) - 1;
}
/** The offset of field `field`'s last tag, or -1. */
lastTag(field: i32): i32 {
return this.#entry(field, 1) - 1;
}
/**
* Of the fields in `fields`, the one that occurs last, or 0 when none
* occurs. This is the member of a `oneof` that is set: a later member
* replaces an earlier one.
*/
whichOf(fields: ImmutableArray<i32>): i32 {
var best = 0;
var bestOffset = -1;
for (let field in fields) {
let offset = this.lastTag(field);
if (offset > bestOffset) {
best = field;
bestOffset = offset;
}
}
return best;
}
/** `int32` and enum fields. */
int32(field: i32): i32 {
let pos = this.#valueOf(field, WIRE_VARINT);
return if (pos < 0) 0 else this.int32At(pos);
}
/** `int64` fields. */
int64(field: i32): i64 {
let pos = this.#valueOf(field, WIRE_VARINT);
return if (pos < 0) 0 else this.int64At(pos);
}
/** `uint32` fields. */
uint32(field: i32): u32 {
let pos = this.#valueOf(field, WIRE_VARINT);
return if (pos < 0) 0 else this.uint32At(pos);
}
/** `uint64` fields. */
uint64(field: i32): u64 {
let pos = this.#valueOf(field, WIRE_VARINT);
return if (pos < 0) 0 else this.uint64At(pos);
}
/** `sint32` fields, which are zigzag-encoded. */
sint32(field: i32): i32 {
let pos = this.#valueOf(field, WIRE_VARINT);
return if (pos < 0) 0 else this.sint32At(pos);
}
/** `sint64` fields, which are zigzag-encoded. */
sint64(field: i32): i64 {
let pos = this.#valueOf(field, WIRE_VARINT);
return if (pos < 0) 0 else this.sint64At(pos);
}
/** `bool` fields. */
bool(field: i32): boolean {
let pos = this.#valueOf(field, WIRE_VARINT);
return if (pos < 0) false else this.boolAt(pos);
}
/** `fixed32` fields. */
fixed32(field: i32): u32 {
let pos = this.#valueOf(field, WIRE_I32);
return if (pos < 0) 0 else this.fixed32At(pos);
}
/** `sfixed32` fields. */
sfixed32(field: i32): i32 {
let pos = this.#valueOf(field, WIRE_I32);
return if (pos < 0) 0 else this.sfixed32At(pos);
}
/** `float` fields. */
float(field: i32): f32 {
let pos = this.#valueOf(field, WIRE_I32);
return if (pos < 0) 0.0 as f32 else this.floatAt(pos);
}
/** `fixed64` fields. */
fixed64(field: i32): u64 {
let pos = this.#valueOf(field, WIRE_I64);
return if (pos < 0) 0 else this.fixed64At(pos);
}
/** `sfixed64` fields. */
sfixed64(field: i32): i64 {
let pos = this.#valueOf(field, WIRE_I64);
return if (pos < 0) 0 else this.sfixed64At(pos);
}
/** `double` fields. */
double(field: i32): f64 {
let pos = this.#valueOf(field, WIRE_I64);
return if (pos < 0) 0.0 else this.doubleAt(pos);
}
/**
* `string` fields. The result shares this view's buffer; nothing is
* copied. The bytes are taken as WTF-8 without validation.
*/
string(field: i32): String {
let pos = this.#valueOf(field, WIRE_LEN);
return if (pos < 0) '' else this.stringAt(pos);
}
/** `bytes` fields. The result shares this view's buffer. */
bytes(field: i32): ProtoBytes {
let pos = this.#valueOf(field, WIRE_LEN);
return if (pos < 0) ProtoBytes.empty() else this.bytesAt(pos);
}
/**
* A message field, or null when it is absent. When the field occurs
* more than once, the occurrences are merged: the result is a view of
* their concatenation, which the specification defines to be the merge.
*/
message(field: i32): ProtoView | null {
let count = this.count(field);
if (count == 0) {
return null;
}
if (count == 1) {
return this.messageAt(this.#valueOf(field, WIRE_LEN));
}
let parts = new ByteBuffer();
var pos = this.firstTag(field);
while (pos < this.#end) {
let tag = this.tagAt(pos);
let valueStart = this.#cursor;
let next = this.skip(tag & 7, valueStart);
if ((tag >>> 3) == field) {
if ((tag & 7) != WIRE_LEN) {
throw new ProtoError(`field ${field} has wire type ${tag & 7}, expected 2`);
}
let len = this.readVarint(valueStart) as i32;
parts.writeBytesSlice(this.#bytes, this.#cursor, len);
}
pos = next;
}
return ProtoView.of(parts.toByteArray());
}
/** A message field, or a message with no fields set when it is absent. */
messageOrEmpty(field: i32): ProtoView {
let m = this.message(field);
return m ?? ProtoView.empty();
}
/**
* A repeated field. `wireType` is the wire type of one element, and
* `read` decodes one element at a value position, leaving `cursor` past
* it: `(v, pos) => v.int32At(pos)`. Elements of a numeric type may arrive packed, unpacked, or both,
* and are accepted either way.
*/
repeated<T>(field: i32, wireType: i32, read: (view: ProtoView, pos: i32) => T): ProtoList<T> {
return new ProtoList<T>(this, field, wireType, read);
}
/**
* A map field: a repeated message field whose entries hold the key in
* field 1 and the value in field 2. `key` and `value` read them from an
* entry.
*/
map<K, V>(
field: i32,
key: (entry: ProtoView) => K,
value: (entry: ProtoView) => V
): ProtoMap<K, V> {
return new ProtoMap<K, V>(this, field, key, value);
}
/** Reads the varint at `pos`. */
readVarint(pos: i32): i64 {
let (value, next) = readULEB128_64(this.#bytes, pos, this.#end);
if (next < 0) {
throw new ProtoError('truncated varint, or one longer than 10 bytes');
}
this.#cursor = next;
return value;
}
/** Reads the four little-endian bytes at `pos`. */
readFixed32(pos: i32): i32 {
if (pos + 4 > this.#end) {
throw new ProtoError('truncated fixed32');
}
this.#cursor = pos + 4;
return readU32(this.#bytes, pos);
}
/** Reads the eight little-endian bytes at `pos`. */
readFixed64(pos: i32): i64 {
if (pos + 8 > this.#end) {
throw new ProtoError('truncated fixed64');
}
this.#cursor = pos + 8;
return readU64(this.#bytes, pos);
}
/** Reads the length prefix at `pos` and returns where the value ends; `cursor` is where it starts. */
readLength(pos: i32): i32 {
let len = this.readVarint(pos);
let start = this.#cursor;
if (len < 0 || len > ((this.#end - start) as i64)) {
throw new ProtoError('length-delimited value runs past the end of its message');
}
return start + (len as i32);
}
/** Reads an `int32` or enum value at `pos`. */
int32At(pos: i32): i32 {
return this.readVarint(pos) as i32;
}
int64At(pos: i32): i64 {
return this.readVarint(pos);
}
uint32At(pos: i32): u32 {
return (this.readVarint(pos) as i32) as u32;
}
uint64At(pos: i32): u64 {
return this.readVarint(pos) as u64;
}
sint32At(pos: i32): i32 {
return unzigzag32(this.readVarint(pos) as i32);
}
sint64At(pos: i32): i64 {
return unzigzag64(this.readVarint(pos));
}
boolAt(pos: i32): boolean {
return this.readVarint(pos) != 0;
}
fixed32At(pos: i32): u32 {
return this.readFixed32(pos) as u32;
}
sfixed32At(pos: i32): i32 {
return this.readFixed32(pos);
}
floatAt(pos: i32): f32 {
return f32_reinterpret_i32(this.readFixed32(pos));
}
fixed64At(pos: i32): u64 {
return this.readFixed64(pos) as u64;
}
sfixed64At(pos: i32): i64 {
return this.readFixed64(pos);
}
doubleAt(pos: i32): f64 {
return f64_reinterpret_i64(this.readFixed64(pos));
}
/** Reads the string whose length prefix is at `pos`. */
stringAt(pos: i32): String {
let end = this.readLength(pos);
let start = this.#cursor;
this.#cursor = end;
return String.fromByteArray(this.#bytes, start, end, Encoding.WTF8);
}
/** Reads the bytes value whose length prefix is at `pos`. */
bytesAt(pos: i32): ProtoBytes {
let end = this.readLength(pos);
let start = this.#cursor;
this.#cursor = end;
return new ProtoBytes(this.#bytes, start, end);
}
/** Reads the message whose length prefix is at `pos`. */
messageAt(pos: i32): ProtoView {
let end = this.readLength(pos);
let start = this.#cursor;
this.#cursor = end;
return new ProtoView(this.#bytes, start, end);
}
/** Reads the tag at `pos`; `cursor` is where its value starts. */
tagAt(pos: i32): i32 {
let tag = this.readVarint(pos);
if (tag > MASK32 || (tag >>> 3) == 0) {
throw new ProtoError('invalid tag');
}
return tag as i32;
}
/** Where the value of wire type `wireType` starting at `pos` ends. */
skip(wireType: i32, pos: i32): i32 {
if (wireType == WIRE_VARINT) {
this.readVarint(pos);
return this.#cursor;
}
if (wireType == WIRE_I64) {
return this.#within(pos + 8);
}
if (wireType == WIRE_I32) {
return this.#within(pos + 4);
}
if (wireType == WIRE_LEN) {
return this.readLength(pos);
}
throw new ProtoError(`unsupported wire type ${wireType}`);
}
#within(pos: i32): i32 {
if (pos > this.#end) {
throw new ProtoError('truncated value');
}
return pos;
}
/**
* Where the value of field `field`'s last occurrence starts, or -1 when
* the field is absent. Throws if it was written with another wire type.
*/
#valueOf(field: i32, wireType: i32): i32 {
let tagPos = this.lastTag(field);
if (tagPos < 0) {
return -1;
}
let tag = this.tagAt(tagPos);
if ((tag & 7) != wireType) {
throw new ProtoError(`field ${field} has wire type ${tag & 7}, expected ${wireType}`);
}
return this.#cursor;
}
/** Entry `k` of field `field`'s index slot: see `#dense`. */
#entry(field: i32, k: i32): i32 {
if (this.#dense == null) {
this.#buildIndex();
}
if (field < DENSE_LIMIT) {
let dense = this.#dense as FixedArray<i32>;
let i = field * 3 + k;
return if (i < dense.length) dense[i] else 0;
}
let sparse = this.#sparse;
if (sparse == null) {
return 0;
}
if (let (true, slot) = sparse.get(field)) {
return slot[k];
}
return 0;
}
/** Scans the message once, recording where each field occurs. */
#buildIndex(): void {
var maxField = 0;
var pos = this.#start;
while (pos < this.#end) {
let tag = this.tagAt(pos);
let field = tag >>> 3;
if (field < DENSE_LIMIT && field > maxField) {
maxField = field;
}
pos = this.skip(tag & 7, this.#cursor);
}
let dense = new FixedArray<i32>((maxField + 1) * 3, 0);
pos = this.#start;
while (pos < this.#end) {
let tag = this.tagAt(pos);
let field = tag >>> 3;
let next = this.skip(tag & 7, this.#cursor);
if (field < DENSE_LIMIT) {
let i = field * 3;
if (dense[i] == 0) {
dense[i] = pos + 1;
}
dense[i + 1] = pos + 1;
dense[i + 2] = dense[i + 2] + 1;
} else {
this.#recordSparse(field, pos);
}
pos = next;
}
this.#dense = dense;
}
#recordSparse(field: i32, pos: i32): void {
if (this.#sparse == null) {
this.#sparse = new HashMap<i32, FixedArray<i32>>();
}
let sparse = this.#sparse as HashMap<i32, FixedArray<i32>>;
if (let (true, slot) = sparse.get(field)) {
slot[1] = pos + 1;
slot[2] = slot[2] + 1;
return;
}
let slot = new FixedArray<i32>(3, 0);
slot[0] = pos + 1;
slot[1] = pos + 1;
slot[2] = 1;
sparse[field] = slot;
}
}
/** The value of a `bytes` field: a range of a buffer, shared with the message it came from. */
export final class ProtoBytes {
#bytes: ByteArray;
#start: i32;
#end: i32;
new(bytes: ByteArray, start: i32, end: i32) : #bytes = bytes, #start = start, #end = end;
/** A view of all of `bytes`, which must not change afterwards. */
static of(bytes: ByteArray): ProtoBytes {
return new ProtoBytes(bytes, 0, bytes.length);
}
/** No bytes. */
static empty(): ProtoBytes {
return new ProtoBytes(EMPTY_BYTES, 0, 0);
}
length: i32 {
get { return this.#end - this.#start; }
}
/** The byte at `index`, from 0 to 255. */
operator [](index: i32): i32 {
if (index < 0 || index >= this.#end - this.#start) {
throw new ProtoError(`index ${index} is out of range`);
}
return this.#bytes[this.#start + index] as i32;
}
/** A copy of the bytes. */
toByteArray(): ByteArray {
let out = newByteArray(this.#end - this.#start);
copyBytes(out, 0, this.#bytes, this.#start, this.#end - this.#start);
return out;
}
/** Appends the bytes to `buffer`. */
writeTo(buffer: ByteBuffer): void {
buffer.writeBytesSlice(this.#bytes, this.#start, this.#end - this.#start);
}
}
/** The elements of a repeated field, decoded as they are iterated. */
export final class ProtoList<T> with IterableUtils<T> implements Iterable<T> {
#view: ProtoView;
#field: i32;
#wireType: i32;
#read: (view: ProtoView, pos: i32) => T;
new(view: ProtoView, field: i32, wireType: i32, read: (view: ProtoView, pos: i32) => T)
: #view = view, #field = field, #wireType = wireType, #read = read;
/** The number of elements. Counting a packed field decodes it. */
length: i32 {
get {
if (this.#wireType == WIRE_LEN) {
return this.#view.count(this.#field);
}
var n = 0;
let items = this.[Iterable.iterator]();
while (true) {
let (more, _, _) = items.next();
if (more == 0) {
return n;
}
n += 1;
}
return n;
}
}
[Iterable.iterator](): Iterator<T> {
return new ProtoListIterator<T>(this.#view, this.#field, this.#wireType, this.#read);
}
/** The elements, decoded into an array. */
toArray(): GrowableArray<T> {
let out = new GrowableArray<T>();
for (let item in this) {
out.push(item);
}
return out;
}
}
/** Walks a message for the occurrences of one field, and inside each packed run. */
final class ProtoListIterator<T> implements Iterator<T> {
#view: ProtoView;
#field: i32;
#wireType: i32;
#read: (view: ProtoView, pos: i32) => T;
/** Where to look for the field's next occurrence. */
var #scan: i32;
/** The packed run being read, if any: next element and end. */
var #packedPos: i32 = 0;
var #packedEnd: i32 = 0;
new(view: ProtoView, field: i32, wireType: i32, read: (view: ProtoView, pos: i32) => T)
: #view = view, #field = field, #wireType = wireType, #read = read,
#scan = if (view.firstTag(field) < 0) view.end else view.firstTag(field);
next(): Step<T> {
let view = this.#view;
while (true) {
if (this.#packedPos < this.#packedEnd) {
let value = this.#read(view, this.#packedPos);
this.#packedPos = view.cursor;
return (1, value, _);
}
if (this.#scan >= view.end) {
return (0, _, _);
}
let tag = view.tagAt(this.#scan);
let valueStart = view.cursor;
let wireType = tag & 7;
if ((tag >>> 3) != this.#field) {
this.#scan = view.skip(wireType, valueStart);
continue;
}
if (wireType == WIRE_LEN && this.#wireType != WIRE_LEN) {
let end = view.readLength(valueStart);
this.#packedPos = view.cursor;
this.#packedEnd = end;
this.#scan = end;
continue;
}
if (wireType != this.#wireType) {
throw new ProtoError(`field ${this.#field} has wire type ${wireType}, expected ${this.#wireType}`);
}
this.#scan = view.skip(wireType, valueStart);
return (1, this.#read(view, valueStart), _);
}
return (0, _, _);
}
}
/** One entry of a `ProtoMap`. */
export final class ProtoMapEntry<K, V> {
key: K;
value: V;
new(this.key, this.value);
}
/**
* The entries of a map field. Each lookup scans the entries; for many
* lookups, copy them into a `HashMap` first. When a key occurs more than
* once, the last entry wins.
*/
export final class ProtoMap<K, V> with IterableUtils<ProtoMapEntry<K, V>> implements Iterable<ProtoMapEntry<K, V>> {
#view: ProtoView;
#field: i32;
#key: (entry: ProtoView) => K;
#value: (entry: ProtoView) => V;
new(
view: ProtoView,
field: i32,
key: (entry: ProtoView) => K,
value: (entry: ProtoView) => V
) : #view = view, #field = field, #key = key, #value = value;
/** The number of entries on the wire, counting a repeated key each time. */
length: i32 {
get { return this.#view.count(this.#field); }
}
/** Whether some entry has key `key`. */
has(key: K): boolean {
for (let entry in this.#entries()) {
if (this.#key(entry) == key) {
return true;
}
}
return false;
}
/** The value of the last entry with key `key`, or `fallback` when there is none. */
getOr(key: K, fallback: V): V {
var found: ProtoView | null = null;
for (let entry in this.#entries()) {
if (this.#key(entry) == key) {
found = entry;
}
}
return if (found == null) fallback else this.#value(found);
}
[Iterable.iterator](): Iterator<ProtoMapEntry<K, V>> {
let out = new GrowableArray<ProtoMapEntry<K, V>>();
for (let entry in this.#entries()) {
out.push(new ProtoMapEntry<K, V>(this.#key(entry), this.#value(entry)));
}
return out.[Iterable.iterator]();
}
#entries(): ProtoList<ProtoView> {
return this.#view.repeated(this.#field, WIRE_LEN, (v, pos) => v.messageAt(pos));
}
}
/**
* Encodes one message. Each method writes one field: its tag, then its
* value. Fields may be written in any order, and a field written twice
* reads back as its last value.
*/
export final class ProtoWriter {
#buffer: ByteBuffer;
new() : #buffer = new ByteBuffer(64);
/** The bytes written so far, as a view. */
finish(): ProtoView {
return ProtoView.of(this.#buffer.toByteArray());
}
/** Writes a tag. */
tag(field: i32, wireType: i32): void {
this.#buffer.writeULEB128((field << 3) | wireType);
}
#varint(value: i64): void {
this.#buffer.writeULEB128_64(value);
}
/** Writes `int32` or enum value with no tag, as an element of a packed field. */
rawInt32(value: i32): void {
this.#varint(value as i64);
}
/** Writes `int64` value with no tag, as an element of a packed field. */
rawInt64(value: i64): void {
this.#varint(value);
}
/** Writes `uint32` value with no tag, as an element of a packed field. */
rawUint32(value: u32): void {
this.#varint(value as i64);
}
/** Writes `uint64` value with no tag, as an element of a packed field. */
rawUint64(value: u64): void {
this.#varint(value as i64);
}
/** Writes `sint32` value with no tag, as an element of a packed field. */
rawSint32(value: i32): void {
this.#varint((((value << 1) ^ (value >> 31)) as i64) & MASK32);
}
/** Writes `sint64` value with no tag, as an element of a packed field. */
rawSint64(value: i64): void {
this.#varint((value << 1) ^ (value >> 63));
}
/** Writes `bool` value with no tag, as an element of a packed field. */
rawBool(value: boolean): void {
this.#varint(if (value) 1 else 0);
}
/** Writes `fixed32` value with no tag, as an element of a packed field. */
rawFixed32(value: u32): void {
this.#buffer.writeU32(value as i32);
}
/** Writes `sfixed32` value with no tag, as an element of a packed field. */
rawSfixed32(value: i32): void {
this.#buffer.writeU32(value);
}
/** Writes `float` value with no tag, as an element of a packed field. */
rawFloat(value: f32): void {
this.#buffer.writeU32(i32_reinterpret_f32(value));
}
/** Writes `fixed64` value with no tag, as an element of a packed field. */
rawFixed64(value: u64): void {
this.#buffer.writeU64(value as i64);
}
/** Writes `sfixed64` value with no tag, as an element of a packed field. */
rawSfixed64(value: i64): void {
this.#buffer.writeU64(value);
}
/** Writes `double` value with no tag, as an element of a packed field. */
rawDouble(value: f64): void {
this.#buffer.writeU64(i64_reinterpret_f64(value));
}
int32(field: i32, value: i32): void {
this.tag(field, WIRE_VARINT);
this.rawInt32(value);
}
int64(field: i32, value: i64): void {
this.tag(field, WIRE_VARINT);
this.rawInt64(value);
}
uint32(field: i32, value: u32): void {
this.tag(field, WIRE_VARINT);
this.rawUint32(value);
}
uint64(field: i32, value: u64): void {
this.tag(field, WIRE_VARINT);
this.rawUint64(value);
}
sint32(field: i32, value: i32): void {
this.tag(field, WIRE_VARINT);
this.rawSint32(value);
}
sint64(field: i32, value: i64): void {
this.tag(field, WIRE_VARINT);
this.rawSint64(value);
}
bool(field: i32, value: boolean): void {
this.tag(field, WIRE_VARINT);
this.rawBool(value);
}
fixed32(field: i32, value: u32): void {
this.tag(field, WIRE_I32);
this.rawFixed32(value);
}
sfixed32(field: i32, value: i32): void {
this.tag(field, WIRE_I32);
this.rawSfixed32(value);
}
float(field: i32, value: f32): void {
this.tag(field, WIRE_I32);
this.rawFloat(value);
}
fixed64(field: i32, value: u64): void {
this.tag(field, WIRE_I64);
this.rawFixed64(value);
}
sfixed64(field: i32, value: i64): void {
this.tag(field, WIRE_I64);
this.rawSfixed64(value);
}
double(field: i32, value: f64): void {
this.tag(field, WIRE_I64);
this.rawDouble(value);
}
/** Writes a string field. The string must be WTF-8, as every string built in a component is. */
string(field: i32, value: String): void {
if (value.encoding != Encoding.WTF8) {
throw new ProtoError('only WTF-8 strings can be encoded');
}
let len = value.length;
this.tag(field, WIRE_LEN);
this.#buffer.writeULEB128(len);
let bytes = newByteArray(len);
value.copyBytesTo(bytes, 0);
this.#buffer.writeBytes(bytes);
}
/** Writes a bytes field. */
bytes(field: i32, value: ByteArray | ProtoBytes): void {
this.tag(field, WIRE_LEN);
if (value is ProtoBytes) {
let b = value;
this.#buffer.writeULEB128(b.length);
b.writeTo(this.#buffer);
} else {
let b = value as ByteArray;
this.#buffer.writeULEB128(b.length);
this.#buffer.writeBytes(b);
}
}
/** Writes a message field, copying the message's encoded bytes. */
message(field: i32, value: ProtoView): void {
this.tag(field, WIRE_LEN);
this.#buffer.writeULEB128(value.byteLength);
this.#buffer.writeBytesSlice(value.buffer, value.start, value.byteLength);
}
/**
* Writes a packed repeated field: one length-delimited run holding
* every element. `write` writes one element with no tag:
* `(w, v) => w.rawInt32(v)`. Nothing is written for an empty array.
*/
packed<T>(field: i32, values: Array<T>, write: (w: ProtoWriter, value: T) => void): void {
if (values.length == 0) {
return;
}
let run = new ProtoWriter();
for (let value in values) {
write(run, value);
}
this.tag(field, WIRE_LEN);
this.#buffer.writeULEB128(run.#buffer.length);
this.#buffer.writeBuffer(run.#buffer);
}
}
/** An RPC's full name, which a transport turns into a URL path: `/service/method`. */
export final class RpcMethod {
/** The service's full name: `google.firestore.v1.Firestore`. */
service: String;
/** The method's name: `GetDocument`. */
name: String;
new(this.service, this.name);
}
/**
* The headers a call sends besides the ones its transport sets: routing
* parameters, an API key, a request id. Names are lowercase, as HTTP/2
* requires.
*/
export final class RpcMetadata {
#names: GrowableArray<String> = new GrowableArray<String>();
#values: GrowableArray<String> = new GrowableArray<String>();
/** Adds header `name` with `value`. A name may be added more than once. */
add(name: String, value: String): void {
this.#names.push(name);
this.#values.push(value);
}
/** The number of headers added. */
length: i32 {
get { return this.#names.length; }
}
/** The name of the `index`th header. */
name(index: i32): String {
return this.#names[index];
}
/** The value of the `index`th header. */
value(index: i32): String {
return this.#values[index];
}
}
/**
* The supplier of a call's `authorization` header. A transport asks before
* every call, so an implementation can refresh an expiring token.
*/
export interface Credentials {
/** The header's value, such as `Bearer <token>`, or null to send none. */
authorization(): Future<String | null>;
}
/**
* Builds the `x-goog-request-params` header Google's front ends route a
* call by (https://google.aip.dev/client-libraries/4222): `key=value`
* pairs joined with `&`, each value percent-encoded. Generated clients
* fill one from the request.
*/
export final class RoutingHeader {
#keys: GrowableArray<String> = new GrowableArray<String>();
#values: GrowableArray<String> = new GrowableArray<String>();
/** Sets parameter `key` to `value`, replacing an earlier value. An empty value sets nothing. */
add(key: String, value: String): void {
if (value.length == 0) {
return;
}
for (var i = 0; i < this.#keys.length; i += 1) {
if (this.#keys[i] == key) {
this.#values[i] = value;
return;
}
}
this.#keys.push(key);
this.#values.push(value);
}
/**
* Sets parameter `key` to the part of `value` that the variable `key`
* captures in `template`, when `value` matches the template.
*/
match(key: String, template: String, value: String): void {
let captured = matchPathTemplate(template, key, value);
if (captured != null) {
this.add(key, captured);
}
}
/** Adds the header to `metadata`, unless no parameter was set. */
addTo(metadata: RpcMetadata): void {
if (this.#keys.length == 0) {
return;
}
var header = '';
for (var i = 0; i < this.#keys.length; i += 1) {
let pair = `${this.#keys[i]}=${percentEncode(this.#values[i])}`;
header = if (i == 0) pair else `${header}&${pair}`;
}
metadata.add('x-goog-request-params', header);
}
}
/**
* `value` with every byte outside the URL-unreserved set (letters, digits,
* `-`, `.`, `_` and `~`) written as `%XX`.
*/
export function percentEncode(value: String): String {
let hex = '0123456789ABCDEF';
var out = '';
var start = 0;
for (var i = 0; i < value.length; i += 1) {
let b = value.getByteAt(i);
let unreserved = (b >= 0x41 && b <= 0x5A) || (b >= 0x61 && b <= 0x7A) ||
(b >= 0x30 && b <= 0x39) || b == 0x2D || b == 0x2E || b == 0x5F || b == 0x7E;
if (!unreserved) {
out = `${out}${value.sliceBytes(start, i)}%${hex.sliceBytes(b >> 4, (b >> 4) + 1)}${hex.sliceBytes(b & 15, (b & 15) + 1)}`;
start = i + 1;
}
}
return if (start == 0) value else `${out}${value.sliceBytes(start, value.length)}`;
}
/**
* The part of `value` that variable `variable` captures in the path
* template `template`, or null when `value` does not match it or the
* capture is empty. Segments are separated by `/`; `*` matches one
* segment, `**` any number, and `{name=pattern}` captures what `pattern`
* matches (`{name}` alone is `{name=*}`). For example, variable
* `database_id` of `projects/{project}/databases/{database_id}/**` is
* `(default)` in `projects/p/databases/(default)/documents/posts`.
*/
export function matchPathTemplate(template: String, variable: String, value: String): String | null {
let patterns = new GrowableArray<String>();
var captureStart = -1;
var captureEnd = -1;
for (let raw in template.split('/')) {
var segment = raw;
if (segment.startsWith('{')) {
let close = segment.endsWith('}');
let inner = segment.sliceBytes(1, if (close) segment.length - 1 else segment.length);
let parts = inner.split('=');
if (parts[0] == variable) {
captureStart = patterns.length;
}
segment = if (parts.length > 1) parts[1] else '*';
if (close && parts[0] == variable) {
patterns.push(segment);
captureEnd = patterns.length;
continue;
}
} else if (segment.endsWith('}')) {
segment = segment.sliceBytes(0, segment.length - 1);
if (captureStart >= 0 && captureEnd < 0) {
patterns.push(segment);
captureEnd = patterns.length;
continue;
}
}
patterns.push(segment);
}
if (captureStart < 0 || captureEnd < 0) {
return null;
}
let values = value.split('/');
let positions = new FixedArray<i32>(patterns.length + 1, 0);
if (!matchSegments(patterns, 0, values, 0, positions)) {
return null;
}
let from = positions[captureStart];
let to = positions[captureEnd];
if (from >= to) {
return null;
}
var captured = values[from];
for (var i = from + 1; i < to; i += 1) {
captured = `${captured}/${values[i]}`;
}
return if (captured.length == 0) null else captured;
}
/**
* Whether `values[vi..]` matches `patterns[pi..]`, recording in
* `positions[k]` the value index pattern `k` began matching at.
*/
function matchSegments(
patterns: GrowableArray<String>,
pi: i32,
values: FixedArray<String>,
vi: i32,
positions: FixedArray<i32>
): boolean {
positions[pi] = vi;
if (pi == patterns.length) {
return vi == values.length;
}
let pattern = patterns[pi];
if (pattern == '**') {
var k = values.length;
while (k >= vi) {
if (matchSegments(patterns, pi + 1, values, k, positions)) {
positions[pi] = vi;
return true;
}
k -= 1;
}
return false;
}
if (vi >= values.length) {
return false;
}
if (pattern == '*') {
if (values[vi].length == 0) {
return false;
}
} else if (pattern != values[vi]) {
return false;
}
return matchSegments(patterns, pi + 1, values, vi + 1, positions);
}
/**
* Carries encoded requests and responses. A gRPC transport frames them
* over HTTP/2; Google's fallback protocol posts them over HTTP/1.1.
* Generated service clients call this and know nothing of HTTP.
* `metadata` holds headers to send with the call.
*/
export interface ProtoTransport {
/** Sends one request and receives one response. */
unary(method: RpcMethod, request: ProtoView, metadata: RpcMetadata): Future<ProtoView>;
/** Sends one request and receives a stream of responses. */
serverStream(method: RpcMethod, request: ProtoView, metadata: RpcMetadata): AsyncIterator<ProtoView>;
/**
* Sends a stream of requests, all known before the call starts, and
* receives one response.
*/
clientStream(method: RpcMethod, requests: Array<ProtoView>, metadata: RpcMetadata): Future<ProtoView>;
}
/** The responses of a server-streaming call, each wrapped as its generated message type. */
export final class ProtoStream<T> implements AsyncIterator<T>, AsyncIterable<T> {
#inner: AsyncIterator<ProtoView>;
#wrap: (view: ProtoView) => T;
new(inner: AsyncIterator<ProtoView>, wrap: (view: ProtoView) => T) : #inner = inner, #wrap = wrap;
next(): AsyncStep<T> {
match (this.#inner.next()) {
case (1, let view, _): {
return (1, this.#wrap(view), _);
}
case (2, _, let pending): {
return (2, _, this.#later(pending));
}
case _: {
return (0, _, _);
}
}
}
[AsyncIterable.asyncIterator](): AsyncIterator<T> {
return this;
}
async #later(pending: Future<Option<ProtoView>>): Future<Option<T>> {
let next = await pending;
if (next is Some<ProtoView>) {
return some(this.#wrap(next.value));
}
return none;
}
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|