@steve31415/baselib 2.2.2 → 2.4.0

package/dist/deploy/exec.d.ts

@@ -0,0 +1,10 @@
+import type { ExecOptions, ExecResult, Runner } from './types.js';
+export declare const realRunner: Runner;
+export declare class CommandFailure extends Error {
+    readonly result: ExecResult;
+    constructor(message: string, result: ExecResult);
+}
+/** Run and throw a CommandFailure (with a stderr/stdout tail) on nonzero. */
+export declare function must(runner: Runner, file: string, args: string[], opts?: ExecOptions): Promise<ExecResult>;
+/** must() + parse stdout as JSON. */
+export declare function mustJson<T>(runner: Runner, file: string, args: string[], opts?: ExecOptions): Promise<T>;

package/dist/deploy/exec.js

@@ -0,0 +1,41 @@
+// Process runner for pw-deploy/pw-rollback. All external commands (gcloud,
+// git, npm, bash) flow through the injected Runner so orchestration logic is
+// testable against a scripted fake.
+import { execFile } from 'node:child_process';
+const DEFAULT_TIMEOUT_MS = 15 * 60_000;
+const MAX_BUFFER = 32 * 1024 * 1024;
+export const realRunner = (file, args, opts) => new Promise((resolve) => {
+    const child = execFile(file, args, {
+        timeout: opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        killSignal: 'SIGTERM',
+        maxBuffer: MAX_BUFFER,
+        cwd: opts?.cwd,
+        env: opts?.env ? { ...process.env, ...opts.env } : process.env,
+    }, (error, stdout, stderr) => {
+        const code = error === null ? 0 : typeof error.code === 'number' ? error.code : 1;
+        resolve({ stdout: String(stdout), stderr: String(stderr), code });
+    });
+    if (opts?.input !== undefined)
+        child.stdin?.end(opts.input);
+});
+export class CommandFailure extends Error {
+    result;
+    constructor(message, result) {
+        super(message);
+        this.result = result;
+    }
+}
+/** Run and throw a CommandFailure (with a stderr/stdout tail) on nonzero. */
+export async function must(runner, file, args, opts) {
+    const result = await runner(file, args, opts);
+    if (result.code !== 0) {
+        const tail = (result.stderr.trim() || result.stdout.trim()).slice(-2000);
+        throw new CommandFailure(`${file} ${args.join(' ')} exited ${result.code}\n${tail}`, result);
+    }
+    return result;
+}
+/** must() + parse stdout as JSON. */
+export async function mustJson(runner, file, args, opts) {
+    const result = await must(runner, file, args, opts);
+    return JSON.parse(result.stdout);
+}

package/dist/deploy/gcs.d.ts

@@ -0,0 +1,43 @@
+import type { HoldRecord, ReleaseRecord, Runner } from './types.js';
+export interface LockHandle {
+    uri: string;
+    generation: string;
+}
+export interface AcquireOptions {
+    waitMs?: number;
+    staleMs?: number;
+    pollMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (message: string) => void;
+    /** Rollback mode: break any existing lock immediately (a rollback must not
+     *  queue behind the stuck deploy that motivated it). */
+    breakExisting?: boolean;
+}
+export declare function acquireLock(runner: Runner, uri: string, body: string, opts?: AcquireOptions): Promise<LockHandle>;
+/** The fence: true only while our exact generation still exists. */
+export declare function verifyLock(runner: Runner, handle: LockHandle): Promise<boolean>;
+export declare function releaseLock(runner: Runner, handle: LockHandle): Promise<void>;
+export declare function readHold(runner: Runner, uri: string): Promise<HoldRecord | null>;
+export declare function placeHold(runner: Runner, uri: string, hold: HoldRecord): Promise<void>;
+export declare function clearHold(runner: Runner, uri: string): Promise<void>;
+export declare function listReleaseRecords(runner: Runner, bucket: string, prefix: string): Promise<{
+    url: string;
+    metadata?: {
+        timeCreated?: string;
+    };
+}[]>;
+export declare function readReleaseRecord(runner: Runner, bucket: string, prefix: string, sha: string): Promise<ReleaseRecord | null>;
+/** Create-only; an existing record for the SHA is tolerated (re-release). */
+export declare function writeReleaseRecord(runner: Runner, bucket: string, prefix: string, record: ReleaseRecord): Promise<'written' | 'already-present'>;
+/** Idempotent content-addressed publish: create-only per object, immutable
+ *  caching, build-id metadata. Reused hashed files are left untouched. */
+export declare function publishRetainedAssets(runner: Runner, input: {
+    dir: string;
+    bucket: string;
+    prefix: string;
+    buildId: string;
+}): Promise<{
+    published: number;
+    reused: number;
+}>;

