From ed7a27629d1acd4736f730aea6b6e1f7d5bf3086 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D0=B0=D0=BC=D0=BE=D1=85=D0=B2=D0=B0=D0=BB=D0=BE?= =?UTF-8?q?=D0=B2=20=D0=90=D0=BD=D0=B4=D1=80=D0=B5=D0=B9=20=D0=A0=D0=B5?= =?UTF-8?q?=D0=BC=D0=BE=D0=B2=D0=B8=D1=87?= Date: Fri, 2 Oct 2026 10:55:08 +0300 Subject: [PATCH] Build persistent Compose stack and verify full restart --- .dockerignore | 2 + .env.example | 11 +----- .github/workflows/application.yml | 32 ++++++++++++++++ Dockerfile | 12 ++++++ REPORT.md | 61 ++++++++++++++++++++++++------- compose.yaml | 48 ++++++++++++++++++++++++ evidence/restart-2026-10-02.txt | 30 +++++++++++++++ scripts/restart.sh | 8 ++++ 8 files changed, 181 insertions(+), 23 deletions(-) create mode 100644 .github/workflows/application.yml create mode 100644 Dockerfile create mode 100644 compose.yaml create mode 100644 evidence/restart-2026-10-02.txt create mode 100755 scripts/restart.sh diff --git a/.dockerignore b/.dockerignore index bc16e556..a917814f 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,5 +1,7 @@ .git .github +docs/plans +LAB_NOTES.md .env .env.* !.env.example diff --git a/.env.example b/.env.example index 714c8076..6f07f875 100644 --- a/.env.example +++ b/.env.example @@ -1,11 +1,4 @@ -# Copy to .env for your LOCAL synthetic test environment; never commit .env. -# These are logical interface suggestions; map actual framework names in REPORT.md. -APP_HOST=0.0.0.0 +# Copy to .env for the local Compose stack; never commit .env. APP_PORT=8080 -APP_ENV=lab SESSION_TTL_SECONDS=3600 -# Choose credentials locally. File paths contain no secret values. -DATABASE_URL_FILE=/run/secrets/database_url -# Optional on 3, required use on 4 in lab2; Redis OR Valkey: -SESSION_STORE=postgres -CACHE_URL_FILE=/run/secrets/cache_url +# Create secrets/postgres_password and secrets/database_url locally before Compose. diff --git a/.github/workflows/application.yml b/.github/workflows/application.yml new file mode 100644 index 00000000..31298a27 --- /dev/null +++ b/.github/workflows/application.yml @@ -0,0 +1,32 @@ +name: Application +on: [push, pull_request] +permissions: + contents: read +jobs: + smoke: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Create disposable local secrets + run: | + python3 - <<'PY' + from pathlib import Path + from secrets import token_urlsafe + + Path('secrets').mkdir(exist_ok=True) + password = token_urlsafe(32) + Path('secrets/postgres_password').write_text(password) + Path('secrets/database_url').write_text( + f'postgresql://messenger:{password}@postgres:5432/messenger' + ) + Path('.env').write_text(Path('.env.example').read_text()) + PY + - name: Build and start + run: docker compose --env-file .env up -d --build --wait + - name: Public API smoke + run: make test + - name: Persistence through full restart + run: make test-persistence ACTION_SCRIPT=scripts/restart.sh + - name: Stop without deleting data + if: always() + run: docker compose --env-file .env down diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..cda9cd4d --- /dev/null +++ b/Dockerfile @@ -0,0 +1,12 @@ +FROM python:3.12.12-slim-bookworm + +ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 +WORKDIR /app +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt && useradd --system --uid 10001 --home /app app +COPY --chown=app:app src/ src/ +COPY --chown=app:app migrations/ migrations/ +COPY --chown=app:app scripts/migrate.py scripts/migrate.py +USER app +EXPOSE 8080 +CMD ["sh", "-c", "python scripts/migrate.py && exec python -m src.server"] diff --git a/REPORT.md b/REPORT.md index e42f2b05..86eac0dc 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,70 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Самохвалов Андрей Ремович, БПИ-2302. +- Целевая оценка: 5, трек 2 (сравнение запросов и восстановление). Доказательства уровня 4 и трека 2 дополняются в следующих блоках работы. +- Ветка: `solution/bpi2302-samohvalov`; commit/PR указываются после публикации. +- Источники: `README.md`, `COURSE.md`, `contracts/README.md`, `contracts/openapi.json`, публичные тесты и примеры этого репозитория; FastAPI, psycopg, PostgreSQL и Argon2id. Код и инструкции подготовлены с помощью ИИ Codex и проверяются запуском команд ниже. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Нужны Docker с Compose, Python 3.9+ и `make`. Стенд рассчитан на учебный localhost. API собирается из исходников в `python:3.12.12-slim-bookworm`; БД — `postgres:17.6-bookworm`. Python-зависимости закреплены в `requirements.txt`. Порт API опубликован только на `127.0.0.1:8080`; PostgreSQL наружу не публикуется. На моей macOS с Colima команды `make test` и `make test-persistence` выполнялись на хосте с разрешённым доступом к Docker socket и loopback. В ограниченном sandbox `127.0.0.1:8080` был недоступен; проверка не запускалась внутри VM и SSH-туннель не требовался. + +После чистого clone создать локальные файлы, которые исключены из Git: + +```sh +cp .env.example .env +mkdir -p secrets +python3 - <<'PY' +from pathlib import Path +from secrets import token_urlsafe + +password = token_urlsafe(32) +Path('secrets/postgres_password').write_text(password) +Path('secrets/database_url').write_text( + f'postgresql://messenger:{password}@postgres:5432/messenger' +) +PY +chmod 600 .env secrets/* +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build --wait +make check +make test +make test-persistence ACTION_SCRIPT=scripts/restart.sh +``` + +На каждом старте API выполняет `scripts/migrate.py` под advisory lock: миграции `001` и `002` применяются только один раз и завершаются до приёма запросов. `docker compose --env-file .env exec -T api python scripts/migrate.py` безопасно повторить вручную. `GET /health/ready` требует доступную БД. `docker compose --env-file .env down` останавливает стенд с сохранением именованного volume. Только для намеренного уничтожения учебных данных: `docker compose --env-file .env down -v`. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +Клиент → FastAPI (`api`) → PostgreSQL (`postgres`); `postgres_data` сохраняет состояние между перезапусками. PostgreSQL — источник истины для users, chats, memberships, messages и sessions. Создание чата с участниками выполняется одной транзакцией. Пароль хранится как Argon2id hash, непрозрачный токен выдаётся только клиенту, в БД лежит его SHA-256 и абсолютный срок действия. Из lab1 сохранены чаты, членство, сообщения и keyset-пагинация; `X-User-Id` заменён входом по Basic и запросами по Bearer. `.env.example` задаёт опубликованный `APP_PORT` и `SESSION_TTL_SECONDS`; `DATABASE_URL_FILE`, `APP_HOST` и порт внутри контейнера установлены Compose. Pool ограничен восемью соединениями и SQL timeout 5 секунд. + +| Роль | Образ/версия | Проверка | Хранилище/секрет | +| --- | --- | --- | --- | +| API | Собственный build на Python 3.12.12 | `/health/ready` | Без volume; `database_url` через Docker secret | +| PostgreSQL | postgres:17.6-bookworm | `pg_isready` | `postgres_data`; `postgres_password` через Docker secret | ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Публичный smoke | `make test BASE_URL=http://127.0.0.1:8080` | PASS, lab2 public API scenario | `evidence/restart-2026-10-02.txt` | +| Стенд и миграции уровня 3 | `docker compose --env-file .env up -d --build --wait`; повторный `scripts/migrate.py` | API и БД healthy, повторная миграция завершилась без ошибки | `evidence/restart-2026-10-02.txt` | +| Сохранность уровня 3 | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS: прежние данные и сессия после рестарта обоих сервисов | `evidence/restart-2026-10-02.txt` | +| Отказ обязательной БД | Остановить `postgres`, запросить readiness и защищённый endpoint | Оба HTTP 503; затем БД восстановлена, сервисы healthy | `evidence/restart-2026-10-02.txt` | +| Уровень 4 | Выполняется в следующих блоках | Пока не заявлен как проверенный | — | +| Трек 5 | Выполняется после уровня 4 | Пока не заявлен как проверенный | — | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +У `api` и `postgres` изменились времена `StartedAt` при сохранении именованного volume; точные значения приведены в evidence. Это подтверждает фактический перезапуск обоих контейнеров. Проверка `make validate` локально пока не завершена: DNS до `files.pythonhosted.org` не позволил установить `openapi-spec-validator==0.7.2`; отдельный CI workflow устанавливает зависимости из `requirements-dev.txt` для проверки контракта. ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Исследование производительности и восстановления выполняется в блоках уровня 4 и трека 5. Текущий стенд — Colima на arm64 macOS с Docker/Compose; значения производительности здесь не заявлены. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| Полный restart API и PostgreSQL | Тот же действующий токен читает сообщение | Публичный persistence PASS | Подтверждённая запись сохранена; время восстановления в пределах лимита hook | +| Остановка PostgreSQL | Readiness и защищённый запрос дают ограниченный отказ | Оба HTTP 503; после запуска БД healthy | Без принятия анонимного запроса | ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +Подтверждён рестарт одного API и одного PostgreSQL с сохранением volume. Это не высокая доступность: отказ БД временно делает API недоступным. Локальный HTTP не предназначен для удалённой передачи паролей без TLS. Valkey, проверки уровня 4, сравнение ≥100 000 сообщений и восстановление в новое хранилище ещё должны быть добавлены; их результаты нельзя выводить из smoke или persistence теста. diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..036ca8eb --- /dev/null +++ b/compose.yaml @@ -0,0 +1,48 @@ +name: mtusi2026lab2 + +services: + postgres: + image: postgres:17.6-bookworm + environment: + POSTGRES_DB: messenger + POSTGRES_USER: messenger + POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password + secrets: + - postgres_password + volumes: + - postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"] + interval: 2s + timeout: 2s + retries: 20 + + api: + build: . + environment: + APP_HOST: 0.0.0.0 + APP_PORT: 8080 + DATABASE_URL_FILE: /run/secrets/database_url + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + secrets: + - database_url + depends_on: + postgres: + condition: service_healthy + ports: + - "127.0.0.1:${APP_PORT:-8080}:8080" + healthcheck: + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2).close()"] + interval: 2s + timeout: 3s + retries: 20 + start_period: 5s + +secrets: + postgres_password: + file: ./secrets/postgres_password + database_url: + file: ./secrets/database_url + +volumes: + postgres_data: diff --git a/evidence/restart-2026-10-02.txt b/evidence/restart-2026-10-02.txt new file mode 100644 index 00000000..a90aa399 --- /dev/null +++ b/evidence/restart-2026-10-02.txt @@ -0,0 +1,30 @@ +Lab 2 local Compose verification, 2026-10-02 (UTC timestamps) +Checks ran on the macOS host with Docker socket and loopback access enabled; +the restricted sandbox could not reach 127.0.0.1:8080. No VM-local run or +SSH tunnel was used. + +docker compose --env-file .env config --quiet -> exit 0 +docker compose --env-file .env up -d --build --wait -> API and PostgreSQL healthy +make test BASE_URL=http://127.0.0.1:8080 -> PASS: lab2 public API scenario +make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080 + -> PASS: persistence preserved confirmed data and existing session + +docker inspect before persistence hook: + api 2026-10-02T07:18:38.19716Z + postgres 2026-10-02T07:18:37.971410919Z +docker inspect after persistence hook: + api 2026-10-02T07:20:21.164948401Z + postgres 2026-10-02T07:20:18.602237039Z +Both service StartedAt values changed; container IDs stayed constant. Compose retained +the named mtusi2026lab2_postgres_data volume. No volume deletion or seed occurred. + +With PostgreSQL stopped, GET /health/ready and GET /api/v1/users/me with a +syntactically valid but unknown Bearer each returned HTTP 503. Compose then +started PostgreSQL again; both services returned healthy. +After recovery, make test passed again. Querying schema_migrations returned +one row for version 1 and one row for version 2 after repeated migration runs. + +make check -> PASS: offline skeleton structure, local refs and Python syntax +make validate PYTHON=.venv/bin/python -> not run successfully: the pinned +openapi-spec-validator package was absent and pip could not resolve +files.pythonhosted.org in this environment. The CI job installs it separately. diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..639f272e --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,8 @@ +#!/bin/sh +set -eu + +cd "$(dirname "$0")/.." +# Stop and start every current service, including state stores added in later labs. +# Compose preserves named volumes because neither command removes them. +docker compose --env-file .env stop +docker compose --env-file .env up -d --wait