ferronweb/ferron 3.0.0-beta.6

on GitHub

Added

Security

• Admin API bearer token authentication — the admin block now supports an auth_token directive for bearer token authentication on all admin API endpoints except /health. Clients must send Authorization: Bearer <token> header. The /health endpoint is exempt to allow load balancer and orchestrator probes.
• Prometheus endpoint bearer token authentication — the observability.prometheus block now supports an endpoint_auth_token directive for bearer token authentication on the /metrics scrape endpoint. Scrapers must send Authorization: Bearer <token> header.

Networking

• Multipath TCP (MPTCP) support — the tcp block now supports a multipath directive that enables Multipath TCP on the HTTP listener. MPTCP allows a single TCP connection to use multiple network interfaces simultaneously, improving throughput and connection resilience. When enabled, Ferron attempts to create an MPTCP socket; if the kernel does not support MPTCP or it is disabled, a warning is logged and the listener falls back to standard TCP. (GitHub issue)

Observability & tracing

• Admin API request metrics — the admin API now emits per-request metrics (ferron.admin.request.duration, ferron.admin.request.count) for all endpoints except /health, with http.request.method, url.path, and http.response.status_code attributes. A dedicated ferron.admin.reload.count counter tracks reload attempts.
• Admin API structured logs — the admin API now emits structured log events through the observability pipeline for config reloads (Info/Error) and config queries (Info). Health checks and status queries are not logged to avoid noise.
• Prometheus scrape self-metrics — the Prometheus endpoint now emits ferron_prometheus_scrape_duration_seconds (Histogram), ferron_prometheus_scrape_total (Counter), and ferron_prometheus_scrape_errors_total (Counter) for monitoring scrape performance.
• Process identity in OTel resources — the OTLP resource now automatically includes process.pid and process.start_time attributes, allowing observability backends to distinguish between concurrent and sequential process lifetimes. This prevents cumulative counters from adjacent process lifetimes from being visually interleaved in dashboards.
• Status-code labels on cache store counters — the ferron.cache.stores metric now includes an http.response.status_code attribute, allowing operators to directly query whether error responses are entering the cache layer without correlating timing across separate request and error series.
• Cache key fingerprint in access logs — the cache module now contributes a ferron.cache.key_fingerprint field to HTTP access log lines, containing a truncated representation of the cache key. This simplifies debugging why a specific request resulted in a cache miss.
• Singleflight coalescing traceability in access logs — the cache module now contributes ferron.cache.coalesced (bool) and ferron.cache.coalesce_wait_duration_ms (float) fields to HTTP access log lines, providing direct visibility into how long client requests are queuing inside the proxy during concurrent upstream revalidation.
• Cache key components in OTel trace attributes — the ferron.stage.cache span now includes ferron.cache.key.uri, ferron.cache.key.method, and ferron.cache.key.evaluated_cookies attributes, making trace flame graphs instantly diagnostic when evaluating hit-rate degradation caused by high-cardinality metadata variations.
• Singleflight coordination metrics — new ferron.cache.coalesced_requests (Counter) and ferron.cache.singleflight_active_locks (Gauge) metrics expose the efficiency of the request deduplication layer, providing visibility into how effectively singleflight handles concurrent thundering herds.
• Eviction reason structured logs — cache eviction events now emit debug-level structured log entries with eviction.reason (ttl_expired or capacity_reached_lru), eviction.count, and ferron.cache.zone attributes, providing precise eviction timelines alongside the existing cumulative metrics.
• Cross-plane traceability — the new control_plane directive allows embedding arbitrary key-value metadata and static OpenTelemetry span links in the server configuration at global, host, or location levels. Metadata values are automatically included as ferron.control_plane.* attributes on all observability signals (OTLP traces, logs, metrics, access logs) and as [key=value] prefixes in console and file logs. Span links establish causal relationships between control plane events and data plane traces without requiring a parent-child relationship. The most specific level wins (location > host > global), and metadata values support variable interpolation.

HTTP caching

• vary_cookies directive — the cache module now supports a vary_cookies directive that accepts an explicit list of cookie names for cache key differentiation. When set, only the listed cookies are included in the cache key, preventing high-entropy tracking or session cookies from fragmenting the cache and collapsing hit rates.