nervur 0.23.0 → 0.24.0

package/dist/node/hand.d.ts

@@ -1,39 +0,0 @@
-import type { Json } from '../being/being.ts';
-import type { Answer } from '../house/rows-shape.ts';
-export interface Hand {
-    /** Stops listening, and removes the socket. */
-    close(): Promise<void>;
-}
-/**
- * One line to the hand. On a house's own hand, an ask of a being. On a
- * ground's, an ask of a being in the house it names, of the dock's steward
- * where it names none, or `describe` for all it holds.
- */
-export interface HandRequest {
-    readonly house?: string;
-    readonly describe?: true;
-    readonly id?: string;
-    readonly method?: string;
-    readonly args?: {
-        readonly [key: string]: Json;
-    };
-    /** The answer the owner holds, which makes a `readOnly` ask a watch. */
-    readonly after?: Answer;
-    /** Her cells read, and nothing asked. */
-    readonly cells?: true;
-    /** The ask's call id: asked again, it answers what the first answered. */
-    readonly call?: string;
-}
-/**
- * Where a ground's hand stands for its state folder: a socket inside it,
- * or on Windows a named pipe, which has no place in a folder, named for
- * the folder's path.
- */
-export declare const handAt: (state: string, platform?: NodeJS.Platform) => string;
-/**
- * Serves `ask` at `path`: a house's own hand, or a ground's, which also
- * reads `house` and changes its record. A socket left there by a process
- * that is gone is replaced. A named pipe on Windows is open to its user
- * alone, as the operating system makes it, and leaves nothing behind.
- */
-export declare const serveHand: (ask: (request: HandRequest) => Promise<unknown>, path: string) => Promise<Hand>;

package/dist/node/hand.js

@@ -1,107 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The hand on a local socket, or on Windows a named pipe: one JSON object
-// a line in, one answer a line out, in order. It is open to the ground's
-// user alone.
-import { createHash } from 'node:crypto';
-import { chmod } from 'node:fs/promises';
-import { createServer } from 'node:net';
-import { join, resolve as absolute } from 'node:path';
-import { createInterface } from 'node:readline';
-import { gone } from './gone.js';
-const object = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-const request = (line) => {
-    let value;
-    try {
-        value = JSON.parse(line);
-    }
-    catch {
-        return null;
-    }
-    if (!object(value))
-        return null;
-    const { house, describe, id, method, args, after, cells, call, ...rest } = value;
-    if (Object.keys(rest).length > 0)
-        return null;
-    for (const text of [house, id, method, call])
-        if (text !== undefined && typeof text !== 'string')
-            return null;
-    if (args !== undefined && !object(args))
-        return null;
-    if (describe !== undefined && describe !== true)
-        return null;
-    if (cells !== undefined && cells !== true)
-        return null;
-    // An answer is `{ result }` or `{ error }`, and nothing else.
-    if (after !== undefined && !(object(after) && Object.keys(after).length === 1 && ('result' in after || 'error' in after)))
-        return null;
-    return Object.fromEntries(Object.entries({ house, describe, id, method, args, after, cells, call }).filter(([, field]) => field !== undefined));
-};
-const serve = (ask, socket) => {
-    let turn = Promise.resolve();
-    createInterface({ input: socket }).on('line', (line) => {
-        turn = turn.then(async () => {
-            const asked = request(line);
-            const answer = asked === null ? { error: { message: 'bad request' } } : await ask(asked);
-            if (!socket.destroyed)
-                socket.write(`${JSON.stringify(answer)}\n`);
-        });
-    });
-    socket.on('error', () => undefined);
-};
-// A local socket's path fits the kernel's address: 103 bytes on macOS and
-// the BSDs, 107 on Linux, with the closing zero beyond.
-const LONGEST = process.platform === 'linux' ? 107 : 103;
-const PIPE = /^\\\\[.?]\\pipe\\/;
-/**
- * Where a ground's hand stands for its state folder: a socket inside it,
- * or on Windows a named pipe, which has no place in a folder, named for
- * the folder's path.
- */
-export const handAt = (state, platform = process.platform) => platform === 'win32' ? `\\\\.\\pipe\\nervur-${createHash('sha256').update(absolute(state).toLowerCase()).digest('hex').slice(0, 16)}` : join(state, 'hand');
-/**
- * Serves `ask` at `path`: a house's own hand, or a ground's, which also
- * reads `house` and changes its record. A socket left there by a process
- * that is gone is replaced. A named pipe on Windows is open to its user
- * alone, as the operating system makes it, and leaves nothing behind.
- */
-export const serveHand = async (ask, path) => {
-    if (PIPE.test(path))
-        return listen(ask, path, false);
-    const length = Buffer.byteLength(path);
-    if (length > LONGEST)
-        throw new Error(`a socket's path is at most ${LONGEST} bytes here, and ${path} is ${length}: serve the hand from a shorter folder`);
-    await gone(path);
-    return listen(ask, path, true);
-};
-const listen = async (ask, path, file) => {
-    const server = createServer((socket) => serve(ask, socket));
-    const sockets = new Set();
-    server.on('connection', (socket) => {
-        sockets.add(socket);
-        socket.on('close', () => sockets.delete(socket));
-    });
-    await new Promise((resolve, reject) => {
-        server.once('error', reject);
-        if (!file)
-            return void server.listen(path, () => resolve());
-        // Closed to everyone from the first moment, then opened to the user.
-        const mask = process.umask(0o177);
-        try {
-            server.listen(path, () => resolve());
-        }
-        finally {
-            process.umask(mask);
-        }
-    });
-    if (file)
-        await chmod(path, 0o600);
-    return {
-        close: async () => {
-            for (const socket of sockets)
-                socket.destroy();
-            await new Promise((resolve) => server.close(() => resolve()));
-            if (file)
-                await gone(path);
-        },
-    };
-};

