Guide: progress bar, clearer end-of-run errors, reconnect note #77

Merged
jcoffey-dev merged 1 commits from feat/migrate-guide-ux into main 2026-11-13 03:16:34 +00:00
6 changed files with 157 additions and 28 deletions

No files matched your search

+8
View File
@@ -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
+9 -3
View File
@@ -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, `<DIR>/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 `<DIR>`
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
+41 -16
View File
@@ -95,7 +95,11 @@ struct Job {
kind: Kind,
/// Where a directory run writes.
out: Option<PathBuf>,
/// The run's stderr: the human log, newest last.
lines: Vec<String>,
/// The run's stdout under `--progress json`: one object per line
/// (`start`, `account`, `end`, …), so the page can show real progress.
events: Vec<Value>,
exit: Option<i32>,
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<dyn Read + Send>)> = [
child
.stdout
.take()
.map(|o| Box::new(o) as Box<dyn Read + Send>),
.map(|o| (true, Box::new(o) as Box<dyn Read + Send>)),
child
.stderr
.take()
.map(|e| Box::new(e) as Box<dyn Read + Send>),
.map(|e| (false, Box::new(e) as Box<dyn Read + Send>)),
]
.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::<Value>(&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))
}
+13
View File
@@ -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; }
+64 -9
View File
@@ -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);
+22
View File
@@ -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("[email protected],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()