Основной конфиг (config.<mode>.yml)

Конфигурация разделена на несколько областей:

1. app — параметры самого приложения (сервер, HTTP-клиенты, флаги безопасности, сессии, очистка кэша).
2. oauth — параметры внешних OAuth-провайдеров (сейчас только Google для ACP).
3. infrastructure — подключения к внешним сервисам: PostgreSQL, Redis, Cloudflare Stream и платформы.
4. domain — бизнес-настройки (ивенты, конкурсы, правила соперников, настройки user-data batch).
5. observability — метрики и интеграция Prometheus.

Ниже описан каждый блок.

1. app

app.server

app:
server:
    id: 1            # произвольная строка/число, попадает в X-Server-Id
    host: 0.0.0.0    # слушаемый адрес
    port: 8080       # порт HTTP-сервера

app.http.timeouts

Таймауты для общего HTTP-клиента, используются стримами, traffic-flow и т.д. Формат — time.Duration.

app:
  http:
    timeouts:
      request: 30s
      dial: 20s
      keep_alive: 20s
      tls_handshake: 10s
      response_header: 10s
      handler: 60s          # таймаут обработки HTTP-запроса (middleware)

app.security

app:
  security:
    secret: "..."          # главный секрет (подписи платформ и т.д.)
    disable_auth: false     # глобально выключить проверку платформенных токенов
    enable_cors: false      # включить permissive CORS middleware (только для dev/тестов)
    max_body_size: "4MB"   # лимит размера тела запроса
    rate_limit:
      enabled: true        # включить rate limiting (per-IP, token bucket)
      rps: 100             # запросов в секунду
      burst: 200           # максимальный burst
    jwt:
      secret: "..."        # отдельный ключ для подписи сессионных JWT (HMAC-SHA256)
      ttl: 24h             # время жизни токена

Rate limiter хранится in-memory; при превышении возвращается HTTP 429 Too Many Requests.

jwt.secret — отдельный ключ, используемый для подписи и верификации JWT-токенов V2 сессий. Может быть использован другими сервисами для проверки токена. jwt.ttl — время жизни токена (формат time.Duration).

app.session.single_mode (DEPRECATED)

Deprecated: single-session mode — это legacy V1 функциональность. V2 использует исключительно JWT-авторизацию (Authorization: Bearer). Эти параметры будут удалены в будущих версиях.

app:
  session:
    single_mode:
      enabled: false  # V1 only: если true — выдаём X-Set-Session-Token и проверяем X-Session-Token
      blocking: false # V1 only: если true — блокируем запрос без актуальной сессии

app.online_ttl

Время, в течение которого пользователь считается «онлайн» после последнего запроса. Используется OnlineTracker для маркеров присутствия в Redis.

app:
  online_ttl: 5m   # формат time.Duration; по умолчанию 5m

app.cache_clear

app:
  cache_clear:
    enabled: true       # чистить volatile-кэши при старте контейнера
    patterns:
      - "marv:cache:users:*"
      - "marv:cache:streams:*"

app.invitation_awards

Строки с JSON-наградой, которые выдаются получателю/отправителю инвайта во V2:

app:
  invitation_awards:
    receiver: '{"currency":"coins","amount":100}'
    sender: '{"currency":"coins","amount":50}'

Если оставить строки пустыми (""), награда не отправится.

app.modules

Список модулей для загрузки. Позволяет управлять набором функционала через конфиг (без изменения кода):

app:
  modules:
    - user
    - world
    - transaction
    - message
    - event
    - stream
    - rival
    - abtest
    - remote_config
    - product
    - ads
    - alert
    - traffic_flow
    - bots
    - cron_task
    - merchant
    - platform
    - acp_user
    - system

Модули user, system, cron_task, merchant, platform, acp_user создаются по умолчанию; остальные — только если указаны.

app.routes

Включение/отключение групп HTTP-маршрутов:

app:
  routes:
    v1: false       # V1 API (deprecated)
    v2: true        # V2 API (основной)
    acp: true       # Admin Control Panel
    ext: true       # External webhooks

По умолчанию все роутеры выключены (если секция не указана). Явно укажите true для нужных.

app.min_version

Минимальные версии клиента по маршрутам. Ключ — regex для HTTP-пути, значение — минимальная версия (semver). Заголовок X-Client-Version проверяется middleware; если версия ниже — возвращается ошибка.

app:
  min_version:
    "^/v2": "1.2.0"       # все /v2/* требуют клиент >= 1.2.0
    "^/v2/streams": "1.5.0" # стримы требуют >= 1.5.0

Если секция пуста или отсутствует — проверка версий отключена.

Прочие поля

• app.cdn_url, app.log_dir, app.invite_bonus, app.validation.strict — доступны по тем же ключам внутри app.

2. oauth

oauth.google

Настройки Google OAuth для ACP:

oauth:
  google:
    client_id: "xxx.apps.googleusercontent.com" # аудитория, которую выдаёт Google в ACP UI
    certs: "{}"                                 # JWKS Google; обновляется задачей google_certs

certs автоматически переписывается системной задачей google_certs, которая периодически скачивает JWKS с https://www.googleapis.com/oauth2/v3/certs. Значение по умолчанию ({}) нужно только для инициализации схемы.

3. infrastructure

infrastructure.postgres

infrastructure:
postgres:
  host: localhost
  port: 5432
  username: app
  password: secret
  database: marv
    pool:
      max_open: 20
      max_idle: 10
      timeout: 300s
  sslmode: disable
    dry_run: false

infrastructure.redis

infrastructure:
redis:
  address: 127.0.0.1:6379
    password: ""
  db: 0
  pool: 10
    timeout: 300s     # используется как pool-timeout и default TTL
    store_ttl: 4h     # TTL для Set() без явного timeout

