@remit/web-client 0.0.106 → 0.0.107

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.106",
+  "version": "0.0.107",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/mail/SelectionWizardHost.job-status.test.ts

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+
+/**
+ * A back-apply whose status could not be read is still running on the server
+ * (#526), so the run screen's affordance looks at that job again rather than
+ * queuing a second pass over the same mail.
+ *
+ * The host wires routing, history and several data hooks together, so — as with
+ * this package's other component-level rules (see `SelectionWizardHost.run-exit.test.ts`)
+ * — the wiring is read off the source. What it decides is proven where it can be
+ * run: `./organize-run-state.test.ts` for the ending the screen shows, and
+ * `../../hooks/useOrganizeJob.render.test.ts` for the poll it re-issues.
+ */
+
+const here = dirname(fileURLToPath(import.meta.url));
+const source = readFileSync(resolve(here, "SelectionWizardHost.tsx"), "utf8");
+
+const retryBody = (): string => {
+	const body = source.match(
+		/const retry = \(\): void => \{([\s\S]*?)\n\t\};/,
+	)?.[1];
+	assert.ok(body, "the run screen has no retry");
+	return body;
+};
+
+describe("retrying from an unknown status", () => {
+	it("looks at the job it already has", () => {
+		const body = retryBody();
+		const unknown = body.indexOf('run.state === "statusUnknown"');
+		assert.ok(unknown >= 0, "retry does not recognise an unknown status");
+		assert.match(body.slice(unknown), /organizeJob\.refreshStatus\(\)/);
+	});
+
+	it("decides that before it can reach anything that queues a second job", () => {
+		const body = retryBody();
+		assert.ok(
+			body.indexOf('run.state === "statusUnknown"') < body.indexOf("startJob("),
+			"a second back-apply can be queued over a job that is still running",
+		);
+	});
+
+	it("reads what the job is doing rather than that something failed", () => {
+		assert.doesNotMatch(source, /organizeJob\.isError/);
+		assert.match(source, /organizeRunState\(\{/);
+	});
+});

package/src/components/mail/SelectionWizardHost.tsx

@@ -65,6 +65,7 @@ import {
 import { searchRuleAccountId } from "@/lib/organize/search-to-rule";
 import type { OrganizeMatchPredicate } from "@/lib/organize/sender-fallback";
 import { useWizardEntryValue, useWizardStep } from "@/lib/wizard-history";
+import { organizeRunState } from "./organize-run-state";
 
 const EMPTY_DRAFT: WizardDraft = { clauses: [], matchOperator: "any" };
 
@@ -696,29 +697,34 @@ function SelectionWizardSession({
 		sendCommit();
 	}, [blockedReason, current, goToStep, sendCommit]);
 
-	const jobSnapshot = useCallback((): RunSnapshot => {
-		const progress = organizeJob.progress;
-		const shared = {
-			matched: progress.matchedCount,
-			applied: progress.appliedCount,
-			failures: [],
-		};
-		if (organizeJob.isError) {
-			return { ...NOT_STARTED, state: "commitFailed" };
-		}
-		if (organizeJob.isDone) {
+	const jobSnapshot = useCallback(
+		(ruleSaved: boolean): RunSnapshot => {
+			const progress = organizeJob.progress;
+			const state = organizeRunState({
+				failure: organizeJob.failure,
+				isStarting: organizeJob.isStarting,
+				isRunning: organizeJob.isRunning,
+				isDone: organizeJob.isDone,
+				failedCount: progress.failedCount,
+				ruleSaved,
+			});
+			if (
+				state === "saving" ||
+				state === "commitFailed" ||
+				state === "backApplyStartFailed"
+			) {
+				return { ...NOT_STARTED, state };
+			}
 			return {
-				...shared,
-				state:
-					progress.failedCount > 0 ? "backApplyFailed" : "backApplyComplete",
-				failed: progress.failedCount,
+				state,
+				matched: progress.matchedCount,
+				applied: progress.appliedCount,
+				failed: state === "backApplyFailed" ? progress.failedCount : 0,
+				failures: [],
 			};
-		}
-		if (organizeJob.isStarting || organizeJob.isRunning) {
-			return { ...shared, state: "backApplyRunning", failed: 0 };
-		}
-		return NOT_STARTED;
-	}, [organizeJob]);
+		},
+		[organizeJob],
+	);
 
 	// Every row the wizard has seen a description of, so a run that names what it
 	// did not reach can name it rather than listing an id.
@@ -794,21 +800,27 @@ function SelectionWizardSession({
 				return { ...NOT_STARTED, state: "commitFailed" };
 			if (!createFilter.isSuccess) return NOT_STARTED;
 			if (!backApplyDraft) return { ...NOT_STARTED, state: "filterSaved" };
-			if (organizeJob.isError) {
-				return { ...NOT_STARTED, state: "backApplyStartFailed" };
-			}
-			return jobSnapshot();
+			return jobSnapshot(true);
 		}
 		if (committedScope === "all-like-these" && widenedRunsAsJob(verb)) {
-			return jobSnapshot();
+			return jobSnapshot(false);
 		}
 		return bulkSnapshot();
 	};
 
+	const run = runSnapshot();
+
 	// Retry stays on the run screen: it re-sends the same commit rather than
 	// walking back to Review, which would push an entry the wizard does not own
 	// and leave Cancel rewinding to a step instead of out.
 	const retry = (): void => {
+		// A status that could not be read is a job still running on the server, so
+		// the screen looks at that job again rather than queuing a second pass over
+		// the same mail (#526).
+		if (run.state === "statusUnknown") {
+			organizeJob.refreshStatus();
+			return;
+		}
 		// The predicate is re-resolved, not resumed: every verb it carries is
 		// idempotent, so the messages the first pass already reached are a no-op.
 		if (escalated) {
@@ -881,7 +893,6 @@ function SelectionWizardSession({
 		disabled: current !== "run",
 	});
 
-	const run = runSnapshot();
 	const sampleMessages = escalated
 		? escalatedSample.messages
 		: previewed

package/src/components/mail/organize-run-state.test.ts

@@ -0,0 +1,97 @@
+/**
+ * A back-apply job reports two things that used to arrive as one error flag: it
+ * never started, or its status could not be read (#526). The run screen is only
+ * allowed to say nothing happened for the first.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	type OrganizeJobReading,
+	organizeRunState,
+} from "./organize-run-state";
+
+const reading = (
+	over: Partial<OrganizeJobReading> = {},
+): OrganizeJobReading => ({
+	failure: undefined,
+	isStarting: false,
+	isRunning: false,
+	isDone: false,
+	failedCount: 0,
+	ruleSaved: false,
+	...over,
+});
+
+describe("organizeRunState", () => {
+	it("keeps a running job running when a status poll could not be read", () => {
+		const state = organizeRunState(
+			reading({
+				isRunning: true,
+				failure: { kind: "statusUnreadable", error: new Error("offline") },
+			}),
+		);
+		assert.equal(state, "statusUnknown");
+		assert.notEqual(state, "commitFailed");
+	});
+
+	it("keeps a finished job finished when a later poll fails", () => {
+		// Polling stops on a terminal state, so the failing read is a window-focus
+		// refetch over a job that already reported its counts.
+		assert.equal(
+			organizeRunState(
+				reading({
+					isDone: true,
+					failure: { kind: "statusUnreadable", error: new Error("offline") },
+				}),
+			),
+			"backApplyComplete",
+		);
+		assert.equal(
+			organizeRunState(
+				reading({
+					isDone: true,
+					failedCount: 3,
+					failure: { kind: "statusUnreadable", error: new Error("offline") },
+				}),
+			),
+			"backApplyFailed",
+		);
+	});
+
+	it("says nothing happened only when the create itself failed", () => {
+		assert.equal(
+			organizeRunState(
+				reading({ failure: { kind: "startFailed", error: new Error("nope") } }),
+			),
+			"commitFailed",
+		);
+	});
+
+	it("leaves a saved rule standing when its pass never started", () => {
+		assert.equal(
+			organizeRunState(
+				reading({
+					ruleSaved: true,
+					failure: { kind: "startFailed", error: new Error("nope") },
+				}),
+			),
+			"backApplyStartFailed",
+		);
+	});
+
+	it("reports a job that is starting or polling cleanly as running", () => {
+		assert.equal(
+			organizeRunState(reading({ isStarting: true })),
+			"backApplyRunning",
+		);
+		assert.equal(
+			organizeRunState(reading({ isRunning: true })),
+			"backApplyRunning",
+		);
+	});
+
+	it("has nothing to report before a commit", () => {
+		assert.equal(organizeRunState(reading()), "saving");
+	});
+});

package/src/components/mail/organize-run-state.ts

@@ -0,0 +1,39 @@
+import type { RunState } from "@remit/ui";
+import type { OrganizeJobFailure } from "@/hooks/useOrganizeJob";
+
+/** What the run screen knows about a back-apply job it is reporting on. */
+export interface OrganizeJobReading {
+	failure: OrganizeJobFailure | undefined;
+	isStarting: boolean;
+	isRunning: boolean;
+	isDone: boolean;
+	failedCount: number;
+	/**
+	 * The pass belongs to a rule that already saved, so a pass that never started
+	 * leaves the rule standing rather than leaving nothing behind.
+	 */
+	ruleSaved: boolean;
+}
+
+/**
+ * What the run screen says the job is doing. A status that could not be read is
+ * not a job that never started (#526), so what the job is doing is read before
+ * what failed: a dropped poll leaves a running pass running and a finished one
+ * finished, and only a create that never returned an id says nothing happened.
+ */
+export const organizeRunState = ({
+	failure,
+	isStarting,
+	isRunning,
+	isDone,
+	failedCount,
+	ruleSaved,
+}: OrganizeJobReading): RunState => {
+	if (failure?.kind === "startFailed") {
+		return ruleSaved ? "backApplyStartFailed" : "commitFailed";
+	}
+	if (isDone) return failedCount > 0 ? "backApplyFailed" : "backApplyComplete";
+	if (failure?.kind === "statusUnreadable") return "statusUnknown";
+	if (isStarting || isRunning) return "backApplyRunning";
+	return "saving";
+};

package/src/hooks/useOrganizeJob.render.test.ts

@@ -0,0 +1,142 @@
+/**
+ * useOrganizeJob — the back-apply job seam. It reports two failures that are not
+ * the same fact (#526): a create that never returned a job id, and a status poll
+ * that could not be read over a job the server is already running. Looking at
+ * that job again is a separate move from starting one.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { act, createElement } from "react";
+import type { OrganizeDraft } from "../lib/organize/organize-model";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, mockFetch } from "../test-support/http";
+import { useOrganizeJob } from "./useOrganizeJob";
+
+/**
+ * A poll that could not be read reaches this screen only as a transport failure:
+ * `shouldEscalate` puts every answered non-2xx on the full-screen fatal page, so
+ * a status that is merely unreadable is a `fetch` that never landed.
+ */
+const dropped = (): never => {
+	throw new TypeError("fetch failed");
+};
+
+const ACCOUNT = "acc-1";
+const JOB = "job-1";
+
+const DRAFT: OrganizeDraft = {
+	matchOperator: "Or",
+	literalClauses: [{ field: "From", value: "noreply@example.com" }],
+	moveMailboxId: "mbx-1",
+};
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+let job: ReturnType<typeof useOrganizeJob> | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+	job = undefined;
+});
+
+function Probe() {
+	job = useOrganizeJob(ACCOUNT);
+	return null;
+}
+
+const current = (): ReturnType<typeof useOrganizeJob> => {
+	if (!job) throw new Error("useOrganizeJob is not mounted");
+	return job;
+};
+
+// A request round-trip needs a macrotask, not just a drained microtask queue.
+const settle = async (): Promise<void> => {
+	await harness?.wait(1);
+	await harness?.flush();
+};
+
+/** Start a job the server accepts, then answer every status poll with `status`. */
+const startJob = async (status: () => unknown): Promise<void> => {
+	http = mockFetch((call) => {
+		if (call.method === "POST") {
+			return { organizeJobId: JOB, state: "Pending" };
+		}
+		return status();
+	});
+	harness = createDomHarness();
+	harness.renderApp(createElement(Probe));
+	await act(async () => {
+		current().start(DRAFT);
+	});
+	await settle();
+};
+
+const posts = (): number =>
+	(http?.calls ?? []).filter((call) => call.method === "POST").length;
+
+const statusPolls = (): number => (http?.to(`/organize/${JOB}`) ?? []).length;
+
+describe("useOrganizeJob status reporting", () => {
+	it("reports a status poll it could not read as unreadable, over a job still running", async () => {
+		await startJob(dropped);
+		assert.equal(current().failure?.kind, "statusUnreadable");
+		assert.equal(current().isRunning, true);
+		assert.equal(current().isDone, false);
+	});
+
+	it("reports a create that never returned a job id as a start failure", async () => {
+		http = mockFetch(dropped);
+		harness = createDomHarness();
+		harness.renderApp(createElement(Probe));
+		await act(async () => {
+			current().start(DRAFT);
+		});
+		await settle();
+		assert.equal(current().failure?.kind, "startFailed");
+		assert.equal(current().isRunning, false);
+	});
+
+	it("re-polls the job it already has instead of starting a second one", async () => {
+		let readable = false;
+		await startJob(() =>
+			readable
+				? {
+						organizeJobId: JOB,
+						state: "Running",
+						matchedCount: 1284,
+						appliedCount: 40,
+						failedCount: 0,
+					}
+				: dropped(),
+		);
+		assert.equal(current().failure?.kind, "statusUnreadable");
+		const pollsBefore = statusPolls();
+
+		readable = true;
+		await act(async () => {
+			current().refreshStatus();
+		});
+		await settle();
+
+		assert.equal(posts(), 1);
+		assert.ok(statusPolls() > pollsBefore, "the existing job was polled again");
+		assert.equal(current().failure, undefined);
+		assert.equal(current().progress.matchedCount, 1284);
+	});
+
+	it("stops reporting a job as running once it reaches a terminal state", async () => {
+		await startJob(() => ({
+			organizeJobId: JOB,
+			state: "Complete",
+			matchedCount: 1284,
+			appliedCount: 1284,
+			failedCount: 0,
+		}));
+		assert.equal(current().isDone, true);
+		assert.equal(current().failure, undefined);
+	});
+});

package/src/hooks/useOrganizeJob.ts

@@ -22,6 +22,25 @@ export interface OrganizeJobProgress {
 	errorMessage: string;
 }
 
+/**
+ * Why the job is not reporting, which is two separate facts (#526). A create
+ * that never returned an id means nothing was started; a status read that
+ * failed means a job is out there and this client cannot see how far it got.
+ */
+export interface OrganizeJobFailure {
+	kind: "startFailed" | "statusUnreadable";
+	error: unknown;
+}
+
+const organizeJobFailure = (
+	createError: unknown,
+	statusError: unknown,
+): OrganizeJobFailure | undefined => {
+	if (createError) return { kind: "startFailed", error: createError };
+	if (statusError) return { kind: "statusUnreadable", error: statusError };
+	return undefined;
+};
+
 /**
  * "All like these" — start a one-time retroactive back-apply (POST /organize)
  * and poll its status to completion (GET /organize/{organizeJobId}). Polling
@@ -66,6 +85,13 @@ export const useOrganizeJob = (accountId: string | undefined) => {
 		[accountId, createJob],
 	);
 
+	const { refetch } = jobQuery;
+	// Looks at the job already in flight again. Distinct from `start`, which
+	// queues a second pass over the same mail.
+	const refreshStatus = useCallback(() => {
+		void refetch();
+	}, [refetch]);
+
 	const job = jobQuery.data;
 	const state = job?.state ?? createMutation.data?.state;
 	const isDone = isTerminalJobState(job?.state);
@@ -80,11 +106,11 @@ export const useOrganizeJob = (accountId: string | undefined) => {
 
 	return {
 		start,
+		refreshStatus,
 		progress,
 		isStarting: createMutation.isPending,
 		isRunning: !!organizeJobId && !isDone,
 		isDone,
-		isError: createMutation.isError || jobQuery.isError,
-		error: createMutation.error ?? jobQuery.error,
+		failure: organizeJobFailure(createMutation.error, jobQuery.error),
 	};
 };