@steve31415/baselib 2.1.0 → 2.2.0

package/README.md

@@ -5,8 +5,19 @@ What it provides and why: `docs/SPEC.md`. How it's put together:
 `docs/IMPL.md`. Full design rationale with alternatives:
 `~/migration/research/base-services-design.md` (step 5).
 
-Modules (subpath exports): `config`, `log`, `log-browser`, `rum`, `auth`,
-`s2s`, `db`, `http`.
+Server subpath exports: `config`, `log`, `auth`, `s2s`, `db`, `http`, `sync`,
+and `app-update`. Browser exports: `log-browser`, `rum`, `sync-browser`, and
+`app-update-browser`.
+
+`sync` provides the Postgres event-log and server protocol primitives;
+`sync-browser` provides the IndexedDB outbox and offline-first client.
+`app-update` renders build-aware shells, matches their ETags, and fetches
+retained assets for consumer-owned routes;
+`app-update-browser` detects a new traffic build and reloads when the app's
+injected safety policy permits. Apps inject their domain mutations, state
+adapter, transport/auth-state integration, and update hooks. These modules do
+not decide authentication or ownership, contain app domain logic, or act as a
+generic Yjs or service-worker coordinator.
 
 Bins: `check-test-owners` — the fleet's structural test-coverage gate; every
 app runs it from `npm run verify`.

package/dist/app-update/index.d.ts

@@ -0,0 +1,2 @@
+export * from './shell.js';
+export * from './retained-assets.js';

package/dist/app-update/index.js

@@ -0,0 +1,2 @@
+export * from './shell.js';
+export * from './retained-assets.js';

package/dist/app-update/retained-assets.d.ts

@@ -0,0 +1,21 @@
+export interface AuthenticatedRequester {
+    request(options: {
+        url: string;
+        responseType: 'arraybuffer';
+    }): Promise<{
+        data: ArrayBuffer;
+    }>;
+}
+export interface RetainedAssetStoreOptions {
+    bucketName: string;
+    objectPrefix: string;
+    requester?: AuthenticatedRequester;
+}
+export declare class RetainedAssetStore {
+    private readonly bucketName;
+    private readonly objectPrefix;
+    private readonly requester;
+    constructor(options: RetainedAssetStoreOptions);
+    get(assetPath: string): Promise<Uint8Array | null>;
+}
+export declare function assetContentType(path: string): string;

package/dist/app-update/retained-assets.js

@@ -0,0 +1,51 @@
+// Private GCS archive for hashed assets from prior builds. Current-build
+// assets stay on the revision-local fast path; only a local 404 reaches this
+// store. Consumer HTTP routes remain authenticated and same-origin.
+import { GoogleAuth } from 'google-auth-library';
+export class RetainedAssetStore {
+    bucketName;
+    objectPrefix;
+    requester;
+    constructor(options) {
+        this.bucketName = options.bucketName;
+        this.objectPrefix = options.objectPrefix;
+        this.requester =
+            options.requester ??
+                new GoogleAuth({ scopes: ['https://www.googleapis.com/auth/devstorage.read_only'] });
+    }
+    async get(assetPath) {
+        if (!assetPath || assetPath.split('/').some((part) => !part || part === '.' || part === '..')) {
+            return null;
+        }
+        try {
+            const objectName = `${this.objectPrefix}/${assetPath}`;
+            const bucket = encodeURIComponent(this.bucketName);
+            const object = encodeURIComponent(objectName);
+            const url = `https://storage.googleapis.com/storage/v1/b/${bucket}/o/${object}?alt=media`;
+            const response = await this.requester.request({ url, responseType: 'arraybuffer' });
+            return new Uint8Array(response.data);
+        }
+        catch (error) {
+            const storageError = error;
+            if (storageError.code === 404 || storageError.status === 404 || storageError.response?.status === 404) {
+                return null;
+            }
+            throw error;
+        }
+    }
+}
+export function assetContentType(path) {
+    if (path.endsWith('.js'))
+        return 'text/javascript; charset=utf-8';
+    if (path.endsWith('.css'))
+        return 'text/css; charset=utf-8';
+    if (path.endsWith('.svg'))
+        return 'image/svg+xml';
+    if (path.endsWith('.png'))
+        return 'image/png';
+    if (path.endsWith('.webp'))
+        return 'image/webp';
+    if (path.endsWith('.woff2'))
+        return 'font/woff2';
+    return 'application/octet-stream';
+}

package/dist/app-update/shell.d.ts

