@remit/ui 0.0.14 → 0.0.16

package/src/components/quarantine-report.ts

@@ -0,0 +1,221 @@
+import type { FolderRole } from "./folder-role.js";
+
+/**
+ * The pipeline step that refused the message.
+ *
+ * One member, because **no catch site on the sync path can currently tell a
+ * parse failure from an infrastructure failure**. The per-message frame in
+ * `body-sync.ts` wraps the S3 body write, the parsed-body cache write, the
+ * body-part `pMap` and DynamoDB upsert, the placement move (SQS + DynamoDB)
+ * and the label and counter writes, alongside the `simpleParser` call; only
+ * connection drops are filtered out of it.
+ *
+ * **Precondition on Phase 3**: narrow the try block to the parse call before
+ * quarantining anything. Quarantining at the frame as it stands would set a
+ * message aside for a DynamoDB throttle, tell the user it was unreadable, and
+ * invite a public GitHub issue for an outage — the same defect as naming an
+ * S3 write `AttachmentExtract`, one layer up.
+ *
+ * There are three distinct parse sites, and a quarantine would have to
+ * attribute them differently: the fresh-fetch path, `backfillClassification`
+ * (its own parse over a different result list), and the header parse in
+ * `imapflow-connection.ts`, which is swallowed and treated as "no thread
+ * parent". Stages are added as those sites are separated — never ahead of it.
+ *
+ * The stages this replaced could not fire at all: an unparseable Date falls
+ * back to INTERNALDATE, and an unrecognized MIME type maps to a safe default
+ * rather than throwing. Unparseable addresses are dropped with a `continue`
+ * and the message is written anyway — so that defect is reached but discarded,
+ * never raised, which is a reason to have no `AddressParse` stage but not the
+ * reason that it cannot happen.
+ */
+export type QuarantineFailureStage = "BodyParse";
+
+/**
+ * The specific defect within a stage.
+ *
+ * Closed, because `quarantineIssueTitle` interpolates it into a public issue
+ * title: a `string` here would make the one field whose publishability is
+ * asserted rather than derived into free text. Grows with the narrowing
+ * described on `QuarantineFailureStage`, and no faster.
+ */
+export type QuarantineFailureCode =
+	| "UnterminatedMultipartBoundary"
+	| "UnknownCharset"
+	| "TruncatedBody";
+
+/**
+ * A node in the message's MIME tree.
+ *
+ * `contentType` is `type/subtype` only. BODYSTRUCTURE hands the type and its
+ * parameters over separately, so a node is built from `type`/`subtype` and
+ * never from a raw content-type line — parameters carry `name=` and
+ * `filename=`, which name the user's attachments.
+ */
+export interface QuarantineMimeNode {
+	contentType: string;
+	parts?: readonly QuarantineMimeNode[];
+}
+
+/**
+ * A quarantined message as the settings surface sees it.
+ *
+ * Two fields are stored and shown on screen but never travel in the report:
+ * `mailboxPath` (the user's own folder names can be personal) and
+ * `failureMessage` (parser errors quote the input that broke them, and
+ * redacting arbitrary parser text is not solvable). Everything else is safe to
+ * paste into a public issue without reading it first.
+ */
+export interface QuarantineEntry {
+	quarantineId: string;
+	accountId: string;
+	mailboxId: string;
+	/** IMAP uid of the message that was not written. */
+	uid: number;
+	/** Canonical role of the folder it arrived in — travels in the report. */
+	mailboxRole: FolderRole;
+	/** The user's own folder name. Shown on screen, withheld from the report. */
+	mailboxPath: string;
+	failureStage: QuarantineFailureStage;
+	failureCode: QuarantineFailureCode;
+	/** Parser error text. Shown on screen, never in the report. */
+	failureMessage: string;
+	/**
+	 * Dot-numbered part path the failure is attributable to, or null when it is
+	 * not attributable to one node — the case for a whole-body parse failure.
+	 */
+	failurePartPath: string | null;
+	/** Epoch millis the message was quarantined. */
+	quarantinedAt: number;
+	/** Rounds attempted before the message was set aside. */
+	attempts: number;
+	sizeBytes: number;
+	/** Top-level Content-Type, `type/subtype` only. */
+	contentType: string;
+	transferEncoding: string;
+	/** Declared charset, or null when the message declared none. */
+	charset: string | null;
+	/** The MIME tree, structure only. */
+	structure: QuarantineMimeNode;
+	/** SHA-256 of the Message-ID, `sha256:` prefixed. */
+	messageIdHash: string;
+	/** Build of the worker that failed to parse — a parse bug belongs to it. */
+	appVersion: string;
+}
+
+const stageSummaries: Record<QuarantineFailureStage, string> = {
+	BodyParse: "The message is built in a way Remit could not read.",
+};
+
+/** Plain-language one-liner for a row. The detail lives in the report. */
+export function quarantineSummary(stage: QuarantineFailureStage): string {
+	return stageSummaries[stage];
+}
+
+/**
+ * Guards the node contract where the report is rendered, so a node built from
+ * a raw content-type line cannot put an attachment filename in the report even
+ * if Phase 3 gets the construction wrong.
+ */
+function stripParameters(contentType: string): string {
+	return contentType.split(";")[0].trim();
+}
+
+/** RFC 2045 token characters — what a charset or encoding is allowed to be. */
+const TOKEN = /^[A-Za-z0-9!#$%&'*+._-]+$/;
+const MEDIA_TYPE = /^[A-Za-z0-9!#$%&'*+._-]+\/[A-Za-z0-9!#$%&'*+._-]+$/;
+
+/**
+ * `charset`, `transferEncoding` and `contentType` are BODYSTRUCTURE strings —
+ * arbitrary quoted text chosen by whoever sent the message, echoed into an
+ * issue filed under the user's own account. A conforming value renders as
+ * itself; anything else is JSON-escaped, so newlines and backticks cannot
+ * close the code span and inject markdown. The malformed value is kept rather
+ * than dropped, because a malformed value is usually the bug.
+ */
+function renderToken(value: string, pattern: RegExp): string {
+	if (pattern.test(value)) return `\`${value}\``;
+	const escaped = JSON.stringify(value).replace(/`/g, "\\u0060");
+	return `\`${escaped}\` (malformed)`;
+}
+
+/** Inside a fence the only escape is a lone fence line, so tokens are enough. */
+function renderNodeType(contentType: string): string {
+	const stripped = stripParameters(contentType);
+	if (MEDIA_TYPE.test(stripped)) return stripped;
+	return JSON.stringify(stripped);
+}
+
+function renderStructure(node: QuarantineMimeNode, depth = 0): string[] {
+	const line = `${"  ".repeat(depth)}- ${renderNodeType(node.contentType)}`;
+	const children = node.parts ?? [];
+	return [
+		line,
+		...children.flatMap((part) => renderStructure(part, depth + 1)),
+	];
+}
+
+export const QUARANTINE_REPORT_DISCLAIMER =
+	"_No message content, addresses, subject, attachment names or parser output are included._";
+
+/**
+ * The report split into the parts a bug report assembles.
+ *
+ * `structure` is the only unbounded section, so it is handed over unfenced:
+ * the URL budget truncates it and fences it afterwards, the same shape a
+ * stacktrace already uses. Fencing here instead would let the binary search
+ * cut inside the fence, leaving every following section rendered inside one
+ * code block — and the first line lost would be the disclaimer, so the one
+ * report that is truncated would be the one with no statement of what was
+ * withheld.
+ */
+export interface QuarantineReportSections {
+	head: string;
+	structure: string;
+	disclaimer: string;
+}
+
+export function quarantineReportSections(
+	entry: QuarantineEntry,
+): QuarantineReportSections {
+	const head = [
+		`### Message quarantined at \`${entry.failureStage}\``,
+		"",
+		`- **Failure**: \`${entry.failureCode}\``,
+		`- **Folder role**: ${entry.mailboxRole}`,
+		`- **Failing part**: ${entry.failurePartPath === null ? "_whole message_" : `\`${entry.failurePartPath}\``}`,
+		`- **Attempts before quarantine**: ${entry.attempts}`,
+		`- **Worker build**: ${entry.appVersion}`,
+		`- **Message-ID hash**: \`${entry.messageIdHash}\``,
+		"",
+		"#### Message shape",
+		"",
+		`- **Content-Type**: ${renderToken(stripParameters(entry.contentType), MEDIA_TYPE)}`,
+		`- **Content-Transfer-Encoding**: ${renderToken(entry.transferEncoding, TOKEN)}`,
+		`- **Charset**: ${entry.charset === null ? "_not declared_" : renderToken(entry.charset, TOKEN)}`,
+		`- **Size**: ${entry.sizeBytes} bytes`,
+		"",
+		"MIME structure:",
+	].join("\n");
+
+	return {
+		head,
+		structure: renderStructure(entry.structure).join("\n"),
+		disclaimer: QUARANTINE_REPORT_DISCLAIMER,
+	};
+}
+
+/**
+ * The whole report as one string — what the dialog shows and the copy action
+ * copies. The published issue is assembled from the sections instead, so that
+ * a long MIME tree can be truncated without breaking the fence.
+ */
+export function formatQuarantineReport(entry: QuarantineEntry): string {
+	const { head, structure, disclaimer } = quarantineReportSections(entry);
+	return [head, "", "```", structure, "```", "", disclaimer].join("\n");
+}
+
+/** Issue title. Closed vocabulary only, so it is safe to publish. */
+export function quarantineIssueTitle(entry: QuarantineEntry): string {
+	return `Message quarantined: ${entry.failureCode} at ${entry.failureStage}`;
+}

package/src/components/quarantine-section.render.test.ts

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { QuarantineBugDialog } from "./quarantine-bug-dialog.js";
+import { quarantineDemoEntries } from "./quarantine-fixtures.js";
+import type { QuarantineEntry } from "./quarantine-report.js";
+import { QuarantineSection } from "./quarantine-section.js";
+
+const noop = () => {};
+const [base, second] = quarantineDemoEntries;
+const ISSUE_URL = "https://github.com/remit-mail/reader/issues/new?title=x";
+
+const render = (entries: readonly QuarantineEntry[]) =>
+	renderToString(createElement(QuarantineSection, { entries, onCutBug: noop }));
+
+describe("QuarantineSection", () => {
+	it("reassures when nothing is set aside", () => {
+		const html = render([]);
+		assert.match(html, /Nothing is set aside/);
+		assert.doesNotMatch(html, /role="alert"/);
+	});
+
+	it("shows a single entry as a fact, without an alert", () => {
+		const html = render([base]);
+		assert.match(html, /uid 40217/);
+		assert.doesNotMatch(html, /role="alert"/);
+	});
+
+	it("raises an alert once more than one message is set aside", () => {
+		const html = render([base, second]);
+		assert.match(html, /role="alert"/);
+		assert.match(html, /2 messages could not be read/);
+	});
+
+	it("shows the parser's own words on screen, where the report will not", () => {
+		const html = render([base]);
+		assert.match(html, /multipart boundary was never closed/);
+	});
+
+	it("offers reporting as the only per-row action", () => {
+		const html = render([base]);
+		assert.match(html, /Cut a bug/);
+		assert.doesNotMatch(html, /Try again|Retry/);
+	});
+});
+
+describe("QuarantineBugDialog", () => {
+	it("shows the whole report before anything is filed", () => {
+		const html = renderToString(
+			createElement(QuarantineBugDialog, {
+				entry: base,
+				onClose: noop,
+				onCopy: noop,
+				issueUrl: ISSUE_URL,
+			}),
+		);
+		assert.match(html, /UnterminatedMultipartBoundary/);
+		assert.match(html, /attachment names, or the parser's own error text/);
+		assert.match(html, /Copy report/);
+	});
+
+	it("never renders the parser's own error text into the report", () => {
+		const html = renderToString(
+			createElement(QuarantineBugDialog, {
+				entry: base,
+				onClose: noop,
+				onCopy: noop,
+				issueUrl: ISSUE_URL,
+			}),
+		);
+		// The row shows it; the report must not. Locked at the render boundary,
+		// which is where the regression would actually happen.
+		assert.doesNotMatch(html, /multipart boundary was never closed/);
+	});
+
+	it("files through the supplied url with hardened external rel", () => {
+		const html = renderToString(
+			createElement(QuarantineBugDialog, {
+				entry: base,
+				onClose: noop,
+				onCopy: noop,
+				issueUrl: ISSUE_URL,
+			}),
+		);
+		assert.match(html, /rel="noopener noreferrer"/);
+		assert.match(html, /focus-visible:ring-2/);
+	});
+
+	it("renders nothing without an entry", () => {
+		const html = renderToString(
+			createElement(QuarantineBugDialog, {
+				entry: null,
+				onClose: noop,
+				onCopy: noop,
+				issueUrl: ISSUE_URL,
+			}),
+		);
+		assert.equal(html, "");
+	});
+});

package/src/components/quarantine-section.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { QuarantineBugDialog } from "./quarantine-bug-dialog.js";
+import { quarantineDemoEntries } from "./quarantine-fixtures.js";
+import type { QuarantineEntry } from "./quarantine-report.js";
+import { QuarantineSection } from "./quarantine-section.js";
+
+const [unterminatedBoundary, unknownCharset, truncatedBody] =
+	quarantineDemoEntries;
+
+/**
+ * Stands in for the app's shared bug-report helper, which owns the URL budget
+ * and the repository constant.
+ */
+const demoIssueUrl = "https://github.com/remit-mail/reader/issues/new";
+
+const meta: Meta<typeof QuarantineSection> = {
+	title: "Settings/Quarantine",
+	component: QuarantineSection,
+	parameters: { layout: "padded" },
+	args: { onCutBug: () => {} },
+	decorators: [
+		(Story) => (
+			<div className="mx-auto max-w-2xl">
+				<Story />
+			</div>
+		),
+	],
+};
+export default meta;
+
+type Story = StoryObj<typeof QuarantineSection>;
+
+export const Empty: Story = {
+	args: { entries: [] },
+};
+
+export const OneEntry: Story = {
+	args: { entries: [unterminatedBoundary] },
+};
+
+export const AlertState: Story = {
+	args: { entries: [unterminatedBoundary, unknownCharset, truncatedBody] },
+};
+
+export const CutABugFlow: Story = {
+	render: () => {
+		const [open, setOpen] = useState<QuarantineEntry | null>(null);
+		const [copied, setCopied] = useState(false);
+		return (
+			<>
+				<QuarantineSection entries={quarantineDemoEntries} onCutBug={setOpen} />
+				{copied && <p className="mt-3 text-xs text-positive">Report copied.</p>}
+				<QuarantineBugDialog
+					entry={open}
+					issueUrl={demoIssueUrl}
+					onClose={() => setOpen(null)}
+					onCopy={() => setCopied(true)}
+				/>
+			</>
+		);
+	},
+};
+
+export const BugReport: Story = {
+	render: () => (
+		<QuarantineBugDialog
+			entry={unterminatedBoundary}
+			issueUrl={demoIssueUrl}
+			onClose={() => {}}
+			onCopy={() => {}}
+		/>
+	),
+};

package/src/components/quarantine-section.tsx

@@ -0,0 +1,71 @@
+import { CheckCircle2, TriangleAlert } from "lucide-react";
+import { Banner } from "./banner.js";
+import { QuarantineEntryRow } from "./quarantine-entry-row.js";
+import type { QuarantineEntry } from "./quarantine-report.js";
+
+export interface QuarantineSectionProps {
+	entries: readonly QuarantineEntry[];
+	onCutBug: (entry: QuarantineEntry) => void;
+}
+
+/**
+ * The quarantine list in settings.
+ *
+ * A message that could not be read was never written, so it cannot be found
+ * anywhere else — this list is the only record that it existed. One entry is a
+ * fact and reads as one. More than one is a pattern, and a pattern is a bug, so
+ * it raises an alert.
+ */
+export function QuarantineSection({
+	entries,
+	onCutBug,
+}: QuarantineSectionProps) {
+	return (
+		<section className="space-y-3">
+			<header className="space-y-1">
+				<h2 className="text-sm font-semibold text-fg">Messages set aside</h2>
+				<p className="text-xs text-fg-muted">
+					Mail Remit could not read is set aside here instead of being skipped,
+					so nothing goes missing quietly. The rest of the folder keeps syncing.
+					Recovering a set-aside message is a re-sync, not a per-row action.
+				</p>
+			</header>
+
+			{entries.length === 0 && (
+				<div className="flex items-center gap-2 rounded-sm border border-line bg-surface px-row-inset py-3">
+					<CheckCircle2 className="size-4 shrink-0 text-positive" aria-hidden />
+					<p className="text-sm text-fg-muted">
+						Every message has been read successfully. Nothing is set aside.
+					</p>
+				</div>
+			)}
+
+			{entries.length > 1 && (
+				<Banner tone="warning">
+					<p className="flex items-start gap-2">
+						<TriangleAlert className="mt-0.5 size-4 shrink-0" aria-hidden />
+						<span>
+							<span className="font-semibold">
+								{`${entries.length} messages could not be read.`}
+							</span>{" "}
+							More than one means something is wrong with how Remit reads mail,
+							not with the mail. Reporting one of these gets it fixed.
+						</span>
+					</p>
+				</Banner>
+			)}
+
+			{entries.length > 0 && (
+				<ul className="rounded-sm border border-line bg-surface">
+					{entries.map((entry) => (
+						<QuarantineEntryRow
+							key={entry.quarantineId}
+							entry={entry}
+							onCutBug={onCutBug}
+						/>
+					))}
+				</ul>
+			)}
+		</section>
+	);
+}