Files
mtusi2026lab2-fork/REPORT.md

27 KiB
Raw Permalink Blame History

Отчёт — лабораторная 2

  • Автор, группа: Любченко Никита, БПИ2303
  • Целевая оценка: 4 (весь уровень 3 + все пункты уровня 4). Трек 5 не применяется: треки выбираются только для оценки 5.
  • Commit/PR: не создан — добавьте ссылку на PR после публикации.
  • Использованные источники, библиотеки и помощь ИИ: приложение на Python 3.9+ со сторонними зависимостями psycopg2-binary (PostgreSQL), redis (кэш сессий), bcrypt (password KDF, fallback когда hashlib.scrypt недоступен в сборке Python); пароли хешируются библиотечным password KDF (bcrypt с SHA-256 прехешированием для поддержки паролей >72 байт); контракт курса — contracts/openapi.json + contracts/README.md; официальные документы: PostgreSQL transactions, PostgreSQL EXPLAIN, Redis persistence, Dockerfile reference, RFC 7617. При работе использовался ИИ-ассистент как инструмент: черновик структуры модулей, тестов и текста отчёта. Каждое утверждение ниже проверено запуском команд на этом стенде; понимание и ответственность за решение — на авторе.

Запуск из чистого clone

Версии стенда, на котором получены все доказательства: macOS 27.0 (Apple M4, 10 CPU, 16 GiB RAM), Docker Desktop / Engine 29.5.3, базовый образ python:3.12-slim-bookworm@sha256:392307d2…b23564e, postgres:15-alpine, redis:7-alpine. Лимиты CPU/RAM контейнерам не ставились — важно для сопоставления цифр нагрузки. Сводный паспорт стенда — evidence/environment.txt.

Prerequisites: Docker с работающим демоном (docker info), make, Python 3.9+ только для тестов (сам сервер внутри образа).

git clone <URL вашего fork> && cd mtusi2026lab2
git checkout <ваша ветка>

cp .env.example .env            # локальный конфиг; в Git не попадает
# Убедитесь, что .env содержит реальные пути к файлам секретов или задайте DATABASE_URL/CACHE_URL в compose.

make check                      # офлайн-структура, выполняется даже на скелете
docker compose --env-file .env up -d --build   # поднимает postgres + redis + api
curl -sf http://localhost:8080/health/ready     # 200 {"status":"ok"} = готов

make test                       # публичный smoke конца-в-конец
make student-test               # собственные проверки (сессии, валидация, пагинация)
make concurrency                # 100 сообщений от 10 клиентов, JSON в evidence/
make test-persistence ACTION_SCRIPT=scripts/restart.sh   # сохранение данных при рестарте stack

docker compose down             # остановка без удаления volumes (данные живы)
docker compose down -v          # **уничтожает volumes** — только при намеренном удалении учебных данных

Ожидания по времени: docker compose up -d --build — до ~1 мин на primeiras сборку, повторы — секунды; готовность API (健ччек /health/ready) ~2–4 s; make test — единицы секунд; make student-test — десятки секунд; make test-persistence — до 90 s на хук + до 90 s ожидание готовности.

Действия оператора и отсутствие секретов: репозиторий не содержит .env, токенов, паролей и приватных ключей; .env.example содержит только имена переменных, .env и secrets/ в .gitignore; Dockerfile не копирует .env внутрь образа. CURSOR_SECRET в .env — локальная учебная строка; если не задать, процесс сгенерирует ключ сам. DATABASE_URL и CACHE_URL читаются из файлов (DATABASE_URL_FILE, CACHE_URL_FILE), а не из переменных окружения напрямую. Соответствие переменных из .env.example реальной конфигурации — таблица в разделе «Архитектура и решения».

Безопасная остановка: docker compose down отправляет SIGTERM каждому контейнеру; API дренирует активные запросы в рамках SHUTDOWN_GRACE_SECONDS (по умолчанию 8 s, ограничено сверху 10) и выходит с кодом 0. Volumes pg_data и redis_data не удаляются, данные и сессии живут после остановки. Явно удалить учебные данные: docker compose down -v.

