diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml new file mode 100644 index 0000000..e03f06a --- /dev/null +++ b/.gitea/workflows/ci.yml @@ -0,0 +1,78 @@ +name: CI + +on: + pull_request: + branches: [main] + push: + branches: [main, solution/bvt2303-plastinin] + workflow_dispatch: + +concurrency: + group: ci-${{ github.repository }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + verify: + runs-on: ubuntu-latest + timeout-minutes: 20 + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-go@v5 + with: + go-version-file: go.mod + cache: true + + - uses: actions/setup-python@v5 + with: + python-version: "3.13" + + - name: Check contract + run: make check + + - name: Validate OpenAPI + run: | + python -m venv .venv + .venv/bin/python -m pip install -r requirements-dev.txt + make validate PYTHON=.venv/bin/python + + - name: Check formatting + run: test -z "$(gofmt -l cmd internal migrations)" + + - name: Lint + uses: golangci/golangci-lint-action@v6.5.2 + with: + version: v2.13.2 + args: --timeout=5m + + - name: Unit tests and build + run: | + go test -race ./... + go build ./cmd/messenger + + - name: Prepare local stack + run: | + cp lab2.env.example .env + ./scripts/init-local-secrets.sh + docker compose config --quiet + docker compose up -d --build --wait --wait-timeout 120 + + - name: Public smoke + run: make test + + - name: PostgreSQL and Valkey integration tests + run: docker compose --profile tests run --rm --build tests + + - name: Dependency outage recovery + run: go run ./cmd/dependencycheck + + - name: Persistence test + run: make test-persistence ACTION_SCRIPT=scripts/restart.sh + + - name: Container logs + if: failure() + run: docker compose logs --no-color --tail=200 + + - name: Stop local stack + if: always() + run: docker compose --profile tests down -v --remove-orphans diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml new file mode 100644 index 0000000..5f83c6d --- /dev/null +++ b/.gitea/workflows/deploy.yml @@ -0,0 +1,123 @@ +name: Deploy production + +on: + workflow_dispatch: + inputs: + confirmation: + description: Type DEPLOY to release main + required: true + +concurrency: + group: production + cancel-in-progress: false + +jobs: + deploy: + if: github.ref == 'refs/heads/main' && inputs.confirmation == 'DEPLOY' + runs-on: ubuntu-latest + timeout-minutes: 20 + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-go@v5 + with: + go-version-file: go.mod + cache: true + + - uses: actions/setup-python@v5 + with: + python-version: "3.13" + + - name: Verify release + run: | + make check + python -m venv .venv + .venv/bin/python -m pip install -r requirements-dev.txt + make validate PYTHON=.venv/bin/python + test -z "$(gofmt -l cmd internal migrations)" + go test -race ./... + go build ./cmd/messenger + + - name: Lint + uses: golangci/golangci-lint-action@v6.5.2 + with: + version: v2.13.2 + args: --timeout=5m + + - name: Verify release stack + run: | + cp lab2.env.example .env + ./scripts/init-local-secrets.sh + docker compose up -d --build --wait --wait-timeout 120 + make test + docker compose --profile tests run --rm --build tests + go run ./cmd/dependencycheck + make test-persistence ACTION_SCRIPT=scripts/restart.sh + + - name: Stop release stack + if: always() + run: docker compose --profile tests down -v --remove-orphans + + - name: Configure SSH + run: | + install -d -m 700 ~/.ssh + printf '%s\n' '${{ secrets.DEPLOY_SSH_KEY }}' > ~/.ssh/id_ed25519 + chmod 600 ~/.ssh/id_ed25519 + printf '%s\n' '${{ secrets.DEPLOY_KNOWN_HOSTS }}' > ~/.ssh/known_hosts + + - name: Pack release + run: tar --exclude=.git --exclude=.env --exclude=secrets --exclude=.venv -czf /tmp/mtusi-lab2-${{ github.sha }}.tar.gz . + + - name: Upload release + run: scp /tmp/mtusi-lab2-${{ github.sha }}.tar.gz '${{ secrets.DEPLOY_USER }}@${{ secrets.DEPLOY_HOST }}:/tmp/' + + - name: Deploy exact commit + env: + DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }} + DEPLOY_USER: ${{ secrets.DEPLOY_USER }} + RELEASE_SHA: ${{ github.sha }} + RELEASE_ATTEMPT: ${{ github.run_attempt }} + run: | + ssh "$DEPLOY_USER@$DEPLOY_HOST" sh -s -- "$RELEASE_SHA" "$RELEASE_ATTEMPT" <<'REMOTE' + set -eu + + release_sha=$1 + release_attempt=$2 + deploy_root=/opt/mtusi-lab2 + release_dir=$deploy_root/releases/$release_sha-$release_attempt + archive=/tmp/mtusi-lab2-$release_sha.tar.gz + + mkdir -p "$deploy_root/releases" "$deploy_root/shared/backups" + exec 9>"$deploy_root/deploy.lock" + flock -x 9 + + previous= + previous_image= + if [ -L "$deploy_root/current" ]; then + previous=$(basename "$(readlink "$deploy_root/current")") + previous_image=$(cat "$deploy_root/current/.release-sha") + cd "$deploy_root/current" + docker compose -p mtusi-lab2 exec -T postgres sh -eu -c ' + export PGPASSWORD="$(cat /run/secrets/postgres_password)" + pg_dump --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" --format custom + ' > "$deploy_root/shared/backups/pre-$release_sha.dump" + fi + + mkdir -p "$release_dir" + tar -xzf "$archive" -C "$release_dir" + printf '%s\n' "$release_sha" > "$release_dir/.release-sha" + ln -s "$deploy_root/shared/.env" "$release_dir/.env" + ln -s "$deploy_root/shared/secrets" "$release_dir/secrets" + + cd "$release_dir" + if ! API_IMAGE="mtusi-messenger:$release_sha" docker compose -p mtusi-lab2 up -d --build --wait --wait-timeout 120; then + if [ -n "$previous" ]; then + cd "$deploy_root/releases/$previous" + API_IMAGE="mtusi-messenger:$previous_image" docker compose -p mtusi-lab2 up -d --wait --wait-timeout 120 + fi + exit 1 + fi + + ln -sfn "$release_dir" "$deploy_root/current" + rm -f "$archive" + REMOTE diff --git a/REPORT.md b/REPORT.md index e42f2b0..f7874b4 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,157 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Пластинин Денис, БВТ2303 +- Целевая оценка: 5; трек 2 «План запроса и восстановление» +- Ветка: `solution/bvt2303-plastinin`; ссылка на PR указывается при публикации +- Основные библиотеки: pgx v5, valkey-go, x/crypto/argon2, Prometheus client_golang +- Источники: документация PostgreSQL по [транзакциям](https://www.postgresql.org/docs/current/tutorial-transactions.html) и [EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html), документация [Valkey persistence](https://valkey.io/topics/persistence/), [RFC 7617](https://www.rfc-editor.org/info/rfc7617/) +- Помощь ИИ: применялась для анализа задания и проверки реализации; команды и наблюдаемые результаты проверены локально ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Требуются Docker с Compose, `make`, Python 3.9 или новее для преподавательских тестов. Go на хосте для обычного запуска не требуется. Версии основных образов закреплены: Go 1.26.5, Alpine 3.24.2, PostgreSQL 17.6, Valkey 8.1.4, Swagger UI 5.31.2. + +```sh +cp lab2.env.example .env +./scripts/init-local-secrets.sh +docker compose config --quiet +docker compose up -d --build --wait --wait-timeout 120 +make test +make test-persistence ACTION_SCRIPT=scripts/restart.sh +``` + +API доступен на `http://localhost:8080`, Swagger UI — на `http://localhost:8081`. Миграции встроены в бинарник и выполняются при запуске до начала приёма запросов. Повторное применение уже записанной версии сверяет checksum и не создаёт объекты повторно. + +Собственные integration-тесты запускаются отдельным профилем: + +```sh +docker compose --profile tests run --rm --build tests +``` + +Мониторинг не входит в обязательный путь запуска и включается явно: + +```sh +docker compose --profile monitoring up -d +``` + +После запуска Prometheus доступен на `http://localhost:9090`, Grafana — на `http://localhost:3000`. Пользователь Grafana — `admin`, пароль хранится только в `secrets/grafana_admin_password`. Дашборд `Highload / Messenger overview` создаётся автоматически. + +Безопасная остановка сохраняет именованные volumes: + +```sh +docker compose --profile monitoring down +``` + +Намеренное удаление всех локальных учебных данных выполняется отдельно: + +```sh +docker compose --profile monitoring down -v +``` ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +```mermaid +flowchart LR + C[HTTP client] --> A[Go API] + A --> P[(PostgreSQL)] + A --> V[(Valkey AOF)] + S[Swagger UI] --> A + M[Prometheus] --> A + M --> PE[PostgreSQL exporter] + M --> VE[Valkey exporter] + G[Grafana] --> M +``` + +PostgreSQL является источником истины для пользователей, чатов, участников и сообщений. Внешние ключи не позволяют сообщению ссылаться на отсутствующий чат, пользователя вне чата или удалённое членство. `username` защищён уникальным ограничением базы, поэтому конкурентные запросы не могут создать дубликаты. + +Valkey хранит только сессии. Клиент получает 32 случайных байта в виде opaque Base64URL-токена, а в ключе Valkey используется SHA-256 токена. Значение содержит ID пользователя и срок действия. На ключ устанавливается TTL; logout удаляет ключ. Включены AOF и `appendfsync everysec`, поэтому штатный перезапуск сохраняет сессии. При аварийной остановке граница потери последних изменений AOF составляет примерно одну секунду. + +Пароли хешируются Argon2id с отдельной случайной солью. Basic принимается только на `POST /api/v1/auth/sessions`. Бизнес-ручки принимают Bearer; `X-User-Id` не участвует в аутентификации и не меняет пользователя. Неверный, истёкший или отозванный токен приводит к `401`. Ошибка PostgreSQL или Valkey приводит к `503`, а не к анонимному обходу проверки. + +Создание чата состоит из проверки участников, вставки чата и вставки всех членств в одной транзакции. Любая ошибка вызывает rollback. Все SQL-запросы параметризованы. Пул ограничен переменными `DB_MIN_CONNS` и `DB_MAX_CONNS`, установка соединения и проверки зависимостей имеют таймауты. + +История сообщений использует keyset pagination по `(created_at, id)`. Cursor содержит позицию последней строки, тип ресурса и область чата; сервер проверяет его целостность и принадлежность текущему запросу. Запрос использует индекс `(chat_id, created_at, id)` и не пересчитывает полный offset для каждой страницы. + +Преподавательский `.env.example` сохранён без изменений. Рабочее соответствие параметров находится в `lab2.env.example`: `SESSION_STORE=valkey`, пути Docker secrets задаются Compose, `SESSION_TTL_SECONDS` задаёт срок сессии, `DB_MIN_CONNS`/`DB_MAX_CONNS` ограничивают пул, `DEPENDENCY_TIMEOUT_SECONDS` ограничивает подключение и каждую операцию с зависимостями. ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +| Критерий README | Команда или сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Публичный smoke | `make test` | `PASS: lab2 public API scenario` | `evidence/lab2-verification.txt` | +| Сохранение данных и сессии | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | API, PostgreSQL и Valkey перезапущены; старый токен и подтверждённое сообщение сохранились | `evidence/lab2-verification.txt` | +| Миграции и повторный запуск | повторные сборки и перезапуски API на том же volume | checksum миграции совпал, схема не продублировалась, readiness вернулся в `200` | `evidence/lab2-verification.txt` | +| Гонка username | `docker compose --profile tests run --rm --build tests` | из 8 конкурентных вставок успешна одна, остальные получили conflict | `internal/postgres/store_integration_test.go` | +| Rollback чата | тот же integration suite | неизвестный участник дал `ErrInvalidMembers`, число чатов не изменилось | `internal/postgres/store_integration_test.go` | +| TTL и logout | integration suite и `make test` | сессия исчезла после TTL; после logout запрос и повторный logout дали `401` | `internal/session/session_integration_test.go` | +| Неверный пароль и отказ зависимостей | `go test -race ./internal/messenger` | неверный пароль — `401`; ошибки PostgreSQL и Valkey — `503` | `internal/messenger/server_test.go` | +| Реальный отказ зависимостей | `go run ./cmd/dependencycheck` | поочерёдный stop PostgreSQL/Valkey дал `503`; после up восстановились readiness и старый токен | `evidence/lab2-verification.txt` | +| Индекс истории | Go-эксперимент, 100 000 сообщений, `EXPLAIN (ANALYZE, BUFFERS)` | составной индекс: 0,069 мс и 0 отфильтрованных строк; глобальный индекс: 0,597 мс и 1900 отфильтрованных строк | `evidence/lab2-track2.json` | +| Стоимость записи | 5 повторов `CopyFrom` по 10 000 строк, медиана | без вторичного индекса 309 172 строк/с; составной 286 011 строк/с; снижение около 7,5% | `evidence/lab2-track2.json` | +| Backup и restore | `./scripts/backup-restore.sh` | восстановление в `messenger_restore` за 1 с; counts, memberships и digest полей сообщений совпали | `evidence/lab2-backup-restore.txt` | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +## Эксперимент с планом запроса -## Эксперименты и отказы +Гипотеза: индекс `(chat_id, created_at, id)` ускорит keyset pagination в небольшом чате относительно индекса `(created_at, id)`, потому что PostgreSQL сможет сразу ограничить диапазон конкретным `chat_id`. Цена улучшения — дополнительное обслуживание более широкого индекса при записи и место на диске. -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Эксперимент выполнен Go-программой `cmd/lab2experiment`. Среда обезличена: контейнер `linux/arm64`, Go 1.26.5, лимит 2 CPU. Создано 100 000 синтетических сообщений в 20 чатах с распределением 60 000, 20 000, 10 000 и от 588 до 592 сообщений в остальных чатах. Времена сообщений разных чатов чередуются, поэтому глобальный индекс не получает преимущества от последовательной загрузки одного чата. -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | +Проверялся запрос страницы из 100 сообщений после cursor в середине одного из небольших чатов. Для каждого варианта индекс пересоздавался, выполнялся `ANALYZE`, затем сохранялся полный JSON-план `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)`. + +| Вариант | Execution time | Строк отброшено фильтром | Shared blocks hit/read | +| --- | ---: | ---: | ---: | +| `(chat_id, created_at, id)` | 0,069 мс | 0 | 6 / 4 | +| `(created_at, id)` | 0,597 мс | 1900 | 1994 / 19 | + +В данной точке составной индекс быстрее примерно в 8,7 раза. Причина видна в плане: он сразу выбирает диапазон одного чата, а глобальный индекс идёт по общей временной шкале и проверяет `chat_id` для чужих сообщений. + +Стоимость записи измерялась отдельно. Для каждого варианта таблица создавалась заново, пять раз загружалось по 10 000 одинаково сформированных строк, в отчёт взята медиана. + +| Вариант | Медиана | Производительность | Размер вторичного индекса | +| --- | ---: | ---: | ---: | +| без вторичного индекса | 0,0323 с | 309 172 строк/с | 0 | +| `(chat_id, created_at, id)` | 0,0350 с | 286 011 строк/с | 991 232 байта | +| `(created_at, id)` | 0,0350 с | 285 326 строк/с | 425 984 байта | + +Составной индекс выбран для приложения: потеря около 7,5% в синтетической пакетной записи компенсируется существенным ускорением основной операции чтения истории. Эти числа относятся к прогретой локальной среде, короткому запуску и 100 000 строк; они показывают направление и не являются производственным SLA. + +## Backup, восстановление и отказы + +`scripts/backup-restore.sh` создаёт временный backup PostgreSQL в custom format, создаёт новую базу `messenger_restore`, выполняет `pg_restore`, затем сравнивает counts пользователей, чатов, членств и сообщений. Для десяти выбранных сообщений сравнивается digest полей `id`, `chat_id`, `sender_id`, `text` и `created_at`. Dump удаляется после проверки и не попадает в Git. + +В проверенном запуске восстановлены 35 пользователей, 9 чатов, 17 членств и 8 сообщений; digest совпал, полное время сценария составило 1 секунду. RPO равен моменту snapshot, который видит `pg_dump`: транзакции, зафиксированные после начала snapshot, не входят в этот backup. RTO в 1 секунду относится к малому учебному набору; с ростом объёма он увеличится. + +| Воздействие | Ожидаемое поведение | Наблюдение | Восстановление и потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| штатный restart API, PostgreSQL и Valkey | readiness временно недоступен, затем старые данные и токен читаются | persistence-тест прошёл | автоматическое восстановление; подтверждённые данные не потеряны | +| недоступен PostgreSQL | readiness и операции с данными возвращают `503` | реальный контейнер остановлен; после запуска прежний токен снова сработал | после возврата БД; анонимный доступ не разрешается | +| недоступен Valkey | readiness и Bearer-аутентификация возвращают `503` | реальный контейнер остановлен; после запуска AOF восстановил прежний токен | после возврата Valkey; запрос не считается аутентифицированным | +| истёк TTL или logout | токен возвращает `401` | integration и public smoke прошли | повторный login создаёт новую сессию | +| restore из backup | новая БД содержит снимок исходной | counts, memberships и message digest совпали | 1 с на учебном наборе; RPO равен snapshot | + +## CI/CD и мониторинг + +`.gitea/workflows/ci.yml` запускается для PR в `main`, push в solution/main и вручную. Он проверяет контракт, OpenAPI, форматирование, golangci-lint, race unit-тесты, сборку, public smoke, реальные PostgreSQL/Valkey integration-тесты и persistence. + +Production deployment вынесен в `.gitea/workflows/deploy.yml`. Gitea 1.27 не поддерживает обязательное подтверждение environment, поэтому подтверждением служит ручной `workflow_dispatch` со строкой `DEPLOY`. Workflow разрешает только ветку `main` и для exact SHA повторяет OpenAPI, lint, race, smoke, integration, реальный dependency outage и persistence. После зелёных проверок он делает backup, создаёт release-каталог по SHA и номеру попытки и выполняет health check. Для включения требуются repository secrets `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_KEY`, `DEPLOY_KNOWN_HOSTS`; на сервере заранее создаются `/opt/mtusi-lab2/shared/.env` и `/opt/mtusi-lab2/shared/secrets`. + +Профиль monitoring собирает метрики без пользовательских ID и raw URL в labels. Дашборд содержит RPS, классы HTTP-ответов, p95, in-flight, Go heap, соединения и транзакции PostgreSQL, размер БД, память, ключи и команды Valkey. Мониторинг не участвует в readiness приложения. ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- Стенд содержит одну API-реплику. Горизонтальное масштабирование и idempotency появляются в лабораторной 3. +- Локальный HTTP не шифруется. На сервере Basic и Bearer должны передаваться только через TLS reverse proxy; это будет частью эксплуатационной защиты последующих лабораторных. +- Valkey AOF `everysec` сохраняет сессии при штатном рестарте, но допускает потерю примерно последней секунды при аварии процесса или узла. +- PostgreSQL `COMMIT` подтверждает фиксацию согласно `synchronous_commit`, `fsync` и надёжности диска. Он не заменяет внешние backup и репликацию. +- Exporters в локальном профиле используют учебные credentials сервисов. Для production следует создать отдельного пользователя PostgreSQL с ролью `pg_monitor` и ограничить сетевой доступ к Prometheus/Grafana. +- Эксперимент измеряет один запрос и короткие локальные серии. Для production нужны длительные прогоны, несколько объёмов данных, холодный cache, конкурентное чтение и запись. + +## Ответы на вопросы защиты + +`COMMIT` делает изменения транзакции видимыми как единое целое и фиксирует их согласно настройкам durability PostgreSQL. Гарантия пережить отказ зависит от `fsync`, `synchronous_commit`, WAL и физического хранилища. + +Сессии находятся в Valkey. TTL удаляет истёкшие ключи, logout удаляет ключ немедленно. AOF сохраняет их при рестарте; `FLUSHDB` удалит сессии, после чего клиенты должны войти заново. + +Аутентификация отвечает на вопрос, кто выполняет запрос: Bearer-токен связывается с пользователем. Авторизация дополнительно проверяет членство пользователя в конкретном чате. Валидная сессия не даёт доступ к чужому чату. + +Argon2id намеренно медленный и требует память, поэтому усложняет перебор паролей. Быстрый checksum предназначен для обнаружения случайного изменения данных и не подходит для хранения паролей.