Struct ProxyCachePlugin 

pub struct ProxyCachePlugin {
    role: Role,
    id: String,
    cache_key: Vec<Template>,
    cache_ttl: Duration,
    cache_statuses: Vec<u16>,
    cache_methods: Vec<String>,
    hide_cache_headers: bool,
    cache: Arc<dyn ResponseCache>,
    backend_label: &'static str,
    store_label: String,
    max_object_bytes: usize,
    resources: Arc<PluginResources>,
}

One node of a proxy-cache lookup/store pair.

Holds a handle to the configured ResponseCache backend; the key is derived per request from cache_key, namespaced by id.

Fields

role: Role

id: String

Shared cache namespace — links the lookup and store nodes.

cache_key: Vec<Template>

Cache-key components, each rendered (supports {{namespace.path}} references and legacy $var interpolation — see Template::render_with_legacy) and joined per request.

cache_ttl: Duration

Freshness lifetime for stored entries.

cache_statuses: Vec<u16>

Response statuses eligible for caching.

cache_methods: Vec<String>

HTTP methods eligible for caching (uppercase).

hide_cache_headers: bool

When set, hides upstream cache headers from served cache hits.

cache: Arc<dyn ResponseCache>

The backend this node pair shares, chosen by policy: the process-local cache for local, or a shared RedisResponseCache over a declared stores: entry for redis.

backend_label: &'static str

Label for the backend dimension of cache_events.

store_label: String

Label for the store dimension of cache_events: the declared store’s name for policy: redis, empty for policy: local (which has no store to name).

max_object_bytes: usize

A response body larger than this is served but never cached — one large response must not be able to fill a store that sessions, counters and ACME also live in.

resources: Arc<PluginResources>

Process-wide services, held for the metrics registry.

Implementations

impl ProxyCachePlugin

pub fn from_config( config: &HashMap<String, Value>, resources: &Arc<PluginResources>, ) -> Result<Self, String>

Builds one node of the pair from node config.

Accepted keys:

• phase / role (string, required): lookup (before upstream) or store (after upstream).
• id (string, required): shared cache namespace; the lookup and store nodes of one pair must use the same id.
• cache_key (array of string templates or a single string, default ["$request_method", "$host", "$uri"]): components rendered (supports {{namespace.path}} references plus legacy $var interpolation — see crate::vars::template::Template::render_with_legacy) and joined to form the key. Both nodes must configure it identically.
• cache_ttl (integer seconds, default 300): freshness lifetime.
• cache_http_statuses (array, default [200, 301, 404]): statuses eligible for caching. (cache_http_status, APISIX’s singular spelling, is also accepted.)
• cache_method (array, default ["GET", "HEAD"]): cacheable methods.
• hide_cache_headers (bool, default false): strip cache-control / expires from served cache hits.
• max_object_bytes (integer, default 1048576): responses larger than this are served normally but never cached, in either backend.

# before upstream
type: proxy-cache
config:
  phase: lookup
  id: catalog
  cache_key: ["$request_method", "$host", "$uri"]
  cache_ttl: 300
---
# after upstream
type: proxy-cache
config:
  phase: store
  id: catalog
  cache_key: ["$request_method", "$host", "$uri"]
  cache_ttl: 300
  cache_http_statuses: [200, 301, 404]

fn method_cacheable(&self, ctx: &Context) -> bool

Whether this request’s method is cacheable.

fn derive_key(&self, ctx: &Context) -> String

Derives the cache key: id namespace + cache_key components (each rendered via {{namespace.path}} references plus legacy $var interpolation) joined by a control-char separator (outside the character set of any header/method/path, so components can’t collide).

fn record(&self, event: &str)

Counts one cache outcome. A no-op when metrics are disabled (unit tests).

impl ProxyCachePlugin

async fn run_purge( &self, ctx: Context, ) -> Result<PluginOutput, PluginExecutionError>

Invalidates this node’s pair, independent of request method or cache key – a purge acts on the shared id namespace, not on one derived key, so neither concept applies here.

Trait Implementations

impl Plugin for ProxyCachePlugin

fn cache_target(&self) -> Option<CacheTarget>

A purge-only policy still names a real backend for its id: dedup in collect_targets makes a duplicate target (from a paired lookup/store half also naming it) harmless, and the alternative – None here – would make DELETE /api/cache/{id} 404 for an id only a purge half names, which is worse than the actual consequence: it 200s with removed: 0 when nothing else has ever cached under that id.

fn reads_response_body(&self) -> bool

Only Lookup opts out of buffering. It never reads the existing response body – on a hit it replaces ctx.response outright with the cached entry, on a miss it passes the context through untouched – and it never returns Err from execute: its only fallible call (self.cache.get) is matched and degraded to a miss, not propagated.

Store reads ctx.response.body to cache it, so it must buffer.

Purge reads nothing from the response either, but is deliberately kept buffering anyway: it can return Err from execute (run_purge, on a failed backend), and the engine’s forward streaming walk (infer_stream_capability in src/graph/engine.rs) is only sound for opt-out nodes that never do that – see the safety argument in its doc comment. Opting Purge out too would let a stream-capable upstream’s response stay live past a purge node that then routes to error, exactly the stale-response.stream-beside-a- generated-body case that invariant exists to rule out.

fn plugin_type(&self) -> &str

Unique identifier for the plugin type (e.g., “proxy-rewrite”, “upstream”). This is also the key its PortSpec is registered under in port_spec.

fn execute<'life0, 'async_trait>( &'life0 self, ctx: Context, ) -> Pin<Box<dyn Future<Output = Result<PluginOutput, PluginExecutionError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Executes the plugin logic against the request/response context.