rvlib-shipkit 1.1.1 → 1.3.0

package/src/home/pm.ts

@@ -0,0 +1,174 @@
+// pm, the machine's process manager: it keeps the daemon and the web running
+// (supervise.ts: detached, pid records, crash restarts with backoff, adoption)
+// and owns the machine's global processes (resources.ts). Its api answers on
+// its own port, and the web proxies /api/pm/* to it, so the page switches a
+// process and restarts a child through the one origin it knows.
+//
+// the one constraint a reader breaks first: pm never takes a child down with
+// it. A reload of pm, or pm killed, leaves both running, and the next pm
+// adopts them from their pid records. Only a stop asked of pm stops them.
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { LIB_VERSION } from '../core/lib-version.ts'
+import { iconImageType } from '../shipkit-files.ts'
+import { sameOrigin } from '../serve/same-origin.ts'
+import { childLog, childPid, daemonPort, homePort, pmLog, pmPort } from './home-paths.ts'
+import type { Resources, ResourceView } from './resources.ts'
+import { capLog, Proc, realDeps, tailLines, type ProcView, type SuperviseDeps } from './supervise.ts'
+
+export type Role = 'daemon' | 'web'
+export const ROLES: Role[] = ['daemon', 'web']
+
+/** how often pm looks at its children and the global processes */
+export const PM_TICK_MS = 2_000
+
+export type ChildView = ProcView & { tail: string[] }
+
+/** where pm, the daemon and the web listen */
+export type CorePorts = { pm: number; daemon: number; web: number }
+
+/** how many log lines each of shipkit's own processes hands the page */
+const CORE_TAIL = 20
+
+export type PmAnswer = {
+    pm: 'shipkit-pm'
+    pid: number
+    /** epoch ms this pm started; absent from a pm older than the field */
+    since?: number
+    version: string
+    /** where pm and its children listen; absent from a pm older than the field */
+    ports?: CorePorts
+    /** the last lines of pm's own log; absent from a pm older than the field */
+    tail?: string[]
+    children: ChildView[]
+    resources: ResourceView[]
+    /** the `.shipkit.ts` files that would not load, as pm last read them */
+    unitErrors: string[]
+}
+
+export type PmDeps = {
+    dir: string
+    /** the house repo: where the children run */
+    root: string
+    /** the port pm serves on (default: SHIPKIT_PM_PORT, else 4797) */
+    port?: number
+    /** the command that runs one role, e.g. [bun, cli.ts, 'daemon'] */
+    cmd: (role: Role) => string[]
+    /** true once the role serves */
+    probe: (role: Role) => Promise<boolean>
+    resources: Resources
+    deps?: SuperviseDeps
+    /** runs a stop or restart of the web once its answer is out: the web
+     *  proxies that very request (default: 200 ms later) */
+    later?: (f: () => void) => void
+}
+
+const WEB_ANSWER_MS = 200
+
+export class Pm {
+    readonly children: Map<Role, Proc>
+    private readonly startedAt = Date.now()
+
+    constructor(private d: PmDeps) {
+        this.children = new Map(ROLES.map((role) => [role, new Proc({
+            id: role,
+            cmd: d.cmd(role),
+            cwd: d.root,
+            log: childLog(d.dir, role),
+            pidKey: childPid(d.dir, role),
+            probe: () => d.probe(role),
+            // a crash loop while its code is being edited heals itself
+            neverGiveUp: true,
+        }, d.deps ?? realDeps)]))
+    }
+
+    get resources(): Resources {
+        return this.d.resources
+    }
+
+    /** every child up: adopted from its pid record, else started, unless
+     *  something else already answers its port */
+    async boot(): Promise<void> {
+        await Promise.all([...this.children.values()].map((p) => p.ensure()))
+    }
+
+    async tick(): Promise<void> {
+        await Promise.all([...[...this.children.values()].map((p) => p.tick()), this.d.resources.tick()])
+        for (const role of ROLES) capLog(childLog(this.d.dir, role))
+    }
+
+    /** stop both children and wait until they are gone, SIGKILL included */
+    async stopAll(o: { waitMs?: number; stepMs?: number } = {}): Promise<void> {
+        for (const p of this.children.values()) p.stop()
+        const until = Date.now() + (o.waitMs ?? 12_000)
+        while (Date.now() < until && [...this.children.values()].some((p) => p.status === 'stopping')) {
+            await Bun.sleep(o.stepMs ?? 200)
+            await Promise.all([...this.children.values()].map((p) => p.tick()))
+        }
+    }
+
+    answer(): PmAnswer {
+        // up: since its pid started, so a pm reload never resets its uptime
+        const children = [...this.children.values()].map((p) => {
+            const v = p.view()
+            return { ...v, since: (v.status === 'up' ? p.startedAt() : null) ?? v.since, tail: tailLines(p.spec.log, CORE_TAIL) }
+        })
+        const ports = { pm: this.d.port ?? pmPort(), daemon: daemonPort(), web: homePort() }
+        return { pm: 'shipkit-pm', pid: process.pid, since: this.startedAt, version: LIB_VERSION, ports, tail: tailLines(pmLog(this.d.dir), CORE_TAIL), children, resources: this.d.resources.views(), unitErrors: this.d.resources.errors }
+    }
+
+    /** the image a global process declares as its icon, and no other file */
+    private icon(id: string): Response {
+        const d = this.d.resources.get(id)?.decl
+        const type = d?.icon == null ? null : iconImageType(d.icon)
+        if (d?.icon == null || type == null) return new Response(`no image icon for '${id}'`, { status: 404 })
+        const file = join(d.root, d.icon)
+        if (!existsSync(file)) return new Response(`${d.repo}/${d.icon} does not exist: the icon of '${id}'`, { status: 404 })
+        return new Response(Bun.file(file), { headers: { 'content-type': type, 'cache-control': 'no-cache' } })
+    }
+
+    async handle(req: Request): Promise<Response> {
+        const path = new URL(req.url).pathname
+        if (!sameOrigin(req)) return new Response('refused: a request that changes something must come from the home page', { status: 403 })
+        if (path === '/api/pm/status.json') return Response.json(this.answer())
+        if (path.startsWith('/api/pm/icon/') && req.method === 'GET') return this.icon(decodeURIComponent(path.slice('/api/pm/icon/'.length)))
+        if (req.method !== 'POST') return new Response('not found', { status: 404 })
+        const b = (await req.json().catch(() => ({}))) as Record<string, unknown>
+        if (path === '/api/pm/child') {
+            const p = this.children.get(b.id as Role)
+            if (p == null) return new Response(`no child '${String(b.id)}': pm runs ${ROLES.join(' and ')}`, { status: 404 })
+            if (b.act === 'start') p.start()
+            else if (b.act === 'stop' || b.act === 'restart') {
+                const act = b.act === 'stop' ? () => p.stop() : () => p.restart()
+                if (b.id === 'web') (this.d.later ?? ((f) => { setTimeout(f, WEB_ANSWER_MS) }))(act)
+                else act()
+            } else return new Response('act must be start, stop or restart', { status: 400 })
+            return Response.json(p.view())
+        }
+        if (path === '/api/pm/resource') {
+            const r = this.d.resources.get(String(b.id))
+            if (r == null) return new Response(`no global process '${String(b.id)}': none of the house repos' .shipkit.ts files declares it`, { status: 404 })
+            const act = b.act ?? (b.on === true ? 'start' : b.on === false ? 'stop' : null)
+            // a bring-up or an action can take minutes: the page follows it on its poll
+            const report = (p: Promise<void>): void => { p.catch((e: Error) => { r.note = e.message }) }
+            if (act === 'start') report(r.set('up'))
+            else if (act === 'stop') report(r.set('down'))
+            else if (act === 'restart') report(r.restart())
+            else if (act === 'open' || act === 'app') {
+                if (r.decl.url == null) return new Response(`${r.decl.id} declares no url to open`, { status: 400 })
+                report(r.open(act === 'app' ? 'app' : 'browser'))
+            } else if (act === 'takeover') {
+                const v = r.takeOverView
+                if (v == null) return new Response(`${r.decl.id} does not run outside the supervisor: nothing to take over`, { status: 409 })
+                if (!v.ok) return new Response(`${r.decl.id}: ${v.why}`, { status: 400 })
+                report(r.takeOver())
+            } else if (act === 'action') {
+                if (!r.decl.actions.some((a) => a.id === b.action)) return new Response(`${r.decl.id} declares no action '${String(b.action)}'`, { status: 404 })
+                if (r.running != null) return new Response(`${r.decl.id} is already running its action '${r.running}'`, { status: 409 })
+                report(r.action(String(b.action)))
+            } else return new Response('act must be start, stop, restart, open, app, takeover or action', { status: 400 })
+            return Response.json(r.view())
+        }
+        return new Response('not found', { status: 404 })
+    }
+}