package/dist/node/http.d.ts

@@ -1,11 +0,0 @@
-import type { Handler } from '../bodies/web-carry.ts';
-export interface Served {
-    /** The port it listens on. */
-    readonly port: number;
-    close(): Promise<void>;
-}
-/** Listens on `port`, `0` for one the system picks, and hands every request to `handlers` in order. */
-export declare const serveHttp: ({ port, host }: {
-    port?: number;
-    host?: string;
-}, handlers: readonly Handler[]) => Promise<Served>;

package/dist/node/http.js

@@ -1,90 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// One HTTP listener for a ground, chaining its handlers: each request goes
-// to the first handler that answers it, and each WebSocket to the first
-// that takes it. `WebCarry` is one handler, and every face is another, so
-// a ground holds one port whatever speaks HTTP on it.
-import { createServer } from 'node:http';
-import { acceptOf, hold } from './websocket.js';
-/** The longest request body a handler is handed, and the longest WebSocket message. */
-const LONGEST = 8 * 1024 * 1024;
-const requestOf = (message, body) => {
-    const headers = new Headers();
-    for (let index = 0; index + 1 < message.rawHeaders.length; index += 2)
-        headers.append(message.rawHeaders[index], message.rawHeaders[index + 1]);
-    const url = `http://${message.headers.host ?? 'localhost'}${message.url ?? '/'}`;
-    return new Request(url, { method: message.method ?? 'GET', headers, ...(body === null ? {} : { body: new Uint8Array(body) }) });
-};
-const read = (message) => new Promise((resolve) => {
-    const chunks = [];
-    let length = 0;
-    message.on('data', (chunk) => {
-        length += chunk.length;
-        if (length > LONGEST) {
-            resolve(null);
-            message.destroy();
-            return;
-        }
-        chunks.push(chunk);
-    });
-    message.on('end', () => resolve(Buffer.concat(chunks)));
-    message.on('error', () => resolve(null));
-});
-/** Listens on `port`, `0` for one the system picks, and hands every request to `handlers` in order. */
-export const serveHttp = async ({ port = 0, host = '0.0.0.0' }, handlers) => {
-    const sockets = new Set();
-    const server = createServer(async (message, response) => {
-        try {
-            const bodied = message.method !== 'GET' && message.method !== 'HEAD';
-            const body = bodied ? await read(message) : null;
-            if (bodied && body === null) {
-                response.writeHead(413).end();
-                return;
-            }
-            const request = requestOf(message, body);
-            for (const handler of handlers) {
-                const answered = await handler.fetch(request);
-                if (answered === null)
-                    continue;
-                response.writeHead(answered.status, Object.fromEntries(answered.headers));
-                response.end(Buffer.from(await answered.arrayBuffer()));
-                return;
-            }
-            response.writeHead(404).end();
-        }
-        catch {
-            if (!response.headersSent)
-                response.writeHead(500);
-            response.end();
-        }
-    });
-    server.on('connection', (socket) => {
-        sockets.add(socket);
-        socket.on('close', () => sockets.delete(socket));
-    });
-    server.on('upgrade', (message, socket, head) => {
-        const key = message.headers['sec-websocket-key'];
-        const request = requestOf(message, null);
-        const taken = typeof key === 'string' && message.headers['sec-websocket-version'] === '13' ? handlers.map((handler) => handler.upgrade?.(request) ?? null).find((one) => one !== null) : undefined;
-        if (taken === undefined || typeof key !== 'string') {
-            socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n');
-            return;
-        }
-        socket.write(['HTTP/1.1 101 Switching Protocols', 'Upgrade: websocket', 'Connection: Upgrade', `Sec-WebSocket-Accept: ${acceptOf(key)}`, `Sec-WebSocket-Protocol: ${taken.protocol}`, '', ''].join('\r\n'));
-        hold(socket, taken.open, LONGEST);
-        if (head.length > 0)
-            socket.unshift(head);
-    });
-    await new Promise((resolve, reject) => {
-        server.once('error', reject);
-        server.listen(port, host, () => resolve());
-    });
-    const address = server.address();
-    return {
-        port: typeof address === 'object' && address !== null ? address.port : port,
-        close: async () => {
-            for (const socket of sockets)
-                socket.destroy();
-            await new Promise((resolve) => server.close(() => resolve()));
-        },
-    };
-};

