Fluxheim 1.6.33

[eldryoth]

Fluxheim 1.6.33 Release Notes

Fluxheim 1.6.33 is the native proxy-cache parity release in the Pingora
removal line.

This checkpoint adds Fluxheim-owned native memory-cache, filesystem and
storage-bin disk cache, local-key and OpenBao Transit encrypted disk cache, and
memory+disk tiering for ordinary HTTP/1 proxy responses.

Highlights

• Added a shared native memory-cache helper inside fluxheim-server for
  buffered HTTP/1 responses. Static-web cache and proxy cache now use the same
  entry metadata, TTL, age, pruning, response-header map, and cache-status
  helper code.
• Native HTTP/1 proxy routes can now attach a Fluxheim-owned memory cache for
  non-load-balanced upstreams when the cache policy is limited to the supported
  native subset.
• Native proxy cache lookup/fill now reuses the Pingora-independent
  fluxheim-cache request and response policy helpers for cache key
  construction, request bypasses, client revalidation, response
  no-store/private, Set-Cookie, status TTLs, content-type admission, and
  object-size limits.
• Native proxy cache emits configured cache status and reason headers. The
  live native listener test proves a cacheable proxy response returns MISS
  on first fill and HIT on the second request without contacting the origin.
• HEAD requests remain bypassed in the native proxy cache path so a HEAD probe
  cannot poison a cached GET body.
• Native root, vhost, and route readiness checks now accept only the supported
  memory-tier proxy cache subset and keep unsupported cache shapes blocked
  instead of silently dropping policy.
• Native HTTP/1 TLS startup now recognizes managed ACME certificate sources on
  server.default_vhost, so rustls deployments using server.tls_listen can
  start with a pending default-vhost ACME certificate source and serve HTTP-01
  issuance traffic instead of failing the TLS listener plan.
• Native proxy memory cache now bypasses shared-cache lookup/fill for requests
  carrying Authorization, keeps configured BYPASS cache-status headers on
  upstream error responses, and strips stored upstream Age so cache hits emit
  one recomputed Age header.
• Native proxy memory cache now isolates origin Vary response variants and
  configured cache.vary_request_headers variants in the native memory-cache
  key space.
• Native proxy memory cache now serves expired memory-cache entries under
  configured stale_if_error_secs when the single-upstream native proxy sees a
  matching upstream error or 5xx status.
• Native proxy memory cache now enforces cache.origin_protection fill budgets
  for the supported single-upstream memory-cache path.
• Native proxy memory cache now uses checked Instant arithmetic for freshness
  and stale-if-error expiry, bypassing cache admission instead of panicking if a
  constrained platform cannot represent the configured window.
• Native proxy memory cache now serves bounded single Range requests from
  fresh cached full objects, emits cached 416 responses for unsatisfiable
  ranges, and bypasses cache fill on range misses so upstream 206 responses
  are never stored under full-object keys.
• Native proxy memory cache now supports native load-balanced upstream pools;
  cache hits return before backend selection, and cache misses fill from the
  selected backend.
• Native proxy memory cache now supports cache.min_uses,
  cache.pass_uncacheable_after, and opt-in [cache.predictor] cache-pass
  decisions with bounded Fluxheim-owned counters. Cacheable responses clear
  cache-pass state before min-use admission, matching the existing
  compatibility behavior.
• Native proxy memory cache now supports stale_while_revalidate_secs for
  expired memory objects. The native path serves a STALE-UPDATING response,
  keeps origin-fill protection in front of the refresh task, and updates the
  cached object through the same response admission path.
• Native proxy memory cache now supports [cache.lock] request collapsing for
  concurrent same-key memory-cache misses. The first request fills from origin;
  matching readers wait up to wait_timeout_secs and then serve the completed
  object as a normal HIT when the fill succeeds.
• Native proxy memory cache now supports memory-tier [cache.range.slice]
  composition. The native path fetches fixed-size origin slices with bounded
  Range subrequests, validates 206, Content-Range, Content-Length,
  identity encoding, and matching ETag/Last-Modified identity, then composes
  single-range or multipart responses from cached slices.
