http: add jitter support for max_connection_duration by Retr0-XD · Pull Request #44064 · envoyproxy/envoy

Retr0-XD · 2026-03-21T09:23:31Z

Description

TCP connections already support max_downstream_connection_duration_jitter_percentage (merged in #40686). This PR adds the equivalent feature for HTTP connections via a new max_connection_duration_jitter_percent field in HttpProtocolOptions.

Problem

When many HTTP/2 connections are established simultaneously (e.g. during a pod restart or rolling deploy), they all reach max_connection_duration at the same time, triggering simultaneous drain → reconnect storms ("thundering herd").

Solution

Add max_connection_duration_jitter_percent to HttpProtocolOptions. When configured, the effective max_connection_duration for each connection is individually extended by a random amount uniformly distributed in [0, jitter_percent/100 * base_duration], spreading connection drains over a window rather than synchronizing them.

Example: max_connection_duration = 10s, max_connection_duration_jitter_percent = 25 → each connection drains at a random time in [10s, 12.5s].

Changes

File	Change
`api/envoy/config/core/v3/protocol.proto`	Add `max_connection_duration_jitter_percent` (field 8) to `HttpProtocolOptions`
`source/common/http/conn_manager_config.h`	Add `maxConnectionDurationJitterPercent()` pure virtual method
`source/extensions/filters/network/http_connection_manager/config.{h,cc}`	Parse and store the new proto field
`source/common/http/conn_manager_impl.cc`	Apply jitter when arming the connection duration timer
`source/server/admin/admin.h`	Stub: returns `absl::nullopt` (no jitter for admin connections)
`test/mocks/http/mocks.h`	Add `MOCK_METHOD` for new interface method
`test/common/http/conn_manager_impl_test_base.{h,cc}`	Add stub forwarding delegates
`test/common/http/conn_manager_impl_fuzz_test.cc`	Add stub returning `absl::nullopt`

Prior art

The TCP proxy implementation in source/common/tcp_proxy/tcp_proxy.cc (method Config::calculateMaxDownstreamConnectionDurationWithJitter()) provides the exact same pattern — this PR follows it faithfully.

AI Disclosure: Used GitHub Copilot for coding assistance.

AI disclosure: GitHub Copilot was used during implementation and test writing. I fully understand all changes made in this PR.

Commit Message: See PR title
Risk Level: Low
Testing: Unit tests added/verified
Docs Changes: N/A
Release Notes: N/A
Platform Specific Features: N/A

repokitteh-read-only · 2026-03-21T09:23:38Z

Hi @Retr0-XD, welcome and thank you for your contribution.

We will try to review your Pull Request as quickly as possible.

In the meantime, please take a look at the contribution guidelines if you have not done so already.

🐱

Caused by: #44064 was opened by Retr0-XD.

see: more, trace.

repokitteh-read-only · 2026-03-21T09:23:43Z

CC @envoyproxy/api-shepherds: Your approval is needed for changes made to (api/envoy/|docs/root/api-docs/).
envoyproxy/api-shepherds assignee is @markdroth
CC @envoyproxy/api-watchers: FYI only for changes made to (api/envoy/|docs/root/api-docs/).

🐱

Caused by: #44064 was opened by Retr0-XD.

see: more, trace.

wbpcode

Thanks for this contribution and I added some comments. :)

/wait

wbpcode · 2026-03-25T08:18:14Z

+  /**
+   * @return optional jitter percentage to apply to maxConnectionDuration, in range [0, 100].
+   *         When set, the effective max_connection_duration is extended by a random amount
+   *         up to (jitter_percent / 100) * max_connection_duration.
+   */
+  virtual absl::optional<double> maxConnectionDurationJitterPercent() const PURE;


I think we may needn't this new API. We can calculate the effective duration at maxConnectionDuration() directly?

