nervur 0.20.0 → 0.20.2

package/src/browser/worker.ts

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+// The browser harbor in a worker, one for every tab. A shared, dedicated
+// or service worker calls `serveWorker` as its script starts, with the
+// harbor it opens; every tab reaches that harbor's root line with
+// `rootOf`, one request on a channel of its own. A service worker that
+// hears a push asks every relay client of its harbor to `ring`, since a
+// push carries nothing but the news that something waits.
+import type { JsonObject } from '../being/index.ts';
+import { RELAY_CLIENT, rootLine, type Harbor } from '../harbor/index.ts';
+
+type Asked = { request?: unknown };
+type Answering = { postMessage(message: unknown): void };
+type Scope = {
+  addEventListener(type: string, listener: (event: never) => void): void;
+};
+type Connecting = { ports: readonly MessagePort[] };
+type Messaging = { data: unknown; ports: readonly MessagePort[] };
+type Pushing = { waitUntil(work: Promise<unknown>): void };
+
+const answer = async (harbor: Promise<Harbor>, data: unknown, reply: Answering | undefined): Promise<void> => {
+  if (!reply) return;
+  let out: JsonObject;
+  try {
+    out = await rootLine(await harbor, (data as Asked | null)?.request);
+  } catch {
+    out = { error: 'the harbor threw' };
+  }
+  reply.postMessage(out);
+};
+
+// Every relay client of the harbor asked to collect what waits.
+export const ringAll = async (harbor: Harbor): Promise<JsonObject[]> => {
+  const keys = Object.entries(harbor.box.partition.beings)
+    .filter(([, row]) => row.class === RELAY_CLIENT)
+    .map(([key]) => key);
+  return Promise.all(keys.map(async (being) => (await harbor.root('ask', { being, method: 'ring' })) as JsonObject));
+};
+
+// Called as the worker's script starts, so no tab's first message is
+// lost while the harbor opens.
+export const serveWorker = (harbor: Promise<Harbor>, scope: Scope = globalThis as unknown as Scope): void => {
+  scope.addEventListener('connect', (event: Connecting) => {
+    const port = event.ports[0]!;
+    port.onmessage = (message) => void answer(harbor, message.data, message.ports[0]);
+    port.start();
+  });
+  scope.addEventListener('message', (event: Messaging) => void answer(harbor, event.data, event.ports[0]));
+  scope.addEventListener('push', (event: Pushing) => event.waitUntil(harbor.then(ringAll)));
+};
+
+// Where a tab sends root requests: a shared worker's port, a dedicated
+// worker, or a service worker.
+export type Reaching = { postMessage(message: unknown, transfer: Transferable[]): void };
+
+// A tab's root line to the worker's harbor.
+export const rootOf =
+  (worker: Reaching) =>
+  (request: JsonObject): Promise<JsonObject> =>
+    new Promise((resolve) => {
+      const channel = new MessageChannel();
+      channel.port1.onmessage = (message) => {
+        channel.port1.close();
+        resolve(message.data as JsonObject);
+      };
+      worker.postMessage({ request }, [channel.port2]);
+    });