• Native proxy memory cache now supports peer-fill over HTTPS and over
  constrained HTTP peers. HTTPS peers use the native upstream TLS connector and
  derive SNI from the peer URL host; plaintext HTTP peers are accepted only for
  loopback peers or when cache.peer_fill.allow_insecure_http = true. Native
  peer-fill preserves the X-Fluxheim-Peer-Fill loop guard, sends
  Cache-Control: only-if-cached, honors peer-fill concurrency limits, stores
  successful peer 200 responses locally, and returns PEER-HIT before later
  requests become normal memory-cache HITs.
• Native proxy cache now supports unencrypted filesystem disk cache and
  memory+disk tiering. Disk objects use hashed paths under the configured cache
  root, reuse the shared Fluxheim disk object envelope, persist freshness and
  stale windows as absolute timestamps, rebuild a bounded native index at
  startup, and promote fresh disk hits back into memory when the memory tier is
  enabled.
• Native proxy cache now supports local-key encrypted filesystem disk cache.
  The native path reuses the existing FLUXHEIM-CACHE-ENC-v1 AES-256-GCM
  envelope, loads the same safe key_file/key_credential sources, rejects
  plaintext objects while encryption is enabled, and has live listener coverage
  proving encrypted disk MISS then HIT reuse without storing the origin
  response body in plaintext on disk.
• Native proxy cache now supports the storage-bin disk backend. The native
  path prepares the same manifest/bin layout, persists a bounded native index,
  rebuilds free-space state at startup, evicts oldest objects when the storage
  budget is full, and has live listener coverage proving storage-bin MISS
  then HIT reuse across a native proxy restart.
• Native proxy cache now supports local-key encrypted storage-bin disk cache.
  The same encrypted disk-object envelope is written into bin slots, and live
  listener coverage proves restart HIT reuse without storing the origin
  response body in plaintext inside bin files.
• Native proxy cache now supports OpenBao Transit encrypted disk cache in the
  native cache path. The native adapter reuses the existing
  FLUXHEIM-CACHE-ENC-v1 envelope, sends Transit encrypt/decrypt requests
  with authenticated cache-key data, disables OpenBao redirects, caps Transit
  response bodies, trims zeroized token-file/credential secrets before header
  use, and has live storage-bin listener coverage proving MISS, restart
  validation decrypt, and HIT decrypt behavior.
• Native peer-fill admission now subtracts upstream Age from peer response
  freshness, so aged peer objects cannot extend origin freshness when copied
  into local memory cache.
• Native cache-only requests with Cache-Control: only-if-cached now return a
  bounded 504 miss instead of contacting origin. A client-supplied
  X-Fluxheim-Peer-Fill marker is stripped before normal proxy handling and
  no longer suppresses peer-fill.
• Hardened native cache internals by using checked static-web cache expiry
  arithmetic, suppressing duplicate stale-while-revalidate refresh tasks per
  cache key before task allocation, and avoiding full predictor-counter table
  scans on the hot miss path.
• Hardened native cache admin purge parity by adding a Fluxheim-owned native
  memory-cache purge index and wiring exact, bulk, prefix, tag, wildcard,
  route-scope, and stale purge operations through live native memory state as
  well as disk state. The proxy-cache smoke now proves those purges cannot
  leave a native memory HIT or STALE response behind while the origin is
  stopped.
• Closed native observability parity gaps found during the final release gate:
  native HTTP/1 proxy requests now regenerate forwarded traceparent span IDs,
  record proxy request counters, expose native cache memory/disk runtime gauges,
  and publish native cache lookup duration histograms through the existing
  Prometheus metrics surface.
• Fixed native disk-cache purge parity so exact, bulk, prefix, tag, wildcard,
  route-scope, stale, and slice path-exact purges operate on the live native
  filesystem/storage-bin disk cache instead of a reconstructed throwaway cache.
  Native disk cache now keeps its own purge index and reports non-zero disk
  purge-index metrics when indexed disk objects are present.
• Moved native disk-cache lookup and store work onto Tokio's blocking pool.
  This covers filesystem I/O, storage-bin I/O, storage-bin index persistence,
  and OpenBao Transit encrypt/decrypt HTTP calls so cache operations do not
  pin async worker threads while external storage or OpenBao is slow.
• Reduced storage-bin write amplification by batching index persistence for
  multi-object eviction during one cache store, instead of rewriting the full
  storage-bin index after every single evicted object.