infrastructure.cloudflare

Учетные данные для Cloudflare API.

infrastructure:
  cloudflare:
    account_id: "..."
    api_token: "..."

infrastructure.platforms

Словарь платформ. Ключ — строковый api_type (числовой идентификатор платформы).

infrastructure:
  platforms:
    "2":
      type: vk
      credentials:
        id: "7365134"
        secret_key: "..."
    "30":
      type: ms_start
      credentials:
        id: "9NPZT17FTVZ4"
        package_name: "HGPOINTLTD.MergeHotel"
        secret_key: "..."
      merchant_profiles:
        default:
          type: xsolla
          merchant_id: "702055"
          project_id: "265997"
          api_key: "..."
          webhook_secret: "..."
        promo:
          type: xsolla
          merchant_id: "702055"
          project_id: "400001"
          api_key: "..."
          webhook_secret: "..."

type — тип платформы. Допустимые значения: default, unauthorized, ok, vk, fb, mm, mobage, dr, fs, gm, app_store, play_market, amazon, ms_store, ru_store, bazaar, galaxy_store, yandex, exe, beeline, play_deck, ms_start, tg, crazy_games, discord, myket.

name (опционально) — человекочитаемое имя платформы.

credentials — учётные данные платформы. Набор полей зависит от типа платформы:

Поле	Описание
id	Идентификатор приложения
app_id	Альтернативный ID приложения
uid	UID приложения
secret_key	Секретный ключ
application_key	Ключ приложения (OK)
auth_token	Токен авторизации
package	Имя пакета
package_name	Имя пакета (MS Store, RuStore)
client_id	Client ID (OAuth)
refresh_token	Refresh Token (Bazaar)
redirect_url	Redirect URL (OAuth)
consumer_key	Consumer Key (Mobage)
cert	Сертификат
public_key	Публичный ключ (RuStore)
private_key_id	ID приватного ключа (RuStore)
company_id	ID компании (RuStore)
bot_token	Токен бота (Telegram)

merchant_profiles — словарь профилей мерчанта. Ключ — произвольное имя профиля (используется в маршрутах /ext/{api_type}/{profile}/{action}).

Поля профиля:

Поле	Обязательное	Описание
type	да	Тип мерчанта (xsolla, rustore, ...)
merchant_id	нет	ID мерчанта
project_id	нет	ID проекта
api_key	нет	API-ключ
webhook_secret	нет	Секрет для подписи вебхуков
company_id	нет	ID компании (RuStore)
private_key_id	нет	ID приватного ключа (RuStore)

Для Xsolla Basic Auth (merchant_id:api_key) вычисляется автоматически при каждом запросе.

Профиль default используется, если в маршруте не указан конкретный профиль.

4. domain

domain:
  stream:
    delete_after: 1080h
    entrance_timeout: 900s
    proxy_url: "https://..."
    subdomain: "example.cloudflarestream.com"
  events:
    lookback: 336h
    dead_letter_queue:
      enabled: true
      max_retries: 3
  contest:
    group_size: 50
  rivals:
    max_count: 100
    compatible_api_types:
      vk: [1,2,3]
    platform_rules:
      - platform: app_store
        api_types: [1,2,3]
  user_updates:
    batch_size: 250
    ttl: 168h                # TTL записей в очереди обновлений

5. observability

observability:
  metrics:
    http_buckets_ms: [50, 100, 200, 500, 1000, 2000, 5000]
    prometheus_enabled: false

6. tasks

tasks.system

Системные cron-задачи, которые поднимаются из конфигурации (без записи в БД).

tasks:
  system:
    - name: "Reload Google certs"
      type: google_certs
      schedule: "0 */6 * * *"
      enabled: true
      scope: all          # leader (по умолчанию) или all
    - name: "Persist user data updates"
      type: user_data_batch_update
      schedule: "*/5 * * * *"
      enabled: true
      scope: leader
    - name: "Stats snapshot"
      type: stats_snapshot
      schedule: "0 * * * *"
      enabled: true
      start_immediately: true
      scope: leader

stats_snapshot — периодически рассчитывает агрегированную статистику пользователей (total, today, week, month, DAU, MAU) и сохраняет в in-memory StatsStore. Результат отдаётся через POST /acp/system/overview. Рекомендуется запускать раз в час на лидере; при start_immediately: true первый расчёт происходит сразу после старта.

scope управляет тем, где выполняется задача:

• leader — только на активном лидере (рекомендовано для операций с единственным воркером: перенос очередей из Redis в БД и т.п.)
• all — на каждом сервере (подходит для задач вроде обновления сертификатов или прогрева кэшей).

7. alerts

Шлюз критических уведомлений.

alerts:
  destinations:
    - name: payments_slack
      provider: slack                # slack / telegram
      endpoint: "https://hooks.slack.com/services/..."
      severities: [critical]
      tags: ["payments"]
      template: payment_critical
    - name: oncall_tg
      provider: telegram
      token: "<bot-token>"
      chat_id: -1001234567
      severities: [critical, warning]
      template: default_telegram
  templates:
    - id: payment_critical
      provider: slack
      text: |
        :rotating_light: *{{ .Title }}*
        {{ .Message }}
        {{ if .Payload.transaction_id }}ID: `{{ .Payload.transaction_id }}`{{ end }}
    - id: default_telegram
      provider: telegram
      text: |
        {{ .Title }}
        {{ .Message }}
        severity={{ .Severity }}

• destinations — куда отправлять события (Slack webhook, Telegram-чат и т.д.), плюс фильтры по severity/tag, выбор шаблона.
• templates — текстовые шаблоны (Go text/template). Доступные поля: Title, Message, Severity, Tags, Payload.

Полная JSON Schema расположена в infrastructure/config/koanf/schemas/config.schema.json.