@trevrpc/trevrpc-js 0.2.3 → 1.1.0

package/src/client.js

@@ -1,467 +1,39 @@
-import { DefaultMaxFrameSize, marshalMessage, unmarshalMessage } from "./framing.js";
-import { normalizeMetadata, validateMetadata } from "./metadata.js";
-import {
-  Code,
-  FrameTooLargeError,
-  TrevRpcError,
-  cancelled,
-  deadlineExceeded,
-  internal,
-  invalidArgument,
-  isOkStatus,
-  resourceExhausted,
-  statusFromResponse,
-  unavailable,
-} from "./status.js";
-import { scheduleTimeout } from "./timer.js";
-import { RpcKind, RpcStreamFrameKind, WireVersion } from "./wire.js";
-
-const RequestStreamBatchSize = 16;
-const PreparedCallOptions = Symbol("trevrpc.preparedCallOptions");
-const EmptyMetadata = Object.freeze(Object.create(null));
-const WriterTerminalNone = 0;
-const WriterTerminalOk = 1;
-const WriterTerminalNonOk = 2;
-
-/** Internal stream-state failure with a stable diagnostic reason. */
-class StreamStateError extends TrevRpcError {
-  constructor(reason, message) {
-    super(Code.Internal, message);
-    this.name = "StreamStateError";
-    this.reason = reason;
-  }
-}
-
-/** Coordinates request writer completion with response stream cleanup. */
-export class RequestWriterSettlement {
-  constructor(
-    normalizeError = (error) => error,
-    isCleanupError = () => false,
-    isTerminalError = () => false,
-    terminalErrorRequiresTerminalFirst = false,
-  ) {
-    this._terminal = WriterTerminalNone;
-    this._cleanupStarted = false;
-    this._hasWriterError = false;
-    this._writerError = undefined;
-    this._errorAfterCleanup = false;
-    this._errorAfterTerminal = false;
-    this._errorReported = false;
-    this._normalizeError = normalizeError;
-    this._isCleanupError = isCleanupError;
-    this._isTerminalError = isTerminalError;
-    this._terminalErrorRequiresTerminalFirst = terminalErrorRequiresTerminalFirst;
-    this.done = Promise.resolve();
-  }
-
-  track(writerTask) {
-    this.done = Promise.resolve(writerTask).then(
-      () => {},
-      (error) => this.recordError(error),
-    );
-  }
-
-  recordError(error) {
-    if (this._hasWriterError) {
-      return;
-    }
-    this._hasWriterError = true;
-    this._writerError = this._normalizeError(error);
-    this._errorAfterCleanup = this._cleanupStarted;
-    this._errorAfterTerminal = this._terminal !== WriterTerminalNone;
-  }
-
-  recordTerminal(statusCode) {
-    if (this._terminal === WriterTerminalNone) {
-      this._terminal = statusCode === Code.Ok ? WriterTerminalOk : WriterTerminalNonOk;
-    }
-  }
-
-  beginCleanup() {
-    this._cleanupStarted = true;
-  }
-
-  async finish() {
-    await this.done;
-    if (
-      !this._hasWriterError ||
-      this._terminal === WriterTerminalNonOk ||
-      (this._terminal === WriterTerminalOk &&
-        (!this._terminalErrorRequiresTerminalFirst || this._errorAfterTerminal) &&
-        this._isTerminalError(this._writerError)) ||
-      (this._errorAfterCleanup && this._isCleanupError(this._writerError)) ||
-      this._errorReported
-    ) {
-      return;
-    }
-
-    this._errorReported = true;
-    throw this._writerError;
-  }
-}
-
-/** Returns the default client call options. */
-export function defaultCallOptions() {
-  return {
-    timeoutMs: undefined,
-    maxResponseBodySize: DefaultMaxFrameSize,
-    maxResponseMessages: 4096,
-    maxResponseStreamBodySize: 16 * 1024 * 1024,
-    streamIdleTimeoutMs: 30_000,
-    metadata: {},
-    signal: undefined,
-  };
-}
-
-/** Merges call options and normalizes metadata. */
-export function mergeCallOptions(base = {}, override = {}) {
-  if (isPreparedCallOptions(base) && !hasDefinedOptions(override)) {
-    return base;
-  }
-
-  const merged = { ...defaultCallOptions() };
-  copyDefined(merged, base);
-  copyDefined(merged, override);
-  merged.metadata = mergeMetadata(base, override);
-  return markPreparedCallOptions(merged);
-}
-
-function preparedCallOptions(options = {}) {
-  return isPreparedCallOptions(options) ? options : mergeCallOptions(options);
-}
-
-/** Calls a unary RPC and decodes the protobuf response. */
-export async function unary(
-  transport,
-  service,
-  method,
-  requestType,
-  responseType,
-  request,
-  options = {},
-) {
-  return (
-    await unaryWithResponse(transport, service, method, requestType, responseType, request, options)
-  ).message;
-}
-
-/** Calls a unary RPC and returns the decoded response envelope. */
-export async function unaryWithResponse(
-  transport,
-  service,
-  method,
-  requestType,
-  responseType,
-  request,
-  options = {},
-) {
-  const callOptions = preparedCallOptions(options);
-  const abortScope = callAbortScope(callOptions);
-
-  try {
-    throwIfAborted(abortScope.signal);
-    const requestBody = marshalMessage(requestType, request);
-    const rpcRequest = prepareClientRequest(
-      service,
-      method,
-      RpcKind.Unary,
-      requestBody,
-      abortScope.options,
-    );
-    const response = await waitForOperation(
-      transport.call(rpcRequest, abortScope.options),
-      abortScope.signal,
-    );
-    const responseStatus = validateResponse(response, callOptions.maxResponseBodySize);
-    abortScope.terminal();
-    if (!isOkStatus(responseStatus)) {
-      throw responseStatus;
-    }
-    return {
-      message: unmarshalMessage(responseType, response.body ?? new Uint8Array(0)),
-      metadata: response.metadata ?? {},
-    };
-  } finally {
-    abortScope.cleanup();
-  }
-}
-
-/** Calls a server-streaming RPC and returns a decoded response stream. */
-export async function serverStreaming(
-  transport,
-  service,
-  method,
-  requestType,
-  responseType,
-  request,
-  options = {},
-) {
-  const callOptions = preparedCallOptions(options);
-  const abortScope = callAbortScope(callOptions);
-  try {
-    throwIfAborted(abortScope.signal);
-    const requestBody = marshalMessage(requestType, request);
-    const rpcRequest = prepareClientRequest(
-      service,
-      method,
-      RpcKind.ServerStreaming,
-      requestBody,
-      abortScope.options,
-    );
-    const frames = await waitForOperation(
-      transport.streamingCall(rpcRequest, emptyAsyncIterable(), abortScope.options),
-      abortScope.signal,
-    );
-    return responseMessageStream(frames, responseType, abortScope.options, abortScope);
-  } catch (error) {
-    abortScope.cleanup();
-    throw error;
-  }
-}
-
-/** Calls a client-streaming RPC and returns a sendable call object. */
-export async function clientStreaming(
-  transport,
-  service,
-  method,
-  requestType,
-  responseType,
-  options = {},
-) {
-  const callOptions = preparedCallOptions(options);
-  const abortScope = callAbortScope(callOptions, { requestCancellation: true });
-  const requests = new RequestQueue(abortScope.signal);
-  try {
-    const rpcRequest = prepareClientRequest(
-      service,
-      method,
-      RpcKind.ClientStreaming,
-      new Uint8Array(0),
-      abortScope.options,
-    );
-    const frames = await waitForOperation(
-      transport.streamingCall(
-        rpcRequest,
-        encodeRequestStream(requestType, requests, abortScope.signal),
-        abortScope.options,
-      ),
-      abortScope.signal,
-    );
-    return new ClientStreamingCall(
-      requests,
-      responseMessageStream(frames, responseType, abortScope.options, abortScope, (error) =>
-        requests.close(error),
-      ),
-    );
-  } catch (error) {
-    requests.close(error);
-    abortScope.cleanup();
-    throw error;
-  }
-}
-
-/** Calls a bidirectional-streaming RPC and returns a sendable call object. */
-export async function bidirectionalStreaming(
-  transport,
-  service,
-  method,
-  requestType,
-  responseType,
-  options = {},
-) {
-  const callOptions = preparedCallOptions(options);
-  const abortScope = callAbortScope(callOptions, { requestCancellation: true });
-  const requests = new RequestQueue(abortScope.signal);
-  try {
-    const rpcRequest = prepareClientRequest(
-      service,
-      method,
-      RpcKind.BidirectionalStreaming,
-      new Uint8Array(0),
-      abortScope.options,
-    );
-    const frames = await waitForOperation(
-      transport.streamingCall(
-        rpcRequest,
-        encodeRequestStream(requestType, requests, abortScope.signal),
-        abortScope.options,
-      ),
-      abortScope.signal,
-    );
-    return new BidirectionalStreamingCall(
-      requests,
-      responseMessageStream(frames, responseType, abortScope.options, abortScope, (error) =>
-        requests.close(error),
-      ),
-    );
-  } catch (error) {
-    requests.close(error);
-    abortScope.cleanup();
-    throw error;
-  }
-}
-
-/** A client-streaming RPC call. */
-export class ClientStreamingCall {
-  constructor(requests, responses) {
-    this._requests = requests;
-    this._responses = responses;
-  }
-
-  /** Sends one request message. */
-  send(request) {
-    return this._requests.send(request);
-  }
-
-  /** Sends multiple request messages. */
-  sendMany(requests) {
-    return this._requests.sendMany(requests);
-  }
-
-  /** Closes the request stream. */
-  closeSend() {
-    this._requests.close();
-    return Promise.resolve();
-  }
-
-  /** Closes the request stream and returns the final response. */
-  async closeAndRecv() {
-    this._requests.close();
-    return await readUnaryResponseFromStream(this._responses);
-  }
-
-  /** Closes the request stream and returns the final response envelope. */
-  async closeAndRecvWithResponse() {
-    this._requests.close();
-    return await readUnaryResponseEnvelopeFromStream(this._responses);
-  }
-
-  /** Releases call resources without waiting for the response. */
-  async close(reason) {
-    const error = cancellationReason(reason, "request stream cancelled");
-    this._requests.close(error);
-    await this._responses.close(error);
-  }
-}
-
-/** A bidirectional-streaming RPC call. */
-export class BidirectionalStreamingCall {
-  constructor(requests, responses) {
-    this._requests = requests;
-    this._responses = responses;
-    this.status = responses.status;
-    this._iterator = responses[Symbol.asyncIterator]();
-  }
-
-  /** Sends one request message. */
-  send(request) {
-    return this._requests.send(request);
-  }
-
-  /** Sends multiple request messages. */
-  sendMany(requests) {
-    return this._requests.sendMany(requests);
-  }
-
-  /** Receives one response message, or undefined after the response stream completes. */
-  async recv() {
-    const result = await this._iterator.next();
-    return result.done ? undefined : result.value;
-  }
-
-  /** Closes the request stream while keeping the response stream readable. */
-  closeSend() {
-    this._requests.close();
-    return Promise.resolve();
-  }
-
-  /** Releases call resources without waiting for more responses. */
-  async close(reason) {
-    const error = cancellationReason(reason, "request stream cancelled");
-    this._requests.close(error);
-    await this._responses.close(error);
-  }
-
-  [Symbol.asyncIterator]() {
-    return {
-      next: async () => {
-        const value = await this.recv();
-        return value === undefined ? { done: true, value: undefined } : { done: false, value };
-      },
-      return: async () => {
-        await this.close();
-        return { done: true, value: undefined };
-      },
-    };
-  }
-}
+import { Call, 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";
 
 /** Creates a service client from a generated service descriptor. */
 export function createServiceClient(transport, service, root, options = {}) {
+  const defaults = mergeCallOptions(defaultCallOptions(), options);
   const client = {};
-  const baseOptions = mergeCallOptions(options);
 
   for (const [jsName, method] of Object.entries(service.methods)) {
-    const requestType = root.lookupType(method.inputType);
-    const responseType = root.lookupType(method.outputType);
-    const callOptions = (override) => mergeCallOptions(baseOptions, override ?? {});
+    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),
+      datagrams: datagramUse(method),
+    };
+    const resolve = (override) => mergeCallOptions(defaults, override);
 
     switch (method.kind) {
       case "unary":
-        client[jsName] = (request, override) =>
-          unary(
-            transport,
-            service.fullName,
-            method.name,
-            requestType,
-            responseType,
-            request,
-            callOptions(override),
-          );
-        client[`${jsName}WithResponse`] = (request, override) =>
-          unaryWithResponse(
-            transport,
-            service.fullName,
-            method.name,
-            requestType,
-            responseType,
-            request,
-            callOptions(override),
-          );
+        client[jsName] = async (request, override) =>
+          unaryCall(transport, rpc, request, resolve(override));
         break;
       case "serverStreaming":
         client[jsName] = (request, override) =>
-          serverStreaming(
-            transport,
-            service.fullName,
-            method.name,
-            requestType,
-            responseType,
-            request,
-            callOptions(override),
-          );
+          serverStreamingCall(transport, rpc, request, resolve(override));
         break;
       case "clientStreaming":
-        client[jsName] = (override) =>
-          clientStreaming(
-            transport,
-            service.fullName,
-            method.name,
-            requestType,
-            responseType,
-            callOptions(override),
-          );
+        client[jsName] = (override) => clientStreamingCall(transport, rpc, resolve(override));
         break;
       case "bidirectionalStreaming":
         client[jsName] = (override) =>
-          bidirectionalStreaming(
-            transport,
-            service.fullName,
-            method.name,
-            requestType,
-            responseType,
-            callOptions(override),
-          );
+          bidirectionalStreamingCall(transport, rpc, resolve(override));
         break;
       default:
         throw internal(`unsupported generated RPC kind ${JSON.stringify(method.kind)}`);
@@ -471,927 +43,644 @@ export function createServiceClient(transport, service, root, options = {}) {
   return client;
 }
 
-function prepareClientRequest(service, method, kind, body, options) {
-  const metadata = isPreparedCallOptions(options)
-    ? (options.metadata ?? EmptyMetadata)
-    : normalizeMetadata(options.metadata ?? {});
-  const request = {
-    service,
-    method,
-    body,
-    metadata,
-    version: WireVersion,
-  };
-  const timeout = timeoutNanos(options.timeoutMs);
-
-  if (kind !== RpcKind.Unary) {
-    request.kind = kind;
-  }
-
-  if (timeout != null) {
-    request.timeoutNanos = timeout;
-  }
-
-  return request;
+/** 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 stream = new BidirectionalStreamingCall(call, rpc, { options });
+  // The response decides the outcome, so the request side finishes in the background.
+  stream.closeSend().catch(() => {});
+  return await receiveSingleResponse(stream, "unary");
 }
 
-function validateResponse(response, maxBodySize) {
-  if (response == null) {
-    throw internal("missing RPC response");
-  }
-
-  validateResponseMetadata(response.metadata ?? {});
-
-  const body = response.body ?? new Uint8Array(0);
-  if (body.byteLength > maxBodySize) {
-    throw new FrameTooLargeError(body.byteLength, maxBodySize);
-  }
-
-  return statusFromResponse(response);
+/** Calls a server-streaming RPC and returns its response stream. */
+export async function serverStreamingCall(transport, rpc, request, options) {
+  const body = marshalMessage(rpc.requestType, request);
+  const call = await Call.open(
+    transport,
+    requestFields(rpc, RpcKind.ServerStreaming),
+    body,
+    options,
+    rpc.datagrams,
+  );
+  const stream = new BidirectionalStreamingCall(call, rpc, { options });
+  stream.closeSend().catch(() => {});
+  return new ResponseStream(stream);
+}
+
+/** Calls a client-streaming RPC and returns a call for sending requests. */
+export async function clientStreamingCall(transport, rpc, options) {
+  const call = await Call.open(
+    transport,
+    requestFields(rpc, RpcKind.ClientStreaming),
+    undefined,
+    options,
+    rpc.datagrams,
+  );
+  return new ClientStreamingCall(
+    new BidirectionalStreamingCall(call, rpc, { streamsRequest: true, options }),
+  );
 }
 
-function responseMessageStream(
-  frameStream,
-  responseType,
-  options,
-  abortScope,
-  onTerminal = () => {},
-) {
-  return new ResponseStreamController(frameStream, responseType, options, abortScope, onTerminal);
-}
+/** Calls a bidirectional-streaming RPC. */
+export async function bidirectionalStreamingCall(transport, rpc, options) {
+  const call = await Call.open(
+    transport,
+    requestFields(rpc, RpcKind.BidirectionalStreaming),
+    undefined,
+    options,
+    rpc.datagrams,
+  );
+  return new BidirectionalStreamingCall(call, rpc, { streamsRequest: true, options });
+}
+
+/**
+ * Receives the single response message of a unary or client-streaming call, then its final
+ * status. A second message fails the call immediately; none at all is an internal error.
+ */
+async function receiveSingleResponse(stream, kind) {
+  let message;
+  let count = 0;
+  for (;;) {
+    const next = await stream.recv();
+    if (next === undefined) {
+      break;
+    }
+    count += 1;
+    if (count > 1) {
+      const error = internal(`${kind} RPC returned more than one response message`);
+      await stream.close(error);
+      throw error;
+    }
+    message = next;
+  }
+  if (count !== 1) {
+    throw internal(`${kind} RPC returned no response message`);
+  }
+  await stream.status;
+  return message;
+}
+
+/**
+ * How much of a response the call reads ahead of recv() while it is still uploading: at most this
+ * many frames or bytes are queued before reading pauses and the transport's flow control applies
+ * to a caller that does not receive. The byte bound is checked before each read, so the queue can
+ * exceed it by at most one frame, which is at most `maxFrameSize`. Without a bound a caller that
+ * only sends could be made to buffer a whole response.
+ */
+const ReadAheadFrames = 32;
+const ReadAheadBytes = 1 << 20;
+
+/**
+ * How a method uses datagrams, or undefined if it does not: `send` for request messages, which
+ * needs a streaming request and `unreliableRequests`, and `receive` for response messages, which
+ * every call with a streaming response accepts. A method needs a flow if it marks either
+ * direction unreliable; the generator rejects marks on a direction that does not stream.
+ */
+function datagramUse({ kind, unreliableRequests, unreliableResponses }) {
+  const streamsRequest = kind === "clientStreaming" || kind === "bidirectionalStreaming";
+  const streamsResponse = kind === "serverStreaming" || kind === "bidirectionalStreaming";
+  if (!(unreliableRequests || unreliableResponses) || !(streamsRequest || streamsResponse)) {
+    return undefined;
+  }
+  return { send: Boolean(unreliableRequests) && streamsRequest, receive: streamsResponse };
+}
+
+const EarlyOk = "the server completed the call before the request stream ended";
+
+/**
+ * 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.
+ *
+ * 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
+ * later sends fail with the non-OK status, or with Cancelled if the status is OK. A call that
+ * does not stream its request reads only what recv() or `headers` ask for.
+ *
+ * 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.
+ */
+export class BidirectionalStreamingCall {
+  #call;
+  #rpc;
+  /** Whether the request side streams, so that responses are read ahead of recv(). */
+  #streamsRequest;
+  /** Serializes recv() so concurrent callers never interleave frame reads. */
+  #reads = Promise.resolve();
+  /** Response messages read ahead of recv(), in order. */
+  #queue = [];
+  #queuedBytes = 0;
+  /**
+   * What ends the response, delivered by recv() after the queued messages: `{ status, error }`
+   * for the final status (error unless OK) or `{ error }` for a failed stream.
+   */
+  #terminal;
+  /** An error that ended the call out of order, such as an abort; queued messages are dropped. */
+  #failure;
+  #failingInOrder = false;
+  #outcomeSettled = false;
+  #pumping = false;
+  /**
+   * The call's datagram flow when its responses may arrive as datagrams, else undefined. The flow
+   * connects once HEADERS (or the first frame that implies them) was read; until then it buffers.
+   */
+  #flow;
+  /** Receivers waiting for a frame. */
+  #demand = 0;
+  #headersWanted = false;
+  #sawHeaders = false;
+  #sawMessage = false;
+  /** Settles on every change a waiter may care about. */
+  #changed = deferred();
+  #resolveStatus;
+  #rejectStatus;
+  #resolveHeaders;
+  #rejectHeaders;
+  #headers;
+  #onResponseHeaders;
+  #onResponseMetadata;
+  /** Whether the headers were handed to onResponseHeaders. */
+  #headersReported = false;
+
+  /** The final status, or the error that ended the call. */
+  status = new Promise((resolve, reject) => {
+    this.#resolveStatus = resolve;
+    this.#rejectStatus = reject;
+  });
 
-class ResponseStreamController {
-  constructor(frameStream, responseType, options, abortScope, onTerminal) {
-    this._iterator = frameStream[Symbol.asyncIterator]();
-    this._responseType = responseType;
-    this._options = options;
-    this._abortScope = abortScope;
-    this._onTerminal = onTerminal;
-    this._useBodyBatches = typeof this._iterator.nextBodyBatch === "function";
-    this._counters = { messages: 0, streamBodySize: 0 };
-    this._messages = [];
-    this._pendingError = null;
-    this._pendingStatus = null;
-    this._complete = false;
-    this._failure = null;
-    this._cleanupPromise = null;
-    this._statusSettled = false;
-    this._operation = Promise.resolve();
-    this.status = new Promise((resolve, reject) => {
-      this._resolveStatus = resolve;
-      this._rejectStatus = reject;
-    });
+  constructor(call, rpc, { streamsRequest = false, options = {} } = {}) {
+    this.#call = call;
+    this.#rpc = rpc;
+    this.#streamsRequest = streamsRequest;
+    this.#onResponseHeaders = options.onResponseHeaders;
+    this.#onResponseMetadata = options.onResponseMetadata;
+    this.#flow = rpc.datagrams?.receive ? call.flow : undefined;
     this.status.catch(() => {});
-    this._onAbort = () => {
-      const error = signalAbortError(this._options.signal);
-      this._recordFailure(error);
-      void this._cleanup(error);
-    };
-    if (this._options.signal?.aborted) {
-      this._onAbort();
+    this.#headers = new Promise((resolve, reject) => {
+      this.#resolveHeaders = resolve;
+      this.#rejectHeaders = reject;
+    });
+    this.#headers.catch(() => {});
+    call.signal.addEventListener(
+      "abort",
+      () => {
+        if (!this.#failingInOrder) {
+          this.#settleFailure(call.signal.reason);
+        }
+      },
+      { once: true },
+    );
+    if (call.signal.aborted) {
+      this.#settleFailure(call.signal.reason);
     } else {
-      this._options.signal?.addEventListener?.("abort", this._onAbort, { once: true });
-    }
-  }
-
-  [Symbol.asyncIterator]() {
-    return this;
-  }
-
-  next() {
-    return this._serialize(() => this._next());
-  }
-
-  async return() {
-    await this.close();
-    return { done: true, value: undefined };
-  }
-
-  async close(reason) {
-    if (this._complete) {
-      await this._cleanupPromise;
-      return;
+      this.#kick();
     }
-    const error = cancellationReason(reason, "response stream cancelled");
-    this._abortScope?.abort(error);
-    this._recordFailure(error);
-    await this._cleanup(error);
   }
 
-  _serialize(operation) {
-    const result = this._operation.then(operation, operation);
-    this._operation = result.catch(() => {});
-    return result;
+  /**
+   * 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.
+   */
+  get headers() {
+    this.#headersWanted = true;
+    this.#kick();
+    return this.#headers;
   }
 
-  async _next() {
-    if (this._failure != null) {
-      throw this._failure;
-    }
-    if (this._complete) {
-      return { done: true, value: undefined };
-    }
-
+  /**
+   * Sends one request message. Fails with the server's final status if the server ended the
+   * call, as soon as it is known; with Cancelled if that status is OK; and with the error that
+   * ended the call otherwise.
+   */
+  async send(message) {
+    const body = marshalMessage(this.#rpc.requestType, message);
     try {
-      for (;;) {
-        if (this._messages.length > 0) {
-          return { done: false, value: this._messages.shift() };
-        }
-        if (this._pendingError != null) {
-          const error = this._pendingError;
-          this._pendingError = null;
-          throw error;
-        }
-        if (this._pendingStatus != null) {
-          const frame = this._pendingStatus;
-          this._pendingStatus = null;
-          await this._finishStatus(frame);
-          if (this._failure != null) {
-            throw this._failure;
-          }
-          return { done: true, value: undefined };
-        }
-
-        const result = await this._readNext();
-        if (result.done) {
-          throw new StreamStateError(
-            "missing_terminal_status",
-            "response stream ended before final status",
-          );
-        }
-        this._consumeBatch(result.value);
-      }
+      await this.#call.sendMessage(body);
     } catch (error) {
-      const primary = this._recordFailure(error);
-      await this._cleanup(primary);
-      throw primary;
+      throw await this.#explainUploadFailure(error);
     }
   }
 
-  _consumeBatch(value) {
-    if (this._useBodyBatches) {
-      for (const body of value.bodies) {
-        validateResponseMessageBody(body, this._options, this._counters);
-        this._messages.push(unmarshalMessage(this._responseType, body));
-      }
-      if (value.status != null) {
-        this._pendingStatus = this._claimStatus(value.status);
-      }
-      return;
-    }
-
-    for (let index = 0; index < value.length; index += 1) {
-      const frame = value[index];
-      if (frame == null) {
-        const error = new StreamStateError(
-          "missing_terminal_status",
-          "response stream ended before final status",
-        );
-        if (this._messages.length > 0) {
-          this._pendingError = error;
-          return;
-        }
-        throw error;
-      }
-      if (frame.kind === RpcStreamFrameKind.Message) {
-        const body = frame.body ?? new Uint8Array(0);
-        validateResponseMessageBody(body, this._options, this._counters);
-        this._messages.push(unmarshalMessage(this._responseType, body));
-        continue;
-      }
-      if (frame.kind === RpcStreamFrameKind.Status) {
-        if (index + 1 < value.length) {
-          throw new StreamStateError(
-            "trailing_frame",
-            "response stream contained a frame after final status",
-          );
-        }
-        this._pendingStatus = this._claimStatus(frame);
-        continue;
+  /**
+   * 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().
+   */
+  async closeSend() {
+    try {
+      await this.#call.closeSend();
+    } catch (error) {
+      const reason = await this.#explainUploadFailure(error);
+      if (this.#terminal?.status === undefined) {
+        throw reason;
       }
-      const error = invalidArgument("response stream contained an unknown frame kind");
-      error.reason = "unsupported_frame_kind";
-      throw error;
     }
   }
 
-  _claimStatus(frame) {
-    validateResponseMetadata(frame.metadata ?? {});
-    const status = {
-      code: frame.status ?? Code.Ok,
-      message: frame.message ?? "",
-      metadata: frame.metadata ?? {},
-    };
-    const terminalError =
-      status.code === Code.Ok
-        ? null
-        : statusFromResponse({
-            status: status.code,
-            message: status.message,
-            metadata: status.metadata,
-          });
-
-    if (!this._abortScope?.terminal()) {
-      throw signalAbortError(this._options.signal);
-    }
-    this._onTerminal(terminalError);
-    return { status, terminalError };
-  }
-
-  async _finishStatus(terminal) {
-    const { status, terminalError } = terminal;
-    let end;
+  /**
+   * Sends every message of requests, an iterable or async iterable, then closes the request
+   * stream. If the server ends the call first, the rest is not sent and nothing is thrown: the
+   * response side reports the outcome. A send that fails otherwise rejects as send() does, and
+   * requests that throw cancel the call with that error and reject with it.
+   */
+  async sendAll(requests) {
+    let sendFailure;
     try {
-      end = await this._readNext();
+      for await (const request of requests) {
+        try {
+          await this.send(request);
+        } catch (error) {
+          if (this.#terminal?.status !== undefined) {
+            return; // the server ended the call; the response side reports how
+          }
+          sendFailure = error;
+          throw error;
+        }
+      }
     } catch (error) {
-      if (!isMalformedTrailingRead(error)) {
-        throw error;
+      if (error !== sendFailure) {
+        await this.close(error);
       }
-      const trailing = new StreamStateError(
-        "trailing_frame",
-        "response stream did not end cleanly after final status",
-      );
-      trailing.cause = error;
-      throw trailing;
-    }
-    if (!end.done) {
-      throw new StreamStateError(
-        "trailing_frame",
-        "response stream contained a frame after final status",
-      );
-    }
-
-    await this._cleanup(terminalError);
-    if (terminalError != null) {
-      this._recordFailure(terminalError);
-      throw terminalError;
+      throw error;
     }
-    this._complete = true;
-    this._settleStatus(true, status);
+    await this.closeSend();
   }
 
-  _readNext() {
-    return this._useBodyBatches
-      ? nextBodyBatchWithTimeout(
-          this._iterator,
-          this._options.streamIdleTimeoutMs,
-          this._options.signal,
-          this._abortScope?.abort,
-        )
-      : nextFrameBatchWithTimeout(
-          this._iterator,
-          this._options.streamIdleTimeoutMs,
-          this._options.signal,
-          this._abortScope?.abort,
-        );
+  /** Receives the next response message, or undefined after the final OK status. */
+  recv() {
+    const next = this.#reads.then(() => this.#recv());
+    this.#reads = next.catch(() => {});
+    return next;
   }
 
-  _recordFailure(error) {
-    if (this._failure == null && !this._complete) {
-      this._failure = error;
-      this._settleStatus(false, error);
+  /** Cancels the call unless it already finished. */
+  async close(reason) {
+    if (this.#terminal === undefined || this.#queue.length > 0) {
+      this.#call.cancel(reason);
+      this.#settleFailure(this.#call.signal.reason);
     }
-    return this._failure ?? error;
   }
 
-  _settleStatus(success, value) {
-    if (this._statusSettled) {
-      return;
-    }
-    this._statusSettled = true;
-    if (success) {
-      this._resolveStatus(value);
-    } else {
-      this._rejectStatus(value);
-    }
+  [Symbol.asyncIterator]() {
+    return {
+      next: async () => {
+        const value = await this.recv();
+        return value === undefined ? { done: true, value: undefined } : { done: false, value };
+      },
+      return: async () => {
+        await this.close();
+        return { done: true, value: undefined };
+      },
+    };
   }
 
-  _cleanup(primaryError) {
-    if (this._cleanupPromise != null) {
-      return this._cleanupPromise;
-    }
-    this._cleanupPromise = (async () => {
-      this._options.signal?.removeEventListener?.("abort", this._onAbort);
+  async #recv() {
+    const item = await this.#take();
+    if (item.payload !== undefined) {
       try {
-        if (typeof this._iterator.return === "function") {
-          await this._iterator.return();
-        }
+        return unmarshalMessage(this.#rpc.responseType, item.payload);
       } catch (error) {
-        if (primaryError == null) {
-          throw error;
-        }
-      } finally {
-        this._abortScope?.cleanup();
+        throw this.#settleFailure(this.#call.fail(error));
       }
-    })();
-    return this._cleanupPromise;
-  }
-}
-
-function validateResponseMessageBody(body, options, counters) {
-  if (options.maxResponseMessages >= 0 && counters.messages >= options.maxResponseMessages) {
-    throw resourceExhausted(
-      `response stream exceeded maximum of ${options.maxResponseMessages} messages`,
-    );
-  }
-
-  if (body.byteLength > options.maxResponseBodySize) {
-    throw new FrameTooLargeError(body.byteLength, options.maxResponseBodySize);
-  }
-
-  counters.messages += 1;
-  counters.streamBodySize = saturatingAdd(counters.streamBodySize, body.byteLength);
-  if (
-    options.maxResponseStreamBodySize >= 0 &&
-    counters.streamBodySize > options.maxResponseStreamBodySize
-  ) {
-    throw resourceExhausted(
-      `response stream exceeded maximum body size of ${options.maxResponseStreamBodySize} bytes`,
-    );
-  }
-}
-
-async function nextBodyBatchWithTimeout(iterator, idleTimeoutMs, signal, onTimeout) {
-  return await withTimeout(
-    iterator.nextBodyBatch(),
-    idleTimeoutMs,
-    () => unavailable("response stream idle timeout"),
-    onTimeout,
-    signal,
-  );
-}
-
-async function nextFrameBatchWithTimeout(iterator, idleTimeoutMs, signal, onTimeout) {
-  const hasBatchReader = typeof iterator.nextBatch === "function";
-  const result = await withTimeout(
-    hasBatchReader ? iterator.nextBatch() : iterator.next(),
-    idleTimeoutMs,
-    () => unavailable("response stream idle timeout"),
-    onTimeout,
-    signal,
-  );
-  return hasBatchReader || result.done ? result : { done: false, value: [result.value] };
-}
-
-function isMalformedTrailingRead(error) {
-  return (
-    error instanceof FrameTooLargeError ||
-    error?.reason === "malformed_protobuf" ||
-    error?.reason === "incomplete_frame"
-  );
-}
-
-function validateResponseMetadata(metadata) {
-  try {
-    validateMetadata(metadata);
-  } catch (error) {
-    throw new StreamStateError(
-      "invalid_metadata",
-      `invalid response metadata: ${error.statusMessage ?? error.message}`,
-    );
-  }
-}
-
-async function readUnaryResponseFromStream(stream) {
-  return (await readUnaryResponseEnvelopeFromStream(stream)).message;
-}
-
-async function readUnaryResponseEnvelopeFromStream(stream) {
-  let firstMessage;
-  let messageCount = 0;
-  for await (const message of stream) {
-    if (messageCount === 0) {
-      firstMessage = message;
     }
-    messageCount += 1;
-  }
-
-  const status = stream.status == null ? { metadata: {} } : await stream.status;
-  if (messageCount === 0) {
-    throw new StreamStateError(
-      "response_cardinality",
-      "response stream ended without a response message",
-    );
-  }
-  if (messageCount !== 1) {
-    throw new StreamStateError(
-      "response_cardinality",
-      "client-streaming RPC returned more than one response message",
-    );
-  }
-
-  return { message: firstMessage, metadata: status.metadata ?? {} };
-}
-
-function timeoutNanos(timeoutMs) {
-  if (timeoutMs == null) {
-    return null;
-  }
-
-  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
-    throw invalidArgument("RPC timeout must be a non-negative finite number of milliseconds");
-  }
-
-  const nanos = BigInt(Math.ceil(timeoutMs)) * 1_000_000n;
-  return String(nanos === 0n ? 1n : nanos);
-}
-
-function withTimeout(promise, timeoutMs, makeError, onTimeout, signal) {
-  if (timeoutMs == null && signal == null) {
-    return promise;
-  }
-
-  if (timeoutMs != null && !Number.isFinite(timeoutMs)) {
-    throw invalidArgument("RPC timeout must be a finite number of milliseconds");
+    if (item.error !== undefined) {
+      throw item.error;
+    }
+    return undefined;
   }
 
-  return new Promise((resolve, reject) => {
-    let settled = false;
-    let cancelTimer = () => {};
-    const cleanup = () => {
-      cancelTimer();
-      signal?.removeEventListener?.("abort", onAbort);
-    };
-    const settle = (complete, value) => {
-      if (settled) {
-        return;
+  /** Takes the next queued message, or the end of the response once the queue is empty. */
+  async #take() {
+    for (;;) {
+      if (this.#failure !== undefined) {
+        throw this.#failure;
       }
-      settled = true;
-      cleanup();
-      complete(value);
-    };
-    const onAbort = () => settle(reject, signalAbortError(signal));
-
-    if (timeoutMs != null && timeoutMs >= 0) {
-      cancelTimer = scheduleTimeout(() => {
-        const error = makeError();
-        onTimeout?.(error);
-        settle(reject, error);
-      }, timeoutMs);
-    }
-
-    if (signal != null) {
-      if (signal.aborted) {
-        onAbort();
-        return;
+      const payload = this.#queue.shift();
+      if (payload !== undefined) {
+        this.#queuedBytes -= payload.byteLength;
+        // Room for more read-ahead.
+        this.#kick();
+        return { payload };
+      }
+      if (this.#terminal !== undefined) {
+        // A failure of the stream itself surfaces here, in order, after the responses before it.
+        if (this.#terminal.status === undefined) {
+          throw this.#settleFailure(this.#terminal.error);
+        }
+        return this.#terminal;
+      }
+      const changed = this.#changed.promise;
+      this.#demand += 1;
+      this.#kick();
+      try {
+        await changed;
+      } finally {
+        this.#demand -= 1;
       }
-      signal.addEventListener("abort", onAbort, { once: true });
     }
-
-    promise.then(
-      (value) => {
-        settle(resolve, value);
-      },
-      (error) => {
-        settle(reject, error);
-      },
-    );
-  });
-}
-
-function signalAbortError(signal) {
-  const reason = signal?.reason;
-  return reason instanceof TrevRpcError ? reason : cancelled("RPC cancelled");
-}
-
-function cancellationReason(reason, fallback) {
-  if (reason instanceof TrevRpcError && reason.code === Code.Cancelled) {
-    return reason;
-  }
-  const error = cancelled(fallback);
-  if (reason !== undefined) {
-    Object.defineProperty(error, "cause", { configurable: true, value: reason });
-  }
-  return error;
-}
-
-function normalizeAbortReason(reason) {
-  return reason instanceof TrevRpcError ? reason : cancellationReason(reason, "RPC cancelled");
-}
-
-function throwIfAborted(signal) {
-  if (signal?.aborted) {
-    throw signalAbortError(signal);
-  }
-}
-
-function waitForOperation(promise, signal) {
-  return withTimeout(promise, null, null, null, signal);
-}
-
-function callAbortScope(options, { requestCancellation = false } = {}) {
-  const needsTransportSignal = options.signal != null || options.timeoutMs != null;
-  if (!needsTransportSignal && !requestCancellation) {
-    return {
-      options,
-      signal: undefined,
-      abort() {
-        return false;
-      },
-      terminal() {
-        return true;
-      },
-      cleanup() {},
-    };
   }
 
-  if (options.timeoutMs != null && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) {
-    throw invalidArgument("RPC timeout must be a non-negative finite number of milliseconds");
+  /** Starts reading the response unless it is running or has nothing to read for. */
+  #kick() {
+    if (!this.#pumping && this.#wantsRead()) {
+      this.#pumping = true;
+      // The pump handles the errors of the response itself; anything else is a bug that ends the call.
+      this.#pump().catch((error) => this.#settleFailure(this.#call.fail(error)));
+    }
   }
 
-  const controller = new AbortController();
-  const parentSignal = options.signal;
-  const deadlineError =
-    options.timeoutMs == null ? null : deadlineExceeded("RPC deadline exceeded");
-  let settlement = "active";
-  let cleaned = false;
-  let cancelDeadline = () => {};
-
-  const clearDeadline = () => {
-    cancelDeadline();
-    cancelDeadline = () => {};
-  };
-  const removeParent = () => parentSignal?.removeEventListener?.("abort", onParentAbort);
-  const abort = (reason) => {
-    if (settlement !== "active") {
+  #wantsRead() {
+    if (this.#terminal !== undefined || this.#failure !== undefined) {
       return false;
     }
-    settlement = "aborted";
-    clearDeadline();
-    removeParent();
-    controller.abort(normalizeAbortReason(reason));
-    return true;
-  };
-  const terminal = () => {
-    if (settlement !== "active") {
-      return false;
+    if (this.#demand > 0 && this.#queue.length === 0) {
+      return true;
     }
-    settlement = "terminal";
-    clearDeadline();
-    removeParent();
-    return true;
-  };
-  const onParentAbort = () => abort(parentSignal.reason);
-
-  if (parentSignal != null) {
-    if (parentSignal.aborted) {
-      onParentAbort();
-    } else {
-      parentSignal.addEventListener("abort", onParentAbort, { once: true });
+    if (this.#headersWanted && !this.#sawHeaders && !this.#sawMessage) {
+      return true;
     }
+    // A call with a datagram flow always reads ahead, so datagrams are released after HEADERS
+    // even if nobody receives.
+    return (
+      ((this.#streamsRequest && this.#call.uploadOpen) || this.#flow !== undefined) &&
+      this.#queue.length < ReadAheadFrames &&
+      this.#queuedBytes < ReadAheadBytes
+    );
   }
-  if (deadlineError != null && settlement === "active") {
-    cancelDeadline = scheduleTimeout(() => abort(deadlineError), options.timeoutMs);
+
+  /** Reads response events into the queue for as long as someone wants them. */
+  async #pump() {
+    try {
+      while (this.#wantsRead()) {
+        let event;
+        try {
+          event = await this.#readEvent();
+        } catch (error) {
+          this.#endWithError(error);
+          return;
+        }
+        if (this.#failure !== undefined) {
+          return;
+        }
+        if (event.type === FrameType.Message) {
+          this.#queue.push(event.payload);
+          this.#queuedBytes += event.payload.byteLength;
+        } else {
+          this.#endWithStatus(event.status);
+        }
+        this.#notify();
+      }
+    } finally {
+      this.#pumping = false;
+      this.#notify();
+    }
   }
 
-  return {
-    options: markPreparedCallOptions({ ...options, signal: controller.signal }),
-    signal: controller.signal,
-    abort,
-    terminal,
-    cleanup() {
-      if (cleaned) {
+  /** The final status arrived: it is the outcome, and it ends the upload. */
+  #endWithStatus({ code, message, metadata }) {
+    if (code === Code.Ok && this.#onResponseMetadata !== undefined) {
+      try {
+        this.#onResponseMetadata(metadata);
+      } catch (error) {
+        this.#endWithError(error);
         return;
       }
-      cleaned = true;
-      clearDeadline();
-      removeParent();
-    },
-  };
-}
-
-class RequestQueue {
-  constructor(signal) {
-    this._pending = [];
-    this._waiter = undefined;
-    this._closed = false;
-    this._error = undefined;
-    this._signal = signal;
-    this._onAbort = () => this.close(signalAbortError(signal));
-    if (signal?.aborted) {
-      this._onAbort();
+    }
+    const error = code === Code.Ok ? undefined : statusError(code, message, metadata);
+    this.#terminal = { status: { code, message, metadata }, error };
+    this.#call.finish(error ?? cancelled(EarlyOk));
+    if (error === undefined) {
+      this.#outcomeSettled = true;
+      this.#resolveStatus({ code, message, metadata });
     } else {
-      signal?.addEventListener?.("abort", this._onAbort, { once: true });
+      this.#rejectOutcome(error);
     }
   }
 
-  send(value) {
-    return this.sendMany([value]);
-  }
-
-  sendMany(values) {
-    if (this._closed) {
-      return Promise.reject(this._error ?? cancelled("request stream is closed"));
+  /**
+   * The response stream failed or ended without a final status. Responses read before are still
+   * delivered; the error surfaces when recv() reaches it. The call is torn down now, so sends
+   * fail with this error.
+   */
+  #endWithError(error) {
+    if (this.#call.signal.aborted) {
+      return; // an abort already decided the outcome
     }
-
-    const batch = Array.from(values);
-    if (batch.length === 0) {
-      return Promise.resolve();
-    }
-
-    return new Promise((resolve, reject) => {
-      let remaining = batch.length;
-      const resolveOne = () => {
-        remaining -= 1;
-        if (remaining === 0) {
-          resolve();
-        }
-      };
-      for (const value of batch) {
-        this._pending.push({ value, resolve: resolveOne, reject });
-      }
-      this._wakeWaiter();
-    });
+    this.#failingInOrder = true;
+    const reason = this.#call.fail(error);
+    this.#failingInOrder = false;
+    this.#terminal = { error: reason };
+    this.#rejectOutcome(reason);
+    this.#notify();
   }
 
-  close(error) {
-    if (this._closed) {
-      return;
+  /** Settles the headers on their first frame, and hands them to onResponseHeaders once. */
+  #settleHeaders(metadata) {
+    this.#resolveHeaders(metadata);
+    if (!this.#headersReported) {
+      this.#headersReported = true;
+      this.#onResponseHeaders?.(metadata);
     }
+  }
 
-    this._closed = true;
-    this._error = error;
-    this._signal?.removeEventListener?.("abort", this._onAbort);
-    if (error != null) {
-      for (const pending of this._pending.splice(0)) {
-        pending.reject(error);
+  /**
+   * Reads the next MESSAGE or STATUS event, consuming HEADERS on the way. Enforces the response
+   * grammar `[HEADERS] MESSAGE* STATUS`.
+   */
+  async #readEvent() {
+    for (;;) {
+      const frame = await this.#call.readFrame();
+      if (frame === null) {
+        throw this.#call.uploadFailure ?? internal("response stream ended before final status");
       }
-    }
-    if (this._waiter != null) {
-      const waiter = this._waiter;
-      this._waiter = undefined;
-      if (error == null) {
-        waiter.resolve({ done: true, value: undefined });
-      } else {
-        waiter.reject(error);
+
+      switch (frame.type) {
+        case FrameType.Headers: {
+          if (this.#sawHeaders || this.#sawMessage) {
+            throw internal(
+              this.#sawHeaders ? "duplicate HEADERS frame" : "HEADERS frame after MESSAGE",
+            );
+          }
+          const headers = unmarshalMessage(RpcHeaders, frame.payload);
+          validateResponseMetadata(headers.metadata, "headers");
+          this.#sawHeaders = true;
+          this.#settleHeaders(headers.metadata);
+          this.#flow?.connect(this.#onDatagram);
+          continue;
+        }
+        case FrameType.Message:
+          this.#sawMessage = true;
+          this.#settleHeaders({});
+          this.#flow?.connect(this.#onDatagram);
+          return frame;
+        case FrameType.Status: {
+          const status = unmarshalMessage(RpcStatus, frame.payload);
+          validateResponseMetadata(status.metadata, "trailing metadata");
+          this.#settleHeaders({});
+          this.#flow?.connect(this.#onDatagram);
+          return { type: FrameType.Status, status };
+        }
+        default:
+          throw internal(`unexpected frame type ${frame.type} on a response stream`);
       }
     }
   }
 
-  [Symbol.asyncIterator]() {
-    return this;
-  }
-
-  next() {
-    if (this._pending.length > 0) {
-      const pending = this._pending.shift();
-      pending.resolve();
-      return Promise.resolve({ done: false, value: pending.value });
-    }
-    if (this._error != null) {
-      return Promise.reject(this._error);
-    }
-    if (this._closed) {
-      return Promise.resolve({ done: true, value: undefined });
+  /**
+   * Queues a response message that arrived as a datagram, in arrival order with the stream's
+   * messages. It never blocks: a message is dropped when the call ended or its queue is full.
+   */
+  #onDatagram = (payload) => {
+    if (
+      this.#terminal !== undefined ||
+      this.#failure !== undefined ||
+      payload.byteLength > this.#call.maxFrameSize ||
+      this.#queue.length >= ReadAheadFrames ||
+      this.#queuedBytes + payload.byteLength > ReadAheadBytes
+    ) {
+      return;
     }
+    this.#queue.push(payload);
+    this.#queuedBytes += payload.byteLength;
+    this.#notify();
+  };
 
-    return new Promise((resolve, reject) => {
-      this._waiter = { resolve, reject };
-    });
+  /** Ends the call out of order: receivers fail with `error` without draining the queue. */
+  #settleFailure(error) {
+    this.#failure ??= error;
+    this.#rejectOutcome(error);
+    this.#notify();
+    return this.#failure;
   }
 
-  nextBatch(max = RequestStreamBatchSize) {
-    if (this._pending.length > 0) {
-      return Promise.resolve({ done: false, value: this._takePendingBatch(max) });
-    }
-    if (this._error != null) {
-      return Promise.reject(this._error);
+  #rejectOutcome(error) {
+    if (!this.#outcomeSettled) {
+      this.#outcomeSettled = true;
+      this.#rejectStatus(error);
+      this.#rejectHeaders(error);
     }
-    if (this._closed) {
-      return Promise.resolve({ done: true, value: undefined });
-    }
-
-    return new Promise((resolve, reject) => {
-      this._waiter = { resolve, reject, batch: true, max };
-    });
   }
 
-  return() {
-    this.close(cancelled("request stream cancelled"));
-    return Promise.resolve({ done: true, value: undefined });
+  /** Wakes everything waiting for a change of the response. */
+  #notify() {
+    const { resolve } = this.#changed;
+    this.#changed = deferred();
+    resolve();
   }
 
-  _takePendingBatch(max) {
-    const count = Math.min(Math.max(1, max), this._pending.length);
-    const values = Array.from({ length: count });
-    for (let i = 0; i < count; i++) {
-      const pending = this._pending.shift();
-      pending.resolve();
-      values[i] = pending.value;
+  /**
+   * Resolves when the response outcome is known, the call failed, or no read is in progress, which
+   * is when nothing more will be learned without the caller receiving.
+   */
+  async #outcomeKnown() {
+    while (this.#terminal === undefined && this.#failure === undefined && this.#pumping) {
+      await this.#changed.promise;
     }
-    return values;
   }
 
-  _wakeWaiter() {
-    if (this._waiter == null || this._pending.length === 0) {
-      return;
+  /**
+   * The error a failed request-side operation reports. A request side that the transport failed
+   * on its own, typically because the server stopped reading it, says little: the server's
+   * final status, or the failure of the response stream, explains it, so those are awaited.
+   */
+  async #explainUploadFailure(error) {
+    if (error !== this.#call.uploadFailure) {
+      return error;
     }
-
-    const waiter = this._waiter;
-    this._waiter = undefined;
-    if (waiter.batch) {
-      queueMicrotask(() => this._resolveBatchWaiter(waiter));
-      return;
+    await this.#outcomeKnown();
+    if (this.#terminal?.status !== undefined) {
+      return this.#terminal.error ?? cancelled(EarlyOk);
     }
-
-    const pending = this._pending.shift();
-    pending.resolve();
-    waiter.resolve({ done: false, value: pending.value });
-  }
-
-  _resolveBatchWaiter(waiter) {
-    if (this._pending.length > 0) {
-      waiter.resolve({ done: false, value: this._takePendingBatch(waiter.max) });
-    } else if (this._error != null) {
-      waiter.reject(this._error);
-    } else if (this._closed) {
-      waiter.resolve({ done: true, value: undefined });
-    } else {
-      this._waiter = waiter;
+    if (this.#call.signal.aborted) {
+      return this.#call.signal.reason;
     }
+    return this.#terminal?.error ?? error;
   }
 }
 
-function encodeRequestStream(requestType, requests, signal) {
-  const iterator = requestIterator(requests);
-  let done = false;
-  return {
-    [Symbol.asyncIterator]() {
-      return this;
-    },
-    async next() {
-      if (done) {
-        return { done: true, value: undefined };
-      }
-      const result = await nextRequest(iterator, signal);
-      if (result.done) {
-        done = true;
-        return { done: true, value: undefined };
-      }
-
-      return { done: false, value: marshalMessage(requestType, result.value) };
-    },
-    async nextBatch(max = RequestStreamBatchSize) {
-      if (done) {
-        return { done: true, value: undefined };
-      }
-      const result = await nextRequestBatch(iterator, signal, max);
-      if (result.done) {
-        done = true;
-        return { done: true, value: undefined };
-      }
-
-      return {
-        done: false,
-        value: result.value.map((value) => marshalMessage(requestType, value)),
-      };
-    },
-    async return() {
-      done = true;
-      if (signal?.aborted && typeof iterator.return === "function") {
-        await iterator.return();
-      }
-      return { done: true, value: undefined };
-    },
-  };
-}
+/** A client-streaming RPC: send requests, then close and receive the single response. */
+export class ClientStreamingCall {
+  #call;
 
-function requestIterator(requests) {
-  if (typeof requests?.[Symbol.asyncIterator] === "function") {
-    return requests[Symbol.asyncIterator]();
+  constructor(call) {
+    this.#call = call;
   }
 
-  if (typeof requests?.[Symbol.iterator] === "function") {
-    const iterator = requests[Symbol.iterator]();
-    return {
-      next() {
-        return Promise.resolve(iterator.next());
-      },
-      return() {
-        return Promise.resolve(
-          typeof iterator.return === "function"
-            ? iterator.return()
-            : { done: true, value: undefined },
-        );
-      },
-    };
+  /** Sends one request message. */
+  send(message) {
+    return this.#call.send(message);
   }
 
-  throw invalidArgument("request stream must be an async iterable or iterable");
-}
-
-function nextRequest(iterator, signal) {
-  return nextRequestResult(() => iterator.next(), signal);
-}
-
-async function nextRequestBatch(iterator, signal, max) {
-  if (typeof iterator.nextBatch === "function") {
-    return await nextRequestResult(() => iterator.nextBatch(max), signal);
+  /** Sends every message of requests, then closes the request stream; see the bidirectional call. */
+  sendAll(requests) {
+    return this.#call.sendAll(requests);
   }
 
-  const result = await nextRequest(iterator, signal);
-  return result.done ? result : { done: false, value: [result.value] };
-}
-
-function nextRequestResult(next, signal) {
-  if (signal?.aborted) {
-    return Promise.reject(signal.reason ?? cancelled("request stream cancelled"));
-  }
-  if (signal == null) {
-    return next();
+  /** Closes the request stream and returns the final response. */
+  async closeAndRecv() {
+    this.#call.closeSend().catch(() => {});
+    return await receiveSingleResponse(this.#call, "client-streaming");
   }
 
-  return new Promise((resolve, reject) => {
-    const onAbort = () => reject(signal.reason ?? cancelled("request stream cancelled"));
-    signal.addEventListener("abort", onAbort, { once: true });
-    next().then(
-      (value) => {
-        signal.removeEventListener("abort", onAbort);
-        resolve(value);
-      },
-      (error) => {
-        signal.removeEventListener("abort", onAbort);
-        reject(error);
-      },
-    );
-  });
-}
-
-async function* emptyAsyncIterable() {}
-
-function copyDefined(target, source) {
-  for (const [key, value] of Object.entries(source ?? {})) {
-    if (value !== undefined && key !== "metadata") {
-      target[key] = value;
-    }
+  /** Cancels the call unless it already finished. */
+  close(reason) {
+    return this.#call.close(reason);
   }
 }
 
-function mergeMetadata(base, override) {
-  const baseHasMetadata = hasMetadataEntries(base?.metadata);
-  const overrideHasMetadata = hasMetadataEntries(override?.metadata);
+/** The response stream of a server-streaming RPC. */
+export class ResponseStream {
+  #call;
 
-  if (!baseHasMetadata && !overrideHasMetadata) {
-    return EmptyMetadata;
+  constructor(call) {
+    this.#call = call;
   }
 
-  if (!overrideHasMetadata) {
-    return isPreparedCallOptions(base)
-      ? (base.metadata ?? EmptyMetadata)
-      : normalizeMetadata(base.metadata);
+  /** The final status after the stream ends, or the error that ended it. */
+  get status() {
+    return this.#call.status;
   }
 
-  if (!baseHasMetadata) {
-    return isPreparedCallOptions(override)
-      ? (override.metadata ?? EmptyMetadata)
-      : normalizeMetadata(override.metadata);
+  /**
+   * 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.
+   */
+  get headers() {
+    return this.#call.headers;
   }
 
-  const metadata = Object.assign(
-    Object.create(null),
-    isPreparedCallOptions(base) ? base.metadata : normalizeMetadata(base.metadata),
-    isPreparedCallOptions(override) ? override.metadata : normalizeMetadata(override.metadata),
-  );
-  validateMetadata(metadata);
-  return metadata;
-}
-
-function hasMetadataEntries(metadata) {
-  if (metadata == null) {
-    return false;
-  }
-  if (metadata instanceof Map) {
-    return metadata.size > 0;
+  /** Cancels the call unless it already finished. */
+  close(reason) {
+    return this.#call.close(reason);
   }
-  for (const _key in metadata) {
-    return true;
-  }
-  return false;
-}
 
-function hasDefinedOptions(options) {
-  for (const [key, value] of Object.entries(options ?? {})) {
-    if (key === "metadata") {
-      if (hasMetadataEntries(value)) {
-        return true;
-      }
-    } else if (value !== undefined) {
-      return true;
-    }
+  [Symbol.asyncIterator]() {
+    return this.#call[Symbol.asyncIterator]();
   }
-  return false;
 }
 
-function markPreparedCallOptions(options) {
-  Object.defineProperty(options, PreparedCallOptions, { value: true });
-  return options;
+function deferred() {
+  let resolve;
+  const promise = new Promise((resolvePromise) => {
+    resolve = resolvePromise;
+  });
+  return { promise, resolve };
 }
 
-function isPreparedCallOptions(options) {
-  return options?.[PreparedCallOptions] === true;
+function requestFields(rpc, kind) {
+  return { method: rpc.path, kind };
 }
 
-function saturatingAdd(left, right) {
-  const sum = left + right;
-  return Number.isSafeInteger(sum) ? sum : Number.MAX_SAFE_INTEGER;
+function validateResponseMetadata(metadata, what) {
+  try {
+    validateMetadata(metadata);
+  } catch (error) {
+    throw internal(`invalid response ${what}: ${error.statusMessage ?? error.message}`);
+  }
 }