@volter/world-runtime 3.0.46 → 3.0.48

package/dist/src/pglite-backing.d.ts

@@ -2,6 +2,11 @@ export interface InfraService {
     kind: string;
     hostPort: number;
     replicaSet?: string;
+    postgres?: {
+        user: string;
+        database: string;
+        password?: string;
+    };
 }
 /** Read the generated definition's loopback port mappings. MongoDB may explicitly request
  *  one replica-set member through its Compose-compatible command; other mongod options are refused. */

package/dist/src/pglite-backing.js

@@ -44,7 +44,20 @@ export function parseInfraDefinition(text) {
         });
         if (ports.length !== 1)
             throw new Error(`managed infrastructure ${kind} needs exactly one declared loopback port`);
-        services.push({ kind, hostPort: ports[0], ...(replicaSet ? { replicaSet } : {}) });
+        let postgres;
+        if (kind === 'postgres') {
+            const environment = declared.environment ?? {};
+            const user = environment.POSTGRES_USER ?? 'postgres';
+            const database = environment.POSTGRES_DB ?? user;
+            const password = environment.POSTGRES_PASSWORD;
+            if ([user, database, password].some(value => value !== undefined && (typeof value !== 'string' || !value || /[\r\n\0]|\$\{/.test(value)))) {
+                throw new Error('World-managed PGlite requires literal POSTGRES_USER, POSTGRES_DB and POSTGRES_PASSWORD');
+            }
+            if ([user, database].some(value => Buffer.byteLength(value, 'utf8') > 63))
+                throw new Error('World-managed PGlite identifiers must fit PostgreSQL\'s 63-byte name limit');
+            postgres = { user: user, database: database, ...(password !== undefined ? { password: password } : {}) };
+        }
+        services.push({ kind, hostPort: ports[0], ...(replicaSet ? { replicaSet } : {}), ...(postgres ? { postgres } : {}) });
     }
     return services;
 }
@@ -160,6 +173,8 @@ export async function pgliteUp(services, dataDir, launch = {}) {
         }
         const name = CONTAINERLESS[service.kind] ?? `pglite-${service.kind}`;
         const serviceData = join(dataDir, containerlessDataDirectory(service.kind) ?? `${name}-data`);
+        if (service.kind === 'postgres' && !service.postgres?.password)
+            throw new Error('World-managed PGlite requires a literal POSTGRES_PASSWORD; declare a throwaway World credential');
         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`);
@@ -177,7 +192,8 @@ export async function pgliteUp(services, dataDir, launch = {}) {
             const logFd = openSync(log, 'a');
             const child = spawn(command, args, {
                 windowsHide: true,
-                env,
+                env: service.postgres ? { ...env, VOLTER_WORLD_PGLITE_USER: service.postgres.user,
+                    VOLTER_WORLD_PGLITE_DATABASE: service.postgres.database, VOLTER_WORLD_PGLITE_PASSWORD: service.postgres.password } : env,
                 detached: true,
                 stdio: ['ignore', logFd, logFd],
             });

package/dist/src/pglite-host.mjs

@@ -33,18 +33,11 @@
 //
 // Limits, stated plainly (measured on 0.5.8 through this gateway with `pg`
 // clients; pglite-backing.test.ts holds the extension and database checks):
-// - ONE database. Trust auth accepts any user/password/database in the
-//   startup packet, so a DATABASE_URL naming `/rallly` connects — but every
-//   name lands in PGlite's single `postgres` database: current_database()
-//   and current_user answer `postgres`, and all names share one catalog.
-//   PGlite itself ACCEPTS `CREATE DATABASE` (a pg_database row appears) yet
-//   nothing can ever connect to it, so this host fails the statement loudly
-//   (see refusal() below): 42P04 "already exists" when the name is the
-//   connection's own startup database (true: it connects, so check-then-
-//   create for the app's own database proceeds), 0A000 "not supported" for
-//   any other name. An app that needs a second real database (Prisma's
-//   shadow database for `migrate dev`, Django's `test_<name>`; `migrate
-//   deploy` needs none) needs the container backing.
+// - ONE declared database and login, authenticated with the World's throwaway
+//   password. Undeclared databases fail 3D000; failed logins fail 28P01.
+//   current_database() and current_user come from the configured backend.
+//   CREATE DATABASE of the declared name fails 42P04, other names fail 0A000;
+//   multiple databases require the native or container backing.
 // - No COPY … FROM STDIN: refused with 0A000 (it aborts PGlite's backend);
 //   COPY … TO STDOUT works.
 // - ONE serialized session. Connections are accepted concurrently but run
