ЛР2 - БВТ2304 - Жирнова - на 4 #176

Open
Polina_Zhirnova wants to merge 1 commits from Polina_Zhirnova/mtusi2026lab2:master into master
First-time contributor

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

  • Автор, группа: Жирнова Полина БВТ2304.
  • Целевая оценка: 4. Исследовательский трек на 5 не заявлен.
  • Commit/PR: заполнить после публикации.
  • Основа: контракт ЛР2 и Python/FastAPI-реализация из приложенного архива ЛР1.

Запуск

Подробная инструкция: Docker Desktop/Engine с Compose v2 (поддержкой --wait),
Python 3.9+ для внешних проверок. API в образе использует Python 3.12.10.
Образы: postgres:17.5-bookworm, redis:7.4.4-bookworm. Версии закреплены тегами, не digest.
Библиотеки сервера закреплены в requirements.txt, полный проверенный набор — requirements.lock.txt.

python3 scripts/init_env.py
docker compose config --quiet
docker compose up -d --build --wait
python3 tests/smoke.py
python3 scripts/verify.py

Windows: py вместо python3. Проверки запускаются из корня проекта.
Миграции применяются при старте API, вручную создавать таблицы не нужно.
Повторно проверяются контрольные суммы; изменение применённого SQL останавливает старт.
Локальный .env создаётся один раз со случайными паролем PostgreSQL и ключом подписи cursor.
Файлы секретов также поддерживаются для DATABASE_URL, CACHE_URL, CURSOR_SECRET через суффикс _FILE.
Compose передаёт эти значения через environment. APP_HOST и APP_PORT читает run.py;
APP_ENV=lab — обозначение среды, поведение не переключает. SESSION_STORE не используется:
источник сессий всегда PostgreSQL. CACHE_URL — адрес Redis, не хранилища сессий.

Остановка: docker compose down. Возобновление: docker compose up -d --wait.
Намеренное удаление всех учебных данных: docker compose down -v. Для рестарта не использовать.
PostgreSQL и Redis не публикуют порты на хост; API опубликован только на 127.0.0.1.
API работает под UID 10001. Пользователь PostgreSQL в учебном образе владеет БД;
разделение роли мигратора и ограниченной роли приложения — дальнейшее улучшение.

Архитектура и схема

Клиент обращается к API. API проверяет сессию в PostgreSQL и участника в members.
Все важные данные и действующие сессии — в PostgreSQL. Redis содержит только
неизменяемые публичные профили (profile:v1:<uuid>, TTL 60 секунд).
История не кэшируется; read-after-write обеспечивается чтением той же основной БД после COMMIT.

Таблица Ключи и ограничения Назначение
users PK id; UNIQUE username; CHECK формата имени Пользователь и Argon2id-хеш
sessions PK token_hash; FK user_id → users Пропуск и абсолютный expires_at
chats PK id Чат
members PK(chat_id,user_id); FK в chats и users Состав чата
messages PK id; FK chat_id, sender_id; составной FK(chat_id,sender_id) → members Сообщения участников
schema_migrations PK version; checksum Версии структуры

Индексы: messages_history(chat_id,created_at,id), members_user(user_id,chat_id),
chats_order(created_at,id), sessions_expiry(expires_at), плюс индексы PK и UNIQUE.
Индекс сессий по сроку оставлен для будущей пакетной очистки; текущий доступ идёт по PK токена.
Строковые поля, размеры, JSON и UUID проверяются API. БД дополнительно защищает
уникальность имён, обязательные поля и связи даже при конкурирующих запросах.

Транзакционные границы

Регистрация — один INSERT, конфликт UNIQUE становится 409.
Чат + все members — одна транзакция: отсутствующий пользователь вызывает FK violation,
и весь чат откатывается. Сообщение — отдельный INSERT/COMMIT до ответа 201.
Вход — проверка хеша вне соединения БД, затем INSERT сессии; выход — DELETE/COMMIT.
Миграции — транзакция с advisory lock, последовательностью версий и контрольными суммами.
Обычная изоляция — READ COMMITTED. Явные глобальные Python-lock больше не нужны.

В ЛР1 сохранены формы объектов, Unicode, ограничения полей, права участников, ошибки,
request ID и keyset-пагинация. Изменены регистрация (добавлен пароль), идентификация
(Bearer вместо X-User-Id), хранилище и управление конкурентностью. Старые in-memory
лимиты количества пользователей/сообщений и локальный rate limiter не переносились.
Автоматический импорт содержимого ЛР1 не реализован и заданием не требуется.

