Caching

Overview

coreX Manager provides a two-tier cache for HTTP responses:

1. Memory Cache (L1) — HAProxy’s native in-memory cache. Fast, limited by available RAM.
2. Disk Cache (L2) — A file-backed cache sidecar. Larger capacity, persistent across restarts.

Both tiers are configured per backend, allowing different caching strategies for different upstream services.

Memory Cache

The memory cache uses HAProxy’s native cache sections. Configuration:

Setting	Description
total_max_size	Maximum total cache size in bytes
max_object_size	Maximum size of a single cached object
max_age	Maximum age of cached objects in seconds
process_vary	Honor the Vary header for variant caching
max_secondary_entries	Maximum number of Vary variants per entry
cache_condition	Optional HAProxy ACL condition for cacheability

Disk Cache

The disk cache runs as a sidecar container. Configuration:

Setting	Description
disk_cache_ttl	Default TTL for cached objects
disk_cache_grace	Grace period for serving stale objects
disk_cache_purge_enabled	Enable cache purging

The disk cache is gated by the global disk_cache_enabled toggle. On a cache miss, the disk cache fetches through HAProxy so that response filters (compression, WebP conversion, transforms) run before the response is cached.

Cacheability Rules

Cacheability rules are ordered, first-match-wins rules that decide what gets cached. Each rule has:

Property	Description
Match type	path (prefix), filename (exact final segment), extension (case-insensitive)
Match value	The path prefix, filename, or extension to match
Action	cache or bypass
Tier	memory or disk

Cache Clearing

Cache can be cleared:

• Per backend — clear the cache for a specific backend
• All caches — clear all caches across all backends

Memory cache clearing uses the HAProxy admin socket. Disk cache clearing uses BAN requests to the Varnish sidecar.

Cache Metrics

Cache metrics are sampled every 30 seconds:

• Hit rate
• Number of objects
• Total bytes cached

Available via the API and displayed in the metrics dashboard.

Step-by-Step: Enable Memory Cache

1. Navigate to Core > Backends and open the backend you want to cache
2. Scroll to Cache Configuration
3. Enable Memory Cache
4. Set max_object_size to 1MB (or appropriate for your content)
5. Set max_age to 3600 (1 hour)
6. Enable process_vary (recommended)
7. Save

Step-by-Step: Add Cacheability Rules

1. In the backend’s Cacheability Rules section, click Add Rule
2. Add a rule for static assets:
   • Match type: extension
   • Match value: css,js,png,jpg,gif,svg,woff,woff2
   • Action: cache
   • Tier: memory
3. Add a bypass rule for dynamic content:
   • Match type: path
   • Match value: /api/
   • Action: bypass
4. Save and Apply

Step-by-Step: Enable Disk Cache

1. Navigate to Settings > Global Options
2. Enable disk_cache_enabled
3. Open the backend and scroll to Disk Cache Configuration
4. Set disk_cache_ttl to 3600 (1 hour)
5. Set disk_cache_grace to 600 (10 minutes — serve stale while refreshing)
6. Enable disk_cache_purge_enabled
7. Add a cacheability rule with tier disk for large static files:
   • Match type: extension
   • Match value: mp4,zip,pdf
   • Action: cache
   • Tier: disk
8. Save and Apply

Verification

1. Test cache hit:

   # First request (cache miss)
   curl -k -sI https://localhost/style.css | grep -i 'age\|cache\|x-cache'
   # Second request (cache hit)
   curl -k -sI https://localhost/style.css | grep -i 'age\|cache\|x-cache'

   The second request should show a cache hit indicator.

2. Check cache metrics:

   • Navigate to Observability > Metrics > Cache
   • Verify hit rate, object count, and bytes

3. Test cache clearing:

   # Clear cache for a backend
   curl -k -X POST https://localhost/api/cache/clear/backend-name

   Subsequent requests should be cache misses.

Next Steps

• Compression — Compress cached responses
• Image Conversion — Convert images to WebP before caching
• Metrics & Logging — Monitor cache hit rates