@remit/web-client 0.0.269 → 0.0.271

package/src/hooks/update-restart-escalation.render.test.ts

@@ -0,0 +1,340 @@
+/**
+ * The update poll against the app's own fail-fast sink (#468).
+ *
+ * An update stops and starts the backend on purpose, so the proxy in front of
+ * it answers 502 for the seconds it is gone. Every other test in this package
+ * mounts on the harness's plain `QueryClient`, which has no global sink, so none
+ * of them can see that the 502 took the whole screen before the update surface
+ * ever read it. Mounted here on the client `shell/index.tsx` builds.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, test } from "node:test";
+import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
+import { act, createElement } from "react";
+import { SelfUpdateOverlay } from "@/components/self-update/SelfUpdateOverlay";
+import { __resetFatalError, getCurrentFatalError } from "@/lib/fatal-error";
+import {
+	handleMutationCacheError,
+	handleQueryCacheError,
+} from "@/lib/query-error-handler";
+import {
+	APPLY_BUDGET_SECONDS,
+	NEVER_CAME_BACK_MARGIN_SECONDS,
+} from "@/lib/self-update-state";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, httpError, mockFetch } from "../test-support/http";
+import {
+	type SelfUpdateApi,
+	SelfUpdateProvider,
+	useSelfUpdate,
+} from "./use-system-update";
+import "@/lib/client";
+
+const BUDGET_MS =
+	(APPLY_BUDGET_SECONDS + NEVER_CAME_BACK_MARGIN_SECONDS) * 1000;
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+let api: SelfUpdateApi | undefined;
+
+beforeEach(() => {
+	__resetFatalError();
+});
+
+afterEach(() => {
+	__resetFatalError();
+	http?.restore();
+	http = undefined;
+	harness?.close();
+	harness = undefined;
+	api = undefined;
+});
+
+const available = {
+	currentVersion: "0.9.3",
+	check: {
+		status: "ok",
+		updateAvailable: true,
+		latestVersion: "0.9.4",
+		publishedAt: "2026-07-14T09:00:00.000Z",
+		summary: "Faster first sync.",
+		releaseNotesUrl: "https://example.test/notes",
+	},
+	run: null,
+};
+
+const accepted = {
+	currentVersion: "0.9.3",
+	check: { status: "ok", updateAvailable: true, latestVersion: "0.9.4" },
+	run: {
+		runId: "upd_1",
+		fromVersion: "0.9.3",
+		targetVersion: "0.9.4",
+		phase: "stopping",
+		outcome: null,
+		startedAt: "2026-07-20T11:59:30.000Z",
+		updatedAt: "2026-07-20T11:59:45.000Z",
+		message: "Restarting Remit on 0.9.4.",
+		logCommand: "remit logs --since 10m",
+	},
+};
+
+/**
+ * The run as a tab that never pressed install finds it: reported by the server,
+ * started just now, so the wait is measured from a start the page did not see.
+ */
+const reportedRunning = () => ({
+	...accepted,
+	run: { ...accepted.run, startedAt: new Date().toISOString() },
+});
+
+/** The client `shell/index.tsx` builds: the real global escalation sink. */
+const appQueryClient = (): QueryClient =>
+	new QueryClient({
+		queryCache: new QueryCache({ onError: handleQueryCacheError }),
+		mutationCache: new MutationCache({ onError: handleMutationCacheError }),
+		defaultOptions: {
+			queries: { retry: false },
+			mutations: { retry: false },
+		},
+	});
+
+const hook = (): SelfUpdateApi => {
+	if (!api) throw new Error("hook not mounted");
+	return api;
+};
+
+const dom = (): DomHarness => {
+	if (!harness) throw new Error("nothing mounted");
+	return harness;
+};
+
+/** Mount the surface, with `poll` deciding what each `GET /system/update` answers. */
+async function mount(poll: () => unknown): Promise<void> {
+	http = mockFetch((call) => {
+		if (call.path.endsWith("/system/update") && call.method === "GET") {
+			return poll();
+		}
+		return accepted;
+	});
+	const Probe = () => {
+		api = useSelfUpdate();
+		return null;
+	};
+	harness = createDomHarness({ queryClient: appQueryClient() });
+	harness.renderApp(
+		createElement(
+			SelfUpdateProvider,
+			null,
+			createElement(Probe),
+			createElement(SelfUpdateOverlay),
+		),
+	);
+	await settle();
+}
+
+async function settle(): Promise<void> {
+	for (let round = 0; round < 40; round += 1) {
+		await dom().flush();
+		await dom().wait(0);
+	}
+}
+
+/** Press install and wait for the run this page now holds to reach the surface. */
+async function install(): Promise<void> {
+	await act(async () => {
+		hook().install("0.9.4");
+		await dom().flush();
+	});
+	await dom().waitFor(() => {
+		const surface = hook().surface;
+		return surface.status === "ready" && surface.overlay.kind === "applying";
+	}, "the install to be accepted");
+}
+
+async function repoll(): Promise<void> {
+	await act(async () => {
+		hook().onRetryConnection();
+		await dom().flush();
+	});
+	await settle();
+}
+
+describe("the update poll across the restart it asked for (#468)", () => {
+	test("a 502 while a run is held keeps the update surface, not the fatal page", async () => {
+		let restarting = false;
+		await mount(() => (restarting ? httpError(502) : available));
+		await install();
+
+		restarting = true;
+		await repoll();
+
+		assert.equal(getCurrentFatalError(), null);
+		const surface = hook().surface;
+		assert.equal(
+			surface.status === "ready" &&
+				surface.section.status === "applying" &&
+				surface.section.phase,
+			"reconnecting",
+		);
+		assert.match(dom().html(), /Installing Remit 0\.9\.4/);
+	});
+
+	test("the same 502 with no run held escalates", async () => {
+		await mount(() => httpError(502));
+
+		assert.equal(getCurrentFatalError()?.error !== undefined, true);
+	});
+
+	test("a 502 with no run known from either source escalates", async () => {
+		// The server has answered, and what it said was that nothing is running.
+		let restarting = false;
+		await mount(() => (restarting ? httpError(502) : available));
+
+		restarting = true;
+		await repoll();
+
+		assert.equal(getCurrentFatalError()?.error !== undefined, true);
+	});
+
+	test("a connection refused inside the window stays soft, as any transport failure does", async () => {
+		let restarting = false;
+		await mount(() => {
+			if (restarting) throw new Error("connection refused");
+			return available;
+		});
+		await install();
+
+		restarting = true;
+		await repoll();
+
+		assert.equal(getCurrentFatalError(), null);
+		assert.match(dom().html(), /Installing Remit 0\.9\.4/);
+	});
+
+	test("a 500 while a run is held escalates — the server answered", async () => {
+		let broken = false;
+		await mount(() => (broken ? httpError(500) : available));
+		await install();
+
+		broken = true;
+		await repoll();
+
+		assert.equal(getCurrentFatalError()?.error !== undefined, true);
+	});
+
+	test("a 502 past the apply budget gives up loudly, still not fatally", async () => {
+		let restarting = false;
+		await mount(() => (restarting ? httpError(502) : available));
+		await install();
+
+		restarting = true;
+		const realNow = Date.now;
+		Date.now = () => realNow() + BUDGET_MS + 60_000;
+		try {
+			await repoll();
+
+			assert.equal(getCurrentFatalError(), null);
+			assert.match(dom().html(), /has not answered since the restart/);
+			assert.match(dom().html(), /remit logs/);
+			assert.doesNotMatch(dom().html(), /Installing Remit 0\.9\.4/);
+		} finally {
+			Date.now = realNow;
+		}
+	});
+});
+
+/**
+ * The overlay speaks for a run in any tab the server tells about it, so the
+ * restart has to be ridden there too — a second tab, or the initiating one after
+ * a reload, holds nothing of its own.
+ */
+describe("a tab that never pressed install (#468)", () => {
+	test("holds the applying overlay across a 502", async () => {
+		let restarting = false;
+		await mount(() => (restarting ? httpError(502) : reportedRunning()));
+		assert.match(dom().html(), /Installing Remit 0\.9\.4/);
+
+		restarting = true;
+		await repoll();
+
+		assert.equal(getCurrentFatalError(), null);
+		assert.match(dom().html(), /Installing Remit 0\.9\.4/);
+	});
+
+	test("gives up loudly past the same apply budget, and names the run's own log command", async () => {
+		let restarting = false;
+		await mount(() => (restarting ? httpError(502) : reportedRunning()));
+
+		restarting = true;
+		const realNow = Date.now;
+		Date.now = () => realNow() + BUDGET_MS + 60_000;
+		try {
+			await repoll();
+
+			assert.equal(getCurrentFatalError(), null);
+			assert.match(dom().html(), /has not answered since the restart/);
+			assert.match(dom().html(), /remit logs --since 10m/);
+			assert.doesNotMatch(dom().html(), /Installing Remit 0\.9\.4/);
+		} finally {
+			Date.now = realNow;
+		}
+	});
+
+	test("a box clock behind the browser's does not spend the budget before the first 502", async () => {
+		// `startedAt` is written on the box. Twenty minutes of skew is more than
+		// the whole budget, so measuring the wait from it would open the screen on
+		// the give-up and never show the install at all.
+		const skewed = () => ({
+			...accepted.run,
+			startedAt: new Date(Date.now() - BUDGET_MS - 60_000).toISOString(),
+		});
+		let restarting = false;
+		await mount(() =>
+			restarting ? httpError(502) : { ...accepted, run: skewed() },
+		);
+
+		restarting = true;
+		await repoll();
+
+		assert.equal(getCurrentFatalError(), null);
+		assert.match(dom().html(), /Installing Remit 0\.9\.4/);
+		assert.doesNotMatch(dom().html(), /has not answered since the restart/);
+
+		// The wait is this tab's, so it still runs out — on this tab's clock.
+		const realNow = Date.now;
+		Date.now = () => realNow() + BUDGET_MS + 60_000;
+		try {
+			await repoll();
+
+			assert.equal(getCurrentFatalError(), null);
+			assert.match(dom().html(), /has not answered since the restart/);
+		} finally {
+			Date.now = realNow;
+		}
+	});
+
+	test("says the service is unreachable once the run it knew about is finished", async () => {
+		let restarting = false;
+		await mount(() =>
+			restarting
+				? httpError(502)
+				: {
+						currentVersion: "0.9.4",
+						check: { status: "ok", updateAvailable: false },
+						run: { ...accepted.run, outcome: "succeeded" },
+					},
+		);
+
+		restarting = true;
+		await repoll();
+
+		const surface = hook().surface;
+		assert.equal(
+			surface.status === "ready" && surface.section.status,
+			"checkFailed",
+		);
+		assert.equal(getCurrentFatalError()?.error !== undefined, true);
+	});
+});

