# 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

Для MVP:

- operation хранит только `auth_profile_ref`;
- auth profile хранит только `secret_ref`;
- реальные секреты не должны попадать в YAML export;
- секреты не должны логироваться.

Допустимые варианты secret storage:

- env-backed secret store;
- encrypted local secret storage.

Минимальный безопасный вариант для MVP:

- `secret_ref` указывает на env variable alias или key в локальном secret store;
- приложение резолвит его на runtime.

## 5. Переменные окружения

Минимально ожидаются:

- `CRANK_DATABASE_URL`
- `CRANK_STORAGE_ROOT`
- `CRANK_ADMIN_BIND`
- `CRANK_MCP_BIND`
- `CRANK_MCP_REFRESH_MS`
- `CRANK_LOG_LEVEL`
- `CRANK_SECRET_PROVIDER`
- `CRANK_PUBLIC_BASE_URL`
- `CRANK_MCP_PUBLIC_URL`

Опционально:

- `CRANK_ADMIN_TOKEN`
- `CRANK_MASTER_KEY`

Стартовое значение для refresh published tools:

- `CRANK_MCP_REFRESH_MS=5000`

## 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;
- упрощенная auth-модель admin-api.

Demo/deployment:

- `PostgreSQL`;
- локальный или сетевой storage;
- включенная auth-защита admin-api;
- стабильный `Streamable HTTP` endpoint для MCP.
- containerized runtime через `Docker` и `docker-compose`.

## 8.1. Delivery artifacts

Для production-like запуска проект должен поставляться с:

- `Dockerfile` для backend приложений;
- `docker-compose.yml`;
- `.env.example`;
- healthcheck endpoints;
- reverse proxy configuration examples.

Подробности вынесены в `docs/deployment.md`.

## 9. Что важно не допустить

- пути к storage, зашитые в код;
- секреты в `.yaml` exports;
- разные конфигурационные модели для local и production без причины;
- смешивание runtime config и business config operation.

## 10. Практический итог

До старта разработки должны быть приняты как минимум такие решения:

- где лежит БД;
- где лежат artifacts;
- как резолвятся `secret_ref`;
- на каких bind-address запускаются `admin-api` и `mcp-server`;
- какой transport использует MCP server.