@tinycloud/courier 0.1.6-beta.9 → 0.2.0-beta.32

package/dist/watch.d.ts

@@ -0,0 +1,140 @@
+import type { HookSubscription } from '@tinycloud/node-sdk';
+import type { StoredPeer } from './profile.js';
+import { type KV } from './inbox.js';
+import type { WakeMessage, Waker, WatchLog } from './wake.js';
+export interface PendingWake {
+    peer: string;
+    threadId: string;
+    subject: string;
+    messages: WakeMessage[];
+    firstSeenAt: number;
+    lastSeenAt: number;
+}
+export interface WatchState {
+    v: 1;
+    /** Keyed `<peer>/<threadId>`. */
+    pending: Record<string, PendingWake>;
+    /** Recently woken message ids, so a receipt write that failed cannot cause a second wake. */
+    woken: string[];
+    approvalsSeen: string[];
+}
+export interface WatchOptions {
+    debounceMs: number;
+    pollMs: number;
+    ticketSeconds: number;
+}
+export declare const WATCH_DEFAULTS: WatchOptions;
+interface HookEventLike {
+    path?: string;
+}
+interface HooksLike {
+    subscribe(subscriptions: HookSubscription[], options: {
+        ttlSeconds: number;
+        signal: AbortSignal;
+    }): AsyncIterable<HookEventLike>;
+}
+export interface WatchDeps {
+    selfKv: KV;
+    /** Own space id, for the `me/approvals/` subscription. */
+    spaceId: string;
+    /** The owner's own space. */
+    selfHooks: HooksLike;
+    /** A peer's space, through the peer delegation (each peer streams independently: one refused scope must not stall the rest). */
+    peerHooks(peer: StoredPeer): Promise<HooksLike>;
+    /** Fresh peer list each call (pairing and renewals change the profile under a running watcher). */
+    loadPeers(): StoredPeer[];
+    kvFor(peer: StoredPeer): Promise<KV>;
+    wake: Waker;
+    log: WatchLog;
+    /**
+     * Who this watcher is, for wake claims. `profileId` is stable for this profile on this machine (a restart keeps it,
+     * a second profile or machine differs); `pid` and `isAlive` tell a restarted watcher its predecessor is dead.
+     */
+    holder?: {
+        profileId: string;
+        pid?: number;
+        isAlive?(pid: number): boolean;
+    };
+    now?(): number;
+}
+type Via = 'startup' | 'hook' | 'poll';
+export declare function emptyWatchState(): WatchState;
+/** Wake time: `debounce` after the latest message, but never later than twice `debounce` after the first. */
+export declare function wakeDueAt(pending: PendingWake, debounceMs: number): number;
+export declare function sentAtOf(messageId: string): string;
+export declare class Watcher {
+    private readonly deps;
+    private readonly opts;
+    private state;
+    private readonly retryAt;
+    private readonly waking;
+    /** Unique to this run: a claim with this id is this process's own. */
+    private readonly runId;
+    private readonly profileId;
+    private readonly pid;
+    private readonly isAlive;
+    private lastClaimPrune;
+    /** Set when another watcher is writing this profile's state: this one stops and `run` throws it. */
+    private fatalError;
+    private onFatal;
+    /** Etag of me/state/watch.json as this watcher last saw it: null = absent, undefined = unknown (fetch before writing). */
+    private stateEtag;
+    private readonly taskCache;
+    private readonly metaMirrored;
+    private readonly syncing;
+    private stateQueue;
+    private readonly now;
+    constructor(deps: WatchDeps, opts?: WatchOptions);
+    loadState(): Promise<void>;
+    snapshot(): WatchState;
+    /**
+     * Serialised: callers mutate `this.state` inside `fn`, then it is written with if-match against the etag this
+     * watcher last saw. A second `watch` on the same profile therefore fails with `state-conflict` instead of
+     * silently overwriting (last writer wins) the other's pending wakes.
+     */
+    private mutate;
+    /** Another watcher owns this profile's state. Carrying on would double-wake and overwrite its pending wakes: stop. */
+    private stateConflict;
+    /**
+     * One create-only marker per wake (keyed by the first message or approval it carries), so a second watcher that
+     * runs while this one's wake is in flight cannot wake the same thing. The marker names its holder
+     * (`profile`, `run`, `pid`):
+     *   - this run's own marker: reuse it;
+     *   - same profile and machine, holder pid gone or equal to ours (restart, crash, reboot, pid 1 in a container): take it over at once;
+     *   - same profile and machine, holder pid alive and different: another watcher is running now: skip the thread (the
+     *     state etag stops the loser when it writes state), unless the claim outlived the own lease (pid reuse);
+     *   - another profile or machine: skip until the lease (plus clock-skew margin) runs out, then take it over.
+     * Returns false when the thread must be skipped this tick. Markers are deleted when the adapter fails.
+     */
+    private claimWake;
+    /** Drops this run's own claim (best effort): a failed wake must not keep the thread from being woken. */
+    private releaseClaim;
+    /** Claim markers are only needed while a double wake is possible; drop those older than two days. */
+    private pruneClaims;
+    /** Serialises syncs per peer; a request that arrives mid-sync reruns once after it. */
+    sync(peer: StoredPeer, via: Via): Promise<void>;
+    private syncPeer;
+    private mirrorCreate;
+    /**
+     * meta.json is immutable (create-only); tasks are mutable, so copy the latest until they are terminal. Runs after
+     * message delivery and each item is isolated: a bad or unwritable peer task never blocks receipts or wakes.
+     */
+    private mirrorThreads;
+    private mirrorThreadItem;
+    /** Own `me/approvals/`: record new decisions (the wake on them is added with `courier approval`). */
+    syncApprovals(via: Via): Promise<string[]>;
+    /** Wake every thread whose debounce has elapsed (`force`: all of them now). Threads wake in parallel, one wake per thread at a time. */
+    tick(force?: boolean): Promise<void>;
+    private wakeThread;
+    pollOnce(via: Via): Promise<void>;
+    /**
+     * Runs until `signal` aborts. With `once`, does one catch-up and wakes everything immediately. Throws
+     * `state-conflict` (after stopping everything) if another watcher is writing this profile's state.
+     */
+    run(external: AbortSignal, options?: {
+        once?: boolean;
+    }): Promise<void>;
+    /** One hook subscription. A refused ticket (revoked or expired delegation) backs off; the poll covers meanwhile. */
+    private supervise;
+}
+export {};