nervur 0.22.0 → 0.22.2-3

package/dist/core/harbor/package.js

@@ -1,172 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The package: a harbor's memory, sealed under the harbor's seed. The
-// terrain keeps its bytes and reads neither a ward's name, nor a being's
-// key, nor anything a row holds.
-//
-//   key            HKDF-SHA-256 of the seed under `nervur-package`
-//   place          16 bytes under ["place", ward], as hex
-//   entry          16 bytes under ["entry", ward, row], as hex
-//   seal           32 bytes under ["seal", ward]
-//   entry bytes    nonce (12) || AES-256-GCM( JSON { row, value } ),
-//                  the entry's name as additional data
-//
-// A row is the head, under the empty name, or one being, under her key. An
-// entry that does not open refuses the whole ward, so nothing unpacks from
-// bytes the package did not seal.
-import { concat, decrypt, encrypt, hex, hkdf, isHex, unhex, utf8 } from '../crypto/index.js';
-import { HEAD_ROW } from '../ward/index.js';
-// Every place of one memory, written into another, and the places
-// carried. The bytes are the package's own, sealed under a seed neither
-// memory holds, so a harbor opened on the second memory under that seed
-// stands what the first one stood. A place the second memory already
-// holds is written over.
-export const copyPackage = async (from, to) => {
-    const places = await from.places();
-    for (const place of places)
-        await to.write(place, await from.read(place));
-    return places;
-};
-// A carried harbor as JSON reads, or null for anything else.
-export const readCarried = (value) => {
-    if (typeof value !== 'object' || value === null)
-        return null;
-    const { seed, places } = value;
-    if (seed !== undefined && !isHex(seed, 32))
-        return null;
-    if (typeof places !== 'object' || places === null || Array.isArray(places))
-        return null;
-    for (const entries of Object.values(places)) {
-        if (typeof entries !== 'object' || entries === null || Array.isArray(entries))
-            return null;
-        for (const bytes of Object.values(entries))
-            if (!isHex(bytes))
-                return null;
-    }
-    return { ...(seed === undefined ? {} : { seed }), places: places };
-};
-// Every place of a memory, as a carried harbor holds it.
-export const carryPlaces = async (memory) => {
-    const places = {};
-    for (const place of await memory.places()) {
-        places[place] = Object.fromEntries([...(await memory.read(place))].map(([name, bytes]) => [name, hex(bytes)]));
-    }
-    return places;
-};
-// A carried harbor's places, written into a memory, and their names.
-export const landPlaces = async (memory, carried) => {
-    for (const [place, entries] of Object.entries(carried.places)) {
-        await memory.write(place, new Map(Object.entries(entries).map(([name, bytes]) => [name, unhex(bytes)])));
-    }
-    return Object.keys(carried.places);
-};
-const NONCE = 12;
-const LABEL = utf8('nervur-package');
-class PackageRows {
-    rows;
-    #ward;
-    #told = new Set();
-    #line = Promise.resolve(true);
-    constructor(ward, rows) {
-        this.#ward = ward;
-        this.rows = rows;
-    }
-    told(row) {
-        this.#told.add(row);
-    }
-    // Every row told since the last keep, sealed and written as one keep, one
-    // keep at a time. Where nothing was told, nothing is written, so an ask
-    // that only reads keeps even where the keeper refuses every write.
-    kept() {
-        const rows = [...this.#told];
-        this.#told.clear();
-        this.#line = this.#line.then(() => this.#write(rows)).catch(() => false);
-        return this.#line;
-    }
-    async #write(told) {
-        if (told.length === 0)
-            return true;
-        const beings = (this.rows.beings ?? {});
-        const entries = new Map();
-        for (const row of told) {
-            const value = row === HEAD_ROW ? (this.rows.ward ?? null) : Object.hasOwn(beings, row) ? beings[row] : undefined;
-            entries.set(await this.#ward.entry(row), value === undefined ? null : await this.#ward.seal(row, value));
-        }
-        await this.#ward.write(entries);
-        return true;
-    }
-}
-class WardPlace {
-    #pack;
-    #name;
-    #seal;
-    #keeper;
-    place;
-    constructor(pack, name, seal, place, keeper) {
-        this.#pack = pack;
-        this.#name = name;
-        this.#seal = seal;
-        this.place = place;
-        this.#keeper = keeper;
-    }
-    read() {
-        return this.#keeper.read(this.place);
-    }
-    entry(row) {
-        return this.#pack.derive(['entry', this.#name, row], 16).then(hex);
-    }
-    async seal(row, value) {
-        const nonce = this.#pack.entropy.draw(NONCE);
-        const text = utf8(JSON.stringify({ row, value }));
-        return concat(nonce, await encrypt(this.#seal, nonce, utf8(await this.entry(row)), text));
-    }
-    // The name is the additional data, so an entry moved under another name
-    // does not open either.
-    async open(name, bytes) {
-        const text = bytes.length > NONCE ? await decrypt(this.#seal, bytes.subarray(0, NONCE), utf8(name), bytes.subarray(NONCE)) : null;
-        if (text === null)
-            throw new Error('an entry the package did not seal');
-        return JSON.parse(new TextDecoder().decode(text));
-    }
-    write(entries) {
-        return this.#keeper.write(this.place, entries);
-    }
-}
-export class Package {
-    memory;
-    entropy;
-    #key;
-    constructor(memory, entropy, key) {
-        this.memory = memory;
-        this.entropy = entropy;
-        this.#key = key;
-    }
-    static async open(memory, entropy, seed) {
-        return new Package(memory, entropy, await hkdf(seed, LABEL, 32));
-    }
-    derive(info, length) {
-        return hkdf(this.#key, utf8(JSON.stringify(info)), length);
-    }
-    // The place a ward's rows live in.
-    place(name) {
-        return this.derive(['place', name], 16).then(hex);
-    }
-    // One ward's rows, as its keeper kept them: the root memory unless a
-    // memory faculty is named.
-    async rows(name, keeper = this.memory) {
-        const ward = new WardPlace(this, name, await this.derive(['seal', name], 32), await this.place(name), keeper);
-        const rows = {};
-        const beings = {};
-        let any = false;
-        for (const [entry, bytes] of await ward.read()) {
-            const { row, value } = await ward.open(entry, bytes);
-            any = true;
-            if (row === HEAD_ROW)
-                rows.ward = value;
-            else
-                beings[row] = value;
-        }
-        if (any)
-            rows.beings = beings;
-        return new PackageRows(ward, rows);
-    }
-}

package/dist/core/harbor/probe.d.ts

@@ -1,22 +0,0 @@
-import type { Bundled } from '../contract/index.ts';
-import type { Defaults, Terrain } from './terrain.ts';
-export type Probing = {
-    readonly where?: string;
-    readonly given?: unknown;
-    readonly bundle?: readonly Bundled[];
-};
-export type GroundProbe = {
-    readonly name: string;
-    fits(probing: Probing): boolean;
-    terrain(probing: Probing, defaults: Defaults): Terrain;
-};
-export type KnownGround = {
-    readonly probe: GroundProbe;
-    readonly defaults: Defaults;
-};
-export declare const addGround: (probe: GroundProbe, defaults: Defaults) => void;
-export declare const grounds: () => string[];
-export declare const probeGround: (probing: Probing, among?: readonly KnownGround[]) => {
-    ground: string;
-    terrain: Terrain;
-};

package/dist/core/harbor/probe.js

@@ -1,15 +0,0 @@
-const known = [];
-// A ground this process can stand on, known once by its name.
-export const addGround = (probe, defaults) => {
-    if (!known.some((k) => k.probe.name === probe.name))
-        known.push({ probe, defaults });
-};
-// The grounds known, in the order they are tried.
-export const grounds = () => known.map((k) => k.probe.name).reverse();
-// The terrain of the first ground that fits, and its name.
-export const probeGround = (probing, among = known) => {
-    for (const { probe, defaults } of [...among].reverse())
-        if (probe.fits(probing))
-            return { ground: probe.name, terrain: probe.terrain(probing, defaults) };
-    throw new Error('no ground fits here');
-};

package/dist/core/harbor/registry.d.ts

@@ -1,15 +0,0 @@
-import { Faculty, type BeingClass } from '../being/index.ts';
-import type { Module } from '../contract/index.ts';
-export declare const REGISTRY = "org.nervur.registry";
-export declare abstract class RegistryFaculty extends Faculty {
-    static readonly kind: string;
-    abstract classOf(kind: string): BeingClass | undefined;
-}
-export declare const registers: (C: unknown) => C is typeof RegistryFaculty;
-export declare class Registry {
-    #private;
-    constructor(kit: readonly BeingClass[], modules: readonly Module[]);
-    static refusal(kit: readonly BeingClass[], modules: readonly Module[]): string | null;
-    classOf(kind: string): BeingClass | undefined;
-    kindsOf(module: string): string[];
-}

package/dist/core/harbor/registry.js

@@ -1,110 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The catalogue's index: every kind the harbor runs, from the kit's own
-// classes and the modules the catalogue loaded. It resolves a kind a row
-// keeps, and decides nothing about what stands. It refuses any set of
-// modules two readings could split:
-//
-//   a module whose name is no kind, or is the kit's, or two of one name
-//   a class with no kind of its own, or one outside its module's domain
-//   two classes of one kind, or one kind in two modules
-//   a contract with no kind of its own, or one kind for two contracts
-//   a class above a module's class of a kit kind that the kit does not ship
-//   a kind that is a class and a contract
-//
-// A module's domain is its name's first two segments: `com.acme.shop`
-// stands classes under `com.acme.` alone. A contract may be any domain's,
-// so a faculty fulfils a contract another module declares. A module's
-// class may extend any class or contract the kit ships, and never declares
-// one of a kit kind itself. Two harbors hold two registries, and nothing
-// between them names a class.
-import { Faculty, isKind, KIT, kindOf, ownKind, shipped, ships } from '../being/index.js';
-const domainOf = (name) => `${name.split('.').slice(0, 2).join('.')}.`;
-export const REGISTRY = 'org.nervur.registry';
-// The registry faculty: a faculty of the box ward that resolves the kind a
-// row keeps to a class. The catalogue is the core's, and resolves through
-// the DNA. Any other is an owner's, stood by the registry named on its row,
-// and each being of the box, and each hosted ward whole, names the registry
-// its classes come from.
-export class RegistryFaculty extends Faculty {
-    static kind = REGISTRY;
-    static {
-        ships(this);
-    }
-}
-// Whether a class is a registry faculty's.
-export const registers = (C) => typeof C === 'function' && C.prototype instanceof RegistryFaculty;
-export class Registry {
-    #classes = new Map();
-    #modules = new Map();
-    // `kit` holds the kit's own classes, which alone may be of its kinds.
-    constructor(kit, modules) {
-        const contracts = new Map();
-        const owners = new Map();
-        const add = (C, kind) => {
-            if (this.#classes.has(kind) && this.#classes.get(kind) !== C)
-                throw new Error(`two classes are of kind ${kind}`);
-            this.#classes.set(kind, C);
-        };
-        for (const C of kit)
-            add(C, kindOf(C));
-        for (const m of modules) {
-            if (!isKind(m.module) || m.module.startsWith(KIT))
-                throw new Error(`module ${String(m.module)} is no name a module may take`);
-            if (this.#modules.has(m.module))
-                throw new Error(`two modules are named ${m.module}`);
-            if (typeof m.version !== 'string' || m.version === '')
-                throw new Error(`module ${m.module} declares no version`);
-            const kinds = [];
-            for (const C of m.classes) {
-                if (typeof C !== 'function')
-                    throw new Error(`module ${m.module} holds something that is no class`);
-                const kind = kindOf(C);
-                if (!kind.startsWith(domainOf(m.module)))
-                    throw new Error(`kind ${kind} is outside module ${m.module}`);
-                const owner = owners.get(kind);
-                if (owner !== undefined && owner !== m.module)
-                    throw new Error(`kind ${kind} is in modules ${owner} and ${m.module}`);
-                owners.set(kind, m.module);
-                add(C, kind);
-                kinds.push(kind);
-                for (let c = Object.getPrototypeOf(C); typeof c === 'function'; c = Object.getPrototypeOf(c)) {
-                    if (ownKind(c)?.startsWith(KIT) && !shipped(c))
-                        throw new Error(`kind ${ownKind(c)} is the kit's`);
-                }
-                if (!Faculty.fulfils(C))
-                    continue;
-                for (let c = Object.getPrototypeOf(C); c !== Faculty; c = Object.getPrototypeOf(c)) {
-                    const contract = kindOf(c);
-                    if (shipped(c))
-                        continue;
-                    if (contracts.has(contract) && contracts.get(contract) !== c)
-                        throw new Error(`two contracts are of kind ${contract}`);
-                    contracts.set(contract, c);
-                }
-            }
-            this.#modules.set(m.module, kinds);
-        }
-        for (const kind of contracts.keys()) {
-            if (this.#classes.has(kind))
-                throw new Error(`kind ${kind} is a class and a contract`);
-        }
-    }
-    // Why a registry of these modules would be refused, or null.
-    static refusal(kit, modules) {
-        try {
-            const registry = new Registry(kit, modules);
-            void registry;
-            return null;
-        }
-        catch (e) {
-            return e.message;
-        }
-    }
-    classOf(kind) {
-        return this.#classes.get(kind);
-    }
-    // The kinds a module stands, or none.
-    kindsOf(module) {
-        return [...(this.#modules.get(module) ?? [])];
-    }
-}

package/dist/core/harbor/root-line.d.ts

@@ -1,7 +0,0 @@
-import type { JsonObject } from '../being/index.ts';
-export type RootRequest = {
-    ward?: string;
-    method?: string;
-    args?: JsonObject;
-};
-export declare const readRootRequest: (value: unknown) => RootRequest | null;

package/dist/core/harbor/root-line.js

@@ -1,9 +0,0 @@
-const object = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
-export const readRootRequest = (value) => {
-    if (!object(value))
-        return null;
-    const { ward, method, args } = value;
-    if ((ward !== undefined && typeof ward !== 'string') || (method !== undefined && typeof method !== 'string') || (args !== undefined && !object(args)))
-        return null;
-    return { ...(ward === undefined ? {} : { ward }), ...(method === undefined ? {} : { method }), ...(args === undefined ? {} : { args }) };
-};

package/dist/core/harbor/terrain.d.ts

@@ -1,25 +0,0 @@
-import type { BeingClass } from '../being/index.ts';
-import type { Carrier, Clock, Custody, Entropy, Loader, Memory } from '../contract/index.ts';
-import type { Sockets, WebServe } from './carrying.ts';
-import type { Harbor } from './harbor.ts';
-export type Defaults = {
-    readonly dock: BeingClass;
-    readonly ward: BeingClass;
-    readonly classes: readonly BeingClass[];
-};
-export declare abstract class Terrain {
-    abstract readonly entropy: Entropy;
-    abstract readonly clock: Clock;
-    abstract readonly custody: Custody;
-    abstract readonly memory: Memory;
-    abstract readonly loader: Loader;
-    abstract readonly carrier: Carrier;
-    abstract readonly defaults: Defaults;
-    readonly tcp: (() => Sockets) | undefined;
-    readonly web: WebServe | undefined;
-    readonly wakes: boolean;
-    get foreground(): boolean;
-    claim(): Promise<void>;
-    stand(_harbor: Harbor): Promise<void>;
-    release(): Promise<void>;
-}

package/dist/core/harbor/terrain.js

@@ -1,28 +0,0 @@
-export class Terrain {
-    // The platform under the carriers, where this ground has one: the sockets
-    // TCP is spoken on, one set for each carrier that asks, and the listener
-    // the web carrier runs.
-    tcp = undefined;
-    web = undefined;
-    // Whether its carriers wake and listen where their cells say. A harbor
-    // opened for one ask and closed again dials and hears nothing.
-    wakes = true;
-    // Whether the harbor lives only as long as a screen: a tab's, or a worker
-    // one tab owns. It is reached only while that screen is open, and hears
-    // no push, so its census says so.
-    get foreground() {
-        return false;
-    }
-    // Before the harbor opens: a terrain whose ground another run holds
-    // refuses here. Once it stands: whatever the ground serves beside it.
-    // Once its carriers sleep: what that served, gone.
-    claim() {
-        return Promise.resolve();
-    }
-    stand(_harbor) {
-        return Promise.resolve();
-    }
-    release() {
-        return Promise.resolve();
-    }
-}

package/dist/core/http/index.d.ts

@@ -1,2 +0,0 @@
-import type { WebServe } from '../harbor/index.ts';
-export declare const webServe: WebServe;

package/dist/core/http/index.js

@@ -1,154 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// `nervur/http`: the web carrier's listener on Node's HTTP server, an entry
-// that names a platform.
-//
-//   webServe   answers posts at a path, and held lines opened to that path
-//              with the subprotocol `quo`, for the ground it is handed:
-//              the body a Node terrain hands the web carrier
-//
-// A post is one ask: 200 with the reply's box, or 204 for nothing. A post
-// to another path is 404, another method 405, a body that is no ask 400.
-// A page of an origin the cells name, or of any origin under `*`, is
-// answered as the CORS protocol says, its preflight included. A held line
-// carries one frame body to a binary message; a text message, a body that
-// is no frame, or bytes that break RFC 6455 close it, and nothing after
-// them is read.
-import { createServer } from 'node:http';
-import { MAX_BODY, MAX_POST, nothingBody, readBody, readPost, replyBody } from '../line/index.js';
-import { hex } from '../crypto/index.js';
-import { tcpAt } from '../quo/index.js';
-import { acceptKey, frameOf, isClientKey, OP, WsReader } from './websocket.js';
-const pathOf = (url) => {
-    const at = (url ?? '/').indexOf('?');
-    return at < 0 ? (url ?? '/') : (url ?? '/').slice(0, at);
-};
-const originOf = (origins, origin) => {
-    if (origin === undefined)
-        return null;
-    if (origins.includes('*'))
-        return '*';
-    return origins.includes(origin) ? origin : null;
-};
-// The bytes of a request, up to one more than `max`, as they came.
-const bodyOf = (request, max) => new Promise((resolve, reject) => {
-    const parts = [];
-    let length = 0;
-    request.on('data', (chunk) => {
-        if (length > max)
-            return;
-        parts.push(chunk);
-        length += chunk.length;
-    });
-    request.on('end', () => {
-        const out = new Uint8Array(length);
-        let at = 0;
-        for (const part of parts) {
-            out.set(part, at);
-            at += part.length;
-        }
-        resolve(out);
-    });
-    request.on('error', reject);
-});
-const post = async (ground, listen, request, response) => {
-    const allowed = originOf(listen.origins, request.headers.origin);
-    if (allowed !== null)
-        response.setHeader('access-control-allow-origin', allowed);
-    if (pathOf(request.url) !== listen.path)
-        return void response.writeHead(404).end();
-    if (request.method === 'OPTIONS') {
-        if (allowed !== null) {
-            response.setHeader('access-control-allow-methods', 'POST');
-            response.setHeader('access-control-allow-headers', 'content-type');
-        }
-        return void response.writeHead(204).end();
-    }
-    if (request.method !== 'POST')
-        return void response.writeHead(405, { allow: 'POST, OPTIONS' }).end();
-    const ask = readPost(await bodyOf(request, MAX_POST));
-    if (ask === null)
-        return void response.writeHead(400).end();
-    let reply = null;
-    try {
-        reply = await ground.arrive(ask.pk, ask.box);
-    }
-    catch {
-        reply = null;
-    }
-    if (reply === null || reply.length === 0)
-        return void response.writeHead(204).end();
-    response.writeHead(200, { 'content-type': 'application/octet-stream' }).end(reply);
-};
-const upgrade = (ground, listen, request, socket) => {
-    const key = request.headers['sec-websocket-key'];
-    const offered = String(request.headers['sec-websocket-protocol'] ?? '')
-        .split(',')
-        .map((p) => p.trim());
-    const fine = pathOf(request.url) === listen.path && request.headers['sec-websocket-version'] === '13' && isClientKey(key) && offered.includes('quo');
-    if (!fine) {
-        socket.end('HTTP/1.1 400 Bad Request\r\nconnection: close\r\ncontent-length: 0\r\n\r\n');
-        return;
-    }
-    socket.write(`HTTP/1.1 101 Switching Protocols\r\nupgrade: websocket\r\nconnection: Upgrade\r\nsec-websocket-accept: ${acceptKey(key)}\r\nsec-websocket-protocol: quo\r\n\r\n`);
-    const reader = new WsReader(MAX_BODY);
-    const send = (opcode, payload) => {
-        if (!socket.destroyed)
-            socket.write(frameOf(opcode, payload));
-    };
-    const close = () => {
-        send(OP.close);
-        socket.end();
-    };
-    socket.on('data', (chunk) => {
-        for (const event of reader.push(chunk)) {
-            if (event.type === 'ping')
-                send(OP.pong, event.data);
-            else if (event.type !== 'binary')
-                return close();
-            else {
-                const frame = readBody(event.data);
-                if (frame === null)
-                    return close();
-                if (frame.kind !== 'ask')
-                    continue;
-                void ground
-                    .arrive(hex(frame.pk), frame.box)
-                    .catch(() => null)
-                    .then((reply) => send(OP.binary, reply === null ? nothingBody(frame.id) : replyBody(frame.id, reply)));
-            }
-        }
-    });
-    socket.on('error', () => socket.destroy());
-};
-// A listener of the web carrier for one ground.
-export const webServe = (ground, listen) => {
-    const sockets = new Set();
-    const server = createServer((request, response) => {
-        void post(ground, listen, request, response).catch(() => {
-            if (!response.headersSent)
-                response.writeHead(400);
-            response.end();
-        });
-    });
-    server.on('connection', (socket) => {
-        sockets.add(socket);
-        socket.on('close', () => sockets.delete(socket));
-    });
-    server.on('upgrade', (request, socket) => upgrade(ground, listen, request, socket));
-    return new Promise((resolve, reject) => {
-        server.once('error', reject);
-        server.listen(listen.port, listen.host, () => {
-            const { address, port } = server.address();
-            const authority = tcpAt(address, port).slice('tcp://'.length);
-            resolve({
-                port,
-                at: [`http://${authority}${listen.path}`, `ws://${authority}${listen.path}`],
-                close: () => {
-                    for (const socket of sockets)
-                        socket.destroy();
-                    return new Promise((done) => server.close(() => done()));
-                },
-            });
-        });
-    });
-};

package/dist/core/http/websocket.d.ts

@@ -1,29 +0,0 @@
-export declare const OP: {
-    readonly continuation: 0;
-    readonly text: 1;
-    readonly binary: 2;
-    readonly close: 8;
-    readonly ping: 9;
-    readonly pong: 10;
-};
-export declare const acceptKey: (key: string) => string;
-export declare const isClientKey: (key: unknown) => key is string;
-export declare const frameOf: (opcode: number, payload?: Uint8Array) => Uint8Array;
-export type WsEvent = {
-    type: 'binary';
-    data: Uint8Array;
-} | {
-    type: 'text';
-} | {
-    type: 'ping';
-    data: Uint8Array;
-} | {
-    type: 'close';
-} | {
-    type: 'bad';
-};
-export declare class WsReader {
-    #private;
-    constructor(max: number);
-    push(chunk: Uint8Array): WsEvent[];
-}