CHANGELOG.md

Changelog

v0.2.11

Release date: 2026-04-03

Added

• Bulk control endpoints for cache invalidation and snapshot management. The control server now supports batched operations with shared optional server targeting and per-item result reporting:
  • POST /bulk_invalidate — invalidate multiple wildcard patterns in one request with { "patterns": ["/api/*", "/blog/*"], "server": "frontend" }.
  • POST /bulk_add_snapshot — add multiple snapshot paths in one request with { "paths": ["/about", "/pricing"], "server": "frontend" }.
  • POST /bulk_refresh_snapshot — refresh multiple tracked snapshot paths in one request.
  • POST /bulk_remove_snapshot — remove multiple tracked snapshot paths in one request.
• Bulk control responses now return aggregate counts plus per-item success and error details so clients can handle partial failures without losing successful work.

Changed

• Bulk snapshot actions now execute asynchronously per path. bulk_add_snapshot, bulk_refresh_snapshot, and bulk_remove_snapshot no longer process request items one-by-one; each path is dispatched concurrently and results are collected back into a stable response payload.
• README control-endpoint documentation now reflects the current control API, including the long-standing /invalidate_all route and the new bulk endpoints.

v0.2.10

Release date: 2026-03-26

Fixed

• Snapshot broadcast returns an error when no PreGenerate servers are available. Previously, calling /add_snapshot, /refresh_snapshot, /remove_snapshot, or /refresh_all_snapshots without a "server" field would silently succeed (returning 200 OK) when all configured servers are in Dynamic mode. Now returns 400 Bad Request with "No servers running in PreGenerate mode — snapshot operations are not available".

v0.2.9

Release date: 2026-03-26

Fixed

• Snapshot broadcast no longer errors on Dynamic-mode servers. When POST /add_snapshot, /refresh_snapshot, /remove_snapshot, or /refresh_all_snapshots is called without a "server" field, Dynamic-mode servers are now silently skipped. Previously the first Dynamic-mode handle in the list caused a 400 Bad Request, preventing the snapshot from being added to any PreGenerate server.
• Added CacheHandle::is_snapshot_capable() helper to distinguish PreGenerate handles from Dynamic ones without calling into the worker.

v0.2.8

Release date: 2026-03-26

Added

• Optional server field on all control-plane endpoints. Snapshot and invalidation requests now accept an optional "server" field in the JSON body to target a specific named server. When omitted, the operation is broadcast to all servers (previous behaviour preserved).
  • POST /invalidate — { "pattern": "/api/*", "server": "frontend" }
  • POST /add_snapshot — { "path": "/about", "server": "frontend" }
  • POST /refresh_snapshot — { "path": "/about", "server": "frontend" }
  • POST /remove_snapshot — { "path": "/about", "server": "frontend" }
  • POST /refresh_all_snapshots — { "server": "frontend" }
  • Returns 404 if the given server name does not exist.

Changed

• ControlState now stores Vec<(String, CacheHandle)> (name + handle) instead of Vec<CacheHandle>. The create_control_router function signature is updated accordingly — this only affects code using phantom-frame as a library that calls create_control_router directly.

v0.2.7

Release date: 2026-03-26

Added

• cache_key webhook type. A new type = "cache_key" webhook makes phantom-frame POST the request metadata to a URL and use the plain-text response body as the cache key for that request (both for the cache read and the subsequent cache write). On failure, a non-2xx response, a timeout, or an empty body, the default cache key (method:path?query) is used instead — the request is never denied by a cache_key webhook. Works in both Dynamic and PreGenerate modes.
• Redirect passthrough for blocking webhooks. When a blocking webhook returns a 3xx status, phantom-frame now forwards the redirect to the client with the Location header intact (e.g. 302 + Location: /login). Redirects are not followed internally. Previously, 3xx responses from the webhook server were silently followed by reqwest, masking the redirect entirely.

Changed

• call_webhook (internal) now disables reqwest's automatic redirect following (redirect::Policy::none()) and returns a richer result that includes the HTTP status, the Location header, and the response body.

v0.2.6

Release date: 2026-03-26

Added

• Webhook support (webhooks per [server.NAME]). Each server can now declare one or more webhooks that are called on every request before cache reads, ensuring access control is enforced even for cached responses.
  • type = "blocking" — phantom-frame POSTs the request metadata to the webhook URL and awaits the response. A 2xx reply allows the request to proceed; any non-2xx reply causes the same status code to be returned to the client immediately (the request is never forwarded to the backend or served from cache). A timeout or network error returns 503 Service Unavailable.
  • type = "notify" — the POST is dispatched as a fire-and-forget background task; the request always proceeds immediately regardless of the webhook outcome.
  • url — the endpoint to POST to.
  • timeout_ms — optional per-webhook timeout in milliseconds (default: 5000). Only meaningful for blocking webhooks.
  • Multiple webhooks per server are supported via the [[server.NAME.webhooks]] TOML array syntax. Blocking webhooks run sequentially; the first denial short-circuits the chain.
  • Webhook POST body: { "method", "path", "query", "headers" }. The request body is never consumed so latency overhead is minimal.
