@volter/world-runtime 3.0.5 → 3.0.7

package/dist/src/index.d.ts

@@ -46,7 +46,7 @@ export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServe
 export type { BranchDoors, BranchRow, DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.js';
 export { LocalBranches } from './local-branches.js';
 export { serveWorldView, VIEW_CONSOLE_BASE } from './world-view.js';
-export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from './world-origins.js';
+export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from './world-origins.js';
 export type { ViewConsole, WorldView } from './world-view.js';
 export type { LocalBranchesOptions } from './local-branches.js';
 export type { ServedWorld } from './served-world.js';

package/dist/src/index.js

@@ -33,7 +33,7 @@ export { deployWorld, refreshTwin, adaptersFor, credentialPath, rewrapTwinCreden
 export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from "./served-world.js";
 export { LocalBranches } from "./local-branches.js";
 export { serveWorldView, VIEW_CONSOLE_BASE } from "./world-view.js";
-export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
+export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor } from "./console-apart.js";
 export { assertWorldStateRemovable } from "./ancestry.js";
 export { withoutVaultSignIn } from "./runtime.js";

package/dist/src/pack-facts.d.ts

@@ -42,6 +42,11 @@ export type PackFacts = {
         body: Record<string, unknown>;
         fill: Record<string, string>;
     };
+    /** The door listing the hostnames the twin answers while it runs (TwinPack.hostsClaimed). */
+    hostsClaimed?: {
+        door: string;
+        note?: string;
+    };
     credentialIssuer?: string;
     /** The pack's colocatable `create<Name>TwinServer` factory export, derived (or descriptor-
      *  declared under ambiguity) by scripts/pack-facts.ts. Consumed by `init` to emit

package/dist/src/served-world.d.ts

@@ -54,7 +54,8 @@ export type MountedWorld = {
         token: string;
         readToken: string;
     };
-    handle: (request: Request) => Promise<Response>;
+    handle: (request: Request) => Promise<Response>; /** a hostname this World's twins answer, as a browser reads it (siteOfHost) */
+    site: (request: Request, host: string) => Promise<Response>;
     boot: (url: string) => Promise<void>;
     stop: () => Promise<void>;
 };
