@volter/world-runtime 2.0.13 → 2.0.14

package/dist/src/redirect-proxy.js

@@ -351,8 +351,12 @@ export async function startRedirectProxy(options) {
                     for (const [k, v] of Object.entries(loadInject().appForwardHeaders(new URL(`https://${req.headers.get('host') ?? vendorHost}`))))
                         headers.set(k, v);
                 }
-                else if (env.VOLTER_TWINS_KEY)
-                    headers.set('x-twins-key', env.VOLTER_TWINS_KEY);
+                else {
+                    if (env.VOLTER_TWINS_KEY)
+                        headers.set('x-twins-key', env.VOLTER_TWINS_KEY);
+                    // the caller reached the vendor's host over TLS, which ends here: the twin renders its own links with https
+                    headers.set('x-forwarded-proto', 'https');
+                }
                 // Hosted namespaces need their transport Host; direct twins can use
                 // the original Host for vendor semantics (for example S3 buckets).
                 if (origin.pathname.replace(/\/$/, '') && twin.vendor !== 'app') {

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

@@ -63,7 +63,8 @@ export declare function mountWorld(name: string, opts?: {
     root?: string; /** the host's branches of this World, by its served name */
     branches?: (served: string) => BranchDoors | undefined; /** the origin a browser reaches this World at, when the host gives each World one */
     browserOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */
-    localTrust?: boolean;
+    localTrust?: boolean; /** DoorHost.serveBranch */
+    serveBranch?: (branch: string) => Promise<void>;
 }): Promise<MountedWorld>;
 /** Boot the world (state kept) and serve it on its own port. Announces and returns after boot; `stop` downs the world. */
 export declare function serveWorld(name: string, opts?: {
@@ -143,6 +144,9 @@ export type DoorHost = {
     /** This World's branches, where the host can make them (a branch is another World, so making one
      *  is the host's act); absent, the branches doors answer 404. */
     branches?: BranchDoors;
+    /** Serve another of the World's own named branches in this one's place (`volter world view` does; a host that
+     *  serves one branch leaves it absent): this branch's twins stop, that one's start, under the same served name. */
+    serveBranch?: (branch: string) => Promise<void>;
 };
 /** A branch as its parent lists it. */
 export type BranchRow = {

package/dist/src/served-world.js

@@ -143,6 +143,7 @@ export async function mountWorld(name, opts = {}) {
         ...(opts.branches?.(served) ? { branches: opts.branches(served) } : {}),
         ...(opts.browserOrigin ? { browserOrigin: () => opts.browserOrigin(served), originOf: (other) => opts.browserOrigin(other) } : {}),
         ...(opts.localTrust ? { localTrust: () => true } : {}),
+        ...(opts.serveBranch ? { serveBranch: opts.serveBranch } : {}),
         ...(opts.passIssuers?.length ? { passIssuers: () => opts.passIssuers } : {}),
         // a local twin is its own process: the wire forwards to the port it listens on
         twinFetch: (vendor) => {
@@ -1439,6 +1440,28 @@ export class WorldDoors {
             catch { /* a World with no local branches */ }
             return Response.json({ world: this.served, branches: await branches.list(), checkedOut: this.name, named });
         }
+        // SERVE ANOTHER NAMED BRANCH here (`POST branches/<branch>/serve`): only who may write the World switches what it serves
+        if (rest.length === 2 && rest[1] === 'serve' && request.method === 'POST') {
+            if (!this.host.serveBranch)
+                return Response.json({ error: `this host serves ${this.served} on one branch` }, { status: 404 });
+            if (this.credential(request).scope !== 'write')
+                return Response.json({ error: 'serving another branch needs the World\'s write access' }, { status: 403 });
+            const target = decodeURIComponent(rest[0]);
+            let known = false;
+            try {
+                known = listWorlds(this.worldRoot).some((w) => w.name === target);
+            }
+            catch { /* no local branches */ }
+            if (!known)
+                return Response.json({ error: `no branch ${target} in this World` }, { status: 404 });
+            try {
+                await this.host.serveBranch(target);
+            }
+            catch (error) {
+                return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 409 });
+            }
+            return Response.json({ world: this.served, checkedOut: target });
+        }
         if (rest.length === 0 && request.method === 'POST') {
             const body = (await request.json().catch(() => null));
             const instant = body?.at?.instant;

package/dist/src/world-view.js

@@ -2,7 +2,7 @@
 // ("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 { existsSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { loadWorldConfig } from "./configs.js";
 import { join, resolve } from 'node:path';
 import { serveHttp, stateDirName } from '@volter/world-core';
@@ -42,7 +42,46 @@ export async function serveWorldView(name, opts = {}) {
     const browserOrigin = origins ? (served) => (port ? localWorldOrigin(served, port) : null) : undefined;
     const mountAt = (at) => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}) });
     const branches = 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 } : {}) });
