Cache Purge API

bext provides a cache purge API that's compatible with nginx's NJS-based cache purge module. If you have scripts or deployment hooks that purge nginx's proxy cache, they work with bext unchanged.

Configuration

The cache purge API runs on a separate port (default 8442):

The API respects nginx's levels=1:2 directory layout for cache key storage.

Endpoints

Purge Specific Paths

POST /nginx-cache/purge
Content-Type: application/json

{
  "host": "example.com",
  "paths": ["/api/products", "/api/categories"]
}

Deletes the cache entries for the specified host + path combinations.

Purge by Pattern

POST /nginx-cache/purge-pattern
Content-Type: application/json

{
  "host": "example.com",
  "pattern": "X-Cache-Tag: products"
}

Scans cache entries and deletes those matching the header pattern for the given host.

Purge All

POST /nginx-cache/purge-all

Wipes the entire cache directory.

Cache Status

GET /nginx-cache/status

Returns cache directory statistics:

{
  "cache_dir": "/var/cache/nginx/page_cache",
  "total_entries": 1247,
  "total_size_bytes": 52428800,
  "oldest_entry": "2026-01-15T10:30:00Z"
}

Cache Key Hashing

bext uses the same MD5-based key hashing as nginx:

1. The cache key (e.g., GETexample.com/api/products) is MD5-hashed 2. The hash is mapped to a file path using the levels=1:2 layout:

Hash: d41d8cd98f00b204e9800998ecf8427e

Path: /var/cache/nginx/page_cache/e/27/d41d8cd98f00b204e9800998ecf8427e
                                  ^  ^^
                                  |  |+-- last 2 hex chars before last 1
                                  |  +--- levels=1:2 second level
                                  +------ levels=1:2 first level

Integration with Deployment Scripts

If you have existing purge scripts that call nginx's cache purge:

#!/bin/bash
# deploy.sh — works with both nginx NJS and bext
curl -X POST http://localhost:8442/nginx-cache/purge \
  -H "Content-Type: application/json" \
  -d '{"host": "example.com", "paths": ["/"]}'

No changes needed — the API is compatible.