27 KiB
Отчёт — лабораторная 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— PASSmake test(публичный smoke) — PASSmake student-test(13 кейсов) — 13/13 PASSmake 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-сессии сBasiclogin и паролями по библиотечному 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задания не изменён.