@trevrpc/trevrpc-js 1.0.0 → 1.2.0

package/src/generator.js

@@ -62,6 +62,7 @@ message FieldDescriptorProto {
   optional int32 oneof_index = 9;
   optional string json_name = 10;
   optional bool proto3_optional = 17;
+  optional FieldOptions options = 8;
 }
 
 message OneofDescriptorProto {
@@ -89,6 +90,24 @@ 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;
+  // trevrpc.Compression, read as its number so that unknown values reach the check.
+  optional int32 compression = 5;
+}
+
+message FieldOptions {
+  optional bool debug_redact = 16;
 }
 
 message FileOptions {
@@ -171,7 +190,6 @@ const GeneratedTypeImports = [
   "BidirectionalStreamingCall",
   "ClientStreamingCall",
   "ResponseStream",
-  "UnaryResponse",
 ];
 
 const RESERVED_WORDS = new Set([
@@ -225,6 +243,7 @@ export function generate(request) {
     const protoFiles = request.protoFile ?? [];
     const rootJson = buildProtobufJson(protoFiles);
     const typeNames = declarationTypeNames(protoFiles);
+    const redacted = redactedTypes(protoFiles);
     const files = [];
 
     for (const file of protoFiles) {
@@ -235,11 +254,11 @@ export function generate(request) {
       const fileName = outputFileName(file.name, options.fileSuffix);
       files.push({
         name: fileName,
-        content: generateFile(file, rootJson, options),
+        content: generateFile(file, rootJson, redacted, options),
       });
       files.push({
         name: declarationFileName(fileName),
-        content: generateDeclarationFile(protoFiles, file, typeNames, options),
+        content: generateDeclarationFile(protoFiles, file, typeNames, redacted, options),
       });
     }
 
@@ -312,8 +331,10 @@ export function buildProtobufJson(files) {
   return root;
 }
 
-function generateFile(file, rootJson, options) {
-  const services = (file.service ?? []).map((service) => serviceDescriptor(file, service));
+function generateFile(file, rootJson, redacted, options) {
+  const services = (file.service ?? []).map((service) =>
+    serviceDescriptor(file, service, redacted),
+  );
   const serviceExports = services.map((service) => generateService(service)).join("\n");
 
   return `// Code generated by protoc-gen-trevrpc-js. DO NOT EDIT.\n\nimport { createRoot, createServiceClient } from ${JSON.stringify(
@@ -321,13 +342,13 @@ function generateFile(file, rootJson, options) {
   )};\n\nexport const root = createRoot(${JSON.stringify(rootJson, null, 2)});\n\n${serviceExports}`;
 }
 
-function generateDeclarationFile(protoFiles, file, typeNames, options) {
+function generateDeclarationFile(protoFiles, file, typeNames, redacted, options) {
   const messages = collectMessages(protoFiles)
     .filter(({ message }) => !message.options?.mapEntry)
     .map((message) => generateMessageDeclaration(message, typeNames))
     .join("\n\n");
   const services = (file.service ?? [])
-    .map((service) => serviceDescriptor(file, service))
+    .map((service) => serviceDescriptor(file, service, redacted))
     .map((service) => generateServiceDeclaration(service, typeNames))
     .join("\n\n");
   const sections = [messages, services].filter(Boolean).join("\n\n");
@@ -358,10 +379,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 +398,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":
@@ -393,7 +410,7 @@ function generateMethodDeclaration(jsName, method, typeNames) {
   }
 }
 
-function serviceDescriptor(file, service) {
+function serviceDescriptor(file, service, redacted) {
   const fullName =
     file.package === "" || file.package == null ? service.name : `${file.package}.${service.name}`;
   const methods = {};
@@ -401,11 +418,18 @@ function serviceDescriptor(file, service) {
 
   for (const method of service.method ?? []) {
     const jsName = uniqueName(lowerCamelIdentifier(method.name), usedNames);
+    const kind = methodKind(method);
+    const inputType = stripLeadingDot(method.inputType);
+    const outputType = stripLeadingDot(method.outputType);
+    const methodName = `${fullName}.${method.name}`;
+    const options = method.options?.trevrpcMethod;
     methods[jsName] = {
       name: method.name,
-      kind: methodKind(method),
-      inputType: stripLeadingDot(method.inputType),
-      outputType: stripLeadingDot(method.outputType),
+      kind,
+      inputType,
+      outputType,
+      ...unreliableDirections(methodName, kind, options),
+      ...compressionDirections(methodName, kind, options, { inputType, outputType }, redacted),
     };
   }
 
@@ -417,6 +441,113 @@ 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;
+}
+
+/** `trevrpc.Compression` values, from proto/trevrpc/options.proto. */
+const Compression = { unspecified: 0, message: 1, stream: 2 };
+
+/**
+ * The directions a method's `compression` lets compress, as descriptor fields, leaving out message
+ * types with a field marked `debug_redact`. `COMPRESSION_MESSAGE` compresses messages without a
+ * dictionary in both directions. `COMPRESSION_STREAM` does too, for the messages outside the
+ * stream, and stream-compresses the directions that stream; on a unary method it is an error, and
+ * so is a value this generator does not know.
+ */
+function compressionDirections(methodName, kind, options, { inputType, outputType }, redacted) {
+  const compression = options?.compression ?? Compression.unspecified;
+  if (compression === Compression.unspecified) {
+    return {};
+  }
+  if (compression !== Compression.message && compression !== Compression.stream) {
+    throw new Error(`${methodName}: unknown compression ${compression}`);
+  }
+  const directions = {};
+  if (!redacted.has(inputType)) {
+    directions.compressRequests = true;
+  }
+  if (!redacted.has(outputType)) {
+    directions.compressResponses = true;
+  }
+  if (compression === Compression.message) {
+    return directions;
+  }
+  if (kind === "unary") {
+    throw new Error(`${methodName}: COMPRESSION_STREAM requires a streaming method`);
+  }
+  if (
+    (kind === "clientStreaming" || kind === "bidirectionalStreaming") &&
+    !redacted.has(inputType)
+  ) {
+    directions.compressStreamRequests = true;
+  }
+  if (
+    (kind === "serverStreaming" || kind === "bidirectionalStreaming") &&
+    !redacted.has(outputType)
+  ) {
+    directions.compressStreamResponses = true;
+  }
+  return directions;
+}
+
+/**
+ * The full names of the message types that contain a field marked `debug_redact`, directly or in
+ * a message-typed field, however deeply nested.
+ */
+function redactedTypes(files) {
+  const messages = new Map(
+    collectMessages(files).map(({ fullName, message }) => [fullName, message]),
+  );
+  const redacted = new Set();
+  const visiting = new Set();
+  const visit = (name) => {
+    if (redacted.has(name)) {
+      return true;
+    }
+    const message = messages.get(name);
+    if (message === undefined || visiting.has(name)) {
+      return false;
+    }
+    visiting.add(name);
+    const found = (message.field ?? []).some(
+      (field) =>
+        field.options?.debugRedact === true ||
+        (field.typeName != null && visit(stripLeadingDot(field.typeName))),
+    );
+    visiting.delete(name);
+    if (found) {
+      redacted.add(name);
+    }
+    return found;
+  };
+  for (const name of messages.keys()) {
+    visit(name);
+  }
+  return redacted;
+}
+
 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 they, the first
+   * message or the final status arrive. 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,49 @@ 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>;
+}
+
+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
+ * 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;
+  /** Compression settings for calls on this transport; absent without compression. */
+  readonly compression?: Compression;
+  /**
+   * 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.
+   */
+  createBidirectionalStreamWithSession?(): Promise<{
+    stream: TransportStream;
+    session: { readonly datagrams?: DatagramTransport };
+  }>;
 }
 
 export type RpcMethodKind =
@@ -75,6 +126,35 @@ 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;
+  /**
+   * 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 {
@@ -84,11 +164,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 +178,94 @@ 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 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. */
   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 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>;
+  /**
+   * 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,18 +291,65 @@ 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;
+  /**
+   * 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. */
@@ -180,23 +367,42 @@ 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;
+  /** 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 session that carries it. */
+  createBidirectionalStreamWithSession(): Promise<{
+    stream: TransportStream;
+    session: { readonly datagrams?: DatagramTransport };
+  }>;
   /** Resolves once the channel is ready, immediately if it already is. */
   waitUntilReady(): Promise<void>;
   /** Stops reconnecting and closes the current session. */