@volter/world-runtime 2.0.0

package/dist/src/serve.js

@@ -0,0 +1,82 @@
+// Remote worlds (docs/guides/route-a-cli-through-the-world.md): a served world publishes its manifest over
+// HTTP and opens ONE advertised TLS door (the reflect front terminating the
+// advertised hostname alongside vendor hosts). The manifest an attacher
+// fetches has every vendor rewritten to the advertised origin — the injector
+// preserves the vendor Host header, the door routes by it, the twin answers.
+// Read-only publication: the manifest endpoint tracks no attachers and takes
+// no writes. An optional attach token protects manifest publication.
+import { timingSafeEqual } from 'node:crypto';
+import { createServer as createHttpServer } from 'node:http';
+import { deriveWorldManifest } from "./attach.js";
+import { statusWorld } from "./runtime.js";
+export const MANIFEST_PATH = '/.well-known/volter-world';
+/** The manifest a REMOTE attacher sees: every vendor behind the one advertised
+ * door. The serving side keeps routing against its own loopback env. */
+export function advertiseWorldManifest(name, root, advertisedOrigin) {
+    const local = deriveWorldManifest(name, statusWorld(name, root).env);
+    const vendors = {};
+    // /__vendor/<id> keeps the fetch flow routable through the one door (the
+    // injector's fetch patch rewrites URLs wholesale and loses the vendor Host);
+    // the http/https flow still Host-routes and ignores the origin's path.
+    for (const vendor of Object.keys(local.vendors))
+        vendors[vendor] = `${advertisedOrigin}/__vendor/${vendor}`;
+    return { ...local, vendors };
+}
+export async function startManifestServer(options) {
+    const server = createHttpServer((request, response) => {
+        if (options.token !== undefined) {
+            const presented = (request.headers.authorization ?? '').replace(/^Bearer\s+/i, '');
+            const expected = Buffer.from(options.token);
+            const actual = Buffer.from(presented);
+            if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+                response.writeHead(401, { 'content-type': 'text/plain' });
+                response.end('attach token required\n');
+                return;
+            }
+        }
+        if (request.method !== 'GET' || (request.url !== MANIFEST_PATH && request.url !== '/')) {
+            response.writeHead(404, { 'content-type': 'text/plain' });
+            response.end('volter-world: GET ' + MANIFEST_PATH + '\n');
+            return;
+        }
+        response.writeHead(200, { 'content-type': 'application/json' });
+        response.end(`${JSON.stringify(options.manifest(), null, 2)}\n`);
+    });
+    await new Promise((resolveListen, reject) => {
+        server.once('error', reject);
+        server.listen(options.port ?? 0, options.host ?? '0.0.0.0', () => resolveListen());
+    });
+    const address = server.address();
+    return {
+        port: typeof address === 'object' && address ? address.port : (options.port ?? 0),
+        async close() {
+            await new Promise((resolveClose) => server.close(() => resolveClose()));
+        },
+    };
+}
+/** Fetch a remote world's manifest. Accepts the manifest URL itself or the
+ * world's base URL (the well-known path is appended). */
+export async function fetchRemoteManifest(ref, options = {}) {
+    const base = ref.replace(/\/$/, '');
+    const url = base.endsWith(MANIFEST_PATH) ? base : `${base}${MANIFEST_PATH}`;
+    const response = await fetch(url, options.token === undefined ? undefined : { headers: { authorization: `Bearer ${options.token}` } });
+    if (!response.ok)
+        throw new Error(`remote world manifest: ${url} → ${response.status}`);
+    const manifest = (await response.json());
+    if (typeof manifest.name !== 'string' || typeof manifest.vendors !== 'object' || manifest.vendors === null) {
+        throw new Error(`remote world manifest: ${url} returned no manifest`);
+    }
+    return manifest;
+}
+/** The env a remote env-attachment exports: vendor twin URLs (the advertised
+ * door), suggested fake credentials, CA trust, and the injector preload. */
+export function remoteAttachEnv(manifest, options) {
+    const env = { ...manifest.env };
+    for (const [vendor, origin] of Object.entries(manifest.vendors)) {
+        env[`${vendor.toUpperCase()}_TWIN_URL`] = origin;
+    }
+    env.NODE_OPTIONS = `--require ${options.injectPath}`;
+    if (options.caFile !== undefined)
+        env.NODE_EXTRA_CA_CERTS = options.caFile;
+    return env;
+}

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

