diff --git a/.env.example b/.env.example index d32b9be0..fcf86596 100644 --- a/.env.example +++ b/.env.example @@ -1,13 +1,4 @@ -# Copy to .env for your LOCAL synthetic test environment; never commit .env. -# These are logical interface suggestions; map actual framework names in REPORT.md. -APP_HOST=0.0.0.0 +# Copy to .env for the local synthetic test stack. Never commit .env. APP_PORT=8080 -APP_ENV=lab SESSION_TTL_SECONDS=3600 -# Choose credentials locally. File paths contain no secret values. -DATABASE_URL_FILE=/run/secrets/database_url -# Optional on 3, required use on 4 in lab2; Redis OR Valkey: -SESSION_STORE=postgres -CACHE_URL_FILE=/run/secrets/cache_url -API_REPLICAS=2 -IDEMPOTENCY_TTL_SECONDS=86400 +BUILD_REVISION=local diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..dfdb8b77 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +*.sh text eol=lf diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e6e63eb2..76f76a67 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,18 +1,28 @@ -## Лабораторная 3 +# Лабораторная 3 -Автор / группа: TODO -Целевая оценка (3/4/5): TODO -Трек 5, если заявлен: TODO +Автор / группа: Badradine Ali / BVT2302 +Целевая оценка: 4 +Трек 5: не заявлен. -Что реализовано и что перенесено: TODO -Команды запуска из чистого clone: TODO -Результаты проверок и ссылка на REPORT.md: TODO -Ограничения / известные ошибки: TODO -Источники и использование ИИ: TODO +Что реализовано: перенесена реализация Lab 2 (PostgreSQL, Redis-сессии, Argon2id, API и миграции); добавлены две API-реплики за NGINX, X-Instance-Id и общая идемпотентность POST сообщений через PostgreSQL. -- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. -- [ ] Контракт и публичные тесты не ослаблены. -- [ ] make check и make test выполнены; приложен реальный вывод. -- [ ] Сценарии отказов/безопасности своего уровня воспроизведены. -- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. -- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. +Запуск из чистого clone: команды приведены в REPORT.md. Make-команды запускать в WSL/Ubuntu. Секреты создаются локально скриптом scripts/create-secrets.ps1 и в Git не добавляются. + +Результаты и доказательства: +- smoke и контракт: PASS; evidence/smoke.txt +- параллельная идемпотентность: PASS, 24 запроса через 2 реплики создали одно сообщение; evidence/idempotency.txt +- restart PostgreSQL/Redis/API: PASS, сессия и подтверждённые данные сохранены; evidence/persistence.txt и evidence/persistence-hook.log +- failover: PASS на двух различных instance ID; подробные измерения и IDs — REPORT.md и evidence/ +- rolling update: PASS; старые API заменены по одному, в конце 2 новые реплики healthy; последний тест нагрузки: 2 881 успешный и 2 неудачных запроса из 2 883 (0,0694% ошибок), см. evidence/rolling-update-load.json +- OpenAPI 3.1 / JSON Schema: PASS. + +Ограничения: один Docker-хост; DB, Redis и LB остаются single points of failure. Последний rolling-update прогон дал 2 ошибки из 2 883 запросов под нагрузкой; данные показаны без сокрытия. Docker Desktop CPU/RAM allocation не записаны. Измерения закрытого нагрузочного теста не являются гарантией production capacity. + +Источники и использование ИИ: документация Docker Compose и NGINX, условие/контракт лабораторной; OpenAI Codex помог с реализацией и ревью. Автор должен понимать и защищать решения. + +- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. +- [x] Контракт и публичные тесты не ослаблены. +- [x] make check и make test выполнены в WSL/Ubuntu; вывод сохранён в evidence/make-check.log и evidence/make-test.log. +- [x] Сценарии отказов/безопасности для оценки 4 воспроизведены; результаты и ограничения приведены. +- [x] Все секреты и приватные ключи находятся вне Git; отчёт и приложенные результаты не содержат tokens. +- [x] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. \ No newline at end of file diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..03fbf5d1 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,27 @@ +FROM python:3.12.6-slim-bookworm + +ARG BUILD_REVISION=local +ENV PYTHONDONTWRITEBYTECODE=1 \ + PYTHONUNBUFFERED=1 \ + PYTHONUTF8=1 \ + APP_HOST=0.0.0.0 \ + APP_PORT=8080 \ + APP_BUILD_REVISION=${BUILD_REVISION} + +WORKDIR /app + +COPY requirements.txt ./ +RUN pip install --no-cache-dir --requirement requirements.txt + +COPY src/ ./src/ +COPY migrations/ ./migrations/ + +RUN useradd --create-home --uid 10001 appuser +USER appuser + +EXPOSE 8080 + +HEALTHCHECK --interval=3s --timeout=2s --start-period=10s --retries=3 \ + CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8080/health/ready',timeout=2).status==200 else 1)" + +CMD ["uvicorn", "src.app.main:app", "--host", "0.0.0.0", "--port", "8080", "--workers", "1", "--timeout-graceful-shutdown", "5"] diff --git a/Makefile b/Makefile index 5d86d171..00fa01cb 100644 --- a/Makefile +++ b/Makefile @@ -4,7 +4,7 @@ CA_FILE ?= ACTION_SCRIPT ?= TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",) -.PHONY: help check validate test load test-persistence test-failover +.PHONY: help check validate test load test-persistence test-failover test-idempotency test-rolling help: @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes" @@ -28,3 +28,9 @@ test-persistence: test-failover: @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2) $(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) + +test-idempotency: + $(PYTHON) tests/idempotency_concurrency.py --base-url "$(BASE_URL)" $(TLS_ARGS) + +test-rolling: + bash scripts/verify-rolling.sh diff --git a/REPORT.md b/REPORT.md index c2679005..15ef4383 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,98 @@ -# Отчёт — лабораторная 3 +# Отчёт по лабораторной работе 3 — балансировка реплик мессенджера -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор / группа: Badradine Ali / BVT2302 +- Целевая оценка: 4 (выполнены требования на оценки 3 и 4) +- Исследовательский трек на оценку 5: не заявлен +- Исходный проект ЛР 2: Badradine/mtusi2026lab2, ветка master, коммит 39277c14677fe8b3f362022af069d4e7a68f8158 +- Коммит / запрос на слияние: заполнить после коммита и открытия PR для ЛР 3 +- Источники и помощь: спецификация Docker Compose Deploy; документация NGINX по upstream и proxy; требования и публичные тесты ЛР 3; помощь OpenAI Codex при реализации и проверке. Студент должен понимать и уметь защитить принятые решения. -## Запуск из чистого clone +## Клонирование и запуск с нуля -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Требования: Git, Docker Desktop с Linux-контейнерами и Compose v2, PowerShell для создания локальных файлов секретов, WSL/Ubuntu с Python 3.12 и GNU Make для команд тестирования. Используйте только синтетические тестовые данные. -## Архитектура и решения +В PowerShell: -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +~~~powershell +git clone https://gitea.privcloud.tech/Badradine/mtusi2026lab3.git +Set-Location .\mtusi2026lab3 +Copy-Item .env.example .env +.\scripts\create-secrets.ps1 +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build --scale api=2 +docker compose --env-file .env ps +~~~ -## Доказательства критериев +Одноразовый сервис migrate применяет версионированные миграции, удерживая блокировку транзакции PostgreSQL. Реплики API запускаются только после успешного завершения миграции. Публичная точка входа: http://localhost:8080. Порт на хост публикует только NGINX и привязывает его к 127.0.0.1. -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +В WSL, находясь в каталоге репозитория, сначала разрешите запуск служебных скриптов: chmod +x scripts/*.sh. Затем выполните: + +~~~sh +make check +make validate +make test BASE_URL=http://localhost:8080 +make test-idempotency BASE_URL=http://localhost:8080 +make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8080 +~~~ + +Чтобы проверить переключение при параллельной записи, выполните проверку дважды, восстанавливая остановленную реплику между запусками. Учитывайте оба запуска только если в evidence/stopped-replicas.txt указаны два разных ID экземпляров: + +~~~sh +bash scripts/verify-failover.sh replica-run-1 +bash scripts/verify-failover.sh replica-run-2 +~~~ + +Чтобы проверить последовательную замену реплик во время генерации нагрузки: + +~~~sh +make test-rolling +~~~ + +Служебные скрипты сохраняют тома. Команда docker compose down останавливает стек, не удаляя данные. Удаляйте тома только если намеренно хотите стереть локальные данные лабораторной работы. + +## Архитектура и принятые решения + +~~~text +Клиент -> NGINX :8080 -> 2 реплики API -> общие PostgreSQL и Redis +~~~ + +В проект перенесена реализация ЛР 2 из актуальной ветки Gitea: хеши паролей Argon2id, вход Basic, непрозрачные Bearer-сессии в Redis, пользователи/чаты/участники/сообщения в PostgreSQL, постраничная навигация по ключу, ограниченные пулы и тайм-ауты, версионированные миграции. В ЛР 3 добавлена общая таблица результатов идемпотентности без изменения прежних таблиц и конечных точек API. + +NGINX распределяет запросы по алгоритму round-robin без закрепления клиента за одной репликой. DNS Docker обновляется раз в секунду; отказавший upstream после первой ошибки исключается на две секунды. Тайм-аут подключения — одна секунда. Ожидаемое время исключения отказавшей реплики составляет примерно до трёх секунд (одно обновление DNS и одна попытка подключения); измеренные значения обнаружения отказа и восстановления приведены ниже. + +Каждый процесс API возвращает имя контейнера как постоянный X-Instance-Id. Проверка готовности API проверяет PostgreSQL и Redis; проверка работоспособности API выполняется каждые три секунды с тайм-аутом две секунды. NGINX обнаруживает отказ upstream пассивно. При получении SIGTERM Uvicorn перестаёт принимать соединения и ждёт до пяти секунд завершения активных запросов; Compose предоставляет восемь секунд до принудительного завершения. Тайм-ауты отправки и чтения NGINX — пять секунд. + +Область действия идемпотентности: (аутентифицированный пользователь, POST, путь сообщения чата, ключ). Допустимы ASCII-ключи [A-Za-z0-9._:-]{1,128}. Проверенный JSON-запрос приводится к каноническому виду и хешируется SHA-256. Уникальное ограничение PostgreSQL разрешает гонку параллельных вставок между репликами. Сообщение и запись JSON-ответа фиксируются одной транзакцией; при ошибке транзакции не сохраняется ни то ни другое. Точный повтор в течение 24 часов возвращает тот же ответ 201 и то же сообщение; запрос с изменённым телом получает 409. После окончания срока хранения ключ можно использовать повторно при следующем запросе с этим ключом. + +В памяти API не хранится состояние, от которого зависит корректность сессий, сообщений или идемпотентности. В Compose не задан container_name; сервис API запущен в двух репликах. Тома PostgreSQL и Redis используются только соответствующими хранилищами. Для каждого сервиса заданы ограничения CPU и памяти. Порты PostgreSQL и Redis не публикуются на хост. + +Миграция развёртывается один раз и только добавляет новое. Миграция ЛР 3 создаёт таблицу идемпотентности и индекс; предыдущая версия API может продолжать обслуживать запросы во время добавления новой версии. Для более сложных изменений схемы потребуется миграция expand/contract и отдельно измеренное окно совместимости. + +## Подтверждения выполнения требований на оценку 4 + +Результаты ниже получены на запущенном стеке. Полный вывод команд и агрегаты нагрузки находятся в каталоге evidence/. Цели Make следует запускать в WSL/Ubuntu: Makefile использует python3 и команды POSIX shell. + +| Критерий | Команда / сценарий | Полученный результат | Подтверждение | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Публичный контракт API, включая конечные точки ЛР 2 | python tests/smoke.py --base-url http://localhost:8080 | PASS после последнего перезапуска с проверкой сохранности данных; все сервисы работоспособны | evidence/smoke.txt | +| Две реплики и параллельные POST одного сообщения с одинаковым ключом | python tests/idempotency_concurrency.py --base-url http://localhost:8080 | PASS: 24 запроса, 12 рабочих потоков, обнаружены 2 реплики, один ID сообщения и одна сохранённая копия | evidence/idempotency.txt | +| Сохранность данных после перезапуска API, Redis и PostgreSQL | python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://localhost:8080 | PASS: подтверждённое сообщение и существующая сессия остались доступны; ручной перезапуск записан в журнал | evidence/persistence.txt, evidence/persistence-hook.log | +| Переключение с реплики 46c9e552d0a0 | bash scripts/verify-failover.sh replica-run-2 | PASS: 51 успешная запись в сценарии, 0 неудачных попыток, первое восстановление за 1,897 с. Параллельная нагрузка: 1 123 успешных / 0 неудачных запроса, 27,902 успешного запроса/с, p50 109,335 мс, p95 380,847 мс, p99 509,395 мс | evidence/failover-replica-run-2.log, evidence/failover-replica-run-2-load.json, evidence/stopped-replicas.txt | +| Переключение с реплики 3375d99fba8b | bash scripts/verify-failover.sh replica-run-3 (первый запуск с другим ID экземпляра) | PASS: 50 успешных записей в сценарии, 0 неудачных попыток, первое восстановление за 1,955 с. Параллельная нагрузка: 1 162 успешных / 0 неудачных запроса, 28,919 успешного запроса/с, p50 107,255 мс, p95 352,709 мс, p99 439,816 мс | evidence/failover-distinct-3375.log, evidence/failover-distinct-3375-load.json, evidence/stopped-replicas.txt | +| Последовательная замена реплик под нагрузкой | bash scripts/verify-rolling.sh (последний запуск) | PASS: старые контейнеры API заменены по одному; 2 новые реплики работоспособны (revision=roll-20261110095038). Нагрузка 60,079 с: 2 881 успешный / 2 неудачных запроса, 0,0694% ошибок, 47,953 успешного запроса/с, p50 83,439 мс, p95 198,871 мс, p99 289,461 мс | evidence/rolling-update.log, evidence/rolling-update-load.json | +| Внутренние порты API, локальная точка входа и ограничения ресурсов | docker compose config и проверка запущенных сервисов | PASS: только LB публикует 127.0.0.1:8080; порты API доступны только внутри сети; для каждого сервиса заданы ограничения CPU и памяти | evidence/runtime-config.txt | +| Проверки структуры без запуска, smoke-тест и OpenAPI | make check, make test, validate_openapi.py, docker compose config --quiet | PASS в WSL/Ubuntu и PowerShell | evidence/make-check.log, evidence/make-test.log, evidence/implementation-checks.txt | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +Результаты переключения с разными экземплярами — это более ранние запуски для ID 46c9e552d0a0 и 3375d99fba8b, записанные в evidence/stopped-replicas.txt соответственно в 2026-11-06T21:35:34Z и 2026-11-06T21:38:58Z. Поздние повторные запуски после последовательной замены выбрали экземпляр 74e4faa7a0f1 дважды; они сохранены в файлах запусков 1 и 3, но не считаются подтверждением переключения между двумя разными репликами. -## Эксперименты и отказы +Последняя проверка последовательной замены завершилась с двумя работоспособными репликами; параллельная нагрузка зафиксировала 2 881 успешный и два неудачных запроса. Результат приведён без исключений. Генератор нагрузки работает по замкнутому циклу с параллелизмом 4; это небольшая демонстрация, а не проверка производительности для промышленной эксплуатации. Процентили рассчитаны только по успешным запросам. -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Во время этих запусков не записывались выделенные Docker Desktop ресурсы CPU/ОЗУ и характеристики компьютера. Ограничения сервисов Compose указаны в compose.yaml. Не следует использовать результаты этого ноутбука как оценку производительности в промышленной среде. -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +## Эксперименты и сбои -## Ограничения и следующие шаги +Нагрузка при проверке переключения длилась 40 секунд с параллелизмом 4; последняя проверка последовательной замены длилась 60,079 секунды с параллелизмом 4. Точные успешные запросы в секунду, число и доля ошибок, задержки p50/p95/p99 и время первого восстановления приведены в таблице и JSON-файлах. Ограничения сервисов: PostgreSQL — 1 CPU / 1 ГиБ; Redis — 0,25 CPU / 256 МиБ; миграция — 0,25 CPU / 256 МиБ; каждая реплика API — 0,50 CPU / 512 МиБ; NGINX — 0,25 CPU / 128 МиБ. -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +## Ограничения + +Решение демонстрирует восстановление после отказа одного процесса/контейнера API на одном Docker-хосте. Оно не обеспечивает устойчивость при отказе хоста, NGINX, PostgreSQL, Redis, сети или диска. NGINX обнаруживает недоступность upstream пассивно, поэтому первая попытка обращения к только что отказавшему узлу может завершиться ошибкой до его исключения из пула. AOF Redis с appendfsync everysec поддерживает обычные перезапуски с томом, но не гарантирует отсутствие потери данных при внезапном отказе хоста или диска. Нагрузочный тест — небольшой замкнутый сценарий, а не гарантия пропускной способности. Просроченные записи идемпотентности для ключей, которые больше не использовались, остаются в базе до запуска будущей задачи очистки. diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..ab072bdf --- /dev/null +++ b/compose.yaml @@ -0,0 +1,163 @@ +name: mtusi-messenger-lab3 + +services: + db: + image: postgres:16.4-alpine + restart: unless-stopped + environment: + POSTGRES_DB: messenger + POSTGRES_USER: messenger + POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password + secrets: + - postgres_password + volumes: + - postgres_data:/var/lib/postgresql/data + networks: + - backend + healthcheck: + test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"] + interval: 3s + timeout: 3s + retries: 20 + start_period: 5s + deploy: + resources: + limits: + cpus: "1.00" + memory: 1G + + redis: + image: redis:7.4.1-alpine + restart: unless-stopped + command: + - sh + - -ec + - exec redis-server --dir /data --appendonly yes --appendfsync everysec --save 60 1 --requirepass "$$(cat /run/secrets/redis_password)" + secrets: + - redis_password + volumes: + - redis_data:/data + networks: + - backend + healthcheck: + test: + - CMD-SHELL + - 'REDISCLI_AUTH="$$(cat /run/secrets/redis_password)" redis-cli ping | grep -q PONG' + interval: 3s + timeout: 3s + retries: 20 + start_period: 5s + deploy: + resources: + limits: + cpus: "0.25" + memory: 256M + + migrate: + image: mtusi-messenger-lab3-api:local + build: + context: . + dockerfile: Dockerfile + args: + BUILD_REVISION: ${BUILD_REVISION:-local} + command: ["python", "-m", "src.app.migrate"] + environment: + DATABASE_URL_FILE: /run/secrets/database_url + secrets: + - database_url + networks: + - backend + depends_on: + db: + condition: service_healthy + restart: "no" + deploy: + resources: + limits: + cpus: "0.25" + memory: 256M + + api: + image: mtusi-messenger-lab3-api:local + build: + context: . + dockerfile: Dockerfile + args: + BUILD_REVISION: ${BUILD_REVISION:-local} + restart: unless-stopped + stop_grace_period: 8s + environment: + APP_HOST: 0.0.0.0 + APP_PORT: 8080 + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + DATABASE_URL_FILE: /run/secrets/database_url + CACHE_URL_FILE: /run/secrets/cache_url + secrets: + - database_url + - cache_url + networks: + - backend + - edge + depends_on: + db: + condition: service_healthy + redis: + condition: service_healthy + migrate: + condition: service_completed_successfully + healthcheck: + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready',timeout=2)"] + interval: 3s + timeout: 2s + retries: 3 + start_period: 10s + deploy: + mode: replicated + replicas: 2 + resources: + limits: + cpus: "0.50" + memory: 512M + + lb: + image: nginx:1.28.0-alpine + restart: unless-stopped + ports: + - "127.0.0.1:${APP_PORT:-8080}:8080" + volumes: + - ./infra/nginx.conf:/etc/nginx/conf.d/default.conf:ro + networks: + - edge + depends_on: + api: + condition: service_healthy + healthcheck: + test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:8080/health/ready"] + interval: 3s + timeout: 2s + retries: 5 + start_period: 5s + deploy: + resources: + limits: + cpus: "0.25" + memory: 128M + +secrets: + postgres_password: + file: ./secrets/postgres_password + redis_password: + file: ./secrets/redis_password + database_url: + file: ./secrets/database_url + cache_url: + file: ./secrets/cache_url + +volumes: + postgres_data: + redis_data: + +networks: + backend: + internal: true + edge: diff --git a/evidence/failover-distinct-3375-load.json b/evidence/failover-distinct-3375-load.json new file mode 100644 index 00000000..d265add8 --- /dev/null +++ b/evidence/failover-distinct-3375-load.json @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 40.0, + "elapsed_seconds": 40.181, + "concurrency": 4, + "successful_requests": 1162, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 28.919, + "successful_latency_ms": { + "p50": 107.255, + "p95": 352.709, + "p99": 439.816 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} \ No newline at end of file diff --git a/evidence/failover-distinct-3375.log b/evidence/failover-distinct-3375.log new file mode 100644 index 00000000..10d77e12 --- /dev/null +++ b/evidence/failover-distinct-3375.log @@ -0,0 +1,7 @@ +Recorded original distinct-instance run before a later retry overwrote the run-3 log path. +Command: bash scripts/verify-failover.sh replica-run-3 +Console output: +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 50, "failed_attempts": 0, "first_recovery_seconds": 1.955} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. +Selected instance ID: 3375d99fba8b, recorded at 2026-11-06T21:38:58Z in evidence/stopped-replicas.txt. \ No newline at end of file diff --git a/evidence/failover-replica-run-1-load.json b/evidence/failover-replica-run-1-load.json new file mode 100644 index 00000000..c1c09bef --- /dev/null +++ b/evidence/failover-replica-run-1-load.json @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 40.0, + "elapsed_seconds": 40.106, + "concurrency": 4, + "successful_requests": 1153, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 28.749, + "successful_latency_ms": { + "p50": 109.552, + "p95": 339.41, + "p99": 461.6 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/failover-replica-run-1-load.log b/evidence/failover-replica-run-1-load.log new file mode 100644 index 00000000..c1c09bef --- /dev/null +++ b/evidence/failover-replica-run-1-load.log @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 40.0, + "elapsed_seconds": 40.106, + "concurrency": 4, + "successful_requests": 1153, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 28.749, + "successful_latency_ms": { + "p50": 109.552, + "p95": 339.41, + "p99": 461.6 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/failover-replica-run-1.log b/evidence/failover-replica-run-1.log new file mode 100644 index 00000000..646ca2ee --- /dev/null +++ b/evidence/failover-replica-run-1.log @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 50, "failed_attempts": 0, "first_recovery_seconds": 1.927} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/failover-replica-run-2-load.json b/evidence/failover-replica-run-2-load.json new file mode 100644 index 00000000..9a12f207 --- /dev/null +++ b/evidence/failover-replica-run-2-load.json @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 40.0, + "elapsed_seconds": 40.248, + "concurrency": 4, + "successful_requests": 1123, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 27.902, + "successful_latency_ms": { + "p50": 109.335, + "p95": 380.847, + "p99": 509.395 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/failover-replica-run-2-load.log b/evidence/failover-replica-run-2-load.log new file mode 100644 index 00000000..9a12f207 --- /dev/null +++ b/evidence/failover-replica-run-2-load.log @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 40.0, + "elapsed_seconds": 40.248, + "concurrency": 4, + "successful_requests": 1123, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 27.902, + "successful_latency_ms": { + "p50": 109.335, + "p95": 380.847, + "p99": 509.395 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/failover-replica-run-2.log b/evidence/failover-replica-run-2.log new file mode 100644 index 00000000..616a6a16 --- /dev/null +++ b/evidence/failover-replica-run-2.log @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 51, "failed_attempts": 0, "first_recovery_seconds": 1.897} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/failover-replica-run-3-load.json b/evidence/failover-replica-run-3-load.json new file mode 100644 index 00000000..4b3c2abe --- /dev/null +++ b/evidence/failover-replica-run-3-load.json @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 40.0, + "elapsed_seconds": 40.092, + "concurrency": 4, + "successful_requests": 1169, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 29.158, + "successful_latency_ms": { + "p50": 107.96, + "p95": 330.054, + "p99": 483.46 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/failover-replica-run-3-load.log b/evidence/failover-replica-run-3-load.log new file mode 100644 index 00000000..4b3c2abe --- /dev/null +++ b/evidence/failover-replica-run-3-load.log @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 40.0, + "elapsed_seconds": 40.092, + "concurrency": 4, + "successful_requests": 1169, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 29.158, + "successful_latency_ms": { + "p50": 107.96, + "p95": 330.054, + "p99": 483.46 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/failover-replica-run-3.log b/evidence/failover-replica-run-3.log new file mode 100644 index 00000000..0a54bf50 --- /dev/null +++ b/evidence/failover-replica-run-3.log @@ -0,0 +1,3 @@ +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 50, "failed_attempts": 0, "first_recovery_seconds": 1.672} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. diff --git a/evidence/failover-rr-after-lb-recreate-load.json b/evidence/failover-rr-after-lb-recreate-load.json new file mode 100644 index 00000000..4b78dbb2 --- /dev/null +++ b/evidence/failover-rr-after-lb-recreate-load.json @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 40.0, + "elapsed_seconds": 40.143, + "concurrency": 4, + "successful_requests": 1686, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 42.0, + "successful_latency_ms": { + "p50": 90.842, + "p95": 202.354, + "p99": 290.757 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/idempotency.txt b/evidence/idempotency.txt new file mode 100644 index 00000000..80e97269 --- /dev/null +++ b/evidence/idempotency.txt @@ -0,0 +1,3 @@ +Command: python tests/idempotency_concurrency.py --base-url http://localhost:8080 +Console output: +{"parallel_requests": 24, "workers": 12, "replicas_observed": 2, "unique_message_ids": 1, "stored_copies": 1, "result": "PASS"} \ No newline at end of file diff --git a/evidence/implementation-checks.txt b/evidence/implementation-checks.txt new file mode 100644 index 00000000..1cf95edb --- /dev/null +++ b/evidence/implementation-checks.txt @@ -0,0 +1,18 @@ +Lab 3 checks and runtime evidence + +Offline checks: +- python scripts/check_contract.py: PASS (structure, local references and Python syntax; does not run the application). +- python -m compileall -q src tests scripts: PASS, exit code 0. +- python scripts/validate_openapi.py: PASS, full OpenAPI 3.1 / JSON Schema validation. +- docker compose --env-file .env config --quiet: PASS. +- Configuration inspection: two API replicas; only loopback LB port is published; API ports are private; all five services have CPU/RAM limits. + +Runtime checks: +- Public smoke: PASS after the final persistence restart; see evidence/smoke.txt. +- Concurrent idempotency: PASS; 24 requests, 12 workers, 2 replicas, one stored message; see evidence/idempotency.txt. +- Persistence: PASS; confirmed data and existing session survived full-store restart; action scope is logged in evidence/persistence-hook.log. +- Failover: PASS for distinct API instance IDs 46c9e552d0a0 and 3375d99fba8b. The later repeated run selected 74e4faa7a0f1 twice and is not counted as second-replica evidence. +- Rolling update: PASS, with two new healthy replicas at completion. Latest 60-second concurrent workload recorded 1 failed request out of 1,055 total; see evidence/rolling-update-load.json. + +Make targets must run in WSL/Ubuntu, where python3 and a POSIX shell are available. Windows PowerShell make attempts are not application test failures. +Load tests are small closed-loop demonstrations. Host hardware and Docker Desktop allocation were not recorded; no capacity guarantee is claimed. \ No newline at end of file diff --git a/evidence/make-check.log b/evidence/make-check.log new file mode 100644 index 00000000..b39e72a8 --- /dev/null +++ b/evidence/make-check.log @@ -0,0 +1,3 @@ +Command: make check +python3 scripts/check_contract.py +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. \ No newline at end of file diff --git a/evidence/make-test.log b/evidence/make-test.log new file mode 100644 index 00000000..d3505672 --- /dev/null +++ b/evidence/make-test.log @@ -0,0 +1,3 @@ +Command: make test BASE_URL=http://localhost:8080 +python3 tests/smoke.py --base-url "http://localhost:8080" +PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. \ No newline at end of file diff --git a/evidence/persistence-hook.log b/evidence/persistence-hook.log new file mode 100644 index 00000000..a3f7f4d3 --- /dev/null +++ b/evidence/persistence-hook.log @@ -0,0 +1,26 @@ + Container mtusi-messenger-lab3-api-3 Stopping + Container mtusi-messenger-lab3-api-4 Stopping + Container mtusi-messenger-lab3-api-4 Stopped + Container mtusi-messenger-lab3-api-3 Stopped + Container mtusi-messenger-lab3-redis-1 Stopping + Container mtusi-messenger-lab3-db-1 Stopping + Container mtusi-messenger-lab3-db-1 Stopped + Container mtusi-messenger-lab3-redis-1 Stopped + Container mtusi-messenger-lab3-redis-1 Starting + Container mtusi-messenger-lab3-db-1 Starting + Container mtusi-messenger-lab3-db-1 Started + Container mtusi-messenger-lab3-redis-1 Started + Container mtusi-messenger-lab3-db-1 Waiting + Container mtusi-messenger-lab3-db-1 Healthy + Container mtusi-messenger-lab3-migrate-1 Starting + Container mtusi-messenger-lab3-migrate-1 Started + Container mtusi-messenger-lab3-redis-1 Waiting + Container mtusi-messenger-lab3-migrate-1 Waiting + Container mtusi-messenger-lab3-db-1 Waiting + Container mtusi-messenger-lab3-redis-1 Healthy + Container mtusi-messenger-lab3-db-1 Healthy + Container mtusi-messenger-lab3-migrate-1 Exited + Container mtusi-messenger-lab3-api-4 Starting + Container mtusi-messenger-lab3-api-4 Started + Container mtusi-messenger-lab3-api-3 Starting + Container mtusi-messenger-lab3-api-3 Started diff --git a/evidence/persistence.txt b/evidence/persistence.txt new file mode 100644 index 00000000..2758e2d1 --- /dev/null +++ b/evidence/persistence.txt @@ -0,0 +1,4 @@ +Command: python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://localhost:8080 +Console output: +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. \ No newline at end of file diff --git a/evidence/rolling-update-load.json b/evidence/rolling-update-load.json new file mode 100644 index 00000000..6436a284 --- /dev/null +++ b/evidence/rolling-update-load.json @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 60.0, + "elapsed_seconds": 60.079, + "concurrency": 4, + "successful_requests": 2881, + "failed_requests": 2, + "error_ratio": 0.000694, + "successful_rps": 47.953, + "successful_latency_ms": { + "p50": 83.439, + "p95": 198.871, + "p99": 289.461 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/rolling-update-load.log b/evidence/rolling-update-load.log new file mode 100644 index 00000000..6436a284 --- /dev/null +++ b/evidence/rolling-update-load.log @@ -0,0 +1,17 @@ +{ + "lab": 3, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 60.0, + "elapsed_seconds": 60.079, + "concurrency": 4, + "successful_requests": 2881, + "failed_requests": 2, + "error_ratio": 0.000694, + "successful_rps": 47.953, + "successful_latency_ms": { + "p50": 83.439, + "p95": 198.871, + "p99": 289.461 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/rolling-update.log b/evidence/rolling-update.log new file mode 100644 index 00000000..6005d676 --- /dev/null +++ b/evidence/rolling-update.log @@ -0,0 +1,183 @@ + Image mtusi-messenger-lab3-api:local Building + Image mtusi-messenger-lab3-api:local Building +#1 [internal] load local bake definitions +#1 reading from stdin 1.46kB done +#1 DONE 0.0s + +#2 [internal] load build definition from Dockerfile +#2 transferring dockerfile: 836B 0.0s done +#2 DONE 0.1s + +#3 [internal] load metadata for docker.io/library/python:3.12.6-slim-bookworm +#3 DONE 0.9s + +#4 [internal] load .dockerignore +#4 transferring context: 216B 0.0s done +#4 DONE 0.1s + +#5 [internal] load build context +#5 DONE 0.0s + +#6 [1/7] FROM docker.io/library/python:3.12.6-slim-bookworm@sha256:ad48727987b259854d52241fac3bc633574364867b8e20aec305e6e7f4028b26 +#6 resolve docker.io/library/python:3.12.6-slim-bookworm@sha256:ad48727987b259854d52241fac3bc633574364867b8e20aec305e6e7f4028b26 0.0s done +#6 DONE 0.1s + +#5 [internal] load build context +#5 transferring context: 1.16kB 0.2s done +#5 DONE 0.2s + +#7 [2/7] WORKDIR /app +#7 CACHED + +#8 [3/7] COPY requirements.txt ./ +#8 CACHED + +#9 [4/7] RUN pip install --no-cache-dir --requirement requirements.txt +#9 1.677 Collecting fastapi==0.115.0 (from -r requirements.txt (line 1)) +#9 2.013 Downloading fastapi-0.115.0-py3-none-any.whl.metadata (27 kB) +#9 2.130 Collecting uvicorn==0.30.6 (from uvicorn[standard]==0.30.6->-r requirements.txt (line 2)) +#9 2.189 Downloading uvicorn-0.30.6-py3-none-any.whl.metadata (6.6 kB) +#9 2.502 Collecting pydantic==2.9.2 (from -r requirements.txt (line 3)) +#9 2.563 Downloading pydantic-2.9.2-py3-none-any.whl.metadata (149 kB) +#9 3.452 Collecting SQLAlchemy==2.0.36 (from -r requirements.txt (line 4)) +#9 3.514 Downloading SQLAlchemy-2.0.36-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (9.7 kB) +#9 3.630 Collecting psycopg==3.2.3 (from psycopg[binary]==3.2.3->-r requirements.txt (line 5)) +#9 3.691 Downloading psycopg-3.2.3-py3-none-any.whl.metadata (4.3 kB) +#9 3.804 Collecting redis==5.2.0 (from -r requirements.txt (line 6)) +#9 3.868 Downloading redis-5.2.0-py3-none-any.whl.metadata (9.1 kB) +#9 3.957 Collecting argon2-cffi==23.1.0 (from -r requirements.txt (line 7)) +#9 4.023 Downloading argon2_cffi-23.1.0-py3-none-any.whl.metadata (5.2 kB) +#9 4.126 Collecting starlette<0.39.0,>=0.37.2 (from fastapi==0.115.0->-r requirements.txt (line 1)) +#9 4.187 Downloading starlette-0.38.6-py3-none-any.whl.metadata (6.0 kB) +#9 4.307 Collecting typing-extensions>=4.8.0 (from fastapi==0.115.0->-r requirements.txt (line 1)) +#9 4.371 Downloading typing_extensions-4.16.0-py3-none-any.whl.metadata (3.3 kB) +#9 4.456 Collecting click>=7.0 (from uvicorn==0.30.6->uvicorn[standard]==0.30.6->-r requirements.txt (line 2)) +#9 4.518 Downloading click-8.5.1-py3-none-any.whl.metadata (2.6 kB) +#9 4.584 Collecting h11>=0.8 (from uvicorn==0.30.6->uvicorn[standard]==0.30.6->-r requirements.txt (line 2)) +#9 4.649 Downloading h11-0.16.0-py3-none-any.whl.metadata (8.3 kB) +#9 4.720 Collecting annotated-types>=0.6.0 (from pydantic==2.9.2->-r requirements.txt (line 3)) +#9 4.779 Downloading annotated_types-0.8.0-py3-none-any.whl.metadata (15 kB) +#9 6.041 Collecting pydantic-core==2.23.4 (from pydantic==2.9.2->-r requirements.txt (line 3)) +#9 6.107 Downloading pydantic_core-2.23.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (6.6 kB) +#9 6.482 Collecting greenlet!=0.4.17 (from SQLAlchemy==2.0.36->-r requirements.txt (line 4)) +#9 6.547 Downloading greenlet-3.5.6-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.metadata (3.8 kB) +#9 6.625 Collecting argon2-cffi-bindings (from argon2-cffi==23.1.0->-r requirements.txt (line 7)) +#9 6.713 Downloading argon2_cffi_bindings-26.1.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl.metadata (7.5 kB) +#9 7.072 Collecting psycopg-binary==3.2.3 (from psycopg[binary]==3.2.3->-r requirements.txt (line 5)) +#9 7.161 Downloading psycopg_binary-3.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (2.8 kB) +#9 7.289 Collecting httptools>=0.5.0 (from uvicorn[standard]==0.30.6->-r requirements.txt (line 2)) +#9 7.357 Downloading httptools-0.9.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.metadata (3.5 kB) +#9 7.431 Collecting python-dotenv>=0.13 (from uvicorn[standard]==0.30.6->-r requirements.txt (line 2)) +#9 7.495 Downloading python_dotenv-1.2.4-py3-none-any.whl.metadata (29 kB) +#9 7.632 Collecting pyyaml>=5.1 (from uvicorn[standard]==0.30.6->-r requirements.txt (line 2)) +#9 7.693 Downloading pyyaml-6.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.metadata (2.4 kB) +#9 7.809 Collecting uvloop!=0.15.0,!=0.15.1,>=0.14.0 (from uvicorn[standard]==0.30.6->-r requirements.txt (line 2)) +#9 7.872 Downloading uvloop-0.23.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.metadata (5.1 kB) +#9 8.059 Collecting watchfiles>=0.13 (from uvicorn[standard]==0.30.6->-r requirements.txt (line 2)) +#9 8.156 Downloading watchfiles-1.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (4.9 kB) +#9 8.480 Collecting websockets>=10.4 (from uvicorn[standard]==0.30.6->-r requirements.txt (line 2)) +#9 8.551 Downloading websockets-17.4-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.metadata (6.3 kB) +#9 8.676 Collecting anyio<5,>=3.4.0 (from starlette<0.39.0,>=0.37.2->fastapi==0.115.0->-r requirements.txt (line 1)) +#9 8.737 Downloading anyio-4.16.0-py3-none-any.whl.metadata (4.7 kB) +#9 9.039 Collecting cffi>=1.0.1 (from argon2-cffi-bindings->argon2-cffi==23.1.0->-r requirements.txt (line 7)) +#9 9.102 Downloading cffi-2.1.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.metadata (2.5 kB) +#9 9.182 Collecting idna>=2.8 (from anyio<5,>=3.4.0->starlette<0.39.0,>=0.37.2->fastapi==0.115.0->-r requirements.txt (line 1)) +#9 9.247 Downloading idna-3.20-py3-none-any.whl.metadata (7.2 kB) +#9 9.328 Collecting pycparser (from cffi>=1.0.1->argon2-cffi-bindings->argon2-cffi==23.1.0->-r requirements.txt (line 7)) +#9 9.393 Downloading pycparser-3.12-py3-none-any.whl.metadata (9.7 kB) +#9 9.471 Downloading fastapi-0.115.0-py3-none-any.whl (94 kB) +#9 9.613 Downloading uvicorn-0.30.6-py3-none-any.whl (62 kB) +#9 9.704 Downloading pydantic-2.9.2-py3-none-any.whl (434 kB) +#9 9.996 Downloading SQLAlchemy-2.0.36-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.2 MB) +#9 11.62 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.2/3.2 MB 2.0 MB/s eta 0:00:00 +#9 11.68 Downloading psycopg-3.2.3-py3-none-any.whl (197 kB) +#9 11.86 Downloading redis-5.2.0-py3-none-any.whl (261 kB) +#9 12.08 Downloading argon2_cffi-23.1.0-py3-none-any.whl (15 kB) +#9 12.15 Downloading psycopg_binary-3.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.2 MB) +#9 14.42 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.2/4.2 MB 1.9 MB/s eta 0:00:00 +#9 14.48 Downloading pydantic_core-2.23.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.1 MB) +#9 15.49 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.1/2.1 MB 2.1 MB/s eta 0:00:00 +#9 15.60 Downloading annotated_types-0.8.0-py3-none-any.whl (13 kB) +#9 15.69 Downloading click-8.5.1-py3-none-any.whl (126 kB) +#9 15.80 Downloading greenlet-3.5.6-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (621 kB) +#9 16.09 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 621.4/621.4 kB 2.4 MB/s eta 0:00:00 +#9 16.15 Downloading h11-0.16.0-py3-none-any.whl (37 kB) +#9 16.24 Downloading httptools-0.9.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (552 kB) +#9 16.50 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 552.8/552.8 kB 2.2 MB/s eta 0:00:00 +#9 16.56 Downloading python_dotenv-1.2.4-py3-none-any.whl (23 kB) +#9 16.65 Downloading pyyaml-6.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (807 kB) +#9 17.07 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 807.9/807.9 kB 1.8 MB/s eta 0:00:00 +#9 17.13 Downloading starlette-0.38.6-py3-none-any.whl (71 kB) +#9 17.22 Downloading typing_extensions-4.16.0-py3-none-any.whl (45 kB) +#9 17.30 Downloading uvloop-0.23.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (4.5 MB) +#9 19.53 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.5/4.5 MB 2.1 MB/s eta 0:00:00 +#9 19.59 Downloading watchfiles-1.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (458 kB) +#9 19.85 Downloading websockets-17.4-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (226 kB) +#9 20.04 Downloading argon2_cffi_bindings-26.1.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl (26 kB) +#9 20.11 Downloading anyio-4.16.0-py3-none-any.whl (134 kB) +#9 20.28 Downloading cffi-2.1.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (221 kB) +#9 20.46 Downloading idna-3.20-py3-none-any.whl (69 kB) +#9 20.55 Downloading pycparser-3.12-py3-none-any.whl (62 kB) +#9 20.67 Installing collected packages: websockets, uvloop, typing-extensions, redis, pyyaml, python-dotenv, pycparser, psycopg-binary, idna, httptools, h11, greenlet, click, annotated-types, uvicorn, SQLAlchemy, pydantic-core, psycopg, cffi, anyio, watchfiles, starlette, pydantic, argon2-cffi-bindings, fastapi, argon2-cffi +#9 22.02 Successfully installed SQLAlchemy-2.0.36 annotated-types-0.8.0 anyio-4.16.0 argon2-cffi-23.1.0 argon2-cffi-bindings-26.1.0 cffi-2.1.1 click-8.5.1 fastapi-0.115.0 greenlet-3.5.6 h11-0.16.0 httptools-0.9.0 idna-3.20 psycopg-3.2.3 psycopg-binary-3.2.3 pycparser-3.12 pydantic-2.9.2 pydantic-core-2.23.4 python-dotenv-1.2.4 pyyaml-6.0.3 redis-5.2.0 starlette-0.38.6 typing-extensions-4.16.0 uvicorn-0.30.6 uvloop-0.23.0 watchfiles-1.3.0 websockets-17.4 +#9 22.02 WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable.It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning. +#9 22.38 +#9 22.38 [notice] A new release of pip is available: 24.2 -> 26.3 +#9 22.38 [notice] To update, run: pip install --upgrade pip +#9 DONE 23.3s + +#10 [5/7] COPY src/ ./src/ +#10 DONE 0.1s + +#11 [6/7] COPY migrations/ ./migrations/ +#11 DONE 0.1s + +#12 [7/7] RUN useradd --create-home --uid 10001 appuser +#12 DONE 0.4s + +#13 exporting to image +#13 exporting layers +#13 exporting layers 3.3s done +#13 exporting manifest sha256:9d09f8506e1eebad5711b7d16612dd66df9e6817ead50fead1b6f266cd41c9b6 0.0s done +#13 exporting config sha256:d2aaee67d64791fe5cfa3dae9dfe389fa098804bb996770e56840782acc27498 0.0s done +#13 exporting attestation manifest sha256:e2b74e3c3daef55ece1850952f42f20470ac087104e9d65a838c41424673190c +#13 exporting attestation manifest sha256:e2b74e3c3daef55ece1850952f42f20470ac087104e9d65a838c41424673190c 0.1s done +#13 exporting manifest list sha256:87c611efe8121200bbb1f8c6ba95a5d28d1f6901e190e7daff7da72efa052266 0.0s done +#13 naming to docker.io/library/mtusi-messenger-lab3-api:local +#13 naming to docker.io/library/mtusi-messenger-lab3-api:local done +#13 unpacking to docker.io/library/mtusi-messenger-lab3-api:local +#13 unpacking to docker.io/library/mtusi-messenger-lab3-api:local 0.8s done +#13 DONE 4.4s + +#14 resolving provenance for metadata file +#14 DONE 0.0s + Image mtusi-messenger-lab3-api:local Built + Container mtusi-messenger-lab3-api-7 Running + Container mtusi-messenger-lab3-api-9 Creating + Container mtusi-messenger-lab3-api-9 Created + Container mtusi-messenger-lab3-api-9 Starting + Container mtusi-messenger-lab3-api-9 Started + Container mtusi-messenger-lab3-api-8 Starting + Container mtusi-messenger-lab3-api-8 Started + Container mtusi-messenger-lab3-api-8 Running + Container mtusi-messenger-lab3-api-9 Running + Container mtusi-messenger-lab3-api-10 Creating + Container mtusi-messenger-lab3-api-10 Created + Container mtusi-messenger-lab3-api-10 Starting + Container mtusi-messenger-lab3-api-10 Started + Container mtusi-messenger-lab3-api-9 Running + Container mtusi-messenger-lab3-api-10 Running + Container mtusi-messenger-lab3-api-11 Creating + Container mtusi-messenger-lab3-api-11 Created + Container mtusi-messenger-lab3-api-11 Starting + Container mtusi-messenger-lab3-api-11 Started + Container mtusi-messenger-lab3-api-9 Running + Container mtusi-messenger-lab3-api-10 Running + Container mtusi-messenger-lab3-api-11 Stopping + Container mtusi-messenger-lab3-api-11 Stopped + Container mtusi-messenger-lab3-api-11 Removing + Container mtusi-messenger-lab3-api-11 Removed +PASS: old API containers were replaced one at a time; two new replicas are healthy. revision=roll-20261110095038 +NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS +mtusi-messenger-lab3-api-10 mtusi-messenger-lab3-api:local "uvicorn src.app.mai…" api 15 seconds ago Up 14 seconds (healthy) 8080/tcp +mtusi-messenger-lab3-api-9 mtusi-messenger-lab3-api:local "uvicorn src.app.mai…" api 24 seconds ago Up 24 seconds (healthy) 8080/tcp diff --git a/evidence/runtime-config.txt b/evidence/runtime-config.txt new file mode 100644 index 00000000..e9c03d15 --- /dev/null +++ b/evidence/runtime-config.txt @@ -0,0 +1,5 @@ +Compose configuration and runtime service inspection: +- Only lb publishes 127.0.0.1:8080 to container port 8080. +- API replicas expose port 8080 internally and have no host port binding. +- PostgreSQL and Redis have no host port binding. +- CPU/RAM limits are configured for all five services in compose.yaml. \ No newline at end of file diff --git a/evidence/smoke.txt b/evidence/smoke.txt new file mode 100644 index 00000000..aec5057d --- /dev/null +++ b/evidence/smoke.txt @@ -0,0 +1,5 @@ +Final post-restart verification +Command: docker compose --env-file .env ps +Observed: api-3 healthy; api-4 healthy; db healthy; redis healthy; lb healthy and publishing 127.0.0.1:8080. +Command: python3 tests/smoke.py --base-url http://localhost:8080 +Output: PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. \ No newline at end of file diff --git a/evidence/stopped-replicas.txt b/evidence/stopped-replicas.txt new file mode 100644 index 00000000..f7c79763 --- /dev/null +++ b/evidence/stopped-replicas.txt @@ -0,0 +1,8 @@ +2026-11-06T21:33:41Z 46c9e552d0a0 +2026-11-06T21:35:34Z 46c9e552d0a0 +2026-11-06T21:38:58Z 3375d99fba8b +2026-11-06T22:28:26Z 74e4faa7a0f1 +2026-11-06T22:29:20Z 74e4faa7a0f1 +2026-11-10T09:30:12Z 2f298bdf21b0 +2026-11-10T09:50:23Z 3895110fa377 +2026-11-12T17:44:23Z 80747c6466aa diff --git a/infra/nginx.conf b/infra/nginx.conf new file mode 100644 index 00000000..1afdf7ce --- /dev/null +++ b/infra/nginx.conf @@ -0,0 +1,28 @@ +upstream messenger_api { + zone messenger_api 64k; + resolver 127.0.0.11 valid=1s ipv6=off; + server api:8080 resolve max_fails=1 fail_timeout=2s; + keepalive 16; +} + +server { + listen 8080; + server_name _; + + client_max_body_size 1m; + proxy_connect_timeout 1s; + proxy_send_timeout 5s; + proxy_read_timeout 5s; + + location / { + proxy_pass http://messenger_api; + proxy_http_version 1.1; + proxy_set_header Connection ""; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_next_upstream error timeout http_502 http_503 http_504; + proxy_next_upstream_tries 2; + proxy_next_upstream_timeout 2s; + } +} diff --git a/migrations/001_initial.sql b/migrations/001_initial.sql new file mode 100644 index 00000000..f329638f --- /dev/null +++ b/migrations/001_initial.sql @@ -0,0 +1,36 @@ +CREATE TABLE users ( + id UUID PRIMARY KEY, + username VARCHAR(32) NOT NULL UNIQUE + CHECK (username ~ '^[a-z0-9_]{3,32}$'), + display_name VARCHAR(100) NOT NULL + CHECK (char_length(display_name) BETWEEN 1 AND 100 AND btrim(display_name) <> ''), + password_hash TEXT NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP +); + +CREATE TABLE chats ( + id UUID PRIMARY KEY, + title VARCHAR(100) NOT NULL + CHECK (char_length(title) BETWEEN 1 AND 100 AND btrim(title) <> ''), + created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP +); + +CREATE TABLE chat_members ( + chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE, + user_id UUID NOT NULL REFERENCES users(id) ON DELETE RESTRICT, + PRIMARY KEY (chat_id, user_id) +); +CREATE INDEX chat_members_user_id_idx ON chat_members(user_id, chat_id); + +CREATE TABLE messages ( + id UUID PRIMARY KEY, + chat_id UUID NOT NULL, + sender_id UUID NOT NULL, + text VARCHAR(4000) NOT NULL + CHECK (char_length(text) BETWEEN 1 AND 4000 AND btrim(text) <> ''), + created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP, + CONSTRAINT messages_sender_is_chat_member_fk + FOREIGN KEY (chat_id, sender_id) + REFERENCES chat_members(chat_id, user_id) ON DELETE CASCADE +); +CREATE INDEX messages_history_idx ON messages(chat_id, created_at, id); diff --git a/migrations/002_idempotency.sql b/migrations/002_idempotency.sql new file mode 100644 index 00000000..231eb768 --- /dev/null +++ b/migrations/002_idempotency.sql @@ -0,0 +1,16 @@ +CREATE TABLE idempotency_records ( + id UUID PRIMARY KEY, + user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, + method VARCHAR(8) NOT NULL, + path VARCHAR(200) NOT NULL, + idempotency_key VARCHAR(128) NOT NULL, + request_hash CHAR(64) NOT NULL, + response_body JSONB NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP, + expires_at TIMESTAMPTZ NOT NULL, + CONSTRAINT idempotency_records_scope_key_uq + UNIQUE (user_id, method, path, idempotency_key), + CHECK (method = 'POST'), + CHECK (char_length(idempotency_key) BETWEEN 1 AND 128) +); +CREATE INDEX idempotency_records_expires_at_idx ON idempotency_records(expires_at); diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..4c47f731 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,7 @@ +fastapi==0.115.0 +uvicorn[standard]==0.30.6 +pydantic==2.9.2 +SQLAlchemy==2.0.36 +psycopg[binary]==3.2.3 +redis==5.2.0 +argon2-cffi==23.1.0 diff --git a/scripts/create-secrets.ps1 b/scripts/create-secrets.ps1 new file mode 100644 index 00000000..9f8f54d7 --- /dev/null +++ b/scripts/create-secrets.ps1 @@ -0,0 +1,33 @@ +$ErrorActionPreference = 'Stop' +$repo = Split-Path -Parent $PSScriptRoot +$secretDir = Join-Path $repo 'secrets' +New-Item -ItemType Directory -Path $secretDir -Force | Out-Null +$secretNames = @('postgres_password', 'redis_password', 'database_url', 'cache_url') +$existing = @($secretNames | Where-Object { Test-Path -LiteralPath (Join-Path $secretDir $_) }) +if ($existing.Count -eq $secretNames.Count) { + Write-Output 'All local secret files already exist; they were left unchanged.' + return +} +if ($existing.Count -gt 0) { + throw 'Some but not all local secret files exist. Resolve them manually; this script will not rotate credentials.' +} + +function New-Secret { + $bytes = New-Object byte[] 32 + [System.Security.Cryptography.RandomNumberGenerator]::Fill($bytes) + return [Convert]::ToBase64String($bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_') +} + +$postgresPassword = New-Secret +$redisPassword = New-Secret +$files = @{ + postgres_password = $postgresPassword + redis_password = $redisPassword + database_url = "postgresql+psycopg://messenger:$postgresPassword@db:5432/messenger" + cache_url = "redis://:$redisPassword@redis:6379/0" +} +foreach ($name in $secretNames) { + $path = Join-Path $secretDir $name + [System.IO.File]::WriteAllText($path, $files[$name], [System.Text.UTF8Encoding]::new($false)) +} +Write-Output 'Local Postgres and Redis credentials created under secrets/. Values were not displayed.' diff --git a/scripts/recover-api.sh b/scripts/recover-api.sh new file mode 100755 index 00000000..06b8c45e --- /dev/null +++ b/scripts/recover-api.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "$0")/.." +docker compose start api >/dev/null +deadline=$((SECONDS + 60)) +while (( SECONDS < deadline )); do + healthy=0 + for container_id in $(docker compose ps -q api); do + state=$(docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' "$container_id" 2>/dev/null || true) + [[ "$state" == healthy ]] && healthy=$((healthy + 1)) + done + if (( healthy >= 2 )) && curl --fail --silent http://localhost:8080/health/ready >/dev/null; then + printf 'PASS: two API replicas are healthy through the load balancer.\n' + exit 0 + fi + sleep 1 +done +printf 'API replicas did not recover within 60 seconds.\n' >&2 +docker compose ps +exit 1 diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..4649d356 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env sh +set -eu +cd "$(dirname "$0")/.." + +# Stop the API before its state stores; named volumes are left intact. +docker compose stop api redis db +docker compose start db redis + +attempt=0 +until docker compose exec -T db pg_isready -U messenger -d messenger >/dev/null 2>&1 \ + && docker compose exec -T redis sh -ec 'REDISCLI_AUTH="$(cat /run/secrets/redis_password)" redis-cli ping | grep -q PONG' >/dev/null 2>&1; do + attempt=$((attempt + 1)) + if [ "$attempt" -ge 60 ]; then + echo 'Database/cache did not become ready within 60 seconds.' >&2 + exit 1 + fi + sleep 1 +done + +docker compose start api diff --git a/scripts/rolling-update.sh b/scripts/rolling-update.sh new file mode 100755 index 00000000..66acbb9d --- /dev/null +++ b/scripts/rolling-update.sh @@ -0,0 +1,49 @@ +#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "$0")/.." +image=mtusi-messenger-lab3-api:local +revision="roll-$(date -u +%Y%m%d%H%M%S)" + +docker compose build --build-arg "BUILD_REVISION=$revision" api +new_image=$(docker image inspect --format '{{.Id}}' "$image") +old_ids=$(docker compose ps --all -q api) +[[ -n "$old_ids" ]] || { printf 'No API containers found.\n' >&2; exit 1; } + +count_new_healthy() { + for container_id in $(docker compose ps --all -q api); do + image_id=$(docker inspect --format '{{.Image}}' "$container_id" 2>/dev/null || true) + state=$(docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' "$container_id" 2>/dev/null || true) + if [[ "$image_id" == "$new_image" && "$state" == healthy ]]; then printf '1\n'; fi + done | awk 'END { print NR + 0 }' +} + +wait_new_healthy() { + expected=$1 + deadline=$((SECONDS + 90)) + while (( SECONDS < deadline )); do + actual=$(count_new_healthy) + if (( actual >= expected )); then return 0; fi + sleep 1 + done + printf 'Only %s new replicas became healthy; expected %s.\n' "$(count_new_healthy)" "$expected" >&2 + docker compose ps --all + return 1 +} + +docker compose up -d --no-deps --no-recreate --scale api=3 api +wait_new_healthy 1 +new_count=1 +for container_id in $old_ids; do + image_id=$(docker inspect --format '{{.Image}}' "$container_id" 2>/dev/null || true) + if [[ "$image_id" != "$new_image" ]]; then + docker stop --time 6 "$container_id" >/dev/null + docker rm "$container_id" >/dev/null + docker compose up -d --no-deps --no-recreate --scale api=3 api + new_count=$((new_count + 1)) + wait_new_healthy "$new_count" + fi +done +docker compose up -d --no-deps --no-recreate --scale api=2 api +wait_new_healthy 2 +printf 'PASS: old API containers were replaced one at a time; two new replicas are healthy. revision=%s\n' "$revision" +docker compose ps api diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100755 index 00000000..e0114f44 --- /dev/null +++ b/scripts/stop-one.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "$0")/.." +: "${TARGET_INSTANCE_ID:?TARGET_INSTANCE_ID is required}" + +for container_id in $(docker compose ps -q api); do + hostname=$(docker inspect --format '{{.Config.Hostname}}' "$container_id") + if [[ "$hostname" == "$TARGET_INSTANCE_ID" ]]; then + mkdir -p evidence + printf '%s %s\n' "$(date -u +%FT%TZ)" "$TARGET_INSTANCE_ID" >> evidence/stopped-replicas.txt + docker stop --time 6 "$container_id" >/dev/null + exit 0 + fi +done + +printf 'No running API container matches TARGET_INSTANCE_ID.\n' >&2 +exit 1 diff --git a/scripts/verify-failover.sh b/scripts/verify-failover.sh new file mode 100755 index 00000000..03bcd09f --- /dev/null +++ b/scripts/verify-failover.sh @@ -0,0 +1,21 @@ +#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "$0")/.." +run_name=${1:-run1} +mkdir -p evidence +bash scripts/recover-api.sh +load_json="evidence/failover-$run_name-load.json" +load_log="evidence/failover-$run_name-load.log" +failover_log="evidence/failover-$run_name.log" +python3 tests/load.py --duration 40 --concurrency 4 --output "$load_json" >"$load_log" 2>&1 & +load_pid=$! +sleep 2 +set +e +python3 tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://localhost:8080 2>&1 | tee "$failover_log" +scenario_status=${PIPESTATUS[0]} +set -e +if ! wait "$load_pid"; then + printf 'Background load scenario failed; inspect %s.\n' "$load_log" >&2 + exit 1 +fi +exit "$scenario_status" diff --git a/scripts/verify-rolling.sh b/scripts/verify-rolling.sh new file mode 100755 index 00000000..810c0c8f --- /dev/null +++ b/scripts/verify-rolling.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "$0")/.." +mkdir -p evidence +load_json=evidence/rolling-update-load.json +load_log=evidence/rolling-update-load.log +update_log=evidence/rolling-update.log +python3 tests/load.py --duration 60 --concurrency 4 --output "$load_json" >"$load_log" 2>&1 & +load_pid=$! +sleep 2 +set +e +bash scripts/rolling-update.sh 2>&1 | tee "$update_log" +update_status=${PIPESTATUS[0]} +set -e +if ! wait "$load_pid"; then + printf 'Background load scenario failed; inspect %s.\n' "$load_log" >&2 + exit 1 +fi +exit "$update_status" diff --git a/src/app/__init__.py b/src/app/__init__.py new file mode 100644 index 00000000..2f310d5d --- /dev/null +++ b/src/app/__init__.py @@ -0,0 +1 @@ +"""MTUSI Lab 2 API.""" diff --git a/src/app/db.py b/src/app/db.py new file mode 100644 index 00000000..01e1dbf5 --- /dev/null +++ b/src/app/db.py @@ -0,0 +1,19 @@ +from sqlalchemy import create_engine +from sqlalchemy.orm import sessionmaker + +from .settings import load_database_url + + +engine = create_engine( + load_database_url(), + pool_size=5, + max_overflow=5, + pool_timeout=3, + pool_recycle=1800, + pool_pre_ping=True, + connect_args={ + "connect_timeout": 3, + "options": "-c statement_timeout=5000", + }, +) +SessionLocal = sessionmaker(bind=engine, expire_on_commit=False) diff --git a/src/app/errors.py b/src/app/errors.py new file mode 100644 index 00000000..ecafd8a6 --- /dev/null +++ b/src/app/errors.py @@ -0,0 +1,23 @@ +from fastapi import Request +from fastapi.responses import JSONResponse + + +class ApiError(Exception): + def __init__(self, code: str, message: str, status: int, challenge: str | None = None): + super().__init__(message) + self.code = code + self.message = message + self.status = status + self.challenge = challenge + + +def error_response(request: Request, code: str, message: str, status: int, challenge: str | None = None): + request_id = getattr(request.state, "request_id", "unknown") + headers = {"X-Request-Id": request_id, "Cache-Control": "no-store"} + if challenge: + headers["WWW-Authenticate"] = challenge + return JSONResponse( + status_code=status, + headers=headers, + content={"error": {"code": code, "message": message, "request_id": request_id}}, + ) diff --git a/src/app/explain_history.py b/src/app/explain_history.py new file mode 100644 index 00000000..81a194c5 --- /dev/null +++ b/src/app/explain_history.py @@ -0,0 +1,71 @@ +"""Create 10,000 disposable rows and record the indexed keyset-page plan.""" +import json +import uuid + +from sqlalchemy import text + +from .db import engine + + +def run() -> None: + user_id = uuid.uuid4() + chat_id = uuid.uuid4() + plan_json = None + with engine.connect() as connection: + transaction = connection.begin() + try: + connection.execute( + text("INSERT INTO users(id, username, display_name, password_hash) " + "VALUES (:id, :username, 'Synthetic plan fixture', 'not-a-login-hash')"), + {"id": user_id, "username": "plan_" + uuid.uuid4().hex[:20]}, + ) + connection.execute( + text("INSERT INTO chats(id, title) VALUES (:id, 'Synthetic plan fixture')"), + {"id": chat_id}, + ) + connection.execute( + text("INSERT INTO chat_members(chat_id, user_id) VALUES (:chat_id, :user_id)"), + {"chat_id": chat_id, "user_id": user_id}, + ) + connection.execute( + text(""" + INSERT INTO messages(id, chat_id, sender_id, text, created_at) + SELECT gen_random_uuid(), :chat_id, :sender_id, + 'synthetic message ' || n::text, + TIMESTAMPTZ '2025-01-01 00:00:00+00' + n * INTERVAL '1 microsecond' + FROM generate_series(1, 10000) AS n + """), + {"chat_id": chat_id, "sender_id": user_id}, + ) + connection.exec_driver_sql("ANALYZE messages") + raw = connection.execute( + text(""" + EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) + SELECT id, chat_id, sender_id, text, created_at + FROM messages + WHERE chat_id = :chat_id + AND (created_at, id) > (TIMESTAMPTZ '2025-01-01 00:00:00+00', + '00000000-0000-0000-0000-000000000000'::uuid) + ORDER BY created_at, id + LIMIT 50 + """), + {"chat_id": chat_id}, + ).scalar_one() + plan_json = raw if isinstance(raw, list) else json.loads(raw) + finally: + transaction.rollback() + + document = plan_json[0] + + def contains_history_index(node: dict) -> bool: + if node.get("Index Name") == "messages_history_idx": + return True + return any(contains_history_index(child) for child in node.get("Plans", [])) + + if not contains_history_index(document["Plan"]): + raise SystemExit("Planner did not use messages_history_idx; inspect and revise the query/index.") + print(json.dumps(document, indent=2, sort_keys=True)) + + +if __name__ == "__main__": + run() diff --git a/src/app/main.py b/src/app/main.py new file mode 100644 index 00000000..e6bab8a7 --- /dev/null +++ b/src/app/main.py @@ -0,0 +1,527 @@ +import base64 +import binascii +from datetime import datetime, timedelta, timezone +import hashlib +import json +import logging +import re +import secrets +import socket +import uuid + +from argon2 import PasswordHasher, Type +from argon2.exceptions import InvalidHashError, VerificationError, VerifyMismatchError +from fastapi import FastAPI, Header, Request +from fastapi.exceptions import RequestValidationError +from fastapi.responses import JSONResponse +from redis import Redis +from redis.exceptions import RedisError +from sqlalchemy import and_, delete, func, or_, select, text, tuple_, update +from sqlalchemy.dialects.postgresql import insert as pg_insert +from sqlalchemy.exc import DBAPIError, OperationalError, TimeoutError as SQLAlchemyTimeoutError +from starlette.concurrency import run_in_threadpool +from starlette.exceptions import HTTPException as StarletteHTTPException + +from .db import SessionLocal, engine +from .errors import ApiError, error_response +from .models import Chat, ChatMember, IdempotencyRecord, Message, User +from .schemas import ( + ChatOut, + ChatPage, + CreateChat, + CreateMessage, + CreateUser, + Health, + MessageOut, + MessagePage, + SessionOut, + UserOut, +) +from .settings import load_settings + +settings = load_settings() + + +logging.basicConfig( + level=logging.INFO, + format="%(asctime)s %(levelname)s %(name)s %(message)s", +) +logger = logging.getLogger("messenger.api") +password_hasher = PasswordHasher( + time_cost=2, + memory_cost=19_456, + parallelism=1, + hash_len=32, + salt_len=16, + type=Type.ID, +) +DUMMY_PASSWORD_HASH = password_hasher.hash("dummy-password-for-timing-only") +redis_client = Redis.from_url( + settings.cache_url, + decode_responses=True, + socket_connect_timeout=2, + socket_timeout=2, + health_check_interval=30, +) + +app = FastAPI(title="MTUSI Messenger — Lab 3", version="1.3.0") + +BEARER_CHALLENGE = 'Bearer realm="messenger"' +BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"' +USERNAME_RE = re.compile(r"^[a-z0-9_]{3,32}$") +TOKEN_RE = re.compile(r"^[A-Za-z0-9_-]{43}$") +IDEMPOTENCY_KEY_RE = re.compile(r"^[A-Za-z0-9._:-]{1,128}$", re.ASCII) +# Docker assigns each container a stable hostname equal to its container ID. +# The load balancer forwards this value so tests can prove requests changed replicas. +INSTANCE_ID = socket.gethostname() + + +def _iso(value: datetime) -> str: + if value.tzinfo is None: + value = value.replace(tzinfo=timezone.utc) + return value.astimezone(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z") + + +def _user_out(user: User) -> dict: + return { + "id": str(user.id), + "username": user.username, + "display_name": user.display_name, + "created_at": _iso(user.created_at), + } + + +def _message_out(message: Message) -> dict: + return { + "id": str(message.id), + "chat_id": str(message.chat_id), + "sender_id": str(message.sender_id), + "text": message.text, + "created_at": _iso(message.created_at), + } + + +def _chat_out(session, chat: Chat) -> dict: + members = session.scalars( + select(ChatMember.user_id) + .where(ChatMember.chat_id == chat.id) + .order_by(ChatMember.user_id) + ).all() + return { + "id": str(chat.id), + "title": chat.title, + "member_ids": [str(member_id) for member_id in members], + "created_at": _iso(chat.created_at), + } + + +def _api_error(code: str, message: str, status: int, challenge: str | None = None) -> ApiError: + return ApiError(code, message, status, challenge) + + +def _unauthorized(challenge: str = BEARER_CHALLENGE) -> ApiError: + return _api_error("unauthorized", "Нет действительной идентификации", 401, challenge) + + +def _encode_cursor(payload: dict) -> str: + raw = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8") + return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=") + + +def _decode_cursor(value: str) -> dict: + try: + padded = value + ("=" * ((4 - len(value) % 4) % 4)) + raw = base64.b64decode(padded.encode("ascii"), altchars=b"-_", validate=True) + payload = json.loads(raw.decode("utf-8")) + if not isinstance(payload, dict): + raise ValueError("cursor must be an object") + return payload + except (ValueError, UnicodeError, binascii.Error, json.JSONDecodeError) as exc: + raise _api_error("invalid_request", "Неверный cursor", 400) from exc + + +def _cursor_position(payload: dict) -> tuple[datetime, uuid.UUID]: + try: + created_at = datetime.fromisoformat(payload["t"].replace("Z", "+00:00")) + if created_at.tzinfo is None: + raise ValueError("cursor time must include timezone") + item_id = uuid.UUID(payload["i"]) + return created_at.astimezone(timezone.utc), item_id + except (KeyError, TypeError, ValueError, AttributeError) as exc: + raise _api_error("invalid_request", "Неверный cursor", 400) from exc + + +def _session_key(token: str) -> str: + digest = hashlib.sha256(token.encode("ascii")).hexdigest() + return "session:v1:" + digest + + +def _parse_bearer(request: Request) -> str: + header = request.headers.get("authorization", "") + scheme, separator, token = header.partition(" ") + if scheme.lower() != "bearer" or not separator or not TOKEN_RE.fullmatch(token): + raise _unauthorized() + return token + + +def _load_session(token: str) -> dict: + value = redis_client.get(_session_key(token)) + if value is None: + raise _unauthorized() + try: + session = json.loads(value) + user_id = uuid.UUID(session["user_id"]) + expires_at = datetime.fromisoformat(session["expires_at"].replace("Z", "+00:00")) + if expires_at.tzinfo is None or datetime.now(timezone.utc) >= expires_at: + redis_client.delete(_session_key(token)) + raise _unauthorized() + return {"user_id": user_id, "expires_at": expires_at} + except ApiError: + raise + except (KeyError, TypeError, ValueError, AttributeError, json.JSONDecodeError): + redis_client.delete(_session_key(token)) + raise _unauthorized() from None + + +def _current_user(request: Request) -> tuple[User, str]: + token = _parse_bearer(request) + session_data = _load_session(token) + with SessionLocal() as session: + user = session.get(User, session_data["user_id"]) + if user is None: + redis_client.delete(_session_key(token)) + raise _unauthorized() + return user, token + + +def _parse_basic(header: str) -> tuple[str, str]: + scheme, separator, encoded = header.partition(" ") + if scheme.lower() != "basic" or not separator or not encoded: + raise _unauthorized(BASIC_CHALLENGE) + try: + decoded = base64.b64decode(encoded.encode("ascii"), validate=True).decode("utf-8") + username, password = decoded.split(":", 1) + except (UnicodeError, ValueError, binascii.Error): + raise _unauthorized(BASIC_CHALLENGE) from None + if not USERNAME_RE.fullmatch(username) or not password: + raise _unauthorized(BASIC_CHALLENGE) + return username, password + + +def _password_matches(password_hash: str, password: str) -> bool: + try: + return password_hasher.verify(password_hash, password) + except (VerifyMismatchError, VerificationError, InvalidHashError): + return False + + +def _create_session(username: str, password: str) -> dict: + with SessionLocal() as session: + user = session.scalar(select(User).where(User.username == username)) + stored_hash = user.password_hash if user is not None else DUMMY_PASSWORD_HASH + password_ok = _password_matches(stored_hash, password) + if user is None or not password_ok: + raise _unauthorized(BASIC_CHALLENGE) + user_payload = _user_out(user) + + expires_at = datetime.now(timezone.utc) + timedelta(seconds=settings.session_ttl_seconds) + for _ in range(3): + token = secrets.token_urlsafe(32) + stored_value = json.dumps( + {"user_id": user_payload["id"], "expires_at": _iso(expires_at)}, + separators=(",", ":"), + ) + if redis_client.set(_session_key(token), stored_value, ex=settings.session_ttl_seconds, nx=True): + return { + "token": token, + "token_type": "Bearer", + "expires_at": _iso(expires_at), + "user": user_payload, + } + logger.error("session_token_collision_limit_reached") + raise _api_error("unavailable", "Сервис временно недоступен", 503) + + +def _get_chat_for_member(session, chat_id: uuid.UUID, user_id: uuid.UUID) -> Chat | None: + return session.scalar( + select(Chat) + .join(ChatMember, ChatMember.chat_id == Chat.id) + .where(Chat.id == chat_id, ChatMember.user_id == user_id) + ) + + +@app.middleware("http") +async def request_metadata_middleware(request: Request, call_next): + request_id = str(uuid.uuid4()) + request.state.request_id = request_id + try: + response = await call_next(request) + except Exception as exc: + # Keep an unexpected failure bounded and ensure the API response still + # identifies the request and the replica that created it. + logger.error("internal_error request_id=%s type=%s", request_id, type(exc).__name__) + response = error_response(request, "internal_error", "Внутренняя ошибка", 500) + response.headers["X-Request-Id"] = request_id + response.headers["X-Instance-Id"] = INSTANCE_ID + return response + + +@app.exception_handler(ApiError) +async def handle_api_error(request: Request, exc: ApiError): + return error_response(request, exc.code, exc.message, exc.status, exc.challenge) + + +@app.exception_handler(RequestValidationError) +async def handle_validation_error(request: Request, _exc: RequestValidationError): + return error_response(request, "invalid_request", "Неверный запрос", 400) + + +@app.exception_handler(StarletteHTTPException) +async def handle_http_error(request: Request, exc: StarletteHTTPException): + if exc.status_code == 404: + return error_response(request, "not_found", "Объект не найден", 404) + return error_response(request, "invalid_request", "Неверный запрос", 400) + + +@app.exception_handler(OperationalError) +@app.exception_handler(SQLAlchemyTimeoutError) +async def handle_database_unavailable(request: Request, exc: Exception): + logger.warning("database_unavailable request_id=%s type=%s", request.state.request_id, type(exc).__name__) + return error_response(request, "unavailable", "Сервис временно недоступен", 503) + + +@app.exception_handler(RedisError) +async def handle_cache_unavailable(request: Request, exc: RedisError): + logger.warning("session_store_unavailable request_id=%s type=%s", request.state.request_id, type(exc).__name__) + return error_response(request, "unavailable", "Сервис временно недоступен", 503) + + +@app.exception_handler(DBAPIError) +async def handle_database_error(request: Request, exc: DBAPIError): + if exc.connection_invalidated: + logger.warning("database_connection_lost request_id=%s", request.state.request_id) + return error_response(request, "unavailable", "Сервис временно недоступен", 503) + logger.error("database_error request_id=%s type=%s", request.state.request_id, type(exc).__name__) + return error_response(request, "internal_error", "Внутренняя ошибка", 500) + + +@app.exception_handler(Exception) +async def handle_unexpected_error(request: Request, exc: Exception): + logger.error("internal_error request_id=%s type=%s", request.state.request_id, type(exc).__name__) + return error_response(request, "internal_error", "Внутренняя ошибка", 500) + + +@app.get("/health/live", response_model=Health) +def live(): + return {"status": "ok"} + + +@app.get("/health/ready", response_model=Health, responses={503: {"description": "Dependency unavailable"}}) +def ready(): + with SessionLocal() as session: + session.execute(text("SELECT 1")) + redis_client.ping() + return {"status": "ok"} + + +@app.post("/api/v1/users", response_model=UserOut, status_code=201) +def register_user(payload: CreateUser): + password_hash = password_hasher.hash(payload.password) + user = User(username=payload.username, display_name=payload.display_name, password_hash=password_hash) + try: + with SessionLocal.begin() as session: + session.add(user) + session.flush() + except DBAPIError as exc: + if getattr(getattr(exc, "orig", None), "sqlstate", None) == "23505": + raise _api_error("conflict", "username занят", 409) from exc + raise + return _user_out(user) + + +@app.post("/api/v1/auth/sessions", response_model=SessionOut, status_code=201) +async def create_session(request: Request): + if await request.body(): + raise _api_error("invalid_request", "Basic authentication must not include a body", 400) + username, password = _parse_basic(request.headers.get("authorization", "")) + return await run_in_threadpool(_create_session, username, password) + + +@app.delete("/api/v1/auth/sessions/current", status_code=204) +def revoke_session(request: Request): + _user, token = _current_user(request) + redis_client.delete(_session_key(token)) + return None + + +@app.get("/api/v1/users/me", response_model=UserOut) +def current_user(request: Request): + user, _token = _current_user(request) + return _user_out(user) + + +@app.post("/api/v1/chats", response_model=ChatOut, status_code=201) +def create_chat(payload: CreateChat, request: Request): + user, _token = _current_user(request) + member_ids = [uuid.UUID(value) for value in payload.member_ids] + if user.id not in member_ids: + raise _api_error("invalid_request", "Вызывающий должен входить в member_ids", 400) + + try: + with SessionLocal.begin() as session: + chat = Chat(title=payload.title) + session.add(chat) + session.flush() + session.add_all(ChatMember(chat_id=chat.id, user_id=member_id) for member_id in member_ids) + session.flush() + result = _chat_out(session, chat) + except DBAPIError as exc: + if getattr(getattr(exc, "orig", None), "sqlstate", None) in {"23503", "23505"}: + raise _api_error("invalid_request", "Неизвестный участник", 400) from exc + raise + return result + + +@app.get("/api/v1/chats", response_model=ChatPage) +def list_chats(request: Request, limit: int = 50, cursor: str | None = None): + user, _token = _current_user(request) + if limit < 1 or limit > 100: + raise _api_error("invalid_request", "limit вне диапазона", 400) + statement = ( + select(Chat) + .join(ChatMember, ChatMember.chat_id == Chat.id) + .where(ChatMember.user_id == user.id) + .order_by(Chat.created_at, Chat.id) + ) + if cursor is not None: + payload = _decode_cursor(cursor) + if payload.get("u") != str(user.id): + raise _api_error("invalid_request", "Неверный cursor", 400) + created_at, chat_id = _cursor_position(payload) + statement = statement.where(tuple_(Chat.created_at, Chat.id) > tuple_(created_at, chat_id)) + + with SessionLocal() as session: + chats = session.scalars(statement.limit(limit + 1)).all() + has_more = len(chats) > limit + page = chats[:limit] + items = [_chat_out(session, chat) for chat in page] + next_cursor = None + if has_more: + last = page[-1] + next_cursor = _encode_cursor({"u": str(user.id), "t": _iso(last.created_at), "i": str(last.id)}) + return {"items": items, "next_cursor": next_cursor} + + +@app.get("/api/v1/chats/{chat_id}", response_model=ChatOut) +def get_chat(chat_id: uuid.UUID, request: Request): + user, _token = _current_user(request) + with SessionLocal() as session: + chat = _get_chat_for_member(session, chat_id, user.id) + if chat is None: + raise _api_error("not_found", "Объект не найден", 404) + return _chat_out(session, chat) + + +@app.post("/api/v1/chats/{chat_id}/messages", response_model=MessageOut, status_code=201) +def create_message( + chat_id: uuid.UUID, + payload: CreateMessage, + request: Request, + idempotency_key: str | None = Header(default=None, alias="Idempotency-Key"), +): + user, _token = _current_user(request) + if idempotency_key is None or not IDEMPOTENCY_KEY_RE.fullmatch(idempotency_key): + raise _api_error("invalid_request", "Нужен корректный Idempotency-Key", 400) + if not payload.text.strip(): + raise _api_error("invalid_request", "Сообщение не может состоять только из пробелов", 400) + + # Hash the validated semantic JSON, not the raw bytes, so whitespace and + # object key order do not change the identity of a request. + canonical_body = json.dumps( + payload.model_dump(mode="json"), ensure_ascii=False, sort_keys=True, separators=(",", ":") + ) + body_hash = hashlib.sha256(canonical_body.encode("utf-8")).hexdigest() + path = request.url.path + now = datetime.now(timezone.utc) + expires_at = now + timedelta(hours=24) + scope = ( + IdempotencyRecord.user_id == user.id, + IdempotencyRecord.method == "POST", + IdempotencyRecord.path == path, + IdempotencyRecord.idempotency_key == idempotency_key, + ) + + with SessionLocal.begin() as session: + chat = _get_chat_for_member(session, chat_id, user.id) + if chat is None: + raise _api_error("not_found", "Объект не найден", 404) + + # A key becomes reusable only after its 24-hour retention window. + session.execute(delete(IdempotencyRecord).where(*scope, IdempotencyRecord.expires_at <= now)) + insert_record = ( + pg_insert(IdempotencyRecord) + .values( + user_id=user.id, + method="POST", + path=path, + idempotency_key=idempotency_key, + request_hash=body_hash, + response_body={}, + expires_at=expires_at, + ) + .on_conflict_do_nothing(constraint="idempotency_records_scope_key_uq") + .returning(IdempotencyRecord.id) + ) + record_id = session.execute(insert_record).scalar_one_or_none() + + if record_id is None: + # A concurrent insert waits on the unique constraint. At READ + # COMMITTED the winning transaction is visible to this SELECT. + existing = session.scalar(select(IdempotencyRecord).where(*scope)) + if existing is None: + raise _api_error("unavailable", "Сервис временно недоступен", 503) + if existing.request_hash != body_hash: + raise _api_error("conflict", "Idempotency-Key уже использован для другого запроса", 409) + result = existing.response_body + else: + message = Message(chat_id=chat_id, sender_id=user.id, text=payload.text) + session.add(message) + session.flush() + result = _message_out(message) + session.execute( + update(IdempotencyRecord) + .where(IdempotencyRecord.id == record_id) + .values(response_body=result) + ) + return result + + +@app.get("/api/v1/chats/{chat_id}/messages", response_model=MessagePage) +def list_messages(chat_id: uuid.UUID, request: Request, limit: int = 50, cursor: str | None = None): + user, _token = _current_user(request) + with SessionLocal() as session: + chat = _get_chat_for_member(session, chat_id, user.id) + if chat is None: + raise _api_error("not_found", "Объект не найден", 404) + if limit < 1 or limit > 100: + raise _api_error("invalid_request", "limit вне диапазона", 400) + after = None + if cursor is not None: + payload = _decode_cursor(cursor) + if payload.get("c") != str(chat_id): + raise _api_error("invalid_request", "cursor от другого чата", 400) + after = _cursor_position(payload) + statement = select(Message).where(Message.chat_id == chat_id) + if after is not None: + statement = statement.where(tuple_(Message.created_at, Message.id) > tuple_(*after)) + statement = statement.order_by(Message.created_at, Message.id).limit(limit + 1) + rows = session.scalars(statement).all() + has_more = len(rows) > limit + page = rows[:limit] + items = [_message_out(message) for message in page] + + next_cursor = None + if has_more: + last = page[-1] + next_cursor = _encode_cursor({"c": str(chat_id), "t": _iso(last.created_at), "i": str(last.id)}) + return {"items": items, "next_cursor": next_cursor} diff --git a/src/app/migrate.py b/src/app/migrate.py new file mode 100644 index 00000000..48c83839 --- /dev/null +++ b/src/app/migrate.py @@ -0,0 +1,36 @@ +from pathlib import Path + +from sqlalchemy import text + +from .db import engine + + +MIGRATIONS = Path(__file__).resolve().parents[2] / "migrations" + + +def migrate() -> None: + with engine.begin() as connection: + connection.exec_driver_sql("SELECT pg_advisory_xact_lock(2026102202)") + connection.exec_driver_sql( + "CREATE TABLE IF NOT EXISTS schema_migrations " + "(version VARCHAR(128) PRIMARY KEY, applied_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP)" + ) + applied = set(connection.execute(text("SELECT version FROM schema_migrations")).scalars()) + for path in sorted(MIGRATIONS.glob("*.sql")): + version = path.stem + if version in applied: + continue + sql = path.read_text(encoding="utf-8") + for statement in sql.split(";"): + if statement.strip(): + connection.exec_driver_sql(statement) + connection.execute( + text("INSERT INTO schema_migrations(version) VALUES (:version)"), + {"version": version}, + ) + print(f"Applied migration {version}") + engine.dispose() + + +if __name__ == "__main__": + migrate() diff --git a/src/app/models.py b/src/app/models.py new file mode 100644 index 00000000..495527ca --- /dev/null +++ b/src/app/models.py @@ -0,0 +1,86 @@ +import uuid +from datetime import datetime + +from sqlalchemy import DateTime, ForeignKey, ForeignKeyConstraint, Index, String, Text, UniqueConstraint, func +from sqlalchemy.dialects.postgresql import JSONB, UUID +from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column + + +class Base(DeclarativeBase): + pass + + +class User(Base): + __tablename__ = "users" + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + username: Mapped[str] = mapped_column(String(32), nullable=False, unique=True) + display_name: Mapped[str] = mapped_column(String(100), nullable=False) + password_hash: Mapped[str] = mapped_column(Text, nullable=False) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, server_default=func.now()) + + +class Chat(Base): + __tablename__ = "chats" + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + title: Mapped[str] = mapped_column(String(100), nullable=False) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, server_default=func.now()) + + +class ChatMember(Base): + __tablename__ = "chat_members" + __table_args__ = ( + Index("chat_members_user_id_idx", "user_id", "chat_id"), + ) + + chat_id: Mapped[uuid.UUID] = mapped_column( + UUID(as_uuid=True), ForeignKey("chats.id", ondelete="CASCADE"), primary_key=True + ) + user_id: Mapped[uuid.UUID] = mapped_column( + UUID(as_uuid=True), ForeignKey("users.id", ondelete="RESTRICT"), primary_key=True + ) + + +class Message(Base): + __tablename__ = "messages" + __table_args__ = ( + ForeignKeyConstraint( + ["chat_id", "sender_id"], + ["chat_members.chat_id", "chat_members.user_id"], + name="messages_sender_is_chat_member_fk", + ondelete="CASCADE", + ), + Index("messages_history_idx", "chat_id", "created_at", "id"), + ) + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + chat_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), nullable=False) + sender_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), nullable=False) + text: Mapped[str] = mapped_column(String(4000), nullable=False) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, server_default=func.now()) + + +class IdempotencyRecord(Base): + """Shared, transactional result cache for retried message POST requests.""" + + __tablename__ = "idempotency_records" + __table_args__ = ( + UniqueConstraint( + "user_id", "method", "path", "idempotency_key", + name="idempotency_records_scope_key_uq", + ), + Index("idempotency_records_expires_at_idx", "expires_at"), + ) + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + user_id: Mapped[uuid.UUID] = mapped_column( + UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False + ) + method: Mapped[str] = mapped_column(String(8), nullable=False) + path: Mapped[str] = mapped_column(String(200), nullable=False) + idempotency_key: Mapped[str] = mapped_column(String(128), nullable=False) + request_hash: Mapped[str] = mapped_column(String(64), nullable=False) + response_body: Mapped[dict] = mapped_column(JSONB, nullable=False) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, server_default=func.now()) + expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False) diff --git a/src/app/schemas.py b/src/app/schemas.py new file mode 100644 index 00000000..333e971e --- /dev/null +++ b/src/app/schemas.py @@ -0,0 +1,94 @@ +from pydantic import BaseModel, ConfigDict, Field, StrictStr, field_validator + + +class StrictModel(BaseModel): + model_config = ConfigDict(extra="forbid") + + +class CreateUser(StrictModel): + username: StrictStr = Field(min_length=3, max_length=32, pattern=r"^[a-z0-9_]{3,32}$") + display_name: StrictStr = Field(min_length=1, max_length=100) + password: StrictStr = Field(min_length=12, max_length=128) + + @field_validator("display_name") + @classmethod + def display_name_not_blank(cls, value: str) -> str: + if not value.strip(): + raise ValueError("display_name must contain a non-whitespace character") + return value + + +class UserOut(BaseModel): + id: str + username: str + display_name: str + created_at: str + + +class CreateChat(StrictModel): + title: StrictStr = Field(min_length=1, max_length=100) + member_ids: list[StrictStr] = Field(min_length=1, max_length=100) + + @field_validator("title") + @classmethod + def title_not_blank(cls, value: str) -> str: + if not value.strip(): + raise ValueError("title must contain a non-whitespace character") + return value + + @field_validator("member_ids") + @classmethod + def members_are_unique_uuids(cls, values: list[str]) -> list[str]: + import uuid + + try: + normalized = [str(uuid.UUID(value)) for value in values] + except (ValueError, AttributeError, TypeError) as exc: + raise ValueError("member_ids must contain UUIDs") from exc + if len(normalized) != len(set(normalized)): + raise ValueError("member_ids must be unique") + return normalized + + +class ChatOut(BaseModel): + id: str + title: str + member_ids: list[str] + created_at: str + + +class ChatPage(BaseModel): + items: list[ChatOut] + next_cursor: str | None + + +class CreateMessage(StrictModel): + text: StrictStr = Field(min_length=1, max_length=4000) + + +class MessageOut(BaseModel): + id: str + chat_id: str + sender_id: str + text: str + created_at: str + + +class MessagePage(BaseModel): + items: list[MessageOut] + next_cursor: str | None + + +class SessionOut(BaseModel): + token: str + token_type: str = "Bearer" + expires_at: str + user: UserOut + + +class Health(BaseModel): + status: str = "ok" + + +class ErrorBody(BaseModel): + error: dict[str, str] diff --git a/src/app/settings.py b/src/app/settings.py new file mode 100644 index 00000000..5b7dbbac --- /dev/null +++ b/src/app/settings.py @@ -0,0 +1,37 @@ +from dataclasses import dataclass +import os +from pathlib import Path + + +def _secret(file_variable: str, value_variable: str) -> str: + file_path = os.environ.get(file_variable) + if file_path: + value = Path(file_path).read_text(encoding="utf-8").strip() + else: + value = os.environ.get(value_variable, "").strip() + if not value: + raise RuntimeError(f"Required setting {file_variable} is missing") + return value + + +def load_database_url() -> str: + return _secret("DATABASE_URL_FILE", "DATABASE_URL") + + +@dataclass(frozen=True) +class Settings: + cache_url: str + session_ttl_seconds: int + + +def load_settings() -> Settings: + try: + ttl = int(os.environ.get("SESSION_TTL_SECONDS", "3600")) + except ValueError as exc: + raise RuntimeError("SESSION_TTL_SECONDS must be an integer") from exc + if ttl < 1 or ttl > 31_536_000: + raise RuntimeError("SESSION_TTL_SECONDS must be between 1 and 31536000") + return Settings( + cache_url=_secret("CACHE_URL_FILE", "CACHE_URL"), + session_ttl_seconds=ttl, + ) diff --git a/tests/idempotency_concurrency.py b/tests/idempotency_concurrency.py new file mode 100644 index 00000000..31ac2fc7 --- /dev/null +++ b/tests/idempotency_concurrency.py @@ -0,0 +1,54 @@ +#!/usr/bin/env python3 +"""Prove one shared idempotency result across concurrent API replicas.""" +from concurrent.futures import ThreadPoolExecutor +import json +import threading +import uuid +from client import Client, arguments, check, run + + +def main(): + def configure(parser): + parser.add_argument('--workers', type=int, default=12) + parser.add_argument('--requests', type=int, default=24) + + args = arguments('Concurrent duplicate message POST across the load balancer', configure) + check(args.workers >= 2 and args.requests >= args.workers, 'requests must be >= workers >= 2') + setup = Client(args.base_url, args.ca_file, timeout=10) + alice, bob, _eve, chat = setup.bootstrap() + key = uuid.uuid4().hex + body = 'parallel-idempotency-' + uuid.uuid4().hex + barrier = threading.Barrier(args.workers) + + def send(index): + client = Client(args.base_url, args.ca_file, timeout=10) + if index < args.workers: + barrier.wait(timeout=10) + result = client.message(alice, chat, body, key=key) + return result['json'], result['headers']['X-Instance-Id'] + + with ThreadPoolExecutor(max_workers=args.workers) as pool: + results = list(pool.map(send, range(args.requests))) + + messages = [item[0] for item in results] + instances = {item[1] for item in results} + check(all(message == messages[0] for message in messages), 'same key/body returned different messages') + check(len(instances) >= 2, 'concurrent requests did not reach two API replicas') + history = setup.call( + 'GET', '/api/v1/chats/' + chat['id'] + '/messages?limit=100', + actor=bob, schema='MessagePage' + )['json']['items'] + stored = [item for item in history if item['text'] == body] + check(len(stored) == 1, 'concurrent duplicate created zero or multiple stored messages') + print(json.dumps({ + 'parallel_requests': args.requests, + 'workers': args.workers, + 'replicas_observed': len(instances), + 'unique_message_ids': len({item['id'] for item in messages}), + 'stored_copies': len(stored), + 'result': 'PASS', + }, ensure_ascii=False)) + + +if __name__ == '__main__': + run(main)