@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/plugins/graph-endpoint.ts

@@ -0,0 +1,532 @@
+/**
+ * graph-endpoint — `GET /__timber/graph` on the dev server.
+ *
+ * The fast path of design/47: when a dev server runs, the env module
+ * graphs are already resident and classification is a lookup. Serves
+ * the `timber graph` CLI (delegation lands with the fast-path ticket)
+ * and the VS Code extension, which additionally needs push updates on
+ * HMR — something a CLI cannot provide.
+ *
+ * Dev-only by construction: registered from the timber-dev-server
+ * plugin, which is `apply: 'serve'`; production builds contain none of
+ * this. Same JSON contract as the CLI, produced by the same
+ * classification module (analyze/live-graph.ts → classify/chains/
+ * poison-scan) — never a second implementation.
+ *
+ * Endpoint hygiene (§10): requests are validated against DNS rebinding
+ * consistent with Vite's own dev-endpoint protections — the Host
+ * header must be a localhost form or an allowed host (Vite's
+ * `server.allowedHosts` semantics, including leading-dot suffix
+ * entries), and a present Origin header must pass the same check. A
+ * CLI probe sends no Origin and passes; a browser on an attacker's
+ * page either fails the Host check (rebinding: Host is the attacker's
+ * domain) or the Origin check (direct cross-origin fetch).
+ *
+ * Push channel: `timber:graph-update` custom HMR events, one per
+ * project-source watcher event. The channel just emits — debounce is
+ * the consumer's concern (design/47 §"Dev-server endpoint").
+ *
+ * Design docs: 47-module-environment-tooling.md §10, 21-dev-server.md.
+ */
+
+import type { ViteDevServer } from 'vite';
+import { normalizePath } from 'vite';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { realpath, stat } from 'node:fs/promises';
+import { isIP } from 'node:net';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import type { PluginContext } from '../plugin-context.ts';
+import { buildSourceExtensions, isScannableSourceFile } from '../analyze/scan.ts';
+import { GRAPH_JSON_VERSION } from '../analyze/graph-cache.ts';
+
+export const GRAPH_ENDPOINT_PATH = '/__timber/graph';
+
+/** HMR custom event name for graph-affecting file changes. */
+export const GRAPH_UPDATE_EVENT = 'timber:graph-update';
+
+/**
+ * Host-header allowlist check, ported branch-for-branch from Vite's
+ * host-validation middleware (`isHostAllowedWithoutCache`) so this
+ * endpoint's reachability matches the rest of the dev server:
+ *
+ * - `allowedHosts: true` allows everything
+ * - a MISSING Host header is allowed (Vite parity — HTTP/1.0 probes)
+ * - any IP-literal host is allowed (`vite --host` LAN access sends
+ *   `Host: 192.168.x.x:port`; rejecting it would 403 this endpoint
+ *   while every other dev route works)
+ * - `localhost` and `*.localhost` are always allowed
+ * - allowedHosts entries: exact match, or `.suffix` subdomain entries
+ */
+export function isAllowedGraphHost(
+  hostHeader: string | undefined,
+  allowedHosts: true | string[] | undefined
+): boolean {
+  if (allowedHosts === true) return true;
+  if (hostHeader === undefined) return true;
+  // Strip the port: `localhost:3000`, `[::1]:3000`, bare `[::1]`.
+  let host = hostHeader;
+  const bracket = host.match(/^\[([^\]]+)\](?::\d+)?$/);
+  if (bracket) {
+    // Bracketed form is only valid for IPv6 literals.
+    return isIP(bracket[1]) === 6;
+  }
+  const colon = host.lastIndexOf(':');
+  if (colon !== -1) host = host.slice(0, colon);
+  host = host.toLowerCase();
+  if (isIP(host) !== 0) return true;
+  if (host === 'localhost' || host.endsWith('.localhost')) return true;
+  for (const entry of allowedHosts ?? []) {
+    const allowed = entry.toLowerCase();
+    if (allowed.startsWith('.')) {
+      if (host === allowed.slice(1) || host.endsWith(allowed)) return true;
+    } else if (host === allowed) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Non-http(s) origins admitted without a host check: Vite's own
+ * `file:` / `*-extension:` set (its host-validation regex), plus
+ * `vscode-webview:` — VS Code webviews fetch with that Origin, and the
+ * extension is this endpoint's primary consumer. Vite itself never
+ * origin-checks plain HTTP GETs (only WebSocket upgrades), so this
+ * layer is strictly additional; the additions keep it from rejecting
+ * consumers Vite would serve.
+ *
+ * NOT admitted: `Origin: null`. Browsers serialize file:// pages'
+ * opaque origin as the literal string `null` — but so do sandboxed
+ * iframes and data: documents, exactly the untrusted embedders the
+ * check exists to stop, and the header offers nothing to tell them
+ * apart. file:// pages therefore cannot use this endpoint from a
+ * browser; the `file:` scheme entry covers non-browser clients that
+ * send a real scheme-form Origin (Vite admits the same set).
+ */
+const TRUSTED_ORIGIN_SCHEMES = /^(?:file|vscode-webview|.+-extension):/i;
+
+/** Origin check: absent is fine (CLI probe); present must pass the host allowlist. */
+export function isAllowedGraphOrigin(
+  originHeader: string | undefined,
+  allowedHosts: true | string[] | undefined
+): boolean {
+  if (originHeader === undefined) return true;
+  if (TRUSTED_ORIGIN_SCHEMES.test(originHeader)) return true;
+  let originUrl: URL;
+  try {
+    originUrl = new URL(originHeader);
+  } catch {
+    return false;
+  }
+  // An http(s) origin has a real host — hold it to the host allowlist,
+  // NOT to the missing-Host leniency above (an Origin header is never
+  // "missing" once present; an empty host must fail).
+  if (originUrl.host === '') return false;
+  // IP-literal leniency applies to the request's HOST header (LAN dev
+  // access), never to Origin: a hostile page at http://203.0.113.10
+  // sends that IP as its Origin, and admitting it (plus reflected
+  // CORS) would let it read the whole module graph. Only loopback IP
+  // origins pass; other IPs need an allowedHosts entry. (A developer
+  // browsing the app over LAN fetches same-origin, which sends no
+  // Origin header on GET — unaffected.)
+  const bareHost = originUrl.hostname.replace(/^\[|\]$/g, '');
+  if (isIP(bareHost) !== 0) {
+    if (bareHost === '127.0.0.1' || bareHost === '::1') return true;
+    if (allowedHosts === true) return true;
+    return (allowedHosts ?? []).some((entry) => entry.toLowerCase() === bareHost);
+  }
+  return isAllowedGraphHost(originUrl.host, allowedHosts);
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.statusCode = status;
+  res.setHeader('content-type', 'application/json; charset=utf-8');
+  res.end(JSON.stringify(body));
+}
+
+/**
+ * Echo an ADMITTED origin back as CORS headers. A webview fetch from
+ * `vscode-webview://…` passes the origin check but the browser rejects
+ * the response body without `Access-Control-Allow-Origin` — the exact
+ * transport design/47 specifies for the extension. Only the validated
+ * origin is echoed (never `*`), with `Vary: Origin` for any cache in
+ * between; unadmitted origins were already 403'd and get nothing.
+ */
+function reflectCors(res: ServerResponse, origin: string | undefined): void {
+  if (!origin) return;
+  res.setHeader('Access-Control-Allow-Origin', origin);
+  res.setHeader('Vary', 'Origin');
+}
+
+/**
+ * Create the Connect middleware handling GET /__timber/graph.
+ *
+ * Query surface: `?file=<path>` (absolute or project-root-relative) or
+ * `?all=1`. Anything else is a 400 — fail loudly, like the CLI.
+ */
+export function createGraphEndpointMiddleware(server: ViteDevServer, ctx: PluginContext) {
+  const sourceExtensions = buildSourceExtensions(ctx.config.pageExtensions);
+  return async (req: IncomingMessage, res: ServerResponse, next: () => void): Promise<void> => {
+    const rawUrl = req.url;
+    // Reserve the whole /__timber/ namespace: unknown paths under it
+    // must 404 here, not fall through and render the app's 404 page.
+    if (!rawUrl || !rawUrl.startsWith('/__timber/')) {
+      next();
+      return;
+    }
+    const url = new URL(rawUrl, 'http://placeholder.invalid');
+    if (url.pathname !== GRAPH_ENDPOINT_PATH) {
+      sendJson(res, 404, { error: `unknown /__timber/ endpoint: ${url.pathname}` });
+      return;
+    }
+
+    if (req.method !== 'GET') {
+      res.setHeader('Allow', 'GET');
+      sendJson(res, 405, { error: 'GET only' });
+      return;
+    }
+
+    // Host validation is skipped under server.https, as Vite skips it
+    // (TLS cert matching already defeats DNS rebinding). The ORIGIN
+    // check is not: it guards cross-site reads, which TLS does nothing
+    // about — and since admitted origins get reflected CORS below,
+    // skipping it under https would let any page read the endpoint.
+    const origin = req.headers.origin as string | undefined;
+    const allowedHosts = server.config.server.allowedHosts;
+    if (!server.config.server.https && !isAllowedGraphHost(req.headers.host, allowedHosts)) {
+      sendJson(res, 403, { error: 'host not allowed' });
+      return;
+    }
+    if (!isAllowedGraphOrigin(origin, allowedHosts)) {
+      sendJson(res, 403, { error: 'origin not allowed' });
+      return;
+    }
+    // Past validation: reflect the admitted origin so webview/browser
+    // consumers can actually READ the response.
+    reflectCors(res, origin);
+
+    try {
+      // Lazy import: the analyze pipeline (oxc parse, chains) loads on
+      // first query, not on every dev-server boot.
+      const { classifyLiveFile, classifyLiveProject } = await import('../analyze/live-graph.ts');
+      // Root must share the graphs' path space: by default Vite
+      // resolves through symlinks and nodes carry realpaths, but under
+      // resolve.preserveSymlinks the graphs keep the SYMLINK paths and
+      // realpathing would break every lookup instead of fixing it —
+      // honor the resolved setting (same rule as the crawl).
+      const preserveSymlinks = server.config.resolve.preserveSymlinks;
+      // Slash-normalized like every other frontend's paths — on
+      // Windows a native-separator root beside slash-normalized module
+      // paths would break consumers stripping the root prefix.
+      const root = normalizePath(preserveSymlinks ? ctx.root : await realpath(ctx.root));
+      // appDir must live in the same path space as root and the graph
+      // nodes: on a symlinked project ctx.appDir still carries Vite's
+      // unresolved prefix — and the appDir itself may be a symlink
+      // (src/app -> elsewhere), so realpath the whole thing rather
+      // than assuming the relative suffix is symlink-free. Under
+      // preserveSymlinks the graphs keep logical paths and ctx.appDir
+      // is already in that space.
+      const appDir = normalizePath(
+        preserveSymlinks
+          ? ctx.appDir
+          : await realpath(ctx.appDir).catch(() => join(root, relative(ctx.root, ctx.appDir)))
+      );
+      const liveCtx = {
+        rsc: server.environments.rsc.moduleGraph,
+        ssr: server.environments.ssr.moduleGraph,
+        client: server.environments.client.moduleGraph,
+        root,
+        appDir,
+        pageExtensions: ctx.config.pageExtensions,
+      };
+
+      const allParam = url.searchParams.get('all');
+      if (allParam !== null && allParam !== '1') {
+        // Fail loudly: `?all=0`/`?all=false` silently returning the
+        // full project would hand API clients the wrong response shape.
+        sendJson(res, 400, { error: `unsupported all value: ${allParam} (use ?all=1)` });
+        return;
+      }
+      if (allParam === '1') {
+        const report = await classifyLiveProject(liveCtx);
+        // `cached: false` always — live answers are never cached, and
+        // consumers switching between sources should not lose the
+        // field. `stats` stays a static-scan extra (crawl bookkeeping
+        // with no live equivalent) — documented in design/47.
+        sendJson(res, 200, {
+          version: GRAPH_JSON_VERSION,
+          source: 'dev-server',
+          cached: false,
+          ...report,
+        });
+        return;
+      }
+
+      const fileParam = url.searchParams.get('file');
+      if (!fileParam) {
+        sendJson(res, 400, { error: 'missing ?file=<path> (or ?all=1)' });
+        return;
+      }
+      // resolve() in BOTH branches: it collapses `..` segments, and
+      // under preserveSymlinks the un-realpathed value is what gets
+      // containment-checked — a raw absolute `/root/../outside/x.ts`
+      // would pass the prefix check while stat/readFile escape the
+      // project.
+      // Slash-normalized so every comparison below shares the root's
+      // path space (resolve/realpath emit backslashes on Windows).
+      const absolute = normalizePath(
+        isAbsolute(fileParam) ? resolve(fileParam) : resolve(root, fileParam)
+      );
+      // Target follows the root's path-space rule. realpath doubles as
+      // the existence check in both branches — and the PHYSICAL path is
+      // containment-checked even under preserveSymlinks: a symlink
+      // inside the project pointing outside it would otherwise pass the
+      // lexical prefix check while readFile followed it out of the
+      // project. (Symlinks resolving within the project still work.)
+      let target: string;
+      try {
+        const physical = normalizePath(await realpath(absolute));
+        const rootPhysical = preserveSymlinks ? normalizePath(await realpath(root)) : root;
+        if (
+          physical !== rootPhysical &&
+          !physical.startsWith(rootPhysical + '/') &&
+          !physical.startsWith(rootPhysical + '\\')
+        ) {
+          sendJson(res, 404, { error: `not a project file under ${root}` });
+          return;
+        }
+        if (preserveSymlinks) {
+          // Segment-safe symlink check: the disk scan neither follows
+          // file symlinks nor descends directory symlinks, so a path
+          // reached through EITHER (link.ts, or link/a.ts via
+          // link -> src) would 200 here while the ?all sweep omits it.
+          // Symlinks ABOVE the root are fine (reaching the project via
+          // one is the preserveSymlinks use case) — require only that
+          // the path RELATIVE to the root is symlink-free, i.e. the
+          // physical path equals the physical root plus that suffix.
+          const suffix = absolute.slice(root.length);
+          const expected = rootPhysical + suffix;
+          if (physical !== expected) {
+            sendJson(res, 404, { error: `not a project source file: ${absolute}` });
+            return;
+          }
+        }
+        target = normalizePath(preserveSymlinks ? absolute : physical);
+      } catch {
+        sendJson(res, 404, { error: `file not found: ${absolute}` });
+        return;
+      }
+      if (target !== root && !target.startsWith(root + '/') && !target.startsWith(root + '\\')) {
+        sendJson(res, 404, { error: `not a project file under ${root}` });
+        return;
+      }
+      // Same admission rules as the CLI's scan (design/47: project
+      // source files only) via the shared helper — without it, any
+      // real path under the root (package.json, dist/generated.js,
+      // types.d.ts, a nested node_modules file, a DIRECTORY named
+      // foo.ts) would get a synthetic classification the static scan
+      // would refuse, and the frontends would disagree.
+      const targetStat = await stat(target).catch(() => null);
+      if (
+        !targetStat?.isFile() ||
+        !isScannableSourceFile(normalizePath(target), normalizePath(root), sourceExtensions)
+      ) {
+        sendJson(res, 404, { error: `not a project source file: ${target}` });
+        return;
+      }
+      const errors: import('../analyze/live-graph.ts').LiveGraphError[] = [];
+      const module = await classifyLiveFile(target, liveCtx, undefined, errors);
+      // Explicit field list, mirroring the CLI's single-file output —
+      // a spread would leak `file` (redundant with target.resolved) and
+      // silently drift the two frontends' key sets. `stats` is a
+      // static-scan extra and deliberately absent here.
+      sendJson(res, 200, {
+        version: GRAPH_JSON_VERSION,
+        source: 'dev-server',
+        cached: false,
+        target: { input: fileParam, resolved: target },
+        kind: module.kind,
+        pending: module.pending,
+        subtreeUnknown: module.subtreeUnknown,
+        envs: module.envs,
+        boundary: module.boundary,
+        chains: module.chains,
+        poisonings: module.poisonings,
+        errors,
+      });
+    } catch (error) {
+      sendJson(res, 500, {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  };
+}
+
+/** What one hotUpdate invocation tells the emitter. */
+export interface GraphHotUpdate {
+  file: string;
+  /** Vite's own hotUpdate vocabulary. */
+  type: 'create' | 'update' | 'delete';
+  /** Environment the hook ran for (rsc/ssr/client). */
+  environment: string;
+}
+
+/** The push channel's two notification points for one edit. */
+export interface GraphUpdateChannel {
+  /** Feed from the plugin's hotUpdate hook (post graph invalidation). */
+  onHotUpdate(update: GraphHotUpdate): void;
+  /**
+   * Feed from the plugin's transform hook (module id, may carry a
+   * query suffix). Emits phase "transformed" for files with a pending
+   * invalidation, once their import edges are actually rebuilt.
+   */
+  onTransform(id: string, environment: string): void;
+}
+
+/**
+ * Accessor the channel uses to decide when a re-transforming module's
+ * graph data is current: Vite stores the node's `transformResult` only
+ * at the END of the transform request — after `vite:import-analysis`
+ * has rebuilt the importer edges — so a non-null result is the
+ * edges-are-current signal.
+ */
+export type IsNodeTransformed = (file: string, environment: string) => boolean;
+
+/**
+ * Build the push channel: `timber:graph-update` custom HMR events per
+ * project-source change. Consumers (the VS Code extension) re-query
+ * and debounce on their side; the channel just emits. Non-source noise
+ * (build output, dotdirs) is filtered by the same extension set the
+ * scanners use.
+ *
+ * Two phases per edit, because one is not enough (codex review, PR
+ * #1057): the `invalidated` event fires from the plugin's `hotUpdate`
+ * hook — after Vite clears the module's transform result, but its
+ * importer EDGES are only rebuilt when the module is next transformed.
+ * The `transformed` event fires for exactly the files with a pending
+ * invalidation, and only once the node's `transformResult` is set
+ * again — the plugin transform hook itself runs BEFORE Vite's trailing
+ * `vite:import-analysis` (which rebuilds the edges), so the hook only
+ * marks the file "settling" and a short bounded timer confirms
+ * completion via `isTransformed` before emitting. (A module nothing
+ * re-requests never re-transforms — its `transformed` event waits for
+ * the next render, which is also when the graph has new information.)
+ */
+export function makeGraphUpdateChannel(
+  ctx: Pick<PluginContext, 'root' | 'config'>,
+  send: (payload: { type: 'custom'; event: string; data: unknown }) => void,
+  isTransformed?: IsNodeTransformed,
+  // Maps a watcher/hook path into the module graphs' path space (the
+  // dev-server passes a preserveSymlinks-aware realpath). Watcher
+  // events can carry the symlink path while transform ids carry the
+  // physical one — unkeyed by a common canonical form, the pending
+  // entry would never match its own transform.
+  canonicalize: (file: string) => string = (file) => file
+): GraphUpdateChannel {
+  /** Files invalidated but not yet re-transformed, per environment. */
+  const pending = new Set<string>();
+  const key = (file: string, environment: string) => `${environment}\0${file}`;
+  // The root goes through the same canonicalization as the files it
+  // contains — containment checks must compare in one path space.
+  const root = normalizePath(canonicalize(ctx.root));
+  const extensions = buildSourceExtensions(ctx.config.pageExtensions);
+
+  const emitTransformed = (file: string, environment: string, structural?: boolean) => {
+    send({
+      type: 'custom',
+      event: GRAPH_UPDATE_EVENT,
+      data: structural
+        ? { file, event: 'update', environment, phase: 'transformed', structural: true }
+        : { file, event: 'update', environment, phase: 'transformed' },
+    });
+  };
+
+  /**
+   * Confirm the transform request finished (transformResult set again)
+   * before emitting phase `transformed`. If confirmation never arrives
+   * within the bounded schedule below, the pending key is RE-ARMED
+   * rather than emitted — a `transformed` event over a still-stale
+   * graph would be a false all-clear with no corrective event.
+   */
+  /**
+   * Delays between confirmation re-checks: dense while a normal
+   * transform request finishes, then exponential backoff for slow
+   * import-analysis passes (large graphs, cold dep optimizer) — a
+   * completed slow transform is CACHED, so no later transform hook may
+   * ever fire for it and the tail checks are the only chance to emit.
+   * Total window ≈ 16 s, then give up (bounded — the async-safety
+   * rules ban open-ended polling) and re-arm the pending key.
+   */
+  const CONFIRM_DELAYS_MS = [
+    ...Array.from({ length: 25 }, () => 20),
+    500,
+    1_000,
+    2_000,
+    4_000,
+    8_000,
+  ];
+
+  const confirmAndEmit = (file: string, environment: string, attempt = 0, structural = false) => {
+    if (!isTransformed || isTransformed(file, environment)) {
+      emitTransformed(file, environment, structural);
+      return;
+    }
+    if (attempt >= CONFIRM_DELAYS_MS.length) {
+      // Structural (virtual-id) updates have no pending-key cycle to
+      // re-arm; project files wait for their next transform.
+      if (!structural) pending.add(key(file, environment));
+      return;
+    }
+    setTimeout(
+      () => confirmAndEmit(file, environment, attempt + 1, structural),
+      CONFIRM_DELAYS_MS[attempt]
+    );
+  };
+
+  return {
+    onHotUpdate(update) {
+      // The scanner's FULL admission rules, not just the extension —
+      // otherwise the channel pushes updates for files the endpoint
+      // itself 404s (node_modules, dist, .d.ts, dot-dirs) and editor
+      // consumers refresh into dead ends. Deletes canonicalize too:
+      // the dev-server's canonicalizer falls back to resolving the
+      // parent directory when the file itself is gone.
+      const file = normalizePath(canonicalize(update.file));
+      if (!isScannableSourceFile(file, root, extensions)) return;
+      if (update.type === 'delete') {
+        // Deleted files never re-transform; no second phase to track.
+        pending.delete(key(file, update.environment));
+      } else {
+        pending.add(key(file, update.environment));
+      }
+      send({
+        type: 'custom',
+        event: GRAPH_UPDATE_EVENT,
+        data: {
+          file,
+          event: update.type,
+          environment: update.environment,
+          phase: 'invalidated',
+        },
+      });
+    },
+    onTransform(id, environment) {
+      const file = normalizePath(id.split('?')[0]);
+      // Structural change: the route manifest re-transforms when routes
+      // are added/removed (its dynamic-import edges are what connect
+      // new route files to the graph). The new FILE itself may not
+      // transform until visited, so per-file tracking cannot see this —
+      // emit a structural notification, through the same confirmation
+      // gate (the manifest's own edges are also rebuilt only by the
+      // trailing import-analysis; the accessor resolves virtual ids).
+      if (file.includes('virtual:timber-route-manifest')) {
+        confirmAndEmit(file, environment, 25, true);
+        return;
+      }
+      const pendingKey = key(file, environment);
+      if (!pending.has(pendingKey)) return;
+      pending.delete(pendingKey);
+      confirmAndEmit(file, environment);
+    },
+  };
+}