@steve31415/baselib 3.2.0 → 3.3.0

package/dist/deploy/deploy.js

@@ -228,6 +228,7 @@ export async function runDeploy(options) {
             throw new Error('deploy exceeded its 25-minute deadline; lock may be breakable — aborting before traffic');
         }
         if (!(await verifyLock(runner, lock))) {
+            lock.stopHeartbeat();
             lock = null; // someone broke and superseded us; never touch their lock
             throw new Error('deploy lock lost (superseded by another deploy or rollback); aborting before traffic');
         }

package/dist/deploy/gcs.d.ts

@@ -2,11 +2,16 @@ import type { HoldRecord, ReleaseRecord, Runner } from './types.js';
 export interface LockHandle {
     uri: string;
     generation: string;
+    /** Ends the heartbeat; releaseLock calls it, and so must anyone who gives
+     *  the lock up without releasing it. */
+    stopHeartbeat(): void;
 }
 export interface AcquireOptions {
     waitMs?: number;
     staleMs?: number;
     pollMs?: number;
+    /** Refresh interval; 0 disables the heartbeat (tests). */
+    heartbeatMs?: number;
     now?: () => number;
     sleep?: (ms: number) => Promise<void>;
     log?: (message: string) => void;

package/dist/deploy/gcs.js

@@ -1,12 +1,20 @@
 // 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.
+// (create-only, generation-fenced, heartbeat-refreshed, 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;
+/** A holder refreshes its lock every HEARTBEAT_MS; a lock not refreshed for
+ *  STALE_MS is a dead holder's and may be broken — well inside the WAIT_MS a
+ *  waiter is prepared to spend, so a killed deploy no longer needs a human
+ *  to delete its lock. (Until 2026-09-04 staleness was judged from creation
+ *  time with a 30-minute threshold, read from a key gcloud does not emit:
+ *  the automatic break never fired.) */
+const HEARTBEAT_MS = 30_000;
+const STALE_MS = 3 * 60_000;
 const WAIT_MS = 5 * 60_000;
 const POLL_MS = 10_000;
 async function describeObject(runner, uri) {
@@ -45,17 +53,23 @@ export async function acquireLock(runner, uri, body, opts = {}) {
             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 generation = String(meta.generation);
+            const stopHeartbeat = startHeartbeat(runner, uri, generation, {
+                everyMs: opts.heartbeatMs ?? HEARTBEAT_MS,
+                now,
+                log,
+            });
+            return { uri, generation, stopHeartbeat };
         }
         const meta = await describeObject(runner, uri);
         if (meta?.generation) {
             const stale = opts.breakExisting ||
-                (meta.timeCreated !== undefined &&
-                    lockIsStale(meta.timeCreated, now(), opts.staleMs ?? STALE_MS));
+                (meta.update_time !== undefined &&
+                    lockIsStale(meta.update_time, now(), opts.staleMs ?? STALE_MS));
             if (stale) {
                 log(opts.breakExisting
                     ? `breaking existing lock (rollback takes priority): ${uri}`
-                    : `breaking stale lock (created ${meta.timeCreated}): ${uri}`);
+                    : `breaking stale lock (last refreshed ${meta.update_time}): ${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));
@@ -77,12 +91,46 @@ export async function acquireLock(runner, uri, body, opts = {}) {
         await sleep(opts.pollMs ?? POLL_MS);
     }
 }
+/** Refresh the lock's custom metadata, fenced on our generation: a metadata
+ *  update advances the object's server-side update_time (what staleness is
+ *  judged from) without changing its generation (what the fence is). A
+ *  refresh that fails the fence means a successor broke us — stop, and let
+ *  verifyLock report it before traffic. Refreshes run one at a time. */
+function startHeartbeat(runner, uri, generation, opts) {
+    if (opts.everyMs <= 0)
+        return () => { };
+    let stopped = false;
+    let chain = Promise.resolve();
+    const stop = () => {
+        stopped = true;
+        clearInterval(timer);
+    };
+    const refresh = async () => {
+        if (stopped)
+            return;
+        const result = await runner('gcloud', [
+            'storage', 'objects', 'update', uri,
+            `--custom-metadata=heartbeat=${new Date(opts.now()).toISOString()}`,
+            `--if-generation-match=${generation}`, '--quiet',
+        ]);
+        if (result.code !== 0) {
+            opts.log(`lock heartbeat failed (generation ${generation} gone?): ${result.stderr.trim()}`);
+            stop();
+        }
+    };
+    const timer = setInterval(() => {
+        chain = chain.then(refresh);
+    }, opts.everyMs);
+    timer.unref?.();
+    return stop;
+}
 /** 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) {
+    handle.stopHeartbeat();
     const ok = await conditionalDelete(runner, handle.uri, handle.generation);
     if (!ok) {
         // A successor broke us; their lock must survive. Nothing to clean up.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",