package/src/hooks/use-system-update.ts

@@ -37,7 +37,11 @@ import {
 	useRef,
 	useState,
 } from "react";
-import { shouldEscalate, softErrorMeta } from "@/lib/error-classifier";
+import {
+	restartExpectedMeta,
+	shouldEscalate,
+	softErrorMeta,
+} from "@/lib/error-classifier";
 import { reportFatalError } from "@/lib/fatal-error";
 import {
 	appliesSchemaMigration,
@@ -48,13 +52,30 @@ import {
 	type HeldRun,
 	isSurfaceAbsent,
 	mapUpdatePhase,
+	type RunSighting,
 	releaseFromCheck,
+	runInFlight,
 	type UpdateSurface,
 } from "@/lib/self-update-state";
 
 const IDLE_POLL_MS = 30_000;
 const RUN_POLL_MS = 5_000;
 
+/**
+ * The poll's own error UX, and — while a run is known to be in flight — the
+ * restart that run performs. Stopping and starting the backend is what the run
+ * is, so the gateway statuses answered while it is down belong to the surface
+ * below, which shows the phase and gives up loudly if the server never comes
+ * back (#468). Outside that window the poll carries no such claim.
+ *
+ * "Known" is either source: the run this page started and holds, or the run the
+ * server last reported as going. The overlay speaks for a run in any tab, so the
+ * window it rides has to open in any tab too — a second tab, or this one after a
+ * reload, holds nothing and would otherwise meet the restart with no claim on it.
+ */
+const POLL_META = softErrorMeta;
+const POLL_ACROSS_RESTART_META = { ...softErrorMeta, ...restartExpectedMeta };
+
 /**
  * How long a pressed check waits for the updater before the pane calls it a
  * failure. The backend only records the request; the updater picks it up on a
@@ -105,16 +126,25 @@ export function useSystemUpdate(): SelfUpdateApi {
 	const [dismissedRunId, setDismissedRunId] = useState<string | null>(null);
 	const [checkPress, setCheckPress] = useState<CheckPress | null>(null);
 	const [checkFailure, setCheckFailure] = useState<string | null>(null);
+	const [sighting, setSighting] = useState<RunSighting | null>(null);
 
 	const heldRef = useRef(held);
 	heldRef.current = held;
 	const pressRef = useRef(checkPress);
 	pressRef.current = checkPress;
 
+	// The last answer, which outlives the failed requests after it: a tab that
+	// never pressed install learns from here that it is inside a restart.
+	const lastKnown = queryClient.getQueryData<RemitImapSystemUpdateResponse>(
+		systemOperationsGetSystemUpdateQueryKey(),
+	);
+	const insideRestart =
+		held !== null || runInFlight(lastKnown, dismissedRunId) !== null;
+
 	const query = useQuery({
 		...systemOperationsGetSystemUpdateOptions(),
 		retry: false,
-		meta: { softError: true },
+		meta: insideRestart ? POLL_ACROSS_RESTART_META : POLL_META,
 		refetchInterval: (query) =>
 			pollInterval(
 				query.state.error,
@@ -135,9 +165,26 @@ export function useSystemUpdate(): SelfUpdateApi {
 		dismissedRunId,
 		checkPress,
 		checkFailure,
+		sighting,
 		now: Date.now(),
 	});
 
+	// Stamp the run the server reports, once, off this tab's clock. The stamp is
+	// what the give-up is measured against, so it must not move while the server
+	// is unreachable — and it must not carry over to the next run.
+	const reported = runInFlight(query.data, dismissedRunId);
+	useEffect(() => {
+		if (reported === null) {
+			setSighting((current) => (current === null ? current : null));
+			return;
+		}
+		setSighting((current) =>
+			current !== null && current.runId === reported.runId
+				? current
+				: { runId: reported.runId, observedAt: Date.now() },
+		);
+	}, [reported]);
+
 	const shownRunIdRef = useRef<string | null>(null);
 	shownRunIdRef.current =
 		derived.surface.status === "ready" && "runId" in derived.surface.section

package/src/hooks/useEscalatedActions.ts

@@ -84,7 +84,9 @@ export interface UseEscalatedActionsResult {
 	 *  selection to that predicate once it answers. */
 	escalate: () => void;
 	/**
-	 * Stop whatever's running — the count or an action — at the next boundary.
+	 * Stop whatever's running — the count or an action. The request in flight is
+	 * aborted and nothing further leaves (#113); a delete the server has already
+	 * accepted still applies, so the batch on the wire is what a stop is worth.
 	 * A no-op when nothing is running. The only thing that ends a run in
 	 * flight: leaving the selection, the wizard or the search does not.
 	 */
@@ -147,7 +149,10 @@ export const useEscalatedActions = ({
 	const [progress, setProgress] = useState<BulkActionProgress | undefined>(
 		undefined,
 	);
-	const cancelRef = useRef(false);
+	// Cancellation is the signal every call the run makes is issued under, so a
+	// stop ends the request on the wire instead of waiting for it to come back
+	// (#113). Replaced, never reused, at the start of each count and each run.
+	const abortRef = useRef<AbortController | undefined>(undefined);
 	// True from the moment a run starts until its outcome is in hand. A run is
 	// mail already leaving the mailbox, so nothing that merely changes what the
 	// list is showing gets to end it — only `stop`.
@@ -170,7 +175,7 @@ export const useEscalatedActions = ({
 	// against and reports what it reached, wherever the list moved on to.
 	// biome-ignore lint/correctness/useExhaustiveDependencies: enabled/predicateKey are trigger-only — the reset itself reads neither.
 	useEffect(() => {
-		if (!runningRef.current) cancelRef.current = true;
+		if (!runningRef.current) abortRef.current?.abort();
 		setPhase({ kind: "idle" });
 	}, [enabled, predicateKey]);
 
@@ -179,10 +184,11 @@ export const useEscalatedActions = ({
 
 	const fetchPagesOf = useCallback(
 		(query: EscalationSearchQuery): FetchIdsPage =>
-			async (continuationToken) => {
+			async (continuationToken, signal) => {
 				const { data } = await threadOperationsSearchThreads({
 					path: { mailboxId },
 					query: { ...query, continuationToken, limit: PAGE_SIZE },
+					signal,
 					throwOnError: true,
 				});
 				return {
@@ -198,27 +204,32 @@ export const useEscalatedActions = ({
 	 * resolves it (#509). One count-only request: `limit` is a page size and has
 	 * no bearing on the answer, so nothing is paged to arrive at it.
 	 */
-	const fetchMatchCount = useCallback(async (): Promise<number> => {
-		const { data } = await threadOperationsSearchThreads({
-			path: { mailboxId },
-			query: { ...searchQueryRef.current, count: true, results: false },
-			throwOnError: true,
-		});
-		if (data.count === undefined) {
-			throw new Error("the search returned no count for the selection");
-		}
-		return data.count;
-	}, [mailboxId]);
+	const fetchMatchCount = useCallback(
+		async (signal: AbortSignal): Promise<number> => {
+			const { data } = await threadOperationsSearchThreads({
+				path: { mailboxId },
+				query: { ...searchQueryRef.current, count: true, results: false },
+				signal,
+				throwOnError: true,
+			});
+			if (data.count === undefined) {
+				throw new Error("the search returned no count for the selection");
+			}
+			return data.count;
+		},
+		[mailboxId],
+	);
 
 	const applyBatchFor = useCallback(
 		(action: EscalatedAction): ApplyBatch =>
-			async (ids: string[]) => {
+			async (ids: string[], signal: AbortSignal) => {
 				if (action.kind === "move") {
 					const { data } = await messageBulkOperationsMoveMessages({
 						body: {
 							messageIds: ids,
 							destinationMailboxId: action.destinationMailboxId,
 						},
+						signal,
 						throwOnError: true,
 					});
 					return data;
@@ -226,12 +237,14 @@ export const useEscalatedActions = ({
 				if (action.kind === "markRead") {
 					const { data } = await messageBulkOperationsUpdateFlags({
 						body: { messageIds: ids, isRead: true },
+						signal,
 						throwOnError: true,
 					});
 					return data;
 				}
 				const { data } = await messageBulkOperationsDeleteMessages({
 					body: { messageIds: ids },
+					signal,
 					throwOnError: true,
 				});
 				return data;
@@ -267,17 +280,24 @@ export const useEscalatedActions = ({
 	);
 
 	const escalate = useCallback(() => {
-		cancelRef.current = false;
+		const controller = new AbortController();
+		abortRef.current = controller;
 		setPhase({ kind: "counting" });
-		fetchMatchCount().then(
+		fetchMatchCount(controller.signal).then(
 			(total) => {
-				if (cancelRef.current) {
+				if (controller.signal.aborted) {
 					setPhase({ kind: "idle" });
 					return;
 				}
 				setPhase({ kind: "escalated", total });
 			},
 			(error: unknown) => {
+				// A stopped count rejects with its own abort. That is the press the
+				// user made, not a failure to report back to them.
+				if (controller.signal.aborted) {
+					setPhase({ kind: "idle" });
+					return;
+				}
 				pushError(
 					buildMutationErrorBanner(
 						"Couldn't count matching messages",
@@ -291,12 +311,12 @@ export const useEscalatedActions = ({
 	}, [fetchMatchCount, pushError]);
 
 	const stop = useCallback(() => {
-		cancelRef.current = true;
+		abortRef.current?.abort();
 	}, []);
 
 	const clear = useCallback(() => {
 		if (runningRef.current) return;
-		cancelRef.current = true;
+		abortRef.current?.abort();
 		setPhase({ kind: "idle" });
 	}, []);
 
@@ -305,7 +325,8 @@ export const useEscalatedActions = ({
 			action: EscalatedAction,
 			targets?: readonly BulkActionTarget[],
 		): Promise<BulkRunOutcome> => {
-			cancelRef.current = false;
+			const controller = new AbortController();
+			abortRef.current = controller;
 			runningRef.current = true;
 			setRunningAction(action);
 			// Read before the run clears the phase below, so a refusal can say how
@@ -334,14 +355,14 @@ export const useEscalatedActions = ({
 								targets,
 								applyBatch,
 								onProgress,
-								() => cancelRef.current,
+								controller.signal,
 							)
 						: await runPredicateAction(
 								runPages,
 								phase.kind === "escalated" ? phase.total : 0,
 								applyBatch,
 								onProgress,
-								() => cancelRef.current,
+								controller.signal,
 							);
 			} finally {
 				runningRef.current = false;

package/src/lib/bulk-action-copy.test.ts

@@ -68,19 +68,29 @@ describe("bulkActionFailureTitle", () => {
 });
 
 describe("a run that stopped short of its match", () => {
-	test("states what it reached and that the rest is untouched", () => {
+	test("states what it reached and what became of the rest", () => {
 		assert.equal(bulkActionStoppedTitle(1200), "Stopped after 1,200");
 		assert.equal(
 			bulkActionStoppedDetail("delete", 1200, 3412),
-			"1,200 of 3,412 moved to Trash. Nothing was sent for the rest, so they are untouched.",
+			"1,200 of 3,412 moved to Trash. The rest were not sent, apart from the ones already on their way when you stopped — those may still have gone through.",
 		);
 		assert.equal(
 			bulkActionStoppedDetail("markRead", 1200, 3412),
-			"1,200 of 3,412 marked as read. Nothing was sent for the rest, so they are untouched.",
+			"1,200 of 3,412 marked as read. The rest were not sent, apart from the ones already on their way when you stopped — those may still have gone through.",
 		);
 	});
 
-	test("never reads as a rejection — nothing was sent", () => {
+	// Stopping aborts the request on the wire; it does not un-send one the server
+	// already took (#113). Promising the remainder is untouched would be a claim
+	// the client cannot make about the batch that was in flight.
+	test("stops short of promising the batch in flight never landed", () => {
+		assert.match(
+			bulkActionStoppedDetail("move", 1, 2),
+			/may still have gone through/,
+		);
+	});
+
+	test("never reads as a rejection — nothing was refused", () => {
 		assert.doesNotMatch(
 			bulkActionStoppedDetail("move", 1, 2),
 			/rejected|couldn't/i,

package/src/lib/bulk-action-copy.ts

@@ -86,9 +86,11 @@ export const bulkActionCompletionText = (
 
 /**
  * Shown when a run ended before it covered what it was started against. The
- * remainder was never sent, so the mail is where it was and only the user can
+ * remainder was never sent, so that mail is where it was and only the user can
  * decide to run it again — which is why this is stated rather than left to a
- * list that quietly stops changing.
+ * list that quietly stops changing. Stopping aborts the request already on the
+ * wire rather than un-sending it (#113), so what the copy can promise about the
+ * remainder stops short of the batch that was in flight.
  */
 export const bulkActionStoppedTitle = (done: number): string =>
 	`Stopped after ${formatNumber(done)}`;
@@ -99,7 +101,7 @@ export const bulkActionStoppedDetail = (
 	total: number,
 	outcome: DeleteOutcome = "trash",
 ): string =>
-	`${formatNumber(done)} of ${formatNumber(total)} ${pastTenseFor(kind, outcome)}. Nothing was sent for the rest, so they are untouched.`;
+	`${formatNumber(done)} of ${formatNumber(total)} ${pastTenseFor(kind, outcome)}. The rest were not sent, apart from the ones already on their way when you stopped — those may still have gone through.`;
 
 /** Error-banner title for a run stopped by an infrastructure failure. */
 export const bulkActionFailureTitle = (