task_progress 0.0.1

data/js/row_view.js

@@ -0,0 +1,69 @@
+import { humanBytes } from "./task_tree.js"
+import { pathKey } from "./paths.js"
+
+const GLYPHS = { done: "✓", failed: "✗", canceled: "⊘", pending: "·" }
+const FINISHED = new Set(["done", "failed", "canceled"])
+
+// A circle with a cross in it, drawn in the row's text color - the same in every font
+export const CANCEL_ICON = '<svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"><circle cx="8" cy="8" r="6.25" fill="none" stroke="currentColor" stroke-width="1.5"/><path d="M5.6 5.6l4.8 4.8M10.4 5.6l-4.8 4.8" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>'
+
+// What one row shows, worked out once for both demos - a task, or siblings folded into one row
+// (see TaskTree#rows)
+export function rowView(tree, node) {
+  if (node.fold) return foldView(node)
+  const percent = tree.percentOf(node)
+  const leaf = node.children.length === 0
+  const indeterminate = leaf && node.indeterminate && node.status === "active"
+  let measure = `${percent}%`
+  if (leaf && node.total != null) {
+    measure = node.unit === "bytes" ? `${humanBytes(node.count)} / ${humanBytes(node.total)}` : `${node.count} / ${node.total}`
+  } else if (indeterminate) {
+    measure = elapsed(tree, node)
+  }
+  // A task called done with something still running under it - browser work grafted to it, say -
+  // is not through, and is drawn as running until it is
+  const status = node.status === "done" && !tree.complete(node) ? "active" : node.status
+  // Every state is one inner span, so the .icon box around it never changes; the spinner is drawn in CSS
+  const glyph = GLYPHS[status]
+  const icon = glyph ? `<span>${glyph}</span>` : '<span class="spin"></span>'
+  return {
+    key: pathKey(node.path), path: node.path, depth: node.path.length, name: node.name, status, stale: node.stale,
+    local: !!tree.local || node.path.some((id) => String(id).startsWith("_")), // runs in this browser, see LocalTasks
+    cancelable: !!node.cancelable && !FINISHED.has(node.status),
+    percent, indeterminate, measure, icon,
+    message: [node.attempt > 1 ? `attempt ${node.attempt}` : null,
+      node.status === "failed" ? node.error?.message : [pace(tree, node), node.message].filter(Boolean).join(" · ")].filter(Boolean).join(" · ")
+  }
+}
+
+function foldView({ path, status, count }) {
+  const done = status === "done"
+  return {
+    key: pathKey(path), path, depth: path.length, name: `${count.toLocaleString("en-US")} more ${done ? "done" : "waiting"}`,
+    status, stale: false, local: false, cancelable: false, folded: true,
+    percent: done ? 100 : 0, indeterminate: false, measure: "", icon: `<span>${GLYPHS[status]}</span>`, message: ""
+  }
+}
+
+// The rate over the run so far and the time left at it, as the terminal shows them
+function pace(tree, node) {
+  if (node.status !== "active" || node.children.length > 0 || !node.started_at || node.count === 0) return ""
+  const seconds = tree.now() - node.started_at
+  if (seconds < 1) return ""
+  const rate = node.count / seconds
+  const per = node.unit === "bytes" ? `${humanBytes(rate)}/s` : `${rate < 10 ? rate.toFixed(1) : Math.floor(rate)}/s`
+  if (node.total == null || node.total <= node.count) return per
+  return `${per}, ${duration((node.total - node.count) / rate)} left`
+}
+
+function duration(seconds) {
+  if (seconds < 60) return `${seconds.toFixed(1)}s`
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m${String(Math.floor(seconds % 60)).padStart(2, "0")}s`
+  return `${Math.floor(seconds / 3600)}h${String(Math.floor((seconds % 3600) / 60)).padStart(2, "0")}m`
+}
+
+// Measured on the clock the times came from, never this machine's
+function elapsed(tree, node) {
+  if (!node.started_at) return ""
+  return `${Math.max(0, (node.finished_at ?? tree.now()) - node.started_at).toFixed(1)}s`
+}

data/js/stimulus_controller.d.ts

@@ -0,0 +1,10 @@
+import { Controller } from "@hotwired/stimulus"
+import type { Path } from "./task_tree.js"
+import type { LocalTasks } from "./local_tasks.js"
+
+/** Register as "task-tree" - see the MANUAL */
+export default class TaskTreeController extends Controller {
+  graft(path: Path, local: LocalTasks): void
+  /** Draws tasks running in this browser on their own, in place of whatever it followed */
+  show(local: LocalTasks): void
+}

data/js/stimulus_controller.js

@@ -0,0 +1,137 @@
+import { Controller } from "@hotwired/stimulus"
+import { followEventSourceAt, followLocal, followPollingAt, followProgress, requestCancel, pathKey } from "./task_tree.js"
+import { rowView, CANCEL_ICON } from "./row_view.js"
+
+// Draws a tree. Give it what TaskProgress.for_page hands a page, as the progress value - it draws
+// the snapshot at once, follows the stream, falls back to polling where SSE does not get through,
+// and its cancel buttons ask where it says:
+//   <div data-controller="task-tree" data-task-tree-progress-value="<%= TaskProgress.for_page(key).to_json %>"></div>
+// Or point it at a TaskProgress SSE stream with the url value:
+//   <div data-controller="task-tree" data-task-tree-url-value="/jobs/abc/events"></div>
+// Changing the value follows the new stream instead. Where SSE does not get through, point it at
+// a TaskProgress::Poll endpoint and give it a poll value - seconds between polls - and a wait
+// value to long-poll instead. Draws once a frame at most, and then only
+// the rows the batches in that frame touched. Fires task-tree:render after every draw.
+//
+// A cancelable task gets a cancel button. Pressing it fires task-tree:cancel with the task's
+// path, and - unless that is prevented - creates a cancellation at the cancel-url value, if there
+// is one, signed with the cancel-token value. A task running in this browser is canceled here.
+//
+// `graft(path, localTasks)` draws tasks running in this browser under a server task, until the
+// url value changes - see TaskTree#graft. `show(localTasks)` draws them on their own instead, with
+// no server at all - uploads, say. Reach the controller through an outlet, or with
+// application.getControllerForElementAndIdentifier(element, "task-tree")
+export default class extends Controller {
+  static values = { url: String, progress: Object, cancelUrl: String, cancelToken: String, poll: Number, wait: Number }
+
+  urlValueChanged() { this.#follow() }
+
+  progressValueChanged() { this.#follow() }
+
+  #follow(local = null) {
+    this.#stop()
+    this.rows = new Map()
+    this.keys = null
+    this.element.replaceChildren()
+    const draw = (tree, changes) => this.render(tree, changes)
+    this.local = local
+    if (local) return (this.following = followLocal(local, draw))
+    const progress = this.progressValue
+    if (progress?.events || progress?.poll) {
+      const transport = this.pollValue || this.waitValue ? "poll" : "auto"
+      this.following = followProgress(progress, draw, { transport, poll: this.pollValue || 1, wait: this.waitValue })
+    } else if (this.urlValue) {
+      this.following = this.pollValue || this.waitValue
+        ? followPollingAt(this.urlValue, draw, { poll: this.pollValue || 1, wait: this.waitValue })
+        : followEventSourceAt(this.urlValue, draw)
+    }
+  }
+
+  // Stimulus does not tell a controller its values again when its element comes back - moved in
+  // the page, or kept across visits with data-turbo-permanent - so it picks up where it was
+  connect() { if (!this.following) this.#follow(this.local) }
+
+  show(local) { this.#follow(local) }
+
+  disconnect() { this.#stop() }
+
+  graft(path, local) {
+    if (this.following) this.ungrafts.push(this.following.tree.graft(path, local))
+  }
+
+  #stop() {
+    for (const ungraft of this.ungrafts ?? []) ungraft()
+    this.ungrafts = []
+    this.following?.close()
+    this.following = null
+  }
+
+  render(tree, changes) {
+    const shown = [...tree.rows()]
+    // A task finishing can fold it away, so which rows there are is checked every time, not only when tasks come and go
+    const keys = shown.map((node) => pathKey(node.path)).join(" ")
+    const rebuilt = changes.structure || keys !== this.keys
+    if (rebuilt) {
+      const rows = new Map()
+      for (const node of shown) {
+        const k = pathKey(node.path)
+        rows.set(k, this.rows.get(k) ?? this.#row())
+      }
+      this.rows = rows
+      this.keys = keys
+      this.element.replaceChildren(...rows.values())
+    }
+    for (const node of shown) {
+      const k = pathKey(node.path)
+      // An active row reads the clock for its rate, ETA or elapsed time, so it moves without a batch for it
+      if (rebuilt || node.fold || changes.touched.has(k) || node.status === "active") this.#patch(this.rows.get(k), rowView(tree, node))
+    }
+    this.dispatch("render", { detail: changes })
+  }
+
+  #row() {
+    const el = document.createElement("div")
+    el.innerHTML = `
+      <div class="label"><span class="icon"></span><span class="name"></span><span class="message"></span></div>
+      <div class="bar"><span></span></div>
+      <button type="button" class="cancel" hidden>${CANCEL_ICON}</button>
+      <div class="measure"></div>`
+    el.view = {}
+    el.querySelector(".cancel").addEventListener("click", (event) => this.#cancel(event.currentTarget, el.view))
+    return el
+  }
+
+  #cancel(button, row) {
+    const { defaultPrevented } = this.dispatch("cancel", { detail: { path: row.path, name: row.name }, cancelable: true })
+    if (defaultPrevented) return
+    if (row.local) return this.following?.tree.cancelLocal(row.path, "Canceled in this browser")
+    const url = this.progressValue?.cancel || this.cancelUrlValue
+    if (!url) return
+    button.disabled = true // until the cancel comes down the stream, or the server says no
+    requestCancel(url, row.path, { token: this.cancelTokenValue || undefined })
+      .then((response) => { if (!response.ok) button.disabled = false }, () => { button.disabled = false })
+  }
+
+  // Writes only what differs from the last draw, so an unchanged row costs no DOM work
+  #patch(el, row) {
+    const last = el.view
+    const set = (field, write) => { if (last[field] !== row[field]) write(row[field]) }
+    if (last.status !== row.status || last.stale !== row.stale || last.folded !== row.folded) {
+      el.className = `row ${row.status}${row.stale ? " stale" : ""}${row.folded ? " folded" : ""}`
+    }
+    set("depth", (depth) => { el.querySelector(".label").style.paddingLeft = `${depth * 18}px` })
+    set("icon", (icon) => { el.querySelector(".icon").innerHTML = icon })
+    set("name", (name) => { el.querySelector(".name").textContent = name })
+    set("message", (message) => { el.querySelector(".message").textContent = message })
+    set("indeterminate", (on) => { el.querySelector(".bar").classList.toggle("indeterminate", on) })
+    set("percent", (percent) => { el.querySelector(".bar span").style.width = `${percent}%` })
+    set("measure", (measure) => { el.querySelector(".measure").textContent = measure })
+    set("cancelable", (on) => {
+      const button = el.querySelector(".cancel")
+      button.hidden = !on
+      button.disabled = false
+    })
+    set("name", (name) => { el.querySelector(".cancel").setAttribute("aria-label", `Cancel ${name}`) })
+    el.view = row
+  }
+}

data/js/task_progress_clock.d.ts

@@ -0,0 +1,2 @@
+/** <task-progress-clock started drawn [finished]> - defined when the module is imported */
+export class TaskProgressClock extends HTMLElement {}

data/js/task_progress_clock.js

@@ -0,0 +1,33 @@
+// <task-progress-clock started="…" drawn="…" [finished="…"]> - an elapsed time that ticks on
+// between the frames a server sends (see TaskProgress::HTMLRenderer), so a page drawn a few
+// times a second, or less, still counts the seconds. Its times are the server's: `drawn` is when
+// the server drew it, and the time since then is measured here, so the two clocks never have to
+// agree. A finished one stands still. Import this module once on the page, and the element
+// does the rest
+
+export class TaskProgressClock extends HTMLElement {
+  static observedAttributes = ["started", "drawn", "finished"]
+
+  connectedCallback() {
+    this.#sync()
+    this.timer = setInterval(() => this.#tick(), 100)
+  }
+
+  disconnectedCallback() { clearInterval(this.timer) }
+
+  // A morph that redraws the tree changes the attributes, and the clock starts over from them
+  attributeChangedCallback() { this.#sync() }
+
+  #sync() { this.syncedAt = performance.now() / 1000 }
+
+  #tick() {
+    const started = Number(this.getAttribute("started"))
+    if (!started) return
+    const finished = this.getAttribute("finished")
+    const now = finished ? Number(finished) : Number(this.getAttribute("drawn")) + (performance.now() / 1000 - this.syncedAt)
+    const text = `${Math.max(0, now - started).toFixed(1)}s`
+    if (this.textContent !== text) this.textContent = text
+  }
+}
+
+if (!customElements.get("task-progress-clock")) customElements.define("task-progress-clock", TaskProgressClock)

data/js/task_tree.css

@@ -0,0 +1,51 @@
+/* The rows of a task tree, as the Stimulus controller and the React component draw them.
+   The palette sits on :where(.tree), which weighs nothing - any selector of yours overrides it */
+:where(.tree) {
+  --bg: #fbfaf7; --fg: #1d1d1b; --muted: #77756f; --line: #e6e3dc;
+  --track: #ebe8e1; --fill: #2f6f4f; --fail: #b3261e; --stale: #a06a00;
+  --stripe: color-mix(in srgb, var(--fill) 60%, white);
+}
+@media (prefers-color-scheme: dark) {
+  :where(.tree) { --bg: #161615; --fg: #ecebe6; --muted: #9a978f; --line: #2c2b29; --track: #2a2927; --fill: #5fb98c; --fail: #ff7a70; --stale: #e0a640; --stripe: color-mix(in srgb, var(--fill) 55%, black); }
+}
+.tree { border-top: 1px solid var(--line); }
+/* Rows have one fixed height: every cell is a single line and the icon sits in a fixed box */
+/* label | bar | cancel | measure - the cancel column is always there, so every bar lines up */
+.row { display: grid; grid-template-columns: minmax(0, 1fr) 140px 20px 110px; gap: 12px; align-items: center; box-sizing: border-box; height: 35px; padding: 0; overflow: hidden; border-bottom: 1px solid var(--line); font-size: 14px; line-height: 20px; }
+.row .label { display: flex; gap: 8px; align-items: center; min-width: 0; height: 20px; overflow: hidden; }
+.row .name { flex: 0 1 auto; min-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.row .message { flex: 1 1 0; min-width: 0; color: var(--muted); font-size: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.row .measure { min-width: 0; color: var(--muted); font-size: 12px; text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.row.failed .name, .row.failed .message { color: var(--fail); }
+.row.stale .name::after { content: " (stale)"; color: var(--stale); }
+.row.folded .name { color: var(--muted); }
+/* Same box for every state, whatever font the glyph falls back to; only the inner .spin rotates */
+.icon { flex: none; display: inline-flex; align-items: center; justify-content: center; width: 14px; height: 14px; line-height: 14px; font-size: 13px; overflow: hidden; }
+.icon > span { display: block; line-height: 14px; }
+/* Right of the bar, the way a Finder copy shows it. A fixed box, so a row is as tall with the
+   button as without it - and hidden it keeps its place, so nothing after it moves */
+.row button.cancel { all: unset; display: inline-flex; align-items: center; justify-content: center; box-sizing: border-box; width: 20px; height: 20px; margin-left: -6px; border-radius: 50%; color: var(--muted); cursor: pointer; }
+.row button.cancel:hover, .row button.cancel:focus-visible { color: var(--fail); background: var(--track); }
+.row button.cancel:disabled { cursor: progress; opacity: 0.4; }
+.row button.cancel[hidden] { display: inline-flex; visibility: hidden; }
+/* Server-drawn rows (TaskProgress::HTMLRenderer) put the button in a form, or leave the column empty */
+.row .cancel-slot { display: inline-flex; width: 20px; height: 20px; margin: 0; }
+.bar { height: 6px; background: var(--track); border-radius: 3px; overflow: hidden; }
+.bar > span { display: block; height: 100%; background: var(--fill); transition: width 0.2s ease-out; }
+.row.failed .bar > span { background: var(--fail); }
+.row.canceled .name { color: var(--muted); }
+.row.canceled .bar > span { background: var(--muted); }
+/* Work with no measure is a barber pole: the whole bar in stripes, crawling along. One tile is
+   one stripe and one gap, so moving the background by a tile is seamless */
+.bar.indeterminate > span {
+  width: 100% !important; transition: none;
+  background-color: var(--fill);
+  background-image: linear-gradient(-45deg, var(--stripe) 25%, transparent 25%, transparent 50%, var(--stripe) 50%, var(--stripe) 75%, transparent 75%, transparent);
+  background-size: 12px 12px;
+  animation: stripes 0.6s linear infinite;
+}
+@keyframes stripes { from { background-position: 0 0; } to { background-position: 12px 0; } }
+@media (prefers-reduced-motion: reduce) { .bar.indeterminate > span { animation: none; } }
+.icon > .spin { box-sizing: border-box; width: 11px; height: 11px; border: 2px solid var(--track); border-top-color: var(--fill); border-radius: 50%; animation: spin 0.9s linear infinite; }
+@keyframes spin { to { transform: rotate(360deg); } }
+@media (max-width: 560px) { .row { grid-template-columns: minmax(0, 1fr) 80px 20px; } .row .measure { display: none; } }

data/js/task_tree.d.ts

@@ -0,0 +1,111 @@
+import type { Path } from "./paths.js"
+import type { Changes, Schedule } from "./render_queue.js"
+
+export { pathKey, pathFromKey } from "./paths.js"
+export type { Path } from "./paths.js"
+export type { Changes } from "./render_queue.js"
+
+/** One op: `[path, op, value]` - see the wire format in the MANUAL */
+export type Op = [Path, string] | [Path, string, unknown]
+
+/** A batch, as TaskProgress::Wire writes it */
+export interface Batch {
+  v: 1
+  log: string
+  prev: number
+  seq: number
+  at: number
+  ops: Op[]
+}
+
+export type Status = "pending" | "active" | "done" | "failed" | "canceled"
+
+/** One task, as the tree holds it */
+export interface Node {
+  path: Path
+  name: string
+  total: number | null
+  count: number
+  percent: number
+  weight: number
+  expect: number | null
+  indeterminate: boolean
+  cancelable: boolean
+  attempt: number | null
+  unit: string | null
+  message: string | null
+  status: Status
+  error: { class: string; message: string; backtrace?: string[] } | null
+  stale: boolean
+  opened_at: number
+  started_at: number | null
+  finished_at: number | null
+  children: string[]
+}
+
+/** Siblings drawn as one row, see TaskTree#rows */
+export interface Fold {
+  fold: true
+  path: Path
+  status: "done" | "pending"
+  count: number
+}
+
+export type ApplyOutcome = "applied" | "duplicate" | "gap" | "unsupported"
+
+/** What TaskProgress.for_page hands a page */
+export interface Progress {
+  events?: string
+  poll?: string
+  cancel?: string
+  snapshot?: Batch
+}
+
+export const WIRE_VERSION: 1
+export const FOLD_OVER: number
+export const FOLD_KEEP: number
+
+export class TaskTree {
+  constructor(options?: { clock?: () => number })
+  log: string | null
+  seq: number | null
+  stale: boolean
+  readonly root: Node | undefined
+  apply(batch: Batch): ApplyOutcome
+  get(path: Path): Node | undefined
+  childrenOf(node: Node): Node[]
+  each(node?: Node): Generator<Node>
+  rows(node?: Node, options?: { foldOver?: number; keep?: number }): Generator<Node | Fold>
+  complete(node: Node): boolean
+  fraction(node: Node): number
+  percentOf(node: Node): number
+  now(): number
+  /** The LocalTasks this whole tree mirrors, see followLocal */
+  local: import("./local_tasks.js").LocalTasks | null
+  graft(path: Path, local: import("./local_tasks.js").LocalTasks): () => void
+  cancelLocal(path: Path, reason?: string): void
+}
+
+export interface Following {
+  readonly tree: TaskTree
+  close(): void
+}
+
+export interface FeedOptions {
+  schedule?: Schedule
+  clock?: () => number
+  /** A batch to start from - the snapshot a page was rendered with */
+  initial?: Batch
+}
+
+export type OnChange = (tree: TaskTree, changes: Changes) => void
+
+export function batchFeed(onChange: OnChange, options?: FeedOptions): Following & { push(batch: Batch): ApplyOutcome }
+export function followEventSourceAt(url: string, onChange: OnChange, options?: FeedOptions & { onUnreachable?: () => void; unreachableAfter?: number }): Following
+/** `poll` and `wait` are in seconds */
+export function followPollingAt(url: string, onChange: OnChange, options?: FeedOptions & { poll?: number; wait?: number }): Following
+/** Draws tasks that run in this browser on their own, with no server tree around them */
+export function followLocal(local: import("./local_tasks.js").LocalTasks, onChange: OnChange, options?: FeedOptions): Following
+export function followProgress(progress: Progress, onChange: OnChange, options?: FeedOptions & { transport?: "auto" | "sse" | "poll"; poll?: number; wait?: number; unreachableAfter?: number }): Following
+export function requestCancel(url: string, path: Path, options?: { token?: string }): Promise<Response>
+export function humanBytes(n: number): string