mirror of
https://github.com/KohakuBlueleaf/KohakuHub.git
synced 2026-07-15 18:25:09 -05:00
aff9fd47ef
Introduces the prerequisite cache layer tracked in #73. No business code yet consumes the helpers — this is plumbing only, gated by KOHAKU_HUB_CACHE_ENABLED (default: false). Subsequent issues will adopt specific cache patterns on top of this foundation. Why now: every hot read endpoint currently makes 1–3 LakeFS REST calls plus several Postgres queries per request, with the only existing cache being a per-process cachetools.TTLCache in fallback/cache.py — useless across the default 4-worker uvicorn deployment. Design highlights (full design in docs/development/cache.md): - Pure cache, no source-of-truth state. Silent-degradation contract: every cache call is wrapped in try/except and falls back to L3 when Valkey is unreachable. CI runs a dedicated cache-disabled job to regression-guard this. - L1 (per-worker cachetools) restricted to immutable / content-addressed data only — multi-worker uvicorn has no portable cross-worker invalidation channel, and constraining L1 to "key contains its own version" sidesteps that entirely. - L2 (Valkey) holds everything. Helpers ship with TTL jitter (±15% default), two-level singleflight (asyncio.Lock + Valkey SET NX EX), negative cache, generation counters, and per-namespace metrics. - Persistence: RDB on, AOF off, persistent volume. Mode-A (lakefs:commit, lakefs:stat, lakefs:list — commit_id-keyed) survives restart safely. Mode-B (mutable) namespaces are flushed on every Valkey restart by a run_id-based bootstrap coordinator that serializes the flush across workers. Includes: - src/kohakuhub/cache.py — the helper module (319 stmts, 83% coverage via the new test module). - src/kohakuhub/api/admin/routers/cache.py — admin endpoints exposing hit/miss/error counters, Valkey memory state, and bootstrap-flush metadata. - test/kohakuhub/test_cache.py — 34 tests against a real Valkey, covering: round-trips, TTL jitter spread, SCAN-based prefix delete over >SCAN_BATCH_SIZE keys, two-level singleflight (100 concurrent calls fold to 1 fetch), bootstrap flush selectivity (Mode-A survives, Mode-B is wiped, exactly), two-worker bootstrap coordination, silent degradation when Valkey is disabled OR unreachable, generation counters, negative cache, the Mode-B prefix list shape contract. - docker-compose.example.yml — adds the valkey service with RDB + LFU + bind-mounted hub-meta/valkey-data, mirroring the persistence pattern of the other stateful services. - scripts/dev/up_infra.sh / down_infra.sh / reset_local_data.sh — Valkey container plumbing for local dev (host port 26379). - .github/workflows/fullstack-tests.yml — adds valkey to the existing matrix services and adds a separate single-Python job (backend-tests-cache-disabled) running with KOHAKU_HUB_CACHE_ENABLED=false as the silent-degradation contract regression guard. - docs/development/cache.md — the design doc referenced by the cache module's docstrings. Refs: #73 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
58 lines
2.1 KiB
Plaintext
58 lines
2.1 KiB
Plaintext
# Copy this file to .env.dev before local development.
|
|
# It is sourced by scripts/dev/*.sh, so shell variable expansion is supported.
|
|
|
|
DEV_POSTGRES_USER=hub_dev
|
|
DEV_POSTGRES_PASSWORD=hub_dev_password
|
|
DEV_POSTGRES_DB=kohakuhub_dev
|
|
|
|
DEV_MINIO_ROOT_USER=minioadmin
|
|
DEV_MINIO_ROOT_PASSWORD=minioadmin
|
|
|
|
DEV_LAKEFS_ENCRYPT_SECRET_KEY=dev-lakefs-encrypt-key-32chars
|
|
|
|
# Public links should resolve through the main Vite dev server.
|
|
KOHAKU_HUB_BASE_URL=http://127.0.0.1:5173
|
|
# Backend self-calls should bypass Vite and hit uvicorn directly.
|
|
KOHAKU_HUB_INTERNAL_BASE_URL=http://127.0.0.1:48888
|
|
KOHAKU_HUB_API_BASE=/api
|
|
|
|
KOHAKU_HUB_DB_BACKEND=postgres
|
|
KOHAKU_HUB_DATABASE_URL=postgresql://${DEV_POSTGRES_USER}:${DEV_POSTGRES_PASSWORD}@127.0.0.1:25432/${DEV_POSTGRES_DB}
|
|
KOHAKU_HUB_DATABASE_KEY=dev-database-key-change-me
|
|
|
|
KOHAKU_HUB_S3_ENDPOINT=http://127.0.0.1:29001
|
|
KOHAKU_HUB_S3_PUBLIC_ENDPOINT=http://127.0.0.1:29001
|
|
KOHAKU_HUB_S3_ACCESS_KEY=${DEV_MINIO_ROOT_USER}
|
|
KOHAKU_HUB_S3_SECRET_KEY=${DEV_MINIO_ROOT_PASSWORD}
|
|
KOHAKU_HUB_S3_BUCKET=hub-storage
|
|
KOHAKU_HUB_S3_REGION=us-east-1
|
|
|
|
KOHAKU_HUB_LAKEFS_ENDPOINT=http://127.0.0.1:28000
|
|
KOHAKU_HUB_LAKEFS_REPO_NAMESPACE=hf
|
|
|
|
# L2 cache (Valkey). Default-on in dev so contributors hit cache bugs early.
|
|
# See docs/development/cache.md for the design. Disable with =false to
|
|
# verify the silent-degradation contract locally.
|
|
KOHAKU_HUB_CACHE_ENABLED=true
|
|
KOHAKU_HUB_CACHE_URL=redis://127.0.0.1:26379/0
|
|
|
|
KOHAKU_HUB_SESSION_SECRET=dev-session-secret-change-me
|
|
KOHAKU_HUB_SESSION_EXPIRE_HOURS=168
|
|
KOHAKU_HUB_TOKEN_EXPIRE_DAYS=365
|
|
KOHAKU_HUB_REQUIRE_EMAIL_VERIFICATION=false
|
|
KOHAKU_HUB_INVITATION_ONLY=false
|
|
|
|
KOHAKU_HUB_ADMIN_ENABLED=true
|
|
KOHAKU_HUB_ADMIN_SECRET_TOKEN=dev-admin-token-change-me
|
|
# First backend bootstrap can auto-create fixed local demo users/orgs/repos.
|
|
KOHAKU_HUB_DEV_AUTO_SEED=true
|
|
|
|
KOHAKU_HUB_SITE_NAME="KohakuHub Dev"
|
|
KOHAKU_HUB_LOG_LEVEL=INFO
|
|
KOHAKU_HUB_LOG_FORMAT=terminal
|
|
KOHAKU_HUB_LFS_THRESHOLD_BYTES=1000000
|
|
KOHAKU_HUB_LFS_MULTIPART_THRESHOLD_BYTES=100000000
|
|
KOHAKU_HUB_LFS_MULTIPART_CHUNK_SIZE_BYTES=50000000
|
|
KOHAKU_HUB_LFS_KEEP_VERSIONS=5
|
|
KOHAKU_HUB_LFS_AUTO_GC=true
|