ЛР-3 Варданян БПИ2304 на 3 #159

Closed
Gavarin23 wants to merge 3 commits from Gavarin23/mtusi2026lab3:solution/bpi2304-vardanyan into main
18 changed files with 948 additions and 180 deletions
+2 -16
View File
@@ -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
+2 -12
View File
@@ -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
+1 -27
View File
@@ -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.
+10
View File
@@ -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"]
+8 -11
View File
@@ -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
+110 -80
View File
@@ -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 <token>`.
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
+54 -20
View File
@@ -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, потому что её данные хранились в памяти; новая лаборатория запускается с чистой БД.
+11 -11
View File
@@ -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: {}
+83
View File
@@ -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:
+55
View File
@@ -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;
+3 -3
View File
@@ -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 преждевременно.
+30
View File
@@ -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;
}
}
}
+1
View File
@@ -0,0 +1 @@
psycopg[binary]==3.2.6
+5
View File
@@ -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
+8
View File
@@ -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
+452
View File
@@ -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()
+41
View File
@@ -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)
+72
View File
@@ -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()