From 33a5773415ca4bf3a994e85068989ac7410ece89 Mon Sep 17 00:00:00 2001 From: "a.tolmachev" Date: Sun, 3 May 2026 20:58:15 +0000 Subject: [PATCH] docs: add optional cache layer plan --- TASKS.md | 39 +++++++++++++++++++++++++++++++++++ docs/commercial-boundaries.md | 3 +++ docs/implementation-plan.md | 19 +++++++++++++++-- docs/product-editions.md | 4 ++++ docs/repository-split-map.md | 3 +++ docs/runtime-config.md | 19 +++++++++++++++++ 6 files changed, 85 insertions(+), 2 deletions(-) diff --git a/TASKS.md b/TASKS.md index 2443050..8fa34cf 100644 --- a/TASKS.md +++ b/TASKS.md @@ -123,6 +123,45 @@ DoD: - Enterprise и Cloud используют private delivery path; - коммерческий код не требуется публиковать в open source ради поставки. +### `feat/optional-cache-layer` + +Status: ready + +Goal: +- добавить в продукт optional cache/coordination layer с `Valkey/Redis` backend без обязательной зависимости от него. + +Main code areas: +- `crates/crank-core` +- `crates/crank-runtime` +- `apps/admin-api` +- `apps/mcp-server` +- `deploy/community/*` +- `docs/runtime-config.md` +- `docs/product-editions.md` +- `docs/commercial-boundaries.md` + +Implementation slices: +1. Зафиксировать public cache contracts: + - response cache + - rate-limit store + - token replay / one-time token store + - ephemeral coordination state +2. Подготовить Community fallback path: + - без `Valkey/Redis` все должно работать + - degraded mode documented explicitly +3. Добавить optional `Valkey` service в Community deployment manifests как рекомендованный, но не обязательный runtime component. +4. Подготовить `Valkey/Redis` backend для: + - managed Cloud default + - enterprise optional cluster-aware deployment +5. Протянуть capability/config model так, чтобы решение "использовать или нет внешний cache" принимал оператор, а не кодовая база. + +DoD: +- без `Valkey/Redis` Community и self-hosted deployment остаются рабочими; +- с `Valkey/Redis` платформа умеет снижать runtime/load pressure и хранить ephemeral coordination state; +- `Cloud` может использовать shared cache layer по умолчанию; +- `Enterprise` может подключать cache layer на своей инфраструктуре, включая кластерный вариант; +- runtime/docs/manifests не делают cache обязательным для базового запуска. + ### `feat/live-authenticated-staging-entry` Status: ready diff --git a/docs/commercial-boundaries.md b/docs/commercial-boundaries.md index 7f01e6c..0eb2f85 100644 --- a/docs/commercial-boundaries.md +++ b/docs/commercial-boundaries.md @@ -30,6 +30,7 @@ - секреты, auth profiles, agent publishing, logs и usage; - статический ключ AI-агента; - контейнерное развертывание Community; +- optional cache abstraction и Community fallback path без внешнего cache store; - документация, тесты и демо-сценарии Community. ## 4. Что считается коммерческим контуром @@ -44,6 +45,7 @@ - advanced streaming execution modes; - metering и billing; - cloud control plane; +- managed shared cache layer defaults; - enterprise licensing and entitlement checks; - private operational tooling and support tooling. @@ -104,6 +106,7 @@ - edition flags; - protocol registry abstraction; - token issuer abstraction; +- cache store abstraction; - feature availability checks. Private code должен подключаться как реализация этих контрактов, а не как условные ветки по всему коду Community. diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md index ae79be2..fb61f50 100644 --- a/docs/implementation-plan.md +++ b/docs/implementation-plan.md @@ -179,7 +179,22 @@ - build provenance и подпись артефактов документированы; - коммерческий код не требуется публиковать в public repository. -## 13. Этап 10. Live staging and demo readiness +## 13. Этап 10. Optional cache and coordination layer + +### Цель + +Подготовить optional cache/coordination layer так, чтобы платформа могла использовать `Valkey/Redis`, +но не зависела от него для базового запуска. + +### DoD + +- определены абстракции для cache/coordination state; +- Community может запускаться без внешнего cache store; +- Community deployment path умеет поднимать optional `Valkey`; +- Cloud использует shared cache layer как default managed runtime component; +- Enterprise может подключать свой `Valkey/Redis` на уровне single-node или cluster deployment. + +## 14. Этап 11. Live staging and demo readiness ### Цель @@ -192,7 +207,7 @@ - demo user flow подтвержден на реальном окружении; - регрессии в publish/call/auth flow ловятся до релиза. -## 14. Связанные документы +## 15. Связанные документы - `docs/product-editions.md` - `docs/commercial-boundaries.md` diff --git a/docs/product-editions.md b/docs/product-editions.md index aef6a34..daa83f8 100644 --- a/docs/product-editions.md +++ b/docs/product-editions.md @@ -48,6 +48,7 @@ Crank развивается как три редакции: - статический ключ AI-агента; - только `security_level = standard`; - контейнерное развертывание; +- optional cache layer на базе `Valkey`, если оператор хочет снизить нагрузку; - документация, демо-сценарий и базовый CI. ### 3.3. Что не входит @@ -81,6 +82,7 @@ Crank развивается как три редакции: - `SSO`, `2FA`, расширенная `RBAC`, `audit log`; - `GraphQL`; - `gRPC unary`; +- shared cache layer, если он нужен для self-hosted production load; - короткоживущие машинные токены; - одноразовые токены для критичных операций; - `security_level = elevated` и `security_level = strict`; @@ -105,6 +107,7 @@ Crank развивается как три редакции: - usage metering; - тарифы и лимиты; - cloud control plane; +- shared cache layer по умолчанию для снижения нагрузки и хранения ephemeral coordination state; - эксплуатационный мониторинг и обновления со стороны поставщика; - биллинг и tenant-oriented support tooling. @@ -121,6 +124,7 @@ Crank развивается как три редакции: | WebSocket / SOAP / gRPC streaming | no | yes | yes | | Streaming modes | no | yes | yes | | Static agent key | yes | yes | yes | +| Optional Valkey/Redis cache backend | yes | yes | yes | | Short-lived MCP token | no | yes | yes | | One-time MCP token | no | yes | selectively | | `security_level = standard` | yes | yes | yes | diff --git a/docs/repository-split-map.md b/docs/repository-split-map.md index bab2c16..be38936 100644 --- a/docs/repository-split-map.md +++ b/docs/repository-split-map.md @@ -46,6 +46,7 @@ Public repository. - static AI-agent key; - only `security_level = standard`; - `deploy/community/*`; +- optional `Valkey` service definition для Community deployment; - public CI/CD for Community; - Community docs, smoke docs и demo flow. @@ -74,6 +75,7 @@ Private repository. - `audit log` - premium protocol/runtime additions, если они не входят в Community; - enterprise deployment manifests; +- optional cluster-aware cache integration для self-hosted production; - private container/release packaging; - enterprise operator docs. @@ -88,6 +90,7 @@ Private repository. - billing; - hosted tenant management; - hosted operational tooling; +- managed shared cache layer defaults and cache operations; - cloud-only delivery manifests; - cloud release pipeline; - hosted support/admin tooling. diff --git a/docs/runtime-config.md b/docs/runtime-config.md index 727517a..c6decb3 100644 --- a/docs/runtime-config.md +++ b/docs/runtime-config.md @@ -89,6 +89,9 @@ var/crank/ - `CRANK_ADMIN_TOKEN` - `CRANK_DEMO_SEED` +- `CRANK_CACHE_BACKEND` +- `CRANK_CACHE_URL` +- `CRANK_CACHE_DEFAULT_TTL_MS` Стартовое значение для refresh published tools: @@ -146,8 +149,23 @@ Demo/deployment: - включенная app-level auth-защита admin-api; - стабильный `Streamable HTTP` endpoint для MCP. - containerized runtime через `Docker` и `docker-compose`. +- optional shared cache layer через `Valkey/Redis`. - registry-backed image rollout через `GHCR` или совместимый registry. +### Cache env + +Для optional cache/coordination layer должны быть предусмотрены: + +- `CRANK_CACHE_BACKEND` +- `CRANK_CACHE_URL` +- `CRANK_CACHE_DEFAULT_TTL_MS` + +Рекомендуемая модель: + +- `CRANK_CACHE_BACKEND=memory` по умолчанию; +- `CRANK_CACHE_BACKEND=valkey` или `redis` при наличии внешнего cache store; +- без этих переменных система должна оставаться полностью работоспособной. + ### Auth env Для app-level auth нужны: @@ -226,6 +244,7 @@ runtime env-переменной. Это значит, что: - `Dockerfile` для backend приложений; - `deploy/community/docker-compose.yml` как canonical Community deployment manifest; - `deploy/community/.env.example` как canonical Community env template; +- optional `Valkey` service как рекомендованный, но не обязательный компонент Community deployment; - root `docker-compose.yml` и root `.env.example` только как local development convenience files; - healthcheck endpoints; - reverse proxy configuration examples.