diff --git a/server/src/__tests__/error-handler.test.ts b/server/src/__tests__/error-handler.test.ts index 934cf7aa7c0..8ef380af6f9 100644 --- a/server/src/__tests__/error-handler.test.ts +++ b/server/src/__tests__/error-handler.test.ts @@ -83,6 +83,67 @@ describe("errorHandler", () => { expect(telemetryMocks.trackErrorHandlerCrash).not.toHaveBeenCalled(); }); + function endedPoolQueryError() { + // Drizzle wraps the driver error; postgres.js uses CONNECTION_ENDED for a + // query issued after this process called `sql.end()`. + const driverError = Object.assign(new Error("write CONNECTION_ENDED db.example:5432"), { + code: "CONNECTION_ENDED", + }); + return new Error('Failed query: select "id" from "issues"', { cause: driverError }); + } + + it("answers 503 without reporting a query that outlived the database shutdown", () => { + const req = { ...makeReq(), app: { locals: { paperclipDatabaseClosing: true } } } as unknown as Request; + const res = makeRes() as any; + const next = vi.fn() as unknown as NextFunction; + + errorHandler(endedPoolQueryError(), req, res, next); + + expect(res.status).toHaveBeenCalledWith(503); + expect(res.json).toHaveBeenCalledWith({ error: "Server is shutting down" }); + expect(res.err).toBeUndefined(); + expect(captureExceptionMock).not.toHaveBeenCalled(); + expect(telemetryMocks.trackErrorHandlerCrash).not.toHaveBeenCalled(); + }); + + it("only ends the response when headers were already sent during database shutdown", () => { + const req = { ...makeReq(), app: { locals: { paperclipDatabaseClosing: true } } } as unknown as Request; + const res = { ...makeRes(), end: vi.fn(), headersSent: true } as any; + const next = vi.fn() as unknown as NextFunction; + + errorHandler(endedPoolQueryError(), req, res, next); + + expect(res.status).not.toHaveBeenCalled(); + expect(res.end).toHaveBeenCalled(); + expect(captureExceptionMock).not.toHaveBeenCalled(); + }); + + it("still reports an ended-pool query error outside database shutdown", () => { + const req = { ...makeReq(), app: { locals: {} } } as unknown as Request; + const res = makeRes() as any; + const next = vi.fn() as unknown as NextFunction; + const err = endedPoolQueryError(); + + errorHandler(err, req, res, next); + + expect(res.status).toHaveBeenCalledWith(500); + expect(captureExceptionMock).toHaveBeenCalledWith(err); + }); + + it("still reports other connection failures during database shutdown", () => { + const req = { ...makeReq(), app: { locals: { paperclipDatabaseClosing: true } } } as unknown as Request; + const res = makeRes() as any; + const next = vi.fn() as unknown as NextFunction; + const err = new Error("Failed query", { + cause: Object.assign(new Error("write CONNECTION_CLOSED"), { code: "CONNECTION_CLOSED" }), + }); + + errorHandler(err, req, res, next); + + expect(res.status).toHaveBeenCalledWith(500); + expect(captureExceptionMock).toHaveBeenCalledWith(err); + }); + it("exposes raw 500 messages for trusted Cloud tenant imports", () => { const req = { ...makeReq(), diff --git a/server/src/__tests__/public-mcp-dispatch-shutdown.test.ts b/server/src/__tests__/public-mcp-dispatch-shutdown.test.ts new file mode 100644 index 00000000000..7540922f3e4 --- /dev/null +++ b/server/src/__tests__/public-mcp-dispatch-shutdown.test.ts @@ -0,0 +1,51 @@ +import express from "express"; +import { beforeEach, describe, expect, it, vi } from "vitest"; +import { createMcpApiDispatch } from "../services/public-mcp/capabilities.js"; +import type { McpPrincipal } from "../services/public-mcp/oauth.js"; + +const captureExceptionMock = vi.hoisted(() => vi.fn()); +const trackErrorHandlerCrashMock = vi.hoisted(() => vi.fn()); + +vi.mock("../sentry.js", () => ({ captureException: captureExceptionMock })); +vi.mock("../telemetry.js", () => ({ getTelemetryClient: () => ({}) })); +vi.mock("@paperclipai/shared/telemetry", () => ({ + trackErrorHandlerCrash: trackErrorHandlerCrashMock, +})); + +const principal = { actor: { type: "board", userId: "user-1" } } as unknown as McpPrincipal; + +// The internal dispatch runs each public MCP call in its own Express app, so +// the shutdown flag set on the main app must reach that app's error handler. +function endedPoolApi() { + const api = express.Router(); + api.get("/tasks", () => { + throw new Error('Failed query: select "id" from "issues"', { + cause: Object.assign(new Error("write CONNECTION_ENDED db.example:5432"), { code: "CONNECTION_ENDED" }), + }); + }); + return api; +} + +describe("public MCP dispatch during database shutdown", () => { + beforeEach(() => { + captureExceptionMock.mockReset(); + trackErrorHandlerCrashMock.mockReset(); + }); + + it("does not report a call that outlived the database pool", async () => { + const parentLocals: Record = {}; + const dispatch = createMcpApiDispatch(endedPoolApi(), parentLocals); + parentLocals.paperclipDatabaseClosing = true; + + await expect(dispatch(principal, "GET", "/tasks", undefined)).rejects.toMatchObject({ status: 503 }); + expect(captureExceptionMock).not.toHaveBeenCalled(); + expect(trackErrorHandlerCrashMock).not.toHaveBeenCalled(); + }); + + it("still reports an ended-pool error outside database shutdown", async () => { + const dispatch = createMcpApiDispatch(endedPoolApi(), {}); + + await expect(dispatch(principal, "GET", "/tasks", undefined)).rejects.toMatchObject({ status: 500 }); + expect(captureExceptionMock).toHaveBeenCalledTimes(1); + }); +}); diff --git a/server/src/app.ts b/server/src/app.ts index bd8685fe49d..b320dea6913 100644 --- a/server/src/app.ts +++ b/server/src/app.ts @@ -1061,7 +1061,7 @@ export async function createApp( let publicMcpEvents: PublicMcpEvents | null = null; let dotMcpEvents: PublicMcpEvents | null = null; if (publicMcpOAuth) { - const dispatch = createMcpApiDispatch(api); + const dispatch = createMcpApiDispatch(api, app.locals); publicMcpEvents = createPublicMcpEvents(db, publicMcpOAuth, dispatch, { isBackgroundWorkEnabled: () => !isWarmStandby() && !isIdleTaskDrainActive(), }); diff --git a/server/src/database-retry.ts b/server/src/database-retry.ts index d56429f7140..17cc9448510 100644 --- a/server/src/database-retry.ts +++ b/server/src/database-retry.ts @@ -6,14 +6,27 @@ const transientDbConnectionCodes = new Set([ "CONNECTION_DESTROYED", ]); -export function isTransientDbConnectionError(error: unknown): boolean { +function hasDbConnectionErrorCode(error: unknown, matches: (code: string) => boolean): boolean { for (let current: unknown = error; current instanceof Error; current = current.cause) { const code = (current as { code?: unknown }).code; - if (typeof code === "string" && transientDbConnectionCodes.has(code)) return true; + if (typeof code === "string" && matches(code)) return true; } return false; } +export function isTransientDbConnectionError(error: unknown): boolean { + return hasDbConnectionErrorCode(error, (code) => transientDbConnectionCodes.has(code)); +} + +/** + * postgres.js rejects every query issued after this process called + * `sql.end()` with `CONNECTION_ENDED`. Unlike a dropped socket, it never comes + * from the database or the network: the pool was ended locally. + */ +export function isEndedDbPoolError(error: unknown): boolean { + return hasDbConnectionErrorCode(error, (code) => code === "CONNECTION_ENDED"); +} + /** * Retry only an explicitly idempotent operation, such as a known read-only * lookup or receipt-protected synchronization. Neither a SQL prefix nor a diff --git a/server/src/index.ts b/server/src/index.ts index ab0d225ad95..be6b6bd701f 100644 --- a/server/src/index.ts +++ b/server/src/index.ts @@ -2062,7 +2062,12 @@ async function startServerWithDatabaseTeardown( closeHttpListener: () => closeHttpListenerForShutdown({ server, signal, log: logger }), drainPendingRunFailureReports: waitForPendingRunFailureReports, - closeDatabase: closeDatabaseClients, + // Mark the pool as ending before `sql.end()` rejects the first query, + // so the error handler recognizes a request that outlived the drain. + closeDatabase: () => { + (app.locals as { paperclipDatabaseClosing?: boolean }).paperclipDatabaseClosing = true; + return closeDatabaseClients(); + }, stopEmbeddedPostgres, shutdownInstrumentation, shutdownSentry, diff --git a/server/src/middleware/error-handler.ts b/server/src/middleware/error-handler.ts index f138c06e4d6..4300267c884 100644 --- a/server/src/middleware/error-handler.ts +++ b/server/src/middleware/error-handler.ts @@ -15,6 +15,7 @@ import { } from "./redact-sensitive.js"; import { recordResponsibleUserDenialOnActiveRun } from "../services/responsible-user-denial-run-outcomes.js"; import { isExpectedMcpConnectionFailure } from "../services/mcp-connection-failure.js"; +import { isEndedDbPoolError } from "../database-retry.js"; export interface ErrorContext { error: { @@ -93,6 +94,12 @@ function reportCrash(error: Error, reportToSentry = true): void { if (reportToSentry) captureException(error); } +/** Set by the orderly shutdown just before it ends the database pools. */ +function isDatabaseClosing(req: Request): boolean { + const locals = req.app?.locals as { paperclipDatabaseClosing?: boolean } | undefined; + return locals?.paperclipDatabaseClosing === true; +} + function getPaperclipDb(req: Request): Db | null { const locals = req.app?.locals as { paperclipDb?: Db; db?: Db } | undefined; return locals?.paperclipDb ?? locals?.db ?? null; @@ -266,6 +273,21 @@ export function errorHandler( return; } + // Shutdown drains the HTTP listener before it ends the pool, but a handler + // whose client already disconnected (or whose socket the drain timeout + // closed) keeps running. Its next query then fails with CONNECTION_ENDED + // against the pool this process deliberately ended. That is shutdown, not a + // server fault, so skip the error sinks. Any other error during shutdown is + // still reported. + if (isDatabaseClosing(req) && isEndedDbPoolError(rootError)) { + if (!res.headersSent) { + res.status(503).json({ error: "Server is shutting down" }); + } else { + res.end(); + } + return; + } + const reportableError = sanitizeSecretSensitiveError(req, rootError); attachErrorContext( req, diff --git a/server/src/services/public-mcp/capabilities.ts b/server/src/services/public-mcp/capabilities.ts index ca0eaf27cc7..a56683cff4e 100644 --- a/server/src/services/public-mcp/capabilities.ts +++ b/server/src/services/public-mcp/capabilities.ts @@ -19,10 +19,17 @@ import { expandedMcpCapabilities } from "./expanded-capabilities.js"; /** Internal HTTP dispatch reuses domain authorization, validation, audit and scheduling. * Neither an arbitrary path nor an actor is accepted from the MCP client. * Each invocation has its own Express request and verified actor. + * `parentLocals` is the main app's locals; the orderly-shutdown flag is read + * through it so a call that outlives the database pool is recognized. */ -export function createMcpApiDispatch(api: Router): ApiDispatch { +export function createMcpApiDispatch(api: Router, parentLocals?: Record): ApiDispatch { return async (principal, method, path, body) => { const app = express(); + if (parentLocals) { + Object.defineProperty(app.locals, "paperclipDatabaseClosing", { + get: () => parentLocals.paperclipDatabaseClosing === true, + }); + } // light-my-request adapts the parent prototypes of app.request/response. // Clone Express's shared parents so injection cannot alter real HTTP traffic. for (const target of [app.request, app.response]) {