+    // THE WORLD'S OWN BRANCHES, one served at a time: serving another stops this one's twins and starts that one's under the
+    // same served name (its tokens and sessions are the World's, so the page stays open); `.volter/current` follows, as
+    // \`volter world checkout\` sets it. While it switches, the World's doors answer 503.
+    let url = '';
+    let switching = false;
+    const serveBranch = async (branch) => {
+        if (switching)
+            throw new Error('already switching branches');
+        if (branch === world.name)
+            return;
+        switching = true;
+        const from = world.name;
+        try {
+            await world.stop();
+            let next;
+            try {
+                next = await mountWorld(branch, mountOpts);
+                await next.boot(url);
+            }
+            catch (error) {
+                const back = await mountWorld(from, mountOpts);
+                await back.boot(url);
+                worlds.set(back.served, back);
+                world = back;
+                throw error;
+            }
+            worlds.set(next.served, next);
+            world = next;
+            const current = join(root, stateDirName(), 'current');
+            if (branch === loadWorldConfig(join(root, stateDirName(), 'world.json'), root).config.id)
+                rmSync(current, { force: true });
+            else
+                writeFileSync(current, `${branch}\n`);
+        }
+        finally {
+            switching = false;
+        }
+    };
+    const mountOpts = { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}), serveBranch };
+    let world = await mountWorld(name, mountOpts);
     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
@@ -73,6 +112,8 @@ export async function serveWorldView(name, opts = {}) {
                     return answered;
             }
             const m = /^\/(?:-\/)?([^/]+)\/([^/]+)/.exec(path);
+            if (switching && m && `${m[1]}/${m[2]}` === world.served)
+                return Response.json({ error: `${world.served} is switching branches` }, { status: 503, headers: { 'retry-after': '2' } });
             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 });
@@ -80,7 +121,7 @@ export async function serveWorldView(name, opts = {}) {
         },
     });
     port = server.port ?? 0;