Кэш, сессии и отказ

Кэш не участвует в решении о доступе. Сессия каждый раз проверяется в PostgreSQL;
её expires_at вычисляется временем БД. Logout удаляет запись, expiry не продлевается.
Токен — secrets.token_urlsafe(32), хранится только SHA-256 случайного токена.
Пароли — Argon2id, параметры time_cost=2, memory_cost=19456 KiB, parallelism=1.

У профиля нет API изменения/удаления: естественная инвалидация — TTL 60 секунд.
При добавлении PATCH профиля понадобится стратегия сброса/версионирования кэша.
Redis можно очистить: профили восстановятся из PostgreSQL. AOF и volume включены,
но корректность приложения не зависит от сохранности кэша.

Пул PostgreSQL: 1–10 соединений, до 32 ожидающих, pool timeout 3 s,
connect timeout 3 s, statement timeout 3 s, lock timeout 2 s.
Redis: максимум 16 соединений, connect/read timeout 0.2 s, без автоматических повторов.
При ошибке Redis чтение профиля идёт в PostgreSQL. При ошибке PostgreSQL — 503.
Это не жёсткий общий дедлайн всего HTTP-запроса; отдельные ожидания могут суммироваться.
Парольные операции: до четырёх одновременно, очередь допуска ожидания до 1 s.

Пагинация

История: WHERE chat_id=%s AND (created_at,id)>(%s,%s) ORDER BY created_at,id LIMIT %s.
Параметры передаются Psycopg отдельно от SQL. Cursor содержит scope, время, UUID и HMAC;
ключ подписи сохраняется в .env, поэтому курсор не ломается от обычного рестарта.
Для next_cursor читается limit+1. OFFSET в endpoint отсутствует.
В конкурентной истории нет общего snapshot между страницами. Поздний COMMIT записи
с более ранним created_at или перевод часов назад может поместить её до уже выданной закладки.
На неизменной истории порядок стабилен; UUID разрешает совпадения timestamp.

Выполненные проверки и границы доказательств

В среде подготовки Docker отсутствовал. Проверки выполнены с настоящими локальными
процессами PostgreSQL 17.11, Redis 8.0.2, Python 3.12, с закреплёнными библиотеками API.
Это не запуск контейнеров с версиями из compose.yaml. Docker build, compose up,
scripts/verify.py и публичный tests/resilience.py с Docker-hook здесь не запускались.
Их требуется выполнить на компьютере студентки. Ниже native означает реальные отдельные
процессы с постоянным каталогом данных, не mocks и не SQLite.

Критерий Команда/сценарий Полученный результат Доказательство
Основной API, неправильный пароль, logout, X-User-Id tests/smoke.py PASS на native-стенде evidence/local-integration.txt
Повторное применение миграций student-tests/database.py PASS, два повторных вызова evidence/local-explain-and-rollback.txt
Гонка одинакового username student-tests/extra.py, 4 параллельных запроса один 201, три 409 evidence/local-integration.txt
Откат составной операции student-tests/database.py число чатов не изменилось после FK failure evidence/local-explain-and-rollback.txt
Redis реально используется проверка EXISTS ключа профиля PASS evidence/local-integration.txt
Сохранность данных/сессий native_verify.py: остановка и запуск всех трёх процессов прежний токен читает прежнее сообщение evidence/local-integration.txt
Короткий TTL student-tests/expiry.py, API с TTL=2 сначала 200, через 2.5 s — 401 evidence/local-integration.txt
Отказ Redis native_verify.py: остановка процесса 200 из БД, неизвестный токен 401 evidence/local-integration.txt
Отказ БД native_verify.py: остановка процесса защищённый запрос 503; live 200; ready 503 evidence/local-integration.txt
Индекс истории, ≥10 000 сообщений EXPLAIN ANALYZE BUFFERS, 12 000 сообщений, страница после 9001-й строки Index Scan по messages_history evidence/local-explain-and-rollback.txt
JSON, границы, пароль UTF-8 с двоеточием, чужой cursor student-tests/extra.py PASS evidence/local-integration.txt
Неизменность задания/контракта/public tests побайтовая сверка с архивом skeleton PASS evidence/protected-files.sha256
Полный Compose и Docker restart hook scripts/verify.py и tests/resilience.py выполнить локально evidence/compose-verification.txt и restart-before/after.txt после запуска

