ЛР3 - БВТ2304 - Травкин - на 5 #13

Closed
casablancawastaken wants to merge 7 commits from casablancawastaken/mtusi2026lab3:solution/bvt2304-travkin into main
99 changed files with 4495 additions and 19 deletions
+25
View File
@@ -0,0 +1,25 @@
FROM python:3.13.15-slim
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY alembic.ini .
COPY migrations ./migrations
COPY src ./src
RUN useradd --create-home --uid 10001 appuser
USER appuser
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)" || exit 1
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8080"]
+902 -19
View File
@@ -1,37 +1,920 @@
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Станислав Травкин, БВТ2304
- Целевая оценка: 5
- Текущий этап: реализованы и исследованы критерии оценок 3, 4 и 5;
- Выбранный трек оценки 5: цена масштабирования
- Commit/PR: будет указан после публикации
- Использованные источники: документация Docker Compose, FastAPI, SQLAlchemy, Alembic, PostgreSQL, Redis, Nginx; материалы лабораторной работы
- Помощь ИИ: ChatGPT использовался для обсуждения архитектуры, разработки, отладки и подготовки документации
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Для запуска необходимы Docker Engine с поддержкой Docker Compose, Git и Python 3.9 или новее.
Приложение работает в контейнерах. Локальная установка PostgreSQL и Redis не требуется.
Используемые образы:
- Python 3.13.15-slim
- PostgreSQL 17.6
- Redis 8.2.2
- Nginx 1.29-alpine
Из корневого каталога проекта выполнить:
```bash
./scripts/bootstrap.sh
docker compose config --quiet
docker compose up -d --build
docker compose ps -a
```
Скрипт `bootstrap.sh` создаёт локальные файлы секретов, если они отсутствуют, и проверяет конфигурацию Compose. Значения существующих секретов не перезаписываются.
Используются файлы:
- `secrets/postgres_password` — пароль PostgreSQL
- `secrets/database_url` — строка подключения к PostgreSQL
- `secrets/cache_url` — строка подключения к Redis
Секреты исключены из Git.
Миграции Alembic выполняются отдельным сервисом `migrate` перед запуском API. Успешное завершение контейнера миграций отображается как `Exited (0)`.
После запуска обе API-реплики должны иметь статус `healthy`, PostgreSQL и Redis — `healthy`, Nginx — `Up`.
Единая точка входа:
`http://localhost:8080`
Основные проверки:
```bash
make check
make validate
make test
make test-persistence ACTION_SCRIPT=./scripts/restart.sh
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
python3 tests/test_concurrent_idempotency.py
python3 tests/test_failover_concurrent_idempotency.py
python3 tests/test_review_regressions.py
```
Для локальных Python-проверок требуется установить зависимости из `requirements-dev.txt`, если они ещё не установлены.
После failover-тестов восстановить реплики:
```bash
docker compose start api-1 api-2
```
Безопасная остановка стенда с сохранением данных:
```bash
docker compose down
```
Повторный запуск:
```bash
docker compose up -d --build
```
Для намеренного удаления учебных данных и постоянных Docker volumes используется:
```bash
docker compose down -v
```
Последняя команда удаляет данные PostgreSQL и Redis и не применяется при обычном перезапуске.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Используется Docker Compose со следующими компонентами:
```text
Client
|
v
Nginx :8080
|
+---- API-1 :8080
|
+---- API-2 :8080
|
+---- PostgreSQL
|
+---- Redis
```
Nginx является единой публичной точкой входа. API-реплики не публикуют порты на хосте и доступны через внутреннюю сеть Compose.
Обе реплики используют одну PostgreSQL и один Redis.
PostgreSQL хранит постоянные данные приложения и информацию, необходимую для общей идемпотентности отправки сообщений. Redis хранит пользовательские сессии с TTL 3600 секунд.
В API не используются локальные пользовательские сессии, поэтому запросы одного пользователя могут обслуживаться разными репликами без повторной авторизации.
Каждая реплика возвращает заголовок `X-Instance-Id`, позволяющий определить обработавший запрос экземпляр.
Для отправки сообщений используется обязательный `Idempotency-Key`. Повторная отправка с тем же ключом не должна создавать второе сообщение. Согласованность между репликами обеспечивается общим PostgreSQL, транзакциями и механизмом advisory locks.
Миграции выполняются отдельным контейнером, что исключает одновременный запуск Alembic несколькими API-репликами.
В Nginx настроены два backend-сервера, динамическое разрешение DNS-имён контейнеров через Docker DNS, таймауты подключения и обработки запросов, а также повторная попытка при отдельных ошибках upstream.
Из лабораторной 2 перенесены основная реализация API, PostgreSQL, миграции, авторизация и работа с сообщениями. В лабораторной 3 добавлены балансировка, две API-реплики, идентификация экземпляров и общая идемпотентность.
Файл `.env.example` является шаблоном задания. Фактическая конфигурация контейнеров задаётся в `compose.yaml`; подключения к PostgreSQL и Redis передаются через файлы секретов.
### Проверки работоспособности и готовности
В приложении реализованы два endpoint:
- `GET /health/live` — проверяет работоспособность процесса API.
- `GET /health/ready` — проверяет доступность PostgreSQL и Redis.
При недоступности необходимой зависимости `/health/ready` возвращает HTTP 503.
Для API также настроен Docker HEALTHCHECK, обращающийся к `/health/ready`.
Это позволяет различать работающий процесс и экземпляр, готовый обслуживать запросы.
### Таймауты и завершение работы
Для подключения к PostgreSQL и Redis заданы ограничения времени ожидания. В Nginx настроены таймауты подключения, чтения и отправки запросов.
Для API установлен `stop_grace_period: 15s`.
При получении SIGTERM сервер Uvicorn завершает приложение штатно. В обработчике lifespan закрываются клиент Redis и пул соединений SQLAlchemy.
При ручной остановке `api-1` в логах наблюдались сообщения об успешном завершении приложения и серверного процесса.
### Ограничения ресурсов
В основной конфигурации для каждой API-реплики установлены 1 CPU и 512 MiB RAM. После замечания преподавателя ограничения добавлены также ко всем инфраструктурным сервисам. Фактические значения проверены командой `docker inspect` (поле `HostConfig`):
| Сервис | CPU | RAM | `NanoCpus` | `Memory`, байт |
|---|---:|---:|---:|---:|
| PostgreSQL | 1 | 768 MiB | 1000000000 | 805306368 |
| Redis | 0,5 | 256 MiB | 500000000 | 268435456 |
| Migrate | 1 | 512 MiB | 1000000000 | 536870912 |
| API-1 | 1 | 512 MiB | 1000000000 | 536870912 |
| API-2 | 1 | 512 MiB | 1000000000 | 536870912 |
| Nginx | 0,5 | 256 MiB | 500000000 | 268435456 |
Сервис `migrate` завершился с кодом 0; заданные ограничения подтверждены и для его завершившегося контейнера. Для API также задан `stop_grace_period: 15s`. При масштабировании API общий бюджет изменяется, если лимиты каждой реплики сохраняются. Поэтому проведены две серии: с фиксированным суммарным бюджетом и с растущим бюджетом.
### Секреты и сетевой доступ
API запускается от непривилегированного пользователя `appuser` с UID 10001. PostgreSQL использует пользователя `postgres` с UID 999.
API, PostgreSQL и Redis не публикуют порты на хосте. Внешний порт `8080` опубликован только у Nginx.
Секреты хранятся в локальном каталоге `secrets/`, исключённом из Git.
Скрипт `bootstrap.sh` устанавливает права:
- `700` для каталога `secrets/`
- `644` для файлов секретов
Каталог недоступен другим обычным пользователям хоста. При этом файлы с правами `644` после монтирования в контейнер доступны для чтения согласно правам файловой системы.
Это ограничение выбранной схемы Docker Compose с файловыми bind mounts. Для более строгой изоляции секретов необходим другой способ их предоставления контейнерам.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| Критерий | Команда или сценарий | Наблюдаемый результат | Доказательство |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Публичный smoke | `make test` | PASS | `evidence/smoke.txt` |
| Структура проекта | `make check` | PASS | Вывод проверки |
| OpenAPI | `make validate` | PASS | Вывод проверки |
| Две API-реплики | `docker compose ps -a` | Обе реплики healthy | `evidence/compose-status.txt` |
| Общая сессия | `make test-failover` | Сессия сохраняется после отказа реплики | `evidence/failover.txt` |
| Отказ реплики на оценку 3 | `make test-failover ACTION_SCRIPT=./scripts/stop-one.sh` | 55 успешных записей, 4 неудачные попытки, восстановление за 1,327 с | `evidence/failover.txt` |
| Сохранность данных | `make test-persistence ACTION_SCRIPT=./scripts/restart.sh` | PASS | `evidence/persistence.txt` |
| Конкурентная идемпотентность | `python3 tests/test_concurrent_idempotency.py` | 20 запросов, 1 уникальный ID, 1 сообщение в истории | `evidence/idempotency.txt` |
| Базовая нагрузка | `tests/load.py`, 30 с, 8 клиентов | 199,148 RPS, 0 ошибок | `evidence/load-baseline.json` |
| Остановка `api-1` под нагрузкой | `tests/load.py`, 45 с, 8 клиентов | 130,833 RPS, 0 ошибок | `evidence/load-failover-api1.json` |
| Остановка `api-2` под нагрузкой | `tests/load.py`, 45 с, 8 клиентов | 133,351 RPS, 0 ошибок | `evidence/load-failover-api2.json` |
| Failover `api-1` | `make test-failover` | PASS, восстановление за 1,311 с | `evidence/failover-grade4-api1.txt` |
| Failover `api-2` | `make test-failover` | PASS, восстановление за 1,339 с | `evidence/failover-grade4-second.txt` |
| Идемпотентность при отказе | `python3 tests/test_failover_concurrent_idempotency.py` | 20 запросов, 1 сообщение, PASS | `evidence/failover-concurrent-idempotency.txt` |
| Rolling replacement | Поочерёдное пересоздание API под нагрузкой | 16927 успешных запросов, 1 ошибка | `evidence/load-rolling.json` |
| Ограничения CPU/RAM | `docker inspect` для шести сервисов | Все значения `NanoCpus` и `Memory` ненулевые; таблица выше | Вывод проверки 22.10.2026 |
| Регрессии по замечаниям | `python3 tests/test_review_regressions.py` | PASS: UTF-8 Basic Auth, двоеточие в пароле, курсор чатов, последняя страница, некорректный курсор | Вывод проверки 22.10.2026 |
| Растущий бюджет 1/2/4 | `./scripts/run_growing_scale.sh` | 289,590 / 425,950 / 601,701 RPS, по три прогона, ошибок 0 | `evidence/scale/growing/` |
| Оптимизация «до/после» | `./scripts/run_optimization.sh` | 4 → 2 реплики при 2 CPU / 1024 MiB; RPS +6,2%, p95 −29,3%, p99 −42,1%, ошибок 0 | `evidence/scale/optimization/` |
| Закрытые внутренние порты | `docker compose ps` | На хост опубликован только порт Nginx | Результат проверки |
| Корректное завершение | `docker compose stop api-1` | Штатное завершение Uvicorn | Логи контейнера |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
### Оценка 3 — отказ API-реплики
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
Команда:
## Ограничения и следующие шаги
```bash
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
```
Полученные результаты:
- Наблюдаемых реплик до отказа: 2
- Успешных записей: 55
- Неудачных попыток: 4
- Время до первого успешного восстановления: 1,327 с
- Подтверждённые данные: сохранены
- Существующая сессия: сохранена
Дополнительно вручную проверена остановка каждой реплики с восстановлением предыдущей. В обоих случаях оставшаяся реплика продолжала обслуживать запросы через Nginx.
### Оценка 3 — сохранность данных
Команда:
```bash
make test-persistence ACTION_SCRIPT=./scripts/restart.sh
```
Результат: PASS.
После перезапуска PostgreSQL, Redis и API подтверждённые данные и существующая сессия остались доступными.
### Оценка 3 — конкурентная идемпотентность
Команда:
```bash
python3 tests/test_concurrent_idempotency.py
```
Результаты:
- Параллельных запросов: 20
- Уникальных идентификаторов сообщений: 1
- Наблюдаемые реплики: `api-1`, `api-2`
- Совпадающих сообщений в истории: 1
- Итог: PASS
Таким образом, конкурентные запросы с одинаковым ключом не создали дублирующих сообщений.
### Оценка 4 — базовая нагрузка
Команда:
```bash
python3 tests/load.py --duration 30 --concurrency 8 --output evidence/load-baseline.json
```
Результаты:
| Показатель | Значение |
| --- | ---: |
| Продолжительность | 30,038 с |
| Успешные запросы | 5982 |
| Ошибки | 0 |
| Пропускная способность | 199,148 RPS |
| p50 | 33,537 мс |
| p95 | 86,622 мс |
| p99 | 201,671 мс |
Полученные значения используются как базовый ориентир для сравнения с экспериментами при остановке реплик.
### Оценка 4 — последовательная остановка реплик под нагрузкой
Для проверки устойчивости выполнялись отдельные нагрузочные испытания с последовательной остановкой `api-1` и `api-2`.
В каждом эксперименте нагрузка создавалась восемью параллельными клиентами. Примерно через 10 секунд после начала испытания останавливалась одна из реплик.
После завершения испытания реплика восстанавливалась перед следующим экспериментом.
| Сценарий | Продолжительность | Успешные запросы | Ошибки | RPS | p50 | p95 | p99 |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| Без отказа | 30,038 с | 5982 | 0 | 199,148 | 33,537 мс | 86,622 мс | 201,671 мс |
| Остановка `api-1` | 45,073 с | 5897 | 0 | 130,833 | 54,133 мс | 112,499 мс | 216,195 мс |
| Остановка `api-2` | 45,084 с | 6012 | 0 | 133,351 | 52,247 мс | 115,109 мс | 208,774 мс |
Доказательства:
- `evidence/load-baseline.json`
- `evidence/load-failover-api1.json`
- `evidence/load-failover-api2.json`
В обоих сценариях остановки приложение продолжило обслуживать запросы через оставшуюся реплику.
Ошибок в этих двух нагрузочных прогонах не зафиксировано. Пропускная способность была ниже базовой, а задержки увеличились.
При интерпретации результатов необходимо учитывать различную длительность базового и отказных испытаний, а также возможные колебания производительности тестового окружения.
### Оценка 4 — проверка восстановления после отказа
Отдельно выполнен сценарий проверки отказоустойчивости с остановкой каждой реплики.
Команда:
```bash
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
```
Для проверки `api-2` использовалась настройка `TARGET_INSTANCE_ID`.
Результаты:
| Остановленная реплика | Наблюдаемых реплик до отказа | Успешные записи | Неудачные попытки | Первое восстановление | Итог |
| --- | ---: | ---: | ---: | ---: | --- |
| `api-1` | 2 | 65 | 3 | 1,311 с | PASS |
| `api-2` | 2 | 81 | 2 | 1,339 с | PASS |
Доказательства:
- `evidence/failover-grade4-api1.txt`
- `evidence/failover-grade4-second.txt`
Оба испытания завершились успешно.
Время восстановления характеризует момент первого успешного запроса, наблюдаемый тестовым клиентом. Оно не является отдельным измерением времени обнаружения отказа балансировщиком.
Наличие нескольких неудачных попыток показывает, что переключение не было абсолютно бесшовным.
### Оценка 4 — конкурентная идемпотентность при отказе
Команда:
```bash
python3 tests/test_failover_concurrent_idempotency.py
```
Тест создаёт 20 конкурентных запросов с одинаковым `Idempotency-Key` и инициирует остановку `api-1`.
После завершения конкурентных запросов выполняется повторная отправка с тем же ключом и проверяется история сообщений.
Результаты:
- Конкурентных запросов: 20
- Успешных запросов: 20
- Неудачных запросов: 0
- Наблюдаемые реплики: `api-1`, `api-2`
- Уникальных ID успешных ответов: 1
- Сообщений с проверяемым текстом в истории: 1
- Повторная отправка вернула тот же ID
- Итог: PASS
Доказательство:
`evidence/failover-concurrent-idempotency.txt`
Эксперимент подтвердил, что при конкурентных запросах и инициированной остановке одной реплики не появились дублирующие сообщения.
Ограничение эксперимента: все 20 запросов завершились успешно. Сам факт одновременного запуска запросов и остановки контейнера не доказывает, что конкретный запрос был прерван непосредственно во время записи в PostgreSQL.
### Оценка 4 — rolling replacement
Для проверки обновления без полной остановки сервиса выполнялось последовательное пересоздание API-реплик под постоянной нагрузкой.
Нагрузочный тест:
```bash
python3 tests/load.py --duration 90 --concurrency 8 --output evidence/load-rolling.json
```
Во время его выполнения поочерёдно запускались команды:
```bash
docker compose up -d --no-deps --force-recreate api-1
docker compose up -d --no-deps --force-recreate api-2
```
Между пересозданиями проверялись готовность API и ответы через Nginx. При проверке наблюдались ответы от обеих реплик.
Nginx, PostgreSQL и Redis во время пересоздания API не перезапускались.
Результаты:
| Показатель | Значение |
| --- | ---: |
| Продолжительность | 90,037 с |
| Успешные запросы | 16927 |
| Ошибки | 1 |
| Доля ошибок | Около 0,0059 % |
| Пропускная способность | 188,0 RPS |
| p50 | 33,878 мс |
| p95 | 99,116 мс |
| p99 | 199,301 мс |
Доказательство:
`evidence/load-rolling.json`
Во время последовательного пересоздания реплик сервис в целом оставался доступным, однако зарегистрирована одна ошибка.
Поэтому результат нельзя характеризовать как обновление с гарантированным отсутствием ошибок. Эксперимент подтверждает возможность поочерёдного обновления при сохранении обслуживания большинства запросов.
### Оценка 4 — проверка ограничений и завершения
Проверка Docker показала, что на каждую API-реплику действуют ограничения 1 CPU и 512 MiB RAM.
При ручной остановке `api-1` контейнер завершился с кодом 0. В логах Uvicorn наблюдалось штатное завершение приложения.
После восстановления реплика снова получила статус `healthy`.
Проверка опубликованных портов подтвердила, что на хосте доступен только Nginx на порту 8080.
API-реплики, PostgreSQL и Redis доступны через внутреннюю сеть Docker Compose.
### Проверка изолированного окружения
На этапе оценки 3 дополнительно проводились проверки с отдельным именем проекта Docker Compose и чистыми Docker volumes.
Функциональные проверки, сохранность данных, отказоустойчивость и конкурентная идемпотентность в таком окружении завершились успешно.
Это подтверждает воспроизводимость запуска на новом наборе volumes в использованной локальной среде.
Полностью независимый запуск на другом компьютере из нового клона репозитория отдельно не подтверждён.
## Ограничения
PostgreSQL, Redis и Nginx представлены одиночными экземплярами и остаются едиными точками отказа.
При недоступности PostgreSQL или Redis API может потерять готовность к обслуживанию запросов. Репликация и автоматическое переключение этих компонентов не реализованы.
Nginx способен перенаправлять запросы на доступную API-реплику, но отдельные запросы во время отказа или обновления всё равно могут завершиться ошибкой.
Нагрузочный генератор `tests/load.py` создаёт фиксированное число конкурентных клиентов и измеряет успешную пропускную способность и задержки. Он не обеспечивает точное поддержание заданного входящего RPS.
Поэтому полученные значения характеризуют пропускную способность в выбранном режиме нагрузки, а не максимальную производительность системы при произвольном входящем потоке.
В нагрузочных результатах отсутствует детальная посекундная разбивка ошибок и задержек. Время восстановления измеряется отдельно тестом отказоустойчивости.
Секреты хранятся вне Git, но файловая схема Docker Compose с правами `644` не обеспечивает строгой изоляции содержимого от всех процессов, имеющих доступ к смонтированным файлам.
Испытания проведены в одном локальном окружении. Результаты зависят от характеристик компьютера, Docker, нагрузки и состояния базы данных.
## Итоги оценки 4
Выполнены следующие проверки:
- Две API-реплики за балансировщиком Nginx.
- Общие PostgreSQL и Redis.
- Общая авторизация и идемпотентность между репликами.
- Проверки `/health/live` и `/health/ready`.
- Таймауты подключения и обработки запросов.
- Корректное завершение приложения при SIGTERM.
- Ограничения CPU и RAM.
- Отсутствие прямой публикации внутренних сервисов.
- Однократное выполнение миграций отдельным контейнером.
- Остановка каждой API-реплики под нагрузкой.
- Проверка времени восстановления после отказа.
- Конкурентная идемпотентность при инициированном отказе.
- Поочерёдное пересоздание реплик под нагрузкой.
- Хранение секретов вне Git.
Базовая пропускная способность в проведённом испытании составила 199,148 успешного запроса в секунду.
При остановке одной реплики оставшаяся продолжала обслуживать запросы. В отдельных failover-проверках первое успешное восстановление наблюдалось через 1,311 и 1,339 секунды.
При rolling replacement зарегистрирована одна ошибка на 16928 попыток.
Таким образом, реализована и экспериментально проверена устойчивость к отказу одной API-реплики. Полная безошибочность переключения и отсутствие единых точек отказа для всей инфраструктуры не заявляются.
## Оценка 5 — исследование цены масштабирования
### Цель эксперимента
Исследовать влияние количества API-реплик на пропускную способность и задержки приложения при фиксированном суммарном бюджете CPU и RAM.
Сравниваются конфигурации с 1, 2 и 4 API-репликами. PostgreSQL, Redis и Nginx остаются общими компонентами системы.
### Методика
Для всех конфигураций установлен одинаковый суммарный лимит ресурсов API: 2 CPU и 1024 MiB RAM.
| API-реплик | CPU на реплику | RAM на реплику | Общий CPU | Общая RAM |
|---|---|---|---|---|
| 1 | 2 | 1024 MiB | 2 | 1024 MiB |
| 2 | 1 | 512 MiB | 2 | 1024 MiB |
| 4 | 0,5 | 256 MiB | 2 | 1024 MiB |
Конфигурации запускаются с использованием `compose.yaml` и `compose.scale.yaml`. Для каждого количества реплик подготовлена отдельная конфигурация Nginx.
Нагрузочные испытания выполняются скриптом `tests/load.py`. Генератор использует закрытую модель нагрузки с фиксированным количеством конкурентных клиентов, отправляющих POST-запросы на создание сообщений. Автоматические повторные попытки отсутствуют.
Первоначально для каждой конфигурации проведены тесты продолжительностью 60 секунд с 8, 16, 32 и 64 конкурентными клиентами.
Для сравнения воспроизводимости дополнительно выполнены повторные прогоны при 16 клиентах. В итоговом сравнении используются три измерения для каждой конфигурации.
Измеряются успешные запросы в секунду (RPS), задержки p50, p95, p99 и количество ошибок.
Исходные результаты сохранены в `evidence/scale/`. Скрипт `scripts/analyze_scale.py` вычисляет агрегированные показатели и формирует графики.
### Результаты при 16 клиентах
| API-реплик | RPS, прогон 1 | RPS, прогон 2 | RPS, прогон 3 | Средний RPS | Стандартное отклонение RPS |
|---|---|---|---|---|---|
| 1 | 145,953 | 142,549 | 142,668 | 143,723 | 1,932 |
| 2 | 224,292 | 210,316 | 228,380 | 220,996 | 9,472 |
| 4 | 106,885 | 97,026 | 108,340 | 104,084 | 6,155 |
Средние значения перцентилей отдельных прогонов:
| API-реплик | Средний p95 | Средний p99 | Ошибок за три прогона |
|---|---|---|---|
| 1 | 135,946 мс | 158,606 мс | 0 |
| 2 | 129,875 мс | 371,534 мс | 0 |
| 4 | 572,950 мс | 1152,931 мс | 0 |
При одинаковом суммарном бюджете ресурсов конфигурация с двумя репликами показала наибольшую пропускную способность — 220,996 RPS.
По сравнению с одной репликой прирост составил около 53,8%. При переходе с двух реплик на четыре пропускная способность, напротив, снизилась примерно на 52,9%.
При этом минимальное среднее значение p99 наблюдалось у одной реплики. Следовательно, выбор конфигурации зависит не только от максимального RPS, но и от требований к задержкам.
### Графики
Пропускная способность при 16 конкурентных клиентах:
![Пропускная способность](evidence/scale/charts/throughput.png)
Задержки p95 и p99:
![Задержки](evidence/scale/charts/latency.png)
На первом графике столбики погрешности обозначают выборочное стандартное отклонение RPS трёх прогонов.
На втором графике приведены средние значения перцентилей отдельных прогонов. Они не являются перцентилями объединённой выборки всех запросов.
### Диагностика ограничений CPU
Для конфигурации с четырьмя репликами дополнительно исследовано использование CPU.
Проверка параметров cgroup показала, что каждой реплике установлена квота 50000 микросекунд процессорного времени на период 100000 микросекунд, что соответствует 0,5 CPU.
Во время отдельного нагрузочного испытания зафиксировано ограничение процессорного времени (CPU throttling). Доля периодов с throttling составила приблизительно:
| Реплика | Доля периодов с throttling |
|---|---|
| api-1 | 55,0% |
| api-2 | 35,8% |
| api-3 | 41,4% |
| api-4 | 37,8% |
Во время нагрузки наблюдалось использование CPU около установленного лимита, тогда как потребление памяти составляло примерно 70 MiB на реплику при лимите 256 MiB.
Это согласуется с предположением о существенном влиянии процессорных ограничений на результаты четырёх реплик.
### Дополнительный диагностический эксперимент
Для проверки влияния CPU-квоты проведён отдельный эксперимент с четырьмя репликами и 16 конкурентными клиентами.
CPU-квота каждой реплики временно увеличена с 0,5 до 1 CPU. Лимит памяти не изменялся.
При суммарном лимите 4 CPU получены следующие результаты:
- Успешная пропускная способность: 353,146 RPS.
- p50: 31,047 мс.
- p95: 125,895 мс.
- p99: 300,611 мс.
- Ошибок: 0.
Это приблизительно на 239,3% выше средней пропускной способности четырёх реплик при суммарном лимите 2 CPU.
Однако данный эксперимент использовал вдвое больший CPU-бюджет, поэтому его нельзя считать прямым сравнением эффективности масштабирования при одинаковых ресурсах.
После эксперимента ограничения четырёх реплик были возвращены к 0,5 CPU.
Результат свидетельствует о чувствительности производительности к доступному процессорному времени, но сам по себе не доказывает, что всё снижение производительности четырёх реплик вызвано исключительно CPU throttling.
### Ограничения исследования
Испытания выполнялись в одном локальном окружении. На результаты могли влиять фоновая нагрузка компьютера, планировщик CPU, состояние PostgreSQL и Redis, прогрев системы и накопление данных в базе.
Для каждой конфигурации при 16 клиентах проведено три прогона. Это позволяет оценить повторяемость результатов, но недостаточно для строгих статистических выводов.
Генератор использует закрытую модель нагрузки, поэтому результаты зависят от задержек ответов и производительности самого клиента. Возможны coordinated omission и дополнительная нагрузка со стороны генератора.
PostgreSQL, Redis и Nginx не масштабировались вместе с API. Поэтому эксперимент характеризует масштабирование API при фиксированной общей инфраструктуре.
Зафиксированы признаки CPU throttling, однако влияние других факторов на снижение производительности четырёх реплик полностью не исключено.
### Экспериментальная оптимизация CPU-периода
В качестве дополнительной оптимизации проверено изменение периода CPU-квоты для четырёх API-реплик при неизменном суммарном бюджете ресурсов.
В исходной конфигурации каждая реплика имела период 100000 мкс и квоту 50000 мкс. В экспериментальной конфигурации период увеличен до 200000 мкс, а квота — до 100000 мкс. В обоих случаях лимит каждой реплики составлял 0,5 CPU, суммарный бюджет — 2 CPU и 1024 MiB RAM.
Для экспериментальной конфигурации проведено три нагрузочных теста продолжительностью 60 секунд с 16 конкурентными клиентами.
| Прогон | RPS | p95 | p99 | Ошибок |
|---|---:|---:|---:|---:|
| 1 | 86,649 | 888,403 мс | 1559,440 мс | 1 |
| 2 | 85,505 | 925,831 мс | 1351,136 мс | 0 |
| 3 | 85,683 | 890,303 мс | 1366,728 мс | 0 |
| Среднее | 85,946 | 901,512 мс | 1425,768 мс | — |
Сравнение со стандартным периодом 100 мс:
| Метрика | Период 100 мс | Период 200 мс | Изменение |
|---|---:|---:|---:|
| Средний RPS | 104,084 | 85,946 | −17,4% |
| Средний p95 | 572,950 мс | 901,512 мс | +57,3% |
| Средний p99 | 1152,931 мс | 1425,768 мс | +23,7% |
| Ошибок за три прогона | 0 | 1 | — |
Увеличение CPU-периода не привело к улучшению производительности. Средняя пропускная способность снизилась на 17,4%, а задержки p95 и p99 увеличились.
Следовательно, предложенная оптимизация оказалась неэффективной в исследованных условиях. При этом результаты не позволяют утверждать, что увеличение CPU-периода всегда ухудшает производительность: вывод относится к данному приложению, окружению и выбранной нагрузке.
После эксперимента восстановлена стандартная конфигурация с двумя API-репликами.
Результаты сохранены в `evidence/scale/replicas-4-c16-period200.json`, `evidence/scale/replicas-4-c16-period200-repeat.json` и `evidence/scale/replicas-4-c16-period200-repeat2.json`.
### Вторая серия: растущий суммарный бюджет CPU и RAM
Для отделения влияния числа реплик от влияния выделенных ресурсов проведена дополнительная серия. В отличие от основной серии с фиксированным бюджетом, каждая API-реплика получает 1 CPU и 512 MiB RAM. PostgreSQL, Redis и Nginx остаются общими компонентами, их лимиты не увеличиваются. Использован скрипт `./scripts/run_growing_scale.sh`.
| API-реплик | CPU на реплику | RAM на реплику | Общий CPU API | Общая RAM API |
|---|---:|---:|---:|---:|
| 1 | 1 | 512 MiB | 1 | 512 MiB |
| 2 | 1 | 512 MiB | 2 | 1024 MiB |
| 4 | 1 | 512 MiB | 4 | 2048 MiB |
Для каждого варианта: 16 конкурентных клиентов, 15 секунд прогрева, затем три измерения по 60 секунд; запросы `POST` на создание сообщений, закрытая модель нагрузки, без автоматических повторных попыток. Между вариантами Compose-стенд пересоздавался без `down -v`. Все API-реплики становились `healthy`. Итоговые средние и стандартные отклонения вычислены по трём прогонам.
| API-реплик | Средний RPS | Стандартное отклонение RPS | Средний p95 | Средний p99 | Ошибок за три прогона |
|---|---:|---:|---:|---:|---:|
| 1 | 289,590 | 3,160 | 72,661 мс | 106,882 мс | 0 |
| 2 | 425,950 | 4,614 | 63,237 мс | 93,203 мс | 0 |
| 4 | 601,701 | 4,421 | 41,706 мс | 79,650 мс | 0 |
При переходе от 1 к 2 репликам средний RPS увеличился на 47,1%; от 2 к 4 — на 41,3%; от 1 к 4 — на 107,8%. Средний p95 при переходе от 1 к 4 репликам уменьшился на 42,6%. Это подтверждает положительный эффект добавления API-ресурсов в данной серии, но не доказывает линейного масштабирования: при четырёхкратном CPU-бюджете RPS вырос примерно в 2,08 раза.
В первой серии общий бюджет API составлял 2 CPU и 1024 MiB для всех вариантов, поэтому там сравнивалась **цена распределения фиксированных ресурсов**. В этой серии бюджет API увеличивался пропорционально числу реплик, поэтому она показывает **эффект добавления ресурсов**. Числа RPS между сериями нельзя использовать как строгое сравнение «до/после» изменения приложения: менялись ресурсные лимиты и состояние экспериментального окружения.
Доказательства: JSON-файлы измерений в `evidence/scale/growing/`, вывод `./scripts/run_growing_scale.sh` и агрегирование `python3 scripts/summarize_growing_scale.py`. Исходные JSON-файлы должны быть включены в коммит вместе с отчётом.
### Контрольный эксперимент «до/после»: оптимизация числа реплик
После неудачного эксперимента с изменением CPU-периода выполнен отдельный контрольный эксперимент по выбору числа API-реплик. Проверялась гипотеза, что при фиксированном суммарном бюджете уменьшение числа реплик с четырёх до двух повысит пропускную способность и снизит задержки. Это **оптимизация конфигурации развёртывания**, а не изменение кода приложения.
В обеих конфигурациях суммарный бюджет API равен 2 CPU и 1024 MiB RAM. Код приложения, генератор нагрузки, число клиентов и лимиты инфраструктурных сервисов не менялись. При переключении пересоздавались контейнеры, но Docker volumes не удалялись; менялись число API-реплик, распределение их квот и список upstream-серверов Nginx.
| Условие | До оптимизации | После оптимизации |
|---|---:|---:|
| API-реплики | 4 | 2 |
| CPU на реплику | 0,5 | 1 |
| RAM на реплику | 256 MiB | 512 MiB |
| Суммарный бюджет API | 2 CPU / 1024 MiB | 2 CPU / 1024 MiB |
| Конкурентные клиенты | 16 | 16 |
| Прогрев | 15 с | 15 с |
| Основные измерения | 3 × 60 с | 3 × 60 с |
Использована закрытая модель нагрузки `POST`-запросами на создание сообщений без автоматических повторных попыток. Для каждой конфигурации выполнены прогрев и три отдельных измерения.
| Метрика | До: 4 реплики | После: 2 реплики | Изменение |
|---|---:|---:|---:|
| RPS, прогон 1 | 403,177 | 417,559 | — |
| RPS, прогон 2 | 392,746 | 416,933 | — |
| RPS, прогон 3 | 386,841 | 421,396 | — |
| Средний RPS | 394,255 | 418,629 | +6,2% |
| Средний p95 | 91,445 мс | 64,615 мс | −29,3% |
| Средний p99 | 165,019 мс | 95,539 мс | −42,1% |
| Ошибок за три прогона | 0 | 0 | — |
**Подтверждённое улучшение:** при переходе от четырёх к двум репликам средний RPS вырос на 6,2%, средний p95 уменьшился на 29,3%, а средний p99 — на 42,1%. Во всех шести основных прогонах ошибок не зафиксировано. При этом каждый из трёх прогонов конфигурации «после» показал больший RPS, чем любой из трёх прогонов «до».
Результат согласуется с гипотезой о преимуществах двух реплик при ограниченном бюджете, но конкретный вклад CPU throttling, планировщика и других накладных расходов в этом контрольном эксперименте отдельно не измерялся. Результаты отличаются по абсолютному RPS от ранней серии с фиксированным бюджетом; сравнивать их напрямую как единый эксперимент некорректно из-за возможных изменений состояния стенда и базы данных. Вывод «до/после» основан только на шести прогонах новой контрольной серии.
Исходные JSON-файлы: `evidence/scale/optimization/before-run1.json` — `before-run3.json` и `after-run1.json` — `after-run3.json`; файлы прогрева хранятся в том же каталоге. Скрипт `scripts/run_optimization.sh` воспроизводит эксперимент и восстанавливает обычную конфигурацию с двумя репликами. Испытание проведено в одном локальном окружении при 16 клиентах; результат не следует обобщать на все нагрузки и оборудование.
### Сопоставление с предыдущими экспериментами
В исходной серии с фиксированным бюджетом конфигурация с двумя репликами также оказалась быстрее четырёх (220,996 против 104,084 RPS). Однако это отдельная серия с иными абсолютными результатами; её нельзя объединять с новым контрольным экспериментом при расчёте процента улучшения.
Во второй серии с растущим бюджетом четыре реплики достигли 601,701 RPS при 4 CPU и 2048 MiB RAM суммарно. Поэтому преимущество двух реплик относится к **фиксированному бюджету**, а не к любым условиям масштабирования. Эксперимент с изменением CPU-периода остался отрицательным (−17,4% RPS) и не рассматривается как успешная оптимизация.
### Итоговые выводы
В работе исследована цена горизонтального масштабирования API в двух режимах: при фиксированном суммарном бюджете 2 CPU и 1024 MiB RAM и при увеличении бюджета от 1 CPU / 512 MiB до 4 CPU / 2048 MiB.
В исходной серии с фиксированным бюджетом при 16 конкурентных клиентах конфигурация с двумя репликами обеспечила максимальную среднюю пропускную способность — 220,996 RPS. Это приблизительно на 53,8% больше, чем у одной реплики, и на 112,3% больше, чем у четырёх.
При этом одна реплика показала наименьшую среднюю задержку p99 — 158,606 мс. Следовательно, оптимальный выбор зависит от требований к пропускной способности и задержкам.
Диагностика четырёх реплик выявила CPU throttling. Дополнительный эксперимент с увеличенным CPU-бюджетом подтвердил чувствительность приложения к доступному процессорному времени, но не позволил однозначно установить единственную причину снижения производительности.
Попытка оптимизации путём увеличения периода CPU-квоты со 100 до 200 мс при сохранении общего бюджета оказалась неэффективной: RPS снизился на 17,4%.
По результатам исследования для данной нагрузки выбрана конфигурация с двумя API-репликами по 1 CPU и 512 MiB RAM. В отдельном контрольном эксперименте «до/после» при том же суммарном бюджете она обеспечила 418,629 RPS против 394,255 RPS у четырёх реплик (+6,2%) и снизила средние p95 и p99 на 29,3% и 42,1% соответственно. Это подтверждённое конфигурационное улучшение без увеличения общего бюджета API.
Во второй серии с растущим бюджетом средний RPS вырос с 289,590 (1 реплика) до 601,701 (4 реплики), без ошибок за девять измерений. Таким образом, горизонтальное масштабирование необходимо оценивать экспериментально: увеличение числа реплик само по себе не гарантирует повышения производительности, а выделение дополнительных ресурсов способно изменить результат.
## Команды для демонстрации
Все команды выполняются из корневого каталога проекта. Команды с `docker compose down` останавливают стенд, но без `-v` сохраняют постоянные данные PostgreSQL. Для демонстрации достаточно начать с обычной конфигурации двух реплик. Запуск тестов создаёт учебные записи в базе; повторные измерения на изменившемся состоянии базы могут отличаться от приведённых в отчёте.
### 1. Подготовка и запуск
```bash
./scripts/bootstrap.sh
docker compose config --quiet
docker compose up -d --build
docker compose ps -a
```
При первом запуске локальных Python-тестов установить зависимости в виртуальное окружение:
```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
```
Если `.venv` уже существует и зависимости установлены, повторять создание окружения не нужно. Для проверки миграций и журналов:
```bash
docker compose ps -a
docker compose logs --tail=50 migrate
docker compose logs --tail=30 api-1 api-2 nginx
```
Сервис `migrate` должен завершиться с кодом 0; две реплики API, PostgreSQL и Redis должны быть `healthy`.
### 2. Проверка API, балансировки и изоляции
```bash
curl -i http://localhost:8080/health/live
curl -i http://localhost:8080/health/ready
for i in $(seq 1 12); do curl -s -D - -o /dev/null http://localhost:8080/health/live | grep -i '^x-instance-id:'; done
docker compose ps
docker compose port nginx 8080
```
В заголовке `X-Instance-Id` при повторных запросах ожидаются ответы от `api-1` и `api-2`. Порты API, PostgreSQL и Redis на хост не публикуются; точка входа — Nginx на `localhost:8080`.
Проверка ресурсных ограничений и запуска API от непривилегированного пользователя:
```bash
for i in 1 2; do docker inspect mtusi2026lab3-api-$i-1 --format '{{.Name}} NanoCpus={{.HostConfig.NanoCpus}} Memory={{.HostConfig.Memory}} StopTimeout={{.HostConfig.StopTimeout}}'; done
docker compose exec -T api-1 id
docker stats --no-stream
```
### 3. Функциональные тесты и отказоустойчивость
```bash
make check
make validate
make test
make test-persistence ACTION_SCRIPT=./scripts/restart.sh
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
python3 tests/test_concurrent_idempotency.py
python3 tests/test_failover_concurrent_idempotency.py
docker compose start api-1 api-2
docker compose ps
```
Тесты проверяют контракт, сохранность данных, работу сессии при отказе и отсутствие дублирования сообщения при конкурентной отправке с одинаковым `Idempotency-Key`. После сценариев отказа необходимо восстановить обе реплики.
Для ручного показа остановки одной реплики и восстановления:
```bash
docker compose stop api-1
curl -i http://localhost:8080/health/ready
docker compose ps
docker compose start api-1
docker compose ps
```
### 4. Нагрузка и последовательное обновление на оценку 4
Базовый нагрузочный тест:
```bash
python3 tests/load.py --duration 30 --concurrency 8 --output evidence/load-demo.json
```
Для демонстрации rolling replacement запустить нагрузку в первом терминале:
```bash
python3 tests/load.py --duration 90 --concurrency 8 --output evidence/load-rolling-demo.json
```
Пока идёт тест, во втором терминале поочерёдно выполнить:
```bash
docker compose up -d --no-deps --force-recreate api-1
docker compose ps
docker compose up -d --no-deps --force-recreate api-2
docker compose ps
```
После теста посмотреть JSON-файл с RPS, задержками и ошибками. Пересоздание под нагрузкой не гарантирует нулевое число ошибок: в исходном эксперименте была зафиксирована одна ошибка.
### 5. Воспроизведение сравнения 1, 2 и 4 реплик на оценку 5
Используются `compose.yaml`, `compose.scale.yaml` и конфигурации Nginx в `infra/scale/`. Для каждого варианта общий лимит API одинаков: 2 CPU и 1024 MiB RAM. Переход между вариантами выполняется с остановкой предыдущего стенда. Команды не используют `down -v`, поэтому накопленные данные сохраняются.
Одна реплика — 2 CPU и 1024 MiB:
```bash
docker compose -f compose.yaml -f compose.scale.yaml down
API_REPLICAS=1 API_CPUS=2.0 API_MEMORY=1024m docker compose -f compose.yaml -f compose.scale.yaml up -d --build postgres redis migrate api-1 nginx
docker compose -f compose.yaml -f compose.scale.yaml ps
python3 tests/load.py --duration 60 --concurrency 16 --output evidence/scale/demo-1-c16.json
```
Две реплики — по 1 CPU и 512 MiB:
```bash
docker compose -f compose.yaml -f compose.scale.yaml down
API_REPLICAS=2 API_CPUS=1.0 API_MEMORY=512m docker compose -f compose.yaml -f compose.scale.yaml up -d --build postgres redis migrate api-1 api-2 nginx
docker compose -f compose.yaml -f compose.scale.yaml ps
python3 tests/load.py --duration 60 --concurrency 16 --output evidence/scale/demo-2-c16.json
```
Четыре реплики — по 0,5 CPU и 256 MiB:
```bash
docker compose -f compose.yaml -f compose.scale.yaml down
API_REPLICAS=4 API_CPUS=0.5 API_MEMORY=256m docker compose -f compose.yaml -f compose.scale.yaml up -d --build postgres redis migrate api-1 api-2 api-3 api-4 nginx
docker compose -f compose.yaml -f compose.scale.yaml ps
python3 tests/load.py --duration 60 --concurrency 16 --output evidence/scale/demo-4-c16.json
```
Для демонстрации ограничений четырёх реплик:
```bash
for i in 1 2 3 4; do docker inspect mtusi2026lab3-api-$i-1 --format '{{.Name}} NanoCpus={{.HostConfig.NanoCpus}} Memory={{.HostConfig.Memory}}'; done
docker stats --no-stream
```
Исторические результаты всех прогонов находятся в `evidence/scale/`; графики уже сохранены в `evidence/scale/charts/`. Для повторного формирования графиков:
```bash
python3 scripts/analyze_scale.py
```
Для воспроизведения всех исходных серий вместо `--concurrency 16` последовательно использовать 8, 16, 32 и 64 клиента; для статистического сравнения провести по три прогона при 16 клиентах, сохраняя каждый результат в отдельный JSON-файл.
### 6. Проверка изменения CPU-периода
Этот эксперимент проводится на четырёх репликах. Он показал отрицательный результат, поэтому не является рекомендуемой рабочей конфигурацией. Дополнительный файл `compose.cpu-period.yaml` заменяет способ задания лимита CPU: `cpu_period: 200000` и `cpu_quota: 100000` вместо `cpus: 0.5`. Перед запуском убедиться, что файл присутствует в проекте.
```bash
docker compose -f compose.yaml -f compose.scale.yaml down
API_REPLICAS=4 API_CPUS=0.5 API_MEMORY=256m docker compose -f compose.yaml -f compose.scale.yaml -f compose.cpu-period.yaml config --quiet
API_REPLICAS=4 API_CPUS=0.5 API_MEMORY=256m docker compose -f compose.yaml -f compose.scale.yaml -f compose.cpu-period.yaml up -d --build postgres redis migrate api-1 api-2 api-3 api-4 nginx
for i in 1 2 3 4; do docker inspect mtusi2026lab3-api-$i-1 --format '{{.Name}} NanoCpus={{.HostConfig.NanoCpus}} CpuPeriod={{.HostConfig.CpuPeriod}} CpuQuota={{.HostConfig.CpuQuota}}'; done
python3 tests/load.py --duration 60 --concurrency 16 --output evidence/scale/demo-4-c16-period200.json
```
При корректной конфигурации каждая реплика имеет `NanoCpus=0`, `CpuPeriod=200000`, `CpuQuota=100000`, то есть 0,5 CPU. Для повторения методики выполнить три прогона с разными именами выходных файлов.
### 7. Воспроизведение серии с растущим бюджетом
```bash
./scripts/run_growing_scale.sh
python3 scripts/summarize_growing_scale.py
```
Скрипт последовательно запускает 1, 2 и 4 API-реплики с лимитами 1 CPU и 512 MiB на реплику, выполняет прогрев и три измерения по 60 секунд. Результаты сохраняются в `evidence/scale/growing/`. После завершения восстанавливается основная конфигурация двух реплик. Команда пересоздаёт контейнеры, поэтому её следует выполнять на учебном стенде.
### 8. Воспроизведение контрольной оптимизации «до/после»
```bash
./scripts/run_optimization.sh
```
Скрипт сравнивает четыре реплики по 0,5 CPU / 256 MiB и две реплики по 1 CPU / 512 MiB при одинаковом общем бюджете 2 CPU / 1024 MiB. Для каждой конфигурации выполняются 15 секунд прогрева и три измерения по 60 секунд с 16 клиентами. Результаты сохраняются в `evidence/scale/optimization/`. После эксперимента восстанавливаются две API-реплики. Скрипт пересоздаёт контейнеры без удаления volumes и предназначен для учебного стенда.
### 9. Регрессионные тесты по замечаниям
```bash
python3 tests/test_review_regressions.py
for service in postgres redis migrate api-1 api-2 nginx; do
echo "=== $service ==="
docker inspect "$(docker compose ps -aq "$service")" --format 'CPU: {{.HostConfig.NanoCpus}}, RAM: {{.HostConfig.Memory}} bytes'
done
```
Регрессионный тест проверяет UTF-8 Basic Auth с двоеточием в пароле, переход между страницами списка чатов, отсутствие курсора на последней странице и отклонение некорректного курсора. Команда `docker inspect` подтверждает ограничения всех сервисов.
### 10. Возврат к основной конфигурации после демонстрации
```bash
docker compose -f compose.yaml -f compose.scale.yaml -f compose.cpu-period.yaml down
API_REPLICAS=2 API_CPUS=1.0 API_MEMORY=512m docker compose -f compose.yaml -f compose.scale.yaml up -d --build postgres redis migrate api-1 api-2 nginx
docker compose -f compose.yaml -f compose.scale.yaml ps
curl -i http://localhost:8080/health/ready
```
Для обычной остановки без удаления данных:
```bash
docker compose down
```
`docker compose down -v` применять только при намеренном удалении учебной базы и volumes. При защите удобно показать сначала работающие две реплики, затем `X-Instance-Id`, проверки `make`, failover и результаты масштабирования; полные 60-секундные серии можно воспроизвести по приведённым командам при необходимости.
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
+149
View File
@@ -0,0 +1,149 @@
# A generic, single database configuration.
[alembic]
# path to migration scripts.
# this is typically a path given in POSIX (e.g. forward slashes)
# format, relative to the token %(here)s which refers to the location of this
# ini file
script_location = %(here)s/migrations
# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
# Uncomment the line below if you want the files to be prepended with date and time
# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
# for all available tokens
# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
# Or organize into date-based subdirectories (requires recursive_version_locations = true)
# file_template = %%(year)d/%%(month).2d/%%(day).2d_%%(hour).2d%%(minute).2d_%%(second).2d_%%(rev)s_%%(slug)s
# sys.path path, will be prepended to sys.path if present.
# defaults to the current working directory. for multiple paths, the path separator
# is defined by "path_separator" below.
prepend_sys_path = .
# timezone to use when rendering the date within the migration file
# as well as the filename.
# If specified, requires the tzdata library which can be installed by adding
# `alembic[tz]` to the pip requirements.
# string value is passed to ZoneInfo()
# leave blank for localtime
# timezone =
# max length of characters to apply to the "slug" field
# truncate_slug_length = 40
# set to 'true' to run the environment during
# the 'revision' command, regardless of autogenerate
# revision_environment = false
# set to 'true' to allow .pyc and .pyo files without
# a source .py file to be detected as revisions in the
# versions/ directory
# sourceless = false
# version location specification; This defaults
# to <script_location>/versions. When using multiple version
# directories, initial revisions must be specified with --version-path.
# The path separator used here should be the separator specified by "path_separator"
# below.
# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
# path_separator; This indicates what character is used to split lists of file
# paths, including version_locations and prepend_sys_path within configparser
# files such as alembic.ini.
# The default rendered in new alembic.ini files is "os", which uses os.pathsep
# to provide os-dependent path splitting.
#
# Note that in order to support legacy alembic.ini files, this default does NOT
# take place if path_separator is not present in alembic.ini. If this
# option is omitted entirely, fallback logic is as follows:
#
# 1. Parsing of the version_locations option falls back to using the legacy
# "version_path_separator" key, which if absent then falls back to the legacy
# behavior of splitting on spaces and/or commas.
# 2. Parsing of the prepend_sys_path option falls back to the legacy
# behavior of splitting on spaces, commas, or colons.
#
# Valid values for path_separator are:
#
# path_separator = :
# path_separator = ;
# path_separator = space
# path_separator = newline
#
# Use os.pathsep. Default configuration used for new projects.
path_separator = os
# set to 'true' to search source files recursively
# in each "version_locations" directory
# new in Alembic version 1.10
# recursive_version_locations = false
# the output encoding used when revision files
# are written from script.py.mako
# output_encoding = utf-8
# database URL. This is consumed by the user-maintained env.py script only.
# other means of configuring database URLs may be customized within the env.py
# file.
sqlalchemy.url =
[post_write_hooks]
# post_write_hooks defines scripts or Python functions that are run
# on newly generated revision scripts. See the documentation for further
# detail and examples
# format using "black" - use the console_scripts runner, against the "black" entrypoint
# hooks = black
# black.type = console_scripts
# black.entrypoint = black
# black.options = -l 79 REVISION_SCRIPT_FILENAME
# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
# hooks = ruff
# ruff.type = module
# ruff.module = ruff
# ruff.options = check --fix REVISION_SCRIPT_FILENAME
# Alternatively, use the exec runner to execute a binary found on your PATH
# hooks = ruff
# ruff.type = exec
# ruff.executable = ruff
# ruff.options = check --fix REVISION_SCRIPT_FILENAME
# Logging configuration. This is also consumed by the user-maintained
# env.py script only.
[loggers]
keys = root,sqlalchemy,alembic
[handlers]
keys = console
[formatters]
keys = generic
[logger_root]
level = WARNING
handlers = console
qualname =
[logger_sqlalchemy]
level = WARNING
handlers =
qualname = sqlalchemy.engine
[logger_alembic]
level = INFO
handlers =
qualname = alembic
[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic
[formatter_generic]
format = %(levelname)-5.5s [%(name)s] %(message)s
datefmt = %H:%M:%S
+21
View File
@@ -0,0 +1,21 @@
services:
api-1:
cpus: !reset null
cpu_period: 200000
cpu_quota: 100000
api-2:
cpus: !reset null
cpu_period: 200000
cpu_quota: 100000
api-3:
cpus: !reset null
cpu_period: 200000
cpu_quota: 100000
api-4:
cpus: !reset null
cpu_period: 200000
cpu_quota: 100000
+36
View File
@@ -0,0 +1,36 @@
services:
api-1:
cpus: ${API_CPUS:-1.0}
mem_limit: ${API_MEMORY:-512m}
api-2:
cpus: ${API_CPUS:-1.0}
mem_limit: ${API_MEMORY:-512m}
api-3:
extends:
service: api-1
file: compose.yaml
environment:
INSTANCE_ID: api-3
cpus: ${API_CPUS:-1.0}
mem_limit: ${API_MEMORY:-512m}
api-4:
extends:
service: api-1
file: compose.yaml
environment:
INSTANCE_ID: api-4
cpus: ${API_CPUS:-1.0}
mem_limit: ${API_MEMORY:-512m}
nginx:
volumes:
- ./infra/scale/nginx-${API_REPLICAS:-2}.conf:/etc/nginx/nginx.conf:ro
depends_on: !override
api-1:
condition: service_healthy
+119
View File
@@ -0,0 +1,119 @@
x-api: &api
build:
context: .
dockerfile: Dockerfile
environment:
APP_ENV: lab
SESSION_TTL_SECONDS: 3600
DATABASE_URL_FILE: /run/secrets/database_url
CACHE_URL_FILE: /run/secrets/cache_url
secrets:
- database_url
- cache_url
depends_on:
migrate:
condition: service_completed_successfully
redis:
condition: service_healthy
expose:
- "8080"
restart: unless-stopped
stop_grace_period: 15s
mem_limit: 512m
cpus: 1.0
services:
postgres:
image: postgres:17.6
environment:
POSTGRES_DB: messenger
POSTGRES_USER: lab2
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
secrets:
- postgres_password
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U lab2 -d messenger"]
interval: 5s
timeout: 3s
retries: 10
restart: unless-stopped
cpus: 1.0
mem_limit: 768m
redis:
image: redis:8.2.2
command:
- redis-server
- --appendonly
- "yes"
- --appendfsync
- everysec
volumes:
- redis_data:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 3s
retries: 10
restart: unless-stopped
cpus: 0.5
mem_limit: 256m
migrate:
build:
context: .
dockerfile: Dockerfile
command: ["alembic", "upgrade", "head"]
secrets:
- database_url
depends_on:
postgres:
condition: service_healthy
restart: "no"
cpus: 1.0
mem_limit: 512m
api-1:
<<: *api
environment:
APP_ENV: lab
SESSION_TTL_SECONDS: 3600
DATABASE_URL_FILE: /run/secrets/database_url
CACHE_URL_FILE: /run/secrets/cache_url
INSTANCE_ID: api-1
api-2:
<<: *api
environment:
APP_ENV: lab
SESSION_TTL_SECONDS: 3600
DATABASE_URL_FILE: /run/secrets/database_url
CACHE_URL_FILE: /run/secrets/cache_url
INSTANCE_ID: api-2
nginx:
image: nginx:1.29-alpine
ports:
- "8080:8080"
volumes:
- ./infra/nginx.conf:/etc/nginx/nginx.conf:ro
depends_on:
- api-1
- api-2
restart: unless-stopped
cpus: 0.5
mem_limit: 256m
secrets:
postgres_password:
file: ./secrets/postgres_password
database_url:
file: ./secrets/database_url
cache_url:
file: ./secrets/cache_url
volumes:
postgres_data:
redis_data:
+7
View File
@@ -0,0 +1,7 @@
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
mtusi2026lab3-api-1-1 sha256:c9c8b63333aa74724c05967ab2be710213e8636de9b5563f83c992e68067fe27 "uvicorn src.main:ap…" api-1 44 minutes ago Up 6 minutes (healthy) 8080/tcp
mtusi2026lab3-api-2-1 sha256:2450b84cf4e2e2386916c732dfbf3b345488435830de312062c91953cf46eead "uvicorn src.main:ap…" api-2 44 minutes ago Up 21 minutes (healthy) 8080/tcp
mtusi2026lab3-migrate-1 sha256:e7713bfcd86cf0405a7503aaf1a00e5d3d3b3f0ce2c76d024c41b33e2f16d06e "alembic upgrade head" migrate 44 minutes ago Exited (0) 2 minutes ago
mtusi2026lab3-nginx-1 nginx:1.29-alpine "/docker-entrypoint.…" nginx 44 minutes ago Up 41 minutes 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp
mtusi2026lab3-postgres-1 postgres:17.6 "docker-entrypoint.s…" postgres 44 minutes ago Up 27 minutes (healthy) 5432/tcp
mtusi2026lab3-redis-1 redis:8.2.2 "docker-entrypoint.s…" redis 44 minutes ago Up 27 minutes (healthy) 6379/tcp
@@ -0,0 +1,8 @@
Concurrent requests: 20
Successful requests: 20
Failed requests: 0
Instances: ['api-1', 'api-2']
Unique successful message IDs: 1
Messages in history: 1
Recovered message ID: 926f7a4d-017b-43d3-8ef7-3ce643534af8
PASS: concurrent idempotency preserved during api-1 failover
+4
View File
@@ -0,0 +1,4 @@
python3 tests/resilience.py --mode failover --action-script "./scripts/stop-one.sh" --base-url "http://localhost:8080"
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 65, "failed_attempts": 3, "first_recovery_seconds": 1.311}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
+4
View File
@@ -0,0 +1,4 @@
python3 tests/resilience.py --mode failover --action-script "./scripts/stop-one.sh" --base-url "http://localhost:8080"
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 81, "failed_attempts": 2, "first_recovery_seconds": 1.339}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
+4
View File
@@ -0,0 +1,4 @@
python3 tests/resilience.py --mode failover --action-script "./scripts/stop-one.sh" --base-url "http://localhost:8080"
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 55, "failed_attempts": 4, "first_recovery_seconds": 1.327}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
+5
View File
@@ -0,0 +1,5 @@
Requests: 20
Unique message IDs: 1
Instances: ['api-1', 'api-2']
Messages in history: 1
PASS: concurrent idempotency across replicas
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 30.0,
"elapsed_seconds": 30.038,
"concurrency": 8,
"successful_requests": 5982,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 199.148,
"successful_latency_ms": {
"p50": 33.537,
"p95": 86.622,
"p99": 201.671
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 45.0,
"elapsed_seconds": 45.073,
"concurrency": 8,
"successful_requests": 5897,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 130.833,
"successful_latency_ms": {
"p50": 54.133,
"p95": 112.499,
"p99": 216.195
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 45.0,
"elapsed_seconds": 45.084,
"concurrency": 8,
"successful_requests": 6012,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 133.351,
"successful_latency_ms": {
"p50": 52.247,
"p95": 115.109,
"p99": 208.774
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 90.0,
"elapsed_seconds": 90.037,
"concurrency": 8,
"successful_requests": 16927,
"failed_requests": 1,
"error_ratio": 5.9e-05,
"successful_rps": 188.0,
"successful_latency_ms": {
"p50": 33.878,
"p95": 99.116,
"p99": 199.301
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+3
View File
@@ -0,0 +1,3 @@
python3 tests/resilience.py --mode persistence --action-script "./scripts/restart.sh" --base-url "http://localhost:8080"
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
+3
View File
@@ -0,0 +1,3 @@
nr_periods 8378
nr_throttled 3207
throttled_time 270000128500
+3
View File
@@ -0,0 +1,3 @@
nr_periods 7410
nr_throttled 2675
throttled_time 222356681100
+3
View File
@@ -0,0 +1,3 @@
nr_periods 8371
nr_throttled 2898
throttled_time 237731735800
+3
View File
@@ -0,0 +1,3 @@
nr_periods 7403
nr_throttled 2551
throttled_time 203403537000
+3
View File
@@ -0,0 +1,3 @@
nr_periods 8357
nr_throttled 2976
throttled_time 242442862500
+3
View File
@@ -0,0 +1,3 @@
nr_periods 7391
nr_throttled 2576
throttled_time 209050114200
+3
View File
@@ -0,0 +1,3 @@
nr_periods 8378
nr_throttled 2920
throttled_time 235549876300
+3
View File
@@ -0,0 +1,3 @@
nr_periods 7414
nr_throttled 2556
throttled_time 203469227700
Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 32 KiB

@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.038,
"concurrency": 16,
"successful_requests": 17175,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 286.068,
"successful_latency_ms": {
"p50": 52.594,
"p95": 81.865,
"p99": 108.938
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.042,
"concurrency": 16,
"successful_requests": 17543,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 292.177,
"successful_latency_ms": {
"p50": 52.781,
"p95": 69.305,
"p99": 105.621
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.047,
"concurrency": 16,
"successful_requests": 17445,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 290.524,
"successful_latency_ms": {
"p50": 52.874,
"p95": 66.813,
"p99": 106.086
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 15.0,
"elapsed_seconds": 15.039,
"concurrency": 16,
"successful_requests": 4643,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 308.737,
"successful_latency_ms": {
"p50": 49.524,
"p95": 68.017,
"p99": 99.238
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.024,
"concurrency": 16,
"successful_requests": 25283,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 421.214,
"successful_latency_ms": {
"p50": 40.975,
"p95": 64.203,
"p99": 94.122
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.037,
"concurrency": 16,
"successful_requests": 25588,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 426.204,
"successful_latency_ms": {
"p50": 40.434,
"p95": 63.728,
"p99": 93.727
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.04,
"concurrency": 16,
"successful_requests": 25843,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 430.432,
"successful_latency_ms": {
"p50": 36.673,
"p95": 61.779,
"p99": 91.761
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 15.0,
"elapsed_seconds": 15.038,
"concurrency": 16,
"successful_requests": 7179,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 477.394,
"successful_latency_ms": {
"p50": 31.008,
"p95": 58.811,
"p99": 74.541
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.025,
"concurrency": 16,
"successful_requests": 35821,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 596.766,
"successful_latency_ms": {
"p50": 24.158,
"p95": 43.446,
"p99": 84.503
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.026,
"concurrency": 16,
"successful_requests": 36198,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 603.038,
"successful_latency_ms": {
"p50": 24.296,
"p95": 41.592,
"p99": 78.952
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.028,
"concurrency": 16,
"successful_requests": 36335,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 605.3,
"successful_latency_ms": {
"p50": 24.214,
"p95": 40.08,
"p99": 75.496
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 15.0,
"elapsed_seconds": 15.026,
"concurrency": 16,
"successful_requests": 9974,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 663.761,
"successful_latency_ms": {
"p50": 21.623,
"p95": 38.696,
"p99": 85.055
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.037,
"concurrency": 16,
"successful_requests": 25069,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 417.559,
"successful_latency_ms": {
"p50": 37.705,
"p95": 63.254,
"p99": 94.489
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.038,
"concurrency": 16,
"successful_requests": 25032,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 416.933,
"successful_latency_ms": {
"p50": 40.359,
"p95": 65.787,
"p99": 102.35
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.039,
"concurrency": 16,
"successful_requests": 25300,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 421.396,
"successful_latency_ms": {
"p50": 39.572,
"p95": 64.804,
"p99": 89.779
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 15.0,
"elapsed_seconds": 15.034,
"concurrency": 16,
"successful_requests": 7049,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 468.855,
"successful_latency_ms": {
"p50": 33.257,
"p95": 55.415,
"p99": 74.659
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.098,
"concurrency": 16,
"successful_requests": 24230,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 403.177,
"successful_latency_ms": {
"p50": 20.095,
"p95": 90.688,
"p99": 177.425
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.024,
"concurrency": 16,
"successful_requests": 23574,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 392.746,
"successful_latency_ms": {
"p50": 21.246,
"p95": 90.636,
"p99": 155.902
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.097,
"concurrency": 16,
"successful_requests": 23248,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 386.841,
"successful_latency_ms": {
"p50": 22.844,
"p95": 93.01,
"p99": 161.73
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 15.0,
"elapsed_seconds": 15.075,
"concurrency": 16,
"successful_requests": 6116,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 405.708,
"successful_latency_ms": {
"p50": 19.709,
"p95": 88.349,
"p99": 172.728
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.106,
"concurrency": 16,
"successful_requests": 8568,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 142.549,
"successful_latency_ms": {
"p50": 110.389,
"p95": 136.182,
"p99": 158.802
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.098,
"concurrency": 16,
"successful_requests": 8574,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 142.668,
"successful_latency_ms": {
"p50": 109.902,
"p95": 138.423,
"p99": 158.119
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.088,
"concurrency": 16,
"successful_requests": 8770,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 145.953,
"successful_latency_ms": {
"p50": 107.179,
"p95": 133.233,
"p99": 158.897
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.196,
"concurrency": 32,
"successful_requests": 8771,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 145.707,
"successful_latency_ms": {
"p50": 215.689,
"p95": 329.942,
"p99": 384.589
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.376,
"concurrency": 64,
"successful_requests": 8536,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 141.381,
"successful_latency_ms": {
"p50": 446.212,
"p95": 789.407,
"p99": 880.616
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.068,
"concurrency": 8,
"successful_requests": 6724,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 111.939,
"successful_latency_ms": {
"p50": 58.407,
"p95": 112.768,
"p99": 146.62
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.171,
"concurrency": 16,
"successful_requests": 12655,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 210.316,
"successful_latency_ms": {
"p50": 69.914,
"p95": 143.475,
"p99": 393.474
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.066,
"concurrency": 16,
"successful_requests": 13718,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 228.38,
"successful_latency_ms": {
"p50": 61.921,
"p95": 122.108,
"p99": 350.672
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.073,
"concurrency": 16,
"successful_requests": 13474,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 224.292,
"successful_latency_ms": {
"p50": 63.238,
"p95": 124.043,
"p99": 370.455
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.177,
"concurrency": 32,
"successful_requests": 12789,
"failed_requests": 1,
"error_ratio": 7.8e-05,
"successful_rps": 212.523,
"successful_latency_ms": {
"p50": 131.06,
"p95": 351.284,
"p99": 615.035
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.384,
"concurrency": 64,
"successful_requests": 14015,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 232.097,
"successful_latency_ms": {
"p50": 201.222,
"p95": 615.727,
"p99": 889.776
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.042,
"concurrency": 8,
"successful_requests": 13372,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 222.711,
"successful_latency_ms": {
"p50": 31.738,
"p95": 54.653,
"p99": 179.282
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.052,
"concurrency": 16,
"successful_requests": 21207,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 353.146,
"successful_latency_ms": {
"p50": 31.047,
"p95": 125.895,
"p99": 300.611
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.172,
"concurrency": 16,
"successful_requests": 6519,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 108.34,
"successful_latency_ms": {
"p50": 65.375,
"p95": 484.37,
"p99": 1067.28
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.16,
"concurrency": 16,
"successful_requests": 5144,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 85.505,
"successful_latency_ms": {
"p50": 35.656,
"p95": 925.831,
"p99": 1351.136
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.759,
"concurrency": 16,
"successful_requests": 5206,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 85.683,
"successful_latency_ms": {
"p50": 34.87,
"p95": 890.303,
"p99": 1366.728
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.208,
"concurrency": 16,
"successful_requests": 5217,
"failed_requests": 1,
"error_ratio": 0.000192,
"successful_rps": 86.649,
"successful_latency_ms": {
"p50": 32.204,
"p95": 888.403,
"p99": 1559.44
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.252,
"concurrency": 16,
"successful_requests": 5846,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 97.026,
"successful_latency_ms": {
"p50": 26.896,
"p95": 765.653,
"p99": 1306.985
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.467,
"concurrency": 16,
"successful_requests": 6463,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 106.885,
"successful_latency_ms": {
"p50": 36.504,
"p95": 468.828,
"p99": 1084.529
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.791,
"concurrency": 32,
"successful_requests": 6457,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 106.217,
"successful_latency_ms": {
"p50": 61.313,
"p95": 1079.084,
"p99": 2016.636
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 62.112,
"concurrency": 64,
"successful_requests": 5285,
"failed_requests": 9,
"error_ratio": 0.0017,
"successful_rps": 85.089,
"successful_latency_ms": {
"p50": 391.871,
"p95": 2904.723,
"p99": 3996.054
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 3,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 60.0,
"elapsed_seconds": 60.27,
"concurrency": 8,
"successful_requests": 5960,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 98.888,
"successful_latency_ms": {
"p50": 30.52,
"p95": 345.366,
"p99": 511.875
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+2
View File
@@ -0,0 +1,2 @@
python3 tests/smoke.py --base-url "http://localhost:8080"
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
+36
View File
@@ -0,0 +1,36 @@
events {
worker_connections 1024;
}
http {
resolver 127.0.0.11 valid=5s ipv6=off;
resolver_timeout 2s;
upstream api_backend {
zone api_backend 64k;
server api-1:8080 resolve max_fails=1 fail_timeout=5s;
server api-2:8080 resolve max_fails=1 fail_timeout=5s;
}
server {
listen 8080;
location / {
proxy_pass http://api_backend;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 2s;
proxy_read_timeout 10s;
proxy_send_timeout 10s;
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2;
}
}
}
+35
View File
@@ -0,0 +1,35 @@
events {
worker_connections 1024;
}
http {
resolver 127.0.0.11 valid=5s ipv6=off;
resolver_timeout 2s;
upstream api_backend {
zone api_backend 64k;
server api-1:8080 resolve max_fails=1 fail_timeout=5s;
}
server {
listen 8080;
location / {
proxy_pass http://api_backend;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 2s;
proxy_read_timeout 10s;
proxy_send_timeout 10s;
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2;
}
}
}
+36
View File
@@ -0,0 +1,36 @@
events {
worker_connections 1024;
}
http {
resolver 127.0.0.11 valid=5s ipv6=off;
resolver_timeout 2s;
upstream api_backend {
zone api_backend 64k;
server api-1:8080 resolve max_fails=1 fail_timeout=5s;
server api-2:8080 resolve max_fails=1 fail_timeout=5s;
}
server {
listen 8080;
location / {
proxy_pass http://api_backend;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 2s;
proxy_read_timeout 10s;
proxy_send_timeout 10s;
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2;
}
}
}
+38
View File
@@ -0,0 +1,38 @@
events {
worker_connections 1024;
}
http {
resolver 127.0.0.11 valid=5s ipv6=off;
resolver_timeout 2s;
upstream api_backend {
zone api_backend 64k;
server api-1:8080 resolve max_fails=1 fail_timeout=5s;
server api-2:8080 resolve max_fails=1 fail_timeout=5s;
server api-3:8080 resolve max_fails=1 fail_timeout=5s;
server api-4:8080 resolve max_fails=1 fail_timeout=5s;
}
server {
listen 8080;
location / {
proxy_pass http://api_backend;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 2s;
proxy_read_timeout 10s;
proxy_send_timeout 10s;
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2;
}
}
}
+1
View File
@@ -0,0 +1 @@
Generic single-database configuration with an async dbapi.
+50
View File
@@ -0,0 +1,50 @@
import asyncio
from alembic import context
from sqlalchemy import pool
from sqlalchemy.ext.asyncio import async_engine_from_config
config = context.config
DATABASE_URL_FILE = "/run/secrets/database_url"
def read_database_url() -> str:
with open(DATABASE_URL_FILE, encoding="utf-8") as file:
return file.read().strip()
config.set_main_option("sqlalchemy.url", read_database_url())
target_metadata = None
def do_run_migrations(connection) -> None:
context.configure(
connection=connection,
target_metadata=target_metadata,
)
with context.begin_transaction():
context.run_migrations()
async def run_async_migrations() -> None:
connectable = async_engine_from_config(
config.get_section(config.config_ini_section, {}),
prefix="sqlalchemy.",
poolclass=pool.NullPool,
)
async with connectable.connect() as connection:
await connection.run_sync(do_run_migrations)
await connectable.dispose()
def run_migrations_online() -> None:
asyncio.run(run_async_migrations())
run_migrations_online()
+28
View File
@@ -0,0 +1,28 @@
"""${message}
Revision ID: ${up_revision}
Revises: ${down_revision | comma,n}
Create Date: ${create_date}
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
${imports if imports else ""}
# revision identifiers, used by Alembic.
revision: str = ${repr(up_revision)}
down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
def upgrade() -> None:
"""Upgrade schema."""
${upgrades if upgrades else "pass"}
def downgrade() -> None:
"""Downgrade schema."""
${downgrades if downgrades else "pass"}
@@ -0,0 +1,61 @@
"""Message idempotency for lab 3.
Revision ID: b3a91c0e7d42
Revises: f7c51e1e945b
"""
from alembic import op
import sqlalchemy as sa
revision = "b3a91c0e7d42"
down_revision = "f7c51e1e945b"
branch_labels = None
depends_on = None
def upgrade() -> None:
op.create_table(
"message_idempotency",
sa.Column("user_id", sa.Uuid(), nullable=False),
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("key", sa.String(length=128), nullable=False),
sa.Column("request_hash", sa.String(length=64), nullable=False),
sa.Column("message_id", sa.Uuid(), nullable=False),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
server_default=sa.text("CURRENT_TIMESTAMP"),
nullable=False,
),
sa.ForeignKeyConstraint(
["user_id"],
["users.id"],
ondelete="CASCADE",
),
sa.ForeignKeyConstraint(
["chat_id"],
["chats.id"],
ondelete="CASCADE",
),
sa.ForeignKeyConstraint(
["message_id"],
["messages.id"],
ondelete="CASCADE",
),
sa.PrimaryKeyConstraint("user_id", "chat_id", "key"),
)
op.create_index(
"ix_message_idempotency_created_at",
"message_idempotency",
["created_at"],
)
def downgrade() -> None:
op.drop_index(
"ix_message_idempotency_created_at",
table_name="message_idempotency",
)
op.drop_table("message_idempotency")
@@ -0,0 +1,110 @@
"""initial schema
Revision ID: f7c51e1e945b
Revises:
Create Date: 2026-10-07 18:33:37.771593
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
# revision identifiers, used by Alembic.
revision: str = "f7c51e1e945b"
down_revision: Union[str, Sequence[str], None] = None
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None
def upgrade() -> None:
op.create_table(
"users",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("username", sa.String(length=32), nullable=False),
sa.Column("display_name", sa.String(length=100), nullable=False),
sa.Column("password_hash", sa.Text(), nullable=False),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
server_default=sa.text("CURRENT_TIMESTAMP"),
nullable=False,
),
sa.PrimaryKeyConstraint("id"),
sa.UniqueConstraint("username", name="uq_users_username"),
)
op.create_table(
"chats",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("title", sa.String(length=100), nullable=False),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
server_default=sa.text("CURRENT_TIMESTAMP"),
nullable=False,
),
sa.PrimaryKeyConstraint("id"),
)
op.create_table(
"chat_members",
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("user_id", sa.Uuid(), nullable=False),
sa.ForeignKeyConstraint(
["chat_id"],
["chats.id"],
ondelete="CASCADE",
),
sa.ForeignKeyConstraint(
["user_id"],
["users.id"],
ondelete="CASCADE",
),
sa.PrimaryKeyConstraint("chat_id", "user_id"),
)
op.create_table(
"messages",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("sender_id", sa.Uuid(), nullable=False),
sa.Column("text", sa.String(length=4000), nullable=False),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
server_default=sa.text("CURRENT_TIMESTAMP"),
nullable=False,
),
sa.ForeignKeyConstraint(
["chat_id"],
["chats.id"],
ondelete="CASCADE",
),
sa.ForeignKeyConstraint(
["sender_id"],
["users.id"],
ondelete="RESTRICT",
),
sa.PrimaryKeyConstraint("id"),
)
op.create_index(
"ix_messages_chat_created_id",
"messages",
["chat_id", "created_at", "id"],
unique=False,
)
def downgrade() -> None:
op.drop_index(
"ix_messages_chat_created_id",
table_name="messages",
)
op.drop_table("messages")
op.drop_table("chat_members")
op.drop_table("chats")
op.drop_table("users")
+20
View File
@@ -0,0 +1,20 @@
annotated-doc==0.0.5
annotated-types==0.8.0
anyio==4.15.1
click==8.5.0
fastapi==0.141.1
h11==0.16.0
idna==3.20
pydantic==2.13.5
pydantic_core==2.46.5
starlette==1.7.0
typing-inspection==0.4.4
typing_extensions==4.16.0
uvicorn==0.53.0
SQLAlchemy==2.1.4
asyncpg==0.32.0
alembic==1.20.0
greenlet==3.5.6
argon2-cffi==25.1.0
redis==7.0.1
+91
View File
@@ -0,0 +1,91 @@
import json
import statistics
from pathlib import Path
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
ROOT = Path("evidence/scale")
OUTPUT = ROOT / "charts"
THIRD_RUN = {
1: "repeat2",
2: "repeat2",
4: "diagnostics",
}
OUTPUT.mkdir(parents=True, exist_ok=True)
summary = []
for replicas in (1, 2, 4):
files = [
ROOT / f"replicas-{replicas}-c16.json",
ROOT / f"replicas-{replicas}-c16-repeat.json",
ROOT / f"replicas-{replicas}-c16-{THIRD_RUN[replicas]}.json",
]
results = [json.loads(path.read_text(encoding="utf-8")) for path in files]
rps = [result["successful_rps"] for result in results]
p95 = [result["successful_latency_ms"]["p95"] for result in results]
p99 = [result["successful_latency_ms"]["p99"] for result in results]
errors = sum(result["failed_requests"] for result in results)
item = {
"replicas": replicas,
"rps_mean": statistics.mean(rps),
"rps_std": statistics.stdev(rps),
"p95_mean": statistics.mean(p95),
"p99_mean": statistics.mean(p99),
"errors": errors,
}
summary.append(item)
print(f"\nРеплик: {replicas}")
print(f"RPS: {', '.join(f'{value:.3f}' for value in rps)}")
print(f"Средний RPS: {item['rps_mean']:.3f}")
print(f"Стандартное отклонение RPS: {item['rps_std']:.3f}")
print(f"Средний p95: {item['p95_mean']:.3f} мс")
print(f"Средний p99: {item['p99_mean']:.3f} мс")
print(f"Ошибок: {errors}")
replicas = [item["replicas"] for item in summary]
rps_means = [item["rps_mean"] for item in summary]
rps_stds = [item["rps_std"] for item in summary]
p95_means = [item["p95_mean"] for item in summary]
p99_means = [item["p99_mean"] for item in summary]
fig, ax = plt.subplots(figsize=(8, 5))
ax.bar(replicas, rps_means, yerr=rps_stds, capsize=6)
ax.set_xticks(replicas)
ax.set_xlabel("API replicas")
ax.set_ylabel("Successful requests per second")
ax.set_title("Throughput at 16 concurrent clients")
ax.grid(axis="y", alpha=0.3)
fig.tight_layout()
fig.savefig(OUTPUT / "throughput.png", dpi=160)
plt.close(fig)
fig, ax = plt.subplots(figsize=(8, 5))
positions = list(range(len(replicas)))
width = 0.35
ax.bar([x - width / 2 for x in positions], p95_means, width, label="p95")
ax.bar([x + width / 2 for x in positions], p99_means, width, label="p99")
ax.set_xticks(positions, replicas)
ax.set_xlabel("API replicas")
ax.set_ylabel("Latency (ms)")
ax.set_title("Mean latency percentiles at 16 concurrent clients")
ax.legend()
ax.grid(axis="y", alpha=0.3)
fig.tight_layout()
fig.savefig(OUTPUT / "latency.png", dpi=160)
plt.close(fig)
print(f"\nГрафики сохранены в {OUTPUT}")
+29
View File
@@ -0,0 +1,29 @@
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/.."
mkdir -p secrets
chmod 700 secrets
umask 077
if [[ ! -f secrets/postgres_password ]]; then
python3 -c 'import secrets; print(secrets.token_hex(24))' > secrets/postgres_password
fi
if [[ ! -f secrets/database_url ]]; then
PASSWORD="$(cat secrets/postgres_password)"
printf 'postgresql+asyncpg://lab2:%s@postgres:5432/messenger\n' "$PASSWORD" > secrets/database_url
fi
if [[ ! -f secrets/cache_url ]]; then
printf 'redis://redis:6379/0\n' > secrets/cache_url
fi
chmod 644 secrets/postgres_password secrets/database_url secrets/cache_url
if [[ ! -f .env ]]; then
cp .env.example .env
fi
docker compose config --quiet
+4
View File
@@ -0,0 +1,4 @@
#!/usr/bin/env bash
set -euo pipefail
docker compose restart postgres redis api-1 api-2
+28
View File
@@ -0,0 +1,28 @@
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/.."
mkdir -p evidence/scale/growing
for replicas in 1 2 4; do
export API_REPLICAS="$replicas"
export API_CPUS=1.0
export API_MEMORY=512m
docker compose -f compose.yaml -f compose.scale.yaml down
services=(postgres redis migrate nginx)
for ((i=1;i<=replicas;i++)); do services+=("api-$i"); done
docker compose -f compose.yaml -f compose.scale.yaml up -d --build "${services[@]}"
for ((attempt=1;attempt<=60;attempt++)); do
if curl --fail --silent http://localhost:8080/health/ready >/dev/null; then break; fi
sleep 2
done
curl --fail --silent http://localhost:8080/health/ready >/dev/null
for ((i=1;i<=replicas;i++)); do
docker compose -f compose.yaml -f compose.scale.yaml ps "api-$i"
done
python3 tests/load.py --duration 15 --concurrency 16 --output "evidence/scale/growing/replicas-${replicas}-warmup.json"
for run in 1 2 3; do
python3 tests/load.py --duration 60 --concurrency 16 --output "evidence/scale/growing/replicas-${replicas}-run${run}.json"
done
done
API_REPLICAS=2 API_CPUS=1.0 API_MEMORY=512m docker compose -f compose.yaml -f compose.scale.yaml down
API_REPLICAS=2 API_CPUS=1.0 API_MEMORY=512m docker compose -f compose.yaml -f compose.scale.yaml up -d --build postgres redis migrate api-1 api-2 nginx
python3 scripts/summarize_growing_scale.py
+65
View File
@@ -0,0 +1,65 @@
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/.."
mkdir -p evidence/scale/optimization
run_case() {
local name="$1"
local replicas="$2"
local cpus="$3"
local memory="$4"
export API_REPLICAS="$replicas"
export API_CPUS="$cpus"
export API_MEMORY="$memory"
echo "=== $name: $replicas replicas, $cpus CPU and $memory per replica ==="
docker compose -f compose.yaml -f compose.scale.yaml down
services=(postgres redis migrate nginx)
for ((i=1; i<=replicas; i++)); do
services+=("api-$i")
done
docker compose -f compose.yaml -f compose.scale.yaml up -d --build "${services[@]}"
ready=0
for ((attempt=1; attempt<=60; attempt++)); do
if curl --fail --silent http://localhost:8080/health/ready >/dev/null; then
ready=1
break
fi
sleep 2
done
if ((ready == 0)); then
echo "ERROR: API readiness timeout" >&2
exit 1
fi
python3 tests/load.py \
--duration 15 \
--concurrency 16 \
--output "evidence/scale/optimization/${name}-warmup.json"
for run in 1 2 3; do
python3 tests/load.py \
--duration 60 \
--concurrency 16 \
--output "evidence/scale/optimization/${name}-run${run}.json"
done
}
run_case before 4 0.5 256m
run_case after 2 1.0 512m
API_REPLICAS=2 API_CPUS=1.0 API_MEMORY=512m \
docker compose -f compose.yaml -f compose.scale.yaml down
API_REPLICAS=2 API_CPUS=1.0 API_MEMORY=512m \
docker compose -f compose.yaml -f compose.scale.yaml up -d --build \
postgres redis migrate api-1 api-2 nginx
echo "=== Optimization experiment completed ==="
+14
View File
@@ -0,0 +1,14 @@
#!/usr/bin/env bash
set -euo pipefail
: "${TARGET_INSTANCE_ID:?}"
case "$TARGET_INSTANCE_ID" in
api-1|api-2)
docker compose stop "$TARGET_INSTANCE_ID"
;;
*)
echo "Unknown instance: $TARGET_INSTANCE_ID" >&2
exit 1
;;
esac
+17
View File
@@ -0,0 +1,17 @@
import json
import statistics
from pathlib import Path
root = Path('evidence/scale/growing')
print('Growing budget: 1/2/4 replicas, each 1 CPU and 512 MiB, 16 clients, 60 seconds, 3 runs')
for replicas in (1, 2, 4):
files = [root / f'replicas-{replicas}-run{i}.json' for i in (1, 2, 3)]
if not all(p.exists() for p in files):
print(f'{replicas}: INCOMPLETE (measurements not yet run)')
continue
data = [json.loads(p.read_text()) for p in files]
values = [x['successful_rps'] for x in data]
errors = sum(x['failed_requests'] for x in data)
print(f'{replicas}: mean RPS={statistics.mean(values):.3f}, stdev={statistics.stdev(values):.3f}, '
f'mean p95={statistics.mean(x["successful_latency_ms"]["p95"] for x in data):.3f} ms, '
f'mean p99={statistics.mean(x["successful_latency_ms"]["p99"] for x in data):.3f} ms, errors={errors}')
View File
+86
View File
@@ -0,0 +1,86 @@
import base64
import binascii
import json
from datetime import datetime
from uuid import UUID
def encode_cursor(
chat_id: UUID,
created_at: datetime,
message_id: UUID,
) -> str:
data = {
"chat_id": str(chat_id),
"created_at": created_at.isoformat(),
"message_id": str(message_id),
}
raw = json.dumps(
data,
separators=(",", ":"),
).encode("utf-8")
return base64.urlsafe_b64encode(raw).decode("ascii")
def decode_cursor(cursor: str) -> tuple[UUID, datetime, UUID]:
try:
raw = base64.urlsafe_b64decode(cursor.encode("ascii"))
data = json.loads(raw.decode("utf-8"))
if not isinstance(data, dict):
raise ValueError("Invalid cursor")
if set(data.keys()) != {
"chat_id",
"created_at",
"message_id",
}:
raise ValueError("Invalid cursor")
chat_id = UUID(data["chat_id"])
created_at = datetime.fromisoformat(data["created_at"])
message_id = UUID(data["message_id"])
if created_at.tzinfo is None or created_at.utcoffset() is None:
raise ValueError("Invalid cursor")
return chat_id, created_at, message_id
except (
ValueError,
KeyError,
TypeError,
UnicodeError,
binascii.Error,
json.JSONDecodeError,
) as exc:
raise ValueError("Invalid cursor") from exc
def encode_chat_cursor(user_id: UUID, created_at: datetime, chat_id: UUID) -> str:
data = {
"user_id": str(user_id),
"created_at": created_at.isoformat(),
"chat_id": str(chat_id),
}
raw = json.dumps(data, separators=(",", ":")).encode("utf-8")
return base64.urlsafe_b64encode(raw).decode("ascii")
def decode_chat_cursor(cursor: str) -> tuple[UUID, datetime, UUID]:
try:
raw = base64.b64decode(cursor.encode("ascii"), altchars=b"-_", validate=True)
data = json.loads(raw.decode("utf-8"))
if not isinstance(data, dict) or set(data) != {"user_id", "created_at", "chat_id"}:
raise ValueError("Invalid cursor")
user_id = UUID(data["user_id"])
created_at = datetime.fromisoformat(data["created_at"])
chat_id = UUID(data["chat_id"])
if created_at.tzinfo is None or created_at.utcoffset() is None:
raise ValueError("Invalid cursor")
return user_id, created_at, chat_id
except (ValueError, TypeError, KeyError, UnicodeError, binascii.Error, json.JSONDecodeError) as exc:
raise ValueError("Invalid cursor") from exc
+57
View File
@@ -0,0 +1,57 @@
from collections.abc import AsyncIterator
import socket
from sqlalchemy import text
from sqlalchemy.exc import SQLAlchemyError
from sqlalchemy.ext.asyncio import (
AsyncSession,
async_sessionmaker,
create_async_engine,
)
DATABASE_URL_FILE = "/run/secrets/database_url"
POOL_SIZE = 5
MAX_OVERFLOW = 5
POOL_TIMEOUT_SECONDS = 5
DB_CONNECT_TIMEOUT_SECONDS = 5
def read_database_url() -> str:
with open(DATABASE_URL_FILE, encoding="utf-8") as file:
return file.read().strip()
database_url = read_database_url()
engine = create_async_engine(
database_url,
pool_size=POOL_SIZE,
max_overflow=MAX_OVERFLOW,
pool_timeout=POOL_TIMEOUT_SECONDS,
connect_args={
"timeout": DB_CONNECT_TIMEOUT_SECONDS,
},
pool_pre_ping=True,
)
SessionFactory = async_sessionmaker(
bind=engine,
expire_on_commit=False,
)
async def get_db_session() -> AsyncIterator[AsyncSession]:
async with SessionFactory() as session:
yield session
async def ping_database() -> bool:
try:
async with engine.connect() as connection:
await connection.execute(text("SELECT 1"))
return True
except (SQLAlchemyError, OSError):
return False
+12
View File
@@ -0,0 +1,12 @@
class APIError(Exception):
def __init__(
self,
status_code: int,
code: str,
message: str,
headers: dict[str, str] | None = None,
):
self.status_code = status_code
self.code = code
self.message = message
self.headers = headers
+528
View File
@@ -0,0 +1,528 @@
from datetime import datetime, timedelta, timezone
from uuid import UUID, uuid4
import os
import re
import base64
import binascii
from fastapi import Depends, FastAPI, Request, Header
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from fastapi.security import (
HTTPAuthorizationCredentials,
HTTPBearer,
)
from sqlalchemy.exc import IntegrityError, SQLAlchemyError
from sqlalchemy.ext.asyncio import AsyncSession
from starlette.exceptions import HTTPException as StarletteHTTPException
from contextlib import asynccontextmanager
from src.database import engine, get_db_session, ping_database
from src.errors import APIError
from src.models import CreateUser, SessionResponse, User, CreateChat, Chat, ChatPage, CreateMessage, Message, MessagePage
from src.repositories import (
create_chat,
list_chats,
create_user as create_user_in_db,
get_user_by_id,
get_chat_by_id,
get_user_credentials_by_username,
create_message,
get_messages,
)
from src.security import verify_password
from src.sessions import (
create_session,
delete_session,
get_session_user_id,
ping_session_store,
redis_client,
)
@asynccontextmanager
async def lifespan(app: FastAPI):
yield
await redis_client.aclose()
await engine.dispose()
app = FastAPI(lifespan=lifespan)
INSTANCE_ID = os.getenv("INSTANCE_ID") or str(uuid4())
bearer_security = HTTPBearer(auto_error=False)
async def get_current_user(
credentials: HTTPAuthorizationCredentials | None = Depends(bearer_security),
session: AsyncSession = Depends(get_db_session),
) -> User:
if credentials is None or credentials.scheme.lower() != "bearer":
raise APIError(
status_code=401,
code="unauthorized",
message="Unauthorized",
headers={
"WWW-Authenticate": "Bearer",
},
)
user_id = await get_session_user_id(credentials.credentials)
if user_id is None:
raise APIError(
status_code=401,
code="unauthorized",
message="Unauthorized",
headers={
"WWW-Authenticate": "Bearer",
},
)
user = await get_user_by_id(session, user_id)
if user is None:
raise APIError(
status_code=401,
code="unauthorized",
message="Unauthorized",
headers={
"WWW-Authenticate": "Bearer",
},
)
return user
@app.middleware("http")
async def request_middleware(request: Request, call_next):
request_id = str(uuid4())
request.state.request_id = request_id
if request.method in {"POST", "PUT", "PATCH"}:
content_type = request.headers.get("content-type")
if content_type is not None:
media_type = content_type.split(";", 1)[0].strip().lower()
if media_type != "application/json":
return JSONResponse(
status_code=415,
content={
"error": {
"code": "unsupported_media_type",
"message": "Unsupported media type",
"request_id": request_id,
}
},
headers={
"X-Request-Id": request_id,
"X-Instance-Id": INSTANCE_ID,
},
)
response = await call_next(request)
response.headers["X-Request-Id"] = request_id
response.headers["X-Instance-Id"] = INSTANCE_ID
return response
@app.exception_handler(RequestValidationError)
async def validation_exception_handler(
request: Request,
exc: RequestValidationError,
):
request_id = request.state.request_id
return JSONResponse(
status_code=400,
content={
"error": {
"code": "invalid_request",
"message": "Invalid request",
"request_id": request_id,
}
},
)
@app.exception_handler(APIError)
async def api_error_handler(request: Request, exc: APIError):
request_id = request.state.request_id
return JSONResponse(
status_code=exc.status_code,
content={
"error": {
"code": exc.code,
"message": exc.message,
"request_id": request_id,
}
},
headers=exc.headers,
)
@app.exception_handler(SQLAlchemyError)
async def database_exception_handler(
request: Request,
exc: SQLAlchemyError,
):
request_id = request.state.request_id
return JSONResponse(
status_code=503,
content={
"error": {
"code": "unavailable",
"message": "Database unavailable",
"request_id": request_id,
}
},
)
@app.exception_handler(OSError)
async def database_connection_exception_handler(
request: Request,
exc: OSError,
):
request_id = request.state.request_id
return JSONResponse(
status_code=503,
content={
"error": {
"code": "unavailable",
"message": "Database unavailable",
"request_id": request_id,
}
},
)
@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(
request: Request,
exc: StarletteHTTPException,
):
request_id = request.state.request_id
if exc.status_code == 404:
code = "not_found"
message = "Not found"
else:
code = "invalid_request"
message = "Invalid request"
return JSONResponse(
status_code=exc.status_code,
content={
"error": {
"code": code,
"message": message,
"request_id": request_id,
}
},
headers=exc.headers,
)
@app.exception_handler(Exception)
async def unexpected_exception_handler(
request: Request,
exc: Exception,
):
request_id = request.state.request_id
return JSONResponse(
status_code=500,
content={
"error": {
"code": "internal_error",
"message": "Internal server error",
"request_id": request_id,
}
},
)
@app.get("/health/live")
async def health_live():
return {"status": "ok"}
@app.get("/health/ready")
async def health_ready():
database_ready = await ping_database()
session_store_ready = await ping_session_store()
if not database_ready or not session_store_ready:
raise APIError(
status_code=503,
code="unavailable",
message="Service dependencies unavailable",
)
return {"status": "ok"}
@app.post("/api/v1/users", response_model=User, status_code=201)
async def create_user(
data: CreateUser,
session: AsyncSession = Depends(get_db_session),
):
try:
async with session.begin():
return await create_user_in_db(session, data)
except IntegrityError as exc:
raise APIError(
status_code=409,
code="conflict",
message="Username already exists",
) from exc
@app.get("/api/v1/users/me", response_model=User)
async def get_me(
current_user: User = Depends(get_current_user),
):
return current_user
@app.post(
"/api/v1/auth/sessions",
response_model=SessionResponse,
status_code=201,
)
async def create_auth_session(
authorization: str | None = Header(default=None),
session: AsyncSession = Depends(get_db_session),
):
credentials = None
if authorization is not None:
scheme, separator, encoded = authorization.partition(" ")
if separator and scheme.lower() == "basic":
try:
decoded = base64.b64decode(encoded.strip(), validate=True).decode("utf-8")
if ":" in decoded:
credentials = decoded.split(":", 1)
except (ValueError, UnicodeError, binascii.Error):
pass
if credentials is None:
raise APIError(
status_code=401,
code="unauthorized",
message="Unauthorized",
headers={
"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"',
},
)
user_credentials = await get_user_credentials_by_username(
session,
credentials[0],
)
if user_credentials is None:
raise APIError(
status_code=401,
code="unauthorized",
message="Unauthorized",
headers={
"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"',
},
)
if not verify_password(
user_credentials.password_hash,
credentials[1],
):
raise APIError(
status_code=401,
code="unauthorized",
message="Unauthorized",
headers={
"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"',
},
)
user = User(
id=user_credentials.id,
username=user_credentials.username,
display_name=user_credentials.display_name,
created_at=user_credentials.created_at,
)
token, ttl = await create_session(user.id)
expires_at = datetime.now(timezone.utc) + timedelta(seconds=ttl)
return SessionResponse(
token=token,
token_type="Bearer",
expires_at=expires_at,
user=user,
)
@app.delete(
"/api/v1/auth/sessions/current",
status_code=204,
)
async def delete_current_session(
credentials: HTTPAuthorizationCredentials | None = Depends(bearer_security),
current_user: User = Depends(get_current_user),
):
await delete_session(credentials.credentials)
@app.post(
"/api/v1/chats",
response_model=Chat,
status_code=201,
)
async def create_chat_endpoint(
data: CreateChat,
current_user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_db_session),
) -> Chat:
try:
chat = await create_chat(
session=session,
data=data,
current_user_id=current_user.id,
)
await session.commit()
except Exception:
await session.rollback()
raise
return chat
@app.get(
"/api/v1/chats",
response_model=ChatPage,
)
async def get_chats(
limit: int = 50,
cursor: str | None = None,
current_user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_db_session),
) -> ChatPage:
if limit < 1 or limit > 100:
raise APIError(
status_code=400,
code="invalid_request",
message="Limit must be between 1 and 100",
)
return await list_chats(
session=session,
current_user_id=current_user.id,
limit=limit,
cursor=cursor,
)
@app.get(
"/api/v1/chats/{chat_id}",
response_model=Chat,
)
async def get_chat_endpoint(
chat_id: UUID,
current_user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_db_session),
) -> Chat:
chat = await get_chat_by_id(
session=session,
chat_id=chat_id,
current_user_id=current_user.id,
)
if chat is None:
raise APIError(
status_code=404,
code="not_found",
message="Chat not found",
)
return chat
@app.post(
"/api/v1/chats/{chat_id}/messages",
response_model=Message,
status_code=201,
)
async def create_message_endpoint(
chat_id: UUID,
data: CreateMessage,
idempotency_key: str | None = Header(
default=None,
alias="Idempotency-Key",
),
current_user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_db_session),
) -> Message:
if (
idempotency_key is None
or re.fullmatch(
r"[A-Za-z0-9._:-]{1,128}",
idempotency_key,
) is None
):
raise APIError(
status_code=400,
code="invalid_request",
message="Invalid or missing Idempotency-Key",
)
try:
message = await create_message(
session=session,
chat_id=chat_id,
current_user_id=current_user.id,
data=data,
idempotency_key=idempotency_key,
)
await session.commit()
except Exception:
await session.rollback()
raise
return message
@app.get(
"/api/v1/chats/{chat_id}/messages",
response_model=MessagePage,
)
async def get_messages_endpoint(
chat_id: UUID,
limit: int = 50,
cursor: str | None = None,
current_user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_db_session),
) -> MessagePage:
if limit < 1 or limit > 100:
raise APIError(
status_code=400,
code="invalid_request",
message="Limit must be between 1 and 100",
)
return await get_messages(
session=session,
chat_id=chat_id,
current_user_id=current_user.id,
limit=limit,
cursor=cursor,
)
+118
View File
@@ -0,0 +1,118 @@
from datetime import datetime
from uuid import UUID
from pydantic import BaseModel, ConfigDict, Field, field_validator
class CreateUser(BaseModel):
model_config = ConfigDict(extra="forbid")
username: str = Field(
min_length=3,
max_length=32,
pattern=r"^[a-z0-9_]+$",
)
display_name: str = Field(
min_length=1,
max_length=100,
)
password: str = Field(
min_length=12,
max_length=128,
)
@field_validator("display_name")
@classmethod
def validate_display_name(cls, value: str) -> str:
if not value.strip():
raise ValueError("Display name must not be blank")
return value
class User(BaseModel):
id: UUID
username: str
display_name: str
created_at: datetime
class SessionResponse(BaseModel):
token: str
token_type: str
expires_at: datetime
user: User
class CreateChat(BaseModel):
model_config = ConfigDict(extra="forbid")
title: str = Field(
min_length=1,
max_length=100,
)
member_ids: list[UUID] = Field(
min_length=1,
max_length=100,
)
@field_validator("title")
@classmethod
def validate_title(cls, value: str) -> str:
if not value.strip():
raise ValueError("Chat title must not be blank")
return value
@field_validator("member_ids")
@classmethod
def validate_member_ids(cls, value: list[UUID]) -> list[UUID]:
if len(value) != len(set(value)):
raise ValueError("Member IDs must be unique")
return value
class Chat(BaseModel):
id: UUID
title: str
member_ids: list[UUID]
created_at: datetime
class ChatPage(BaseModel):
items: list[Chat]
next_cursor: str | None
class CreateMessage(BaseModel):
model_config = ConfigDict(extra="forbid")
text: str = Field(
min_length=1,
max_length=4000,
)
@field_validator("text")
@classmethod
def validate_text(cls, value: str) -> str:
if not value.strip():
raise ValueError("Message text must not be blank")
return value
class Message(BaseModel):
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: datetime
class MessagePage(BaseModel):
items: list[Message]
next_cursor: str | None
+655
View File
@@ -0,0 +1,655 @@
from uuid import UUID, uuid4
import hashlib
import json
from sqlalchemy import text
from sqlalchemy.ext.asyncio import AsyncSession
from src.models import Chat, ChatPage, CreateChat, CreateUser, User, CreateMessage, Message, MessagePage
from src.security import hash_password
from src.errors import APIError
from src.cursor import decode_cursor, encode_cursor, decode_chat_cursor, encode_chat_cursor
async def create_user(
session: AsyncSession,
data: CreateUser,
) -> User:
user_id = uuid4()
password_hash = hash_password(data.password)
result = await session.execute(
text(
"""
INSERT INTO users (
id,
username,
display_name,
password_hash
)
VALUES (
:id,
:username,
:display_name,
:password_hash
)
RETURNING
id,
username,
display_name,
created_at
"""
),
{
"id": user_id,
"username": data.username,
"display_name": data.display_name,
"password_hash": password_hash,
},
)
row = result.one()
return User(
id=UUID(str(row.id)),
username=row.username,
display_name=row.display_name,
created_at=row.created_at,
)
async def get_user_credentials_by_username(
session: AsyncSession,
username: str,
):
result = await session.execute(
text(
"""
SELECT
id,
username,
display_name,
password_hash,
created_at
FROM users
WHERE username = :username
"""
),
{
"username": username,
},
)
return result.one_or_none()
async def get_user_by_id(
session: AsyncSession,
user_id: UUID,
) -> User | None:
result = await session.execute(
text(
"""
SELECT
id,
username,
display_name,
created_at
FROM users
WHERE id = :user_id
"""
),
{
"user_id": user_id,
},
)
row = result.one_or_none()
if row is None:
return None
return User(
id=UUID(str(row.id)),
username=row.username,
display_name=row.display_name,
created_at=row.created_at,
)
async def create_chat(
session: AsyncSession,
data: CreateChat,
current_user_id: UUID,
) -> Chat:
if current_user_id not in data.member_ids:
raise APIError(
status_code=400,
code="invalid_request",
message="Current user must be a chat member",
)
users_result = await session.execute(
text(
"""
SELECT id
FROM users
WHERE id = ANY(:member_ids)
"""
),
{
"member_ids": data.member_ids,
},
)
existing_user_ids = {
UUID(str(row.id))
for row in users_result
}
if existing_user_ids != set(data.member_ids):
raise APIError(
status_code=400,
code="invalid_request",
message="Unknown chat member",
)
chat_id = uuid4()
chat_result = await session.execute(
text(
"""
INSERT INTO chats (
id,
title
)
VALUES (
:id,
:title
)
RETURNING
id,
title,
created_at
"""
),
{
"id": chat_id,
"title": data.title,
},
)
chat_row = chat_result.one()
for member_id in data.member_ids:
await session.execute(
text(
"""
INSERT INTO chat_members (
chat_id,
user_id
)
VALUES (
:chat_id,
:user_id
)
"""
),
{
"chat_id": chat_id,
"user_id": member_id,
},
)
return Chat(
id=UUID(str(chat_row.id)),
title=chat_row.title,
member_ids=data.member_ids,
created_at=chat_row.created_at,
)
async def get_chat_by_id(
session: AsyncSession,
chat_id: UUID,
current_user_id: UUID,
) -> Chat | None:
chat_result = await session.execute(
text(
"""
SELECT
c.id,
c.title,
c.created_at
FROM chats AS c
JOIN chat_members AS cm
ON cm.chat_id = c.id
WHERE c.id = :chat_id
AND cm.user_id = :current_user_id
"""
),
{
"chat_id": chat_id,
"current_user_id": current_user_id,
},
)
chat_row = chat_result.one_or_none()
if chat_row is None:
return None
members_result = await session.execute(
text(
"""
SELECT user_id
FROM chat_members
WHERE chat_id = :chat_id
ORDER BY user_id
"""
),
{
"chat_id": chat_id,
},
)
member_ids = [
UUID(str(row.user_id))
for row in members_result
]
return Chat(
id=UUID(str(chat_row.id)),
title=chat_row.title,
member_ids=member_ids,
created_at=chat_row.created_at,
)
async def list_chats(
session: AsyncSession,
current_user_id: UUID,
limit: int,
cursor: str | None = None,
) -> ChatPage:
cursor_created_at = None
cursor_chat_id = None
if cursor is not None:
try:
cursor_user_id, cursor_created_at, cursor_chat_id = decode_chat_cursor(cursor)
except ValueError as exc:
raise APIError(status_code=400, code="invalid_request", message="Invalid cursor") from exc
if cursor_user_id != current_user_id:
raise APIError(status_code=400, code="invalid_request", message="Invalid cursor")
result = await session.execute(
text(
"""
SELECT c.id, c.title, c.created_at
FROM chats AS c
JOIN chat_members AS cm ON cm.chat_id = c.id
WHERE cm.user_id = :current_user_id
AND (
CAST(:cursor_created_at AS timestamptz) IS NULL
OR (c.created_at, c.id) > (
CAST(:cursor_created_at AS timestamptz),
CAST(:cursor_chat_id AS uuid)
)
)
ORDER BY c.created_at, c.id
LIMIT :fetch_limit
"""
),
{
"current_user_id": current_user_id,
"cursor_created_at": cursor_created_at,
"cursor_chat_id": cursor_chat_id,
"fetch_limit": limit + 1,
},
)
rows = result.all()
has_more = len(rows) > limit
page_rows = rows[:limit]
items = []
for chat_row in page_rows:
members_result = await session.execute(
text(
"""
SELECT user_id
FROM chat_members
WHERE chat_id = :chat_id
ORDER BY user_id
"""
),
{"chat_id": chat_row.id},
)
items.append(
Chat(
id=UUID(str(chat_row.id)),
title=chat_row.title,
member_ids=[UUID(str(row.user_id)) for row in members_result],
created_at=chat_row.created_at,
)
)
next_cursor = None
if has_more:
last = page_rows[-1]
next_cursor = encode_chat_cursor(
current_user_id, last.created_at, UUID(str(last.id))
)
return ChatPage(items=items, next_cursor=next_cursor)
async def create_message(
session: AsyncSession,
chat_id: UUID,
current_user_id: UUID,
data: CreateMessage,
idempotency_key: str,
) -> Message:
membership_result = await session.execute(
text("""
SELECT 1
FROM chat_members
WHERE chat_id = :chat_id
AND user_id = :user_id
"""),
{
"chat_id": chat_id,
"user_id": current_user_id,
},
)
if membership_result.scalar_one_or_none() is None:
raise APIError(
status_code=404,
code="not_found",
message="Chat not found",
)
canonical_body = json.dumps(
{"text": data.text},
sort_keys=True,
ensure_ascii=False,
separators=(",", ":"),
)
request_hash = hashlib.sha256(
canonical_body.encode("utf-8")
).hexdigest()
scope = (
f"{current_user_id}:POST:"
f"/api/v1/chats/{chat_id}/messages:"
f"{idempotency_key}"
)
await session.execute(
text("""
SELECT pg_advisory_xact_lock(
hashtextextended(:scope, 0)
)
"""),
{"scope": scope},
)
await session.execute(
text("""
DELETE FROM message_idempotency
WHERE user_id = :user_id
AND chat_id = :chat_id
AND key = :key
AND created_at <=
clock_timestamp() - INTERVAL '24 hours'
"""),
{
"user_id": current_user_id,
"chat_id": chat_id,
"key": idempotency_key,
},
)
existing_result = await session.execute(
text("""
SELECT
i.request_hash,
m.id,
m.chat_id,
m.sender_id,
m.text,
m.created_at
FROM message_idempotency AS i
JOIN messages AS m
ON m.id = i.message_id
WHERE i.user_id = :user_id
AND i.chat_id = :chat_id
AND i.key = :key
"""),
{
"user_id": current_user_id,
"chat_id": chat_id,
"key": idempotency_key,
},
)
existing = existing_result.one_or_none()
if existing is not None:
if existing.request_hash != request_hash:
raise APIError(
status_code=409,
code="conflict",
message=(
"Idempotency key already used "
"with different request body"
),
)
return Message(
id=UUID(str(existing.id)),
chat_id=UUID(str(existing.chat_id)),
sender_id=UUID(str(existing.sender_id)),
text=existing.text,
created_at=existing.created_at,
)
message_id = uuid4()
message_result = await session.execute(
text("""
INSERT INTO messages (
id,
chat_id,
sender_id,
text
)
VALUES (
:id,
:chat_id,
:sender_id,
:text
)
RETURNING
id,
chat_id,
sender_id,
text,
created_at
"""),
{
"id": message_id,
"chat_id": chat_id,
"sender_id": current_user_id,
"text": data.text,
},
)
row = message_result.one()
await session.execute(
text("""
INSERT INTO message_idempotency (
user_id,
chat_id,
key,
request_hash,
message_id
)
VALUES (
:user_id,
:chat_id,
:key,
:request_hash,
:message_id
)
"""),
{
"user_id": current_user_id,
"chat_id": chat_id,
"key": idempotency_key,
"request_hash": request_hash,
"message_id": message_id,
},
)
return Message(
id=UUID(str(row.id)),
chat_id=UUID(str(row.chat_id)),
sender_id=UUID(str(row.sender_id)),
text=row.text,
created_at=row.created_at,
)
async def get_messages(
session: AsyncSession,
chat_id: UUID,
current_user_id: UUID,
limit: int,
cursor: str | None,
) -> MessagePage:
membership_result = await session.execute(
text(
"""
SELECT 1
FROM chat_members
WHERE chat_id = :chat_id
AND user_id = :current_user_id
"""
),
{
"chat_id": chat_id,
"current_user_id": current_user_id,
},
)
if membership_result.scalar_one_or_none() is None:
raise APIError(
status_code=404,
code="not_found",
message="Chat not found",
)
cursor_created_at = None
cursor_message_id = None
if cursor is not None:
try:
(
cursor_chat_id,
cursor_created_at,
cursor_message_id,
) = decode_cursor(cursor)
except ValueError:
raise APIError(
status_code=400,
code="invalid_request",
message="Invalid cursor",
)
if cursor_chat_id != chat_id:
raise APIError(
status_code=400,
code="invalid_request",
message="Cursor belongs to another chat",
)
if cursor is None:
messages_result = await session.execute(
text(
"""
SELECT
id,
chat_id,
sender_id,
text,
created_at
FROM messages
WHERE chat_id = :chat_id
ORDER BY created_at, id
LIMIT :fetch_limit
"""
),
{
"chat_id": chat_id,
"fetch_limit": limit + 1,
},
)
else:
messages_result = await session.execute(
text(
"""
SELECT
id,
chat_id,
sender_id,
text,
created_at
FROM messages
WHERE chat_id = :chat_id
AND (created_at, id) > (
:cursor_created_at,
:cursor_message_id
)
ORDER BY created_at, id
LIMIT :fetch_limit
"""
),
{
"chat_id": chat_id,
"cursor_created_at": cursor_created_at,
"cursor_message_id": cursor_message_id,
"fetch_limit": limit + 1,
},
)
rows = messages_result.all()
has_more = len(rows) > limit
rows = rows[:limit]
items = [
Message(
id=UUID(str(row.id)),
chat_id=UUID(str(row.chat_id)),
sender_id=UUID(str(row.sender_id)),
text=row.text,
created_at=row.created_at,
)
for row in rows
]
next_cursor = None
if has_more:
last_message = items[-1]
next_cursor = encode_cursor(
chat_id=chat_id,
created_at=last_message.created_at,
message_id=last_message.id,
)
return MessagePage(
items=items,
next_cursor=next_cursor,
)
+16
View File
@@ -0,0 +1,16 @@
from argon2 import PasswordHasher
from argon2.exceptions import VerifyMismatchError
password_hasher = PasswordHasher()
def hash_password(password: str) -> str:
return password_hasher.hash(password)
def verify_password(password_hash: str, password: str) -> bool:
try:
return password_hasher.verify(password_hash, password)
except VerifyMismatchError:
return False
+87
View File
@@ -0,0 +1,87 @@
import os
import secrets
from uuid import UUID
from redis.asyncio import Redis
from redis.exceptions import RedisError
from src.errors import APIError
CACHE_URL_FILE = "/run/secrets/cache_url"
DEFAULT_SESSION_TTL_SECONDS = 3600
def read_cache_url() -> str:
with open(CACHE_URL_FILE, encoding="utf-8") as file:
return file.read().strip()
def get_session_ttl_seconds() -> int:
return int(
os.getenv(
"SESSION_TTL_SECONDS",
str(DEFAULT_SESSION_TTL_SECONDS),
)
)
redis_client = Redis.from_url(
read_cache_url(),
decode_responses=True,
socket_connect_timeout=5,
socket_timeout=5,
)
def session_store_unavailable() -> APIError:
return APIError(
status_code=503,
code="unavailable",
message="Session store unavailable",
)
async def create_session(user_id: UUID) -> tuple[str, int]:
token = secrets.token_urlsafe(32)
ttl = get_session_ttl_seconds()
try:
await redis_client.set(
f"session:{token}",
str(user_id),
ex=ttl,
)
except RedisError as exc:
raise session_store_unavailable() from exc
return token, ttl
async def get_session_user_id(token: str) -> UUID | None:
try:
value = await redis_client.get(f"session:{token}")
except RedisError as exc:
raise session_store_unavailable() from exc
if value is None:
return None
try:
return UUID(value)
except ValueError:
return None
async def delete_session(token: str) -> None:
try:
await redis_client.delete(f"session:{token}")
except RedisError as exc:
raise session_store_unavailable() from exc
async def ping_session_store() -> bool:
try:
return bool(await redis_client.ping())
except RedisError:
return False
+46
View File
@@ -0,0 +1,46 @@
import concurrent.futures
import uuid
from client import Client, check
def main():
client = Client("http://localhost:8080")
alice, bob, eve, chat = client.bootstrap()
key = uuid.uuid4().hex
text = "Concurrent idempotency " + key
def send(_):
return client.message(alice, chat, text, key=key)
with concurrent.futures.ThreadPoolExecutor(max_workers=20) as executor:
results = list(executor.map(send, range(20)))
message_ids = {result["json"]["id"] for result in results}
instances = {result["headers"]["X-Instance-Id"] for result in results}
page = client.call(
"GET",
"/api/v1/chats/" + chat["id"] + "/messages?limit=100",
actor=alice,
schema="MessagePage",
)["json"]
matches = [message for message in page["items"] if message["text"] == text]
print("Requests:", len(results))
print("Unique message IDs:", len(message_ids))
print("Instances:", sorted(instances))
print("Messages in history:", len(matches))
check(len(message_ids) == 1, "duplicate message IDs returned")
check(len(instances) >= 2, "requests did not reach both replicas")
check(len(matches) == 1, "duplicate messages found in history")
check(matches[0]["id"] in message_ids, "history message ID differs")
print("PASS: concurrent idempotency across replicas")
if __name__ == "__main__":
main()
@@ -0,0 +1,80 @@
import concurrent.futures
import subprocess
import threading
import time
import uuid
from client import Client, Failure, check, run
def main():
client = Client("http://localhost:8080", timeout=5)
alice, bob, eve, chat = client.bootstrap()
key = uuid.uuid4().hex
text = "Failover concurrent idempotency " + key
start = threading.Event()
def send(_):
start.wait()
try:
response = client.message(alice, chat, text, key=key)
return response["json"]["id"], response["headers"]["X-Instance-Id"], None
except Failure as exc:
return None, None, str(exc)
with concurrent.futures.ThreadPoolExecutor(max_workers=20) as executor:
futures = [executor.submit(send, i) for i in range(20)]
process = subprocess.Popen(
["docker", "compose", "stop", "api-1"],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
)
start.set()
results = [future.result() for future in futures]
code = process.wait(timeout=20)
check(code == 0, "failed to stop api-1")
successful_ids = {item[0] for item in results if item[0] is not None}
instances = {item[1] for item in results if item[1] is not None}
failures = [item[2] for item in results if item[2] is not None]
check(len(successful_ids) <= 1, "different message IDs returned")
recovered = client.message(alice, chat, text, key=key)
message_id = recovered["json"]["id"]
check(
not successful_ids or successful_ids == {message_id},
"message ID changed after failover",
)
page = client.call(
"GET",
"/api/v1/chats/" + chat["id"] + "/messages?limit=100",
actor=alice,
schema="MessagePage",
)["json"]
matches = [message for message in page["items"] if message["text"] == text]
print("Concurrent requests:", len(results))
print("Successful requests:", len(results) - len(failures))
print("Failed requests:", len(failures))
print("Instances:", sorted(instances))
print("Unique successful message IDs:", len(successful_ids))
print("Messages in history:", len(matches))
print("Recovered message ID:", message_id)
check(len(matches) == 1, "duplicate messages found in history")
check(matches[0]["id"] == message_id, "history message ID differs")
print("PASS: concurrent idempotency preserved during api-1 failover")
if __name__ == "__main__":
run(main)
+52
View File
@@ -0,0 +1,52 @@
import base64
import json
import os
import time
import urllib.error
import urllib.parse
import urllib.request
BASE_URL = os.environ.get('BASE_URL', 'http://localhost:8080')
def request(method, path, body=None, token=None, basic=None, expected=200):
headers = {}
if body is not None:
headers['Content-Type'] = 'application/json'
if token:
headers['Authorization'] = 'Bearer ' + token
if basic:
headers['Authorization'] = 'Basic ' + base64.b64encode(basic.encode('utf-8')).decode('ascii')
data = json.dumps(body, ensure_ascii=False).encode('utf-8') if body is not None else None
req = urllib.request.Request(BASE_URL + path, data=data, headers=headers, method=method)
try:
with urllib.request.urlopen(req, timeout=15) as response:
status = response.status
result = response.read()
except urllib.error.HTTPError as exc:
status = exc.code
result = exc.read()
assert status == expected, f'{method} {path}: expected {expected}, got {status}: {result!r}'
return json.loads(result) if result else None
def main():
username = 'review_' + str(time.time_ns())[-16:]
password = 'Пример:пароля-12345'
user = request('POST', '/api/v1/users', {'username': username, 'display_name': 'Проверка', 'password': password}, expected=201)
session = request('POST', '/api/v1/auth/sessions', basic=username + ':' + password, expected=201)
assert session['user']['id'] == user['id']
token = session['token']
first = request('POST', '/api/v1/chats', {'title': 'Первый', 'member_ids': [user['id']]}, token=token, expected=201)
second = request('POST', '/api/v1/chats', {'title': 'Второй', 'member_ids': [user['id']]}, token=token, expected=201)
page1 = request('GET', '/api/v1/chats?limit=1', token=token)
assert len(page1['items']) == 1 and page1['next_cursor'], page1
page2 = request('GET', '/api/v1/chats?limit=1&cursor=' + urllib.parse.quote(page1['next_cursor']), token=token)
assert len(page2['items']) == 1 and page2['next_cursor'] is None, page2
assert [page1['items'][0]['id'], page2['items'][0]['id']] == [first['id'], second['id']]
request('GET', '/api/v1/chats?limit=1&cursor=invalid', token=token, expected=400)
print('PASS: UTF-8 Basic Auth, colon in password, chat cursor, last page, invalid cursor')
if __name__ == '__main__':
main()