Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
9.9 KB
Raw Blame
/**
 * Shutting the MCP transports down without cutting a request in half.
 *
 * Before this unit `HttpServerHandle.close` was a bare `server.close()`:
 * it stopped the listener and returned, while the promise returned by
 * `handleHttpRequest` was floated. A supervisor sending SIGTERM during a
 * tool call got a truncated response and no record of it, and neither
 * transport handled a signal at all.
 *
 * The tests below therefore hold a REAL request open across the drain
 * rather than asserting on a counter. The hold is produced by a client
 * that announces a `Content-Length` and then sends only part of the body,
 * so the server is genuinely parked inside `readBody` - a mock would
 * prove the bookkeeping and nothing about the server.
 */

import { afterEach, describe, expect, test } from "bun:test";
import { connect, type Socket } from "node:net";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { installMcpSignalDrain } from "../../src/cli/mcp-drain.ts";
import { EXIT_TERMINATED } from "../../src/cli/interrupt.ts";
import {
  DEFAULT_DRAIN_DEADLINE_MS,
  DRAIN_DEADLINE_ENV,
  DRAIN_STATE,
  describeAbandonedRequests,
  resolveDrainDeadlineMs,
} from "../../src/mcp/drain.ts";
import { startHttp, type HttpServerHandle } from "../../src/mcp/http.ts";

const temps: string[] = [];

afterEach(() => {
  while (temps.length > 0) rmSync(temps.pop()!, { recursive: true, force: true });
});

function tempVault(): string {
  const dir = mkdtempSync(join(tmpdir(), "osb-mcp-drain-"));
  temps.push(dir);
  return dir;
}

/**
 * A request the server has begun and cannot finish until the caller says
 * so: the headers promise more body than has been sent, so the server is
 * parked awaiting the rest.
 */
interface HeldRequest {
  readonly socket: Socket;
  /** Send the rest of the body, letting the server complete the request. */
  readonly complete: () => void;
  /** The full HTTP response, once the server writes one. */
  readonly response: Promise<string>;
}

async function holdRequestOpen(handle: HttpServerHandle): Promise<HeldRequest> {
  const held = await openHeldSocket(handle);
  // The socket write returning says nothing about the server having read
  // it. Without this wait the drain below can start before the request
  // has been registered at all, and every assertion about waiting for it
  // would pass over an empty register.
  await until(() => handle.drain.inFlight === 1, "the held request to reach the server");
  return held;
}

/** Poll a condition the server reaches on its own schedule, or say what failed. */
async function until(condition: () => boolean, what: string): Promise<void> {
  for (let attempt = 0; attempt < 200; attempt++) {
    if (condition()) return;
    await Bun.sleep(5);
  }
  throw new Error(`timed out waiting for ${what}`);
}

function openHeldSocket(handle: HttpServerHandle): Promise<HeldRequest> {
  const body = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "ping" });
  const head = body.slice(0, 5);
  const tail = body.slice(5);
  return new Promise((ready, failed) => {
    const socket = connect(handle.port, handle.host, () => {
      socket.write(
        `POST / HTTP/1.1\r\nHost: ${handle.host}:${handle.port}\r\n` +
          `content-type: application/json\r\ncontent-length: ${Buffer.byteLength(body)}\r\n\r\n` +
          head,
      );
      let seen = "";
      const response = new Promise<string>((resolve) => {
        socket.on("data", (chunk) => {
          seen += String(chunk);
          if (seen.includes("\r\n\r\n")) resolve(seen);
        });
        socket.on("close", () => resolve(seen));
      });
      ready({ socket, complete: () => socket.write(tail), response });
    });
    socket.on("error", failed);
  });
}

async function health(handle: HttpServerHandle): Promise<Record<string, unknown>> {
  const res = await fetch(`${handle.url}/health`);
  return (await res.json()) as Record<string, unknown>;
}

describe("the drain deadline", () => {
  test("defaults to ten seconds", () => {
    expect(DEFAULT_DRAIN_DEADLINE_MS).toBe(10_000);
    expect(resolveDrainDeadlineMs({})).toBe(DEFAULT_DRAIN_DEADLINE_MS);
  });

  test("is overridable by the environment", () => {
    expect(resolveDrainDeadlineMs({ [DRAIN_DEADLINE_ENV]: "250" })).toBe(250);
  });

  test("refuses a value that is not a deadline rather than silently defaulting", () => {
    expect(() => resolveDrainDeadlineMs({ [DRAIN_DEADLINE_ENV]: "soon" })).toThrow(
      new RegExp(DRAIN_DEADLINE_ENV),
    );
    expect(() => resolveDrainDeadlineMs({ [DRAIN_DEADLINE_ENV]: "-1" })).toThrow(
      new RegExp(DRAIN_DEADLINE_ENV),
    );
  });
});

