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

38.7 KiB Raw
/**
 * Turns a resolved schema into Zena source.
 *
 * For each message `M` it emits:
 *
 * - `class M`, a view over an encoded message, with one getter per field
 *   that decodes the field when called;
 * - `type MInit`, a record with one presence-optional field per proto
 *   field, and `M.of(init)`, which encodes one;
 * - for each `oneof`, a sealed class with a case per member.
 *
 * A message-typed field holds the field's view class on both sides, so
 * `MInit` never refers to another `Init` record and a message read from
 * one response can be put into the next request as it is.
 *
 * For each enum it emits a Zena enum, and for each service a client class
 * over a `ProtoTransport`. The output imports only the runtime names it
 * uses. See docs/design/protobuf.md.
 */

import {HashMap, HashSet} from 'zena:collections';
import {StringBuilder} from 'zena:core';
import {joinStrings} from './text.zena';
import {MethodDecl, OptionAggregate, OptionDecl, OptionString} from './parser.zena';
import {
  EnumInfo,
  FieldInfo,
  FieldType,
  MessageInfo,
  MethodInfo,
  Scalar,
  Schema,
  SchemaError,
  ServiceInfo
} from './schema.zena';

/** Words a generated member or record field cannot be named; the generator appends `_`. */
let KEYWORDS = new HashSet<String>();

/** Names the generated module imports or relies on, which a generated type must not take. */
let RESERVED_TYPES = new HashSet<String>();

function initNames() {
  if (KEYWORDS.size > 0) {
    return;
  }
  for (let word in [
    'abstract', 'as', 'async', 'await', 'break', 'case', 'catch', 'class', 'continue',
    'declare', 'decorator', 'distinct', 'else', 'enum', 'export', 'extends', 'extension',
    'false', 'final', 'finally', 'for', 'function', 'gen', 'if', 'implements', 'import',
    'in', 'inline', 'interface', 'is', 'let', 'match', 'mixin', 'new', 'null', 'on',
    'opaque', 'operator', 'return', 'sealed', 'static', 'super', 'symbol', 'this', 'throw',
    'true', 'try', 'type', 'using', 'var', 'while', 'with', 'yield'
  ]) {
    KEYWORDS.add(word);
  }
  for (let name in [
    'Array', 'Box', 'ByteArray', 'Error', 'FixedArray', 'Future', 'GrowableArray', 'HashMap',
    'ImmutableArray', 'Iterable', 'Iterator', 'Map', 'MapEntry', 'None', 'Option', 'ProtoBytes',
    'ProtoError', 'ProtoList', 'ProtoMap', 'ProtoMapEntry', 'ProtoStream', 'ProtoTransport',
    'ProtoView', 'ProtoWriter', 'Result', 'RpcMethod', 'Some', 'Step', 'String'
  ]) {
    RESERVED_TYPES.add(name);
  }
}

/** `field_name` as `FieldName`. */
export function pascalCase(name: String): String {
  let out = new StringBuilder();
  var upper = true;
  for (var i = 0; i < name.length; i += 1) {
    let b = name.getByteAt(i);
    if (b == 0x5F) {
      upper = true;
      continue;
    }
    if (upper && b >= 0x61 && b <= 0x7A) {
      out.appendByte(b - 0x20);
    } else {
      out.appendByte(b);
    }
    upper = b >= 0x30 && b <= 0x39;
  }
  return out.toString();
}

/** `field_name` as `fieldName`, as protoc derives JSON names. */
export function camelCase(name: String): String {
  let pascal = pascalCase(name);
  if (pascal.length == 0) {
    return pascal;
  }
  let first = pascal.getByteAt(0);
  if (first >= 0x41 && first <= 0x5A && !(name.getByteAt(0) >= 0x41 && name.getByteAt(0) <= 0x5A)) {
    let out = new StringBuilder();
    out.appendByte(first + 0x20);
    out.append(pascal.sliceBytes(1, pascal.length));
    return out.toString();
  }
  return pascal;
}

/** `GetDocument` as `getDocument`. */
function lowerFirst(name: String) {
  if (name.length == 0) {
    return name;
  }
  let first = name.getByteAt(0);
  if (first < 0x41 || first > 0x5A) {
    return name;
  }
  let out = new StringBuilder();
  out.appendByte(first + 0x20);
  out.append(name.sliceBytes(1, name.length));
  return out.toString();
}

/** `NullValue` as `NULL_VALUE`, for matching enum value prefixes. */
function screamingCase(name: String) {
  let out = new StringBuilder();
  for (var i = 0; i < name.length; i += 1) {
    let b = name.getByteAt(i);
    let isUpper = b >= 0x41 && b <= 0x5A;
    if (isUpper && i > 0) {
      let prev = name.getByteAt(i - 1);
      if ((prev >= 0x61 && prev <= 0x7A) || (prev >= 0x30 && prev <= 0x39)) {
        out.appendByte(0x5F);
      }
    }
    out.appendByte(if (b >= 0x61 && b <= 0x7A) b - 0x20 else b);
  }
  return out.toString();
}

/** `LESS_THAN` as `LessThan`. */
function enumMemberName(value: String) {
  let lower = new StringBuilder();
  for (var i = 0; i < value.length; i += 1) {
    let b = value.getByteAt(i);
    lower.appendByte(if (b >= 0x41 && b <= 0x5A) b + 0x20 else b);
  }
  return pascalCase(lower.toString());
}