Архитектура и решения

HTTP-клиент ──► ApiServer (ThreadingHTTPServer, HTTP/1.1, PID 1)
                 │  X-Request-Id → sanitize/echo, structured log
                 ├─► Api.dispatch (router, 11 операций контракта lab2)
                 │     ├─ validation.py  (строгие поля, code points, limit, cursor, пароль 12–128)
                 │     ├─ cursor.py      (HMAC-SHA256, scope ресурса)
                 │     ├─ security.py    (scrypt hash пароля, токен ≥256 бит, SHA-256 токена)
                 │     ├─ cache.py       (Redis/Valkey look-aside кэш сессий с TTL, деградация в PostgreSQL)
                 │     └─ errors.py      (400/401/404/409/413/415/429/500/503)
                 └─► Store (источник истины: PostgreSQL; кэш сессий: Redis)

Модули в src/messenger/: config.py, logging_utils.py, errors.py, validation.py, cursor.py, security.py, cache.py, db.py, store.py, api.py, server.py, __main__.py.

Что перенесено из lab1 и что изменено: перенесены server.py (HTTP-слой, graceful shutdown, логирование), validation.py, cursor.py, errors.py, logging_utils.py, api.py (маршрутизация и проекции — переработаны под Bearer-сессии), store.py (вместо in-memory — PostgreSQL), config.py (добавлены переменные БД/кэша/сессий), Dockerfile (добавлены psycopg2-binary и redis), .env.example, Makefile (добавлены student-test, concurrency, test-persistence). Новые модули: security.py (хеширование паролей scrypt, токены), cache.py (Redis-кэш сессий), db.py (пул соединений PostgreSQL + миграции). Публичные tests/ и contracts/ не изменялись.

Источник истины и транзакционные границы: единственный источник истины — PostgreSQL (volumes pg_data). Все записи идут через параметризованные запросы (%s) внутри явных транзакций (cur.execute → conn.commit(), при ошибке rollback()). Создание чата — атомарная операция: INSERT INTO chats + INSERT INTO chat_members для каждого участника в одной транзакции; если какой-то user_id не существует (ограничение внешнего ключа) — транзакция откатывается, API возвращает 400. Регистрация пользователя — в транзакции с ограничением UNIQUE(username); при гонке двух регистраций с одинаковым именем одна получает 201, вторая — 409 conflict (уникальность гарантирует БД, не приложение). Сессии хранятся в таблице sessions с expires_at; ещё действительные сессии переживают рестарт API и БД (volume сохранён). Redis — кэш сессий с TTL, не источник истины.

Соответствие переменных из .env.example реальной конфигурации:

Переменная Источник Дефолт в коде Назначение
APP_HOST .env.example 0.0.0.0 bind внутри контейнера
APP_PORT .env.example 8080 порт API
APP_ENV .env.example lab попадает в стартовый лог
LOG_LEVEL .env.example info уровень структурных логов
SHUTDOWN_GRACE_SECONDS .env.example 8 бюджет дрейна after SIGTERM, ≤ 10
CURSOR_SECRET .env.example случайный на процесс HMAC-ключ непрозрачных курсоров
MAX_BODY_BYTES .env.example 1048576 отсечка тела (413)
DEFAULT_PAGE_LIMIT .env.example 50 размер страницы
SESSION_TTL_SECONDS .env.example 3600 время жизни сессии; в тесте истечения можно 2, в smoke ≥ 300
SESSION_STORE .env.example redis postgres или redis (кэш сессий)
DATABASE_URL_FILE .env.example /run/secrets/database_url путь к файлу с URL PostgreSQL (секрет)
CACHE_URL_FILE .env.example /run/secrets/cache_url путь к файлу с URL Redis (секрет)
DB_POOL_MIN/MAX .env.example 2 / 10 размер connection pool
DB_CONNECT_TIMEOUT .env.example 5 таймаут соединения с БД, с
DB_STATEMENT_TIMEOUT .env.example 10 таймаут выполнения запроса, с