describe("the HTTP transport drains before it closes", () => {
  test("reports draining on the unauthenticated /health while a request is in flight", async () => {
    const handle = await startHttp({ vault: tempVault() }, { host: "127.0.0.1", port: 0 });
    const held = await holdRequestOpen(handle);
    try {
      expect((await health(handle)).status).toBe("ok");

      const closing = handle.close();
      await until(() => handle.drain.draining, "the drain to start");
      // The listener stays up so a supervisor can still be told what is
      // happening; what stops is the acceptance of new MCP work.
      const probe = await health(handle);
      expect(probe.status).toBe(DRAIN_STATE.draining);
      expect(probe.in_flight).toBe(1);

      const refused = await fetch(handle.url, {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "ping" }),
      });
      expect(refused.status).toBe(503);

      held.complete();
      const outcome = await closing;
      expect(outcome.state).toBe(DRAIN_STATE.drained);
      expect(outcome.abandoned).toEqual([]);
      expect(await held.response).toContain("200 OK");
    } finally {
      held.socket.destroy();
    }
  });

  test("a request refused with 503 is not counted as work the drain waits for", async () => {
    const handle = await startHttp({ vault: tempVault() }, { host: "127.0.0.1", port: 0 });
    const held = await holdRequestOpen(handle);
    try {
      const closing = handle.close();
      await until(() => handle.drain.draining, "the drain to start");

      const retries = await Promise.all(
        [1, 2, 3].map((id) =>
          fetch(handle.url, {
            method: "POST",
            headers: { "content-type": "application/json" },
            body: JSON.stringify({ jsonrpc: "2.0", id, method: "ping" }),
          }),
        ),
      );
      expect(retries.map((r) => r.status)).toEqual([503, 503, 503]);

      // The register hands out ids in registration order, so the id of
      // the next request IS the count of everything registered before
      // it: 1 is the held request, and 2 means the three refusals above
      // never entered the register. Counting them let a client retrying
      // in a tight loop hold the drain open to its own deadline.
      const finish = handle.drain.begin("probe");
      expect(handle.drain.snapshot().find((r) => r.label === "probe")?.id).toBe(2);
      finish();

      held.complete();
      expect((await closing).state).toBe(DRAIN_STATE.drained);
    } finally {
      held.socket.destroy();
    }
  });

  test("names the still-open requests on stderr when the deadline expires", async () => {
    const handle = await startHttp(
      { vault: tempVault() },
      { host: "127.0.0.1", port: 0, drainDeadlineMs: 120 },
    );
    const held = await holdRequestOpen(handle);
    try {
      const outcome = await handle.close();
      expect(outcome.state).toBe(DRAIN_STATE.deadlineExpired);
      expect(outcome.abandoned).toHaveLength(1);
      expect(outcome.abandoned[0]!.label).toBe("POST /");

      const report = describeAbandonedRequests(outcome);
      expect(report).toContain("POST /");
      expect(report).toContain("120");
    } finally {
      held.socket.destroy();
    }
  });

  test("a close with nothing in flight resolves at once and shuts the listener", async () => {
    const handle = await startHttp({ vault: tempVault() }, { host: "127.0.0.1", port: 0 });
    const outcome = await handle.close();
    expect(outcome.state).toBe(DRAIN_STATE.drained);
    await expect(fetch(`${handle.url}/health`)).rejects.toThrow();
  });
});

describe("a signal drains the transport", () => {
  // Sends a real SIGTERM to this process. Windows has no POSIX signal
  // delivery: `process.kill(pid, "SIGTERM")` terminates the process outright
  // instead of dispatching the handler, which would kill the test runner.
  test.skipIf(process.platform === "win32")(
    "SIGTERM drains, then exits with the signal's code so the exit hooks run",
    async () => {
      const handle = await startHttp({ vault: tempVault() }, { host: "127.0.0.1", port: 0 });
      const held = await holdRequestOpen(handle);
      const stderr: string[] = [];
      const exits: number[] = [];
      let settled: () => void = () => {};
      const finished = new Promise<void>((resolve) => {
        settled = resolve;
      });

      const installed = installMcpSignalDrain({
        close: () => handle.close(),
        stderr: { write: (chunk: string) => void stderr.push(chunk) },
        exit: (code) => {
          exits.push(code);
          settled();
        },
      });
      try {
        process.kill(process.pid, "SIGTERM");
        // A signal handler is a callback dispatched from the event loop, so
        // it runs a turn or more after delivery (`src/cli/interrupt.ts`
        // measures exactly this). The request is still open when it does,
        // which is the point of the test.
        await until(() => handle.drain.draining, "the signal handler to start a drain");
        expect((await health(handle)).status).toBe(DRAIN_STATE.draining);
        held.complete();
        await finished;

        expect(exits).toEqual([EXIT_TERMINATED]);
        expect(stderr.join("")).toContain("SIGTERM");
      } finally {
        installed.release();
        held.socket.destroy();
      }
    },
  );
});