package/src/browser.ts

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur` as a browser bundle reads it: the main entry, with the browser
+// ground added, so `Harbor.open()` keeps a harbor in IndexedDB.
+import { browserGround } from './browser/index.ts';
+import { addGround } from './harbor/index.ts';
+
+export * from './index.ts';
+
+addGround(browserGround);

package/src/cli/command.ts

@@ -0,0 +1,224 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur`: a harbor on this machine. Each command is one root request, the
+// same the root line carries from any front, printed as one JSON line.
+//
+//   nervur init   [--dir D]                         the harbor made: its seed drawn,
+//                                                   its catalogue stood, and an owner
+//                                                   invitation for whoever made it
+//   nervur serve  [--dir D] [--host H] [--port P]   the harbor served: Quo over TCP,
+//                                                   and the root line on its socket
+//   nervur module add <file>                        a module the catalogue runs
+//   nervur module remove <module>                   a module it runs no more
+//   nervur modules                                  what the catalogue runs
+//   nervur census [--ward W]                        the empty ask
+//   nervur sweep                                    every place of the folder this
+//                                                   harbor does not name, gone
+//   nervur export [--with-seed]                     the harbor as one JSON line, to
+//                                                   carry it to another ground; with
+//                                                   --with-seed the seed goes too
+//   nervur import <file>                            a carried harbor into an empty
+//                                                   folder, `-` being this input
+//   nervur open   <key> <kind>                      a faculty stands in the box ward
+//   nervur host   <ward> [--seed S]                 a hosted ward stands
+//   nervur route  <ward pk> <address... | none>     where a ward is reached, in order
+//   nervur reach  <address...>                      where this harbor is reached, as
+//                                                   every invitation it gives says
+//   nervur boot   [--ward W] <key> <kind>           a being stands
+//   nervur unboot [--ward W] <being>                a being goes
+//   nervur public [--ward W] <key | none>           the being a stranger reaches
+//   nervur invite [--ward W] <being> <id>           an invitation on a being
+//   nervur ask    [--ward W] [being] [method] [args] a being, asked as the owner
+//   nervur own    [--ward W] <id>                   an invitation for an owner
+//   nervur disown [--ward W] <id>                   an owner no more
+//   nervur pilot  <name> <invitation> [address]     a far ward held as its owner, by a
+//                                                   pilot being of the box ward, at
+//                                                   the address or the invitation's at
+//   nervur <command> --via <name> ...               the command asked of the far ward
+//                                                   that pilot holds, as its owner
+//
+// D is --dir, then $NERVUR_DIR, then ~/.nervur. A module file is named from
+// where the command runs and kept by its absolute path. No --ward is the box
+// ward, and a pilot holds one ward, so --via takes no --ward. The exit is 1
+// when the answer is an error.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import type { JsonObject } from '../being/index.ts';
+import type { RootRequest } from '../harbor/index.ts';
+import { harborDir } from '../node/index.ts';
+import { carry, isServed, land, open, request, serve } from './harbor.ts';
+
+const USAGE = 'usage: nervur <init|serve|module|modules|census|sweep|open|host|route|reach|boot|unboot|public|invite|ask|own|disown|pilot|export|import> [args] [--dir D] [--ward W] [--via V] [--seed S] [--with-seed] [--host H] [--port P]';
+const FLAGS = new Set(['dir', 'ward', 'via', 'seed', 'host', 'port']);
+// The one flag that stands alone, since what it names is a yes.
+const ALONE = 'with-seed';
+
+export const parse = (argv: string[]): { command?: string; words: string[]; flags: Record<string, string> } => {
+  const flags: Record<string, string> = {};
+  const words: string[] = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]!;
+    const name = arg.startsWith('--') ? arg.slice(2) : undefined;
+    if (name === undefined) words.push(arg);
+    else if (name === ALONE) flags[name] = 'yes';
+    else if (!FLAGS.has(name) || argv[i + 1] === undefined) throw new Error(`--${name} is no flag with a value`);
+    else flags[name] = argv[(i += 1)]!;
+  }
+  const [command, ...rest] = words;
+  return { ...(command === undefined ? {} : { command }), words: rest, flags };
+};
+
+// What this command was handed on its input, for `import -`.
+const standingIn = async (): Promise<string> => {
+  let text = '';
+  for await (const chunk of process.stdin) text += (chunk as Buffer).toString('utf8');
+  return text;
+};
+
+const none = (word: string): string | null => (word === 'none' ? null : word);
+const json = (word: string | undefined): JsonObject | undefined => (word === undefined ? undefined : (JSON.parse(word) as JsonObject));
+const catalogue = (method: string, args: JsonObject = {}): RootRequest => ({ method: 'ask', args: { being: 'catalogue', method, args } });
+
+// The root request a command names, or a throw saying what it lacks.
+export const requestOf = (command: string, words: string[], flags: Record<string, string>): RootRequest => {
+  const need = (n: number): string[] => {
+    if (words.length !== n) throw new Error(`${command} takes ${n} argument${n === 1 ? '' : 's'}`);
+    return words;
+  };
+  const at = flags.ward === undefined ? {} : { ward: flags.ward };
+  switch (command) {
+    case 'module': {
+      const [verb, what] = need(2);
+      if (verb === 'add') return catalogue('add', { from: resolve(what!) });
+      if (verb === 'remove') return catalogue('remove', { module: what! });
+      throw new Error('module is add or remove');
+    }
+    case 'modules':
+      return (need(0), catalogue('modules'));
+    case 'sweep':
+      return (need(0), { method: 'sweep', args: {} });
+    case 'census':
+      return (need(0), at);
+    case 'open': {
+      const [key, kind] = need(2);
+      return { method: 'open', args: { key: key!, class: kind! } };
+    }
+    case 'host': {
+      const [ward] = need(1);
+      return { method: 'host', args: { ward: ward!, ...(flags.seed === undefined ? {} : { seed: flags.seed }) } };
+    }
+    case 'route': {
+      const [ward, ...where] = words;
+      if (ward === undefined || where.length === 0) throw new Error('route takes a ward pk and its addresses, or none');
+      return { method: 'route', args: { ward, at: where.length === 1 && where[0] === 'none' ? null : where } };
+    }
+    case 'reach':
+      if (words.length === 0) throw new Error('reach takes the addresses this harbor is reached at');
+      return { method: 'reach', args: { at: words } };
+    case 'boot': {
+      const [key, kind] = need(2);
+      return { ...at, method: 'boot', args: { key: key!, class: kind! } };
+    }
+    case 'unboot':
+      return { ...at, method: 'unboot', args: { being: need(1)[0]! } };
+    case 'public':
+      return { ...at, method: 'public', args: { key: none(need(1)[0]!) } };
+    case 'invite': {
+      const [being, id] = need(2);
+      return { ...at, method: 'invite', args: { being: being!, id: id! } };
+    }
+    case 'ask': {
+      if (words.length > 3) throw new Error('ask takes at most a being, a method and its args');
+      const [being, method, args] = words;
+      return { ...at, method: 'ask', args: { ...(being === undefined ? {} : { being }), ...(method === undefined ? {} : { method }), ...(args === undefined ? {} : { args: json(args)! }) } };
+    }
+    case 'own':
+    case 'disown':
+      return { ...at, method: command, args: { id: need(1)[0]! } };
+    default:
+      throw new Error(USAGE);
+  }
+};
+
+// An error answer at any depth the root line or an ask carries it.
+const failed = (answer: unknown): boolean => {
+  if (typeof answer !== 'object' || answer === null) return false;
+  const a = answer as JsonObject;
+  return 'error' in a || failed(a.answer);
+};
+
+export const main = async (argv: string[], env: Record<string, string | undefined>, print: (line: string) => void): Promise<number> => {
+  const { command, words, flags } = parse(argv);
+  if (command === undefined) throw new Error(USAGE);
+  const dir = flags.dir ?? harborDir(env);
+  const out = (answer: JsonObject): number => {
+    print(JSON.stringify(answer));
+    return failed(answer) ? 1 : 0;
+  };
+  if (command === 'init') {
+    if (words.length > 0) throw new Error('init takes no argument');
+    if (existsSync(join(dir, 'seed'))) return out({ error: `a harbor stands at ${dir}` });
+    const harbor = await open(dir);
+    try {
+      const owner = await harbor.root('own', { id: 'owner' });
+      return out({ pk: harbor.box.pk, owner: owner as JsonObject });
+    } finally {
+      await harbor.close();
+    }
+  }
+  if (command === 'export' || command === 'import') {
+    if (words.length !== (command === 'import' ? 1 : 0)) throw new Error(`${command} takes ${command === 'import' ? 'one file' : 'no argument'}`);
+    if (flags.via !== undefined) throw new Error(`${command} reads this folder, so it takes no --via`);
+    if (await isServed(dir)) throw new Error(`a harbor is served from ${dir}: stop it first`);
+    if (command === 'export') return out((await carry(dir, flags[ALONE] !== undefined)) as unknown as JsonObject);
+    const text = words[0] === '-' ? await standingIn() : await readFile(words[0]!, 'utf8');
+    return out({ landed: await land(dir, JSON.parse(text)) });
+  }
+  if (command === 'serve') {
+    if (words.length > 0) throw new Error('serve takes no argument');
+    const served = await serve(dir, flags.host, flags.port === undefined ? undefined : Number(flags.port));
+    const stop = (): void => void served.close().then(() => process.exit(0));
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    print(JSON.stringify({ pk: served.pk, at: served.at, listening: served.listening, root: served.root }));
+    return SERVING;
+  }
+  if (command === 'pilot') {
+    if (words.length !== 2 && words.length !== 3) throw new Error('pilot takes a name, an invitation, and an address where the invitation carries none');
+    const [name, invitation, at] = words as [string, string, string | undefined];
+    const held = JSON.parse(invitation) as JsonObject;
+    for (const req of pilotRequests(name, held, at)) {
+      const answer = await request(dir, req);
+      if (!failed(answer)) continue;
+      if (req.method === 'ask') await request(dir, { method: 'unboot', args: { being: name } });
+      return out(answer);
+    }
+    return out({ piloting: name, ward: held.ward! });
+  }
+  if (flags.via === undefined) return out(await request(dir, requestOf(command, words, flags)));
+  if (flags.ward !== undefined) throw new Error('--via takes no --ward');
+  return out(farAnswer(await request(dir, via(flags.via, requestOf(command, words, flags)))));
+};
+
+// The root requests that hold a far ward: its route where one is named,
+// else the take learns it from the invitation's `at`; the pilot; the take.
+export const pilotRequests = (name: string, invitation: JsonObject, at?: string): RootRequest[] => [
+  ...(at === undefined ? [] : [{ method: 'route', args: { ward: invitation.ward ?? null, at: [at] } }]),
+  { method: 'boot', args: { key: name, class: 'org.nervur.pilot' } },
+  { method: 'ask', args: { being: name, method: 'hold', args: { invitation } } },
+];
+
+// A root request, asked of the far ward a pilot holds.
+export const via = (pilot: string, far: RootRequest): RootRequest => ({
+  method: 'ask',
+  args: { being: pilot, method: 'pilot', args: { ...(far.method === undefined ? {} : { method: far.method }), ...(far.args === undefined ? {} : { args: far.args }) } },
+});
+
+// The far ward-being's answer out of the pilot's, or the local error.
+export const farAnswer = (local: JsonObject): JsonObject => {
+  const inner = (local.answer as JsonObject | undefined)?.answer;
+  return typeof inner === 'object' && inner !== null && !Array.isArray(inner) ? inner : local;
+};
+
+// What `main` answers for a harbor it keeps serving: no exit yet.
+export const SERVING = -1;

