@remit/web-client 0.0.269 → 0.0.271

package/src/lib/bulk-actions.test.ts

@@ -11,6 +11,24 @@ import {
 	runPredicateAction,
 } from "./bulk-actions.js";
 
+/** A run nobody stops. */
+const neverAborted = (): AbortSignal => new AbortController().signal;
+
+/**
+ * What an aborted request does: reject with the signal's own reason, whether it
+ * was already aborted when the call was made or aborted while in flight.
+ */
+const abortable = (signal: AbortSignal): Promise<never> =>
+	new Promise((_, reject) => {
+		if (signal.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		signal.addEventListener("abort", () => reject(signal.reason), {
+			once: true,
+		});
+	});
+
 const ids = (count: number, prefix = "m"): string[] =>
 	Array.from({ length: count }, (_, i) => `${prefix}${i}`);
 
@@ -112,7 +130,6 @@ describe("chunkTargets", () => {
 });
 
 describe("runChunkedAction", () => {
-	const neverCancelled = () => false;
 	const noopProgress = () => undefined;
 
 	test("zero ids does nothing and reports done=0", async () => {
@@ -124,7 +141,7 @@ describe("runChunkedAction", () => {
 				return { successCount: chunk.length, failureCount: 0 };
 			},
 			noopProgress,
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.deepEqual(outcome, {
 			done: 0,
@@ -144,7 +161,7 @@ describe("runChunkedAction", () => {
 				return { successCount: chunk.length, failureCount: 0 };
 			},
 			noopProgress,
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.equal(calls.length, 2);
 		assert.equal(calls[0].length, BULK_ACTION_CHUNK_SIZE);
@@ -159,7 +176,7 @@ describe("runChunkedAction", () => {
 			input,
 			async (chunk) => ({ successCount: chunk.length, failureCount: 0 }),
 			noopProgress,
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.equal(outcome.done, input.length);
 		assert.deepEqual(outcome.failedIds, []);
@@ -168,16 +185,16 @@ describe("runChunkedAction", () => {
 	test("cancelling mid-run folds every unreached chunk into failedIds", async () => {
 		const input = targets(BULK_ACTION_CHUNK_SIZE * 3);
 		let calls = 0;
-		let cancelled = false;
+		const stop = new AbortController();
 		const outcome = await runChunkedAction(
 			input,
 			async (chunk) => {
 				calls++;
-				if (calls === 1) cancelled = true; // cancel after the first chunk lands
+				if (calls === 1) stop.abort(); // cancel after the first chunk lands
 				return { successCount: chunk.length, failureCount: 0 };
 			},
 			() => undefined,
-			() => cancelled,
+			stop.signal,
 		);
 		assert.equal(outcome.cancelled, true);
 		assert.equal(calls, 1);
@@ -195,7 +212,7 @@ describe("runChunkedAction", () => {
 				throw boom;
 			},
 			noopProgress,
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.equal(outcome.error, boom);
 		assert.equal(outcome.done, 0);
@@ -215,7 +232,7 @@ describe("runChunkedAction", () => {
 				return { successCount: chunk.length, failureCount: 0 };
 			},
 			noopProgress,
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.deepEqual(calls, [["a1", "a2"], ["b1"]]);
 		assert.equal(outcome.done, 3);
@@ -231,7 +248,7 @@ describe("runChunkedAction", () => {
 			],
 			async (chunk) => ({ successCount: chunk.length, failureCount: 0 }),
 			(p) => seen.push(p),
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.deepEqual(seen, [
 			{ done: 1, total: 2 },
@@ -240,7 +257,7 @@ describe("runChunkedAction", () => {
 	});
 
 	test("cancelling at an account boundary hands back the accounts never reached", async () => {
-		let cancelled = false;
+		const stop = new AbortController();
 		const outcome = await runChunkedAction(
 			[
 				{ id: "a1", accountId: "acct-a" },
@@ -248,11 +265,11 @@ describe("runChunkedAction", () => {
 				{ id: "c1", accountId: "acct-c" },
 			],
 			async (chunk) => {
-				cancelled = true;
+				stop.abort();
 				return { successCount: chunk.length, failureCount: 0 };
 			},
 			() => undefined,
-			() => cancelled,
+			stop.signal,
 		);
 		assert.equal(outcome.cancelled, true);
 		assert.equal(outcome.done, 1);
@@ -271,7 +288,7 @@ describe("runChunkedAction", () => {
 				return { successCount: chunk.length, failureCount: 0 };
 			},
 			() => undefined,
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.equal(outcome.error, boom);
 		assert.equal(outcome.done, 1);
@@ -291,7 +308,7 @@ describe("runChunkedAction", () => {
 				throw new Error("auth expired");
 			},
 			() => undefined,
-			neverCancelled,
+			neverAborted(),
 		);
 		// The run stops where it threw rather than trying the accounts behind it:
 		// what it hands back is exactly what is still untouched, which is what a
@@ -308,7 +325,7 @@ describe("runChunkedAction", () => {
 			input,
 			async (chunk) => ({ successCount: chunk.length, failureCount: 0 }),
 			(p) => progressCalls.push(p),
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.deepEqual(progressCalls, [
 			{ done: BULK_ACTION_CHUNK_SIZE, total: input.length },
@@ -318,7 +335,6 @@ describe("runChunkedAction", () => {
 });
 
 describe("runPredicateAction", () => {
-	const neverCancelled = () => false;
 	const noopProgress = () => undefined;
 
 	/** Builds a paged fixture: `pages[i]` is what the i-th call returns. */
@@ -338,7 +354,7 @@ describe("runPredicateAction", () => {
 			0,
 			async (chunk) => ({ successCount: chunk.length, failureCount: 0 }),
 			noopProgress,
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.deepEqual(outcome, { done: 0, failedIds: [], cancelled: false });
 	});
@@ -354,7 +370,7 @@ describe("runPredicateAction", () => {
 				return { successCount: chunk.length, failureCount: 0 };
 			},
 			noopProgress,
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.equal(deleteCalls.length, 1);
 		assert.equal(outcome.done, BULK_ACTION_CHUNK_SIZE);
@@ -374,7 +390,7 @@ describe("runPredicateAction", () => {
 				return { successCount: chunk.length, failureCount: 0 };
 			},
 			noopProgress,
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.equal(deleteCalls.length, 2);
 		assert.equal(outcome.done, 150);
@@ -397,7 +413,7 @@ describe("runPredicateAction", () => {
 				return { successCount: chunk.length, failureCount: 0 };
 			},
 			noopProgress,
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.deepEqual(deleteCalls, [
 			["a", "b"],
@@ -408,7 +424,7 @@ describe("runPredicateAction", () => {
 
 	test("cancelling mid-delete stops paging without inventing failedIds for unfetched pages", async () => {
 		let fetchCalls = 0;
-		let cancelled = false;
+		const stop = new AbortController();
 		const fetch = async (): Promise<FetchIdsPageResult> => {
 			fetchCalls++;
 			return { ids: ["a", "b"], continuationToken: "more" };
@@ -417,11 +433,11 @@ describe("runPredicateAction", () => {
 			fetch,
 			1000,
 			async (chunk) => {
-				cancelled = true; // cancel takes effect on the next loop iteration
+				stop.abort(); // cancel takes effect on the next loop iteration
 				return { successCount: chunk.length, failureCount: 0 };
 			},
 			() => undefined,
-			() => cancelled,
+			stop.signal,
 		);
 		assert.equal(outcome.cancelled, true);
 		assert.equal(fetchCalls, 1);
@@ -439,7 +455,7 @@ describe("runPredicateAction", () => {
 			100,
 			async (chunk) => ({ successCount: chunk.length, failureCount: 0 }),
 			noopProgress,
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.equal(outcome.error, boom);
 		assert.equal(outcome.done, 0);
@@ -455,12 +471,85 @@ describe("runPredicateAction", () => {
 				throw boom;
 			},
 			noopProgress,
-			neverCancelled,
+			neverAborted(),
 		);
 		assert.equal(outcome.error, boom);
 	});
 });
 
+// Regression for #113: a stop used to be a flag read between pages, so the
+// search or delete already on the wire ran to completion — up to a hundred
+// messages deleted after the press. The run's signal is now the call's signal.
+describe("stopping a run that has a request in flight", () => {
+	test("a bounded run reports the aborted batch as a clean stop, never an error", async () => {
+		const stop = new AbortController();
+		const calls: string[][] = [];
+		const outcome = await runChunkedAction(
+			targets(BULK_ACTION_CHUNK_SIZE * 3),
+			async (chunk, signal) => {
+				calls.push(chunk);
+				stop.abort();
+				return abortable(signal);
+			},
+			() => undefined,
+			stop.signal,
+		);
+		assert.equal(outcome.cancelled, true);
+		assert.equal(outcome.error, undefined);
+		assert.equal(calls.length, 1, "nothing further left after the stop");
+		assert.equal(outcome.done, 0);
+		// The aborted batch may or may not have been accepted server-side, so it
+		// comes back with the chunks never attempted rather than counted as done.
+		assert.equal(outcome.failedIds.length, BULK_ACTION_CHUNK_SIZE * 3);
+	});
+
+	test("a predicate run whose delete is aborted sends nothing more and reports a clean stop", async () => {
+		const stop = new AbortController();
+		let fetches = 0;
+		let deletes = 0;
+		const outcome = await runPredicateAction(
+			async () => {
+				fetches++;
+				return { ids: ["a", "b"], continuationToken: "more" };
+			},
+			1000,
+			async (_chunk, signal) => {
+				deletes++;
+				stop.abort();
+				return abortable(signal);
+			},
+			() => undefined,
+			stop.signal,
+		);
+		assert.equal(outcome.cancelled, true);
+		assert.equal(outcome.error, undefined);
+		assert.equal(deletes, 1);
+		assert.equal(fetches, 1);
+		assert.equal(outcome.done, 0);
+	});
+
+	test("a predicate run whose search page is aborted deletes nothing", async () => {
+		const stop = new AbortController();
+		let deletes = 0;
+		const outcome = await runPredicateAction(
+			async (_token, signal) => {
+				stop.abort();
+				return abortable(signal);
+			},
+			1000,
+			async (chunk) => {
+				deletes++;
+				return { successCount: chunk.length, failureCount: 0 };
+			},
+			() => undefined,
+			stop.signal,
+		);
+		assert.equal(outcome.cancelled, true);
+		assert.equal(outcome.error, undefined);
+		assert.equal(deletes, 0);
+	});
+});
+
 describe("honestProgress", () => {
 	// Regression for #109: the count and `runPredicateAction` resolve the same
 	// predicate independently, so the delete can outrun the frozen `total` it

package/src/lib/bulk-actions.ts

@@ -15,6 +15,18 @@
  * failure (auth, the write, or the enqueue) that takes out the whole batch and
  * stops the run.
  *
+ * Cancellation is an `AbortSignal` the caller owns, handed to every call the run
+ * makes (#113). Aborting ends the request in flight rather than waiting for it,
+ * so at most the batch already on the wire is at stake instead of a whole page;
+ * the run then stops before the next request leaves. A rejection raised while
+ * the signal is aborted is that abort, so it reports `cancelled` rather than an
+ * error — the user asked for it.
+ *
+ * That classification reads `signal.aborted`, deliberately, and not the shape of
+ * the rejection (`isAbortError`): a genuine failure that raced the user's Stop
+ * should read as a stop. The user pressed it and the run is over either way, and
+ * an error banner for a run they ended themselves is the wrong answer.
+ *
  * Pure, framework-agnostic, and independently testable — no React, no fetch.
  * `useEscalatedActions.ts` supplies the real `ApplyBatch`/`FetchIdsPage`
  * implementations (the generated SDK client) and owns the React state.
@@ -22,6 +34,9 @@
 
 export const BULK_ACTION_CHUNK_SIZE = 100;
 
+/** For a run with no Stop control to wire a signal to. */
+const NEVER_ABORTED = new AbortController().signal;
+
 /**
  * Resolves a promise to a discriminated result instead of throwing, so a
  * caller can branch on infrastructure failure as a value — the app's
@@ -104,7 +119,10 @@ export interface BatchResult {
 }
 
 /** Applies the action to one batch of ids (≤100) with a single bulk call. */
-export type ApplyBatch = (ids: string[]) => Promise<BatchResult>;
+export type ApplyBatch = (
+	ids: string[],
+	signal: AbortSignal,
+) => Promise<BatchResult>;
 
 export interface BulkActionProgress {
 	/** Ids the action has been applied to so far. */
@@ -122,6 +140,9 @@ export interface BulkActionOutcome {
 	 * cancellation or a thrown error, the chunks the bounded run never attempted
 	 * (see `runChunkedAction`). Empty in the predicate case, which re-resolves on
 	 * every run rather than handing back a remainder (see `runPredicateAction`).
+	 * An aborted batch is counted here too: aborting the request does not
+	 * un-send what the server already accepted, so its ids are "may not have
+	 * landed" rather than "did not", and every action here is idempotent.
 	 * There is no per-id failure source: a returned batch call counts every id in
 	 * it as accepted (see the module header).
 	 */
@@ -150,7 +171,7 @@ export const runChunkedAction = async (
 	targets: readonly BulkActionTarget[],
 	applyBatch: ApplyBatch,
 	onProgress: (progress: BulkActionProgress) => void,
-	isCancelled: () => boolean,
+	signal: AbortSignal,
 ): Promise<BulkActionOutcome> => {
 	const chunks = chunkTargets(targets);
 	const total = targets.length;
@@ -158,14 +179,15 @@ export const runChunkedAction = async (
 	const failedIds: string[] = [];
 
 	for (let i = 0; i < chunks.length; i++) {
-		if (isCancelled()) {
+		if (signal.aborted) {
 			failedIds.push(...chunks.slice(i).flat());
 			return { done, failedIds, cancelled: true };
 		}
 		const chunk = chunks[i];
-		const attempted = await attempt(applyBatch(chunk));
+		const attempted = await attempt(applyBatch(chunk, signal));
 		if (!attempted.ok) {
 			failedIds.push(...chunks.slice(i).flat());
+			if (signal.aborted) return { done, failedIds, cancelled: true };
 			onProgress({ done, total });
 			return { done, failedIds, cancelled: false, error: attempted.error };
 		}
@@ -194,6 +216,10 @@ export const runChunkedAction = async (
  * focused row, or a selection the surface already scoped — so nothing here
  * carries an account to split by. A caller with a cross-account selection
  * belongs on `runChunkedAction`, whose targets name one (#872).
+ *
+ * These callers have no Stop control to wire a signal to — a mutation over a
+ * handful of ids has no progress surface to stop from — so the run is handed a
+ * signal that never aborts.
  */
 export const runChunkedMutation = async (
 	ids: readonly string[],
@@ -206,7 +232,7 @@ export const runChunkedMutation = async (
 			return { successCount: chunk.length, failureCount: 0 };
 		},
 		() => {},
-		() => false,
+		NEVER_ABORTED,
 	);
 };
 
@@ -218,6 +244,7 @@ export interface FetchIdsPageResult {
 /** Fetches one page of matching message ids for the active predicate. */
 export type FetchIdsPage = (
 	continuationToken: string | undefined,
+	signal: AbortSignal,
 ) => Promise<FetchIdsPageResult>;
 
 /**
@@ -230,33 +257,36 @@ export type FetchIdsPage = (
  * `failedIds` for the unreached remainder, because those ids were never
  * fetched — there is nothing to hand back. A predicate resolves fresh on
  * every run (D2), so resuming is re-invoking this same function with the same
- * predicate.
+ * predicate. Aborting also ends the page or batch on the wire, so the run gives
+ * up at most the one request rather than the whole page it was mid-way through.
  */
 export const runPredicateAction = async (
 	fetchIdsPage: FetchIdsPage,
 	total: number,
 	applyBatch: ApplyBatch,
 	onProgress: (progress: BulkActionProgress) => void,
-	isCancelled: () => boolean,
+	signal: AbortSignal,
 ): Promise<BulkActionOutcome> => {
 	let done = 0;
 	const failedIds: string[] = [];
 	let token: string | undefined;
 
 	do {
-		if (isCancelled()) {
+		if (signal.aborted) {
 			return { done, failedIds, cancelled: true };
 		}
 
-		const fetched = await attempt(fetchIdsPage(token));
+		const fetched = await attempt(fetchIdsPage(token, signal));
 		if (!fetched.ok) {
+			if (signal.aborted) return { done, failedIds, cancelled: true };
 			return { done, failedIds, cancelled: false, error: fetched.error };
 		}
 		const page = fetched.value;
 
 		if (page.ids.length > 0) {
-			const attempted = await attempt(applyBatch(page.ids));
+			const attempted = await attempt(applyBatch(page.ids, signal));
 			if (!attempted.ok) {
+				if (signal.aborted) return { done, failedIds, cancelled: true };
 				return { done, failedIds, cancelled: false, error: attempted.error };
 			}
 			done += page.ids.length;

package/src/lib/error-classifier.test.ts

@@ -9,6 +9,7 @@ import {
 	isNetworkError,
 	isNotFound,
 	isServerError,
+	restartExpectedMeta,
 	shouldEscalate,
 	softErrorStatuses,
 } from "./error-classifier";
@@ -366,6 +367,13 @@ describe("meta.softErrorStatuses (one outcome owned, the rest not)", () => {
 		);
 	});
 
+	it("does not open the restart gap for a call site that never claimed one", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("bad gateway", 502), ownsNotFound, "nobody"),
+			true,
+		);
+	});
+
 	it("names the record's absence, whichever client raised it", () => {
 		assert.equal(isNotFound(new ApiError("gone", 404)), true);
 		assert.equal(isNotFound({ status: 404 }), true);
@@ -373,3 +381,54 @@ describe("meta.softErrorStatuses (one outcome owned, the rest not)", () => {
 		assert.equal(isNotFound(new TypeError("x is undefined")), false);
 	});
 });
+
+/**
+ * A self-update stops and starts the backend, so for those seconds the proxy in
+ * front of it has nothing to dial. That gap belongs to the surface that asked
+ * for the restart; every other 5xx, on that call site and on any other, is still
+ * the API reporting itself broken (#468).
+ */
+describe("meta.restartExpected (the gap in a restart this call site asked for)", () => {
+	it("does NOT escalate the gateway statuses answered while the backend is down", () => {
+		for (const status of [502, 503, 504]) {
+			assert.equal(
+				shouldEscalate(
+					new ApiError("gateway", status),
+					restartExpectedMeta,
+					"nobody",
+				),
+				false,
+				`a ${status} inside the restart window belongs to the update surface`,
+			);
+		}
+	});
+
+	it("escalates a 500 — a server that answered is up, and up and broken is not designed", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("boom", 500), restartExpectedMeta, "nobody"),
+			true,
+		);
+	});
+
+	it("escalates the same 502 without the claim, however soft the call site is", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("gateway", 502), undefined, "nobody"),
+			true,
+		);
+		assert.equal(
+			shouldEscalate(new ApiError("gateway", 502), { softError: true }, "user"),
+			true,
+		);
+	});
+
+	it("escalates a client bug raised inside the window", () => {
+		assert.equal(
+			shouldEscalate(
+				new TypeError("x is undefined"),
+				restartExpectedMeta,
+				"nobody",
+			),
+			true,
+		);
+	});
+});

package/src/lib/error-classifier.ts

@@ -143,6 +143,33 @@ const isSoftErrorMeta = (
 	return status !== undefined && owned.includes(status);
 };
 
+/**
+ * The statuses answered for the seconds a service is not there. Every `/api/*`
+ * request is proxied to apisix, which stays up while the backend behind it
+ * restarts and refuses in milliseconds — the 29ms 502 in #468, not a dial Caddy
+ * waited out. 503 and 504 are the same gap through a hop that answers
+ * differently.
+ */
+const RESTART_GAP_STATUSES = [502, 503, 504];
+
+/**
+ * The gap in a restart this call site asked for. A self-update stops and starts
+ * the backend on purpose, so the poll watching that run meets a proxy with
+ * nothing behind it — the designed shape of the operation the user pressed, not
+ * our API answering "I'm broken".
+ *
+ * A 500 is not in it: a server that answered is a server that is up, and up and
+ * broken is never designed.
+ */
+const isDesignedRestartGap = (
+	error: unknown,
+	meta: Record<string, unknown> | undefined,
+): boolean => {
+	if (meta?.restartExpected !== true) return false;
+	const status = getErrorStatus(error);
+	return status !== undefined && RESTART_GAP_STATUSES.includes(status);
+};
+
 /**
  * The single fail-fast decision: should this error escalate to the full-screen
  * fatal overlay? Default is YES — a non-2xx must never silently vanish.
@@ -151,7 +178,10 @@ const isSoftErrorMeta = (
  *  1. DEFAULT = escalate.
  *  2. A 5xx (500–599) ALWAYS escalates — no opt-out, even on a background
  *     refetch, even when the call site marked `meta.softError`. Our API
- *     answered "I'm broken"; that is never benign.
+ *     answered "I'm broken"; that is never benign. The single exception is a
+ *     502/503/504 on a call site that declared it is polling across a restart it
+ *     asked for (`meta.restartExpected`, #468): there the backend being gone is
+ *     the operation working, and that call site renders the wait itself.
  *  3. A client-side exception ALWAYS escalates, on the same terms. It is our
  *     bug; there is nothing for the user to retry and nothing to dismiss.
  *  4. A 401 on a request the user is waiting on ALWAYS escalates, on the same
@@ -173,7 +203,7 @@ export const shouldEscalate = (
 	meta?: Record<string, unknown>,
 	awaiting: Awaiting = "nobody",
 ): boolean => {
-	if (isServerError(error)) return true;
+	if (isServerError(error)) return !isDesignedRestartGap(error, meta);
 	if (isAbortError(error)) return false;
 	if (isNetworkError(error)) return false;
 	if (awaiting === "user" && isUnauthenticated(error)) return true;
@@ -209,6 +239,22 @@ export const softErrorStatuses = (
 	...statuses: number[]
 ): { softErrorStatuses: number[] } => ({ softErrorStatuses: statuses });
 
+/**
+ * The one opt-out from rule 2, for a request watching a restart the run it is
+ * following performs. Set it only while a run is known to be in flight — the
+ * update poll carries it while it holds a run it started or the server's last
+ * answer reported one going — because a 502 outside that window is the API being
+ * broken, which is exactly what rule 2 is for.
+ *
+ * A call site that sets this owns the whole wait, so the window outlives the
+ * budget: the give-up screen keeps polling a server it has stopped expecting,
+ * and a fatal page thrown over that verdict would replace the one screen that
+ * names the run and the log to read. A 500 from that same poll still escalates.
+ */
+export const restartExpectedMeta: { restartExpected: true } = {
+	restartExpected: true,
+};
+
 /** The record is not there. */
 export const isNotFound = (error: unknown): boolean =>
 	getErrorStatus(error) === 404;

package/src/lib/self-update-state.test.ts

@@ -72,6 +72,7 @@ function input(overrides: Partial<DeriveInput> = {}): DeriveInput {
 		dismissedRunId: null,
 		checkPress: null,
 		checkFailure: null,
+		sighting: null,
 		now: NOW,
 		...overrides,
 	};