• Hardened native cache encryption and rebuild behavior by bounding
  filesystem cache-object reads before startup rebuild parsing, zeroizing
  transient decrypted OpenBao/native serialized-object buffers, and logging
  local AES-GCM key-rotation warnings as a process approaches the random-nonce
  invocation bound.
• Native filesystem disk-cache startup scans now list root and shard
  directories through the native safe disk-cache path wrapper, keeping the
  symlink/canonical path boundary explicit at the directory traversal point.
• Native disk-cache indexed purge removals now update object state and purge
  index membership under the same cache-state lock, closing a split-lock race
  where a concurrent store could become invisible to indexed purge operations.
• Updated arc-swap to 1.9.2 and env_logger to 0.11.11.
• Stale admin purges now log an explicit security warning if the system clock
  regresses before the Unix epoch, instead of silently substituting timestamp
  zero without operator visibility.

Compatibility Notes

• Supported in this checkpoint: memory-tier proxy cache for ordinary GET
  responses from static or native load-balanced upstream pools, with optional
  cache-status headers, Vary/request-header variant isolation,
  stale_if_error_secs serving, cache.origin_protection fill budgets,
  native load-balanced pools, cache.min_uses, pass_uncacheable_after,
  opt-in [cache.predictor] cache-pass decisions,
  stale_while_revalidate_secs background refresh, [cache.lock] same-key
  request collapsing, memory-tier [cache.range.slice] composition,
  unencrypted, local-key encrypted, or OpenBao Transit encrypted filesystem or
  storage-bin disk cache, memory+disk tiering, and HTTPS/loopback-or-opt-in
  HTTP peer-fill.
  If cache.range.enabled = true, bounded single Range requests can be
  served from fresh cached full objects or from compatible fixed-size memory
  slices when slice caching is enabled.
• Native runtime readiness still rejects cache policies that are attached to no
  native cacheable handler or whose route/upstream shape is outside the
  supported native proxy-cache subset; it no longer has a backend/encryption
  parity gate for filesystem, storage-bin, local-key, or OpenBao Transit disk
  cache.
• Security note: native HTTP peer-fill is intentionally available only when
  the peer is loopback or allow_insecure_http = true. Plaintext HTTP has no
  transport integrity and can be cache-poisoned by a network-path attacker; use
  HTTPS peers, loopback peers, encrypted overlays, mTLS sidecars, or trusted
  private networks.
• The compatibility runtime remains available for unsupported cache policy
  shapes while operators migrate route layouts to the native-supported subset.

Verification

• cargo test -p fluxheim-server native_route_proxy_caches_proxy_response_in_memory --locked
• cargo test -p fluxheim-server native_route_proxy_min_uses_delays_memory_cache_admission --locked
• cargo test -p fluxheim-server native_route_proxy_predictor_passes_repeated_uncacheable_memory_response --locked
• cargo test -p fluxheim-server native_route_proxy_serves_stale_while_revalidating_memory_cache --locked
• cargo test -p fluxheim-server native_route_proxy_cache_lock_collapses_concurrent_memory_fills --locked
• cargo test -p fluxheim-server native_route_proxy_slice_cache_fills_and_composes_memory_range --locked
• cargo test -p fluxheim-server native_route_proxy_slice_cache_composes_multipart_memory_response --locked
• cargo test -p fluxheim-server native_route_proxy_accepts_route_memory_proxy_cache_with_https_peer_fill --locked
• cargo test -p fluxheim-server native_route_proxy_caches_proxy_response_on_disk --locked
• cargo test -p fluxheim-server native_route_proxy_caches_proxy_response_on_encrypted_disk --locked
• cargo test -p fluxheim-server native_route_proxy_caches_proxy_response_on_storage_bin_disk --locked
• cargo test -p fluxheim-server native_route_proxy_caches_proxy_response_on_encrypted_storage_bin_disk --locked
• cargo test -p fluxheim-server --features openbao-cache-encryption native_route_proxy_caches_proxy_response_on_openbao_storage_bin_disk --locked
• cargo test -p fluxheim-server native_route_proxy_tiered_cache_refills_memory_from_disk --locked
• cargo test -p fluxheim-server native_route_proxy_peer_fills_and_stores_memory_cache_response --locked
• cargo test -p fluxheim-server native_storage_bin_disk_purge_uses_live_cache_instance --locked
• cargo test -p fluxheim-server static_cache_expiry_rejects_unrepresentable_ttl --locked
• cargo test -p fluxheim-server native_route_proxy_regenerates_forwarded_traceparent_span_id --features otel-tracing --locked
• cargo test -p fluxheim-server --features acme,tls-rustls-backend native_http1_proxy_runtime_accepts_default_vhost_acme_certificate_source --locked
• cargo test -p fluxheim-server native_http1_plan --locked
• cargo check -p fluxheim-server --all-features --locked
• cargo check -p fluxheim --features profile-observability --locked
• sh scripts/smoke_observability_local.sh
• sh scripts/smoke_proxy_cache.sh
• scripts/podman_smoke.sh
• scripts/stable_release_gate.sh check

