nervur 0.20.0 → 0.20.2

package/src/pointer/world.ts

@@ -3,10 +3,9 @@
 // to harbor that stands in for the internet, and weather between them. A
 // restart drops a harbor and opens a new one on the terrain the world
 // keeps for it, so only what its memory kept comes back.
-import type { BeingClass } from '../being/index.ts';
-import { Carrier, type Clock, type Custody, type Entropy, type Memory } from '../contract/index.ts';
-import { Harbor, Terrain } from '../harbor/index.ts';
-import { CryptoEntropy, HeldCustody, SystemClock, VolatileMemory } from './bodies.ts';
+import { Carrier, type Clock, type Custody, type Entropy, type Loader, type Memory, type Module } from '../contract/index.ts';
+import { Harbor, Terrain, type GroundFaculty, type Opening } from '../harbor/index.ts';
+import { CryptoEntropy, HeldCustody, HeldLoader, SystemClock, VolatileMemory } from './bodies.ts';
 
 // A carrier that reaches no one: a harbor alone.
 export class NoCarrier extends Carrier {
@@ -27,7 +26,17 @@ export class PointerCarrier extends Carrier {
   }
 }
 
-export type PointerParts = { entropy?: Entropy; clock?: Clock; custody?: Custody; memory?: Memory; carrier?: Carrier };
+export type PointerParts = {
+  entropy?: Entropy;
+  clock?: Clock;
+  custody?: Custody;
+  memory?: Memory;
+  carrier?: Carrier;
+  loader?: Loader;
+  faculties?: readonly GroundFaculty[];
+  opens?: readonly Opening[];
+  wakes?: boolean;
+};
 
 export class PointerTerrain extends Terrain {
   readonly entropy: Entropy;
@@ -35,6 +44,10 @@ export class PointerTerrain extends Terrain {
   readonly custody: Custody;
   readonly memory: Memory;
   readonly carrier: Carrier;
+  readonly loader: Loader;
+  override readonly faculties: readonly GroundFaculty[];
+  override readonly opens: readonly Opening[];
+  override readonly wakes: boolean;
 
   constructor(parts: PointerParts = {}) {
     super();
@@ -43,23 +56,29 @@ export class PointerTerrain extends Terrain {
     this.custody = parts.custody ?? new HeldCustody(this.entropy);
     this.memory = parts.memory ?? new VolatileMemory();
     this.carrier = parts.carrier ?? new NoCarrier();
+    this.loader = parts.loader ?? new HeldLoader();
+    this.faculties = parts.faculties ?? [];
+    this.opens = parts.opens ?? [];
+    this.wakes = parts.wakes ?? true;
   }
 }
 
-type Place = { harbor: Harbor; terrain: Terrain; classes: readonly BeingClass[] };
+type Place = { harbor: Harbor; terrain: Terrain };
 
 export class World {
   readonly #places = new Map<string, Place>();
   // Harbors the world reaches no one in, nor anyone out of.
   readonly cut = new Set<string>();
 
-  // A harbor of this world. `parts` replaces the pointer bodies, a folder's
-  // memory and custody among them.
-  async harbor(name: string, classes: readonly BeingClass[], parts: Omit<PointerParts, 'carrier'> = {}): Promise<Harbor> {
+  // A harbor of this world, whose loader holds `modules` unless `parts`
+  // names a loader. `parts` replaces the pointer bodies, a folder's memory
+  // and custody among them. The harbor runs only the modules its catalogue
+  // was told to add.
+  async harbor(name: string, modules: readonly Module[] = [], parts: Omit<PointerParts, 'carrier'> = {}): Promise<Harbor> {
     if (this.#places.has(name)) throw new Error(`a harbor named ${name} stands`);
-    const terrain = new PointerTerrain({ ...parts, carrier: new PointerCarrier(this) });
-    const harbor = await Harbor.open(terrain, classes);
-    this.#places.set(name, { harbor, terrain, classes });
+    const terrain = new PointerTerrain({ loader: new HeldLoader(modules), ...parts, carrier: new PointerCarrier(this) });
+    const harbor = await Harbor.open(terrain);
+    this.#places.set(name, { harbor, terrain });
     return harbor;
   }
 
@@ -69,16 +88,16 @@ export class World {
     return place.harbor;
   }
 
-  // The harbor opened again on its own terrain, with the classes it was
-  // made with unless others are named. `parts` replaces bodies of the
-  // terrain, as a new process would build them over the same disk.
-  async restart(name: string, classes?: readonly BeingClass[], parts?: Omit<PointerParts, 'carrier'>): Promise<Harbor> {
+  // The harbor opened again on its own terrain. `parts` replaces bodies of
+  // the terrain, as a new process would build them over the same disk, or
+  // with other code.
+  async restart(name: string, parts?: Omit<PointerParts, 'carrier'>): Promise<Harbor> {
     const place = this.#places.get(name);
     if (!place) throw new Error(`no harbor named ${name}`);
     const t = place.terrain;
-    const terrain = parts ? new PointerTerrain({ entropy: t.entropy, clock: t.clock, custody: t.custody, memory: t.memory, ...parts, carrier: t.carrier }) : t;
-    const harbor = await Harbor.open(terrain, classes ?? place.classes);
-    this.#places.set(name, { ...place, harbor, terrain });
+    const terrain = parts ? new PointerTerrain({ entropy: t.entropy, clock: t.clock, custody: t.custody, memory: t.memory, loader: t.loader, ...parts, carrier: t.carrier }) : t;
+    const harbor = await Harbor.open(terrain);
+    this.#places.set(name, { harbor, terrain });
     return harbor;
   }
 

package/src/quo/address.ts

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+// Addresses, as `SPEC.md` names them in an invitation's `at`: a URI of
+// RFC 3986 whose scheme, read in any case, names a carrier.
+// `CARRIER-TCP.md` writes `tcp://host:port`, and `CARRIER-WEB.md` writes
+// `http` and `https` for the post and `ws` and `wss` for the held line.
+
+// RFC 3986 appendix B, with the characters a URI may hold checked apart.
+const SPLIT = /^(?:([^:/?#]+):)?(?:\/\/([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?$/;
+const URI_CHARS = /^(?:[A-Za-z0-9\-._~:/?#[\]@!$&'()*+,;=]|%[0-9A-Fa-f]{2})*$/;
+const SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*$/;
+const REG_NAME = /^(?:[A-Za-z0-9\-._~!$&'()*+,;=]|%[0-9A-Fa-f]{2})*$/;
+const IP_LITERAL = /^\[(?:[0-9A-Fa-f:.]+|v[0-9A-Fa-f]+\.[A-Za-z0-9\-._~!$&'()*+,;=:]+)\]$/;
+
+type Parts = { scheme: string; authority: string | null; userinfo: string | null; host: string | null; port: string | null; path: string; query: string | null; fragment: string | null };
+
+// A URI with a scheme, taken apart, or null. `host` is as written,
+// brackets included, and `port` the digits as written.
+const parse = (s: unknown): Parts | null => {
+  if (typeof s !== 'string' || !URI_CHARS.test(s)) return null;
+  const m = SPLIT.exec(s);
+  if (!m || m[1] === undefined || !SCHEME.test(m[1])) return null;
+  const out: Parts = { scheme: m[1].toLowerCase(), authority: m[2] ?? null, userinfo: null, host: null, port: null, path: m[3] ?? '', query: m[4] ?? null, fragment: m[5] ?? null };
+  if (out.authority === null) return out;
+  let rest = out.authority;
+  const at = rest.lastIndexOf('@');
+  if (at >= 0) {
+    out.userinfo = rest.slice(0, at);
+    rest = rest.slice(at + 1);
+  }
+  const hp = /^(\[[^\]]*\]|[^:[\]]*)(?::([0-9]*))?$/.exec(rest);
+  if (!hp) return null;
+  const host = hp[1]!;
+  if (host.startsWith('[') ? !IP_LITERAL.test(host) : !REG_NAME.test(host)) return null;
+  out.host = host;
+  out.port = hp[2] ?? null;
+  return out;
+};
+
+// The host as a socket takes it: an IPv6 literal without its brackets.
+const bare = (host: string): string => (host.startsWith('[') ? host.slice(1, -1) : host);
+
+// The scheme an address names, lowercase, or null for what is no URI.
+export const schemeOf = (s: unknown): string | null => parse(s)?.scheme ?? null;
+
+export type TcpAddress = { host: string; port: number };
+
+// A `tcp` address as `CARRIER-TCP.md` writes one, or null.
+export const tcpAddress = (s: unknown): TcpAddress | null => {
+  const a = parse(s);
+  if (!a || a.scheme !== 'tcp' || a.authority === null) return null;
+  if (a.userinfo !== null || a.path !== '' || a.query !== null || a.fragment !== null) return null;
+  if (!a.host || a.port === null || !/^[0-9]+$/.test(a.port)) return null;
+  const port = Number(a.port);
+  if (port < 1 || port > 65_535) return null;
+  return { host: bare(a.host), port };
+};
+
+// The `tcp` address of a host and port.
+export const tcpAt = (host: string, port: number): string => `tcp://${host.includes(':') ? `[${host}]` : host}:${port}`;
+
+export type WebAddress = { scheme: 'http' | 'https' | 'ws' | 'wss'; secure: boolean; held: boolean; host: string; port: number; path: string; href: string };
+const WEB = new Set(['http', 'https', 'ws', 'wss']);
+
+// An address of `CARRIER-WEB.md`, or null. `path` is the path and query
+// a request names, `/` when both are empty.
+export const webAddress = (s: unknown): WebAddress | null => {
+  const a = parse(s);
+  if (!a || !WEB.has(a.scheme) || a.authority === null) return null;
+  if (a.userinfo !== null || a.fragment !== null || !a.host) return null;
+  if (a.port !== null && a.port !== '' && (!/^[0-9]+$/.test(a.port) || Number(a.port) > 65_535)) return null;
+  const scheme = a.scheme as WebAddress['scheme'];
+  const secure = scheme === 'https' || scheme === 'wss';
+  const port = a.port ? Number(a.port) : secure ? 443 : 80;
+  const path = `${a.path || '/'}${a.query !== null ? `?${a.query}` : ''}`;
+  return { scheme, secure, held: scheme === 'ws' || scheme === 'wss', host: bare(a.host), port, path, href: s as string };
+};
+
+// Whether a tcp or web address names the unspecified host, where a
+// listener binds every interface and no caller can dial.
+export const unspecified = (s: unknown): boolean => {
+  const host = (tcpAddress(s) ?? webAddress(s))?.host;
+  return host === '0.0.0.0' || host === '::';
+};
+
+// An invitation's `at` as `SPEC.md` reads it: the strings that are URIs
+// with a scheme, in their order. A value that is no array is absent.
+export const readAt = (value: unknown): string[] => (Array.isArray(value) ? value.filter((s): s is string => parse(s) !== null) : []);

package/src/quo/door.ts

@@ -42,16 +42,18 @@ export class Door {
   }
 
   // A new heir, held fresh, and its invitation. The lock is drawn at the
-  // first invitation that names a heir, before the heir's secret.
-  async invite(): Promise<{ heir: string; invitation: Invitation }> {
+  // first invitation that names an heir, before the heir's secret.
+  // A new heir, and its invitation, naming in `at` the addresses given.
+  async invite(at: readonly string[] = []): Promise<{ heir: string; invitation: Invitation }> {
     let lock = this.relations.lock();
     if (!lock) this.relations.setLock((lock = drawLock(this.draw)));
     const heir = await SigningKey.draw(this.draw);
     this.relations.set(heir.id, { state: 'fresh' });
-    return { heir: heir.id, invitation: { ward: this.key.pk, heir: heir.id, secret: hex(heir.secret), lock: hex(lock.ek) } };
+    const invitation = { ward: this.key.pk, heir: heir.id, secret: hex(heir.secret), lock: hex(lock.ek), ...(at.length > 0 ? { at: [...at] } : {}) };
+    return { heir: heir.id, invitation };
   }
 
-  // The door stops holding a heir. A fresh one leaves nothing, a spent one
+  // The door stops holding an heir. A fresh one leaves nothing, a spent one
   // leaves the keys kept at removal.
   remove(heir: string): boolean {
     const record = this.relations.get(heir);

package/src/quo/index.ts

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Quo's wire: keys, the invitation, the payload, the reply, the boxes, the
 // door and the standing. It knows no being, no ward and no terrain.
+export { readAt, schemeOf, tcpAddress, tcpAt, unspecified, webAddress, type TcpAddress, type WebAddress } from './address.ts';
 export { Door, SPAN, type Behind, type Choice, type Judged } from './door.ts';
 export { readInvitation, type Invitation } from './invitation.ts';
 export { Ephemeral, SigningKey, WardKey, type Draw } from './keys.ts';

package/src/quo/invitation.ts

@@ -1,15 +1,19 @@
 // SPDX-License-Identifier: Apache-2.0
-// The invitation: `{ ward, heir, secret, lock }`, a value with no route.
+// The invitation: `{ ward, heir, secret, lock, at? }`. A door reads no
+// route from it; `at`, when present, names where the ward is reached.
 import { EK, encapsulate, isHex, unhex } from '../crypto/index.ts';
+import { readAt } from './address.ts';
 
-export type Invitation = { readonly ward: string; readonly heir: string; readonly secret: string; readonly lock: string };
+export type Invitation = { readonly ward: string; readonly heir: string; readonly secret: string; readonly lock: string; readonly at?: string[] };
 
-// An invitation, or null for any other shape. A field beside the four is
-// ignored, and the lock is held to the modulus check.
+// An invitation, or null for any other shape. A field beside the five is
+// ignored, the lock is held to the modulus check, and `at` keeps the
+// addresses it holds, an `at` with none or of another shape being absent.
 export const readInvitation = (value: unknown): Invitation | null => {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) return null;
-  const { ward, heir, secret, lock } = value as Record<string, unknown>;
+  const { ward, heir, secret, lock, at } = value as Record<string, unknown>;
   if (!isHex(ward, 64) || !isHex(heir, 32) || !isHex(secret, 32) || !isHex(lock, EK)) return null;
   if (encapsulate(unhex(lock), new Uint8Array(32)) === null) return null;
-  return { ward, heir, secret, lock };
+  const addresses = readAt(at);
+  return { ward, heir, secret, lock, ...(addresses.length > 0 ? { at: addresses } : {}) };
 };

package/src/quo/keys.ts

@@ -15,7 +15,7 @@ export const LABEL = {
   wardSeal: utf8('quo-ward-seal'),
 } as const;
 
-// An Ed25519 pair: a heir, or a standing's own key.
+// An Ed25519 pair: an heir, or a standing's own key.
 export class SigningKey {
   readonly secret: Uint8Array;
   readonly pk: Uint8Array;

package/src/stand/main.ts

@@ -17,3 +17,4 @@ for await (const line of createInterface({ input: process.stdin, crlfDelay: Infi
   );
 }
 await Promise.all(pending);
+await stand.close();

package/src/stand/stand.ts

@@ -1,9 +1,14 @@
 // SPDX-License-Identifier: Apache-2.0
-// The stand of `quo/vectors/HARNESS.md`, part one, over `quo/` alone. Part
-// two carries bytes over TCP, which is the dock's, so its three requests
-// are `bad request`.
+// The stand of `quo/vectors/HARNESS.md`, over `quo/`, `nervur/tcp` and
+// `nervur/http`: part one judged, and part two carried, its wards
+// answering on one tcp listener and one web listener, a post's and a held
+// line's, and asking through a dialer of each.
 import { hex, isHex, unhex } from '../crypto/index.ts';
-import { Door, freshStanding, MemoryRelations, readInvitation, Standing, WardKey, type Behind, type Choice, type Draw, type Invitation, type Payload, type Read, type Sent } from '../quo/index.ts';
+import { UNDIALED, type Dialed } from '../harbor/index.ts';
+import { webServe } from '../http/index.ts';
+import { WebDialer, type WebListener } from '../line/index.ts';
+import { Door, freshStanding, MemoryRelations, readInvitation, Standing, tcpAddress, WardKey, webAddress, type Behind, type Choice, type Draw, type Invitation, type Payload, type Read, type Sent } from '../quo/index.ts';
+import { TcpCarrier, TcpListener } from '../tcp/index.ts';
 
 type Answer = Record<string, unknown>;
 const ERRORS = ['bad request', 'no such op', 'no such ward', 'not reached', 'ward stood', 'name held'] as const;
@@ -51,11 +56,43 @@ const OPS = new Set(['ward', 'invite', 'release', 'arrive', 'ask', 'read', 'list
 export class Stand {
   readonly #wards = new Map<string, StandWard>();
   readonly #draw: Draw;
+  readonly #tcp = new TcpCarrier();
+  readonly #web = new WebDialer();
+  readonly #routes = new Map<string, string>();
+  #tcpListener: Promise<TcpListener> | undefined;
+  #webListener: Promise<WebListener> | undefined;
 
   constructor(draw: Draw) {
     this.#draw = draw;
   }
 
+  async close(): Promise<void> {
+    await this.#tcp.close();
+    await this.#web.close();
+    await (await this.#tcpListener)?.close();
+    await (await this.#webListener)?.close();
+  }
+
+  // Every ward this program stands, as a listener reaches them.
+  readonly #doors = {
+    arrive: async (pk: string, bytes: Uint8Array): Promise<Uint8Array | null> => {
+      const ward = this.#wards.get(pk);
+      return ward ? (await ward.door.arrive(bytes)).bytes : null;
+    },
+  };
+
+  // Bytes to a ward at one address, over the carrier its scheme names.
+  #dial(at: string, pk: string, bytes: Uint8Array): Promise<Dialed> {
+    return tcpAddress(at) ? this.#tcp.dial(at, pk, bytes) : this.#web.dial(at, pk, bytes);
+  }
+
+  // The addresses this program listens at, for an invitation's `at`.
+  async #listening(): Promise<string[]> {
+    const tcp = await this.#tcpListener;
+    const web = await this.#webListener;
+    return [...(tcp ? [tcp.at] : []), ...(web ? web.at : [])];
+  }
+
   async handle(line: string): Promise<Answer> {
     let request: unknown;
     try {
@@ -90,9 +127,53 @@ export class Stand {
         return this.#ask(r);
       case 'read':
         return this.#read(r);
+      case 'listen':
+        return this.#listen(r.scheme);
+      case 'route':
+        return this.#route(r);
       default:
-        return refuse('bad request');
+        return this.#send(r);
+    }
+  }
+
+  // One listener of a scheme this program stands, answering for every ward
+  // it stands.
+  async #listen(scheme: unknown): Promise<Answer> {
+    if (scheme === undefined || scheme === 'tcp') {
+      this.#tcpListener ??= TcpListener.listen(this.#doors);
+      return { at: (await this.#tcpListener).at };
+    }
+    if (scheme !== 'http' && scheme !== 'ws') return refuse('bad request');
+    this.#webListener ??= webServe(this.#doors, { host: '127.0.0.1', port: 0, path: '/quo', origins: ['*'] });
+    return { at: (await this.#webListener).at.find((at) => at.startsWith(`${scheme}:`))! };
+  }
+
+  #route(r: Record<string, unknown>): Answer {
+    const far = r.far;
+    if (!isHex(far, 64) || (tcpAddress(r.at) === null && webAddress(r.at) === null)) return refuse('bad request');
+    this.#routes.set(far, r.at as string);
+    return { routed: far };
+  }
+
+  async #send(r: Record<string, unknown>): Promise<Answer> {
+    const invitation = inviteOf(r.invitation);
+    const method = r.method === undefined ? undefined : text(r.method);
+    const args = r.args === undefined ? undefined : objectText(r.args);
+    const ward = this.#ward_(r.ward);
+    const held = this.#standing(ward, invitation);
+    const sent = await held.standing.ask(method, args);
+    if (sent === null) return refuse('bad request');
+    held.last = sent;
+    const far = invitation.ward;
+    const route = this.#routes.get(far);
+    let reply: Uint8Array | null = null;
+    for (const at of route === undefined ? (invitation.at ?? []) : [route]) {
+      const out = await this.#dial(at, far, sent.bytes);
+      if (out === UNDIALED) continue;
+      reply = out;
+      break;
     }
+    return { read: readOf(await held.standing.read(sent, reply)) };
   }
 
   async #ward(seed: string, reach: string | undefined): Promise<Answer> {
@@ -109,7 +190,7 @@ export class Stand {
     const ward = this.#ward_(r.ward);
     reached(reach);
     if (ward.names.has(name)) refuse('name held');
-    const { heir, invitation } = await ward.door.invite();
+    const { heir, invitation } = await ward.door.invite(await this.#listening());
     ward.names.set(name, heir);
     ward.reaches.set(heir, reach);
     return { invitation };