Files
mtusi2026lab3/docs/ARCHITECTURE.md

9.6 KiB

Устройство стенда

flowchart LR
    C[HTTP-клиент] --> L[HAProxy :8080]
    L --> A[API, реплика 1]
    L --> B[API, реплика 2]
    A & B --> P[(PostgreSQL)]
    A & B --> R[(Redis: сессии)]
    M[Одноразовые миграции] --> P

Только HAProxy публикует порт на loopback хоста. API подключены к сетям edge и data; PostgreSQL и Redis — только к внутренней data. Балансировщик не получает пароли БД и Redis. Сервис checks запускается явно через профиль tools; Docker socket нужен ему для сценариев отказа, приложение его не получает.

Состояние и транзакции

PostgreSQL хранит пользователей, чаты, членство, сообщения и результаты идемпотентных запросов. Redis хранит общие серверные сессии. В API нет локального хранилища бизнес-данных или сессий. Ключ подписи cursor одинаков на всех репликах и сохраняется в файле секрета. Следующую страницу можно читать через другую реплику.

Из lab2 перенесены параметризованные SQL-запросы, scrypt, ограничения пулов, таймауты и keyset-пагинация. Индекс истории: messages(chat_id, created_at, id). Для страницы выбираются максимум limit + 1 строк после (created_at, id), без OFFSET.

Миграция 001 сохранена без изменения. Новая 002 добавляет message_requests: составной PK (user_id, chat_id, request_key), fingerprint валидированного JSON, ID сообщения и срок действия. Метод и путь операции фиксированы: POST сообщения данного чата. Поэтому эта комбинация реализует область ключа «пользователь + метод + путь + ключ».

Отправка сообщения:

  1. Проверить действительность сессии и членство, формат ключа и JSON.
  2. В транзакции заблокировать строку чата FOR UPDATE. Блокировка общая для всех реплик.
  3. Удалить прежнюю запись данного ключа, если истекли 24 часа.
  4. Для действующего ключа сравнить fingerprint. При совпадении вернуть сохранённое сообщение с 201; при различии — 409.
  5. Для нового ключа назначить время, вставить сообщение и результат запроса, затем COMMIT. Только после этого вернуть 201.

Ошибка до COMMIT откатывает обе записи. После потери ответа клиент повторяет тот же ключ и JSON: при состоявшемся COMMIT получает прежний результат, иначе создаёт сообщение. Локальный mutex и sticky sessions для этого не используются. JSON разбирается до хеширования: пробелы и представление Unicode не меняют результат. В контракте lab3 тело содержит только text; вложения появляются в lab4.

В одном чате записи сериализуются. Метка времени выбирается после блокировки как максимум часов PostgreSQL и предыдущей метки + 1 микросекунда. Это сохраняет порядок при одинаковом времени или откате часов. Между страницами нет snapshot; новые сообщения могут появиться на следующей странице. Чтение идёт в PostgreSQL, кэша истории нет.

Сессия: случайный Bearer с энтропией 256 бит, SHA-256 токена в ключе Redis, абсолютный expiry и PXAT. Чтение и рестарт не продлевают срок. Logout удаляет ключ до 204. Для сохранности Redis настроены volume, AOF и appendfsync always. Потеря Redis даёт 503; локального обхода аутентификации нет.

Балансировка и остановка

HAProxy использует round-robin без affinity. Каждый ответ приложения, включая ошибку и health, содержит X-Instance-Id: hostname контейнера и случайный суффикс процесса. Это позволяет отличать и контейнеры, и перезапуски. Дополнительный X-App-Version показывает версию конфигурации при последовательной замене.

HAProxy опрашивает /health/ready каждую секунду: fall 2, rise 1, fastinter 500ms, timeout check 1s, timeout connect 1s. Консервативный бюджет исключения зависшего backend — до 4 секунд при штатном планировании; остановившийся процесс обычно обнаруживается быстрее. Docker healthcheck дополняет проверку LB и не заменяет её. Readiness API требует PostgreSQL и Redis, liveness зависит только от процесса.

Docker DNS 127.0.0.11 обновляет адреса api; server-template резервирует восемь backend-слотов. hold valid/obsolete — 1 секунда. При замене контейнера HAProxy получает новый IP без перезапуска. Для этого стенда поддерживаются 2–8 реплик.

API: SQL 2 s, lock 1 s, pool 1 s, Redis 1 s, общий HTTP-бюджет 5 s. HAProxy ждёт backend до 6 s, клиента до 10 s. Автоматических повторов в LB нет: повтор POST выполняет клиент с исходным ключом.

Uvicorn получает SIGTERM как PID 1, закрывает слушающий сокет и завершает текущие запросы в пределах 5 s. Docker даёт API 8 s. Публичный hook оставляет выбранную реплику остановленной и проверяет exit code 0. Нагрузка измеряет доступность через оставшуюся реплику.

Поочерёдная замена

scripts/experiments.py выполняет миграции один раз перед заменой. Для каждой из двух API-реплик находит backend по IP, включает drain через внутренний HAProxy Runtime API и ждёт завершения активных запросов. Затем останавливает и удаляет только этот контейнер и восстанавливает недостающую реплику командой compose up --no-recreate --scale api=2 api. Вторая продолжает работать. После обнаружения новой реплики через LB операция повторяется для второй.

Эксперимент проверяет поочерёдную замену контейнеров того же образа с новой меткой конфигурации APP_VERSION=lab3-v2. Изменение бизнес-логики между версиями не моделируется. Миграции 001/002 добавляют таблицы и совместимы с текущим lab3 API. Обновление с lab2 без промежуточной остановки не заявляется: старый API ещё не требует ключа идемпотентности.

Runtime API HAProxy доступен только внутри Docker-сети, порт 9999 не публикуется. Он используется операторским контейнером для drain; обычный клиент обращается только к опубликованному HTTP-порту.

Границы решения

Стенд выдерживает остановку одной API-реплики и перезапуск компонентов с сохранением volumes. Единственные PostgreSQL, Redis, HAProxy и Docker-host остаются точками отказа. Потеря диска, удаление volume, Redis flush и отказ всего host не покрываются. Это локальный учебный HTTP-стенд с синтетическими данными, без UI и TLS.

Просроченные записи идемпотентности удаляются при повторном использовании соответствующего ключа. Старые неиспользуемые ключи можно удалять отдельно по индексу expires_at; фоновая очистка в этой лабораторной не реализована.