package/dist/node/index.d.ts

@@ -1,11 +0,0 @@
-export { NodeGround } from './node-ground.ts';
-export { bridge } from './bridge.ts';
-export { FileMemory } from './file-memory.ts';
-export { FolderClasses } from './folder-classes.ts';
-export { serveHand } from './hand.ts';
-export { serveHttp, type Served } from './http.ts';
-export { LedgerMemory } from './ledger-memory.ts';
-export { takeLock } from './lock.ts';
-export { notifyReady } from './notify.ts';
-export { TcpCarry } from './tcp-carry.ts';
-export { FileUnlock, KeychainUnlock } from './unlock.ts';

package/dist/node/index.js

@@ -1,13 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// `nervur/node`: the bodies a ground on Node passes, and what it runs beside them.
-export { NodeGround } from './node-ground.js';
-export { bridge } from './bridge.js';
-export { FileMemory } from './file-memory.js';
-export { FolderClasses } from './folder-classes.js';
-export { serveHand } from './hand.js';
-export { serveHttp } from './http.js';
-export { LedgerMemory } from './ledger-memory.js';
-export { takeLock } from './lock.js';
-export { notifyReady } from './notify.js';
-export { TcpCarry } from './tcp-carry.js';
-export { FileUnlock, KeychainUnlock } from './unlock.js';

package/dist/node/ledger-memory.d.ts

@@ -1,17 +0,0 @@
-import type { Memory, PlaceRead } from '../foundation.ts';
-type Writes = Readonly<Record<string, Readonly<Record<string, Uint8Array | null>>>>;
-export declare class LedgerMemory implements Memory {
-    #private;
-    constructor(at: string | URL, { witness }?: {
-        witness?: string | URL;
-    });
-    read({ place }: {
-        place: string;
-    }): Promise<PlaceRead>;
-    list(): Promise<readonly string[]>;
-    write(options: {
-        writes: Writes;
-        expect: Readonly<Record<string, string | null>>;
-    }): Promise<Readonly<Record<string, string | null>> | null>;
-}
-export {};

package/dist/node/ledger-memory.js

