@parall/daemon 1.36.1 → 1.37.0

package/dist/clip-runtime/browser-profile-pool.d.ts

@@ -0,0 +1,250 @@
+import { type BrowserInvokeRequest, type BrowserInvoker, type BrowserProfileManagerOptions, type BrowserProfileStatus } from './browser-profile-manager.js';
+import type { ViewerTurnConfig } from './browser-viewer-streamer.js';
+/**
+ * The subset of BrowserProfileManager the pool drives. Extracted so tests can
+ * inject a fake runtime — the real manager spawns bb-browser + Chromium on the
+ * first command, which a unit test must not do — via
+ * {@link BrowserProfilePoolOptions.createManager}.
+ */
+export interface BrowserProfileRuntime {
+    invoke(request: BrowserInvokeRequest): Promise<unknown>;
+    ensureRuntime(profileId: string, opts?: {
+        forceStatusReport?: boolean;
+    }): Promise<void>;
+    openProfile(profileId: string, startUrl?: string): Promise<void>;
+    handleViewerCommand(profileId: string, sessionId: string, command: string, input?: Record<string, unknown>, turn?: ViewerTurnConfig): Promise<Record<string, unknown>>;
+    stopProfile(profileId: string): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface BrowserProfilePoolOptions {
+    /** Parent dir under which each profile gets its own `<baseHomeDir>/<profileId>` home. */
+    baseHomeDir: string;
+    log: BrowserProfileManagerOptions['log'];
+    /** Report a profile's status to the server. Unlike the manager's 3-arg callback,
+     *  the pool's carries the lifecycle generation the op was acting under (PR #1650),
+     *  so the server can reject a stale report. The pool injects the generation for
+     *  manager-driven reports (it owns the per-op generation); supervisor passes it
+     *  straight to client.reportBrowserProfileStatus. */
+    reportStatus?: (profileId: string, status: BrowserProfileStatus, errorMsg?: string, generation?: number) => void;
+    /** Per-profile outbound proxy resolver (#1642), threaded to each profile's
+     *  manager so its isolated Chromium binds its own egress proxy at account_create. */
+    resolveProxy?: BrowserProfileManagerOptions['resolveProxy'];
+    /**
+     * Per-profile runtime factory. Defaults to a real {@link BrowserProfileManager};
+     * overridable in tests to avoid spawning a real bb-browser / Chromium.
+     */
+    createManager?: (opts: BrowserProfileManagerOptions) => BrowserProfileRuntime;
+}
+/**
+ * BrowserProfilePool — true per-profile isolation for the BYOC daemon supervisor.
+ *
+ * WHY THIS EXISTS. A single bb-browser/Chromium shared across profiles isolates
+ * only at the bb-browser "account" (CDP BrowserContext) level. That is real for
+ * cookies/storage, but bb-browser's COMMAND routing is account-blind: any command
+ * issued without an explicit tabId falls through to a single GLOBAL current tab
+ * (cdp.currentTargetId, else targets[0]) regardless of the `account` field
+ * (bb-browser-pro daemon.js ensurePageTarget). So when the global current tab
+ * belongs to profile A, a command meant for profile B executes in A's context —
+ * e.g. logging into a second account overwrites the first, and two profiles can
+ * never hold two different sessions at once (reproduced on a real Chrome).
+ *
+ * THE FIX. Give every profile its OWN bb-browser daemon + Chromium + on-disk home
+ * (`<baseHomeDir>/<profileId>`). Each Chromium then hosts exactly one profile, so
+ * there is no cross-profile global tab to leak into — isolation is enforced by the
+ * OS process + user-data-dir boundary, not by remembering to scope every command.
+ * The pool owns one {@link BrowserProfileManager} per profile and routes by
+ * profileId; an idle (stopped) profile holds no Chromium, so cost scales with the
+ * number of CONCURRENTLY-OPEN profiles, not the number that ever existed.
+ *
+ * NOT used by the hosted browser pod (`browser-pod.ts`): a pod serves exactly one
+ * profile, so it keeps using a single BrowserProfileManager directly (and its
+ * BrowserStateStore snapshots that manager's flat homeDir to S3 — the pool's
+ * per-profile nesting would break that). The pool is supervisor-only.
+ *
+ * OWNERSHIP. The pool is a per-profile runtime REGISTRY + the per-profile mutex
+ * (create / stop / list-active / invoke / viewer, serialized via `enqueue()`). The
+ * DESIRED-STATE coordinator is the supervisor: the server (clip-service) is the
+ * SSOT for which profiles should be live, and `DaemonSupervisor.reconcileBrowserProfiles`
+ * converges the local registry to it (open/ensure desired, stop the rest via
+ * `activeProfileIds()`). The pool keeps one bit of lifecycle policy — the `stopped`
+ * fence — because invoke (hub channel) and viewer funnel through it and must reject
+ * a stale command without a server round-trip.
+ */
+export declare class BrowserProfilePool implements BrowserInvoker {
+    private readonly opts;
+    private readonly managers;
+    private readonly opChains;
+    private readonly stopped;
+    private readonly stopSeq;
+    private readonly generations;
+    private readonly opGeneration;
+    private stopping;
+    constructor(opts: BrowserProfilePoolOptions);
+    /** Inbound hub browser invoke for a profile — routed to that profile's own daemon. */
+    invoke(request: BrowserInvokeRequest): Promise<unknown>;
+    private runWithGeneration;
+    /**
+     * Reconcile-time: ensure the profile's runtime (account + tab) is live. If
+     * `sinceSeq` (the fence generation observed when this op was enqueued) is given
+     * and a newer stop has been observed since, skip — a stale reconcile/open queued
+     * before a stop must not un-fence and revive a profile about to be torn down
+     * (the pending stop wins; last-write-wins).
+     */
+    ensureRuntime(profileId: string, sinceSeq?: number, generation?: number, opts?: {
+        forceStatusReport?: boolean;
+    }): Promise<void>;
+    /** Lifecycle `open` — open (or reuse) the profile's start tab. `sinceSeq`: see ensureRuntime. */
+    openProfile(profileId: string, startUrl?: string, sinceSeq?: number, generation?: number): Promise<void>;
+    /** True if a newer stop was observed after this revive captured `sinceSeq`. */
+    private isStaleRevive;
+    /** Live-viewer control command for a profile — routed to its own daemon/streamer. */
+    handleViewerCommand(profileId: string, sessionId: string, command: string, input?: Record<string, unknown>, turn?: ViewerTurnConfig): Promise<Record<string, unknown>>;
+    /**
+     * Lifecycle `stop` (explicit, owner-driven) — stop the profile's viewer + tear
+     * down its bb-browser daemon and Chromium to free the resources (an idle profile
+     * must not keep a browser running). Confirms `stopped` back to the server: the
+     * stop API already set the server row to `stopped`, and this report keeps the
+     * daemon authoritative over the actual runtime state (the no-runtime case still
+     * confirms). For reconcile-driven cleanup of profiles the server no longer owns
+     * here, use {@link releaseRuntime} — it must NOT report.
+     */
+    stopProfile(profileId: string, generation?: number): Promise<void>;
+    /**
+     * Reconcile teardown (negative convergence) — release a local runtime the server
+     * no longer lists as live on this machine (stopped / deleted / reassigned).
+     * Fences + disposes like a stop, but does NOT report status: here the server is
+     * the desired-state SSOT, so a daemon-side `stopped` push is semantically wrong
+     * (for a profile reassigned to another machine it isn't ours to report — the
+     * server's machine-binding check rejects it as 404 anyway) and only emits
+     * spurious calls. Local-only cleanup.
+     */
+    releaseRuntime(profileId: string): Promise<void>;
+    /**
+     * Synchronously fence a profile (reject late invoke/viewer until an explicit
+     * reopen) WITHOUT tearing anything down. The supervisor calls this the moment a
+     * stop/reset lifecycle event is received, before the queued stop/reset op runs:
+     * a hub invoke — which bypasses the supervisor queue and hits {@link invoke}
+     * directly — authorized just before the server row flipped to `stopped` could
+     * otherwise arrive in that window and spawn a transient Chromium the stop then
+     * immediately tears down. Fencing now rejects it instead. An in-flight invoke
+     * already past the fence check is unaffected (the queued stop serializes behind
+     * it); open/ensure clears the fence. Idempotent; no-op once stopping.
+     */
+    fence(profileId: string): void;
+    /** The current fence generation for a profile — captured by a revive at enqueue. */
+    stopSeqOf(profileId: string): number;
+    /**
+     * Lifecycle `reset` — wipe the profile's persisted state (cookies, localStorage,
+     * IndexedDB, cache) for a clean slate. Removes BOTH the per-profile home AND any
+     * unmigrated legacy flat cookie file — a reset done before the profile's first
+     * post-upgrade open would otherwise leave the legacy file in place, and the lazy
+     * migration would re-import the old login on the next open, silently undoing the
+     * reset. Done AFTER the daemon is stopped so Chromium has released its files.
+     * Isolated by construction — it can never touch another profile's state.
+     * Fail-closed: if the wipe fails (e.g. Chromium still holds a file, or a
+     * permission error), report `error` and throw rather than report `stopped` —
+     * a reset that left state on disk must not be marked clean, since the next open
+     * could restore the old login. Reports `stopped` only on a confirmed wipe.
+     */
+    resetProfile(profileId: string, generation?: number, resetGeneration?: number): Promise<void>;
+    /**
+     * Apply a reset the daemon hasn't yet (caught on reconnect when the server's
+     * reset_generation is newer than this daemon's recorded one). Same wipe as
+     * resetProfile but WITHOUT a status report — the caller drives desired state (an
+     * open/ensure reports running for a still-desired profile; a stopped profile is
+     * left stopped). Must run BEFORE any open/ensure for the profile so a reopen starts
+     * from clean state, never the old cookies (the supervisor enqueues it first).
+     */
+    applyResetWipe(profileId: string, resetGeneration: number): Promise<void>;
+    private doResetWipe;
+    /**
+     * Reconnect cleanup for a profile the server no longer lists AT ALL (deleted or
+     * reassigned away): dispose any runtime and wipe the per-profile home — the old host
+     * must not keep its cookies/storage. NO status report (the server is the SSOT and the
+     * row is gone there); fences too. Idempotent (a wiped home simply isn't found again).
+     */
+    wipeAbsent(profileId: string): Promise<void>;
+    /**
+     * Tear down every profile's daemon (supervisor shutdown). TERMINAL: the
+     * supervisor discards the pool after this, so `stopping` stays set forever —
+     * manager() refuses any further op. Drain outstanding per-profile chains BEFORE
+     * clearing the maps, so a queued op whose `prev` settles only after stop()
+     * returns can't slip through manager() and recreate a runtime (orphaning a
+     * Chromium past shutdown); `stopping` is the backstop if one still races in.
+     */
+    stop(): Promise<void>;
+    /**
+     * Registry view: profile ids that currently hold a live local runtime. The
+     * supervisor (the desired-state coordinator) diffs this against the server's
+     * desired-live set on full reconcile and stops the extras via stopProfile() —
+     * the convergence policy lives there, not here; the pool only owns runtime
+     * lifecycle mechanics.
+     */
+    activeProfileIds(): string[];
+    /**
+     * Run `op` after every prior operation for this profile settles — a per-profile
+     * serialization so invoke / open / stop / reset / viewer never interleave for
+     * one profile (different profiles still run in parallel). Bounded: bb-browser
+     * commands time out (~30s), so a stop never waits forever behind a hung invoke.
+     * Also normalizes a synchronous throw from `op` into a rejected promise.
+     *
+     * QUEUE CONTRACT. This is the FINAL per-profile mutex — EVERY pool entrypoint
+     * (invoke, open, ensure, stop, reset, viewer) goes through it, so it alone
+     * guarantees per-profile mutual exclusion. The supervisor's separate
+     * `enqueueBrowserProfileOp` is a higher-level ORDERING layer for the ops it
+     * originates (WS lifecycle/viewer events + reconcile), not a second mutex. Hub
+     * invokes arrive from the clip runtime and do NOT pass through the supervisor
+     * queue — only this one. So: do not assume "all profile ops share one queue";
+     * they share THIS one.
+     */
+    private enqueue;
+    /**
+     * Get (or lazily create) the dedicated manager for a profile. Synchronous so the
+     * get-or-create is atomic — the bb-browser daemon itself starts lazily on first
+     * command, not here.
+     */
+    private manager;
+    /** Stop a manager and drop it from the map (identity-checked so a concurrent
+     *  recreate during the async stop is never evicted). */
+    private dispose;
+    private profileHome;
+    /** Legacy shared-layout cookie file for a profile (pre per-profile homes). */
+    private legacyAccountFile;
+    /**
+     * Remove every on-disk trace of a profile: its per-profile home AND any
+     * unmigrated legacy flat cookie file — otherwise a later open would re-import
+     * the legacy cookies (see resetProfile). Throws if any target could not be
+     * removed so the caller can fail the reset closed rather than report a clean
+     * slate while state survives on disk.
+     */
+    private removeProfileState;
+    private metaFile;
+    /** The reset_generation this daemon has applied for the profile (0 if unknown). */
+    appliedResetGeneration(profileId: string): number;
+    private writeResetGeneration;
+    /**
+     * Profile ids that have ANY local state on this host — the reconcile's inventory for
+     * finding deleted/reassigned profiles whose residue must be wiped. Union of the two
+     * storage layouts this pool owns:
+     *   - per-profile home dirs      `<baseHomeDir>/brp_*`
+     *   - legacy flat account files  `<baseHomeDir>/accounts/brp_*.json` (pre per-profile
+     *     homes; a profile deleted before its first post-upgrade reopen has ONLY this file
+     *     and no home dir, so home-only enumeration would miss its login residue)
+     * Only names passing the strict brp_ check are returned, and the two layouts are
+     * deduped, so reconnect cleanup never touches the `accounts/` dir itself, a hidden
+     * dir, `legacy.json`, or any non-profile entry. removeProfileState wipes both layouts.
+     */
+    localStateProfileIds(): string[];
+    /**
+     * One-time, lazy migration from the legacy shared layout. Before per-profile
+     * homes, all profiles shared one bb-browser home and bb-browser persisted each
+     * profile's cookies to `<baseHomeDir>/accounts/<profileId>.json` (account name =
+     * profileId). Move that file into the profile's own `accounts/` dir on first use
+     * so existing cookie logins survive the upgrade instead of forcing a re-login.
+     * Only cookies are migrated — the shared `chrome-data/` was a single comingled
+     * Chromium profile that cannot be split per profile, and bb-browser never
+     * persisted localStorage/IndexedDB across restarts anyway.
+     */
+    private migrateFlatProfileState;
+}
+//# sourceMappingURL=browser-profile-pool.d.ts.map

package/dist/clip-runtime/browser-profile-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-profile-pool.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/browser-profile-pool.ts"],"names":[],"mappings":"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"}