browser-broker 0.1.0

package/dist/src/service/queue.js

@@ -0,0 +1,233 @@
+import { randomUUID } from 'node:crypto';
+import { admits, countActiveClaims } from "./capacity.js";
+import { append } from "./events.js";
+/**
+ * The queue: strictly first in, first out (§1.5, §2.5).
+ *
+ * **There is no queue table.** The queue is simply the leases whose state is
+ * `queued`, in the order they arrived. §1.5 argues the alternative looks
+ * tidier and is worse: a queue table means a waiting lease exists twice, once
+ * as a lease and once as an entry, and the moment the two disagree the
+ * service has two answers to *"where am I"*. Admission is one field changing
+ * on the row that was already there, which cannot half-happen.
+ *
+ * ── Why this is close to trivially correct, which is a consequence ──────
+ *
+ * Every request is one tab (§2.3), so a freed tab always fits the front of
+ * the queue. That is not a rule anybody enforces here; it falls out of there
+ * being no such thing as a larger or smaller request. What follows:
+ *
+ * - **Nothing to skip ahead of**, so there is no scheduling decision.
+ * - **No aging rule**, because a caller cannot be overtaken forever by
+ *   smaller requests when no such request exists.
+ * - **A position only ever improves**, by exactly one each time a tab frees.
+ *
+ * **What is real is the dead entry at the head**, and it is the one failure
+ * invisible in a capacity count — the count is correct the whole time while
+ * an entry that will never take its tab blocks everyone behind it. Queue
+ * entries therefore expire by the same sweep as leases (§2.4), and that
+ * expiry is not housekeeping: **it is the only thing that makes strictness
+ * safe.**
+ */
+/**
+ * Where a lease sits in the queue, counting from one.
+ *
+ * **Computed rather than stored** (§1.3): storing it means rewriting every
+ * waiting row each time one is admitted, and a stored position is a second
+ * fact that can disagree with the order.
+ *
+ * **Ordered by `arrival`, a counter the database allocates at insert**, and
+ * that column exists because the ordering §1.5 describes does not keep the
+ * promise §2.5 makes. Ordering by `created_at` tie-broken by `id` is stable —
+ * which is what §1.5 argues for — but the tie-break is a random identifier,
+ * so among callers arriving inside one millisecond the order bears no
+ * relation to arrival. **Measured: a caller told position 1 is told position
+ * 2 on its next call**, because a caller that really did arrive earlier was
+ * placed ahead of it afterwards. §2.5 promises a position that only ever
+ * improves, and a counter has no ties to get that wrong with.
+ *
+ * It is not `activated_at`, which is null for everyone waiting and is set at
+ * the moment you stop waiting — the answer rather than the question.
+ */
+export function queuePosition(db, claimId) {
+    const row = db
+        .prepare(`SELECT count(*) + 1 AS position
+         FROM claims AS ahead
+         WHERE ahead.state = 'queued'
+           AND ahead.arrival <
+               (SELECT self.arrival FROM claims AS self WHERE self.id = @claimId)`)
+        .get({ claimId });
+    return row.position;
+}
+/** How many leases are waiting, in total. */
+export function queueDepth(db) {
+    const row = db.prepare("SELECT count(*) AS n FROM claims WHERE state = 'queued'").get();
+    return row.n;
+}
+/**
+ * How long recent leases were actually held, in seconds.
+ *
+ * **Deliberately not computed from the expiry** (§1.5): a lease that keeps
+ * being renewed runs far past its expiry, so an estimate built on that would
+ * be confidently wrong in the common case rather than vaguely wrong in all of
+ * them. It is `ended_at` minus `activated_at` over leases that actually ended,
+ * which is the only place that number can come from once the ledger has been
+ * trimmed.
+ *
+ * Returns `undefined` when nothing has ended yet, because a fresh
+ * installation has no history to average and inventing one would produce a
+ * confident number from no evidence.
+ */
+export function recentHoldSeconds(db, sample = 20) {
+    const rows = db
+        .prepare(`SELECT (julianday(ended_at) - julianday(activated_at)) * 86400.0 AS held
+         FROM claims
+         WHERE activated_at IS NOT NULL AND ended_at IS NOT NULL
+         ORDER BY ended_at DESC
+         LIMIT @sample`)
+        .all({ sample });
+    const held = rows.map((row) => row.held).filter((value) => value !== null);
+    if (held.length === 0) {
+        return undefined;
+    }
+    return held.reduce((total, value) => total + value, 0) / held.length;
+}
+/**
+ * The wait estimate: how many are ahead, multiplied by how long leases are
+ * held.
+ *
+ * **A weak number, and it is labelled as one everywhere it appears** (§1.5).
+ * It is, however, a better number than it would be under variable request
+ * sizes: with every request the same size, "how many are ahead of me"
+ * translates directly into how many tabs have to come free, which is one
+ * fewer piece of guesswork in the same calculation.
+ *
+ * `undefined` when there is no history to base it on, so a caller can say
+ * *"no estimate yet"* rather than print a zero that reads as *"any moment
+ * now"*.
+ */
+export function waitEstimateSeconds(db, position) {
+    const held = recentHoldSeconds(db);
+    if (held === undefined) {
+        return undefined;
+    }
+    // Position counts from one and the caller ahead of nobody still waits for
+    // one lease to end, so the multiplier is the position itself.
+    return Math.round(position * held);
+}
+/** The lease at the front of the queue, or nothing if none is waiting. */
+export function headOfQueue(db) {
+    return db
+        .prepare(`SELECT id, browser_id AS browserId
+         FROM claims
+         WHERE state = 'queued'
+         ORDER BY arrival
+         LIMIT 1`)
+        .get();
+}
+/**
+ * Promote the front of the queue for as long as capacity exists.
+ *
+ * **This is the whole scheduling rule** (§2.5): the sweep promotes the front
+ * while capacity exists and stops when it does not. There is no arithmetic in
+ * the step — no size to check a freed tab against — because every waiting
+ * request is the same size as every freed tab.
+ *
+ * ── What a promotion does and does not do here ──────────────────────────
+ *
+ * It flips the lease to `active`, stamps `activated_at`, and puts the lease
+ * on a **fresh** lifetime: the promoted caller has just been given a tab and
+ * its clock starts now rather than continuing from a queue place it has
+ * already spent. `ttl_seconds` moves to the active duration with it, because
+ * §1.3 requires a renewal to extend by the duration the caller was told and
+ * the caller is being told this one on this response.
+ *
+ * **It creates the tab row but does not open the tab.** The row is required:
+ * §1.4 makes active leases and live tab rows the same count, always, so a
+ * promotion that moved the state without creating the row would leave the
+ * store one short of that identity — invisibly, because a capacity count
+ * counts claims. Opening the page is browser work and browser work never
+ * happens inside the arbitration transaction (§2.4b), so the row is created
+ * `opening` with no driver name and the driver call belongs to the caller's
+ * after-commit work.
+ *
+ * The loop is bounded by capacity and by the queue's own length, both of
+ * which shrink on each pass, so it terminates on the smaller of the two.
+ */
+export function promoteWhileCapacity(db, options) {
+    const promoted = [];
+    for (;;) {
+        if (!admits(countActiveClaims(db), options.budget)) {
+            break;
+        }
+        const head = headOfQueue(db);
+        if (head === undefined) {
+            break;
+        }
+        const row = db
+            .prepare(`UPDATE claims
+            SET state = 'active',
+                activated_at = @now,
+                expires_at = strftime('%Y-%m-%dT%H:%M:%fZ', @now, @extend),
+                ttl_seconds = @ttl,
+                updated_at = @now
+          WHERE id = @id AND state = 'queued'
+      RETURNING session_id AS sessionId, browser_id AS browserId`)
+            .get({
+            id: head.id,
+            now: options.now,
+            // The modifier is assembled from a number this process computed, not
+            // from anything a caller supplied.
+            extend: `+${String(options.leaseSeconds)} seconds`,
+            ttl: options.leaseSeconds,
+        });
+        if (row === undefined) {
+            // The lease stopped being queued between the read and the write. Inside
+            // one immediate transaction nothing else can have done that, so this is
+            // a bug rather than a race — but breaking is the safe response either
+            // way, and looping again on an unchanged head would not terminate.
+            break;
+        }
+        // The tab row, created here rather than left to the caller.
+        //
+        // **A promoted lease is an active lease, and §1.4 makes active leases and
+        // live tab rows the same count, always** — "a lease is a tab (§2.3), so
+        // this table and the live part of `claims` have the same number of rows".
+        // A promotion that flipped the state without creating the row would put
+        // the store one short of that identity, and the shortfall would be
+        // invisible to a capacity count, which counts claims.
+        //
+        // `opening` with no driver name, exactly as a grant creates one
+        // (`claim.ts`): opening the page is browser work, and browser work never
+        // happens inside the arbitration transaction (§2.4b).
+        const tabId = randomUUID();
+        db.prepare(`INSERT INTO tabs (id, claim_id, browser_id, state, created_at, updated_at)
+       VALUES (@tabId, @claimId, @browserId, 'opening', @now, @now)`).run({ tabId, claimId: head.id, browserId: row.browserId, now: options.now });
+        append(db, {
+            kind: 'claim_promoted',
+            outcome: 'allow',
+            adapter: options.adapter,
+            claimId: head.id,
+            tabId,
+            sessionId: row.sessionId,
+            browserId: row.browserId,
+            detail: { promotedAt: options.now },
+        });
+        append(db, {
+            kind: 'tab_opening',
+            outcome: 'allow',
+            adapter: options.adapter,
+            claimId: head.id,
+            tabId,
+            sessionId: row.sessionId,
+            browserId: row.browserId,
+        });
+        promoted.push({
+            claimId: head.id,
+            browserId: row.browserId,
+            sessionId: row.sessionId,
+            tabId,
+        });
+    }
+    return promoted;
+}

