Documentation
¶
Overview ¶
Package extensionfilter is the single source of truth for the proxy-extension escape hatch (proposal 025): the allow-list of Envoy HTTP filters aether supports and the in-process, fail-closed validation of an HTTPFilter's opaque typed_config.
It lives in common/ (not agent/internal) because BOTH the agent (the GAMMA reconciler + the xDS proxy builders) AND the controller (the admission webhook, which cannot import the agent's internal packages) depend on it.
Index ¶
- Constants
- Variables
- func Allowed(name string) bool
- func CombineLevels(name string, vhost, route *anypb.Any) (*anypb.Any, error)
- func DefaultConfig(name string) (proto.Message, bool)
- func Render(spec *configprotov1.HTTPFilterSpec) (string, *anypb.Any, error)
- func ValidateSpec(spec *configprotov1.HTTPFilterSpec) error
- type LevelSemantics
Constants ¶
const ExtAuthzFilterName = "envoy.filters.http.ext_authz"
ExtAuthzFilterName is the external-authorization filter (proposal 027).
const HeaderMutationFilterName = "envoy.filters.http.header_mutation"
HeaderMutationFilterName is the header-mutation filter.
const HeaderToMetadataFilterName = "envoy.filters.http.header_to_metadata"
HeaderToMetadataFilterName is the Envoy filter the typed header_to_metadata authoring form renders to.
const RBACFilterName = "envoy.filters.http.rbac"
RBACFilterName is the local-authorization filter (RBAC).
Variables ¶
var ErrHeaderMutationLevelsInexact = errors.New("header_mutation: the route mutates the query and the virtual host mutates request headers or the query; " +
"the proxy applies each level whole, route first, which one config cannot")
ErrHeaderMutationLevelsInexact: a route's header_mutation mutates the query and the virtual host's mutates a request header or the query, which no single config applies in the proxy's order (combineHeaderMutation).
Functions ¶
func CombineLevels ¶
CombineLevels returns the ONE per-route config that has the effect of vhost on the virtual host plus route on the route, for an allow-listed filter. It writes to neither argument. An error means it cannot be said what the two levels amount to (a filter that is not allow-listed, or a config that does not decode): the caller must not guess, because dropping either level can drop an authorization.
func DefaultConfig ¶
DefaultConfig returns an empty default config message for an allow-listed filter (the neutral config carried on its default-disabled HCM entry), or (nil, false).
func Render ¶
func Render(spec *configprotov1.HTTPFilterSpec) (string, *anypb.Any, error)
Render resolves an HTTPFilterSpec's authoring form to the concrete Envoy filter name + typed config (proposal 025 M4): the typed headerToMetadata form is rendered to envoy.filters.http.header_to_metadata config; the opaque form passes through verbatim. Assumes ValidateSpec passed; callers on unvalidated input must check the error.
func ValidateSpec ¶
func ValidateSpec(spec *configprotov1.HTTPFilterSpec) error
ValidateSpec validates an HTTPFilterSpec fail-closed, IN-PROCESS (no Envoy binary):
- exactly ONE authoring form is set: typed (headerToMetadata) XOR opaque (filter + typedConfig) — proposal 025 M4 typed promotion;
- opaque form: spec.filter is allow-listed and spec.typedConfig resolves by its `@type` to a known Envoy message (else unknown/malformed → reject) passing its protoc-gen-validate constraints (the same `(validate.rules)` Envoy enforces);
- typed form: rules are structurally valid (rendered internally, always allow-listed by construction);
- scope CHAIN (M4: service-wide always-on) requires a Service targetRef — the "one CHAIN filter per service" invariant is enforced by the webhook (it needs the cluster view), not here.
It does NOT prove the config composes with the live chain (ordering, filter interactions) — that's the optional `envoy --mode validate` CI gate. Returns nil when the spec is admissible.
Types ¶
type LevelSemantics ¶
type LevelSemantics int
LevelSemantics says how the proxy combines a filter's virtual-host config and its route config when a request matches both.
const ( // MostSpecificLevelWins: the route's config is the whole config. MostSpecificLevelWins LevelSemantics = iota + 1 // EveryLevelApplies: the virtual host's config applies, then the route's. EveryLevelApplies // LevelsAreMerged: one config is made of the two, field by field. LevelsAreMerged )
func LevelSemanticsOf ¶
func LevelSemanticsOf(name string) (LevelSemantics, bool)
LevelSemanticsOf returns how name combines its levels; false for a filter that is not allow-listed.
Source Files