diff --git a/.dockerignore b/.dockerignore index bc16e556..4b96220f 100644 --- a/.dockerignore +++ b/.dockerignore @@ -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 diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..ce49a858 --- /dev/null +++ b/Dockerfile @@ -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"] diff --git a/Makefile b/Makefile index 9ecb223e..8a65ccdc 100644 --- a/Makefile +++ b/Makefile @@ -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)" diff --git a/REPORT.md b/REPORT.md index e42f2b05..fba3861a 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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 && 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:, 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:`. Сам токен (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`), в отчёте осталось наблюдение, а не ожидание. diff --git a/alembic.ini b/alembic.ini new file mode 100644 index 00000000..e299f789 --- /dev/null +++ b/alembic.ini @@ -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 diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..f2856903 --- /dev/null +++ b/compose.yaml @@ -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 diff --git a/evidence/01-check-and-smoke.txt b/evidence/01-check-and-smoke.txt new file mode 100644 index 00000000..a0cf40bc --- /dev/null +++ b/evidence/01-check-and-smoke.txt @@ -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) diff --git a/evidence/02-persistence-restart.txt b/evidence/02-persistence-restart.txt new file mode 100644 index 00000000..16960762 --- /dev/null +++ b/evidence/02-persistence-restart.txt @@ -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) diff --git a/evidence/03-student-tests.txt b/evidence/03-student-tests.txt new file mode 100644 index 00000000..8b0b640c --- /dev/null +++ b/evidence/03-student-tests.txt @@ -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) diff --git a/evidence/04-expiry-short-ttl.txt b/evidence/04-expiry-short-ttl.txt new file mode 100644 index 00000000..c7106323 --- /dev/null +++ b/evidence/04-expiry-short-ttl.txt @@ -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) diff --git a/evidence/05-valkey-outage.txt b/evidence/05-valkey-outage.txt new file mode 100644 index 00000000..ea58d5aa --- /dev/null +++ b/evidence/05-valkey-outage.txt @@ -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 diff --git a/evidence/06-postgres-outage.txt b/evidence/06-postgres-outage.txt new file mode 100644 index 00000000..3a2f9feb --- /dev/null +++ b/evidence/06-postgres-outage.txt @@ -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) diff --git a/evidence/07-explain-messages.txt b/evidence/07-explain-messages.txt new file mode 100644 index 00000000..8dd40593 --- /dev/null +++ b/evidence/07-explain-messages.txt @@ -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 diff --git a/evidence/08-explain-chats.txt b/evidence/08-explain-chats.txt new file mode 100644 index 00000000..d48b5cd9 --- /dev/null +++ b/evidence/08-explain-chats.txt @@ -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 diff --git a/evidence/09-load-c16.json b/evidence/09-load-c16.json new file mode 100644 index 00000000..56ef927c --- /dev/null +++ b/evidence/09-load-c16.json @@ -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." +} diff --git a/evidence/09-load.txt b/evidence/09-load.txt new file mode 100644 index 00000000..a3e554d4 --- /dev/null +++ b/evidence/09-load.txt @@ -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 сообщения — это режим учебного стенда, +при десятках миллионов строк и запись, и индексы будут вести себя иначе; это +ограничение эксперимента, а не свойство схемы. diff --git a/evidence/10-infra-mapping.txt b/evidence/10-infra-mapping.txt new file mode 100644 index 00000000..648ffaae --- /dev/null +++ b/evidence/10-infra-mapping.txt @@ -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. diff --git a/evidence/11-container-security.txt b/evidence/11-container-security.txt new file mode 100644 index 00000000..fe18201e --- /dev/null +++ b/evidence/11-container-security.txt @@ -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 diff --git a/evidence/12-clean-clone.txt b/evidence/12-clean-clone.txt new file mode 100644 index 00000000..8dc111df --- /dev/null +++ b/evidence/12-clean-clone.txt @@ -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"} diff --git a/migrations/env.py b/migrations/env.py new file mode 100644 index 00000000..8478d568 --- /dev/null +++ b/migrations/env.py @@ -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()) diff --git a/migrations/script.py.mako b/migrations/script.py.mako new file mode 100644 index 00000000..c6284cb9 --- /dev/null +++ b/migrations/script.py.mako @@ -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"} diff --git a/migrations/versions/0001_initial_schema.py b/migrations/versions/0001_initial_schema.py new file mode 100644 index 00000000..4cdd21cf --- /dev/null +++ b/migrations/versions/0001_initial_schema.py @@ -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") diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..b567313f --- /dev/null +++ b/requirements.txt @@ -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 diff --git a/scripts/bootstrap-secrets.sh b/scripts/bootstrap-secrets.sh new file mode 100644 index 00000000..9f88e539 --- /dev/null +++ b/scripts/bootstrap-secrets.sh @@ -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 : 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' diff --git a/scripts/restart.cmd b/scripts/restart.cmd new file mode 100644 index 00000000..fa6309c5 --- /dev/null +++ b/scripts/restart.cmd @@ -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 diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100644 index 00000000..e577ce38 --- /dev/null +++ b/scripts/restart.sh @@ -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' diff --git a/src/messenger/__init__.py b/src/messenger/__init__.py new file mode 100644 index 00000000..80be8344 --- /dev/null +++ b/src/messenger/__init__.py @@ -0,0 +1,5 @@ +"""Мессенджер на PostgreSQL и Valkey: лабораторная 2 курса HighLoad (MTUSI).""" + +__all__ = ["__version__"] + +__version__ = "2.0.0" diff --git a/src/messenger/__main__.py b/src/messenger/__main__.py new file mode 100644 index 00000000..df116f9f --- /dev/null +++ b/src/messenger/__main__.py @@ -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()) diff --git a/src/messenger/access.py b/src/messenger/access.py new file mode 100644 index 00000000..a03d541e --- /dev/null +++ b/src/messenger/access.py @@ -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 diff --git a/src/messenger/app.py b/src/messenger/app.py new file mode 100644 index 00000000..29176dc6 --- /dev/null +++ b/src/messenger/app.py @@ -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) diff --git a/src/messenger/config.py b/src/messenger/config.py new file mode 100644 index 00000000..b5a1ddcb --- /dev/null +++ b/src/messenger/config.py @@ -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"), + ) diff --git a/src/messenger/context.py b/src/messenger/context.py new file mode 100644 index 00000000..78f326f4 --- /dev/null +++ b/src/messenger/context.py @@ -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) diff --git a/src/messenger/cursor.py b/src/messenger/cursor.py new file mode 100644 index 00000000..7f55bc15 --- /dev/null +++ b/src/messenger/cursor.py @@ -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 diff --git a/src/messenger/db.py b/src/messenger/db.py new file mode 100644 index 00000000..461d7f92 --- /dev/null +++ b/src/messenger/db.py @@ -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() diff --git a/src/messenger/deps.py b/src/messenger/deps.py new file mode 100644 index 00000000..f93ea2d6 --- /dev/null +++ b/src/messenger/deps.py @@ -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)] diff --git a/src/messenger/domain.py b/src/messenger/domain.py new file mode 100644 index 00000000..53bf7522 --- /dev/null +++ b/src/messenger/domain.py @@ -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 diff --git a/src/messenger/errorhandlers.py b/src/messenger/errorhandlers.py new file mode 100644 index 00000000..2e0048a7 --- /dev/null +++ b/src/messenger/errorhandlers.py @@ -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, "Внутренняя ошибка сервера") diff --git a/src/messenger/errors.py b/src/messenger/errors.py new file mode 100644 index 00000000..42dfd951 --- /dev/null +++ b/src/messenger/errors.py @@ -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) diff --git a/src/messenger/healthcheck.py b/src/messenger/healthcheck.py new file mode 100644 index 00000000..d0585bd0 --- /dev/null +++ b/src/messenger/healthcheck.py @@ -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()) diff --git a/src/messenger/logging_setup.py b/src/messenger/logging_setup.py new file mode 100644 index 00000000..88ee2cd1 --- /dev/null +++ b/src/messenger/logging_setup.py @@ -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, + ) diff --git a/src/messenger/middleware.py b/src/messenger/middleware.py new file mode 100644 index 00000000..99d968b3 --- /dev/null +++ b/src/messenger/middleware.py @@ -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), + ) diff --git a/src/messenger/models.py b/src/messenger/models.py new file mode 100644 index 00000000..c96972de --- /dev/null +++ b/src/messenger/models.py @@ -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) diff --git a/src/messenger/pagination.py b/src/messenger/pagination.py new file mode 100644 index 00000000..4a342dc2 --- /dev/null +++ b/src/messenger/pagination.py @@ -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)) diff --git a/src/messenger/repository.py b/src/messenger/repository.py new file mode 100644 index 00000000..69c04ed5 --- /dev/null +++ b/src/messenger/repository.py @@ -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()} diff --git a/src/messenger/routers/__init__.py b/src/messenger/routers/__init__.py new file mode 100644 index 00000000..acd99363 --- /dev/null +++ b/src/messenger/routers/__init__.py @@ -0,0 +1 @@ +"""Маршруты HTTP API: только разбор запроса, вызов зависимостей и сборка ответа.""" diff --git a/src/messenger/routers/auth.py b/src/messenger/routers/auth.py new file mode 100644 index 00000000..c9ccb566 --- /dev/null +++ b/src/messenger/routers/auth.py @@ -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) diff --git a/src/messenger/routers/chats.py b/src/messenger/routers/chats.py new file mode 100644 index 00000000..dee42e57 --- /dev/null +++ b/src/messenger/routers/chats.py @@ -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)) diff --git a/src/messenger/routers/health.py b/src/messenger/routers/health.py new file mode 100644 index 00000000..42b201a9 --- /dev/null +++ b/src/messenger/routers/health.py @@ -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() diff --git a/src/messenger/routers/messages.py b/src/messenger/routers/messages.py new file mode 100644 index 00000000..4ab331cb --- /dev/null +++ b/src/messenger/routers/messages.py @@ -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) + ) diff --git a/src/messenger/routers/users.py b/src/messenger/routers/users.py new file mode 100644 index 00000000..86dfb6bc --- /dev/null +++ b/src/messenger/routers/users.py @@ -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) diff --git a/src/messenger/schema.py b/src/messenger/schema.py new file mode 100644 index 00000000..c160d759 --- /dev/null +++ b/src/messenger/schema.py @@ -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"), +) diff --git a/src/messenger/security.py b/src/messenger/security.py new file mode 100644 index 00000000..ea0e343a --- /dev/null +++ b/src/messenger/security.py @@ -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) diff --git a/src/messenger/sessions.py b/src/messenger/sessions.py new file mode 100644 index 00000000..e9e5700a --- /dev/null +++ b/src/messenger/sessions.py @@ -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() diff --git a/student-tests/README.md b/student-tests/README.md new file mode 100644 index 00000000..772014dc --- /dev/null +++ b/student-tests/README.md @@ -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/` собраны из такого вывода. diff --git a/student-tests/explain_queries.py b/student-tests/explain_queries.py new file mode 100644 index 00000000..f9025c85 --- /dev/null +++ b/student-tests/explain_queries.py @@ -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 diff --git a/student-tests/harness.py b/student-tests/harness.py new file mode 100644 index 00000000..7f7117f9 --- /dev/null +++ b/student-tests/harness.py @@ -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 недоступен на этом хосте") diff --git a/student-tests/run_all.py b/student-tests/run_all.py new file mode 100644 index 00000000..f3dfe4b7 --- /dev/null +++ b/student-tests/run_all.py @@ -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()) diff --git a/student-tests/seed_messages.py b/student-tests/seed_messages.py new file mode 100644 index 00000000..f0fe5afa --- /dev/null +++ b/student-tests/seed_messages.py @@ -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 diff --git a/student-tests/test_access.py b/student-tests/test_access.py new file mode 100644 index 00000000..25fbf5d9 --- /dev/null +++ b/student-tests/test_access.py @@ -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) diff --git a/student-tests/test_auth.py b/student-tests/test_auth.py new file mode 100644 index 00000000..a753f856 --- /dev/null +++ b/student-tests/test_auth.py @@ -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) diff --git a/student-tests/test_chat_atomicity.py b/student-tests/test_chat_atomicity.py new file mode 100644 index 00000000..28220b44 --- /dev/null +++ b/student-tests/test_chat_atomicity.py @@ -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) diff --git a/student-tests/test_dependency_outage.py b/student-tests/test_dependency_outage.py new file mode 100644 index 00000000..8a9f678a --- /dev/null +++ b/student-tests/test_dependency_outage.py @@ -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) diff --git a/student-tests/test_expiry.py b/student-tests/test_expiry.py new file mode 100644 index 00000000..c59ac168 --- /dev/null +++ b/student-tests/test_expiry.py @@ -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) diff --git a/student-tests/test_health.py b/student-tests/test_health.py new file mode 100644 index 00000000..23a36a72 --- /dev/null +++ b/student-tests/test_health.py @@ -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) diff --git a/student-tests/test_pagination.py b/student-tests/test_pagination.py new file mode 100644 index 00000000..98683df4 --- /dev/null +++ b/student-tests/test_pagination.py @@ -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) diff --git a/student-tests/test_registration_race.py b/student-tests/test_registration_race.py new file mode 100644 index 00000000..62d02f0a --- /dev/null +++ b/student-tests/test_registration_race.py @@ -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) diff --git a/student-tests/test_sessions.py b/student-tests/test_sessions.py new file mode 100644 index 00000000..6de80525 --- /dev/null +++ b/student-tests/test_sessions.py @@ -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) diff --git a/student-tests/test_validation.py b/student-tests/test_validation.py new file mode 100644 index 00000000..eeb4d907 --- /dev/null +++ b/student-tests/test_validation.py @@ -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) diff --git a/student-tests/valkey_crash.py b/student-tests/valkey_crash.py new file mode 100644 index 00000000..280c965f --- /dev/null +++ b/student-tests/valkey_crash.py @@ -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()) diff --git a/student-tests/verify_stack.py b/student-tests/verify_stack.py new file mode 100644 index 00000000..8cbe2f2f --- /dev/null +++ b/student-tests/verify_stack.py @@ -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