Files
pipelines/web/src/routes.js
T

296 lines
11 KiB
JavaScript

// The page's URL route model (L6). Pure and DOM-free: the parser is total (a
// malformed or unknown location resolves to the default Pipelines list), and the
// serialiser is its inverse for every route the page can produce.
//
// The Android app's `pipelines://run/<id>` deep link becomes a real page route,
// and every destination the app has becomes a URL:
//
// /pipelines Pipelines list
// /pipelines/:id pipeline detail, latest version
// /pipelines/:id/:version pipeline detail at a version (0 = latest)
// /pipelines/:id[/:version]/stage/:key the definition pane's stage
// /runs Runs list
// /runs/:id run detail (optional ?action=decide)
// /runs/:id/stage/:key[?visit=N] one visit's stage pane
// /chat Chat list
// /chat/:id one chat session
// /templates template gallery
// /templates/:key template detail
// /settings Settings
// /settings/templates[/:key] aliases for the two template routes
//
// Where a section sits inside a detail (Summary/Graph/Source, run tabs) is
// in-place state, not a route: only the two stage panes are deep-linkable. Search
// is query state owned by the search panel and is never part of a route; unknown
// query parameters are ignored. `/templates` and `/templates/:key` are the
// canonical forms the serialiser emits; the `/settings/...` aliases still parse
// and round-trip to the same route.
/** The destination an unknown or malformed location opens. */
export const DEFAULT_ROUTE = Object.freeze({ kind: "pipelines" });
const ID_PATTERN = /^[0-9]+$/;
/** Decode one path segment, or null when the percent escapes are malformed. */
function decodeSegment(segment) {
try {
return decodeURIComponent(segment);
} catch {
return null;
}
}
/** A positive safe integer id, or null. Mirrors runLinkFromDeepLink's id > 0. */
function parseId(value) {
if (!ID_PATTERN.test(value)) return null;
const id = Number(value);
return Number.isSafeInteger(id) && id > 0 ? id : null;
}
/** A non-negative safe integer (a pipeline version; 0 means latest), or null. */
/** A chat session id segment: nonempty, bounded, URL-safe. */
function parseChatId(value) {
const id = String(value ?? "");
return id !== "" && id.length <= 200 && /^[A-Za-z0-9_-]+$/.test(id) ? id : null;
}
function parseVersion(value) {
if (!ID_PATTERN.test(value)) return null;
const version = Number(value);
return Number.isSafeInteger(version) ? version : null;
}
/** The `action` query value verbatim, or null; only `decide` has an effect. */
function parseAction(params) {
if (!params) return null;
const action = params.get("action");
return action != null && action !== "" ? action : null;
}
/**
* The zero-based visit index from `?visit=`, or null. A negative, non-integer or
* absent value drops the query while keeping the stage route, exactly as the
* Android extra is optional.
*/
function parseVisit(params) {
if (!params) return null;
const raw = params.get("visit");
if (raw == null || raw === "") return null;
return parseVersion(raw);
}
function parseParams(search) {
if (!search) return null;
const text = String(search).replace(/^\?/, "");
if (!text) return null;
try {
return new URLSearchParams(text);
} catch {
return null;
}
}
/**
* Parse a location-style pathname (and optional search) into a route. Total:
* anything unrecognised — an unknown path, a malformed percent escape, a zero or
* negative run id, a non-numeric version — returns DEFAULT_ROUTE and never
* throws. Unknown query parameters are ignored; `visit` is dropped when invalid.
*/
export function parseRoute(pathname, search = "") {
let raw = pathname == null ? "" : String(pathname);
let query = search == null ? "" : String(search);
// A full URL is accepted too (the smoke and a pasted link use one); its own
// path and query stand in for the arguments.
if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
try {
const url = new URL(raw);
if (!query) query = url.search;
raw = url.pathname;
} catch {
return DEFAULT_ROUTE;
}
}
const hash = raw.indexOf("#");
if (hash !== -1) raw = raw.slice(0, hash);
const mark = raw.indexOf("?");
if (mark !== -1) {
if (!query) query = raw.slice(mark);
raw = raw.slice(0, mark);
}
if (!query && typeof search === "string") query = search;
// Normalise trailing slashes: `/runs/` is `/runs`.
const trimmed = raw.replace(/\/+$/, "");
const segments = trimmed.split("/").filter((segment, index) => index > 0 || segment !== "");
if (trimmed === "" || trimmed === "/") return { ...DEFAULT_ROUTE };
const decoded = [];
for (const segment of segments) {
const value = decodeSegment(segment);
if (value == null || value === "") return { ...DEFAULT_ROUTE };
decoded.push(value);
}
const params = parseParams(query);
const [head, second, third, fourth, fifth, ...rest] = decoded;
if (rest.length) return { ...DEFAULT_ROUTE };
if (head === "pipelines" && second == null) return { kind: "pipelines" };
if (head === "runs" && second == null) {
const pipelineId = parseId(params?.get("pipeline") ?? "");
return pipelineId == null ? { kind: "runs" } : { kind: "runs", pipelineId };
}
if (head === "chat") {
if (second == null) return { kind: "chat" };
if (third == null) {
const id = parseChatId(second);
return id == null ? { ...DEFAULT_ROUTE } : { kind: "chatSession", id };
}
return { ...DEFAULT_ROUTE };
}
if (head === "settings" && second == null) return { kind: "settings" };
if (head === "templates") {
if (second == null) return { kind: "templates" };
if (third == null) return { kind: "template", key: second };
return { ...DEFAULT_ROUTE };
}
if (head === "settings" && second === "templates") {
if (third == null) return { kind: "templates" };
if (fourth == null) return { kind: "template", key: third };
return { ...DEFAULT_ROUTE };
}
if (head === "pipelines") {
const id = parseId(second);
if (id == null) return { ...DEFAULT_ROUTE };
if (third == null) return { kind: "pipeline", id, version: 0 };
if (third === "stage" && fourth != null && fifth == null) {
return { kind: "pipelineStage", id, version: 0, stageKey: fourth };
}
const version = parseVersion(third);
if (version == null) return { ...DEFAULT_ROUTE };
if (fourth == null) return { kind: "pipeline", id, version };
if (fourth === "stage" && fifth != null) {
return { kind: "pipelineStage", id, version, stageKey: fifth };
}
return { ...DEFAULT_ROUTE };
}
if (head === "runs") {
const id = parseId(second);
if (id == null) return { ...DEFAULT_ROUTE };
if (third == null) {
const action = parseAction(params);
return action == null ? { kind: "run", id } : { kind: "run", id, action };
}
if (third === "stage" && fourth != null && fifth == null) {
const visit = parseVisit(params);
return visit == null
? { kind: "runStage", id, stageKey: fourth }
: { kind: "runStage", id, stageKey: fourth, visit };
}
return { ...DEFAULT_ROUTE };
}
return { ...DEFAULT_ROUTE };
}
function encode(value) {
return encodeURIComponent(String(value));
}
/**
* An id the parser will accept back (a positive safe integer), or null. A
* numeric string is accepted like the parser's own digit-only form.
*/
function serialId(value) {
if (typeof value === "number") {
return Number.isSafeInteger(value) && value > 0 ? value : null;
}
if (typeof value === "string" && ID_PATTERN.test(value)) {
const id = Number(value);
return Number.isSafeInteger(id) && id > 0 ? id : null;
}
return null;
}
/**
* A version the parser will accept back (a non-negative safe integer), or null
* when the value cannot describe one; the caller then emits the latest form so
* the URL still parses to a canonical route.
*/
function serialVersion(value) {
if (value == null) return 0;
if (typeof value === "number") {
return Number.isSafeInteger(value) && value >= 0 ? value : null;
}
if (typeof value === "string" && ID_PATTERN.test(value)) {
const version = Number(value);
return Number.isSafeInteger(version) ? version : null;
}
return null;
}
/**
* Serialise a route to a path + query. Total: an unrecognised object serialises
* to the default Pipelines route rather than throwing. Version 0/absent is
* omitted (it means latest), an absent visit is omitted, and `action` is emitted
* only when present.
*/
export function serializeRoute(route) {
const r = route ?? DEFAULT_ROUTE;
switch (r.kind) {
case "pipelines":
return "/pipelines";
case "runs":
return parseId(String(r.pipelineId ?? "")) == null ? "/runs" : `/runs?pipeline=${r.pipelineId}`;
case "chat":
return "/chat";
case "chatSession": {
const id = parseChatId(r.id);
return id == null ? "/chat" : `/chat/${encode(id)}`;
}
case "settings":
return "/settings";
case "templates":
return "/templates";
case "template":
return typeof r.key === "string" && r.key ? `/templates/${encode(r.key)}` : "/templates";
case "pipeline": {
const id = serialId(r.id);
if (id == null) return "/pipelines";
const version = serialVersion(r.version) ?? 0;
return version > 0 ? `/pipelines/${id}/${version}` : `/pipelines/${id}`;
}
case "pipelineStage": {
const id = serialId(r.id);
if (id == null || typeof r.stageKey !== "string" || !r.stageKey) return "/pipelines";
const version = serialVersion(r.version) ?? 0;
const base = version > 0 ? `/pipelines/${id}/${version}` : `/pipelines/${id}`;
return `${base}/stage/${encode(r.stageKey)}`;
}
case "run": {
const id = serialId(r.id);
if (id == null) return "/runs";
const base = `/runs/${id}`;
return r.action ? `${base}?${new URLSearchParams({ action: r.action }).toString()}` : base;
}
case "runStage": {
const id = serialId(r.id);
if (id == null || typeof r.stageKey !== "string" || !r.stageKey) return "/runs";
const base = `/runs/${id}/stage/${encode(r.stageKey)}`;
// A valid visit is a non-negative integer; anything else is omitted.
const visit = Number.isSafeInteger(r.visit) && r.visit >= 0 ? r.visit : null;
return visit == null ? base : `${base}?visit=${visit}`;
}
default:
return "/pipelines";
}
}
/** Two routes are the same when their canonical serialisations agree. */
export function sameRoute(a, b) {
return serializeRoute(a) === serializeRoute(b);
}