Files
pipelines/web/src/pipelines.js
T

504 lines
19 KiB
JavaScript

// Pure pipeline-list/detail logic for the web client. Deliberately DOM-free:
// every helper here is a plain function a `node --test` can exercise without a
// browser, exactly like `client.js`. The DOM wiring lives in `app.js`.
//
// The wording and behaviour mirror the Android app one-for-one — the same
// singular/plural spelling, the same status vocabulary, the same comparator
// tie-breaks and the same empty-state sentences — because the web client's goal
// is feature parity, not a re-invention:
// ui/Format.kt, ui/screens/ListSort.kt, ui/screens/ListFilter.kt,
// ui/screens/PipelineLastRun.kt, ui/screens/PipelineDetailScreen.kt,
// ui/components/RunStatus.kt.
// ---------------------------------------------------------------------------
// Timestamps and durations (ui/Format.kt)
// ---------------------------------------------------------------------------
import { pipelineScheduleState, matchesScheduleState } from "./scheduleOrigin.js";
/**
* Parses an RFC3339 timestamp to epoch millis, or null when blank or
* unparseable. The single parser every time-reading helper shares, so a bad
* timestamp is handled the same way everywhere.
*/
export function parseInstant(text) {
if (typeof text !== "string" || text.trim() === "") return null;
const ms = Date.parse(text);
return Number.isNaN(ms) ? null : ms;
}
/**
* An RFC3339 timestamp as the app's one human, local rendering (`d MMM HH:mm`,
* e.g. `17 Oct 21:26`), or null when blank/unparseable so the caller omits the
* value rather than printing a blank. The day/month/hour/minute parts are
* assembled from `Intl.DateTimeFormat.formatToParts`, so no locale's list comma
* leaks into the string and the shape is the same everywhere. `timeZone` is
* accepted for deterministic tests; `locale` defaults to a fixed English so the
* month abbreviation matches the app's `d MMM` wording rather than drifting with
* the host locale.
*/
export function formatLocalTimestamp(instant, options = {}) {
const ms = parseInstant(instant);
if (ms === null) return null;
const { timeZone, locale = "en-GB" } = options;
const parts = new Intl.DateTimeFormat(locale, {
day: "numeric",
month: "short",
hour: "2-digit",
minute: "2-digit",
hourCycle: "h23",
...(timeZone ? { timeZone } : {}),
}).formatToParts(new Date(ms));
const get = (type) => parts.find((part) => part.type === type)?.value ?? "";
return `${get("day")} ${get("month")} ${get("hour")}:${get("minute")}`;
}
/**
* Human duration for a whole number of seconds: `45s`, `2m 5s`, `1h 2m`. The
* single duration rule every surface shares. A negative total renders as `0s`
* so a clamped value never prints a negative.
*/
export function formatDuration(totalSeconds) {
const seconds = Math.max(0, Math.trunc(totalSeconds));
if (seconds < 60) return `${seconds}s`;
if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`;
}
/**
* Non-negative whole seconds between two RFC3339 timestamps, or null when either
* is blank/unparseable or the end precedes the start.
*/
export function durationSeconds(start, end) {
const from = parseInstant(start);
const to = parseInstant(end);
if (from === null || to === null) return null;
const seconds = Math.floor((to - from) / 1000);
return seconds >= 0 ? seconds : null;
}
/**
* Non-negative whole seconds from a `start` timestamp to `nowMillis`, or null
* when `start` is blank/unparseable. Clamps a future/unparseable elapsed to 0 so
* a live timer never prints a negative.
*/
export function secondsSince(start, nowMillis) {
const from = parseInstant(start);
if (from === null) return null;
return Math.max(0, Math.floor((nowMillis - from) / 1000));
}
/**
* The time a run has taken so far: while it is still executing, its live elapsed
* from its start to `nowMs`; once finished, its stored total duration. Null when
* the needed timestamps are unusable, so the caller omits the value.
*/
export function runDurationText(run, nowMs) {
if (run && run.executing) {
const elapsed = secondsSince(run.created_at, nowMs);
return elapsed === null ? null : formatDuration(elapsed);
}
const total = durationSeconds(run?.created_at, run?.finished_at);
return total === null ? null : formatDuration(total);
}
/**
* A compact "how long ago" for a run's start: `just now` under a minute, then
* `Nm ago`/`Nh ago`/`Nd ago`. Null when the timestamp is blank/unparseable so
* the caller omits the fragment instead of printing a blank. A future start
* (clock skew) reads as `just now`, never a negative age.
*/
export function formatRanAgo(createdAt, nowMs) {
const start = parseInstant(createdAt);
if (start === null) return null;
const seconds = Math.max(0, Math.floor((nowMs - start) / 1000));
if (seconds < 60) return "just now";
if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`;
if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`;
return `${Math.floor(seconds / 86400)}d ago`;
}
/**
* A stage count in the app's one singular/plural spelling (`1 stage` /
* `n stages`), shared by the list and the detail so a single-stage pipeline
* never reads "1 stages".
*/
export function stageCountText(count) {
const n = Number(count) || 0;
return `${n} ${n === 1 ? "stage" : "stages"}`;
}
// ---------------------------------------------------------------------------
// Run states (ui/components/RunStatus.kt)
// ---------------------------------------------------------------------------
const RUN_STATE_ALIASES = {
running: "running",
queued: "queued",
waiting: "waiting",
active: "active",
succeeded: "succeeded",
success: "succeeded",
completed: "succeeded",
done: "succeeded",
failed: "failed",
error: "failed",
canceled: "canceled",
cancelled: "canceled",
interrupted: "interrupted",
blocked: "blocked",
skipped: "skipped",
};
/**
* Maps a server status or outcome word to the app's run-state word, accepting
* the server's own vocabulary only. A blank or unrecognised value falls back to
* `unknown` so a bad value never crashes the UI.
*/
export function runStateOf(status) {
const key = String(status ?? "").trim().toLowerCase();
return RUN_STATE_ALIASES[key] ?? "unknown";
}
// ---------------------------------------------------------------------------
// Last-run join and badge (ui/screens/PipelineLastRun.kt)
// ---------------------------------------------------------------------------
/** Shown for a pipeline that has recorded no run. */
export const NO_RUNS_RECORDED = "no runs recorded";
/**
* Timestamps decide recency; the higher run id breaks an exact tie (or a bad
* timestamp). The one recency rule, shared by the per-pipeline last-run join
* and the "most recent run" ordering.
*/
export function isMoreRecent(candidate, current) {
const a = parseInstant(candidate.created_at);
const b = parseInstant(current.created_at);
if (a !== null && b !== null && a !== b) return a > b;
return candidate.id > current.id;
}
/**
* Joins the whole run history onto pipelines by pipeline id: the most recent
* run per pipeline. The input order never matters — recency is decided from the
* timestamps, with the higher run id breaking an exact tie — so a pipeline with
* no runs is simply absent from the result (the caller renders
* [NO_RUNS_RECORDED] for it).
*/
export function latestRunByPipeline(runs) {
const latest = new Map();
for (const run of runs ?? []) {
const current = latest.get(run.pipeline_id);
if (current === undefined || isMoreRecent(run, current)) latest.set(run.pipeline_id, run);
}
return latest;
}
/** The display facts one pipeline row shows for `run`, anchored to `nowMs`. */
export function runBadge(run, nowMs) {
return {
runId: run.id,
state: runStateOf(run.status),
ranAgo: formatRanAgo(run.created_at, nowMs),
duration: runDurationText(run, nowMs),
};
}
/**
* The last-run secondary line, e.g. `2h ago · 1m 5s · run 42`. Missing
* fragments (an unparseable start, a run still executing) are omitted so no
* blank separator is ever printed; the run id is always present.
*/
export function runBadgeMetaLine(badge) {
const fragments = [badge.ranAgo, badge.duration, `run ${badge.runId}`];
return fragments.filter((fragment) => fragment != null && fragment !== "").join(" · ");
}
// ---------------------------------------------------------------------------
// Sorting (ui/screens/ListSort.kt)
// ---------------------------------------------------------------------------
/** The pipeline-list orderings offered by the sort control; Server order is the default. */
export const PIPELINE_SORTS = [
{ key: "server_order", label: "Server order" },
{ key: "name_asc", label: "Name A\u2013Z" },
{ key: "name_desc", label: "Name Z\u2013A" },
{ key: "recent_run", label: "Most recent run" },
{ key: "fewest_stages", label: "Fewest stages" },
{ key: "most_stages", label: "Most stages" },
];
/** Case-insensitive string comparison, matching String.CASE_INSENSITIVE_ORDER for ASCII. */
function compareInsensitive(a, b) {
const x = String(a ?? "").toUpperCase();
const y = String(b ?? "").toUpperCase();
if (x < y) return -1;
if (x > y) return 1;
return 0;
}
/** Plain (case-sensitive) string comparison for the comparator's second key. */
function compareSensitive(a, b) {
const x = String(a ?? "");
const y = String(b ?? "");
if (x < y) return -1;
if (x > y) return 1;
return 0;
}
/**
* The pure pipeline comparator for `sort`. Every case ends in an explicit
* tie-break (`id` is unique), so pipelines that compare equal on the primary
* key always order the same way rather than depending on the input order.
*
* `latestRuns` maps a pipeline id to that pipeline's most recent run (see
* [latestRunByPipeline]); only "Most recent run" uses it but it is passed in
* once so the fold is never repeated per comparison.
*/
export function pipelineComparator(sort, latestRuns = new Map()) {
const runFor = (pipeline) =>
latestRuns instanceof Map ? latestRuns.get(pipeline.id) : latestRuns[pipeline.id];
switch (sort) {
case "name_asc":
return (a, b) =>
compareInsensitive(a.name, b.name) ||
compareSensitive(a.name, b.name) ||
a.id - b.id;
case "name_desc":
return (a, b) =>
-compareInsensitive(a.name, b.name) ||
compareSensitive(a.name, b.name) ||
a.id - b.id;
case "recent_run":
return (a, b) => {
const ra = runFor(a);
const rb = runFor(b);
const noRunA = ra == null ? 1 : 0;
const noRunB = rb == null ? 1 : 0;
if (noRunA !== noRunB) return noRunA - noRunB;
const ta = ra ? parseInstant(ra.created_at) : null;
const tb = rb ? parseInstant(rb.created_at) : null;
const na = ta == null ? -Infinity : ta;
const nb = tb == null ? -Infinity : tb;
if (na !== nb) return na > nb ? -1 : 1;
const ia = ra ? ra.id : -Infinity;
const ib = rb ? rb.id : -Infinity;
if (ia !== ib) return ia > ib ? -1 : 1;
return a.id - b.id;
};
case "fewest_stages":
return (a, b) =>
(Number(a.stages) || 0) - (Number(b.stages) || 0) ||
compareInsensitive(a.name, b.name) ||
a.id - b.id;
case "most_stages":
return (a, b) =>
(Number(b.stages) || 0) - (Number(a.stages) || 0) ||
compareInsensitive(a.name, b.name) ||
a.id - b.id;
// Server order (and any unknown stored value): the identity comparator, so
// a stable sort preserves the server's own ordering exactly.
case "server_order":
default:
return () => 0;
}
}
/** Orders `pipelines` by `sort` without mutating the input, folding the run history once. */
export function sortPipelines(pipelines, sort, latestRuns = new Map()) {
return [...(pipelines ?? [])].sort(pipelineComparator(sort, latestRuns));
}
// ---------------------------------------------------------------------------
// Filtering (ui/screens/ListFilter.kt)
// ---------------------------------------------------------------------------
/**
* The statuses a filter can select: the server's own run vocabulary. The
* app-only `active` bucket, the stage-outcome words (`blocked`/`skipped`) and
* the `unknown` fallback are deliberately not offered, so a status filter
* always names a real run state.
*/
export const RUN_STATUS_FILTERS = [
"queued",
"running",
"waiting",
"succeeded",
"failed",
"canceled",
"interrupted",
];
/** The has/no-runs narrowing offered by the filter's Runs section. */
export const RUN_PRESENCES = [
{ key: "any", label: "Any" },
{ key: "has_runs", label: "Has runs" },
{ key: "no_runs", label: "No runs" },
];
export const PIPELINE_SCHEDULE_FILTERS = [
{ key: "any", label: "Any schedule" },
{ key: "scheduled", label: "Has schedules" },
{ key: "unscheduled", label: "No schedules" },
];
/** The default, no-narrowing pipeline filter. */
export const EMPTY_PIPELINE_FILTERS = { presence: "any", lastRunStatuses: [], name: "", scheduled: "any" };
/** Whether a run-history facet (presence or last-run status) is set. */
export function hasRunFacets(filters) {
return (filters?.presence ?? "any") !== "any" || (filters?.lastRunStatuses ?? []).length > 0;
}
/** True when the filters actually narrow anything. */
export function pipelineFiltersActive(filters) {
return hasRunFacets(filters) || String(filters?.name ?? "").trim() !== "" || ["scheduled", "unscheduled"].includes(filters?.scheduled);
}
/** The number of active facets, used for the control's badge. */
export function pipelineFilterCount(filters) {
return (
((filters?.presence ?? "any") !== "any" ? 1 : 0) +
((filters?.lastRunStatuses ?? []).length > 0 ? 1 : 0) +
(String(filters?.name ?? "").trim() !== "" ? 1 : 0) +
(["scheduled", "unscheduled"].includes(filters?.scheduled) ? 1 : 0)
);
}
/** True when `name` is blank, or when `pipelineName` contains it, ignoring case. */
export function pipelineMatchesName(name, pipelineName) {
const needle = String(name ?? "").trim();
return needle === "" || String(pipelineName ?? "").toLowerCase().includes(needle.toLowerCase());
}
/** True when `presence` is satisfied by whether the pipeline has a run. */
export function pipelineMatchesPresence(presence, hasRun) {
switch (presence) {
case "has_runs":
return hasRun;
case "no_runs":
return !hasRun;
case "any":
default:
return true;
}
}
/**
* True when `latestRun`'s status is in `statuses`; an empty set means "any
* status" and a pipeline with no run never matches a selected status, so the
* filter genuinely narrows.
*/
export function pipelineMatchesLastRunStatus(latestRun, statuses) {
const wanted = statuses ?? [];
if (wanted.length === 0) return true;
return latestRun != null && wanted.includes(runStateOf(latestRun.status));
}
/**
* Narrows `pipelines` by `filters`: the name narrowing and both run facets
* combined with AND. The name facet never depends on the run history, so it
* applies immediately; the run facets do, so while that history is still
* unknown (`runsKnown == false`) they are skipped rather than briefly hiding
* every pipeline.
*/
export function filterPipelines(pipelines, filters, latestRuns = new Map(), runsKnown = true) {
const all = pipelines ?? [];
if (!pipelineFiltersActive(filters)) return all;
const runFacets = hasRunFacets(filters);
const getRun = (pipeline) =>
latestRuns instanceof Map ? latestRuns.get(pipeline.id) : latestRuns[pipeline.id];
return all.filter((pipeline) => {
if (!pipelineMatchesName(filters?.name, pipeline.name)) return false;
if (!matchesScheduleState(pipelineScheduleState(pipeline), filters?.scheduled)) return false;
if (runFacets && runsKnown) {
const latestRun = getRun(pipeline) ?? null;
if (!pipelineMatchesPresence(filters.presence, latestRun != null)) return false;
if (!pipelineMatchesLastRunStatus(latestRun, filters.lastRunStatuses)) return false;
}
return true;
});
}
/**
* The empty-state sentence for the pipeline list plus its optional reset action.
* Returns null when there is something to show. `Clear filters` is only offered
* when pipelines exist (nothing exists to reveal otherwise).
*/
export function pipelineListEmptyState(all, items, filters) {
if ((items ?? []).length > 0) return null;
const every = all ?? [];
if (every.length === 0) {
return { message: "No pipelines are defined on this server.", clearAction: null };
}
const name = String(filters?.name ?? "");
const message =
name.trim() !== "" && !hasRunFacets(filters) && !["scheduled", "unscheduled"].includes(filters?.scheduled)
? `No pipelines match "${name}".`
: "No pipelines match the current filters.";
return { message, clearAction: "Clear filters" };
}
// ---------------------------------------------------------------------------
// List row and detail text
// ---------------------------------------------------------------------------
/** The pipeline row's secondary line: `id {id} · v{version} · {N stages}`. */
export function pipelineSubtitle(pipeline) {
const stages = pipeline.stages ?? pipeline.graph?.stages?.length ?? 0;
return `id ${pipeline.id} · v${pipeline.version} · ${stageCountText(stages)}`;
}
/** The row's `updated …` line, or null when the timestamp is unparseable. */
export function pipelineUpdatedLine(pipeline) {
const formatted = formatLocalTimestamp(pipeline.updated_at);
return formatted ? `updated ${formatted}` : null;
}
/** The pipeline-detail tabs, Summary first (the version list lives inside it). */
export const PIPELINE_DETAIL_TABS = [
{ key: "summary", label: "Summary" },
{ key: "graph", label: "Graph" },
{ key: "source", label: "Source" },
];
/**
* The Summary tab's key/value rows, in the app's order: Content hash
* (monospace), Latest version (`v{n}` or blank — never a dash), Version created,
* Pipeline created, Pipeline updated.
*/
export function summaryFields(detail) {
const latest = Number(detail?.latest_version) || 0;
return [
{ key: "Content hash", value: detail?.content_hash ?? "", monospace: true },
{ key: "Latest version", value: latest > 0 ? `v${latest}` : "" },
{ key: "Version created", value: formatLocalTimestamp(detail?.version_created_at) ?? "" },
{ key: "Pipeline created", value: formatLocalTimestamp(detail?.created_at) ?? "" },
{ key: "Pipeline updated", value: formatLocalTimestamp(detail?.updated_at) ?? "" },
];
}
/** One Version row: `v{n}` plus its stage count and (parseable) created time. */
export function versionRow(version) {
return {
versionLabel: `v${version?.version}`,
stagesText: stageCountText(version?.stages),
createdText: formatLocalTimestamp(version?.created_at),
};
}
/**
* The Graph tab's guidance note, adapted for a browser: mouse-wheel zoom and
* click replace the app's pinch and tap. The graph itself is the separate P6
* item.
*/
export const GRAPH_NOTE =
"Mouse wheel to zoom, drag to pan, click a stage for details. " +
"Edges are labelled with their outcome; error* is the implicit fallback.";
/** The guidance note string (a function so callers need no constant import). */
export function graphNote() {
return GRAPH_NOTE;
}