ЛР 4 - БВТ2301 - Кокорин - на 4 #81

Closed
kokorindenis wants to merge 1 commits from kokorindenis/mtusi2026lab4:solution/bvt2301-kokorin into main
97 changed files with 7579 additions and 23 deletions
+5
View File
@@ -1,5 +1,10 @@
.git
.github
.dockercli
.dsh-tools
.tmp
.venv
.venv-libs
.env
.env.*
!.env.example
+9 -3
View File
@@ -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
+7
View File
@@ -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__/
+55
View File
@@ -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"]
+18 -1
View File
@@ -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
+362 -16
View File
@@ -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 <URL fork> && 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/<uuid>`. `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 <api> 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
```
+38
View File
@@ -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
+11
View File
@@ -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>:/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
+2
View File
@@ -0,0 +1,2 @@
PASS: lab4 public API scenario; infrastructure and grading evidence remain separate.
SMOKE_EXIT=0
+21
View File
@@ -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
+116
View File
@@ -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
}
+28
View File
@@ -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`.
+61
View File
@@ -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
+26
View File
@@ -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
+13
View File
@@ -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"
}
+34
View File
@@ -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"
}
+23
View File
@@ -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
}
+8
View File
@@ -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
+102
View File
@@ -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.
+23
View File
@@ -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.
+17
View File
@@ -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
}
+6
View File
@@ -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
+26 -3
View File
@@ -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` — исходные файлы, из которых
сделаны нумерованные копии.
+13
View File
@@ -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"
}
+17
View File
@@ -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
}
+17
View File
@@ -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."
}
+23
View File
@@ -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
}
+34
View File
@@ -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"
}
+116
View File
@@ -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
}
+58
View File
@@ -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())
+24
View File
@@ -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"}
+103
View File
@@ -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")
@@ -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")
+128
View File
@@ -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")
+37
View File
@@ -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
+49
View File
@@ -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 <name> <value>: 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'
+48
View File
@@ -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'
+117
View File
@@ -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())
+4
View File
@@ -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%
+52
View File
@@ -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
+165
View File
@@ -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
}
}
+86
View File
@@ -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 <<EOF
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
"Resource": ["arn:aws:s3:::$bucket/attachments/*"]
},
{
"Effect": "Allow",
"Action": ["s3:ListBucket"],
"Resource": ["arn:aws:s3:::$bucket"],
"Condition": {"StringLike": {"s3:prefix": ["attachments/*"]}}
},
{
"Effect": "Allow",
"Action": ["s3:GetBucketLocation"],
"Resource": ["arn:aws:s3:::$bucket"]
}
]
}
EOF
mc admin policy detach local "$policy_name" --user "$access_key" >/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"
+14
View File
@@ -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 "$@"
+4
View File
@@ -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%
+23
View File
@@ -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
+4
View File
@@ -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%
+27
View File
@@ -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
+4
View File
@@ -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%
+20
View File
@@ -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
+4
View File
@@ -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%
+50
View File
@@ -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"
+5
View File
@@ -0,0 +1,5 @@
"""Мессенджер на PostgreSQL, Valkey и S3: лабораторная 4 курса HighLoad (MTUSI)."""
__all__ = ["__version__"]
__version__ = "4.0.0"
+38
View File
@@ -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())
+16
View File
@@ -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
+142
View File
@@ -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)
+283
View File
@@ -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,
)
+23
View File
@@ -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)
+119
View File
@@ -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
+74
View File
@@ -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()
+133
View File
@@ -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)]
+109
View File
@@ -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
+184
View File
@@ -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, "Внутренняя ошибка сервера")
+88
View File
@@ -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)
+26
View File
@@ -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())
+42
View File
@@ -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()
+88
View File
@@ -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)
+76
View File
@@ -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,
)
+99
View File
@@ -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,
)
+273
View File
@@ -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),
)
+38
View File
@@ -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))
+190
View File
@@ -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())
+554
View File
@@ -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
+1
View File
@@ -0,0 +1 @@
"""Маршруты HTTP API: только разбор запроса, вызов зависимостей и сборка ответа."""
+196
View File
@@ -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)},
)
+51
View File
@@ -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)
+55
View File
@@ -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))
+46
View File
@@ -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()
+74
View File
@@ -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)
)
+34
View File
@@ -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)
+192
View File
@@ -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"),
)
+119
View File
@@ -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)
+122
View File
@@ -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()
+195
View File
@@ -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)
+100
View File
@@ -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
+325
View File
@@ -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
+27
View File
@@ -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 реплики.
+96
View File
@@ -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())
Binary file not shown.

After

Width:  |  Height:  |  Size: 7.7 KiB

+74
View File
@@ -0,0 +1,74 @@
"""Общая обвязка собственных проверок лабораторной 4.
Публичный клиент из tests/ переиспользуется, а не копируется: он уже проверяет
схему ответа, X-Request-Id, X-Instance-Id, конверт ошибки и challenge. Здесь
живут только помощники, специфичные для балансировки и идемпотентности.
"""
from __future__ import annotations
import os
import sys
import time
import uuid
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
TESTS = ROOT / "tests"
HERE = Path(__file__).resolve().parent
for candidate in (str(TESTS), str(HERE)):
if candidate not in sys.path:
sys.path.insert(0, candidate)
from client import Client, Failure # noqa: E402
DEFAULT_BASE_URL = "http://127.0.0.1:8080"
DEFAULT_TIMEOUT = 10.0
def client(timeout: float = DEFAULT_TIMEOUT) -> 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
+53
View File
@@ -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())
+128
View File
@@ -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())
+157
View File
@@ -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())
+32
View File
@@ -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())
+114
View File
@@ -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())
+108
View File
@@ -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)
+163
View File
@@ -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)
+204
View File
@@ -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())