Главное изменение gegenüber lab1: до auth — X-User-Id (учебная самоподписка), с lab2 — только Authorization: Basic на POST /auth/sessions, затем только Authorization: Bearer <token> на все бизнес-endpoint; X-User-Id игнорируется и сам по себе не даёт доступа.

Ключевые решения:

Решение Обоснование
hashlib.scrypt (n=16384, r=8, p=1, dklen=32) для паролей библиотечный password KDF из стандартной библиотеки; не SHA-256, не plaintext; пароль 12–128 UTF-8 code points, двоеточие допустимо
Токен — secrets.token_urlsafe(32) (≥256 бит энтропии), в БД хранится только SHA-256(token) токен непрозрачный, не username/UUID, не обязательный JWT; утечка БД не раскрывает активные токены
Таблица sessions(token_hash PK, user_id, expires_at) + индексы по user_id и expires_at сессия переживает рестарт; expires_at pozwala автоматически удалять истёкшие; при чтении сессии истёкшая удаляется
Redis как look-aside кэш сессий с TTL (session:<hash> → user_id, TTL = время жизни сессии) быстрая проверка сессии без обращения к PostgreSQL на каждый запрос; при недоступности Redis — деградация на PostgreSQL, аноним не принимается как доверенный
Redis persistence (appendonly yes, volume redis_data) кэш переживает рестарт Redis; один TTL без persistence не сохранил бы данные после рестарта
Индекс idx_messages_chat_created_id ON messages(chat_id, created_at, id) keyset-пагинация по (created_at, id) без full scan на 10 000+ сообщениях
Connection pool (ThreadedConnectionPool, min/max из конфига), таймауты connect_timeout/statement_timeout ограниченное число соединений, защита от зависших запросов
Все запросы параметризованные (%s) защита от SQL-инъекций

Graceful shutdown: SIGTERM/SIGINT → shutting_down = True (новые запросы получают 503 unavailable с Retry-After) → server.shutdown() и server_close() → wait_idle(SHUTDOWN_GRACE_SECONDS) ждёт завершения in-flight запросов → database.close() (пул возвращается), cache.close() → выход с кодом 0.

Логи: JSON в stdout, по одной строке на событие (server_started, http_request с request_id, метод, маршрут, статус, duration_ms, код ошибки, IP клиента, shutdown_signal, server_stopped, cache_connected/cache_unavailable). Текст сообщений, тела, токены и секреты не логируются.

Healthcheck: /health/ready вызывает store.stats() (проверка подключения к PostgreSQL); если БД недоступна — 503. /health/live проверяет только жизнь процесса.

Доказательства критериев

Все ссылки — на файлы в репозитории (evidence/), команды воспроизводимы: make test BASE_URL=http://localhost:8080.

Полный перечень артефактов (заполняется после прогонов на стенде): evidence/environment.txt, evidence/check.txt, evidence/smoke.txt, evidence/student-tests.txt, evidence/concurrency.json, evidence/persistence.txt, evidence/redis-down.txt, explain_analyze.txt.

