Fastify keepAliveTimeout limits behind shorter upstream proxy idle timeouts

Direct answer

Yes. Set Fastify's keepAliveTimeout below the smallest idle timeout among all upstream proxies in the request path. When multiple hops exist, derive the value from the lowest idle limit across every proxy and load balancer between the client and the Fastify server. This ensures the Node HTTP server closes the socket first, so a proxy cannot hand a dead connection to a client for retry.

Confirmed behavior vs. likely explanation

Confirmed: Fastify forwards keepAliveTimeout to Node's http.Server, and Node closes an idle socket when that timer fires. Fastify's documented default for this option has historically differed from Node's own HTTP server default, though exact values are version-dependent.

Likely explanation: When Fastify's timeout exceeds an upstream proxy's idle limit, the proxy can close the TCP connection while the Fastify server still holds it open. A client retrying a non-idempotent request on that socket may reach the server again before the proxy notices the closure, causing a duplicate side effect. Setting Fastify's timeout lower makes the server close first, shrinking that race window.

Deriving the value across hops

1. Collect idle timeout settings from every proxy in the path (for example, Nginx keepalive_timeout, HAProxy timeout http-keep-alive, or cloud load balancer idle timeouts).
2. Take the minimum of those values.
3. Set Fastify's keepAliveTimeout to a few seconds below that minimum, leaving a small safety margin for clock skew and network jitter.

If you cannot enumerate every hop, you cannot safely derive an exact number. In that case, choose a conservative value and validate with proxy logs.

Application-level idempotency

Timeout alignment reduces the race window but does not eliminate duplicate writes. Fastify has no built-in idempotency-key store. For non-idempotent routes, enforce idempotency at the application layer:

• Require an Idempotency-Key header on mutating routes.
• Store the key with the response payload and status in a durable store (Redis or database) before returning to the client.
• On retry, check the store first. If the key exists, return the stored response instead of re-executing the handler.
• Use database unique constraints as a backstop so concurrent duplicate writes fail safely.

This pattern handles the case where a retry arrives after the handler side effect but before the client received the response.

Interaction with other server options

connectionTimeout controls how long the server waits for a new TCP connection to be established; it operates before any HTTP request is parsed and is independent of keepAliveTimeout. requestTimeout caps the time allowed to receive the complete request headers and body. Both are orthogonal to idle keep-alive persistence. maxRequestsPerSocket forces a socket to close after a fixed number of requests, acting as a safety valve that recycles connections regardless of timeout values. These options are supported by recent Node versions; verify availability and defaults for your specific runtime.

Illustrative configuration

const fastify = require('fastify')({
  keepAliveTimeout: 5000,      // derive from minimum upstream idle timeout minus margin
  connectionTimeout: 10000,
  requestTimeout: 30000,
  maxRequestsPerSocket: 1000
});

Verification

Inspect proxy logs for premature upstream closure errors (for example, Nginx may log upstream prematurely closed connection). Under load, confirm whether the server or the proxy initiates the connection close first. If the proxy consistently closes first, increase the gap between Fastify's keepAliveTimeout and the proxy idle timeout.

Missing diagnostic

Do you know the exact idle timeout values for every proxy hop, and are you serving HTTP/1.1 or HTTP/2? The protocol changes the semantics of stream reuse and affects whether keep-alive tuning remains the primary mitigation.