From bf1ca4b86cab2fad13f1b7707c16bbfe0fa7d4db Mon Sep 17 00:00:00 2001 From: PJ Fanning Date: Wed, 29 Jul 2026 22:30:29 +0100 Subject: [PATCH 1/3] add warnings about limitations of idle-timeout --- http-core/src/main/resources/reference.conf | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/http-core/src/main/resources/reference.conf b/http-core/src/main/resources/reference.conf index b47d6c48e..d05107dc9 100644 --- a/http-core/src/main/resources/reference.conf +++ b/http-core/src/main/resources/reference.conf @@ -45,6 +45,11 @@ pekko.http { # The time after which an idle connection will be automatically closed. # Set to `infinite` to completely disable idle connection timeouts. + # + # Note: this timeout only triggers when no data is received. A slow + # client that sends data continuously (even at a low rate) will keep + # the connection alive. For untrusted clients, consider a lower value + # and use max-content-length to bound total entity size. idle-timeout = 60 s # Defines the default time period within which the application has to From 73b8d79147cc812151e4ec25d58cfa701dcac376 Mon Sep 17 00:00:00 2001 From: PJ Fanning Date: Wed, 29 Jul 2026 22:53:33 +0100 Subject: [PATCH 2/3] Update idle connection timeout description Clarified the description of the idle connection timeout to specify it as a bidirectional inactivity timeout and provided additional context on its behavior. --- http-core/src/main/resources/reference.conf | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/http-core/src/main/resources/reference.conf b/http-core/src/main/resources/reference.conf index d05107dc9..608ea3852 100644 --- a/http-core/src/main/resources/reference.conf +++ b/http-core/src/main/resources/reference.conf @@ -46,10 +46,14 @@ pekko.http { # The time after which an idle connection will be automatically closed. # Set to `infinite` to completely disable idle connection timeouts. # - # Note: this timeout only triggers when no data is received. A slow - # client that sends data continuously (even at a low rate) will keep - # the connection alive. For untrusted clients, consider a lower value - # and use max-content-length to bound total entity size. + # Note: This is a bidirectional inactivity timeout. It triggers only when + # no bytes are sent or received for the configured duration. Traffic in + # either direction, including a client sending bytes at intervals shorter + # than the timeout, keeps the connection alive; it is not an overall + # request-receive timeout. Lowering this value and configuring + # pekko.http.server.parsing.max-content-length reduce exposure but do not + # bound request duration. Use an appropriately configured reverse proxy or + # application-level entity timeout when a hard receive deadline is required. idle-timeout = 60 s # Defines the default time period within which the application has to From c63ca5eed71add6062c700898969810b64ac43be Mon Sep 17 00:00:00 2001 From: PJ Fanning Date: Wed, 29 Jul 2026 23:04:29 +0100 Subject: [PATCH 3/3] Enhance documentation on inactivity timeout behavior Clarify the behavior of the inactivity timeout, including its bidirectional nature and implications for connection management. --- docs/src/main/paradox/common/timeouts.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/src/main/paradox/common/timeouts.md b/docs/src/main/paradox/common/timeouts.md index aaf08a8a5..ea5918ef8 100644 --- a/docs/src/main/paradox/common/timeouts.md +++ b/docs/src/main/paradox/common/timeouts.md @@ -15,6 +15,15 @@ on a connection for over `idle-timeout` time, the connection will be automatical This setting should be used as a last-resort safeguard to prevent unused or stuck connections from consuming resources for an indefinite time. +This is a bidirectional inactivity timeout. It triggers only when no +bytes are sent or received for the configured duration. Traffic in +either direction, including a client sending bytes at intervals shorter +than the timeout, keeps the connection alive; it is not an overall +request-receive timeout. Lowering this value and configuring +`pekko.http.server.parsing.max-content-length` reduce exposure but do not +bound request duration. Use an appropriately configured reverse proxy or +application-level entity timeout when a hard receive deadline is required. + The setting works the same way for server and client connections and it is configurable independently using the following keys: ```