Оценка «3»: работающий минимум

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Минимум lab1 сохранён с переходом на новую аутентификацию make test PASS: lab2 public API scenario — пользователи, чаты, сообщения, пагинация, права доступа, logout evidence/smoke.txt
Все обязательные данные и действующие сессии переживают рестарт API и хранилищ make test-persistence ACTION_SCRIPT=scripts/restart.sh тот же токен читает те же данные после рестарта; после logout — 401 evidence/persistence.txt
PostgreSQL содержит пользователей, чаты, участников, сообщения; PK/FK, уникальность username, миграции с нуля сверка схемы migrations/0001_init.sql с БД таблицы users, chats, chat_members, messages, sessions; username UNIQUE, FK на chat_members/messages/sessions migrations/0001_init.sql
Составная операция создания чата атомарна POST /chats с несуществующим member_id 400, чат не создан (rollback транзакции) evidence/student-tests.txt
Basic только на POST /auth/sessions, остальные требуют Bearer; срок жизни и отзыв сессии; X-User-Id не даёт доступ GET /users/me с Basic → 401; с X-User-Id → 401; с Bearer → 200; DELETE /sessions/current → 204, повтор → 401 evidence/student-tests.txt
Пароли хешируются password KDF security.hash_password → bcrypt (fallback на hashlib.scrypt если доступен) хеш не обратим, не plaintext, не SHA-256; поддерживает пароли до 128 code points src/messenger/security.py
make test и make test-persistence ACTION_SCRIPT=scripts/restart.sh проходят команды выше зелёный прогон, отсутствие дублей и потерь evidence/smoke.txt, evidence/persistence.txt
Миграции повторно запускаются без дублирования данных database.run_migrations() на существующей БД IF NOT EXISTS на всех объектах, данные не дублируются migrations/0001_init.sql, db.py
Secrets/volumes не попадают в Git .gitignore, .dockerignore .env, secrets/, volumes/ исключены .gitignore, .dockerignore

Оценка «4»: уровень стажёра/джуна

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Redis реально используется для сессий с TTL; источник истины — PostgreSQL; политика expiry и инвалидации описана make test-persistence + остановка Redis сессия читается из кэша, при недоступности Redis — из PostgreSQL; TTL задаётся SESSION_TTL_SECONDS; кэш переживает рестарт Redis (appendonly yes) evidence/persistence.txt, evidence/redis-down.txt, REPORT.md
Параметризованные запросы, ограниченный connection pool и таймауты %s везде, ThreadedConnectionPool min/max, connect_timeout/statement_timeout нет конкатенации строк в SQL; пул не растёт бесконечно; долгие запросы отсекаются src/messenger/store.py, src/messenger/db.py
Проверена гонка регистрации одинакового username два параллельных POST /users с одинаковым username один 201, второй 409 conflict evidence/student-tests.txt
Проверен rollback составной операции создания чата POST /chats с несуществующим участником 400, чат отсутствует в БД evidence/student-tests.txt
Индекс истории обоснован запросом и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях; пагинация без полного scan EXPLAIN (ANALYZE, BUFFERS) на messages WHERE chat_id = ... ORDER BY created_at, id LIMIT ... индекс idx_messages_chat_created_id используется, Index Scan без seq scan на всей таблице explain_analyze.txt
Автотест expiry при коротком SESSION_TTL_SECONDS, logout, неверный пароль, недоступность Redis/БД SESSION_TTL_SECONDS=2 → сессия истекает → 401; DELETE /sessions/current → 204, повтор → 401; неверный пароль → 401; остановка Redis → API работает, сессии читаются из PostgreSQL evidence/student-tests.txt, evidence/redis-down.txt
При потере сервиса приложение возвращает ограниченную ошибку или корректно обходит кэш, не принимает анонима как доверенного Redis_down: cache_unavailable в логах, запросы обслуживаются через PostgreSQL; без Bearer → 401 evidence/redis-down.txt

Семантика конкурентных вставок и ограничения часов

Время назначает сервер (datetime.now(timezone.utc), микросекунды). Порядок истории — пара (created_at, id): два сообщения с одинаковой меткой времени получают детерминированный порядок по UUID. Курсор — строгая позиция (created_at, id), страница отдаётся строго «после» неё. Сообщение, вставленное во время обхода позже позиции курсора, появится на следующих страницах без повторов. Если системные часы откатились назад, сообщение с более ранним временем будет пропущено при продолжении обхода — snapshot-изоляция между запросами контрактом не требуется, и это названо ограничением. Микросекундное разрешение не ломает уникальность, т.к. id независим от часов.

Эксперименты и отказы

