browser-broker 0.1.0

package/dist/src/service/refusals.js

@@ -0,0 +1,262 @@
+import { BrokerError } from "../errors.js";
+/**
+ * Every refusal code this build can produce, and the §7 rule behind each.
+ *
+ * Written as an object rather than a list so the union below is the set of
+ * its keys — which means a code that is not in this table does not type-check
+ * at the throw site, and a table entry nothing throws shows up as an unused
+ * key rather than hiding inside an array.
+ */
+export const REFUSALS = {
+    /**
+     * §7.1 `key.present`. Separate from `unrecognised_key` on purpose: a caller
+     * that forgot the key entirely and a caller whose key is wrong need
+     * different sentences, and merging them sends the first one hunting for a
+     * lease that was never the problem.
+     */
+    key_missing: {
+        rule: 'key.present',
+        summary: 'Every operation except requesting a lease carries a key, written out by the caller.',
+        retryable: false,
+    },
+    /**
+     * §7.1 `key.valid`. What a caller gets for a key this store has never seen.
+     */
+    unrecognised_key: {
+        rule: 'key.valid',
+        summary: 'The key matches a lease.',
+        retryable: false,
+    },
+    /**
+     * §7.1 `claim.live`. Names the state it ended in and when, per §2.2 — a
+     * caller told only "no" cannot tell a revoke it should escalate from an
+     * expiry it should simply retry with a fresh lease.
+     */
+    lease_ended: {
+        rule: 'claim.live',
+        summary: 'That lease is queued or active.',
+        retryable: false,
+    },
+    /**
+     * §7.1 `claim.browser_known`, and §2.2's first outright refusal: "nothing
+     * will ever make it valid", which is why waiting is not offered.
+     */
+    unknown_browser: {
+        rule: 'claim.browser_known',
+        summary: 'The browser named is one of the two.',
+        retryable: false,
+    },
+    /**
+     * §7.1 `claim.browser_kind_agrees`. `DECISIONS.md` §13i names two
+     * processes on one machine holding **different configurations** as a real
+     * scenario, and rules that "every disagreement is a nameable refusal
+     * rather than a silently broken invariant" — this is that rule for the one
+     * disagreement `INSERT OR IGNORE` cannot detect on its own: the insert is a
+     * no-op when a row already exists, whatever kind it was created with, so a
+     * name configured `regular` on this process and `private` on the one that
+     * created the row would otherwise be handed a browser of the wrong kind in
+     * silence. Checked immediately after the insert, inside the same
+     * transaction, against the row as it now stands.
+     *
+     * Not retryable: the row's kind does not change by waiting, only by one of
+     * the two processes reconfiguring.
+     */
+    browser_kind_mismatch: {
+        rule: 'claim.browser_kind_agrees',
+        summary: "A browser's stored kind agrees with the kind this process configured it as.",
+        retryable: false,
+    },
+    /**
+     * §7.1 `claim.purpose_bounded`. The bound §1.3 states — three to two
+     * hundred characters, mandatory — checked before a row is written.
+     *
+     * ── Why this row exists at all ──────────────────────────────────────────
+     *
+     * Because until it did, the bound was enforced **only** by the column's
+     * `CHECK (length(purpose) BETWEEN 3 AND 200)`, which is not a refusal: it
+     * is a driver error raised after the statement is handed to the store. On
+     * the command line it left the process with an unhandled `SqliteError` and
+     * exit 1, and on the tool surface it came back as `unexpected_failure`
+     * carrying the constraint text verbatim. Both told a caller the name of a
+     * database constraint instead of the name of the argument they got wrong,
+     * and the first of the two is indistinguishable from the service being
+     * broken — on the first command anybody runs.
+     *
+     * **This is the rule §7.1 was missing rather than a new policy.** §1.3
+     * already made the field mandatory and already fixed the bound; every other
+     * bounded free-text field in the service had its refusal
+     * (`feedback.note_bounded`, `evaluate.expression_bounded`,
+     * `capture.max_tier_reason`) and this one did not. The naming follows those
+     * — `<operation>.<field>_bounded` — rather than starting a second
+     * convention beside them.
+     *
+     * Not retryable: the identical call, with the identical argument, fails
+     * identically forever. What changes it is the caller writing a purpose, not
+     * the caller waiting.
+     */
+    purpose_out_of_bounds: {
+        rule: 'claim.purpose_bounded',
+        summary: 'A claim carries a purpose, three to two hundred characters.',
+        retryable: false,
+    },
+    /**
+     * §1.3's attribution key, absent.
+     *
+     * ── Why this needs a code of its own rather than reusing the purpose's ──
+     *
+     * They are the same *shape* of defect — a surface coerced a missing
+     * argument to the empty string and the service took it — but not the same
+     * refusal, and the rule is looked up here precisely so a code and a rule
+     * cannot drift apart. A caller branching on `purpose_out_of_bounds` would
+     * go and rewrite a purpose that was never wrong.
+     *
+     * ── Why it is not retryable ─────────────────────────────────────────────
+     *
+     * Nothing about waiting supplies an identity the caller did not send
+     * (§2.2). The same reasoning that makes `unknown_browser` permanent applies
+     * unchanged: the request has to be re-made differently, not re-made later.
+     */
+    session_id_missing: {
+        rule: 'claim.session_bounded',
+        summary: 'A claim carries the identity of the session asking for it.',
+        retryable: false,
+    },
+    /**
+     * §5.5.1's last line: the private browser cannot be signed into.
+     *
+     * ── Why this is not `unknown_browser`, which it was at first ────────────
+     *
+     * The private browser **is** one of the two. Refusing it with the code for
+     * a name that does not exist made the command report the rule
+     * `claim.browser_known` — telling a person their browser name was wrong
+     * when it was correct, and pointing them at the one rule that was not the
+     * reason. The message said the right thing and the machine-readable fields
+     * contradicted it, which is worse than either alone: a caller branching on
+     * the rule would conclude it had a typo and retry the same word.
+     *
+     * The rule is looked up here rather than passed by the caller precisely so
+     * that the pair cannot drift — so a refusal that needs a different rule
+     * needs a different code, which is this one.
+     *
+     * Not retryable: the private browser's profile is ephemeral by design, so
+     * no amount of waiting makes signing into it produce anything.
+     */
+    cannot_sign_in: {
+        // §7.1 `browser.serving`, whose entry covers the signing-in cases. The
+        // private browser is not available *to be signed into* — permanently,
+        // which is why this code and `browser_unavailable` share a rule and
+        // differ on the one field a caller acts on.
+        rule: 'browser.serving',
+        summary: 'The browser named keeps a profile that a sign-in can persist in.',
+        retryable: false,
+    },
+    /**
+     * §7.1 `browser.serving`, and §2.2's second: a browser being down is an
+     * availability problem rather than a capacity one, so it is refused rather
+     * than queued — the queue's promise is that capacity frees up, and nothing
+     * about a failed browser promises that.
+     */
+    browser_unavailable: {
+        rule: 'browser.serving',
+        summary: 'The browser is available.',
+        retryable: true,
+    },
+    /**
+     * §7.1 `tab.owned` **and** `tab.open` produce this one code, and the
+     * sharing is the point rather than an economy: §7.1 says outright that an
+     * unowned tab gets "the same refusal as an unknown tab, so probing cannot
+     * discover another lease's tabs". Two rules, two ledger rows, one code — a
+     * caller able to tell them apart is a caller able to enumerate tabs it does
+     * not own.
+     */
+    tab_not_found: {
+        rule: 'tab.owned',
+        summary: 'The tab belongs to this lease and is open.',
+        retryable: false,
+    },
+    /** §7.1 `revoke.reason_required`. An operator taking capacity owes a sentence. */
+    reason_required: {
+        rule: 'revoke.reason_required',
+        summary: 'A revoke carries a reason.',
+        retryable: false,
+    },
+    /**
+     * §7.1 `signin.what_bounded`. What a caller gets for a sign-in request that
+     * does not say what is being signed into.
+     *
+     * ── Why this is not `purpose_out_of_bounds` ─────────────────────────────
+     *
+     * Same shape of defect, different field, and the table's own rule is that a
+     * code and a rule are looked up together precisely so they cannot drift. A
+     * caller branching on `purpose_out_of_bounds` would go and rewrite the
+     * purpose it gave its *claim*, which was never wrong and is not what the
+     * refusal is about.
+     *
+     * ── Why it matters more than an ordinary bound ──────────────────────────
+     *
+     * This is the one free-text field in the service that is **relayed to a
+     * person verbatim by a third party**. Everything else a caller writes is
+     * read by an operator with the ledger in front of them; this is read by
+     * somebody who has been interrupted and told to go and type a password. An
+     * empty one produces a request that reaches a person saying nothing about
+     * what they are signing into, which is a request they cannot act on.
+     *
+     * Not retryable: the identical call with the identical argument fails
+     * identically forever. What changes it is the caller writing a sentence.
+     */
+    sign_in_what_out_of_bounds: {
+        rule: 'signin.what_bounded',
+        summary: 'A sign-in request says what is being signed into, three to two hundred characters.',
+        retryable: false,
+    },
+    /**
+     * Not a §7.1 row, and it is here because the arbitration runner raises it
+     * (`arbitration.ts`). An operation named on a surface that this build does
+     * not register is a caller mistake rather than a crash, and it is the shape
+     * a version mismatch between a caller and this service arrives in.
+     */
+    unknown_operation: {
+        rule: 'arbitration.registered',
+        summary: 'The operation named is one this build registers.',
+        retryable: false,
+    },
+};
+/** The codes as data, for a test that walks them. */
+export const REFUSAL_CODES = Object.keys(REFUSALS);
+/**
+ * A refusal from §7.1 — checked on a call, and the call does not happen.
+ *
+ * Distinct from `StartupRefusal` because the two are acted on differently and
+ * by different code: a startup refusal means this process does not run at
+ * all, and a call refusal means this one call did not, on a process that is
+ * otherwise serving fine. An entry point that could not tell them apart would
+ * either exit the process over a bad argument or carry on over a bad
+ * configuration.
+ *
+ * **The rule is looked up rather than passed.** A caller supplies the code
+ * and the table supplies the rule, so the pair cannot drift and a surface
+ * cannot quietly attribute a refusal to a rule that did not make it.
+ */
+export class CallRefusal extends BrokerError {
+    /** The stable code the caller matches on (§3.14). */
+    code;
+    /** Whether the identical call could succeed later. Read from the table. */
+    retryable;
+    /**
+     * The rest, shaped per refusal — §3.14's "any details". The state a lease
+     * ended in, the position in the queue, the two numbers that disagreed.
+     *
+     * **Not the sentence and not a substitute for it.** The sentence is for a
+     * person and is deliberately worded differently per surface (§3.14); this
+     * is for a caller that has already branched on the code and now needs the
+     * number.
+     */
+    detail;
+    constructor(code, message, options = {}) {
+        super(REFUSALS[code].rule, message, { cause: options.cause });
+        this.name = 'CallRefusal';
+        this.code = code;
+        this.retryable = REFUSALS[code].retryable;
+        this.detail = options.detail ?? {};
+    }
+}

