Dynamic Modules Input Matcher (proto)

This extension has the qualified name envoy.matching.matchers.dynamic_modules

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension is not hardened and should only be used in deployments where both the downstream and upstream are trusted.

Tip

This extension extends and can be used with the following extension category:

This extension must be configured with one of the following type URLs:

extensions.matching.input_matchers.dynamic_modules.v3.DynamicModuleMatcher

[extensions.matching.input_matchers.dynamic_modules.v3.DynamicModuleMatcher proto]

Configuration for the Dynamic Modules Input Matcher. This matcher allows loading shared object files via dlopen to implement custom matching logic in dynamic modules (e.g. Rust, Go).

A module can implement arbitrary matching logic by examining request headers and other HTTP attributes during the match evaluation. This is useful for scenarios that require complex matching beyond what built-in matchers provide, such as JWT/OAuth token analysis, custom routing decisions, or integration with external data sources.

{
  "dynamic_module_config": {...},
  "matcher_name": ...,
  "matcher_config": {...},
  "on_error": ...
}
dynamic_module_config

(extensions.dynamic_modules.v3.DynamicModuleConfig, REQUIRED) Specifies the shared-object level configuration. This field is required.

matcher_name

(string) The name for this matcher configuration. If not specified, defaults to an empty string.

This can be used to distinguish between different matcher implementations inside a dynamic module. For example, a module can have completely different matcher implementations (e.g., OAuth token matcher, geo-IP matcher). When Envoy receives this configuration, it passes the matcher_name to the dynamic module’s matcher config init function together with the matcher_config. That way a module can decide which in-module matcher implementation to use based on the name at load time.

matcher_config

(Any) The configuration for the matcher chosen by matcher_name. If not specified, an empty configuration is passed to the module.

This is passed to the module’s matcher initialization function. Together with the matcher_name, the module can decide which in-module matcher implementation to use and fine-tune the behavior of the matcher.

google.protobuf.Struct and the value field of xds.type.v3.TypedStruct are serialized as JSON before passing them to the module. google.protobuf.BytesValue and google.protobuf.StringValue are passed directly without the wrapper.

on_error

(extensions.matching.input_matchers.dynamic_modules.v3.DynamicModuleMatcher.OnError) The result applied for an evaluation that the module could not complete, for example when the module’s match hook panics. A panic is caught at the ABI boundary and cannot report a match result, so the matcher applies this policy for that single evaluation. If not specified, defaults to NO_MATCH.

NO_MATCH is safe for allow-on-match trees where a missed match denies the request. MATCH is safe for deny-on-match trees where a missed match would let a request bypass the rule.

Enum extensions.matching.input_matchers.dynamic_modules.v3.DynamicModuleMatcher.OnError

[extensions.matching.input_matchers.dynamic_modules.v3.DynamicModuleMatcher.OnError proto]

The policy applied when the module cannot evaluate a match, for example after a panic in the module’s match hook.

NO_MATCH

(DEFAULT) ⁣Treat an evaluation that could not complete as no match. This is the default.

MATCH

⁣Treat an evaluation that could not complete as a match.