package/dist/src/service/reconcile.js

@@ -0,0 +1,220 @@
+/**
+ * Decide what a live browser and the store disagree about.
+ *
+ * **Pure: no database, no driver, no clock.** Two lists in, one plan out.
+ *
+ * ── The two disagreements, and the direction of each ────────────────────
+ *
+ * §2.6 names them and this function is a transcription of that sentence:
+ * *"A page open that no live lease owns is closed; a tab a live lease
+ * believes it owns that is not there is marked closed and its lease ended."*
+ *
+ * - **A page the browser has that no row names** — something opened a tab and
+ *   the row that would have owned it is gone, or was never written. Nobody is
+ *   using it and nobody can: it is unaddressable, because addressing goes
+ *   through `tabs.id` and there is no such row. It costs memory forever.
+ * - **A row naming a page the browser does not have** — the page died with a
+ *   crash, or a person closed it by hand. The lease still counts against the
+ *   budget while the thing it is a lease *over* does not exist.
+ *
+ * ── `opening` rows: the race, and why the answer is not a timeout ───────
+ *
+ * This is the part that is easy to get wrong, and getting it wrong closes a
+ * tab that was mid-open.
+ *
+ * `reserveTab` writes the row **before the browser is asked**, and says why:
+ * the identifier has to exist before anything can fail, or a tab that opened
+ * and then lost its answer is a page with no row naming it. The open itself
+ * is browser work, so it happens after the commit (§2.4b). Between those two
+ * moments the store holds an `opening` row and the browser is about to grow a
+ * page that no row yet names.
+ *
+ * **Reconciliation running inside that window sees exactly the shape it is
+ * built to destroy**: a page nothing owns. Closing it would close a tab whose
+ * lease was granted seconds ago and whose caller is about to be handed it.
+ *
+ * What makes this safe is not a heuristic and not a grace period. It is
+ * §1.4's check constraint:
+ *
+ * > `CHECK ((state = 'opening') = (driver_tab_id IS NULL))`
+ *
+ * An `opening` row has **no driver name, by database constraint**. So it
+ * cannot participate in either comparison — there is nothing to compare it
+ * against. It cannot be found vanished, because "vanished" means the browser
+ * does not list a name the row holds and it holds none. And the page it is
+ * about to acquire cannot be matched to it, because matching is by name.
+ *
+ * **Therefore the safe rule is: while any row is `opening`, no page can be
+ * proven unowned.** A page that looks unowned may be that row's, a
+ * millisecond before `recordTabOpened` names it. So this function refuses to
+ * close anything at all when an `opening` row is present, rather than trying
+ * to work out which page belongs to it — which is not knowable from here, and
+ * would be a guess dressed as a decision.
+ *
+ * That is deliberately blunt, and the bluntness is the argument: **the cost
+ * of declining is that a genuinely leaked page survives until the next run,
+ * and the cost of guessing is a caller losing a tab it was just granted.**
+ * Those are not comparable. Reconciliation is not the only thing that
+ * reclaims a page — the sweep closes an expired lease's tabs on every
+ * arbitration call (§2.4) — so a page this declines to close is a page that
+ * waits, not a page that leaks forever.
+ *
+ * The vanished half is unaffected and still runs: it is a claim about rows
+ * that name a page, and an `opening` row names none, so no `opening` row is
+ * ever settled by it. A row is only settled when it holds a driver name the
+ * browser did not list.
+ *
+ * ── What is not decided here ────────────────────────────────────────────
+ *
+ * **Expiry.** `arbitration.ts` owns time-based reclamation and nothing here
+ * reads a clock. The question this asks is *"does this page exist"*, which is
+ * a different question from *"has this lease lapsed"*, and answering the
+ * second one here would be the second spelling of the sweep that `tabs.ts`
+ * says to go and not write.
+ *
+ * **The keeper tab.** It is not in `pages` because `listTabs` excludes it
+ * (§3.15). It is worth stating what would happen if a driver ever included
+ * it, because the failure is silent and severe: the keeper is owned by no
+ * lease, so it would be decided unowned, and closing it kills the shared
+ * signed-in session — a headed browser dies within about half a second of its
+ * final tab closing. The conformance obligation that keeps this true belongs
+ * to the seam, and `tests/service/reconcile.test.ts` asserts the shape here
+ * on the assumption the seam holds up its end.
+ */
+export function decideReconciliation(pages, recorded) {
+    const skippedOpening = recorded.filter((tab) => tab.driverTabId === null).map((tab) => tab.tabId);
+    // Every driver name a live lease claims. Built from the rows that have one,
+    // which by §1.4's check is exactly the rows that are not `opening`.
+    const owned = new Set(recorded
+        .map((tab) => tab.driverTabId)
+        .filter((driverTabId) => driverTabId !== null));
+    const listed = new Set(pages.map((page) => page.driverTabId));
+    // A row holding a name the browser did not list. Safe regardless of the
+    // `opening` window: a row in that window holds no name and so is never
+    // here.
+    const vanishedTabs = recorded
+        .filter((tab) => tab.driverTabId !== null && !listed.has(tab.driverTabId))
+        .map((tab) => ({
+        tabId: tab.tabId,
+        claimId: tab.claimId,
+        // Non-null by the filter above; narrowed for the type rather than
+        // asserted, because an assertion here would be the one place a null
+        // could reach a driver call.
+        driverTabId: tab.driverTabId ?? '',
+    }));
+    // See the docblock: while a row is mid-open, "unowned" is not provable, so
+    // nothing is closed. The vanished half above is untouched by this.
+    const unownedPages = skippedOpening.length > 0
+        ? []
+        : pages
+            .filter((page) => !owned.has(page.driverTabId))
+            .map((page) => ({ driverTabId: page.driverTabId }));
+    return { unownedPages, vanishedTabs, skippedOpening };
+}
+/**
+ * The live tab rows to reconcile against, for one browser.
+ *
+ * **A `Database` and no session** — this is the read half of the writing
+ * part, and it is here rather than in the command so that the command holds
+ * no SQL. `claims.state = 'active'` is what makes it *live* leases: a lapsed
+ * lease's rows belong to the sweep.
+ */
+export function readRecordedTabs(db, browserId) {
+    return db
+        .prepare(`SELECT tabs.id AS tabId,
+              tabs.driver_tab_id AS driverTabId,
+              tabs.claim_id AS claimId
+         FROM tabs
+         JOIN claims ON claims.id = tabs.claim_id
+        WHERE tabs.browser_id = ?
+          AND tabs.state IN ('opening', 'open')
+          AND claims.state = 'active'
+        ORDER BY tabs.id`)
+        .all(browserId);
+}
+/**
+ * Settle the rows whose pages are gone, and end the leases that held them.
+ *
+ * **A database handle and no session** (the constraint `tabs.ts` sets), so
+ * this cannot be the function that also asks the browser. It is called
+ * *before* any page is closed, which is the safe order: a write that lands
+ * and a close that fails leaves a settled row and a leaked page, which §2.4b
+ * already describes and `broker doctor` already reports. The reverse order —
+ * closing first — would leave a closed page and a row still claiming a live
+ * lease over it, which is capacity pinned by nothing.
+ *
+ * ── Why this is not `updateSweptTabs` ───────────────────────────────────
+ *
+ * `arbitration.ts` exports that function so release and sweep cannot spell
+ * one rule twice, and it is the right function for the question *"this lease
+ * has ended, what becomes of its tabs"*. This is a different question, and
+ * the difference is visible in the states each produces:
+ *
+ * | | Question | The tab goes to |
+ * |---|---|---|
+ * | `updateSweptTabs` | The lease ended; is there a page to close? | `closing` — the tool is about to be asked |
+ * | this | The page is already gone | `closed` — there is nothing to ask |
+ *
+ * A vanished page has no round trip outstanding, so `closing` would assert
+ * one that is not, and the row would wait forever for an answer nobody is
+ * coming to give — the exact reasoning the sweep uses for a tab that never
+ * opened. `closed_at` is this moment because that is when the absence was
+ * established; the page died earlier and nothing here knows when, which is
+ * the honest version of §2.4a's distinction rather than a violation of it:
+ * a fact nobody observed is not recoverable by stamping a guess.
+ *
+ * **And the lease is ended, not expired.** §2.6 says the row is marked closed
+ * *"and its lease ended"*. `expired` would claim the lease lapsed on time,
+ * which is a claim about a clock and is false — this lease was cut short by
+ * its tab disappearing. `revoked` is the state for a lease ended by a
+ * decision that was not the caller's and not the clock's, and an
+ * administrator running reconciliation is exactly that.
+ *
+ * ── The sentence is not decoration, and the schema says so ──────────────
+ *
+ * `CHECK ((state = 'revoked') = (revoke_reason IS NOT NULL))` refuses a
+ * revoked lease with no reason, and the column's own comment gives the
+ * purpose: *"an operator taking capacity off a caller owes a sentence, and
+ * the caller's next call is refused with it"*. That is the whole reason this
+ * state is the right one — the caller does not get a bare failure on its next
+ * call, it gets told its page was gone when somebody looked.
+ *
+ * **Found by the constraint rather than by review.** The first version of
+ * this function wrote `state = 'revoked'` with no reason and would have
+ * thrown on the first vanished tab it ever met. The check is doing exactly
+ * the job §1.11 describes.
+ */
+export function applyReconciliation(db, vanished, at) {
+    if (vanished.length === 0) {
+        return;
+    }
+    const tabIds = vanished.map((tab) => tab.tabId);
+    const tabPlaceholders = tabIds.map(() => '?').join(', ');
+    db.prepare(`UPDATE tabs
+        SET state = 'closed', closed_at = ?, updated_at = ?
+      WHERE id IN (${tabPlaceholders})
+        AND state IN ('opening', 'open')`).run(at, at, ...tabIds);
+    // The lease goes with the tab, because a lease *is* a tab (§2.3): a lease
+    // whose tab is gone owns nothing while still counting against the budget,
+    // which §3.13 names as a state that should not exist.
+    const claimIds = [...new Set(vanished.map((tab) => tab.claimId))];
+    const claimPlaceholders = claimIds.map(() => '?').join(', ');
+    db.prepare(`UPDATE claims
+        SET state = 'revoked',
+            revoke_reason = ?,
+            ended_at = ?,
+            updated_at = ?
+      WHERE id IN (${claimPlaceholders})
+        AND state = 'active'`).run(VANISHED_TAB_REASON, at, at, ...claimIds);
+}
+/**
+ * The sentence a caller is refused with after its page went away.
+ *
+ * **Written for the caller rather than for a log.** §3.14: every refusal
+ * *"names the way forward, because the alternative teaches a caller to
+ * satisfy the check rather than to do the right thing"*. The way forward
+ * after losing a page is a fresh lease, so that is what it says — and it says
+ * what happened in terms the caller can act on, without naming the driver's
+ * identifier for the page (§1.4) or implying the caller did anything wrong.
+ */
+export const VANISHED_TAB_REASON = 'This lease’s tab was absent from the browser when reconciliation checked, so the lease was ended. Claim again to get a fresh tab.';