# Требования к healthcheck / Healthcheck Requirements

Единая спецификация для реализации healthcheck в config_manager и в приложениях (в т.ч. MailOrderBot).

A unified specification for implementing healthcheck in config_manager and in applications (including MailOrderBot).

---

## 1. Назначение / Purpose

- Healthcheck используется скриптом деплоя (`deploy.sh`): после `docker compose up -d` деплой ждёт успешного ответа по `HEALTHCHECK_URL`; при таймауте — откат и выход с ошибкой.
- The healthcheck is used by the deploy script (`deploy.sh`): after `docker compose up -d`, the deploy waits for a successful response at `HEALTHCHECK_URL`; on timeout — rollback and exit with error.

- Эндпоинт должен отражать **реальное состояние приложения**, а не только факт работы HTTP-сервера (иначе деплой может считать успешным запуск «зависшего» или упавшего воркера).
- The endpoint must reflect the **actual state of the application**, not just that the HTTP server is running (otherwise deploy may consider successful a «hung» or crashed worker).

---

## 2. Поведение deploy.sh / deploy.sh behaviour

(Логика уже может быть реализована в коде deploy-скрипта.)

- Если задана переменная `HEALTHCHECK_URL` — после поднятия контейнеров вызывается `wait_for_healthcheck`: цикл с интервалом `HEALTHCHECK_INTERVAL` (по умолчанию 5 с), пока не истечёт `HEALTHCHECK_TIMEOUT` (по умолчанию 120 с).
- If `HEALTHCHECK_URL` is set — after bringing up containers, `wait_for_healthcheck` is called: a loop with interval `HEALTHCHECK_INTERVAL` (default 5 s) until `HEALTHCHECK_TIMEOUT` (default 120 s) expires.

- Проверка: `curl -fsS --max-time 5 "$HEALTHCHECK_URL"`. Флаг `-f`: любой HTTP-код 4xx/5xx считается ошибкой (повтор до таймаута).
- Check: `curl -fsS --max-time 5 "$HEALTHCHECK_URL"`. Flag `-f`: any HTTP 4xx/5xx is treated as failure (retry until timeout).

- **Успех:** HTTP 2xx. **Неуспех:** не 2xx или таймаут curl/соединения → деплой падает с откатом.
- **Success:** HTTP 2xx. **Failure:** non-2xx or curl/connection timeout → deploy fails with rollback.

### Переменные окружения / Environment variables

| Переменная / Variable     | Назначение / Purpose              | Пример/дефолт / Example/default     |
| ------------------------- | --------------------------------- | ----------------------------------- |
| `HEALTHCHECK_URL`         | URL для проверки / Check URL      | `http://127.0.0.1:8000/health`      |
| `HEALTHCHECK_TIMEOUT`     | Макс. время ожидания (сек) / Max wait (s) | `120`                        |
| `HEALTHCHECK_INTERVAL`    | Интервал между попытками (сек) / Interval between attempts (s) | `5` |

---

## 3. Контракт эндпоинта / Endpoint contract

- **Метод и путь / Method and path:** `GET /health` (или иной путь по соглашению; один для всех приложений на config_manager).
- **Method and path:** `GET /health` (or another agreed path; one for all applications using config_manager).

- **Успех (приложение в порядке) / Success (application healthy):** HTTP **200**, опционально тело JSON: `{"status": "ok"}`.
- **Success (application healthy):** HTTP **200**, optional JSON body: `{"status": "ok"}`.

- **Приложение не в порядке / Application not healthy:** HTTP **503**, опционально тело: `{"status": "unhealthy"|"degraded", "detail": "причина"}`.
- **Application not healthy:** HTTP **503**, optional body: `{"status": "unhealthy"|"degraded", "detail": "reason"}`.

- Ответ должен приходить в разумное время (рекомендуемый таймаут вызова логики проверки в config_manager — 2–5 с), иначе deploy через `curl --max-time 5` получит таймаут и будет повторять запросы.
- The response must arrive within a reasonable time (recommended timeout for the check logic in config_manager — 2–5 s); otherwise deploy will get a timeout via `curl --max-time 5` and will retry.

---

## 4. Обратная связь от приложения (config_manager) / Application feedback (config_manager)

- Эндпоинт реализуется в **config_manager** (опционально, при включённой опции).
- The endpoint is implemented in **config_manager** (optional, when the option is enabled).

- При обработке `GET /health` config_manager **не решает сам** «здорово ли приложение», а вызывает метод приложения, например: `app.get_health_status()`.
- When handling `GET /health`, config_manager does **not** decide by itself whether the application is healthy; it calls the application method, e.g. `app.get_health_status()`.

- **Контракт метода / Method contract** (приложение переопределяет в наследнике):
  - **Method contract** (application overrides in subclass):
  - Возвращает `dict`: `{"status": "ok" | "degraded" | "unhealthy", "detail": "..."}` (поле `detail` опционально).
  - Returns `dict`: `{"status": "ok" | "degraded" | "unhealthy", "detail": "..."}` (`detail` optional).
  - При исключении или превышении таймаута вызова — считать состояние unhealthy и отдавать 503.
  - On exception or call timeout — treat as unhealthy and return 503.

Таким образом, основное приложение «даёт обратную связь» через реализацию `get_health_status()` (флаги после сбоев, проверка БД, heartbeat и т.д.).

Thus, the main application provides feedback via `get_health_status()` (flags after failures, DB check, heartbeat, etc.).

---

## 5. Требования к приложению (например, MailOrderBot) / Application requirements (e.g. MailOrderBot)

- Переопределить `get_health_status()` и возвращать:
- Override `get_health_status()` and return:
  - `{"status": "ok"}` при нормальной работе;
  - `{"status": "ok"}` when running normally;
  - `{"status": "unhealthy", "detail": "..."}` при критичном сбое (например, последний `execute()` упал, зависимость недоступна);
  - `{"status": "unhealthy", "detail": "..."}` on critical failure (e.g. last `execute()` failed, dependency unavailable);
  - при желании — `{"status": "degraded", "detail": "..."}` для нефатальной деградации (в обоих случаях эндпоинт отдаёт 503 для совместимости с `curl -f`).
  - optionally — `{"status": "degraded", "detail": "..."}` for non-fatal degradation (in both cases the endpoint returns 503 for compatibility with `curl -f`).

---

## 6. Инфраструктура / Infrastructure

- Для работы healthcheck приложение должно поднимать HTTP-сервер (в config_manager при включённой опции) и пробрасывать порт в `docker-compose` (например `8000:8000`), чтобы `deploy.sh` на хосте мог обращаться по `HEALTHCHECK_URL` (например `http://127.0.0.1:8000/health`).
- For healthcheck to work, the application must run an HTTP server (in config_manager when the option is enabled) and expose the port in `docker-compose` (e.g. `8000:8000`), so that `deploy.sh` on the host can call `HEALTHCHECK_URL` (e.g. `http://127.0.0.1:8000/health`).