@volter/world-core 2.0.0

package/src/placeholder-remote.ts

@@ -0,0 +1,81 @@
+// THE PLACEHOLDER REMOTE (docs/concepts/the-model.md#a-branch-is-a-position-not-a-copy, "default data"): a fresh twin is a clone of the
+// coherent default data its pack ships, and that seed is a PULL, never a pending write. While a
+// service's placeholder-pull window is open — a marker file under its state dir, read through the
+// active world store like the world clock — every local `set` write the twin accepts lands as an
+// OBSERVED event from the placeholder (origin `virtual`, provenance `placeholder`) and no action row
+// is appended: `main` equals `origin/main` when the seed ends, `diff` is empty, nothing is pending,
+// and no real remote linked later is ever offered the seed. The placeholder has no origin and no
+// credential, so it can never be a push target; a pull from it again is "back to the defaults".
+import { appendParentEntry, toEntry } from './log.ts';
+import { join } from 'node:path';
+import { worldPaths, worldStateRoot } from './storage.ts';
+import { WorldServiceEventSchema } from './schemas.ts';
+import { hashFieldValue } from './hash.ts';
+import { getActiveWorldStore } from './world-store.ts';
+import type { TwinAction } from './actions.ts';
+import type { WorldServiceEvent } from './types.ts';
+
+export const PLACEHOLDER_REMOTE = 'placeholder';
+
+/** The window is per WORLD SERVICE ROOT, not per state service: a twin may record under a state
+ *  service that is not its world service id (slack records under `chat`), and every state service
+ *  of one twin lives under the same root — so the marker sits at the root's state dir. */
+export function placeholderPullMarkerPath(_service: string, root?: string): string {
+  return join(worldStateRoot(root), 'placeholder-pull');
+}
+/** Is the service's placeholder-pull window open? */
+export function placeholderPullActive(service: string, root?: string): boolean {
+  return getActiveWorldStore().exists(placeholderPullMarkerPath(service, root));
+}
+export function beginPlaceholderPull(service: string, root?: string, at: string = new Date().toISOString()): void {
+  const path = placeholderPullMarkerPath(service, root);
+  const store = getActiveWorldStore();
+  store.mkdir(join(path, '..'));
+  store.write(path, `${JSON.stringify({ remote: PLACEHOLDER_REMOTE, openedAt: at })}\n`);
+}
+export function endPlaceholderPull(service: string, root?: string): void {
+  const path = placeholderPullMarkerPath(service, root);
+  if (getActiveWorldStore().exists(path)) getActiveWorldStore().remove(path);
+}
+/** Open the window around `fn` (in-process seeding). */
+export async function withPlaceholderPull<T>(service: string, root: string | undefined, fn: () => T | Promise<T>): Promise<T> {
+  beginPlaceholderPull(service, root);
+  try { return await fn(); } finally { endPlaceholderPull(service, root); }
+}
+
+/** The observed events a local write becomes when it is a pull from the placeholder: the write's
+ *  own subject and fields, plus every resource its projection creates or updates. A projection
+ *  DELETE has no observed form (the placeholder holds what exists, not what was removed) and is
+ *  refused loudly — a seed creates the world, it does not un-create it. */
+export function placeholderEventsFor(action: TwinAction): WorldServiceEvent[] {
+  const observations: Array<{ subject: { type: string; id: string }; fields: Record<string, unknown> }> = [];
+  if (action.fields) observations.push({ subject: action.subject, fields: action.fields });
+  for (const c of action.projection?.creates ?? []) observations.push({ subject: { type: c.type, id: c.id }, fields: c.fields });
+  for (const u of action.projection?.updates ?? []) observations.push({ subject: { type: u.type, id: u.id }, fields: u.fields });
+  if (action.projection?.deletes?.length) throw new Error(`placeholder pull: ${action.service} ${action.operation ?? action.op} deletes ${action.projection.deletes.map((d) => `${d.type}:${d.id}`).join(', ')} — a seed creates the placeholder world, it cannot remove from it`);
+  return observations.map((o) => {
+    const contentHash = hashFieldValue({ subject: o.subject, fields: o.fields, operation: action.operation ?? action.op });
+    const id = `placeholder:${action.service}:${o.subject.type}:${o.subject.id}:${contentHash}`;
+    return WorldServiceEventSchema.parse({
+      id,
+      service: action.service,
+      type: `${action.service}.${o.subject.type}.delta`,
+      schemaVersion: 1,
+      idempotencyKey: id,
+      occurredAt: action.occurredAt,
+      observedAt: action.occurredAt,
+      origin: 'virtual',
+      subject: o.subject,
+      data: { changed: Object.fromEntries(Object.entries(o.fields).map(([k, v]) => [k, { after: v }])), provenance: PLACEHOLDER_REMOTE, remote: PLACEHOLDER_REMOTE },
+    }) as WorldServiceEvent;
+  });
+}
+
+/** Land `action` as the placeholder's observed facts. Caller holds the service locks. */
+export function landAsPlaceholder(action: TwinAction, root?: string): { events: WorldServiceEvent[] } {
+  const paths = worldPaths(action.service, root);
+  const events = placeholderEventsFor(action);
+  // v2: the placeholder's rows land as ENTRIES on the parent log (one row kind), marked as the placeholder's
+  for (const event of events) appendParentEntry({ ...toEntry(event as unknown as Record<string, unknown>), provenance: 'placeholder' }, root);
+  return { events };
+}