package/src/cli/harbor.ts

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+// A harbor on this machine, as the `nervur` command stands it: a harbor of
+// the Node ground in a folder, served while `serve` runs, and asked over
+// its root line's socket.
+//
+// A root request goes to a served harbor over its socket. With none served,
+// the command unpacks the harbor from its folder, asks, and closes it, so
+// one process at a time writes the folder.
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { JsonObject } from '../being/index.ts';
+import { hex, isHex, unhex } from '../crypto/index.ts';
+import { FolderCustody, FolderMemory } from '../folder/index.ts';
+import { Harbor, rootLine, type CarrierFaculty, type RootRequest } from '../harbor/index.ts';
+import { askServed, NodeTerrain, socketOf } from '../node/index.ts';
+import { CryptoEntropy } from '../pointer/index.ts';
+import { TCP_OPENING } from '../tcp/index.ts';
+
+// A harbor of a folder, opened for one ask: it listens nowhere and serves
+// nothing.
+export const open = (dir: string): Promise<Harbor> => Harbor.open(new NodeTerrain({ dir, wakes: false, serves: false }));
+
+// Whether a harbor of this folder is served now.
+export const isServed = async (dir: string): Promise<boolean> => (await askServed(dir, {})) !== undefined;
+
+export const request = async (dir: string, req: RootRequest): Promise<JsonObject> => {
+  const served = await askServed(dir, req);
+  if (served !== undefined) return served;
+  const harbor = await open(dir);
+  try {
+    return await rootLine(harbor, req);
+  } finally {
+    await harbor.close();
+  }
+};
+
+// A harbor as one JSON value, for carrying it to another ground: every
+// place of its memory with its sealed entries as hex, and its seed only
+// where the one who asks says so, since custody holds it and a package
+// without it opens nowhere.
+export type Carried = { seed?: string; places: Record<string, Record<string, string>> };
+
+const carried = (value: unknown): Carried | null => {
+  if (typeof value !== 'object' || value === null) return null;
+  const { seed, places } = value as { seed?: unknown; places?: unknown };
+  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 as Carried['places'] };
+};
+
+// The harbor of a folder, read as bytes alone. No harbor opens, so
+// nothing is asked and nothing is written.
+export const carry = async (dir: string, seed: boolean): Promise<Carried> => {
+  const memory = new FolderMemory(dir);
+  const places: Carried['places'] = {};
+  for (const place of await memory.places()) {
+    places[place] = Object.fromEntries([...(await memory.read(place))].map(([name, bytes]) => [name, hex(bytes)]));
+  }
+  if (!seed) return { places };
+  return { seed: hex(await new FolderCustody(dir, new CryptoEntropy()).seed()), places };
+};
+
+// A carried harbor into an empty folder. A folder holding a seed or a
+// place is left as it stands, and a package with no seed needs one there
+// already, which a terrain that seals its custody writes its own way.
+export const land = async (dir: string, value: unknown): Promise<string[]> => {
+  const held = carried(value);
+  if (held === null) throw new Error('that is no carried harbor');
+  const memory = new FolderMemory(dir);
+  if ((await memory.places()).length > 0 || (held.seed !== undefined && existsSync(join(dir, 'seed')))) throw new Error(`a harbor stands at ${dir}`);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  if (held.seed !== undefined) await writeFile(join(dir, 'seed'), `${held.seed}\n`, { mode: 0o600, flag: 'wx' });
+  else if (!existsSync(join(dir, 'seed'))) throw new Error('the package carries no seed, and none is held here');
+  for (const [place, entries] of Object.entries(held.places)) {
+    await memory.write(place, new Map(Object.entries(entries).map(([name, bytes]) => [name, unhex(bytes)])));
+  }
+  return Object.keys(held.places);
+};
+
+// A served harbor: its pk, its tcp address, every address its carriers
+// listen at, and its root line's socket.
+export type Served = { pk: string; at: string; listening: string[]; root: string; close(): Promise<void> };
+
+// The harbor served: a harbor of the Node ground, with Quo over TCP on
+// host and port.
+export const serve = async (dir: string, host?: string, port?: number): Promise<Served> => {
+  const harbor = await Harbor.open(new NodeTerrain({ dir }));
+  if (!harbor.box.being(TCP_OPENING.key)) await harbor.root('open', { key: TCP_OPENING.key, class: TCP_OPENING.kind });
+  const tcp = harbor.box.being(TCP_OPENING.key) as CarrierFaculty;
+  if (host !== undefined || port !== undefined || tcp.listening().length === 0) {
+    const heard = (await harbor.root('ask', { being: TCP_OPENING.key, method: 'listen', args: { ...(host === undefined ? {} : { host }), ...(port === undefined ? {} : { port }) } })) as JsonObject;
+    if (typeof (heard.answer as JsonObject | undefined)?.at !== 'string') {
+      await harbor.close();
+      throw new Error(`the harbor does not listen: ${JSON.stringify(heard)}`);
+    }
+  }
+  return { pk: harbor.box.pk, at: tcp.listening()[0]!, listening: harbor.carriers.flatMap((c) => c.listening()), root: socketOf(dir), close: () => harbor.close() };
+};