@@ -291,6 +292,15 @@ export declare class WorldDoors {
     private refresh;
     private controlRoot;
     private stateOf;
+    /** The hostnames each of this World's twins answers while it runs (its hostsClaimed door). */
+    claimedHosts(origin: string): Promise<Array<{
+        vendor: string;
+        hosts: string[];
+    }>>;
+    /** A hostname one of this World's twins answers (its hostsClaimed door lists it), read as a browser reads it there:
+     *  the request goes to that twin with the hostname as its original host, as the injector routes it inside the World.
+     *  Reads only: the site is the twin's state as the World holds it, never a way to write it. */
+    site(request: Request, host: string): Promise<Response>;
     handle(request: Request): Promise<Response>;
     /** A twin's workspaces as its discovery door lists them (`GET /twin`'s `screens`: each built workspace screen's id and
      *  path), which a person is shown at `/<served>/<vendor><path>`. Asked again after a minute, as `enforcesRead` is. */

package/dist/src/served-world.js

@@ -158,6 +158,7 @@ export async function mountWorld(name, opts = {}) {
         twins: () => world.twins(),
         rotate: () => { world.retoken(mintToken('tok_'), mintToken('tok_r_')); keep(); return { token: world.token, readToken: world.readToken }; },
         handle: (request) => world.handle(request),
+        site: (request, host) => world.site(request, host),
         async boot(url) {
             keep();
             const port = Number(new URL(url).port) || 0;
@@ -746,6 +747,56 @@ export class WorldDoors {
     stateOf(vendor) {
         return stateServiceOf(this.controlRoot(vendor), vendor);
     }
+    /** The hostnames each of this World's twins answers while it runs (its hostsClaimed door). */
+    async claimedHosts(origin) {
+        const out = [];
+        for (const vendor of Object.keys(this.up().services)) {
+            const door = packFacts()[vendor]?.hostsClaimed?.door;
+            const twin = door ? this.host.twinFetch(vendor) : undefined;
+            if (!door || !twin)
+                continue;
+            const listed = await twin(new Request(`${origin}${door}`, { headers: { [READ_ONLY_HEADER]: '1' } })).then((r) => (r.ok ? r.json() : null)).catch(() => null);
+            const hosts = Array.isArray(listed?.hosts) ? listed.hosts.map((h) => String(h).toLowerCase()) : [];
+            if (hosts.length)
+                out.push({ vendor, hosts });
+        }
+        return out;
+    }
+    /** A hostname one of this World's twins answers (its hostsClaimed door lists it), read as a browser reads it there:
+     *  the request goes to that twin with the hostname as its original host, as the injector routes it inside the World.
+     *  Reads only: the site is the twin's state as the World holds it, never a way to write it. */
+    async site(request, host) {
+        if (request.method !== 'GET' && request.method !== 'HEAD')
+            return Response.json({ error: 'a site in a World is read: GET and HEAD' }, { status: 405 });
+        const url = new URL(request.url);
+        for (const { vendor, hosts } of await this.claimedHosts(url.origin)) {
+            const twin = this.host.twinFetch(vendor);
+            if (!twin || !hosts.includes(host))
+                continue;
+            const headers = new Headers();
+            for (const name of ['accept', 'accept-language', 'if-none-match', 'range', 'user-agent']) {
+                const v = request.headers.get(name);
+                if (v !== null)
+                    headers.set(name, v);
+            }
+            headers.set('x-volter-twin-original-host', host);
+            headers.set(READ_ONLY_HEADER, '1');
+            const answer = await twin(new Request(`${url.origin}${url.pathname}${url.search}`, { method: request.method, headers, redirect: 'manual' }));
+            // a redirect the site answers names its own hostname: in the World it stays under the World's origin
+            const out = new Headers(answer.headers);
+            const location = out.get('location');
+            if (location) {
+                try {
+                    const to = new URL(location, `https://${host}`);
+                    if (to.hostname === host)
+                        out.set('location', `${to.pathname}${to.search}${to.hash}`);
+                }
+                catch { /* left as answered */ }
+            }
+            return new Response(request.method === 'HEAD' ? null : answer.body, { status: answer.status, statusText: answer.statusText, headers: out });
+        }
+        return Response.json({ error: `no twin of ${this.served} answers ${host}` }, { status: 404 });
+    }
     async handle(request) {
         try {
             if (!this.host.ready() && !new URL(request.url).pathname.startsWith('/-/ping'))
@@ -1124,9 +1175,15 @@ export class WorldDoors {
             return Response.json(await this.map());
         if (kind === 'timeline' && !name && request.method === 'GET')
             return this.timeline(url);
+        // the sites this World's twins answer (a Workers Custom Domain, an R2 public domain), each read in a browser at
+        // `<hostname>.<the World's origin>` (siteOfHost)
+        if (kind === 'sites' && !name && request.method === 'GET')
+            return Response.json({ world: this.served, sites: (await this.claimedHosts(url.origin)).flatMap((c) => c.hosts.map((host) => ({ twin: c.vendor, host }))) });
         if (kind === 'diff' && !name && request.method === 'GET') {
             const delta = diffWorld(this.name, { root: this.worldRoot });
-            return Response.json({ world: this.served, base: { id: delta.base.id, at: delta.base.createdAt ?? null }, changes: delta.actions.map((a) => ({ twin: a.service, entry: a.action })) });
+            // what another World pushed here is in its changeset already: never this World's uncut changes
+            const received = new Set(listWorldChangesets({ root: this.worldRoot, world: this.name }).filter((l) => l.changeset.pushedBy).flatMap((l) => l.changeset.actions.map((a) => a.action.id)));
+            return Response.json({ world: this.served, base: { id: delta.base.id, at: delta.base.createdAt ?? null }, changes: delta.actions.filter((a) => !received.has(a.action.id)).map((a) => ({ twin: a.service, entry: a.action })) });
         }
         if (kind === 'log' && name && request.method === 'GET') {
             const state = this.stateOf(name);

package/dist/src/world-origins.d.ts

@@ -11,3 +11,10 @@ export declare function worldDoorUnderConsole(path: string, served: (name: strin
 /** Whether a path on a World's origin belongs to that World (its wire, its doors, its vendors' screens) or to
  *  what every origin carries (`/-/ping`, the console): a World's origin serves no other World. */
 export declare function pathOfWorld(path: string, served: string, consoleBase: string): boolean;
+/** A site a World's twins answer, reached under the World's origin: `<hostname>.<world>--<org>.localhost` names the
+ *  hostname `<hostname>` as that World's twins answer it (a Workers Custom Domain, an R2 public domain). The World and
+ *  the hostname, or undefined for any other host. Each site is an origin of its own, apart from the World's session. */
+export declare function siteOfHost(hostname: string, served: Iterable<string>, base?: string): {
+    world: string;
+    site: string;
+} | undefined;

package/dist/src/world-origins.js

@@ -35,3 +35,21 @@ export function worldDoorUnderConsole(path, served, consoleBase) {
 export function pathOfWorld(path, served, consoleBase) {
     return path === '/-/ping' || path === consoleBase || path.startsWith(`${consoleBase}/`) || path.startsWith(`/${served}/`) || path.startsWith(`/-/${served}/`) || path === `/${served}` || path === `/-/${served}`;
 }
+/** A site a World's twins answer, reached under the World's origin: `<hostname>.<world>--<org>.localhost` names the
+ *  hostname `<hostname>` as that World's twins answer it (a Workers Custom Domain, an R2 public domain). The World and
+ *  the hostname, or undefined for any other host. Each site is an origin of its own, apart from the World's session. */
+export function siteOfHost(hostname, served, base = LOCAL_ORIGIN_BASE) {
+    const suffix = `.${base}`;
+    if (!hostname.endsWith(suffix))
+        return undefined;
+    const rest = hostname.slice(0, -suffix.length);
+    for (const name of served) {
+        const label = worldOriginLabel(name);
+        if (!label || !rest.endsWith(`.${label}`))
+            continue;
+        const site = rest.slice(0, -(label.length + 1));
+        if (site.includes('.'))
+            return { world: name, site };
+    }
+    return undefined;
+}

package/dist/src/world-view.js

@@ -8,7 +8,7 @@ import { join, resolve } from 'node:path';
 import { serveHttp, stateDirName } from '@volter/world-core/runtime';
 import { LocalBranches } from "./local-branches.js";
 import { mountWorld } from "./served-world.js";
-import { localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
+import { localWorldOrigin, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
 export const VIEW_CONSOLE_BASE = '/-/console';
 /** The branch Worlds already under `dir` (`<dir>/<org>/<world>/.volter/world.json`). */
 function branchRoots(dir) {
@@ -110,6 +110,10 @@ export async function serveWorldView(name, opts = {}) {
             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
+            // a site the World's twins answer, under the World's local origin (`<hostname>.<world>--<org>.localhost`)
+            const site = origins && !proxied ? siteOfHost(at.hostname, worlds.keys()) : undefined;
+            if (site)
+                return worlds.get(site.world).site(request, site.site);
             const own = origins ? (proxied && at.host === proxied.host ? base : worldOfHost(at.hostname, worlds.keys())) : undefined;
             if (own === null)
                 return Response.json({ error: `no world at ${at.host}` }, { status: 404 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.5",
+  "version": "3.0.7",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -68,14 +68,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.5",
-    "@volter/world-console": "3.0.1"
+    "@volter/world-core": "3.0.7",
+    "@volter/world-console": "3.0.2"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.5",
+    "@volter/world-core": "3.0.7",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",
     "yaml": "2.9.0"

package/src/index.ts

@@ -168,7 +168,7 @@ export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServe
 export type { BranchDoors, BranchRow, DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.ts';
 export { LocalBranches } from './local-branches.ts';
 export { serveWorldView, VIEW_CONSOLE_BASE } from './world-view.ts';
-export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from './world-origins.ts';
+export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from './world-origins.ts';
 export type { ViewConsole, WorldView } from './world-view.ts';
 export type { LocalBranchesOptions } from './local-branches.ts';
 export type { ServedWorld } from './served-world.ts';

package/src/pack-facts.ts

@@ -22,6 +22,8 @@ export type PackFacts = {
   endpointEnvNone?: string;
   /** The door that issues the application a credential the twin accepts (TwinPack.credentialDoor). */
   credentialDoor?: { path: string; body: Record<string, unknown>; fill: Record<string, string> };
+  /** The door listing the hostnames the twin answers while it runs (TwinPack.hostsClaimed). */
+  hostsClaimed?: { door: string; note?: string };
   credentialIssuer?: string;
   /** The pack's colocatable `create<Name>TwinServer` factory export, derived (or descriptor-
    *  declared under ambiguity) by scripts/pack-facts.ts. Consumed by `init` to emit

package/src/served-world.ts

@@ -115,7 +115,7 @@ function configRefFor(worldRoot: string, name: string): string {
 /** A world mounted by a host. `token`/`readToken` read the CURRENT tokens (rotate changes them);
  *  `twins()` names the world's twins once booted; `rotate()` mints both tokens anew — the old die
  *  with the call — and keeps them beside the world like `boot` does. */
-export type MountedWorld = { name: string; served: string; root: string; readonly token: string; readonly readToken: string; twins: () => string[]; rotate: () => { token: string; readToken: string }; handle: (request: Request) => Promise<Response>; boot: (url: string) => Promise<void>; stop: () => Promise<void> };
+export type MountedWorld = { name: string; served: string; root: string; readonly token: string; readonly readToken: string; twins: () => string[]; rotate: () => { token: string; readToken: string }; handle: (request: Request) => Promise<Response>; /** a hostname this World's twins answer, as a browser reads it (siteOfHost) */ site: (request: Request, host: string) => Promise<Response>; boot: (url: string) => Promise<void>; stop: () => Promise<void> };
 /** A browser session a World keeps: its scope, when it ends, and the person a pass named, when one did. */
 type HeldSession = { scope: 'read' | 'write'; until: number; /** opened by this machine's own page (localSession) */ local?: true; who?: string; /** the platform whose pass opened it */ issuer?: string; /** the person's subject there */ sub?: string; /** the read key a shared link opened it with: it lasts only while that key does */ key?: string };
 
@@ -169,6 +169,7 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
     twins: () => world.twins(),
     rotate: () => { world.retoken(mintToken('tok_'), mintToken('tok_r_')); keep(); return { token: world.token, readToken: world.readToken }; },
     handle: (request) => world.handle(request),
+    site: (request, host) => world.site(request, host),
     async boot(url) {
       keep();
       const port = Number(new URL(url).port) || 0;
@@ -671,6 +672,43 @@ export class WorldDoors {
     return stateServiceOf(this.controlRoot(vendor), vendor);
   }
 
+  /** The hostnames each of this World's twins answers while it runs (its hostsClaimed door). */
+  async claimedHosts(origin: string): Promise<Array<{ vendor: string; hosts: string[] }>> {
+    const out: Array<{ vendor: string; hosts: string[] }> = [];
+    for (const vendor of Object.keys(this.up().services)) {
+      const door = packFacts()[vendor]?.hostsClaimed?.door;
+      const twin = door ? this.host.twinFetch(vendor) : undefined;
+      if (!door || !twin) continue;
+      const listed = await twin(new Request(`${origin}${door}`, { headers: { [READ_ONLY_HEADER]: '1' } })).then((r) => (r.ok ? r.json() as Promise<{ hosts?: unknown }> : null)).catch(() => null);
+      const hosts = Array.isArray(listed?.hosts) ? (listed.hosts as unknown[]).map((h) => String(h).toLowerCase()) : [];
+      if (hosts.length) out.push({ vendor, hosts });
+    }
+    return out;
+  }
+
+  /** A hostname one of this World's twins answers (its hostsClaimed door lists it), read as a browser reads it there:
+   *  the request goes to that twin with the hostname as its original host, as the injector routes it inside the World.
+   *  Reads only: the site is the twin's state as the World holds it, never a way to write it. */
+  async site(request: Request, host: string): Promise<Response> {
+    if (request.method !== 'GET' && request.method !== 'HEAD') return Response.json({ error: 'a site in a World is read: GET and HEAD' }, { status: 405 });
+    const url = new URL(request.url);
+    for (const { vendor, hosts } of await this.claimedHosts(url.origin)) {
+      const twin = this.host.twinFetch(vendor);
+      if (!twin || !hosts.includes(host)) continue;
+      const headers = new Headers();
+      for (const name of ['accept', 'accept-language', 'if-none-match', 'range', 'user-agent']) { const v = request.headers.get(name); if (v !== null) headers.set(name, v); }
+      headers.set('x-volter-twin-original-host', host);
+      headers.set(READ_ONLY_HEADER, '1');
+      const answer = await twin(new Request(`${url.origin}${url.pathname}${url.search}`, { method: request.method, headers, redirect: 'manual' }));
+      // a redirect the site answers names its own hostname: in the World it stays under the World's origin
+      const out = new Headers(answer.headers);
+      const location = out.get('location');
+      if (location) { try { const to = new URL(location, `https://${host}`); if (to.hostname === host) out.set('location', `${to.pathname}${to.search}${to.hash}`); } catch { /* left as answered */ } }
+      return new Response(request.method === 'HEAD' ? null : answer.body, { status: answer.status, statusText: answer.statusText, headers: out });
+    }
+    return Response.json({ error: `no twin of ${this.served} answers ${host}` }, { status: 404 });
+  }
+
   async handle(request: Request): Promise<Response> {
     try {
       if (!this.host.ready() && !new URL(request.url).pathname.startsWith('/-/ping')) return Response.json({ error: 'booting', world: this.served }, { status: 503, headers: { 'retry-after': '1' } });
@@ -975,9 +1013,14 @@ export class WorldDoors {
     }
     if (kind === 'map' && !name && request.method === 'GET') return Response.json(await this.map());
     if (kind === 'timeline' && !name && request.method === 'GET') return this.timeline(url);
+    // the sites this World's twins answer (a Workers Custom Domain, an R2 public domain), each read in a browser at
+    // `<hostname>.<the World's origin>` (siteOfHost)
+    if (kind === 'sites' && !name && request.method === 'GET') return Response.json({ world: this.served, sites: (await this.claimedHosts(url.origin)).flatMap((c) => c.hosts.map((host) => ({ twin: c.vendor, host }))) });
     if (kind === 'diff' && !name && request.method === 'GET') {
       const delta = diffWorld(this.name, { root: this.worldRoot });
-      return Response.json({ world: this.served, base: { id: delta.base.id, at: delta.base.createdAt ?? null }, changes: delta.actions.map((a) => ({ twin: a.service, entry: a.action })) });
+      // what another World pushed here is in its changeset already: never this World's uncut changes
+      const received = new Set(listWorldChangesets({ root: this.worldRoot, world: this.name }).filter((l) => l.changeset.pushedBy).flatMap((l) => l.changeset.actions.map((a) => a.action.id)));
+      return Response.json({ world: this.served, base: { id: delta.base.id, at: delta.base.createdAt ?? null }, changes: delta.actions.filter((a) => !received.has(a.action.id)).map((a) => ({ twin: a.service, entry: a.action })) });
     }
 
     if (kind === 'log' && name && request.method === 'GET') {

package/src/world-origins.ts

@@ -36,3 +36,19 @@ export function worldDoorUnderConsole(path: string, served: (name: string) => bo
 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}`;
 }
+
+/** A site a World's twins answer, reached under the World's origin: `<hostname>.<world>--<org>.localhost` names the
+ *  hostname `<hostname>` as that World's twins answer it (a Workers Custom Domain, an R2 public domain). The World and
+ *  the hostname, or undefined for any other host. Each site is an origin of its own, apart from the World's session. */
+export function siteOfHost(hostname: string, served: Iterable<string>, base = LOCAL_ORIGIN_BASE): { world: string; site: string } | undefined {
+  const suffix = `.${base}`;
+  if (!hostname.endsWith(suffix)) return undefined;
+  const rest = hostname.slice(0, -suffix.length);
+  for (const name of served) {
+    const label = worldOriginLabel(name);
+    if (!label || !rest.endsWith(`.${label}`)) continue;
+    const site = rest.slice(0, -(label.length + 1));
+    if (site.includes('.')) return { world: name, site };
+  }
+  return undefined;
+}

package/src/world-view.ts

@@ -8,7 +8,7 @@ import { join, resolve } from 'node:path';
 import { serveHttp, stateDirName } from '@volter/world-core/runtime';
 import { LocalBranches } from './local-branches.ts';
 import { mountWorld, type MountedWorld } from './served-world.ts';
-import { localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from './world-origins.ts';
+import { localWorldOrigin, pathOfWorld, siteOfHost, 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> };
@@ -99,6 +99,9 @@ export async function serveWorldView(name: string, opts: { /** the person signed
         : incoming;
       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
+      // a site the World's twins answer, under the World's local origin (`<hostname>.<world>--<org>.localhost`)
+      const site = origins && !proxied ? siteOfHost(at.hostname, worlds.keys()) : undefined;
+      if (site) return worlds.get(site.world)!.site(request, site.site);
       const own = origins ? (proxied && at.host === proxied.host ? base! : 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