@aventara/client 1.0.0-rc.1 → 1.0.0-rc.11

package/dist/emit/runtime.emitter.js

@@ -1,6 +1,7 @@
 import { FRAMEWORK_ERROR_CLASS_OF, OPERATION_CODES, VALIDATION_CODES, } from "@aventara/core/internal";
 import { AvProtocol } from "@aventara/core/protocol";
 import { entrypointHref } from "../config/config.resolver.js";
+import { AVCLIENT_REGENERATE, } from "./banner.emitter.js";
 import { moduleSpecifierWriter, } from "./module-style.interface.js";
 import { wireGrammarLiteral } from "./scalar.codec.js";
 export function emitDecimalModule() {
@@ -51,10 +52,13 @@ export function emitMetadataModule(protocol, entrypoint) {
             `export const DEFAULT_ENTRYPOINT = ${JSON.stringify(entrypointHref(entrypoint))};\n`,
     };
 }
+function contractMismatchSummary(regenerate) {
+    return `This client was generated against a ClientContract other than the one the server serves. Regenerate it with ${regenerate}.`;
+}
 const FRAMEWORK_ERROR_CLASSES = {
     AvAuthError: "The caller is not authenticated, or is not permitted to run the operation.",
     AvConflictError: "The operation conflicted with stored state, and nothing was written. A2008 fails the same way if sent again; A2013 and A2014 may succeed if sent again, and no retry is automatic.",
-    AvContractMismatchError: "This client was generated against a ClientContract other than the one the server serves. Regenerate it with `avclient generate`.",
+    AvContractMismatchError: contractMismatchSummary(AVCLIENT_REGENERATE),
     AvInternalError: "The server failed. Nothing in its cause is actionable; the diagnostics are in the server's logs.",
     AvNotFoundError: "A strict unique target does not exist.",
     AvProtocolError: "The request was not one the server could route or interpret: an unknown Resource or operation, a protocol version it does not speak, or a body, media type, size or method it refuses.",
@@ -152,8 +156,12 @@ export class AvTransportError extends Error {
 	}
 }
 `;
-export function emitErrorsModule() {
-    const classes = Object.entries(FRAMEWORK_ERROR_CLASSES).map(([name, summary]) => {
+export function emitErrorsModule(regenerate = AVCLIENT_REGENERATE) {
+    const summaries = {
+        ...FRAMEWORK_ERROR_CLASSES,
+        AvContractMismatchError: contractMismatchSummary(regenerate),
+    };
+    const classes = Object.entries(summaries).map(([name, summary]) => {
         const codes = ERROR_CODES.filter((code) => FRAMEWORK_ERROR_CLASS_OF[code] === name);
         return (`\n/** ${summary} Thrown for ${codes.join(", ")}. */\n` +
             `export class ${name} extends AvError<${codes.map((code) => JSON.stringify(code)).join(" | ")}> {\n` +
@@ -186,12 +194,49 @@ export function emitErrorsModule() {
             "}\n",
     };
 }
-export function emitTransportModule(style) {
+export function emitTransportModule(style, access = false) {
     return {
         path: "runtime/transport.ts",
-        source: transportModuleSource(moduleSpecifierWriter(style)),
+        source: transportModuleSource(moduleSpecifierWriter(style)) +
+            (access ? ASK_CAN_SOURCE : ""),
     };
 }
+const ASK_CAN_SOURCE = `
+/**
+ * Asks the policy every question in one request (\`POST /_access/can\`), each
+ * question's \`where\` in its wire forms, and resolves one boolean each, in order.
+ *
+ * @throws as {@link execute} does: the AvError subclass of a refusal (A2001 for a
+ *   Resource this client cannot reach, A2004 for a malformed question, A2009 past
+ *   the batch limit), AvTransportError when no framework envelope arrived.
+ */
+export async function askCan(
+	connection: TransportConnection,
+	questions: readonly unknown[],
+	options: AvCallOptions = {},
+): Promise<boolean[]> {
+	const operation = "$access.can";
+	if (!Array.isArray(questions)) {
+		throw new TypeError("$access.can takes a list of questions.");
+	}
+	const headers = requestHeaders(options);
+	const body = serializeWireBody({
+		questions: questions.map((question: unknown) =>
+			isRecord(question) && Object.hasOwn(question, "where")
+				? { ...question, where: encodeArguments(question["where"]) }
+				: question,
+		),
+	});
+	const response = await post(connection, "/_access/can", operation, headers, body, options.signal);
+	return decoded(operation, response.status, () => {
+		const data: unknown = response.data;
+		if (!Array.isArray(data) || data.length !== questions.length || !data.every((answer) => typeof answer === "boolean")) {
+			throw new TypeError("The answer must hold one boolean per question.");
+		}
+		return data as boolean[];
+	});
+}
+`;
 const IDENTITY_HEADERS = (() => {
     const { protocolVersion, contractHash, requestId } = AvProtocol.headers;
     const prefix = protocolVersion.slice(0, protocolVersion.indexOf("-"));
@@ -209,7 +254,7 @@ const IDENTITY_HEADERS = (() => {
 })();
 function transportModuleSource(from) {
     return `import { CLIENT_CONTRACT_HASH, PROTOCOL_VERSION } from ${from("../metadata")};
-import { decodeResult, encodeArguments, readArgument, serializeWireBody } from ${from("./codec")};
+import { decodeResult, encodeArguments, readArgument, serializeWireBody, unsentValues } from ${from("./codec")};
 import { DECODE_TABLE } from ${from("./descriptor")};
 import {
 	type AvCause,
@@ -224,7 +269,8 @@ import {
 } from ${from("./errors")};
 
 /**
- * The transport of Aventara protocol version 1: one POST per operation,
+ * The transport of Aventara protocol version 1: one POST per operation, or one
+ * POST /_all for an Operation Set of them,
  * sent with the protocol version and ClientContract hash, its response
  * read by the protocol's rule: A1xxx resolves with the envelope's data, every other
  * code throws its AvError subclass, and anything that is not a framework
@@ -252,6 +298,9 @@ const FRAMEWORK_HEADERS: Readonly<Record<string, string>> = {
 	[WIRE_PREFIX + ${JSON.stringify(IDENTITY_HEADERS.contractHash)}]: CLIENT_CONTRACT_HASH,
 };
 
+/** The media type of a streamed Operation Set answer: one JSON line per entry. */
+const NDJSON = "application/x-ndjson";
+
 /** The request id header: AvCallOptions.requestId sends it. */
 const REQUEST_ID_HEADER = WIRE_PREFIX + ${JSON.stringify(IDENTITY_HEADERS.requestId)};
 
@@ -262,9 +311,11 @@ export interface StructuralSignal {
 
 /** The request the transport hands to fetch. */
 export interface FetchInit {
-	readonly method: "POST";
+	/** POST, or GET for a cached read. */
+	readonly method: "POST" | "GET";
 	readonly headers: Readonly<Record<string, string>>;
-	readonly body: string;
+	/** The JSON body of a POST; a GET has none. */
+	readonly body?: string;
 	readonly signal?: PlatformSignal;
 }
 
@@ -272,6 +323,16 @@ export interface FetchInit {
 export interface FetchResponse {
 	readonly status: number;
 	text(): Promise<string>;
+	/** Read for an Operation Set's answer: its media type. */
+	readonly headers?: { get(name: string): string | null };
+	/** Read for a streamed Operation Set answer, where the runtime gives one. */
+	readonly body?: { getReader(): BodyReader } | null;
+}
+
+/** What the transport reads of a response body's stream. */
+export interface BodyReader {
+	read(): Promise<{ readonly done: boolean; readonly value?: Uint8Array | undefined }>;
+	cancel(reason?: unknown): Promise<void>;
 }
 
 /** The AvFetch API as far as the transport calls it, where the consumer's lib declares none. */
@@ -301,15 +362,30 @@ export interface TransportConnection {
 
 /** Per-call options. Never serialized into the operation body. */
 export interface AvCallOptions {
-	/** Aborts the request; the call rejects with what fetch rejected with. */
+	/**
+	 * Aborts this call, and only this call. Sent in an Operation Set, the call
+	 * rejects with the signal's reason (an AbortError) and the others go on; sent
+	 * alone, it aborts the request, and the call rejects with what fetch rejected
+	 * with. Aborted before it is sent, it is never sent.
+	 */
 	readonly signal?: PlatformSignal;
-	/** Extra request headers. The framework's own headers cannot be set here. */
+	/**
+	 * Extra request headers. The framework's own headers cannot be set here. A
+	 * call with headers is sent alone, never in an Operation Set.
+	 */
 	readonly headers?: Readonly<Record<string, string>>;
 	/**
 	 * Sent as the request id header (Aventara-Request-Id); the empty string is
-	 * absent. It wins over that header in headers, which it overwrites.
+	 * absent. It wins over that header in headers, which it overwrites. A call
+	 * with a request id is sent alone, never in an Operation Set.
 	 */
 	readonly requestId?: string;
+	/**
+	 * false sends this operation call to its own route, never in an Operation Set
+	 * (POST /_all) with the calls made beside it. A transaction is always
+	 * sent alone.
+	 */
+	readonly grouping?: boolean;
 }
 
 type SuccessCode = Exclude<AvOperationCode, AvOperationErrorCode>;
@@ -319,12 +395,132 @@ type Envelope =
 	| { readonly outcome: "data"; readonly code: SuccessCode; readonly data: unknown }
 	| { readonly outcome: "failure"; readonly code: AvOperationErrorCode; readonly cause: AvCause };
 
+/** What a refusal of an operation's arguments says. */
+const REFUSAL_MESSAGE = "Operation arguments failed framework validation.";
+
+/** What an undefined value the request would leave out is told. */
+const UNSENT_MESSAGE =
+	"Value must not be undefined: sent as JSON it would be left out, and the request would reach more rows.";
+
+/**
+ * Refuses arguments that hold an undefined value whose leaving out would reach more
+ * rows than the caller wrote (in a filter, a unique selector or a cursor, or a where,
+ * cursor, limit or offset left undefined), before anything is sent: JSON would drop
+ * it. Throws the AvValidationError (A2004) the server answers when it is handed such
+ * a value: one issue at each, with the server's code, its path under \`at\`
+ * (["arguments"] for a call, ["operations", i, "args"] for a plan step, whose index
+ * the cause names).
+ */
+export function refuseUnsentValues(
+	resource: string,
+	family: string,
+	variant: string,
+	args: unknown,
+	at: readonly (string | number)[],
+	operation?: number,
+): void {
+	const unsent = unsentValues(DECODE_TABLE, resource, family, variant, args);
+	if (unsent.length === 0) {
+		return;
+	}
+	const issues: readonly AvValidationIssue[] = Object.freeze(
+		unsent.map(({ path, code }) =>
+			Object.freeze({ path: Object.freeze([...at, ...path]), code, message: UNSENT_MESSAGE }),
+		),
+	);
+	throw frameworkErrorOf(
+		"A2004",
+		Object.freeze(
+			operation === undefined ? { message: REFUSAL_MESSAGE, issues } : { message: REFUSAL_MESSAGE, issues, operation },
+		),
+	);
+}
+
+/** One operation, checked and encoded when it was called: what any request for it sends. */
+export interface PreparedOperation {
+	readonly resource: string;
+	readonly family: string;
+	readonly variant: string;
+	/** How a failure names it: \`"Post" find.many\`. */
+	readonly label: string;
+	/** Its request headers: the framework's, and the caller's when it is sent alone. */
+	readonly headers: Readonly<Record<string, string>>;
+	/** The caller's headers alone (its request id among them): what a cached read's GET sends. */
+	readonly callerHeaders: Readonly<Record<string, string>>;
+	/** Its arguments in wire form, as JSON text: its own route's body. */
+	readonly body: string;
+}
+
+/**
+ * Checks and encodes one operation call, sending nothing: the checks
+ * {@link execute} runs before it sends, in its order, and with its errors.
+ */
+export function prepareOperation(
+	resource: string,
+	family: string,
+	variant: string,
+	args: Readonly<Record<string, unknown>>,
+	options: AvCallOptions = {},
+	check?: (resource: string, family: string, args: unknown) => void,
+): PreparedOperation {
+	refuseUnsentValues(resource, family, variant, args, ["arguments"]);
+	check?.(resource, family, args);
+	const label = JSON.stringify(resource) + " " + family + "." + variant;
+	const callerHeaders = callerHeadersOf(options);
+	const headers = { ...FRAMEWORK_HEADERS, ...callerHeaders };
+	const body = serializeWireBody(encodeArguments(argumentObject(args)));
+	return { resource, family, variant, label, headers, callerHeaders, body };
+}
+
+/**
+ * Sends one prepared operation to its own route and settles its envelope.
+ *
+ * @throws as {@link execute} does once its arguments are checked.
+ */
+export async function sendOperation(
+	connection: TransportConnection,
+	operation: PreparedOperation,
+	signal?: PlatformSignal,
+): Promise<unknown> {
+	const response = await post(connection, routeOf(operation), operation.label, operation.headers, operation.body, signal);
+	return decoded(operation.label, response.status, () => decodeResult(DECODE_TABLE, operation.resource, response.data));
+}
+
+/** An operation's own route: \`/_resources/<resource>/<family>/<variant>\`. */
+export function routeOf(operation: PreparedOperation): string {
+	return "/_resources/" + [operation.resource, operation.family, operation.variant].map(encodeURIComponent).join("/");
+}
+
+/**
+ * Sends one cached read as a GET to its own route with \`query\` (its \`q\` and
+ * \`v\`) and only the caller's headers, and settles its envelope as
+ * {@link sendOperation} does.
+ */
+export async function sendRead(
+	connection: TransportConnection,
+	operation: PreparedOperation,
+	query: string,
+	signal?: PlatformSignal,
+): Promise<unknown> {
+	const init: FetchInit =
+		signal === undefined
+			? { method: "GET", headers: operation.callerHeaders }
+			: { method: "GET", headers: operation.callerHeaders, signal };
+	const response = await received(connection, routeOf(operation) + "?" + query, operation.label, init);
+	return decoded(operation.label, response.status, () => decodeResult(DECODE_TABLE, operation.resource, response.data));
+}
+
 /**
  * Runs one operation: POSTs its arguments and settles its envelope.
  *
+ * @param check the client's own checks of the arguments, run before anything is sent
+ *   (the ClientContract's field validators, when it has any).
  * @returns the envelope's data when the code is A1xxx; null for A1001.
  * @throws the AvError subclass of any other code; AvTransportError when no
- *   framework envelope arrived; TypeError, before anything is sent, when the
+ *   framework envelope arrived; AvValidationError (A2004), before anything is sent,
+ *   when the arguments hold an undefined value JSON would leave out to widen the
+ *   request (see refuseUnsentValues), or when
+ *   \`check\` refuses the arguments; TypeError, before anything is sent, when the
  *   arguments are not a JSON-safe object or a request header is the framework's.
  *   A caller's abort rejects with what fetch rejected with.
  */
@@ -335,13 +531,9 @@ export async function execute(
 	variant: string,
 	args: Readonly<Record<string, unknown>>,
 	options: AvCallOptions = {},
+	check?: (resource: string, family: string, args: unknown) => void,
 ): Promise<unknown> {
-	const operation = JSON.stringify(resource) + " " + family + "." + variant;
-	const headers = requestHeaders(options);
-	const body = serializeWireBody(encodeArguments(argumentObject(args)));
-	const path = "/_resources/" + [resource, family, variant].map(encodeURIComponent).join("/");
-	const response = await post(connection, path, operation, headers, body, options);
-	return decoded(operation, response.status, () => decodeResult(DECODE_TABLE, resource, response.data));
+	return sendOperation(connection, prepareOperation(resource, family, variant, args, options, check), options.signal);
 }
 
 /**
@@ -361,7 +553,7 @@ export async function executePlan(
 	const operation = "the transaction";
 	const headers = requestHeaders(options);
 	const body = serializeWireBody(plan);
-	const response = await post(connection, "/_transactions", operation, headers, body, options);
+	const response = await post(connection, "/_transactions", operation, headers, body, options.signal);
 	return decoded(operation, response.status, () => {
 		if (!Array.isArray(response.data) || response.data.length !== resources.length) {
 			throw new TypeError("A committed plan's data must hold one result per operation.");
@@ -377,38 +569,279 @@ async function post(
 	operation: string,
 	headers: Readonly<Record<string, string>>,
 	body: string,
-	options: AvCallOptions,
+	signal: PlatformSignal | undefined,
 ): Promise<{ readonly status: number; readonly data: unknown }> {
+	const init: FetchInit = signal === undefined ? { method: "POST", headers, body } : { method: "POST", headers, body, signal };
+	return received(connection, path, operation, init);
+}
+
+/** One request and its settled envelope data, still in wire form. */
+async function received(
+	connection: TransportConnection,
+	path: string,
+	operation: string,
+	init: FetchInit,
+): Promise<{ readonly status: number; readonly data: unknown }> {
+	const signal = init.signal;
+	const response = await send(connection, path, operation, init);
+	let text: string;
+	try {
+		text = await response.text();
+	} catch (error) {
+		if (signal?.aborted === true) {
+			throw error;
+		}
+		throw new AvTransportError(
+			"The response to " + operation + " (HTTP " + response.status + ") could not be read.",
+			response.status,
+		);
+	}
+	return { status: response.status, data: settle(operation, response.status, text) };
+}
+
+/** One request, until its response arrives; a caller's abort rejects with what fetch rejected with. */
+async function send(
+	connection: TransportConnection,
+	path: string,
+	operation: string,
+	init: FetchInit,
+): Promise<FetchResponse> {
 	const url = connection.entrypoint + path;
-	const init: FetchInit =
-		options.signal === undefined
-			? { method: "POST", headers, body }
-			: { method: "POST", headers, body, signal: options.signal };
+	const signal = init.signal;
 
 	// Called unbound: a browser's fetch refuses a this that is not the global.
 	const fetch = connection.fetch as StructuralFetch;
-	let response: FetchResponse;
 	try {
-		response = await fetch(url, init);
+		return await fetch(url, init);
 	} catch (error) {
-		if (options.signal?.aborted === true) {
+		if (signal?.aborted === true) {
 			throw error;
 		}
 		throw new AvTransportError("The request for " + operation + " failed before any response arrived.", null);
 	}
-	let text: string;
+}
+
+/** How one entry of an Operation Set settled: its decoded data, or what its call rejects with. */
+export type EntryOutcome =
+	| { readonly kind: "value"; readonly value: unknown }
+	| { readonly kind: "error"; readonly error: unknown };
+
+/** What an Operation Set request came to: its entries answered, or no /_all on the server (A2002, A2000). */
+export type OperationSetAnswer = "answered" | "absent";
+
+/** How errors name an Operation Set request. */
+const SET_LABEL = "the Operation Set";
+
+/** The key the client gives the entry at \`index\`: an identifier, never the caller's. */
+export function operationSetKey(index: number): string {
+	return "k" + index;
+}
+
+/** One entry of an Operation Set's body, as JSON text, under \`key\`. */
+export function operationSetEntry(key: string, operation: PreparedOperation): string {
+	return (
+		JSON.stringify(key) +
+		':{"resource":' +
+		JSON.stringify(operation.resource) +
+		',"family":' +
+		JSON.stringify(operation.family) +
+		',"variant":' +
+		JSON.stringify(operation.variant) +
+		',"args":' +
+		operation.body +
+		"}"
+	);
+}
+
+/** The JSON text of an Operation Set's body, around its entries' text. */
+export function operationSetBody(entries: readonly string[]): string {
+	return '{"operations":{' + entries.join(",") + "}}";
+}
+
+/**
+ * Sends prepared operations as one Operation Set (\`POST /_all\`), each under a key
+ * the client makes, and hands each entry's outcome to \`answer\` as it arrives: line
+ * by line when the answer is streamed (NDJSON, asked for where the runtime can
+ * stream), all at once from a plain JSON answer. Each entry decodes and fails as
+ * its own route would answer it. A request refused whole answers every entry with
+ * that refusal, except A2002 or A2000, which answer none: the server has no /_all.
+ * A response that is not an Aventara answer answers each entry still waiting with
+ * AvTransportError. Never rejects.
+ */
+export async function sendOperationSet(
+	connection: TransportConnection,
+	operations: readonly PreparedOperation[],
+	signal: PlatformSignal | undefined,
+	answer: (index: number, outcome: EntryOutcome) => void,
+): Promise<OperationSetAnswer> {
+	const keys = new Map(operations.map((_, index) => [operationSetKey(index), index]));
+	const waiting = new Set(keys.values());
+	const settleEntry = (index: number, outcome: EntryOutcome): void => {
+		if (waiting.delete(index)) {
+			answer(index, outcome);
+		}
+	};
+	const failWaiting = (error: unknown): OperationSetAnswer => {
+		for (const index of [...waiting]) {
+			settleEntry(index, { kind: "error", error });
+		}
+		return "answered";
+	};
+	const entryOf = (index: number, status: number, envelope: unknown): EntryOutcome => {
+		const operation = operations[index] as PreparedOperation;
+		try {
+			const data = settleEnvelope(operation.label, status, envelope);
+			return { kind: "value", value: decoded(operation.label, status, () => decodeResult(DECODE_TABLE, operation.resource, data)) };
+		} catch (error) {
+			return { kind: "error", error };
+		}
+	};
+	const streaming = canStream();
+	const headers: Record<string, string> = streaming ? { ...FRAMEWORK_HEADERS, Accept: NDJSON } : { ...FRAMEWORK_HEADERS };
+	const body = operationSetBody(operations.map((operation, index) => operationSetEntry(operationSetKey(index), operation)));
+
+	let response: FetchResponse;
 	try {
-		text = await response.text();
+		response = await send(
+			connection,
+			"/_all",
+			SET_LABEL,
+			signal === undefined ? { method: "POST", headers, body } : { method: "POST", headers, body, signal },
+		);
 	} catch (error) {
-		if (options.signal?.aborted === true) {
-			throw error;
-		}
-		throw new AvTransportError(
-			"The response to " + operation + " (HTTP " + response.status + ") could not be read.",
+		return failWaiting(error);
+	}
+	const unreadable = (): AvTransportError =>
+		new AvTransportError("The response to " + SET_LABEL + " (HTTP " + response.status + ") could not be read.", response.status);
+	const malformed = (): AvTransportError =>
+		new AvTransportError(
+			"The response to " + SET_LABEL + " (HTTP " + response.status + ") is not an Aventara Operation Set answer.",
 			response.status,
 		);
+
+	const mediaType = (response.headers?.get("content-type") ?? "").split(";")[0]?.trim().toLowerCase();
+	if (mediaType !== NDJSON) {
+		let text: string;
+		try {
+			text = await response.text();
+		} catch {
+			return failWaiting(unreadable());
+		}
+		const envelope = envelopeOf(parseJson(text));
+		if (envelope === undefined) {
+			return failWaiting(
+				new AvTransportError(
+					"The response to " + SET_LABEL + " (HTTP " + response.status + ") is not an Aventara response envelope.",
+					response.status,
+				),
+			);
+		}
+		if (envelope.outcome === "failure") {
+			// A server without /_all: A2002 (no such route), or A2000 from a server older
+			// than Operation Sets, which reads /_all as a malformed operation path.
+			return envelope.code === "A2002" || envelope.code === "A2000"
+				? "absent"
+				: failWaiting(frameworkErrorOf(envelope.code, envelope.cause));
+		}
+		const entries = envelope.data;
+		if (!isRecord(entries)) {
+			return failWaiting(malformed());
+		}
+		for (const [key, index] of keys) {
+			if (Object.hasOwn(entries, key)) {
+				settleEntry(index, entryOf(index, response.status, entries[key]));
+			}
+		}
+		return failWaiting(
+			new AvTransportError(
+				"The response to " + SET_LABEL + " (HTTP " + response.status + ") holds no answer for this call.",
+				response.status,
+			),
+		);
+	}
+
+	// One line: {"key": …, "envelope": …}. false when it is not one of this request's.
+	const readLine = (line: string): boolean => {
+		if (line.trim() === "") {
+			return true;
+		}
+		const parsed = parseJson(line);
+		if (!isRecord(parsed) || !Object.hasOwn(parsed, "envelope") || typeof parsed["key"] !== "string") {
+			return false;
+		}
+		const index = keys.get(parsed["key"]);
+		if (index === undefined) {
+			return false;
+		}
+		settleEntry(index, entryOf(index, response.status, parsed["envelope"]));
+		return true;
+	};
+	const ended = (): OperationSetAnswer =>
+		failWaiting(
+			new AvTransportError(
+				"The response to " + SET_LABEL + " (HTTP " + response.status + ") ended before it answered this call.",
+				response.status,
+			),
+		);
+
+	const reader = streaming ? response.body?.getReader() : undefined;
+	if (reader === undefined) {
+		let text: string;
+		try {
+			text = await response.text();
+		} catch {
+			return failWaiting(unreadable());
+		}
+		for (const line of text.split("\\n")) {
+			if (!readLine(line)) {
+				return failWaiting(malformed());
+			}
+		}
+		return ended();
+	}
+	const decoder = textDecoder();
+	let buffer = "";
+	for (;;) {
+		let chunk: { readonly done: boolean; readonly value?: Uint8Array | undefined };
+		try {
+			chunk = await reader.read();
+		} catch {
+			return failWaiting(unreadable());
+		}
+		buffer += decoder.decode(chunk.value, { stream: !chunk.done });
+		let newline = buffer.indexOf("\\n");
+		while (newline !== -1) {
+			if (!readLine(buffer.slice(0, newline))) {
+				reader.cancel().catch((): void => undefined);
+				return failWaiting(malformed());
+			}
+			buffer = buffer.slice(newline + 1);
+			newline = buffer.indexOf("\\n");
+		}
+		if (chunk.done) {
+			return readLine(buffer) ? ended() : failWaiting(malformed());
+		}
 	}
-	return { status: response.status, data: settle(operation, response.status, text) };
+}
+
+/** What the transport reads of a TextDecoder, where the consumer's lib declares none. */
+interface StreamDecoder {
+	decode(input?: Uint8Array, options?: { readonly stream?: boolean }): string;
+}
+
+/** Whether this runtime can read an answer as it streams: a stream reader and a text decoder. */
+function canStream(): boolean {
+	const platform = globalThis as {
+		readonly ReadableStream?: { readonly prototype?: { readonly getReader?: unknown } };
+		readonly TextDecoder?: unknown;
+	};
+	return typeof platform.ReadableStream?.prototype?.getReader === "function" && typeof platform.TextDecoder === "function";
+}
+
+/** The platform's TextDecoder, for UTF-8 (canStream says one exists). */
+function textDecoder(): StreamDecoder {
+	const Platform = (globalThis as unknown as { readonly TextDecoder: new () => StreamDecoder }).TextDecoder;
+	return new Platform();
 }
 
 /**
@@ -435,7 +868,12 @@ function decoded<T>(operation: string, status: number, decode: () => T): T {
  * this client cannot read, which is what AvTransportError means.
  */
 function settle(operation: string, status: number, text: string): unknown {
-	const envelope = envelopeOf(parseJson(text));
+	return settleEnvelope(operation, status, parseJson(text));
+}
+
+/** Settles one parsed response body (or one Operation Set entry's envelope) by the same rule. */
+function settleEnvelope(operation: string, status: number, body: unknown): unknown {
+	const envelope = envelopeOf(body);
 	if (envelope === undefined) {
 		throw new AvTransportError(
 			"The response to " + operation + " (HTTP " + status + ") is not an Aventara response envelope.",
@@ -586,13 +1024,17 @@ function argumentObject(args: unknown): unknown {
 	return args;
 }
 
+/** The framework's headers plus the caller's (see callerHeadersOf). */
+function requestHeaders(options: AvCallOptions): Record<string, string> {
+	return { ...FRAMEWORK_HEADERS, ...callerHeadersOf(options) };
+}
+
 /**
- * The framework's headers plus the caller's, refusing a caller's that names one of
- * the framework's; then requestId, which overwrites any request id header the
- * caller set.
+ * The caller's headers, refusing one that names one of the framework's; then
+ * requestId, which overwrites any request id header the caller set.
  */
-function requestHeaders(options: AvCallOptions): Record<string, string> {
-	const headers: Record<string, string> = { ...FRAMEWORK_HEADERS };
+function callerHeadersOf(options: AvCallOptions): Record<string, string> {
+	const headers: Record<string, string> = {};
 	const owned = new Set(Object.keys(FRAMEWORK_HEADERS).map((name) => name.toLowerCase()));
 	for (const [name, value] of Object.entries(options.headers ?? {})) {
 		if (owned.has(name.toLowerCase())) {