Yep, the new API is needed here (it'd return different values on each call if not handled). This approach mirrors how TCP proxy handles it with calculateMaxDownstreamConnectionDurationWithJitter()

But we needn't copy the implementation of TCP proxy, right? See, if you remove this method, then you only need to revise implementation of maxConnectionDuration() of the HttpConnectionManagerConfig. The new maxConnectionDuration() could calculate a different connection duration based on the configured jitter. That's say, treat the jitter as internal implementation of the HttpConnectionManagerConfig rather than an exposed API to caller.

- Add PGV validation for max_connection_duration_jitter_percent (required field) - Add documentation note that jitter is only for HTTP/1.1 and HTTP/2 - Note that upstream cluster support is not yet implemented Signed-off-by: Retr0-XD <sakthi.harish@edgeverve.com>

Retr0-XD · 2026-03-25T18:53:41Z

added changes to feat branch

- Add PGV validation for max_connection_duration_jitter_percent (required field) - Add documentation note that jitter is only for HTTP/1.1 and HTTP/2 - Note that upstream cluster support is not yet implemented Signed-off-by: Retr0-XD <sakthi.harish@edgeverve.com> (cherry picked from commit 21a33ac) Signed-off-by: Retr0-XD <sakthi.harish@edgeverve.com>

Fixes envoyproxy#42410. TCP connections already support max_downstream_connection_duration_jitter_percentage (added in envoyproxy#40686). This adds the equivalent for HTTP connections via a new max_connection_duration_jitter_percent field in HttpProtocolOptions. When set, the effective max_connection_duration is extended by a random amount uniformly distributed in [0, jitter_percent/100 * base_duration]. For example, max_connection_duration=10s with 25% jitter means connections drain after a random duration in [10s, 12.5s]. This avoids thundering herd problems when many HTTP/2 connections are established simultaneously. AI Disclosure: Used GitHub Copilot for coding assistance. Signed-off-by: Retr0-XD <sakthi.harish@edgeverve.com>

Adds two test cases: - ConnectionDurationWithJitter: verifies jitter is applied and timer fires at base + jitter - ConnectionDurationJitterNoBaseIgnored: verifies jitter is ignored when base duration is not set Signed-off-by: Retr0-XD <sakthi.harish@edgeverve.com>

- Add PGV validation for max_connection_duration_jitter_percent (required field) - Add documentation note that jitter is only for HTTP/1.1 and HTTP/2 - Note that upstream cluster support is not yet implemented Signed-off-by: Retr0-XD <sakthi.harish@edgeverve.com>

Retr0-XD · 2026-03-27T14:59:48Z

can you please review this :)

Retr0-XD · 2026-03-30T07:29:21Z

@wbpcode issues addressed can you review please? :)

markdroth · 2026-04-08T22:38:40Z

+  //   This field is only effective for HTTP/1.1 and HTTP/2 connections. Support for
+  //   upstream clusters is not implemented and the jitter will not be applied.
+  type.v3.Percent max_connection_duration_jitter_percent = 8
+      [(validate.rules).message = {required: true}];


The comment above implies that this field is optional, but here it's marked as required.

I think adding a new field and marking it as required would essentially be a breaking change, since existing control planes won't populate this field.

phlax · 2026-04-14T12:04:12Z

@Retr0-XD i think this is waiting on your response to feedback

/wait-any

Retr0-XD · 2026-04-14T12:57:44Z

Will get the branch corrected

wbpcode

Sorry for the delay. But I think Mark have left a great comment to the API.

wbpcode · 2026-04-16T14:45:57Z

+  /**
+   * @return optional jitter percentage to apply to maxConnectionDuration, in range [0, 100].
+   *         When set, the effective max_connection_duration is extended by a random amount
+   *         up to (jitter_percent / 100) * max_connection_duration.
+   */
+  virtual absl::optional<double> maxConnectionDurationJitterPercent() const PURE;


But we needn't copy the implementation of TCP proxy, right? See, if you remove this method, then you only need to revise implementation of maxConnectionDuration() of the HttpConnectionManagerConfig. The new maxConnectionDuration() could calculate a different connection duration based on the configured jitter. That's say, treat the jitter as internal implementation of the HttpConnectionManagerConfig rather than an exposed API to caller.

