@trevrpc/trevrpc-js 1.0.0 → 1.1.0

package/src/generator.js

@@ -89,6 +89,18 @@ message MethodDescriptorProto {
   optional string output_type = 3;
   optional bool client_streaming = 5 [default = false];
   optional bool server_streaming = 6 [default = false];
+  optional MethodOptions options = 4;
+}
+
+// Only the trevrpc.method extension is modelled; protobuf.js keeps every other extension out of
+// the decoded message. The numbers are those of proto/trevrpc/options.proto.
+message MethodOptions {
+  optional TrevrpcMethodOptions trevrpc_method = 58247;
+}
+
+message TrevrpcMethodOptions {
+  optional bool unreliable_requests = 1;
+  optional bool unreliable_responses = 2;
 }
 
 message FileOptions {
@@ -171,7 +183,6 @@ const GeneratedTypeImports = [
   "BidirectionalStreamingCall",
   "ClientStreamingCall",
   "ResponseStream",
-  "UnaryResponse",
 ];
 
 const RESERVED_WORDS = new Set([
@@ -358,10 +369,6 @@ function generateServiceMethod(jsName, method) {
     return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(options = {}) {\n    return this._client.${jsName}(options);\n  }`;
   }
 
-  if (method.kind === "unary") {
-    return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(request, options = {}) {\n    return this._client.${jsName}(request, options);\n  }\n\n  /** Calls the ${method.name} RPC and returns response metadata. */\n  ${jsName}WithResponse(request, options = {}) {\n    return this._client.${jsName}WithResponse(request, options);\n  }`;
-  }
-
   return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(request, options = {}) {\n    return this._client.${jsName}(request, options);\n  }`;
 }
 
@@ -381,7 +388,7 @@ function generateMethodDeclaration(jsName, method, typeNames) {
 
   switch (method.kind) {
     case "unary":
-      return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(request: ${inputType}, options?: CallOptions): Promise<${outputType}>;\n  /** Calls the ${method.name} RPC and returns response metadata. */\n  ${jsName}WithResponse(request: ${inputType}, options?: CallOptions): Promise<UnaryResponse<${outputType}>>;`;
+      return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(request: ${inputType}, options?: CallOptions): Promise<${outputType}>;`;
     case "serverStreaming":
       return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(request: ${inputType}, options?: CallOptions): Promise<ResponseStream<${outputType}>>;`;
     case "clientStreaming":
@@ -401,11 +408,13 @@ function serviceDescriptor(file, service) {
 
   for (const method of service.method ?? []) {
     const jsName = uniqueName(lowerCamelIdentifier(method.name), usedNames);
+    const kind = methodKind(method);
     methods[jsName] = {
       name: method.name,
-      kind: methodKind(method),
+      kind,
       inputType: stripLeadingDot(method.inputType),
       outputType: stripLeadingDot(method.outputType),
+      ...unreliableDirections(`${fullName}.${method.name}`, kind, method.options?.trevrpcMethod),
     };
   }
 
@@ -417,6 +426,31 @@ function serviceDescriptor(file, service) {
   };
 }
 
+/**
+ * The `(trevrpc.method)` flags of a method as descriptor fields, only for the ones that are set.
+ * A flag on a direction that does not stream is an error.
+ */
+function unreliableDirections(methodName, kind, options) {
+  const directions = {};
+  if (options?.unreliableRequests) {
+    if (kind !== "clientStreaming" && kind !== "bidirectionalStreaming") {
+      throw new Error(
+        `${methodName}: unreliable_requests requires a client-streaming or bidirectional method`,
+      );
+    }
+    directions.unreliableRequests = true;
+  }
+  if (options?.unreliableResponses) {
+    if (kind !== "serverStreaming" && kind !== "bidirectionalStreaming") {
+      throw new Error(
+        `${methodName}: unreliable_responses requires a server-streaming or bidirectional method`,
+      );
+    }
+    directions.unreliableResponses = true;
+  }
+  return directions;
+}
+
 function declarationTypeNames(files) {
   const names = new Map();
   const usedNames = new Set();

package/src/index.d.ts

@@ -52,6 +52,17 @@ export interface CallOptions {
   metadata?: MetadataInput;
   /** 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.
+   */
+  onResponseHeaders?(headers: Metadata): void;
+  /**
+   * Called with the trailing metadata of the final status when the call succeeds, before its
+   * result is returned or its response stream ends. A failed call reports its metadata on the
+   * TrevRpcError instead. A callback that throws fails the call.
+   */
+  onResponseMetadata?(metadata: Metadata): void;
 }
 
 export interface TransportStream {
@@ -59,9 +70,36 @@ export interface TransportStream {
   writable: WritableStream<Uint8Array>;
 }
 
-/** Anything that opens a bidirectional byte stream per call, such as a Channel or WebTransport. */
+/**
+ * The datagram side of a WebTransport session (`WebTransport.datagrams`). TrevRPC needs only
+ * `readable`; sending also needs `createWritable()` (or the older `writable`), and
+ * `maxDatagramSize` bounds what is sent as a datagram (1100 bytes if it is missing).
+ */
+export interface DatagramTransport {
+  readonly readable: ReadableStream<Uint8Array>;
+  readonly maxDatagramSize?: number;
+  createWritable?(): WritableStream<Uint8Array>;
+  readonly writable?: WritableStream<Uint8Array>;
+}
+
+/**
+ * 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
+ * their stream, when it has them.
+ */
 export interface Transport {
   createBidirectionalStream(): Promise<TransportStream>;
+  /** Datagrams of the session that the next stream opens on; absent without datagrams. */
+  readonly datagrams?: DatagramTransport;
+  /**
+   * 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.
+   */
+  createBidirectionalStreamWithDatagrams?(): Promise<{
+    stream: TransportStream;
+    datagrams?: DatagramTransport;
+  }>;
 }
 
 export type RpcMethodKind =
@@ -75,6 +113,17 @@ export interface RpcMethodDescriptor {
   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;
 }
 
 export interface RpcServiceDescriptor {
@@ -84,11 +133,6 @@ export interface RpcServiceDescriptor {
   methods: Record<string, RpcMethodDescriptor>;
 }
 
-export interface UnaryResponse<TResponse> {
-  readonly message: TResponse;
-  readonly metadata: Metadata;
-}
-
 /** The final status of a call that ended with OK. */
 export interface StreamStatus {
   readonly code: StatusCode;
@@ -103,29 +147,92 @@ export interface StreamStatus {
 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.
+   */
+  readonly headers: Promise<Metadata>;
   /** Cancels the call unless it already finished. */
   close(reason?: unknown): Promise<void>;
 }
 
 export interface ClientStreamingCall<TRequest, TResponse> {
-  /** Sends one request message. */
+  /**
+   * Sends one request message; the promise settles when the transport accepted it, which applies
+   * backpressure.
+   *
+   * Rejects as soon as the server ends the call before the upload is done: with the server's
+   * `TrevRpcError` if its final status is not OK, even if the server never reads the rest of the
+   * request, and with `Code.Cancelled` if the status is OK (the call succeeded without the rest
+   * of the upload; `closeAndRecv()` returns its response). A response that fails after the
+   * upload stopped, such as a lost connection, is reported instead of a generic closed-stream
+   * error. A failed send is not retried or reported twice: later sends fail the same way, and
+   * `closeAndRecv()` returns the call's outcome.
+   *
+   * Pending sends are rejected too when the call is cancelled or its deadline expires.
+   */
   send(request: TRequest): Promise<void>;
+  /**
+   * Sends every message of `requests`, then closes the request stream. If the server ends the
+   * call first, the rest is not sent and the promise resolves; `closeAndRecv()` reports the
+   * outcome. A send that fails otherwise rejects as `send()` does, and requests that throw cancel
+   * the call and reject with what they threw.
+   */
+  sendAll(requests: Iterable<TRequest> | AsyncIterable<TRequest>): Promise<void>;
   /** Closes the request stream and returns the final response. */
   closeAndRecv(): Promise<TResponse>;
-  /** Closes the request stream and returns the final response with its metadata. */
-  closeAndRecvWithResponse(): Promise<UnaryResponse<TResponse>>;
   /** Cancels the call unless it already finished. */
   close(reason?: unknown): Promise<void>;
 }
 
+/**
+ * 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
+ * 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.
+ */
 export interface BidirectionalStreamingCall<TRequest, TResponse> extends AsyncIterable<TResponse> {
   /** Settles with the final status, or rejects with the error that ended the call. */
   readonly status: Promise<StreamStatus>;
-  /** Sends one request message. */
+  /**
+   * 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.
+   */
+  readonly headers: Promise<Metadata>;
+  /**
+   * Sends one request message; the promise settles when the transport accepted it, which applies
+   * backpressure.
+   *
+   * Rejects as soon as the server ends the call before the upload is done, even if nobody is
+   * calling `recv()` and the server never reads the rest of the request: with the server's
+   * `TrevRpcError` if its final status is not OK, and with `Code.Cancelled` if the status is OK
+   * (`recv()` then returns `undefined` after the responses that were sent). A response that
+   * fails after the upload stopped, such as a lost connection, is reported instead of a generic
+   * closed-stream error. Later sends fail the same way, `closeSend()` resolves, and `recv()` and
+   * `status` report the call's outcome.
+   *
+   * While the request side is open the response is read ahead of `recv()` to find the final
+   * status: at most 32 frames or 1 MiB (plus one frame of at most `maxFrameSize`), after which
+   * reading pauses until `recv()` takes messages. Responses read ahead are delivered in order.
+   *
+   * Pending sends are rejected too when the call is cancelled or its deadline expires.
+   */
   send(request: TRequest): Promise<void>;
+  /**
+   * Sends every message of `requests`, then closes the request stream. If the server ends the
+   * call first, the rest is not sent and the promise resolves; `recv()` and `status` report the
+   * outcome. A send that fails otherwise rejects as `send()` does, and requests that throw cancel
+   * the call and reject with what they threw.
+   */
+  sendAll(requests: Iterable<TRequest> | AsyncIterable<TRequest>): Promise<void>;
   /** Receives the next response message, or undefined after the final OK status. */
   recv(): Promise<TResponse | undefined>;
-  /** Closes the request stream while keeping the response stream readable. */
+  /**
+   * Closes the request stream while keeping the response stream readable. Resolves if the server
+   * already ended the call; its final status is reported by `recv()` and `status`.
+   */
   closeSend(): Promise<void>;
   /** Cancels the call unless it already finished. */
   close(reason?: unknown): Promise<void>;
@@ -151,17 +258,45 @@ export interface WebTransportCertificateHash {
 
 export interface WebTransportSessionLike extends Transport {
   readonly ready: Promise<unknown>;
+  /**
+   * The WebTransport protocol the server selected. An empty or missing value means wire version 1.
+   * Any other value than "trevrpc-1" fails the connection attempt with FailedPrecondition.
+   */
+  readonly protocol?: string;
   readonly closed: Promise<unknown>;
   close(closeInfo?: { closeCode?: number; reason?: string }): void;
 }
 
+/** How a channel reaches the server: WebTransport, or QMux over WebSocket as the fallback. */
+export type TransportKind = "webtransport" | "websocket";
+
 export interface ConnectOptions {
+  /**
+   * Transports to use, in order of preference. The default, `["webtransport", "websocket"]`,
+   * starts QMux over WebSocket once WebTransport fails or has not connected within
+   * `fallbackDelayMs`, and uses whichever is ready first.
+   */
+  transports?: readonly TransportKind[];
+  /** The `wss://` URL of the server's TCP listener. Defaults to `url` with a `wss:` scheme. */
+  webSocketUrl?: string | URL;
+  /** How long WebTransport may take before the WebSocket fallback starts. Defaults to 300. */
+  fallbackDelayMs?: number;
+  /** How long reconnects keep using WebSocket after it won, before trying WebTransport again. */
+  reprobeIntervalMs?: number;
+  /** WebSocket implementation to use instead of the global one. */
+  WebSocket?: new (url: string | URL, protocols?: string | string[]) => WebSocket;
   allowPooling?: boolean;
   congestionControl?: "default" | "low-latency" | "throughput";
   requireUnreliable?: boolean;
-  /** Trusts a self-signed ECDSA certificate (at most 14 days old) by its SHA-256 hash. */
+  /**
+   * Trusts a self-signed ECDSA certificate (at most 14 days old) by its SHA-256 hash. WebTransport
+   * only: the WebSocket fallback needs a certificate the browser trusts.
+   */
   serverCertificateHashes?: readonly WebTransportCertificateHash[];
-  /** WebTransport implementation to use instead of the global one. */
+  /**
+   * WebTransport implementation to use instead of the global one. It is constructed with
+   * `protocols: ["trevrpc-1"]`, the wire version, which cannot be changed.
+   */
   WebTransport?: new (url: string | URL, options?: object) => WebTransportSessionLike;
   /** Cancels the initial connection attempt only. */
   signal?: AbortSignal;
@@ -180,23 +315,33 @@ export interface ChannelStateChange {
   delayMs?: number;
   /** Why the session was lost or the previous attempt failed. */
   error?: unknown;
+  /** The transport of the new session, when it becomes ready. */
+  transport?: TransportKind;
 }
 
-/** Opens a channel to a WebTransport server and waits for its session to be ready. */
+/** Opens a channel to a TrevRPC server and waits for its session to be ready. */
 export function connect(url: string | URL, options?: ConnectOptions): Promise<Channel>;
 
 /**
- * A WebTransport session that reconnects in the background after it is lost. Calls fail fast
- * with Unavailable while it reconnects and are never replayed.
+ * A session that reconnects in the background after it is lost: WebTransport, or QMux over
+ * WebSocket when WebTransport is unavailable or blocked. Calls fail fast with Unavailable while it
+ * reconnects and are never replayed.
  */
 export class Channel implements Transport {
   private constructor();
 
-  /** Opens a channel to a WebTransport server and waits for its session to be ready. */
+  /** Opens a channel to a TrevRPC server and waits for its session to be ready. */
   static connect(url: string | URL, options?: ConnectOptions): Promise<Channel>;
 
   readonly state: ChannelState;
+  /** The transport of the current or last session. */
+  readonly transport: TransportKind;
   createBidirectionalStream(): Promise<TransportStream>;
+  /** Opens a stream together with the datagrams of the session that carries it, if any. */
+  createBidirectionalStreamWithDatagrams(): Promise<{
+    stream: TransportStream;
+    datagrams?: DatagramTransport;
+  }>;
   /** Resolves once the channel is ready, immediately if it already is. */
   waitUntilReady(): Promise<void>;
   /** Stops reconnecting and closes the current session. */

package/src/qmux/frames.js

@@ -0,0 +1,262 @@
+// QMux frames (draft-ietf-quic-qmux-02): the QUIC v1 frames QMux carries plus its own
+// QX_TRANSPORT_PARAMETERS and QX_PING frames.
+import { readVarint, varintLength, writeVarint } from "../varint.js";
+
+export const FrameType = Object.freeze({
+  Padding: 0x00,
+  ResetStream: 0x04,
+  StopSending: 0x05,
+  Stream: 0x08, // through 0x0f
+  MaxData: 0x10,
+  MaxStreamData: 0x11,
+  MaxStreamsBidi: 0x12,
+  MaxStreamsUni: 0x13,
+  DataBlocked: 0x14,
+  StreamDataBlocked: 0x15,
+  StreamsBlockedBidi: 0x16,
+  StreamsBlockedUni: 0x17,
+  ConnectionClose: 0x1c,
+  ApplicationClose: 0x1d,
+  TransportParameters: 0x3f51_5330_0d0a_0d0an,
+  Ping: 0x348c_6752_9ef8_c7bdn,
+  PingResponse: 0x348c_6752_9ef8_c7ben,
+});
+
+const StreamFin = 0x01;
+const StreamLen = 0x02;
+const StreamOff = 0x04;
+
+/** QUIC transport error codes (RFC 9000 §20.1). */
+export const TransportError = Object.freeze({
+  NoError: 0x00,
+  InternalError: 0x01,
+  FlowControlError: 0x03,
+  StreamLimitError: 0x04,
+  StreamStateError: 0x05,
+  FinalSizeError: 0x06,
+  FrameEncodingError: 0x07,
+  TransportParameterError: 0x08,
+  ProtocolViolation: 0x0a,
+});
+
+/** A QMux protocol error that closes the session with a transport CONNECTION_CLOSE. */
+export class QMuxProtocolError extends Error {
+  constructor(code, message, frameType = 0) {
+    super(message);
+    this.name = "QMuxProtocolError";
+    this.code = code;
+    this.frameType = frameType;
+  }
+}
+
+function truncated(frameType) {
+  return new QMuxProtocolError(TransportError.FrameEncodingError, "truncated frame", frameType);
+}
+
+/** Builds the frames of one record. */
+export class FrameWriter {
+  #bytes = new Uint8Array(256);
+  #length = 0;
+
+  get length() {
+    return this.#length;
+  }
+
+  #reserve(extra) {
+    if (this.#length + extra > this.#bytes.length) {
+      const grown = new Uint8Array(Math.max(this.#bytes.length * 2, this.#length + extra));
+      grown.set(this.#bytes.subarray(0, this.#length));
+      this.#bytes = grown;
+    }
+  }
+
+  varint(value) {
+    this.#reserve(8);
+    this.#length = writeVarint(this.#bytes, this.#length, value);
+    return this;
+  }
+
+  bytes(data) {
+    this.#reserve(data.length);
+    this.#bytes.set(data, this.#length);
+    this.#length += data.length;
+    return this;
+  }
+
+  /** Returns the frames written so far and starts over. */
+  take() {
+    const frames = this.#bytes.slice(0, this.#length);
+    this.#length = 0;
+    return frames;
+  }
+}
+
+/** Size of a STREAM frame header carrying `length` bytes at `offset`. */
+export function streamFrameOverhead(streamId, offset, length) {
+  return (
+    1 + varintLength(streamId) + varintLength(length) + (offset > 0 ? varintLength(offset) : 0)
+  );
+}
+
+/** Appends a STREAM frame. It always carries a length so that frames may follow it. */
+export function writeStreamFrame(writer, streamId, offset, data, fin) {
+  let type = FrameType.Stream | StreamLen;
+  if (offset > 0) {
+    type |= StreamOff;
+  }
+  if (fin) {
+    type |= StreamFin;
+  }
+  writer.varint(type).varint(streamId);
+  if (offset > 0) {
+    writer.varint(offset);
+  }
+  return writer.varint(data.length).bytes(data);
+}
+
+export function writeResetStream(writer, streamId, code, finalSize) {
+  return writer.varint(FrameType.ResetStream).varint(streamId).varint(code).varint(finalSize);
+}
+
+export function writeStopSending(writer, streamId, code) {
+  return writer.varint(FrameType.StopSending).varint(streamId).varint(code);
+}
+
+export function writeMaxData(writer, maximum) {
+  return writer.varint(FrameType.MaxData).varint(maximum);
+}
+
+export function writeMaxStreamData(writer, streamId, maximum) {
+  return writer.varint(FrameType.MaxStreamData).varint(streamId).varint(maximum);
+}
+
+/** Appends an application CONNECTION_CLOSE, or a transport one for a QMuxProtocolError. */
+export function writeConnectionClose(writer, { code = 0, reason = "", protocolError } = {}) {
+  const reasonBytes = new TextEncoder().encode(reason).subarray(0, 256);
+  if (protocolError) {
+    writer
+      .varint(FrameType.ConnectionClose)
+      .varint(protocolError.code)
+      .varint(protocolError.frameType);
+  } else {
+    writer.varint(FrameType.ApplicationClose).varint(code);
+  }
+  return writer.varint(reasonBytes.length).bytes(reasonBytes);
+}
+
+export function writePing(writer, type, sequence) {
+  return writer.varint(type).varint(sequence);
+}
+
+/** Decodes the frames of one record; `next()` returns null at its end. */
+export class FrameParser {
+  #bytes;
+  #offset = 0;
+
+  constructor(bytes) {
+    this.#bytes = bytes;
+  }
+
+  #varint(frameType) {
+    const result = readVarint(this.#bytes, this.#offset);
+    if (result === null) {
+      throw truncated(frameType);
+    }
+    this.#offset = result.next;
+    return result.value;
+  }
+
+  /** A varint that must fit a number: offsets, lengths, limits and stream IDs. */
+  #number(frameType) {
+    const value = this.#varint(frameType);
+    if (typeof value === "bigint") {
+      throw new QMuxProtocolError(
+        TransportError.FrameEncodingError,
+        "value exceeds what this endpoint supports",
+        frameType,
+      );
+    }
+    return value;
+  }
+
+  #take(frameType, length) {
+    if (length > this.#bytes.length - this.#offset) {
+      throw truncated(frameType);
+    }
+    const data = this.#bytes.subarray(this.#offset, this.#offset + length);
+    this.#offset += length;
+    return data;
+  }
+
+  next() {
+    if (this.#offset >= this.#bytes.length) {
+      return null;
+    }
+    const type = this.#varint(0);
+    if (typeof type === "bigint") {
+      if (type === FrameType.TransportParameters) {
+        return { type, params: this.#take(type, this.#number(type)) };
+      }
+      if (type === FrameType.Ping || type === FrameType.PingResponse) {
+        return { type, sequence: this.#number(type) };
+      }
+      throw new QMuxProtocolError(
+        TransportError.FrameEncodingError,
+        `frame type 0x${type.toString(16)} is not allowed in QMux`,
+        0,
+      );
+    }
+    switch (type) {
+      case FrameType.Padding:
+        return { type };
+      case FrameType.ResetStream:
+        return {
+          type,
+          streamId: this.#number(type),
+          code: this.#number(type),
+          finalSize: this.#number(type),
+        };
+      case FrameType.StopSending:
+        return { type, streamId: this.#number(type), code: this.#number(type) };
+      case FrameType.MaxData:
+      case FrameType.DataBlocked:
+      case FrameType.MaxStreamsBidi:
+      case FrameType.MaxStreamsUni:
+      case FrameType.StreamsBlockedBidi:
+      case FrameType.StreamsBlockedUni:
+        return { type, maximum: this.#number(type) };
+      case FrameType.MaxStreamData:
+      case FrameType.StreamDataBlocked:
+        return { type, streamId: this.#number(type), maximum: this.#number(type) };
+      case FrameType.ConnectionClose:
+      case FrameType.ApplicationClose: {
+        const code = this.#number(type);
+        const frameType = type === FrameType.ConnectionClose ? this.#varint(type) : undefined;
+        const reason = new TextDecoder().decode(this.#take(type, this.#number(type)));
+        return { type, code, frameType, reason };
+      }
+      default:
+        if (type >= FrameType.Stream && type <= (FrameType.Stream | 0x07)) {
+          return this.#stream(type);
+        }
+        throw new QMuxProtocolError(
+          TransportError.FrameEncodingError,
+          `frame type 0x${type.toString(16)} is not allowed in QMux`,
+          type,
+        );
+    }
+  }
+
+  #stream(type) {
+    const streamId = this.#number(type);
+    const offset = type & StreamOff ? this.#number(type) : 0;
+    const length = type & StreamLen ? this.#number(type) : this.#bytes.length - this.#offset;
+    return {
+      type,
+      streamId,
+      offset,
+      data: this.#take(type, length),
+      fin: (type & StreamFin) !== 0,
+    };
+  }
+}