alvin-bot 4.9.2 → 4.9.4

package/test/web-server-integration.test.ts

@@ -0,0 +1,189 @@
+/**
+ * Fix #16 (integration) — end-to-end tests for the decoupled
+ * startWebServer + stopWebServer pair.
+ *
+ * These tests exercise the ACTUAL http.Server binding, not the pure
+ * decision helper. They rely on:
+ *   - process.env.WEB_PORT to keep the test off the running bot's 3100
+ *   - process.env.ALVIN_DATA_DIR to keep touch-points away from
+ *     the maintainer's real ~/.alvin-bot/.env
+ *
+ * What's covered here:
+ *   1. startWebServer() returns synchronously (void) without throwing
+ *   2. stopWebServer() releases the port so another server can bind
+ *   3. Start → stop → start cycle doesn't leak sockets or timers
+ *   4. If the configured port is already busy, startWebServer still
+ *      returns cleanly (no throw); the bot keeps running.
+ *   5. stopWebServer() is idempotent — safe to call twice in a row
+ *      and safe to call before startWebServer ever succeeded.
+ *
+ * The deliberate EADDRINUSE scenario is tested HERE against a real
+ * running hog — no mocking.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import http from "http";
+import fs from "fs";
+import os from "os";
+import { resolve } from "path";
+
+const TEST_DATA_DIR = resolve(os.tmpdir(), `alvin-bot-web-int-${process.pid}-${Date.now()}`);
+
+function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const s = http.createServer();
+    s.listen(0, () => {
+      const addr = s.address();
+      if (typeof addr === "object" && addr) {
+        const p = addr.port;
+        s.close(() => resolve(p));
+      } else {
+        reject(new Error("no address"));
+      }
+    });
+  });
+}
+
+async function waitForPortBound(port: number, timeoutMs = 3000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const code = await new Promise<number>((resolveCode, reject) => {
+        const req = http.get(`http://127.0.0.1:${port}/`, (res) => {
+          res.resume();
+          resolveCode(res.statusCode ?? 0);
+        });
+        req.on("error", (err) => reject(err));
+        req.setTimeout(500, () => {
+          req.destroy(new Error("timeout"));
+        });
+      });
+      if (code > 0) return true;
+    } catch {
+      /* not yet */
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  return false;
+}
+
+beforeEach(async () => {
+  if (fs.existsSync(TEST_DATA_DIR)) fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+  process.env.ALVIN_DATA_DIR = TEST_DATA_DIR;
+  // Write a minimal .env so config.ts loads cleanly
+  fs.writeFileSync(`${TEST_DATA_DIR}/.env`, "WEB_PASSWORD=\n", "utf-8");
+  process.env.WEB_PORT = String(await getFreePort());
+  // Reset module cache so each test imports server.js fresh and
+  // picks up the new WEB_PORT env var at module-load time.
+  vi.resetModules();
+});
+
+afterEach(async () => {
+  // Best-effort: stop whatever is running in the current module instance
+  try {
+    const { stopWebServer } = await import("../src/web/server.js");
+    await stopWebServer();
+  } catch {
+    /* ignore */
+  }
+  // Give the OS a moment to release ports before the next test
+  await new Promise((r) => setTimeout(r, 50));
+});
+
+describe("startWebServer / stopWebServer integration (Fix #16)", () => {
+  it("startWebServer returns void synchronously without throwing", async () => {
+    const { startWebServer } = await import("../src/web/server.js");
+    const result = startWebServer();
+    // Must return void (undefined). If it returned a Server instance
+    // the old API is still in place.
+    expect(result).toBeUndefined();
+  });
+
+  it("actually binds the web server and serves HTTP", async () => {
+    const port = Number(process.env.WEB_PORT);
+    const { startWebServer } = await import("../src/web/server.js");
+    startWebServer();
+    const up = await waitForPortBound(port, 3000);
+    expect(up).toBe(true);
+  });
+
+  it("stopWebServer releases the port", async () => {
+    const port = Number(process.env.WEB_PORT);
+    const { startWebServer, stopWebServer } = await import("../src/web/server.js");
+    startWebServer();
+    expect(await waitForPortBound(port, 3000)).toBe(true);
+    await stopWebServer();
+
+    // Port should now be free — a fresh bind must succeed
+    const reuse = http.createServer();
+    await new Promise<void>((resolve, reject) => {
+      reuse.once("error", reject);
+      reuse.listen(port, () => resolve());
+    });
+    await new Promise<void>((r) => reuse.close(() => r()));
+  });
+
+  it("stopWebServer is idempotent — safe to call multiple times", async () => {
+    const { startWebServer, stopWebServer } = await import("../src/web/server.js");
+    startWebServer();
+    await new Promise((r) => setTimeout(r, 200));
+    await stopWebServer();
+    // Second call must not throw
+    await expect(stopWebServer()).resolves.toBeUndefined();
+    // Third call must also not throw
+    await expect(stopWebServer()).resolves.toBeUndefined();
+  });
+
+  it("stopWebServer is safe to call before startWebServer ever bound", async () => {
+    const { stopWebServer } = await import("../src/web/server.js");
+    // Module just imported — nothing started yet
+    await expect(stopWebServer()).resolves.toBeUndefined();
+  });
+
+  it("when the primary port is taken, startWebServer still returns cleanly (climbs the ladder)", async () => {
+    const originalPort = Number(process.env.WEB_PORT);
+    // Plant a hog on the primary port BEFORE startWebServer
+    const hog = http.createServer();
+    await new Promise<void>((r) => hog.listen(originalPort, () => r()));
+
+    try {
+      const { startWebServer } = await import("../src/web/server.js");
+      // Must NOT throw even though the port is occupied
+      expect(() => startWebServer()).not.toThrow();
+
+      // The bot should have climbed the ladder — one port higher should
+      // now be serving HTTP.
+      const climbed = await waitForPortBound(originalPort + 1, 3000);
+      expect(climbed).toBe(true);
+    } finally {
+      await new Promise<void>((r) => hog.close(() => r()));
+    }
+  });
+
+  it("closeHttpServerGracefully closes a server that's holding an open socket", async () => {
+    const { closeHttpServerGracefully } = await import("../src/web/server.js");
+    const port = await getFreePort();
+    const server = http.createServer((_req, res) => {
+      res.writeHead(200, { "Content-Type": "text/plain" });
+      res.write("chunk");
+      // never res.end — client hangs forever
+    });
+    await new Promise<void>((r) => server.listen(port, () => r()));
+
+    const req = http.get(`http://127.0.0.1:${port}/hang`);
+    req.on("error", () => { /* expected */ });
+    await new Promise((r) => setTimeout(r, 100));
+
+    const t0 = Date.now();
+    await closeHttpServerGracefully(server);
+    expect(Date.now() - t0).toBeLessThan(2000);
+
+    // Port is reusable
+    const reuse = http.createServer();
+    await new Promise<void>((resolve, reject) => {
+      reuse.once("error", reject);
+      reuse.listen(port, () => resolve());
+    });
+    await new Promise<void>((r) => reuse.close(() => r()));
+  });
+});

