chore: publish clean community baseline

docs/runtime-config.md

@@ -0,0 +1,313 @@
+# Runtime Config
+
+## 1. Назначение документа
+
+Этот документ фиксирует конфигурацию окружения, storage и базовые operational assumptions для MVP.
+
+Его задача - убрать неявные решения, которые обычно всплывают уже в процессе написания кода.
+
+## 2. Базовые решения для MVP
+
+- каноническая БД: `PostgreSQL`
+- локальная разработка и тесты используют ту же `PostgreSQL`-модель хранения
+- artifact storage: локальная файловая система
+- MCP transport: `Streamable HTTP`
+- admin API и mcp-server запускаются как отдельные приложения
+
+## 3. Artifact storage
+
+В MVP sample JSON, `.proto`, `descriptor set` и YAML import payload должны храниться в локальном файловом storage.
+
+Требования:
+
+- все файлы кладутся в контролируемый базовый каталог;
+- в БД хранится только `storage_ref`;
+- структура каталогов должна быть детерминированной;
+- storage слой должен быть абстрагирован, чтобы потом заменить его на S3-compatible backend.
+
+Рекомендуемая структура:
+
+```text
+var/crank/
+  samples/
+  descriptors/
+  yaml-imports/
+```
+
+## 4. Секреты и auth profiles
+
+Для целевой модели:
+
+- operation хранит только `auth_profile_ref`;
+- `AuthProfile` хранит только ссылки на `secret_id`;
+- plaintext секреты не должны попадать в YAML export;
+- plaintext секреты не должны логироваться;
+- runtime получает секрет только на короткое время перед upstream вызовом.
+
+Стартовая реализация:
+
+- `PostgreSQL`-backed secret store;
+- `ciphertext` хранится в БД;
+- шифрование выполняется через `CRANK_MASTER_KEY`;
+- ключ шифрования приходит только из env.
+
+## 5. Переменные окружения
+
+Минимально ожидаются:
+
+- `POSTGRES_HOST`
+- `POSTGRES_PORT`
+- `POSTGRES_DB`
+- `POSTGRES_USER`
+- `POSTGRES_PASSWORD`
+- `POSTGRES_MAX_CONNECTIONS`
+- `POSTGRES_MIN_CONNECTIONS`
+- `POSTGRES_ACQUIRE_TIMEOUT_MS`
+- `POSTGRES_IDLE_TIMEOUT_MS`
+- `POSTGRES_MAX_LIFETIME_MS`
+- `CRANK_ADMIN_API_IMAGE`
+- `CRANK_MCP_SERVER_IMAGE`
+- `CRANK_UI_IMAGE`
+- `CRANK_STORAGE_ROOT`
+- `CRANK_PUBLISH_BIND`
+- `CRANK_ADMIN_BIND`
+- `CRANK_ADMIN_RATE_LIMIT_RPS`
+- `CRANK_ADMIN_RATE_LIMIT_BURST`
+- `CRANK_MCP_BIND`
+- `CRANK_MCP_REFRESH_MS`
+- `CRANK_MCP_RATE_LIMIT_RPS`
+- `CRANK_MCP_RATE_LIMIT_BURST`
+- `CRANK_RUNTIME_MAX_CONCURRENT_UNARY`
+- `CRANK_RUNTIME_MAX_CONCURRENT_WINDOW`
+- `CRANK_RUNTIME_MAX_CONCURRENT_SESSIONS`
+- `CRANK_RUNTIME_MAX_CONCURRENT_JOBS`
+- `CRANK_LOG_LEVEL`
+- `CRANK_MASTER_KEY`
+- `CRANK_BASE_URL`
+
+Опционально:
+
+- `CRANK_ADMIN_TOKEN`
+- `CRANK_DEMO_SEED`
+- `CRANK_CACHE_BACKEND`
+- `CRANK_CACHE_URL`
+- `CRANK_CACHE_DEFAULT_TTL_MS`
+
+Стартовое значение для refresh published tools:
+
+- `CRANK_ADMIN_RATE_LIMIT_RPS=30`
+- `CRANK_ADMIN_RATE_LIMIT_BURST=60`
+- `CRANK_MCP_REFRESH_MS=5000`
+- `CRANK_MCP_RATE_LIMIT_RPS=60`
+- `CRANK_MCP_RATE_LIMIT_BURST=120`
+
+Стартовые значения для runtime concurrency limits:
+
+- `CRANK_RUNTIME_MAX_CONCURRENT_UNARY=64`
+- `CRANK_RUNTIME_MAX_CONCURRENT_WINDOW=16`
+- `CRANK_RUNTIME_MAX_CONCURRENT_SESSIONS=16`
+- `CRANK_RUNTIME_MAX_CONCURRENT_JOBS=16`
+
+## 6. Логирование и трассировка
+
+Для MVP нужно использовать:
+
+- structured logging через `tracing`;
+- correlation id для test runs и runtime execution;
+- раздельные стадии ошибок: schema, mapping, adapter, external service.
+
+## 7. Таймауты и retries
+
+Рекомендуемые стартовые значения:
+
+- default timeout: `10s`
+- retry default: `1` attempt, то есть без автоматического повтора
+
+Причина:
+
+- сначала важнее детерминированность и прозрачность;
+- aggressive retries могут маскировать реальные ошибки интеграции.
+
+## 8. Режимы запуска
+
+Минимально нужны два режима:
+
+- local development
+- demo/deployment
+
+Local development:
+
+- локальное окружение должно иметь доступ к `PostgreSQL`;
+- локальный storage;
+- app-level auth и bootstrap admin user через `.env`.
+- при необходимости UI можно наполнить живыми demo-данными через `CRANK_DEMO_SEED=true`.
+
+Demo/deployment:
+
+- `PostgreSQL`;
+- локальный или сетевой storage;
+- включенная app-level auth-защита admin-api;
+- стабильный `Streamable HTTP` endpoint для MCP.
+- containerized runtime через `Docker` и `docker-compose`.
+- optional shared cache layer через `Valkey/Redis`.
+- registry-backed image rollout через Gitea Container Registry или совместимый 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;
+- без этих переменных система должна оставаться полностью работоспособной.
+
+### Cache boundaries
+
+В платформе должны существовать два разных cache-контура:
+
+- `platform / coordination cache`
+- `response cache`
+
+Первый контур хранит служебное краткоживущее состояние:
+
+- ingress rate limiting;
+- replay guard;
+- ephemeral coordination state;
+- shared snapshots published MCP catalogs between instances;
+
+Второй контур хранит только кэшируемые ответы операций.
+
+Текущий безопасный runtime scope для response cache:
+
+- `REST GET`;
+
+Это не означает автоматическое кэширование всех REST-вызовов. Кэширование
+разрешается только для безопасных `GET` operations без upstream auth profile.
+
+Эти контуры не должны смешивать ключи друг с другом.
+
+### Cache key isolation
+
+Базовое правило изоляции:
+
+- разные `workspace` не должны делить одни и те же cache keys;
+- разные `agent` внутри одного `workspace` тоже не должны делить одни и те же response cache keys по умолчанию;
+- разные `operation` внутри одного `agent` не должны попадать в общий response cache namespace.
+
+Стартовая модель namespace для response cache:
+
+- `workspace + agent + operation + operation version + request fingerprint`
+
+Стартовая модель namespace для platform / coordination cache:
+
+- `workspace + agent + cache scope + logical key`
+
+Это позволяет безопасно использовать один внешний `Valkey/Redis` сразу для нескольких агентов и рабочих областей без взаимного пересечения данных.
+
+### Auth env
+
+Для app-level auth нужны:
+
+- `CRANK_SESSION_SECRET`
+- `CRANK_PASSWORD_PEPPER`
+- `CRANK_BOOTSTRAP_ADMIN_EMAIL`
+- `CRANK_BOOTSTRAP_ADMIN_PASSWORD`
+- `CRANK_BOOTSTRAP_ADMIN_DISPLAY_NAME`
+
+Для secret store foundation нужен:
+
+- `CRANK_MASTER_KEY`
+
+`CRANK_MASTER_KEY` обязателен и для `admin-api`, и для `mcp-server`, потому что оба приложения
+должны уметь резолвить `secret_id` в runtime.
+
+Для опционального demo-seed:
+
+- `CRANK_DEMO_SEED=true`
+
+В deployment workflow больше не используется монолитный `DEPLOY_ENV_FILE`.
+
+`.env` на сервере собирается из OpenBao. В Gitea Actions хранятся только AppRole credentials
+`BAO_ADDR`, `BAO_ROLE_ID` и `BAO_SECRET_ID`, а внутри OpenBao ключи проекта
+`projects/crank/runtime` совпадают с именами runtime env-переменных. Это значит, что:
+
+- `CRANK_MASTER_KEY` хранится в OpenBao как ключ `CRANK_MASTER_KEY`;
+- `CRANK_DEMO_SEED` хранится в OpenBao как ключ `CRANK_DEMO_SEED`;
+- и так же для остальных runtime-переменных.
+
+Для БД основной runtime-контракт теперь компонентный:
+
+- `POSTGRES_HOST`
+- `POSTGRES_PORT`
+- `POSTGRES_DB`
+- `POSTGRES_USER`
+- `POSTGRES_PASSWORD`
+- `POSTGRES_MAX_CONNECTIONS`
+- `POSTGRES_MIN_CONNECTIONS`
+- `POSTGRES_ACQUIRE_TIMEOUT_MS`
+- `POSTGRES_IDLE_TIMEOUT_MS`
+- `POSTGRES_MAX_LIFETIME_MS`
+
+Для pool behavior используются явные defaults:
+
+- `POSTGRES_MAX_CONNECTIONS=20`
+- `POSTGRES_MIN_CONNECTIONS=2`
+- `POSTGRES_ACQUIRE_TIMEOUT_MS=5000`
+- `POSTGRES_IDLE_TIMEOUT_MS=600000`
+- `POSTGRES_MAX_LIFETIME_MS=1800000`
+
+Для runtime concurrency используются явные defaults:
+
+- `CRANK_RUNTIME_MAX_CONCURRENT_UNARY=64`
+- `CRANK_RUNTIME_MAX_CONCURRENT_WINDOW=16`
+- `CRANK_RUNTIME_MAX_CONCURRENT_SESSIONS=16`
+- `CRANK_RUNTIME_MAX_CONCURRENT_JOBS=16`
+
+Для MCP transport ingress throttling используются явные defaults:
+
+- `CRANK_MCP_RATE_LIMIT_RPS=60`
+- `CRANK_MCP_RATE_LIMIT_BURST=120`
+
+Для admin-api ingress throttling используются явные defaults:
+
+- `CRANK_ADMIN_RATE_LIMIT_RPS=30`
+- `CRANK_ADMIN_RATE_LIMIT_BURST=60`
+
+`CRANK_DATABASE_URL` допускается только как backward-compatible fallback для локальных тестов и
+переходного периода, но не как основная deployment-модель.
+
+## 8.1. Delivery artifacts
+
+Для production-like запуска проект должен поставляться с:
+
+- `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.
+
+Подробности вынесены в `docs/deployment.md`.
+
+## 9. Что важно не допустить
+
+- пути к storage, зашитые в код;
+- секреты в `.yaml` exports;
+- разные конфигурационные модели для local и production без причины;
+- смешивание runtime config и business config operation.
+
+## 10. Практический итог
+
+До старта разработки должны быть приняты как минимум такие решения:
+
+- где лежит БД;
+- где лежат artifacts;
+- как резолвятся `secret_id` и как ротируется `CRANK_MASTER_KEY`;
+- на каких bind-address запускаются `admin-api` и `mcp-server`;
+- какой transport использует MCP server.