From 02a55ad29e3c2e5935c95c94409e2faecb432ba2 Mon Sep 17 00:00:00 2001 From: myDan Date: Fri, 30 Oct 2026 01:40:38 +0300 Subject: [PATCH] docs: fill report --- REPORT.md | 108 ++++++++++++++++++++++++++++++++------- evidence/explain.txt | 53 +++++++++++++++++++ evidence/outage.txt | 18 +++++++ evidence/persistence.txt | 26 ++++++++++ evidence/smoke.txt | 5 ++ evidence/test-go.txt | 18 +++++++ 6 files changed, 209 insertions(+), 19 deletions(-) create mode 100644 evidence/explain.txt create mode 100644 evidence/outage.txt create mode 100644 evidence/persistence.txt create mode 100644 evidence/smoke.txt create mode 100644 evidence/test-go.txt diff --git a/REPORT.md b/REPORT.md index e42f2b0..e1d2f44 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,107 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Спесивцев Даниил БПИ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 +## Запуск из clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Тестовый стенд: 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 + +$COMPOSE down # остановка, данные сохраняются +$COMPOSE down -v # удаление учебных данных +``` ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +``` +клиент ──HTTP:8080──▶ api (Go) ──pgx pool──▶ postgres [volume pgdata] + └─go-redis──▶ redis [volume redisdata, AOF] +``` + +- **Источник истины:** PostgreSQL — пользователи, чаты, участники, сообщения. Redis — единственное хранилище сессий (COURSE.md допускает сессии в Redis/Valkey), поэтому включён AOF (`appendfsync everysec`). +- **Сессии:** + - токен — 32 байта из `crypto/rand`, base64url; + - в Redis хранится `session: → 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` только документирует выбор. ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +| Критерий | Команда | Результат | Файл | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Публичный 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` | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +## 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 на каждую вставку. ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. - -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | +| Воздействие | Ожидание | Наблюдение | Восстановление / потери | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| `restart.sh` (API, PG, Redis) | данные и токен сохраняются | PASS | потерь нет | +| `stop redis` | 503, без токена 401 | совпадает | после старта токен работает (AOF) | +| `stop postgres` | 503, ready 503 | совпадает | pool переподключается сам | -## Ограничения и следующие шаги +## Ограничения -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- Один host, без HA и backup. При аварийном падении Redis возможна потеря сессий за последнюю секунду (`everysec`). +- Redis без пароля. Порты PG и Redis открыты только на `127.0.0.1`, они нужны для `make test-go`. +- HTTP допустим только на локальном стенде, TLS будет в lab7. +- Не реализовано, потому что не требуется контрактом: отказ на тело у `POST /auth/sessions`, выравнивание времени ответа для неизвестного username, кэш данных. diff --git a/evidence/explain.txt b/evidence/explain.txt new file mode 100644 index 0000000..db1529e --- /dev/null +++ b/evidence/explain.txt @@ -0,0 +1,53 @@ +# scripts/explain.sh; date: 2026-10-29T22:07:31Z + messages_total | messages_in_big_chat +----------------+---------------------- + 60328 | 20000 +(1 row) + +=== 1. First page (limit=50 -> LIMIT 51), index messages_chat_created_id_idx + QUERY PLAN +--------------------------------------------------------------------------------------------------------------------------------------------------------- + Limit (cost=0.41..8.31 rows=51 width=78) (actual time=0.009..0.014 rows=51.00 loops=1) + Buffers: shared hit=4 + -> Index Scan using messages_chat_created_id_idx on messages (cost=0.41..3088.25 rows=19942 width=78) (actual time=0.008..0.012 rows=51.00 loops=1) + Index Cond: (chat_id = '00000000-0000-4000-8000-00000000e001'::uuid) + Index Searches: 1 + Buffers: shared hit=4 + Planning: + Buffers: shared hit=10 + Planning Time: 0.077 ms + Execution Time: 0.024 ms +(10 rows) + +=== 2. Page in the middle by keyset cursor (after 10 000 messages) + QUERY PLAN +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ + Limit (cost=0.41..27.77 rows=51 width=78) (actual time=0.008..0.014 rows=51.00 loops=1) + Buffers: shared hit=5 + -> Index Scan using messages_chat_created_id_idx on messages (cost=0.41..1834.26 rows=3419 width=78) (actual time=0.008..0.012 rows=51.00 loops=1) + Index Cond: ((chat_id = '00000000-0000-4000-8000-00000000e001'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 02:46:40+00'::timestamp with time zone, 'ea1e0a08-377a-4911-aa17-221192625ad3'::uuid))) + Index Searches: 1 + Buffers: shared hit=5 + Planning Time: 0.035 ms + Execution Time: 0.042 ms +(8 rows) + +=== 3. Same middle page WITHOUT the index (dropped inside a rolled-back transaction) + QUERY PLAN +-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + Limit (cost=1988.81..1988.93 rows=51 width=78) (actual time=3.462..3.467 rows=51.00 loops=1) + Buffers: shared hit=819 + -> Sort (cost=1988.81..1997.35 rows=3419 width=78) (actual time=3.462..3.464 rows=51.00 loops=1) + Sort Key: created_at, id + Sort Method: top-N heapsort Memory: 31kB + Buffers: shared hit=819 + -> Seq Scan on messages (cost=0.00..1874.74 rows=3419 width=78) (actual time=0.498..2.888 rows=10000.00 loops=1) + Filter: ((chat_id = '00000000-0000-4000-8000-00000000e001'::uuid) AND (ROW(created_at, id) > ROW('2026-01-01 02:46:40+00'::timestamp with time zone, 'ea1e0a08-377a-4911-aa17-221192625ad3'::uuid))) + Rows Removed by Filter: 50328 + Buffers: shared hit=819 + Planning: + Buffers: shared hit=4 + Planning Time: 0.052 ms + Execution Time: 3.492 ms +(14 rows) + diff --git a/evidence/outage.txt b/evidence/outage.txt new file mode 100644 index 0000000..a75c4d2 --- /dev/null +++ b/evidence/outage.txt @@ -0,0 +1,18 @@ +# scripts/outage-demo.sh (COMPOSE="podman compose") +# Dependency outage demo on the live stand; date: 2026-10-29T22:09:23Z. Token is kept in a shell variable, never printed. +baseline: GET /users/me (Bearer) -> 200 + +## podman compose stop redis +GET /health/ready -> 503 +GET /users/me (valid Bearer) -> 503 +GET /users/me (no auth) -> 401 +POST /auth/sessions (Basic) -> 503 +body: {"error":{"code":"unavailable","message":"service temporarily unavailable","request_id":"0fc08a63-dc18-4508-a95e-7274844d13c8"}} +## podman compose start redis -> ready; same token: GET /users/me -> 200 + +## podman compose stop postgres +GET /health/ready -> 503 +GET /users/me (valid Bearer) -> 503 +GET /chats (valid Bearer) -> 503 +body: {"error":{"code":"unavailable","message":"service temporarily unavailable","request_id":"43f47140-394e-461e-b5bc-1863a33fc6da"}} +## podman compose start postgres -> ready; same token: GET /users/me -> 200 diff --git a/evidence/persistence.txt b/evidence/persistence.txt new file mode 100644 index 0000000..4ef7430 --- /dev/null +++ b/evidence/persistence.txt @@ -0,0 +1,26 @@ +# make test-persistence ACTION_SCRIPT=scripts/restart.sh (COMPOSE="podman compose") +# date: 2026-10-29T22:09:51Z; podman 6.1.0, podman-compose 1.6.0 + +## containers before +messenger_api_1 id=e8951624fe7a started=2026-10-30 01:09:02.81809688 +0300 MSK +messenger_postgres_1 id=6aab8ebe96dd started=2026-10-30 01:09:30.742003352 +0300 MSK +messenger_redis_1 id=7af579a966dd started=2026-10-30 01:09:28.731706375 +0300 MSK +schema_migrations (version|dirty): 1|f +rows users|chats|messages: 111|43|60437 + +## test +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. + +## containers after (same IDs, new start time = real restart, volumes kept) +messenger_api_1 id=e8951624fe7a started=2026-10-30 01:09:54.107586909 +0300 MSK +messenger_postgres_1 id=6aab8ebe96dd started=2026-10-30 01:09:53.97943161 +0300 MSK +messenger_redis_1 id=7af579a966dd started=2026-10-30 01:09:54.047665509 +0300 MSK +schema_migrations (version|dirty): 1|f +rows users|chats|messages: 114|44|60438 (test adds 3 users, 1 chat, 1 message) +api log after restart: "msg":"migrations applied" + +## volumes +messenger_pgdata +messenger_redisdata diff --git a/evidence/smoke.txt b/evidence/smoke.txt new file mode 100644 index 0000000..8f332ce --- /dev/null +++ b/evidence/smoke.txt @@ -0,0 +1,5 @@ +# make check && make test; date: 2026-10-29T22:09:30Z +python3 scripts/check_contract.py +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. +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-go.txt b/evidence/test-go.txt new file mode 100644 index 0000000..9804c7d --- /dev/null +++ b/evidence/test-go.txt @@ -0,0 +1,18 @@ +# make test-go; date: 2026-10-29T22:09:31Z; go version go1.27.1 linux/amd64 +--- PASS: TestSessionExpiry (3.10s) +--- PASS: TestLogout (0.07s) +--- PASS: TestWrongPassword (0.09s) +--- PASS: TestRedisUnavailable (2.80s) +--- PASS: TestDatabaseUnavailable (0.16s) +--- PASS: TestInvalidJSON (0.01s) +--- PASS: TestForeignChat (0.16s) +--- PASS: TestEmptyMessage (0.07s) +--- PASS: TestDuplicateUsername (0.09s) +--- PASS: TestPaginationMultiplePages (0.08s) +--- PASS: TestConcurrentMessages (0.50s) +PASS +ok messenger/internal/handler 7.128s +--- PASS: TestRegisterUsernameRace (0.08s) +--- PASS: TestCreateChatRollback (0.03s) +PASS +ok messenger/internal/repository/postgres 0.109s