Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
⏱️ feat: Configurable HTTP Server Timeouts (#14481)
Danny Avila324584552c15
diff --git a/.env.example b/.env.exampleindex 8ffb4cd1f4..a51cf71664 100644--- a/.env.example+++ b/.env.example@@ -14,6 +14,19 @@HOST=localhostPORT=3080+# Optional Node.js HTTP server timeouts in milliseconds. When unset, Node.js defaults apply.+# For an ALB, set the application keep-alive timeout above the ALB idle timeout.+# Requires Node.js: Bun accepts these values but does not enforce them.+# Header and request timeout expiry is only detected on a 30s connection sweep, so values+# below 30000 take effect late and are not enforced at the precision configured.+# The header timeout is clamped to the request timeout when the latter is lower, since Node+# does not enforce a request timeout that a longer header timeout sits above.+# Keep-alive is socket-driven and remains exact at any value.+# HTTP_KEEP_ALIVE_TIMEOUT_MS=70000+# HTTP_KEEP_ALIVE_TIMEOUT_BUFFER_MS=5000+# HTTP_HEADERS_TIMEOUT_MS=80000+# HTTP_REQUEST_TIMEOUT_MS=300000+MONGO_URI=mongodb://127.0.0.1:27017/LibreChat#The maximum number of connections in the connection pool. */MONGO_MAX_POOL_SIZE=diff --git a/api/server/experimental.js b/api/server/experimental.jsindex dadb87dd0b..2632c2d2bc 100644--- a/api/server/experimental.js+++ b/api/server/experimental.js@@ -23,6 +23,7 @@ const {loadToolApprovalHooks,maybeInjectQueryDevtoolsBootstrap,preAuthTenantMiddleware,+ configureServerTimeouts,} = require('@librechat/api');const { connectDb, indexSync } = require('~/db');const initializeOAuthReconnectManager = require('./services/initializeOAuthReconnectManager');@@ -450,7 +451,7 @@ if (cluster.isMaster) {app.use(ErrorController);/** Start listening on shared port (cluster will distribute connections) */- app.listen(port, host, async (err) => {+ const server = app.listen(port, host, async (err) => {if (err) {logger.error(`Worker ${process.pid} failed to start server:`, err);process.exit(1);@@ -479,6 +480,14 @@ if (cluster.isMaster) {process.exit(1);}});++ configureServerTimeouts(server);+ logger.info(`Worker ${process.pid} HTTP server timeout configuration`, {+ keepAliveTimeout: server.keepAliveTimeout,+ keepAliveTimeoutBuffer: server.keepAliveTimeoutBuffer,+ headersTimeout: server.headersTimeout,+ requestTimeout: server.requestTimeout,+ });};startServer().catch((err) => {diff --git a/api/server/experimental.spec.js b/api/server/experimental.spec.jsnew file mode 100644index 0000000000..db58e7c20c--- /dev/null+++ b/api/server/experimental.spec.js@@ -0,0 +1,15 @@+const fs = require('fs');+const path = require('path');++describe('Experimental server configuration', () => {+ const source = fs.readFileSync(path.join(__dirname, 'experimental.js'), 'utf8');++ it('configures HTTP timeouts for each cluster worker server', () => {+ const listenIndex = source.indexOf('const server = app.listen');+ const timeoutConfigIndex = source.indexOf('configureServerTimeouts(server);');++ expect(listenIndex).toBeGreaterThan(-1);+ expect(timeoutConfigIndex).toBeGreaterThan(-1);+ expect(listenIndex).toBeLessThan(timeoutConfigIndex);+ });+});diff --git a/api/server/index.js b/api/server/index.jsindex be3b8a1fe0..eca877e8de 100644--- a/api/server/index.js+++ b/api/server/index.js@@ -29,6 +29,7 @@ const {maybeInjectQueryDevtoolsBootstrap,preAuthTenantMiddleware,registerShutdownTask,+ configureServerTimeouts,setupGracefulShutdown,updateInterfacePermissions,} = require('@librechat/api');@@ -363,6 +364,14 @@ const startServer = async () => {}});+ configureServerTimeouts(server);+ logger.info('HTTP server timeout configuration', {+ keepAliveTimeout: server.keepAliveTimeout,+ keepAliveTimeoutBuffer: server.keepAliveTimeoutBuffer,+ headersTimeout: server.headersTimeout,+ requestTimeout: server.requestTimeout,+ });+setupGracefulShutdown(server);};diff --git a/api/server/index.spec.js b/api/server/index.spec.jsindex e73ee40f60..9945c51253 100644--- a/api/server/index.spec.js+++ b/api/server/index.spec.js@@ -126,6 +126,18 @@ describe('Startup readiness wiring', () => {expect(shutdownRegistrationIndex).toBeLessThan(listenIndex);});+ it('configures HTTP timeouts before graceful shutdown handling', () => {+ const listenIndex = source.indexOf('const server = app.listen');+ const timeoutConfigIndex = source.indexOf('configureServerTimeouts(server);');+ const shutdownIndex = source.indexOf('setupGracefulShutdown(server);');++ expect(listenIndex).toBeGreaterThan(-1);+ expect(timeoutConfigIndex).toBeGreaterThan(-1);+ expect(shutdownIndex).toBeGreaterThan(-1);+ expect(listenIndex).toBeLessThan(timeoutConfigIndex);+ expect(timeoutConfigIndex).toBeLessThan(shutdownIndex);+ });+it('mounts the chat-start readiness gate before agent routes', () => {const readinessGateIndex = source.indexOf("app.use('/api/agents/chat', rejectChatStartsUntilReady);",diff --git a/packages/api/src/app/index.ts b/packages/api/src/app/index.tsindex b5380612d2..b5962a45f7 100644--- a/packages/api/src/app/index.ts+++ b/packages/api/src/app/index.ts@@ -6,5 +6,6 @@ export * from './cdn';export * from './checks';export * from './resolve';export * from './shutdown';+export * from './server';export { resolveBuildInfo } from './build';export type { BuildInfo } from './build';diff --git a/packages/api/src/app/server.spec.ts b/packages/api/src/app/server.spec.tsnew file mode 100644index 0000000000..498dd73658--- /dev/null+++ b/packages/api/src/app/server.spec.ts@@ -0,0 +1,175 @@+import { createServer } from 'node:http';+import { logger } from '@librechat/data-schemas';+import { configureServerTimeouts } from './server';++describe('configureServerTimeouts', () => {+ const NODE = {};+ const BUN = { bun: '1.3.13' };++ let warn: jest.SpyInstance;++ beforeEach(() => {+ warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);+ });++ afterEach(() => {+ warn.mockRestore();+ });++ it('preserves Node.js defaults when variables are unset', () => {+ const server = createServer();+ const defaults = {+ keepAliveTimeout: server.keepAliveTimeout,+ keepAliveTimeoutBuffer: server.keepAliveTimeoutBuffer,+ headersTimeout: server.headersTimeout,+ requestTimeout: server.requestTimeout,+ };++ configureServerTimeouts(server, {});++ expect(server.keepAliveTimeout).toBe(defaults.keepAliveTimeout);+ expect(server.keepAliveTimeoutBuffer).toBe(defaults.keepAliveTimeoutBuffer);+ expect(server.headersTimeout).toBe(defaults.headersTimeout);+ expect(server.requestTimeout).toBe(defaults.requestTimeout);+ });++ it('applies configured timeout values', () => {+ const server = createServer();++ configureServerTimeouts(server, {+ HTTP_KEEP_ALIVE_TIMEOUT_MS: '70000',+ HTTP_KEEP_ALIVE_TIMEOUT_BUFFER_MS: '5000',+ HTTP_HEADERS_TIMEOUT_MS: '80000',+ HTTP_REQUEST_TIMEOUT_MS: '300000',+ });++ expect(server.keepAliveTimeout).toBe(70_000);+ expect(server.keepAliveTimeoutBuffer).toBe(5_000);+ expect(server.headersTimeout).toBe(80_000);+ expect(server.requestTimeout).toBe(300_000);+ });++ it('ignores invalid values and permits zero to disable a timeout', () => {+ const server = createServer();+ const defaultKeepAliveTimeout = server.keepAliveTimeout;+ const defaultHeadersTimeout = server.headersTimeout;++ configureServerTimeouts(server, {+ HTTP_KEEP_ALIVE_TIMEOUT_MS: '-1',+ HTTP_KEEP_ALIVE_TIMEOUT_BUFFER_MS: '0',+ HTTP_HEADERS_TIMEOUT_MS: 'not-a-number',+ HTTP_REQUEST_TIMEOUT_MS: '0',+ });++ expect(server.keepAliveTimeout).toBe(defaultKeepAliveTimeout);+ expect(server.keepAliveTimeoutBuffer).toBe(0);+ expect(server.headersTimeout).toBe(defaultHeadersTimeout);+ expect(server.requestTimeout).toBe(0);+ });++ it('clamps the headers timeout when only a lower request timeout is configured', () => {+ const server = createServer();++ configureServerTimeouts(server, { HTTP_REQUEST_TIMEOUT_MS: '45000' }, NODE);++ expect(server.requestTimeout).toBe(45_000);+ expect(server.headersTimeout).toBe(45_000);+ expect(warn).not.toHaveBeenCalled();+ });++ it('leaves the headers timeout alone when it already fits the request timeout', () => {+ const server = createServer();++ configureServerTimeouts(server, { HTTP_REQUEST_TIMEOUT_MS: '300000' }, NODE);++ expect(server.headersTimeout).toBe(60_000);+ });++ it('warns and clamps when both timeouts are configured in conflict', () => {+ const server = createServer();++ configureServerTimeouts(+ server,+ { HTTP_HEADERS_TIMEOUT_MS: '80000', HTTP_REQUEST_TIMEOUT_MS: '45000' },+ NODE,+ );++ expect(server.headersTimeout).toBe(45_000);+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('a pairing Node rejects'));+ });++ it('treats zero as disabled on either side rather than clamping', () => {+ const disabledRequest = createServer();+ configureServerTimeouts(+ disabledRequest,+ { HTTP_HEADERS_TIMEOUT_MS: '5000', HTTP_REQUEST_TIMEOUT_MS: '0' },+ NODE,+ );+ expect(disabledRequest.headersTimeout).toBe(5_000);++ const disabledHeaders = createServer();+ configureServerTimeouts(+ disabledHeaders,+ { HTTP_HEADERS_TIMEOUT_MS: '0', HTTP_REQUEST_TIMEOUT_MS: '10000' },+ NODE,+ );+ expect(disabledHeaders.headersTimeout).toBe(0);+ });++ it('produces a pairing Node itself accepts', () => {+ const server = createServer();++ configureServerTimeouts(server, { HTTP_REQUEST_TIMEOUT_MS: '45000' }, NODE);++ expect(() =>+ createServer({+ headersTimeout: server.headersTimeout,+ requestTimeout: server.requestTimeout,+ }).close(),+ ).not.toThrow();+ });++ it('warns that Bun does not enforce the configured timeouts', () => {+ configureServerTimeouts(createServer(), { HTTP_KEEP_ALIVE_TIMEOUT_MS: '70000' }, BUN);++ expect(warn).toHaveBeenCalledWith(expect.stringContaining('Bun does not enforce them'));+ });++ it('stays quiet under Bun when no timeout is configured', () => {+ configureServerTimeouts(createServer(), {}, BUN);++ expect(warn).not.toHaveBeenCalled();+ });++ it('does not warn about the runtime under Node.js', () => {+ configureServerTimeouts(createServer(), { HTTP_KEEP_ALIVE_TIMEOUT_MS: '70000' }, NODE);++ expect(warn).not.toHaveBeenCalled();+ });++ it('warns when header or request timeouts fall below the connection sweep interval', () => {+ configureServerTimeouts(+ createServer(),+ { HTTP_HEADERS_TIMEOUT_MS: '5000', HTTP_REQUEST_TIMEOUT_MS: '10000' },+ NODE,+ );++ expect(warn).toHaveBeenCalledWith(+ expect.stringContaining('HTTP_HEADERS_TIMEOUT_MS, HTTP_REQUEST_TIMEOUT_MS'),+ );+ });++ it('does not warn about sweep resolution for zero or above-interval timeouts', () => {+ configureServerTimeouts(+ createServer(),+ {+ HTTP_KEEP_ALIVE_TIMEOUT_MS: '1000',+ HTTP_HEADERS_TIMEOUT_MS: '80000',+ HTTP_REQUEST_TIMEOUT_MS: '0',+ },+ NODE,+ );++ expect(warn).not.toHaveBeenCalled();+ });+});diff --git a/packages/api/src/app/server.ts b/packages/api/src/app/server.tsnew file mode 100644index 0000000000..23c18980f8--- /dev/null+++ b/packages/api/src/app/server.ts@@ -0,0 +1,92 @@+import { logger } from '@librechat/data-schemas';+import type { Server } from 'node:http';++/**+ * Node detects header/request timeout expiry only on `connectionsCheckingInterval`, a+ * `createServer` option that `app.listen()` leaves at its 30s default, so short values+ * take effect late rather than at the configured deadline. `keepAliveTimeout` is+ * socket-driven and stays exact.+ */+const TIMEOUT_SWEEP_RESOLUTION_MS = 30_000;++/**+ * `createServer` throws ERR_OUT_OF_RANGE unless `headersTimeout <= requestTimeout`, treating+ * zero on either side as disabled. Assigning the properties afterwards skips that check, and+ * the resulting mismatch leaves a stalled request body open past the request timeout.+ */+const clampHeadersToRequestTimeout = (server: Server, configuredHeadersTimeout?: number): void => {+ if (server.requestTimeout === 0 || server.headersTimeout === 0) {+ return;+ }+ if (server.headersTimeout <= server.requestTimeout) {+ return;+ }++ const clamped = server.requestTimeout;+ if (configuredHeadersTimeout != null) {+ logger.warn(+ `HTTP_HEADERS_TIMEOUT_MS (${configuredHeadersTimeout}ms) exceeds HTTP_REQUEST_TIMEOUT_MS (${clamped}ms), a pairing Node rejects; clamped to the request timeout.`,+ );+ }+ server.headersTimeout = clamped;+};++const parseTimeout = (value?: string): number | undefined => {+ if (value == null || value.trim() === '') {+ return undefined;+ }++ const timeout = Number(value);+ return Number.isSafeInteger(timeout) && timeout >= 0 ? timeout : undefined;+};++export const configureServerTimeouts = (+ server: Server,+ environment: NodeJS.ProcessEnv = process.env,+ versions: { bun?: string } = process.versions,+): void => {+ const keepAliveTimeout = parseTimeout(environment.HTTP_KEEP_ALIVE_TIMEOUT_MS);+ const keepAliveTimeoutBuffer = parseTimeout(environment.HTTP_KEEP_ALIVE_TIMEOUT_BUFFER_MS);+ const headersTimeout = parseTimeout(environment.HTTP_HEADERS_TIMEOUT_MS);+ const requestTimeout = parseTimeout(environment.HTTP_REQUEST_TIMEOUT_MS);++ if (keepAliveTimeout != null) {+ server.keepAliveTimeout = keepAliveTimeout;+ }+ if (keepAliveTimeoutBuffer != null) {+ server.keepAliveTimeoutBuffer = keepAliveTimeoutBuffer;+ }+ if (headersTimeout != null) {+ server.headersTimeout = headersTimeout;+ }+ if (requestTimeout != null) {+ server.requestTimeout = requestTimeout;+ }++ clampHeadersToRequestTimeout(server, headersTimeout);++ const configured = [keepAliveTimeout, keepAliveTimeoutBuffer, headersTimeout, requestTimeout];+ if (configured.every((value) => value == null)) {+ return;+ }++ /** Bun accepts and reflects these assignments back without enforcing them. */+ if (versions.bun != null) {+ logger.warn(+ 'HTTP server timeouts are configured but Bun does not enforce them; run under Node.js for these settings to take effect.',+ );+ }++ const belowResolution = [+ { name: 'HTTP_HEADERS_TIMEOUT_MS', value: headersTimeout },+ { name: 'HTTP_REQUEST_TIMEOUT_MS', value: requestTimeout },+ ]+ .filter(({ value }) => value != null && value > 0 && value < TIMEOUT_SWEEP_RESOLUTION_MS)+ .map(({ name }) => name);++ if (belowResolution.length > 0) {+ logger.warn(+ `${belowResolution.join(', ')} set below the ${TIMEOUT_SWEEP_RESOLUTION_MS}ms connection sweep interval; expiry is only detected on the next sweep, so the connection can stay open well past the configured deadline. Use values at or above ${TIMEOUT_SWEEP_RESOLUTION_MS}ms for predictable enforcement.`,+ );+ }+};