@volter/world-runtime 2.0.0 → 2.0.2

package/src/service-recorder.ts

@@ -46,7 +46,7 @@ const record = (entry: Record<string, unknown>, then?: () => void): void => {
 };
 
 const started = Date.now();
-const child = spawn(command, args, { stdio: 'inherit', env });
+const child = spawn(command, args, { windowsHide: true, stdio: 'inherit', env });
 if (child.pid !== undefined) record({ event: 'world.service.started', pid: child.pid, parentPid: process.pid });
 
 /** The log's last `bytes` (from a line start) as the rotation `<log>.1`: however far a runaway writer overshot the cap,

package/src/storage-capacity.ts

@@ -18,7 +18,7 @@ export function storagePoolResolver(onFailure?: (failure: StorageProbeFailure) =
       let pool: string | undefined;
       if (process.platform === 'darwin') {
         stage = 'volume lookup';
-        const df = execFileSync('/bin/df', ['-P', root], { encoding: 'utf8', timeout: 3000, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'ignore'] });
+        const df = execFileSync('/bin/df', ['-P', root], { windowsHide: true, encoding: 'utf8', timeout: 3000, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'ignore'] });
         const disk = df.trim().split('\n').at(-1)?.trim().split(/\s+/)[0];
         if (disk && /^\/dev\/disk\d+(?:s\d+)*$/.test(disk)) {
           stage = 'volume metadata';
@@ -49,7 +49,7 @@ export function storagePoolResolver(onFailure?: (failure: StorageProbeFailure) =
 }
 
 function diskInfo(disk: string): string {
-  return execFileSync('/usr/sbin/diskutil', ['info', '-plist', disk], {
+  return execFileSync('/usr/sbin/diskutil', ['info', '-plist', disk], { windowsHide: true,
     encoding: 'utf8', timeout: 3000, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'ignore'],
   });
 }

package/src/up-task.ts

@@ -14,7 +14,7 @@ export type UpTaskReply = { instance: WorldInstance } | { error: string };
  *  is not the caller's to keep, so the boot completes and its outcome is written to the lifecycle log. */
 export function superviseWorldUp(configId: string, options: UpWorldOptions): Promise<WorldInstance> {
   return new Promise((done, reject) => {
-    const child = spawn(process.execPath, [siblingScript(import.meta.url, 'up-task-worker')], {
+    const child = spawn(process.execPath, [siblingScript(import.meta.url, 'up-task-worker')], { windowsHide: true,
       cwd: process.cwd(), env: process.env, detached: process.platform !== 'win32',
       stdio: ['ignore', 'inherit', 'inherit', 'ipc'], serialization: 'json',
     });

package/src/world-origins.ts

@@ -0,0 +1,38 @@
+// WORLD ORIGINS for a local host (docs/contributing/architecture.md, "Viewing a World"): each World a
+// browser steps into is reached at an origin of its own, `http://<world>--<org>.localhost:<port>`, so no
+// World's page shares an origin with another World's session. Browsers and curl resolve `*.localhost`
+// to loopback. Callers that present a token keep path addressing on the host's own origin.
+import { worldOriginLabel } from './served-world.ts';
+
+export const LOCAL_ORIGIN_BASE = 'localhost';
+
+/** The origin a browser reaches `served` at on a local host listening on `port`, or null when its
+ *  names make no label. */
+export function localWorldOrigin(served: string, port: number, base = LOCAL_ORIGIN_BASE): string | null {
+  const label = worldOriginLabel(served);
+  return label ? `http://${label}.${base}:${port}` : null;
+}
+
+/** Which World a request's host names: undefined for a host that is not a World's origin (the host's
+ *  own, path-addressed), null for a World-origin-shaped host naming no World served here. */
+export function worldOfHost(hostname: string, served: Iterable<string>, base = LOCAL_ORIGIN_BASE): string | null | undefined {
+  const suffix = `.${base}`;
+  if (!hostname.endsWith(suffix)) return undefined;
+  const label = hostname.slice(0, -suffix.length);
+  for (const name of served) if (worldOriginLabel(name) === label) return name;
+  return null;
+}
+
+/** Whether a path under the console's base is a door of a World served here: a World whose org shares the console's
+ *  name (`console/<world>`) has its doors at `/-/console/<world>/…`, and they are the World's, never the console's. */
+export function worldDoorUnderConsole(path: string, served: (name: string) => boolean, consoleBase: string): boolean {
+  if (path !== consoleBase && !path.startsWith(`${consoleBase}/`)) return false;
+  const m = /^\/-\/([^/]+)\/([^/]+)/.exec(path);
+  return Boolean(m && served(`${m[1]}/${m[2]}`));
+}
+
+/** Whether a path on a World's origin belongs to that World (its wire, its doors, its mirrors) or to
+ *  what every origin carries (`/-/ping`, the console): a World's origin serves no other World. */
+export function pathOfWorld(path: string, served: string, consoleBase: string): boolean {
+  return path === '/-/ping' || path === consoleBase || path.startsWith(`${consoleBase}/`) || path.startsWith(`/${served}/`) || path.startsWith(`/-/${served}/`) || path === `/${served}` || path === `/-/${served}`;
+}

package/src/world-view.ts

@@ -0,0 +1,100 @@
+// THE LOCAL VIEW: one World served for a person to step into — its doors, its mirrors, its branches
+// ("as of" views) and the console, on one origin (docs/contributing/architecture.md, "Viewing a
+// World"). `volter world view` is this; the runtime's `up` gains no step. A host that serves many
+// Worlds (world-host) answers the same doors; this serves one, and the branches made of it.
+import { existsSync, readdirSync } from 'node:fs';
+import { loadWorldConfig } from './configs.ts';
+import { join, resolve } from 'node:path';
+import { serveHttp, stateDirName } from '@volter/world-core';
+import { LocalBranches } from './local-branches.ts';
+import { mountWorld, type MountedWorld } from './served-world.ts';
+import { localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from './world-origins.ts';
+
+/** A console as a host mounts it (`@volter/world-console`): answer a request under `base`, or null. */
+export type ViewConsole = { handle: (request: Request, base: string, opts?: { worldOrigin?: boolean }) => Promise<Response | null> };
+export const VIEW_CONSOLE_BASE = '/-/console';
+export type WorldView = { url: string; base: string; served: string; token: string; readToken: string; console: string | null; /** the World's own browser origin, when it has one */ origin: string | null; stop: () => Promise<void> };
+
+/** The branch Worlds already under `dir` (`<dir>/<org>/<world>/.volter/world.json`). */
+function branchRoots(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const org of readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory())) {
+    for (const world of readdirSync(join(dir, org.name), { withFileTypes: true }).filter((e) => e.isDirectory())) {
+      const root = join(dir, org.name, world.name);
+      if (existsSync(join(root, stateDirName(), 'world.json'))) out.push(root);
+    }
+  }
+  return out.sort();
+}
+
+export async function serveWorldView(name: string, opts: { root?: string; port?: number; host?: string; console?: ViewConsole; announce?: (line: string) => void; /** each World a browser steps into at an origin of its own (on by default on loopback) */ origins?: boolean } = {}): Promise<WorldView> {
+  const root = resolve(opts.root ?? process.cwd());
+  const host = opts.host ?? '127.0.0.1';
+  const worlds = new Map<string, MountedWorld>();
+  let loopback = ''; let port = 0;
+  const loopbackBind = host === '127.0.0.1' || host === 'localhost' || host === '::1';
+  // each World's browser session on an origin of its own, where the view listens on loopback (*.localhost)
+  const origins = opts.origins ?? loopbackBind;
+  // bound to loopback with an origin per World, the view is for the person at this machine: its pages need no token
+  // (served-world.ts localSession). Without origins every World's pages share one, and none is handed a session.
+  const local = loopbackBind && origins;
+  // a non-loopback --host turns origins off by default: say so (the World and its branches then share one origin)
+  if (opts.origins === undefined && !origins) opts.announce?.(`origins  off (bound to ${host}): the World and its branches share one origin, where a browser session is only path-scoped; bind loopback for an origin per World`);
+  const browserOrigin = origins ? (served: string) => (port ? localWorldOrigin(served, port) : null) : undefined;
+  const mountAt = (at: string): Promise<MountedWorld> => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}) });
+  const branches: LocalBranches = new LocalBranches({ dir: join(root, stateDirName(), 'branches'), origin: () => loopback, worlds, mount: mountAt, ...(opts.announce ? { announce: opts.announce } : {}) });
+  const world = await mountWorld(name, { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}) });
+  worlds.set(world.served, world);
+  const server = await serveHttp({
+    // a pushed blob (a release video) is one PUT: bodies up to 1 GiB, as `serve` takes them
+    hostname: host, port: opts.port ?? 0, maxRequestBodySize: 1024 * 1024 * 1024,
+    // this front serves a World and its branches; each World's own twins journal their requests
+    twinRequestJournal: false,
+    async fetch(request) {
+      const at = new URL(request.url); const path = at.pathname;
+      // a World's own origin serves that World (and the ping and the console) and no other
+      const own = origins ? worldOfHost(at.hostname, worlds.keys()) : undefined;
+      if (own === null) return Response.json({ error: `no world at ${at.host}` }, { status: 404 });
+      // the bare address, typed into a browser, is the World's page: at its own origin when it has one
+      if (opts.console && path === '/' && request.method === 'GET' && (request.headers.get('accept') ?? '').includes('text/html')) {
+        const served = own ?? world.served; const page = `${VIEW_CONSOLE_BASE}/${served}`;
+        return Response.redirect(own ? `${at.origin}${page}` : `${browserOrigin?.(served) ?? at.origin}${page}`, 302);
+      }
+      if (own && !pathOfWorld(path, own, VIEW_CONSOLE_BASE)) return Response.json({ error: `this origin serves ${own} only` }, { status: 404 });
+      if (path === '/-/ping') return Response.json({ ok: true, worlds: own ? [own] : [...worlds.keys()], ...(opts.console ? { console: `${VIEW_CONSOLE_BASE}/` } : {}) });
+      if (opts.console && (path === VIEW_CONSOLE_BASE || path.startsWith(`${VIEW_CONSOLE_BASE}/`)) && !worldDoorUnderConsole(path, (n) => worlds.has(n), VIEW_CONSOLE_BASE)) {
+        // on a World's own origin the console keeps no token script can read (its session is the credential)
+        const answered = await opts.console.handle(request, VIEW_CONSOLE_BASE, own ? { worldOrigin: true } : undefined);
+        if (answered) return answered;
+      }
+      const m = /^\/(?:-\/)?([^/]+)\/([^/]+)/.exec(path);
+      const target = m ? worlds.get(`${m[1]}/${m[2]}`) : undefined;
+      if (!target) return Response.json({ error: `no world at ${path}: this view serves ${[...worlds.keys()].join(', ')}` }, { status: 404 });
+      return target.handle(request);
+    },
+  });
+  port = server.port ?? 0;
+  const url = `http://${host}:${server.port}`;
+  loopback = `http://${host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host}:${server.port}`;
+  // a branch outlives the view that made it until its time runs out: stopping stops its compute only
+  const stop = async (): Promise<void> => {
+    branches.stop();
+    await server.stop(true);
+    for (const w of [...worlds.values()].reverse()) await w.stop();
+  };
+  try {
+    await world.boot(url);
+    // branches an earlier view made: mounted again (the sweep then removes those whose time ran out)
+    for (const at of branchRoots(join(root, stateDirName(), 'branches'))) {
+      const b = await mountAt(at);
+      await b.boot(url);
+      worlds.set(b.served, b);
+    }
+    await branches.resume();
+  } catch (error) { await stop().catch(() => undefined); throw error; }
+  // the console opens on the World's own origin, where its session lives
+  const consoleUrl = opts.console ? `${browserOrigin?.(world.served) ?? url}${VIEW_CONSOLE_BASE}/${world.served}` : null;
+  opts.announce?.(`viewing  ${world.served}  ${url}/${world.served}${consoleUrl ? `\nconsole  ${consoleUrl}` : ''}`);
+  return { url, base: `${url}/${world.served}`, served: world.served, get token() { return world.token; }, get readToken() { return world.readToken; }, console: consoleUrl, origin: browserOrigin?.(world.served) ?? null, stop };
+}