docs: add optional cache layer plan

2026-05-03 20:58:15 +00:00
parent 201fe16aae
commit 33a5773415
6 changed files with 85 additions and 2 deletions
@@ -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
@@ -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.
@@ -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`
@@ -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 |
@@ -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.
@@ -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.