wbpcode · 2026-04-16T14:46:06Z

+  //   This field is only effective for HTTP/1.1 and HTTP/2 connections. Support for
+  //   upstream clusters is not implemented and the jitter will not be applied.
+  type.v3.Percent max_connection_duration_jitter_percent = 8
+      [(validate.rules).message = {required: true}];


wbpcode · 2026-04-16T14:47:36Z

/wait

Retr0-XD requested review from mattklein123 and yanavlasov as code owners March 21, 2026 09:23

Retr0-XD had a problem deploying to external-contributors March 21, 2026 09:23 — with GitHub Actions Error

repokitteh-read-only Bot added the api label Mar 21, 2026

repokitteh-read-only Bot assigned markdroth Mar 21, 2026

Retr0-XD had a problem deploying to external-contributors March 21, 2026 09:33 — with GitHub Actions Error

Retr0-XD force-pushed the feat/http-max-connection-duration-jitter-42410 branch from afbdc5d to 8ad2fb7 Compare March 22, 2026 06:17

Retr0-XD had a problem deploying to external-contributors March 22, 2026 06:17 — with GitHub Actions Error

Retr0-XD force-pushed the feat/http-max-connection-duration-jitter-42410 branch from 8ad2fb7 to 28b7046 Compare March 22, 2026 06:20

Retr0-XD had a problem deploying to external-contributors March 22, 2026 06:20 — with GitHub Actions Error

Retr0-XD force-pushed the feat/http-max-connection-duration-jitter-42410 branch from 28b7046 to 56cfa01 Compare March 24, 2026 18:28

Retr0-XD had a problem deploying to external-contributors March 24, 2026 18:28 — with GitHub Actions Error

wbpcode reviewed Mar 25, 2026

View reviewed changes

repokitteh-read-only Bot added the waiting label Mar 25, 2026

wbpcode self-assigned this Mar 25, 2026

repokitteh-read-only Bot removed the waiting label Mar 25, 2026

Retr0-XD had a problem deploying to external-contributors March 25, 2026 18:50 — with GitHub Actions Error

Retr0-XD force-pushed the feat/http-max-connection-duration-jitter-42410 branch from 21a33ac to b379b44 Compare March 25, 2026 19:05

Retr0-XD had a problem deploying to external-contributors March 25, 2026 19:05 — with GitHub Actions Error

Retr0-XD added 3 commits March 25, 2026 19:06

Retr0-XD force-pushed the feat/http-max-connection-duration-jitter-42410 branch from b379b44 to ee7b782 Compare March 25, 2026 19:07

Retr0-XD requested a deployment to external-contributors March 25, 2026 19:07 — with GitHub Actions Waiting

markdroth reviewed Apr 8, 2026

View reviewed changes

repokitteh-read-only Bot added the waiting:any label Apr 14, 2026

repokitteh-read-only Bot removed the waiting:any label Apr 14, 2026

wbpcode reviewed Apr 16, 2026

View reviewed changes

repokitteh-read-only Bot added the waiting label Apr 16, 2026

Conversation

Retr0-XD commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Problem

Solution

Changes

Prior art

AI Disclosure: Used GitHub Copilot for coding assistance.

Uh oh!

repokitteh-read-only Bot commented Mar 21, 2026

Uh oh!

repokitteh-read-only Bot commented Mar 21, 2026

Uh oh!

wbpcode left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

wbpcode Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Retr0-XD Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

wbpcode Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Retr0-XD commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Retr0-XD commented Mar 27, 2026

Uh oh!

Retr0-XD commented Mar 30, 2026

Uh oh!

markdroth Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

wbpcode Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

phlax commented Apr 14, 2026

Uh oh!

Retr0-XD commented Apr 14, 2026

Uh oh!

wbpcode left a comment

Choose a reason for hiding this comment

Uh oh!

wbpcode Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

wbpcode Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

wbpcode commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Retr0-XD commented Mar 21, 2026 •

edited

Loading

Retr0-XD commented Mar 25, 2026 •

edited

Loading