- Основа: собственная лабораторная 2 (Flask/Waitress, Argon2id, Basic→Bearer, keyset-пагинация, сессии в PostgreSQL). Первая и вторая работы не редактировались.
## Запуск из чистого clone
## Среда и как запускалось в этой работе
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
В среде подготовки **не было Docker и бинарника HAProxy**, поэтому реплики, балансировщик и hooks были проведены как **локальные процессы** (см. «Ограничения»). Код, Compose-стенд и CI написаны для стандартной сдачи через Docker (см. ниже), но фактически валидировались локально.
- PostgreSQL 17.12 уже запущен на `127.0.0.1:5432`, учебная БД `lab3db` создана заранее; **БД не пересоздавалась и не перезапускалась** в ходе проверок (для persistence это важно: `pg_postmaster_start_time` не менялся).
- Две реплики API подняты как отдельные процессы: `api1` на `127.0.0.1:8083`, `api2` на `127.0.0.1:8084`, каждая со своим `X-Instance-Id`.
- Балансировщик — временный локальный round-robin на `127.0.0.1:8080` (эмуляция HAProxy: round-robin + healthcheck по `/health/ready`, отбрасывает недоступный backend). Файл балансировщика и hooks лежали в `/tmp` и **не входят в репозиторий**.
- Все публичные тесты (`make test`, `make test-idempotency`, `test-persistence`, `test-failover`) шли **через LB `127.0.0.1:8080`**.
### Запуск из чистого clone (стандартный путь — Docker/Compose)
Требуется Docker Engine/Desktop и Compose v2 с`up --wait`, Python 3.9+, доступ к Docker Hub и PyPI для первой сборки:
```sh
python3 scripts/init_local.py
docker compose config --quiet
docker compose up -d --build --wait --wait-timeout 120
curl --fail -i http://localhost:8080/health/ready
make check
make test
make test-idempotency
chmod +x scripts/restart.sh scripts/stop-one.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose ps -a
docker compose start api1 api2 # вернуть остановленную реплику перед дальнейшей работой
```
### Запуск без Docker (как в этой среде, локально)
```sh
# 1) миграции (отдельно от старта API; повтор безопасен, применённые версии пропускаются)
# 3) локальный балансировщик на 8080 (round-robin 8083/8084)
$PY /tmp/lab3_lb.py &
# 4) проверки через LB
make check validate test test-idempotency student-test PYTHON=$PYBASE_URL=http://127.0.0.1:8080
```
`make check` и `make validate` не требуют запущенного API. `make validate` устанавливает `requirements-dev.txt` (openapi-spec-validator).
### Миграции и жизненный цикл
- Команда `migrate` в Compose — отдельный job, выполняется до старта api1/api2. API сами миграции не запускают.
- Runner хранит версии в `schema_migrations` и работает под PostgreSQL advisory lock. `001` перенесён без изменений, `002` добавляет `message_requests` (идемпотентность).
- Повторное применение уже выполненных версий пропускается — `migrate` идемпотентен.
В локальном режиме: `$PY -m unittest discover -s student-tests -v` (в-процесс, против той же БД). Тесты создают синтетические записи; запускать на учебной БД.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Клиент → HAProxy (round-robin) → `api1` / `api2` → одна PostgreSQL. В БД общие пользователи, чаты, сообщения, сессии, ключ подписи курсоров и результаты идемпотентных отправок. Sticky sessions отсутствуют. Обе реплики используют одну схему и credentials; нет локального состояния, от которого зависит сохранность сообщений или идентификация.
| Роль | Compose service / образ | Готовность | Данные / сеть |
| --- | --- | --- | --- |
| Балансировщик | `lb`; haproxy:3.0.8-bookworm | backend `GET /health/ready` | Единственный опубликованный порт `127.0.0.1:8080` |
| Реплики API | `api1`, `api2`; python:3.11.11-slim-bookworm | `/health/ready` проверяет БД; `/health/live` — жизнь процесса | Только внутренняя сеть, собственных volumes нет |
| Миграции | `migrate`; тот же образ приложения | Завершение с exit 0 до старта API | Однократный job, не HTTP-сервис |
Credentials в Compose — через secrets (`postgres_password` для БД, `database_url` для migrate и API). Redis отсутствует: на уровне 3 сессии в PostgreSQL.
| Переменная из .env.example | Применение |
| --- | --- |
| APP_ENV | Метка стартового лога |
| SESSION_TTL_SECONDS | TTL новых сессий, по умолчанию 3600; для smoke/persistence ≥300 |
| IDEMPOTENCY_TTL_SECONDS | TTL результата отправки, минимум 86400; меньшее значение отклоняется |
| SESSION_STORE | Поддерживается только postgres |
| DATABASE_URL_FILE | Compose задаёт `/run/secrets/database_url`; локально можно дать `DATABASE_URL` |
| CACHE_URL_FILE | Не используется на уровне 3 |
| APP_HOST / APP_PORT | Для локального процесса читаются из окружения; Compose фиксирует `0.0.0.0:8080` |
| API_REPLICAS | В шаблоне 2; топология намеренно фиксирована на api1+api2 (уровень 3) |
Топология намеренно фиксирована на двух репликах. `container_name` не задан; расширение до 3+ требует отдельной доработки. `/docs` и `/swagger` не подключены.
### Балансировка, DNS, таймауты, остановка
HAProxy выбирает backend round-robin. Readiness раз в 1s, `fall=2`, `rise=1`, `timeout check=1s`. `retries 0` — автоматический replay POST в LB выключен; клиент повторяет неопределённую отправку сам с прежним Idempotency-Key. На SIGTERM API прекращает принимать новые соединения, выставляет DRAINING и до 5s продолжает сетевой цикл; завершение worker ограничено ещё 1s. Используется Waitress 3.0.2 (версия закреплена) — это ограниченный drain, а не гарантия завершения любого долгих запрос.
`stop-one.sh` получает `TARGET_INSTANCE_ID`, читает настоящий `X-Instance-Id` каждой реплики через `docker compose exec`, находит соответствующий контейнер и останавливает только его; состояние сохраняется в `evidence/stop-api1.txt`/`stop-api2.txt`. Автоматический restart не включён.
`restart.sh` останавливает LB и обе API, перезапускает PostgreSQL с тем же volume, ждёт БД, запускает API и LB. Не удаляет данные и не выполняет seed. Evidence — `evidence/restart-*.txt`.
## Идемпотентность и транзакционная граница
Область ключа — текущий пользователь + POST сообщений конкретного чата + Idempotency-Key. Метод/тип endpoint заданы назначением таблицы; пользователь/чат/ключ — её PK. Новый ключ — новая отправка, даже при одинаковом тексте.
В одной транзакции: проверить членство → взять advisory transaction lock по хешу области → найти непросроченный результат → либо вернуть его/409, либо вставить Message и строку `message_requests` → COMMIT. Поиск — по полному ключу; 64-битный хеш только для блокировки, коллизия не подменяет результат.
При одновременном повторе вторая реплика ждёт lock и видит COMMIT первой. Одинаковый текст — те же id/created_at и HTTP 201, другой текст — 409. Токен проверяется заново при каждом HTTP-повторе; локального кэша результатов нет. TTL результата — 24 часа по умолчанию, повтор не продлевает. Схема описана в [infra/DATABASE.md](infra/DATABASE.md).
## Что перенесено и что изменено
Сохранены: HTTP/сервисный слой/Repository, Flask/Waitress, Argon2id, Basic→Bearer, expiry/logout, членство, валидация, формат ошибок, SQL keyset-пагинация, хранение данных и сессий в PostgreSQL.
Изменения lab3:
-`api.py` создаёт случайный `X-Instance-Id` один раз при создании приложения; все ответы (включая ошибки и health) получают его и `X-Request-Id`. Заголовок стабилен в течение жизни процесса.
-`service.py` требует Idempotency-Key только для POST сообщения; допустим ASCII `[A-Za-z0-9._:-]{1,128}`, иначе 400.
-`postgres.py` и миграция `002` обеспечивают единый результат повторной отправки через разные процессы.
- Миграции вынесены из старта API в отдельный job; добавлены HAProxy, Compose и реальные restart/stop hooks.
- Адаптированы собственные тесты под ключи и вторую версию миграции; добавлена конкурентная HTTP-проверка через LB.
## Доказательства критериев
Все публичные проверки — через LB `127.0.0.1:8080` в локальной среде (без Docker/HAProxy). Команды и stdout сохранены в `evidence/`.
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Структура и OpenAPI | `make check`, `make validate` | PASS (offline structure; full OpenAPI 3.1 + JSON Schema) | evidence/local-checks.txt |
| Публичный smoke (контракт lab3) | `make test BASE_URL=http://127.0.0.1:8080` | PASS (lab3 public API scenario) | evidence/local-checks.txt |
| Общая идемпотентность | `make test-idempotency` | 24 запроса / 8 клиентов / ≥2 X-Instance-Id через LB → одно сообщение, все 201 и равны; conflict 409, scope/404/401 | evidence/local-checks.txt |
| Полный рестарт (persistence) | `make test-persistence ACTION_SCRIPT=<restart hook>` | Прежний токен и сообщение сохранены; PID API изменились, `pg_postmaster_start_time` не изменился (БД не трогалась) | evidence/local-restart.txt; evidence/restart-*.txt |
| Реальность рестарта | Смена PID/X-Instance-Id API, `pg_postmaster_start_time` | Те же данные; без reseed | evidence/restart-before.txt; evidence/restart-after.txt |
| Отказ одной реплики (failover) | `make test-failover ACTION_SCRIPT=<stop-one hook>` | 102 успешные записи, 0 неудач, восстановление 0.321s; LB переключился на живую реплику | evidence/local-stops.txt; evidence/stop-api1.txt |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Гипотеза: отказ одного процесса API при живой второй реплике должен перекрываться LB без потери подтверждённых записей. Проверено публичным `test-failover` (15-секундный сценарий, не измерение предельного RPS).
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Рестарт обеих реплик (БД не трогать) | Сессия и данные сохранены | PASS: токен и сообщение живы, PID изменились | — / без потерь |
| Остановка одной реплики под нагрузкой | LB уходит на живую, записи не теряются | PASS: 102 записей, 0 неудач | 0.321s / без потерь |
Нагрузочное исследование (RPS, p50/p95/p99, CPU/RAM) **не заявляется** на уровне 3.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- **Docker/Compose и HAProxy в среде подготовки отсутствовали**, поэтому весь публичный/собственный набор проверок и persistence/failover были проведены **локальными процессами** (две реплики + временный round-robin балансировщик и hooks в `/tmp`, не входящие в репозиторий). Код, Compose-стенд (`compose.yaml`, `infra/haproxy.cfg`, `Dockerfile`) и CI (`application.yml`) подготовлены для стандартной сдачи через Docker, но **в этой среде не исполнялись**.
- Коммиты `scripts/restart.sh`/`stop-one.sh` написаны под `docker compose` (стандартная сдача). В локальной валидации persistence/failover выполнялись эквивалентными временными hooks в `/tmp` (`/tmp/lab3_restart.sh`, `/tmp/lab3_stop_one.sh`), которые перезапускали/останавливали процессы по pidfile и `TARGET_INSTANCE_ID`/`X-Instance-Id` и **не трогали БД**.
- Отказ одного процесса API при живой второй реплике выдерживается. Единые PostgreSQL и HAProxy и один host — остаются точками отказа: потеря узла/диска/volume не покрыта. Две API не делают БД высокодоступной.
- Не реализовано: connection pool, ресурсные лимиты, rolling update под нагрузкой, backup/restore, масштабирование 1/2/4. Уровень 4 и трек 5 не заявлены.
- Сессии общие, потому что в БД, а не из-за закрепления клиента за репликой. Время сообщений задаёт PostgreSQL, а не часы процессов.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.