@trevrpc/trevrpc-js 1.4.0 → 1.6.0

package/src/index.d.ts

@@ -1,139 +1,4 @@
-import type { INamespace, Root } from "protobufjs";
-
-export const protobuf: typeof import("protobufjs");
-
-/**
- * How decoded messages represent 64-bit integer fields: `bigint`, `number` (exact up to 2^53),
- * decimal `string`, or protobuf.js's `long` (a Long object). 64-bit map keys are decimal strings
- * in every representation.
- */
-export type Int64Representation = "bigint" | "number" | "string" | "long";
-
-export interface CreateRootOptions {
-  /**
-   * How calls decode the 64-bit integers of the root's messages; a field's `jstype` option
-   * (`JS_STRING` or `JS_NUMBER`) overrides it. Without it they stay Long objects. Generated code
-   * passes the generator's `int64` option.
-   */
-  int64?: Int64Representation;
-}
-
-/** Creates a protobuf root from a JSON namespace definition. */
-export function createRoot(json: INamespace, options?: CreateRootOptions): Root;
-
-/** A 64-bit integer in any representation, including a Long. */
-type Int64Value = bigint | number | string | { low: number; high: number; unsigned?: boolean };
-
-/** A decoded google.protobuf.Timestamp message. */
-export interface Timestamp {
-  seconds: bigint;
-  nanos: number;
-}
-
-/** A google.protobuf.Timestamp message to send. */
-export interface TimestampInit {
-  seconds?: bigint | number | string;
-  nanos?: number;
-}
-
-/** A decoded google.protobuf.Duration message. */
-export interface Duration {
-  seconds: bigint;
-  nanos: number;
-}
-
-/** A google.protobuf.Duration message to send. */
-export interface DurationInit {
-  seconds?: bigint | number | string;
-  nanos?: number;
-}
-
-/** A decoded google.protobuf.Empty message. */
-export interface Empty {}
-
-/** A google.protobuf.Empty message to send. */
-export interface EmptyInit {}
-
-/** Values of the google.protobuf.NullValue enum. */
-export const NullValue: Readonly<{ NULL_VALUE: 0 }>;
-/** A value of the google.protobuf.NullValue enum. */
-export type NullValue = (typeof NullValue)[keyof typeof NullValue];
-
-/** A decoded google.protobuf.Struct message: a JSON object; see `structToJson`. */
-export interface Struct {
-  fields: Record<string, Value>;
-}
-
-/** A google.protobuf.Struct message to send; see `structFromJson`. */
-export interface StructInit {
-  fields?: Record<string, ValueInit>;
-}
-
-/**
- * A decoded google.protobuf.Value message: a JSON value, which sets one member of the `kind`
- * oneof; see `valueToJson`.
- */
-export interface Value {
-  nullValue: NullValue;
-  numberValue: number;
-  stringValue: string;
-  boolValue: boolean;
-  structValue: Struct | null;
-  listValue: ListValue | null;
-}
-
-/** A google.protobuf.Value message to send; see `valueFromJson`. */
-export interface ValueInit {
-  nullValue?: NullValue;
-  numberValue?: number;
-  stringValue?: string;
-  boolValue?: boolean;
-  structValue?: StructInit | null;
-  listValue?: ListValueInit | null;
-}
-
-/** A decoded google.protobuf.ListValue message: a JSON array. */
-export interface ListValue {
-  values: Value[];
-}
-
-/** A google.protobuf.ListValue message to send. */
-export interface ListValueInit {
-  values?: ValueInit[];
-}
-
-export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
-export type JsonObject = { [key: string]: JsonValue };
-
-/** Returns the Timestamp of a Date, to the millisecond. */
-export function timestampFromDate(date: Date): Timestamp;
-/** Returns the Timestamp of milliseconds since the Unix epoch. */
-export function timestampFromMs(ms: number): Timestamp;
-/** Returns the Date of a Timestamp, whatever the representation of its seconds. */
-export function timestampDate(timestamp: {
-  seconds?: Int64Value | null;
-  nanos?: number | null;
-}): Date;
-/** Returns the milliseconds since the Unix epoch of a Timestamp, rounded down. */
-export function timestampMs(timestamp: {
-  seconds?: Int64Value | null;
-  nanos?: number | null;
-}): number;
-/** Returns the Duration of a number of milliseconds. */
-export function durationFromMs(ms: number): Duration;
-/** Returns the milliseconds of a Duration, rounded towards zero. */
-export function durationMs(duration: {
-  seconds?: Int64Value | null;
-  nanos?: number | null;
-}): number;
-/** Returns the Struct of a JSON object. */
-export function structFromJson(json: JsonObject): StructInit;
-/** Returns the JSON object of a Struct. */
-export function structToJson(struct: StructInit): JsonObject;
-/** Returns the Value of a JSON value. */
-export function valueFromJson(json: JsonValue): ValueInit;
-/** Returns the JSON value of a Value; one with no member of `kind` set is null. */
-export function valueToJson(value: ValueInit): JsonValue;
+import type { DescMessage, DescService, MessageInitShape, MessageShape } from "@bufbuild/protobuf";
 
 export const Code: Readonly<{
   Ok: 0;
@@ -166,6 +31,8 @@ export type Metadata = Record<string, Uint8Array>;
 
 /** Error carrying a TrevRPC status code, message, and metadata. */
 export class TrevRpcError extends Error {
+  /** Always `"TrevRpcError"`, for matching errors by tag, as Effect's `catchTag` does. */
+  readonly _tag: "TrevRpcError";
   readonly code: StatusCode;
   readonly statusMessage: string;
   readonly metadata: Metadata;
@@ -195,7 +62,7 @@ export interface CallOptions {
   onResponseMetadata?(metadata: Metadata): void;
 }
 
-/** The kind of an RPC, as in its generated descriptor. */
+/** The kind of an RPC. */
 export type CallKind = "unary" | "serverStreaming" | "clientStreaming" | "bidirectionalStreaming";
 
 /** What a call interceptor sees of a call before it starts. */
@@ -332,55 +199,6 @@ export interface Transport {
   }>;
 }
 
-export type RpcMethodKind =
-  | "unary"
-  | "clientStreaming"
-  | "serverStreaming"
-  | "bidirectionalStreaming";
-
-export interface RpcMethodDescriptor {
-  name: string;
-  kind: RpcMethodKind;
-  inputType: string;
-  outputType: string;
-  /**
-   * The method marks its streamed request messages unreliable (`unreliable_requests` in the
-   * `trevrpc.method` option). They are sent as WebTransport datagrams when they fit and the
-   * session has datagrams, and may be lost or reordered; otherwise they travel on the stream.
-   */
-  unreliableRequests?: boolean;
-  /**
-   * The method marks its streamed response messages unreliable (`unreliable_responses`). The
-   * client accepts them as datagrams on any session that has them.
-   */
-  unreliableResponses?: boolean;
-  /**
-   * The method's request messages may be stream-compressed (`compression: COMPRESSION_STREAM` in
-   * the `trevrpc.method` option, on a method that streams requests, whose request type has no
-   * field marked `debug_redact`). Calls on a transport with compression then compress them with one zstd
-   * context per call, once the server agrees.
-   */
-  compressStreamRequests?: boolean;
-  /** The method's response messages may be stream-compressed; see `compressStreamRequests`. */
-  compressStreamResponses?: boolean;
-  /**
-   * The method's request messages may be compressed without a dictionary: one at a time, from 256
-   * bytes, where no dictionary applies to their type and the server decodes it. The generator
-   * sets it for `COMPRESSION_MESSAGE` and `COMPRESSION_STREAM`, except for message types with a
-   * field marked `debug_redact`.
-   */
-  compressRequests?: boolean;
-  /** The method's response messages may be compressed without a dictionary; see `compressRequests`. */
-  compressResponses?: boolean;
-}
-
-export interface RpcServiceDescriptor {
-  name: string;
-  fullName: string;
-  exportName: string;
-  methods: Record<string, RpcMethodDescriptor>;
-}
-
 /** The final status of a call that ended with OK. */
 export interface StreamStatus {
   readonly code: StatusCode;
@@ -391,6 +209,9 @@ export interface StreamStatus {
 /**
  * Responses of a server-streaming call. Iteration ends after the final OK status and throws a
  * TrevRpcError for any other outcome. Leaving the loop early cancels the call.
+ *
+ * Buffered messages are delivered without returning to the event loop, so a page that renders a
+ * long stream must yield to let the browser render; see "Rendering long streams" in the guide.
  */
 export interface ResponseStream<TResponse> extends AsyncIterable<TResponse> {
   /** Settles with the final status, or rejects with the error that ended the call. */
@@ -437,12 +258,15 @@ export interface ClientStreamingCall<TRequest, TResponse> {
 }
 
 /**
- * On a method that marks a direction unreliable (`RpcMethodDescriptor.unreliableRequests` or
- * `unreliableResponses`), a call on a session with datagrams may send its request messages, and
+ * On a method whose `trevrpc.method` option marks a direction unreliable (`unreliable_requests` or
+ * `unreliable_responses`), a call on a session with datagrams may send its request messages, and
  * receive its response messages, as datagrams: they can be lost or reordered, never duplicated.
  * Response datagrams are delivered after the response headers, merged with the stream's messages
  * in arrival order, and dropped when the call's queue is full (32 messages or 1 MiB) or the call
  * has ended. Without datagrams, such as over WebSocket, everything stays on the stream.
+ *
+ * Like a `ResponseStream`, iteration delivers buffered messages without returning to the event
+ * loop.
  */
 export interface BidirectionalStreamingCall<TRequest, TResponse> extends AsyncIterable<TResponse> {
   /** Settles with the final status, or rejects with the error that ended the call. */
@@ -490,21 +314,62 @@ export interface BidirectionalStreamingCall<TRequest, TResponse> extends AsyncIt
   close(reason?: unknown): Promise<void>;
 }
 
-export type ServiceClient = Record<
-  string,
-  (requestOrOptions?: unknown, options?: CallOptions) => Promise<unknown>
->;
+/** A unary method of a client: sends one request and resolves with the response. */
+export type UnaryMethod<I extends DescMessage, O extends DescMessage> = (
+  request: MessageInitShape<I>,
+  options?: CallOptions,
+) => Promise<MessageShape<O>>;
+
+/** A server-streaming method of a client: sends one request and resolves with the responses. */
+export type ServerStreamingMethod<I extends DescMessage, O extends DescMessage> = (
+  request: MessageInitShape<I>,
+  options?: CallOptions,
+) => Promise<ResponseStream<MessageShape<O>>>;
+
+/** A client-streaming method of a client: starts a call to send requests on. */
+export type ClientStreamingMethod<I extends DescMessage, O extends DescMessage> = (
+  options?: CallOptions,
+) => Promise<ClientStreamingCall<MessageInitShape<I>, MessageShape<O>>>;
+
+/** A bidirectional-streaming method of a client: starts a call to send and receive on. */
+export type BidirectionalStreamingMethod<I extends DescMessage, O extends DescMessage> = (
+  options?: CallOptions,
+) => Promise<BidirectionalStreamingCall<MessageInitShape<I>, MessageShape<O>>>;
+
+/**
+ * The client of a protobuf-es service descriptor: one function per method, named by its
+ * `localName`. Requests take a message or the init object `create()` takes; responses are
+ * messages.
+ */
+export type Client<S extends DescService> = {
+  [K in keyof S["method"]]: S["method"][K] extends {
+    methodKind: infer Kind;
+    input: infer I extends DescMessage;
+    output: infer O extends DescMessage;
+  }
+    ? Kind extends "unary"
+      ? UnaryMethod<I, O>
+      : Kind extends "server_streaming"
+        ? ServerStreamingMethod<I, O>
+        : Kind extends "client_streaming"
+          ? ClientStreamingMethod<I, O>
+          : Kind extends "bidi_streaming"
+            ? BidirectionalStreamingMethod<I, O>
+            : never
+    : never;
+};
 
 /**
- * Creates a service client from a generated service descriptor. Its calls run the transport's
- * interceptors, then those of `options.interceptors`.
+ * Creates a client for `service`, a service descriptor that protoc-gen-es generates (such as
+ * `GreeterService` from `greeter_pb.js`). The `trevrpc.method` option of each method decides
+ * what its calls send as datagrams and compress; one the method's kind cannot use throws
+ * InvalidArgument. Calls run the transport's interceptors, then those of `options.interceptors`.
  */
-export function createServiceClient<TClient extends ServiceClient = ServiceClient>(
+export function createClient<S extends DescService>(
+  service: S,
   transport: Transport,
-  service: RpcServiceDescriptor,
-  root: Root,
   options?: ClientOptions,
-): TClient;
+): Client<S>;
 
 export interface WebTransportCertificateHash {
   algorithm: string;

package/src/index.js

@@ -1,18 +1,4 @@
 export { fetchServerCertificateHashes } from "./certificate-hashes.js";
 export { Channel, connect, createChannel } from "./channel.js";
-export { createServiceClient } from "./client.js";
+export { createClient } from "./client.js";
 export { Code, TrevRpcError, codeName } from "./status.js";
-export { createRoot, protobuf } from "./wire.js";
-export {
-  NullValue,
-  durationFromMs,
-  durationMs,
-  structFromJson,
-  structToJson,
-  timestampDate,
-  timestampFromDate,
-  timestampFromMs,
-  timestampMs,
-  valueFromJson,
-  valueToJson,
-} from "./wkt.js";

package/src/method-options.js

@@ -0,0 +1,170 @@
+// How a client calls each method of a protobuf-es service descriptor: the method's kind, and what
+// its `(trevrpc.method)` option (proto/trevrpc/options.proto) lets it send as datagrams and
+// compress. protoc-gen-es keeps the option in the descriptors it embeds, where protobuf-es leaves
+// it as an unknown field of the method's options, so it is read from there without the generated
+// extension.
+import { BinaryReader, WireType } from "@bufbuild/protobuf/wire";
+
+import { invalidArgument } from "./status.js";
+
+/** The field number of the `trevrpc.method` extension of google.protobuf.MethodOptions. */
+const MethodOptionField = 58247;
+
+/** `trevrpc.Compression` values. */
+const Compression = Object.freeze({ Unspecified: 0, Message: 1, Stream: 2 });
+
+/** The kind of each protobuf-es `methodKind`, as calls and interceptors name it. */
+const Kinds = Object.freeze({
+  __proto__: null,
+  unary: "unary",
+  server_streaming: "serverStreaming",
+  client_streaming: "clientStreaming",
+  bidi_streaming: "bidirectionalStreaming",
+});
+
+/**
+ * The call settings of `method`, a protobuf-es DescMethod: `{ kind, unreliableRequests,
+ * unreliableResponses, compressRequests, compressResponses, compressStreamRequests,
+ * compressStreamResponses }`, with each flag true only where the option sets it for a direction
+ * that allows it. An option the method's kind cannot use throws InvalidArgument.
+ */
+export function methodSettings(method) {
+  const kind = Kinds[method.methodKind];
+  const name = method.parent?.typeName ? `${method.parent.typeName}.${method.name}` : method.name;
+  if (kind === undefined) {
+    throw invalidArgument(`${name}: unsupported RPC kind ${JSON.stringify(method.methodKind)}`);
+  }
+  const options = trevrpcMethodOptions(method, name);
+  return {
+    kind,
+    ...unreliableDirections(name, kind, options),
+    ...compressionDirections(name, kind, options, method),
+  };
+}
+
+/** The method's `(trevrpc.method)` option, with unset fields false or zero. */
+function trevrpcMethodOptions(method, name) {
+  const options = { unreliableRequests: false, unreliableResponses: false, compression: 0 };
+  for (const field of method.proto?.options?.$unknown ?? []) {
+    if (field.no !== MethodOptionField) {
+      continue;
+    }
+    try {
+      if (field.wireType !== WireType.LengthDelimited) {
+        throw new Error(`wire type ${field.wireType}`);
+      }
+      // A message-typed option may be split over several fields, which merge in order.
+      const reader = new BinaryReader(new BinaryReader(field.data).bytes());
+      while (reader.pos < reader.len) {
+        const [number, wireType] = reader.tag();
+        if (number === 1 || number === 2 || number === 5) {
+          if (wireType !== WireType.Varint) {
+            throw new Error(`field ${number} has wire type ${wireType}`);
+          }
+          if (number === 5) {
+            options.compression = reader.int32();
+          } else {
+            options[number === 1 ? "unreliableRequests" : "unreliableResponses"] = reader.bool();
+          }
+        } else {
+          reader.skip(wireType, number);
+        }
+      }
+    } catch (error) {
+      throw invalidArgument(`${name}: malformed trevrpc.method option: ${error.message}`, error);
+    }
+  }
+  return options;
+}
+
+/** The `unreliable_*` flags that are set; one on a direction that does not stream throws. */
+function unreliableDirections(name, kind, options) {
+  const directions = {};
+  if (options.unreliableRequests) {
+    if (kind !== "clientStreaming" && kind !== "bidirectionalStreaming") {
+      throw invalidArgument(
+        `${name}: unreliable_requests requires a client-streaming or bidirectional method`,
+      );
+    }
+    directions.unreliableRequests = true;
+  }
+  if (options.unreliableResponses) {
+    if (kind !== "serverStreaming" && kind !== "bidirectionalStreaming") {
+      throw invalidArgument(
+        `${name}: unreliable_responses requires a server-streaming or bidirectional method`,
+      );
+    }
+    directions.unreliableResponses = true;
+  }
+  return directions;
+}
+
+/**
+ * The directions `compression` lets compress, leaving out message types with a field marked
+ * `debug_redact`. `COMPRESSION_MESSAGE` compresses messages without a dictionary in both
+ * directions. `COMPRESSION_STREAM` does too, for the messages outside the stream, and
+ * stream-compresses the directions that stream; on a unary method it throws, as does a value this
+ * runtime does not know.
+ */
+function compressionDirections(name, kind, { compression }, method) {
+  if (compression === Compression.Unspecified) {
+    return {};
+  }
+  if (compression !== Compression.Message && compression !== Compression.Stream) {
+    throw invalidArgument(`${name}: unknown compression ${compression}`);
+  }
+  if (compression === Compression.Stream && kind === "unary") {
+    throw invalidArgument(`${name}: COMPRESSION_STREAM requires a streaming method`);
+  }
+  const requests = !hasRedactedField(method.input);
+  const responses = !hasRedactedField(method.output);
+  const directions = {};
+  if (requests) {
+    directions.compressRequests = true;
+  }
+  if (responses) {
+    directions.compressResponses = true;
+  }
+  if (compression === Compression.Stream) {
+    if (requests && (kind === "clientStreaming" || kind === "bidirectionalStreaming")) {
+      directions.compressStreamRequests = true;
+    }
+    if (responses && (kind === "serverStreaming" || kind === "bidirectionalStreaming")) {
+      directions.compressStreamResponses = true;
+    }
+  }
+  return directions;
+}
+
+/** Whether each message type checked so far has a redacted field. */
+const redacted = new WeakMap();
+
+/**
+ * Whether `message`, a DescMessage, has a field marked `debug_redact`, directly or in a
+ * message-typed field (singular, repeated or a map value), however deeply nested.
+ */
+export function hasRedactedField(message) {
+  let found = redacted.get(message);
+  if (found !== undefined) {
+    return found;
+  }
+  // Every message type reachable from this one; a cycle is visited once.
+  const reachable = new Set([message]);
+  found = false;
+  for (const type of reachable) {
+    for (const field of type.fields) {
+      if (field.proto?.options?.debugRedact === true) {
+        found = true;
+        break;
+      }
+      if (field.message !== undefined) {
+        reachable.add(field.message);
+      }
+    }
+    if (found) {
+      break;
+    }
+  }
+  redacted.set(message, found);
+  return found;
+}

package/src/qmux/session.js

@@ -69,6 +69,8 @@ export class QMuxWebSocketSession {
   /** The highest QX_PING request sequence received, -1 before the first: a peer may start at 0. */
   #pingReceived = -1;
   #closedError = null;
+  /** Whether the WebSocket opened with the QMux subprotocol. */
+  #open = false;
   #lastActivity = Date.now();
   #idleTimer;
   #handshakeTimer;
@@ -110,6 +112,20 @@ export class QMuxWebSocketSession {
     );
   }
 
+  /**
+   * How far the session got: "opening" until the WebSocket opens, "handshaking" until the server's
+   * transport parameters arrive, "ready" after them, and "closed" once the session ended.
+   */
+  get stage() {
+    if (this.#closedError) {
+      return "closed";
+    }
+    if (this.#peer !== null) {
+      return "ready";
+    }
+    return this.#open ? "handshaking" : "opening";
+  }
+
   /** Opens a bidirectional stream, waiting for the server's stream limit. */
   async createBidirectionalStream() {
     await this.ready;
@@ -154,6 +170,7 @@ export class QMuxWebSocketSession {
       );
       return;
     }
+    this.#open = true;
     // The transport parameters must be the first frame on the wire.
     writeTransportParameters(this.#pending, {
       initialMaxData: this.#window,

package/src/status.js

@@ -37,6 +37,10 @@ export class TrevRpcError extends Error {
   }
 }
 
+// A discriminant for libraries that match errors by tag, such as Effect's `catchTag`. It is on the
+// prototype, so errors carry no extra own property.
+Object.defineProperty(TrevRpcError.prototype, "_tag", { value: "TrevRpcError" });
+
 /** Converts a number into a known status code, defaulting unknown values to Unknown. */
 export function codeFromNumber(code) {
   return Number.isInteger(code) && code >= 0 && code < CodeNames.length ? code : Code.Unknown;