browser-broker 0.1.0

package/dist/src/store/network-path.js

@@ -0,0 +1,182 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { StartupRefusal } from "../errors.js";
+import { isNetworkVolumeType, networkFilesystemName, } from "./network-volume.js";
+/**
+ * `store.not_on_network_filesystem` (`SCHEMA.md` §7.2, §1.0).
+ *
+ * The write-ahead log coordinates through a shared-memory index that requires
+ * every process using the database to be on the same host. On a network
+ * filesystem that requirement is not met, and the failure is not a clean
+ * error — it is two hosts each believing they hold the writer's position,
+ * which is corruption rather than contention. So this is a refusal to run,
+ * not a warning.
+ *
+ * ── Why one check is not enough ─────────────────────────────────────────
+ *
+ * §1.0's table is explicit: a path written as a share directly is caught by
+ * reading its root, but **a mapped network drive is lexically identical to a
+ * local one**. There is nothing in the string to read. A check that only
+ * inspects the string passes on every machine with nothing mapped, which is
+ * every machine anybody writes the test on — so a second check has to ask the
+ * operating system what the volume actually is.
+ *
+ * ── The three checks, and why the third is not the second again ─────────
+ *
+ * | | What it asks | What it catches |
+ * |---|---|---|
+ * | One | Does the path's root name a share? | A share written out directly, in either separator spelling |
+ * | Two | Does the path *resolve* to one? | A mapped drive, on the platform where mappings resolve to the share behind them |
+ * | Three | What does the volume's own type code say? | A mount on a platform that has no share spelling to read and no mapping to resolve |
+ *
+ * **Checks one and two cover exactly one platform's spelling of the problem.**
+ * On a platform whose separator is the forward slash, a mounted network volume
+ * lives at an ordinary absolute path with no share prefix and nothing to
+ * resolve to one — it is a directory as far as every string operation is
+ * concerned. That is the same argument the mapped drive makes, transposed, and
+ * it needs its own check for the same reason. Check three is in
+ * `network-volume.ts` with its own limits written down.
+ *
+ * **A guard developed on one platform is untested on the other by
+ * construction**, so the tests drive all three through injected inputs and
+ * refuse on every platform rather than on the one they were written on.
+ *
+ * ── How check two asks ──────────────────────────────────────────────────
+ *
+ * By resolving the path to its real location. Where a mapped drive resolves to
+ * the share it points at, that turns an invisible case into the visible one
+ * check one already handles — so it reduces to check one, applied to the
+ * resolved path.
+ *
+ * The alternative is asking the platform's management interface for the
+ * volume's drive-type code in a subprocess. It answers correctly and it was
+ * measured, and it is not used here: it costs between roughly 0.7 and 1.1
+ * seconds per call, against a process startup this design puts at tens of
+ * milliseconds and a service that is spawned once per session. Paying a
+ * second on every spawn to learn something a filesystem call answers in a
+ * fraction of a millisecond would invalidate the startup measurement the
+ * storage decision rests on. It stays documented here as the fallback if a
+ * mapping is ever found that does not resolve.
+ *
+ * Filesystem statistics are **not** a route to that answer on the platform
+ * with drive letters, and the reason is worth keeping: there the type field
+ * reports the same value for a local volume and a mapped network one, so an
+ * implementation built on it looks correct, tests green, and refuses nothing.
+ * That is why check three stands beside check two rather than standing in for
+ * it — each is blind exactly where the other sees.
+ */
+/** A path that does not exist yet cannot be resolved; walk up to one that does. */
+function nearestExistingAncestor(target) {
+    let candidate = path.resolve(target);
+    // The loop terminates: `path.dirname` of a root is the root itself.
+    for (;;) {
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(candidate);
+        if (parent === candidate) {
+            return candidate;
+        }
+        candidate = parent;
+    }
+}
+/**
+ * Resolve a path to its real location, following any mapping.
+ *
+ * The store file does not exist on a first spawn, and resolving a path that
+ * is not there throws — so what gets resolved is the nearest ancestor that
+ * does exist. That ancestor is on the same volume as the file will be, which
+ * is the only property this check needs from it.
+ */
+export function resolveRealPath(target) {
+    try {
+        return fs.realpathSync.native(nearestExistingAncestor(target));
+    }
+    catch {
+        // A path that cannot be resolved at all is left as it was written. The
+        // root check below still runs on it, and the store open that follows
+        // will fail for its own reasons with a better message than this one
+        // could invent.
+        return path.resolve(target);
+    }
+}
+/**
+ * Is this path's root a network share?
+ *
+ * Both separator spellings are tested. The platform path parser reports the
+ * share prefix as the root for the backslash spelling, and reports the
+ * forward-slash spelling **unchanged** rather than normalising it — so
+ * matching one spelling really does catch only half the cases.
+ */
+export function hasNetworkShareRoot(target) {
+    const root = path.win32.parse(target).root;
+    if (root === '') {
+        return false;
+    }
+    const normalised = root.replace(/\//g, '\\');
+    // A share root is two separators, then a host, then a share. Two
+    // separators alone is a root-relative path on the current drive, which is
+    // local.
+    return /^\\\\[^\\]+\\/.test(normalised);
+}
+/**
+ * Read the volume statistics for a path, walking up to an ancestor that
+ * exists for the same reason resolution does — the store file is not there on
+ * a first spawn, and the ancestor is on the volume the file will be on.
+ *
+ * A path whose statistics cannot be read reports nothing rather than throwing.
+ * That is a deliberate allow: refusing on an unreadable answer would refuse
+ * paths for reasons that have nothing to do with a network, and the store open
+ * that follows fails with a better message than this could invent.
+ */
+export function readVolumeStatistics(target) {
+    try {
+        return fs.statfsSync(nearestExistingAncestor(target));
+    }
+    catch {
+        return undefined;
+    }
+}
+export const realChecks = {
+    resolveRealPath,
+    hasNetworkShareRoot,
+    readVolumeStatistics,
+};
+/**
+ * Refuse a network location.
+ *
+ * Returns nothing on purpose. What check two resolves is the nearest
+ * *existing ancestor* of the store path, not the store path itself, so the
+ * resolved string is an answer to "which volume is this on" and would be
+ * wrong used as a location. The caller keeps the path it asked about.
+ *
+ * **Surrounding blank space is stripped before any check runs.** A value with
+ * a leading space is a value somebody typed with a leading space, and every
+ * check here reads the front of the string: the share-root test sees a space
+ * where it expects a separator and reports no root, and resolution treats the
+ * whole thing as a relative name. One invisible character would walk a share
+ * past all three, which is a guard defeated by a typing accident rather than
+ * by anything anybody meant.
+ */
+export function refuseNetworkLocation(target, checks = realChecks) {
+    const candidate = target.trim();
+    // Check one: the path as written names a share. Tested before resolution,
+    // for the reason above.
+    if (checks.hasNetworkShareRoot(candidate)) {
+        throw new StartupRefusal('store.not_on_network_filesystem', `The store location is on a network share. The write-ahead log requires every process using the database to be on one host, so a network location is refused rather than risked. Set BROKER_DB to a local path.`);
+    }
+    // Check two: the path as written looks local, and resolving it says
+    // otherwise. This is the mapped-drive case, and it is the reason one check
+    // is not enough.
+    const real = checks.resolveRealPath(candidate);
+    if (checks.hasNetworkShareRoot(real)) {
+        throw new StartupRefusal('store.not_on_network_filesystem', `The store location resolves to a network share. A mapped network drive is indistinguishable from a local one by its path alone, and the write-ahead log requires every process using the database to be on one host. Set BROKER_DB to a local path.`);
+    }
+    // Check three: nothing in the string says share on this platform because
+    // this platform has no share spelling — so the volume is asked what it is.
+    const statistics = checks.readVolumeStatistics(candidate);
+    if (statistics !== undefined && isNetworkVolumeType(statistics.type)) {
+        const name = networkFilesystemName(statistics.type) ?? 'a network filesystem';
+        throw new StartupRefusal('store.not_on_network_filesystem', `The store location is on a network filesystem (${name}). A mount point is indistinguishable from an ordinary directory by its path alone, and the write-ahead log requires every process using the database to be on one host. Set BROKER_DB to a path on a local disk.`);
+    }
+}

package/dist/src/store/network-volume.js

@@ -0,0 +1,92 @@
+/**
+ * The network-volume check for platforms whose separator is the forward slash.
+ *
+ * ── Why this file exists at all ─────────────────────────────────────────
+ *
+ * The share-root check reads a path's root and refuses a two-separator
+ * spelling. That is the whole of the detection on a platform that spells a
+ * share that way. **On a platform that does not, there is nothing in the
+ * string to read**: a mount lives at an ordinary absolute path, and a mount
+ * point is lexically identical to a directory. The mapped-drive argument of
+ * `SCHEMA.md` §1.0 transposes exactly — a check that only inspects the string
+ * passes on every machine with nothing mounted, which is every machine
+ * anybody writes the test on.
+ *
+ * The failure it is guarding is the same one and it is not a clean error: the
+ * write-ahead log coordinates through a shared-memory index that requires
+ * every process using the database to be on one host. Two hosts each believing
+ * they hold the writer's position is corruption rather than contention.
+ *
+ * ── How this asks ───────────────────────────────────────────────────────
+ *
+ * Filesystem statistics report a type code for the volume a path is on, and on
+ * a platform whose separator is the forward slash that code distinguishes a
+ * network filesystem from a local one. So the volume is asked what it is,
+ * rather than the string being asked what it looks like.
+ *
+ * > **The same call is not a route to this answer on the platform with drive
+ * > letters, and the reason is worth keeping**: there the type field reports
+ * > the same value for a local volume and a mapped network one, so an
+ * > implementation built on it looks correct, tests green, and refuses
+ * > nothing. That platform is served by resolving the path instead, which
+ * > turns its invisible case into the visible one — and this file is not
+ * > consulted there.
+ *
+ * ── Why a list of codes rather than a property ──────────────────────────
+ *
+ * There is no "is this remote" flag to read. The type code is the only thing
+ * reported that distinguishes the filesystems at all, so the check is a
+ * membership test against the codes the network filesystems in ordinary use
+ * report. That has a known and stated limit: **a network filesystem whose code
+ * is not below is not detected.** The list is the mitigation for the common
+ * cases rather than a proof over all of them, and saying so is better than
+ * implying a completeness this cannot have.
+ */
+/**
+ * The type codes network filesystems report.
+ *
+ * Each is the constant that filesystem's own implementation reports for a
+ * mounted volume of its kind. They are magic numbers in the literal sense —
+ * fixed values with no derivation — so they are written down with the name of
+ * what reports them and nothing else to check them against.
+ */
+export const NETWORK_FILESYSTEM_TYPES = new Map([
+    // Server message block, versions one through three — the protocol the
+    // drive-letter platform's shares also speak, mounted natively here.
+    [0x517b, 'SMB'],
+    [0xfe534d42, 'SMB2'],
+    [0xff534d42, 'CIFS'],
+    // Network file system, versions two through four.
+    [0x6969, 'NFS'],
+    // Andrew file system, and its open reimplementation.
+    [0x5346414f, 'AFS'],
+    [0x6b414653, 'AFS (OpenAFS)'],
+    // Netware core protocol.
+    [0x564c, 'NCP'],
+    // A filesystem in user space, which is how most user-mounted network
+    // filesystems arrive. Not every one of these is remote — the code says
+    // "a program is serving this", not "a program on another host is serving
+    // this" — and that is stated plainly below rather than hidden.
+    [0x65735546, 'FUSE'],
+    [0x65735543, 'FUSE (control)'],
+    // Cluster filesystems, which are shared between hosts by definition and so
+    // break the one-host requirement for the same reason a mount does.
+    [0x47504653, 'GPFS'],
+    [0x7461636f, 'OCFS2'],
+]);
+/**
+ * Is this path on a filesystem whose type code says it is served over a
+ * network?
+ *
+ * A path whose statistics cannot be read is **not** refused. The store open
+ * that follows fails for its own reasons with a better message than this could
+ * invent, and refusing on an unreadable answer would refuse every path that
+ * does not exist yet — which is every path on a first spawn.
+ */
+export function isNetworkVolumeType(type) {
+    return NETWORK_FILESYSTEM_TYPES.has(type);
+}
+/** The name of the filesystem a type code belongs to, for the refusal message. */
+export function networkFilesystemName(type) {
+    return NETWORK_FILESYSTEM_TYPES.get(type);
+}

package/dist/src/store/open.js

@@ -0,0 +1,226 @@
+import fs from 'node:fs';
+import path from 'node:path';
+// The one place the driver is imported. Keeping it to a single file is what
+// makes the storage choice reversible: the built-in module is a plausible
+// future once it stops being experimental and stops taking its SQLite
+// version from the runtime, and swapping to it is then a change to this file
+// rather than to everything that opens a store.
+//
+// A default import, not a named one: the driver is CommonJS, and under
+// `verbatimModuleSyntax` with node-style resolution the named form
+// type-checks in some configurations and fails at run time.
+import Database from 'better-sqlite3';
+import { agreeOnTabBudget } from "./budget.js";
+import { resolveStoreLocation } from "./location.js";
+import { stepSchema } from "./schema/step.js";
+import { immediate } from "./transaction.js";
+/**
+ * Open the store: resolve where it is, refuse a network location, create the
+ * directory if it is absent, and set the three pragmas that make many
+ * processes on one file safe.
+ *
+ * There is no connection pool and looking for one is looking for the wrong
+ * shape (`MILESTONES.md`): a pool shares connections between concurrent work
+ * inside one long-lived process, and here the callers are separate operating
+ * system processes, each opening the file, doing its work and exiting.
+ *
+ * ── There is exactly one way for a spawn to open this store ─────────────
+ *
+ * `prepareStore` below. It opens, steps the schema, and settles the tab-budget
+ * agreement, in that order, and **it is the only export that hands a spawn a
+ * handle**. The raw open is deliberately module-private now.
+ *
+ * **The privacy is the mechanism, and a comment would not be one.** An
+ * entry point that a sibling export can bypass is a suggestion; the thing that
+ * makes it a path is that there is nothing else to call. Were the raw open
+ * exported beside it, each binary could assemble its own open-and-step pair,
+ * every one of them would be a place for `agreeOnTabBudget` to go missing, and
+ * the omission would be invisible: a store opens, a schema steps, and the one
+ * value several processes must agree on (§1.10, §7.2) is simply never compared.
+ * The budget suite would keep passing throughout, because it calls
+ * `prepareStore` — so the tests would agree with a product that did something
+ * else.
+ *
+ * The one exception is a diagnostic that must be able to observe the states
+ * this refuses to return from, and it is exported under a name that says so.
+ *
+ * Stepping remains a separate asynchronous call inside this module because it
+ * goes through the transaction helper; no caller outside can hold the halves
+ * apart.
+ */
+/** How long a blocked writer waits before giving up, in milliseconds. */
+export const BUSY_TIMEOUT_MS = 5000;
+/**
+ * How many times the conversion to write-ahead-log mode is retried, and how
+ * long each attempt waits before the next.
+ *
+ * Deliberately small. The conversion the retry is waiting on is one pragma on
+ * a file with no rows in it yet, so the only thing being waited for is another
+ * process finishing something that takes single-digit milliseconds. A budget
+ * this size turns the collision into a pause nobody notices; a larger one
+ * would turn a genuinely stuck file into a long hang.
+ */
+const WAL_CONVERSION_ATTEMPTS = 10;
+const WAL_CONVERSION_PAUSE_MS = 20;
+/**
+ * Put the store into write-ahead-log mode, retrying while another process is
+ * doing the same thing.
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY A RETRY AND NOT A LONGER BUSY TIMEOUT — MEASURED, NOT ASSUMED
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * Switching a database into write-ahead-log mode **takes an exclusive lock on
+ * the file**. On a store already in that mode the pragma is a cheap no-op, so
+ * this never shows once an installation is warm. On a **fresh file the first
+ * spawn converts it**, and because the service is spawned per session and
+ * exits with it, a second spawn arriving during that conversion is the
+ * ordinary case on a machine that has never run this.
+ *
+ * The obvious repair — set `busy_timeout` first and let the second process
+ * wait the conversion out — **is not sufficient, and that was measured rather
+ * than reasoned about.** The timeout *is* honoured: with the file held by
+ * another connection, the conversion waits and then throws `SQLITE_BUSY`
+ * anyway, and it waits longer the larger the timeout is (measured at 0, 50,
+ * 200 and 1000ms: it threw after 21, 321, 664 and 1787ms respectively, and at
+ * five seconds after 7.4). So the timeout buys time and does not buy success —
+ * raising it only makes the eventual failure slower.
+ *
+ * Retrying works because the thing being contended for is transient by
+ * construction: the other process is converting the same file to the same
+ * mode, and once it has, this call finds the mode already set and returns it
+ * without needing any lock at all.
+ *
+ * **How load-bearing this is, measured:** with the budget cut to a single
+ * attempt, two barrier-aligned spawns against an empty directory fail in
+ * **9 runs of 10**. It is not a defensive flourish; without it a fresh install
+ * where two agents reach for a browser at once usually fails outright.
+ *
+ * ── One thing this comment will not overclaim ───────────────────────────
+ *
+ * The `busy_timeout` ordering above is correct and is kept, but **no test
+ * fails if it is moved back** — the retry covers that case on its own. It is
+ * ordered this way because a timeout configured after the first thing that can
+ * block is a timeout that was not configured when it was needed. That reason
+ * stands on its own; no assertion rests on it.
+ *
+ * **A busy error is the only one retried.** Anything else — a directory that
+ * cannot be written, a file that is not a database — is returned to the caller
+ * immediately, because retrying a permanent failure ten times only delays the
+ * message that says what is actually wrong.
+ */
+function convertToWriteAheadLog(db, location) {
+    let lastError;
+    for (let attempt = 0; attempt < WAL_CONVERSION_ATTEMPTS; attempt += 1) {
+        try {
+            return db.pragma('journal_mode = WAL', { simple: true });
+        }
+        catch (error) {
+            if (error.code !== 'SQLITE_BUSY') {
+                throw error;
+            }
+            lastError = error;
+            // A synchronous pause, because everything on this path is synchronous
+            // and making the open asynchronous to accommodate a rare retry would
+            // change the signature of every caller that wants a handle.
+            const until = Date.now() + WAL_CONVERSION_PAUSE_MS;
+            while (Date.now() < until) {
+                /* waiting for the other process to finish converting */
+            }
+        }
+    }
+    throw new Error(`The store at ${location} could not be put into write-ahead-log mode after ${String(WAL_CONVERSION_ATTEMPTS)} attempts: another process held the file locked throughout. That mode is what lets several processes share this file. The underlying error was: ${String(lastError.message ?? lastError)}`);
+}
+function openStore(environment, options = {}) {
+    const location = resolveStoreLocation(environment, options.checks);
+    // Created on first spawn, not at install time. An install step that
+    // prepares state is a second lifecycle, and installation is the whole of
+    // deployment here.
+    fs.mkdirSync(path.dirname(location), { recursive: true });
+    const db = new Database(location);
+    // ── The busy timeout is set BEFORE the journal mode, and that ordering is
+    //    necessary but on its own not sufficient ─────────────────────────────
+    //
+    // Ordinary lock contention: a blocked writer waits rather than failing at
+    // once. What this does **not** do is worth knowing before somebody reads
+    // the line and concludes retries are handled — the busy-snapshot error a
+    // deferred transaction raises is not retryable by this setting at all
+    // (§1.0a). The transaction mode is what addresses that, not this number.
+    //
+    // It precedes the conversion below because the conversion is the first
+    // thing on this path that can block, and a timeout set after it is a
+    // timeout that was not configured at the moment it was needed.
+    db.pragma(`busy_timeout = ${String(BUSY_TIMEOUT_MS)}`);
+    // The mode that lets several processes read while one writes, which is the
+    // whole basis of the concurrency model (§1.0a). Asserted rather than
+    // assumed: the pragma returns the mode it actually set.
+    const journalMode = convertToWriteAheadLog(db, location);
+    if (journalMode !== 'wal') {
+        throw new Error(`The store could not be opened in write-ahead-log mode; the journal mode is ${String(journalMode)}. That mode is what lets several processes share this file.`);
+    }
+    // Set explicitly, and the reason is not that the engine defaults it off.
+    // The driver in use is compiled with foreign keys defaulted on, so this
+    // pragma is a restatement of what it already does rather than a change to
+    // it. It is set because **a correctness guarantee must not rest on a
+    // third-party dependency's compile-time flag**: that
+    // flag is not part of the driver's public interface, and a rebuild from
+    // source, a differently packaged build, or the driver swap this file's own
+    // import comment contemplates could all change it with nothing to notice.
+    // Row #7's composite foreign key on tabs — the one that stops a tab naming
+    // a browser its own lease did not — is the guarantee being protected.
+    db.pragma('foreign_keys = ON');
+    return {
+        location,
+        immediate: (fn) => immediate(db, fn),
+        pragma: (statement) => db.pragma(statement, { simple: true }),
+        close: () => {
+            db.close();
+        },
+        db,
+    };
+}
+export async function prepareStore(environment, options = {}) {
+    const store = openStore(environment, options);
+    try {
+        const stepped = await stepSchema(store.db);
+        // `budget.agrees_with_store` (§7.2), and it runs **after** stepping
+        // because the row it compares against is part of the schema. A process
+        // whose environment disagrees with the store refuses here rather than
+        // arbitrating against a bound the other processes are not using.
+        const budget = agreeOnTabBudget(store.db, environment.tabBudget);
+        return { ...store, stepped, budget };
+    }
+    catch (error) {
+        store.close();
+        throw error;
+    }
+}
+/**
+ * Open an **existing** store without stepping it and without settling the
+ * budget agreement — for `broker doctor`, and for nothing else.
+ *
+ * ── Why this exception exists, and why it is a separate name ────────────
+ *
+ * `doctor`'s whole job is to report the state of an installation, including
+ * the two states `prepareStore` refuses to return from: a store behind this
+ * build's schema version, and a store whose recorded tab budget disagrees with
+ * this process's environment. A diagnostic that used the spawn path would
+ * throw on exactly the installations it exists to describe, and the operator
+ * would get a refusal instead of the report naming both numbers.
+ *
+ * **It is a distinct exported name rather than a second call to the raw open**
+ * because that is the difference between an exception and a bypass. The
+ * defect this module's header describes came from four callers quietly doing
+ * their own open; a caller reaching for something spelled
+ * `openStoreForDiagnosis` is stating that it is the diagnostic, and anything
+ * else calling it is visible in one grep.
+ *
+ * **Never creates a store.** The caller checks the file exists first, and that
+ * ordering is load-bearing: the raw open creates the directory and the file,
+ * so a doctor that opened unconditionally would create an empty store at
+ * version zero and then truthfully report it at the wrong version — a fault it
+ * had itself caused on an installation that was fine a moment earlier.
+ */
+export function openStoreForDiagnosis(environment, options = {}) {
+    return openStore(environment, options);
+}