hookherald 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookherald",
-  "version": "0.5.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

@@ -284,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

@@ -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;
@@ -258,11 +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();
-  // Run watchers that were deferred during startup (before registration)
-  for (const w of currentWatcherConfigs) runWatcher(w);
+
+  // 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";
@@ -64,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() {
@@ -87,6 +97,11 @@ 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);
@@ -116,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);
@@ -154,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);
@@ -190,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);
 
@@ -222,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);
 
@@ -247,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);
 
@@ -267,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);
@@ -278,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);
 
@@ -319,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,
@@ -332,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() });
@@ -349,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),
@@ -362,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() });
@@ -455,15 +456,7 @@ const staleInterval = setInterval(() => {
       routes.delete(slug);
       metrics.unregistrations++;
       log.warn("reaped stale route", { slug, lastHeartbeatAgoMs: now - info.lastHeartbeatAt });
-      events.push({
-        id: newEventId(),
-        timestamp: new Date().toISOString(),
-        type: "unregister",
-        slug,
-        routingDecision: null,
-        durationMs: 0,
-        responseStatus: 200,
-      });
+      events.push(createRouterEvent("unregister", slug));
       changed = true;
     }
   }
@@ -517,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" });