package/dist/src/service/runtime.js

@@ -0,0 +1,131 @@
+import { readEnvironment } from "../config/environment.js";
+import { prepareStore } from "../store/open.js";
+import { ArtifactStore } from "../artifacts/store.js";
+import { browserSessionProvider } from "./browser-session.js";
+import { serviceFor } from "./bridge.js";
+import { createBroker } from "./broker.js";
+/**
+ * Build the service a shipped binary serves, **with a real browser behind it**.
+ *
+ * ── What changed here, and why it is now correct to do it ───────────────
+ *
+ * This function used to supply no session source, and said so at length: a
+ * page verb decided, renewed, checked ownership and wrote its ledger row, and
+ * then moved no page, because there was no page. That was honest and it is now
+ * obsolete. The two reasons it gave have both been answered:
+ *
+ *  1. `act` and `read` are implemented on the real driver, and the directory
+ *     they write into is supplied here from the artifact store rather than
+ *     left to the driver's temporary default.
+ *  2. Attach-against-launch is not decided here at all. It is decided in the
+ *     store, by `decideAdoption`, in the same transaction that arbitrates
+ *     claims — which is where §1.2a puts it. `service/browser-session.ts`
+ *     composes that decision with the driver that performs it.
+ *
+ * **Row #55, settled.** The launch-race loser polls with a ceiling *in this
+ * process* and refuses when it is reached, rather than proceeding as if it
+ * had a browser; see `browser-session.ts` for the argument in full.
+ *
+ * ── Nothing is acquired here, and that is the load-bearing part ─────────
+ *
+ * `browserSessionProvider` returns a **function**, and this hands that
+ * function to the broker. No browser is launched, attached to, or looked for
+ * until a page verb actually needs one, inside an after-commit closure.
+ *
+ * That is what keeps every other path working on a machine with no browser at
+ * all: `claim`, `status`, `release`, `feedback`, `doctor`, every refusal, and
+ * the continuous-integration job that spawns these executables on a runner
+ * where no browser is installed. A build that connected eagerly would make all
+ * of them depend on something most of them never use.
+ *
+ * ── And a browser that cannot be reached is reported, not hidden ────────
+ *
+ * After-commit failures are swallowed by design (§2.4b), so a browser that
+ * fails to launch or dies mid-operation produces no error a caller can see.
+ * What stops that becoming a lie is that `pageDriven` is settled **after** the
+ * work has run rather than predicted before it: the arbitration half is
+ * reported as the `accepted` fact it genuinely is, and the page half is
+ * reported as `false`. See `operations/pages.ts` for why that is a field on an
+ * accepted result rather than a refusal.
+ */
+export async function createRuntime(options) {
+    const environment = readEnvironment({ env: options.env });
+    // **The spawn path, not a hand-assembled equivalent of it.** This used to
+    // open and step inline, which silently omitted the third thing a spawn owes:
+    // `budget.agrees_with_store` (§1.10, §7.2). Both shipped binaries build
+    // their service here, so that omission meant the one value several processes
+    // must agree on was never recorded and never compared in anything that
+    // shipped. `prepareStore` closes the handle itself if any of the three
+    // refuses, so there is no partially-opened store to clean up here.
+    const store = await prepareStore(environment);
+    const artifacts = new ArtifactStore(environment.artifactsRoot);
+    const browsers = browserSessionProvider({
+        store,
+        environment,
+        artifacts,
+        ...(options.driver === undefined ? {} : { driver: options.driver }),
+    });
+    const broker = createBroker({
+        store,
+        environment,
+        adapter: options.adapter,
+        session: browsers.session,
+        artifacts,
+        // The same provider closes the tabs the sweep orphaned. Without one,
+        // `SCHEMA.md` §2.4b's "a leaked tab is not a leaked lease" describes a
+        // permanent state rather than a failure mode: an expired lease's page
+        // stays open for the life of the browser. Reclaiming capacity does not
+        // depend on a browser; reclaiming the page does.
+        closeTab: async (tab) => {
+            const session = await browsers.session(tab.browserId);
+            const opened = await resolveDriverTab(store.db, tab.tabId);
+            if (opened !== undefined) {
+                await session.closeTab({ browser: tab.browserId, driverTabId: opened });
+            }
+        },
+    });
+    let closed = false;
+    return {
+        service: serviceFor({ broker, db: store.db }),
+        broker,
+        store,
+        environment,
+        session: browsers.session,
+        close: () => {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            // **Detaching is deliberately not awaited, and the store is closed
+            // regardless.** `close` is synchronous because its callers are: the
+            // command line closes in a `finally` after one command, and the tool
+            // shim closes when its input stream ends.
+            //
+            // Letting go of a connection is not closing a browser — `real.ts`
+            // measures that attaching and detaching are non-destructive, and a
+            // browser is adopted rather than owned, so a process that exits without
+            // having finished detaching leaves the browser exactly where it was.
+            // The connection dies with the process either way. What must not happen
+            // is the store staying open, and it does not.
+            void browsers.close().catch(() => {
+                // Nothing can act on a failure to let go of a connection.
+            });
+            store.close();
+        },
+    };
+}
+/**
+ * The driver's name for a tab, or nothing if it never had one.
+ *
+ * Read here rather than carried on {@link OrphanedTab} because that type is
+ * the arbitration transaction's, and the driver name is only wanted **after**
+ * the commit, by the one caller that has a browser to ask. A tab that was
+ * never opened has no page, so there is nothing to close and this returns
+ * nothing rather than asking the browser about a page that does not exist.
+ */
+function resolveDriverTab(db, tabId) {
+    const row = db
+        .prepare('SELECT driver_tab_id AS driverTabId FROM tabs WHERE id = ?')
+        .get(tabId);
+    return Promise.resolve(row?.driverTabId ?? undefined);
+}