@@ -0,0 +1,16 @@
+export interface AppShell {
+    html: string;
+    etag: string;
+    buildId: string;
+}
+export interface LoadAppShellOptions {
+    staticDir: string;
+    app: string;
+    dataset: string;
+    buildId: string;
+    logToken?: string;
+    meta?: ReadonlyArray<readonly [name: string, value: string]>;
+}
+export declare function loadAppShell(opts: LoadAppShellOptions): Promise<AppShell>;
+/** If-None-Match uses weak comparison for GET/HEAD, even for a strong ETag. */
+export declare function etagMatches(header: string | undefined, etag: string): boolean;

package/dist/app-update/shell.js

@@ -0,0 +1,35 @@
+// Production app-shell rendering. The fully rendered bytes are held for the
+// process lifetime by consumers: build identity and logging configuration are
+// revision constants, and a stable body gives browsers a useful strong ETag.
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+function escapeAttribute(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('"', '"')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+}
+export async function loadAppShell(opts) {
+    const metas = [
+        ['pw-log-app', opts.app],
+        ['pw-log-dataset', opts.dataset],
+        ['pw-build-id', opts.buildId],
+        ...(opts.logToken ? [['pw-log-token', opts.logToken]] : []),
+        ...(opts.meta ?? []),
+    ];
+    const renderedMetas = metas
+        .map(([name, value]) => `<meta name="${escapeAttribute(name)}" content="${escapeAttribute(value)}">`)
+        .join('');
+    const source = await readFile(`${opts.staticDir}/index.html`, 'utf8');
+    const html = source.replace('</head>', `${renderedMetas}</head>`);
+    const digest = createHash('sha256').update(html).digest('base64url');
+    return { html, etag: `"${digest}"`, buildId: opts.buildId };
+}
+/** If-None-Match uses weak comparison for GET/HEAD, even for a strong ETag. */
+export function etagMatches(header, etag) {
+    if (!header)
+        return false;
+    const normalize = (value) => value.trim().replace(/^W\//, '');
+    return header.split(',').some((candidate) => candidate.trim() === '*' || normalize(candidate) === etag);
+}

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

@@ -0,0 +1,52 @@
+import type { Logger } from '../log-browser.js';
+import type { ReloadSafety } from './reload-safety.js';
+export type BuildUpdateState = {
+    kind: 'current';
+} | {
+    kind: 'available';
+    buildId: string;
+} | {
+    kind: 'reloading';
+    buildId: string;
+};
+export interface BuildUpdateDeps {
+    currentBuildId: string;
+    safety: ReloadSafety;
+    logger: Pick<Logger, 'info' | 'warn'>;
+    fetchFn?: (input: string, init?: RequestInit) => Promise<Response>;
+    reload?: () => void;
+    pollMs?: number;
+    onTrafficBuildChange?: (buildId: string) => void;
+}
+export declare function pageBuildId(): string;
+export declare class BuildUpdateMonitor {
+    private deps;
+    private state;
+    private listeners;
+    private interval;
+    private stopSafety;
+    private started;
+    private lifecycle;
+    private requestNumber;
+    private appliedRequestNumber;
+    private trafficBuild;
+    private checkFailure;
+    constructor(deps: BuildUpdateDeps);
+    getState: () => BuildUpdateState;
+    subscribe: (listener: () => void) => (() => void);
+    start(): void;
+    stop(): void;
+    /** Additive sync-protocol observation. It can mark stale but cannot cancel
+     *  an update because an old socket does not define current traffic. */
+    observeSocketBuild(buildId: string): void;
+    /** 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;
+    checkNow(): Promise<void>;
+    private observeTrafficBuild;
+    private markAvailable;
+    private maybeReload;
+    private setState;
+    private onVisibility;
+    private onOnline;
+}

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

@@ -0,0 +1,161 @@
+// Long-lived-tab build pickup. HTTP says which revision owns new traffic;
+// sync observations are an opportunistic second signal. Reload policy is
+// separate and injected through ReloadSafety.
+const DEFAULT_POLL_MS = 5 * 60 * 1000;
+const LEGACY_BUILD = 'legacy-pre-build-id';
+export function pageBuildId() {
+    return document.querySelector('meta[name="pw-build-id"]')?.content || 'development';
+}
+export class BuildUpdateMonitor {
+    deps;
+    state = { kind: 'current' };
+    listeners = new Set();
+    interval = null;
+    stopSafety = null;
+    started = false;
+    lifecycle = 0;
+    requestNumber = 0;
+    appliedRequestNumber = 0;
+    trafficBuild = null;
+    checkFailure = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    getState = () => this.state;
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.lifecycle += 1;
+        this.stopSafety = this.deps.safety.subscribe(() => this.maybeReload());
+        this.interval = setInterval(() => {
+            if (document.visibilityState === 'visible')
+                void this.checkNow();
+        }, this.deps.pollMs ?? DEFAULT_POLL_MS);
+        document.addEventListener('visibilitychange', this.onVisibility);
+        window.addEventListener('online', this.onOnline);
+        void this.checkNow();
+    }
+    stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        this.lifecycle += 1;
+        if (this.interval)
+            clearInterval(this.interval);
+        this.interval = null;
+        this.stopSafety?.();
+        this.stopSafety = null;
+        document.removeEventListener('visibilitychange', this.onVisibility);
+        window.removeEventListener('online', this.onOnline);
+    }
+    /** Additive sync-protocol observation. It can mark stale but cannot cancel
+     *  an update because an old socket does not define current traffic. */
+    observeSocketBuild(buildId) {
+        if (buildId && buildId !== this.deps.currentBuildId)
+            this.markAvailable(buildId);
+    }
+    /** 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 this.checkNow();
+    }
+    async checkNow() {
+        if (!navigator.onLine)
+            return;
+        const lifecycle = this.lifecycle;
+        const requestNumber = ++this.requestNumber;
+        try {
+            const response = await (this.deps.fetchFn ?? fetch)('/api/build', {
+                cache: 'no-store',
+                headers: { accept: 'application/json' },
+            });
+            if (!response.ok)
+                throw new Error(`build check failed: ${response.status}`);
+            const contentType = response.headers.get('content-type') ?? '';
+            let buildId;
+            if (contentType.includes('application/json')) {
+                const body = (await response.json());
+                if (typeof body.buildId !== 'string' || !body.buildId) {
+                    throw new Error('build check returned no build ID');
+                }
+                buildId = body.buildId;
+            }
+            else if (contentType.includes('text/html')) {
+                buildId = LEGACY_BUILD;
+            }
+            else {
+                throw new Error(`unexpected build response: ${contentType || 'no content type'}`);
+            }
+            if (lifecycle !== this.lifecycle || requestNumber < this.appliedRequestNumber)
+                return;
+            this.appliedRequestNumber = requestNumber;
+            if (this.checkFailure) {
+                this.checkFailure = false;
+                this.deps.logger.info('build check recovered');
+            }
+            this.observeTrafficBuild(buildId);
+        }
+        catch (error) {
+            if (lifecycle !== this.lifecycle ||
+                requestNumber < this.appliedRequestNumber ||
+                !navigator.onLine)
+                return;
+            if (!this.checkFailure) {
+                this.checkFailure = true;
+                this.deps.logger.warn('build check failed', { error });
+            }
+        }
+    }
+    observeTrafficBuild(buildId) {
+        const prior = this.trafficBuild;
+        this.trafficBuild = buildId;
+        if (buildId !== prior && (prior !== null || buildId !== this.deps.currentBuildId)) {
+            this.deps.onTrafficBuildChange?.(buildId);
+        }
+        if (buildId === this.deps.currentBuildId) {
+            if (this.state.kind === 'available')
+                this.setState({ kind: 'current' });
+            return;
+        }
+        this.markAvailable(buildId);
+    }
+    markAvailable(buildId) {
+        if (this.state.kind === 'reloading')
+            return;
+        if (this.state.kind !== 'available' || this.state.buildId !== buildId) {
+            this.deps.logger.info('new build observed', {
+                pageBuildId: this.deps.currentBuildId,
+                observedBuildId: buildId,
+            });
+            this.setState({ kind: 'available', buildId });
+        }
+        this.maybeReload();
+    }
+    maybeReload() {
+        if (this.state.kind !== 'available' || !this.deps.safety.isSafe())
+            return;
+        const buildId = this.state.buildId;
+        this.setState({ kind: 'reloading', buildId });
+        if (this.deps.reload)
+            this.deps.reload();
+        else
+            location.reload();
+    }
+    setState(state) {
+        this.state = state;
+        for (const listener of this.listeners)
+            listener();
+    }
+    onVisibility = () => {
+        if (document.visibilityState === 'visible')
+            void this.checkNow();
+    };
+    onOnline = () => {
+        void this.checkNow();
+    };
+}

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

@@ -0,0 +1,2 @@
+export * from './reload-safety.js';
+export * from './build-update.js';

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

@@ -0,0 +1,2 @@
+export * from './reload-safety.js';
+export * from './build-update.js';

package/dist/app-update-browser/reload-safety.d.ts

@@ -0,0 +1,8 @@
+export declare class ReloadSafety<T extends string = string> {
+    private blockers;
+    private listeners;
+    isSafe: () => boolean;
+    has: (blocker: T) => boolean;
+    set(blocker: T, blocked: boolean): void;
+    subscribe: (listener: () => void) => (() => void);
+}

package/dist/app-update-browser/reload-safety.js

@@ -0,0 +1,23 @@
+// One authority for controlled page reloads. Producers own named blockers;
+// the update monitor only asks whether the aggregate is safe.
+export class ReloadSafety {
+    blockers = new Set();
+    listeners = new Set();
+    isSafe = () => this.blockers.size === 0;
+    has = (blocker) => this.blockers.has(blocker);
+    set(blocker, blocked) {
+        const changed = blocked ? !this.blockers.has(blocker) : this.blockers.has(blocker);
+        if (!changed)
+            return;
+        if (blocked)
+            this.blockers.add(blocker);
+        else
+            this.blockers.delete(blocker);
+        for (const listener of this.listeners)
+            listener();
+    }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+}

package/dist/sync/broadcaster.d.ts

@@ -0,0 +1,9 @@
+export declare class ScopeBroadcaster<T> {
+    private readonly listeners;
+    subscribe(scopeKey: string, send: (message: T) => void): () => void;
+    /** Deliver to every matching listener in subscription order. Throwing
+     * listeners are detached immediately, but their errors are reported only
+     * after the remaining listeners have received the message. */
+    publish(scopeKey: string, message: T, except?: (message: T) => void): void;
+    count(scopeKey: string): number;
+}

package/dist/sync/broadcaster.js

@@ -0,0 +1,47 @@
+export class ScopeBroadcaster {
+    listeners = new Map();
+    subscribe(scopeKey, send) {
+        let scopeListeners = this.listeners.get(scopeKey);
+        if (!scopeListeners) {
+            scopeListeners = new Set();
+            this.listeners.set(scopeKey, scopeListeners);
+        }
+        scopeListeners.add(send);
+        return () => {
+            scopeListeners.delete(send);
+            if (scopeListeners.size === 0 && this.listeners.get(scopeKey) === scopeListeners) {
+                this.listeners.delete(scopeKey);
+            }
+        };
+    }
+    /** Deliver to every matching listener in subscription order. Throwing
+     * listeners are detached immediately, but their errors are reported only
+     * after the remaining listeners have received the message. */
+    publish(scopeKey, message, except) {
+        const scopeListeners = this.listeners.get(scopeKey);
+        if (!scopeListeners)
+            return;
+        const errors = [];
+        for (const listener of scopeListeners) {
+            if (listener === except)
+                continue;
+            try {
+                listener(message);
+            }
+            catch (error) {
+                scopeListeners.delete(listener);
+                errors.push(error);
+            }
+        }
+        if (scopeListeners.size === 0 && this.listeners.get(scopeKey) === scopeListeners) {
+            this.listeners.delete(scopeKey);
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, 'scope broadcast failed');
+    }
+    count(scopeKey) {
+        return this.listeners.get(scopeKey)?.size ?? 0;
+    }
+}

package/dist/sync/engine.d.ts

@@ -0,0 +1,55 @@
+import type pg from 'pg';
+import type { Logger } from '../log.js';
+import type { EventLogSchema } from './schema.js';
+import { type ClientEvent, type EventBody, type PreparedEvent, type SyncEvent } from './types.js';
+export type MutationPreparer<C extends EventBody, S extends EventBody> = (client: pg.PoolClient, scopeKey: string, event: ClientEvent<C>) => Promise<PreparedEvent<S>[]>;
+export interface EventLogEngineOptions<C extends EventBody, S extends EventBody> {
+    pool: pg.Pool;
+    logger: Logger;
+    prepareMutation: MutationPreparer<C, S>;
+    schema?: EventLogSchema;
+    catchupLimit?: number;
+    retentionDays?: number;
+    randomGuid?: () => string;
+    now?: () => number;
+}
+export type ApplyOutcome<S extends EventBody> = {
+    kind: 'applied';
+    events: SyncEvent<S>[];
+} | {
+    kind: 'duplicate';
+    event: SyncEvent<S>;
+} | {
+    kind: 'rejected';
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export type CatchupOutcome<S extends EventBody> = {
+    kind: 'events';
+    events: SyncEvent<S>[];
+    currentSeq: number;
+} | {
+    kind: 'reload';
+};
+export declare class EventLogEngine<C extends EventBody, S extends EventBody> {
+    private readonly pool;
+    private readonly logger;
+    private readonly prepareMutation;
+    private readonly schema;
+    private readonly catchupLimit;
+    private readonly retentionDays;
+    private readonly randomGuid;
+    private readonly now;
+    constructor(options: EventLogEngineOptions<C, S>);
+    /** Apply one event. Domain validation failures are stable rejections; an
+     * unexpected failure is retried once because event GUID dedupe makes an
+     * ambiguous commit safe to replay. */
+    apply(scopeKey: string, clientGuid: string | null, event: ClientEvent<C>): Promise<ApplyOutcome<S>>;
+    private rejectedOutcome;
+    private applyOnce;
+    currentSeq(scopeKey: string): Promise<number>;
+    catchup(scopeKey: string, afterSeq: number): Promise<CatchupOutcome<S>>;
+    pruneOldEvents(): Promise<number>;
+}