sparkforensics-cli 0.1.0

package/vendor-core/plan-node-detail.js

@@ -0,0 +1,159 @@
+// Per-operator plan-node rendering helpers for the stage-detail modal's
+// hierarchical plan tree. Ported near-verbatim from the legacy canvas widget
+// (src/widgets/stage-detail.js, deleted at 1db5365): pure string-parsing /
+// tree-walking logic, no DOM. Per AGENTS.md, plan-text parsing is
+// best-effort: unparseable fragments are silently skipped, never thrown.
+
+import { pathBasename, formatBytes, formatDuration } from './format-utils.js';
+import { attributeStageDurationToPlan } from './plan-duration-attribution.js';
+import { stageIdsForSqlExec } from './detectors.js';
+                                                                   
+
+const BOILERPLATE_PREFIXES = ['serializefromobject', 'deserializetoobject', 'mapelements',
+  'mappartitions', 'inputadapter', 'columnartorow', 'rowtocolumnar', 'union'];
+
+export function classifyNode(
+  name        ,
+)                                                                                                       {
+  const n = (name ?? '').toLowerCase();
+  if (n.startsWith('scan')) return 'scan';
+  if (n.includes('exchange')) return 'exchange';
+  if (n.includes('join')) return 'join';
+  if (n.includes('aggregate')) return 'aggregate';
+  if (n.startsWith('sort')) return 'sort';
+  if (n.startsWith('filter')) return 'filter';
+  if (n === 'adaptivesparkplan') return 'aqe';
+  if (BOILERPLATE_PREFIXES.some(b => n.startsWith(b)) || n.startsWith('wholestagecodegen')) return 'boilerplate';
+  return 'transform';
+}
+
+export function parseOperatorDetail(name        , simpleString        )         {
+  if (!simpleString || simpleString === name) return '';
+  const n = (name ?? '').toLowerCase();
+  const stripAliases = (s        ) => s.replace(/#\d+/g, '');
+
+  if (BOILERPLATE_PREFIXES.some(b => n.startsWith(b))) return '';
+  if (n === 'adaptivesparkplan') return '';
+  if (n.startsWith('wholestagecodegen')) {
+    const m = name.match(/\((\d+)\)/);
+    return m ? `codegen #${m[1]}` : '';
+  }
+
+  if (n.includes('exchange')) {
+    const m = simpleString.match(/Exchange\s+(\w+partitioning)\(([^)]+)\)/i);
+    if (m) {
+      const type = m[1].toLowerCase().startsWith('hash') ? 'hash' : 'range';
+      const args = stripAliases(m[2]).split(',').map(s => s.trim());
+      const lastIsNum = /^\d+$/.test(args[args.length - 1]);
+      const partCount = lastIsNum ? args.pop() : null;
+      const keys = args.map(k =>
+        k.replace(/\s+ASC(\s+NULLS\s+\w+)?$/i, '↑')
+         .replace(/\s+DESC(\s+NULLS\s+\w+)?$/i, '↓').trim()
+      ).slice(0, 3);
+      return `${type}(${keys.join(', ')}${partCount ? `, ${partCount}` : ''})`;
+    }
+    const singleM = simpleString.match(/Exchange\s+(\w+)/);
+    return singleM ? singleM[1] : '';
+  }
+
+  if (n.startsWith('sort') && !n.includes('merge')) {
+    const m = simpleString.match(/Sort\s+\[([^\]]+)\]/);
+    if (m) {
+      return stripAliases(m[1]).split(',').map(s =>
+        s.trim()
+         .replace(/\s+ASC(\s+NULLS\s+\w+)?$/i, '↑')
+         .replace(/\s+DESC(\s+NULLS\s+\w+)?$/i, '↓')
+      ).slice(0, 4).join(', ');
+    }
+  }
+
+  if (n.includes('join')) {
+    const m = simpleString.match(/Join\s+\[([^\]]*)\][^,]*,\s*\[[^\]]*\][^,]*,\s*(\w+)/i);
+    if (m) {
+      const leftKey = stripAliases(m[1]).split(',')[0].trim();
+      return leftKey ? `${leftKey}  ${m[2]}` : m[2];
+    }
+  }
+
+  if (n.includes('aggregate')) {
+    const funcM = simpleString.match(/functions=\[([^\]]+)\]/);
+    if (funcM) {
+      const funcs = [...new Set(
+        funcM[1].split(',').map(f => (f.trim().match(/^(\w+)\(/)?.[1] ?? '').replace(/^partial_/, ''))
+      )].filter(Boolean);
+      return funcs.slice(0, 5).join(', ') + (funcs.length > 5 ? ` +${funcs.length - 5}` : '');
+    }
+  }
+
+  if (n.startsWith('filter')) {
+    const m = simpleString.match(/Filter\s+(.+)/s);
+    if (m) {
+      const expr = stripAliases(m[1]).trim().replace(/^\((.+)\)$/s, '$1');
+      return expr.length > 70 ? expr.slice(0, 70) + '…' : expr;
+    }
+  }
+
+  if (n.startsWith('project')) {
+    const m = simpleString.match(/Project\s+\[([^\]]+)\]/);
+    if (m) {
+      const cols = stripAliases(m[1]).split(',').map(s => s.trim());
+      if (cols.length <= 3) return cols.join(', ');
+      return `${cols.length} columns`;
+    }
+    return '';
+  }
+
+  if (n.startsWith('scan')) {
+    if (n.includes('existingrdd')) {
+      const short = pathBasename(name);
+      if (short !== name) return short;
+    }
+    const fmtM = name.match(/Scan\s+(\S+)/);
+    return fmtM ? fmtM[1] : '';
+  }
+
+  const stripped = stripAliases(simpleString);
+  return stripped.length > 80 ? stripped.slice(0, 80) + '…' : stripped;
+}
+
+export function formatMetricValue(metric                                                 )         {
+  const { value, metricType } = metric;
+  if (typeof value === 'string') return value;
+  if (metricType === 'size') return formatBytes(value);
+  if (metricType === 'timing') return formatDuration(value);
+  if (metricType === 'nsTiming') return formatDuration(value / 1_000_000);
+  return value.toLocaleString('en-US');
+}
+
+export function getPrimaryMetric(
+  metrics                                                                                  ,
+)         {
+  if (!metrics || metrics.length === 0) return '';
+  const priority = ['number of output rows', 'size of files read', 'spill size', 'duration'];
+  const found = priority.map(n => metrics.find(m => m.name === n)).find(Boolean) ?? metrics[0];
+  return formatMetricValue(found);
+}
+
+// Approximate per-node wall-time (dataflint-style segment attribution): see
+// attributeStageDurationToPlan. Returns null when there's nothing to attribute
+// (no plan tree, or the SQL execution doesn't carry a stageIds list).
+export function buildDurationMap(
+  planTree                 ,
+  appModel          ,
+  sqlExec              ,
+  executionId        ,
+)                               {
+  if (!planTree || !sqlExec) return null;
+  const stageIds           = stageIdsForSqlExec(executionId, appModel.stages);
+  if (!stageIds.length) return null;
+  const stagesById = new Map                                                        ();
+  for (const id of stageIds) {
+    const s = appModel.stages.get(id);
+    if (s) stagesById.set(id, { submittedAt: s.submittedAt, completedAt: s.completedAt });
+  }
+  // attributeStageDurationToPlan still reads its 3rd arg's own `.stageIds`
+  // field internally (Task 2 didn't change that signature); override it
+  // with the derived array rather than the (always-empty, on real data)
+  // one already on `sqlExec`, without needing to change that function.
+  return attributeStageDurationToPlan(planTree, stagesById, { ...sqlExec, stageIds });
+}

