@volter/world-runtime 2.0.14 → 2.0.16

package/dist/src/branch.js

@@ -55,22 +55,26 @@ export async function branchWorld(base, name, options = {}) {
     catch {
         return false;
     } })();
+    const began = Date.now();
     let instance;
     try {
         instance = await upWorld(existsSync(from.configPath) ? from.configPath : from.config, { name, root, mode: from.mode, envFile });
     }
     catch (error) {
-        let recorded = false;
+        // only a record made during this call is ours to remove, and it is removed by its own createdAt, as the fork's
+        // cleanup below does: a concurrent `branch` of the same name that recorded first keeps its World
+        let recorded = null;
         if (!existed) {
             try {
-                statusWorld(name, root);
-                recorded = true;
+                const made = statusWorld(name, root).createdAt;
+                if (Date.parse(made) >= began)
+                    recorded = made;
             }
             catch { /* the boot recorded nothing */ }
         }
         if (recorded) {
             try {
-                await downWorld(name, root, { purge: true });
+                await downWorld(name, root, { purge: true, expectedCreatedAt: recorded });
             }
             catch (cleanup) {
                 throw new Error(`${error instanceof Error ? error.message : String(error)} (and the half-made branch ${name} could not be removed: ${cleanup instanceof Error ? cleanup.message : String(cleanup)})`);

package/dist/src/served-world.js

@@ -156,7 +156,8 @@ export async function mountWorld(name, opts = {}) {
     const world = new WorldDoors(name, worldRoot, configRef, served, host, held('token') ?? mintToken('tok_'), held('token.read') ?? mintToken('tok_r_'));
     const keep = () => { writeSecret(join(worldRoot, stateDirName(), 'token'), world.token); writeSecret(join(worldRoot, stateDirName(), 'token.read'), world.readToken); };
     let timers = [];
-    return {
+    let stopping = null;
+    const mounted = {
         name, served, root: worldRoot,
         get token() { return world.token; }, get readToken() { return world.readToken; },
         twins: () => world.twins(),
@@ -166,24 +167,67 @@ export async function mountWorld(name, opts = {}) {
             keep();
             const port = Number(new URL(url).port) || 0;
             writeFileSync(record, `${JSON.stringify({ name: served, url, base: `${url}/${served}`, port, pid: process.pid, startedAt: new Date().toISOString() }, null, 2)}\n`);
-            const booted = await upWorld(configRef, { name, root: worldRoot, keepState: true });
-            instance = booted;
-            // a root set in the config while the world was stopped reaches the twins' state now, where the deploy reads it
-            materializeRoots(loadWorldConfig(configRef, worldRoot).config, booted.dirs.data, worldRoot);
-            timers = await scheduleRefreshes(name, worldRoot, booted);
-        },
-        async stop() {
-            for (const t of timers)
-                clearInterval(t);
+            // a boot that fails leaves nothing claimed: no serve record naming this process (a later mount of this World would
+            // refuse as "already served"), and no twins it started; twins another owner runs were never ours to stop
+            let booted = null;
             try {
-                rmSync(record, { force: true });
+                booted = await upWorld(configRef, { name, root: worldRoot, keepState: true });
+                instance = booted;
+                // a root set in the config while the world was stopped reaches the twins' state now, where the deploy reads it
+                materializeRoots(loadWorldConfig(configRef, worldRoot).config, booted.dirs.data, worldRoot);
+                timers = await scheduleRefreshes(name, worldRoot, booted);
             }
-            catch { /* already gone */ }
-            const result = await downWorld(name, worldRoot);
-            if (result.externalErrors.length)
-                throw new Error(`World "${name}" shutdown incomplete; instance and reservation retained: ${result.externalErrors.join('; ')}`);
+            catch (error) {
+                for (const t of timers)
+                    clearInterval(t);
+                timers = [];
+                if (booted) {
+                    try {
+                        await downWorld(name, worldRoot);
+                    }
+                    catch { /* the boot's own error is the one reported */ }
+                }
+                try {
+                    rmSync(record, { force: true });
+                }
+                catch { /* already gone */ }
+                throw error;
+            }
+        },
+        stop() {
+            // one stop at a time: a second caller (the view shutting down while a switch stops this World) shares the first's
+            stopping ??= stopOnce().finally(() => { stopping = null; });
+            return stopping;
         },
     };
+    async function stopOnce() {
+        // refreshes stop first, so none writes into the World while its twins stop; the serve record goes only once they are
+        // down. A stop that fails keeps the record (a checkout under the serve still refuses) and re-arms the refreshes:
+        // refused before anything stopped, the World is served as it was; failed part way, its record names what remains
+        for (const t of timers)
+            clearInterval(t);
+        timers = [];
+        let result;
+        try {
+            result = await downWorld(name, worldRoot);
+            if (result.externalErrors.length)
+                throw new Error(`World "${name}" shutdown incomplete; instance and reservation retained: ${result.externalErrors.join('; ')}`);
+        }
+        catch (error) {
+            if (instance) {
+                try {
+                    timers = await scheduleRefreshes(name, worldRoot, instance);
+                }
+                catch { /* the stop's error is the one reported */ }
+            }
+            throw error;
+        }
+        try {
+            rmSync(record, { force: true });
+        }
+        catch { /* already gone */ }
+    }
+    return mounted;
 }
 /** A local World's mirrors: each pack's builders, found once per process, and each client built once. */
 const localMirrors = new Map();
@@ -1438,7 +1482,7 @@ export class WorldDoors {
                 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 });
+            return Response.json({ world: this.served, branches: await branches.list(), checkedOut: this.name, named, canServe: this.host.serveBranch !== undefined });
         }
         // 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') {

package/dist/src/world-view.js

@@ -55,6 +55,7 @@ export async function serveWorldView(name, opts = {}) {
         switching = true;
         const from = world.name;
         try {
+            // a stop that is refused or fails leaves this branch served as it was (served-world.ts stop): the switch just fails
             await world.stop();
             let next;
             try {
@@ -62,6 +63,7 @@ export async function serveWorldView(name, opts = {}) {
                 await next.boot(url);
             }
             catch (error) {
+                // the target's failed boot released its claim (served-world.ts boot), so the branch it replaced mounts again
                 const back = await mountWorld(from, mountOpts);
                 await back.boot(url);
                 worlds.set(back.served, back);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.14",
+  "version": "2.0.16",
   "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",
@@ -67,14 +67,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.8",
-    "@volter/world-console": "2.0.8"
+    "@volter/world-core": "2.0.10",
+    "@volter/world-console": "2.0.9"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "2.0.1",
-    "@volter/world-core": "2.0.8",
+    "@volter/world-core": "2.0.10",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -84,6 +84,6 @@
     }
   },
   "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.8"
+    "@volter/twin-mongodb": "0.1.10"
   }
 }

package/src/branch.ts

@@ -51,14 +51,17 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
   // a branch that fails to boot (a twin whose mounted version breaks the config's pin) leaves no half-made branch behind:
   // its record without a fork would check out later as an empty World
   const existed = (() => { try { statusWorld(name, root); return true; } catch { return false; } })();
+  const began = Date.now();
   let instance: WorldInstance;
   try {
     instance = await upWorld(existsSync(from.configPath) ? from.configPath : from.config, { name, root, mode: from.mode, envFile });
   } catch (error) {
-    let recorded = false;
-    if (!existed) { try { statusWorld(name, root); recorded = true; } catch { /* the boot recorded nothing */ } }
+    // only a record made during this call is ours to remove, and it is removed by its own createdAt, as the fork's
+    // cleanup below does: a concurrent `branch` of the same name that recorded first keeps its World
+    let recorded: string | null = null;
+    if (!existed) { try { const made = statusWorld(name, root).createdAt; if (Date.parse(made) >= began) recorded = made; } catch { /* the boot recorded nothing */ } }
     if (recorded) {
-      try { await downWorld(name, root, { purge: true }); } catch (cleanup) {
+      try { await downWorld(name, root, { purge: true, expectedCreatedAt: recorded }); } catch (cleanup) {
         throw new Error(`${error instanceof Error ? error.message : String(error)} (and the half-made branch ${name} could not be removed: ${cleanup instanceof Error ? cleanup.message : String(cleanup)})`);
       }
     }

package/src/served-world.ts

@@ -161,7 +161,8 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
   const world = new WorldDoors(name, worldRoot, configRef, served, host, held('token') ?? mintToken('tok_'), held('token.read') ?? mintToken('tok_r_'));
   const keep = (): void => { writeSecret(join(worldRoot, stateDirName(), 'token'), world.token); writeSecret(join(worldRoot, stateDirName(), 'token.read'), world.readToken); };
   let timers: ReturnType<typeof setInterval>[] = [];
-  return {
+  let stopping: Promise<void> | null = null;
+  const mounted: MountedWorld = {
     name, served, root: worldRoot,
     get token() { return world.token; }, get readToken() { return world.readToken; },
     twins: () => world.twins(),
@@ -171,19 +172,46 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
       keep();
       const port = Number(new URL(url).port) || 0;
       writeFileSync(record, `${JSON.stringify({ name: served, url, base: `${url}/${served}`, port, pid: process.pid, startedAt: new Date().toISOString() }, null, 2)}\n`);
-      const booted = await upWorld(configRef, { name, root: worldRoot, keepState: true });
-      instance = booted;
-      // a root set in the config while the world was stopped reaches the twins' state now, where the deploy reads it
-      materializeRoots(loadWorldConfig(configRef, worldRoot).config, booted.dirs.data, worldRoot);
-      timers = await scheduleRefreshes(name, worldRoot, booted);
+      // a boot that fails leaves nothing claimed: no serve record naming this process (a later mount of this World would
+      // refuse as "already served"), and no twins it started; twins another owner runs were never ours to stop
+      let booted: WorldInstance | null = null;
+      try {
+        booted = await upWorld(configRef, { name, root: worldRoot, keepState: true });
+        instance = booted;
+        // a root set in the config while the world was stopped reaches the twins' state now, where the deploy reads it
+        materializeRoots(loadWorldConfig(configRef, worldRoot).config, booted.dirs.data, worldRoot);
+        timers = await scheduleRefreshes(name, worldRoot, booted);
+      } catch (error) {
+        for (const t of timers) clearInterval(t);
+        timers = [];
+        if (booted) { try { await downWorld(name, worldRoot); } catch { /* the boot's own error is the one reported */ } }
+        try { rmSync(record, { force: true }); } catch { /* already gone */ }
+        throw error;
+      }
     },
-    async stop() {
-      for (const t of timers) clearInterval(t);
-      try { rmSync(record, { force: true }); } catch { /* already gone */ }
-      const result = await downWorld(name, worldRoot);
-      if (result.externalErrors.length) throw new Error(`World "${name}" shutdown incomplete; instance and reservation retained: ${result.externalErrors.join('; ')}`);
+    stop() {
+      // one stop at a time: a second caller (the view shutting down while a switch stops this World) shares the first's
+      stopping ??= stopOnce().finally(() => { stopping = null; });
+      return stopping;
     },
   };
+  async function stopOnce(): Promise<void> {
+      // refreshes stop first, so none writes into the World while its twins stop; the serve record goes only once they are
+      // down. A stop that fails keeps the record (a checkout under the serve still refuses) and re-arms the refreshes:
+      // refused before anything stopped, the World is served as it was; failed part way, its record names what remains
+      for (const t of timers) clearInterval(t);
+      timers = [];
+      let result: Awaited<ReturnType<typeof downWorld>>;
+      try {
+        result = await downWorld(name, worldRoot);
+        if (result.externalErrors.length) throw new Error(`World "${name}" shutdown incomplete; instance and reservation retained: ${result.externalErrors.join('; ')}`);
+      } catch (error) {
+        if (instance) { try { timers = await scheduleRefreshes(name, worldRoot, instance); } catch { /* the stop's error is the one reported */ } }
+        throw error;
+      }
+      try { rmSync(record, { force: true }); } catch { /* already gone */ }
+  }
+  return mounted;
 }
 
 /** A local World's mirrors: each pack's builders, found once per process, and each client built once. */
@@ -1234,7 +1262,7 @@ export class WorldDoors {
       // `checkedOut` is the one this serve holds, so a page never names the World for the branch it shows
       let named: Array<{ name: string; running: boolean }> = [];
       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 });
+      return Response.json({ world: this.served, branches: await branches.list(), checkedOut: this.name, named, canServe: this.host.serveBranch !== undefined });
     }
     // 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') {

package/src/world-view.ts

@@ -55,12 +55,14 @@ export async function serveWorldView(name: string, opts: { root?: string; port?:
     switching = true;
     const from = world.name;
     try {
+      // a stop that is refused or fails leaves this branch served as it was (served-world.ts stop): the switch just fails
       await world.stop();
       let next: MountedWorld;
       try {
         next = await mountWorld(branch, mountOpts);
         await next.boot(url);
       } catch (error) {
+        // the target's failed boot released its claim (served-world.ts boot), so the branch it replaced mounts again
         const back = await mountWorld(from, mountOpts);
         await back.boot(url);
         worlds.set(back.served, back); world = back;