Struct Ctx 

pub struct Ctx {
    pub conn: ConnectionInfo,
    pub upstream: UpstreamInfo,
    pub timing: Timing,
    pub state: RequestState,
    pub cache: Option<Box<CacheInfo>>,
    pub features: Option<Box<Features>>,
    pub plugins: Option<Arc<[NamedPlugin]>>,
    pub response_plugins: Option<Arc<[NamedPlugin]>>,
}

Represents the state of a request/response cycle, tracking various metrics and properties including connection details, caching information, and upstream server interactions.

Fields

conn: ConnectionInfo

Information about the client connection.

upstream: UpstreamInfo

Information about the upstream server.

timing: Timing

Timing metrics for the request lifecycle.

state: RequestState

State related to the current request.

cache: Option<Box<CacheInfo>>

Cache-related information. Boxed behind an Option: most requests never touch the cache, and a None costs a pointer instead of the whole struct on every Ctx.

features: Option<Box<Features>>

Optional features, boxed for the same reason.

plugins: Option<Arc<[NamedPlugin]>>

Plugins for the current location, shared with the location’s cache of resolved plugins so a request only bumps a reference count.

response_plugins: Option<Arc<[NamedPlugin]>>

The same list, left here while the request plugins run when one of them asks to see the responses of the others (handles_plugin_response), for a plugin that writes its response itself: see crate::decorate_plugin_response.

Implementations

impl Ctx

pub fn new() -> Self

Creates a new Ctx instance with the current timestamp and default values.

Returns a new Ctx struct initialized with the current timestamp and all other fields set to their default values.

pub fn add_variable(&mut self, key: &str, value: &str)

Adds a variable to the state’s variables map with the given key and value.

Arguments

• key - The variable name.
• value - The value to store for this variable.

pub fn extend_variables(&mut self, values: AHashMap<String, String>)

Extends the variables map with the given key-value pairs.

Arguments

• values - A HashMap containing the key-value pairs to add.

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

Returns the value of a variable by key.

Arguments

• key - The key of the variable to retrieve.

Returns: Option<&str> representing the value of the variable, or None if the variable does not exist.

pub fn set_plugin_note(&mut self, name: &str, note: &'static str)

Keeps note for the plugin that calls itself name, until the request ends.

For a decision that is made once and has to hold: the request a later step sees is not the one the first step saw - a location rewrites the path, another plugin takes a parameter out of the query or changes a header - and a plugin that decided again from what is there then could come to the other answer.

pub fn get_plugin_note(&self, name: &str) -> Option<&'static str>

What Ctx::set_plugin_note kept under name.

pub fn keep_response_body_plain(&mut self, types: Option<&[String]>)

Says that a plugin reads the body of the answer to this request on its way to the client - signs it as a token, rewrites it by rules - and so has to have it as the upstream sends it.

What looks at the response before the plugins of the response step do goes by it: compression in its upstream mode, which codes the body as it arrives from the upstream, leaves such a response as it comes. Coded there, the body was opaque bytes to every plugin after it, whatever their order in the list.

types are the content types the plugin reads (prefixes, in lower case), where it reads only some: the others are none of its business and are coded as before. None is every response.

pub fn response_body_stays_plain( &self, is_of: impl FnOnce(&[String]) -> bool, ) -> bool

Whether a plugin asked for the body of this response as the upstream sends it (Ctx::keep_response_body_plain). is_of says whether the response is of one of the content types it is given.

pub fn add_modify_body_handler( &mut self, name: &str, handler: Box<dyn ModifyResponseBody>, )

Adds a modify body handler to the context.

Arguments

• name - The name of the handler.
• handler - The handler to add.

pub fn add_request_body_handler(&mut self, handler: Box<dyn HandleRequestBody>)

Has handler see the body of the request as the proxy passes it to the upstream.

pub fn get_modify_body_handler( &mut self, name: &str, ) -> Option<&mut Box<dyn ModifyResponseBody>>

Returns the modify body handler by name.

pub fn get_upstream_response_time(&self) -> Option<u32>

Returns the upstream response time if it’s less than one hour, otherwise None. This helps filter out potentially invalid or stale timing data.

Returns: Option representing milliseconds, or None if time exceeds 1 hour.

pub fn get_upstream_connect_time(&self) -> Option<u32>

Returns the upstream connect time if it’s less than one hour, otherwise None. This helps filter out potentially invalid or stale timing data.

Returns: Option representing milliseconds, or None if time exceeds 1 hour.

pub fn get_upstream_processing_time(&self) -> Option<u32>

Returns the upstream processing time if it’s less than one hour, otherwise None. This helps filter out potentially invalid or stale timing data.

Returns: Option representing milliseconds, or None if time exceeds 1 hour.

pub fn add_plugin_processing_time(&mut self, name: &Arc<str>, time: u32)

Adds a plugin processing time to the context.

Arguments

• name - The name of the plugin.
• time - The time taken by the plugin in milliseconds.

pub fn append_log_value(&self, buf: &mut BytesMut, key: &str)

Appends a formatted value to the provided log buffer based on the given key. Handles various metrics including connection info, timing data, and TLS details.

Resolves key on every call; a caller that knows the key ahead of time (the access log format) should parse it into a CtxLogField once and use Ctx::append_log_field.

Arguments

• buf - The BytesMut buffer to append the value to.
• key - The key identifying which state value to format and append.

pub fn append_log_field(&self, buf: &mut BytesMut, field: CtxLogField)

Appends the value of field to the log buffer.

pub fn generate_server_timing(&self) -> String

Generates a Server-Timing header value based on the context’s timing metrics.

The Server-Timing header allows servers to communicate performance metrics about the request-response cycle to the client. This implementation includes various timing metrics like connection time, processing time, and cache operations.

Returns a String containing the formatted Server-Timing header value.

pub fn push_cache_key(&mut self, key: String)

Pushes a single cache key component to the context.

pub fn extend_cache_keys(&mut self, keys: Vec<String>)

Extends the cache key components with a vector of keys.

pub fn push_cache_key_variant( &mut self, current: Vec<String>, alternatives: Arc<Vec<Vec<String>>>, )

Adds current to the cache key as the one of alternatives this request stands for. It may be empty: the place is noted all the same, for the request that has to know what else could be there.

pub fn cache_key_alternatives(&self) -> Vec<Vec<String>>

Every list of key components a request for this url can have: the one of this request, with each CacheKeyVariant in it replaced by each of its alternatives. The list of this request itself when it has no variants, or when there would be too many lists to go through.

pub fn update_upstream_timing_from_digest( &mut self, digest: &Digest, reused: bool, )

Updates the upstream timing from the digest.

Trait Implementations

impl Default for Ctx

fn default() -> Self

Returns the “default value” for a type.