Sharing data between filters

Static state is any immutable state specified at configuration load time (e.g., through xDS). There are three categories of static state:

Several parts of Envoy configuration (e.g. listeners, routes, clusters) contain a metadata where arbitrary key-value pairs can be encoded. The typical pattern is to use the filter names in reverse DNS format as the key and encode filter specific configuration metadata in the value. This metadata is immutable and shared across all requests/connections. Such config metadata is usually provided during bootstrap time or as part of xDS. For example, weighted clusters in HTTP routes use the metadata to indicate the labels on the endpoints corresponding to the weighted cluster. Another example, the subset load balancer uses the metadata from the route entry corresponding to the weighted cluster to select appropriate endpoints in a cluster

For example, a filter that desires to have a convenience wrapper class over an opaque metadata with key xxx.service.policy in ClusterInfo could register a factory ServicePolicyFactory that inherits from ClusterTypedMetadataFactory. The factory translates the ProtobufWkt::Struct into an instance of ServicePolicy class (inherited from FilterState::Object). When a Cluster is created, the associated ServicePolicy instance will be created and cached. Note that typed metadata is not a new source of metadata. It is obtained from metadata that is specified as part of the configuration. A FilterState::Object implements serializeAsProto method can be configured in access loggers to log it.

In HTTP routes, allows HTTP filters to have virtualhost/route-specific configuration in addition to a global filter config common to all virtual hosts. This configuration is converted and embedded into the route table. It is up to the HTTP filter implementation to treat the route-specific filter config as a replacement to global config or an enhancement. For example, the HTTP fault filter uses this technique to provide per-route fault configuration.

Dynamic State

Dynamic state is generated per network connection or per HTTP stream. Dynamic state can be mutable if desired by the filter generating the state.

Envoy::Network::Connection and Envoy::Http::Filter provide a StreamInfo object that contains information about the current TCP connection and HTTP stream (i.e., HTTP request/response pair) respectively. StreamInfo contains a set of fixed attributes as part of the class definition (e.g., HTTP protocol, requested server name, etc.). In addition, it provides a facility to store typed objects in a map (map<string, FilterState::Object>). The state stored per filter can be either write-once (immutable), or write-many (mutable).