package/src/proxy.ts

@@ -0,0 +1,183 @@
+// Zero-edit browser injection: a dev proxy you put in front of your app so the
+// browser's vendor SDK calls share the SAME twin the backend uses — no app edits.
+//
+//   volter-twin proxy --target http://localhost:3000 \
+//     --map stripe=http://127.0.0.1:12111 --route stripe=/v1/ --loader-host stripe=https://api.stripe.com
+//
+// The browser loads your app through the proxy. Requests to a configured vendor's
+// browser API path (its `apiPathPrefix`, e.g. Stripe's /v1/…) are forwarded to that
+// vendor's twin; everything else passes through to your app. For vendors whose browser
+// SDK loads from a CDN and calls an absolute host (its `loaderHost`, e.g. Stripe.js →
+// api.stripe.com), the proxy rewrites the loader so its calls become same-origin and get
+// forwarded too. This kernel module is VENDOR-AGNOSTIC: the per-vendor routing values are
+// DATA supplied by the caller (sourced from each pack's `TwinPack.browserRouting`), never a
+// hardcoded vendor table.
+import http from 'node:http';
+import net from 'node:net';
+
+/** How one vendor's browser SDK is routed to its twin. Supplied by the caller. */
+export interface VendorRoute {
+  /** The vendor's twin origin, e.g. http://127.0.0.1:12111 */
+  origin: string;
+  /** Same-origin browser API path that belongs to this vendor, e.g. '/v1/' */
+  apiPathPrefix: string;
+  /** Absolute API host to strip from the vendor's browser loader so calls become
+   *  same-origin (e.g. 'https://api.stripe.com'). Omit if the SDK already calls same-origin. */
+  loaderHost?: string;
+}
+
+export interface TwinProxyOptions {
+  /** Your app's origin, e.g. http://localhost:3000 */
+  target: string;
+  /** vendor → routing. */
+  map: Record<string, VendorRoute>;
+  /** Extra local service origins whose redirects should be rewritten back to this proxy origin. */
+  redirectOrigins?: string[];
+  /** Listen port (0 = ephemeral). */
+  port?: number;
+}
+
+export interface TwinProxy {
+  port: number;
+  stop(): void;
+}
+
+function vendorForPath(path: string, map: Record<string, VendorRoute>): string | null {
+  for (const [vendor, route] of Object.entries(map)) {
+    if (path.startsWith(route.apiPathPrefix)) return vendor;
+  }
+  return null;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Strip `loaderHost` (a full origin, e.g. 'https://api.stripe.com') from `text` so its
+ * calls become same-origin — but ONLY where it appears as a complete host, not as a
+ * blind substring. A plain `split(loaderHost).join('')` (the prior implementation) is
+ * NOT position-aware: it removes the substring wherever it occurs, including as a
+ * PREFIX of a longer, different host — e.g. 'https://api.stripe.com.evil.example/x'
+ * contains 'https://api.stripe.com' as a literal substring, and a naive strip corrupts
+ * it into '.evil.example/x' (the true host is stripe.com.evil.example, not stripe.com;
+ * same substring bug would also mangle a subdomain like sandbox.api.stripe.com if the
+ * scheme weren't part of the match). Position-aware fix: only strip a match that is NOT
+ * immediately followed by a domain-continuing character (letter/digit/dot/hyphen) —
+ * that character means the matched text is a prefix of a longer host, not the whole
+ * host, so it is left untouched.
+ */
+function stripLoaderHost(text: string, loaderHost: string): string {
+  const pattern = new RegExp(`${escapeRegExp(loaderHost)}(?![A-Za-z0-9.-])`, 'g');
+  return text.replace(pattern, '');
+}
+
+function rewriteLocation(location: string | string[] | undefined, req: http.IncomingMessage, origins: string[]): string | string[] | undefined {
+  if (!location || Array.isArray(location)) return location;
+  const host = req.headers.host;
+  if (!host) return location;
+  const proxyOrigin = `http://${host}`;
+  for (const origin of origins) {
+    const normalized = origin.replace(/\/$/, '');
+    if (location === normalized) return proxyOrigin;
+    if (location.startsWith(`${normalized}/`)) return `${proxyOrigin}${location.slice(normalized.length)}`;
+  }
+  return location;
+}
+
+function forwardTo(
+  origin: string,
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  rewrite?: (body: Buffer, headers: http.IncomingHttpHeaders) => Buffer,
+  redirectOrigins: string[] = [],
+): void {
+  const target = new URL(req.url || '/', origin);
+  const headers = { ...req.headers, host: target.host };
+  delete headers['accept-encoding']; // so we can rewrite uncompressed bodies
+  const upstream = http.request(target, { method: req.method, headers }, (up) => {
+    if ((up.statusCode ?? 0) >= 300 && (up.statusCode ?? 0) < 400) {
+      const responseHeaders = { ...up.headers };
+      // `location` is single-valued, so rewriteLocation returns string|undefined here (never an array).
+      responseHeaders.location = rewriteLocation(responseHeaders.location, req, [origin, ...redirectOrigins]) as string | undefined;
+      delete responseHeaders['transfer-encoding'];
+      delete responseHeaders['content-length'];
+      res.writeHead(up.statusCode || 302, responseHeaders);
+      res.end();
+      up.resume();
+      return;
+    }
+    const chunks: Buffer[] = [];
+    up.on('data', (c) => chunks.push(c as Buffer));
+    up.on('error', () => res.destroyed || res.end());
+    up.on('end', () => {
+      const body = Buffer.concat(chunks);
+      const out = rewrite ? rewrite(body, up.headers) : body;
+      const responseHeaders = { ...up.headers };
+      delete responseHeaders['content-length'];
+      delete responseHeaders['content-encoding'];
+      delete responseHeaders['transfer-encoding'];
+      responseHeaders['content-length'] = String(Buffer.byteLength(out));
+      res.writeHead(up.statusCode || 502, responseHeaders);
+      res.end(out);
+    });
+  });
+  upstream.on('error', (error) => {
+    if (res.headersSent) { res.destroy(error); return; }
+    res.writeHead(502, { 'content-type': 'text/plain' });
+    res.end(`twin proxy upstream error: ${error.message}`);
+  });
+  req.pipe(upstream);
+}
+
+export function createTwinProxy(opts: TwinProxyOptions): TwinProxy {
+  const map: Record<string, VendorRoute> = {};
+  for (const [vendor, route] of Object.entries(opts.map)) map[vendor] = { ...route, origin: route.origin.replace(/\/$/, '') };
+  const redirectOrigins = (opts.redirectOrigins ?? []).map((origin) => origin.replace(/\/$/, ''));
+
+  const server = http.createServer((req, res) => {
+    const path = req.url || '/';
+    const vendor = vendorForPath(path, map);
+    if (vendor) {
+      forwardTo(map[vendor].origin, req, res, undefined, redirectOrigins); // browser vendor API call → the twin
+      return;
+    }
+    // Otherwise pass through to the app, rewriting vendor loaders so their calls come back here.
+    forwardTo(opts.target, req, res, (body, headers) => {
+      const contentType = String(headers['content-type'] || '');
+      if (!contentType.includes('javascript') && !contentType.includes('html')) return body;
+      let text = body.toString('utf8');
+      for (const route of Object.values(map)) {
+        if (route.loaderHost) text = stripLoaderHost(text, route.loaderHost);
+      }
+      return Buffer.from(text, 'utf8');
+    }, redirectOrigins);
+  });
+
+  // WebSocket / HTTP upgrade passthrough — routed by the SAME vendor map as plain
+  // requests, so a vendor whose browser surface speaks WebSocket (a media SFU's
+  // signal path, a realtime API) reaches its twin instead of the app.
+  server.on('upgrade', (req, socket, head) => {
+    const upgradeVendor = vendorForPath(req.url || '/', map);
+    const target = new URL(req.url || '/', upgradeVendor ? map[upgradeVendor].origin : opts.target);
+    const upstream = net.connect(Number(target.port || 80), target.hostname, () => {
+      upstream.write(`${req.method} ${target.pathname}${target.search} HTTP/${req.httpVersion}\r\n`);
+      for (const [name, value] of Object.entries(req.headers)) upstream.write(`${name}: ${value}\r\n`);
+      upstream.write('\r\n');
+      upstream.write(head);
+      upstream.pipe(socket);
+      socket.pipe(upstream);
+    });
+    const killSocket = () => { if (!socket.destroyed) socket.destroy(); };
+    const killUpstream = () => { if (!upstream.destroyed) upstream.destroy(); };
+    upstream.on('error', killSocket);
+    socket.on('error', killUpstream);
+    socket.on('close', killUpstream);
+    upstream.on('close', killSocket);
+  });
+
+  server.listen(opts.port ?? 0, '127.0.0.1');
+  const address = server.address();
+  const port = address && typeof address === 'object' ? address.port : (opts.port ?? 0);
+  return { port, stop: () => server.close() };
+}