@remit/web-client 0.0.270 → 0.0.272

package/src/hooks/useEscalatedActions.ts

@@ -1,4 +1,3 @@
-import { mailboxOperationsListMailboxesQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
 import {
 	messageBulkOperationsDeleteMessages,
 	messageBulkOperationsMoveMessages,
@@ -6,30 +5,22 @@ import {
 	threadOperationsSearchThreads,
 } from "@remit/api-http-client/sdk.gen.ts";
 import type { ThreadOperationsSearchThreadsData } from "@remit/api-http-client/types.gen.ts";
-import { useQueryClient } from "@tanstack/react-query";
 import { useCallback, useEffect, useRef, useState } from "react";
-import { useRoleAppointmentPrompt } from "@/components/mail/RoleAppointmentPromptProvider";
+import {
+	type BulkRunRequest,
+	type BulkRunSource,
+	useBulkRun,
+} from "@/components/mail/BulkRunProvider";
 import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
 import { buildMutationErrorBanner } from "@/components/ui/error-banners";
-import { isFolderRoleRefusal } from "@/components/ui/folder-role-refusal";
-import {
-	bulkActionFailureDetail,
-	bulkActionFailureTitle,
-} from "@/lib/bulk-action-copy";
-import {
-	type ApplyBatch,
-	type BulkActionProgress,
-	type BulkActionTarget,
-	type BulkRunOutcome,
-	type FetchIdsPage,
-	honestProgress,
-	runChunkedAction,
-	runPredicateAction,
+import type {
+	ApplyBatch,
+	BulkActionProgress,
+	BulkActionTarget,
+	BulkRunStart,
+	EscalatedAction,
+	FetchIdsPage,
 } from "@/lib/bulk-actions";
-import {
-	invalidateThreadListQueries,
-	threadListCacheKeys,
-} from "@/lib/thread-list-cache";
 
 /** The predicate a search-scoped run re-issues on every page — the same
  *  filters the visible list is searching with, minus pagination/count knobs. */
@@ -45,16 +36,6 @@ export type EscalationSearchQuery = Pick<
 	| "category"
 >;
 
-/**
- * What a bulk run applies to every batch it reaches (#114). Delete, move and
- * mark-read differ only in the bulk call they issue and the caches that call
- * invalidates; the paging, chunking, progress and cancellation are the same.
- */
-export type EscalatedAction =
-	| { kind: "delete" }
-	| { kind: "move"; destinationMailboxId: string }
-	| { kind: "markRead" };
-
 /** Page size for the execution loop. Set to the write side's own 100-id cap so
  *  an execution page IS a write chunk — no in-memory accumulation step between
  *  reading ids and sending them. */
@@ -67,6 +48,8 @@ export type EscalationPhase =
 
 interface UseEscalatedActionsOptions {
 	mailboxId: string;
+	/** The mailbox in the user's words, for a commit refused while this runs. */
+	mailboxLabel?: string;
 	/** Owning account, forwarded to the unseen-count invalidation on completion. */
 	accountId?: string;
 	/** Disables escalation entirely (e.g. not searching). Resets any in-flight
@@ -76,6 +59,12 @@ interface UseEscalatedActionsOptions {
 	 *  changes (a different search is a different question). */
 	predicateKey: string;
 	searchQuery: EscalationSearchQuery;
+	/**
+	 * States how a run ended, for a user who is no longer looking at any screen
+	 * that could show it. Handed to the run's owner rather than called here, so
+	 * an ending that lands after this hook unmounted is still said (#112).
+	 */
+	reportEnding?: BulkRunRequest["reportEnding"];
 }
 
 export interface UseEscalatedActionsResult {
@@ -84,11 +73,14 @@ export interface UseEscalatedActionsResult {
 	 *  selection to that predicate once it answers. */
 	escalate: () => void;
 	/**
-	 * 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.
+	 * Stop whatever this mailbox has running — its count, and the run when the
+	 * run is its own. 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.
+	 * Cancelling a count here never reaches a run in another mailbox: that run is
+	 * not what this screen is offering to stop, and ending it would be silent.
+	 * The only thing that ends a run in flight: leaving the selection, the
+	 * wizard, the search or the mailbox does not.
 	 */
 	stop: () => void;
 	/**
@@ -99,7 +91,7 @@ export interface UseEscalatedActionsResult {
 	 */
 	clear: () => void;
 	/** True while a chunked run (bounded->100 ids, or the escalated predicate)
-	 *  is in flight. */
+	 *  over this mailbox is in flight, whichever screen started it. */
 	isRunning: boolean;
 	/** The action currently in flight, for status and progress wording. */
 	runningAction: EscalatedAction | undefined;
@@ -112,61 +104,44 @@ export interface UseEscalatedActionsResult {
 	 * as one batch the endpoint refuses whole (#872). Resolves once the run ends
 	 * for any reason — cancelled, errored, or complete — with a
 	 * `done`/`failedIds` outcome the caller reads to decide what is still
-	 * outstanding.
-	 * Infrastructure failures are reported through the app's existing
-	 * escalation seam (`pushError`, which itself escalates a 5xx/exception to
-	 * the fatal overlay) — not swallowed here.
+	 * outstanding, or with the refusal of a run that never started because
+	 * another one is still going.
+	 *
+	 * The run itself belongs to `BulkRunProvider`, which outlives every screen
+	 * that can show it: the caches, the refusal replay, the failure banner and
+	 * the ending are its, so none of them are lost when the surface that started
+	 * the run goes (#112).
 	 */
 	runAction: (
 		action: EscalatedAction,
 		targets?: readonly BulkActionTarget[],
-	) => Promise<BulkRunOutcome>;
+		claimEnding?: BulkRunRequest["claimEnding"],
+	) => Promise<BulkRunStart>;
 }
 
-/**
- * The mailboxes whose cached listings a bulk run affects: the mailbox it ran
- * over, plus a move's destination, which gains the messages the source loses.
- */
-export const mailboxesTouchedBy = (
-	action: EscalatedAction,
-	mailboxId: string,
-): string[] =>
-	action.kind === "move"
-		? [mailboxId, action.destinationMailboxId]
-		: [mailboxId];
-
 export const useEscalatedActions = ({
 	mailboxId,
+	mailboxLabel,
 	accountId,
 	enabled,
 	predicateKey,
 	searchQuery,
+	reportEnding,
 }: UseEscalatedActionsOptions): UseEscalatedActionsResult => {
 	const [phase, setPhase] = useState<EscalationPhase>({ kind: "idle" });
-	const [runningAction, setRunningAction] = useState<
-		EscalatedAction | undefined
-	>(undefined);
-	const [progress, setProgress] = useState<BulkActionProgress | undefined>(
-		undefined,
-	);
-	// 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`.
-	const runningRef = useRef(false);
-	const queryClient = useQueryClient();
+	// The count's own signal, which is not the run's: leaving the search ends a
+	// count, and never a run (#112).
+	const countAbortRef = useRef<AbortController | undefined>(undefined);
+	const { run, start, stop: stopRun } = useBulkRun();
 	const { pushError } = useErrorBanners();
-	const { requestAppointment } = useRoleAppointmentPrompt();
-	// The run replays itself once a folder is appointed, so it needs a handle on
-	// itself that does not make `runAction` its own dependency.
-	const runRef = useRef<UseEscalatedActionsResult["runAction"]>(async () => ({
-		done: 0,
-		failedIds: [],
-		cancelled: false,
-	}));
+
+	// The live run, when it is this mailbox's. A run is mail leaving one mailbox,
+	// so it reports on that mailbox's list — not on whichever list is on screen.
+	const activeRun = run?.mailboxId === mailboxId ? run : undefined;
+	const isRunning = activeRun !== undefined;
+	// Read by callbacks that must not close over a stale render's answer.
+	const isRunningRef = useRef(false);
+	isRunningRef.current = isRunning;
 
 	// A different search (or leaving search/desktop) makes any in-flight
 	// escalation meaningless — it would otherwise keep counting or offering to
@@ -175,7 +150,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) abortRef.current?.abort();
+		countAbortRef.current?.abort();
 		setPhase({ kind: "idle" });
 	}, [enabled, predicateKey]);
 
@@ -252,36 +227,9 @@ export const useEscalatedActions = ({
 		[],
 	);
 
-	/**
-	 * The unseen counts a run moved, per account. A cross-account selection has
-	 * no single owning account — the surface leaves the option undefined exactly
-	 * then — so the run's own targets are what name the accounts to refresh.
-	 */
-	const invalidateAfterRun = useCallback(
-		(action: EscalatedAction, targets: readonly BulkActionTarget[]) => {
-			invalidateThreadListQueries(
-				queryClient,
-				threadListCacheKeys(mailboxesTouchedBy(action, mailboxId)),
-			);
-			const touched = new Set<string>();
-			if (accountId) touched.add(accountId);
-			for (const target of targets) {
-				if (target.accountId) touched.add(target.accountId);
-			}
-			for (const touchedAccountId of touched) {
-				queryClient.invalidateQueries({
-					queryKey: mailboxOperationsListMailboxesQueryKey({
-						path: { accountId: touchedAccountId },
-					}),
-				});
-			}
-		},
-		[queryClient, mailboxId, accountId],
-	);
-
 	const escalate = useCallback(() => {
 		const controller = new AbortController();
-		abortRef.current = controller;
+		countAbortRef.current = controller;
 		setPhase({ kind: "counting" });
 		fetchMatchCount(controller.signal).then(
 			(total) => {
@@ -311,12 +259,13 @@ export const useEscalatedActions = ({
 	}, [fetchMatchCount, pushError]);
 
 	const stop = useCallback(() => {
-		abortRef.current?.abort();
-	}, []);
+		countAbortRef.current?.abort();
+		if (isRunningRef.current) stopRun(mailboxId);
+	}, [stopRun, mailboxId]);
 
 	const clear = useCallback(() => {
-		if (runningRef.current) return;
-		abortRef.current?.abort();
+		if (isRunningRef.current) return;
+		countAbortRef.current?.abort();
 		setPhase({ kind: "idle" });
 	}, []);
 
@@ -324,105 +273,62 @@ export const useEscalatedActions = ({
 		async (
 			action: EscalatedAction,
 			targets?: readonly BulkActionTarget[],
-		): Promise<BulkRunOutcome> => {
-			const controller = new AbortController();
-			abortRef.current = controller;
-			runningRef.current = true;
-			setRunningAction(action);
+			claimEnding?: BulkRunRequest["claimEnding"],
+		): Promise<BulkRunStart> => {
 			// Read before the run clears the phase below, so a refusal can say how
 			// many messages the appointment's replay is about.
 			const matched =
 				targets?.length ?? (phase.kind === "escalated" ? phase.total : 0);
-			// `honestProgress` widens `total` if `done` overtakes it (#109) — the
-			// predicate can match more by the time the run pages it than the count
-			// saw, and the bar must never show more done than out of.
-			const onProgress = (next: BulkActionProgress) =>
-				setProgress(honestProgress(next));
-			const applyBatch = applyBatchFor(action);
 			// The predicate as it read when the run was confirmed. The run outlives
 			// the screen that started it, so reading the live query on every page
 			// would let a search typed afterwards redirect what is being deleted.
-			const runPages = fetchPagesOf(searchQueryRef.current);
+			const source: BulkRunSource =
+				targets !== undefined
+					? { kind: "targets", targets }
+					: {
+							kind: "predicate",
+							fetchPage: fetchPagesOf(searchQueryRef.current),
+						};
 
-			// The one invariant nothing may lose: while `runningRef` is up, both
-			// `clear` and the reset effect stand down, so a run that never marked
-			// itself finished would leave an escalated selection nobody can leave.
-			let outcome: BulkRunOutcome;
-			try {
-				outcome =
-					targets !== undefined
-						? await runChunkedAction(
-								targets,
-								applyBatch,
-								onProgress,
-								controller.signal,
-							)
-						: await runPredicateAction(
-								runPages,
-								phase.kind === "escalated" ? phase.total : 0,
-								applyBatch,
-								onProgress,
-								controller.signal,
-							);
-			} finally {
-				runningRef.current = false;
-			}
-
-			setRunningAction(undefined);
-			setProgress(undefined);
-			setPhase({ kind: "idle" });
+			const started = await start({
+				action,
+				mailboxId,
+				mailboxLabel,
+				accountId,
+				matched,
+				source,
+				applyBatch: applyBatchFor(action),
+				reportEnding,
+				claimEnding,
+			});
 
-			// A provenance refusal is answered by the appointment prompt here exactly
-			// as it is on the single-row path (#887, #876). Left to the banner it
-			// arrives as the API's own sentence — "Appoint one under Settings ›
-			// Folder roles" — which asks the user to reassemble a select-all they
-			// have already made.
-			const refusal = outcome.error
-				? isFolderRoleRefusal(outcome.error)
-				: undefined;
-			if (refusal) {
-				requestAppointment({
-					accountId: refusal.accountId,
-					role: refusal.role,
-					reason: refusal.reason,
-					action: { kind: "delete", count: matched },
-					onAppointed: async () => {
-						await runRef.current(action, targets);
-					},
-				});
-			} else if (outcome.error) {
-				pushError(
-					buildMutationErrorBanner(
-						bulkActionFailureTitle(action.kind, outcome.done),
-						bulkActionFailureDetail(action.kind),
-						outcome.error,
-					),
-				);
-			}
-			if (outcome.done > 0) {
-				invalidateAfterRun(action, targets ?? []);
-			}
-			return outcome;
+			// The escalated selection was what the run was confirmed from, and the
+			// run has now happened to it. A refused commit leaves it standing: the
+			// selection is still the question, and stopping the other run is what
+			// makes it answerable.
+			if (started.kind === "ran") setPhase({ kind: "idle" });
+			return started;
 		},
 		[
 			applyBatchFor,
 			fetchPagesOf,
 			phase,
-			pushError,
-			invalidateAfterRun,
-			requestAppointment,
+			mailboxId,
+			mailboxLabel,
+			accountId,
+			reportEnding,
+			start,
 		],
 	);
-	runRef.current = runAction;
 
 	return {
 		phase,
 		escalate,
 		stop,
 		clear,
-		isRunning: runningAction !== undefined,
-		runningAction,
-		progress,
+		isRunning,
+		runningAction: activeRun?.action,
+		progress: activeRun?.progress,
 		runAction,
 	};
 };

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

@@ -115,6 +115,27 @@ export const bulkActionFailureTitle = (
 export const bulkActionFailureDetail = (kind: BulkActionKind): string =>
 	failureDetail[kind];
 
+const busyPhrase: Record<BulkActionKind, (count: string) => string> = {
+	delete: (count) => `A delete of ${count} messages`,
+	move: (count) => `A move of ${count} messages`,
+	markRead: (count) => `Marking ${count} messages as read`,
+};
+
+/**
+ * The commit that could not start, because the one still going owns the bar and
+ * the Stop it would need. It names the run in flight and where it is, so the
+ * user knows which screen to end it from rather than pressing a commit that
+ * silently does nothing.
+ */
+export const bulkRunBusyRefusal = (
+	kind: BulkActionKind,
+	matched: number,
+	mailboxLabel: string | undefined,
+): string =>
+	`${busyPhrase[kind](formatNumber(matched))}${
+		mailboxLabel ? ` in ${mailboxLabel}` : ""
+	} is still running — stop it first.`;
+
 /** Progress-bar tone: only delete is destructive. */
 export const bulkActionProgressTone = (
 	kind: BulkActionKind,

package/src/lib/bulk-actions.ts

@@ -34,6 +34,28 @@
 
 export const BULK_ACTION_CHUNK_SIZE = 100;
 
+/**
+ * What a bulk run applies to every batch it reaches (#114). Delete, move and
+ * mark-read differ only in the bulk call they issue and the caches that call
+ * invalidates; the paging, chunking, progress and cancellation are the same.
+ */
+export type EscalatedAction =
+	| { kind: "delete" }
+	| { kind: "move"; destinationMailboxId: string }
+	| { kind: "markRead" };
+
+/**
+ * The mailboxes whose cached listings a bulk run affects: the mailbox it ran
+ * over, plus a move's destination, which gains the messages the source loses.
+ */
+export const mailboxesTouchedBy = (
+	action: EscalatedAction,
+	mailboxId: string,
+): string[] =>
+	action.kind === "move"
+		? [mailboxId, action.destinationMailboxId]
+		: [mailboxId];
+
 /** For a run with no Stop control to wire a signal to. */
 const NEVER_ABORTED = new AbortController().signal;
 
@@ -323,3 +345,13 @@ export interface BulkRunOutcome {
 	cancelled: boolean;
 	error?: unknown;
 }
+
+/**
+ * What asking for a run got: the run itself, or the reason there is none. One
+ * run at a time is the design — a second one would page a second predicate
+ * behind the same bar and the same Stop — so a commit pressed while one is
+ * going is answered with what is going rather than with a run that replaces it.
+ */
+export type BulkRunStart =
+	| { kind: "ran"; outcome: BulkRunOutcome }
+	| { kind: "refused"; reason: string };

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,
 	};