@trevrpc/trevrpc-js 1.0.0 → 1.2.0

package/src/race.js

@@ -0,0 +1,90 @@
+import { cancelled, statusFromTransportError, unavailable } from "./status.js";
+
+/**
+ * Dials `primary`, adds `fallback` once the primary fails or `delayMs` passes, and resolves with
+ * `{ session, transport }` from the first to connect. The loser is abandoned and closed if it
+ * connects anyway. Each candidate is `{ transport, dial(signal) }`.
+ */
+export function dialRace(primary, fallback, { delayMs, signal } = {}) {
+  return new Promise((resolve, reject) => {
+    const attempts = new Map();
+    const errors = [];
+    let settled = false;
+    let fallbackStarted = false;
+    let timer;
+
+    const settle = (winner) => {
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      for (const [candidate, controller] of attempts) {
+        if (candidate !== winner) {
+          controller.abort();
+        }
+      }
+    };
+    const start = (candidate) => {
+      const controller = new AbortController();
+      attempts.set(candidate, controller);
+      let dialing;
+      try {
+        // Dialing starts synchronously, so a session exists as soon as the race begins.
+        dialing = Promise.resolve(candidate.dial(controller.signal));
+      } catch (error) {
+        dialing = Promise.reject(error);
+      }
+      dialing.then(
+        (session) => {
+          if (settled) {
+            closeQuietly(session);
+            return;
+          }
+          settle(candidate);
+          resolve({ session, transport: candidate.transport });
+        },
+        (error) => {
+          attempts.delete(candidate);
+          if (settled) {
+            return;
+          }
+          errors.push(`${candidate.transport}: ${statusFromTransportError(error).message}`);
+          if (candidate === primary) {
+            startFallback();
+          } else if (attempts.size === 0) {
+            settle(null);
+            reject(unavailable(`transport unavailable: ${errors.join("; ")}`));
+          }
+        },
+      );
+    };
+    const startFallback = () => {
+      if (!fallbackStarted && !settled) {
+        fallbackStarted = true;
+        clearTimeout(timer);
+        start(fallback);
+      }
+    };
+    const onAbort = () => {
+      if (!settled) {
+        settle(null);
+        reject(cancelled("connection cancelled", signal.reason));
+      }
+    };
+
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+    start(primary);
+    timer = setTimeout(startFallback, delayMs);
+  });
+}
+
+function closeQuietly(session) {
+  try {
+    session.close();
+  } catch {
+    // The session may already be gone.
+  }
+}

package/src/status.js

@@ -48,7 +48,7 @@ export function codeName(code) {
 }
 
 /** Creates a TrevRPC status error. */
