http: new filter chain filter #42912

wbpcode · 2026-01-08T15:17:25Z

Commit Message: http: new filter chain filter
Additional Description:

New filter to configured multiple sub filter chains and allow the route to select one or provide a inline sub filter chain.

This PR gives the actual per route level filter chain support. We only need to ensure most filters could support the createFilterFactoryFromProtoWithServerContext.

This filter is a little similar to composite, but with following difference:

provides full feature sub filter chain support.
not as flexible as composite filter, only the initial route could be used to help to select the sub filter chain, but more easier to use and more robust for lots scenarios.

Risk Level: low. new filter.
Testing: unit/integration.
Docs Changes: added.
Release Notes: added.
Platform Specific Features: n/a.

Signed-off-by: wbpcode/wangbaiping <[email protected]>

repokitteh-read-only · 2026-01-08T15:17:35Z

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

🐱

Caused by: #42912 was opened by wbpcode.

see: more, trace.

Signed-off-by: wbpcode/wangbaiping <[email protected]>

wbpcode · 2026-01-09T10:26:56Z

I like it, CI are all green.

adisuissa

Thanks.
Left a few high-level comments.
This should probably be reviewed by the rest of the api shepherds.
cc @markdroth

api/envoy/extensions/filters/http/filter_chain/v3/filter_chain.proto

adisuissa · 2026-01-15T16:19:09Z

api/envoy/extensions/filters/http/filter_chain/v3/filter_chain.proto

+
+  // Map of named filter chains. The key is an arbitrary name assigned to the filter chain.
+  // These named filter chains can be referenced by the per-route configuration using
+  // the filter_chain_name field in FilterChainConfigPerRoute.


I think there's an implementation detail that should be highlighted here:
all the filters (in all the chains) will be initialized even if not used.
This will cause some confusion especially as some filters of the same type that appear in two different chains will not have a shared state.

I will update the comment to make it more clear.

adisuissa · 2026-01-15T16:20:31Z

api/envoy/extensions/filters/http/filter_chain/v3/filter_chain.proto

+  // Each filter in the chain will process the request/response in sequence.
+  // At least one filter must be specified.
+  // [#extension-category: envoy.filters.http]
+  repeated config.core.v3.TypedExtensionConfig filters = 1


As this is a filter chain, what were the design tradeoffs between typed-extension and Filter types here?

Sorry, what you mean by Filter types? We prefer to use the TypedExtensionConfig in most cases I think?

adisuissa · 2026-01-15T16:22:04Z

api/envoy/extensions/filters/http/filter_chain/v3/filter_chain.proto

+  // If specified, this filter chain takes precedence over filter_chain_name.
+  FilterChain filter_chain = 1;
+
+  // Name of the filter chain to be applied on this route. This name should match


I'm trying to understand what's the difference between this and the Composite filter, and all I see is that the matching is done on a route override rather than in the HCM filter chain. Is that correct?

I see that it was referenced in the PR description:

This filter is a little similar to composite, but with following difference:

provides full feature sub filter chain support.

not as flexible as composite filter, only the initial route could be used to help to select the sub filter chain, but more easier to use and more robust for lots scenarios.

What I wonder is whether the referencing by name can be done with a different design that allows referencing global named filters which will help multi-tenant deployments that have shared filters across listeners.

What I wonder is whether the referencing by name can be done with a different design that allows referencing global named filters which will help multi-tenant deployments that have shared filters across listeners.

I think it's a little hard because we need to add a filter chain map at the bootstrap that means we cannot update it dynamically by the xDS?

api/envoy/extensions/filters/http/filter_chain/v3/filter_chain.proto

Signed-off-by: wbpcode <[email protected]>

… dev-new-filter-chain-filter

agrawroh

Looks great! Just some minor comments/questions. Thank you so much for working on this. We really need this to organize our filter chains.

source/extensions/filters/http/filter_chain/filter.cc

agrawroh · 2026-01-19T02:47:25Z

api/envoy/extensions/filters/http/filter_chain/v3/filter_chain.proto

+  //
+  // This field is optional. If not specified and no route-level configuration matches,
+  // the filter will pass through without applying any additional filters.
+  FilterChain filter_chain = 1;


Should we add a warning (and also validation) that configuring envoy.filters.http.filter_chain recursively within its own filter chains is not supported.

agrawroh · 2026-01-19T02:48:54Z

api/envoy/extensions/filters/http/filter_chain/v3/filter_chain.proto

+  // Each filter in the chain will process the request/response in sequence.
+  // At least one filter must be specified.
+  // [#extension-category: envoy.filters.http]
+  repeated config.core.v3.TypedExtensionConfig filters = 1


I think we should also add a note on how the filters across all the named chains and the default chain are compiled and initialized. AFAIK they are all initialized at configuration time, regardless of runtime usage. Is that right?

