From ef09674cb62b1b7418e9eaea0671f998060330ad Mon Sep 17 00:00:00 2001 From: John Coffey Date: Thu, 12 Nov 2026 18:35:51 -0700 Subject: [PATCH] guide: progress bar, clearer end-of-run errors, reconnect note Run the guide's preview and move with --progress json and drive the page off the structured event stream instead of scraping the log. While a run is going the page shows a real progress bar with a running count and percentage; when it ends it says how many accounts didn't finish and points at the report's marked rows. The guide process outlives the browser, so a reload reconnects to a run in progress and now says so. stdout now carries the JSON events and stderr the human log, kept apart in the job so each is rendered for what it is. --- CHANGELOG.md | 8 +++++ docs/usage.md | 12 +++++-- src/guide/mod.rs | 57 ++++++++++++++++++++++--------- src/guide/page/guide.css | 13 +++++++ src/guide/page/guide.js | 73 +++++++++++++++++++++++++++++++++++----- tests/mock_guide.rs | 22 ++++++++++++ 6 files changed, 157 insertions(+), 28 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a584bcf..3c30847 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,14 @@ candidates before a series ships (`27.1-rc.1`). The tag is the version with a limit, alongside the existing honoring of 429/`Retry-After`. Off by default (uncapped). +### Changed +- The `guide` page shows a real progress bar with a running count and + percentage while a preview or move runs, reads the counts from the run's + structured progress stream rather than scraping its log, and when a run + ends it says how many accounts didn't finish and points at the table. A + reload reconnects to a run already in progress -- the guide outlives the + browser -- and now says so. + ## [27.1-rc.12] The twelfth release candidate of the 27.1 series: upstream v1.0.15, keywords diff --git a/docs/usage.md b/docs/usage.md index 6f7421d..f8152a9 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -795,15 +795,21 @@ opens it. The page asks five things in turn: gets a generated password, written to a file only its owner can read. 4. **Preview:** a dry run. It signs in for each account, counts what would move, and creates nothing. -5. **Move,** with progress, a report, and a final pass for when the old - server stops taking mail. +5. **Move,** with a progress bar that fills as accounts finish and a running + count and percentage beside it, a report, and a final pass for when the + old server stops taking mail. When a run ends the page says how many + accounts didn't finish and points at the report, whose failed rows are + marked. The guide writes an ordinary plan, `/plan.json`, and runs it with `migrate`, so a move started in the browser can be finished from a terminal. The page shows the command. Everything else goes into `` too: the archives, the logs, `work/report.csv`, the passwords file, and the answers so far, in `guide.json`. A guide started again on the same -directory picks up where it was. +directory picks up where it was. The guide process also outlives the +browser: close the tab or reload while a move runs and the page reconnects +to it and says so. A move that stopped part way starts again from where +each account left off -- start it once more, or run the final pass. - **Only this browser.** The page is served on 127.0.0.1 alone, at an address with a random token that changes each start. A request without diff --git a/src/guide/mod.rs b/src/guide/mod.rs index d0f1d00..0726014 100644 --- a/src/guide/mod.rs +++ b/src/guide/mod.rs @@ -95,7 +95,11 @@ struct Job { kind: Kind, /// Where a directory run writes. out: Option, + /// The run's stderr: the human log, newest last. lines: Vec, + /// The run's stdout under `--progress json`: one object per line + /// (`start`, `account`, `end`, …), so the page can show real progress. + events: Vec, exit: Option, result: Value, } @@ -346,7 +350,7 @@ impl Guide { let job = state.job.as_ref().map(|j| { json!({ "kind": j.kind.name(), "running": j.exit.is_none(), "exit": j.exit, - "lines": j.lines, "result": j.result, + "lines": j.lines, "events": j.events, "result": j.result, }) }); json!({ @@ -513,34 +517,52 @@ impl Guide { kind, out, lines: vec![format!("inbuxa-migrate {}", args.join(" "))], + events: Vec::new(), exit: None, result: Value::Null, }); - let readers: Vec<_> = [ + // stdout carries the `--progress json` events; stderr the human log. + let streams: Vec<(bool, Box)> = [ child .stdout .take() - .map(|o| Box::new(o) as Box), + .map(|o| (true, Box::new(o) as Box)), child .stderr .take() - .map(|e| Box::new(e) as Box), + .map(|e| (false, Box::new(e) as Box)), ] .into_iter() .flatten() - .map(|out| { - let me = Arc::clone(self); - std::thread::spawn(move || { - for line in BufReader::new(out).lines().map_while(Result::ok) { - if let Some(job) = lock(&me.state).job.as_mut() { - job.lines.push(line); - let over = job.lines.len().saturating_sub(KEEP_LINES); - job.lines.drain(..over); - } - } - }) - }) .collect(); + let readers: Vec<_> = streams + .into_iter() + .map(|(is_stdout, out)| { + let me = Arc::clone(self); + std::thread::spawn(move || { + for line in BufReader::new(out).lines().map_while(Result::ok) { + let event = is_stdout + .then(|| serde_json::from_str::(&line).ok()) + .flatten() + .filter(Value::is_object); + if let Some(job) = lock(&me.state).job.as_mut() { + match event { + Some(v) => { + job.events.push(v); + let over = job.events.len().saturating_sub(KEEP_LINES); + job.events.drain(..over); + } + None => { + job.lines.push(line); + let over = job.lines.len().saturating_sub(KEEP_LINES); + job.lines.drain(..over); + } + } + } + } + }) + }) + .collect(); let me = Arc::clone(self); std::thread::spawn(move || { for r in readers { @@ -604,6 +626,9 @@ impl Guide { Kind::FinalPass => args.push("--again".into()), _ => {} } + // Structured progress on stdout, so the page can show a real bar and + // name what failed; the human log still comes on stderr. + args.extend(["--progress".to_owned(), "json".to_owned()]); args.push("work".into()); Ok((args, f.env(), None)) } diff --git a/src/guide/page/guide.css b/src/guide/page/guide.css index b3340cd..f1a4221 100644 --- a/src/guide/page/guide.css +++ b/src/guide/page/guide.css @@ -98,6 +98,19 @@ button:disabled { opacity: .5; cursor: default; } } .job .summary { font-weight: 600; margin: .75rem 0 .25rem; } +.progress { display: flex; align-items: center; gap: .6rem; margin: .25rem 0 .5rem; } +.progress progress { + flex: 1; height: .9rem; appearance: none; -webkit-appearance: none; + border: 1px solid var(--line); border-radius: 6px; background: var(--page); overflow: hidden; +} +.progress progress::-webkit-progress-bar { background: var(--page); } +.progress progress::-webkit-progress-value { background: var(--accent); } +.progress progress::-moz-progress-bar { background: var(--accent); } +.progress-label { + font-variant-numeric: tabular-nums; color: var(--muted); + font-size: .85rem; white-space: nowrap; +} + table { border-collapse: collapse; width: 100%; font-size: .85rem; margin-top: .5rem; } th, td { text-align: left; padding: .3rem .5rem; border-bottom: 1px solid var(--line); vertical-align: top; } td:last-child { overflow-wrap: anywhere; } diff --git a/src/guide/page/guide.js b/src/guide/page/guide.js index 3e6148e..089a274 100644 --- a/src/guide/page/guide.js +++ b/src/guide/page/guide.js @@ -5,6 +5,10 @@ const $ = (id) => document.getElementById(id); let polling = false; +let firstRefresh = true; +// True when the page opened onto a run that was already going: the guide +// outlives the browser, so a reload reconnects to it rather than losing it. +let reconnected = false; function kind() { return document.querySelector("input[name=kind]:checked").value; @@ -144,17 +148,59 @@ function reportTable(csv) { return table; } -function summary(job) { - const progress = job.lines.map((l) => l.match(/^\[(\d+)\/(\d+)\]/)).filter((m) => m).pop(); - if (job.running) { - return progress ? `Running: ${progress[1]} of ${progress[2]} accounts done.` : "Running…"; +// The accounts done and the total, from the structured progress events +// (a `start` gives the total, each `account` the running count). Falls back +// to the `[n/total]` markers the run also prints, for an older binary. +function progressOf(job) { + let done = 0, total = 0; + for (const e of job.events || []) { + if (e.event === "start") total = e.accounts ?? total; + else if (e.event === "account") { done = e.n ?? done; total = e.total ?? total; } } + if (total === 0) { + const m = job.lines.map((l) => l.match(/^\[(\d+)\/(\d+)\]/)).filter((x) => x).pop(); + if (m) { done = Number(m[1]); total = Number(m[2]); } + } + return { done, total }; +} + +function endEvent(job) { + return (job.events || []).filter((e) => e.event === "end").pop(); +} + +function progressBar(done, total) { + const wrap = document.createElement("div"); + wrap.className = "progress"; + const bar = document.createElement("progress"); + bar.max = total; + bar.value = done; + const label = document.createElement("span"); + label.className = "progress-label"; + label.textContent = `${done} / ${total} · ${Math.floor((done / total) * 100)}%`; + wrap.append(bar, label); + return wrap; +} + +function summary(job) { const preview = job.kind === "preview"; + if (job.running) { + const { done, total } = progressOf(job); + return total ? `Running: ${done} of ${total} accounts (${Math.floor((done / total) * 100)}%).` : "Running…"; + } const report = (job.result && job.result.report) || ""; if (/^\(setup\),[^,]*,failed,/m.test(report)) { return (preview ? "Setting up the accounts would fail" : "Setting up the accounts failed") + ", so no account was " + (preview ? "previewed" : "moved") + ". The table says why."; } + const end = endEvent(job); + if (end) { + const unfinished = end.unfinished ?? 0, total = (end.done ?? 0) + unfinished; + if (unfinished === 0) return preview ? "Nothing in the preview failed." : "Every account moved."; + const count = `${unfinished} of ${total} account${total === 1 ? "" : "s"}`; + return preview + ? `${count} would fail. The table says which, and why.` + : `${count} didn't finish. Fix what the table shows and start again: it picks up where each stopped.`; + } if (job.exit === 0) return preview ? "Nothing in the preview failed." : "Every account moved."; if (job.exit === 5) { return preview @@ -164,7 +210,7 @@ function summary(job) { return (preview ? "The preview" : "The run") + " stopped. The output says why."; } -function renderJob(job) { +function renderJob(job, reconnected) { if (job.kind === "directory") { if (job.running) status("accounts-status", true, "Reading the list from the server…"); else if (job.result && job.result.accounts) { @@ -174,10 +220,18 @@ function renderJob(job) { return; } const box = $(job.kind === "preview" ? "preview-job" : "run-job"); + const ok = job.running || job.exit === 0; + const parts = []; + if (reconnected) parts.push(para("note", "Reconnected to a run already in progress — it kept going while the page was away.")); + parts.push(para("summary " + (ok ? "" : "bad"), summary(job))); + if (job.running) { + const { done, total } = progressOf(job); + if (total) parts.push(progressBar(done, total)); + } const pre = document.createElement("pre"); pre.textContent = job.lines.slice(-40).join("\n"); - const ok = job.running || job.exit === 0; - box.replaceChildren(para("summary " + (ok ? "" : "bad"), summary(job)), pre); + parts.push(pre); + box.replaceChildren(...parts); const result = job.result || {}; if (result.report) box.append(reportTable(result.report), para("note", "Report: " + result.reportPath)); if (result.passwords) box.append(para("note", "The new accounts' passwords are in " + result.passwords)); @@ -186,13 +240,14 @@ function renderJob(job) { async function refresh() { const s = await call("api/state"); + const running = s.job && s.job.running; + if (firstRefresh) { firstRefresh = false; reconnected = !!running; } $("dir").textContent = s.dir; $("command").textContent = s.command; $("src-secret-kept").hidden = !s.hasSourceSecret; $("dst-token-kept").hidden = !s.hasTargetToken; - const running = s.job && s.job.running; for (const id of ["preview", "run", "final", "read-directory"]) $(id).disabled = running; - if (s.job) renderJob(s.job); + if (s.job) renderJob(s.job, reconnected && running); if (running && !polling) { polling = true; setTimeout(() => { polling = false; refresh(); }, 1000); diff --git a/tests/mock_guide.rs b/tests/mock_guide.rs index c431419..9d5990e 100644 --- a/tests/mock_guide.rs +++ b/tests/mock_guide.rs @@ -93,6 +93,18 @@ fn a_maildir_move_previews_runs_and_reports() { "{report}" ); assert_eq!(state["job"]["exit"], 0, "{state}"); + // The page drives its progress bar and counts off the structured events. + let events = state["job"]["events"].as_array().unwrap(); + let kinds: Vec<&str> = events.iter().filter_map(|e| e["event"].as_str()).collect(); + assert!( + kinds.contains(&"start") && kinds.contains(&"account") && kinds.contains(&"end"), + "{events:?}" + ); + let start = events.iter().find(|e| e["event"] == "start").unwrap(); + assert_eq!(start["accounts"], 1, "{start}"); + let end = events.iter().find(|e| e["event"] == "end").unwrap(); + assert_eq!(end["done"], 1, "{end}"); + assert_eq!(end["unfinished"], 0, "{end}"); // The token came once; an empty one keeps it. let mut again = form.clone(); @@ -107,6 +119,16 @@ fn a_maildir_move_previews_runs_and_reports() { "{report}" ); assert!(report.contains("ann@example.org,export,failed"), "{report}"); + // The final `end` event counts the account as unfinished, so the page can + // say so and point at the table. + let end = state["job"]["events"] + .as_array() + .unwrap() + .iter() + .rev() + .find(|e| e["event"] == "end") + .unwrap(); + assert_eq!(end["unfinished"], 1, "{end}"); assert!( state["command"] .as_str() -- 2.54.0