Описать запуск и доказательства лабораторной 2

This commit is contained in:
Dima
2026-09-23 21:58:04 +03:00
parent c6db0aa71a
commit fd4bf013bb
+56 -19
View File
@@ -1,37 +1,74 @@
# Отчёт — лабораторная 2
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Гришко Дмитрий Михайлович, БВТ2303
- Целевая оценка: **3**
- Ветка: `solution/BVT2303-grishko`
- Источники: [задание](README.md), [контракт](contracts/README.md), [проверки](tests/README.md), [golang-migrate](https://github.com/golang-migrate/migrate), документация PostgreSQL и Go
- Зависимости: Go 1.22.2, PostgreSQL 16.10, `pgx/v5`, `golang-migrate/v4`, `x/crypto/scrypt`, `google/uuid`; помощь ИИ: OpenAI Codex — реализация и проверка кода
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Нужны Docker Engine с Compose, Python 3.9+ и Make. Go нужен для `go test ./...` вне контейнера. Команды приведены для Linux/WSL в корне репозитория.
```sh
cp .env.example .env
sed -i "s/replace-with-local-random-password/$(openssl rand -hex 24)/" .env
make check
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
go test ./...
```
`.env` содержит локальный пароль и исключён из Git. База доступна только внутри Compose-сети; HTTP API опубликован на `127.0.0.1:8080`. Миграции `up` применяются автоматически перед запуском HTTP-сервера. Они встроены в бинарник из `src/migrations`. Применение вручную: `docker compose --env-file .env run --rm --no-deps api migrate up` при уже запущенной БД. Откат **одной** версии, удаляющий таблицы и данные этой начальной миграции, выполняется только сознательно при остановленном API: `docker compose --env-file .env stop api`, затем `docker compose --env-file .env run --rm --no-deps api migrate down`.
Безопасная остановка: `docker compose --env-file .env down` — volume сохранится. Намеренное удаление учебных данных: `docker compose --env-file .env down -v`. После смены пароля в `.env` для уже инициализированного volume надо отдельно менять пароль роли PostgreSQL; изменение одной строки `.env` существующую роль не обновляет.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```text
HTTP-клиент → Go net/http API → PostgreSQL (именованный volume postgres_data)
```
Перенесены модели, маршруты, валидация JSON и курсоры из лабораторной 1. Методы `userStore`, `chatStore` и `messageStore` переписаны на PostgreSQL; прежние in-memory коллекции удалены. Публичная регистрация теперь требует пароль. На `POST /auth/sessions` допускается только Basic; остальные защищённые маршруты проходят через проверку Bearer. Идентификатор пользователя передаётся обработчикам через контекст запроса, `X-User-Id` игнорируется.
| Таблица | Ключи и ограничения | Назначение |
| --- | --- | --- |
| `users` | PK `id`, UNIQUE `username`, CHECK длины и формата | Пользователи и хеши паролей |
| `chats` | PK `id`, CHECK длины названия | Чаты |
| `chat_members` | PK `(chat_id,user_id)`, FK на обе таблицы, индекс `(user_id,chat_id)` | Членство и выборка доступных чатов |
| `messages` | PK `id`, FK на чат и отправителя, индекс `(chat_id,created_at,id)` | История и keyset-пагинация |
| `sessions` | PK `token_hash`, FK `user_id`, индекс `expires_at` | Действующие сессии |
Создание чата и всех записей членства — одна транзакция: при ошибке ни чат, ни часть участников не сохраняются. Регистрация, отправка сообщения, выдача и отзыв сессии — отдельные атомарные SQL-операции. Все параметры передаются через `pgx`, а не собираются в SQL-строку. Чтение истории выполняет `ORDER BY created_at,id LIMIT limit+1` с условием курсора. Часы назначения времени находятся в API; при конкурентных вставках между страницами snapshot всей истории не обещается.
Пароль обрабатывается `scrypt` со случайной 32-байтной солью (`N=32768,r=8,p=1`). В БД у пользователя только колонка `password_hash`: её 64 байта содержат соль и производный ключ подряд. Это нужно для повторной проверки пароля; значение не входит в API-ответ. Токен сессии содержит 256 случайных бит, клиент получает его один раз, в БД хранится только SHA-256 токена. Истечение проверяется по `expires_at` при каждом запросе, logout удаляет строку. Это не продлевает TTL при рестарте. PostgreSQL — источник истины для всех данных и сессий. `GET /health/ready` проверяет доступность БД.
`golang-migrate` хранит номер версии и признак незавершённой миграции в `schema_migrations`. Есть ровно одна парная миграция: `000001_initial.up.sql` и `.down.sql`; повторный `up` не создаёт данные заново. Миграция `down` проверялась только на отдельной временной БД.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
| Критерий | Команда/сценарий | Результат |
| --- | --- | --- |
| Контракт и код | `make check`, `go test ./...`, `go vet ./...` | PASS |
| PostgreSQL и миграция с нуля | `migrate up` на пустой временной БД | версия `1`, `dirty=false`, таблица `users` создана |
| Применение и откат | `migrate up → down → up` на временной БД | все три команды PASS; в конце версия `1`, `dirty=false` |
| Базовый API, Basic, Bearer, доступ, logout | `make test` | PASS, публичный сценарий lab2 |
| Сохранность данных и действующей сессии | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS с прежним токеном после рестарта API и БД |
| Срок жизни сессии | API с `SESSION_TTL_SECONDS=2`, вход, чтение, ожидание 3 с, чтение | после истечения получен `401`; затем восстановлен TTL 3600 |
| Повтор миграции и volume | повторный запуск API после рестарта | данные сохранены, версия миграции осталась `1` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
`make test` также проверяет неверный пароль, Basic на бизнес-маршруте и невозможность доступа по одному `X-User-Id`. Токены и пароли не сохранялись в отчёте.
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Воздействие | Ожидание | Наблюдение |
| --- | --- | --- |
| `scripts/restart.sh` | API и БД перезапускаются без удаления volume | время запуска БД изменилось с `18:55:34Z` на `18:56:24Z`, API — с `18:55:38Z` на `18:56:27Z`; число пользователей/чатов/сообщений/миграций было и осталось `6/2/3/1`; persistence-сценарий PASS |
| TTL 2 секунды | истёкший токен отклоняется | после 3 секунд `401` |
| `migrate down` на временной БД | откат начальной схемы | версия `1` удалена; повторный `up` снова создал схему |
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Одна копия API и одна БД не дают отказоустойчивости при потере хоста/volume. Рестарт с сохранённым volume проверен, резервное копирование и восстановление не реализованы. Redis/Valkey, нагрузочные измерения и EXPLAIN относятся к уровню 4 и здесь не заявлены. HTTP и пароль в локальном `.env` предназначены только для изолированного учебного стенда с синтетическими данными. `DATABASE_URL` доступен оператору Docker в окружении контейнера. Для удалённого размещения нужны TLS и управление секретами.