@trevrpc/trevrpc-js 1.1.0 → 1.2.0

package/src/channel.js

@@ -1,6 +1,8 @@
+import { ConnectionMetadataKey, ConnectionMetadataSource } from "./connection-metadata.js";
 import { QMuxWebSocketSession } from "./qmux/session.js";
 import { dialRace } from "./race.js";
 import { cancelled, failedPrecondition, statusFromTransportError, unavailable } from "./status.js";
+import { StreamBudget, StreamBudgetKey } from "./stream-compression.js";
 
 /**
  * The WebTransport protocol that names wire version 1, offered through the `protocols` constructor
@@ -30,6 +32,7 @@ const DefaultReprobeIntervalMs = 5 * 60_000;
  */
 export class Channel {
   #dial;
+  #compression;
   #onStateChange;
   #session;
   #transport;
@@ -40,11 +43,32 @@ export class Channel {
   /** Opens a channel and waits for its first session; use connect() instead. */
   static async connect(url, options = {}) {
     const dial = sessionDialer(url, options);
-    return new Channel(await dial(options.signal), dial, options.onStateChange);
+    // Checked before dialing, so an invalid option never leaves a session behind.
+    const streamBudget = new StreamBudget(options.streamCompressionMemory);
+    const connectionMetadata = new ConnectionMetadataSource(options.connectionMetadata);
+    return new Channel(await dial(options.signal), dial, {
+      ...options,
+      streamBudget,
+      connectionMetadata,
+    });
   }
 
-  constructor(dialed, dial, onStateChange) {
+  constructor(
+    dialed,
+    dial,
+    {
+      compression,
+      streamBudget = new StreamBudget(),
+      connectionMetadata = new ConnectionMetadataSource(),
+      onStateChange,
+    } = {},
+  ) {
     this.#dial = dial;
+    this.#compression = compression;
+    // The memory budget of the stream compression contexts of this channel's calls.
+    this[StreamBudgetKey] = streamBudget;
+    // The connection metadata every call of this channel carries.
+    this[ConnectionMetadataKey] = connectionMetadata;
     this.#onStateChange = onStateChange;
     this.#adopt(dialed);
   }
@@ -59,6 +83,20 @@ export class Channel {
     return this.#transport;
   }
 
+  /** The compression settings from the connect options, or undefined. */
+  get compression() {
+    return this.#compression;
+  }
+
+  /**
+   * Replaces the channel's connection metadata, which every call carries; empty or missing
+   * metadata removes it. Calls started after this use the new metadata. Throws InvalidArgument if
+   * it is invalid, and then keeps the old.
+   */
+  setConnectionMetadata(metadata) {
+    this[ConnectionMetadataKey].set(metadata);
+  }
+
   /** Opens a bidirectional stream on the current session. */
   createBidirectionalStream() {
     if (this.#state !== "ready") {
@@ -68,19 +106,18 @@ export class Channel {
   }
 
   /**
-   * Opens a bidirectional stream on the current session, together with that session's WebTransport
-   * `datagrams` object, or undefined if the session has none (QMux over WebSocket). Calls that may
-   * use datagrams open their stream here, so their datagram flow belongs to the session that
-   * carries them even if the channel reconnects meanwhile.
+   * Opens a bidirectional stream on the current session, together with that session: the
+   * WebTransport or QMux over WebSocket session, whose `datagrams` are undefined for QMux. Calls
+   * whose setup depends on their session (dictionary negotiation, datagram flows) open their stream
+   * here, so that setup belongs to the session that carries them even if the channel reconnects
+   * meanwhile.
    */
-  createBidirectionalStreamWithDatagrams() {
+  createBidirectionalStreamWithSession() {
     if (this.#state !== "ready") {
       return Promise.reject(unavailable(`channel is ${this.#state}`));
     }
     const session = this.#session;
-    return session
-      .createBidirectionalStream()
-      .then((stream) => ({ stream, datagrams: session.datagrams }));
+    return session.createBidirectionalStream().then((stream) => ({ stream, session }));
   }
 
   /** Resolves once the channel is ready, immediately if it already is. */

package/src/client.js

@@ -1,8 +1,8 @@
-import { Call, defaultCallOptions, mergeCallOptions } from "./call.js";
+import { Call, EarlyOk, defaultCallOptions, mergeCallOptions } from "./call.js";
 import { FrameType, marshalMessage, unmarshalMessage } from "./framing.js";
 import { validateMetadata } from "./metadata.js";
 import { Code, cancelled, internal, statusError } from "./status.js";
-import { RpcHeaders, RpcKind, RpcStatus } from "./wire.js";
+import { RpcAnswer, RpcHeaders, RpcKind, RpcStatus } from "./wire.js";
 
 /** Creates a service client from a generated service descriptor. */
 export function createServiceClient(transport, service, root, options = {}) {
@@ -10,12 +10,18 @@ export function createServiceClient(transport, service, root, options = {}) {
   const client = {};
 
   for (const [jsName, method] of Object.entries(service.methods)) {
+    const requestType = root.lookupType(method.inputType);
+    const responseType = root.lookupType(method.outputType);
     const rpc = {
       // The wire method path, computed once per method rather than per call.
       path: `/${service.fullName}/${method.name}`,
-      requestType: root.lookupType(method.inputType),
-      responseType: root.lookupType(method.outputType),
+      requestType,
+      responseType,
+      // Full protobuf names, which pick the compression dictionaries.
+      types: { request: fullName(requestType), response: fullName(responseType) },
       datagrams: datagramUse(method),
+      compressStream: streamCompressionUse(method),
+      compress: plainCompressionUse(method),
     };
     const resolve = (override) => mergeCallOptions(defaults, override);
 
@@ -46,7 +52,7 @@ export function createServiceClient(transport, service, root, options = {}) {
 /** Calls a unary RPC and returns the decoded response. */
 export async function unaryCall(transport, rpc, request, options) {
   const body = marshalMessage(rpc.requestType, request);
-  const call = await Call.open(transport, requestFields(rpc, RpcKind.Unary), body, options);
+  const call = await Call.open(transport, requestFields(rpc, RpcKind.Unary), body, options, rpc);
   const stream = new BidirectionalStreamingCall(call, rpc, { options });
   // The response decides the outcome, so the request side finishes in the background.
   stream.closeSend().catch(() => {});
@@ -61,7 +67,7 @@ export async function serverStreamingCall(transport, rpc, request, options) {
     requestFields(rpc, RpcKind.ServerStreaming),
     body,
     options,
-    rpc.datagrams,
+    rpc,
   );
   const stream = new BidirectionalStreamingCall(call, rpc, { options });
   stream.closeSend().catch(() => {});
@@ -75,7 +81,7 @@ export async function clientStreamingCall(transport, rpc, options) {
     requestFields(rpc, RpcKind.ClientStreaming),
     undefined,
     options,
-    rpc.datagrams,
+    rpc,
   );
   return new ClientStreamingCall(
     new BidirectionalStreamingCall(call, rpc, { streamsRequest: true, options }),
@@ -89,7 +95,7 @@ export async function bidirectionalStreamingCall(transport, rpc, options) {
     requestFields(rpc, RpcKind.BidirectionalStreaming),
     undefined,
     options,
-    rpc.datagrams,
+    rpc,
   );
   return new BidirectionalStreamingCall(call, rpc, { streamsRequest: true, options });
 }
@@ -146,14 +152,35 @@ function datagramUse({ kind, unreliableRequests, unreliableResponses }) {
   return { send: Boolean(unreliableRequests) && streamsRequest, receive: streamsResponse };
 }
 
-const EarlyOk = "the server completed the call before the request stream ended";
+/**
+ * The directions a method may stream-compress, `{ requests, responses }`, or undefined for none:
+ * those its descriptor marks (the generator leaves out directions that do not stream and message
+ * types with redacted fields), except directions marked unreliable, whose messages mostly travel
+ * as datagrams.
+ */
+function streamCompressionUse({ compressStreamRequests, compressStreamResponses, ...method }) {
+  const requests = Boolean(compressStreamRequests) && !method.unreliableRequests;
+  const responses = Boolean(compressStreamResponses) && !method.unreliableResponses;
+  return requests || responses ? { requests, responses } : undefined;
+}
+
+/**
+ * The directions whose messages a method may compress without a dictionary, `{ requests,
+ * responses }`, or undefined for none: those its descriptor marks (the generator marks both for
+ * `COMPRESSION_MESSAGE` and `COMPRESSION_STREAM`, except message types with redacted fields).
+ */
+function plainCompressionUse({ compressRequests, compressResponses }) {
+  const requests = Boolean(compressRequests);
+  const responses = Boolean(compressResponses);
+  return requests || responses ? { requests, responses } : undefined;
+}
 
 /**
  * A bidirectional-streaming RPC. Messages are received with recv() or async iteration. The call
  * ends with the server's final status: a non-OK status makes recv() throw it, and `status`
  * settles with the final status or the error that ended the call. `headers` resolves once the
- * first response frame arrived; reading it starts that read, so headers are available before the
- * first message.
+ * first response frame after any ANSWER arrived; reading it starts that read, so headers are
+ * available before the first message.
  *
  * While the request side is open, the response is read ahead of recv() (see ReadAheadFrames), so
  * a final status reaches a caller that is only sending. It stops the upload at once: pending and
@@ -163,9 +190,13 @@ const EarlyOk = "the server completed the call before the request stream ended";
  * The final status settles the outcome as soon as it is read. Responses read before it are still
  * delivered in order, and the call's deadline and abort signal no longer apply to it.
  *
- * The call options' `onResponseHeaders` is called with the headers when the first response frame
- * is read, and `onResponseMetadata` with the trailing metadata when the final status is OK. A
- * callback that throws fails the call.
+ * The call options' `onResponseHeaders` is called with the headers when the first frame after
+ * ANSWER is read, and `onResponseMetadata` with the trailing metadata when the final status is
+ * OK. A callback that throws fails the call.
+ *
+ * A call that stream-compresses its requests optimistically and is refused by the server is
+ * replayed without that, transparently: the caller's sends and the response continue on the
+ * replay.
  */
 export class BidirectionalStreamingCall {
   #call;
@@ -195,6 +226,7 @@ export class BidirectionalStreamingCall {
   /** Receivers waiting for a frame. */
   #demand = 0;
   #headersWanted = false;
+  #sawAnswer = false;
   #sawHeaders = false;
   #sawMessage = false;
   /** Settles on every change a waiter may care about. */
@@ -245,8 +277,8 @@ export class BidirectionalStreamingCall {
   }
 
   /**
-   * The response headers, empty when the server sent none. Settles when the first response frame
-   * arrives, or rejects with the error that ended the call first.
+   * The response headers, empty when the server sent none. Settles when the first frame after
+   * ANSWER arrives, or rejects with the error that ended the call first.
    */
   get headers() {
     this.#headersWanted = true;
@@ -454,7 +486,7 @@ export class BidirectionalStreamingCall {
     }
     const error = code === Code.Ok ? undefined : statusError(code, message, metadata);
     this.#terminal = { status: { code, message, metadata }, error };
-    this.#call.finish(error ?? cancelled(EarlyOk));
+    this.#call.finish(error);
     if (error === undefined) {
       this.#outcomeSettled = true;
       this.#resolveStatus({ code, message, metadata });
@@ -490,8 +522,10 @@ export class BidirectionalStreamingCall {
   }
 
   /**
-   * Reads the next MESSAGE or STATUS event, consuming HEADERS on the way. Enforces the response
-   * grammar `[HEADERS] MESSAGE* STATUS`.
+   * Reads the next MESSAGE or STATUS event, consuming ANSWER and HEADERS on the way. Enforces the
+   * response grammar `[ANSWER] [HEADERS] MESSAGE* STATUS`, and that an optimistic call's response
+   * starts with ANSWER or STATUS. A ZSTD_MESSAGE or ZSTD_STREAM_MESSAGE is a MESSAGE,
+   * decompressed. ANSWER is not the headers: they settle with the first frame after it.
    */
   async #readEvent() {
     for (;;) {
@@ -500,7 +534,26 @@ export class BidirectionalStreamingCall {
         throw this.#call.uploadFailure ?? internal("response stream ended before final status");
       }
 
+      if (
+        frame.type !== FrameType.Status &&
+        frame.type !== FrameType.Answer &&
+        this.#call.replayable
+      ) {
+        throw internal("optimistic call answered without an ANSWER frame");
+      }
       switch (frame.type) {
+        case FrameType.Answer: {
+          if (this.#sawAnswer || this.#sawHeaders || this.#sawMessage) {
+            throw internal(
+              this.#sawAnswer
+                ? "duplicate ANSWER frame"
+                : `ANSWER frame after ${this.#sawMessage ? "MESSAGE" : "HEADERS"}`,
+            );
+          }
+          this.#sawAnswer = true;
+          this.#call.learnAnswers(unmarshalMessage(RpcAnswer, frame.payload));
+          continue;
+        }
         case FrameType.Headers: {
           if (this.#sawHeaders || this.#sawMessage) {
             throw internal(
@@ -515,12 +568,25 @@ export class BidirectionalStreamingCall {
           continue;
         }
         case FrameType.Message:
+        case FrameType.ZstdMessage:
+        case FrameType.ZstdStreamMessage: {
+          const payload = this.#call.receivedMessage(frame);
           this.#sawMessage = true;
           this.#settleHeaders({});
           this.#flow?.connect(this.#onDatagram);
-          return frame;
+          return { type: FrameType.Message, payload };
+        }
         case FrameType.Status: {
           const status = unmarshalMessage(RpcStatus, frame.payload);
+          if (status.refusedStreamCompression && this.#call.replayable) {
+            // The server refused the optimistic call before running anything for it: the call
+            // continues on a replay, and its response is read from there.
+            // A call with a datagram flow is never optimistic, but its replay, on a session
+            // that may differ after a reconnect, can get one.
+            await this.#call.replay();
+            this.#flow = this.#rpc.datagrams?.receive ? this.#call.flow : undefined;
+            continue;
+          }
           validateResponseMetadata(status.metadata, "trailing metadata");
           this.#settleHeaders({});
           this.#flow?.connect(this.#onDatagram);
@@ -648,8 +714,8 @@ export class ResponseStream {
   }
 
   /**
-   * The response headers, empty when the server sent none. Settles when the first response frame
-   * arrives, even before the first message is received, or rejects with the call error.
+   * The response headers, empty when the server sent none. Settles when the first frame after
+   * ANSWER arrives, even before the first message is received, or rejects with the call error.
    */
   get headers() {
     return this.#call.headers;
@@ -677,6 +743,11 @@ function requestFields(rpc, kind) {
   return { method: rpc.path, kind };
 }
 
+/** The full name of a protobuf.js message type, without the leading dot. */
+function fullName(type) {
+  return type.fullName.replace(/^\./u, "");
+}
+
 function validateResponseMetadata(metadata, what) {
   try {
     validateMetadata(metadata);

package/src/compression.js

@@ -0,0 +1,330 @@
+// Compressed messages: ZSTD_MESSAGE frames, whose payload is a magicless zstd frame compressed with
+// a dictionary both peers hold or, on methods that allow it, without one, and the chunks of
+// ZSTD_STREAM_MESSAGE frames (see the "Compressed Messages" section of the wire format). The codec itself lives in the `@trevrpc/trevrpc-js/zstd`
+// subpath, so the runtime never loads it unless compression is configured; this module negotiates
+// dictionaries per session, validates payloads, and enforces limits before handing a payload to
+// the codec. Stream compression's per-call state is in stream-compression.js.
+import { byteView } from "./bytes.js";
+import { FrameType } from "./framing.js";
+import { internal, resourceExhausted } from "./status.js";
+
+/**
+ * The compression configuration of a transport, or undefined without one. A Channel carries the
+ * one from its connect options. A configuration without dictionaries still enables stream
+ * compression.
+ */
+export function transportCompression(transport) {
+  return transport.compression ?? undefined;
+}
+
+/**
+ * The smallest message compressed without a dictionary: a smaller one rarely has anything to
+ * compress against within itself.
+ */
+export const PlainMinSize = 256;
+
+const sessions = new WeakMap();
+
+/**
+ * The compression state of one session (one connection) for a configuration. The server's answer
+ * to a query holds for the whole session, so it is cached here and dropped with the session.
+ */
+export function sessionCompression(compression, session) {
+  let bySession = sessions.get(compression);
+  if (bySession === undefined) {
+    bySession = new WeakMap();
+    sessions.set(compression, bySession);
+  }
+  let state = bySession.get(session);
+  if (state === undefined) {
+    state = new SessionCompression(compression);
+    bySession.set(session, state);
+  }
+  return state;
+}
+
+class SessionCompression {
+  #compression;
+  /** The session's shared set, from the server's answer to a query; undefined until one arrives. */
+  #shared;
+  /**
+   * Whether calls on the session stream-compress requests optimistically: from the start, until
+   * the server refuses one, and again once a later call's ANSWER accepts `stream_compression`.
+   */
+  optimisticStreams = true;
+
+  constructor(compression) {
+    this.#compression = compression;
+  }
+
+  /**
+   * The negotiation of one call whose response messages have type `responseType`: the REQUEST
+   * fields it sets, what it accepts on its responses (a Map from dictionary ID to dictionary, 0
+   * for compression without one, which `plainResponses` allows), and whether it queries the
+   * server.
+   */
+  prepare(responseType, plainResponses = false) {
+    const shared = this.#shared;
+    const fields = {};
+    const queried = shared === undefined;
+    if (queried) {
+      fields.dictionaryQuery = this.#compression.query;
+    }
+    // A call that queries may already accept the dictionary it asks about: the server compresses
+    // with it only if its answer confirms it. Compression without a dictionary needs no
+    // confirmation: a server that does not decode it does not send it either.
+    const accept = new Map();
+    const dictionary = this.#compression.dictionaryFor(responseType);
+    if (dictionary !== undefined && (shared === undefined || shared.has(dictionary))) {
+      accept.set(dictionary.id, dictionary);
+    }
+    if (plainResponses) {
+      accept.set(0, this.#compression.plain);
+    }
+    if (accept.size > 0) {
+      fields.acceptDictionaries = [...accept.keys()];
+    }
+    return { fields, accept, queried };
+  }
+
+  /**
+   * Records the server's answer to a query as the session's shared set. The first answer wins;
+   * they all come from one configuration.
+   */
+  learn(answer = []) {
+    if (this.#shared !== undefined) {
+      return;
+    }
+    const shared = new Set();
+    for (const { id = 0, fingerprint } of answer) {
+      // ID 0, which an entry without fields decodes to, is compression without a dictionary.
+      const dictionary = this.#compression.dictionary(id);
+      if (dictionary !== undefined && sameBytes(dictionary.fingerprint, byteView(fingerprint))) {
+        shared.add(dictionary);
+      }
+    }
+    this.#shared = shared;
+  }
+
+  /** The dictionary request messages of type `requestType` may use now, or undefined. */
+  requestDictionary(requestType) {
+    const dictionary = this.#compression.dictionaryFor(requestType);
+    return dictionary !== undefined && this.#shared?.has(dictionary) ? dictionary : undefined;
+  }
+
+  /**
+   * What request messages of type `requestType` are compressed with now: their dictionary, or,
+   * with `plain`, `Compression.plain` once the server has confirmed it decodes compression
+   * without a dictionary; undefined for neither.
+   */
+  requestCompressor(requestType, plain) {
+    const dictionary = this.requestDictionary(requestType);
+    if (dictionary !== undefined || !plain) {
+      return dictionary;
+    }
+    const compressor = this.#compression.plain;
+    return this.#shared?.has(compressor) ? compressor : undefined;
+  }
+}
+
+/**
+ * Encodes a marshalled message as an outgoing message, `{ type, payload, size }`: a ZSTD_MESSAGE
+ * compressed with `dictionary` when that is shorter, and a MESSAGE otherwise, as without one.
+ * Compression without a dictionary (ID 0) applies from PlainMinSize. `size` is the message size,
+ * which limits apply to.
+ */
+export function encodeMessage(body, dictionary) {
+  const worth =
+    dictionary !== undefined && (dictionary.id !== 0 || body.byteLength >= PlainMinSize);
+  const compressed = worth ? dictionary.compress(body) : undefined;
+  return compressed !== undefined && compressed.byteLength < body.byteLength
+    ? { type: FrameType.ZstdMessage, payload: compressed, size: body.byteLength }
+    : { type: FrameType.Message, payload: body, size: body.byteLength };
+}
+
+/**
+ * The message of a received MESSAGE or ZSTD_MESSAGE frame, `{ type, payload }`, decompressed with
+ * what `accept` holds (see inflateMessage).
+ */
+export function receivedMessage({ type, payload }, accept, maxSize) {
+  return type === FrameType.ZstdMessage ? inflateMessage(accept, payload, maxSize) : payload;
+}
+
+/**
+ * Decompresses the payload of a ZSTD_MESSAGE frame received on a response. `accept` maps the
+ * dictionary IDs the call accepts to their dictionaries, 0 for compression without one, or is
+ * undefined for none. A message above maxSize is ResourceExhausted, found before decompressing;
+ * every other fault is Internal.
+ */
+export function inflateMessage(accept, payload, maxSize) {
+  if (accept === undefined || accept.size === 0) {
+    throw internal("compressed message where no dictionary is accepted");
+  }
+  const header = parseZstdHeader(payload);
+  if (header.contentSize > maxSize) {
+    throw resourceExhausted(
+      `compressed message of ${header.contentSize} bytes exceeds maximum ${maxSize}`,
+    );
+  }
+  const dictionary = accept.get(header.dictionaryId);
+  if (dictionary === undefined) {
+    throw internal(
+      header.dictionaryId === 0
+        ? "compressed message without a dictionary, which is not accepted"
+        : `compressed message uses dictionary ${header.dictionaryId}, which is not accepted`,
+    );
+  }
+  let message;
+  try {
+    message = dictionary.decompress(payload, header.contentSize);
+  } catch {
+    // Caught below as a failure; the codec's own error says nothing more.
+  }
+  if (message?.byteLength !== header.contentSize) {
+    throw internal("invalid ZSTD_MESSAGE payload");
+  }
+  return message;
+}
+
+const FcsSizes = [0, 2, 4, 8];
+const DidSizes = [0, 1, 2, 4];
+
+/**
+ * Validates that payload is exactly one magicless zstd frame with a Frame_Content_Size, and
+ * returns its Dictionary_ID (0 if absent or zero: compressed without a dictionary) and content
+ * size as `{ dictionaryId, contentSize }`. It walks the block
+ * headers to find the frame's end, so trailing bytes, a second frame included, are rejected. Block
+ * contents are not checked; decompression does that. A content size beyond 2^53 is approximate,
+ * which only matters for limits it exceeds anyway.
+ */
+export function parseZstdHeader(payload) {
+  const bytes = byteView(payload);
+  const invalid = () => internal("invalid ZSTD_MESSAGE payload");
+  if (bytes.byteLength === 0) {
+    throw invalid();
+  }
+  const descriptor = bytes[0];
+  const fcsFlag = descriptor >> 6;
+  const singleSegment = (descriptor & 0x20) !== 0;
+  const checksum = (descriptor & 0x04) !== 0;
+  const didSize = DidSizes[descriptor & 0x03];
+  const fcsSize = fcsFlag === 0 && singleSegment ? 1 : FcsSizes[fcsFlag];
+  // The reserved bit must be unset.
+  if ((descriptor & 0x08) !== 0 || fcsSize === 0) {
+    throw invalid();
+  }
+  let position = singleSegment ? 1 : 2; // after the Window_Descriptor, if present
+  if (bytes.byteLength < position + didSize + fcsSize) {
+    throw invalid();
+  }
+  const dictionaryId = readLittleEndian(bytes, position, didSize);
+  position += didSize;
+  let contentSize = readLittleEndian(bytes, position, fcsSize);
+  if (fcsSize === 2) {
+    contentSize += 256;
+  }
+  position += fcsSize;
+  for (;;) {
+    const block = nextBlock(bytes, position);
+    if (block === undefined) {
+      throw invalid();
+    }
+    position = block.next;
+    if (block.last) {
+      break;
+    }
+  }
+  if (checksum) {
+    position += 4;
+  }
+  if (position !== bytes.byteLength) {
+    throw invalid();
+  }
+  return { dictionaryId, contentSize };
+}
+
+/**
+ * Validates `chunk`, the zstd data of a ZSTD_STREAM_MESSAGE, and returns
+ * `{ startsFrame, dictionaryId, endsFrame }`. `atFrameStart` says that no frame is open, so a
+ * non-empty chunk must start with a frame header: one without Single_Segment_flag,
+ * Frame_Content_Size_flag, Content_Checksum_flag or the reserved bit, whose window is at most
+ * 2^maxWindowLog. It then walks the block headers: a chunk is whole blocks, and a Last_Block ends
+ * both the chunk and the frame. An empty chunk is an empty message and changes nothing. Block
+ * contents are not checked; decompression does that.
+ */
+export function parseStreamChunk(chunk, atFrameStart, maxWindowLog) {
+  const bytes = byteView(chunk);
+  const invalid = () => internal("invalid ZSTD_STREAM_MESSAGE payload");
+  const result = { startsFrame: false, dictionaryId: 0, endsFrame: false };
+  if (bytes.byteLength === 0) {
+    return result;
+  }
+  let position = 0;
+  if (atFrameStart) {
+    const descriptor = bytes[0];
+    // Frame_Content_Size_flag (bits 7-6), Single_Segment_flag (bit 5), the reserved bit (bit 3) and
+    // Content_Checksum_flag (bit 2) must be unset.
+    if ((descriptor & 0xec) !== 0 || bytes.byteLength < 2) {
+      throw invalid();
+    }
+    const windowDescriptor = bytes[1];
+    const base = 2 ** (10 + (windowDescriptor >> 3));
+    if (base + (base / 8) * (windowDescriptor & 7) > 2 ** maxWindowLog) {
+      throw invalid();
+    }
+    const didSize = DidSizes[descriptor & 0x03];
+    position = 2 + didSize;
+    if (bytes.byteLength < position) {
+      throw invalid();
+    }
+    result.dictionaryId = readLittleEndian(bytes, 2, didSize);
+    result.startsFrame = true;
+  }
+  while (position < bytes.byteLength) {
+    const block = nextBlock(bytes, position);
+    if (block === undefined || (block.last && block.next !== bytes.byteLength)) {
+      throw invalid();
+    }
+    position = block.next;
+    result.endsFrame = block.last;
+  }
+  return result;
+}
+
+/**
+ * Walks the zstd block whose header starts at `position` and returns `{ next, last }`: where the
+ * next block starts and whether this one is the Last_Block. Returns undefined for a reserved block
+ * type or a block that does not fit. Block contents are not checked.
+ */
+function nextBlock(bytes, position) {
+  if (bytes.byteLength - position < 3) {
+    return undefined;
+  }
+  const header = bytes[position] | (bytes[position + 1] << 8) | (bytes[position + 2] << 16);
+  let size = header >>> 3;
+  switch ((header >>> 1) & 0x03) {
+    case 0: // Raw_Block
+    case 2: // Compressed_Block
+      break;
+    case 1: // RLE_Block
+      size = 1;
+      break;
+    default:
+      return undefined;
+  }
+  const next = position + 3 + size;
+  return next > bytes.byteLength ? undefined : { next, last: (header & 1) !== 0 };
+}
+
+/** Reads an unsigned little-endian integer of size bytes as a number. */
+function readLittleEndian(bytes, offset, size) {
+  let value = 0;
+  for (let index = size - 1; index >= 0; index -= 1) {
+    value = value * 256 + bytes[offset + index];
+  }
+  return value;
+}
+
+function sameBytes(a, b) {
+  return a.byteLength === b.byteLength && a.every((byte, index) => byte === b[index]);
+}