nervur 0.20.0 → 0.20.2

package/dist/harbor/index.js

@@ -1,6 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
-// The onion: a terrain, a registry, the dock, and the harbor.
+// The onion: a terrain, the package, the dock, the catalogue and its
+// registry, and the harbor.
+export { Catalogue, CATALOGUE } from './catalogue.js';
 export { BOX, Dock } from './dock.js';
+export { CarrierFaculty, UNDIALED } from './carrying.js';
 export { Harbor } from './harbor.js';
+export { copyPackage, Package } from './package.js';
+export { readRootRequest, rootLine } from './root-line.js';
+export { addGround, grounds, probeGround } from './probe.js';
 export { Registry } from './registry.js';
+export { Push, PUSH, RELAY, RELAY_CLIENT, RELAY_HOLD, RELAY_REST, RELAY_WAIT, RELAYED } from './relay.js';
 export { Terrain } from './terrain.js';

package/dist/harbor/package.d.ts

@@ -0,0 +1,12 @@
+import type { Entropy, Memory, Rows } from '../contract/index.ts';
+export declare const copyPackage: (from: Memory, to: Memory) => Promise<string[]>;
+export declare class Package {
+    #private;
+    readonly memory: Memory;
+    readonly entropy: Entropy;
+    private constructor();
+    static open(memory: Memory, entropy: Entropy, seed: Uint8Array): Promise<Package>;
+    derive(info: string[], length: number): Promise<Uint8Array>;
+    place(name: string): Promise<string>;
+    rows(name: string): Promise<Rows>;
+}

package/dist/harbor/package.js

@@ -0,0 +1,130 @@
+// 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, 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;
+};
+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.
+    kept() {
+        const rows = [...this.#told];
+        this.#told.clear();
+        this.#line = this.#line.then(() => this.#write(rows)).catch(() => false);
+        return this.#line;
+    }
+    async #write(told) {
+        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 Ward {
+    #pack;
+    #name;
+    #seal;
+    place;
+    constructor(pack, name, seal, place) {
+        this.#pack = pack;
+        this.#name = name;
+        this.#seal = seal;
+        this.place = 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.#pack.memory.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 the package kept them.
+    async rows(name) {
+        const ward = new Ward(this, name, await this.derive(['seal', name], 32), hex(await this.derive(['place', name], 16)));
+        const rows = {};
+        const beings = {};
+        let any = false;
+        for (const [entry, bytes] of await this.memory.read(ward.place)) {
+            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/harbor/probe.d.ts

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

package/dist/harbor/probe.js

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

package/dist/harbor/registry.d.ts

@@ -1,7 +1,10 @@
-import type { BeingClass } from '../being/index.ts';
+import { type BeingClass } from '../being/index.ts';
+import type { Module } from '../contract/index.ts';
 import type { Catalogue } from '../ward/index.ts';
 export declare class Registry implements Catalogue {
     #private;
-    constructor(classes: readonly BeingClass[]);
-    classOf(name: string): BeingClass | undefined;
+    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/harbor/registry.js

@@ -1,13 +1,89 @@
+// 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 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. Two harbors hold
+// two registries, and nothing between them names a class.
+import { Faculty, isKind, KIT, kindOf } from '../being/index.js';
+const domainOf = (name) => `${name.split('.').slice(0, 2).join('.')}.`;
 export class Registry {
     #classes = new Map();
-    constructor(classes) {
-        for (const C of classes) {
-            if (this.#classes.has(C.name) && this.#classes.get(C.name) !== C)
-                throw new Error(`two classes are named ${C.name}`);
-            this.#classes.set(C.name, C);
+    #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);
+                if (!Faculty.fulfils(C))
+                    continue;
+                for (let c = Object.getPrototypeOf(C); c !== Faculty; c = Object.getPrototypeOf(c)) {
+                    const contract = kindOf(c);
+                    if (contract.startsWith(KIT))
+                        throw new Error(`kind ${contract} is the kit's`);
+                    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);
     }
-    classOf(name) {
-        return this.#classes.get(name);
+    // The kinds a module stands, or none.
+    kindsOf(module) {
+        return [...(this.#modules.get(module) ?? [])];
     }
 }

package/dist/harbor/relay.d.ts

@@ -0,0 +1,15 @@
+import { Faculty, type BeingClass } from '../being/index.ts';
+import type { Clock } from '../contract/index.ts';
+import { type Ground } from './carrying.ts';
+export declare const RELAY = "org.nervur.relay";
+export declare const RELAY_CLIENT = "org.nervur.relay-client";
+export declare const PUSH = "org.nervur.push";
+export declare const RELAY_WAIT = 30000;
+export declare const RELAY_HOLD = 20000;
+export declare const RELAY_REST = 1000;
+export declare const RELAYED = 262144;
+export declare abstract class Push extends Faculty {
+    static readonly kind: string;
+}
+export declare const relayFaculty: (clock: Clock) => BeingClass;
+export declare const relayClient: (ground: Ground, clock: Clock) => BeingClass;