@optimystic/db-p2p 1.0.0-beta.3 → 1.0.0

package/readme.md

@@ -390,7 +390,10 @@ const node = await createLibp2pNode({
 dropped from it, and `appendAnnounceAddrs` is ignored while it is non-empty. Use
 `appendAnnounceAddrs` alone when the automatically discovered addresses are still worth advertising.
 Both are straight passthroughs to libp2p's `addresses.announce` / `addresses.appendAnnounce`; an
-empty array means "unset".
+empty array means "unset". Because it hides relayed addresses, `announceAddrs` cannot be combined
+with a listen address naming a relay (the circuit address would never be advertised, so the
+reservation could never be confirmed); node creation rejects that combination before anything
+starts. Use `appendAnnounceAddrs` for such a node.
 
 ## Usage Examples
 
@@ -608,6 +611,13 @@ const node = await createLibp2pNode({
 });
 ```
 
+To be reachable through a relay instead, listen on `<relay address>/p2p-circuit` (the relay's
+full dial address, `/p2p/<relay id>` included). The node reserves a slot on that relay at start and
+keeps it itself afterwards, re-reserving after the relay restarts, after the connection to it drops,
+and across libp2p's routine renewal (`superviseRelayReservation` in `src/network/relay-reservation.ts`);
+node creation still rejects if the relay cannot be reserved at all. A bare `/p2p-circuit` listen
+address is left to the host, which then owns that reservation.
+
 #### React Native
 
 For React Native, import from `@optimystic/db-p2p/rn` instead of the root entrypoint.
@@ -640,12 +650,13 @@ before any other imports).
 |-----|-------------|-------|
 | `crypto.getRandomValues()` | @noble/hashes, @libp2p/crypto | RN 0.76+ New Architecture provides natively; fallback via e.g. `react-native-get-random-values` |
 | `crypto.subtle.digest()` | multiformats/hashes/sha2-browser | Async SHA-256/SHA-512 — implement via @noble/hashes |
-| `structuredClone()` | @optimystic/db-core | JSON round-trip is sufficient |
+| `structuredClone()` | @optimystic/db-core | JSON round-trip is sufficient. Still required: db-core calls it on ordinary read and write paths (applying an update to a block, for one), though never while a module loads |
 | `Promise.withResolvers()` | @libp2p/utils, @chainsafe/libp2p-yamux, it-queue | ES2024 — simple shim |
 | `AbortSignal.prototype.throwIfAborted()` | libp2p, @libp2p/circuit-relay-v2, it-pushable | DOM spec addition — simple shim |
 | Timer `.ref()` / `.unref()` | @optimystic/db-p2p, undici | Wrap Hermes numeric timer IDs in objects with no-op `.ref()`/`.unref()` methods; patch `clearTimeout`/`clearInterval` to unwrap |
 | `Event`, `CustomEvent`, `EventTarget` | libp2p, @libp2p/interface | Custom shim or npm `event-target-polyfill` |
 | `Intl.PluralRules` | moat-maker | English-only ordinal/cardinal shim is sufficient |
+| `TextDecoder` | multiformats, cborg, @optimystic/db-core, @optimystic/db-p2p, @optimystic/db-p2p-storage-rn | **multiformats and cborg construct it at module load, so without it the app fails at startup.** Optimystic's own packages construct it only on first use (see below), which does not make it optional. Expo SDK 52+ provides it; bare React Native's Hermes does not. A UTF-8-only shim is sufficient |
 | `WebSocket.prototype.bufferedAmount` | @libp2p/websockets | **RN declares the field but never assigns it, so it reads `undefined`.** See below — without this every WebSocket write hangs. |
 
 **`WebSocket.bufferedAmount` deserves its own note, because the symptom does not look like a
@@ -675,11 +686,24 @@ mechanism.
 | `stream` / `node:stream` | libp2p | `readable-stream` (npm) |
 | `buffer` / `node:buffer` | libp2p, multiformats | `buffer` (npm) |
 
+These four rows are known to be enough for a React Native build to accept the code: `yarn check:rn`
+(the private `packages/rn-bundle-check` workspace) bundles the `/rn` entry with exactly these aliases
+and the React Native 0.83 toolchain, then compiles the bundle with legacy Hermes. Its
+`test/shim-table-parity.test.mjs` fails if its aliases and this table drift apart, so change them
+together. It never runs the bundle, so the global polyfills above are not verified by it.
+
 **Built-in (no polyfill needed):**
 - `TextEncoder` — built-in to Hermes
-- `TextDecoder` — built-in to Expo SDK 52+ (UTF-8 only)
 - `BigInt` — built-in to Hermes since RN 0.70
 
+Optimystic's own code does not require a global `Buffer` — it encodes with `uint8arrays`, and lint (`no-restricted-globals` in `eslint.config.js`) keeps it that way.
+
+Optimystic's own code never touches `TextDecoder` or `structuredClone` while a module is loading: each `TextDecoder` is built the first time something decodes, and then reused. So importing `@optimystic/db-p2p/rn` (or db-core, or db-p2p-storage-rn) does not throw *because of Optimystic* on a runtime whose polyfill is not installed yet. **Both are still required polyfills**, and should still be installed before any other import: the third-party dependencies in the table construct `TextDecoder` at load and fail startup without it, and Optimystic needs both as soon as it decodes or applies an update. `NO_MODULE_SCOPE_TEXT_DECODER` in `eslint.config.js` keeps `TextDecoder` construction out of module scope in every package, and `test/module-load-globals.spec.ts` checks both globals at runtime (for the `/rn` entry's load path only, which includes db-core but not db-p2p-storage-rn). The spec loads the `/rn` entry in a fresh process and fails if any first-party module uses either global during the load.
+
+Optimystic's own code also does not call `AbortSignal.timeout` or `AbortSignal.any`, call `Promise.withResolvers`, or construct `DOMException` — none of those are guaranteed under Hermes. (It does call `signal.throwIfAborted()`, which stays a required host polyfill per the table above because libp2p needs it anyway.) Every deadline is an explicit `AbortController` plus a timer, cleared on every exit path (see `dialRelay` in `src/network/relay-reservation.ts` and `RepoClient.processRepoMessage` in `src/repo/client.ts`, which hand-rolls the "abort on any of several signals" case rather than using `AbortSignal.any` or the `any-signal` package — the code comment there explains why). `no-restricted-syntax` in `eslint.config.js` keeps it that way.
+
+**Dormant, not yet reached:** `crypto.subtle` on React Native provides only `digest`. `@libp2p/crypto`'s ECDSA/RSA import-export and `@libp2p/keychain`'s AES-GCM call other `crypto.subtle` methods and would throw if a host application reached them; nothing in Optimystic's own code path does — peer identity uses Ed25519 through `@noble/curves`/`@noble/hashes`, not the platform `crypto.subtle`. Revisit if a host ever adds a feature that reaches `@libp2p/keychain` or a non-Ed25519 key type on React Native.
+
 See the [Sereus reference-app-rn](https://github.com/gotchoices/sereus/tree/master/packages/reference-app-rn/polyfills) for working polyfill implementations.
 
 ### Ring Transitions

package/src/cluster/block-transfer-service.ts

@@ -1,5 +1,6 @@
 import type { Connection, Startable, Stream } from '@libp2p/interface';
-import type { IRepo, PeerId, IPeerNetwork, ActionId, ActionRev, GetBlockResult, IBlock, BlockId } from '@optimystic/db-core';
+import type { IRepo, PeerId, IPeerNetwork, ActionId, ActionRev, GetBlockResult, IBlock, BlockId, BlockUnavailableReason, CollectionId } from '@optimystic/db-core';
+import { peerIdFromString } from '@libp2p/peer-id';
 import { pipe } from 'it-pipe';
 import * as lp from 'it-length-prefixed';
 import { fromString as u8FromString } from 'uint8arrays/from-string';
@@ -327,7 +328,7 @@ export class BlockTransferService implements Startable {
 		for (const blockId of request.blockIds) {
 			const blockResult = result[blockId];
 			if (blockResult?.block) {
-				blocks[blockId] = Buffer.from(JSON.stringify(blockResult.block)).toString('base64');
+				blocks[blockId] = u8ToString(u8FromString(JSON.stringify(blockResult.block), 'utf8'), 'base64pad');
 			} else {
 				missing.push(blockId);
 			}
@@ -370,7 +371,7 @@ export class BlockTransferService implements Startable {
 			// Decode + parse the wire payload into an IBlock.
 			let block: IBlock;
 			try {
-				block = JSON.parse(Buffer.from(data, 'base64').toString('utf8')) as IBlock;
+				block = JSON.parse(u8ToString(u8FromString(data, 'base64pad'), 'utf8')) as IBlock;
 			} catch {
 				missing.push(blockId);
 				continue;
@@ -512,7 +513,7 @@ export class BlockTransferClient extends ProtocolClient {
 	): Promise<BlockTransferResponse> {
 		const blockData: Record<string, string> = {};
 		for (let i = 0; i < blockIds.length; i++) {
-			blockData[blockIds[i]!] = Buffer.from(blockDataBuffers[i]!).toString('base64');
+			blockData[blockIds[i]!] = u8ToString(blockDataBuffers[i]!, 'base64pad');
 		}
 		const request: BlockTransferRequest = {
 			type: 'push', blockIds, reason, blockData,
@@ -522,3 +523,130 @@ export class BlockTransferClient extends ProtocolClient {
 		return await this.processMessage<BlockTransferResponse>(request, this.protocol, { ...options, maxDataLength: MAX_BLOCK_MESSAGE_BYTES });
 	}
 }
+
+// --- The one push loop ---
+
+/** Why one peer did not confirm a pushed block. */
+export type PushRefusal = {
+	peerId: string;
+	/**
+	 * `rejected`: the peer ANSWERED and listed the block as missing — it did not persist it
+	 * (uncertified under its `requirePushCertificate`, unparseable, or a persist fault; the receiver
+	 * logs which). `unreachable`: the push threw — a dial failure, a deadline, a stream error.
+	 */
+	reason: 'rejected' | 'unreachable';
+	/** The thrown error's message, for `unreachable`. */
+	error?: string;
+};
+
+/**
+ * What {@link pushBlockToPeers} found and did. `no-local-data` and `unavailable` mean nothing was
+ * pushed: the first is "this node holds no revision of the block", the second is "this node could
+ * not find out" (a failed restore, an unmaterializable history) — a caller that prunes on the first
+ * must NOT prune on the second, or it drops a block it may well hold.
+ */
+export type PushBlockOutcome =
+	| { status: 'no-local-data' }
+	| { status: 'unavailable'; reason: BlockUnavailableReason }
+	| {
+		status: 'pushed';
+		/** The revision pushed — the source's `state.latest`. Absent for a repo that reports none. */
+		latest?: ActionRev;
+		/** From the pushed block's header, when it names a collection. */
+		collectionId?: CollectionId;
+		/** Whether a cohort commit proof travelled with the block. Without one a receiver running
+		 *  the default `requirePushCertificate` rejects it, so a `false` here with every peer
+		 *  `rejected` is "cannot place", not "cannot reach". */
+		certified: boolean;
+		/** Peers that hold the block now: each answered without listing it as missing. */
+		confirmed: string[];
+		refusals: PushRefusal[];
+		/** Peers not pushed to because {@link PushBlockOptions.stopAfterConfirmed} was reached first. */
+		skipped: string[];
+	};
+
+export interface PushBlockOptions {
+	/** Default `'replication'`. */
+	reason?: BlockTransferRequest['reason'];
+	/** The `/optimystic/<networkName>` prefix the receivers register their handler under. */
+	protocolPrefix?: string;
+	/** Stop once this many distinct peers have confirmed; the rest are reported `skipped`. Default:
+	 *  every peer is pushed to. */
+	stopAfterConfirmed?: number;
+	/** Per-peer deadlines forwarded to {@link BlockTransferClient.pushBlocks}; omitted = uncapped. */
+	dialTimeoutMs?: number;
+	responseTimeoutMs?: number;
+}
+
+const textEncoder = new TextEncoder();
+
+/**
+ * Push ONE locally held block to `peerIds`, in order: read it unpinned from `repo`, build its
+ * {@link PushCertification} from that same read, push it to each peer, and read each answer the one
+ * way that is true — a peer holds the block only when its response does NOT list the block as
+ * missing, because `handlePush` omits a block from `missing` only after persisting it (or already
+ * holding that revision). A round trip that returns is not a landed replica; a round trip that
+ * throws is not a refusal.
+ *
+ * This is the whole read-certify-push-interpret sequence every sender runs — the rebalance
+ * handoff and confirm (`BlockTransferCoordinator`), spread-on-churn, and the under-replication
+ * drain — so a change to how a block is placed is made here once. Retry, stopping condition and
+ * deadlines are the caller's: `stopAfterConfirmed` for "until one owner accepts" or "until the
+ * floor", the two deadlines for a sequential loop that must not hang on a silent peer, and the
+ * caller wraps the call in its own retry. It logs nothing per peer; the outcome carries what each
+ * caller's own diagnostics say.
+ *
+ * `repo` is the node's OWN store, so the read never consults the cluster and the certification
+ * comes from the proof this node retained; a repo without a proof accessor pushes meta-only
+ * (`certified: false`), which a default-configured receiver refuses.
+ */
+export async function pushBlockToPeers(
+	repo: ArchiveServingRepo,
+	peerNetwork: IPeerNetwork,
+	blockId: BlockId,
+	peerIds: readonly string[],
+	options: PushBlockOptions = {}
+): Promise<PushBlockOutcome> {
+	const result = (await repo.get({ blockIds: [blockId] }))[blockId];
+	if (result?.unavailable !== undefined) {
+		return { status: 'unavailable', reason: result.unavailable };
+	}
+	if (!result?.block) {
+		return { status: 'no-local-data' };
+	}
+	const blockData = textEncoder.encode(JSON.stringify(result.block));
+	const certification = await sourceBlockCertification(repo, blockId, result);
+	const reason = options.reason ?? 'replication';
+	const deadlines = { dialTimeoutMs: options.dialTimeoutMs, responseTimeoutMs: options.responseTimeoutMs };
+	const stopAfter = options.stopAfterConfirmed ?? Number.POSITIVE_INFINITY;
+
+	const confirmed: string[] = [];
+	const refusals: PushRefusal[] = [];
+	const skipped: string[] = [];
+	for (const peerIdStr of peerIds) {
+		if (confirmed.length >= stopAfter) {
+			skipped.push(peerIdStr);
+			continue;
+		}
+		try {
+			const client = new BlockTransferClient(peerIdFromString(peerIdStr), peerNetwork, options.protocolPrefix);
+			const response = await client.pushBlocks([blockId], [blockData], reason, certification, deadlines);
+			if (response.missing.includes(blockId)) {
+				refusals.push({ peerId: peerIdStr, reason: 'rejected' });
+			} else {
+				confirmed.push(peerIdStr);
+			}
+		} catch (err) {
+			refusals.push({ peerId: peerIdStr, reason: 'unreachable', error: err instanceof Error ? err.message : String(err) });
+		}
+	}
+	return {
+		status: 'pushed',
+		latest: result.state?.latest,
+		collectionId: result.block.header?.collectionId,
+		certified: certification.blockProofs !== undefined,
+		confirmed,
+		refusals,
+		skipped
+	};
+}

package/src/cluster/block-transfer.ts

@@ -1,18 +1,33 @@
 import type { IPeerNetwork } from '@optimystic/db-core';
-import { peerIdFromString } from '@libp2p/peer-id';
 import type { PartitionDetector } from './partition-detector.js';
 import type { RestorationCoordinator } from '../storage/restoration-coordinator.js';
 import type { ProofRetainingRepo } from '../storage/block-archive.js';
-import { BlockTransferClient, sourceBlockCertification } from './block-transfer-service.js';
+import { pushBlockToPeers, type PushBlockOutcome, type PushRefusal } from './block-transfer-service.js';
 import type { GrowthOutcome, RebalanceEvent } from './rebalance-monitor.js';
 import { createLogger } from '../logger.js';
 
 const log = createLogger('block-transfer');
 
+/** One line per peer that did not confirm, under the calling path's tag (`push` / `confirm`). */
+function logRefusals(path: 'push' | 'confirm', blockId: string, refusals: readonly PushRefusal[]): void {
+	for (const refusal of refusals) {
+		if (refusal.reason === 'unreachable') {
+			log('%s:peer-error block=%s peer=%s err=%s', path, blockId, refusal.peerId, refusal.error);
+		} else {
+			log('%s:peer-rejected block=%s peer=%s (receiver did not persist)', path, blockId, refusal.peerId);
+		}
+	}
+}
+
 export interface BlockTransferConfig {
 	/** Max concurrent transfers. Default: 4 */
 	maxConcurrency?: number;
-	/** Timeout per block transfer (ms). Default: 30000 */
+	/**
+	 * Timeout per block transfer (ms). Default: 30000. A pull is bounded as a whole. A push or
+	 * confirm is bounded PER PEER, as two deadlines of this length: one on the dial and one on the
+	 * reply (the `BlockTransferClient.pushBlocks` deadlines, which abort the dial and tear down a
+	 * silent stream rather than leaving them running).
+	 */
 	transferTimeoutMs?: number;
 	/** Retry attempts for failed transfers. Default: 2 */
 	maxRetries?: number;
@@ -347,52 +362,29 @@ export class BlockTransferCoordinator {
 		this.inFlight.add(key);
 
 		try {
+			const owners = newOwners.get(blockId);
+			if (!owners || owners.length === 0) {
+				failed.push(blockId);
+				return;
+			}
+
 			for (let attempt = 0; ; attempt++) {
 				await this.acquireSemaphore();
 				let pushed = false;
 				try {
-					const owners = newOwners.get(blockId);
-					if (!owners || owners.length === 0) {
-						failed.push(blockId);
-						return;
-					}
-
-					// Read block data from local storage
-					const result = await this.repo.get({ blockIds: [blockId] });
-					const blockResult = result[blockId];
-					if (!blockResult?.block) {
-						log('push:no-local-data block=%s', blockId);
+					// The shared read-certify-push loop, stopping at the FIRST new owner that accepts. A
+					// receiver running the default `requirePushCertificate` rejects a push with no proof,
+					// so a block whose proof this node never retained (pre-proof history, a diverged
+					// commit) simply fails to place here and is retried/kept as today.
+					const outcome = await this.pushBlock(blockId, owners, 1);
+					if (outcome.status !== 'pushed') {
+						log('push:no-local-data block=%s status=%s', blockId, outcome.status);
 						failed.push(blockId);
 						return;
 					}
-
-					const blockData = new TextEncoder().encode(JSON.stringify(blockResult.block));
-					// Revision metadata AND the cohort proof for that revision, from this one unpinned
-					// read. A receiver running the default `requirePushCertificate` rejects a push with
-					// no proof, so a block whose proof this node never retained (pre-proof history, a
-					// diverged commit) simply fails to place here and is retried/kept as today.
-					const certification = await sourceBlockCertification(this.repo, blockId, blockResult);
-
-					// Push to at least one new owner
-					for (const ownerPeerIdStr of owners) {
-						try {
-							const peerId = peerIdFromString(ownerPeerIdStr);
-							const client = new BlockTransferClient(peerId, this.peerNetwork, this.protocolPrefix);
-							const response = await this.withTimeout(
-								client.pushBlocks([blockId], [blockData], 'rebalance', certification),
-								this.transferTimeoutMs
-							);
-
-							if (response && !response.missing.includes(blockId)) {
-								pushed = true;
-								log('push:ok block=%s peer=%s', blockId, ownerPeerIdStr);
-								break;
-							}
-						} catch (err) {
-							log('push:peer-error block=%s peer=%s err=%s',
-								blockId, ownerPeerIdStr, (err as Error).message);
-						}
-					}
+					logRefusals('push', blockId, outcome.refusals);
+					pushed = outcome.confirmed.length > 0;
+					if (pushed) log('push:ok block=%s peer=%s', blockId, outcome.confirmed[0]);
 				} finally {
 					this.releaseSemaphore();
 				}
@@ -449,47 +441,28 @@ export class BlockTransferCoordinator {
 				await this.acquireSemaphore();
 				let confirmCount = 0;
 				try {
-					// Read block data from local storage once per attempt.
-					const result = await this.repo.get({ blockIds: [blockId] });
-					const blockResult = result[blockId];
-					if (!blockResult?.block) {
-						// No local bytes to prove replication with — cannot confirm; keep serving.
-						log('confirm:no-local-data block=%s', blockId);
+					// The shared read-certify-push loop, once per attempt, stopping once `floor` DISTINCT
+					// owners hold a current replica. A confirming holder either takes a certified replica
+					// or reports the block missing (see executePush).
+					const outcome = await this.pushBlock(blockId, candidateOwners, floor);
+					if (outcome.status !== 'pushed') {
+						// No local bytes to prove replication with — cannot confirm; keep serving. An
+						// `unavailable` read (this node could not find out what it holds) is folded in
+						// here as it always was: neither outcome can confirm anything.
+						log('confirm:no-local-data block=%s status=%s', blockId, outcome.status);
 						return { confirmed: false, confirmedPeers: allConfirmedPeers, noLocalData: true };
 					}
-
-					const blockData = new TextEncoder().encode(JSON.stringify(blockResult.block));
-					// See executePush: meta + proof are built together from this one unpinned read, so a
-					// confirming holder either takes a certified replica or reports the block missing.
-					const certification = await sourceBlockCertification(this.repo, blockId, blockResult);
-
-					// Count DISTINCT owners that hold a current replica; stop once the floor is reached.
-					const confirmedPeers = new Set<string>();
-					for (const ownerPeerIdStr of candidateOwners) {
-						if (confirmedPeers.size >= floor) break;
-						try {
-							const peerId = peerIdFromString(ownerPeerIdStr);
-							const client = new BlockTransferClient(peerId, this.peerNetwork, this.protocolPrefix);
-							const response = await this.withTimeout(
-								client.pushBlocks([blockId], [blockData], 'rebalance', certification),
-								this.transferTimeoutMs
-							);
-							if (response && !response.missing.includes(blockId)) {
-								confirmedPeers.add(ownerPeerIdStr);
-								// NOTE: allConfirmedPeers never un-records a peer. A holder that confirms in one
-								// round and reports `missing` in a later one stays recorded, on the reasoning that
-								// `handlePush` answers non-missing only after persisting. If the receiver ever
-								// gains a path that drops a just-persisted block (an eviction sweep, a rejected
-								// revision), the growth arm would record a peer that no longer holds a replica —
-								// intersect against the LAST round's confirmedPeers instead of unioning.
-								allConfirmedPeers.add(ownerPeerIdStr);
-							}
-						} catch (err) {
-							log('confirm:peer-error block=%s peer=%s err=%s',
-								blockId, ownerPeerIdStr, (err as Error).message);
-						}
+					logRefusals('confirm', blockId, outcome.refusals);
+					for (const peerId of outcome.confirmed) {
+						// NOTE: allConfirmedPeers never un-records a peer. A holder that confirms in one
+						// round and reports `missing` in a later one stays recorded, on the reasoning that
+						// `handlePush` answers non-missing only after persisting. If the receiver ever
+						// gains a path that drops a just-persisted block (an eviction sweep, a rejected
+						// revision), the growth arm would record a peer that no longer holds a replica —
+						// intersect against the LAST round's confirmed peers instead of unioning.
+						allConfirmedPeers.add(peerId);
 					}
-					confirmCount = confirmedPeers.size;
+					confirmCount = outcome.confirmed.length;
 				} finally {
 					this.releaseSemaphore();
 				}
@@ -511,6 +484,20 @@ export class BlockTransferCoordinator {
 		}
 	}
 
+	/**
+	 * This coordinator's binding of the shared push loop: rebalance reason, this node's protocol
+	 * prefix, and `transferTimeoutMs` as BOTH per-peer deadlines (see {@link BlockTransferConfig}).
+	 */
+	private pushBlock(blockId: string, peerIds: readonly string[], stopAfterConfirmed: number): Promise<PushBlockOutcome> {
+		return pushBlockToPeers(this.repo, this.peerNetwork, blockId, peerIds, {
+			reason: 'rebalance',
+			protocolPrefix: this.protocolPrefix,
+			stopAfterConfirmed,
+			dialTimeoutMs: this.transferTimeoutMs,
+			responseTimeoutMs: this.transferTimeoutMs
+		});
+	}
+
 	// --- Semaphore for concurrency limiting ---
 
 	private async acquireSemaphore(): Promise<void> {
@@ -538,10 +525,18 @@ export class BlockTransferCoordinator {
 		return new Promise(resolve => setTimeout(resolve, ms));
 	}
 
+	/**
+	 * Resolve `undefined` if `promise` has not settled within `ms`. The timer is cleared on either
+	 * outcome: left running, it outlived every pull, push and confirm by the full transfer timeout and
+	 * held a stopped node's process open that long (see `withDeadline` in `repo/coordinator-repo.ts`).
+	 */
 	private withTimeout<T>(promise: Promise<T>, ms: number): Promise<T | undefined> {
-		return Promise.race([
-			promise,
-			new Promise<undefined>(resolve => setTimeout(() => resolve(undefined), ms))
-		]);
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const timeout = new Promise<undefined>(resolve => {
+			timer = setTimeout(() => resolve(undefined), ms);
+		});
+		return Promise.race([promise, timeout]).finally(() => {
+			if (timer !== undefined) clearTimeout(timer);
+		});
 	}
 }