Checksums And Signatures

• Commit: fbed3f76f86cd7f7ae394d23dff5050c6fa9366f
• Local gate: GitHub CI green before tag; local release metadata checks passed
• CodeQL/code scanning: no open release-blocking alerts before tag
• Source archive checksums:
  • 9c3d471bda0821f48b5fd67a0768bba2f188358d2a8e1ec8fd0693a78585b640 fluxheim-1.6.33.tar.gz
  • 3276b7d39a20fd28d2d7f71813f3af1f471bff7fee27d470731ca94b7b024292 fluxheim-1.6.33.zip
• Binary checksums:
  • x86_64:
    • e3197578aa4b5411156cd4586662596d421db3c8a1aa3a48e246ec80521b325a fluxheim-1.6.33-full-x86_64-linux.tar.gz
    • e72280874a15530d3dbea3e4bd22f6449c5bcd2efbba131240f839b71b28b818 fluxheim-1.6.33-cache-x86_64-linux.tar.gz
    • c67c1fa6c4638cf0fb91f2f57c85a2bdb41e56bd92dcce9435643d203f2e2ac9 fluxheim-1.6.33-proxy-x86_64-linux.tar.gz
    • fde03ea4ba8174584da7f8a3ef8edc6327e12d149fd6fa7e0f413f16cc31608e fluxheim-1.6.33-php-x86_64-linux.tar.gz
    • b23cdc77d1b911f4dd358c5cf8081550e9af5358b01e1b3e0df480cdbe21878b fluxheim-1.6.33-load-balancer-x86_64-linux.tar.gz
    • 05c1f5c878b856b398255f658fd1a99f7937c3f9eea8b57814ad6cbf35a111d1 fluxheim-1.6.33-config-tester-x86_64-linux.tar.gz
  • aarch64:
    • d0ca3c256db1b7ab7c1813ecd08bb402a53685fa8d60ac68cc302db80fc4a1c4 fluxheim-1.6.33-full-aarch64-linux.tar.gz
    • b11f62272409d6e89ef42b0a99559fdecde00267f9d48f556388986d0177e1f1 fluxheim-1.6.33-cache-aarch64-linux.tar.gz
    • 2679d60ed1e36f9d7bd68f23fd2d9026812abb1df2d292bebd80e22f1aa46652 fluxheim-1.6.33-proxy-aarch64-linux.tar.gz
    • 9fcffc1f68010c5507a9df7a1732851a6860a1f1a53b04a7a9887b77317ae185 fluxheim-1.6.33-php-aarch64-linux.tar.gz
    • f06ec8df9f87e7f1dc9e46e9760ae7e5361000fc65558752e9e3b4a808e9277e fluxheim-1.6.33-load-balancer-aarch64-linux.tar.gz
    • a637ecdd0ebffcfd18c49533f5fba9e1b16ced5906498da6155103695f4ee12b fluxheim-1.6.33-config-tester-aarch64-linux.tar.gz
  • macos:
    • 9cbdf5a84315c631e66e7e63d206e99f53030bd8968eb4f349fa0a47388fb503 fluxheim-1.6.33-dev-aarch64-macos.tar.gz
• SBOM checksums:
  • 81d1757b0cfb0610244b100be9adeafc4fc80651111f94310b717705c2cb7d2c fluxheim.spdx.json
  • e515e6cf896c3c0499fe3671d48978495b5cd155574fbe4d01ddf2f182cc0d1a fluxheim.cyclonedx.json
• Reproducible build:
  • 933e06fb8b3707b59a12a0fdd89f71df2110ca068b779c1a88fcd0db146f71c4 x86_64
  • 70067e8966bc09f972553c09a2252a1b305b7c5843272bea7d9405dcbd8546f6 aarch64
  • 36eedf7983a84769e3c6e7b3ebe8899c0327898f757a9586273ac05750474522 macos
