@mulmobridge/webhook-runtime 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import crypto from "crypto";
+import type { Server } from "node:http";
 import { type Express } from "express";
 import { type RateLimitRequestHandler } from "express-rate-limit";
 export declare function configureTrustProxy(app: Express, env?: string | undefined): void;
@@ -39,3 +40,14 @@ export interface MetaWebhookOptions {
     onBody: (rawBody: string) => Promise<void>;
 }
 export declare function registerMetaWebhook(app: Express, opts: MetaWebhookOptions): void;
+export interface ListenWebhookOptions {
+    /** The env var that overrides the port. Every message names it — each bridge
+     *  has a different one, and "which knob do I turn" is the question an
+     *  operator has at exactly the moment this fails. */
+    envVar: string;
+    /** Port used when the env var is unset or blank. */
+    fallback: number;
+    /** Test seam. Production prints the message and exits non-zero. */
+    onFatal?: (message: string) => void;
+}
+export declare function listenWebhook(app: Express, opts: ListenWebhookOptions, onReady: (port: number) => void): Server | undefined;

package/dist/index.js

@@ -10,6 +10,8 @@
 import crypto from "crypto";
 import express from "express";
 import rateLimit, { ipKeyGenerator } from "express-rate-limit";
+import { hasNumberProp } from "@mulmoclaude/common";
+import { describeListenError, resolveWebhookPort } from "./port.js";
 // Honour an explicit `trust proxy` setting so `req.ip` (the rate-limit
 // key) reflects the real client IP rather than the load balancer's.
 // Default `false` for safety; operators behind a known LB choose from:
@@ -157,3 +159,38 @@ export function registerMetaWebhook(app, opts) {
         await opts.onBody(rawBody);
     });
 }
+// Bind a bridge's webhook port, and say something useful when that fails.
+//
+// Before #3084 each bridge did `Number(process.env.X) || N` and a bare
+// `app.listen(PORT, cb)`: a typo ran on the default without a word, `X=0` was
+// impossible, and `EADDRINUSE` surfaced as an unhandled error with no mention
+// of which env var to change. The server's port band (3002-3021) overlaps the
+// bridge band (3002-3013), so that collision is routine, not theoretical
+// (#3079).
+export function listenWebhook(app, opts, onReady) {
+    const fatal = opts.onFatal ?? exitWithMessage;
+    const resolved = resolveWebhookPort(process.env[opts.envVar], opts.fallback, opts.envVar);
+    if (!resolved.ok) {
+        fatal(resolved.message);
+        return undefined;
+    }
+    const server = app.listen(resolved.port, () => {
+        // `server.address()` is the authority on whether the bind happened, and on
+        // which port it got (it differs from the requested one for `=0`). Express 5
+        // runs this callback even when the bind FAILED — verified against
+        // express@5.1: `address()` is null, `listening` is false, and the 'error'
+        // event arrives on the next tick. Without this guard a bridge prints its
+        // "listening on <port>" banner for a server that never bound, which is the
+        // same silence #3084 is about, one step later.
+        const address = server.address();
+        if (!hasNumberProp(address, "port"))
+            return;
+        onReady(address.port);
+    });
+    server.on("error", (err) => fatal(describeListenError(err, resolved.port, opts.envVar)));
+    return server;
+}
+function exitWithMessage(message) {
+    console.error(message);
+    process.exit(1);
+}

package/dist/port.d.ts

@@ -0,0 +1,14 @@
+export type PortResolution = {
+    readonly ok: true;
+    readonly port: number;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** Resolve a bridge's listen port from its env var, or say why it cannot be used.
+ *  `raw` is passed in rather than read here so this stays pure. */
+export declare function resolveWebhookPort(raw: string | undefined, fallback: number, envVar: string): PortResolution;
+/** What to tell the operator when `listen` fails. Names the env var, because
+ *  every bridge uses a different one and "which knob do I turn" is the whole
+ *  question at that moment. */
+export declare function describeListenError(err: unknown, port: number, envVar: string): string;

package/dist/port.js

@@ -0,0 +1,40 @@
+// Port resolution and bind diagnostics for the webhook bridges (#3084).
+//
+// Pure on purpose — no `process`, no sockets — so both decisions can be tested
+// directly: WHICH port a bridge binds, and WHAT a human is told when the bind
+// fails. `listenWebhook` in `index.ts` is the only part that touches the world.
+import { asInt, errorMessage, isErrorWithCode, PORT_RANGE } from "@mulmoclaude/common";
+// A fallback that `asInt` can never produce from a real value, since
+// `PORT_RANGE.min` is 0. Comparing against it turns `asInt`'s "fell back"
+// into "the operator typed something unusable", without changing `asInt`'s
+// contract (it returns the fallback for bad input by design).
+const UNUSABLE = -1;
+/** Resolve a bridge's listen port from its env var, or say why it cannot be used.
+ *  `raw` is passed in rather than read here so this stays pure. */
+export function resolveWebhookPort(raw, fallback, envVar) {
+    // A blank value means "not configured", which is what `Number(x) || N` did
+    // for the nine bridges before this — `asInt` alone would read it as 0 and
+    // ask the OS for an ephemeral port.
+    if (raw === undefined || raw.trim() === "")
+        return { ok: true, port: fallback };
+    const port = asInt(raw, UNUSABLE, PORT_RANGE);
+    if (port === UNUSABLE) {
+        return {
+            ok: false,
+            message: `${envVar}="${raw}" is not a usable port. Set it to an integer from ${PORT_RANGE.min} to ${PORT_RANGE.max} (${envVar}=0 asks the OS for a free port), or unset it to use ${fallback}.`,
+        };
+    }
+    return { ok: true, port };
+}
+/** What to tell the operator when `listen` fails. Names the env var, because
+ *  every bridge uses a different one and "which knob do I turn" is the whole
+ *  question at that moment. */
+export function describeListenError(err, port, envVar) {
+    if (isErrorWithCode(err) && err.code === "EADDRINUSE") {
+        return `Port ${port} is already in use. Set ${envVar} to a free port, or ${envVar}=0 to let the OS pick one.`;
+    }
+    if (isErrorWithCode(err) && err.code === "EACCES") {
+        return `Port ${port} needs elevated privileges. Set ${envVar} to a port above 1023.`;
+    }
+    return `Failed to listen on port ${port} (set ${envVar} to change it): ${errorMessage(err)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/webhook-runtime",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Shared HTTP-webhook plumbing (Express app, trust-proxy, rate limit, HMAC verify) for the MulmoClaude messaging bridges",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,12 +27,14 @@
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
+    "@mulmoclaude/common": "^1.3.0",
     "express": "^5.1.0",
-    "express-rate-limit": "^8.6.1"
+    "express-rate-limit": "^8.7.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",
-    "tsx": "^4.23.5",
+    "@types/node": "^26.4.1",
+    "tsx": "^4.23.13",
     "typescript": "^6.0.3"
   },
   "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/webhook-runtime#readme",