@volter/world-runtime 2.0.0

package/src/serve.ts

@@ -0,0 +1,102 @@
+// 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, type Server as HttpServer } from 'node:http';
+import { deriveWorldManifest, type WorldManifest } from './attach.ts';
+import { statusWorld } from './runtime.ts';
+
+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: string, root: string, advertisedOrigin: string): WorldManifest {
+  const local = deriveWorldManifest(name, statusWorld(name, root).env);
+  const vendors: Record<string, string> = {};
+  // /__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 interface ManifestServerOptions {
+  manifest: () => WorldManifest;
+  host?: string;
+  port?: number;
+  /** when set, GET requires `Authorization: Bearer <token>` — the attach token
+   * for a shared world (docs/guides/route-a-cli-through-the-world.md). Constant-time-ish compare via length
+   * gate + timingSafeEqual to avoid trivial token oracles. */
+  token?: string;
+}
+
+export interface ManifestServerHandle {
+  port: number;
+  close(): Promise<void>;
+}
+
+export async function startManifestServer(options: ManifestServerOptions): Promise<ManifestServerHandle> {
+  const server: HttpServer = 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<void>((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<void>((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: string, options: { token?: string } = {}): Promise<WorldManifest> {
+  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()) as WorldManifest;
+  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: WorldManifest,
+  options: { caFile?: string; injectPath: string },
+): Record<string, string> {
+  const env: Record<string, string> = { ...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;
+}