Files
mtusi2026lab2-implementation/REPORT.md
T

119 lines
9.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 2
- Автор, группа: Спесивцев Даниил БПИ2301
- Целевая оценка 4; выбранный трек 5, если нужен: не заявлен
- Commit/PR: commit "df7b8fb7010de0dd96c213ba028be9d6e838976c"
- Использованные источники, библиотеки и помощь ИИ: Go 1.27.1 (стандартная библиотека). Для консультации, реализации некоторых фич, написания отчета использовались LLM. Библиотеки:
- [go-chi/chi v5.3.2](https://github.com/go-chi/chi) — HTTP-роутинг;
- [jackc/pgx v5.11.0](https://github.com/jackc/pgx) — драйвер PostgreSQL и пул соединений `pgxpool`;
- [golang-migrate/migrate v4.20.1](https://github.com/golang-migrate/migrate) — версионируемые миграции;
- [redis/go-redis v9.23.0](https://github.com/redis/go-redis) — клиент Redis для сессий;
- [golang.org/x/crypto v0.58.0](https://pkg.go.dev/golang.org/x/crypto/argon2) — Argon2id для хеширования паролей.
## Запуск из clone
Тестовый стенд: i5-11400H, 16 GB RAM, без лимитов на контейнеры
Образы: `postgres:18.6-alpine3.24`, `redis:8.10.3-alpine3.23`; API собирается из `Dockerfile` (`golang:1.27.1-alpine3.24` → `alpine:3.24.1`). `COMPOSE` по умолчанию `docker compose`, для podman: `export COMPOSE="podman compose"`.
```sh
scripts/init-secrets.sh && cp .env.example .env # локальные secrets, вне Git
$COMPOSE --env-file .env up -d --build # миграции применяет API при старте
until curl -sf http://localhost:8080/health/ready; do sleep 1; done
make check && make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-go # Go-тесты уровня 4
scripts/explain.sh # → evidence/explain.txt
scripts/outage-demo.sh # отказ Redis/PostgreSQL
# проверка expiry на стенде (сценарий защиты): короткий TTL, затем вернуть 3600
SESSION_TTL_SECONDS=2 $COMPOSE --env-file .env up -d --force-recreate --no-deps api
$COMPOSE down # остановка, данные сохраняются
$COMPOSE down -v # удаление учебных данных
```
## Архитектура и решения
```
клиент ──HTTP:8080──▶ api (Go) ──pgx pool──▶ postgres [volume pgdata]
└─go-redis──▶ redis [volume redisdata, AOF]
```
| Роль | Service | Образ | Health | Volume | Порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| api | `api` | сборка из `Dockerfile` | `/health/ready` (PG + Redis) | — | `8080` | secrets `database_url`, `cache_url` |
| postgres | `postgres` | `postgres:18.6-alpine3.24` | `pg_isready` | `pgdata` | `127.0.0.1:55432` | secret `postgres_password` |
| redis | `redis` | `redis:8.10.3-alpine3.23` | `redis-cli ping` | `redisdata` | `127.0.0.1:56379` | без пароля |
Bootstrap: `scripts/init-secrets.sh` создаёт secrets, БД и пользователя создаёт образ postgres, схему — миграции при старте API. Всё безопасно повторять.
- **Источник истины:** PostgreSQL — пользователи, чаты, участники, сообщения. Redis — единственное хранилище сессий (COURSE.md допускает сессии в Redis/Valkey), поэтому включён AOF (`appendfsync everysec`).
- **Сессии:**
- токен — 32 байта из `crypto/rand`, base64url;
- в Redis хранится `session:<sha256(token)> → user_id` командой `SET ... EXAT`. Срок абсолютный, рестарт его не продлевает;
- logout = `DEL`;
- после `FLUSHALL` или потери volume Redis все сессии теряются, пользователи входят заново, данные в PG не затрагиваются.
- **Пароли:** Argon2id (m=19 MiB, t=2, p=1), формат PHC, проверка через `subtle.ConstantTimeCompare`.
- **Транзакции:** `POST /chats` — `chats` + `chat_members` в одной транзакции, неизвестный участник (FK 23503) → rollback → 400. Уникальность username обеспечивает `UNIQUE` (23505 → 409).
- **Миграции:** golang-migrate, SQL встроен в бинарник через `embed`, версия в `schema_migrations`, повторный запуск — no-op.
- **Схема:**
- `users` (`UNIQUE username`);
- `chats`;
- `chat_members` (PK `(chat_id,user_id)`, индекс `(user_id)`);
- `messages` (индекс `(chat_id, created_at, id)`).
- **БД и Redis:** запросы только параметризованные. Pool pgx `MaxConns=10`, `ConnectTimeout=3s`, `statement_timeout=5s`. Redis `PoolSize=10`, таймауты 1–2 с.
- **Отказы:** ошибки соединения и SQLSTATE классов 08/53/57 → `503 unavailable`. Критичны PG и Redis: `/health/ready` проверяет оба. Без Redis запрос с токеном получает 503, а не анонимный доступ.
- **Переход с lab1:**
- `password` при регистрации;
- Basic только на `POST /auth/sessions`, на остальных Bearer;
- `X-User-Id` игнорируется;
- in-memory хранилище заменено на PG и Redis.
- **`.env.example`:**
- `SESSION_TTL_SECONDS` → TTL сессии;
- `DATABASE_URL_FILE`, `CACHE_URL_FILE` → файлы-secrets;
- `SESSION_STORE=redis` только документирует выбор.
## Доказательства критериев
| Критерий | Команда | Результат | Файл |
| --- | --- | --- | --- |
| Публичный smoke | `make check && make test` | PASS | `evidence/smoke.txt` |
| 3: данные и сессии переживают рестарт | `make test-persistence` | PASS; все 3 контейнера перезапущены, volumes те же | `evidence/persistence.txt` |
| 3: миграции повторно без дублей | рестарт стенда | `schema_migrations=1, dirty=f` до и после | `evidence/persistence.txt` |
| 3/4: атомарность и rollback чата | `TestCreateChatRollback` | 0 строк в `chats`/`chat_members` | `evidence/test-go.txt` |
| 3: Basic/Bearer, `X-User-Id` не даёт доступа | smoke | PASS | `evidence/smoke.txt` |
| 4: Redis — сессии с TTL и persistence | `make test-persistence` | прежний токен работает после рестарта Redis | `evidence/persistence.txt` |
| 4: гонка регистрации username | `TestRegisterUsernameRace` | из 20 параллельных запросов 1 успех, 19 conflict | `evidence/test-go.txt` |
| 4: индекс + EXPLAIN на ≥10 000 | `scripts/explain.sh` | Index Scan, 4–5 буферов | `evidence/explain.txt` |
| 4: expiry, logout, неверный пароль | `TestSessionExpiry`, `TestLogout`, `TestWrongPassword` | 401 с нужным `WWW-Authenticate` | `evidence/test-go.txt` |
| 4: недоступность Redis/БД | `TestRedisUnavailable`, `TestDatabaseUnavailable`, `scripts/outage-demo.sh` | 503; без токена 401; после старта тот же токен 200 | `evidence/test-go.txt`, `evidence/outage.txt` |
## EXPLAIN истории
Запрос API: `WHERE chat_id=$1 AND (created_at,id) > ($2,$3) ORDER BY created_at,id LIMIT 51`. Данные: 60 328 сообщений, 20 000 из них в одном чате.
| План | Узел | Buffers | Время |
| --- | --- | --- | --- |
| Первая страница | Index Scan `messages_chat_created_id_idx` | 4 | 0.024 ms |
| Страница после 10 000 сообщений | Index Scan, cursor в `Index Cond` | 5 | 0.042 ms |
| Та же без индекса | Seq Scan (отброшено 50 328 строк) + Sort | 819 | 3.492 ms |
Индекс совпадает с фильтром и порядком сортировки, поэтому страница читает ровно 51 запись при любой глубине cursor. Цена индекса — дополнительное обновление B-tree на каждую вставку.
## Эксперименты и отказы
| Воздействие | Ожидание | Наблюдение | Восстановление / потери |
| --- | --- | --- | --- |
| `restart.sh` (API, PG, Redis) | данные и токен сохраняются | PASS | потерь нет |
| `stop redis` | 503, без токена 401 | совпадает | после старта токен работает (AOF) |
| `stop postgres` | 503, ready 503 | совпадает | pool переподключается сам |
## Ограничения
- Один host, без HA и backup. При аварийном падении Redis возможна потеря сессий за последнюю секунду (`everysec`).
- Redis без пароля. Порты PG и Redis открыты только на `127.0.0.1`, они нужны для `make test-go`.
- HTTP допустим только на локальном стенде, TLS будет в lab7.
- Не реализовано, потому что не требуется контрактом: отказ на тело у `POST /auth/sessions`, выравнивание времени ответа для неизвестного username, кэш данных.