function memberName(name: String) {
  return if (KEYWORDS.has(name)) `${name}_` else name;
}

/** Accumulates lines of output at the current indentation. */
final class CodeWriter {
  #out: StringBuilder = new StringBuilder();
  var #indent: i32 = 0;


  line(text: String): void {
    if (text.length > 0) {
      for (var i = 0; i < this.#indent; i += 1) {
        this.#out.append('  ');
      }
      this.#out.append(text);
    }
    this.#out.appendByte(0x0A);
  }

  open(text: String): void {
    this.line(text);
    this.#indent += 1;
  }

  close(text: String): void {
    this.#indent -= 1;
    this.line(text);
  }

  /** A doc comment from proto comment text plus extra paragraphs; nothing when both are empty. */
  doc(comment: String | null, extra: String | null): void {
    let lines = new GrowableArray<String>();
    if (comment != null) {
      for (let line in comment.split('\n')) {
        lines.push(escapeComment(trimEnd(line)));
      }
      while (lines.length > 0 && lines[lines.length - 1].length == 0) {
        lines.pop();
      }
    }
    if (extra != null) {
      if (lines.length > 0) {
        lines.push('');
      }
      lines.push(extra);
    }
    if (lines.length == 0) {
      return;
    }
    if (lines.length == 1) {
      this.line(`/** ${lines[0]} */`);
      return;
    }
    this.line('/**');
    for (let line in lines) {
      this.line(if (line.length == 0) ' *' else ` * ${line}`);
    }
    this.line(' */');
  }

  toString(): String {
    return this.#out.toString();
  }
}

/** `text` without trailing whitespace. */
function trimEnd(text: String): String {
  var end = text.length;
  while (end > 0) {
    let b = text.getByteAt(end - 1);
    if (b != 0x20 && b != 0x09 && b != 0x0D) {
      break;
    }
    end -= 1;
  }
  return text.sliceBytes(0, end);
}

/** `text` with `*\/` broken up, so it cannot end the doc comment it is placed in. */
function escapeComment(text: String): String {
  let parts = text.split('*/');
  if (parts.length == 1) {
    return text;
  }
  var out = parts[0];
  for (var i = 1; i < parts.length; i += 1) {
    out = `${out}*\\/${parts[i]}`;
  }
  return out;
}

/** A generated top-level type, for name assignment. */
final class Named {
  fullName: String;
  package: String;
  message: MessageInfo | null;
  enumInfo: EnumInfo | null;
  /** 0: the nested name; 1: prefixed with the package's last component; 2: with the whole package. */
  var level: i32 = 0;
  new(this.fullName, this.package, this.message, this.enumInfo);

  nameAt(level: i32): String {
    let local = if (this.package.length == 0) this.fullName
      else this.fullName.sliceBytes(this.package.length + 1, this.fullName.length);
    let base = pascalCase(joinStrings(local.split('.'), '_'));
    if (level == 0 || this.package.length == 0) {
      return base;
    }
    let segments = this.package.split('.');
    if (level == 1) {
      return pascalCase(segments[segments.length - 1]) + base;
    }
    return pascalCase(joinStrings(segments, '_')) + base;
  }
}

/**
 * Gives every reached message and enum its Zena name. A type keeps its
 * nested name, `StructuredQueryFieldFilter`, unless that name is reserved
 * or another type has it; then the types outside `primaryPackage` take a
 * prefix from their package until the names are distinct.
 */
function assignNames(schema: Schema, primaryPackage: String) {
  let all = new GrowableArray<Named>();
  for (let m in schema.messageOrder) {
    if (m.reached) {
      all.push(new Named(m.fullName, m.file.package, m, null));
    }
  }
  for (let e in schema.enumOrder) {
    if (e.reached) {
      all.push(new Named(e.fullName, e.file.package, null, e));
    }
  }
  for (var round = 0; round < 3; round += 1) {
    let counts = new HashMap<String, i32>();
    for (let n in all) {
      let name = n.nameAt(n.level);
      counts[name] = counts.getOr(name, 0) + 1;
    }
    var changed = false;
    for (let n in all) {
      let name = n.nameAt(n.level);
      let clashes = counts.getOr(name, 0) > 1;
      let reserved = RESERVED_TYPES.has(name);
      if ((reserved || (clashes && n.package != primaryPackage)) && n.level < 2) {
        n.level += 1;
        changed = true;
      }
    }
    if (!changed) {
      break;
    }
  }
  for (let n in all) {
    let name = n.nameAt(n.level);
    if (n.message != null) {
      (n.message as MessageInfo).zenaName = name;
    } else {
      (n.enumInfo as EnumInfo).zenaName = name;
    }
  }
}

