@volter/world-runtime 2.0.0 → 2.0.1

package/src/init.ts

@@ -47,7 +47,7 @@ import {
   registryAcknowledgedReason,
   type CoverageReport,
 } from './covers.ts';
-import { fakeEnvValue, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from './fixture-env.ts';
+import { fakeEnvValue, isAppKeyName, isGoogleOAuthClientEnvName, isGoogleServiceAccountEnvName } from './fixture-env.ts';
 import { resolveCatalog, twinPackageName, type Catalog } from './catalog.ts';
 import { projectEnvReads, projectManifestDirs } from './project-inspect.ts';
 import { overlayEndpointEnv, packFacts } from './pack-facts.ts';
@@ -300,6 +300,20 @@ export const APP_READ_ENDPOINT_ENV: Record<string, { injectEnv?: string; injectE
       + 'sends there. Read the mail back over the twin-only inspect sidecar: `world-smtp serve --inspect-port N`, then '
       + 'GET http://127.0.0.1:N/twin/messages/latest.',
   },
+  // RAW PROTOCOL, the gRPC kind. The Temporal SDKs dial the frontend address they are given
+  // (`Connection.connect({ address })`, `NativeConnection.connect({ address })`), conventionally read
+  // from TEMPORAL_ADDRESS — Postiz's temporal.module.ts, the SDK samples and the Temporal CLI all read
+  // that name — and speak gRPC over HTTP/2, which the http/fetch injector never sees. The value is an
+  // address (host:port), not a URL, which is why this lives here as a template and not as the
+  // descriptor's `endpointEnv` (whose `name` receives the twin's URL).
+  temporal: {
+    injectEnvTemplates: {
+      TEMPORAL_ADDRESS: '${host}:${port}',
+    },
+    note: 'no injector entry and none possible: the Temporal SDKs speak gRPC to the address they are configured with. '
+      + 'TEMPORAL_ADDRESS=<host>:<port> points them at the twin (namespace `default` exists); an app that sets '
+      + 'TEMPORAL_API_KEY turns TLS on in the SDK, which this loopback frontend does not speak — leave it unset.',
+  },
 };
 // descriptor-first migration (adding-a-twin.md §3): packs now declare their endpoint-env wiring (with its grounding
 // note) on the descriptor (`endpointEnv` on TwinPack); the table above shrinks toward empty as
@@ -442,7 +456,7 @@ const INFRA_PLACEHOLDER: Record<string, string> = {
 //
 // The subject pilots (dub, cal.com) put the number on it: world-side setup is seconds, and the
 // minutes go to the app side — most avoidably, to hand-writing infrastructure for the Postgres/
-// MySQL/Redis the repo signalled. For the kinds below, `init` upgrades the placeholder to a
+// MySQL/Redis/MongoDB the repo signalled. For the kinds below, `init` upgrades the placeholder to a
 // World-managed service and private definition with env URLs already pointing at it. The helper
 // owns its implementation behind the declared service boundary. Kinds without a recipe keep the
 // placeholder + `//infra` stub.
@@ -479,6 +493,15 @@ const COMPOSE_INFRA: Record<string, {
     volumePath: '/data',
     healthcheck: () => ['CMD', 'redis-cli', 'ping'],
   },
+  // Without a container runtime the containerless backing serves this kind with the MongoDB twin
+  // (@volter/twin-mongodb), at the same loopback port and URL.
+  mongodb: {
+    image: 'mongo:7',
+    containerPort: 27017,
+    memoryMiB: 1024,
+    volumePath: '/data/db',
+    healthcheck: () => ['CMD', 'mongosh', '--quiet', '--eval', "db.adminCommand('ping').ok"],
+  },
 };
 
 /** FNV-1a 32-bit — a tiny, dependency-free stable string hash for port derivation. */
