@tikoci/centrs 0.1.6 → 0.1.8-next.0

package/src/protocols/mac-telnet-console.ts

@@ -42,9 +42,10 @@
  *     (name-level) gate — no `/console/inspect` table parsing needed.
  */
 
+import { absentMenuError } from "../absent-menu.ts";
 import { parseRouterOsPosition } from "../core/routeros-errors.ts";
 import { routerOsStringLiteral } from "../core/routeros-string.ts";
-import { CentrsError } from "../errors.ts";
+import { CentrsError, SYNTAX_REJECTED_REMEDIATION } from "../errors.ts";
 import {
 	type MacAddress,
 	type MacTelnetDatagramSink,
@@ -627,14 +628,16 @@ export function parseScriptFor(cli: string): string {
  *      with RouterOS's position suffix. All 425 corpus rows of this shape are
  *      the entire return; none appear embedded. Requiring both line-start and
  *      the `(line N column M)` suffix is what separates a real verdict from
- *      echoed body text.
+ *      echoed body text. The pinned 7.23.5/7.24.2/7.25beta3 captures add no
+ *      new heads beyond `syntax error`, `expected …` and `missing …`
+ *      (`missing closing brace`, `missing value for where`; GH#375).
  */
 const WRAPPED_BAD_PARAMETER = /\(evl\s+bad parameter\s+(\S+)/i;
 const WRAPPED_BAD_COMMAND = /\(<%%\s*bad command name\b/i;
 const BARE_BAD_PARAMETER =
 	/^[ \t]*bad parameter\s+(\S+)[^\n]*\(line \d+ column \d+\)/im;
 const BARE_SYNTAX =
-	/^[ \t]*(?:syntax error|bad command name|expected [a-z]+(?: [a-z]+)*)[^\n]*\(line \d+ column \d+\)/im;
+	/^[ \t]*(?:syntax error|bad command name|(?:expected|missing) [a-z]+(?: [a-z]+)*)[^\n]*\(line \d+ column \d+\)/im;
 
 /**
  * Classify the printed value of `:put [:parse "<cli>"]`. Grounded on CHR 7.23.3
@@ -646,8 +649,8 @@ const BARE_SYNTAX =
  * RouterOS emits them (see the grammar note above): wrapped as
  * `(evl bad parameter <name> (line N column M) /path)` /
  * `(<%% bad command name <name> (line N column M) a;b;c)`, or bare and
- * line-initial as `expected … (line N column M)` / `syntax error (line N column
- * M)`. A single `:parse` covers both the syntax and the unknown-attribute
+ * line-initial as `expected … (line N column M)` / `missing … (line N column
+ * M)` / `syntax error (line N column M)`. A single `:parse` covers both the syntax and the unknown-attribute
  * (name-level) gate on every transport — REST and native API expose the same text
  * in the `ret` value (HTTP 200 / `as-string`), the console transports print it.
  *
@@ -679,11 +682,13 @@ export function classifyParseResult(
 		});
 	}
 	if (WRAPPED_BAD_COMMAND.test(output) || BARE_SYNTAX.test(output)) {
+		// An absent menu reads as a syntax error; name it instead (GH#361).
+		const absent = absentMenuError(cli, output, position, via);
+		if (absent) throw absent;
 		throw new CentrsError({
 			code: "validation/syntax",
 			summary: "RouterOS rejected the command syntax while parsing it.",
-			remediation:
-				"Fix the RouterOS CLI syntax (quotes, brackets, attribute form), then retry.",
+			remediation: SYNTAX_REJECTED_REMEDIATION,
 			context: {
 				command: cli,
 				validationSource: `:put [:parse ...] over ${via}`,

package/src/protocols/native-api.ts

@@ -9,7 +9,7 @@
  * 2. A **session** (`NativeApiSession`) driven over an injectable byte stream
  *    (`NativeApiByteSink`), so scripted server bytes can drive it in tests and
  *    a real socket drives it in integration.
- * 3. A thin **TCP/TLS adapter** (`connectNativeApi`) built on `Bun.connect`.
+ * 3. A thin **TCP/TLS adapter** (`connectNativeApi`) built on Bun's built-in `node:net` / `node:tls` sockets.
  *
  * Wire format grounded against the MikroTik wiki API page and the canonical
  * `go-routeros` and `librouteros` implementations. Default ports: 8728 (plain),
@@ -20,8 +20,11 @@
  */
 
 import { createHash } from "node:crypto";
+import { createConnection, isIP } from "node:net";
+import { connect as connectTls } from "node:tls";
 import { mapRouterOsError } from "../core/routeros-errors.ts";
 import { CentrsError } from "../errors.ts";
+import { formatEndpoint } from "./endpoint.ts";
 
 const utf8Encoder = new TextEncoder();
 const utf8Decoder = new TextDecoder();
@@ -144,9 +147,32 @@ export function decodeLength(
 	return { value: value >>> 0, size };
 }
 
-/** Encode a single word: length prefix followed by its UTF-8 bytes. */
-export function encodeWord(word: string): Uint8Array {
-	const payload = utf8Encoder.encode(word);
+/**
+ * The bytes of a *byte string*: a string whose code units are each one byte
+ * (0–255), the shape `binary` commands carry file contents in. A code unit
+ * above 0xff has no byte, and `Buffer`'s latin1 encoder would silently keep
+ * only its low byte, so it is refused instead.
+ */
+export function byteStringBytes(value: string): Buffer {
+	for (let index = 0; index < value.length; index += 1) {
+		if (value.charCodeAt(index) > 0xff) {
+			throw new CentrsError({
+				code: "internal/byte-string",
+				summary: `A binary RouterOS word holds a character above U+00FF at offset ${index}.`,
+				remediation:
+					'This is a centrs bug; a binary command must carry each byte as one code unit (Buffer#toString("latin1")).',
+			});
+		}
+	}
+	return Buffer.from(value, "latin1");
+}
+
+/**
+ * Encode a single word: length prefix followed by its UTF-8 bytes, or, for a
+ * `binary` word, its byte-string bytes (see {@link byteStringBytes}).
+ */
+export function encodeWord(word: string, binary = false): Uint8Array {
+	const payload = binary ? byteStringBytes(word) : utf8Encoder.encode(word);
 	const prefix = encodeLength(payload.length);
 	const out = new Uint8Array(prefix.length + payload.length);
 	out.set(prefix, 0);
@@ -155,8 +181,11 @@ export function encodeWord(word: string): Uint8Array {
 }
 
 /** Encode a sentence: each word framed, terminated by a zero-length word. */
-export function encodeSentence(words: readonly string[]): Uint8Array {
-	const parts = words.map(encodeWord);
+export function encodeSentence(
+	words: readonly string[],
+	binary = false,
+): Uint8Array {
+	const parts = words.map((word) => encodeWord(word, binary));
 	const total = parts.reduce((sum, part) => sum + part.length, 0) + 1;
 	const out = new Uint8Array(total);
 	let cursor = 0;
@@ -168,17 +197,42 @@ export function encodeSentence(words: readonly string[]): Uint8Array {
 	return out;
 }
 
+/**
+ * Decode one received word. RouterOS sends words as raw bytes: UTF-8 for the
+ * text centrs reads, but `/file` contents are arbitrary bytes, which a UTF-8
+ * decode replaces with U+FFFD (#404). A `binary` word decodes as a byte string
+ * through `Buffer`'s latin1, never WHATWG `TextDecoder("latin1")`, which is
+ * windows-1252 and maps 0x80 to U+20AC.
+ */
+export function decodeWord(word: Uint8Array, binary = false): string {
+	return binary
+		? Buffer.from(word.buffer, word.byteOffset, word.byteLength).toString(
+				"latin1",
+			)
+		: utf8Decoder.decode(word);
+}
+
 /**
  * Incremental sentence reader. Accumulates TCP chunks and yields whole
- * sentences (arrays of decoded words) as they complete. Partial words and
- * partial length prefixes are buffered until the rest of the bytes arrive.
+ * sentences as they complete. Partial words and partial length prefixes are
+ * buffered until the rest of the bytes arrive.
  */
 export class SentenceReader {
 	private buffer: Uint8Array = new Uint8Array(0);
-	private current: string[] = [];
+	private current: Uint8Array[] = [];
 
-	/** Push a chunk and return any sentences completed by it. */
+	/** Push a chunk and return any sentences completed by it, UTF-8 decoded. */
 	push(chunk: Uint8Array): string[][] {
+		return this.pushRaw(chunk).map((words) =>
+			words.map((word) => decodeWord(word)),
+		);
+	}
+
+	/**
+	 * Push a chunk and return any completed sentences as raw word bytes, so the
+	 * caller picks each sentence's decoding (see {@link decodeWord}).
+	 */
+	pushRaw(chunk: Uint8Array): Uint8Array[][] {
 		if (chunk.length > 0) {
 			const next = new Uint8Array(this.buffer.length + chunk.length);
 			next.set(this.buffer, 0);
@@ -186,7 +240,7 @@ export class SentenceReader {
 			this.buffer = next;
 		}
 
-		const sentences: string[][] = [];
+		const sentences: Uint8Array[][] = [];
 		let offset = 0;
 		for (;;) {
 			const header = decodeLength(this.buffer, offset);
@@ -204,9 +258,8 @@ export class SentenceReader {
 				this.current = [];
 				continue;
 			}
-			this.current.push(
-				utf8Decoder.decode(this.buffer.subarray(wordStart, wordEnd)),
-			);
+			// Copy: the buffer is re-sliced and replaced as chunks arrive.
+			this.current.push(this.buffer.slice(wordStart, wordEnd));
 		}
 
 		if (offset > 0) {
@@ -232,6 +285,11 @@ export interface ApiReply {
 	tag?: string;
 	/** Raw words exactly as received, including the leading reply word. */
 	words: readonly string[];
+	/**
+	 * Set by `listen()` on a reply that ARRIVED after its signal aborted (the
+	 * replies a `/cancel` drains), however long it then waited in the queue.
+	 */
+	afterStop?: true;
 }
 
 /** Parse a raw sentence (array of words) into a structured reply. */
@@ -263,6 +321,19 @@ export function parseReply(words: readonly string[]): ApiReply {
 	return { type, attributes, tag, words };
 }
 
+const TAG_PREFIX = utf8Encoder.encode(".tag=");
+
+/** The `.tag=` value of a raw sentence; ASCII, so readable before decoding. */
+function sentenceTag(words: readonly Uint8Array[]): string | undefined {
+	for (let index = 1; index < words.length; index += 1) {
+		const word = words[index] as Uint8Array;
+		if (TAG_PREFIX.every((byte, at) => word[at] === byte)) {
+			return decodeWord(word.subarray(TAG_PREFIX.length));
+		}
+	}
+	return undefined;
+}
+
 /** Read an attribute by name (variable key avoids index-signature pitfalls). */
 export function readAttribute(
 	reply: ApiReply,
@@ -338,10 +409,18 @@ export interface NativeApiCommand {
 	queries?: readonly string[];
 	/** `.proplist` restriction (comma-joined when an array). */
 	proplist?: readonly string[] | string;
+	/**
+	 * Every word, sent and received, is a byte string (see
+	 * {@link byteStringBytes}), not UTF-8 text. Only `transfer`'s `/file`
+	 * contents need it (#404); a non-ASCII value such as a file name must be
+	 * passed as its UTF-8 byte string.
+	 */
+	binary?: boolean;
 }
 
 interface PendingCommand {
 	command: string;
+	binary: boolean;
 	records: ApiReply[];
 	trap?: ApiReply;
 	resolve: (replies: ApiReply[]) => void;
@@ -349,19 +428,18 @@ interface PendingCommand {
 }
 
 /**
- * A long-lived `/listen` subscription. Unlike {@link PendingCommand} it never
+ * An incremental command subscription. Unlike {@link PendingCommand} it never
  * buffers to a single resolve — each `!re` is pushed to the consumer as it
- * arrives, and the stream ends on `!done` (after a `/cancel`'s `interrupted`
- * trap) or fails on `!fatal`/transport closure.
+ * arrives, and ends on natural `!done`, acknowledged cancellation, or failure.
  */
 interface StreamingSubscription {
 	command: string;
-	/** An `!re` change frame arrived. */
+	/** An `!re` row or an `!empty` reply arrived. */
 	push: (reply: ApiReply) => void;
 	/** An `!trap` arrived (an `interrupted` trap is the normal `/cancel` path). */
 	trap: (reply: ApiReply) => void;
 	/** `!done` arrived — the listen closed. */
-	settle: () => void;
+	settle: (reply: ApiReply) => void;
 	/** `!fatal` or transport closure — the stream cannot continue. */
 	fail: (error: CentrsError) => void;
 }
@@ -404,9 +482,9 @@ export class NativeApiSession {
 
 	/** Feed inbound transport bytes into the parser. */
 	handleData(chunk: Uint8Array): void {
-		let sentences: string[][];
+		let sentences: Uint8Array[][];
 		try {
-			sentences = this.reader.push(chunk);
+			sentences = this.reader.pushRaw(chunk);
 		} catch (error) {
 			this.failAll(
 				error instanceof CentrsError
@@ -425,10 +503,21 @@ export class NativeApiSession {
 			if (words.length === 0) {
 				continue;
 			}
-			this.dispatch(parseReply(words));
+			const binary = this.isBinaryReply(words);
+			this.dispatch(parseReply(words.map((word) => decodeWord(word, binary))));
 		}
 	}
 
+	/** A binary command's data replies; its `!trap` message stays UTF-8 text. */
+	private isBinaryReply(words: readonly Uint8Array[]): boolean {
+		const tag = sentenceTag(words);
+		return (
+			tag !== undefined &&
+			this.pending.get(tag)?.binary === true &&
+			decodeWord(words[0] as Uint8Array) !== "!trap"
+		);
+	}
+
 	/** Notify the session the transport closed (optionally with an error). */
 	handleClose(error?: Error): void {
 		if (this.closed) {
@@ -458,6 +547,9 @@ export class NativeApiSession {
 				context: { attributes: reply.attributes },
 			});
 			this.failAll(this.closeError);
+			// Fatal ends the session locally too: a peer that sends !fatal but
+			// leaves TCP open must not keep the CLI alive after its error summary.
+			this.sink.close();
 			return;
 		}
 
@@ -496,17 +588,18 @@ export class NativeApiSession {
 		const subscription = this.subscriptions.get(tag);
 		if (subscription !== undefined) {
 			switch (reply.type) {
+				// `!empty` is a reply in its own right (a zero-row tick, an empty
+				// finite read), so a stream consumer sees it like a row (#402).
 				case "!re":
+				case "!empty":
 					subscription.push(reply);
 					return;
 				case "!trap":
 					subscription.trap(reply);
 					return;
-				case "!empty":
-					return;
 				case "!done":
 					this.subscriptions.delete(tag);
-					subscription.settle();
+					subscription.settle(reply);
 					return;
 				default:
 					return;
@@ -601,12 +694,13 @@ export class NativeApiSession {
 		return new Promise<ApiReply[]>((resolve, reject) => {
 			this.pending.set(tag, {
 				command: command.command,
+				binary: command.binary === true,
 				records: [],
 				resolve,
 				reject,
 			});
 			try {
-				this.sink.write(encodeSentence(words));
+				this.sink.write(encodeSentence(words, command.binary));
 			} catch (error) {
 				this.pending.delete(tag);
 				reject(
@@ -624,22 +718,44 @@ export class NativeApiSession {
 	}
 
 	/**
-	 * Open a `/listen` subscription and yield each `!re` change frame as it
-	 * arrives (the open-ended follow path; the listen command never sends `!done`
-	 * on its own). The generator ends cleanly when the listen is cancelled:
+	 * Stream a native command and yield each `!re` and `!empty` as it arrives. Finite commands
+	 * end on `!done`; `/listen` needs cancellation. The generator ends cleanly:
 	 * - via `options.signal` aborting — the subscription stays registered, so the
 	 *   resulting `interrupted` trap + `!done` are drained and the loop ends
 	 *   without throwing;
 	 * - via the consumer breaking out of the `for await` — `finally` sends
 	 *   `/cancel` best-effort (the subscription is already torn down, so the
 	 *   trap/`!done` are not awaited) and the generator returns.
-	 * A non-`interrupted` trap (e.g. a bad path) or `!fatal`/transport closure
-	 * throws. CHR-grounded (7.23.1): see `commands/api/AGENTS.md`.
+	 * A trap throws unless it acknowledges our cancellation; unsolicited
+	 * interruption, `!fatal`, and transport closure are failures. CHR grounding
+	 * lives in `commands/api/AGENTS.md` and the command examples.
+	 *
+	 * After an abort, `cancelGraceMs` bounds the wait for that acknowledgement: a
+	 * peer that never answers `/cancel` would otherwise hold the generator open
+	 * forever (#385). On expiry the generator ends without the router's
+	 * `!done` and `onCancelUnacknowledged` fires, so the caller can close the
+	 * session and report that the stop was local, not acknowledged.
 	 */
 	async *listen(
 		command: NativeApiCommand,
-		options: { signal?: AbortSignal; onListening?: () => void } = {},
+		options: {
+			signal?: AbortSignal;
+			onListening?: () => void;
+			cancelGraceMs?: number;
+			onCancelUnacknowledged?: () => void;
+			/** Terminal attributes, distinct from the streamed `!re` rows. */
+			onDone?: (attributes: Record<string, string>) => void;
+			/**
+			 * Every reply for this tag (`!re`, `!empty`, `!trap`, `!done`), called
+			 * synchronously as it is routed, before the generator yields it. Taps
+			 * on several concurrent commands see one connection's wire order.
+			 */
+			onReply?: (reply: ApiReply) => void;
+		} = {},
 	): AsyncGenerator<ApiReply, void, void> {
+		// A cancelled caller must not dispatch a command, especially now that
+		// this path streams writes as well as read-only change subscriptions.
+		if (options.signal?.aborted) return;
 		if (this.closed) {
 			throw (
 				this.closeError ??
@@ -658,6 +774,13 @@ export class NativeApiSession {
 		let ended = false;
 		let failure: CentrsError | undefined;
 		let trap: ApiReply | undefined;
+		let trapAcknowledgesCancel = false;
+		const assertNoFailure = (): void => {
+			if (failure) throw failure;
+			if (trap && !trapAcknowledgesCancel) {
+				throw this.trapToError(command.command, trap);
+			}
+		};
 		const signalWake = (): void => {
 			const resume = wake;
 			wake = undefined;
@@ -667,13 +790,21 @@ export class NativeApiSession {
 		this.subscriptions.set(tag, {
 			command: command.command,
 			push: (reply) => {
-				queue.push(reply);
+				options.onReply?.(reply);
+				queue.push(
+					options.signal?.aborted ? { ...reply, afterStop: true } : reply,
+				);
 				signalWake();
 			},
 			trap: (reply) => {
+				options.onReply?.(reply);
 				trap = reply;
+				trapAcknowledgesCancel =
+					isInterruptedTrap(reply) && !!options.signal?.aborted;
 			},
-			settle: () => {
+			settle: (reply) => {
+				options.onReply?.(reply);
+				options.onDone?.(reply.attributes);
 				ended = true;
 				signalWake();
 			},
@@ -702,10 +833,24 @@ export class NativeApiSession {
 		// can act on a real barrier rather than a blind timer.
 		options.onListening?.();
 
-		const onAbort = (): void => this.cancel(tag);
+		let graceTimer: ReturnType<typeof setTimeout> | undefined;
+		const onAbort = (): void => {
+			this.cancel(tag);
+			if (options.cancelGraceMs === undefined) return;
+			graceTimer = setTimeout(() => {
+				if (ended) return;
+				// Stop routing this tag and drop anything queued: a peer that ignores
+				// `/cancel` but keeps sending frames must not keep the loop draining.
+				this.subscriptions.delete(tag);
+				queue.length = 0;
+				ended = true;
+				options.onCancelUnacknowledged?.();
+				signalWake();
+			}, options.cancelGraceMs);
+		};
 		if (options.signal) {
 			if (options.signal.aborted) {
-				this.cancel(tag);
+				onAbort();
 			} else {
 				options.signal.addEventListener("abort", onAbort, { once: true });
 			}
@@ -731,19 +876,17 @@ export class NativeApiSession {
 					});
 				}
 			}
-			if (failure) {
-				throw failure;
-			}
-			if (trap && !isInterruptedTrap(trap)) {
-				throw this.trapToError(command.command, trap);
-			}
 		} finally {
+			clearTimeout(graceTimer);
 			options.signal?.removeEventListener("abort", onAbort);
 			this.subscriptions.delete(tag);
 			// Consumer broke out early (e.g. --count reached): tell the router to stop.
 			if (!ended && !this.closed) {
 				this.cancel(tag);
 			}
+			// Consumer return (including --count) must not hide a trap/close
+			// already received alongside the last row in the same TCP chunk.
+			assertNoFailure();
 		}
 	}
 
@@ -826,6 +969,8 @@ export interface ConnectNativeApiOptions {
 	rejectUnauthorized?: boolean;
 	/** Connection timeout in milliseconds. */
 	timeoutMs?: number;
+	/** Cancel TCP/TLS connection and login before dispatching any command. */
+	signal?: AbortSignal;
 }
 
 interface ConnectedNativeApi {
@@ -841,58 +986,83 @@ export async function connectNativeApi(
 ): Promise<ConnectedNativeApi> {
 	const port =
 		options.port ?? (options.tls ? NATIVE_API_TLS_PORT : NATIVE_API_PORT);
-	const endpoint = `${options.host}:${port}`;
+	const endpoint = formatEndpoint(options.host, port);
 	const timeoutMs = options.timeoutMs ?? 15_000;
+	options.signal?.throwIfAborted();
 
-	let session: NativeApiSession | undefined;
-	const connectPromise = Bun.connect({
-		hostname: options.host,
-		port,
-		...(options.tls
-			? {
-					tls: {
-						rejectUnauthorized: options.rejectUnauthorized ?? false,
-					},
-				}
-			: {}),
-		socket: {
-			data(_socket, data) {
-				session?.handleData(new Uint8Array(data));
-			},
-			close() {
-				session?.handleClose();
-			},
-			error(_socket, error) {
-				session?.handleClose(error);
-			},
-		},
-	}).catch((error: unknown) => {
-		throw mapConnectError(error, endpoint);
-	});
-
-	const socket = await withTimeout(connectPromise, timeoutMs, endpoint);
-	session = new NativeApiSession({
+	// Own the socket before TCP/TLS completes: aborting only the connect promise
+	// leaves a pending connection alive and can prevent the CLI from exiting.
+	const socket = options.tls
+		? connectTls({
+				host: options.host,
+				port,
+				rejectUnauthorized: options.rejectUnauthorized ?? false,
+				...(isIP(options.host) ? {} : { servername: options.host }),
+			})
+		: createConnection({ host: options.host, port });
+	socket.setNoDelay(true);
+	const session = new NativeApiSession({
 		endpoint,
 		sink: {
 			write(bytes) {
 				socket.write(bytes);
 			},
 			close() {
-				socket.end();
+				socket.destroy();
 			},
 		},
 	});
+	socket.on("data", (data: Buffer) => session.handleData(data));
+	socket.on("close", () => session.handleClose());
+	socket.on("error", (error) => session.handleClose(error));
 
+	const readyEvent = options.tls ? "secureConnect" : "connect";
+	const connectPromise = new Promise<void>((resolve, reject) => {
+		const cleanup = () => {
+			socket.removeListener(readyEvent, onConnect);
+			socket.removeListener("error", onError);
+			socket.removeListener("close", onClose);
+		};
+		const onConnect = () => {
+			cleanup();
+			resolve();
+		};
+		const onError = (error: Error) => {
+			cleanup();
+			reject(mapConnectError(error, endpoint));
+		};
+		const onClose = () => {
+			cleanup();
+			reject(
+				new CentrsError({
+					code: "transport/connection-closed",
+					summary: `The RouterOS API connection to ${endpoint} closed before it was ready.`,
+					remediation:
+						"Confirm the API service and network path are available.",
+				}),
+			);
+		};
+		socket.once(readyEvent, onConnect);
+		socket.once("error", onError);
+		socket.once("close", onClose);
+	});
+	const onAbort = (): void => session.close();
+	options.signal?.addEventListener("abort", onAbort, { once: true });
 	try {
+		options.signal?.throwIfAborted();
+		await withTimeout(connectPromise, timeoutMs, endpoint, options.signal);
 		await withTimeout(
 			session.login(options.username, options.password),
 			timeoutMs,
 			endpoint,
+			options.signal,
 		);
 	} catch (error) {
-		// Never leave a half-open socket when login times out or is rejected.
+		// Destroy even a pending connection when its deadline or login fails.
 		session.close();
 		throw error;
+	} finally {
+		options.signal?.removeEventListener("abort", onAbort);
 	}
 	return { session };
 }
@@ -901,9 +1071,17 @@ async function withTimeout<T>(
 	promise: Promise<T>,
 	timeoutMs: number,
 	endpoint: string,
+	signal?: AbortSignal,
 ): Promise<T> {
 	let handle: ReturnType<typeof setTimeout> | undefined;
+	let onAbort: (() => void) | undefined;
 	const timeout = new Promise<never>((_resolve, reject) => {
+		onAbort = () =>
+			reject(
+				signal?.reason ?? new DOMException("Operation cancelled", "AbortError"),
+			);
+		if (signal?.aborted) onAbort();
+		else signal?.addEventListener("abort", onAbort, { once: true });
 		handle = setTimeout(() => {
 			reject(
 				new CentrsError({
@@ -918,6 +1096,7 @@ async function withTimeout<T>(
 	try {
 		return await Promise.race([promise, timeout]);
 	} finally {
+		if (onAbort) signal?.removeEventListener("abort", onAbort);
 		if (handle !== undefined) {
 			clearTimeout(handle);
 		}