I am not sure whether it make sense or not. Because all filters absolutely will be initialized/loaded because it's part of configuration loading? So, I think we may needn't that redundant description?

agrawroh · 2026-01-19T02:50:21Z

source/extensions/filters/http/filter_chain/filter.cc

+}
+
+// Helper to process filter config and create filter factories
+Http::FilterChainUtility::FilterFactoriesList createFilterFactoriesFromConfig(


Hmmm, looks like we have two versions of createFilterFactoriesFromConfig with different arguments. Is it possible to create a template helper?

Hmmm, it's some difference between the server context version and factory context version. Template may couldn't simplify too much.

source/extensions/filters/http/filter_chain/filter.cc

agrawroh · 2026-01-19T02:54:04Z

test/extensions/filters/http/filter_chain/filter_test.cc

+      - name: mock_filter
+        typed_config:
+          "@type": type.googleapis.com/google.protobuf.Struct
+      - name: another_filter


Looks like this is unregistered and currently per the implementation if a per-route config references a non-existent filter chain name, we seems to be silently falls back to the default. Do we need to do any config-time validation or have any counter which records this?

Stats SGTM. I don't think we could do any validation at config-time because the route configuration could be shared across listeners.

agrawroh · 2026-01-19T02:54:54Z

api/envoy/extensions/filters/http/filter_chain/v3/filter_chain.proto

+  // Each filter in the chain will process the request/response in sequence.
+  // At least one filter must be specified.
+  // [#extension-category: envoy.filters.http]
+  repeated config.core.v3.TypedExtensionConfig filters = 1


I'm assuming that we won't be able to support ECDS here. Is that right?

Yeah, because TypedExtensionConfig rather then the HttpFilter is used here and I have no plan to make the feature too complex.

agrawroh · 2026-01-19T02:56:28Z

source/extensions/filters/http/filter_chain/filter.cc

@@ -0,0 +1,107 @@
+#include "source/extensions/filters/http/filter_chain/filter.h"


Our main filter chain also validates the terminal filters but our new filter does not. It's possible that the users could configure the router filter inside a sub-chain which would lead to an undefined behavior.

Yeah. It's possible. I will document it rather than to make the code more complex.

Signed-off-by: wbpcode <[email protected]>

Signed-off-by: wbpcode/wangbaiping <[email protected]>

ramaraochavali · 2026-01-19T15:05:10Z

docs/root/configuration/http/http_filters/filter_chain_filter.rst

+
+.. code-block:: yaml
+
+  http_filters:


Does WASM filter works with this per route config?

http: new filter chain filter

0f91aca

Signed-off-by: wbpcode/wangbaiping <[email protected]>

wbpcode requested a review from yanavlasov as a code owner January 8, 2026 15:17

repokitteh-read-only bot added the api label Jan 8, 2026

repokitteh-read-only bot assigned adisuissa Jan 8, 2026

wbpcode assigned agrawroh and unassigned adisuissa Jan 8, 2026

minor update

bc43811

Signed-off-by: wbpcode/wangbaiping <[email protected]>

wbpcode mentioned this pull request Jan 11, 2026

feat: xds policy metadata envoyproxy/gateway#7824

Open

wbpcode assigned adisuissa Jan 12, 2026

adisuissa reviewed Jan 15, 2026

View reviewed changes

wbpcode added 2 commits January 18, 2026 15:10

address comments

f752dc9

Signed-off-by: wbpcode <[email protected]>

Merge branch 'main' of ssh://ssh.github.com:443/envoyproxy/envoy into…

38333da

… dev-new-filter-chain-filter

agrawroh reviewed Jan 19, 2026

View reviewed changes

wbpcode added 3 commits January 19, 2026 03:18

fix format

5b5ce0b

Signed-off-by: wbpcode <[email protected]>

add stats and address comments

8eca506

Signed-off-by: wbpcode <[email protected]>

fix test

6ac1f45

Signed-off-by: wbpcode/wangbaiping <[email protected]>

ramaraochavali reviewed Jan 19, 2026

View reviewed changes

		@@ -0,0 +1,107 @@
		#include "source/extensions/filters/http/filter_chain/filter.h"

http: new filter chain filter #42912

Are you sure you want to change the base?

http: new filter chain filter #42912

Uh oh!

Conversation

wbpcode commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

repokitteh-read-only bot commented Jan 8, 2026

Uh oh!

wbpcode commented Jan 9, 2026

Uh oh!

adisuissa left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

agrawroh left a comment • 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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wbpcode Jan 19, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wbpcode Jan 19, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

wbpcode commented Jan 8, 2026 •

edited

Loading

agrawroh left a comment •

edited

Loading

wbpcode Jan 19, 2026 •

edited

Loading

wbpcode Jan 19, 2026 •

edited

Loading