Struct SentinelProxy 

pub struct SentinelProxy {
    pub config_manager: Arc<ConfigManager>,
    /* private fields */
}

Main proxy service implementing Pingora’s ProxyHttp trait

Fields

config_manager: Arc<ConfigManager>

Configuration manager with hot reload

Implementations

impl SentinelProxy

pub async fn new(config_path: Option<&str>) -> Result<Self>

Create new proxy instance

If config_path is None, uses the embedded default configuration. Note: Tracing must be initialized by the caller before calling this function.

Trait Implementations

impl ProxyHttp for SentinelProxy

fn early_request_filter<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session: &'life1 mut Session, ctx: &'life2 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<(), Box<Error>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Early request filter - runs before upstream selection Used to handle builtin routes that don’t need an upstream connection

fn request_body_filter<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _session: &'life1 mut Session, body: &'life2 mut Option<Bytes>, end_of_stream: bool, ctx: &'life3 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<(), Box<Error>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Process incoming request body chunks. Used for body size enforcement and WAF/agent inspection.

Supports two modes:

• Buffer mode (default): Buffer chunks until end of stream or limit, then send to agents
• Stream mode: Send each chunk immediately to agents as it arrives

fn upstream_request_filter<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _session: &'life1 mut Session, upstream_request: &'life2 mut RequestHeader, ctx: &'life3 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self::CTX: Send + Sync, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Modify the request before sending to upstream. Used for header modifications, adding authentication, etc.

fn response_body_filter( &self, _session: &mut Session, body: &mut Option<Bytes>, end_of_stream: bool, ctx: &mut Self::CTX, ) -> Result<Option<Duration>, Box<Error>>

Process response body chunks from upstream. Used for response size tracking and WAF inspection.

Note: Response body inspection is currently buffered only (streaming mode not supported for responses due to Pingora’s synchronous filter design).

fn connected_to_upstream<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, _session: &'life1 mut Session, reused: bool, peer: &'life2 HttpPeer, _fd: RawFd, digest: Option<&'life3 Digest>, ctx: &'life4 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<(), Box<Error>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait,

Called when a connection to upstream is established or reused. Logs connection reuse statistics for observability.

fn request_cache_filter( &self, session: &mut Session, ctx: &mut Self::CTX, ) -> Result<()>

Decide if the request should use caching.

This method is called early in the request lifecycle to determine if the response should be served from cache or if the response should be cached.

fn cache_key_callback( &self, session: &Session, ctx: &mut Self::CTX, ) -> Result<CacheKey>

Generate the cache key for this request.

The cache key uniquely identifies the cached response. It typically includes the method, host, path, and potentially query parameters.

fn cache_miss(&self, session: &mut Session, ctx: &mut Self::CTX)

Called when a cache miss occurs.

This is called when the cache lookup found no matching entry. We can use this to log and track cache misses.

fn cache_hit_filter<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, session: &'life1 mut Session, meta: &'life2 CacheMeta, _hit_handler: &'life3 mut HitHandler, is_fresh: bool, ctx: &'life4 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<Option<ForcedInvalidationKind>>> + Send + 'async_trait>>

where Self::CTX: Send + Sync, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait,

Called after a successful cache lookup.

This filter allows inspecting the cached response before serving it. Returns None to serve the cached response, or a ForcedInvalidationKind to invalidate and refetch.

fn response_cache_filter( &self, _session: &Session, resp: &ResponseHeader, ctx: &mut Self::CTX, ) -> Result<RespCacheable>

Decide if the response should be cached.

Called after receiving the response from upstream to determine if it should be stored in the cache.

fn should_serve_stale( &self, _session: &mut Session, ctx: &mut Self::CTX, error: Option<&Error>, ) -> bool

Decide whether to serve stale content on error or during revalidation.

This implements stale-while-revalidate and stale-if-error semantics.

fn range_header_filter( &self, session: &mut Session, response: &mut ResponseHeader, ctx: &mut Self::CTX, ) -> RangeType

where Self::CTX: Send + Sync,

Handle Range header for byte-range requests (streaming support).

This method is called when a Range header is present in the request. It allows proper handling of:

• Video streaming (HTML5 video seeking)
• Large file downloads with resume support
• Partial content delivery

Uses Pingora’s built-in range handling with route-specific logging.

fn fail_to_proxy<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _session: &'life1 mut Session, e: &'life2 Error, ctx: &'life3 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = FailToProxy> + Send + 'async_trait>>

