@nervur-org/dock 0.3.0

package/dist/harbor/disk.js

@@ -0,0 +1,249 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// SPDX-License-Identifier: Apache-2.0
+// The node daemon's harbor: the core over a folder on disk. The store is
+// `files.ts`, one folder per ward; the class bodies come from a module the
+// ward record names, loaded from the folder; the lease is a pid file. The
+// estate's own beings, the user being, the front desk and the avatar, are
+// held by every harbor here: they are what every side needs, and a folder's
+// class source adds to them.
+//
+//   <dir>/
+//     lease                 pid of the one process that holds this harbor
+//     classes/index.ts      the default class source, a module exporting classes
+//     tab/index.ts          the classes for the tab, served bundled by the web route: human/web.ts
+//     design/               the face this world wears: tokens.css, fonts.css, fonts/, served by the web route
+//     wards/<name>/         seed, rows/, ward.json, or one sealed
+//                           blob when the daemon holds QUO_SEED_KEY: see files.ts
+//     reach.json            the directory's hints
+import { mkdir, readFile, writeFile, unlink, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { register } from 'node:module';
+import process from 'node:process';
+import { User, Desk, Avatar, Presence, Clock, Courier } from '../beings/index.js';
+import { setup } from '../beings/setup.js';
+import { Harbor, DEFAULT_CODE } from '@nervur-org/nervur/harbor';
+import { FACULTY_CLASSES, settled, stand } from '../dock/index.js';
+import { Files } from './files.js';
+export const BUILT_IN = { User, Desk, Avatar, Presence, Clock, Courier, ...FACULTY_CLASSES };
+// The default ward, the one a caller means when naming none: the one marked,
+// or the one ward hosted when there is exactly one, which is every harbor an
+// adopter stands with one `quo init`. Several wards and none marked is
+// refused by name, since agents and a door would otherwise hang off a
+// guess. The dock ward is furniture, never a candidate.
+export function defaultWard(marked, hosted) {
+    if (marked.length > 1)
+        throw new Error(`this device marks ${marked.join(', ')} as default, and one at most may be`);
+    const one = marked[0];
+    if (one !== undefined) {
+        if (!hosted.includes(one))
+            throw new Error(`this device says its default ward is ${one}, and hosts no such ward`);
+        return one;
+    }
+    const [first, ...more] = hosted.filter((n) => n !== 'dock');
+    if (first !== undefined && more.length === 0)
+        return first;
+    const names = first === undefined ? [] : [first, ...more];
+    throw new Error(names.length === 0 ? 'this device hosts no ward: run `quo init`' : `this device hosts ${names.join(', ')} and says which is the default: quo default <name>`);
+}
+// Folders held by a harbor in this process. The lease file names a pid, and
+// a second harbor in the same pid would pass that check while still being a
+// second ward with one pk.
+const HELD = new Set();
+// A class file in the harbor folder resolves its packages from where the
+// dock is installed, `resolve.ts`: the folder has no node_modules and is not
+// meant to. Registered once per process, before the first class loads.
+let hooked = false;
+function hook() {
+    if (hooked)
+        return;
+    hooked = true;
+    const self = import.meta.url;
+    // bundled into one script, as the desk's sidecar is, the dock has no URL and no folder of
+    // packages beside it to resolve to: a class file there imports nothing bare
+    if (!self)
+        return;
+    register(new URL(self.endsWith('.ts') ? './resolve.ts' : './resolve.js', self), { parentURL: self, data: { parent: self } });
+}
+// The class source is a module. Every export that is a class is a class the
+// harbor holds, under its export name. The harbor never sees a body: it
+// constructs when a ward names a class, and never chooses one.
+async function loadClasses(path) {
+    if (!existsSync(path))
+        return {};
+    hook();
+    // Keyed by the file's own time, so a source that changed on disk is read
+    // again and a harbor boots on what it pins, not on what it once loaded.
+    const { mtimeMs } = await stat(path);
+    const mod = (await import(__rewriteRelativeImportExtension(`${pathToFileURL(path).href}?v=${mtimeMs}`)));
+    const out = {};
+    for (const [name, v] of Object.entries(mod))
+        if (typeof v === 'function' && 'prototype' in v)
+            out[name] = v;
+    return out;
+}
+export class DiskHarbor extends Harbor {
+    dir;
+    // The default ward: the one a caller means when naming none. Not a kind of
+    // ward and nothing in Quo knows of it: a harbor is not a being and has no
+    // self to be, so it can only point at one of its wards. Its agents boot
+    // there, and its door answers for it when a caller names no ward. The one
+    // ward it hosts when there is one, the one marked otherwise, resolved by
+    // the daemon at boot; empty until then.
+    defaultWard = '';
+    // The mark is a file in the ward's own folder, `wards/<name>/default`, so
+    // it moves with the ward and nothing beside the wards says it. One at most:
+    // marking one takes the mark off every other.
+    static async setDefault(dir, name) {
+        const h = new DiskHarbor(dir);
+        const names = await h.store.list();
+        if (!names.includes(name))
+            throw new Error(`no ward ${name} in ${h.dir}`);
+        for (const n of names)
+            await unlink(join(h.dir, 'wards', n, 'default')).catch(() => { });
+        await writeFile(join(h.dir, 'wards', name, 'default'), '');
+    }
+    // Whether a ward is shown at the web route: listed at its root and its
+    // public being's page painted for a stranger. Hidden, it is not listed
+    // and a stranger meets the plain door page, while a link still knocks
+    // with its invitation and the desk still answers a proof, so nothing of
+    // the way in changes. A mark in the ward's own folder, `wards/<name>/shown`,
+    // hidden until the root shows it.
+    static async setShown(dir, name, shown) {
+        const h = new DiskHarbor(dir);
+        if (!(await h.store.list()).includes(name))
+            throw new Error(`no ward ${name} in ${h.dir}`);
+        const p = join(h.dir, 'wards', name, 'shown');
+        if (shown)
+            await writeFile(p, '');
+        else
+            await unlink(p).catch(() => { });
+    }
+    static isShown(dir, name) {
+        return existsSync(join(resolve(dir), 'wards', name, 'shown'));
+    }
+    static async marked(dir) {
+        const h = new DiskHarbor(dir);
+        return (await h.store.list()).filter((n) => existsSync(join(h.dir, 'wards', n, 'default')));
+    }
+    // The default ward read from the folder alone, for a command with no
+    // daemon in front of it and no `--ward` given.
+    static async defaultOf(dir) {
+        const h = new DiskHarbor(dir);
+        return defaultWard(await DiskHarbor.marked(dir), await h.store.list());
+    }
+    #held = false;
+    // `lend` is what this box lends the beings of every ward here: a name to
+    // an invitation on a being of its own ward, which `stand` puts up. A
+    // folder booted by a command lends nothing.
+    // `own` are this terrain's own class bodies, the faculty subclasses a box
+    // has: they stand in front of the built-ins, so a daemon that can ring
+    // hands its own `Push` and the dock ward boots that one.
+    constructor(dir, lend, own = {}) {
+        const abs = resolve(dir);
+        // The key the environment gives, the edge's name for it: from the
+        // Keychain through the app that spawned this daemon, or nothing on a
+        // droplet, whose folder stays plain under its file modes.
+        super(new Files(abs, process.env.QUO_SEED_KEY), async (rec) => ({ ...BUILT_IN, ...own, ...(await loadClasses(isAbsolute(rec.code) ? rec.code : join(abs, rec.code))) }), lend);
+        this.dir = abs;
+    }
+    // What this box lends, by name. Set before `boot` and read there; a box
+    // that says nothing stands no ward of its own and lends nothing.
+    lent;
+    // Create a harbor folder with one ward, and the root's setup in it: the
+    // front desk, public, and one user being, with the desk holding a standing
+    // to her placed by the root's knock. Boots the ward once, with no lease, to
+    // do that and to learn its pk, and writes the record. Refuses a folder that
+    // has one.
+    static async init(dir, name = 'main', user = 'me', cls = 'User', mark = false, shown = false) {
+        const h = new DiskHarbor(dir);
+        if ((await h.store.list()).includes(name))
+            throw new Error(`ward ${name} already exists in ${h.dir}`);
+        await mkdir(join(h.dir, 'classes'), { recursive: true });
+        const classes = join(h.dir, DEFAULT_CODE);
+        if (!existsSync(classes))
+            await writeFile(classes, '// The classes this harbor holds beside the built-in ones. Export each one by name.\nexport {};\n');
+        const hosted = await h.create(name, user);
+        await setup(hosted, user, cls);
+        if (mark)
+            await DiskHarbor.setDefault(h.dir, name);
+        if (shown)
+            await DiskHarbor.setShown(h.dir, name, true);
+        return { dir: h.dir, name, pk: hosted.pk, user };
+    }
+    // Take the lease and boot every ward in the folder. The lease is the
+    // harbor's vouch made a store property: two processes over one seed are two
+    // wards with one pk, so a held lease refuses the boot.
+    //
+    // The box's own ward goes up before every other, because a being born in
+    // any of them lends from her first line, and a ground that could not reach
+    // it yet would leave her holding nothing until her next birth.
+    async boot() {
+        await this.#lease();
+        if (this.lent)
+            this.lend = await stand(this, this.lent);
+        await super.boot();
+        // Every being who takes what this box lends does it at her birth, and
+        // birth is synchronous while taking a standing is not. A box is up when
+        // they have landed, not before.
+        await settled();
+    }
+    // Every ward's writing finished, then the lease. A ward says it wrote and
+    // the harbor writes it after, so a close that only dropped the lease would
+    // let the process end with a write still on its way to the disk, and the
+    // next daemon would boot on a partition older than the last reply this one
+    // gave. The lease goes last: while a write is in flight this box is still
+    // the one holding these wards.
+    async close() {
+        for (const w of this.wards.values())
+            await w.save().catch(() => { });
+        if (!this.#held)
+            return;
+        await unlink(join(this.dir, 'lease')).catch(() => { });
+        HELD.delete(this.dir);
+        this.#held = false;
+    }
+    // Boot a ward whose folder was placed here by hand.
+    async adoptFolder(name) {
+        const kept = await this.store.load(name);
+        if (!kept)
+            throw new Error(`no ward ${name} in ${this.dir}`);
+        return this.host(name, kept);
+    }
+    async #lease() {
+        if (HELD.has(this.dir))
+            throw new Error(`harbor ${this.dir} is held by pid ${process.pid}`);
+        const path = join(this.dir, 'lease');
+        if (existsSync(path)) {
+            const pid = Number(await readFile(path, 'utf8'));
+            let alive = pid !== process.pid; // our own pid with no entry in HELD is a lease we left behind
+            if (alive) {
+                try {
+                    process.kill(pid, 0);
+                }
+                catch (e) {
+                    alive = e.code === 'EPERM'; // EPERM: somebody is home, and not us. anything else: a corpse
+                }
+            }
+            if (alive)
+                throw new Error(`harbor ${this.dir} is held by pid ${pid}`);
+            await unlink(path).catch(() => { }); // the corpse, so the write below can be exclusive
+        }
+        try {
+            await writeFile(path, String(process.pid), { flag: 'wx', mode: 0o600 });
+        }
+        catch {
+            throw new Error(`harbor ${this.dir} is held: another daemon took the lease first`);
+        }
+        HELD.add(this.dir);
+        this.#held = true;
+    }
+}

package/dist/harbor/edge/alarm.d.ts

@@ -0,0 +1,10 @@
+import { Timer } from '../../dock/index.ts';
+import type { Storage } from './platform.d.ts';
+export type Alarms = (at: number | null) => Promise<void>;
+export declare const alarmsIn: (storage: Storage) => Alarms;
+export declare class Alarm extends Timer {
+    #private;
+    alarms: Alarms | undefined;
+    get setting(): Promise<void>;
+    protected arm(when: number | null): void;
+}

package/dist/harbor/edge/alarm.js

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's timer on this terrain. One method of hers knows a platform, the
+// arming, and this replaces it: the object's own storage alarm in place of a
+// `setTimeout` that would die with the request. Everything else about her is
+// the same class, the same door and the same suite, because when a box wakes
+// is a terrain's answer and what it does when it wakes is not.
+//
+// One harbor is one Durable Object, and every ward of it lives in that
+// object, so the alarm wakes the whole harbor and a tick from her to a home's
+// Clock is in-process here as it is on a disk. Only the object may set its
+// own alarm, so the two calls are handed to her after the box ward stands,
+// the way the grants are handed their save: a faculty is built by her ward
+// with a stance and nothing else.
+import { Timer } from '../../dock/index.js';
+export const alarmsIn = (storage) => async (at) => {
+    if (at === null)
+        await storage.deleteAlarm();
+    else
+        await storage.setAlarm(at);
+};
+export class Alarm extends Timer {
+    // Handed in after the box ward stands. A timer holding none arms nothing
+    // and wakes nobody, which is a harbor standing no box ward.
+    alarms;
+    #setting = Promise.resolve();
+    // The arming written, for the device's own code and a suite: on this
+    // terrain an arming is a write to storage, and a reader of the alarm waits
+    // for it. It crosses no door.
+    get setting() {
+        return this.#setting;
+    }
+    arm(when) {
+        // A faculty arms inside whatever ask learned the moment, and a write is
+        // not something that ask can answer for, so this is left to finish on its
+        // own. An alarm the platform refused is armed again by the next round.
+        this.#setting = (this.alarms?.(when) ?? Promise.resolve()).catch(() => { });
+    }
+}

package/dist/harbor/edge/edge.d.ts

@@ -0,0 +1,54 @@
+import type { BeingClass } from '@nervur-org/nervur';
+import { Harbor, Socket as Held } from '@nervur-org/nervur/harbor';
+import { type Folder } from '../../human/web.ts';
+import { Grants } from '../../dock/grants.ts';
+import { type Routes } from '../../mcp/route.ts';
+import { Exchange } from '../../mcp/allow.ts';
+import { DurableStorage, danceInStorage, wearInStorage } from './storage.ts';
+import { type Deployed, type Given, type SettingsStore } from './given.ts';
+import type { State, Env } from './platform.d.ts';
+export declare const BUILT_IN: Record<string, BeingClass>;
+export declare class EdgeHarbor extends Harbor {
+    #private;
+    readonly sockets: Set<Held>;
+    readonly root: string | undefined;
+    readonly deployed: Deployed;
+    readonly settings: SettingsStore;
+    readonly folder: Folder;
+    readonly wear: ReturnType<typeof wearInStorage>;
+    readonly dance: ReturnType<typeof danceInStorage>;
+    static open(state: State, env: Env, deployed?: Deployed): Promise<EdgeHarbor>;
+    constructor(store: DurableStorage, root: string | undefined, deployed?: Deployed);
+    given(): Promise<Given>;
+    lent: Record<string, string> | undefined;
+    ready(): Promise<void>;
+    boot(): Promise<void>;
+    rang(): Promise<void>;
+    get grants(): Grants | undefined;
+    web(request: Request, path: string, base: string): Promise<Response>;
+    routes(base: string): Promise<Routes & {
+        quo: string;
+        api: string;
+    }>;
+    here(): string;
+    api(request: Request, path: string, base: string): Promise<Response>;
+    mcp(request: Request, path: string, base: string): Promise<Response>;
+    wellKnown(request: Request, path: string, base: string): Promise<Response>;
+    exchange(base: string): Promise<Exchange | undefined>;
+    fetch(request: Request, path: string, base: string): Promise<Response>;
+    health(): {
+        ok: boolean;
+        wards: {
+            [k: string]: string;
+        };
+        reaches: {
+            [k: string]: string;
+        };
+        sockets: number;
+        faults: {
+            [k: string]: number;
+        };
+    };
+    upgrade(): Response;
+    rootAsk(request: Request): Promise<Response>;
+}