Loading files
a8366f179This file is pinned to the selected release. Download the original to open it in your design tool.
/**
* Self-update mechanics — PURE (no process-control; the daemon decides when to restart).
*
* The daemon polls a GCS `metadata.json` (same shape as the device OTA manifest), and when a strictly
* newer build is published it downloads `cli.js` + `notify.mjs`, verifies sha256 IN MEMORY (so a bad
* download never touches disk), canary-runs the new bundle, then atomically swaps them into the install
* dir (keeping a `.prev` for rollback). Firing the restart, supervising the new process, and rolling
* back are all the CALLER's job (`restartForUpdate` in cli.ts) — this module only stages.
*
* Manifest entry shape (key = ADAPTER_UPDATE_KEY, coexists with the device `commander` key):
* { "adapter": { "version": "0.0.2",
* "cli": { "url": "…/cli.js", "sha256": "…", "size": N },
* "notify": { "url": "…/notify.mjs","sha256": "…", "size": M } } }
*/
import { createHash } from 'crypto'
import { copyFileSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'fs'
import { spawnSync } from 'child_process'
import { join } from 'path'
import { SpawnLockBusyError, describeSpawnLockFailure } from './daemonSpawnLock.js'
import { managedNodePath } from './nodeRuntime.js'
export interface FileRef {
url: string
sha256: string
size?: number
}
export interface UpdateEntry {
version: string
cli: FileRef
notify: FileRef
}
const CLI = 'cli.js'
const NOTIFY = 'notify.mjs'
const PACKAGE = 'package.json'
const RUNTIME_PACKAGE = `${JSON.stringify({ type: 'module' })}\n`
/** Strict semver-greater on the `X.Y.Z` core (ignores pre-release/build). Unparseable → false, so a
* malformed manifest or the `0.0.0-dev` dev sentinel never triggers a downgrade/oscillation.
*
* Ordering only — it is NOT the permission to update. Automatic updates go through
* {@link shouldAutoUpdate}, which also refuses to overwrite a local build. */
export function semverGt(a: string, b: string): boolean {
const parse = (v: string): number[] | null => {
const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v)
return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null
}
const x = parse(a)
const y = parse(b)
if (!x || !y) return false
for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i]
return false
}
/** A build made from a working tree rather than downloaded from the release channel: the
* `<published-core>-dev.<sha>[.dirty]` label that scripts/lib/build-label.sh stamps on every local
* install, plus the `0.0.0-dev` sentinel version.ts falls back to. */
export function isLocalDevBuild(version: string): boolean {
return /^\d+\.\d+\.\d+-dev(\.|$)/.test(version.trim())
}
/**
* The gate every AUTOMATIC update passes: the daemon's background poll and `harness start`'s
* update-before-connect. Newer, AND not on top of a local build.
*
* Install-if-missing, never upgrade-over-a-dev-build. The old rule was ordering alone, and because
* `install-cli.sh` labels a local build `<published-core>-dev.<sha>`, the very next release outranked
* it: a machine developing against unreleased CLI code had its bundle silently replaced mid-session,
* and the only symptom was the unreleased feature quietly not working. Being carried forward is not
* worth that — a developer who wants the release can ask for it (`harness update --force`) and a
* release install, which is every user's, still updates exactly as before.
*/
export function shouldAutoUpdate(candidate: string, current: string): boolean {
if (isLocalDevBuild(current)) return false
return semverGt(candidate, current)
}
/** Fetch + parse the manifest; return this adapter's entry, or null (unreachable / malformed / absent). */
export async function fetchManifest(url: string, key: string): Promise<UpdateEntry | null> {
// No `cache` option needed: undici doesn't HTTP-cache by default and GCS serves the manifest no-cache.
const res = await fetch(url)
if (!res.ok) return null
const json = (await res.json()) as Record<string, unknown>
const entry = json?.[key] as Partial<UpdateEntry> | undefined
const okFile = (f: unknown): f is FileRef =>
!!f && typeof (f as FileRef).url === 'string' && typeof (f as FileRef).sha256 === 'string'
if (!entry || typeof entry.version !== 'string' || !okFile(entry.cli) || !okFile(entry.notify)) return null
return { version: entry.version, cli: entry.cli, notify: entry.notify }
}
/** Download one file and verify its sha256 in memory; throws on a non-2xx or a digest mismatch. */
export async function downloadVerified(ref: FileRef): Promise<Buffer> {
const res = await fetch(ref.url)
if (!res.ok) throw new Error(`download ${ref.url} → HTTP ${res.status}`)
const buf = Buffer.from(await res.arrayBuffer())
const got = createHash('sha256').update(buf).digest('hex')
if (got.toLowerCase() !== ref.sha256.toLowerCase()) {
throw new Error(`sha256 mismatch for ${ref.url}: expected ${ref.sha256}, got ${got}`)
}
return buf
}
/** Cheap runnability check: write the new bundle into a temp install-shaped dir and run
* `node cli.js version`. This catches broken ESM/CJS packaging before the live install is touched. */
export function canary(cliBuf: Buffer, dir: string): boolean {
const tmpDir = join(dir, `.canary-${process.pid}-${Date.now()}`)
const tmpCli = join(tmpDir, CLI)
try {
mkdirSync(tmpDir, { recursive: true })
writeFileSync(join(tmpDir, PACKAGE), RUNTIME_PACKAGE)
writeFileSync(tmpCli, cliBuf)
// The interpreter the NEXT daemon will run on — see managedNodePath(). Canarying on this
// process's interpreter would assert about a Node the new build may never be started with.
const r = spawnSync(managedNodePath(), [tmpCli, 'version'], { timeout: 15_000, stdio: 'ignore' })
return r.status === 0
} catch {
return false
} finally {
try { rmSync(tmpDir, { recursive: true, force: true }) } catch { /* ignore */ }
}
}
/** Atomically swap the new bytes into `dir`, backing up the current files to `.prev` for rollback.
* (Verify-in-memory first ⇒ we only ever write bytes we already trust; write-tmp+rename ⇒ no torn file.) */
export function stage(dir: string, cliBuf: Buffer, notifyBuf: Buffer): void {
mkdirSync(dir, { recursive: true })
writeFileSync(join(dir, PACKAGE), RUNTIME_PACKAGE)
const swap = (name: string, buf: Buffer): void => {
const target = join(dir, name)
if (existsSync(target)) copyFileSync(target, `${target}.prev`)
const tmp = `${target}.tmp`
writeFileSync(tmp, buf)
renameSync(tmp, target) // atomic within the same filesystem
}
swap(CLI, cliBuf)
swap(NOTIFY, notifyBuf)
}
/** Roll a failed update back to the `.prev` bytes (called by the supervisor when the new build crashes). */
export function restore(dir: string): void {
for (const name of [CLI, NOTIFY]) {
const prev = join(dir, `${name}.prev`)
if (existsSync(prev)) { try { renameSync(prev, join(dir, name)) } catch { /* ignore */ } }
}
}
/** Drop the `.prev` backups once the new build is confirmed healthy. */
export function confirm(dir: string): void {
for (const name of [CLI, NOTIFY]) {
try { rmSync(join(dir, `${name}.prev`), { force: true }) } catch { /* ignore */ }
}
}
export interface Poller { stop(): void }
/**
* Milliseconds from `nowMs` to the next tick. With a slot, ticks land on the wall-clock instant
* `slotSecond` seconds past each `intervalMs` boundary (`:45` of every minute for the defaults) —
* strictly in the future, so a call made exactly on the slot waits a whole interval rather than
* firing twice. Without a usable slot (negative, or an interval that does not divide a minute) it is
* the plain interval.
*/
export function msUntilSlot(nowMs: number, slotSecond: number | undefined, intervalMs: number): number {
if (slotSecond === undefined || slotSecond < 0 || intervalMs <= 0 || 60_000 % intervalMs !== 0) return intervalMs
const slotMs = (slotSecond * 1000) % intervalMs
const phase = ((nowMs % intervalMs) + intervalMs) % intervalMs
const wait = slotMs - phase
return wait > 0 ? wait : wait + intervalMs
}
/**
* Poll on an interval; on the first build {@link shouldAutoUpdate} allows that also verifies and
* passes its canary, STAGE it and call `onStaged(version)` exactly once, then stop polling (the
* caller restarts immediately). Every failure
* (fetch/parse/sha/canary/disk) is swallowed and simply retried next tick — the daemon never crashes
* on a bad update.
*
* Ticks are SCHEDULED, not immediate: the first one lands on the next slot (see {@link msUntilSlot}),
* and each tick books the next from the clock rather than from its own end, so a slow download does
* not drift the slot. `harness start` already staged the newest build before spawning this daemon,
* which is why nothing is lost by not checking at start.
*/
export function startSelfUpdater(opts: {
currentVersion: string
url: string
key: string
dir: string
intervalMs: number
/** Wall-clock second the ticks land on; omit or negative for a plain interval. */
slotSecond?: number
/** The clock (tests). */
now?: () => number
/** Awaited: the section from the byte swap through whatever `onStaged` does (the daemon's restart
* handoff) is ONE critical section, and the lock `withLock` takes must outlive all of it. */
onStaged: (version: string) => void | Promise<void>
/** Wrap the swap + `onStaged` in a mutual exclusion with every other process that writes the
* bundle or spawns the daemon. Default: none (tests, and callers that hold their own). */
withLock?: <T>(fn: () => Promise<T>) => Promise<T>
}): Poller {
let checking = false
let done = false
let timer: NodeJS.Timeout | null = null
const withLock = opts.withLock ?? ((fn) => fn())
// The bytes of a build we have already downloaded, verified and canaried, kept across ticks: when
// the lock was busy (a `harness start` or `harness update` mid-flight) the next tick should try the
// swap again, not the whole download.
let verified: { version: string; cliBuf: Buffer; notifyBuf: Buffer } | null = null
const now = opts.now ?? Date.now
const stop = (): void => { if (timer) { clearTimeout(timer); timer = null } }
const schedule = (): void => {
if (done) return
stop()
timer = setTimeout(() => void tick(), msUntilSlot(now(), opts.slotSecond, opts.intervalMs))
timer.unref?.()
}
const tick = async (): Promise<void> => {
if (done) return
// Booked before the work, from the clock: the next tick is on the next slot whatever this one
// costs; a tick that stages calls `stop()` below and cancels it. Booked even when this slot is
// skipped because the previous check is still running (a download on a slow link can outlast a
// minute) — otherwise the chain would end there and the daemon would never look again.
schedule()
if (checking) return
checking = true
try {
const entry = await fetchManifest(opts.url, opts.key)
if (!entry || !shouldAutoUpdate(entry.version, opts.currentVersion)) return
if (verified?.version !== entry.version) {
console.log(`[update] newer build available: ${opts.currentVersion} → ${entry.version}`)
const cliBuf = await downloadVerified(entry.cli)
const notifyBuf = await downloadVerified(entry.notify)
if (!canary(cliBuf, opts.dir)) { console.error('[update] canary failed for the new build — skipping'); return }
verified = { version: entry.version, cliBuf, notifyBuf }
}
const ready = verified
// Downloaded and verified OUTSIDE the lock (that can take a while on a slow link and touches
// nothing shared); swapped and handed off INSIDE it.
await withLock(async () => {
stage(opts.dir, ready.cliBuf, ready.notifyBuf)
done = true
stop()
console.log(`[update] staged ${ready.version} — restarting now`)
await opts.onStaged(ready.version)
})
} catch (err) {
// A busy lock is not a failed check: the bytes are good and waiting, and the next tick tries
// the swap again. Say so, or a minute of "check failed" reads as the updater being broken.
if (err instanceof SpawnLockBusyError) {
console.log(`[update] ${verified?.version ?? 'a new build'} is ready but the daemon spawn lock is ${describeSpawnLockFailure(err)} — trying again next check`)
} else {
console.error('[update] check failed (will retry):', err instanceof Error ? err.message : err)
}
} finally {
checking = false
}
}
schedule()
return { stop }
}