package/test/web-server-resilience.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Fix #16 — Web server must never crash the bot.
+ *
+ * Colleague feedback (WhatsApp voice note, 2026-04-13):
+ *   > The gateway binds to port 3100 like OpenClaw. When the bot
+ *   > restarts, the port is often still held → catastrophic crash.
+ *   > I ended up decoupling the gateway process completely, because
+ *   > the actual bot runs independently of the gateway — it can still
+ *   > answer Telegram even if the web endpoint isn't reachable yet.
+ *   > It's weird that the main routine crashes when the port is busy.
+ *   > It should just run in the background, watch for the port to
+ *   > become free, and connect then. Zero impact on the main routine.
+ *
+ * This file tests the pure decision helper that the new startWebServer
+ * uses to choose between "try the next port immediately" and "retry
+ * the default port in the background after a delay".
+ *
+ * Contract:
+ *   decideNextBindAction(err, attempt, opts)
+ *
+ *   err.code = "EADDRINUSE", attempt < maxPortTries
+ *     → { type: "retry-port", port: opts.originalPort + attempt + 1, attempt: attempt + 1 }
+ *
+ *   err.code = "EADDRINUSE", attempt >= maxPortTries
+ *     → { type: "retry-background", delayMs: opts.backgroundRetryMs, port: opts.originalPort }
+ *
+ *   err.code = anything else (EACCES, ECONNRESET, "Listen method called twice"…)
+ *     → { type: "retry-background", delayMs: opts.backgroundRetryMs, port: opts.originalPort }
+ *
+ *   Pure function, no side effects, no timers, no I/O.
+ */
+import { describe, it, expect } from "vitest";
+import { decideNextBindAction } from "../src/web/bind-strategy.js";
+
+const defaultOpts = {
+  originalPort: 3100,
+  maxPortTries: 20,
+  backgroundRetryMs: 30_000,
+};
+
+describe("decideNextBindAction (Fix #16)", () => {
+  it("retries on the next port when EADDRINUSE and attempts remain", () => {
+    const err = Object.assign(new Error("EADDRINUSE"), { code: "EADDRINUSE" });
+    const result = decideNextBindAction(err, 0, defaultOpts);
+    expect(result).toEqual({ type: "retry-port", port: 3101, attempt: 1 });
+  });
+
+  it("walks the port ladder across multiple attempts", () => {
+    const err = Object.assign(new Error("EADDRINUSE"), { code: "EADDRINUSE" });
+    expect(decideNextBindAction(err, 5, defaultOpts)).toEqual({
+      type: "retry-port",
+      port: 3106,
+      attempt: 6,
+    });
+    expect(decideNextBindAction(err, 18, defaultOpts)).toEqual({
+      type: "retry-port",
+      port: 3119,
+      attempt: 19,
+    });
+  });
+
+  it("switches to background retry when all port attempts are exhausted", () => {
+    const err = Object.assign(new Error("EADDRINUSE"), { code: "EADDRINUSE" });
+    const result = decideNextBindAction(err, 19, defaultOpts); // 20th failure
+    expect(result).toEqual({
+      type: "retry-background",
+      delayMs: 30_000,
+      port: 3100,
+    });
+  });
+
+  it("goes straight to background retry on non-EADDRINUSE errors", () => {
+    const err = Object.assign(new Error("EACCES"), { code: "EACCES" });
+    const result = decideNextBindAction(err, 0, defaultOpts);
+    expect(result).toEqual({
+      type: "retry-background",
+      delayMs: 30_000,
+      port: 3100,
+    });
+  });
+
+  it("handles errors without a .code field by doing background retry", () => {
+    const err = new Error("Listen method has been called more than once");
+    const result = decideNextBindAction(err, 3, defaultOpts);
+    expect(result.type).toBe("retry-background");
+    if (result.type === "retry-background") {
+      expect(result.port).toBe(3100);
+    }
+  });
+
+  it("respects custom maxPortTries", () => {
+    const err = Object.assign(new Error("EADDRINUSE"), { code: "EADDRINUSE" });
+    const opts = { ...defaultOpts, maxPortTries: 3 };
+    // attempts 0, 1 still retry; attempt 2 is the LAST retry; attempt 3 -> background
+    expect(decideNextBindAction(err, 0, opts).type).toBe("retry-port");
+    expect(decideNextBindAction(err, 1, opts).type).toBe("retry-port");
+    expect(decideNextBindAction(err, 2, opts).type).toBe("retry-background");
+  });
+
+  it("respects custom backgroundRetryMs", () => {
+    const err = Object.assign(new Error("EACCES"), { code: "EACCES" });
+    const opts = { ...defaultOpts, backgroundRetryMs: 5_000 };
+    const result = decideNextBindAction(err, 0, opts);
+    expect(result).toEqual({
+      type: "retry-background",
+      delayMs: 5_000,
+      port: 3100,
+    });
+  });
+
+  it("is pure — same input, same output, no mutation", () => {
+    const err = Object.assign(new Error("EADDRINUSE"), { code: "EADDRINUSE" });
+    const snapshot = JSON.stringify({ ...defaultOpts });
+    decideNextBindAction(err, 5, defaultOpts);
+    decideNextBindAction(err, 5, defaultOpts);
+    expect(JSON.stringify({ ...defaultOpts })).toBe(snapshot);
+  });
+});

package/test/web-server-shutdown.test.ts

@@ -17,7 +17,13 @@
 import { describe, it, expect } from "vitest";
 import http from "http";
 import { once } from "events";
-import { startWebServer, stopWebServer } from "../src/web/server.js";
+// Fix #1 shipped as stopWebServer(server) — Fix #16 (v4.9.4) promoted
+// that to `closeHttpServerGracefully(server)` and reserved the name
+// `stopWebServer()` for the module-state-aware shutdown. The underlying
+// contract (close an http.Server even when clients hold open sockets,
+// release the port, idempotent, never throw) is unchanged — these
+// tests now exercise the renamed helper.
+import { closeHttpServerGracefully as stopWebServer } from "../src/web/server.js";
 
 function getFreePort(): Promise<number> {
   return new Promise((resolve, reject) => {