@volter/world-core 2.0.1 → 2.0.2

package/src/trace-context.ts

@@ -0,0 +1,87 @@
+// W3C TRACE CONTEXT across a World (https://www.w3.org/TR/trace-context/): one cause followed across
+// vendors by the tracing standard, never an id of our own. An app instrumented with OpenTelemetry
+// sends `traceparent` on its outgoing calls; a real vendor ignores it, so the vendor wire is
+// unchanged. The kernel serve seams (twin-fetch.ts, derived.ts) run a handler inside the request's
+// valid traceparent; every entry appended while handling it records that value (actions.ts
+// `traceparent`, authoring metadata excluded from replay identity like `correlationId`); and a
+// pack's outbound delivery the write caused (a webhook to the app) carries a CHILD of it — the
+// same trace-id, a new parent-id — so the app's handler continues the same trace.
+//
+// Nothing here is vendor knowledge, and nothing runs at import: the async-context store is made on
+// first use (a browser bundle of a mirror client carries the kernel and has no AsyncLocalStorage).
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export const TRACEPARENT_HEADER = 'traceparent';
+
+// version-traceid-parentid-flags, lowercase hex only (the spec's HEXDIGLC). Version ff is invalid;
+// a future version is read by its version-00 prefix only when nothing else follows, which keeps the
+// accepted form exactly the one this module emits.
+const TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+const ZERO_TRACE = '0'.repeat(32);
+const ZERO_SPAN = '0'.repeat(16);
+
+export type Traceparent = { version: string; traceId: string; parentId: string; flags: string };
+
+/** A `traceparent` header value parsed strictly, or null: malformed, version `ff`, or an all-zero
+ *  trace-id or parent-id is no trace at all (the spec: such a header is ignored). */
+export function parseTraceparent(value: unknown): Traceparent | null {
+  if (typeof value !== 'string') return null;
+  const m = TRACEPARENT.exec(value.trim());
+  if (!m) return null;
+  const [, version, traceId, parentId, flags] = m as unknown as [string, string, string, string, string];
+  if (version === 'ff' || traceId === ZERO_TRACE || parentId === ZERO_SPAN) return null;
+  return { version, traceId, parentId, flags };
+}
+
+/** The value itself when it is a valid traceparent (normalized: trimmed), else undefined. */
+export function validTraceparent(value: unknown): string | undefined {
+  const parsed = parseTraceparent(value);
+  return parsed ? `${parsed.version}-${parsed.traceId}-${parsed.parentId}-${parsed.flags}` : undefined;
+}
+
+// created on first use, never at import (see the header)
+let traceStore: AsyncLocalStorage<string> | undefined;
+const traceScope = (): AsyncLocalStorage<string> => (traceStore ??= new AsyncLocalStorage<string>());
+
+/** Run `fn` with `traceparent` as the request's trace context; an invalid value runs `fn` outside any. */
+export function runWithTraceparent<T>(traceparent: string | undefined, fn: () => T): T {
+  const valid = validTraceparent(traceparent);
+  return valid ? traceScope().run(valid, fn) : fn();
+}
+
+/** The trace context of the request being handled, when it carried a valid traceparent. */
+export function currentTraceparent(): string | undefined {
+  return traceStore?.getStore();
+}
+
+/** Run `fn` inside the trace context `request` carries (its `traceparent` header), if any. */
+export function runWithRequestTrace<T>(request: Request, fn: () => T): T {
+  return runWithTraceparent(request.headers.get(TRACEPARENT_HEADER) ?? undefined, fn);
+}
+
+function newSpanId(): string {
+  const bytes = new Uint8Array(8);
+  for (;;) {
+    globalThis.crypto.getRandomValues(bytes);
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    if (hex !== ZERO_SPAN) return hex;
+  }
+}
+
+/**
+ * The `traceparent` an outbound delivery carries: a CHILD of its cause — the same trace-id and
+ * flags, a new parent-id — so the receiving handler continues the cause's trace. The cause is the
+ * given traceparent, or an entry's recorded one, or (omitted) the trace context of the request
+ * being handled. No valid cause, no traceparent: a delivery never invents a trace.
+ */
+export function traceparentForDelivery(cause?: string | { traceparent?: unknown } | null): string | undefined {
+  const source = cause === undefined ? currentTraceparent() : typeof cause === 'string' ? cause : cause?.traceparent;
+  const parent = parseTraceparent(source);
+  return parent ? `00-${parent.traceId}-${newSpanId()}-${parent.flags}` : undefined;
+}
+
+/** `traceparentForDelivery` as headers to spread into a delivery's own: `{ traceparent }` or `{}`. */
+export function deliveryTraceHeaders(cause?: string | { traceparent?: unknown } | null): Record<string, string> {
+  const traceparent = traceparentForDelivery(cause);
+  return traceparent ? { [TRACEPARENT_HEADER]: traceparent } : {};
+}