where Self::CTX: Send + Sync, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Handle fatal proxy errors by generating custom error pages. Called when the proxy itself fails to process the request.

fn error_while_proxy( &self, peer: &HttpPeer, session: &mut Session, e: Box<Error>, ctx: &mut Self::CTX, client_reused: bool, ) -> Box<Error>

Handle errors that occur during proxying after upstream connection is established.

This method enables retry logic and circuit breaker integration. It’s called when an error occurs during the request/response exchange with the upstream server.

type CTX = RequestContext

The per request object to share state across the different filters

fn new_ctx(&self) -> Self::CTX

Define how the ctx should be created.

fn fail_to_connect( &self, _session: &mut Session, peer: &HttpPeer, ctx: &mut Self::CTX, e: Box<Error>, ) -> Box<Error>

This filter is called when there is an error in the process of establishing a connection to the upstream.

fn upstream_peer<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session: &'life1 mut Session, ctx: &'life2 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<Box<HttpPeer>, Box<Error>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Define where the proxy should send the request to.

fn request_filter<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session: &'life1 mut Session, ctx: &'life2 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<bool, Box<Error>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Handle the incoming request.

fn response_filter<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _session: &'life1 mut Session, upstream_response: &'life2 mut ResponseHeader, ctx: &'life3 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<(), Box<Error>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Modify the response header before it is send to the downstream

fn logging<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, session: &'life1 mut Session, _error: Option<&'life2 Error>, ctx: &'life3 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

This filter is called when the entire response is sent to the downstream successfully or there is a fatal error that terminate the request.

fn init_downstream_modules(&self, modules: &mut HttpModules)

Set up downstream modules.

fn proxy_upstream_filter<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _session: &'life1 mut Session, _ctx: &'life2 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<bool, Box<Error>>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self::CTX: Send + Sync, Self: Sync + 'async_trait,

Decide if a request should continue to upstream after not being served from cache.

fn cache_vary_filter( &self, _meta: &CacheMeta, _ctx: &mut Self::CTX, _req: &RequestHeader, ) -> Option<[u8; 16]>

Decide how to generate cache vary key from both request and response

fn cache_not_modified_filter( &self, session: &Session, resp: &ResponseHeader, _ctx: &mut Self::CTX, ) -> Result<bool, Box<Error>>

Decide if the incoming request’s condition fails against the cached response.

fn upstream_response_filter( &self, _session: &mut Session, _upstream_response: &mut ResponseHeader, _ctx: &mut Self::CTX, ) -> Result<(), Box<Error>>

Modify the response header from the upstream

fn upstream_response_body_filter( &self, _session: &mut Session, _body: &mut Option<Bytes>, _end_of_stream: bool, _ctx: &mut Self::CTX, ) -> Result<(), Box<Error>>

Similar to Self::upstream_response_filter() but for response body

fn upstream_response_trailer_filter( &self, _session: &mut Session, _upstream_trailers: &mut HeaderMap, _ctx: &mut Self::CTX, ) -> Result<(), Box<Error>>

Similar to Self::upstream_response_filter() but for response trailers

fn response_trailer_filter<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _session: &'life1 mut Session, _upstream_trailers: &'life2 mut HeaderMap, _ctx: &'life3 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<Option<Bytes>, Box<Error>>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, Self::CTX: Send + Sync, Self: Sync + 'async_trait,

Similar to Self::response_filter() but for response trailers. Note, returning an Ok(Some(Bytes)) will result in the downstream response trailers being written to the response body.

fn suppress_error_log( &self, _session: &Session, _ctx: &Self::CTX, _error: &Error, ) -> bool

A value of true means that the log message will be suppressed. The default value is false.

fn request_summary(&self, session: &Session, _ctx: &Self::CTX) -> String

This callback is invoked every time request related error log needs to be generated

fn is_purge(&self, _session: &Session, _ctx: &Self::CTX) -> bool

Whether the request should be used to invalidate(delete) the HTTP cache

fn purge_response_filter( &self, _session: &Session, _ctx: &mut Self::CTX, _purge_status: PurgeStatus, _purge_response: &mut Cow<'static, ResponseHeader>, ) -> Result<(), Box<Error>>

This filter is called after the proxy cache generates the downstream response to the purge request (to invalidate or delete from the HTTP cache), based on the purge status, which indicates whether the request succeeded or failed.