fix(shutdown): add phase tracking and pool-close timeout test (#116) (#150)

- Add ShutdownPhase type and currentPhase tracking for precise timeout logging
- Log current phase when drain timeout fires (server_close / pool_close)
- Add test covering pool-close-hangs-within-drain-timeout scenario
- Change timeout log from console.error to console.warn per acceptance criteria

Author: Junman140

src/shutdown.test.ts

@@ -90,6 +90,49 @@ describe("Graceful Shutdown", () => {
     expect(processExitSpy).toHaveBeenCalledWith(1);
   });
 
+  it("should force exit if pool close hangs within drain timeout", async () => {
+    // Pool close hangs (never resolves)
+    let poolCloseNeverResolve: () => void;
+    const hangingPoolPromise = new Promise<void>((resolve) => {
+      poolCloseNeverResolve = resolve;
+    });
+    mockClosePool.mockReturnValue(hangingPoolPromise);
+
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    setupGracefulShutdown(mockServer as unknown as Server, mockClosePool, 10000);
+
+    const sigtermHandlerCall = processOnSpy.mock.calls.find((call: any) => call[0] === "SIGTERM");
+    const handler = sigtermHandlerCall[1];
+
+    handler("SIGTERM");
+
+    expect(mockServer.close).toHaveBeenCalled();
+
+    // Call the server close callback without awaiting — it will execute
+    // synchronously up to the pending `await closePool()` and yield.
+    mockServer._closeCallback();
+
+    expect(mockClosePool).toHaveBeenCalled();
+
+    // Fast-forward past the drain timeout
+    vi.advanceTimersByTime(10001);
+
+    // Should force exit with 1 because pool close hung and timeout fired
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+
+    // Verify the timeout warning mentions the pool_close phase
+    const timeoutCall = warnSpy.mock.calls.find((call: any) =>
+      call[0].includes("Drain timeout"),
+    );
+    expect(timeoutCall).toBeDefined();
+    expect(timeoutCall[0]).toMatch(/pool_close/);
+
+    warnSpy.mockRestore();
+    // Resolve the hanging promise to clean up
+    poolCloseNeverResolve();
+  });
+
   it("should handle error during pool close", async () => {
     mockClosePool.mockRejectedValue(new Error("Pool close error"));
 

src/shutdown.ts

@@ -10,12 +10,15 @@ import { Server } from "http";
  * @param closePool - A function to close the database connection pool
  * @param drainTimeoutMs - The bounded timeout in milliseconds to wait for connections to drain
  */
+type ShutdownPhase = "starting" | "server_close" | "pool_close";
+
 export function setupGracefulShutdown(
   server: Server,
   closePool: () => Promise<void>,
   drainTimeoutMs: number,
 ): void {
   let isShuttingDown = false;
+  let currentPhase: ShutdownPhase = "starting";
 
   const shutdownHandler = async (signal: string) => {
     if (isShuttingDown) {
@@ -27,11 +30,14 @@ export function setupGracefulShutdown(
 
     // Create a bounded drain timeout
     const timeout = setTimeout(() => {
-      console.error(`[shutdown] Drain timeout (${drainTimeoutMs}ms) exceeded, forcing exit`);
+      console.warn(
+        `[shutdown] Drain timeout (${drainTimeoutMs}ms) exceeded during ${currentPhase}, forcing exit`,
+      );
       process.exit(1);
     }, drainTimeoutMs);
     timeout.unref();
 
+    currentPhase = "server_close";
     console.log("[shutdown] Stopping HTTP server from accepting new connections...");
     server.close(async (err) => {
       if (err) {
@@ -40,6 +46,7 @@ export function setupGracefulShutdown(
         console.log("[shutdown] HTTP server closed");
       }
 
+      currentPhase = "pool_close";
       try {
         await closePool();
         clearTimeout(timeout);