@steve31415/baselib 3.32.0 → 3.33.0

package/dist/app-update-browser/build-update.d.ts

@@ -65,10 +65,17 @@ export declare class BuildUpdateMonitor {
     /** Deployment push is intentionally only a prompt to ask canonical HTTP;
      *  it carries no traffic authority of its own and runs while hidden too. */
     observeDeploymentHint(): void;
+    /** Asks canonical HTTP for the traffic build. Nothing to ask once the page
+     * is reloading: the navigation aborts the request, so a check then can only
+     * log a false failure (digest, 2026-10-06: a page hidden and shown within
+     * 0.4 s ran its deferred reload on the hide and this check on the show). */
     checkNow(): Promise<void>;
     private observeTrafficBuild;
     private markAvailable;
     private maybeReload;
+    /** A method, not an inline test: TypeScript would keep the narrowing from
+     * checkNow's entry across its await. */
+    private isReloading;
     private justReturned;
     private setState;
     /** Polls only while visible: an interval in a hidden page would wake it

package/dist/app-update-browser/build-update.js

@@ -91,8 +91,12 @@ export class BuildUpdateMonitor {
     observeDeploymentHint() {
         void this.checkNow();
     }
+    /** Asks canonical HTTP for the traffic build. Nothing to ask once the page
+     * is reloading: the navigation aborts the request, so a check then can only
+     * log a false failure (digest, 2026-10-06: a page hidden and shown within
+     * 0.4 s ran its deferred reload on the hide and this check on the show). */
     async checkNow() {
-        if (!navigator.onLine)
+        if (!navigator.onLine || this.isReloading())
             return;
         const lifecycle = this.lifecycle;
         const requestNumber = ++this.requestNumber;
@@ -130,7 +134,8 @@ export class BuildUpdateMonitor {
         catch (error) {
             if (lifecycle !== this.lifecycle ||
                 requestNumber < this.appliedRequestNumber ||
-                !navigator.onLine)
+                !navigator.onLine ||
+                this.isReloading())
                 return;
             if (!this.checkFailure) {
                 this.checkFailure = true;
@@ -185,6 +190,11 @@ export class BuildUpdateMonitor {
         else
             location.reload();
     }
+    /** A method, not an inline test: TypeScript would keep the narrowing from
+     * checkNow's entry across its await. */
+    isReloading() {
+        return this.state.kind === 'reloading';
+    }
     justReturned() {
         return (document.visibilityState === 'visible' &&
             this.returnedAt !== null &&

package/dist/sync-browser/client.d.ts

@@ -157,6 +157,8 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     private loopEscalated;
     private reconciliationTail;
     private initialization;
+    /** Non-null while the first bootstrap is loading, retries included. */
+    private firstLoadRetry;
     private disposed;
     private hiddenSince;
     private hiddenSocketFailed;
@@ -181,6 +183,14 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     constructor(options: SyncClientOptions<B, C, S, Summary>);
     init(): Promise<void>;
     private initialize;
+    /** The first bootstrap. One that gets no HTTP answer (fetch's TypeError: no
+     * network, or one that reaches nothing — a tab Android Chrome restored from
+     * its cache) is retried until it loads, while init() stays pending and the
+     * state says `disconnected`; any other failure rejects, as it always did
+     * (docs/SYNC-INIT-RECOVERY-PLAN.md). Rejects with a LifecycleAbort once
+     * halted, disposed, or abandoned by a failed outbox. */
+    private loadFirstBootstrap;
+    private createFirstLoadRetry;
     dispose(): void;
     submit(event: ClientEvent<C>, summary: Summary): Promise<void>;
     /** Current-tab entries only; recovered work is retried silently. */

package/dist/sync-browser/client.js

@@ -1,3 +1,4 @@
+import { FirstLoadRetry } from './first-load-retry.js';
 const RECONNECT_DELAYS_SECONDS = [1, 2, 4, 8, 16, 30];
 const PING_INTERVAL_MS = 30_000;
 const CONNECT_WATCHDOG_MS = 10_000;
@@ -91,6 +92,8 @@ export class SyncClient {
     loopEscalated = false;
     reconciliationTail = Promise.resolve();
     initialization = null;
+    /** Non-null while the first bootstrap is loading, retries included. */
+    firstLoadRetry = null;
     disposed = false;
     // Hidden-page state (docs/SYNC-BACKGROUND-PLAN.md).
     hiddenSince = null;
@@ -158,16 +161,7 @@ export class SyncClient {
             throw error;
         });
         this.options.markPerformance?.('bootstrap-start');
-        const bootstrapPromise = this.abortable((signal) => this.options.fetchBootstrap(signal))
-            .then((bootstrap) => {
-            this.options.markPerformance?.('bootstrap-response');
-            return bootstrap;
-        })
-            .catch((error) => {
-            if (!isLifecycleAbort(error))
-                this.options.logger.error('bootstrap failed', { error });
-            throw error;
-        });
+        const bootstrapPromise = this.loadFirstBootstrap();
         let recovered;
         let bootstrap;
         try {
@@ -177,6 +171,10 @@ export class SyncClient {
         }
         catch (error) {
             this.abortFetches();
+            this.firstLoadRetry?.stop();
+            // A halt or dispose is a deliberate stop, not a failed load.
+            if (this.halted || this.disposed)
+                return;
             throw isLifecycleAbort(error) ? error.reason : error;
         }
         if (this.stopBeforeStoreMutation())
@@ -202,11 +200,77 @@ export class SyncClient {
         this.installRuntimeListeners();
         this.connect();
     }
+    /** The first bootstrap. One that gets no HTTP answer (fetch's TypeError: no
+     * network, or one that reaches nothing — a tab Android Chrome restored from
+     * its cache) is retried until it loads, while init() stays pending and the
+     * state says `disconnected`; any other failure rejects, as it always did
+     * (docs/SYNC-INIT-RECOVERY-PLAN.md). Rejects with a LifecycleAbort once
+     * halted, disposed, or abandoned by a failed outbox. */
+    async loadFirstBootstrap() {
+        const retry = this.createFirstLoadRetry();
+        this.firstLoadRetry = retry;
+        try {
+            for (;;) {
+                const controller = new AbortController();
+                this.abortControllers.add(controller);
+                retry.attemptStarted(() => controller.abort());
+                try {
+                    const bootstrap = await this.options.fetchBootstrap(controller.signal);
+                    retry.attemptEnded('loaded');
+                    this.options.markPerformance?.('bootstrap-response');
+                    retry.recovered();
+                    return bootstrap;
+                }
+                catch (error) {
+                    retry.attemptEnded('failed');
+                    if (this.halted || this.disposed || retry.stopped)
+                        throw new LifecycleAbort(error);
+                    // An abort here is the retry replacing a stale attempt: no answer.
+                    if (!controller.signal.aborted && !(error instanceof TypeError)) {
+                        this.options.logger.error('bootstrap failed', { reachedServer: true, failures: retry.failures, error });
+                        this.publish({ kind: 'error', pending: this.pendingCount(), message: 'Failed to load' });
+                        throw error;
+                    }
+                    retry.failed(error);
+                    if (retry.failures === 1)
+                        this.publish({ kind: 'disconnected', pending: this.pendingCount() });
+                }
+                finally {
+                    this.abortControllers.delete(controller);
+                }
+                const proceed = await retry.next();
+                if (!proceed || this.stopBeforeStoreMutation())
+                    throw new LifecycleAbort('first load stopped');
+            }
+        }
+        finally {
+            retry.stop();
+            if (this.firstLoadRetry === retry)
+                this.firstLoadRetry = null;
+        }
+    }
+    createFirstLoadRetry() {
+        const runtime = this.options.runtime;
+        return new FirstLoadRetry({
+            now: () => this.now(),
+            visible: () => runtime.visibility() !== 'hidden',
+            setTimer: (callback, delayMs) => this.setTimer(callback, delayMs),
+            clearTimer: (timer) => runtime.clearTimeout(timer),
+            onOnline: (listener) => runtime.onOnline(listener),
+            onVisibilityChange: (listener) => runtime.onVisibilityChange(listener),
+            logger: this.options.logger,
+            visibleDelaysMs: RECONNECT_DELAYS_SECONDS.map((seconds) => seconds * 1000),
+            hiddenDelayMs: this.options.backgroundCatchupMs ?? DEFAULT_BACKGROUND_CATCHUP_MS,
+            escalateAfterMs: OUTAGE_ESCALATE_MS,
+            staleAttemptMs: CONNECT_WATCHDOG_MS,
+        });
+    }
     dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
         this.abortFetches();
+        this.firstLoadRetry?.stop();
         for (const remove of this.removeListeners.splice(0))
             remove();
         this.clearAllTimers();
@@ -1488,6 +1552,7 @@ export class SyncClient {
             return;
         this.halted = true;
         this.abortFetches();
+        this.firstLoadRetry?.stop();
         this.clearAllTimers();
         const socket = this.socket;
         this.socket = null;

package/dist/sync-browser/first-load-retry.d.ts

@@ -0,0 +1,58 @@
+import type { Logger } from '../log-browser.js';
+type TimeoutHandle = ReturnType<typeof globalThis.setTimeout>;
+export interface FirstLoadRetryOptions {
+    now(): number;
+    visible(): boolean;
+    setTimer(callback: () => void, delayMs: number): TimeoutHandle;
+    clearTimer(timer: TimeoutHandle): void;
+    onOnline(listener: () => void): () => void;
+    onVisibilityChange(listener: () => void): () => void;
+    logger: Pick<Logger, 'info' | 'warn' | 'error'>;
+    /** The wait after each failure while visible; the last one repeats. */
+    visibleDelaysMs: readonly number[];
+    hiddenDelayMs: number;
+    /** Not loaded after this much visible, on-time loading: one ERROR. */
+    escalateAfterMs: number;
+    /** A trigger replaces an attempt that has run this long; an attempt this
+     * long is logged (INFO `bootstrap slow`). */
+    staleAttemptMs: number;
+}
+export declare class FirstLoadRetry {
+    private readonly options;
+    private failureCount;
+    private readonly startedAt;
+    /** Ladder position of the next visible wait; a return restarts it. */
+    private step;
+    private escalated;
+    private escalateTimer;
+    private waitTimer;
+    private wake;
+    private attempt;
+    /** A trigger arrived during the running attempt: if it fails, no wait. */
+    private triggered;
+    private stoppedFlag;
+    private readonly removeListeners;
+    /** Created as the first attempt starts. */
+    constructor(options: FirstLoadRetryOptions);
+    get failures(): number;
+    get stopped(): boolean;
+    /** `abort` cancels this attempt (its fetch's AbortSignal). */
+    attemptStarted(abort: () => void): void;
+    attemptEnded(outcome: 'loaded' | 'failed'): void;
+    /** An attempt failed without an HTTP answer (or was replaced as stale).
+     * One WARN per streak. */
+    failed(error: unknown): void;
+    /** Resolves true when the next attempt is due (timer, `online`, a return
+     * to visible, or a trigger during the attempt that just failed), false
+     * once stopped. */
+    next(): Promise<boolean>;
+    recovered(): void;
+    /** Removes listeners and timers and ends a running wait (`next` → false). */
+    stop(): void;
+    private trigger;
+    private release;
+    /** ERROR only once the load has lasted `escalateAfterMs` in view, on time;
+     * re-armed on each return. */
+    private armEscalation;
+}
+export {};

package/dist/sync-browser/first-load-retry.js

@@ -0,0 +1,167 @@
+// First-load recovery (docs/SYNC-INIT-RECOVERY-PLAN.md): while the first
+// bootstrap has not loaded, this decides when the next attempt is due and
+// owns the streak's logs. SyncClient makes the attempts, one at a time; a
+// trigger (`online`, a return to visible) never starts a second attempt next
+// to a running one: it ends the wait between attempts, or marks the running
+// attempt so that its failure retries at once, or, when that attempt has
+// already run `staleAttemptMs`, aborts it so a fresh one starts.
+/** A timer this late ran after the device slept or the page was frozen. */
+const LATE_TIMER_MS = 1_000;
+/** An escalation timer this late: that time was not spent loading in front
+ * of the user (as the socket's `sync outage ongoing`). */
+const ESCALATE_LATE_TOLERANCE_MS = 5_000;
+export class FirstLoadRetry {
+    options;
+    failureCount = 0;
+    startedAt;
+    /** Ladder position of the next visible wait; a return restarts it. */
+    step = 0;
+    escalated = false;
+    escalateTimer = null;
+    waitTimer = null;
+    wake = null;
+    attempt = null;
+    /** A trigger arrived during the running attempt: if it fails, no wait. */
+    triggered = false;
+    stoppedFlag = false;
+    removeListeners;
+    /** Created as the first attempt starts. */
+    constructor(options) {
+        this.options = options;
+        this.startedAt = options.now();
+        this.removeListeners = [
+            options.onOnline(() => this.trigger()),
+            options.onVisibilityChange(() => {
+                if (!this.options.visible())
+                    return;
+                this.step = 0;
+                this.armEscalation();
+                this.trigger();
+            }),
+        ];
+        this.armEscalation();
+    }
+    get failures() {
+        return this.failureCount;
+    }
+    get stopped() {
+        return this.stoppedFlag;
+    }
+    /** `abort` cancels this attempt (its fetch's AbortSignal). */
+    attemptStarted(abort) {
+        this.attempt = { startedAt: this.options.now(), abort };
+        this.triggered = false;
+    }
+    attemptEnded(outcome) {
+        const attempt = this.attempt;
+        this.attempt = null;
+        if (attempt === null || this.stoppedFlag)
+            return;
+        const attemptMs = this.options.now() - attempt.startedAt;
+        if (attemptMs >= this.options.staleAttemptMs) {
+            this.options.logger.info('bootstrap slow', { attemptMs, outcome, failures: this.failureCount });
+        }
+    }
+    /** An attempt failed without an HTTP answer (or was replaced as stale).
+     * One WARN per streak. */
+    failed(error) {
+        this.failureCount++;
+        if (this.failureCount > 1)
+            return;
+        this.options.logger.warn('bootstrap failed', { reachedServer: false, hidden: !this.options.visible(), error });
+    }
+    /** Resolves true when the next attempt is due (timer, `online`, a return
+     * to visible, or a trigger during the attempt that just failed), false
+     * once stopped. */
+    next() {
+        if (this.stoppedFlag)
+            return Promise.resolve(false);
+        if (this.triggered) {
+            this.triggered = false;
+            return Promise.resolve(true);
+        }
+        const visible = this.options.visible();
+        const delays = this.options.visibleDelaysMs;
+        const delayMs = visible ? delays[Math.min(this.step, delays.length - 1)] : this.options.hiddenDelayMs;
+        if (visible)
+            this.step++;
+        const dueAt = this.options.now() + delayMs;
+        return new Promise((resolve) => {
+            this.wake = resolve;
+            this.waitTimer = this.options.setTimer(() => {
+                this.waitTimer = null;
+                // Late: the device slept or the page was frozen — a phone whose
+                // screen went off with the page in front sends no visibilitychange.
+                // Waking is a return: restart the ladder.
+                if (this.options.now() - dueAt >= LATE_TIMER_MS)
+                    this.step = 0;
+                this.release(true);
+            }, delayMs);
+        });
+    }
+    recovered() {
+        if (this.failureCount > 0) {
+            this.options.logger.info('bootstrap recovered', {
+                failures: this.failureCount,
+                loadingForMs: Math.max(0, this.options.now() - this.startedAt),
+                escalated: this.escalated,
+            });
+        }
+        this.stop();
+    }
+    /** Removes listeners and timers and ends a running wait (`next` → false). */
+    stop() {
+        if (this.stoppedFlag)
+            return;
+        this.stoppedFlag = true;
+        for (const remove of this.removeListeners.splice(0))
+            remove();
+        if (this.escalateTimer !== null)
+            this.options.clearTimer(this.escalateTimer);
+        this.escalateTimer = null;
+        this.release(false);
+    }
+    trigger() {
+        if (this.wake !== null) {
+            this.release(true);
+            return;
+        }
+        const attempt = this.attempt;
+        if (attempt === null)
+            return;
+        this.triggered = true;
+        // Probably hung: on a dead path a request can wait out the OS connect
+        // timeout (minutes), and this trigger says the network or page changed.
+        if (this.options.now() - attempt.startedAt >= this.options.staleAttemptMs)
+            attempt.abort();
+    }
+    release(proceed) {
+        if (this.waitTimer !== null)
+            this.options.clearTimer(this.waitTimer);
+        this.waitTimer = null;
+        const wake = this.wake;
+        this.wake = null;
+        wake?.(proceed);
+    }
+    /** ERROR only once the load has lasted `escalateAfterMs` in view, on time;
+     * re-armed on each return. */
+    armEscalation() {
+        if (this.stoppedFlag || this.escalated || !this.options.visible())
+            return;
+        if (this.escalateTimer !== null)
+            this.options.clearTimer(this.escalateTimer);
+        const armedAt = this.options.now();
+        this.escalateTimer = this.options.setTimer(() => {
+            this.escalateTimer = null;
+            const lateMs = this.options.now() - armedAt - this.options.escalateAfterMs;
+            if (!this.options.visible() || lateMs > ESCALATE_LATE_TOLERANCE_MS)
+                return;
+            this.escalated = true;
+            this.options.logger.error('bootstrap still failing', {
+                failures: this.failureCount,
+                loadingForMs: Math.max(0, this.options.now() - this.startedAt),
+                attemptMs: this.attempt === null ? null : this.options.now() - this.attempt.startedAt,
+            });
+        }, this.options.escalateAfterMs);
+    }
+}

package/package.json

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