@trevrpc/trevrpc-js 1.1.0 → 1.3.0

package/src/index.d.ts

@@ -53,8 +53,8 @@ export interface CallOptions {
   /** Cancels the call. */
   signal?: AbortSignal;
   /**
-   * Called with the response headers, empty when the server sent none, as soon as the first
-   * response frame arrives. A callback that throws fails the call.
+   * Called with the response headers, empty when the server sent none, as soon as they, the first
+   * message or the final status arrive. A callback that throws fails the call.
    */
   onResponseHeaders?(headers: Metadata): void;
   /**
@@ -82,6 +82,16 @@ export interface DatagramTransport {
   readonly writable?: WritableStream<Uint8Array>;
 }
 
+declare const compressionBrand: unique symbol;
+
+/**
+ * Compression settings, made by `createCompression()` from `@trevrpc/trevrpc-js/zstd`: the zstd
+ * dictionaries a channel holds and the message types each compresses. See `ConnectOptions`.
+ */
+export interface Compression {
+  readonly [compressionBrand]: true;
+}
+
 /**
  * Anything that opens a bidirectional byte stream per call, such as a Channel or WebTransport.
  * Calls to methods that mark a direction unreliable use the `datagrams` of the session that opens
@@ -91,14 +101,17 @@ export interface Transport {
   createBidirectionalStream(): Promise<TransportStream>;
   /** Datagrams of the session that the next stream opens on; absent without datagrams. */
   readonly datagrams?: DatagramTransport;
+  /** Compression settings for calls on this transport; absent without compression. */
+  readonly compression?: Compression;
   /**
-   * Like `createBidirectionalStream()`, but also returns the datagrams of the session that opened
-   * the stream. Transports whose session can change, such as a Channel, implement it so a call
-   * never mixes the stream of one session with the datagrams of another.
+   * Like `createBidirectionalStream()`, but also returns the session that opened the stream.
+   * Calls negotiate dictionaries and open datagram flows per session, so transports whose session
+   * can change, such as a Channel, implement it so a call never mixes the stream of one session
+   * with the state of another.
    */
-  createBidirectionalStreamWithDatagrams?(): Promise<{
+  createBidirectionalStreamWithSession?(): Promise<{
     stream: TransportStream;
-    datagrams?: DatagramTransport;
+    session: { readonly datagrams?: DatagramTransport };
   }>;
 }
 
@@ -124,6 +137,24 @@ export interface RpcMethodDescriptor {
    * 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 {
@@ -148,8 +179,9 @@ export interface ResponseStream<TResponse> extends AsyncIterable<TResponse> {
   /** Settles with the final status, or rejects with the error that ended the call. */
   readonly status: Promise<StreamStatus>;
   /**
-   * The response headers, empty when the server sent none. Settles when the first response frame
-   * arrives, before the first message is received, or rejects with the error that ended the call.
+   * The response headers, empty when the server sent none. Settles when they, the first message or
+   * the final status arrive, before the first message is received, or rejects with the error that
+   * ended the call.
    */
   readonly headers: Promise<Metadata>;
   /** Cancels the call unless it already finished. */
@@ -197,8 +229,9 @@ export interface BidirectionalStreamingCall<TRequest, TResponse> extends AsyncIt
   /** Settles with the final status, or rejects with the error that ended the call. */
   readonly status: Promise<StreamStatus>;
   /**
-   * The response headers, empty when the server sent none. Settles when the first response frame
-   * arrives, before the first message is received, or rejects with the error that ended the call.
+   * The response headers, empty when the server sent none. Settles when they, the first message or
+   * the final status arrive, before the first message is received, or rejects with the error that
+   * ended the call.
    */
   readonly headers: Promise<Metadata>;
   /**
@@ -298,6 +331,25 @@ export interface ConnectOptions {
    * `protocols: ["trevrpc-1"]`, the wire version, which cannot be changed.
    */
   WebTransport?: new (url: string | URL, options?: object) => WebTransportSessionLike;
+  /**
+   * Compresses messages with the dictionaries these settings hold, from `createCompression()` in
+   * `@trevrpc/trevrpc-js/zstd`. Dictionaries are negotiated with the server per session, so a
+   * message whose dictionary the server lacks travels uncompressed. Compression settings also
+   * enable stream compression on methods that allow it, even without dictionaries.
+   */
+  compression?: Compression;
+  /**
+   * The memory, in bytes, the stream compression contexts of this channel's calls may hold.
+   * Defaults to 64 MiB; 0 turns stream compression off. Calls beyond it compress per message.
+   */
+  streamCompressionMemory?: number;
+  /**
+   * Request metadata for all of the channel's calls, such as a bearer token, which crosses each
+   * connection once instead of in every request. A call's own `metadata` wins over an entry with
+   * the same key. Keys are lowercase ASCII and the `trevrpc-` prefix is reserved, as for call
+   * metadata. Replace it with `Channel.setConnectionMetadata()`.
+   */
+  connectionMetadata?: MetadataInput;
   /** Cancels the initial connection attempt only. */
   signal?: AbortSignal;
   /** Receives channel state transitions. */
@@ -336,11 +388,20 @@ export class Channel implements Transport {
   readonly state: ChannelState;
   /** The transport of the current or last session. */
   readonly transport: TransportKind;
+  /** The compression settings from the connect options. */
+  readonly compression?: Compression;
+  /**
+   * Replaces the channel's connection metadata (see `ConnectOptions.connectionMetadata`); empty or
+   * missing metadata removes it. Calls started after this use the new metadata, and each
+   * connection sends it again before referring to it. Throws if it is invalid, and then keeps the
+   * old.
+   */
+  setConnectionMetadata(metadata?: MetadataInput): void;
   createBidirectionalStream(): Promise<TransportStream>;
-  /** Opens a stream together with the datagrams of the session that carries it, if any. */
-  createBidirectionalStreamWithDatagrams(): Promise<{
+  /** Opens a stream together with the session that carries it. */
+  createBidirectionalStreamWithSession(): Promise<{
     stream: TransportStream;
-    datagrams?: DatagramTransport;
+    session: { readonly datagrams?: DatagramTransport };
   }>;
   /** Resolves once the channel is ready, immediately if it already is. */
   waitUntilReady(): Promise<void>;

package/src/qmux/session.js

@@ -66,7 +66,8 @@ export class QMuxWebSocketSession {
   #pending = new FrameWriter();
   #flushScheduled = false;
   #waiters = new Set();
-  #pingReceived = 0;
+  /** The highest QX_PING request sequence received, -1 before the first: a peer may start at 0. */
+  #pingReceived = -1;
   #closedError = null;
   #lastActivity = Date.now();
   #idleTimer;

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/wire.js

@@ -11,6 +11,13 @@ export const RpcKind = Object.freeze({
   BidirectionalStreaming: 3,
 });
 
+/** The values of `RpcRequest.stream_compression`. */
+export const StreamCompression = Object.freeze({
+  None: 0,
+  Enabled: 1,
+  Optimistic: 2,
+});
+
 const wireRoot = protobuf.Root.fromJSON({
   nested: {
     trevrpc: {
@@ -23,25 +30,48 @@ const wireRoot = protobuf.Root.fromJSON({
             BidirectionalStreaming: 3,
           },
         },
+        StreamCompression: {
+          values: {
+            STREAM_COMPRESSION_NONE: 0,
+            STREAM_COMPRESSION_ENABLED: 1,
+            STREAM_COMPRESSION_OPTIMISTIC: 2,
+          },
+        },
         RpcRequest: {
           fields: {
             method: { type: "string", id: 1 },
-            metadata: { keyType: "string", type: "bytes", id: 4 },
-            kind: { type: "RpcKind", id: 5 },
-            timeoutNanos: { type: "uint64", id: 7 },
-            extensions: { rule: "repeated", type: "uint64", id: 8 },
-            datagramFlow: { type: "uint64", id: 9 },
+            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 },
           },
-          // Fields 2 (method name), 3 (request body) and 6 (wire version) must never be reused.
-          reserved: [
-            [2, 3],
-            [6, 6],
-          ],
         },
         RpcHeaders: {
           fields: {
             metadata: { keyType: "string", type: "bytes", id: 1 },
-            extensions: { rule: "repeated", type: "uint64", id: 2 },
+          },
+        },
+        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 },
           },
         },
         RpcStatus: {
@@ -49,6 +79,7 @@ const wireRoot = protobuf.Root.fromJSON({
             code: { type: "uint32", id: 1 },
             message: { type: "string", id: 2 },
             metadata: { keyType: "string", type: "bytes", id: 3 },
+            refusedStreamCompression: { type: "bool", id: 4 },
           },
         },
       },
@@ -58,6 +89,7 @@ const wireRoot = protobuf.Root.fromJSON({
 
 export const RpcRequest = wireRoot.lookupType("trevrpc.RpcRequest");
 export const RpcHeaders = wireRoot.lookupType("trevrpc.RpcHeaders");
+export const RpcAnswer = wireRoot.lookupType("trevrpc.RpcAnswer");
 export const RpcStatus = wireRoot.lookupType("trevrpc.RpcStatus");
 
 const MaxFieldNumber = 0x1fffffff;

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>;