diff --git a/.dockerignore b/.dockerignore index bc16e556..639a55ae 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,4 +1,6 @@ .git +docs/plans +LAB_NOTES.md .github .env .env.* diff --git a/.env.example b/.env.example index d32b9be0..ac22be39 100644 --- a/.env.example +++ b/.env.example @@ -1,13 +1,3 @@ -# 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; create secrets/postgres_password and secrets/database_url locally. 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 -API_REPLICAS=2 -IDEMPOTENCY_TTL_SECONDS=86400 diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..1ecad6dc --- /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 ["python", "-m", "src.server"] diff --git a/REPORT.md b/REPORT.md index c2679005..cd2d7d56 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,57 @@ # Отчёт — лабораторная 3 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор: Самохвалов Андрей Ремович, БПИ-2302. +- Цель: оценка 5, трек 1 (цена масштабирования). Уровень 4 и исследование трека дополняются следующими блоками. +- Ветка: `solution/bpi2302-samohvalov`; commit/PR после публикации. +- Источники: `README.md`, `COURSE.md`, `contracts/`, публичные тесты репозитория, [HAProxy 3.0 configuration](https://docs.haproxy.org/3.0/configuration.html), [Docker Compose services](https://docs.docker.com/reference/compose-file/services/). Код и текст подготовлены с помощью Codex; результаты ниже получены реальным запуском. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Нужны Docker с Compose, Python 3.9+ и `make`. Dockerfile собирает исходники в `python:3.12.12-slim-bookworm`; БД — `postgres:17.6-bookworm`, балансировщик — `haproxy:3.0.11-alpine`. Python-пакеты закреплены в `requirements.txt`. Стенд рассчитан на localhost и синтетические данные. + +```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 --scale api=2 +make check +make test +make test-persistence ACTION_SCRIPT=scripts/restart.sh +make test-failover ACTION_SCRIPT=scripts/stop-one.sh +docker compose --env-file .env up -d --wait --scale api=2 # восстановить остановленную реплику +``` + +Для повторного failover после восстановления балансировщик должен обслуживать обе реплики; повторите команду и сверьте, какой контейнер остановлен. `docker compose --env-file .env ps -a` показывает реальный процесс. `migrate` — одноразовый сервис, который под advisory lock применяет SQL-миграции до запуска API; повторный `up` безопасно проверяет уже применённые версии. `docker compose --env-file .env down` сохраняет volume. Только для намеренного удаления учебных данных: `docker compose --env-file .env down -v`. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +Клиент → HAProxy (`lb`, единственный опубликованный порт) → две FastAPI-реплики (`api`) → общий PostgreSQL (`postgres`). Сессии, сообщения и записи идемпотентности хранятся в PostgreSQL. Каждая реплика принимает любой действующий Bearer без sticky session. `X-Instance-Id` — случайный alias, постоянный в пределах процесса. Внешний порт PostgreSQL и API не опубликован. -## Доказательства критериев +Балансировка round-robin использует `server-template` на четыре слота, Docker DNS `127.0.0.11`, повторное разрешение адресов и `/health/ready` раз в 1 секунду (`fall 2`, `rise 1`). Сбой backend обнаруживается примерно за 2 проверки; проверка через публичный endpoint важнее расчётного интервала. HAProxy имеет connect timeout 2 с и client/server timeout 15 с. Compose ждёт готовности БД и однократной миграции; API имеет 10-секундный `stop_grace_period`, Uvicorn получает SIGTERM как главный процесс контейнера. На API установлены ограничения 0.5 CPU/256 MiB на реплику, на LB — 0.5 CPU/128 MiB. Дополнительное исследование фиксированного суммарного бюджета выполняется позже. -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | -| --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +Создание чата и членов атомарно. POST сообщения требует ключ `[A-Za-z0-9._:-]{1,128}`; PostgreSQL unique key `(user_id, chat_id, request_key)` резервируется в транзакции вместе с сообщением и ссылкой на результат. Конкурентный повтор ждёт исход первой транзакции. При одинаковом тексте возвращается тот же `201 Message`, при другом — `409`. Ключ другой пары пользователь/чат независим. Повтор проверяет Bearer и членство до чтения сохранённого результата. Записи старше 24 часов по тому же ключу удаляются перед новым запросом; массовая очистка исторических ключей пока не автоматизирована. -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +## Проверки уровня 3 -## Эксперименты и отказы +| Критерий | Команда/наблюдение | Результат | +| --- | --- | --- | +| Контракт | `make check`; локальный `make test BASE_URL=http://127.0.0.1:8083` через LB | PASS; публичный lab3 smoke | +| Реальные реплики | 12 GET `/health/live` через LB, `docker compose ps -a` | Два разных `X-Instance-Id`, два healthy API-контейнера; только LB опубликован наружу | +| Конкурентная идемпотентность | `python -m unittest discover -s student-tests` на временной PostgreSQL | 7 тестов PASS; два конкурентных вызова, одна запись `messages` | +| Полный рестарт | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS, прежние данные и токен; времена `StartedAt` обеих API, LB и PostgreSQL изменились | +| Отказ API-1 | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`; `docker compose ps -a` | PASS, 2 реплики до отказа, 112 записей, 1 переходная ошибка, первая успешная запись через 2.935 с; API-1 `Exited (0)` | +| Отказ API-2 | Восстановить API-1, сдвинуть round-robin одним GET, повторить failover | PASS, 2 реплики до отказа, 110 записей, 1 переходная ошибка, первая успешная запись через 3.985 с; API-2 `Exited (0)` | -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Сырые безопасные агрегаты и времена контейнеров: `evidence/failover-2026-10-02.txt`. После опытов обе реплики восстановлены. Проверки выполнялись на macOS/Colima arm64 с локальным портом 8083, поскольку 8080 занят стендом lab2. На чистом clone `.env.example` использует 8080. `make validate` локально не запускался: зависимость `openapi-spec-validator` недоступна из-за DNS к `files.pythonhosted.org`; обязательный контракт не менялся, штатный CI job `contracts.yml` выполняет validate. -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +## Ограничения и дальнейшие измерения -## Ограничения и следующие шаги - -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +Стенд имеет один Docker-host, один LB и один PostgreSQL: отказ узла или БД не переживает. `depends_on` гарантирует порядок запуска, а маршрутизацию выполняет HAProxy. Проверка failover измеряет краткие ошибки и время восстановления, но не RPS до/после и не rolling update; это и исследование 1/2/4 реплик на фиксированном бюджете с повторениями будут добавлены для уровня 4/5. Текущий локальный HTTP разрешён только для изолированного стенда с синтетическими данными; удалённая демонстрация требует TLS. diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..7e762985 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,70 @@ +name: mtusi2026lab3 + +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 + + migrate: + build: . + command: ["python", "scripts/migrate.py"] + environment: + DATABASE_URL_FILE: /run/secrets/database_url + secrets: [database_url] + depends_on: + postgres: + condition: service_healthy + restart: "no" + + api: + build: . + scale: 2 + 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: + migrate: + condition: service_completed_successfully + 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 + stop_grace_period: 10s + cpus: 0.5 + mem_limit: 256m + + lb: + image: haproxy:3.0.11-alpine + volumes: + - ./infra/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro + ports: + - "127.0.0.1:${APP_PORT:-8080}:8080" + depends_on: + api: + condition: service_healthy + cpus: 0.5 + mem_limit: 128m + +secrets: + postgres_password: + file: ./secrets/postgres_password + database_url: + file: ./secrets/database_url + +volumes: + postgres_data: diff --git a/evidence/failover-2026-10-02.txt b/evidence/failover-2026-10-02.txt new file mode 100644 index 00000000..85f443e3 --- /dev/null +++ b/evidence/failover-2026-10-02.txt @@ -0,0 +1,40 @@ +Lab 3 local Compose evidence, 2026-10-02, macOS/Colima arm64. +All public requests used HAProxy at http://127.0.0.1:8083; API and PostgreSQL +had no published host ports. The local .env and secrets are ignored by Git. + +docker compose --env-file .env config --quiet -> PASS +docker compose --env-file .env up -d --build --wait --scale api=2 -> + api-1 healthy, api-2 healthy, postgres healthy, migrate exited 0, lb running. +make check -> PASS +make test BASE_URL=http://127.0.0.1:8083 -> PASS: lab3 public API scenario. +12 GET /health/live through LB observed two X-Instance-Id values. + +Isolated PostgreSQL integration run before Compose: + python -m unittest discover -s student-tests -v -> 7 tests, OK. + Concurrent same-key requests returned identical Message; SQL count was 1. + +make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://127.0.0.1:8083 + API-1 stop: observed_instances_before=2, successful_writes=112, + failed_attempts=1, first_recovery_seconds=2.935, PASS. + docker compose ps -a: api-1 Exited (0), api-2 healthy, lb/postgres running. + Restored api-1 using docker compose up -d --wait --scale api=2. + A repeat selected api-1 again; it was not counted as the second-replica proof. + Restored api-1, sent one GET to advance round-robin, and repeated: + API-2 stop: observed_instances_before=2, successful_writes=110, + failed_attempts=1, first_recovery_seconds=3.985, PASS. + docker compose ps -a: api-2 Exited (0), api-1 healthy, lb/postgres running. + Restored api-2; both replicas healthy. + +Persistence hook proof, times UTC; named postgres_data volume preserved: + before: + api-1 2026-10-02T08:46:12.886332892Z + api-2 2026-10-02T08:48:59.563753865Z + lb 2026-10-02T08:42:41.675055235Z + postgres 2026-10-02T08:42:32.879514014Z + make test-persistence ACTION_SCRIPT=scripts/restart.sh + -> PASS: confirmed data and existing session survived. + after: + api-1 2026-10-02T08:49:48.469504932Z + api-2 2026-10-02T08:49:48.407940425Z + lb 2026-10-02T08:49:54.047109297Z + postgres 2026-10-02T08:49:45.282318374Z diff --git a/infra/haproxy.cfg b/infra/haproxy.cfg new file mode 100644 index 00000000..40952ab9 --- /dev/null +++ b/infra/haproxy.cfg @@ -0,0 +1,26 @@ +global + log stdout format raw local0 + +defaults + mode http + log global + option httplog + timeout connect 2s + timeout client 15s + timeout server 15s + +resolvers docker + nameserver docker 127.0.0.11:53 + resolve_retries 2 + timeout retry 1s + hold valid 1s + +frontend public + bind *:8080 + default_backend api + +backend api + balance roundrobin + option httpchk GET /health/ready + http-check expect status 200 + server-template api 1-4 api:8080 check inter 1s fall 2 rise 1 resolvers docker init-addr none diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..c9148ca0 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,5 @@ +#!/bin/sh +set -eu +cd "$(dirname "$0")/.." +docker compose --env-file .env stop api lb postgres +docker compose --env-file .env up -d --wait --scale api=2 diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100755 index 00000000..99c65a25 --- /dev/null +++ b/scripts/stop-one.sh @@ -0,0 +1,13 @@ +#!/bin/sh +set -eu +cd "$(dirname "$0")/.." +: "${TARGET_INSTANCE_ID:?test provides target API instance alias}" +for container in $(docker compose --env-file .env ps -q api); do + instance=$(docker exec "$container" python -c "import urllib.request; print(urllib.request.urlopen('http://127.0.0.1:8080/health/live', timeout=2).headers['X-Instance-Id'])") + if [ "$instance" = "$TARGET_INSTANCE_ID" ]; then + docker stop -t 5 "$container" >/dev/null + exit 0 + fi +done +echo "target API instance not found" >&2 +exit 1