package/dist/deploy/gcs.js

@@ -0,0 +1,189 @@
+// GCS-backed coordination for pw-deploy/pw-rollback: the per-app deploy lock
+// (create-only, generation-fenced, server-time staleness), the rollback hold,
+// release records, and the default retained-asset publisher.
+import { readdir, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { CommandFailure, must } from './exec.js';
+import { contentTypeFor, lockIsStale, SHA40 } from './plan.js';
+const STALE_MS = 30 * 60_000;
+const WAIT_MS = 5 * 60_000;
+const POLL_MS = 10_000;
+async function describeObject(runner, uri) {
+    const result = await runner('gcloud', ['storage', 'objects', 'describe', uri, '--format=json']);
+    if (result.code !== 0)
+        return null;
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        return null;
+    }
+}
+async function createOnly(runner, uri, body) {
+    const tmp = join(tmpdir(), `pw-lock-${process.pid}-${Date.now()}`);
+    await writeFile(tmp, body);
+    const result = await runner('gcloud', [
+        'storage', 'cp', tmp, uri, '--if-generation-match=0', '--quiet',
+    ]);
+    return result.code === 0;
+}
+/** Delete only the observed generation; false when someone else won. */
+async function conditionalDelete(runner, uri, generation) {
+    const result = await runner('gcloud', [
+        'storage', 'rm', uri, `--if-generation-match=${generation}`, '--quiet',
+    ]);
+    return result.code === 0;
+}
+export async function acquireLock(runner, uri, body, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const log = opts.log ?? (() => { });
+    const deadline = now() + (opts.waitMs ?? WAIT_MS);
+    for (;;) {
+        if (await createOnly(runner, uri, body)) {
+            const meta = await describeObject(runner, uri);
+            if (!meta?.generation)
+                throw new Error(`lock created but not describable: ${uri}`);
+            return { uri, generation: String(meta.generation) };
+        }
+        const meta = await describeObject(runner, uri);
+        if (meta?.generation) {
+            const stale = opts.breakExisting ||
+                (meta.timeCreated !== undefined &&
+                    lockIsStale(meta.timeCreated, now(), opts.staleMs ?? STALE_MS));
+            if (stale) {
+                log(opts.breakExisting
+                    ? `breaking existing lock (rollback takes priority): ${uri}`
+                    : `breaking stale lock (created ${meta.timeCreated}): ${uri}`);
+                // Conditional on the observed generation: two breakers cannot both
+                // win, and a just-released-and-reacquired lock is not clobbered.
+                await conditionalDelete(runner, uri, String(meta.generation));
+                continue; // fresh create-only attempt decides the winner
+            }
+            let holder = '';
+            try {
+                const read = await runner('gcloud', ['storage', 'cat', uri]);
+                holder = read.code === 0 ? read.stdout.trim().split('\n').slice(0, 2).join(' ') : '';
+            }
+            catch {
+                /* informational only */
+            }
+            if (now() >= deadline) {
+                throw new Error(`deploy lock held: ${uri} (${holder || 'holder unknown'})`);
+            }
+            log(`waiting for deploy lock: ${uri} (${holder || 'holder unknown'})`);
+        }
+        await sleep(opts.pollMs ?? POLL_MS);
+    }
+}
+/** The fence: true only while our exact generation still exists. */
+export async function verifyLock(runner, handle) {
+    const meta = await describeObject(runner, handle.uri);
+    return meta !== null && String(meta.generation) === handle.generation;
+}
+export async function releaseLock(runner, handle) {
+    const ok = await conditionalDelete(runner, handle.uri, handle.generation);
+    if (!ok) {
+        // A successor broke us; their lock must survive. Nothing to clean up.
+    }
+}
+// ---- hold ----
+export async function readHold(runner, uri) {
+    const result = await runner('gcloud', ['storage', 'cat', uri]);
+    if (result.code !== 0)
+        return null;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return Array.isArray(parsed.heldShas) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function placeHold(runner, uri, hold) {
+    const tmp = join(tmpdir(), `pw-hold-${process.pid}-${Date.now()}`);
+    await writeFile(tmp, JSON.stringify(hold, null, 2));
+    await must(runner, 'gcloud', [
+        'storage', 'cp', tmp, uri, '--cache-control=no-store', '--quiet',
+    ]);
+}
+export async function clearHold(runner, uri) {
+    await runner('gcloud', ['storage', 'rm', uri, '--quiet']);
+}
+// ---- release records ----
+export async function listReleaseRecords(runner, bucket, prefix) {
+    const result = await runner('gcloud', ['storage', 'ls', '--json', `gs://${bucket}/${prefix}**`]);
+    if (result.code !== 0)
+        return []; // no records yet
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        return [];
+    }
+}
+export async function readReleaseRecord(runner, bucket, prefix, sha) {
+    if (!SHA40.test(sha))
+        return null;
+    const result = await runner('gcloud', ['storage', 'cat', `gs://${bucket}/${prefix}${sha}.json`]);
+    if (result.code !== 0)
+        return null;
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        return null;
+    }
+}
+/** Create-only; an existing record for the SHA is tolerated (re-release). */
+export async function writeReleaseRecord(runner, bucket, prefix, record) {
+    const tmp = join(tmpdir(), `pw-release-${process.pid}-${Date.now()}`);
+    await writeFile(tmp, `${JSON.stringify(record, null, 2)}\n`);
+    const uri = `gs://${bucket}/${prefix}${record.sha}.json`;
+    const result = await runner('gcloud', [
+        'storage', 'cp', tmp, uri,
+        '--if-generation-match=0', '--cache-control=no-store',
+        '--content-type=application/json', '--quiet',
+    ]);
+    if (result.code === 0)
+        return 'written';
+    const existing = await readReleaseRecord(runner, bucket, prefix, record.sha);
+    if (existing)
+        return 'already-present';
+    throw new CommandFailure(`release record write failed: ${uri}`, result);
+}
+// ---- retained assets (default publisher) ----
+/** Idempotent content-addressed publish: create-only per object, immutable
+ *  caching, build-id metadata. Reused hashed files are left untouched. */
+export async function publishRetainedAssets(runner, input) {
+    const entries = await readdir(input.dir, { recursive: true });
+    let published = 0;
+    let reused = 0;
+    for (const entry of entries.map((e) => e.split('\\').join('/')).sort()) {
+        const path = join(input.dir, entry);
+        if (!(await stat(path)).isFile())
+            continue;
+        const uri = `gs://${input.bucket}/${input.prefix}${entry}`;
+        const result = await runner('gcloud', [
+            'storage', 'cp', path, uri,
+            '--if-generation-match=0',
+            '--cache-control=public, max-age=31536000, immutable',
+            `--content-type=${contentTypeFor(entry)}`,
+            `--custom-metadata=pwBuildId=${input.buildId}`,
+            '--quiet',
+        ]);
+        if (result.code === 0)
+            published += 1;
+        else {
+            // Exists already (content-addressed name): reuse. Anything else is a
+            // real failure we surface by re-checking existence.
+            const meta = await describeObject(runner, uri);
+            if (!meta) {
+                throw new CommandFailure(`asset publish failed: ${uri}`, result);
+            }
+            reused += 1;
+        }
+    }
+    return { published, reused };
+}