• serde_json added as a dependency (used for webhook payload serialisation).

v0.2.5

Release date: 2026-03-26

Added

• .env file loading via dotenv config key. A new top-level dotenv field controls whether a .env file is loaded before environment variable resolution:
  • Absent or false — disabled (default).
  • true — load .env from the current working directory (silently ignored if absent).
  • "./path/to/.env" — load from the given path (error if the file does not exist).
• $env:VAR interpolation in config values. Any string value in the TOML config that matches "$env:VAR_NAME" is replaced at startup with the value of the corresponding environment variable. If the variable is not set, the key is silently dropped (optional fields become None, fields with defaults fall back to their defaults). Works for all string fields — control_auth, proxy_url, cert_path, key_path, etc. Pairs naturally with dotenv to keep secrets out of the config file.
• && / || command chaining in execute. Intermediate segments are run to completion in order; the final segment becomes the long-running server process. && runs the next segment only on success (exit code 0); || runs it only on failure. Example: execute = "pnpm install && pnpm run build && pnpm run start".
• cd support in execute chains. A segment that is a cd <path> command (including cd /d on Windows) changes the virtual working directory for all subsequent segments in the chain without spawning a subprocess.
• Inline KEY=VALUE env-prefix support in execute. Linux-style KEY=VALUE cmd prefixes are parsed and injected as environment variables for that command segment on all platforms. Example: execute = "PORT=5173 NODE_ENV=production pnpm run start".
• dotenvy added as a dependency for .env file loading.

v0.2.4

Release date: 2026-03-26

Added

• execute and execute_dir fields on [server.NAME]. When set, phantom-frame spawns the specified command before the proxy begins serving traffic and polls proxy_url's TCP port every 500 ms until it accepts connections (360 s hard timeout). All processes are spawned concurrently so multiple servers start booting in parallel.
  • execute = "pnpm run dev" — shell command to run.
  • execute_dir = "./apps/client" — optional working directory (relative to where phantom-frame is invoked).
  • Cross-platform: on Windows commands are dispatched via cmd /C, which resolves .cmd shims (pnpm.cmd, npm.cmd, yarn.cmd, etc.) transparently. On Unix, sh -c is used.

Changed

• Control server endpoints renamed to match the CacheHandle API. The previous /refresh-cache endpoint has been replaced. All new routes use underscore-separated names that mirror the corresponding CacheHandle methods:
  • POST /invalidate_all — invalidate every cached entry across all servers (replaces /refresh-cache).
  • POST /invalidate — invalidate entries matching a wildcard pattern. Body: { "pattern": "..." }.
  • POST /add_snapshot — fetch a path from upstream, cache it, and add it to the snapshot list (PreGenerate mode only). Body: { "path": "..." }.
  • POST /refresh_snapshot — re-fetch a single cached snapshot from upstream (PreGenerate mode only). Body: { "path": "..." }.
  • POST /remove_snapshot — remove a path from the cache and snapshot list (PreGenerate mode only). Body: { "path": "..." }.
  • POST /refresh_all_snapshots — re-fetch every tracked snapshot from upstream (PreGenerate mode only).
• Snapshot endpoints called against a Dynamic-mode proxy return 400 Bad Request with a descriptive error message.

Breaking Changes

• POST /refresh-cache has been removed. Replace with POST /invalidate_all.

v0.2.3

Release date: 2026-03-26

Changed

• Default feature changed from native-tls to rustls. The default build now uses axum-server/tls-rustls + reqwest/rustls-tls — pure Rust, no system dependencies.
• native-tls feature now uses axum-server/tls-openssl for server-side TLS. Requires OpenSSL as a system library (libssl-dev on Ubuntu, openssl-devel on Fedora, vcpkg/OPENSSL_DIR on Windows).

v0.2.2

Release date: 2026-03-26

Breaking Changes

• Multi-server TOML config: the single [server] block is replaced by named [server.NAME] blocks. At least one named block is required. Old configs must be migrated.
• proxy_port removed. Replaced by top-level http_port (default: 3000).
• control_port and control_auth moved from [server] to the TOML root (no section header).

Added

• Multi-server support: multiple [server.NAME] blocks can be declared in a single config file. Each block is mounted as an independent Axum router entry.
• bind_to field on each server block:
  • "*" (default) — catch-all fallback, registered last.
  • Any path prefix (e.g. "/api") — nested via Router::nest, registered longest-first so more-specific paths shadow shorter ones.
• http_port (top-level, default 3000) — HTTP listen port.
• https_port (top-level, optional) — HTTPS listen port. When set, cert_path and key_path are required.
• cert_path / key_path — PEM certificate and private key paths for HTTPS.
  • rustls feature (default): TLS via axum-server/tls-rustls — pure Rust, no system dependencies.
  • native-tls feature: TLS via axum-server/tls-openssl — requires OpenSSL installed as a system library.
