product: ship Sky Cache bounded TTL/CAS service

.github/workflows/ci.yml

@@ -1,12 +1,33 @@
-name: CI
-on: [push, pull_request]
+name: cache-ci
+
+on:
+ push:
+ pull_request:
+
+permissions:
+ contents: read
+
 jobs:
-test:
+verify:
  runs-on: ubuntu-latest
+ env:
+ PYTHONPATH: .
  steps:
- - uses: actions/checkout@v3
- - uses: actions/setup-python@v4
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
  with:
- python-version: '3.11'
- - run: pip install -r requirements.txt
- - run: pytest tests/
+ python-version: '3.12'
+ - name: Install verification dependencies
+ run: python -m pip install --upgrade pip && pip install -r requirements-dev.txt
+ - name: Compile
+ run: python -m compileall -q cache.py main.py tests
+ - name: Lint
+ run: ruff check cache.py main.py tests
+ - name: Unit tests
+ run: pytest -q
+ - name: Audit runtime dependencies
+ run: pip-audit -r requirements.txt
+ - name: Build container
+ run: docker build -t sky-cache:ci .
+ - name: Verify non-root image
+ run: test "$(docker run --rm --entrypoint=id sky-cache:ci -u)" != "0"

Dockerfile

@@ -1,6 +1,15 @@
-FROM python:3.11-slim
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+ PYTHONUNBUFFERED=1 \
+ PIP_NO_CACHE_DIR=1
+
 WORKDIR /app
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
-COPY . .
-CMD ["python", "-m", "src.server"]
+COPY requirements.txt ./
+RUN python -m pip install --upgrade pip && pip install -r requirements.txt \
+ && useradd --system --uid 10001 --create-home skycache
+COPY cache.py main.py ./
+USER 10001:10001
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/healthz', timeout=2).read()"
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080", "--no-access-log"]

PRODUCT.md

@@ -0,0 +1,24 @@
+# Sky Cache Product Definition
+
+**Product number:** 13 in the SKYCOIN4444 standalone-product master plan.
+
+## Problem
+
+Applications often need a bounded local cache with predictable TTL, eviction and optimistic-update semantics without operating an external cache service for every workload.
+
+## Product
+
+Sky Cache packages a reusable Python cache domain and an optional HTTP service. It is suitable for ephemeral API response caching, local AI inference/result caching, short-lived metadata, development/test acceleration and other non-durable workloads.
+
+## Commercial packaging
+
+- embeddable `SkyCache` Python class
+- standalone FastAPI service
+- non-root container image
+- health/readiness/metrics endpoints
+- optional bearer boundary
+- deterministic test suite and dependency audit CI
+
+## Explicit non-claims
+
+Sky Cache is not Redis, Memcached, a persistent database, a distributed cache, a consensus system, a multi-region service or a durable session/financial store. Those capabilities require a separate shared backend or product tier and independent evidence.

README.md

@@ -1,64 +1,72 @@
-# Python Distributed Cache
+# Sky Cache
 
-Reusable caching component for the SKYCOIN4444 infrastructure ecosystem.
+Sky Cache is a bounded, thread-safe, single-process TTL/LRU cache and HTTP service for SKYCOIN4444 infrastructure workloads.
 
-## Current implementation
+## Verified capabilities
 
-- Thread-safe in-process cache domain
-- TTL expiration using a monotonic clock
-- Explicit get/set/delete/clear operations
-- Input validation
-- Unit tests for expiration, invalidation, and invalid inputs
-- FastAPI/uvicorn dependencies retained for the service boundary
+- 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
 
-## Ecosystem role
+## API
 
-**Infrastructure → Caching Boundary**
+- `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`
 
-The repository currently provides a reusable cache-domain implementation. Despite the repository name, the verified implementation is **not yet a multi-node distributed cache**. Redis/Memcached or another shared backend, consistency semantics, invalidation propagation, and failure handling are still required before that claim is accurate.
+`PUT` supports either `only_if_absent=true` or `expected_version=<version>` for optimistic writes. The two controls cannot be combined.
 
-## Commercial starter-kit potential
+## Run locally
 
-This component can become an enterprise caching starter kit for:
+```bash
+python -m pip install -r requirements-dev.txt
+pytest -q
+uvicorn main:app --host 127.0.0.1 --port 8080
+```
 
-- API response caching
-- session/cache layers
-- AI inference/result caching
-- market-data caching
-- rate-limit state
-- frequently accessed platform data
+Container:
 
-Its commercial value comes from reusable implementation, tested adapters, deployment configuration, observability, and customer adoption—not from the repository name or “enterprise-grade” wording.
+```bash
+docker build -t sky-cache .
+docker run --rm -p 8080:8080 -e CACHE_MAX_ENTRIES=10000 sky-cache
+```
 
-## Truthful status
+Optional authentication:
 
-- Cache domain: **implemented**
-- TTL/invalidation tests: **implemented**
-- Shared distributed backend: **not integrated**
-- Multi-node consistency: **not verified**
-- Production deployment: **not verified**
-- Paying customers: **not verified**
-- ARR/revenue: **not claimed**
+```bash
+export CACHE_API_TOKEN='replace-with-at-least-16-characters'
+```
 
-The prior README described the project as “enterprise-grade” while the audit evidence showed a small implementation footprint. This README reports the concrete capability instead. fileciteturn296file0
+## Architecture boundary
 
-## Open-source integration policy
+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 genuine distributed-cache requirements, prefer mature public foundations such as Redis-compatible or other established cache systems rather than inventing distributed consistency and replication protocols. Integrate through a stable adapter and preserve third-party licenses/attribution.
+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.
 
-## Production roadmap
+## Security and reliability boundaries
 
-1. Add Redis-backed adapter.
-2. Add cache namespace/versioning.
-3. Define consistency and invalidation semantics.
-4. Add metrics and tracing.
-5. Add health/readiness checks.
-6. Add integration tests against the target backend.
-7. Add load/eviction benchmarks.
-8. Add authentication/network controls where required.
-9. Package Docker/CI deployment artifacts.
-10. Consolidate the strongest implementation into SKYCOIN4444 Infrastructure.
+- 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 applicable third-party dependency licenses.
+See the checked-in repository license and third-party dependency licenses.

SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+## Supported product boundary
+
+Sky Cache stores values only in the memory of the current process. It should be treated as an ephemeral cache, not as a secret store or durable database.
+
+## Deployment requirements
+
+- enable `CACHE_API_TOKEN` when exposing the HTTP boundary outside a trusted network
+- terminate TLS at a trusted reverse proxy or service mesh
+- do not cache plaintext credentials, private keys, regulated data, or other material that requires durable encryption controls
+- apply network-level access control and resource limits in the deployment environment
+- restart the service to clear all cached values when a full purge is required
+
+## Implemented controls
+
+- bounded key length and value size
+- bounded maximum entry count
+- bounded TTL
+- constant-time bearer comparison when authentication is configured
+- optimistic version checks for write races
+- non-root container execution
+- dependency auditing in CI
+
+## Not implemented
+
+Sky Cache does not provide tenant isolation, encryption at rest, distributed authentication, TLS termination, replication, consensus, cross-node invalidation, or durable audit logging.
+
+Report suspected vulnerabilities through the repository's GitHub security/reporting channel without including live secrets in public issues.