-    const url = `http://${host}:${server.port}`;
+    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 () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "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,7 +68,7 @@
   },
   "peerDependencies": {
     "@volter/world-core": "2.0.8",
-    "@volter/world-console": "2.0.7"
+    "@volter/world-console": "2.0.8"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",

package/src/redirect-proxy.ts

@@ -373,7 +373,11 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
         if (twin.vendor === 'app') {
           headers.delete('x-twins-key');
           for (const [k, v] of Object.entries(loadInject().appForwardHeaders(new URL(`https://${req.headers.get('host') ?? vendorHost}`)))) headers.set(k, v);
-        } else if (env.VOLTER_TWINS_KEY) headers.set('x-twins-key', env.VOLTER_TWINS_KEY);
+        } else {
+          if (env.VOLTER_TWINS_KEY) headers.set('x-twins-key', env.VOLTER_TWINS_KEY);
+          // the caller reached the vendor's host over TLS, which ends here: the twin renders its own links with https
+          headers.set('x-forwarded-proto', 'https');
+        }
         // Hosted namespaces need their transport Host; direct twins can use
         // the original Host for vendor semantics (for example S3 buckets).
         if (origin.pathname.replace(/\/$/, '') && twin.vendor !== 'app') {

package/src/served-world.ts

@@ -116,7 +116,7 @@ export type MountedWorld = { name: string; served: string; root: string; readonl
 /** 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; 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 };
 
-export async function mountWorld(name: string, opts: { /** the platforms whose passes open this World */ passIssuers?: TrustedIssuer[]; root?: string; /** the host's branches of this World, by its served name */ branches?: (served: string) => BranchDoors | undefined; /** the origin a browser reaches this World at, when the host gives each World one */ browserOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */ localTrust?: boolean } = {}): Promise<MountedWorld> {
+export async function mountWorld(name: string, opts: { /** the platforms whose passes open this World */ passIssuers?: TrustedIssuer[]; root?: string; /** the host's branches of this World, by its served name */ branches?: (served: string) => BranchDoors | undefined; /** the origin a browser reaches this World at, when the host gives each World one */ browserOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */ localTrust?: boolean; /** DoorHost.serveBranch */ serveBranch?: (branch: string) => Promise<void> } = {}): Promise<MountedWorld> {
   const worldRoot = resolve(opts.root ?? process.cwd());
   const configRef = configRefFor(worldRoot, name);
   if (loadWorldConfig(configRef, worldRoot).config.resources) {
@@ -149,6 +149,7 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
     ...(opts.branches?.(served) ? { branches: opts.branches(served)! } : {}),
     ...(opts.browserOrigin ? { browserOrigin: () => opts.browserOrigin!(served), originOf: (other: string) => opts.browserOrigin!(other) } : {}),
     ...(opts.localTrust ? { localTrust: () => true } : {}),
+    ...(opts.serveBranch ? { serveBranch: opts.serveBranch } : {}),
     ...(opts.passIssuers?.length ? { passIssuers: () => opts.passIssuers! } : {}),
     // a local twin is its own process: the wire forwards to the port it listens on
     twinFetch: (vendor) => {
@@ -304,6 +305,9 @@ export type DoorHost = {
   /** This World's branches, where the host can make them (a branch is another World, so making one
    *  is the host's act); absent, the branches doors answer 404. */
   branches?: BranchDoors;
+  /** Serve another of the World's own named branches in this one's place (`volter world view` does; a host that
+   *  serves one branch leaves it absent): this branch's twins stop, that one's start, under the same served name. */
+  serveBranch?: (branch: string) => Promise<void>;
 };
 
 /** A branch as its parent lists it. */
@@ -1232,6 +1236,17 @@ export class WorldDoors {
       try { named = listWorlds(this.worldRoot).map((w) => ({ name: w.name, running: w.running })); } catch { /* a World with no local branches */ }
       return Response.json({ world: this.served, branches: await branches.list(), checkedOut: this.name, named });
     }
+    // SERVE ANOTHER NAMED BRANCH here (`POST branches/<branch>/serve`): only who may write the World switches what it serves
+    if (rest.length === 2 && rest[1] === 'serve' && request.method === 'POST') {
+      if (!this.host.serveBranch) return Response.json({ error: `this host serves ${this.served} on one branch` }, { status: 404 });
+      if (this.credential(request).scope !== 'write') return Response.json({ error: 'serving another branch needs the World\'s write access' }, { status: 403 });
+      const target = decodeURIComponent(rest[0]!);
+      let known = false;
+      try { known = listWorlds(this.worldRoot).some((w) => w.name === target); } catch { /* no local branches */ }
+      if (!known) return Response.json({ error: `no branch ${target} in this World` }, { status: 404 });
+      try { await this.host.serveBranch(target); } catch (error) { return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 409 }); }
+      return Response.json({ world: this.served, checkedOut: target });
+    }
     if (rest.length === 0 && request.method === 'POST') {
       const body = (await request.json().catch(() => null)) as { at?: { instant?: unknown }; ttl?: unknown; live?: unknown; label?: unknown } | null;
       const instant = body?.at?.instant;

package/src/world-view.ts

@@ -2,7 +2,7 @@
 // ("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 { existsSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { loadWorldConfig } from './configs.ts';
 import { join, resolve } from 'node:path';
 import { serveHttp, stateDirName } from '@volter/world-core';
@@ -44,7 +44,35 @@ export async function serveWorldView(name: string, opts: { root?: string; port?:
   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 } : {}) });
+  // THE WORLD'S OWN BRANCHES, one served at a time: serving another stops this one's twins and starts that one's under the
+  // same served name (its tokens and sessions are the World's, so the page stays open); `.volter/current` follows, as
+  // \`volter world checkout\` sets it. While it switches, the World's doors answer 503.
+  let url = '';
+  let switching = false;
+  const serveBranch = async (branch: string): Promise<void> => {
+    if (switching) throw new Error('already switching branches');
+    if (branch === world.name) return;
+    switching = true;
+    const from = world.name;
+    try {
+      await world.stop();
+      let next: MountedWorld;
+      try {
+        next = await mountWorld(branch, mountOpts);
+        await next.boot(url);
+      } catch (error) {
+        const back = await mountWorld(from, mountOpts);
+        await back.boot(url);
+        worlds.set(back.served, back); world = back;
+        throw error;
+      }
+      worlds.set(next.served, next); world = next;
+      const current = join(root, stateDirName(), 'current');
+      if (branch === loadWorldConfig(join(root, stateDirName(), 'world.json'), root).config.id) rmSync(current, { force: true }); else writeFileSync(current, `${branch}\n`);
+    } finally { switching = false; }
+  };
+  const mountOpts = { root, branches: (served: string) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}), serveBranch };
+  let world = await mountWorld(name, mountOpts);
   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
@@ -69,13 +97,14 @@ export async function serveWorldView(name: string, opts: { root?: string; port?:
         if (answered) return answered;
       }
       const m = /^\/(?:-\/)?([^/]+)\/([^/]+)/.exec(path);
+      if (switching && m && `${m[1]}/${m[2]}` === world.served) return Response.json({ error: `${world.served} is switching branches` }, { status: 503, headers: { 'retry-after': '2' } });
       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}`;
+  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> => {