@volter/twin-world 0.1.0 → 0.1.2

package/src/schema.ts

@@ -4,6 +4,7 @@ export type WorldMode = 'local' | 'share' | 'sealed';
 /**
  * Process model for the world's twins — a DIAL, not a binary (see src/host.ts):
  *  - 'process'   (default): one OS process per service — the existing spawn path. Strongest
+ *                 service-to-service process separation (not a network or Machine boundary),
  *                 isolation; the oracle, and the only choice for share/sealed/hosted worlds
  *                 (enforced by `upWorld` — see runtime.ts, not just documented here; TWIN-67).
  *  - 'colocated': every service declaring `colocate` runs in ONE `volter-world-host` child
@@ -94,10 +95,28 @@ export type WorldShareConfig = {
    *  service's local URL. When set, provider defaults to 'command'. */
   command?: string;
   args?: string[];
+  /** Lifecycle, independent of provider type. Cloudflare Quick Tunnels are always ephemeral;
+   * custom providers state the same fact explicitly when teardown retires the URL. */
+  ephemeral?: boolean;
   services: WorldShareServiceConfig[];
 };
 
+/** Peak capacity reserved for the complete World, including a foreground command run through it.
+ * Values are deliberately ordinary config data, not a resource-control DSL. */
+export type WorldResourceRequirements = {
+  memoryMiB: number;
+  writableStorageMiB: number;
+};
+
 export type WorldServiceConfig = {
+  /**
+   * A free-text NOTE about this service, ignored by the runtime — JSON has no comments, and a
+   * generated config needs somewhere to say WHY it is shaped the way it is. `volter-world init`
+   * writes the wiring rationale here (which `*_TWIN_URL` the injector actually reads, or why a
+   * vendor has no endpoint env at all), so an operator reading the emitted file is not left to
+   * reverse-engineer the decision. Hand-written configs may use it freely.
+   */
+  '//'?: string;
   id: string;
   type?: WorldServiceType;
   /** Required for 'twin'/'process' services. Omitted for 'external' (the tool's `up`/`down` hold the commands). */
@@ -181,6 +200,9 @@ export type WorldServiceConfig = {
 export type WorldConfig = {
   id: string;
   description?: string;
+  /** Peak capacity for this World. Conservative defaults are used when omitted for compatibility;
+   * resource-intensive Worlds should always declare both values explicitly. */
+  resources?: WorldResourceRequirements;
   /** Default process model for this world's twins ('process' when omitted). `upWorld`'s
    * `isolation` option overrides it per boot. */
   isolation?: WorldIsolation;
@@ -250,6 +272,35 @@ export type WorldServiceInstance = {
   };
 };
 
+/** Durable outcome of the most recent foreground consumer launched by `volter-world run`.
+ * Deliberately excludes argv and environment values: both can contain credentials. */
+export type WorldRunOutcome = {
+  state: 'completed';
+  runnerPid: number;
+  startedAt: string;
+  finishedAt: string;
+  exitCode: number;
+  log: string;
+  signal?: NodeJS.Signals;
+  error?: string;
+};
+
+export type WorldRunRecord = WorldRunOutcome | {
+  state: 'running';
+  runnerPid: number;
+  consumerPid?: number;
+  startedAt: string;
+  log: string;
+} | {
+  state: 'abrupt';
+  runnerPid: number;
+  consumerPid?: number;
+  startedAt: string;
+  observedAt: string;
+  log: string;
+  error: string;
+};
+
 export type WorldInstance = {
   name: string;
   config: string;
@@ -268,6 +319,8 @@ export type WorldInstance = {
   pidsFile: string;
   actors?: Record<string, unknown>;
   fixtures?: Record<string, unknown>;
+  resources?: WorldResourceRequirements & { log: string; holderPid: number };
+  lastRun?: WorldRunRecord;
 };
 
 function assertStringArray(value: unknown, what: string, path: string): asserts value is string[] {
@@ -367,6 +420,17 @@ export function assertWorldConfig(value: unknown, path: string): WorldConfig {
   if (config.isolation !== undefined && config.isolation !== 'process' && config.isolation !== 'colocated' && config.isolation !== 'worker') {
     throw new Error(`World config isolation must be "process", "colocated", or "worker" in ${path}`);
   }
+  if (config.resources !== undefined) {
+    if (!config.resources || typeof config.resources !== 'object' || Array.isArray(config.resources)) {
+      throw new Error(`World config resources must be an object in ${path}`);
+    }
+    for (const key of ['memoryMiB', 'writableStorageMiB'] as const) {
+      const amount = config.resources[key];
+      if (!Number.isInteger(amount) || amount <= 0) {
+        throw new Error(`World config resources.${key} must be a positive integer in ${path}`);
+      }
+    }
+  }
   const ids = new Set<string>();
   for (const service of config.services as Partial<WorldServiceConfig>[]) {
     if (!service || typeof service !== 'object') throw new Error(`Invalid service in ${path}`);
@@ -457,6 +521,9 @@ export function assertWorldConfig(value: unknown, path: string): WorldConfig {
         throw new Error(`World config share.args must be a string array in ${path}`);
       }
     }
+    if (share.ephemeral !== undefined && typeof share.ephemeral !== 'boolean') {
+      throw new Error(`World config share.ephemeral must be a boolean in ${path}`);
+    }
     if (!Array.isArray(share.services)) throw new Error(`World config share.services must be an array in ${path}`);
     for (const target of share.services as Partial<WorldShareServiceConfig>[]) {
       if (!target || typeof target !== 'object' || Array.isArray(target)) throw new Error(`Invalid share service in ${path}`);

package/src/serve.ts

@@ -0,0 +1,102 @@
+// Remote worlds (docs/ATTACH.md): a served world publishes its manifest over
+// HTTP and opens ONE advertised TLS door (the reflect front terminating the
+// advertised hostname alongside vendor hosts). The manifest an attacher
+// fetches has every vendor rewritten to the advertised origin — the injector
+// preserves the vendor Host header, the door routes by it, the twin answers.
+// Read-only publication: the manifest endpoint tracks no attachers and takes
+// no writes. An optional attach token protects manifest publication.
+import { timingSafeEqual } from 'node:crypto';
+import { createServer as createHttpServer, type Server as HttpServer } from 'node:http';
+import { deriveWorldManifest, type WorldManifest } from './attach.ts';
+import { statusWorld } from './runtime.ts';
+
+export const MANIFEST_PATH = '/.well-known/volter-world';
+
+/** The manifest a REMOTE attacher sees: every vendor behind the one advertised
+ * door. The serving side keeps routing against its own loopback env. */
+export function advertiseWorldManifest(name: string, root: string, advertisedOrigin: string): WorldManifest {
+  const local = deriveWorldManifest(name, statusWorld(name, root).env);
+  const vendors: Record<string, string> = {};
+  // /__vendor/<id> keeps the fetch flow routable through the one door (the
+  // injector's fetch patch rewrites URLs wholesale and loses the vendor Host);
+  // the http/https flow still Host-routes and ignores the origin's path.
+  for (const vendor of Object.keys(local.vendors)) vendors[vendor] = `${advertisedOrigin}/__vendor/${vendor}`;
+  return { ...local, vendors };
+}
+
+export interface ManifestServerOptions {
+  manifest: () => WorldManifest;
+  host?: string;
+  port?: number;
+  /** when set, GET requires `Authorization: Bearer <token>` — the attach token
+   * for a shared world (docs/ATTACH.md). Constant-time-ish compare via length
+   * gate + timingSafeEqual to avoid trivial token oracles. */
+  token?: string;
+}
+
+export interface ManifestServerHandle {
+  port: number;
+  close(): Promise<void>;
+}
+
+export async function startManifestServer(options: ManifestServerOptions): Promise<ManifestServerHandle> {
+  const server: HttpServer = createHttpServer((request, response) => {
+    if (options.token !== undefined) {
+      const presented = (request.headers.authorization ?? '').replace(/^Bearer\s+/i, '');
+      const expected = Buffer.from(options.token);
+      const actual = Buffer.from(presented);
+      if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+        response.writeHead(401, { 'content-type': 'text/plain' });
+        response.end('attach token required\n');
+        return;
+      }
+    }
+    if (request.method !== 'GET' || (request.url !== MANIFEST_PATH && request.url !== '/')) {
+      response.writeHead(404, { 'content-type': 'text/plain' });
+      response.end('volter-world: GET ' + MANIFEST_PATH + '\n');
+      return;
+    }
+    response.writeHead(200, { 'content-type': 'application/json' });
+    response.end(`${JSON.stringify(options.manifest(), null, 2)}\n`);
+  });
+  await new Promise<void>((resolveListen, reject) => {
+    server.once('error', reject);
+    server.listen(options.port ?? 0, options.host ?? '0.0.0.0', () => resolveListen());
+  });
+  const address = server.address();
+  return {
+    port: typeof address === 'object' && address ? address.port : (options.port ?? 0),
+    async close() {
+      await new Promise<void>((resolveClose) => server.close(() => resolveClose()));
+    },
+  };
+}
+
+/** Fetch a remote world's manifest. Accepts the manifest URL itself or the
+ * world's base URL (the well-known path is appended). */
+export async function fetchRemoteManifest(ref: string, options: { token?: string } = {}): Promise<WorldManifest> {
+  const base = ref.replace(/\/$/, '');
+  const url = base.endsWith(MANIFEST_PATH) ? base : `${base}${MANIFEST_PATH}`;
+  const response = await fetch(url, options.token === undefined ? undefined : { headers: { authorization: `Bearer ${options.token}` } });
+  if (!response.ok) throw new Error(`remote world manifest: ${url} → ${response.status}`);
+  const manifest = (await response.json()) as WorldManifest;
+  if (typeof manifest.name !== 'string' || typeof manifest.vendors !== 'object' || manifest.vendors === null) {
+    throw new Error(`remote world manifest: ${url} returned no manifest`);
+  }
+  return manifest;
+}
+
+/** The env a remote env-attachment exports: vendor twin URLs (the advertised
+ * door), suggested fake credentials, CA trust, and the injector preload. */
+export function remoteAttachEnv(
+  manifest: WorldManifest,
+  options: { caFile?: string; injectPath: string },
+): Record<string, string> {
+  const env: Record<string, string> = { ...manifest.env };
+  for (const [vendor, origin] of Object.entries(manifest.vendors)) {
+    env[`${vendor.toUpperCase()}_TWIN_URL`] = origin;
+  }
+  env.NODE_OPTIONS = `--require ${options.injectPath}`;
+  if (options.caFile !== undefined) env.NODE_EXTRA_CA_CERTS = options.caFile;
+  return env;
+}

package/src/tail.ts

@@ -0,0 +1,203 @@
+// `volter-world tail` — the live observability verb: one merged, causally-ordered (by
+// `occurredAt`) feed of a world's twin action ledgers. Strictly READ-ONLY over data at rest
+// (the per-service `actions.jsonl` files the control plane appends to — see
+// control-plane/src/actions.ts, plus — under `--requests` — the opt-in
+// `requests.jsonl` request journals serve.ts writes, shape + credential shape); the runtime stays a lifecycle primitive,
+// this just watches what the twins already record. A ledger dir may not exist until a service
+// records its first action, so discovery re-runs on every poll and a missing ledger is a
+// notice, never an error.
+import { closeSync, existsSync, openSync, readSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { stateDirName } from '@volter/twin';
+import { statusWorld } from './runtime.ts';
+
+/** The slice of a ledger row `tail` renders. Rows are vendor-recorded TwinActions
+ * (control-plane/src/actions.ts); everything else passes through untouched under `--json`. */
+type TailRecord = Record<string, unknown> & {
+  occurredAt?: string;
+  /** request-journal rows (requests.jsonl) carry `at` instead of `occurredAt`. */
+  at?: string;
+  op?: string;
+  operation?: string;
+  method?: string;
+  path?: string;
+  status?: number;
+  /** credential SHAPE on a request row: which header/query name carried a credential, and a
+   *  truncated sha256 of the value. Never the value — see control-plane/src/serve.ts. */
+  credentials?: Array<{ name?: string; in?: string; scheme?: string; fp?: string; empty?: true }>;
+  subject?: { type?: string; id?: string };
+};
+
+type TailEntry = { service: string; record: TailRecord; source: 'actions' | 'requests' };
+
+export type TailWorldOptions = {
+  root?: string;
+  /** Restrict the feed to these world service ids (default: every service in the world). */
+  services?: string[];
+  /** Keep watching for new entries after the initial dump (default true; `--no-follow` clears it). */
+  follow?: boolean;
+  /** Raw JSONL passthrough with the world service id injected as `service` (default: human lines). */
+  json?: boolean;
+  /** Also merge each service's opt-in REQUEST journal into the feed (`requests.jsonl`, written
+   * by twins running under VOLTER_TWIN_REQUEST_JOURNAL=1 — shape-only `{at, method, path,
+   * status}` rows; control-plane/src/serve.ts). Reads are otherwise invisible here: an
+   * empty-catalog GET that 404s leaves no trace in an actions-only tail. */
+  requests?: boolean;
+  /** Poll interval while following (ledger appends are cross-process, so this polls rather than
+   * fs.watch — watch descriptors can't see a file that doesn't exist yet). */
+  pollMs?: number;
+  /** Entry sink — one already-formatted line per call (default: process.stdout). */
+  write?: (line: string) => void;
+  /** Diagnostics sink for the one-time "no ledger yet" notices (default: process.stderr). */
+  notice?: (line: string) => void;
+  /** Aborting stops a following tail (the CLI wires Ctrl-C here). */
+  signal?: AbortSignal;
+};
+
+/** Every action ledger a world service currently owns. One world service can record actions
+ * under one or more STATE services (see runtime.ts `worldServiceStateService`), so this returns
+ * every `<data>/<service>/<state-dir>/world/<state-service>/actions.jsonl` present right now. */
+function serviceLedgers(dataDir: string, service: string, file: 'actions.jsonl' | 'requests.jsonl' = 'actions.jsonl'): string[] {
+  const stateRoot = join(dataDir, service, stateDirName(), 'world');
+  if (!existsSync(stateRoot)) return [];
+  return readdirSync(stateRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(stateRoot, entry.name, file)))
+    .map((entry) => join(stateRoot, entry.name, file))
+    .sort();
+}
+
+/** Read the complete lines appended to `path` since the recorded offset, advancing the offset
+ * only past the last newline — a half-written trailing line stays unconsumed until the writer
+ * finishes it, so a poll can never emit a torn row. */
+function readNewLines(path: string, offsets: Map<string, number>): string[] {
+  let offset = offsets.get(path) ?? 0;
+  let size: number;
+  try {
+    size = statSync(path).size;
+  } catch {
+    return []; // vanished between discovery and read (e.g. a purge mid-tail) — next poll rediscovers
+  }
+  if (size < offset) offset = 0; // rewritten shorter (scrub/rebuild) — replay rather than silently skip
+  if (size === offset) return [];
+  const fd = openSync(path, 'r');
+  const buffer = Buffer.alloc(size - offset);
+  try {
+    readSync(fd, buffer, 0, buffer.length, offset);
+  } finally {
+    closeSync(fd);
+  }
+  const lastNewline = buffer.lastIndexOf(0x0a);
+  if (lastNewline < 0) return [];
+  offsets.set(path, offset + lastNewline + 1);
+  return buffer.subarray(0, lastNewline).toString('utf8').split('\n').filter((line) => line.trim() !== '');
+}
+
+/** Local wall-clock `HH:MM:SS.mmm` — the operator is watching a live feed on this machine. */
+function formatOccurredAt(occurredAt: string | undefined): string {
+  const date = occurredAt === undefined ? new Date(NaN) : new Date(occurredAt);
+  if (Number.isNaN(date.getTime())) return '??:??:??.???';
+  const pad = (value: number, width = 2) => String(value).padStart(width, '0');
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}`;
+}
+
+/** The instant an entry sorts (and renders) by: actions carry `occurredAt`, request rows `at`. */
+function entryInstant(entry: TailEntry): string | undefined {
+  return entry.record.occurredAt ?? entry.record.at;
+}
+
+function formatEntry(entry: TailEntry, json: boolean): string {
+  if (json) return JSON.stringify({ ...entry.record, service: entry.service });
+  const { record } = entry;
+  if (entry.source === 'requests') {
+    // a served request, not an action: `HH:MM:SS.mmm <service> <METHOD> <path> <status>`, and —
+    // when the caller presented one — which credential arrived, named and fingerprinted. The
+    // fingerprint is short on purpose: enough to see "these two headers carried DIFFERENT keys"
+    // and "this is the same key as the line above" at a glance, never enough to be a secret.
+    const creds = (record.credentials ?? [])
+      .map((c) => `${c.name ?? '?'}${c.in === 'query' ? '(query)' : ''}=${c.empty ? 'EMPTY' : `${c.scheme ? `${c.scheme} ` : ''}${(c.fp ?? '').replace(/^sha256:/, '').slice(0, 8)}`}`)
+      .join(' ');
+    return `${formatOccurredAt(entryInstant(entry))} ${entry.service} ${record.method ?? '?'} ${record.path ?? '?'} ${record.status ?? '?'}${creds ? ` [${creds}]` : ''}`;
+  }
+  return `${formatOccurredAt(record.occurredAt)} ${entry.service} ${record.operation ?? record.op ?? '?'} ${record.subject?.id ?? '?'}`;
+}
+
+/** Stable causal order: the entry instant first; ties keep discovery order (service, file, line). */
+function byOccurredAt(a: TailEntry, b: TailEntry): number {
+  return (entryInstant(a) ?? '') < (entryInstant(b) ?? '') ? -1
+    : (entryInstant(a) ?? '') > (entryInstant(b) ?? '') ? 1 : 0;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const finish = (): void => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', finish);
+      resolve();
+    };
+    const timer = setTimeout(finish, ms);
+    signal?.addEventListener('abort', finish, { once: true });
+  });
+}
+
+/**
+ * Stream a world's action ledgers as one merged feed: dump everything recorded so far in
+ * `occurredAt` order, then (unless `follow` is false) poll for appends until `signal` aborts.
+ * New entries within each poll batch are `occurredAt`-sorted too, so concurrent services still
+ * read causally; cross-batch order is arrival order, as in any live tail.
+ */
+export async function tailWorldActions(name: string, options: TailWorldOptions = {}): Promise<void> {
+  const root = options.root ?? process.cwd();
+  const instance = statusWorld(name, root);
+  const known = Object.keys(instance.services);
+  for (const service of options.services ?? []) {
+    if (!instance.services[service]) {
+      throw new Error(`World ${name} has no service "${service}"; it has: ${known.join(', ')}`);
+    }
+  }
+  const services = options.services?.length ? options.services : known;
+  const follow = options.follow ?? true;
+  const json = options.json ?? false;
+  const pollMs = options.pollMs ?? 200;
+  const write = options.write ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const notice = options.notice ?? ((line: string) => process.stderr.write(`${line}\n`));
+
+  const offsets = new Map<string, number>();
+  const sources: Array<'actions' | 'requests'> = options.requests ? ['actions', 'requests'] : ['actions'];
+  const collect = (): TailEntry[] => {
+    const entries: TailEntry[] = [];
+    for (const service of services) {
+      for (const source of sources) {
+        for (const ledger of serviceLedgers(instance.dirs.data, service, source === 'actions' ? 'actions.jsonl' : 'requests.jsonl')) {
+          for (const line of readNewLines(ledger, offsets)) {
+            try {
+              entries.push({ service, record: JSON.parse(line) as TailRecord, source });
+            } catch {
+              // a corrupt row must not kill a live feed; the ledger itself is untouched
+            }
+          }
+        }
+      }
+    }
+    return entries.sort(byOccurredAt);
+  };
+
+  const emit = (entries: TailEntry[]): void => {
+    for (const entry of entries) write(formatEntry(entry, json));
+  };
+
+  emit(collect());
+  for (const service of services) {
+    if (serviceLedgers(instance.dirs.data, service).length === 0) {
+      notice(`World ${name}: service "${service}" has no action ledger yet${follow
+        ? ' — watching; drive the app (or a vendor SDK) through the world to record actions'
+        : '; drive the app (or a vendor SDK) through the world to record actions, then tail again'}`);
+    }
+  }
+  if (!follow) return;
+
+  while (!options.signal?.aborted) {
+    await sleep(pollMs, options.signal);
+    if (options.signal?.aborted) return;
+    emit(collect());
+  }
+}