package/dist/deploy/plan.d.ts

@@ -0,0 +1,56 @@
+import type { ServingState } from './types.js';
+export declare const SHA40: RegExp;
+/** Lock staleness is judged from the GCS object's server-side timeCreated,
+ *  never from anything the lock writer wrote (its clock may be wrong). */
+export declare function lockIsStale(timeCreatedIso: string, nowMs: number, staleMs: number): boolean;
+/** Consistent serving base across an app's services (notes2's rule,
+ *  generalized): all services on one SHA -> that SHA; some already on the
+ *  target -> the rest must agree on one other SHA (the base); anything else
+ *  is a skew that needs a human. A null buildSha (pre-unification revision)
+ *  yields base null — callers skip base-dependent guards. */
+export declare function consistentBaseSha(serving: ServingState[], targetSha: string): {
+    ok: true;
+    baseSha: string | null;
+} | {
+    ok: false;
+    detail: string;
+};
+export interface RollbackSelection {
+    ok: boolean;
+    sha?: string;
+    refusal?: string;
+}
+/** Rollback target selection. A rollback may only move backward: the target
+ *  must come from a successful release record, differ from every serving
+ *  SHA, and be an ancestor of each serving SHA (per isAncestor). Re-running
+ *  the no-arg form converges instead of oscillating. */
+export declare function selectRollbackTarget(input: {
+    requested?: string;
+    records: {
+        sha: string;
+        at: string;
+    }[];
+    serving: ServingState[];
+    isAncestor: (maybeAncestor: string, descendant: string) => Promise<boolean>;
+}): Promise<RollbackSelection>;
+/** Pick the revision to roll back to for one service: newest ready revision
+ *  carrying the target BUILD_ID (same-SHA revisions with different digests
+ *  can exist after a rebuilt image; newest wins). Input rows are
+ *  `gcloud run revisions list --format=json` items. */
+export declare function pickRevisionForSha(revisions: unknown[], targetSha: string): {
+    revision: string;
+    imageDigest: string;
+} | null;
+/** Extract serving state from a `gcloud run services describe --format=json`. */
+export declare function servingStateOf(service: string, described: unknown): ServingState;
+export declare function contentTypeFor(path: string): string;
+/** Parse release-record listing rows into {sha, at} entries. */
+export declare function releaseEntriesFrom(rows: {
+    url?: string;
+    metadata?: {
+        timeCreated?: string;
+    };
+}[] | unknown, prefix: string): {
+    sha: string;
+    at: string;
+}[];