Native-методика сохранена в student-tests/native_verify.py. Она принимает пути через
PG_BIN, REDIS_SERVER, NATIVE_DATA; запускается Python из окружения requirements.txt.
PG_BIN — каталог с postgres и initdb. NATIVE_DATA — отдельная папка временного стенда.
Пример Linux: PG_BIN=/path/to/pgsql/bin REDIS_SERVER=/path/to/redis-server NATIVE_DATA=/tmp/lab2-test .venv/bin/python student-tests/native_verify.py.
Библиотеки ОС для выбранных бинарников должны быть установлены. Рекомендуемый для сдачи путь — Compose.

Эксперимент SQL использует 12 000 синтетических сообщений в одном чате, ANALYZE,
затем запрос страницы 51 запись после 9001-й. Синтетические строки откатываются.
Результат доказывает выбор индекса для данного набора, но не производительность при боевой нагрузке.
Нагрузочный эксперимент, p95/p99, CPU/RAM и аппаратная ёмкость не заявляются.
Время отказов из лога — единичный локальный замер, не SLA и не верхняя гарантия задержки.

Ограничения

Один PostgreSQL и один хост: отказ БД временно делает API неготовым. Репликации, failover,
backup и восстановления на другой диск нет. COMMIT использует обычные durability-настройки PostgreSQL;
сохранение volume не защищает от удаления volume или потери физического диска.
Нет UI, вложений, очередей, идемпотентных повторов сообщений и исследовательского трека 5.
Истёкшие сессии проверяются корректно, но автоматическая уборка строк пока не реализована.
Ограничен размер тела JSON, но отдельный timeout медленной загрузки тела не реализован.
Учебный HTTP предназначен только для localhost; для удалённого доступа нужен TLS.
Не публиковать .env, реальные пароли, токены и полные дампы БД.

Источники и библиотеки