-export function statusError(code, message = "", metadata = {}, cause = undefined) {
+export function statusError(code, message = "", metadata = {}, cause) {
   return new TrevRpcError(code, message, metadata, { cause });
 }
 

package/src/stream-compression.js

@@ -0,0 +1,298 @@
+// Stream compression: each direction of a call may compress its messages with one zstd context
+// that lasts as long as the call, sent as ZSTD_STREAM_MESSAGE frames (see the "Stream Compression"
+// section of the wire format). A client offers it in its REQUEST on methods that allow it, and
+// may compress its requests once the server's ANSWER accepts them, or from the start when it offers
+// optimistically. Contexts hold memory for the whole call, so every channel has a budget for them.
+import { encodeMessage, parseStreamChunk } from "./compression.js";
+import { FrameType } from "./framing.js";
+import { internal, resourceExhausted } from "./status.js";
+import { readVarint, varintLength, writeVarint } from "./varint.js";
+import { StreamCompression } from "./wire.js";
+
+/** The window of every stream context, as a base-2 logarithm: the wire format fixes it at 64 KiB. */
+const StreamWindowLog = 16;
+/** A direction's context starts with this message; earlier ones are compressed per message. */
+const StreamCompressionStart = 3;
+
+/** The default memory budget of one channel's stream contexts, in bytes. */
+export const DefaultStreamCompressionMemory = 64 * 1024 * 1024;
+
+/** The key of a transport's StreamBudget; a Channel sets it from its connect options. */
+export const StreamBudgetKey = Symbol("trevrpc.streamBudget");
+
+/** The memory stream contexts may hold, shared by the calls of one channel. */
+export class StreamBudget {
+  #available;
+
+  constructor(bytes = DefaultStreamCompressionMemory) {
+    if (!(Number.isSafeInteger(bytes) && bytes >= 0)) {
+      throw new TypeError("streamCompressionMemory must be a non-negative integer number of bytes");
+    }
+    this.#available = bytes;
+  }
+
+  /** Whether `bytes` fit now. */
+  fits(bytes) {
+    return bytes <= this.#available;
+  }
+
+  /** Sets aside `bytes`, returning a function that gives them back, or undefined if they do not fit. */
+  reserve(bytes) {
+    if (bytes > this.#available) {
+      return undefined;
+    }
+    this.#available -= bytes;
+    let held = true;
+    return () => {
+      if (held) {
+        held = false;
+        this.#available += bytes;
+      }
+    };
+  }
+}
+
+const defaultBudgets = new WeakMap();
+
+/** The stream budget of a transport: a Channel's own, or a default one per other transport. */
+export function streamBudget(transport) {
+  const budget = transport[StreamBudgetKey];
+  if (budget !== undefined) {
+    return budget;
+  }
+  let fallback = defaultBudgets.get(transport);
+  if (fallback === undefined) {
+    fallback = new StreamBudget();
+    defaultBudgets.set(transport, fallback);
+  }
+  return fallback;
+}
+
+/**
+ * The stream compression of one call on the client. `directions` is `{ requests, responses }`:
+ * the directions the method allows it on. `session` picks dictionaries for request contexts, and
+ * `accept` maps the dictionary IDs the call accepts on its responses to their dictionaries, which
+ * response frames may start from.
+ */
+export class CallStreams {
+  #compression;
+  #budget;
+  #requests;
+  #responses;
+  #session;
+  #requestType;
+  #accept;
+  /** Whether the REQUEST offered stream compression. */
+  #offered = false;
+  /** Whether requests may be stream-compressed: the call is optimistic, or the server accepted. */
+  #requestsEnabled = false;
+  #requestsSent = 0;
+  /** Whether the request direction stays per-message for the rest of the call. */
+  #requestsStopped = false;
+  #encoder;
+  #decoder;
+  /** Whether a response frame is open, so the next non-empty chunk continues it. */
+  #inFrame = false;
+  #closed = false;
+  #releases = [];
+
+  constructor(compression, budget, directions, { session, requestType, accept }) {
+    this.#compression = compression;
+    this.#budget = budget;
+    this.#requests = directions.requests;
+    this.#responses = directions.responses;
+    this.#session = session;
+    this.#requestType = requestType;
+    this.#accept = accept;
+  }
+
+  /**
+   * Sets the REQUEST's `streamCompression` offer, and returns whether it is optimistic. A call
+   * whose responses may be compressed first reserves their decompressing context, and offers
+   * nothing if that does not fit; a call that only compresses requests offers so the server can
+   * answer. With `optimistic`, a call whose requests may be compressed offers optimistically if
+   * the budget has room for their compressing context now: its requests are enabled from the
+   * start, and the server accepts or refuses the call at dispatch.
+   */
+  offer(fields, optimistic = false) {
+    if (this.#responses) {
+      const release = this.#budget.reserve(this.#compression.streamDecoderCost(StreamWindowLog));
+      if (release === undefined) {
+        return false;
+      }
+      this.#releases.push(release);
+    }
+    this.#offered = true;
+    if (
+      optimistic &&
+      this.#requests &&
+      this.#budget.fits(this.#compression.streamEncoderCost(StreamWindowLog))
+    ) {
+      fields.streamCompression = StreamCompression.Optimistic;
+      this.#requestsEnabled = true;
+      return true;
+    }
+    fields.streamCompression = StreamCompression.Enabled;
+    return false;
+  }
+
+  /** Records that the server's ANSWER accepted stream-compressed requests. */
+  accept() {
+    if (this.#offered && this.#requests) {
+      this.#requestsEnabled = true;
+    }
+  }
+
+  /**
+   * Encodes a request message: through the direction's context once it exists, and per message,
+   * with `dictionary`, before. The context starts with the direction's third message if the
+   * server's answer allows it and its memory fits the budget.
+   */
+  encode(body, dictionary) {
+    if (!this.#requests) {
+      return encodeMessage(body, dictionary);
+    }
+    this.#requestsSent += 1;
+    if (
+      this.#encoder === undefined &&
+      !this.#requestsStopped &&
+      this.#requestsEnabled &&
+      this.#requestsSent >= StreamCompressionStart
+    ) {
+      this.#startEncoder();
+    }
+    if (this.#encoder === undefined) {
+      return encodeMessage(body, dictionary);
+    }
+    const chunk = this.#encoder.encode(body);
+    const payload = new Uint8Array(varintLength(body.byteLength) + chunk.byteLength);
+    payload.set(chunk, writeVarint(payload, 0, body.byteLength));
+    return { type: FrameType.ZstdStreamMessage, payload, size: body.byteLength };
+  }
+
+  #startEncoder() {
+    const release = this.#budget.reserve(this.#compression.streamEncoderCost(StreamWindowLog));
+    if (release === undefined) {
+      this.#requestsStopped = true;
+      return;
+    }
+    try {
+      this.#encoder = this.#compression.streamEncoder(
+        this.#session.requestDictionary(this.#requestType),
+        StreamWindowLog,
+      );
+    } catch {
+      release();
+      this.#requestsStopped = true;
+      return;
+    }
+    this.#releases.push(release);
+  }
+
+  /**
+   * Decompresses the payload of a ZSTD_STREAM_MESSAGE frame on the response. A message above
+   * maxSize is ResourceExhausted, found before decompressing; every other fault is Internal, and
+   * the call cannot continue after it.
+   */
+  receive(payload, maxSize) {
+    if (!(this.#offered && this.#responses) || this.#closed) {
+      throw internal("stream-compressed message where stream compression is not enabled");
+    }
+    const size = readVarint(payload, 0);
+    if (size === null || typeof size.value !== "number") {
+      throw internal("invalid ZSTD_STREAM_MESSAGE payload");
+    }
+    if (size.value > maxSize) {
+      throw resourceExhausted(
+        `compressed message of ${size.value} bytes exceeds maximum ${maxSize}`,
+      );
+    }
+    const chunk = payload.subarray(size.next);
+    const info = parseStreamChunk(chunk, !this.#inFrame, StreamWindowLog);
+    let frameDictionary;
+    if (info.startsFrame) {
+      frameDictionary = null;
+      if (info.dictionaryId !== 0) {
+        frameDictionary = this.#accept?.get(info.dictionaryId);
+        if (frameDictionary === undefined) {
+          throw internal(
+            `stream-compressed message uses dictionary ${info.dictionaryId}, which is not accepted`,
+          );
+        }
+      }
+    }
+    let message;
+    try {
+      this.#decoder ??= this.#compression.streamDecoder(StreamWindowLog);
+      message = this.#decoder.decode(chunk, size.value, frameDictionary);
+    } catch {
+      throw internal("invalid ZSTD_STREAM_MESSAGE payload");
+    }
+    if (chunk.byteLength > 0) {
+      this.#inFrame = !info.endsFrame;
+    }
+    return message;
+  }
+
+  /** Frees the call's contexts and returns their memory; every way a call ends gets here. */
+  close() {
+    this.#closed = true;
+    this.#encoder?.close();
+    this.#decoder?.close();
+    this.#encoder = undefined;
+    this.#decoder = undefined;
+    this.#requestsStopped = true;
+    for (const release of this.#releases.splice(0)) {
+      release();
+    }
+  }
+}
+
+/** The most request bytes an optimistic call keeps for a replay. */
+export const MaxReplayBytes = 1 << 20;
+
+/**
+ * The requests an optimistic call has sent while the server has not yet accepted or refused it:
+ * the marshalled messages, before compression, so a refused call can be replayed. They are held
+ * within MaxReplayBytes and the channel's stream budget; a request that does not fit waits for
+ * the decision. `decided` settles with "accepted", "refused" or "ended".
+ */
+export class ReplayCopies {
+  #budget;
+  #bodies = [];
+  #bytes = 0;
+  #releases = [];
+  #resolve;
+  decided = new Promise((resolve) => {
+    this.#resolve = resolve;
+  });
+
+  constructor(budget) {
+    this.#budget = budget;
+  }
+
+  /** Keeps `body`, or returns false if it does not fit; the sender then waits for `decided`. */
+  keep(body) {
+    if (this.#bytes + body.byteLength > MaxReplayBytes) {
+      return false;
+    }
+    const release = this.#budget.reserve(body.byteLength);
+    if (release === undefined) {
+      return false;
+    }
+    this.#releases.push(release);
+    this.#bodies.push(body);
+    this.#bytes += body.byteLength;
+    return true;
+  }
+
+  /** Settles the decision, returns the memory, and returns the kept messages in order. */
+  settle(outcome) {
+    for (const release of this.#releases.splice(0)) {
+      release();
+    }
+    this.#bytes = 0;
+    this.#resolve(outcome);
+    return this.#bodies.splice(0);
+  }
+}

package/src/varint.js

@@ -0,0 +1,73 @@
+// QUIC variable-length integers (RFC 9000 §16), shared by the frame layer and QMux. Values below
+// 2^53 are numbers; larger codepoints are bigints.
+
+const MaxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+
+/** Encoded length of a varint. */
+export function varintLength(value) {
+  if (typeof value === "number" && value >= 0 && value < 0x4000_0000) {
+    return value < 0x40 ? 1 : value < 0x4000 ? 2 : 4;
+  }
+  const v = typeof value === "bigint" ? value : BigInt(value);
+  if (v < 0x40n) {
+    return 1;
+  }
+  if (v < 0x4000n) {
+    return 2;
+  }
+  if (v < 0x4000_0000n) {
+    return 4;
+  }
+  if (v < 0x4000_0000_0000_0000n) {
+    return 8;
+  }
+  throw new RangeError(`varint ${v} exceeds 2^62 - 1`);
+}
+
+/** Writes a varint at offset and returns the offset after it. */
+export function writeVarint(bytes, offset, value) {
+  const length = varintLength(value);
+  if (typeof value === "number" && length < 8 && Number.isInteger(value)) {
+    // Fast path without BigInt for the common small values.
+    let v = value;
+    for (let i = length - 1; i >= 0; i -= 1) {
+      bytes[offset + i] = v % 256;
+      v = Math.floor(v / 256);
+    }
+    bytes[offset] |= [0, 0x40, 0, 0x80][length - 1];
+    return offset + length;
+  }
+  let v = typeof value === "bigint" ? value : BigInt(value);
+  for (let i = length - 1; i >= 0; i -= 1) {
+    bytes[offset + i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  bytes[offset] |= [0, 0x40, 0, 0x80, 0, 0, 0, 0xc0][length - 1];
+  return offset + length;
+}
+
+/**
+ * Reads a varint at offset. Returns `{ value, next }`, or null when the bytes end first. Values
+ * above 2^53 - 1 are bigints.
+ */
+export function readVarint(bytes, offset) {
+  if (offset >= bytes.length) {
+    return null;
+  }
+  const length = 1 << (bytes[offset] >> 6);
+  if (offset + length > bytes.length) {
+    return null;
+  }
+  if (length < 8) {
+    let value = bytes[offset] & 0x3f;
+    for (let i = 1; i < length; i += 1) {
+      value = value * 256 + bytes[offset + i];
+    }
+    return { value, next: offset + length };
+  }
+  let value = BigInt(bytes[offset] & 0x3f);
+  for (let i = 1; i < 8; i += 1) {
+    value = (value << 8n) | BigInt(bytes[offset + i]);
+  }
+  return { value: value <= MaxSafe ? Number(value) : value, next: offset + 8 };
+}

package/src/wire.js

@@ -4,8 +4,6 @@ import { byteView } from "./bytes.js";
 
 export { protobuf };
 
-export const WireVersion = 1;
-
 export const RpcKind = Object.freeze({
   Unary: 0,
   ClientStreaming: 1,
@@ -13,9 +11,11 @@ export const RpcKind = Object.freeze({
   BidirectionalStreaming: 3,
 });
 
-export const RpcStreamFrameKind = Object.freeze({
-  Message: 0,
-  Status: 1,
+/** The values of `RpcRequest.stream_compression`. */
+export const StreamCompression = Object.freeze({
+  None: 0,
+  Enabled: 1,
+  Optimistic: 2,
 });
 
 const wireRoot = protobuf.Root.fromJSON({
@@ -30,38 +30,56 @@ const wireRoot = protobuf.Root.fromJSON({
             BidirectionalStreaming: 3,
           },
         },
-        RpcStreamFrameKind: {
+        StreamCompression: {
           values: {
-            Message: 0,
-            Status: 1,
+            STREAM_COMPRESSION_NONE: 0,
+            STREAM_COMPRESSION_ENABLED: 1,
+            STREAM_COMPRESSION_OPTIMISTIC: 2,
           },
         },
         RpcRequest: {
           fields: {
-            service: { type: "string", id: 1 },
-            method: { type: "string", id: 2 },
-            body: { type: "bytes", id: 3 },
-            metadata: { keyType: "string", type: "bytes", id: 4 },
-            kind: { type: "RpcKind", id: 5 },
-            version: { type: "uint32", id: 6 },
-            timeoutNanos: { type: "uint64", id: 7 },
+            method: { type: "string", id: 1 },
+            metadata: { keyType: "string", type: "bytes", id: 2 },
+            kind: { type: "RpcKind", id: 3 },
+            timeoutNanos: { type: "uint64", id: 4 },
+            datagramFlow: { type: "uint64", id: 5 },
+            acceptDictionaries: { rule: "repeated", type: "uint32", id: 6 },
+            dictionaryQuery: { rule: "repeated", type: "DictionaryInfo", id: 7 },
+            streamCompression: { type: "StreamCompression", id: 8 },
+            connectionMetadata: { type: "ConnectionMetadata", id: 9 },
           },
         },
-        RpcResponse: {
+        RpcHeaders: {
           fields: {
-            status: { type: "uint32", id: 1 },
-            message: { type: "string", id: 2 },
-            body: { type: "bytes", id: 3 },
-            metadata: { keyType: "string", type: "bytes", id: 4 },
+            metadata: { keyType: "string", type: "bytes", id: 1 },
+          },
+        },
+        RpcAnswer: {
+          fields: {
+            dictionaries: { rule: "repeated", type: "DictionaryInfo", id: 1 },
+            streamCompression: { type: "bool", id: 2 },
+            connectionMetadata: { type: "uint32", id: 3 },
+          },
+        },
+        ConnectionMetadata: {
+          fields: {
+            id: { type: "uint32", id: 1 },
+            metadata: { keyType: "string", type: "bytes", id: 2 },
+          },
+        },
+        DictionaryInfo: {
+          fields: {
+            id: { type: "uint32", id: 1 },
+            fingerprint: { type: "bytes", id: 2 },
           },
         },
-        RpcStreamFrame: {
+        RpcStatus: {
           fields: {
-            kind: { type: "RpcStreamFrameKind", id: 1 },
-            status: { type: "uint32", id: 2 },
-            message: { type: "string", id: 3 },
-            body: { type: "bytes", id: 4 },
-            metadata: { keyType: "string", type: "bytes", id: 5 },
+            code: { type: "uint32", id: 1 },
+            message: { type: "string", id: 2 },
+            metadata: { keyType: "string", type: "bytes", id: 3 },
+            refusedStreamCompression: { type: "bool", id: 4 },
           },
         },
       },
@@ -70,8 +88,9 @@ const wireRoot = protobuf.Root.fromJSON({
 });
 
 export const RpcRequest = wireRoot.lookupType("trevrpc.RpcRequest");
-export const RpcResponse = wireRoot.lookupType("trevrpc.RpcResponse");
-export const RpcStreamFrame = wireRoot.lookupType("trevrpc.RpcStreamFrame");
+export const RpcHeaders = wireRoot.lookupType("trevrpc.RpcHeaders");
+export const RpcAnswer = wireRoot.lookupType("trevrpc.RpcAnswer");
+export const RpcStatus = wireRoot.lookupType("trevrpc.RpcStatus");
 
 const MaxFieldNumber = 0x1fffffff;
 const MaxUint32 = 0xffffffffn;

package/src/zstd.d.ts

@@ -0,0 +1,35 @@
+import type { Compression } from "./index.js";
+
+/** A zstd dictionary and the protobuf message types it compresses. */
+export interface DictionaryOptions {
+  /**
+   * The dictionary in zstd's format, as written by `zstd --train`. Its header carries the
+   * Dictionary_ID that identifies it to peers, which must never name different dictionaries.
+   */
+  data: ArrayBuffer | ArrayBufferView;
+  /**
+   * Full names of the protobuf message types the dictionary compresses, such as
+   * "example.v1.Position". A message type may appear in one dictionary only. A dictionary without
+   * messages is still offered to servers, which may compress with it, but the channel never does;
+   * adding a new dictionary that way first lets clients hold it before servers use it.
+   */
+  messages?: readonly string[];
+}
+
+export interface CompressionOptions {
+  /** The dictionaries the channel holds. */
+  dictionaries?: readonly DictionaryOptions[];
+  /**
+   * The zstd level of outgoing messages; defaults to 1. The module keeps only the strategies of
+   * levels 1 to 4, and higher levels fall back to them.
+   */
+  level?: number;
+}
+
+/**
+ * Creates compression settings for `connect()`. It loads libzstd as WebAssembly (about 85 KB
+ * gzipped), digests the dictionaries, and rejects with a TypeError for an invalid dictionary, a
+ * dictionary ID used twice, or a message type in two dictionaries. Settings without dictionaries
+ * enable stream compression and compression without a dictionary alone.
+ */
+export function createCompression(options?: CompressionOptions): Promise<Compression>;