@@ -525,9 +548,12 @@ function composeService(name: string, kind: string, signals: string[], taken: Se
   const recipe = COMPOSE_INFRA[kind]!;
   const hostPort = composePort(name, kind, taken);
   const ident = composeIdent(name);
+  // redis and mongodb run without authentication (no credentials in their images' env), so their URLs carry none
   const url = kind === 'redis'
     ? `redis://127.0.0.1:${hostPort}`
-    : `${kind}://${composeUser(name, kind)}:${ident}@127.0.0.1:${hostPort}/${ident}`;
+    : kind === 'mongodb'
+      ? `mongodb://127.0.0.1:${hostPort}/${ident}`
+      : `${kind}://${composeUser(name, kind)}:${ident}@127.0.0.1:${hostPort}/${ident}`;
   return {
     kind,
     image: recipe.image,
@@ -540,7 +566,7 @@ function composeService(name: string, kind: string, signals: string[], taken: Se
   };
 }
 
-/** The declared env of one compose service (empty for redis). */
+/** The declared env of one compose service (empty for redis and mongodb). */
 function composeEnvironment(name: string, kind: string): Array<[string, string]> {
   const ident = composeIdent(name);
   if (kind === 'postgres') {
@@ -858,7 +884,7 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
     // RULE 3: credential-shaped means faked, even when no vendor claims the stem. That covers
     // app-local secrets (JWT_SECRET, ENCRYPTION_KEY) and untwinned vendors alike — and it is the
     // reason a live key committed to `.env.example` can never reach the emitted world.
-    if (isCredentialShapedEnvName(name)) {
+    if (isCredentialShapedEnvName(name) || isAppKeyName(name)) {
       env[name] = fakeEnvValue(name);
       envRows.push({ name, disposition: 'faked', source, reason: 'credential-shaped name — the example value is never copied' });
       continue;

package/src/pglite-backing.ts

@@ -1,18 +1,23 @@
-// The containerless backing for World-managed infrastructure: PGlite hosts
-// (see pglite-host.ts) instead of docker compose. Selected by
-// `volter-world-infra` when no container runtime is available (or by
-// explicit VOLTER_WORLD_INFRA_BACKING=pglite); the world config, definition
-// file, injected env, and declared-service contract are byte-identical either
-// way — backing is private, exactly as the boundary comment in
-// infra-cli.ts promises.
+// The containerless backing for World-managed infrastructure, instead of docker
+// compose: a POSTGRES service is a PGlite host (see pglite-host.mjs), a MONGODB
+// service is the MongoDB twin (@volter/twin-mongodb: the MongoDB wire protocol over
+// the World state kernel). Selected by `volter-world-infra` when no container
+// runtime is available (or by explicit VOLTER_WORLD_INFRA_BACKING=pglite); the
+// world config, definition file, injected env, and declared-service contract are
+// byte-identical either way — backing is private, exactly as the boundary comment
+// in infra-cli.ts promises. Each service's bytes live under VOLTER_WORLD_DATA, so
+// they survive down/up as the compose volumes do.
 //
-// Capability is stated, not stretched: this backing serves POSTGRES services
-// only. A definition declaring mysql/redis without a container runtime is
-// refused with the kinds named, never half-booted.
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+// Capability is stated, not stretched: this backing serves POSTGRES and MONGODB
+// services only. A definition declaring mysql without a container runtime is
+// refused with the kinds named, never half-booted. Redis never reaches it: every
+// redis service is the redis twin's (redis-backing.ts).
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { connect } from 'node:net';
 import { dirname, join } from 'node:path';
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { findInstalledPackage, packCli } from './catalog.ts';
 
 export interface InfraService { kind: string; hostPort: number }
 
@@ -55,11 +60,48 @@ export function infraConnections(services: InfraService[], env: Record<string, s
   return connections;
 }
 
-const HOST = join(import.meta.dir, 'pglite-host.mjs');
+// this module's directory under Node as under Bun: `volter-world-infra` is a node-shebang bin, where
+// `import.meta.dir` (Bun's) is undefined
+const HERE = fileURLToPath(new URL('.', import.meta.url));
+const HOST = join(HERE, 'pglite-host.mjs');
 const READY_TIMEOUT_MS = 60_000;
+const MONGODB_TWIN = '@volter/twin-mongodb';
+
+/** The kinds this backing serves, and the name its files carry under the data dir. */
+const CONTAINERLESS: Record<string, string> = { postgres: 'pglite-postgres', mongodb: 'twin-mongodb' };
 
 function pidPath(dataDir: string, kind: string): string {
-  return join(dataDir, `pglite-${kind}.pid`);
+  return join(dataDir, `${CONTAINERLESS[kind] ?? `pglite-${kind}`}.pid`);
+}
+
+/** The MongoDB twin's cli: the package installed above the World's config (an app repo), else the one
+ *  this runtime was installed with (its dependency, or the checkout's workspace link). */
+export function mongodbTwinCli(worldConfig?: string, froms: string[] = [...(worldConfig ? [dirname(worldConfig)] : []), HERE]): string {
+  for (const from of froms) {
+    const dir = findInstalledPackage(from, MONGODB_TWIN);
+    const cli = dir === undefined ? undefined : packCli(dir);
+    if (cli !== undefined) return cli;
+  }
+  throw new Error(`the containerless mongodb service is served by ${MONGODB_TWIN} (an optional dependency of @volter/world-runtime), which is not installed above ${froms.join(' or ')} — install it, or run the World with a container runtime`);
+}
+
+/** The runtime a twin's cli runs under. A published package's cli is JavaScript and runs under this
+ *  process's own runtime; a checkout's is TypeScript whose kernel needs more than Node's type
+ *  stripping, so it runs under Bun (this process's, or the one on PATH) — the repository's toolchain —
+ *  and without Bun it is refused by name rather than started to fail. */
+export function twinRunner(cli: string, bunOnPath: () => boolean = () => spawnSync('bun', ['--version'], { stdio: 'ignore', timeout: 10_000 }).status === 0, underBun = typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined'): string {
+  if (!cli.endsWith('.ts') || underBun) return process.execPath;
+  if (bunOnPath()) return 'bun';
+  throw new Error(`a checkout's MongoDB twin runs under bun, which is not on PATH (${cli} is TypeScript that Node cannot run)`);
+}
+
+/** The argv that serves one service on its declared loopback port, with its bytes in `serviceData`. */
+function hostArgv(service: InfraService, serviceData: string): string[] {
+  if (service.kind === 'mongodb') {
+    const cli = mongodbTwinCli(process.env.VOLTER_WORLD_CONFIG);
+    return [twinRunner(cli), cli, 'serve', '--port', String(service.hostPort), '--root', serviceData];
+  }
+  return ['node', HOST, '--port', String(service.hostPort), '--data', serviceData];
 }
 
 function alive(pid: number): boolean {
@@ -81,36 +123,67 @@ const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
 /** The kinds this backing cannot serve, or [] when it can serve the world. */
 export function unsupportedKinds(services: InfraService[]): string[] {
-  return [...new Set(services.filter((s) => s.kind !== 'postgres').map((s) => s.kind))];
+  return [...new Set(services.filter((s) => CONTAINERLESS[s.kind] === undefined).map((s) => s.kind))];
+}
+
+/** The line each host prints once ITS OWN listener is bound: readiness is taken from the child, never
+ *  from a connect to the port, which any other process holding the port would answer. */
+function readyLine(kind: string, port: number): string {
+  return kind === 'mongodb' ? `listening on mongodb://127.0.0.1:${port}` : `serving postgres wire protocol on 127.0.0.1:${port}`;
+}
+
+function logSince(log: string, offset: number): string {
+  try { return readFileSync(log).subarray(offset).toString('utf8'); } catch { return ''; }
 }
 
 export async function pgliteUp(services: InfraService[], dataDir: string): Promise<void> {
+  // Every check before any start: a refused up starts nothing, so it never leaves the World half-booted.
+  const plan: Array<{ service: InfraService; name: string; serviceData: string; log: string; pidFile: string; argv: string[] }> = [];
   for (const service of services) {
     const pidFile = pidPath(dataDir, service.kind);
     if (existsSync(pidFile) && alive(Number(readFileSync(pidFile, 'utf8').trim()))) continue;
-    const serviceData = join(dataDir, `pglite-${service.kind}-data`);
-    mkdirSync(serviceData, { recursive: true });
-    const log = join(dataDir, `pglite-${service.kind}.log`);
-    mkdirSync(dirname(log), { recursive: true });
-    // a real fd, not a pipe: the host must outlive this process untethered
-    const logFd = openSync(log, 'a');
-    const child = spawn('node', [HOST, '--port', String(service.hostPort), '--data', serviceData], {
-      detached: true,
-      stdio: ['ignore', logFd, logFd],
-    });
-    child.unref();
-    closeSync(logFd);
-    writeFileSync(pidFile, `${child.pid}\n`);
-    const deadline = Date.now() + READY_TIMEOUT_MS;
-    while (!(await listening(service.hostPort))) {
-      if (!alive(child.pid!)) {
-        throw new Error(`pglite ${service.kind} exited before serving — see ${log}`);
-      }
-      if (Date.now() > deadline) {
-        throw new Error(`pglite ${service.kind} did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
+    const name = CONTAINERLESS[service.kind] ?? `pglite-${service.kind}`;
+    const serviceData = join(dataDir, `${name}-data`);
+    const log = join(dataDir, `${name}.log`);
+    if (await listening(service.hostPort)) {
+      throw new Error(`${name} cannot serve port ${service.hostPort}: another process is already listening on it`);
+    }
+    plan.push({ service, name, serviceData, log, pidFile, argv: hostArgv(service, serviceData) });
+  }
+  const started: Array<{ pid: number; pidFile: string }> = [];
+  try {
+    for (const { service, name, serviceData, log, pidFile, argv } of plan) {
+      mkdirSync(serviceData, { recursive: true });
+      mkdirSync(dirname(log), { recursive: true });
+      const offset = existsSync(log) ? statSync(log).size : 0;
+      const [command, ...args] = argv;
+      // a real fd, not a pipe: the host must outlive this process untethered
+      const logFd = openSync(log, 'a');
+      const child = spawn(command!, args, {
+        detached: true,
+        stdio: ['ignore', logFd, logFd],
+      });
+      child.unref();
+      closeSync(logFd);
+      writeFileSync(pidFile, `${child.pid}\n`);
+      started.push({ pid: child.pid!, pidFile });
+      const deadline = Date.now() + READY_TIMEOUT_MS;
+      const line = readyLine(service.kind, service.hostPort);
+      // ready when OUR child says its listener is bound (a squatter that took the port after the check
+      // above makes the child fail its bind and exit, never print this) and the port answers
+      while (!(alive(child.pid!) && logSince(log, offset).includes(line) && await listening(service.hostPort))) {
+        if (!alive(child.pid!)) throw new Error(`${name} exited before serving — see ${log}`);
+        if (Date.now() > deadline) throw new Error(`${name} did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
+        await sleep(200);
       }
-      await sleep(200);
     }
+  } catch (error) {
+    // tear down what this up started, so a failed up leaves nothing running
+    for (const { pid, pidFile } of started) {
+      if (alive(pid)) { try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ } }
+      rmSync(pidFile, { force: true });
+    }
+    throw error;
   }
 }