Implement lab 2 PostgreSQL persistence and expiring sessions

This commit is contained in:
Горбанюк
2026-10-17 17:43:08 +03:00
parent b65738733c
commit c070b4babc
40 changed files with 7016 additions and 22 deletions
+6
View File
@@ -17,4 +17,10 @@ backups
__pycache__
node_modules
evidence
student-tests
tests
research
REPORT.md
SCHEMA.md
requirements-dev.txt
.DS_Store
+1
View File
@@ -3,6 +3,7 @@
APP_HOST=0.0.0.0
APP_PORT=8080
APP_ENV=lab
PUBLIC_PORT=8082
SESSION_TTL_SECONDS=3600
# Choose credentials locally. File paths contain no secret values.
DATABASE_URL_FILE=/run/secrets/database_url
+1
View File
@@ -0,0 +1 @@
3.14.7
+28
View File
@@ -0,0 +1,28 @@
FROM python:3.14.7-slim-bookworm@sha256:82bc3c539b8813ada9d68c63b40158fa002f7f33de9bf3312a3dfdc0620dff56 AS builder
WORKDIR /app
RUN python -m pip install --no-cache-dir uv==0.12.13
ENV UV_PYTHON_DOWNLOADS=never
COPY pyproject.toml uv.lock .python-version ./
COPY src ./src
RUN uv sync --frozen --no-dev --no-editable --compile-bytecode
FROM python:3.14.7-slim-bookworm@sha256:82bc3c539b8813ada9d68c63b40158fa002f7f33de9bf3312a3dfdc0620dff56
RUN groupadd --gid 10001 app && useradd --uid 10001 --gid app --no-create-home app
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY migrations /app/migrations
ARG VCS_REF=uncommitted
LABEL org.opencontainers.image.revision=$VCS_REF
ENV PATH="/app/.venv/bin:$PATH" \
PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 \
APP_HOST=0.0.0.0 \
APP_PORT=8080 \
APP_ENV=lab \
APP_LOG_LEVEL=INFO
USER 10001:10001
EXPOSE 8080
STOPSIGNAL SIGTERM
HEALTHCHECK --interval=2s --timeout=2s --start-period=5s --retries=3 \
CMD ["python", "-c", "import os, urllib.request; urllib.request.urlopen('http://127.0.0.1:' + os.environ.get('APP_PORT', '8080') + '/health/ready', timeout=1).close()"]
CMD ["python", "-m", "messenger"]
+15 -1
View File
@@ -1,5 +1,5 @@
PYTHON ?= python3
BASE_URL ?= http://localhost:8080
BASE_URL ?= http://127.0.0.1:8082
CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
@@ -24,3 +24,17 @@ 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)
.PHONY: bootstrap up down lint test-student image
bootstrap:
$(PYTHON) scripts/bootstrap.py
up:
VCS_REF=$$(git rev-parse HEAD) docker compose --env-file .env up -d --build --wait
down:
docker compose --env-file .env down
image:
VCS_REF=$$(git rev-parse HEAD) docker compose --env-file .env build
lint:
uv run --locked ruff check src student-tests scripts/bootstrap.py scripts/verify_lifecycle.py research
test-student:
uv run --locked pytest
+116 -21
View File
@@ -1,37 +1,132 @@
# Отчёт — лабораторная 2
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
Автор: **Горбанюк, БВТ2301**. Целевая оценка: **5**, трек 2 «План запроса и восстановление». Подготовлено локально 17.10.2026; форк и МР этой работы пока не создавались.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Нужны Docker с Compose v2+ и make. Для собственных тестов и исследования: Python 3.14.7 и uv 0.12.13. Образы: Python 3.14.7-slim-bookworm с digest из Dockerfile, PostgreSQL 18.3, Valkey 8.1.3-alpine. В uv.lock закреплены FastAPI 0.143.3, Pydantic 2.14.1, Uvicorn 0.54.0, psycopg 3.3.6, psycopg-pool 3.3.3, argon2-cffi 25.1.0, redis client 8.1.0 и транзитивные зависимости.
## Архитектура и решения
```sh
git switch solution/bvt2301-gorbanyuk
make bootstrap
docker compose --env-file .env config --quiet
make up
NO_PROXY=localhost,127.0.0.1 no_proxy=localhost,127.0.0.1 make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
```
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Bootstrap один раз создаёт случайные credentials учебной БД, secret files и .env. Существующие значения сохраняет. Секреты читаются из файлов, не печатаются, не включаются в образ и Git. Родительский secrets/ имеет права 0700; файлы доступны non-root процессу через Compose bind-mount secrets.
## Доказательства критериев
Старт: PostgreSQL healthy → migrate → API healthy. Повтор migrate сверяет checksum и не дублирует DDL/данные. Make up ждёт готовности. API слушает 0.0.0.0:8080, с хоста доступен только http://127.0.0.1:8082. БД и кэш по умолчанию не публикуют порты хоста. Для интеграционных проверок:
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
```sh
uv sync --locked
VCS_REF=$(git rev-parse HEAD) docker compose --env-file .env \
-f compose.yaml -f compose.test.yaml up -d --build --wait
make check validate PYTHON=.venv/bin/python
make lint test-student
uv run --locked python scripts/verify_lifecycle.py --output evidence/lifecycle-repeat.json
uv run --locked python research/query_plan.py --output evidence/query-plan-repeat.json
```
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Override открывает только localhost:55432/56379. Собственные тесты создают отдельную временную БД student_tests_*, исследование — research_* и restored_*. Рабочая messenger не очищается; в finally удаляются только созданные проверками БД. Для новых результатов выбираются новые имена JSON.
## Эксперименты и отказы
```sh
make down # обычная остановка своего стенда: данные остаются
# Только для намеренного удаления ВСЕХ учебных данных lab2:
docker compose --env-file .env down --volumes
```
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Удаление volumes не входит в проверки или restart hook. После обычного down/up нужны прежние secrets и volume. Удаление secret files при сохранённом volume не меняет пароль уже созданной БД.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
## Архитектура и транзакции
Перенесены собственные HTTP-слой, схемы, сервисы, immutable domain values и cursor из lab1. In-memory repository заменён PostgreSQL; X-User-Id заменён Basic → Bearer. README, COURSE, CONTRIBUTING, contracts и публичные tests текущего skeleton сохранены.
Клиент → один API → PostgreSQL; Valkey — восстанавливаемый кэш карточки владельца сессии. Таблицы, ограничения и транзакционные границы зафиксированы в [SCHEMA.md](SCHEMA.md). [Миграция](migrations/001_initial.sql) задаёт PK/FK, UNIQUE username, порядок участников, составной FK автора сообщения в участников и индекс истории (chat_id,created_at,id).
Значения SQL параметризованы. Имена таблиц в исследовании оформляются psycopg.sql.Identifier. Pool: максимум 8 соединений, 32 ожидающих; ожидание 1 с, connect timeout 2 с, statement_timeout 2500 мс, lock_timeout 1000 мс. Соединение проверяется перед выдачей. Ошибка зависимости превращается в безопасный 503 без SQL и credentials.
Каждая запись подтверждается после COMMIT. Создание чата и участников — одна транзакция: ошибочный FK откатывает уже вставленный чат. Гонку username решает UNIQUE, а не предварительный SELECT. READ COMMITTED достаточен для нынешних операций: изменения/удаления членства нет. История читается с основной БД без кэша, поэтому подтверждённое сообщение видно следующему подходящему чтению. Cursor хранит (created_at,id) и scope; несколько страниц не составляют общий snapshot. Откат часов может поместить запись до уже пройденной границы.
PostgreSQL: fsync=on, synchronous_commit=on, full_page_writes=on и named volume. COMMIT подтверждает фиксацию в настроенной модели durability, но не отказоустойчивость единственного диска/host.
## Пароли, сессии и роль Valkey
Пароли обрабатываются Argon2id, профиль RFC_9106_LOW_MEMORY, с отдельной случайной солью. UTF-8 не усекается: 12–128 code points, двоеточие допустимо. Максимум два одновременных KDF ограничивают расход памяти; при исчерпании бюджета ожидания — 503. Для неизвестного имени проверяется dummy hash. Неверный пароль и неизвестное имя получают одинаковую ошибку 401.
Basic применяется только на POST /api/v1/auth/sessions без body. Выдаётся opaque token из 32 случайных байтов, в БД — только его SHA-256, user_id и абсолютный expires_at по часам БД. Быстрый digest здесь нужен для поиска случайного секрета, а не вместо password KDF. В User нет пароля/hash. Защищённые endpoint принимают Bearer, X-User-Id игнорируется. Каждый 401 имеет нужный WWW-Authenticate; logout — 204 без тела, повтор — 401.
SESSION_TTL_SECONDS по умолчанию 3600. В тесте через переменную окружения задаётся 2 с, затем приложение пересоздаётся с обычным TTL; прежняя сессия всё равно истекает через исходные 2 с. Рестарт не продлевает expiry.
Каждый запрос проверяет наличие/expiry сессии в PostgreSQL. Valkey с TTL позволяет пропустить повторный SELECT неизменяемой User. На miss карточка читается из БД, на hit этот SELECT не нужен. Ключ кэша не подтверждает действительность токена. Logout сначала фиксируется в БД, затем удаляет ключ; даже специально возвращённый stale key не оживляет сессию.
Valkey: 64 MiB, allkeys-lru, persistence выключен, поскольку это не источник истины. Flush/eviction/restart приводят к cache miss; данные и сессии остаются в PostgreSQL. Кэш обходится при отказе, таймауты клиента 0,2 с, retry выключены. При отказе PostgreSQL даже cache hit не даёт доступ. Readiness проверяет критичную БД, liveness — жизнь процесса.
## Проверки и доказательства
| Критерий | Наблюдение | Доказательство |
| --- | --- | --- |
| Контракт | make check и validate прошли; исходные tests/contracts не изменены | evidence/contract-checks.txt |
| Публичный сценарий | make test: PASS lab2 | evidence/smoke.txt |
| Persistence | Прежний токен читает прежнее сообщение после полного restart | evidence/persistence.txt |
| Реальные процессы | StartedAt и PID API/PostgreSQL/Valkey изменились | evidence/lifecycle.json |
| Миграции | Применение с нуля, повтор без дублей, отказ при изменённом checksum | student-tests, lifecycle.json |
| UNIQUE и rollback | 10 HTTP-регистраций: один 201 и девять 409; ошибочный чат не оставляет строк | evidence/student-tests.txt |
| Строгий API/ACL | Неверный JSON/тип/Unicode/cursor; чужой чат; Basic вместо Bearer; подмена X-User-Id | student-tests/test_api.py |
| Конкурентные записи | 10 клиентов, 100 сообщений, точное равенство множеств ID | evidence/lifecycle.json |
| Кэш и отзыв | Hit избегает User SELECT; flush восстанавливает ключ; stale key не обходит logout | student-tests/test_api.py |
| Expiry | SESSION_TTL_SECONDS=2; пересоздание приложения не продлевает сессию | evidence/student-tests.txt |
| Отказы | Valkey: 200 действующей сессии, 401 анониму; БД: 503, liveness 200 | evidence/lifecycle.json |
| Индекс и трек 5 | Два индекса, три повтора, 100 000 сообщений; запись и backup/restore | evidence/query-plan.json |
| Non-root и логи | UID 10001; canary, пароли и токены отсутствуют в проверенных API logs | evidence/lifecycle.json |
**36 собственных случаев** используют настоящие PostgreSQL и Valkey, а не SQLite/mock SQL. TestClient дополнен публичным TCP smoke и реальными контейнерными отказами. Есть предупреждение библиотеки TestClient об устаревающем HTTP-клиенте; проверки выполняются. Ruff прошёл. Пути рабочей машины в доказательствах заменены на `<project>`; секреты не сохраняются.
При отключённом Valkey корректный ответ получен за **0,254 с**. При остановленном PostgreSQL запрос с закэшированной сессией получил 503 за **1,006 с**, readiness — за **1,008 с**. После восстановления все 100 подтверждённых сообщений остались прежними. Это измерения конкретного запуска, не обещанный SLA.
## Исследование: план запроса и восстановление
Гипотеза: индекс только по chat_id вынуждает читать много строк и сортировать историю, а (chat_id,created_at,id) позволяет остановиться после небольшой keyset-страницы. У дополнительного индекса есть цена размера и записи.
Методика: 100 000 сообщений в 10 чатах с размерами 90 000 / 5 000 / 2 000 / 1 000 / 500 / 500 / 250 / 250 / 250 / 250. Перед каждым из шести прогонов история пересоздаётся с теми же ключами/текстом, установлен ровно один сравниваемый вторичный индекс и выполнен VACUUM ANALYZE. Общие PK/FK сохраняются. Порядок: AB, BA, AB.
На прогон: EXPLAIN (ANALYZE, BUFFERS) для большого чата с первой/глубокой страницей и малого чата с глубокой; 20 прогревочных и 200 измеряемых SELECT, конкуренция 1, closed-loop, страница до 51 строки. 75% запросов — большой чат, 25% — малый; чередуются начало и позиция около 90%. Затем 20 транзакций по 100 новых сообщений: время с COMMIT, WAL delta и размер индекса. После записи — 102 000 сообщений.
PostgreSQL: 1 CPU/512 MiB, swap сверх лимита запрещён. API: 1 CPU/512 MiB; Valkey: 0,5 CPU/128 MiB. Генератор SQL на Mac через localhost, Docker VM: 18 vCPU, около 7,75 GiB RAM. Raw durations и CPU/RAM samples сохранены. Вся серия заняла около 24 с с подготовкой/restore. Это короткий **SQL-микроэксперимент, не HTTP API latency/RPS**.
| Медиана трёх повторов | Только chat_id | chat_id,created_at,id |
| --- | ---: | ---: |
| SELECT в секунду | 164,77 | 2092,27 |
| p95 SELECT, мс | 8,877 | 0,671 |
| Записанных строк/с, batch=100 | 26 621,51 | 26 986,71 |
| Размер вторичного индекса после записи | 688 128 B | 6 127 616 B |
В одном плане глубокой страницы большого чата до изменения — 2703 shared hit blocks и Sort, после — Index Scan и 5 shared hit blocks. Деревья и Execution Time есть в JSON; seqscan принудительно не отключался.
Стоимость записи измерена, но короткая серия не доказывает её улучшения: диапазоны перекрываются, есть шум клиента/VM и batch COMMIT. Явная цена — вторичный индекс примерно в 8,9 раза больше. Медиана трёх p95 не равна общему p95. CPU/RAM — редкие выборки, для быстрых прогонов недостаточные для оценки пиков. Кэш cluster не сбрасывался; прогрев и чередование уменьшают, но не устраняют дрейф. Производительность локального SQL-клиента также ограничивает результат.
### Backup → новая БД → сверка
После последнего прогона создаётся сессия и custom-format pg_dump. Pg_restore восстанавливает архив **в новую пустую БД**. Совпали количества: 2 пользователя, 10 чатов, 20 членств, **102 000 сообщений**, 1 сессия, 1 миграция. Дополнительно совпали восемь выбранных сообщений и SHA-256 полного упорядоченного содержимого всех сообщений.
Архив: 2 723 619 B. Dump — **0,368 с**, создание новой БД и restore — **0,510 с**. Это время локальной логической операции, не полный RTO сервиса: переключение API, перенос с другого host и production-размеры не измерялись. Raw dump содержит password hashes/сессионные digest и удаляется с временным каталогом; в Git остаются только результаты сверки.
После backup в исходной БД специально подтверждено ещё одно сообщение. В восстановленной БД его нет: snapshot не включает более поздние COMMIT. Для них нужны WAL/PITR или новый backup. Так показана граница потери данных; нулевой RPO не заявляется. Копия на том же host не защищает от его потери. Процедура: [research/query_plan.py](research/query_plan.py).
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Один PostgreSQL и host — SPOF; volume не заменяет внешний backup. Valkey можно потерять, PostgreSQL — нет. Нет реплик БД, PITR, TLS и rate limiting по клиенту. Просроченные сессии не дают доступа, но их строки пока сохраняются; уборка — отдельная эксплуатационная задача. Учебная роль БД не является production-моделью минимальных привилегий. Basic/Bearer по HTTP допустимы только на локальном изолированном стенде.
В lab3 отдельно добавляются балансировщик, API-реплики, X-Instance-Id и атомарная идемпотентность отправки. Это не заявляется реализованным в lab2. Secrets, volumes и история .git между работами не переносятся.
## Источники
Нормативные: README.md, COURSE.md, CONTRIBUTING.md и contracts/ этой лабораторной. Предыдущая реализация — собственная lab1; публичные tests не изменялись. Используются перечисленные библиотеки из uv.lock.
- [Psycopg: connection pools](https://www.psycopg.org/psycopg3/docs/advanced/pool.html)
- [PostgreSQL: multicolumn indexes](https://www.postgresql.org/docs/18/indexes-multicolumn.html)
- [PostgreSQL: EXPLAIN](https://www.postgresql.org/docs/18/using-explain.html)
- [PostgreSQL: SQL dump](https://www.postgresql.org/docs/18/backup-dump.html)
- [Argon2-cffi: password hashing API](https://argon2-cffi.readthedocs.io/en/stable/api.html)
- [Basic authentication, RFC 7617](https://www.rfc-editor.org/rfc/rfc7617)
+34
View File
@@ -0,0 +1,34 @@
# Схема и границы транзакций — до реализации запросов
Источник истины — PostgreSQL. Все подтверждения записи выдаются после успешного
COMMIT. Пользователи, чаты, участники, сообщения и сессии находятся в одной БД.
Valkey хранит только восстанавливаемую копию неизменяемой карточки пользователя
для активной сессии; наличие ключа никогда не заменяет проверку сессии в БД.
| Таблица | Ограничения | Индексы и назначение |
| --- | --- | --- |
| users | UUID PK, UNIQUE username, hash Argon2id, ограничения длины | уникальный username для регистрации/входа |
| chats | UUID PK, title, created_at UTC | PK для метаданных |
| chat_members | FK chat/user, PK(chat_id,user_id), UNIQUE(chat_id,position) | (user_id,chat_id) для списка доступных чатов |
| messages | UUID PK, FK chat, составной FK(chat_id,sender_id) в участников | (chat_id,created_at,id) для keyset-страницы |
| sessions | SHA-256 случайного токена PK, FK user, expires_at | expires_at для будущей очистки |
Одна операция repository — одна транзакция READ COMMITTED. Создание чата и всех
его участников выполняется целиком: ошибка FK откатывает уже вставленный чат.
Уникальность username обеспечивается UNIQUE, а не предварительным SELECT.
Отправка сообщения фиксируется до HTTP 201; чтение идёт на основной PostgreSQL,
кэша истории нет. Несколько HTTP-страниц не образуют общий snapshot.
Сессия создаётся после проверки пароля. Хранятся только digest токена и абсолютный
expires_at, вычисленный часами БД. На каждом защищённом запросе БД проверяет expiry
и отзыв. Logout удаляет сессию транзакционно, затем пытается удалить кэш. Даже при
ошибке Valkey старый ключ не даёт доступа. После flush/restart кэш заполняется заново;
после отказа PostgreSQL запрос отклоняется с 503, без доверия к кэшу.
Миграции имеют номера и SHA-256 содержимого. Их применение и запись версии идут
в одной транзакции под advisory lock. Повторное применение ничего не дублирует;
изменение уже применённого файла считается ошибкой.
Durability: fsync=on, synchronous_commit=on, full_page_writes=on; постоянный named
volume. Это сохранность при проверяемом перезапуске, а не HA или защита от потери
диска/хоста. Backup и проверка восстановления выполняются отдельно.
+6
View File
@@ -0,0 +1,6 @@
# Optional host access for local integration tests. No host-wide service discovery.
services:
postgres:
ports: ["127.0.0.1:55432:5432"]
valkey:
ports: ["127.0.0.1:56379:6379"]
+86
View File
@@ -0,0 +1,86 @@
name: mtusi-lab2
x-api: &api
image: mtusi-messenger:lab2
build:
context: .
args:
VCS_REF: ${VCS_REF:-uncommitted}
init: false
user: "10001:10001"
read_only: true
tmpfs:
- /tmp:rw,noexec,nosuid,size=16m
cap_drop: [ALL]
security_opt: [no-new-privileges:true]
pids_limit: 96
cpus: 1
mem_limit: 512m
memswap_limit: 512m
secrets: [database_url, cache_url]
environment:
APP_HOST: 0.0.0.0
APP_PORT: 8080
APP_ENV: lab2
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
DATABASE_POOL_SIZE: 8
DATABASE_URL_FILE: /run/secrets/database_url
CACHE_URL_FILE: /run/secrets/cache_url
networks: [backend]
services:
postgres:
image: postgres:18.3
environment:
POSTGRES_USER: messenger
POSTGRES_DB: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
secrets: [postgres_password]
volumes: [postgres_data:/var/lib/postgresql]
command: [postgres, -c, fsync=on, -c, synchronous_commit=on, -c, full_page_writes=on]
healthcheck:
test: [CMD-SHELL, "pg_isready -U messenger -d messenger"]
interval: 2s
timeout: 2s
retries: 30
cpus: 1
mem_limit: 512m
memswap_limit: 512m
networks: [backend]
valkey:
image: valkey/valkey:8.1.3-alpine
command: [valkey-server, --save, "", --appendonly, "no", --maxmemory, 64mb,
--maxmemory-policy, allkeys-lru]
healthcheck:
test: [CMD, valkey-cli, ping]
interval: 2s
timeout: 1s
retries: 20
cpus: 0.5
mem_limit: 128m
memswap_limit: 128m
networks: [backend]
migrate:
<<: *api
command: [python, -m, messenger.migrate]
healthcheck: {disable: true}
depends_on:
postgres: {condition: service_healthy}
api:
<<: *api
ports: ["127.0.0.1:${PUBLIC_PORT:-8082}:8080"]
depends_on:
migrate: {condition: service_completed_successfully}
valkey: {condition: service_healthy}
networks:
backend: {}
volumes:
postgres_data:
secrets:
postgres_password:
file: ./secrets/postgres_password
database_url:
file: ./secrets/database_url
cache_url:
file: ./secrets/cache_url
+4
View File
@@ -0,0 +1,4 @@
.venv/bin/python scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
.venv/bin/python scripts/validate_openapi.py
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
+22
View File
@@ -0,0 +1,22 @@
{
"docker": "29.8.1",
"vm_cpus": 18,
"vm_memory_bytes": 8317267968,
"cpu_model": "Apple M5 Pro",
"host_memory_bytes": 25769803776,
"runtime_source_matches": true,
"python_source_sha256": {
"auth.py": "6bebcd8d1d3ca4c2c6e8b0e5793ae13d8996cac3709b5b845d814b51a5e1a3c3",
"service.py": "d395dac6864c6ee6df6e1f30e3fa24a00cb29bdadfbdd1bdbc2d34c791e2a2c4",
"domain.py": "e970ab21fb0ada53dce3520563ef891c28710957dabf6bcff063449516ebb425",
"cache.py": "17756fa84a2c40fd4d1baf9602a7b755ca5998bc241f0657db3505b04623321d",
"__init__.py": "f798dc149d6bef46d697dccdaf6be9c8d08654f18161e42c99f548c30074f4ae",
"schemas.py": "e0254f10b3f64f38525f22824548f935723a1ea895ee8cf7c2be0b5d3b80c5b1",
"settings.py": "c6c9f8dec27b94c76f7e9e4c2be2b1b4b053521dea2edd5eacb312b766722e72",
"app.py": "ee214a538b2dfe5083f07400dfe73423877b9d2019213fc91f00a57017368175",
"repository.py": "0232b73d77d5ab551090f14eb5709cac422aa1a97f32a75241bca369f8ddf21c",
"migrate.py": "f073c080e13635a01482539dbb474b9b4f49bbf5ff66f483dbda4fbe1d1eb57f",
"__main__.py": "486cd5bbb3f1a814de74357e938968d219070e845cf178761a7a23e87d003ea4",
"cursor.py": "a2208cba232ae0f67c4430d3e90c3962129c8fb3987ea853c624cdd2c73d7a1f"
}
}
+79
View File
@@ -0,0 +1,79 @@
{
"at": "2026-10-17T14:34:34.316178+00:00",
"before_restart": {
"api": {
"id": "b608ad8e989d9dbdf1cd57d9eb72c4a51641dd4a4a8a57664413e696802c7eca",
"started_at": "2026-10-17T14:31:11.185486549Z",
"pid": 11744,
"image": "sha256:320b3b425ce160820a3cda448d2a080f00abad7e84eb47dff68a4ca1e05748fb",
"memory_limit": 536870912,
"nano_cpus": 1000000000
},
"postgres": {
"id": "3e23e8c2f67821a47170c4eefdca1f1cb9924943d66e8e00e5f6f9bb68003a47",
"started_at": "2026-10-17T14:31:08.021070173Z",
"pid": 11535,
"image": "sha256:7e32e9833a6fb1c92c32552794cb6ed569d51b445a54907d35fc112ef39684db",
"memory_limit": 536870912,
"nano_cpus": 1000000000
},
"valkey": {
"id": "c3a46b5456d9fe3af9c4cab15ef5524dcd221b756d8b66a446b9828796644645",
"started_at": "2026-10-17T14:31:07.934909464Z",
"pid": 11460,
"image": "sha256:d827e7f7552cdee40cc7482dbae9da020f42bc47669af6f71182a4ef76a22773",
"memory_limit": 134217728,
"nano_cpus": 500000000
}
},
"after_restart": {
"api": {
"id": "b608ad8e989d9dbdf1cd57d9eb72c4a51641dd4a4a8a57664413e696802c7eca",
"started_at": "2026-10-17T14:34:31.776726503Z",
"pid": 18302,
"image": "sha256:320b3b425ce160820a3cda448d2a080f00abad7e84eb47dff68a4ca1e05748fb",
"memory_limit": 536870912,
"nano_cpus": 1000000000
},
"postgres": {
"id": "3e23e8c2f67821a47170c4eefdca1f1cb9924943d66e8e00e5f6f9bb68003a47",
"started_at": "2026-10-17T14:34:31.623388544Z",
"pid": 18098,
"image": "sha256:7e32e9833a6fb1c92c32552794cb6ed569d51b445a54907d35fc112ef39684db",
"memory_limit": 536870912,
"nano_cpus": 1000000000
},
"valkey": {
"id": "c3a46b5456d9fe3af9c4cab15ef5524dcd221b756d8b66a446b9828796644645",
"started_at": "2026-10-17T14:34:31.662652628Z",
"pid": 18166,
"image": "sha256:d827e7f7552cdee40cc7482dbae9da020f42bc47669af6f71182a4ef76a22773",
"memory_limit": 134217728,
"nano_cpus": 500000000
}
},
"concurrent_clients": 10,
"unique_messages": 100,
"faults": [
{
"dependency": "valkey",
"valid_session_status": 200,
"anonymous_status": 401,
"revoked_status": 401,
"fallback_seconds": 0.25391316600007485
},
{
"dependency": "postgres",
"liveness": 200,
"readiness": 503,
"cached_session_status": 503,
"anonymous_status": 401,
"request_seconds": 1.0061383330003082,
"readiness_seconds": 1.0079494999999952
}
],
"secrets_absent_from_api_logs": true,
"migration_repeat_ok": true,
"api_uid": 10001,
"history_preserved": true
}
+1
View File
@@ -0,0 +1 @@
PASS: full restart, concurrent writes, dependency failures, cache flush and revocation
+2
View File
@@ -0,0 +1,2 @@
uv run --locked ruff check src student-tests scripts/bootstrap.py scripts/verify_lifecycle.py research
All checks passed!
+3
View File
@@ -0,0 +1,3 @@
python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://127.0.0.1:8082"
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
File diff suppressed because it is too large Load Diff
+8
View File
@@ -0,0 +1,8 @@
Applied migration 001_initial
Completed single repeat 1
Completed composite repeat 1
Completed composite repeat 2
Completed single repeat 2
Completed single repeat 3
Completed composite repeat 3
PASS: index comparison and backup restore verified
+2
View File
@@ -0,0 +1,2 @@
python3 tests/smoke.py --base-url "http://127.0.0.1:8082"
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
+2
View File
@@ -0,0 +1,2 @@
.................................... [100%]
36 passed, 1 warning in 6.10s
+37
View File
@@ -0,0 +1,37 @@
CREATE TABLE users (
id uuid PRIMARY KEY,
username varchar(32) COLLATE "C" NOT NULL UNIQUE CHECK (username ~ '^[a-z0-9_]{3,32}$'),
display_name text NOT NULL CHECK (char_length(display_name) BETWEEN 1 AND 100),
password_hash text NOT NULL,
created_at timestamptz NOT NULL DEFAULT clock_timestamp()
);
CREATE TABLE chats (
id uuid PRIMARY KEY,
title text NOT NULL CHECK (char_length(title) BETWEEN 1 AND 100),
created_at timestamptz NOT NULL DEFAULT clock_timestamp()
);
CREATE TABLE chat_members (
chat_id uuid NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
user_id uuid NOT NULL REFERENCES users(id),
position smallint NOT NULL CHECK (position BETWEEN 0 AND 99),
PRIMARY KEY (chat_id,user_id),
UNIQUE (chat_id,position)
);
CREATE INDEX chat_members_by_user ON chat_members (user_id,chat_id);
CREATE TABLE messages (
id uuid PRIMARY KEY,
chat_id uuid NOT NULL REFERENCES chats(id),
sender_id uuid NOT NULL REFERENCES users(id),
text text NOT NULL CHECK (char_length(text) BETWEEN 1 AND 4000),
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
FOREIGN KEY (chat_id,sender_id) REFERENCES chat_members(chat_id,user_id)
);
CREATE INDEX messages_history ON messages (chat_id,created_at,id);
CREATE TABLE sessions (
token_hash bytea PRIMARY KEY CHECK (octet_length(token_hash)=32),
user_id uuid NOT NULL REFERENCES users(id),
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
expires_at timestamptz NOT NULL,
CHECK (expires_at > created_at)
);
CREATE INDEX sessions_expiry ON sessions (expires_at);
+42
View File
@@ -0,0 +1,42 @@
[project]
name = "mtusi-messenger"
version = "0.2.0"
description = "MTUSI lab 2: durable PostgreSQL messenger and expiring sessions"
requires-python = ">=3.14,<3.15"
dependencies = [
"argon2-cffi==25.1.0",
"fastapi==0.143.3",
"psycopg[binary,pool]==3.3.6",
"pydantic==2.14.1",
"redis==8.1.0",
"uvicorn==0.54.0",
]
[build-system]
requires = ["hatchling==1.27.0"]
build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
packages = ["src/messenger"]
[dependency-groups]
dev = [
"httpx==0.28.1",
"openapi-spec-validator==0.7.2",
"pytest==9.1.1",
"ruff==0.17.1",
]
research = ["matplotlib==3.11.2"]
[tool.pytest.ini_options]
testpaths = ["student-tests"]
addopts = "-ra --tb=short"
[tool.ruff]
target-version = "py314"
line-length = 100
[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP"]
[tool.ruff.per-file-target-version]
+371
View File
@@ -0,0 +1,371 @@
#!/usr/bin/env python3
"""Isolated SQL experiment and logical restore; never resets the application DB."""
import argparse
import hashlib
import json
import platform
import statistics
import subprocess
import tempfile
import threading
import time
from datetime import UTC, datetime, timedelta
from pathlib import Path
from uuid import UUID, uuid4
import psycopg
from argon2 import PasswordHasher
from psycopg import sql
from psycopg.conninfo import make_conninfo
from messenger.migrate import migrate
ROOT = Path(__file__).resolve().parents[1]
SIZES = [90_000, 5_000, 2_000, 1_000, 500, 500, 250, 250, 250, 250]
CHAT_IDS = [UUID(int=100 + i) for i in range(10)]
USER_IDS = [UUID(int=1), UUID(int=2)]
START = datetime(2026, 10, 17, tzinfo=UTC)
QUERY = (
"SELECT id,chat_id,sender_id,text,created_at FROM messages WHERE chat_id=%s "
"AND (created_at,id) > (%s,%s) ORDER BY created_at,id LIMIT 51"
)
def docker(*args, **kwargs):
return subprocess.run(
["docker", "compose", *args], cwd=ROOT, check=True, capture_output=True, **kwargs
)
def percentiles(values):
ordered = sorted(values)
def p(fraction):
index = (len(ordered) - 1) * fraction
lower = int(index)
return ordered[lower] + (ordered[min(lower + 1, len(ordered) - 1)] - ordered[lower]) * (
index - lower
)
return {"p50_ms": p(0.5), "p95_ms": p(0.95), "p99_ms": p(0.99)}
def initialize(conn):
encoded = PasswordHasher().hash("Synthetic-research-password-only")
for i, user_id in enumerate(USER_IDS):
conn.execute(
"INSERT INTO users (id,username,display_name,password_hash) VALUES (%s,%s,%s,%s)",
(user_id, "research_" + str(i), "Research", encoded),
)
for chat_id in CHAT_IDS:
conn.execute("INSERT INTO chats (id,title) VALUES (%s,'Synthetic history')", (chat_id,))
for position, user_id in enumerate(USER_IDS):
conn.execute(
"INSERT INTO chat_members (chat_id,user_id,position) VALUES (%s,%s,%s)",
(chat_id, user_id, position),
)
def seed(conn, variant):
conn.execute("TRUNCATE messages")
conn.execute("DROP INDEX IF EXISTS messages_history")
conn.execute("DROP INDEX IF EXISTS messages_by_chat")
if variant == "single":
conn.execute("CREATE INDEX messages_by_chat ON messages (chat_id)")
else:
conn.execute("CREATE INDEX messages_history ON messages (chat_id,created_at,id)")
with conn.transaction():
for chat_id, size in zip(CHAT_IDS, SIZES, strict=True):
conn.execute(
"INSERT INTO messages (id,chat_id,sender_id,text,created_at) "
"SELECT md5(%s || ':' || g::text)::uuid,%s,%s,repeat('m',128),"
"%s::timestamptz + g * interval '1 microsecond' FROM generate_series(1,%s) g",
(str(chat_id), chat_id, USER_IDS[0], START, size),
)
conn.execute("VACUUM (ANALYZE) messages")
def parameters(i):
chat_index = 8 if i % 4 == 0 else 0
boundary = int(SIZES[chat_index] * 0.9) if i % 2 == 0 else 0
return CHAT_IDS[chat_index], START + timedelta(microseconds=boundary), UUID(int=0)
def resource_samples(stop, samples, container):
while not stop.is_set():
try:
result = subprocess.run(
["docker", "stats", "--no-stream", "--format", "{{json .}}", container],
capture_output=True,
text=True,
timeout=5,
check=True,
)
raw = json.loads(result.stdout)
samples.append(
{
"at": datetime.now(UTC).isoformat(),
"cpu": raw["CPUPerc"],
"memory": raw["MemUsage"],
}
)
except OSError, subprocess.SubprocessError, ValueError, KeyError:
samples.append({"error": "resource_sample_unavailable"})
stop.wait(0.25)
def measure(conn, variant, repeat, queries, batches, container):
seed(conn, variant)
plans = {}
for name, params in [
("large_first", parameters(1)),
("large_deep", parameters(2)),
("small_deep", parameters(0)),
]:
plans[name] = conn.execute(
"EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) " + QUERY, params
).fetchone()[0]
for i in range(20):
conn.execute(QUERY, parameters(i)).fetchall()
stop, samples = threading.Event(), []
sampler = threading.Thread(
target=resource_samples, args=(stop, samples, container), daemon=True
)
sampler.start()
try:
latency = []
started = time.perf_counter()
for i in range(queries):
before = time.perf_counter()
rows = conn.execute(QUERY, parameters(i)).fetchall()
latency.append((time.perf_counter() - before) * 1000)
assert len(rows) > 0
elapsed = time.perf_counter() - started
reads = {
"successful_queries": queries,
"errors": 0,
"elapsed_seconds": elapsed,
"queries_per_second": queries / elapsed,
**percentiles(latency),
"raw_latency_ms": latency,
}
before_wal = conn.execute("SELECT pg_current_wal_lsn()").fetchone()[0]
latency = []
started = time.perf_counter()
for batch in range(batches):
records = [
(uuid4(), CHAT_IDS[0], USER_IDS[0], f"write:{batch}:{i}") for i in range(100)
]
before = time.perf_counter()
with conn.transaction(), conn.cursor() as cur:
cur.executemany(
"INSERT INTO messages (id,chat_id,sender_id,text) VALUES (%s,%s,%s,%s)", records
)
latency.append((time.perf_counter() - before) * 1000)
elapsed = time.perf_counter() - started
wal = conn.execute(
"SELECT pg_wal_lsn_diff(pg_current_wal_lsn(),%s::pg_lsn)", (before_wal,)
).fetchone()[0]
writes = {
"committed_batches": batches,
"rows_per_batch": 100,
"errors": 0,
"elapsed_seconds": elapsed,
"rows_per_second": batches * 100 / elapsed,
"wal_bytes_cluster_delta": int(wal),
**percentiles(latency),
"raw_batch_latency_ms": latency,
}
finally:
stop.set()
sampler.join(timeout=6)
name = "messages_by_chat" if variant == "single" else "messages_history"
index_bytes = conn.execute("SELECT pg_relation_size(%s::regclass)", (name,)).fetchone()[0]
return {
"index": variant,
"repeat": repeat,
"initial_messages": sum(SIZES),
"plans": plans,
"reads": reads,
"writes": writes,
"index_bytes_after_writes": index_bytes,
"postgres_resource_samples": samples,
}
def fingerprint(conn):
counts = {
table: conn.execute(
sql.SQL("SELECT count(*) FROM {}").format(sql.Identifier(table))
).fetchone()[0]
for table in ("users", "chats", "chat_members", "messages", "sessions", "schema_migrations")
}
digest = hashlib.sha256()
with conn.transaction(), conn.cursor(name="fingerprint") as cur:
cur.execute("SELECT id,chat_id,sender_id,text,created_at FROM messages ORDER BY id")
for row in cur:
digest.update((json.dumps(row, default=str, ensure_ascii=False) + "\n").encode())
selected = conn.execute(
"SELECT id,chat_id,sender_id,text,created_at FROM messages ORDER BY id LIMIT 8"
).fetchall()
return {
"counts": counts,
"all_messages_sha256": digest.hexdigest(),
"selected_messages": [[str(value) for value in row] for row in selected],
}
def restore_check(conn, admin, source, restored, config):
token_hash = hashlib.sha256(uuid4().bytes + uuid4().bytes).digest()
conn.execute(
"INSERT INTO sessions (token_hash,user_id,expires_at) "
"VALUES (%s,%s,clock_timestamp()+interval '1 hour')",
(token_hash, USER_IDS[0]),
)
before = fingerprint(conn)
with tempfile.TemporaryDirectory(prefix="lab2-backup-") as temporary:
archive = Path(temporary) / "snapshot.dump"
started = time.perf_counter()
dump = docker(
"exec",
"-T",
"postgres",
"pg_dump",
"-U",
"messenger",
"-d",
source,
"--format=custom",
"--no-owner",
"--no-acl",
)
archive.write_bytes(dump.stdout)
dump_seconds = time.perf_counter() - started
# Deliberately committed AFTER the backup; logical restore must not contain it.
late_id = uuid4()
conn.execute(
"INSERT INTO messages (id,chat_id,sender_id,text) VALUES (%s,%s,%s,'after snapshot')",
(late_id, CHAT_IDS[0], USER_IDS[0]),
)
started = time.perf_counter()
admin.execute(sql.SQL("CREATE DATABASE {}").format(sql.Identifier(restored)))
docker(
"exec",
"-T",
"postgres",
"pg_restore",
"-U",
"messenger",
"-d",
restored,
"--no-owner",
"--no-acl",
input=archive.read_bytes(),
)
restore_seconds = time.perf_counter() - started
with psycopg.connect(make_conninfo(config, dbname=restored), autocommit=True) as target:
after = fingerprint(target)
assert before == after, "Restored snapshot differs"
assert (
target.execute("SELECT count(*) FROM messages WHERE id=%s", (late_id,)).fetchone()[
0
]
== 0
)
return {
"snapshot": before,
"restored": after,
"equal": before == after,
"dump_seconds": dump_seconds,
"restore_database_seconds": restore_seconds,
"archive_bytes": archive.stat().st_size,
"archive_sha256": hashlib.sha256(archive.read_bytes()).hexdigest(),
"post_backup_commits_absent_after_restore": 1,
"archive_retained": False,
}
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--output", type=Path, default=ROOT / "evidence/query-plan.json")
parser.add_argument("--queries", type=int, default=200)
parser.add_argument("--write-batches", type=int, default=20)
args = parser.parse_args()
if args.output.exists():
raise SystemExit("Choose a new output path; existing evidence will not be overwritten")
password = (ROOT / "secrets/postgres_password").read_text().strip()
config = make_conninfo(
host="127.0.0.1",
port=55432,
dbname="messenger",
user="messenger",
password=password,
options="-c timezone=UTC",
)
source, restored = "research_" + uuid4().hex, "restored_" + uuid4().hex
container = docker("ps", "-q", "postgres", text=True).stdout.strip()
result = {
"started_at": datetime.now(UTC).isoformat(),
"scope": "SQL, not HTTP latency",
"initial_chat_sizes": SIZES,
"concurrency": 1,
"warmup_queries_per_trial": 20,
"client_platform": platform.machine(),
"trials": [],
}
with psycopg.connect(config, autocommit=True) as admin:
admin.execute(sql.SQL("CREATE DATABASE {}").format(sql.Identifier(source)))
try:
dsn = make_conninfo(config, dbname=source)
migrate(dsn, ROOT / "migrations")
with psycopg.connect(dsn, autocommit=True) as conn:
initialize(conn)
result["postgres_version"] = conn.execute("SELECT version()").fetchone()[0]
result["durability"] = {
name: conn.execute(sql.SQL("SHOW {}").format(sql.Identifier(name))).fetchone()[
0
]
for name in ("fsync", "synchronous_commit", "full_page_writes")
}
for repeat in range(3):
for variant in (
("single", "composite") if repeat % 2 == 0 else ("composite", "single")
):
trial = measure(
conn, variant, repeat + 1, args.queries, args.write_batches, container
)
result["trials"].append(trial)
print("Completed " + variant + " repeat " + str(repeat + 1), flush=True)
result["backup_restore"] = restore_check(conn, admin, source, restored, config)
result["finished_at"] = datetime.now(UTC).isoformat()
result["median_by_index"] = {
variant: {
"read_queries_per_second": statistics.median(
t["reads"]["queries_per_second"]
for t in result["trials"]
if t["index"] == variant
),
"read_p95_ms": statistics.median(
t["reads"]["p95_ms"] for t in result["trials"] if t["index"] == variant
),
"write_rows_per_second": statistics.median(
t["writes"]["rows_per_second"]
for t in result["trials"]
if t["index"] == variant
),
}
for variant in ("single", "composite")
}
args.output.parent.mkdir(parents=True, exist_ok=True)
args.output.write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n")
print("PASS: index comparison and backup restore verified")
finally:
for name in (restored, source):
admin.execute(
sql.SQL("DROP DATABASE IF EXISTS {} WITH (FORCE)").format(sql.Identifier(name))
)
if __name__ == "__main__":
main()
+29
View File
@@ -0,0 +1,29 @@
#!/usr/bin/env python3
"""Create local synthetic credentials once, without printing their values."""
import os
import secrets
from pathlib import Path
root = Path(__file__).resolve().parents[1]
directory = root / "secrets"
directory.mkdir(mode=0o700, exist_ok=True)
password_file = directory / "postgres_password"
if not password_file.exists():
password_file.write_text(secrets.token_urlsafe(32) + "\n")
password = password_file.read_text().strip()
for name, value in {
"database_url": f"postgresql://messenger:{password}@postgres:5432/messenger",
"cache_url": "redis://valkey:6379/0",
}.items():
path = directory / name
if not path.exists():
path.write_text(value + "\n")
# Compose bind-mount secrets must be readable by the non-root container process.
# The parent directory remains 0700 on the host.
for name in ("postgres_password", "database_url", "cache_url"):
os.chmod(directory / name, 0o644)
env = root / ".env"
if not env.exists():
env.write_text((root / ".env.example").read_text())
print("Local secret files and environment are ready; existing values preserved.")
+5
View File
@@ -0,0 +1,5 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
# All running application/state services; no migration, down -v, flush or seed.
docker compose --env-file .env restart --timeout 10 api postgres valkey
+188
View File
@@ -0,0 +1,188 @@
#!/usr/bin/env python3
"""Explicit, scoped Docker failure checks. Bearer tokens stay in memory only."""
import argparse
import json
import os
import subprocess
import sys
import time
from concurrent.futures import ThreadPoolExecutor
from datetime import UTC, datetime
from pathlib import Path
from uuid import uuid4
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "tests"))
from client import Client, check # noqa: E402
def compose(*args):
return subprocess.run(
["docker", "compose", "--env-file", ".env", *args],
cwd=ROOT,
capture_output=True,
text=True,
timeout=60,
check=True,
).stdout
def states():
values = {}
for service in ("api", "postgres", "valkey"):
container = compose("ps", "-q", service).strip()
value = subprocess.run(
[
"docker",
"inspect",
"--format",
'{"id":{{json .Id}},"started_at":{{json .State.StartedAt}},'
'"pid":{{.State.Pid}},"image":{{json .Image}},'
'"memory_limit":{{.HostConfig.Memory}},"nano_cpus":{{.HostConfig.NanoCpus}}}',
container,
],
capture_output=True,
text=True,
check=True,
)
values[service] = json.loads(value.stdout)
return values
def wait_ready(client):
deadline = time.monotonic() + 60
while True:
try:
client.call("GET", "/health/ready", schema="Health")
return
except AssertionError:
if time.monotonic() >= deadline:
raise
time.sleep(0.3)
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--output", type=Path, default=ROOT / "evidence/lifecycle.json")
parser.add_argument("--base-url", default="http://127.0.0.1:8082")
args = parser.parse_args()
if args.output.exists():
raise SystemExit("Choose a new evidence file")
os.environ["NO_PROXY"] = os.environ["no_proxy"] = "127.0.0.1,localhost"
client = Client(args.base_url, timeout=8)
before = states()
hook = subprocess.run(
[
"make",
"test-persistence",
"ACTION_SCRIPT=scripts/restart.sh",
"BASE_URL=" + args.base_url,
],
cwd=ROOT,
capture_output=True,
text=True,
timeout=150,
check=True,
)
(ROOT / "evidence/persistence.txt").write_text(hook.stdout)
after = states()
for service in before:
check(
before[service]["started_at"] != after[service]["started_at"],
"Persistence hook did not restart " + service,
)
alice, bob, eve, room = client.bootstrap()
path = "/api/v1/chats/" + room["id"] + "/messages"
canary = "PRIVATE_CANARY_" + uuid4().hex
def send(i):
return client.call(
"POST",
path,
201,
actor=alice if i % 2 else bob,
body={"text": canary + ":" + str(i)},
schema="Message",
)["json"]
with ThreadPoolExecutor(max_workers=10) as pool:
sent = list(pool.map(send, range(100)))
page = client.call("GET", path + "?limit=100", actor=bob, schema="MessagePage")["json"]
check(
len(page["items"]) == len({x["id"] for x in page["items"]}) == 100,
"Concurrent sends lost or duplicated messages",
)
check({x["id"] for x in sent} == {x["id"] for x in page["items"]}, "Message set differs")
results = {
"at": datetime.now(UTC).isoformat(),
"before_restart": before,
"after_restart": after,
"concurrent_clients": 10,
"unique_messages": 100,
"faults": [],
}
try:
# Cache loss is harmless; PG decides auth even when a stale key remains.
for _ in range(2):
client.call("GET", "/api/v1/users/me", actor=bob, schema="User")
compose("stop", "--timeout", "10", "valkey")
valid = client.call("GET", "/api/v1/users/me", actor=bob, schema="User")
check(valid["elapsed"] < 3, "Cache fallback exceeded request budget")
client.call("GET", "/api/v1/users/me", 401)
client.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=alice)
client.call("GET", "/api/v1/users/me", 401, actor=alice)
results["faults"].append(
{
"dependency": "valkey",
"valid_session_status": 200,
"anonymous_status": 401,
"revoked_status": 401,
"fallback_seconds": valid["elapsed"],
}
)
compose("start", "valkey")
compose("exec", "-T", "valkey", "valkey-cli", "FLUSHDB")
client.call("GET", "/api/v1/users/me", actor=bob, schema="User")
client.call("GET", "/api/v1/users/me", 401, actor=alice)
compose("stop", "--timeout", "10", "postgres")
client.call("GET", "/health/live", schema="Health")
ready = client.call("GET", "/health/ready", 503)
denied = client.call("GET", "/api/v1/users/me", 503, actor=bob)
check(denied["elapsed"] < 6, "DB failure exceeded request budget")
client.call("GET", "/api/v1/users/me", 401)
results["faults"].append(
{
"dependency": "postgres",
"liveness": 200,
"readiness": 503,
"cached_session_status": 503,
"anonymous_status": 401,
"request_seconds": denied["elapsed"],
"readiness_seconds": ready["elapsed"],
}
)
finally:
compose("start", "postgres", "valkey")
wait_ready(client)
recovered = client.call("GET", path + "?limit=100", actor=bob, schema="MessagePage")["json"]
check(page == recovered, "Confirmed history changed across dependency failures")
client.call("GET", "/api/v1/users/me", 401, actor=alice)
client.call("GET", "/api/v1/users/me", actor=bob, schema="User")
client.call("GET", "/api/v1/chats/" + room["id"], 404, actor=eve)
compose("run", "--rm", "--no-deps", "migrate")
logs = compose("logs", "--no-color", "api")
sensitive = [canary] + [a["token"] for a in (alice, bob, eve)]
sensitive += [a["registration"]["password"] for a in (alice, bob, eve)]
check(not any(value in logs for value in sensitive), "Sensitive content appeared in logs")
results["secrets_absent_from_api_logs"] = True
results["migration_repeat_ok"] = True
results["api_uid"] = int(compose("exec", "-T", "api", "id", "-u").strip())
check(results["api_uid"] == 10001, "API must run non-root")
results["history_preserved"] = True
args.output.write_text(json.dumps(results, ensure_ascii=False, indent=2) + "\n")
print("PASS: full restart, concurrent writes, dependency failures, cache flush and revocation")
if __name__ == "__main__":
main()
+1
View File
@@ -0,0 +1 @@
"""One-process implementation of the lab 1 messenger contract."""
+24
View File
@@ -0,0 +1,24 @@
import logging
import os
import uvicorn
def main():
level = os.getenv("APP_LOG_LEVEL", "INFO").upper()
logging.basicConfig(level=level, format="%(message)s")
uvicorn.run(
"messenger.app:create_app",
factory=True,
host=os.getenv("APP_HOST", "0.0.0.0"),
port=int(os.getenv("APP_PORT", "8080")),
workers=1,
access_log=False,
log_level=level.lower(),
timeout_keep_alive=2,
timeout_graceful_shutdown=5,
)
if __name__ == "__main__":
main()
+259
View File
@@ -0,0 +1,259 @@
"""HTTP adapter. The instructor's OpenAPI, not FastAPI defaults, defines errors."""
import json
import logging
import os
import re
from contextlib import asynccontextmanager
from time import perf_counter
from typing import Annotated
from uuid import uuid4
from fastapi import Depends, FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse, Response
from starlette.exceptions import HTTPException
from starlette.types import ASGIApp, Message, Receive, Scope, Send
from messenger.auth import AuthService, Identity, basic_credentials, bearer_digest, unauthorized
from messenger.cache import SessionCache
from messenger.domain import DomainError, User, invalid
from messenger.repository import PostgresRepository
from messenger.schemas import (
ChatPage,
ChatView,
CreateChat,
CreateMessage,
CreateUser,
MessagePage,
MessageView,
SessionView,
UserView,
canonical_uuid,
)
from messenger.service import Messenger
from messenger.settings import Settings
logger = logging.getLogger("messenger")
class RequestContext:
def __init__(self, app: ASGIApp):
self.app = app
async def __call__(self, scope: Scope, receive: Receive, send: Send):
if scope["type"] != "http":
return await self.app(scope, receive, send)
request_id = str(uuid4())
scope.setdefault("state", {})["request_id"] = request_id
start, status, response_started = perf_counter(), 500, False
async def with_id(message: Message):
nonlocal status, response_started
if message["type"] == "http.response.start":
response_started = True
status = message["status"]
message["headers"] = [
pair
for pair in message.get("headers", [])
if pair[0].lower() != b"x-request-id"
] + [(b"x-request-id", request_id.encode())]
await send(message)
try:
await self.app(scope, receive, with_id)
except Exception as exc:
# Do not let Uvicorn print exception values that could contain user data.
if response_started:
raise
logger.error(json.dumps({"event": "internal_error", "type": type(exc).__name__}))
response = error_response(
Request(scope), 500, "internal_error", "Внутренняя ошибка сервера"
)
await response(scope, receive, with_id)
finally:
route = getattr(scope.get("route"), "path", "unmatched")
logger.info(
json.dumps(
{
"event": "request",
"request_id": request_id,
"method": scope["method"],
"route": route,
"status": status,
"duration_ms": round((perf_counter() - start) * 1000, 3),
}
)
)
def error_response(
request: Request, status: int, code: str, message: str, headers: dict | None = None
) -> JSONResponse:
identity = getattr(request.state, "request_id", str(uuid4()))
return JSONResponse(
status_code=status,
content={"error": {"code": code, "message": message, "request_id": identity}},
headers={"X-Request-Id": identity, **(headers or {})},
)
def create_app(settings: Settings | None = None) -> FastAPI:
settings = settings or Settings.from_env()
repository = PostgresRepository(settings.database_url, settings.pool_size)
cache = SessionCache(settings.cache_url)
authentication = AuthService(repository, cache, settings.session_ttl)
@asynccontextmanager
async def lifespan(app: FastAPI):
repository.open()
app.state.ready = True
logger.info(json.dumps({"event": "started", "environment": os.getenv("APP_ENV", "lab")}))
try:
yield
finally:
app.state.ready = False
repository.close()
cache.close()
logger.info(json.dumps({"event": "stopped"}))
app = FastAPI(lifespan=lifespan, docs_url=None, redoc_url=None, openapi_url=None)
app.add_middleware(RequestContext)
app.state.messenger = Messenger(repository)
app.state.repository = repository
app.state.authentication = authentication
app.state.cache = cache
app.state.ready = False
@app.exception_handler(DomainError)
async def domain_error(request: Request, exc: DomainError):
return error_response(request, exc.status, exc.code, exc.message, exc.headers)
@app.exception_handler(RequestValidationError)
async def validation_error(request: Request, exc: RequestValidationError):
return error_response(request, 400, "invalid_request", "Некорректные поля или JSON")
@app.exception_handler(HTTPException)
async def http_error(request: Request, exc: HTTPException):
code = "not_found" if exc.status_code == 404 else "invalid_request"
return error_response(request, exc.status_code, code, "Некорректный HTTP-запрос")
@app.exception_handler(Exception)
async def unexpected_error(request: Request, exc: Exception):
logger.error(json.dumps({"event": "internal_error", "type": type(exc).__name__}))
return error_response(request, 500, "internal_error", "Внутренняя ошибка сервера")
def service(request: Request) -> Messenger:
return request.app.state.messenger
def identity(request: Request) -> Identity:
if len(request.headers.getlist("authorization")) != 1:
raise unauthorized()
return authentication.identify(bearer_digest(request.headers.get("authorization")))
def actor(current: Annotated[Identity, Depends(identity)]) -> User:
return current.user
async def credentials(request: Request) -> tuple[str, str]:
if len(request.headers.getlist("authorization")) != 1:
raise unauthorized("Basic")
result = basic_credentials(request.headers.get("authorization"))
if await request.body():
raise invalid("Вход не принимает тело запроса")
return result
def resource_id(chat_id: str) -> str:
try:
return canonical_uuid(chat_id)
except ValueError:
raise invalid("Некорректный UUID чата") from None
def pagination(request: Request) -> tuple[int, str | None]:
for key in ("limit", "cursor"):
if len(request.query_params.getlist(key)) > 1:
raise invalid("Параметр пагинации указан несколько раз")
raw = request.query_params.get("limit", "50")
try:
if not re.fullmatch(r"[0-9]+", raw):
raise ValueError
limit = int(raw)
if not 1 <= limit <= 100:
raise ValueError
except ValueError:
raise invalid("limit должен быть целым от 1 до 100") from None
return limit, request.query_params.get("cursor")
def json_input(request: Request):
media = request.headers.get("content-type", "").split(";", 1)[0].strip().lower()
if media != "application/json":
raise DomainError(415, "unsupported_media_type", "Требуется application/json")
CurrentUser = Annotated[User, Depends(actor)]
Service = Annotated[Messenger, Depends(service)]
ChatId = Annotated[str, Depends(resource_id)]
Pagination = Annotated[tuple[int, str | None], Depends(pagination)]
@app.get("/health/live")
def live():
return {"status": "ok"}
@app.get("/health/ready")
def ready(request: Request):
if not request.app.state.ready:
raise DomainError(503, "unavailable", "Приложение не готово")
repository.ready()
return {"status": "ok"}
@app.post(
"/api/v1/users",
status_code=201,
response_model=UserView,
dependencies=[Depends(json_input)],
)
def register(body: CreateUser):
return authentication.register(body.username, body.display_name, body.password)
@app.post("/api/v1/auth/sessions", status_code=201, response_model=SessionView)
def login(value: Annotated[tuple[str, str], Depends(credentials)]):
return authentication.login(*value)
@app.delete("/api/v1/auth/sessions/current", status_code=204)
def logout(current: Annotated[Identity, Depends(identity)]):
authentication.logout(current)
return Response(status_code=204)
@app.get("/api/v1/users/me", response_model=UserView)
def me(current: CurrentUser):
return current
@app.post(
"/api/v1/chats",
status_code=201,
response_model=ChatView,
dependencies=[Depends(json_input)],
)
def create_chat(body: CreateChat, current: CurrentUser, messenger: Service):
return messenger.create_chat(current, body.title, body.member_ids)
@app.get("/api/v1/chats", response_model=ChatPage)
def chats(current: CurrentUser, messenger: Service, page: Pagination):
return messenger.chats(current, *page)
@app.get("/api/v1/chats/{chat_id}", response_model=ChatView)
def chat(current: CurrentUser, chat: ChatId, messenger: Service):
return messenger.chat(current, chat)
@app.post(
"/api/v1/chats/{chat_id}/messages",
status_code=201,
response_model=MessageView,
dependencies=[Depends(json_input)],
)
def send_message(body: CreateMessage, current: CurrentUser, chat: ChatId, messenger: Service):
return messenger.send(current, chat, body.text)
@app.get("/api/v1/chats/{chat_id}/messages", response_model=MessagePage)
def messages(current: CurrentUser, chat: ChatId, messenger: Service, page: Pagination):
return messenger.messages(current, chat, *page)
return app
+127
View File
@@ -0,0 +1,127 @@
"""Argon2id passwords and opaque sessions. Cache hits never authorize a request."""
import base64
import binascii
import hashlib
import re
import secrets
from contextlib import contextmanager
from dataclasses import dataclass
from threading import BoundedSemaphore
from argon2 import PasswordHasher
from argon2.exceptions import InvalidHashError, VerificationError
from argon2.profiles import RFC_9106_LOW_MEMORY
from messenger.cache import SessionCache
from messenger.domain import DomainError, User
from messenger.repository import PostgresRepository
def unauthorized(scheme: str = "Bearer") -> DomainError:
challenge = scheme + ' realm="messenger"'
if scheme == "Basic":
challenge += ', charset="UTF-8"'
return DomainError(
401,
"unauthorized",
"Требуется действительная идентификация",
{"WWW-Authenticate": challenge},
)
def basic_credentials(header: str | None) -> tuple[str, str]:
try:
if header is None or len(header) > 2048:
raise ValueError
scheme, encoded = header.split(" ", 1)
if scheme.lower() != "basic":
raise ValueError
raw = base64.b64decode(encoded, validate=True).decode("utf-8")
username, password = raw.split(":", 1)
if not re.fullmatch(r"[a-z0-9_]{3,32}", username):
raise ValueError
if not 12 <= len(password) <= 128 or not password.strip():
raise ValueError
return username, password
except ValueError, UnicodeError, binascii.Error:
raise unauthorized("Basic") from None
def bearer_digest(header: str | None) -> bytes:
if header:
parts = header.split(" ")
if len(parts) == 2 and parts[0].lower() == "bearer":
if re.fullmatch(r"[A-Za-z0-9_-]{43}", parts[1]):
return hashlib.sha256(parts[1].encode()).digest()
raise unauthorized()
@dataclass(frozen=True)
class Identity:
user: User
token_hash: bytes
@dataclass(frozen=True)
class Session:
token: str
token_type: str
expires_at: str
user: User
class AuthService:
def __init__(self, repository: PostgresRepository, cache: SessionCache, ttl: int):
self.repository, self.cache, self.ttl = repository, cache, ttl
self.hasher = PasswordHasher.from_parameters(RFC_9106_LOW_MEMORY)
self.kdf_slots = BoundedSemaphore(2)
self.dummy_hash = self.hasher.hash(secrets.token_urlsafe(32))
@contextmanager
def kdf(self):
if not self.kdf_slots.acquire(timeout=0.5):
raise DomainError(503, "unavailable", "Обработка пароля временно занята")
try:
yield
finally:
self.kdf_slots.release()
def register(self, username: str, display_name: str, password: str) -> User:
with self.kdf():
encoded = self.hasher.hash(password)
return self.repository.add_user(username, display_name, encoded)
def login(self, username: str, password: str) -> Session:
credentials = self.repository.credentials(username)
encoded = credentials[1] if credentials else self.dummy_hash
try:
with self.kdf():
self.hasher.verify(encoded, password)
except VerificationError, InvalidHashError:
raise unauthorized("Basic") from None
if credentials is None:
raise unauthorized("Basic")
token = secrets.token_urlsafe(32)
digest = hashlib.sha256(token.encode()).digest()
user = credentials[0]
expires = self.repository.create_session(digest, user.id, self.ttl)
return Session(token, "Bearer", expires, user)
def identify(self, digest: bytes) -> Identity:
session = self.repository.active_session(digest)
if session is None:
raise unauthorized()
user_id = str(session["user_id"])
user = self.cache.get(digest, user_id)
if user is None:
user = self.repository.get_user(user_id)
if user is None:
raise unauthorized()
ttl = int((session["expires_at"] - session["checked_at"]).total_seconds())
self.cache.put(digest, user, ttl)
return Identity(user, digest)
def logout(self, identity: Identity):
self.repository.revoke_session(identity.token_hash)
self.cache.delete(identity.token_hash)
+57
View File
@@ -0,0 +1,57 @@
"""Disposable session-user cache; PostgreSQL always decides token validity."""
import json
import logging
from dataclasses import asdict
from redis import Redis
from redis.backoff import NoBackoff
from redis.exceptions import RedisError
from redis.retry import Retry
from messenger.domain import User
logger = logging.getLogger("messenger")
class SessionCache:
def __init__(self, url: str):
self.client = Redis.from_url(
url,
socket_connect_timeout=0.2,
socket_timeout=0.2,
max_connections=8,
decode_responses=True,
retry_on_timeout=False,
retry=Retry(NoBackoff(), 0),
)
@staticmethod
def key(digest: bytes) -> str:
return "session-user:" + digest.hex()
def get(self, digest: bytes, user_id: str) -> User | None:
try:
raw = self.client.get(self.key(digest))
if raw:
value = User(**json.loads(raw))
if value.id == user_id:
return value
except RedisError, ValueError, TypeError:
logger.warning('{"event":"session_cache_unavailable","operation":"get"}')
return None
def put(self, digest: bytes, user: User, ttl: int):
try:
self.client.set(self.key(digest), json.dumps(asdict(user)), ex=max(1, ttl))
except RedisError:
logger.warning('{"event":"session_cache_unavailable","operation":"set"}')
def delete(self, digest: bytes):
try:
self.client.delete(self.key(digest))
except RedisError:
logger.warning('{"event":"session_cache_unavailable","operation":"delete"}')
def close(self):
self.client.close()
+41
View File
@@ -0,0 +1,41 @@
"""Versioned keyset position, bound to a list and its resource, never an offset."""
import base64
import binascii
import json
from datetime import UTC, datetime
from uuid import UUID
from messenger.domain import HistoryKey, invalid
def encode_cursor(scope: str, position: HistoryKey) -> str:
value = {"v": 1, "scope": scope, "created_at": position[0], "id": position[1]}
return (
base64.urlsafe_b64encode(json.dumps(value, separators=(",", ":")).encode())
.decode()
.rstrip("=")
)
def decode_cursor(value: str | None, scope: str) -> HistoryKey | None:
if value is None:
return None
try:
if not value or len(value) > 1024:
raise ValueError
raw = base64.b64decode(value + "=" * (-len(value) % 4), altchars=b"-_", validate=True)
data = json.loads(raw)
if not isinstance(data, dict) or set(data) != {"v", "scope", "created_at", "id"}:
raise ValueError
if type(data["v"]) is not int or data["v"] != 1 or data["scope"] != scope:
raise ValueError
if not isinstance(data["created_at"], str) or not data["created_at"].endswith("Z"):
raise ValueError
stamp = datetime.fromisoformat(data["created_at"])
if stamp.tzinfo != UTC or not isinstance(data["id"], str):
raise ValueError
identity = str(UUID(data["id"]))
return stamp.isoformat(timespec="microseconds").replace("+00:00", "Z"), identity
except ValueError, TypeError, KeyError, UnicodeError, binascii.Error:
raise invalid("Некорректный cursor или другая область пагинации") from None
+62
View File
@@ -0,0 +1,62 @@
"""Immutable domain values; no dependency on HTTP or a storage technology."""
from dataclasses import dataclass
from datetime import UTC, datetime
from uuid import uuid4
def utc_now() -> str:
return datetime.now(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z")
def new_id() -> str:
return str(uuid4())
class DomainError(Exception):
def __init__(self, status: int, code: str, message: str, headers: dict | None = None):
super().__init__(message)
self.status = status
self.code = code
self.message = message
self.headers = headers or {}
def invalid(message: str = "Некорректный запрос") -> DomainError:
return DomainError(400, "invalid_request", message)
def not_found() -> DomainError:
return DomainError(404, "not_found", "Объект не найден")
@dataclass(frozen=True, slots=True)
class User:
id: str
username: str
display_name: str
created_at: str
@dataclass(frozen=True, slots=True)
class Chat:
id: str
title: str
member_ids: tuple[str, ...]
created_at: str
@dataclass(frozen=True, slots=True)
class Message:
id: str
chat_id: str
sender_id: str
text: str
created_at: str
type HistoryKey = tuple[str, str]
def history_key(item: Chat | Message) -> HistoryKey:
return item.created_at, item.id
+46
View File
@@ -0,0 +1,46 @@
"""Transactional, checksummed migrations, serialized across concurrent starts."""
import hashlib
import os
from pathlib import Path
import psycopg
from messenger.settings import secret
def migrate(conninfo: str, directory: Path):
with psycopg.connect(conninfo, connect_timeout=5) as conn:
conn.execute("SELECT pg_advisory_xact_lock(2301002)")
conn.execute(
"CREATE TABLE IF NOT EXISTS schema_migrations ("
"version text PRIMARY KEY, checksum text NOT NULL, "
"applied_at timestamptz NOT NULL DEFAULT clock_timestamp())"
)
for path in sorted(directory.glob("*.sql")):
content = path.read_text()
checksum = hashlib.sha256(content.encode()).hexdigest()
current = conn.execute(
"SELECT checksum FROM schema_migrations WHERE version=%s", (path.stem,)
).fetchone()
if current:
if current[0] != checksum:
raise RuntimeError("Applied migration checksum changed: " + path.stem)
continue
conn.execute(content)
conn.execute(
"INSERT INTO schema_migrations (version,checksum) VALUES (%s,%s)",
(path.stem, checksum),
)
print("Applied migration " + path.stem)
def main():
migrate(
secret("DATABASE_URL_FILE", "/run/secrets/database_url"),
Path(os.getenv("MIGRATIONS_DIR", "/app/migrations")),
)
if __name__ == "__main__":
main()
+196
View File
@@ -0,0 +1,196 @@
"""PostgreSQL adapter: bounded connections, parameterized SQL, commit before return."""
from contextlib import contextmanager
from datetime import datetime
from typing import Protocol
import psycopg
from psycopg import errors
from psycopg.rows import dict_row
from psycopg_pool import ConnectionPool, PoolTimeout, TooManyRequests
from messenger.domain import Chat, DomainError, HistoryKey, Message, User, invalid, new_id
def stamp(value: datetime) -> str:
return value.isoformat(timespec="microseconds").replace("+00:00", "Z")
def user_value(row) -> User:
return User(str(row["id"]), row["username"], row["display_name"], stamp(row["created_at"]))
def chat_value(row) -> Chat:
return Chat(
str(row["id"]),
row["title"],
tuple(str(x) for x in row["member_ids"]),
stamp(row["created_at"]),
)
def message_value(row) -> Message:
return Message(
str(row["id"]),
str(row["chat_id"]),
str(row["sender_id"]),
row["text"],
stamp(row["created_at"]),
)
class Repository(Protocol):
def get_user(self, user_id: str) -> User | None: ...
def add_chat(self, title: str, member_ids: tuple[str, ...]) -> Chat: ...
def get_chat(self, chat_id: str) -> Chat | None: ...
def page_chats(self, user_id: str, after: HistoryKey | None, limit: int) -> list[Chat]: ...
def add_message(self, chat_id: str, sender_id: str, text: str) -> Message: ...
def page_messages(
self, chat_id: str, after: HistoryKey | None, limit: int
) -> list[Message]: ...
CHAT_COLUMNS = """c.id, c.title, c.created_at,
ARRAY(SELECT user_id FROM chat_members WHERE chat_id=c.id ORDER BY position) AS member_ids"""
class PostgresRepository:
def __init__(self, conninfo: str, pool_size: int = 8):
self.pool = ConnectionPool(
conninfo,
min_size=1,
max_size=pool_size,
timeout=1,
max_waiting=32,
open=False,
check=ConnectionPool.check_connection,
kwargs={
"row_factory": dict_row,
"connect_timeout": 2,
"options": "-c statement_timeout=2500 -c lock_timeout=1000 "
"-c idle_in_transaction_session_timeout=5000 -c timezone=UTC",
},
)
def open(self):
self.pool.open(wait=True, timeout=15)
def close(self):
self.pool.close(timeout=5)
@contextmanager
def connection(self):
try:
with self.pool.connection() as conn:
yield conn
except (
psycopg.OperationalError,
psycopg.InterfaceError,
PoolTimeout,
TooManyRequests,
errors.QueryCanceled,
errors.LockNotAvailable,
):
raise DomainError(503, "unavailable", "Хранилище временно недоступно") from None
def ready(self):
with self.connection() as conn:
conn.execute("SELECT 1 FROM schema_migrations WHERE version = '001_initial'").fetchone()
def add_user(self, username: str, display_name: str, password_hash: str) -> User:
try:
with self.connection() as conn:
row = conn.execute(
"INSERT INTO users (id,username,display_name,password_hash) "
"VALUES (%s,%s,%s,%s) RETURNING *",
(new_id(), username, display_name, password_hash),
).fetchone()
return user_value(row)
except errors.UniqueViolation:
raise DomainError(409, "conflict", "Имя пользователя уже занято") from None
def credentials(self, username: str):
with self.connection() as conn:
row = conn.execute("SELECT * FROM users WHERE username=%s", (username,)).fetchone()
return (user_value(row), row["password_hash"]) if row else None
def get_user(self, user_id: str) -> User | None:
with self.connection() as conn:
row = conn.execute("SELECT * FROM users WHERE id=%s", (user_id,)).fetchone()
return user_value(row) if row else None
def add_chat(self, title: str, member_ids: tuple[str, ...]) -> Chat:
try:
with self.connection() as conn:
row = conn.execute(
"INSERT INTO chats (id,title) VALUES (%s,%s) RETURNING *", (new_id(), title)
).fetchone()
with conn.cursor() as cur:
cur.executemany(
"INSERT INTO chat_members (chat_id,user_id,position) VALUES (%s,%s,%s)",
[(row["id"], member, i) for i, member in enumerate(member_ids)],
)
return Chat(str(row["id"]), title, member_ids, stamp(row["created_at"]))
except errors.ForeignKeyViolation:
raise invalid("Указан неизвестный участник") from None
def get_chat(self, chat_id: str) -> Chat | None:
with self.connection() as conn:
row = conn.execute(
"SELECT " + CHAT_COLUMNS + " FROM chats c WHERE c.id=%s", (chat_id,)
).fetchone()
return chat_value(row) if row else None
def page_chats(self, user_id: str, after: HistoryKey | None, limit: int) -> list[Chat]:
condition = " AND (c.created_at,c.id) > (%s::timestamptz,%s::uuid)" if after else ""
params = (user_id, *after, limit) if after else (user_id, limit)
with self.connection() as conn:
rows = conn.execute(
"SELECT " + CHAT_COLUMNS + " FROM chats c WHERE EXISTS "
"(SELECT 1 FROM chat_members m WHERE m.chat_id=c.id AND m.user_id=%s)"
+ condition
+ " ORDER BY c.created_at,c.id LIMIT %s",
params,
).fetchall()
return [chat_value(row) for row in rows]
def add_message(self, chat_id: str, sender_id: str, text: str) -> Message:
with self.connection() as conn:
row = conn.execute(
"INSERT INTO messages (id,chat_id,sender_id,text) VALUES (%s,%s,%s,%s) RETURNING *",
(new_id(), chat_id, sender_id, text),
).fetchone()
return message_value(row)
def page_messages(self, chat_id: str, after: HistoryKey | None, limit: int) -> list[Message]:
condition = " AND (created_at,id) > (%s::timestamptz,%s::uuid)" if after else ""
params = (chat_id, *after, limit) if after else (chat_id, limit)
with self.connection() as conn:
rows = conn.execute(
"SELECT * FROM messages WHERE chat_id=%s"
+ condition
+ " ORDER BY created_at,id LIMIT %s",
params,
).fetchall()
return [message_value(row) for row in rows]
def create_session(self, token_hash: bytes, user_id: str, ttl: int) -> str:
with self.connection() as conn:
row = conn.execute(
"INSERT INTO sessions (token_hash,user_id,expires_at) "
"VALUES (%s,%s,clock_timestamp() + make_interval(secs => %s)) RETURNING expires_at",
(token_hash, user_id, ttl),
).fetchone()
return stamp(row["expires_at"])
def active_session(self, token_hash: bytes):
with self.connection() as conn:
return conn.execute(
"SELECT user_id,expires_at,clock_timestamp() AS checked_at FROM sessions "
"WHERE token_hash=%s AND expires_at > clock_timestamp()",
(token_hash,),
).fetchone()
def revoke_session(self, token_hash: bytes):
with self.connection() as conn:
conn.execute("DELETE FROM sessions WHERE token_hash=%s", (token_hash,))
+92
View File
@@ -0,0 +1,92 @@
"""Strict lab 2 wire types; password never belongs to a response User."""
import re
from typing import Annotated
from uuid import UUID
from pydantic import AfterValidator, BaseModel, ConfigDict, Field, field_validator
def canonical_uuid(value: str) -> str:
if not re.fullmatch(r"[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}", value):
raise ValueError("Ожидается UUID")
return str(UUID(value))
def nonblank(value: str) -> str:
if not value.strip() or any(0xD800 <= ord(char) <= 0xDFFF for char in value):
raise ValueError("Ожидается непустая строка Unicode")
return value
type Identifier = Annotated[str, AfterValidator(canonical_uuid)]
type ShortText = Annotated[str, Field(min_length=1, max_length=100), AfterValidator(nonblank)]
class Input(BaseModel):
model_config = ConfigDict(strict=True, extra="forbid")
class CreateUser(Input):
username: str = Field(min_length=3, max_length=32)
display_name: ShortText
password: Annotated[str, Field(min_length=12, max_length=128), AfterValidator(nonblank)]
@field_validator("username")
@classmethod
def valid_username(cls, value: str) -> str:
if not re.fullmatch(r"[a-z0-9_]{3,32}", value):
raise ValueError("Недопустимое имя пользователя")
return value
class CreateChat(Input):
title: ShortText
member_ids: list[Identifier] = Field(min_length=1, max_length=100)
class CreateMessage(Input):
text: Annotated[str, Field(min_length=1, max_length=4000), AfterValidator(nonblank)]
class View(BaseModel):
model_config = ConfigDict(from_attributes=True, extra="forbid")
class UserView(View):
id: str
username: str
display_name: str
created_at: str
class SessionView(View):
token: str
token_type: str
expires_at: str
user: UserView
class ChatView(View):
id: str
title: str
member_ids: list[str]
created_at: str
class MessageView(View):
id: str
chat_id: str
sender_id: str
text: str
created_at: str
class ChatPage(View):
items: list[ChatView]
next_cursor: str | None
class MessagePage(View):
items: list[MessageView]
next_cursor: str | None
+50
View File
@@ -0,0 +1,50 @@
"""Use cases shared by HTTP and tests. Authorization precedes resource access."""
from dataclasses import dataclass
from messenger.cursor import decode_cursor, encode_cursor
from messenger.domain import Chat, Message, User, history_key, invalid, not_found
from messenger.repository import Repository
@dataclass(frozen=True)
class Page[T]:
items: list[T]
next_cursor: str | None
class Messenger:
def __init__(self, repository: Repository):
self.repository = repository
def create_chat(self, actor: User, title: str, member_ids: list[str]) -> Chat:
if len(member_ids) != len(set(member_ids)) or actor.id not in member_ids:
raise invalid("Участники не должны повторяться; вызывающий должен входить в чат")
return self.repository.add_chat(title, tuple(member_ids))
def chat(self, actor: User, chat_id: str) -> Chat:
chat = self.repository.get_chat(chat_id)
if chat is None or actor.id not in chat.member_ids:
raise not_found()
return chat
def chats(self, actor: User, limit: int, cursor: str | None) -> Page[Chat]:
scope = "chats:" + actor.id
after = decode_cursor(cursor, scope)
return self._page(self.repository.page_chats(actor.id, after, limit + 1), limit, scope)
def send(self, actor: User, chat_id: str, text: str) -> Message:
self.chat(actor, chat_id)
return self.repository.add_message(chat_id, actor.id, text)
def messages(self, actor: User, chat_id: str, limit: int, cursor: str | None) -> Page[Message]:
self.chat(actor, chat_id)
scope = "messages:" + chat_id
after = decode_cursor(cursor, scope)
return self._page(self.repository.page_messages(chat_id, after, limit + 1), limit, scope)
@staticmethod
def _page[T: Chat | Message](items: list[T], limit: int, scope: str) -> Page[T]:
visible = items[:limit]
cursor = encode_cursor(scope, history_key(visible[-1])) if len(items) > limit else None
return Page(visible, cursor)
+30
View File
@@ -0,0 +1,30 @@
"""Explicit configuration; credentials are read from untracked secret files."""
import os
from dataclasses import dataclass, field
from pathlib import Path
def secret(name: str, default: str) -> str:
return Path(os.getenv(name, default)).read_text().strip()
@dataclass(frozen=True)
class Settings:
database_url: str = field(repr=False)
cache_url: str = field(repr=False)
session_ttl: int = 3600
pool_size: int = 8
@classmethod
def from_env(cls):
ttl = int(os.getenv("SESSION_TTL_SECONDS", "3600"))
size = int(os.getenv("DATABASE_POOL_SIZE", "8"))
if not 1 <= ttl <= 2_592_000 or not 1 <= size <= 32:
raise ValueError("Invalid session lifetime or connection pool size")
return cls(
secret("DATABASE_URL_FILE", "/run/secrets/database_url"),
secret("CACHE_URL_FILE", "/run/secrets/cache_url"),
ttl,
size,
)
+72
View File
@@ -0,0 +1,72 @@
import base64
from pathlib import Path
from uuid import uuid4
import psycopg
import pytest
from fastapi.testclient import TestClient
from psycopg import sql
from psycopg.conninfo import make_conninfo
from messenger.app import create_app
from messenger.migrate import migrate
from messenger.settings import Settings
ROOT = Path(__file__).resolve().parents[1]
PASSWORD = "Учебный:пароль😀-12345"
@pytest.fixture(scope="session")
def settings():
password = (ROOT / "secrets/postgres_password").read_text().strip()
admin = make_conninfo(
host="127.0.0.1", port=55432, user="messenger", password=password, dbname="messenger"
)
database = "student_tests_" + uuid4().hex
with psycopg.connect(admin, autocommit=True) as conn:
conn.execute(sql.SQL("CREATE DATABASE {}").format(sql.Identifier(database)))
config = Settings(make_conninfo(admin, dbname=database), "redis://127.0.0.1:56379/1")
migrate(config.database_url, ROOT / "migrations")
yield config
with psycopg.connect(admin, autocommit=True) as conn:
conn.execute(sql.SQL("DROP DATABASE {} WITH (FORCE)").format(sql.Identifier(database)))
@pytest.fixture
def client(settings):
with psycopg.connect(settings.database_url) as conn:
conn.execute("TRUNCATE users,chats,chat_members,messages,sessions CASCADE")
with TestClient(create_app(settings), raise_server_exceptions=False) as client:
client.app.state.cache.client.flushdb()
yield client
def basic(username, password=PASSWORD):
return {
"Authorization": "Basic " + base64.b64encode((username + ":" + password).encode()).decode()
}
@pytest.fixture
def actors(client):
result = []
for name in ("alice", "bob", "eve"):
r = client.post(
"/api/v1/users", json={"username": name, "display_name": name, "password": PASSWORD}
)
assert r.status_code == 201
session = client.post("/api/v1/auth/sessions", headers=basic(name))
assert session.status_code == 201
result.append({**r.json(), "token": session.json()["token"]})
return result
@pytest.fixture
def room(client, actors):
response = client.post(
"/api/v1/chats",
headers={"Authorization": "Bearer " + actors[0]["token"]},
json={"title": "Чат 👋", "member_ids": [u["id"] for u in actors[:2]]},
)
assert response.status_code == 201
return response.json()
+299
View File
@@ -0,0 +1,299 @@
import hashlib
import json
import re
import time
from concurrent.futures import ThreadPoolExecutor
from uuid import uuid4
import psycopg
import pytest
from conftest import PASSWORD, ROOT, basic
from fastapi.testclient import TestClient
from messenger.app import create_app
from messenger.auth import basic_credentials
from messenger.migrate import migrate
def headers(actor):
return {"Authorization": "Bearer " + actor["token"]}
def error(response, status, code):
assert response.status_code == status, response.text
body = response.json()["error"]
assert set(body) == {"code", "message", "request_id"}
assert body["code"] == code
assert body["request_id"] == response.headers["X-Request-Id"]
assert len(response.headers.get_list("X-Request-Id")) == 1
if status == 401:
assert response.headers["WWW-Authenticate"].startswith(("Basic", "Bearer"))
@pytest.mark.parametrize("body", ["{", "null", "[]", '"text"', '{"username":'])
def test_malformed_json(client, body):
error(
client.post("/api/v1/users", content=body, headers={"Content-Type": "application/json"}),
400,
"invalid_request",
)
@pytest.mark.parametrize(
"change",
[
{"username": "ab"},
{"username": "a" * 33},
{"username": "Upper"},
{"username": "кириллица"},
{"username": "valid\n"},
{"username": 123},
{"username": True},
{"display_name": 123},
{"display_name": None},
{"display_name": " \n\t"},
{"display_name": "😀" * 101},
{"display_name": "\ud800"},
{"password": "short"},
{"password": "😀" * 129},
{"password": 123},
{"password": " " * 12},
{"password": "\ud800" * 12},
{"extra": True},
],
)
def test_strict_registration(client, change):
data = {"username": "valid", "display_name": "Имя", "password": PASSWORD, **change}
response = client.post(
"/api/v1/users", content=json.dumps(data), headers={"Content-Type": "application/json"}
)
error(response, 400, "invalid_request")
def test_unicode_password_hash_and_authentication(client, settings, actors):
for u in actors:
assert "password" not in u and "password_hash" not in u
assert re.fullmatch(r"[A-Za-z0-9_-]{43}", u["token"])
with psycopg.connect(settings.database_url) as conn:
encoded = conn.execute("SELECT password_hash FROM users WHERE username='alice'").fetchone()[
0
]
assert encoded.startswith("$argon2id$") and PASSWORD not in encoded
assert (
conn.execute("SELECT octet_length(token_hash) FROM sessions LIMIT 1").fetchone()[0]
== 32
)
bad = client.post("/api/v1/auth/sessions", headers=basic("alice", "wrong-password"))
absent = client.post("/api/v1/auth/sessions", headers=basic("unknown", "wrong-password"))
error(bad, 401, "unauthorized")
error(absent, 401, "unauthorized")
assert bad.json()["error"]["message"] == absent.json()["error"]["message"]
assert bad.headers["WWW-Authenticate"] == 'Basic realm="messenger", charset="UTF-8"'
for value in (
{},
basic("alice"),
{"X-User-Id": actors[0]["id"]},
{"Authorization": "Bearer unknown"},
):
error(client.get("/api/v1/users/me", headers=value), 401, "unauthorized")
actual = client.get(
"/api/v1/users/me", headers={**headers(actors[0]), "X-User-Id": actors[2]["id"]}
).json()
assert actual["id"] == actors[0]["id"]
error(
client.post("/api/v1/auth/sessions", headers=basic("alice"), json={}),
400,
"invalid_request",
)
@pytest.mark.parametrize("value", [None, "Bearer a", "Basic !", "Basic YWxpY2U=", "Basic /w=="])
def test_invalid_basic(value):
with pytest.raises(Exception) as caught:
basic_credentials(value)
assert caught.value.status == 401
def test_registration_race(client, settings):
def register(_):
return client.post(
"/api/v1/users",
json={"username": "same", "display_name": "Алиса", "password": PASSWORD},
).status_code
with ThreadPoolExecutor(max_workers=2) as pool:
assert sorted(pool.map(register, range(10))) == [201] + [409] * 9
with psycopg.connect(settings.database_url) as conn:
assert conn.execute("SELECT count(*) FROM users WHERE username='same'").fetchone()[0] == 1
def test_acl_validation_and_transaction_rollback(client, actors, room, settings):
path = "/api/v1/chats/" + room["id"]
for suffix in ("", "/messages"):
error(client.get(path + suffix, headers=headers(actors[2])), 404, "not_found")
error(client.get("/api/v1/chats/not-a-uuid"), 401, "unauthorized")
error(
client.get("/api/v1/chats/not-a-uuid", headers=headers(actors[0])), 400, "invalid_request"
)
with psycopg.connect(settings.database_url) as conn:
before = conn.execute("SELECT count(*) FROM chats").fetchone()[0]
for members in ([actors[0]["id"], str(uuid4())], [actors[0]["id"]] * 2, [actors[1]["id"]], []):
error(
client.post(
"/api/v1/chats",
headers=headers(actors[0]),
json={"title": "rollback", "member_ids": members},
),
400,
"invalid_request",
)
with psycopg.connect(settings.database_url) as conn:
assert conn.execute("SELECT count(*) FROM chats").fetchone()[0] == before
assert conn.execute("SELECT count(*) FROM chat_members").fetchone()[0] == 2
for body in (
{"text": ""},
{"text": " \t"},
{"text": "😀" * 4001},
{"text": 123},
{"text": None},
{"text": "ok", "sender_id": actors[1]["id"]},
):
error(
client.post(path + "/messages", headers=headers(actors[0]), json=body),
400,
"invalid_request",
)
for query in (
"limit=0",
"limit=101",
"limit=true",
"limit=1.0",
"limit=1&limit=2",
"cursor=",
"cursor=bad!",
"cursor=e30",
"cursor=x&cursor=y",
):
error(
client.get(path + "/messages?" + query, headers=headers(actors[0])),
400,
"invalid_request",
)
def test_concurrent_messages_and_keyset_ties(client, actors, room, settings):
path = f"/api/v1/chats/{room['id']}/messages"
def send(i):
r = client.post(path, headers=headers(actors[i % 2]), json={"text": f"m{i} 😀"})
assert r.status_code == 201
return r.json()
with ThreadPoolExecutor(max_workers=10) as pool:
sent = list(pool.map(send, range(100)))
with psycopg.connect(settings.database_url) as conn:
conn.execute(
"UPDATE messages SET created_at='2026-10-17T12:00:00Z' WHERE chat_id=%s", (room["id"],)
)
for m in sent:
m["created_at"] = "2026-10-17T12:00:00.000000Z"
found, cursor = [], None
while True:
query = {"limit": 17 if cursor else 1}
if cursor:
query["cursor"] = cursor
response = client.get(path, params=query, headers=headers(actors[1]))
assert response.status_code == 200
page = response.json()
found.extend(page["items"])
cursor = page["next_cursor"]
if not cursor:
break
assert len(found) == len({x["id"] for x in found}) == 100
assert found == sorted(sent, key=lambda x: (x["created_at"], x["id"]))
first_cursor = client.get(path + "?limit=1", headers=headers(actors[0])).json()["next_cursor"]
error(
client.get("/api/v1/chats", params={"cursor": first_cursor}, headers=headers(actors[0])),
400,
"invalid_request",
)
def test_cache_hit_flush_and_revocation(client, actors, monkeypatch):
user = actors[0]
url = "/api/v1/users/me"
assert client.get(url, headers=headers(user)).status_code == 200
repository = client.app.state.repository
original = repository.get_user
def must_be_cached(*args):
raise AssertionError("cache hit should avoid fetching immutable user again")
monkeypatch.setattr(repository, "get_user", must_be_cached)
assert client.get(url, headers=headers(user)).status_code == 200
monkeypatch.setattr(repository, "get_user", original)
cache = client.app.state.cache.client
digest = hashlib.sha256(user["token"].encode()).digest()
key = client.app.state.cache.key(digest)
assert 0 < cache.ttl(key) <= 3600
stale = cache.get(key)
cache.flushdb()
assert client.get(url, headers=headers(user)).status_code == 200
assert client.delete("/api/v1/auth/sessions/current", headers=headers(user)).status_code == 204
cache.set(key, stale, ex=3600) # A resurrected stale cache entry must not resurrect a session.
error(client.get(url, headers=headers(user)), 401, "unauthorized")
error(
client.delete("/api/v1/auth/sessions/current", headers=headers(user)), 401, "unauthorized"
)
def test_expiry_and_api_restart(client, actors, settings, monkeypatch, tmp_path):
database_file, cache_file = tmp_path / "database_url", tmp_path / "cache_url"
database_file.write_text(settings.database_url)
cache_file.write_text(settings.cache_url)
monkeypatch.setenv("DATABASE_URL_FILE", str(database_file))
monkeypatch.setenv("CACHE_URL_FILE", str(cache_file))
monkeypatch.setenv("SESSION_TTL_SECONDS", "2")
with TestClient(create_app()) as short:
response = short.post("/api/v1/auth/sessions", headers=basic("alice"))
assert response.status_code == 201
token = {"Authorization": "Bearer " + response.json()["token"]}
assert short.get("/api/v1/users/me", headers=token).status_code == 200
with TestClient(create_app(settings)) as restarted:
assert restarted.get("/api/v1/users/me", headers=token).status_code == 200
time.sleep(2.1)
error(restarted.get("/api/v1/users/me", headers=token), 401, "unauthorized")
def test_migrations_idempotent_and_detect_change(client, settings, tmp_path):
migrate(settings.database_url, ROOT / "migrations")
modified = tmp_path / "001_initial.sql"
modified.write_text((ROOT / "migrations/001_initial.sql").read_text() + "\n-- changed")
with pytest.raises(RuntimeError, match="checksum changed"):
migrate(settings.database_url, tmp_path)
def test_logs_and_safe_errors(client, monkeypatch, caplog):
canary = "PRIVATE_BODY_CANARY_123"
with caplog.at_level("INFO", logger="messenger"):
r = client.post(
"/api/v1/users",
json={"username": "logging", "display_name": canary, "password": PASSWORD},
)
assert r.status_code == 201
assert canary not in caplog.text and PASSWORD not in caplog.text
def broken(*args):
raise RuntimeError(canary)
monkeypatch.setattr(client.app.state.authentication, "register", broken)
response = client.post(
"/api/v1/users", json={"username": "broken", "display_name": "x", "password": PASSWORD}
)
error(response, 500, "internal_error")
assert canary not in response.text and canary not in caplog.text
error(
client.post("/api/v1/users", content="{}", headers={"Content-Type": "text/plain"}),
415,
"unsupported_media_type",
)
Generated
+1022
View File
File diff suppressed because it is too large Load Diff