@volter/world-runtime 3.0.162 → 3.0.164

package/dist/src/infra-definition.js

@@ -0,0 +1,146 @@
+import { goMysqlBinding, goMysqlEndpoint } from "./go-mysql-binding.js";
+import * as managedOriginalInputs from '@volter/world-core/managed-original-inputs';
+// Definition metadata is independent of database host lifetimes.
+import { createRequire } from 'node:module';
+import { nativeMariaDBReference } from "./mariadb-supplier.js";
+import { mariaDBCredentials } from "./mariadb-bootstrap.js";
+/** Read the generated definition's loopback port mappings and backing-independent options.
+ *  The Compose extension carries a MongoDB replica-set name. Older generated commands remain readable. */
+export function parseInfraDefinition(text) {
+    const { parse } = createRequire(import.meta.url)('yaml');
+    const definition = parse(text);
+    const services = [];
+    for (const [kind, value] of Object.entries(definition?.services ?? {})) {
+        const declared = value;
+        const nativeReference = declared['x-volter-native-server'] === undefined ? undefined : nativeMariaDBReference(declared['x-volter-native-server']);
+        if (nativeReference && (kind !== 'mysql' || declared['x-volter-interfaces'] !== 3 || typeof declared.image !== 'string'
+            || !/^(?:docker\.io\/)?(?:library\/)?mariadb(?::[^@]+)?@sha256:[a-f0-9]{64}$/u.test(declared.image)))
+            throw new Error('Managed native MariaDB needs mysql, infrastructure interface3 and its exact declared image');
+        const originalInputs = declared['x-volter-original-inputs'] === undefined ? undefined : managedOriginalInputs.referenceOf(declared['x-volter-original-inputs']);
+        if (originalInputs && declared['x-volter-interfaces'] !== 2)
+            throw new Error('Managed original inputs require infrastructure interface2');
+        const option = declared['x-volter-replica-set'];
+        if (option !== undefined && (kind !== 'mongodb' || typeof option !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(option))) {
+            throw new Error('World-managed replica-set metadata must name one valid MongoDB replica set');
+        }
+        let replicaSet = option;
+        if (kind === 'mongodb' && declared.command !== undefined) {
+            const command = declared.command;
+            if (!Array.isArray(command) || command.length !== 3 || command[0] !== 'mongod' || command[1] !== '--replSet'
+                || typeof command[2] !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(command[2])) {
+                throw new Error('World-managed MongoDB command must be ["mongod", "--replSet", "<name>"] or absent for standalone');
+            }
+            if (replicaSet !== undefined && replicaSet !== command[2])
+                throw new Error('World-managed MongoDB command and replica-set metadata disagree');
+            replicaSet = command[2];
+        }
+        const mapped = (declared.ports ?? []).flatMap((port) => {
+            const match = typeof port === 'string' ? port.match(/^127\.0\.0\.1:(\d+):(\d+)$/) : null;
+            if ((kind === 'clickhouse' || nativeReference) && (!match || ![Number(match[1]), Number(match[2])].every(value => Number.isInteger(value) && value > 0 && value <= 65535)))
+                throw new Error(`managed infrastructure ${kind} has an invalid loopback port`);
+            // Other kinds retain their earlier reader: unrecognized mappings are skipped.
+            return match ? [{ hostPort: Number(match[1]), containerPort: Number(match[2]) }] : [];
+        });
+        let sides, configuration;
+        if (kind === 'clickhouse') {
+            if (declared['x-volter-interfaces'] !== (originalInputs ? 2 : 1) || mapped.length !== 2 || mapped[0].containerPort !== 8123 || mapped[1].containerPort !== 9000 || mapped[0].hostPort === mapped[1].hostPort)
+                throw new Error('Managed ClickHouse needs named-interface version1, HTTP8123 and native9000 mappings');
+            const raw = declared['x-volter-side-ports'];
+            const native = raw?.native;
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw) || Object.keys(raw).join() !== 'native' || !native || native.hostPort !== mapped[1].hostPort || native.containerPort !== 9000)
+                throw new Error('Managed ClickHouse native side metadata differs from its declared port');
+            sides = { native: mapped[1] };
+            const input = declared['x-volter-configuration'];
+            if (!input || typeof input !== 'object' || Array.isArray(input))
+                throw new Error('Managed ClickHouse needs explicit operator configuration');
+            configuration = input;
+        }
+        else if (mapped.length !== 1 || declared['x-volter-interfaces'] !== (nativeReference ? 3 : originalInputs ? 2 : undefined) || declared['x-volter-side-ports'] !== undefined || declared['x-volter-configuration'] !== undefined) {
+            throw new Error(`managed infrastructure ${kind} needs exactly one declared loopback port and no multiwire metadata`);
+        }
+        const ports = mapped.map(port => port.hostPort);
+        let nativeMariaDB;
+        if (nativeReference) {
+            if (mapped[0].containerPort !== 3306 || originalInputs || declared.command !== undefined || declared.entrypoint !== undefined)
+                throw new Error('Managed native MariaDB has an unconsumed port, original-input, command or entrypoint requirement');
+            const volumes = declared.volumes;
+            if (volumes !== undefined && (!Array.isArray(volumes) || volumes.length !== 1
+                || volumes[0] !== '${VOLTER_WORLD_DATA:?}/native-mariadb-data:/var/lib/mysql'))
+                throw new Error('Managed native MariaDB has an unconsumed source mount requirement');
+            nativeMariaDB = { hostPort: ports[0], image: declared.image,
+                reference: nativeReference, credentials: mariaDBCredentials(declared.environment ?? {}) };
+        }
+        const virtual = declared['x-volter-virtual-tcp-endpoint'];
+        let virtualTcpEndpoint;
+        if (virtual !== undefined) {
+            if (!virtual || typeof virtual !== 'object' || Array.isArray(virtual) || Object.keys(virtual).sort().join() !== 'host,port,targetPort,version'
+                || virtual.version !== 1 || typeof virtual.host !== 'string' || !/^[a-z0-9][a-z0-9-]{0,62}\.world\.volter\.internal$/.test(virtual.host)
+                || virtual.port !== mapped[0].containerPort || virtual.targetPort !== mapped[0].hostPort)
+                throw new Error(`Managed ${kind} virtual TCP endpoint differs from its owned listener`);
+            virtualTcpEndpoint = { version: 1, host: virtual.host, port: Number(virtual.port), targetPort: Number(virtual.targetPort) };
+        }
+        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 } : {}) };
+        }
+        const typed = declared['x-volter-issued-dsn-bindings'];
+        let connectionBindings;
+        if (typed !== undefined) {
+            if (kind !== 'mysql' || !typed || typeof typed !== 'object' || Array.isArray(typed))
+                throw new Error('Managed DSN bindings need a declared MySQL service');
+            connectionBindings = Object.create(null);
+            for (const [name, value] of Object.entries(typed)) {
+                if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || !value || typeof value !== 'object' || Array.isArray(value))
+                    throw new Error('Invalid managed DSN binding');
+                const row = value;
+                const parsed = goMysqlBinding({ ...row, scheme: 'mysql' }, 6, name, mapped[0].containerPort);
+                if (!parsed.dsnFormat || Object.keys(row).some(key => !['dsnFormat', 'endpoint', 'dsnPrefix', 'dsnProtocol', 'containerPort', 'query'].includes(key)))
+                    throw new Error(`Invalid managed DSN declaration for ${name}`);
+                connectionBindings[name] = { ...parsed, containerPort: mapped[0].containerPort };
+            }
+        }
+        services.push({ kind, ...(nativeMariaDB ? { nativeMariaDB } : {}), ...(virtualTcpEndpoint ? { virtualTcpEndpoint } : {}), ...(connectionBindings ? { connectionBindings } : {}), ...(originalInputs ? { originalInputs } : {}), hostPort: ports[0], ...(sides ? { sides } : {}), ...(configuration ? { configuration } : {}), ...(replicaSet ? { replicaSet } : {}), ...(postgres ? { postgres } : {}) });
+    }
+    return services;
+}
+/** Endpoints of the declared infrastructure, published through external.discover. Only URLs
+ * whose protocol and loopback port match a declared service belong to this lifecycle. */
+export function infraConnections(services, env) {
+    const connections = {};
+    for (const [name, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        const typed = services.filter(service => service.connectionBindings?.[name] !== undefined);
+        if (typed.length > 1)
+            throw new Error(`Managed DSN ${name} belongs to multiple infrastructure services`);
+        if (typed.length === 1) {
+            const service = typed[0], endpoint = goMysqlEndpoint(value, service.connectionBindings[name], service.connectionBindings[name].containerPort);
+            const virtual = service.virtualTcpEndpoint, binding = service.connectionBindings[name];
+            const expectedHost = binding.endpoint === 'default-port' && virtual ? virtual.host : '127.0.0.1';
+            const expectedPort = binding.endpoint === 'default-port' && virtual ? virtual.port : service.hostPort;
+            if (!endpoint || endpoint.host !== expectedHost || endpoint.port !== expectedPort)
+                throw new Error(`Managed DSN ${name} does not match its owned endpoint`);
+            connections[name] = value;
+            continue;
+        }
+        try {
+            const url = new URL(value);
+            if (url.hostname !== '127.0.0.1')
+                continue;
+            const kind = url.protocol === 'postgresql:' ? 'postgres' : url.protocol.slice(0, -1);
+            if (services.some((service) => (service.kind === kind && service.hostPort === Number(url.port)) || (service.kind === 'clickhouse' && ((url.protocol === 'http:' && service.hostPort === Number(url.port)) || (url.protocol === 'clickhouse:' && service.sides?.native?.hostPort === Number(url.port))))))
+                connections[name] = value;
+        }
+        catch { /* not an infrastructure endpoint */ }
+    }
+    return connections;
+}

package/dist/src/infra.d.ts

@@ -1,6 +1,9 @@
 export interface InfrastructureIo {
     out: (text: string) => void;
     err: (text: string) => void;
+    /** The runtime's own in-process `up` (runtime.ts): handed the status its `status` would print, when this `up` itself
+     *  proved everything that status proves (every service twin-served, each held and serving). */
+    verified?: (status: string) => void;
 }
 /** One phase of the World-managed infrastructure. `env` is the infrastructure service's environment, which the
  *  services this starts run in; `signal` is the boot's abort (the World's own up passes it; the tool has none). */