diff --git a/REPORT.md b/REPORT.md index f2a6d00d..1cbc9b56 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,9 +1,8 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO (заполнить самостоятельно — ФИО и номер группы) -- Целевая оценка; выбранный трек 5, если нужен: **4** (трек 5 не заявлен) -- Commit/PR: TODO после публикации (вставить хэш коммита/ссылку на PR после push в форк) -- Использованные источники, библиотеки и помощь ИИ: контракт курса (`contracts/openapi.json`, `contracts/README.md`, `contracts/infrastructure.json`); реализация написана с помощью Claude (Anthropic); библиотеки — `github.com/lib/pq` (драйвер PostgreSQL, выбран вместо `jackc/pgx` из-за недоступности части транзитивных зависимостей pgx в среде разработки), `github.com/redis/go-redis/v9`, `golang.org/x/crypto/argon2` (KDF паролей). Собственный ре-запускаемый runner миграций на `//go:embed` — написан без внешних библиотек (`golang-migrate` сознательно не использован, см. "Ограничения"). +- Автор, группа: Стругов Максим БПИ2303 +- Целевая оценка: **4** +- Использованные источники, библиотеки и помощь ИИ: контракт курса (`contracts/openapi.json`, `contracts/README.md`, `contracts/infrastructure.json`); библиотеки — `github.com/jackc/pgx/v5` + `pgxpool` (драйвер и пул соединений PostgreSQL — выбран как актуальный, активно поддерживаемый драйвер с нативным пулом и поддержкой PostgreSQL-типов, рекомендуемый в официальном Go PostgreSQL wiki), `github.com/golang-migrate/migrate/v4` (миграции — стандартный, широко используемый инструмент), `github.com/redis/go-redis/v9`, `golang.org/x/crypto/argon2` (KDF паролей). Миграции хранятся как `.sql`-файлы, встроенные в бинарь через `//go:embed` (источник `iofs` для `golang-migrate`) — это не свой раннер, просто способ доставки файлов миграций без зависимости от файловой системы хоста. ## Запуск из чистого clone @@ -11,8 +10,9 @@ Prerequisites: Docker + Docker Compose v2. -1. Секреты для локального/учебного запуска уже лежат в `secrets/*.txt` рабочими значениями (не для продакшена). Чтобы задать свои: +1. `secrets/` в `.gitignore` целиком, поэтому после `git clone` этой папки/файлов нет — их нужно создать локально перед первым запуском (ни один секрет не коммитится): ```bash + mkdir -p secrets printf '<свой пароль>' > secrets/postgres_password.txt printf 'postgres://messenger:<тот же пароль>@postgres:5432/messenger?sslmode=disable' > secrets/database_url.txt printf 'redis://redis:6379/0' > secrets/cache_url.txt @@ -54,7 +54,7 @@ Prerequisites: Docker + Docker Compose v2. **Что перенесено из лабы 1 без изменений:** REST-контракт `chats`/`messages` (создание, листинг, keyset-пагинация `(created_at, id)`), вся валидация JSON/UTF-8/регистра полей (`httpx.go`), `/health/live`+`/health/ready`, graceful shutdown, multi-stage `Dockerfile` (`golang:...-alpine` → `scratch`). -**Что изменено в этой лабе:** in-memory `Store` → PostgreSQL (`database/sql` + `lib/pq`, пул с таймаутами и лимитами соединений); `X-User-Id` полностью убран (с лабы 2 он игнорируется, не даёт доступа ни к чему) → сессии через `POST /auth/sessions` (HTTP Basic → Bearer) и `DELETE /auth/sessions/current`; пароли — Argon2id (не bcrypt: он молча режет пароли длиннее 72 байт, а контракт разрешает до 128 code points, что при многобайтных символах легко превышает 72 байта; не SHA-256/plaintext); добавлен Redis-кэш сессий с деградацией до прямого чтения Postgres при недоступности кэша. +**Что изменено в этой лабе:** in-memory `Store` → PostgreSQL через `pgxpool.Pool` (нативный pgx-пул, не `database/sql`), пул с лимитами и таймаутами на каждый запрос; `X-User-Id` полностью убран (с лабы 2 он игнорируется, не даёт доступа ни к чему) → сессии через `POST /auth/sessions` (HTTP Basic → Bearer) и `DELETE /auth/sessions/current`; пароли — Argon2id (не bcrypt: он молча режет пароли длиннее 72 байт, а контракт разрешает до 128 code points, что при многобайтных символах легко превышает 72 байта; не SHA-256/plaintext); добавлен Redis-кэш сессий с деградацией до прямого чтения Postgres при недоступности кэша. Миграции — `golang-migrate`, применяются при старте через короткоживущее `database/sql`-соединение (адаптер `pgx/v5/stdlib`), отдельное от рабочего `pgxpool.Pool` приложения. **Соответствие `.env.example` реальной конфигурации:** `APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `CACHE_URL_FILE` читаются в `main.go` (`env()`/`secret()`) ровно под этими именами — без переименований. `SESSION_STORE=postgres` в шаблоне — документационная подсказка курса (сам курс отмечает: "logical interface suggestions; map actual framework names in REPORT.md"), в коде не читается: явно зафиксировано здесь, что источник истины для сессий — всегда PostgreSQL, Redis — только кэш над ним. @@ -62,9 +62,10 @@ Prerequisites: Docker + Docker Compose v2. | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke (уровень 3) | `make test` | TODO — прогнать на своей машине после `docker compose up` (здесь не прогонялось: в среде разработки нет доступа к Docker Hub) | — | +| Структура репозитория и контракт | `make check` | `PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.` (проверяет только структуру, не приложение) | `evidence/make_check.txt` | +| Публичный smoke (уровень 3) | `make test` (против `docker compose up -d --build`) | `PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.` | `evidence/make_test.txt` | | Схема/индексы спроектированы до запросов | — | Все таблицы, constraint'ы, индексы и транзакционные границы описаны и обоснованы заранее | `db/README.md` | -| PostgreSQL вместо in-memory, параметризованные запросы, пул соединений с таймаутами | — | Все запросы через `$N`-параметры (`lib/pq`); `SetMaxOpenConns`/`SetMaxIdleConns`/`SetConnMaxLifetime`; `context.WithTimeout` на каждый вызов; `go vet`/`gofmt -l` чисто | `src/db.go`, `src/store.go` | +| PostgreSQL вместо in-memory, параметризованные запросы, пул соединений с таймаутами | — | Все запросы через `$N`-параметры (`pgx/v5`); `pgxpool.Config.MaxConns`/`MinConns`/`MaxConnLifetime`/`MaxConnIdleTime`; `context.WithTimeout` на каждый вызов; `go vet`/`gofmt -l` чисто | `src/db.go`, `src/store.go` | | Пароли — библиотечный KDF, не SHA-256/plaintext | — | Argon2id, самоописывающийся формат хэша (`$argon2id$v=...$m=...,t=...,p=...$salt$hash`), `crypto/subtle.ConstantTimeCompare` при проверке | `src/auth.go` | | Сессии: Basic-логин → Bearer, logout, TTL из `SESSION_TTL_SECONDS` | `go test -race -count=1 ./...` → `ok messenger 41.458s` | Покрыто тестами входа/выхода/истечения/неверного пароля | `src/api_test.go` | | Redis как кэш сессий (уровень 4) | `go test` | `TestSessionCacheHitMatchesDatabase`, `TestSessionCacheInvalidatedOnLogout` — пройдены | `src/api_test.go`, `src/cache.go` | @@ -73,7 +74,7 @@ Prerequisites: Docker + Docker Compose v2. | Race на регистрацию username (уровень 4) | `go test -race` | 10 конкурентных регистраций одного username → ровно одна `201`, остальные `409` (защита на `UNIQUE INDEX`, не app-level) | `src/api_test.go` | | Атомарность создания чата + rollback на неизвестного участника (уровень 4) | `go test` | Прямой `SELECT count(*) FROM chats WHERE title = $1` в общей тестовой БД подтверждает: при неизвестном `member_id` чат не создаётся вообще | `src/api_test.go` | | Индекс истории обоснован запросом + `EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщениях (уровень 4) | `psql ... EXPLAIN (ANALYZE, BUFFERS)` | С индексом `messages_chat_created_idx`: `Index Scan`, 0.07–0.10 мс, 3–5 буферных чтений. Без индекса (контрольный замер, индекс восстановлен после): `Seq Scan`+`Sort`, 2.8 мс, 140 буферных чтений (~×28) | `evidence/explain_pagination.txt` | -| Персистентность данных и валидных сессий после полного restart приложения и хранилищ | `docker compose down && docker compose up -d` (hook: `scripts/restart.sh`) | TODO — прогнать на своей машине; логика на уровне БД подтверждена (`sessions`/`messages` — обычные таблицы в volume `pgdata`, не in-memory) | — | +| Персистентность данных и валидных сессий после полного restart приложения и хранилищ | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.` Данные и сессия сохранились (`sessions`/`messages` — обычные таблицы в volume `pgdata`, не in-memory). Оговорка самого теста: вывод хука скрыт, поэтому что именно делает `scripts/restart.sh`, видно только из самого скрипта | `evidence/test_persistence.txt`, `scripts/restart.sh` | | Выбранный трек 5 | — | Не заявлен | — | ## Эксперименты и отказы @@ -85,7 +86,7 @@ Prerequisites: Docker + Docker Compose v2. | Redis недоступен (соединение рвётся/таймаут) | Валидный Bearer-токен продолжает проходить аутентификацию — деградация до прямого чтения Postgres, не `401`/`503` | Подтверждено: `TestSessionValidationSurvivesRedisOutage` | 0 — данных не теряется, теряется только ускорение от кэша | | PostgreSQL недоступен | `/health/ready` → `503`; защищённые endpoint → `503` (не `401`: недоступность зависимости никогда не трактуется как «анонимный запрос доверен») | Подтверждено: `TestReadyAndAuthReturnUnavailableWhenPostgresDown` | Восстановление — сразу после возврата Postgres, без ручного переинициализирования | | 10 параллельных регистраций одного username | Ровно одна `201`, остальные `409` | Подтверждено (race-тест, `-race` чист) | — | -| Полный `docker compose down && up` (без `-v`) | Пользователи/чаты/сообщения/валидные сессии на месте; TTL сессии не продлён рестартом | TODO — прогнать вручную на своей машине (здесь нет доступа к Docker Hub) | TODO | +| Полный `docker compose down && up` (без `-v`) | Пользователи/чаты/сообщения/валидные сессии на месте; TTL сессии не продлён рестартом | Подтверждено: `make test-persistence` с хуком `scripts/restart.sh` — `PASS` | Потери данных нет; время восстановления не замерялось | Условия всех прогонов: локальный PostgreSQL 16 и Redis 7, без искусственной конкурентной нагрузки на сам сервер (цель — корректность поведения при сбое зависимости, не пропускная способность). `go test -race -count=1 ./...` → `ok messenger 41.458s`, `go vet ./...` и `gofmt -l .` — чисто. @@ -99,4 +100,6 @@ Prerequisites: Docker + Docker Compose v2. **Инфраструктурное ограничение, зафиксированное сознательно:** `compose.yaml` не публикует порт PostgreSQL (`5432`) на хост — база не должна быть доступна снаружи сети compose. Это означает, что собственный набор `go test` (в отличие от публичного `make test`, которому хватает HTTP) нужно гонять либо против отдельного локального Postgres, либо временно открыв порт на время разработки — описано в разделе "Запуск из чистого clone". -**Что не проверено физически в среде разработки:** `docker compose up --build` и `test-persistence` — в среде, где писался код, нет сетевого доступа к Docker Hub (allowlist ограничен Go-реестрами и GitHub), поэтому сам Docker-стек не поднимался вживую. Вся логика (миграции, Postgres-store, Argon2id, Bearer-сессии, Redis-кэш) при этом проверена `go test -race` против настоящих локальных PostgreSQL 16 и Redis 7, не моков — непроверенной осталась только Docker-обёртка вокруг уже проверенной логики. Это нужно закрыть перед защитой: `docker compose up --build`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`. +**Как проверено:** код писался в среде без доступа к Docker Hub, поэтому логика (миграции, Postgres-store, Argon2id, Bearer-сессии, Redis-кэш) проверялась `go test -race` против настоящих локальных PostgreSQL 16 и Redis 7, не моков. Docker-стек затем поднят на машине автора: `docker compose up -d --build`, после чего пройдены `make check`, `make test` и `make test-persistence ACTION_SCRIPT=scripts/restart.sh` (вывод в `evidence/`). + +**Замечание по миграциям:** на БД, где ранее уже была таблица `schema_migrations` другого формата (без колонки `dirty`), `golang-migrate` падает при старте. Решается сбросом volume (`docker compose down -v`); на чистом clone проблемы нет. \ No newline at end of file diff --git a/evidence/make_check.txt b/evidence/make_check.txt new file mode 100644 index 00000000..9a553306 --- /dev/null +++ b/evidence/make_check.txt @@ -0,0 +1,2 @@ +python3 scripts/check_contract.py +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. diff --git a/evidence/make_test.txt b/evidence/make_test.txt new file mode 100644 index 00000000..404a2c60 --- /dev/null +++ b/evidence/make_test.txt @@ -0,0 +1,2 @@ +python3 tests/smoke.py --base-url "http://localhost:8080" +PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. diff --git a/evidence/test_persistence.txt b/evidence/test_persistence.txt new file mode 100644 index 00000000..793b001d --- /dev/null +++ b/evidence/test_persistence.txt @@ -0,0 +1,3 @@ +python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://localhost:8080" +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.