lab3 load balancer haproxy

This commit is contained in:
2026-10-27 13:50:56 +03:00
parent 0ab3a341aa
commit 1b476ee432
47 changed files with 5049 additions and 3790 deletions
+13
View File
@@ -0,0 +1,13 @@
FROM python:3.12.11-slim-bookworm
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_DISABLE_PIP_VERSION_CHECK=1
WORKDIR /app
RUN addgroup --system app && adduser --system --ingroup app app
COPY requirements.txt ./requirements.txt
RUN python -m pip install --no-cache-dir -r requirements.txt
COPY src ./src
COPY migrations ./migrations
COPY scripts ./scripts
USER app
EXPOSE 8080
STOPSIGNAL SIGTERM
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8080", "--timeout-graceful-shutdown", "10", "--proxy-headers"]
+144
View File
@@ -0,0 +1,144 @@
# Отчёт — лабораторная 3
- Автор, группа: Миронов Алексей, бвт2302
- Целевая оценка: 4; трек 5 не заявлен
- Commit/PR: заполнить после публикации
- Использованные источники, библиотеки и помощь ИИ: исходный репозиторий лабораторной 3 и его `COURSE.md`, `README.md`, `contracts/README.md`, `contracts/openapi.json`, `tests/`; перенесённая собственная реализация лабораторной 2; FastAPI, Pydantic, psycopg/psycopg-pool, PostgreSQL, Redis, Argon2, HAProxy, Docker Compose; использовалась помощь ИИ.
## Запуск из чистого clone
Требуются Docker Engine с Compose v2 и GNU Make. Команды выполняются из корня репозитория. Стенд предназначен только для локальных синтетических данных.
1. Создать `.env` и задать уникальный локальный пароль PostgreSQL:
```bash
cp .env.example .env
```
2. Проверить структуру и конфигурацию:
```bash
make check
pip install -r requirements-dev.txt
make validate
docker compose --env-file .env config --quiet
```
3. Собрать образы и запустить две API-реплики за HAProxy:
```bash
docker compose --env-file .env up -d --build --scale api=2
```
`migrate` запускается однократно после готовности PostgreSQL и до API.
Проверить `docker compose --env-file .env ps` и `curl -i http://localhost:8080/health/ready`.
4. Проверить контракт и общую идемпотентность:
```bash
make test
python tests/grade4_checks.py
```
5. Проверить сохранность состояния и отказ реплик (только на тестовом стенде):
```bash
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
```
Failover-тест оставляет одну реплику остановленной. Восстановить желаемые две реплики: `docker compose --env-file .env up -d --scale api=2 api`. Проверить отказ для каждой реплики отдельно, каждый раз восстанавливая предыдущую.
6. Нагрузка и поочерёдная замена:
```bash
make load
# В отдельном терминале можно запустить `bash scripts/rolling-restart.sh`
(проверка того, что апи-реплики могут перезапускаться по отдельности без изменения, не останавливая всё приложение. Это проверка отказоустойчивости, балансировщик должен перенаправлять запросы на доступную реплику, пока другая перезапускается)
```
Сохранить фактические параметры и JSON-нагрузку в `evidence/`. Команды ожидания готовности и остановки: `docker compose --env-file .env down` (volumes сохраняются); для намеренного удаления учебных данных использовать `docker compose --env-file .env down -v` только после явного решения удалить БД и Redis.
## Архитектура и решения
Клиент → HAProxy → две и более взаимозаменяемые FastAPI-реплики → общая PostgreSQL и общий Redis. В Compose наружу опубликован только HAProxy на `127.0.0.1:8080`; API-реплики доступны лишь во внутренней сети. HAProxy опрашивает `/health/ready`, исключает backend после неуспешных проверок и повторно включает после восстановления. Период проверки — 1 с; исключение после двух ошибок ожидается примерно за 2 с плюс timeout/расписание проверок, фактическое время необходимо измерить.
- **Перенос из lab2:** `src/main.py`, базовая SQL-схема пользователей/чатов/участников/сообщений, Redis-сессии, Argon2, пагинация и формат ошибок перенесены. Также перенесены зависимости, `examples/requests.http`, `.gitignore` и `scripts/restart.sh`. В `REPORT1.md` явно фиксируется этот перенос.
- **Изменения lab3:** добавлен `X-Instance-Id` (hostname контейнера, стабильный в пределах его жизни), обязательный `Idempotency-Key` при POST сообщения и таблица `idempotency_records`. Тело запроса нормализуется перед SHA-256; транзакционная advisory lock сериализует одинаковый ключ на всех репликах; запись сообщения и сохранённого ответа выполняется в одной транзакции PostgreSQL. Идентичный повтор в течение 24 часов возвращает исходный `201` и то же сообщение; другой body при том же ключе получает `409`.
- **Миграции:** `scripts/migrate.py` — отдельный одноразовый Compose-сервис, применяющий миграции в порядке имени и записывающий версии в `schema_migrations`. API-реплики не пытаются одновременно менять схему при старте.
- **Сессии:** остаются в Redis, который использует AOF и именованный volume; PostgreSQL — источник истины для бизнес-данных и идемпотентности.
- **Health/shutdown:** `/health/live` проверяет процесс, `/health/ready` проверяет PostgreSQL и Redis. Uvicorn получает SIGTERM, graceful timeout — 10 с, Compose `stop_grace_period` — 15 с.
- **Ресурсы:** Compose задаёт CPU/RAM limits для API, PostgreSQL, Redis и HAProxy. Это ограничения на одном Docker-host, не гарантия доступности при потере хоста.
- **Секреты:** `.env` игнорируется Git и не копируется в образ.
## Доказательства критериев
| Критерий | Команда/сценарий | Фактический результат | Источник |
|---|---|---|---|
| Структура проекта и синтаксис | `make check` | **PASS:** проверка офлайн-структуры, локальных ссылок и синтаксиса Python. В выводе отдельно указано, что приложение этим тестом не проверялось. | `evidence.txt` |
| OpenAPI и JSON Schema | `make validate` | **PASS:** полная валидация OpenAPI 3.1 и JSON Schema. В выводе отдельно указано, что приложение этим тестом не проверялось. | `evidence.txt` |
| Конфигурация Docker Compose | `docker compose --env-file .env config --quiet` | Команда завершилась без диагностического вывода. Отдельный код завершения в предоставленном фрагменте не зафиксирован. | `evidence.txt` |
| Сквозной публичный API | `make test` | **PASS:** `lab3 public API scenario`. | `evidence.txt` |
| Две разные API-реплики и конкурентная идемпотентность | `python3 tests/grade4_checks.py` | **PASS:** наблюдались две разные реплики (`21d7ab63f9dc`, `3c995d3af7ef`); 12 параллельных запросов дали один уникальный ID сообщения; изменённое тело с тем же ключом вернуло HTTP 409; отсутствующий и некорректный ключи вернули HTTP 400. | `evidence.txt` |
| Сохранность данных и сессии после перезапуска | `make test-persistence ACTION_SCRIPT=./scripts/restart.sh` | **PASS:** подтверждённые данные и существующая сессия сохранены. Вывод содержит предупреждение: `Hook scope needs operator evidence`; область действия hook требует отдельного подтверждения оператором. | `evidence.txt` |
| Failover одной API-реплики | `make test-failover ACTION_SCRIPT=./scripts/stop-one.sh` | **PASS:** до отказа наблюдались 2 экземпляра; зафиксировано 73 успешные записи, 1 неудачная попытка и 3,223 секунды до первой успешной записи после восстановления. Подтверждена сохранность данных и сессии. В предоставленном результате не указано, что проверка отдельно повторялась для каждой реплики. | `evidence.txt` |
| Нагрузка без перезапуска | `make load` | **PASS:** 30,088 с; concurrency=4; 1528 успешных запросов, 0 неудачных; error ratio 0; 50,785 успешного запроса/с; p50=64,545 мс, p95=192,316 мс, p99=258,186 мс. Процентили рассчитаны только по успешным запросам. | `evidence.txt` |
| Rolling restart | `bash scripts/rolling-restart.sh` | **PASS:** скрипт завершился сообщением `rolling restart completed with 2 healthy API replicas`. | `evidence.txt` |
| Нагрузка во время rolling restart | `make load`, выполнявшийся параллельно с rolling restart | **Выполнено, но не без ошибок:** 30,128 с; concurrency=4; 1839 успешных запросов и 9 неудачных; error ratio=0,00487 (около 0,487%); 61,039 успешного запроса/с; p50=33,306 мс, p95=97,359 мс, p99=163,583 мс. Типы этих 9 ошибок в приведённом JSON не указаны. | `evidence.txt` |
|
## Эксперименты и отказы
В качестве доказательств используются только результаты из `evidence.txt`. Метрики нагрузки получены закрытым циклом POST-запросов к сообщениям, с concurrency=4, длительностью около 30 секунд и без автоматических повторов. В выводе теста отдельно отмечено, что процентили задержки учитывают только успешные запросы, а closed-loop профиль подвержен coordinated omission и накладным расходам клиента. Поэтому значения характеризуют именно этот тестовый профиль и не являются универсальной оценкой пропускной способности сервиса.
OS: Майкрософт Windows 11 Pro 10.0.22631 (build 22631)
CPU: Intel(R) Core(TM) i5-8350U CPU @ 1.70GHz, cores=4, threads=8
RAM: 15.9 GB
Docker Compose version v2.32.4-desktop.1
docker version
Client:
Version: 27.5.1
API version: 1.47
Go version: go1.22.11
Git commit: 9f9e405
Built: Wed Jan 22 13:41:44 2025
OS/Arch: windows/amd64
Context: desktop-linux
Server: Docker Desktop 4.38.0 (181591)
Engine:
Version: 27.5.1
API version: 1.47 (minimum version 1.24)
Go version: go1.22.11
Git commit: 4c9b3b0
Built: Wed Jan 22 13:41:17 2025
OS/Arch: linux/amd64
Experimental: false
containerd:
Version: 1.7.25
GitCommit: bcc810d6b9066471b0b6fa75f557a15a1cbf31bb
runc:
Version: 1.1.12
GitCommit: v1.1.12-0-g51d5e946
docker-init:
Version: 0.19.0
GitCommit: de40ad0
### Сводка нагрузочных прогонов
| Сценарий | Длительность | Успешные | Ошибки | Error ratio | Успешных запросов/с | p50 | p95 | p99 |
|---|---:|---:|---:|---:|---:|---:|---:|---:|
| Обычная нагрузка | 30,088 с | 1528 | 0 | 0% | 50,785 | 64,545 мс | 192,316 мс | 258,186 мс |
| Нагрузка во время rolling restart | 30,128 с | 1839 | 9 | 0,487% | 61,039 | 33,306 мс | 97,359 мс | 163,583 мс |
Успешные RPS и задержки различаются между двумя прогонами; на основании только этих двух запусков нельзя заключать, что rolling restart сам по себе повышает производительность. Во время параллельного прогона было 9 ошибок, поэтому результат не подтверждает полностью безошибочную доступность при замене реплик. Предоставленный JSON не содержит классификации ошибок, поэтому их HTTP-коды и причины здесь не приписываются.
### Проверки идемпотентности и отказоустойчивости
| Воздействие | Наблюдение из `evidence.txt` | Вывод и ограничение |
|---|---|---|
| 12 параллельных запросов с одинаковым ключом | Обнаружены две разные реплики; все параллельные повторы дали один уникальный ID сообщения. | Подтверждена конкурентная идемпотентность между наблюдавшимися репликами в этом сценарии. |
| Тот же ключ с изменённым телом | HTTP 409. | Конфликт при повторном использовании ключа с другим телом подтверждён. |
| Отсутствующий или некорректный ключ | HTTP 400 в обоих случаях. | Валидация ключа подтверждена для этих случаев. |
| Перезапуск с проверкой сохранности | Подтверждённые данные и существующая сессия сохранились. | Тест завершился PASS; при этом вывод просит дополнительное операторское подтверждение области действия hook. |
| Остановка одной API-реплики | 73 успешные записи, 1 неудачная попытка, первая успешная запись после восстановления через 3,223 с; данные и сессия сохранены. | Failover-сценарий завершился PASS, но переход не был полностью безошибочным. Предоставленный результат не доказывает отдельную проверку каждой реплики. |
| Rolling restart без параллельной нагрузки | Скрипт завершился с двумя здоровыми API-репликами. | Завершение скрипта и конечное состояние подтверждены; это само по себе не означает нулевых ошибок во время замены. |
| Rolling restart под нагрузкой | 1839 успешных запросов, 9 ошибок за 30,128 с. | Нагрузка продолжалась, но были ошибки. Их тип и временное распределение в предоставленном JSON не указаны. |
## Ограничения и следующие шаги
- Реализована репликация процесса API на одном Docker-host. Потеря хоста, единственного HAProxy, PostgreSQL или Redis не переживается; автоматическая HA для этих компонентов отсутствует.
- HAProxy health checks и Docker health checks имеют ограниченную периодичность; краткие ошибки во время обнаружения отказа возможны и должны измеряться.
- Идемпотентность ограничена текущим API POST сообщений, scope — пользователь + чат/путь + ключ, срок — 24 часа. Ключи старше 24 часов могут быть использованы повторно.
- Redis AOF `appendfsync everysec` не равен синхронной репликации/резервному копированию.
- `scripts/rolling-restart.sh` выполняет поочерёдную замену контейнеров в Compose как упражнение rolling restart; он не является автоматическим blue/green deployment с гарантированным обновлением версии приложения. Проверить поведение в целевой версии Compose и сохранить журнал.
+121
View File
@@ -0,0 +1,121 @@
# Отчёт — лабораторная 3
- Автор, группа: Миронов Алексей, бвт2302
- Целевая оценка: 4; трек 5 не заявлен
- Commit/PR: заполнить после публикации
- Использованные источники, библиотеки и помощь ИИ: исходный репозиторий лабораторной 3 и его `COURSE.md`, `README.md`, `contracts/README.md`, `contracts/openapi.json`, `tests/`; перенесённая собственная реализация лабораторной 2; FastAPI, Pydantic, psycopg/psycopg-pool, PostgreSQL, Redis, Argon2, HAProxy, Docker Compose; использовалась помощь ИИ.
## Запуск из чистого clone
Требуются Docker Engine с Compose v2 и GNU Make. Команды выполняются из корня репозитория. Стенд предназначен только для локальных синтетических данных.
1. Создать `.env` и задать уникальный локальный пароль PostgreSQL:
```bash
cp .env.example .env
```
2. Проверить структуру и конфигурацию:
```bash
make check
pip install -r requirements-dev.txt
make validate
docker compose --env-file .env config --quiet
```
3. Собрать образы и запустить две API-реплики за HAProxy:
```bash
docker compose --env-file .env up -d --build --scale api=2
```
`migrate` запускается однократно после готовности PostgreSQL и до API.
Проверить `docker compose --env-file .env ps` и `curl -i http://localhost:8080/health/ready`.
4. Проверить контракт и общую идемпотентность:
```bash
make test
python tests/grade4_checks.py
```
5. Проверить сохранность состояния и отказ реплик (только на тестовом стенде):
```bash
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
```
Failover-тест оставляет одну реплику остановленной. Восстановить желаемые две реплики: `docker compose --env-file .env up -d --scale api=2 api`. Проверить отказ для каждой реплики отдельно, каждый раз восстанавливая предыдущую.
6. Нагрузка и поочерёдная замена:
```bash
make load
# В отдельном терминале можно запустить `bash scripts/rolling-restart.sh`
(проверка того, что апи-реплики могут перезапускаться по отдельности без изменения, не останавливая всё приложение. Это проверка отказоустойчивости, балансировщик должен перенаправлять запросы на доступную реплику, пока другая перезапускается)
```
Сохранить фактические параметры и JSON-нагрузку в `evidence/`. Команды ожидания готовности и остановки: `docker compose --env-file .env down` (volumes сохраняются); для намеренного удаления учебных данных использовать `docker compose --env-file .env down -v` только после явного решения удалить БД и Redis.
## Архитектура и решения
Клиент → HAProxy → две и более взаимозаменяемые FastAPI-реплики → общая PostgreSQL и общий Redis. В Compose наружу опубликован только HAProxy на `127.0.0.1:8080`; API-реплики доступны лишь во внутренней сети. HAProxy опрашивает `/health/ready`, исключает backend после неуспешных проверок и повторно включает после восстановления. Период проверки — 1 с; исключение после двух ошибок ожидается примерно за 2 с плюс timeout/расписание проверок, фактическое время необходимо измерить.
- **Перенос из lab2:** `src/main.py`, базовая SQL-схема пользователей/чатов/участников/сообщений, Redis-сессии, Argon2, пагинация и формат ошибок перенесены. Также перенесены зависимости, `examples/requests.http`, `.gitignore` и `scripts/restart.sh`. В `REPORT1.md` явно фиксируется этот перенос.
- **Изменения lab3:** добавлен `X-Instance-Id` (hostname контейнера, стабильный в пределах его жизни), обязательный `Idempotency-Key` при POST сообщения и таблица `idempotency_records`. Тело запроса нормализуется перед SHA-256; транзакционная advisory lock сериализует одинаковый ключ на всех репликах; запись сообщения и сохранённого ответа выполняется в одной транзакции PostgreSQL. Идентичный повтор в течение 24 часов возвращает исходный `201` и то же сообщение; другой body при том же ключе получает `409`.
- **Миграции:** `scripts/migrate.py` — отдельный одноразовый Compose-сервис, применяющий миграции в порядке имени и записывающий версии в `schema_migrations`. API-реплики не пытаются одновременно менять схему при старте.
- **Сессии:** остаются в Redis, который использует AOF и именованный volume; PostgreSQL — источник истины для бизнес-данных и идемпотентности.
- **Health/shutdown:** `/health/live` проверяет процесс, `/health/ready` проверяет PostgreSQL и Redis. Uvicorn получает SIGTERM, graceful timeout — 10 с, Compose `stop_grace_period` — 15 с.
- **Ресурсы:** Compose задаёт CPU/RAM limits для API, PostgreSQL, Redis и HAProxy. Это ограничения на одном Docker-host, не гарантия доступности при потере хоста.
- **Секреты:** `.env` игнорируется Git и не копируется в образ.
## Доказательства критериев
Результаты ниже перенесены из предоставленного `evidence.txt`. Этот файл является единственным источником доказательств для таблицы; результаты, отсутствующие в нём, обозначены как неподтверждённые. `make check` и `make validate` подтверждают статические проверки, но сами по себе не означают, что приложение было запущено и проверено.
| Критерий | Команда/сценарий | Фактический результат | Источник |
|---|---|---|---|
| Структура проекта и синтаксис | `make check` | **PASS:** проверка офлайн-структуры, локальных ссылок и синтаксиса Python. В выводе отдельно указано, что приложение этим тестом не проверялось. | `evidence.txt` |
| OpenAPI и JSON Schema | `make validate` | **PASS:** полная валидация OpenAPI 3.1 и JSON Schema. В выводе отдельно указано, что приложение этим тестом не проверялось. | `evidence.txt` |
| Конфигурация Docker Compose | `docker compose --env-file .env config --quiet` | Команда завершилась без диагностического вывода. Отдельный код завершения в предоставленном фрагменте не зафиксирован. | `evidence.txt` |
| Сквозной публичный API | `make test` | **PASS:** `lab3 public API scenario`. | `evidence.txt` |
| Две разные API-реплики и конкурентная идемпотентность | `python3 tests/grade4_checks.py` | **PASS:** наблюдались две разные реплики (`21d7ab63f9dc`, `3c995d3af7ef`); 12 параллельных запросов дали один уникальный ID сообщения; изменённое тело с тем же ключом вернуло HTTP 409; отсутствующий и некорректный ключи вернули HTTP 400. | `evidence.txt` |
| Сохранность данных и сессии после перезапуска | `make test-persistence ACTION_SCRIPT=./scripts/restart.sh` | **PASS:** подтверждённые данные и существующая сессия сохранены. Вывод содержит предупреждение: `Hook scope needs operator evidence`; область действия hook требует отдельного подтверждения оператором. | `evidence.txt` |
| Failover одной API-реплики | `make test-failover ACTION_SCRIPT=./scripts/stop-one.sh` | **PASS:** до отказа наблюдались 2 экземпляра; зафиксировано 73 успешные записи, 1 неудачная попытка и 3,223 секунды до первой успешной записи после восстановления. Подтверждена сохранность данных и сессии. В предоставленном результате не указано, что проверка отдельно повторялась для каждой реплики. | `evidence.txt` |
| Нагрузка без перезапуска | `make load` | **PASS:** 30,088 с; concurrency=4; 1528 успешных запросов, 0 неудачных; error ratio 0; 50,785 успешного запроса/с; p50=64,545 мс, p95=192,316 мс, p99=258,186 мс. Процентили рассчитаны только по успешным запросам. | `evidence.txt` |
| Rolling restart | `bash scripts/rolling-restart.sh` | **PASS:** скрипт завершился сообщением `rolling restart completed with 2 healthy API replicas`. | `evidence.txt` |
| Нагрузка во время rolling restart | `make load`, выполнявшийся параллельно с rolling restart | **Выполнено, но не без ошибок:** 30,128 с; concurrency=4; 1839 успешных запросов и 9 неудачных; error ratio=0,00487 (около 0,487%); 61,039 успешного запроса/с; p50=33,306 мс, p95=97,359 мс, p99=163,583 мс. Типы этих 9 ошибок в приведённом JSON не указаны. | `evidence.txt` |
| TTL сессии | Проверка с временным `SESSION_TTL_SECONDS=3` | Результат в предоставленном `evidence.txt` отсутствует; не подтверждено. | Нет подтверждения в `evidence.txt` |
| Отказ Redis / PostgreSQL | Проверки отказа хранилищ | Результаты в предоставленном `evidence.txt` отсутствуют; не подтверждено. | Нет подтверждения в `evidence.txt` |
| CPU/RAM limits и доступность внутренних портов | Проверки конфигурации/контейнеров | Достаточных результатов в предоставленном `evidence.txt` нет; не подтверждено. | Нет подтверждения в `evidence.txt` |
## Эксперименты и отказы
В качестве доказательств используются только результаты из `evidence.txt`. Метрики нагрузки получены закрытым циклом POST-запросов к сообщениям, с concurrency=4, длительностью около 30 секунд и без автоматических повторов. В выводе теста отдельно отмечено, что процентили задержки учитывают только успешные запросы, а closed-loop профиль подвержен coordinated omission и накладным расходам клиента. Поэтому значения характеризуют именно этот тестовый профиль и не являются универсальной оценкой пропускной способности сервиса.
### Сводка нагрузочных прогонов
| Сценарий | Длительность | Успешные | Ошибки | Error ratio | Успешных запросов/с | p50 | p95 | p99 |
|---|---:|---:|---:|---:|---:|---:|---:|---:|
| Обычная нагрузка | 30,088 с | 1528 | 0 | 0% | 50,785 | 64,545 мс | 192,316 мс | 258,186 мс |
| Нагрузка во время rolling restart | 30,128 с | 1839 | 9 | 0,487% | 61,039 | 33,306 мс | 97,359 мс | 163,583 мс |
Успешные RPS и задержки различаются между двумя прогонами; на основании только этих двух запусков нельзя заключать, что rolling restart сам по себе повышает производительность. Во время параллельного прогона было 9 ошибок, поэтому результат не подтверждает полностью безошибочную доступность при замене реплик. Предоставленный JSON не содержит классификации ошибок, поэтому их HTTP-коды и причины здесь не приписываются.
### Проверки идемпотентности и отказоустойчивости
| Воздействие | Наблюдение из `evidence.txt` | Вывод и ограничение |
|---|---|---|
| 12 параллельных запросов с одинаковым ключом | Обнаружены две разные реплики; все параллельные повторы дали один уникальный ID сообщения. | Подтверждена конкурентная идемпотентность между наблюдавшимися репликами в этом сценарии. |
| Тот же ключ с изменённым телом | HTTP 409. | Конфликт при повторном использовании ключа с другим телом подтверждён. |
| Отсутствующий или некорректный ключ | HTTP 400 в обоих случаях. | Валидация ключа подтверждена для этих случаев. |
| Перезапуск с проверкой сохранности | Подтверждённые данные и существующая сессия сохранились. | Тест завершился PASS; при этом вывод просит дополнительное операторское подтверждение области действия hook. |
| Остановка одной API-реплики | 73 успешные записи, 1 неудачная попытка, первая успешная запись после восстановления через 3,223 с; данные и сессия сохранены. | Failover-сценарий завершился PASS, но переход не был полностью безошибочным. Предоставленный результат не доказывает отдельную проверку каждой реплики. |
| Rolling restart без параллельной нагрузки | Скрипт завершился с двумя здоровыми API-репликами. | Завершение скрипта и конечное состояние подтверждены; это само по себе не означает нулевых ошибок во время замены. |
| Rolling restart под нагрузкой | 1839 успешных запросов, 9 ошибок за 30,128 с. | Нагрузка продолжалась, но были ошибки. Их тип и временное распределение в предоставленном JSON не указаны. |
### Что не подтверждено предоставленным журналом
- Отдельный failover-тест для каждой из двух реплик.
- Проверка TTL сессии.
- Отказы Redis и PostgreSQL.
- Фактические значения CPU/RAM во время нагрузки и проверка лимитов контейнеров.
- Типы и причины 9 ошибок во время rolling restart.
- Дополнительные подробности операторского подтверждения для persistence hook.
## Ограничения и следующие шаги
- Реализована репликация процесса API на одном Docker-host. Потеря хоста, единственного HAProxy, PostgreSQL или Redis не переживается; автоматическая HA для этих компонентов отсутствует.
- HAProxy health checks и Docker health checks имеют ограниченную периодичность; краткие ошибки во время обнаружения отказа возможны и должны измеряться.
- Идемпотентность ограничена текущим API POST сообщений, scope — пользователь + чат/путь + ключ, срок — 24 часа. Ключи старше 24 часов могут быть использованы повторно.
- Redis AOF `appendfsync everysec` не равен синхронной репликации/резервному копированию.
- `scripts/rolling-restart.sh` выполняет поочерёдную замену контейнеров в Compose как упражнение rolling restart; он не является автоматическим blue/green deployment с гарантированным обновлением версии приложения. Проверить поведение в целевой версии Compose и сохранить журнал.
+112
View File
@@ -0,0 +1,112 @@
name: mtusi-lab3
services:
postgres:
image: postgres:17.6-alpine
environment:
POSTGRES_DB: ${POSTGRES_DB:-messenger}
POSTGRES_USER: ${POSTGRES_USER:-messenger}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
volumes:
- postgres_data:/var/lib/postgresql/data
networks: [backend]
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 5s
timeout: 3s
retries: 20
cpus: 1.0
mem_limit: 768m
restart: unless-stopped
redis:
image: redis:7.4.2-alpine
command: ["redis-server", "--appendonly", "yes", "--appendfsync", "everysec"]
volumes:
- redis_data:/data
networks: [backend]
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 3s
retries: 20
cpus: 0.25
mem_limit: 256m
restart: unless-stopped
migrate:
build: .
image: mtusi-lab3-api:1.0.0
command: ["python", "scripts/migrate.py"]
environment:
PGHOST: postgres
PGPORT: "5432"
PGDATABASE: ${POSTGRES_DB:-messenger}
PGUSER: ${POSTGRES_USER:-messenger}
PGPASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
networks: [backend]
depends_on:
postgres:
condition: service_healthy
restart: "no"
cpus: 0.5
mem_limit: 384m
api:
build: .
image: mtusi-lab3-api:1.0.0
environment:
APP_HOST: 0.0.0.0
APP_PORT: "8080"
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
DB_POOL_MIN_SIZE: ${DB_POOL_MIN_SIZE:-1}
DB_POOL_MAX_SIZE: ${DB_POOL_MAX_SIZE:-10}
DB_POOL_TIMEOUT_SECONDS: ${DB_POOL_TIMEOUT_SECONDS:-5}
PGHOST: postgres
PGPORT: "5432"
PGDATABASE: ${POSTGRES_DB:-messenger}
PGUSER: ${POSTGRES_USER:-messenger}
PGPASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
REDIS_URL: redis://redis:6379/0
expose: ["8080"]
networks: [backend]
depends_on:
migrate:
condition: service_completed_successfully
redis:
condition: service_healthy
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)"]
interval: 3s
timeout: 3s
retries: 3
start_period: 5s
stop_grace_period: 15s
cpus: 1.0
mem_limit: 512m
restart: unless-stopped
load_balancer:
image: haproxy:3.2.5-alpine
ports:
- "127.0.0.1:${APP_PORT:-8080}:8080"
volumes:
- ./infra/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
networks: [backend]
depends_on:
api:
condition: service_healthy
healthcheck:
test: ["CMD", "haproxy", "-c", "-f", "/usr/local/etc/haproxy/haproxy.cfg"]
interval: 10s
timeout: 3s
retries: 3
cpus: 0.5
mem_limit: 128m
restart: unless-stopped
networks:
backend:
driver: bridge
volumes:
postgres_data:
redis_data:
+131
View File
@@ -0,0 +1,131 @@
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$ make check
python3 scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$ make validate
python3 scripts/validate_openapi.py
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$ docker compose --env-file .env config --quiet
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$ docker compose --env-file .env up --build --scale api=2
^Ccanceled
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$ docker compose --env-file .env up --build --scale api=2
[+] Running 7/7
✔ load_balancer Pulled 26.4s
✔ 4f4fb700ef54 Already exists 0.1s
✔ 9824c27679d3 Download complete 11.0s
✔ 659a606929e4 Download complete 5.8s
✔ 88a6cca0d216 Download complete 7.5s
✔ e7c528653130 Download complete 6.0s
✔ 344cf3eba5e5 Download complete 13.7s
[+] Building 105.8s (24/24) FINISHED docker:default
=> [migrate internal] load build definition from Dockerfile 0.4s
=> => transferring dockerfile: 567B 0.3s
=> [api internal] load metadata for docker.io/library/python:3.12.11-slim-bookworm 42.2s
=> [migrate internal] load .dockerignore 0.1s
=> => transferring context: 216B
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$ make test
python3 tests/smoke.py --base-url "http://localhost:8080"
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$ python3 tests/grade4_checks.py
{"distinct_instances": ["21d7ab63f9dc", "3c995d3af7ef"], "parallel_requests": 12, "distinct_message_ids": 1, "changed_body_status": 409, "missing_key_status": 400, "invalid_key_status": 400}
PASS: concurrent cross-replica idempotency, key validation, and instance visibility
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$ make test-persistence ACTION_SCRIPT=./scripts/restart.sh
python3 tests/resilience.py --mode persistence --action-script "./scripts/restart.sh" --base-url "http://localhost:8080"
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$ make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
python3 tests/resilience.py --mode failover --action-script "./scripts/stop-one.sh" --base-url "http://localhost:8080"
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 73, "failed_attempts": 1, "first_recovery_seconds": 3.223}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$
(нагрузочная проверка сама по себе, без перезапусков контейнеров)
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$ make load
python3 tests/load.py --base-url "http://localhost:8080"
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 30,
"elapsed_seconds": 30.088,
"concurrency": 4,
"successful_requests": 1528,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 50.785,
"successful_latency_ms": {
"p50": 64.545,
"p95": 192.316,
"p99": 258.186
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$ bash scripts/rolling-restart.sh
[+] Running 6/6
✔ Container mtusi-lab3-redis-1 Healthy 1.8s
✔ Container mtusi-lab3-postgres-1 Healthy 0.9s
✔ Container mtusi-lab3-migrate-1 Exited 3.8s
✔ Container mtusi-lab3-api-3 Running 0.0s
✔ Container mtusi-lab3-api-4 Running 0.0s
✔ Container mtusi-lab3-api-5 Started 4.1s
[+] Running 6/6
✔ Container mtusi-lab3-redis-1 Healthy 2.1s
✔ Container mtusi-lab3-postgres-1 Healthy 1.3s
✔ Container mtusi-lab3-migrate-1 Exited 5.3s
✔ Container mtusi-lab3-api-4 Running 0.0s
✔ Container mtusi-lab3-api-5 Running 0.0s
✔ Container mtusi-lab3-api-6 Started 6.0s
[+] Running 6/6
✔ Container mtusi-lab3-redis-1 Healthy 2.1s
✔ Container mtusi-lab3-postgres-1 Healthy 1.2s
✔ Container mtusi-lab3-migrate-1 Exited 4.7s
✔ Container mtusi-lab3-api-5 Running 0.0s
✔ Container mtusi-lab3-api-6 Running 0.0s
✔ Container mtusi-lab3-api-7 Started 5.3s
[+] Running 6/6
✔ Container mtusi-lab3-redis-1 Healthy 2.4s
✔ Container mtusi-lab3-postgres-1 Healthy 1.4s
✔ Container mtusi-lab3-migrate-1 Exited 4.3s
✔ Container mtusi-lab3-api-5 Running 0.0s
✔ Container mtusi-lab3-api-6 Running 0.0s
✔ Container mtusi-lab3-api-7 Removed 0.6s
PASS: rolling restart completed with 2 healthy API replicas
(нагрузочное тестирование во время ролинг рестарт проверки)
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$ make load
python3 tests/load.py --base-url "http://localhost:8080"
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 30,
"elapsed_seconds": 30.128,
"concurrency": 4,
"successful_requests": 1839,
"failed_requests": 9,
"error_ratio": 0.00487,
"successful_rps": 61.039,
"successful_latency_ms": {
"p50": 33.306,
"p95": 97.359,
"p99": 163.583
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
thereal_alyoname@DESKTOP-8Q26HPT:/mnt/c/Users/User/Desktop/MTUCI/4_course/highload_apps/lab3/mtusi2026lab3-fork$
+32
View File
@@ -0,0 +1,32 @@
global
log stdout format raw local0
maxconn 1024
defaults
log global
mode http
option httplog
option http-keep-alive
timeout connect 2s
timeout client 30s
timeout server 30s
timeout check 2s
resolvers docker
nameserver docker-dns 127.0.0.11:53
resolve_retries 3
timeout resolve 1s
timeout retry 1s
hold valid 2s
hold obsolete 2s
frontend public_http
bind :8080
default_backend api_replicas
backend api_replicas
balance roundrobin
option httpchk GET /health/ready
http-check expect status 200
default-server inter 1s fall 2 rise 1
server-template api 10 api:8080 check resolvers docker init-addr libc,none
+32
View File
@@ -0,0 +1,32 @@
CREATE TABLE IF NOT EXISTS users (
id UUID PRIMARY KEY,
username VARCHAR(32) NOT NULL UNIQUE,
display_name VARCHAR(100) NOT NULL,
password_hash TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
CONSTRAINT users_username_format CHECK (username ~ '^[a-z0-9_]{3,32}$'),
CONSTRAINT users_display_name_nonblank CHECK (length(btrim(display_name)) > 0)
);
CREATE TABLE IF NOT EXISTS chats (
id UUID PRIMARY KEY,
title VARCHAR(100) NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
CONSTRAINT chats_title_nonblank CHECK (length(btrim(title)) > 0)
);
CREATE TABLE IF NOT EXISTS chat_members (
chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
position INTEGER NOT NULL DEFAULT 0,
PRIMARY KEY (chat_id, user_id)
);
ALTER TABLE chat_members ADD COLUMN IF NOT EXISTS position INTEGER NOT NULL DEFAULT 0;
CREATE INDEX IF NOT EXISTS chat_members_user_chat_idx ON chat_members(user_id, chat_id);
CREATE TABLE IF NOT EXISTS messages (
id UUID PRIMARY KEY,
chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
sender_id UUID NOT NULL REFERENCES users(id),
text VARCHAR(4000) NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
CONSTRAINT messages_text_nonblank CHECK (length(btrim(text)) > 0)
);
CREATE INDEX IF NOT EXISTS messages_chat_created_id_idx ON messages(chat_id, created_at, id);
+11
View File
@@ -0,0 +1,11 @@
CREATE TABLE IF NOT EXISTS idempotency_records (
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
idempotency_key VARCHAR(128) NOT NULL,
request_hash CHAR(64) NOT NULL,
response_body JSONB NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (user_id, chat_id, idempotency_key),
CONSTRAINT idempotency_key_format CHECK (idempotency_key ~ '^[A-Za-z0-9._:-]{1,128}$')
);
CREATE INDEX IF NOT EXISTS idempotency_records_created_at_idx ON idempotency_records(created_at);
+5
View File
@@ -0,0 +1,5 @@
fastapi==0.116.1
uvicorn[standard]==0.35.0
psycopg[pool,binary]==3.2.9
argon2-cffi==25.1.0
redis==6.4.0
+37
View File
@@ -0,0 +1,37 @@
#!/usr/bin/env python3
"""Apply SQL migrations once, before any API replica is started."""
from pathlib import Path
import os
import time
import psycopg
ROOT = Path(__file__).resolve().parents[1]
CONNINFO = os.getenv("DATABASE_URL", "")
def main():
last_error = None
for _ in range(30):
try:
with psycopg.connect(CONNINFO, connect_timeout=3) as conn:
conn.execute("CREATE TABLE IF NOT EXISTS schema_migrations (version TEXT PRIMARY KEY, applied_at TIMESTAMPTZ NOT NULL DEFAULT now())")
conn.commit()
for path in sorted((ROOT / "migrations").glob("*.sql")):
version = path.name
if conn.execute("SELECT 1 FROM schema_migrations WHERE version=%s", (version,)).fetchone():
continue
sql = path.read_text(encoding="utf-8")
with conn.transaction():
for statement in sql.split(";"):
if statement.strip():
conn.execute(statement)
conn.execute("INSERT INTO schema_migrations(version) VALUES (%s)", (version,))
print(f"APPLIED {version}", flush=True)
print("PASS: migrations complete", flush=True)
return
except Exception as exc:
last_error = exc
time.sleep(1)
raise SystemExit(f"Migration failed after retries: {type(last_error).__name__}")
if __name__ == "__main__":
main()
+5
View File
@@ -0,0 +1,5 @@
#!/bin/sh
set -eu
# Restart state stores first, then every API replica; preserve named volumes.
docker compose restart postgres redis
docker compose restart api
+68
View File
@@ -0,0 +1,68 @@
#!/bin/sh
set -eu
# Safely replace API replicas one at a time.
# Temporarily scale to 3 so there is no need to stop a replica
# before its replacement becomes healthy.
service="api"
target=2
temporary=3
healthy_count() {
count=0
for id in $(docker compose ps -q "$service"); do
status=$(docker inspect --format '{{.State.Health.Status}}' "$id" 2>/dev/null || echo starting)
[ "$status" = healthy ] && count=$((count + 1))
done
echo "$count"
}
wait_for_healthy() {
tries=0
while [ "$tries" -lt 60 ]; do
healthy=$(healthy_count)
if [ "$healthy" -ge "$1" ]; then
return 0
fi
tries=$((tries + 1))
sleep 1
done
echo "Timed out waiting for $1 healthy API replicas" >&2
return 1
}
docker compose up -d --scale api="$temporary" api
wait_for_healthy "$temporary"
# Replace two original replicas. Each iteration starts with 3 healthy
# replicas, stops one, then recreates it to restore the count to 3.
for iteration in 1 2; do
old_id=""
for id in $(docker compose ps -q "$service"); do
status=$(docker inspect --format '{{.State.Health.Status}}' "$id" 2>/dev/null || echo starting)
if [ "$status" = healthy ]; then
old_id="$id"
break
fi
done
[ -n "$old_id" ] || {
echo "No healthy API replica available to replace" >&2
exit 1
}
docker stop --time 10 "$old_id" >/dev/null
docker rm "$old_id" >/dev/null
docker compose up -d --scale api="$temporary" api
wait_for_healthy "$target"
# Wait until the third healthy replica is available before next iteration.
wait_for_healthy "$temporary"
done
docker compose up -d --scale api="$target" api
wait_for_healthy "$target"
echo "PASS: rolling restart completed with $target healthy API replicas"
+17
View File
@@ -0,0 +1,17 @@
#!/bin/sh
set -eu
: "${TARGET_INSTANCE_ID:?TARGET_INSTANCE_ID must be supplied by tests/resilience.py}"
found=""
for id in $(docker compose ps -q api); do
host=$(docker inspect --format '{{.Config.Hostname}}' "$id")
if [ "$host" = "$TARGET_INSTANCE_ID" ]; then
found="$id"
break
fi
done
if [ -z "$found" ]; then
echo "No running API container matches TARGET_INSTANCE_ID" >&2
exit 1
fi
# Stop exactly one API replica and intentionally leave it stopped for the failover check.
docker stop --time 10 "$found" >/dev/null
+1
View File
@@ -0,0 +1 @@
"""Lab 3 FastAPI application package."""
+483
View File
@@ -0,0 +1,483 @@
"""Lab 3 REST API: FastAPI + PostgreSQL persistence + opaque Bearer sessions."""
from __future__ import annotations
import base64
import hashlib
import json
import logging
import os
import re
import secrets
import socket
import uuid
from datetime import datetime, timedelta, timezone
from pathlib import Path
from typing import Any
import psycopg
from psycopg_pool import ConnectionPool, PoolTimeout
import redis
from redis.exceptions import RedisError
from argon2 import PasswordHasher
from argon2.exceptions import InvalidHashError, VerificationError, VerifyMismatchError
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse, Response
from pydantic import BaseModel, ConfigDict, Field, ValidationError
from starlette.exceptions import HTTPException as StarletteHTTPException
logging.basicConfig(level=os.getenv("LOG_LEVEL", "INFO"))
log = logging.getLogger("messenger")
DATABASE_URL = os.getenv("DATABASE_URL", "")
INSTANCE_ID = os.getenv("INSTANCE_ID") or socket.gethostname()
IDEMPOTENCY_KEY_RE = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
REDIS_URL = os.getenv("REDIS_URL", "redis://localhost:6379/0")
SESSION_TTL_SECONDS = int(os.getenv("SESSION_TTL_SECONDS", "3600"))
if SESSION_TTL_SECONDS < 1:
raise RuntimeError("SESSION_TTL_SECONDS must be positive")
# Redis uses its connection pool; session keys contain only a hash of the opaque token.
session_store = redis.Redis.from_url(REDIS_URL, decode_responses=True, socket_connect_timeout=3, socket_timeout=3, health_check_interval=30)
DB_POOL_MIN_SIZE = int(os.getenv("DB_POOL_MIN_SIZE", "1"))
DB_POOL_MAX_SIZE = int(os.getenv("DB_POOL_MAX_SIZE", "10"))
DB_POOL_TIMEOUT_SECONDS = float(os.getenv("DB_POOL_TIMEOUT_SECONDS", "5"))
if DB_POOL_MIN_SIZE < 1 or DB_POOL_MAX_SIZE < DB_POOL_MIN_SIZE:
raise RuntimeError("Invalid PostgreSQL pool size configuration")
# Every pooled connection gets bounded connect/query/idle-transaction timeouts.
db_pool = ConnectionPool(
conninfo=DATABASE_URL,
min_size=DB_POOL_MIN_SIZE,
max_size=DB_POOL_MAX_SIZE,
timeout=DB_POOL_TIMEOUT_SECONDS,
kwargs={
"connect_timeout": 5,
"options": "-c statement_timeout=5000 -c idle_in_transaction_session_timeout=10000",
},
open=False,
name="messenger-postgres",
)
USERNAME_RE = re.compile(r"^[a-z0-9_]{3,32}$")
PASSWORDS = PasswordHasher()
class ApiError(Exception):
def __init__(self, status: int, code: str, message: str, headers: dict[str, str] | None = None):
self.status, self.code, self.message, self.headers = status, code, message, headers or {}
def fail(status: int, code: str, message: str, headers: dict[str, str] | None = None):
raise ApiError(status, code, message, headers)
class StrictModel(BaseModel):
model_config = ConfigDict(extra="forbid", strict=True)
class RegisterBody(StrictModel):
username: str
display_name: str
password: str
class ChatBody(StrictModel):
title: str
member_ids: list[str] = Field(min_length=1, max_length=100)
class MessageBody(StrictModel):
text: str
app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
@app.middleware("http")
async def request_id_middleware(request: Request, call_next):
request.state.request_id = uuid.uuid4().hex
try:
response = await call_next(request)
except Exception:
log.exception("Unhandled API exception request_id=%s", request.state.request_id)
response = JSONResponse(status_code=500, content={"error": {"code": "internal_error", "message": "Internal server error", "request_id": request.state.request_id}})
response.headers["X-Request-Id"] = request.state.request_id
response.headers["X-Instance-Id"] = INSTANCE_ID
return response
def error_response(status: int, code: str, message: str, request_id: str, headers: dict[str, str] | None = None):
return JSONResponse(status_code=status, content={"error": {"code": code, "message": message, "request_id": request_id}}, headers=headers or {})
@app.exception_handler(ApiError)
async def api_error_handler(request: Request, exc: ApiError):
return error_response(exc.status, exc.code, exc.message, request.state.request_id, exc.headers)
@app.exception_handler(PoolTimeout)
async def database_pool_timeout_handler(request: Request, exc: PoolTimeout):
log.warning("Database connection pool timed out request_id=%s", request.state.request_id)
return error_response(503, "unavailable", "Required storage is unavailable", request.state.request_id)
@app.exception_handler(psycopg.Error)
async def database_error_handler(request: Request, exc: psycopg.Error):
log.warning("Database operation failed request_id=%s", request.state.request_id)
return error_response(503, "unavailable", "Required storage is unavailable", request.state.request_id)
@app.exception_handler(RedisError)
async def redis_error_handler(request: Request, exc: RedisError):
log.warning("Session store operation failed request_id=%s", request.state.request_id)
return error_response(503, "unavailable", "Required storage is unavailable", request.state.request_id)
@app.exception_handler(RequestValidationError)
async def validation_error_handler(request: Request, exc: RequestValidationError):
return error_response(400, "invalid_request", "Invalid request", request.state.request_id)
@app.exception_handler(StarletteHTTPException)
async def http_error_handler(request: Request, exc: StarletteHTTPException):
status = exc.status_code
code = "not_found" if status == 404 else "invalid_request"
message = "Object not found" if status == 404 else "Invalid request"
headers = dict(exc.headers or {})
return error_response(status, code, message, request.state.request_id, headers)
def db():
"""Borrow a bounded pooled connection; context exit commits/rolls back and returns it."""
return db_pool.connection(timeout=DB_POOL_TIMEOUT_SECONDS)
@app.on_event("startup")
def startup():
# Migrations run once in the dedicated `migrate` service before API replicas.
import time
db_pool.open(wait=False)
last_error = None
for _ in range(30):
try:
with db() as conn:
conn.execute("SELECT 1")
conn.execute("SELECT 1 FROM idempotency_records LIMIT 0")
session_store.ping()
log.info("PostgreSQL and Redis session store are ready; instance=%s", INSTANCE_ID)
return
except Exception as exc:
last_error = exc
time.sleep(1)
raise RuntimeError("PostgreSQL schema or Redis unavailable during startup") from last_error
@app.on_event("shutdown")
def shutdown():
session_store.close()
db_pool.close()
def now_utc() -> datetime:
return datetime.now(timezone.utc)
def iso(value: datetime) -> str:
return value.astimezone(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z")
def user_dict(row: dict[str, Any]) -> dict[str, Any]:
return {"id": str(row["id"]), "username": row["username"], "display_name": row["display_name"], "created_at": iso(row["created_at"])}
def chat_dict(row: dict[str, Any], member_ids: list[str]) -> dict[str, Any]:
return {"id": str(row["id"]), "title": row["title"], "member_ids": member_ids, "created_at": iso(row["created_at"])}
def message_dict(row: dict[str, Any]) -> dict[str, Any]:
return {"id": str(row["id"]), "chat_id": str(row["chat_id"]), "sender_id": str(row["sender_id"]), "text": row["text"], "created_at": iso(row["created_at"])}
def validate_unicode(value: str, label: str) -> str:
"""Reject unpaired UTF-16 surrogates before sending text to PostgreSQL/KDF."""
try:
value.encode("utf-8")
except UnicodeEncodeError:
fail(400, "invalid_request", "Invalid Unicode in " + label)
return value
def parse_uuid(value: str, label: str = "UUID") -> uuid.UUID:
try:
# Keep the canonical UUID representation used by the Lab 1 API.
if not isinstance(value, str) or len(value) != 36:
raise ValueError("non-canonical UUID")
parsed = uuid.UUID(value)
if str(parsed) != value:
raise ValueError("non-canonical UUID")
return parsed
except (ValueError, TypeError, AttributeError):
fail(400, "invalid_request", "Invalid " + label)
def validate_body_type(request: Request):
content_type = request.headers.get("content-type", "").split(";", 1)[0].strip().lower()
if content_type != "application/json":
fail(415, "unsupported_media_type", "Content-Type must be application/json")
async def parse_body(request: Request, model):
validate_body_type(request)
try:
raw = await request.body()
data = json.loads(raw.decode("utf-8"))
return model.model_validate(data)
except (UnicodeDecodeError, json.JSONDecodeError, ValidationError, TypeError):
fail(400, "invalid_request", "Invalid JSON request body")
def challenge(scheme: str) -> dict[str, str]:
if scheme == "Basic":
return {"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"'}
return {"WWW-Authenticate": 'Bearer realm="messenger"'}
def current_user(request: Request) -> dict[str, Any]:
auth = request.headers.get("authorization", "")
if not auth.startswith("Bearer ") or not auth[7:].strip():
fail(401, "unauthorized", "Valid Bearer session required", challenge("Bearer"))
token_hash = hashlib.sha256(auth[7:].strip().encode("utf-8")).hexdigest()
session_json = session_store.get("session:" + token_hash)
if session_json is None:
fail(401, "unauthorized", "Valid Bearer session required", challenge("Bearer"))
try:
session = json.loads(session_json)
user_id = uuid.UUID(session["user_id"])
expires_at = datetime.fromisoformat(session["expires_at"].replace("Z", "+00:00"))
except (ValueError, KeyError, TypeError, json.JSONDecodeError):
# Corrupt session data is invalidated instead of trusted.
session_store.delete("session:" + token_hash)
fail(401, "unauthorized", "Valid Bearer session required", challenge("Bearer"))
if expires_at <= now_utc():
session_store.delete("session:" + token_hash)
fail(401, "unauthorized", "Valid Bearer session required", challenge("Bearer"))
with db() as conn:
row = conn.execute("SELECT id,username,display_name,created_at FROM users WHERE id=%s", (user_id,)).fetchone()
if row is None:
session_store.delete("session:" + token_hash)
fail(401, "unauthorized", "Valid Bearer session required", challenge("Bearer"))
return {"id": row[0], "username": row[1], "display_name": row[2], "created_at": row[3], "expires_at": expires_at, "user": {"id": str(row[0]), "username": row[1], "display_name": row[2], "created_at": iso(row[3])}, "token_hash": token_hash}
def ensure_member(actor_id: uuid.UUID, chat_id: uuid.UUID):
with db() as conn:
row = conn.execute("SELECT 1 FROM chats c JOIN chat_members m ON m.chat_id=c.id WHERE c.id=%s AND m.user_id=%s", (chat_id, actor_id)).fetchone()
if row is None:
fail(404, "not_found", "Object not found")
def parse_page_args(limit: int | None, cursor: str | None, resource: str):
actual_limit = 50 if limit is None else limit
if isinstance(actual_limit, bool) or actual_limit < 1 or actual_limit > 100:
fail(400, "invalid_request", "limit must be an integer from 1 to 100")
after = None
if cursor is not None:
if not cursor:
fail(400, "invalid_request", "Invalid cursor")
try:
decoded = base64.urlsafe_b64decode(cursor + "=" * (-len(cursor) % 4)).decode("utf-8")
obj = json.loads(decoded)
if obj.get("resource") != resource:
fail(400, "invalid_request", "Cursor belongs to another resource")
after = (datetime.fromisoformat(obj["created_at"].replace("Z", "+00:00")), uuid.UUID(obj["id"]))
except ApiError:
raise
except Exception:
fail(400, "invalid_request", "Invalid cursor")
return actual_limit, after
def make_cursor(resource: str, created_at: datetime, item_id: uuid.UUID) -> str:
raw = json.dumps({"resource": resource, "created_at": iso(created_at), "id": str(item_id)}, separators=(",", ":")).encode()
return base64.urlsafe_b64encode(raw).decode().rstrip("=")
def json_rows(cursor, query: str, params=()):
with db() as conn:
cur = conn.execute(query, params)
names = [d.name for d in cur.description]
return [dict(zip(names, row)) for row in cur.fetchall()]
@app.get("/health/live")
def live():
return {"status": "ok"}
@app.get("/health/ready")
def ready():
try:
with db() as conn:
conn.execute("SELECT 1")
session_store.ping()
return {"status": "ok"}
except (psycopg.Error, PoolTimeout, RedisError):
fail(503, "unavailable", "Required storage is unavailable")
@app.post("/api/v1/users", status_code=201)
async def register(request: Request):
body = await parse_body(request, RegisterBody)
if not USERNAME_RE.fullmatch(body.username):
fail(400, "invalid_request", "Invalid username")
validate_unicode(body.display_name, "display_name")
validate_unicode(body.password, "password")
if not body.display_name.strip() or len(body.display_name) > 100:
fail(400, "invalid_request", "Invalid display_name")
if not 12 <= len(body.password) <= 128:
fail(400, "invalid_request", "Password must contain 12 to 128 Unicode code points")
user_id = uuid.uuid4()
password_hash = PASSWORDS.hash(body.password)
try:
with db() as conn:
row = conn.execute("INSERT INTO users(id,username,display_name,password_hash) VALUES (%s,%s,%s,%s) RETURNING id,username,display_name,created_at", (user_id, body.username, body.display_name, password_hash)).fetchone()
except psycopg.errors.UniqueViolation:
fail(409, "conflict", "Username already exists")
return user_dict(dict(zip(("id", "username", "display_name", "created_at"), row)))
@app.get("/api/v1/users/me")
def me(request: Request):
return current_user(request)["user"]
@app.post("/api/v1/auth/sessions", status_code=201)
async def create_session(request: Request):
if await request.body():
fail(400, "invalid_request", "Session creation does not accept a request body")
auth = request.headers.get("authorization", "")
if not auth[:6].lower() == "basic ":
fail(401, "unauthorized", "Valid Basic credentials required", challenge("Basic"))
try:
decoded = base64.b64decode(auth[6:], validate=True).decode("utf-8")
username, password = decoded.split(":", 1)
except Exception:
fail(401, "unauthorized", "Invalid credentials", challenge("Basic"))
try:
validate_unicode(password, "password")
except ApiError:
fail(401, "unauthorized", "Invalid credentials", challenge("Basic"))
if not password or len(password) < 12 or len(password) > 128:
fail(401, "unauthorized", "Invalid credentials", challenge("Basic"))
with db() as conn:
row = conn.execute("SELECT id,username,display_name,password_hash,created_at FROM users WHERE username=%s", (username,)).fetchone()
if row is None:
fail(401, "unauthorized", "Invalid credentials", challenge("Basic"))
try:
PASSWORDS.verify(row[3], password)
except (VerifyMismatchError, VerificationError, InvalidHashError):
fail(401, "unauthorized", "Invalid credentials", challenge("Basic"))
token = secrets.token_urlsafe(32)
token_hash = hashlib.sha256(token.encode()).hexdigest()
expires_at = now_utc() + timedelta(seconds=SESSION_TTL_SECONDS)
session_json = json.dumps({"user_id": str(row[0]), "expires_at": iso(expires_at)}, separators=(",", ":"))
# Redis TTL enforces expiry; AOF + named volume make active sessions survive stack restarts.
session_store.setex("session:" + token_hash, SESSION_TTL_SECONDS, session_json)
user = user_dict({"id": row[0], "username": row[1], "display_name": row[2], "created_at": row[4]})
return {"token": token, "token_type": "Bearer", "expires_at": iso(expires_at), "user": user}
@app.delete("/api/v1/auth/sessions/current", status_code=204)
def revoke_session(request: Request):
actor = current_user(request)
session_store.delete("session:" + actor["token_hash"])
return Response(status_code=204)
@app.post("/api/v1/chats", status_code=201)
async def create_chat(request: Request):
actor = current_user(request)
body = await parse_body(request, ChatBody)
validate_unicode(body.title, "title")
if not body.title.strip() or len(body.title) > 100:
fail(400, "invalid_request", "Invalid title")
ids = [parse_uuid(value, "member UUID") for value in body.member_ids]
if len(ids) != len(set(ids)) or actor["id"] not in ids:
fail(400, "invalid_request", "Members must be unique and include the caller")
chat_id = uuid.uuid4()
try:
with db() as conn:
existing = conn.execute("SELECT id FROM users WHERE id = ANY(%s)", (ids,)).fetchall()
if len(existing) != len(ids):
fail(400, "invalid_request", "Unknown chat member")
row = conn.execute("INSERT INTO chats(id,title) VALUES (%s,%s) RETURNING id,title,created_at", (chat_id, body.title)).fetchone()
with conn.cursor() as cur:
cur.executemany(
"INSERT INTO chat_members(chat_id,user_id,position) VALUES (%s,%s,%s)",
[(chat_id, uid, position) for position, uid in enumerate(ids)]
)
except psycopg.errors.ForeignKeyViolation:
fail(400, "invalid_request", "Unknown chat member")
return chat_dict({"id": row[0], "title": row[1], "created_at": row[2]}, [str(x) for x in ids])
@app.get("/api/v1/chats")
def list_chats(request: Request, limit: int | None = None, cursor: str | None = None):
actor = current_user(request)
chat_list_resource = "chats:" + str(actor["id"])
actual_limit, after = parse_page_args(limit, cursor, chat_list_resource)
params: list[Any] = [actor["id"]]
where = "m.user_id=%s"
if after:
where += " AND (c.created_at,c.id)>(%s,%s)"
params.extend(after)
params.append(actual_limit + 1)
rows = json_rows(None, f"SELECT c.id,c.title,c.created_at FROM chats c JOIN chat_members m ON m.chat_id=c.id WHERE {where} ORDER BY c.created_at,c.id LIMIT %s", tuple(params))
more = len(rows) > actual_limit
rows = rows[:actual_limit]
items = []
for row in rows:
members = json_rows(None, "SELECT user_id FROM chat_members WHERE chat_id=%s ORDER BY position,user_id", (row["id"],))
items.append(chat_dict(row, [str(m["user_id"]) for m in members]))
next_cursor = make_cursor(chat_list_resource, rows[-1]["created_at"], rows[-1]["id"]) if more and rows else None
return {"items": items, "next_cursor": next_cursor}
@app.get("/api/v1/chats/{chat_id}")
def get_chat(chat_id: str, request: Request):
actor = current_user(request)
parsed = parse_uuid(chat_id, "chat UUID")
ensure_member(actor["id"], parsed)
rows = json_rows(None, "SELECT id,title,created_at FROM chats WHERE id=%s", (parsed,))
members = json_rows(None, "SELECT user_id FROM chat_members WHERE chat_id=%s ORDER BY position,user_id", (parsed,))
return chat_dict(rows[0], [str(m["user_id"]) for m in members])
@app.post("/api/v1/chats/{chat_id}/messages", status_code=201)
async def create_message(chat_id: str, request: Request):
actor = current_user(request)
parsed_chat = parse_uuid(chat_id, "chat UUID")
ensure_member(actor["id"], parsed_chat)
body = await parse_body(request, MessageBody)
validate_unicode(body.text, "text")
if not body.text.strip() or len(body.text) > 4000:
fail(400, "invalid_request", "Message text must contain 1 to 4000 non-whitespace code points")
key = request.headers.get("Idempotency-Key", "")
if not IDEMPOTENCY_KEY_RE.fullmatch(key):
fail(400, "invalid_request", "Idempotency-Key must contain 1 to 128 ASCII letters, digits, '.', '_', ':', or '-'")
# Hash semantic JSON rather than raw bytes, so insignificant JSON formatting does not matter.
canonical_body = json.dumps({"text": body.text}, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
request_hash = hashlib.sha256(canonical_body.encode("utf-8")).hexdigest()
scope = f"{actor['id']}|POST|/api/v1/chats/{parsed_chat}/messages|{key}"
# The advisory transaction lock serializes the same key across every API replica.
# Message and idempotency result are committed atomically in the same PostgreSQL transaction.
with db() as conn:
conn.execute("SELECT pg_advisory_xact_lock(hashtextextended(%s, 0))", (scope,))
existing = conn.execute(
"SELECT request_hash, response_body FROM idempotency_records "
"WHERE user_id=%s AND chat_id=%s AND idempotency_key=%s AND created_at >= now() - interval '24 hours'",
(actor["id"], parsed_chat, key),
).fetchone()
if existing is not None:
if existing[0] != request_hash:
fail(409, "conflict", "Idempotency-Key was already used with a different request body")
return JSONResponse(status_code=201, content=existing[1])
# Keys are guaranteed for 24 hours; expired records may be replaced by a new attempt.
conn.execute(
"DELETE FROM idempotency_records WHERE user_id=%s AND chat_id=%s AND idempotency_key=%s AND created_at < now() - interval '24 hours'",
(actor["id"], parsed_chat, key),
)
row = conn.execute(
"INSERT INTO messages(id,chat_id,sender_id,text) VALUES (%s,%s,%s,%s) "
"RETURNING id,chat_id,sender_id,text,created_at",
(uuid.uuid4(), parsed_chat, actor["id"], body.text),
).fetchone()
result = message_dict(dict(zip(("id", "chat_id", "sender_id", "text", "created_at"), row)))
conn.execute(
"INSERT INTO idempotency_records(user_id,chat_id,idempotency_key,request_hash,response_body) "
"VALUES (%s,%s,%s,%s,%s::jsonb)",
(actor["id"], parsed_chat, key, request_hash, json.dumps(result, ensure_ascii=False)),
)
return result
@app.get("/api/v1/chats/{chat_id}/messages")
def list_messages(chat_id: str, request: Request, limit: int | None = None, cursor: str | None = None):
actor = current_user(request)
parsed_chat = parse_uuid(chat_id, "chat UUID")
ensure_member(actor["id"], parsed_chat)
actual_limit, after = parse_page_args(limit, cursor, "messages:" + str(parsed_chat))
params: list[Any] = [parsed_chat]
where = "chat_id=%s"
if after:
where += " AND (created_at,id)>(%s,%s)"
params.extend(after)
params.append(actual_limit + 1)
rows = json_rows(None, f"SELECT id,chat_id,sender_id,text,created_at FROM messages WHERE {where} ORDER BY created_at,id LIMIT %s", tuple(params))
more = len(rows) > actual_limit
rows = rows[:actual_limit]
items = [message_dict(row) for row in rows]
next_cursor = make_cursor("messages:" + str(parsed_chat), rows[-1]["created_at"], rows[-1]["id"]) if more and rows else None
return {"items": items, "next_cursor": next_cursor}
if __name__ == "__main__":
import uvicorn
uvicorn.run("main:app", host=os.getenv("APP_HOST", "0.0.0.0"), port=int(os.getenv("APP_PORT", "8080")), timeout_graceful_shutdown=5)
+47
View File
@@ -0,0 +1,47 @@
#!/usr/bin/env python3
"""Focused Lab 3 level-4 checks; run only against the local synthetic Compose stack."""
from concurrent.futures import ThreadPoolExecutor
import json, time, uuid
from client import Client, Failure, arguments, check, run
def main():
args = arguments("Concurrent idempotency and replica diversity checks")
c = Client(args.base_url, args.ca_file, timeout=5)
alice, bob, eve, chat = c.bootstrap()
instances = set()
for _ in range(40):
instances.add(c.call('GET', '/api/v1/users/me', actor=alice, schema='User')['headers'].get('X-Instance-Id',''))
instances.discard('')
check(len(instances) >= 2, 'load balancer did not expose at least two distinct API instances')
key = 'parallel-' + uuid.uuid4().hex
body = {'text':'Одна запись при конкурентном повторе'}
def send(_):
return c.call(
'POST',
'/api/v1/chats/' + chat['id'] + '/messages',
expected=201,
actor=alice,
body=body,
headers={'Idempotency-Key': key},
schema='Message'
)
with ThreadPoolExecutor(max_workers=12) as pool:
responses = list(pool.map(send, range(12)))
ids = {r['json']['id'] for r in responses}
check(len(ids) == 1, 'concurrent identical keys produced different message IDs')
check(all(r['status'] == 201 for r in responses), 'identical retry must return HTTP 201')
changed = c.call('POST', '/api/v1/chats/'+chat['id']+'/messages', expected=409, actor=alice,
body={'text':'Другой текст'}, headers={'Idempotency-Key':key})
missing = c.call('POST', '/api/v1/chats/'+chat['id']+'/messages', expected=400, actor=alice,
body={'text':'Без ключа'}, headers={})
invalid = c.call('POST', '/api/v1/chats/'+chat['id']+'/messages', expected=400, actor=alice,
body={'text':'Неверный ключ'}, headers={'Idempotency-Key':'bad key'})
print(json.dumps({'distinct_instances':sorted(instances), 'parallel_requests':len(responses),
'distinct_message_ids':len(ids), 'changed_body_status':changed['status'],
'missing_key_status':missing['status'], 'invalid_key_status':invalid['status']}, ensure_ascii=False))
print('PASS: concurrent cross-replica idempotency, key validation, and instance visibility')
if __name__ == '__main__':
run(main)