/** The Zena type a scalar reads as. */
function scalarReadType(scalar: i32) {
  if (scalar == (Scalar.Double as i32)) { return 'f64'; }
  if (scalar == (Scalar.Float as i32)) { return 'f32'; }
  if (scalar == (Scalar.Int32 as i32) || scalar == (Scalar.Sint32 as i32) ||
      scalar == (Scalar.Sfixed32 as i32)) { return 'i32'; }
  if (scalar == (Scalar.Int64 as i32) || scalar == (Scalar.Sint64 as i32) ||
      scalar == (Scalar.Sfixed64 as i32)) { return 'i64'; }
  if (scalar == (Scalar.Uint32 as i32) || scalar == (Scalar.Fixed32 as i32)) { return 'u32'; }
  if (scalar == (Scalar.Uint64 as i32) || scalar == (Scalar.Fixed64 as i32)) { return 'u64'; }
  if (scalar == (Scalar.Bool as i32)) { return 'boolean'; }
  if (scalar == (Scalar.String as i32)) { return 'String'; }
  return 'ProtoBytes';
}

/** The runtime method, writer or reader suffix for a scalar: `int32`, `sfixed64`, `string`. */
function scalarMethod(scalar: i32) {
  if (scalar == (Scalar.Double as i32)) { return 'double'; }
  if (scalar == (Scalar.Float as i32)) { return 'float'; }
  if (scalar == (Scalar.Int32 as i32)) { return 'int32'; }
  if (scalar == (Scalar.Int64 as i32)) { return 'int64'; }
  if (scalar == (Scalar.Uint32 as i32)) { return 'uint32'; }
  if (scalar == (Scalar.Uint64 as i32)) { return 'uint64'; }
  if (scalar == (Scalar.Sint32 as i32)) { return 'sint32'; }
  if (scalar == (Scalar.Sint64 as i32)) { return 'sint64'; }
  if (scalar == (Scalar.Fixed32 as i32)) { return 'fixed32'; }
  if (scalar == (Scalar.Fixed64 as i32)) { return 'fixed64'; }
  if (scalar == (Scalar.Sfixed32 as i32)) { return 'sfixed32'; }
  if (scalar == (Scalar.Sfixed64 as i32)) { return 'sfixed64'; }
  if (scalar == (Scalar.Bool as i32)) { return 'bool'; }
  if (scalar == (Scalar.String as i32)) { return 'string'; }
  return 'bytes';
}

function scalarWire(scalar: i32) {
  if (scalar == (Scalar.Double as i32) || scalar == (Scalar.Fixed64 as i32) ||
      scalar == (Scalar.Sfixed64 as i32)) { return 'WIRE_I64'; }
  if (scalar == (Scalar.Float as i32) || scalar == (Scalar.Fixed32 as i32) ||
      scalar == (Scalar.Sfixed32 as i32)) { return 'WIRE_I32'; }
  if (scalar == (Scalar.String as i32) || scalar == (Scalar.Bytes as i32)) { return 'WIRE_LEN'; }
  return 'WIRE_VARINT';
}

function scalarDefault(scalar: i32) {
  if (scalar == (Scalar.Double as i32)) { return '0.0'; }
  if (scalar == (Scalar.Float as i32)) { return '0.0 as f32'; }
  if (scalar == (Scalar.Bool as i32)) { return 'false'; }
  if (scalar == (Scalar.String as i32)) { return "''"; }
  if (scalar == (Scalar.Bytes as i32)) { return 'ProtoBytes.empty()'; }
  return '0';
}

/** Emits one generated module. */
final class Emitter {
  #schema: Schema;
  #out: CodeWriter = new CodeWriter();
  /** Runtime names the output uses, imported at the top. */
  #uses: HashSet<String> = new HashSet<String>();
  /** Every top-level name emitted, with what it was emitted for, to catch clashes. */
  #topNames: HashMap<String, String> = new HashMap<String, String>();
  /** The names of the generated messages, enums and `Init` records, which a oneof case must avoid. */
  #typeNames: HashSet<String> = new HashSet<String>();
  /** Each emitted message's getter names, parallel to its fields, by full name. */
  #getterNames: HashMap<String, GrowableArray<String>> = new HashMap<String, GrowableArray<String>>();

