hookherald 0.4.0 → 0.6.0

package/bin/hh

@@ -7,4 +7,8 @@ while [ -L "$SELF" ]; do
   case "$SELF" in /*) ;; *) SELF="$DIR/$SELF" ;; esac
 done
 SCRIPT_DIR="$(cd "$(dirname "$SELF")" && pwd)"
-exec npx tsx "$SCRIPT_DIR/../src/cli.ts" "$@"
+PKG_DIR="$SCRIPT_DIR/.."
+
+# Use node --import directly instead of npx tsx for faster startup
+TSX_LOADER="$PKG_DIR/node_modules/tsx/dist/esm/index.mjs"
+exec node --import "$TSX_LOADER" "$PKG_DIR/src/cli.ts" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookherald",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Webhook relay for Claude Code — push notifications from any HTTP POST into running sessions",
   "type": "module",
   "license": "MIT",

package/src/observability.ts

@@ -38,6 +38,7 @@ export interface WatcherConfig {
 export interface RouteInfo {
   port: number;
   registeredAt: string;
+  lastHeartbeatAt: number;
   lastEventAt: string | null;
   eventCount: number;
   errorCount: number;
@@ -283,3 +284,22 @@ export function truncatePayload(payload: any): any {
 export function newEventId(): string {
   return randomUUID();
 }
+
+// --- Event factory ---
+
+export function createRouterEvent(
+  type: RouterEvent["type"],
+  slug: string,
+  overrides: Partial<RouterEvent> = {},
+): RouterEvent {
+  return {
+    id: newEventId(),
+    timestamp: new Date().toISOString(),
+    type,
+    slug,
+    routingDecision: null,
+    durationMs: 0,
+    responseStatus: 200,
+    ...overrides,
+  };
+}

package/src/webhook-channel.ts

@@ -2,7 +2,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "node:http";
 import { readFileSync, watch as fsWatch, type FSWatcher } from "node:fs";
-import { execSync } from "node:child_process";
+import { execFile } from "node:child_process";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createLogger, type WatcherConfig } from "./observability.js";
@@ -56,8 +56,17 @@ const httpServer = createServer(async (req, res) => {
 
   const traceId = req.headers["x-trace-id"] as string | undefined;
 
+  const MAX_BODY = 1024 * 1024; // 1MB
   const chunks: Buffer[] = [];
-  for await (const chunk of req) chunks.push(chunk as Buffer);
+  let size = 0;
+  for await (const chunk of req) {
+    size += (chunk as Buffer).length;
+    if (size > MAX_BODY) {
+      res.writeHead(413).end("Payload too large");
+      return;
+    }
+    chunks.push(chunk as Buffer);
+  }
   const rawBody = Buffer.concat(chunks).toString();
 
   let payload: any;
@@ -146,16 +155,16 @@ function readConfig(): { slug: string; router_url: string; watchers: WatcherConf
   }
 }
 
-function executeCommand(cmd: string): string {
-  try {
-    return execSync(cmd, { encoding: "utf-8", shell: true, stdio: ["pipe", "pipe", "pipe"], timeout: 60000 }).trim();
-  } catch (err: any) {
-    return (err.stdout || "").trim();
-  }
+function executeCommand(cmd: string): Promise<string> {
+  return new Promise((resolve) => {
+    execFile("sh", ["-c", cmd], { encoding: "utf-8", timeout: 60000 }, (err, stdout) => {
+      resolve((stdout || "").trim());
+    });
+  });
 }
 
 async function runWatcher(watcher: WatcherConfig) {
-  const output = executeCommand(watcher.command);
+  const output = await executeCommand(watcher.command);
   if (!output) return;
 
   let parsed: any;
@@ -206,8 +215,8 @@ function startWatchers(watchers: WatcherConfig[]) {
     const key = watcherKey(w);
     if (watcherIntervals.has(key)) continue;
 
-    // Run immediately, then on interval
-    runWatcher(w);
+    // Run immediately (if registered), then on interval
+    if (registered) runWatcher(w);
     const timer = setInterval(() => runWatcher(w), w.interval * 1000);
     timer.unref();
     watcherIntervals.set(key, timer);
@@ -217,10 +226,12 @@ function startWatchers(watchers: WatcherConfig[]) {
   currentWatcherConfigs = watchers;
 }
 
-function loadAndStartWatchers() {
+async function loadAndStartWatchers() {
   const config = readConfig();
   const watchers = config?.watchers || [];
   startWatchers(watchers);
+  // Re-register so the router sees the updated watcher list
+  if (registered) await register();
 }
 
 function startConfigWatcher() {
@@ -256,9 +267,17 @@ httpServer.listen(0, "127.0.0.1", async () => {
   assignedPort = typeof addr === "object" && addr ? addr.port : 0;
   log.info("HTTP server listening", { host: "127.0.0.1", port: assignedPort });
 
-  loadAndStartWatchers();
-  startConfigWatcher();
+  // Load watcher configs (but don't start them yet)
+  const config = readConfig();
+  currentWatcherConfigs = config?.watchers || [];
+
+  // Register first so watchers can POST immediately
   await register();
+
+  // Now start watchers — they'll run immediately since we're registered
+  startWatchers(currentWatcherConfigs);
+
+  startConfigWatcher();
   startHeartbeat();
 });
 

package/src/webhook-router.ts

@@ -10,6 +10,7 @@ import {
   createTrace,
   truncatePayload,
   newEventId,
+  createRouterEvent,
   type RouteInfo,
   type RouterEvent,
 } from "./observability.js";
@@ -24,8 +25,14 @@ const HOST = process.env.ROUTER_HOST || "127.0.0.1";
 const SECRET = process.env.WEBHOOK_SECRET || "";
 
 function safeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  if (bufA.length !== bufB.length) {
+    // Compare against self to burn constant time, then return false
+    timingSafeEqual(bufA, bufA);
+    return false;
+  }
+  return timingSafeEqual(bufA, bufB);
 }
 
 const log = createLogger("router");
@@ -58,6 +65,15 @@ async function readBody(req: IncomingMessage): Promise<string> {
   return Buffer.concat(chunks).toString();
 }
 
+// --- Slug validation ---
+
+const SLUG_PATTERN = /^[\w\-\.\/]+$/;
+const MAX_SLUG_LENGTH = 200;
+
+function isValidSlug(slug: string): boolean {
+  return slug.length <= MAX_SLUG_LENGTH && SLUG_PATTERN.test(slug);
+}
+
 // --- Route helpers ---
 
 function getRoutesSnapshot() {
@@ -81,10 +97,16 @@ async function handleRegister(req: IncomingMessage, res: ServerResponse) {
     res.end(JSON.stringify({ error: "missing project_slug or port" }));
     return;
   }
+  if (!isValidSlug(project_slug)) {
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "invalid project_slug format" }));
+    return;
+  }
 
   // Heartbeat: if same slug and same port, treat as keepalive
   const existing = routes.get(project_slug);
   if (existing && existing.port === port) {
+    existing.lastHeartbeatAt = Date.now();
     // Update watchers on heartbeat (supports hot reload)
     if (watchers && JSON.stringify(watchers) !== JSON.stringify(existing.watchers)) {
       existing.watchers = watchers;
@@ -98,6 +120,7 @@ async function handleRegister(req: IncomingMessage, res: ServerResponse) {
   const info: RouteInfo = {
     port,
     registeredAt: new Date().toISOString(),
+    lastHeartbeatAt: Date.now(),
     lastEventAt: null,
     eventCount: 0,
     errorCount: 0,
@@ -108,16 +131,7 @@ async function handleRegister(req: IncomingMessage, res: ServerResponse) {
   metrics.registrations++;
   log.info("registered", { slug: project_slug, port });
 
-  const event: RouterEvent = {
-    id: newEventId(),
-    timestamp: new Date().toISOString(),
-    type: "register",
-    slug: project_slug,
-    routingDecision: null,
-    downstreamPort: port,
-    durationMs: 0,
-    responseStatus: 200,
-  };
+  const event = createRouterEvent("register", project_slug, { downstreamPort: port });
   events.push(event);
   broadcast("session", { sessions: getSessionsData() });
   broadcast("webhook", event);
@@ -146,15 +160,7 @@ async function handleUnregister(req: IncomingMessage, res: ServerResponse) {
   metrics.unregistrations++;
   log.info("unregistered", { slug: project_slug });
 
-  const event: RouterEvent = {
-    id: newEventId(),
-    timestamp: new Date().toISOString(),
-    type: "unregister",
-    slug: project_slug,
-    routingDecision: null,
-    durationMs: 0,
-    responseStatus: 200,
-  };
+  const event = createRouterEvent("unregister", project_slug);
   events.push(event);
   broadcast("session", { sessions: getSessionsData() });
   broadcast("webhook", event);
@@ -182,17 +188,14 @@ async function handleWebhook(req: IncomingMessage, res: ServerResponse) {
       metrics.recordRequest(401);
       metrics.recordWebhook("unauthorized");
 
-      const ev: RouterEvent = {
+      const ev = createRouterEvent("webhook", "unknown", {
         id: traceId,
-        timestamp: new Date().toISOString(),
-        type: "webhook",
-        slug: "unknown",
         routingDecision: "unauthorized",
         durationMs: trace.elapsed(),
         responseStatus: 401,
         traceSpans: trace.spans,
         error: "invalid token",
-      };
+      });
       events.push(ev);
       broadcast("webhook", ev);
 
@@ -214,17 +217,14 @@ async function handleWebhook(req: IncomingMessage, res: ServerResponse) {
     metrics.recordRequest(400);
     metrics.recordWebhook("invalid");
 
-    const ev: RouterEvent = {
+    const ev = createRouterEvent("webhook", "unknown", {
       id: traceId,
-      timestamp: new Date().toISOString(),
-      type: "webhook",
-      slug: "unknown",
       routingDecision: "invalid",
       durationMs: trace.elapsed(),
       responseStatus: 400,
       traceSpans: trace.spans,
       error: "invalid JSON",
-    };
+    });
     events.push(ev);
     broadcast("webhook", ev);
 
@@ -239,18 +239,15 @@ async function handleWebhook(req: IncomingMessage, res: ServerResponse) {
     metrics.recordRequest(400);
     metrics.recordWebhook("invalid");
 
-    const ev: RouterEvent = {
+    const ev = createRouterEvent("webhook", "unknown", {
       id: traceId,
-      timestamp: new Date().toISOString(),
-      type: "webhook",
-      slug: "unknown",
       routingDecision: "invalid",
       payload: truncatePayload(payload),
       durationMs: trace.elapsed(),
       responseStatus: 400,
       traceSpans: trace.spans,
       error: "missing project_slug",
-    };
+    });
     events.push(ev);
     broadcast("webhook", ev);
 
@@ -259,6 +256,27 @@ async function handleWebhook(req: IncomingMessage, res: ServerResponse) {
     return;
   }
 
+  if (!isValidSlug(slug)) {
+    metrics.recordRequest(400);
+    metrics.recordWebhook("invalid");
+
+    const ev = createRouterEvent("webhook", "unknown", {
+      id: traceId,
+      routingDecision: "invalid",
+      payload: truncatePayload(payload),
+      durationMs: trace.elapsed(),
+      responseStatus: 400,
+      traceSpans: trace.spans,
+      error: "invalid project_slug format",
+    });
+    events.push(ev);
+    broadcast("webhook", ev);
+
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "invalid project_slug format" }));
+    return;
+  }
+
   // Route lookup
   const routeSpan = trace.span("route_lookup");
   const routeInfo = routes.get(slug);
@@ -270,17 +288,14 @@ async function handleWebhook(req: IncomingMessage, res: ServerResponse) {
     metrics.recordRequest(404);
     metrics.recordWebhook("no_route", slug, durationMs);
 
-    const ev: RouterEvent = {
+    const ev = createRouterEvent("webhook", slug, {
       id: traceId,
-      timestamp: new Date().toISOString(),
-      type: "webhook",
-      slug,
       routingDecision: "no_route",
       payload: truncatePayload(payload),
       durationMs,
       responseStatus: 404,
       traceSpans: trace.spans,
-    };
+    });
     events.push(ev);
     broadcast("webhook", ev);
 
@@ -311,11 +326,8 @@ async function handleWebhook(req: IncomingMessage, res: ServerResponse) {
     metrics.recordWebhook("forwarded", slug, durationMs);
     log.info("forwarded", { slug, port: routeInfo.port, status: resp.status, durationMs, traceId });
 
-    const ev: RouterEvent = {
+    const ev = createRouterEvent("webhook", slug, {
       id: traceId,
-      timestamp: new Date().toISOString(),
-      type: "webhook",
-      slug,
       routingDecision: "forwarded",
       downstreamPort: routeInfo.port,
       downstreamStatus: resp.status,
@@ -324,7 +336,7 @@ async function handleWebhook(req: IncomingMessage, res: ServerResponse) {
       forwardDurationMs: fwdSpan.durationMs,
       responseStatus: 200,
       traceSpans: trace.spans,
-    };
+    });
     events.push(ev);
     broadcast("webhook", ev);
     broadcast("session", { sessions: getSessionsData() });
@@ -341,11 +353,8 @@ async function handleWebhook(req: IncomingMessage, res: ServerResponse) {
     metrics.recordWebhook("downstream_error", slug, durationMs);
     log.error("forward failed", { slug, port: routeInfo.port, error: err.message, traceId });
 
-    const ev: RouterEvent = {
+    const ev = createRouterEvent("webhook", slug, {
       id: traceId,
-      timestamp: new Date().toISOString(),
-      type: "webhook",
-      slug,
       routingDecision: "forwarded",
       downstreamPort: routeInfo.port,
       payload: truncatePayload(payload),
@@ -354,7 +363,7 @@ async function handleWebhook(req: IncomingMessage, res: ServerResponse) {
       responseStatus: 502,
       traceSpans: trace.spans,
       error: err.message,
-    };
+    });
     events.push(ev);
     broadcast("webhook", ev);
     broadcast("session", { sessions: getSessionsData() });
@@ -435,6 +444,26 @@ const statsInterval = setInterval(() => {
 }, 5000);
 statsInterval.unref();
 
+// Stale route cleanup: remove routes that missed 3 heartbeat intervals
+const HEARTBEAT_MS = parseInt(process.env.HH_HEARTBEAT_MS || "30000", 10);
+const STALE_THRESHOLD_MS = HEARTBEAT_MS * 3;
+
+const staleInterval = setInterval(() => {
+  const now = Date.now();
+  let changed = false;
+  for (const [slug, info] of routes) {
+    if (now - info.lastHeartbeatAt > STALE_THRESHOLD_MS) {
+      routes.delete(slug);
+      metrics.unregistrations++;
+      log.warn("reaped stale route", { slug, lastHeartbeatAgoMs: now - info.lastHeartbeatAt });
+      events.push(createRouterEvent("unregister", slug));
+      changed = true;
+    }
+  }
+  if (changed) broadcast("session", { sessions: getSessionsData() });
+}, STALE_THRESHOLD_MS);
+staleInterval.unref();
+
 function handleApiHealth(_req: IncomingMessage, res: ServerResponse) {
   res.writeHead(200, { "Content-Type": "application/json" });
   res.end(JSON.stringify({
@@ -481,15 +510,7 @@ async function handleApiKill(req: IncomingMessage, res: ServerResponse) {
   routes.delete(project_slug);
   log.info("killed", { slug: project_slug, port: routeInfo.port });
 
-  events.push({
-    id: newEventId(),
-    timestamp: new Date().toISOString(),
-    type: "unregister",
-    slug: project_slug,
-    routingDecision: null,
-    durationMs: 0,
-    responseStatus: 200,
-  });
+  events.push(createRouterEvent("unregister", project_slug));
   broadcast("session", { sessions: getSessionsData() });
 
   res.writeHead(200, { "Content-Type": "application/json" });