http: add priority_load_shed extension filter for priority-based overload shedding by leosarra · Pull Request #45039 · envoyproxy/envoy

leosarra · 2026-05-12T22:07:39Z

Commit Message: http: add priority_load_shed filter for priority-based overload shedding
Additional Description:
Adds a new alpha HTTP filter, envoy.filters.http.priority_load_shed, that maps a configured request header value into buckets and checks corresponding overload manager load shed points.

The filter reads a configured request header and treats its first value as the request priority. The priority value must be a non-negative integer. For example, a deployment could use a header such as x-message-priority: 10 or 3gpp-Sbi-Message-Priority: 10, then configure integer ranges that classify priorities into different shedding policies.

The parsed priority is mapped into configured priority buckets. Each bucket defines a half-open integer range, [start, end), and references an overload manager load shed point. If the parsed priority value falls within one of the configured bucket ranges and that bucket’s load shed point is currently active, the filter rejects the request locally using Envoy’s existing overload response behavior:503 Service Unavailable with the envoy overloaded body.

Requests are allowed to continue when:

the configured priority header is missing and no strict missing-header rejection is enabled
the header value is invalid and no strict invalid-header rejection is enabled
the parsed priority does not match any configured bucket and no default load shed point is configured
the matched load shed point is inactive
the referenced load shed point cannot be resolved

The filter also supports an optional default load shed point. When configured, it is used as a fallback for requests with missing, invalid, or unmatched priority values, allowing users to apply a baseline overload policy to otherwise unclassified traffic.
Note that this filter is much more configurable than the original proposal I had in the linked issue (especially when it comes to default bucket and the rejections config) , this was done in order to make it more flexible to accommodate use-cases that are not exactly the one that was described originally.

Risk Level: Low since the feature is implemented by an independent opt-in filter
Testing: Added unit and integration tests
Docs Changes: Added dedicated doc for the filter
Release Notes: Added mention in the release notes
Platform Specific Features: not present
Fixes #Issue: Close #43552

repokitteh-read-only · 2026-05-12T22:07:45Z

As a reminder, PRs marked as draft will not be automatically assigned reviewers,
or be handled by maintainer-oncall triage.

Please mark your PR as ready when you want it to be reviewed!

🐱

Caused by: #45039 was opened by leosarra.

see: more, trace.

leosarra · 2026-05-12T22:29:44Z

 /*/extensions/filters/http/local_ratelimit @mattklein123 @wbpcode
 /*/extensions/filters/common/local_ratelimit @mattklein123 @wbpcode