package/src/twin-fetch.ts

@@ -10,6 +10,8 @@
 // Workerd-clean by construction: no Bun APIs, no fs, no clock but worldNow() — the same
 // closure serves under Bun.serve locally and mounted in-process on Cloudflare.
 import { runWithCorrelationId } from './actions.ts';
+import { runWithRequestTrace } from './trace-context.ts';
+import { isReadOnlyRequest, runAsReadOnlyRequest, type ReadOnlyRequestError } from './request-scope.ts';
 import { worldNow } from './world-clock.ts';
 
 /** The header a host sets when it mounts a twin under a path (a served World's wire:
@@ -40,6 +42,53 @@ export type TwinStreamSink = { write(bytes: Uint8Array): void; end(): void };
 export type TwinStreamConnection = { data(chunk: Uint8Array): void; settled(): Promise<void>; close(): void };
 export type TwinStream = (sink: TwinStreamSink, peer: string) => TwinStreamConnection;
 
+/** The request scopes a pack wrapped in `withRequestScopes` enforces, advertised on its `GET /twin` as
+ *  `requestScopes`: `read` — a request carrying `x-volter-read-only: 1` (request-scope.ts) has every
+ *  write it attempts refused at the kernel's write seam, whatever operation it names. A World's doors
+ *  forward a read-scope request that is not a GET only to a twin that advertises it. */
+export const TWIN_REQUEST_SCOPES: readonly string[] = ['read'];
+
+/** `GET /twin`'s body with the request scopes this seam enforces. */
+function advertised(manifest: unknown): unknown {
+  return manifest !== null && typeof manifest === 'object' && !Array.isArray(manifest) ? { ...(manifest as Record<string, unknown>), requestScopes: [...TWIN_REQUEST_SCOPES] } : manifest;
+}
+
+/** The answer to a read-only request's write when the twin names no vendor-shaped one (rule D3). */
+function readOnlyRefusal(error: ReadOnlyRequestError): Response {
+  return Response.json({ error: 'read_only', message: error.message }, { status: 405 });
+}
+
+/**
+ * THE READ SCOPE for a pack that writes its own fetch (the derived packs, the byte-wire packs): a
+ * request carrying the read-only marker runs with the kernel's write seam refusing its writes, and a
+ * refused write answers `refuse` (the vendor's own read-only error; a generic 405 without one) —
+ * whatever the handler made of the refusal. `GET /twin` advertises `requestScopes`. Everything else
+ * passes through untouched; the wrapped fetch keeps its own properties (a derived fetch's `owners`).
+ */
+export function withRequestScopes<F extends (request: Request) => Promise<Response>>(
+  fetch: F,
+  opts: { refuse?: (request: Request, error: ReadOnlyRequestError) => Response | Promise<Response> } = {},
+): F {
+  const scoped = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    if (request.method === 'GET' && (url.pathname.replace(/\/+$/, '') || '/') === '/twin') {
+      const answer = await fetch(request);
+      if (!answer.ok || !(answer.headers.get('content-type') ?? '').includes('json')) return answer;
+      const headers = new Headers(answer.headers); headers.delete('content-length');
+      return new Response(JSON.stringify(advertised(await answer.json())), { status: answer.status, headers });
+    }
+    // the request's W3C traceparent follows every entry the fetch writes, as through the kernel's own adapters
+    // (a custom fetch never entered it, so the timeline's trace filter missed its entries)
+    return runWithRequestTrace(request, async () => {
+      if (!isReadOnlyRequest(request)) return fetch(request);
+      const out = await runAsReadOnlyRequest(() => fetch(request));
+      if (!out.refused) return out.value;
+      return opts.refuse ? await opts.refuse(request, out.refused) : readOnlyRefusal(out.refused);
+    });
+  };
+  return Object.assign(scoped, fetch);
+}
+
 export type TwinFetchHandlerResult = {
   status: number;
   body: unknown;
@@ -119,18 +168,23 @@ export function createTwinFetchFromHandler(
     // world instant. A client-settable occurredAt would be a direct R9 hole.
     // D3 — the wire's request id becomes the correlation of every action this handler appends.
     const requestId = request.headers.get('x-twins-request-id') ?? undefined;
-    const invoke = () => handler({
+    const invoke = (asReadOnly = readOnly) => handler({
       ...config.handlerOptions,
       ...config.extras?.(request, url),
       method: request.method,
       path: url.pathname + (url.search || ''),
       body,
       headers,
-      readOnly,
+      readOnly: asReadOnly,
       occurredAt: worldNow(),
       ...(config.root !== undefined ? { root: config.root } : {}),
     });
-    const result = await (requestId ? runWithCorrelationId(requestId, invoke) : invoke());
+    // a read-only request is, to the handler, a request to a read-only twin: the pack refuses its
+    // writes in the vendor's own shape (D3), and the kernel's write seam refuses any it misses
+    const scoped = readOnly || isReadOnlyRequest(request);
+    const run = (asReadOnly = scoped) => (requestId ? runWithCorrelationId(requestId, () => invoke(asReadOnly)) : invoke(asReadOnly));
+    // W3C trace context: a valid incoming traceparent scopes the handler, so its entries record it
+    const result = await runWithRequestTrace(request, () => (isReadOnlyRequest(request) ? readScoped(run) : run()));
     // A null/undefined body is an EMPTY reply (`JSON.stringify(null)` would serve the
     // four bytes "null") — and so is the estate's own 204 idiom, `body: ''` with a
     // null-body status: workerd THROWS on any body with 204/205/304 (review B2), where
@@ -145,3 +199,15 @@ export function createTwinFetchFromHandler(
     });
   };
 }
+
+/** A read-only request through the handler seam: the handler runs once, with its writes refused at
+ *  the kernel's write seam; a write it attempted answers 405 (rule D3). The handler is never asked
+ *  twice (a second run would repeat whatever it did before its first write: a rate-limit slot, a
+ *  vendor call). The seam enforces the marker for whoever sends it, but does not advertise
+ *  `requestScopes`: a pack opts in to being handed a World's read-token requests by wrapping its
+ *  fetch in `withRequestScopes`, once it has made sure nothing it does on a read escapes the seam. */
+async function readScoped(run: (asReadOnly?: boolean) => TwinFetchHandlerResult | Promise<TwinFetchHandlerResult>): Promise<TwinFetchHandlerResult> {
+  const out = await runAsReadOnlyRequest(() => run());
+  if (!out.refused) return out.value;
+  return { status: 405, body: { error: 'read_only', message: out.refused.message } };
+}

package/src/world-store.ts

@@ -44,6 +44,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { hostname } from 'node:os';
+import { refuseReadOnlyWrite } from './request-scope.ts';
 import { basename, dirname, join, resolve } from 'node:path';
 
 /** Metadata a caller needs about a stored path. `isDirectory` distinguishes a JSON
@@ -183,6 +184,7 @@ export class FsWorldStore implements WorldStore {
   }
 
   append(path: string, data: string): void {
+    refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
     // Historical appendDurable: a completed append syscall survives a process crash;
     // fsync additionally survives kernel-panic/power-loss when VOLTER_DURABLE=1.
     const fd = openSync(path, 'a');
@@ -195,6 +197,7 @@ export class FsWorldStore implements WorldStore {
   }
 
   write(path: string, data: string, options: { secret?: boolean } = {}): void {
+    refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
     if (!options.secret) {
       mkdirSync(dirname(path), { recursive: true });
       writeFileSync(path, data);
@@ -206,6 +209,7 @@ export class FsWorldStore implements WorldStore {
   }
 
   writeAtomic(path: string, data: string, options: { secret?: boolean } = {}): void {
+    refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
     mkdirSync(dirname(path), { recursive: true });
     const tmp = `${path}.${process.pid}.${Date.now()}.${fsAtomicSequence++}.tmp`;
     try {
@@ -222,6 +226,7 @@ export class FsWorldStore implements WorldStore {
   }
 
   remove(path: string): void {
+    refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
     rmSync(path, { recursive: true, force: true });
   }
 
@@ -391,18 +396,21 @@ export class MemoryWorldStore implements WorldStore {
   }
 
   append(path: string, data: string): void {
+    refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
     this.files.set(path, (this.files.get(path) ?? '') + data);
     this.sizes.set(path, (this.sizes.get(path) ?? 0) + byteLength(data));
     this.bump(path);
   }
 
   write(path: string, data: string): void {
+    refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
     this.files.set(path, data);
     this.sizes.set(path, byteLength(data));
     this.bump(path);
   }
 
   writeAtomic(path: string, data: string): void {
+    refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
     // Atomic by nature in a single process: the assignment is indivisible, so no reader
     // ever observes a partial document.
     this.files.set(path, data);
@@ -419,6 +427,7 @@ export class MemoryWorldStore implements WorldStore {
   }
 
   remove(path: string): void {
+    refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
     let removedAny = false;
     if (this.files.delete(path)) {
       this.versions.delete(path);