Sky Cache

Sky Cache is a bounded, thread-safe, single-process TTL/LRU cache and HTTP service for SKYCOIN4444 infrastructure workloads.

Verified capabilities

• bounded LRU capacity with deterministic eviction
• optional default and per-entry TTL using a monotonic clock
• get, set, delete, clear and expired-entry purge operations
• set-if-absent semantics
• optimistic compare-and-set using monotonically increasing entry versions
• hit/miss, eviction, expiration, mutation and CAS-conflict metrics
• FastAPI service with health, readiness and metrics endpoints
• JSON value limit of 64 KiB
• optional constant-time bearer authentication
• configurable maximum entry count and default TTL
• Python 3.12 non-root container with healthcheck
• CI gates for compile, Ruff, pytest, dependency audit and container user verification

API

• GET /healthz
• GET /readyz
• GET /metrics
• GET /api/v1/cache/{key}
• PUT /api/v1/cache/{key}
• DELETE /api/v1/cache/{key}
• POST /internal/purge-expired

PUT supports either only_if_absent=true or expected_version=<version> for optimistic writes. The two controls cannot be combined.

Run locally

python -m pip install -r requirements-dev.txt
pytest -q
uvicorn main:app --host 127.0.0.1 --port 8080

Container:

docker build -t sky-cache .
docker run --rm -p 8080:8080 -e CACHE_MAX_ENTRIES=10000 sky-cache

Optional authentication:

export CACHE_API_TOKEN='replace-with-at-least-16-characters'

Architecture boundary

Despite the historical repository name Python-Distributed-Cache, this product is deliberately single-process. It does not implement peer discovery, replication, consensus, cross-node invalidation, persistent storage or Redis protocol compatibility.

For distributed deployments, place a mature shared cache such as Redis behind an adapter rather than pretending the in-process implementation is distributed. The standalone Sky Cache product remains useful for local service caches, ephemeral inference/result caching, request-local acceleration and test environments.

Security and reliability boundaries

• cache values reside in process memory and are not encrypted at rest because they are not persisted
• bearer authentication is optional and should be enabled when the HTTP service is exposed beyond a trusted boundary
• TLS termination is expected from a trusted reverse proxy or service mesh
• cache contents disappear on process restart
• the service is not a session database or durable financial store
• no multi-node HA or consistency guarantee is claimed

See SECURITY.md and PRODUCT.md for deployment and commercial boundaries.

License

See the checked-in repository license and third-party dependency licenses.