package/src/cli/main.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// The `nervur` program: `command.ts` over this process's arguments. A
+// command that cannot run exits 2 and says why on stderr.
+import { main, SERVING } from './command.ts';
+
+try {
+  const code = await main(process.argv.slice(2), process.env, (line) => process.stdout.write(`${line}\n`));
+  if (code !== SERVING) process.exitCode = code;
+} catch (e) {
+  process.stderr.write(`nervur: ${(e as Error).message}\n`);
+  process.exitCode = 2;
+}

package/src/contract/index.ts

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
-// The contracts: what the onion cannot unpack from cells, each an abstract
-// class, so a registry can tell at run time which class fulfils which. The
-// class differs by terrain, and the contract does not.
+// The contracts: what the onion cannot unpack from cells, a module's code
+// among them, each an abstract class, so a registry can tell at run time
+// which class fulfils which. The class differs by terrain, and the
+// contract does not.
 import type { Draw } from '../quo/index.ts';
 
 // Drawn bytes.
@@ -20,25 +21,56 @@ export abstract class Clock {
   abstract wait(ms: number): { done: Promise<void>; cancel(): void };
 }
 
-// One ward's partition, opened by name: the rows the ward writes into
-// directly, told after every write, and kept once at the end of an arrival.
+// One ward's partition, as the harbor's package opens it: the rows the
+// ward writes into directly, told after every write, and kept once at the
+// end of an arrival.
 export interface Rows {
   readonly rows: Record<string, unknown>;
   told(row: string): void;
   kept(): Promise<boolean>;
 }
 