package/dist/src/service/signin-recovery.js

@@ -0,0 +1,148 @@
+/**
+ * Reclaiming a sign-in whose owner is gone (`SCHEMA.md` §5.5.1).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY THIS EXISTS EVEN THOUGH A SIGNAL HANDLER ALSO EXISTS
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * `broker login` installs a handler that gives the browser back on `SIGINT`
+ * and `SIGTERM`, which covers Ctrl-C — the way a person actually stops a
+ * command that is sitting there waiting. **That handler is not sufficient and
+ * this module is not a belt on top of it.**
+ *
+ * A handler is code the dying process runs, so it covers exactly the deaths
+ * that let a process run code. It does not cover `SIGKILL`, which cannot be
+ * handled by design. It does not cover a power cut, a battery running out, or
+ * a machine being reset. It does not cover the process being killed by an
+ * out-of-memory reaper, and it does not cover a crash in the runtime itself.
+ * In every one of those the browser stays `signing-in` and — before this
+ * module — **stayed that way forever**, refusing every caller and refusing the
+ * second `broker login` that would have ended it, so the only exit was editing
+ * the database by hand.
+ *
+ * So the guarantee is split deliberately, and each half is honest about its
+ * reach:
+ *
+ * - **The handler** returns the browser promptly on an interruption, which is
+ *   the common case and the one where a person is watching.
+ * - **This module** makes the state recoverable when nothing ran at all. It
+ *   asks a question about the world rather than trusting that some earlier
+ *   process did its job.
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY LIVENESS IS ASKED OF THE OWNER, AND WHAT THE ANSWER IS WORTH
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * A sign-in has no expiry (§5.5.1) — a person takes as long as they take, and
+ * a timeout would end a sign-in that was going fine. So there is no lapse for
+ * the lease sweep to notice, and the sweep is not extended to invent one.
+ * The question is settled by evidence instead: **the process that began the
+ * sign-in is either running or it is not.**
+ *
+ * ── The one inference this module draws, and the one it refuses to ──────
+ *
+ * The same discipline `login-command.ts` states for browsers applies here, and
+ * it points the other way round, so it is worth being exact.
+ *
+ * - **A process that does not exist is not signing anybody in.** That is a
+ *   sound negative: `ESRCH` from a zero-signal means no process holds that
+ *   identifier now, and a command that is not running cannot be waiting for a
+ *   person. This is the only conclusion used to reclaim.
+ * - **A process that exists is not evidence the sign-in is live**, because
+ *   process identifiers are reused. This module therefore never reports a
+ *   live owner as proof of anything — it simply declines to reclaim, which is
+ *   the safe direction: the cost of declining is that a person runs one more
+ *   command, and the cost of reclaiming wrongly is a browser taken out from
+ *   under somebody mid-sign-in.
+ *
+ * **Identifier reuse is why the live answer is worth so much less than the
+ * dead one.** A reused identifier can only make this module *more* cautious,
+ * never less: it can turn a dead owner into an apparently-live one and cost a
+ * reclamation, and it cannot turn a live owner into a dead one.
+ *
+ * ── An unknown owner is not a dead owner ────────────────────────────────
+ *
+ * A store written before the owner column existed carries `signing-in` rows
+ * with no owner recorded. Those are reported as **unknown**, never reclaimed:
+ * reclaiming on the strength of a missing record would mean ending a sign-in
+ * because an old build did not write down who started it, which is a guess
+ * dressed as a fact. A person is told what was found and what to do.
+ */
+/**
+ * The real answer: signal zero.
+ *
+ * Signal zero performs the error checking a real signal would and **sends
+ * nothing**, which is the standard way to ask whether an identifier is live
+ * without disturbing what holds it.
+ *
+ * `EPERM` is treated as **alive**, and that is the load-bearing case rather
+ * than a detail: it means a process with that identifier exists and belongs to
+ * somebody this user may not signal. Reading a permission error as "gone"
+ * would reclaim a browser out from under a sign-in that is running perfectly
+ * well under another account — the exact failure this module must not cause,
+ * and the one the caution above is spent on.
+ */
+export function livenessFromSignalError(error) {
+    const code = error?.code;
+    if (code === 'ESRCH') {
+        return false;
+    }
+    // `EPERM` — and anything else this cannot interpret — is read as alive.
+    // **The unsafe direction is concluding "gone"**, so an unrecognised error
+    // never reaches it: a permission error means a process with that identifier
+    // exists and belongs to somebody this user may not signal, and reading that
+    // as gone would reclaim a browser out from under a sign-in running perfectly
+    // well under another account.
+    //
+    // Split out of {@link processIsRunning} so this decision is reachable from a
+    // test. It is the branch a real process cannot be made to produce on demand
+    // — you cannot conjure an `EPERM` from a process you own — and it is the one
+    // whose failure is silent and severe.
+    return true;
+}
+export const processIsRunning = (pid) => {
+    // A non-positive identifier is not a process. Guarded rather than passed
+    // through, because zero and the negatives address process *groups* on a
+    // POSIX system: `kill(0, 0)` asks about the caller's own group and would
+    // answer "alive" about whatever is asking, turning a nonsense value into a
+    // confident wrong answer.
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return livenessFromSignalError(error);
+    }
+};
+/**
+ * Classify a browser row against the world.
+ *
+ * Pure given its liveness function, so every branch is reachable from a test
+ * — including the two that matter most, a dead owner and an unrecorded one,
+ * neither of which can be produced on demand by killing something real.
+ */
+export function classifySignIn(row, isRunning = processIsRunning) {
+    if (row === undefined || row.state !== 'signing-in') {
+        return { kind: 'not-signing-in' };
+    }
+    const pid = row.signin_owner_pid;
+    if (pid === null) {
+        return { kind: 'owner-unknown' };
+    }
+    return isRunning(pid) ? { kind: 'owner-running', pid } : { kind: 'owner-gone', pid };
+}
+/**
+ * What a person is told about a sign-in that cannot be recovered
+ * automatically, and what to do about it.
+ *
+ * Written here rather than at each surface so `doctor` and the refusal a
+ * second `login` produces say the same thing. Two spellings of one remedy is
+ * how they come to disagree, and the disagreement is discovered by somebody
+ * who is already stuck.
+ */
+export const SIGN_IN_OWNER_UNKNOWN_REMEDY = 'This store does not record which process began that sign-in, so it cannot be confirmed abandoned. ' +
+    'If nobody is signing in, run `broker login` — it reclaims a sign-in whose process is gone, and ' +
+    'a sign-in recorded without an owner is left alone rather than ended on a guess.';