@@ -0,0 +1,194 @@
+import { type HistoryReference } from '@volter/world-core';
+import { type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core';
+import { type Changeset, type Receipt } from '@volter/world-core';
+import { rootForControlRoot } from './root.js';
+import type { WorldInstance } from './schema.js';
+export declare const TOKEN_HEADER = "x-volter-token";
+/** The header the injector carries a hosted World's token in (inject.cjs, VOLTER_TWINS_KEY). */
+export declare const TWINS_KEY_HEADER = "x-twins-key";
+/** fetch that waits out a world still booting: a refused connection is retried for `forMs`. */
+export declare function fetchReady(input: string, init: RequestInit, forMs?: number): Promise<Response>;
+/** The serve record beside a world, when the process it names is alive; a stale record (its serving
+ *  process gone) is removed and reads as none. */
+export type ServeRecord = {
+    name: string;
+    url: string;
+    base: string;
+    port: number;
+    pid: number;
+    startedAt: string;
+};
+export declare function readServeRecord(worldRoot: string): ServeRecord | null;
+export type ServedWorld = {
+    url: string;
+    base: string;
+    name: string;
+    port: number;
+    token: string;
+    readToken: string;
+    console: string | null;
+    stop: () => Promise<void>;
+};
+/** The served name: `bare.name` (`acme/team`), else `<id>/<id>`. */
+export declare function servedName(worldRoot: string, configRef: string): string;
+/** A world MOUNTED for serving: its doors, its tokens, and a boot that writes the serve record once the
+ *  URL is known. `serveWorld` mounts one world on its own port; the host mounts many under one URL
+ *  (contract "Just like Neon", 4: one URL per served world, solid and discoverable). */
+/** A world mounted by a host. `token`/`readToken` read the CURRENT tokens (rotate changes them);
+ *  `twins()` names the world's twins once booted; `rotate()` mints both tokens anew — the old die
+ *  with the call — and keeps them beside the world like `boot` does. */
+export type MountedWorld = {
+    name: string;
+    served: string;
+    root: string;
+    readonly token: string;
+    readonly readToken: string;
+    twins: () => string[];
+    rotate: () => {
+        token: string;
+        readToken: string;
+    };
+    handle: (request: Request) => Promise<Response>;
+    boot: (url: string) => Promise<void>;
+    stop: () => Promise<void>;
+};
+export declare function mountWorld(name: string, opts?: {
+    root?: string;
+}): 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?: {
+    root?: string;
+    port?: number;
+    host?: string;
+    consolePort?: number;
+    announce?: (info: {
+        name: string;
+        base: string;
+        token: string;
+        readToken: string;
+        console: string | null;
+    }) => void;
+}): Promise<ServedWorld>;
+/** What the doors need of a world: where each twin's state lives and which twins it has. A booted
+ *  local instance is one; a hosted World describes itself. */
+export type WorldLayout = {
+    dirs: {
+        data: string;
+    };
+    services: Record<string, {
+        url?: string;
+        protocol?: unknown;
+    }>;
+};
+/** The host a world's doors run in: its layout, and how a request reaches a twin's wire — a local
+ *  host forwards to the twin's own port, a hosted World calls the pack in-process. */
+export type DoorHost = {
+    ready: () => boolean;
+    layout: () => WorldLayout;
+    /** The layout re-read before a write lands (a local world may have been re-booted). */
+    reload: () => WorldLayout;
+    /** The twin's wire for a request whose path is the twin's own; null when the world has no such twin. */
+    twinFetch: (vendor: string) => ((request: Request) => Promise<Response>) | null;
+    /** The world's byte-stream doors (a TCP protocol a twin serves: smtp's own, planetscale's mysql),
+     *  by the id a local World gives that listener's service, when this host carries bytes over a
+     *  WebSocket (a hosted World takes no inbound TCP). */
+    streams?: () => Record<string, {
+        protocol: string;
+    }>;
+    openStream?: (id: string, sink: TwinStreamSink, peer: string) => TwinStreamConnection | null;
+    /** Where this host reads a twin's scenario (the handlers document a generative twin serves from,
+     *  re-read on every request), or null when the twin takes none here. */
+    scenarioPath?: (vendor: string) => string | null;
+};
+export declare class WorldDoors {
+    readonly name: string;
+    readonly worldRoot: string;
+    readonly configRef: string;
+    readonly served: string;
+    private readonly host;
+    private readonly queues;
+    token: string;
+    readToken: string;
+    constructor(name: string, worldRoot: string, configRef: string, served: string, host: DoorHost, token: string, readToken: string);
+    /** New tokens; a request presenting the old ones is refused from the next call on. */
+    retoken(token: string, readToken: string): void;
+    /** The world's twins, by vendor, once booted. */
+    twins(): string[];
+    private up;
+    /** The world's token, presented the way the app's SDK presents a credential: the world's own header,
+     *  the injector's `x-twins-key` (a zero-edit app keeps its SDK's own Authorization), `Bearer <token>`,
+     *  GitHub's `token <token>`, or the password half of `Basic` (Jira's email:token). */
+    private scope;
+    /** The World token the request presented, in whichever form, and the scope it opens. */
+    private match;
+    /** Open one connection on a byte-stream door for the holder of the World's (write) token; null when
+     *  the token is not the World's or the World has no such stream. */
+    openStream(token: string, id: string, sink: TwinStreamSink, peer: string): TwinStreamConnection | null;
+    private serialized;
+    private refresh;
+    private controlRoot;
+    private stateOf;
+    handle(request: Request): Promise<Response>;
+    /** The vendor wire: `/<org>/<world>/<vendor>/<rest>` → the twin's own URL. */
+    private wire;
+    /** Whether the twin's pack ships a mirror (its vendor's UI over this World's state). */
+    private hasMirror;
+    /** THE MIRROR MOUNT, as the hosted World serves it (apps/cloud supervisor.ts): `/<org>/<world>/<vendor>/mirror/`
+     *  and `…/mirror/assets/*`, keyless, GET only — the pack's own shell and bundle. The shell's <base> is the
+     *  twin's place under this World, so its reads go to the keyed wire with the browser's World session. */
+    private mirror;
+    private linksPath;
+    /** The World's links: name → the vendor origin it forwards to. */
+    links(): Record<string, {
+        origin: string;
+    }>;
+    private link;
+    /** Forward to the link's origin: the path under the link, the caller's headers with the World's
+     *  token removed and the sealed credential's headers replacing any of the same name. The vendor's
+     *  answer (status, headers, body) is streamed back as it arrives. */
+    private forward;
+    /** The instant of the twin's last completed refresh (its marker's `observedAt`), when it has a root. */
+    private observedAt;
+    /** The world's own doors under `/-/<org>/<world>/`. */
+    private door;
+    /** PUSH: see `landChangeset` — the door hands the body to it. */
+    private push;
+}
+/**
+ * LAND a pushed changeset in a world: its entries go onto the world's branch log for each twin, in
+ * order, each by its own id (landing twice is a no-op). Under `deploy: auto` each landed entry is
+ * performed at once and its receipt answered; under `gated`/`hold` the entry waits (`landed`). The
+ * changeset object is kept beside the world's own, so verify/approve/deploy can name it. The push
+ * door and the path transport both come here.
+ */
+export declare function landChangeset(name: string, worldRoot: string, instance: WorldLayout, changeset: Changeset, expected?: Record<string, HistoryReference>): Promise<Array<{
+    actionId: string;
+    twin: string;
+} & Receipt>>;
+/** Confirm locally what a served world answered: each receipt lands the entry's copy on the parent
+ *  log with that receipt, so `log --receipts` shows it and the entry stops being unpushed. */
+export declare function landReceipts(controlRoot: string, state: string, receipts: Array<{
+    actionId: string;
+} & Receipt>, at?: string): void;
+/** The twins of a world that refresh on a cadence: each rooted twin with `root.refresh.every` ("15m",
+ *  "1h", "30s"), else its pack's declared posture ("Refresh is the kernel's fold", 2). What a local
+ *  host puts on timers and a hosted World on its object's alarm. */
+export declare function refreshSchedule(worldRoot: string, layout: WorldLayout, log?: (line: string) => void): Promise<Array<{
+    vendor: string;
+    controlRoot: string;
+    root: NonNullable<ReturnType<typeof rootForControlRoot>>;
+    everyMs: number;
+}>>;
+/** Observe each scheduled twin's root on its cadence while the world serves locally. A failed refresh
+ *  is logged, never fatal; the next tick tries again. */
+export declare function scheduleRefreshes(name: string, worldRoot: string, instance: WorldInstance, log?: (line: string) => void): Promise<ReturnType<typeof setInterval>[]>;
+/** A remote given as a PATH: the world in that directory, on its checked-out branch, as `fetch` and
+ *  `push` reach it with no server between — git's file transport. The world must have booted at
+ *  least once (its logs live in its instance); `serve` or `up` makes that so. */
+export declare function isPathRemote(target: string): boolean;
+export declare function localWorld(target: string): {
+    root: string;
+    name: string;
+    served: string;
+    instance: WorldInstance;
+};