• Default feature changed from native-tls to rustls. Users who relied on the previous default must now explicitly opt in with --features native-tls --no-default-features.
• Startup validation: missing cert/key when https_port is set, or an empty server map, produce a clear error before the server starts.
• control::create_control_router now accepts Vec<CacheHandle>. A single /refresh-cache call invalidates all registered server caches.

Changed

• WebSocket / upgrade gating: enable_websocket = true is now ignored in pure SSG mode (proxy_mode = "pre_generate" with pre_generate_fallthrough = false). Upgrade requests on such servers always return 501 Not Implemented because there is no live backend to tunnel to. Upgrade support remains fully functional in Dynamic mode and PreGenerate mode with fallthrough = true.

v0.2.1

Release date: 2026-03-26

Breaking Changes

• RefreshTrigger renamed to CacheHandle. Update all usages of phantom_frame::cache::RefreshTrigger to phantom_frame::cache::CacheHandle.
• Methods on CacheHandle renamed:
  • trigger() → invalidate_all()
  • trigger_by_key_match(pattern) → invalidate(pattern)
• create_proxy_with_trigger() renamed to create_proxy_with_handle().

Added

• PreGenerate (SSG) mode via ProxyMode::PreGenerate { paths, fallthrough }:
  • Specified paths are pre-fetched from the upstream server at startup and served exclusively from the cache.
  • fallthrough: false (default) — cache misses return 404 immediately without contacting the backend.
  • fallthrough: true — cache misses fall through to the upstream backend.
• CacheHandle gains four async snapshot-management methods (only available in PreGenerate mode):
  • add_snapshot(path) — fetch and cache a new path, append it to the snapshot list.
  • refresh_snapshot(path) — re-fetch a single path from the backend and overwrite its cache entry.
  • remove_snapshot(path) — evict a path from the cache and remove it from the snapshot list.
  • refresh_all_snapshots() — re-fetch every tracked snapshot path.
• ProxyMode enum exported from the crate root.
• TOML config fields for PreGenerate mode:
  • proxy_mode = "pre_generate" (or "dynamic", the default)
  • pre_generate_paths = ["/book/1", "/about"]
  • pre_generate_fallthrough = false
• CreateProxyConfig::with_proxy_mode(mode) builder method.

v0.1.19

Release date: 2026-03-23

Fixed

• Fixed 502 Bad Gateway errors when phantom-frame is served behind HTTPS / HTTP/2. HTTP/2 requests carry an absolute-form URI (e.g. https://example.com/path) rather than origin-form (/path). The upstream target_url was being constructed by appending the full absolute URI to proxy_url, producing a malformed URL like http://localhost:5173https://example.com/path. The proxy now correctly extracts only the path and query from the incoming request URI before forming the upstream URL. This fix applies to both regular proxied requests and WebSocket upgrade requests.

v0.1.18

Release date: 2026-03-23

Added

• native-tls and rustls Cargo features for selecting the TLS backend used by the upstream HTTP client.
• native-tls is the default, using the platform's native TLS stack (SChannel on Windows, Secure Transport on macOS, OpenSSL on Linux).
• rustls feature (--no-default-features --features rustls) compiles in rustls with bundled webpki root certificates instead.
• Compile-time mutual-exclusivity guard: enabling both features simultaneously produces a clear compile_error!.

v0.1.17

Release date: 2026-03-10

Fixed

• Re-exported CacheStorageMode from phantom_frame::cache, so code importing phantom_frame::cache::CacheStorageMode now compiles.
• Updated the library usage example to show filesystem cache storage configuration directly.

v0.1.16

Release date: 2026-03-10

This release includes the new disk-backed cache body implementation and supersedes v0.1.15, which missed src/compression.rs in the tagged commit.

Added

• Filesystem-backed cache body storage through CacheStorageMode::Filesystem.
• New src/compression.rs module for cache compression, decompression, upstream body normalization, and Accept-Encoding negotiation.
• Startup cleanup for orphaned cache files left in phantom-frame managed cache directories.
• Tests covering compression behavior, disk-backed cache round-trips, wildcard cleanup, 404 eviction cleanup, and startup cleanup.

Changed

• Cache metadata remains in memory while cached body bytes can now be written to the filesystem.
• Cache invalidation now removes backing files during full clear, wildcard clear, and 404 FIFO eviction.
• Proxy cache hits now serve compressed or identity-decoded bodies based on client Accept-Encoding support.
• Upstream response handling now disables automatic reqwest decompression so cache normalization is deterministic.
• Configuration now supports:
  • compress_strategy
  • cache_storage_mode
  • cache_directory
• The example template server dependency was bumped to phantom-frame = "0.1.16".

Documentation

• Updated README.md with cache compression and cache body storage documentation.
• Updated examples/configs/basic.toml with the new cache storage options.
• Updated examples/library_usage.rs to show compression strategy usage.

Release Notes

• v0.1.16 is the valid corrective release tag for this work.
• v0.1.15 was created before src/compression.rs was tracked and should not be treated as the correct release for these changes.