Лабораторная 2: PostgreSQL, сессии, Valkey, трек 2

This commit is contained in:
2026-10-16 19:39:21 +03:00
commit aa0fd15616
82 changed files with 7996 additions and 0 deletions
+20
View File
@@ -0,0 +1,20 @@
.git
.github
.env
.env.*
!.env.example
secrets
certs
volumes
data
backups
*.key
*.pem
*.p12
*.pfx
*.jks
.venv
__pycache__
node_modules
evidence
.DS_Store
+16
View File
@@ -0,0 +1,16 @@
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
# These are logical interface suggestions; map actual framework names in REPORT.md.
APP_HOST=0.0.0.0
APP_PORT=8080
APP_ENV=lab
SESSION_TTL_SECONDS=3600
# Choose credentials locally. File paths contain no secret values.
DATABASE_URL_FILE=/run/secrets/database_url
# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
# postgres = сессии только в PostgreSQL; postgres+cache = PostgreSQL (источник истины) + Valkey как read-through кэш.
SESSION_STORE=postgres+cache
SESSION_CACHE_TTL_SECONDS=60
CACHE_URL_FILE=/run/secrets/cache_url
# Пулы/таймауты (необязательно, значения по умолчанию в app/config.py):
# DB_POOL_MAX=10 DB_POOL_TIMEOUT=3 DB_STATEMENT_TIMEOUT_MS=5000 CACHE_TIMEOUT=0.25
# WEB_CONCURRENCY=2 THREAD_LIMIT=24 HASH_CONCURRENCY=4
+18
View File
@@ -0,0 +1,18 @@
## Лабораторная 2
Автор / группа: TODO
Целевая оценка (3/4/5): TODO
Трек 5, если заявлен: TODO
Что реализовано и что перенесено: TODO
Команды запуска из чистого clone: TODO
Результаты проверок и ссылка на REPORT.md: TODO
Ограничения / известные ошибки: TODO
Источники и использование ИИ: TODO
- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [ ] Контракт и публичные тесты не ослаблены.
- [ ] make check и make test выполнены; приложен реальный вывод.
- [ ] Сценарии отказов/безопасности своего уровня воспроизведены.
- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
+16
View File
@@ -0,0 +1,16 @@
name: Skeleton contracts
on: [push, pull_request]
permissions:
contents: read
jobs:
contracts:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- run: python -m pip install -r requirements-dev.txt
- run: make check validate PYTHON=python
# This job validates the skeleton, not a student solution.
# Add build, readiness and make test in a separate application job.
+32
View File
@@ -0,0 +1,32 @@
# Local/private state
.env
.env.*
!.env.example
secrets/
certs/private/
*.key
*.p12
*.pfx
*.jks
*.pem
*.tfstate*
volumes/
data/
backups/
# Runtime/build artifacts
.venv/
__pycache__/
*.py[cod]
node_modules/
dist/
build/
target/
bin/
obj/
coverage/
*.log
.DS_Store
.idea/
.vscode/
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
+19
View File
@@ -0,0 +1,19 @@
# Работа через fork и pull request
1. После публикации преподавателем сделайте fork репозитория **текущей** лабораторной в своём аккаунте и clone своего fork. URL преподаватель выдаёт отдельно.
2. Создайте ветку `solution/<group>-<surname>` от исходной ветки skeleton. Ветка преподавателя и файлы контракта остаются основой проверки.
3. Для lab2–7 перенесите из своей предыдущей лабы только исходники, миграции, собственные тесты, Dockerfile и нужные конфигурации. Не копируйте `.git`, `.env`, credentials, volumes, `README.md`, `COURSE.md`, публичные `tests/` и `contracts/` поверх новой версии. Сначала сравните изменения API в `COURSE.md`.
4. Реализуйте задание, добавьте свою инструкцию запуска и заполните `REPORT.md`. Публичные проверки дополняйте отдельными тестами, не ослабляйте assertions.
5. Выполните `make check`, запустите свой стенд, затем `make test`. Выполните сценарии отказов текущей лабы. Их запуск всегда явный: scaffold сам не останавливает контейнеры.
6. Commit и push делайте в свой fork. Откройте PR в исходный репозиторий преподавателя, заголовок: `ЛР N — Группа — Фамилия — на 3/4/5`. Выберите правильную базовую ветку и заполните шаблон.
7. После замечаний обновляйте тот же PR. Чужие решения не переносите без указания источника и согласованных правил курса.
Платформа может называть PR «merge request» — процесс тот же. `.github/` содержит необязательные удобства для GitHub; проверки локально от платформы не зависят. Инициализация и публикация исходных Git-репозиториев выполняются преподавателем отдельно.
## Правила изменения skeleton
Не удаляйте обязательные endpoint, поля, рубрику и публичные проверки. Изменение контракта согласуйте отдельным комментарием/PR; обход тестов не является решением. Код приложения размещайте в `src/` либо в принятой для языка структуре. Собственные тесты — `student-tests/` или штатный каталог фреймворка. Ссылки на результаты проверки и команды запуска должны переживать clone на другой машине.
## CI
Готовый GitHub workflow проверяет целостность контракта и синтаксис Python-проверок. Он **не запускает отсутствующее приложение** и **не подтверждает оценку**. Студент добавляет сборку своего приложения, запуск/готовность стенда и `make test` в отдельный job. Не используйте `pull_request_target` для запуска кода из fork, не выдавайте CI секреты или доступ к общему Docker-host.
+53
View File
@@ -0,0 +1,53 @@
# Сквозной проект: мессенджер под нагрузкой
Семь самостоятельных репозиториев содержат задания и проверяемые контракты одной системы. Вы переносите собственную реализацию между лабораторными. Язык, фреймворк и библиотеки выбираете сами. Web UI, WebSocket, редактирование/удаление сообщений, публичный поиск пользователей и Kubernetes не входят в обязательный минимум: достаточно REST API.
| Лаба | Новая инженерная задача | Что появляется в системе |
| --- | --- | --- |
| 1 | Контракт, процессы и контейнер | In-memory API, Dockerfile, HTTP smoke |
| 2 | Сохранность и идентификация | PostgreSQL, Basic → сессия; Redis/Valkey на 4 |
| 3 | Горизонтальное масштабирование | Балансировщик, ≥2 API-реплики, общие сессии, идемпотентность |
| 4 | Бинарные данные | Приватное S3-совместимое хранилище и вложения |
| 5 | Фоновая работа | Брокер, worker, состояния вложений и преобразование изображений |
| 6 | Диагностика | OTel Collector, хранилища сигналов, Grafana |
| 7 | Защита и эксплуатация | Argon2id, TLS/mTLS, OpenBao, минимальные привилегии |
## Как оценивать
Оценки накопительные **внутри лабораторной**: 4 = весь уровень 3 + весь уровень 4; 5 = весь уровень 4 + **один** полностью выполненный трек 5 на выбор. Несколько недоделанных треков не заменяют один завершённый. Условие «весь уровень» включает реализацию, проверку и объяснение на защите. Красивые схемы и дополнительные технологии не компенсируют неработающий обязательный сценарий.
Для начала следующей лабы достаточно обязательного минимума предыдущей. Сохраняются предыдущие обязательные возможности, с явно описанными переходами API ниже. Не требуется сначала получить 5 за все ранние лабы. Можно исправлять свою базу по ходу курса; такие исправления выделяйте в PR. Реализация на 3 работоспособна, но не претендует на промышленную готовность. Даже 5 в lab7 — учебная доказанная защита в заявленной модели угроз, а не сертификат полной безопасности.
На 3 студент самостоятельно собирает рабочую систему. На 4 показывает практики, ожидаемые от стажёра/джуна в команде: воспроизводимость, диагностику, обработку ошибок и проверки отказов. На 5 формулирует гипотезу, ставит эксперимент, приводит измерения и обсуждает границы решения — это предмет конкретной похвалы магистранту.
## Контракт и совместимость
`contracts/openapi.json` — OpenAPI 3.1.0, `contracts/README.md` — нормативная семантика. Контракт каждого репозитория самодостаточен; соседние папки на машине преподавателя не нужны. `tests/` — публичные проверки, а не эталонное решение. Контракт, рубрика и публичные тесты имеют приоритет над случайным поведением библиотек. При противоречии создайте вопрос преподавателю; не подгоняйте тест под приложение.
Три объявленных изменения обязательного API:
1. **1 → 2:** регистрация требует `password`; `X-User-Id` заменяется Bearer. Basic используется только при создании сессии.
2. **2 → 3:** `Idempotency-Key` обязателен для отправки сообщения; ответы API содержат `X-Instance-Id`.
3. **4 → 5:** загрузка вложения возвращает `202` вместо `201`, состояние становится асинхронным. Клиент опрашивает метаданные. Старое текстовое сообщение остаётся валидным: `attachment_ids` по умолчанию `[]`.
У lab7 меняется транспорт на HTTPS, бизнес-эндпоинты остаются прежними. Внутреннее mTLS не заменяет пользовательскую сессию. Новые возможности на 4/5 добавляйте обратно совместимо, в отдельном `contracts/extensions.openapi.json` или документе; обязательный контракт сохраняйте.
## Общая предметная модель
Пользователь (`username`, `display_name`) состоит в чатах. Список участников задаётся при создании чата и в обязательном API не изменяется. В чате отправляются сообщения, с lab4 — со ссылками на вложения этого чата. Сервер назначает UUID и время. Порядок истории — `(created_at, id)` по возрастанию. Для защиты достаточно показать взаимодействие нескольких API-клиентов; фронтенд не требуется.
С lab2 данные PostgreSQL — источник истины. Сессии могут храниться в PostgreSQL или Redis/Valkey, если выполняют контракт срока жизни и перезапуска. Файлы с lab4 живут в S3, метаданные — в PostgreSQL. Redis и Valkey — альтернативы: оба одновременно не нужны. Аналогично выбирается одно S3-хранилище, один брокер и один основной путь оркестрации.
## Воспроизводимость и честные измерения
- Укажите версии runtime и контейнерных образов, аппаратную конфигурацию, CPU/RAM-лимиты, команду запуска и время прогрева. Для образов используйте явный тег версии или digest, не `latest`.
- Все тестовые пользователи и изображения синтетические. `make test` создаёт данные: запускайте его на учебном стенде. Не публикуйте пароли, токены, приватные ключи, персональные данные или подписанные URL.
- Минимальный отчёт о нагрузке: длительность, конкуренция/интенсивность, успешные RPS, доля ошибок, p50/p95/p99, CPU/RAM, размер набора данных. Универсального проходного RPS для разных ноутбуков нет.
- Сравнивайте одинаковые запросы при одинаковых ресурсах. Успешный `/health/live` не доказывает сохранность сообщений, а HTTP `202` — окончание обработки.
- Один Docker-host не обеспечивает отказоустойчивость к потере этого host. Несколько API-процессов не делают единственную БД или LB высокодоступными. Отдельно называйте, какие отказы выдерживает эксперимент.
## Что сдавать
Исходники, Dockerfile, нужные манифесты и конфигурации, миграции, собственные тесты, заполненный `REPORT.md`, сведения об использовании внешнего кода и ИИ. Уметь объяснить и изменить своё решение на защите обязательно. Приложите команды и текстовые результаты; скриншоты — дополнение, а не единственное доказательство.
PR должен собираться из чистого clone по инструкции автора. Секреты создаются отдельно; тестовые fixtures и открытые конфигурации хранятся в репозитории. Перенос кода между лабами описан в [CONTRIBUTING.md](CONTRIBUTING.md).
+28
View File
@@ -0,0 +1,28 @@
# syntax=docker/dockerfile:1
# Базовый образ тот же, что в lab1 (python:3.11.9-slim) — тег уже собирался и существует.
FROM python:3.11.9-slim
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1 PIP_DISABLE_PIP_VERSION_CHECK=1 \
WEB_CONCURRENCY=2
WORKDIR /app
# 1) зависимости по lockfile отдельным слоем — кэш Docker не инвалидируется правкой исходников
COPY requirements.txt .
RUN pip install -r requirements.txt
# 2) исходники (секреты и .env исключены .dockerignore)
COPY main.py .
COPY app ./app
# 3) не root (UID фиксирован, чтобы права на secrets-файлы были предсказуемы)
RUN useradd --system --uid 10001 --no-create-home --shell /usr/sbin/nologin appuser
USER 10001
EXPOSE 8080
HEALTHCHECK --interval=5s --timeout=3s --start-period=10s --retries=10 \
CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/live', timeout=2)"]
# exec-форма: uvicorn = PID 1, получает SIGTERM и за 5 с дообслуживает запросы (как в lab1).
# Число процессов берётся из WEB_CONCURRENCY (uvicorn читает её сам).
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080", "--timeout-graceful-shutdown", "5"]
+8
View File
@@ -0,0 +1,8 @@
# Teaching outline, not a runnable Dockerfile. Implement your own Dockerfile.
# 1. Choose a runtime/toolchain version and pin the base image tag/digest.
# 2. Copy dependency manifests first; install from the language lockfile.
# 3. Copy source and build. For compiled languages use a separate runtime stage.
# 4. Run the HTTP process as PID 1; listen on 0.0.0.0:8080.
# 5. Add non-root, signals and healthcheck according to the current rubric.
# 6. Pass runtime config/secrets at startup, never COPY .env or secret files.
# This file deliberately has no FROM/CMD: selecting/implementing them is the task.
+38
View File
@@ -0,0 +1,38 @@
# Памятка преподавателю — лабораторная 2
## Что подготовлено
Язык реализации не задан. README содержит накопительные уровни 3/4/5, сценарий защиты и вопросы. В каждой лабе собственная полная версия OpenAPI, поэтому fork не зависит от соседних каталогов. Публичный HTTP smoke не содержит реализации сервера; Dockerfile.example и compose.example.yaml (если есть) — задания/ориентиры, не готовый deployment.
## Перед публикацией
1. Выберите GitHub/GitLab и организацию, опубликуйте каждый каталог как отдельный template/skeleton repository, сообщите студентам URL и правила именования PR/MR. Эти материалы не публикуют репозитории автоматически.
2. Задайте default branch, защиту исходных материалов и правила приёма. `.github/` уже содержит шаблон PR и CI контракта; в GitLab перенесите эквивалентные настройки, локальные Makefile-команды одинаковы.
3. Сообщите, индивидуальная работа или командная, сроки, правила использования стороннего кода/ИИ и ресурсы демонстрационного стенда. Эти организационные решения намеренно не выдуманы в задании.
4. Уточните ограничения площадки (например доступна ли виртуализация/несколько узлов). Для 5 предусмотрено по два трека: один можно выполнить без настоящего multi-node cloud. Универсальный проходной RPS не установлен.
## Что проверять
| Проверка | Что подтверждает | Чего не подтверждает |
| --- | --- | --- |
| make check | Структура файлов, JSON, локальные refs, синтаксис Python | Реализация/запуск API |
| make validate | Полная OpenAPI 3.1, JSON Schema и примеры | Поведение сервера |
| make test | Один сквозной контрактный сценарий текущей лабы | Все ошибки, persistence, HA, security |
| test-persistence (lab2+) | Данные/прежний токен после вызова restart hook | Реальный перезапуск, если hook — no-op |
| test-failover (lab3+) | Смена обслуживающей реплики, сохранность, retry без дубля | Несколько физических узлов, HA DB/LB |
| test-security (lab7) | Доверенный HTTPS и отказ недоверенного CA | Внутреннее mTLS/identity/ACL/OpenBao |
| Защита и тесты студента | Реальность инфраструктуры и критерии выбранного уровня | Неограниченная промышленная безопасность |
Проверяйте реальные контейнеры/логи процессов и данные до/после отказа: одного X-Instance-Id недостаточно. Для 4 требуются все пункты 3+4, для 5 — все пункты 3+4 и один **завершённый** трек 5. Сравнивайте подтверждённые результаты со сформулированными критериями, а не количество установленных сервисов.
## Приём PR
Проверка запускается на изолированном учебном окружении с синтетическими secrets, не на общей production БД. Студенческие Dockerfile/hooks/CI — выполняемый код: обычный fork workflow без секретов и без доступа к общему Docker socket. Не запускайте PR через pull_request_target с привилегиями преподавателя.
Исходные README/контракт/публичные tests сохраняются, реализация переносится студентом между лабами через собственные исходники и миграции. Исправление общей спецификации публикуйте отдельным изменением, объясняя влияние на все затронутые лабораторные.
## Проверка этой версии skeleton
На 2026-09-10 выполнены структурные проверки и полная валидация всех семи OpenAPI/JSON Schema, проверка локальных Markdown-ссылок/YAML и декодирование PNG fixture. HTTP-клиенты проверены на временном изолированном тестовом стенде: позитивный smoke 1–7, отрицательные варианты неправильного sender, pagination, ACL, logout, bytes и пустого API; также пути persistence/failover/load и внешнего TLS.
Временный стенд не включён в студенческие каталоги и не является эталонным решением. Реальное приложение, Compose, PostgreSQL/S3/broker и mTLS/OpenBao в skeleton отсутствуют: их работоспособность не заявляется. Docker CLI в среде подготовки не был доступен. Это проверка материалов и тестовых драйверов, не приёмка будущих решений студентов.
+56
View File
@@ -0,0 +1,56 @@
PYTHON ?= python3
BASE_URL ?= http://localhost:8080
CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
.PHONY: help check validate test load test-persistence up down test-student test-rollback test-expiry test-deps explain track2-indexes track2-restore
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
check:
$(PYTHON) scripts/check_contract.py
validate:
$(PYTHON) scripts/validate_openapi.py
test:
$(PYTHON) tests/smoke.py --base-url "$(BASE_URL)" $(TLS_ARGS)
load:
$(PYTHON) tests/load.py --base-url "$(BASE_URL)" $(TLS_ARGS)
test-persistence:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable restart hook"; exit 2)
$(PYTHON) tests/resilience.py --mode persistence --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
# ---- Цели студента (публичные цели выше не менялись) ----
up:
sh scripts/init-secrets.sh
docker compose --env-file .env up -d --build
# Намеренно БЕЗ -v: тома (данные) сохраняются. Удаление данных: docker compose --env-file .env down -v
down:
docker compose --env-file .env down
test-student:
cd tests_student && $(PYTHON) test_integration.py
test-rollback:
docker compose --env-file .env run --rm --no-deps -v "$(CURDIR)/tests_student:/srv/tests_student:ro" api python tests_student/test_db_rollback.py
test-expiry:
sh scripts/test-expiry.sh
test-deps:
cd tests_student && $(PYTHON) test_dependencies.py
# Трек 5.2: нужна ОТДЕЛЬНАЯ БД эксперимента (DATABASE_URL_FILE) и второй сервер PostgreSQL для восстановления.
track2-indexes:
$(PYTHON) scripts/track2_indexes.py --out evidence/track2-indexes.json
$(PYTHON) scripts/track2_indexes.py --reverse --out evidence/track2-indexes-pass2.json
track2-restore:
@test -n "$(SRC_URL)" -a -n "$(DST_ADMIN_URL)" || (echo "Set SRC_URL and DST_ADMIN_URL"; exit 2)
$(PYTHON) scripts/track2_restore.py --src-url "$(SRC_URL)" --dst-admin-url "$(DST_ADMIN_URL)" --out evidence/track2-restore.json
+105
View File
@@ -0,0 +1,105 @@
# Лабораторная 2. PostgreSQL, сессии и Redis/Valkey
Перенести состояние в постоянное хранилище и связать запросы с аутентифицированным пользователем. Подтверждённые сообщения и действующие сессии переживают перезапуск.
Это **skeleton**, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; UI не обязателен.
[Карта курса](COURSE.md) · [Процесс fork/PR](CONTRIBUTING.md) · [OpenAPI](contracts/openapi.json) · [Семантика API](contracts/README.md) · [Проверки](tests/README.md) · [Отчёт](REPORT.md) · [Примеры JSON](contracts/examples.json) · [Памятка преподавателю](MAINTAINERS.md)
## Откуда начинаем
Перенесите собственный минимум lab1. Изменения API: password при регистрации, Basic для создания сессии, Bearer вместо X-User-Id для бизнес-запросов.
**Архитектура:** Клиент → API → PostgreSQL; на 4 появляется Redis ИЛИ Valkey для сессий/кэша.
## Что сделать
1. Опишите таблицы, ограничения, индексы и транзакционные границы до написания запросов. Добавьте версионируемые миграции.
2. Перенесите пользователей, чаты, членство и сообщения в PostgreSQL. Не используйте SQLite как замену PostgreSQL в принимаемом стенде.
3. Реализуйте регистрацию с password KDF, вход через Basic, opaque Bearer-сессию, expiry и logout. Действующие сессии тоже должны сохраняться.
4. Подготовьте единый локальный запуск API и БД (Compose рекомендуется уже здесь), подключите именованные volumes.
5. Пройдите smoke и тест полного перезапуска. На 4 добавьте Redis/Valkey с конкретной ролью и повторите эксперимент отказа.
## Оценка «3»: работающий минимум
- Минимум lab1 сохранён с объявленным переходом на новую аутентификацию. Все обязательные данные и ещё действующие сессии переживают рестарт API и хранилищ без удаления volumes.
- PostgreSQL содержит пользователей, чаты, участников и сообщения. Есть первичные/внешние ключи, уникальность username и миграции с нуля. Составная операция создания чата выполняется атомарно.
- Basic применяется только на POST /auth/sessions, остальные endpoint требуют Bearer. Есть срок жизни сессии и отзыв; X-User-Id не даёт доступ. Пароли уже хешируются password KDF.
- make test и make test-persistence ACTION_SCRIPT=scripts/restart.sh проходят. Миграции повторно запускаются без дублирования данных. Secrets/volumes не попадают в Git.
## Оценка «4»: уровень стажёра/джуна
Весь уровень 3 **и все** пункты ниже:
- Redis ИЛИ Valkey реально используется для сессий с TTL либо осмысленного кэша. Опишите источник истины, политику expiry и инвалидации. Если это единственное хранилище сессий, включите persistence, выдерживающее проверяемый рестарт; один TTL не сохраняет данные.
- Используются параметризованные запросы/безопасный ORM, ограниченный connection pool и таймауты. Проверены гонка регистрации одинакового username и rollback составной операции.
- Индекс истории обоснован запросом и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях; пагинация не использует полный scan всей истории на каждую страницу.
- Есть автоматическая проверка expiry при коротком SESSION_TTL_SECONDS, logout, неверного пароля и недоступности Redis/БД. При потере сервиса приложение возвращает ограниченную ошибку/корректно обходит кэш, не принимает запрос от анонимного пользователя как доверенный.
## Оценка «5»: исследование и доказанный результат
Весь уровень 4 **и один законченный трек на выбор**. Приведите гипотезу, повторяемую методику, результаты и ограничения.
**Трек 1. Согласованность кэша.** Покажите на конкурентном сценарии stale read или cache stampede, реализуйте защиту и измерьте число SQL-запросов/latency до и после. Докажите read-after-write из контракта и восстановление после рестарта кэша; одной установки Redis недостаточно.
**Трек 2. План запроса и восстановление.** Исследуйте ≥100 000 сообщений с неравномерными размерами чатов, сравните ≥2 индекса/запроса и стоимость записи. Сделайте backup → восстановление в новое хранилище → сверку количества и выбранных сообщений. Обсудите время восстановления и границы потери данных.
## Как начать и проверить
```sh
# Работает прямо в skeleton, Python 3.9+; приложение не запускается:
make check
# После реализации запустите свой сервер/стенд по REPORT.md.
# По умолчанию тест использует http://localhost:8080.
make test
```
`.env.example`, `compose.example.yaml` и `contracts/infrastructure.json` описывают настройки и роли компонентов. **compose.example.yaml — список ролей с пустым services, не запускаемый стенд.** Реализуйте свой `compose.yaml`/`stack.yaml`, закрепите версии образов, заполните локальный `.env` и опишите bootstrap/миграции. Все зависимости поднимаются из этого репозитория; ссылка «у меня БД уже установлена» не заменяет воспроизводимость.
```sh
# Compose-вариант после реализации:
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождитесь /health/ready; затем make test.
# Для Swarm укажите эквивалентные build/push/deploy-команды в REPORT.md.
```
Примеры запросов доступны в `examples/requests.http`, примеры JSON — в `contracts/examples.json`. Для полной проверки схемы (по желанию локально; CI делает её автоматически):
```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
```
Smoke не выставляет оценку автоматически. Проверку сохранности/отказов запускайте явно по [tests/README.md](tests/README.md), остальные доказательства приведите в отчёте.
## Сценарий защиты
1. Применить миграции к пустому volume, создать пользователей, войти, отправить сообщение.
2. Запустить persistence-сценарий: он держит токен только в памяти тестового процесса; action script перезапускает API и все используемые хранилища, сохраняя volumes.
3. После готовности тот же токен читает те же данные; после logout — 401. Повторить с отдельным коротким TTL для проверки expiry.
4. Для 4: показать роль Redis/Valkey, план SQL и ошибку зависимости. Для 5: выполнить выбранный эксперимент.
## Что должно быть в PR
Исходники, Dockerfile, миграции, compose.yaml либо эквивалентный воспроизводимый запуск, scripts/restart.sh, собственные тесты и отчёт.
Заполните `REPORT.md` и [шаблон PR](.github/pull_request_template.md), укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах [объявленных переходов](COURSE.md).
## Вопросы на защите
- Что подтверждает COMMIT и какие гарантии зависят от настройки durability?
- Где хранятся сессии и что будет после flush/restart Redis?
- Чем аутентификация отличается от доступа к конкретному чату?
- Почему hash пароля и быстрый checksum имеют разные задачи?
## Первичные материалы
- [PostgreSQL transactions](https://www.postgresql.org/docs/current/tutorial-transactions.html)
- [PostgreSQL EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html)
- [Valkey persistence](https://valkey.io/topics/persistence/)
- [Redis persistence](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/)
- [Basic authentication](https://www.rfc-editor.org/info/rfc7617/)
+217
View File
@@ -0,0 +1,217 @@
# Отчёт — лабораторная 2
- Автор, группа: Никифорова Екатерина, БВТ2301
- Целевая оценка: **5**, выбранный трек 5: **Трек 2 «План запроса и восстановление»** (уровни 3 и 4 тоже выполнены)
- Commit/PR: ЗАПОЛНИТЬ после публикации
- Источники, библиотеки и помощь ИИ: FastAPI 0.115 + Uvicorn 0.30 (как в lab1), psycopg 3.2 + psycopg_pool, argon2-cffi, redis-py; документация PostgreSQL (transactions, EXPLAIN), Valkey persistence, RFC 7617.
## Запуск из чистого clone
Требования: Docker Engine ≥ 24 с Compose v2, Python ≥ 3.9 (для тестов), `sh` (Git Bash на Windows).
```sh
sh scripts/init-secrets.sh # случайные пароли -> secrets/*, копия .env.example -> .env (всё в .gitignore)
docker compose --env-file .env config --quiet # проверка конфигурации
docker compose --env-file .env up -d --build # postgres -> migrate (одноразово) -> valkey -> api
until curl -fs localhost:8080/health/ready; do sleep 1; done
python tests/smoke.py --base-url http://localhost:8080 # публичный smoke
cd tests_student && python test_integration.py && python test_dependencies.py && cd .. # расширенные тесты API (11 + зависимости)
python scripts/track2_indexes.py --out evidence/track2-indexes.json # трек 2: замеры индексов
python scripts/track2_restore.py --src-url "$DATABASE_URL" --dst-admin-url "$DST_URL" --out evidence/track2-restore.json
```
Оператору больше ничего делать не нужно. Миграции применяет сервис `migrate` (идемпотентно, под advisory-lock).
Безопасная остановка: `docker compose --env-file .env stop` (данные и тома целы). Намеренное удаление учебных данных:
`docker compose --env-file .env down -v && rm -rf secrets` — **только это стирает тома**; в `restart.sh` и тестах `-v` не используется.
## Архитектура и решения
```
Клиент ──HTTP──> api (FastAPI, Uvicorn) ──> PostgreSQL 17 (источник истины, том pgdata)
└──────────────> Valkey 8 (кэш сессий, AOF, том valkeydata)
migrate (одноразово) ──> PostgreSQL
```
| Роль | Service | Образ (зафиксирован) | Health | Том | Сеть/порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| api | `api` | сборка из `Dockerfile`, база `python:3.11.9-slim` (как в lab1), зависимости из `requirements.txt` | `/health/ready` (API + PostgreSQL) | нет (stateless, read-only rootfs) | `127.0.0.1:8080` | secrets-файлы `database_url`, `cache_url` |
| postgres | `postgres` | `postgres:17.6-alpine` | `pg_isready` | `pgdata` | только внутренняя сеть | `POSTGRES_PASSWORD_FILE` |
| valkey | `valkey` | `valkey/valkey:8.1.3-alpine` | `valkey-cli ping` | `valkeydata` | только внутренняя сеть | `--requirepass` из secrets-файла |
| migrate | `migrate` | образ api | — (завершается) | — | внутренняя | `database_url` |
**Источник истины.** Пользователи, чаты, участники, сообщения и сессии — в PostgreSQL. Valkey хранит только производные данные
(кэш сессий) и может быть потерян без потери данных.
**Схема (`app/migrations/`).** `users` (UNIQUE username + CHECK формата), `chats`, `chat_members` (PK `(chat_id,user_id)`),
`messages` (композитный FK `(chat_id,sender_id) -> chat_members`: в чат пишет только участник — инвариант в БД, а не только в коде),
`sessions` (PK = SHA-256 токена). Индексы: `messages(chat_id, created_at, id)` — история; `chats(created_at,id)`;
`chat_members(user_id, chat_id)`; `sessions(expires_at)`.
**Транзакционные границы.** (1) Регистрация: Argon2id считается *до* транзакции (без удержания соединения), затем один `INSERT`;
гонку одинаковых username решает `UNIQUE` → `409`. (2) Создание чата: проверка участников + `INSERT chats` + `INSERT chat_members`
в одной транзакции; любая ошибка → ROLLBACK. (3) Сообщение: один `INSERT`; COMMIT происходит до ответа `201`.
(4) Логин: проверка пароля → `INSERT sessions` в транзакции → после COMMIT прогрев кэша.
**Сессии и кэш (уровень 4).**
- *Источник истины* — таблица `sessions` (в БД хранится SHA-256 токена, не сам токен). Токен — `secrets.token_urlsafe(32)` (256 бит).
- *Кэш*: cache-aside `sess:v1:<sha256(token)>` → `{user, exp}`. Чтение: Valkey → при промахе PostgreSQL → `SET NX PX`.
- *Expiry*: `expires_at` в PostgreSQL; в кэше TTL = `min(SESSION_CACHE_TTL_SECONDS, остаток жизни)` **и** `exp` проверяется в самой записи — срок не зависит от точности TTL ключа.
TTL не продлевается ни обращениями, ни рестартом.
- *Инвалидация*: logout = `DELETE` в PostgreSQL → после COMMIT `SET sess:v1:… "revoked"` (tombstone, TTL = cache TTL). Заполнение кэша — `SET NX`, поэтому медленный
параллельный читатель не «воскресит» отозванную сессию поверх tombstone. Негативные результаты не кэшируются (защита от забивания кэша мусорными токенами).
Пользователи в этом API неизменяемы, поэтому инвалидации данных пользователя не требуется.
- *Persistence Valkey*: AOF `everysec` + том. Строго она не обязательна (истина в PostgreSQL), но стенд подтверждает рестарт всех хранилищ.
- *Известная граница*: если logout выполнен, пока Valkey недоступен, tombstone не записывается, и после возврата Valkey (AOF сохраняет TTL) отозванная сессия может
ещё ≤ `SESSION_CACHE_TTL_SECONDS` (60 с) приниматься из кэша. Это осознанный компромисс; снижается уменьшением TTL кэша.
**Пул, таймауты, ошибки.** `psycopg_pool`: `max_size=16` на процесс (2 процесса uvicorn = 32 из 100 соединений PostgreSQL), потоков sync-обработчиков 24, ожидание соединения 3 с, `connect_timeout=3`, `statement_timeout=5 s`, `lock_timeout=3 s`,
`idle_in_transaction_session_timeout=10 s`, `check_connection` при выдаче (после рестарта PostgreSQL мёртвые соединения отбрасываются). Valkey: таймаут 0,25 с +
circuit breaker 2 с. Все запросы параметризованы (psycopg передаёт параметры отдельно от SQL; конкатенации SQL нет). Недоступность БД → `503 unavailable`
без деталей; неожиданное исключение → `500 internal_error`, стек — только в серверный лог.
**Критичные зависимости readiness.** PostgreSQL — критична (`/health/ready` = 503 без неё). Valkey — нет (`ready` остаётся 200, кэш обходится).
**Что перенесено из lab1 и что изменено.** Приложение — прямое развитие `main.py` из lab1 (FastAPI/Uvicorn, тот же Dockerfile-подход).
- *Сохранено без изменений по поведению*: маршруты и коды ответов; формат ошибки `{"error":{code,message,request_id}}`; middleware `X-Request-Id` (входящее значение теперь принимается только если оно безопасно: `[A-Za-z0-9._-]{1,64}`, иначе генерируется новое; заголовок есть и в ответах 500/503); keyset-пагинация с курсором, привязанным к ресурсу (`messages`/`chats` + id) и порядком `(created_at, id)`; строгая валидация (лишние поля → 400, неверный Content-Type → 415, пустой/пробельный текст → 400); 404 вместо 403 для чужого чата; `/health/live` и `/health/ready`; `--timeout-graceful-shutdown 5`; тесты lab1 (`tests/test_own.py`, `tests/test_race.py`, 8+1 сценариев) перенесены на Bearer.
- *Изменено (объявленные переходы lab2)*: добавлен `password` при регистрации (Argon2id); `POST /auth/sessions` с Basic; `Authorization: Bearer` вместо `X-User-Id` (заголовок игнорируется); словари под `RLock` заменены PostgreSQL; `threading.RLock` больше не нужен — согласованность обеспечивают транзакции и ограничения БД; `/health/ready` проверяет PostgreSQL.
- *Заменено осознанно*: pydantic-модели lab1 (`extra="forbid"`) заменены строгим разбором JSON (`app/validation.py`): он отвергает дубли ключей, `NaN`, NUL и одиночные суррогаты (после них PostgreSQL возвращал бы 500), а проверка доступа (404) выполняется **до** валидации тела; автодокументация FastAPI (`/docs`) отключена — контракт в `contracts/openapi.json`.
- *Исправлено по сравнению с lab1*: регулярка `^…$` пропускала username с завершающим `\n` (в Python `$` совпадает перед `\n`) — теперь `fullmatch`; `len(display_name)` считался до проверки типов — теперь тип проверяется первым.
**Переменные `.env.example` → код.** `APP_HOST/APP_PORT` — как в lab1, совпадают с `CMD uvicorn main:app --host 0.0.0.0 --port 8080`; число процессов — `WEB_CONCURRENCY` (читает сам uvicorn); `SESSION_TTL_SECONDS` → `app/config.py` (срок сессии);
`DATABASE_URL_FILE`, `CACHE_URL_FILE` → пути к secrets-файлам; `SESSION_STORE` = `postgres` | `postgres+cache`; `SESSION_CACHE_TTL_SECONDS` — TTL записи кэша.
## Доказательства критериев
Основные замеры выполнены в песочнице (без Docker, PostgreSQL 16.15, Redis 7). Дополнительно всё проверено на реальном Docker Compose-стенде
(Windows 11 + Docker Desktop, PostgreSQL 17.6, Valkey 8.1.3):
- `sh scripts/init-secrets.sh` — 4 секрета в `secrets/`, `.env`
- `docker compose --env-file .env up -d --build` — postgres/migrate/valkey/api, api healthy
- `python tests/smoke.py --base-url http://localhost:8080` → PASS
- Persistence: полный рестарт api+valkey+postgres тем же Bearer-токеном → 200 (`evidence/persistence-my.txt`)
- Миграции идемпотентны: `migrate` повторно → «nothing to do» (`evidence/migrations-my.txt`)
- Свои тесты: 11/11 passed (`evidence/tests-my.txt`)
- Тесты зависимостей (`evidence/tests-deps-my.txt`)
- **Трек 2 — индексы (2 прохода)**: `evidence/track2-indexes-my.json`, `evidence/track2-indexes-pass2-my.json`
- **Трек 2 — backup/restore со сверкой md5**: `evidence/track2-restore-my.txt`
(SRC=DST: users 1, chats 563, messages 102000, sessions 1; md5 совпал)
- Теги `postgres:17.6-alpine` и `valkey/valkey:8.1.3-alpine` проверены через `docker pull`
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Тесты lab1 в новой аутентификации + гонка регистрации | `pytest tests/test_own.py tests/test_race.py -v` | 15 passed | `test-results.txt` |
| Публичный smoke | `python tests/smoke.py` | `PASS: lab2 public API scenario` | `test-results.txt`, `smoke_docker.txt` |
| Контракт offline | `python scripts/check_contract.py` | `PASS: offline skeleton structure…` | `test-results.txt` |
| PostgreSQL: таблицы, PK/FK, UNIQUE, миграции с нуля | `python -m app.migrate` ×2 | 1-й запуск: применены 0001, 0002; 2-й: «nothing to do» | `migrations.txt`, `migrations-my.txt` |
| Атомарное создание чата | `tests_student/test_db_rollback.py` | FK-ошибка после `INSERT chats` → 0 строк остаётся | `test-results.txt` |
| Basic только на `/auth/sessions`, Bearer везде, `X-User-Id` игнорируется | smoke + `test_integration.py` | 401 с корректными `WWW-Authenticate` | `test-results.txt` |
| Пароли — KDF | код `app/security.py` | Argon2id (m=19 MiB, t=2, p=1), соль на пароль, rehash при смене параметров | — |
| Рестарт API и хранилищ, сессии живы | `docker compose stop api valkey postgres && up -d` | тот же токен работает после рестарта | `persistence-restart.txt`, `persistence-my.txt` |
| Secrets/volumes не в Git | `.gitignore`, `.dockerignore` | `secrets/`, `.env` исключены; в образ не копируются | — |
| **4:** Valkey реально используется | `evidence/cache-role.txt` | ключи `sess:v1:<sha256>`, PTTL ≤ 60 000 мс; tombstone после logout; сессия переживает `FLUSHALL` | `cache-role.txt` |
| **4:** параметризованные запросы, пул, таймауты | код `app/db.py`, `app/repo.py` | см. «Пул, таймауты» | — |
| **4:** гонка регистрации | `test_integration.py::registration_race_same_username` | 16 параллельных → ровно один 201, 15×409 | `test-results.txt` |
| **4:** индекс истории, EXPLAIN на ≥10 000 | `scripts/explain_history.py` (100 000 строк) | keyset с индексом: Index Scan, 4 буфера, **0,03–0,04 мс**; без индекса: Seq Scan 1235 буферов, **~8–9 мс** | `explain-history.txt` |
| **4:** expiry (короткий TTL) | `tests_student/test_expiry.py 2` | после 3,5 с: 401 на `users/me`, `chats`, `logout` | `test-results.txt` |
| **4:** logout, неверный пароль | smoke + `logout_revokes_only_that_session` | 204; повтор 401; неверный пароль 401 | `test-results.txt` |
| **5 (трек 2):** ≥100 000 сообщений, ≥2 индекса/запроса, цена записи | `scripts/track2_indexes.py` (2 прохода, Windows + Docker) | см. раздел «Трек 5.2» | `track2-indexes*.json`, `track2-indexes-my.json`, `track2-indexes-pass2-my.json` |
| **5 (трек 2):** backup → восстановление → сверка | `docker exec pg_dump/pg_restore` + md5 | counts SRC=DST (users 1, chats 563, messages 102000, sessions 1), md5 совпал | `track2-restore-my.txt` |
| **4:** недоступность Valkey/БД | `tests_student/test_dependencies.py` | Valkey off/flush → 200; PostgreSQL off → `ready`=503; после старта токен целы | `dependency-failure.txt`, `tests-deps-my.txt` |
Пагинация: `pagination_walk_and_cursor_binding` — 250 сообщений от 8 параллельных писателей, обход страницами 100/37, нет потерь/дублей/перестановок; курсор чужого чата → 400.
## Эксперименты и отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| Полный рестарт API + PostgreSQL + Valkey, тома сохранены | сессии и данные целы, прежний токен работает | PASS (`persistence-restart.txt`, `persistence-my.txt`) | потерь нет |
| Остановка Valkey | API работает через PostgreSQL | все запросы 200, `ready` 200, задержка < 2,5 с (circuit breaker) | мгновенно; потерь нет |
| `FLUSHALL` Valkey | сессии берутся из PostgreSQL, кэш наполняется заново | токены работают | мгновенно |
| Остановка PostgreSQL | 503, никакого доверия анониму | `ready`/бизнес 503 (`unavailable`), без токена 401 | после старта БД API восстановился автоматически; потерь нет |
| Короткий TTL (2 с) | сессия перестаёт действовать | 401 после истечения | — |
Методика EXPLAIN: PostgreSQL 16.15 (песочница) и 17.6 (Docker Windows), 100 000 строк (1 чат 20 000 + 4 чата-шума по 20 000), `VACUUM ANALYZE`,
сравнение «без индекса» выполнено удалением индекса в откатываемой транзакции.
## Трек 5.2. План запроса и восстановление
### Гипотезы
- **H1.** Составной индекс `(chat_id, created_at, id)` даёт страницу истории за O(размер страницы) для чата любого размера и любой глубины; индекс только по `chat_id` и «глобальный» `(created_at, id)` — нет.
- **H2.** Дополнительный индекс удорожает запись; цена растёт с шириной индекса (покрывающий `INCLUDE (sender_id, text)` дороже всех).
- **H3.** Логический backup (`pg_dump -Fc`) восстанавливается в новый сервер без потери данных *на момент снапшота*; всё записанное после начала дампа теряется (RPO = возраст бэкапа).
### Методика (повторяемая: `scripts/track2_indexes.py`, `scripts/track2_restore.py`)
- **Данные**: 100 000 сообщений в 563 чатах с неравномерными размерами: 1×50 000, 1×20 000, 1×10 000, 10×1 000, 50×100, 500×10; текст 10–400 символов; плюс 2 000 одиночных вставок в процессе замера записи (итого ≈102 000).
- **Конфигурации** (5): C0 только PK · C1 `(chat_id)` · **C2 `(chat_id, created_at, id)`** · C3 то же `INCLUDE (sender_id, text)` · C4 `(created_at, id)`.
- **Запросы**: Q1 первая страница гиганта (50 000) · Q2 keyset на глубине 40 000 · Q3 первая страница чата из 10 сообщений · Q4 keyset в середине чата из 1 000 · Q5 `OFFSET 40000` (антипример). Страница = 50 (+1) строк.
- **Чтение**: 20 прогревочных + 300 замеров на запрос, p50/p95 клиентской латентности, плюс `EXPLAIN (ANALYZE, BUFFERS)`.
- **Запись**: (а) `INSERT … SELECT` 100 000 строк, 3 повтора, медиана; (б) 2 000 одиночных `INSERT` с коммитом.
- **Повторяемость**: два прохода, второй — в **обратном** порядке конфигураций.
### Результаты — собственные замеры (Windows 11 + Docker Desktop, PostgreSQL 17.6)
**Проход 1** (`evidence/track2-indexes-my.json`):
| Конфигурация | bulk 100k, с | single p50, мс | индекс, МиБ | Q1 p50, мс | Q2 p50, мс | Q3 p50, мс |
| --- | --- | --- | --- | --- | --- | --- |
| C0 (PK only) | 3.00 | 1.770 | 0.0 | 20.143 | 14.824 | 14.878 |
| C1 `(chat_id)` | 3.06 | 1.787 | 0.9 | 14.884 | 14.300 | 0.957 |
| **C2 `(chat_id, created_at, id)`** | 3.11 | 1.733 | 6.9 | **1.219** | **1.196** | **0.932** |
| C3 + `INCLUDE` | 3.79 | 1.741 | 35.6 | 1.184 | 1.221 | 1.050 |
| C4 `(created_at, id)` | 3.26 | 1.904 | 5.0 | 3.453 | 1.492 | 32.912 |
**Проход 2** (`evidence/track2-indexes-pass2-my.json`, обратный порядок):
| Конфигурация | bulk 100k, с | single p50, мс | индекс, МиБ | Q1 p50, мс | Q2 p50, мс | Q3 p50, мс |
| --- | --- | --- | --- | --- | --- | --- |
| C4 | 3.38 | 1.714 | 5.0 | 3.433 | 1.418 | 15.920 |
| C3 | 5.17 | 2.267 | 35.5 | 2.224 | 1.837 | 1.347 |
| **C2** | 3.62 | 1.847 | 6.9 | 1.327 | 1.861 | 1.095 |
| C1 | 3.86 | 2.258 | 0.9 | 17.321 | 16.562 | 1.417 |
| C0 | 3.65 | 1.822 | 0.0 | 18.452 | 18.306 | 14.635 |
### Выводы по гипотезам
- **H1 подтверждена для C2**: 1.2–1.9 мс на любой странице любого чата (от 10 до 50 000 сообщений). C1 деградирует на гиганте (14.9–17.3 мс), C0 — везде 14–20 мс. **C4 хуже всего для маленького чата** (15.9–32.9 мс): планировщик не может эффективно отфильтровать крошечный чат по глобальному порядку.
- **Покрывающий C3 не оправдан**: Q1–Q3 того же порядка, что C2, но индекс **в 5 раз больше** (35.6 МиБ против 6.9 МиБ) и bulk-загрузка дороже (3.79 с и 5.17 с против 3.11 с и 3.62 с у C2).
- **Решение**: оставлен C2 (он же в миграции `0001_core.sql`).
### Backup → восстановление в новое хранилище → сверка (`evidence/track2-restore-my.txt`)
- **Backup**: `docker exec messenger-lab2-postgres-1 pg_dump -U messenger -d messenger -Fc --no-owner -f /tmp/dump.dump` → 3.62 МБ.
- **Новое хранилище**: отдельный контейнер `pg-restore-target` (PostgreSQL 17.6, порт 5434). `docker exec pg_restore --no-owner --exit-on-error` — без ошибок. Затем `ANALYZE`.
- **Сверка** (совпала с источником):
| Таблица | SRC | DST |
| --- | --- | --- |
| users | 1 | 1 |
| chats | 563 | 563 |
| messages | 102000 | 102000 |
| sessions | 1 | 1 |
| md5 всех сообщений | `440f9224c9a3e355f7fbd551e2a078eb` | `440f9224c9a3e355f7fbd551e2a078eb` |
- **Работоспособность копии**: публичный smoke и 11 собственных тестов прошли на API, подключённом к восстановленной БД.
### Время восстановления (RTO) и границы потери данных (RPO)
- **Измерено** (102 тыс. строк, ~65 МиБ): dump ≈0,8 с + restore ≈1,3 с + analyze ≈0,2 с ≈ **2,3 с**. Это **не оценка для продакшена**; на 100× больших данных восстановление займёт минуты.
- **RPO у логического дампа = возраст дампа.** После дампа записано 500 сообщений — в копии их нет (102 000 против 102 500 в источнике). Для сокращения RPO нужны WAL-архивация + `pg_basebackup` (PITR) или синхронная репликация — **в работе не реализованы**.
- **Безопасность при восстановлении**: отозванная после дампа сессия в копии «воскресла». Практика: после восстановления из бэкапа очистить `sessions`.
- **Что не проверялось**: восстановление в другую мажорную версию PostgreSQL, повреждённый дамп, шифрование бэкапа.
### Ограничения методики
- 1 CPU, клиент на той же машине, 2 прохода (не повторы с доверительными интервалами); p95 одиночных вставок шумит.
- Данные синтетические; реальные распределения могут сместить цифры.
- Горячий кэш: все данные поместились в `shared_buffers`/page cache; на «холодном» диске разрыв между Seq Scan и индексом был бы больше.
## Ограничения проверки
- Основные замеры трека 2 сделаны в песочнице Claude (без Docker, PostgreSQL 16.15). **Дополнительно проверено на Windows 11 + Docker Desktop (PostgreSQL 17.6, Valkey 8.1.3)**: init-secrets.sh, docker compose up -d --build, smoke PASS, persistence, миграции, трек 2 (индексы + backup/restore). См. `evidence/*-my.*`.
- Теги образов проверены: `docker pull postgres:17.6-alpine` и `docker pull valkey/valkey:8.1.3-alpine` — оба существуют.
- В evidence использованы PostgreSQL 16 и Redis 7 (песочница) и 17.6/Valkey 8.1.3 (Docker Windows); на проверяемые свойства это не влияет.
- Нагрузочный профиль (`make load`) не снимался — для уровня 4 не требуется.
## Ограничения и следующие шаги
- Выдерживается: рестарт API/PostgreSQL/Valkey с томами; потеря/сброс/недоступность Valkey; кратковременная недоступность PostgreSQL (503 → автоматическое восстановление).
- Не выдерживается: потеря тома PostgreSQL без свежего бэкапа (логический backup делается вручную, расписания и PITR нет); отказ единственного хоста.
- Семантика конкурентных вставок: `created_at` ставится `clock_timestamp()` в момент вставки, а не COMMIT. Для точной гарантии нужна монотонная последовательность (`bigserial`/outbox) — следующий шаг.
- Кэш истории сообщений не делался (трек 1 не заявлен): сейчас кэшируются только сессии.
- HTTP без TLS допустим только для локального стенда с синтетическими данными (Basic — кодирование, а не шифрование).
View File
+58
View File
@@ -0,0 +1,58 @@
"""Тонкая обёртка над Redis/Valkey. Кэш — НЕ источник истины: любая ошибка = «кэша нет».
Circuit breaker: после сбоя кэш обходится CACHE_BACKOFF секунд, чтобы недоступный Valkey
не добавлял таймаут к каждому запросу.
"""
import logging
import threading
import time
import redis
from . import config
log = logging.getLogger("cache")
_client = None
_down_until = 0.0
_lock = threading.Lock()
def _get_client():
global _client
if not config.CACHE_URL:
return None
if _client is None:
with _lock:
if _client is None:
_client = redis.Redis.from_url(
config.CACHE_URL, socket_timeout=config.CACHE_TIMEOUT,
socket_connect_timeout=config.CACHE_TIMEOUT, max_connections=20,
decode_responses=True, retry_on_timeout=False)
return _client
def _call(fn):
"""Выполнить операцию; при недоступности вернуть None и включить паузу."""
global _down_until
client = _get_client()
if client is None or time.monotonic() < _down_until:
return None
try:
return fn(client)
except redis.RedisError as exc:
_down_until = time.monotonic() + config.CACHE_BACKOFF
log.warning("cache unavailable (%s); bypassing for %.0fs", type(exc).__name__, config.CACHE_BACKOFF)
return None
def get(key):
return _call(lambda c: c.get(key))
def set_if_absent(key, value, ttl_ms):
"""SET NX PX: не перезаписывает tombstone отозванной сессии."""
return _call(lambda c: c.set(key, value, nx=True, px=ttl_ms))
def set_always(key, value, ttl_ms):
return _call(lambda c: c.set(key, value, px=ttl_ms))
+46
View File
@@ -0,0 +1,46 @@
"""Конфигурация из переменных окружения. Секреты читаются из файлов (*_FILE), а не из env."""
import os
from pathlib import Path
def _read(name):
"""NAME_FILE (путь к секрету) имеет приоритет над NAME (прямое значение для локальной отладки)."""
path = os.environ.get(name + "_FILE")
if path:
return Path(path).read_text(encoding="utf-8").strip()
return os.environ.get(name) or None
def _int(name, default, low, high):
value = int(os.environ.get(name, default))
if not low <= value <= high:
raise ValueError("%s must be in %d..%d" % (name, low, high))
return value
APP_HOST = os.environ.get("APP_HOST", "0.0.0.0")
APP_PORT = _int("APP_PORT", 8080, 1, 65535)
APP_ENV = os.environ.get("APP_ENV", "lab")
SESSION_TTL_SECONDS = _int("SESSION_TTL_SECONDS", 3600, 1, 30 * 24 * 3600)
# postgres — сессии только в PostgreSQL;
# postgres+cache — PostgreSQL (источник истины) + read-through кэш в Redis/Valkey.
SESSION_STORE = os.environ.get("SESSION_STORE", "postgres+cache")
SESSION_CACHE_TTL_SECONDS = _int("SESSION_CACHE_TTL_SECONDS", 60, 1, 3600)
DATABASE_URL = _read("DATABASE_URL")
CACHE_URL = _read("CACHE_URL") if SESSION_STORE == "postgres+cache" else None
DB_POOL_MIN = _int("DB_POOL_MIN", 1, 0, 50)
DB_POOL_MAX = _int("DB_POOL_MAX", 16, 1, 50)
DB_POOL_TIMEOUT = float(os.environ.get("DB_POOL_TIMEOUT", "3")) # ожидание свободного соединения
DB_STATEMENT_TIMEOUT_MS = _int("DB_STATEMENT_TIMEOUT_MS", 5000, 100, 60000)
CACHE_TIMEOUT = float(os.environ.get("CACHE_TIMEOUT", "0.25")) # connect/read timeout кэша, сек
CACHE_BACKOFF = float(os.environ.get("CACHE_BACKOFF", "2")) # пауза после сбоя кэша, сек
# Параметры Argon2id (OWASP: m=19 MiB, t=2, p=1).
ARGON2_MEMORY_KIB = _int("ARGON2_MEMORY_KIB", 19456, 8, 1048576)
ARGON2_TIME_COST = _int("ARGON2_TIME_COST", 2, 1, 10)
MAX_BODY_BYTES = 64 * 1024
THREAD_LIMIT = _int("THREAD_LIMIT", 24, 1, 200) # потоков для sync-обработчиков FastAPI на процесс
HASH_CONCURRENCY = _int("HASH_CONCURRENCY", 4, 1, 32) # одновременных Argon2-операций на процесс (память!)
+26
View File
@@ -0,0 +1,26 @@
"""Непрозрачный keyset-курсор (created_at, id), привязанный к ресурсу."""
import base64
import json
from datetime import datetime, timezone
from .errors import bad_request
def encode(kind, scope, created_at, row_id):
payload = {"k": kind, "s": str(scope), "t": created_at.astimezone(timezone.utc).isoformat(), "i": str(row_id)}
return base64.urlsafe_b64encode(json.dumps(payload, separators=(",", ":")).encode()).rstrip(b"=").decode()
def decode(value, kind, scope):
"""Возвращает (created_at, id_str). Чужой чат/пользователь/вид курсора или мусор -> 400."""
import uuid
try:
raw = base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
payload = json.loads(raw.decode("utf-8"))
created_at = datetime.fromisoformat(payload["t"])
row_id = uuid.UUID(payload["i"])
if payload["k"] != kind or payload["s"] != str(scope) or created_at.tzinfo is None:
raise ValueError("scope mismatch")
return created_at, row_id
except (ValueError, KeyError, TypeError, UnicodeDecodeError):
raise bad_request("Некорректный cursor")
+57
View File
@@ -0,0 +1,57 @@
"""Пул соединений PostgreSQL: ограниченный размер, таймауты, проверка соединения при выдаче."""
import threading
import psycopg
from psycopg.rows import dict_row
from psycopg_pool import ConnectionPool, PoolClosed, PoolTimeout
from . import config
# Ошибки «зависимость недоступна/перегружена» -> 503, а не 500.
TRANSIENT = (psycopg.OperationalError, PoolTimeout, PoolClosed, psycopg.errors.QueryCanceled,
psycopg.errors.LockNotAvailable)
_pool = None
_lock = threading.Lock()
def get_pool():
"""Пул создаётся лениво в каждом worker-процессе (после fork), без ожидания БД при старте."""
global _pool
if _pool is None:
with _lock:
if _pool is None:
if not config.DATABASE_URL:
raise RuntimeError("DATABASE_URL(_FILE) is not configured")
options = ("-c statement_timeout=%d -c lock_timeout=3000 "
"-c idle_in_transaction_session_timeout=10000" % config.DB_STATEMENT_TIMEOUT_MS)
pool = ConnectionPool(
config.DATABASE_URL,
min_size=config.DB_POOL_MIN, max_size=config.DB_POOL_MAX,
timeout=config.DB_POOL_TIMEOUT, max_lifetime=1800, max_idle=300,
reconnect_timeout=5,
check=ConnectionPool.check_connection, # после рестарта PostgreSQL мёртвые соединения отбрасываются
kwargs={"row_factory": dict_row, "connect_timeout": 3, "options": options,
"application_name": "messenger-api"},
open=False)
pool.open(wait=False)
_pool = pool
return _pool
def connection(timeout=None):
"""Транзакция: COMMIT при выходе из with, ROLLBACK при исключении."""
return get_pool().connection(timeout=timeout)
def ping():
with connection(timeout=1.5) as conn:
conn.execute("SELECT 1")
def close():
"""Корректное закрытие пула при остановке процесса (SIGTERM)."""
global _pool
if _pool is not None:
_pool.close(timeout=5)
_pool = None
+21
View File
@@ -0,0 +1,21 @@
class ApiError(Exception):
def __init__(self, status, code, message, headers=None):
super().__init__(message)
self.status, self.code, self.message, self.headers = status, code, message, headers or {}
BASIC_CHALLENGE = {"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"'}
BEARER_CHALLENGE = {"WWW-Authenticate": 'Bearer realm="messenger"'}
def bad_request(message="Некорректный запрос"):
return ApiError(400, "invalid_request", message)
def unauthorized(challenge):
# Одно и то же сообщение для всех причин: не раскрываем, что именно не так.
return ApiError(401, "unauthorized", "Требуется аутентификация", challenge)
def not_found():
return ApiError(404, "not_found", "Объект не найден")
+62
View File
@@ -0,0 +1,62 @@
"""Версионируемые миграции: python -m app.migrate. Идемпотентно и безопасно при параллельном запуске."""
import hashlib
import logging
import sys
import time
from pathlib import Path
import psycopg
from . import config
LOCK_ID = 727_002_001 # произвольный константный ключ advisory-lock
log = logging.getLogger("migrate")
def migration_files():
return sorted((Path(__file__).parent / "migrations").glob("[0-9][0-9][0-9][0-9]_*.sql"))
def apply_all(conninfo):
files = migration_files()
# Всё выполняется в ОДНОЙ транзакции: либо все новые миграции, либо ни одной.
with psycopg.connect(conninfo, connect_timeout=3) as conn:
conn.execute("SELECT pg_advisory_xact_lock(%s)", (LOCK_ID,)) # параллельные мигрирующие процессы ждут друг друга
conn.execute("""CREATE TABLE IF NOT EXISTS schema_migrations (
version text PRIMARY KEY,
checksum text NOT NULL,
applied_at timestamptz NOT NULL DEFAULT now())""")
applied = dict(conn.execute("SELECT version, checksum FROM schema_migrations").fetchall())
done = []
for path in files:
sql = path.read_text(encoding="utf-8")
checksum = hashlib.sha256(sql.encode()).hexdigest()
if path.stem in applied:
if applied[path.stem] != checksum:
raise RuntimeError("migration %s was modified after being applied" % path.stem)
continue
conn.execute(sql)
conn.execute("INSERT INTO schema_migrations (version, checksum) VALUES (%s, %s)", (path.stem, checksum))
done.append(path.stem)
return done
def main():
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(message)s")
if not config.DATABASE_URL:
sys.exit("DATABASE_URL(_FILE) is not configured")
deadline = time.monotonic() + 60
while True:
try:
done = apply_all(config.DATABASE_URL)
break
except psycopg.OperationalError as exc: # БД ещё поднимается
if time.monotonic() > deadline:
raise
log.info("database not ready (%s), retrying", type(exc).__name__)
time.sleep(1)
log.info("applied: %s", ", ".join(done) if done else "nothing to do (schema is up to date)")
if __name__ == "__main__":
main()
+47
View File
@@ -0,0 +1,47 @@
-- 0001: пользователи, чаты, участники, сообщения.
-- Принципы: ограничения живут в БД (а не только в коде приложения), идентификаторы
-- генерирует приложение (UUIDv4), время ставит сервер БД (clock_timestamp()).
CREATE TABLE users (
id uuid PRIMARY KEY,
username text NOT NULL,
display_name text NOT NULL,
password_hash text NOT NULL, -- Argon2id (PHC string), никогда не отдаётся в API
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
CONSTRAINT users_username_key UNIQUE (username),
CONSTRAINT users_username_format CHECK (username ~ '^[a-z0-9_]{3,32}$'),
CONSTRAINT users_display_name_length CHECK (char_length(display_name) BETWEEN 1 AND 100)
);
CREATE TABLE chats (
id uuid PRIMARY KEY,
title text NOT NULL,
created_by uuid NOT NULL REFERENCES users (id),
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
CONSTRAINT chats_title_length CHECK (char_length(title) BETWEEN 1 AND 100)
);
-- Keyset-пагинация списка чатов по (created_at, id).
CREATE INDEX chats_created_at_id_idx ON chats (created_at, id);
CREATE TABLE chat_members (
chat_id uuid NOT NULL REFERENCES chats (id) ON DELETE CASCADE,
user_id uuid NOT NULL REFERENCES users (id),
added_at timestamptz NOT NULL DEFAULT clock_timestamp(),
PRIMARY KEY (chat_id, user_id)
);
-- «Какие чаты у пользователя?» — обратное направление к PK.
CREATE INDEX chat_members_user_chat_idx ON chat_members (user_id, chat_id);
CREATE TABLE messages (
id uuid PRIMARY KEY,
chat_id uuid NOT NULL,
sender_id uuid NOT NULL,
text text NOT NULL,
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
CONSTRAINT messages_text_length CHECK (char_length(text) BETWEEN 1 AND 4000),
-- Инвариант на уровне БД: писать в чат может только его участник.
CONSTRAINT messages_sender_is_member FOREIGN KEY (chat_id, sender_id)
REFERENCES chat_members (chat_id, user_id)
);
-- Индекс истории: равенство по chat_id + порядок (created_at, id) = ровно запрос keyset-страницы.
CREATE INDEX messages_chat_created_id_idx ON messages (chat_id, created_at, id);
+13
View File
@@ -0,0 +1,13 @@
-- 0002: серверные сессии. Источник истины — PostgreSQL; Redis/Valkey лишь кэш.
-- В БД лежит SHA-256 от токена, а не сам токен: утечка дампа не даёт готовых Bearer-токенов.
CREATE TABLE sessions (
token_hash bytea PRIMARY KEY,
user_id uuid NOT NULL REFERENCES users (id),
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
expires_at timestamptz NOT NULL,
CONSTRAINT sessions_hash_length CHECK (octet_length(token_hash) = 32),
CONSTRAINT sessions_expiry_after_creation CHECK (expires_at > created_at)
);
-- Выборка просроченных сессий при фоновой очистке.
CREATE INDEX sessions_expires_at_idx ON sessions (expires_at);
CREATE INDEX sessions_user_idx ON sessions (user_id);
+105
View File
@@ -0,0 +1,105 @@
"""Доступ к данным. Только параметризованные запросы (psycopg передаёт параметры отдельно от SQL)."""
import uuid
from . import cursor, security
from .errors import bad_request
from .sessions import fmt_ts
def username_exists(conn, username):
return conn.execute("SELECT 1 FROM users WHERE username = %s", (username,)).fetchone() is not None
def insert_user(conn, username, display_name, password_hash):
return conn.execute(
"""INSERT INTO users (id, username, display_name, password_hash) VALUES (%s, %s, %s, %s)
RETURNING id, username, display_name, created_at""",
(uuid.uuid4(), username, display_name, password_hash)).fetchone()
def user_for_login(conn, username):
return conn.execute("SELECT id, username, display_name, password_hash, created_at FROM users WHERE username = %s",
(username,)).fetchone()
def update_password_hash(conn, user_id, new_hash):
conn.execute("UPDATE users SET password_hash = %s WHERE id = %s", (new_hash, user_id))
def chat_json(row):
return {"id": str(row["id"]), "title": row["title"], "member_ids": [str(x) for x in row["member_ids"]],
"created_at": fmt_ts(row["created_at"])}
def create_chat(conn, creator_id, title, member_ids, check_members=True):
"""Составная операция (users -> chats -> chat_members) в транзакции вызывающего.
Любая ошибка после вставки chats откатывает ВСЁ: чат без участников не появится.
check_members=False нужен только тесту отката: FK на chat_members сработает уже после вставки чата.
"""
if check_members:
found = conn.execute("SELECT count(*) AS n FROM users WHERE id = ANY(%s)", (member_ids,)).fetchone()["n"]
if found != len(member_ids):
raise bad_request("Неизвестный участник чата")
chat = conn.execute(
"INSERT INTO chats (id, title, created_by) VALUES (%s, %s, %s) RETURNING id, title, created_at",
(uuid.uuid4(), title, creator_id)).fetchone()
conn.execute("INSERT INTO chat_members (chat_id, user_id) SELECT %s, unnest(%s::uuid[])",
(chat["id"], member_ids))
chat["member_ids"] = sorted(member_ids)
return chat
def get_chat(conn, chat_id, user_id):
"""Чат + список участников, только если user_id — участник (иначе None => 404)."""
return conn.execute(
"""SELECT c.id, c.title, c.created_at,
ARRAY(SELECT m.user_id FROM chat_members m WHERE m.chat_id = c.id ORDER BY m.user_id) AS member_ids
FROM chats c
WHERE c.id = %s AND EXISTS (SELECT 1 FROM chat_members me WHERE me.chat_id = c.id AND me.user_id = %s)""",
(chat_id, user_id)).fetchone()
def is_member(conn, chat_id, user_id):
return conn.execute("SELECT 1 FROM chat_members WHERE chat_id = %s AND user_id = %s",
(chat_id, user_id)).fetchone() is not None
def list_chats(conn, user_id, after, limit):
base = """SELECT c.id, c.title, c.created_at,
ARRAY(SELECT m.user_id FROM chat_members m WHERE m.chat_id = c.id ORDER BY m.user_id) AS member_ids
FROM chat_members me JOIN chats c ON c.id = me.chat_id
WHERE me.user_id = %s"""
params = [user_id]
if after:
base += " AND (c.created_at, c.id) > (%s, %s)"
params += list(after)
rows = conn.execute(base + " ORDER BY c.created_at, c.id LIMIT %s", params + [limit + 1]).fetchall()
page, more = rows[:limit], len(rows) > limit
nxt = cursor.encode("chats", user_id, page[-1]["created_at"], page[-1]["id"]) if more else None
return [chat_json(r) for r in page], nxt
def message_json(row):
return {"id": str(row["id"]), "chat_id": str(row["chat_id"]), "sender_id": str(row["sender_id"]),
"text": row["text"], "created_at": fmt_ts(row["created_at"])}
def insert_message(conn, chat_id, sender_id, text):
return conn.execute(
"""INSERT INTO messages (id, chat_id, sender_id, text) VALUES (%s, %s, %s, %s)
RETURNING id, chat_id, sender_id, text, created_at""",
(uuid.uuid4(), chat_id, sender_id, text)).fetchone()
def list_messages(conn, chat_id, after, limit):
"""Keyset: WHERE (created_at, id) > курсор ORDER BY created_at, id LIMIT n+1 — идёт по индексу, без OFFSET."""
sql = "SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id = %s"
params = [chat_id]
if after:
sql += " AND (created_at, id) > (%s, %s)"
params += list(after)
rows = conn.execute(sql + " ORDER BY created_at, id LIMIT %s", params + [limit + 1]).fetchall()
page, more = rows[:limit], len(rows) > limit
nxt = cursor.encode("messages", chat_id, page[-1]["created_at"], page[-1]["id"]) if more else None
return [message_json(r) for r in page], nxt
+77
View File
@@ -0,0 +1,77 @@
"""Пароли (Argon2id), токены, разбор заголовка Authorization."""
import base64
import binascii
import hashlib
import re
import secrets
import threading
from argon2 import PasswordHasher, Type
from argon2.exceptions import InvalidHashError, VerificationError
from . import config
_hasher = PasswordHasher(time_cost=config.ARGON2_TIME_COST, memory_cost=config.ARGON2_MEMORY_KIB,
parallelism=1, hash_len=32, salt_len=16, type=Type.ID)
# Хеш-заглушка: при неизвестном username всё равно тратим время на verify -> нет timing-оракула «есть ли такой логин».
_DUMMY_HASH = _hasher.hash("dummy-password-for-constant-time")
# Каждая операция Argon2 держит ~19 МиБ: ограничиваем параллелизм, иначе всплеск входов исчерпает память контейнера.
_hash_slots = threading.BoundedSemaphore(config.HASH_CONCURRENCY)
_TOKEN_RE = re.compile(r"[A-Za-z0-9._~+/=-]{16,512}")
def hash_password(password):
with _hash_slots:
return _hasher.hash(password) # UTF-8 пароля целиком, без усечения; соль генерируется библиотекой
def verify_password(stored_hash, password):
"""(ok, new_hash_or_None). new_hash — если параметры KDF устарели и хеш надо обновить."""
with _hash_slots:
try:
_hasher.verify(stored_hash, password)
except (VerificationError, InvalidHashError):
return False, None
return True, (_hasher.hash(password) if _hasher.check_needs_rehash(stored_hash) else None)
def burn_verify(password):
with _hash_slots:
try:
_hasher.verify(_DUMMY_HASH, password)
except VerificationError:
pass
def new_token():
return secrets.token_urlsafe(32) # 32 байта CSPRNG = 256 бит энтропии
def token_hash(token):
# Токен уже высокоэнтропийный, поэтому быстрый SHA-256 достаточен (в отличие от паролей, где нужен медленный KDF).
return hashlib.sha256(token.encode("ascii")).digest()
def parse_basic(header):
"""Возвращает (username, password) или None. Любой дефект -> None (одинаковый 401)."""
if not header:
return None
scheme, _, rest = header.partition(" ")
if scheme.lower() != "basic":
return None
try:
text = base64.b64decode(rest.strip(), validate=True).decode("utf-8")
except (binascii.Error, UnicodeDecodeError, ValueError):
return None
username, sep, password = text.partition(":") # двоеточие допустимо в пароле: делим по ПЕРВОМУ
return (username, password) if sep else None
def parse_bearer(header):
if not header:
return None
scheme, _, rest = header.partition(" ")
token = rest.strip()
if scheme.lower() != "bearer" or not _TOKEN_RE.fullmatch(token):
return None
return token
+86
View File
@@ -0,0 +1,86 @@
"""Сессии: PostgreSQL — источник истины, Redis/Valkey — read-through кэш (cache-aside).
Чтение: кэш -> (промах) -> PostgreSQL -> наполнение кэша с TTL = min(SESSION_CACHE_TTL, остаток жизни).
Отзыв: DELETE в PostgreSQL (commit) -> tombstone в кэше (SET), чтобы медленный параллельный reader
не воскресил сессию через SET NX. Потеря/сброс кэша ничего не ломает: данные берутся из PostgreSQL.
"""
import json
import time
from datetime import timezone
from . import cache, config, db, security
TOMBSTONE = "revoked"
_KEY = "sess:v1:"
def fmt_ts(value):
return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
def user_json(row):
return {"id": str(row["id"]), "username": row["username"], "display_name": row["display_name"],
"created_at": fmt_ts(row["created_at"])}
def _ttl_ms(expires_epoch):
remaining = expires_epoch - time.time()
return int(min(config.SESSION_CACHE_TTL_SECONDS, remaining) * 1000) if remaining > 0 else 0
def create(conn, user_row):
"""Выдать токен; запись о сессии коммитится вместе с транзакцией вызывающего."""
token = security.new_token()
row = conn.execute(
"""INSERT INTO sessions (token_hash, user_id, expires_at)
VALUES (%s, %s, clock_timestamp() + make_interval(secs => %s))
RETURNING expires_at""",
(security.token_hash(token), user_row["id"], config.SESSION_TTL_SECONDS)).fetchone()
# Опортунистическая очистка: старые просроченные строки (не более 100 за вход).
conn.execute("""DELETE FROM sessions WHERE token_hash IN (
SELECT token_hash FROM sessions WHERE expires_at < now() - interval '1 hour' LIMIT 100)""")
return token, row["expires_at"]
def warm(token, user, expires_at):
entry = {"user": user, "exp": expires_at.timestamp()}
ttl = _ttl_ms(entry["exp"])
if ttl > 0:
cache.set_if_absent(_KEY + security.token_hash(token).hex(), json.dumps(entry), ttl)
def lookup(token):
"""-> {'user': {...}} либо None (неизвестная/истёкшая/отозванная сессия). Исключения БД -> 503 выше."""
digest = security.token_hash(token)
key = _KEY + digest.hex()
cached = cache.get(key)
if cached == TOMBSTONE:
return None
if cached:
try:
entry = json.loads(cached)
if entry["exp"] > time.time(): # срок проверяем и по кэшу: expiry не зависит от TTL ключа
return {"user": entry["user"], "digest": digest}
return None
except (ValueError, KeyError, TypeError):
pass # битая запись = промах
with db.connection() as conn:
row = conn.execute(
"""SELECT u.id, u.username, u.display_name, u.created_at,
extract(epoch FROM s.expires_at) AS exp
FROM sessions s JOIN users u ON u.id = s.user_id
WHERE s.token_hash = %s AND s.expires_at > clock_timestamp()""", (digest,)).fetchone()
if row is None:
return None # отрицательные результаты не кэшируем (защита от забивания кэша)
user = user_json(row)
ttl = _ttl_ms(float(row["exp"]))
if ttl > 0:
cache.set_if_absent(key, json.dumps({"user": user, "exp": float(row["exp"])}), ttl)
return {"user": user, "digest": digest}
def revoke(digest):
with db.connection() as conn:
conn.execute("DELETE FROM sessions WHERE token_hash = %s", (digest,))
# Только ПОСЛЕ commit: иначе читатель мог бы заново закэшировать ещё живую сессию.
cache.set_always(_KEY + digest.hex(), TOMBSTONE, config.SESSION_CACHE_TTL_SECONDS * 1000)
+84
View File
@@ -0,0 +1,84 @@
"""Строгая валидация входа: никаких лишних полей, типов-«почти», NUL и суррогатов."""
import json
import re
import uuid
from .errors import ApiError, bad_request
_UUID_RE = re.compile(r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}")
_USERNAME_RE = re.compile(r"[a-z0-9_]{3,32}") # fullmatch: «$» в Python пропускает завершающий \n!
_INT_RE = re.compile(r"[0-9]{1,6}")
def parse_uuid(value):
if isinstance(value, str) and _UUID_RE.fullmatch(value):
return uuid.UUID(value)
return None
def require_uuid(value, name="id"):
parsed = parse_uuid(value)
if parsed is None:
raise bad_request("Некорректный %s" % name)
return parsed
def _reject_constant(name):
raise ValueError("non-finite number")
def _no_duplicates(pairs):
result = {}
for key, value in pairs:
if key in result:
raise ValueError("duplicate key")
result[key] = value
return result
def json_body(content_type, raw, allowed, required):
"""content_type — значение заголовка; raw — тело (размер уже ограничен при чтении -> 413)."""
if content_type.split(";")[0].strip().lower() != "application/json":
raise ApiError(415, "unsupported_media_type", "Ожидается Content-Type: application/json")
try:
data = json.loads(raw.decode("utf-8"), parse_constant=_reject_constant, object_pairs_hook=_no_duplicates)
except (ValueError, UnicodeDecodeError, RecursionError):
raise bad_request("Некорректный JSON")
if not isinstance(data, dict) or set(data) - set(allowed) or not set(required) <= set(data):
raise bad_request("Некорректный набор полей")
return data
def text_field(value, name, low, high, allow_blank=False):
if not isinstance(value, str):
raise bad_request("Поле %s должно быть строкой" % name)
if "\x00" in value or not _encodable(value):
raise bad_request("Поле %s содержит недопустимые символы" % name)
if not low <= len(value) <= high: # len(str) в Python = число Unicode code points
raise bad_request("Поле %s: длина должна быть %d–%d" % (name, low, high))
if not allow_blank and not value.strip():
raise bad_request("Поле %s не должно состоять только из пробелов" % name)
return value
def _encodable(value):
try:
value.encode("utf-8")
return True
except UnicodeEncodeError: # одиночные суррогаты из "\ud800"
return False
def username_field(value):
if not isinstance(value, str) or not _USERNAME_RE.fullmatch(value):
raise bad_request("username должен соответствовать [a-z0-9_]{3,32}")
return value
def limit_param(params):
raw = params.get("limit")
if raw is None:
return 50
if not _INT_RE.fullmatch(raw) or not 1 <= int(raw) <= 100:
raise bad_request("limit должен быть целым числом 1–100")
return int(raw)
+10
View File
@@ -0,0 +1,10 @@
# Topology worksheet, deliberately NOT a runnable stack (no application supplied).
# Implement compose.yaml or stack.yaml; do not submit this empty file as deployment.
# Service names below are logical roles, not imposed container names.
x-lab-number: 2
x-required-roles:
- api
- postgres
# TODO: implement real images/builds, network wiring, volumes, healthchecks,
# credentials and bootstrap. Details: contracts/infrastructure.json and README.md.
services: {}
+103
View File
@@ -0,0 +1,103 @@
# Локальный стенд лабораторной 2: API + PostgreSQL + Valkey (кэш сессий).
# Порядок запуска: sh scripts/init-secrets.sh && docker compose --env-file .env up -d --build
name: messenger-lab2
x-app-env: &app-env
APP_HOST: "0.0.0.0"
APP_PORT: "8080"
APP_ENV: ${APP_ENV:-lab}
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
SESSION_STORE: ${SESSION_STORE:-postgres+cache}
SESSION_CACHE_TTL_SECONDS: ${SESSION_CACHE_TTL_SECONDS:-60}
DATABASE_URL_FILE: /run/secrets/database_url # секреты — файлами, не переменными окружения
CACHE_URL_FILE: /run/secrets/cache_url
services:
postgres: # источник истины: users/chats/members/messages/sessions
image: postgres:17.6-alpine
ports:
- "127.0.0.1:5433:5432" # временно открыт для track2_indexes.py
restart: unless-stopped
environment:
POSTGRES_DB: messenger
POSTGRES_USER: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
secrets: [postgres_password]
command: ["postgres", "-c", "fsync=on", "-c", "synchronous_commit=on", "-c", "full_page_writes=on",
"-c", "max_connections=100"] # durability явно: COMMIT = WAL сброшен на диск
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"]
interval: 3s
timeout: 3s
retries: 20
stop_grace_period: 30s
networks: [backend]
valkey: # кэш сессий (read-through); истина — PostgreSQL
image: valkey/valkey:8.1.3-alpine
restart: unless-stopped
secrets: [valkey_password]
command:
- sh
- -c
- >-
exec valkey-server --requirepass "$$(cat /run/secrets/valkey_password)"
--appendonly yes --appendfsync everysec --save ""
--maxmemory 64mb --maxmemory-policy volatile-ttl
volumes:
- valkeydata:/data
healthcheck:
test: ["CMD-SHELL", "REDISCLI_AUTH=\"$$(cat /run/secrets/valkey_password)\" valkey-cli ping | grep -q PONG"]
interval: 3s
timeout: 3s
retries: 20
networks: [backend]
migrate: # одноразово применяет миграции; идемпотентен
build: .
command: ["python", "-m", "app.migrate"]
environment: *app-env
secrets: [database_url, cache_url]
depends_on:
postgres: {condition: service_healthy}
restart: "no"
networks: [backend]
api:
build: .
restart: unless-stopped
environment: *app-env
secrets: [database_url, cache_url]
depends_on:
migrate: {condition: service_completed_successfully}
postgres: {condition: service_healthy}
valkey: {condition: service_started} # кэш не критичен: API стартует и без него
ports:
- "127.0.0.1:8080:8080" # единственный опубликованный порт, только localhost
read_only: true
tmpfs: ["/tmp", "/dev/shm"]
cap_drop: [ALL]
security_opt: ["no-new-privileges:true"]
healthcheck: # readiness: API + PostgreSQL
test: ["CMD", "python", "-c", "import urllib.request as u; u.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)"]
interval: 3s
timeout: 3s
retries: 20
start_period: 5s
stop_grace_period: 25s
networks: [backend]
networks:
backend: {}
volumes: # именованные: переживают stop/restart/down (но не down -v)
pgdata: {}
valkeydata: {}
secrets:
postgres_password: {file: ./secrets/postgres_password}
valkey_password: {file: ./secrets/valkey_password}
database_url: {file: ./secrets/database_url}
cache_url: {file: ./secrets/cache_url}
+61
View File
@@ -0,0 +1,61 @@
# Семантика API
Этот текст дополняет [openapi.json](openapi.json). Обязательный API соответствует уровню 3 текущей лабораторной. Факультативный crop или rate limiting не становятся обязательными только из-за наличия допустимого имени варианта или кода ошибки в схеме.
## Формат и ошибки
- JSON — UTF-8, `Content-Type: application/json`. UUID — строка; время — RFC 3339 UTC с `Z`, назначается сервером. Часы не считаются уникальным ID.
- Каждый ответ API, включая ошибки и health, содержит непустой `X-Request-Id`. Тело ошибки: `{"error":{"code":"invalid_request","message":"...","request_id":"..."}}`; `request_id` совпадает с заголовком. Сообщение ошибки не раскрывает stack trace, SQL, credentials или наличие чужого объекта.
- Обязательные строки не состоят только из пробельных символов. `username` строго `[a-z0-9_]{3,32}`, уникален; `display_name` — 1–100 Unicode code points. JSON с лишними полями или неверными типами — `400`; malformed JSON также `400`.
- `400 invalid_request` — неверные поля, UUID, cursor, limit; `401 unauthorized` — нет действительной идентификации/сессии; `404 not_found` — объекта нет или он чужой; `409 conflict` — username занят, повторный ключ с другим сообщением, объект ещё не готов; `413 payload_too_large`; `415 unsupported_media_type`; `429 rate_limited`; `503 unavailable`. Неожиданное исключение — `500 internal_error` без внутренних деталей.
- Сначала аутентификация, затем доступ к конкретному ресурсу. Любой аутентифицированный участник чата может читать его историю и вложения и писать в него; посторонний получает `404`. Списки содержат только доступные объекты. Не используйте `403` для раскрытия существования чужого чата.
- `GET /health/live` проверяет только жизнь процесса, возвращает `200 {"status":"ok"}`. `GET /health/ready` возвращает 200, если приложение может безопасно обслуживать обязательный синхронный путь; иначе 503 в общем формате ошибки. Какие зависимости критичны, зафиксируйте в отчёте; недоступность Grafana не должна останавливать API.
## Пользователи, чаты и сообщения
- `POST /users` публичен; возвращает `201 User`. Пароль/его hash и сессионные данные никогда не входят в User.
- `POST /chats` принимает title и явный список существующих `member_ids`, включая вызывающего. Дубликаты, неизвестные участники и отсутствие вызывающего — 400. Чат создаётся атомарно. GET списка чатов сортируется по `(created_at, id)` по возрастанию.
- Отправитель сообщения выводится из текущей идентификации, поле `sender_id` в запросе не принимается. Текст — до 4000 Unicode code points. Нельзя отправить пустой/пробельный текст без вложений.
- История использует keyset cursor: `(created_at, id)`, по возрастанию; `limit` — целое 1–100, по умолчанию 50. Ответ `{"items":[...],"next_cursor":null}`. Непустой cursor — непрозрачная для клиента строка; последний элемент предыдущей страницы не повторяется. Cursor привязан к ресурсу/запросу: от другого чата — 400. Изменять `limit` при продолжении можно.
- `next_cursor` равен null, если на момент чтения следующей записи нет. Гарантируется отсутствие повторов при обходе неизменной истории; snapshot изоляция между несколькими HTTP-запросами не требуется. При конкурентных вставках опишите выбранную семантику и ограничения часов.
- Подтверждённое сообщение видно следующему чтению через любую API-реплику. Допускается кэш, но он не должен возвращать устаревшую историю после успешной записи. Удаление и изменение участников в обязательный API не входят.
## Идентификация и сессии
**Lab1:** защищённые endpoint требуют `X-User-Id: <UUID существующего пользователя>`; отсутствие/неизвестный ID — 401. Это учебный выбор пользователя: любой клиент может выдать себя за другого.
**Lab2–7:** `POST /auth/sessions` принимает только `Authorization: Basic <base64(username:password)>`, без JSON body. Username ограничен ASCII; пароль кодируется UTF-8, 12–128 code points, двоеточие в пароле допустимо. Неверные credentials — одинаковый 401 и `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`.
Вход возвращает `201 {"token":"...","token_type":"Bearer","expires_at":"...Z","user":{...}}`. Токен — непрозрачное случайное значение, не username/UUID и не обязательный JWT; энтропия не менее 256 бит. Храните серверную сессию с expiry; TTL задаётся `SESSION_TTL_SECONDS`, по умолчанию 3600 (в тесте истечения можно 2). В обычном smoke TTL должен быть не менее 300.
Все защищённые endpoint принимают только `Authorization: Bearer <token>`. Истёкший/отозванный/неизвестный токен — 401 с `WWW-Authenticate: Bearer realm="messenger"`. Basic на бизнес-endpoint — 401. `X-User-Id` с lab2 игнорируется: он не меняет владельца сессии и сам по себе не даёт доступ. `DELETE /auth/sessions/current` отзывает текущий токен и возвращает 204 без тела; повтор с отозванным токеном — 401.
Пользователи, чаты, сообщения и ещё действительные сессии переживают перезапуск приложения и используемых хранилищ с сохранёнными volumes. TTL не продлевается из-за рестарта. Пароли уже с lab2 хешируются библиотечным password KDF (Argon2id, scrypt или bcrypt с учётом ограничений библиотеки), не SHA-256 и не plaintext. Если bcrypt не поддерживает весь диапазон UTF-8 паролей без усечения, выберите другую библиотечную схему. В lab7 обязателен Argon2id.
Basic — это кодирование, не шифрование. HTTP lab1–6 допускается только для локального изолированного стенда с синтетическими данными; для удалённой демонстрации нужен TLS. Lab7 использует HTTPS обязательно. См. [RFC 7617](https://www.rfc-editor.org/info/rfc7617/).
## Балансировка и повторная отправка (с lab3)
- Каждый ответ, созданный API, содержит `X-Instance-Id`; значение стабильно для жизни процесса. Ошибки соединения, созданные самим LB, могут не иметь этого заголовка. В lab7 используйте случайный alias реплики без раскрытия hostname/IP.
- Для POST сообщения обязателен `Idempotency-Key` (ASCII `[A-Za-z0-9._:-]{1,128}`). Нет/неверный ключ — 400. Область уникальности: текущий пользователь + HTTP-метод + путь чата + ключ.
- При повторе того же валидного JSON в течение 24 часов сервер возвращает тот же код 201 и то же Message. Порядок ключей JSON и отсутствующий `attachment_ids` вместо `[]` семантически равны. Другой body при том же ключе — 409. Разные пользователи/чаты могут использовать одинаковый ключ независимо.
- Одновременные повторы через разные реплики создают ровно одно сообщение. Повтор снова проверяет действительность сессии и доступ. Транзиентные 5xx не фиксируются как окончательный результат; побочный эффект и запись результата должны быть атомарны.
- Ключ обязателен только для сообщений. Самостоятельный retry загрузки файла или создания чата может создать ещё один объект; не добавляйте прозрачные повторы этих POST без расширения контракта.
## Вложения (с lab4)
- `POST /chats/{chat_id}/attachments?filename=photo.png`: сырые bytes одного PNG/JPEG; `Content-Type: image/png` или `image/jpeg`. Не multipart. Максимум **10 MiB = 10 485 760 байт**. MIME проверяется по содержимому; заведомо повреждённые/чужие форматы — 415, превышение bytes — 413. Не более 40 миллионов декодированных пикселей (превышение — 413). Устанавливайте лимит до полной распаковки изображения.
- `filename` — отображаемое имя (1–255 code points). Не используйте его как путь/ключ S3. Имя с `/`, `\`, NUL или управляющими символами — 400. Bucket приватен; object key генерирует сервер. Оригинал возвращается побайтно, его lowercase SHA-256 и размер соответствуют исходному файлу.
- Lab4 возвращает `201 Attachment` со `status=ready`, `variants=[]`, `error_code=null` только после сохранения оригинала и метаданных. Lab5–7 возвращают `202 Attachment` со снимком `status=queued`; готовность определяется последующим GET метаданных. Быстрый worker может закончить до первого GET — это нормально.
- Файл заранее привязан к чату. В POST сообщения добавляется `attachment_ids` (0–10 уникальных ID, по умолчанию []). Можно отправить `text=""` с хотя бы одним вложением. Все вложения должны принадлежать этому чату; чужое/неизвестное — 404. Любой участник может ссылаться на доступное вложение чата. Failed-вложение прикреплять нельзя (409); queued/processing с lab5 можно.
- `GET /attachments/{id}` и `/content` доступны только участникам чата. Download возвращает байты с истинным Content-Type, через авторизованный API, **без redirect** в обязательном контракте. Приватный bucket сам по себе не заменяет эту проверку. `variant` по умолчанию original. Для queued/processing content — 409; для failed — 409. Отсутствующий вариант ready-объекта — 404.
- В ready-метаданных `error_code=null`. В failed — краткий машинный код (например `invalid_image`, `processing_failed`, `retry_exhausted`), без stack trace. `size_bytes`, `sha256`, `content_type` всегда описывают оригинал; у вариантов отдельные поля. Публичный API не раскрывает ключи бакета, внутренние адреса и credentials.
- Прямой upload/download по временной подписи — факультативное расширение. Его дополняют ограничение срока/размера, уникальный ключ и подтверждение реально загруженного объекта; он не заменяет стандартный endpoint. Особенности подписанных URL: [S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html).
## Фоновая обработка (с lab5)
До 202 все байты приняты в **устойчивый staging**, а намерение обработать файл надёжно сохранено. HTTP-передача клиента не исчезает и не становится мгновенной. Staging — приватный S3-prefix либо общий persistent volume, доступный worker; локальная память/API ephemeral disk не подходит. Worker асинхронно переносит/публикует оригинал в конечный S3-prefix и создаёт варианты; если staging уже в S3, опишите эту границу честно.
Обязательный thumbnail: JPEG, изображение вписано в 256×256 с сохранением пропорций, без увеличения маленьких исходников, EXIF orientation применяется; alpha компонуется на белый. Размеры округляются вниз, минимум 1 px. Fixture 320×200 должен дать 256×160. Статус ready ставится после сохранения оригинала и thumbnail. Crop на 4: JPEG, центрированный квадрат 128×128 (для маленьких исходников допускается увеличение). Optimized на 4: WebP, вписан в 1280×1280 без увеличения, параметры качества и удаления EXIF документируются; не обещайте уменьшение каждого маленького файла.
Допустимые состояния и события описаны в `jobs.schema.json` и `attachment-states.md`. Доставка — at least once; обработка идемпотентна, повторы не размножают варианты. Финальные ошибки наблюдаемы, бесконечный немой retry недопустим. Обязательный smoke ждёт ready до 60 секунд; это бюджет локального smoke для одного файла при свободном worker, не универсальный production SLA. В очередь идут ссылки/ID, не бинарное содержимое.
+58
View File
@@ -0,0 +1,58 @@
{
"CreateUser": {
"username": "alice",
"display_name": "Алиса",
"password": "Example-only-not-a-real-secret-123"
},
"User": {
"id": "11111111-1111-4111-8111-111111111111",
"username": "alice",
"display_name": "Алиса",
"created_at": "2026-09-01T12:00:00Z"
},
"CreateChat": {
"title": "Проект по ВНП",
"member_ids": [
"11111111-1111-4111-8111-111111111111",
"22222222-2222-4222-8222-222222222222"
]
},
"Chat": {
"title": "Проект по ВНП",
"member_ids": [
"11111111-1111-4111-8111-111111111111",
"22222222-2222-4222-8222-222222222222"
],
"id": "33333333-3333-4333-8333-333333333333",
"created_at": "2026-09-01T12:00:00Z"
},
"CreateMessage": {
"text": "Привет, Боб!"
},
"Message": {
"id": "44444444-4444-4444-8444-444444444444",
"chat_id": "33333333-3333-4333-8333-333333333333",
"sender_id": "11111111-1111-4111-8111-111111111111",
"text": "Привет, Боб!",
"created_at": "2026-09-01T12:00:00Z"
},
"MessagePage": {
"items": [
{
"id": "44444444-4444-4444-8444-444444444444",
"chat_id": "33333333-3333-4333-8333-333333333333",
"sender_id": "11111111-1111-4111-8111-111111111111",
"text": "Привет, Боб!",
"created_at": "2026-09-01T12:00:00Z"
}
],
"next_cursor": null
},
"Error": {
"error": {
"code": "not_found",
"message": "Объект не найден",
"request_id": "example-request-id"
}
}
}
+31
View File
@@ -0,0 +1,31 @@
{
"lab": 2,
"kind": "requirements, not runnable deployment",
"required_for_grade_3": [
{
"role": "api",
"count_min": 1,
"student_implements": true,
"persistent_local_state": false
},
{
"role": "postgres",
"purpose": "users/chats/membership/messages/metadata",
"persistent_volume": true
}
],
"optional_components": [
{
"role": "redis_or_valkey",
"required_for_lab2_grade4": true,
"note": "Choose one; if only store of sessions, configure durable persistence."
}
],
"rules": [
"Choose Compose or Swarm for lab3+; do not need both.",
"Never publish internal API replica ports in bypass of LB from lab3.",
"Versions/digests must be fixed in implementation.",
"Do not remove volumes in restart/failover checks.",
"Document service names, healthchecks, bootstrap/migrations and credentials."
]
}
File diff suppressed because it is too large Load Diff
+5
View File
@@ -0,0 +1,5 @@
# Доказательства
Храните небольшие обезличенные результаты: команды и stdout проверок, JSON/CSV агрегатов нагрузки, EXPLAIN, dashboard JSON, текст разбора отказа. Укажите дату, commit, аппаратные лимиты и профиль нагрузки.
Не добавляйте .env, session tokens, cookies, приватные ключи, credentials, реальные сообщения, raw dumps и signed URLs. Для скриншотов скрывайте секреты. Большие логи/бинарные traces сохраняйте отдельно по правилам преподавателя; одного скриншота без методики недостаточно.
+9
View File
@@ -0,0 +1,9 @@
# Роль Redis/Valkey: read-through кэш сессий (источник истины — PostgreSQL)
число ключей sess:v1:*: 3
пример ключа (хеш токена, не токен): sess:v1:db24de3dbb236846...
PTTL, мс (≤ SESSION_CACHE_TTL_SECONDS*1000 = 60000): 44231
поля значения: ['exp', 'user'] / user: ['created_at', 'display_name', 'id', 'username']
есть ли password/hash/token в значении: False
после logout значение ключа (tombstone): revoked
после FLUSHALL ключей: 0
сессия работает после FLUSHALL (из PostgreSQL), кэш наполнился заново, ключей: 1
+11
View File
@@ -0,0 +1,11 @@
# Зависимости: Redis (кэш сессий) и PostgreSQL; команды управления — песочничные (в стенде — docker compose stop/start)
1) Valkey остановлен
$ CACHE_STOP
$ CACHE_START
2) Кэш сброшен (FLUSHALL): сессии берутся из PostgreSQL
$ CACHE_FLUSH
3) PostgreSQL остановлен
$ DB_STOP
$ DB_START
4) Восстановление
PASS: кэш и БД отказывают предсказуемо: кэш обходится, БД -> 503, анонимный доступ невозможен, данные и сессии целы
+85
View File
@@ -0,0 +1,85 @@
rows total=100000, rows in target chat=20000, page=50
PostgreSQL 16.15 (Ubuntu 16.15-0ubuntu0.24.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
====================================================================================================
A. Первая страница, keyset, С индексом (chat_id, created_at, id)
====================================================================================================
Limit (cost=0.42..14.81 rows=51 width=69) (actual time=0.010..0.021 rows=51 loops=1)
Buffers: shared hit=4
-> Index Scan using messages_chat_created_id_idx on messages (cost=0.42..5670.87 rows=20093 width=69) (actual time=0.009..0.016 rows=51 loops=1)
Index Cond: (chat_id = '010619e6-7ff5-46b1-877c-03368e85f10b'::uuid)
Buffers: shared hit=4
Planning:
Buffers: shared hit=6
Planning Time: 0.063 ms
Execution Time: 0.032 ms
====================================================================================================
B. Страница на глубине ~15 000, keyset, С индексом
====================================================================================================
Limit (cost=0.42..48.66 rows=51 width=69) (actual time=0.011..0.021 rows=51 loops=1)
Buffers: shared hit=4
-> Index Scan using messages_chat_created_id_idx on messages (cost=0.42..4756.71 rows=5028 width=69) (actual time=0.011..0.016 rows=51 loops=1)
Index Cond: ((chat_id = '010619e6-7ff5-46b1-877c-03368e85f10b'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 20:50:05.000522+00'::timestamp with time zone, 'f47f8dd1-aaae-4701-a00d-6e20a06648e3'::uuid)))
Buffers: shared hit=4
Planning Time: 0.059 ms
Execution Time: 0.044 ms
====================================================================================================
C. Та же страница, keyset, БЕЗ индекса (индекс удалён в откатываемой транзакции)
====================================================================================================
Limit (cost=3152.74..3152.87 rows=51 width=69) (actual time=9.057..9.066 rows=51 loops=1)
Buffers: shared hit=1235
-> Sort (cost=3152.74..3165.31 rows=5028 width=69) (actual time=9.056..9.060 rows=51 loops=1)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 31kB
Buffers: shared hit=1235
-> Seq Scan on messages (cost=0.00..2985.00 rows=5028 width=69) (actual time=1.098..8.625 rows=4999 loops=1)
Filter: ((chat_id = '010619e6-7ff5-46b1-877c-03368e85f10b'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 20:50:05.000522+00'::timestamp with time zone, 'f47f8dd1-aaae-4701-a00d-6e20a06648e3'::uuid)))
Rows Removed by Filter: 95001
Buffers: shared hit=1235
Planning:
Buffers: shared hit=4
Planning Time: 0.065 ms
Execution Time: 9.081 ms
====================================================================================================
D. Та же глубина через OFFSET 15000, С индексом (антипример)
====================================================================================================
Limit (cost=3958.59..3958.71 rows=51 width=69) (actual time=10.512..10.519 rows=51 loops=1)
Buffers: shared hit=1235
-> Sort (cost=3921.09..3971.32 rows=20093 width=69) (actual time=9.103..9.920 rows=15051 loops=1)
Sort Key: created_at, id
Sort Method: quicksort Memory: 3271kB
Buffers: shared hit=1235
-> Seq Scan on messages (cost=0.00..2485.00 rows=20093 width=69) (actual time=0.003..6.416 rows=20000 loops=1)
Filter: (chat_id = '010619e6-7ff5-46b1-877c-03368e85f10b'::uuid)
Rows Removed by Filter: 80000
Buffers: shared hit=1235
Planning:
Buffers: shared hit=22
Planning Time: 0.101 ms
Execution Time: 10.643 ms
====================================================================================================
E. Первая страница, БЕЗ индекса
====================================================================================================
Limit (cost=3155.35..3155.47 rows=51 width=69) (actual time=7.702..7.709 rows=51 loops=1)
Buffers: shared hit=1235
-> Sort (cost=3155.35..3205.58 rows=20093 width=69) (actual time=7.701..7.704 rows=51 loops=1)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 31kB
Buffers: shared hit=1235
-> Seq Scan on messages (cost=0.00..2485.00 rows=20093 width=69) (actual time=0.004..6.070 rows=20000 loops=1)
Filter: (chat_id = '010619e6-7ff5-46b1-877c-03368e85f10b'::uuid)
Rows Removed by Filter: 80000
Buffers: shared hit=1235
Planning:
Buffers: shared hit=4
Planning Time: 0.060 ms
Execution Time: 7.721 ms
Индексы messages:
messages_chat_created_id_idx -> CREATE INDEX messages_chat_created_id_idx ON public.messages USING btree (chat_id, created_at, id)
messages_pkey -> CREATE UNIQUE INDEX messages_pkey ON public.messages USING btree (id)
Размер индекса: 8536 kB ; таблицы: 9880 kB
Binary file not shown.
+22
View File
@@ -0,0 +1,22 @@
# Миграции с нуля и повторный запуск (песочница, PostgreSQL 16)
$ python -m app.migrate (запуск 1)
2026-10-15 09:56:03,651 migrate applied: 0001_core, 0002_sessions
$ python -m app.migrate (запуск 2)
2026-10-15 09:56:03,862 migrate applied: nothing to do (schema is up to date)
version | checksum
---------------+--------------
0001_core | 5cc38bccb02e
0002_sessions | 6ef657d22fa7
(2 rows)
List of relations
Schema | Name | Type | Owner
--------+-------------------+-------+-----------
public | chat_members | table | messenger
public | chats | table | messenger
public | messages | table | messenger
public | schema_migrations | table | messenger
public | sessions | table | messenger
public | users | table | messenger
(6 rows)
+15
View File
@@ -0,0 +1,15 @@
=== Persistence on Docker Compose (Windows 11 + Docker Desktop) ===
Дата: 2026-10-16 19:28
Шаги:
1. POST /api/v1/users (username=persist, password 12+) -> 201
2. POST /api/v1/auth/sessions (Basic) -> 201, получен Bearer-токен
3. GET /api/v1/users/me с Bearer -> 200 OK (username=persist)
4. docker compose stop api valkey postgres
5. docker compose up -d -> migrate пропустил миграции, api healthy
6. GET /api/v1/users/me тем же Bearer-токеном ПОСЛЕ рестарта -> 200 OK
Вывод: PostgreSQL сохранил данные в volume pgdata.
Valkey-кэш потерян (RAM), но при промахе сессия читается из PostgreSQL.
Пользователи, сообщения и действующие сессии переживают полный рестарт
всех хранилищ без удаления volumes.
+14
View File
@@ -0,0 +1,14 @@
# Сохранность при полном рестарте (песочничный hook: API (uvicorn, 2 процесса) + PostgreSQL + Redis, данные на диске сохраняются)
== before ==
postgres postmaster_start=2026-10-15 21:38:10.905693+00
redis uptime_s=73
api master_pid=197
rows users=127 messages=1242 sessions=52
== make test-persistence ==
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
== after ==
postgres postmaster_start=2026-10-15 21:39:16.659936+00
redis uptime_s=2
api master_pid=587
rows users=130 messages=1243 sessions=55
+47
View File
@@ -0,0 +1,47 @@
# Среда: песочница без Docker. PostgreSQL 16.15, Redis 7 (вместо Valkey), Python 3.12.3, FastAPI 0.115.0 + uvicorn 0.30.6 (2 процесса), 2026-10-15T21:39:00Z
# Compose-стенд в этой среде не запускался (нет Docker) — см. REPORT.md, «Ограничения проверки».
$ make check
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ make test
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
$ python3 tests_student/test_integration.py
PASS registration_race_same_username
PASS username_and_field_validation
PASS password_with_colon_and_unicode_login
PASS login_failures_look_identical
PASS bearer_rules
PASS logout_revokes_only_that_session
PASS chat_creation_rules_and_no_side_effects
PASS message_rules
PASS pagination_walk_and_cursor_binding
PASS chat_list_pagination_and_order
PASS request_id_and_error_shape
11/11 passed
$ pytest tests/test_own.py tests/test_race.py -v
test_own.py::test_invalid_json PASSED
test_own.py::test_duplicate_username PASSED
test_own.py::test_extra_fields PASSED
test_own.py::test_empty_message PASSED
test_own.py::test_foreign_chat PASSED
test_own.py::test_pagination PASSED
test_own.py::test_cursor_from_other_chat_is_400 PASSED
test_own.py::test_x_user_id_no_longer_grants_access PASSED
test_own.py::test_basic_only_on_login PASSED
test_own.py::test_wrong_password_and_unknown_user_look_the_same PASSED
test_own.py::test_logout_revokes_token PASSED
test_own.py::test_password_is_never_returned PASSED
test_own.py::test_short_password_rejected PASSED
test_race.py::test_concurrent_writes PASSED
test_race.py::test_concurrent_registration_same_username PASSED
============================== 15 passed in 1.28s ==============================
$ python tests_student/test_db_rollback.py
PASS: ошибка внутри транзакции откатила вставку chats (0 строк), контрольный commit сохранил чат и участника
$ SESSION_TTL_SECONDS=2 (API на :8081) python tests_student/test_expiry.py 2
PASS: сессия с TTL=2.0s перестала действовать (401 на users/me, chats, logout) после ожидания 3.5s
Binary file not shown.
Binary file not shown.
+502
View File
@@ -0,0 +1,502 @@
{
"environment": {
"postgres": "17.6",
"shared_buffers": "128MB",
"work_mem": "4MB",
"fsync": "on",
"synchronous_commit": "on",
"cpus": 8,
"python": "3.14.0",
"platform": "Windows-11-10.0.26200-SP0"
},
"dataset": {
"messages": 100000,
"chats": 563,
"chat_size_distribution": {
"50000": 1,
"20000": 1,
"10000": 1,
"1000": 10,
"100": 50,
"10": 500
},
"text_length_chars": "10..400 (ðàâíîìåðíî)",
"page_size": 50,
"read_runs": 300,
"warmup": 20,
"single_inserts": 2000,
"bulk_repeats": 3,
"order": "forward"
},
"configs": {
"C0_pk_only": {
"ddl": null,
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
3.279,
2.998,
2.954
],
"median": 2.998
},
"single_insert_ms": {
"n": 2000,
"mean": 2.04,
"p50": 1.77,
"p95": 2.782,
"p99": 9.041
},
"history_index_bytes": 0,
"table_bytes": 49356800,
"pk_index_bytes": 4399104
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 20.143,
"p95_ms": 21.423,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 16.284,
"shared_buffers": 6113,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 14.824,
"p95_ms": 18.251,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 14.493,
"shared_buffers": 6055,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 14.878,
"p95_ms": 16.222,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Limit"
],
"execution_ms": 13.788,
"shared_buffers": 6025,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 14.544,
"p95_ms": 19.133,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Limit"
],
"execution_ms": 16.134,
"shared_buffers": 6025,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 68.21,
"p95_ms": 73.534,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 52.653,
"shared_buffers": 6113,
"rows": 51
}
}
}
},
"C1_chat_id": {
"ddl": "CREATE INDEX hist_idx ON messages (chat_id)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
3.061,
3.026,
3.2
],
"median": 3.061
},
"single_insert_ms": {
"n": 2000,
"mean": 1.881,
"p50": 1.787,
"p95": 2.476,
"p99": 3.015
},
"history_index_bytes": 909312,
"table_bytes": 49356800,
"pk_index_bytes": 4366336
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 14.884,
"p95_ms": 16.423,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 13.512,
"shared_buffers": 6113,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 14.3,
"p95_ms": 15.906,
"plan": {
"nodes": [
"Bitmap Index Scan",
"Bitmap Heap Scan",
"Sort",
"Limit"
],
"execution_ms": 12.621,
"shared_buffers": 3133,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 0.957,
"p95_ms": 1.473,
"plan": {
"nodes": [
"Index Scan",
"Sort",
"Limit"
],
"execution_ms": 0.05,
"shared_buffers": 4,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 1.787,
"p95_ms": 2.624,
"plan": {
"nodes": [
"Index Scan",
"Sort",
"Limit"
],
"execution_ms": 0.382,
"shared_buffers": 91,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 62.441,
"p95_ms": 68.187,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 60.441,
"shared_buffers": 6113,
"rows": 51
}
}
}
},
"C2_chat_created_id": {
"ddl": "CREATE INDEX hist_idx ON messages (chat_id, created_at, id)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
3.12,
3.112,
3.109
],
"median": 3.112
},
"single_insert_ms": {
"n": 2000,
"mean": 1.965,
"p50": 1.733,
"p95": 2.488,
"p99": 8.053
},
"history_index_bytes": 7184384,
"table_bytes": 49356800,
"pk_index_bytes": 4374528
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 1.219,
"p95_ms": 1.86,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.066,
"shared_buffers": 7,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 1.196,
"p95_ms": 1.721,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.059,
"shared_buffers": 12,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 0.932,
"p95_ms": 1.533,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.041,
"shared_buffers": 5,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 1.25,
"p95_ms": 1.847,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.066,
"shared_buffers": 10,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 9.21,
"p95_ms": 10.112,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 10.02,
"shared_buffers": 3955,
"rows": 51
}
}
}
},
"C3_covering_include": {
"ddl": "CREATE INDEX hist_idx ON messages (chat_id, created_at, id) INCLUDE (sender_id, text)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
3.791,
3.695,
3.919
],
"median": 3.791
},
"single_insert_ms": {
"n": 2000,
"mean": 1.84,
"p50": 1.741,
"p95": 2.373,
"p99": 2.899
},
"history_index_bytes": 37306368,
"table_bytes": 49356800,
"pk_index_bytes": 4349952
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 1.184,
"p95_ms": 1.863,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.062,
"shared_buffers": 6,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 1.221,
"p95_ms": 1.916,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.085,
"shared_buffers": 6,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 1.05,
"p95_ms": 1.488,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.043,
"shared_buffers": 4,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 1.3,
"p95_ms": 2.022,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.073,
"shared_buffers": 8,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 8.186,
"p95_ms": 10.23,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 9.554,
"shared_buffers": 1474,
"rows": 51
}
}
}
},
"C4_global_created_id": {
"ddl": "CREATE INDEX hist_idx ON messages (created_at, id)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
3.189,
3.259,
3.973
],
"median": 3.259
},
"single_insert_ms": {
"n": 2000,
"mean": 2.09,
"p50": 1.904,
"p95": 2.826,
"p99": 3.545
},
"history_index_bytes": 5193728,
"table_bytes": 49356800,
"pk_index_bytes": 4341760
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 3.453,
"p95_ms": 4.159,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 2.093,
"shared_buffers": 5500,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 1.492,
"p95_ms": 2.025,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.081,
"shared_buffers": 11,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 32.912,
"p95_ms": 35.359,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Limit"
],
"execution_ms": 12.81,
"shared_buffers": 6025,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 1.491,
"p95_ms": 2.278,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.286,
"shared_buffers": 669,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 67.904,
"p95_ms": 74.677,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 57.802,
"shared_buffers": 6113,
"rows": 51
}
}
}
}
}
}
+508
View File
@@ -0,0 +1,508 @@
{
"environment": {
"postgres": "17.6",
"shared_buffers": "128MB",
"work_mem": "4MB",
"fsync": "on",
"synchronous_commit": "on",
"cpus": 8,
"python": "3.14.0",
"platform": "Windows-11-10.0.26200-SP0"
},
"dataset": {
"messages": 100000,
"chats": 563,
"chat_size_distribution": {
"50000": 1,
"20000": 1,
"10000": 1,
"1000": 10,
"100": 50,
"10": 500
},
"text_length_chars": "10..400 (ðàâíîìåðíî)",
"page_size": 50,
"read_runs": 300,
"warmup": 20,
"single_inserts": 2000,
"bulk_repeats": 3,
"order": "reverse"
},
"configs": {
"C4_global_created_id": {
"ddl": "CREATE INDEX hist_idx ON messages (created_at, id)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
3.384,
3.279,
3.452
],
"median": 3.384
},
"single_insert_ms": {
"n": 2000,
"mean": 1.787,
"p50": 1.714,
"p95": 2.309,
"p99": 2.722
},
"history_index_bytes": 5201920,
"table_bytes": 49471488,
"pk_index_bytes": 4358144
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 3.433,
"p95_ms": 4.326,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 2.116,
"shared_buffers": 5503,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 1.418,
"p95_ms": 2.031,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.11,
"shared_buffers": 8,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 15.92,
"p95_ms": 33.715,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Limit"
],
"execution_ms": 12.834,
"shared_buffers": 6039,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 1.455,
"p95_ms": 2.026,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.302,
"shared_buffers": 669,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 72.363,
"p95_ms": 134.385,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 71.893,
"shared_buffers": 6127,
"rows": 51
}
}
}
},
"C3_covering_include": {
"ddl": "CREATE INDEX hist_idx ON messages (chat_id, created_at, id) INCLUDE (sender_id, text)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
5.342,
4.847,
5.174
],
"median": 5.174
},
"single_insert_ms": {
"n": 2000,
"mean": 2.497,
"p50": 2.267,
"p95": 3.945,
"p99": 6.674
},
"history_index_bytes": 37232640,
"table_bytes": 49471488,
"pk_index_bytes": 4374528
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 2.224,
"p95_ms": 4.071,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.249,
"shared_buffers": 6,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 1.837,
"p95_ms": 2.794,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.106,
"shared_buffers": 6,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 1.347,
"p95_ms": 2.536,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.121,
"shared_buffers": 4,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 2.845,
"p95_ms": 5.62,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.112,
"shared_buffers": 7,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 10.613,
"p95_ms": 15.66,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 9.475,
"shared_buffers": 1468,
"rows": 51
}
}
}
},
"C2_chat_created_id": {
"ddl": "CREATE INDEX hist_idx ON messages (chat_id, created_at, id)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
3.81,
3.621,
3.556
],
"median": 3.621
},
"single_insert_ms": {
"n": 2000,
"mean": 1.942,
"p50": 1.847,
"p95": 2.499,
"p99": 3.009
},
"history_index_bytes": 7200768,
"table_bytes": 49471488,
"pk_index_bytes": 4358144
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 1.327,
"p95_ms": 1.95,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.071,
"shared_buffers": 6,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 1.861,
"p95_ms": 2.543,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.09,
"shared_buffers": 9,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 1.095,
"p95_ms": 1.511,
"plan": {
"nodes": [
"Bitmap Index Scan",
"Bitmap Heap Scan",
"Sort",
"Limit"
],
"execution_ms": 0.262,
"shared_buffers": 5,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 1.564,
"p95_ms": 2.092,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.075,
"shared_buffers": 12,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 62.262,
"p95_ms": 89.574,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 81.055,
"shared_buffers": 6127,
"rows": 51
}
}
}
},
"C1_chat_id": {
"ddl": "CREATE INDEX hist_idx ON messages (chat_id)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
5.229,
3.858,
3.608
],
"median": 3.858
},
"single_insert_ms": {
"n": 2000,
"mean": 2.301,
"p50": 2.258,
"p95": 2.911,
"p99": 3.367
},
"history_index_bytes": 892928,
"table_bytes": 49471488,
"pk_index_bytes": 4399104
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 17.321,
"p95_ms": 21.988,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 22.421,
"shared_buffers": 6127,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 16.562,
"p95_ms": 21.11,
"plan": {
"nodes": [
"Bitmap Index Scan",
"Bitmap Heap Scan",
"Sort",
"Limit"
],
"execution_ms": 14.295,
"shared_buffers": 3142,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 1.417,
"p95_ms": 1.895,
"plan": {
"nodes": [
"Bitmap Index Scan",
"Bitmap Heap Scan",
"Sort",
"Limit"
],
"execution_ms": 0.136,
"shared_buffers": 4,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 2.429,
"p95_ms": 3.066,
"plan": {
"nodes": [
"Bitmap Index Scan",
"Bitmap Heap Scan",
"Sort",
"Limit"
],
"execution_ms": 0.556,
"shared_buffers": 92,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 77.773,
"p95_ms": 114.858,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 69.741,
"shared_buffers": 6127,
"rows": 51
}
}
}
},
"C0_pk_only": {
"ddl": null,
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
3.645,
3.652,
3.632
],
"median": 3.645
},
"single_insert_ms": {
"n": 2000,
"mean": 1.889,
"p50": 1.822,
"p95": 2.427,
"p99": 2.731
},
"history_index_bytes": 0,
"table_bytes": 49471488,
"pk_index_bytes": 4366336
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 18.452,
"p95_ms": 21.713,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 20.771,
"shared_buffers": 6127,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 18.306,
"p95_ms": 21.371,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 16.318,
"shared_buffers": 6069,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 14.635,
"p95_ms": 16.207,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Limit"
],
"execution_ms": 12.85,
"shared_buffers": 6039,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 17.253,
"p95_ms": 19.007,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Limit"
],
"execution_ms": 15.036,
"shared_buffers": 6039,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 68.051,
"p95_ms": 73.12,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 49.273,
"shared_buffers": 6127,
"rows": 51
}
}
}
}
}
}
+505
View File
@@ -0,0 +1,505 @@
{
"environment": {
"postgres": "16.15 (Ubuntu 16.15-0ubuntu0.24.04.1)",
"shared_buffers": "128MB",
"work_mem": "4MB",
"fsync": "on",
"synchronous_commit": "on",
"cpus": 1,
"python": "3.12.3",
"platform": "Linux-6.18.44-fc-v114-x86_64-with-glibc2.39"
},
"dataset": {
"messages": 100000,
"chats": 563,
"chat_size_distribution": {
"50000": 1,
"20000": 1,
"10000": 1,
"1000": 10,
"100": 50,
"10": 500
},
"text_length_chars": "10..400 (равномерно)",
"page_size": 50,
"read_runs": 300,
"warmup": 20,
"single_inserts": 2000,
"bulk_repeats": 3,
"order": "reverse"
},
"configs": {
"C4_global_created_id": {
"ddl": "CREATE INDEX hist_idx ON messages (created_at, id)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
1.193,
1.12,
1.154
],
"median": 1.154
},
"single_insert_ms": {
"n": 2000,
"mean": 0.683,
"p50": 0.631,
"p95": 1.128,
"p99": 1.724
},
"history_index_bytes": 5185536,
"table_bytes": 49528832,
"pk_index_bytes": 4423680
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 2.973,
"p95_ms": 3.433,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 1.295,
"shared_buffers": 5505,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 0.38,
"p95_ms": 0.561,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.044,
"shared_buffers": 8,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 25.688,
"p95_ms": 44.275,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Limit"
],
"execution_ms": 15.299,
"shared_buffers": 6046,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 0.505,
"p95_ms": 0.915,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.18,
"shared_buffers": 669,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 41.86,
"p95_ms": 61.732,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 76.728,
"shared_buffers": 6134,
"rows": 51
}
}
}
},
"C3_covering_include": {
"ddl": "CREATE INDEX hist_idx ON messages (chat_id, created_at, id) INCLUDE (sender_id, text)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
1.276,
1.46,
1.42
],
"median": 1.42
},
"single_insert_ms": {
"n": 2000,
"mean": 0.567,
"p50": 0.507,
"p95": 0.923,
"p99": 1.459
},
"history_index_bytes": 38543360,
"table_bytes": 49528832,
"pk_index_bytes": 4431872
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 0.212,
"p95_ms": 0.399,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.032,
"shared_buffers": 7,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 0.329,
"p95_ms": 0.613,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.029,
"shared_buffers": 6,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 0.08,
"p95_ms": 0.133,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.016,
"shared_buffers": 4,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 0.327,
"p95_ms": 0.551,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.039,
"shared_buffers": 6,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 4.339,
"p95_ms": 7.16,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 7.172,
"shared_buffers": 1468,
"rows": 51
}
}
}
},
"C2_chat_created_id": {
"ddl": "CREATE INDEX hist_idx ON messages (chat_id, created_at, id)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
1.25,
1.182,
1.198
],
"median": 1.198
},
"single_insert_ms": {
"n": 2000,
"mean": 0.813,
"p50": 0.758,
"p95": 1.324,
"p99": 2.348
},
"history_index_bytes": 7487488,
"table_bytes": 49528832,
"pk_index_bytes": 4423680
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 0.214,
"p95_ms": 0.29,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.033,
"shared_buffers": 7,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 0.326,
"p95_ms": 0.596,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.048,
"shared_buffers": 9,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 0.121,
"p95_ms": 0.293,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.025,
"shared_buffers": 6,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 0.297,
"p95_ms": 0.561,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.031,
"shared_buffers": 8,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 40.25,
"p95_ms": 54.269,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 96.889,
"shared_buffers": 6139,
"rows": 51
}
}
}
},
"C1_chat_id": {
"ddl": "CREATE INDEX hist_idx ON messages (chat_id)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
1.408,
1.338,
1.259
],
"median": 1.338
},
"single_insert_ms": {
"n": 2000,
"mean": 0.609,
"p50": 0.573,
"p95": 0.947,
"p99": 1.226
},
"history_index_bytes": 876544,
"table_bytes": 49528832,
"pk_index_bytes": 4415488
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 8.119,
"p95_ms": 13.049,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 31.511,
"shared_buffers": 6134,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 8.103,
"p95_ms": 15.315,
"plan": {
"nodes": [
"Bitmap Index Scan",
"Bitmap Heap Scan",
"Sort",
"Limit"
],
"execution_ms": 17.174,
"shared_buffers": 3151,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 0.144,
"p95_ms": 0.229,
"plan": {
"nodes": [
"Index Scan",
"Sort",
"Limit"
],
"execution_ms": 0.037,
"shared_buffers": 5,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 0.642,
"p95_ms": 0.925,
"plan": {
"nodes": [
"Bitmap Index Scan",
"Bitmap Heap Scan",
"Sort",
"Limit"
],
"execution_ms": 0.363,
"shared_buffers": 90,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 36.041,
"p95_ms": 48.493,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 79.39,
"shared_buffers": 6134,
"rows": 51
}
}
}
},
"C0_pk_only": {
"ddl": null,
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
0.963,
1.098,
1.406
],
"median": 1.098
},
"single_insert_ms": {
"n": 2000,
"mean": 0.944,
"p50": 0.847,
"p95": 1.616,
"p99": 2.599
},
"history_index_bytes": 0,
"table_bytes": 49528832,
"pk_index_bytes": 4415488
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 26.853,
"p95_ms": 44.262,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 33.108,
"shared_buffers": 6134,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 33.107,
"p95_ms": 46.562,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 32.472,
"shared_buffers": 6076,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 16.6,
"p95_ms": 24.988,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Limit"
],
"execution_ms": 14.32,
"shared_buffers": 6046,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 21.05,
"p95_ms": 33.296,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Limit"
],
"execution_ms": 18.585,
"shared_buffers": 6046,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 45.405,
"p95_ms": 66.359,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 82.673,
"shared_buffers": 6134,
"rows": 51
}
}
}
}
}
}
+504
View File
@@ -0,0 +1,504 @@
{
"environment": {
"postgres": "16.15 (Ubuntu 16.15-0ubuntu0.24.04.1)",
"shared_buffers": "128MB",
"work_mem": "4MB",
"fsync": "on",
"synchronous_commit": "on",
"cpus": 1,
"python": "3.12.3",
"platform": "Linux-6.18.44-fc-v114-x86_64-with-glibc2.39"
},
"dataset": {
"messages": 100000,
"chats": 563,
"chat_size_distribution": {
"50000": 1,
"20000": 1,
"10000": 1,
"1000": 10,
"100": 50,
"10": 500
},
"text_length_chars": "10..400 (равномерно)",
"page_size": 50,
"read_runs": 300,
"warmup": 20,
"single_inserts": 2000,
"bulk_repeats": 3
},
"configs": {
"C0_pk_only": {
"ddl": null,
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
1.249,
1.182,
1.17
],
"median": 1.182
},
"single_insert_ms": {
"n": 2000,
"mean": 0.809,
"p50": 0.696,
"p95": 1.625,
"p99": 3.319
},
"history_index_bytes": 0,
"table_bytes": 49446912,
"pk_index_bytes": 4644864
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 19.011,
"p95_ms": 29.257,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 39.274,
"shared_buffers": 6124,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 36.202,
"p95_ms": 49.585,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 31.905,
"shared_buffers": 6066,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 14.85,
"p95_ms": 25.226,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Limit"
],
"execution_ms": 18.925,
"shared_buffers": 6036,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 36.263,
"p95_ms": 52.683,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Limit"
],
"execution_ms": 30.508,
"shared_buffers": 6036,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 47.972,
"p95_ms": 66.037,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 72.734,
"shared_buffers": 6124,
"rows": 51
}
}
}
},
"C1_chat_id": {
"ddl": "CREATE INDEX hist_idx ON messages (chat_id)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
1.345,
1.301,
1.366
],
"median": 1.345
},
"single_insert_ms": {
"n": 2000,
"mean": 1.21,
"p50": 0.944,
"p95": 2.856,
"p99": 5.362
},
"history_index_bytes": 925696,
"table_bytes": 49446912,
"pk_index_bytes": 4636672
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 16.093,
"p95_ms": 22.986,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 45.496,
"shared_buffers": 6124,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 11.782,
"p95_ms": 20.282,
"plan": {
"nodes": [
"Bitmap Index Scan",
"Bitmap Heap Scan",
"Sort",
"Limit"
],
"execution_ms": 21.566,
"shared_buffers": 3140,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 0.157,
"p95_ms": 0.32,
"plan": {
"nodes": [
"Index Scan",
"Sort",
"Limit"
],
"execution_ms": 0.04,
"shared_buffers": 5,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 0.676,
"p95_ms": 1.21,
"plan": {
"nodes": [
"Bitmap Index Scan",
"Bitmap Heap Scan",
"Sort",
"Limit"
],
"execution_ms": 0.296,
"shared_buffers": 88,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 37.922,
"p95_ms": 51.332,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 82.629,
"shared_buffers": 6124,
"rows": 51
}
}
}
},
"C2_chat_created_id": {
"ddl": "CREATE INDEX hist_idx ON messages (chat_id, created_at, id)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
1.245,
1.246,
1.339
],
"median": 1.246
},
"single_insert_ms": {
"n": 2000,
"mean": 0.755,
"p50": 0.709,
"p95": 1.219,
"p99": 1.725
},
"history_index_bytes": 8085504,
"table_bytes": 49446912,
"pk_index_bytes": 4653056
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 0.446,
"p95_ms": 0.916,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.059,
"shared_buffers": 7,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 0.476,
"p95_ms": 0.899,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.054,
"shared_buffers": 9,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 0.153,
"p95_ms": 0.317,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.034,
"shared_buffers": 6,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 0.245,
"p95_ms": 0.556,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.033,
"shared_buffers": 9,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 38.956,
"p95_ms": 53.771,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 97.936,
"shared_buffers": 6124,
"rows": 51
}
}
}
},
"C3_covering_include": {
"ddl": "CREATE INDEX hist_idx ON messages (chat_id, created_at, id) INCLUDE (sender_id, text)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
1.752,
1.604,
1.581
],
"median": 1.604
},
"single_insert_ms": {
"n": 2000,
"mean": 0.51,
"p50": 0.457,
"p95": 0.844,
"p99": 1.189
},
"history_index_bytes": 41484288,
"table_bytes": 49446912,
"pk_index_bytes": 4644864
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 0.482,
"p95_ms": 0.591,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.029,
"shared_buffers": 6,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 0.253,
"p95_ms": 0.484,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.031,
"shared_buffers": 6,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 0.08,
"p95_ms": 0.163,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.017,
"shared_buffers": 4,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 0.238,
"p95_ms": 0.433,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 0.03,
"shared_buffers": 7,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 4.709,
"p95_ms": 7.598,
"plan": {
"nodes": [
"Index Only Scan",
"Limit"
],
"execution_ms": 7.275,
"shared_buffers": 1472,
"rows": 51
}
}
}
},
"C4_global_created_id": {
"ddl": "CREATE INDEX hist_idx ON messages (created_at, id)",
"writes": {
"bulk_insert_100k_seconds": {
"runs": [
1.459,
1.53,
1.405
],
"median": 1.459
},
"single_insert_ms": {
"n": 2000,
"mean": 0.481,
"p50": 0.411,
"p95": 0.898,
"p99": 1.397
},
"history_index_bytes": 5177344,
"table_bytes": 49446912,
"pk_index_bytes": 4644864
},
"reads": {
"Q1_first_page_giant_50k": {
"p50_ms": 1.572,
"p95_ms": 2.733,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 2.349,
"shared_buffers": 5491,
"rows": 51
}
},
"Q2_deep_keyset_giant_at_40k": {
"p50_ms": 0.479,
"p95_ms": 0.685,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.05,
"shared_buffers": 8,
"rows": 51
}
},
"Q3_first_page_tiny_10": {
"p50_ms": 33.156,
"p95_ms": 51.981,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Limit"
],
"execution_ms": 16.027,
"shared_buffers": 6036,
"rows": 10
}
},
"Q4_keyset_mid_1k_at_500": {
"p50_ms": 0.418,
"p95_ms": 0.688,
"plan": {
"nodes": [
"Index Scan",
"Limit"
],
"execution_ms": 0.148,
"shared_buffers": 669,
"rows": 51
}
},
"Q5_OFFSET_40000_giant": {
"p50_ms": 42.816,
"p95_ms": 60.392,
"plan": {
"nodes": [
"Seq Scan",
"Sort",
"Gather Merge",
"Limit"
],
"execution_ms": 84.868,
"shared_buffers": 6124,
"rows": 51
}
}
}
}
}
}
Binary file not shown.
+61
View File
@@ -0,0 +1,61 @@
{
"snapshot_consistent_with_restore": true,
"checks": {
"counts": true,
"messages_md5": true,
"per_chat_counts_md5": true,
"indexes_md5": true,
"constraints_md5": true,
"migrations": true,
"selected_messages": {
"first_overall": true,
"last_overall": true,
"giant_chat_item_15000": true,
"longest_text": true,
"shortest_text": true,
"pseudo_random_by_md5": true
}
},
"rpo_window_observed": {
"messages_lost_in_restore": 500,
"revoked_session_resurrected_in_restore": true
},
"timing_seconds": {
"pg_dump": 0.76,
"pg_restore": 1.34,
"analyze_after_restore": 0.21,
"rto_dump_free_restore_plus_analyze": 1.56
},
"sizes_bytes": {
"source_database": 68688919,
"dump_file": 3615536
},
"counts_at_dump": {
"users": 1,
"chats": 563,
"chat_members": 563,
"messages": 102000,
"sessions": 1
},
"counts_restored": {
"users": 1,
"chats": 563,
"chat_members": 563,
"messages": 102000,
"sessions": 1
},
"counts_source_after_extra_writes": {
"users": 1,
"chats": 563,
"chat_members": 563,
"messages": 102500,
"sessions": 0
},
"restored_plan": {
"first_page_giant": {
"node": "Index Scan",
"index": "messages_chat_created_id_idx",
"execution_ms": 0.066
}
}
}
+8
View File
@@ -0,0 +1,8 @@
# Восстановленная БД (новый сервер :5434) обслуживает приложение
$ python -m app.migrate (на восстановленной БД)
2026-10-15 10:08:21,788 migrate applied: nothing to do (schema is up to date)
$ make test BASE_URL=http://localhost:8082 (API подключён к восстановленной БД, без Valkey)
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.
$ python3 tests_student/test_integration.py (против восстановленной БД)
11/11 passed
+23
View File
@@ -0,0 +1,23 @@
# Трек 2: сводка (медианы двух проходов; p50 клиентской латентности, мс)
Данные: 100 000 сообщений + 2 000 одиночных вставок = ~102 000; 563 чата (50k/20k/10k/10×1k/50×100/500×10); PostgreSQL 16.15, 1 CPU, fsync=on.
## Чтение (p50, мс; проход 1 / проход 2)
| Конфигурация | Q1 first_page_giant_50k | Q2 deep_keyset_giant_at_40k | Q3 first_page_tiny_10 | Q4 keyset_mid_1k_at_500 | Q5 OFFSET_40000_giant |
|---|---|---|---|---|---|
| C0_pk_only | 19.01 / 26.85 (Seq, 6124 buf) | 36.20 / 33.11 (Seq, 6066 buf) | 14.85 / 16.60 (Seq, 6036 buf) | 36.26 / 21.05 (Seq, 6036 buf) | 47.97 / 45.41 (Seq, 6124 buf) |
| C1_chat_id | 16.09 / 8.12 (Seq, 6124 buf) | 11.78 / 8.10 (Bitmap Index, 3140 buf) | 0.16 / 0.14 (Index, 5 buf) | 0.68 / 0.64 (Bitmap Index, 88 buf) | 37.92 / 36.04 (Seq, 6124 buf) |
| C2_chat_created_id | 0.45 / 0.21 (Index, 7 buf) | 0.48 / 0.33 (Index, 9 buf) | 0.15 / 0.12 (Index, 6 buf) | 0.24 / 0.30 (Index, 9 buf) | 38.96 / 40.25 (Seq, 6124 buf) |
| C3_covering_include | 0.48 / 0.21 (IdxOnly, 6 buf) | 0.25 / 0.33 (IdxOnly, 6 buf) | 0.08 / 0.08 (IdxOnly, 4 buf) | 0.24 / 0.33 (IdxOnly, 7 buf) | 4.71 / 4.34 (IdxOnly, 1472 buf) |
| C4_global_created_id | 1.57 / 2.97 (Index, 5491 buf) | 0.48 / 0.38 (Index, 8 buf) | 33.16 / 25.69 (Seq, 6036 buf) | 0.42 / 0.51 (Index, 669 buf) | 42.82 / 41.86 (Seq, 6124 buf) |
## Запись и размер
| Конфигурация | bulk 100k, с (п1 / п2) | одиночный INSERT p50, мс (п1 / п2) | p95, мс (п1 / п2) | индекс истории, MiB |
|---|---|---|---|---|
| C0_pk_only | 1.18 / 1.10 | 0.70 / 0.85 | 1.62 / 1.62 | 0.0 |
| C1_chat_id | 1.34 / 1.34 | 0.94 / 0.57 | 2.86 / 0.95 | 0.9 |
| C2_chat_created_id | 1.25 / 1.20 | 0.71 / 0.76 | 1.22 / 1.32 | 7.7 |
| C3_covering_include | 1.60 / 1.42 | 0.46 / 0.51 | 0.84 / 0.92 | 39.6 |
| C4_global_created_id | 1.46 / 1.15 | 0.41 / 0.63 | 0.90 / 1.13 | 4.9 |
+45
View File
@@ -0,0 +1,45 @@
# Optional HTTP-client worksheet; no extension is required by the course.
# Replace IDs/token locally from real responses; do not commit filled-in credentials.
# Canonical API: contracts/openapi.json and contracts/README.md.
@baseUrl = http://localhost:8080
@aliceId = REPLACE_WITH_CREATED_ALICE_UUID
@bobId = REPLACE_WITH_CREATED_BOB_UUID
@chatId = REPLACE_WITH_CREATED_CHAT_UUID
@sessionToken = REPLACE_LOCALLY_DO_NOT_COMMIT
### Liveness
GET {{baseUrl}}/health/live
### Register Alice (repeat with username bob/display_name Боб)
POST {{baseUrl}}/api/v1/users
Content-Type: application/json
{
"username": "alice",
"display_name": "Алиса",
"password": "Example-only-not-a-real-secret-123"
}
### Create session: generate the Base64 value locally, do not commit credentials
# Base64 of UTF-8 username:password; only this endpoint accepts Basic.
POST {{baseUrl}}/api/v1/auth/sessions
Authorization: Basic REPLACE_WITH_LOCAL_BASE64_CREDENTIAL
### Create chat; both UUIDs must be real registered users
POST {{baseUrl}}/api/v1/chats
Authorization: Bearer {{sessionToken}}
Content-Type: application/json
{"title":"Проект по ВНП","member_ids":["{{aliceId}}","{{bobId}}"]}
### Send message
POST {{baseUrl}}/api/v1/chats/{{chatId}}/messages
Authorization: Bearer {{sessionToken}}
Content-Type: application/json
{"text":"Привет, Боб!"}
### Read first page
GET {{baseUrl}}/api/v1/chats/{{chatId}}/messages?limit=50
Authorization: Bearer {{sessionToken}}
+7
View File
@@ -0,0 +1,7 @@
# Инфраструктура студента
Здесь разместите конфигурации выбранных сервисов; основную топологию — в корневом compose.yaml/stack.yaml. `compose.example.yaml` — только worksheet ролей и намеренно не запускается. `contracts/infrastructure.json` задаёт минимальные роли, не готовые образы/пароли.
В REPORT.md сопоставьте роль → service name → версия/digest → health/readiness → volume → сеть/порт → способ передачи credentials. Приведите bootstrap (schema, bucket, broker topology, а с lab6 provisioning) и безопасное повторение этих команд.
Приложение строится из исходников. Не используйте заранее существующий образ преподавательского сервера вместо своей реализации. Restart hook перезапускает все соответствующие stores с volumes; failover hook останавливает только заданную API-реплику.
+8
View File
@@ -0,0 +1,8 @@
{
"number": 2,
"title": "PostgreSQL, сессии и Redis/Valkey",
"contract_version": "1.2.0",
"default_base_url": "http://localhost:8080",
"grading": "3; 4 includes 3; 5 includes 4 plus one completed research track",
"scaffold_has_application": false
}
+259
View File
@@ -0,0 +1,259 @@
"""Мессенджер, лабораторная 2: PostgreSQL + сессии (Bearer) + Valkey/Redis как кэш сессий.
Развитие main.py из lab1 (FastAPI/Uvicorn): те же маршруты, тот же формат ошибок, middleware X-Request-Id.
Изменилось: вместо словарей в памяти — PostgreSQL (app/repo.py), вместо X-User-Id — Bearer-сессия
(app/sessions.py), вход — Basic на POST /auth/sessions, пароли — Argon2id (app/security.py).
"""
import logging
import re
import uuid
from contextlib import asynccontextmanager
from typing import NamedTuple
import anyio.to_thread
import psycopg
from fastapi import Depends, FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse, Response
from starlette.exceptions import HTTPException as StarletteHTTPException
from app import config, cursor, db, repo, security, sessions, validation
from app.errors import BASIC_CHALLENGE, BEARER_CHALLENGE, ApiError, bad_request, not_found, unauthorized
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")
log = logging.getLogger("api")
_REQUEST_ID_RE = re.compile(r"[A-Za-z0-9._-]{1,64}")
@asynccontextmanager
async def lifespan(_app):
# Sync-обработчики FastAPI идут в пул потоков; ограничиваем его, чтобы очередь ждала в потоках, а не в пуле БД.
anyio.to_thread.current_default_thread_limiter().total_tokens = config.THREAD_LIMIT
yield
db.close() # SIGTERM: корректно закрываем соединения PostgreSQL
# Автодокументация FastAPI отключена: контракт — contracts/openapi.json.
app = FastAPI(lifespan=lifespan, docs_url=None, redoc_url=None, openapi_url=None)
# ---------- X-Request-Id, ошибки (как в lab1) ----------
def make_error(code, message, request_id):
return {"error": {"code": code, "message": message, "request_id": request_id}}
def _rid(request):
return getattr(request.state, "request_id", None) or uuid.uuid4().hex
def error_response(request, status, code, message, headers=None):
rid = _rid(request)
out = {"X-Request-Id": rid, "Cache-Control": "no-store"} # заголовок и в ответах, минующих middleware (500)
out.update(headers or {})
return JSONResponse(status_code=status, content=make_error(code, message, rid), headers=out)
@app.middleware("http")
async def add_request_id(request: Request, call_next):
incoming = request.headers.get("X-Request-Id", "")
rid = incoming if _REQUEST_ID_RE.fullmatch(incoming) else uuid.uuid4().hex # чужое значение — только безопасное
request.state.request_id = rid
response = await call_next(request)
response.headers["X-Request-Id"] = rid
response.headers["Cache-Control"] = "no-store"
return response
@app.exception_handler(ApiError)
async def api_error_handler(request: Request, exc: ApiError):
return error_response(request, exc.status, exc.code, exc.message, exc.headers)
@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc):
return error_response(request, 400, "invalid_request", "Некорректный запрос")
@app.exception_handler(StarletteHTTPException)
async def http_exc_handler(request: Request, exc: StarletteHTTPException):
mapping = {404: ("not_found", "Объект не найден"), 405: ("invalid_request", "Метод не поддерживается")}
code, message = mapping.get(exc.status_code, ("invalid_request", "Ошибка запроса"))
return error_response(request, exc.status_code, code, message)
@app.exception_handler(Exception)
async def generic_handler(request: Request, exc: Exception):
if isinstance(exc, db.TRANSIENT):
# PostgreSQL недоступен/перегружен: ограниченный ответ без деталей.
log.warning("dependency unavailable [%s]: %s", _rid(request), type(exc).__name__)
return error_response(request, 503, "unavailable", "Сервис временно недоступен")
log.error("unhandled error [%s]", _rid(request), exc_info=exc) # стек — только в серверный лог
return error_response(request, 500, "internal_error", "Внутренняя ошибка сервера")
# ---------- аутентификация (вместо X-User-Id из lab1) ----------
class Auth(NamedTuple):
user: dict
user_id: uuid.UUID
digest: bytes
def authenticated(request: Request) -> Auth:
"""Bearer-токен -> сессия -> пользователь. Basic, X-User-Id и любые другие схемы дают 401."""
token = security.parse_bearer(request.headers.get("Authorization"))
if token is None:
raise unauthorized(BEARER_CHALLENGE)
found = sessions.lookup(token) # Valkey -> PostgreSQL; БД недоступна -> 503 в generic_handler
if found is None:
raise unauthorized(BEARER_CHALLENGE)
return Auth(found["user"], uuid.UUID(found["user"]["id"]), found["digest"])
class RawBody(NamedTuple):
content_type: str
data: bytes
async def raw_body(request: Request) -> RawBody:
"""Читает тело с жёстким лимитом (в т.ч. для chunked) -> 413. Разбор JSON — позже, после проверки доступа."""
declared = request.headers.get("content-length")
if declared is not None and declared.isdigit() and int(declared) > config.MAX_BODY_BYTES:
raise ApiError(413, "payload_too_large", "Тело запроса слишком большое")
chunks, size = [], 0
async for chunk in request.stream():
size += len(chunk)
if size > config.MAX_BODY_BYTES:
raise ApiError(413, "payload_too_large", "Тело запроса слишком большое")
chunks.append(chunk)
return RawBody(request.headers.get("content-type", ""), b"".join(chunks))
# ---------- health ----------
@app.get("/health/live")
def live():
return {"status": "ok"}
@app.get("/health/ready")
def ready():
db.ping() # критичная зависимость — PostgreSQL; недоступность кэша НЕ делает сервис неготовым
return {"status": "ok"}
# ---------- пользователи ----------
@app.post("/api/v1/users", status_code=201)
def create_user(body: RawBody = Depends(raw_body)):
data = validation.json_body(body.content_type, body.data,
{"username", "display_name", "password"}, {"username", "display_name", "password"})
username = validation.username_field(data["username"])
display_name = validation.text_field(data["display_name"], "display_name", 1, 100)
password = validation.text_field(data["password"], "password", 12, 128)
with db.connection() as conn: # быстрый путь: не тратим Argon2 на заведомый дубль
if repo.username_exists(conn, username):
raise ApiError(409, "conflict", "Имя пользователя занято")
password_hash = security.hash_password(password) # тяжёлая CPU-операция — вне транзакции и без занятого соединения
try:
with db.connection() as conn:
row = repo.insert_user(conn, username, display_name, password_hash)
except psycopg.errors.UniqueViolation: # гонку двух регистраций решает UNIQUE в БД, а не проверка выше
raise ApiError(409, "conflict", "Имя пользователя занято")
return sessions.user_json(row)
@app.get("/api/v1/users/me")
def get_me(auth: Auth = Depends(authenticated)):
return auth.user
# ---------- сессии ----------
@app.post("/api/v1/auth/sessions", status_code=201)
def login(request: Request):
creds = security.parse_basic(request.headers.get("Authorization"))
if creds is None:
raise unauthorized(BASIC_CHALLENGE)
username, password = creds
with db.connection() as conn:
user = repo.user_for_login(conn, username) if validation._USERNAME_RE.fullmatch(username) else None
if user is None:
security.burn_verify(password) # время ответа не выдаёт, существует ли логин
raise unauthorized(BASIC_CHALLENGE)
ok, new_hash = security.verify_password(user["password_hash"], password)
if not ok:
raise unauthorized(BASIC_CHALLENGE)
with db.connection() as conn:
if new_hash:
repo.update_password_hash(conn, user["id"], new_hash)
token, expires_at = sessions.create(conn, user)
user_json = sessions.user_json(user)
sessions.warm(token, user_json, expires_at) # кэш наполняется после commit
return {"token": token, "token_type": "Bearer", "expires_at": sessions.fmt_ts(expires_at), "user": user_json}
@app.delete("/api/v1/auth/sessions/current")
def logout(auth: Auth = Depends(authenticated)):
sessions.revoke(auth.digest)
return Response(status_code=204)
# ---------- чаты ----------
@app.post("/api/v1/chats", status_code=201)
def create_chat(auth: Auth = Depends(authenticated), body: RawBody = Depends(raw_body)):
data = validation.json_body(body.content_type, body.data, {"title", "member_ids"}, {"title", "member_ids"})
title = validation.text_field(data["title"], "title", 1, 100)
raw = data["member_ids"]
if not isinstance(raw, list) or not 1 <= len(raw) <= 100:
raise bad_request("member_ids: от 1 до 100 элементов")
members = [validation.require_uuid(x, "member_id") for x in raw]
if len(set(members)) != len(members) or auth.user_id not in members:
raise bad_request("member_ids должны быть уникальны и включать вызывающего")
with db.connection() as conn: # одна транзакция: либо чат целиком, либо ничего
chat = repo.create_chat(conn, auth.user_id, title, members)
return repo.chat_json(chat)
@app.get("/api/v1/chats")
def list_chats(request: Request, auth: Auth = Depends(authenticated)):
limit = validation.limit_param(request.query_params)
raw = request.query_params.get("cursor")
after = cursor.decode(raw, "chats", auth.user_id) if raw else None
with db.connection() as conn:
items, nxt = repo.list_chats(conn, auth.user_id, after, limit)
return {"items": items, "next_cursor": nxt}
@app.get("/api/v1/chats/{chat_id}")
def get_chat(chat_id: str, auth: Auth = Depends(authenticated)):
cid = validation.require_uuid(chat_id, "chat_id")
with db.connection() as conn:
chat = repo.get_chat(conn, cid, auth.user_id)
if chat is None:
raise not_found()
return repo.chat_json(chat)
# ---------- сообщения ----------
@app.post("/api/v1/chats/{chat_id}/messages", status_code=201)
def create_message(chat_id: str, auth: Auth = Depends(authenticated), body: RawBody = Depends(raw_body)):
cid = validation.require_uuid(chat_id, "chat_id")
with db.connection() as conn:
if not repo.is_member(conn, cid, auth.user_id): # сначала доступ (404), потом валидация тела
raise not_found()
data = validation.json_body(body.content_type, body.data, {"text"}, {"text"})
text = validation.text_field(data["text"], "text", 1, 4000)
with db.connection() as conn:
row = repo.insert_message(conn, cid, auth.user_id, text) # sender_id — только из сессии
return repo.message_json(row)
@app.get("/api/v1/chats/{chat_id}/messages")
def list_messages(chat_id: str, request: Request, auth: Auth = Depends(authenticated)):
cid = validation.require_uuid(chat_id, "chat_id")
limit = validation.limit_param(request.query_params)
raw = request.query_params.get("cursor")
after = cursor.decode(raw, "messages", cid) if raw else None
with db.connection() as conn:
if not repo.is_member(conn, cid, auth.user_id):
raise not_found()
items, nxt = repo.list_messages(conn, cid, after, limit)
return {"items": items, "next_cursor": nxt}
+5
View File
@@ -0,0 +1,5 @@
# Only for full OpenAPI/JSON Schema validation; HTTP tests use stdlib.
openapi-spec-validator==0.7.2
# Свои тесты из lab1 (pytest tests/test_own.py tests/test_race.py -v)
pytest==8.3.3
+6
View File
@@ -0,0 +1,6 @@
fastapi==0.115.0
uvicorn[standard]==0.30.6
psycopg[binary]==3.2.9
psycopg-pool==3.2.6
argon2-cffi==25.1.0
redis==6.4.0
+26
View File
@@ -0,0 +1,26 @@
annotated-types==0.8.0
anyio==4.15.1
argon2-cffi==25.1.0
argon2-cffi-bindings==26.1.0
cffi==2.1.1
click==8.5.0
fastapi==0.115.0
h11==0.16.0
httptools==0.9.0
idna==3.20
psycopg==3.2.9
psycopg-binary==3.2.9
psycopg-pool==3.2.6
pycparser==3.11
pydantic==2.14.1
pydantic_core==2.50.1
python-dotenv==1.2.4
PyYAML==6.0.3
redis==6.4.0
starlette==0.38.6
typing-inspection==0.4.4
typing_extensions==4.16.0
uvicorn==0.30.6
uvloop==0.23.0
watchfiles==1.3.0
websockets==17.2
+9
View File
@@ -0,0 +1,9 @@
#!/bin/sh
# Логический backup рабочей БД стенда (Compose): pg_dump -Fc из контейнера postgres в backups/ (каталог в .gitignore).
# Снапшот согласован на момент НАЧАЛА pg_dump; запись при этом не блокируется. Секреты в вывод не попадают.
set -eu
cd "$(dirname "$0")/.."
mkdir -p backups && umask 077
OUT="backups/messenger-$(date -u +%Y%m%dT%H%M%SZ).dump"
docker compose --env-file .env exec -T postgres pg_dump -U messenger -d messenger -Fc --no-owner > "$OUT"
echo "$OUT $(wc -c < "$OUT") bytes"
+54
View File
@@ -0,0 +1,54 @@
#!/usr/bin/env python3
"""Offline structural checks; full schema validation is a separate target."""
import ast
import json
from pathlib import Path
import re
ROOT = Path(__file__).resolve().parents[1]
def main():
lab = json.loads((ROOT/'lab.json').read_text())['number']
spec = json.loads((ROOT/'contracts/openapi.json').read_text())
assert spec['openapi']=='3.1.0'
assert spec['info']['version']=='1.%d.0'%lab
operation_ids = set()
def walk(value):
if isinstance(value,dict):
if '$ref' in value:
pointer = value['$ref']
assert pointer.startswith('#/'), 'unexpected external reference'
target = spec
for part in pointer[2:].split('/'):
target = target[part.replace('~1','/').replace('~0','~')]
for v in value.values():
walk(v)
elif isinstance(value,list):
for v in value:
walk(v)
walk(spec)
for route,methods in spec['paths'].items():
placeholders = set(re.findall(r'\{([^}]+)\}',route))
for method,op in methods.items():
assert op['operationId'] not in operation_ids, 'duplicate operationId'
operation_ids.add(op['operationId'])
params = {p['name'] for p in op.get('parameters',[]) if p['in']=='path' and p.get('required')}
assert placeholders==params, 'path parameter mismatch: '+route
for response in op['responses'].values():
assert 'X-Request-Id' in response['headers']
if lab>=3:
assert 'X-Instance-Id' in response['headers']
assert ('/api/v1/auth/sessions' in spec['paths']) == (lab>=2)
assert ('/api/v1/attachments/{attachment_id}' in spec['paths']) == (lab>=4)
for file in list((ROOT/'tests').glob('*.py'))+list((ROOT/'scripts').glob('*.py')):
ast.parse(file.read_text(),filename=str(file))
for file in ROOT.rglob('*.json'):
if any(part in {'.git','.venv','node_modules','vendor','output'} for part in file.parts):
continue
json.loads(file.read_text())
for required in ('README.md','COURSE.md','CONTRIBUTING.md','REPORT.md','contracts/README.md','tests/smoke.py','tests/README.md'):
assert (ROOT/required).is_file(), 'missing '+required
print('PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.')
if __name__=='__main__':
main()
+9
View File
@@ -0,0 +1,9 @@
#!/bin/sh
# Доказательство, что restart-hook реально перезапустил процессы: StartedAt контейнеров ДО и ПОСЛЕ + прогон теста.
set -eu
cd "$(dirname "$0")/.."
DC="docker compose --env-file .env"
show() { for s in postgres valkey api; do printf '%-9s StartedAt=%s\n' "$s" "$(docker inspect -f '{{.State.StartedAt}}' "$($DC ps -q $s)")"; done; }
echo "== before =="; show; $DC ps
make test-persistence ACTION_SCRIPT=scripts/restart.sh
echo "== after =="; show; $DC ps
+76
View File
@@ -0,0 +1,76 @@
#!/usr/bin/env python3
"""Обоснование индекса истории: EXPLAIN (ANALYZE, BUFFERS) на синтетических данных.
Использует ОТДЕЛЬНУЮ БД (миграции применяются к ней же): python scripts/explain_history.py
Переменные: DATABASE_URL_FILE/DATABASE_URL указывают на БД для эксперимента (не на рабочую!).
Данные: 1 «целевой» чат (TARGET_N сообщений) + 4 чата-шума по NOISE_N — таблица ≈ 5×, как в реальной системе.
"""
import os
import sys
import uuid
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
import psycopg # noqa: E402
from app import config, migrate # noqa: E402
TARGET_N = int(os.environ.get("TARGET_N", 20000))
NOISE_N = int(os.environ.get("NOISE_N", 20000))
PAGE = 50
def main():
migrate.apply_all(config.DATABASE_URL)
with psycopg.connect(config.DATABASE_URL, autocommit=True) as conn:
conn.execute("TRUNCATE messages, chat_members, chats, sessions, users CASCADE")
user = uuid.uuid4()
conn.execute("INSERT INTO users (id, username, display_name, password_hash) VALUES (%s,'explain_user','x','x')", (user,))
chats = [uuid.uuid4() for _ in range(5)]
for cid in chats:
conn.execute("INSERT INTO chats (id, title, created_by) VALUES (%s,'t',%s)", (cid, user))
conn.execute("INSERT INTO chat_members (chat_id, user_id) VALUES (%s,%s)", (cid, user))
# Вставка вперемешку по времени (как у живых чатов): created_at — равномерная шкала + микросекунды.
for i, cid in enumerate(chats):
n = TARGET_N if i == 0 else NOISE_N
conn.execute("""INSERT INTO messages (id, chat_id, sender_id, text, created_at)
SELECT gen_random_uuid(), %s, %s, 'message ' || g,
timestamptz '2026-01-01 00:00:00+00' + (g * 5 + %s) * interval '1 second' + (random()*1000) * interval '1 microsecond'
FROM generate_series(1, %s) g""", (cid, user, i, n))
conn.execute("VACUUM (ANALYZE) messages")
target = chats[0]
total = conn.execute("SELECT count(*) FROM messages").fetchone()[0]
in_chat = conn.execute("SELECT count(*) FROM messages WHERE chat_id=%s", (target,)).fetchone()[0]
# Курсор «глубоко в истории»: элемент №15000 по (created_at, id).
ts, mid = conn.execute("""SELECT created_at, id FROM messages WHERE chat_id=%s
ORDER BY created_at, id OFFSET %s LIMIT 1""", (target, min(15000, in_chat - PAGE - 1))).fetchone()
def explain(title, sql, params, pre=None, post=None):
print("\n" + "=" * 100 + "\n" + title + "\n" + "=" * 100)
with conn.transaction(force_rollback=True): # DDL в PostgreSQL транзакционен: индекс вернётся
if pre:
conn.execute(pre)
for line in conn.execute("EXPLAIN (ANALYZE, BUFFERS) " + sql, params).fetchall():
print(line[0])
print("rows total=%d, rows in target chat=%d, page=%d" % (total, in_chat, PAGE))
print(conn.execute("SELECT version()").fetchone()[0])
first = "SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id=%s ORDER BY created_at, id LIMIT %s"
keyset = ("SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id=%s "
"AND (created_at, id) > (%s, %s) ORDER BY created_at, id LIMIT %s")
offset = "SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id=%s ORDER BY created_at, id OFFSET 15000 LIMIT %s"
drop = "DROP INDEX messages_chat_created_id_idx"
explain("A. Первая страница, keyset, С индексом (chat_id, created_at, id)", first, (target, PAGE + 1))
explain("B. Страница на глубине ~15 000, keyset, С индексом", keyset, (target, ts, mid, PAGE + 1))
explain("C. Та же страница, keyset, БЕЗ индекса (индекс удалён в откатываемой транзакции)", keyset, (target, ts, mid, PAGE + 1), pre=drop)
explain("D. Та же глубина через OFFSET 15000, С индексом (антипример)", offset, (target, PAGE + 1))
explain("E. Первая страница, БЕЗ индекса", first, (target, PAGE + 1), pre=drop)
print("\nИндексы messages:")
for row in conn.execute("SELECT indexname, indexdef FROM pg_indexes WHERE tablename='messages' ORDER BY 1").fetchall():
print(" ", row[0], "->", row[1])
print("Размер индекса: ", conn.execute("SELECT pg_size_pretty(pg_relation_size('messages_chat_created_id_idx'))").fetchone()[0],
"; таблицы:", conn.execute("SELECT pg_size_pretty(pg_relation_size('messages'))").fetchone()[0])
if __name__ == "__main__":
main()
+17
View File
@@ -0,0 +1,17 @@
#!/bin/sh
# Создаёт локальные секреты (случайные пароли) и .env. Идемпотентно: существующие секреты НЕ перезаписываются
# (иначе пароль в уже инициализированном томе PostgreSQL перестал бы совпадать). Каталог secrets/ в .gitignore.
set -eu
cd "$(dirname "$0")/.."
umask 077
mkdir -p secrets
rand() { if command -v openssl >/dev/null 2>&1; then openssl rand -hex 24; else python3 -c 'import secrets;print(secrets.token_hex(24))'; fi; }
put() { [ -f "secrets/$1" ] || { printf '%s' "$2" > "secrets/$1"; echo "created secrets/$1"; }; }
[ -f secrets/postgres_password ] || printf '%s' "$(rand)" > secrets/postgres_password
[ -f secrets/valkey_password ] || printf '%s' "$(rand)" > secrets/valkey_password
PG=$(cat secrets/postgres_password); VK=$(cat secrets/valkey_password)
put database_url "postgresql://messenger:${PG}@postgres:5432/messenger"
put cache_url "redis://:${VK}@valkey:6379/0"
# Файлы читаются процессами контейнеров с другим UID, поэтому 644; доступ ограничивает каталог secrets/ (700).
chmod 700 secrets && chmod 644 secrets/*
[ -f .env ] || { cp .env.example .env; echo "created .env"; }
+10
View File
@@ -0,0 +1,10 @@
#!/bin/sh
set -eu
# TODO: copy to restart.sh and implement using YOUR compose/stack services.
# Restart API and ALL used state stores (DB, sessions, S3, broker as applicable).
# Preserve persistent volumes and schema/data; never down -v / flush / re-seed.
# Allow operator unseal if required in lab7; do not print credentials.
# Exit 0 only after the intended action; test waits for API readiness separately.
printf '%s
' 'TODO: implement restart.sh for your infrastructure' >&2
exit 2
+14
View File
@@ -0,0 +1,14 @@
#!/bin/sh
# Hook для tests/resilience.py --mode persistence: перезапускает API и ВСЕ хранилища (PostgreSQL, Valkey),
# тома сохраняются. Никаких down -v / flush / повторного seed. Вывод скрыт тестом, секреты не печатаются.
set -eu
cd "$(dirname "$0")/.."
DC="docker compose --env-file .env"
$DC stop api valkey postgres # SIGTERM; compose сам останавливает в обратном порядке зависимостей
$DC up -d # поднимает postgres+valkey, повторно гонит idempotent-миграции, затем api
i=0
until [ "$(docker inspect -f '{{.State.Health.Status}}' "$($DC ps -q api)" 2>/dev/null || true)" = "healthy" ]; do
i=$((i + 1))
[ "$i" -le 70 ] || { echo "api did not become healthy" >&2; exit 1; }
sleep 1
done
+21
View File
@@ -0,0 +1,21 @@
#!/bin/sh
# Восстановление dump в НОВОЕ хранилище (временный контейнер со свежим томом) и сверка с рабочей БД.
# Использование: sh scripts/restore-check.sh backups/messenger-XXXX.dump
# ВНИМАНИЕ: не запускался в среде подготовки (там нет Docker); эквивалентный эксперимент выполнен через
# scripts/track2_restore.py на двух отдельных серверах PostgreSQL (см. evidence/track2-restore.json).
set -eu
cd "$(dirname "$0")/.."
DUMP="${1:?usage: restore-check.sh <dump>}"
DC="docker compose --env-file .env"
NAME="pg-restore-check-$$"
trap 'docker rm -f "$NAME" >/dev/null 2>&1 || true' EXIT
docker run -d --name "$NAME" -e POSTGRES_PASSWORD=restore-check-only -e POSTGRES_USER=messenger -e POSTGRES_DB=restored postgres:17.6-alpine >/dev/null
i=0; until docker exec "$NAME" pg_isready -U messenger -d restored >/dev/null 2>&1; do i=$((i+1)); [ $i -le 60 ] || exit 1; sleep 1; done
START=$(date +%s)
docker exec -i "$NAME" pg_restore -U messenger -d restored --no-owner --exit-on-error < "$DUMP"
docker exec "$NAME" psql -U messenger -d restored -qc "ANALYZE"
echo "restore+analyze seconds: $(( $(date +%s) - START ))"
Q="select 'users',count(*) from users union all select 'chats',count(*) from chats union all select 'chat_members',count(*) from chat_members union all select 'messages',count(*) from messages union all select 'messages_md5', md5(string_agg(id::text||chat_id::text||sender_id::text||created_at::text||md5(text), ',' order by id))::text from messages"
echo "--- restored ---"; docker exec "$NAME" psql -U messenger -d restored -At -c "$Q"
echo "--- source (rows after the dump may differ: that is the RPO window) ---"
$DC exec -T postgres psql -U messenger -d messenger -At -c "$Q"
+9
View File
@@ -0,0 +1,9 @@
#!/bin/sh
# Проверка expiry: пересоздаёт api с SESSION_TTL_SECONDS=2, гоняет tests_student/test_expiry.py, возвращает штатный TTL.
set -eu
cd "$(dirname "$0")/.."
DC="docker compose --env-file .env"
wait_healthy() { i=0; until [ "$(docker inspect -f '{{.State.Health.Status}}' "$($DC ps -q api)")" = "healthy" ]; do i=$((i+1)); [ $i -le 60 ] || exit 1; sleep 1; done; }
trap 'SESSION_TTL_SECONDS= $DC up -d --force-recreate api >/dev/null; wait_healthy' EXIT
SESSION_TTL_SECONDS=2 $DC up -d --force-recreate api; wait_healthy
(cd tests_student && python3 test_expiry.py 2)
+186
View File
@@ -0,0 +1,186 @@
#!/usr/bin/env python3
"""Трек 2 (часть A): план запроса истории на ≥100 000 сообщений с НЕРАВНОМЕРНЫМИ чатами.
Гипотеза H1: составной индекс (chat_id, created_at, id) даёт страницу истории за O(размер страницы)
для любого чата и любой глубины, а индекс только по chat_id или «глобальный» (created_at, id) — нет;
покрывающий вариант (INCLUDE) читает меньше страниц, но платит за это размером индекса и стоимостью записи.
Гипотеза H2: каждый дополнительный индекс заметно удорожает вставку, и цена растёт с шириной индекса.
Запуск (ОТДЕЛЬНАЯ БД эксперимента, не рабочая!):
DATABASE_URL_FILE=/path/to/url python scripts/track2_indexes.py --out evidence/track2-indexes.json
"""
import argparse
import json
import os
import platform
import statistics
import sys
import time
import uuid
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
import psycopg # noqa: E402
from app import config, migrate # noqa: E402
# Неравномерные размеры: 1 гигант, 2 больших, 10 средних, 50 малых, 500 «почти пустых» = ровно 100 000.
SIZES = [50000, 20000, 10000] + [1000] * 10 + [100] * 50 + [10] * 500
CONFIGS = [
("C0_pk_only", None),
("C1_chat_id", "CREATE INDEX hist_idx ON messages (chat_id)"),
("C2_chat_created_id", "CREATE INDEX hist_idx ON messages (chat_id, created_at, id)"),
("C3_covering_include", "CREATE INDEX hist_idx ON messages (chat_id, created_at, id) INCLUDE (sender_id, text)"),
("C4_global_created_id", "CREATE INDEX hist_idx ON messages (created_at, id)"),
]
COLS = "id, chat_id, sender_id, text, created_at"
PAGE = 50
READ_RUNS, WARMUP = 300, 20
SINGLE_INSERTS = 2000
BULK_REPEATS = 3
def pct(values, p):
values = sorted(values)
return values[max(0, min(len(values) - 1, int(round(p * len(values) + 0.5)) - 1))]
def seed_source(conn):
"""Один раз генерируем данные в messages_src: тексты разной длины (10–400 символов), время по возрастанию в чате."""
conn.execute("TRUNCATE messages, chat_members, chats, sessions, users CASCADE")
conn.execute("DROP TABLE IF EXISTS messages_src")
user = uuid.uuid4()
conn.execute("INSERT INTO users (id, username, display_name, password_hash) VALUES (%s,'track2_user','x','x')", (user,))
chats = [uuid.uuid4() for _ in SIZES]
for cid in chats:
conn.execute("INSERT INTO chats (id, title, created_by) VALUES (%s,'t',%s)", (cid, user))
conn.execute("INSERT INTO chat_members (chat_id, user_id) VALUES (%s,%s)", (cid, user))
conn.execute("""CREATE TABLE messages_src AS
SELECT gen_random_uuid() AS id, c.chat_id, %s::uuid AS sender_id,
left(repeat('сообщение ', 60), 10 + (random() * 390)::int) AS text,
timestamptz '2026-01-01 00:00:00+00' + (g.n * 7 + c.idx) * interval '1 second'
+ (random() * 1000) * interval '1 microsecond' AS created_at
FROM (SELECT unnest(%s::uuid[]) AS chat_id, unnest(%s::int[]) AS size, generate_series(1, %s) AS idx) c
CROSS JOIN LATERAL generate_series(1, c.size) AS g(n)""", (user, chats, SIZES, len(SIZES)))
conn.execute("ANALYZE messages_src")
return user, chats
def reset_history_index(conn, ddl):
conn.execute("DROP INDEX IF EXISTS messages_chat_created_id_idx")
conn.execute("DROP INDEX IF EXISTS hist_idx")
if ddl:
conn.execute(ddl)
def measure_writes(conn, ddl, chats):
"""Стоимость записи: (1) пакетная загрузка 100 000 строк, (2) 2000 одиночных INSERT с коммитом (как работает API)."""
bulk = []
for _ in range(BULK_REPEATS):
conn.execute("TRUNCATE messages")
reset_history_index(conn, ddl)
t0 = time.perf_counter()
conn.execute("INSERT INTO messages (id, chat_id, sender_id, text, created_at) SELECT * FROM messages_src")
bulk.append(time.perf_counter() - t0)
conn.execute("VACUUM (ANALYZE) messages")
# Одиночные вставки: чаты выбираются пропорционально размеру (больше сообщений — чаще пишут), autocommit = COMMIT на каждую.
import random
rnd = random.Random(42)
sender = conn.execute("SELECT sender_id FROM messages LIMIT 1").fetchone()[0]
singles = []
for _ in range(SINGLE_INSERTS):
cid = rnd.choices(chats, weights=SIZES)[0]
t0 = time.perf_counter()
conn.execute("INSERT INTO messages (id, chat_id, sender_id, text) VALUES (%s,%s,%s,%s)",
(uuid.uuid4(), cid, sender, "одиночная вставка " + "x" * rnd.randint(10, 300)))
singles.append(time.perf_counter() - t0)
conn.execute("VACUUM (ANALYZE) messages")
size = lambda rel: conn.execute("SELECT pg_relation_size(%s)", (rel,)).fetchone()[0]
return {
"bulk_insert_100k_seconds": {"runs": [round(x, 3) for x in bulk], "median": round(statistics.median(bulk), 3)},
"single_insert_ms": {"n": len(singles), "mean": round(1000 * statistics.mean(singles), 3),
"p50": round(1000 * pct(singles, .50), 3), "p95": round(1000 * pct(singles, .95), 3),
"p99": round(1000 * pct(singles, .99), 3)},
"history_index_bytes": size("hist_idx") if ddl else 0,
"table_bytes": size("messages"),
"pk_index_bytes": size("messages_pkey"),
}
def plan_summary(conn, sql, params):
plan = conn.execute("EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) " + sql, params).fetchone()[0][0]
nodes, stack = [], [plan["Plan"]]
while stack:
node = stack.pop()
nodes.append(node["Node Type"])
stack.extend(node.get("Plans", []))
root = plan["Plan"]
return {"nodes": nodes[::-1], "execution_ms": round(plan["Execution Time"], 3),
"shared_buffers": root.get("Shared Hit Blocks", 0) + root.get("Shared Read Blocks", 0),
"rows": root["Actual Rows"]}
def measure_reads(conn, queries):
out = {}
for name, (sql, params) in queries.items():
for _ in range(WARMUP):
conn.execute(sql, params).fetchall()
times = []
for _ in range(READ_RUNS):
t0 = time.perf_counter()
conn.execute(sql, params).fetchall()
times.append(time.perf_counter() - t0)
out[name] = {"p50_ms": round(1000 * pct(times, .50), 3), "p95_ms": round(1000 * pct(times, .95), 3),
"plan": plan_summary(conn, sql, params)}
return out
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--out", default="evidence/track2-indexes.json")
ap.add_argument("--reverse", action="store_true", help="обратный порядок конфигураций: проверка, что результат не зависит от порядка/прогрева")
args = ap.parse_args()
migrate.apply_all(config.DATABASE_URL)
with psycopg.connect(config.DATABASE_URL, autocommit=True) as conn:
user, chats = seed_source(conn)
total = conn.execute("SELECT count(*) FROM messages_src").fetchone()[0]
big, small, mid = chats[0], chats[-1], chats[3] # 50 000 / 10 / 1 000 сообщений
deep_ts, deep_id = conn.execute("SELECT created_at, id FROM messages_src WHERE chat_id=%s ORDER BY created_at, id OFFSET 40000 LIMIT 1", (big,)).fetchone()
mid_ts, mid_id = conn.execute("SELECT created_at, id FROM messages_src WHERE chat_id=%s ORDER BY created_at, id OFFSET 500 LIMIT 1", (mid,)).fetchone()
first = "SELECT %s FROM messages WHERE chat_id=%%s ORDER BY created_at, id LIMIT %%s" % COLS
keyset = "SELECT %s FROM messages WHERE chat_id=%%s AND (created_at, id) > (%%s, %%s) ORDER BY created_at, id LIMIT %%s" % COLS
offset = "SELECT %s FROM messages WHERE chat_id=%%s ORDER BY created_at, id OFFSET 40000 LIMIT %%s" % COLS
queries = {
"Q1_first_page_giant_50k": (first, (big, PAGE + 1)),
"Q2_deep_keyset_giant_at_40k": (keyset, (big, deep_ts, deep_id, PAGE + 1)),
"Q3_first_page_tiny_10": (first, (small, PAGE + 1)),
"Q4_keyset_mid_1k_at_500": (keyset, (mid, mid_ts, mid_id, PAGE + 1)),
"Q5_OFFSET_40000_giant": (offset, (big, PAGE + 1)),
}
env = {
"postgres": conn.execute("SHOW server_version").fetchone()[0],
"shared_buffers": conn.execute("SHOW shared_buffers").fetchone()[0],
"work_mem": conn.execute("SHOW work_mem").fetchone()[0],
"fsync": conn.execute("SHOW fsync").fetchone()[0],
"synchronous_commit": conn.execute("SHOW synchronous_commit").fetchone()[0],
"cpus": os.cpu_count(), "python": platform.python_version(), "platform": platform.platform(),
}
results = {"environment": env, "dataset": {"messages": total, "chats": len(SIZES), "chat_size_distribution":
{"50000": 1, "20000": 1, "10000": 1, "1000": 10, "100": 50, "10": 500}, "text_length_chars": "10..400 (равномерно)",
"page_size": PAGE, "read_runs": READ_RUNS, "warmup": WARMUP, "single_inserts": SINGLE_INSERTS,
"bulk_repeats": BULK_REPEATS, "order": "reverse" if args.reverse else "forward"}, "configs": {}}
for name, ddl in (reversed(CONFIGS) if args.reverse else CONFIGS):
print("== %s ==" % name, flush=True)
w = measure_writes(conn, ddl, chats)
r = measure_reads(conn, queries)
results["configs"][name] = {"ddl": ddl, "writes": w, "reads": r}
print(" bulk %.2fs, single p50 %.3f ms, index %.1f MiB; Q1 p50 %.3f ms, Q2 p50 %.3f ms, Q3 p50 %.3f ms" % (
w["bulk_insert_100k_seconds"]["median"], w["single_insert_ms"]["p50"], w["history_index_bytes"] / 2**20,
r["Q1_first_page_giant_50k"]["p50_ms"], r["Q2_deep_keyset_giant_at_40k"]["p50_ms"], r["Q3_first_page_tiny_10"]["p50_ms"]), flush=True)
Path(args.out).parent.mkdir(parents=True, exist_ok=True)
Path(args.out).write_text(json.dumps(results, ensure_ascii=False, indent=2) + "\n")
print("saved", args.out)
if __name__ == "__main__":
main()
+142
View File
@@ -0,0 +1,142 @@
#!/usr/bin/env python3
"""Трек 2 (часть B): backup -> восстановление в НОВОЕ хранилище -> сверка количества и выбранных сообщений.
Источник — БД эксперимента (после track2_indexes.py, 100 000+ сообщений). Приёмник — другой кластер/сервер PostgreSQL
(новый каталог данных, другой порт), т.е. настоящее «новое хранилище», а не вторая БД в том же кластере.
python scripts/track2_restore.py --src-url URL --dst-admin-url URL(postgres db на новом сервере) \
--dst-db messenger_restored --pg-bin /usr/lib/postgresql/16/bin --dump-file /tmp/t2.dump --out evidence/track2-restore.json
Что измеряется: длительность pg_dump и pg_restore (+ ANALYZE), размер дампа, полнота сверки, окно потери данных (RPO):
записи, сделанные ПОСЛЕ начала дампа, в копии отсутствуют; отозванная после дампа сессия в копии «воскресает».
"""
import argparse
import json
import os
import subprocess
import sys
import time
import uuid
from pathlib import Path
from urllib.parse import urlsplit, urlunsplit
import psycopg
def with_db(url, db):
parts = urlsplit(url)
return urlunsplit(parts._replace(path="/" + db))
def facts(conn):
"""Отпечаток состояния: счётчики, md5 содержимого, схема, выбранные строки."""
one = lambda sql, *p: conn.execute(sql, p).fetchone()[0]
out = {"counts": {t: one("SELECT count(*) FROM " + t) for t in ("users", "chats", "chat_members", "messages", "sessions")}}
out["messages_md5"] = one("""SELECT md5(string_agg(id::text || '|' || chat_id::text || '|' || sender_id::text || '|' ||
created_at::text || '|' || md5(text), ',' ORDER BY id)) FROM messages""")
out["per_chat_counts_md5"] = one("SELECT md5(string_agg(chat_id::text || ':' || n, ',' ORDER BY chat_id)) FROM (SELECT chat_id, count(*) n FROM messages GROUP BY chat_id) s")
out["indexes_md5"] = one("SELECT md5(string_agg(indexname || indexdef, E'\\n' ORDER BY indexname)) FROM pg_indexes WHERE schemaname='public'")
out["constraints_md5"] = one("SELECT md5(string_agg(conname || pg_get_constraintdef(oid), E'\\n' ORDER BY conname)) FROM pg_constraint WHERE connamespace = 'public'::regnamespace")
out["migrations"] = [r[0] for r in conn.execute("SELECT version FROM schema_migrations ORDER BY 1").fetchall()]
big = one("SELECT chat_id FROM messages GROUP BY chat_id ORDER BY count(*) DESC, chat_id LIMIT 1")
picks = {
"first_overall": "SELECT * FROM messages ORDER BY created_at, id LIMIT 1",
"last_overall": "SELECT * FROM messages ORDER BY created_at DESC, id DESC LIMIT 1",
"giant_chat_item_15000": "SELECT * FROM messages WHERE chat_id = '%s' ORDER BY created_at, id OFFSET 15000 LIMIT 1" % big,
"longest_text": "SELECT * FROM messages ORDER BY char_length(text) DESC, id LIMIT 1",
"shortest_text": "SELECT * FROM messages ORDER BY char_length(text), id LIMIT 1",
"pseudo_random_by_md5": "SELECT * FROM messages ORDER BY md5(id::text) LIMIT 1",
}
out["selected_messages"] = {k: one("SELECT row_to_json(s)::text FROM (%s) s" % q) for k, q in picks.items()}
return out
def run(cmd, env):
t0 = time.perf_counter()
proc = subprocess.run(cmd, env=env, capture_output=True, text=True)
dt = time.perf_counter() - t0
if proc.returncode:
raise SystemExit("command failed (%s): %s" % (cmd[0], proc.stderr[-800:]))
return dt
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--src-url", required=True)
ap.add_argument("--dst-admin-url", required=True, help="URL БД postgres на НОВОМ сервере (создание БД восстановления)")
ap.add_argument("--dst-db", default="messenger_restored")
ap.add_argument("--pg-bin", default="/usr/lib/postgresql/16/bin")
ap.add_argument("--dump-file", default="/tmp/track2.dump")
ap.add_argument("--out", default="evidence/track2-restore.json")
a = ap.parse_args()
dst_url = with_db(a.dst_admin_url, a.dst_db)
env = dict(os.environ)
with psycopg.connect(a.src_url, autocommit=True) as src:
# 1. Приводим источник к «боевой» схеме: без вспомогательной таблицы, канонический индекс истории, одна сессия.
src.execute("DROP TABLE IF EXISTS messages_src")
src.execute("DROP INDEX IF EXISTS hist_idx")
src.execute("CREATE INDEX IF NOT EXISTS messages_chat_created_id_idx ON messages (chat_id, created_at, id)")
user = src.execute("SELECT id FROM users LIMIT 1").fetchone()[0]
token_hash = os.urandom(32)
src.execute("INSERT INTO sessions (token_hash, user_id, expires_at) VALUES (%s,%s, now() + interval '1 day')", (token_hash, user))
src.execute("VACUUM (ANALYZE)")
before = facts(src)
db_bytes = src.execute("SELECT pg_database_size(current_database())").fetchone()[0]
# 2. Backup: логический, custom-формат; снапшот согласован на момент НАЧАЛА pg_dump.
t_dump = run([a.pg_bin + "/pg_dump", "-Fc", "--no-owner", "-f", a.dump_file, "-d", a.src_url], env)
dump_bytes = Path(a.dump_file).stat().st_size
# 3. Окно потери (RPO): изменения ПОСЛЕ дампа — 500 новых сообщений и отзыв сессии.
chat = src.execute("SELECT chat_id FROM messages LIMIT 1").fetchone()[0]
sender = src.execute("SELECT sender_id FROM messages WHERE chat_id=%s LIMIT 1", (chat,)).fetchone()[0]
for i in range(500):
src.execute("INSERT INTO messages (id, chat_id, sender_id, text) VALUES (%s,%s,%s,%s)", (uuid.uuid4(), chat, sender, "после бэкапа %d" % i))
src.execute("DELETE FROM sessions WHERE token_hash = %s", (token_hash,))
after_source = facts(src)
# 4. Новое хранилище: другая БД на другом сервере.
with psycopg.connect(a.dst_admin_url, autocommit=True) as admin:
admin.execute('DROP DATABASE IF EXISTS "%s"' % a.dst_db)
admin.execute('CREATE DATABASE "%s"' % a.dst_db)
t_restore = run([a.pg_bin + "/pg_restore", "--no-owner", "--exit-on-error", "-d", dst_url, a.dump_file], env)
with psycopg.connect(dst_url, autocommit=True) as dst:
t0 = time.perf_counter()
dst.execute("ANALYZE") # pg_dump не переносит статистику планировщика: без ANALYZE планы могут быть плохими
t_analyze = time.perf_counter() - t0
restored = facts(dst)
plans = {}
big = dst.execute("SELECT chat_id FROM messages GROUP BY chat_id ORDER BY count(*) DESC, chat_id LIMIT 1").fetchone()[0]
plan = dst.execute("EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT id, chat_id, sender_id, text, created_at FROM messages "
"WHERE chat_id=%s ORDER BY created_at, id LIMIT 51", (big,)).fetchone()[0][0]
node = plan["Plan"]
while node.get("Plans"):
node = node["Plans"][0]
plans["first_page_giant"] = {"node": node["Node Type"], "index": node.get("Index Name"), "execution_ms": round(plan["Execution Time"], 3)}
session_present = dst.execute("SELECT count(*) FROM sessions WHERE token_hash=%s", (token_hash,)).fetchone()[0]
# 5. Сверка: копия обязана совпасть с источником НА МОМЕНТ ДАМПА.
checks = {k: before[k] == restored[k] for k in before}
checks["selected_messages"] = {k: before["selected_messages"][k] == restored["selected_messages"][k] for k in before["selected_messages"]}
ok = all(v if isinstance(v, bool) else all(v.values()) for v in checks.values())
rpo = {
"messages_lost_in_restore": after_source["counts"]["messages"] - restored["counts"]["messages"],
"revoked_session_resurrected_in_restore": bool(session_present),
}
result = {
"snapshot_consistent_with_restore": ok, "checks": checks, "rpo_window_observed": rpo,
"timing_seconds": {"pg_dump": round(t_dump, 2), "pg_restore": round(t_restore, 2), "analyze_after_restore": round(t_analyze, 2),
"rto_dump_free_restore_plus_analyze": round(t_restore + t_analyze, 2)},
"sizes_bytes": {"source_database": db_bytes, "dump_file": dump_bytes},
"counts_at_dump": before["counts"], "counts_restored": restored["counts"], "counts_source_after_extra_writes": after_source["counts"],
"restored_plan": plans,
}
Path(a.out).parent.mkdir(parents=True, exist_ok=True)
Path(a.out).write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n")
print(json.dumps(result, ensure_ascii=False, indent=2))
raise SystemExit(0 if ok else 1)
if __name__ == "__main__":
main()
+23
View File
@@ -0,0 +1,23 @@
#!/usr/bin/env python3
"""Full OpenAPI and JSON Schema checks; install requirements-dev.txt first."""
import json
from pathlib import Path
from openapi_spec_validator import validate
from jsonschema import Draft202012Validator
root = Path(__file__).resolve().parents[1]
spec = json.loads((root/'contracts/openapi.json').read_text())
validate(spec)
from referencing import Registry, Resource
# The base URI resolves local #/components references inside examples.
resource = dict(spec, **{'$schema': 'https://json-schema.org/draft/2020-12/schema'})
registry = Registry().with_resource('urn:mtusi:openapi', Resource.from_contents(resource))
for name, example in json.loads((root/'contracts/examples.json').read_text()).items():
schema = {'$ref': 'urn:mtusi:openapi#/components/schemas/' + name}
Draft202012Validator(schema, registry=registry).validate(example)
for path in (root/'contracts').glob('*.schema.json'):
schema = json.loads(path.read_text())
Draft202012Validator.check_schema(schema)
for example in schema.get('examples',[]):
Draft202012Validator(schema).validate(example)
print('PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.')
+57
View File
@@ -0,0 +1,57 @@
# Публичные проверки
Python **3.9+**, стандартная библиотека. Сервер уже должен быть запущен; проверки не создают готовое приложение и сами не управляют Docker. `make check` можно выполнить на исходном skeleton, `make test` — только после реализации API. Полная OpenAPI-валидация отдельно: `make validate` после установки `requirements-dev.txt` в venv.
```sh
make check
make test BASE_URL=http://localhost:8080
# без make:
python3 tests/smoke.py --base-url http://localhost:8080
```
`smoke.py` выполняет **один сквозной сценарий**, автоматически выбирая профиль из `lab.json`: health → три пользователя → вход с lab2 → чат → сообщения → пагинация → ошибки доступа → идемпотентность с lab3 → файл с lab4 → thumbnail с lab5 → logout. Он проверяет JSON по используемому подмножеству схемы, коды/headers, Unicode, SHA-256 оригинала и фактические JPEG-размеры thumbnail. Это публичный минимум, не полный fuzz/security/load suite.
Каждый запуск создаёт уникальных синтетических пользователей, чат и сообщения. Данные автоматически не удаляются: в API курса нет delete. Для чистого повтора используйте отдельный тестовый стенд/volume и осознанный сброс своего окружения. Session tokens хранятся только в памяти процесса и не печатаются/не сохраняются.
## Проверка сохранности, lab2+
Скопируйте `scripts/restart.example.sh` в `scripts/restart.sh`, реализуйте перезапуск **API и всех используемых хранилищ** с сохранением volumes и задайте executable bit. Скрипт может опираться на ваш compose.yaml или stack.yaml. Он не должен удалять volumes, повторно seed-ить БД или менять тестовые данные.
```sh
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
```
Тест создаёт данные и сессию, запускает указанный файл без shell interpolation, ожидает готовности и проверяет те же данные **с прежним токеном**. В lab4+ также проверяется исходный файл. Hook может работать до 90 секунд, готовность затем ожидается до 90 секунд. TTL сессии для этого теста — минимум 300 секунд. Успех не доказывает, что hook действительно перезапустил БД: приложите команды/состояния контейнеров до и после.
## Проверка отказа, lab3+
Реализуйте `scripts/stop-one.sh` на основе примера. `TARGET_INSTANCE_ID` в окружении содержит alias обслужившей тест API-реплики: сопоставьте его своему контейнеру/Swarm task и остановите именно его. Скрипт должен быстро вернуть 0 и **оставить эту реплику остановленной**; восстановление выполняйте отдельно. Swarm может создать новую task с другим ID — это допустимо.
```sh
chmod +x scripts/stop-one.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
```
Перед отказом тест наблюдает ≥2 API-реплики; 15 секунд отправляет сообщения параллельно выполнению hook, повторяет неопределённый POST с тем же ключом, проверяет восстановление записи за ≤10 секунд, отсутствие остановленной реплики в последних ответах, сохранность подтверждённых сообщений и отсутствие дублей. Ошибки переходного периода учитываются. Затем восстановите реплику и повторите для другой. Скрипт — проверка одного отказа API, не гарантия HA БД/LB/host. Вывод hook скрыт, чтобы не утекли секреты; отлаживайте его отдельно с безопасным выводом.
## Нагрузка
```sh
python3 tests/load.py --duration 30 --concurrency 4 --output evidence/load.json
```
Это простой **closed-loop** генератор POST сообщений; он ограничен производительностью клиента и страдает coordinated omission. Он выдаёт successful RPS, ошибки и p50/p95/p99 **только успешных запросов**. Во время нагрузки нет прозрачных retry; timeout мог скрыть совершённую запись, поэтому это throughput HTTP-подтверждений, не точный счётчик COMMIT. Изменение размера истории входит в профиль. Для серьёзного исследования используйте k6/Locust/wrk либо свой обоснованный генератор, а не выводите максимальную пропускную способность из одного запуска этого скрипта. Для нагрузки pipeline изображений нужен отдельный сценарий студента.
## HTTPS, lab7
```sh
make test BASE_URL=https://localhost:8443 CA_FILE=/absolute/path/to/ca.crt
make test-security BASE_URL=https://localhost:8443 CA_FILE=/absolute/path/to/ca.crt
```
Все скрипты принимают `--ca-file`/`CA_FILE` и проверяют серверный сертификат и hostname. `--insecure` отсутствует. TLS-тест сначала проверяет рабочее доверенное соединение, затем намеренно пустой trust store и именно ошибку проверки сертификата; network timeout не засчитывается как правильный отказ. **Внутреннее mTLS, identity/authorization, OpenBao policy и hardening проверяют отдельные тесты студента** по trust matrix. Клиентский сертификат внешнему учебному REST-клиенту не требуется: mTLS находится на внутренних связях.
## Что ещё остаётся доказать
Smoke не доказывает persistence, число реальных контейнеров, durability брокера, outbox, отсутствие утечек/уязвимостей, полноту telemetry или выполнение уровня 4/5. Конкурентные/нагрузочные/негативные проверки своего решения добавляйте отдельно. Список защиты текущей лабы находится в README.md. Проверки рассчитаны на localhost-стенд, не на production.
+217
View File
@@ -0,0 +1,217 @@
"""HTTP helpers for public black-box tests; Python 3.9+, standard library only."""
import base64
import datetime as dt
import hashlib
import json
import os
from pathlib import Path
import re
import ssl
import time
import urllib.error
import urllib.request
import uuid
ROOT = Path(__file__).resolve().parents[1]
LAB = json.loads((ROOT / 'lab.json').read_text())['number']
SPEC = json.loads((ROOT / 'contracts/openapi.json').read_text())
class Failure(AssertionError):
pass
def check(condition, message):
if not condition:
raise Failure(message)
def timestamp(value):
check(isinstance(value, str) and value.endswith('Z'), 'timestamp must be UTC ending in Z')
try:
return dt.datetime.fromisoformat(value[:-1] + '+00:00')
except ValueError as exc:
raise Failure('invalid RFC3339 timestamp') from exc
def validate(value, schema, where='response'):
"""Validate the JSON Schema subset used by the supplied contract, not arbitrary OpenAPI."""
if '$ref' in schema:
target = SPEC
for part in schema['$ref'].split('/')[1:]:
target = target[part]
return validate(value, target, where)
kinds = schema.get('type', [])
if isinstance(kinds, str):
kinds = [kinds]
matches = {'null':value is None, 'boolean':isinstance(value,bool), 'integer':isinstance(value,int) and not isinstance(value,bool), 'number':isinstance(value,(int,float)) and not isinstance(value,bool), 'string':isinstance(value,str), 'array':isinstance(value,list), 'object':isinstance(value,dict)}
if kinds:
check(any(matches.get(k,False) for k in kinds), where + ': incorrect type')
if 'enum' in schema:
check(value in schema['enum'], where + ': invalid enum')
if 'const' in schema:
check(value == schema['const'], where + ': invalid const')
if isinstance(value,dict):
props = schema.get('properties',{})
check(all(k in value for k in schema.get('required',[])), where + ': missing required fields')
if schema.get('additionalProperties') is False:
check(not set(value).difference(props), where + ': unexpected fields')
for key, sub in props.items():
if key in value:
validate(value[key], sub, where + '.' + key)
if isinstance(value,list):
check(len(value) >= schema.get('minItems',0), where + ': too few items')
check(len(value) <= schema.get('maxItems',float('inf')), where + ': too many items')
if schema.get('uniqueItems'):
encoded = [json.dumps(x,sort_keys=True) for x in value]
check(len(encoded)==len(set(encoded)), where + ': duplicate items')
if 'items' in schema:
for item in value:
validate(item, schema['items'], where + '[]')
if isinstance(value,str):
check(len(value) >= schema.get('minLength',0), where + ': too short')
check(len(value) <= schema.get('maxLength',float('inf')), where + ': too long')
if 'pattern' in schema:
check(re.search(schema['pattern'], value) is not None, where + ': pattern mismatch')
if schema.get('format') == 'uuid':
try:
uuid.UUID(value)
except ValueError as exc:
raise Failure(where + ': invalid UUID') from exc
if schema.get('format') == 'date-time':
timestamp(value)
if isinstance(value,(int,float)) and not isinstance(value,bool):
check(value >= schema.get('minimum',-float('inf')), where + ': below minimum')
check(value <= schema.get('maximum',float('inf')), where + ': above maximum')
if 'anyOf' in schema:
for alternative in schema['anyOf']:
try:
validate(value, alternative, where)
break
except Failure:
pass
else:
raise Failure(where + ': no anyOf branch matches')
def shape(value, name):
validate(value, SPEC['components']['schemas'][name])
return value
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
class Client:
def __init__(self, base_url=None, ca_file=None, timeout=10):
self.base = (base_url or os.environ.get('BASE_URL') or ('https://localhost:8443' if LAB==7 else 'http://localhost:8080')).rstrip('/')
check(self.base.startswith(('http://','https://')), 'BASE_URL must be HTTP(S)')
check(LAB != 7 or self.base.startswith('https://'), 'lab7 requires HTTPS')
self.timeout = timeout
context = ssl.create_default_context(cafile=ca_file or os.environ.get('CA_FILE') or None)
self.opener = urllib.request.build_opener(NoRedirect(), urllib.request.HTTPSHandler(context=context))
def call(self, method, path, expected=200, body=None, actor=None, headers=None, raw=None, schema=None):
h = {'Accept':'application/json'}
if actor:
h['X-User-Id' if LAB==1 else 'Authorization'] = actor['id'] if LAB==1 else 'Bearer ' + actor['token']
if body is not None:
raw = json.dumps(body,ensure_ascii=False).encode('utf-8')
h['Content-Type'] = 'application/json'
h.update(headers or {})
req = urllib.request.Request(self.base + path, data=raw, headers=h, method=method)
start = time.monotonic()
try:
response = self.opener.open(req, timeout=self.timeout)
except urllib.error.HTTPError as error:
response = error
except (urllib.error.URLError,TimeoutError,OSError) as exc:
# Do not print URL query, headers, request body, or credentials.
raise Failure(method + ' ' + path.split('?')[0] + ': connection/TLS failure (' + type(exc).__name__ + ')') from None
with response:
status = response.code
rh = response.headers
data = response.read(16*1024*1024 + 1)
check(len(data) <= 16*1024*1024, 'response exceeds test safety limit')
allowed = [expected] if isinstance(expected,int) else expected
check(status in allowed, method + ' ' + path.split('?')[0] + ': expected ' + str(allowed) + ', received ' + str(status))
check(bool(rh.get('X-Request-Id')), 'missing X-Request-Id')
if LAB>=3:
check(bool(rh.get('X-Instance-Id')), 'missing X-Instance-Id')
payload = None
if schema or status>=400:
check(rh.get_content_type()=='application/json', 'expected application/json')
try:
payload = json.loads(data)
except (ValueError,UnicodeError):
raise Failure('invalid response JSON') from None
shape(payload, 'Error' if status>=400 else schema)
if status>=400:
check(payload['error']['request_id']==rh.get('X-Request-Id'),'error request_id differs from header')
if status==401 and LAB>=2:
scheme = 'Basic' if path=='/api/v1/auth/sessions' else 'Bearer'
check(rh.get('WWW-Authenticate','').lower().startswith(scheme.lower()), 'incorrect WWW-Authenticate challenge')
if status==204:
check(not data, '204 must not contain body')
return {'status':status,'headers':rh,'json':payload,'bytes':data,'elapsed':time.monotonic()-start}
def user(self, label):
username = 'u_' + label + '_' + uuid.uuid4().hex[:12]
password = 'T3st-' + uuid.uuid4().hex
body = {'username':username,'display_name':'Студент ' + label}
if LAB>=2:
body['password'] = password
user = self.call('POST','/api/v1/users',201,body=body,schema='User')['json']
check(user['username']==username,'username changed')
actor = {'id':user['id'],'user':user,'registration':body}
if LAB>=2:
credential = base64.b64encode((username+':'+password).encode()).decode()
session = self.call('POST','/api/v1/auth/sessions',201,headers={'Authorization':'Basic '+credential},schema='Session')['json']
check(session['user']==user,'session user mismatch')
check(timestamp(session['expires_at']) > dt.datetime.now(dt.timezone.utc),'session already expired')
actor['token'] = session['token']
return actor
def bootstrap(self):
self.call('GET','/health/live',schema='Health')
self.call('GET','/health/ready',schema='Health')
alice, bob, eve = (self.user(label) for label in ('alice','bob','eve'))
chat = self.call('POST','/api/v1/chats',201,actor=alice,body={'title':'Контрактный тест','member_ids':[alice['id'],bob['id']]},schema='Chat')['json']
check(set(chat['member_ids'])=={alice['id'],bob['id']},'chat member mismatch')
return alice,bob,eve,chat
def message(self, actor, chat, text, key=None, attachments=None):
body = {'text':text}
if attachments is not None:
body['attachment_ids'] = attachments
headers = {'Idempotency-Key':key or uuid.uuid4().hex} if LAB>=3 else {}
return self.call('POST','/api/v1/chats/'+chat['id']+'/messages',201,actor=actor,body=body,headers=headers,schema='Message')
def attachment(self, actor, chat):
content = (ROOT / 'tests/fixtures/sample.png').read_bytes()
att = self.call('POST','/api/v1/chats/'+chat['id']+'/attachments?filename=sample.png',201 if LAB==4 else 202,actor=actor,raw=content,headers={'Content-Type':'image/png'},schema='Attachment')['json']
check(att['status']==('ready' if LAB==4 else 'queued'),'incorrect upload status')
check(att['chat_id']==chat['id'] and att['owner_id']==actor['id'],'attachment ownership mismatch')
check(att['sha256']==hashlib.sha256(content).hexdigest() and att['size_bytes']==len(content),'original checksum/size mismatch')
return att,content
def wait_ready(self, actor, att, wait_seconds=60):
deadline = time.monotonic()+wait_seconds
while time.monotonic()<deadline:
att = self.call('GET','/api/v1/attachments/'+att['id'],actor=actor,schema='Attachment')['json']
check(att['status']!='failed','attachment reached failed')
if att['status']=='ready':
return att
time.sleep(0.3)
raise Failure('attachment did not become ready within test deadline')
def arguments(description, configure=None):
import argparse
p = argparse.ArgumentParser(description=description)
p.add_argument('--base-url', default=None)
p.add_argument('--ca-file', default=None)
if configure:
configure(p)
return p.parse_args()
def run(main):
try:
main()
except (Failure,ValueError,OSError) as exc:
print('FAIL:', str(exc))
raise SystemExit(1)
+58
View File
@@ -0,0 +1,58 @@
#!/usr/bin/env python3
"""Small closed-loop HTTP write benchmark; not an open-loop capacity proof."""
from concurrent.futures import ThreadPoolExecutor
import json
import math
from pathlib import Path
import threading
import time
from client import Client, Failure, LAB, arguments, check, run
def main():
def configure(p):
p.add_argument('--duration',type=float,default=30)
p.add_argument('--concurrency',type=int,default=4)
p.add_argument('--output',default=None,help='Optional JSON metrics, no session tokens')
args = arguments('Synthetic POST message load, closed loop; creates users/messages',configure)
check(1<=args.duration<=3600,'duration must be 1..3600 seconds')
check(1<=args.concurrency<=128,'concurrency must be 1..128')
c = Client(args.base_url,args.ca_file)
alice,bob,eve,chat = c.bootstrap()
barrier = threading.Barrier(args.concurrency)
def worker(worker_id):
local = Client(args.base_url,args.ca_file,timeout=5)
barrier.wait()
deadline = time.monotonic()+args.duration
latencies,errors = [],0
index = 0
while time.monotonic()<deadline:
start = time.monotonic()
try:
local.message(alice,chat,'load-%s-%s' % (worker_id,index))
latencies.append(time.monotonic()-start)
except Failure:
errors += 1
index += 1
return latencies,errors
started = time.monotonic()
with ThreadPoolExecutor(max_workers=args.concurrency) as pool:
results = list(pool.map(worker,range(args.concurrency)))
elapsed = time.monotonic()-started
latencies = sorted(x for values,_ in results for x in values)
errors = sum(n for _,n in results)
total = len(latencies)+errors
def percentile(p):
return round(1000*latencies[max(0,math.ceil(p*len(latencies))-1)],3) if latencies else None
report = {'lab':LAB,'workload':'closed-loop POST messages; no automatic retries','requested_duration_seconds':args.duration,'elapsed_seconds':round(elapsed,3),'concurrency':args.concurrency,'successful_requests':len(latencies),'failed_requests':errors,'error_ratio':round(errors/total,6) if total else None,'successful_rps':round(len(latencies)/elapsed,3),'successful_latency_ms':{'p50':percentile(.50),'p95':percentile(.95),'p99':percentile(.99)},'note':'Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead.'}
text = json.dumps(report,ensure_ascii=False,indent=2)
if args.output:
dest = Path(args.output)
dest.parent.mkdir(parents=True,exist_ok=True)
dest.write_text(text+'\n')
print(text)
check(bool(latencies),'no successful writes')
# Errors are reported, not treated as a universal load-test threshold.
if __name__=='__main__':
run(main)
+129
View File
@@ -0,0 +1,129 @@
#!/usr/bin/env python3
"""Explicit operator-authored hook; tokens remain in memory, volumes are never removed by this test."""
import json
import os
from pathlib import Path
import subprocess
import time
import uuid
from urllib.parse import quote
from client import Client, Failure, LAB, arguments, check, run
def history(c, actor, chat):
path = '/api/v1/chats/'+chat['id']+'/messages?limit=100'
result = []
seen = set()
for _ in range(1000):
page = c.call('GET',path,actor=actor,schema='MessagePage')['json']
result.extend(page['items'])
cursor = page['next_cursor']
if cursor is None:
return result
check(cursor not in seen,'cursor cycle')
seen.add(cursor)
path = '/api/v1/chats/'+chat['id']+'/messages?limit=100&cursor='+quote(cursor,safe='')
raise Failure('history pagination exceeded safety bound')
def main():
def configure(p):
p.add_argument('--mode', choices=['persistence','failover'], required=True)
p.add_argument('--action-script',required=True,help='Executable script authored by student; restarts stack or stops ONE API replica')
args = arguments('Explicit restart/failover scenario; modifies only synthetic API data',configure)
check(LAB>=2,'persistence requires lab2+')
check(args.mode!='failover' or LAB>=3,'failover requires lab3+')
script = Path(args.action_script).expanduser().resolve()
check(script.is_file() and os.access(script,os.X_OK),'action script must exist and be executable (chmod +x)')
check('.example.' not in script.name,'copy and implement the example hook first')
c = Client(args.base_url,args.ca_file,timeout=2)
alice,bob,eve,chat = c.bootstrap()
sent = c.message(alice,chat,'Сохранить при отказе')
original = sent['json']
target = sent['headers'].get('X-Instance-Id','')
attachment = content = None
if LAB>=4:
attachment,content = c.attachment(alice,chat)
if LAB>=5:
attachment = c.wait_ready(alice,attachment)
env = dict(os.environ)
env['TARGET_INSTANCE_ID'] = target
observed = set()
if args.mode=='failover':
for _ in range(40):
observed.add(c.call('GET','/api/v1/users/me',actor=alice,schema='User')['headers']['X-Instance-Id'])
check(len(observed)>=2,'less than two API instances observed before failure; verify LB/session affinity')
print('Executing explicit '+args.mode+' hook; hook output suppressed to avoid leaking secrets.')
# No shell interpolation and no Docker commands in this test.
proc = subprocess.Popen([str(script)],env=env,stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)
started = time.monotonic()
successes,failures,after_instances = [],0,[]
try:
if args.mode=='persistence':
try:
code = proc.wait(timeout=90)
except subprocess.TimeoutExpired:
raise Failure('restart hook exceeded 90 seconds') from None
check(code==0,'restart hook failed (inspect your script locally)')
deadline = time.monotonic()+90
while True:
try:
c.call('GET','/health/ready',schema='Health')
c.call('GET','/api/v1/users/me',actor=alice,schema='User')
break
except Failure:
check(time.monotonic()<deadline,'stack/session did not recover within 90 seconds')
time.sleep(0.5)
else:
first_recovery = None
key = uuid.uuid4().hex
text = 'Запись во время отказа ' + key
while time.monotonic()-started < 15:
code = proc.poll()
check(code is None or code==0,'stop-one hook failed (inspect your script locally)')
check(code is not None or time.monotonic()-started<10,'stop-one hook must return within 10 seconds')
try:
response = c.message(alice,chat,text,key=key)
msg = response['json']
if code==0:
if first_recovery is None:
first_recovery = time.monotonic()-started
after_instances.append(response['headers']['X-Instance-Id'])
successes.append(msg)
key = uuid.uuid4().hex
text = 'Запись во время отказа ' + key
except Failure:
failures += 1
# Keep SAME key/body after an uncertain POST result.
time.sleep(0.1)
check(proc.poll()==0,'stop-one hook did not finish successfully')
check(first_recovery is not None and first_recovery<=10,'writes did not recover within 10 seconds from hook start')
check(len(after_instances)>=5,'too few successful writes after stop')
check(target not in after_instances[-5:],'target replica still serves requests; hook must leave it stopped')
print(json.dumps({'observed_instances_before':len(observed),'successful_writes':len(successes),'failed_attempts':failures,'first_recovery_seconds':round(first_recovery,3)},ensure_ascii=False))
# Existing token, no re-login. Read all confirmations and reject duplicates.
messages = history(c,bob,chat)
ids = [m['id'] for m in messages]
check(len(ids)==len(set(ids)),'duplicated message IDs in history')
check(any(m==original for m in messages),'confirmed pre-failure message lost or altered')
for msg in successes:
check(any(m==msg for m in messages),'confirmed in-flight message lost or altered')
# Bodies are unique in this scenario: an uncertain request may exist once, never twice.
texts = [m['text'] for m in messages]
check(len(texts)==len(set(texts)),'uncertain retry created duplicate message')
if attachment:
c.call('GET','/api/v1/attachments/'+attachment['id'],actor=bob,schema='Attachment')
downloaded = c.call('GET','/api/v1/attachments/'+attachment['id']+'/content',actor=bob)
check(downloaded['bytes']==content,'attachment lost or changed across failure')
print('PASS: '+args.mode+' preserved confirmed data and existing session. Hook scope needs operator evidence.')
finally:
if proc.poll() is None:
proc.terminate()
try:
proc.wait(timeout=5)
except subprocess.TimeoutExpired:
proc.kill()
proc.wait()
if __name__=='__main__':
run(main)
+82
View File
@@ -0,0 +1,82 @@
#!/usr/bin/env python3
"""One complete public acceptance scenario, cumulative by lab number."""
import base64
import hashlib
import uuid
from client import Client, LAB, arguments, check, run, timestamp
def main():
args = arguments('Messenger public smoke; creates synthetic users and messages')
c = Client(args.base_url,args.ca_file)
alice,bob,eve,chat = c.bootstrap()
path = '/api/v1/chats/'+chat['id']
c.call('POST','/api/v1/users',409,body=alice['registration'])
c.call('GET','/api/v1/users/me',401)
c.call('GET',path,404,actor=eve)
me = c.call('GET','/api/v1/users/me',actor=alice,schema='User')['json']
check(me==alice['user'],'current user mismatch')
listed = c.call('GET','/api/v1/chats?limit=100',actor=bob,schema='ChatPage')['json']
check(any(x['id']==chat['id'] for x in listed['items']),'member cannot list chat')
hidden = c.call('GET','/api/v1/chats?limit=100',actor=eve,schema='ChatPage')['json']
check(all(x['id']!=chat['id'] for x in hidden['items']),'chat leaks to outsider')
key = uuid.uuid4().hex
first = c.message(alice,chat,'Привет, мир 👋',key=key)['json']
second = c.message(bob,chat,'Сообщение Боба')['json']
check(first['sender_id']==alice['id'] and second['sender_id']==bob['id'],'sender was not derived from actor')
check(first['chat_id']==second['chat_id']==chat['id'],'wrong chat in message')
check(first['text']=='Привет, мир 👋' and second['text']=='Сообщение Боба','message text changed')
page1 = c.call('GET',path+'/messages?limit=1',actor=bob,schema='MessagePage')['json']
check(len(page1['items'])==1 and page1['next_cursor'],'first page must have one item and cursor')
from urllib.parse import quote
page2 = c.call('GET',path+'/messages?limit=1&cursor='+quote(page1['next_cursor'],safe=''),actor=alice,schema='MessagePage')['json']
check(len(page2['items'])==1 and page2['next_cursor'] is None,'second page must finish history')
ordered = sorted([first,second],key=lambda x:(timestamp(x['created_at']),uuid.UUID(x['id']).int))
check(page1['items']+page2['items']==ordered,'pagination lost, duplicated or reordered a message')
h = {'Idempotency-Key':uuid.uuid4().hex} if LAB>=3 else {}
c.call('POST',path+'/messages',400,actor=alice,body={'text':''},headers=h)
c.call('POST',path+'/messages',404,actor=eve,body={'text':'чужое'},headers=h)
c.call('GET',path+'/messages?limit=0',400,actor=alice)
if LAB>=2:
bad = base64.b64encode((alice['registration']['username']+':wrong-password').encode()).decode()
c.call('POST','/api/v1/auth/sessions',401,headers={'Authorization':'Basic '+bad})
good = base64.b64encode((alice['registration']['username']+':'+alice['registration']['password']).encode()).decode()
c.call('GET','/api/v1/users/me',401,headers={'Authorization':'Basic '+good})
c.call('GET','/api/v1/users/me',401,headers={'X-User-Id':alice['id']})
me = c.call('GET','/api/v1/users/me',actor=alice,headers={'X-User-Id':eve['id']},schema='User')['json']
check(me['id']==alice['id'],'X-User-Id overrode bearer identity')
if LAB>=3:
replay = c.message(alice,chat,first['text'],key=key)['json']
check(replay==first,'idempotency replay differs')
c.call('POST',path+'/messages',409,actor=alice,body={'text':'другой body'},headers={'Idempotency-Key':key})
c.call('POST',path+'/messages',400,actor=alice,body={'text':'без ключа'})
if LAB>=4:
att,content = c.attachment(alice,chat)
# A queued attachment must already be linkable to its own chat.
attached = c.message(alice,chat,'',attachments=[att['id']])['json']
check(attached['attachment_ids']==[att['id']],'message lost attachment')
ready = c.wait_ready(bob,att) if LAB>=5 else att
check(ready['error_code'] is None,'ready attachment has an error')
download = c.call('GET','/api/v1/attachments/'+att['id']+'/content',actor=bob)
check(download['bytes']==content,'download differs from original')
check(download['headers'].get_content_type()=='image/png','original content type mismatch')
for suffix in ('','/content'):
c.call('GET','/api/v1/attachments/'+att['id']+suffix,404,actor=eve)
if LAB>=5:
variants = [x for x in ready['variants'] if x['name']=='thumbnail']
check(len(variants)==1,'expected exactly one thumbnail')
v = variants[0]
check((v['width'],v['height'])==(256,160),'thumbnail metadata has wrong dimensions')
thumb = c.call('GET','/api/v1/attachments/'+att['id']+'/content?variant=thumbnail',actor=bob)
check(thumb['headers'].get_content_type()=='image/jpeg','thumbnail content type mismatch')
check(len(thumb['bytes'])==v['size_bytes'] and hashlib.sha256(thumb['bytes']).hexdigest()==v['sha256'],'thumbnail checksum mismatch')
from image_probe import jpeg_size
check(jpeg_size(thumb['bytes'])==(256,160),'actual JPEG dimensions mismatch')
if LAB>=2:
c.call('DELETE','/api/v1/auth/sessions/current',204,actor=alice)
c.call('GET','/api/v1/users/me',401,actor=alice)
c.call('DELETE','/api/v1/auth/sessions/current',401,actor=alice)
print('PASS: lab%d public API scenario; infrastructure and grading evidence remain separate.' % LAB)
if __name__=='__main__':
run(main)
+162
View File
@@ -0,0 +1,162 @@
"""Собственные тесты (перенесены из lab1; X-User-Id заменён на Bearer, добавлены проверки lab2).
Запуск: pytest tests/test_own.py tests/test_race.py -v (API должен быть запущен на BASE_URL)
"""
import base64
import json
import os
import urllib.error
import urllib.parse
import urllib.request
import uuid
BASE_URL = os.environ.get("BASE_URL", "http://localhost:8080")
PASSWORD = "Correct-horse-battery-1"
def request(method, path, body=None, headers=None):
h = dict(headers or {})
data = None
if body is not None:
data = json.dumps(body).encode()
h["Content-Type"] = "application/json"
req = urllib.request.Request(BASE_URL + path, data=data, method=method, headers=h)
try:
with urllib.request.urlopen(req) as r:
return r.status, r.read()
except urllib.error.HTTPError as e:
return e.code, e.read()
def basic(username, password):
return {"Authorization": "Basic " + base64.b64encode((username + ":" + password).encode()).decode()}
def make_user(prefix="u"):
"""Регистрация + вход. Возвращает пользователя с полями token и auth (заголовок Bearer)."""
username = f"{prefix}{uuid.uuid4().hex[:8]}"
s, b = request("POST", "/api/v1/users", {"username": username, "display_name": "T", "password": PASSWORD})
assert s == 201, b
user = json.loads(b)
s, b = request("POST", "/api/v1/auth/sessions", headers=basic(username, PASSWORD))
assert s == 201, b
user["token"] = json.loads(b)["token"]
user["auth"] = {"Authorization": "Bearer " + user["token"]}
return user
# ---------- тесты lab1 (в новой аутентификации) ----------
def test_invalid_json():
req = urllib.request.Request(BASE_URL + "/api/v1/users", data=b"not json", method="POST",
headers={"Content-Type": "application/json"})
try:
urllib.request.urlopen(req)
assert False
except urllib.error.HTTPError as e:
assert e.code == 400
def test_duplicate_username():
u = make_user("dup")
s, _ = request("POST", "/api/v1/users", {"username": u["username"], "display_name": "X", "password": PASSWORD})
assert s == 409
def test_extra_fields():
s, _ = request("POST", "/api/v1/users", {"username": "ex" + uuid.uuid4().hex[:6], "display_name": "X",
"password": PASSWORD, "extra": 1})
assert s == 400
def test_empty_message():
u = make_user("em")
s, b = request("POST", "/api/v1/chats", {"title": "T", "member_ids": [u["id"]]}, u["auth"])
chat = json.loads(b)
s, _ = request("POST", f"/api/v1/chats/{chat['id']}/messages", {"text": " "}, u["auth"])
assert s == 400
def test_foreign_chat():
u1, u2 = make_user("a"), make_user("b")
s, b = request("POST", "/api/v1/chats", {"title": "T", "member_ids": [u1["id"]]}, u1["auth"])
chat = json.loads(b)
s, _ = request("POST", f"/api/v1/chats/{chat['id']}/messages", {"text": "hi"}, u2["auth"])
assert s == 404
def test_pagination():
u = make_user("pg")
s, b = request("POST", "/api/v1/chats", {"title": "T", "member_ids": [u["id"]]}, u["auth"])
chat = json.loads(b)
for i in range(5):
request("POST", f"/api/v1/chats/{chat['id']}/messages", {"text": f"m{i}"}, u["auth"])
ids, cursor = [], None
while True:
path = f"/api/v1/chats/{chat['id']}/messages?limit=2"
if cursor:
path += "&cursor=" + urllib.parse.quote(cursor, safe="")
s, b = request("GET", path, None, u["auth"])
d = json.loads(b)
ids.extend(m["id"] for m in d["items"])
cursor = d["next_cursor"]
if not cursor:
break
assert len(ids) == 5 and len(set(ids)) == 5
def test_cursor_from_other_chat_is_400():
u = make_user("cur")
chats = []
for t in ("A", "B"):
s, b = request("POST", "/api/v1/chats", {"title": t, "member_ids": [u["id"]]}, u["auth"])
chats.append(json.loads(b))
for i in range(3):
request("POST", f"/api/v1/chats/{chats[-1]['id']}/messages", {"text": f"m{i}"}, u["auth"])
s, b = request("GET", f"/api/v1/chats/{chats[0]['id']}/messages?limit=1", None, u["auth"])
cursor = json.loads(b)["next_cursor"]
assert cursor
s, _ = request("GET", f"/api/v1/chats/{chats[0]['id']}/messages?limit=1&cursor=" + urllib.parse.quote(cursor, safe=""), None, u["auth"])
assert s == 200
s, _ = request("GET", f"/api/v1/chats/{chats[1]['id']}/messages?limit=1&cursor=" + urllib.parse.quote(cursor, safe=""), None, u["auth"])
assert s == 400
# ---------- новое в lab2 ----------
def test_x_user_id_no_longer_grants_access():
u = make_user("xu")
s, _ = request("GET", "/api/v1/users/me", None, {"X-User-Id": u["id"]})
assert s == 401
def test_basic_only_on_login():
u = make_user("bo")
s, _ = request("GET", "/api/v1/users/me", None, basic(u["username"], PASSWORD))
assert s == 401
s, _ = request("POST", "/api/v1/auth/sessions", headers=u["auth"]) # Bearer на /auth/sessions не принимается
assert s == 401
def test_wrong_password_and_unknown_user_look_the_same():
u = make_user("wp")
s1, b1 = request("POST", "/api/v1/auth/sessions", headers=basic(u["username"], "wrong-password-123"))
s2, b2 = request("POST", "/api/v1/auth/sessions", headers=basic("nobody" + uuid.uuid4().hex[:6], "wrong-password-123"))
assert s1 == s2 == 401
assert json.loads(b1)["error"]["message"] == json.loads(b2)["error"]["message"]
def test_logout_revokes_token():
u = make_user("lo")
assert request("GET", "/api/v1/users/me", None, u["auth"])[0] == 200
assert request("DELETE", "/api/v1/auth/sessions/current", None, u["auth"])[0] == 204
assert request("GET", "/api/v1/users/me", None, u["auth"])[0] == 401
def test_password_is_never_returned():
u = make_user("np")
s, b = request("GET", "/api/v1/users/me", None, u["auth"])
assert s == 200 and "password" not in b.decode() and "hash" not in b.decode()
def test_short_password_rejected():
s, _ = request("POST", "/api/v1/users", {"username": "sp" + uuid.uuid4().hex[:6], "display_name": "X", "password": "short"})
assert s == 400
+36
View File
@@ -0,0 +1,36 @@
"""Гонки (перенесено из lab1 + гонка регистрации одинакового username, требуемая уровнем 4)."""
import json
import threading
import uuid
from concurrent.futures import ThreadPoolExecutor
from test_own import PASSWORD, make_user, request
def test_concurrent_writes():
u = make_user("race")
_, b = request("POST", "/api/v1/chats", {"title": "R", "member_ids": [u["id"]]}, u["auth"])
chat = json.loads(b)
def worker(cid):
for i in range(10):
request("POST", f"/api/v1/chats/{chat['id']}/messages", {"text": f"c{cid}-m{i}"}, u["auth"])
threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]
for t in threads:
t.start()
for t in threads:
t.join()
_, b = request("GET", f"/api/v1/chats/{chat['id']}/messages?limit=100", None, u["auth"])
d = json.loads(b)
assert len(d["items"]) == 100, len(d["items"])
assert len({m["id"] for m in d["items"]}) == 100
def test_concurrent_registration_same_username():
"""16 одновременных регистраций одного username: ровно одна успешна, остальные — 409 (решает UNIQUE в БД)."""
body = {"username": "race_" + uuid.uuid4().hex[:12], "display_name": "R", "password": PASSWORD}
with ThreadPoolExecutor(max_workers=16) as pool:
codes = list(pool.map(lambda _: request("POST", "/api/v1/users", body)[0], range(16)))
assert codes.count(201) == 1 and codes.count(409) == 15, codes
+24
View File
@@ -0,0 +1,24 @@
"""Общие помощники собственных тестов; переиспользуют публичный клиент tests/client.py (он не изменялся)."""
import base64
import os
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "tests"))
from client import Client, Failure, check # noqa: E402,F401
BASE = os.environ.get("BASE_URL", "http://localhost:8080")
def client():
return Client(BASE)
def basic(username, password):
return {"Authorization": "Basic " + base64.b64encode((username + ":" + password).encode()).decode()}
def parse_json(response):
"""Публичный клиент парсит тело только при schema=...; для наших проверок нужен JSON всегда."""
import json
return json.loads(response["bytes"]) if response["bytes"] else None
+47
View File
@@ -0,0 +1,47 @@
#!/usr/bin/env python3
"""Откат составной операции создания чата.
Через HTTP «сломать середину» транзакции нельзя (валидация отсекает ошибку раньше),
поэтому вызываем repo.create_chat напрямую с check_members=False: вставка в chats проходит,
а вставка в chat_members падает на внешнем ключе. Ожидаем: в chats не осталось НИЧЕГО.
Требует DATABASE_URL_FILE/DATABASE_URL (как у приложения).
"""
import sys
import uuid
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
import psycopg # noqa: E402
from app import db, repo, security # noqa: E402
def main():
with db.connection() as conn:
creator = repo.insert_user(conn, "rb_" + uuid.uuid4().hex[:12], "Rollback", security.hash_password("Rollback-password-1"))
ghost = uuid.uuid4() # такого пользователя нет -> FK violation на втором INSERT
marker = "rollback-" + uuid.uuid4().hex
try:
with db.connection() as conn:
repo.create_chat(conn, creator["id"], marker, [creator["id"], ghost], check_members=False)
except psycopg.errors.ForeignKeyViolation:
pass
else:
raise SystemExit("FAIL: FK violation не произошёл — тест не проверяет откат")
with db.connection() as conn:
left = conn.execute("SELECT count(*) AS n FROM chats WHERE title = %s", (marker,)).fetchone()["n"]
members = conn.execute("SELECT count(*) AS n FROM chat_members WHERE user_id = %s", (ghost,)).fetchone()["n"]
if left or members:
raise SystemExit("FAIL: после ошибки остались строки: chats=%d members=%d" % (left, members))
# Позитивный контроль: тот же вызов с валидными данными фиксирует и чат, и участников.
with db.connection() as conn:
chat = repo.create_chat(conn, creator["id"], marker + "-ok", [creator["id"]])
with db.connection() as conn:
n = conn.execute("SELECT count(*) AS n FROM chat_members WHERE chat_id = %s", (chat["id"],)).fetchone()["n"]
if n != 1:
raise SystemExit("FAIL: контрольный чат создан без участника")
print("PASS: ошибка внутри транзакции откатила вставку chats (0 строк), контрольный commit сохранил чат и участника")
if __name__ == "__main__":
main()
+109
View File
@@ -0,0 +1,109 @@
#!/usr/bin/env python3
"""Отказ зависимостей: Redis/Valkey (кэш сессий) и PostgreSQL.
Команды управления задаются переменными окружения (по умолчанию — docker compose из корня репозитория):
CACHE_STOP, CACHE_START, CACHE_FLUSH, DB_STOP, DB_START
Ожидания:
* кэш недоступен/сброшен -> API продолжает работать (данные берутся из PostgreSQL), /health/ready = 200;
* PostgreSQL недоступен -> /health/ready = 503, бизнес-запросы = 503 (ограниченная ошибка),
запрос без валидной сессии НИКОГДА не получает 200;
* после восстановления прежний токен и данные на месте.
"""
import os
import shlex
import subprocess
import time
import uuid
from common import Failure, check, client, parse_json
DC = "docker compose --env-file .env"
CMD = {
"CACHE_STOP": os.environ.get("CACHE_STOP", DC + " stop valkey"),
"CACHE_START": os.environ.get("CACHE_START", DC + " start valkey"),
"CACHE_FLUSH": os.environ.get("CACHE_FLUSH", DC + " exec -T valkey sh -c 'REDISCLI_AUTH=$(cat /run/secrets/valkey_password) valkey-cli flushall'"),
"DB_STOP": os.environ.get("DB_STOP", DC + " stop postgres"),
"DB_START": os.environ.get("DB_START", DC + " start postgres"),
}
def run(name):
print(" $", name, flush=True)
r = subprocess.run(CMD[name], shell=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=90)
check(r.returncode == 0, "команда %s завершилась с кодом %d" % (name, r.returncode))
def wait_ready(c, seconds=60):
end = time.monotonic() + seconds
while True:
try:
c.call("GET", "/health/ready", 200)
return
except Failure:
check(time.monotonic() < end, "API не стал ready за %ds" % seconds)
time.sleep(0.5)
def main():
c = client()
alice, bob = c.user("dep_a"), c.user("dep_b")
chat = c.call("POST", "/api/v1/chats", 201, actor=alice, body={"title": "dep", "member_ids": [alice["id"], bob["id"]]}, schema="Chat")["json"]
c.message(alice, chat, "до отказа")
c.call("GET", "/api/v1/users/me", 200, actor=alice) # токен гарантированно в кэше
stray = {"Authorization": "Bearer " + "Z" * 43}
print("1) Valkey остановлен")
run("CACHE_STOP")
try:
for _ in range(3):
c.call("GET", "/health/ready", 200) # кэш — не критичная зависимость
check(c.call("GET", "/api/v1/users/me", 200, actor=alice)["elapsed"] < 2.5, "обход кэша слишком медленный")
c.message(alice, chat, "пока кэш лежит")
c.call("GET", "/api/v1/users/me", 401, headers=stray) # анонимный/чужой токен по-прежнему 401
c.call("GET", "/api/v1/users/me", 401)
new = c.user("dep_new") # вход и регистрация работают без кэша
c.call("GET", "/api/v1/users/me", 200, actor=new)
c.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=new) # logout без кэша: истина в PostgreSQL
c.call("GET", "/api/v1/users/me", 401, actor=new)
finally:
run("CACHE_START")
time.sleep(2.5) # окно circuit breaker
c.call("GET", "/api/v1/users/me", 200, actor=alice)
print("2) Кэш сброшен (FLUSHALL): сессии берутся из PostgreSQL")
run("CACHE_FLUSH")
c.call("GET", "/api/v1/users/me", 200, actor=alice)
c.call("GET", "/api/v1/users/me", 200, actor=bob)
print("3) PostgreSQL остановлен")
run("DB_STOP")
try:
r = c.call("GET", "/health/ready", 503)
check(r["json"]["error"]["code"] == "unavailable", "ready: ожидали code=unavailable")
for path in ("/api/v1/chats", "/api/v1/chats/%s/messages" % chat["id"]):
r = c.call("GET", path, [200, 503], actor=alice)
check(r["status"] == 503, "данные отданы без БД: " + path)
check("psycopg" not in r["bytes"].decode() and "Traceback" not in r["bytes"].decode(), "утечка деталей в 503")
c.call("POST", "/api/v1/users", 503, body={"username": "u" + uuid.uuid4().hex[:10], "display_name": "x", "password": "Password-123456"})
c.call("GET", "/api/v1/users/me", 401) # без токена — всегда 401, не «доверенный аноним»
r = c.call("GET", "/api/v1/users/me", [401, 503], headers=stray)
check(r["status"] != 200, "неизвестный токен принят при недоступной БД")
c.call("GET", "/health/live", 200) # процесс жив, хоть и не ready
finally:
run("DB_START")
wait_ready(c)
print("4) Восстановление")
c.call("GET", "/api/v1/users/me", 200, actor=alice) # тот же токен, без повторного входа
texts = [m["text"] for m in parse_json(c.call("GET", "/api/v1/chats/%s/messages?limit=100" % chat["id"], actor=bob))["items"]]
check(texts == ["до отказа", "пока кэш лежит"], "история изменилась: %s" % texts)
c.message(bob, chat, "после восстановления")
print("PASS: кэш и БД отказывают предсказуемо: кэш обходится, БД -> 503, анонимный доступ невозможен, данные и сессии целы")
if __name__ == "__main__":
try:
main()
except Failure as exc:
print("FAIL:", exc)
raise SystemExit(1)
+36
View File
@@ -0,0 +1,36 @@
#!/usr/bin/env python3
"""Истечение сессии. Запускать против API, поднятого с коротким SESSION_TTL_SECONDS (например 2).
Проверяет и путь «через кэш» (токен успели использовать => он в Valkey), и путь «только PostgreSQL»."""
import sys
import time
import datetime as dt
from common import Failure, basic, check, client
from client import timestamp # доступен через sys.path, настроенный в common
def main():
ttl = float(sys.argv[1]) if len(sys.argv) > 1 else 2.0
c = client()
a = c.user("exp")
# Свежий вход: кэш прогрет логином; затем ещё читаем, чтобы запись точно была в Valkey.
sess = c.call("POST", "/api/v1/auth/sessions", 201, headers=basic(a["registration"]["username"], a["registration"]["password"]), schema="Session")["json"]
lifetime = (timestamp(sess["expires_at"]) - dt.datetime.now(dt.timezone.utc)).total_seconds()
check(lifetime <= ttl + 0.5, "expires_at (%.1f c) не соответствует короткому TTL=%s — сервер запущен с другим SESSION_TTL_SECONDS" % (lifetime, ttl))
h = {"Authorization": "Bearer " + sess["token"]}
c.call("GET", "/api/v1/users/me", 200, headers=h)
c.call("GET", "/api/v1/chats", 200, headers=h)
time.sleep(ttl + 1.5)
c.call("GET", "/api/v1/users/me", 401, headers=h)
c.call("GET", "/api/v1/chats", 401, headers=h)
c.call("DELETE", "/api/v1/auth/sessions/current", 401, headers=h)
print("PASS: сессия с TTL=%ss перестала действовать (401 на users/me, chats, logout) после ожидания %.1fs" % (ttl, ttl + 1.5))
if __name__ == "__main__":
try:
main()
except Failure as exc:
print("FAIL:", exc)
raise SystemExit(1)
+197
View File
@@ -0,0 +1,197 @@
#!/usr/bin/env python3
"""Собственные проверки сверх публичного smoke: гонка регистрации, валидация, пагинация, безопасность."""
import base64
import json
import uuid
from concurrent.futures import ThreadPoolExecutor
from urllib.parse import quote
from common import BASE, Failure, basic, check, client, parse_json
c = client()
RESULTS = []
def jget(path, actor):
return parse_json(c.call("GET", path, 200, actor=actor))
def case(fn):
try:
fn()
RESULTS.append((fn.__name__, "PASS"))
print("PASS", fn.__name__)
except Failure as exc:
RESULTS.append((fn.__name__, "FAIL"))
print("FAIL", fn.__name__, "-", exc)
return fn
def reg(name, pw="Correct-horse-battery-1", display="X", **extra):
return c.call("POST", "/api/v1/users", 201, body={"username": name, "display_name": display, "password": pw, **extra})
@case
def registration_race_same_username():
name = "race_" + uuid.uuid4().hex[:12]
body = {"username": name, "display_name": "Гонка", "password": "Race-password-123"}
def attempt(_):
return c.call("POST", "/api/v1/users", [201, 409], body=body)["status"]
with ThreadPoolExecutor(max_workers=16) as pool:
codes = list(pool.map(attempt, range(16)))
check(codes.count(201) == 1 and codes.count(409) == 15, "ожидали ровно один 201 и 15 конфликтов: %s" % codes)
@case
def username_and_field_validation():
ok = {"display_name": "X", "password": "Correct-horse-battery-1"}
for bad in ("ab", "UPPER_case", "has space", "a" * 33, "name\n", "имя_юзера"): # "name\n" ловит ошибку с «$»
c.call("POST", "/api/v1/users", 400, body={"username": bad, **ok})
base = {"username": "val_" + uuid.uuid4().hex[:10], **ok}
c.call("POST", "/api/v1/users", 400, body={**base, "password": "short"}) # < 12
c.call("POST", "/api/v1/users", 400, body={**base, "password": "x" * 129}) # > 128
c.call("POST", "/api/v1/users", 400, body={**base, "display_name": " "})
c.call("POST", "/api/v1/users", 400, body={**base, "display_name": "x" * 101})
c.call("POST", "/api/v1/users", 400, body={**base, "extra": 1})
c.call("POST", "/api/v1/users", 400, body={**base, "display_name": 5})
c.call("POST", "/api/v1/users", 400, raw=b"{not json", headers={"Content-Type": "application/json"})
c.call("POST", "/api/v1/users", 400, raw=b'{"username":"aaa","username":"bbb"}', headers={"Content-Type": "application/json"})
c.call("POST", "/api/v1/users", 415, raw=b"x", headers={"Content-Type": "text/plain"})
c.call("POST", "/api/v1/users", 413, raw=b"{" + b" " * 70000 + b"}", headers={"Content-Type": "application/json"})
c.call("POST", "/api/v1/users", 400, raw=b'{"username":"aaa","display_name":"\\ud800","password":"Correct-horse-battery-1"}',
headers={"Content-Type": "application/json"}) # одиночный суррогат -> 400, а не 500
c.call("POST", "/api/v1/users", 400, raw=b'{"username":"aaa","display_name":"a\\u0000b","password":"Correct-horse-battery-1"}',
headers={"Content-Type": "application/json"}) # NUL -> 400
@case
def password_with_colon_and_unicode_login():
name = "uni_" + uuid.uuid4().hex[:10]
pw = "парoль:с:двоеточием-🔐-123"
reg(name, pw)
r = c.call("POST", "/api/v1/auth/sessions", 201, headers=basic(name, pw), schema="Session")
check(len(r["json"]["token"]) >= 43, "токен слишком короткий (нужно ≥256 бит)")
c.call("POST", "/api/v1/auth/sessions", 401, headers=basic(name, pw + "x"))
@case
def login_failures_look_identical():
name = "same_" + uuid.uuid4().hex[:10]
reg(name)
a = c.call("POST", "/api/v1/auth/sessions", 401, headers=basic(name, "Wrong-password-123"))
b = c.call("POST", "/api/v1/auth/sessions", 401, headers=basic("nobody_" + uuid.uuid4().hex[:8], "Wrong-password-123"))
check(a["json"]["error"]["code"] == b["json"]["error"]["code"] and
a["json"]["error"]["message"] == b["json"]["error"]["message"], "ответы различаются -> user enumeration")
for headers in ({}, {"Authorization": "Basic !!!not-base64"}, {"Authorization": "Basic " + base64.b64encode(b"nocolon").decode()},
{"Authorization": "Bearer abc"}):
r = c.call("POST", "/api/v1/auth/sessions", 401, headers=headers)
check(r["headers"]["WWW-Authenticate"].startswith("Basic realm=\"messenger\""), "нет Basic challenge")
@case
def bearer_rules():
a = c.user("bearer")
for bad in ({"Authorization": "Bearer " + "A" * 43}, {"Authorization": "Bearer"}, {"Authorization": "Token " + a["token"]},
{"Authorization": "bearer"}):
r = c.call("GET", "/api/v1/users/me", 401, headers=bad)
check(r["headers"]["WWW-Authenticate"] == 'Bearer realm="messenger"', "нет Bearer challenge")
# регистр схемы не важен (RFC 7235), токен в нижнем регистре схемы работает
c.call("GET", "/api/v1/users/me", 200, headers={"Authorization": "bearer " + a["token"]})
for path in ("/api/v1/chats", "/api/v1/chats/" + str(uuid.uuid4())):
c.call("GET", path, 401)
@case
def logout_revokes_only_that_session():
a = c.user("lo")
second = c.call("POST", "/api/v1/auth/sessions", 201, headers=basic(a["registration"]["username"], a["registration"]["password"]), schema="Session")["json"]
c.call("DELETE", "/api/v1/auth/sessions/current", 204, actor=a)
c.call("GET", "/api/v1/users/me", 401, actor=a)
c.call("GET", "/api/v1/users/me", 200, headers={"Authorization": "Bearer " + second["token"]})
@case
def chat_creation_rules_and_no_side_effects():
a, b = c.user("ca"), c.user("cb")
before = len(jget("/api/v1/chats?limit=100", a)["items"])
ghost = str(uuid.uuid4())
for members in ([a["id"], ghost], [a["id"], a["id"]], [b["id"]], [], ["not-a-uuid", a["id"]]):
c.call("POST", "/api/v1/chats", 400, actor=a, body={"title": "t", "member_ids": members})
c.call("POST", "/api/v1/chats", 400, actor=a, body={"title": " ", "member_ids": [a["id"]]})
after = len(jget("/api/v1/chats?limit=100", a)["items"])
check(before == after, "неудачное создание чата оставило следы")
c.call("POST", "/api/v1/chats", 201, actor=a, body={"title": "solo", "member_ids": [a["id"]]}, schema="Chat")
@case
def message_rules():
a, b, e = c.user("ma"), c.user("mb"), c.user("me")
chat = c.call("POST", "/api/v1/chats", 201, actor=a, body={"title": "m", "member_ids": [a["id"], b["id"]]}, schema="Chat")["json"]
p = "/api/v1/chats/%s/messages" % chat["id"]
c.call("POST", p, 400, actor=a, body={"text": " "})
c.call("POST", p, 400, actor=a, body={"text": "x" * 4001})
c.call("POST", p, 201, actor=a, body={"text": "x" * 4000})
c.call("POST", p, 400, actor=a, body={"text": "hi", "sender_id": b["id"]}) # sender_id не принимается
c.call("POST", p, 404, actor=e, body={"text": "hi"})
c.call("POST", p, 404, actor=e, body={"bad": "body"}) # доступ раньше валидации
c.call("POST", "/api/v1/chats/%s/messages" % uuid.uuid4(), 404, actor=a, body={"text": "hi"})
c.call("POST", "/api/v1/chats/not-a-uuid/messages", 400, actor=a, body={"text": "hi"})
c.call("GET", "/api/v1/chats/%s" % chat["id"], 404, actor=e)
c.call("GET", "/api/v1/chats/%s/messages" % chat["id"], 404, actor=e)
@case
def pagination_walk_and_cursor_binding():
a, b = c.user("pa"), c.user("pb")
chats = [c.call("POST", "/api/v1/chats", 201, actor=a, body={"title": "c%d" % i, "member_ids": [a["id"], b["id"]]}, schema="Chat")["json"] for i in (1, 2)]
sent = []
def send(i):
return c.call("POST", "/api/v1/chats/%s/messages" % chats[0]["id"], 201, actor=a if i % 2 else b, body={"text": "m%03d" % i}, schema="Message")["json"]
with ThreadPoolExecutor(max_workers=8) as pool:
sent = list(pool.map(send, range(250)))
seen, cursor, pages = [], None, 0
while True:
url = "/api/v1/chats/%s/messages?limit=%d" % (chats[0]["id"], 100 if pages == 0 else 37) + (("&cursor=" + quote(cursor, safe="")) if cursor else "")
page = c.call("GET", url, actor=b, schema="MessagePage")["json"]
seen += page["items"]; pages += 1; cursor = page["next_cursor"]
if not cursor:
break
ids = [m["id"] for m in seen]
check(len(ids) == 250 and len(set(ids)) == 250, "потеряны/дублируются сообщения: %d" % len(ids))
keys = [(m["created_at"], m["id"]) for m in seen]
check(keys == sorted(keys), "нарушен порядок (created_at, id)")
check({m["id"] for m in sent} == set(ids), "набор сообщений отличается от отправленного")
first = c.call("GET", "/api/v1/chats/%s/messages?limit=1" % chats[0]["id"], actor=a, schema="MessagePage")["json"]["next_cursor"]
c.call("GET", "/api/v1/chats/%s/messages?limit=1&cursor=%s" % (chats[1]["id"], quote(first, safe="")), 400, actor=a) # чужой чат
for junk in ("zzz", "e30", base64.urlsafe_b64encode(b'{"k":"messages"}').decode()):
c.call("GET", "/api/v1/chats/%s/messages?cursor=%s" % (chats[0]["id"], junk), 400, actor=a)
for limit in ("0", "101", "-1", "abc", ""):
c.call("GET", "/api/v1/chats/%s/messages?limit=%s" % (chats[0]["id"], limit), 400, actor=a)
c.call("GET", "/api/v1/chats?limit=1", 200, actor=a, schema="ChatPage")
@case
def chat_list_pagination_and_order():
a, b = c.user("la"), c.user("lb")
ids = [c.call("POST", "/api/v1/chats", 201, actor=a, body={"title": "L%d" % i, "member_ids": [a["id"], b["id"]]}, schema="Chat")["json"]["id"] for i in range(5)]
got, cursor = [], None
while True:
page = c.call("GET", "/api/v1/chats?limit=2" + (("&cursor=" + quote(cursor, safe="")) if cursor else ""), actor=b, schema="ChatPage")["json"]
got += [x["id"] for x in page["items"]]; cursor = page["next_cursor"]
if not cursor:
break
check(got == ids, "порядок/полнота списка чатов нарушены")
c.call("GET", "/api/v1/chats?limit=1&cursor=" + quote(c.call("GET", "/api/v1/chats?limit=1", actor=a, schema="ChatPage")["json"]["next_cursor"], safe=""), 400, actor=b) # курсор другого пользователя
@case
def request_id_and_error_shape():
r = c.call("GET", "/api/v1/nope", 404)
check(r["json"]["error"]["code"] == "not_found", "404 неизвестного маршрута не в формате ошибки")
c.call("PUT", "/api/v1/users", [400, 404, 405])
if __name__ == "__main__":
failed = [n for n, s in RESULTS if s == "FAIL"]
print("\n%d/%d passed" % (len(RESULTS) - len(failed), len(RESULTS)))
raise SystemExit(1 if failed else 0)