@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

package/src/server/tracing.ts

@@ -32,7 +32,7 @@ export function getTraceId(): string {
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
-  return store.traceId;
+  return store.request.traceId;
 }
 
 /**
@@ -57,31 +57,35 @@ export function generateTraceId(): string {
  * per-request ALS scope.
  */
 export function runWithTraceId<T>(id: string, fn: () => T): T {
-  return traceAls.run({ traceId: id }, fn);
+  return traceAls.run({ request: { traceId: id } }, fn);
 }
 
 /**
- * Replace the trace ID in the current ALS store. Used when OTEL creates
- * a root span and we want to switch from the UUID fallback to the real
- * OTEL trace ID.
+ * Replace the request's trace ID. Used when OTEL creates the root span and
+ * we want to switch from the UUID fallback to the real OTEL trace ID. Writes
+ * the request's shared trace, so every scope in the request sees it —
+ * including the ones outside the span this runs in.
  */
-export function replaceTraceId(newTraceId: string, newSpanId?: string): void {
+export function replaceTraceId(newTraceId: string): void {
   const store = traceAls.getStore();
   if (store) {
-    store.traceId = newTraceId;
-    store.spanId = newSpanId;
+    store.request.traceId = newTraceId;
   }
 }
 
 /**
- * Update the span ID in the current ALS store. Used when entering a new
- * OTEL span to keep log–trace correlation accurate.
+ * Run `fn` in a new trace scope for one span: the enclosing scope's request
+ * trace, with this span's pointers. A scope per span, not a save/restore on
+ * a shared store — spans overlap (MetadataCollector does not await
+ * `timber.metadata`), and a restore that runs after a sibling's would
+ * leave the sibling's pointer behind (TIM-1538).
  */
-export function updateSpanId(newSpanId: string | undefined): void {
+function runInSpanScope<T>(
+  pointers: Pick<TraceStore, 'spanId'> | Pick<TraceStore, 'platformSpan'>,
+  fn: () => T
+): T {
   const store = traceAls.getStore();
-  if (store) {
-    store.spanId = newSpanId;
-  }
+  return store ? traceAls.run({ ...store, ...pointers }, fn) : fn();
 }
 
 /**
@@ -113,7 +117,8 @@ const DEV_TRACING_INIT_KEY = Symbol.for('timber.dev.tracing-initialized');
  * we create a BasicTracerProvider with our processor.
  *
  * Idempotent across module re-evaluations (HMR) — only the first call
- * registers. Only called in dev mode — zero overhead in production.
+ * registers. Called in dev, and in production only when TIMBER_DEBUG is
+ * set — otherwise production never loads the OTEL SDK.
  */
 export async function initDevTracing(
   config: import('../dev-tools/logger.ts').DevLoggerConfig
@@ -124,39 +129,17 @@ export async function initDevTracing(
   const api = await getOtelApi();
   if (!api) return;
 
-  let DevSpanProcessor: typeof import('../dev-tools/instrumentation.ts').DevSpanProcessor;
-  let BasicTracerProvider: typeof import('@opentelemetry/sdk-trace-base').BasicTracerProvider;
-  let AsyncLocalStorageContextManager: typeof import('@opentelemetry/context-async-hooks').AsyncLocalStorageContextManager;
-
+  // Tracing is a diagnostic: any failure to load or construct the SDK
+  // disables it with a warning and never fails the server's boot (TIM-1554).
   try {
-    ({ DevSpanProcessor } = await import('../dev-tools/instrumentation.ts'));
-    ({ BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base'));
-    ({ AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks'));
+    const { registerDevTracing } = await import('../dev-tools/instrumentation.ts');
+    registerDevTracing(config);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    console.warn(`[timber] Dev tracing disabled — failed to load OTEL packages:\n  ${msg}`);
+    console.warn(`[timber] Dev tracing disabled — failed to set up OTEL:\n  ${msg}`);
     return;
   }
 
-  const processor = new DevSpanProcessor(config);
-
-  // Register a context manager so OTEL can propagate the active span
-  // across async boundaries. Without this, startActiveSpan can't make
-  // spans "active" — child spans get random trace IDs and getActiveSpan()
-  // returns undefined.
-  const contextManager = new AsyncLocalStorageContextManager();
-  contextManager.enable();
-  api.context.setGlobalContextManager(contextManager);
-
-  // Create a minimal TracerProvider with our DevSpanProcessor.
-  // If the user also configures an SDK in register(), their provider
-  // will coexist — the global provider set last wins for new tracers,
-  // but our processor captures all spans from the timber.js tracer.
-  const provider = new BasicTracerProvider({
-    spanProcessors: [processor],
-  });
-  api.trace.setGlobalTracerProvider(provider);
-
   // Reset cached tracer so next getTracer() picks up the new provider
   _tracer = undefined;
 
@@ -259,7 +242,8 @@ export async function getTracer(): Promise<import('@opentelemetry/api').Tracer |
  *
  * Automatically:
  * - Creates the span as a child of the current context
- * - Updates the ALS span ID for log–trace correlation
+ * - Runs fn in its own trace scope carrying the span's IDs, for log–trace
+ *   correlation and setSpanAttribute()
  * - Ends the span when the function completes
  * - Records exceptions on error (OTEL channel)
  */
@@ -274,21 +258,13 @@ export async function withSpan<T>(
   }
 
   // Native platform span wraps the OTEL emission (dual emission). The
-  // innermost platform span is tracked on the trace store so
-  // setSpanAttribute() can reach it after creation — the platform API has
-  // no getActiveSpan() equivalent.
-  return platformTracer.enterSpan(name, async (span) => {
+  // span is tracked on its own trace scope so setSpanAttribute() can reach
+  // it after creation — the platform API has no getActiveSpan() equivalent.
+  return platformTracer.enterSpan(name, (span) => {
     for (const key of Object.keys(attributes)) {
       span.setAttribute(key, attributes[key]);
     }
-    const store = traceAls.getStore();
-    const prevPlatformSpan = store?.platformSpan;
-    if (store) store.platformSpan = span;
-    try {
-      return await runOtelSpan(name, attributes, fn);
-    } finally {
-      if (store) store.platformSpan = prevPlatformSpan;
-    }
+    return runInSpanScope({ platformSpan: span }, () => runOtelSpan(name, attributes, fn));
   });
 }
 
@@ -304,24 +280,30 @@ async function runOtelSpan<T>(
   }
 
   const api = (await getOtelApi())!;
-  return tracer.startActiveSpan(name, { attributes }, async (span) => {
-    const prevSpanId = getSpanId();
-    updateSpanId(span.spanContext().spanId);
-    try {
-      const result = await fn();
-      span.setStatus({ code: api.SpanStatusCode.OK });
-      return result;
-    } catch (error) {
-      span.setStatus({ code: api.SpanStatusCode.ERROR });
-      if (error instanceof Error) {
-        span.recordException(error);
-      }
-      throw error;
-    } finally {
-      span.end();
-      updateSpanId(prevSpanId);
+  return tracer.startActiveSpan(name, { attributes }, (span) =>
+    runInSpanScope({ spanId: span.spanContext().spanId }, () => settleOtelSpan(api, span, fn))
+  );
+}
+
+/** Run `fn` and end `span` with its outcome. */
+async function settleOtelSpan<T>(
+  api: typeof import('@opentelemetry/api'),
+  span: import('@opentelemetry/api').Span,
+  fn: () => T | Promise<T>
+): Promise<T> {
+  try {
+    const result = await fn();
+    span.setStatus({ code: api.SpanStatusCode.OK });
+    return result;
+  } catch (error) {
+    span.setStatus({ code: api.SpanStatusCode.ERROR });
+    if (error instanceof Error) {
+      span.recordException(error);
     }
-  });
+    throw error;
+  } finally {
+    span.end();
+  }
 }
 
 /**
@@ -389,9 +371,10 @@ export function addSpanEventSync(
 
 /**
  * Try to extract the OTEL trace ID from the current active span context.
- * Returns undefined if OTEL is not active or no span exists.
+ * Returns undefined if OTEL is not active or no span exists. (The span ID
+ * reaches logs through the span's own trace scope, not from here.)
  */
-export async function getOtelTraceId(): Promise<{ traceId: string; spanId: string } | undefined> {
+export async function getOtelTraceId(): Promise<string | undefined> {
   const api = await getOtelApi();
   if (!api) return undefined;
 
@@ -404,5 +387,5 @@ export async function getOtelTraceId(): Promise<{ traceId: string; spanId: strin
     return undefined;
   }
 
-  return { traceId: ctx.traceId, spanId: ctx.spanId };
+  return ctx.traceId;
 }

package/src/server/types.ts

@@ -6,7 +6,7 @@ import type { EarlyHint } from './early-hints.ts';
 /**
  * A value that is safe to pass through `JSON.stringify` without data loss.
  *
- * Used as the constraint for `deny(status, data)` and `RenderError` digest data
+ * Used as the constraint for `deny(status, { dangerouslyPassData })` data
  * because the post-flush path serializes via JSON.stringify, not React Flight.
  * Types that survive Flight (Date, Map, Set, BigInt) would silently coerce or
  * throw when serialized as JSON. This type prevents that at compile time.

package/src/server/version-skew.ts

@@ -32,15 +32,15 @@ export const RELOAD_HEADER = 'X-Timber-Reload';
 // ─── Deployment ID ───────────────────────────────────────────────
 
 /**
- * The current build's deployment ID. Set at startup from the manifest init
- * module (globalThis.__TIMBER_DEPLOYMENT_ID__). Null in dev mode.
+ * The current build's deployment ID. Set at startup from the runtime config
+ * (`virtual:timber-config`'s `deploymentId`). Null in dev mode.
  */
 let currentDeploymentId: string | null = null;
 
 /**
- * Set the current deployment ID. Called once at server startup from the
- * manifest init module. In dev mode this is never called (deployment ID
- * checks are skipped).
+ * Set the current deployment ID. Called once at server startup by the RSC
+ * entry's `createRequestHandler()`. In dev mode this is never called
+ * (deployment ID checks are skipped).
  */
 export function setDeploymentId(id: string): void {
   currentDeploymentId = id;

package/src/shared/csrf-reject.ts

@@ -0,0 +1,15 @@
+/**
+ * Marker header on CSRF rejections.
+ *
+ * A CSRF rejection is a 403, the same status as an access-control denial.
+ * The server stamps this header on every CSRF 403 so callers — the browser
+ * action runtime, a same-origin `fetch` in user code, a curl session — can
+ * tell the two apart without parsing the body. A cross-origin `fetch` cannot
+ * read it: the rejection returns before proxy.ts, so no CORS headers are set
+ * and the browser reports a network error instead. Shared so the server writer and the client
+ * reader cannot drift.
+ *
+ * See design/08-forms-and-actions.md §"CSRF Protection" (TIM-1459).
+ */
+export const CSRF_REJECT_HEADER = 'X-Timber-Reject';
+export const CSRF_REJECT_VALUE = 'csrf';

package/src/shared/error-digest.ts

@@ -0,0 +1,46 @@
+/**
+ * The digest an unhandled render error carries across Flight, and the
+ * correlation ID error pages read back out of it.
+ *
+ * Flight's `onError` (server/rsc-entry/rsc-stream.ts) returns this string for
+ * any error that is not a deny or redirect, and React sets it as `digest` on
+ * the Error it revives for that row, in SSR and on the client alike. The
+ * `errorId` is the one the server logged the error with, so an error page
+ * that shows it gives the reader something to quote that an operator can
+ * find. It is the `digest` prop every TSX error page receives.
+ *
+ * `message` is the real message only in dev; production sends a fixed string
+ * (design/13-security.md §"Errors don't leak").
+ */
+
+interface ErrorRowDigest {
+  type: 'error';
+  message: string;
+  errorId: string;
+}
+
+export function encodeErrorDigest(digest: Omit<ErrorRowDigest, 'type'>): string {
+  const row: ErrorRowDigest = { type: 'error', ...digest };
+  return JSON.stringify(row);
+}
+
+/**
+ * The correlation ID in an error's Flight digest, or `null` when the error
+ * carries none — a deny or redirect row, an error that never crossed Flight,
+ * or anything that is not an object.
+ */
+export function errorDigestId(error: unknown): string | null {
+  if (typeof error !== 'object' || error === null) return null;
+  const digest: unknown = Reflect.get(error, 'digest');
+  if (typeof digest !== 'string') return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(digest);
+  } catch {
+    // A digest someone else set (a library's own error): not ours to read.
+    return null;
+  }
+  if (typeof parsed !== 'object' || parsed === null) return null;
+  const errorId: unknown = Reflect.get(parsed, 'errorId');
+  return Reflect.get(parsed, 'type') === 'error' && typeof errorId === 'string' ? errorId : null;
+}

package/src/shared/payload-root.ts

@@ -67,9 +67,9 @@ export interface RscPayloadRoot extends PublishedParams {
  * In the browser this is unreachable for a real response: all four producers
  * of a route payload go through `withPublishedParams`, and a client talking to
  * a different build is answered with 204 at Stage 1c
- * (`server/pipeline-phases.ts`) before any payload exists. It is reachable in
- * the router's test/fallback path, where `decodeRsc` is absent and the
- * "payload" is the raw response text.
+ * (`server/pipeline-phases.ts`) before any payload exists. It is what a page
+ * with no payload at all publishes — a document hydrated without an inlined
+ * payload, or a prefetch entry that carries no params.
  */
 export const NO_PUBLISHED_PARAMS: PublishedParams = { params: {}, slotParams: null };
 
@@ -99,9 +99,8 @@ export function readPublishedParams(source: unknown): PublishedParams {
 /**
  * Read the renderable tree out of a payload root.
  *
- * Returns the value unchanged when it is not a root — the router's fallback
- * path stores raw response text under the same name, and a test asserting on
- * that text should see the text.
+ * Returns the value unchanged when it is not a root, so a malformed value
+ * reaches React (and its error boundaries) rather than vanishing here.
  */
 export function readPayloadTree(root: unknown): unknown {
   if (typeof root === 'object' && root !== null && 'tree' in root && hasPublishedParams(root)) {
@@ -118,10 +117,12 @@ export interface SplitPayload {
    * The params published beside it. Settled when the root already is, so the
    * hydration path can render without an extra await.
    *
-   * **Never rejects.** A decode failure has to surface where React renders
-   * `tree`, so the error boundary *around the tree* catches it. Rejecting here
-   * too would take down the provider above every boundary in the app, turning
-   * a contained failure into a blank page (TIM-1297).
+   * **Never rejects.** A decode failure has to surface through `tree`: where
+   * React renders it on hydration, so the error boundary *around the tree*
+   * catches it, and where the router awaits it before handing a navigation
+   * over, so the navigation fails and recovers. Rejecting here too would take
+   * down the provider above every boundary in the app, turning a contained
+   * failure into a blank page (TIM-1297).
    */
   params: ParamsSource;
 }

package/src/shared/rsc-payload-path.ts

@@ -39,7 +39,14 @@
  *   normalize; this function does not, because the two callers normalize from
  *   different sources (a browser URL, a build-time route entry).
  */
+/**
+ * The directory, relative to the site root, that holds every static RSC
+ * payload. The one spelling: the build writes, hashes, and reports it as
+ * content-hashed from here.
+ */
+export const RSC_PAYLOAD_DIR = '_rsc';
+
 export function rscPayloadPath(routePath: string): string {
   const prefix = routePath === '/' ? '' : routePath;
-  return `/_rsc${prefix}/index.rsc`;
+  return `/${RSC_PAYLOAD_DIR}${prefix}/index.rsc`;
 }

package/src/utils/write-file-atomic.ts

@@ -0,0 +1,32 @@
+/**
+ * Replace a file's contents in one step: write a uniquely named temp sibling,
+ * then `rename()` it over the target.
+ *
+ * `writeFile()` opens its target with `O_TRUNC`, so for the length of the write
+ * a concurrent reader sees an empty or half-written file under the real name.
+ * `rename()` within one directory swaps the name atomically, so a reader sees
+ * either the old file or the new one — never a torn one — and a crashed
+ * writer leaves no partial artifact under the final name.
+ *
+ * The temp name is unique per call, not a fixed `${path}.tmp`: two writers of
+ * the same path (a dev server and a `vite build` rewriting the same route
+ * types, parallel CLI invocations sharing a cache) would otherwise write into
+ * one temp file and rename each other's half-written bytes into place.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { rename, rm, writeFile } from 'node:fs/promises';
+
+export async function writeFileAtomic(path: string, data: Uint8Array | string): Promise<void> {
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmp, data);
+    await rename(tmp, path);
+  } catch (err) {
+    // Best-effort cleanup. If the directory refuses the write it may refuse
+    // the rm too, and that error — naming a random temp path — must not
+    // replace the one that says what actually failed.
+    await rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+}