Keep settings with the account, not the browser

Every setting lived in localStorage, so none of them travelled between devices. The sharpest edge is the default identity: with none set the address that sorts first wins, so mail goes out from an address the recipient may not recognise -- and someone who sets it at work finds it unset at home, with nothing to say so. Reported in #54. They now live in a settings.json in the account's own JMAP Files, beside the signature images already kept there. ihasmail itself stays stateless: no volume, no database, nothing to back up separately, and the settings are covered by whatever backs up the mail store. localStorage stays as a cache rather than the source of truth, so the first frame is painted from it and the file corrects it a moment later. A private window has no cache and shows defaults for that one frame, which is the trade for not gating the whole app on a network round trip. Not everything should follow the account. A list-pane width picked on a 27" monitor is wrong on a laptop, and the notification toggles track a permission the browser grants per-device, so claiming it elsewhere would be a lie. Those stay local, written as a list of exceptions so that a setting added later syncs by default -- which is what adding one almost always means. Writes are coalesced: update() fires on every frame of a splitter drag, so a change waits 3s and the newest value wins. A tab going away flushes first, as does signing out, so a setting changed seconds before either is not lost. The ihasmail folder is now hidden from the Files view, contents and all. Hiding the folder alone would have been worse than showing it: the tree attaches a node whose parent is missing to the root, so the signature images would have spilled into the top level as if the user had put them there. Those images have been visible since signatures shipped. Requires 0.16 -- FileNode/query cannot see directories before that. On 0.15 settings stay local exactly as they were. Verified against the mock end to end: folder create, blob upload, node create, read back, update, re-read. Not yet exercised against the live 0.16.19.
2026-08-26 08:19:57 -07:00
parent abd2269581
commit b7e0fc0c7d
10 changed files with 520 additions and 55 deletions
@@ -0,0 +1,158 @@
+/**
+ * Settings that follow the account rather than the browser.
+ *
+ * Everything used to live in localStorage, which meant no preference travelled
+ * between devices — most painfully the default identity, where the fallback is
+ * whichever address sorts first, so a forgotten setting sends mail from an
+ * address the recipient may not know (issue #54).
+ *
+ * The store is a `settings.json` in the account's own JMAP Files, beside the
+ * signature images that are already kept there. That keeps ihasmail itself
+ * stateless: no volume, no database, nothing to back up separately, and the
+ * settings are covered by whatever backs up the mail store.
+ *
+ * localStorage stays, demoted to a cache: it is what paints the first frame,
+ * and the file overwrites it once it lands. A browser with no cache (a private
+ * window) therefore shows defaults for one frame before the account's real
+ * settings arrive.
+ *
+ * Requires Stalwart 0.16: `FileNode/query` before that cannot see directories
+ * and the rights model differs. On an older server the settings simply stay
+ * local, exactly as they were.
+ */
+import { CAP, client, setErrorMessage } from "@/jmap/client";
+import type { FileNode, Id, SetResponse } from "@/jmap/types";
+import { ensureFolder, findInFolder, nodeBlobId } from "@/lib/appFolder";
+import { fileCreate, supportsNodeType } from "@/lib/filenode";
+import { useSession } from "@/store/session";
+
+const FILE = "settings.json";
+const TYPE = "application/json";
+
+/** How long a change sits before it is written up. */
+const DEBOUNCE_MS = 3000;
+
+let timer: number | null = null;
+let pending: Record<string, unknown> | null = null;
+let inFlight: Promise<void> | null = null;
+/** Nothing is pushed before the first load has settled, or we would race it. */
+let armed = false;
+let listenersBound = false;
+
+export function settingsSyncAvailable(): boolean {
+  return supportsNodeType() && client.hasCapability(CAP.filenode) && Boolean(useSession.getState().accountFor(CAP.filenode));
+}
+
+/**
+ * Read the account's settings file. Returns null when there is nothing to read
+ * — no file yet, no Files, an older server — which leaves the local cache in
+ * charge rather than wiping it.
+ */
+export async function loadRemoteSettings(): Promise<Record<string, unknown> | null> {
+  if (!settingsSyncAvailable()) return null;
+  const accountId = useSession.getState().accountFor(CAP.filenode)!;
+  try {
+    const folderId = await ensureFolder(accountId);
+    const node = await findInFolder(accountId, folderId, FILE);
+    if (!node?.blobId) return null;
+    const text = await client.fetchBlobText(accountId, node.blobId, TYPE);
+    const parsed = JSON.parse(text) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return parsed as Record<string, unknown>;
+  } catch {
+    // A settings file we cannot read must not cost anyone their session; the
+    // cached settings are still perfectly good.
+    return null;
+  }
+}
+
+/** Allow pushes. Called once the first load has settled, either way. */
+export function armSettingsSync(): void {
+  armed = true;
+  bindFlushListeners();
+}
+
+/** Stop syncing and drop anything queued (logout). */
+export function stopSettingsSync(): void {
+  armed = false;
+  pending = null;
+  if (timer !== null) {
+    window.clearTimeout(timer);
+    timer = null;
+  }
+}
+
+/**
+ * Queue the synced settings for writing. Called on every change — including
+ * each frame of a splitter drag — so it coalesces: the newest value wins and
+ * one request goes out once the changes stop.
+ */
+export function queueSettingsPush(synced: Record<string, unknown>): void {
+  if (!armed || !settingsSyncAvailable()) return;
+  pending = synced;
+  if (timer !== null) window.clearTimeout(timer);
+  timer = window.setTimeout(() => {
+    timer = null;
+    void flushSettingsPush();
+  }, DEBOUNCE_MS);
+}
+
+/** Write anything queued now, rather than waiting out the debounce. */
+export async function flushSettingsPush(): Promise<void> {
+  if (timer !== null) {
+    window.clearTimeout(timer);
+    timer = null;
+  }
+  if (!pending || !armed) return;
+  const body = pending;
+  pending = null;
+  // Serialise: two overlapping writes could land in either order.
+  inFlight = (inFlight ?? Promise.resolve()).then(() => writeSettings(body)).catch(() => undefined);
+  await inFlight;
+}
+
+async function writeSettings(body: Record<string, unknown>): Promise<void> {
+  if (!settingsSyncAvailable()) return;
+  const accountId = useSession.getState().accountFor(CAP.filenode)!;
+  const json = JSON.stringify(body, null, 2);
+  // Byte length, not character count: a template or a signature with any
+  // non-ASCII in it would otherwise be reported shorter than it is.
+  const blob = new Blob([json], { type: TYPE });
+  const up = await client.upload(accountId, blob, { type: TYPE });
+  const folderId = await ensureFolder(accountId);
+  const existing = await findInFolder(accountId, folderId, FILE);
+  if (existing) {
+    const res = await client.call<SetResponse<FileNode>>("FileNode/set", {
+      accountId,
+      update: { [existing.id]: { blobId: up.blobId, type: TYPE, size: blob.size } },
+    });
+    const err = res.notUpdated?.[existing.id];
+    if (err) throw new Error(setErrorMessage(err));
+    return;
+  }
+  const res = await client.call<SetResponse<FileNode>>("FileNode/set", {
+    accountId,
+    create: { s: fileCreate(folderId, FILE, up.blobId, TYPE) },
+  });
+  const err = res.notCreated?.s;
+  if (err) throw new Error(setErrorMessage(err));
+  // Some servers hand back no blobId on create; ask, so the next read finds it.
+  await nodeBlobId(accountId, (res.created?.s as Partial<FileNode> | undefined)?.id as Id | undefined);
+}
+
+/**
+ * A debounce that outlives the page helps no one, so a tab going away writes
+ * first. `visibilitychange` is the one that fires reliably on mobile; `pagehide`
+ * covers the desktop close.
+ */
+function bindFlushListeners(): void {
+  if (listenersBound || typeof window === "undefined") return;
+  listenersBound = true;
+  const flush = () => {
+    if (pending) void flushSettingsPush();
+  };
+  window.addEventListener("pagehide", flush);
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") flush();
+  });
+}