+# Priority load shed
+/*/extensions/filters/http/priority_load_shed @kbaichoo @botengyao


not sure who to put here, I added the maintainers involved in the review of the original issue (@KBaichoo @botengyao) . Let me know if I need to change this

Hi @leosarra, have you followed Envoy extension policy prior to implementing this extension?

Ouch, sorry I was not aware of this requirement. I will raise an issue for the proposal of this extension filter (probably it is better to not reuse the old issue) and I will check if someone is willing to sponsor it.
Then we can continue with this PR

It took a while but proposal is up here: #45993

looks like @KBaichoo is okay with sponsoring. cc @botengyao

repokitteh-read-only · 2026-05-18T07:48:16Z

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: #45039 was ready_for_review by leosarra.

see: more, trace.

leosarra · 2026-05-18T08:09:15Z

Failure in precheck looks unrelated to the changes, probably a flaky test

markdroth · 2026-05-27T22:56:24Z

/lgtm api

KBaichoo · 2026-06-02T00:18:50Z

+    // Numeric range of header values in half-open interval semantics [start, end).
+    type.v3.Int64Range value_range = 1;
+
+    // Name of the overload manager load shed point used for this bucket.
+    string load_shed_point = 2 [(validate.rules).string = {min_len: 1}];


How much range do you think we'd need e.g. do we need full Int64Range for values?
Also how many buckets do you think would be needed? For example SRE book uses 4.

Also what happens for requests above the range?

It would also be worth documenting the direction of priority.

On second thought, Int64Range is definitely overkill, but I do expect use cases where more than 4 buckets are defined. In the case of SBI Message Priority, the 3GPP standard defines 32 levels, in the worst case, someone could decide to assign a different threshold to each one.
Ideally I'd prefer to stay within the range 0–255. Since an unsigned 8-bit range isn't available in the proto, I've reduced it to Int32Range.

Also what happens for requests above the range?

If the priority header value exceeds the representable range, atoi will fail and a 400 status code is returned.

It would also be worth documenting the direction of priority.

The filter does not enforce any priority direction. The direction is dictated by how the user defines the buckets and their associated load shed points. I've added a comment to make this clear.

KBaichoo · 2026-06-02T00:19:04Z

/wait

Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Change-Id: Ica10811d9194789f25368fb2b9972dad5045aadb Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Change-Id: I66569a0d2ba12f482fdde4642dd06aa70e4e8661 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Change-Id: I486cc4769aac0dca67ae4aa7b5e3b78f73ae76ae Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Change-Id: Ie58ef7f7d4e04c38550c4e0ea2088567e6656b36 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Change reject_on_missing_header and reject_on_invalid_header from bool to google.protobuf.BoolValue so that individual data plane implementations can decide their own defaults when the fields are unset. Change-Id: I70c4231ea197b31acb56b0d5b875b4096af7a6c0 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Int64Range is overkill for priority values. Switched to Int32Range which is sufficient for the 0-255 range. Updated C++ types from int64_t to int32_t accordingly. Also added documentation for priority direction convention and unmatched request behavior. Removed reject_on_missing_header and reject_on_invalid_header options in favor of simpler behavior: reject with 400 unless default_load_shed_point is configured. Change-Id: I384f71086c215b2d41cb1c8ad3212c8db7f70471 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Removed tests for reject_on_missing_header and reject_on_invalid_header. Updated tests to expect 400 rejection when no default_load_shed_point is configured and header is missing, invalid, or unmatched. Change-Id: I4f6428a605efa153c78ee2a751309fb1316e2618 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Remove unused protobuf:utility_lib dep from BUILD. Add priority_load_shed/BUILD to visibility_excludes in format config. Change-Id: If22ef75b04762cca11c77e54c337b0ca684d73c6 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

…d equivalents Change-Id: I8a448542c5080dfa3191ae01b939d690beb85ea6 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Use context.shouldBypassOverloadManager() directly instead of context.listenerInfo().shouldBypassOverloadManager() which is only available on ListenerFactoryContext, not FactoryContext. Change-Id: I049b20e6768a1ccfd49eb8b3ea4cd0bdca90d2cf Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Change-Id: I2d32a967fd0f7a98bd56477b0c35fbfa5a576f94 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

KBaichoo

/wait

Thank you for iterating on this, took another pass at it.

Change-Id: I9c307478c75783b5b944a65e8281c54327903dfa Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Change-Id: I222367a1e0fde50ea02d13b583198a99ba1b2674 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Change-Id: I68398f78d67011c6e9f4b664bbc5f3a2b10d2113 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Change-Id: I26e5467ab1d8fc3e61c1135ee6b0771c402dc361 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Change-Id: I1616dfe74af3db148dbab720d8605bb45668f64e Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Change-Id: I90c708cf56bba5a759dfc002e3af103fda1fb6ab Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

leosarra · 2026-07-19T17:16:40Z

/wait

Most of the changes are in place. I keep it on wait until I finish some changes to the tests and doc

Change-Id: I2230a83746017a786200455999a6de98529c76d0 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

Change-Id: I10ac28ef72fcf60adcdce73c243c5477862f32bb Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

leosarra changed the title ~~Priority overload~~ http: add priority_load_shed filter for priority-based overload shedding May 12, 2026

leosarra force-pushed the priority-overload branch 2 times, most recently from 188e40b to 122e61d Compare May 12, 2026 22:14

leosarra commented May 12, 2026

View reviewed changes

repokitteh-read-only Bot added the api label May 12, 2026

leosarra force-pushed the priority-overload branch 3 times, most recently from ff0faeb to 70f7e3c Compare May 13, 2026 18:46

leosarra changed the title ~~http: add priority_load_shed filter for priority-based overload shedding~~ http: add priority_load_shed extension filter for priority-based overload shedding May 14, 2026

leosarra force-pushed the priority-overload branch 6 times, most recently from 2084996 to 6f50d48 Compare May 15, 2026 22:47

leosarra commented May 17, 2026

View reviewed changes

Comment thread source/extensions/filters/http/priority_load_shed/filter.cc Outdated

leosarra marked this pull request as ready for review May 18, 2026 07:48

repokitteh-read-only Bot assigned markdroth May 18, 2026

markdroth reviewed May 19, 2026

View reviewed changes

Comment thread api/envoy/extensions/filters/http/priority_load_shed/v3/priority_load_shed.proto Outdated

leosarra force-pushed the priority-overload branch 2 times, most recently from 6d3e244 to c14914d Compare May 19, 2026 23:49

repokitteh-read-only Bot removed the api label May 27, 2026

mattklein123 assigned KBaichoo and nezdolik May 29, 2026

KBaichoo reviewed Jun 2, 2026

View reviewed changes

leosarra added 9 commits July 6, 2026 12:59

format tests

e0a91a3

Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

fix visibility for tests

376f4fe

Change-Id: Ica10811d9194789f25368fb2b9972dad5045aadb Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

format api

6891f25

Change-Id: I66569a0d2ba12f482fdde4642dd06aa70e4e8661 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

cleanup connection in tests

584b98d

Change-Id: I486cc4769aac0dca67ae4aa7b5e3b78f73ae76ae Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

add unit tests for optional flags

2141381

Change-Id: Ie58ef7f7d4e04c38550c4e0ea2088567e6656b36 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

priority_load_shed: fix build and format check

268c64e

Remove unused protobuf:utility_lib dep from BUILD. Add priority_load_shed/BUILD to visibility_excludes in format config. Change-Id: If22ef75b04762cca11c77e54c337b0ca684d73c6 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

leosarra force-pushed the priority-overload branch from 3a9e5d8 to 268c64e Compare July 6, 2026 13:00

github-actions Bot removed the stale stalebot believes this issue/PR has not been touched recently label Jul 6, 2026

leosarra mentioned this pull request Jul 6, 2026

proposal: add extension priority_load_shed HTTP filter for header-based priority shedding #45993

Open

leosarra added 3 commits July 6, 2026 14:02

priority_load_shed: replace deprecated absl::optional/nullopt with st…

efb1357

…d equivalents Change-Id: I8a448542c5080dfa3191ae01b939d690beb85ea6 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

fix formatting

beafe6b

Change-Id: I2d32a967fd0f7a98bd56477b0c35fbfa5a576f94 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

KBaichoo reviewed Jul 10, 2026

View reviewed changes

repokitteh-read-only Bot added the waiting label Jul 10, 2026

leosarra added 6 commits July 19, 2026 17:07

reject config if load shed points are not configured

ae9056f

Change-Id: I9c307478c75783b5b944a65e8281c54327903dfa Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

move validation to create(), simplify constructor

6d7bebd

Change-Id: I222367a1e0fde50ea02d13b583198a99ba1b2674 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

remove redundant validation already handled by proto rules

c31620f

Change-Id: I68398f78d67011c6e9f4b664bbc5f3a2b10d2113 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

update docs and proto comments to reflect removal of reject_on_* APIs

46e001a

Change-Id: I26e5467ab1d8fc3e61c1135ee6b0771c402dc361 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

fix overlapping ranges test

71bc5ae

Change-Id: I1616dfe74af3db148dbab720d8605bb45668f64e Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

fix formatting

758c4f0

Change-Id: I90c708cf56bba5a759dfc002e3af103fda1fb6ab Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

repokitteh-read-only Bot removed the waiting label Jul 19, 2026

repokitteh-read-only Bot added the waiting label Jul 19, 2026

move integration tests to extension test directory

702dd07

Change-Id: I2230a83746017a786200455999a6de98529c76d0 Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

repokitteh-read-only Bot removed the waiting label Jul 26, 2026

small improvements in doc about direction

c826ad0

Change-Id: I10ac28ef72fcf60adcdce73c243c5477862f32bb Signed-off-by: Leonardo Sarra <leonardosarra96@gmail.com>

leosarra force-pushed the priority-overload branch from bc32ce8 to c826ad0 Compare July 26, 2026 16:08

Uh oh!

Conversation

leosarra commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

repokitteh-read-only Bot commented May 12, 2026

Uh oh!

leosarra May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nezdolik May 20, 2026

Choose a reason for hiding this comment

Uh oh!

leosarra May 25, 2026

Choose a reason for hiding this comment

Uh oh!

leosarra Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

nezdolik Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

repokitteh-read-only Bot commented May 18, 2026

Uh oh!

leosarra commented May 18, 2026

Uh oh!

Uh oh!

markdroth commented May 27, 2026

Uh oh!

Uh oh!

Uh oh!

KBaichoo Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

leosarra Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

KBaichoo commented Jun 2, 2026

Uh oh!

KBaichoo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

leosarra commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

leosarra commented May 12, 2026 •

edited

Loading

leosarra May 12, 2026 •

edited

Loading

leosarra commented Jul 19, 2026 •

edited

Loading