forked from mtusi2026/mtusi2026lab2
ЛР 2 — БПИ-2304 — Саламатин — на 4
This commit is contained in:
@@ -0,0 +1,33 @@
|
||||
# Хранение и транзакции
|
||||
|
||||
Схема спроектирована для одного локального стенда: API → PostgreSQL для бизнес-данных; API → Redis для сессий. PostgreSQL и Redis — независимые источники истины для своих данных. История сообщений не кэшируется.
|
||||
|
||||
## Таблицы PostgreSQL
|
||||
|
||||
| Таблица | Назначение и ограничения |
|
||||
| --- | --- |
|
||||
| `schema_migrations` | Имя и SHA-256 применённой миграции; изменение уже применённого SQL запрещено |
|
||||
| `users` | UUID PK, уникальный username, display_name, scrypt-хеш, время регистрации |
|
||||
| `chats` | UUID PK, title, время создания, внутренняя последняя метка сообщения |
|
||||
| `chat_members` | Составной PK `(chat_id, user_id)`, FK на чаты и пользователей |
|
||||
| `messages` | UUID PK, chat_id, sender_id, text, created_at; составной FK `(chat_id, sender_id)` на членство |
|
||||
|
||||
Индекс `chat_members(user_id, chat_id)` выбирает доступные чаты. Индекс `messages(chat_id, created_at, id)` обслуживает равенство по чату, диапазон после курсора и сортировку. Следующая страница использует `(created_at, id) > (%s, %s)` и `LIMIT limit + 1`, без OFFSET и загрузки всей истории. Приложение запрашивает только нужную страницу.
|
||||
|
||||
## Границы транзакций
|
||||
|
||||
- Регистрация: один INSERT, уникальность обеспечивается БД, проигравшая конкурентная запись получает 409.
|
||||
- Создание чата: INSERT чата и всех участников в одной транзакции. Неизвестный участник нарушает FK; вся операция откатывается, включая уже вставленный чат.
|
||||
- Отправка: блокировка строки чата, проверка членства, назначение метки времени, обновление метки и INSERT сообщения в одной транзакции. COMMIT заканчивается до HTTP 201. Составной FK дополнительно запрещает сообщение неучастника.
|
||||
- Чтение: READ COMMITTED. Между HTTP-страницами snapshot отсутствует. В одном чате запись сериализуется блокировкой строки: `max(clock_timestamp(), last_message_at + 1 microsecond)` сохраняет возрастающий порядок даже при совпадении времени или откате часов. Соседние чаты не делят эту блокировку. При откате часов логическое время может опережать часы. Параллельно создаваемые чаты сортируются по назначенному времени; общий snapshot их списка не обещается.
|
||||
- Миграции: advisory lock, проверка контрольной суммы, SQL и регистрация версии в одной транзакции. Для checksum окончания строк приводятся к LF, поэтому checkout Windows не меняет версию миграции. Повторный запуск ничего не вставляет. Миграция запускается отдельным одноразовым сервисом до API.
|
||||
|
||||
## Сессии Redis
|
||||
|
||||
Клиент получает 32 случайных байта в URL-safe base64. Ключ Redis — `session:<sha256(token)>`, значение — UUID пользователя и абсолютное `expires_at`; исходный токен на сервере не сохраняется. `SET ... PXAT` назначает срок в момент создания, чтение его не продлевает. API дополнительно проверяет абсолютную дату. Logout удаляет ключ до ответа 204. При отказе Redis защищённый запрос получает 503, вход по X-User-Id или локальному запасному словарю отсутствует.
|
||||
|
||||
Redis использует именованный volume, AOF, `appendfsync always` и `maxmemory-policy noeviction`. Обычный рестарт и аварийное завершение Redis проверяются отдельно. Потеря/удаление volume не покрывается; PostgreSQL не содержит резервной копии сессий. Потеря любого источника истины делает readiness равным 503; liveness остаётся 200.
|
||||
|
||||
## Пределы ожидания
|
||||
|
||||
PostgreSQL: pool 1–10 соединений, очередь максимум 20, ожидание pool 1 s, connect 2 s, SQL 2 s, блокировка 1 s, TCP keepalive/TCP_USER_TIMEOUT. Redis: максимум 10 соединений, connect/read 1 s, без повторов команды. Общий бюджет HTTP-обработки 5 s. KDF выполняется вне event loop, не более четырёх параллельных вычислений. Секреты читаются из локальных файлов; в логах нет SQL, DSN, паролей, токенов и текстов сообщений.
|
||||
@@ -0,0 +1,52 @@
|
||||
# Защита лабораторной 2
|
||||
|
||||
Целевая оценка — 4. Основа первой работы сохранена: пользователи, чаты, участники, сообщения, проверки доступа и cursor-пагинация. Изменилось хранение и подтверждение личности.
|
||||
|
||||
## Суть решения за минуту
|
||||
|
||||
В первой работе всё лежало в RAM одного процесса и исчезало после рестарта. Теперь бизнес-данные хранятся в PostgreSQL на именованном volume. Redis хранит серверные сессии с TTL и AOF. Регистрация принимает пароль, scrypt сохраняет его хеш. Вход с Basic выдаёт случайный Bearer-токен. По токену сервер находит пользователя, затем отдельно проверяет его участие в чате.
|
||||
|
||||
## Демонстрация
|
||||
|
||||
Из папки проекта:
|
||||
|
||||
```powershell
|
||||
python scripts/init_local.py
|
||||
docker compose --env-file .env up -d --build --wait
|
||||
docker compose --env-file .env build checks
|
||||
python scripts/verify.py --skip-build
|
||||
```
|
||||
|
||||
Команда проверки создаёт только синтетические данные. Она временно останавливает хранилища этого Compose-проекта, восстанавливает их и оставляет основной стенд запущенным. Её выполняют на учебном стенде.
|
||||
|
||||
1. Открыть `docs/DATABASE.md`: показать таблицы, FK, уникальный username и транзакцию создания чата.
|
||||
2. Открыть `evidence/smoke.txt` и `evidence/student-tests.txt`: публичный сценарий, гонка регистрации, rollback, 100 сообщений из 10 клиентов.
|
||||
3. Открыть `scripts/restart.sh`, `evidence/persistence.txt`, `evidence/restart.json`: перезапущены API, PostgreSQL и Redis; `StartedAt` изменился у всех трёх, имена volumes сохранились. Публичный тест использовал старый токен без повторного входа.
|
||||
4. Показать `infra/redis.conf`: `appendonly yes`, `appendfsync always`. В тесте Redis выдерживает также SIGKILL; срок сессии не продлевается.
|
||||
5. Показать `evidence/expiry.json`: отдельный API с TTL=2 возвращает 200 сразу и 401 после 2.3 s. Logout и неверный пароль покрыты интеграционными тестами.
|
||||
6. Показать `evidence/failures.json`: readiness и защищённый запрос дают 503 при отказе каждого хранилища; liveness остаётся 200, X-User-Id не даёт доступ.
|
||||
7. Показать `evidence/explain.txt`: 10 000 сообщений, индекс истории, начало/середина/конец. SQL читает 51 строку, API отдаёт 50 и формирует следующий cursor.
|
||||
|
||||
## Что понимать в коде
|
||||
|
||||
`app/api.py` обрабатывает HTTP, аутентификацию, валидацию, request ID и ошибки. `app/store.py` выполняет SQL и операции Redis. `app/security.py` содержит KDF, разбор Basic/Bearer и подпись курсоров. `app/migrate.py` применяет миграции; `migrations/001_initial.sql` задаёт схему.
|
||||
|
||||
- **COMMIT:** операция PostgreSQL завершена до HTTP 201. В стенде включены `synchronous_commit` и `fsync`; потеря самого диска или volume этим не покрывается.
|
||||
- **Образ, контейнер, volume:** образ содержит код, контейнер запускает процесс, volume хранит данные независимо от жизни контейнера. `down` сохраняет volumes, `down --volumes` удаляет учебные данные.
|
||||
- **Сессии:** Redis — источник истины для них. TTL отвечает за время жизни, AOF — за восстановление после рестарта. Flush/удаление volume уничтожит сессии; одного TTL недостаточно.
|
||||
- **Basic и Bearer:** Basic передаёт username:password в base64 при входе. Bearer — случайный ключ действующей серверной сессии для остальных запросов. Base64 не шифрует пароль.
|
||||
- **Аутентификация и доступ:** действительная сессия определяет пользователя, членство определяет доступ к конкретному чату. Чужой чат возвращает 404.
|
||||
- **Хеш пароля:** scrypt использует соль и затраты CPU/RAM. SHA-256 токена допустим для уже случайного 256-битного значения, но быстрый SHA-256 не заменяет password KDF.
|
||||
- **Гонка username:** проверка SELECT перед INSERT не гарантирует уникальность. Нужен UNIQUE в PostgreSQL; проигравший INSERT превращается в 409.
|
||||
- **Rollback:** INSERT чата и участников выполняются вместе. Ошибка второго участника отменяет первый INSERT, что проверяется прямым подсчётом строк.
|
||||
- **Keyset:** cursor хранит подписанную границу `(created_at, id)` и область чата. B-tree сразу переходит к нужному диапазону. OFFSET заставил бы пропускать предыдущие строки.
|
||||
- **Конкурентная история:** блокировка одной строки чата упорядочивает записи этого чата; разные чаты пишут независимо. Между страницами общего snapshot нет.
|
||||
- **Отказы:** ошибка зависимости даёт ограниченный 503, а не анонимный вход. Один Docker-host и одиночные хранилища не дают высокой доступности.
|
||||
|
||||
## Остановка после защиты
|
||||
|
||||
```powershell
|
||||
docker compose --env-file .env stop
|
||||
# Повторный запуск с прежними данными:
|
||||
docker compose --env-file .env up -d --wait
|
||||
```
|
||||
@@ -0,0 +1,15 @@
|
||||
# Передача работы на площадку
|
||||
|
||||
Рабочая папка — `mtusi2026lab2`. Исходное задание и публичные тесты оставлены в ней. Реализация и доказательства самодостаточны; соседняя первая лабораторная для запуска не нужна.
|
||||
|
||||
Перед публикацией проверить список файлов: в него входят `app/`, `migrations/`, `compose.yaml`, `Dockerfile`, `infra/redis.conf`, `scripts/`, `student-tests/`, `docs/`, `REPORT.md`, `requirements.txt`, `.env.example` и текстовые результаты `evidence/`. Папка `secrets/` и файл `.env` локальные и исключены через `.gitignore`. Volumes находятся в Docker, в репозитории их нет.
|
||||
|
||||
Копировать пароли и токены в описание PR не требуется. Файл `.github/pull_request_template.md` содержит готовое описание реализации и проверок. При переносе файлов в свой fork сохранить executable bit для `scripts/restart.sh`:
|
||||
|
||||
```sh
|
||||
git add .
|
||||
git update-index --chmod=+x scripts/restart.sh
|
||||
git diff --cached --stat
|
||||
```
|
||||
|
||||
Адрес fork, удалённую ветку и PR оформить на Gitea отдельно. Отчёт содержит фактические локальные результаты, оценка выставляется преподавателем после проверки и защиты.
|
||||
Reference in New Issue
Block a user