  new(schema: Schema) : #schema = schema {
    for (let m in schema.messageOrder) {
      if (m.reached) {
        this.#typeNames.add(m.zenaName);
        this.#typeNames.add(`${m.zenaName}Init`);
      }
    }
    for (let e in schema.enumOrder) {
      if (e.reached) {
        this.#typeNames.add(e.zenaName);
      }
    }
  }

  /**
   * The case class for oneof member `field`: the message's name and the
   * field's, or the oneof type's name and the field's when the first is a
   * type's name (`TransactionOptions.read_write` beside the nested message
   * `TransactionOptions.ReadWrite`).
   */
  #caseName(m: MessageInfo, field: FieldInfo, oneofType: String): String {
    let short = `${m.zenaName}${pascalCase(field.decl.name)}`;
    return if (this.#typeNames.has(short)) `${oneofType}${pascalCase(field.decl.name)}` else short;
  }

  emit(services: GrowableArray<ServiceInfo>, runtimeImport: String, sources: String): String {
    for (let e in this.#schema.enumOrder) {
      if (e.reached) {
        this.#emitEnum(e);
      }
    }
    for (let m in this.#schema.messageOrder) {
      if (m.reached) {
        this.#emitMessage(m);
      }
    }
    for (let service in services) {
      this.#emitService(service);
    }
    let head = new CodeWriter();
    head.doc(`Generated from ${sources} by the Zena protobuf generator. Do not edit.`, null);
    head.line('');
    let names = new GrowableArray<String>();
    for (let name in this.#uses) {
      names.push(name);
    }
    sortStrings(names);
    if (names.length > 0) {
      head.open('import {');
      for (var i = 0; i < names.length; i += 1) {
        head.line(if (i == names.length - 1) names[i] else `${names[i]},`);
      }
      head.close(`} from '${runtimeImport}';`);
    }
    return head.toString() + this.#out.toString();
  }

  #declare(name: String, what: String): void {
    if (let (true, previous) = this.#topNames.get(name)) {
      throw new SchemaError(`the generated name ${name} is used for both ${previous} and ${what}`);
    }
    this.#topNames[name] = what;
  }

  #use(name: String): String {
    this.#uses.add(name);
    return name;
  }

  #emitEnum(e: EnumInfo): void {
    let out = this.#out;
    this.#declare(e.zenaName, e.fullName);
    let values = e.decl.values;
    let prefix = `${screamingCase(e.decl.name)}_`;
    var strip = values.length > 0;
    for (let value in values) {
      if (!value.name.startsWith(prefix) || value.name.length == prefix.length) {
        strip = false;
      } else {
        let first = value.name.getByteAt(prefix.length);
        if (first >= 0x30 && first <= 0x39) {
          strip = false;
        }
      }
    }
    out.line('');
    out.doc(e.decl.comment, `Protobuf: \`${e.fullName}\`.`);
    out.open(`export enum ${e.zenaName} {`);
    let seen = new HashSet<i32>();
    let members = new GrowableArray<String>();
    let comments = new GrowableArray<String | null>();
    for (let value in values) {
      if (seen.has(value.number)) {
        continue;
      }
      seen.add(value.number);
      let raw = if (strip) value.name.sliceBytes(prefix.length, value.name.length) else value.name;
      members.push(`${enumMemberName(raw)} = ${value.number}`);
      comments.push(value.comment);
    }
    for (var i = 0; i < members.length; i += 1) {
      out.doc(comments[i], null);
      out.line(if (i == members.length - 1) members[i] else `${members[i]},`);
    }
    out.close('}');
  }

  #emitMessage(m: MessageInfo): void {
    let out = this.#out;
    let name = m.zenaName;
    let decl = m.decl;
    this.#declare(name, m.fullName);
    this.#declare(`${name}Init`, `the record of ${m.fullName}`);
    this.#use('ProtoView');

    // Member names, distinct within the class. `protoView` and the statics
    // are claimed first.
    let taken = new HashSet<String>();
    taken.add('protoView');
    taken.add('of');
    taken.add('decode');
    let getters = new GrowableArray<String>();
    for (let field in m.fields) {
      getters.push(claim(taken, memberName(camelCase(field.decl.name))));
    }
    this.#getterNames[m.fullName] = getters;
    let hasGetters = new GrowableArray<String>();
    for (let field in m.fields) {
      hasGetters.push(
        if (needsHas(field)) claim(taken, `has${pascalCase(field.decl.name)}`) else ''
      );
    }
    let oneofGetters = new GrowableArray<String>();
    let oneofTypes = new GrowableArray<String>();
    for (let oneof in decl.oneofs) {
      oneofGetters.push(claim(taken, memberName(camelCase(oneof.name))));
      oneofTypes.push(`${name}${pascalCase(oneof.name)}`);
    }

    for (var o = 0; o < decl.oneofs.length; o += 1) {
      this.#emitOneofType(m, o, oneofTypes[o]);
    }

    out.line('');
    out.doc(
      `The fields of a \`${m.fullName}\` to encode, for \`${name}.of\`.`,
      null
    );
    out.open(`export type ${name}Init = {`);
    for (var i = 0; i < m.fields.length; i += 1) {
      let field = m.fields[i];
      if (field.outputOnly) {
        continue;
      }
      let optional = if (field.required) '' else '?';
      out.line(`${getters[i]}${optional}: ${this.#writeType(field)},`);
    }
    out.close('};');

    out.line('');
    out.doc(decl.comment, `Protobuf: \`${m.fullName}\`.`);
    out.open(`export final class ${name} {`);
    out.line('#m: ProtoView;');
    out.line('');
    out.doc(`A message over \`m\`, which must hold an encoded \`${m.fullName}\`.`, null);
    out.line(`new(m: ProtoView) : #m = m;`);
    out.line('');
    out.doc('Decodes `bytes`. Fields are decoded as they are read.', null);
    out.open(`static decode(bytes: ByteArray): ${name} {`);
    out.line(`return new ${name}(ProtoView.of(bytes));`);
    out.close('}');
    out.line('');
    this.#emitOf(m, getters);
    out.line('');
    out.doc('The encoded message.', null);
    out.open('protoView: ProtoView {');
    out.line('get { return this.#m; }');
    out.close('}');

    for (var i = 0; i < m.fields.length; i += 1) {
      let field = m.fields[i];
      out.line('');
      out.doc(field.decl.comment, null);
      this.#emitGetter(m, field, getters[i]);
      if (hasGetters[i].length > 0) {
        out.line('');
        out.doc(`Whether \`${getters[i]}\` is set.`, null);
        out.open(`${hasGetters[i]}: boolean {`);
        let test = if (field.decl.oneofIndex >= 0)
          `this.#which${pascalCase(decl.oneofs[field.decl.oneofIndex].name)}() == ${field.decl.number}`
          else `this.#m.has(${field.decl.number})`;
        out.line(`get { return ${test}; }`);
        out.close('}');
      }
    }

    for (var o = 0; o < decl.oneofs.length; o += 1) {
      this.#emitOneofGetter(m, o, oneofGetters[o], oneofTypes[o]);
    }
    out.close('}');
  }

  /** The `of` static: encodes an `Init` record, field by field. */
  #emitOf(m: MessageInfo, getters: GrowableArray<String>): void {
    let out = this.#out;
    let name = m.zenaName;
    this.#use('ProtoWriter');
    out.doc(`Encodes \`init\` as a \`${m.fullName}\`.`, null);
    out.open(`static of(init: ${name}Init): ${name} {`);
    out.line('let w = new ProtoWriter();');
    for (var i = 0; i < m.fields.length; i += 1) {
      let field = m.fields[i];
      if (field.outputOnly) {
        continue;
      }
      let local = `f${field.decl.number}`;
      if (field.required) {
        out.line(`let ${local} = init.${getters[i]};`);
        this.#emitWrite(field, local);
      } else {
        out.open(`if (let {${getters[i]} as ${local}} = init) {`);
        this.#emitWrite(field, local);
        out.close('}');
      }
    }
    out.line(`return new ${name}(w.finish());`);
    out.close('}');
  }

  /** The statements that write field `field`, whose value is in `local`. */
  #emitWrite(field: FieldInfo, local: String): void {
    let out = this.#out;
    let n = field.decl.number;
    if (field.isMap) {
      out.open(`for (let entry in ${local}) {`);
      out.line('let e = new ProtoWriter();');
      out.line(`e.${scalarMethod(field.mapKey)}(1, entry.key);`);
      out.line(this.#writeCall('e', 2, field.type, 'entry.value'));
      out.line(`w.message(${n}, e.finish());`);
      out.close('}');
      return;
    }
    if (field.isRepeated) {
      if (field.packed) {
        out.line(`w.packed(${n}, ${local}, ${this.#elementWriter(field.type)});`);
        return;
      }
      out.open(`for (let item in ${local}) {`);
      out.line(this.#writeCall('w', n, field.type, 'item'));
      out.close('}');
      return;
    }
    out.line(this.#writeCall('w', n, field.type, local));
  }

  /** A call that writes one value of `type` as field `n`. */
  #writeCall(writer: String, n: i32, type: FieldType, value: String): String {
    if (type.message != null) {
      return `${writer}.message(${n}, ${value}.protoView);`;
    }
    if (type.enumInfo != null) {
      return `${writer}.int32(${n}, ${value} as i32);`;
    }
    return `${writer}.${scalarMethod(type.scalar)}(${n}, ${value});`;
  }

  /**
   * The element writer `ProtoWriter.packed` takes for a packable type. It
   * is an arrow over a `ProtoWriter` method rather than a function the
   * runtime exports: an imported function used as a value only inside a
   * class method does not compile (see
   * tests/language/execution/imports/let_fn_value_in_class.zena).
   */
  #elementWriter(type: FieldType): String {
    if (type.enumInfo != null) {
      return '(pw, pv) => pw.rawInt32(pv as i32)';
    }
    return `(pw, pv) => pw.raw${pascalCase(scalarMethod(type.scalar))}(pv)`;
  }

  /** The type a getter of `field` returns. */
  #readType(field: FieldInfo): String {
    if (field.isMap) {
      this.#use('ProtoMap');
      return `ProtoMap<${scalarReadType(field.mapKey)}, ${this.#elementReadType(field.type)}>`;
    }
    if (field.isRepeated) {
      this.#use('ProtoList');
      return `ProtoList<${this.#elementReadType(field.type)}>`;
    }
    if (field.type.message != null) {
      return `${(field.type.message as MessageInfo).zenaName} | null`;
    }
    return this.#elementReadType(field.type);
  }

  #elementReadType(type: FieldType): String {
    if (type.message != null) {
      return (type.message as MessageInfo).zenaName;
    }
    if (type.enumInfo != null) {
      return (type.enumInfo as EnumInfo).zenaName;
    }
    let t = scalarReadType(type.scalar);
    if (t == 'ProtoBytes') {
      this.#use('ProtoBytes');
    }
    return t;
  }

  /** The type of `field` in its message's `Init` record. */
  #writeType(field: FieldInfo): String {
    if (field.isMap) {
      return `Map<${scalarReadType(field.mapKey)}, ${this.#elementWriteType(field.type)}>`;
    }
    if (field.isRepeated) {
      return `Array<${this.#elementWriteType(field.type)}>`;
    }
    return this.#elementWriteType(field.type);
  }

  #elementWriteType(type: FieldType): String {
    if (type.scalar == (Scalar.Bytes as i32)) {
      this.#use('ProtoBytes');
      return 'ByteArray | ProtoBytes';
    }
    return this.#elementReadType(type);
  }

  /** An expression reading field `field` from `this.#m`, ignoring any `oneof`. */
  #readExpr(field: FieldInfo): String {
    let n = field.decl.number;
    let type = field.type;
    if (field.isMap) {
      return `this.#m.map(${n}, (e) => e.${scalarMethod(field.mapKey)}(1), (e) => ${this.#entryValue(type)})`;
    }
    if (field.isRepeated) {
      return `this.#m.repeated(${n}, ${this.#use(this.#wireOf(type))}, ${this.#elementReader(type)})`;
    }
    if (type.message != null) {
      return `this.#m.message(${n})`;
    }
    if (type.enumInfo != null) {
      return `this.#m.int32(${n}) as ${(type.enumInfo as EnumInfo).zenaName}`;
    }
    return `this.#m.${scalarMethod(type.scalar)}(${n})`;
  }

  /** How a map entry's value, field 2, is read from entry view `e`. */
  #entryValue(type: FieldType): String {
    if (type.message != null) {
      return `new ${(type.message as MessageInfo).zenaName}(e.messageOrEmpty(2))`;
    }
    if (type.enumInfo != null) {
      return `e.int32(2) as ${(type.enumInfo as EnumInfo).zenaName}`;
    }
    return `e.${scalarMethod(type.scalar)}(2)`;
  }

  #wireOf(type: FieldType): String {
    if (type.message != null) {
      return 'WIRE_LEN';
    }
    if (type.enumInfo != null) {
      return 'WIRE_VARINT';
    }
    return scalarWire(type.scalar);
  }

  /** The element reader `ProtoView.repeated` takes. */
  #elementReader(type: FieldType): String {
    if (type.message != null) {
      return `(v, p) => new ${(type.message as MessageInfo).zenaName}(v.messageAt(p))`;
    }
    if (type.enumInfo != null) {
      return `(v, p) => v.int32At(p) as ${(type.enumInfo as EnumInfo).zenaName}`;
    }
    return `(v, p) => v.${scalarMethod(type.scalar)}At(p)`;
  }

  #emitGetter(m: MessageInfo, field: FieldInfo, getter: String): void {
    let out = this.#out;
    let type = this.#readType(field);
    let oneofIndex = field.decl.oneofIndex;
    let n = field.decl.number;
    out.open(`${getter}: ${type} {`);
    if (field.isMap || field.isRepeated || (oneofIndex < 0 && field.type.message == null)) {
      out.line(`get { return ${this.#readExpr(field)}; }`);
      out.close('}');
      return;
    }
    out.open('get {');
    if (oneofIndex >= 0) {
      let which = `this.#which${pascalCase(m.decl.oneofs[oneofIndex].name)}()`;
      out.open(`if (${which} != ${n}) {`);
      out.line(`return ${this.#defaultOf(field.type)};`);
      out.close('}');
    }
    if (field.type.message != null) {
      out.line(`let m = this.#m.message(${n});`);
      let mname = (field.type.message as MessageInfo).zenaName;
      out.line(`return if (m == null) null else new ${mname}(m as ProtoView);`);
    } else {
      out.line(`return ${this.#readExpr(field)};`);
    }
    out.close('}');
    out.close('}');
  }

  /** What a field reads as when absent, or when another member of its `oneof` is set. */
  #defaultOf(type: FieldType): String {
    if (type.message != null) {
      return 'null';
    }
    if (type.enumInfo != null) {
      return `0 as ${(type.enumInfo as EnumInfo).zenaName}`;
    }
    if (type.scalar == (Scalar.Bytes as i32)) {
      this.#use('ProtoBytes');
    }
    return scalarDefault(type.scalar);
  }

  #emitOneofType(m: MessageInfo, index: i32, typeName: String): void {
    let out = this.#out;
    let oneof = m.decl.oneofs[index];
    this.#declare(typeName, `${m.fullName}.${oneof.name}`);
    let notSet = `${typeName}NotSet`;
    out.line('');
    out.doc(
      oneof.comment,
      `The member of \`${m.fullName}.${oneof.name}\` that is set, as \`${m.zenaName}.${camelCase(oneof.name)}\` reads it.`
    );
    out.open(`export sealed class ${typeName} {`);
    for (let field in m.fields) {
      if (field.decl.oneofIndex != index) {
        continue;
      }
      let caseName = this.#caseName(m, field, typeName);
      this.#declare(caseName, `${m.fullName}.${field.decl.name}`);
      out.line(`case ${caseName}(value: ${this.#elementReadType(field.type)})`);
    }
    this.#declare(notSet, `${m.fullName}.${oneof.name} with no member set`);
    out.line(`case ${notSet}`);
    out.close('}');
  }

  #emitOneofGetter(m: MessageInfo, index: i32, getter: String, typeName: String): void {
    let out = this.#out;
    let oneof = m.decl.oneofs[index];
    let pascal = pascalCase(oneof.name);
    let numbers = new GrowableArray<String>();
    for (let field in m.fields) {
      if (field.decl.oneofIndex == index) {
        numbers.push(`${field.decl.number}`);
      }
    }
    out.line('');
    out.doc(`The member of \`${oneof.name}\` that is set.`, null);
    out.open(`${getter}: ${typeName} {`);
    out.open('get {');
    out.line(`let which = this.#which${pascal}();`);
    for (let field in m.fields) {
      if (field.decl.oneofIndex != index) {
        continue;
      }
      let n = field.decl.number;
      let caseName = this.#caseName(m, field, typeName);
      let value = if (field.type.message != null)
        `new ${(field.type.message as MessageInfo).zenaName}(this.#m.message(${n}) as ProtoView)`
        else this.#readExpr(field);
      out.open(`if (which == ${n}) {`);
      out.line(`return new ${caseName}(${value});`);
      out.close('}');
    }
    out.line(`return new ${typeName}NotSet();`);
    out.close('}');
    out.close('}');
    out.line('');
    out.open(`#which${pascal}(): i32 {`);
    out.line(`return this.#m.whichOf([${joinStrings(numbers, ', ')}]);`);
    out.close('}');
  }

  /**
   * Declares `metadata` for a call to `method`, with the routing header
   * its request's fields give (see `routingParams`). A method that streams
   * requests takes `metadata` as a parameter, and routes by its first
   * request.
   */
  #emitMetadata(method: MethodInfo): void {
    let out = this.#out;
    this.#use('RpcMetadata');
    if (!method.decl.inputStream) {
      out.line('let metadata = new RpcMetadata();');
    }
    let params = routingParams(method.decl);
    if (params.length == 0) {
      return;
    }
    this.#use('RoutingHeader');
    if (method.decl.inputStream) {
      out.open('if (requests.length > 0) {');
      out.line('let request = requests[0];');
    }
    out.line('let routing = new RoutingHeader();');
    var temp = 0;
    for (let param in params) {
      var message = method.input;
      var value = 'request';
      var opened = 0;
      var resolved = true;
      for (var i = 0; i < param.path.length; i += 1) {
        let index = fieldIndexNamed(message, param.path[i]);
        if (index < 0) {
          resolved = false;
          break;
        }
        let field = message.fields[index];
        let last = i == param.path.length - 1;
        if (field.isRepeated || (last && field.type.scalar != (Scalar.String as i32)) ||
            (!last && field.type.message == null) || (i == 0 && field.outputOnly)) {
          resolved = false;
          break;
        }
        let getter = this.#getterNames.getOr(message.fullName, new GrowableArray<String>())[index];
        let local = `r${temp}`;
        temp += 1;
        if (i == 0) {
          if (field.required) {
            out.line(`let ${local} = request.${getter};`);
          } else {
            out.open(`if (let {${getter} as ${local}} = request) {`);
            opened += 1;
          }
        } else if (last) {
          out.line(`let ${local} = ${value}.${getter};`);
        } else {
          out.line(`let ${local} = ${value}.${getter};`);
          out.open(`if (${local} != null) {`);
          opened += 1;
        }
        value = if (!last && i > 0) `(${local} as ${(field.type.message as MessageInfo).zenaName})` else local;
        if (!last) {
          message = field.type.message as MessageInfo;
        }
      }
      if (resolved) {
        if (param.template == null) {
          out.line(`routing.add('${param.key}', ${value});`);
        } else {
          out.line(`routing.match('${param.key}', '${param.template as String}', ${value});`);
        }
      }
      for (var k = 0; k < opened; k += 1) {
        out.close('}');
      }
    }
    out.line('routing.addTo(metadata);');
    if (method.decl.inputStream) {
      out.close('}');
    }
  }

  #emitService(service: ServiceInfo): void {
    let out = this.#out;
    let name = `${service.decl.name}Client`;
    this.#declare(name, service.fullName);
    this.#use('ProtoTransport');
    this.#use('RpcMethod');
    let skipped = new GrowableArray<String>();
    for (let method in service.methods) {
      if (method.decl.inputStream && method.decl.outputStream) {
        skipped.push(`\`${method.decl.name}\``);
      }
    }
    var extra = `A client for \`${service.fullName}\`.`;
    if (skipped.length > 0) {
      extra = `${extra} Not generated, because they stream both ways: ${joinStrings(skipped, ', ')}.`;
    }
    out.line('');
    out.doc(service.decl.comment, extra);
    out.open(`export final class ${name} {`);
    out.line('#transport: ProtoTransport;');
    out.line('');
    out.line('new(transport: ProtoTransport) : #transport = transport;');
    let taken = new HashSet<String>();
    for (let method in service.methods) {
      if (method.decl.inputStream && method.decl.outputStream) {
        continue;
      }
      let methodName = claim(taken, memberName(lowerFirst(method.decl.name)));
      let input = method.input.zenaName;
      let output = method.output.zenaName;
      let rpc = `new RpcMethod('${service.fullName}', '${method.decl.name}')`;
      out.line('');
      out.doc(method.decl.comment, null);
      if (method.decl.outputStream) {
        this.#use('ProtoStream');
        out.open(`${methodName}(request: ${input}Init): ProtoStream<${output}> {`);
        this.#emitMetadata(method);
        out.open(`return new ProtoStream<${output}>(`);
        out.line(`this.#transport.serverStream(${rpc}, ${input}.of(request).protoView, metadata),`);
        out.line(`(view) => new ${output}(view)`);
        out.close(');');
        out.close('}');
      } else if (method.decl.inputStream) {
        this.#use('ProtoView');
        this.#use('RpcMetadata');
        out.open(`async ${methodName}(requests: Array<${input}Init>, metadata: RpcMetadata = new RpcMetadata()): Future<${output}> {`);
        this.#emitMetadata(method);
        out.line('let views = new GrowableArray<ProtoView>();');
        out.open('for (let request in requests) {');
        out.line(`views.push(${input}.of(request).protoView);`);
        out.close('}');
        out.line(`let response = await this.#transport.clientStream(${rpc}, views, metadata);`);
        out.line(`return new ${output}(response);`);
        out.close('}');
      } else {
        out.open(`async ${methodName}(request: ${input}Init): Future<${output}> {`);
        this.#emitMetadata(method);
        out.line(`let response = await this.#transport.unary(${rpc}, ${input}.of(request).protoView, metadata);`);
        out.line(`return new ${output}(response);`);
        out.close('}');
      }
    }
    out.close('}');
  }
}

