Skip to main content

AI Cost Firewall v0.5.0

AI Cost Firewall v0.5.0 is a production-hardening release focused on predictable dependency failure handling, runtime readiness, graceful shutdown, and repeatable release validation.

Highlights​

  • unified failure classification for Redis, Qdrant, upstream, guard, and Audit-related runtime failures
  • configurable fail-open or fail-closed behavior for exact- and semantic-cache dependency outages
  • runtime readiness tracking exposed through /readyz
  • graceful shutdown with in-flight request handling
  • configuration reload validation with rollback when a SIGHUP reload contains invalid configuration
  • explicit timeout controls for Redis, upstream chat requests, and embedding requests
  • improved Audit delivery loss diagnostics for queue-full and exhausted-retry conditions
  • expanded destructive and failure-path validation for dependency outages, timeouts, guard failures, Audit failures, and evidence lifecycle invariants
  • container health checks for AI Cost Firewall and supported VCAL service integrations
  • repeatable release validation that produces the OCI image and CycloneDX SBOM

Dependency failure handling​

Version 0.5.0 makes cache dependency behavior explicit and configurable rather than treating Redis and Qdrant outages as a single generic failure mode.

Relevant configuration includes:

redis_timeout_seconds 2;
guard_fail_open false;
semantic_cache_fail_open true;
request_timeout_seconds 120;
upstream_timeout_seconds 120;
embedding_timeout_seconds 30;

When fail-open behavior is enabled for an optional cache path, AI Cost Firewall can bypass the unavailable dependency and continue processing the request. When fail-closed behavior is configured, the request fails instead of silently bypassing the dependency.

This allows operators to choose between availability and strict dependency enforcement according to the deployment policy.

Readiness and graceful shutdown​

The release distinguishes process liveness from runtime readiness:

/healthz
/readyz

/healthz indicates that the AI Cost Firewall process is running. /readyz reflects whether the instance is ready to accept traffic according to its runtime state.

Graceful shutdown handling allows the service to stop accepting new work while active requests are given an opportunity to complete before process termination.

Configuration reload safety​

Configuration reloads triggered with SIGHUP are validated before the new configuration becomes active.

If the reloaded configuration is invalid, AI Cost Firewall keeps the previously valid runtime configuration rather than replacing it with an unusable one. The reload failure is logged for operators.

Evidence and Audit diagnostics​

The structured evidence lifecycle introduced in earlier releases remains in place, including stable trace_id correlation and the terminal-event invariant:

request.completed

or:

request.failed

Version 0.5.0 strengthens failure-path validation around this lifecycle and improves diagnostics when asynchronous VCAL Audit delivery cannot retain evidence, including bounded-queue exhaustion and retry exhaustion.

Audit delivery remains memory-backed and does not provide disk-backed replay.

Validation​

The release was validated against scenarios including:

  • Redis outage with configured fail-open and fail-closed behavior
  • Qdrant outage with configured fail-open and fail-closed behavior
  • upstream request timeout
  • delayed or failed embedding requests
  • Security Guard and Privacy Guard failure paths
  • VCAL Audit HTTP 429 and 5xx responses
  • Audit queue-full conditions
  • lifecycle failures and terminal-event invariants
  • cross-user PII and cache-isolation scenarios
  • health and readiness checks across the integrated deployment

The container runs as a non-root user and exposes the AI Cost Firewall service on port 8080.

Compatibility notes​

  • The supported client and upstream API style remains OpenAI-compatible.
  • Streaming chat completions remain unsupported and return HTTP 422.
  • VCAL Privacy Guard, VCAL Security Guard, and VCAL Audit remain optional integrations; AI Cost Firewall can be deployed without them.
  • Fail-open and fail-closed behavior should be selected deliberately for each deployment according to availability and enforcement requirements.
  • Audit delivery remains asynchronous and memory-backed; evidence can still be lost if the queue is full or retry attempts are exhausted.