Struct Server 

pub struct Server { /* private fields */ }

Core HTTP proxy server implementation that handles request processing, caching, and monitoring. Manages server configuration, connection lifecycle, and integration with various modules.

Implementations

impl Server

pub fn new(conf: &ServerConf, ctx: AppContext) -> Result<Self, Error>

Creates a new HTTP proxy server instance with the given configuration. Initializes all server components including:

• TCP socket options
• TLS settings
• Prometheus metrics (if enabled)
• Threading configuration

pub fn enable_lets_encrypt(&mut self)

Enable lets encrypt proxy plugin for handling ACME challenges at /.well-known/acme-challenge path

pub fn get_prometheus_push_service(&self) -> Option<Box<dyn BackgroundTask>>

Get the prometheus push service configuration if enabled. Returns a tuple of (metrics endpoint, service future) if push mode is configured.

pub fn run(self, conf: Arc<ServerConf>) -> Result<ServerServices, Error>

Starts the server and sets up TCP/TLS listening endpoints.

• Configures listeners for each address
• Sets up TLS if enabled
• Initializes HTTP/2 support
• Configures thread pool

impl Server

pub async fn handle_request_plugin( &self, step: PluginStep, session: &mut Session, ctx: &mut Ctx, ) -> Result<bool>

Executes request plugins in the configured chain Returns true if a plugin handled the request completely

pub async fn handle_response_plugin( &self, session: &mut Session, ctx: &mut Ctx, upstream_response: &mut ResponseHeader, ) -> Result<()>

Run response plugins

pub fn handle_upstream_response_plugin( &self, session: &mut Session, ctx: &mut Ctx, upstream_response: &mut ResponseHeader, ) -> Result<()>

pub fn handle_upstream_response_body_plugin( &self, session: &mut Session, ctx: &mut Ctx, body: &mut Option<Bytes>, end_of_stream: bool, ) -> Result<()>

pub fn handle_response_body_plugin( &self, session: &mut Session, ctx: &mut Ctx, body: &mut Option<Bytes>, end_of_stream: bool, ) -> Result<()>

Trait Implementations

impl ProxyHttp for Server

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<()>> + Send + 'async_trait>>

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

Handles early request processing before main request handling. Key responsibilities:

• Sets up connection tracking and metrics
• Records timing information
• Initializes OpenTelemetry tracing
• Matches request to location configuration
• Validates request parameters
• Initializes compression and gRPC modules if needed

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>> + Send + 'async_trait>>

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

Main request processing filter. Handles:

• Admin interface requests
• Let’s Encrypt certificate challenges
• Location-specific processing
• URL rewriting
• Plugin execution

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>> + Send + 'async_trait>>

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

Filters requests before sending to upstream. Allows modifying request before proxying.

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

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

Selects and configures the upstream peer to proxy to. Handles upstream connection pooling and health checking.

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<()>> + 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 when connection is established to upstream. Records timing metrics and TLS details.

fn upstream_request_filter<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, session: &'life1 mut Session, upstream_response: &'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,

Filters upstream request before sending. Adds proxy headers and performs any request modifications.

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<()>> + Send + 'async_trait>>

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

Filters request body chunks before sending upstream. Tracks payload size and enforces size limits.

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

Generates cache keys for request caching. Combines:

• Cache namespace
• Request method
• URL path and query
• Optional custom prefix

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

Determines if and how responses should be cached. Checks:

• Cache-Control headers
• TTL settings
• Cache privacy settings
• Custom cache control directives

fn upstream_response_body_filter( &self, session: &mut Session, body: &mut Option<Bytes>, end_of_stream: bool, ctx: &mut Self::CTX, ) -> Result<Option<Duration>>

Filters upstream response body chunks. Records timing metrics and finalizes spans.

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

where Self::CTX: Send + Sync,

Final filter for response body before sending to client. Handles response body modifications and compression.

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,

Handles proxy failures and generates appropriate error responses. Error handling for:

• Upstream connection failures (502, 504)
• Client timeouts (408)
• Client disconnections (499) Generates error pages using configured template

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

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

Performs request logging and cleanup after request completion. Handles:

• Request counting cleanup
• Compression statistics
• Prometheus metrics
• OpenTelemetry span completion
• Access logging

type CTX = Ctx

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 init_downstream_modules(&self, modules: &mut HttpModules)

Set up downstream modules.

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 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<()>> + 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 response header before it is send to the downstream

fn upstream_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<()>> + Send + 'async_trait>>

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

Modify the response header from the upstream

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

where Self::CTX: Send + Sync,

Returns whether this session is allowed to spawn subrequests.

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

where Self::CTX: Send + Sync,

This filter decides if the request is cacheable and what cache backend to use

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

This callback is invoked when a cacheable response is ready to be admitted to cache.

fn cache_hit_filter<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, _session: &'life1 mut Session, _meta: &'life2 CacheMeta, _hit_handler: &'life3 mut Box<dyn HandleHit + Send + Sync>, _is_fresh: bool, _ctx: &'life4 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<Option<ForcedFreshness>, Box<Error>>> + Send + 'async_trait>>

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

This filter is called after a successful cache lookup and before the cache asset is ready to be used.

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 range_header_filter( &self, session: &mut Session, resp: &mut ResponseHeader, _ctx: &mut Self::CTX, ) -> RangeType

This filter is called when cache is enabled to determine what byte range to return (in both cache hit and miss cases) from the response body. It is only used when caching is enabled, otherwise the upstream is responsible for any filtering. It allows users to define the range this request is for via its return type range_filter::RangeType.

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 error_while_proxy( &self, peer: &HttpPeer, session: &mut Session, e: Box<Error>, _ctx: &mut Self::CTX, client_reused: bool, ) -> Box<Error>

This filter is called when there is an error after a connection is established (or reused) to the upstream.

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

Decide whether should serve stale when encountering an error or during revalidation

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.