/**
 * One routing parameter of an RPC (https://google.aip.dev/client-libraries/4222):
 * the header key, the request field path it reads (proto field names),
 * and the path template the value is matched against, or null to send the
 * whole value.
 */
final class RoutingParam {
  key: String;
  path: FixedArray<String>;
  template: String | null;
  new(this.key, this.path, this.template);
}

/**
 * The routing parameters of `method`. A `google.api.routing` annotation
 * lists them explicitly; without one, each variable in the path of the
 * method's `google.api.http` rule is a parameter, keyed and read by its
 * field path and sent whole.
 */
function routingParams(method: MethodDecl): GrowableArray<RoutingParam> {
  let params = new GrowableArray<RoutingParam>();
  for (let option in method.options) {
    if (option.name != '(google.api.routing)' || !(option.value is OptionAggregate)) {
      continue;
    }
    for (let entry in (option.value as OptionAggregate).fields) {
      if (entry.name != 'routing_parameters' || !(entry.value is OptionAggregate)) {
        continue;
      }
      var field = '';
      var template: String | null = null;
      for (let part in (entry.value as OptionAggregate).fields) {
        if (part.value is OptionString) {
          let text = (part.value as OptionString).value;
          if (part.name == 'field') {
            field = text;
          } else if (part.name == 'path_template') {
            template = text;
          }
        }
      }
      if (field.length == 0) {
        continue;
      }
      let key = if (template == null) field else templateVariable(template);
      if (key.length > 0) {
        params.push(new RoutingParam(key, field.split('.'), template));
      }
    }
  }
  if (params.length > 0) {
    return params;
  }
  let path = httpRulePath(method.options);
  if (path == null) {
    return params;
  }
  for (let variable in pathVariables(path)) {
    params.push(new RoutingParam(variable, variable.split('.'), null));
  }
  return params;
}