• Full Build Container digests:
  • Wolfi: ghcr.io/valkyoth/fluxheim@sha256:f4ba0069137962452360ab0e11f9ac4326b351f9fc15a4a777bc6bb7990c6c4e
  • Alpine: ghcr.io/valkyoth/fluxheim@sha256:47477f22bf850466616706e8de95c81df41774a9b7f6d197ad3d8e8382d0c701
  • SUSE Micro: ghcr.io/valkyoth/fluxheim@sha256:a927099369c7aaf949211a0a37bb4dc7dce00f60319c3c8cbfb6f349aa2da1ac
  • Debian: ghcr.io/valkyoth/fluxheim@sha256:033f0eec6197aedeebeb77df7424472ea3aaabb5094ca1999dbb67f4bd5855e0
• Cache Build Container digests:
  • Wolfi: ghcr.io/valkyoth/fluxheim@sha256:0a85ca39440725c42028caeaba11af10c71617de254a044ec3461c3be941727b
  • Alpine: ghcr.io/valkyoth/fluxheim@sha256:b8332b98ba9e83f86f3c2cecac56e5f82c7338f145bcac5e4add81460a94b2f6
  • SUSE Micro: ghcr.io/valkyoth/fluxheim@sha256:230bdfe4721a7bdff6806fc2afa858de8b8c0748d8a87fc8aa3b431c696792ae
  • Debian: ghcr.io/valkyoth/fluxheim@sha256:4491b5576cc46dc3c1d946634c9a802043b631d62f792758b4394084fdb4cd5f
• Proxy Build Container digests:
  • Wolfi: ghcr.io/valkyoth/fluxheim@sha256:167d354ab055c72a2e24a4c8f4ced6478d390c1a0ad98900b312ebf90e671c4c
  • Alpine: ghcr.io/valkyoth/fluxheim@sha256:474de47af6df5f2dcaf45c27f91682c71c494fc5d8856b3e046ce21e733456c9
  • SUSE Micro: ghcr.io/valkyoth/fluxheim@sha256:22f7bd5a89bb668a61a0a9c0da70f769e4a467bf62fb813abe41d1058cb0f0c5
  • Debian: ghcr.io/valkyoth/fluxheim@sha256:8112e6d6e7d10728b32ebfe3571c14cbe99d6f93614e9b67ee2ea9a2a72f7680
• PHP Build Container digests:
  • Wolfi: ghcr.io/valkyoth/fluxheim@sha256:1365cbf8c9f37e24168b4f7a7d0121fee801a28fdebea5598698857cda3518a1
  • Alpine: ghcr.io/valkyoth/fluxheim@sha256:249fed959289adb1d024790f6e9a519a6cbdf4794f91d2de5bc4178ba5f1e311
  • SUSE Micro: ghcr.io/valkyoth/fluxheim@sha256:4b6ff7e0e6ca1429fdb0475ee1879e77a1604ac56b3c4c754035b7b6a8afd4d3
  • Debian: ghcr.io/valkyoth/fluxheim@sha256:4e816031c3ce40c3801a3dd1ae94afb980113e7f28648ab3fd174d1726f41b52
• Load Balancer Build Container digests:
  • Wolfi: ghcr.io/valkyoth/fluxheim@sha256:0a9c28da592f410e2efc81a8560d161cf094a1a8b286a2050d429670b46b4f16
  • Alpine: ghcr.io/valkyoth/fluxheim@sha256:7e98d79aee2995af65ad2a40c3124abcf214c6999149513f5e178c8ce1b69a5b
  • SUSE Micro: ghcr.io/valkyoth/fluxheim@sha256:815b1f27f42928684e634c2bd769e64a2a8e398ea8c23f7de162b767f2d0f2f2
  • Debian: ghcr.io/valkyoth/fluxheim@sha256:42785ef9f54dacd08004ee64c0c8e8d530d67b5ac700328539030e2903ef155d
• Tag signature:
  • Good "git" signature for 1921261+eldryoth@users.noreply.github.com with ED25519 key SHA256:EoLRQ5k4J5pYz3UMFmkrV798gYFNkToGS2xEPvebqB4

---

This discussion was created from the release Fluxheim 1.6.33.