+// A harbor's memory as a terrain keeps it: sealed entries it cannot read,
+// in places, each entry by name. Every name is lowercase hex the kit
+// chose, so a body may use it as a file name as it stands.
 export abstract class Memory {
-  abstract open(name: string): Promise<Rows>;
+  // Every entry kept in a place; a place nothing was kept in is empty.
+  abstract read(place: string): Promise<Map<string, Uint8Array>>;
+  // One keep, whole: every entry written and every null removed together,
+  // or none of them. A read after a keep that did not finish, in this run
+  // or in the run before it, holds the place as it was or as the keep
+  // leaves it, and never half of each.
+  abstract write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void>;
+  // Every place this memory holds something in, in any order.
+  abstract places(): Promise<string[]>;
+  // A place and everything in it, gone.
+  abstract forget(place: string): Promise<void>;
 }
 
-// A ward's seed by the harbor's name for it: thirty-two bytes, the same
-// every time that name is asked.
+// The harbor's seed: thirty-two bytes, the same every time. It is the one
+// secret a terrain holds.
 export abstract class Custody {
-  abstract seed(name: string): Promise<Uint8Array>;
+  abstract seed(): Promise<Uint8Array>;
 }
 
-// Bytes to a ward pk in; bytes, or null for nothing, out.
+// A module: the code a harbor's classes come from. It declares its own
+// name, a reversed domain as a kind is, and its version.
+export type Module = { readonly module: string; readonly version: string; readonly classes: readonly unknown[] };
+
+// A module as a loader found it, with `from`, the name this loader finds
+// it by again.
+export type Loaded = Module & { readonly from: string };
+
+// Code, by the name a harbor keeps for it, or null where this loader has
+// none. Code never crosses a door and never lives in a cell, so it is the
+// one thing beside the seed a terrain hands in: a map, an import, a bundle.
+export abstract class Loader {
+  abstract load(from: string): Promise<Loaded | null>;
+}
+
+// Bytes to a ward pk in; bytes, or null for nothing, out. A harbor hands a
+// terrain's carrier what it holds no route for; what it routes goes to its
+// carrier faculties.
 export abstract class Carrier {
   abstract carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
 }