Struct HttpFilterContext 

pub struct HttpFilterContext<'a> {

    pub body_done_indices: Vec<bool>,
    pub branch_iterations: HashMap<Arc<str>, u32>,
    pub client_addr: Option<IpAddr>,
    pub cluster: Option<Arc<str>>,
    pub current_filter_id: Option<usize>,
    pub downstream_tls: bool,
    pub extensions: RequestExtensions,
    pub executed_filter_indices: Vec<bool>,
    pub extra_request_headers: Vec<(Cow<'static, str>, String)>,
    pub request_headers_to_remove: Vec<HeaderName>,
    pub request_headers_to_set: Vec<(HeaderName, HeaderValue)>,
    pub filter_metadata: HashMap<String, String>,
    pub filter_results: HashMap<&'static str, FilterResultSet>,
    pub filter_state: HashMap<usize, Box<dyn Any + Send + Sync>>,
    pub health_registry: Option<&'a HealthRegistry>,
    pub id_generator: &'a IdGenerator,
    pub kv_stores: Option<&'a KvStoreRegistry>,
    pub request: &'a Request,
    pub request_body_bytes: u64,
    pub request_body_mode: BodyMode,
    pub request_start: Instant,
    pub response_body_bytes: u64,
    pub response_body_mode: BodyMode,
    pub response_header: Option<&'a mut Response>,
    pub response_headers_modified: bool,
    pub selected_endpoint_index: Option<usize>,
    pub time_source: &'a dyn TimeSource,
    pub rewritten_path: Option<String>,
    pub upstream: Option<Upstream>,
}

Per-request mutable state shared across all HTTP filters.

Created by the protocol layer for each incoming request. Filters read and mutate it to select clusters, choose upstreams, and inject headers.

Fields

body_done_indices: Vec<bool>

Per-filter body-done tracking. When true at index i, filter i is skipped for remaining body chunks.

branch_iterations: HashMap<Arc<str>, u32>

Iteration counters for re-entrant branches. Branch name -> current iteration count.

client_addr: Option<IpAddr>

Downstream client IP address (from the TCP connection).

cluster: Option<Arc<str>>

The cluster name selected by the router filter.

current_filter_id: Option<usize>

Stable invocation ID of the filter currently executing.

Assigned at pipeline build time and unique within the request’s pinned FilterPipeline. Set by the pipeline executor before each filter hook call and cleared after. Filter state accessors use this as the storage key so that multiple instances of the same filter type — including filters in branch chains — get independent state.

downstream_tls: bool

Whether the downstream connection uses TLS.

Set by the protocol layer from the connection’s SSL digest. Used by the forwarded headers filter to derive X-Forwarded-Proto from the actual connection state rather than the request URI scheme (which is absent in HTTP/1.1).

extensions: RequestExtensions

Type-safe request-scoped extension container.

Filters store and retrieve arbitrary typed values that persist across all Pingora lifecycle phases (request, request body, response, response body, logging). Keyed by TypeId, so only one value per concrete type. Use private newtypes to avoid collisions between independent filters.

executed_filter_indices: Vec<bool>

Tracks which pipeline filter indices actually executed during the request phase. The response phase skips filters that did not run (e.g. due to SkipTo).

