@crouter/api 0.3.387 → 0.3.388

package/dist/core/spaces/open-beneath.js

@@ -0,0 +1,581 @@
+import { chmodSync, chownSync, closeSync, constants, fchmodSync, fchownSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, readSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeSync, } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { loadLinuxNative, O_CLOEXEC, O_PATH, RESOLVE_BENEATH, RESOLVE_NO_SYMLINKS } from '../../native/linux.js';
+// Every path the daemon opens for a caller resolves beneath the root of the
+// permission that names it, with no symlink anywhere on the way: on Linux the
+// kernel enforces it (openat2). Every Linux open is O_NONBLOCK and keeps only a
+// regular file (or a directory where one is expected), so a FIFO, socket,
+// device or leased file an agent plants is refused instead of blocking the
+// daemon. A Mac has
+// no addon and opens by pathname.
+const RESOLVE = RESOLVE_BENEATH | RESOLVE_NO_SYMLINKS;
+const DIR = O_PATH | constants.O_DIRECTORY | O_CLOEXEC;
+let cached = null;
+function native() {
+    if (cached === null)
+        cached = loadLinuxNative();
+    return cached;
+}
+function code(error) {
+    return error.code;
+}
+/** A path this module refused: it meets a symlink, leaves its root, is not a
+ *  regular file, or is held by a lease. */
+class BeneathRefusal extends Error {
+}
+export function isBeneathRefusal(error) {
+    return error instanceof BeneathRefusal;
+}
+/** A kernel refusal re-thrown as a `BeneathRefusal` naming the caller's path (the
+ *  addon's message is bare): ELOOP a symlink, EXDEV an escape, ENXIO a socket or
+ *  a FIFO opened non-blocking for writing with no reader, EAGAIN a file lease
+ *  (F_SETLEASE) the non-blocking open would otherwise wait out. */
+function refused(error, shown) {
+    switch (code(error)) {
+        case 'ELOOP':
+        case 'EXDEV': return new BeneathRefusal(`path meets a symlink: ${shown}`);
+        case 'ENXIO': return new BeneathRefusal(`path is not a regular file: ${shown}`);
+        case 'EAGAIN': return new BeneathRefusal(`path is held by a lease: ${shown}`);
+        default: return error;
+    }
+}
+function openat2(n, dirfd, rel, flags, shown) {
+    try {
+        return n.openat2(dirfd, rel, flags, RESOLVE);
+    }
+    catch (error) {
+        throw refused(error, shown);
+    }
+}
+/** `fd` if it is a regular file (or, with `directory`, a directory); otherwise
+ *  it is closed and refused. */
+function regular(fd, shown, directory) {
+    let stat;
+    try {
+        stat = fstatSync(fd);
+    }
+    catch (error) {
+        closeSync(fd);
+        throw error;
+    }
+    if (stat.isFile() || (directory && stat.isDirectory()))
+        return fd;
+    closeSync(fd);
+    throw new BeneathRefusal(`path is not a regular file: ${shown}`);
+}
+/** Codes that mean "nothing is there to use", as a pathname existence check reads them. */
+const ABSENT = new Set(['ENOENT', 'ENOTDIR', 'EACCES']);
+/** Whether a beneath read failed because nothing usable is there: absent, not a
+ *  directory, unreadable, or refused (see `BeneathRefusal`). */
+export function isAbsentOrRefused(error) {
+    return ABSENT.has(code(error) ?? '') || isBeneathRefusal(error);
+}
+function inside(root, path) {
+    const rel = relative(resolve(root), resolve(path));
+    if (rel === '..' || rel.startsWith(`..${sep}`) || rel.startsWith(sep))
+        throw new Error(`${path} is outside ${root}`);
+    return rel;
+}
+function entry(name) {
+    if (name === '' || name === '..' || name.includes('/'))
+        throw new Error(`not one path component: ${name}`);
+    return name;
+}
+/** An fd for `path` opened with `flags`, resolved beneath `root`. Never creates:
+ *  `openat2` takes no mode, so a file it created would be mode 0000. On Linux
+ *  the fd is a regular file or a directory, except with O_PATH, which opens
+ *  nothing and is only stat'd. */
+export function openBeneath(root, path, flags) {
+    if (flags & constants.O_CREAT)
+        throw new Error('openBeneath never creates; use writeFileBeneath or createFileBeneath');
+    const rel = inside(root, path);
+    const n = native();
+    if (!n)
+        return openSync(path, flags);
+    const slash = openSync('/', DIR);
+    let rootFd;
+    try {
+        rootFd = openat2(n, slash, relative('/', resolve(root)) || '.', DIR, root);
+    }
+    finally {
+        closeSync(slash);
+    }
+    try {
+        if (flags & O_PATH)
+            return openat2(n, rootFd, rel || '.', flags | O_CLOEXEC, path);
+        return regular(openat2(n, rootFd, rel || '.', flags | O_CLOEXEC | constants.O_NONBLOCK, path), path, true);
+    }
+    finally {
+        closeSync(rootFd);
+    }
+}
+export function readFileBeneath(root, path) {
+    const fd = openBeneath(root, path, constants.O_RDONLY);
+    try {
+        return readFileSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** The file's text, or null when it is missing or refused. */
+export function readTextBeneathIfExists(root, path) {
+    try {
+        return readFileBeneath(root, path).toString('utf8');
+    }
+    catch (error) {
+        if (code(error) === 'ENOENT' || isBeneathRefusal(error))
+            return null;
+        throw error;
+    }
+}
+export function statBeneath(root, path) {
+    if (!native())
+        return statSync(path);
+    const fd = openBeneath(root, path, O_PATH);
+    try {
+        return fstatSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function existsBeneath(root, path) {
+    try {
+        statBeneath(root, path);
+        return true;
+    }
+    catch (error) {
+        if (ABSENT.has(code(error) ?? ''))
+            return false;
+        throw error;
+    }
+}
+/** Run `fn` with `at(name)`, a pathname that reaches one entry of `dir` after
+ *  `dir` itself resolved beneath `root` (`at()` is the directory). With
+ *  `create`, missing directories on the way are made. */
+export function withDirBeneath(root, dir, fn, create = false) {
+    inside(root, dir);
+    const n = native();
+    if (!n) {
+        if (create)
+            mkdirSync(dir, { recursive: true });
+        return fn((name) => name === undefined ? dir : join(dir, entry(name)));
+    }
+    let fd = openSync('/', DIR);
+    try {
+        for (const part of relative('/', resolve(dir)).split(sep).filter(Boolean)) {
+            let next;
+            try {
+                next = openat2(n, fd, part, DIR, dir);
+            }
+            catch (error) {
+                if (!create || code(error) !== 'ENOENT')
+                    throw error;
+                try {
+                    mkdirSync(`/proc/self/fd/${fd}/${part}`);
+                }
+                catch (made) {
+                    if (code(made) !== 'EEXIST')
+                        throw made;
+                }
+                next = openat2(n, fd, part, DIR, dir);
+            }
+            closeSync(fd);
+            fd = next;
+        }
+        const base = `/proc/self/fd/${fd}`;
+        return fn((name) => name === undefined ? base : `${base}/${entry(name)}`);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Open the final component for writing. On Linux it must be a regular file,
+ *  never a symlink (O_NOFOLLOW's ELOOP is the same refusal openat2 gives). */
+function openForWrite(at, flags, mode, shown) {
+    if (!native())
+        return openSync(at, flags, mode);
+    let fd;
+    try {
+        fd = openSync(at, flags | constants.O_NOFOLLOW | constants.O_NONBLOCK, mode);
+    }
+    catch (error) {
+        throw refused(error, shown);
+    }
+    return regular(fd, shown, false);
+}
+function writeAll(fd, data) {
+    let offset = 0;
+    while (offset < data.length)
+        offset += writeSync(fd, data, offset, data.length - offset);
+}
+/** Write `data` to `path` beneath `root`, making missing parents. `atomic`
+ *  writes a temporary file and renames it over the target, so on Linux a
+ *  symlink at the target is replaced, never followed. A Mac writes through a
+ *  symlink to its target, as it always has (a dangling one fails ENOENT). */
+export function writeFileBeneath(root, path, data, options = {}) {
+    const bytes = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+    const mode = options.mode ?? 0o666;
+    let dir = dirname(path);
+    let name = basename(path);
+    let base = root;
+    if (options.atomic && !native()) {
+        let link = false;
+        try {
+            link = lstatSync(path).isSymbolicLink();
+        }
+        catch (error) {
+            if (code(error) !== 'ENOENT')
+                throw error;
+        }
+        if (link) {
+            const target = realpathSync(path);
+            dir = dirname(target);
+            name = basename(target);
+            base = '/';
+        }
+    }
+    withDirBeneath(base, dir, (at) => {
+        if (!options.atomic) {
+            const fd = openForWrite(at(name), constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC, mode, path);
+            try {
+                writeAll(fd, bytes);
+            }
+            finally {
+                closeSync(fd);
+            }
+            return;
+        }
+        const temporary = at(`.${name}.${randomUUID()}.tmp`);
+        let fd = openSync(temporary, 'wx', mode);
+        try {
+            writeAll(fd, bytes);
+            fsyncSync(fd);
+            closeSync(fd);
+            fd = undefined;
+            renameSync(temporary, at(name));
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+            try {
+                unlinkSync(temporary);
+            }
+            catch (error) {
+                if (code(error) !== 'ENOENT')
+                    throw error;
+            }
+        }
+    }, true);
+}
+/** Create `path` beneath `root` only if absent (`wx`), making missing parents. */
+export function createFileBeneath(root, path, data, mode = 0o666) {
+    const bytes = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+    withDirBeneath(root, dirname(path), (at) => {
+        const fd = openSync(at(basename(path)), 'wx', mode);
+        try {
+            writeAll(fd, bytes);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }, true);
+}
+export function appendFileBeneath(root, path, data) {
+    withDirBeneath(root, dirname(path), (at) => {
+        const fd = openForWrite(at(basename(path)), constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND, 0o666, path);
+        try {
+            writeAll(fd, Buffer.from(data, 'utf8'));
+        }
+        finally {
+            closeSync(fd);
+        }
+    }, true);
+}
+export function unlinkBeneath(root, path) {
+    withDirBeneath(root, dirname(path), (at) => unlinkSync(at(basename(path))));
+}
+export function rmdirBeneath(root, path) {
+    withDirBeneath(root, dirname(path), (at) => rmdirSync(at(basename(path))));
+}
+export function renameBeneath(root, from, to) {
+    withDirBeneath(root, dirname(from), (src) => withDirBeneath(root, dirname(to), (dst) => renameSync(src(basename(from)), dst(basename(to))), true));
+}
+/** link(2) without replacement: fails if `to` exists. */
+export function linkBeneath(root, from, to) {
+    withDirBeneath(root, dirname(from), (src) => withDirBeneath(root, dirname(to), (dst) => linkSync(src(basename(from)), dst(basename(to)))));
+}
+export function fsyncDirBeneath(root, dir) {
+    withDirBeneath(root, dir, (at) => {
+        const fd = openSync(at(), constants.O_RDONLY);
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    });
+}
+/** Directory entries typed by the directory itself (a symlink stays a symlink). */
+export function readdirBeneath(root, dir) {
+    return withDirBeneath(root, dir, (at) => readdirSync(at(), { withFileTypes: true }));
+}
+/** The first `limit` entries by name, each with its own (unfollowed on Linux)
+ *  stat; an entry removed before its stat is left out. */
+export function listBeneath(root, dir, limit) {
+    return withDirBeneath(root, dir, (at) => readdirSync(at()).sort((a, b) => a.localeCompare(b)).slice(0, limit).flatMap((name) => {
+        try {
+            return [{ name, stat: native() ? lstatSync(at(name)) : statSync(at(name)) }];
+        }
+        catch (error) {
+            if (code(error) === 'ENOENT')
+                return [];
+            throw error;
+        }
+    }));
+}
+/** Regular files under `dir` matching `predicate`, never descending a symlink. */
+export function walkFilesBeneath(root, dir, predicate = () => true, skipDir = () => false) {
+    const out = [];
+    const stack = [dir];
+    while (stack.length) {
+        const current = stack.pop();
+        let entries;
+        try {
+            entries = readdirBeneath(root, current);
+        }
+        catch (error) {
+            if (current === dir && !ABSENT.has(code(error) ?? ''))
+                throw error;
+            continue;
+        }
+        for (const e of entries) {
+            const full = join(current, e.name);
+            if (e.isDirectory()) {
+                if (!skipDir(e.name))
+                    stack.push(full);
+            }
+            else if (e.isFile() && predicate(e.name))
+                out.push(full);
+        }
+    }
+    return out;
+}
+/** Copy the entries of `from` (beneath `fromRoot`) into `to` (beneath
+ *  `toRoot`): directories and regular files with their permission bits, and
+ *  symlinks as links, never followed. Any other entry, any entry removed or
+ *  refused after the directory was read, and any top-level name in `skip`, is
+ *  left out. A name `to` already holds is overwritten, except by a symlink. */
+export function copyTreeBeneath(fromRoot, from, toRoot, to, skip = new Set()) {
+    copyEntries(fromRoot, from, readdirBeneath(fromRoot, from), toRoot, to, skip);
+}
+function copyEntries(fromRoot, from, entries, toRoot, to, skip) {
+    withDirBeneath(toRoot, to, () => undefined, true);
+    for (const entry of entries) {
+        if (skip.has(entry.name))
+            continue;
+        const source = join(from, entry.name);
+        const target = join(to, entry.name);
+        if (entry.isDirectory()) {
+            let mode;
+            let children;
+            try {
+                mode = statBeneath(fromRoot, source).mode & 0o777;
+                children = readdirBeneath(fromRoot, source);
+            }
+            catch (error) {
+                if (isAbsentOrRefused(error))
+                    continue;
+                throw error;
+            }
+            copyEntries(fromRoot, source, children, toRoot, target, new Set());
+            withDirBeneath(toRoot, to, (at) => chmodSync(at(entry.name), mode));
+        }
+        else if (entry.isSymbolicLink()) {
+            let link;
+            try {
+                link = withDirBeneath(fromRoot, from, (at) => readlinkSync(at(entry.name)));
+            }
+            catch (error) {
+                if (code(error) === 'EINVAL' || isAbsentOrRefused(error))
+                    continue;
+                throw error;
+            }
+            withDirBeneath(toRoot, to, (at) => symlinkSync(link, at(entry.name)));
+        }
+        else if (entry.isFile()) {
+            let fd;
+            try {
+                fd = openBeneath(fromRoot, source, constants.O_RDONLY);
+            }
+            catch (error) {
+                if (isAbsentOrRefused(error))
+                    continue;
+                throw error;
+            }
+            try {
+                copyFileFd(fd, toRoot, target);
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+    }
+}
+/** Copy the open regular file `fd` to `path` beneath `root` in 1 MiB chunks,
+ *  with its permission bits. */
+function copyFileFd(fd, root, path) {
+    const mode = fstatSync(fd).mode & 0o777;
+    withDirBeneath(root, dirname(path), (at) => {
+        const out = openForWrite(at(basename(path)), constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC, mode, path);
+        try {
+            fchmodSync(out, mode);
+            const chunk = Buffer.allocUnsafe(1 << 20);
+            for (let read = readSync(fd, chunk); read > 0; read = readSync(fd, chunk))
+                writeAll(out, chunk.subarray(0, read));
+        }
+        finally {
+            closeSync(out);
+        }
+    }, true);
+}
+/** Set the mode (and, with `owner`, the owner) of the file or directory at
+ *  `path` beneath `root` through an fd opened without following a symlink. A
+ *  Mac sets them by pathname, as it always has. */
+export function setModeBeneath(root, path, mode, owner) {
+    if (!native()) {
+        if (owner)
+            chownSync(path, owner.uid, owner.gid);
+        chmodSync(path, mode);
+        return;
+    }
+    const fd = openBeneath(root, path, constants.O_RDONLY | constants.O_NONBLOCK);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() && !stat.isDirectory())
+            throw new BeneathRefusal(`path is not a regular file or directory: ${path}`);
+        if (owner)
+            fchownSync(fd, owner.uid, owner.gid);
+        fchmodSync(fd, mode);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function unlinkIfPresent(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (error) {
+        if (code(error) !== 'ENOENT')
+            throw error;
+    }
+}
+/** Remove the tree at `path` beneath `root`, never descending a symlink: a
+ *  symlink at `path` or inside it is unlinked itself. Absent is not an error.
+ *  On Linux the walk holds one directory fd per level and opens each child
+ *  relative to its parent, so a deep tree costs one open per entry. */
+export function removeTreeBeneath(root, path) {
+    const n = native();
+    if (!n) {
+        rmSync(path, { recursive: true, force: true });
+        return;
+    }
+    try {
+        withDirBeneath(root, dirname(path), (at) => {
+            const parent = openSync(at(), DIR);
+            try {
+                removeTreeAt(n, parent, basename(path), path);
+            }
+            finally {
+                closeSync(parent);
+            }
+        });
+    }
+    catch (error) {
+        if (code(error) !== 'ENOENT')
+            throw error;
+    }
+}
+function removeTreeAt(n, parentFd, name, shown) {
+    const stack = [];
+    const enter = (at, child, childShown) => {
+        let fd;
+        try {
+            fd = openat2(n, at, child, DIR, childShown);
+        }
+        catch (error) {
+            if (code(error) === 'ENOENT')
+                return;
+            if (code(error) !== 'ENOTDIR' && !(error instanceof BeneathRefusal))
+                throw error;
+            unlinkIfPresent(`/proc/self/fd/${at}/${child}`);
+            return;
+        }
+        stack.push({ fd, parentFd: at, name: child, shown: childShown, dirs: [] });
+        const level = stack[stack.length - 1];
+        for (const e of readdirSync(`/proc/self/fd/${fd}`, { withFileTypes: true })) {
+            if (e.isDirectory())
+                level.dirs.push(e.name);
+            else
+                unlinkIfPresent(`/proc/self/fd/${fd}/${e.name}`);
+        }
+    };
+    try {
+        enter(parentFd, name, shown);
+        while (stack.length > 0) {
+            const level = stack[stack.length - 1];
+            const child = level.dirs.pop();
+            if (child !== undefined) {
+                enter(level.fd, child, join(level.shown, child));
+                continue;
+            }
+            stack.pop();
+            closeSync(level.fd);
+            try {
+                rmdirSync(`/proc/self/fd/${level.parentFd}/${level.name}`);
+            }
+            catch (error) {
+                if (code(error) !== 'ENOENT')
+                    throw error;
+            }
+        }
+    }
+    finally {
+        for (const level of stack)
+            closeSync(level.fd);
+    }
+}
+/** A pathname that connects to the unix socket at `path` beneath `root`
+ *  without following a symlink, and `release`, to call once the connect has
+ *  settled. On Linux it is the magic link of an O_PATH fd held until release. */
+export function socketBeneath(root, path) {
+    if (!native())
+        return { path, release: () => undefined };
+    const fd = openBeneath(root, path, O_PATH);
+    let stat;
+    try {
+        stat = fstatSync(fd);
+    }
+    catch (error) {
+        closeSync(fd);
+        throw error;
+    }
+    if (!stat.isSocket()) {
+        closeSync(fd);
+        throw new BeneathRefusal(`path is not a socket: ${path}`);
+    }
+    let open = true;
+    return {
+        path: `/proc/self/fd/${fd}`,
+        release: () => {
+            if (!open)
+                return;
+            open = false;
+            closeSync(fd);
+        },
+    };
+}

package/dist/core/sqlite-statements.d.ts

@@ -0,0 +1,4 @@
+import type { DatabaseSync, StatementSync } from 'node:sqlite';
+export declare function prepared(db: DatabaseSync, sql: string): StatementSync;
+/** Explicitly release compiled statements before closing or migrating a connection. */
+export declare function forgetPrepared(db: DatabaseSync): void;

package/dist/core/sqlite-statements.js

@@ -0,0 +1,17 @@
+/** Statements belong to a connection, not a database path. Cache only fixed SQL:
+ * generated IN lists and schema-dependent SQL remain uncached at their call sites.
+ */
+const statements = new WeakMap();
+export function prepared(db, sql) {
+    let byDb = statements.get(db);
+    if (!byDb)
+        statements.set(db, byDb = new Map());
+    let statement = byDb.get(sql);
+    if (!statement)
+        byDb.set(sql, statement = db.prepare(sql));
+    return statement;
+}
+/** Explicitly release compiled statements before closing or migrating a connection. */
+export function forgetPrepared(db) {
+    statements.delete(db);
+}