ЛР 2 — БВТ2301 — Кокорин — на 4 #94

Closed
kokorindenis wants to merge 2 commits from kokorindenis/mtusi2026lab2:solution/bvt2301-kokorin into master
70 changed files with 8193 additions and 17 deletions
+10
View File
@@ -18,3 +18,13 @@ __pycache__
node_modules
evidence
.DS_Store
# В образ не входят контракт, публичные тесты и отладочные материалы:
# приложению нужны только src/, migrations/, alembic.ini и requirements.txt.
tests
student-tests
contracts
examples
infra
Makefile
*.md
.vscode
+50
View File
@@ -0,0 +1,50 @@
# Сборка и рантайм разделены: в итоговый образ не попадают кэш pip и инструменты
# сборки, а зависимости ставятся по зафиксированному requirements.txt.
# Базовый образ закреплён по неизменяемому digest, а не только по тегу.
FROM python:3.11.9-slim-bookworm@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317 AS builder
ENV PIP_NO_CACHE_DIR=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1 \
PYTHONDONTWRITEBYTECODE=1
RUN python -m venv /opt/venv
COPY requirements.txt ./
RUN /opt/venv/bin/pip install --no-cache-dir --timeout 60 -r requirements.txt
FROM python:3.11.9-slim-bookworm@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317 AS runtime
LABEL org.opencontainers.image.title="mtusi-messenger-lab2" \
org.opencontainers.image.description="API мессенджера на PostgreSQL и Valkey, лабораторная 2 (MTUSI HighLoad)" \
org.opencontainers.image.version="2.0.0"
ENV PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 \
PATH="/opt/venv/bin:$PATH" \
PYTHONPATH=/app/src \
APP_HOST=0.0.0.0 \
APP_PORT=8080
WORKDIR /app
RUN useradd --create-home --uid 10001 --shell /usr/sbin/nologin app
COPY --from=builder /opt/venv /opt/venv
# Миграции лежат в образе: роль контейнера задаётся командой (api или migrate).
COPY --chown=app:app src/ ./src/
COPY --chown=app:app alembic.ini ./
COPY --chown=app:app migrations/ ./migrations/
# Приложение работает без прав root: в образе нет ни компилятора, ни secrets.
USER 10001:10001
EXPOSE 8080
# SIGTERM доходит до PID 1 напрямую: uvicorn завершает запросы в своём бюджете.
STOPSIGNAL SIGTERM
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
CMD ["python", "-m", "messenger.healthcheck"]
CMD ["python", "-m", "messenger"]
+8 -2
View File
@@ -4,10 +4,10 @@ CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
.PHONY: help check validate test load test-persistence
.PHONY: help check validate test load test-persistence secrets student-test
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes; secrets: create local secrets/ (never overwrites); student-test: own checks (student-tests/run_all.py)"
check:
$(PYTHON) scripts/check_contract.py
@@ -24,3 +24,9 @@ load:
test-persistence:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable restart hook"; exit 2)
$(PYTHON) tests/resilience.py --mode persistence --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
secrets:
sh scripts/bootstrap-secrets.sh
student-test:
$(PYTHON) student-tests/run_all.py --base-url "$(BASE_URL)"
+466 -15
View File
@@ -1,37 +1,488 @@
# Отчёт — лабораторная 2
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Кокорин Денис, БВТ2301
- Целевая оценка: **4** — уровень 3 целиком и все пункты уровня 4; трек 5 не заявляем
- Commit/PR: решение лежит в ветке `solution/bvt2301-kokorin`; коммиты делает автор,
поэтому ссылки на PR здесь нет
- Использованные источники, библиотеки и помощь ИИ: см. раздел «Источники и ИИ»
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
### Версии и предпосылки
| Компонент | Версия | Примечание |
| --- | --- | --- |
| Python | 3.11.9 | локально и в образе |
| Docker Engine | 28.0.1 | Docker Desktop, Windows 10 Pro 19045, AMD64 |
| Docker Compose | 2.33.1-desktop.1 | |
| Базовый образ | `python:3.11.9-slim-bookworm` | digest `sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317`, тот же в builder и runtime |
| PostgreSQL | `postgres:16.15-bookworm` | digest `sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4` |
| Valkey | `valkey/valkey:8.0.11-trixie` | digest `sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab` |
| Образ приложения | `mtusi-messenger-lab2:2.0.0` | сборка с нуля 1 м 35 с, 74 408 022 байта (~71 МиБ) |
Все 24 зависимости закреплены точными версиями в `requirements.txt` — это полное
замыкание `pip freeze` на Python 3.11.9, включая транзитивные.
Обязательных действий оператора два: скопировать `.env.example` в `.env` (там только
несекретные значения) и создать локальные секреты — `make secrets`, он же
`sh scripts/bootstrap-secrets.sh`. Первый запуск занимает минуты из-за сборки образа,
последующие — секунды.
```sh
git clone <URL своего fork> && cd mtusi2026lab2
git checkout solution/bvt2301-kokorin
cp .env.example .env # порт и TTL; секретов здесь нет
make secrets # то же, что sh scripts/bootstrap-secrets.sh: режим 600,
# повторный запуск существующие файлы не перезаписывает
docker compose --env-file .env config --quiet # конфигурация валидна (пустой вывод)
docker compose --env-file .env up -d --build # migrate → api, публикация 127.0.0.1:8080
# готовность: обычно 1–2 с после старта api
curl -s http://127.0.0.1:8080/health/ready # {"status":"ok"}
# в другом терминале
make check
python3 -m venv .venv && .venv/Scripts/python.exe -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/Scripts/python.exe
make test BASE_URL=http://127.0.0.1:8080
make test-persistence ACTION_SCRIPT=scripts/restart.cmd BASE_URL=http://127.0.0.1:8080
make student-test BASE_URL=http://127.0.0.1:8080 PYTHON="python3 -X utf8"
```
Инструкция проверена целиком на копии репозитория без игнорируемых Git файлов:
сборка `--no-cache` 1 м 35 с в первом прогоне и 2 м 49 с в повторном, `up -d` 8–19 с,
готовность через 1 с, `make check` и `make validate` — PASS, `make test` — PASS,
`make test-persistence` — PASS, `make student-test` — 82 теста OK за 30.9 с.
Транскрипт — `evidence/12-clean-clone.txt` (первый прогон и повторный на итоговом дереве).
Три оговорки для Windows, все проверены на практике:
- Хук перезапуска вызывается тестом через `Popen([script])` без оболочки, а Windows
исполняет так только `.exe`/`.cmd`/`.bat`: `.sh` падает с `WinError 193`. Поэтому в
комплекте есть `scripts/restart.cmd` — двойник POSIX-версии с тем же поведением;
оба запускаются в доказательстве 02.
- `make` в этом окружении (MSYS/Git Bash) не передаёт рецептам переменные окружения —
работают только переопределения в командной строке, отсюда `PYTHON="python3 -X utf8"`.
- Адрес стенда в примерах — `127.0.0.1`, а не `localhost`: на Windows `localhost`
сначала разрешается в `::1`, и каждый запрос платит около 2 с за откат на IPv4
(это измерение есть и в отчёте по лабораторной 1). Публичные тесты по умолчанию
ходят на `localhost` — это их право, время в них не измеряется.
### Безопасная остановка и удаление учебных данных
```sh
docker compose stop # остановить, сохранив тома: данные на месте
docker compose start # вернуть стенд
docker compose down # убрать контейнеры и сеть; тома pgdata и valkeydata остаются
docker compose down -v # намеренно удалить учебные данные вместе с томами
```
Порядок именно такой, и `-v` стоит последним, потому что после него данные не вернуть.
Хуки перезапуска в репозитории удаление не делают вовсе: `scripts/restart.sh` и его
`.cmd`-двойник вызывают только `docker compose restart --timeout 10 api postgres valkey`
и проверяют, что все три сервиса снова running (доказательство 02).
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
### Схема
```
Клиент (curl, tests/smoke.py, tests/load.py, student-tests)
│ HTTP/1.1 + JSON; Basic — только на POST /api/v1/auth/sessions, дальше Bearer
▼
RequestContextMiddleware — X-Request-Id и access-лог
▼
FastAPI + Pydantic — валидация на границе, зависимости, единый конверт ошибок
▼
repository (SQL, только bind-параметры) sessions (SessionStore)
▼ ▼
PostgreSQL — источник истины Valkey — только сессии
users, chats, chat_members, messages messenger:session:<sha256(token)>, TTL
```
Модули: `domain` (сущности и правила) ← `repository`, `sessions`, `security`;
`access` и `deps` связывают их с `routers`; сборка — в `app`, конфигурация — в `config`,
схема — в `schema`, миграции — в `migrations/`. Транспорт не знает ни об SQL, ни о
ключах Valkey: замена хранилища не трогает обработчики, а замена формата ответа не
трогает запросы.
Сопоставление ролей из `contracts/infrastructure.json` с фактическими сервисами,
версиями, digest'ами, healthcheck'ами, томами, сетями и способом передачи credentials
(как требует `infra/README.md`) — в `evidence/10-infra-mapping.txt`.
### Таблицы, ограничения, индексы
| Таблица | Ключи и ограничения |
| --- | --- |
| `users` | `id uuid pk`, `uq_users_username` (уникальный индекс), `ck_users_username_format`, `ck_users_display_name_length`, `created_at timestamptz` |
| `chats` | `id uuid pk`, `ck_chats_title_length`, `created_at` |
| `chat_members` | `pk(chat_id, user_id)`, FK на `chats` с `on delete cascade`, FK на `users` с `on delete restrict` |
| `messages` | `id uuid pk`, FK на `chats`, FK на `users`, `ck_messages_text_length`, `created_at` |
Индексов ровно три, и каждый появился под конкретный запрос, а не «на всякий случай»:
- `ix_messages_chat_id_created_at_id (chat_id, created_at, id)` — равенство по чату,
порядок истории и позиция keyset-курсора (обоснование — доказательство 07).
- `ix_chat_members_user_id_chat_id (user_id, chat_id)` — «мои чаты» (доказательство 08).
- `uq_users_username (username)` — уникальность имени, она же закрывает гонку регистрации.
Время назначает база (`now()` + `RETURNING`), а не процесс: часы приложения и часы БД
разъезжаются, и порядок истории должен зависеть от одного источника. Ничья по
`created_at` разрешается `id` — контракт этого и требует, а публичный smoke сравнивает
выдачу с сортировкой по `(created_at, id)`.
### Транзакционные границы и гонки
- **Регистрация** — предпроверка `SELECT` (избавляет от argon2 на заведомо занятом
имени) плюс один оператор `INSERT ... ON CONFLICT (username) DO NOTHING RETURNING id`.
Пустой `RETURNING` означает, что имя занято: 409 без аборченной транзакции. Гонку
закрывает уникальный индекс, а не предварительная проверка, которая между `SELECT` и
`INSERT` ничего не гарантирует: при одновременной регистрации проигравший зря
хэширует пароль, но теряет только время. Проверка: 12 одновременных регистраций
одного имени дают ровно один 201.
- **Создание чата** — одна транзакция: `INSERT chats RETURNING` плюс `INSERT
chat_members` по всем участникам. Неизвестный участник даёт ошибку внешнего ключа
`23503`, транзакция откатывается целиком, клиент получает 400, и чата не остаётся.
Именно это и есть проверяемый откат составной операции.
- **Между страницами истории нет snapshot-изоляции**: каждый запрос — своя транзакция.
Строка, вставленная во время обхода, может появиться на следующей странице, если её
ключ больше курсора, и не появиться, если меньше. Уже отданные строки не дублируются —
это свойство keyset-позиции. Транзакция, начатая до чтения страницы, но зафиксированная
после, теоретически может добавить строку «позади» курсора: тогда её не увидит этот
обход. Для мессенджера это приемлемо (история не перечитывается ради точности), но
это ограничение, а не гарантия.
### Источник истины, сессии, expiry и инвалидация
Источник истины ровно один — PostgreSQL: пользователи, чаты, членство, сообщения.
Valkey хранит **только сессии**. Разделение выбрано так, чтобы у каждого хранилища была
одна роль: если Valkey потеряет всё, никто не потеряет данные, но все разлогинятся;
если бы сессии лежали ещё и в PostgreSQL, появилось бы два источника истины и вопрос
«чья запись главнее», который в лабораторной негде проверить.
- Ключ — `messenger:session:<sha256(token)>`. Сам токен (256 бит из
`secrets.token_urlsafe`) в хранилище не попадает, поэтому дамп Valkey, `MONITOR` и
логи не выдают действующих токенов.
- Значение — JSON с `user_id`, `created_at`, `expires_at`, но **сроком владеет
хранилище**: TTL ставится на ключ (`SET ... EX`). Приложение не хранит свой счётчик
времени, поэтому перезапуск процесса не продлевает сессию: в доказательстве 04 у
токена, выданного при TTL 3600, после переключения на TTL 3 осталось 3596 с.
- Инвалидация — `GETDEL` при logout: удаление атомарно, повторный logout получает 401,
а не 204 и не 404. Истечение и отзыв — независимые механизмы; приложение не
подчищает просроченные ключи, это делает Valkey (в 04 видно, что ключ исчез сам
между двумя запросами).
- Долговечность — AOF (`appendonly yes`, `appendfsync everysec`), RDB выключен, чтобы
механизм был ровно один и его было видно в evidence. Цена честная: при гибели
процесса теряется примерно последняя секунда записей — это измерено в 05.
- `SESSION_STORE` принимает только `redis` и падает при старте на любом другом
значении, включая `postgres` из `.env.example`. Молча проигнорировать переменную было
бы хуже: человек решил бы, что сессии лежат в PostgreSQL, а они лежали бы в Valkey.
### Пагинация и курсор
История и список чатов листаются по ключу: `WHERE chat_id = $1 AND ($2::timestamptz IS
NULL OR (created_at, id) > ($2, $3)) ORDER BY created_at, id LIMIT $4`. В выборке
запрашивается `limit + 1` строка: лишняя означает `has_more`, а её ключ становится
`next_cursor` — без второго запроса и без «сколько там всего». UUID сравнивается в
PostgreSQL нативно (порядок байтов совпадает с порядком `uuid.UUID(x).int`, которым
публичный smoke сортирует выдачу), поэтому курсор и сортировка не расходятся.
Курсор подписан HMAC-SHA256 (`CURSOR_SECRET`), привязан к ресурсу и не содержит
`limit`: обход можно продолжить с другим размером страницы, а чужой курсор даёт 400.
Альтернатива с `OFFSET` измерена в 07: 4.078 мс против 0.267 мс на десятой тысяче
строк, и она читает 10 000 строк там, где keyset читает 199.
### Ошибки
Единый конверт `{"error":{"code","message","request_id"}}`; `request_id` совпадает с
заголовком `X-Request-Id`. Штатный 422 FastAPI перехвачен и приведён к контрактному
400 `invalid_request`. **403 не используется нигде**: чужой чат неотличим от
несуществующего — 404; сначала аутентификация (401), затем доступ к ресурсу.
`WWW-Authenticate` соответствует маршруту: `Basic` предлагается только на
`POST /api/v1/auth/sessions`, на бизнес-маршрутах челлендж — `Bearer`, иначе клиент с
Basic-креденшелами получил бы приглашение повторить то, что и привело к отказу.
Неверный пароль и несуществующий пользователь отвечают одинаково, и время ответа
выравнивается проверочным хешем, чтобы отказ не выдавал существование имени.
Валидация на границе отвергает две категории строк, которые не должны доходить до
базы: пароль из одних пробельных символов (это пустое значение обязательного поля,
а не секрет) и U+0000 в сохраняемых строках — PostgreSQL `text` его не хранит.
Обе дают 400 `invalid_request`. 503 `unavailable` закреплён только за отказами
соединения и пула (`OperationalError`, `InterfaceError`, `DisconnectionError`,
таймаут пула, ошибки Valkey): `DataError` — ошибка данных клиента — в это семейство
не входит, поэтому сбой значения не маскируется под аварию зависимости.
### Таймауты и поведение при отказе зависимостей
| Параметр | Значение | Зачем именно столько |
| --- | --- | --- |
| `DB_POOL_SIZE` / `DB_MAX_OVERFLOW` | 5 / 5 | Верхняя граница одновременных соединений задана на процесс; при `workers>1` её пришлось бы делить, поэтому процесс один |
| `DB_POOL_TIMEOUT_SECONDS` | 2 | Ожидание свободного соединения в пуле — последняя линия, а не первая |
| `DB_CONNECT_TIMEOUT_SECONDS` | 1.5 | Отдельный таймаут подключения: разрешение имени остановленного контейнера занимает ~3.3 с (доказательство 06), и общий бюджет запроса его не покрывает |
| `DB_COMMAND_TIMEOUT_SECONDS` | 2.5 | Клиентский потолок на запрос |
| `DB_STATEMENT_TIMEOUT_MS` | 2000 | Серверный `statement_timeout` строже клиентского: запрос обрывает PostgreSQL, а не только клиент, и соединение возвращается в пул живьём |
| `CACHE_TIMEOUT_SECONDS` | 1 | Сессия — одна операция в Valkey; секунды хватает с запасом |
При недоступной зависимости бизнес-маршруты и `/health/ready` отвечают 503
`unavailable`, а не 401 и не «доверяем анониму»: клиент, реагирующий на 401 повторным
входом, выбросил бы рабочую сессию из-за чужой аварии. `/health/live` при этом остаётся
200 — супервизор не должен перезапускать здоровый процесс.
### Логи и `X-Request-Id`
`RequestContextMiddleware` стоит снаружи стека Starlette, поэтому заголовок есть и на
ответе 500. Лог — JSON-строка на событие: `request_id`, метод, **шаблон маршрута**,
статус, длительность, `user_id`. Тел запросов, текстов сообщений и query-строки с
курсором в логе нет, access-лог uvicorn отключён. `verify_stack.py` отдельно проверяет
по всему логу контейнера (11 512 строк), что в нём не встречаются ни пароль, ни токен,
ни ключ сессии.
### Живость, готовность, остановка
- `/health/live` — «процесс жив», зависимости не трогает; его опрашивает Docker.
- `/health/ready` — «можно принимать трафик»: проверяет PostgreSQL и Valkey. На старте
неудачный `ping` **не фатален**: при одновременном подъёме api, PostgreSQL и Valkey
приложение стартовало бы в петлю перезапусков, а готовность — это как раз то, что
должно быть красным, пока зависимости недоступны.
- `CMD` в exec-форме, приложение — PID 1, `STOPSIGNAL SIGTERM`. Бюджет остановки —
`GRACEFUL_SHUTDOWN_SECONDS` (5) плюс `SHUTDOWN_DRAIN_SECONDS` (0 в стенде;
значение больше 10 отвергается при старте с кодом 2).
### Соответствие переменных `.env.example`
| `.env.example` | Где используется | По умолчанию | Замечание |
| --- | --- | --- | --- |
| `APP_HOST` | `Config.host` → адрес bind | `0.0.0.0` | в compose задано явно |
| `APP_PORT` | `Config.port` → порт bind и healthcheck | `8080` | проверяется диапазон 1..65535 |
| `APP_ENV` | `Config.env` → метка в логах | `lab` | |
| `SESSION_TTL_SECONDS` | `Config.session_ttl_seconds` | `3600` | допустимо 1..86400; короткое значение включает проверки истечения |
| `SESSION_STORE` | `Config.session_store` | `redis` | допускается только `redis`; `postgres` из примера отвергается при старте |
| `DATABASE_URL_FILE` | `Config.database_url` | — | обязательна; `DATABASE_URL` и `*_FILE` одновременно — ошибка |
| `CACHE_URL_FILE` | `Config.cache_url` | — | обязательна; тот же принцип «значение или файл» |
Дополнительно поддерживаются `LOG_LEVEL`, `DB_POOL_SIZE`, `DB_MAX_OVERFLOW`,
`DB_POOL_TIMEOUT_SECONDS`, `DB_CONNECT_TIMEOUT_SECONDS`, `DB_COMMAND_TIMEOUT_SECONDS`,
`DB_STATEMENT_TIMEOUT_MS`, `CACHE_TIMEOUT_SECONDS`, `GRACEFUL_SHUTDOWN_SECONDS`,
`SHUTDOWN_DRAIN_SECONDS`, `CURSOR_SECRET(_FILE)`. Некорректное значение — отказ старта
с понятным сообщением и кодом выхода 2, а не тихая подстановка умолчания. Значения
секретов в текст ошибок не попадают.
### Что перенесено из лабораторной 1 и что изменено в файлах skeleton
Перенесены: `context`, `middleware`, `logging_setup`, `healthcheck`, `errors`,
`errorhandlers`, `domain`, `models`, `schema`, `cursor`, `pagination`, `config`,
`deps`, `access`, `routers`, `app` и `__main__` — то есть структура и дисциплина
(конверт ошибок, `X-Request-Id`, JSON-логи без содержимого, русские docstring'и,
полные type hints, `docs_url=None`). Изменено по существу: хранилище (память → SQL),
идентификация (`X-User-Id` → Basic-вход и opaque Bearer-сессия с TTL и отзывом),
появились `repository`, `db`, `security`, `sessions`, `migrations/`, `Dockerfile`,
`compose.yaml`. Строка `X-User-Id` не читается нигде. `X-Instance-Id` и
`Idempotency-Key` не добавлялись — это возможности лабораторной 3.
В файлах skeleton изменены только три: `Makefile` (добавлена цель `student-test` и
строка в `help`), `.dockerignore` (дополнен — в образ не входят `tests/`,
`student-tests/`, `contracts/`, `examples/`, `infra/`, `Makefile`, `*.md`) и этот
`REPORT.md`. Контракт, публичные тесты, `README.md`, `COURSE.md`, `lab.json`,
`scripts/check_contract.py`, `scripts/validate_openapi.py` и `.github/**` не
изменялись.
## Доказательства критериев
Все измерения сделаны на стенде: Windows 10 Pro 19045, x64, Python 3.11.9,
Docker 28.0.1 (WSL2), контейнеры ограничены 2 CPU и 512 МБ (api, postgres), 1 CPU и
256 МБ (valkey).
### Уровень 3
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
| Минимум lab1 сохранён с переходом на новую аутентификацию | `make test` | `PASS: lab2 public API scenario` | `evidence/01-check-and-smoke.txt` |
| Данные и действующие сессии переживают рестарт API и хранилищ без удаления volumes | `make test-persistence ACTION_SCRIPT=scripts/restart.cmd` | `PASS: persistence preserved confirmed data and existing session`; `StartedAt` сменился у всех трёх контейнеров | `evidence/02-persistence-restart.txt` |
| PostgreSQL содержит пользователей, чаты, участников и сообщения; PK/FK, уникальность username | `python student-tests/verify_stack.py`, разд. 6 | таблицы, `uq_users_username`, CHECK-ограничения и индексы на месте | `evidence/11-container-security.txt` |
| Миграции с нуля | `docker compose up -d` на пустом томе в чистом клоне | `migrate` применяет схему и выходит с кодом 0 | `evidence/12-clean-clone.txt` |
| Миграции повторяются без дублирования | `alembic upgrade head` второй раз, `verify_stack.py` разд. 6 | «нет Running upgrade» — повторный прогон ничего не меняет; `alembic check` совпадает с моделями | `evidence/11-container-security.txt` |
| Составная операция создания чата атомарна | `make student-test` (`test_chat_atomicity`) | 6 тестов: неизвестный участник, дубликат и отсутствие создателя дают 400, чата не остаётся | `evidence/03-student-tests.txt` |
| Basic только на `POST /auth/sessions`, остальное Bearer | `make student-test` (`test_auth`) | 14 тестов: Basic на бизнес-маршруте → 401 с челленджем `Bearer` | `evidence/03-student-tests.txt` |
| Есть срок жизни сессии и отзыв | `test_sessions`, `test_expiry` | 10 + 4 теста: несколько независимых сессий, logout → 204, повтор → 401, истечение по TTL | `evidence/03-student-tests.txt`, `evidence/04-expiry-short-ttl.txt` |
| `X-User-Id` не даёт доступа | `test_auth`, публичный smoke | заголовок лабораторной 1 не даёт доступа и не подменяет сессию | `evidence/03-student-tests.txt` |
| Пароли хешируются KDF | `test_auth` | 128 кириллических кодовых точек (256 байт) и пароль длиннее 72 байт не усекаются | `evidence/03-student-tests.txt` |
| Secrets/volumes не попадают в Git | `verify_stack.py` разд. 4 (`git check-ignore`) | `secrets/` и `.env` игнорируются, в индексе Git нет файлов `secrets/` | `evidence/11-container-security.txt` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
### Уровень 4
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Valkey реально используется для сессий с TTL | `verify_stack.py` разд. 5 и 7 | ключ — sha256 токена, а не сам токен; `TTL` ключа положителен; сырой токен не встречается ни в одном имени ключа | `evidence/11-container-security.txt` |
| Источник истины, политика expiry и инвалидации описаны | раздел «Архитектура и решения» + `test_expiry` | TTL принадлежит хранилищу: `expires_at` в ответе и TTL ключа совпадают (3.00 с против 3 с); logout — атомарный `GETDEL` | `evidence/04-expiry-short-ttl.txt` |
| Persistence, выдерживающее проверяемый рестарт | `make test-persistence`; `test_dependency_outage::test_valkey_outage`; `valkey_crash.py` | сессия возвращается вместе с TTL 3595 с после `stop` и после `kill -9` процесса | `evidence/02-persistence-restart.txt`, `evidence/05-valkey-outage.txt` |
| Параметризованные запросы, ограниченный pool, таймауты | `src/messenger/repository.py` (только bind-параметры, без f-строк), `compose.yaml`, `verify_stack.py` разд. 9 | пул 5+5, лимиты CPU/памяти и политика `restart` заданы; бюджет таймаутов измерен на живом отказе | `evidence/06-postgres-outage.txt` |
| Гонка регистрации одинакового username проверена | `test_registration_race` | 12 одновременных регистраций → ровно один 201, остальные 409, в базе одна строка | `evidence/03-student-tests.txt` |
| Rollback составной операции проверен | `test_chat_atomicity` | 400 на неизвестном участнике и ни одного созданного чата | `evidence/03-student-tests.txt` |
| Индекс истории обоснован `EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщениях | `student-tests/seed_messages.py` (20 116 сообщений, 3 071 чат) + `student-tests/explain_queries.py` | используется `ix_messages_chat_id_created_at_id`, `Rows Removed by Filter: 0`, 199 прочитанных строк; без индекса — `Seq Scan` + `Sort`, 20 116 строк и в 6 раз медленнее | `evidence/07-explain-messages.txt` |
| Индекс «моих чатов» обоснован | `explain_queries.py --only chats` | `Index Only Scan` — 1 001 строка из 3 105; без индекса `Seq Scan` по той же таблице; отдельно показана граница применимости | `evidence/08-explain-chats.txt` |
| Пагинация не сканирует всю историю | `explain_queries.py`, разд. 4 | keyset 0.267 мс и 199 строк против `OFFSET 9999` — 4.078 мс и 10 000 строк; обе страницы возвращают один и тот же набор | `evidence/07-explain-messages.txt` |
| Автоматическая проверка expiry при коротком `SESSION_TTL_SECONDS` | `test_expiry` при `SHORT_TTL_SECONDS=3` | токен, выданный до переключения, продолжает работать (3596 с из 3600); через 4 с отвергается обоими маршрутами, ключ исчезает сам | `evidence/04-expiry-short-ttl.txt` |
| Автоматическая проверка logout | `test_sessions` | 204 без тела, повтор → 401, отзыв одной сессии не трогает остальные | `evidence/03-student-tests.txt` |
| Автоматическая проверка неверного пароля | `test_auth` | одинаковый 401 для неверного пароля и неизвестного пользователя | `evidence/03-student-tests.txt` |
| Автоматическая проверка недоступности Redis/БД | `ALLOW_OUTAGE=1 … -p test_dependency_outage.py` | все маршруты: 503 `unavailable` за 1.0–1.5 с, ни одного 401 и ни одного 200; `/health/live` остаётся 200 | `evidence/05-valkey-outage.txt`, `evidence/06-postgres-outage.txt` |
| Приложение не принимает запрос анонимного пользователя как доверенный | те же прогоны | при недоступной зависимости доступа нет ни у кого: 503, а не «пустим как анонима» | `evidence/05-valkey-outage.txt`, `evidence/06-postgres-outage.txt` |
| PR собирается из чистого clone | копия без игнорируемых файлов → `up -d --build` → `make check`/`validate`/`test`/`test-persistence`/`student-test` | сборка с нуля 1 м 35 с и 2 м 49 с в двух прогонах, миграции на пустом томе, все проверки PASS, 82 теста OK | `evidence/12-clean-clone.txt` |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
### Измерение 1. Индекс истории: 20 116 сообщений, ключ `(created_at, id)`
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
Гипотеза: индекс `(chat_id, created_at, id)` отдаёт страницу истории по порядку, без
сортировки всей выборки и без чтения чужих сообщений. Данные — засев через
`generate_series`, включая пары с одинаковым `created_at`, затем `ANALYZE`; чат для
эксперимента содержит 10 000 сообщений.
Планы: страница середины истории — `Limit → Sort → Bitmap Heap Scan → Bitmap Index Scan`
(сортируется выборка чата, а не вся таблица), страница с курсором у конца истории —
`Limit → Index Scan` вообще без узла `Sort`, потому что порядок задаёт индекс.
`Rows Removed by Filter: 0` — курсор отсекает строки индексом, а не фильтром после
чтения; прочитано 199 строк, то есть две страницы по 100 и одна лишняя для `has_more`.
Контрпример получен честно: `BEGIN; DROP INDEX ...; EXPLAIN; ROLLBACK`. Сравнение на
странице с курсором (нижняя граница диапазона ключей): 199 строк и 0.267 мс с индексом
против 20 116 строк, `Seq Scan` и 1.601 мс без него, то есть **в 6 раз медленнее и в
101 раз больше прочитанных строк**. `ROLLBACK` вернул индекс на место (проверено
отдельным запросом к каталогу).
`OFFSET` против курсора на десятой тысяче строк: 4.078 мс против 0.267 мс, и `OFFSET`
читает 10 000 строк, которые всё равно выбрасывает. Это и есть ответ на «пагинация не
просматривает всю историю».
### Измерение 2. Граница применимости второго индекса
Список чатов читается по `ix_chat_members_user_id_chat_id`: `Index Only Scan`, 1 001
строка из 3 105 — вместо перебора всей таблицы членства.
Здесь же измерена **граница**, а не только успех. Для пользователя, который состоит в
2 000 чатах из 3 105 (64 % таблицы), планировщик отказывается от индекса и делает
`Seq Scan` с `Rows Removed by Filter: 1105` — и это правильное решение: поднимать две
тысячи строк по индексу дороже, чем прочитать три тысячи подряд. Индекс рассчитан на
обычного пользователя, у которого чатов мало, и в этом сценарии он полезен; случай
«64 % таблицы» вынесен в отчёт как зафиксированная граница, а не спрятан. Если такие
пользователи станут нормой, лечится не индексом, а денормализацией (дублированием
`created_at` в `chat_members`, чтобы убрать `Sort`) — но это уже другая схема, и
менять её без данных о реальном распределении значило бы гадать.
### Измерение 3. Нагрузка: closed loop, 30 с, 4 и 16 потоков
Профиль: `tests/load.py` пишет сообщения в один чат; каждый поток ждёт ответа, прежде
чем отправить следующий (closed loop, без retry); длительность 30 с; прогрева нет;
повторов нет — числа одного прогона, а не среднее.
| Потоков | Успешных | Ошибок | RPS | p50 | p95 | p99 |
| --- | --- | --- | --- | --- | --- | --- |
| 4 | 6 282 | 0 | 208.9 | 16 мс | 32 мс | 47 мс |
| 16 | 4 933 | 0 | 162.5 | 93 мс | 172 мс | 234 мс |
CPU и память (сэмплы `docker stats` во время второго прогона): api 56 % → 93–102 %,
postgres 20–23 %, valkey меньше 2 %. Датасет после двух прогонов: 31 454 сообщения в
3 136 чатах, 349 пользователей, таблица `messages` 7 472 кБ.
Сырые числа и оговорки стенда — `evidence/09-load.txt`; JSON второго прогона, который
принимает `tests/load.py --output`, — `evidence/09-load-c16.json` (сессионных токенов
в нём нет).
Что из этого следует. Потоков стало вчетверо больше, а пропускная способность **упала**
на 22 %, задержка p99 выросла в 5 раз — стенд упёрся не в базу и не в квоту CPU:
у контейнера api лимит 2.0 ядра, а он занят примерно одним. Причина видна в коде:
приложение запущено одним процессом uvicorn (`workers=1`; там же объяснено, почему —
границы пула соединений заданы на процесс). Один процесс — один event loop — одно
ядро; семнадцатый одновременный запрос не получает параллелизма, он ждёт в очереди.
Что именно ест это ядро — сериализация SQLAlchemy, JSON или проверка сессии, — эти
замеры не показывают: нужен профиль, и это записано следующим шагом, а не выводом.
Ограничения измерения: клиент живёт на той же машине и вне контейнеров, поэтому его
собственные затраты в `docker stats` не видны, а время запроса включает и его;
closed loop занижает перцентили при насыщении (coordinated omission) и связывает RPS с
задержкой; датасет учебный, при десятках миллионов строк и запись, и индексы будут
вестись иначе.
### Таблица отказов
| Воздействие | Что ожидали | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| `docker compose stop valkey` | 503 `unavailable` < 2 с, `/health/live` 200, сессия возвращается | 1.016 / 1.000 / 1.031 / 1.000 с, все `unavailable`; ключ вернулся с TTL 3595 с, прежний токен принимается | поднят за 0.31 с; потерь нет (SIGTERM + AOF) |
| `docker compose stop postgres` | 503 < 2 с, данные целы | 1.500–1.516 с на всех маршрутах, включая вход; запись, сделанная до отказа, читается после | поднят за 0.83 с; потерь нет |
| `kill -9` процессу `valkey-server` внутри контейнера | контейнер поднимается сам, сессия возвращается | `RestartCount` 0 → 1, готов через 5.56 с; ключ `EXISTS 1`, TTL 3591 с | 5.56 с (из них около 5 с — период healthcheck); теоретическая потеря ≤1 с записей `everysec` на этом прогоне не выстрелила |
| `docker compose kill valkey` | — (проверяли, поднимется ли) | контейнер остался `exited`: политика `restart` не поднимает контейнер, убитый снаружи, — Docker считает это ручным действием | поднят оператором за 5.22 с; сессия на месте |
| `docker compose restart api postgres valkey` (`scripts/restart.sh`) | тот же токен читает те же данные | `PASS: persistence preserved confirmed data and existing session`; `StartedAt` сменился у всех трёх контейнеров | ~30 с вместе с проверкой; потерь нет |
| Повторный `alembic upgrade head` | ничего не меняет | «нет Running upgrade»; `alembic check` совпадает с моделями | — |
Отдельно про время ответа при отказе Valkey: в одном прогоне запрос получил 503 за
0.000 с (соединение к мёртвому процессу отвергается сразу), в другом — за 1.000 с
(клиент дождался таймаута сокета на уже установленном соединении). Оба значения внутри
бюджета, и оба означают одно: `CACHE_TIMEOUT_SECONDS=1` ограничивает ожидание сверху, а
не задаёт его. При остановленной PostgreSQL ответ занимает 1.5 с и упирается в
`DB_CONNECT_TIMEOUT_SECONDS`: за это время успевает истечь только подключение, но не
запрос. Стоит помнить, что 3.3 с внутри этого времени — вклад DNS Docker, а не базы: имя
остановленного контейнера перестаёт разрешаться, и запрос уходит вышестоящему
резолверу (измерено изнутри контейнера, доказательство 06).
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Что решение выдерживает (подтверждено измерением): остановку и падение Valkey,
остановку PostgreSQL, полный перезапуск всех трёх сервисов без удаления томов,
конкурентную регистрацию одного имени, откат неудачного создания чата, истечение и
отзыв сессий, обход истории в 10 000 сообщений с корректным курсором.
Чего решение **не** выдерживает или не делает:
- **Rate limiting отсутствует.** Пароль проверяется argon2id, и каждый вход стоит
процессорного времени; поток входов с одного адреса никем не ограничен. Для учебного
стенда на loopback это допустимо, для публичного — первое, что нужно добавить.
- **Кэша истории нет**, и это осознанно: кэш создал бы второй источник истины и вопрос
о read-after-write, который нечем проверить в этой лабораторной. Трек 5 как раз про
это, и мы его не заявляем.
- **Один процесс uvicorn.** Горизонтального масштабирования нет: вторая реплика — это
второй набор пулов и второй набор курсоров (курсоры, впрочем, не привязаны к
процессу, так как подписаны общим секретом). Масштабирование — задача лабораторной 3.
- **Потеря до ~1 секунды сессий** при гибели процесса с `appendfsync everysec`. Вариант
`always` убрал бы окно ценой заметно более медленной записи; для сессий это плохой
размен, и он не сделан осознанно. Что именно теряется — только что выданные сессии;
данные в PostgreSQL не затронуты.
- **Нет snapshot-изоляции между страницами** истории: строка, зафиксированная позади
курсора во время обхода, может не попасть в этот обход. Дубликатов при этом не
возникает. Полноценное решение — материализованный снимок или версионирование.
- **`GETDEL` не защищает от гонки logout с параллельным запросом**: запрос, начатый до
отзыва, успеет завершиться. Для мессенджера это нормальное поведение (отзыв не
мгновенный), но его стоит назвать.
- **Курсоры не имеют срока жизни**: подписанный курсор остаётся валидным, пока жив
секрет. Протухший курсор просто вернёт пустую страницу — это безопасно, но
неинформативно.
- **Идентификатор пользователя не секрет**: `user_id` виден в ответах, а UUID — не
средство авторизации. Доступ проверяется членством в чате, а не знанием идентификатора.
Подтверждено измерением: индекс истории и его ценность, граница применимости второго
индекса, бюджет таймаутов и поведение при отказах, долговечность AOF при остановке и
падении, потолок пропускной способности одного процесса. **Гипотеза, требующая
отдельного замера:** что именно ограничивает пропускную способность (профиль
процессора) и где предел при горизонтальном масштабировании — это предмет следующих
работ, а не вывод этой.
## Источники и ИИ
- **Контракт и семантика:** `contracts/openapi.json`, `contracts/README.md`,
`contracts/infrastructure.json`, `COURSE.md`, `README.md` — единственный источник
требований. Контракт и публичные проверки не изменялись и не подгонялись под решение.
- **Библиотеки:** FastAPI 0.141.1, uvicorn 0.53.0, SQLAlchemy 2.0.44 (async), asyncpg
0.30.0, Alembic 1.16.5, redis-py 6.4.0 (клиент Valkey), argon2-cffi 25.1.0; полный
список с точными версиями — в `requirements.txt`, отдельно `requirements-dev.txt` для
полной проверки OpenAPI. Стандартная библиотека: `asyncio`, `hmac`, `hashlib`,
`secrets`, `logging`, `dataclasses`, `uuid`, `datetime`, `unittest`.
- **Первичные материалы:** [PostgreSQL: EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html),
[PostgreSQL: transactions](https://www.postgresql.org/docs/current/tutorial-transactions.html),
[Valkey: persistence](https://valkey.io/topics/persistence/),
[Basic authentication](https://www.rfc-editor.org/info/rfc7617/),
[Dockerfile reference](https://docs.docker.com/reference/dockerfile/).
- **Помощь ИИ:** реализация написана с использованием Claude Code (Anthropic):
генерация кода по моей постановке, разбор контракта, подготовка проверок и этого
отчёта. Измерения выполнены на моём стенде и воспроизводимы командами из отчёта;
там, где эксперимент дал неожиданный результат (например, `docker compose kill` не
поднимается политикой `restart`), в отчёте осталось наблюдение, а не ожидание.
+38
View File
@@ -0,0 +1,38 @@
# Конфигурация Alembic. URL базы здесь намеренно не задан: он приходит из
# окружения (DATABASE_URL или DATABASE_URL_FILE) и подставляется migrations/env.py.
[alembic]
script_location = migrations
prepend_sys_path = src
[loggers]
keys = root,sqlalchemy,alembic
[handlers]
keys = console
[formatters]
keys = plain
[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 = plain
[formatter_plain]
format = %(levelname)s [%(name)s] %(message)s
+158
View File
@@ -0,0 +1,158 @@
# Стенд лабораторной 2: api + postgres + valkey + одноразовая миграция.
#
# Секреты передаются файлами (docker secrets в /run/secrets/*), поэтому вывод
# `docker compose config` содержит только пути и пригоден для evidence.
# Версии базовых образов закреплены по digest, а не только по тегу.
# PostgreSQL и Valkey наружу не публикуются: они видны только внутри сети backend.
x-api-environment: &api-environment
APP_ENV: lab
APP_HOST: 0.0.0.0
APP_PORT: "8080"
LOG_LEVEL: info
SESSION_STORE: redis
SESSION_TTL_SECONDS: "${SESSION_TTL_SECONDS:-3600}"
DB_POOL_SIZE: "5"
DB_MAX_OVERFLOW: "5"
DB_POOL_TIMEOUT_SECONDS: "2"
DB_CONNECT_TIMEOUT_SECONDS: "1.5"
DB_COMMAND_TIMEOUT_SECONDS: "2.5"
DB_STATEMENT_TIMEOUT_MS: "2000"
CACHE_TIMEOUT_SECONDS: "1"
GRACEFUL_SHUTDOWN_SECONDS: "5"
SHUTDOWN_DRAIN_SECONDS: "0"
services:
postgres:
image: postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4
restart: unless-stopped
environment:
POSTGRES_USER: messenger
POSTGRES_DB: messenger
# Пароль приходит файлом: в `docker compose config` он не печатается.
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
POSTGRES_INITDB_ARGS: "--auth-host=scram-sha-256"
secrets:
- postgres_password
volumes:
- pgdata:/var/lib/postgresql/data
networks:
- backend
healthcheck:
test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"]
interval: 5s
timeout: 3s
retries: 12
start_period: 10s
deploy:
resources:
limits:
cpus: "2.0"
memory: 512M
valkey:
image: valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab
restart: unless-stopped
# AOF с fsync раз в секунду: сессии переживают рестарт, TTL хранится
# абсолютным временем и от перезапуска не продлевается. RDB отключён,
# чтобы механизм долговечности был ровно один и его было видно в evidence.
command:
- valkey-server
- --appendonly
- "yes"
- --appendfsync
- everysec
- --save
- ""
volumes:
- valkeydata:/data
networks:
- backend
healthcheck:
test: ["CMD", "valkey-cli", "ping"]
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
deploy:
resources:
limits:
cpus: "1.0"
memory: 256M
migrate:
build:
context: .
dockerfile: Dockerfile
image: mtusi-messenger-lab2:2.0.0
# Одноразовая роль того же образа: схема приводится к head и контейнер выходит.
command: ["alembic", "upgrade", "head"]
restart: "no"
environment:
# Миграциям нужен только URL базы: Valkey и настройки сессий ни при чём.
DATABASE_URL_FILE: /run/secrets/database_url
secrets:
- database_url
depends_on:
postgres:
condition: service_healthy
networks:
- backend
api:
build:
context: .
dockerfile: Dockerfile
image: mtusi-messenger-lab2:2.0.0
restart: unless-stopped
environment:
<<: *api-environment
DATABASE_URL_FILE: /run/secrets/database_url
CACHE_URL_FILE: /run/secrets/cache_url
CURSOR_SECRET_FILE: /run/secrets/cursor_secret
secrets:
- database_url
- cache_url
- cursor_secret
ports:
# Наружу публикуется только API и только на loopback: тесты идут с хоста.
- "127.0.0.1:${APP_PORT:-8080}:8080"
depends_on:
postgres:
condition: service_healthy
valkey:
condition: service_healthy
migrate:
condition: service_completed_successfully
networks:
- backend
healthcheck:
test: ["CMD", "python", "-m", "messenger.healthcheck"]
interval: 10s
timeout: 3s
start_period: 5s
retries: 3
deploy:
resources:
limits:
cpus: "2.0"
memory: 512M
secrets:
database_url:
file: ./secrets/database_url
cache_url:
file: ./secrets/cache_url
postgres_password:
file: ./secrets/postgres_password
cursor_secret:
file: ./secrets/cursor_secret
volumes:
# Именованные тома: `docker compose down` данные не удаляет.
pgdata:
valkeydata:
networks:
backend:
driver: bridge
+35
View File
@@ -0,0 +1,35 @@
== 01: офлайн-проверка контракта, публичный сценарий, пробы живости ==
host: Windows 10 Pro 19045, Git Bash; make работает через sh (MSYS)
date: 2026-10-11T14:21:40Z (UTC)
Что показывает: структура репозитория и контракт проверены офлайн (`make check`),
публичный сценарий API пройден (`make test`), обе пробы здоровья отвечают 200 —
и это ещё ничего не говорит о качестве решения, только о том, что стенд живой.
Глубина проверок уровня 4 — в доказательствах 03-08, описание стенда — в 10.
$ make check
python3 scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ make test BASE_URL=http://localhost:8080
python3 tests/smoke.py --base-url "http://localhost:8080"
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
$ curl -si http://localhost:8080/health/live
HTTP/1.1 200 OK
content-length: 15
content-type: application/json
x-request-id: d716aed826ff4424aafe386732507506
{"status":"ok"}
$ curl -si http://localhost:8080/health/ready
HTTP/1.1 200 OK
content-length: 15
content-type: application/json
x-request-id: c50a844c78bb42a0b5870b71170ec839
{"status":"ok"}
$ docker compose ps --format '{{.Service}} | {{.Image}} | {{.Status}}'
api | mtusi-messenger-lab2:2.0.0 | Up About a minute (healthy)
postgres | postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 | Up About a minute (healthy)
valkey | valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab | Up About a minute (healthy)
+57
View File
@@ -0,0 +1,57 @@
== 02: сохранность данных при явном перезапуске api + postgres + valkey ==
date: 2026-10-11T14:23:30Z (UTC)
Хук: scripts/restart.cmd — двойник scripts/restart.sh для Windows: те же вызовы
docker compose и те же гарантии (тома не удаляются, данные не сбрасываются, засев
не повторяется).
Почему двойник: tests/resilience.py запускает хук через Popen([script]) без оболочки,
а Windows через CreateProcess исполняет только .exe/.cmd/.bat; .sh падает с WinError 193.
WSL на этой машине оказался недоступен (Wsl/Service/CreateInstance/CreateVm/HCS/
ERROR_NO_SYSTEM_RESOURCES), поэтому записанный прогон сделан через .cmd. Ниже проверены
оба хука.
$ docker inspect -f '{{.Name}} {{.State.StartedAt}}' api postgres valkey # BEFORE
/mtusi2026lab2-api-1 2026-10-11T14:23:19.3827432Z
/mtusi2026lab2-postgres-1 2026-10-11T14:23:18.9549031Z
/mtusi2026lab2-valkey-1 2026-10-11T14:23:18.9330739Z
$ make test-persistence ACTION_SCRIPT=scripts/restart.cmd
python3 tests/resilience.py --mode persistence --action-script "scripts/restart.cmd" --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.
make exit code: 0
$ docker inspect -f '{{.Name}} {{.State.StartedAt}}' api postgres valkey # AFTER
/mtusi2026lab2-api-1 2026-10-11T14:23:52.4305544Z
/mtusi2026lab2-postgres-1 2026-10-11T14:23:52.1114406Z
/mtusi2026lab2-valkey-1 2026-10-11T14:23:52.0904113Z
StartedAt сменился у всех трёх контейнеров: хук действительно перезапустил стенд. Сам тест
этого показать не может — он об этом и пишет в своей последней строке, — поэтому проверка
внесена сюда.
-- POSIX-хук, запущенный из POSIX-оболочки: sh scripts/restart.sh --
=== services before restart ===
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
mtusi2026lab2-api-1 mtusi-messenger-lab2:2.0.0 "python -m messenger" api 16 minutes ago Up 7 seconds (healthy) 127.0.0.1:8080->8080/tcp
mtusi2026lab2-postgres-1 postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 "docker-entrypoint.s…" postgres 16 minutes ago Up 7 seconds (healthy) 5432/tcp
mtusi2026lab2-valkey-1 valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab "tini -- docker-entr…" valkey 16 minutes ago Up 7 seconds (healthy) 6379/tcp
=== restart api postgres valkey (grace 10s) ===
Container mtusi2026lab2-postgres-1 Restarting
Container mtusi2026lab2-api-1 Restarting
Container mtusi2026lab2-valkey-1 Restarting
Container mtusi2026lab2-postgres-1 Started
Container mtusi2026lab2-valkey-1 Started
Container mtusi2026lab2-api-1 Started
=== services after restart ===
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
mtusi2026lab2-api-1 mtusi-messenger-lab2:2.0.0 "python -m messenger" api 16 minutes ago Up Less than a second (health: starting) 127.0.0.1:8080->8080/tcp
mtusi2026lab2-postgres-1 postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 "docker-entrypoint.s…" postgres 16 minutes ago Up Less than a second (health: starting) 5432/tcp
mtusi2026lab2-valkey-1 valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab "tini -- docker-entr…" valkey 16 minutes ago Up Less than a second (health: starting) 6379/tcp
running services: api postgres valkey
restart complete
restart.sh exit code: 0
$ docker compose ps --format '{{.Service}} | {{.Status}}'
api | Up Less than a second (health: starting)
postgres | Up 1 second (health: starting)
valkey | Up 1 second (health: starting)
+133
View File
@@ -0,0 +1,133 @@
== 03: собственные проверки (student-tests) ==
date: 2026-10-23T19:19:36Z (UTC)
host: Windows 10 Pro 19045, Git Bash (MSYS), python3 3.11.9; стенд поднят docker compose
Что показывает: проверки поверх публичного контракта — пароли и границы их длины,
сессии и их отзыв, доступ к чужим чатам, атомарность создания чата, гонка регистрации,
пагинация, валидация и живучесть при недоступной зависимости. Три проверки
отказоустойчивости пропущены: они останавливают контейнеры и запускаются отдельно
с ALLOW_OUTAGE=1 (доказательства 05 и 06).
Адрес стенда — 127.0.0.1, а не localhost: на Windows имя localhost разрешается сначала
в ::1, и обращение к опубликованному порту 127.0.0.1:8080 добавляло бы около двух секунд
на запрос. Стенд публикует только loopback, так что это тот же самый адрес.
PYTHON="python3 -X utf8" передан аргументом make: этой сборке make переменные
окружения не передаются, а вывод тестов на русском в консоли Windows иначе
попал бы в файл в кодировке cp1251.
$ make student-test BASE_URL=http://127.0.0.1:8080 PYTHON="python3 -X utf8"
python3 -X utf8 student-tests/run_all.py --base-url "http://127.0.0.1:8080"
BASE_URL = http://127.0.0.1:8080
test_a_foreign_chat_and_a_missing_chat_are_reported_alike (test_access.ChatVisibility.test_a_foreign_chat_and_a_missing_chat_are_reported_alike)
Тот же статус, тот же код, то же сообщение: разница не должна утекать. ... ok
test_a_left_member_still_sees_the_history (test_access.ChatVisibility.test_a_left_member_still_sees_the_history)
Участие фиксируется при создании, поэтому история участника не исчезает. ... ok
test_members_read_the_chat (test_access.ChatVisibility.test_members_read_the_chat) ... ok
test_outsider_cannot_write (test_access.ChatVisibility.test_outsider_cannot_write) ... ok
test_outsider_does_not_see_the_chat_in_the_list (test_access.ChatVisibility.test_outsider_does_not_see_the_chat_in_the_list) ... ok
test_outsider_gets_not_found (test_access.ChatVisibility.test_outsider_gets_not_found) ... ok
test_x_user_id_does_not_open_a_foreign_chat (test_access.ChatVisibility.test_x_user_id_does_not_open_a_foreign_chat) ... ok
test_each_session_sees_its_own_user (test_access.CurrentUser.test_each_session_sees_its_own_user) ... ok
test_registration_body_is_never_echoed (test_access.CurrentUser.test_registration_body_is_never_echoed) ... ok
test_basic_is_accepted_on_the_session_route (test_auth.Credentials.test_basic_is_accepted_on_the_session_route) ... ok
test_basic_is_rejected_on_business_routes (test_auth.Credentials.test_basic_is_rejected_on_business_routes)
Учётные данные Basic не должны открывать /users/me: челлендж должен требовать Bearer. ... ok
test_bearer_is_rejected_on_the_session_route (test_auth.Credentials.test_bearer_is_rejected_on_the_session_route)
Маршрут входа принимает только Basic; сессионный токен не создаёт сессию. ... ok
test_malformed_authorization_headers (test_auth.Credentials.test_malformed_authorization_headers) ... ok
test_token_is_opaque_and_unique (test_auth.Credentials.test_token_is_opaque_and_unique) ... ok
test_unknown_user_and_wrong_password_are_indistinguishable (test_auth.Credentials.test_unknown_user_and_wrong_password_are_indistinguishable)
Тот же статус, тот же код, то же сообщение — и сопоставимый объём работы. ... ok
test_x_user_id_cannot_authenticate_or_impersonate (test_auth.Credentials.test_x_user_id_cannot_authenticate_or_impersonate)
Заголовок из лабораторной 1 не работает: не даёт доступа и не переопределяет сессию. ... ok
test_accepted_passwords_work_for_login (test_auth.Registration.test_accepted_passwords_work_for_login) ... ok
test_duplicate_username_conflicts (test_auth.Registration.test_duplicate_username_conflicts) ... ok
test_multibyte_password_far_beyond_72_bytes (test_auth.Registration.test_multibyte_password_far_beyond_72_bytes)
128 кириллических кодовых точек — это 256 байт UTF-8, и они проходят без потерь. ... ok
test_password_is_checked_to_the_last_byte (test_auth.Registration.test_password_is_checked_to_the_last_byte)
Пароль длиннее 72 байт не усекается KDF. ... ok
test_password_is_required (test_auth.Registration.test_password_is_required) ... ok
test_password_length_bounds (test_auth.Registration.test_password_length_bounds)
11 и 129 кодовых точек отклоняются; 12 и 128 принимаются. ... ok
test_password_may_contain_a_colon (test_auth.Registration.test_password_may_contain_a_colon)
Basic разделяет только по первому двоеточию, остальное принадлежит паролю. ... ok
test_surrounding_spaces_are_part_of_the_password (test_auth.Registration.test_surrounding_spaces_are_part_of_the_password)
Пароль не обрезается: пробелы по краям значат то же, что и любые другие символы. ... ok
test_whitespace_only_password_is_refused (test_auth.Registration.test_whitespace_only_password_is_refused)
Двенадцать пробелов — пустое значение обязательного поля, а не пароль. ... ok
test_a_valid_chat_is_created_whole (test_chat_atomicity.ChatCreation.test_a_valid_chat_is_created_whole) ... ok
test_creator_must_be_a_member (test_chat_atomicity.ChatCreation.test_creator_must_be_a_member) ... ok
test_duplicate_members_are_refused (test_chat_atomicity.ChatCreation.test_duplicate_members_are_refused) ... ok
test_empty_and_oversized_member_lists_are_refused (test_chat_atomicity.ChatCreation.test_empty_and_oversized_member_lists_are_refused) ... ok
test_one_unknown_member_among_known_ones_still_rolls_back (test_chat_atomicity.ChatCreation.test_one_unknown_member_among_known_ones_still_rolls_back) ... ok
test_unknown_member_is_refused_without_a_trace (test_chat_atomicity.ChatCreation.test_unknown_member_is_refused_without_a_trace) ... ok
test_liveness_stays_green_throughout (test_dependency_outage.DependencyOutage.test_liveness_stays_green_throughout)
Отказ зависимости не должен выглядеть для супервизора смертью процесса. ... skipped 'задайте ALLOW_OUTAGE=1 для запуска: этот модуль останавливает контейнеры'
test_postgres_outage (test_dependency_outage.DependencyOutage.test_postgres_outage) ... skipped 'задайте ALLOW_OUTAGE=1 для запуска: этот модуль останавливает контейнеры'
test_valkey_outage (test_dependency_outage.DependencyOutage.test_valkey_outage) ... skipped 'задайте ALLOW_OUTAGE=1 для запуска: этот модуль останавливает контейнеры'
api пересоздан с SESSION_TTL_SECONDS=3, готов через 3.73s
test_a_token_issued_before_the_change_still_works (test_expiry.ShortLivedSessions.test_a_token_issued_before_the_change_still_works)
Пересоздание API не выдаёт новые сессии и не продлевает старые. ... у токена, выданного до переключения, осталось 3596s из исходных 3600s
ok
test_a_token_stops_working_once_the_ttl_passes (test_expiry.ShortLivedSessions.test_a_token_stops_working_once_the_ttl_passes) ... через 4s токен отвергается обоими маршрутами, а его ключ исчез
ok
test_expiry_does_not_need_a_cleanup_job (test_expiry.ShortLivedSessions.test_expiry_does_not_need_a_cleanup_job)
Хранилище никто не чистит: ключа просто больше нет. ... ключ исчез сам между двумя запросами: приложение не удаляет просроченные сессии
ok
test_the_short_ttl_is_the_one_in_force (test_expiry.ShortLivedSessions.test_the_short_ttl_is_the_one_in_force) ... expires_at через 3.00s, ключ в Valkey живёт 3s: сроком владеет хранилище, а не процесс
ok
api пересоздан с SESSION_TTL_SECONDS=3600, готов через 3.78s
test_error_envelope_carries_a_request_id (test_health.Probes.test_error_envelope_carries_a_request_id) ... ok
test_every_probe_gets_its_own_request_id (test_health.Probes.test_every_probe_gets_its_own_request_id) ... ok
test_liveness (test_health.Probes.test_liveness) ... ok
test_probes_need_no_credentials (test_health.Probes.test_probes_need_no_credentials) ... ok
test_readiness (test_health.Probes.test_readiness) ... ok
test_readiness_is_not_a_cached_constant (test_health.Probes.test_readiness_is_not_a_cached_constant)
Повторные пробы должен обслуживать процесс, а не кешированное тело. ... ok
test_a_cursor_from_one_user_is_refused_for_another (test_pagination.ChatList.test_a_cursor_from_one_user_is_refused_for_another) ... ok
test_chat_pages_cover_the_list_exactly_once (test_pagination.ChatList.test_chat_pages_cover_the_list_exactly_once) ... ok
test_a_cursor_from_another_chat_is_refused (test_pagination.MessageHistory.test_a_cursor_from_another_chat_is_refused) ... ok
test_a_cursor_from_another_user_is_refused (test_pagination.MessageHistory.test_a_cursor_from_another_user_is_refused) ... ok
test_a_cursor_from_the_chat_list_is_refused_here (test_pagination.MessageHistory.test_a_cursor_from_the_chat_list_is_refused_here) ... ok
test_items_are_ordered_by_created_at_then_id (test_pagination.MessageHistory.test_items_are_ordered_by_created_at_then_id) ... ok
test_pages_cover_the_history_exactly_once (test_pagination.MessageHistory.test_pages_cover_the_history_exactly_once) ... ok
test_small_pages_agree_with_a_single_large_one (test_pagination.MessageHistory.test_small_pages_agree_with_a_single_large_one) ... ok
test_the_second_page_starts_right_after_the_first (test_pagination.MessageHistory.test_the_second_page_starts_right_after_the_first) ... ok
test_database_holds_exactly_one_row (test_registration_race.RegistrationRace.test_database_holds_exactly_one_row) ... ok
test_every_loser_gets_the_conflict_envelope (test_registration_race.RegistrationRace.test_every_loser_gets_the_conflict_envelope) ... ok
test_only_one_registration_wins (test_registration_race.RegistrationRace.test_only_one_registration_wins) ... ok
test_vanishing_key_means_unauthorized (test_sessions.ExpiryIsEnforcedByTheStore.test_vanishing_key_means_unauthorized) ... ok
test_logout_returns_an_empty_204_and_then_401 (test_sessions.Lifecycle.test_logout_returns_an_empty_204_and_then_401) ... ok
test_missing_and_unknown_tokens (test_sessions.Lifecycle.test_missing_and_unknown_tokens) ... ok
test_revocation_closes_every_route (test_sessions.Lifecycle.test_revocation_closes_every_route) ... ok
test_session_matches_the_contract (test_sessions.Lifecycle.test_session_matches_the_contract) ... ok
test_session_survives_an_api_process_restart (test_sessions.Lifecycle.test_session_survives_an_api_process_restart)
Сессии не в памяти процесса: перезапуск только API их сохраняет. ... ok
test_two_sessions_are_independent (test_sessions.Lifecycle.test_two_sessions_are_independent) ... ok
test_revocation_removes_the_key (test_sessions.Storage.test_revocation_removes_the_key) ... ok
test_token_entropy (test_sessions.Storage.test_token_entropy)
16 входов подряд должны дать 16 разных токенов: повтор ломал бы отзыв. ... ok
test_token_is_not_stored_verbatim (test_sessions.Storage.test_token_is_not_stored_verbatim) ... ok
test_empty_cursor_is_refused (test_validation.QueryParameters.test_empty_cursor_is_refused) ... ok
test_invalid_chat_id (test_validation.QueryParameters.test_invalid_chat_id) ... ok
test_limit_bounds (test_validation.QueryParameters.test_limit_bounds) ... ok
test_non_numeric_limit (test_validation.QueryParameters.test_non_numeric_limit) ... ok
test_tampered_cursor_is_refused (test_validation.QueryParameters.test_tampered_cursor_is_refused) ... ok
test_broken_json_is_refused_without_echoing_it (test_validation.RequestBodies.test_broken_json_is_refused_without_echoing_it) ... ok
test_display_name_and_title_limits (test_validation.RequestBodies.test_display_name_and_title_limits) ... ok
test_message_text_limits (test_validation.RequestBodies.test_message_text_limits) ... ok
test_missing_required_fields (test_validation.RequestBodies.test_missing_required_fields) ... ok
test_nul_is_refused_before_it_reaches_the_store (test_validation.RequestBodies.test_nul_is_refused_before_it_reaches_the_store)
U+0000 не хранится в `text`: это 400, а не ложная недоступность базы. ... ok
test_sender_id_cannot_be_injected (test_validation.RequestBodies.test_sender_id_cannot_be_injected) ... ok
test_the_password_never_appears_in_an_error (test_validation.RequestBodies.test_the_password_never_appears_in_an_error) ... ok
test_unknown_json_field_is_refused (test_validation.RequestBodies.test_unknown_json_field_is_refused) ... ok
test_username_pattern (test_validation.RequestBodies.test_username_pattern) ... ok
test_unknown_route (test_validation.Routing.test_unknown_route) ... ok
test_wrong_method (test_validation.Routing.test_wrong_method) ... ok
----------------------------------------------------------------------
Ran 82 tests in 30.188s
OK (skipped=3)
+42
View File
@@ -0,0 +1,42 @@
== 04: истечение срока сессии при коротком TTL ==
date: 2026-10-11T19:28:09Z (UTC)
Что показывает: срок сессии задаёт хранилище, а не процесс приложения. Модуль
пересоздаёт сервис api с SESSION_TTL_SECONDS=3, поэтому ждать час не нужно: токен,
выданный после переключения, перестаёт работать через три секунды, а его ключ
в Valkey исчезает сам — никакой задачи очистки в приложении нет. Токен, выданный
до переключения, продолжает работать, и срок у него остаётся прежним: пересоздание
контейнера сессий не создаёт и не продлевает — они лежат в Valkey, а не в процессе.
Почему это ещё и проверка хранилища: живи сессии в процессе, токен, выданный до
пересоздания api, перестал бы приниматься. Ниже видно обратное, а остаток срока
у него близок к исходному часу, а не равен ему заново — сессию не выдавали повторно.
$ docker compose ps --format '{{.Service}} | {{.Image}} | {{.Status}}'
api | mtusi-messenger-lab2:2.0.0 | Up 12 seconds (healthy)
postgres | postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 | Up About a minute (healthy)
valkey | valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab | Up About a minute (healthy)
$ BASE_URL=http://127.0.0.1:8080 python3 -u -X utf8 -m unittest discover -s student-tests -t student-tests -p 'test_expiry.py' -v
api пересоздан с SESSION_TTL_SECONDS=3, готов через 3.70s
test_a_token_issued_before_the_change_still_works (test_expiry.ShortLivedSessions.test_a_token_issued_before_the_change_still_works)
Пересоздание API не выдаёт новые сессии и не продлевает старые. ... у токена, выданного до переключения, осталось 3596s из исходных 3600s
ok
test_a_token_stops_working_once_the_ttl_passes (test_expiry.ShortLivedSessions.test_a_token_stops_working_once_the_ttl_passes) ... через 4s токен отвергается обоими маршрутами, а его ключ исчез
ok
test_expiry_does_not_need_a_cleanup_job (test_expiry.ShortLivedSessions.test_expiry_does_not_need_a_cleanup_job)
Хранилище никто не чистит: ключа просто больше нет. ... ключ исчез сам между двумя запросами: приложение не удаляет просроченные сессии
ok
test_the_short_ttl_is_the_one_in_force (test_expiry.ShortLivedSessions.test_the_short_ttl_is_the_one_in_force) ... expires_at через 3.00s, ключ в Valkey живёт 3s: сроком владеет хранилище, а не процесс
ok
api пересоздан с SESSION_TTL_SECONDS=3600, готов через 3.69s
----------------------------------------------------------------------
Ran 4 tests in 17.586s
OK
$ docker compose ps --format '{{.Service}} | {{.Image}} | {{.Status}}' # сервис возвращён на место самим тестом
api | mtusi-messenger-lab2:2.0.0 | Up 1 second (health: starting)
postgres | postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 | Up About a minute (healthy)
valkey | valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab | Up About a minute (healthy)
+105
View File
@@ -0,0 +1,105 @@
== 05: недоступность зависимости — Valkey остановлен ==
date: 2026-10-11T19:28:38Z (UTC)
Что показывает: пока хранилища сессий нет, каждый маршрут, которому оно нужно,
отвечает 503 unavailable — не 401 и не 200 — и отвечает быстрее секунды. /health/live
остаётся 200, чтобы супервизор не перезапускал живой процесс, а /health/ready
переключается в 503, чтобы балансировщик снял узел с трафика. Сама сессия не теряется:
Valkey возвращается с теми же ключами, и прежний токен по-прежнему принимается.
Почему это важно именно так: клиент, который на 401 повторно входит в систему,
на отказе зависимости выбросил бы рабочую сессию. Поэтому недоступность хранилища
обязана выглядеть как 503, а не как «ваш токен недействителен».
Почему быстро: хранилище адресуется с socket_timeout = socket_connect_timeout =
CACHE_TIMEOUT_SECONDS = 1 с — это и есть секунда в замерах ниже. Без этого предела
запрос висел бы до отказа клиента (tests/client.py ждёт 10 с).
Сессия переживает перезапуск, потому что журнал AOF включён: ключ возвращается
вместе со своим сроком, а не выдаётся заново.
$ docker compose ps --format '{{.Service}} | {{.Image}} | {{.Status}}'
api | mtusi-messenger-lab2:2.0.0 | Up 12 seconds (healthy)
postgres | postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 | Up 2 minutes (healthy)
valkey | valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab | Up 2 minutes (healthy)
$ BASE_URL=http://127.0.0.1:8080 ALLOW_OUTAGE=1 python3 -u -X utf8 -m unittest discover -s student-tests -t student-tests -p 'test_dependency_outage.py' -k test_valkey_outage -v
test_valkey_outage (test_dependency_outage.DependencyOutage.test_valkey_outage) ... GET /api/v1/users/me 1.016s unavailable
GET /api/v1/chats 1.000s unavailable
GET /health/ready 1.031s unavailable
DELETE /api/v1/auth/sessions/current 1.000s unavailable
valkey снова поднят и готов через 0.31s
messenger:session:0c111bba36a52b4b81cf61a03c855f5bee9f89a09ff2c52647c3453b0b9b01ae переживает перезапуск с TTL 3595 с (AOF), тот же токен всё ещё принимается
ok
----------------------------------------------------------------------
Ran 1 test in 5.364s
OK
$ docker compose ps --format '{{.Service}} | {{.Image}} | {{.Status}}' # контейнер возвращён на место самим тестом
api | mtusi-messenger-lab2:2.0.0 | Up 18 seconds (healthy)
postgres | postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 | Up 2 minutes (healthy)
valkey | valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab | Up Less than a second (health: starting)
== 5б: не остановка, а падение — два разных отказа ==
Остановка контейнера — вежливый сценарий: Valkey получает SIGTERM и успевает дописать
журнал. Ниже два грубых: гибель самого процесса valkey-server (так выглядит OOM или
падение в библиотеке) и `docker compose kill` снаружи. Разница между ними оказалась
не косметической: упавший процесс политика restart поднимает, а убитый снаружи
контейнер — нет. Скрипт измеряет окно потери около секунды при appendfsync everysec
и заодно проверяет то, что обязано работать всегда: 503 вместо 401 и ответ в бюджет.
$ BASE_URL=http://127.0.0.1:8080 python3 -u -X utf8 student-tests/valkey_crash.py
========================================================================
Подготовка: две сессии разного возраста
========================================================================
сессия старшая создана, ключ messenger:session:05ae707f47b7c612…
прошло 2.0s — журнал успел сбросить её на диск
сессия младшая создана прямо перед падением, ключ messenger:session:0537c06dfc4bb9f1…
[OK] обе сессии работают до падения
ключей в Valkey до падения: 116, перезапусков контейнера: 0
========================================================================
Отказ 1: гибнет сам процесс valkey-server
========================================================================
$ docker compose exec -T valkey sh -c '<найти valkey-server и kill -9>'
убиваю 7: valkey-server *:6379
[OK] процесс убит сигналом SIGKILL
GET /api/v1/users/me 0.000s unavailable
[OK] во время отказа бизнес-маршрут отвечает 503, а не 401
[OK] ответ не ждёт восстановления зависимости — 0.000s при бюджете 2.0s
[OK] контейнер поднялся сам по политике restart: unless-stopped — готов через 5.56s
RestartCount: 0 → 1, состояние running
старший ключ: EXISTS 1, TTL 3591
[OK] сессия старше секунды пережила падение процесса — тот же токен снова принимается, TTL не продлён
[--] сессия, созданная за доли секунды до SIGKILL, тоже уцелела:
сброс журнала успел пройти — на этом прогоне окно потери не выстрелило
========================================================================
Отказ 2: контейнер убивают снаружи — docker compose kill
========================================================================
$ docker compose kill valkey # код 0
состояние контейнера через секунду: exited
GET /api/v1/users/me 1.000s unavailable
[OK] во время отказа бизнес-маршрут отвечает 503, а не 401
[OK] ответ не ждёт восстановления зависимости — 1.000s при бюджете 2.0s
[OK] политика restart не поднимает контейнер, убитый снаружи — состояние exited, RestartCount 1
Так и должно быть: `docker kill` — ручное действие, и Docker отличает его от
падения процесса. Хранилище поднимает оператор, а не политика.
$ docker compose start valkey
[OK] после ручного старта стенд снова готов — через 5.22s
[OK] сессия пережила и это: журнал AOF пишется независимо от того, как именно умер процесс
ключей в Valkey после двух отказов: 116 (до них было 116)
========================================================================
Итог
========================================================================
успешно: 11
РЕЗУЛЬТАТ: PASS
код возврата: 0
+71
View File
@@ -0,0 +1,71 @@
== 06: недоступность зависимости — PostgreSQL остановлен ==
date: 2026-10-11T19:31:32Z (UTC)
Что показывает: пока базы нет, каждый маршрут, который в неё читает или пишет,
отвечает 503 unavailable (и никогда 401: клиент, реагирующий на 401 повторным входом,
выбросил бы исправную сессию), /health/live остаётся 200, /health/ready переключается
в 503, а история, записанная до отказа, после него читается.
Откуда берётся время. Остановка контейнера убирает имя postgres из сети, а встроенный
DNS Docker на неизвестное односоставное имя не отвечает «не найдено» — он передаёт
запрос вышестоящему серверу и ждёт. Замер внутри контейнера api при остановленной базе:
$ docker compose ps --format '{{.Service}} | {{.Image}} | {{.Status}}'
api | mtusi-messenger-lab2:2.0.0 | Up 3 minutes (healthy)
postgres | postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 | Up 19 seconds (healthy)
valkey | valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab | Up 2 minutes (healthy)
$ docker compose stop postgres
Container mtusi2026lab2-postgres-1 Stopping
Container mtusi2026lab2-postgres-1 Stopped
$ MSYS_NO_PATHCONV=1 docker compose exec -T api python - < probe.py
getaddrinfo valkey 0.002s resolved
getaddrinfo postgres 3.290s gaierror: [Errno -2] Name or service not known
getaddrinfo postgres 3.294s gaierror: [Errno -2] Name or service not known
asyncpg.connect(postgres, timeout=1.5) 1.503s TimeoutError
asyncpg.connect(postgres, timeout=5.0) 3.300s gaierror
$ docker compose start postgres
Container mtusi2026lab2-postgres-1 Starting
Container mtusi2026lab2-postgres-1 Started
То есть 3,3 с — это DNS, а не PostgreSQL и не драйвер: живое имя разрешается
за 2 мс, а остановленное ждёт ответа вышестоящего сервера. Предел этому ставит
собственный таймаут подключения asyncpg, поэтому API отвечает за 1,5 с.
Бюджет отказов: DB_CONNECT_TIMEOUT_SECONDS=1.5, DB_COMMAND_TIMEOUT_SECONDS=2.5,
DB_STATEMENT_TIMEOUT_MS=2000, DB_POOL_TIMEOUT_SECONDS=2. Серверный предел строже
клиентского, поэтому медленный запрос снимает PostgreSQL, а не драйвер, и в ответе
остаётся причина, а не факт обрыва связи.
Отдельный таймаут на подключение нужен именно поэтому: 3,3 с ожидания DNS
в бюджет не помещаются, а один общий таймаут на запрос их бы пропустил.
$ curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8080/health/ready
200
$ docker compose ps --format '{{.Service}} | {{.Image}} | {{.Status}}'
api | mtusi-messenger-lab2:2.0.0 | Up 3 minutes (healthy)
postgres | postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 | Up Less than a second (health: starting)
valkey | valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab | Up 3 minutes (healthy)
$ BASE_URL=http://127.0.0.1:8080 ALLOW_OUTAGE=1 python3 -u -X utf8 -m unittest discover -s student-tests -t student-tests -p 'test_dependency_outage.py' -k test_postgres_outage -v
test_postgres_outage (test_dependency_outage.DependencyOutage.test_postgres_outage) ... GET /api/v1/users/me 1.516s unavailable
GET /api/v1/chats 1.516s unavailable
GET /api/v1/chats/c0ab6bd6-a215-41c3-b8c9-e93415cbf94b 1.500s unavailable
GET /health/ready 1.500s unavailable
POST /api/v1/auth/sessions 1.500s unavailable
postgres снова поднят и готов через 0.83s
записей в истории после отказа: 1
ok
----------------------------------------------------------------------
Ran 1 test in 8.891s
OK
$ docker compose ps --format '{{.Service}} | {{.Image}} | {{.Status}}' # контейнер возвращён на место самим тестом
api | mtusi-messenger-lab2:2.0.0 | Up 3 minutes (healthy)
postgres | postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 | Up Less than a second (health: starting)
valkey | valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab | Up 3 minutes (healthy)
+170
View File
@@ -0,0 +1,170 @@
== 07: EXPLAIN (ANALYZE, BUFFERS) — страница истории чата ==
date: 2026-10-11T14:53:54Z (UTC)
host: Windows 10 Pro 19045, Git Bash (MSYS), python3 3.11.9; PostgreSQL 16.15 в контейнере
Что показывает: индекс ix_messages_chat_id_created_at_id (chat_id, created_at, id) не просто
существует, а используется. Запросы в разделах 2-4 — те же по форме, что собирает
src/messenger/repository.py: страница истории читается по курсору (created_at, id) > (...),
порядок задан парой (created_at, id), чтобы ничья по времени разрешалась идентификатором.
Данные: python3 student-tests/seed_messages.py --messages 10000 --chats 1000
чат с историей: 10 000 сообщений (20 116 в таблице), 3 333 момента времени делят
несколько сообщений — на уникальном времени проверка ничьей не выполнялась бы;
страница берётся у конца истории (позиция 9800), где OFFSET дороже всего.
Контрпримеры снимаются внутри транзакции BEGIN; DROP INDEX ...; ROLLBACK, поэтому схема
в базе не меняется — последняя проверка каждого раздела это подтверждает.
$ PYTHONIOENCODING=utf-8 python3 student-tests/explain_queries.py --only messages
========================================================================
1. Данные под экспериментом
========================================================================
всего сообщений: 20116
всего чатов: 3071, участников: 3105
чат 76ee3134-f95a-4f20-b1df-ba5b16062f49: 10000 сообщений
позиция страницы: 9800, курсор (created_at, id) = (2026-01-01 00:54:26+00, c7b45685-cd53-4ae7-8a7d-0d9438841896)
размер messages: 4448 kB, индекс ix_messages_chat_id_created_at_id: 1624 kB
моментов времени, которые делят несколько сообщений: 3333 (порядок обязан разрешать ничью по id)
========================================================================
2. Страница истории по курсору (keyset)
========================================================================
$ SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at FROM messages WHERE chat_id = '76ee3134-f95a-4f20-b1df-ba5b16062f49' AND (created_at, id) > ('2026-01-01 00:54:26+00'::timestamptz, 'c7b45685-cd53-4ae7-8a7d-0d9438841896'::uuid) ORDER BY created_at, id LIMIT 200;
Limit (cost=288.23..288.73 rows=200 width=65) (actual time=0.128..0.149 rows=199 loops=1)
Output: id, chat_id, sender_id, text, created_at
Buffers: shared hit=15
-> Sort (cost=288.23..288.87 rows=256 width=65) (actual time=0.127..0.135 rows=199 loops=1)
Output: id, chat_id, sender_id, text, created_at
Sort Key: messages.created_at, messages.id
Sort Method: quicksort Memory: 51kB
Buffers: shared hit=15
-> Bitmap Heap Scan on public.messages (cost=14.91..277.99 rows=256 width=65) (actual time=0.038..0.052 rows=199 loops=1)
Output: id, chat_id, sender_id, text, created_at
Recheck Cond: ((messages.chat_id = '76ee3134-f95a-4f20-b1df-ba5b16062f49'::uuid) AND (ROW(messages.created_at, messages.id) > ROW('2026-01-01 00:54:26+00'::timestamp with time zone, 'c7b45685-cd53-4ae7-8a7d-0d9438841896'::uuid)))
Heap Blocks: exact=4
Buffers: shared hit=9
-> Bitmap Index Scan on ix_messages_chat_id_created_at_id (cost=0.00..14.85 rows=256 width=0) (actual time=0.029..0.030 rows=199 loops=1)
Index Cond: ((messages.chat_id = '76ee3134-f95a-4f20-b1df-ba5b16062f49'::uuid) AND (ROW(messages.created_at, messages.id) > ROW('2026-01-01 00:54:26+00'::timestamp with time zone, 'c7b45685-cd53-4ae7-8a7d-0d9438841896'::uuid)))
Buffers: shared hit=5
Planning:
Buffers: shared hit=106
Planning Time: 0.326 ms
Execution Time: 0.196 ms
[OK] использован именно ix_messages_chat_id_created_at_id
[OK] история не читается последовательно — Limit, Sort, Bitmap Heap Scan, Bitmap Index Scan
[OK] курсор отсекает строки индексом, а не фильтром — Rows Removed by Filter: 0
[OK] прочитано не больше двух страниц — 199 строк
execution 0.267 ms, shared hit 15, read 0
Планировщик предпочёл bitmap-чтение и сортировку: по его оценке под
условие попадает 256 строк, и отсортировать их дешевле, чем идти по
индексу. Оценка занижена, но оба плана читают десятки блоков вместо
всей истории; на плане ниже видно, что порядок тоже даёт индекс.
========================================================================
2б. Тот же запрос, когда bitmap-чтение выключено
========================================================================
$ BEGIN; SET LOCAL enable_bitmapscan = off; EXPLAIN (...); ROLLBACK;
BEGIN
SET
Limit (cost=0.29..475.43 rows=200 width=65) (actual time=0.023..0.059 rows=199 loops=1)
Output: id, chat_id, sender_id, text, created_at
Buffers: shared hit=13
-> Index Scan using ix_messages_chat_id_created_at_id on public.messages (cost=0.29..608.47 rows=256 width=65) (actual time=0.022..0.046 rows=199 loops=1)
Output: id, chat_id, sender_id, text, created_at
Index Cond: ((messages.chat_id = '76ee3134-f95a-4f20-b1df-ba5b16062f49'::uuid) AND (ROW(messages.created_at, messages.id) > ROW('2026-01-01 00:54:26+00'::timestamp with time zone, 'c7b45685-cd53-4ae7-8a7d-0d9438841896'::uuid)))
Buffers: shared hit=13
Planning:
Buffers: shared hit=106
Planning Time: 0.352 ms
Execution Time: 0.098 ms
ROLLBACK
[OK] индекс отдаёт страницу по порядку (Index Scan) — Limit, Index Scan
[OK] сортировки нет: порядок (created_at, id) даёт индекс — Limit, Index Scan
execution 0.092 ms, shared hit 13, read 0
Оба плана читают десятки блоков вместо всей истории: индекс нужен не
«на всякий случай», а потому что без него страница требует полного чтения.
========================================================================
3. Контрпример: тот же запрос без индекса
========================================================================
Индекс удаляется и возвращается внутри одной транзакции:
$ BEGIN; DROP INDEX ix_messages_chat_id_created_at_id; EXPLAIN (...); ROLLBACK;
BEGIN
DROP INDEX
Limit (cost=610.94..611.44 rows=200 width=65) (actual time=1.434..1.453 rows=199 loops=1)
Output: id, chat_id, sender_id, text, created_at
Buffers: shared hit=255
-> Sort (cost=610.94..611.58 rows=256 width=65) (actual time=1.433..1.441 rows=199 loops=1)
Output: id, chat_id, sender_id, text, created_at
Sort Key: messages.created_at, messages.id
Sort Method: quicksort Memory: 51kB
Buffers: shared hit=255
-> Seq Scan on public.messages (cost=0.00..600.70 rows=256 width=65) (actual time=1.362..1.380 rows=199 loops=1)
Output: id, chat_id, sender_id, text, created_at
Filter: ((messages.chat_id = '76ee3134-f95a-4f20-b1df-ba5b16062f49'::uuid) AND (ROW(messages.created_at, messages.id) > ROW('2026-01-01 00:54:26+00'::timestamp with time zone, 'c7b45685-cd53-4ae7-8a7d-0d9438841896'::uuid)))
Rows Removed by Filter: 19917
Buffers: shared hit=249
Planning:
Buffers: shared hit=78
Planning Time: 0.247 ms
Execution Time: 1.495 ms
ROLLBACK
[OK] без индекса появляется последовательное чтение — Seq Scan
[OK] без индекса появляется сортировка — Limit, Sort, Seq Scan
[OK] без индекса читается вся история чата — просмотрено 20116 строк
[OK] с индексом просматривается малая доля истории — 199 строк против 10000
[OK] индекс ускоряет страницу — 0.267 ms против 1.601 ms
execution 1.601 ms, shared hit 255, read 0
ускорение: x6.0
[OK] ROLLBACK вернул схему: индекс на месте (найдено 1)
========================================================================
4. OFFSET против курсора на той же позиции
========================================================================
$ SELECT messages.id, messages.chat_id, messages.sender_id, messages.text, messages.created_at FROM messages WHERE chat_id = '76ee3134-f95a-4f20-b1df-ba5b16062f49' ORDER BY created_at, id OFFSET 9801 LIMIT 200;
Limit (cost=1188.44..1188.91 rows=190 width=65) (actual time=3.993..4.011 rows=199 loops=1)
Output: id, chat_id, sender_id, text, created_at
Buffers: shared hit=255
-> Sort (cost=1163.94..1188.91 rows=9991 width=65) (actual time=3.335..3.672 rows=10000 loops=1)
Output: id, chat_id, sender_id, text, created_at
Sort Key: messages.created_at, messages.id
Sort Method: quicksort Memory: 1713kB
Buffers: shared hit=255
-> Seq Scan on public.messages (cost=0.00..500.21 rows=9991 width=65) (actual time=0.586..1.375 rows=10000 loops=1)
Output: id, chat_id, sender_id, text, created_at
Filter: (messages.chat_id = '76ee3134-f95a-4f20-b1df-ba5b16062f49'::uuid)
Rows Removed by Filter: 10116
Buffers: shared hit=249
Planning:
Buffers: shared hit=107
Planning Time: 0.259 ms
Execution Time: 4.154 ms
[OK] обе страницы возвращают одни и те же строки
[OK] OFFSET медленнее курсора — 4.078 ms против 0.267 ms
[OK] OFFSET читает всё, что было до страницы — 10000 строк
execution 4.078 ms, shared hit 255, read 0
Задержка страницы по курсору не зависит от её номера, а OFFSET читает
всю предысторию заново на каждой странице.
========================================================================
Итог
========================================================================
[OK] использован именно ix_messages_chat_id_created_at_id
[OK] история не читается последовательно — Limit, Sort, Bitmap Heap Scan, Bitmap Index Scan
[OK] курсор отсекает строки индексом, а не фильтром — Rows Removed by Filter: 0
[OK] прочитано не больше двух страниц — 199 строк
[OK] индекс отдаёт страницу по порядку (Index Scan) — Limit, Index Scan
[OK] сортировки нет: порядок (created_at, id) даёт индекс — Limit, Index Scan
[OK] без индекса появляется последовательное чтение — Seq Scan
[OK] без индекса появляется сортировка — Limit, Sort, Seq Scan
[OK] без индекса читается вся история чата — просмотрено 20116 строк
[OK] с индексом просматривается малая доля истории — 199 строк против 10000
[OK] индекс ускоряет страницу — 0.267 ms против 1.601 ms
[OK] ROLLBACK вернул схему: индекс на месте (найдено 1)
[OK] обе страницы возвращают одни и те же строки
[OK] OFFSET медленнее курсора — 4.078 ms против 0.267 ms
[OK] OFFSET читает всё, что было до страницы — 10000 строк
проверок: 15, провалено: 0
РЕЗУЛЬТАТ: PASS
+159
View File
@@ -0,0 +1,159 @@
== 08: EXPLAIN (ANALYZE, BUFFERS) — список чатов пользователя ==
date: 2026-10-11T14:53:54Z (UTC)
host: Windows 10 Pro 19045, Git Bash (MSYS), python3 3.11.9; PostgreSQL 16.15 в контейнере
Что показывает: запрос «мои чаты» (repository.list_chats) находит чаты пользователя
индексом ix_chat_members_user_id_chat_id (user_id, chat_id), а не перебором таблицы
участников. Раздел 5б добавлен ради честной границы: у пользователя, которому
принадлежит 64% таблицы, планировщик законно предпочитает перебор — индекс рассчитан
на обычного пользователя с малой долей чатов, и замер показывает именно этот случай.
Данные: python3 student-tests/seed_messages.py --chats 1000 --noise-chats 2000
1001 чат у пользователя при 3105 строках chat_members; шумовые чаты существуют,
чтобы таблица участников была не из одного пользователя (раздел 5б).
$ PYTHONIOENCODING=utf-8 python3 student-tests/explain_queries.py --only chats
========================================================================
1. Данные под экспериментом
========================================================================
всего сообщений: 20116
всего чатов: 3071, участников: 3105
владелец засеянного списка чатов: 21268622-ac06-46b0-bf94-b9b4c98fb451, чатов у него 1001
========================================================================
5. Список чатов пользователя
========================================================================
$ SELECT chats.id, chats.title, chats.created_at FROM chats JOIN chat_members ON chats.id = chat_members.chat_id WHERE chat_members.user_id = '21268622-ac06-46b0-bf94-b9b4c98fb451'::uuid ORDER BY chats.created_at, chats.id LIMIT 200;
Limit (cost=174.36..174.86 rows=200 width=39) (actual time=0.967..0.986 rows=200 loops=1)
Output: chats.id, chats.title, chats.created_at
Buffers: shared hit=42
-> Sort (cost=174.36..176.86 rows=1001 width=39) (actual time=0.966..0.973 rows=200 loops=1)
Output: chats.id, chats.title, chats.created_at
Sort Key: chats.created_at, chats.id
Sort Method: top-N heapsort Memory: 39kB
Buffers: shared hit=42
-> Hash Join (cost=66.31..131.09 rows=1001 width=39) (actual time=0.242..0.767 rows=1001 loops=1)
Output: chats.id, chats.title, chats.created_at
Inner Unique: true
Hash Cond: (chats.id = chat_members.chat_id)
Buffers: shared hit=36
-> Seq Scan on public.chats (cost=0.00..56.71 rows=3071 width=39) (actual time=0.003..0.190 rows=3071 loops=1)
Output: chats.id, chats.title, chats.created_at
Buffers: shared hit=26
-> Hash (cost=53.80..53.80 rows=1001 width=16) (actual time=0.217..0.218 rows=1001 loops=1)
Output: chat_members.chat_id
Buckets: 1024 Batches: 1 Memory Usage: 55kB
Buffers: shared hit=10
-> Index Only Scan using ix_chat_members_user_id_chat_id on public.chat_members (cost=0.28..53.80 rows=1001 width=16) (actual time=0.017..0.111 rows=1001 loops=1)
Output: chat_members.chat_id
Index Cond: (chat_members.user_id = '21268622-ac06-46b0-bf94-b9b4c98fb451'::uuid)
Heap Fetches: 0
Buffers: shared hit=10
Planning:
Buffers: shared hit=177
Planning Time: 0.537 ms
Execution Time: 1.029 ms
[OK] использован именно ix_chat_members_user_id_chat_id
[OK] участники читаются по индексу, а не перебором — Index Only Scan
[OK] просмотрены участники пользователя, а не все строки таблицы — 1001 строк из 3105
execution 0.999 ms, shared hit 42, read 0
Порядок в этом запросе задаёт таблица chats (created_at живёт в ней),
поэтому узел Sort ожидаем: индекс отдаёт только чаты пользователя, а
сортируются его строки, а не вся таблица. Убрать этот Sort можно было
бы дублированием created_at в chat_members, но это денормализация
ради сортировки небольшой выборки. Таблицу chats планировщик при этом
перебирает целиком — здесь это дешевле индекса, и на данных большего
размера план изменится.
========================================================================
5б. Справка: пользователь с большой долей таблицы
========================================================================
afb4f512-933a-4ac6-816a-bedbe92bd41e — участник 2000 чатов из 3105 (64% таблицы).
Здесь индекс не нужен, и планировщик его не берёт: перебрать 3105 строк
дешевле, чем поднимать две тысячи строк по индексу. Это граница
применимости индекса, а не его дефект: у обычного пользователя чатов
мало, и индекс рассчитан на него.
$ SELECT chats.id, chats.title, chats.created_at FROM chats JOIN chat_members ON chats.id = chat_members.chat_id WHERE chat_members.user_id = 'afb4f512-933a-4ac6-816a-bedbe92bd41e'::uuid ORDER BY chats.created_at, chats.id LIMIT 200;
Limit (cost=238.03..238.53 rows=200 width=39) (actual time=2.011..2.034 rows=200 loops=1)
Output: chats.id, chats.title, chats.created_at
Buffers: shared hit=55
-> Sort (cost=238.03..243.03 rows=2000 width=39) (actual time=2.008..2.018 rows=200 loops=1)
Output: chats.id, chats.title, chats.created_at
Sort Key: chats.created_at, chats.id
Sort Method: top-N heapsort Memory: 39kB
Buffers: shared hit=55
-> Hash Join (cost=86.81..151.60 rows=2000 width=39) (actual time=1.024..1.581 rows=2000 loops=1)
Output: chats.id, chats.title, chats.created_at
Inner Unique: true
Hash Cond: (chats.id = chat_members.chat_id)
Buffers: shared hit=49
-> Seq Scan on public.chats (cost=0.00..56.71 rows=3071 width=39) (actual time=0.026..0.220 rows=3071 loops=1)
Output: chats.id, chats.title, chats.created_at
Buffers: shared hit=26
-> Hash (cost=61.81..61.81 rows=2000 width=16) (actual time=0.750..0.751 rows=2000 loops=1)
Output: chat_members.chat_id
Buckets: 2048 Batches: 1 Memory Usage: 110kB
Buffers: shared hit=23
-> Seq Scan on public.chat_members (cost=0.00..61.81 rows=2000 width=16) (actual time=0.099..0.380 rows=2000 loops=1)
Output: chat_members.chat_id
Filter: (chat_members.user_id = 'afb4f512-933a-4ac6-816a-bedbe92bd41e'::uuid)
Rows Removed by Filter: 1105
Buffers: shared hit=23
Planning:
Buffers: shared hit=177
Planning Time: 0.879 ms
Execution Time: 2.088 ms
execution 1.388 ms, shared hit 55, read 0
========================================================================
6. Контрпример: список чатов без индекса
========================================================================
$ BEGIN; DROP INDEX ix_chat_members_user_id_chat_id; EXPLAIN (...); ROLLBACK;
BEGIN
DROP INDEX
Limit (cost=182.37..182.87 rows=200 width=39) (actual time=0.995..1.030 rows=200 loops=1)
Output: chats.id, chats.title, chats.created_at
Buffers: shared hit=55
-> Sort (cost=182.37..184.87 rows=1001 width=39) (actual time=0.994..1.002 rows=200 loops=1)
Output: chats.id, chats.title, chats.created_at
Sort Key: chats.created_at, chats.id
Sort Method: top-N heapsort Memory: 39kB
Buffers: shared hit=55
-> Hash Join (cost=74.33..139.11 rows=1001 width=39) (actual time=0.353..0.812 rows=1001 loops=1)
Output: chats.id, chats.title, chats.created_at
Inner Unique: true
Hash Cond: (chats.id = chat_members.chat_id)
Buffers: shared hit=49
-> Seq Scan on public.chats (cost=0.00..56.71 rows=3071 width=39) (actual time=0.004..0.157 rows=3071 loops=1)
Output: chats.id, chats.title, chats.created_at
Buffers: shared hit=26
-> Hash (cost=61.81..61.81 rows=1001 width=16) (actual time=0.328..0.328 rows=1001 loops=1)
Output: chat_members.chat_id
Buckets: 1024 Batches: 1 Memory Usage: 55kB
Buffers: shared hit=23
-> Seq Scan on public.chat_members (cost=0.00..61.81 rows=1001 width=16) (actual time=0.008..0.216 rows=1001 loops=1)
Output: chat_members.chat_id
Filter: (chat_members.user_id = '21268622-ac06-46b0-bf94-b9b4c98fb451'::uuid)
Rows Removed by Filter: 2104
Buffers: shared hit=23
Planning:
Buffers: shared hit=152
Planning Time: 0.543 ms
Execution Time: 1.066 ms
ROLLBACK
[OK] без индекса участники перебираются целиком — Seq Scan
[OK] индекс сокращает объём чтения — 1001 строк против 3105
execution 1.025 ms, shared hit 55, read 0
========================================================================
Итог
========================================================================
[OK] использован именно ix_chat_members_user_id_chat_id
[OK] участники читаются по индексу, а не перебором — Index Only Scan
[OK] просмотрены участники пользователя, а не все строки таблицы — 1001 строк из 3105
[OK] без индекса участники перебираются целиком — Seq Scan
[OK] индекс сокращает объём чтения — 1001 строк против 3105
проверок: 5, провалено: 0
РЕЗУЛЬТАТ: PASS
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 2,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 30,
"elapsed_seconds": 30.359,
"concurrency": 16,
"successful_requests": 4933,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 162.489,
"successful_latency_ms": {
"p50": 93.0,
"p95": 172.0,
"p99": 234.0
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+109
View File
@@ -0,0 +1,109 @@
== 09: синтетическая нагрузка на запись (closed loop) ==
date: 2026-10-11T19:34:09Z (UTC)
Что измеряется: сценарий tests/load.py пишет сообщения в один чат из нескольких
потоков и печатает число успешных запросов, долю ошибок, RPS и перцентили задержки.
Первый прогон — цель make load по умолчанию (4 потока, 30 с), второй — те же 30 с
в 16 потоков, чтобы увидеть, что меняется, когда очередь растёт.
Чего эти числа не показывают. Это closed loop: каждый поток ждёт ответа, прежде чем
отправить следующий запрос, поэтому при насыщении нагрузка падает вместе с
производительностью, а перцентили занижены (coordinated omission). Клиент и сервер
живут на одной машине в Docker Desktop, так что здесь есть и накладные расходы
клиента, и общий процессор. Доля ошибок 0 означает «ни один запрос не упал по
таймауту или 5xx», а не «система выдерживает любой поток»: предел здесь задан
числом потоков, а не открытой нагрузкой.
Стенд перед нагрузкой: api/postgres/valkey подняты, в базе засеяно 20 116 сообщений
в 3 071 чате (доказательства 07 и 08), конкурирующая нагрузка не запущена.
$ make load BASE_URL=http://127.0.0.1:8080
python3 tests/load.py --base-url "http://127.0.0.1:8080"
{
"lab": 2,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 30,
"elapsed_seconds": 30.078,
"concurrency": 4,
"successful_requests": 6282,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 208.857,
"successful_latency_ms": {
"p50": 16.0,
"p95": 32.0,
"p99": 47.0
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
$ python3 -X utf8 tests/load.py --base-url http://127.0.0.1:8080 --concurrency 16 --output evidence/09-load-c16.json
{
"lab": 2,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 30,
"elapsed_seconds": 30.359,
"concurrency": 16,
"successful_requests": 4933,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 162.489,
"successful_latency_ms": {
"p50": 93.0,
"p95": 172.0,
"p99": 234.0
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
$ docker stats --no-stream --format '{{.Name}} | CPU {{.CPUPerc}} | RAM {{.MemUsage}} ({{.MemPerc}})' # во время второго прогона
mtusi2026lab2-api-1 | CPU 56.39% | RAM 99.45MiB / 512MiB (19.42%)
mtusi2026lab2-postgres-1 | CPU 22.86% | RAM 42.13MiB / 512MiB (8.23%)
mtusi2026lab2-valkey-1 | CPU 1.54% | RAM 8.727MiB / 256MiB (3.41%)
mtusi2026lab2-api-1 | CPU 93.35% | RAM 101.8MiB / 512MiB (19.89%)
mtusi2026lab2-postgres-1 | CPU 20.34% | RAM 43.64MiB / 512MiB (8.52%)
mtusi2026lab2-valkey-1 | CPU 0.92% | RAM 8.73MiB / 256MiB (3.41%)
mtusi2026lab2-api-1 | CPU 101.81% | RAM 103.3MiB / 512MiB (20.19%)
mtusi2026lab2-postgres-1 | CPU 23.35% | RAM 45.68MiB / 512MiB (8.92%)
mtusi2026lab2-valkey-1 | CPU 0.91% | RAM 8.73MiB / 256MiB (3.41%)
mtusi2026lab2-api-1 | CPU 0.14% | RAM 103.3MiB / 512MiB (20.18%)
mtusi2026lab2-postgres-1 | CPU 2.87% | RAM 35.48MiB / 512MiB (6.93%)
mtusi2026lab2-valkey-1 | CPU 0.65% | RAM 8.73MiB / 256MiB (3.41%)
$ psql: размер датасета после обоих прогонов
сообщений 31454
чатов 3136
пользователей 349
таблица messages 7472 kB
база messenger 16 MB
Два прогона вместе записали 11 215 сообщений (6 282 + 4 933) — таблица выросла с
засеянных 20 116 до 31 454 строк.
Что из этого следует (и чего не следует)
За те же 30 с четыре потока приняли 6 282 сообщения, а шестнадцать — 4 933:
потоков стало вчетверо больше, пропускная способность упала на 22 %,
задержка p99 выросла с 47 до 234 мс. Ошибок не было ни в одном прогоне.
Счётчики docker stats показывают, где предел. postgres в обоих прогонах держит
20-23 % (запись в таблицу с двумя индексами стоит дёшево), valkey — меньше 2 %
(на запрос один GET сессии). Остальное занимает api: 56 % на четырёх потоках и
93-102 % на шестнадцати. Важно: у контейнера api лимит 2.0 CPU (compose.yaml),
то есть в квоту он не упирается — он упирается в одно ядро, потому что приложение
запущено одним процессом uvicorn (workers=1 в src/messenger/__main__.py; там же
объяснено почему — границы пула соединений заданы на процесс). Один процесс — один
event loop — одно ядро: семнадцатый одновременный запрос не получает параллелизма,
он ждёт в очереди, и растёт задержка.
Что именно ест это ядро, эти замеры не отвечают. Кандидаты — сериализация
SQLAlchemy на каждый POST, JSON, проверка сессии в Valkey. Это вопрос для
профилировщика, поэтому в отчёте он записан следующим шагом, а не выводом.
Чего числа не доказывают. Клиент живёт на той же машине и вне контейнеров, поэтому
его собственные затраты (16 потоков Python на хосте) в docker stats не видны, а
время запроса включает и его. Closed loop означает, что при насыщении RPS и
задержка связаны: упавший RPS здесь — следствие того, что каждый поток ждёт ответа,
а не отказ системы. И датасет мал: 31 454 сообщения — это режим учебного стенда,
при десятках миллионов строк и запись, и индексы будут вести себя иначе; это
ограничение эксперимента, а не свойство схемы.
+107
View File
@@ -0,0 +1,107 @@
== 10: роли инфраструктуры и их реализация ==
host: Windows 10 Pro 19045, Git Bash; make работает через sh (MSYS)
date: 2026-10-11T19:45:00Z (UTC)
docker: 28.0.1, compose 2.33.1-desktop.1
Что показывает: infra/README.md требует сопоставить роль → service → версия/digest →
health → volume → сеть/порт → способ передачи credentials и привести bootstrap с
безопасным повторением. Ниже это сопоставление и есть. Факты взяты из compose.yaml,
Dockerfile и работающего стенда; проверка того, что они совпадают с живыми
контейнерами, — в доказательстве 11.
роль (contracts/infrastructure.json) → фактический сервис
------------------------------------------------------------------------------
api → api (собственная сборка, student_implements: true)
postgres → postgres (users/chats/membership/messages + миграции)
redis_or_valkey → valkey (required_for_lab2_grade4: true — выбран Valkey)
(bootstrap) → migrate (одноразовая роль того же образа)
Подробная таблица
------------------------------------------------------------------------------
роль/сервис | образ | healthcheck
| том | сеть и порт
| credentials
api | mtusi-messenger-lab2:2.0.0 | python -m messenger.healthcheck
| из Dockerfile, база python:3.11.9-slim- | interval 10s, timeout 3s,
| bookworm@sha256:8fb099199b9f2d70342674 | retries 3, start_period 5s
| bd9dbccd3ed03a258f26bbd1d556822c6dfc60 | (GET /health/live)
| c317 (тот же digest в builder и runtime) |
| том не нужен: процесс без локального | backend (bridge),
| состояния; состояние — в PG и Valkey | 127.0.0.1:8080->8080
| | /run/secrets/{database_url,
| | cache_url,cursor_secret}
postgres | postgres:16.15-bookworm | pg_isready -U messenger
| @sha256:0ea6700a3b4f0ae6ce746519073558 | -d messenger
| aed4d88a79d8d07622a9a644946c7319c4 | interval 5s, timeout 3s,
| (pinned tag + digest) | retries 12, start_period 10s
| pgdata:/var/lib/postgresql/data | backend; порты НЕ публикуются
| (named volume, `down` его не удаляет) | POSTGRES_PASSWORD_FILE=
| | /run/secrets/postgres_password
| | initdb: --auth-host=scram-sha-256
valkey | valkey/valkey:8.0.11-trixie | valkey-cli ping
| @sha256:4436c94fc34ce4af0354b9379d433a1f | interval 5s, timeout 3s,
| 258998fb955f995c89822f98c14a8cab | retries 12, start_period 5s
| valkeydata:/data | backend; порты НЕ публикуются
| (AOF: --appendonly yes --appendfsync | credentials нет: сервис виден
| everysec --save "" — RDB выключен, | только внутри сети backend
| чтобы механизм долговечности был один) |
migrate | тот же образ mtusi-messenger-lab2:2.0.0 | healthcheck не нужен:
| command: alembic upgrade head | контейнер живёт до конца
| restart: "no" — одноразовая роль, | миграции и выходит
| api ждёт service_completed_successfully | backend; портов нет
| тома нет: пишет только в PostgreSQL | /run/secrets/database_url
| | (Valkey миграциям не нужен)
Почему наружу не смотрит ничего, кроме API: публикация портов PostgreSQL и Valkey
превратила бы учебный стенд в открытую базу. Тесты ходят с хоста только на API,
а сервисы находят друг друга по именам в сети backend.
Bootstrap и его безопасное повторение
------------------------------------------------------------------------------
$ sh scripts/bootstrap-secrets.sh
# Скрипт запущен на стенде, где secrets/ уже создан; на чистом клоне те же строки
# читались бы как "create secrets/...". Значения при повторном запуске не меняются,
# потому что файлы с содержимым не перезаписываются (umask 077, режим 600).
keep secrets/postgres_password
keep secrets/cursor_secret
keep secrets/cache_url
keep secrets/database_url
done: /c/Users/denis/Desktop/HighLoad/mtusi2026lab2/secrets
next: docker compose up -d --build
$ docker compose --env-file .env config --quiet
(пустой вывод, код 0: конфигурация валидна и полностью разрешается)
$ docker compose --env-file .env up -d --build
# migrate ждёт здоровый postgres, применяет схему до head и выходит с кодом 0;
# api ждёт migrate и стартует; готовность — GET /health/ready == 200.
Почему это повторяемо: миграции идемпотентны (повторный `alembic upgrade head`
ничего не меняет — доказательство 11, раздел 6), существующие secrets/* скрипт
не перезаписывает, тома `pgdata` и `valkeydata` именованные и `docker compose
down` без `-v` их сохраняет. Опасные команды (`down -v`, `docker volume rm`,
flushall) в репозитории не встречаются: scripts/restart.sh делает только
`docker compose restart --timeout 10 api postgres valkey` и проверяет, что все три
сервиса снова running.
Что лежит в образах, а что нет
------------------------------------------------------------------------------
В образ приложения не попадают tests/, student-tests/, contracts/, examples/,
infra/, Makefile и *.md — они перечислены в .dockerignore. То есть публичные тесты
не могут «пройти» за счёт кода, которого нет рядом, а сам образ содержит только
src/, migrations/, alembic.ini и requirements.txt. Внутри контейнера нет ни
компилятора, ни заголовочных файлов: зависимости ставятся в builder-стадии,
runtime получает готовый venv (образ весит 74 408 022 байта, то есть ~71 МиБ).
Какие роли заявлены и какие реализованы
------------------------------------------------------------------------------
contracts/infrastructure.json требует минимум: api (count_min 1, student_implements)
и postgres (persistent_volume для пользователей, чатов, членства и сообщений).
Опциональный redis_or_valkey помечен как required_for_lab2_grade4 — он реализован
и действительно используется: сессии, TTL, отзыв (доказательства 04, 05, 11).
Правило «не публиковать внутренние порты реплик API» к ЛР2 не применяется: реплика
одна, и она публикуется на loopback для тестов; балансировщик — задача ЛР3.
+143
View File
@@ -0,0 +1,143 @@
== 11: проверка работающего стенда, а не файлов ==
host: Windows 10 Pro 19045, Git Bash; make работает через sh (MSYS)
date: 2026-10-11T19:40:57Z (UTC)
Что показывает: student-tests/verify_stack.py смотрит на запущенные контейнеры и на
живой API, а не на репозиторий. Проверяются непривилегированный пользователь и
доступность только на чтение внутри контейнера, отсутствие публикации портов
PostgreSQL и Valkey, AOF и режим fsync, версии и digest образов, схема, ограничения
и индексы, сквозной сценарий через HTTP, отсутствие секретов в логах, лимиты памяти
и политика перезапуска. Скрипт печатает только то, что можно показывать: ни паролей,
ни токенов, ни содержимого secrets/ в выводе нет.
$ python3 -u -X utf8 student-tests/verify_stack.py
========================================================================
Аппаратура и версии
========================================================================
хост: Windows 10 (AMD64)
python: 3.11.9
стенд: C:\Users\denis\Desktop\HighLoad\mtusi2026lab2
========================================================================
0. Docker и Compose доступны
========================================================================
[OK] docker compose отвечает
docker: 2.33.1-desktop.1
compose: Docker Compose version v2.33.1-desktop.1
========================================================================
1. Состав стенда
========================================================================
$ docker compose ps --all
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
mtusi2026lab2-api-1 mtusi-messenger-lab2:2.0.0 "python -m messenger" api 8 minutes ago Up 7 minutes (healthy) 127.0.0.1:8080->8080/tcp
mtusi2026lab2-migrate-1 mtusi-messenger-lab2:2.0.0 "alembic upgrade head" migrate 5 hours ago Exited (0) 8 minutes ago
mtusi2026lab2-postgres-1 postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 "docker-entrypoint.s…" postgres 6 hours ago Up 9 minutes (healthy) 5432/tcp
mtusi2026lab2-valkey-1 valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab "tini -- docker-entr…" valkey 6 hours ago Up 12 minutes (healthy) 6379/tcp
[OK] сервис api запущен
[OK] сервис postgres запущен
[OK] сервис valkey запущен
[OK] одноразовая миграция завершилась с кодом 0
image: postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4
image: valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab
[OK] образы postgres и valkey закреплены по digest — 2 строк
========================================================================
2. Непривилегированный пользователь
========================================================================
$ docker compose exec -T api id -> uid=10001(app) gid=10001(app) groups=10001(app)
[OK] процесс работает под uid 10001
[OK] USER образа равен 10001 — 10001:10001
[OK] PID 1 работает не от root — Uid: 10001 10001 10001 10001
CapDrop/Privileged: [] false
========================================================================
3. Сеть: что и куда публикуется
========================================================================
[OK] postgres не публикует порты — {}
[OK] valkey не публикует порты — {}
api: {"8080/tcp":[{"HostIp":"127.0.0.1","HostPort":"8080"}]}
[OK] API опубликован только на loopback
========================================================================
4. Секреты
========================================================================
файлы: cache_url, cursor_secret, database_url, postgres_password
[OK] каталог secrets/ заполнен
[OK] secrets/ и .env вне Git (git check-ignore)
[OK] в индексе Git нет файлов secrets/
[OK] docker compose config не печатает пароль PostgreSQL
[OK] database_url с паролем тоже не попадает в вывод compose
/run/secrets:
total 2
-rwxr-xr-x 1 app app 22 Oct 11 14:05 cache_url
-rwxr-xr-x 1 app app 65 Oct 11 14:05 cursor_secret
-rwxr-xr-x 1 root root 120 Oct 11 14:05 database_url
[OK] секреты смонтированы файлами в /run/secrets
[OK] контейнер получает *_FILE, а не значение
[OK] значений секретов нет в окружении процесса
========================================================================
5. Valkey: долговечность сессий
========================================================================
[OK] CONFIG GET appendonly = 'yes' — получено 'yes'
[OK] CONFIG GET appendfsync = 'everysec' — получено 'everysec'
[OK] CONFIG GET save = '' — получено ''
[OK] INFO persistence подтверждает AOF — aof_enabled:1
[OK] данные лежат в именованном томе — /data
========================================================================
6. PostgreSQL: схема, миграции, индексы
========================================================================
PostgreSQL 16.15 (Debian 16.15-1.pgdg12+2)
[OK] версия PostgreSQL соответствует compose
[OK] схема находится на head — 0001_initial_schema (head)
[OK] alembic upgrade head проходит повторно без ошибок
[OK] повторный прогон миграции ничего не меняет (нет Running upgrade)
[OK] alembic check: миграция совпадает с моделями SQLAlchemy
[OK] индекс ix_messages_chat_id_created_at_id существует — CREATE INDEX ix_messages_chat_id_created_at_id ON public.messages USING btree (chat_id, created_at, id)
[OK] индекс ix_chat_members_user_id_chat_id существует — CREATE INDEX ix_chat_members_user_id_chat_id ON public.chat_members USING btree (user_id, chat_id)
[OK] индекс uq_users_username существует — CREATE UNIQUE INDEX uq_users_username ON public.users USING btree (username)
[OK] CHECK-ограничение users:ck_users_username_format существует
[OK] CHECK-ограничение users:ck_users_display_name_length существует
[OK] CHECK-ограничение chats:ck_chats_title_length существует
[OK] CHECK-ограничение messages:ck_messages_text_length существует
все ограничения: chats:ck_chats_title_length, messages:ck_messages_text_length, users:ck_users_display_name_length, users:ck_users_username_format
========================================================================
7. Сквозная проверка через HTTP
========================================================================
[OK] вход выдаёт opaque-токен длиной 43
[OK] /users/me возвращает владельца сессии
[OK] в ответе нет ни пароля, ни его хэша
[OK] сессия лежит в Valkey
[OK] ключ — sha256 токена, а не сам токен
[OK] у ключа положительный TTL — 3597 s
[OK] сырой токен не встречается ни в одном имени ключа
========================================================================
8. Логи не содержат секретов
========================================================================
всего строк лога: 11518
[OK] во всём логе нет пароль
[OK] во всём логе нет токен
[OK] во всём логе нет ключ сессии
[OK] во всём логе нет query-строки с курсором
[OK] во всём логе нет заголовка авторизации
========================================================================
9. Ограничения ресурсов и политика перезапуска
========================================================================
[OK] api: память 536870912 Б, restart=unless-stopped
[OK] postgres: память 536870912 Б, restart=unless-stopped
[OK] valkey: память 268435456 Б, restart=unless-stopped
========================================================================
Итог
========================================================================
успешно: 52
РЕЗУЛЬТАТ: PASS
код возврата: 0
+779
View File
@@ -0,0 +1,779 @@
== 12: запуск из чистого clone ==
host: Windows 10 Pro 19045, x64, Git Bash; Docker 28.0.1 (Docker Desktop, WSL2)
date: 2026-10-11T19:43:28Z (UTC)
Что показывает: что получит человек, склонировавший репозиторий, — сборку образа
без кэша, миграции на пустом томе, публичный сценарий, проверку перезапуска и свои
проверки. Ничего из локального состояния (том .venv, secrets/, .env, кэш сборки) в
клон не переносится.
Оговорка. Закоммиченного состояния в этой работе нет — коммиты делает автор позже,
поэтому «клон» здесь — копия рабочего дерева без файлов, которые Git игнорирует
(.git, .venv, secrets/, .env, __pycache__). Для проверки это то же самое: в копии нет
ни одного файла, который не попадёт в репозиторий.
$ mkdir -p /c/Users/denis/AppData/Local/Temp/lab2-clean-clone && tar -c --exclude=.git --exclude=.venv --exclude=secrets \n --exclude=.env --exclude=__pycache__ --exclude="*.pyc" . | tar -x -C /c/Users/denis/AppData/Local/Temp/lab2-clean-clone
скопировано: 97 файлов, 706K
корень копии:
CONTRIBUTING.md
COURSE.md
Dockerfile
Dockerfile.example
MAINTAINERS.md
Makefile
README.md
REPORT.md
alembic.ini
compose.example.yaml
compose.yaml
contracts
evidence
examples
infra
lab.json
migrations
requirements-dev.txt
requirements.txt
scripts
src
student-tests
tests
Чего в копии нет (как и в клоне, пока автор не положил их рядом): secrets/, .env, .venv
$ docker compose stop # в основном репозитории: освобождаем порт 8080 и имя проекта
Container mtusi2026lab2-api-1 Stopping
Container mtusi2026lab2-api-1 Stopped
Container mtusi2026lab2-valkey-1 Stopping
Container mtusi2026lab2-migrate-1 Stopping
Container mtusi2026lab2-migrate-1 Stopped
Container mtusi2026lab2-postgres-1 Stopping
Container mtusi2026lab2-valkey-1 Stopped
Container mtusi2026lab2-postgres-1 Stopped
$ cd /c/Users/denis/AppData/Local/Temp/lab2-clean-clone
$ cp .env.example .env && sh scripts/bootstrap-secrets.sh
create secrets/postgres_password
create secrets/cursor_secret
create secrets/cache_url
create secrets/database_url
done: /c/Users/denis/AppData/Local/Temp/lab2-clean-clone/secrets
next: docker compose up -d --build
$ docker compose --env-file .env config --quiet # валидность до сборки
(пустой вывод, код 0)
$ time docker compose --env-file .env build --no-cache
Compose now can delegate build to bake for better performances
Just set COMPOSE_BAKE=true
#0 building with "desktop-linux" instance using docker driver
#1 [migrate internal] load build definition from Dockerfile
#1 transferring dockerfile: 2.13kB 0.0s done
#1 DONE 0.1s
#2 [migrate internal] load metadata for docker.io/library/python:3.11.9-slim-bookworm@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317
#2 DONE 1.1s
#3 [migrate internal] load .dockerignore
#3 transferring context: 488B done
#3 DONE 0.1s
#4 [migrate runtime 2/7] WORKDIR /app
#4 CACHED
#5 [migrate builder 1/4] FROM docker.io/library/python:3.11.9-slim-bookworm@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317
#5 resolve docker.io/library/python:3.11.9-slim-bookworm@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317 0.1s done
#5 CACHED
#6 [migrate internal] load build context
#6 transferring context: 98.23kB 0.0s done
#6 DONE 0.1s
#7 [migrate builder 2/4] RUN python -m venv /opt/venv
#7 ...
#8 [migrate runtime 3/7] RUN useradd --create-home --uid 10001 --shell /usr/sbin/nologin app
#8 DONE 0.5s
#7 [migrate builder 2/4] RUN python -m venv /opt/venv
#7 DONE 4.6s
#9 [migrate builder 3/4] COPY requirements.txt ./
#9 DONE 0.1s
#10 [migrate builder 4/4] RUN /opt/venv/bin/pip install --no-cache-dir --timeout 60 -r requirements.txt
#10 1.038 Collecting alembic==1.16.5 (from -r requirements.txt (line 5))
#10 1.377 Downloading alembic-1.16.5-py3-none-any.whl.metadata (7.3 kB)
#10 1.441 Collecting annotated-doc==0.0.5 (from -r requirements.txt (line 6))
#10 1.502 Downloading annotated_doc-0.0.5-py3-none-any.whl.metadata (6.5 kB)
#10 1.572 Collecting annotated-types==0.8.0 (from -r requirements.txt (line 7))
#10 1.634 Downloading annotated_types-0.8.0-py3-none-any.whl.metadata (15 kB)
#10 1.725 Collecting anyio==4.15.1 (from -r requirements.txt (line 8))
#10 1.789 Downloading anyio-4.15.1-py3-none-any.whl.metadata (4.7 kB)
#10 1.869 Collecting argon2-cffi==25.1.0 (from -r requirements.txt (line 9))
#10 1.931 Downloading argon2_cffi-25.1.0-py3-none-any.whl.metadata (4.1 kB)
#10 2.002 Collecting argon2-cffi-bindings==26.1.0 (from -r requirements.txt (line 10))
#10 2.065 Downloading argon2_cffi_bindings-26.1.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl.metadata (7.5 kB)
#10 2.218 Collecting asyncpg==0.30.0 (from -r requirements.txt (line 11))
#10 2.281 Downloading asyncpg-0.30.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (5.0 kB)
#10 2.502 Collecting cffi==2.1.1 (from -r requirements.txt (line 12))
#10 2.563 Downloading cffi-2.1.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.metadata (2.5 kB)
#10 2.636 Collecting click==8.5.0 (from -r requirements.txt (line 13))
#10 2.697 Downloading click-8.5.0-py3-none-any.whl.metadata (2.6 kB)
#10 2.824 Collecting fastapi==0.141.1 (from -r requirements.txt (line 14))
#10 2.886 Downloading fastapi-0.141.1-py3-none-any.whl.metadata (27 kB)
#10 3.171 Collecting greenlet==3.5.6 (from -r requirements.txt (line 15))
#10 3.234 Downloading greenlet-3.5.6-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.metadata (3.8 kB)
#10 3.299 Collecting h11==0.16.0 (from -r requirements.txt (line 16))
#10 3.364 Downloading h11-0.16.0-py3-none-any.whl.metadata (8.3 kB)
#10 3.435 Collecting idna==3.20 (from -r requirements.txt (line 17))
#10 3.497 Downloading idna-3.20-py3-none-any.whl.metadata (7.2 kB)
#10 3.570 Collecting Mako==1.4.3 (from -r requirements.txt (line 18))
#10 3.631 Downloading mako-1.4.3-py3-none-any.whl.metadata (2.9 kB)
#10 3.743 Collecting MarkupSafe==3.0.4 (from -r requirements.txt (line 19))
#10 3.804 Downloading markupsafe-3.0.4-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.metadata (2.7 kB)
#10 3.868 Collecting pycparser==3.11 (from -r requirements.txt (line 20))
#10 3.929 Downloading pycparser-3.11-py3-none-any.whl.metadata (8.2 kB)
#10 4.122 Collecting pydantic==2.14.0 (from -r requirements.txt (line 21))
#10 4.182 Downloading pydantic-2.14.0-py3-none-any.whl.metadata (131 kB)
#10 4.265 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 131.6/131.6 kB 1.6 MB/s eta 0:00:00
#10 5.185 Collecting pydantic_core==2.50.0 (from -r requirements.txt (line 22))
#10 5.250 Downloading pydantic_core-2.50.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (6.5 kB)
#10 5.347 Collecting redis==6.4.0 (from -r requirements.txt (line 23))
#10 5.409 Downloading redis-6.4.0-py3-none-any.whl.metadata (10 kB)
#10 5.857 Collecting SQLAlchemy==2.0.44 (from -r requirements.txt (line 24))
#10 5.920 Downloading sqlalchemy-2.0.44-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (9.5 kB)
#10 6.010 Collecting starlette==1.7.0 (from -r requirements.txt (line 25))
#10 6.071 Downloading starlette-1.7.0-py3-none-any.whl.metadata (6.6 kB)
#10 6.134 Collecting typing-inspection==0.4.4 (from -r requirements.txt (line 26))
#10 6.197 Downloading typing_inspection-0.4.4-py3-none-any.whl.metadata (2.6 kB)
#10 6.272 Collecting typing_extensions==4.16.0 (from -r requirements.txt (line 27))
#10 6.332 Downloading typing_extensions-4.16.0-py3-none-any.whl.metadata (3.3 kB)
#10 6.418 Collecting uvicorn==0.53.0 (from -r requirements.txt (line 28))
#10 6.479 Downloading uvicorn-0.53.0-py3-none-any.whl.metadata (6.6 kB)
#10 6.703 Downloading alembic-1.16.5-py3-none-any.whl (247 kB)
#10 6.777 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 247.4/247.4 kB 3.3 MB/s eta 0:00:00
#10 6.838 Downloading annotated_doc-0.0.5-py3-none-any.whl (5.3 kB)
#10 6.899 Downloading annotated_types-0.8.0-py3-none-any.whl (13 kB)
#10 6.960 Downloading anyio-4.15.1-py3-none-any.whl (132 kB)
#10 6.974 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 132.1/132.1 kB 10.2 MB/s eta 0:00:00
#10 7.034 Downloading argon2_cffi-25.1.0-py3-none-any.whl (14 kB)
#10 7.096 Downloading argon2_cffi_bindings-26.1.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl (26 kB)
#10 7.161 Downloading asyncpg-0.30.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.1 MB)
#10 7.538 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.1/3.1 MB 8.3 MB/s eta 0:00:00
#10 7.600 Downloading cffi-2.1.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (217 kB)
#10 7.617 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 217.8/217.8 kB 13.1 MB/s eta 0:00:00
#10 7.679 Downloading click-8.5.0-py3-none-any.whl (125 kB)
#10 7.689 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 125.3/125.3 kB 13.7 MB/s eta 0:00:00
#10 7.750 Downloading fastapi-0.141.1-py3-none-any.whl (131 kB)
#10 7.761 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 132.0/132.0 kB 13.4 MB/s eta 0:00:00
#10 7.823 Downloading greenlet-3.5.6-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (624 kB)
#10 7.948 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 624.4/624.4 kB 5.0 MB/s eta 0:00:00
#10 8.010 Downloading h11-0.16.0-py3-none-any.whl (37 kB)
#10 8.080 Downloading idna-3.20-py3-none-any.whl (69 kB)
#10 8.102 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 69.6/69.6 kB 3.5 MB/s eta 0:00:00
#10 8.163 Downloading mako-1.4.3-py3-none-any.whl (80 kB)
#10 8.188 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 80.2/80.2 kB 3.3 MB/s eta 0:00:00
#10 8.252 Downloading markupsafe-3.0.4-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (22 kB)
#10 8.317 Downloading pycparser-3.11-py3-none-any.whl (51 kB)
#10 8.333 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 51.2/51.2 kB 3.7 MB/s eta 0:00:00
#10 8.395 Downloading pydantic-2.14.0-py3-none-any.whl (487 kB)
#10 8.570 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 487.1/487.1 kB 2.8 MB/s eta 0:00:00
#10 8.632 Downloading pydantic_core-2.50.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.2 MB)
#10 9.173 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.2/2.2 MB 4.0 MB/s eta 0:00:00
#10 9.239 Downloading redis-6.4.0-py3-none-any.whl (279 kB)
#10 9.284 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 279.8/279.8 kB 6.3 MB/s eta 0:00:00
#10 9.346 Downloading sqlalchemy-2.0.44-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.3 MB)
#10 9.922 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.3/3.3 MB 5.8 MB/s eta 0:00:00
#10 9.983 Downloading starlette-1.7.0-py3-none-any.whl (78 kB)
#10 9.994 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 79.0/79.0 kB 8.0 MB/s eta 0:00:00
#10 10.06 Downloading typing_inspection-0.4.4-py3-none-any.whl (14 kB)
#10 10.12 Downloading typing_extensions-4.16.0-py3-none-any.whl (45 kB)
#10 10.12 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 45.6/45.6 kB 15.4 MB/s eta 0:00:00
#10 10.19 Downloading uvicorn-0.53.0-py3-none-any.whl (87 kB)
#10 10.19 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 87.1/87.1 kB 14.8 MB/s eta 0:00:00
#10 10.32 Installing collected packages: typing_extensions, redis, pycparser, MarkupSafe, idna, h11, greenlet, click, asyncpg, annotated-types, annotated-doc, uvicorn, typing-inspection, SQLAlchemy, pydantic_core, Mako, cffi, anyio, starlette, pydantic, argon2-cffi-bindings, alembic, fastapi, argon2-cffi
#10 12.63 Successfully installed Mako-1.4.3 MarkupSafe-3.0.4 SQLAlchemy-2.0.44 alembic-1.16.5 annotated-doc-0.0.5 annotated-types-0.8.0 anyio-4.15.1 argon2-cffi-25.1.0 argon2-cffi-bindings-26.1.0 asyncpg-0.30.0 cffi-2.1.1 click-8.5.0 fastapi-0.141.1 greenlet-3.5.6 h11-0.16.0 idna-3.20 pycparser-3.11 pydantic-2.14.0 pydantic_core-2.50.0 redis-6.4.0 starlette-1.7.0 typing-inspection-0.4.4 typing_extensions-4.16.0 uvicorn-0.53.0
#10 DONE 15.5s
#11 [migrate runtime 4/7] COPY --from=builder /opt/venv /opt/venv
#11 DONE 4.0s
#12 [migrate runtime 5/7] COPY --chown=app:app src/ ./src/
#12 DONE 0.3s
#13 [migrate runtime 6/7] COPY --chown=app:app alembic.ini ./
#13 DONE 0.4s
#14 [migrate runtime 7/7] COPY --chown=app:app migrations/ ./migrations/
#14 DONE 0.4s
#15 [migrate] exporting to image
#15 exporting layers
#15 exporting layers 6.0s done
#15 exporting manifest sha256:497714c4d6d7418762b653f07ea94c448f92f929a1caae79f3a80186f4ec97eb 0.1s done
#15 exporting config sha256:7f4549760fd2cd13e09f6df2097340279389796f0c0a89161a7256959b0b83e4 0.1s done
#15 exporting attestation manifest sha256:53ee5a784e528301b62ba62631f7d8e41f36288a118e130d55546275cd491723 0.1s done
#15 exporting manifest list sha256:072b4ca96ef50ee50ef92f2f350756cbf3083a8fdc948255ee8705e6927f0153
#15 exporting manifest list sha256:072b4ca96ef50ee50ef92f2f350756cbf3083a8fdc948255ee8705e6927f0153 0.1s done
#15 naming to docker.io/library/mtusi-messenger-lab2:2.0.0 0.0s done
#15 unpacking to docker.io/library/mtusi-messenger-lab2:2.0.0
#15 unpacking to docker.io/library/mtusi-messenger-lab2:2.0.0 1.6s done
#15 DONE 8.1s
#16 [migrate] resolving provenance for metadata file
#16 DONE 0.1s
#17 [api internal] load build definition from Dockerfile
#17 transferring dockerfile:
#17 transferring dockerfile: 2.13kB done
#17 DONE 0.2s
#2 [api internal] load metadata for docker.io/library/python:3.11.9-slim-bookworm@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317
#2 DONE 1.2s
#18 [api internal] load .dockerignore
#18 transferring context: 488B done
#18 DONE 0.1s
#19 [api internal] load build context
#19 transferring context: 1.62kB done
#19 DONE 0.1s
#5 [api builder 1/4] FROM docker.io/library/python:3.11.9-slim-bookworm@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317
#5 resolve docker.io/library/python:3.11.9-slim-bookworm@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317
#5 resolve docker.io/library/python:3.11.9-slim-bookworm@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317 0.2s done
#5 CACHED
#4 [api runtime 2/7] WORKDIR /app
#4 CACHED
#8 [api runtime 3/7] RUN useradd --create-home --uid 10001 --shell /usr/sbin/nologin app
#8 ...
#7 [api builder 2/4] RUN python -m venv /opt/venv
#7 ...
#8 [api runtime 3/7] RUN useradd --create-home --uid 10001 --shell /usr/sbin/nologin app
#8 DONE 12.9s
#7 [api builder 2/4] RUN python -m venv /opt/venv
#7 DONE 20.6s
#20 [api builder 3/4] COPY requirements.txt ./
#20 DONE 0.3s
#21 [api builder 4/4] RUN /opt/venv/bin/pip install --no-cache-dir --timeout 60 -r requirements.txt
#21 1.234 Collecting alembic==1.16.5 (from -r requirements.txt (line 5))
#21 1.409 Downloading alembic-1.16.5-py3-none-any.whl.metadata (7.3 kB)
#21 1.464 Collecting annotated-doc==0.0.5 (from -r requirements.txt (line 6))
#21 1.515 Downloading annotated_doc-0.0.5-py3-none-any.whl.metadata (6.5 kB)
#21 1.573 Collecting annotated-types==0.8.0 (from -r requirements.txt (line 7))
#21 1.623 Downloading annotated_types-0.8.0-py3-none-any.whl.metadata (15 kB)
#21 1.705 Collecting anyio==4.15.1 (from -r requirements.txt (line 8))
#21 1.752 Downloading anyio-4.15.1-py3-none-any.whl.metadata (4.7 kB)
#21 1.826 Collecting argon2-cffi==25.1.0 (from -r requirements.txt (line 9))
#21 1.875 Downloading argon2_cffi-25.1.0-py3-none-any.whl.metadata (4.1 kB)
#21 1.939 Collecting argon2-cffi-bindings==26.1.0 (from -r requirements.txt (line 10))
#21 1.988 Downloading argon2_cffi_bindings-26.1.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl.metadata (7.5 kB)
#21 2.127 Collecting asyncpg==0.30.0 (from -r requirements.txt (line 11))
#21 2.179 Downloading asyncpg-0.30.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (5.0 kB)
#21 2.375 Collecting cffi==2.1.1 (from -r requirements.txt (line 12))
#21 2.423 Downloading cffi-2.1.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.metadata (2.5 kB)
#21 2.488 Collecting click==8.5.0 (from -r requirements.txt (line 13))
#21 2.538 Downloading click-8.5.0-py3-none-any.whl.metadata (2.6 kB)
#21 2.658 Collecting fastapi==0.141.1 (from -r requirements.txt (line 14))
#21 2.707 Downloading fastapi-0.141.1-py3-none-any.whl.metadata (27 kB)
#21 2.977 Collecting greenlet==3.5.6 (from -r requirements.txt (line 15))
#21 3.026 Downloading greenlet-3.5.6-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.metadata (3.8 kB)
#21 3.081 Collecting h11==0.16.0 (from -r requirements.txt (line 16))
#21 3.131 Downloading h11-0.16.0-py3-none-any.whl.metadata (8.3 kB)
#21 3.194 Collecting idna==3.20 (from -r requirements.txt (line 17))
#21 3.242 Downloading idna-3.20-py3-none-any.whl.metadata (7.2 kB)
#21 3.307 Collecting Mako==1.4.3 (from -r requirements.txt (line 18))
#21 3.358 Downloading mako-1.4.3-py3-none-any.whl.metadata (2.9 kB)
#21 3.462 Collecting MarkupSafe==3.0.4 (from -r requirements.txt (line 19))
#21 3.511 Downloading markupsafe-3.0.4-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.metadata (2.7 kB)
#21 3.567 Collecting pycparser==3.11 (from -r requirements.txt (line 20))
#21 3.617 Downloading pycparser-3.11-py3-none-any.whl.metadata (8.2 kB)
#21 3.792 Collecting pydantic==2.14.0 (from -r requirements.txt (line 21))
#21 3.847 Downloading pydantic-2.14.0-py3-none-any.whl.metadata (131 kB)
#21 3.912 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 131.6/131.6 kB 2.1 MB/s eta 0:00:00
#21 4.822 Collecting pydantic_core==2.50.0 (from -r requirements.txt (line 22))
#21 4.877 Downloading pydantic_core-2.50.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (6.5 kB)
#21 4.963 Collecting redis==6.4.0 (from -r requirements.txt (line 23))
#21 5.016 Downloading redis-6.4.0-py3-none-any.whl.metadata (10 kB)
#21 5.503 Collecting SQLAlchemy==2.0.44 (from -r requirements.txt (line 24))
#21 5.558 Downloading sqlalchemy-2.0.44-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (9.5 kB)
#21 5.646 Collecting starlette==1.7.0 (from -r requirements.txt (line 25))
#21 5.695 Downloading starlette-1.7.0-py3-none-any.whl.metadata (6.6 kB)
#21 5.750 Collecting typing-inspection==0.4.4 (from -r requirements.txt (line 26))
#21 5.801 Downloading typing_inspection-0.4.4-py3-none-any.whl.metadata (2.6 kB)
#21 5.867 Collecting typing_extensions==4.16.0 (from -r requirements.txt (line 27))
#21 5.917 Downloading typing_extensions-4.16.0-py3-none-any.whl.metadata (3.3 kB)
#21 6.001 Collecting uvicorn==0.53.0 (from -r requirements.txt (line 28))
#21 6.050 Downloading uvicorn-0.53.0-py3-none-any.whl.metadata (6.6 kB)
#21 6.271 Downloading alembic-1.16.5-py3-none-any.whl (247 kB)
#21 6.328 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 247.4/247.4 kB 4.3 MB/s eta 0:00:00
#21 6.383 Downloading annotated_doc-0.0.5-py3-none-any.whl (5.3 kB)
#21 6.432 Downloading annotated_types-0.8.0-py3-none-any.whl (13 kB)
#21 6.480 Downloading anyio-4.15.1-py3-none-any.whl (132 kB)
#21 6.491 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 132.1/132.1 kB 12.8 MB/s eta 0:00:00
#21 6.541 Downloading argon2_cffi-25.1.0-py3-none-any.whl (14 kB)
#21 6.589 Downloading argon2_cffi_bindings-26.1.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl (26 kB)
#21 6.658 Downloading asyncpg-0.30.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.1 MB)
#21 6.974 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.1/3.1 MB 9.9 MB/s eta 0:00:00
#21 7.022 Downloading cffi-2.1.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (217 kB)
#21 7.040 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 217.8/217.8 kB 12.8 MB/s eta 0:00:00
#21 7.089 Downloading click-8.5.0-py3-none-any.whl (125 kB)
#21 7.100 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 125.3/125.3 kB 12.2 MB/s eta 0:00:00
#21 7.150 Downloading fastapi-0.141.1-py3-none-any.whl (131 kB)
#21 7.160 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 132.0/132.0 kB 14.4 MB/s eta 0:00:00
#21 7.214 Downloading greenlet-3.5.6-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (624 kB)
#21 7.272 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 624.4/624.4 kB 10.9 MB/s eta 0:00:00
#21 7.320 Downloading h11-0.16.0-py3-none-any.whl (37 kB)
#21 7.370 Downloading idna-3.20-py3-none-any.whl (69 kB)
#21 7.375 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 69.6/69.6 kB 19.8 MB/s eta 0:00:00
#21 7.423 Downloading mako-1.4.3-py3-none-any.whl (80 kB)
#21 7.429 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 80.2/80.2 kB 17.6 MB/s eta 0:00:00
#21 7.480 Downloading markupsafe-3.0.4-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (22 kB)
#21 7.527 Downloading pycparser-3.11-py3-none-any.whl (51 kB)
#21 7.532 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 51.2/51.2 kB 12.0 MB/s eta 0:00:00
#21 7.583 Downloading pydantic-2.14.0-py3-none-any.whl (487 kB)
#21 7.623 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 487.1/487.1 kB 12.7 MB/s eta 0:00:00
#21 7.670 Downloading pydantic_core-2.50.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.2 MB)
#21 7.906 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.2/2.2 MB 9.2 MB/s eta 0:00:00
#21 7.955 Downloading redis-6.4.0-py3-none-any.whl (279 kB)
#21 7.984 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 279.8/279.8 kB 10.1 MB/s eta 0:00:00
#21 8.036 Downloading sqlalchemy-2.0.44-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.3 MB)
#21 8.452 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.3/3.3 MB 8.0 MB/s eta 0:00:00
#21 8.502 Downloading starlette-1.7.0-py3-none-any.whl (78 kB)
#21 8.511 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 79.0/79.0 kB 10.4 MB/s eta 0:00:00
#21 8.559 Downloading typing_inspection-0.4.4-py3-none-any.whl (14 kB)
#21 8.606 Downloading typing_extensions-4.16.0-py3-none-any.whl (45 kB)
#21 8.610 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 45.6/45.6 kB 13.6 MB/s eta 0:00:00
#21 8.662 Downloading uvicorn-0.53.0-py3-none-any.whl (87 kB)
#21 8.669 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 87.1/87.1 kB 16.0 MB/s eta 0:00:00
#21 8.794 Installing collected packages: typing_extensions, redis, pycparser, MarkupSafe, idna, h11, greenlet, click, asyncpg, annotated-types, annotated-doc, uvicorn, typing-inspection, SQLAlchemy, pydantic_core, Mako, cffi, anyio, starlette, pydantic, argon2-cffi-bindings, alembic, fastapi, argon2-cffi
#21 11.77 Successfully installed Mako-1.4.3 MarkupSafe-3.0.4 SQLAlchemy-2.0.44 alembic-1.16.5 annotated-doc-0.0.5 annotated-types-0.8.0 anyio-4.15.1 argon2-cffi-25.1.0 argon2-cffi-bindings-26.1.0 asyncpg-0.30.0 cffi-2.1.1 click-8.5.0 fastapi-0.141.1 greenlet-3.5.6 h11-0.16.0 idna-3.20 pycparser-3.11 pydantic-2.14.0 pydantic_core-2.50.0 redis-6.4.0 starlette-1.7.0 typing-inspection-0.4.4 typing_extensions-4.16.0 uvicorn-0.53.0
#21 DONE 20.1s
#22 [api runtime 4/7] COPY --from=builder /opt/venv /opt/venv
#22 DONE 11.4s
#23 [api runtime 5/7] COPY --chown=app:app src/ ./src/
#23 DONE 0.7s
#24 [api runtime 6/7] COPY --chown=app:app alembic.ini ./
#24 DONE 0.5s
#25 [api runtime 7/7] COPY --chown=app:app migrations/ ./migrations/
#25 DONE 0.4s
#26 [api] exporting to image
#26 exporting layers
#26 exporting layers 5.7s done
#26 exporting manifest sha256:13238cdec831519696e999a3bdf3a3c7209331cbe4b28cfe9fb88871f1584bcc 0.1s done
#26 exporting config sha256:1908c88271261d26061bdaaa56321dc5ab3ac239c694fb9697371e15072815a1 0.1s done
#26 exporting attestation manifest sha256:1a2008c82b4d08f46cb74800653a6b1e3e6d428aec3b77d858d26ee80f81d738 0.1s done
#26 exporting manifest list sha256:984dd8cb75bfce4be643e72e70c1b61eb5170691b324f399f61d7095e0a036ba
#26 exporting manifest list sha256:984dd8cb75bfce4be643e72e70c1b61eb5170691b324f399f61d7095e0a036ba 0.1s done
#26 naming to docker.io/library/mtusi-messenger-lab2:2.0.0 0.0s done
#26 unpacking to docker.io/library/mtusi-messenger-lab2:2.0.0
#26 unpacking to docker.io/library/mtusi-messenger-lab2:2.0.0 1.2s done
#26 DONE 7.4s
#27 [api] resolving provenance for metadata file
#27 DONE 0.0s
api Built
migrate Built
real 1m35.220s
user 0m0.015s
sys 0m0.091s
$ time docker compose --env-file .env up -d
Network lab2-clean-clone_backend Creating
Network lab2-clean-clone_backend Created
Volume "lab2-clean-clone_valkeydata" Creating
Volume "lab2-clean-clone_valkeydata" Created
Volume "lab2-clean-clone_pgdata" Creating
Volume "lab2-clean-clone_pgdata" Created
Container lab2-clean-clone-valkey-1 Creating
Container lab2-clean-clone-postgres-1 Creating
Container lab2-clean-clone-valkey-1 Created
Container lab2-clean-clone-postgres-1 Created
Container lab2-clean-clone-migrate-1 Creating
Container lab2-clean-clone-migrate-1 Created
Container lab2-clean-clone-api-1 Creating
Container lab2-clean-clone-api-1 Created
Container lab2-clean-clone-valkey-1 Starting
Container lab2-clean-clone-postgres-1 Starting
Container lab2-clean-clone-valkey-1 Started
Container lab2-clean-clone-postgres-1 Started
Container lab2-clean-clone-postgres-1 Waiting
Container lab2-clean-clone-postgres-1 Healthy
Container lab2-clean-clone-migrate-1 Starting
Container lab2-clean-clone-migrate-1 Started
Container lab2-clean-clone-postgres-1 Waiting
Container lab2-clean-clone-valkey-1 Waiting
Container lab2-clean-clone-migrate-1 Waiting
Container lab2-clean-clone-valkey-1 Healthy
Container lab2-clean-clone-postgres-1 Healthy
Container lab2-clean-clone-migrate-1 Exited
Container lab2-clean-clone-api-1 Starting
Container lab2-clean-clone-api-1 Started
real 0m19.129s
user 0m0.015s
sys 0m0.090s
$ docker compose --env-file .env ps --all
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
lab2-clean-clone-api-1 mtusi-messenger-lab2:2.0.0 "python -m messenger" api 8 seconds ago Up Less than a second (health: starting) 127.0.0.1:8080->8080/tcp
lab2-clean-clone-migrate-1 mtusi-messenger-lab2:2.0.0 "alembic upgrade head" migrate 8 seconds ago Exited (0) Less than a second ago
lab2-clean-clone-postgres-1 postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 "docker-entrypoint.s…" postgres 19 seconds ago Up 7 seconds (healthy) 5432/tcp
lab2-clean-clone-valkey-1 valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab "tini -- docker-entr…" valkey 19 seconds ago Up 7 seconds (healthy) 6379/tcp
Ожидание готовности: опрос GET /health/ready раз в секунду
готов через 1 с (попытка 2)
$ curl -s http://127.0.0.1:8080/health/ready
{"status":"ok"}
$ python3 -m venv .venv && .venv/Scripts/python.exe -m pip install --quiet -r requirements-dev.txt
[notice] A new release of pip is available: 24.0 -> 26.2.1
[notice] To update, run: C:\Users\denis\AppData\Local\Temp\lab2-clean-clone\.venv\Scripts\python.exe -m pip install --upgrade pip
готово: Python 3.11.9
$ make check
python3 scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ make validate PYTHON=.venv/Scripts/python.exe
.venv/Scripts/python.exe scripts/validate_openapi.py
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
$ make test BASE_URL=http://127.0.0.1:8080
python3 tests/smoke.py --base-url "http://127.0.0.1:8080"
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
$ make test-persistence ACTION_SCRIPT=scripts/restart.cmd BASE_URL=http://127.0.0.1:8080
# Тест запускает хук через Popen([script]) без оболочки, поэтому на Windows это
# .cmd-двойник scripts/restart.sh: CreateProcess умеет запускать .exe/.cmd/.bat,
# но не .sh. Сам POSIX-хук проверен ниже.
python3 tests/resilience.py --mode persistence --action-script "scripts/restart.cmd" --base-url "http://127.0.0.1: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.
$ sh scripts/restart.sh # тот же хук из POSIX-оболочки
=== services before restart ===
=== restart api postgres valkey (grace 10s) ===
Container lab2-clean-clone-valkey-1 Restarting
Container lab2-clean-clone-api-1 Restarting
Container lab2-clean-clone-postgres-1 Restarting
Container lab2-clean-clone-valkey-1 Started
Container lab2-clean-clone-postgres-1 Started
Container lab2-clean-clone-api-1 Started
=== services after restart ===
running services: api postgres valkey
restart complete
(строки таблицы docker compose ps опущены, полная таблица есть в доказательстве 02)
Ожидание готовности после хука
готов через 1 с
$ time make student-test BASE_URL=http://127.0.0.1:8080 PYTHON="python3 -X utf8"
Учётные данные Basic не должны открывать /users/me: челлендж должен требовать Bearer. ... ok
Маршрут входа принимает только Basic; сессионный токен не создаёт сессию. ... ok
Тот же статус, тот же код, то же сообщение — и сопоставимый объём работы. ... ok
Заголовок из лабораторной 1 не работает: не даёт доступа и не переопределяет сессию. ... ok
128 кириллических кодовых точек — это 256 байт UTF-8, и они проходят без потерь. ... ok
Пароль длиннее 72 байт не усекается KDF. ... ok
11 и 129 кодовых точек отклоняются; 12 и 128 принимаются. ... ok
Basic разделяет только по первому двоеточию, остальное принадлежит паролю. ... ok
Отказ зависимости не должен выглядеть для супервизора смертью процесса. ... skipped 'задайте ALLOW_OUTAGE=1 для запуска: этот модуль останавливает контейнеры'
api пересоздан с SESSION_TTL_SECONDS=3, готов через 3.69s
Пересоздание API не выдаёт новые сессии и не продлевает старые. ... у токена, выданного до переключения, осталось 3596s из исходных 3600s
Хранилище никто не чистит: ключа просто больше нет. ... ключ исчез сам между двумя запросами: приложение не удаляет просроченные сессии
api пересоздан с SESSION_TTL_SECONDS=3600, готов через 3.66s
Повторные пробы должен обслуживать процесс, а не кешированное тело. ... ok
Сессии не в памяти процесса: перезапуск только API их сохраняет. ... ok
16 входов подряд должны дать 16 разных токенов: повтор ломал бы отзыв. ... ok
----------------------------------------------------------------------
Ran 79 tests in 28.511s
OK (skipped=3)
real 0m28.818s
user 0m0.000s
sys 0m0.015s
$ docker compose --env-file .env stop # безопасная остановка: тома остаются
Container lab2-clean-clone-api-1 Stopping
Container lab2-clean-clone-api-1 Stopped
Container lab2-clean-clone-valkey-1 Stopping
Container lab2-clean-clone-migrate-1 Stopping
Container lab2-clean-clone-migrate-1 Stopped
Container lab2-clean-clone-postgres-1 Stopping
Container lab2-clean-clone-postgres-1 Stopped
Container lab2-clean-clone-valkey-1 Stopped
api | Exited (0) Less than a second ago
migrate | Exited (0) 21 seconds ago
postgres | Exited (0) Less than a second ago
valkey | Exited (0) Less than a second ago
$ docker volume ls --filter name=lab2-clean-clone --format "{{.Name}}"
lab2-clean-clone_pgdata
lab2-clean-clone_valkeydata
$ docker compose --env-file .env start # данные на месте, стенд снова жив
Container lab2-clean-clone-valkey-1 Healthy
Container lab2-clean-clone-migrate-1 Exited
Container lab2-clean-clone-api-1 Starting
Container lab2-clean-clone-api-1 Started
health/ready: 200
$ docker compose --env-file .env down # удаляет контейнеры, но не тома
Container lab2-clean-clone-valkey-1 Removed
Network lab2-clean-clone_backend Removing
Network lab2-clean-clone_backend Removed
тома после down:
lab2-clean-clone_pgdata
lab2-clean-clone_valkeydata
$ docker compose --env-file .env down -v # намеренное удаление учебных данных
Volume lab2-clean-clone_valkeydata Removing
Volume lab2-clean-clone_pgdata Removed
Volume lab2-clean-clone_valkeydata Removed
тома после down -v:
(ни одного)
Порядок именно такой: stop → down → down -v. Первые две команды данные сохраняют,
и ни один хук перезапуска в репозитории их не вызывает: scripts/restart.sh делает
только restart. Удаление -v здесь стоит последним шагом, потому что это учебный
стенд на одноразовой копии репозитория, а не рабочие данные.
$ cd /c/Users/denis/Desktop/HighLoad/mtusi2026lab2 && docker compose start # возвращаем основной стенд
Container mtusi2026lab2-postgres-1 Healthy
Container mtusi2026lab2-migrate-1 Exited
Container mtusi2026lab2-api-1 Starting
Container mtusi2026lab2-api-1 Started
основной стенд: готов через 2 с
Копия после прогона удалена: C:/Users/denis/AppData/Local/Temp/lab2-clean-clone
== 12б: повторный прогон из чистого clone после исправления валидации ==
date: 2026-10-23T19:25:46Z (UTC)
host: Windows 10 Pro 19045, x64, Git Bash; Docker 28.0.1 (Docker Desktop, WSL2)
Зачем: после транскрипта выше добавлены три регрессионных теста — пароль только из
пробельных символов и U+0000 в сохраняемых строках дают 400 invalid_request, — а
503 unavailable сужен до отказов соединения и пула. Ниже тот же сценарий целиком
на итоговом дереве: снова копия без игнорируемых Git файлов, сборка без кэша,
пустой том и все проверки. Инфраструктура и последовательность команд не менялись.
$ docker compose stop # в основном репозитории: освобождаем порт 8080 и имя проекта
Container mtusi2026lab2-api-1 Stopping
Container mtusi2026lab2-api-1 Stopped
Container mtusi2026lab2-migrate-1 Stopping
Container mtusi2026lab2-valkey-1 Stopping
Container mtusi2026lab2-migrate-1 Stopped
Container mtusi2026lab2-postgres-1 Stopping
Container mtusi2026lab2-postgres-1 Stopped
Container mtusi2026lab2-valkey-1 Stopped
$ mkdir -p /c/Users/denis/AppData/Local/Temp/lab2-clean-clone && tar -c --exclude=.git --exclude=.venv --exclude=secrets \
--exclude=.env --exclude=__pycache__ --exclude="*.pyc" . | tar -x -C /c/Users/denis/AppData/Local/Temp/lab2-clean-clone
скопировано: 98 файлов
$ cd /c/Users/denis/AppData/Local/Temp/lab2-clean-clone
$ cp .env.example .env && sh scripts/bootstrap-secrets.sh
create secrets/postgres_password
create secrets/cursor_secret
create secrets/cache_url
create secrets/database_url
done: /c/Users/denis/AppData/Local/Temp/lab2-clean-clone/secrets
next: docker compose up -d --build
$ docker compose --env-file .env config --quiet # валидность до сборки
config: OK
$ time docker compose --env-file .env build --no-cache
#27 [api] resolving provenance for metadata file
#27 DONE 0.0s
api Built
migrate Built
real 2m49.033s
user 0m0.030s
sys 0m0.076s
$ time docker compose --env-file .env up -d
$ time docker compose --env-file .env up -d
Network lab2-clean-clone_backend Creating
Network lab2-clean-clone_backend Created
Volume "lab2-clean-clone_pgdata" Creating
Volume "lab2-clean-clone_pgdata" Created
Volume "lab2-clean-clone_valkeydata" Creating
Volume "lab2-clean-clone_valkeydata" Created
Container lab2-clean-clone-postgres-1 Creating
Container lab2-clean-clone-valkey-1 Creating
Container lab2-clean-clone-postgres-1 Created
Container lab2-clean-clone-migrate-1 Creating
Container lab2-clean-clone-valkey-1 Created
Container lab2-clean-clone-migrate-1 Created
Container lab2-clean-clone-api-1 Creating
Container lab2-clean-clone-api-1 Created
Container lab2-clean-clone-postgres-1 Starting
Container lab2-clean-clone-valkey-1 Starting
Container lab2-clean-clone-valkey-1 Started
Container lab2-clean-clone-postgres-1 Started
Container lab2-clean-clone-postgres-1 Waiting
Container lab2-clean-clone-postgres-1 Healthy
Container lab2-clean-clone-migrate-1 Starting
Container lab2-clean-clone-migrate-1 Started
Container lab2-clean-clone-valkey-1 Waiting
Container lab2-clean-clone-migrate-1 Waiting
Container lab2-clean-clone-postgres-1 Waiting
Container lab2-clean-clone-valkey-1 Healthy
Container lab2-clean-clone-postgres-1 Healthy
Container lab2-clean-clone-migrate-1 Exited
Container lab2-clean-clone-api-1 Starting
Container lab2-clean-clone-api-1 Started
real 0m7.912s
user 0m0.000s
sys 0m0.106s
Ожидание готовности: опрос GET /health/ready раз в секунду
готов через 1 с
$ curl -s http://127.0.0.1:8080/health/ready
{"status":"ok"}
$ docker compose --env-file .env ps --all
lab2-clean-clone-api-1 mtusi-messenger-lab2:2.0.0 "python -m messenger" api 8 seconds ago Up 1 second (health: starting) 127.0.0.1:8080->8080/tcp
lab2-clean-clone-migrate-1 mtusi-messenger-lab2:2.0.0 "alembic upgrade head" migrate 8 seconds ago Exited (0) 1 second ago
lab2-clean-clone-postgres-1 postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 "docker-entrypoint.s…" postgres 9 seconds ago Up 8 seconds (healthy) 5432/tcp
lab2-clean-clone-valkey-1 valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab "tini -- docker-entr…" valkey 9 seconds ago Up 8 seconds (healthy) 6379/tcp
$ python3 -m venv .venv && .venv/Scripts/python.exe -m pip install --quiet -r requirements-dev.txt
sys 0m0.015s
Python 3.11.9
$ make check
python3 scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ make validate PYTHON=.venv/Scripts/python.exe
.venv/Scripts/python.exe scripts/validate_openapi.py
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
$ make test BASE_URL=http://127.0.0.1:8080
python3 tests/smoke.py --base-url "http://127.0.0.1:8080"
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
$ make test-persistence ACTION_SCRIPT=scripts/restart.cmd BASE_URL=http://127.0.0.1:8080
python3 tests/resilience.py --mode persistence --action-script "scripts/restart.cmd" --base-url "http://127.0.0.1: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.
$ sh scripts/restart.sh # тот же хук из POSIX-оболочки
lab2-clean-clone-api-1 mtusi-messenger-lab2:2.0.0 "python -m messenger" api 59 seconds ago Up Less than a second (health: starting) 127.0.0.1:8080->8080/tcp
lab2-clean-clone-postgres-1 postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 "docker-entrypoint.s…" postgres About a minute ago Up Less than a second (health: starting) 5432/tcp
lab2-clean-clone-valkey-1 valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab "tini -- docker-entr…" valkey About a minute ago Up Less than a second (health: starting) 6379/tcp
running services: api postgres valkey
restart complete
$ time make student-test BASE_URL=http://127.0.0.1:8080 PYTHON="python3 -X utf8"
----------------------------------------------------------------------
Ran 82 tests in 30.852s
OK (skipped=3)
real 0m31.300s
user 0m0.015s
sys 0m0.000s
Полный построчный вывод этих же 82 тестов — в доказательстве 03 (тот же запуск
на итоговом дереве; здесь только итог, чтобы не дублировать 130 строк).
$ docker compose --env-file .env stop # безопасная остановка: тома остаются
Container lab2-clean-clone-valkey-1 Stopping
Container lab2-clean-clone-migrate-1 Stopping
Container lab2-clean-clone-migrate-1 Stopped
Container lab2-clean-clone-postgres-1 Stopping
Container lab2-clean-clone-postgres-1 Stopped
Container lab2-clean-clone-valkey-1 Stopped
$ docker volume ls --filter name=lab2-clean-clone --format "{{.Name}}"
lab2-clean-clone_pgdata
lab2-clean-clone_valkeydata
$ docker compose --env-file .env start # данные на месте, стенд снова жив
$ docker compose --env-file .env start
Container lab2-clean-clone-valkey-1 Starting
Container lab2-clean-clone-postgres-1 Starting
Container lab2-clean-clone-valkey-1 Started
Container lab2-clean-clone-postgres-1 Started
Container lab2-clean-clone-postgres-1 Waiting
Container lab2-clean-clone-postgres-1 Healthy
Container lab2-clean-clone-migrate-1 Starting
Container lab2-clean-clone-migrate-1 Started
Container lab2-clean-clone-migrate-1 Waiting
Container lab2-clean-clone-postgres-1 Waiting
Container lab2-clean-clone-valkey-1 Waiting
Container lab2-clean-clone-valkey-1 Healthy
Container lab2-clean-clone-postgres-1 Healthy
Container lab2-clean-clone-migrate-1 Exited
Container lab2-clean-clone-api-1 Starting
Container lab2-clean-clone-api-1 Started
$ docker compose --env-file .env ps --all
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
lab2-clean-clone-api-1 mtusi-messenger-lab2:2.0.0 "python -m messenger" api 27 seconds ago Up Less than a second (health: starting) 127.0.0.1:8080->8080/tcp
lab2-clean-clone-migrate-1 mtusi-messenger-lab2:2.0.0 "alembic upgrade head" migrate About a minute ago Exited (0) Less than a second ago
lab2-clean-clone-postgres-1 postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 "docker-entrypoint.s…" postgres About a minute ago Up 7 seconds (healthy) 5432/tcp
lab2-clean-clone-valkey-1 valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab "tini -- docker-entr…" valkey About a minute ago Up 7 seconds (healthy) 6379/tcp
$ docker compose --env-file .env down # удаляет контейнеры, но не тома
$ docker compose --env-file .env down
Container lab2-clean-clone-api-1 Stopping
Container lab2-clean-clone-api-1 Stopped
Container lab2-clean-clone-api-1 Removing
Container lab2-clean-clone-api-1 Removed
Container lab2-clean-clone-valkey-1 Stopping
Container lab2-clean-clone-migrate-1 Stopping
Container lab2-clean-clone-migrate-1 Stopped
Container lab2-clean-clone-migrate-1 Removing
Container lab2-clean-clone-migrate-1 Removed
Container lab2-clean-clone-postgres-1 Stopping
Container lab2-clean-clone-valkey-1 Stopped
Container lab2-clean-clone-valkey-1 Removing
Container lab2-clean-clone-postgres-1 Stopped
Container lab2-clean-clone-postgres-1 Removing
Container lab2-clean-clone-valkey-1 Removed
Container lab2-clean-clone-postgres-1 Removed
Network lab2-clean-clone_backend Removing
Network lab2-clean-clone_backend Removed
$ docker compose --env-file .env down -v # намеренное удаление учебных данных
$ docker compose --env-file .env down -v
Volume lab2-clean-clone_valkeydata Removing
Volume lab2-clean-clone_pgdata Removing
Volume lab2-clean-clone_valkeydata Removed
Volume lab2-clean-clone_pgdata Removed
$ docker volume ls --filter name=lab2-clean-clone --format "{{.Name}}"
(пусто)
$ cd /c/Users/denis/Desktop/HighLoad/mtusi2026lab2 && docker compose start # возвращаем основной стенд
$ docker compose ps --format "{{.Service}} {{.State}} {{.Health}}"
api running healthy
postgres running healthy
valkey running healthy
$ curl -s http://127.0.0.1:8080/health/ready
{"status":"ok"}
+58
View File
@@ -0,0 +1,58 @@
"""Окружение Alembic: URL базы берётся из тех же переменных, что и у приложения."""
from __future__ import annotations
import asyncio
from logging.config import fileConfig
from alembic import context
from sqlalchemy import pool
from sqlalchemy.ext.asyncio import async_engine_from_config
from messenger.config import database_url_from_env
from messenger.schema import METADATA
config = context.config
if config.config_file_name is not None:
fileConfig(config.config_file_name)
# Сравнение идёт ровно с теми объектами, по которым работает приложение:
# расхождение между схемой и миграциями ловится на `alembic check`.
target_metadata = METADATA
def run_migrations_offline() -> None:
"""Режим без подключения: печатает SQL миграции, удобен для ревью."""
context.configure(
url=database_url_from_env(),
target_metadata=target_metadata,
literal_binds=True,
compare_type=True,
dialect_opts={"paramstyle": "named"},
)
with context.begin_transaction():
context.run_migrations()
def _run_migrations(connection) -> None:
context.configure(connection=connection, target_metadata=target_metadata, compare_type=True)
with context.begin_transaction():
context.run_migrations()
async def run_migrations_online() -> None:
"""Драйвер асинхронный (asyncpg), поэтому миграции идут через run_sync."""
section = config.get_section(config.config_ini_section, {})
section["sqlalchemy.url"] = database_url_from_env()
engine = async_engine_from_config(section, prefix="sqlalchemy.", poolclass=pool.NullPool)
try:
async with engine.connect() as connection:
await connection.run_sync(_run_migrations)
finally:
await engine.dispose()
if context.is_offline_mode():
run_migrations_offline()
else:
asyncio.run(run_migrations_online())
+24
View File
@@ -0,0 +1,24 @@
"""${message}
Revision ID: ${up_revision}
Revises: ${down_revision | comma,n}
Create Date: ${create_date}
"""
from __future__ import annotations
from alembic import op
import sqlalchemy as sa
${imports if imports else ""}
revision = ${repr(up_revision)}
down_revision = ${repr(down_revision)}
branch_labels = ${repr(branch_labels)}
depends_on = ${repr(depends_on)}
def upgrade() -> None:
${upgrades if upgrades else "pass"}
def downgrade() -> None:
${downgrades if downgrades else "pass"}
+103
View File
@@ -0,0 +1,103 @@
"""Начальная схема: пользователи, чаты, участники и сообщения
Revision ID: 0001_initial_schema
Revises:
Create Date: 2026-10-11
DDL написан вручную и повторяет src/messenger/schema.py: имена ограничений
и индексов совпадают, поэтому `alembic check` не находит расхождений между
схемой в базе и описанием, по которому работают запросы.
"""
from __future__ import annotations
import sqlalchemy as sa
from alembic import op
from sqlalchemy.dialects import postgresql
revision = "0001_initial_schema"
down_revision = None
branch_labels = None
depends_on = None
def upgrade() -> None:
op.create_table(
"users",
sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("username", sa.Text(), nullable=False),
sa.Column("display_name", sa.Text(), nullable=False),
sa.Column("password_hash", sa.Text(), nullable=False),
sa.Column(
"created_at",
postgresql.TIMESTAMP(timezone=True),
server_default=sa.text("now()"),
nullable=False,
),
sa.CheckConstraint(
"char_length(display_name) BETWEEN 1 AND 100", name="ck_users_display_name_length"
),
sa.CheckConstraint(r"username ~ '^[a-z0-9_]{3,32}$'", name="ck_users_username_format"),
sa.PrimaryKeyConstraint("id"),
sa.UniqueConstraint("username", name="uq_users_username"),
)
op.create_table(
"chats",
sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("title", sa.Text(), nullable=False),
sa.Column(
"created_at",
postgresql.TIMESTAMP(timezone=True),
server_default=sa.text("now()"),
nullable=False,
),
sa.CheckConstraint("char_length(title) BETWEEN 1 AND 100", name="ck_chats_title_length"),
sa.PrimaryKeyConstraint("id"),
)
op.create_table(
"chat_members",
sa.Column("chat_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("user_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.ForeignKeyConstraint(
["chat_id"], ["chats.id"], name="fk_chat_members_chat", ondelete="CASCADE"
),
sa.ForeignKeyConstraint(
["user_id"], ["users.id"], name="fk_chat_members_user", ondelete="RESTRICT"
),
sa.PrimaryKeyConstraint("chat_id", "user_id"),
)
op.create_index("ix_chat_members_user_id_chat_id", "chat_members", ["user_id", "chat_id"])
op.create_table(
"messages",
sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("chat_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("sender_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("text", sa.Text(), nullable=False),
sa.Column(
"created_at",
postgresql.TIMESTAMP(timezone=True),
server_default=sa.text("now()"),
nullable=False,
),
sa.CheckConstraint(
"text <> '' AND char_length(text) <= 4000", name="ck_messages_text_length"
),
sa.ForeignKeyConstraint(["chat_id"], ["chats.id"], name="fk_messages_chat", ondelete="CASCADE"),
sa.ForeignKeyConstraint(
["sender_id"], ["users.id"], name="fk_messages_sender", ondelete="RESTRICT"
),
sa.PrimaryKeyConstraint("id"),
)
# Порядок истории (created_at, id) и keyset-предикат обслуживает один индекс.
op.create_index("ix_messages_chat_id_created_at_id", "messages", ["chat_id", "created_at", "id"])
def downgrade() -> None:
op.drop_index("ix_messages_chat_id_created_at_id", table_name="messages")
op.drop_table("messages")
op.drop_index("ix_chat_members_user_id_chat_id", table_name="chat_members")
op.drop_table("chat_members")
op.drop_table("chats")
op.drop_table("users")
+28
View File
@@ -0,0 +1,28 @@
# Рантайм-зависимости лабораторной 2: точное замыкание (top-level и транзитивные),
# получено `pip freeze` после установки на Python 3.11.9:
# pip install fastapi==0.141.1 uvicorn==0.53.0 "sqlalchemy[asyncio]==2.0.44" \
# asyncpg==0.30.0 alembic==1.16.5 redis==6.4.0 argon2-cffi==25.1.0
alembic==1.16.5
annotated-doc==0.0.5
annotated-types==0.8.0
anyio==4.15.1
argon2-cffi==25.1.0
argon2-cffi-bindings==26.1.0
asyncpg==0.30.0
cffi==2.1.1
click==8.5.0
fastapi==0.141.1
greenlet==3.5.6
h11==0.16.0
idna==3.20
Mako==1.4.3
MarkupSafe==3.0.4
pycparser==3.11
pydantic==2.14.0
pydantic_core==2.50.0
redis==6.4.0
SQLAlchemy==2.0.44
starlette==1.7.0
typing-inspection==0.4.4
typing_extensions==4.16.0
uvicorn==0.53.0
+37
View File
@@ -0,0 +1,37 @@
#!/bin/sh
# Create local Compose secrets under secrets/ (gitignored, never printed).
# Existing files are never overwritten, so rerunning the script is safe.
# Usage: sh scripts/bootstrap-secrets.sh
set -eu
root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
dir="$root/secrets"
# Files are created with mode 600: group and other have no access.
umask 077
mkdir -p "$dir"
random_hex() {
head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n'
}
# write <name> <value>: keeps the current file if it already has content.
write() {
name=$1
value=$2
if [ -s "$dir/$name" ]; then
printf 'keep secrets/%s\n' "$name"
return 0
fi
printf '%s\n' "$value" > "$dir/$name"
printf 'create secrets/%s\n' "$name"
}
write postgres_password "$(random_hex)"
write cursor_secret "$(random_hex)"
write cache_url 'redis://valkey:6379/0'
# The password is hex, so the URL needs no percent-encoding.
write database_url "postgresql+asyncpg://messenger:$(cat "$dir/postgres_password")@postgres:5432/messenger"
printf 'done: %s\n' "$dir"
printf 'next: docker compose up -d --build\n'
+75
View File
@@ -0,0 +1,75 @@
@echo off
rem Windows-native twin of scripts/restart.sh, same docker compose subcommands.
rem
rem Why it exists: tests/resilience.py launches the hook with Popen([script]) and
rem no shell. On native Windows that only works for .exe/.cmd/.bat - a .sh file
rem fails with WinError 193 (%1 is not a valid Win32 application). Linux and WSL
rem hosts use scripts/restart.sh instead; see REPORT.md.
rem
rem The hook restarts the API and every state store it depends on, keeping the
rem schema and the data: no volumes removed, no flush, no re-seed. Sessions live
rem in Valkey with AOF, so the same token keeps working after the restart.
rem Usage: scripts\restart.cmd
setlocal enableextensions enabledelayedexpansion
cd /d "%~dp0.."
rem Docker CLI finds its plugins in %ProgramW6432%\Docker\cli-plugins. The
rem environment `make` builds under MSYS drops that variable, and then every
rem `docker compose` call is answered with "unknown command: docker compose".
rem Restoring it keeps the hook working whichever shell started the test.
if not defined PROGRAMW6432 for %%d in ("%SystemDrive%\Program Files") do (
if exist "%%~d\Docker\cli-plugins" set "PROGRAMW6432=%%~d"
)
where docker >nul 2>&1
if errorlevel 1 (
echo docker is required 1>&2
exit /b 2
)
echo === services before restart ===
docker compose ps
if errorlevel 1 exit /b 1
echo === restart api postgres valkey (grace 10s) ===
docker compose restart --timeout 10 api postgres valkey
if errorlevel 1 (
rem One retry: a transient daemon error here leaves the stack in an unknown
rem state, and repeating the operator action is the natural next step.
echo restart attempt failed, retrying once 1>&2
ping -n 4 127.0.0.1 >nul
docker compose restart --timeout 10 api postgres valkey
if errorlevel 1 exit /b 1
)
echo === services after restart ===
docker compose ps
if errorlevel 1 exit /b 1
rem Every service must be reported running; order is not assumed, and the check
rem is retried because docker needs a moment to publish the new container state.
rem `timeout` is avoided on purpose: it fails without a console, and the caller
rem runs this hook with redirected output.
set "remaining=30"
:verify
set "missing="
for %%r in (api postgres valkey) do (
set "found="
for /f "delims=" %%s in ('docker compose ps --status running --services') do (
if /i "%%s"=="%%r" set "found=1"
)
if not defined found set "missing=!missing! %%r"
)
if not defined missing goto verified
if "!remaining!"=="0" goto still_down
set /a remaining-=1
ping -n 2 127.0.0.1 >nul
goto verify
:still_down
echo services not running after 30s:!missing! 1>&2
exit /b 1
:verified
echo restart complete
exit /b 0
+39
View File
@@ -0,0 +1,39 @@
#!/bin/sh
# Restart the API and every state store it depends on, keeping schema and data.
#
# Published as the action script for `make test-persistence`: it must not remove
# volumes, must not flush state and must not re-seed anything. Sessions live in
# Valkey with AOF, so the same token keeps working after the restart.
# Usage: sh scripts/restart.sh
set -eu
root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
cd "$root"
if ! docker compose version >/dev/null 2>&1; then
printf 'docker compose is required\n' >&2
exit 2
fi
printf '=== services before restart ===\n'
docker compose ps
printf '=== restart api postgres valkey (grace 10s) ===\n'
docker compose restart --timeout 10 api postgres valkey
printf '=== services after restart ===\n'
docker compose ps
running=$(docker compose ps --status running --services | sort | tr '\n' ' ')
printf 'running services: %s\n' "$running"
for service in api postgres valkey; do
case " $running " in
*" $service "*) ;;
*)
printf 'service %s is not running\n' "$service" >&2
exit 1
;;
esac
done
printf 'restart complete\n'
+5
View File
@@ -0,0 +1,5 @@
"""Мессенджер на PostgreSQL и Valkey: лабораторная 2 курса HighLoad (MTUSI)."""
__all__ = ["__version__"]
__version__ = "2.0.0"
+38
View File
@@ -0,0 +1,38 @@
"""Точка входа: `python -m messenger` (в контейнере — PID 1)."""
from __future__ import annotations
import sys
import uvicorn
from .app import create_app
from .config import Config, ConfigError
def main() -> int:
try:
config = Config.from_env()
except ConfigError as exc:
print(f"config error: {exc}", file=sys.stderr)
return 2
uvicorn.run(
create_app(config),
host=config.host,
port=config.port,
# Свой формат логов: uvicorn не пишет access-лог с query-строкой.
log_config=None,
access_log=False,
# Верхняя граница ожидания активных запросов при остановке.
timeout_graceful_shutdown=config.graceful_shutdown_seconds,
# Один процесс: лимиты пула соединений заданы на процесс, а не на весь стенд.
workers=1,
server_header=False,
date_header=False,
proxy_headers=False,
)
return 0
if __name__ == "__main__":
raise SystemExit(main())
+16
View File
@@ -0,0 +1,16 @@
"""Правила доступа: чужой объект неотличим от отсутствующего (404, не 403)."""
from __future__ import annotations
from uuid import UUID
from .domain import ChatRecord, UserRecord
from .errors import not_found
from .repository import Repository
async def visible_chat(repository: Repository, chat_id: UUID, user: UserRecord) -> ChatRecord:
"""Возвращает чат, если пользователь его участник, иначе 404."""
chat = await repository.chat_for_member(chat_id, user.id)
if chat is None:
raise not_found("Чат не найден")
return chat
+126
View File
@@ -0,0 +1,126 @@
"""Сборка ASGI-приложения: жизненный цикл, обработчики ошибок, маршруты."""
from __future__ import annotations
import asyncio
import logging
from contextlib import asynccontextmanager
from typing import AsyncIterator, Awaitable, Callable
from fastapi import FastAPI
from . import __version__
from .config import Config
from .cursor import CursorCodec
from .db import Database
from .errorhandlers import register_error_handlers
from .logging_setup import configure_logging, log
from .middleware import RequestContextMiddleware
from .routers import auth, chats, health, messages, users
from .sessions import RedisSessionStore
ROUTERS = (health.router, auth.router, users.router, chats.router, messages.router)
async def _release(
logger: logging.Logger, resource: str, closer: Callable[[], Awaitable[None]]
) -> None:
"""Освобождает ресурс: отказ зависимости при остановке не должен мешать выходу."""
try:
await closer()
except Exception as exc:
log(
logger,
logging.WARNING,
"release_failed",
exc_info=exc,
resource=resource,
error=type(exc).__name__,
)
def build_fastapi(config: Config, logger: logging.Logger) -> FastAPI:
"""Создаёт приложение FastAPI с обработчиками ошибок и маршрутами."""
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
# Клиенты создаются здесь, но к зависимостям не подключаются: старт не
# должен падать, если PostgreSQL или Valkey поднимаются одновременно с API.
# За трафик отвечает готовность, а не перезапуск контейнера.
database = Database(config)
sessions = RedisSessionStore(
config.cache_url, config.session_ttl_seconds, config.cache_timeout_seconds
)
app.state.database = database
app.state.sessions = sessions
app.state.cursors = CursorCodec(config.cursor_secret)
app.state.draining = False
log(
logger,
logging.INFO,
"startup",
version=__version__,
host=config.host,
port=config.port,
shutdown_budget_seconds=config.shutdown_budget_seconds,
storage="postgresql",
session_store=config.session_store,
session_ttl_seconds=config.session_ttl_seconds,
db_pool_size=config.db_pool_size,
db_max_overflow=config.db_max_overflow,
db_pool_timeout_seconds=config.db_pool_timeout_seconds,
db_connect_timeout_seconds=config.db_connect_timeout_seconds,
db_command_timeout_seconds=config.db_command_timeout_seconds,
db_statement_timeout_ms=config.db_statement_timeout_ms,
cache_timeout_seconds=config.cache_timeout_seconds,
)
if config.binds_to_loopback:
# Bind на loopback внутри контейнера не виден через published port.
log(
logger,
logging.WARNING,
"loopback_bind",
detail="bind на loopback недоступен через published port контейнера",
)
try:
yield
finally:
app.state.draining = True
log(
logger,
logging.INFO,
"shutdown_begin",
drain_seconds=config.shutdown_drain_seconds,
note="слушающий сокет уже закрыт: новые соединения не принимаются",
)
if config.shutdown_drain_seconds > 0:
# Окно управляемого снятия с балансировки: процесс ещё жив,
# но трафик на него уже не идёт.
await asyncio.sleep(config.shutdown_drain_seconds)
await _release(logger, "sessions", sessions.close)
await _release(logger, "database", database.dispose)
app.state.draining = False
log(logger, logging.INFO, "shutdown_complete")
app = FastAPI(
title="MTUSI Messenger — лабораторная 2",
version=__version__,
lifespan=lifespan,
# Источник истины — contracts/openapi.json: свои /docs и /openapi.json не публикуются.
docs_url=None,
redoc_url=None,
openapi_url=None,
)
register_error_handlers(app, logger)
for router in ROUTERS:
app.include_router(router)
return app
def create_app(
config: Config | None = None,
logger: logging.Logger | None = None,
) -> RequestContextMiddleware:
"""Создаёт приложение; разбор окружения идёт здесь, а не при импорте модуля."""
config = Config.from_env() if config is None else config
logger = configure_logging(config.log_level, config.env) if logger is None else logger
return RequestContextMiddleware(build_fastapi(config, logger), logger)
+263
View File
@@ -0,0 +1,263 @@
"""Конфигурация процесса: значения приходят только из переменных окружения.
Секреты читаются либо напрямую (`NAME`), либо из файла (`NAME_FILE`) — второй
вариант используется стендом Compose и Docker secrets. Значения секретов
никогда не попадают в текст ошибки.
"""
from __future__ import annotations
import os
from dataclasses import dataclass
from pathlib import Path
from typing import Mapping
DEFAULT_HOST = "0.0.0.0"
DEFAULT_PORT = 8080
DEFAULT_ENV = "lab"
DEFAULT_LOG_LEVEL = "info"
DEFAULT_GRACEFUL_SHUTDOWN_SECONDS = 5
DEFAULT_SHUTDOWN_DRAIN_SECONDS = 0.0
MAX_SHUTDOWN_BUDGET_SECONDS = 10
DEFAULT_SESSION_TTL_SECONDS = 3600
MIN_SESSION_TTL_SECONDS = 1
MAX_SESSION_TTL_SECONDS = 86400
DEFAULT_DB_POOL_SIZE = 5
MAX_DB_POOL_SIZE = 32
DEFAULT_DB_MAX_OVERFLOW = 5
MAX_DB_MAX_OVERFLOW = 32
# Бюджет отказа: недоступный PostgreSQL обязан превращаться в 503 быстрее, чем
# клиент успеет отправить повтор. Установление соединения ограничено отдельно от
# запроса, потому что при остановленном контейнере тормозит именно разрешение
# имени `postgres` встроенным DNS Docker (замеры — в отчёте и в evidence/06).
DEFAULT_DB_POOL_TIMEOUT_SECONDS = 2.0
MAX_DB_POOL_TIMEOUT_SECONDS = 30.0
DEFAULT_DB_CONNECT_TIMEOUT_SECONDS = 1.5
MAX_DB_CONNECT_TIMEOUT_SECONDS = 30.0
DEFAULT_DB_COMMAND_TIMEOUT_SECONDS = 2.5
MAX_DB_COMMAND_TIMEOUT_SECONDS = 60.0
# Серверный предел строже клиентского: ошибку выдаёт PostgreSQL, а не asyncpg.
DEFAULT_DB_STATEMENT_TIMEOUT_MS = 2000
MAX_DB_STATEMENT_TIMEOUT_MS = 60000
DEFAULT_CACHE_TIMEOUT_SECONDS = 1.0
MAX_CACHE_TIMEOUT_SECONDS = 10.0
ENVIRONMENTS = ("lab", "dev", "prod")
LOG_LEVELS = ("debug", "info", "warning", "error")
# Хранилище сессий: в этой работе реализован только вариант с Valkey/Redis.
# Значение SESSION_STORE=postgres из .env.example стенду не соответствует —
# соответствие переменных описано в REPORT.md.
SESSION_STORES = ("redis",)
DEFAULT_SESSION_STORE = "redis"
DATABASE_URL_SCHEME = "postgresql+asyncpg://"
CACHE_URL_SCHEMES = ("redis://", "rediss://", "unix://")
LOOPBACK_HOSTS = ("127.0.0.1", "localhost", "::1")
class ConfigError(RuntimeError):
"""Некорректная конфигурация. Текст не раскрывает значений переменных."""
def _choice(environ: Mapping[str, str], name: str, default: str, allowed: tuple[str, ...]) -> str:
value = environ.get(name, default).strip().lower()
if value not in allowed:
raise ConfigError(f"{name} must be one of: {', '.join(allowed)}")
return value
def _integer(environ: Mapping[str, str], name: str, default: int, minimum: int, maximum: int) -> int:
raw = environ.get(name, "").strip()
if not raw:
return default
try:
value = int(raw)
except ValueError:
raise ConfigError(f"{name} must be an integer") from None
if not minimum <= value <= maximum:
raise ConfigError(f"{name} must be within {minimum}..{maximum}")
return value
def _seconds(environ: Mapping[str, str], name: str, default: float, maximum: float) -> float:
raw = environ.get(name, "").strip()
if not raw:
return default
try:
value = float(raw)
except ValueError:
raise ConfigError(f"{name} must be a number of seconds") from None
if not 0.0 <= value <= maximum:
raise ConfigError(f"{name} must be within 0..{maximum}")
return value
def _secret(environ: Mapping[str, str], name: str) -> str | None:
"""Читает секрет из `NAME` или из файла `NAME_FILE`; иначе возвращает None."""
direct = environ.get(name, "").strip()
path = environ.get(f"{name}_FILE", "").strip()
if direct and path:
raise ConfigError(f"{name} and {name}_FILE must not be set together")
if direct:
return direct
if not path:
return None
try:
value = Path(path).read_text(encoding="utf-8").strip()
except OSError:
raise ConfigError(f"{name}_FILE must point to a readable file") from None
if not value:
raise ConfigError(f"{name}_FILE must not be empty")
return value
def _required_secret(environ: Mapping[str, str], name: str) -> str:
value = _secret(environ, name)
if value is None:
raise ConfigError(f"{name} or {name}_FILE is required")
return value
def _checked_url(value: str, *, name: str, schemes: tuple[str, ...]) -> str:
"""Схема проверяется до создания клиента: ошибка видна на старте процесса."""
if not value.startswith(schemes):
raise ConfigError(f"{name} must start with one of: {', '.join(schemes)}")
return value
def database_url_from_env(environ: Mapping[str, str] | None = None) -> str:
"""URL базы из окружения (`DATABASE_URL` или `DATABASE_URL_FILE`).
Отдельная функция нужна миграциям: Alembic не должен требовать переменные
Valkey и настройки сессий, которые к схеме отношения не имеют.
"""
source: Mapping[str, str] = os.environ if environ is None else environ
return _checked_url(
_required_secret(source, "DATABASE_URL"),
name="DATABASE_URL",
schemes=(DATABASE_URL_SCHEME,),
)
@dataclass(frozen=True)
class Config:
"""Разобранная конфигурация процесса."""
host: str
port: int
env: str
log_level: str
graceful_shutdown_seconds: int
shutdown_drain_seconds: float
database_url: str
cache_url: str
session_store: str
session_ttl_seconds: int
db_pool_size: int
db_max_overflow: int
db_pool_timeout_seconds: float
db_connect_timeout_seconds: float
db_command_timeout_seconds: float
db_statement_timeout_ms: int
cache_timeout_seconds: float
cursor_secret: bytes | None
def __post_init__(self) -> None:
"""Сумма остановки не должна превышать требование лабы."""
if self.shutdown_budget_seconds > MAX_SHUTDOWN_BUDGET_SECONDS:
raise ConfigError(
"GRACEFUL_SHUTDOWN_SECONDS + SHUTDOWN_DRAIN_SECONDS must be "
f"at most {MAX_SHUTDOWN_BUDGET_SECONDS} seconds"
)
@property
def shutdown_budget_seconds(self) -> float:
"""Худшее время от SIGTERM до выхода; требование лабы — не более 10 секунд."""
return self.graceful_shutdown_seconds + self.shutdown_drain_seconds
@property
def binds_to_loopback(self) -> bool:
return self.host in LOOPBACK_HOSTS
@classmethod
def from_env(cls, environ: Mapping[str, str] | None = None) -> "Config":
source: Mapping[str, str] = os.environ if environ is None else environ
env = _choice(source, "APP_ENV", DEFAULT_ENV, ENVIRONMENTS)
host = source.get("APP_HOST", DEFAULT_HOST).strip()
if not host:
raise ConfigError("APP_HOST must not be empty")
default_log_level = "debug" if env == "dev" else DEFAULT_LOG_LEVEL
database_url = database_url_from_env(source)
cache_url = _checked_url(
_required_secret(source, "CACHE_URL"),
name="CACHE_URL",
schemes=CACHE_URL_SCHEMES,
)
cursor_secret = _secret(source, "CURSOR_SECRET")
return cls(
host=host,
port=_integer(source, "APP_PORT", DEFAULT_PORT, 1, 65535),
env=env,
log_level=_choice(source, "LOG_LEVEL", default_log_level, LOG_LEVELS),
graceful_shutdown_seconds=_integer(
source, "GRACEFUL_SHUTDOWN_SECONDS", DEFAULT_GRACEFUL_SHUTDOWN_SECONDS, 1, 10
),
shutdown_drain_seconds=_seconds(
source, "SHUTDOWN_DRAIN_SECONDS", DEFAULT_SHUTDOWN_DRAIN_SECONDS, 5.0
),
database_url=database_url,
cache_url=cache_url,
session_store=_choice(
source, "SESSION_STORE", DEFAULT_SESSION_STORE, SESSION_STORES
),
session_ttl_seconds=_integer(
source,
"SESSION_TTL_SECONDS",
DEFAULT_SESSION_TTL_SECONDS,
MIN_SESSION_TTL_SECONDS,
MAX_SESSION_TTL_SECONDS,
),
db_pool_size=_integer(
source, "DB_POOL_SIZE", DEFAULT_DB_POOL_SIZE, 1, MAX_DB_POOL_SIZE
),
db_max_overflow=_integer(
source, "DB_MAX_OVERFLOW", DEFAULT_DB_MAX_OVERFLOW, 0, MAX_DB_MAX_OVERFLOW
),
db_pool_timeout_seconds=_seconds(
source,
"DB_POOL_TIMEOUT_SECONDS",
DEFAULT_DB_POOL_TIMEOUT_SECONDS,
MAX_DB_POOL_TIMEOUT_SECONDS,
),
db_connect_timeout_seconds=_seconds(
source,
"DB_CONNECT_TIMEOUT_SECONDS",
DEFAULT_DB_CONNECT_TIMEOUT_SECONDS,
MAX_DB_CONNECT_TIMEOUT_SECONDS,
),
db_command_timeout_seconds=_seconds(
source,
"DB_COMMAND_TIMEOUT_SECONDS",
DEFAULT_DB_COMMAND_TIMEOUT_SECONDS,
MAX_DB_COMMAND_TIMEOUT_SECONDS,
),
db_statement_timeout_ms=_integer(
source,
"DB_STATEMENT_TIMEOUT_MS",
DEFAULT_DB_STATEMENT_TIMEOUT_MS,
1,
MAX_DB_STATEMENT_TIMEOUT_MS,
),
cache_timeout_seconds=_seconds(
source,
"CACHE_TIMEOUT_SECONDS",
DEFAULT_CACHE_TIMEOUT_SECONDS,
MAX_CACHE_TIMEOUT_SECONDS,
),
cursor_secret=None if cursor_secret is None else cursor_secret.encode("utf-8"),
)
+23
View File
@@ -0,0 +1,23 @@
"""Контекст одного HTTP-запроса: данные живут в ASGI-scope."""
from __future__ import annotations
from typing import Any, MutableMapping
CONTEXT_KEY = "messenger.request_context"
REQUEST_ID = "request_id"
USER_ID = "user_id"
def context_of(scope: MutableMapping[str, Any]) -> dict[str, Any]:
"""Возвращает (при необходимости создавая) словарь контекста запроса."""
context = scope.get(CONTEXT_KEY)
if context is None:
context = {}
scope[CONTEXT_KEY] = context
return context
def request_context(request: Any) -> dict[str, Any]:
"""Контекст по объекту Request/WebSocket."""
return context_of(request.scope)
+119
View File
@@ -0,0 +1,119 @@
"""Keyset-курсор: подписан ключом процесса и привязан к ресурсу (kind + scope)."""
from __future__ import annotations
import base64
import binascii
import hashlib
import hmac
import json
import secrets
from dataclasses import dataclass
from uuid import UUID
from .domain import Position, parse_rfc3339_z
CURSOR_VERSION = 1
SIGNATURE_BYTES = 16
SEPARATOR = "."
KIND_CHATS = "chats"
KIND_MESSAGES = "messages"
class InvalidCursor(ValueError):
"""Курсор повреждён, подделан или выпущен для другого ресурса."""
def _b64encode(raw: bytes) -> str:
return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
def _b64decode(value: str) -> bytes:
return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
def _parse_timestamp(value: object) -> str:
"""Проверяет, что метка времени — RFC 3339 UTC с суффиксом Z."""
if not isinstance(value, str):
raise InvalidCursor("cursor timestamp is not a string")
try:
parse_rfc3339_z(value)
except ValueError:
raise InvalidCursor("cursor timestamp is not RFC 3339 UTC with Z suffix") from None
return value
@dataclass(frozen=True)
class Cursor:
"""Позиция последнего отданного элемента выборки."""
kind: str
scope: str
created_at: str
item_id: str
@property
def position(self) -> Position:
"""Место в порядке (created_at, id), с которого продолжается выборка."""
return (parse_rfc3339_z(self.created_at), UUID(self.item_id))
class CursorCodec:
"""Кодирует и проверяет курсоры ключом, известным только процессу."""
def __init__(self, key: bytes | None = None) -> None:
self._key = secrets.token_bytes(32) if key is None else key
def encode(self, kind: str, scope: str, created_at: str, item_id: str) -> str:
payload = json.dumps(
{
"v": CURSOR_VERSION,
"kind": kind,
"scope": scope,
"created_at": created_at,
"id": item_id,
},
ensure_ascii=False,
separators=(",", ":"),
sort_keys=True,
).encode("utf-8")
signature = hmac.new(self._key, payload, hashlib.sha256).digest()[:SIGNATURE_BYTES]
return _b64encode(payload) + SEPARATOR + _b64encode(signature)
def decode(self, token: str, *, kind: str, scope: str) -> Cursor:
"""Разбирает курсор или поднимает InvalidCursor — наружу это всегда 400."""
if not isinstance(token, str) or not token:
raise InvalidCursor("cursor is empty")
encoded_payload, separator, encoded_signature = token.partition(SEPARATOR)
if not separator:
raise InvalidCursor("cursor has no signature part")
try:
payload = _b64decode(encoded_payload)
signature = _b64decode(encoded_signature)
except (binascii.Error, ValueError):
raise InvalidCursor("cursor is not valid base64url") from None
expected = hmac.new(self._key, payload, hashlib.sha256).digest()[:SIGNATURE_BYTES]
if not hmac.compare_digest(signature, expected):
raise InvalidCursor("cursor signature mismatch")
try:
data = json.loads(payload.decode("utf-8"))
except (UnicodeDecodeError, ValueError):
raise InvalidCursor("cursor payload is not valid JSON") from None
if not isinstance(data, dict) or data.get("v") != CURSOR_VERSION:
raise InvalidCursor("unsupported cursor version")
cursor = Cursor(
kind=str(data.get("kind", "")),
scope=str(data.get("scope", "")),
created_at=_parse_timestamp(data.get("created_at")),
item_id=str(data.get("id", "")),
)
try:
UUID(cursor.item_id)
except ValueError:
raise InvalidCursor("cursor id is not a UUID") from None
if cursor.kind != kind or cursor.scope != scope:
raise InvalidCursor("cursor belongs to another resource")
return cursor
+59
View File
@@ -0,0 +1,59 @@
"""Асинхронный доступ к PostgreSQL: движок, ограниченный пул и таймауты."""
from __future__ import annotations
from contextlib import asynccontextmanager
from typing import AsyncIterator
from sqlalchemy import text
from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
from .config import Config
APPLICATION_NAME = "messenger"
# Незакоммиченная транзакция не должна держать соединение пула бесконечно.
IDLE_IN_TRANSACTION_TIMEOUT_MS = 10000
class Database:
"""Владеет пулом соединений; сессия живёт ровно один HTTP-запрос."""
def __init__(self, config: Config) -> None:
self._engine: AsyncEngine = create_async_engine(
config.database_url,
# Пул ограничен: лишние запросы ждут освобождения соединения.
pool_size=config.db_pool_size,
max_overflow=config.db_max_overflow,
pool_timeout=config.db_pool_timeout_seconds,
pool_pre_ping=True,
pool_recycle=1800,
connect_args={
# Границы на круг asyncpg, на установление соединения (включая
# разрешение имени) и на стороне сервера.
"timeout": config.db_connect_timeout_seconds,
"command_timeout": config.db_command_timeout_seconds,
"server_settings": {
"application_name": APPLICATION_NAME,
"statement_timeout": str(config.db_statement_timeout_ms),
"idle_in_transaction_session_timeout": str(IDLE_IN_TRANSACTION_TIMEOUT_MS),
},
},
)
self._sessions = async_sessionmaker(self._engine, expire_on_commit=False)
@asynccontextmanager
async def session(self) -> AsyncIterator[AsyncSession]:
"""Сессия на один запрос: закрывается всегда, откат делает SQLAlchemy."""
session = self._sessions()
try:
yield session
finally:
await session.close()
async def ping(self) -> None:
"""Проверка готовности: одно дешёвое обращение к серверу."""
async with self.session() as session:
await session.execute(text("SELECT 1"))
async def dispose(self) -> None:
await self._engine.dispose()
+119
View File
@@ -0,0 +1,119 @@
"""Зависимости FastAPI: PostgreSQL, хранилище сессий и текущий пользователь.
Личность в этой работе определяется только сессией: заголовок X-User-Id из ЛР1
не читается нигде и не влияет на ответ.
"""
from __future__ import annotations
from collections.abc import AsyncIterator
from dataclasses import dataclass
from typing import Annotated
from fastapi import Depends, Header, Request
from sqlalchemy.ext.asyncio import AsyncSession
from .context import USER_ID, request_context
from .cursor import CursorCodec
from .db import Database
from .domain import UserRecord
from .errors import BASIC_CHALLENGE, unauthorized
from .repository import Repository
from .security import parse_basic, parse_bearer
from .sessions import SessionStore
AUTHORIZATION_HEADER = "Authorization"
@dataclass(frozen=True)
class BasicCredentials:
"""Разобранные учётные данные входа по Basic."""
username: str
password: str
def get_database(request: Request) -> Database:
"""Пул соединений живёт в состоянии приложения: один на процесс."""
return request.app.state.database
def get_sessions(request: Request) -> SessionStore:
"""Хранилище сессий живёт в состоянии приложения."""
return request.app.state.sessions
def get_cursors(request: Request) -> CursorCodec:
"""Кодек курсоров привязан к процессу: ключ подписи не покидает память."""
return request.app.state.cursors
DatabaseDep = Annotated[Database, Depends(get_database)]
SessionsDep = Annotated[SessionStore, Depends(get_sessions)]
CursorsDep = Annotated[CursorCodec, Depends(get_cursors)]
async def get_db_session(database: DatabaseDep) -> AsyncIterator[AsyncSession]:
"""Сессия БД на один запрос: закрывается вместе с ответом."""
async with database.session() as session:
yield session
DbSession = Annotated[AsyncSession, Depends(get_db_session)]
def get_repository(session: DbSession) -> Repository:
"""Репозиторий поверх сессии запроса: всё SQL живёт в нём."""
return Repository(session)
RepositoryDep = Annotated[Repository, Depends(get_repository)]
def basic_credentials(
authorization: Annotated[str | None, Header(alias=AUTHORIZATION_HEADER)] = None,
) -> BasicCredentials:
"""Учётные данные входа: единственное место, где принимается схема Basic."""
parsed = parse_basic(authorization)
if parsed is None:
raise unauthorized("Требуется Basic-аутентификация", challenge=BASIC_CHALLENGE)
return BasicCredentials(username=parsed[0], password=parsed[1])
BasicCredentialsDep = Annotated[BasicCredentials, Depends(basic_credentials)]
def bearer_token(
authorization: Annotated[str | None, Header(alias=AUTHORIZATION_HEADER)] = None,
) -> str:
"""Токен сессии из заголовка Authorization; иначе 401 с Bearer-челленджем."""
token = parse_bearer(authorization)
if token is None:
raise unauthorized("Требуется Bearer-токен сессии")
return token
BearerToken = Annotated[str, Depends(bearer_token)]
async def get_current_user(
request: Request,
sessions: SessionsDep,
repository: RepositoryDep,
token: BearerToken,
) -> UserRecord:
"""Владелец действующей сессии.
Порядок важен: сначала сессия в Valkey, потом пользователь в PostgreSQL.
Неизвестный или истёкший токен — это 401, а не «анонимный доступ».
"""
state = await sessions.resolve(token)
if state is None:
raise unauthorized("Сессия не найдена или истекла")
user = await repository.get_user(state.user_id)
if user is None:
raise unauthorized("Владелец сессии больше не существует")
request_context(request)[USER_ID] = str(user.id)
return user
CurrentUser = Annotated[UserRecord, Depends(get_current_user)]
+80
View File
@@ -0,0 +1,80 @@
"""Сущности предметной области, порядок сортировки и формат метки времени."""
from __future__ import annotations
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Protocol, Sequence
from uuid import UUID
def utc_now() -> datetime:
return datetime.now(timezone.utc)
def rfc3339_z(moment: datetime) -> str:
"""RFC 3339 в UTC с суффиксом Z и микросекундной точностью."""
return moment.astimezone(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z")
def parse_rfc3339_z(value: str) -> datetime:
"""Разбирает метку в формате `rfc3339_z`; иначе ValueError."""
if not value.endswith("Z"):
raise ValueError("timestamp is not UTC with Z suffix")
return datetime.fromisoformat(value[:-1] + "+00:00")
class Sortable(Protocol):
"""Общая часть записей: пара, по которой строится порядок и keyset-курсор.
Порядок выборок — (created_at, id) по возрастанию. UUID упорядочивается
своим целым значением (так же, как `uuid.UUID(x).int` в публичном smoke),
поэтому порядок PostgreSQL и порядок клиента совпадают.
"""
created_at: datetime
id: UUID
# Место в этом порядке, откуда продолжается выборка: пара (created_at, id).
Position = tuple[datetime, UUID]
class UsernameTaken(Exception):
"""username уже занят другим пользователем."""
class UnknownMembers(Exception):
"""В member_ids есть идентификаторы несуществующих пользователей."""
def __init__(self, member_ids: Sequence[UUID]) -> None:
super().__init__("unknown members")
self.member_ids = tuple(member_ids)
@dataclass(frozen=True)
class UserRecord:
id: UUID
username: str
display_name: str
created_at: datetime
@dataclass(frozen=True)
class ChatRecord:
id: UUID
title: str
member_ids: tuple[UUID, ...]
created_at: datetime
def has_member(self, user_id: UUID) -> bool:
"""Состав участников задаётся при создании и не меняется."""
return user_id in self.member_ids
@dataclass(frozen=True)
class MessageRecord:
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: datetime
+157
View File
@@ -0,0 +1,157 @@
"""Обработчики ошибок: единый конверт контракта и заголовки к нему."""
from __future__ import annotations
import logging
import uuid
from typing import Mapping
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from redis.exceptions import RedisError
from sqlalchemy.exc import DataError, DisconnectionError, InterfaceError, OperationalError
from sqlalchemy.exc import TimeoutError as PoolTimeoutError
from starlette.exceptions import HTTPException as StarletteHTTPException
from .context import REQUEST_ID, request_context
from .errors import INTERNAL_ERROR, INVALID_REQUEST, UNAVAILABLE, ApiError, code_for_status
from .logging_setup import log
FALLBACK_MESSAGES: Mapping[int, str] = {
404: "Маршрут не найден",
405: "Метод не поддерживается для этого маршрута",
}
# Отказ критичной зависимости (PostgreSQL или Valkey): наружу 503 без деталей,
# подробности остаются в логе. Для клиента «сессии недоступны» и «база недоступна»
# выглядят одинаково — и это правильно, различать их он не должен.
#
# Здесь только отказы соединения и исчерпание пула. Более широкий SQLAlchemyError
# сюда не годится: он включает DataError, и тогда значение, которое PostgreSQL
# не может принять, выглядело бы как недоступность базы.
DEPENDENCY_ERRORS = (
OperationalError,
InterfaceError,
DisconnectionError,
PoolTimeoutError,
RedisError,
OSError,
)
DEPENDENCY_MESSAGE = "Сервис временно недоступен: критичная зависимость не отвечает"
DATA_ERROR_MESSAGE = "Значение поля не может быть сохранено"
def request_id_of(request: Request) -> str:
"""Идентификатор запроса; запасной вариант — если middleware не подключён."""
context = request_context(request)
identifier = context.get(REQUEST_ID)
if not identifier:
identifier = uuid.uuid4().hex
context[REQUEST_ID] = identifier
return identifier
def error_response(
request: Request,
status: int,
code: str,
message: str,
headers: Mapping[str, str] | None = None,
) -> JSONResponse:
"""Собирает конверт ошибки контракта; request_id совпадает с заголовком."""
identifier = request_id_of(request)
response_headers = {"X-Request-Id": identifier}
response_headers.update(headers or {})
return JSONResponse(
status_code=status,
content={"error": {"code": code, "message": message, "request_id": identifier}},
headers=response_headers,
)
def describe_validation_error(exc: RequestValidationError) -> str:
"""Краткое описание без значений полей: наружу уходит только расположение ошибки.
Значения сюда не попадают намеренно: среди них может быть пароль.
"""
errors = exc.errors()
if not errors:
return "Тело запроса не соответствует контракту"
first = errors[0]
if str(first.get("type", "")) == "json_invalid":
return "Тело запроса не является корректным JSON"
location = ".".join(
str(part)
for part in first.get("loc", ())
if part not in ("body", "query", "path", "header")
)
return f"Некорректный запрос: {location or 'body'}"
def register_error_handlers(app: FastAPI, logger: logging.Logger) -> None:
"""Ставит обработчики так, чтобы наружу не ушёл ответ без конверта."""
@app.exception_handler(ApiError)
async def handle_api_error(request: Request, exc: ApiError) -> JSONResponse:
return error_response(request, exc.status, exc.code, exc.message, exc.headers)
@app.exception_handler(RequestValidationError)
async def handle_validation_error(
request: Request, exc: RequestValidationError
) -> JSONResponse:
return error_response(request, 400, INVALID_REQUEST, describe_validation_error(exc))
@app.exception_handler(StarletteHTTPException)
async def handle_http_exception(
request: Request, exc: StarletteHTTPException
) -> JSONResponse:
status = exc.status_code
return error_response(
request,
status,
code_for_status(status),
FALLBACK_MESSAGES.get(status, "Запрос не может быть обработан"),
getattr(exc, "headers", None),
)
async def handle_dependency_failure(request: Request, exc: Exception) -> JSONResponse:
log(
logger,
logging.ERROR,
"dependency_unavailable",
exc_info=exc,
request_id=request_id_of(request),
error=type(exc).__name__,
)
return error_response(request, 503, UNAVAILABLE, DEPENDENCY_MESSAGE)
@app.exception_handler(DataError)
async def handle_data_error(request: Request, exc: DataError) -> JSONResponse:
"""Данные клиента, которые СУБД не в состоянии сохранить, — это 400.
На границе такие значения уже отсекаются; обработчик оставлен страховкой,
чтобы ошибка данных никогда не выдавалась за отказ зависимости.
"""
log(
logger,
logging.WARNING,
"invalid_stored_value",
request_id=request_id_of(request),
error=type(exc).__name__,
)
return error_response(request, 400, INVALID_REQUEST, DATA_ERROR_MESSAGE)
for error_type in DEPENDENCY_ERRORS:
app.add_exception_handler(error_type, handle_dependency_failure)
@app.exception_handler(Exception)
async def handle_unexpected(request: Request, exc: Exception) -> JSONResponse:
log(
logger,
logging.ERROR,
"unhandled_exception",
exc_info=exc,
request_id=request_id_of(request),
error=type(exc).__name__,
)
return error_response(request, 500, INTERNAL_ERROR, "Внутренняя ошибка сервера")
+78
View File
@@ -0,0 +1,78 @@
"""Ошибки API и единый конверт ответа контракта."""
from __future__ import annotations
from typing import Mapping
INVALID_REQUEST = "invalid_request"
UNAUTHORIZED = "unauthorized"
NOT_FOUND = "not_found"
CONFLICT = "conflict"
PAYLOAD_TOO_LARGE = "payload_too_large"
UNSUPPORTED_MEDIA_TYPE = "unsupported_media_type"
RATE_LIMITED = "rate_limited"
UNAVAILABLE = "unavailable"
INTERNAL_ERROR = "internal_error"
BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"'
BEARER_CHALLENGE = 'Bearer realm="messenger"'
DEFAULT_CODE_BY_STATUS: Mapping[int, str] = {
400: INVALID_REQUEST,
401: UNAUTHORIZED,
403: UNAUTHORIZED,
404: NOT_FOUND,
405: INVALID_REQUEST,
409: CONFLICT,
413: PAYLOAD_TOO_LARGE,
415: UNSUPPORTED_MEDIA_TYPE,
429: RATE_LIMITED,
500: INTERNAL_ERROR,
503: UNAVAILABLE,
}
class ApiError(Exception):
"""Ошибка, которую можно безопасно показать клиенту в конверте контракта."""
def __init__(
self,
status: int,
code: str,
message: str,
headers: Mapping[str, str] | None = None,
) -> None:
super().__init__(message)
self.status = status
self.code = code
self.message = message
self.headers = dict(headers or {})
def code_for_status(status: int) -> str:
"""Подбирает код конверта для статуса, пришедшего извне контракта."""
if status in DEFAULT_CODE_BY_STATUS:
return DEFAULT_CODE_BY_STATUS[status]
return INTERNAL_ERROR if status >= 500 else INVALID_REQUEST
def invalid_request(message: str) -> ApiError:
return ApiError(400, INVALID_REQUEST, message)
def unauthorized(message: str, challenge: str = BEARER_CHALLENGE) -> ApiError:
"""401 с challenge схемы: Basic — только на создании сессии, иначе Bearer."""
return ApiError(401, UNAUTHORIZED, message, headers={"WWW-Authenticate": challenge})
def not_found(message: str) -> ApiError:
"""Чужой объект неотличим от отсутствующего: 403 не используется."""
return ApiError(404, NOT_FOUND, message)
def conflict(message: str) -> ApiError:
return ApiError(409, CONFLICT, message)
def unavailable(message: str) -> ApiError:
"""503: зависимость недоступна, отказ ограничен и не раскрывает внутренностей."""
return ApiError(503, UNAVAILABLE, message)
+26
View File
@@ -0,0 +1,26 @@
"""Проверка живости для Docker HEALTHCHECK: python -m messenger.healthcheck."""
from __future__ import annotations
import os
import urllib.error
import urllib.request
DEFAULT_PORT = "8080"
TIMEOUT_SECONDS = 2
def liveness_url() -> str:
port = os.environ.get("APP_PORT", DEFAULT_PORT).strip() or DEFAULT_PORT
return "http://127.0.0.1:%s/health/live" % port
def main() -> int:
try:
with urllib.request.urlopen(liveness_url(), timeout=TIMEOUT_SECONDS) as response:
return 0 if response.status == 200 else 1
except (urllib.error.URLError, OSError, ValueError):
return 1
if __name__ == "__main__":
raise SystemExit(main())
+76
View File
@@ -0,0 +1,76 @@
"""Структурные логи в stdout: одна JSON-строка на событие, без тел и query-строки."""
from __future__ import annotations
import json
import logging
import sys
from datetime import datetime, timezone
class JsonFormatter(logging.Formatter):
"""Сериализует запись лога в компактный JSON без потери структуры."""
def format(self, record: logging.LogRecord) -> str:
payload: dict[str, object] = {
"ts": datetime.fromtimestamp(record.created, timezone.utc)
.isoformat(timespec="milliseconds")
.replace("+00:00", "Z"),
"level": record.levelname.lower(),
"logger": record.name,
"event": record.getMessage(),
}
payload.update(getattr(record, "fields", {}) or {})
if record.exc_info:
payload["exception"] = self.formatException(record.exc_info)
return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
class _EnvironmentFilter(logging.Filter):
"""Добавляет метку окружения в каждую запись, включая логи uvicorn."""
def __init__(self, env: str) -> None:
super().__init__()
self._env = env
def filter(self, record: logging.LogRecord) -> bool:
fields = dict(getattr(record, "fields", {}) or {})
fields.setdefault("env", self._env)
record.fields = fields
return True
def configure_logging(level: str, env: str) -> logging.Logger:
"""Перенаправляет логи процесса в stdout в структурированном виде."""
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(JsonFormatter())
handler.addFilter(_EnvironmentFilter(env))
root = logging.getLogger()
root.handlers[:] = [handler]
root.setLevel(level.upper())
for name in ("uvicorn", "uvicorn.error", "uvicorn.access"):
logger = logging.getLogger(name)
logger.handlers[:] = []
logger.propagate = True
logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
return logging.getLogger("messenger")
def log(
logger: logging.Logger,
level: int,
event: str,
exc_info: BaseException | None = None,
**fields: object,
) -> None:
"""Пишет событие с произвольными структурированными полями."""
if not logger.isEnabledFor(level):
return
logger.log(
level,
event,
extra={"fields": {k: v for k, v in fields.items() if v is not None}},
exc_info=exc_info,
)
+92
View File
@@ -0,0 +1,92 @@
"""Внешний ASGI-слой: X-Request-Id (в том числе на 500) и структурный access-лог."""
from __future__ import annotations
import logging
import re
import time
import uuid
from typing import Any, Awaitable, Callable, MutableMapping
from .context import REQUEST_ID, USER_ID, context_of
from .logging_setup import log
SAFE_REQUEST_ID = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
Scope = MutableMapping[str, Any]
Message = MutableMapping[str, Any]
Receive = Callable[[], Awaitable[Message]]
Send = Callable[[Message], Awaitable[None]]
ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
def incoming_request_id(scope: Scope) -> str | None:
"""Возвращает заголовок клиента, если он безопасен для логирования и ответа."""
for name, value in scope.get("headers") or ():
if name.lower() != b"x-request-id":
continue
try:
candidate = value.decode("ascii")
except UnicodeDecodeError:
return None
return candidate if SAFE_REQUEST_ID.match(candidate) else None
return None
def set_response_header(message: Message, name: bytes, value: bytes) -> None:
"""Идемпотентно выставляет заголовок в ASGI-сообщении ответа."""
headers = message.setdefault("headers", [])
lowered = name.lower()
for index, (key, _) in enumerate(headers):
if key.lower() == lowered:
headers[index] = (name, value)
return
headers.append((name, value))
class RequestContextMiddleware:
"""Присваивает запросу идентификатор, гарантирует заголовок и пишет access-лог."""
def __init__(self, app: ASGIApp, logger: logging.Logger) -> None:
self._app = app
self._logger = logger
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
if scope["type"] != "http":
await self._app(scope, receive, send)
return
request_id = incoming_request_id(scope) or uuid.uuid4().hex
context = context_of(scope)
context[REQUEST_ID] = request_id
started = time.perf_counter()
status_holder: dict[str, int] = {}
async def send_with_request_id(message: Message) -> None:
if message["type"] == "http.response.start":
status_holder["status"] = int(message["status"])
set_response_header(message, b"x-request-id", request_id.encode("ascii"))
await send(message)
try:
await self._app(scope, receive, send_with_request_id)
finally:
self._write_access_log(scope, status_holder.get("status"), started)
def _write_access_log(self, scope: Scope, status: int | None, started: float) -> None:
context = context_of(scope)
# Логируется шаблон маршрута, а не сырой путь: query-строка в лог не попадает.
route = getattr(scope.get("route"), "path", None)
endpoint = scope.get("endpoint")
log(
self._logger,
logging.INFO,
"request",
request_id=context.get(REQUEST_ID),
method=scope.get("method"),
route=route,
operation=None if endpoint is None else getattr(endpoint, "__name__", None),
matched=route is not None,
status=status,
duration_ms=round((time.perf_counter() - started) * 1000, 3),
user_id=context.get(USER_ID),
)
+209
View File
@@ -0,0 +1,209 @@
"""Схемы запросов и ответов ровно по contracts/openapi.json."""
from __future__ import annotations
from typing import Literal
from uuid import UUID
from pydantic import BaseModel, ConfigDict, Field, field_validator
from .domain import ChatRecord, MessageRecord, UserRecord, rfc3339_z
from .sessions import IssuedSession
USERNAME_PATTERN = r"^[a-z0-9_]{3,32}$"
MIN_PASSWORD = 12
MAX_PASSWORD = 128
MAX_DISPLAY_NAME = 100
MAX_TITLE = 100
MAX_TEXT = 4000
MAX_MEMBERS = 100
MAX_LIMIT = 100
DEFAULT_LIMIT = 50
def _require_content(value: str, *, field: str) -> str:
"""Обязательная строка не может быть пустой или состоять из пробельных символов."""
if not value.strip():
raise ValueError(f"{field} must not be empty or contain only whitespace")
return value
def _visible(value: str, *, field: str, maximum: int) -> str:
"""Проверяет строку, которую предстоит сохранить в PostgreSQL.
U+0000 отвергается на границе: тип `text` его не хранит, и без этой проверки
ошибка данных клиента дошла бы до обработчика ошибок базы, где выглядела бы
отказом зависимости.
"""
_require_content(value, field=field)
if "\u0000" in value:
raise ValueError(f"{field} must not contain U+0000")
if len(value) > maximum:
raise ValueError(f"{field} must be at most {maximum} Unicode code points")
return value
class Health(BaseModel):
"""Тело ответа /health/live и /health/ready."""
model_config = ConfigDict(extra="forbid")
status: Literal["ok"] = "ok"
class User(BaseModel):
"""Публичное представление пользователя: ни пароля, ни сессий здесь нет."""
model_config = ConfigDict(extra="forbid")
id: UUID
username: str
display_name: str
created_at: str
@classmethod
def from_record(cls, record: UserRecord) -> "User":
return cls(
id=record.id,
username=record.username,
display_name=record.display_name,
created_at=rfc3339_z(record.created_at),
)
class CreateUser(BaseModel):
"""Регистрация: пароль приходит открытым текстом и дальше живёт только как хэш."""
model_config = ConfigDict(extra="forbid")
username: str = Field(pattern=USERNAME_PATTERN)
display_name: str
password: str = Field(min_length=MIN_PASSWORD, max_length=MAX_PASSWORD)
@field_validator("display_name")
@classmethod
def _check_display_name(cls, value: str) -> str:
return _visible(value, field="display_name", maximum=MAX_DISPLAY_NAME)
@field_validator("password")
@classmethod
def _check_password(cls, value: str) -> str:
"""Пароль из одних пробелов — пустое значение, а не секрет.
Пробелы внутри и по краям допустимы и не обрезаются: при входе пароль
сверяется целиком. U+0000 здесь не проверяется: в PostgreSQL попадает
только хэш, а не сам пароль.
"""
return _require_content(value, field="password")
class Session(BaseModel):
"""Выданная сессия: токен показывается клиенту один раз и в логи не попадает."""
model_config = ConfigDict(extra="forbid")
token: str
token_type: Literal["Bearer"] = "Bearer"
expires_at: str
user: User
@classmethod
def from_issued(cls, issued: IssuedSession, user: UserRecord) -> "Session":
return cls(
token=issued.token,
expires_at=rfc3339_z(issued.state.expires_at),
user=User.from_record(user),
)
class Chat(BaseModel):
model_config = ConfigDict(extra="forbid")
id: UUID
title: str
member_ids: list[UUID]
created_at: str
@classmethod
def from_record(cls, record: ChatRecord) -> "Chat":
return cls(
id=record.id,
title=record.title,
member_ids=list(record.member_ids),
created_at=rfc3339_z(record.created_at),
)
class CreateChat(BaseModel):
model_config = ConfigDict(extra="forbid")
title: str
member_ids: list[UUID]
@field_validator("title")
@classmethod
def _check_title(cls, value: str) -> str:
return _visible(value, field="title", maximum=MAX_TITLE)
@field_validator("member_ids")
@classmethod
def _check_member_ids(cls, value: list[UUID]) -> list[UUID]:
if not 1 <= len(value) <= MAX_MEMBERS:
raise ValueError(f"member_ids must contain 1..{MAX_MEMBERS} items")
if len(set(value)) != len(value):
raise ValueError("member_ids must not contain duplicates")
return value
class Message(BaseModel):
model_config = ConfigDict(extra="forbid")
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: str
@classmethod
def from_record(cls, record: MessageRecord) -> "Message":
return cls(
id=record.id,
chat_id=record.chat_id,
sender_id=record.sender_id,
text=record.text,
created_at=rfc3339_z(record.created_at),
)
class CreateMessage(BaseModel):
"""Поле sender_id не принимается: отправитель выводится из идентификации."""
model_config = ConfigDict(extra="forbid")
text: str
@field_validator("text")
@classmethod
def _check_text(cls, value: str) -> str:
return _visible(value, field="text", maximum=MAX_TEXT)
class ChatPage(BaseModel):
model_config = ConfigDict(extra="forbid")
items: list[Chat]
next_cursor: str | None
@classmethod
def from_records(cls, records: list[ChatRecord], next_cursor: str | None) -> "ChatPage":
return cls(items=[Chat.from_record(record) for record in records], next_cursor=next_cursor)
class MessagePage(BaseModel):
model_config = ConfigDict(extra="forbid")
items: list[Message]
next_cursor: str | None
@classmethod
def from_records(cls, records: list[MessageRecord], next_cursor: str | None) -> "MessagePage":
return cls(items=[Message.from_record(record) for record in records], next_cursor=next_cursor)
+38
View File
@@ -0,0 +1,38 @@
"""Keyset-пагинация: разбор курсора клиента и сборка следующего."""
from __future__ import annotations
from typing import Sequence
from .cursor import CursorCodec, InvalidCursor
from .domain import Position, Sortable, rfc3339_z
from .errors import invalid_request
def decoded_cursor(
cursors: CursorCodec,
token: str | None,
*,
kind: str,
scope: str,
) -> Position | None:
"""Позиция из курсора клиента; None означает «начать с начала выборки»."""
if token is None:
return None
try:
return cursors.decode(token, kind=kind, scope=scope).position
except InvalidCursor:
raise invalid_request("cursor недействителен для этого запроса") from None
def build_next_cursor(
cursors: CursorCodec,
kind: str,
scope: str,
records: Sequence[Sortable],
has_more: bool,
) -> str | None:
"""next_cursor равен null, если на момент чтения следующей записи нет."""
if not has_more or not records:
return None
last = records[-1]
return cursors.encode(kind, scope, rfc3339_z(last.created_at), str(last.id))
+261
View File
@@ -0,0 +1,261 @@
"""Запросы к PostgreSQL: единственное место, где выполняется SQL.
Все значения передаются bind-параметрами — строки запросов не собираются из
данных пользователя. Транзакционную границу задаёт репозиторий: операция,
меняющая несколько таблиц, выполняется целиком или не выполняется вовсе.
Единица работы — неявная транзакция сессии запроса: пишущие методы завершают
её `commit`, а незавершённую откатывает закрытие сессии. Поэтому чтение перед
записью (проверка доступа → вставка сообщения) идёт в той же транзакции.
"""
from __future__ import annotations
from typing import Sequence
from uuid import UUID, uuid4
from sqlalchemy import Row, Select, cast, insert, literal, select, tuple_
from sqlalchemy.dialects.postgresql import TIMESTAMP, UUID as PGUUID
from sqlalchemy.dialects.postgresql import insert as pg_insert
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession
from .domain import ChatRecord, MessageRecord, Position, UnknownMembers, UserRecord
from .schema import CHAT_MEMBERS, CHATS, MESSAGES, USERS
FOREIGN_KEY_VIOLATION = "23503"
def _sqlstate(error: IntegrityError) -> str | None:
"""Код ошибки PostgreSQL: драйвер кладёт его в исходное исключение."""
return getattr(getattr(error, "orig", None), "sqlstate", None)
def _after_predicate(created_at_column, id_column, after: Position):
"""Keyset-условие «строго после пары (created_at, id)» одним сравнением строк.
Сравнение строк целиком — то, что умеет использовать составной индекс;
значение приводится к нужному типу явно, чтобы драйвер не угадывал его.
"""
moment, item_id = after
return tuple_(created_at_column, id_column) > tuple_(
cast(literal(moment), TIMESTAMP(timezone=True)),
cast(literal(item_id), PGUUID(as_uuid=True)),
)
def _user_record(row: Row) -> UserRecord:
return UserRecord(
id=row.id, username=row.username, display_name=row.display_name, created_at=row.created_at
)
def _chat_columns() -> tuple:
return (CHATS.c.id, CHATS.c.title, CHATS.c.created_at)
def _message_columns() -> tuple:
return (
MESSAGES.c.id,
MESSAGES.c.chat_id,
MESSAGES.c.sender_id,
MESSAGES.c.text,
MESSAGES.c.created_at,
)
class Repository:
"""Набор операций над PostgreSQL в рамках одной сессии (одного запроса)."""
def __init__(self, session: AsyncSession) -> None:
self._session = session
async def ping(self) -> None:
"""Дешёвая проверка живости соединения для /health/ready."""
await self._session.execute(select(literal(1)))
async def username_taken(self, username: str) -> bool:
"""Дешёвая предпроверка: занятый username отсекается до дорогого KDF."""
found = await self._session.scalar(
select(USERS.c.id).where(USERS.c.username == username).limit(1)
)
return found is not None
async def create_user(
self, username: str, display_name: str, password_hash: str
) -> UserRecord | None:
"""Создаёт пользователя; None — если username уже занят.
Гонку двух одновременных регистраций закрывает уникальный индекс:
`ON CONFLICT DO NOTHING` не поднимает ошибку и не портит транзакцию.
"""
row = (
await self._session.execute(
pg_insert(USERS)
.values(
id=uuid4(),
username=username,
display_name=display_name,
password_hash=password_hash,
)
.on_conflict_do_nothing(index_elements=[USERS.c.username])
.returning(*USERS.c)
)
).first()
await self._session.commit()
return None if row is None else _user_record(row)
async def credentials_for(self, username: str) -> tuple[UserRecord, str] | None:
"""Пользователь и его хэш пароля для проверки входа."""
row = (
await self._session.execute(
select(USERS.c.id, USERS.c.username, USERS.c.display_name, USERS.c.created_at,
USERS.c.password_hash)
.where(USERS.c.username == username)
.limit(1)
)
).first()
if row is None:
return None
return _user_record(row), row.password_hash
async def get_user(self, user_id: UUID) -> UserRecord | None:
row = (
await self._session.execute(
select(USERS.c.id, USERS.c.username, USERS.c.display_name, USERS.c.created_at)
.where(USERS.c.id == user_id)
.limit(1)
)
).first()
return None if row is None else _user_record(row)
async def create_chat(self, title: str, member_ids: Sequence[UUID]) -> ChatRecord:
"""Чат и его участники появляются одной транзакцией.
Неизвестный участник нарушает внешний ключ — транзакция откатывается
целиком, поэтому «чат без участников» или «чат с чужаком» не возникает.
"""
chat_id = uuid4()
row = (
await self._session.execute(
insert(CHATS).values(id=chat_id, title=title).returning(*_chat_columns())
)
).one()
try:
await self._session.execute(
insert(CHAT_MEMBERS),
[{"chat_id": chat_id, "user_id": member_id} for member_id in member_ids],
)
except IntegrityError as error:
if _sqlstate(error) != FOREIGN_KEY_VIOLATION:
raise
# Нарушенный внешний ключ обрывает транзакцию: откат снимает и уже
# вставленный чат, поэтому неполного чата в базе не остаётся.
await self._session.rollback()
raise UnknownMembers(member_ids) from None
await self._session.commit()
return ChatRecord(
id=row.id,
title=row.title,
member_ids=tuple(sorted(member_ids, key=lambda item: item.int)),
created_at=row.created_at,
)
async def chat_for_member(self, chat_id: UUID, user_id: UUID) -> ChatRecord | None:
"""Чат глазами участника: чужой чат неотличим от несуществующего (404)."""
row = (
await self._session.execute(
select(*_chat_columns())
.select_from(CHATS.join(CHAT_MEMBERS, CHAT_MEMBERS.c.chat_id == CHATS.c.id))
.where(CHATS.c.id == chat_id, CHAT_MEMBERS.c.user_id == user_id)
.limit(1)
)
).first()
if row is None:
return None
members = await self._members_of([chat_id])
return ChatRecord(
id=row.id, title=row.title, member_ids=members[chat_id], created_at=row.created_at
)
async def list_chats(
self, user_id: UUID, after: Position | None, limit: int
) -> tuple[list[ChatRecord], bool]:
"""Страница чатов пользователя в порядке (created_at, id) и признак «есть ещё»."""
statement = (
select(*_chat_columns())
.select_from(CHATS.join(CHAT_MEMBERS, CHAT_MEMBERS.c.chat_id == CHATS.c.id))
.where(CHAT_MEMBERS.c.user_id == user_id)
)
rows = await self._page(statement, CHATS, after, limit)
more = len(rows) > limit
rows = rows[:limit]
members = await self._members_of([row.id for row in rows])
chats = [
ChatRecord(
id=row.id, title=row.title, member_ids=members[row.id], created_at=row.created_at
)
for row in rows
]
return chats, more
async def append_message(self, chat_id: UUID, sender_id: UUID, text: str) -> MessageRecord:
"""Время и идентификатор назначает база: ответ возвращает то, что записано."""
row = (
await self._session.execute(
insert(MESSAGES)
.values(id=uuid4(), chat_id=chat_id, sender_id=sender_id, text=text)
.returning(*_message_columns())
)
).one()
await self._session.commit()
return MessageRecord(
id=row.id,
chat_id=row.chat_id,
sender_id=row.sender_id,
text=row.text,
created_at=row.created_at,
)
async def list_messages(
self, chat_id: UUID, after: Position | None, limit: int
) -> tuple[list[MessageRecord], bool]:
"""Страница истории чата от старых к новым и признак «есть ещё»."""
statement = select(*_message_columns()).where(MESSAGES.c.chat_id == chat_id)
rows = await self._page(statement, MESSAGES, after, limit)
more = len(rows) > limit
messages = [
MessageRecord(
id=row.id,
chat_id=row.chat_id,
sender_id=row.sender_id,
text=row.text,
created_at=row.created_at,
)
for row in rows[:limit]
]
return messages, more
async def _page(
self, statement: Select, table, after: Position | None, limit: int
) -> list[Row]:
"""Забирает limit+1 строк: лишняя строка и означает «есть ещё»."""
if after is not None:
statement = statement.where(_after_predicate(table.c.created_at, table.c.id, after))
result = await self._session.execute(
statement.order_by(table.c.created_at, table.c.id).limit(limit + 1)
)
return list(result)
async def _members_of(self, chat_ids: Sequence[UUID]) -> dict[UUID, tuple[UUID, ...]]:
"""Состав участников страницы чатов одним запросом, без N+1."""
if not chat_ids:
return {}
rows = await self._session.execute(
select(CHAT_MEMBERS.c.chat_id, CHAT_MEMBERS.c.user_id)
.where(CHAT_MEMBERS.c.chat_id.in_(chat_ids))
.order_by(CHAT_MEMBERS.c.chat_id, CHAT_MEMBERS.c.user_id)
)
grouped: dict[UUID, list[UUID]] = {}
for chat_id, user_id in rows:
grouped.setdefault(chat_id, []).append(user_id)
return {chat_id: tuple(members) for chat_id, members in grouped.items()}
+1
View File
@@ -0,0 +1 @@
"""Маршруты HTTP API: только разбор запроса, вызов зависимостей и сборка ответа."""
+51
View File
@@ -0,0 +1,51 @@
"""Вход по Basic и отзыв текущей сессии."""
from __future__ import annotations
from fastapi import APIRouter, Response, status
from ..deps import BasicCredentialsDep, BearerToken, RepositoryDep, SessionsDep
from ..errors import BASIC_CHALLENGE, unauthorized
from ..models import Session
from ..security import spend_verification_time, verify_password
router = APIRouter(prefix="/api/v1/auth/sessions", tags=["auth"])
INVALID_CREDENTIALS = "Неверный username или пароль"
@router.post("", status_code=status.HTTP_201_CREATED, summary="Вход: Basic username:password")
async def create_session(
credentials: BasicCredentialsDep,
repository: RepositoryDep,
sessions: SessionsDep,
) -> Session:
"""Проверяет пароль и выдаёт opaque-токен сессии; тело запроса не читается.
Неизвестный пользователь и неверный пароль неразличимы: одинаковый 401 с
Basic-челленджем и одинаковая затрата времени на KDF.
"""
found = await repository.credentials_for(credentials.username)
if found is None:
await spend_verification_time()
raise unauthorized(INVALID_CREDENTIALS, challenge=BASIC_CHALLENGE)
user, password_hash = found
if not await verify_password(credentials.password, password_hash):
raise unauthorized(INVALID_CREDENTIALS, challenge=BASIC_CHALLENGE)
issued = await sessions.create(user.id)
return Session.from_issued(issued, user)
@router.delete(
"/current",
status_code=status.HTTP_204_NO_CONTENT,
summary="Отозвать текущую сессию",
)
async def revoke_session(token: BearerToken, sessions: SessionsDep) -> Response:
"""Отзыв действует сразу: тот же токен после него даёт 401.
Ответ пустой (204), поэтому клиент не получает ни тела, ни нового состояния
сессии. Отзыв не трогает PostgreSQL: удаление ключа в Valkey атомарно.
"""
if not await sessions.revoke(token):
raise unauthorized("Сессия не найдена или истекла")
return Response(status_code=status.HTTP_204_NO_CONTENT)
+55
View File
@@ -0,0 +1,55 @@
"""Создание, список и чтение чатов."""
from __future__ import annotations
from typing import Annotated
from uuid import UUID
from fastapi import APIRouter, Path, Query, status
from ..access import visible_chat
from ..cursor import KIND_CHATS
from ..deps import CursorsDep, CurrentUser, RepositoryDep
from ..domain import UnknownMembers
from ..errors import invalid_request
from ..models import DEFAULT_LIMIT, MAX_LIMIT, Chat, ChatPage, CreateChat
from ..pagination import build_next_cursor, decoded_cursor
router = APIRouter(prefix="/api/v1/chats", tags=["chats"])
@router.post("", status_code=status.HTTP_201_CREATED, summary="Создать чат")
async def create_chat(payload: CreateChat, repository: RepositoryDep, user: CurrentUser) -> Chat:
"""Создаёт чат; состав участников задаётся при создании и не меняется."""
if user.id not in payload.member_ids:
raise invalid_request("Создатель чата обязан входить в member_ids")
try:
record = await repository.create_chat(payload.title, payload.member_ids)
except UnknownMembers:
raise invalid_request("member_ids содержит неизвестных пользователей") from None
return Chat.from_record(record)
@router.get("", summary="Чаты текущего пользователя")
async def list_chats(
repository: RepositoryDep,
cursors: CursorsDep,
user: CurrentUser,
limit: Annotated[int, Query(ge=1, le=MAX_LIMIT)] = DEFAULT_LIMIT,
cursor: Annotated[str | None, Query(min_length=1)] = None,
) -> ChatPage:
"""Список видимых чатов по (created_at, id) по возрастанию."""
scope = str(user.id)
after = decoded_cursor(cursors, cursor, kind=KIND_CHATS, scope=scope)
records, has_more = await repository.list_chats(user.id, after, limit)
return ChatPage.from_records(
records, build_next_cursor(cursors, KIND_CHATS, scope, records, has_more)
)
@router.get("/{chat_id}", summary="Получить доступный чат")
async def read_chat(
chat_id: Annotated[UUID, Path()],
repository: RepositoryDep,
user: CurrentUser,
) -> Chat:
return Chat.from_record(await visible_chat(repository, chat_id, user))
+38
View File
@@ -0,0 +1,38 @@
"""Проверки живости и готовности."""
from __future__ import annotations
from fastapi import APIRouter, Request
from ..deps import DatabaseDep, SessionsDep
from ..errors import unavailable
from ..models import Health
router = APIRouter(prefix="/health", tags=["health"])
@router.get("/live", summary="Процесс жив")
async def liveness() -> Health:
"""Проверяет только то, что процесс обслуживает запросы.
Зависимости здесь намеренно не проверяются: их отказ — не повод убивать
контейнер и устраивать цикл перезапусков.
"""
return Health()
@router.get("/ready", summary="Готов принимать трафик")
async def readiness(
request: Request,
database: DatabaseDep,
sessions: SessionsDep,
) -> Health:
"""Готовность = процесс не на остановке и критические зависимости отвечают.
Отказ зависимости превращается в 503 общим обработчиком: у готовности и у
бизнес-операций один и тот же признак неработоспособности.
"""
if getattr(request.app.state, "draining", False):
raise unavailable("Сервис завершает работу и не принимает новые запросы")
await database.ping()
await sessions.ping()
return Health()
+46
View File
@@ -0,0 +1,46 @@
"""Отправка и чтение истории сообщений."""
from __future__ import annotations
from typing import Annotated
from uuid import UUID
from fastapi import APIRouter, Path, Query, status
from ..access import visible_chat
from ..cursor import KIND_MESSAGES
from ..deps import CursorsDep, CurrentUser, RepositoryDep
from ..models import DEFAULT_LIMIT, MAX_LIMIT, CreateMessage, Message, MessagePage
from ..pagination import build_next_cursor, decoded_cursor
router = APIRouter(prefix="/api/v1/chats/{chat_id}/messages", tags=["messages"])
@router.post("", status_code=status.HTTP_201_CREATED, summary="Отправить сообщение")
async def create_message(
chat_id: Annotated[UUID, Path()],
payload: CreateMessage,
repository: RepositoryDep,
user: CurrentUser,
) -> Message:
"""Отправитель выводится из идентификации; sender_id в теле не принимается."""
await visible_chat(repository, chat_id, user)
return Message.from_record(await repository.append_message(chat_id, user.id, payload.text))
@router.get("", summary="Сообщения по (created_at, id) по возрастанию")
async def list_messages(
chat_id: Annotated[UUID, Path()],
repository: RepositoryDep,
cursors: CursorsDep,
user: CurrentUser,
limit: Annotated[int, Query(ge=1, le=MAX_LIMIT)] = DEFAULT_LIMIT,
cursor: Annotated[str | None, Query(min_length=1)] = None,
) -> MessagePage:
"""Keyset-пагинация: страница читается по индексу, предыдущие не повторяются."""
await visible_chat(repository, chat_id, user)
scope = str(chat_id)
after = decoded_cursor(cursors, cursor, kind=KIND_MESSAGES, scope=scope)
records, has_more = await repository.list_messages(chat_id, after, limit)
return MessagePage.from_records(
records, build_next_cursor(cursors, KIND_MESSAGES, scope, records, has_more)
)
+34
View File
@@ -0,0 +1,34 @@
"""Регистрация и текущий пользователь."""
from __future__ import annotations
from fastapi import APIRouter, status
from ..deps import CurrentUser, RepositoryDep
from ..errors import conflict
from ..models import CreateUser, User
from ..security import hash_password
router = APIRouter(prefix="/api/v1/users", tags=["users"])
USERNAME_TAKEN = "username уже занят"
@router.post("", status_code=status.HTTP_201_CREATED, summary="Создать пользователя")
async def register_user(payload: CreateUser, repository: RepositoryDep) -> User:
"""Регистрация публична; username уникален, повтор даёт 409."""
if await repository.username_taken(payload.username):
# Предпроверка экономит KDF на заведомо занятом username; гонку закрывает
# уникальный индекс в create_user, поэтому оба пути дают один и тот же 409.
raise conflict(USERNAME_TAKEN)
record = await repository.create_user(
payload.username, payload.display_name, await hash_password(payload.password)
)
if record is None:
raise conflict(USERNAME_TAKEN)
return User.from_record(record)
@router.get("/me", summary="Текущий пользователь")
async def read_current_user(user: CurrentUser) -> User:
"""Владелец Bearer-сессии; пароль и хэш пароля наружу не выходят."""
return User.from_record(user)
+84
View File
@@ -0,0 +1,84 @@
"""Описание таблиц PostgreSQL: один источник истины для запросов и миграций."""
from __future__ import annotations
from sqlalchemy import (
CheckConstraint,
Column,
ForeignKey,
Index,
MetaData,
Table,
Text,
UniqueConstraint,
text,
)
from sqlalchemy.dialects.postgresql import TIMESTAMP, UUID
METADATA = MetaData()
USERS = Table(
"users",
METADATA,
Column("id", UUID(as_uuid=True), primary_key=True),
Column("username", Text, nullable=False),
Column("display_name", Text, nullable=False),
Column("password_hash", Text, nullable=False),
Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("now()")),
UniqueConstraint("username", name="uq_users_username"),
CheckConstraint(r"username ~ '^[a-z0-9_]{3,32}$'", name="ck_users_username_format"),
CheckConstraint(
"char_length(display_name) BETWEEN 1 AND 100", name="ck_users_display_name_length"
),
)
CHATS = Table(
"chats",
METADATA,
Column("id", UUID(as_uuid=True), primary_key=True),
Column("title", Text, nullable=False),
Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("now()")),
CheckConstraint("char_length(title) BETWEEN 1 AND 100", name="ck_chats_title_length"),
)
CHAT_MEMBERS = Table(
"chat_members",
METADATA,
Column(
"chat_id",
UUID(as_uuid=True),
ForeignKey("chats.id", name="fk_chat_members_chat", ondelete="CASCADE"),
primary_key=True,
),
Column(
"user_id",
UUID(as_uuid=True),
ForeignKey("users.id", name="fk_chat_members_user", ondelete="RESTRICT"),
primary_key=True,
),
Index("ix_chat_members_user_id_chat_id", "user_id", "chat_id"),
)
MESSAGES = Table(
"messages",
METADATA,
Column("id", UUID(as_uuid=True), primary_key=True),
Column(
"chat_id",
UUID(as_uuid=True),
ForeignKey("chats.id", name="fk_messages_chat", ondelete="CASCADE"),
nullable=False,
),
Column(
"sender_id",
UUID(as_uuid=True),
ForeignKey("users.id", name="fk_messages_sender", ondelete="RESTRICT"),
nullable=False,
),
Column("text", Text, nullable=False),
Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("now()")),
CheckConstraint(
"text <> '' AND char_length(text) <= 4000", name="ck_messages_text_length"
),
# Порядок истории (created_at, id) и keyset-предикат обслуживает один индекс.
Index("ix_messages_chat_id_created_at_id", "chat_id", "created_at", "id"),
)
+119
View File
@@ -0,0 +1,119 @@
"""Пароли и токены: argon2id для пароля, случайный opaque-токен для доступа.
Пароль не хранится и не передаётся дальше: в базе лежит только строка argon2id.
KDF считает десятки миллисекунд, поэтому вызывается в рабочем потоке — цикл
событий не должен ждать хэширование.
"""
from __future__ import annotations
import base64
import binascii
import hashlib
import secrets
from functools import lru_cache
import anyio
from argon2 import PasswordHasher
from argon2.exceptions import Argon2Error, InvalidHashError
# Минимальные параметры Argon2id из OWASP Password Storage Cheat Sheet:
# m=19456 КиБ (19 МиБ), t=2, p=1. Память на проверку ограничена осознанно.
TIME_COST = 2
MEMORY_COST_KIB = 19456
PARALLELISM = 1
HASH_BYTES = 32
SALT_BYTES = 16
TOKEN_BYTES = 32
TOKEN_MIN_LENGTH = 32
BASIC_SCHEME = "basic"
BEARER_SCHEME = "bearer"
_DUMMY_PASSWORD = "messenger-dummy-password-never-matches"
_hasher = PasswordHasher(
time_cost=TIME_COST,
memory_cost=MEMORY_COST_KIB,
parallelism=PARALLELISM,
hash_len=HASH_BYTES,
salt_len=SALT_BYTES,
)
def _hash(password: str) -> str:
return _hasher.hash(password)
def _verify(password: str, stored_hash: str) -> bool:
"""True только при совпадении; неподходящий или испорченный хэш — тоже «нет»."""
try:
return _hasher.verify(stored_hash, password)
except (Argon2Error, InvalidHashError):
return False
@lru_cache(maxsize=1)
def _dummy_hash() -> str:
"""Хэш-заглушка: нужен, чтобы ответ про неизвестного пользователя стоил столько же."""
return _hash(_DUMMY_PASSWORD)
async def hash_password(password: str) -> str:
"""Хэширует пароль; длина пароля ограничена контрактом, усечения нет."""
return await anyio.to_thread.run_sync(_hash, password)
async def verify_password(password: str, stored_hash: str) -> bool:
return await anyio.to_thread.run_sync(_verify, password, stored_hash)
async def spend_verification_time() -> None:
"""Выполняет KDF впустую: время ответа не выдаёт существование пользователя."""
await anyio.to_thread.run_sync(_verify, _DUMMY_PASSWORD, _dummy_hash())
def new_token() -> str:
"""Opaque-токен сессии: 256 бит энтропии, длина не меньше требуемых 32 символов."""
return secrets.token_urlsafe(TOKEN_BYTES)
def token_fingerprint(token: str) -> str:
"""Ключ, под которым сессия лежит в хранилище: сам токен там не появляется."""
return hashlib.sha256(token.encode("utf-8")).hexdigest()
def _credentials(header: str | None, scheme: str) -> str | None:
"""Хвост заголовка Authorization, если схема совпала; иначе None."""
if not header:
return None
name, separator, value = header.strip().partition(" ")
if not separator or name.lower() != scheme:
return None
value = value.strip()
return value or None
def parse_basic(header: str | None) -> tuple[str, str] | None:
"""Разбирает `Authorization: Basic ...` в пару (username, password).
None означает «заголовка нет, схема не та или значение испорчено»; наружу все
эти случаи дают один и тот же 401, поэтому различать их незачем.
"""
encoded = _credentials(header, BASIC_SCHEME)
if encoded is None:
return None
try:
decoded = base64.b64decode(encoded + "=" * (-len(encoded) % 4), validate=True)
text = decoded.decode("utf-8")
except (binascii.Error, ValueError):
return None
username, separator, password = text.partition(":")
if not separator or not username:
return None
return username, password
def parse_bearer(header: str | None) -> str | None:
"""Токен из `Authorization: Bearer ...`; None — если заголовок не подходит."""
return _credentials(header, BEARER_SCHEME)
+122
View File
@@ -0,0 +1,122 @@
"""Хранилище сессий в Valkey: opaque-токен → состояние с абсолютным временем жизни.
Ключ строится из sha256 токена, поэтому в дампе и в `MONITOR` нет действующих
токенов — есть только их отпечатки. TTL выставляет сам сервер (`SET ... EX`),
а время истечения хранится абсолютным: перезапуск процесса или сервера срок
жизни сессии не продлевает.
"""
from __future__ import annotations
import json
from dataclasses import dataclass
from datetime import datetime, timedelta
from typing import Protocol
from uuid import UUID
from redis.asyncio import Redis
from .domain import parse_rfc3339_z, rfc3339_z, utc_now
from .security import new_token, token_fingerprint
SESSION_KEY_PREFIX = "messenger:session:"
@dataclass(frozen=True)
class SessionState:
"""Состояние сессии: владелец и границы жизни."""
user_id: UUID
created_at: datetime
expires_at: datetime
@dataclass(frozen=True)
class IssuedSession:
"""Выданная сессия: сам токен клиент видит ровно один раз."""
token: str
state: SessionState
class SessionStore(Protocol):
"""Контракт хранилища сессий: его выполняет Valkey, подменяется в тестах."""
async def create(self, user_id: UUID) -> IssuedSession: ...
async def resolve(self, token: str) -> SessionState | None: ...
async def revoke(self, token: str) -> bool: ...
async def ping(self) -> None: ...
async def close(self) -> None: ...
def _key(token: str) -> str:
return SESSION_KEY_PREFIX + token_fingerprint(token)
def _state_of(payload: str) -> SessionState | None:
"""Разбирает значение сессии; испорченное значение равносильно её отсутствию."""
try:
data = json.loads(payload)
return SessionState(
user_id=UUID(data["user_id"]),
created_at=parse_rfc3339_z(data["created_at"]),
expires_at=parse_rfc3339_z(data["expires_at"]),
)
except (ValueError, KeyError, TypeError):
return None
class RedisSessionStore:
"""Сессии в Valkey/Redis с постоянным хранением (AOF).
Таймауты на сокет ограничены: недоступная зависимость обязана отвечать
отказом быстро, а не держать запрос до таймаута клиента.
"""
def __init__(self, url: str, ttl_seconds: int, timeout_seconds: float) -> None:
self._ttl_seconds = ttl_seconds
self._client = Redis.from_url(
url,
decode_responses=True,
socket_timeout=timeout_seconds,
socket_connect_timeout=timeout_seconds,
)
async def create(self, user_id: UUID) -> IssuedSession:
token = new_token()
created_at = utc_now()
expires_at = created_at + timedelta(seconds=self._ttl_seconds)
payload = json.dumps(
{
"user_id": str(user_id),
"created_at": rfc3339_z(created_at),
"expires_at": rfc3339_z(expires_at),
},
separators=(",", ":"),
sort_keys=True,
)
await self._client.set(_key(token), payload, ex=self._ttl_seconds)
return IssuedSession(token=token, state=SessionState(user_id, created_at, expires_at))
async def resolve(self, token: str) -> SessionState | None:
"""Состояние действующей сессии; None — токен неизвестен или срок истёк."""
payload = await self._client.get(_key(token))
if payload is None:
return None
state = _state_of(payload)
if state is None or state.expires_at <= utc_now():
return None
return state
async def revoke(self, token: str) -> bool:
"""Отзыв: GETDEL проверяет и удаляет одной атомарной операцией."""
return await self._client.getdel(_key(token)) is not None
async def ping(self) -> None:
await self._client.ping()
async def close(self) -> None:
await self._client.aclose()
+98
View File
@@ -0,0 +1,98 @@
# Собственные проверки лабораторной 2
Здесь лежит то, что не входит в публичный `tests/`: проверки уровня 4, эксперименты
с планами запросов и инфраструктурные проверки стенда. Публичные тесты остаются
источником истины по контракту — эти ничего не подменяют и не «исправляют».
```sh
# Все проверки одной командой (стенд должен быть поднят):
make student-test BASE_URL=http://127.0.0.1:8080
# Отдельный модуль:
python3 -u -X utf8 -m unittest discover -s student-tests -t student-tests -p 'test_expiry.py' -v
# Проверки, которые останавливают контейнеры, требуют явного разрешения:
ALLOW_OUTAGE=1 python3 -u -X utf8 -m unittest discover -s student-tests -t student-tests -p 'test_dependency_outage.py' -v
# Отказы жёстче остановки (SIGKILL процесса и контейнера) — отдельным скриптом:
python3 -u -X utf8 student-tests/valkey_crash.py
```
`python3 -u -X utf8` не украшение. Первое снимает блочную буферизацию stdout: без
него печать самих тестов собирается в конце и в отчёте unittest оказывается не на
своём месте. Второе задаёт кодировку вывода на Windows, где локаль иначе решает,
что кириллица в консоли — это cp1251.
**Почему `student-tests/`, а не `scripts/`.** `scripts/check_contract.py` читает
`scripts/*.py`, `tests/*.py` и все `*.json` репозитория вызовом `read_text()` без
явной кодировки, то есть на Windows — в cp1251. Файл с русскими docstring'ами в
`scripts/` уронил бы `make check` на разборе синтаксиса. Поэтому свои проверки
живут в отдельном каталоге, а `scripts/` остаётся ASCII.
## Файлы
| Файл | Что проверяет | Тестов |
| --- | --- | --- |
| `harness.py` | Обвязка: клиент публичного `tests/client.py`, регистрация и вход, `psql` и `valkey-cli` внутри контейнеров, ожидание готовности. Не тест. | — |
| `run_all.py` | Запуск всего каталога, включая `--pattern` для одного модуля. Включает построчный вывод. Не тест. | — |
| `test_auth.py` | Пароль обязателен и ограничен 12..128 символами; границы 11/12/128/129; пароль из одних пробелов отклоняется, а пробелы по краям не обрезаются; кириллица и 128 эмодзи (доказательство, что KDF не режет по 72 байтам); `:` в пароле не ломает Basic; неверный пароль и неизвестный пользователь неразличимы; Basic на бизнес-маршруте → 401 **с Bearer**-челленджем; `X-User-Id` не даёт доступа. | 16 |
| `test_sessions.py` | Форма ответа `Session`; у одного пользователя несколько независимых сессий; отзыв одной не трогает другую; logout → 204 без тела; повтор logout → 401; 16 входов подряд дают 16 разных токенов. | 10 |
| `test_expiry.py` | Реальный срок жизни при `SESSION_TTL_SECONDS=3`: токен, выданный до смены TTL, продолжает работать после пересоздания контейнера; после истечения отвергается и на бизнес-маршруте, и на logout; ключ исчезает из Valkey сам; `expires_at` в ответе согласован с TTL ключа. Стенд возвращается к прежнему TTL. | 4 |
| `test_dependency_outage.py` | Остановка Valkey и остановка PostgreSQL: бизнес-маршруты и `/health/ready` отвечают 503 `unavailable` быстрее 2 с, `/health/live` остаётся 200, анонимом никто не становится; после старта тот же токен снова работает, данные на месте. Только при `ALLOW_OUTAGE=1`. | 3 |
| `test_registration_race.py` | 12 одновременных регистраций одного username → ровно один 201, остальные 409; в базе ровно одна строка. | 3 |
| `test_chat_atomicity.py` | Создание чата — одна транзакция: неизвестный участник, дубликат в списке и отсутствие создателя дают 400, и чата после этого нет. | 6 |
| `test_pagination.py` | Keyset-пагинация: каждая запись ровно один раз, порядок из контракта, `has_more`/`next_cursor`, лимиты 1 и 100, страница за концом истории, чужой курсор. | 9 |
| `test_access.py` | Чужой чат и несуществующий чат отвечают одинаково (404, никогда 403); участник видит историю, посторонний — нет. | 9 |
| `test_validation.py` | Некорректные запросы: всегда конверт `{"error":{...}}`, никогда 422 или трейсбек; лишние поля запрещены; битый JSON; пустые строки и слишком длинные значения; U+0000 в сохраняемых строках → 400, а не 503. | 16 |
| `test_health.py` | Что отвечают пробы здоровья, что им нужно для 200 и чего они не делают (live не зависит от зависимостей). | 6 |
| `verify_stack.py` | Инфраструктура работающего стенда: uid 10001 и PID 1 не от root, порты PG и Valkey не публикуются, секреты файлами и без утечки в `compose config`, AOF и `everysec`, схема, индексы и CHECK-ограничения, идемпотентность миграций, отсутствие секретов в логах, лимиты и `restart`. Не unittest — печатает проверки и возвращает код. | 52 проверки |
| `valkey_crash.py` | Падение, а не остановка: `kill -9` процессу valkey-server внутри контейнера (политика `restart` поднимает его сама, AOF возвращает сессию) и `docker compose kill` снаружи (контейнер не поднимается — нужен оператор). Заодно измеряет окно потери около секунды при `appendfsync everysec`. Управляет контейнерами, поэтому запускается явно. | 11 проверок |
| `seed_messages.py` | Засев данных для экспериментов: ≥10 000 сообщений, пары с одинаковым `created_at` для проверки ничьей по `id`, чаты разной длины. | — |
| `explain_queries.py` | Планы запросов: индекс на истории, отказ планировщика от него без индекса, цена `OFFSET` против keyset, индекс «моих чатов». Пишет PASS/FAIL по каждой проверке. | 20 проверок |
Всего 82 теста unittest: 79 идут всегда, 3 (отказ зависимостей) — только с
`ALLOW_OUTAGE=1`.
## Покрытие критериев уровня 4
| Критерий README | Чем закрыт |
| --- | --- |
| Valkey реально используется для сессий с TTL | `verify_stack.py` (ключ = sha256 токена, TTL ключа живой), `test_sessions.py`, `test_expiry.py`, доказательства 04 и 05 |
| Persistence, выдерживающее проверяемый рестарт | `test_dependency_outage.py::test_valkey_outage` (AOF возвращает сессию вместе с TTL), `valkey_crash.py` (то же после SIGKILL), `make test-persistence`, доказательства 02 и 05 |
| Параметризованные запросы, ограниченный pool, таймауты | `verify_stack.py` (лимиты и политика), доказательство 06 (бюджет таймаутов на живом отказе) |
| Гонка регистрации одинакового username | `test_registration_race.py` |
| Rollback составной операции | `test_chat_atomicity.py` |
| Индекс обоснован `EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщениях | `seed_messages.py` + `explain_queries.py`, доказательства 07 и 08 |
| Пагинация не сканирует всю историю | `explain_queries.py` (keyset против `OFFSET`), `test_pagination.py` |
| Автопроверка expiry при коротком TTL | `test_expiry.py` |
| Logout | `test_sessions.py` |
| Неверный пароль | `test_auth.py` |
| Недоступность Redis/БД | `test_dependency_outage.py` |
## Грабли этого стенда
**`127.0.0.1` вместо `localhost`.** На Windows `localhost` сначала разрешается в
`::1`, и каждый запрос к `127.0.0.1:8080` после этого платит за откат IPv6 → IPv4 —
около 2 с на запрос. Для проверок, которые считают время (отказ зависимостей,
истечение срока), это сопоставимо с измеряемым эффектом, поэтому здесь везде
`127.0.0.1`. Публичные тесты по умолчанию ходят на `localhost` — это их право.
**`ALLOW_OUTAGE=1`.** Модуль отказа останавливает контейнеры. Без флага он
пропускается, и unittest печатает его как skipped, а не как пройденный: пропуск,
выданный за успех, — это ложное доказательство. Каждый тест возвращает контейнеры
на место в `finally`, а `restore()` дожидается `/health/ready`.
**Короткий TTL возвращается на место.** `test_expiry.py` пересоздаёт сервис api с
`SESSION_TTL_SECONDS=3` и в `tearDownClass` возвращает прежнее значение; если
тест упал между этими точками, стенд останется с TTL в 3 секунды — лечится
`docker compose up -d --force-recreate api`.
**Make и переменные окружения.** В этом окружении (MSYS/Git Bash на Windows) `make`
не передаёт дочерним процессам ни `VAR=... make`, ни `export VAR` — работают
только переопределения переменных Make в командной строке. Поэтому флаги тестов
передаются как `PYTHON="python3 -X utf8"` и `BASE_URL=...`, а `ALLOW_OUTAGE`
приходится задавать при прямом запуске `python3 -m unittest`, минуя make.
**Секреты в выводе.** Ни один модуль не печатает токены, пароли и содержимое
`secrets/`; `verify_stack.py` отдельно проверяет, что их нет в логах контейнеров.
Доказательства в `evidence/` собраны из такого вывода.
+445
View File
@@ -0,0 +1,445 @@
#!/usr/bin/env python3
"""Планы запросов на засеянных данных: индекс, порядок и цена OFFSET.
python student-tests/seed_messages.py # один раз, ~10 000 сообщений
python student-tests/explain_queries.py # все планы
python student-tests/explain_queries.py --only chats # только список чатов
Скрипт проверяет не «индекс существует», а «индекс используется»: он берёт те же
по форме запросы, что отправляет `src/messenger/repository.py`, и смотрит на
`EXPLAIN (ANALYZE, BUFFERS, VERBOSE)`.
Контрпример без индекса выполняется внутри транзакции с `DROP INDEX ... ROLLBACK`,
поэтому схема в базе не меняется. План каждого контрольного запроса снимается
дважды — текстом для отчёта и JSON для вердиктов: psql возвращает план набором
строк, и разложить его на два формата в одном вызове нельзя.
"""
from __future__ import annotations
import argparse
import json
import sys
from pathlib import Path
HERE = Path(__file__).resolve().parent
if str(HERE) not in sys.path:
sys.path.insert(0, str(HERE))
import harness # noqa: E402 (путь добавлен выше)
MESSAGES_INDEX = "ix_messages_chat_id_created_at_id"
CHATS_INDEX = "ix_chat_members_user_id_chat_id"
DEFAULT_PAGE = 200
PLAN_OPTIONS = "ANALYZE, BUFFERS, VERBOSE, FORMAT "
MESSAGE_COLUMNS = ("messages.id, messages.chat_id, messages.sender_id, "
"messages.text, messages.created_at")
CHECKS: list[tuple[bool, str, str]] = []
def say(message: str = "") -> None:
print(message, flush=True)
def section(title: str) -> None:
say()
say("=" * 72)
say(title)
say("=" * 72)
def check(ok: bool, what: str, detail: str = "") -> bool:
CHECKS.append((ok, what, detail))
say(" [%s] %s%s" % ("OK" if ok else "FAIL", what, (" — " + detail) if detail else ""))
return ok
def show_plan(sql: str) -> None:
"""Печатает текстовый план: его читает человек."""
say(" $ %s" % " ".join(sql.split()))
for line in harness.psql("EXPLAIN (%s TEXT) %s" % (PLAN_OPTIONS, sql), timeout=600).splitlines():
say(" " + line.rstrip())
def plan_json(sql: str) -> dict:
"""Возвращает разобранный план: по нему выносятся вердикты."""
return parse_plan(harness.psql("EXPLAIN (%s JSON) %s" % (PLAN_OPTIONS, sql), timeout=600))
def parse_plan(raw: str) -> dict:
"""Вырезает JSON-план из вывода psql.
Внутри транзакции psql печатает ещё и теги команд (BEGIN, SET, ROLLBACK),
поэтому брать весь stdout нельзя.
"""
start, end = raw.find("["), raw.rfind("]")
if start < 0 or end < 0:
raise ValueError("в выводе psql нет JSON-плана: %r" % raw[:200])
return json.loads(raw[start:end + 1])[0]
def nodes(plan: dict) -> list[dict]:
"""Все узлы плана, включая вложенные."""
found = [plan["Plan"]]
index = 0
while index < len(found):
found.extend(found[index].get("Plans", []))
index += 1
return found
def node_types(plan: dict) -> str:
return ", ".join(node["Node Type"] for node in nodes(plan))
def scans(plan: dict, relation: str) -> list[dict]:
"""Узлы, которыми читается указанное отношение.
Вопрос «читается ли таблица целиком» относится к конкретной таблице: в
запросе списка чатов планировщик вправе перебрать маленькую `chats` и всё
равно взять `chat_members` по индексу. Поэтому вердикты выносятся не по
плану целиком, а по узлам одной таблицы.
"""
return [node for node in nodes(plan) if node.get("Relation Name") == relation]
def scan_types(plan: dict, relation: str) -> str:
"""Типы узлов чтения отношения: `Seq Scan` здесь — плохой знак."""
return ", ".join(node["Node Type"] for node in scans(plan, relation)) or "узлов нет"
def rows_touched(plan: dict) -> int:
"""Сколько строк прошло через самый работящий узел плана."""
return max(node.get("Actual Rows", 0) for node in nodes(plan))
def rows_examined(plan: dict, relation: str) -> int:
"""Сколько строк отношение реально просмотрело.
Строки, отброшенные фильтром, тоже прочитаны — в `Actual Rows` они не
попадают, поэтому складываются обе величины.
"""
return sum(node.get("Actual Rows", 0)
+ node.get("Rows Removed by Filter", 0)
+ node.get("Rows Removed by Index Recheck", 0)
for node in scans(plan, relation))
def describe(plan: dict) -> str:
return "execution %.3f ms, shared hit %d, read %d" % (
plan["Execution Time"],
plan["Plan"].get("Shared Hit Blocks", 0),
plan["Plan"].get("Shared Read Blocks", 0),
)
def without_index(index: str, options: str, sql: str) -> str:
"""Один контрольный запрос без индекса; ROLLBACK возвращает схему как была."""
return harness.psql(
"BEGIN; DROP INDEX %s; EXPLAIN (%s %s) %s ROLLBACK;" % (index, PLAN_OPTIONS, options, sql),
timeout=600,
)
def page_position(chat_id: str, offset: int) -> tuple[str, str]:
"""Пара (created_at, id) на указанной позиции: это и есть курсор страницы.
Для поиска пары OFFSET уместен: измеряется не он, а запрос страницы.
"""
created_at, item_id = harness.psql(
"SELECT created_at, id FROM messages WHERE chat_id = '%s' "
"ORDER BY created_at, id OFFSET %d LIMIT 1;" % (chat_id, offset)
).strip().split("|")
return created_at, item_id
def keyset_query(chat_id: str, cursor: tuple[str, str], limit: int) -> str:
"""Тот же запрос, что собирает repository._page для истории чата."""
return (
"SELECT %s FROM messages WHERE chat_id = '%s' "
"AND (created_at, id) > ('%s'::timestamptz, '%s'::uuid) "
"ORDER BY created_at, id LIMIT %d;" % (MESSAGE_COLUMNS, chat_id, cursor[0], cursor[1], limit)
)
def offset_query(chat_id: str, offset: int, limit: int) -> str:
"""Страница «с начала, но пропусти N» — так делать нельзя."""
return (
"SELECT %s FROM messages WHERE chat_id = '%s' "
"ORDER BY created_at, id OFFSET %d LIMIT %d;" % (MESSAGE_COLUMNS, chat_id, offset, limit)
)
def chats_query(user_id: str, limit: int) -> str:
"""Тот же запрос, что собирает repository.list_chats."""
return (
"SELECT chats.id, chats.title, chats.created_at "
"FROM chats JOIN chat_members ON chats.id = chat_members.chat_id "
"WHERE chat_members.user_id = '%s'::uuid "
"ORDER BY chats.created_at, chats.id LIMIT %d;" % (user_id, limit)
)
def history_plans(arguments) -> bool:
"""Разделы 2–4: страница истории чата и её цена без индекса.
False — данных для эксперимента нет; что делать, уже напечатано.
"""
chat_id = arguments.chat_id or harness.psql(
"SELECT chat_id FROM messages GROUP BY chat_id ORDER BY count(*) DESC LIMIT 1;"
).strip()
if not chat_id:
say(" В базе нет сообщений. Сначала запустите seed_messages.py.")
return False
history = int(harness.psql("SELECT count(*) FROM messages WHERE chat_id = '%s';" % chat_id))
say(" чат %s: %d сообщений" % (chat_id, history))
if history < 1000:
say(" На короткой истории планировщик выберет последовательное чтение, и")
say(" эксперимент ничего не покажет. Запустите seed_messages.py.")
return False
position = history - arguments.page_size
cursor = page_position(chat_id, position)
say(" позиция страницы: %d, курсор (created_at, id) = (%s, %s)" % (position, *cursor))
say(" размер messages: %s, индекс %s: %s"
% (harness.psql("SELECT pg_size_pretty(pg_total_relation_size('messages'));").strip(),
MESSAGES_INDEX,
harness.psql("SELECT pg_size_pretty(pg_relation_size('%s'));" % MESSAGES_INDEX).strip()))
duplicates = harness.psql(
"SELECT count(*) FROM (SELECT created_at FROM messages WHERE chat_id = '%s' "
"GROUP BY created_at HAVING count(*) > 1) AS shared;" % chat_id).strip()
say(" моментов времени, которые делят несколько сообщений: %s "
"(порядок обязан разрешать ничью по id)" % duplicates)
section("2. Страница истории по курсору (keyset)")
keyset_sql = keyset_query(chat_id, cursor, arguments.page_size)
show_plan(keyset_sql)
keyset = plan_json(keyset_sql)
check(MESSAGES_INDEX in json.dumps(keyset), "использован именно %s" % MESSAGES_INDEX)
check("Seq Scan" not in node_types(keyset),
"история не читается последовательно", node_types(keyset))
removed = sum(node.get("Rows Removed by Filter", 0) for node in nodes(keyset))
check(removed < 10 * arguments.page_size,
"курсор отсекает строки индексом, а не фильтром",
"Rows Removed by Filter: %d" % removed)
check(rows_touched(keyset) <= 2 * arguments.page_size,
"прочитано не больше двух страниц", "%d строк" % rows_touched(keyset))
say(" %s" % describe(keyset))
if "Sort" in node_types(keyset):
estimate = keyset["Plan"]["Plans"][0].get("Plan Rows", 0)
say(" Планировщик предпочёл bitmap-чтение и сортировку: по его оценке под")
say(" условие попадает %d строк, и отсортировать их дешевле, чем идти по"
% estimate)
say(" индексу. Оценка занижена, но оба плана читают десятки блоков вместо")
say(" всей истории; на плане ниже видно, что порядок тоже даёт индекс.")
else:
say(" Сортировки в плане нет: порядок задаёт индекс.")
section("2б. Тот же запрос, когда bitmap-чтение выключено")
say(" $ BEGIN; SET LOCAL enable_bitmapscan = off; EXPLAIN (...); ROLLBACK;")
for line in harness.psql(
"BEGIN; SET LOCAL enable_bitmapscan = off; EXPLAIN (%s TEXT) %s ROLLBACK;"
% (PLAN_OPTIONS, keyset_sql), timeout=600
).splitlines():
say(" " + line.rstrip())
ordered = parse_plan(harness.psql(
"BEGIN; SET LOCAL enable_bitmapscan = off; EXPLAIN (%s JSON) %s ROLLBACK;"
% (PLAN_OPTIONS, keyset_sql), timeout=600))
check("Index Scan" in node_types(ordered) or "Index Only Scan" in node_types(ordered),
"индекс отдаёт страницу по порядку (Index Scan)", node_types(ordered))
check("Sort" not in node_types(ordered),
"сортировки нет: порядок (created_at, id) даёт индекс", node_types(ordered))
say(" %s" % describe(ordered))
say(" Оба плана читают десятки блоков вместо всей истории: индекс нужен не")
say(" «на всякий случай», а потому что без него страница требует полного чтения.")
section("3. Контрпример: тот же запрос без индекса")
say(" Индекс удаляется и возвращается внутри одной транзакции:")
say(" $ BEGIN; DROP INDEX %s; EXPLAIN (...); ROLLBACK;" % MESSAGES_INDEX)
for line in without_index(MESSAGES_INDEX, "TEXT", keyset_sql).splitlines():
say(" " + line.rstrip())
without = parse_plan(without_index(MESSAGES_INDEX, "JSON", keyset_sql))
check("Seq Scan" in scan_types(without, "messages"),
"без индекса появляется последовательное чтение", scan_types(without, "messages"))
check("Sort" in node_types(without), "без индекса появляется сортировка", node_types(without))
examined = rows_examined(keyset, "messages")
check(rows_examined(without, "messages") >= history,
"без индекса читается вся история чата",
"просмотрено %d строк" % rows_examined(without, "messages"))
check(examined < history // 10,
"с индексом просматривается малая доля истории",
"%d строк против %d" % (examined, history))
check(without["Execution Time"] > keyset["Execution Time"],
"индекс ускоряет страницу", "%.3f ms против %.3f ms"
% (keyset["Execution Time"], without["Execution Time"]))
say(" %s" % describe(without))
say(" ускорение: x%.1f" % (without["Execution Time"] / max(keyset["Execution Time"], 0.001)))
presence = harness.psql(
"SELECT count(*) FROM pg_indexes WHERE indexname = '%s';" % MESSAGES_INDEX).strip()
check(presence == "1", "ROLLBACK вернул схему: индекс на месте (найдено %s)" % presence)
section("4. OFFSET против курсора на той же позиции")
# Курсор указывает на последнюю отданную строку, поэтому её же пропускает
# OFFSET: так обе страницы обязаны вернуть ровно один и тот же набор.
offset_sql = offset_query(chat_id, position + 1, arguments.page_size)
show_plan(offset_sql)
offset = plan_json(offset_sql)
same_rows = harness.psql(keyset_sql).strip() == harness.psql(offset_sql).strip()
check(same_rows, "обе страницы возвращают одни и те же строки")
check(offset["Execution Time"] > keyset["Execution Time"],
"OFFSET медленнее курсора",
"%.3f ms против %.3f ms" % (offset["Execution Time"], keyset["Execution Time"]))
check(rows_touched(offset) >= position,
"OFFSET читает всё, что было до страницы", "%d строк" % rows_touched(offset))
say(" %s" % describe(offset))
say(" Задержка страницы по курсору не зависит от её номера, а OFFSET читает")
say(" всю предысторию заново на каждой странице.")
return True
def seeded_owner() -> str:
"""Владелец засеянного списка чатов — тот же пользователь, что и в длинной истории.
«Пользователя с наибольшим числом чатов» брать нельзя: у засеянного шумового
их 2000 из 3105, и планировщик там законно предпочтёт перебор. Такой
эксперимент показал бы не пользу индекса, а порог его применимости —
он вынесен в раздел 5б.
"""
return harness.psql(
"SELECT chat_members.user_id FROM messages "
"JOIN chat_members ON chat_members.chat_id = messages.chat_id "
"GROUP BY chat_members.user_id "
"ORDER BY count(messages.id) DESC, chat_members.user_id LIMIT 1;"
).strip()
def busiest_user() -> tuple[str, int]:
"""Пользователь с самой большой долей таблицы участников и число его чатов."""
row = harness.psql(
"SELECT user_id, count(*) FROM chat_members GROUP BY user_id "
"ORDER BY count(*) DESC, user_id LIMIT 1;"
).strip()
if not row:
return "", 0
user_id, count = row.split("|")
return user_id, int(count)
def selectivity_note(busiest: tuple[str, int], owner: str, members_total: int) -> None:
"""Раздел 5б: где индекс перестаёт быть выгодным.
Вердиктов здесь нет: план для пользователя с большой долей таблицы зависит
от статистики, и его дело — показать границу, а не подтвердить индекс.
"""
user_id, chats = busiest
section("5б. Справка: пользователь с большой долей таблицы")
if not user_id or user_id == owner:
say(" В данных нет пользователя, который делил бы таблицу участников так,")
say(" чтобы перебор оказался дешевле: индекс выгоден для всех.")
return
say(" %s — участник %d чатов из %d (%d%% таблицы)."
% (user_id, chats, members_total, round(100 * chats / members_total)))
say(" Здесь индекс не нужен, и планировщик его не берёт: перебрать %d строк" % members_total)
say(" дешевле, чем поднимать две тысячи строк по индексу. Это граница")
say(" применимости индекса, а не его дефект: у обычного пользователя чатов")
say(" мало, и индекс рассчитан на него.")
show_plan(chats_query(user_id, DEFAULT_PAGE))
say(" %s" % describe(plan_json(chats_query(user_id, DEFAULT_PAGE))))
def chats_plans(arguments, owner: str, busiest: tuple[str, int]) -> bool:
"""Разделы 5–6: список чатов пользователя и цена отказа от индекса."""
if not owner:
say(" В базе нет участников чатов. Сначала запустите seed_messages.py.")
return False
section("5. Список чатов пользователя")
chats_sql = chats_query(owner, arguments.page_size)
show_plan(chats_sql)
chats = plan_json(chats_sql)
check(CHATS_INDEX in json.dumps(chats), "использован именно %s" % CHATS_INDEX)
check("Seq Scan" not in scan_types(chats, "chat_members"),
"участники читаются по индексу, а не перебором",
scan_types(chats, "chat_members"))
members_total = int(harness.psql("SELECT count(*) FROM chat_members;"))
member_rows = rows_examined(chats, "chat_members")
check(member_rows < members_total,
"просмотрены участники пользователя, а не все строки таблицы",
"%d строк из %d" % (member_rows, members_total))
say(" %s" % describe(chats))
say(" Порядок в этом запросе задаёт таблица chats (created_at живёт в ней),")
say(" поэтому узел Sort ожидаем: индекс отдаёт только чаты пользователя, а")
say(" сортируются его строки, а не вся таблица. Убрать этот Sort можно было")
say(" бы дублированием created_at в chat_members, но это денормализация")
say(" ради сортировки небольшой выборки. Таблицу chats планировщик при этом")
say(" перебирает целиком — здесь это дешевле индекса, и на данных большего")
say(" размера план изменится.")
selectivity_note(busiest, owner, members_total)
section("6. Контрпример: список чатов без индекса")
say(" $ BEGIN; DROP INDEX %s; EXPLAIN (...); ROLLBACK;" % CHATS_INDEX)
for line in without_index(CHATS_INDEX, "TEXT", chats_sql).splitlines():
say(" " + line.rstrip())
chats_without = parse_plan(without_index(CHATS_INDEX, "JSON", chats_sql))
check("Seq Scan" in scan_types(chats_without, "chat_members"),
"без индекса участники перебираются целиком",
scan_types(chats_without, "chat_members"))
check(rows_examined(chats_without, "chat_members") > member_rows,
"индекс сокращает объём чтения",
"%d строк против %d" % (member_rows, rows_examined(chats_without, "chat_members")))
say(" %s" % describe(chats_without))
return True
def summary() -> int:
"""Итог по выполненным проверкам; он же код возврата."""
section("Итог")
for ok, what, detail in CHECKS:
say(" [%s] %s%s" % ("OK" if ok else "FAIL", what, (" — " + detail) if detail else ""))
failed = [what for ok, what, _ in CHECKS if not ok]
say()
say(" проверок: %d, провалено: %d" % (len(CHECKS), len(failed)))
say("РЕЗУЛЬТАТ: %s" % ("PASS" if not failed else "FAIL"))
return 0 if not failed else 1
def main() -> int:
parser = argparse.ArgumentParser(description="Планы запросов лабораторной 2")
parser.add_argument("--only", choices=("all", "messages", "chats"), default="all",
help="какие планы снимать (по умолчанию все)")
parser.add_argument("--chat-id", default="", help="чат с историей (по умолчанию самый длинный)")
parser.add_argument("--page-size", type=int, default=DEFAULT_PAGE)
arguments = parser.parse_args()
section("1. Данные под экспериментом")
say(" всего сообщений: %s" % harness.psql("SELECT count(*) FROM messages;").strip())
say(" всего чатов: %s, участников: %s"
% (harness.psql("SELECT count(*) FROM chats;").strip(),
harness.psql("SELECT count(*) FROM chat_members;").strip()))
owner = ""
busiest = ("", 0)
if arguments.only in ("all", "chats"):
busiest = busiest_user()
owner = seeded_owner() or busiest[0]
if owner:
say(" владелец засеянного списка чатов: %s, чатов у него %s"
% (owner, harness.psql(
"SELECT count(*) FROM chat_members WHERE user_id = '%s';" % owner).strip()))
done = True
if arguments.only in ("all", "messages"):
done = history_plans(arguments)
if done and arguments.only in ("all", "chats"):
done = chats_plans(arguments, owner, busiest)
return summary() if done else 1
if __name__ == "__main__":
try:
raise SystemExit(main())
except SystemExit:
raise
except Exception as error: # noqa: BLE001
say()
say("ОШИБКА: %s: %s" % (type(error).__name__, error))
raise SystemExit(1) from error
+238
View File
@@ -0,0 +1,238 @@
"""Общая обвязка собственных проверок: публичный клиент и помощники стенда.
Публичный клиент в tests/ импортируется, а не копируется: в нём уже закодированы
части контракта, нужные каждой проверке (схема ответа, конверт ошибки, эхо
X-Request-Id, челлендж WWW-Authenticate). Всё специфичное для лабораторной 2 -
инспекция docker, уникальные фикстуры, ожидание готовности - живёт здесь.
"""
from __future__ import annotations
import base64
import os
import subprocess
import sys
import time
import uuid
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
PUBLIC_TESTS = ROOT / "tests"
HERE = Path(__file__).resolve().parent
# Публичный клиент - обычный модуль в tests/, поэтому каталог попадает в путь импорта.
for _candidate in (str(PUBLIC_TESTS), str(HERE)):
if _candidate not in sys.path:
sys.path.insert(0, _candidate)
from client import Client, Failure # noqa: E402 (импорт должен идти после правки sys.path)
DEFAULT_TIMEOUT = 10.0
READY_TIMEOUT = 90.0
COMPOSE_TIMEOUT = 180.0
API_CONTAINER = "mtusi2026lab2-api-1"
POSTGRES_CONTAINER = "mtusi2026lab2-postgres-1"
VALKEY_CONTAINER = "mtusi2026lab2-valkey-1"
SESSION_KEY_PREFIX = "messenger:session:"
def client(timeout: float = DEFAULT_TIMEOUT) -> Client:
"""Клиент к BASE_URL - той же переменной, которую используют публичные тесты."""
return Client(os.environ.get("BASE_URL"), None, timeout)
def flag(name: str) -> bool:
"""Считает включённым 1/true/yes, всё остальное (включая отсутствие) - выключенным."""
return os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
def unique(label: str) -> str:
"""Имя пользователя, с которым никто другой в запуске не совпадёт."""
return "s_%s_%s" % (label, uuid.uuid4().hex[:12])
def fresh_password() -> str:
"""12..128 символов, разный при каждом вызове: чужой секрет не переиспользуется."""
return "Pw-" + uuid.uuid4().hex + "-" + uuid.uuid4().hex[:8]
def basic(username: str, secret: str) -> dict:
"""Заголовок Authorization для единственного эндпоинта, принимающего Basic."""
raw = "%s:%s" % (username, secret)
encoded = base64.b64encode(raw.encode("utf-8")).decode("ascii")
return {"Authorization": "Basic " + encoded}
def bearer(token: str) -> dict:
return {"Authorization": "Bearer " + token}
def register(api: Client, username: str, secret: str, display_name: str = "Студент") -> dict:
"""POST /users и возвращает созданного пользователя."""
return api.call(
"POST",
"/api/v1/users",
201,
body={"username": username, "display_name": display_name, "password": secret},
schema="User",
)["json"]
def login(api: Client, username: str, secret: str) -> dict:
"""POST /auth/sessions с Basic и возвращает тело Session."""
return api.call(
"POST", "/api/v1/auth/sessions", 201, headers=basic(username, secret), schema="Session"
)["json"]
def account(api: Client, label: str) -> dict:
"""Зарегистрированный пользователь и рабочая сессия, повторяет Client.user()."""
username = unique(label)
secret = fresh_password()
user = register(api, username, secret)
session = login(api, username, secret)
return {"id": user["id"], "user": user, "username": username, "password": secret,
"token": session["token"], "session": session}
def chat(api: Client, owner: dict, others: list, title: str = "Чат") -> dict:
members = [owner["id"]] + [item["id"] for item in others]
return api.call(
"POST", "/api/v1/chats", 201, actor=owner, body={"title": title, "member_ids": members},
schema="Chat",
)["json"]
def send(api: Client, actor: dict, chat_body: dict, text: str) -> dict:
return api.call(
"POST",
"/api/v1/chats/" + chat_body["id"] + "/messages",
201,
actor=actor,
body={"text": text},
schema="Message",
)["json"]
def all_messages(api: Client, actor: dict, chat_id: str, limit: int = 100) -> list:
"""Читает всю историю через курсор с жёсткой остановкой на случай цикла."""
items, cursor, seen = [], None, set()
for _ in range(1000):
path = "/api/v1/chats/%s/messages?limit=%d" % (chat_id, limit)
if cursor is not None:
if cursor in seen:
raise Failure("цикл курсора при чтении истории")
seen.add(cursor)
path += "&cursor=" + cursor
page = api.call("GET", path, actor=actor, schema="MessagePage")["json"]
items.extend(page["items"])
cursor = page["next_cursor"]
if cursor is None:
return items
raise Failure("пагинация истории вышла за защитный предел")
def all_chats(api: Client, actor: dict, limit: int = 100) -> list:
"""Читает весь список чатов через курсор с жёсткой остановкой на случай цикла."""
items, cursor, seen = [], None, set()
for _ in range(1000):
path = "/api/v1/chats?limit=%d" % limit
if cursor is not None:
if cursor in seen:
raise Failure("цикл курсора при чтении списка чатов")
seen.add(cursor)
path += "&cursor=" + cursor
page = api.call("GET", path, actor=actor, schema="ChatPage")["json"]
items.extend(page["items"])
cursor = page["next_cursor"]
if cursor is None:
return items
raise Failure("пагинация чатов вышла за защитный предел")
def docker_env() -> dict:
"""Окружение для docker CLI.
`make` под MSYS передаёт своим рецептам урезанное окружение без
PROGRAMW6432, а docker CLI ищет свои плагины в
%ProgramW6432%\\Docker\\cli-plugins - без этой переменной каждый вызов
`docker compose` отвечает "unknown command: docker compose".
"""
env = dict(os.environ)
if "PROGRAMW6432" not in env:
default = Path(env.get("SystemDrive", "C:") + "\\Program Files")
if (default / "Docker" / "cli-plugins").is_dir():
env["PROGRAMW6432"] = str(default)
return env
def compose(
*arguments: str, timeout: float = COMPOSE_TIMEOUT, env: dict | None = None
) -> subprocess.CompletedProcess:
"""Запускает `docker compose ...` из корня репозитория; вывод остаётся в результате.
`env` накладывается поверх текущего окружения - так проверка меняет
интерполируемую переменную вроде SESSION_TTL_SECONDS перед пересозданием сервиса.
"""
process_env = docker_env()
process_env.update(env or {})
return subprocess.run(
["docker", "compose", *arguments],
cwd=str(ROOT),
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=timeout,
env=process_env,
)
def docker_available() -> bool:
try:
return compose("version", timeout=60).returncode == 0
except (OSError, subprocess.SubprocessError):
return False
def container_running(name: str) -> bool:
result = compose("ps", "--status", "running", "--services", timeout=60)
return name in result.stdout.split()
def psql(sql: str, timeout: float = COMPOSE_TIMEOUT) -> str:
"""Выполняет один SQL-запрос внутри контейнера postgres и возвращает stdout."""
result = compose(
"exec", "-T", "postgres", "psql", "-U", "messenger", "-d", "messenger",
"-v", "ON_ERROR_STOP=1", "-At", "-c", sql, timeout=timeout,
)
if result.returncode != 0:
raise Failure("сбой psql: " + (result.stderr or result.stdout).strip()[:200])
return result.stdout
def valkey(*arguments: str, timeout: float = 60.0) -> str:
result = compose("exec", "-T", "valkey", "valkey-cli", *arguments, timeout=timeout)
if result.returncode != 0:
raise Failure("сбой valkey-cli: " + (result.stderr or result.stdout).strip()[:200])
return result.stdout.strip()
def wait_ready(timeout: float = READY_TIMEOUT) -> None:
"""Ждёт ответа /health/ready, чтобы перезапущенный стенд можно было использовать снова."""
api = client(timeout=5)
deadline = time.monotonic() + timeout
last = "попыток не было"
while time.monotonic() < deadline:
try:
api.call("GET", "/health/ready", schema="Health")
return
except (Failure, OSError) as exc:
last = str(exc)
time.sleep(0.5)
raise Failure("стенд не достиг готовности за %.0fs: %s" % (timeout, last))
def require_docker(test) -> None:
"""Пропускает проверку, которая управляет стендом, если docker CLI недоступен."""
if not docker_available():
test.skipTest("docker compose недоступен на этом хосте")
+49
View File
@@ -0,0 +1,49 @@
#!/usr/bin/env python3
"""Запуск всех собственных проверок лабораторной 2 одной командой.
python student-tests/run_all.py --base-url http://127.0.0.1:8080
Модуль `test_dependency_outage.py` останавливает контейнеры и без ALLOW_OUTAGE=1
пропускается: `unittest` печатает его как skipped, а не как пройденный. Проверки
истечения срока (`test_expiry.py`) пересоздают сервис api с коротким TTL — это
стенд, который они возвращают на место в tearDownClass.
"""
from __future__ import annotations
import argparse
import os
import sys
import unittest
from pathlib import Path
HERE = Path(__file__).resolve().parent
DEFAULT_BASE_URL = "http://127.0.0.1:8080"
def main() -> int:
parser = argparse.ArgumentParser(description="Собственные проверки лабораторной 2")
parser.add_argument("--base-url", default=os.environ.get("BASE_URL", DEFAULT_BASE_URL))
parser.add_argument("--pattern", default="test_*.py")
parser.add_argument("--quiet", action="store_true", help="краткий вывод")
arguments = parser.parse_args()
# harness.py читает адрес стенда из окружения.
os.environ["BASE_URL"] = arguments.base_url
if str(HERE) not in sys.path:
sys.path.insert(0, str(HERE))
# В файл stdout буферизуется блоками, и без этого печать самих тестов
# собралась бы в конце — отдельно от отчёта unittest, который пишется в stderr.
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(line_buffering=True)
print("BASE_URL =", arguments.base_url, flush=True)
suite = unittest.defaultTestLoader.discover(
str(HERE), pattern=arguments.pattern, top_level_dir=str(HERE)
)
result = unittest.TextTestRunner(verbosity=1 if arguments.quiet else 2).run(suite)
return 0 if result.wasSuccessful() else 1
if __name__ == "__main__":
raise SystemExit(main())
+198
View File
@@ -0,0 +1,198 @@
#!/usr/bin/env python3
"""Засев данных для экспериментов уровня 4: длинная история и длинный список чатов.
python student-tests/seed_messages.py --messages 10000 --chats 1000
Пользователя скрипт создаёт через публичный API — чтобы засеянную историю можно
было прочитать и по HTTP, а не только через psql. Объёмные данные заливаются
SQL-ом `generate_series`: 10 000 сообщений по HTTP заняли бы минуты и измерили
бы скорость клиента, а не базы.
Часть строк получает одинаковый `created_at` намеренно (`--tie`). Порядок
истории и списка чатов обязан разрешать ничью по `id`, и на данных, где время
уникально, эта часть запроса просто не выполняется.
Скрипт печатает идентификаторы созданного, чтобы `explain_queries.py` и
ручные запросы работали с теми же данными.
"""
from __future__ import annotations
import argparse
import os
import sys
import time
from pathlib import Path
HERE = Path(__file__).resolve().parent
if str(HERE) not in sys.path:
sys.path.insert(0, str(HERE))
import harness # noqa: E402 (путь добавлен выше)
DEFAULT_MESSAGES = 10000
DEFAULT_CHATS = 1000
DEFAULT_NOISE_CHATS = 2000
DEFAULT_TIE = 3
HISTORY_EPOCH = "2026-01-01 00:00:00+00"
CHATS_EPOCH = "2026-02-01 00:00:00+00"
HISTORY_TITLE = "seed history"
CHATS_TITLE_PREFIX = "seed chat "
NOISE_TITLE_PREFIX = "noise chat "
# Длины ограничены CHECK-ограничениями схемы: заголовок не длиннее 100 символов.
assert len(CHATS_TITLE_PREFIX) + 8 <= 100 and len(NOISE_TITLE_PREFIX) + 8 <= 100
def say(message: str = "") -> None:
print(message, flush=True)
def section(title: str) -> None:
say()
say("=" * 72)
say(title)
say("=" * 72)
def scalar(sql: str, timeout: float = 120) -> str:
"""Одно значение из psql: строка-статус `INSERT 0 1` в результат не попадает."""
return harness.psql(sql, timeout=timeout).strip().splitlines()[0].strip()
def create_user(api, label: str) -> dict:
"""Пользователь через API: он должен существовать и для HTTP-проверок."""
account = harness.account(api, label)
say(" %s -> %s" % (account["username"], account["id"]))
return account
def seed_history(user: dict, count: int, tie: int) -> dict:
"""Один чат с длинной историей; соседние `tie` сообщений делят `created_at`."""
# Идентификаторы схема не генерирует: их всегда присылает приложение,
# поэтому засев тоже обязан их указать.
chat_id = scalar(
"INSERT INTO chats (id, title) VALUES (gen_random_uuid(), '%s') RETURNING id;"
% HISTORY_TITLE
)
harness.psql(
"INSERT INTO chat_members (chat_id, user_id) VALUES ('%s', '%s');"
% (chat_id, user["id"])
)
started = time.monotonic()
harness.psql(
"INSERT INTO messages (id, chat_id, sender_id, text, created_at) "
"SELECT gen_random_uuid(), '%s'::uuid, '%s'::uuid, 'seed ' || i, "
"'%s'::timestamptz + make_interval(secs => (i - 1) / %d) "
"FROM generate_series(1, %d) AS i;"
% (chat_id, user["id"], HISTORY_EPOCH, tie, count),
timeout=600,
)
say(" %d сообщений за %.2fs" % (count, time.monotonic() - started))
stats = harness.psql(
"SELECT count(*) || ' rows, ' || count(DISTINCT created_at) || ' distinct created_at, ' "
"|| max(shared) || ' rows at most share one created_at ' || min(shared) || ' at least' "
"FROM (SELECT created_at, count(*) AS shared FROM messages WHERE chat_id = '%s' "
"GROUP BY created_at) AS grouped;" % chat_id
).strip()
say(" %s" % stats)
return {"id": chat_id, "title": HISTORY_TITLE, "owner": user}
def seed_chats(user: dict, count: int, epoch: str, title_prefix: str) -> dict:
"""Чаты одного пользователя; соседние 10 делят `created_at`.
Список чатов сортируется по `(created_at, id)` из таблицы `chats`, поэтому
ничьи по времени здесь так же обязательны, как и в истории.
"""
started = time.monotonic()
harness.psql(
"WITH created AS ("
" INSERT INTO chats (id, title, created_at) "
" SELECT gen_random_uuid(), '%s' || i, "
" '%s'::timestamptz + make_interval(secs => (i - 1) / 10) "
" FROM generate_series(1, %d) AS i RETURNING id"
") INSERT INTO chat_members (chat_id, user_id) "
"SELECT id, '%s'::uuid FROM created;" % (title_prefix, epoch, count, user["id"]),
timeout=600,
)
say(" %d чатов за %.2fs" % (count, time.monotonic() - started))
return {"count": count, "owner": user}
def analyze() -> None:
"""Без свежей статистики планировщик выбирает план по догадке."""
started = time.monotonic()
harness.psql("ANALYZE users, chats, chat_members, messages;", timeout=600)
say(" ANALYZE за %.2fs" % (time.monotonic() - started))
def summary(history: dict, chats: dict, noise: dict) -> None:
say(" таблица messages: %s строк, %s"
% (harness.psql("SELECT count(*) FROM messages;").strip(),
harness.psql("SELECT pg_size_pretty(pg_total_relation_size('messages'));").strip()))
say(" таблица chats: %s строк, chat_members: %s строк"
% (harness.psql("SELECT count(*) FROM chats;").strip(),
harness.psql("SELECT count(*) FROM chat_members;").strip()))
say(" индекс ix_messages_chat_id_created_at_id: %s"
% harness.psql("SELECT pg_size_pretty(pg_relation_size("
"'ix_messages_chat_id_created_at_id'));").strip())
say()
say(" владелец длинной истории : %s (%s), чатов у него %d"
% (history["owner"]["username"], history["owner"]["id"], chats["count"] + 1))
say(" чат с историей : %s" % history["id"])
say(" владелец шумовых чатов : %s, чатов у него %d"
% (noise["owner"]["username"], noise["count"]))
say()
say(" Дальше: python student-tests/explain_queries.py — он найдёт чат с самой")
say(" длинной историей и прогонит на нём планы запросов.")
def main() -> int:
parser = argparse.ArgumentParser(description="Засев данных для экспериментов лабораторной 2")
parser.add_argument("--base-url",
default=os.environ.get("BASE_URL", "http://127.0.0.1:8080"))
parser.add_argument("--messages", type=int, default=DEFAULT_MESSAGES)
parser.add_argument("--chats", type=int, default=DEFAULT_CHATS)
parser.add_argument("--noise-chats", type=int, default=DEFAULT_NOISE_CHATS)
parser.add_argument("--tie", type=int, default=DEFAULT_TIE,
help="сколько сообщений делят одно created_at")
parser.add_argument("--skip-analyze", action="store_true")
arguments = parser.parse_args()
os.environ["BASE_URL"] = arguments.base_url
say("Стенд: %s" % arguments.base_url)
api = harness.client()
section("1. Пользователи")
owner = create_user(api, "seed_owner")
noise = create_user(api, "seed_noise")
section("2. История чата")
history = seed_history(owner, arguments.messages, arguments.tie)
section("3. Список чатов")
chats = seed_chats(owner, arguments.chats, CHATS_EPOCH, CHATS_TITLE_PREFIX)
noise_chats = seed_chats(noise, arguments.noise_chats, CHATS_EPOCH, NOISE_TITLE_PREFIX)
section("4. Статистика планировщика")
if arguments.skip_analyze:
say(" ANALYZE пропущен (--skip-analyze)")
else:
analyze()
section("Итог")
summary(history, chats, noise_chats)
say()
say("ЗАСЕЯНО")
return 0
if __name__ == "__main__":
try:
raise SystemExit(main())
except SystemExit:
raise
except Exception as error: # noqa: BLE001
say()
say("ОШИБКА: %s: %s" % (type(error).__name__, error))
raise SystemExit(1) from error
+99
View File
@@ -0,0 +1,99 @@
"""Кто что может читать: чужой чат отдаётся точно так же, как отсутствующий.
В контракте есть 404 для чатов и сообщений и нигде нет 403, поэтому посторонний
не должен по кодам ответов узнавать о существовании чата.
"""
from __future__ import annotations
import unittest
import uuid
import harness
class ChatVisibility(unittest.TestCase):
"""Участие определяется сессией, а не заголовком или полем тела запроса."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
cls.alice = harness.account(cls.api, "acc_alice")
cls.bob = harness.account(cls.api, "acc_bob")
cls.eve = harness.account(cls.api, "acc_eve")
cls.chat = harness.chat(cls.api, cls.alice, [cls.bob], title="Приватный чат")
harness.send(cls.api, cls.alice, cls.chat, "Только для участников")
def test_members_read_the_chat(self):
for actor in (self.alice, self.bob):
with self.subTest(user=actor["username"]):
response = self.api.call("GET", "/api/v1/chats/" + self.chat["id"], 200,
actor=actor, schema="Chat")
self.assertEqual(response["json"]["id"], self.chat["id"])
def test_outsider_gets_not_found(self):
for path in ("/api/v1/chats/" + self.chat["id"],
"/api/v1/chats/" + self.chat["id"] + "/messages"):
with self.subTest(path=path):
response = self.api.call("GET", path, [404], actor=self.eve)
self.assertEqual(response["json"]["error"]["code"], "not_found")
def test_outsider_cannot_write(self):
response = self.api.call(
"POST", "/api/v1/chats/" + self.chat["id"] + "/messages", [404],
actor=self.eve, body={"text": "Посторонний"},
)
self.assertEqual(response["json"]["error"]["code"], "not_found")
def test_outsider_does_not_see_the_chat_in_the_list(self):
self.assertNotIn(self.chat["id"],
{item["id"] for item in harness.all_chats(self.api, self.eve)})
def test_a_foreign_chat_and_a_missing_chat_are_reported_alike(self):
"""Тот же статус, тот же код, то же сообщение: разница не должна утекать."""
foreign = self.api.call("GET", "/api/v1/chats/" + self.chat["id"], [404], actor=self.eve)
missing = self.api.call("GET", "/api/v1/chats/" + str(uuid.uuid4()), [404], actor=self.eve)
left = dict(foreign["json"]["error"])
right = dict(missing["json"]["error"])
left.pop("request_id")
right.pop("request_id")
self.assertEqual(left, right)
self.assertEqual(foreign["status"], missing["status"])
def test_x_user_id_does_not_open_a_foreign_chat(self):
response = self.api.call(
"GET", "/api/v1/chats/" + self.chat["id"], [404], actor=self.eve,
headers={"X-User-Id": self.alice["id"]},
)
self.assertEqual(response["json"]["error"]["code"], "not_found")
def test_a_left_member_still_sees_the_history(self):
"""Участие фиксируется при создании, поэтому история участника не исчезает."""
messages = harness.all_messages(self.api, self.bob, self.chat["id"])
self.assertTrue(messages)
self.assertTrue(all(item["chat_id"] == self.chat["id"] for item in messages))
class CurrentUser(unittest.TestCase):
"""GET /users/me отвечает владельцу сессии и больше никому."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
cls.alice = harness.account(cls.api, "me_alice")
cls.bob = harness.account(cls.api, "me_bob")
def test_each_session_sees_its_own_user(self):
for actor in (self.alice, self.bob):
with self.subTest(user=actor["username"]):
body = self.api.call("GET", "/api/v1/users/me", 200, actor=actor, schema="User")["json"]
self.assertEqual(body["id"], actor["id"])
self.assertEqual(body["username"], actor["username"])
def test_registration_body_is_never_echoed(self):
body = self.api.call("GET", "/api/v1/users/me", 200, actor=self.alice, schema="User")["json"]
self.assertNotIn("password", body)
self.assertNotIn("password_hash", body)
if __name__ == "__main__":
unittest.main(verbosity=2)
+219
View File
@@ -0,0 +1,219 @@
"""Регистрация и вход: правила пароля, Basic только на своём маршруте, Bearer везде.
Самое интересное в лабораторной 2 — переход от X-User-Id к сессиям, поэтому
проверки ниже смотрят на то, что может наблюдать клиент: какая схема где
принимается, отличим ли пароль с опечаткой от неизвестного пользователя и
переживает ли длинный пароль KDF без изменений.
"""
from __future__ import annotations
import statistics
import time
import unittest
import harness
class Registration(unittest.TestCase):
"""POST /api/v1/users: пароль обязателен и ограничен по длине."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
def body(self, secret, label, **extra):
payload = {
"username": harness.unique(label),
"display_name": "Студент",
"password": secret,
}
payload.update(extra)
return payload
def test_password_is_required(self):
payload = self.body(harness.fresh_password(), "nopw")
del payload["password"]
response = self.api.call("POST", "/api/v1/users", [400], body=payload)
self.assertEqual(response["json"]["error"]["code"], "invalid_request")
def test_password_length_bounds(self):
"""11 и 129 кодовых точек отклоняются; 12 и 128 принимаются."""
for length, expected in ((11, 400), (12, 201), (128, 201), (129, 400)):
with self.subTest(length=length):
payload = self.body("a" * length, "bound%d" % length)
self.api.call("POST", "/api/v1/users", expected, body=payload)
def test_accepted_passwords_work_for_login(self):
for length in (12, 128):
with self.subTest(length=length):
secret = "a" * length
payload = self.body(secret, "login%d" % length)
self.api.call("POST", "/api/v1/users", 201, body=payload)
session = harness.login(self.api, payload["username"], secret)
self.assertEqual(session["user"]["username"], payload["username"])
def test_whitespace_only_password_is_refused(self):
"""Двенадцать пробелов — пустое значение обязательного поля, а не пароль."""
response = self.api.call("POST", "/api/v1/users", [400], body=self.body(" " * 12, "blank"))
self.assertEqual(response["json"]["error"]["code"], "invalid_request")
def test_surrounding_spaces_are_part_of_the_password(self):
"""Пароль не обрезается: пробелы по краям значат то же, что и любые другие символы."""
secret = " " + "a" * 10 + " "
payload = self.body(secret, "spaced")
self.api.call("POST", "/api/v1/users", 201, body=payload)
self.assertEqual(harness.login(self.api, payload["username"], secret)["token_type"],
"Bearer")
def test_password_is_checked_to_the_last_byte(self):
"""Пароль длиннее 72 байт не усекается KDF.
Оба секрета совпадают первыми 72 байтами UTF-8, поэтому любой алгоритм,
обрезающий ввод до 72 байт, принял бы один из них за другой.
"""
prefix = "я" * 36 # 2 байта на символ, 36 символов = ровно 72 байта
first = prefix + "-alpha-tail"
second = prefix + "-bravo-tail"
self.assertEqual(first.encode("utf-8")[:72], second.encode("utf-8")[:72])
self.assertNotEqual(first.encode("utf-8"), second.encode("utf-8"))
payload = self.body(first, "trunc")
self.api.call("POST", "/api/v1/users", 201, body=payload)
self.assertEqual(harness.login(self.api, payload["username"], first)["token_type"], "Bearer")
self.api.call(
"POST", "/api/v1/auth/sessions",
[401], headers=harness.basic(payload["username"], second),
)
def test_multibyte_password_far_beyond_72_bytes(self):
"""128 кириллических кодовых точек — это 256 байт UTF-8, и они проходят без потерь."""
secret = "я" * 128
self.assertGreater(len(secret.encode("utf-8")), 255)
payload = self.body(secret, "wide")
self.api.call("POST", "/api/v1/users", 201, body=payload)
self.assertEqual(harness.login(self.api, payload["username"], secret)["token_type"],
"Bearer")
def test_password_may_contain_a_colon(self):
"""Basic разделяет только по первому двоеточию, остальное принадлежит паролю."""
secret = "Aa1:" + "x" * 12
payload = self.body(secret, "colon")
self.api.call("POST", "/api/v1/users", 201, body=payload)
self.assertEqual(harness.login(self.api, payload["username"], secret)["token_type"],
"Bearer")
def test_duplicate_username_conflicts(self):
payload = self.body(harness.fresh_password(), "dupe")
self.api.call("POST", "/api/v1/users", 201, body=payload)
response = self.api.call("POST", "/api/v1/users", [409], body=payload)
self.assertEqual(response["json"]["error"]["code"], "conflict")
class Credentials(unittest.TestCase):
"""Какая схема где принимается и что сообщает клиенту отказ."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
cls.alice = harness.account(cls.api, "cred_alice")
cls.bob = harness.account(cls.api, "cred_bob")
def test_basic_is_accepted_on_the_session_route(self):
session = harness.login(self.api, self.alice["username"], self.alice["password"])
self.assertEqual(session["user"]["id"], self.alice["id"])
def test_basic_is_rejected_on_business_routes(self):
"""Учётные данные Basic не должны открывать /users/me: челлендж должен требовать Bearer."""
for path in ("/api/v1/users/me", "/api/v1/chats"):
with self.subTest(path=path):
response = self.api.call(
"GET", path, [401],
headers=harness.basic(self.alice["username"], self.alice["password"]),
)
self.assertEqual(response["json"]["error"]["code"], "unauthorized")
self.assertTrue(
response["headers"]["WWW-Authenticate"].startswith("Bearer"),
"бизнес-маршрут должен отвечать челленджем Bearer",
)
def test_bearer_is_rejected_on_the_session_route(self):
"""Маршрут входа принимает только Basic; сессионный токен не создаёт сессию."""
self.api.call(
"POST", "/api/v1/auth/sessions", [401], headers=harness.bearer(self.alice["token"])
)
def test_x_user_id_cannot_authenticate_or_impersonate(self):
"""Заголовок из лабораторной 1 не работает: не даёт доступа и не переопределяет сессию."""
anonymous = self.api.call(
"GET", "/api/v1/users/me", [401], headers={"X-User-Id": self.alice["id"]}
)
self.assertEqual(anonymous["json"]["error"]["code"], "unauthorized")
spoofed = self.api.call(
"GET", "/api/v1/users/me", 200, actor=self.alice,
headers={"X-User-Id": self.bob["id"]}, schema="User",
)
self.assertEqual(spoofed["json"]["id"], self.alice["id"],
"X-User-Id не должен переопределять bearer-сессию")
def test_unknown_user_and_wrong_password_are_indistinguishable(self):
"""Тот же статус, тот же код, то же сообщение — и сопоставимый объём работы."""
unknown = self.api.call(
"POST", "/api/v1/auth/sessions", [401],
headers=harness.basic(harness.unique("ghost"), harness.fresh_password()),
)
wrong = self.api.call(
"POST", "/api/v1/auth/sessions", [401],
headers=harness.basic(self.alice["username"], harness.fresh_password()),
)
unknown_error = dict(unknown["json"]["error"])
wrong_error = dict(wrong["json"]["error"])
unknown_error.pop("request_id")
wrong_error.pop("request_id")
self.assertEqual(unknown_error, wrong_error,
"клиент не должен уметь отличить эти два отказа друг от друга")
def median_seconds(header):
samples = []
for _ in range(3):
start = time.monotonic()
self.api.call("POST", "/api/v1/auth/sessions", [401], headers=header)
samples.append(time.monotonic() - start)
return statistics.median(samples)
unknown_time = median_seconds(harness.basic(harness.unique("ghost2"), harness.fresh_password()))
wrong_time = median_seconds(harness.basic(self.alice["username"], harness.fresh_password()))
# Фиктивный хеш для неизвестных пользователей выравнивает стоимость; граница
# намеренно мягкая, потому что общий CI-хост добавляет шум того же порядка, что и сам KDF.
self.assertLess(min(unknown_time, wrong_time) / max(unknown_time, wrong_time), 4.0,
"неизвестный пользователь (%.3fs) и неверный пароль (%.3fs) сильно разнятся"
% (unknown_time, wrong_time))
def test_malformed_authorization_headers(self):
cases = (
{"Authorization": "Bearer"},
{"Authorization": "Bearer "},
{"Authorization": "Bearer short"},
{"Authorization": "Basic"},
{"Authorization": "Basic !!!not-base64!!!"},
{"Authorization": "Token " + self.alice["token"]},
)
for headers in cases:
with self.subTest(headers=headers):
self.api.call("GET", "/api/v1/users/me", [401], headers=headers)
def test_token_is_opaque_and_unique(self):
first = self.alice["token"]
second = harness.login(self.api, self.alice["username"], self.alice["password"])["token"]
self.assertGreaterEqual(len(first), 32)
self.assertNotEqual(first, second, "каждый вход должен выдавать свежий токен")
self.assertNotIn(self.alice["username"], first)
self.assertNotIn(self.alice["password"], first)
session = self.alice["session"]
self.assertEqual(session["token_type"], "Bearer")
self.assertNotIn("expires_at", self.alice["user"])
if __name__ == "__main__":
unittest.main(verbosity=2)
+87
View File
@@ -0,0 +1,87 @@
"""Создание чата - одна транзакция: отказ по участнику не оставляет следов.
Строка чата, вставленная до проверки участников, пережила бы более поздний
сбой, и автор увидел бы пустой чат в своём списке после 400. Здесь проверяются
и представление через API, и сама таблица.
"""
from __future__ import annotations
import unittest
import uuid
import harness
class ChatCreation(unittest.TestCase):
"""Отказы не оставляют следов, успешные создания выполняются целиком."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
cls.alice = harness.account(cls.api, "atom_alice")
cls.bob = harness.account(cls.api, "atom_bob")
def visible_chats(self, actor):
return {item["id"] for item in harness.all_chats(self.api, actor)}
def reject(self, body, title):
"""Отправляет заведомо неуспешное создание и возвращает код ошибки."""
response = self.api.call("POST", "/api/v1/chats", [400], actor=self.alice, body=body)
if harness.docker_available():
rows = harness.psql("SELECT count(*) FROM chats WHERE title = '%s'" % title)
self.assertEqual(rows.strip(), "0",
"отклонённое создание оставило после себя строку: %s" % title)
return response["json"]["error"]["code"]
def test_unknown_member_is_refused_without_a_trace(self):
before = self.visible_chats(self.alice)
title = "ghost-chat-" + uuid.uuid4().hex[:8]
code = self.reject(
{"title": title, "member_ids": [self.alice["id"], str(uuid.uuid4())]}, title
)
self.assertEqual(code, "invalid_request")
self.assertEqual(self.visible_chats(self.alice), before,
"неудачное создание изменило список чатов")
def test_one_unknown_member_among_known_ones_still_rolls_back(self):
before = self.visible_chats(self.alice)
title = "partially-known-" + uuid.uuid4().hex[:8]
code = self.reject(
{"title": title,
"member_ids": [self.alice["id"], self.bob["id"], str(uuid.uuid4())]}, title
)
self.assertEqual(code, "invalid_request")
self.assertEqual(self.visible_chats(self.alice), before)
def test_creator_must_be_a_member(self):
title = "no-creator-" + uuid.uuid4().hex[:8]
code = self.reject({"title": title, "member_ids": [self.bob["id"]]}, title)
self.assertEqual(code, "invalid_request")
def test_duplicate_members_are_refused(self):
title = "duplicate-member-" + uuid.uuid4().hex[:8]
code = self.reject(
{"title": title, "member_ids": [self.alice["id"], self.alice["id"]]}, title
)
self.assertEqual(code, "invalid_request")
def test_empty_and_oversized_member_lists_are_refused(self):
for members, label in (([], "empty"), ([str(uuid.uuid4()) for _ in range(101)], "wide")):
title = "members-" + label + "-" + uuid.uuid4().hex[:8]
with self.subTest(label=label):
code = self.reject({"title": title, "member_ids": members}, title)
self.assertEqual(code, "invalid_request")
def test_a_valid_chat_is_created_whole(self):
before = self.visible_chats(self.alice)
chat = harness.chat(self.api, self.alice, [self.bob], title="Обычный чат")
self.assertEqual(set(chat["member_ids"]), {self.alice["id"], self.bob["id"]})
self.assertEqual(list(chat["member_ids"]), sorted(chat["member_ids"]),
"ожидается устойчивый порядок member_ids")
after = self.visible_chats(self.alice)
self.assertEqual(after - before, {chat["id"]})
self.assertIn(chat["id"], self.visible_chats(self.bob))
if __name__ == "__main__":
unittest.main(verbosity=2)
+111
View File
@@ -0,0 +1,111 @@
"""Что видят клиенты, когда PostgreSQL или Valkey недоступны.
Отказ, от которого это защищает, — недоступность зависимости, выдаваемая за «ваш
токен недействителен»: клиент, реагирующий на 401 повторным входом, выбросил бы
вполне рабочую сессию. Во время отказа API должно отвечать 503 на всё, что требует
зависимости, держать /health/live на 200, чтобы супервизор не перезапускал здоровый
процесс, и отвечать быстро, а не зависать.
Ограничение в 2 с не бесплатно: при остановленном контейнере имя `postgres`
перестаёт разрешаться, а встроенный DNS Docker передаёт неизвестное имя вышестоящему
серверу, и тот отвечает только через ~3.3 с. Быстрым ответ делает бюджет таймаутов
сокета и подключения (DB_CONNECT_TIMEOUT_SECONDS, CACHE_TIMEOUT_SECONDS), так что
проверка ниже на самом деле проверяет этот бюджет.
Остановка контейнеров разрушительна, поэтому модуль запускается только при
ALLOW_OUTAGE=1, и каждый тест возвращает контейнеры на место.
"""
from __future__ import annotations
import hashlib
import time
import unittest
import harness
SLOWEST_ALLOWED = 2.0
@unittest.skipUnless(harness.flag("ALLOW_OUTAGE"),
"задайте ALLOW_OUTAGE=1 для запуска: этот модуль останавливает контейнеры")
class DependencyOutage(unittest.TestCase):
"""По одной зависимости за раз, потом всё возвращается на место."""
@classmethod
def setUpClass(cls):
cls.api = harness.client(timeout=5)
harness.require_docker(cls)
cls.alice = harness.account(cls.api, "out_alice")
cls.bob = harness.account(cls.api, "out_bob")
cls.chat = harness.chat(cls.api, cls.alice, [cls.bob], title="До отказа")
cls.message = harness.send(cls.api, cls.alice, cls.chat, "Записано до отказа")
def restore(self, service: str):
started = time.monotonic()
harness.compose("start", service, timeout=180)
harness.wait_ready(timeout=120)
print(" %s снова поднят и готов через %.2fs" % (service, time.monotonic() - started))
def assert_unavailable(self, method, path, **kwargs):
"""503 в конверте контракта, быстро и никогда не 401."""
response = self.api.call(method, path, [503], **kwargs)
print(" %-6s %-42s %6.3fs %s"
% (method, path, response["elapsed"], response["json"]["error"]["code"]))
self.assertEqual(response["json"]["error"]["code"], "unavailable")
self.assertLess(response["elapsed"], SLOWEST_ALLOWED,
"%s %s занял %.2fs, пока зависимость была недоступна"
% (method, path, response["elapsed"]))
return response
def test_postgres_outage(self):
harness.compose("stop", "postgres", timeout=180)
try:
self.assert_unavailable("GET", "/api/v1/users/me", actor=self.alice)
self.assert_unavailable("GET", "/api/v1/chats", actor=self.alice)
self.assert_unavailable("GET", "/api/v1/chats/" + self.chat["id"], actor=self.alice)
self.assert_unavailable("GET", "/health/ready")
self.assert_unavailable(
"POST", "/api/v1/auth/sessions",
headers=harness.basic(self.alice["username"], self.alice["password"]),
)
self.api.call("GET", "/health/live", 200, schema="Health")
finally:
self.restore("postgres")
self.api.call("GET", "/api/v1/users/me", 200, actor=self.alice, schema="User")
messages = harness.all_messages(self.api, self.alice, self.chat["id"])
self.assertIn(self.message["id"], [item["id"] for item in messages],
"данные, записанные до отказа, исчезли")
print(" записей в истории после отказа: %d" % len(messages))
def test_valkey_outage(self):
harness.compose("stop", "valkey", timeout=180)
try:
self.assert_unavailable("GET", "/api/v1/users/me", actor=self.alice)
self.assert_unavailable("GET", "/api/v1/chats", actor=self.alice)
self.assert_unavailable("GET", "/health/ready")
self.assert_unavailable("DELETE", "/api/v1/auth/sessions/current", actor=self.alice)
finally:
self.restore("valkey")
# Хранилище лишь остановили, поэтому AOF возвращает сессию вместе с её TTL.
self.api.call("GET", "/api/v1/users/me", 200, actor=self.alice, schema="User")
fingerprint = hashlib.sha256(self.alice["token"].encode("utf-8")).hexdigest()
key = harness.SESSION_KEY_PREFIX + fingerprint
self.assertEqual(harness.valkey("EXISTS", key), "1",
"сессия не пережила перезапуск Valkey")
print(" %s переживает перезапуск с TTL %s с (AOF), тот же токен всё ещё принимается"
% (key, harness.valkey("TTL", key)))
def test_liveness_stays_green_throughout(self):
"""Отказ зависимости не должен выглядеть для супервизора смертью процесса."""
harness.compose("stop", "valkey", timeout=180)
try:
for _ in range(3):
self.api.call("GET", "/health/live", 200, schema="Health")
finally:
self.restore("valkey")
if __name__ == "__main__":
unittest.main(verbosity=2)
+114
View File
@@ -0,0 +1,114 @@
"""Истечение срока сессии, прослеженное сквозь весь стек при коротком TTL.
Ждать час, пока токен умрёт, никто не станет, поэтому модуль пересоздаёт сервис
API с SESSION_TTL_SECONDS в несколько секунд, проверяет, что произойдёт, и
возвращает прежнее значение. Пересоздание контейнера — ещё и самый дешёвый способ
показать, что сессии живут в Valkey, а не в процессе: токен, выданный до
пересоздания, продолжает работать и после него.
"""
from __future__ import annotations
import datetime as dt
import hashlib
import os
import time
import unittest
import harness
SHORT_TTL = int(os.environ.get("SHORT_TTL_SECONDS", "3"))
NORMAL_TTL = 3600
class ShortLivedSessions(unittest.TestCase):
"""Весь модуль работает при коротком TTL, а затем возвращает прежний."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
harness.require_docker(cls)
cls.original_ttl = os.environ.get("SESSION_TTL_SECONDS", str(NORMAL_TTL))
# Выдан, пока ещё действует обычный TTL: этот токен должен пережить
# и смену TTL, и пересоздание контейнера, которое её применяет.
cls.survivor = harness.account(cls.api, "exp_survivor")
cls.apply_ttl(str(SHORT_TTL))
@classmethod
def tearDownClass(cls):
if cls.original_ttl != str(SHORT_TTL):
cls.apply_ttl(cls.original_ttl)
@classmethod
def apply_ttl(cls, value: str) -> None:
"""Пересоздаёт API с другим SESSION_TTL_SECONDS и ждёт готовности."""
started = time.monotonic()
result = harness.compose(
"up", "-d", "api", env={"SESSION_TTL_SECONDS": value}, timeout=240
)
if result.returncode != 0:
raise AssertionError("docker compose up не удался: " + result.stderr.strip()[:300])
harness.wait_ready(timeout=120)
print(" api пересоздан с SESSION_TTL_SECONDS=%s, готов через %.2fs"
% (value, time.monotonic() - started))
def key_of(self, token: str) -> str:
return harness.SESSION_KEY_PREFIX + hashlib.sha256(token.encode("utf-8")).hexdigest()
def remaining(self, session) -> float:
expires = dt.datetime.fromisoformat(session["expires_at"].replace("Z", "+00:00"))
return (expires - dt.datetime.now(dt.timezone.utc)).total_seconds()
def test_the_short_ttl_is_the_one_in_force(self):
alice = harness.account(self.api, "exp_short")
remaining = self.remaining(alice["session"])
self.assertGreater(remaining, 0)
self.assertLessEqual(remaining, SHORT_TTL + 2,
"expires_at дальше, чем настроенный TTL")
self.assertGreater(remaining, SHORT_TTL - 2, "expires_at ближе, чем TTL")
ttl = int(harness.valkey("TTL", self.key_of(alice["token"])))
self.assertGreater(ttl, 0)
self.assertLessEqual(ttl, SHORT_TTL, "ключ живёт дольше, чем обещает токен")
print(" expires_at через %.2fs, ключ в Valkey живёт %ds: сроком владеет"
" хранилище, а не процесс" % (remaining, ttl))
def test_a_token_stops_working_once_the_ttl_passes(self):
alice = harness.account(self.api, "exp_dies")
self.api.call("GET", "/api/v1/users/me", 200, actor=alice, schema="User")
time.sleep(SHORT_TTL + 1.5)
self.api.call("GET", "/api/v1/users/me", [401], actor=alice)
self.api.call("DELETE", "/api/v1/auth/sessions/current", [401], actor=alice)
self.assertEqual(harness.valkey("EXISTS", self.key_of(alice["token"])), "0",
"ключ пережил токен: его ничто не удалило по истечении срока")
print(" через %ds токен отвергается обоими маршрутами, а его ключ исчез"
% (SHORT_TTL + 1.5))
def test_a_token_issued_before_the_change_still_works(self):
"""Пересоздание API не выдаёт новые сессии и не продлевает старые."""
self.api.call("GET", "/api/v1/users/me", 200, actor=self.survivor, schema="User")
ttl = int(harness.valkey("TTL", self.key_of(self.survivor["token"])))
self.assertGreater(ttl, SHORT_TTL,
"переживший токен должен сохранить TTL, с которым был выдан")
self.assertLessEqual(ttl, NORMAL_TTL + 1)
self.assertLess(ttl, NORMAL_TTL,
"TTL снова равен полному часу: сессию выдали заново, "
"а не перенесли")
print(" у токена, выданного до переключения, осталось %ds из исходных %ds"
% (ttl, NORMAL_TTL))
def test_expiry_does_not_need_a_cleanup_job(self):
"""Хранилище никто не чистит: ключа просто больше нет."""
alice = harness.account(self.api, "exp_sweep")
key = self.key_of(alice["token"])
self.assertEqual(harness.valkey("EXISTS", key), "1")
time.sleep(SHORT_TTL + 1.5)
self.assertEqual(harness.valkey("EXISTS", key), "0")
self.api.call("GET", "/api/v1/users/me", [401], actor=alice)
print(" ключ исчез сам между двумя запросами: приложение не удаляет "
"просроченные сессии")
if __name__ == "__main__":
unittest.main(verbosity=2)
+62
View File
@@ -0,0 +1,62 @@
"""Эндпоинты здоровья: что они отвечают, что им нужно и чего они не трогают.
/health/live - сигнал, по которому супервизор решает, перезапускать ли процесс,
поэтому он не должен зависеть от PostgreSQL и Valkey. /health/ready - сигнал,
которым балансировщик нагрузки пользуется перед отправкой трафика, поэтому он
должен зависеть от обоих. Проверки отказов, которые отсюда следуют, живут в
test_dependency_outage.py: они останавливают контейнеры и потому требуют
ALLOW_OUTAGE=1.
"""
from __future__ import annotations
import unittest
import harness
class Probes(unittest.TestCase):
"""Обе пробы отвечают без учётных данных и не трогают пользовательские данные."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
def test_liveness(self):
response = self.api.call("GET", "/health/live", 200, schema="Health")
self.assertEqual(response["json"], {"status": "ok"})
self.assertTrue(response["headers"]["X-Request-Id"])
def test_readiness(self):
response = self.api.call("GET", "/health/ready", 200, schema="Health")
self.assertEqual(response["json"], {"status": "ok"})
def test_probes_need_no_credentials(self):
for path in ("/health/live", "/health/ready"):
with self.subTest(path=path):
self.api.call("GET", path, 200, headers={}, schema="Health")
self.api.call("GET", path, 200,
headers={"Authorization": "Bearer nonsense"}, schema="Health")
def test_every_probe_gets_its_own_request_id(self):
seen = set()
for _ in range(5):
seen.add(self.api.call("GET", "/health/ready", 200, schema="Health")
["headers"]["X-Request-Id"])
self.assertEqual(len(seen), 5, "идентификаторы запросов переиспользуются")
def test_readiness_is_not_a_cached_constant(self):
"""Повторные пробы должен обслуживать процесс, а не кешированное тело."""
first = self.api.call("GET", "/health/ready", 200, schema="Health")
second = self.api.call("GET", "/health/ready", 200, schema="Health")
self.assertEqual(first["json"], second["json"])
self.assertNotEqual(first["headers"]["X-Request-Id"],
second["headers"]["X-Request-Id"])
def test_error_envelope_carries_a_request_id(self):
response = self.api.call("GET", "/health/nothing", [404], headers={})
self.assertEqual(response["json"]["error"]["request_id"],
response["headers"]["X-Request-Id"])
if __name__ == "__main__":
unittest.main(verbosity=2)
+167
View File
@@ -0,0 +1,167 @@
"""Пагинация по ключу: каждый элемент ровно один раз, в порядке из контракта.
Контракт обещает порядок (created_at, id). Записи, созданные разными запросами,
могут иметь одинаковую метку времени, поэтому граница страницы внутри такой
группы - случай, где наивная реализация ошибается: проверки ниже читают всю
историю через курсор и сравнивают её с одним чтением без пагинации.
"""
from __future__ import annotations
import unittest
import uuid
import harness
HISTORY = 25
PAGE = 7
def order_key(item):
"""(created_at, id), где UUID сравнивается как целое число - так читает контракт."""
return (item["created_at"], uuid.UUID(item["id"]).int)
class MessageHistory(unittest.TestCase):
"""Чат с известной историей, читаемый страницами по семь."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
cls.alice = harness.account(cls.api, "page_alice")
cls.bob = harness.account(cls.api, "page_bob")
cls.chat = harness.chat(cls.api, cls.alice, [cls.bob], title="История")
cls.texts = ["Сообщение %02d" % index for index in range(HISTORY)]
for text in cls.texts:
harness.send(cls.api, cls.bob, cls.chat, text)
def page(self, cursor=None, limit=PAGE, actor=None):
path = "/api/v1/chats/%s/messages?limit=%d" % (self.chat["id"], limit)
if cursor is not None:
path += "&cursor=" + cursor
return self.api.call("GET", path, 200, actor=actor or self.alice,
schema="MessagePage")["json"]
def test_pages_cover_the_history_exactly_once(self):
collected, sizes, cursor, seen = [], [], None, set()
for _ in range(20):
body = self.page(cursor)
collected.extend(item["id"] for item in body["items"])
sizes.append(len(body["items"]))
cursor = body["next_cursor"]
if cursor is None:
break
self.assertNotIn(cursor, seen, "курсор повторился")
seen.add(cursor)
else:
self.fail("пагинация не завершилась в пределах защитного ограничения")
self.assertEqual(len(collected), HISTORY)
self.assertEqual(len(set(collected)), HISTORY, "элемент встретился на двух страницах")
self.assertEqual(sizes[:-1], [PAGE] * (len(sizes) - 1),
"каждая страница, кроме последней, должна быть полной")
self.assertLessEqual(sizes[-1], PAGE)
def test_small_pages_agree_with_a_single_large_one(self):
paged, cursor = [], None
while True:
body = self.page(cursor, limit=PAGE)
paged.extend(item["id"] for item in body["items"])
cursor = body["next_cursor"]
if cursor is None:
break
unpaged = [item["id"] for item in self.page(limit=100)["items"]]
self.assertEqual(paged, unpaged, "разбиение на страницы изменило результат")
def test_items_are_ordered_by_created_at_then_id(self):
items = self.page(limit=100)["items"]
self.assertEqual(len(items), HISTORY)
keys = [order_key(item) for item in items]
self.assertEqual(keys, sorted(keys), "история не упорядочена по (created_at, id)")
def test_the_second_page_starts_right_after_the_first(self):
first = self.page(limit=PAGE)
second = self.page(first["next_cursor"], limit=PAGE)
boundary = order_key(first["items"][-1])
self.assertLess(boundary, order_key(second["items"][0]))
self.assertTrue(
all(order_key(item) > boundary for item in second["items"]),
"страница вернула элемент на позиции курсора или раньше",
)
def test_a_cursor_from_another_chat_is_refused(self):
other = harness.chat(self.api, self.alice, [], title="Другой чат")
harness.send(self.api, self.alice, other, "Чужое сообщение")
cursor = self.page(limit=1)["next_cursor"]
self.assertIsNotNone(cursor)
response = self.api.call(
"GET", "/api/v1/chats/%s/messages?limit=1&cursor=%s" % (other["id"], cursor),
[400], actor=self.alice,
)
self.assertEqual(response["json"]["error"]["code"], "invalid_request")
def test_a_cursor_from_another_user_is_refused(self):
chat = harness.chat(self.api, self.bob, [], title="Чаты Боба")
harness.send(self.api, self.bob, chat, "Только Боб")
cursor = self.page(limit=1)["next_cursor"]
self.assertIsNotNone(cursor)
response = self.api.call(
"GET", "/api/v1/chats/%s/messages?limit=1&cursor=%s" % (chat["id"], cursor),
[400], actor=self.bob,
)
self.assertEqual(response["json"]["error"]["code"], "invalid_request")
def test_a_cursor_from_the_chat_list_is_refused_here(self):
chats = self.api.call("GET", "/api/v1/chats?limit=1", 200, actor=self.alice,
schema="ChatPage")["json"]
cursor = chats["next_cursor"]
self.assertIsNotNone(cursor, "для фикстуры нужно минимум два чата")
response = self.api.call(
"GET", "/api/v1/chats/%s/messages?limit=1&cursor=%s" % (self.chat["id"], cursor),
[400], actor=self.alice,
)
self.assertEqual(response["json"]["error"]["code"], "invalid_request")
class ChatList(unittest.TestCase):
"""Те же правила для списка чатов, где область видимости - текущий пользователь."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
cls.alice = harness.account(cls.api, "page_owner")
cls.chats = [harness.chat(cls.api, cls.alice, [], title="Чат %d" % index)
for index in range(5)]
def test_chat_pages_cover_the_list_exactly_once(self):
collected, cursor, seen = [], None, set()
for _ in range(20):
path = "/api/v1/chats?limit=2"
if cursor is not None:
self.assertNotIn(cursor, seen)
seen.add(cursor)
path += "&cursor=" + cursor
body = self.api.call("GET", path, 200, actor=self.alice, schema="ChatPage")["json"]
collected.extend(item["id"] for item in body["items"])
cursor = body["next_cursor"]
if cursor is None:
break
else:
self.fail("пагинация списка чатов не завершилась")
expected = {chat["id"] for chat in self.chats}
self.assertTrue(expected.issubset(set(collected)))
self.assertEqual(len(collected), len(set(collected)), "чат появился дважды")
keys = [order_key(item) for item in harness.all_chats(self.api, self.alice)]
self.assertEqual(keys, sorted(keys))
def test_a_cursor_from_one_user_is_refused_for_another(self):
bob = harness.account(self.api, "page_outsider")
cursor = self.api.call("GET", "/api/v1/chats?limit=1", 200, actor=self.alice,
schema="ChatPage")["json"]["next_cursor"]
self.assertIsNotNone(cursor)
response = self.api.call("GET", "/api/v1/chats?limit=1&cursor=" + cursor, [400], actor=bob)
self.assertEqual(response["json"]["error"]["code"], "invalid_request")
if __name__ == "__main__":
unittest.main(verbosity=2)
+77
View File
@@ -0,0 +1,77 @@
"""Два клиента регистрируют один и тот же username в один момент.
Проверка с последующей вставкой в обработчике этого не выдерживает: SELECT
обоих воркеров видит свободный username, и оба продолжают работу. Решает
уникальный индекс, а проигравший должен получить 409 - не 500 и не молчание.
"""
from __future__ import annotations
import threading
import unittest
import harness
WORKERS = 12
class RegistrationRace(unittest.TestCase):
"""Пользователя может создать ровно одна из одновременных регистраций."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
def race(self, workers=WORKERS):
username = harness.unique("race")
secret = harness.fresh_password()
payload = {"username": username, "display_name": "Студент", "password": secret}
outcomes, lock, barrier = [], threading.Lock(), threading.Barrier(workers)
def worker():
api = harness.client(timeout=30)
barrier.wait()
try:
response = api.call("POST", "/api/v1/users", [201, 409], body=payload)
error = response["json"]["error"]["code"] if response["status"] == 409 else None
outcome = (response["status"], error)
except Exception as exc: # сбой транспорта - тоже результат, а не оправдание
outcome = (str(exc), None)
with lock:
outcomes.append(outcome)
threads = [threading.Thread(target=worker) for _ in range(workers)]
for thread in threads:
thread.start()
for thread in threads:
thread.join(timeout=60)
return username, secret, outcomes
def test_only_one_registration_wins(self):
username, secret, outcomes = self.race()
statuses = [status for status, _ in outcomes]
self.assertEqual(len(outcomes), WORKERS, "один из воркеров не сообщил результат")
self.assertEqual(statuses.count(201), 1, "ожидался ровно один 201: %r" % (outcomes,))
self.assertEqual(statuses.count(409), WORKERS - 1,
"каждый проигравший должен получить 409, получено %r" % (outcomes,))
session = harness.login(self.api, username, secret)
self.assertEqual(session["user"]["username"], username)
def test_every_loser_gets_the_conflict_envelope(self):
_, _, outcomes = self.race(workers=4)
self.assertEqual([status for status, _ in outcomes].count(201), 1)
losers = [error for status, error in outcomes if status == 409]
self.assertEqual(len(losers), 3)
self.assertEqual(set(losers), {"conflict"},
"проигравшая регистрация должна вернуть conflict, получено %r" % (losers,))
def test_database_holds_exactly_one_row(self):
harness.require_docker(self)
username, _, outcomes = self.race(workers=6)
self.assertEqual([status for status, _ in outcomes].count(201), 1)
rows = harness.psql("SELECT count(*) FROM users WHERE username = '%s'" % username)
self.assertEqual(rows.strip(), "1", "уникальный индекс не сработал")
if __name__ == "__main__":
unittest.main(verbosity=2)
+161
View File
@@ -0,0 +1,161 @@
"""Жизненный цикл сессии: несколько сессий у пользователя, мгновенный отзыв, размещение в хранилище.
Проверки намеренно опираются на устройство, выбранное в этой лабораторной работе:
сессии живут в Valkey под ключом, производным от токена, а сам токен никогда не
хранится. Это делает отзыв атомарным и не даёт токенам попасть в дамп.
"""
from __future__ import annotations
import datetime as dt
import hashlib
import os
import time
import unittest
import harness
class Lifecycle(unittest.TestCase):
"""Выдача, использование, отзыв."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
cls.alice = harness.account(cls.api, "sess_alice")
def token_of(self):
return harness.login(self.api, self.alice["username"], self.alice["password"])["token"]
def expire_delta(self, session):
expires = dt.datetime.fromisoformat(session["expires_at"].replace("Z", "+00:00"))
return (expires - dt.datetime.now(dt.timezone.utc)).total_seconds()
def test_session_matches_the_contract(self):
session = harness.login(self.api, self.alice["username"], self.alice["password"])
self.assertEqual(session["token_type"], "Bearer")
self.assertEqual(session["user"], self.api.call("GET", "/api/v1/users/me", 200,
actor=session, schema="User")["json"])
expected = int(os.environ.get("SESSION_TTL_SECONDS", "3600"))
remaining = self.expire_delta(session)
self.assertGreater(remaining, 0, "свежая сессия не должна родиться просроченной")
self.assertLessEqual(remaining, expected + 60,
"expires_at дальше, чем настроенный TTL")
def test_two_sessions_are_independent(self):
first, second = self.token_of(), self.token_of()
self.assertNotEqual(first, second)
for token in (first, second):
self.api.call("GET", "/api/v1/users/me", 200, actor={"token": token}, schema="User")
self.api.call("DELETE", "/api/v1/auth/sessions/current", 204, actor={"token": first})
self.api.call("GET", "/api/v1/users/me", [401], actor={"token": first})
self.api.call("GET", "/api/v1/users/me", 200, actor={"token": second},
schema="User")
def test_logout_returns_an_empty_204_and_then_401(self):
token = self.token_of()
response = self.api.call("DELETE", "/api/v1/auth/sessions/current", 204,
actor={"token": token})
self.assertEqual(response["bytes"], b"", "ответ 204 не должен содержать тело")
self.api.call("DELETE", "/api/v1/auth/sessions/current", [401], actor={"token": token})
def test_revocation_closes_every_route(self):
alice = harness.account(self.api, "sess_revoked")
bob = harness.account(self.api, "sess_revoked_bob")
chat = harness.chat(self.api, alice, [bob])
harness.send(self.api, alice, chat, "Сообщение до отзыва")
self.api.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=alice)
for method, path, body in (
("GET", "/api/v1/users/me", None),
("GET", "/api/v1/chats", None),
("GET", "/api/v1/chats/" + chat["id"], None),
("GET", "/api/v1/chats/" + chat["id"] + "/messages", None),
("POST", "/api/v1/chats/" + chat["id"] + "/messages", {"text": "после отзыва"}),
("POST", "/api/v1/chats", {"title": "Чат", "member_ids": [alice["id"]]}),
):
with self.subTest(path=path):
self.api.call(method, path, [401], actor=alice, body=body)
def test_missing_and_unknown_tokens(self):
for headers in ({}, {"Authorization": "Bearer " + "A" * 43},
{"Authorization": "Bearer " + self.alice["token"] + "x"}):
with self.subTest(headers=headers):
self.api.call("GET", "/api/v1/users/me", [401], headers=headers)
def test_session_survives_an_api_process_restart(self):
"""Сессии не в памяти процесса: перезапуск только API их сохраняет."""
harness.require_docker(self)
token = self.token_of()
self.api.call("GET", "/api/v1/users/me", 200, actor={"token": token}, schema="User")
restart = harness.compose("restart", "--timeout", "10", "api")
self.assertEqual(restart.returncode, 0, restart.stderr.strip()[:200])
harness.wait_ready()
self.api.call("GET", "/api/v1/users/me", 200, actor={"token": token}, schema="User")
class Storage(unittest.TestCase):
"""Как сессия на самом деле выглядит внутри Valkey."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
cls.alice = harness.account(cls.api, "sess_store")
harness.require_docker(cls)
def test_token_is_not_stored_verbatim(self):
token = harness.login(self.api, self.alice["username"], self.alice["password"])["token"]
fingerprint = hashlib.sha256(token.encode("utf-8")).hexdigest()
self.assertEqual(harness.valkey("EXISTS", harness.SESSION_KEY_PREFIX + fingerprint), "1",
"сессия ожидается под ключом sha256(token)")
keys = harness.valkey("--scan", "--pattern", harness.SESSION_KEY_PREFIX + "*").split()
self.assertTrue(keys, "ключи сессий вообще не найдены")
for key in keys:
self.assertNotIn(token, key, "сырой токен попал в имя ключа")
ttl = int(harness.valkey("TTL", harness.SESSION_KEY_PREFIX + fingerprint))
self.assertGreater(ttl, 0, "у ключа сессии нет срока жизни: он переживёт токен")
self.assertLessEqual(ttl, int(os.environ.get("SESSION_TTL_SECONDS", "3600")) + 1)
def test_revocation_removes_the_key(self):
token = harness.login(self.api, self.alice["username"], self.alice["password"])["token"]
key = harness.SESSION_KEY_PREFIX + hashlib.sha256(token.encode("utf-8")).hexdigest()
self.assertEqual(harness.valkey("EXISTS", key), "1")
self.api.call("DELETE", "/api/v1/auth/sessions/current", 204, actor={"token": token})
self.assertEqual(harness.valkey("EXISTS", key), "0",
"отзыв должен удалять ключ, а не просто помечать его")
def test_token_entropy(self):
"""16 входов подряд должны дать 16 разных токенов: повтор ломал бы отзыв."""
tokens = set()
for _ in range(16):
tokens.add(harness.login(self.api, self.alice["username"], self.alice["password"])["token"])
self.assertEqual(len(tokens), 16)
self.assertTrue(all(len(item) >= 32 for item in tokens))
class ExpiryIsEnforcedByTheStore(unittest.TestCase):
"""Ключ, истекающий сам по себе, должен перестать аутентифицировать — без задачи очистки."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
harness.require_docker(cls)
def test_vanishing_key_means_unauthorized(self):
alice = harness.account(self.api, "sess_gone")
token = alice["token"]
key = harness.SESSION_KEY_PREFIX + hashlib.sha256(token.encode("utf-8")).hexdigest()
self.api.call("GET", "/api/v1/users/me", 200, actor=alice, schema="User")
self.assertEqual(harness.valkey("DEL", key), "1")
self.api.call("GET", "/api/v1/users/me", [401], actor=alice)
self.api.call("DELETE", "/api/v1/auth/sessions/current", [401], actor=alice)
time.sleep(0.1)
if __name__ == "__main__":
unittest.main(verbosity=2)
+185
View File
@@ -0,0 +1,185 @@
"""Некорректные запросы: всегда конверт контракта, никогда — утёкшее значение.
Контракт указывает 400 для любого тела, которое сервер отклоняет, и нигде не
содержит 422, поэтому отклонённое поле не должно всплывать как стандартный
ответ валидации FastAPI. В одном из таких тел передаётся пароль — именно за
этим полем и стоит следить.
"""
from __future__ import annotations
import json
import unittest
import uuid
import harness
class RequestBodies(unittest.TestCase):
"""Некорректный JSON и некорректные поля одинаково возвращаются как 400 invalid_request."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
cls.alice = harness.account(cls.api, "val_alice")
def assert_invalid(self, response):
self.assertEqual(response["status"], 400)
self.assertEqual(response["json"]["error"]["code"], "invalid_request")
self.assertNotIn("detail", response["json"], "утёк стандартный ответ FastAPI")
return response
def test_unknown_json_field_is_refused(self):
body = {"username": harness.unique("extra"), "display_name": "Студент",
"password": harness.fresh_password(), "is_admin": True}
self.assert_invalid(self.api.call("POST", "/api/v1/users", [400], body=body))
def test_broken_json_is_refused_without_echoing_it(self):
secret = harness.fresh_password()
raw = json.dumps({"username": "broken", "password": secret}).encode()[:-1]
response = self.api.call("POST", "/api/v1/users", [400], raw=raw,
headers={"Content-Type": "application/json"})
self.assert_invalid(response)
self.assertNotIn(secret, response["bytes"].decode("utf-8", "replace"))
def test_missing_required_fields(self):
cases = (
("/api/v1/users", {"username": harness.unique("nofield")}),
("/api/v1/chats", {"title": "Чат"}),
)
for path, body in cases:
with self.subTest(path=path):
self.assert_invalid(self.api.call("POST", path, [400], actor=self.alice, body=body))
def test_username_pattern(self):
for username in ("ab", "A" * 3, "a" * 33, "with-dash", "with space", "кириллица"):
with self.subTest(username=username):
body = {"username": username, "display_name": "Студент",
"password": harness.fresh_password()}
self.assert_invalid(self.api.call("POST", "/api/v1/users", [400], body=body))
def test_display_name_and_title_limits(self):
cases = (
("/api/v1/users", {"username": harness.unique("long"), "display_name": "x" * 101,
"password": harness.fresh_password()}),
("/api/v1/chats", {"title": "x" * 101, "member_ids": [self.alice["id"]]}),
("/api/v1/chats", {"title": " ", "member_ids": [self.alice["id"]]}),
("/api/v1/chats", {"title": "", "member_ids": [self.alice["id"]]}),
)
for path, body in cases:
with self.subTest(path=path, length=len(str(body))):
self.assert_invalid(self.api.call("POST", path, [400], actor=self.alice, body=body))
def test_nul_is_refused_before_it_reaches_the_store(self):
"""U+0000 не хранится в `text`: это 400, а не ложная недоступность базы."""
nul = "x\u0000y"
self.assert_invalid(self.api.call(
"POST", "/api/v1/users", [400],
body={"username": harness.unique("nul"), "display_name": nul,
"password": harness.fresh_password()},
))
self.assert_invalid(self.api.call(
"POST", "/api/v1/chats", [400], actor=self.alice,
body={"title": nul, "member_ids": [self.alice["id"]]},
))
chat = harness.chat(self.api, self.alice, [], title="NUL в сообщении")
self.assert_invalid(self.api.call(
"POST", "/api/v1/chats/" + chat["id"] + "/messages", [400],
actor=self.alice, body={"text": nul},
))
def test_message_text_limits(self):
chat = harness.chat(self.api, self.alice, [], title="Лимиты текста")
for text in ("x" * 4001, " ", ""):
with self.subTest(length=len(text)):
self.assert_invalid(self.api.call(
"POST", "/api/v1/chats/" + chat["id"] + "/messages", [400],
actor=self.alice, body={"text": text},
))
self.assertEqual(len(harness.send(self.api, self.alice, chat, "x" * 4000)["text"]), 4000)
def test_sender_id_cannot_be_injected(self):
chat = harness.chat(self.api, self.alice, [], title="Отправитель")
self.assert_invalid(self.api.call(
"POST", "/api/v1/chats/" + chat["id"] + "/messages", [400], actor=self.alice,
body={"text": "Подмена", "sender_id": str(uuid.uuid4())},
))
def test_the_password_never_appears_in_an_error(self):
secret = harness.fresh_password()
body = {"username": harness.unique("leak"), "display_name": "x" * 101, "password": secret}
response = self.api.call("POST", "/api/v1/users", [400], body=body)
self.assert_invalid(response)
raw = response["bytes"].decode("utf-8", "replace")
self.assertNotIn(secret, raw, "пароль вернулся в ответе")
self.assertNotIn(secret, response["json"]["error"]["message"])
class QueryParameters(unittest.TestCase):
"""limit и cursor проверяются до выполнения любого SQL."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
cls.alice = harness.account(cls.api, "val_page")
cls.chat = harness.chat(cls.api, cls.alice, [], title="Параметры")
def test_limit_bounds(self):
for limit, expected in ((0, 400), (101, 400), (1, 200), (100, 200)):
with self.subTest(limit=limit):
self.api.call("GET", "/api/v1/chats?limit=%d" % limit, expected,
actor=self.alice, schema="ChatPage")
self.api.call(
"GET", "/api/v1/chats/%s/messages?limit=%d" % (self.chat["id"], limit),
expected, actor=self.alice, schema="MessagePage",
)
def test_non_numeric_limit(self):
self.assert_invalid_route("/api/v1/chats?limit=many")
self.assert_invalid_route("/api/v1/chats?limit=")
def assert_invalid_route(self, path):
response = self.api.call("GET", path, [400], actor=self.alice)
self.assertEqual(response["json"]["error"]["code"], "invalid_request")
self.assertNotIn("detail", response["json"])
def test_invalid_chat_id(self):
for chat_id in ("not-a-uuid", "1234", "1-2-3-4", "x" * 36):
with self.subTest(chat_id=chat_id):
self.api.call("GET", "/api/v1/chats/" + chat_id, [400], actor=self.alice)
def test_tampered_cursor_is_refused(self):
harness.chat(self.api, self.alice, [], title="Второй чат для курсора")
page = self.api.call("GET", "/api/v1/chats?limit=1", 200, actor=self.alice,
schema="ChatPage")["json"]
cursor = page["next_cursor"]
self.assertIsNotNone(cursor)
middle = len(cursor) // 2
replaced = "A" if cursor[middle] != "A" else "B"
tampered = cursor[:middle] + replaced + cursor[middle + 1:]
self.assert_invalid_route("/api/v1/chats?limit=1&cursor=" + tampered)
def test_empty_cursor_is_refused(self):
self.assert_invalid_route("/api/v1/chats?limit=1&cursor=")
class Routing(unittest.TestCase):
"""Неизвестные маршруты и методы всё равно отвечают конвертом контракта."""
@classmethod
def setUpClass(cls):
cls.api = harness.client()
def test_unknown_route(self):
response = self.api.call("GET", "/api/v1/nothing-here", [404], headers={})
self.assertEqual(response["json"]["error"]["code"], "not_found")
def test_wrong_method(self):
for method, path in (("PATCH", "/api/v1/users/me"), ("PUT", "/health/live"),
("DELETE", "/api/v1/chats")):
with self.subTest(method=method, path=path):
response = self.api.call(method, path, [405], headers={})
self.assertEqual(response["json"]["error"]["code"], "invalid_request")
if __name__ == "__main__":
unittest.main(verbosity=2)
+223
View File
@@ -0,0 +1,223 @@
#!/usr/bin/env python3
"""Падение Valkey, а не его остановка: что теряется и что возвращается.
python student-tests/valkey_crash.py
`docker compose stop` отправляет SIGTERM: Valkey успевает дописать журнал и
закрыть файлы. Здесь два более грубых сценария.
1. **Гибнет сам процесс** (`kill -9` процессу valkey-server внутри контейнера).
Так выглядит настоящий сбой: OOM, падение в библиотеке. Контейнер при этом
не считается остановленным вручную, поэтому политика `restart: unless-stopped`
поднимает его заново, а журнал AOF восстанавливает сессии. При
`appendfsync everysec` сброс на диск идёт раз в секунду, поэтому сессия,
созданная прямо перед падением, может не вернуться — это окно измеряется,
а не замалчивается.
2. **Контейнер убивают снаружи** (`docker compose kill`). Docker помечает такой
контейнер остановленным вручную и **не перезапускает его**, хотя политика
restart задана. Это не дефект стенда, а свойство Docker, о котором надо
знать: после `docker kill` хранилище поднимает оператор, а не политика.
Обязательными считаются только утверждения, которые обязаны выполняться всегда:
во время отказа бизнес-маршрут отвечает 503 (и никогда 401 — иначе клиент
выбросит рабочую сессию), ответ приходит быстрее бюджета таймаутов, упавший
процесс возвращается по политике restart, а сессия старше секунды возвращается
из AOF. Судьба младшей сессии — наблюдение, а не вердикт.
Управление контейнерами разрушительно, поэтому скрипт запускается явно, а не в
общем прогоне `make student-test`.
"""
from __future__ import annotations
import argparse
import hashlib
import os
import subprocess
import sys
import time
from pathlib import Path
HERE = Path(__file__).resolve().parent
if str(HERE) not in sys.path:
sys.path.insert(0, str(HERE))
import harness # noqa: E402 (путь добавлен выше)
DEFAULT_BASE_URL = "http://127.0.0.1:8080"
SLOWEST_ALLOWED = 2.0
# Сессия, прожившая столько, обязана лежать на диске: everysec пишет раз в секунду.
DURABLE_AGE_SECONDS = 2.0
RECOVERY_TIMEOUT = 90.0
# Убить именно сервер, а не tini: тогда контейнер завершается как упавший,
# и решение о перезапуске остаётся за политикой restart.
KILL_SERVER = (
'for p in /proc/[0-9]*; do c=$(tr "\\0" " " < "$p/cmdline" 2>/dev/null); '
'case "$c" in valkey-server*) echo "убиваю ${p#/proc/}: $c"; kill -9 "${p#/proc/}";; esac; done'
)
PASSED: list[str] = []
FAILED: list[str] = []
def say(message: str = "") -> None:
print(message, flush=True)
def section(title: str) -> None:
say()
say("=" * 72)
say(title)
say("=" * 72)
def record(ok: bool, what: str, detail: str = "") -> bool:
(PASSED if ok else FAILED).append(what)
say(" [%s] %s%s" % ("OK" if ok else "FAIL", what, (" — " + detail) if detail else ""))
return ok
def inspect(container: str, template: str) -> str:
"""Значение из `docker inspect` или пустая строка, если контейнера нет."""
result = subprocess.run(
["docker", "inspect", "-f", template, container],
cwd=str(harness.ROOT), capture_output=True, text=True, encoding="utf-8",
errors="replace", env=harness.docker_env(), timeout=60,
)
return result.stdout.strip() if result.returncode == 0 else ""
def session_key(token: str) -> str:
"""Ключ сессии в Valkey: приложение хранит sha256 токена, а не сам токен."""
return harness.SESSION_KEY_PREFIX + hashlib.sha256(token.encode("utf-8")).hexdigest()
def short(key: str) -> str:
return harness.SESSION_KEY_PREFIX + key[len(harness.SESSION_KEY_PREFIX):][:16] + "…"
def usable(api, actor: dict) -> bool:
"""Работает ли сессия прямо сейчас: ключ на месте и запрос проходит."""
if harness.valkey("EXISTS", session_key(actor["token"])) != "1":
return False
try:
api.call("GET", "/api/v1/users/me", actor=actor, schema="User")
except Exception: # noqa: BLE001 — интересен только факт отказа
return False
return True
def report_outage(api, actor: dict) -> None:
"""Что видит клиент, пока хранилище недоступно."""
response = api.call("GET", "/api/v1/users/me", [503], actor=actor)
say(" GET /api/v1/users/me %6.3fs %s"
% (response["elapsed"], response["json"]["error"]["code"]))
record(response["json"]["error"]["code"] == "unavailable",
"во время отказа бизнес-маршрут отвечает 503, а не 401")
record(response["elapsed"] < SLOWEST_ALLOWED,
"ответ не ждёт восстановления зависимости",
"%.3fs при бюджете %.1fs" % (response["elapsed"], SLOWEST_ALLOWED))
def wait_recovered() -> float:
"""Ждёт, пока хранилище станет здоровым, а вслед за ним и стенд."""
started = time.monotonic()
while time.monotonic() - started < RECOVERY_TIMEOUT:
if inspect(harness.VALKEY_CONTAINER, "{{.State.Health.Status}}") == "healthy":
try:
harness.wait_ready(timeout=10)
return time.monotonic() - started
except Exception: # noqa: BLE001 — api догоняет valkey
pass
time.sleep(0.25)
return -1.0
def main() -> int:
parser = argparse.ArgumentParser(description="Падение Valkey: потеря и восстановление")
parser.add_argument("--base-url", default=os.environ.get("BASE_URL", DEFAULT_BASE_URL))
arguments = parser.parse_args()
os.environ["BASE_URL"] = arguments.base_url
api = harness.client(timeout=5)
harness.wait_ready(timeout=60)
section("Подготовка: две сессии разного возраста")
old = harness.account(api, "crash_old")
say(" сессия старшая создана, ключ %s" % short(session_key(old["token"])))
time.sleep(DURABLE_AGE_SECONDS)
say(" прошло %.1fs — журнал успел сбросить её на диск" % DURABLE_AGE_SECONDS)
young = harness.account(api, "crash_young")
say(" сессия младшая создана прямо перед падением, ключ %s"
% short(session_key(young["token"])))
record(usable(api, old) and usable(api, young), "обе сессии работают до падения")
keys_before = harness.valkey("DBSIZE")
restarts_before = inspect(harness.VALKEY_CONTAINER, "{{.RestartCount}}")
say(" ключей в Valkey до падения: %s, перезапусков контейнера: %s"
% (keys_before, restarts_before))
section("Отказ 1: гибнет сам процесс valkey-server")
say("$ docker compose exec -T valkey sh -c '<найти valkey-server и kill -9>'")
killed = harness.compose("exec", "-T", "valkey", "sh", "-c", KILL_SERVER, timeout=60)
for line in (killed.stdout or "").splitlines():
say(" " + line.strip())
record(killed.returncode == 0, "процесс убит сигналом SIGKILL")
report_outage(api, old)
recovered = wait_recovered()
record(recovered >= 0, "контейнер поднялся сам по политике restart: unless-stopped",
"готов через %.2fs" % recovered if recovered >= 0 else "не дождались")
restarts_after = inspect(harness.VALKEY_CONTAINER, "{{.RestartCount}}")
say(" RestartCount: %s → %s, состояние %s"
% (restarts_before, restarts_after,
inspect(harness.VALKEY_CONTAINER, "{{.State.Status}}")))
old_key = session_key(old["token"])
say(" старший ключ: EXISTS %s, TTL %s"
% (harness.valkey("EXISTS", old_key), harness.valkey("TTL", old_key)))
record(usable(api, old), "сессия старше секунды пережила падение процесса",
"тот же токен снова принимается, TTL не продлён")
if usable(api, young):
say(" [--] сессия, созданная за доли секунды до SIGKILL, тоже уцелела:")
say(" сброс журнала успел пройти — на этом прогоне окно потери не выстрелило")
else:
say(" [--] сессия, созданная за доли секунды до SIGKILL, не вернулась:")
say(" это и есть окно потери около секунды при appendfsync everysec")
section("Отказ 2: контейнер убивают снаружи — docker compose kill")
killed = harness.compose("kill", "valkey", timeout=60)
say("$ docker compose kill valkey # код %d" % killed.returncode)
time.sleep(1.0)
state = inspect(harness.VALKEY_CONTAINER, "{{.State.Status}}")
say(" состояние контейнера через секунду: %s" % state)
report_outage(api, old)
time.sleep(3.0)
still = inspect(harness.VALKEY_CONTAINER, "{{.State.Status}}")
restarts_still = inspect(harness.VALKEY_CONTAINER, "{{.RestartCount}}")
record(still != "running",
"политика restart не поднимает контейнер, убитый снаружи",
"состояние %s, RestartCount %s" % (still, restarts_still))
say(" Так и должно быть: `docker kill` — ручное действие, и Docker отличает его от")
say(" падения процесса. Хранилище поднимает оператор, а не политика.")
say("$ docker compose start valkey")
harness.compose("start", "valkey", timeout=180)
recovered = wait_recovered()
record(recovered >= 0, "после ручного старта стенд снова готов",
"через %.2fs" % recovered if recovered >= 0 else "не дождались")
record(usable(api, old),
"сессия пережила и это: журнал AOF пишется независимо от того, как именно умер процесс")
keys_after = harness.valkey("DBSIZE")
say(" ключей в Valkey после двух отказов: %s (до них было %s)" % (keys_after, keys_before))
section("Итог")
say(" успешно: %d" % len(PASSED))
for what in FAILED:
say(" провалено: %s" % what)
say()
say("РЕЗУЛЬТАТ: %s" % ("PASS" if not FAILED else "FAIL"))
return 0 if not FAILED else 1
if __name__ == "__main__":
raise SystemExit(main())
+304
View File
@@ -0,0 +1,304 @@
#!/usr/bin/env python3
"""Инфраструктурные проверки стенда лабораторной 2; код возврата 0 — только если всё прошло.
python student-tests/verify_stack.py
Проверяет то, чего не видно через HTTP: пользователя внутри контейнера, отсутствие
публикации PostgreSQL и Valkey, файловые секреты и их отсутствие в выводе
`docker compose config`, настройки долговечности Valkey, соответствие схемы
миграциям и наличие ровно тех индексов и ограничений, на которые опираются
запросы. Требуется запущенный Docker и поднятый стенд.
"""
from __future__ import annotations
import argparse
import hashlib
import os
import platform
import subprocess
import sys
import time
from pathlib import Path
HERE = Path(__file__).resolve().parent
if str(HERE) not in sys.path:
sys.path.insert(0, str(HERE))
import harness # noqa: E402 (путь добавлен выше)
ROOT = harness.ROOT
DEFAULT_BASE_URL = "http://127.0.0.1:8080"
API_CONTAINER = harness.API_CONTAINER
POSTGRES_CONTAINER = harness.POSTGRES_CONTAINER
VALKEY_CONTAINER = harness.VALKEY_CONTAINER
MIGRATE_CONTAINER = "mtusi2026lab2-migrate-1"
APP_UID = "10001"
EXPECTED_INDEXES = (
"ix_messages_chat_id_created_at_id",
"ix_chat_members_user_id_chat_id",
"uq_users_username",
)
EXPECTED_CHECKS = (
"users:ck_users_username_format",
"users:ck_users_display_name_length",
"chats:ck_chats_title_length",
"messages:ck_messages_text_length",
)
PASSED: list[str] = []
FAILED: list[str] = []
def say(message: str = "") -> None:
print(message, flush=True)
def section(title: str) -> None:
say()
say("=" * 72)
say(title)
say("=" * 72)
def record(ok: bool, what: str, detail: str = "") -> bool:
(PASSED if ok else FAILED).append(what)
say(" [%s] %s%s" % ("OK" if ok else "FAIL", what, (" — " + detail) if detail else ""))
return ok
def docker(*arguments: str) -> subprocess.CompletedProcess:
"""`docker ...` с окружением, в котором docker CLI находит свои плагины."""
say("$ docker " + " ".join(arguments))
result = subprocess.run(
["docker", *arguments], cwd=str(ROOT), capture_output=True, text=True,
encoding="utf-8", errors="replace", env=harness.docker_env(), timeout=120,
)
if result.stdout.strip():
say(result.stdout.strip())
if result.stderr.strip():
say(result.stderr.strip())
return result
def compose(*arguments: str) -> subprocess.CompletedProcess:
say("$ docker compose " + " ".join(arguments))
result = harness.compose(*arguments)
if result.stdout.strip():
say(result.stdout.strip())
if result.stderr.strip():
say(result.stderr.strip())
return result
def compose_field(*arguments: str) -> str:
"""Тот же compose, но без печати вывода: для проверок вида «верни одно значение»."""
return harness.compose(*arguments).stdout.strip()
def valkey_config(name: str) -> str:
"""Значение CONFIG GET: пустое значение — это когда второй строки нет."""
lines = harness.valkey("CONFIG", "GET", name).splitlines()
return lines[1].strip() if len(lines) > 1 else ""
def container_state(name: str, template: str) -> str:
result = subprocess.run(
["docker", "inspect", "--format", template, name], cwd=str(ROOT),
capture_output=True, text=True, encoding="utf-8", errors="replace",
env=harness.docker_env(), timeout=60,
)
return result.stdout.strip()
def main() -> int:
parser = argparse.ArgumentParser(description="Проверка стенда лабораторной 2")
parser.add_argument("--base-url",
default=os.environ.get("BASE_URL", DEFAULT_BASE_URL))
arguments = parser.parse_args()
section("Аппаратура и версии")
say(" хост: %s %s (%s)" % (platform.system(), platform.release(), platform.machine()))
say(" python: %s" % platform.python_version())
say(" стенд: %s" % ROOT)
section("0. Docker и Compose доступны")
if not record(harness.docker_available(), "docker compose отвечает"):
say("Запустите Docker Desktop и повторите.")
return 1
say(" docker: %s" % compose_field("version", "--short"))
say(" compose: %s" % compose_field("version", "--format", "{{.Version}}"))
section("1. Состав стенда")
compose("ps", "--all")
running = compose_field("ps", "--status", "running", "--services").split()
for service in ("api", "postgres", "valkey"):
record(service in running, "сервис %s запущен" % service)
migrate_exit = container_state(MIGRATE_CONTAINER, "{{.State.ExitCode}}")
record(migrate_exit == "0", "одноразовая миграция завершилась с кодом %s" % migrate_exit)
config = harness.compose("config").stdout
pinned = [line.strip() for line in config.splitlines() if "image:" in line and "@sha256:" in line]
for line in pinned:
say(" %s" % line)
record(len(pinned) >= 2, "образы postgres и valkey закреплены по digest", "%d строк" % len(pinned))
section("2. Непривилегированный пользователь")
identity = compose_field("exec", "-T", "api", "id")
say(" $ docker compose exec -T api id -> %s" % identity)
record("uid=%s" % APP_UID in identity, "процесс работает под uid %s" % APP_UID)
configured_user = container_state(API_CONTAINER, "{{.Config.User}}")
record(configured_user.startswith(APP_UID),
"USER образа равен %s" % APP_UID, configured_user)
status = harness.compose("exec", "-T", "api", "cat", "/proc/1/status").stdout
uid_line = [line for line in status.splitlines() if line.startswith("Uid:")]
record(bool(uid_line) and uid_line[0].split()[1] == APP_UID,
"PID 1 работает не от root", uid_line[0].strip() if uid_line else "нет строки Uid")
caps = container_state(API_CONTAINER, "{{.HostConfig.CapDrop}} {{.HostConfig.Privileged}}")
say(" CapDrop/Privileged: %s" % caps)
section("3. Сеть: что и куда публикуется")
for name, service in ((POSTGRES_CONTAINER, "postgres"), (VALKEY_CONTAINER, "valkey")):
bindings = container_state(name, "{{json .HostConfig.PortBindings}}")
record(bindings in ("", "null", "{}"), "%s не публикует порты" % service, bindings)
api_bindings = container_state(API_CONTAINER, "{{json .HostConfig.PortBindings}}")
say(" api: %s" % api_bindings)
record("127.0.0.1" in api_bindings and "0.0.0.0" not in api_bindings,
"API опубликован только на loopback")
section("4. Секреты")
secrets_dir = ROOT / "secrets"
names = sorted(path.name for path in secrets_dir.glob("*") if path.is_file())
say(" файлы: %s" % ", ".join(names))
record(bool(names), "каталог secrets/ заполнен")
ignored = subprocess.run(
["git", "check-ignore", *[str(secrets_dir / name) for name in names], ".env"],
cwd=str(ROOT), capture_output=True, text=True, encoding="utf-8", errors="replace",
)
record(ignored.returncode == 0, "secrets/ и .env вне Git (git check-ignore)")
tracked = subprocess.run(
["git", "ls-files", "secrets"], cwd=str(ROOT), capture_output=True, text=True,
encoding="utf-8", errors="replace",
).stdout.strip()
record(not tracked, "в индексе Git нет файлов secrets/")
password = (secrets_dir / "postgres_password").read_text(encoding="utf-8").strip()
record(bool(password) and password not in harness.compose("config").stdout,
"docker compose config не печатает пароль PostgreSQL")
database_url = (secrets_dir / "database_url").read_text(encoding="utf-8").strip()
record(password in database_url and database_url not in harness.compose("config").stdout,
"database_url с паролем тоже не попадает в вывод compose")
seen = harness.compose("exec", "-T", "api", "ls", "-l", "/run/secrets").stdout
say(" /run/secrets:\n%s" % seen.rstrip())
record("database_url" in seen and "cache_url" in seen,
"секреты смонтированы файлами в /run/secrets")
environment = harness.compose("exec", "-T", "api", "env").stdout
record("DATABASE_URL_FILE=/run/secrets/database_url" in environment,
"контейнер получает *_FILE, а не значение")
record(password not in environment and database_url not in environment,
"значений секретов нет в окружении процесса")
section("5. Valkey: долговечность сессий")
for name, expected in (("appendonly", "yes"), ("appendfsync", "everysec"), ("save", "")):
actual = valkey_config(name)
record(actual == expected, "CONFIG GET %s = %r" % (name, expected), "получено %r" % actual)
persistence = harness.valkey("INFO", "persistence")
aof_enabled = [line for line in persistence.splitlines() if line.startswith("aof_enabled:")]
record(aof_enabled[:1] == ["aof_enabled:1"], "INFO persistence подтверждает AOF",
aof_enabled[0] if aof_enabled else "нет строки aof_enabled")
volume = container_state(VALKEY_CONTAINER, "{{range .Mounts}}{{.Destination}} {{end}}")
record("/data" in volume, "данные лежат в именованном томе", volume.strip())
section("6. PostgreSQL: схема, миграции, индексы")
version = harness.psql("SELECT version();").strip()
say(" %s" % version.split(" on ")[0])
record("PostgreSQL 16" in version, "версия PostgreSQL соответствует compose")
current = compose_field("run", "--rm", "migrate", "alembic", "current")
record("(head)" in current, "схема находится на head", current.splitlines()[-1].strip())
first = harness.compose("run", "--rm", "migrate")
second = harness.compose("run", "--rm", "migrate")
record(first.returncode == 0 and second.returncode == 0,
"alembic upgrade head проходит повторно без ошибок")
record("Running upgrade" not in second.stdout + second.stderr,
"повторный прогон миграции ничего не меняет (нет Running upgrade)")
check = harness.compose("run", "--rm", "migrate", "alembic", "check")
record("No new upgrade operations detected" in check.stdout + check.stderr,
"alembic check: миграция совпадает с моделями SQLAlchemy")
indexes = dict(
line.split(" :: ", 1)
for line in harness.psql(
"SELECT indexname || ' :: ' || indexdef FROM pg_indexes WHERE schemaname = 'public';"
).splitlines()
if " :: " in line
)
for name in EXPECTED_INDEXES:
record(name in indexes, "индекс %s существует" % name, indexes.get(name, "нет"))
checks = set()
for line in harness.psql(
"SELECT conrelid::regclass || ' : ' || conname FROM pg_constraint "
"WHERE connamespace = 'public'::regnamespace AND contype = 'c';"
).splitlines():
if " : " in line:
left, right = line.split(" : ", 1)
checks.add("%s:%s" % (left.strip(), right.strip()))
for name in EXPECTED_CHECKS:
record(name in checks, "CHECK-ограничение %s существует" % name)
say(" все ограничения: %s" % ", ".join(sorted(checks)))
section("7. Сквозная проверка через HTTP")
api = harness.client()
username = harness.unique("stack")
secret = harness.fresh_password()
user = harness.register(api, username, secret)
session = harness.login(api, username, secret)
record(bool(session["token"]) and len(session["token"]) >= 32,
"вход выдаёт opaque-токен длиной %d" % len(session["token"]))
actor = {"token": session["token"], "id": user["id"], "username": username, "password": secret}
me = api.call("GET", "/api/v1/users/me", 200, actor=actor, schema="User")["json"]
record(me["id"] == user["id"], "/users/me возвращает владельца сессии")
record("password" not in me and "password_hash" not in me,
"в ответе нет ни пароля, ни его хэша")
key = harness.SESSION_KEY_PREFIX + hashlib.sha256(session["token"].encode()).hexdigest()
record(harness.valkey("EXISTS", key) == "1", "сессия лежит в Valkey")
record(session["token"] not in key, "ключ — sha256 токена, а не сам токен")
ttl = int(harness.valkey("TTL", key))
record(0 < ttl <= 3600, "у ключа положительный TTL", "%d s" % ttl)
record(harness.valkey("KEYS", harness.SESSION_KEY_PREFIX + session["token"] + "*") == "",
"сырой токен не встречается ни в одном имени ключа")
section("8. Логи не содержат секретов")
logs = harness.compose("logs", "--no-color", "api")
text = logs.stdout + logs.stderr
say(" всего строк лога: %d" % len(text.splitlines()))
for label, needle in (("пароль", secret), ("токен", session["token"]),
("ключ сессии", key)):
record(needle not in text, "во всём логе нет %s" % label)
record("cursor=" not in text, "во всём логе нет query-строки с курсором")
record("Authorization" not in text and "Basic " not in text,
"во всём логе нет заголовка авторизации")
section("9. Ограничения ресурсов и политика перезапуска")
for name, service in ((API_CONTAINER, "api"), (POSTGRES_CONTAINER, "postgres"),
(VALKEY_CONTAINER, "valkey")):
memory = container_state(name, "{{.HostConfig.Memory}}")
policy = container_state(name, "{{.HostConfig.RestartPolicy.Name}}")
record(memory not in ("", "0") and policy == "unless-stopped",
"%s: память %s Б, restart=%s" % (service, memory, policy))
section("Итог")
say(" успешно: %d" % len(PASSED))
for what in FAILED:
say(" провалено: %s" % what)
say()
say("РЕЗУЛЬТАТ: %s" % ("PASS" if not FAILED else "FAIL"))
return 0 if not FAILED else 1
if __name__ == "__main__":
started = time.monotonic()
try:
raise SystemExit(main())
except SystemExit:
raise
except Exception as error: # noqa: BLE001
say()
say("НЕОЖИДАННАЯ ОШИБКА через %.1f s: %s: %s"
% (time.monotonic() - started, type(error).__name__, error))
raise SystemExit(1) from error