package/src/home/process-rows.ts

@@ -0,0 +1,205 @@
+// the processes as rows: shipkit's own first (pm, the daemon, the web: the
+// core group), then one group per declaring repo, one row per process, in the
+// order the page and `shipkit global-processes` both show.
+// The page's table and the command's text and json are all drawn from these
+// rows, so the two can never disagree. A row carries no clock: ages are words
+// computed at render time from `since`.
+import type { GlobalProcessDecl } from './global-units.ts'
+import type { CorePorts, PmAnswer } from './pm.ts'
+import type { ProcessIcon, ResourceView } from './resources.ts'
+import type { ProcStatus } from './supervise.ts'
+
+/** a status as pm reports it, or unknown while pm does not answer */
+export type RowStatus = ProcStatus | 'unknown'
+
+/** the dot a row wears: green up, red crashed, grey stopped or unknown, orange on its way */
+export type RowDot = 'up' | 'crashed' | 'down' | 'starting' | 'unknown'
+
+export type ProcessRow = {
+    id: string
+    label: string
+    repo: string
+    file: string
+    status: RowStatus
+    dot: RowDot
+    url: string | null
+    /** the url without its scheme, what the table shows dimmed */
+    host: string | null
+    pid: number | null
+    /** epoch ms its state counts from (up: its pid's start when it has one), null when pm never said */
+    since: number | null
+    note: string | null
+    description: string | null
+    where: string | null
+    /** the last line of its log, null when it has none */
+    lastLog: string | null
+    tail: string[]
+    canStop: boolean
+    /** the page offers restart: a global process pm runs and can stop, while
+     *  up; the daemon and the web always, through pm; never pm itself */
+    canRestart: boolean
+    /** one of shipkit's own: always on, no stop, no open */
+    core: boolean
+    /** the shipkit version it runs, when known (core rows only) */
+    version: string | null
+    takeOver: ResourceView['takeOver']
+    actions: { id: string; label: string }[]
+    running: string | null
+    icon: ProcessIcon | null
+}
+
+/** a repo's processes, or shipkit's own (`core`, always the first group) */
+export type ProcessGroup = { repo: string; core?: true; rows: ProcessRow[] }
+
+/** the core group's name */
+export const CORE_GROUP = 'shipkit'
+
+export const dotOf = (s: RowStatus): RowDot =>
+    s === 'up' ? 'up' : s === 'crashed' ? 'crashed' : s === 'starting' || s === 'stopping' ? 'starting' : s === 'down' ? 'down' : 'unknown'
+
+const hostOf = (url: string | null): string | null => (url == null ? null : url.replace(/^https?:\/\//, '').replace(/\/$/, ''))
+
+/** a process as pm serves it. A pm older than pid and since reads them as null */
+export function rowOf(r: ResourceView): ProcessRow {
+    return {
+        id: r.id,
+        label: r.label,
+        repo: r.repo,
+        file: r.file,
+        status: r.status,
+        dot: dotOf(r.status),
+        url: r.url,
+        host: hostOf(r.url),
+        pid: r.pid ?? null,
+        since: r.since ?? null,
+        note: r.note,
+        description: r.description,
+        where: r.where,
+        lastLog: r.tail.at(-1) ?? null,
+        tail: r.tail,
+        canStop: r.canStop,
+        canRestart: r.status === 'up' && r.canStop,
+        core: false,
+        version: null,
+        takeOver: r.takeOver,
+        actions: r.actions,
+        running: r.running,
+        icon: r.icon,
+    }
+}
+
+/** a declared process while pm does not answer: everything but its state */
+export function declaredRow(d: GlobalProcessDecl): ProcessRow {
+    return {
+        id: d.id,
+        label: d.label,
+        repo: d.repo,
+        file: d.file,
+        status: 'unknown',
+        dot: 'unknown',
+        url: d.url,
+        host: hostOf(d.url),
+        pid: null,
+        since: null,
+        note: null,
+        description: d.description,
+        where: d.where,
+        lastLog: null,
+        tail: [],
+        canStop: false,
+        canRestart: false,
+        core: false,
+        version: null,
+        takeOver: null,
+        actions: d.actions.map((a) => ({ id: a.id, label: a.label })),
+        running: null,
+        // an image is pm's to serve, and pm does not answer
+        icon: d.icon == null || /\.[a-z0-9]+$/i.test(d.icon) ? null : { text: d.icon },
+    }
+}
+
+/** one group per repo, in `order` (the project list), the repos it does not
+ *  list after it by name; a group keeps pm's order */
+export function groupRows(rows: ProcessRow[], order: string[]): ProcessGroup[] {
+    const by = new Map<string, ProcessRow[]>()
+    for (const r of rows) by.set(r.repo, [...(by.get(r.repo) ?? []), r])
+    const rank = (repo: string): number => {
+        const i = order.indexOf(repo)
+        return i < 0 ? order.length : i
+    }
+    return [...by.keys()]
+        .sort((a, b) => rank(a) - rank(b) || a.localeCompare(b))
+        .map((repo) => ({ repo, rows: by.get(repo)! }))
+}
+
+export const CORE_ABOUT = {
+    pm: 'the process manager, the LaunchAgent com.shipkit.pm: launchd starts it at login and again when it dies, so the page has no restart for it (from a terminal: launchctl kickstart -k gui/$(id -u)/com.shipkit.pm)',
+    daemon: 'loads every house repo hub in one process and serves their api, restarted through pm',
+    web: 'serves this page and passes every api request to the daemon, restarted through pm',
+} as const
+
+export type CoreOpts = {
+    /** the daemon's own version, asked of the daemon; null when it does not answer */
+    daemonVersion?: string | null
+    /** where each listens, when pm does not say (an older pm, or pm down) */
+    ports?: CorePorts | null
+}
+
+function coreRow(id: 'pm' | 'daemon' | 'web', o: { status: RowStatus; pid: number | null; since: number | null; note: string | null; tail: string[]; version: string | null; port: number | null; restart: boolean }): ProcessRow {
+    const url = o.port == null ? null : `http://127.0.0.1:${o.port}`
+    return {
+        id, label: id, repo: CORE_GROUP, file: '', status: o.status, dot: dotOf(o.status), url, host: hostOf(url), pid: o.pid, since: o.since, note: o.note,
+        description: CORE_ABOUT[id], where: null, lastLog: o.tail.at(-1) ?? null, tail: o.tail,
+        canStop: false, canRestart: o.restart, core: true, version: o.version, takeOver: null, actions: [], running: null, icon: null,
+    }
+}
+
+/** shipkit's own processes, one row each: pm as it answers (down when it does
+ *  not), then the daemon and the web as pm reports them (unknown without pm) */
+export function coreGroup(pm: PmAnswer | null, o: CoreOpts = {}): ProcessGroup {
+    const ports = pm?.ports ?? o.ports ?? null
+    const rows: ProcessRow[] = [pm == null
+        ? coreRow('pm', { status: 'down', pid: null, since: null, note: 'pm does not answer', tail: [], version: null, port: ports?.pm ?? null, restart: false })
+        : coreRow('pm', { status: 'up', pid: pm.pid, since: pm.since ?? null, note: null, tail: pm.tail ?? [], version: pm.version, port: ports?.pm ?? null, restart: false })]
+    for (const id of ['daemon', 'web'] as const) {
+        const c = pm?.children.find((x) => x.id === id)
+        const port = ports?.[id] ?? null
+        const version = id === 'daemon' ? (o.daemonVersion ?? null) : null
+        if (c == null) rows.push(coreRow(id, { status: 'unknown', pid: null, since: null, note: null, tail: [], version, port, restart: false }))
+        else {
+            const note = [c.note, c.restarts > 0 ? `${c.restarts} restart(s)` : null].filter((x) => x != null).join(', ')
+            rows.push(coreRow(id, { status: c.status, pid: c.pid, since: c.since, note: note === '' ? null : note, tail: c.tail, version, port, restart: true }))
+        }
+    }
+    return { repo: CORE_GROUP, core: true, rows }
+}
+
+/** what the page's table holds, from pm's answer: the core group, then the
+ *  global processes by repo */
+export const processGroups = (pm: PmAnswer | null, order: string[], o: CoreOpts = {}): ProcessGroup[] =>
+    [coreGroup(pm, o), ...groupRows((pm?.resources ?? []).map(rowOf), order)]
+
+/** the declared icon, else the repo's own, else none */
+export const processIcon = (r: { icon: ProcessIcon | null }, repoIcon: string | null): ProcessIcon | null =>
+    r.icon ?? (repoIcon == null ? null : { src: repoIcon })
+
+/** a span in its largest whole unit: 45s, 3m, 2h, 4d */
+export function spanWords(ms: number): string {
+    const s = Math.max(0, Math.floor(ms / 1000))
+    if (s < 60) return `${s}s`
+    if (s < 3600) return `${Math.floor(s / 60)}m`
+    if (s < 86400) return `${Math.floor(s / 3600)}h`
+    return `${Math.floor(s / 86400)}d`
+}
+
+/** the state in words: `up 2h`, `crashed 3m ago`, `stopped`, `starting` */
+export function stateWords(r: Pick<ProcessRow, 'status' | 'since'>, now: number): string {
+    const age = r.since == null ? null : spanWords(now - r.since)
+    switch (r.status) {
+        case 'up': return age == null ? 'up' : `up ${age}`
+        case 'crashed': return age == null ? 'crashed' : `crashed ${age} ago`
+        case 'down': return 'stopped'
+        case 'unknown': return 'unknown (pm down)'
+        default: return r.status
+    }
+}