extra_request_headers: Vec<(Cow<'static, str>, String)>

Extra headers to inject into the upstream request.

request_headers_to_remove: Vec<HeaderName>

Headers to remove from the upstream request.

request_headers_to_set: Vec<(HeaderName, HeaderValue)>

Headers to set (overwrite) on the upstream request.

filter_metadata: HashMap<String, String>

Durable per-request metadata that persists across all Pingora lifecycle phases (request, request-body, response, response-body, logging). Unlike filter_results which are cleared after branch evaluation, metadata survives for the entire request lifetime.

Keys use dot-prefix namespacing by convention (e.g. json_rpc.kind, classifier.label).

filter_results: HashMap<&'static str, FilterResultSet>

Filter result map: filter_name -> result entries.

Filters write string key-value pairs here during on_request or on_response. The pipeline executor reads these to evaluate branch conditions. Cleared after branch evaluation at each filter.

filter_state: HashMap<usize, Box<dyn Any + Send + Sync>>

Typed per-filter state that persists across all lifecycle phases (request, request-body, response, response-body).

Keyed by stable filter invocation ID, unique within the request’s pinned FilterPipeline. Swapped into each HttpFilterContext from the protocol-layer request context and written back after filter execution, following the same pattern as filter_metadata.

health_registry: Option<&'a HealthRegistry>

Shared health registry for endpoint health lookups.

id_generator: &'a IdGenerator

Shared request ID generator.

kv_stores: Option<&'a KvStoreRegistry>

Named key-value stores for runtime mappings.

request: &'a Request

Transport-agnostic request headers, URI, and method.

request_body_bytes: u64

Accumulated request body bytes seen so far.

request_body_mode: BodyMode

Per-request body delivery mode for the request direction. Defaults to BodyMode::Stream; filters may upgrade it via set_request_body_mode.

request_start: Instant

When the request was received; available in all phases.

response_body_bytes: u64

Accumulated response body bytes seen so far.

response_body_mode: BodyMode

Per-request body delivery mode for the response direction. Defaults to BodyMode::Stream; filters may upgrade it via set_response_body_mode.

response_header: Option<&'a mut Response>

The upstream response headers, available during on_response. None during the request phase.

response_headers_modified: bool

Whether any filter modified the response headers during on_response. Used to skip unnecessary work.

selected_endpoint_index: Option<usize>

Index of the selected endpoint in the cluster’s endpoint list. Set by the load balancer filter for use by passive health checking in the protocol layer.

time_source: &'a dyn TimeSource

Wall-clock time source for timestamp generation.

rewritten_path: Option<String>

Rewritten URI path for the upstream request.

Set by the path_rewrite or url_rewrite filter during on_request. Applied to the upstream RequestHeader in the protocol layer.

The router checks this field before the original request URI. If a preceding filter sets rewritten_path, the router matches against it, enabling “rewrite then route” pipelines.

If both path_rewrite and url_rewrite appear in the same pipeline, only the last writer’s value takes effect. Pipeline validation rejects this by default; set allow_rewrite_override: true on the later filter to permit it. Or, better yet, don’t.

upstream: Option<Upstream>

The upstream peer selected by the load balancer filter.

Implementations

impl HttpFilterContext<'_>

pub fn cluster_name(&self) -> Option<&str>

Selected cluster name, if any.

pub fn upstream_addr(&self) -> Option<&str>

Upstream peer address, if selected.

pub fn get_metadata(&self, key: &str) -> Option<&str>

Read a durable metadata value by key.

pub fn request_id(&self) -> Option<&str>

X-Request-ID header value, if present and valid UTF-8.

pub fn set_metadata(&mut self, key: impl Into<String>, value: impl Into<String>)

Write a durable metadata value that persists across all phases.

Keys should use dot-prefix namespacing (e.g. json_rpc.kind, classifier.label). Keys are limited to 64 bytes and values to 256 bytes to bound per-request memory growth.

pub fn set_request_body_mode(&mut self, mode: BodyMode)

Upgrade the request body delivery mode for this request.

Merges mode into the current mode using ratchet-up semantics: StreamBuffer > SizeLimit > Stream. A mode can only be upgraded, never downgraded.

pub fn set_response_body_mode(&mut self, mode: BodyMode)

Upgrade the response body delivery mode for this request.

Same ratchet-up semantics as set_request_body_mode.

pub fn insert_filter_state<T: Any + Send + Sync>(&mut self, state: T)

Store typed per-request state for the currently executing filter.

Uses current_filter_id as the storage key, so multiple instances of the same filter type get independent state.

No-op if called outside of pipeline execution (when current_filter_id is None).

pub fn get_filter_state<T: Any + Send + Sync>(&self) -> Option<&T>

Retrieve a shared reference to the typed state stored by the currently executing filter.

Returns None when no state is stored, when the stored type does not match T, or when called outside pipeline execution.

pub fn get_filter_state_mut<T: Any + Send + Sync>(&mut self) -> Option<&mut T>

Retrieve a mutable reference to the typed state stored by the currently executing filter.

Returns None under the same conditions as get_filter_state.

pub fn remove_filter_state<T: Any + Send + Sync>(&mut self) -> Option<T>

Remove and return the typed state stored by the currently executing filter.

Returns None when no state is stored, when the stored type does not match T, or when called outside pipeline execution. A type mismatch does not destroy the stored entry.