# Отчёт — лабораторная 2 - Автор, группа: Жирнова Полина БВТ2304. - Целевая оценка: **4**. Исследовательский трек на 5 не заявлен. - Commit/PR: заполнить после публикации. - Основа: контракт ЛР2 и Python/FastAPI-реализация из приложенного архива ЛР1. ## Запуск Подробная инструкция: Docker Desktop/Engine с Compose v2 (поддержкой --wait), Python 3.9+ для внешних проверок. API в образе использует Python 3.12.10. Образы: postgres:17.5-bookworm, redis:7.4.4-bookworm. Версии закреплены тегами, не digest. Библиотеки сервера закреплены в requirements.txt, полный проверенный набор — requirements.lock.txt. ```sh python3 scripts/init_env.py docker compose config --quiet docker compose up -d --build --wait python3 tests/smoke.py python3 scripts/verify.py ``` Windows: `py` вместо `python3`. Проверки запускаются из корня проекта. Миграции применяются при старте API, вручную создавать таблицы не нужно. Повторно проверяются контрольные суммы; изменение применённого SQL останавливает старт. Локальный .env создаётся один раз со случайными паролем PostgreSQL и ключом подписи cursor. Файлы секретов также поддерживаются для DATABASE_URL, CACHE_URL, CURSOR_SECRET через суффикс _FILE. Compose передаёт эти значения через environment. APP_HOST и APP_PORT читает run.py; APP_ENV=lab — обозначение среды, поведение не переключает. SESSION_STORE не используется: источник сессий всегда PostgreSQL. CACHE_URL — адрес Redis, не хранилища сессий. Остановка: `docker compose down`. Возобновление: `docker compose up -d --wait`. **Намеренное удаление всех учебных данных: `docker compose down -v`.** Для рестарта не использовать. PostgreSQL и Redis не публикуют порты на хост; API опубликован только на 127.0.0.1. API работает под UID 10001. Пользователь PostgreSQL в учебном образе владеет БД; разделение роли мигратора и ограниченной роли приложения — дальнейшее улучшение. ## Архитектура и схема Клиент обращается к API. API проверяет сессию в PostgreSQL и участника в members. Все важные данные и действующие сессии — в PostgreSQL. Redis содержит только неизменяемые публичные профили (`profile:v1:<uuid>`, TTL 60 секунд). История не кэшируется; read-after-write обеспечивается чтением той же основной БД после COMMIT. | Таблица | Ключи и ограничения | Назначение | | --- | --- | --- | | users | PK id; UNIQUE username; CHECK формата имени | Пользователь и Argon2id-хеш | | sessions | PK token_hash; FK user_id → users | Пропуск и абсолютный expires_at | | chats | PK id | Чат | | members | PK(chat_id,user_id); FK в chats и users | Состав чата | | messages | PK id; FK chat_id, sender_id; составной FK(chat_id,sender_id) → members | Сообщения участников | | schema_migrations | PK version; checksum | Версии структуры | Индексы: messages_history(chat_id,created_at,id), members_user(user_id,chat_id), chats_order(created_at,id), sessions_expiry(expires_at), плюс индексы PK и UNIQUE. Индекс сессий по сроку оставлен для будущей пакетной очистки; текущий доступ идёт по PK токена. Строковые поля, размеры, JSON и UUID проверяются API. БД дополнительно защищает уникальность имён, обязательные поля и связи даже при конкурирующих запросах. ### Транзакционные границы Регистрация — один INSERT, конфликт UNIQUE становится 409. Чат + все members — одна транзакция: отсутствующий пользователь вызывает FK violation, и весь чат откатывается. Сообщение — отдельный INSERT/COMMIT до ответа 201. Вход — проверка хеша вне соединения БД, затем INSERT сессии; выход — DELETE/COMMIT. Миграции — транзакция с advisory lock, последовательностью версий и контрольными суммами. Обычная изоляция — READ COMMITTED. Явные глобальные Python-lock больше не нужны. В ЛР1 сохранены формы объектов, Unicode, ограничения полей, права участников, ошибки, request ID и keyset-пагинация. Изменены регистрация (добавлен пароль), идентификация (Bearer вместо X-User-Id), хранилище и управление конкурентностью. Старые in-memory лимиты количества пользователей/сообщений и локальный rate limiter не переносились. Автоматический импорт содержимого ЛР1 не реализован и заданием не требуется. ### Кэш, сессии и отказ Кэш не участвует в решении о доступе. Сессия каждый раз проверяется в PostgreSQL; её expires_at вычисляется временем БД. Logout удаляет запись, expiry не продлевается. Токен — secrets.token_urlsafe(32), хранится только SHA-256 случайного токена. Пароли — Argon2id, параметры time_cost=2, memory_cost=19456 KiB, parallelism=1. У профиля нет API изменения/удаления: естественная инвалидация — TTL 60 секунд. При добавлении PATCH профиля понадобится стратегия сброса/версионирования кэша. Redis можно очистить: профили восстановятся из PostgreSQL. AOF и volume включены, но корректность приложения не зависит от сохранности кэша. Пул PostgreSQL: 1–10 соединений, до 32 ожидающих, pool timeout 3 s, connect timeout 3 s, statement timeout 3 s, lock timeout 2 s. Redis: максимум 16 соединений, connect/read timeout 0.2 s, без автоматических повторов. При ошибке Redis чтение профиля идёт в PostgreSQL. При ошибке PostgreSQL — 503. Это не жёсткий общий дедлайн всего HTTP-запроса; отдельные ожидания могут суммироваться. Парольные операции: до четырёх одновременно, очередь допуска ожидания до 1 s. ### Пагинация История: `WHERE chat_id=%s AND (created_at,id)>(%s,%s) ORDER BY created_at,id LIMIT %s`. Параметры передаются Psycopg отдельно от SQL. Cursor содержит scope, время, UUID и HMAC; ключ подписи сохраняется в .env, поэтому курсор не ломается от обычного рестарта. Для next_cursor читается limit+1. OFFSET в endpoint отсутствует. В конкурентной истории нет общего snapshot между страницами. Поздний COMMIT записи с более ранним created_at или перевод часов назад может поместить её до уже выданной закладки. На неизменной истории порядок стабилен; UUID разрешает совпадения timestamp. ## Выполненные проверки и границы доказательств В среде подготовки **Docker отсутствовал**. Проверки выполнены с настоящими локальными процессами PostgreSQL **17.11**, Redis **8.0.2**, Python **3.12**, с закреплёнными библиотеками API. Это не запуск контейнеров с версиями из compose.yaml. Docker build, `compose up`, `scripts/verify.py` и публичный `tests/resilience.py` с Docker-hook **здесь не запускались**. Их требуется выполнить на компьютере студентки. Ниже native означает реальные отдельные процессы с постоянным каталогом данных, не mocks и не SQLite. | Критерий | Команда/сценарий | Полученный результат | Доказательство | | --- | --- | --- | --- | | Основной API, неправильный пароль, logout, X-User-Id | tests/smoke.py | PASS на native-стенде | evidence/local-integration.txt | | Повторное применение миграций | student-tests/database.py | PASS, два повторных вызова | evidence/local-explain-and-rollback.txt | | Гонка одинакового username | student-tests/extra.py, 4 параллельных запроса | один 201, три 409 | evidence/local-integration.txt | | Откат составной операции | student-tests/database.py | число чатов не изменилось после FK failure | evidence/local-explain-and-rollback.txt | | Redis реально используется | проверка EXISTS ключа профиля | PASS | evidence/local-integration.txt | | Сохранность данных/сессий | native_verify.py: остановка и запуск всех трёх процессов | прежний токен читает прежнее сообщение | evidence/local-integration.txt | | Короткий TTL | student-tests/expiry.py, API с TTL=2 | сначала 200, через 2.5 s — 401 | evidence/local-integration.txt | | Отказ Redis | native_verify.py: остановка процесса | 200 из БД, неизвестный токен 401 | evidence/local-integration.txt | | Отказ БД | native_verify.py: остановка процесса | защищённый запрос 503; live 200; ready 503 | evidence/local-integration.txt | | Индекс истории, ≥10 000 сообщений | EXPLAIN ANALYZE BUFFERS, 12 000 сообщений, страница после 9001-й строки | Index Scan по messages_history | evidence/local-explain-and-rollback.txt | | JSON, границы, пароль UTF-8 с двоеточием, чужой cursor | student-tests/extra.py | PASS | evidence/local-integration.txt | | Неизменность задания/контракта/public tests | побайтовая сверка с архивом skeleton | PASS | evidence/protected-files.sha256 | | Полный Compose и Docker restart hook | scripts/verify.py и tests/resilience.py | **выполнить локально** | evidence/compose-verification.txt и restart-before/after.txt после запуска | Native-методика сохранена в student-tests/native_verify.py. Она принимает пути через PG_BIN, REDIS_SERVER, NATIVE_DATA; запускается Python из окружения requirements.txt. PG_BIN — каталог с postgres и initdb. NATIVE_DATA — отдельная папка временного стенда. Пример Linux: `PG_BIN=/path/to/pgsql/bin REDIS_SERVER=/path/to/redis-server NATIVE_DATA=/tmp/lab2-test .venv/bin/python student-tests/native_verify.py`. Библиотеки ОС для выбранных бинарников должны быть установлены. Рекомендуемый для сдачи путь — Compose. Эксперимент SQL использует 12 000 синтетических сообщений в одном чате, ANALYZE, затем запрос страницы 51 запись после 9001-й. Синтетические строки откатываются. Результат доказывает выбор индекса для данного набора, но не производительность при боевой нагрузке. Нагрузочный эксперимент, p95/p99, CPU/RAM и аппаратная ёмкость не заявляются. Время отказов из лога — единичный локальный замер, не SLA и не верхняя гарантия задержки. ## Ограничения Один PostgreSQL и один хост: отказ БД временно делает API неготовым. Репликации, failover, backup и восстановления на другой диск нет. COMMIT использует обычные durability-настройки PostgreSQL; сохранение volume не защищает от удаления volume или потери физического диска. Нет UI, вложений, очередей, идемпотентных повторов сообщений и исследовательского трека 5. Истёкшие сессии проверяются корректно, но автоматическая уборка строк пока не реализована. Ограничен размер тела JSON, но отдельный timeout медленной загрузки тела не реализован. Учебный HTTP предназначен только для localhost; для удалённого доступа нужен TLS. Не публиковать .env, реальные пароли, токены и полные дампы БД. ## Источники и библиотеки - Задание: README.md, contracts/README.md, contracts/openapi.json. - Psycopg pool и транзакции: https://www.psycopg.org/psycopg3/docs/advanced/pool.html - PostgreSQL составные индексы: https://www.postgresql.org/docs/17/indexes-multicolumn.html - Redis asyncio: https://redis.readthedocs.io/en/v6.4.0/examples/asyncio_examples.html - FastAPI/Uvicorn — HTTP; Psycopg — SQL/pool; redis-py — кэш; argon2-cffi — password KDF.
Polina_Zhirnova added 1 commit 2026-11-13 11:03:36 +03:00
merge done project from github
Skeleton contracts / contracts (pull_request) Canceled after 0s
256d8b9035
Some required checks failed
1 workflow awaiting approval

The workflow will only run after approval from the repository maintainer.

Skeleton contracts / contracts (pull_request) Canceled after 0s
You are not authorized to merge this pull request.
This pull request can be merged automatically.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u https://gitea.privcloud.tech/Polina_Zhirnova/mtusi2026lab2 master:Polina_Zhirnova-master
git checkout Polina_Zhirnova-master
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mtusi2026/mtusi2026lab2#176