@@ -1,152 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Memory as a ledger: every write appended as one line, never rewritten.
-// Each line carries its sequence and the hash of the line before it, and
-// is synced before its write counts. So the file is also the whole record
-// of what the house wrote. A witness, where the ground names one, keeps
-// the last sequence and hash in a second place, and a ledger behind it is
-// refused: a restored copy cannot replay what the house already answered.
-import { createHash } from 'node:crypto';
-import { mkdir, open, readFile, rename, truncate } from 'node:fs/promises';
-import { dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { syncFolder } from './sync-folder.js';
-const GENESIS = { n: 0, hash: '0'.repeat(64) };
-const hash = (text) => createHash('sha256').update(text).digest('hex');
-const unhex = (text) => new Uint8Array(Buffer.from(text, 'hex'));
-const path = (at) => (typeof at === 'string' ? at : fileURLToPath(at));
-/** Opens a file, runs `work` on it, syncs it and lets it go. */
-const synced = async (file, flags, work) => {
-    const handle = await open(file, flags, 0o600);
-    try {
-        await work(handle);
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-};
-/** A line laid on the places: each place it names takes the line's sequence as its version. */
-const apply = (places, line) => {
-    const version = String(line.n);
-    const versions = {};
-    for (const [place, entries] of Object.entries(line.writes)) {
-        const held = places.get(place) ?? { version, entries: new Map() };
-        for (const [name, value] of Object.entries(entries)) {
-            if (value === null)
-                held.entries.delete(name);
-            else
-                held.entries.set(name, value);
-        }
-        held.version = version;
-        if (held.entries.size === 0)
-            places.delete(place);
-        else
-            places.set(place, held);
-        versions[place] = held.entries.size === 0 ? null : version;
-    }
-    return versions;
-};
-export class LedgerMemory {
-    #path;
-    #witness;
-    #state;
-    #turn = Promise.resolve();
-    constructor(at, { witness } = {}) {
-        this.#path = path(at);
-        this.#witness = witness === undefined ? undefined : path(witness);
-    }
-    #open() {
-        this.#state ??= this.#load();
-        this.#state.catch(() => (this.#state = undefined));
-        return this.#state;
-    }
-    async #load() {
-        await mkdir(dirname(this.#path), { recursive: true });
-        let text = '';
-        try {
-            text = await readFile(this.#path, 'utf8');
-        }
-        catch (error) {
-            if (error.code !== 'ENOENT')
-                throw error;
-        }
-        // A last line with no newline was never synced whole, so its write never
-        // counted: it is cut away.
-        const whole = text.lastIndexOf('\n') + 1;
-        if (whole < text.length)
-            await truncate(this.#path, Buffer.byteLength(text.slice(0, whole)));
-        const places = new Map();
-        let head = GENESIS;
-        for (const raw of text.slice(0, whole).split('\n').slice(0, -1)) {
-            const line = JSON.parse(raw);
-            if (line.n !== head.n + 1 || line.prev !== head.hash)
-                throw new Error(`the ledger ${this.#path} is broken at line ${head.n + 1}`);
-            apply(places, line);
-            head = { n: line.n, hash: hash(raw) };
-        }
-        const witnessed = this.#witness === undefined ? null : await this.#witnessed();
-        if (witnessed !== null && (head.n < witnessed.n || (head.n === witnessed.n && head.hash !== witnessed.hash))) {
-            throw new Error(`the ledger ${this.#path} is behind its witness: it holds ${head.n} lines, and the witness saw ${witnessed.n}`);
-        }
-        return { places, head };
-    }
-    async #witnessed() {
-        try {
-            return JSON.parse(await readFile(this.#witness, 'utf8'));
-        }
-        catch (error) {
-            if (error.code === 'ENOENT')
-                return null;
-            throw error;
-        }
-    }
-    async #attest(head) {
-        const temporary = `${this.#witness}.${process.pid}.tmp`;
-        await synced(temporary, 'w', (handle) => handle.writeFile(JSON.stringify(head)));
-        await rename(temporary, this.#witness);
-        await syncFolder(dirname(this.#witness));
-    }
-    async read({ place }) {
-        const held = (await this.#open()).places.get(place);
-        if (held === undefined)
-            return { entries: {}, version: null };
-        return { entries: Object.fromEntries([...held.entries].map(([name, value]) => [name, unhex(value)])), version: held.version };
-    }
-    async list() {
-        return [...(await this.#open()).places.keys()];
-    }
-    write(options) {
-        const turn = this.#turn.then(() => this.#write(options));
-        this.#turn = turn.catch(() => undefined);
-        return turn;
-    }
-    async #write({ writes, expect }) {
-        const state = await this.#open();
-        for (const place of new Set([...Object.keys(writes), ...Object.keys(expect)])) {
-            if (!(place in expect) || expect[place] !== (state.places.get(place)?.version ?? null))
-                return null;
-        }
-        const line = {
-            n: state.head.n + 1,
-            prev: state.head.hash,
-            writes: Object.fromEntries(Object.entries(writes).map(([place, entries]) => [place, Object.fromEntries(Object.entries(entries).map(([name, bytes]) => [name, bytes === null ? null : Buffer.from(bytes).toString('hex')]))])),
-        };
-        const raw = JSON.stringify(line);
-        const head = { n: line.n, hash: hash(raw) };
-        try {
-            await synced(this.#path, 'a', (handle) => handle.appendFile(`${raw}\n`));
-            if (line.n === 1)
-                await syncFolder(dirname(this.#path));
-            if (this.#witness !== undefined)
-                await this.#attest(head);
-        }
-        catch (error) {
-            // What landed is read again from the file: a torn line is cut, and a
-            // whole one stands. The write answers as failed either way.
-            this.#state = undefined;
-            throw error;
-        }
-        state.head = head;
-        return apply(state.places, line);
-    }
-}

package/dist/node/lock.d.ts

@@ -1,10 +0,0 @@
-export interface Lock {
-    /** Lets the lock go, where this process still holds it. */
-    release(): Promise<void>;
-}
-/**
- * Takes the lock of `dir`, or refuses where a living process holds it.
- * The file is written whole beside the lock and linked into place, so a
- * lock is never seen half written, and two takers never both land.
- */
-export declare const takeLock: (dir: string) => Promise<Lock>;

package/dist/node/lock.js

@@ -1,78 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// One instance per folder. The lock is a file named `lock` holding the
-// process id that took it. A lock whose process is gone is taken over.
-import { link, readFile, rename, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { gone } from './gone.js';
-const alive = (pid) => {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return error.code === 'EPERM';
-    }
-};
-const holder = async (path) => {
-    try {
-        const pid = Number((await readFile(path, 'utf8')).trim());
-        return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return null;
-        throw error;
-    }
-};
-/**
- * Takes the lock of `dir`, or refuses where a living process holds it.
- * The file is written whole beside the lock and linked into place, so a
- * lock is never seen half written, and two takers never both land.
- */
-export const takeLock = async (dir) => {
-    const path = join(dir, 'lock');
-    const mine = join(dir, `lock.${process.pid}`);
-    await writeFile(mine, `${process.pid}\n`, { mode: 0o600 });
-    try {
-        for (let attempt = 0; attempt < 3; attempt++) {
-            try {
-                await link(mine, path);
-                return {
-                    release: async () => {
-                        if ((await holder(path)) === process.pid)
-                            await gone(path);
-                    },
-                };
-            }
-            catch (error) {
-                if (error.code !== 'EEXIST')
-                    throw error;
-            }
-            const pid = await holder(path);
-            if (pid !== null && alive(pid))
-                throw new Error(`process ${pid} holds the lock of ${dir}`);
-            // Set aside what stands; where a living lock was set aside instead,
-            // it goes back and this taker refuses.
-            const aside = join(dir, `lock.stale.${process.pid}`);
-            try {
-                await rename(path, aside);
-            }
-            catch (error) {
-                if (error.code === 'ENOENT')
-                    continue;
-                throw error;
-            }
-            const took = await holder(aside);
-            if (took !== pid && took !== null && alive(took)) {
-                await link(aside, path).catch(() => undefined);
-                await gone(aside);
-                throw new Error(`process ${took} holds the lock of ${dir}`);
-            }
-            await gone(aside);
-        }
-        throw new Error(`the lock of ${dir} is contended`);
-    }
-    finally {
-        await gone(mine);
-    }
-};

package/dist/node/node-ground.d.ts

@@ -1,26 +0,0 @@
-import { Ground, type Unlock } from '../ground/ground.ts';
-export interface NodeGroundOptions {
-    /** The folder of its code: a folder for each house, and each module or program its entries name. */
-    readonly folder: string;
-    /** The folder of its state; `NERVUR_STATE`, or `<folder>/state`, where none is named. */
-    readonly state?: string;
-    /**
-     * What opens its drawer and its hand, and nothing else: `NERVUR_STATE`,
-     * `NERVUR_UNLOCK` and `NERVUR_HAND`. The process's own where none are
-     * named. Every other setting is an entry the dock holds.
-     */
-    readonly env?: Readonly<Record<string, string | undefined>>;
-    /** Its unlock, where the host opens the ground from its own code; `NERVUR_UNLOCK`'s, or the key file in its state, where omitted. */
-    readonly unlock?: Unlock;
-}
-export declare class NodeGround {
-    readonly ground: Ground;
-    /** The socket of the ground's hand. */
-    readonly hand: string;
-    private constructor();
-    /** The port HTTP listens on, where its web carry listens: a cell of the web's twin, read through the hand. */
-    port(): Promise<number | undefined>;
-    static open({ folder: given, state: stateGiven, env, unlock }: NodeGroundOptions): Promise<NodeGround>;
-    /** A stop is the boot reversed: the hand, the houses and every body, then the ledger and its lock. */
-    close(): Promise<void>;
-}