/** The path of a `google.api.http` rule's main binding, or null. */
function httpRulePath(options: GrowableArray<OptionDecl>): String | null {
  for (let option in options) {
    if (option.name != '(google.api.http)' || !(option.value is OptionAggregate)) {
      continue;
    }
    for (let entry in (option.value as OptionAggregate).fields) {
      let verb = entry.name;
      if ((verb == 'get' || verb == 'put' || verb == 'post' || verb == 'delete' || verb == 'patch') &&
          entry.value is OptionString) {
        return (entry.value as OptionString).value;
      }
    }
  }
  return null;
}

/** The variable names in an HTTP rule path: `parent` and `collection_id` in `/v1/{parent=...}/{collection_id}`. */
function pathVariables(path: String): GrowableArray<String> {
  let names = new GrowableArray<String>();
  var i = 0;
  while (i < path.length) {
    if (path.getByteAt(i) == 0x7B) {
      var end = i + 1;
      while (end < path.length && path.getByteAt(end) != 0x3D && path.getByteAt(end) != 0x7D) {
        end += 1;
      }
      names.push(path.sliceBytes(i + 1, end));
      while (end < path.length && path.getByteAt(end) != 0x7D) {
        end += 1;
      }
      i = end;
    }
    i += 1;
  }
  return names;
}

