From ba7bef17e1ed515c3acb09d417a81d72711bd0da Mon Sep 17 00:00:00 2001 From: denis Date: Fri, 6 Nov 2026 18:05:29 +0300 Subject: [PATCH] solution --- .dockerignore | 5 + .env.example | 12 +- .gitignore | 7 + Dockerfile | 55 ++ Makefile | 19 +- REPORT.md | 378 +++++++++++- alembic.ini | 38 ++ evidence/01-contract-and-openapi.txt | 11 + evidence/02-public-smoke.txt | 2 + evidence/03-student-tests.txt | 21 + evidence/04-upload-memory.json | 116 ++++ evidence/05-upload-memory-summary.txt | 28 + evidence/06-persistence.txt | 61 ++ evidence/07-failover.txt | 26 + evidence/08-attachment-failover.json | 13 + evidence/09-s3-outage.json | 34 ++ evidence/10-reconcile.json | 23 + evidence/11-private-bucket.txt | 8 + evidence/12-infrastructure.txt | 102 ++++ evidence/13-load-baseline.txt | 23 + evidence/14-interrupted-upload.json | 17 + evidence/15-bootstrap-idempotent.txt | 6 + evidence/README.md | 29 +- evidence/attachment-failover.json | 13 + evidence/interrupted-upload.json | 17 + evidence/load.json | 17 + evidence/reconcile.json | 23 + evidence/s3-outage.json | 34 ++ evidence/upload-memory.json | 116 ++++ migrations/env.py | 58 ++ migrations/script.py.mako | 24 + migrations/versions/0001_initial_schema.py | 103 ++++ .../versions/0002_message_idempotency.py | 61 ++ migrations/versions/0003_attachments.py | 128 ++++ requirements.txt | 37 ++ scripts/bootstrap-secrets.sh | 49 ++ scripts/check-bucket-private.sh | 48 ++ scripts/collect_infrastructure.py | 117 ++++ scripts/deploy.cmd | 4 + scripts/deploy.sh | 52 ++ scripts/hooks.ps1 | 165 ++++++ scripts/minio-init.sh | 86 +++ scripts/reconcile.sh | 14 + scripts/restart.cmd | 4 + scripts/restart.sh | 23 + scripts/restore.cmd | 4 + scripts/restore.sh | 27 + scripts/rolling-update.cmd | 4 + scripts/rolling-update.sh | 20 + scripts/stop-one.cmd | 4 + scripts/stop-one.sh | 50 ++ src/messenger/__init__.py | 5 + src/messenger/__main__.py | 38 ++ src/messenger/access.py | 16 + src/messenger/app.py | 142 +++++ src/messenger/config.py | 283 +++++++++ src/messenger/context.py | 23 + src/messenger/cursor.py | 119 ++++ src/messenger/db.py | 74 +++ src/messenger/deps.py | 133 +++++ src/messenger/domain.py | 109 ++++ src/messenger/errorhandlers.py | 184 ++++++ src/messenger/errors.py | 88 +++ src/messenger/healthcheck.py | 26 + src/messenger/idempotency.py | 42 ++ src/messenger/images.py | 88 +++ src/messenger/logging_setup.py | 76 +++ src/messenger/middleware.py | 99 ++++ src/messenger/models.py | 273 +++++++++ src/messenger/pagination.py | 38 ++ src/messenger/reconcile.py | 190 ++++++ src/messenger/repository.py | 554 ++++++++++++++++++ src/messenger/routers/__init__.py | 1 + src/messenger/routers/attachments.py | 196 +++++++ src/messenger/routers/auth.py | 51 ++ src/messenger/routers/chats.py | 55 ++ src/messenger/routers/health.py | 46 ++ src/messenger/routers/messages.py | 74 +++ src/messenger/routers/users.py | 34 ++ src/messenger/schema.py | 192 ++++++ src/messenger/security.py | 119 ++++ src/messenger/sessions.py | 122 ++++ src/messenger/storage.py | 195 ++++++ src/messenger/upload.py | 100 ++++ stack.yaml | 325 ++++++++++ student-tests/README.md | 27 + student-tests/attachment_failover.py | 96 +++ student-tests/fixtures/sample.jpg | Bin 0 -> 7849 bytes student-tests/harness.py | 74 +++ student-tests/idempotency_probe.py | 53 ++ student-tests/interrupted_upload.py | 128 ++++ student-tests/reconcile_probe.py | 157 +++++ student-tests/run_all.py | 32 + student-tests/s3_outage_probe.py | 114 ++++ student-tests/test_lab3.py | 108 ++++ student-tests/test_lab4.py | 163 ++++++ student-tests/upload_experiment.py | 204 +++++++ 97 files changed, 7579 insertions(+), 23 deletions(-) create mode 100644 Dockerfile create mode 100644 alembic.ini create mode 100644 evidence/01-contract-and-openapi.txt create mode 100644 evidence/02-public-smoke.txt create mode 100644 evidence/03-student-tests.txt create mode 100644 evidence/04-upload-memory.json create mode 100644 evidence/05-upload-memory-summary.txt create mode 100644 evidence/06-persistence.txt create mode 100644 evidence/07-failover.txt create mode 100644 evidence/08-attachment-failover.json create mode 100644 evidence/09-s3-outage.json create mode 100644 evidence/10-reconcile.json create mode 100644 evidence/11-private-bucket.txt create mode 100644 evidence/12-infrastructure.txt create mode 100644 evidence/13-load-baseline.txt create mode 100644 evidence/14-interrupted-upload.json create mode 100644 evidence/15-bootstrap-idempotent.txt create mode 100644 evidence/attachment-failover.json create mode 100644 evidence/interrupted-upload.json create mode 100644 evidence/load.json create mode 100644 evidence/reconcile.json create mode 100644 evidence/s3-outage.json create mode 100644 evidence/upload-memory.json create mode 100644 migrations/env.py create mode 100644 migrations/script.py.mako create mode 100644 migrations/versions/0001_initial_schema.py create mode 100644 migrations/versions/0002_message_idempotency.py create mode 100644 migrations/versions/0003_attachments.py create mode 100644 requirements.txt create mode 100644 scripts/bootstrap-secrets.sh create mode 100644 scripts/check-bucket-private.sh create mode 100644 scripts/collect_infrastructure.py create mode 100644 scripts/deploy.cmd create mode 100644 scripts/deploy.sh create mode 100644 scripts/hooks.ps1 create mode 100644 scripts/minio-init.sh create mode 100644 scripts/reconcile.sh create mode 100644 scripts/restart.cmd create mode 100644 scripts/restart.sh create mode 100644 scripts/restore.cmd create mode 100644 scripts/restore.sh create mode 100644 scripts/rolling-update.cmd create mode 100644 scripts/rolling-update.sh create mode 100644 scripts/stop-one.cmd create mode 100644 scripts/stop-one.sh create mode 100644 src/messenger/__init__.py create mode 100644 src/messenger/__main__.py create mode 100644 src/messenger/access.py create mode 100644 src/messenger/app.py create mode 100644 src/messenger/config.py create mode 100644 src/messenger/context.py create mode 100644 src/messenger/cursor.py create mode 100644 src/messenger/db.py create mode 100644 src/messenger/deps.py create mode 100644 src/messenger/domain.py create mode 100644 src/messenger/errorhandlers.py create mode 100644 src/messenger/errors.py create mode 100644 src/messenger/healthcheck.py create mode 100644 src/messenger/idempotency.py create mode 100644 src/messenger/images.py create mode 100644 src/messenger/logging_setup.py create mode 100644 src/messenger/middleware.py create mode 100644 src/messenger/models.py create mode 100644 src/messenger/pagination.py create mode 100644 src/messenger/reconcile.py create mode 100644 src/messenger/repository.py create mode 100644 src/messenger/routers/__init__.py create mode 100644 src/messenger/routers/attachments.py create mode 100644 src/messenger/routers/auth.py create mode 100644 src/messenger/routers/chats.py create mode 100644 src/messenger/routers/health.py create mode 100644 src/messenger/routers/messages.py create mode 100644 src/messenger/routers/users.py create mode 100644 src/messenger/schema.py create mode 100644 src/messenger/security.py create mode 100644 src/messenger/sessions.py create mode 100644 src/messenger/storage.py create mode 100644 src/messenger/upload.py create mode 100644 stack.yaml create mode 100644 student-tests/README.md create mode 100644 student-tests/attachment_failover.py create mode 100644 student-tests/fixtures/sample.jpg create mode 100644 student-tests/harness.py create mode 100644 student-tests/idempotency_probe.py create mode 100644 student-tests/interrupted_upload.py create mode 100644 student-tests/reconcile_probe.py create mode 100644 student-tests/run_all.py create mode 100644 student-tests/s3_outage_probe.py create mode 100644 student-tests/test_lab3.py create mode 100644 student-tests/test_lab4.py create mode 100644 student-tests/upload_experiment.py diff --git a/.dockerignore b/.dockerignore index bc16e556..07810edc 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,5 +1,10 @@ .git .github +.dockercli +.dsh-tools +.tmp +.venv +.venv-libs .env .env.* !.env.example diff --git a/.env.example b/.env.example index d99d26a2..5d934397 100644 --- a/.env.example +++ b/.env.example @@ -6,15 +6,21 @@ 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 +# Sessions live in Valkey/Redis; SESSION_STORE=postgres is rejected at start. +SESSION_STORE=redis CACHE_URL_FILE=/run/secrets/cache_url API_REPLICAS=2 IDEMPOTENCY_TTL_SECONDS=86400 -S3_ENDPOINT=http://s3:9000 +S3_ENDPOINT=http://minio:9000 S3_REGION=us-east-1 S3_BUCKET=messenger-attachments +S3_KEY_PREFIX=attachments/ S3_ACCESS_KEY_ID_FILE=/run/secrets/s3_access_key_id S3_SECRET_ACCESS_KEY_FILE=/run/secrets/s3_secret_access_key +S3_CONNECT_TIMEOUT_SECONDS=1.5 +S3_READ_TIMEOUT_SECONDS=30 +S3_MAX_ATTEMPTS=2 MAX_UPLOAD_BYTES=10485760 MAX_IMAGE_PIXELS=40000000 +ATTACHMENT_ORPHAN_GRACE_SECONDS=3600 +ATTACHMENT_FAULT_MODE=none diff --git a/.gitignore b/.gitignore index b5a71896..0e9967d1 100644 --- a/.gitignore +++ b/.gitignore @@ -13,6 +13,13 @@ certs/private/ volumes/ data/ backups/ +# Local harness/Docker workaround directories (not part of the lab) +.dockercli/ +.dsh-tools/ +.tmp/ +.venv-libs/ +# Generated by student-tests/upload_experiment.py +student-tests/fixtures/large.png # Runtime/build artifacts .venv/ __pycache__/ diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..c0292722 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,55 @@ +# Сборка и рантайм разделены: в итоговый образ не попадают кэш pip и инструменты +# сборки, а зависимости ставятся по зафиксированному requirements.txt. +# Базовый образ закреплён по неизменяемому digest, а не только по тегу. +FROM python:3.11.9-slim-bookworm@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317 AS builder + +ENV PIP_NO_CACHE_DIR=1 \ + PIP_DISABLE_PIP_VERSION_CHECK=1 \ + PYTHONDONTWRITEBYTECODE=1 + +RUN python -m venv /opt/venv +COPY requirements.txt ./ +RUN /opt/venv/bin/pip install --no-cache-dir --timeout 60 -r requirements.txt + + +FROM python:3.11.9-slim-bookworm@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317 AS runtime + +# Позволяет собрать новую ревизию того же исходника для проверки rolling update: +# метка меняет config образа, поэтому Swarm видит новую image ID и заменяет задачи. +ARG APP_REVISION=local + +LABEL org.opencontainers.image.title="mtusi-messenger-lab4" \ + org.opencontainers.image.description="API мессенджера на PostgreSQL, Valkey и S3, лабораторная 4 (MTUSI HighLoad)" \ + org.opencontainers.image.version="4.0.0" \ + org.opencontainers.image.revision="${APP_REVISION:-local}" + +ENV PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + PATH="/opt/venv/bin:$PATH" \ + PYTHONPATH=/app/src \ + APP_HOST=0.0.0.0 \ + APP_PORT=8080 + +WORKDIR /app + +RUN useradd --create-home --uid 10001 --shell /usr/sbin/nologin app + +COPY --from=builder /opt/venv /opt/venv + +# Миграции лежат в образе: роль контейнера задаётся командой (api или migrate). +COPY --chown=app:app src/ ./src/ +COPY --chown=app:app alembic.ini ./ +COPY --chown=app:app migrations/ ./migrations/ + +# Приложение работает без прав root: в образе нет ни компилятора, ни secrets. +USER 10001:10001 + +EXPOSE 8080 + +# SIGTERM доходит до PID 1 напрямую: uvicorn завершает запросы в своём бюджете. +STOPSIGNAL SIGTERM + +HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \ + CMD ["python", "-m", "messenger.healthcheck"] + +CMD ["python", "-m", "messenger"] \ No newline at end of file diff --git a/Makefile b/Makefile index 5d86d171..261e1ea2 100644 --- a/Makefile +++ b/Makefile @@ -4,10 +4,12 @@ CA_FILE ?= ACTION_SCRIPT ?= TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",) -.PHONY: help check validate test load test-persistence test-failover +.PHONY: help check validate test load test-persistence test-failover secrets deploy stack-down student-test reconcile help: @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes" + @echo "deploy: build image + deploy stack.yaml (POSIX); secrets: create local files" + @echo "student-test: own lab4 checks; reconcile: S3/PostgreSQL reconciliation (dry-run)" check: $(PYTHON) scripts/check_contract.py @@ -28,3 +30,18 @@ test-persistence: test-failover: @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2) $(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) + +secrets: + sh scripts/bootstrap-secrets.sh + +deploy: + sh scripts/deploy.sh + +stack-down: + docker stack rm lab4 + +student-test: + $(PYTHON) student-tests/run_all.py --base-url "$(BASE_URL)" + +reconcile: + docker exec $$(docker ps -q -f name=lab4_api | head -1) python -m messenger.reconcile --dry-run diff --git a/REPORT.md b/REPORT.md index 9ad2b84f..82486962 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,383 @@ # Отчёт — лабораторная 4 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Кокорин Денис, БВТ2301 +- Целевая оценка: **4** — весь уровень 3 и весь уровень 4; трек 5 не заявляется +- Commit/PR: коммиты в этой сессии намеренно не создавались; решение лежит в + рабочем дереве. Ссылка на PR появится после публикации автором. +- Использованные источники: skeleton лабораторной 4 (README, contracts, tests), + собственная реализация и отчёт лабораторной 3 из `mtusi2026lab3`, документация + Docker Swarm, Traefik 3.5, PostgreSQL, MinIO, FastAPI/SQLAlchemy/boto3/Pillow. + Помощь ИИ: генерация и ревью кода, текста отчёта и сценариев проверки; все + команды и выводы в [evidence](evidence/README.md) получены на описанном стенде. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +### Версии и предпосылки + +| Компонент | Версия | Примечание | +| --- | --- | --- | +| Python | 3.11.9 | приложение и миграции; в образе `python:3.11.9-slim-bookworm` | +| Docker Engine | 28.0.1 | Docker Desktop, Linux containers | +| Docker Swarm | single manager/worker | `docker swarm init` при необходимости | +| PostgreSQL | `postgres:16.15-bookworm` | digest `sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4` | +| Valkey | `valkey/valkey:8.0.11-trixie` | digest `sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab` | +| Traefik | `traefik:v3.5.4` | единственная публичная точка входа | +| MinIO | `minio/minio@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e` | release `RELEASE.2025-09-07T16-13-09Z` (label образа) | +| Приложение | `mtusi-messenger-lab4:4.0.0` | собирается `Dockerfile` | + +Стенд измерен на Docker Desktop Linux VM: **6 CPU / 4 GiB** (`docker info`: +`cpus=6`, `mem=4103159808`). Лимиты контейнеров заданы в `stack.yaml`: API +1.0 CPU / 512 MiB, PostgreSQL 2.0 CPU / 512 MiB, MinIO 1.0 CPU / 512 MiB, +Valkey 1.0 CPU / 256 MiB, Traefik 0.5 CPU / 128 MiB. Абсолютные числа не +переносятся на другой хост; сравнивать нужно одинаковые профили. + +### Одна последовательность запуска (Swarm) + +Выбран **Docker Swarm**: он даёт service discovery, readiness-фильтрацию через +Traefik, start-first rolling update и явное управление задачами без +`container_name`. Все зависимости поднимаются из этого репозитория. + +Linux / macOS: + +```sh +git clone && cd mtusi2026lab4 +chmod +x scripts/*.sh +sh scripts/bootstrap-secrets.sh # создаёт secrets/*, повторно не перезаписывает +sh scripts/deploy.sh # swarm init (если нужно), secret create, build, stack deploy +# deploy.sh сам ждёт /health/ready до 180 с +curl -fsS http://127.0.0.1:8080/health/ready +``` + +Windows PowerShell (именно так получен evidence на этом стенде): + +```powershell +powershell -NoProfile -ExecutionPolicy Bypass -File scripts\hooks.ps1 -Mode deploy +``` + +Проверки: + +```sh +make check +make validate PYTHON=.venv/bin/python # requirements-dev.txt +make test BASE_URL=http://127.0.0.1:8080 +make test-persistence ACTION_SCRIPT=scripts/restart.sh +make test-failover ACTION_SCRIPT=scripts/stop-one.sh +make student-test BASE_URL=http://127.0.0.1:8080 +``` + +На Windows публичные тесты запускают action-скрипт через `Popen([script])` без +shell, поэтому используются `.cmd`-двойники: `scripts/restart.cmd`, +`scripts/stop-one.cmd`, `scripts/restore.cmd`. В этой среде MSYS-`make` под +sandbox падал на создании signal pipe (Win32 error 5), а Python по умолчанию +открывал UTF-8 контракт как cp1251; поэтому evidence получен прямым запуском +Python с `PYTHONUTF8=1`. На Linux команды выше выполняются штатно. + +### Остановка и удаление учебных данных + +```sh +docker stack rm lab4 # убрать сервисы; named volumes остаются +docker volume rm lab4_pgdata lab4_valkeydata lab4_miniodata # только осознанно: удаляет данные +docker secret rm lab4_database_url lab4_cache_url lab4_postgres_password lab4_cursor_secret \ + lab4_s3_root_user lab4_s3_root_password lab4_s3_access_key_id lab4_s3_secret_access_key +docker config rm lab4_lab4_minio_init # config завершившегося bootstrap +``` + +`scripts/restart.sh|cmd` и `scripts/stop-one.sh|cmd` никогда не удаляют тома, +не пересоздают БД и не делают seed. `stop-one` останавливает ровно одну задачу +по `X-Instance-Id` (hostname контейнера); Swarm создаёт новую задачу с новым +hostname — это разрешено условиями лабораторной. `scripts/restore.sh|cmd` +возвращает 2 реплики и ждёт готовности. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +``` +Клиент -> Traefik :8080 (единственная публикация, ingress) + | healthcheck /health/ready каждые 2 s, timeout 1 s + +--> api.1 (1 CPU / 512 MiB) --+--> PostgreSQL (метаданные, истина) + +--> api.2 (1 CPU / 512 MiB) --+--> Valkey (сессии, AOF) + +--> MinIO (приватные байты, bucket) + minio-init (одна задача) --> bucket + private + restricted API user + migrate (одна задача) --> alembic upgrade head (0003_attachments) +``` + +- **Источник истины**: PostgreSQL хранит пользователей, чаты, членство, + сообщения, идемпотентность и метаданные вложений. **Байты** вложений лежат + только в приватном S3-bucket MinIO; в PostgreSQL и в постоянном локальном + каталоге API оригинала нет. +- **Object key** назначает сервер: `attachments/`. `filename` + используется только для отображения и не участвует в пути/ключе. Bucket + создаётся без anonymous-доступа; `filename` с `/`, `\`, NUL и + управляющими символами отклоняется. +- **upload**: сначала аутентификация и доступ к чату (404 для чужого), затем + `filename` и `Content-Type`, затем `Content-Length`-лимит до чтения тела. + Тело читается чанками 64 KiB во временный файл (не `request.body()`), + параллельно считаются SHA-256 и MD5. Pillow проверяет сигнатуру/формат/ + целостность и число пикселей по заголовку до полной распаковки. Затем + вставляется `attachments.status='pending'` (намерение), выполняется S3 PUT + с проверкой ETag=MD5, и только после успешного COMMIT статус становится + `ready`; ответ 201 отдаёт ровно сохранённые метаданные. Временный файл + удаляется в `finally`. +- **download**: API проверяет членство в чате, берёт метаданные из PostgreSQL и + стримит объект из S3 через `StreamingResponse`; redirect и presigned URL в + обязательном контракте не используются. `Content-Type` и `Content-Length` + соответствуют оригиналу. +- **Сообщение с вложениями**: таблица `message_attachments` хранит + `(message_id, attachment_id, position)`; `attachment_ids` проверяются на + существование, принадлежность именно этому чату и статус `ready`. Чужое/ + неизвестное — 404, pending — 409. Канонический хэш идемпотентности включает + отсортированный список `attachment_ids`; повтор с тем же ключом и телом + возвращает то же Message, другое тело — 409. Текст может быть пустым только + при наличии хотя бы одного вложения. +- **Готовность**: `/health/live` проверяет только процесс. `/health/ready` + проверяет PostgreSQL, ревизию схемы `0003_attachments`, Valkey и S3 + (листинг одного объекта под префиксом вложений). Пока S3 недоступен, Traefik + не направляет трафик на API; недоступность Grafana/вспомогательных сервисов + API не останавливает. +- **Границы отказа**: pending-строка пишется до S3 PUT. Если процесс умер между + S3 PUT и COMMIT, остаются pending + объект; reconciler удаляет их после grace + period. Если S3 PUT не удался, pending-строка удаляется компенсацией, клиент + получает 503, а не 500. Ready-вложение никогда не удаляется автоматически: + пропавший объект — авария хранилища, её нужно разбирать, а не терять + метаданные. +- **S3 credentials**: root-пара MinIO используется только задачей + `minio-init`; API получает отдельные `s3_access_key_id`/`s3_secret_access_key` + с политикой только на `attachments/*` и `ListBucket` с `s3:prefix=attachments/*`. + Консоль MinIO не публикуется, `MINIO_BROWSER=off`, наружу открыт только + Traefik :8080. +- **Миграции**: отдельный сервис `migrate` с одной задачей и + `restart_policy: none`; `alembic upgrade head` идемпотентен. 0003 добавляет + `attachments`, `message_attachments`, индексы и ослабляет CHECK текста + сообщения (пустой текст допустим только с вложением, это проверяет API). + Readiness не пропускает трафик до head-ревизии. +- **S3/Traefik/сеть**: API, PostgreSQL, Valkey и MinIO не публикуют порты; + published port есть только у Traefik. Секреты — Docker secrets, монтируются + файлами; значения не попадают в `stack config` и логи приложения. + +### Соответствие переменных `.env.example` + +| Переменная | Где используется | Значение/примечание | +| --- | --- | --- | +| `APP_PORT` | публикация Traefik | 8080; API слушает 8080 внутри | +| `API_IMAGE` | `stack.yaml` | `mtusi-messenger-lab4:4.0.0` | +| `API_REPLICAS` | декларация в `stack.yaml` | 2 (фактическое `deploy.replicas`) | +| `SESSION_TTL_SECONDS` | `SESSION_TTL_SECONDS` API | 3600; TTL хранится в Valkey | +| `SESSION_STORE` | `Config.session_store` | только `redis`; `postgres` отвергается при старте | +| `DATABASE_URL_FILE` | secret | `/run/secrets/database_url` | +| `CACHE_URL_FILE` | secret | `/run/secrets/cache_url` | +| `S3_ENDPOINT` | boto3 endpoint | `http://minio:9000` | +| `S3_REGION` | boto3 | `us-east-1` | +| `S3_BUCKET` | bucket | `messenger-attachments` | +| `S3_KEY_PREFIX` | object key | `attachments/` | +| `S3_ACCESS_KEY_ID_FILE` / `S3_SECRET_ACCESS_KEY_FILE` | restricted API user | отдельные от root | +| `MAX_UPLOAD_BYTES` | `Config.max_upload_bytes` | 10485760; больше контракта запрещено | +| `MAX_IMAGE_PIXELS` | `Config.max_image_pixels` | 40000000; больше контракта запрещено | +| `S3_CONNECT_TIMEOUT_SECONDS` / `S3_READ_TIMEOUT_SECONDS` | boto3 | 1.5 / 30 | +| `S3_MAX_ATTEMPTS` | boto3 retries | 2 | +| `ATTACHMENT_ORPHAN_GRACE_SECONDS` | reconciler | 3600 | +| `ATTACHMENT_FAULT_MODE` | fault injection | `none` в стенде; `after_s3_put` только для проверки | + +Дополнительно поддерживаются `INSTANCE_ID`, `LOG_LEVEL`, `DB_*`, +`CACHE_TIMEOUT_SECONDS`, `GRACEFUL_SHUTDOWN_SECONDS`, +`SHUTDOWN_DRAIN_SECONDS`. Некорректное значение — отказ старта с кодом 2, а не +тихая подстановка. + +### Что перенесено из lab3 и что изменено + +Перенесены: FastAPI-приложение, модели/схемы, PostgreSQL-репозиторий, +Valkey-сессии, Alembic, argon2id, конверт ошибок, `X-Request-Id`, +`X-Instance-Id`, JSON-логи, healthchecks, Dockerfile, Swarm stack, action-скрипты +stop/restore/restart, идемпотентность сообщений, тесты и evidence lab3. +Добавлены: `attachments` и `message_attachments` (миграция 0003), S3-клиент, +потоковый upload/download, проверка PNG/JPEG и лимитов, MinIO и `minio-init`, +restricted S3 policy, reconciler, fault injection, тесты вложений, эксперименты +с памятью и отказом S3. Обязательные текстовые POST лабораторных 1–3 остаются +валидными; `attachment_ids` по умолчанию `[]`, старый smoke-сценарий проходит. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | - -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +| Контракт и OpenAPI не сломаны | `python scripts/check_contract.py`; `python scripts/validate_openapi.py` | PASS, PASS | [01-contract-and-openapi.txt](evidence/01-contract-and-openapi.txt) | +| Публичный smoke lab4 | `python tests/smoke.py --base-url http://127.0.0.1:8080` | PASS; attachment 201 ready, download побайтно, SHA-256 | [02-public-smoke.txt](evidence/02-public-smoke.txt) | +| lab3-возможности сохранены | `student-tests/run_all.py` (test_lab3) | 6/6 ok; 2 реплики, конкурентная идемпотентность | [03-student-tests.txt](evidence/03-student-tests.txt) | +| S3 в общем стенде, метаданные в PostgreSQL, байты в приватном bucket | `docker stack services lab4`; `check-bucket-private.sh`; SQL-схема | MinIO 1/1, bucket private, anonymous GET 403 | [12-infrastructure.txt](evidence/12-infrastructure.txt), [11-private-bucket.txt](evidence/11-private-bucket.txt) | +| POST вложения → 201 ready после сохранения; оригинал скачивается побайтно | `tests/smoke.py`; `test_lab4.py::test_01` | 201 `status=ready`, `variants=[]`, `error_code=null`; bytes равны | [02-public-smoke.txt](evidence/02-public-smoke.txt), [03-student-tests.txt](evidence/03-student-tests.txt) | +| Message с `attachment_ids` читается участниками | smoke; `test_lab4.py::test_04` | `attachment_ids` сохранён; посторонний 404 | [02-public-smoke.txt](evidence/02-public-smoke.txt), [03-student-tests.txt](evidence/03-student-tests.txt) | +| PNG/JPEG ≤10 MiB и ≤40 млн пикселей; MIME по содержимому; опасные filename; лимиты до чтения | `test_lab4.py::test_05` | 413 на 10 MiB+1, 48 Мп и 100 Мп (Pillow bomb warning); 415 на повреждённый/подменённый MIME; 400 на path/NUL/control | [03-student-tests.txt](evidence/03-student-tests.txt) | +| Upload → остановка обслужившей реплики → download через другую | `student-tests/attachment_failover.py` | target остановлен, download с другой реплики, байты совпали | [08-attachment-failover.json](evidence/08-attachment-failover.json) | +| Restart стенда сохраняет metadata и оригинал | `tests/resilience.py --mode persistence --action-script scripts/restart.cmd` | PASS; PostgreSQL/Valkey/MinIO/API/Traefik перезапущены, volumes те же | [06-persistence.txt](evidence/06-persistence.txt) | +| Тесты слишком большого файла, повреждения, MIME, чужого attachment_id и файла другого чата; ошибка не 500 | `test_lab4.py::test_02..05` | 413/415/400/404/409; 500 не наблюдался | [03-student-tests.txt](evidence/03-student-tests.txt) | +| Компенсация/сверка/очистка после отказа между S3 и PostgreSQL, безопасный grace | `student-tests/reconcile_probe.py` | fault PUT → 503; pending+object; dry-run 0 удалений; apply с grace 1 → 1 object/1 row; повтор 0; ready-вложение цело | [10-reconcile.json](evidence/10-reconcile.json) | +| Прерывание загрузки клиентом не создаёт вечный мусор | `student-tests/interrupted_upload.py` | до/после: metadata_rows 94/94, objects 94/94, delta 0/0; API ready | [14-interrupted-upload.json](evidence/14-interrupted-upload.json) | +| Потоковая обработка не даёт одной загрузке занять неограниченную RAM; ≥10 одновременных с измерением пика | `student-tests/upload_experiment.py --concurrency 12` | 12/12 201, 12×7.3 MiB; пик двух API 355.8 MiB при лимите 512 MiB; прирост 14.8 MiB | [04-upload-memory.json](evidence/04-upload-memory.json), [05-upload-memory-summary.txt](evidence/05-upload-memory-summary.txt) | +| Bucket bootstrap идемпотентен; отдельные S3 credentials; консоль не в общей сети; private bucket вне API | deploy повторно; `minio-init` log; два запуска скрипта; `check-bucket-private.sh`; `docker service inspect` | два `bootstrap complete`; bucket=private, anonymous 403, API user не создаёт bucket/не пишет вне префикса, console не published | [11-private-bucket.txt](evidence/11-private-bucket.txt), [12-infrastructure.txt](evidence/12-infrastructure.txt), [15-bootstrap-idempotent.txt](evidence/15-bootstrap-idempotent.txt) | +| S3 недоступен: readiness/upload/download не 200, после возврата MinIO всё работает | `student-tests/s3_outage_probe.py` (scale minio 0/1) | during 503 на readiness/upload/download; after ready=true, upload ready, download совпал | [09-s3-outage.json](evidence/09-s3-outage.json) | +| Lab3: health/readiness/timeouts/SIGTERM согласованы; LB исключает backend | `docker service inspect`; readiness; S3 outage | live не зависит от БД; ready проверяет БД+схему+Valkey+S3; Traefik 2 s/1 s/1 s | [12-infrastructure.txt](evidence/12-infrastructure.txt), [09-s3-outage.json](evidence/09-s3-outage.json) | +| Lab3: остановка одной реплики, RPS/ошибки/восстановление | `tests/resilience.py --mode failover --action-script scripts/stop-one.cmd` | 123 успешных / 4 переходных отказа за 15 s; recovery 3.156 s; restore 2/2 | [07-failover.txt](evidence/07-failover.txt) | +| Lab3: CPU/RAM-лимиты, API не публикует порты, нет container_name | `docker service inspect`; `docker stack services` | limits/reservations; API/MinIO/DB ports=null; только Traefik :8080 | [12-infrastructure.txt](evidence/12-infrastructure.txt) | +| Миграции однократны и совместимы | `migrate` service log; `alembic current/check` | head=0003_attachments; `No new upgrade operations detected` | [12-infrastructure.txt](evidence/12-infrastructure.txt) | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +### 12 одновременных загрузок и память -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | +Гипотеза: потоковый приём не буферизует все тела в RAM; пик RSS API не растёт +пропорционально сумме размеров файлов. Fixture — настоящий PNG 1800×1350, +7 301 750 байт; 12 параллельных POST в один чат; две реплики; `docker stats` +каждые 0.2 s. + +| Показатель | Значение | +| --- | ---: | +| Успешных загрузок | 12 / 12 | +| Суммарный объём тел | 87 621 000 байт (~83.6 MiB) | +| Пик памяти двух API | 373 083 340 байт (~355.8 MiB) | +| Baseline двух API | 357 564 415 байт (~341.0 MiB) | +| Прирост пика | 15 518 925 байт (~14.8 MiB) | +| Время | 1.953 s; p50 1.727 s, p95 1.781 s | + +Прирост ~15 MiB на 83.6 MiB тел показывает отсутствие пропорциональной +буферизации; API читает чанками 64 KiB, пишет во временный файл и стримит в S3. +Метод — working set контейнера, не cgroup peak; 5 Hz может пропустить короткий +всплеск. Сырые сэмплы — [04-upload-memory.json](evidence/04-upload-memory.json). + +### Отказ API-реплики и вложения + +| Воздействие | Что ожидали | Что наблюдали | Восстановление / потери | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| Остановлена одна API-реплика (target по `X-Instance-Id`) | вторая продолжает read/write, подтверждённые сообщения целы | 123 успешных POST за 15 s, 4 переходных отказа; target task остановлен, новая task с новым hostname | первая успешная запись через 3.156 s; дублей нет | +| Upload в реплику A, затем stop A, download через LB | файл доступен и совпадает побайтно | download обслужила другая реплика, SHA-256/bytes совпали | сервис восстановлен до 2/2 | + +Публичный тест проверяет отсутствие дублей и сохранность confirmed-сообщений; +отдельный `attachment_failover.py` гарантирует, что остановлена именно +обслужившая upload реплика. Это отказ **процесса/задачи**, а не узла. + +### Недоступность MinIO + +`docker service scale lab4_minio=0`, затем запросы через LB: readiness, upload +и download вернули **503**; после `scale=1` readiness восстановился, новый +upload стал `ready`, download совпал с оригиналом. На время отказа Traefik +исключает API из ротации, поэтому ответ — `no available server` (без +`X-Request-Id`); это отказ LB/зависимости, а не 500 приложения. +Это проверка зависимости, а не отказ узла: PostgreSQL, Valkey и Traefik не +трогались. + +### Согласованность S3/PostgreSQL и reconciler + +Одноразовый API-контейнер с `ATTACHMENT_FAULT_MODE=after_s3_put` принял файл, +выполнил S3 PUT и был остановлен до COMMIT статуса `ready`: клиент получил +**503**, в БД осталась `pending`-строка, в S3 — объект. + +`python -m messenger.reconcile`: + +1. `--dry-run --grace-seconds 3600`: `would_delete_objects=0`, + `would_delete_rows=0`, в плане `keep_fresh` — свежий мусор не удаляется. +2. `--apply --grace-seconds 1` после паузы: удалены **1 объект и 1 pending-строка**. +3. Повторный `--apply`: **0/0** — операция идемпотентна. +4. Заранее загруженное ready-вложение после всех действий скачивается + побайтно (`used_download_matches=true`). + +Механизм: object key — только серверный UUID; pending-строка фиксирует +намерение; ready-строка и объект сверяются; orphan-объекты и stale pending +удаляются только после `ATTACHMENT_ORPHAN_GRACE_SECONDS`; ready-строки с +пропавшим объектом только репортируются (не удаляются), чтобы не терять +пользовательские метаданные. Запуск: `scripts/reconcile.sh --dry-run` или +`docker exec python -m messenger.reconcile --apply --grace-seconds N`. + +### Прерывание загрузки клиентом + +Отдельный raw-socket probe отправил заголовки с `Content-Length: 5 000 000`, +только 1 KiB PNG и закрыл соединение. До и после обрыва dry-run reconciler +показал одинаковые `metadata_rows=94` и `objects=94` (`delta=0/0`), API +остался `ready`: строка pending и объект S3 не появились. Клиент получает +обрыв/502 от LB, но не создаёт учтённого вложения; временный файл удаляется в +`finally`. + +### Нагрузочная база + +`tests/load.py` — closed-loop, 4 потока, 30 s: 5929 успешных, 0 ошибок, +197.324 RPS, p50/p95/p99 = 16/47/78 ms. Генератор ограничен клиентом и страдает +coordinated omission; это throughput HTTP-подтверждений, не точный счётчик +COMMIT. Сырой JSON — [load.json](evidence/load.json), сводка — +[13-load-baseline.txt](evidence/13-load-baseline.txt). + +### Persistence + +`tests/resilience.py --mode persistence` перезапустил API, PostgreSQL, Valkey, +MinIO и Traefik без удаления volumes; тот же bearer-токен, то же сообщение и +тот же файл доступны после рестарта. В [06-persistence.txt](evidence/06-persistence.txt) +видны новые task-и и те же три named volumes до/после. ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- **Один Docker host**. Swarm из одного manager/worker не переживает потерю + узла; PostgreSQL, Valkey, MinIO и Traefik — единственные экземпляры и + остаются SPOF. Это не трек 5 и не заявление об HA. +- **S3 outage** проверен остановкой сервиса MinIO, а не потерей узла/диска. + Traefik отвечает 503 без конверта API; прямой замер внутреннего 503 API + через service VIP не выделен в отдельный артефакт. +- **Temp staging**. Тело загрузки временно живёт в `/tmp` контейнера API + (≤10 MiB) и удаляется после запроса; это не место хранения оригинала. + При падении процесса файл исчезает вместе с контейнером; при падении между + S3 PUT и COMMIT остаётся pending-строка + объект, которые убирает reconciler. +- **Ready-объект пропал из S3**: reconciler сообщает `missing_ready`, но не + удаляет metadata; API отдаёт 404 на content. Автоматическое восстановление + объекта не реализовано — это следующий шаг. +- **minio-init config неизменяем**: Swarm не позволяет обновлять config; + `scripts/deploy.sh` и `hooks.ps1` перед повторным deploy удаляют + завершившийся `minio-init` и его config, затем создают заново. На первом + deploy это no-op. +- **Rotation S3 credentials**: bootstrap сохраняет существующего API-пользователя; + смена секрета требует отдельной ротации (remove/add user) — в отчёте не + автоматизирована. +- **Lab5 не реализована**: нет queued/processing/failed, thumbnail/crop/WebP, + worker и брокера; `variants` всегда `[]`, ответ lab4 — 201 ready. +- **Presigned upload (трек 5) не заявляется**: обязательный proxy endpoint + сохранён, прямых подписанных URL нет. +- **Таймауты**: S3 (connect/read), PostgreSQL (connect/command/statement) и + graceful shutdown ограничены; отдельного HTTP-таймаута на всё тело загрузки + нет. RAM всё равно ограничен `MAX_UPLOAD_BYTES` и потоковым чтением, но + медленный клиент может дольше держать соединение — это осознанное упрощение. +- **Измерения**: closed-loop load и 5 Hz `docker stats`; абсолютные RPS/RAM не + переносимы на другую машину. Docker Desktop виртуализирован. +- **Секреты**: `secrets/` и `.env` не входят в Git; при публикации PR их + нужно создать заново. В отчёте и evidence токенов/значений credentials нет. +- **Windows-обвязка**: `.cmd`-двойники и `PYTHONUTF8=1` нужны из-за + `Popen([script])` и кодировки; на Linux достаточно `make` и `.sh`. + +## Ответы на вопросы защиты + +- **Почему файл в Docker volume одной API-реплики не равен объектному + хранилищу?** Volume привязан к узлу/контейнеру, не даёт общего доступа второй + реплике, не имеет S3-политики, версионирования и durability. S3 — отдельный + сервис с общим bucket; API-реплики читают один объект, а метаданные — из + PostgreSQL. +- **Когда можно честно вернуть 201?** Только после того, как тело полностью + принято и проверено, S3 PUT подтверждён (ETag/размер), а metadata-строка + переведена в `ready` и закоммичена. 202/201 без S3 или до COMMIT был бы + ложным подтверждением. +- **Что будет, если S3 PUT прошёл, а COMMIT в PostgreSQL — нет?** Клиент + получит 503, в БД останется pending, в S3 — объект. Это не «вечный» мусор: + reconciler после grace period удалит объект и pending-строку; повторный + upload создаст новый attachment (upload не идемпотентен по контракту). +- **Почему случайный object key и приватный bucket не заменяют ACL + приложения?** Приватность bucket защищает только от анонимного доступа; + любой, у кого есть S3 credentials, читает объект. Право на конкретное + вложение определяется членством в чате в API; ключ — не capability и не + авторизация. Поэтому API сам проверяет участника и не отдаёт redirect. + +## Приложение: структура изменений + +``` +src/messenger/routers/attachments.py -> upload/download/metadata +src/messenger/storage.py -> boto3 S3 adapter, StorageUnavailable/Missing +src/messenger/images.py -> PNG/JPEG sniff, Pillow verify, pixel limit +src/messenger/upload.py -> streaming to temp file, SHA-256/MD5, limits +src/messenger/reconcile.py -> orphan/pending/missing reconciler +migrations/versions/0003_attachments.py +scripts/minio-init.sh -> idempotent bucket/private/user/policy +scripts/check-bucket-private.sh +scripts/collect_infrastructure.py +student-tests/test_lab4.py, attachment_failover.py, upload_experiment.py, +student-tests/s3_outage_probe.py, reconcile_probe.py, interrupted_upload.py +stack.yaml, Dockerfile, requirements.txt, .env.example +``` diff --git a/alembic.ini b/alembic.ini new file mode 100644 index 00000000..e299f789 --- /dev/null +++ b/alembic.ini @@ -0,0 +1,38 @@ +# Конфигурация Alembic. URL базы здесь намеренно не задан: он приходит из +# окружения (DATABASE_URL или DATABASE_URL_FILE) и подставляется migrations/env.py. +[alembic] +script_location = migrations +prepend_sys_path = src + +[loggers] +keys = root,sqlalchemy,alembic + +[handlers] +keys = console + +[formatters] +keys = plain + +[logger_root] +level = WARNING +handlers = console +qualname = + +[logger_sqlalchemy] +level = WARNING +handlers = +qualname = sqlalchemy.engine + +[logger_alembic] +level = INFO +handlers = +qualname = alembic + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = plain + +[formatter_plain] +format = %(levelname)s [%(name)s] %(message)s diff --git a/evidence/01-contract-and-openapi.txt b/evidence/01-contract-and-openapi.txt new file mode 100644 index 00000000..191f913f --- /dev/null +++ b/evidence/01-contract-and-openapi.txt @@ -0,0 +1,11 @@ +# Контракт и OpenAPI (offline) + +date=2026-11-06 +python scripts/check_contract.py (PYTHONUTF8=1) +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. +CHECK_EXIT=0 + +## Full OpenAPI/JSON Schema validation +command: docker run --rm -v :/repo -w /repo python:3.11.9-slim-bookworm sh -c 'pip install -q -r requirements-dev.txt && python scripts/validate_openapi.py' +PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested. +VALIDATE_EXIT=0 diff --git a/evidence/02-public-smoke.txt b/evidence/02-public-smoke.txt new file mode 100644 index 00000000..2ad62b87 --- /dev/null +++ b/evidence/02-public-smoke.txt @@ -0,0 +1,2 @@ +PASS: lab4 public API scenario; infrastructure and grading evidence remain separate. +SMOKE_EXIT=0 diff --git a/evidence/03-student-tests.txt b/evidence/03-student-tests.txt new file mode 100644 index 00000000..1986b64e --- /dev/null +++ b/evidence/03-student-tests.txt @@ -0,0 +1,21 @@ +BASE_URL = http://127.0.0.1:8080 +test_01_at_least_two_instances_and_stable_header (test_lab3.Lab3Tests.test_01_at_least_two_instances_and_stable_header) +LB действительно распределяет один и тот же токен между разными процессами. ... ok +test_02_concurrent_same_key_through_lb_creates_one_message (test_lab3.Lab3Tests.test_02_concurrent_same_key_through_lb_creates_one_message) +Один ключ + одно тело одновременно через разные реплики = одно сообщение. ... ok +test_03_same_key_other_body_conflicts (test_lab3.Lab3Tests.test_03_same_key_other_body_conflicts) ... ok +test_04_key_scope_user_and_chat (test_lab3.Lab3Tests.test_04_key_scope_user_and_chat) ... ok +test_05_key_validation (test_lab3.Lab3Tests.test_05_key_validation) ... ok +test_06_uncertain_retry_is_safe (test_lab3.Lab3Tests.test_06_uncertain_retry_is_safe) +Повтор с тем же ключом после потери ответа не создаёт второй объект. ... ok +test_01_png_jpeg_and_metadata (test_lab4.Lab4AttachmentTests.test_01_png_jpeg_and_metadata) ... ok +test_02_stranger_and_nonmember (test_lab4.Lab4AttachmentTests.test_02_stranger_and_nonmember) ... ok +test_03_attachment_from_another_chat_is_404 (test_lab4.Lab4AttachmentTests.test_03_attachment_from_another_chat_is_404) ... ok +test_04_message_attachment_validation_and_idempotency (test_lab4.Lab4AttachmentTests.test_04_message_attachment_validation_and_idempotency) ... ok +test_05_rejects_bad_images_and_filenames (test_lab4.Lab4AttachmentTests.test_05_rejects_bad_images_and_filenames) ... ok + +---------------------------------------------------------------------- +Ran 11 tests in 2.309s + +OK +STUDENT_EXIT=0 diff --git a/evidence/04-upload-memory.json b/evidence/04-upload-memory.json new file mode 100644 index 00000000..64527b39 --- /dev/null +++ b/evidence/04-upload-memory.json @@ -0,0 +1,116 @@ +{ + "after_rss_bytes": { + "3981ea44b835f8d07e1daab6c615ca56c66295a6259b7fad28033c441b59d866": 180669644, + "627ad63b26d105fa90b6bdb5144c30db565eb3f5cd54883b57a2e734813ea8a0": 182347366 + }, + "base_url": "http://127.0.0.1:8080", + "baseline_rss_bytes": { + "3981ea44b835f8d07e1daab6c615ca56c66295a6259b7fad28033c441b59d866": 180459929, + "627ad63b26d105fa90b6bdb5144c30db565eb3f5cd54883b57a2e734813ea8a0": 177104486 + }, + "concurrency": 12, + "containers": [ + "3981ea44b835f8d07e1daab6c615ca56c66295a6259b7fad28033c441b59d866", + "627ad63b26d105fa90b6bdb5144c30db565eb3f5cd54883b57a2e734813ea8a0" + ], + "elapsed_seconds": 1.953, + "failed": 0, + "image_bytes": 7301750, + "image_dimensions": [ + 1800, + 1350 + ], + "instances": [ + "3981ea44b835", + "627ad63b26d1" + ], + "measured_at": "2026-11-06T14:23:48.900389Z", + "p50_seconds": 1.727, + "p95_seconds": 1.781, + "peak_delta_bytes": 15518925, + "peak_rss_bytes": { + "3981ea44b835f8d07e1daab6c615ca56c66295a6259b7fad28033c441b59d866": 190735974, + "627ad63b26d105fa90b6bdb5144c30db565eb3f5cd54883b57a2e734813ea8a0": 182347366 + }, + "results": [ + { + "instance": "627ad63b26d1", + "seconds": 1.437, + "status": 201 + }, + { + "instance": "627ad63b26d1", + "seconds": 1.562, + "status": 201 + }, + { + "instance": "627ad63b26d1", + "seconds": 1.656, + "status": 201 + }, + { + "instance": "627ad63b26d1", + "seconds": 1.687, + "status": 201 + }, + { + "instance": "3981ea44b835", + "seconds": 1.703, + "status": 201 + }, + { + "instance": "627ad63b26d1", + "seconds": 1.703, + "status": 201 + }, + { + "instance": "3981ea44b835", + "seconds": 1.75, + "status": 201 + }, + { + "instance": "3981ea44b835", + "seconds": 1.75, + "status": 201 + }, + { + "instance": "3981ea44b835", + "seconds": 1.75, + "status": 201 + }, + { + "instance": "3981ea44b835", + "seconds": 1.781, + "status": 201 + }, + { + "instance": "627ad63b26d1", + "seconds": 1.781, + "status": 201 + }, + { + "instance": "3981ea44b835", + "seconds": 1.844, + "status": 201 + } + ], + "samples": [ + { + "memory": { + "3981ea44b835f8d07e1daab6c615ca56c66295a6259b7fad28033c441b59d866": 190735974, + "627ad63b26d105fa90b6bdb5144c30db565eb3f5cd54883b57a2e734813ea8a0": 181613363 + }, + "t": 3265086.125 + }, + { + "memory": { + "3981ea44b835f8d07e1daab6c615ca56c66295a6259b7fad28033c441b59d866": 180669644, + "627ad63b26d105fa90b6bdb5144c30db565eb3f5cd54883b57a2e734813ea8a0": 182347366 + }, + "t": 3265088.328 + } + ], + "successful": 12, + "sum_baseline_rss_bytes": 357564415, + "sum_peak_rss_bytes": 373083340 +} \ No newline at end of file diff --git a/evidence/05-upload-memory-summary.txt b/evidence/05-upload-memory-summary.txt new file mode 100644 index 00000000..fda7f005 --- /dev/null +++ b/evidence/05-upload-memory-summary.txt @@ -0,0 +1,28 @@ +# Пик памяти API при 12 одновременных загрузках + +Дата: 2026-11-06 (Europe/Moscow) +Стенд: Docker Desktop Linux VM, 6 CPU / 4 GiB (docker info: cpus=6, mem=4103159808), +API-контейнеры по 1.0 CPU / 512 MiB, две реплики. +Fixture: валидный PNG 1800x1350, 7 301 750 байт (6.96 MiB), сгенерирован +скриптом `student-tests/upload_experiment.py`; 12 одновременных POST на один чат. + +Методика: `docker stats --no-stream` для контейнеров `lab4_api.*` до старта и +каждые 0.2 s во время загрузки; пик — максимум по сэмплам. Это рабочий набор +(working set) контейнера, а не RSS процесса и не точный cgroup peak; частота +сэмплирования 5 Hz может пропустить очень короткий всплеск. + +| Показатель | Значение | +| --- | ---: | +| Успешных загрузок | 12 / 12 | +| Суммарный объём тел запросов | 87 621 000 байт (~83.6 MiB) | +| Память API до старта, сумма двух реплик | 357 564 415 байт (~341 MiB) | +| Пик памяти API, сумма двух реплик | 373 083 340 байт (~355.8 MiB) | +| Прирост пика | 15 518 925 байт (~14.8 MiB) | +| Время сценария | 1.953 s | +| p50 / p95 успешной загрузки | 1.727 s / 1.781 s | + +Прирост памяти (~15 MiB) не пропорционален 83.6 MiB переданных тел и не равен +ни одному отдельному 7 MiB файлу на каждую из 12 загрузок: API читает тело +чанками 64 KiB, пишет во временный файл и отдаёт файл в S3, не собирая +`request.body()` целиком. Абсолютные значения не переносимы на другой хост; +сравнивать нужно одинаковые профили. Сырые сэмплы — `evidence/upload-memory.json`. diff --git a/evidence/06-persistence.txt b/evidence/06-persistence.txt new file mode 100644 index 00000000..df87daca --- /dev/null +++ b/evidence/06-persistence.txt @@ -0,0 +1,61 @@ +# Persistence: restart API + PostgreSQL + Valkey + MinIO + Traefik, keep volumes +date=2026-11-06T17:35:41.5221757+03:00 +BEFORE service tasks: +lab4_api.1 Running 40 seconds ago +lab4_api.1 Shutdown 34 seconds ago +lab4_api.1 Shutdown 3 minutes ago +lab4_api.1 Complete 9 minutes ago +lab4_api.1 Shutdown 10 minutes ago +lab4_api.2 Running 48 seconds ago +lab4_api.2 Shutdown 42 seconds ago +lab4_api.2 Shutdown 4 minutes ago +lab4_api.2 Complete 8 minutes ago +lab4_api.2 Shutdown 10 minutes ago +lab4_minio.1 Running about a minute ago +lab4_minio.1 Shutdown about a minute ago +lab4_minio.1 Shutdown 10 minutes ago +lab4_postgres.1 Running about a minute ago +lab4_postgres.1 Shutdown about a minute ago +lab4_postgres.1 Shutdown 11 minutes ago +lab4_valkey.1 Running about a minute ago +lab4_valkey.1 Shutdown about a minute ago +lab4_valkey.1 Shutdown 10 minutes ago +BEFORE volumes: +lab4_miniodata +lab4_pgdata +lab4_valkeydata +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. +PERSIST_EXIT=0 +AFTER service tasks: +lab4_api.1 Running 19 seconds ago +lab4_api.1 Shutdown 14 seconds ago +lab4_api.1 Shutdown about a minute ago +lab4_api.1 Shutdown 5 minutes ago +lab4_api.1 Complete 11 minutes ago +lab4_api.2 Running 28 seconds ago +lab4_api.2 Shutdown 22 seconds ago +lab4_api.2 Shutdown 2 minutes ago +lab4_api.2 Shutdown 5 minutes ago +lab4_api.2 Complete 9 minutes ago +lab4_minio.1 Running 40 seconds ago +lab4_minio.1 Shutdown 46 seconds ago +lab4_minio.1 Shutdown 2 minutes ago +lab4_minio.1 Shutdown 12 minutes ago +lab4_postgres.1 Running about a minute ago +lab4_postgres.1 Shutdown about a minute ago +lab4_postgres.1 Shutdown 2 minutes ago +lab4_postgres.1 Shutdown 12 minutes ago +lab4_valkey.1 Running 54 seconds ago +lab4_valkey.1 Shutdown about a minute ago +lab4_valkey.1 Shutdown 2 minutes ago +lab4_valkey.1 Shutdown 12 minutes ago +AFTER volumes: +lab4_miniodata +lab4_pgdata +lab4_valkeydata +TRAEFIK tasks after restart: +lab4_traefik.1 Running 12 minutes ago +lab4_traefik.1 Shutdown 12 minutes ago +lab4_traefik.1 Shutdown 13 minutes ago +lab4_traefik.1 Shutdown 23 minutes ago diff --git a/evidence/07-failover.txt b/evidence/07-failover.txt new file mode 100644 index 00000000..ded4720f --- /dev/null +++ b/evidence/07-failover.txt @@ -0,0 +1,26 @@ +# Failover: stop one API replica by X-Instance-Id +date=2026-11-06T17:37:28.9403010+03:00 +BEFORE replicas: +lab4_api 2/2 +BEFORE tasks: +lab4_api.1 Running 48 seconds ago +lab4_api.1 Shutdown 42 seconds ago +lab4_api.1 Shutdown 2 minutes ago +lab4_api.1 Shutdown 5 minutes ago +lab4_api.1 Complete 11 minutes ago +Executing explicit failover hook; hook output suppressed to avoid leaking secrets. +{"observed_instances_before": 2, "successful_writes": 123, "failed_attempts": 4, "first_recovery_seconds": 3.156} +PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. +FAILOVER_EXIT=0 +AFTER replicas: +lab4_api 2/2 +AFTER tasks: +lab4_api.1 Running about a minute ago +lab4_api.1 Shutdown 59 seconds ago +lab4_api.1 Shutdown 2 minutes ago +lab4_api.1 Shutdown 6 minutes ago +lab4_api.1 Complete 11 minutes ago +lab4_api.2 Running 5 seconds ago +RESTORE: +api restored: 2 running tasks and readiness OK +RESTORE_EXIT=0 diff --git a/evidence/08-attachment-failover.json b/evidence/08-attachment-failover.json new file mode 100644 index 00000000..4b5d40d5 --- /dev/null +++ b/evidence/08-attachment-failover.json @@ -0,0 +1,13 @@ +{ + "attachment_id": "7534c914-4f2f-47d5-ba53-b237eba3e6f8", + "download_matches": true, + "download_served_by": "3552129b8003", + "downloaded_from_other_replica": true, + "metadata": "ready", + "observed_instances": [ + "5d23c2c33720" + ], + "restore_exit": 0, + "stop_exit": 0, + "target_instance": "5d23c2c33720" +} \ No newline at end of file diff --git a/evidence/09-s3-outage.json b/evidence/09-s3-outage.json new file mode 100644 index 00000000..255185e0 --- /dev/null +++ b/evidence/09-s3-outage.json @@ -0,0 +1,34 @@ +{ + "after": { + "download_matches": true, + "new_upload_ready": "ready", + "ready": true + }, + "before": { + "download_matches": true, + "ready": true + }, + "during": { + "ready": { + "body": "no available server\n", + "seconds": 0.0, + "status": 503, + "x_request_id": null + }, + "trend_download": { + "body": "no available server\n", + "seconds": 0.016, + "status": 503, + "x_request_id": null + }, + "upload": { + "body": "no available server\n", + "seconds": 0.0, + "status": 503, + "x_request_id": null + } + }, + "measured_at": "2026-11-06T14:23:55.081889Z", + "scale_down_seconds": 0, + "stack": "lab4" +} \ No newline at end of file diff --git a/evidence/10-reconcile.json b/evidence/10-reconcile.json new file mode 100644 index 00000000..0ff5ac55 --- /dev/null +++ b/evidence/10-reconcile.json @@ -0,0 +1,23 @@ +{ + "apply": { + "deleted_objects": 1, + "deleted_rows": 1, + "missing_ready": 0 + }, + "apply_again": { + "deleted_objects": 0, + "deleted_rows": 0 + }, + "dry_run_fresh": { + "fresh_kept": true, + "would_delete_objects": 0, + "would_delete_rows": 0 + }, + "fault_upload": { + "error": "unavailable", + "instance": "01075da3ebbf", + "status": 503 + }, + "used_attachment": "046bbbbb-ca4f-4fc5-a249-147d047465cf", + "used_download_matches": true +} \ No newline at end of file diff --git a/evidence/11-private-bucket.txt b/evidence/11-private-bucket.txt new file mode 100644 index 00000000..e8d70afe --- /dev/null +++ b/evidence/11-private-bucket.txt @@ -0,0 +1,8 @@ +# Private bucket and restricted API credentials +date=2026-11-06T17:38:12.6024014+03:00 +anonymous-policy: Access permission for `root/messenger-attachments` is `private` +anonymous-http-get: 403 +api-list-attachments: [2026-11-06 14:22:51 UTC] 109KiB STANDARD 026d5f1e-27dd-4e23-a82a-0fab8729d76c +api-create-bucket: denied (expected) +api-put-other-bucket: denied (expected) +root-bucket-list: ok diff --git a/evidence/12-infrastructure.txt b/evidence/12-infrastructure.txt new file mode 100644 index 00000000..584e4ed5 --- /dev/null +++ b/evidence/12-infrastructure.txt @@ -0,0 +1,102 @@ +# Infrastructure and image pinning +host=DESKTOP-JUMCS0L platform=Windows-10-10.0.19045-SP0 +python=3.12.14 + +## docker version +exit=0 +client=28.0.1 server=28.0.1 + +## docker info +exit=0 +swarm=active cpus=6 mem=4103159808 + +## stack services +exit=0 +ID NAME MODE REPLICAS IMAGE PORTS +2rw2zma3fzeo lab4_api replicated 2/2 mtusi-messenger-lab4:4.0.0 +wm6bq4dalohy lab4_migrate replicated 0/1 mtusi-messenger-lab4:4.0.0 +vafxw59jmbnk lab4_minio replicated 1/1 minio/minio@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e +7n44exmy7fzs lab4_minio-init replicated 0/1 minio/minio@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e +8u1pk1obef5v lab4_postgres replicated 1/1 postgres:16.15-bookworm +pyq7ug1uuxjz lab4_traefik replicated 1/1 traefik:v3.5.4 *:8080->8080/tcp +korr5zc57nx2 lab4_valkey replicated 1/1 valkey/valkey:8.0.11-trixie + +## api service +exit=0 +image=mtusi-messenger-lab4:4.0.0 ports=null limits={"NanoCPUs":1000000000,"MemoryBytes":536870912} reservations={"NanoCPUs":250000000,"MemoryBytes":134217728} update={"Parallelism":1,"Delay":2000000000,"FailureAction":"rollback","Monitor":10000000000,"MaxFailureRatio":0,"Order":"start-first"} + +## minio service +exit=0 +image=minio/minio@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e ports=null limits={"NanoCPUs":1000000000,"MemoryBytes":536870912} mounts=[{"Type":"volume","Source":"lab4_miniodata","Target":"/data","VolumeOptions":{"Labels":{"com.docker.stack.namespace":"lab4"}}}] + +## traefik ports +exit=0 +ports=[{"Protocol":"tcp","TargetPort":8080,"PublishedPort":8080,"PublishMode":"ingress"}] + +## volumes +exit=0 +lab4_miniodata local +lab4_pgdata local +lab4_valkeydata local + +## secrets (names only) +exit=0 +lab4_cache_url +lab4_cursor_secret +lab4_database_url +lab4_postgres_password +lab4_s3_access_key_id +lab4_s3_root_password +lab4_s3_root_user +lab4_s3_secret_access_key + +## configs (names only) +exit=0 +lab4_lab4_minio_init + +## api secret mounts +exit=0 +[{"File":{"Name":"cache_url","UID":"0","GID":"0","Mode":292},"SecretID":"px32lqtry46f3oayd798gnymy","SecretName":"lab4_cache_url"},{"File":{"Name":"cursor_secret","UID":"0","GID":"0","Mode":292},"SecretID":"dxcjo5z5gnokfpw44x9xj1icx","SecretName":"lab4_cursor_secret"},{"File":{"Name":"database_url","UID":"0","GID":"0","Mode":292},"SecretID":"kuszlkdxg87lta7umqr6j80in","SecretName":"lab4_database_url"},{"File":{"Name":"s3_access_key_id","UID":"0","GID":"0","Mode":292},"SecretID":"j8njjgip6pjg3yd6eilb863ge","SecretName":"lab4_s3_access_key_id"},{"File":{"Name":"s3_secret_access_key","UID":"0","GID":"0","Mode":292},"SecretID":"1eyu3tb77yjteli0l4qnckhz6","SecretName":"lab4_s3_secret_access_key"}] + +## minio-init secret mounts +exit=0 +[{"File":{"Name":"s3_access_key_id","UID":"0","GID":"0","Mode":292},"SecretID":"j8njjgip6pjg3yd6eilb863ge","SecretName":"lab4_s3_access_key_id"},{"File":{"Name":"s3_root_password","UID":"0","GID":"0","Mode":292},"SecretID":"atjtp6acmgoqxq936acbilq5k","SecretName":"lab4_s3_root_password"},{"File":{"Name":"s3_root_user","UID":"0","GID":"0","Mode":292},"SecretID":"tx0ihalboezf8jufpef20k6iw","SecretName":"lab4_s3_root_user"},{"File":{"Name":"s3_secret_access_key","UID":"0","GID":"0","Mode":292},"SecretID":"1eyu3tb77yjteli0l4qnckhz6","SecretName":"lab4_s3_secret_access_key"}] + +## migrate log +exit=0 +$ stderr +lab4_migrate.1.qdrdp19e5m1p@docker-desktop | INFO [alembic.runtime.migration] Context impl PostgresqlImpl. +lab4_migrate.1.qdrdp19e5m1p@docker-desktop | INFO [alembic.runtime.migration] Will assume transactional DDL. +lab4_migrate.1.qdrdp19e5m1p@docker-desktop | INFO [alembic.runtime.migration] Running upgrade -> 0001_initial_schema, Начальная схема: пользователи, чаты, участники и сообщения +lab4_migrate.1.qdrdp19e5m1p@docker-desktop | INFO [alembic.runtime.migration] Running upgrade 0001_initial_schema -> 0002_message_idempotency, Общая идемпотентность отправки сообщения +lab4_migrate.1.qdrdp19e5m1p@docker-desktop | INFO [alembic.runtime.migration] Running upgrade 0002_message_idempotency -> 0003_attachments, Вложения и связь сообщений с вложениями + +## minio-init log +exit=0 +lab4_minio-init.1.n8n1xlh347nt@docker-desktop | minio bootstrap complete: bucket=messenger-attachments private=yes policy=messenger-attachments-rw + +## other service ports (must be null) +exit=0 lab4_postgres ports=null +exit=0 lab4_valkey ports=null +exit=0 lab4_minio-init ports=null +exit=0 lab4_migrate ports=null + +## image digests +exit=0 [mtusi-messenger-lab4:4.0.0] id=sha256:56a1ca2c55b4decb132423f681df11a513ffa2c13b010ea7a8ba1681ba8329b3 digests=["mtusi-messenger-lab4@sha256:56a1ca2c55b4decb132423f681df11a513ffa2c13b010ea7a8ba1681ba8329b3"] +exit=0 [minio/minio:latest] id=sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e digests=["minio/minio@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e"] +exit=0 [postgres@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4] id=sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 digests=["postgres@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4"] +exit=0 [valkey/valkey@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab] id=sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab digests=["valkey/valkey@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab"] +exit=0 [traefik:v3.5.4] id=sha256:4df0a50fcf71b454c0d7ad17675776dc8d37359deae3291895bdaa008c1b9972 digests=["traefik@sha256:4df0a50fcf71b454c0d7ad17675776dc8d37359deae3291895bdaa008c1b9972"] +exit=0 [python:3.11.9-slim-bookworm] id=sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317 digests=["python@sha256:8fb099199b9f2d70342674bd9dbccd3ed03a258f26bbd1d556822c6dfc60c317"] + +## alembic current / check +-- current exit=0 +0003_attachments (head) +$ stderr +INFO [alembic.runtime.migration] Context impl PostgresqlImpl. +INFO [alembic.runtime.migration] Will assume transactional DDL. +-- check exit=0 +No new upgrade operations detected. +$ stderr +INFO [alembic.runtime.migration] Context impl PostgresqlImpl. +INFO [alembic.runtime.migration] Will assume transactional DDL. diff --git a/evidence/13-load-baseline.txt b/evidence/13-load-baseline.txt new file mode 100644 index 00000000..3ede711d --- /dev/null +++ b/evidence/13-load-baseline.txt @@ -0,0 +1,23 @@ +# Load baseline (public closed-loop generator) + +date=2026-11-06 (Europe/Moscow) +command: python3 tests/load.py --base-url http://127.0.0.1:8080 --duration 30 --concurrency 4 --output evidence/load.json + +{ + "lab": 4, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 30.0, + "elapsed_seconds": 30.047, + "concurrency": 4, + "successful_requests": 5929, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 197.324, + "successful_latency_ms": {"p50": 16.0, "p95": 47.0, "p99": 78.0}, + "note": "Latency percentiles cover successes only; closed-loop has coordinated omission and client overhead." +} + +Стенд и ограничения: Docker Desktop VM 6 CPU / 4 GiB; API 2 x (1 CPU / 512 MiB), +PostgreSQL 2 CPU / 512 MiB, MinIO 1 CPU / 512 MiB, Valkey 1 CPU / 256 MiB, +Traefik 0.5 CPU / 128 MiB. Генератор и API на одном хосте; это throughput +HTTP-подтверждений, не точный счётчик COMMIT. diff --git a/evidence/14-interrupted-upload.json b/evidence/14-interrupted-upload.json new file mode 100644 index 00000000..f1eb098f --- /dev/null +++ b/evidence/14-interrupted-upload.json @@ -0,0 +1,17 @@ +{ + "aborted_request": { + "response_prefix": "HTTP/1.1 502 Bad Gateway\r\nDate: Fri, 06 Nov 2026 14:56:11 GMT\r\nContent-Length: 1", + "sent_bytes": 1024 + }, + "after": { + "metadata_rows": 94, + "objects": 94 + }, + "before": { + "metadata_rows": 94, + "objects": 94 + }, + "delta_objects": 0, + "delta_rows": 0, + "ready": true +} \ No newline at end of file diff --git a/evidence/15-bootstrap-idempotent.txt b/evidence/15-bootstrap-idempotent.txt new file mode 100644 index 00000000..c3e56dc0 --- /dev/null +++ b/evidence/15-bootstrap-idempotent.txt @@ -0,0 +1,6 @@ +# Idempotent MinIO bootstrap: two consecutive runs +date=2026-11-06T17:57:06.8786631+03:00 +RUN 1 +minio bootstrap complete: bucket=messenger-attachments private=yes policy=messenger-attachments-rw +RUN 2 +minio bootstrap complete: bucket=messenger-attachments private=yes policy=messenger-attachments-rw diff --git a/evidence/README.md b/evidence/README.md index 8df70015..0b7bb12d 100644 --- a/evidence/README.md +++ b/evidence/README.md @@ -1,5 +1,28 @@ -# Доказательства +# Доказательства — лабораторная 4 -Храните небольшие обезличенные результаты: команды и stdout проверок, JSON/CSV агрегатов нагрузки, EXPLAIN, dashboard JSON, текст разбора отказа. Укажите дату, commit, аппаратные лимиты и профиль нагрузки. +Все результаты получены на локальном синтетическом стенде 2026-11-06 +(Docker Desktop Linux VM: 6 CPU / 4 GiB, Swarm, две API-реплики). Секреты, +токены и значения credentials в файлы не попадают. Большие сырые данные не +добавлялись; JSON-агрегаты небольшие. -Не добавляйте .env, session tokens, cookies, приватные ключи, credentials, реальные сообщения, raw dumps и signed URLs. Для скриншотов скрывайте секреты. Большие логи/бинарные traces сохраняйте отдельно по правилам преподавателя; одного скриншота без методики недостаточно. +| Файл | Что подтверждает | +| --- | --- | +| `01-contract-and-openapi.txt` | `check_contract.py` и полная OpenAPI/JSON Schema-валидация | +| `02-public-smoke.txt` | `tests/smoke.py` профиля lab4: users/auth/chat/messages/idempotency/attachment/download/logout | +| `03-student-tests.txt` | 11 собственных тестов: lab3-инварианты + PNG/JPEG, 413/415/400/404, чужой чат, идемпотентность вложений | +| `04-upload-memory.json` | сырые сэмплы памяти API при 12 одновременных загрузках | +| `05-upload-memory-summary.txt` | методика и сводка эксперимента с памятью | +| `06-persistence.txt` | restart API+PostgreSQL+Valkey+MinIO+Traefik, volumes и тот же токен/файл | +| `07-failover.txt` | остановка одной API-реплики, 123 успешных записи, recovery 3.156 s, restore 2/2 | +| `08-attachment-failover.json` | upload → stop обслужившей реплики → download через другую, байты совпали | +| `09-s3-outage.json` | MinIO остановлен: readiness/upload/download 503; после возврата — 200 и файл | +| `10-reconcile.json` | injected fault после S3 PUT: pending+object, dry-run, apply с grace, повторный apply, ready-вложение цело | +| `11-private-bucket.txt` | anonymous GET 403, bucket private, ограниченный API-пользователь не создаёт bucket/не пишет вне префикса | +| `12-infrastructure.txt` | Swarm services, отсутствие published ports у API/MinIO/DB, лимиты, тома, secrets/configs, digest-ы, alembic head/check | +| `13-load-baseline.txt` | closed-loop baseline: 5929 успешных, 197.324 RPS, p50/p95/p99 | +| `14-interrupted-upload.json` | клиент оборвал тело upload: metadata_rows/objects не изменились (0/0), API остался ready | +| `15-bootstrap-idempotent.txt` | два последовательных запуска `minio-init`: оба завершились `bootstrap complete` | + +Ненумерованные `load.json`, `upload-memory.json`, `s3-outage.json`, +`reconcile.json`, `attachment-failover.json` — исходные файлы, из которых +сделаны нумерованные копии. diff --git a/evidence/attachment-failover.json b/evidence/attachment-failover.json new file mode 100644 index 00000000..4b5d40d5 --- /dev/null +++ b/evidence/attachment-failover.json @@ -0,0 +1,13 @@ +{ + "attachment_id": "7534c914-4f2f-47d5-ba53-b237eba3e6f8", + "download_matches": true, + "download_served_by": "3552129b8003", + "downloaded_from_other_replica": true, + "metadata": "ready", + "observed_instances": [ + "5d23c2c33720" + ], + "restore_exit": 0, + "stop_exit": 0, + "target_instance": "5d23c2c33720" +} \ No newline at end of file diff --git a/evidence/interrupted-upload.json b/evidence/interrupted-upload.json new file mode 100644 index 00000000..f1eb098f --- /dev/null +++ b/evidence/interrupted-upload.json @@ -0,0 +1,17 @@ +{ + "aborted_request": { + "response_prefix": "HTTP/1.1 502 Bad Gateway\r\nDate: Fri, 06 Nov 2026 14:56:11 GMT\r\nContent-Length: 1", + "sent_bytes": 1024 + }, + "after": { + "metadata_rows": 94, + "objects": 94 + }, + "before": { + "metadata_rows": 94, + "objects": 94 + }, + "delta_objects": 0, + "delta_rows": 0, + "ready": true +} \ No newline at end of file diff --git a/evidence/load.json b/evidence/load.json new file mode 100644 index 00000000..3dfa1d15 --- /dev/null +++ b/evidence/load.json @@ -0,0 +1,17 @@ +{ + "lab": 4, + "workload": "closed-loop POST messages; no automatic retries", + "requested_duration_seconds": 30.0, + "elapsed_seconds": 30.047, + "concurrency": 4, + "successful_requests": 5929, + "failed_requests": 0, + "error_ratio": 0.0, + "successful_rps": 197.324, + "successful_latency_ms": { + "p50": 16.0, + "p95": 47.0, + "p99": 78.0 + }, + "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." +} diff --git a/evidence/reconcile.json b/evidence/reconcile.json new file mode 100644 index 00000000..0ff5ac55 --- /dev/null +++ b/evidence/reconcile.json @@ -0,0 +1,23 @@ +{ + "apply": { + "deleted_objects": 1, + "deleted_rows": 1, + "missing_ready": 0 + }, + "apply_again": { + "deleted_objects": 0, + "deleted_rows": 0 + }, + "dry_run_fresh": { + "fresh_kept": true, + "would_delete_objects": 0, + "would_delete_rows": 0 + }, + "fault_upload": { + "error": "unavailable", + "instance": "01075da3ebbf", + "status": 503 + }, + "used_attachment": "046bbbbb-ca4f-4fc5-a249-147d047465cf", + "used_download_matches": true +} \ No newline at end of file diff --git a/evidence/s3-outage.json b/evidence/s3-outage.json new file mode 100644 index 00000000..255185e0 --- /dev/null +++ b/evidence/s3-outage.json @@ -0,0 +1,34 @@ +{ + "after": { + "download_matches": true, + "new_upload_ready": "ready", + "ready": true + }, + "before": { + "download_matches": true, + "ready": true + }, + "during": { + "ready": { + "body": "no available server\n", + "seconds": 0.0, + "status": 503, + "x_request_id": null + }, + "trend_download": { + "body": "no available server\n", + "seconds": 0.016, + "status": 503, + "x_request_id": null + }, + "upload": { + "body": "no available server\n", + "seconds": 0.0, + "status": 503, + "x_request_id": null + } + }, + "measured_at": "2026-11-06T14:23:55.081889Z", + "scale_down_seconds": 0, + "stack": "lab4" +} \ No newline at end of file diff --git a/evidence/upload-memory.json b/evidence/upload-memory.json new file mode 100644 index 00000000..64527b39 --- /dev/null +++ b/evidence/upload-memory.json @@ -0,0 +1,116 @@ +{ + "after_rss_bytes": { + "3981ea44b835f8d07e1daab6c615ca56c66295a6259b7fad28033c441b59d866": 180669644, + "627ad63b26d105fa90b6bdb5144c30db565eb3f5cd54883b57a2e734813ea8a0": 182347366 + }, + "base_url": "http://127.0.0.1:8080", + "baseline_rss_bytes": { + "3981ea44b835f8d07e1daab6c615ca56c66295a6259b7fad28033c441b59d866": 180459929, + "627ad63b26d105fa90b6bdb5144c30db565eb3f5cd54883b57a2e734813ea8a0": 177104486 + }, + "concurrency": 12, + "containers": [ + "3981ea44b835f8d07e1daab6c615ca56c66295a6259b7fad28033c441b59d866", + "627ad63b26d105fa90b6bdb5144c30db565eb3f5cd54883b57a2e734813ea8a0" + ], + "elapsed_seconds": 1.953, + "failed": 0, + "image_bytes": 7301750, + "image_dimensions": [ + 1800, + 1350 + ], + "instances": [ + "3981ea44b835", + "627ad63b26d1" + ], + "measured_at": "2026-11-06T14:23:48.900389Z", + "p50_seconds": 1.727, + "p95_seconds": 1.781, + "peak_delta_bytes": 15518925, + "peak_rss_bytes": { + "3981ea44b835f8d07e1daab6c615ca56c66295a6259b7fad28033c441b59d866": 190735974, + "627ad63b26d105fa90b6bdb5144c30db565eb3f5cd54883b57a2e734813ea8a0": 182347366 + }, + "results": [ + { + "instance": "627ad63b26d1", + "seconds": 1.437, + "status": 201 + }, + { + "instance": "627ad63b26d1", + "seconds": 1.562, + "status": 201 + }, + { + "instance": "627ad63b26d1", + "seconds": 1.656, + "status": 201 + }, + { + "instance": "627ad63b26d1", + "seconds": 1.687, + "status": 201 + }, + { + "instance": "3981ea44b835", + "seconds": 1.703, + "status": 201 + }, + { + "instance": "627ad63b26d1", + "seconds": 1.703, + "status": 201 + }, + { + "instance": "3981ea44b835", + "seconds": 1.75, + "status": 201 + }, + { + "instance": "3981ea44b835", + "seconds": 1.75, + "status": 201 + }, + { + "instance": "3981ea44b835", + "seconds": 1.75, + "status": 201 + }, + { + "instance": "3981ea44b835", + "seconds": 1.781, + "status": 201 + }, + { + "instance": "627ad63b26d1", + "seconds": 1.781, + "status": 201 + }, + { + "instance": "3981ea44b835", + "seconds": 1.844, + "status": 201 + } + ], + "samples": [ + { + "memory": { + "3981ea44b835f8d07e1daab6c615ca56c66295a6259b7fad28033c441b59d866": 190735974, + "627ad63b26d105fa90b6bdb5144c30db565eb3f5cd54883b57a2e734813ea8a0": 181613363 + }, + "t": 3265086.125 + }, + { + "memory": { + "3981ea44b835f8d07e1daab6c615ca56c66295a6259b7fad28033c441b59d866": 180669644, + "627ad63b26d105fa90b6bdb5144c30db565eb3f5cd54883b57a2e734813ea8a0": 182347366 + }, + "t": 3265088.328 + } + ], + "successful": 12, + "sum_baseline_rss_bytes": 357564415, + "sum_peak_rss_bytes": 373083340 +} \ No newline at end of file diff --git a/migrations/env.py b/migrations/env.py new file mode 100644 index 00000000..8478d568 --- /dev/null +++ b/migrations/env.py @@ -0,0 +1,58 @@ +"""Окружение Alembic: URL базы берётся из тех же переменных, что и у приложения.""" +from __future__ import annotations + +import asyncio +from logging.config import fileConfig + +from alembic import context +from sqlalchemy import pool +from sqlalchemy.ext.asyncio import async_engine_from_config + +from messenger.config import database_url_from_env +from messenger.schema import METADATA + +config = context.config + +if config.config_file_name is not None: + fileConfig(config.config_file_name) + +# Сравнение идёт ровно с теми объектами, по которым работает приложение: +# расхождение между схемой и миграциями ловится на `alembic check`. +target_metadata = METADATA + + +def run_migrations_offline() -> None: + """Режим без подключения: печатает SQL миграции, удобен для ревью.""" + context.configure( + url=database_url_from_env(), + target_metadata=target_metadata, + literal_binds=True, + compare_type=True, + dialect_opts={"paramstyle": "named"}, + ) + with context.begin_transaction(): + context.run_migrations() + + +def _run_migrations(connection) -> None: + context.configure(connection=connection, target_metadata=target_metadata, compare_type=True) + with context.begin_transaction(): + context.run_migrations() + + +async def run_migrations_online() -> None: + """Драйвер асинхронный (asyncpg), поэтому миграции идут через run_sync.""" + section = config.get_section(config.config_ini_section, {}) + section["sqlalchemy.url"] = database_url_from_env() + engine = async_engine_from_config(section, prefix="sqlalchemy.", poolclass=pool.NullPool) + try: + async with engine.connect() as connection: + await connection.run_sync(_run_migrations) + finally: + await engine.dispose() + + +if context.is_offline_mode(): + run_migrations_offline() +else: + asyncio.run(run_migrations_online()) diff --git a/migrations/script.py.mako b/migrations/script.py.mako new file mode 100644 index 00000000..c6284cb9 --- /dev/null +++ b/migrations/script.py.mako @@ -0,0 +1,24 @@ +"""${message} + +Revision ID: ${up_revision} +Revises: ${down_revision | comma,n} +Create Date: ${create_date} +""" +from __future__ import annotations + +from alembic import op +import sqlalchemy as sa +${imports if imports else ""} + +revision = ${repr(up_revision)} +down_revision = ${repr(down_revision)} +branch_labels = ${repr(branch_labels)} +depends_on = ${repr(depends_on)} + + +def upgrade() -> None: + ${upgrades if upgrades else "pass"} + + +def downgrade() -> None: + ${downgrades if downgrades else "pass"} diff --git a/migrations/versions/0001_initial_schema.py b/migrations/versions/0001_initial_schema.py new file mode 100644 index 00000000..4cdd21cf --- /dev/null +++ b/migrations/versions/0001_initial_schema.py @@ -0,0 +1,103 @@ +"""Начальная схема: пользователи, чаты, участники и сообщения + +Revision ID: 0001_initial_schema +Revises: +Create Date: 2026-10-11 + +DDL написан вручную и повторяет src/messenger/schema.py: имена ограничений +и индексов совпадают, поэтому `alembic check` не находит расхождений между +схемой в базе и описанием, по которому работают запросы. +""" +from __future__ import annotations + +import sqlalchemy as sa +from alembic import op +from sqlalchemy.dialects import postgresql + +revision = "0001_initial_schema" +down_revision = None +branch_labels = None +depends_on = None + + +def upgrade() -> None: + op.create_table( + "users", + sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column("username", sa.Text(), nullable=False), + sa.Column("display_name", sa.Text(), nullable=False), + sa.Column("password_hash", sa.Text(), nullable=False), + sa.Column( + "created_at", + postgresql.TIMESTAMP(timezone=True), + server_default=sa.text("now()"), + nullable=False, + ), + sa.CheckConstraint( + "char_length(display_name) BETWEEN 1 AND 100", name="ck_users_display_name_length" + ), + sa.CheckConstraint(r"username ~ '^[a-z0-9_]{3,32}$'", name="ck_users_username_format"), + sa.PrimaryKeyConstraint("id"), + sa.UniqueConstraint("username", name="uq_users_username"), + ) + + op.create_table( + "chats", + sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column("title", sa.Text(), nullable=False), + sa.Column( + "created_at", + postgresql.TIMESTAMP(timezone=True), + server_default=sa.text("now()"), + nullable=False, + ), + sa.CheckConstraint("char_length(title) BETWEEN 1 AND 100", name="ck_chats_title_length"), + sa.PrimaryKeyConstraint("id"), + ) + + op.create_table( + "chat_members", + sa.Column("chat_id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column("user_id", postgresql.UUID(as_uuid=True), nullable=False), + sa.ForeignKeyConstraint( + ["chat_id"], ["chats.id"], name="fk_chat_members_chat", ondelete="CASCADE" + ), + sa.ForeignKeyConstraint( + ["user_id"], ["users.id"], name="fk_chat_members_user", ondelete="RESTRICT" + ), + sa.PrimaryKeyConstraint("chat_id", "user_id"), + ) + op.create_index("ix_chat_members_user_id_chat_id", "chat_members", ["user_id", "chat_id"]) + + op.create_table( + "messages", + sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column("chat_id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column("sender_id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column("text", sa.Text(), nullable=False), + sa.Column( + "created_at", + postgresql.TIMESTAMP(timezone=True), + server_default=sa.text("now()"), + nullable=False, + ), + sa.CheckConstraint( + "text <> '' AND char_length(text) <= 4000", name="ck_messages_text_length" + ), + sa.ForeignKeyConstraint(["chat_id"], ["chats.id"], name="fk_messages_chat", ondelete="CASCADE"), + sa.ForeignKeyConstraint( + ["sender_id"], ["users.id"], name="fk_messages_sender", ondelete="RESTRICT" + ), + sa.PrimaryKeyConstraint("id"), + ) + # Порядок истории (created_at, id) и keyset-предикат обслуживает один индекс. + op.create_index("ix_messages_chat_id_created_at_id", "messages", ["chat_id", "created_at", "id"]) + + +def downgrade() -> None: + op.drop_index("ix_messages_chat_id_created_at_id", table_name="messages") + op.drop_table("messages") + op.drop_index("ix_chat_members_user_id_chat_id", table_name="chat_members") + op.drop_table("chat_members") + op.drop_table("chats") + op.drop_table("users") diff --git a/migrations/versions/0002_message_idempotency.py b/migrations/versions/0002_message_idempotency.py new file mode 100644 index 00000000..56f714ed --- /dev/null +++ b/migrations/versions/0002_message_idempotency.py @@ -0,0 +1,61 @@ +"""Общая идемпотентность отправки сообщения + +Revision ID: 0002_message_idempotency +Revises: 0001_initial_schema +Create Date: 2026-10-30 + +Таблица описана в src/messenger/schema.py; DDL повторяет имена ограничений и +индексов, чтобы alembic check не находил расхождений. +""" +from __future__ import annotations + +import sqlalchemy as sa +from alembic import op +from sqlalchemy.dialects import postgresql + +revision = "0002_message_idempotency" +down_revision = "0001_initial_schema" +branch_labels = None +depends_on = None + + +def upgrade() -> None: + op.create_table( + "message_idempotency", + sa.Column("user_id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column("chat_id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column("idempotency_key", sa.Text(), nullable=False), + sa.Column("request_hash", sa.Text(), nullable=False), + sa.Column("message_id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column( + "created_at", + postgresql.TIMESTAMP(timezone=True), + server_default=sa.text("now()"), + nullable=False, + ), + sa.CheckConstraint( + "char_length(idempotency_key) BETWEEN 1 AND 128", + name="ck_message_idempotency_key_length", + ), + sa.ForeignKeyConstraint( + ["chat_id"], ["chats.id"], name="fk_message_idempotency_chat", ondelete="CASCADE" + ), + sa.ForeignKeyConstraint( + ["message_id"], + ["messages.id"], + name="fk_message_idempotency_message", + ondelete="CASCADE", + ), + sa.ForeignKeyConstraint( + ["user_id"], ["users.id"], name="fk_message_idempotency_user", ondelete="CASCADE" + ), + sa.PrimaryKeyConstraint("user_id", "chat_id", "idempotency_key"), + ) + op.create_index( + "ix_message_idempotency_created_at", "message_idempotency", ["created_at"] + ) + + +def downgrade() -> None: + op.drop_index("ix_message_idempotency_created_at", table_name="message_idempotency") + op.drop_table("message_idempotency") diff --git a/migrations/versions/0003_attachments.py b/migrations/versions/0003_attachments.py new file mode 100644 index 00000000..d1387085 --- /dev/null +++ b/migrations/versions/0003_attachments.py @@ -0,0 +1,128 @@ +"""Вложения и связь сообщений с вложениями + +Revision ID: 0003_attachments +Revises: 0002_message_idempotency +Create Date: 2026-11-06 + +DDL повторяет src/messenger/schema.py, включая имена ограничений и индексов, +поэтому `alembic check` не находит расхождений. Отдельно ослабляется CHECK +текста сообщения: пустая строка теперь допустима только вместе с вложением, +а это правило проверяет API (CHECK не может ссылаться на другую таблицу). +""" +from __future__ import annotations + +import sqlalchemy as sa +from alembic import op +from sqlalchemy.dialects import postgresql + +revision = "0003_attachments" +down_revision = "0002_message_idempotency" +branch_labels = None +depends_on = None + + +def upgrade() -> None: + op.create_table( + "attachments", + sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column("chat_id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column("owner_id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column("object_key", sa.Text(), nullable=False), + sa.Column("filename", sa.Text(), nullable=False), + sa.Column("content_type", sa.Text(), nullable=False), + sa.Column("size_bytes", sa.BigInteger(), nullable=False), + sa.Column("sha256", sa.Text(), nullable=False), + sa.Column("status", sa.Text(), server_default=sa.text("'pending'"), nullable=False), + sa.Column("error_code", sa.Text(), nullable=True), + sa.Column( + "created_at", + postgresql.TIMESTAMP(timezone=True), + server_default=sa.text("now()"), + nullable=False, + ), + sa.Column( + "updated_at", + postgresql.TIMESTAMP(timezone=True), + server_default=sa.text("now()"), + nullable=False, + ), + sa.CheckConstraint( + "char_length(filename) BETWEEN 1 AND 255", name="ck_attachments_filename_length" + ), + sa.CheckConstraint( + "content_type IN ('image/png','image/jpeg')", name="ck_attachments_content_type" + ), + sa.CheckConstraint( + "size_bytes > 0 AND size_bytes <= 10485760", name="ck_attachments_size_bytes" + ), + sa.CheckConstraint("sha256 ~ '^[a-f0-9]{64}$'", name="ck_attachments_sha256"), + sa.CheckConstraint( + "status IN ('pending','ready','failed')", name="ck_attachments_status" + ), + sa.CheckConstraint( + "error_code IS NULL OR char_length(error_code) BETWEEN 1 AND 64", + name="ck_attachments_error_code", + ), + sa.ForeignKeyConstraint( + ["chat_id"], ["chats.id"], name="fk_attachments_chat", ondelete="CASCADE" + ), + sa.ForeignKeyConstraint( + ["owner_id"], ["users.id"], name="fk_attachments_owner", ondelete="RESTRICT" + ), + sa.PrimaryKeyConstraint("id"), + sa.UniqueConstraint("object_key", name="uq_attachments_object_key"), + ) + op.create_index( + "ix_attachments_chat_id_created_at_id", + "attachments", + ["chat_id", "created_at", "id"], + ) + op.create_index("ix_attachments_status_updated_at", "attachments", ["status", "updated_at"]) + + op.create_table( + "message_attachments", + sa.Column("message_id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column("attachment_id", postgresql.UUID(as_uuid=True), nullable=False), + sa.Column("position", sa.SmallInteger(), nullable=False), + sa.CheckConstraint( + "position >= 0 AND position < 10", name="ck_message_attachments_position" + ), + sa.ForeignKeyConstraint( + ["attachment_id"], + ["attachments.id"], + name="fk_message_attachments_attachment", + ondelete="RESTRICT", + ), + sa.ForeignKeyConstraint( + ["message_id"], + ["messages.id"], + name="fk_message_attachments_message", + ondelete="CASCADE", + ), + sa.PrimaryKeyConstraint("message_id", "attachment_id"), + sa.UniqueConstraint( + "message_id", "position", name="uq_message_attachments_position" + ), + ) + op.create_index( + "ix_message_attachments_attachment_id", + "message_attachments", + ["attachment_id"], + ) + + op.drop_constraint("ck_messages_text_length", "messages", type_="check") + op.create_check_constraint( + "ck_messages_text_length", "messages", "char_length(text) <= 4000" + ) + + +def downgrade() -> None: + op.drop_constraint("ck_messages_text_length", "messages", type_="check") + op.create_check_constraint( + "ck_messages_text_length", "messages", "text <> '' AND char_length(text) <= 4000" + ) + op.drop_index("ix_message_attachments_attachment_id", table_name="message_attachments") + op.drop_table("message_attachments") + op.drop_index("ix_attachments_status_updated_at", table_name="attachments") + op.drop_index("ix_attachments_chat_id_created_at_id", table_name="attachments") + op.drop_table("attachments") diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..7b065e14 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,37 @@ +# Рантайм-зависимости лабораторной 4: точное замыкание (top-level и транзитивные), +# получено `pip freeze` после установки на Python 3.11.9: +# pip install fastapi==0.141.1 uvicorn==0.53.0 "sqlalchemy[asyncio]==2.0.44" \ +# asyncpg==0.30.0 alembic==1.16.5 redis==6.4.0 argon2-cffi==25.1.0 \ +# boto3==1.43.125 Pillow==13.0.0 +alembic==1.16.5 +annotated-doc==0.0.5 +annotated-types==0.8.0 +anyio==4.15.1 +argon2-cffi==25.1.0 +argon2-cffi-bindings==26.1.0 +asyncpg==0.30.0 +boto3==1.43.125 +botocore==1.43.125 +cffi==2.1.1 +click==8.5.0 +fastapi==0.141.1 +greenlet==3.5.6 +h11==0.16.0 +idna==3.20 +jmespath==1.1.0 +Mako==1.4.3 +MarkupSafe==3.0.4 +pycparser==3.11 +pydantic==2.14.0 +Pillow==13.0.0 +pydantic_core==2.50.0 +python-dateutil==2.9.0.post0 +redis==6.4.0 +SQLAlchemy==2.0.44 +s3transfer==0.19.3 +six==1.17.0 +starlette==1.7.0 +typing-inspection==0.4.4 +typing_extensions==4.16.0 +urllib3==2.5.0 +uvicorn==0.53.0 \ No newline at end of file diff --git a/scripts/bootstrap-secrets.sh b/scripts/bootstrap-secrets.sh new file mode 100644 index 00000000..746d3ff3 --- /dev/null +++ b/scripts/bootstrap-secrets.sh @@ -0,0 +1,49 @@ +#!/bin/sh +# Create local Swarm secret files under secrets/ (gitignored, never printed). +# Existing files are never overwritten, so rerunning the script is safe. +# Usage: sh scripts/bootstrap-secrets.sh +set -eu + +root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd) +dir="$root/secrets" + +# Files are created with mode 600: group and other have no access. +umask 077 +mkdir -p "$dir" + +random_hex() { + head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n' +} + +# 10 bytes = 20 hex chars: MinIO access keys are limited to 20 characters. +random_access_key() { + head -c 10 /dev/urandom | od -An -tx1 | tr -d ' \n' +} + +# write : keeps the current file if it already has content. +write() { + name=$1 + value=$2 + if [ -s "$dir/$name" ]; then + printf 'keep secrets/%s\n' "$name" + return 0 + fi + printf '%s\n' "$value" > "$dir/$name" + printf 'create secrets/%s\n' "$name" +} + +write postgres_password "$(random_hex)" +write cursor_secret "$(random_hex)" +write cache_url 'redis://valkey:6379/0' +# The password is hex, so the URL needs no percent-encoding. +write database_url "postgresql+asyncpg://messenger:$(cat "$dir/postgres_password")@postgres:5432/messenger" + +# MinIO: root credentials only for minio-init; API uses a separate restricted +# pair. The access key is 20 hex chars (MinIO limit), the secret is 64 hex chars. +write s3_root_user 'messenger-root' +write s3_root_password "$(random_hex)" +write s3_access_key_id "$(random_access_key)" +write s3_secret_access_key "$(random_hex)" + +printf 'done: %s\n' "$dir" +printf 'next: sh scripts/deploy.sh\n' diff --git a/scripts/check-bucket-private.sh b/scripts/check-bucket-private.sh new file mode 100644 index 00000000..9182ecad --- /dev/null +++ b/scripts/check-bucket-private.sh @@ -0,0 +1,48 @@ +#!/bin/sh +# Проверка приватности bucket и ограниченности API-пользователя. +# +# Запускается в образе MinIO (в нём есть mc и curl) на backend-сети стенда: +# docker run --rm --network lab4_backend --user 0 \ +# -v "$PWD/scripts:/scripts:ro" -v "$PWD/secrets:/run/secrets:ro" \ +# -e S3_ENDPOINT=http://minio:9000 -e S3_BUCKET=messenger-attachments \ +# --entrypoint /bin/sh minio/minio:... /scripts/check-bucket-private.sh +# +# Root нужен только для чтения local secrets в этом проверочном контейнере; +# API-пользователь проверяется отдельным alias и не имеет прав на bucket. +set -eu + +endpoint=${S3_ENDPOINT:-http://minio:9000} +bucket=${S3_BUCKET:-messenger-attachments} +export MC_CONFIG_DIR=${MC_CONFIG_DIR:-/tmp/.mc} +mkdir -p "$MC_CONFIG_DIR" + +root_user=$(cat "${MINIO_ROOT_USER_FILE:?}") +root_password=$(cat "${MINIO_ROOT_PASSWORD_FILE:?}") +access_key=$(cat "${S3_ACCESS_KEY_ID_FILE:?}") +secret_key=$(cat "${S3_SECRET_ACCESS_KEY_FILE:?}") + +mc alias set root "$endpoint" "$root_user" "$root_password" >/dev/null +mc alias set api "$endpoint" "$access_key" "$secret_key" >/dev/null + +printf 'anonymous-policy: ' +mc anonymous get "root/$bucket" 2>&1 || true +printf 'anonymous-http-get: ' +curl -s -o /dev/null -w '%{http_code}\n' "$endpoint/$bucket/attachments/does-not-exist" +printf 'api-list-attachments: ' +mc ls "api/$bucket/attachments/" >/tmp/list.txt 2>&1 && head -1 /tmp/list.txt || cat /tmp/list.txt +printf 'api-create-bucket: ' +if mc mb "api/should-not-exist" >/dev/null 2>&1; then + printf 'ALLOWED (unexpected)\n' + mc rb "api/should-not-exist" >/dev/null 2>&1 || true +else + printf 'denied (expected)\n' +fi +printf 'api-put-other-bucket: ' +echo test >/tmp/probe +if mc cp /tmp/probe "api/other-bucket/" >/dev/null 2>&1; then + printf 'ALLOWED (unexpected)\n' +else + printf 'denied (expected)\n' +fi +printf 'root-bucket-list: ' +mc ls "root/$bucket/" >/dev/null 2>&1 && printf 'ok\n' || printf 'failed\n' diff --git a/scripts/collect_infrastructure.py b/scripts/collect_infrastructure.py new file mode 100644 index 00000000..bd01d018 --- /dev/null +++ b/scripts/collect_infrastructure.py @@ -0,0 +1,117 @@ +#!/usr/bin/env python3 +"""Собирает текстовый evidence об инфраструктуре без секретов. + +Все команды выполняются локальным Docker CLI; stdout/stderr сохраняются как +есть. Секреты в вывод не попадают: печатаются только имена Docker secrets и +пути внутри контейнеров, но не их значения. +""" +from __future__ import annotations + +import os +import platform +import subprocess +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +OUT = ROOT / "evidence" / "12-infrastructure.txt" +STACK = os.environ.get("STACK_NAME", "lab4") +IMAGE = os.environ.get("API_IMAGE", "mtusi-messenger-lab4:4.0.0") +MINIO = "minio/minio@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e" + + +def run(*args: str) -> tuple[int, str]: + result = subprocess.run(["docker", *args], capture_output=True, text=True, encoding="utf-8", errors="replace") + text = result.stdout + if result.stderr: + text += "$ stderr\n" + result.stderr + return result.returncode, text + + +def main() -> int: + lines: list[str] = [] + lines.append("# Infrastructure and image pinning") + lines.append("host=" + platform.node() + " platform=" + platform.platform()) + lines.append("python=" + sys.version.split()[0]) + lines.append("") + for label, args in [ + ("docker version", ("version", "--format", "client={{.Client.Version}} server={{.Server.Version}}")), + ("docker info", ("info", "--format", "swarm={{.Swarm.LocalNodeState}} cpus={{.NCPU}} mem={{.MemTotal}}")), + ("stack services", ("stack", "services", STACK)), + ( + "api service", + ( + "service", "inspect", STACK + "_api", "--format", + "image={{.Spec.TaskTemplate.ContainerSpec.Image}} ports={{json .Endpoint.Ports}} " + "limits={{json .Spec.TaskTemplate.Resources.Limits}} " + "reservations={{json .Spec.TaskTemplate.Resources.Reservations}} " + "update={{json .Spec.UpdateConfig}}", + ), + ), + ( + "minio service", + ( + "service", "inspect", STACK + "_minio", "--format", + "image={{.Spec.TaskTemplate.ContainerSpec.Image}} ports={{json .Endpoint.Ports}} " + "limits={{json .Spec.TaskTemplate.Resources.Limits}} " + "mounts={{json .Spec.TaskTemplate.ContainerSpec.Mounts}}", + ), + ), + ("traefik ports", ("service", "inspect", STACK + "_traefik", "--format", "ports={{json .Endpoint.Ports}}")), + ("volumes", ("volume", "ls", "--filter", "name=" + STACK, "--format", "{{.Name}} {{.Driver}}")), + ("secrets (names only)", ("secret", "ls", "--filter", "name=" + STACK, "--format", "{{.Name}}")), + ("configs (names only)", ("config", "ls", "--filter", "name=" + STACK, "--format", "{{.Name}}")), + ("api secret mounts", ("service", "inspect", STACK + "_api", "--format", "{{json .Spec.TaskTemplate.ContainerSpec.Secrets}}")), + ("minio-init secret mounts", ("service", "inspect", STACK + "_minio-init", "--format", "{{json .Spec.TaskTemplate.ContainerSpec.Secrets}}")), + ("migrate log", ("service", "logs", STACK + "_migrate", "--tail", "20")), + ("minio-init log", ("service", "logs", STACK + "_minio-init", "--tail", "20")), + ]: + lines.append("## " + label) + code, text = run(*args) + lines.append("exit=" + str(code)) + lines.append(text.rstrip()) + lines.append("") + + lines.append("## other service ports (must be null)") + for name in ("postgres", "valkey", "minio-init", "migrate"): + code, text = run("service", "inspect", STACK + "_" + name, "--format", "{{.Spec.Name}} ports={{json .Endpoint.Ports}}") + lines.append("exit=" + str(code) + " " + text.strip()) + lines.append("") + + lines.append("## image digests") + for image in ( + IMAGE, + MINIO, + "postgres@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4", + "valkey/valkey@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab", + "traefik:v3.5.4", + "python:3.11.9-slim-bookworm", + ): + code, text = run("image", "inspect", image, "--format", "{{.RepoTags}} id={{.Id}} digests={{json .RepoDigests}}") + lines.append("exit=" + str(code) + " " + text.strip()) + lines.append("") + + lines.append("## alembic current / check") + secrets = str(ROOT / "secrets") + for name, args in ( + ("current", ("-d", "--name", "alembic-current", "--network", STACK + "_backend", "--user", "0", + "-v", secrets + ":/run/secrets:ro", "-e", "DATABASE_URL_FILE=/run/secrets/database_url", + "--entrypoint", "alembic", IMAGE, "current")), + ("check", ("-d", "--name", "alembic-check", "--network", STACK + "_backend", "--user", "0", + "-v", secrets + ":/run/secrets:ro", "-e", "DATABASE_URL_FILE=/run/secrets/database_url", + "--entrypoint", "alembic", IMAGE, "check")), + ): + run("run", *args) + run("wait", "alembic-" + name) + code, text = run("logs", "alembic-" + name) + lines.append("-- " + name + " exit=" + str(code)) + lines.append(text.rstrip()) + run("rm", "-f", "alembic-" + name) + + OUT.write_text("\n".join(lines) + "\n", encoding="utf-8") + print("wrote", OUT) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/deploy.cmd b/scripts/deploy.cmd new file mode 100644 index 00000000..77170029 --- /dev/null +++ b/scripts/deploy.cmd @@ -0,0 +1,4 @@ +@echo off +rem Windows wrapper for scripts/hooks.ps1 (deploy). +powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0hooks.ps1" -Mode deploy %* +exit /b %ERRORLEVEL% diff --git a/scripts/deploy.sh b/scripts/deploy.sh new file mode 100644 index 00000000..04c6e872 --- /dev/null +++ b/scripts/deploy.sh @@ -0,0 +1,52 @@ +#!/bin/sh +# Build the application image, create local Swarm secrets once, deploy the stack. +# +# Prerequisites: Docker Engine with Swarm mode (docker swarm init is done here if +# needed) and the files created by scripts/bootstrap-secrets.sh. No secret value +# is printed. This is the one documented bootstrap sequence for stack.yaml. +set -eu +root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd) +cd "$root" + +# The public failover test invokes the action script without a shell; it must be +# executable on POSIX. Git may not preserve the mode on a Windows checkout. +chmod +x scripts/stop-one.sh scripts/restore.sh scripts/restart.sh scripts/rolling-update.sh scripts/deploy.sh 2>/dev/null || true + +stack=${STACK_NAME:-lab4} +image=${API_IMAGE:-mtusi-messenger-lab4:4.0.0} + +state=$(docker info --format '{{.Swarm.LocalNodeState}}') +if [ "$state" != "active" ]; then + docker swarm init >/dev/null +fi + +sh scripts/bootstrap-secrets.sh +for name in database_url cache_url postgres_password cursor_secret s3_root_user s3_root_password s3_access_key_id s3_secret_access_key; do + if ! docker secret inspect "${stack}_${name}" >/dev/null 2>&1; then + docker secret create "${stack}_${name}" "secrets/${name}" >/dev/null + fi +done + +docker build -t "$image" . + +# Swarm configs неизменяемы. Перед повторным deploy убираем завершившийся +# minio-init и его config, иначе stack deploy попытается обновить config и +# получит "only updates to Labels are allowed". На первом deploy это no-op. +docker service rm "${stack}_minio-init" >/dev/null 2>&1 || true +docker config rm "${stack}_lab4_minio_init" >/dev/null 2>&1 || true + +API_IMAGE="$image" docker stack deploy --resolve-image never -c stack.yaml "$stack" + +i=0 +while [ "$i" -lt 90 ]; do + if curl -fsS http://127.0.0.1:8080/health/ready >/dev/null 2>&1; then + printf 'deployed: http://127.0.0.1:8080 (image %s)\n' "$image" + docker stack services "$stack" + exit 0 + fi + i=$((i + 1)) + sleep 2 +done +printf 'stack did not become ready within 180s\n' >&2 +docker stack services "$stack" >&2 || true +exit 1 \ No newline at end of file diff --git a/scripts/hooks.ps1 b/scripts/hooks.ps1 new file mode 100644 index 00000000..e2ca189d --- /dev/null +++ b/scripts/hooks.ps1 @@ -0,0 +1,165 @@ +# Windows twin of scripts/deploy.sh, stop-one.sh, restore.sh, restart.sh and +# rolling-update.sh. The public resilience test launches an action script with +# Popen([script]) without a shell; on native Windows a .cmd wrapper is required. +# +# X-Instance-Id is the Swarm task container hostname, so a target is resolved by +# inspecting running task containers, not by trusting the header alone. +param( + [Parameter(Mandatory = $true)] + [ValidateSet('deploy', 'stop-one', 'restore', 'restart', 'rollout')] + [string]$Mode, + [string]$Image = '' +) + +$ErrorActionPreference = 'Stop' +$root = Split-Path -Parent (Split-Path -Parent $MyInvocation.MyCommand.Path) +Set-Location $root +$stack = if ($env:STACK_NAME) { $env:STACK_NAME } else { 'lab4' } +$service = "$stack" + '_api' +if (-not $Image) { + $Image = if ($env:API_IMAGE) { $env:API_IMAGE } else { 'mtusi-messenger-lab4:4.0.0' } +} + +function Invoke-Docker { + param([Parameter(ValueFromRemainingArguments = $true)][string[]]$Arguments) + & docker @Arguments + if ($LASTEXITCODE -ne 0) { + throw "docker $($Arguments -join ' ') failed with exit code $LASTEXITCODE" + } +} + +function Test-Ready { + try { + $response = Invoke-WebRequest -UseBasicParsing -Uri 'http://127.0.0.1:8080/health/ready' -TimeoutSec 3 + return $response.StatusCode -eq 200 + } catch { + return $false + } +} + +function Wait-Ready { + param([int]$Seconds = 180) + $deadline = (Get-Date).AddSeconds($Seconds) + while ((Get-Date) -lt $deadline) { + if (Test-Ready) { return } + Start-Sleep -Seconds 2 + } + throw "stack did not become ready within $Seconds seconds" +} + +function Get-RunningTasks { + return @(& docker service ps -q $service --filter desired-state=running) +} + +function Find-TargetContainer { + param([string]$Target) + foreach ($task in (Get-RunningTasks)) { + $container = (& docker inspect -f '{{.Status.ContainerStatus.ContainerID}}' $task 2>$null) + if (-not $container) { continue } + $hostname = (& docker inspect -f '{{.Config.Hostname}}' $container 2>$null) + if ($hostname -eq $Target) { return $container } + } + return $null +} + +function New-HexSecret { + param([int]$Bytes = 32) + $buffer = New-Object byte[] $Bytes + [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($buffer) + return (-join ($buffer | ForEach-Object { $_.ToString('x2') })) +} + +function Ensure-SecretFiles { + New-Item -ItemType Directory -Force -Path 'secrets' | Out-Null + $passwordPath = Join-Path 'secrets' 'postgres_password' + $password = if ((Test-Path $passwordPath) -and (Get-Item $passwordPath).Length -gt 0) { + (Get-Content $passwordPath -Raw).Trim() + } else { + New-HexSecret + } + $defaults = [ordered]@{ + postgres_password = $password + cursor_secret = (New-HexSecret) + cache_url = 'redis://valkey:6379/0' + database_url = "postgresql+asyncpg://messenger:$password@postgres:5432/messenger" + s3_root_user = 'messenger-root' + s3_root_password = (New-HexSecret) + s3_access_key_id = (New-HexSecret -Bytes 10) + s3_secret_access_key = (New-HexSecret) + } + foreach ($name in $defaults.Keys) { + $path = Join-Path 'secrets' $name + if (-not (Test-Path $path) -or (Get-Item $path).Length -eq 0) { + Set-Content -NoNewline -Encoding ascii -Path $path -Value $defaults[$name] + } + } +} + +function Ensure-Secrets { + $names = @('database_url', 'cache_url', 'postgres_password', 'cursor_secret', 's3_root_user', 's3_root_password', 's3_access_key_id', 's3_secret_access_key') + $existing = @(& docker secret ls --format '{{.Name}}') + foreach ($name in $names) { + $secret = "$stack" + '_' + $name + if ($existing -notcontains $secret) { + Invoke-Docker secret create $secret (Join-Path 'secrets' $name) | Out-Null + } + } +} + +switch ($Mode) { + 'deploy' { + $state = (& docker info --format '{{.Swarm.LocalNodeState}}').Trim() + if ($state -ne 'active') { Invoke-Docker swarm init | Out-Null } + Ensure-SecretFiles + Ensure-Secrets + Invoke-Docker build -t $Image . | Out-Null + $env:API_IMAGE = $Image + # Swarm configs неизменяемы: перед повторным deploy убираем завершившийся + # minio-init и его config; на первом deploy это no-op. + & cmd /c "docker service rm ${stack}_minio-init >nul 2>&1" + & cmd /c "docker config rm ${stack}_lab4_minio_init >nul 2>&1" + Invoke-Docker stack deploy --resolve-image never -c stack.yaml $stack | Out-Null + Wait-Ready + & docker stack services $stack + } + 'stop-one' { + $target = $env:TARGET_INSTANCE_ID + if (-not $target) { throw 'TARGET_INSTANCE_ID is required' } + $container = Find-TargetContainer $target + if (-not $container) { throw "target instance $target not found among running tasks" } + Write-Output "stopping instance $target container $container" + Invoke-Docker stop --time 15 $container | Out-Null + # Swarm may already be creating a replacement task; the target container + # itself was stopped by id and its X-Instance-Id will not be served again. + Write-Output "instance $target stopped" + } + 'restore' { + Invoke-Docker service update --restart-condition any --replicas 2 $service | Out-Null + $running = @(Get-RunningTasks).Count + if ($running -lt 2) { Invoke-Docker service update --force $service | Out-Null } + $deadline = (Get-Date).AddSeconds(120) + while ((Get-Date) -lt $deadline) { + $running = @(Get-RunningTasks).Count + if ($running -ge 2 -and (Test-Ready)) { + Write-Output "api restored: $running running tasks and readiness OK" + exit 0 + } + Start-Sleep -Seconds 2 + } + throw 'api did not recover within 120s' + } + 'restart' { + foreach ($name in @('postgres', 'valkey', 'minio', 'api', 'traefik')) { + $svc = $stack + '_' + $name + Write-Output "restarting $svc" + Invoke-Docker service update --force $svc | Out-Null + } + Wait-Ready + Write-Output 'stack ready after restart' + } + 'rollout' { + Invoke-Docker build --build-arg APP_REVISION=$Image -t $Image . | Out-Null + Invoke-Docker service update --image $Image --update-order start-first --update-parallelism 1 --update-delay 5s --update-failure-action rollback $service | Out-Null + & docker service ps $service --no-trunc + } +} \ No newline at end of file diff --git a/scripts/minio-init.sh b/scripts/minio-init.sh new file mode 100644 index 00000000..33402ee7 --- /dev/null +++ b/scripts/minio-init.sh @@ -0,0 +1,86 @@ +#!/bin/sh +# Идемпотентный bootstrap приватного bucket и ограниченного S3-пользователя. +# +# Запускается один раз сервисом minio-init (образ MinIO уже содержит mc). +# Повторный запуск не удаляет данные: bucket создаётся с --ignore-existing, +# пользователь переиспользуется, политика пересоздаётся и привязывается заново. +# Root-credentials используются только здесь; API получает отдельную пару. +set -eu + +endpoint=${S3_ENDPOINT:-http://minio:9000} +bucket=${S3_BUCKET:-messenger-attachments} +policy_name=${S3_POLICY_NAME:-messenger-attachments-rw} + +read_secret() { + # $1 — путь к Docker secret; секрет не печатается. + cat "$1" +} + +root_user=$(read_secret "${MINIO_ROOT_USER_FILE:?MINIO_ROOT_USER_FILE is required}") +root_password=$(read_secret "${MINIO_ROOT_PASSWORD_FILE:?MINIO_ROOT_PASSWORD_FILE is required}") +access_key=$(read_secret "${S3_ACCESS_KEY_ID_FILE:?S3_ACCESS_KEY_ID_FILE is required}") +secret_key=$(read_secret "${S3_SECRET_ACCESS_KEY_FILE:?S3_SECRET_ACCESS_KEY_FILE is required}") + +export MC_CONFIG_DIR=${MC_CONFIG_DIR:-/tmp/.mc} +mkdir -p "$MC_CONFIG_DIR" + +i=0 +until mc alias set local "$endpoint" "$root_user" "$root_password" --api S3v4 >/dev/null 2>&1; do + i=$((i + 1)) + if [ "$i" -ge 60 ]; then + printf 'minio is not reachable at %s\n' "$endpoint" >&2 + exit 1 + fi + sleep 2 +done + +until mc ready local >/dev/null 2>&1; do + i=$((i + 1)) + if [ "$i" -ge 120 ]; then + printf 'minio did not become ready\n' >&2 + exit 1 + fi + sleep 1 +done + +mc mb --ignore-existing "local/$bucket" >/dev/null +mc anonymous set none "local/$bucket" >/dev/null + +# Пользователь API: при повторном запуске оставляем существующего, чтобы не +# разорвать уже работающий API. Секрет при первом создании берётся из secrets. +mc admin user add local "$access_key" "$secret_key" >/dev/null 2>&1 || true +if ! mc admin user info local "$access_key" >/dev/null 2>&1; then + printf 'failed to create API user\n' >&2 + exit 1 +fi + +cat >/tmp/messenger-attachments-policy.json </dev/null 2>&1 || true +mc admin policy remove local "$policy_name" >/dev/null 2>&1 || true +mc admin policy create local "$policy_name" /tmp/messenger-attachments-policy.json >/dev/null +mc admin policy attach local "$policy_name" --user "$access_key" >/dev/null + +printf 'minio bootstrap complete: bucket=%s private=yes policy=%s\n' "$bucket" "$policy_name" diff --git a/scripts/reconcile.sh b/scripts/reconcile.sh new file mode 100644 index 00000000..3a0b843a --- /dev/null +++ b/scripts/reconcile.sh @@ -0,0 +1,14 @@ +#!/bin/sh +# Запуск сверки PostgreSQL/S3 внутри работающего API-контейнера. +# +# Использует те же secrets и переменные окружения, что и API, поэтому не +# требует отдельного набора credentials. По умолчанию — dry-run; для удаления +# мусора добавьте --apply. +set -eu +stack=${STACK_NAME:-lab4} +container=$(docker ps -q -f "name=${stack}_api" | head -n 1) +if [ -z "$container" ]; then + printf 'no running %s_api container\n' "$stack" >&2 + exit 2 +fi +docker exec "$container" python -m messenger.reconcile "$@" diff --git a/scripts/restart.cmd b/scripts/restart.cmd new file mode 100644 index 00000000..bd5a8b23 --- /dev/null +++ b/scripts/restart.cmd @@ -0,0 +1,4 @@ +@echo off +rem Windows wrapper for scripts/hooks.ps1 (restart). +powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0hooks.ps1" -Mode restart %* +exit /b %ERRORLEVEL% diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100644 index 00000000..a109e6ca --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,23 @@ +#!/bin/sh +# Restart API and every state store without deleting volumes. +# +# Used by make test-persistence. Sessions live in Valkey with AOF and users, +# chats and messages in PostgreSQL, so the same bearer token and data survive. +set -eu +stack=${STACK_NAME:-lab4} +for service in "${stack}_postgres" "${stack}_valkey" "${stack}_minio" "${stack}_api" "${stack}_traefik"; do + printf 'restarting %s\n' "$service" + docker service update --force "$service" >/dev/null +done + +i=0 +while [ "$i" -lt 60 ]; do + if curl -fsS http://127.0.0.1:8080/health/ready >/dev/null 2>&1; then + printf 'stack ready after restart\n' + exit 0 + fi + i=$((i + 1)) + sleep 2 +done +printf 'stack did not become ready within 120s\n' >&2 +exit 1 diff --git a/scripts/restore.cmd b/scripts/restore.cmd new file mode 100644 index 00000000..0d72b653 --- /dev/null +++ b/scripts/restore.cmd @@ -0,0 +1,4 @@ +@echo off +rem Windows wrapper for scripts/hooks.ps1 (restore). +powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0hooks.ps1" -Mode restore %* +exit /b %ERRORLEVEL% diff --git a/scripts/restore.sh b/scripts/restore.sh new file mode 100644 index 00000000..a7175a02 --- /dev/null +++ b/scripts/restore.sh @@ -0,0 +1,27 @@ +#!/bin/sh +# Restore the API service to 2 replicas after scripts/stop-one.sh. +set -eu +stack=${STACK_NAME:-lab4} +service="${stack}_api" + +# Swarm normally creates the replacement itself after stopping one task. This hook +# restores the declared replica count and waits for two healthy tasks; a forced +# rolling update is used only when the service is still under-replicated. +docker service update --restart-condition any --replicas 2 "$service" >/dev/null +running=$(docker service ps -q "$service" --filter desired-state=running | wc -l | tr -d ' ') +if [ "$running" -lt 2 ]; then + docker service update --force "$service" >/dev/null +fi + +i=0 +while [ "$i" -lt 60 ]; do + running=$(docker service ps -q "$service" --filter desired-state=running | wc -l | tr -d ' ') + if [ "$running" -ge 2 ] && curl -fsS http://127.0.0.1:8080/health/ready >/dev/null 2>&1; then + printf 'api restored: %s running tasks and readiness OK\n' "$running" + exit 0 + fi + i=$((i + 1)) + sleep 2 +done +printf 'api did not recover within 120s\n' >&2 +exit 1 \ No newline at end of file diff --git a/scripts/rolling-update.cmd b/scripts/rolling-update.cmd new file mode 100644 index 00000000..62f46a43 --- /dev/null +++ b/scripts/rolling-update.cmd @@ -0,0 +1,4 @@ +@echo off +rem Windows wrapper for scripts/hooks.ps1 (rollout). +powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0hooks.ps1" -Mode rollout %* +exit /b %ERRORLEVEL% diff --git a/scripts/rolling-update.sh b/scripts/rolling-update.sh new file mode 100644 index 00000000..6f682bfa --- /dev/null +++ b/scripts/rolling-update.sh @@ -0,0 +1,20 @@ +#!/bin/sh +# Start-first rolling update of the API service under load. +# +# Swarm replaces one task at a time (parallelism 1), waiting for the new task's +# health check before removing the old one. Traefik keeps routing to ready tasks. +set -eu +root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd) +cd "$root" +stack=${STACK_NAME:-lab4} +image=${API_IMAGE:-mtusi-messenger-lab4:4.0.1} + +docker build --build-arg APP_REVISION="$image" -t "$image" . +docker service update \ + --image "$image" \ + --update-order start-first \ + --update-parallelism 1 \ + --update-delay 5s \ + --update-failure-action rollback \ + "${stack}_api" +docker service ps "${stack}_api" --no-trunc \ No newline at end of file diff --git a/scripts/stop-one.cmd b/scripts/stop-one.cmd new file mode 100644 index 00000000..a7838d62 --- /dev/null +++ b/scripts/stop-one.cmd @@ -0,0 +1,4 @@ +@echo off +rem Windows wrapper for scripts/hooks.ps1 (stop-one). +powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0hooks.ps1" -Mode stop-one %* +exit /b %ERRORLEVEL% diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100644 index 00000000..bb010e3d --- /dev/null +++ b/scripts/stop-one.sh @@ -0,0 +1,50 @@ +#!/bin/sh +# Stop exactly one API replica selected by TARGET_INSTANCE_ID. +# +# The public failover test sets TARGET_INSTANCE_ID to the X-Instance-Id that served +# the test request. In this stack X-Instance-Id is the container hostname, so the +# target task is found by inspecting every running task's container and stopped by +# container id. Swarm then creates a *new* task (new hostname) after its restart +# delay: the laboratory explicitly allows that, and the test checks that the old +# X-Instance-Id disappears from responses. Restore with scripts/restore.sh. +set -eu + +stack=${STACK_NAME:-lab4} +service="${stack}_api" +target=${TARGET_INSTANCE_ID:-} +if [ -z "$target" ]; then + printf 'TARGET_INSTANCE_ID is required\n' >&2 + exit 2 +fi + +if ! docker service inspect "$service" >/dev/null 2>&1; then + printf 'service %s not found\n' "$service" >&2 + exit 3 +fi + +find_container() { + # Prints the container id whose hostname equals $target; empty if not found. + for task in $(docker service ps -q "$service" --filter desired-state=running); do + container=$(docker inspect -f '{{.Status.ContainerStatus.ContainerID}}' "$task" 2>/dev/null || true) + [ -n "$container" ] || continue + hostname=$(docker inspect -f '{{.Config.Hostname}}' "$container" 2>/dev/null || true) + if [ "$hostname" = "$target" ]; then + printf '%s\n' "$container" + return 0 + fi + done + return 0 +} + +container=$(find_container) +if [ -z "$container" ]; then + printf 'target instance %s not found among running tasks\n' "$target" >&2 + exit 4 +fi + +printf 'stopping instance %s container %s\n' "$target" "$container" +docker stop --time 15 "$container" >/dev/null + +# Swarm may already be creating a replacement task with a different hostname; +# the target container itself was stopped by id and is no longer served. +printf 'instance %s stopped\n' "$target" \ No newline at end of file diff --git a/src/messenger/__init__.py b/src/messenger/__init__.py new file mode 100644 index 00000000..0abe74c3 --- /dev/null +++ b/src/messenger/__init__.py @@ -0,0 +1,5 @@ +"""Мессенджер на PostgreSQL, Valkey и S3: лабораторная 4 курса HighLoad (MTUSI).""" + +__all__ = ["__version__"] + +__version__ = "4.0.0" \ No newline at end of file diff --git a/src/messenger/__main__.py b/src/messenger/__main__.py new file mode 100644 index 00000000..df116f9f --- /dev/null +++ b/src/messenger/__main__.py @@ -0,0 +1,38 @@ +"""Точка входа: `python -m messenger` (в контейнере — PID 1).""" +from __future__ import annotations + +import sys + +import uvicorn + +from .app import create_app +from .config import Config, ConfigError + + +def main() -> int: + try: + config = Config.from_env() + except ConfigError as exc: + print(f"config error: {exc}", file=sys.stderr) + return 2 + + uvicorn.run( + create_app(config), + host=config.host, + port=config.port, + # Свой формат логов: uvicorn не пишет access-лог с query-строкой. + log_config=None, + access_log=False, + # Верхняя граница ожидания активных запросов при остановке. + timeout_graceful_shutdown=config.graceful_shutdown_seconds, + # Один процесс: лимиты пула соединений заданы на процесс, а не на весь стенд. + workers=1, + server_header=False, + date_header=False, + proxy_headers=False, + ) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/src/messenger/access.py b/src/messenger/access.py new file mode 100644 index 00000000..a03d541e --- /dev/null +++ b/src/messenger/access.py @@ -0,0 +1,16 @@ +"""Правила доступа: чужой объект неотличим от отсутствующего (404, не 403).""" +from __future__ import annotations + +from uuid import UUID + +from .domain import ChatRecord, UserRecord +from .errors import not_found +from .repository import Repository + + +async def visible_chat(repository: Repository, chat_id: UUID, user: UserRecord) -> ChatRecord: + """Возвращает чат, если пользователь его участник, иначе 404.""" + chat = await repository.chat_for_member(chat_id, user.id) + if chat is None: + raise not_found("Чат не найден") + return chat diff --git a/src/messenger/app.py b/src/messenger/app.py new file mode 100644 index 00000000..6cc97deb --- /dev/null +++ b/src/messenger/app.py @@ -0,0 +1,142 @@ +"""Сборка ASGI-приложения: жизненный цикл, обработчики ошибок, маршруты.""" +from __future__ import annotations + +import asyncio +import logging +from contextlib import asynccontextmanager +from typing import AsyncIterator, Awaitable, Callable + +from fastapi import FastAPI + +from . import __version__ +from .config import Config +from .cursor import CursorCodec +from .db import Database +from .errorhandlers import register_error_handlers +from .logging_setup import configure_logging, log +from .middleware import RequestContextMiddleware +from .routers import attachments, auth, chats, health, messages, users +from .sessions import RedisSessionStore +from .storage import S3Storage + +ROUTERS = ( + health.router, + auth.router, + users.router, + chats.router, + messages.router, + attachments.router, +) + + +async def _release( + logger: logging.Logger, resource: str, closer: Callable[[], Awaitable[None]] +) -> None: + """Освобождает ресурс: отказ зависимости при остановке не должен мешать выходу.""" + try: + await closer() + except Exception as exc: + log( + logger, + logging.WARNING, + "release_failed", + exc_info=exc, + resource=resource, + error=type(exc).__name__, + ) + + +def build_fastapi(config: Config, logger: logging.Logger) -> FastAPI: + """Создаёт приложение FastAPI с обработчиками ошибок и маршрутами.""" + + @asynccontextmanager + async def lifespan(app: FastAPI) -> AsyncIterator[None]: + # Клиенты создаются здесь, но к зависимостям не подключаются: старт не + # должен падать, если PostgreSQL или Valkey поднимаются одновременно с API. + # За трафик отвечает готовность, а не перезапуск контейнера. + database = Database(config) + sessions = RedisSessionStore( + config.cache_url, config.session_ttl_seconds, config.cache_timeout_seconds + ) + storage = S3Storage(config) + app.state.database = database + app.state.sessions = sessions + app.state.storage = storage + app.state.config = config + app.state.cursors = CursorCodec(config.cursor_secret) + app.state.draining = False + log( + logger, + logging.INFO, + "startup", + version=__version__, + host=config.host, + port=config.port, + shutdown_budget_seconds=config.shutdown_budget_seconds, + storage="postgresql+s3", + s3_bucket=config.s3_bucket, + max_upload_bytes=config.max_upload_bytes, + max_image_pixels=config.max_image_pixels, + instance_id=config.instance_id, + session_store=config.session_store, + session_ttl_seconds=config.session_ttl_seconds, + db_pool_size=config.db_pool_size, + db_max_overflow=config.db_max_overflow, + db_pool_timeout_seconds=config.db_pool_timeout_seconds, + db_connect_timeout_seconds=config.db_connect_timeout_seconds, + db_command_timeout_seconds=config.db_command_timeout_seconds, + db_statement_timeout_ms=config.db_statement_timeout_ms, + cache_timeout_seconds=config.cache_timeout_seconds, + ) + if config.binds_to_loopback: + # Bind на loopback внутри контейнера не виден через published port. + log( + logger, + logging.WARNING, + "loopback_bind", + detail="bind на loopback недоступен через published port контейнера", + ) + try: + yield + finally: + app.state.draining = True + log( + logger, + logging.INFO, + "shutdown_begin", + drain_seconds=config.shutdown_drain_seconds, + note="слушающий сокет уже закрыт: новые соединения не принимаются", + ) + if config.shutdown_drain_seconds > 0: + # Окно управляемого снятия с балансировки: процесс ещё жив, + # но трафик на него уже не идёт. + await asyncio.sleep(config.shutdown_drain_seconds) + await _release(logger, "storage", storage.close) + await _release(logger, "sessions", sessions.close) + await _release(logger, "database", database.dispose) + app.state.draining = False + log(logger, logging.INFO, "shutdown_complete") + + app = FastAPI( + title="MTUSI Messenger — лабораторная 4", + version=__version__, + lifespan=lifespan, + # Источник истины — contracts/openapi.json: свои /docs и /openapi.json не публикуются. + docs_url=None, + redoc_url=None, + openapi_url=None, + ) + register_error_handlers(app, logger) + for router in ROUTERS: + app.include_router(router) + return app + + +def create_app( + config: Config | None = None, + logger: logging.Logger | None = None, +) -> RequestContextMiddleware: + """Создаёт приложение; разбор окружения идёт здесь, а не при импорте модуля.""" + config = Config.from_env() if config is None else config + logger = configure_logging(config.log_level, config.env) if logger is None else logger + return RequestContextMiddleware(build_fastapi(config, logger), logger, config.instance_id) \ No newline at end of file diff --git a/src/messenger/config.py b/src/messenger/config.py new file mode 100644 index 00000000..1c4c9819 --- /dev/null +++ b/src/messenger/config.py @@ -0,0 +1,283 @@ +"""Конфигурация процесса: значения приходят только из переменных окружения. + +Секреты читаются либо напрямую (NAME), либо из файла (NAME_FILE) — второй +вариант используется стендом Swarm и Docker secrets. Значения секретов +никогда не попадают в текст ошибки. +""" +from __future__ import annotations + +import hashlib +import os +import re +import socket +import uuid +from dataclasses import dataclass +from pathlib import Path +from typing import Mapping + +DEFAULT_HOST = "0.0.0.0" +DEFAULT_PORT = 8080 +DEFAULT_ENV = "lab" +DEFAULT_LOG_LEVEL = "info" +DEFAULT_GRACEFUL_SHUTDOWN_SECONDS = 5 +DEFAULT_SHUTDOWN_DRAIN_SECONDS = 0.0 + +MAX_SHUTDOWN_BUDGET_SECONDS = 10 + +DEFAULT_SESSION_TTL_SECONDS = 3600 +MIN_SESSION_TTL_SECONDS = 1 +MAX_SESSION_TTL_SECONDS = 86400 + +DEFAULT_DB_POOL_SIZE = 5 +MAX_DB_POOL_SIZE = 32 +DEFAULT_DB_MAX_OVERFLOW = 5 +MAX_DB_MAX_OVERFLOW = 32 +DEFAULT_DB_POOL_TIMEOUT_SECONDS = 2.0 +MAX_DB_POOL_TIMEOUT_SECONDS = 30.0 +DEFAULT_DB_CONNECT_TIMEOUT_SECONDS = 1.5 +MAX_DB_CONNECT_TIMEOUT_SECONDS = 30.0 +DEFAULT_DB_COMMAND_TIMEOUT_SECONDS = 2.5 +MAX_DB_COMMAND_TIMEOUT_SECONDS = 60.0 +DEFAULT_DB_STATEMENT_TIMEOUT_MS = 2000 +MAX_DB_STATEMENT_TIMEOUT_MS = 60000 + +DEFAULT_CACHE_TIMEOUT_SECONDS = 1.0 +MAX_CACHE_TIMEOUT_SECONDS = 10.0 + +# Контракт лабораторной 4 фиксирует эти два предела; переменные окружения +# позволяют выбрать меньший предел для эксперимента, но не больший. +MAX_UPLOAD_BYTES_HARD_LIMIT = 10_485_760 +MAX_IMAGE_PIXELS_HARD_LIMIT = 40_000_000 +DEFAULT_MAX_UPLOAD_BYTES = MAX_UPLOAD_BYTES_HARD_LIMIT +DEFAULT_MAX_IMAGE_PIXELS = MAX_IMAGE_PIXELS_HARD_LIMIT + +DEFAULT_S3_REGION = "us-east-1" +DEFAULT_S3_BUCKET = "messenger-attachments" +DEFAULT_S3_KEY_PREFIX = "attachments/" +DEFAULT_S3_CONNECT_TIMEOUT_SECONDS = 1.5 +DEFAULT_S3_READ_TIMEOUT_SECONDS = 30.0 +DEFAULT_S3_MAX_ATTEMPTS = 2 +MAX_S3_READ_TIMEOUT_SECONDS = 120.0 +DEFAULT_ATTACHMENT_ORPHAN_GRACE_SECONDS = 3600 +MAX_ATTACHMENT_ORPHAN_GRACE_SECONDS = 7 * 24 * 3600 + +ENVIRONMENTS = ("lab", "dev", "prod") +LOG_LEVELS = ("debug", "info", "warning", "error") + +SESSION_STORES = ("redis",) +DEFAULT_SESSION_STORE = "redis" + +DATABASE_URL_SCHEME = "postgresql+asyncpg://" +CACHE_URL_SCHEMES = ("redis://", "rediss://", "unix://") + +LOOPBACK_HOSTS = ("127.0.0.1", "localhost", "::1") + +INSTANCE_ID_PATTERN = re.compile(r"^[A-Za-z0-9._:-]{1,128}$") +BUCKET_PATTERN = re.compile(r"^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$") +KEY_PREFIX_PATTERN = re.compile(r"^[A-Za-z0-9._/-]{0,128}$") + +FAULT_MODES = ("none", "after_s3_put") + + +class ConfigError(RuntimeError): + """Некорректная конфигурация. Текст не раскрывает значений переменных.""" + + +def _choice(environ: Mapping[str, str], name: str, default: str, allowed: tuple[str, ...]) -> str: + value = environ.get(name, default).strip().lower() + if value not in allowed: + raise ConfigError(f"{name} must be one of: {', '.join(allowed)}") + return value + + +def _integer(environ: Mapping[str, str], name: str, default: int, minimum: int, maximum: int) -> int: + raw = environ.get(name, "").strip() + if not raw: + return default + try: + value = int(raw) + except ValueError: + raise ConfigError(f"{name} must be an integer") from None + if not minimum <= value <= maximum: + raise ConfigError(f"{name} must be within {minimum}..{maximum}") + return value + + +def _seconds(environ: Mapping[str, str], name: str, default: float, maximum: float) -> float: + raw = environ.get(name, "").strip() + if not raw: + return default + try: + value = float(raw) + except ValueError: + raise ConfigError(f"{name} must be a number of seconds") from None + if not 0.0 <= value <= maximum: + raise ConfigError(f"{name} must be within 0..{maximum}") + return value + + +def _secret(environ: Mapping[str, str], name: str) -> str | None: + direct = environ.get(name, "").strip() + path = environ.get(f"{name}_FILE", "").strip() + if direct and path: + raise ConfigError(f"{name} and {name}_FILE must not be set together") + if direct: + return direct + if not path: + return None + try: + value = Path(path).read_text(encoding="utf-8").strip() + except OSError: + raise ConfigError(f"{name}_FILE must point to a readable file") from None + if not value: + raise ConfigError(f"{name}_FILE must not be empty") + return value + + +def _required_secret(environ: Mapping[str, str], name: str) -> str: + value = _secret(environ, name) + if value is None: + raise ConfigError(f"{name} or {name}_FILE is required") + return value + + +def _checked_url(value: str, *, name: str, schemes: tuple[str, ...]) -> str: + if not value.startswith(schemes): + raise ConfigError(f"{name} must start with one of: {', '.join(schemes)}") + return value + + +def database_url_from_env(environ: Mapping[str, str] | None = None) -> str: + source: Mapping[str, str] = os.environ if environ is None else environ + return _checked_url( + _required_secret(source, "DATABASE_URL"), + name="DATABASE_URL", + schemes=(DATABASE_URL_SCHEME,), + ) + + +def instance_id_from_env(environ: Mapping[str, str]) -> str: + raw = environ.get("INSTANCE_ID", "").strip() or socket.gethostname().strip() + if not raw: + raw = "api-" + uuid.uuid4().hex[:12] + if INSTANCE_ID_PATTERN.fullmatch(raw): + return raw + return "api-" + hashlib.sha256(raw.encode("utf-8")).hexdigest()[:16] + + +@dataclass(frozen=True) +class Config: + host: str + port: int + env: str + instance_id: str + log_level: str + graceful_shutdown_seconds: int + shutdown_drain_seconds: float + database_url: str + cache_url: str + session_store: str + session_ttl_seconds: int + db_pool_size: int + db_max_overflow: int + db_pool_timeout_seconds: float + db_connect_timeout_seconds: float + db_command_timeout_seconds: float + db_statement_timeout_ms: int + cache_timeout_seconds: float + cursor_secret: bytes | None + s3_endpoint: str + s3_region: str + s3_bucket: str + s3_key_prefix: str + s3_access_key_id: str + s3_secret_access_key: str + s3_connect_timeout_seconds: float + s3_read_timeout_seconds: float + s3_max_attempts: int + max_upload_bytes: int + max_image_pixels: int + attachment_orphan_grace_seconds: int + attachment_fault_mode: str + + def __post_init__(self) -> None: + if self.shutdown_budget_seconds > MAX_SHUTDOWN_BUDGET_SECONDS: + raise ConfigError( + "GRACEFUL_SHUTDOWN_SECONDS + SHUTDOWN_DRAIN_SECONDS must be " + f"at most {MAX_SHUTDOWN_BUDGET_SECONDS} seconds" + ) + if not self.s3_endpoint.startswith(("http://", "https://")): + raise ConfigError("S3_ENDPOINT must start with http:// or https://") + if not BUCKET_PATTERN.fullmatch(self.s3_bucket): + raise ConfigError("S3_BUCKET must be a valid S3 bucket name") + if not KEY_PREFIX_PATTERN.fullmatch(self.s3_key_prefix) or ".." in self.s3_key_prefix: + raise ConfigError("S3_KEY_PREFIX is not a safe object prefix") + + @property + def shutdown_budget_seconds(self) -> float: + return self.graceful_shutdown_seconds + self.shutdown_drain_seconds + + @property + def binds_to_loopback(self) -> bool: + return self.host in LOOPBACK_HOSTS + + @classmethod + def from_env(cls, environ: Mapping[str, str] | None = None) -> "Config": + source: Mapping[str, str] = os.environ if environ is None else environ + env = _choice(source, "APP_ENV", DEFAULT_ENV, ENVIRONMENTS) + host = source.get("APP_HOST", DEFAULT_HOST).strip() + if not host: + raise ConfigError("APP_HOST must not be empty") + default_log_level = "debug" if env == "dev" else DEFAULT_LOG_LEVEL + database_url = database_url_from_env(source) + cache_url = _checked_url( + _required_secret(source, "CACHE_URL"), + name="CACHE_URL", + schemes=CACHE_URL_SCHEMES, + ) + cursor_secret = _secret(source, "CURSOR_SECRET") + fault_mode = _choice(source, "ATTACHMENT_FAULT_MODE", "none", FAULT_MODES) + if env == "prod" and fault_mode != "none": + raise ConfigError("ATTACHMENT_FAULT_MODE must be none in prod") + key_prefix = source.get("S3_KEY_PREFIX", DEFAULT_S3_KEY_PREFIX).strip() or DEFAULT_S3_KEY_PREFIX + return cls( + host=host, + port=_integer(source, "APP_PORT", DEFAULT_PORT, 1, 65535), + env=env, + instance_id=instance_id_from_env(source), + log_level=_choice(source, "LOG_LEVEL", default_log_level, LOG_LEVELS), + graceful_shutdown_seconds=_integer( + source, "GRACEFUL_SHUTDOWN_SECONDS", DEFAULT_GRACEFUL_SHUTDOWN_SECONDS, 1, 10 + ), + shutdown_drain_seconds=_seconds( + source, "SHUTDOWN_DRAIN_SECONDS", DEFAULT_SHUTDOWN_DRAIN_SECONDS, 5.0 + ), + database_url=database_url, + cache_url=cache_url, + session_store=_choice(source, "SESSION_STORE", DEFAULT_SESSION_STORE, SESSION_STORES), + session_ttl_seconds=_integer( + source, "SESSION_TTL_SECONDS", DEFAULT_SESSION_TTL_SECONDS, + MIN_SESSION_TTL_SECONDS, MAX_SESSION_TTL_SECONDS, + ), + db_pool_size=_integer(source, "DB_POOL_SIZE", DEFAULT_DB_POOL_SIZE, 1, MAX_DB_POOL_SIZE), + db_max_overflow=_integer(source, "DB_MAX_OVERFLOW", DEFAULT_DB_MAX_OVERFLOW, 0, MAX_DB_MAX_OVERFLOW), + db_pool_timeout_seconds=_seconds(source, "DB_POOL_TIMEOUT_SECONDS", DEFAULT_DB_POOL_TIMEOUT_SECONDS, MAX_DB_POOL_TIMEOUT_SECONDS), + db_connect_timeout_seconds=_seconds(source, "DB_CONNECT_TIMEOUT_SECONDS", DEFAULT_DB_CONNECT_TIMEOUT_SECONDS, MAX_DB_CONNECT_TIMEOUT_SECONDS), + db_command_timeout_seconds=_seconds(source, "DB_COMMAND_TIMEOUT_SECONDS", DEFAULT_DB_COMMAND_TIMEOUT_SECONDS, MAX_DB_COMMAND_TIMEOUT_SECONDS), + db_statement_timeout_ms=_integer(source, "DB_STATEMENT_TIMEOUT_MS", DEFAULT_DB_STATEMENT_TIMEOUT_MS, 1, MAX_DB_STATEMENT_TIMEOUT_MS), + cache_timeout_seconds=_seconds(source, "CACHE_TIMEOUT_SECONDS", DEFAULT_CACHE_TIMEOUT_SECONDS, MAX_CACHE_TIMEOUT_SECONDS), + cursor_secret=None if cursor_secret is None else cursor_secret.encode("utf-8"), + s3_endpoint=_checked_url(_required_secret(source, "S3_ENDPOINT"), name="S3_ENDPOINT", schemes=("http://", "https://")), + s3_region=source.get("S3_REGION", DEFAULT_S3_REGION).strip() or DEFAULT_S3_REGION, + s3_bucket=source.get("S3_BUCKET", DEFAULT_S3_BUCKET).strip() or DEFAULT_S3_BUCKET, + s3_key_prefix=key_prefix, + s3_access_key_id=_required_secret(source, "S3_ACCESS_KEY_ID"), + s3_secret_access_key=_required_secret(source, "S3_SECRET_ACCESS_KEY"), + s3_connect_timeout_seconds=_seconds(source, "S3_CONNECT_TIMEOUT_SECONDS", DEFAULT_S3_CONNECT_TIMEOUT_SECONDS, MAX_S3_READ_TIMEOUT_SECONDS), + s3_read_timeout_seconds=_seconds(source, "S3_READ_TIMEOUT_SECONDS", DEFAULT_S3_READ_TIMEOUT_SECONDS, MAX_S3_READ_TIMEOUT_SECONDS), + s3_max_attempts=_integer(source, "S3_MAX_ATTEMPTS", DEFAULT_S3_MAX_ATTEMPTS, 1, 5), + max_upload_bytes=_integer(source, "MAX_UPLOAD_BYTES", DEFAULT_MAX_UPLOAD_BYTES, 1, MAX_UPLOAD_BYTES_HARD_LIMIT), + max_image_pixels=_integer(source, "MAX_IMAGE_PIXELS", DEFAULT_MAX_IMAGE_PIXELS, 1, MAX_IMAGE_PIXELS_HARD_LIMIT), + attachment_orphan_grace_seconds=_integer(source, "ATTACHMENT_ORPHAN_GRACE_SECONDS", DEFAULT_ATTACHMENT_ORPHAN_GRACE_SECONDS, 0, MAX_ATTACHMENT_ORPHAN_GRACE_SECONDS), + attachment_fault_mode=fault_mode, + ) diff --git a/src/messenger/context.py b/src/messenger/context.py new file mode 100644 index 00000000..78f326f4 --- /dev/null +++ b/src/messenger/context.py @@ -0,0 +1,23 @@ +"""Контекст одного HTTP-запроса: данные живут в ASGI-scope.""" +from __future__ import annotations + +from typing import Any, MutableMapping + +CONTEXT_KEY = "messenger.request_context" + +REQUEST_ID = "request_id" +USER_ID = "user_id" + + +def context_of(scope: MutableMapping[str, Any]) -> dict[str, Any]: + """Возвращает (при необходимости создавая) словарь контекста запроса.""" + context = scope.get(CONTEXT_KEY) + if context is None: + context = {} + scope[CONTEXT_KEY] = context + return context + + +def request_context(request: Any) -> dict[str, Any]: + """Контекст по объекту Request/WebSocket.""" + return context_of(request.scope) diff --git a/src/messenger/cursor.py b/src/messenger/cursor.py new file mode 100644 index 00000000..7f55bc15 --- /dev/null +++ b/src/messenger/cursor.py @@ -0,0 +1,119 @@ +"""Keyset-курсор: подписан ключом процесса и привязан к ресурсу (kind + scope).""" +from __future__ import annotations + +import base64 +import binascii +import hashlib +import hmac +import json +import secrets +from dataclasses import dataclass +from uuid import UUID + +from .domain import Position, parse_rfc3339_z + +CURSOR_VERSION = 1 +SIGNATURE_BYTES = 16 +SEPARATOR = "." + +KIND_CHATS = "chats" +KIND_MESSAGES = "messages" + + +class InvalidCursor(ValueError): + """Курсор повреждён, подделан или выпущен для другого ресурса.""" + + +def _b64encode(raw: bytes) -> str: + return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=") + + +def _b64decode(value: str) -> bytes: + return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4)) + + +def _parse_timestamp(value: object) -> str: + """Проверяет, что метка времени — RFC 3339 UTC с суффиксом Z.""" + if not isinstance(value, str): + raise InvalidCursor("cursor timestamp is not a string") + try: + parse_rfc3339_z(value) + except ValueError: + raise InvalidCursor("cursor timestamp is not RFC 3339 UTC with Z suffix") from None + return value + + +@dataclass(frozen=True) +class Cursor: + """Позиция последнего отданного элемента выборки.""" + + kind: str + scope: str + created_at: str + item_id: str + + @property + def position(self) -> Position: + """Место в порядке (created_at, id), с которого продолжается выборка.""" + return (parse_rfc3339_z(self.created_at), UUID(self.item_id)) + + +class CursorCodec: + """Кодирует и проверяет курсоры ключом, известным только процессу.""" + + def __init__(self, key: bytes | None = None) -> None: + self._key = secrets.token_bytes(32) if key is None else key + + def encode(self, kind: str, scope: str, created_at: str, item_id: str) -> str: + payload = json.dumps( + { + "v": CURSOR_VERSION, + "kind": kind, + "scope": scope, + "created_at": created_at, + "id": item_id, + }, + ensure_ascii=False, + separators=(",", ":"), + sort_keys=True, + ).encode("utf-8") + signature = hmac.new(self._key, payload, hashlib.sha256).digest()[:SIGNATURE_BYTES] + return _b64encode(payload) + SEPARATOR + _b64encode(signature) + + def decode(self, token: str, *, kind: str, scope: str) -> Cursor: + """Разбирает курсор или поднимает InvalidCursor — наружу это всегда 400.""" + if not isinstance(token, str) or not token: + raise InvalidCursor("cursor is empty") + encoded_payload, separator, encoded_signature = token.partition(SEPARATOR) + if not separator: + raise InvalidCursor("cursor has no signature part") + try: + payload = _b64decode(encoded_payload) + signature = _b64decode(encoded_signature) + except (binascii.Error, ValueError): + raise InvalidCursor("cursor is not valid base64url") from None + + expected = hmac.new(self._key, payload, hashlib.sha256).digest()[:SIGNATURE_BYTES] + if not hmac.compare_digest(signature, expected): + raise InvalidCursor("cursor signature mismatch") + + try: + data = json.loads(payload.decode("utf-8")) + except (UnicodeDecodeError, ValueError): + raise InvalidCursor("cursor payload is not valid JSON") from None + if not isinstance(data, dict) or data.get("v") != CURSOR_VERSION: + raise InvalidCursor("unsupported cursor version") + + cursor = Cursor( + kind=str(data.get("kind", "")), + scope=str(data.get("scope", "")), + created_at=_parse_timestamp(data.get("created_at")), + item_id=str(data.get("id", "")), + ) + try: + UUID(cursor.item_id) + except ValueError: + raise InvalidCursor("cursor id is not a UUID") from None + if cursor.kind != kind or cursor.scope != scope: + raise InvalidCursor("cursor belongs to another resource") + return cursor diff --git a/src/messenger/db.py b/src/messenger/db.py new file mode 100644 index 00000000..a03d7d57 --- /dev/null +++ b/src/messenger/db.py @@ -0,0 +1,74 @@ +"""Асинхронный доступ к PostgreSQL: движок, ограниченный пул и таймауты.""" +from __future__ import annotations + +from contextlib import asynccontextmanager +from typing import AsyncIterator + +from sqlalchemy import text +from sqlalchemy.exc import ProgrammingError +from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine + +from .config import Config + +APPLICATION_NAME = "messenger" + +# Незакоммиченная транзакция не должна держать соединение пула бесконечно. +IDLE_IN_TRANSACTION_TIMEOUT_MS = 10000 + + +class Database: + """Владеет пулом соединений; сессия живёт ровно один HTTP-запрос.""" + + def __init__(self, config: Config) -> None: + self._engine: AsyncEngine = create_async_engine( + config.database_url, + # Пул ограничен: лишние запросы ждут освобождения соединения. + pool_size=config.db_pool_size, + max_overflow=config.db_max_overflow, + pool_timeout=config.db_pool_timeout_seconds, + pool_pre_ping=True, + pool_recycle=1800, + connect_args={ + # Границы на круг asyncpg, на установление соединения (включая + # разрешение имени) и на стороне сервера. + "timeout": config.db_connect_timeout_seconds, + "command_timeout": config.db_command_timeout_seconds, + "server_settings": { + "application_name": APPLICATION_NAME, + "statement_timeout": str(config.db_statement_timeout_ms), + "idle_in_transaction_session_timeout": str(IDLE_IN_TRANSACTION_TIMEOUT_MS), + }, + }, + ) + self._sessions = async_sessionmaker(self._engine, expire_on_commit=False) + + @asynccontextmanager + async def session(self) -> AsyncIterator[AsyncSession]: + """Сессия на один запрос: закрывается всегда, откат делает SQLAlchemy.""" + session = self._sessions() + try: + yield session + finally: + await session.close() + + async def ping(self) -> None: + """Проверка готовности: одно дешёвое обращение к серверу.""" + async with self.session() as session: + await session.execute(text("SELECT 1")) + + async def schema_revision(self) -> str | None: + """Текущая ревизия Alembic; None, если таблицы версий ещё нет. + + До завершения однократной миграции API обязан быть неготовым, иначе + Traefik отправит трафик на процесс, который не может писать в схему. + Отсутствие таблицы — это не отказ соединения, а нормальное состояние + холодного старта, поэтому исключение гасится здесь. + """ + async with self.session() as session: + try: + return await session.scalar(text("SELECT version_num FROM alembic_version")) + except ProgrammingError: + return None + + async def dispose(self) -> None: + await self._engine.dispose() \ No newline at end of file diff --git a/src/messenger/deps.py b/src/messenger/deps.py new file mode 100644 index 00000000..ccb101f4 --- /dev/null +++ b/src/messenger/deps.py @@ -0,0 +1,133 @@ +"""Зависимости FastAPI: PostgreSQL, хранилище сессий и текущий пользователь. + +Личность в этой работе определяется только сессией: заголовок X-User-Id из ЛР1 +не читается нигде и не влияет на ответ. +""" +from __future__ import annotations + +from collections.abc import AsyncIterator +from dataclasses import dataclass +from typing import Annotated + +from fastapi import Depends, Header, Request +from sqlalchemy.ext.asyncio import AsyncSession + +from .config import Config +from .context import USER_ID, request_context +from .cursor import CursorCodec +from .db import Database +from .domain import UserRecord +from .errors import BASIC_CHALLENGE, unauthorized +from .repository import Repository +from .security import parse_basic, parse_bearer +from .sessions import SessionStore +from .storage import S3Storage + +AUTHORIZATION_HEADER = "Authorization" + + +@dataclass(frozen=True) +class BasicCredentials: + """Разобранные учётные данные входа по Basic.""" + + username: str + password: str + + +def get_database(request: Request) -> Database: + """Пул соединений живёт в состоянии приложения: один на процесс.""" + return request.app.state.database + + +def get_sessions(request: Request) -> SessionStore: + """Хранилище сессий живёт в состоянии приложения.""" + return request.app.state.sessions + + +def get_cursors(request: Request) -> CursorCodec: + """Кодек курсоров привязан к процессу: ключ подписи не покидает память.""" + return request.app.state.cursors + + +def get_config(request: Request) -> Config: + """Разобранная конфигурация процесса живёт в состоянии приложения.""" + return request.app.state.config + + +def get_storage(request: Request) -> S3Storage: + """S3-клиент один на процесс; байты не проходят через PostgreSQL.""" + return request.app.state.storage + + +DatabaseDep = Annotated[Database, Depends(get_database)] +SessionsDep = Annotated[SessionStore, Depends(get_sessions)] +CursorsDep = Annotated[CursorCodec, Depends(get_cursors)] +ConfigDep = Annotated[Config, Depends(get_config)] +StorageDep = Annotated[S3Storage, Depends(get_storage)] + + +async def get_db_session(database: DatabaseDep) -> AsyncIterator[AsyncSession]: + """Сессия БД на один запрос: закрывается вместе с ответом.""" + async with database.session() as session: + yield session + + +DbSession = Annotated[AsyncSession, Depends(get_db_session)] + + +def get_repository(session: DbSession) -> Repository: + """Репозиторий поверх сессии запроса: всё SQL живёт в нём.""" + return Repository(session) + + +RepositoryDep = Annotated[Repository, Depends(get_repository)] + + +def basic_credentials( + authorization: Annotated[str | None, Header(alias=AUTHORIZATION_HEADER)] = None, +) -> BasicCredentials: + """Учётные данные входа: единственное место, где принимается схема Basic.""" + parsed = parse_basic(authorization) + if parsed is None: + raise unauthorized("Требуется Basic-аутентификация", challenge=BASIC_CHALLENGE) + return BasicCredentials(username=parsed[0], password=parsed[1]) + + +BasicCredentialsDep = Annotated[BasicCredentials, Depends(basic_credentials)] + + +def bearer_token( + authorization: Annotated[str | None, Header(alias=AUTHORIZATION_HEADER)] = None, +) -> str: + """Токен сессии из заголовка Authorization; иначе 401 с Bearer-челленджем.""" + token = parse_bearer(authorization) + if token is None: + raise unauthorized("Требуется Bearer-токен сессии") + return token + + +BearerToken = Annotated[str, Depends(bearer_token)] + + +async def get_current_user( + request: Request, + sessions: SessionsDep, + repository: RepositoryDep, + token: BearerToken, +) -> UserRecord: + """Владелец действующей сессии. + + Порядок важен: сначала сессия в Valkey, потом пользователь в PostgreSQL. + Неизвестный или истёкший токен — это 401, а не «анонимный доступ». + """ + state = await sessions.resolve(token) + if state is None: + raise unauthorized("Сессия не найдена или истекла") + user = await repository.get_user(state.user_id) + if user is None: + raise unauthorized("Владелец сессии больше не существует") + request_context(request)[USER_ID] = str(user.id) + return user + + +CurrentUser = Annotated[UserRecord, Depends(get_current_user)] diff --git a/src/messenger/domain.py b/src/messenger/domain.py new file mode 100644 index 00000000..9b5c5c8f --- /dev/null +++ b/src/messenger/domain.py @@ -0,0 +1,109 @@ +"""Сущности предметной области, порядок сортировки и формат метки времени.""" +from __future__ import annotations + +from dataclasses import dataclass, field +from datetime import datetime, timezone +from typing import Protocol, Sequence +from uuid import UUID + + +def utc_now() -> datetime: + return datetime.now(timezone.utc) + + +def rfc3339_z(moment: datetime) -> str: + """RFC 3339 в UTC с суффиксом Z и микросекундной точностью.""" + return moment.astimezone(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z") + + +def parse_rfc3339_z(value: str) -> datetime: + """Разбирает метку в формате `rfc3339_z`; иначе ValueError.""" + if not value.endswith("Z"): + raise ValueError("timestamp is not UTC with Z suffix") + return datetime.fromisoformat(value[:-1] + "+00:00") + + +class Sortable(Protocol): + """Общая часть записей: пара, по которой строится порядок и keyset-курсор.""" + + created_at: datetime + id: UUID + + +Position = tuple[datetime, UUID] + +ATTACHMENT_STATUS_PENDING = "pending" +ATTACHMENT_STATUS_READY = "ready" +ATTACHMENT_STATUS_FAILED = "failed" + + +class UsernameTaken(Exception): + """username уже занят другим пользователем.""" + + +class UnknownMembers(Exception): + """В member_ids есть идентификаторы несуществующих пользователей.""" + + def __init__(self, member_ids: Sequence[UUID]) -> None: + super().__init__("unknown members") + self.member_ids = tuple(member_ids) + + +class IdempotencyConflict(Exception): + """Тот же ключ идемпотентности использован с другим телом запроса.""" + + +class AttachmentUnknown(Exception): + """Вложение не существует, чужое или принадлежит другому чату.""" + + +class AttachmentNotReady(Exception): + """Вложение существует, но ещё не готово (pending/failed).""" + + +@dataclass(frozen=True) +class UserRecord: + id: UUID + username: str + display_name: str + created_at: datetime + + +@dataclass(frozen=True) +class ChatRecord: + id: UUID + title: str + member_ids: tuple[UUID, ...] + created_at: datetime + + def has_member(self, user_id: UUID) -> bool: + """Состав участников задаётся при создании и не меняется.""" + return user_id in self.member_ids + + +@dataclass(frozen=True) +class MessageRecord: + id: UUID + chat_id: UUID + sender_id: UUID + text: str + created_at: datetime + attachment_ids: tuple[UUID, ...] = field(default_factory=tuple) + + +@dataclass(frozen=True) +class AttachmentRecord: + """Метаданные вложения. Байты в этой записи отсутствуют принципиально.""" + + id: UUID + chat_id: UUID + owner_id: UUID + object_key: str + filename: str + content_type: str + size_bytes: int + sha256: str + status: str + error_code: str | None + created_at: datetime + updated_at: datetime diff --git a/src/messenger/errorhandlers.py b/src/messenger/errorhandlers.py new file mode 100644 index 00000000..61e923ab --- /dev/null +++ b/src/messenger/errorhandlers.py @@ -0,0 +1,184 @@ +"""Обработчики ошибок: единый конверт контракта и заголовки к нему.""" +from __future__ import annotations + +import logging +import uuid +from typing import Mapping + +from fastapi import FastAPI, Request +from fastapi.exceptions import RequestValidationError +from fastapi.responses import JSONResponse +from redis.exceptions import RedisError +from sqlalchemy.exc import DataError, DisconnectionError, InterfaceError, OperationalError +from sqlalchemy.exc import TimeoutError as PoolTimeoutError +from starlette.exceptions import HTTPException as StarletteHTTPException + +from .context import REQUEST_ID, request_context +from .errors import INTERNAL_ERROR, INVALID_REQUEST, NOT_FOUND, UNAVAILABLE, ApiError, code_for_status +from .logging_setup import log +from .storage import StorageObjectMissing, StorageUnavailable + +FALLBACK_MESSAGES: Mapping[int, str] = { + 404: "Маршрут не найден", + 405: "Метод не поддерживается для этого маршрута", +} + +# Отказ критичной зависимости (PostgreSQL или Valkey): наружу 503 без деталей, +# подробности остаются в логе. Для клиента «сессии недоступны» и «база недоступна» +# выглядят одинаково — и это правильно, различать их он не должен. +# +# Здесь только отказы соединения и исчерпание пула. Более широкий SQLAlchemyError +# сюда не годится: он включает DataError, и тогда значение, которое PostgreSQL +# не может принять, выглядело бы как недоступность базы. +DEPENDENCY_ERRORS = ( + OperationalError, + InterfaceError, + DisconnectionError, + PoolTimeoutError, + RedisError, + OSError, +) +DEPENDENCY_MESSAGE = "Сервис временно недоступен: критичная зависимость не отвечает" +DATA_ERROR_MESSAGE = "Значение поля не может быть сохранено" + + +def request_id_of(request: Request) -> str: + """Идентификатор запроса; запасной вариант — если middleware не подключён.""" + context = request_context(request) + identifier = context.get(REQUEST_ID) + if not identifier: + identifier = uuid.uuid4().hex + context[REQUEST_ID] = identifier + return identifier + + +def error_response( + request: Request, + status: int, + code: str, + message: str, + headers: Mapping[str, str] | None = None, +) -> JSONResponse: + """Собирает конверт ошибки контракта; request_id совпадает с заголовком.""" + identifier = request_id_of(request) + response_headers = {"X-Request-Id": identifier} + response_headers.update(headers or {}) + return JSONResponse( + status_code=status, + content={"error": {"code": code, "message": message, "request_id": identifier}}, + headers=response_headers, + ) + + +def describe_validation_error(exc: RequestValidationError) -> str: + """Краткое описание без значений полей: наружу уходит только расположение ошибки. + + Значения сюда не попадают намеренно: среди них может быть пароль. + """ + errors = exc.errors() + if not errors: + return "Тело запроса не соответствует контракту" + first = errors[0] + if str(first.get("type", "")) == "json_invalid": + return "Тело запроса не является корректным JSON" + location = ".".join( + str(part) + for part in first.get("loc", ()) + if part not in ("body", "query", "path", "header") + ) + return f"Некорректный запрос: {location or 'body'}" + + +def register_error_handlers(app: FastAPI, logger: logging.Logger) -> None: + """Ставит обработчики так, чтобы наружу не ушёл ответ без конверта.""" + + @app.exception_handler(ApiError) + async def handle_api_error(request: Request, exc: ApiError) -> JSONResponse: + return error_response(request, exc.status, exc.code, exc.message, exc.headers) + + @app.exception_handler(RequestValidationError) + async def handle_validation_error( + request: Request, exc: RequestValidationError + ) -> JSONResponse: + return error_response(request, 400, INVALID_REQUEST, describe_validation_error(exc)) + + @app.exception_handler(StarletteHTTPException) + async def handle_http_exception( + request: Request, exc: StarletteHTTPException + ) -> JSONResponse: + status = exc.status_code + return error_response( + request, + status, + code_for_status(status), + FALLBACK_MESSAGES.get(status, "Запрос не может быть обработан"), + getattr(exc, "headers", None), + ) + + async def handle_dependency_failure(request: Request, exc: Exception) -> JSONResponse: + log( + logger, + logging.ERROR, + "dependency_unavailable", + exc_info=exc, + request_id=request_id_of(request), + error=type(exc).__name__, + ) + return error_response(request, 503, UNAVAILABLE, DEPENDENCY_MESSAGE) + + @app.exception_handler(StorageObjectMissing) + async def handle_storage_missing(request: Request, exc: StorageObjectMissing) -> JSONResponse: + """Объект, на который ссылаются метаданные, отсутствует — 404.""" + log( + logger, + logging.WARNING, + "storage_object_missing", + request_id=request_id_of(request), + error=type(exc).__name__, + ) + return error_response(request, 404, NOT_FOUND, "Объект вложения отсутствует") + + @app.exception_handler(StorageUnavailable) + async def handle_storage_unavailable( + request: Request, exc: StorageUnavailable + ) -> JSONResponse: + """S3 недоступен: 503, детали остаются в логе.""" + log( + logger, + logging.ERROR, + "storage_unavailable", + request_id=request_id_of(request), + error=type(exc).__name__, + ) + return error_response(request, 503, UNAVAILABLE, "Хранилище вложений недоступно") + + @app.exception_handler(DataError) + async def handle_data_error(request: Request, exc: DataError) -> JSONResponse: + """Данные клиента, которые СУБД не в состоянии сохранить, — это 400. + + На границе такие значения уже отсекаются; обработчик оставлен страховкой, + чтобы ошибка данных никогда не выдавалась за отказ зависимости. + """ + log( + logger, + logging.WARNING, + "invalid_stored_value", + request_id=request_id_of(request), + error=type(exc).__name__, + ) + return error_response(request, 400, INVALID_REQUEST, DATA_ERROR_MESSAGE) + + for error_type in DEPENDENCY_ERRORS: + app.add_exception_handler(error_type, handle_dependency_failure) + + @app.exception_handler(Exception) + async def handle_unexpected(request: Request, exc: Exception) -> JSONResponse: + log( + logger, + logging.ERROR, + "unhandled_exception", + exc_info=exc, + request_id=request_id_of(request), + error=type(exc).__name__, + ) + return error_response(request, 500, INTERNAL_ERROR, "Внутренняя ошибка сервера") diff --git a/src/messenger/errors.py b/src/messenger/errors.py new file mode 100644 index 00000000..6541a70c --- /dev/null +++ b/src/messenger/errors.py @@ -0,0 +1,88 @@ +"""Ошибки API и единый конверт ответа контракта.""" +from __future__ import annotations + +from typing import Mapping + +INVALID_REQUEST = "invalid_request" +UNAUTHORIZED = "unauthorized" +NOT_FOUND = "not_found" +CONFLICT = "conflict" +PAYLOAD_TOO_LARGE = "payload_too_large" +UNSUPPORTED_MEDIA_TYPE = "unsupported_media_type" +RATE_LIMITED = "rate_limited" +UNAVAILABLE = "unavailable" +INTERNAL_ERROR = "internal_error" + +BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"' +BEARER_CHALLENGE = 'Bearer realm="messenger"' + +DEFAULT_CODE_BY_STATUS: Mapping[int, str] = { + 400: INVALID_REQUEST, + 401: UNAUTHORIZED, + 403: UNAUTHORIZED, + 404: NOT_FOUND, + 405: INVALID_REQUEST, + 409: CONFLICT, + 413: PAYLOAD_TOO_LARGE, + 415: UNSUPPORTED_MEDIA_TYPE, + 429: RATE_LIMITED, + 500: INTERNAL_ERROR, + 503: UNAVAILABLE, +} + + +class ApiError(Exception): + """Ошибка, которую можно безопасно показать клиенту в конверте контракта.""" + + def __init__( + self, + status: int, + code: str, + message: str, + headers: Mapping[str, str] | None = None, + ) -> None: + super().__init__(message) + self.status = status + self.code = code + self.message = message + self.headers = dict(headers or {}) + + +def code_for_status(status: int) -> str: + """Подбирает код конверта для статуса, пришедшего извне контракта.""" + if status in DEFAULT_CODE_BY_STATUS: + return DEFAULT_CODE_BY_STATUS[status] + return INTERNAL_ERROR if status >= 500 else INVALID_REQUEST + + +def invalid_request(message: str) -> ApiError: + return ApiError(400, INVALID_REQUEST, message) + + +def unauthorized(message: str, challenge: str = BEARER_CHALLENGE) -> ApiError: + """401 с challenge схемы: Basic — только на создании сессии, иначе Bearer.""" + return ApiError(401, UNAUTHORIZED, message, headers={"WWW-Authenticate": challenge}) + + +def not_found(message: str) -> ApiError: + """Чужой объект неотличим от отсутствующего: 403 не используется.""" + return ApiError(404, NOT_FOUND, message) + + +def conflict(message: str) -> ApiError: + return ApiError(409, CONFLICT, message) + + +def unavailable(message: str) -> ApiError: + """503: зависимость недоступна, отказ ограничен и не раскрывает внутренностей.""" + return ApiError(503, UNAVAILABLE, message) + + +def payload_too_large(message: str) -> ApiError: + """413: тело или декодированное изображение превышает контрактный предел.""" + return ApiError(413, PAYLOAD_TOO_LARGE, message) + + +def unsupported_media_type(message: str) -> ApiError: + """415: тип не PNG/JPEG или содержимое не совпало с объявленным типом.""" + return ApiError(415, UNSUPPORTED_MEDIA_TYPE, message) diff --git a/src/messenger/healthcheck.py b/src/messenger/healthcheck.py new file mode 100644 index 00000000..d0585bd0 --- /dev/null +++ b/src/messenger/healthcheck.py @@ -0,0 +1,26 @@ +"""Проверка живости для Docker HEALTHCHECK: python -m messenger.healthcheck.""" +from __future__ import annotations + +import os +import urllib.error +import urllib.request + +DEFAULT_PORT = "8080" +TIMEOUT_SECONDS = 2 + + +def liveness_url() -> str: + port = os.environ.get("APP_PORT", DEFAULT_PORT).strip() or DEFAULT_PORT + return "http://127.0.0.1:%s/health/live" % port + + +def main() -> int: + try: + with urllib.request.urlopen(liveness_url(), timeout=TIMEOUT_SECONDS) as response: + return 0 if response.status == 200 else 1 + except (urllib.error.URLError, OSError, ValueError): + return 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/src/messenger/idempotency.py b/src/messenger/idempotency.py new file mode 100644 index 00000000..f56cd9c4 --- /dev/null +++ b/src/messenger/idempotency.py @@ -0,0 +1,42 @@ +"""Идемпотентность POST сообщения: проверка ключа и канонический хэш тела.""" +from __future__ import annotations + +import hashlib +import json +import re +from collections.abc import Sequence +from uuid import UUID + +from .errors import invalid_request + +# Контракт: ASCII [A-Za-z0-9._:-]{1,128}. Полное совпадение, а не поиск. +IDEMPOTENCY_KEY_PATTERN = re.compile(r"^[A-Za-z0-9._:-]{1,128}$") + + +def require_idempotency_key(value: str | None) -> str: + """Возвращает валидный ключ или 400; отсутствие ключа — тоже 400.""" + if value is None or not IDEMPOTENCY_KEY_PATTERN.fullmatch(value): + raise invalid_request( + "Idempotency-Key обязателен и должен соответствовать [A-Za-z0-9._:-]{1,128}" + ) + return value + + +def message_request_hash(text: str, attachment_ids: Sequence[UUID] = ()) -> str: + """Хэш семантически нормализованного тела запроса. + + Порядок ключей JSON и отсутствие необязательных полей не должны менять + результат. Список вложений канонизируется как множество: порядок ссылок в + сообщении не является частью семантики запроса (порядок хранения при этом + сохраняется отдельно, в message_attachments.position). + """ + canonical = json.dumps( + { + "attachment_ids": sorted(str(item) for item in attachment_ids), + "text": text, + }, + ensure_ascii=False, + separators=(",", ":"), + sort_keys=True, + ) + return hashlib.sha256(canonical.encode("utf-8")).hexdigest() diff --git a/src/messenger/images.py b/src/messenger/images.py new file mode 100644 index 00000000..fc7fb2a5 --- /dev/null +++ b/src/messenger/images.py @@ -0,0 +1,88 @@ +"""Проверка изображения по содержимому, без доверия к Content-Type клиента.""" +from __future__ import annotations + +import struct +import warnings +from dataclasses import dataclass + +from PIL import Image, UnidentifiedImageError + +PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n" +JPEG_SIGNATURE = b"\xff\xd8\xff" + + +class UnsupportedImage(ValueError): + """Не PNG/JPEG или файл повреждён.""" + + +class ImageTooLarge(ValueError): + """Пиксельный предел контракта превышен.""" + + +@dataclass(frozen=True) +class ImageInfo: + content_type: str + width: int + height: int + + +def detect_content_type(head: bytes) -> str | None: + """MIME по первым байтам, а не по заголовку запроса.""" + if head.startswith(PNG_SIGNATURE): + return "image/png" + if head.startswith(JPEG_SIGNATURE): + return "image/jpeg" + return None + + +def inspect_image(path: str, *, expected_content_type: str, max_pixels: int) -> ImageInfo: + """Проверяет сигнатуру, формат, целостность и число пикселей. + + Размеры читаются из заголовка и проверяются до полной распаковки; для + отсечения бомб Pillow получает те же пределы, а предупреждение о бомбе + превращается в `ImageTooLarge`. Полное декодирование в этой лабораторной + не требуется: вариантов изображения нет. + """ + with open(path, "rb") as probe: + head = probe.read(len(PNG_SIGNATURE)) + detected = detect_content_type(head) + if detected is None: + raise UnsupportedImage("Содержимое не является PNG/JPEG") + if detected != expected_content_type: + raise UnsupportedImage("Content-Type не совпадает с содержимым") + + try: + with warnings.catch_warnings(): + warnings.simplefilter("error", Image.DecompressionBombWarning) + with Image.open(path) as image: + width, height = image.size + image_format = image.format + if width <= 0 or height <= 0: + raise UnsupportedImage("Некорректные размеры изображения") + if width * height > max_pixels: + raise ImageTooLarge("Изображение превышает предел пикселей") + if image_format not in ("PNG", "JPEG"): + raise UnsupportedImage("Формат изображения не PNG/JPEG") + image.verify() + except (UnsupportedImage, ImageTooLarge): + raise + except Image.DecompressionBombWarning as exc: + raise ImageTooLarge("Изображение превышает предел пикселей") from exc + except Image.DecompressionBombError as exc: + raise ImageTooLarge("Изображение превышает предел пикселей") from exc + except ( + UnidentifiedImageError, + OSError, + SyntaxError, + ValueError, + struct.error, + IndexError, + OverflowError, + ) as exc: + raise UnsupportedImage("Изображение повреждено") from exc + + if detected == "image/png" and image_format != "PNG": + raise UnsupportedImage("Расширение и формат PNG не совпали") + if detected == "image/jpeg" and image_format != "JPEG": + raise UnsupportedImage("Расширение и формат JPEG не совпали") + return ImageInfo(content_type=detected, width=width, height=height) diff --git a/src/messenger/logging_setup.py b/src/messenger/logging_setup.py new file mode 100644 index 00000000..88ee2cd1 --- /dev/null +++ b/src/messenger/logging_setup.py @@ -0,0 +1,76 @@ +"""Структурные логи в stdout: одна JSON-строка на событие, без тел и query-строки.""" +from __future__ import annotations + +import json +import logging +import sys +from datetime import datetime, timezone + + +class JsonFormatter(logging.Formatter): + """Сериализует запись лога в компактный JSON без потери структуры.""" + + def format(self, record: logging.LogRecord) -> str: + payload: dict[str, object] = { + "ts": datetime.fromtimestamp(record.created, timezone.utc) + .isoformat(timespec="milliseconds") + .replace("+00:00", "Z"), + "level": record.levelname.lower(), + "logger": record.name, + "event": record.getMessage(), + } + payload.update(getattr(record, "fields", {}) or {}) + if record.exc_info: + payload["exception"] = self.formatException(record.exc_info) + return json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + + +class _EnvironmentFilter(logging.Filter): + """Добавляет метку окружения в каждую запись, включая логи uvicorn.""" + + def __init__(self, env: str) -> None: + super().__init__() + self._env = env + + def filter(self, record: logging.LogRecord) -> bool: + fields = dict(getattr(record, "fields", {}) or {}) + fields.setdefault("env", self._env) + record.fields = fields + return True + + +def configure_logging(level: str, env: str) -> logging.Logger: + """Перенаправляет логи процесса в stdout в структурированном виде.""" + handler = logging.StreamHandler(sys.stdout) + handler.setFormatter(JsonFormatter()) + handler.addFilter(_EnvironmentFilter(env)) + + root = logging.getLogger() + root.handlers[:] = [handler] + root.setLevel(level.upper()) + + for name in ("uvicorn", "uvicorn.error", "uvicorn.access"): + logger = logging.getLogger(name) + logger.handlers[:] = [] + logger.propagate = True + logging.getLogger("uvicorn.access").setLevel(logging.WARNING) + + return logging.getLogger("messenger") + + +def log( + logger: logging.Logger, + level: int, + event: str, + exc_info: BaseException | None = None, + **fields: object, +) -> None: + """Пишет событие с произвольными структурированными полями.""" + if not logger.isEnabledFor(level): + return + logger.log( + level, + event, + extra={"fields": {k: v for k, v in fields.items() if v is not None}}, + exc_info=exc_info, + ) diff --git a/src/messenger/middleware.py b/src/messenger/middleware.py new file mode 100644 index 00000000..63b4365d --- /dev/null +++ b/src/messenger/middleware.py @@ -0,0 +1,99 @@ +"""Внешний ASGI-слой: X-Request-Id, X-Instance-Id (в том числе на 500) и access-лог.""" +from __future__ import annotations + +import logging +import re +import time +import uuid +from typing import Any, Awaitable, Callable, MutableMapping + +from .context import REQUEST_ID, USER_ID, context_of +from .logging_setup import log + +SAFE_REQUEST_ID = re.compile(r"^[A-Za-z0-9._:-]{1,128}$") + +Scope = MutableMapping[str, Any] +Message = MutableMapping[str, Any] +Receive = Callable[[], Awaitable[Message]] +Send = Callable[[Message], Awaitable[None]] +ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]] + + +def incoming_request_id(scope: Scope) -> str | None: + """Возвращает заголовок клиента, если он безопасен для логирования и ответа.""" + for name, value in scope.get("headers") or (): + if name.lower() != b"x-request-id": + continue + try: + candidate = value.decode("ascii") + except UnicodeDecodeError: + return None + return candidate if SAFE_REQUEST_ID.match(candidate) else None + return None + + +def set_response_header(message: Message, name: bytes, value: bytes) -> None: + """Идемпотентно выставляет заголовок в ASGI-сообщении ответа.""" + headers = message.setdefault("headers", []) + lowered = name.lower() + for index, (key, _) in enumerate(headers): + if key.lower() == lowered: + headers[index] = (name, value) + return + headers.append((name, value)) + + +class RequestContextMiddleware: + """Присваивает запросу идентификатор, гарантирует заголовок и пишет access-лог.""" + + def __init__(self, app: ASGIApp, logger: logging.Logger, instance_id: str) -> None: + if not instance_id: + raise ValueError("instance_id must not be empty") + self._app = app + self._logger = logger + self._instance_id = instance_id + + async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: + if scope["type"] != "http": + await self._app(scope, receive, send) + return + + request_id = incoming_request_id(scope) or uuid.uuid4().hex + context = context_of(scope) + context[REQUEST_ID] = request_id + started = time.perf_counter() + status_holder: dict[str, int] = {} + instance_id = self._instance_id.encode("ascii") + + async def send_with_request_id(message: Message) -> None: + if message["type"] == "http.response.start": + status_holder["status"] = int(message["status"]) + set_response_header(message, b"x-request-id", request_id.encode("ascii")) + # Значение стабильно на жизнь процесса; LB не переписывает его. + set_response_header(message, b"x-instance-id", instance_id) + await send(message) + + try: + await self._app(scope, receive, send_with_request_id) + finally: + self._write_access_log(scope, status_holder.get("status"), started) + + def _write_access_log(self, scope: Scope, status: int | None, started: float) -> None: + context = context_of(scope) + # Логируется шаблон маршрута, а не сырой путь: query-строка в лог не попадает. + route = getattr(scope.get("route"), "path", None) + endpoint = scope.get("endpoint") + log( + self._logger, + logging.INFO, + "request", + request_id=context.get(REQUEST_ID), + method=scope.get("method"), + route=route, + operation=None if endpoint is None else getattr(endpoint, "__name__", None), + matched=route is not None, + status=status, + duration_ms=round((time.perf_counter() - started) * 1000, 3), + user_id=context.get(USER_ID), + instance_id=self._instance_id, + ) \ No newline at end of file diff --git a/src/messenger/models.py b/src/messenger/models.py new file mode 100644 index 00000000..a0386d1a --- /dev/null +++ b/src/messenger/models.py @@ -0,0 +1,273 @@ +"""Схемы запросов и ответов ровно по contracts/openapi.json.""" +from __future__ import annotations + +from typing import Literal +from uuid import UUID + +from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator + +from .domain import AttachmentRecord, ChatRecord, MessageRecord, UserRecord, rfc3339_z +from .sessions import IssuedSession + +USERNAME_PATTERN = r"^[a-z0-9_]{3,32}$" +MIN_PASSWORD = 12 +MAX_PASSWORD = 128 +MAX_DISPLAY_NAME = 100 +MAX_TITLE = 100 +MAX_TEXT = 4000 +MAX_MEMBERS = 100 +MAX_ATTACHMENTS = 10 +MAX_LIMIT = 100 +DEFAULT_LIMIT = 50 + +ATTACHMENT_CONTENT_TYPES = ("image/png", "image/jpeg") +SHA256_PATTERN = r"^[a-f0-9]{64}$" + + +def _require_content(value: str, *, field: str) -> str: + """Обязательная строка не может быть пустой или состоять из пробельных символов.""" + if not value.strip(): + raise ValueError(f"{field} must not be empty or contain only whitespace") + return value + + +def _visible(value: str, *, field: str, maximum: int) -> str: + """Проверяет строку, которую предстоит сохранить в PostgreSQL.""" + _require_content(value, field=field) + if "\u0000" in value: + raise ValueError(f"{field} must not contain U+0000") + if len(value) > maximum: + raise ValueError(f"{field} must be at most {maximum} Unicode code points") + return value + + +class Health(BaseModel): + """Тело ответа /health/live и /health/ready.""" + + model_config = ConfigDict(extra="forbid") + + status: Literal["ok"] = "ok" + + +class User(BaseModel): + """Публичное представление пользователя: ни пароля, ни сессий здесь нет.""" + + model_config = ConfigDict(extra="forbid") + + id: UUID + username: str + display_name: str + created_at: str + + @classmethod + def from_record(cls, record: UserRecord) -> "User": + return cls( + id=record.id, + username=record.username, + display_name=record.display_name, + created_at=rfc3339_z(record.created_at), + ) + + +class CreateUser(BaseModel): + """Регистрация: пароль приходит открытым текстом и дальше живёт только как хэш.""" + + model_config = ConfigDict(extra="forbid") + + username: str = Field(pattern=USERNAME_PATTERN) + display_name: str + password: str = Field(min_length=MIN_PASSWORD, max_length=MAX_PASSWORD) + + @field_validator("display_name") + @classmethod + def _check_display_name(cls, value: str) -> str: + return _visible(value, field="display_name", maximum=MAX_DISPLAY_NAME) + + @field_validator("password") + @classmethod + def _check_password(cls, value: str) -> str: + return _require_content(value, field="password") + + +class Session(BaseModel): + """Выданная сессия: токен показывается клиенту один раз и в логи не попадает.""" + + model_config = ConfigDict(extra="forbid") + + token: str + token_type: Literal["Bearer"] = "Bearer" + expires_at: str + user: User + + @classmethod + def from_issued(cls, issued: IssuedSession, user: UserRecord) -> "Session": + return cls( + token=issued.token, + expires_at=rfc3339_z(issued.state.expires_at), + user=User.from_record(user), + ) + + +class Chat(BaseModel): + model_config = ConfigDict(extra="forbid") + + id: UUID + title: str + member_ids: list[UUID] + created_at: str + + @classmethod + def from_record(cls, record: ChatRecord) -> "Chat": + return cls( + id=record.id, + title=record.title, + member_ids=list(record.member_ids), + created_at=rfc3339_z(record.created_at), + ) + + +class CreateChat(BaseModel): + model_config = ConfigDict(extra="forbid") + + title: str + member_ids: list[UUID] + + @field_validator("title") + @classmethod + def _check_title(cls, value: str) -> str: + return _visible(value, field="title", maximum=MAX_TITLE) + + @field_validator("member_ids") + @classmethod + def _check_member_ids(cls, value: list[UUID]) -> list[UUID]: + if not 1 <= len(value) <= MAX_MEMBERS: + raise ValueError(f"member_ids must contain 1..{MAX_MEMBERS} items") + if len(set(value)) != len(value): + raise ValueError("member_ids must not contain duplicates") + return value + + +class Message(BaseModel): + model_config = ConfigDict(extra="forbid") + + id: UUID + chat_id: UUID + sender_id: UUID + text: str + created_at: str + attachment_ids: list[UUID] + + @classmethod + def from_record(cls, record: MessageRecord) -> "Message": + return cls( + id=record.id, + chat_id=record.chat_id, + sender_id=record.sender_id, + text=record.text, + created_at=rfc3339_z(record.created_at), + attachment_ids=list(record.attachment_ids), + ) + + +class CreateMessage(BaseModel): + """Поле sender_id не принимается: отправитель выводится из идентификации. + + Текст может быть пустым только при наличии хотя бы одного вложения. + """ + + model_config = ConfigDict(extra="forbid") + + text: str = Field(max_length=MAX_TEXT) + attachment_ids: list[UUID] = Field(default_factory=list, max_length=MAX_ATTACHMENTS) + + @field_validator("text") + @classmethod + def _check_text(cls, value: str) -> str: + if "\u0000" in value: + raise ValueError("text must not contain U+0000") + if len(value) > MAX_TEXT: + raise ValueError(f"text must be at most {MAX_TEXT} Unicode code points") + return value + + @field_validator("attachment_ids") + @classmethod + def _check_attachment_ids(cls, value: list[UUID]) -> list[UUID]: + if len(set(value)) != len(value): + raise ValueError("attachment_ids must not contain duplicates") + return value + + @model_validator(mode="after") + def _check_content(self) -> "CreateMessage": + if not self.text.strip() and not self.attachment_ids: + raise ValueError("text must not be empty or contain only whitespace without attachments") + return self + + +class ChatPage(BaseModel): + model_config = ConfigDict(extra="forbid") + + items: list[Chat] + next_cursor: str | None + + @classmethod + def from_records(cls, records: list[ChatRecord], next_cursor: str | None) -> "ChatPage": + return cls(items=[Chat.from_record(record) for record in records], next_cursor=next_cursor) + + +class MessagePage(BaseModel): + model_config = ConfigDict(extra="forbid") + + items: list[Message] + next_cursor: str | None + + @classmethod + def from_records(cls, records: list[MessageRecord], next_cursor: str | None) -> "MessagePage": + return cls(items=[Message.from_record(record) for record in records], next_cursor=next_cursor) + + +class Variant(BaseModel): + """Вариант изображения. В лабораторной 4 список всегда пуст, но форма + ответа описана контрактом и должна оставаться совместимой с lab5.""" + + model_config = ConfigDict(extra="forbid") + + name: Literal["thumbnail", "crop", "optimized"] + content_type: Literal["image/jpeg", "image/png", "image/webp"] + size_bytes: int = Field(gt=0) + width: int = Field(gt=0) + height: int = Field(gt=0) + sha256: str = Field(pattern=SHA256_PATTERN) + + +class Attachment(BaseModel): + model_config = ConfigDict(extra="forbid") + + id: UUID + chat_id: UUID + owner_id: UUID + filename: str = Field(min_length=1, max_length=255) + content_type: Literal["image/png", "image/jpeg"] + size_bytes: int = Field(gt=0, le=10485760) + sha256: str = Field(pattern=SHA256_PATTERN) + status: Literal["ready"] + variants: list[Variant] = Field(default_factory=list) + error_code: str | None = None + created_at: str + updated_at: str + + @classmethod + def from_record(cls, record: AttachmentRecord) -> "Attachment": + return cls( + id=record.id, + chat_id=record.chat_id, + owner_id=record.owner_id, + filename=record.filename, + content_type=record.content_type, + size_bytes=record.size_bytes, + sha256=record.sha256, + status=record.status, + variants=[], + error_code=record.error_code, + created_at=rfc3339_z(record.created_at), + updated_at=rfc3339_z(record.updated_at), + ) diff --git a/src/messenger/pagination.py b/src/messenger/pagination.py new file mode 100644 index 00000000..4a342dc2 --- /dev/null +++ b/src/messenger/pagination.py @@ -0,0 +1,38 @@ +"""Keyset-пагинация: разбор курсора клиента и сборка следующего.""" +from __future__ import annotations + +from typing import Sequence + +from .cursor import CursorCodec, InvalidCursor +from .domain import Position, Sortable, rfc3339_z +from .errors import invalid_request + + +def decoded_cursor( + cursors: CursorCodec, + token: str | None, + *, + kind: str, + scope: str, +) -> Position | None: + """Позиция из курсора клиента; None означает «начать с начала выборки».""" + if token is None: + return None + try: + return cursors.decode(token, kind=kind, scope=scope).position + except InvalidCursor: + raise invalid_request("cursor недействителен для этого запроса") from None + + +def build_next_cursor( + cursors: CursorCodec, + kind: str, + scope: str, + records: Sequence[Sortable], + has_more: bool, +) -> str | None: + """next_cursor равен null, если на момент чтения следующей записи нет.""" + if not has_more or not records: + return None + last = records[-1] + return cursors.encode(kind, scope, rfc3339_z(last.created_at), str(last.id)) diff --git a/src/messenger/reconcile.py b/src/messenger/reconcile.py new file mode 100644 index 00000000..050fef61 --- /dev/null +++ b/src/messenger/reconcile.py @@ -0,0 +1,190 @@ +"""Сверка PostgreSQL и S3: orphan-объекты, stale pending и missing ready. + +Запуск идемпотентен и по умолчанию только показывает план (`--dry-run`). +Удаление объектов и pending-строк выполняется лишь с `--apply` и только после +grace period. Ready-вложения не удаляются никогда: если объект пропал, это +авария хранилища, которую нужно разбирать, а не тихо терять метаданные. + +Пример: + python -m messenger.reconcile --dry-run + python -m messenger.reconcile --apply --grace-seconds 60 +""" +from __future__ import annotations + +import argparse +import asyncio +import json +import logging +from dataclasses import asdict, dataclass +from datetime import datetime, timedelta + +from .config import Config +from .db import Database +from .domain import AttachmentRecord, utc_now +from .repository import Repository +from .storage import ObjectInfo, S3Storage, StorageUnavailable + +logger = logging.getLogger("messenger.reconcile") + + +@dataclass(frozen=True) +class PlanItem: + kind: str + identifier: str + object_key: str | None + age_seconds: int | None + action: str + + +def build_plan( + rows: list[AttachmentRecord], + objects: list[ObjectInfo], + *, + now: datetime, + grace_seconds: int, +) -> tuple[list[PlanItem], list[PlanItem]]: + """Возвращает (план удаления/очистки, отдельно missing-ready для отчёта).""" + objects_by_key = {item.key: item for item in objects} + rows_by_key = {row.object_key: row for row in rows} + cutoff = now - timedelta(seconds=grace_seconds) + items: list[PlanItem] = [] + + # Объект без ready-строки — orphan. Pending-строка не делает объект + # используемым: клиент ещё не получил 201 и не может на него сослаться. + # Для ключа с pending-строкой план строит ветка stale_pending, чтобы не + # удалить один объект дважды и не удвоить счётчики. + for item in objects: + row = rows_by_key.get(item.key) + if row is not None: + continue + age = max(0, int((now - item.last_modified).total_seconds())) + fresh = item.last_modified >= cutoff + items.append( + PlanItem( + kind="orphan_object", + identifier=item.key, + object_key=item.key, + age_seconds=age, + action="keep_fresh" if fresh else "delete", + ) + ) + + # Pending/failed-строка без объекта или со старым объектом — мусор после + # прерванной загрузки. Строку удаляем только после grace period. + for row in rows: + if row.status == "ready": + continue + item = objects_by_key.get(row.object_key) + age = None if item is None else max(0, int((now - item.last_modified).total_seconds())) + fresh_object = item is not None and item.last_modified >= cutoff + stale_row = row.updated_at < cutoff + if not stale_row: + action = "keep_fresh" + elif item is None: + action = "delete_row" + elif fresh_object: + action = "keep_fresh" + else: + action = "delete_object_and_row" + items.append( + PlanItem( + kind="stale_pending", + identifier=str(row.id), + object_key=row.object_key, + age_seconds=age, + action=action, + ) + ) + + missing = [ + PlanItem( + kind="missing_ready", + identifier=str(row.id), + object_key=row.object_key, + age_seconds=max(0, int((now - row.updated_at).total_seconds())), + action="report_only", + ) + for row in rows + if row.status == "ready" and row.object_key not in objects_by_key + ] + return items, missing + + +async def run(args: argparse.Namespace) -> int: + config = Config.from_env() + database = Database(config) + storage = S3Storage(config) + grace = config.attachment_orphan_grace_seconds if args.grace_seconds is None else args.grace_seconds + if grace < 0: + raise SystemExit("--grace-seconds must be >= 0") + try: + async with database.session() as session: + repository = Repository(session) + rows = await repository.list_attachment_states() + objects = await storage.list_objects() + now = utc_now() + items, missing = build_plan(rows, objects, now=now, grace_seconds=grace) + deletable = [item for item in items if item.action in ("delete", "delete_object_and_row", "delete_row")] + summary = { + "mode": "apply" if args.apply else "dry-run", + "grace_seconds": grace, + "prefix": config.s3_key_prefix, + "metadata_rows": len(rows), + "objects": len(objects), + "plan": [asdict(item) for item in items], + "missing_ready": [asdict(item) for item in missing], + "would_delete_objects": len( + [item for item in items if item.action in ("delete", "delete_object_and_row")] + ), + "would_delete_rows": len( + [item for item in items if item.action in ("delete_row", "delete_object_and_row")] + ), + } + if not args.apply: + print(json.dumps(summary, ensure_ascii=False, indent=2, sort_keys=True)) + return 1 if (missing and args.fail_on_missing) else 0 + + deleted_objects = 0 + deleted_rows = 0 + async with database.session() as session: + repository = Repository(session) + for item in deletable: + if item.action in ("delete", "delete_object_and_row") and item.object_key: + try: + await storage.delete(item.object_key) + deleted_objects += 1 + except StorageUnavailable: + # Не удаляем строку, если объект не удалился: следующий + # запуск повторит попытку. + logger.warning("reconcile_object_delete_failed", extra={"fields": {"key": item.object_key}}) + continue + if item.action in ("delete_row", "delete_object_and_row"): + try: + from uuid import UUID + if await repository.delete_attachment_if_stale(UUID(item.identifier), now - timedelta(seconds=grace)): + deleted_rows += 1 + except Exception: + logger.warning("reconcile_row_delete_failed", extra={"fields": {"id": item.identifier}}) + summary["deleted_objects"] = deleted_objects + summary["deleted_rows"] = deleted_rows + print(json.dumps(summary, ensure_ascii=False, indent=2, sort_keys=True)) + return 1 if (missing and args.fail_on_missing) else 0 + finally: + await storage.close() + await database.dispose() + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description="Сверка вложений PostgreSQL и S3") + parser.add_argument("--apply", action="store_true", help="действительно удалять мусор") + parser.add_argument("--dry-run", action="store_true", help="только показать план (по умолчанию)") + parser.add_argument("--grace-seconds", type=int, default=None, help="возраст, после которого мусор удаляется") + parser.add_argument("--fail-on-missing", action="store_true", help="код 1, если ready-объект отсутствует") + args = parser.parse_args(argv) + if args.dry_run: + args.apply = False + return asyncio.run(run(args)) + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/src/messenger/repository.py b/src/messenger/repository.py new file mode 100644 index 00000000..c77d9907 --- /dev/null +++ b/src/messenger/repository.py @@ -0,0 +1,554 @@ +"""Запросы к PostgreSQL: единственное место, где выполняется SQL. + +Все значения передаются bind-параметрами — строки запросов не собираются из +данных пользователя. Транзакционную границу задаёт репозиторий: операция, +меняющая несколько таблиц, выполняется целиком или не выполняется вовсе. + +Единица работы — неявная транзакция сессии запроса: пишущие методы завершают +её `commit`, а незавершённую откатывает закрытие сессии. +""" +from __future__ import annotations + +from typing import Sequence +from uuid import UUID, uuid4 + +from sqlalchemy import Row, Select, cast, delete, func, insert, literal, select, text, tuple_, update +from sqlalchemy.dialects.postgresql import TIMESTAMP, UUID as PGUUID +from sqlalchemy.dialects.postgresql import insert as pg_insert +from sqlalchemy.exc import IntegrityError +from sqlalchemy.ext.asyncio import AsyncSession + +from .domain import ( + ATTACHMENT_STATUS_PENDING, + ATTACHMENT_STATUS_READY, + AttachmentNotReady, + AttachmentRecord, + AttachmentUnknown, + ChatRecord, + IdempotencyConflict, + MessageRecord, + Position, + UnknownMembers, + UserRecord, +) +from .schema import ATTACHMENTS, CHAT_MEMBERS, CHATS, MESSAGE_ATTACHMENTS, MESSAGE_IDEMPOTENCY, MESSAGES, USERS + +FOREIGN_KEY_VIOLATION = "23503" + +# Ключ идемпотентности живёт 24 часа; срок считает PostgreSQL, а не часы +# приложения, чтобы реплики с разными часами принимали одинаковое решение. +IDEMPOTENCY_FRESH_PREDICATE = MESSAGE_IDEMPOTENCY.c.created_at > ( + func.now() - text("INTERVAL '24 hours'") +) + + +def _sqlstate(error: IntegrityError) -> str | None: + """Код ошибки PostgreSQL: драйвер кладёт его в исходное исключение.""" + return getattr(getattr(error, "orig", None), "sqlstate", None) + + +def _after_predicate(created_at_column, id_column, after: Position): + """Keyset-условие «строго после пары (created_at, id)» одним сравнением строк.""" + moment, item_id = after + return tuple_(created_at_column, id_column) > tuple_( + cast(literal(moment), TIMESTAMP(timezone=True)), + cast(literal(item_id), PGUUID(as_uuid=True)), + ) + + +def _user_record(row: Row) -> UserRecord: + return UserRecord( + id=row.id, username=row.username, display_name=row.display_name, created_at=row.created_at + ) + + +def _chat_columns() -> tuple: + return (CHATS.c.id, CHATS.c.title, CHATS.c.created_at) + + +def _message_columns() -> tuple: + return ( + MESSAGES.c.id, + MESSAGES.c.chat_id, + MESSAGES.c.sender_id, + MESSAGES.c.text, + MESSAGES.c.created_at, + ) + + +def _attachment_columns() -> tuple: + return ( + ATTACHMENTS.c.id, + ATTACHMENTS.c.chat_id, + ATTACHMENTS.c.owner_id, + ATTACHMENTS.c.object_key, + ATTACHMENTS.c.filename, + ATTACHMENTS.c.content_type, + ATTACHMENTS.c.size_bytes, + ATTACHMENTS.c.sha256, + ATTACHMENTS.c.status, + ATTACHMENTS.c.error_code, + ATTACHMENTS.c.created_at, + ATTACHMENTS.c.updated_at, + ) + + +def _attachment_record(row: Row) -> AttachmentRecord: + return AttachmentRecord( + id=row.id, + chat_id=row.chat_id, + owner_id=row.owner_id, + object_key=row.object_key, + filename=row.filename, + content_type=row.content_type, + size_bytes=row.size_bytes, + sha256=row.sha256, + status=row.status, + error_code=row.error_code, + created_at=row.created_at, + updated_at=row.updated_at, + ) + + +def _message_record(row: Row, attachment_ids: Sequence[UUID] = ()) -> MessageRecord: + return MessageRecord( + id=row.id, + chat_id=row.chat_id, + sender_id=row.sender_id, + text=row.text, + created_at=row.created_at, + attachment_ids=tuple(attachment_ids), + ) + + +class Repository: + """Набор операций над PostgreSQL в рамках одной сессии (одного запроса).""" + + def __init__(self, session: AsyncSession) -> None: + self._session = session + + async def ping(self) -> None: + """Дешёвая проверка живости соединения для /health/ready.""" + await self._session.execute(select(literal(1))) + + async def username_taken(self, username: str) -> bool: + found = await self._session.scalar( + select(USERS.c.id).where(USERS.c.username == username).limit(1) + ) + return found is not None + + async def create_user( + self, username: str, display_name: str, password_hash: str + ) -> UserRecord | None: + row = ( + await self._session.execute( + pg_insert(USERS) + .values( + id=uuid4(), + username=username, + display_name=display_name, + password_hash=password_hash, + ) + .on_conflict_do_nothing(index_elements=[USERS.c.username]) + .returning(*USERS.c) + ) + ).first() + await self._session.commit() + return None if row is None else _user_record(row) + + async def credentials_for(self, username: str) -> tuple[UserRecord, str] | None: + row = ( + await self._session.execute( + select(USERS.c.id, USERS.c.username, USERS.c.display_name, USERS.c.created_at, + USERS.c.password_hash) + .where(USERS.c.username == username) + .limit(1) + ) + ).first() + if row is None: + return None + return _user_record(row), row.password_hash + + async def get_user(self, user_id: UUID) -> UserRecord | None: + row = ( + await self._session.execute( + select(USERS.c.id, USERS.c.username, USERS.c.display_name, USERS.c.created_at) + .where(USERS.c.id == user_id) + .limit(1) + ) + ).first() + return None if row is None else _user_record(row) + + async def create_chat(self, title: str, member_ids: Sequence[UUID]) -> ChatRecord: + chat_id = uuid4() + row = ( + await self._session.execute( + insert(CHATS).values(id=chat_id, title=title).returning(*_chat_columns()) + ) + ).one() + try: + await self._session.execute( + insert(CHAT_MEMBERS), + [{"chat_id": chat_id, "user_id": member_id} for member_id in member_ids], + ) + except IntegrityError as error: + if _sqlstate(error) != FOREIGN_KEY_VIOLATION: + raise + await self._session.rollback() + raise UnknownMembers(member_ids) from None + await self._session.commit() + return ChatRecord( + id=row.id, + title=row.title, + member_ids=tuple(sorted(member_ids, key=lambda item: item.int)), + created_at=row.created_at, + ) + + async def chat_for_member(self, chat_id: UUID, user_id: UUID) -> ChatRecord | None: + row = ( + await self._session.execute( + select(*_chat_columns()) + .select_from(CHATS.join(CHAT_MEMBERS, CHAT_MEMBERS.c.chat_id == CHATS.c.id)) + .where(CHATS.c.id == chat_id, CHAT_MEMBERS.c.user_id == user_id) + .limit(1) + ) + ).first() + if row is None: + return None + members = await self._members_of([chat_id]) + return ChatRecord( + id=row.id, title=row.title, member_ids=members[chat_id], created_at=row.created_at + ) + + async def list_chats( + self, user_id: UUID, after: Position | None, limit: int + ) -> tuple[list[ChatRecord], bool]: + statement = ( + select(*_chat_columns()) + .select_from(CHATS.join(CHAT_MEMBERS, CHAT_MEMBERS.c.chat_id == CHATS.c.id)) + .where(CHAT_MEMBERS.c.user_id == user_id) + ) + rows = await self._page(statement, CHATS, after, limit) + more = len(rows) > limit + rows = rows[:limit] + members = await self._members_of([row.id for row in rows]) + chats = [ + ChatRecord( + id=row.id, title=row.title, member_ids=members[row.id], created_at=row.created_at + ) + for row in rows + ] + return chats, more + + async def append_message( + self, chat_id: UUID, sender_id: UUID, text: str, attachment_ids: Sequence[UUID] = () + ) -> MessageRecord: + message_id = uuid4() + row = ( + await self._session.execute( + insert(MESSAGES) + .values(id=message_id, chat_id=chat_id, sender_id=sender_id, text=text) + .returning(*_message_columns()) + ) + ).one() + await self._link_attachments(message_id, attachment_ids) + await self._session.commit() + return _message_record(row, attachment_ids) + + async def append_message_idempotent( + self, + chat_id: UUID, + sender_id: UUID, + text: str, + attachment_ids: Sequence[UUID], + idempotency_key: str, + request_hash: str, + ) -> MessageRecord: + """Создаёт сообщение ровно один раз для ключа (пользователь, чат, ключ). + + Побочный эффект (messages + message_attachments) и запись результата + (message_idempotency) фиксируются одной транзакцией. + """ + lock_scope = f'{sender_id}:{chat_id}:{idempotency_key}' + await self._session.execute( + select(func.pg_advisory_xact_lock(func.hashtextextended(lock_scope, 0))) + ) + fresh = IDEMPOTENCY_FRESH_PREDICATE + existing = ( + await self._session.execute( + select(*_message_columns(), MESSAGE_IDEMPOTENCY.c.request_hash, fresh.label('fresh')) + .select_from( + MESSAGE_IDEMPOTENCY.join( + MESSAGES, MESSAGES.c.id == MESSAGE_IDEMPOTENCY.c.message_id + ) + ) + .where( + MESSAGE_IDEMPOTENCY.c.user_id == sender_id, + MESSAGE_IDEMPOTENCY.c.chat_id == chat_id, + MESSAGE_IDEMPOTENCY.c.idempotency_key == idempotency_key, + ) + .limit(1) + ) + ).first() + if existing is not None: + if existing.fresh and existing.request_hash == request_hash: + linked = await self._attachment_ids_of([existing.id]) + record = _message_record(existing, linked.get(existing.id, ())) + await self._session.commit() + return record + if existing.fresh: + await self._session.rollback() + raise IdempotencyConflict() + # Срок хранения ключа истёк: старый ключ можно использовать снова. + await self._session.execute( + delete(MESSAGE_IDEMPOTENCY).where( + MESSAGE_IDEMPOTENCY.c.user_id == sender_id, + MESSAGE_IDEMPOTENCY.c.chat_id == chat_id, + MESSAGE_IDEMPOTENCY.c.idempotency_key == idempotency_key, + ) + ) + message_id = uuid4() + row = ( + await self._session.execute( + insert(MESSAGES) + .values(id=message_id, chat_id=chat_id, sender_id=sender_id, text=text) + .returning(*_message_columns()) + ) + ).one() + await self._link_attachments(message_id, attachment_ids) + await self._session.execute( + insert(MESSAGE_IDEMPOTENCY).values( + user_id=sender_id, + chat_id=chat_id, + idempotency_key=idempotency_key, + request_hash=request_hash, + message_id=message_id, + ) + ) + await self._session.commit() + return _message_record(row, attachment_ids) + + async def list_messages( + self, chat_id: UUID, after: Position | None, limit: int + ) -> tuple[list[MessageRecord], bool]: + statement = select(*_message_columns()).where(MESSAGES.c.chat_id == chat_id) + rows = await self._page(statement, MESSAGES, after, limit) + more = len(rows) > limit + page = rows[:limit] + linked = await self._attachment_ids_of([row.id for row in page]) + messages = [ + _message_record(row, linked.get(row.id, ())) + for row in page + ] + return messages, more + + async def _link_attachments(self, message_id: UUID, attachment_ids: Sequence[UUID]) -> None: + if not attachment_ids: + return + await self._session.execute( + insert(MESSAGE_ATTACHMENTS), + [ + {"message_id": message_id, "attachment_id": attachment_id, "position": position} + for position, attachment_id in enumerate(attachment_ids) + ], + ) + + async def _attachment_ids_of(self, message_ids: Sequence[UUID]) -> dict[UUID, tuple[UUID, ...]]: + if not message_ids: + return {} + rows = await self._session.execute( + select(MESSAGE_ATTACHMENTS.c.message_id, MESSAGE_ATTACHMENTS.c.attachment_id) + .where(MESSAGE_ATTACHMENTS.c.message_id.in_(message_ids)) + .order_by(MESSAGE_ATTACHMENTS.c.message_id, MESSAGE_ATTACHMENTS.c.position) + ) + grouped: dict[UUID, list[UUID]] = {} + for message_id, attachment_id in rows: + grouped.setdefault(message_id, []).append(attachment_id) + return {message_id: tuple(items) for message_id, items in grouped.items()} + + async def _page( + self, statement: Select, table, after: Position | None, limit: int + ) -> list[Row]: + if after is not None: + statement = statement.where(_after_predicate(table.c.created_at, table.c.id, after)) + result = await self._session.execute( + statement.order_by(table.c.created_at, table.c.id).limit(limit + 1) + ) + return list(result) + + async def _members_of(self, chat_ids: Sequence[UUID]) -> dict[UUID, tuple[UUID, ...]]: + if not chat_ids: + return {} + rows = await self._session.execute( + select(CHAT_MEMBERS.c.chat_id, CHAT_MEMBERS.c.user_id) + .where(CHAT_MEMBERS.c.chat_id.in_(chat_ids)) + .order_by(CHAT_MEMBERS.c.chat_id, CHAT_MEMBERS.c.user_id) + ) + grouped: dict[UUID, list[UUID]] = {} + for chat_id, user_id in rows: + grouped.setdefault(chat_id, []).append(user_id) + return {chat_id: tuple(members) for chat_id, members in grouped.items()} + + # --- Вложения --------------------------------------------------------- + + async def create_pending_attachment( + self, + attachment_id: UUID, + chat_id: UUID, + owner_id: UUID, + object_key: str, + filename: str, + content_type: str, + size_bytes: int, + sha256: str, + ) -> AttachmentRecord: + """Фиксирует намерение загрузить объект до обращения к S3. + + Строка pending — это долг перед сверкой: если процесс умрёт между + вставкой и подтверждением, reconciler найдёт её и уберёт после grace + period. Клиент ещё не получил 201 и не может ссылаться на вложение. + """ + row = ( + await self._session.execute( + insert(ATTACHMENTS) + .values( + id=attachment_id, + chat_id=chat_id, + owner_id=owner_id, + object_key=object_key, + filename=filename, + content_type=content_type, + size_bytes=size_bytes, + sha256=sha256, + status=ATTACHMENT_STATUS_PENDING, + ) + .returning(*_attachment_columns()) + ) + ).one() + await self._session.commit() + return _attachment_record(row) + + async def mark_attachment_ready(self, attachment_id: UUID) -> AttachmentRecord | None: + row = ( + await self._session.execute( + update(ATTACHMENTS) + .where( + ATTACHMENTS.c.id == attachment_id, + ATTACHMENTS.c.status == ATTACHMENT_STATUS_PENDING, + ) + .values( + status=ATTACHMENT_STATUS_READY, + error_code=None, + updated_at=func.now(), + ) + .returning(*_attachment_columns()) + ) + ).first() + await self._session.commit() + return None if row is None else _attachment_record(row) + + async def delete_attachment(self, attachment_id: UUID) -> bool: + """Удаляет метаданные pending-вложения при неудачной загрузке. + + Готовые вложения удалять нельзя: на них могут ссылаться сообщения, + поэтому FK `RESTRICT` не даст сделать это случайно. + """ + try: + row = ( + await self._session.execute( + delete(ATTACHMENTS) + .where( + ATTACHMENTS.c.id == attachment_id, + ATTACHMENTS.c.status == ATTACHMENT_STATUS_PENDING, + ) + .returning(ATTACHMENTS.c.id) + ) + ).first() + await self._session.commit() + return row is not None + except IntegrityError: + await self._session.rollback() + return False + + async def attachment_for_member( + self, attachment_id: UUID, user_id: UUID + ) -> AttachmentRecord | None: + """Вложение глазами участника чата; чужое неотличимо от отсутствующего.""" + row = ( + await self._session.execute( + select(*_attachment_columns()) + .select_from( + ATTACHMENTS.join( + CHAT_MEMBERS, CHAT_MEMBERS.c.chat_id == ATTACHMENTS.c.chat_id + ) + ) + .where(ATTACHMENTS.c.id == attachment_id, CHAT_MEMBERS.c.user_id == user_id) + .limit(1) + ) + ).first() + return None if row is None else _attachment_record(row) + + async def attachment_by_id(self, attachment_id: UUID) -> AttachmentRecord | None: + row = ( + await self._session.execute( + select(*_attachment_columns()).where(ATTACHMENTS.c.id == attachment_id).limit(1) + ) + ).first() + return None if row is None else _attachment_record(row) + + async def validate_message_attachments( + self, chat_id: UUID, attachment_ids: Sequence[UUID] + ) -> list[AttachmentRecord]: + """Проверяет, что все вложения существуют, принадлежат чату и готовы. + + Неизвестное или чужое — 404; pending/failed — 409. Порядок возвращаемых + записей совпадает с порядком `attachment_ids` в запросе. + """ + if not attachment_ids: + return [] + rows = ( + await self._session.execute( + select(*_attachment_columns()).where(ATTACHMENTS.c.id.in_(attachment_ids)) + ) + ).all() + found = {row.id: _attachment_record(row) for row in rows} + if any(attachment_id not in found for attachment_id in attachment_ids): + raise AttachmentUnknown() + if any(found[attachment_id].chat_id != chat_id for attachment_id in attachment_ids): + raise AttachmentUnknown() + if any(found[attachment_id].status != ATTACHMENT_STATUS_READY for attachment_id in attachment_ids): + raise AttachmentNotReady() + return [found[attachment_id] for attachment_id in attachment_ids] + + async def list_attachment_states(self) -> list[AttachmentRecord]: + """Все строки метаданных для reconciler (без байтов).""" + rows = ( + await self._session.execute( + select(*_attachment_columns()).order_by(ATTACHMENTS.c.created_at, ATTACHMENTS.c.id) + ) + ).all() + return [_attachment_record(row) for row in rows] + + async def delete_attachment_if_stale(self, attachment_id: UUID, before) -> bool: + """Удаляет только pending/failed-строку старше `before`. + + Готовые вложения не удаляются даже при расхождении с S3: это данные + пользователя, и автоматическое удаление метаданных было бы потерей. + """ + try: + row = ( + await self._session.execute( + delete(ATTACHMENTS) + .where( + ATTACHMENTS.c.id == attachment_id, + ATTACHMENTS.c.status.in_(("pending", "failed")), + ATTACHMENTS.c.updated_at < before, + ) + .returning(ATTACHMENTS.c.id) + ) + ).first() + await self._session.commit() + return row is not None + except IntegrityError: + await self._session.rollback() + return False diff --git a/src/messenger/routers/__init__.py b/src/messenger/routers/__init__.py new file mode 100644 index 00000000..acd99363 --- /dev/null +++ b/src/messenger/routers/__init__.py @@ -0,0 +1 @@ +"""Маршруты HTTP API: только разбор запроса, вызов зависимостей и сборка ответа.""" diff --git a/src/messenger/routers/attachments.py b/src/messenger/routers/attachments.py new file mode 100644 index 00000000..725c629e --- /dev/null +++ b/src/messenger/routers/attachments.py @@ -0,0 +1,196 @@ +"""Загрузка, метаданные и авторизованная выдача вложений. + +Байты не проходят через PostgreSQL и не отдаются redirect-ом в S3: API сам +проверяет членство в чате и стримит объект из приватного bucket. +""" +from __future__ import annotations + +import logging +from typing import Annotated, AsyncIterator +from uuid import UUID, uuid4 + +import anyio +from fastapi import APIRouter, Path, Query, Request, status +from fastapi.responses import StreamingResponse + +from ..access import visible_chat +from ..deps import ConfigDep, CurrentUser, RepositoryDep, StorageDep +from ..domain import AttachmentNotReady, AttachmentRecord, AttachmentUnknown +from ..errors import conflict, invalid_request, not_found, payload_too_large, unavailable, unsupported_media_type +from ..models import Attachment +from ..storage import StorageObjectMissing, StorageUnavailable +from ..upload import receive_image + +router = APIRouter(prefix="/api/v1", tags=["attachments"]) +logger = logging.getLogger("messenger") + +ALLOWED_CONTENT_TYPES = ("image/png", "image/jpeg") +FORBIDDEN_FILENAME_CHARS = ("/", "\\", "\x00") + + +def declared_content_type(value: str | None) -> str | None: + """Медиа-тип без параметров; None — если он не PNG/JPEG.""" + if not value: + return None + media_type = value.split(";", 1)[0].strip().lower() + return media_type if media_type in ALLOWED_CONTENT_TYPES else None + + +def validate_filename(value: str) -> str: + """filename — только отображаемое имя, но опасные символы отклоняются.""" + if not value or len(value) > 255: + raise invalid_request("filename должен содержать 1..255 code points") + if any(char in value for char in FORBIDDEN_FILENAME_CHARS): + raise invalid_request("filename не должен содержать /, \\ или NUL") + if any(ord(char) < 0x20 or ord(char) == 0x7F for char in value): + raise invalid_request("filename не должен содержать управляющие символы") + return value + + +async def _stream_body(body) -> AsyncIterator[bytes]: + """Читает S3-поток в рабочем потоке, не блокируя event loop.""" + try: + while True: + chunk = await anyio.to_thread.run_sync(body.read, 64 * 1024) + if not chunk: + break + yield chunk + finally: + close = getattr(body, "close", None) + if close is not None: + close() + + +@router.post( + "/chats/{chat_id}/attachments", + status_code=status.HTTP_201_CREATED, + summary="Принять один PNG/JPEG, до 10 MiB", +) +async def upload_attachment( + chat_id: Annotated[UUID, Path()], + request: Request, + repository: RepositoryDep, + user: CurrentUser, + config: ConfigDep, + storage: StorageDep, + filename: Annotated[str, Query(min_length=1, max_length=255)], +) -> Attachment: + """Сначала доступ к чату, затем лимиты и MIME; 201 — только после S3 и БД. + + Порядок важен: чужой чат даёт 404 до чтения тела. `Content-Length` больше + предела отсекается до чтения; потоковый счётчик — вторая линия защиты для + chunked-запросов. Временный файл ограничен 10 MiB и удаляется после запроса. + """ + await visible_chat(repository, chat_id, user) + validate_filename(filename) + expected_type = declared_content_type(request.headers.get("content-type")) + if expected_type is None: + raise unsupported_media_type("Content-Type должен быть image/png или image/jpeg") + + raw_length = request.headers.get("content-length") + if raw_length is not None: + try: + length = int(raw_length) + except ValueError: + raise invalid_request("Content-Length должен быть целым числом") from None + if length < 0: + raise invalid_request("Content-Length не может быть отрицательным") + if length > config.max_upload_bytes: + raise payload_too_large(f"Файл больше {config.max_upload_bytes} байт") + + received = await receive_image( + request, expected_content_type=expected_type, config=config + ) + try: + attachment_id = uuid4() + object_key = storage.new_key(str(attachment_id)) + await repository.create_pending_attachment( + attachment_id=attachment_id, + chat_id=chat_id, + owner_id=user.id, + object_key=object_key, + filename=filename, + content_type=received.info.content_type, + size_bytes=received.size_bytes, + sha256=received.sha256, + ) + try: + with open(received.path, "rb") as file: + await storage.put( + object_key, + file, + content_type=received.info.content_type, + size_bytes=received.size_bytes, + sha256=received.sha256, + md5_hex=received.md5, + ) + except BaseException: + # S3 не принял объект: pending-строка не должна пережить запрос. + try: + await repository.delete_attachment(attachment_id) + except Exception: + logger.warning("attachment_compensation_failed", extra={"fields": {"attachment_id": str(attachment_id)}}) + raise + + if config.attachment_fault_mode == "after_s3_put": + # Учебное внедрение отказа между S3 и фиксацией в PostgreSQL. + # Строка остаётся pending, объект — orphan; reconciler уберёт его + # после grace period. В prod этот режим запрещён конфигурацией. + raise StorageUnavailable("Смоделирован отказ после S3 PUT") + + ready = await repository.mark_attachment_ready(attachment_id) + if ready is None: + # Строку мог удалить reconciler; объект уже в S3, поэтому его + # удаление — задача следующей сверки, а не этого запроса. + raise StorageUnavailable("Не удалось подтвердить вложение в PostgreSQL") + return Attachment.from_record(ready) + finally: + received.cleanup() + + +@router.get("/attachments/{attachment_id}", summary="Метаданные вложения") +async def get_attachment( + attachment_id: Annotated[UUID, Path()], + repository: RepositoryDep, + user: CurrentUser, +) -> Attachment: + record = await repository.attachment_for_member(attachment_id, user.id) + if record is None: + raise not_found("Вложение не найдено") + if record.status != "ready": + raise conflict("Вложение ещё не готово") + return Attachment.from_record(record) + + +@router.get("/attachments/{attachment_id}/content", summary="Скачать байты через API") +async def download_attachment( + attachment_id: Annotated[UUID, Path()], + repository: RepositoryDep, + user: CurrentUser, + storage: StorageDep, + variant: Annotated[str | None, Query()] = None, +) -> StreamingResponse: + """Оригинал отдаётся потоком, без redirect и без публичной ссылки.""" + if variant not in (None, "", "original"): + raise not_found("Вариант вложения не найден") + record = await repository.attachment_for_member(attachment_id, user.id) + if record is None: + raise not_found("Вложение не найдено") + if record.status != "ready": + raise conflict("Вложение ещё не готово") + try: + stored = await storage.open(record.object_key) + except StorageObjectMissing: + raise not_found("Объект вложения отсутствует") from None + except StorageUnavailable: + raise unavailable("Хранилище вложений недоступно") from None + if stored.size_bytes != record.size_bytes: + close = getattr(stored.body, "close", None) + if close is not None: + close() + raise unavailable("Размер объекта в хранилище не совпадает с метаданными") + return StreamingResponse( + _stream_body(stored.body), + media_type=record.content_type, + headers={"Content-Length": str(record.size_bytes)}, + ) diff --git a/src/messenger/routers/auth.py b/src/messenger/routers/auth.py new file mode 100644 index 00000000..c9ccb566 --- /dev/null +++ b/src/messenger/routers/auth.py @@ -0,0 +1,51 @@ +"""Вход по Basic и отзыв текущей сессии.""" +from __future__ import annotations + +from fastapi import APIRouter, Response, status + +from ..deps import BasicCredentialsDep, BearerToken, RepositoryDep, SessionsDep +from ..errors import BASIC_CHALLENGE, unauthorized +from ..models import Session +from ..security import spend_verification_time, verify_password + +router = APIRouter(prefix="/api/v1/auth/sessions", tags=["auth"]) + +INVALID_CREDENTIALS = "Неверный username или пароль" + + +@router.post("", status_code=status.HTTP_201_CREATED, summary="Вход: Basic username:password") +async def create_session( + credentials: BasicCredentialsDep, + repository: RepositoryDep, + sessions: SessionsDep, +) -> Session: + """Проверяет пароль и выдаёт opaque-токен сессии; тело запроса не читается. + + Неизвестный пользователь и неверный пароль неразличимы: одинаковый 401 с + Basic-челленджем и одинаковая затрата времени на KDF. + """ + found = await repository.credentials_for(credentials.username) + if found is None: + await spend_verification_time() + raise unauthorized(INVALID_CREDENTIALS, challenge=BASIC_CHALLENGE) + user, password_hash = found + if not await verify_password(credentials.password, password_hash): + raise unauthorized(INVALID_CREDENTIALS, challenge=BASIC_CHALLENGE) + issued = await sessions.create(user.id) + return Session.from_issued(issued, user) + + +@router.delete( + "/current", + status_code=status.HTTP_204_NO_CONTENT, + summary="Отозвать текущую сессию", +) +async def revoke_session(token: BearerToken, sessions: SessionsDep) -> Response: + """Отзыв действует сразу: тот же токен после него даёт 401. + + Ответ пустой (204), поэтому клиент не получает ни тела, ни нового состояния + сессии. Отзыв не трогает PostgreSQL: удаление ключа в Valkey атомарно. + """ + if not await sessions.revoke(token): + raise unauthorized("Сессия не найдена или истекла") + return Response(status_code=status.HTTP_204_NO_CONTENT) diff --git a/src/messenger/routers/chats.py b/src/messenger/routers/chats.py new file mode 100644 index 00000000..dee42e57 --- /dev/null +++ b/src/messenger/routers/chats.py @@ -0,0 +1,55 @@ +"""Создание, список и чтение чатов.""" +from __future__ import annotations + +from typing import Annotated +from uuid import UUID + +from fastapi import APIRouter, Path, Query, status + +from ..access import visible_chat +from ..cursor import KIND_CHATS +from ..deps import CursorsDep, CurrentUser, RepositoryDep +from ..domain import UnknownMembers +from ..errors import invalid_request +from ..models import DEFAULT_LIMIT, MAX_LIMIT, Chat, ChatPage, CreateChat +from ..pagination import build_next_cursor, decoded_cursor + +router = APIRouter(prefix="/api/v1/chats", tags=["chats"]) + + +@router.post("", status_code=status.HTTP_201_CREATED, summary="Создать чат") +async def create_chat(payload: CreateChat, repository: RepositoryDep, user: CurrentUser) -> Chat: + """Создаёт чат; состав участников задаётся при создании и не меняется.""" + if user.id not in payload.member_ids: + raise invalid_request("Создатель чата обязан входить в member_ids") + try: + record = await repository.create_chat(payload.title, payload.member_ids) + except UnknownMembers: + raise invalid_request("member_ids содержит неизвестных пользователей") from None + return Chat.from_record(record) + + +@router.get("", summary="Чаты текущего пользователя") +async def list_chats( + repository: RepositoryDep, + cursors: CursorsDep, + user: CurrentUser, + limit: Annotated[int, Query(ge=1, le=MAX_LIMIT)] = DEFAULT_LIMIT, + cursor: Annotated[str | None, Query(min_length=1)] = None, +) -> ChatPage: + """Список видимых чатов по (created_at, id) по возрастанию.""" + scope = str(user.id) + after = decoded_cursor(cursors, cursor, kind=KIND_CHATS, scope=scope) + records, has_more = await repository.list_chats(user.id, after, limit) + return ChatPage.from_records( + records, build_next_cursor(cursors, KIND_CHATS, scope, records, has_more) + ) + + +@router.get("/{chat_id}", summary="Получить доступный чат") +async def read_chat( + chat_id: Annotated[UUID, Path()], + repository: RepositoryDep, + user: CurrentUser, +) -> Chat: + return Chat.from_record(await visible_chat(repository, chat_id, user)) diff --git a/src/messenger/routers/health.py b/src/messenger/routers/health.py new file mode 100644 index 00000000..7ac6910f --- /dev/null +++ b/src/messenger/routers/health.py @@ -0,0 +1,46 @@ +"""Проверки живости и готовности.""" +from __future__ import annotations + +from fastapi import APIRouter, Request + +from ..deps import DatabaseDep, SessionsDep, StorageDep +from ..errors import unavailable +from ..models import Health +from ..schema import SCHEMA_REVISION + +router = APIRouter(prefix="/health", tags=["health"]) + + +@router.get("/live", summary="Процесс жив") +async def liveness() -> Health: + """Проверяет только то, что процесс обслуживает запросы. + + Зависимости здесь намеренно не проверяются: их отказ — не повод убивать + контейнер и устраивать цикл перезапусков. + """ + return Health() + + +@router.get("/ready", summary="Готов принимать трафик") +async def readiness( + request: Request, + database: DatabaseDep, + sessions: SessionsDep, + storage: StorageDep, +) -> Health: + """Готовность = процесс не на остановке и критические зависимости отвечают. + + Отказ зависимости превращается в 503 общим обработчиком: у готовности и у + бизнес-операций один и тот же признак неработоспособности. + """ + if getattr(request.app.state, "draining", False): + raise unavailable("Сервис завершает работу и не принимает новые запросы") + await database.ping() + revision = await database.schema_revision() + if revision != SCHEMA_REVISION: + raise unavailable("Схема базы данных ещё не готова") + await sessions.ping() + # S3 — критичная зависимость обязательного синхронного upload/download. + # Без него API не должен получать трафик от балансировщика. + await storage.ping() + return Health() \ No newline at end of file diff --git a/src/messenger/routers/messages.py b/src/messenger/routers/messages.py new file mode 100644 index 00000000..9d614570 --- /dev/null +++ b/src/messenger/routers/messages.py @@ -0,0 +1,74 @@ +"""Отправка и чтение истории сообщений.""" +from __future__ import annotations + +from typing import Annotated +from uuid import UUID + +from fastapi import APIRouter, Header, Path, Query, status + +from ..access import visible_chat +from ..cursor import KIND_MESSAGES +from ..deps import CursorsDep, CurrentUser, RepositoryDep +from ..domain import AttachmentNotReady, AttachmentUnknown, IdempotencyConflict +from ..errors import conflict, not_found +from ..idempotency import message_request_hash, require_idempotency_key +from ..models import DEFAULT_LIMIT, MAX_LIMIT, CreateMessage, Message, MessagePage +from ..pagination import build_next_cursor, decoded_cursor + +router = APIRouter(prefix="/api/v1/chats/{chat_id}/messages", tags=["messages"]) + + +@router.post("", status_code=status.HTTP_201_CREATED, summary="Отправить сообщение") +async def create_message( + chat_id: Annotated[UUID, Path()], + payload: CreateMessage, + repository: RepositoryDep, + user: CurrentUser, + idempotency_key: Annotated[str | None, Header(alias="Idempotency-Key")] = None, +) -> Message: + """Отправитель выводится из идентификации; sender_id в теле не принимается. + + Порядок проверок контракта: аутентификация (зависимость user), доступ к + чату (404 для чужого), затем ключ идемпотентности. Повтор с тем же ключом + и телом возвращает то же сообщение и тот же код 201. + """ + await visible_chat(repository, chat_id, user) + try: + await repository.validate_message_attachments(chat_id, payload.attachment_ids) + except AttachmentUnknown: + # Чужое и несуществующее вложение неотличимы от отсутствующего (404). + raise not_found("Вложение не найдено") from None + except AttachmentNotReady: + raise conflict("Вложение ещё не готово") from None + key = require_idempotency_key(idempotency_key) + try: + record = await repository.append_message_idempotent( + chat_id, + user.id, + payload.text, + payload.attachment_ids, + key, + message_request_hash(payload.text, payload.attachment_ids), + ) + except IdempotencyConflict: + raise conflict("Idempotency-Key уже использован с другим телом запроса") from None + return Message.from_record(record) + + +@router.get("", summary="Сообщения по (created_at, id) по возрастанию") +async def list_messages( + chat_id: Annotated[UUID, Path()], + repository: RepositoryDep, + cursors: CursorsDep, + user: CurrentUser, + limit: Annotated[int, Query(ge=1, le=MAX_LIMIT)] = DEFAULT_LIMIT, + cursor: Annotated[str | None, Query(min_length=1)] = None, +) -> MessagePage: + """Keyset-пагинация: страница читается по индексу, предыдущие не повторяются.""" + await visible_chat(repository, chat_id, user) + scope = str(chat_id) + after = decoded_cursor(cursors, cursor, kind=KIND_MESSAGES, scope=scope) + records, has_more = await repository.list_messages(chat_id, after, limit) + return MessagePage.from_records( + records, build_next_cursor(cursors, KIND_MESSAGES, scope, records, has_more) + ) \ No newline at end of file diff --git a/src/messenger/routers/users.py b/src/messenger/routers/users.py new file mode 100644 index 00000000..86dfb6bc --- /dev/null +++ b/src/messenger/routers/users.py @@ -0,0 +1,34 @@ +"""Регистрация и текущий пользователь.""" +from __future__ import annotations + +from fastapi import APIRouter, status + +from ..deps import CurrentUser, RepositoryDep +from ..errors import conflict +from ..models import CreateUser, User +from ..security import hash_password + +router = APIRouter(prefix="/api/v1/users", tags=["users"]) + +USERNAME_TAKEN = "username уже занят" + + +@router.post("", status_code=status.HTTP_201_CREATED, summary="Создать пользователя") +async def register_user(payload: CreateUser, repository: RepositoryDep) -> User: + """Регистрация публична; username уникален, повтор даёт 409.""" + if await repository.username_taken(payload.username): + # Предпроверка экономит KDF на заведомо занятом username; гонку закрывает + # уникальный индекс в create_user, поэтому оба пути дают один и тот же 409. + raise conflict(USERNAME_TAKEN) + record = await repository.create_user( + payload.username, payload.display_name, await hash_password(payload.password) + ) + if record is None: + raise conflict(USERNAME_TAKEN) + return User.from_record(record) + + +@router.get("/me", summary="Текущий пользователь") +async def read_current_user(user: CurrentUser) -> User: + """Владелец Bearer-сессии; пароль и хэш пароля наружу не выходят.""" + return User.from_record(user) diff --git a/src/messenger/schema.py b/src/messenger/schema.py new file mode 100644 index 00000000..a242d925 --- /dev/null +++ b/src/messenger/schema.py @@ -0,0 +1,192 @@ +"""Описание таблиц PostgreSQL: один источник истины для запросов и миграций.""" +from __future__ import annotations + +from sqlalchemy import ( + BigInteger, + CheckConstraint, + Column, + ForeignKey, + Index, + MetaData, + SmallInteger, + Table, + Text, + UniqueConstraint, + text, +) +from sqlalchemy.dialects.postgresql import TIMESTAMP, UUID + +METADATA = MetaData() + +# Версия схемы, которую процесс считает совместимой с собой. Готовность +# проверяет её в alembic_version, поэтому API не начинает принимать трафик +# раньше однократной миграции. +SCHEMA_REVISION = "0003_attachments" + +USERS = Table( + "users", + METADATA, + Column("id", UUID(as_uuid=True), primary_key=True), + Column("username", Text, nullable=False), + Column("display_name", Text, nullable=False), + Column("password_hash", Text, nullable=False), + Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("now()")), + UniqueConstraint("username", name="uq_users_username"), + CheckConstraint(r"username ~ '^[a-z0-9_]{3,32}$'", name="ck_users_username_format"), + CheckConstraint( + "char_length(display_name) BETWEEN 1 AND 100", name="ck_users_display_name_length" + ), +) + +CHATS = Table( + "chats", + METADATA, + Column("id", UUID(as_uuid=True), primary_key=True), + Column("title", Text, nullable=False), + Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("now()")), + CheckConstraint("char_length(title) BETWEEN 1 AND 100", name="ck_chats_title_length"), +) + +CHAT_MEMBERS = Table( + "chat_members", + METADATA, + Column( + "chat_id", + UUID(as_uuid=True), + ForeignKey("chats.id", name="fk_chat_members_chat", ondelete="CASCADE"), + primary_key=True, + ), + Column( + "user_id", + UUID(as_uuid=True), + ForeignKey("users.id", name="fk_chat_members_user", ondelete="RESTRICT"), + primary_key=True, + ), + Index("ix_chat_members_user_id_chat_id", "user_id", "chat_id"), +) + +MESSAGES = Table( + "messages", + METADATA, + Column("id", UUID(as_uuid=True), primary_key=True), + Column( + "chat_id", + UUID(as_uuid=True), + ForeignKey("chats.id", name="fk_messages_chat", ondelete="CASCADE"), + nullable=False, + ), + Column( + "sender_id", + UUID(as_uuid=True), + ForeignKey("users.id", name="fk_messages_sender", ondelete="RESTRICT"), + nullable=False, + ), + Column("text", Text, nullable=False), + Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("now()")), + # Пустой текст допустим только вместе с вложениями; это правило проверяет + # API, потому что CHECK не может ссылаться на другую таблицу. + CheckConstraint("char_length(text) <= 4000", name="ck_messages_text_length"), + # Порядок истории (created_at, id) и keyset-предикат обслуживает один индекс. + Index("ix_messages_chat_id_created_at_id", "chat_id", "created_at", "id"), +) + +# Общая идемпотентность отправки сообщения. Область уникальности — +# (пользователь, чат, ключ); тело запроса сравнивается по каноническому хэшу. +# Строка и само сообщение пишутся одной транзакцией, поэтому подтверждённый +# ответ и побочный эффект не могут разойтись. +MESSAGE_IDEMPOTENCY = Table( + "message_idempotency", + METADATA, + Column( + "user_id", + UUID(as_uuid=True), + ForeignKey("users.id", name="fk_message_idempotency_user", ondelete="CASCADE"), + primary_key=True, + ), + Column( + "chat_id", + UUID(as_uuid=True), + ForeignKey("chats.id", name="fk_message_idempotency_chat", ondelete="CASCADE"), + primary_key=True, + ), + Column("idempotency_key", Text, primary_key=True), + Column("request_hash", Text, nullable=False), + Column( + "message_id", + UUID(as_uuid=True), + ForeignKey("messages.id", name="fk_message_idempotency_message", ondelete="CASCADE"), + nullable=False, + ), + Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("now()")), + CheckConstraint( + "char_length(idempotency_key) BETWEEN 1 AND 128", + name="ck_message_idempotency_key_length", + ), + Index("ix_message_idempotency_created_at", "created_at"), +) + +# Вложение: метаданные в PostgreSQL, байты — в приватном S3 по object_key. +# object_key назначает сервер; filename — только отображаемое имя. +ATTACHMENTS = Table( + "attachments", + METADATA, + Column("id", UUID(as_uuid=True), primary_key=True), + Column( + "chat_id", + UUID(as_uuid=True), + ForeignKey("chats.id", name="fk_attachments_chat", ondelete="CASCADE"), + nullable=False, + ), + Column( + "owner_id", + UUID(as_uuid=True), + ForeignKey("users.id", name="fk_attachments_owner", ondelete="RESTRICT"), + nullable=False, + ), + Column("object_key", Text, nullable=False), + Column("filename", Text, nullable=False), + Column("content_type", Text, nullable=False), + Column("size_bytes", BigInteger, nullable=False), + Column("sha256", Text, nullable=False), + Column("status", Text, nullable=False, server_default=text("'pending'")), + Column("error_code", Text, nullable=True), + Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("now()")), + Column("updated_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("now()")), + UniqueConstraint("object_key", name="uq_attachments_object_key"), + CheckConstraint("char_length(filename) BETWEEN 1 AND 255", name="ck_attachments_filename_length"), + CheckConstraint("content_type IN ('image/png','image/jpeg')", name="ck_attachments_content_type"), + CheckConstraint( + "size_bytes > 0 AND size_bytes <= 10485760", name="ck_attachments_size_bytes" + ), + CheckConstraint("sha256 ~ '^[a-f0-9]{64}$'", name="ck_attachments_sha256"), + CheckConstraint("status IN ('pending','ready','failed')", name="ck_attachments_status"), + CheckConstraint( + "error_code IS NULL OR char_length(error_code) BETWEEN 1 AND 64", + name="ck_attachments_error_code", + ), + Index("ix_attachments_chat_id_created_at_id", "chat_id", "created_at", "id"), + Index("ix_attachments_status_updated_at", "status", "updated_at"), +) + +# Связь сообщения с вложениями. position сохраняет порядок, в котором клиент +# передал attachment_ids; FK не даёт сослаться на несуществующее вложение. +MESSAGE_ATTACHMENTS = Table( + "message_attachments", + METADATA, + Column( + "message_id", + UUID(as_uuid=True), + ForeignKey("messages.id", name="fk_message_attachments_message", ondelete="CASCADE"), + primary_key=True, + ), + Column( + "attachment_id", + UUID(as_uuid=True), + ForeignKey("attachments.id", name="fk_message_attachments_attachment", ondelete="RESTRICT"), + primary_key=True, + ), + Column("position", SmallInteger, nullable=False), + UniqueConstraint("message_id", "position", name="uq_message_attachments_position"), + CheckConstraint("position >= 0 AND position < 10", name="ck_message_attachments_position"), + Index("ix_message_attachments_attachment_id", "attachment_id"), +) diff --git a/src/messenger/security.py b/src/messenger/security.py new file mode 100644 index 00000000..ea0e343a --- /dev/null +++ b/src/messenger/security.py @@ -0,0 +1,119 @@ +"""Пароли и токены: argon2id для пароля, случайный opaque-токен для доступа. + +Пароль не хранится и не передаётся дальше: в базе лежит только строка argon2id. +KDF считает десятки миллисекунд, поэтому вызывается в рабочем потоке — цикл +событий не должен ждать хэширование. +""" +from __future__ import annotations + +import base64 +import binascii +import hashlib +import secrets +from functools import lru_cache + +import anyio +from argon2 import PasswordHasher +from argon2.exceptions import Argon2Error, InvalidHashError + +# Минимальные параметры Argon2id из OWASP Password Storage Cheat Sheet: +# m=19456 КиБ (19 МиБ), t=2, p=1. Память на проверку ограничена осознанно. +TIME_COST = 2 +MEMORY_COST_KIB = 19456 +PARALLELISM = 1 +HASH_BYTES = 32 +SALT_BYTES = 16 + +TOKEN_BYTES = 32 +TOKEN_MIN_LENGTH = 32 + +BASIC_SCHEME = "basic" +BEARER_SCHEME = "bearer" + +_DUMMY_PASSWORD = "messenger-dummy-password-never-matches" + +_hasher = PasswordHasher( + time_cost=TIME_COST, + memory_cost=MEMORY_COST_KIB, + parallelism=PARALLELISM, + hash_len=HASH_BYTES, + salt_len=SALT_BYTES, +) + + +def _hash(password: str) -> str: + return _hasher.hash(password) + + +def _verify(password: str, stored_hash: str) -> bool: + """True только при совпадении; неподходящий или испорченный хэш — тоже «нет».""" + try: + return _hasher.verify(stored_hash, password) + except (Argon2Error, InvalidHashError): + return False + + +@lru_cache(maxsize=1) +def _dummy_hash() -> str: + """Хэш-заглушка: нужен, чтобы ответ про неизвестного пользователя стоил столько же.""" + return _hash(_DUMMY_PASSWORD) + + +async def hash_password(password: str) -> str: + """Хэширует пароль; длина пароля ограничена контрактом, усечения нет.""" + return await anyio.to_thread.run_sync(_hash, password) + + +async def verify_password(password: str, stored_hash: str) -> bool: + return await anyio.to_thread.run_sync(_verify, password, stored_hash) + + +async def spend_verification_time() -> None: + """Выполняет KDF впустую: время ответа не выдаёт существование пользователя.""" + await anyio.to_thread.run_sync(_verify, _DUMMY_PASSWORD, _dummy_hash()) + + +def new_token() -> str: + """Opaque-токен сессии: 256 бит энтропии, длина не меньше требуемых 32 символов.""" + return secrets.token_urlsafe(TOKEN_BYTES) + + +def token_fingerprint(token: str) -> str: + """Ключ, под которым сессия лежит в хранилище: сам токен там не появляется.""" + return hashlib.sha256(token.encode("utf-8")).hexdigest() + + +def _credentials(header: str | None, scheme: str) -> str | None: + """Хвост заголовка Authorization, если схема совпала; иначе None.""" + if not header: + return None + name, separator, value = header.strip().partition(" ") + if not separator or name.lower() != scheme: + return None + value = value.strip() + return value or None + + +def parse_basic(header: str | None) -> tuple[str, str] | None: + """Разбирает `Authorization: Basic ...` в пару (username, password). + + None означает «заголовка нет, схема не та или значение испорчено»; наружу все + эти случаи дают один и тот же 401, поэтому различать их незачем. + """ + encoded = _credentials(header, BASIC_SCHEME) + if encoded is None: + return None + try: + decoded = base64.b64decode(encoded + "=" * (-len(encoded) % 4), validate=True) + text = decoded.decode("utf-8") + except (binascii.Error, ValueError): + return None + username, separator, password = text.partition(":") + if not separator or not username: + return None + return username, password + + +def parse_bearer(header: str | None) -> str | None: + """Токен из `Authorization: Bearer ...`; None — если заголовок не подходит.""" + return _credentials(header, BEARER_SCHEME) diff --git a/src/messenger/sessions.py b/src/messenger/sessions.py new file mode 100644 index 00000000..e9e5700a --- /dev/null +++ b/src/messenger/sessions.py @@ -0,0 +1,122 @@ +"""Хранилище сессий в Valkey: opaque-токен → состояние с абсолютным временем жизни. + +Ключ строится из sha256 токена, поэтому в дампе и в `MONITOR` нет действующих +токенов — есть только их отпечатки. TTL выставляет сам сервер (`SET ... EX`), +а время истечения хранится абсолютным: перезапуск процесса или сервера срок +жизни сессии не продлевает. +""" +from __future__ import annotations + +import json +from dataclasses import dataclass +from datetime import datetime, timedelta +from typing import Protocol +from uuid import UUID + +from redis.asyncio import Redis + +from .domain import parse_rfc3339_z, rfc3339_z, utc_now +from .security import new_token, token_fingerprint + +SESSION_KEY_PREFIX = "messenger:session:" + + +@dataclass(frozen=True) +class SessionState: + """Состояние сессии: владелец и границы жизни.""" + + user_id: UUID + created_at: datetime + expires_at: datetime + + +@dataclass(frozen=True) +class IssuedSession: + """Выданная сессия: сам токен клиент видит ровно один раз.""" + + token: str + state: SessionState + + +class SessionStore(Protocol): + """Контракт хранилища сессий: его выполняет Valkey, подменяется в тестах.""" + + async def create(self, user_id: UUID) -> IssuedSession: ... + + async def resolve(self, token: str) -> SessionState | None: ... + + async def revoke(self, token: str) -> bool: ... + + async def ping(self) -> None: ... + + async def close(self) -> None: ... + + +def _key(token: str) -> str: + return SESSION_KEY_PREFIX + token_fingerprint(token) + + +def _state_of(payload: str) -> SessionState | None: + """Разбирает значение сессии; испорченное значение равносильно её отсутствию.""" + try: + data = json.loads(payload) + return SessionState( + user_id=UUID(data["user_id"]), + created_at=parse_rfc3339_z(data["created_at"]), + expires_at=parse_rfc3339_z(data["expires_at"]), + ) + except (ValueError, KeyError, TypeError): + return None + + +class RedisSessionStore: + """Сессии в Valkey/Redis с постоянным хранением (AOF). + + Таймауты на сокет ограничены: недоступная зависимость обязана отвечать + отказом быстро, а не держать запрос до таймаута клиента. + """ + + def __init__(self, url: str, ttl_seconds: int, timeout_seconds: float) -> None: + self._ttl_seconds = ttl_seconds + self._client = Redis.from_url( + url, + decode_responses=True, + socket_timeout=timeout_seconds, + socket_connect_timeout=timeout_seconds, + ) + + async def create(self, user_id: UUID) -> IssuedSession: + token = new_token() + created_at = utc_now() + expires_at = created_at + timedelta(seconds=self._ttl_seconds) + payload = json.dumps( + { + "user_id": str(user_id), + "created_at": rfc3339_z(created_at), + "expires_at": rfc3339_z(expires_at), + }, + separators=(",", ":"), + sort_keys=True, + ) + await self._client.set(_key(token), payload, ex=self._ttl_seconds) + return IssuedSession(token=token, state=SessionState(user_id, created_at, expires_at)) + + async def resolve(self, token: str) -> SessionState | None: + """Состояние действующей сессии; None — токен неизвестен или срок истёк.""" + payload = await self._client.get(_key(token)) + if payload is None: + return None + state = _state_of(payload) + if state is None or state.expires_at <= utc_now(): + return None + return state + + async def revoke(self, token: str) -> bool: + """Отзыв: GETDEL проверяет и удаляет одной атомарной операцией.""" + return await self._client.getdel(_key(token)) is not None + + async def ping(self) -> None: + await self._client.ping() + + async def close(self) -> None: + await self._client.aclose() diff --git a/src/messenger/storage.py b/src/messenger/storage.py new file mode 100644 index 00000000..00eeef9b --- /dev/null +++ b/src/messenger/storage.py @@ -0,0 +1,195 @@ +"""Приватное S3-хранилище: только байты и служебные операции над объектами. + +Метаданные вложений живут в PostgreSQL; этот модуль не знает о чатах и правах. +Ключ объекта всегда назначает сервер. Ошибки S3 преобразуются в два типа: +`StorageObjectMissing` (404) и `StorageUnavailable` (503), чтобы наружу не +уходили детали boto3/MinIO. +""" +from __future__ import annotations + +from dataclasses import dataclass +from datetime import datetime, timezone +from typing import Any, BinaryIO + +import anyio +from botocore.config import Config as BotoConfig +from botocore.exceptions import BotoCoreError, ClientError + +from .config import Config + +CHUNK_SIZE = 64 * 1024 +MISSING_CODES = {"404", "NoSuchKey", "NotFound", "NoSuchBucket"} + + +class StorageUnavailable(RuntimeError): + """S3/MinIO не ответил или вернул ошибку, которую нельзя исправить запросом.""" + + +class StorageObjectMissing(RuntimeError): + """Объект отсутствует в bucket (оригинал потерян или ключ неверен).""" + + +@dataclass(frozen=True) +class S3Object: + """Открытый поток объекта и его наблюдаемый размер.""" + + body: Any + size_bytes: int + content_type: str | None + + +@dataclass(frozen=True) +class ObjectInfo: + """Элемент листинга bucket для сверки.""" + + key: str + size_bytes: int + last_modified: datetime + + +def _is_missing(error: ClientError) -> bool: + response = getattr(error, "response", {}) or {} + code = str((response.get("Error") or {}).get("Code", "")) + status = int((response.get("ResponseMetadata") or {}).get("HTTPStatusCode", 0) or 0) + return code in MISSING_CODES or status == 404 + + +class S3Storage: + """Один boto3-клиент на процесс; вызовы уходят в рабочий поток.""" + + def __init__(self, config: Config) -> None: + self._bucket = config.s3_bucket + self._prefix = config.s3_key_prefix + boto_config = BotoConfig( + signature_version="s3v4", + s3={"addressing_style": "path"}, + connect_timeout=config.s3_connect_timeout_seconds, + read_timeout=config.s3_read_timeout_seconds, + retries={"max_attempts": config.s3_max_attempts, "mode": "standard"}, + max_pool_connections=32, + ) + import boto3 + + self._client = boto3.session.Session().client( + "s3", + endpoint_url=config.s3_endpoint, + region_name=config.s3_region, + aws_access_key_id=config.s3_access_key_id, + aws_secret_access_key=config.s3_secret_access_key, + config=boto_config, + ) + + @property + def bucket(self) -> str: + return self._bucket + + @property + def key_prefix(self) -> str: + return self._prefix + + def new_key(self, attachment_id: str) -> str: + """Ключ назначает сервер; filename и путь клиента в него не попадают.""" + return f"{self._prefix}{attachment_id}" + + async def ping(self) -> None: + """Готовность: листинг одного объекта под служебным префиксом. + + Это проверяет и доступность S3, и наличие bucket, и право ListBucket, + которое выдано API-пользователю только на префикс вложений. + """ + try: + await anyio.to_thread.run_sync(self._list_one) + except (BotoCoreError, ClientError, OSError) as exc: + raise StorageUnavailable("S3 не отвечает") from exc + + def _list_one(self) -> None: + self._client.list_objects_v2(Bucket=self._bucket, Prefix=self._prefix, MaxKeys=1) + + async def put( + self, + key: str, + file: BinaryIO, + *, + content_type: str, + size_bytes: int, + sha256: str, + md5_hex: str, + ) -> None: + """Загружает один объект и проверяет, что S3 сохранил ровно эти байты.""" + try: + response = await anyio.to_thread.run_sync( + lambda: self._client.put_object( + Bucket=self._bucket, + Key=key, + Body=file, + ContentLength=size_bytes, + ContentType=content_type, + Metadata={"sha256": sha256}, + ) + ) + except (BotoCoreError, ClientError, OSError) as exc: + raise StorageUnavailable("S3 не принял объект") from exc + etag = str(response.get("ETag", "")).strip('"').lower() + # Для одиночного PUT ETag — MD5 тела; это дешёвая проверка целостности + # передачи. Если S3 не вернул ETag, полагаемся на SHA-256 в метаданных. + if etag and etag != md5_hex.lower(): + try: + await self.delete(key) + except StorageUnavailable: + pass + raise StorageUnavailable("S3 сохранил объект с другим ETag") + + async def open(self, key: str) -> S3Object: + """Открывает объект для потоковой отдачи без redirect.""" + try: + response = await anyio.to_thread.run_sync( + lambda: self._client.get_object(Bucket=self._bucket, Key=key) + ) + except ClientError as exc: + if _is_missing(exc): + raise StorageObjectMissing("Объект отсутствует в S3") from exc + raise StorageUnavailable("S3 не отдал объект") from exc + except (BotoCoreError, OSError) as exc: + raise StorageUnavailable("S3 не отдал объект") from exc + return S3Object( + body=response["Body"], + size_bytes=int(response.get("ContentLength", 0)), + content_type=response.get("ContentType"), + ) + + async def delete(self, key: str) -> None: + try: + await anyio.to_thread.run_sync( + lambda: self._client.delete_object(Bucket=self._bucket, Key=key) + ) + except (BotoCoreError, ClientError, OSError) as exc: + raise StorageUnavailable("S3 не удалил объект") from exc + + async def list_objects(self) -> list[ObjectInfo]: + """Все объекты под префиксом вложений (страницы по 1000).""" + try: + return await anyio.to_thread.run_sync(self._list_all) + except (BotoCoreError, ClientError, OSError) as exc: + raise StorageUnavailable("S3 не отдал список объектов") from exc + + def _list_all(self) -> list[ObjectInfo]: + paginator = self._client.get_paginator("list_objects_v2") + result: list[ObjectInfo] = [] + for page in paginator.paginate(Bucket=self._bucket, Prefix=self._prefix): + for item in page.get("Contents", []) or []: + last_modified = item["LastModified"] + if last_modified.tzinfo is None: + last_modified = last_modified.replace(tzinfo=timezone.utc) + result.append( + ObjectInfo( + key=str(item["Key"]), + size_bytes=int(item.get("Size", 0)), + last_modified=last_modified, + ) + ) + return result + + async def close(self) -> None: + close = getattr(self._client, "close", None) + if close is not None: + await anyio.to_thread.run_sync(close) diff --git a/src/messenger/upload.py b/src/messenger/upload.py new file mode 100644 index 00000000..896ea5fb --- /dev/null +++ b/src/messenger/upload.py @@ -0,0 +1,100 @@ +"""Потоковый приём тела загрузки: диск вместо RAM и ранние лимиты.""" +from __future__ import annotations + +import hashlib +import os +import tempfile +from dataclasses import dataclass + +import anyio +from starlette.requests import ClientDisconnect, Request + +from .config import Config +from .errors import payload_too_large, unsupported_media_type +from .images import ImageInfo, ImageTooLarge, UnsupportedImage, inspect_image + +READ_CHUNK = 64 * 1024 + + +@dataclass +class SpooledImage: + """Принятое тело на временном диске и его измеренные характеристики.""" + + path: str + size_bytes: int + sha256: str + md5: str + info: ImageInfo + + def cleanup(self) -> None: + try: + os.unlink(self.path) + except OSError: + pass + + +async def receive_image(request: Request, *, expected_content_type: str, config: Config) -> SpooledImage: + """Читает ровно один файл, не поднимая всё тело в память. + + `request.stream()` отдаёт чанки по мере прихода; счётчик байт обрывает + передачу сразу после превышения предела. Временный файл нужен только как + staging до S3; после запроса он удаляется (или ОС уберёт его при падении + процесса). В PostgreSQL и локальном каталоге API оригинал не остаётся. + """ + handle = tempfile.NamedTemporaryFile(prefix="upload-", suffix=".bin", delete=False) + path = handle.name + size = 0 + sha = hashlib.sha256() + md5 = hashlib.md5() + try: + try: + async for chunk in request.stream(): + if not chunk: + continue + size += len(chunk) + if size > config.max_upload_bytes: + raise payload_too_large( + f"Файл больше {config.max_upload_bytes} байт" + ) + handle.write(chunk) + sha.update(chunk) + md5.update(chunk) + except ClientDisconnect as exc: + raise unsupported_media_type("Загрузка прервана клиентом") from exc + finally: + handle.close() + if size == 0: + raise unsupported_media_type("Пустое тело загрузки") + try: + info = await anyio.to_thread.run_sync( + lambda: inspect_image( + path, + expected_content_type=expected_content_type, + max_pixels=config.max_image_pixels, + ) + ) + except ImageTooLarge: + raise payload_too_large( + f"Изображение превышает {config.max_image_pixels} пикселей" + ) from None + except UnsupportedImage: + raise unsupported_media_type( + "Содержимое не является корректным PNG/JPEG" + ) from None + return SpooledImage( + path=path, + size_bytes=size, + sha256=sha.hexdigest(), + md5=md5.hexdigest(), + info=info, + ) + except BaseException: + try: + handle.close() + except Exception: + pass + try: + os.unlink(path) + except OSError: + pass + raise diff --git a/stack.yaml b/stack.yaml new file mode 100644 index 00000000..68a04b6e --- /dev/null +++ b/stack.yaml @@ -0,0 +1,325 @@ +# Docker Swarm stack лабораторной 4. +# +# Роли: Traefik (единственная публичная точка входа), api (2+ взаимозаменяемые +# реплики), PostgreSQL (метаданные), Valkey (общие сессии), MinIO (приватные +# байты вложений), minio-init (идемпотентный bootstrap bucket и прав), migrate +# (однократное применение схемы). Наружу опубликован только Traefik :8080; +# API, PostgreSQL, Valkey и MinIO портов не публикуют. +# +# Версия MinIO закреплена digest-ом; release виден в label образа +# RELEASE.2025-09-07T16-13-09Z. Для приложения тег задаёт scripts/deploy.sh. + +x-api-environment: &api-environment + APP_ENV: lab + APP_HOST: 0.0.0.0 + APP_PORT: "8080" + LOG_LEVEL: info + SESSION_STORE: redis + SESSION_TTL_SECONDS: "${SESSION_TTL_SECONDS:-3600}" + DB_POOL_SIZE: "5" + DB_MAX_OVERFLOW: "5" + DB_POOL_TIMEOUT_SECONDS: "2" + DB_CONNECT_TIMEOUT_SECONDS: "1.5" + DB_COMMAND_TIMEOUT_SECONDS: "2.5" + DB_STATEMENT_TIMEOUT_MS: "2000" + CACHE_TIMEOUT_SECONDS: "1" + GRACEFUL_SHUTDOWN_SECONDS: "5" + SHUTDOWN_DRAIN_SECONDS: "2" + S3_ENDPOINT: "http://minio:9000" + S3_REGION: "us-east-1" + S3_BUCKET: "messenger-attachments" + S3_KEY_PREFIX: "attachments/" + S3_CONNECT_TIMEOUT_SECONDS: "1.5" + S3_READ_TIMEOUT_SECONDS: "30" + S3_MAX_ATTEMPTS: "2" + MAX_UPLOAD_BYTES: "10485760" + MAX_IMAGE_PIXELS: "40000000" + ATTACHMENT_ORPHAN_GRACE_SECONDS: "3600" + ATTACHMENT_FAULT_MODE: "none" + DATABASE_URL_FILE: /run/secrets/database_url + CACHE_URL_FILE: /run/secrets/cache_url + CURSOR_SECRET_FILE: /run/secrets/cursor_secret + S3_ACCESS_KEY_ID_FILE: /run/secrets/s3_access_key_id + S3_SECRET_ACCESS_KEY_FILE: /run/secrets/s3_secret_access_key + +services: + traefik: + image: traefik:v3.5.4 + command: + - --providers.swarm=true + - --providers.swarm.endpoint=unix:///var/run/docker.sock + - --providers.swarm.exposedByDefault=false + - --providers.swarm.network=backend + - --providers.swarm.watch=true + - --entryPoints.web.address=:8080 + - --log.level=INFO + - --accesslog=false + ports: + - target: 8080 + published: 8080 + protocol: tcp + mode: ingress + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + networks: + - backend + deploy: + replicas: 1 + placement: + constraints: + - node.role == manager + resources: + limits: + cpus: "0.50" + memory: 128M + restart_policy: + condition: any + delay: 5s + + postgres: + image: postgres:16.15-bookworm@sha256:0ea6700a3b4f0ae6ce746519073558aed4d88a79d8d07622a9a644946c7319c4 + environment: + POSTGRES_USER: messenger + POSTGRES_DB: messenger + POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password + POSTGRES_INITDB_ARGS: "--auth-host=scram-sha-256" + secrets: + - source: lab4_postgres_password + target: postgres_password + volumes: + - pgdata:/var/lib/postgresql/data + networks: + - backend + healthcheck: + test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"] + interval: 5s + timeout: 3s + retries: 12 + start_period: 10s + deploy: + replicas: 1 + resources: + limits: + cpus: "2.0" + memory: 512M + restart_policy: + condition: any + delay: 5s + + valkey: + image: valkey/valkey:8.0.11-trixie@sha256:4436c94fc34ce4af0354b9379d433a1f258998fb955f995c89822f98c14a8cab + command: + - valkey-server + - --appendonly + - "yes" + - --appendfsync + - everysec + - --save + - "" + volumes: + - valkeydata:/data + networks: + - backend + healthcheck: + test: ["CMD", "valkey-cli", "ping"] + interval: 5s + timeout: 3s + retries: 12 + start_period: 5s + deploy: + replicas: 1 + resources: + limits: + cpus: "1.0" + memory: 256M + restart_policy: + condition: any + delay: 5s + + minio: + # RELEASE.2025-09-07T16-13-09Z; digest фиксирует именно проверенный образ. + image: minio/minio@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e + entrypoint: ["/bin/sh", "-c"] + command: + - >- + export MINIO_ROOT_USER=$$(cat /run/secrets/s3_root_user); + export MINIO_ROOT_PASSWORD=$$(cat /run/secrets/s3_root_password); + exec /usr/bin/minio server /data --console-address :9001 + environment: + MINIO_BROWSER: "off" + secrets: + - source: lab4_s3_root_user + target: s3_root_user + - source: lab4_s3_root_password + target: s3_root_password + volumes: + - miniodata:/data + networks: + - backend + healthcheck: + test: ["CMD", "curl", "-f", "http://127.0.0.1:9000/minio/health/live"] + interval: 5s + timeout: 3s + retries: 12 + start_period: 10s + deploy: + replicas: 1 + resources: + limits: + cpus: "1.0" + memory: 512M + restart_policy: + condition: any + delay: 5s + + minio-init: + # Тот же проверенный MinIO-образ: в нём уже есть /bin/sh и mc. + image: minio/minio@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e + entrypoint: ["/bin/sh", "/etc/minio-init.sh"] + environment: + S3_ENDPOINT: "http://minio:9000" + S3_BUCKET: "messenger-attachments" + S3_POLICY_NAME: "messenger-attachments-rw" + MC_CONFIG_DIR: "/tmp/.mc" + MINIO_ROOT_USER_FILE: /run/secrets/s3_root_user + MINIO_ROOT_PASSWORD_FILE: /run/secrets/s3_root_password + S3_ACCESS_KEY_ID_FILE: /run/secrets/s3_access_key_id + S3_SECRET_ACCESS_KEY_FILE: /run/secrets/s3_secret_access_key + secrets: + - source: lab4_s3_root_user + target: s3_root_user + - source: lab4_s3_root_password + target: s3_root_password + - source: lab4_s3_access_key_id + target: s3_access_key_id + - source: lab4_s3_secret_access_key + target: s3_secret_access_key + configs: + - source: lab4_minio_init + target: /etc/minio-init.sh + mode: 0555 + networks: + - backend + deploy: + replicas: 1 + restart_policy: + condition: none + resources: + limits: + cpus: "0.5" + memory: 128M + + migrate: + image: ${API_IMAGE:-mtusi-messenger-lab4:4.0.0} + command: + - /bin/sh + - -c + - "until alembic upgrade head; do echo migration waiting for postgres; sleep 2; done" + environment: + DATABASE_URL_FILE: /run/secrets/database_url + secrets: + - source: lab4_database_url + target: database_url + networks: + - backend + deploy: + replicas: 1 + resources: + limits: + cpus: "1.0" + memory: 256M + restart_policy: + condition: none + + api: + image: ${API_IMAGE:-mtusi-messenger-lab4:4.0.0} + environment: + <<: *api-environment + secrets: + - source: lab4_database_url + target: database_url + - source: lab4_cache_url + target: cache_url + - source: lab4_cursor_secret + target: cursor_secret + - source: lab4_s3_access_key_id + target: s3_access_key_id + - source: lab4_s3_secret_access_key + target: s3_secret_access_key + networks: + - backend + stop_grace_period: 15s + healthcheck: + test: ["CMD", "python", "-m", "messenger.healthcheck"] + interval: 5s + timeout: 3s + start_period: 15s + retries: 3 + deploy: + replicas: 2 + labels: + - traefik.enable=true + - traefik.swarm.network=backend + - traefik.http.routers.messenger.rule=PathPrefix(`/`) + - traefik.http.routers.messenger.entrypoints=web + - traefik.http.routers.messenger.service=messenger + - traefik.http.services.messenger.loadbalancer.server.port=8080 + - traefik.http.services.messenger.loadbalancer.server.scheme=http + - traefik.http.services.messenger.loadbalancer.healthcheck.path=/health/ready + - traefik.http.services.messenger.loadbalancer.healthcheck.interval=2s + - traefik.http.services.messenger.loadbalancer.healthcheck.unhealthyinterval=1s + - traefik.http.services.messenger.loadbalancer.healthcheck.timeout=1s + - traefik.http.services.messenger.loadbalancer.healthcheck.scheme=http + update_config: + parallelism: 1 + order: start-first + delay: 5s + monitor: 10s + failure_action: rollback + rollback_config: + parallelism: 1 + order: start-first + delay: 5s + restart_policy: + condition: any + delay: 1s + max_attempts: 0 + resources: + limits: + cpus: "1.0" + memory: 512M + reservations: + cpus: "0.25" + memory: 128M + +configs: + lab4_minio_init: + file: ./scripts/minio-init.sh + +secrets: + lab4_database_url: + external: true + lab4_cache_url: + external: true + lab4_postgres_password: + external: true + lab4_cursor_secret: + external: true + lab4_s3_root_user: + external: true + lab4_s3_root_password: + external: true + lab4_s3_access_key_id: + external: true + lab4_s3_secret_access_key: + external: true + +volumes: + pgdata: + valkeydata: + miniodata: + +networks: + backend: + driver: overlay + attachable: true diff --git a/student-tests/README.md b/student-tests/README.md new file mode 100644 index 00000000..7368d231 --- /dev/null +++ b/student-tests/README.md @@ -0,0 +1,27 @@ +# Собственные проверки лабораторной 4 + +```sh +make student-test BASE_URL=http://127.0.0.1:8080 +python3 student-tests/upload_experiment.py --concurrency 12 +python3 student-tests/s3_outage_probe.py +python3 student-tests/attachment_failover.py +python3 student-tests/reconcile_probe.py +python3 student-tests/interrupted_upload.py +``` + +| Файл | Что проверяет | +| --- | --- | +| `harness.py` | клиент публичного `tests/client.py`, сбор `X-Instance-Id`, история, ожидание готовности | +| `test_lab3.py` | lab3-инварианты: ≥2 реплики на одном токене, конкурентная идемпотентность, 409 на другое тело | +| `test_lab4.py` | PNG/JPEG, SHA-256, MIME по содержимому, 413/415/400/404, чужой чат, `attachment_ids`, idempotency с вложениями, ранний 413 по `Content-Length` | +| `upload_experiment.py` | 12 одновременных загрузок реального PNG ~7.3 МиБ; пик RSS контейнеров API через `docker stats`; JSON в `evidence/upload-memory.json` | +| `s3_outage_probe.py` | остановка `lab4_minio`, readiness/upload во время отказа и восстановление; JSON в `evidence/s3-outage.json` | +| `attachment_failover.py` | upload → stop обслужившей реплики → download через другую; JSON в `evidence/attachment-failover.json` | +| `reconcile_probe.py` | fault после S3 PUT, dry-run/apply reconciler, grace, повторный apply; JSON в `evidence/reconcile.json` | +| `interrupted_upload.py` | обрыв тела клиентом: размеры metadata/objects до/после равны, pending-строка и объект не появляются | + +Все проверки идут через `BASE_URL` (по умолчанию `http://127.0.0.1:8080`), не +печатают токены и не меняют публичные `tests/`. `upload_experiment.py` требует +Pillow только для генерации большого изображения; API использует Pillow для +проверки загруженного изображения. `s3_outage_probe.py` управляет только +лабораторным сервисом `minio` и всегда возвращает его в состояние 1 реплики. diff --git a/student-tests/attachment_failover.py b/student-tests/attachment_failover.py new file mode 100644 index 00000000..8c4d7dc1 --- /dev/null +++ b/student-tests/attachment_failover.py @@ -0,0 +1,96 @@ +#!/usr/bin/env python3 +"""Upload -> остановка обслужившей реплики -> download через другую. + +Публичный failover-тест проверяет сообщения, но не гарантирует, что остановлена +именно реплика, принявшая файл. Этот probe выбирает attachment, загруженный +конкретным X-Instance-Id, останавливает его через scripts/stop-one.cmd и +скачивает файл через LB. После проверки восстанавливает 2 реплики. +""" +from __future__ import annotations + +import argparse +import json +import os +import subprocess +import sys +import time +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "tests")) +from client import Client, Failure # noqa: E402 + +PNG = (ROOT / "tests" / "fixtures" / "sample.png").read_bytes() + + +def main() -> int: + parser = argparse.ArgumentParser(description="Failover вложения") + parser.add_argument("--base-url", default=os.environ.get("BASE_URL", "http://127.0.0.1:8080")) + parser.add_argument("--attempts", type=int, default=20) + parser.add_argument("--output", default="evidence/attachment-failover.json") + args = parser.parse_args() + api = Client(args.base_url, None, timeout=10) + alice, bob, _eve, chat = api.bootstrap() + chosen = None + observed = set() + for _ in range(args.attempts): + attachment, content = api.attachment(alice, chat) + instance = api.call( + "GET", "/api/v1/attachments/" + attachment["id"], actor=alice, schema="Attachment" + )["headers"]["X-Instance-Id"] + observed.add(instance) + chosen = (attachment, content, instance) + if len(observed) >= 2: + break + if chosen is None: + raise SystemExit("no attachment uploaded") + attachment, content, target = chosen + report = {"target_instance": target, "attachment_id": attachment["id"], "observed_instances": sorted(observed)} + env = dict(os.environ) + env["TARGET_INSTANCE_ID"] = target + suffix = ".cmd" if os.name == "nt" else ".sh" + proc = subprocess.run( + [str(ROOT / "scripts" / ("stop-one" + suffix))], + env=env, + cwd=str(ROOT), + capture_output=True, + text=True, + timeout=30, + ) + report["stop_exit"] = proc.returncode + try: + if proc.returncode != 0: + raise SystemExit("stop-one failed: " + (proc.stderr or "")[:300]) + deadline = time.monotonic() + 10 + while time.monotonic() < deadline: + try: + api.call("GET", "/health/ready", schema="Health") + break + except Failure: + time.sleep(0.3) + download = api.call("GET", "/api/v1/attachments/" + attachment["id"] + "/content", actor=bob) + served_by = download["headers"]["X-Instance-Id"] + report["download_matches"] = download["bytes"] == content + report["download_served_by"] = served_by + report["downloaded_from_other_replica"] = served_by != target + report["metadata"] = api.call( + "GET", "/api/v1/attachments/" + attachment["id"], actor=bob, schema="Attachment" + )["json"]["status"] + finally: + restore = subprocess.run( + [str(ROOT / "scripts" / ("restore" + suffix))], + cwd=str(ROOT), + capture_output=True, + text=True, + timeout=120, + ) + report["restore_exit"] = restore.returncode + output = Path(args.output) + output.parent.mkdir(parents=True, exist_ok=True) + output.write_text(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8") + print(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True)) + return 0 if report.get("download_matches") and report.get("downloaded_from_other_replica") else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/student-tests/fixtures/sample.jpg b/student-tests/fixtures/sample.jpg new file mode 100644 index 0000000000000000000000000000000000000000..5968d308effef76497f9945ea512060d792eea67 GIT binary patch literal 7849 zcmbVR3s_TEwmv*kG*l^7z%ngdwG|BtBad-P!A!McMTGK5z*>xmNP&)wC{++RQ>fa4 zl#3V;6sb@iAt+)8DX64sk*7tTK8m991_2=;1d^P)_Ss2z=zMqX#mBe5bIxAtU;kcv zy`b(>Pl&f1?6=qxYH9?b27d_Z4`L&sp{|bp!jC5WWz1tRG&LDaEv+}^y~%v@O>L&O z_JW0PzqMeY?m}(txAfoAU9?zFPw!0~gC+Wlm%P1LZ!r?0rU8328S@#8`HL55FIfD4 z{-J&)bmtM3YJbyETSlnss%hw|QNIz!fRmv{{}75FHFd!FhSt3KOl|m}=q*BBO+!On zQv;!fuOr|+p{dJwd+FMb-&o}0t+j0bVvBDQ&d*!Eq40*DYyFG&Eq4b;&1dQxEP2Q9 zgB2z#SFxOHKU{{L|3Y zWGr3##@ipeXnF5nw9Mk0d5bqBoG-jFf4QaW3%%XJ^-TTut)6}`j7*~~`_BxE`hQub zGHlwehs2v2YH)ZOx&)h$R(P^F$1da>HM4H;1f|E%I0;<51zf``myWm#8N2(8;%u^G zZn@@L|9#g>0aqtLR@JmD%{AkOYrdZ1NmY{_E5yln7rn_{s8tlH-eI=}*Ayp;yj zFc6ll%&bjOS)Qzi2y|?2m{nh@_5z1X%|-Cgbll{#m=K591&)`Rv!Wkndzu=2HtOH} z;n8DRo&gVU47dU@6N_>q*4SiiLXV!IM@Yz@^S)ed&AP>H(Fx%1dRfq#w!y!dwOWsL zL-8cvYh!(m`$Q3Dt*7O-xuhd~yi&lu&6ae*qQLt_XOLvFtc&C~4S(6KPm8%2_mvMt zoZCVX;W2!A>5rCGiciC=h64-LF{mx!ZIYh06oE%AY>1Pj_J(_GmPd%Lzc<=A=;djb z$BBL@Fh4^Pc7KvjTC*e~alOdWv&=M;BG$J(j<-*Zs5aFqa=3KF!~V)zil}>^BFZ*7 zOfN&7kDHQp&Eu9$Ik8?p?0=mV$eeuMLM}z53kUr&o%O%NM&xbnA|pgYnXU!2da-rW z#Km~&6dCrBAg8qy9j;c9E6-9MwyrCHBW9Pijo0V%^y)!O(9q`0ZR z<(*6cRZ6}nBEqomHH@uFo*Iy(@-esn4wXm=3NKWcdO=&oU$KD)1AUC8BhFJD?m`~} zdcjpPTAvfU2{3_)c_-;}8On4sPeCUowr)^T)tl4$3zpE`*?7H~6|=wkG0eMS*0df{$ZEAIxr8eLo_ z-&+{SKtA}y?EL7ZJoo8HG~ii!Jkv?=`P5G3qJQ``9?o1 z4AHSqb35%Bz==Z9%i_iW@1Lc|8{9xl019Yu6_J!ICLJ*#Skckz4jsK_#IxzZ10hct zy%d2*5sKzUFQyDjQ3N8cPQWZ7bo4@D=auM%LMe(t%20ZzNf86_6J-#b9Z9FLC?e@m zo1ChC+qTCthQrU>WJ7n|V`&ZtoGovYb-m;hXKCF?%-PKQaeL29wf!jI`irhlG85ni zC+P%Kb)Bx0$jqhlDI%q(@$32$xW4GAWPbyEAYf?n*sDHIx?AEMX6k$sdZmt)T zb);h1Hh&aad3m-*I`Z%eicsTqaBM~f_bT2xlzzb$*Ns{KgtN_y!)%GzSjr$1dN*9V zdRm)Sq$CSRz4jq16N-4|tK_*{(NT6LS*0PJt#=eu@-bFqaCkhWo!vbudSN2>ySw2Pp6I~&A2W6B ze`5-{>F#N!dKwGNy4TM<83%kF*3USbN#=q0-PW%nH<<>WIlrRNSK%+dN`KL#?Hk)X z!(U<$37v`$1PV9&R}ylW{GB>lkftCL{w+sDXS^62i7)rWk?&&Aoge}dw|`5gkX zRFoj#_VES_Is$v!-hOgK^h;m%PmU037#oURDI$bi?s}mq{SmLS#rgYx*tNBWSv8%= zg5)2#|KMR6Pi*|u^S|v%+ipBG?b+c zn`vF0`XMjilNyL2O{O8{;~pc{ER1pw2A8?*(`v+Av4K)1t7kY&)WyD8wzk7_ux7|E z=5X%mKq#nMp7jh*q8C|SM&{_CxaLbMzUGBO7XD;YRJJEeuQVCk*D+T+>~>dauRH>fsa6sBx6EYy0 zSC@KIiMgAgwp2bs^=2X}QO{P-*vXVKn${9z%6mHcja)eAe=ycwy z?^FwZ7D&fBuG#sX#=HaC^aq?Q`YOIK`E1f5!~rTXNWYvSq#YN&NE}>2A-xq#<8yTa zAbkkwG{bdL3R7%^iur{BEey5*0#E?emJq6FLGvtOG`7Wk{Fw@lD8!l0z+opu@;--} zT=h^P(7$;-XGh(nFGa+YV|kow6p>9%j9KH8kaZ3(^ri?lIgcU|tfirAUu^(T2M*)EcW-Nz+K=wG}ba8blNBxKj$ z>Pk)&r;pZAgb@vZY;ThV>_*j-o}_;o!5@Gi_%YdNEBnrnr`A@v`0+srGpuRtpA{;4VxQ`FaCezGjuSS*E_Vr6^$?l=2#t^N; z(~g^|usN2llUac^dldVL=pD{9@9>61?t#c`8&5IlXaroyeRGu-EO!Wy42sEKeJ z0}On$0DZh<+hPb?>r;l@eyb=sh1m}@!yupp>Kt>1@xakNBdv#|lW>a`8FkdqQO)&2 zD~S)l03E=jDSZNljls{C(IK))c!++%dQ^c|3A^Gj{d(Z^_@@T=IG{cYl2sKy+RB+_wfV8f$LNP}bX{@K2AVV&7c z2rh6B!Hr1pBB;p_WUjf*uh4Wfg;}*;HC{D)1hY~4V~%?+l&y5n$Wiu)DYzk|!z5}E z8|hAy?iyJ)w%edaGXpo8EKZatIAk6YqG&uJT88L2q`A$IF~IxAW=5Zh#NuvMAq1!Y zVAQT6EDS|Kfcw=HXs|#t9bc5~DwH?)i4qHK0LC&ON(fcAs%#MPcxz6xiYIo;SzDBH zQxc5HUf1+4;lPXws-gxuAx&uG5f>B(Feamm47v(QH(Py|B94q&v+n4Oi#BpV8h=+o z&+&54y3Y7kijXXqp3Tl|z5Me=XhfT8tk{ob3pmK(qYA@0C*+h#tWZ7$IT0aO6Br7Gkf*k17sb$$z7;K z?}g$i&=jjg4PiLgGKuDfPZO0VgskWB`+Anj{32_k&McamEX-3Lj=8Za4tpA120u|8 zf(2H|orM0ysQLMN)mi-A_KOpYhAuP^$c6rmKHcILRCvNrP=y+%N(rghJ1|kScSJud z+pn^JOprUiX11Ggk(2C_-20+7%13&IAUZ+Z-a;>dBDgU^MsEi}-2}*ys#% z*i`=Xvb^zvG#;j&PM2ZY3f)l-&wQ#Mrix5{xJc3?8oyicz{nzATyR~JWx)Wa2nZPw zb!W(TXDh!eZ(m6fHdFOIjk&+?e+3OhI2u^wfAzM=H;-HP2wJ?VP0`T0voKj6Dw2%^ z_!cJ0L)o&CKm(`Z5q8PBIGdW1{V*11riB*(g3|(zYWXBZv~3XWIb6;Dy=-)GSEaro zf0y814cHSaiQ(h#@^{iWjZUyE)6f8}V9kkiF|=eV4GhNgBAU#aYz;Rw=?vCZ{v`BzUNeue!$=F$;zs-sEhV?r-l%xIs2 zNk(#TABxM~;i91e*(i%M0<+qTS!dK|QHlly-gC~d5FcTfRaf0fxMQjg?TE+oedpya zD5JrUH2R@x>VTArgj7k=*WsaG2f}jV^DrqWYz}c(FBnfC9wX$HqZv}bsR7VwR0WxCB zuY_53)bhdAR%VFQgZ&zAI>L2>@AAKZb}-R~0i7|t2@c-VnD_yz17b`~R?OI<23y>e zZ}cDZ+;r^Grv=NZsuG Client: + return Client(os.environ.get("BASE_URL", DEFAULT_BASE_URL), None, timeout) + + +def instance_ids(api: Client, actor: dict, count: int = 40) -> set[str]: + """Собирает X-Instance-Id разных ответов через LB, не доверяя одному запросу.""" + seen: set[str] = set() + for _ in range(count): + seen.add( + api.call("GET", "/api/v1/users/me", actor=actor, schema="User")["headers"][ + "X-Instance-Id" + ] + ) + return seen + + +def wait_ready(timeout: float = 120.0) -> None: + api = client(timeout=5) + deadline = time.monotonic() + timeout + last = "no attempts" + while time.monotonic() < deadline: + try: + api.call("GET", "/health/ready", schema="Health") + return + except (Failure, OSError) as exc: + last = str(exc) + time.sleep(0.5) + raise Failure("stand did not become ready within %.0fs: %s" % (timeout, last)) + + +def history(api: Client, actor: dict, chat_id: str) -> list[dict]: + items: list[dict] = [] + cursor = None + for _ in range(1000): + path = "/api/v1/chats/%s/messages?limit=100" % chat_id + if cursor is not None: + path += "&cursor=" + cursor + page = api.call("GET", path, actor=actor, schema="MessagePage")["json"] + items.extend(page["items"]) + cursor = page["next_cursor"] + if cursor is None: + return items + raise Failure("history pagination exceeded safety bound") + + +def unique_key() -> str: + return uuid.uuid4().hex diff --git a/student-tests/idempotency_probe.py b/student-tests/idempotency_probe.py new file mode 100644 index 00000000..42dcdc56 --- /dev/null +++ b/student-tests/idempotency_probe.py @@ -0,0 +1,53 @@ +#!/usr/bin/env python3 +"""Печатает обезличенную сводку конкурентного повтора одного Idempotency-Key.""" +from __future__ import annotations + +import json +import threading +import time +from concurrent.futures import ThreadPoolExecutor +from uuid import uuid4 + +import harness + + +def main() -> int: + api = harness.client() + alice, bob, _, chat = api.bootstrap() + key = uuid4().hex + text = "probe-" + uuid4().hex + workers = 32 + barrier = threading.Barrier(workers) + + def worker(_: int) -> dict: + local = harness.client(10) + barrier.wait() + return local.message(alice, chat, text, key=key) + + started = time.monotonic() + with ThreadPoolExecutor(max_workers=workers) as pool: + responses = list(pool.map(worker, range(workers))) + elapsed = time.monotonic() - started + bodies = [r["json"] for r in responses] + instances = sorted({r["headers"]["X-Instance-Id"] for r in responses}) + messages = [m for m in harness.history(api, bob, chat["id"]) if m["text"] == text] + summary = { + "concurrent_requests": workers, + "elapsed_seconds": round(elapsed, 3), + "statuses": sorted({r["status"] for r in responses}), + "distinct_instances": instances, + "distinct_message_ids": len({b["id"] for b in bodies}), + "history_matches": len(messages), + "all_responses_identical": all(b == bodies[0] for b in bodies), + } + print(json.dumps(summary, ensure_ascii=False, indent=2)) + return 0 if ( + summary["statuses"] == [201] + and summary["distinct_message_ids"] == 1 + and summary["history_matches"] == 1 + and len(instances) >= 2 + ) else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) \ No newline at end of file diff --git a/student-tests/interrupted_upload.py b/student-tests/interrupted_upload.py new file mode 100644 index 00000000..235f7406 --- /dev/null +++ b/student-tests/interrupted_upload.py @@ -0,0 +1,128 @@ +#!/usr/bin/env python3 +"""Прерывание загрузки: клиент обрывает тело, мусор не остаётся. + +Сценарий: + * считаем metadata_rows/objects через dry-run reconciler; + * открываем raw TCP, отправляем заголовки с Content-Length 5 MB и только + 1 KiB PNG, затем закрываем запись; + * ждём и повторяем dry-run: счётчики не должны измениться. +""" +from __future__ import annotations + +import argparse +import json +import os +import socket +import subprocess +import sys +import time +import urllib.parse +import uuid +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "tests")) +from client import Client # noqa: E402 + +PNG = (ROOT / "tests" / "fixtures" / "sample.png").read_bytes() +STACK = os.environ.get("STACK_NAME", "lab4") +IMAGE = os.environ.get("API_IMAGE", "mtusi-messenger-lab4:4.0.0") + + +def docker(*args: str, check: bool = True) -> subprocess.CompletedProcess: + return subprocess.run(["docker", *args], check=check, capture_output=True, text=True) + + +def reconcile_dry() -> dict: + name = "lab4-abort-recon-" + uuid.uuid4().hex[:8] + secrets = str(ROOT / "secrets") + args = [ + "run", "-d", "--name", name, + "--user", "0", "--network", STACK + "_backend", + "-v", secrets + ":/run/secrets:ro", + "-e", "APP_ENV=lab", + "-e", "APP_PORT=8080", + "-e", "SESSION_TTL_SECONDS=3600", + "-e", "DATABASE_URL_FILE=/run/secrets/database_url", + "-e", "CACHE_URL_FILE=/run/secrets/cache_url", + "-e", "CURSOR_SECRET_FILE=/run/secrets/cursor_secret", + "-e", "S3_ENDPOINT=http://minio:9000", + "-e", "S3_REGION=us-east-1", + "-e", "S3_BUCKET=messenger-attachments", + "-e", "S3_ACCESS_KEY_ID_FILE=/run/secrets/s3_access_key_id", + "-e", "S3_SECRET_ACCESS_KEY_FILE=/run/secrets/s3_secret_access_key", + IMAGE, "python", "-m", "messenger.reconcile", "--dry-run", "--grace-seconds", "3600", + ] + try: + docker(*args) + docker("wait", name) + logs = docker("logs", name).stdout + finally: + docker("rm", "-f", name, check=False) + start, end = logs.find("{"), logs.rfind("}") + if start < 0 or end < start: + raise SystemExit("reconcile did not print JSON: " + logs[-500:]) + return json.loads(logs[start:end + 1]) + + +def abort_upload(base_url: str, chat_id: str, token: str) -> dict: + parsed = urllib.parse.urlparse(base_url) + host, port = parsed.hostname, parsed.port or 80 + request = ( + "POST /api/v1/chats/%s/attachments?filename=abort.png HTTP/1.1\r\n" + "Host: %s\r\n" + "Authorization: Bearer %s\r\n" + "Content-Type: image/png\r\n" + "Content-Length: 5000000\r\n" + "Connection: close\r\n\r\n" % (chat_id, host, token) + ).encode("ascii") + PNG[:1024] + sock = socket.create_connection((host, port), timeout=5) + try: + sock.sendall(request) + try: + sock.shutdown(socket.SHUT_WR) + except OSError: + pass + try: + sock.settimeout(2) + response = sock.recv(256) + except OSError: + response = b"" + finally: + sock.close() + return {"sent_bytes": 1024, "response_prefix": response[:80].decode("latin-1", "replace")} + + +def main() -> int: + parser = argparse.ArgumentParser(description="Прерывание upload и проверка отсутствия мусора") + parser.add_argument("--base-url", default=os.environ.get("BASE_URL", "http://127.0.0.1:8080")) + parser.add_argument("--output", default="evidence/interrupted-upload.json") + args = parser.parse_args() + + api = Client(args.base_url, None, timeout=10) + alice, _bob, _eve, chat = api.bootstrap() + before = reconcile_dry() + aborted = abort_upload(args.base_url, chat["id"], alice["token"]) + time.sleep(1.5) + after = reconcile_dry() + report = { + "before": {"metadata_rows": before.get("metadata_rows"), "objects": before.get("objects")}, + "after": {"metadata_rows": after.get("metadata_rows"), "objects": after.get("objects")}, + "delta_rows": (after.get("metadata_rows") or 0) - (before.get("metadata_rows") or 0), + "delta_objects": (after.get("objects") or 0) - (before.get("objects") or 0), + "aborted_request": aborted, + "ready": True, + } + try: + api.call("GET", "/health/ready", schema="Health") + except Exception: + report["ready"] = False + output = Path(args.output) + output.parent.mkdir(parents=True, exist_ok=True) + output.write_text(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8") + print(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True)) + return 0 if report["delta_rows"] == 0 and report["delta_objects"] == 0 and report["ready"] else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/student-tests/reconcile_probe.py b/student-tests/reconcile_probe.py new file mode 100644 index 00000000..fd671bf4 --- /dev/null +++ b/student-tests/reconcile_probe.py @@ -0,0 +1,157 @@ +#!/usr/bin/env python3 +"""Сценарий согласованности: pending-строка + объект после отказа S3/БД. + +Поднимает одноразовый API-контейнер с ATTACHMENT_FAULT_MODE=after_s3_put, +заставляет его загрузить файл (S3 PUT прошёл, COMMIT в PostgreSQL — нет), +затем запускает reconciler в dry-run и apply. Проверяет, что: + * свежий pending-мусор не удаляется при большом grace; + * после grace удаляются и объект, и pending-строка; + * готовое (используемое) вложение не удаляется; + * повторный apply идемпотентен. +""" +from __future__ import annotations + +import argparse +import json +import os +import subprocess +import sys +import time +import urllib.error +import urllib.request +import uuid +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "tests")) +from client import Client, Failure # noqa: E402 + +PNG = (ROOT / "tests" / "fixtures" / "sample.png").read_bytes() +STACK = os.environ.get("STACK_NAME", "lab4") +IMAGE = os.environ.get("API_IMAGE", "mtusi-messenger-lab4:4.0.0") +NETWORK = STACK + "_backend" +FAULT_API = "lab4-reconcile-fault" +FAULT_PORT = 18099 + + +def docker(*args: str, check: bool = True) -> subprocess.CompletedProcess: + return subprocess.run(["docker", *args], check=check, capture_output=True, text=True) + + +def common_args() -> list[str]: + secrets = str(ROOT / "secrets") + return [ + "--user", "0", + "--network", NETWORK, + "-v", secrets + ":/run/secrets:ro", + "-e", "APP_ENV=lab", + "-e", "APP_PORT=8080", + "-e", "SESSION_TTL_SECONDS=3600", + "-e", "DATABASE_URL_FILE=/run/secrets/database_url", + "-e", "CACHE_URL_FILE=/run/secrets/cache_url", + "-e", "CURSOR_SECRET_FILE=/run/secrets/cursor_secret", + "-e", "S3_ENDPOINT=http://minio:9000", + "-e", "S3_REGION=us-east-1", + "-e", "S3_BUCKET=messenger-attachments", + "-e", "S3_ACCESS_KEY_ID_FILE=/run/secrets/s3_access_key_id", + "-e", "S3_SECRET_ACCESS_KEY_FILE=/run/secrets/s3_secret_access_key", + ] + + +def wait_http(url: str, deadline_seconds: float = 60.0) -> None: + deadline = time.monotonic() + deadline_seconds + last = "no attempt" + while time.monotonic() < deadline: + try: + with urllib.request.urlopen(url, timeout=3) as response: + if response.status == 200: + return + except Exception as exc: # noqa: BLE001 - diagnostics only + last = type(exc).__name__ + time.sleep(0.5) + raise SystemExit("fault API did not become ready: " + last) + + +def reconcile(*mode: str) -> dict: + name = "lab4-reconcile-" + uuid.uuid4().hex[:10] + try: + docker("run", "-d", "--name", name, *common_args(), IMAGE, "python", "-m", "messenger.reconcile", *mode) + code = int(docker("wait", name).stdout.strip() or "1") + logs = docker("logs", name).stdout + finally: + docker("rm", "-f", name, check=False) + start, end = logs.find("{"), logs.rfind("}") + if start < 0 or end < start: + raise SystemExit("reconcile did not print JSON: " + logs[-500:]) + report = json.loads(logs[start:end + 1]) + report["exit_code"] = code + return report + + +def main() -> int: + parser = argparse.ArgumentParser(description="Проверка reconciler") + parser.add_argument("--base-url", default=os.environ.get("BASE_URL", "http://127.0.0.1:8080")) + parser.add_argument("--output", default="evidence/reconcile.json") + args = parser.parse_args() + + api = Client(args.base_url, None, timeout=10) + alice, bob, _eve, chat = api.bootstrap() + used, used_content = api.attachment(alice, chat) + report: dict = {"used_attachment": used["id"]} + + docker("run", "-d", "--name", FAULT_API, "-p", "18099:8080", *common_args(), + "-e", "ATTACHMENT_FAULT_MODE=after_s3_put", IMAGE, "python", "-m", "messenger") + try: + wait_http("http://127.0.0.1:18099/health/ready") + fault_client = Client("http://127.0.0.1:18099", None, timeout=20) + pending = fault_client.call( + "POST", + "/api/v1/chats/%s/attachments?filename=pending.png" % chat["id"], + 503, + actor=alice, + raw=PNG, + headers={"Content-Type": "image/png"}, + ) + report["fault_upload"] = { + "status": pending["status"], + "error": pending["json"]["error"]["code"], + "instance": pending["headers"].get("X-Instance-Id"), + } + finally: + docker("rm", "-f", FAULT_API, check=False) + + # Свежий pending-мусор должен пережить большой grace. + dry = reconcile("--dry-run", "--grace-seconds", "3600") + report["dry_run_fresh"] = { + "would_delete_objects": dry.get("would_delete_objects"), + "would_delete_rows": dry.get("would_delete_rows"), + "fresh_kept": any(item.get("action") == "keep_fresh" for item in dry.get("plan", [])), + } + time.sleep(2.0) + applied = reconcile("--apply", "--grace-seconds", "1") + report["apply"] = { + "deleted_objects": applied.get("deleted_objects"), + "deleted_rows": applied.get("deleted_rows"), + "missing_ready": len(applied.get("missing_ready", [])), + } + again = reconcile("--apply", "--grace-seconds", "1") + report["apply_again"] = { + "deleted_objects": again.get("deleted_objects"), + "deleted_rows": again.get("deleted_rows"), + } + # Готовое вложение не тронуто и скачивается байт-в-байт. + try: + downloaded = api.call("GET", "/api/v1/attachments/" + used["id"] + "/content", actor=bob)["bytes"] + report["used_download_matches"] = downloaded == used_content + except Failure as exc: + report["used_download_matches"] = False + report["used_download_error"] = str(exc) + output = Path(args.output) + output.parent.mkdir(parents=True, exist_ok=True) + output.write_text(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8") + print(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True)) + return 0 if report.get("used_download_matches") and report["apply"]["deleted_rows"] >= 1 else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/student-tests/run_all.py b/student-tests/run_all.py new file mode 100644 index 00000000..e76c1ca7 --- /dev/null +++ b/student-tests/run_all.py @@ -0,0 +1,32 @@ +#!/usr/bin/env python3 +"""Запуск собственных проверок лабораторной 4.""" +from __future__ import annotations + +import argparse +import os +import sys +import unittest +from pathlib import Path + +HERE = Path(__file__).resolve().parent + + +def main() -> int: + parser = argparse.ArgumentParser(description="Собственные проверки лабораторной 4") + parser.add_argument("--base-url", default=os.environ.get("BASE_URL", "http://127.0.0.1:8080")) + arguments = parser.parse_args() + os.environ["BASE_URL"] = arguments.base_url + if str(HERE) not in sys.path: + sys.path.insert(0, str(HERE)) + if hasattr(sys.stdout, "reconfigure"): + sys.stdout.reconfigure(line_buffering=True) + print("BASE_URL =", arguments.base_url, flush=True) + suite = unittest.defaultTestLoader.discover( + str(HERE), pattern="test_*.py", top_level_dir=str(HERE) + ) + result = unittest.TextTestRunner(verbosity=2).run(suite) + return 0 if result.wasSuccessful() else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/student-tests/s3_outage_probe.py b/student-tests/s3_outage_probe.py new file mode 100644 index 00000000..f7ddcd7b --- /dev/null +++ b/student-tests/s3_outage_probe.py @@ -0,0 +1,114 @@ +#!/usr/bin/env python3 +"""Проверка отказа S3: readiness, upload и восстановление после возврата MinIO. + +Скрипт намеренно управляет Docker-сервисом minio (лабораторный стенд), поэтому +запускается только оператором. Он не печатает токены; в evidence попадают +только статусы, тайминги и коды ошибок. +""" +from __future__ import annotations + +import argparse +import json +import os +import subprocess +import time +import urllib.error +import urllib.request +from datetime import datetime, timezone +from pathlib import Path +from urllib.parse import quote + +ROOT = Path(__file__).resolve().parents[1] +import sys + +sys.path.insert(0, str(ROOT / "tests")) +from client import Client, Failure # noqa: E402 + +PNG = (ROOT / "tests" / "fixtures" / "sample.png").read_bytes() + + +def docker(*args: str) -> None: + subprocess.run(["docker", *args], check=True, capture_output=True, text=True) + + +def raw(method: str, url: str, token: str | None = None, body: bytes | None = None, content_type: str | None = None) -> dict: + headers = {"Accept": "application/json"} + if token: + headers["Authorization"] = "Bearer " + token + if content_type: + headers["Content-Type"] = content_type + request = urllib.request.Request(url, data=body, headers=headers, method=method) + started = time.monotonic() + try: + with urllib.request.urlopen(request, timeout=10) as response: + payload = response.read() + return {"status": response.status, "seconds": round(time.monotonic() - started, 3), "body": payload[:500].decode("utf-8", "replace")} + except urllib.error.HTTPError as exc: + payload = exc.read() + return { + "status": exc.code, + "seconds": round(time.monotonic() - started, 3), + "body": payload[:500].decode("utf-8", "replace"), + "x_request_id": exc.headers.get("X-Request-Id"), + } + except (urllib.error.URLError, OSError) as exc: + return {"status": None, "seconds": round(time.monotonic() - started, 3), "error": type(exc).__name__} + + +def main() -> int: + parser = argparse.ArgumentParser(description="Отказ MinIO и восстановление") + parser.add_argument("--base-url", default=os.environ.get("BASE_URL", "http://127.0.0.1:8080")) + parser.add_argument("--stack", default=os.environ.get("STACK_NAME", "lab4")) + parser.add_argument("--output", default="evidence/s3-outage.json") + args = parser.parse_args() + + api = Client(args.base_url, None, timeout=10) + alice, bob, _eve, chat = api.bootstrap() + healthy = api.attachment(alice, chat)[0] + before = api.call("GET", "/api/v1/attachments/" + healthy["id"] + "/content", actor=bob)["bytes"] + report: dict = { + "measured_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"), + "stack": args.stack, + "before": {"ready": True, "download_matches": before == PNG}, + } + try: + docker("service", "scale", args.stack + "_minio=0") + report["scale_down_seconds"] = 0 + time.sleep(3) + report["during"] = { + "ready": raw("GET", args.base_url + "/health/ready"), + "upload": raw( + "POST", + args.base_url + "/api/v1/chats/%s/attachments?filename=outage.png" % chat["id"], + token=alice["token"], + body=PNG, + content_type="image/png", + ), + "trend_download": raw("GET", args.base_url + "/api/v1/attachments/" + healthy["id"] + "/content", token=bob["token"]), + } + finally: + docker("service", "scale", args.stack + "_minio=1") + deadline = time.monotonic() + 120 + recovered = False + while time.monotonic() < deadline: + try: + api.call("GET", "/health/ready", schema="Health") + recovered = True + break + except Failure: + time.sleep(1) + report["after"] = {"ready": recovered} + if recovered: + new = api.attachment(alice, chat)[0] + downloaded = api.call("GET", "/api/v1/attachments/" + new["id"] + "/content", actor=bob)["bytes"] + report["after"]["new_upload_ready"] = new["status"] + report["after"]["download_matches"] = downloaded == PNG + output = Path(args.output) + output.parent.mkdir(parents=True, exist_ok=True) + output.write_text(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8") + print(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True)) + return 0 if recovered and report["after"].get("download_matches") else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/student-tests/test_lab3.py b/student-tests/test_lab3.py new file mode 100644 index 00000000..4519bb70 --- /dev/null +++ b/student-tests/test_lab3.py @@ -0,0 +1,108 @@ +"""Собственные проверки лабораторной 3: реплики, LB и общая идемпотентность.""" +from __future__ import annotations + +import threading +import unittest +from concurrent.futures import ThreadPoolExecutor +from uuid import uuid4 + +import harness +from client import Client + + +class Lab3Tests(unittest.TestCase): + @classmethod + def setUpClass(cls) -> None: + harness.wait_ready() + cls.api = harness.client() + cls.alice, cls.bob, cls.eve, cls.chat = cls.api.bootstrap() + + def test_01_at_least_two_instances_and_stable_header(self) -> None: + """LB действительно распределяет один и тот же токен между разными процессами.""" + observed = harness.instance_ids(self.api, self.alice, 40) + self.assertGreaterEqual(len(observed), 2, "less than two X-Instance-Id values through LB") + for _ in range(10): + me = self.api.call("GET", "/api/v1/users/me", actor=self.alice, schema="User")["json"] + self.assertEqual(me["id"], self.alice["id"]) + + def test_02_concurrent_same_key_through_lb_creates_one_message(self) -> None: + """Один ключ + одно тело одновременно через разные реплики = одно сообщение.""" + key = uuid4().hex + text = "concurrent-idempotency-" + uuid4().hex + workers = 24 + barrier = threading.Barrier(workers) + + def worker(_: int) -> dict: + local = harness.client(10) + barrier.wait() + return local.message(self.alice, self.chat, text, key=key) + + with ThreadPoolExecutor(max_workers=workers) as pool: + responses = list(pool.map(worker, range(workers))) + + bodies = [response["json"] for response in responses] + instances = {response["headers"]["X-Instance-Id"] for response in responses} + self.assertGreaterEqual(len(instances), 2, "concurrent requests did not reach both replicas") + self.assertEqual(bodies, [bodies[0]] * workers, "replay returned a different Message") + messages = [m for m in harness.history(self.api, self.bob, self.chat["id"]) if m["text"] == text] + self.assertEqual(len(messages), 1, "idempotency key created %d messages" % len(messages)) + self.assertEqual(messages[0], bodies[0]) + + def test_03_same_key_other_body_conflicts(self) -> None: + key = uuid4().hex + first = self.api.message(self.alice, self.chat, "first-" + uuid4().hex, key=key)["json"] + replay = self.api.message(self.alice, self.chat, first["text"], key=key)["json"] + self.assertEqual(replay, first) + self.api.call( + "POST", + "/api/v1/chats/" + self.chat["id"] + "/messages", + 409, + actor=self.alice, + body={"text": "different body"}, + headers={"Idempotency-Key": key}, + ) + + def test_04_key_scope_user_and_chat(self) -> None: + key = uuid4().hex + text_alice = "scope-a-" + uuid4().hex + text_bob = "scope-b-" + uuid4().hex + alice_message = self.api.message(self.alice, self.chat, text_alice, key=key)["json"] + bob_message = self.api.message(self.bob, self.chat, text_bob, key=key)["json"] + self.assertNotEqual(alice_message["id"], bob_message["id"]) + other_chat = self.api.call( + "POST", + "/api/v1/chats", + 201, + actor=self.alice, + body={"title": "Другой чат", "member_ids": [self.alice["id"]]}, + schema="Chat", + )["json"] + other = self.api.message(self.alice, other_chat, text_alice, key=key)["json"] + self.assertNotEqual(other["id"], alice_message["id"]) + + def test_05_key_validation(self) -> None: + path = "/api/v1/chats/" + self.chat["id"] + "/messages" + for bad in ("", "has space", "bad/slash", "x" * 129): + self.api.call( + "POST", + path, + 400, + actor=self.alice, + body={"text": "bad-key"}, + headers={"Idempotency-Key": bad}, + ) + self.api.call("POST", path, 400, actor=self.alice, body={"text": "no key"}) + for good in ("a", "z" * 128): + self.api.message(self.alice, self.chat, "boundary-" + uuid4().hex, key=good) + + def test_06_uncertain_retry_is_safe(self) -> None: + """Повтор с тем же ключом после потери ответа не создаёт второй объект.""" + key = uuid4().hex + text = "retry-after-conflict-" + uuid4().hex + first = self.api.message(self.alice, self.chat, text, key=key)["json"] + again = self.api.message(self.alice, self.chat, text, key=key)["json"] + self.assertEqual(first, again) + + +if __name__ == "__main__": + unittest.main(verbosity=2) \ No newline at end of file diff --git a/student-tests/test_lab4.py b/student-tests/test_lab4.py new file mode 100644 index 00000000..8a8dfcdd --- /dev/null +++ b/student-tests/test_lab4.py @@ -0,0 +1,163 @@ +"""Собственные проверки лабораторной 4: вложения, лимиты и отказы. + +Проверки идут через публичный контракт и LB, не подменяют приложение и не +управляют Docker. Инфраструктурные сценарии (S3 outage, reconciler, память) +лежат в отдельных скриптах и evidence. +""" +from __future__ import annotations + +import hashlib +import struct +import unittest +import uuid +import zlib +from pathlib import Path +from urllib.parse import quote + +import harness +from client import Client + +ROOT = Path(__file__).resolve().parents[1] +PNG = (ROOT / "tests" / "fixtures" / "sample.png").read_bytes() +JPEG = (Path(__file__).resolve().parent / "fixtures" / "sample.jpg").read_bytes() +MAX_BYTES = 10_485_760 + + +def upload(api: Client, actor: dict, chat: dict, content: bytes, *, filename: str = "photo.png", content_type: str = "image/png", expected: int = 201): + path = "/api/v1/chats/%s/attachments?filename=%s" % (chat["id"], quote(filename, safe="")) + return api.call( + "POST", + path, + expected, + actor=actor, + raw=content, + headers={"Content-Type": content_type}, + schema="Attachment" if expected == 201 else None, + ) + + +def png_with_dimensions(width: int, height: int) -> bytes: + """Меняет IHDR у реального PNG и пересчитывает CRC: файл остаётся PNG.""" + data = bytearray(PNG) + struct.pack_into(">I", data, 16, width) + struct.pack_into(">I", data, 20, height) + struct.pack_into(">I", data, 29, zlib.crc32(bytes(data[12:29])) & 0xFFFFFFFF) + return bytes(data) + + +class Lab4AttachmentTests(unittest.TestCase): + @classmethod + def setUpClass(cls) -> None: + harness.wait_ready() + cls.api = harness.client() + cls.alice, cls.bob, cls.eve, cls.chat = cls.api.bootstrap() + cls.other_chat = cls.api.call( + "POST", + "/api/v1/chats", + 201, + actor=cls.alice, + body={"title": "Другой чат lab4", "member_ids": [cls.alice["id"], cls.bob["id"]]}, + schema="Chat", + )["json"] + + def test_01_png_jpeg_and_metadata(self) -> None: + for content, content_type, filename in ((PNG, "image/png", "sample.png"), (JPEG, "image/jpeg", "sample.jpg")): + attachment = upload(self.api, self.alice, self.chat, content, filename=filename, content_type=content_type)["json"] + self.assertEqual(attachment["status"], "ready") + self.assertEqual(attachment["variants"], []) + self.assertIsNone(attachment["error_code"]) + self.assertEqual(attachment["chat_id"], self.chat["id"]) + self.assertEqual(attachment["owner_id"], self.alice["id"]) + self.assertEqual(attachment["content_type"], content_type) + self.assertEqual(attachment["size_bytes"], len(content)) + self.assertEqual(attachment["sha256"], hashlib.sha256(content).hexdigest()) + metadata = self.api.call("GET", "/api/v1/attachments/" + attachment["id"], actor=self.bob, schema="Attachment")["json"] + self.assertEqual(metadata, attachment) + downloaded = self.api.call("GET", "/api/v1/attachments/" + attachment["id"] + "/content", actor=self.bob) + self.assertEqual(downloaded["bytes"], content) + self.assertEqual(downloaded["headers"].get_content_type(), content_type) + self.assertEqual(downloaded["headers"].get("Content-Length"), str(len(content))) + + def test_02_stranger_and_nonmember(self) -> None: + attachment = upload(self.api, self.alice, self.chat, PNG)["json"] + for suffix in ("", "/content"): + self.api.call("GET", "/api/v1/attachments/" + attachment["id"] + suffix, 404, actor=self.eve) + # Посторонний не может загрузить файл в чужой чат. + upload(self.api, self.eve, self.chat, PNG, expected=404) + + def test_03_attachment_from_another_chat_is_404(self) -> None: + foreign = upload(self.api, self.alice, self.other_chat, PNG)["json"] + self.api.call( + "POST", + "/api/v1/chats/" + self.chat["id"] + "/messages", + 404, + actor=self.alice, + body={"text": "", "attachment_ids": [foreign["id"]]}, + headers={"Idempotency-Key": uuid.uuid4().hex}, + ) + # В своём чате это же вложение допустимо. + own = self.api.message(self.alice, self.other_chat, "", attachments=[foreign["id"]])["json"] + self.assertEqual(own["attachment_ids"], [foreign["id"]]) + + def test_04_message_attachment_validation_and_idempotency(self) -> None: + attachment = upload(self.api, self.alice, self.chat, PNG)["json"] + path = "/api/v1/chats/" + self.chat["id"] + "/messages" + self.api.call("POST", path, 400, actor=self.alice, body={"text": ""}, headers={"Idempotency-Key": uuid.uuid4().hex}) + self.api.call( + "POST", + path, + 400, + actor=self.alice, + body={"text": "too many", "attachment_ids": [str(uuid.uuid4()) for _ in range(11)]}, + headers={"Idempotency-Key": uuid.uuid4().hex}, + ) + self.api.call( + "POST", + path, + 400, + actor=self.alice, + body={"text": "duplicate", "attachment_ids": [attachment["id"], attachment["id"]]}, + headers={"Idempotency-Key": uuid.uuid4().hex}, + ) + self.api.call( + "POST", + path, + 404, + actor=self.alice, + body={"text": "unknown", "attachment_ids": [str(uuid.uuid4())]}, + headers={"Idempotency-Key": uuid.uuid4().hex}, + ) + key = uuid.uuid4().hex + first = self.api.message(self.alice, self.chat, "", key=key, attachments=[attachment["id"]])["json"] + self.assertEqual(first["text"], "") + self.assertEqual(first["attachment_ids"], [attachment["id"]]) + replay = self.api.message(self.alice, self.chat, "", key=key, attachments=[attachment["id"]])["json"] + self.assertEqual(replay, first) + self.api.call( + "POST", + path, + 409, + actor=self.alice, + body={"text": "different", "attachment_ids": []}, + headers={"Idempotency-Key": key}, + ) + + def test_05_rejects_bad_images_and_filenames(self) -> None: + # Слишком большое тело отсекается по Content-Length до чтения. + upload(self.api, self.alice, self.chat, b"\x00" * (MAX_BYTES + 1), expected=413) + # Повреждённый PNG, подмена MIME содержимым и не-изображение. + upload(self.api, self.alice, self.chat, PNG[:100], expected=415) + upload(self.api, self.alice, self.chat, PNG, content_type="image/jpeg", expected=415) + upload(self.api, self.alice, self.chat, b"not an image", expected=415) + upload(self.api, self.alice, self.chat, b"", expected=415) + # Размеры читаются из заголовка и проверяются до распаковки. + upload(self.api, self.alice, self.chat, png_with_dimensions(8000, 6000), expected=413) + # 100 Мп выше порога Pillow DecompressionBombWarning; это всё ещё 413, не 500. + upload(self.api, self.alice, self.chat, png_with_dimensions(10000, 10000), expected=413) + for bad in ("../secret.png", "a/b.png", "a\\b.png", "a\x00b.png", "a\nb.png", "x" * 256): + upload(self.api, self.alice, self.chat, PNG, filename=bad, expected=400) + + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/student-tests/upload_experiment.py b/student-tests/upload_experiment.py new file mode 100644 index 00000000..31f75cf9 --- /dev/null +++ b/student-tests/upload_experiment.py @@ -0,0 +1,204 @@ +#!/usr/bin/env python3 +"""Эксперимент с памятью: >=10 одновременных загрузок настоящих PNG. + +Гипотеза: API не буферизует тело целиком в RAM, поэтому пик RSS не растёт +пропорционально сумме размеров всех одновременных файлов. Скрипт измеряет +память контейнеров API через `docker stats`, а не память клиента. + +Требуется Pillow для генерации большого валидного PNG (это инструмент +эксперимента, а не рантайм API). Запуск: + python3 student-tests/upload_experiment.py --concurrency 12 +Docker CLI должен видеть тот же стенд (DOCKER_HOST/DOCKER_CONFIG). +""" +from __future__ import annotations + +import argparse +import json +import os +import re +import statistics +import subprocess +import sys +import threading +import time +from concurrent.futures import ThreadPoolExecutor +from datetime import datetime, timezone +from pathlib import Path +from urllib.parse import quote + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "tests")) + +from client import Client, Failure # noqa: E402 + +UNITS = {"B": 1, "KiB": 1024, "MiB": 1024**2, "GiB": 1024**3, "TiB": 1024**4} + + +def parse_bytes(value: str) -> int: + match = re.match(r"\s*([\d.]+)\s*([A-Za-z]+)", value) + if match is None: + raise ValueError("unrecognized memory value: %r" % value) + number, unit = match.group(1), match.group(2) + return int(float(number) * UNITS[unit]) + + +def api_containers() -> list[str]: + result = subprocess.run( + ["docker", "ps", "--no-trunc", "--format", "{{.ID}} {{.Names}}"], + check=True, + capture_output=True, + text=True, + ) + containers = [] + for line in result.stdout.splitlines(): + parts = line.split(maxsplit=1) + if len(parts) == 2 and "lab4_api." in parts[1]: + containers.append(parts[0]) + return containers + + +def api_memory(containers: list[str]) -> dict[str, int]: + if not containers: + return {} + result = subprocess.run( + ["docker", "stats", "--no-stream", "--no-trunc", "--format", "{{.ID}}\t{{.MemUsage}}"] + + containers, + check=True, + capture_output=True, + text=True, + ) + memory: dict[str, int] = {} + for line in result.stdout.splitlines(): + identifier, usage = line.split("\t", 1) + memory[identifier] = parse_bytes(usage.split("/")[0]) + return memory + + +def make_png(path: Path, width: int = 1800, height: int = 1350) -> int: + if path.exists() and path.stat().st_size <= 10_485_760: + return path.stat().st_size + from PIL import Image + + raw = os.urandom(width * height * 3) + image = Image.frombytes("RGB", (width, height), raw) + image.save(path, "PNG") + size = path.stat().st_size + if size > 10_485_760: + raise SystemExit("generated PNG exceeds the contract limit: %d" % size) + return size + + +def percentile(values: list[float], fraction: float) -> float: + if not values: + return 0.0 + ordered = sorted(values) + index = min(len(ordered) - 1, max(0, int(round((len(ordered) - 1) * fraction)))) + return ordered[index] + + +def main() -> int: + parser = argparse.ArgumentParser(description="Пик RAM API при одновременных загрузках") + parser.add_argument("--base-url", default=os.environ.get("BASE_URL", "http://127.0.0.1:8080")) + parser.add_argument("--concurrency", type=int, default=12) + parser.add_argument("--output", default="evidence/upload-memory.json") + args = parser.parse_args() + + fixture = ROOT / "student-tests" / "fixtures" / "large.png" + image = make_png(fixture) + api = Client(args.base_url, None, timeout=30) + alice, _bob, _eve, chat = api.bootstrap() + containers = api_containers() + if len(containers) < 2: + raise SystemExit("expected >=2 lab4_api containers, saw %d" % len(containers)) + + stop = threading.Event() + samples: list[dict] = [] + + def sampler() -> None: + while not stop.is_set(): + try: + samples.append({"t": round(time.monotonic(), 3), "memory": api_memory(containers)}) + except Exception as exc: # pragma: no cover - diagnostics only + samples.append({"t": round(time.monotonic(), 3), "error": type(exc).__name__}) + stop.wait(0.2) + + baseline = api_memory(containers) + thread = threading.Thread(target=sampler, daemon=True) + thread.start() + started = time.monotonic() + barrier = threading.Barrier(args.concurrency) + results: list[dict] = [] + + def worker(_: int) -> None: + local = Client(args.base_url, None, timeout=120) + barrier.wait() + began = time.monotonic() + try: + response = local.call( + "POST", + "/api/v1/chats/%s/attachments?filename=large.png" % chat["id"], + 201, + actor=alice, + raw=fixture.read_bytes(), + headers={"Content-Type": "image/png"}, + schema="Attachment", + ) + results.append( + { + "status": response["status"], + "seconds": round(time.monotonic() - began, 3), + "instance": response["headers"].get("X-Instance-Id"), + } + ) + except (Failure, OSError) as exc: + results.append({"status": None, "seconds": round(time.monotonic() - began, 3), "error": str(exc)[:200]}) + + with ThreadPoolExecutor(max_workers=args.concurrency) as pool: + list(pool.map(worker, range(args.concurrency))) + elapsed = time.monotonic() - started + time.sleep(0.5) + stop.set() + thread.join(timeout=5) + time.sleep(0.5) + after = api_memory(containers) + + peaks = {identifier: 0 for identifier in containers} + for sample in samples: + for identifier, value in (sample.get("memory") or {}).items(): + peaks[identifier] = max(peaks.get(identifier, 0), value) + successful = [item for item in results if item["status"] == 201] + durations = [item["seconds"] for item in successful] + report = { + "measured_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"), + "base_url": args.base_url, + "concurrency": args.concurrency, + "image_bytes": image, + "image_dimensions": [1800, 1350], + "containers": containers, + "baseline_rss_bytes": baseline, + "peak_rss_bytes": peaks, + "after_rss_bytes": after, + "sum_peak_rss_bytes": sum(peaks.values()), + "sum_baseline_rss_bytes": sum(baseline.values()), + "peak_delta_bytes": sum(peaks.values()) - sum(baseline.values()), + "successful": len(successful), + "failed": len(results) - len(successful), + "elapsed_seconds": round(elapsed, 3), + "p50_seconds": round(statistics.median(durations), 3) if durations else None, + "p95_seconds": round(percentile(durations, 0.95), 3) if durations else None, + "instances": sorted({item.get("instance") for item in successful if item.get("instance")}), + "samples": samples, + "results": results, + } + output = Path(args.output) + output.parent.mkdir(parents=True, exist_ok=True) + output.write_text(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8") + print(json.dumps({key: value for key, value in report.items() if key not in ("samples", "results", "baseline_rss_bytes", "peak_rss_bytes", "after_rss_bytes")}, ensure_ascii=False, indent=2)) + print("baseline_rss_bytes:", baseline) + print("peak_rss_bytes:", peaks) + print("evidence:", output) + return 0 if len(successful) == args.concurrency else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) -- 2.54.0