This commit is contained in:
2026-10-23 15:36:38 +03:00
parent cd9c3402fa
commit 1d85938fb4
35 changed files with 1262 additions and 70 deletions
+19 -14
View File
@@ -1,18 +1,23 @@
## Лабораторная 3
Автор / группа: TODO
Целевая оценка (3/4/5): TODO
Трек 5, если заявлен: TODO
Автор / группа: Ромашко Владимир, БВТ2301
Целевая оценка: **4**, Compose + nginx. Трек 5 не заявлен.
Что реализовано и что перенесено: TODO
Команды запуска из чистого clone: TODO
Результаты проверок и ссылка на REPORT.md: TODO
Ограничения / известные ошибки: TODO
Источники и использование ИИ: TODO
Реализованы две API-реплики за nginx, общие сессии и идемпотентность сообщений,
отдельные миграции, остановка каждой реплики и поочерёдная замена под нагрузкой.
Основа lab2 перенесена отдельным коммитом; изменены только необходимые для lab3 части.
- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [ ] Контракт и публичные тесты не ослаблены.
- [ ] make check и make test выполнены; приложен реальный вывод.
- [ ] Сценарии отказов/безопасности своего уровня воспроизведены.
- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
Запуск: скопировать `.env.example` в `.env`, задать POSTGRES_PASSWORD,
выполнить `docker compose up -d --build --wait --wait-timeout 120`.
Проверки: `python -X utf8 scripts/verify_lab3.py` и
`docker compose exec -T api python -m unittest discover -s student-tests -v`.
Результаты, ограничения и источники: [REPORT.md](../REPORT.md).
Использован Codex. PostgreSQL, Redis, nginx и host остаются единичными точками отказа.
- [x] Возможности предыдущих работ сохранены с объявленными переходами.
- [x] Контракт и публичные тесты не ослаблены.
- [x] Эквиваленты make check/test выполнены; вывод приложен.
- [x] Отказ каждой реплики и поочерёдная замена воспроизведены.
- [x] Секреты вне Git, tokens в отчёте отсутствуют.
- [x] README задания сохранён, REPORT.md описывает решение.
+177 -23
View File
@@ -1,37 +1,191 @@
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Ромашко Владимир, БВТ2301.
- Целевая оценка: **4**, Docker Compose + nginx.
- Проверка: 23 октября 2026 года.
- Основа lab2 зафиксирована отдельным коммитом `cd9c340`.
- Использован Codex для реализации и проверок. Треки оценки 5 не заявлены.
## Запуск из чистого clone
## Запуск
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Нужны Docker Engine/Desktop с Compose v2 и Python 3.9+ на хосте.
Приложение работает на Python 3.12.8 в контейнере.
## Архитектура и решения
```powershell
Copy-Item .env.example .env
# Задать в .env случайный локальный POSTGRES_PASSWORD.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 120
python -X utf8 scripts/verify_lab3.py
docker compose exec -T api python -m unittest discover -s student-tests -v
```
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
`verify_lab3.py` проверяет контракт, smoke, конкурентные повторы, полный restart,
отказ каждой API и поочерёдную замену под нагрузкой. Скрипт останавливает контейнеры
только этого проекта и восстанавливает реплики; volumes сохраняются. Запускать
без одновременного ручного управления стендом. Результаты пишутся в `evidence/`.
## Доказательства критериев
На Linux: `cp .env.example .env`, задать пароль, затем те же Docker-команды и
`python3 scripts/verify_lab3.py`. Перед тестами:
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
```sh
chmod +x scripts/restart.sh scripts/stop-one.sh
make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# Восстановить реплику после отдельного failover:
docker compose up -d --no-deps --no-recreate api
```
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Windows-варианты отдельных проверок:
## Эксперименты и отказы
```powershell
python -X utf8 scripts/check_contract.py
python -X utf8 tests/smoke.py
python -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.cmd
python -X utf8 tests/resilience.py --mode failover --action-script scripts/stop-one.cmd
docker compose up -d --no-deps --no-recreate api
```
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
На Windows make отсутствует: выполнены те же Python-команды, которые вызывают
цели Makefile. `-X utf8` нужен публичным скриптам для чтения файлов с русским текстом.
Контракт, публичные tests, Makefile и README задания не менялись.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
Остановка с сохранением данных: `docker compose down`.
Намеренное удаление всех учебных данных проекта: `docker compose down -v`.
При проверках volumes не удалялись. Исходный проект lab2 не изменялся.
## Ограничения и следующие шаги
## Архитектура
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Клиент → `127.0.0.1:8080` nginx → один Compose-service `api` с двумя репликами
→ общие PostgreSQL и Redis. У API нет опубликованных портов и `container_name`.
Sticky sessions нет. `X-Instance-Id` — hostname контейнера; его соответствие
реальному процессу проверяется через Docker. В каждом контейнере один Uvicorn worker.
Из lab2 сохранены пользователи, чаты, сообщения, Argon2id, Redis-сессии с TTL,
миграции и кэш страниц истории. PostgreSQL — источник истины данных и ключей
идемпотентности. Redis хранит сессии с абсолютным expiry и AOF `appendfsync always`.
Кэш истории использует версию из PostgreSQL: после записи другая реплика не читает
старую версию страницы. Локального состояния сессий в API нет.
Пароль хранится в игнорируемом `.env`. Он передаётся PostgreSQL, API и migrator.
Nginx не получает пароль. Volumes монтируются только соответствующему хранилищу.
API и хранилища находятся во внутренней сети backend, nginx также подключён к edge.
| Сервис | Образ | CPU | RAM |
| --- | --- | ---: | ---: |
| API, каждая реплика | python:3.12.8-slim-bookworm + requirements.txt | 1 | 512 MiB |
| migrate, одноразовый | тот же образ приложения | 1 | 512 MiB |
| nginx | nginx:1.28.0-alpine | 0,5 | 128 MiB |
| PostgreSQL | postgres:17.4-bookworm | 1 | 512 MiB |
| Redis | redis:7.4.2-bookworm | 0,5 | 256 MiB |
`.env.example` сохранён из lab2. `APP_PORT` меняет внешний порт nginx (тестам тогда
нужен `--base-url`); остальные используемые настройки — БД, TTL и лимиты запросов.
API внутри контейнера слушает 0.0.0.0:8080 независимо от APP_HOST в локальном .env.
В Compose заданы две реплики и образ `mtusi2026lab3-api:local`.
## Идемпотентность
POST сообщения требует ключ `[A-Za-z0-9._:-]{1,128}`. Область ключа:
пользователь + POST messages конкретного чата + ключ. Сначала проверяются сессия
и доступ. `SELECT FOR UPDATE` блокирует строку чата до поиска сохранённого результата.
Записи в один чат выполняются последовательно; разные чаты не блокируют друг друга.
Та же строка уже обновляется для инвалидации кэша, отдельный механизм блокировок не нужен.
Сообщение, увеличение версии истории и запись ключа сохраняются одной транзакцией.
После COMMIT возвращается 201. Повтор возвращает тот же Message и 201, другое тело —
409. Сбой до COMMIT откатывает всё; неопределённый ответ после COMMIT можно повторить.
5xx не сохраняется как результат. Сравнивается значение `text`, а не JSON-байты.
Ключи хранятся бессрочно, что обеспечивает обязательные 24 часа повторов.
Очистка не реализована: таблица растёт, использовать старый ключ для нового тела нельзя.
## Health, DNS и остановка
- `/health/live` проверяет процесс; `/health/ready` — PostgreSQL SELECT 1 и Redis PING.
Обе зависимости критичны для защищённых запросов.
- Docker healthcheck API: каждые 2 с, timeout 2 с, 2 неудачи, стартовый период 5 с.
После стартового периода верхняя оценка отметки unhealthy — 8 с.
Эта отметка сама по себе не управляет nginx.
- Nginx исключает backend пассивно: `max_fails=1`, `fail_timeout=2s`.
Учитываются сетевые ошибки, timeout, 502/503/504. При запросах connect-отказ
обнаруживается за ≤1 с, отсутствие ответа — за ≤6 с. Без трафика пассивная
проверка не имеет предельного времени обнаружения. Ошибки переходного периода допустимы.
- Nginx использует Docker DNS `127.0.0.11`, `valid=2s`, resolver timeout 1 с,
`server api:8080 resolve`. Новые адреса появляются без reload nginx.
- GET может перейти на второй backend: до 2 попыток. Бюджет выбора следующей
попытки — 8 с, это не абсолютный deadline всего запроса. Уже отправленный POST
автоматически не повторяется; клиент повторяет сообщение с прежним ключом.
- PostgreSQL: connect 2 с, pool wait 2 с, statement 3 с, lock 2 с; pool до 10/API.
Redis: connect/read по 1 с. Это таймауты отдельных операций.
- Uvicorn получает SIGTERM как PID 1, прекращает приём соединений и даёт активным
запросам до 5 с. Compose ждёт 10 с, action script — 8 с до SIGKILL.
## Миграции и поочерёдная замена
Отдельный сервис `migrate` применяет SQL перед запуском API. Startup API миграций
не выполняет. Реестр версий и перенесённая из lab2 блокировка миграций позволяют
безопасно повторять запуск. Миграция 003 только добавляет таблицу ключей.
`python -X utf8 scripts/rolling.py` собирает образ, один раз запускает migrator,
затем заменяет API по одной: stop выбранного контейнера, удаление только этого
остановленного контейнера, `compose up --no-recreate --scale api=2`, ожидание health
и 3 с на DNS. Соседняя реплика продолжает работать; volumes не удаляются.
Проверена замена контейнеров текущей версии под нагрузкой. Смешанный переход
lab2→lab3 не поддерживается: lab2 ещё не обеспечивает ключи и X-Instance-Id.
Несовместимые будущие изменения схемы потребуют отдельного порядка обновления.
## Результаты
Среда: Docker Desktop Linux x86_64, Engine 28.5.1, Compose 2.40.0;
Docker VM — 8 CPU и 8 328 015 872 байт RAM. Данные синтетические, токены не сохраняются.
Нагрузка: 2 клиента, каждый пишет сообщение, читает чат, ждёт 20 мс. До воздействия
3 с, весь сценарий минимум 20 с и минимум 5 с после завершения воздействия.
После него сверяется вся история, подтверждения и отсутствие дублей; повторяется
прежний ключ. RPS — успешные HTTP-ответы, latency — только успешные запросы.
Один прогон на воздействие, closed-loop нагрузка: это не предел производительности.
Время восстановления считается от начала action до первого успешного read/write
после его завершения, включая время Docker CLI.
| Проверка | Результат | Доказательство |
| --- | --- | --- |
| Контракт и smoke через nginx | PASS | [check.txt](evidence/check.txt), [final-smoke.txt](evidence/final-smoke.txt) |
| Регрессия lab2, миграции, rollback и гонка разных тел | 15 тестов OK | [unit-tests.txt](evidence/unit-tests.txt) |
| Один ключ через разные API | 24 запроса, concurrency 8, 2 реплики, 1 сообщение | [idempotency.json](evidence/idempotency.json) |
| Restart API, LB, PostgreSQL и Redis | Прежняя сессия, сообщения и результат ключа сохранены | [persistence.txt](evidence/persistence.txt), [restart.txt](evidence/restart.txt), [idempotency-restart.json](evidence/idempotency-restart.json) |
| Публичный failover, два запуска с восстановлением | PASS, по 124 записи, 0 ошибок; 2,204 / 2,233 с | [Первый](evidence/public-failover-1.txt), [второй](evidence/public-failover-2.txt) |
| Отдельно остановлена каждая API | PASS, прежняя сессия, потерь и дублей нет | [failover-1.json](evidence/failover-1.json), [failover-2.json](evidence/failover-2.json) |
| Поочерёдная замена под нагрузкой | Обе исходные API заменены, 0 ошибок, данные сохранены | [rolling-load.json](evidence/rolling-load.json), включая снимки контейнеров |
| Nginx, health, DNS, SIGTERM, лимиты и порты | Nginx config OK; остановленные ID исчезают, новые появляются; обе API healthy, порт только у LB | [nginx-check.txt](evidence/nginx-check.txt), [final-containers.json](evidence/final-containers.json) |
| Отдельные миграции | 001/002/003 применяются повторно без дублирования; чистая схема проверена | [unit-tests.txt](evidence/unit-tests.txt), [compose.yaml](compose.yaml) |
| Воздействие | HTTP/с | Записей/с | Ошибок | p50 / p95 / p99, мс | Первые read / write после stop, с |
| --- | ---: | ---: | ---: | --- | --- |
| Stop 6fc32ef53bc9 | 61.9 | 30.95 | 0 | 18.0 / 52.71 / 71.25 | 2.466 / 2.458 |
| Stop a6ee3d7e3779 | 65.84 | 32.92 | 0 | 16.38 / 48.29 / 70.66 | 2.409 / 2.397 |
| Замена обеих API | 62.91 | 31.45 | 0 | 16.51 / 48.68 / 75.14 | Запросы продолжались всю замену |
Замена заняла 29.127 с, включая ожидание health и DNS.
Это длительность операции, не простой API. Максимальный интервал между успешными
ответами: read 0.216 с, write 0.231 с.
Полная сводка: [grade4-summary.json](evidence/grade4-summary.json).
Сохраняются сводки измерений, ошибки и снимки реальных контейнеров, без тысяч
отдельных сообщений. Доказательство исходного переноса: [baseline-lab2.txt](evidence/baseline-lab2.txt).
## Ограничения и источники
Выдерживается отказ одной API при работающей соседней и общих зависимостях.
Nginx, PostgreSQL, Redis и Docker-host остаются единичными точками отказа.
HTTP предназначен для локального учебного стенда. Создание пользователей/чатов
не имеет гарантии идемпотентного повтора. Уровень 5 и отказ узла не заявлены.
- [Compose services](https://docs.docker.com/reference/compose-file/services/).
- [Nginx upstream](https://nginx.org/en/docs/http/ngx_http_upstream_module.html).
- [Nginx proxy](https://nginx.org/en/docs/http/ngx_http_proxy_module.html).
- [Uvicorn shutdown](https://uvicorn.dev/server-behavior/).
- Контракт и публичные тесты репозитория, собственная реализация lab2.
+68 -21
View File
@@ -1,30 +1,71 @@
x-api: &api
image: mtusi2026lab3-api:local
build: .
dns_opt:
- timeout:1
- attempts:1
environment:
APP_HOST: 0.0.0.0
APP_PORT: 8080
POSTGRES_HOST: postgres
POSTGRES_DB: ${POSTGRES_DB:-messenger}
POSTGRES_USER: ${POSTGRES_USER:-messenger}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
REDIS_URL: redis://redis:6379/0
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
CACHE_TTL_SECONDS: ${CACHE_TTL_SECONDS:-30}
MAX_REQUEST_BYTES: ${MAX_REQUEST_BYTES:-65536}
MAX_INFLIGHT: ${MAX_INFLIGHT:-32}
networks: [backend]
cpus: 1.0
mem_limit: 512m
stop_grace_period: 10s
services:
api:
build: .
dns_opt:
- timeout:1
- attempts:1
ports:
- "127.0.0.1:${APP_PORT:-8080}:8080"
environment:
APP_HOST: 0.0.0.0
APP_PORT: 8080
POSTGRES_HOST: postgres
POSTGRES_DB: ${POSTGRES_DB:-messenger}
POSTGRES_USER: ${POSTGRES_USER:-messenger}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
REDIS_URL: redis://redis:6379/0
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
CACHE_TTL_SECONDS: ${CACHE_TTL_SECONDS:-30}
MAX_REQUEST_BYTES: ${MAX_REQUEST_BYTES:-65536}
MAX_INFLIGHT: ${MAX_INFLIGHT:-32}
<<: *api
deploy:
replicas: 2
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=1).read()"]
interval: 2s
timeout: 2s
start_period: 5s
retries: 2
migrate:
<<: *api
command: [python, -m, src.database]
healthcheck:
disable: true
restart: 'no'
depends_on:
postgres:
condition: service_healthy
redis:
nginx:
image: nginx:1.28.0-alpine
ports:
- '127.0.0.1:${APP_PORT:-8080}:8080'
volumes:
- ./infra/nginx.conf:/etc/nginx/nginx.conf:ro
networks: [edge, backend]
depends_on:
api:
condition: service_healthy
cpus: 1.0
mem_limit: 512m
healthcheck:
test: [CMD-SHELL, 'wget -q -O /dev/null http://127.0.0.1:8080/health/ready']
interval: 2s
timeout: 2s
retries: 3
cpus: 0.5
mem_limit: 128m
stop_grace_period: 10s
postgres:
image: postgres:17.4-bookworm
@@ -34,6 +75,7 @@ services:
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: 2s
@@ -47,6 +89,7 @@ services:
command: ["redis-server", "--appendonly", "yes", "--appendfsync", "always", "--maxmemory", "128mb", "--maxmemory-policy", "noeviction"]
volumes:
- redis_data:/data
networks: [backend]
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 2s
@@ -55,6 +98,10 @@ services:
cpus: 0.5
mem_limit: 256m
networks:
edge:
backend:
internal: true
volumes:
postgres_data:
redis_data:
+1
View File
@@ -0,0 +1 @@
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
+88
View File
@@ -0,0 +1,88 @@
{
"summary": {
"duration_seconds": 20.032,
"concurrency": 2,
"successful_http_rps": 61.9,
"successful_write_rps": 30.95,
"successful_requests": 1240,
"errors": 0,
"action_started_seconds": 3.001,
"action_finished_seconds": 5.454,
"first_read_write_after_action_seconds_from_start": {
"read": 2.466,
"write": 2.458
},
"max_success_gap_seconds": {
"read": 0.12,
"write": 0.116
},
"latency_ms": {
"50": 18.0,
"95": 52.71,
"99": 71.25
},
"confirmed_messages_preserved": true,
"duplicate_messages": 0,
"instances": [
"6fc32ef53bc9",
"a6ee3d7e3779"
],
"target": "6fc32ef53bc9"
},
"containers": {
"target": "6fc32ef53bc9",
"before": [
{
"id": "6fc32ef53bc923ae2b9300d22d99d833c1b59a0689e6cbbb78ca3dab0a1654d6",
"name": "/mtusi2026lab3-api-3",
"instance": "6fc32ef53bc9",
"image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082",
"state": "running",
"started": "2026-10-23T12:19:29.450305334Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
},
{
"id": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a",
"name": "/mtusi2026lab3-api-4",
"instance": "a6ee3d7e3779",
"image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082",
"state": "running",
"started": "2026-10-23T12:20:24.84845663Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
}
],
"after": [
{
"id": "6fc32ef53bc923ae2b9300d22d99d833c1b59a0689e6cbbb78ca3dab0a1654d6",
"name": "/mtusi2026lab3-api-3",
"instance": "6fc32ef53bc9",
"image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082",
"state": "exited",
"started": "2026-10-23T12:19:29.450305334Z",
"health": "unhealthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
},
{
"id": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a",
"name": "/mtusi2026lab3-api-4",
"instance": "a6ee3d7e3779",
"image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082",
"state": "running",
"started": "2026-10-23T12:20:24.84845663Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
}
]
},
"errors": []
}
+88
View File
@@ -0,0 +1,88 @@
{
"summary": {
"duration_seconds": 20.05,
"concurrency": 2,
"successful_http_rps": 65.84,
"successful_write_rps": 32.92,
"successful_requests": 1320,
"errors": 0,
"action_started_seconds": 3.001,
"action_finished_seconds": 5.363,
"first_read_write_after_action_seconds_from_start": {
"read": 2.409,
"write": 2.397
},
"max_success_gap_seconds": {
"read": 0.114,
"write": 0.102
},
"latency_ms": {
"50": 16.38,
"95": 48.29,
"99": 70.66
},
"confirmed_messages_preserved": true,
"duplicate_messages": 0,
"instances": [
"6fc32ef53bc9",
"a6ee3d7e3779"
],
"target": "a6ee3d7e3779"
},
"containers": {
"target": "a6ee3d7e3779",
"before": [
{
"id": "6fc32ef53bc923ae2b9300d22d99d833c1b59a0689e6cbbb78ca3dab0a1654d6",
"name": "/mtusi2026lab3-api-3",
"instance": "6fc32ef53bc9",
"image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082",
"state": "running",
"started": "2026-10-23T12:20:57.481834724Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
},
{
"id": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a",
"name": "/mtusi2026lab3-api-4",
"instance": "a6ee3d7e3779",
"image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082",
"state": "running",
"started": "2026-10-23T12:20:24.84845663Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
}
],
"after": [
{
"id": "6fc32ef53bc923ae2b9300d22d99d833c1b59a0689e6cbbb78ca3dab0a1654d6",
"name": "/mtusi2026lab3-api-3",
"instance": "6fc32ef53bc9",
"image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082",
"state": "running",
"started": "2026-10-23T12:20:57.481834724Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
},
{
"id": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a",
"name": "/mtusi2026lab3-api-4",
"instance": "a6ee3d7e3779",
"image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082",
"state": "exited",
"started": "2026-10-23T12:20:24.84845663Z",
"health": "unhealthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
}
]
},
"errors": []
}
+81
View File
@@ -0,0 +1,81 @@
[
{
"id": "52a2db0bf074fa8d0c8ac02253549dabd0fb214d4c2ab35eaa64174c43687f52",
"name": "/mtusi2026lab3-api-5",
"instance": "52a2db0bf074",
"image": "sha256:24f3d4879fd558d1741b8c68e8d6dd7ad1c3c2622d344e21d1f261c44ad6a168",
"state": "running",
"started": "2026-10-23T12:34:15.338654375Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
},
{
"id": "c5211dc7b5256fc33563384f55525ce3f39839ad27c16205aad0a6f33364ae4a",
"name": "/mtusi2026lab3-api-6",
"instance": "c5211dc7b525",
"image": "sha256:24f3d4879fd558d1741b8c68e8d6dd7ad1c3c2622d344e21d1f261c44ad6a168",
"state": "running",
"started": "2026-10-23T12:34:15.606253965Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
},
{
"id": "0fec18666f11eaf3b139f22852b71383ec3cf06b9cf171053950ca887a15119a",
"name": "/mtusi2026lab3-migrate-1",
"instance": "0fec18666f11",
"image": "sha256:24f3d4879fd558d1741b8c68e8d6dd7ad1c3c2622d344e21d1f261c44ad6a168",
"state": "exited",
"started": "2026-10-23T12:34:13.577380317Z",
"health": null,
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
},
{
"id": "cb856359deb9d61c5130f7d9374aa7cecbe39999902e8f87560f4d5fc1a62f79",
"name": "/mtusi2026lab3-nginx-1",
"instance": "cb856359deb9",
"image": "sha256:30f1c0d78e0ad60901648be663a710bdadf19e4c10ac6782c235200619158284",
"state": "running",
"started": "2026-10-23T12:19:29.173913476Z",
"health": "healthy",
"cpu": 500000000,
"memory": 134217728,
"ports": {
"8080/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "8080"
}
]
}
},
{
"id": "a1b2b187e907fcf6ce3b44fbc7c9a5fa807de2b5350d9633656dceab841a658e",
"name": "/mtusi2026lab3-postgres-1",
"instance": "a1b2b187e907",
"image": "sha256:304ab813518754228f9f792f79d6da36359b82d8ecf418096c636725f8c930ad",
"state": "running",
"started": "2026-10-23T12:19:28.899601583Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
},
{
"id": "57f3df8ca10975f9a4375878acc2ef8f668b0436abce7ef374e6f9193ccf0500",
"name": "/mtusi2026lab3-redis-1",
"instance": "57f3df8ca109",
"image": "sha256:fbdbaea47b9ae4ecc2082ecdb4e1cea81e32176ffb1dcf643d422ad07427e5d9",
"state": "running",
"started": "2026-10-23T12:19:28.754756013Z",
"health": "healthy",
"cpu": 500000000,
"memory": 268435456,
"ports": {}
}
]
+1
View File
@@ -0,0 +1 @@
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
+94
View File
@@ -0,0 +1,94 @@
{
"failover-1": {
"duration_seconds": 20.032,
"concurrency": 2,
"successful_http_rps": 61.9,
"successful_write_rps": 30.95,
"successful_requests": 1240,
"errors": 0,
"action_started_seconds": 3.001,
"action_finished_seconds": 5.454,
"first_read_write_after_action_seconds_from_start": {
"read": 2.466,
"write": 2.458
},
"max_success_gap_seconds": {
"read": 0.12,
"write": 0.116
},
"latency_ms": {
"50": 18.0,
"95": 52.71,
"99": 71.25
},
"confirmed_messages_preserved": true,
"duplicate_messages": 0,
"instances": [
"6fc32ef53bc9",
"a6ee3d7e3779"
],
"target": "6fc32ef53bc9"
},
"failover-2": {
"duration_seconds": 20.05,
"concurrency": 2,
"successful_http_rps": 65.84,
"successful_write_rps": 32.92,
"successful_requests": 1320,
"errors": 0,
"action_started_seconds": 3.001,
"action_finished_seconds": 5.363,
"first_read_write_after_action_seconds_from_start": {
"read": 2.409,
"write": 2.397
},
"max_success_gap_seconds": {
"read": 0.114,
"write": 0.102
},
"latency_ms": {
"50": 16.38,
"95": 48.29,
"99": 70.66
},
"confirmed_messages_preserved": true,
"duplicate_messages": 0,
"instances": [
"6fc32ef53bc9",
"a6ee3d7e3779"
],
"target": "a6ee3d7e3779"
},
"rolling": {
"duration_seconds": 37.166,
"concurrency": 2,
"successful_http_rps": 62.91,
"successful_write_rps": 31.45,
"successful_requests": 2338,
"errors": 0,
"action_started_seconds": 3.001,
"action_finished_seconds": 32.128,
"first_read_write_after_action_seconds_from_start": {
"read": 29.135,
"write": 29.137
},
"max_success_gap_seconds": {
"read": 0.216,
"write": 0.231
},
"latency_ms": {
"50": 16.51,
"95": 48.68,
"99": 75.14
},
"confirmed_messages_preserved": true,
"duplicate_messages": 0,
"instances": [
"6fc32ef53bc9",
"8c864b1beb6a",
"a6ee3d7e3779",
"bb8669ea27d1"
],
"target": null
}
}
+4
View File
@@ -0,0 +1,4 @@
{
"same_token": true,
"same_201_message": true
}
+11
View File
@@ -0,0 +1,11 @@
{
"requests": 24,
"concurrency": 8,
"instances": [
"6fc32ef53bc9",
"a6ee3d7e3779"
],
"unique_messages": 1,
"same_response": true,
"conflict_auth_access_key_scope": "PASS"
}
+2
View File
@@ -0,0 +1,2 @@
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
+2
View File
@@ -0,0 +1,2 @@
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
+3
View File
@@ -0,0 +1,3 @@
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 124, "failed_attempts": 0, "first_recovery_seconds": 2.204}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
+3
View File
@@ -0,0 +1,3 @@
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 124, "failed_attempts": 0, "first_recovery_seconds": 2.233}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
+13
View File
@@ -0,0 +1,13 @@
Command: docker compose restart api postgres redis nginx
Before (UTC):
/mtusi2026lab3-api-3 2026-10-23T12:18:00.276504145Z
/mtusi2026lab3-api-4 2026-10-23T12:18:00.50467995Z
/mtusi2026lab3-nginx-1 2026-10-23T12:18:06.464884093Z
/mtusi2026lab3-postgres-1 2026-10-23T12:17:55.596165683Z
/mtusi2026lab3-redis-1 2026-10-23T12:17:55.593753417Z
After (UTC):
/mtusi2026lab3-api-3 2026-10-23T12:19:29.450305334Z
/mtusi2026lab3-api-4 2026-10-23T12:19:29.302397436Z
/mtusi2026lab3-nginx-1 2026-10-23T12:19:29.173913476Z
/mtusi2026lab3-postgres-1 2026-10-23T12:19:28.899601583Z
/mtusi2026lab3-redis-1 2026-10-23T12:19:28.754756013Z
+149
View File
@@ -0,0 +1,149 @@
{
"summary": {
"duration_seconds": 37.166,
"concurrency": 2,
"successful_http_rps": 62.91,
"successful_write_rps": 31.45,
"successful_requests": 2338,
"errors": 0,
"action_started_seconds": 3.001,
"action_finished_seconds": 32.128,
"first_read_write_after_action_seconds_from_start": {
"read": 29.135,
"write": 29.137
},
"max_success_gap_seconds": {
"read": 0.216,
"write": 0.231
},
"latency_ms": {
"50": 16.51,
"95": 48.68,
"99": 75.14
},
"confirmed_messages_preserved": true,
"duplicate_messages": 0,
"instances": [
"6fc32ef53bc9",
"8c864b1beb6a",
"a6ee3d7e3779",
"bb8669ea27d1"
],
"target": null
},
"containers": {
"before": [
{
"id": "6fc32ef53bc923ae2b9300d22d99d833c1b59a0689e6cbbb78ca3dab0a1654d6",
"name": "/mtusi2026lab3-api-3",
"instance": "6fc32ef53bc9",
"image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082",
"state": "running",
"started": "2026-10-23T12:20:57.481834724Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
},
{
"id": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a",
"name": "/mtusi2026lab3-api-4",
"instance": "a6ee3d7e3779",
"image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082",
"state": "running",
"started": "2026-10-23T12:21:29.455170279Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
}
],
"steps": [
{
"replaced": "6fc32ef53bc923ae2b9300d22d99d833c1b59a0689e6cbbb78ca3dab0a1654d6",
"ready": [
{
"id": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a",
"name": "/mtusi2026lab3-api-4",
"instance": "a6ee3d7e3779",
"image": "sha256:cc3df05d4a5e2283a9dd616442a821fa2a8a4a81a67e4d407a7395c3fcb9f082",
"state": "running",
"started": "2026-10-23T12:21:29.455170279Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
},
{
"id": "8c864b1beb6a090a0eff2397fe989ab21ebd0190291f164e6df7dacf7285e82a",
"name": "/mtusi2026lab3-api-5",
"instance": "8c864b1beb6a",
"image": "sha256:7eed22c328d1b387371156ba7c4a30a8017bd48be3acb0b94b63c561925b43ea",
"state": "running",
"started": "2026-10-23T12:21:55.548004137Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
}
]
},
{
"replaced": "a6ee3d7e3779d847efe497f22021f9942f805202ade85495734e1f93418aeb5a",
"ready": [
{
"id": "8c864b1beb6a090a0eff2397fe989ab21ebd0190291f164e6df7dacf7285e82a",
"name": "/mtusi2026lab3-api-5",
"instance": "8c864b1beb6a",
"image": "sha256:7eed22c328d1b387371156ba7c4a30a8017bd48be3acb0b94b63c561925b43ea",
"state": "running",
"started": "2026-10-23T12:21:55.548004137Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
},
{
"id": "bb8669ea27d1bd1fa5b6442a1d1ebcc689aa0ec3991dffdfaa5cb96fb61fe5da",
"name": "/mtusi2026lab3-api-6",
"instance": "bb8669ea27d1",
"image": "sha256:7eed22c328d1b387371156ba7c4a30a8017bd48be3acb0b94b63c561925b43ea",
"state": "running",
"started": "2026-10-23T12:22:08.293929923Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
}
]
}
],
"after": [
{
"id": "8c864b1beb6a090a0eff2397fe989ab21ebd0190291f164e6df7dacf7285e82a",
"name": "/mtusi2026lab3-api-5",
"instance": "8c864b1beb6a",
"image": "sha256:7eed22c328d1b387371156ba7c4a30a8017bd48be3acb0b94b63c561925b43ea",
"state": "running",
"started": "2026-10-23T12:21:55.548004137Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
},
{
"id": "bb8669ea27d1bd1fa5b6442a1d1ebcc689aa0ec3991dffdfaa5cb96fb61fe5da",
"name": "/mtusi2026lab3-api-6",
"instance": "bb8669ea27d1",
"image": "sha256:7eed22c328d1b387371156ba7c4a30a8017bd48be3acb0b94b63c561925b43ea",
"state": "running",
"started": "2026-10-23T12:22:08.293929923Z",
"health": "healthy",
"cpu": 1000000000,
"memory": 536870912,
"ports": {}
}
]
},
"errors": []
}
+20
View File
@@ -0,0 +1,20 @@
test_concurrent_writers_do_not_lose_version_increments (test_cache.CacheTests.test_concurrent_writers_do_not_lose_version_increments) ... ok
test_hit_still_checks_membership_and_cache_failure_falls_back (test_cache.CacheTests.test_hit_still_checks_membership_and_cache_failure_falls_back) ... ok
test_http_read_after_write_and_cursor_pages (test_cache.CacheTests.test_http_read_after_write_and_cursor_pages) ... ok
test_late_fill_cannot_restore_old_page (test_cache.CacheTests.test_late_fill_cannot_restore_old_page) ... ok
test_read_after_write_through_another_api_process (test_cache.CacheTests.test_read_after_write_through_another_api_process) ... ok
test_version_rolls_back_with_failed_message (test_cache.CacheTests.test_version_rolls_back_with_failed_message) ... ok
test_migrate_empty_schema_and_preserve_orm_data_on_repeat (test_database.MigrationTests.test_migrate_empty_schema_and_preserve_orm_data_on_repeat) ... ok
test_concurrent_different_payloads_have_one_winner (test_idempotency.IdempotencyTests.test_concurrent_different_payloads_have_one_winner) ... ok
test_record_and_message_rollback_together (test_idempotency.IdempotencyTests.test_record_and_message_rollback_together) ... ok
test_chat_rollback (test_lab2.Lab2Tests.test_chat_rollback) ... ok
test_expiry_short_ttl (test_lab2.Lab2Tests.test_expiry_short_ttl) ... ok
test_migrations_repeat (test_lab2.Lab2Tests.test_migrations_repeat) ... ok
test_password_logout_and_identity (test_lab2.Lab2Tests.test_password_logout_and_identity) ... ok
test_registration_race (test_lab2.Lab2Tests.test_registration_race) ... ok
test_unicode_password (test_lab2.Lab2Tests.test_unicode_password) ... ok
----------------------------------------------------------------------
Ran 15 tests in 19.204s
OK
+35
View File
@@ -0,0 +1,35 @@
worker_processes 1;
worker_shutdown_timeout 8s;
events { worker_connections 1024; }
http {
resolver 127.0.0.11 valid=2s ipv6=off;
resolver_timeout 1s;
upstream messenger {
zone messenger 64k;
server api:8080 resolve max_fails=1 fail_timeout=2s;
}
log_format upstream '$request_method $uri $status upstream=$upstream_addr '
'upstream_status=$upstream_status time=$request_time';
access_log /var/log/nginx/access.log upstream;
server {
listen 8080;
client_max_body_size 64k;
client_body_timeout 5s;
client_header_timeout 5s;
keepalive_timeout 5s;
location / {
proxy_pass http://messenger;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Connection close;
proxy_connect_timeout 1s;
proxy_send_timeout 6s;
proxy_read_timeout 6s;
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2;
proxy_next_upstream_timeout 8s;
# Never transparently retry a POST already sent to an API.
# A client retries messages using the original Idempotency-Key.
}
}
}
+9
View File
@@ -0,0 +1,9 @@
-- Additive migration: no rewrite of existing lab2 tables or messages.
CREATE TABLE message_idempotency (
actor_id uuid NOT NULL REFERENCES users(id),
chat_id uuid NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
key text NOT NULL CHECK (key ~ '^[A-Za-z0-9._:-]{1,128}$'),
message_id uuid NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
PRIMARY KEY (actor_id, chat_id, key)
);
+79
View File
@@ -0,0 +1,79 @@
"""Project-scoped Docker operations; never read/export container environments."""
import json
import subprocess
import time
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
def docker(*args):
return subprocess.check_output(['docker', *args], cwd=ROOT, text=True, timeout=120).strip()
def compose(*args):
return docker('compose', *args)
def snapshot(service=None):
ids = compose('ps', '-a', '-q', *([service] if service else [])).split()
if not ids:
return []
# Select fields before returning; no secrets in evidence.
template = ('{"id":{{json .Id}},"name":{{json .Name}},"instance":{{json .Config.Hostname}},'
'"image":{{json .Image}},"state":{{json .State.Status}},'
'"started":{{json .State.StartedAt}},'
'"health":{{with index .State "Health"}}{{json .Status}}{{else}}null{{end}},'
'"cpu":{{.HostConfig.NanoCpus}},"memory":{{.HostConfig.Memory}},'
'"ports":{{json .HostConfig.PortBindings}}}')
return [json.loads(line) for line in docker('inspect', '--format', template, *ids).splitlines()]
def wait_api(count=2, timeout=60):
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
rows = snapshot('api')
if len(rows) == count and all(r['health'] == 'healthy' and r['state'] == 'running' for r in rows):
time.sleep(3) # Docker DNS validity 2s, plus resolver budget 1s.
return rows
time.sleep(0.5)
raise RuntimeError('API replicas did not become healthy')
def save(name, value):
(ROOT / 'evidence').mkdir(exist_ok=True)
(ROOT / 'evidence' / name).write_text(json.dumps(value, indent=2) + '\n', encoding='utf-8')
def stop_instance(instance):
before = snapshot('api')
matches = [r for r in before if r['instance'] == instance and r['state'] == 'running']
if len(matches) != 1 or sum(r['state'] == 'running' for r in before) < 2:
raise RuntimeError('Target must identify one running API with a running peer')
docker('stop', '--time', '8', matches[0]['id'])
result = {'target': instance, 'before': before, 'after': snapshot('api')}
if next(r for r in result['after'] if r['instance'] == instance)['state'] != 'exited':
raise RuntimeError('Target was not stopped')
return result
def restore():
compose('up', '-d', '--no-deps', '--no-recreate', 'api')
return wait_api()
def rolling():
before = wait_api()
if len(before) != 2:
raise RuntimeError('This rolling scenario requires exactly two replicas')
steps = []
for old in before:
stop_instance(old['instance'])
# Only remove the selected, already stopped API; never remove a volume.
docker('rm', old['id'])
compose('up', '-d', '--no-deps', '--no-recreate', '--scale', 'api=2', 'api')
steps.append({'replaced': old['id'], 'ready': wait_api()})
result = {'before': before, 'steps': steps, 'after': snapshot('api')}
if {r['id'] for r in before} & {r['id'] for r in result['after']}:
raise RuntimeError('Not all original API containers were replaced')
return result
+2 -2
View File
@@ -15,12 +15,12 @@ def snapshot():
def main():
before = snapshot()
subprocess.run(['docker', 'compose', 'restart', 'api', 'postgres', 'redis'],
subprocess.run(['docker', 'compose', 'restart', 'api', 'postgres', 'redis', 'nginx'],
cwd=ROOT, check=True, timeout=60)
after = snapshot()
(ROOT / 'evidence').mkdir(exist_ok=True)
(ROOT / 'evidence' / 'restart.txt').write_text(
'Command: docker compose restart api postgres redis\nBefore (UTC):\n' + before
'Command: docker compose restart api postgres redis nginx\nBefore (UTC):\n' + before
+ 'After (UTC):\n' + after, encoding='utf-8')
+6
View File
@@ -0,0 +1,6 @@
from ops import compose, rolling
if __name__ == '__main__':
compose('build', 'api')
compose('run', '--rm', '--no-deps', 'migrate')
rolling()
+3
View File
@@ -0,0 +1,3 @@
@echo off
cd /d "%~dp0.."
python scripts\stop-one.py
+5
View File
@@ -0,0 +1,5 @@
import os
from ops import stop_instance
if __name__ == '__main__':
stop_instance(os.environ['TARGET_INSTANCE_ID'])
+4
View File
@@ -0,0 +1,4 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
exec python3 scripts/stop-one.py
+199
View File
@@ -0,0 +1,199 @@
"""Repeatable grade-4 experiments. Run on host with Docker access and UTF-8 mode."""
import argparse
import json
import os
import subprocess
import sys
import threading
import time
from concurrent.futures import ThreadPoolExecutor
from uuid import uuid4
from ops import ROOT, compose, restore, rolling, save, snapshot, stop_instance, wait_api
sys.path.insert(0, str(ROOT / 'tests'))
from client import Client, Failure, check
from resilience import history
def command(name, args):
result = subprocess.run(args, cwd=ROOT, text=True, encoding='utf-8',
stdout=subprocess.PIPE, stderr=subprocess.STDOUT, timeout=180)
(ROOT / 'evidence' / name).write_text(result.stdout, encoding='utf-8')
print(result.stdout, flush=True)
check(result.returncode == 0, 'Command failed: ' + name)
def concurrency(base):
c = Client(base)
alice, bob, eve, chat = c.bootstrap()
path = '/api/v1/chats/' + chat['id'] + '/messages'
key = uuid4().hex
barrier = threading.Barrier(8)
def send(_):
client = Client(base)
barrier.wait(timeout=10)
return client.message(alice, chat, 'one concurrent message', key=key)
responses = []
with ThreadPoolExecutor(max_workers=8) as executor:
for _ in range(3):
responses.extend(executor.map(send, range(8)))
first = responses[0]['json']
check(all(r['json'] == first and r['status'] == 201 for r in responses), 'Concurrent replies differ')
instances = sorted({r['headers']['X-Instance-Id'] for r in responses})
check(len(instances) >= 2, 'Concurrent test did not reach both replicas')
check(history(c, alice, chat) == [first], 'Concurrent retry duplicated message')
c.call('POST', path, 409, actor=alice, body={'text': 'different'}, headers={'Idempotency-Key': key})
c.call('POST', path, 401, body={'text': 'one concurrent message'}, headers={'Idempotency-Key': key})
c.call('POST', path, 404, actor=eve, body={'text': 'one concurrent message'}, headers={'Idempotency-Key': key})
for invalid in (None, '', 'bad key', 'x' * 129):
c.call('POST', path, 400, actor=alice, body={'text': 'invalid key'},
headers={} if invalid is None else {'Idempotency-Key': invalid})
other = c.message(bob, chat, 'independent user', key=key)['json']
check(other['id'] != first['id'], 'Key scope must include actor')
chat2 = c.call('POST', '/api/v1/chats', 201, actor=alice,
body={'title': 'Scope', 'member_ids': [alice['id']]}, schema='Chat')['json']
other = c.message(alice, chat2, 'independent chat', key=key)['json']
check(other['id'] != first['id'], 'Key scope must include chat')
save('idempotency.json', {'requests': 24, 'concurrency': 8, 'instances': instances,
'unique_messages': 1, 'same_response': True,
'conflict_auth_access_key_scope': 'PASS'})
return c, alice, chat, key, first
def experiment(base, name, action, target=None):
c = Client(base, timeout=9)
alice, bob, _, chat = c.bootstrap()
confirmed_before = c.message(alice, chat, 'before ' + name)['json']
events = []
stop = threading.Event()
started = time.monotonic()
def worker():
client = Client(base, timeout=9)
key = uuid4().hex
while not stop.is_set():
begin = time.monotonic()
try:
response = client.message(alice, chat, key, key=key)
msg = response['json']
events.append({'kind': 'write', 'time': time.monotonic() - started,
'latency': response['elapsed'], 'instance': response['headers']['X-Instance-Id'],
'message': msg})
key = uuid4().hex
except Failure as exc:
events.append({'kind': 'error', 'operation': 'write', 'time': time.monotonic() - started,
'latency': time.monotonic() - begin, 'error': str(exc)})
continue # Keep original key/body after an uncertain write.
begin = time.monotonic()
try:
response = client.call('GET', '/api/v1/chats/' + chat['id'], actor=bob, schema='Chat')
events.append({'kind': 'read', 'time': time.monotonic() - started,
'latency': response['elapsed'], 'instance': response['headers']['X-Instance-Id']})
except Failure as exc:
events.append({'kind': 'error', 'operation': 'read', 'time': time.monotonic() - started,
'latency': time.monotonic() - begin, 'error': str(exc)})
time.sleep(0.02)
with ThreadPoolExecutor(max_workers=2) as executor:
futures = [executor.submit(worker) for _ in range(2)]
try:
time.sleep(3)
action_started = time.monotonic() - started
effect = action()
action_finished = time.monotonic() - started
time.sleep(max(5, 20 - (time.monotonic() - started)))
finally:
stop.set()
for future in futures:
future.result()
duration = time.monotonic() - started
successes = [e for e in events if e['kind'] != 'error']
errors = [e for e in events if e['kind'] == 'error']
writes = [e for e in successes if e['kind'] == 'write']
recovery = {}
for kind in ('read', 'write'):
after = [e for e in successes if e['kind'] == kind and e['time'] >= action_finished]
check(bool(after), 'No ' + kind + ' after action')
recovery[kind] = round(min(e['time'] for e in after) - action_started, 3)
if target:
check(all(e['instance'] != target for e in after), 'Stopped target still serves')
check(recovery[kind] <= 10, 'Recovery exceeded 10 seconds')
messages = history(c, bob, chat)
by_id = {m['id']: m for m in messages}
check(by_id.get(confirmed_before['id']) == confirmed_before, 'Pre-failure message lost')
check(all(by_id.get(e['message']['id']) == e['message'] for e in writes), 'Confirmed write lost')
check(len({m['text'] for m in messages}) == len(messages), 'Retry duplicated a message')
# Retry a pre-failure key through the surviving/new processes.
if writes:
item = writes[0]['message']
check(c.message(alice, chat, item['text'], key=item['text'])['json'] == item, 'Replay changed after action')
latencies = sorted(e['latency'] for e in successes)
gaps = {}
for kind in ('read', 'write'):
times = sorted(e['time'] for e in successes if e['kind'] == kind)
gaps[kind] = round(max((b - a for a, b in zip(times, times[1:])), default=0), 3)
summary = {'duration_seconds': round(duration, 3), 'concurrency': 2,
'successful_http_rps': round(len(successes) / duration, 2),
'successful_write_rps': round(len(writes) / duration, 2),
'successful_requests': len(successes), 'errors': len(errors),
'action_started_seconds': round(action_started, 3),
'action_finished_seconds': round(action_finished, 3),
'first_read_write_after_action_seconds_from_start': recovery,
'max_success_gap_seconds': gaps,
'latency_ms': {str(p): round(latencies[min(int(len(latencies)*p/100), len(latencies)-1)]*1000, 2)
for p in (50, 95, 99)},
'confirmed_messages_preserved': True, 'duplicate_messages': 0,
'instances': sorted({e['instance'] for e in successes}), 'target': target}
save(name + '.json', {'summary': summary, 'containers': effect, 'errors': errors})
print(name + ': ' + json.dumps(summary), flush=True)
return summary
def main():
parser = argparse.ArgumentParser()
parser.add_argument('--base-url', default='http://127.0.0.1:8080')
args = parser.parse_args()
os.environ['PYTHONUTF8'] = '1'
base = args.base_url
wait_api()
command('check.txt', [sys.executable, '-X', 'utf8', 'scripts/check_contract.py'])
command('final-smoke.txt', [sys.executable, '-X', 'utf8', 'tests/smoke.py', '--base-url', base])
c, actor, chat, key, original = concurrency(base)
hook = 'scripts/restart.cmd' if os.name == 'nt' else 'scripts/restart.sh'
command('persistence.txt', [sys.executable, '-X', 'utf8', 'tests/resilience.py', '--mode', 'persistence',
'--base-url', base, '--action-script', hook])
wait_api()
check(c.message(actor, chat, original['text'], key=key)['json'] == original,
'Idempotency/session not preserved across full restart')
save('idempotency-restart.json', {'same_token': True, 'same_201_message': True})
hook = 'scripts/stop-one.cmd' if os.name == 'nt' else 'scripts/stop-one.sh'
for index in range(2):
try:
command('public-failover-' + str(index+1) + '.txt',
[sys.executable, '-X', 'utf8', 'tests/resilience.py', '--mode', 'failover',
'--base-url', base, '--action-script', hook])
finally:
restore()
results = {}
for index, row in enumerate(snapshot('api'), start=1):
target = row['instance']
try:
results['failover-' + str(index)] = experiment(base, 'failover-' + str(index),
lambda: stop_instance(target), target)
finally:
restore()
# Build one image first; apply compatible migrations once before replacing replicas.
compose('build', 'api')
compose('run', '--rm', '--no-deps', 'migrate')
results['rolling'] = experiment(base, 'rolling-load', rolling)
save('grade4-summary.json', results)
save('final-containers.json', snapshot())
command('final-smoke.txt', [sys.executable, '-X', 'utf8', 'tests/smoke.py', '--base-url', base])
print('PASS: all grade-4 scenarios', flush=True)
if __name__ == '__main__':
main()
+2 -1
View File
@@ -2,6 +2,7 @@ from fastapi import Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from starlette.exceptions import HTTPException as StarletteHTTPException
from .middleware import INSTANCE_ID
class APIError(Exception):
@@ -15,7 +16,7 @@ def error_response(request: Request, status_code: int, code: str, message: str)
request_id = getattr(request.state, "request_id", "")
return JSONResponse(
status_code=status_code,
headers={"X-Request-Id": request_id},
headers={"X-Request-Id": request_id, "X-Instance-Id": INSTANCE_ID},
content={
"error": {
"code": code,
+1 -3
View File
@@ -5,10 +5,9 @@ from contextlib import asynccontextmanager
from sqlalchemy.exc import OperationalError, InterfaceError, TimeoutError as PoolTimeout
from sqlalchemy.orm import sessionmaker
from redis.exceptions import RedisError
from starlette.concurrency import run_in_threadpool
from .errors import APIError, api_error_handler, validation_error_handler, http_error_handler, internal_error_handler, dependency_error_handler
from .database import create_db_engine, migrate
from .database import create_db_engine
from .store import store
from .auth import sessions
from .middleware import RequestIdMiddleware
@@ -23,7 +22,6 @@ from .routers.auth import router as auth_router
async def lifespan(app):
engine = create_db_engine()
try:
await run_in_threadpool(migrate, engine)
store.sessions = sessionmaker(engine, expire_on_commit=False)
yield
finally:
+5
View File
@@ -1,8 +1,11 @@
from uuid import uuid4
from socket import gethostname
from starlette.responses import JSONResponse
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request
INSTANCE_ID = gethostname()
class RequestIdMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request: Request, call_next):
@@ -25,8 +28,10 @@ class RequestIdMiddleware(BaseHTTPMiddleware):
},
)
response.headers["X-Request-Id"] = request_id
response.headers["X-Instance-Id"] = INSTANCE_ID
return response
response = await call_next(request)
response.headers["X-Request-Id"] = request_id
response.headers["X-Instance-Id"] = INSTANCE_ID
return response
+9
View File
@@ -58,3 +58,12 @@ class SchemaMigration(Base):
__tablename__ = 'schema_migrations'
version: Mapped[str] = mapped_column(Text, primary_key=True)
applied_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=True)
class IdempotencyRecord(Base):
__tablename__ = 'message_idempotency'
actor_id: Mapped[str] = mapped_column(Uuid(as_uuid=False), ForeignKey('users.id'), primary_key=True)
chat_id: Mapped[str] = mapped_column(Uuid(as_uuid=False), ForeignKey('chats.id', ondelete='CASCADE'), primary_key=True)
key: Mapped[str] = mapped_column(Text, primary_key=True)
message_id: Mapped[str] = mapped_column(Uuid(as_uuid=False), ForeignKey('messages.id', ondelete='CASCADE'))
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.clock_timestamp())
+8 -3
View File
@@ -1,6 +1,8 @@
from typing import Optional
import re
from fastapi import APIRouter, Depends, Query, status
from fastapi import APIRouter, Depends, Header, Query, status
from ..errors import APIError
from ..dependencies import current_user, page_limit
from ..schemas.chat import Chat, ChatPage, CreateChat
@@ -30,8 +32,11 @@ def get_chat(chat_id: str, user: dict = Depends(current_user)):
@router.post("/{chat_id}/messages", response_model=Message, status_code=status.HTTP_201_CREATED)
def create_message(chat_id: str, payload: CreateMessage, user: dict = Depends(current_user)):
return store.create_message(chat_id, user["id"], payload.text)
def create_message(chat_id: str, payload: CreateMessage, user: dict = Depends(current_user),
idempotency_key: Optional[str] = Header(default=None)):
if not idempotency_key or not re.fullmatch(r'[A-Za-z0-9._:-]{1,128}', idempotency_key):
raise APIError(400, 'invalid_request', 'Требуется корректный Idempotency-Key')
return store.create_message(chat_id, user["id"], payload.text, idempotency_key)
@router.get("/{chat_id}/messages", response_model=MessagePage)
+15 -2
View File
@@ -10,7 +10,7 @@ from sqlalchemy.exc import IntegrityError
from .auth import password_hasher, verify_password, unauthorized
from .errors import APIError
from .cache import history_cache
from .models import User, Chat, ChatMember, Message
from .models import User, Chat, ChatMember, Message, IdempotencyRecord
def ensure_uuid(value):
@@ -130,15 +130,28 @@ class PostgresStore:
items = [self._members(session, chat) for chat in chats[:limit]]
return self._page(items, len(chats) > limit, 'chats', actor_id)
def create_message(self, chat_id, actor_id, text):
def create_message(self, chat_id, actor_id, text, idempotency_key=None):
chat_id = ensure_uuid(chat_id)
with self.sessions.begin() as session:
self._chat(session, chat_id, actor_id)
if idempotency_key is not None:
# Serialize writers to this chat before looking up the key.
# The same row is updated below for history cache invalidation.
session.execute(select(Chat.id).where(Chat.id == chat_id).with_for_update())
record = session.get(IdempotencyRecord, (actor_id, chat_id, idempotency_key))
if record is not None:
previous = session.get(Message, record.message_id)
if previous.text != text:
raise APIError(409, 'conflict', 'Ключ уже использован для другого сообщения')
return serialize(previous, *MESSAGE_FIELDS)
session.execute(update(Chat).where(Chat.id == chat_id).values(
history_version=Chat.history_version + 1))
message = Message(chat_id=chat_id, sender_id=actor_id, text=text)
session.add(message)
session.flush()
if idempotency_key is not None:
session.add(IdempotencyRecord(actor_id=actor_id, chat_id=chat_id,
key=idempotency_key, message_id=message.id))
result = serialize(message, *MESSAGE_FIELDS)
return result
+1 -1
View File
@@ -27,7 +27,7 @@ class MigrationTests(unittest.TestCase):
self.assertEqual(store.list_messages(chat['id'], user['id'], 100, None)['items'], [message])
with isolated.connect() as conn:
self.assertEqual(set(conn.scalars(select(SchemaMigration.version))),
{'001_initial.sql', '002_history_version.sql'})
{'001_initial.sql', '002_history_version.sql', '003_message_idempotency.sql'})
indexes = {index['name'] for index in inspect(isolated).get_indexes('messages')}
self.assertIn('messages_history_idx', indexes)
self.assertEqual(len(inspect(isolated).get_foreign_keys('messages')), 2)
+55
View File
@@ -0,0 +1,55 @@
"""Database atomicity and concurrent conflict checks, using isolated synthetic data."""
import unittest
from concurrent.futures import ThreadPoolExecutor
from unittest.mock import patch
from uuid import uuid4
from sqlalchemy import func, select
from sqlalchemy.orm import Session, sessionmaker
from src.database import create_db_engine
from src.errors import APIError
from src.models import Chat, IdempotencyRecord, Message
from src.store import PostgresStore
class IdempotencyTests(unittest.TestCase):
def setUp(self):
self.engine = create_db_engine()
self.store = PostgresStore()
self.store.sessions = sessionmaker(self.engine, expire_on_commit=False)
self.user = self.store.create_user('idem_' + uuid4().hex[:16], 'Idempotency', 'Synthetic-password-123')
self.chat = self.store.create_chat(self.user['id'], 'Atomic', [self.user['id']])
def tearDown(self):
self.engine.dispose()
def test_record_and_message_rollback_together(self):
real_add = Session.add
def fail_record(session, instance, *args, **kwargs):
if isinstance(instance, IdempotencyRecord):
raise RuntimeError('Simulate failure after message INSERT, before COMMIT')
return real_add(session, instance, *args, **kwargs)
args = (self.chat['id'], self.user['id'], 'atomic', 'same-key')
with patch.object(Session, 'add', fail_record):
with self.assertRaises(RuntimeError):
self.store.create_message(*args)
with Session(self.engine) as session:
self.assertEqual(session.scalar(select(func.count()).select_from(Message).where(Message.chat_id == self.chat['id'])), 0)
self.assertIsNone(session.get(IdempotencyRecord, (self.user['id'], self.chat['id'], 'same-key')))
self.assertEqual(session.get(Chat, self.chat['id']).history_version, 0)
first = self.store.create_message(*args)
self.assertEqual(self.store.create_message(*args), first)
def test_concurrent_different_payloads_have_one_winner(self):
def send(index):
try:
return self.store.create_message(self.chat['id'], self.user['id'], str(index), 'conflict'), 201
except APIError as exc:
return None, exc.status_code
with ThreadPoolExecutor(max_workers=8) as executor:
results = list(executor.map(send, range(8)))
self.assertEqual(sorted(code for _, code in results), [201] + [409] * 7)
with Session(self.engine) as session:
self.assertEqual(session.scalar(select(func.count()).select_from(Message).where(Message.chat_id == self.chat['id'])), 1)
self.assertEqual(session.get(Chat, self.chat['id']).history_version, 1)