package/dist/deploy/plan.js

@@ -0,0 +1,151 @@
+// Pure decision logic for pw-deploy/pw-rollback: everything here is
+// side-effect-free so the concurrency-sensitive choices (lock staleness,
+// rollback targeting, serving-state consistency) are unit-tested directly.
+export const SHA40 = /^[0-9a-f]{40}$/;
+/** Lock staleness is judged from the GCS object's server-side timeCreated,
+ *  never from anything the lock writer wrote (its clock may be wrong). */
+export function lockIsStale(timeCreatedIso, nowMs, staleMs) {
+    const created = Date.parse(timeCreatedIso);
+    if (!Number.isFinite(created))
+        return false;
+    return nowMs - created > staleMs;
+}
+/** Consistent serving base across an app's services (notes2's rule,
+ *  generalized): all services on one SHA -> that SHA; some already on the
+ *  target -> the rest must agree on one other SHA (the base); anything else
+ *  is a skew that needs a human. A null buildSha (pre-unification revision)
+ *  yields base null — callers skip base-dependent guards. */
+export function consistentBaseSha(serving, targetSha) {
+    if (serving.some((s) => s.buildSha === null))
+        return { ok: true, baseSha: null };
+    const shas = [...new Set(serving.map((s) => s.buildSha))];
+    if (shas.length === 1)
+        return { ok: true, baseSha: shas[0] };
+    const others = shas.filter((sha) => sha !== targetSha);
+    if (others.length === 1 && shas.length === 2)
+        return { ok: true, baseSha: others[0] };
+    return {
+        ok: false,
+        detail: `services serve inconsistent builds: ${serving
+            .map((s) => `${s.service}=${s.buildSha?.slice(0, 7)}`)
+            .join(' ')}`,
+    };
+}
+/** Rollback target selection. A rollback may only move backward: the target
+ *  must come from a successful release record, differ from every serving
+ *  SHA, and be an ancestor of each serving SHA (per isAncestor). Re-running
+ *  the no-arg form converges instead of oscillating. */
+export async function selectRollbackTarget(input) {
+    const servingShas = input.serving.map((s) => s.buildSha);
+    if (servingShas.some((sha) => sha === null)) {
+        return {
+            ok: false,
+            refusal: 'a serving revision has no BUILD_ID (pre-unification); use the manual ' +
+                'gcloud run services update-traffic recipe in OPERATIONS.md',
+        };
+    }
+    const distinctServing = [...new Set(servingShas)];
+    const validate = async (sha) => {
+        if (distinctServing.includes(sha))
+            return `target ${sha.slice(0, 7)} is already serving`;
+        for (const serving of distinctServing) {
+            if (!(await input.isAncestor(sha, serving))) {
+                return `target ${sha.slice(0, 7)} is not an ancestor of serving ${serving.slice(0, 7)} — rollback only moves backward`;
+            }
+        }
+        return null;
+    };
+    if (input.requested) {
+        if (!SHA40.test(input.requested))
+            return { ok: false, refusal: 'target must be a full 40-char SHA' };
+        if (!input.records.some((r) => r.sha === input.requested)) {
+            return { ok: false, refusal: `no successful release record for ${input.requested.slice(0, 7)}` };
+        }
+        const problem = await validate(input.requested);
+        return problem ? { ok: false, refusal: problem } : { ok: true, sha: input.requested };
+    }
+    const newestFirst = [...input.records].sort((a, b) => b.at.localeCompare(a.at));
+    for (const record of newestFirst) {
+        if (distinctServing.includes(record.sha))
+            continue;
+        if ((await validate(record.sha)) === null)
+            return { ok: true, sha: record.sha };
+    }
+    return {
+        ok: false,
+        refusal: 'no earlier successful release record qualifies; pass an explicit SHA or ' +
+            'use the manual traffic-move recipe',
+    };
+}
+/** Pick the revision to roll back to for one service: newest ready revision
+ *  carrying the target BUILD_ID (same-SHA revisions with different digests
+ *  can exist after a rebuilt image; newest wins). Input rows are
+ *  `gcloud run revisions list --format=json` items. */
+export function pickRevisionForSha(revisions, targetSha) {
+    const matches = revisions.flatMap((raw) => {
+        const row = raw;
+        const env = row.spec?.containers?.[0]?.env ?? [];
+        const buildSha = env.find((e) => e.name === 'BUILD_ID')?.value;
+        const ready = (row.status?.conditions ?? []).some((c) => c.type === 'Ready' && c.status === 'True');
+        const created = Date.parse(row.metadata?.creationTimestamp ?? '');
+        if (!ready || buildSha !== targetSha || !row.metadata?.name || !Number.isFinite(created))
+            return [];
+        return [
+            {
+                revision: row.metadata.name,
+                imageDigest: row.spec?.containers?.[0]?.image ?? '',
+                created,
+            },
+        ];
+    });
+    matches.sort((a, b) => b.created - a.created);
+    return matches[0] ? { revision: matches[0].revision, imageDigest: matches[0].imageDigest } : null;
+}
+/** Extract serving state from a `gcloud run services describe --format=json`. */
+export function servingStateOf(service, described) {
+    const d = described;
+    const active = (d.status?.traffic ?? []).filter((t) => (t.percent ?? 0) === 100);
+    if (active.length !== 1 || !active[0].revisionName) {
+        throw new Error(`${service}: expected exactly one 100% traffic target`);
+    }
+    const env = d.spec?.template?.spec?.containers?.[0]?.env ?? [];
+    const buildSha = env.find((e) => e.name === 'BUILD_ID')?.value ?? null;
+    return {
+        service,
+        revision: active[0].revisionName,
+        buildSha: buildSha !== null && SHA40.test(buildSha) ? buildSha : null,
+        imageDigest: d.spec?.template?.spec?.containers?.[0]?.image ?? null,
+    };
+}
+const CONTENT_TYPES = {
+    '.js': 'text/javascript',
+    '.mjs': 'text/javascript',
+    '.css': 'text/css',
+    '.map': 'application/json',
+    '.json': 'application/json',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.webp': 'image/webp',
+    '.woff2': 'font/woff2',
+    '.html': 'text/html',
+    '.txt': 'text/plain',
+};
+export function contentTypeFor(path) {
+    const dot = path.lastIndexOf('.');
+    const ext = dot === -1 ? '' : path.slice(dot).toLowerCase();
+    return CONTENT_TYPES[ext] ?? 'application/octet-stream';
+}
+/** Parse release-record listing rows into {sha, at} entries. */
+export function releaseEntriesFrom(rows, prefix) {
+    if (!Array.isArray(rows))
+        return [];
+    return rows.flatMap((row) => {
+        const r = row;
+        const url = r.url ?? '';
+        const name = url.slice(url.lastIndexOf('/') + 1);
+        const sha = name.endsWith('.json') ? name.slice(0, -5) : '';
+        if (!SHA40.test(sha) || !url.includes(prefix))
+            return [];
+        return [{ sha, at: r.metadata?.timeCreated ?? '' }];
+    });
+}

package/dist/deploy/rollback.d.ts

@@ -0,0 +1,10 @@
+import type { Runner } from './types.js';
+export interface RollbackOptions {
+    repoRoot: string;
+    runner: Runner;
+    log?: (message: string) => void;
+    argv?: string[];
+    sleep?: (ms: number) => Promise<void>;
+    fetchFn?: typeof fetch;
+}
+export declare function runRollback(options: RollbackOptions): Promise<number>;