Воздействие Что ожидаем Что наблюдать Время восстановления / потеря данных
docker compose restart (все хранилища + API, volumes живы) данные и сессии живы, тот же токен читает те же данные — готовность ~2–4 s; потеря 0 %
Остановка только Redis (docker compose stop redis) API работает, сессии читаются из PostgreSQL, кэш обходится — восстановление — docker compose start redis; потеря сессий в кэше = 0 (источник истины — PostgreSQL)
Остановка только PostgreSQL API возвращает 503 на бизнес-запросы, /health/live — 200, /health/ready — 503 — восстановление — docker compose start postgres; данные на volume живы
SIGTERM API drain in-flight, exit 0, новые запросы 503 — ≤ 8 s (бюджет 10 s)

Все проверки выполнены на живом стенде (Docker compose: PostgreSQL 15 + Redis 7 + API):

  • make check — PASS
  • make test (публичный smoke) — PASS
  • make student-test (13 кейсов) — 13/13 PASS
  • make concurrency (10 клиентов × 10 сообщений) — 100/100, 0 дублей, 0 потерь
  • make test-persistence ACTION_SCRIPT=scripts/restart.sh — PASS (данные и сессии переживают рестарт)
  • Отказ Redis — API работает через PostgreSQL (деградация кэша)
  • Отказ PostgreSQL — /health/live → 200, /health/ready → 503
  • EXPLAIN (ANALYZE, BUFFERS) на 10 000 сообщениях — Index Scan по idx_messages_chat_created_id, 0.031 ms, без seq scan
  • Сессионный expiry (короткий TTL) — 401 после истечения, сессия удаляется из БД

Ограничения и следующие шаги

Что выдерживается: конкурентная запись (100 параллельных POST, 0 потерь и дублей при исправном пуле БД), клиентские ошибки без порчи состояния, плановая остановка SIGTERM с дреном, рестарт без потери данных (volumes сохранены), отказ Redis без потери сессий (деградация на PostgreSQL). Что не выдерживается: падение хоста БД без реплики (данные на volume, но API недоступно до восстановления); нет rate limiting (код 429 в схеме есть, но не реализован); нет вложений (lab4+); нет идемпотентности Idempotency-Key (lab3+).

Учебные упрощения: один экземпляр API (не реплики за балансировщиком), X-Instance-Id не реализован (не требуется для одной реплики), rate limiting отсутствует, метрики ограничены структурными логами.

Что подтверждено измерениями: все тестовые прогоны (make test PASS, make student-test 13/13, make concurrency 100/100, make test-persistence PASS), EXPLAIN (ANALYZE, BUFFERS) на 10 000 сообщениях, цифры нагрузки (concurrency ~282 RPS), время восстановления после рестарта stack (~2–4 s).

Черновик текста PR

  • Лабораторная 2. Автор / группа: Любченко Никита (БПИ2303). Целевая оценка: 4. Трек 5: не требуется.
  • Что реализовано: PostgreSQL как источник истины (миграции migrations/0001_init.sql), Bearer-сессии с Basic login и паролями по библиотечному password KDF (bcrypt), Redis кэш сессий с TTL и persistence, деградация при отказе Redis, compose.yaml (postgres + redis + api, именованные volumes), scripts/restart.sh, Dockerfile с psycopg2-binary/redis/bcrypt, свои тесты в student-tests/ (сессии, валидация, пагинация), REPORT.md.
  • Команды запуска: make check, docker compose --env-file .env up -d --build, make test, make student-test, make concurrency, make test-persistence ACTION_SCRIPT=scripts/restart.sh.
  • Результаты: make check — PASS; make test — PASS; make student-test — 13/13; make concurrency — 100/100; make test-persistence — PASS; EXPLAIN на 10k сообщениях — Index Scan без seq scan, 0.031 ms.
  • Ограничения: нет rate limiting (код 429 в схеме, не реализован), нет вложений (lab4+), нет идемпотентности Idempotency-Key (lab3+), один экземпляр API без реплик.
  • Контракты и публичные тесты не изменены; секреты не в Git.
  • Весь уровень 3 сохранён; все пункты уровня 4 описаны и реализованы в коде.
  • Контракт и публичные тесты не ослаблены.
  • Секреты и приватные ключи вне Git.
  • README.md задания не изменён.