package/vendor-core/plan-summary.js

@@ -0,0 +1,233 @@
+// Best-effort summary of a resolved plan tree (parser-worker `resolvePlanTree`).
+// Per AGENTS.md the plan surface is best-effort: unparseable fragments are
+// silently skipped, never surfaced as an error. This replaces the old regex
+// `plan-extractor.js`: the single plan representation is the tree.
+
+                                           
+import { pathBasename } from './format-utils.js';
+import { walkPlanTree } from './plan-tree-walk.js';
+
+                                                                                                                             
+                                                                                       
+                                                                          
+                                                                                                                                 
+                                                                                          
+
+                       
+                   
+                   
+                 
+                           
+                         
+ 
+
+function cleanColRef(ref        )         { return ref.trim().replace(/#\w+$/, ''); }
+
+function parseColList(bracketed        )           {
+  return bracketed.replace(/^\[|\]$/g, '').split(',').map(cleanColRef).filter(Boolean);
+}
+
+function splitTopLevel(s        )           {
+  const parts           = []; let depth = 0, start = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '(') depth++;
+    else if (s[i] === ')') depth--;
+    else if (s[i] === ',' && depth === 0) { parts.push(s.slice(start, i).trim()); start = i + 1; }
+  }
+  parts.push(s.slice(start).trim());
+  return parts.filter(Boolean);
+}
+
+function pushCrossJoinWarning(result             , label        )       {
+  result.warnings.push({ type: 'crossJoin', detail: `${label} detected: this can cause severe data explosion.` });
+}
+function pushLongFilterWarning(result             , len        )       {
+  result.warnings.push({ type: 'longFilterCondition', detail: `Filter condition is ${len} characters: consider simplifying or pushing the filter down closer to the scan.` });
+}
+
+// Stable relation-identity key for a scan node: "<format>:<relation>" (e.g.
+// "delta:mx.t_emp_whitelist", "parquet:business_prd.sales", "jdbc:dw.d_producto")
+// or null when the node is internal Delta metadata / a non-scan / un-nameable.
+// The single source of truth for scan identity, shared by `visitScan` (summary)
+// and the `cachingOpportunity` detector so the regexes live in one place.
+export function scanRelationId(name        , detail        )                {
+  // 1. Named catalog table, untruncated, from the nodeName (the key fix; the
+  //    Location: path is truncated at ~100 chars and points at _delta_log for
+  //    Delta tables). All catalog tables surface as `spark_catalog.<db>.<table>`.
+  let format = null, table = null;
+  const nameM = name.match(/^Scan\s+(parquet|orc|csv|json)\s+(spark_catalog\.\S+)$/i);
+  if (nameM) { format = nameM[1].toLowerCase(); table = nameM[2]; }
+  else {
+    const detM = detail.match(/FileScan\s+(parquet|orc|csv|json)\s+(spark_catalog\.[^[\s]+)\[/i);
+    if (detM) { format = detM[1].toLowerCase(); table = detM[2]; }
+  }
+  if (table) {
+    // A Delta data read keeps its Delta index marker; report format `delta`.
+    if (/PreparedDeltaFileIndex/i.test(detail)) format = 'delta';
+    return `${format}:${table.replace(/^spark_catalog\./, '')}`;
+  }
+
+  // 2. Internal Delta metadata (the _delta_log state scan and anonymous
+  //    commit/checkpoint reads) → null. Location: is often truncated to `Del...`,
+  //    so also key off DeltaLogFileIndex or the Delta-log action column signature.
+  //    ponytail: column-signature heuristic; a future Spark that renames those
+  //    action columns would leak a noise row; acceptable, verified clean on all 9 logs.
+  if (/_delta_log/.test(name) || /_delta_log/.test(detail) ||
+      /DeltaLogFileIndex/i.test(name + detail) ||
+      /checkpointMetadata#|sidecar#|commitInfo#/.test(name + detail)) {
+    return null;
+  }
+
+  // 3. Anonymous real file read (InMemoryFileIndex, no catalog name) →
+  //    best-effort Location basename. Preserves temp/snapshot self-reuse; a
+  //    truncated Location can still fragment these; inherent, unrecoverable.
+  const fileM = detail.match(/FileScan\s+(parquet|orc|csv|json)\b/i);
+  if (fileM) {
+    const locM = detail.match(/Location:[^[]*\[([^\]]+)\]/);
+    if (!locM) return null;
+    return `${fileM[1].toLowerCase()}:${pathBasename(locM[1].split(',')[0].trim())}`;
+  }
+
+  // 4. JDBC: the inner SQL's first real table, lowercased. null when the first
+  //    post-FROM token is a subquery `(` or there is no single table (CTE/UNION).
+  if (/JDBCRelation/.test(detail)) {
+    const fromM = jdbcSql(detail).match(/\bFROM\s+(\(|[A-Za-z_][\w.]*)/i);
+    if (!fromM || fromM[1] === '(') return null;
+    return `jdbc:${fromM[1].toLowerCase()}`;
+  }
+
+  // 5. Non-scan / unrecognized.
+  return null;
+}
+
+// Extracts the inner SQL text from a JDBCRelation detail string (used for both
+// the relation table name and the scan's `sql` summary field).
+function jdbcSql(detail        )         {
+  const jdbcM = detail.match(/JDBCRelation\(([\s\S]+?)\)\s*(?:SPARK_GEN_SUBQ_\d+\)?)?\s*\[numPartitions/);
+  const sqlM = detail.match(/JDBCRelation\(\(([\s\S]+?)\)\s*SPARK_GEN_SUBQ/);
+  return (sqlM ? sqlM[1] : (jdbcM ? jdbcM[1] : '')).replace(/\s+/g, ' ').trim();
+}
+
+function visitScan(name        , detail        , result             )          {
+  // Identity (path + format) comes from the shared classifier; a null key means
+  // internal Delta metadata / an un-nameable read; no Sources bullet.
+  const rid = scanRelationId(name, detail);
+  if (!rid) return false;
+  const colon = rid.indexOf(':');
+  const format = rid.slice(0, colon);
+  const path = rid.slice(colon + 1);
+
+  if (format === 'jdbc') {
+    result.scans.push({ path, format, projectedColumns: [], pushedFilters: [], sql: jdbcSql(detail) });
+    return true;
+  }
+  // FileScan <fmt> [cols] ... PushedFilters: [...] (format may be `delta`).
+  const colsM = detail.match(/FileScan\s+\w+\s+(\[[^\]]*\])/i) ?? detail.match(/(\[[^\]]*\])/);
+  const filM = detail.match(/PushedFilters:\s*\[([^\]]*)\]/);
+  result.scans.push({
+    path,
+    format,
+    projectedColumns: colsM ? parseColList(colsM[1]) : [],
+    pushedFilters: filM && filM[1] ? filM[1].split(',').map(s => s.trim()).filter(Boolean) : [],
+  });
+  return true;
+}
+
+function visitJoin(_name        , detail        , result             )          {
+  // <JoinOp> [leftKeys], [rightKeys], <JoinType>[, BuildSide]
+  const m = detail.match(/^(SortMergeJoin|BroadcastHashJoin|ShuffledHashJoin|BroadcastNestedLoopJoin)\s+(\[[^\]]*\]),\s*(\[[^\]]*\]),\s*(\w+)/);
+  if (m) {
+    result.joins.push({ joinType: m[1], leftKeys: parseColList(m[2]), rightKeys: parseColList(m[3]) });
+    if (/^Cross$/i.test(m[4])) pushCrossJoinWarning(result, 'Cross join');
+    return true;
+  }
+  return false;
+}
+
+function visitAgg(_name        , detail        , result             )          {
+  const m = detail.match(/(?:Object)?HashAggregate\(keys=(\[[^\]]*\]),\s*functions=(\[[\s\S]*\])\)/);
+  if (!m) return false;
+  const funcs = m[2].replace(/^\[|\]$/g, '');
+  if (/\bpartial_/.test(funcs)) return true;   // skip partial pass
+  const aggregations = splitTopLevel(funcs).map(f => f.replace(/#\w+/g, '').trim()).filter(Boolean).slice(0, 8);
+  const groupByKeys = parseColList(m[1]);
+  if (groupByKeys.length || aggregations.length) result.aggs.push({ groupByKeys, aggregations });
+  return true;
+}
+
+function visitExchange(detail        , result             )       {
+  const h = detail.match(/hashpartitioning\((.+?),\s*(\d+)\)/i);
+  const r = detail.match(/rangepartitioning\((.+?),\s*(\d+)\)/i);
+  if (h) {
+    result.exchanges.push({ partitioning: 'hash', keys: splitTopLevel(h[1]).map(s => cleanColRef(s.replace(/\s+(ASC|DESC)(\s+NULLS\s+\w+)?/i, ''))).filter(Boolean), numPartitions: parseInt(h[2], 10) });
+  } else if (r) {
+    result.exchanges.push({ partitioning: 'range', keys: splitTopLevel(r[1]).map(s => cleanColRef(s.replace(/\s+(ASC|DESC)(\s+NULLS\s+\w+)?/i, ''))).filter(Boolean), numPartitions: parseInt(r[2], 10) });
+  } else if (/RoundRobinPartitioning/i.test(detail)) {
+    const n = detail.match(/RoundRobinPartitioning\((\d+)\)/i);
+    result.exchanges.push({ partitioning: 'roundrobin', keys: [], numPartitions: n ? parseInt(n[1], 10) : 0 });
+  } else if (/SinglePartition/i.test(detail)) {
+    result.exchanges.push({ partitioning: 'single', keys: [], numPartitions: 1 });
+  }
+}
+
+export function summarizePlanTree(planTree                 )              {
+  const result              = { scans: [], joins: [], aggs: [], exchanges: [], warnings: [] };
+  if (!planTree) return result;
+
+  walkPlanTree(planTree, (n) => {
+    const name = n.name ?? '';
+    const detail = n.detail ?? '';
+    if (/CartesianProduct/i.test(name) || /CartesianProduct/i.test(detail)) pushCrossJoinWarning(result, 'CartesianProduct');
+    else if (visitScan(name, detail, result)) { /* handled */ }
+    else if (/Join/i.test(name) && visitJoin(name, detail, result)) { /* handled */ }
+    else if (/Aggregate/i.test(name) && visitAgg(name, detail, result)) { /* handled */ }
+    else if (/^Exchange/i.test(name)) visitExchange(detail, result);
+    else if (/^Filter/i.test(name)) {
+      const condM = detail.match(/^Filter\s+([\s\S]+)/);
+      if (condM && condM[1].trim().length > 1000) pushLongFilterWarning(result, condM[1].trim().length);
+    }
+  }, { dedupe: true });
+  return result;
+}
+
+// Per-node structured detail: the same regex visitors as summarizePlanTree
+// (visitScan/visitJoin/visitAgg/visitExchange, plus the crossJoin/
+// longFilterCondition warning checks), scoped to a single node instead of
+// folded into a tree-wide array. Used to attach the flat summary's full
+// fields (every pushed filter, every join key, every partitioning key) to
+// the exact operator they describe, and to attach a plan-text warning to
+// the node that caused it instead of a disconnected list entry.
+export function describePlanNode(
+  node                 ,
+)                                                                                                                                                 {
+  if (!node) return null;
+  const name = node.name ?? '';
+  const detail = node.detail ?? '';
+  const result              = { scans: [], joins: [], aggs: [], exchanges: [], warnings: [] };
+
+  if (/CartesianProduct/i.test(name) || /CartesianProduct/i.test(detail)) {
+    pushCrossJoinWarning(result, 'CartesianProduct');
+  } else if (visitScan(name, detail, result)) {
+    // handled
+  } else if (/Join/i.test(name) && visitJoin(name, detail, result)) {
+    // handled (a Cross join type may also have pushed a crossJoin warning)
+  } else if (/Aggregate/i.test(name) && visitAgg(name, detail, result)) {
+    // handled (a partial-aggregation pass pushes nothing into result.aggs)
+  } else if (/^Exchange/i.test(name)) {
+    visitExchange(detail, result);
+  } else if (/^Filter/i.test(name)) {
+    const condM = detail.match(/^Filter\s+([\s\S]+)/);
+    if (condM && condM[1].trim().length > 1000) pushLongFilterWarning(result, condM[1].trim().length);
+  }
+
+  const kind = result.scans[0] ? 'scan'
+    : result.joins[0] ? 'join'
+    : result.aggs[0] ? 'agg'
+    : result.exchanges[0] ? 'exchange'
+    : null;
+  const fields = result.scans[0] ?? result.joins[0] ?? result.aggs[0] ?? result.exchanges[0] ?? null;
+  const warning = result.warnings[0] ?? null;
+
+  if (!kind && !warning) return null;
+  return { kind, warning, ...(fields ?? {}) };
+}

package/vendor-core/plan-tree-walk.js

@@ -0,0 +1,29 @@
+// Canonical iterative walk over a resolved planTree (parser-worker.js
+// resolvePlanTree). Every plan-*.js consumer and the sql-scope detectors in
+// detectors.js need the same traversal: this is the single implementation
+// they all share, so it must not import from detectors.js (or vice versa).
+//
+// Pre-order, left-to-right child order (children are reverse-pushed so the
+// leftmost pops first): plan-summary.js's finding order depends on this.
+// `visit(node, parent)` gets the parent so callers needing per-edge or
+// per-node state (plan-dot.js's edges, plan-duration-attribution.js's segment
+// index) can track it themselves via a Map keyed by node.
+export function walkPlanTree                              (
+  root                      ,
+  visit                                     ,
+  { dedupe = false }                       = {},
+)       {
+  if (!root) return;
+  const seen = dedupe ? new Set   () : null;
+  const stack                                  = [{ node: root, parent: null }];
+  while (stack.length > 0) {
+    const { node, parent } = stack.pop() ;
+    if (seen) {
+      if (seen.has(node)) continue;
+      seen.add(node);
+    }
+    visit(node, parent);
+    const children = node.children ?? [];
+    for (let i = children.length - 1; i >= 0; i--) stack.push({ node: children[i], parent: node });
+  }
+}

package/vendor-core/proxy.js

@@ -0,0 +1,157 @@
+import { Readable } from 'node:stream';
+import {
+  buildUpstreamUrl as buildNormalizedUpstreamUrl,
+  validateShsRequest,
+} from './shs-request.js';
+
+function sendSafeError(res, status, code) {
+  const body = JSON.stringify({ code });
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(body);
+}
+
+function isConnectionFailure(error) {
+  if (error?.name === 'AbortError' || error?.name === 'TimeoutError') return true;
+  const code = error?.code ?? error?.cause?.code;
+  if (['ECONNREFUSED', 'ECONNRESET', 'EHOSTUNREACH', 'ENETUNREACH', 'ENOTFOUND', 'ETIMEDOUT'].includes(code)) return true;
+  return /\b(?:ECONNREFUSED|ECONNRESET|EHOSTUNREACH|ENETUNREACH|ENOTFOUND|ETIMEDOUT)\b/.test(error?.message ?? '');
+}
+
+const DEFAULT_UPSTREAM_TIMEOUT_MS = 30_000;
+
+function upstreamTimeoutMs() {
+  const v = Number(process.env.SPARKFORENSICS_SHS_TIMEOUT_MS);
+  return Number.isFinite(v) && v > 0 ? v : DEFAULT_UPSTREAM_TIMEOUT_MS;
+}
+
+// CSRF guard: verifies the caller, not the proxy target (`normalizeBaseUrl`'s
+// private-network allowance is unrelated and deliberate). No Origin header
+// means a same-origin navigation or a non-browser client, so it's allowed;
+// an Origin present must match Host. Anything unparseable fails closed.
+export function isSameOriginRequest(req) {
+  const origin = req.headers?.origin;
+  if (origin == null) return true;
+
+  const host = req.headers?.host;
+  if (!host) return false;
+
+  let originHost;
+  try {
+    originHost = new URL(origin).host;
+  } catch {
+    return false;
+  }
+  return originHost.toLowerCase() === host.toLowerCase();
+}
+
+export async function fetchShsEventLog(request, { fetchImpl = fetch, timeoutMs = upstreamTimeoutMs() } = {}) {
+  const upstreamUrl = buildNormalizedUpstreamUrl(request);
+  // Header-phase timeout only: the timer is cleared once headers arrive, so a
+  // slow-but-progressing body download is never cut off mid-stream (the body
+  // gets its own idle watchdog in handleShsProxy).
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let upstream;
+  try {
+    upstream = await fetchImpl(upstreamUrl, { redirect: 'error', credentials: 'omit', signal: controller.signal });
+  } catch (error) {
+    return { ok: false, code: isConnectionFailure(error) ? 'upstream-unreachable' : 'access-or-upstream-failure' };
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!upstream?.ok) {
+    return { ok: false, code: upstream?.status === 404 ? 'application-not-found' : 'access-or-upstream-failure' };
+  }
+  if (!upstream.body) {
+    return { ok: false, code: 'access-or-upstream-failure' };
+  }
+  return { ok: true, upstream };
+}
+
+export async function handleShsProxy(req, res, { fetchImpl = fetch, timeoutMs = upstreamTimeoutMs() } = {}) {
+  if (!isSameOriginRequest(req)) {
+    sendSafeError(res, 403, 'access-or-upstream-failure');
+    return;
+  }
+
+  const query = new URL(req.url, 'http://localhost').searchParams;
+  const result = validateShsRequest({
+    baseUrl: query.get('baseUrl') ?? '',
+    appId: query.get('appId') ?? '',
+    attemptId: query.get('attemptId') ?? '',
+  });
+
+  if (!result.request) {
+    sendSafeError(res, 400, 'access-or-upstream-failure');
+    return;
+  }
+
+  const fetched = await fetchShsEventLog(result.request, { fetchImpl, timeoutMs });
+  if (!fetched.ok) {
+    sendSafeError(res, 502, fetched.code);
+    return;
+  }
+
+  const { upstream } = fetched;
+  let nodeStream;
+  try {
+    nodeStream = Readable.fromWeb(upstream.body);
+  } catch {
+    sendSafeError(res, 502, 'access-or-upstream-failure');
+    return;
+  }
+
+  const headers = {};
+  const contentLength = upstream.headers.get('content-length');
+  if (contentLength) headers['content-length'] = contentLength;
+  headers['content-type'] = 'application/zip';
+  res.writeHead(200, headers);
+
+  await new Promise((resolve) => {
+    // Idle watchdog: a stalled upstream would otherwise leave this promise
+    // pending forever with the 200 already sent. Resets on every chunk, so
+    // slow-but-progressing downloads of any size are unaffected.
+    let watchdog;
+    let settled = false;
+    const resetWatchdog = () => {
+      clearTimeout(watchdog);
+      watchdog = setTimeout(() => nodeStream.destroy(new Error('upstream idle timeout')), timeoutMs);
+    };
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(watchdog);
+      resolve();
+    };
+    resetWatchdog();
+    nodeStream.on('data', resetWatchdog);
+    nodeStream.on('error', (err) => {
+      if (settled) return;
+      console.warn(`[shs-proxy] upstream stream failed mid-body: ${err.message}`);
+      // destroy(err), not destroy(): the 200 header is already out, so an
+      // abnormal termination is the only signal that the body is truncated.
+      res.destroy(err);
+      finish();
+    });
+    // Mirrors the nodeStream-error path in the other direction: a client
+    // disconnecting mid-transfer (res 'close') or a write failure (res
+    // 'error') must also settle this promise (resolve, same as the
+    // nodeStream-error path above) and stop the now-pointless upstream read,
+    // or it dangles until the idle watchdog eventually fires. `res` 'close'
+    // also fires after a normal 'finish', so the `settled` guard keeps that
+    // happy-path case a no-op.
+    res.on('error', (err) => {
+      if (settled) return;
+      console.warn(`[shs-proxy] client connection failed mid-body: ${err.message}`);
+      nodeStream.destroy(err);
+      finish();
+    });
+    res.on('close', () => {
+      if (settled) return;
+      nodeStream.destroy();
+      finish();
+    });
+    res.on('finish', finish);
+    nodeStream.pipe(res);
+  });
+}