@timqi/pier 0.1.0 → 0.1.1

package/dist/update.js

@@ -1,30 +1,19 @@
-// The newer Pier: whether one exists, and when this one may become it.
-//
-// The registry is asked, not the GitHub API: `registry.npmjs.org` is a CDN with
-// no rate limit and no token, and it is the same place `npm i -g` would look,
-// so what it reports is what an update would actually get.
-//
-// Nothing here installs anything. Applying is handed to whatever supervises
-// this process (service.ts's oneshot unit, injected as `apply`): a web server
-// holding provider keys must not npm-install as its own child, and the two
-// gates below — the operator switched it on, and nothing is running — are why
-// a self-replacing timer is not simply a supply-chain surface (AGENTS.md 8).
+// The newer Pier: whether one exists, and when this one may become it. The npm
+// registry is asked (no rate limit, and what `npm i -g` would get). Nothing
+// here installs: a web server holding provider keys must not npm-install as its
+// own child, so applying is handed to the supervisor (service.ts).
 import { createRequire } from "node:module";
 import { logger } from "./log.js";
 const log = logger("update");
 const PACKAGE = "@timqi/pier";
 const ENDPOINT = `https://registry.npmjs.org/${PACKAGE}/latest`;
-/** One conditional-GET-sized request against a CDN, so the cost of asking is
- *  not what sets this — how long a released fix may sit unnoticed is. */
+/** Set by how long a released fix may sit unnoticed, not by request cost. */
 const TTL_MS = 30 * 60_000;
 const TIMEOUT_MS = 5_000;
 export const currentVersion = () => createRequire(import.meta.url)("../package.json").version;
 export const isValidVersion = (version) => /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(version);
-/**
- * `1.2.3` against `1.10.0`, numerically per field: a string compare would call
- * the second one older. A prerelease suffix loses to the release it precedes,
- * which is all the semver this needs.
- */
+/** Numeric per field (a string compare calls `1.10.0` older than `1.2.3`); a
+ *  prerelease loses to its release, which is all the semver this needs. */
 export function isNewer(candidate, than) {
     const parse = (v) => (v.split("-")[0] ?? "").split(".").map((n) => Number.parseInt(n, 10) || 0);
     const [a, b] = [parse(candidate), parse(than)];
@@ -32,7 +21,6 @@ export function isNewer(candidate, than) {
         if ((a[i] ?? 0) !== (b[i] ?? 0))
             return (a[i] ?? 0) > (b[i] ?? 0);
     }
-    // Equal numbers: a prerelease is older than the release of the same version.
     const pre = (v) => v.split("-")[1] ?? "";
     return pre(candidate) === "" && pre(than) !== "";
 }
@@ -49,9 +37,8 @@ export class UpdateCheck {
         this.fetchLatest = fetchLatest;
         this.now = now;
     }
-    /** The last answer, and a refresh in the background when it is stale. Never
-     *  awaits the network: a workbench that loads is worth more than a fresh
-     *  version number. */
+    /** Never awaits the network: a workbench that loads is worth more than a
+     *  fresh version number. */
     status() {
         if (this.now() - this.#checkedAt >= TTL_MS)
             void this.refresh();
@@ -61,16 +48,14 @@ export class UpdateCheck {
             available: this.#latest !== null && isNewer(this.#latest, this.current),
         };
     }
-    /** The answer, waiting for the very first check instead of reporting "no
-     *  idea". A browser asks once per page load, so a process that had never
-     *  checked told every one of them `latest: null` — which is exactly how a
-     *  published release looked undetected. Later loads are served from cache. */
+    /** Waits for the very first check: `latest: null` on every page load is how
+     *  a published release goes undetected. */
     async statusNow() {
         if (this.#checkedAt === 0)
             await this.refresh();
         return this.status();
     }
-    /** Ask now. Concurrent callers share the one request. */
+    /** Concurrent callers share the one request. */
     refresh() {
         this.#inFlight ??= this.fetchLatest()
             .then((latest) => {
@@ -78,8 +63,7 @@ export class UpdateCheck {
             if (isNewer(latest, this.current))
                 log.info(`${latest} is available (running ${this.current})`);
         })
-            // A failed check is not a failure: no network, an offline box, a registry
-            // hiccup. It is reported once at debug and retried at the next TTL.
+            // No network or a registry hiccup is not a failure; retried at the next TTL.
             .catch((err) => log.debug(`registry check failed: ${String(err)}`))
             .finally(() => {
             this.#checkedAt = this.now();
@@ -88,19 +72,16 @@ export class UpdateCheck {
         return this.#inFlight;
     }
 }
-/** Often enough to catch an idle window on a busy box, and cheap: the registry
- *  itself is still only asked once per TTL (`status()` owns that). */
+/** Often enough to catch an idle window on a busy box; the registry is still
+ *  asked only once per TTL. */
 const AUTO_POLL_MS = 15 * 60_000;
 /** Watch for the moment all three conditions hold. Returns its own stop. */
 export function startAutoUpdate(check, auto, pollMs = AUTO_POLL_MS) {
-    // A handover drains first, which can outlast a poll interval; a second
-    // attempt on top of it would drain an already-draining Pier.
+    // A drain can outlast a poll interval.
     let handingOver = false;
     const tick = async () => {
         if (handingOver || !auto.enabled())
             return;
-        // Refreshes in the background when stale; today's answer is good enough,
-        // because the next tick is a quarter of an hour away either way.
         const { latest, available } = check.status();
         if (!available || !auto.idle())
             return;
@@ -108,9 +89,7 @@ export function startAutoUpdate(check, auto, pollMs = AUTO_POLL_MS) {
         handingOver = true;
         try {
             const started = await auto.apply();
-            // Not silent (§5b): an update that never happens must not look like an
-            // update that was never wanted. `busy` is the one non-start that is
-            // fine — someone else is already restarting this Pier.
+            // §5: an update that never happens must not look like one never wanted.
             if (started === "busy")
                 log.info("auto-update: a handover or restart is already in progress");
             else if (started !== "started")
@@ -120,18 +99,16 @@ export function startAutoUpdate(check, auto, pollMs = AUTO_POLL_MS) {
             log.error("auto-update failed", err);
         }
         finally {
-            // Only reached when the handover did *not* take the process with it, so
-            // the next tick is allowed to try again.
+            // Only reached when the handover did not take the process with it.
             handingOver = false;
         }
     };
     const timer = setInterval(() => void tick(), pollMs);
-    timer.unref(); // a pending check must never be what keeps the process alive
+    timer.unref();
     return () => clearInterval(timer);
 }
 async function fetchLatestVersion() {
-    // Plain JSON: the abbreviated-packument content type npm uses for a whole
-    // package is a 406 on this endpoint, which answers one version already.
+    // npm's abbreviated-packument content type is a 406 on this endpoint.
     const res = await fetch(ENDPOINT, {
         signal: AbortSignal.timeout(TIMEOUT_MS),
         headers: { accept: "application/json" },