From 042761e7365f0a9bbf3452b9b780351d3c7b0eb8 Mon Sep 17 00:00:00 2001 From: Gavarin23 <149+gavarin23@noreply.gitea.privcloud.tech> Date: Mon, 16 Nov 2026 22:03:15 +0300 Subject: [PATCH 1/2] =?UTF-8?q?=D0=97=D0=B0=D0=B3=D1=80=D1=83=D0=B7=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D1=84=D0=B0=D0=B9=D0=BB=D1=8B=20=D0=B2=20=C2=AB?= =?UTF-8?q?/=C2=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- compose.example.yaml | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/compose.example.yaml b/compose.example.yaml index dd4d3878..a16f5d59 100644 --- a/compose.example.yaml +++ b/compose.example.yaml @@ -1,11 +1,11 @@ -# Topology worksheet, deliberately NOT a runnable stack (no application supplied). -# Implement compose.yaml or stack.yaml; do not submit this empty file as deployment. -# Service names below are logical roles, not imposed container names. -x-lab-number: 3 -x-required-roles: - - api - - postgres - - load_balancer -# TODO: implement real images/builds, network wiring, volumes, healthchecks, -# credentials and bootstrap. Details: contracts/infrastructure.json and README.md. -services: {} +# Topology worksheet, deliberately NOT a runnable stack (no application supplied). +# Implement compose.yaml or stack.yaml; do not submit this empty file as deployment. +# Service names below are logical roles, not imposed container names. +x-lab-number: 3 +x-required-roles: + - api + - postgres + - load_balancer +# TODO: implement real images/builds, network wiring, volumes, healthchecks, +# credentials and bootstrap. Details: contracts/infrastructure.json and README.md. +services: {} -- 2.54.0 From 0b6edebfc0aae12a3216c0a0a5683d45b5a98316 Mon Sep 17 00:00:00 2001 From: garik Date: Mon, 16 Nov 2026 22:10:49 +0300 Subject: [PATCH 2/2] Lab 3: solution for grade 3 - BPI2304 Vardanyan --- .dockerignore | 18 +- .env.example | 14 +- .gitignore | 28 +- Dockerfile | 10 + Makefile | 19 +- README.md | 190 ++++++----- REPORT.md | 74 +++-- compose.yaml | 83 +++++ db/migrations/001_init.sql | 55 ++++ evidence/README.md | 6 +- infra/nginx.conf | 30 ++ requirements.txt | 1 + scripts/restart.sh | 5 + scripts/stop-one.sh | 8 + server.py | 452 ++++++++++++++++++++++++++ tests_local/concurrent_idempotency.py | 41 +++ tests_local/test_helpers.py | 72 ++++ 17 files changed, 937 insertions(+), 169 deletions(-) create mode 100644 Dockerfile create mode 100644 compose.yaml create mode 100644 db/migrations/001_init.sql create mode 100644 infra/nginx.conf create mode 100644 requirements.txt create mode 100644 scripts/restart.sh create mode 100644 scripts/stop-one.sh create mode 100644 server.py create mode 100644 tests_local/concurrent_idempotency.py create mode 100644 tests_local/test_helpers.py diff --git a/.dockerignore b/.dockerignore index bc16e556..43f563a2 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,20 +1,6 @@ .git -.github .env -.env.* -!.env.example -secrets -certs -volumes -data -backups -*.key -*.pem -*.p12 -*.pfx -*.jks -.venv __pycache__ -node_modules +*.pyc +.venv evidence -.DS_Store diff --git a/.env.example b/.env.example index d32b9be0..c34dc4e0 100644 --- a/.env.example +++ b/.env.example @@ -1,13 +1,3 @@ -# 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 -APP_PORT=8080 -APP_ENV=lab +# For local synthetic tests only. Copy to .env and choose your own password. +POSTGRES_PASSWORD=replace_this_for_local_lab_only 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 diff --git a/.gitignore b/.gitignore index b5a71896..ef303be2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,32 +1,6 @@ -# Local/private state .env -.env.* -!.env.example -secrets/ -certs/private/ -*.key -*.p12 -*.pfx -*.jks -*.pem -*.tfstate* -volumes/ -data/ -backups/ -# Runtime/build artifacts .venv/ __pycache__/ -*.py[cod] -node_modules/ -dist/ -build/ -target/ -bin/ -obj/ -coverage/ +*.pyc *.log .DS_Store -.idea/ -.vscode/ -# Keep small, sanitized evidence summaries in evidence/ under version control. -# Inspect git diff --cached: ignore rules are not a secret scanner. diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..ffce66e4 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,10 @@ +FROM python:3.12.9-slim +ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 +WORKDIR /app +COPY requirements.txt ./ +RUN pip install --no-cache-dir -r requirements.txt +COPY server.py ./ +RUN useradd --create-home --uid 10001 labuser +USER 10001 +EXPOSE 8080 +CMD ["python", "server.py"] diff --git a/Makefile b/Makefile index 5d86d171..9183d26e 100644 --- a/Makefile +++ b/Makefile @@ -4,27 +4,24 @@ 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-concurrency test-local help: - @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes" - + @echo "check, validate, test, test-persistence, test-failover, test-concurrency, test-local" check: $(PYTHON) scripts/check_contract.py - validate: $(PYTHON) scripts/validate_openapi.py - test: $(PYTHON) tests/smoke.py --base-url "$(BASE_URL)" $(TLS_ARGS) - load: $(PYTHON) tests/load.py --base-url "$(BASE_URL)" $(TLS_ARGS) - test-persistence: - @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable restart hook"; exit 2) + @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to restart hook"; exit 2) $(PYTHON) tests/resilience.py --mode persistence --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) - test-failover: - @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2) + @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to stop-one hook"; exit 2) $(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) +test-concurrency: + $(PYTHON) tests_local/concurrent_idempotency.py --base-url "$(BASE_URL)" $(TLS_ARGS) +test-local: + $(PYTHON) -m unittest discover -s tests_local -p 'test_*.py' -v diff --git a/README.md b/README.md index 10381de4..a2a54c8f 100644 --- a/README.md +++ b/README.md @@ -1,104 +1,134 @@ -# Лабораторная 3. Балансировка и отказ API-реплики +# Лабораторная работа №3 — БПИ2304 — Варданян Гарик -Запустить несколько взаимозаменяемых экземпляров API за единой точкой входа и сохранить корректность при остановке одного из них. +**Тема:** балансировка нагрузки и отказ одной API-реплики. **Целевая оценка:** 3. -Это **skeleton**, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; UI не обязателен. +Учебный минимальный мессенджер на Python, продолжение ЛР №2: +- тот же HTTP API (`ThreadingHTTPServer`, пользователи, Basic login, Bearer, чаты, сообщения, cursor); +- **в отличие от ЛР №2 данные больше не хранятся в памяти процесса**; +- Nginx принимает все внешние запросы на `127.0.0.1:8080`, распределяет их между `api1` и `api2`; +- PostgreSQL хранит пользователей, чаты, участников, сообщения, Bearer-сессии с TTL и ключи идемпотентности; +- PostgreSQL выполняет атомарную транзакцию «новое сообщение + ключ», а advisory lock защищает конкурентные повторы; +- `X-Instance-Id` показывает, какая реплика сформировала ответ; +- можно остановить `api1` **или** `api2`: другая реплика продолжит работу с тем же токеном. -[Карта курса](COURSE.md) · [Процесс fork/PR](CONTRIBUTING.md) · [OpenAPI](contracts/openapi.json) · [Семантика API](contracts/README.md) · [Проверки](tests/README.md) · [Отчёт](REPORT.md) · [Примеры JSON](contracts/examples.json) · [Памятка преподавателю](MAINTAINERS.md) +## Архитектура -## Откуда начинаем - -Нужен минимум lab2: PostgreSQL, общие действующие сессии, миграции. Добавляются X-Instance-Id и обязательный Idempotency-Key при отправке сообщения. - -**Архитектура:** Клиент → LB → API × 2+ → общие PostgreSQL и хранилище сессий. Compose или Swarm — на выбор. - -## Что сделать - -1. Выберите Compose + Nginx/HAProxy/Traefik либо Docker Swarm. Для выбранного варианта дайте одну последовательность запуска. -2. Уберите локальные сессии/другие данные, от которых зависит корректность, из API. Миграции выполняйте отдельно и согласованно, а не гонкой всех реплик. -3. Настройте балансировщик, проверки готовности, DNS/обновление backend-адресов и graceful shutdown. Не закрепляйте клиента sticky session как способ исправить раздельное состояние. -4. Реализуйте общую идемпотентность отправки сообщения. Проверьте одинаковый ключ одновременно через разные реплики. -5. Подготовьте явный action script, останавливающий одну выбранную API-реплику, и продемонстрируйте чтение/запись во время отказа. - -## Оценка «3»: работающий минимум - -- Весь стенд описан в compose.yaml или stack.yaml, запускается документированной командой. Не менее двух API-реплик, одна публичная точка входа, одна общая БД и общее хранилище сессий. -- Разные запросы одного пользователя обслуживаются разными репликами без повторного входа. Это видно по X-Instance-Id. Доступ через LB — основной проверяемый маршрут. -- Можно остановить любую одну API-реплику при работающей другой: не позднее 10 секунд продолжаются новые чтения/записи, подтверждённые сообщения доступны. Краткие ошибки/оборванные запросы во время обнаружения отказа измеряются и допустимы. -- Повтор POST сообщения с тем же Idempotency-Key не создаёт дубль, включая конкурентный повтор и переключение реплики. Неподтверждённую запись клиент может безопасно повторить с тем же ключом. -- make test, persistence и failover-сценарий проходят; для failover проверяется наличие ≥2 наблюдаемых реплик. Для Swarm сборка образа и его доступность узлам описаны отдельно. - -## Оценка «4»: уровень стажёра/джуна - -Весь уровень 3 **и все** пункты ниже: - -- Health/readiness, timeouts и прекращение приёма при SIGTERM настроены согласованно; LB исключает недоступный backend. Укажите период проверок и максимальное время обнаружения отказа. -- Последовательно остановите каждую API-реплику (восстанавливая предыдущую); соберите RPS, ошибки и время восстановления. Общая идемпотентность проверяется параллельными запросами с одним ключом. -- Контейнеры имеют CPU/RAM-лимиты, API не публикуют порты наружу в обход LB; секреты и хранилища общие только там, где нужно. Нет container_name, мешающего масштабированию одного Compose-service. -- Rolling update или эквивалентная поочерёдная замена проверена под нагрузкой. Миграции запускаются однократно и совместимы с работающей версией либо ограничение честно описано. - -## Оценка «5»: исследование и доказанный результат - -Весь уровень 4 **и один законченный трек на выбор**. Приведите гипотезу, повторяемую методику, результаты и ограничения. - -**Трек 1. Цена масштабирования.** При фиксированном суммарном CPU/RAM сравните 1/2/4 API-реплики на одном профиле нагрузки; затем проведите серию с ростом ресурсов. Найдите saturation point БД/LB/пула и покажите, почему рост реплик перестаёт помогать. Дайте исходные данные, графики и одно подтверждённое улучшение. - -**Трек 2. Отказ узла.** Расширьте стенд до нескольких узлов, покажите перенос API при потере узла и разберите оставшиеся SPOF (LB, DB, storage). Для заявленной защищённой зависимости покажите реальный failover и сохранность данных. Если DB не реплицирована, не заявляйте выживание её узла. - -## Как начать и проверить - -```sh -# Работает прямо в skeleton, Python 3.9+; приложение не запускается: -make check - -# После реализации запустите свой сервер/стенд по REPORT.md. -# По умолчанию тест использует http://localhost:8080. -make test +```text + http://127.0.0.1:8080 + | + Nginx (lb) + / \ + api1:8080 api2:8080 + \ / + PostgreSQL + users / sessions / chats / messages + / idempotency ``` -`.env.example`, `compose.example.yaml` и `contracts/infrastructure.json` описывают настройки и роли компонентов. **compose.example.yaml — список ролей с пустым services, не запускаемый стенд.** Реализуйте свой `compose.yaml`/`stack.yaml`, закрепите версии образов, заполните локальный `.env` и опишите bootstrap/миграции. Все зависимости поднимаются из этого репозитория; ссылка «у меня БД уже установлена» не заменяет воспроизводимость. +В репликах нет локальных пользователей, сессий или сообщений. Redis не требуется, потому что **общим постоянным хранилищем сессий является PostgreSQL**. Единственный публичный порт — порт Nginx. Приложение и база слушают только во внутренней Docker-сети. + +## Куда скопировать файлы + +Это комплект **файлов реализации поверх официального skeleton ЛР №3**: публичные `tests/`, `contracts/`, `scripts/check_contract.py`, `lab.json` и остальные файлы преподавателя из исходного репозитория не изменяйте и не удаляйте. + +1. Сделайте fork `https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3` в своём Gitea. +2. Клонируйте fork, создайте ветку `solution/bpi2304-vardanyan`. +3. Распакуйте **содержимое** архива в корень клона, разрешив замену `README.md`, `REPORT.md`, `Makefile`, `.env.example`, `.gitignore` и `.dockerignore`. Остальные файлы преподавателя останутся на месте. + +Пример для PowerShell (в корне клона): + +```powershell +git switch -c solution/bpi2304-vardanyan +Expand-Archive -Path "C:\путь\к\lab3_vardanyan_na_3.zip" -DestinationPath . -Force +Copy-Item .env.example .env +notepad .env # обязательно задайте собственный POSTGRES_PASSWORD +``` + +## Запуск и проверка (Docker Desktop + WSL2 / Linux) + +Нужны Docker Engine/Compose v2, Python 3.9+ и `make` (для проверок). Выполняйте shell-скрипты в WSL2/Linux/macOS/Git Bash, а не в чистом PowerShell. + +```bash +# При первом запуске +cp .env.example .env +# Отредактировать .env: заменить POSTGRES_PASSWORD +chmod +x scripts/restart.sh scripts/stop-one.sh -```sh -# Compose-вариант после реализации: docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build -# Дождитесь /health/ready; затем make test. -# Для Swarm укажите эквивалентные build/push/deploy-команды в REPORT.md. +# Дождаться healthy у db, api1, api2 и доступности LB: +docker compose --env-file .env ps +curl -i http://127.0.0.1:8080/health/ready + +# Официальные тесты (в исходном skeleton преподавателя): +make check +make test +make test-persistence ACTION_SCRIPT=scripts/restart.sh +make test-failover ACTION_SCRIPT=scripts/stop-one.sh + +# После failover одна реплика остаётся остановленной; восстановить её: +docker compose --env-file .env up -d api1 api2 + +# Дополнительная проверка параллельных POST на обе реплики: +make test-concurrency ``` +**Важно:** `make test-failover` выбирает цель по `X-Instance-Id`; `scripts/stop-one.sh` остановит именно эту реплику и не будет перезапускать её за тест. Для второй проверки восстановите обе реплики и повторите сценарий. Увидеть реальные контейнеры: `docker compose --env-file .env ps -a`. -Примеры запросов доступны в `examples/requests.http`, примеры JSON — в `contracts/examples.json`. Для полной проверки схемы (по желанию локально; CI делает её автоматически): +При необходимости пересоздать только сервисы, **без удаления данных**: -```sh -python3 -m venv .venv -.venv/bin/python -m pip install -r requirements-dev.txt -make validate PYTHON=.venv/bin/python +```bash +docker compose --env-file .env up -d --build --force-recreate ``` -Smoke не выставляет оценку автоматически. Проверку сохранности/отказов запускайте явно по [tests/README.md](tests/README.md), остальные доказательства приведите в отчёте. +Повторная миграция не удаляет данные: -## Сценарий защиты +```bash +docker compose --env-file .env run --rm migrate +``` -1. Запустить стенд и показать ≥2 разных X-Instance-Id через LB с одной сессией. -2. Запустить make test-failover ACTION_SCRIPT=scripts/stop-one.sh. Скрипт теста выполняет запросы во время action, учитывает ошибки и повторяет сообщения с исходным ключом. -3. Показать, какой контейнер действительно остановлен; заголовок сам по себе не доказательство разных процессов. Повторить для второй реплики после восстановления первой. -4. Проверить restart всего стенда с сохранением volumes и неизменным токеном. Для 4/5 — соответствующие эксперименты. +Показать распределение вручную (запросы должны возвращать `X-Instance-Id: api1` / `api2`): -## Что должно быть в PR +```bash +for i in $(seq 1 10); do curl -s -D - -o /dev/null http://127.0.0.1:8080/health/live | grep -i x-instance-id; done +``` -compose.yaml или stack.yaml, конфигурация LB, scripts/restart.sh, scripts/stop-one.sh, Dockerfile, миграции, результаты отказов. +## Аутентификация и Idempotency-Key -Заполните `REPORT.md` и [шаблон PR](.github/pull_request_template.md), укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах [объявленных переходов](COURSE.md). +1. `POST /api/v1/users`: `username`, `display_name`, `password`. +2. `POST /api/v1/auth/sessions`: `Authorization: Basic base64(username:password)` → токен. +3. Остальные пути используют `Authorization: Bearer `. +4. `POST /api/v1/chats/{id}/messages`: JSON `{"text":"Привет"}` **и** заголовок `Idempotency-Key: some-unique-key`. +5. Повтор такого POST с тем же ключом и текстом возвращает исходное сообщение (201), с другим текстом — 409. -## Вопросы на защите +Ключ уникален в области пользователь + POST + путь сообщения. Запись сообщения и ключа выполняется в одной транзакции. Сессии и сообщения подтверждаются после COMMIT; чтения с другой реплики видят их сразу. Пароли защищены `hashlib.scrypt` с уникальной солью; в базе лежит SHA-256 токена, а не исходный bearer-токен. -- Чем отказ процесса отличается от отказа узла? -- Почему depends_on/healthcheck сами по себе не являются балансировщиком? -- Какие POST можно повторять после timeout и что защищает Idempotency-Key? -- Что сломается при увеличении числа API, если сессии находятся в локальной памяти? +## Отказ и сохранность -## Первичные материалы +- `scripts/stop-one.sh`: останавливает выбранную тестом реплику (`TARGET_INSTANCE_ID=api1` или `api2`), не трогая PostgreSQL и другую реплику. +- `scripts/restart.sh`: перезапускает `db`, обе API и `lb`, **без `down -v`**. Сессия продолжает действовать до исходного expiry. +- Nginx использует Docker DNS resolver, динамическое разрешение адресов и пассивное обнаружение недоступного backend (`max_fails=1`, `fail_timeout=2s`). Неподтверждённые POST следует повторять с прежним `Idempotency-Key`. -- [Compose services](https://docs.docker.com/reference/compose-file/services/) -- [Swarm routing mesh](https://docs.docker.com/engine/swarm/ingress/) -- [Swarm services](https://docs.docker.com/engine/swarm/services/) +Обычная остановка (с сохранением данных): + +```bash +docker compose --env-file .env down +``` + +**УДАЛЕНИЕ учебных данных** (только намеренно; удалит PostgreSQL volume): + +```bash +docker compose --env-file .env down -v +``` + +## Ограничения + +- Задача — оценка «3», без исследовательского трека на 4/5, Redis, нагрузки и rolling update. +- Переживается **отказ одного API-процесса**, но не отказ PostgreSQL, узла Docker или Nginx. +- Сервер использует короткоживущие подключения к БД (без пула — для малого учебного потока). +- Окно хранения ключей идемпотентности здесь неограничено (строже обязательных 24 часов); ручная очистка нужна лишь при росте БД. +- Требования проверяются в локальном изолированном стенде по HTTP только с синтетическими пользователями. Для публикации наружу нужен TLS. +- Реальные `make test`, persistence/failover требуют Docker и не заменяются прохождением `make check`. + +Официальное задание: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3 +Предыдущая работа: https://gitea.privcloud.tech/Gavarin23/mtusi2026lab2/src/branch/solution/bpi2304-vardanyan diff --git a/REPORT.md b/REPORT.md index c2679005..8ebb8d9a 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,71 @@ # Отчёт — лабораторная 3 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- **Автор, группа:** Варданян Гарик, БПИ2304 +- **Целевая оценка:** 3 +- **Commit/PR:** заполнить после публикации в личном fork +- **Исходная база:** ЛР №2 (Python `ThreadingHTTPServer`, Basic/Bearer, чат/сообщения) +- **Источники:** официальный README/контракт/OpenAPI/проверки ЛР №3, Python 3.12, PostgreSQL 16, Nginx 1.28, psycopg 3.2.6; помощь ИИ: ChatGPT при разработке реализации и текста отчёта. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +1. Склонировать собственный fork исходной ЛР №3 и применить файлы реализации поверх skeleton (контракт и `tests/` преподавателя оставить без изменений). +2. Установить Docker Desktop + WSL2 (или Docker Engine с Compose v2), Python 3.9+ и GNU Make. +3. В корне: `cp .env.example .env`; заменить `POSTGRES_PASSWORD` на свой случайный пароль. Файл `.env` игнорируется Git. +4. В Linux/WSL: `chmod +x scripts/restart.sh scripts/stop-one.sh` (важно после распаковки из Windows). Затем `docker compose --env-file .env config --quiet`. +5. `docker compose --env-file .env up -d --build`: запускает БД, ожидает её готовность, однократно выполняет `migrate`, стартует обе API и LB. +6. `docker compose --env-file .env ps`, `curl -i http://localhost:8080/health/ready`. +7. `make check`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, `make test-concurrency`. +8. После отказа восстановить: `docker compose --env-file .env up -d api1 api2`; повторить отказ для второй реплики. + +Безопасная остановка: `docker compose --env-file .env down`. Намеренное удаление всех учебных данных: `docker compose --env-file .env down -v` (**разрушительно**). ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +`Клиент → Nginx:8080 → API api1/api2 → PostgreSQL:5432`. -## Доказательства критериев +Внешний порт опубликован только у Nginx, localhost:8080. API-реплики работают внутри сети Compose, код одинаков. У каждой отдельное имя `INSTANCE_ID` для HTTP `X-Instance-Id`: `api1` и `api2`. Nginx выбирает backend без sticky sessions, использует Docker DNS resolver и пассивное исключение отказавшей реплики (1 ошибка; `fail_timeout=2s`). -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +**Главное отличие от ЛР №2:** словари users/sessions/chats/messages в памяти удалены. Все данные и текущие Bearer-сессии находятся в общем PostgreSQL (именованный volume `postgres_data`). Redis/Valkey не нужен, поскольку PostgreSQL — общий источник истины для сессий и сообщений. + +- `users.username UNIQUE`, пароли `scrypt` с уникальной солью; +- `sessions.token_hash` хранит SHA-256 opaque токена, а `expires_at` задаёт TTL; logout удаляет сессию; +- `chats` + `chat_members`: одна транзакция создания чата и списка участников; +- `messages`: FK для чата и отправителя, индекс `(chat_id,created_at,id)` под keyset-пагинацию; +- `message_idempotency`: уникальный `(user_id,chat_id,idem_key)`; PostgreSQL advisory transaction lock синхронизирует конкурентный повтор, результат фиксируется атомарно с сообщением. Одинаковый запрос 201 + прежнее сообщение, другой текст 409. Запись хранится не меньше 24 часов (без автоматической очистки); +- `db/migrations/001_init.sql`: таблицы и индексы создаются при первом запуске; `IF NOT EXISTS` + `schema_migrations` допускают повторное применение без потери данных. + +`GET /health/live` — жизнь процесса. `GET /health/ready` проверяет PostgreSQL. При недоступности БД возвращается 503 в контрактном JSON, а не выдаётся успешный ответ с раздельным локальным состоянием. + +**Транзакционные границы:** регистрация пользователя; создание чата + участников; отправка сообщения + сохранение результата по ключу; создание/удаление сессии. Успешный API ответ выдаётся после завершения `with db_connect()` (COMMIT). + +## Доказательства критериев уровня 3 + +Это таблица команд для воспроизводимой защиты. **Результаты на машине с Docker нужно записать после настоящего запуска; PASS без запуска здесь не заявлен.** + +| Критерий | Команда / проверка | Что должно наблюдаться | Результат | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Полный запуск стенда | `docker compose --env-file .env up -d --build` | БД, migrate (exit 0), api1, api2, lb | Требует запуска | +| API smoke | `make test` | `PASS: lab3 public API scenario` | Требует запуска | +| Две реплики / общий Bearer | 10 GET `/health/live` через LB, затем `make test-failover` | Заголовки `api1` и `api2`, тот же токен | Требует запуска | +| Отказ одной реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | Успешные записи в пределах 10 с, подтверждённые сообщения доступны, ≥2 реплики были видны до отказа | Требует запуска | +| Общая идемпотентность | `make test-concurrency` | Для 12 конкурентных POST с ключом 1 message ID, в истории 1 запись | Требует запуска | +| Перезапуск с сохранением | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | Тот же токен читает ту же историю после рестарта БД/API/LB | Требует запуска | +| Повтор миграции | `docker compose --env-file .env run --rm migrate` | exit 0, таблицы/данные без изменений | Требует запуска | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +После запуска приложить обезличенные результаты в `evidence/`: `docker compose ps -a` до/после отказа, вывод тестов, времена восстановления из `tests/resilience.py`. Секреты из `.env` и токены в отчёт не копировать. -## Эксперименты и отказы +## Эксперимент отказа -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +**Гипотеза:** при остановке одного API-процесса второй обслуживает новые запросы с общей сессией и общими данными. Nginx может кратко выдавать ошибки на этапе обнаружения; публичный тест допускает переходные ошибки, но требует нового успешного POST за 10 секунд. -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +**Шаги:** запустить обе реплики, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, проверить остановленный контейнер, восстановить его и повторить для второй реплики. Тест создаёт synthetic chat, пишет 15 секунд, сверяет историю и повторы. -## Ограничения и следующие шаги +| Воздействие | Ожидаемое поведение | Фактическое время/ошибки | +| --- | --- | --- | +| Остановка api1 | api2 принимает POST и GET, сообщения без дублей | Заполнить по тесту | +| Остановка api2 | api1 принимает POST и GET, сообщения без дублей | Заполнить по тесту | +| Restart db, api1, api2, lb | Исходный Bearer и сообщения сохраняются | Заполнить по тесту | -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +## Ограничения и дальнейшие шаги + +Стенд рассчитан на локальную проверку одной отказавшей API-реплики, а не на высокий throughput. PostgreSQL и Nginx — оставшиеся single points of failure; отказ Docker-хоста не переживается. Нет измерения RPS/rolling update, connection pool, TLS и Redis: они не заявлены для оценки «3». Пароли/сессии не переносятся автоматически из ЛР №2, потому что её данные хранились в памяти; новая лаборатория запускается с чистой БД. diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..1f8be7a7 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,83 @@ +services: + db: + image: postgres:16.8-alpine + environment: + POSTGRES_DB: lab3 + POSTGRES_USER: labuser + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env} + volumes: + - postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U labuser -d lab3"] + interval: 2s + timeout: 2s + retries: 30 + restart: unless-stopped + + migrate: + image: postgres:16.8-alpine + environment: + PGHOST: db + PGPORT: "5432" + PGDATABASE: lab3 + PGUSER: labuser + PGPASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env} + volumes: + - ./db/migrations:/migrations:ro + command: ["sh", "-ec", "psql -v ON_ERROR_STOP=1 -f /migrations/001_init.sql"] + depends_on: + db: + condition: service_healthy + restart: "no" + + api1: + build: . + environment: &api_env + APP_HOST: 0.0.0.0 + APP_PORT: "8080" + PGHOST: db + PGPORT: "5432" + PGDATABASE: lab3 + PGUSER: labuser + PGPASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env} + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + INSTANCE_ID: api1 + depends_on: + migrate: + condition: service_completed_successfully + healthcheck: &api_health + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)"] + interval: 2s + timeout: 3s + retries: 10 + start_period: 5s + restart: unless-stopped + stop_grace_period: 5s + + api2: + build: . + environment: + <<: *api_env + INSTANCE_ID: api2 + depends_on: + migrate: + condition: service_completed_successfully + healthcheck: *api_health + restart: unless-stopped + stop_grace_period: 5s + + lb: + image: nginx:1.28.0-alpine + ports: + - "127.0.0.1:8080:8080" + volumes: + - ./infra/nginx.conf:/etc/nginx/nginx.conf:ro + depends_on: + api1: + condition: service_healthy + api2: + condition: service_healthy + restart: unless-stopped + +volumes: + postgres_data: diff --git a/db/migrations/001_init.sql b/db/migrations/001_init.sql new file mode 100644 index 00000000..5abe6a23 --- /dev/null +++ b/db/migrations/001_init.sql @@ -0,0 +1,55 @@ +-- All tables (including sessions) are durable and shared by both API replicas. +-- Idempotent migration; safe on an existing non-empty database. +BEGIN; +CREATE TABLE IF NOT EXISTS schema_migrations ( + version INTEGER PRIMARY KEY, + applied_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp() +); +CREATE TABLE IF NOT EXISTS users ( + id UUID PRIMARY KEY, + username VARCHAR(32) NOT NULL UNIQUE, + display_name VARCHAR(100) NOT NULL, + password_hash TEXT NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp() +); +CREATE TABLE IF NOT EXISTS sessions ( + token_hash CHAR(64) PRIMARY KEY, + user_id UUID NOT NULL REFERENCES users(id), + expires_at TIMESTAMPTZ NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp() +); +CREATE INDEX IF NOT EXISTS sessions_expires_at_idx ON sessions(expires_at); +CREATE TABLE IF NOT EXISTS chats ( + id UUID PRIMARY KEY, + title VARCHAR(100) NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp() +); +CREATE TABLE IF NOT EXISTS chat_members ( + chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE, + user_id UUID NOT NULL REFERENCES users(id), + member_index INTEGER NOT NULL, + PRIMARY KEY(chat_id, user_id), + UNIQUE(chat_id, member_index) +); +CREATE INDEX IF NOT EXISTS chat_members_user_idx ON chat_members(user_id, chat_id); +CREATE TABLE IF NOT EXISTS messages ( + id UUID PRIMARY KEY, + chat_id UUID NOT NULL REFERENCES chats(id), + sender_id UUID NOT NULL REFERENCES users(id), + text VARCHAR(4000) NOT NULL CHECK(length(trim(text)) > 0), + created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp() +); +CREATE INDEX IF NOT EXISTS messages_chat_cursor_idx ON messages(chat_id, created_at, id); +CREATE INDEX IF NOT EXISTS chats_cursor_idx ON chats(created_at, id); +CREATE TABLE IF NOT EXISTS message_idempotency ( + user_id UUID NOT NULL REFERENCES users(id), + chat_id UUID NOT NULL REFERENCES chats(id), + idem_key VARCHAR(128) NOT NULL, + body_hash CHAR(64) NOT NULL, + message_id UUID NOT NULL UNIQUE REFERENCES messages(id), + created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(), + PRIMARY KEY(user_id, chat_id, idem_key) +); +-- Keep idempotency keys longer than 24 hours: no pruning in the educational lab. +INSERT INTO schema_migrations(version) VALUES (1) ON CONFLICT DO NOTHING; +COMMIT; diff --git a/evidence/README.md b/evidence/README.md index 8df70015..e286a8b8 100644 --- a/evidence/README.md +++ b/evidence/README.md @@ -1,5 +1,5 @@ -# Доказательства +# Доказательства для защиты -Храните небольшие обезличенные результаты: команды и stdout проверок, JSON/CSV агрегатов нагрузки, EXPLAIN, dashboard JSON, текст разбора отказа. Укажите дату, commit, аппаратные лимиты и профиль нагрузки. +После **фактического** запуска на своей машине сохраните вывод официальных тестов (`make test`, `make test-persistence ...`, `make test-failover ...`), список контейнеров `docker compose --env-file .env ps -a` до и после остановки и измерение `first_recovery_seconds` из failover. Тесты не пишут секреты в stdout. Не прикладывайте файл `.env` и не публикуйте `Authorization` или токены. -Не добавляйте .env, session tokens, cookies, приватные ключи, credentials, реальные сообщения, raw dumps и signed URLs. Для скриншотов скрывайте секреты. Большие логи/бинарные traces сохраняйте отдельно по правилам преподавателя; одного скриншота без методики недостаточно. +Пока реальных результатов здесь нет: окружение подготовки файлов не содержит Docker/PostgreSQL, утверждать PASS преждевременно. diff --git a/infra/nginx.conf b/infra/nginx.conf new file mode 100644 index 00000000..b9b8a609 --- /dev/null +++ b/infra/nginx.conf @@ -0,0 +1,30 @@ +# Nginx >= 1.27.3 supports dynamic DNS re-resolution for upstream servers. +events { worker_connections 1024; } +http { + access_log /dev/stdout; + error_log /dev/stderr warn; + + upstream messenger_api { + zone messenger_api 64k; + resolver 127.0.0.11 valid=1s ipv6=off; + server api1:8080 resolve max_fails=1 fail_timeout=2s; + server api2:8080 resolve max_fails=1 fail_timeout=2s; + } + server { + listen 8080; + server_name _; + client_max_body_size 1m; + location / { + proxy_pass http://messenger_api; + proxy_http_version 1.1; + proxy_set_header Connection ""; + proxy_set_header Host $host; + proxy_set_header X-Request-Id $request_id; + proxy_connect_timeout 1s; + proxy_send_timeout 5s; + proxy_read_timeout 5s; + proxy_next_upstream error timeout http_502 http_503 http_504; + proxy_next_upstream_tries 2; + } + } +} diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..74c889ae --- /dev/null +++ b/requirements.txt @@ -0,0 +1 @@ +psycopg[binary]==3.2.6 diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100644 index 00000000..af344cd4 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,5 @@ +#!/usr/bin/env bash +# ACTION_SCRIPT for make test-persistence. Does not delete volumes. +set -euo pipefail +cd "$(dirname "$0")/.." +docker compose --env-file .env restart db api1 api2 lb >/dev/null diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100644 index 00000000..d5ad8744 --- /dev/null +++ b/scripts/stop-one.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +# ACTION_SCRIPT for make test-failover: stop EXACTLY the replica named by test. +set -euo pipefail +cd "$(dirname "$0")/.." +case "${TARGET_INSTANCE_ID:-}" in + api1|api2) docker compose --env-file .env stop -t 1 "$TARGET_INSTANCE_ID" >/dev/null ;; + *) echo "Unexpected TARGET_INSTANCE_ID; expected api1 or api2" >&2; exit 2 ;; +esac diff --git a/server.py b/server.py new file mode 100644 index 00000000..3437ecf7 --- /dev/null +++ b/server.py @@ -0,0 +1,452 @@ +#!/usr/bin/env python3 +"""MTUSI lab3: the lab2 messenger API with shared PostgreSQL state. + +No user, session, chat, message, or idempotency state is stored in API memory. +Two independent copies of this process may serve the same HTTP endpoint. +""" +from __future__ import annotations + +import base64 +from datetime import datetime, timedelta, timezone +import hashlib +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +import json +import logging +import os +import re +import secrets +import signal +import threading +from urllib.parse import parse_qs, urlsplit +import uuid + +import psycopg +from psycopg.rows import dict_row + +USER_RE = re.compile(r"[a-z0-9_]{3,32}\Z") +IDEMPOTENCY_RE = re.compile(r"[A-Za-z0-9._:-]{1,128}\Z") +MAX_BODY = 1_048_576 +INSTANCE_ID = os.environ.get("INSTANCE_ID") or uuid.uuid4().hex +TTL = int(os.environ.get("SESSION_TTL_SECONDS", "3600")) +if TTL <= 0: + raise SystemExit("SESSION_TTL_SECONDS must be positive") + + +class ApiError(Exception): + def __init__(self, status: int, code: str, message: str, challenge: str | None = None): + super().__init__(message) + self.status, self.code, self.message, self.challenge = status, code, message, challenge + + +def db_connect(): + """A short-lived DB connection; transaction rolls back on exceptions.""" + return psycopg.connect( + host=os.environ.get("PGHOST", "db"), + port=int(os.environ.get("PGPORT", "5432")), + dbname=os.environ.get("PGDATABASE", "lab3"), + user=os.environ.get("PGUSER", "labuser"), + password=os.environ.get("PGPASSWORD", ""), + connect_timeout=3, + row_factory=dict_row, + options="-c statement_timeout=5000", + ) + + +def stamp(value: datetime) -> str: + return value.astimezone(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z") + + +def password_hash(password: str) -> str: + salt = secrets.token_bytes(16) + digest = hashlib.scrypt(password.encode("utf-8"), salt=salt, n=16384, r=8, p=1) + return "scrypt$16384$8$1$" + salt.hex() + "$" + digest.hex() + + +def password_matches(password: str, encoded: str) -> bool: + try: + method, n, r, p, salt_hex, hash_hex = encoded.split("$") + if method != "scrypt": + return False + digest = hashlib.scrypt(password.encode("utf-8"), salt=bytes.fromhex(salt_hex), + n=int(n), r=int(r), p=int(p)) + return secrets.compare_digest(digest, bytes.fromhex(hash_hex)) + except (ValueError, TypeError, MemoryError): + return False + + +def uuid_string(value: object) -> str: + if not isinstance(value, str): + raise ApiError(400, "invalid_request", "Некорректный UUID") + try: + parsed = uuid.UUID(value) + except (ValueError, AttributeError): + raise ApiError(400, "invalid_request", "Некорректный UUID") from None + if str(parsed) != value: + raise ApiError(400, "invalid_request", "Некорректный UUID") + return value + + +def require_fields(obj: dict, fields: set[str]) -> None: + if set(obj) != fields: + raise ApiError(400, "invalid_request", "Неверный набор полей") + + +def public_user(row: dict) -> dict: + return {"id": str(row["id"]), "username": row["username"], + "display_name": row["display_name"], "created_at": stamp(row["created_at"])} + + +def public_message(row: dict) -> dict: + return {"id": str(row["id"]), "chat_id": str(row["chat_id"]), + "sender_id": str(row["sender_id"]), "text": row["text"], + "created_at": stamp(row["created_at"])} + + +def fetch_chat(conn, chat_id: str) -> dict | None: + row = conn.execute( + """SELECT c.id, c.title, c.created_at, + array_agg(cm.user_id ORDER BY cm.member_index) AS member_ids + FROM chats c JOIN chat_members cm ON cm.chat_id = c.id + WHERE c.id = %s GROUP BY c.id""", (chat_id,)).fetchone() + if row is None: + return None + return {"id": str(row["id"]), "title": row["title"], + "member_ids": [str(x) for x in row["member_ids"]], + "created_at": stamp(row["created_at"])} + + +def pagination(query: dict[str, list[str]], scope: str): + if set(query) - {"limit", "cursor"} or any(len(v) != 1 for v in query.values()): + raise ApiError(400, "invalid_request", "Некорректные параметры страницы") + raw = query.get("limit", ["50"])[0] + if not re.fullmatch(r"[0-9]+", raw or "") or not 1 <= int(raw) <= 100: + raise ApiError(400, "invalid_request", "limit должен быть от 1 до 100") + limit = int(raw) + cursor = query.get("cursor", [None])[0] + position = None + if cursor is not None: + try: + decoded = base64.b64decode(cursor + "=" * (-len(cursor) % 4), + altchars=b"-_", validate=True) + packed = json.loads(decoded) + if (not isinstance(packed, list) or len(packed) != 3 or + packed[0] != scope or not isinstance(packed[1], str)): + raise ValueError + created = datetime.fromisoformat(packed[1].replace("Z", "+00:00")) + item_id = uuid_string(packed[2]) + if created.tzinfo is None: + raise ValueError + position = (created, item_id) + except (ValueError, UnicodeError, json.JSONDecodeError, ApiError): + raise ApiError(400, "invalid_request", "Некорректный cursor") from None + return limit, position + + +def next_page(items: list[dict], limit: int, scope: str) -> dict: + has_more = len(items) > limit + selected = items[:limit] + cursor = None + if has_more: + last = selected[-1] + payload = json.dumps([scope, last["created_at"], last["id"]], separators=(",", ":")) + cursor = base64.urlsafe_b64encode(payload.encode()).decode().rstrip("=") + return {"items": selected, "next_cursor": cursor} + + +class Handler(BaseHTTPRequestHandler): + server_version = "MTUSI-Lab3/1.0" + sys_version = "" + + def log_message(self, fmt: str, *args) -> None: + logging.info("%s %s %s", self.address_string(), self.command, urlsplit(self.path).path) + + def send_json(self, status: int, payload: dict | None, request_id: str, challenge: str | None = None): + data = (json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8") + if payload is not None else b"") + self.send_response(status) + self.send_header("X-Request-Id", request_id) + self.send_header("X-Instance-Id", INSTANCE_ID) + if payload is not None: + self.send_header("Content-Type", "application/json; charset=utf-8") + self.send_header("Content-Length", str(len(data))) + if challenge: + self.send_header("WWW-Authenticate", challenge) + self.end_headers() + if data: + self.wfile.write(data) + + def read_json(self) -> dict: + if self.headers.get("Content-Type", "").split(";", 1)[0].lower().strip() != "application/json": + raise ApiError(415, "unsupported_media_type", "Ожидается application/json") + try: + length = int(self.headers.get("Content-Length", "0")) + except ValueError: + raise ApiError(400, "invalid_request", "Некорректный Content-Length") from None + if length < 0 or length > MAX_BODY: + raise ApiError(413, "payload_too_large", "Слишком большое тело запроса") + try: + data = json.loads(self.rfile.read(length).decode("utf-8")) + except (ValueError, UnicodeError): + raise ApiError(400, "invalid_request", "Некорректный JSON") from None + if not isinstance(data, dict): + raise ApiError(400, "invalid_request", "JSON должен быть объектом") + return data + + def basic_credentials(self): + auth = self.headers.get("Authorization", "") + scheme, sep, value = auth.partition(" ") + fail = ApiError(401, "unauthorized", "Неверные credentials", + 'Basic realm="messenger", charset="UTF-8"') + if not sep or scheme.lower() != "basic": + raise fail + try: + decoded = base64.b64decode(value, validate=True).decode("utf-8") + except (ValueError, UnicodeError): + raise fail from None + if ":" not in decoded: + raise fail + username, password = decoded.split(":", 1) + if not username or not password: + raise fail + return username, password + + def bearer_user(self, conn) -> tuple[dict, str]: + auth = self.headers.get("Authorization", "") + scheme, sep, token = auth.partition(" ") + fail = ApiError(401, "unauthorized", "Требуется действительная Bearer-сессия", + 'Bearer realm="messenger"') + if not sep or scheme.lower() != "bearer" or not token or len(token) > 512: + raise fail + token_hash = hashlib.sha256(token.encode()).hexdigest() + row = conn.execute( + """SELECT u.id, u.username, u.display_name, u.created_at + FROM sessions s JOIN users u ON u.id=s.user_id + WHERE s.token_hash=%s AND s.expires_at > clock_timestamp()""", + (token_hash,)).fetchone() + if row is None: + raise fail + return row, token_hash + + def dispatch(self, rid: str): + parsed = urlsplit(self.path) + path, query = parsed.path, parse_qs(parsed.query, keep_blank_values=True) + if self.command == "GET" and path == "/health/live": + return self.send_json(200, {"status": "ok"}, rid) + if self.command == "GET" and path == "/health/ready": + with db_connect() as conn: + conn.execute("SELECT 1").fetchone() + return self.send_json(200, {"status": "ok"}, rid) + + if self.command == "POST" and path == "/api/v1/users": + body = self.read_json() + require_fields(body, {"username", "display_name", "password"}) + username, display, password = body["username"], body["display_name"], body["password"] + if not isinstance(username, str) or not USER_RE.fullmatch(username): + raise ApiError(400, "invalid_request", "Некорректный username") + if not isinstance(display, str) or not 1 <= len(display) <= 100 or not display.strip(): + raise ApiError(400, "invalid_request", "Некорректный display_name") + if not isinstance(password, str) or not 12 <= len(password) <= 128: + raise ApiError(400, "invalid_request", "Некорректный password") + # Unique constraint in PostgreSQL also handles concurrent registrations. + with db_connect() as conn: + exists = conn.execute("SELECT 1 FROM users WHERE username=%s", (username,)).fetchone() + if exists: + raise ApiError(409, "conflict", "Имя пользователя уже занято") + row = conn.execute( + """INSERT INTO users(id,username,display_name,password_hash) + VALUES (%s,%s,%s,%s) + RETURNING id,username,display_name,created_at""", + (str(uuid.uuid4()), username, display, password_hash(password))).fetchone() + return self.send_json(201, public_user(row), rid) + + if self.command == "POST" and path == "/api/v1/auth/sessions": + username, password = self.basic_credentials() + with db_connect() as conn: + row = conn.execute("SELECT * FROM users WHERE username=%s", (username,)).fetchone() + if row is None or not password_matches(password, row["password_hash"]): + raise ApiError(401, "unauthorized", "Неверные credentials", + 'Basic realm="messenger", charset="UTF-8"') + token = secrets.token_urlsafe(32) + expiry = datetime.now(timezone.utc) + timedelta(seconds=TTL) + conn.execute("INSERT INTO sessions(token_hash,user_id,expires_at) VALUES(%s,%s,%s)", + (hashlib.sha256(token.encode()).hexdigest(), row["id"], expiry)) + return self.send_json(201, {"token": token, "token_type": "Bearer", + "expires_at": stamp(expiry), "user": public_user(row)}, rid) + + with db_connect() as conn: + actor, token_hash = self.bearer_user(conn) + user_id = str(actor["id"]) + if self.command == "GET" and path == "/api/v1/users/me": + result = public_user(actor) + status = 200 + elif self.command == "DELETE" and path == "/api/v1/auth/sessions/current": + conn.execute("DELETE FROM sessions WHERE token_hash=%s", (token_hash,)) + result, status = None, 204 + elif self.command == "POST" and path == "/api/v1/chats": + body = self.read_json() + require_fields(body, {"title", "member_ids"}) + title, members = body["title"], body["member_ids"] + if not isinstance(title, str) or not 1 <= len(title) <= 100 or not title.strip(): + raise ApiError(400, "invalid_request", "Некорректный title") + if not isinstance(members, list) or not 1 <= len(members) <= 100: + raise ApiError(400, "invalid_request", "Некорректный список участников") + members = [uuid_string(x) for x in members] + if len(set(members)) != len(members) or user_id not in members: + raise ApiError(400, "invalid_request", "Участники должны быть уникальны, включая автора") + existing = conn.execute("SELECT id FROM users WHERE id = ANY(%s)", + ([uuid.UUID(x) for x in members],)).fetchall() + if len(existing) != len(members): + raise ApiError(400, "invalid_request", "Неизвестный участник") + chat_id = str(uuid.uuid4()) + conn.execute("INSERT INTO chats(id,title) VALUES(%s,%s)", (chat_id, title)) + for position, member_id in enumerate(members): + conn.execute("INSERT INTO chat_members(chat_id,user_id,member_index) VALUES(%s,%s,%s)", + (chat_id, member_id, position)) + result, status = fetch_chat(conn, chat_id), 201 + elif self.command == "GET" and path == "/api/v1/chats": + scope = "chats:" + user_id + limit, position = pagination(query, scope) + if position: + rows = conn.execute( + """SELECT c.id FROM chats c JOIN chat_members m ON m.chat_id=c.id + WHERE m.user_id=%s AND (c.created_at,c.id)>(%s,%s) + ORDER BY c.created_at,c.id LIMIT %s""", + (user_id, *position, limit + 1)).fetchall() + else: + rows = conn.execute( + """SELECT c.id FROM chats c JOIN chat_members m ON m.chat_id=c.id + WHERE m.user_id=%s ORDER BY c.created_at,c.id LIMIT %s""", + (user_id, limit + 1)).fetchall() + result = next_page([fetch_chat(conn, str(x["id"])) for x in rows], limit, scope) + status = 200 + else: + match = re.fullmatch(r"/api/v1/chats/([^/]+)(?:/(messages))?", path) + if not match or self.command not in {"GET", "POST"}: + raise ApiError(404, "not_found", "Объект не найден") + chat_id = uuid_string(match.group(1)) + member = conn.execute( + "SELECT 1 FROM chat_members WHERE chat_id=%s AND user_id=%s", + (chat_id, user_id)).fetchone() + if not member: + raise ApiError(404, "not_found", "Объект не найден") + section = match.group(2) + if self.command == "GET" and section is None: + result, status = fetch_chat(conn, chat_id), 200 + elif self.command == "GET" and section == "messages": + scope = "messages:" + chat_id + limit, position = pagination(query, scope) + if position: + rows = conn.execute( + """SELECT id,chat_id,sender_id,text,created_at FROM messages + WHERE chat_id=%s AND (created_at,id)>(%s,%s) + ORDER BY created_at,id LIMIT %s""", + (chat_id, *position, limit + 1)).fetchall() + else: + rows = conn.execute( + """SELECT id,chat_id,sender_id,text,created_at FROM messages + WHERE chat_id=%s ORDER BY created_at,id LIMIT %s""", + (chat_id, limit + 1)).fetchall() + result, status = next_page([public_message(x) for x in rows], limit, scope), 200 + elif self.command == "POST" and section == "messages": + key = self.headers.get("Idempotency-Key", "") + if not IDEMPOTENCY_RE.fullmatch(key): + raise ApiError(400, "invalid_request", "Требуется Idempotency-Key") + body = self.read_json() + require_fields(body, {"text"}) + value = body["text"] + if not isinstance(value, str) or not 1 <= len(value) <= 4000 or not value.strip(): + raise ApiError(400, "invalid_request", "Текст сообщения должен быть от 1 до 4000 символов") + digest = hashlib.sha256(json.dumps({"text": value}, sort_keys=True, + ensure_ascii=False, separators=(",", ":")).encode()).hexdigest() + # Transaction-level PG lock serializes two replicas using the same key. + # The message and its deduplication record commit together. + lock_key = user_id + ":POST:/api/v1/chats/" + chat_id + "/messages:" + key + conn.execute("SELECT pg_advisory_xact_lock(hashtext(%s))", (lock_key,)) + old = conn.execute( + """SELECT i.body_hash,m.id,m.chat_id,m.sender_id,m.text,m.created_at + FROM message_idempotency i JOIN messages m ON i.message_id=m.id + WHERE i.user_id=%s AND i.chat_id=%s AND i.idem_key=%s""", + (user_id, chat_id, key)).fetchone() + if old: + if old["body_hash"] != digest: + raise ApiError(409, "conflict", "Idempotency-Key уже использован для другого текста") + result = public_message(old) + else: + row = conn.execute( + """INSERT INTO messages(id,chat_id,sender_id,text) + VALUES(%s,%s,%s,%s) + RETURNING id,chat_id,sender_id,text,created_at""", + (str(uuid.uuid4()), chat_id, user_id, value)).fetchone() + conn.execute( + """INSERT INTO message_idempotency(user_id,chat_id,idem_key,body_hash,message_id) + VALUES(%s,%s,%s,%s,%s)""", + (user_id, chat_id, key, digest, row["id"])) + result = public_message(row) + status = 201 + else: + raise ApiError(404, "not_found", "Объект не найден") + self.send_json(status, result, rid) + + def do_GET(self): + self.handle_request() + + def do_POST(self): + self.handle_request() + + def do_DELETE(self): + self.handle_request() + + def handle_request(self): + rid = uuid.uuid4().hex + try: + self.dispatch(rid) + except ApiError as exc: + self.safe_json_error(exc, rid) + except psycopg.errors.UniqueViolation: + self.safe_json_error(ApiError(409, "conflict", "Объект уже существует"), rid) + except (psycopg.OperationalError, psycopg.errors.QueryCanceled) as exc: + logging.warning("Database unavailable: %s", type(exc).__name__) + self.safe_json_error(ApiError(503, "unavailable", "База данных недоступна"), rid) + except (BrokenPipeError, ConnectionResetError): + pass + except Exception: + logging.exception("Unexpected error (request_id=%s)", rid) + self.safe_json_error(ApiError(500, "internal_error", "Внутренняя ошибка сервера"), rid) + + def safe_json_error(self, exc: ApiError, rid: str): + try: + self.send_json(exc.status, + {"error": {"code": exc.code, "message": exc.message, "request_id": rid}}, + rid, exc.challenge) + except (BrokenPipeError, ConnectionResetError): + pass + + +class Server(ThreadingHTTPServer): + daemon_threads = True + allow_reuse_address = True + + +def main(): + logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s") + host = os.environ.get("APP_HOST", "0.0.0.0") + port = int(os.environ.get("APP_PORT", "8080")) + server = Server((host, port), Handler) + closing = threading.Event() + + def stop(_signal, _frame): + if not closing.is_set(): + closing.set() + threading.Thread(target=server.shutdown, daemon=True).start() + + signal.signal(signal.SIGTERM, stop) + signal.signal(signal.SIGINT, stop) + logging.info("API instance %s listening on %s:%s", INSTANCE_ID, host, port) + try: + server.serve_forever(poll_interval=0.1) + finally: + server.server_close() + + +if __name__ == "__main__": + main() diff --git a/tests_local/concurrent_idempotency.py b/tests_local/concurrent_idempotency.py new file mode 100644 index 00000000..fac778ea --- /dev/null +++ b/tests_local/concurrent_idempotency.py @@ -0,0 +1,41 @@ +"""Additional lab3 end-to-end test; requires ORIGINAL skeleton's tests/client.py. + +Creates one chat and posts an identical message 12 times through the load balancer. +""" +from concurrent.futures import ThreadPoolExecutor +from pathlib import Path +import sys +import uuid +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "tests")) +from client import Client, arguments, check, run + + +def main(): + args = arguments("Concurrent Idempotency-Key test for two replicas") + initial = Client(args.base_url, args.ca_file) + alice, bob, _, chat = initial.bootstrap() + key = uuid.uuid4().hex + text = "Один текст от параллельных реплик " + key + path = "/api/v1/chats/" + chat["id"] + "/messages" + + def send_one(_index): + client = Client(args.base_url, args.ca_file) + response = client.call("POST", path, 201, actor=alice, body={"text": text}, + headers={"Idempotency-Key": key}, schema="Message") + return response["json"], response["headers"]["X-Instance-Id"] + + with ThreadPoolExecutor(max_workers=12) as executor: + replies = list(executor.map(send_one, range(12))) + ids = {row["id"] for row, _ in replies} + check(len(ids) == 1, "different message IDs returned for one key") + check(all(row == replies[0][0] for row, _ in replies), "different responses for one key") + messages = initial.call("GET", path, actor=bob, schema="MessagePage")["json"]["items"] + check(len([m for m in messages if m["text"] == text]) == 1, + "duplicate in PostgreSQL message history") + instances = {inst for _, inst in replies} + print("PASS: 12 concurrent same-key POSTs => one durable message; observed instances:", + ", ".join(sorted(instances))) + + +if __name__ == "__main__": + run(main) diff --git a/tests_local/test_helpers.py b/tests_local/test_helpers.py new file mode 100644 index 00000000..6cd35fc3 --- /dev/null +++ b/tests_local/test_helpers.py @@ -0,0 +1,72 @@ +"""Fast pure-function checks; can run even without a local PostgreSQL/Docker install.""" +import base64 +from datetime import datetime, timezone +import importlib +import json +import sys +import types +import unittest +import uuid + +try: + import psycopg # noqa: F401 +except ImportError: + pg = types.ModuleType("psycopg") + pg.OperationalError = type("OperationalError", (Exception,), {}) + pg.errors = types.SimpleNamespace( + UniqueViolation=type("UniqueViolation", (Exception,), {}), + QueryCanceled=type("QueryCanceled", (Exception,), {}), + ) + sys.modules["psycopg"] = pg + rows = types.ModuleType("psycopg.rows") + rows.dict_row = lambda *args: None + sys.modules["psycopg.rows"] = rows + +import server + + +class HelpersTest(unittest.TestCase): + def test_password_kdf(self): + h1 = server.password_hash("test-pass-123456789") + h2 = server.password_hash("test-pass-123456789") + self.assertNotEqual(h1, h2) + self.assertTrue(server.password_matches("test-pass-123456789", h1)) + self.assertFalse(server.password_matches("WRONG", h1)) + + def test_uuid(self): + value = str(uuid.uuid4()) + self.assertEqual(server.uuid_string(value), value) + for invalid in ("abc", None, value.upper()): + with self.assertRaises(server.ApiError): + server.uuid_string(invalid) + + def test_cursor_page(self): + scope = "messages:" + str(uuid.uuid4()) + a, b = str(uuid.uuid4()), str(uuid.uuid4()) + items = [{"id": x, "created_at": "2026-11-16T12:00:00.000001Z"} for x in [a, b]] + result = server.next_page(items, 1, scope) + self.assertEqual(len(result["items"]), 1) + self.assertIsNotNone(result["next_cursor"]) + limit, position = server.pagination({"limit": ["1"], "cursor": [result["next_cursor"]]}, scope) + self.assertEqual(limit, 1) + self.assertEqual(position[1], a) + self.assertEqual(position[0], datetime(2026, 11, 16, 12, 0, 0, 1, tzinfo=timezone.utc)) + with self.assertRaises(server.ApiError): + server.pagination({"cursor": [result["next_cursor"]]}, "messages:another-chat") + + def test_limits(self): + with self.assertRaises(server.ApiError): + server.pagination({"limit": ["0"]}, "chats:alice") + with self.assertRaises(server.ApiError): + server.pagination({"limit": ["101"]}, "chats:alice") + with self.assertRaises(server.ApiError): + server.require_fields({"text": "hi", "extra": "no"}, {"text"}) + + def test_keys(self): + self.assertTrue(server.IDEMPOTENCY_RE.fullmatch("aB12_:-.z")) + self.assertFalse(server.IDEMPOTENCY_RE.fullmatch("bad key")) + self.assertFalse(server.IDEMPOTENCY_RE.fullmatch("")) + + +if __name__ == "__main__": + unittest.main() -- 2.54.0