/** The name of the first variable in a path template: `database_id` in `projects/{project}/databases/{database_id}`. */
function templateVariable(template: String): String {
  let names = pathVariables(template);
  return if (names.length == 0) '' else names[0];
}

/** The index in `message.fields` of the field declared as `name`, or -1. */
function fieldIndexNamed(message: MessageInfo, name: String): i32 {
  for (var i = 0; i < message.fields.length; i += 1) {
    if (message.fields[i].decl.name == name) {
      return i;
    }
  }
  return -1;
}

/** Whether a field gets a `hasX` getter: a scalar or enum whose absence is observable. */
function needsHas(field: FieldInfo): boolean {
  return field.explicitPresence && !field.isRepeated && field.type.message == null;
}

/** `name`, or `name_`, `name__` ... if taken; the result is added to `taken`. */
function claim(taken: HashSet<String>, name: String): String {
  var candidate = name;
  while (taken.has(candidate)) {
    candidate = `${candidate}_`;
  }
  taken.add(candidate);
  return candidate;
}

/** Sorts `names` in place by byte order. */
function sortStrings(names: GrowableArray<String>): void {
  for (var i = 1; i < names.length; i += 1) {
    let item = names[i];
    var j = i - 1;
    while (j >= 0 && names[j].compareTo(item) > 0) {
      names[j + 1] = names[j];
      j -= 1;
    }
    names[j + 1] = item;
  }
}

/**
 * Emits the module for the reached part of `schema`. `primaryPackage`
 * keeps its types' short names when another package's type has the same
 * one. `sources` names the input files in the generated header.
 */
export function emitModule(
  schema: Schema,
  services: GrowableArray<ServiceInfo>,
  primaryPackage: String,
  runtimeImport: String,
  sources: String
): String {
  initNames();
  assignNames(schema, primaryPackage);
  return new Emitter(schema).emit(services, runtimeImport, sources);
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none