@@ -96,6 +89,7 @@ import net from 'node:net';
 import { mkdirSync, readFileSync } from 'node:fs';
 import clockForm from '@volter/world-core/world-clock';
 import { fromNodeSocket } from 'pg-gateway/node';
+import { BackendError } from 'pg-gateway';
 
 // ---- the World's time (above) --------------------------------
 const machineNow = Date.now.bind(Date);
@@ -147,6 +141,13 @@ function arg(name) {
 
 const port = Number(arg('--port'));
 const dataDir = arg('--data');
+const databaseUser = process.env.VOLTER_WORLD_PGLITE_USER;
+const databaseName = process.env.VOLTER_WORLD_PGLITE_DATABASE;
+const databasePassword = process.env.VOLTER_WORLD_PGLITE_PASSWORD;
+if (![databaseUser, databaseName, databasePassword].every(value => typeof value === 'string' && value.length > 0)) {
+  process.stderr.write('pglite-host: declared database identity and throwaway password are required\n');
+  process.exit(2);
+}
 if (!Number.isInteger(port) || port < 1 || port > 65535) {
   process.stderr.write('pglite-host: --port must be 1-65535\n');
   process.exit(2);
@@ -159,7 +160,27 @@ process.stderr.on('error', () => {});
 // PGlite's create() only progresses while something holds the event loop;
 // listening starts AFTER readiness so "port answers" means "serves queries"
 const initKeepAlive = setInterval(() => {}, 500);
-const dbReady = PGlite.create({ dataDir, extensions });
+const quoteIdentifier = value => `"${value.replaceAll('"', '""')}"`;
+async function openDeclaredDatabase() {
+  // PostgreSQL cannot rename its current database. Use its maintenance database
+  // before opening the declared one; old Worlds' rows in postgres stay intact.
+  const maintenance = await PGlite.create({ dataDir, extensions, database: 'template1' });
+  try {
+    const existing = await maintenance.query('SELECT datname FROM pg_database WHERE datname = $1', [databaseName]);
+    if (!existing.rows.length) {
+      const legacy = await maintenance.query("SELECT datname FROM pg_database WHERE datname = 'postgres'");
+      await maintenance.exec(legacy.rows.length
+        ? `ALTER DATABASE postgres RENAME TO ${quoteIdentifier(databaseName)}`
+        : `CREATE DATABASE ${quoteIdentifier(databaseName)}`);
+    }
+    const role = await maintenance.query('SELECT rolname FROM pg_roles WHERE rolname = $1', [databaseUser]);
+    if (!role.rows.length) await maintenance.exec(`CREATE ROLE ${quoteIdentifier(databaseUser)} LOGIN SUPERUSER`);
+  } finally { await maintenance.close(); }
+  const db = await PGlite.create({ dataDir, extensions, database: databaseName });
+  await db.exec(`SET SESSION AUTHORIZATION ${quoteIdentifier(databaseUser)}`);
+  return db;
+}
+const dbReady = openDeclaredDatabase();
 dbReady.catch((error) => {
   process.stderr.write(`pglite-host: backend failed to start: ${errorMessage(error)}\n`);
   process.exit(1);
@@ -624,17 +645,9 @@ function lastReadyStatus(response) {
 }
 
 // ---- CREATE DATABASE refusal -----------------------------------------------
-// PGlite accepts CREATE DATABASE (a pg_database row appears) but nothing can
-// ever connect to it: every startup database name aliases to `postgres`. A
-// client that "creates" a database and then connects to it would silently land
-// in the one real database (a Prisma shadow database would replay migrations
-// into it; a test runner would treat it as disposable). So the statement fails:
-// - naming the connection's OWN startup database (or `postgres`), with 42P04
-//   duplicate_database — true, since that name connects, and the answer
-//   check-then-create setup (`rails db:create`) tolerates;
-// - naming any other database, with 0A000 feature_not_supported, because a
-//   tool that treats 42P04 as "reuse it" would then connect to the alias of
-//   the real database and treat it as disposable.
+// Only the declared database can be connected to. Creating another catalog
+// row would advertise a database this service cannot serve, so the statement
+// fails: 42P04 for the declared name, 0A000 for another name.
 // The statement text is rewritten to a DO block that raises, so the BACKEND
 // reports the error and owns the protocol and transaction state
 // (ErrorResponse, aborted block, ReadyForQuery) as for any failing statement.
@@ -662,9 +675,9 @@ const raising = (errcode, message, detail, hint) => `DO ${DOLLAR_TAG} BEGIN RAIS
  * `own`, in plain SQL literal quoting. */
 function refusal(name, own) {
   const label = name && !name.includes(DOLLAR_TAG) ? ` "${name}"` : '';
-  const exists = name !== undefined && (name === own || name === 'postgres');
-  const detail = "The World's PGlite backing serves ONE database; every database name a client connects with is an alias for it, so CREATE DATABASE cannot make a separate one.";
-  const hint = 'Use the database named in DATABASE_URL, or run the World with a container runtime for multiple databases.';
+  const exists = name !== undefined && name === own;
+  const detail = "The World's PGlite backing serves ONE database; only its declared database can be connected to, so CREATE DATABASE cannot make a separately served one.";
+  const hint = 'Use the database named in DATABASE_URL, or select the native PostgreSQL or container backing for multiple databases.';
   return exists
     ? raising('duplicate_database', `database${label} already exists`, detail, hint)
     : raising('feature_not_supported', `CREATE DATABASE${label} is not supported: this World serves one database`, detail, hint);
@@ -785,7 +798,12 @@ const server = net.createServer(async (socket) => {
   socket.on('error', () => { /* close handler owns cleanup */ });
   await fromNodeSocket(socket, {
     serverVersion: '18.3 (PGlite)',
-    auth: { method: 'trust' },
+    auth: { method: 'password', getClearTextPassword: () => databasePassword,
+      validateCredentials: ({ username, password }) => username === databaseUser && password === databasePassword },
+    onStartup({ clientParams }) {
+      const requested = clientParams?.database || clientParams?.user;
+      if (requested !== databaseName) throw BackendError.create({ severity: 'FATAL', code: '3D000', message: `database "${requested}" does not exist` });
+    },
     async onMessage(data, { isAuthenticated, clientParams }) {
       if (!isAuthenticated) return undefined; // gateway owns startup/auth traffic
       const client = data;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.46",
+  "version": "3.0.48",
   "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",
@@ -69,14 +69,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.46",
-    "@volter/world-console": "3.0.41"
+    "@volter/world-core": "3.0.48",
+    "@volter/world-console": "3.0.43"
   },
   "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.46",
+    "@volter/world-core": "3.0.48",
     "mongodb": "~6.20.0",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",

package/src/pglite-backing.ts

@@ -23,7 +23,7 @@ import { fileURLToPath } from 'node:url';
 import { parse } from 'yaml';
 import { mongodbArgv, mongodbListening, mongodbReady } from './mongodb-backing.ts';
 
-export interface InfraService { kind: string; hostPort: number; replicaSet?: string }
+export interface InfraService { kind: string; hostPort: number; replicaSet?: string; postgres?: { user: string; database: string; password?: string } }
 
 /** Read the generated definition's loopback port mappings. MongoDB may explicitly request
  *  one replica-set member through its Compose-compatible command; other mongod options are refused. */
@@ -31,7 +31,7 @@ export function parseInfraDefinition(text: string): InfraService[] {
   const definition = parse(text);
   const services: InfraService[] = [];
   for (const [kind, value] of Object.entries(definition?.services ?? {})) {
-    const declared = value as { ports?: unknown[]; command?: unknown };
+    const declared = value as { ports?: unknown[]; command?: unknown; environment?: Record<string, unknown> };
     let replicaSet: string | undefined;
     if (kind === 'mongodb' && declared.command !== undefined) {
       const command = declared.command;
@@ -46,7 +46,19 @@ export function parseInfraDefinition(text: string): InfraService[] {
       return match ? [Number(match[1])] : [];
     });
     if (ports.length !== 1) throw new Error(`managed infrastructure ${kind} needs exactly one declared loopback port`);
-    services.push({ kind, hostPort: ports[0]!, ...(replicaSet ? { replicaSet } : {}) });
+    let postgres: InfraService['postgres'];
+    if (kind === 'postgres') {
+      const environment = declared.environment ?? {};
+      const user = environment.POSTGRES_USER ?? 'postgres';
+      const database = environment.POSTGRES_DB ?? user;
+      const password = environment.POSTGRES_PASSWORD;
+      if ([user, database, password].some(value => value !== undefined && (typeof value !== 'string' || !value || /[\r\n\0]|\$\{/.test(value)))) {
+        throw new Error('World-managed PGlite requires literal POSTGRES_USER, POSTGRES_DB and POSTGRES_PASSWORD');
+      }
+      if ([user, database].some(value => Buffer.byteLength(value as string, 'utf8') > 63)) throw new Error('World-managed PGlite identifiers must fit PostgreSQL\'s 63-byte name limit');
+      postgres = { user: user as string, database: database as string, ...(password !== undefined ? { password: password as string } : {}) };
+    }
+    services.push({ kind, hostPort: ports[0]!, ...(replicaSet ? { replicaSet } : {}), ...(postgres ? { postgres } : {}) });
   }
   return services;
 }
@@ -167,6 +179,7 @@ export async function pgliteUp(services: InfraService[], dataDir: string, launch
     }
     const name = CONTAINERLESS[service.kind] ?? `pglite-${service.kind}`;
     const serviceData = join(dataDir, containerlessDataDirectory(service.kind) ?? `${name}-data`);
+    if (service.kind === 'postgres' && !service.postgres?.password) throw new Error('World-managed PGlite requires a literal POSTGRES_PASSWORD; declare a throwaway World credential');
     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`);
@@ -184,7 +197,8 @@ export async function pgliteUp(services: InfraService[], dataDir: string, launch
       const logFd = openSync(log, 'a');
       const child = spawn(command!, args, {
         windowsHide: true,
-        env,
+        env: service.postgres ? { ...env, VOLTER_WORLD_PGLITE_USER: service.postgres.user,
+          VOLTER_WORLD_PGLITE_DATABASE: service.postgres.database, VOLTER_WORLD_PGLITE_PASSWORD: service.postgres.password } : env,
         detached: true,
         stdio: ['ignore', logFd, logFd],
       });

package/src/pglite-host.mjs

@@ -33,18 +33,11 @@
 //
 // Limits, stated plainly (measured on 0.5.8 through this gateway with `pg`
 // clients; pglite-backing.test.ts holds the extension and database checks):
-// - ONE database. Trust auth accepts any user/password/database in the
-//   startup packet, so a DATABASE_URL naming `/rallly` connects — but every
-//   name lands in PGlite's single `postgres` database: current_database()
-//   and current_user answer `postgres`, and all names share one catalog.
-//   PGlite itself ACCEPTS `CREATE DATABASE` (a pg_database row appears) yet
-//   nothing can ever connect to it, so this host fails the statement loudly
-//   (see refusal() below): 42P04 "already exists" when the name is the
-//   connection's own startup database (true: it connects, so check-then-
-//   create for the app's own database proceeds), 0A000 "not supported" for
-//   any other name. An app that needs a second real database (Prisma's
-//   shadow database for `migrate dev`, Django's `test_<name>`; `migrate
-//   deploy` needs none) needs the container backing.
+// - ONE declared database and login, authenticated with the World's throwaway
+//   password. Undeclared databases fail 3D000; failed logins fail 28P01.
+//   current_database() and current_user come from the configured backend.
+//   CREATE DATABASE of the declared name fails 42P04, other names fail 0A000;
+//   multiple databases require the native or container backing.
 // - No COPY … FROM STDIN: refused with 0A000 (it aborts PGlite's backend);
 //   COPY … TO STDOUT works.
 // - ONE serialized session. Connections are accepted concurrently but run
@@ -96,6 +89,7 @@ import net from 'node:net';
 import { mkdirSync, readFileSync } from 'node:fs';
 import clockForm from '@volter/world-core/world-clock';
 import { fromNodeSocket } from 'pg-gateway/node';
+import { BackendError } from 'pg-gateway';
 
 // ---- the World's time (above) --------------------------------
 const machineNow = Date.now.bind(Date);
@@ -147,6 +141,13 @@ function arg(name) {
 
 const port = Number(arg('--port'));
 const dataDir = arg('--data');
+const databaseUser = process.env.VOLTER_WORLD_PGLITE_USER;
+const databaseName = process.env.VOLTER_WORLD_PGLITE_DATABASE;
+const databasePassword = process.env.VOLTER_WORLD_PGLITE_PASSWORD;
+if (![databaseUser, databaseName, databasePassword].every(value => typeof value === 'string' && value.length > 0)) {
+  process.stderr.write('pglite-host: declared database identity and throwaway password are required\n');
+  process.exit(2);
+}
 if (!Number.isInteger(port) || port < 1 || port > 65535) {
   process.stderr.write('pglite-host: --port must be 1-65535\n');
   process.exit(2);
@@ -159,7 +160,27 @@ process.stderr.on('error', () => {});
 // PGlite's create() only progresses while something holds the event loop;
 // listening starts AFTER readiness so "port answers" means "serves queries"
 const initKeepAlive = setInterval(() => {}, 500);
-const dbReady = PGlite.create({ dataDir, extensions });
+const quoteIdentifier = value => `"${value.replaceAll('"', '""')}"`;
+async function openDeclaredDatabase() {
+  // PostgreSQL cannot rename its current database. Use its maintenance database
+  // before opening the declared one; old Worlds' rows in postgres stay intact.
+  const maintenance = await PGlite.create({ dataDir, extensions, database: 'template1' });
+  try {
+    const existing = await maintenance.query('SELECT datname FROM pg_database WHERE datname = $1', [databaseName]);
+    if (!existing.rows.length) {
+      const legacy = await maintenance.query("SELECT datname FROM pg_database WHERE datname = 'postgres'");
+      await maintenance.exec(legacy.rows.length
+        ? `ALTER DATABASE postgres RENAME TO ${quoteIdentifier(databaseName)}`
+        : `CREATE DATABASE ${quoteIdentifier(databaseName)}`);
+    }
+    const role = await maintenance.query('SELECT rolname FROM pg_roles WHERE rolname = $1', [databaseUser]);
+    if (!role.rows.length) await maintenance.exec(`CREATE ROLE ${quoteIdentifier(databaseUser)} LOGIN SUPERUSER`);
+  } finally { await maintenance.close(); }
+  const db = await PGlite.create({ dataDir, extensions, database: databaseName });
+  await db.exec(`SET SESSION AUTHORIZATION ${quoteIdentifier(databaseUser)}`);
+  return db;
+}
+const dbReady = openDeclaredDatabase();
 dbReady.catch((error) => {
   process.stderr.write(`pglite-host: backend failed to start: ${errorMessage(error)}\n`);
   process.exit(1);
@@ -624,17 +645,9 @@ function lastReadyStatus(response) {
 }
 
 // ---- CREATE DATABASE refusal -----------------------------------------------
-// PGlite accepts CREATE DATABASE (a pg_database row appears) but nothing can
-// ever connect to it: every startup database name aliases to `postgres`. A
-// client that "creates" a database and then connects to it would silently land
-// in the one real database (a Prisma shadow database would replay migrations
-// into it; a test runner would treat it as disposable). So the statement fails:
-// - naming the connection's OWN startup database (or `postgres`), with 42P04
-//   duplicate_database — true, since that name connects, and the answer
-//   check-then-create setup (`rails db:create`) tolerates;
-// - naming any other database, with 0A000 feature_not_supported, because a
-//   tool that treats 42P04 as "reuse it" would then connect to the alias of
-//   the real database and treat it as disposable.
+// Only the declared database can be connected to. Creating another catalog
+// row would advertise a database this service cannot serve, so the statement
+// fails: 42P04 for the declared name, 0A000 for another name.
 // The statement text is rewritten to a DO block that raises, so the BACKEND
 // reports the error and owns the protocol and transaction state
 // (ErrorResponse, aborted block, ReadyForQuery) as for any failing statement.
@@ -662,9 +675,9 @@ const raising = (errcode, message, detail, hint) => `DO ${DOLLAR_TAG} BEGIN RAIS
  * `own`, in plain SQL literal quoting. */
 function refusal(name, own) {
   const label = name && !name.includes(DOLLAR_TAG) ? ` "${name}"` : '';
-  const exists = name !== undefined && (name === own || name === 'postgres');
-  const detail = "The World's PGlite backing serves ONE database; every database name a client connects with is an alias for it, so CREATE DATABASE cannot make a separate one.";
-  const hint = 'Use the database named in DATABASE_URL, or run the World with a container runtime for multiple databases.';
+  const exists = name !== undefined && name === own;
+  const detail = "The World's PGlite backing serves ONE database; only its declared database can be connected to, so CREATE DATABASE cannot make a separately served one.";
+  const hint = 'Use the database named in DATABASE_URL, or select the native PostgreSQL or container backing for multiple databases.';
   return exists
     ? raising('duplicate_database', `database${label} already exists`, detail, hint)
     : raising('feature_not_supported', `CREATE DATABASE${label} is not supported: this World serves one database`, detail, hint);
@@ -785,7 +798,12 @@ const server = net.createServer(async (socket) => {
   socket.on('error', () => { /* close handler owns cleanup */ });
   await fromNodeSocket(socket, {
     serverVersion: '18.3 (PGlite)',
-    auth: { method: 'trust' },
+    auth: { method: 'password', getClearTextPassword: () => databasePassword,
+      validateCredentials: ({ username, password }) => username === databaseUser && password === databasePassword },
+    onStartup({ clientParams }) {
+      const requested = clientParams?.database || clientParams?.user;
+      if (requested !== databaseName) throw BackendError.create({ severity: 'FATAL', code: '3D000', message: `database "${requested}" does not exist` });
+    },
     async onMessage(data, { isAuthenticated, clientParams }) {
       if (!isAuthenticated) return undefined; // gateway owns startup/auth traffic
       const client = data;