ЛР 4 - БВТ2304 - Травкин - на 5 #22

Closed
casablancawastaken wants to merge 5 commits from casablancawastaken/mtusi2026lab4:solution/bvt2304-travkin into main
33 changed files with 4122 additions and 15 deletions
+27
View File
@@ -0,0 +1,27 @@
FROM python:3.13.15-slim
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY alembic.ini .
COPY migrations ./migrations
COPY src ./src
COPY scripts ./scripts
COPY tests ./tests
RUN useradd --create-home --uid 10001 appuser
USER appuser
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)" || exit 1
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8080"]
+13 -1
View File
@@ -4,7 +4,7 @@ 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 test-reconcile test-compensation reconcile reconcile-repair
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@@ -28,3 +28,15 @@ 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)
test-reconcile:
docker compose exec -T api-1 python -m unittest discover -s tests -p 'test_reconcile.py' -v
test-compensation:
docker compose exec -T api-1 python -m unittest discover -s tests -p 'test_upload_compensation.py' -v
reconcile:
docker compose exec -T api-1 python -m scripts.reconcile
reconcile-repair:
docker compose exec -T api-1 python -m scripts.reconcile --repair
+515 -14
View File
@@ -1,37 +1,538 @@
# Отчёт — лабораторная 4
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- **Автор, группа:** Станислав Травкин, группа: БВТ2304.
- **Целевая оценка:** 5.
- **Выбранный трек оценки 5:** трек 2 — Согласованность двух хранилищ.
- **Git:** ветка `solution/bvt2304-travkin`; опубликованный коммит реализации `0ef8d739d7c843ac82f3843f11321d8732580a07`. Финальный коммит с отчётом будет опубликован в той же ветке. **PR:** создаётся после публикации финальных изменений.
- **Использованные источники, библиотеки и помощь ИИ:** README и методические требования лабораторной работы; Python 3.13, FastAPI, SQLAlchemy, Alembic, PostgreSQL, Redis, boto3, Pillow, MinIO, Nginx, Docker Compose. ChatGPT использовался для обсуждения архитектуры, реализации, диагностики ошибок, подготовки тестовых сценариев и отчёта. Реализация проверялась запуском тестов и экспериментами в локальном окружении.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
### Окружение
Разработка и испытания проводились в Ubuntu 22.04 под WSL2, с использованием Docker Engine, Docker Compose, Python 3.13 и виртуального окружения `.venv`.
Используемые контейнерные образы:
| Компонент | Образ |
| --- | --- |
| PostgreSQL | `postgres:17.6` |
| Redis | `redis:8.2.2` |
| MinIO | `dappros/minio:RELEASE.2025-09-07T16-13-09Z` |
| Nginx | `nginx:1.29-alpine` |
| API и миграции | Локальная сборка из `Dockerfile` |
Для запуска необходимы Docker Engine, Docker Compose, Python 3.13, Bash и свободные локальные порты 8080 и 9001. Порт 9001 публикуется только на `127.0.0.1`; API MinIO доступен внутри сети Compose.
### Подготовка
После клонирования репозитория необходимо перейти в каталог проекта, создать локальное виртуальное окружение и установить зависимости проекта.
```bash
python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
```
Подготовить локальные секреты и конфигурацию командой:
```bash
./scripts/bootstrap.sh
```
Скрипт создаёт каталог `secrets/` и семь файлов: `postgres_password`, `database_url`, `cache_url`, `minio_root_user`, `minio_root_password`, `s3_access_key_id`, `s3_secret_access_key`. Для отсутствующих секретов генерируются значения, а уже существующие непустые файлы сохраняются. `database_url` создаётся со значением для пользователя PostgreSQL `lab2` и паролем из `postgres_password`; `cache_url` указывает на Redis. Учётные данные S3-приложения отличаются от административных данных MinIO.
Скрипт также копирует `.env.example` в `.env`, если локального `.env` ещё нет, и выполняет `docker compose config --quiet`. Параметры реального стенда задаются главным образом через `environment` в `compose.yaml`, а секреты подключаются как файлы `/run/secrets`. Вручную заполнять `.env` для текущего Compose не требуется.
**Важно:** текущий bootstrap устанавливает для файлов `secrets/*` режим `644`, то есть локальные пользователи хоста могут получить право чтения. Это учебное ограничение: каталог имеет режим `700`, но права файлов следует ужесточить для многопользовательского хоста, предварительно обеспечив доступ непривилегированным контейнерам. Не публиковать содержимое `secrets/`, `.env`, пароли и токены. При повторном запуске на уже заполненных томах PostgreSQL/MinIO нельзя бездумно менять согласованные учётные данные.
### Сборка и запуск
```bash
docker compose config --quiet
docker compose build
docker compose up -d
docker compose ps -a
```
При первом запуске PostgreSQL создаёт базу данных, контейнер `migrate` применяет миграции Alembic, а `s3-init` создаёт приватный бакет и пользователя приложения с ограниченными правами.
Оператор должен дождаться состояния `healthy` для PostgreSQL, Redis, MinIO и обеих API-реплик, а также успешного завершения `migrate` и `s3-init`.
Проверка версии схемы:
```bash
docker compose run --rm migrate alembic current
```
В испытаниях наблюдалась версия `d9e53b20f7c1 (head)`.
### Проверка
После запуска дождаться готовности API:
```bash
curl --fail http://localhost:8080/health/ready
```
Затем выполнить:
```bash
make check
make validate
make test
make test-reconcile
make test-compensation
make reconcile
```
Дополнительные испытания:
```bash
make load
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
make test-persistence ACTION_SCRIPT=./scripts/restart.sh
```
Тест отказоустойчивости намеренно останавливает API-реплику; после него её необходимо запустить снова:
```bash
docker compose up -d api-1 api-2
```
Reconciler в обычном режиме ничего не удаляет. Для разрешённой оператором очистки устаревших незарегистрированных объектов предусмотрена команда:
```bash
make reconcile-repair
```
По умолчанию применяется защитный период 24 часа. Перед очисткой рекомендуется выполнить `make reconcile` и изучить список расхождений.
### Остановка
Безопасная остановка без удаления данных:
```bash
docker compose down
```
Намеренное удаление учебных данных, включая постоянные тома PostgreSQL, Redis и MinIO:
```bash
docker compose down -v
```
Последняя команда необратимо удаляет данные в томах данного Compose-проекта и не должна использоваться при обычном перезапуске.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
### Оценка 3 — базовая функциональность
#### Схема компонентов
```text
Клиент
|
v
Nginx :8080
|
+------ API-1 :8080
|
+------ API-2 :8080
|
+------ PostgreSQL
| пользователи, чаты,
| сообщения, вложения
|
+------ Redis
| сессии
|
+------ MinIO (S3)
бинарные данные вложений
```
Nginx распределяет запросы между двумя экземплярами FastAPI. API-реплики не используют локальное состояние для хранения пользовательских данных. Метаданные сохраняются в PostgreSQL, сессии — в Redis, содержимое вложений — в приватном бакете MinIO.
PostgreSQL является источником истины для регистрации вложений и их принадлежности чатам. S3 хранит бинарные данные, адресуемые через `s3_key`.
**Что мы сделали и зачем.** Сохранили две одинаковые реплики FastAPI за Nginx: запрос пользователя может попасть на любую из них, потому что данные не привязаны к памяти конкретного процесса. PostgreSQL хранит структурированную информацию, Redis — сессии авторизации, а MinIO — сами файлы изображений. Такое разделение позволяет не записывать большие бинарные файлы в таблицы сообщений и использовать единое хранилище вложений для обеих реплик.
**Как проходит запрос с вложением.** Пользователь обращается к Nginx, тот направляет запрос на одну из API-реплик. API проверяет сессию и участие пользователя в чате, принимает и проверяет изображение, сохраняет его в MinIO и регистрирует метаданные в PostgreSQL. При последующем скачивании API снова проверяет права и получает содержимое из S3 по сохранённому ключу. Клиенту не выдаётся публичный адрес объекта в бакете.
#### Что перенесено из лабораторной 3
Сохранены пользовательские операции, авторизация через сессии, чаты, сообщения, идемпотентность создания сообщений, две API-реплики, балансировщик Nginx, PostgreSQL и Redis.
**Что это означает на практике.** Мы не создавали отдельное приложение только для изображений: расширили существующий мессенджер. Пользователи по-прежнему создают чаты и сообщения, авторизуются через сессии, а повторная отправка запроса с тем же ключом идемпотентности не должна создавать дублирующие сообщения. Существующие маршруты и публичные проверки предыдущей лабораторной сохранены. Это проверяется в том числе командой `make test`.
#### Что добавлено в лабораторной 4
- Приватное S3-хранилище MinIO с постоянным томом.
- Идемпотентная инициализация бакета и ограниченной учётной записи приложения.
- Загрузка PNG/JPEG с проверкой MIME-типа, содержимого и имени файла.
- Ограничения: не более 10 МиБ и 40 млн пикселей.
- Метаданные вложений в PostgreSQL и связь вложений с сообщениями.
- Проверка принадлежности вложений чату.
- Компенсация при сбое записи метаданных после успешной загрузки в S3.
- Отдельный reconciler для обнаружения и обработки расхождений между PostgreSQL и MinIO.
- Тесты компенсации, безопасной сверки и исправления расхождений.
**Что относится непосредственно к базовой функциональности оценки 3.** В лабораторной №4 мы добавили возможность загрузить изображение PNG/JPEG размером до 10 МиБ и разрешением до 40 млн пикселей, получить ответ `201 Created`, а затем скачать тот же файл без изменения содержимого. Для контроля целостности сравнивался SHA-256. Запись PostgreSQL содержит метаданные вложения, включая ключ объекта S3; само изображение хранится в MinIO. Вложения можно указать при создании сообщения через `attachment_ids`, но использовать чужое вложение или получить файл из чужого чата нельзя.
**Как мы это проверяли.** Проверяли успешную загрузку, получение метаданных и файла, совпадение SHA-256, привязку к сообщению, отказ в доступе постороннему пользователю (`404`) и отсутствие доступа без сессии (`401`). Проверяли работу двух реплик и сохранение данных после перезапуска контейнеров с постоянными Docker volumes. Результаты перечислены в таблице «Доказательства критериев» ниже.
**Что добавлено сверх базового уровня.** Компенсация, обработка отказов, проверки предельных условий и reconciler тоже перечислены выше как части всей лабораторной, но подробнее относятся к оценкам 4 и 5 и раскрываются в следующих подразделах.
### Оценка 4 — надёжность, безопасность и обработка ошибок
#### Транзакционные границы
PostgreSQL и MinIO не участвуют в общей распределённой транзакции.
При загрузке изображения сначала проверяются права пользователя и содержимое файла, затем объект записывается в S3, после чего создаётся запись PostgreSQL со статусом `ready`.
Ответ `201 Created` возвращается только после успешной записи объекта и завершения транзакции PostgreSQL.
Если запись в БД завершается ошибкой, приложение откатывает транзакцию и проверяет наличие зарегистрированного `s3_key` через отдельную сессию. Удаление объекта допускается только при подтверждённом отсутствии записи. Если состояние PostgreSQL невозможно проверить, объект сохраняется для последующей сверки.
Это уменьшает риск удаления зарегистрированного вложения, но не обеспечивает атомарность двух хранилищ. Оставшиеся после аварий объекты обнаруживаются reconciler.
#### Проверка входных данных и разграничение доступа
**Что сделали.** Для загрузки предусмотрены проверки имени файла, заявленного MIME-типа и фактического содержимого изображения. Приложение принимает PNG/JPEG, отклоняет неподдерживаемые и повреждённые файлы, а также изображения, превышающие ограничения по размеру и числу пикселей. Доступ к вложению определяется членством в чате, а не одним лишь знанием идентификатора вложения.
**Что проверили.** Файл больше 10 МиБ и изображение с более чем 40 млн пикселей приводили к `413`; GIF — к `415`; несовпадение MIME-типа и реального формата, а также повреждённый файл — к `400`. Для чужих вложений и недопустимых `attachment_ids` проверялись отказы, перечисленные в таблице доказательств. Приватность S3 проверялась анонимным запросом к бакету (`403 AccessDenied`).
#### Отказы, компенсация и ограничение ресурсов
**Зачем нужна компенсация.** Между успешной загрузкой объекта в MinIO и сохранением его метаданных в PostgreSQL возможен сбой. Если запись в БД точно отсутствует, приложение может удалить незарегистрированный объект; если подтвердить это нельзя, безопаснее сохранить объект и позднее обнаружить его reconciler. Для этих ситуаций подготовлены модульные тесты: `make test-compensation` — 5 успешных проверок.
**Что ещё проверили.** Повторный запуск инициализации S3 не должен удалять существующие объекты; приложение использует отдельные ограниченные S3-учётные данные, а административная консоль MinIO не публикуется как общедоступный сервис. При остановке MinIO загрузка возвращала `503`, после восстановления — `201`. В испытании с десятью параллельными загрузками примерно по 4,13 МиБ все запросы завершились `201`; пиковое потребление API-реплик составило 154,71 и 138,84 МиБ при лимите 512 МиБ, без OOM. Также проверяли отказ одной API-реплики и сохранность данных после перезапуска. Подробные численные результаты приведены ниже в «Экспериментах и отказах».
### Оценка 5 — трек 2. Согласованность двух хранилищ
#### Reconciliation
Утилита `scripts/reconcile.py` получает список ключей из таблицы `attachments` и перечень объектов S3.
Она вычисляет:
- `orphan_objects` — объекты S3 без соответствующей записи PostgreSQL;
- `missing_objects` — записи PostgreSQL, для которых отсутствует объект S3.
Режим `dry-run` только сообщает о расхождениях.
В режиме `--repair` допускается удаление устаревших незарегистрированных объектов. Для защиты данных используются период ожидания, повторная проверка существования записи PostgreSQL и повторная проверка метаданных объекта S3 непосредственно перед удалением.
Отсутствующие объекты S3 не восстанавливаются автоматически: reconciler сообщает о них, не удаляя метаданные PostgreSQL.
#### Как работает наш reconciler
**Задача.** PostgreSQL и MinIO — независимые хранилища. После частичного сбоя их состояние может разойтись. Мы написали отдельную утилиту `scripts/reconcile.py`, которая сравнивает зарегистрированные ключи вложений с фактически существующими объектами бакета.
**Два типа расхождений.** `orphan` — файл уже есть в S3, но соответствующей записи в PostgreSQL нет; такой объект мог остаться после сбоя сохранения метаданных. `missing` — запись в PostgreSQL существует, но файл в S3 отсутствует; например, он был удалён отдельно. В первом случае возможно безопасное удаление устаревшего незарегистрированного объекта, во втором автоматическое удаление записи БД не выполняется, поскольку это уничтожило бы сведения о проблеме.
**Режимы работы.** `make reconcile` запускает сверку в режиме `dry-run`: выводит JSON с найденными расхождениями, но ничего не меняет. `make reconcile-repair` разрешает исправление устаревших orphan-объектов. По умолчанию действует защитный период 24 часа: свежие объекты не удаляются. Непосредственно перед удалением повторно проверяются наличие записи в PostgreSQL и состояние объекта в S3, в том числе время последнего изменения.
#### Какие ошибки внедряли и что доказали
- Создавали объект S3 без записи PostgreSQL: reconciler находил `orphan`.
- Создавали запись PostgreSQL без файла S3: reconciler находил `missing`, не удаляя запись автоматически.
- Проверяли удаление искусственно состаренного orphan-объекта при разрешённом repair.
- Проверяли, что свежие объекты внутри защитного периода сохраняются.
- Проверяли, что объект, зарегистрированный в БД до удаления, не удаляется.
- Проверяли, что изменившийся объект S3 сохраняется благодаря повторной проверке `LastModified`.
- Повторяли сверку после исправления: новых расхождений не оставалось.
Эти сценарии отражены в `tests/test_reconcile.py` и ручных экспериментах; `make test-reconcile` завершился успешно — 8 тестов.
#### Стоимость обхода и вывод
Мы измерили время полной сверки на двух наборах данных, по 10 запусков на каждый: **28 объектов S3** — медиана **5,161 мс**; **128 объектов S3** — медиана **13,029 мс**. При увеличении числа объектов медианное время выросло примерно в **2,52 раза**. Это показывает увеличение стоимости обхода в измеренном диапазоне, но двух точек недостаточно, чтобы утверждать линейную асимптотику.
**Итог трека 2.** Реализованы обнаружение расхождений двух хранилищ, безопасный режим просмотра, ограниченное автоматическое исправление, защита свежих и зарегистрированных вложений, повторяемость проверки и замеры времени. При этом утилита не восстанавливает потерянные файлы и не гарантирует полную атомарность PostgreSQL и S3 — эти ограничения отдельно указаны ниже.
### Конфигурация
Параметры S3 (`S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`), пути к секретам, `SESSION_TTL_SECONDS`, `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS` передаются через `compose.yaml`.
`INSTANCE_ID` различает реплики `api-1` и `api-2`.
Параметры `APP_HOST`, `APP_PORT`, `SESSION_STORE`, `API_REPLICAS` и `IDEMPOTENCY_TTL_SECONDS` из преподавательского `.env.example` не используются как управляющие настройки в текущем Compose-файле. Число реплик задаётся двумя сервисами, порт — конфигурацией контейнера и Nginx, а сессии фактически хранятся в Redis.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
| Публичный smoke | `make test` | PASS | `tests/smoke.py`, `REPORT.md` |
| Проверка структуры | `make check` | PASS | `scripts/check_contract.py`, `REPORT.md` |
| Проверка OpenAPI | `make validate` | PASS | `scripts/validate_openapi.py`, `REPORT.md` |
| Две API-реплики | `docker compose ps api-1 api-2` | Обе реплики healthy | `compose.yaml`, `REPORT.md` |
| PostgreSQL и Redis | `docker compose ps -a` | Хранилища healthy | `compose.yaml`, `REPORT.md` |
| Приватное S3-хранилище | Анонимный запрос списка объектов бакета | HTTP 403 AccessDenied; прямой анонимный GET оригинала также должен быть запрещён | `infra/minio/attachments-policy.json`, `REPORT.md` |
| Ограниченные права приложения | Запрос политики бакета от имени S3-приложения | HTTP 403 AccessDenied | `infra/minio/attachments-policy.json`, `REPORT.md` |
| Идемпотентный bootstrap | Повторный `docker compose run --rm s3-init` | Успешное выполнение, существующие объекты сохранены | `infra/minio/init.sh`, `REPORT.md` |
| Повторные миграции | `docker compose run --rm migrate` | Успешно; схема на head | `migrations/versions/`, `REPORT.md` |
| Загрузка PNG/JPEG | POST изображения в чат | HTTP 201; объект S3 и запись БД созданы | `src/main.py`, `src/images.py`, `REPORT.md` |
| Ограничение 10 МиБ | POST изображения больше лимита | HTTP 413 | `src/images.py`, `REPORT.md` |
| Ограничение 40 млн пикселей | POST изображения с превышением лимита | HTTP 413 | `src/images.py`, `REPORT.md` |
| Неподдерживаемый формат | POST GIF | HTTP 415 | `src/images.py`, `REPORT.md` |
| Несоответствие MIME содержимому | PNG, заявленный как JPEG | HTTP 400 | `src/images.py`, `REPORT.md` |
| Повреждённое изображение | POST повреждённого файла | HTTP 400 | `src/images.py`, `REPORT.md` |
| Доступ только участникам чата | Запрос вложения посторонним пользователем | HTTP 404 | `src/main.py`, `src/repositories.py`, `REPORT.md` |
| Защита неавторизованного запроса | GET вложения без сессии | HTTP 401 | `src/main.py`, `REPORT.md` |
| Получение метаданных и содержимого | GET вложения участником чата | HTTP 200; SHA-256 содержимого совпал | `src/storage.py`, `REPORT.md` |
| Вложения в сообщениях | Создание сообщения с `attachment_ids` | HTTP 201 | `src/models.py`, `src/repositories.py`, `REPORT.md` |
| Некорректные вложения в сообщении | Передача недопустимых `attachment_ids` | HTTP 400 | `src/repositories.py`, `REPORT.md` |
| Идемпотентность сообщений | Повтор ключа с тем же содержимым / изменение содержимого | Повтор принят; конфликт HTTP 409 | `src/repositories.py`, `REPORT.md` |
| Отказ MinIO | Остановка S3 и попытка загрузки | HTTP 503; после восстановления загрузка HTTP 201 | `src/storage.py`, `REPORT.md` |
| Компенсация при ошибках | `make test-compensation` | 5 тестов, OK | `tests/test_upload_compensation.py`, `REPORT.md` |
| Параллельные загрузки | 10 одновременных загрузок изображений примерно по 4,13 МиБ | 10 ответов HTTP 201; OOM не наблюдался | `REPORT.md` |
| Отказ одной API-реплики | `make test-failover ACTION_SCRIPT=./scripts/stop-one.sh` | PASS; 95 успешных записей, 2 неудачные попытки | `scripts/stop-one.sh`, `REPORT.md` |
| Сохранность при перезапуске | `make test-persistence ACTION_SCRIPT=./scripts/restart.sh` | PASS при повторной проверке; данные и сессия сохранились | `scripts/restart.sh`, `REPORT.md` |
| Тесты reconciler | `make test-reconcile` | 8 тестов, OK | `tests/test_reconcile.py`, `REPORT.md` |
| Поиск orphan-объектов | Добавление объекта S3 без записи БД, запуск dry-run | Объект обнаружен | `scripts/reconcile.py`, `REPORT.md` |
| Поиск missing-объектов | Добавление записи БД без объекта S3 | Отсутствующий объект обнаружен | `scripts/reconcile.py`, `REPORT.md` |
| Безопасный repair | Искусственно состаренный тестовый orphan-объект | Объект удалён, повторная сверка чистая | `scripts/reconcile.py`, `REPORT.md` |
| Защита свежих объектов | Repair при действующем grace period | Свежий объект пропущен | `tests/test_reconcile.py`, `REPORT.md` |
| Защита зарегистрированных объектов | Повторная проверка БД перед удалением | Зарегистрированный объект сохранён | `tests/test_reconcile.py`, `REPORT.md` |
| Защита изменившихся объектов | Повторная проверка `LastModified` | Обновлённый объект сохранён | `tests/test_reconcile.py`, `REPORT.md` |
| Повторяемость reconciliation | Повторный dry-run после очистки тестовых объектов | Нет расхождений | `scripts/reconcile.py`, `REPORT.md` |
| Измерение стоимости сверки | 10 запусков на 28 и 128 объектах S3 | Медиана 5,161 и 13,029 мс соответственно | `REPORT.md` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Результаты ручных сценариев зафиксированы в настоящем отчёте; исходные файлы тестов и конфигурации позволяют воспроизвести соответствующие проверки. Для ручных сценариев, не автоматизированных отдельным скриптом, повторное выполнение требует подготовки тестовых пользователей, чатов и файлов.
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
### Гипотезы
1. Использование двух API-реплик и общих хранилищ позволяет продолжить обслуживание запросов при остановке одной реплики.
2. Ограничение размера загружаемых файлов и ресурсов контейнеров позволяет выполнять параллельные загрузки без превышения лимита памяти.
3. Reconciler обнаруживает расхождения между PostgreSQL и S3, а защитный период и повторные проверки позволяют избежать удаления свежих и зарегистрированных объектов.
4. Увеличение количества объектов S3 повышает время полной сверки.
### Условия испытаний
Среда: WSL2, Ubuntu 22.04, Docker Engine и Docker Compose.
Ресурсы контейнеров:
| Сервис | CPU | RAM |
| --- | --- | --- |
| API-1 | 1 | 512 МиБ |
| API-2 | 1 | 512 МиБ |
| PostgreSQL | 1 | 768 МиБ |
| Redis | 0,5 | 256 МиБ |
| MinIO | 1 | 512 МиБ |
| Nginx | 0,5 | 256 МиБ |
Модель процессора хост-машины, выделенная память WSL2, показатели CPU во время нагрузочного теста и отдельная длительность прогрева не фиксировались. Эксперименты выполнялись в локальном учебном окружении; независимая проверка запуска на другом хосте не проводилась.
### Нагрузочный тест API
Команда:
```bash
make load
```
Сохранённая сводка одного успешного прогона:
```text
duration_seconds: 30
concurrency: 4
successful_requests: 12959
failed_requests: 0
successful_rps: 431.857
p50_ms: 8.592
p95_ms: 11.866
p99_ms: 16.363
```
Тест выполнял синтетические операции записи. Показатель 431,857 RPS характеризует конкретный локальный сценарий, а не гарантированную производительность в производственной среде.
Отдельные значения CPU/RAM для данного прогона не записывались.
### Параллельная загрузка изображений
Выполнены два прогона по 10 одновременных загрузок файлов размером приблизительно 4,13 МиБ.
Все 10 запросов в каждом прогоне завершились HTTP 201.
Наблюдаемая длительность прогонов — приблизительно 1,26 и 0,83 секунды.
Зафиксированные максимальные значения потребления памяти API-контейнеров:
```text
api-1: 154.71 MiB
api-2: 138.84 MiB
limit: 512 MiB per container
oom_kill: 0
```
Значения максимума памяти получены из счётчиков контейнеров и отражают накопленный пик, а не обязательно только интервал данного эксперимента.
### Измерение стоимости reconciliation
Выполнены по 10 последовательных запусков полной сверки для двух размеров S3-хранилища.
**Сценарий A:** 28 записей PostgreSQL и 28 объектов S3.
```text
times_ms:
20.772, 5.299, 5.023, 4.952, 4.469,
5.794, 5.492, 4.698, 4.678, 5.451
min_ms: 4.469
mean_ms: 6.663
median_ms: 5.161
max_ms: 20.772
```
**Сценарий B:** 28 записей PostgreSQL и 128 объектов S3, включая 100 временных объектов.
```text
times_ms:
46.378, 13.201, 13.230, 13.349, 14.940,
12.856, 12.455, 11.603, 12.088, 11.242
min_ms: 11.242
mean_ms: 16.134
median_ms: 13.029
max_ms: 46.378
```
Медианное время выросло приблизительно в 2,52 раза при увеличении числа объектов S3 с 28 до 128.
Результат подтверждает увеличение стоимости полного обхода в исследованном диапазоне. Двух точек недостаточно для доказательства линейной асимптотики. Дополнительные временные объекты после эксперимента удалены.
### Эксперименты с отказами
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Остановка одной API-реплики | Оставшаяся реплика продолжает обслуживать запросы | Failover PASS, 95 успешных записей и 2 неудачные попытки | Первое восстановление успешных запросов через 0,89 с; подтверждённой потери сохранённых данных нет |
| Перезапуск PostgreSQL, Redis и двух API | Данные и сессии сохраняются | Persistence PASS при повторном запуске | Кратковременная недоступность; данные и сессия сохранились |
| Остановка MinIO | Загрузка временно недоступна | HTTP 503, после запуска S3 — HTTP 201 | Восстановление после запуска MinIO; подтверждённой потери ранее сохранённых объектов нет |
| Ошибка вставки или commit в PostgreSQL | Незарегистрированный объект компенсируется | Соответствующие модульные тесты OK | Удаление при подтверждённом отсутствии записи |
| Недоступность PostgreSQL при компенсации | Не удалять объект с неизвестным состоянием регистрации | Модульный тест OK | Объект сохраняется до последующей сверки |
| Добавление orphan-объекта | Reconciler обнаруживает лишний объект | Обнаружен; устаревший тестовый объект удалён при repair | Повторная сверка без расхождений |
| Добавление missing-записи | Reconciler обнаруживает отсутствие бинарных данных | Запись обнаружена; автоматическое удаление БД не выполнялось | Восстановление содержимого не реализовано |
При отдельных запусках теста persistence возникал `TimeoutError` ещё до выполнения сценария перезапуска. В логах Nginx наблюдались ошибки разрешения имён Docker DNS для `api-2`, включая `wrong ident` и `could not be resolved`. Повторные проверки DNS и последующий запуск persistence прошли успешно. Причина нестабильности окончательно не установлена.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
1. **Нет общей транзакции PostgreSQL и S3.** Компенсация и периодическая сверка снижают риск рассогласования, но не заменяют распределённую транзакцию.
2. **Reconciler не восстанавливает отсутствующие бинарные данные.** При наличии метаданных без S3-объекта требуется вмешательство оператора, восстановление из резервной копии или отдельная процедура обработки повреждённого вложения.
3. **Существует окно гонки между проверкой и удалением.** Перед удалением выполняются дополнительные проверки, однако полной атомарности операций между двумя хранилищами нет.
4. **Grace period не гарантирует сохранность всех незарегистрированных объектов.** Он защищает недавно созданные объекты, но старые объекты без метаданных могут быть удалены при repair. Поэтому repair выполняется осознанно оператором.
5. **Наблюдалась нестабильность Docker DNS.** Некоторые запуски persistence завершались ошибкой до воздействия на инфраструктуру. Проблема не была устойчиво воспроизведена и не считается устранённой.
6. **Измерения выполнены локально.** Результаты RPS и задержек зависят от WSL2, ресурсов хоста, профиля нагрузки и размеров данных. Измерения не являются производственным бенчмарком.
7. **Профиль reconciliation ограничен двумя размерами набора.** Для оценки масштабируемости нужны дополнительные точки, большие объёмы данных и повторения на разных состояниях хранилища.
8. **Локальные секреты создаются с правами `644`.** Каталог `secrets/` ограничен режимом `700`, однако для многопользовательского хоста требуются более строгие права файлов и согласованная схема доступа контейнеров.
9. **Не реализованы распределённые блокировки и фоновое расписание reconciliation.** Утилита запускается оператором. Для производственного применения целесообразны планировщик, аудит удалений, метрики, оповещения и резервное копирование.
## Демонстрация
Все команды выполняются из корня репозитория. Перед демонстрацией должны быть подготовлены локальные секреты и запущены контейнеры.
### 1. Запуск и проверка инфраструктуры
```bash
docker compose up -d
docker compose ps -a
docker compose run --rm migrate alembic current
```
Показать две работающие API-реплики, PostgreSQL, Redis, MinIO, Nginx и применённые миграции.
### 2. Проверка API
```bash
make check
make validate
make test
```
Показать успешные результаты проверки структуры, OpenAPI и публичного smoke-теста.
### 3. Проверка компенсации и reconciler
```bash
make test-compensation
make test-reconcile
make reconcile
```
Показать 5 успешных тестов компенсации, 8 успешных тестов reconciler и JSON-отчёт сверки в режиме `dry-run`.
Последняя зафиксированная сверка:
```json
{
"mode": "dry-run",
"grace_hours": 24,
"database_objects": 33,
"storage_objects": 33,
"orphan_objects": [],
"missing_objects": [],
"deleted_objects": [],
"skipped_objects": [],
"duration_seconds": 0.0263
}
```
Количество объектов зависит от текущих тестовых данных и при повторном запуске может отличаться.
### 4. Демонстрация нагрузки
```bash
make load
```
Показать количество успешных запросов, RPS, ошибки и задержки p50/p95/p99.
### 5. Демонстрация отказа одной API-реплики
```bash
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
docker compose up -d api-1 api-2
docker compose ps api-1 api-2
```
Показать, что сценарий действительно останавливает одну реплику, а затем восстановить обе.
### 6. Демонстрация сохранности данных
```bash
make test-persistence ACTION_SCRIPT=./scripts/restart.sh
```
Скрипт `scripts/restart.sh` перезапускает PostgreSQL, Redis, `api-1` и `api-2`. Проверка должна подтвердить сохранение данных и сессии после восстановления.
### 7. Повторная проверка согласованности
```bash
make reconcile
```
Показать отсутствие незарегистрированных и отсутствующих объектов после испытаний.
**Режим `make reconcile-repair` во время защиты без предварительного просмотра и согласования не запускать:** он может удалять устаревшие незарегистрированные объекты.
### 8. Завершение демонстрации
```bash
docker compose down
```
Команда останавливает контейнеры, сохраняя данные PostgreSQL, Redis и MinIO.
+149
View File
@@ -0,0 +1,149 @@
# A generic, single database configuration.
[alembic]
# path to migration scripts.
# this is typically a path given in POSIX (e.g. forward slashes)
# format, relative to the token %(here)s which refers to the location of this
# ini file
script_location = %(here)s/migrations
# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
# Uncomment the line below if you want the files to be prepended with date and time
# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
# for all available tokens
# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
# Or organize into date-based subdirectories (requires recursive_version_locations = true)
# file_template = %%(year)d/%%(month).2d/%%(day).2d_%%(hour).2d%%(minute).2d_%%(second).2d_%%(rev)s_%%(slug)s
# sys.path path, will be prepended to sys.path if present.
# defaults to the current working directory. for multiple paths, the path separator
# is defined by "path_separator" below.
prepend_sys_path = .
# timezone to use when rendering the date within the migration file
# as well as the filename.
# If specified, requires the tzdata library which can be installed by adding
# `alembic[tz]` to the pip requirements.
# string value is passed to ZoneInfo()
# leave blank for localtime
# timezone =
# max length of characters to apply to the "slug" field
# truncate_slug_length = 40
# set to 'true' to run the environment during
# the 'revision' command, regardless of autogenerate
# revision_environment = false
# set to 'true' to allow .pyc and .pyo files without
# a source .py file to be detected as revisions in the
# versions/ directory
# sourceless = false
# version location specification; This defaults
# to <script_location>/versions. When using multiple version
# directories, initial revisions must be specified with --version-path.
# The path separator used here should be the separator specified by "path_separator"
# below.
# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
# path_separator; This indicates what character is used to split lists of file
# paths, including version_locations and prepend_sys_path within configparser
# files such as alembic.ini.
# The default rendered in new alembic.ini files is "os", which uses os.pathsep
# to provide os-dependent path splitting.
#
# Note that in order to support legacy alembic.ini files, this default does NOT
# take place if path_separator is not present in alembic.ini. If this
# option is omitted entirely, fallback logic is as follows:
#
# 1. Parsing of the version_locations option falls back to using the legacy
# "version_path_separator" key, which if absent then falls back to the legacy
# behavior of splitting on spaces and/or commas.
# 2. Parsing of the prepend_sys_path option falls back to the legacy
# behavior of splitting on spaces, commas, or colons.
#
# Valid values for path_separator are:
#
# path_separator = :
# path_separator = ;
# path_separator = space
# path_separator = newline
#
# Use os.pathsep. Default configuration used for new projects.
path_separator = os
# set to 'true' to search source files recursively
# in each "version_locations" directory
# new in Alembic version 1.10
# recursive_version_locations = false
# the output encoding used when revision files
# are written from script.py.mako
# output_encoding = utf-8
# database URL. This is consumed by the user-maintained env.py script only.
# other means of configuring database URLs may be customized within the env.py
# file.
sqlalchemy.url =
[post_write_hooks]
# post_write_hooks defines scripts or Python functions that are run
# on newly generated revision scripts. See the documentation for further
# detail and examples
# format using "black" - use the console_scripts runner, against the "black" entrypoint
# hooks = black
# black.type = console_scripts
# black.entrypoint = black
# black.options = -l 79 REVISION_SCRIPT_FILENAME
# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
# hooks = ruff
# ruff.type = module
# ruff.module = ruff
# ruff.options = check --fix REVISION_SCRIPT_FILENAME
# Alternatively, use the exec runner to execute a binary found on your PATH
# hooks = ruff
# ruff.type = exec
# ruff.executable = ruff
# ruff.options = check --fix REVISION_SCRIPT_FILENAME
# Logging configuration. This is also consumed by the user-maintained
# env.py script only.
[loggers]
keys = root,sqlalchemy,alembic
[handlers]
keys = console
[formatters]
keys = generic
[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 = generic
[formatter_generic]
format = %(levelname)-5.5s [%(name)s] %(message)s
datefmt = %H:%M:%S
+176
View File
@@ -0,0 +1,176 @@
x-api: &api
build:
context: .
dockerfile: Dockerfile
environment: &api-environment
APP_ENV: lab
SESSION_TTL_SECONDS: 3600
DATABASE_URL_FILE: /run/secrets/database_url
CACHE_URL_FILE: /run/secrets/cache_url
S3_ENDPOINT: http://s3:9000
S3_REGION: us-east-1
S3_BUCKET: messenger-attachments
S3_ACCESS_KEY_ID_FILE: /run/secrets/s3_access_key_id
S3_SECRET_ACCESS_KEY_FILE: /run/secrets/s3_secret_access_key
MAX_UPLOAD_BYTES: 10485760
MAX_IMAGE_PIXELS: 40000000
secrets:
- database_url
- cache_url
- s3_access_key_id
- s3_secret_access_key
depends_on:
migrate:
condition: service_completed_successfully
redis:
condition: service_healthy
s3-init:
condition: service_completed_successfully
expose:
- "8080"
restart: unless-stopped
stop_grace_period: 15s
mem_limit: 512m
cpus: 1.0
services:
postgres:
image: postgres:17.6
environment:
POSTGRES_DB: messenger
POSTGRES_USER: lab2
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
secrets:
- postgres_password
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U lab2 -d messenger"]
interval: 5s
timeout: 3s
retries: 10
restart: unless-stopped
cpus: 1.0
mem_limit: 768m
redis:
image: redis:8.2.2
command:
- redis-server
- --appendonly
- "yes"
- --appendfsync
- everysec
volumes:
- redis_data:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 3s
retries: 10
restart: unless-stopped
cpus: 0.5
mem_limit: 256m
s3:
image: dappros/minio:RELEASE.2025-09-07T16-13-09Z
command: server /data --console-address ":9001"
environment:
MINIO_ROOT_USER_FILE: /run/secrets/minio_root_user
MINIO_ROOT_PASSWORD_FILE: /run/secrets/minio_root_password
secrets:
- minio_root_user
- minio_root_password
- s3_access_key_id
- s3_secret_access_key
volumes:
- s3_data:/data
ports:
- "127.0.0.1:9001:9001"
healthcheck:
test: [ "CMD", "mc", "ready", "local" ]
interval: 10s
timeout: 5s
retries: 10
start_period: 15s
restart: unless-stopped
cpus: 1.0
mem_limit: 512m
s3-init:
image: dappros/minio:RELEASE.2025-09-07T16-13-09Z
entrypoint: [ "/bin/sh", "/config/init.sh" ]
volumes:
- ./infra/minio/init.sh:/config/init.sh:ro
- ./infra/minio/attachments-policy.json:/config/attachments-policy.json:ro
secrets:
- minio_root_user
- minio_root_password
- s3_access_key_id
- s3_secret_access_key
depends_on:
s3:
condition: service_healthy
restart: "no"
cpus: 0.5
mem_limit: 256m
migrate:
build:
context: .
dockerfile: Dockerfile
command: ["alembic", "upgrade", "head"]
secrets:
- database_url
depends_on:
postgres:
condition: service_healthy
restart: "no"
cpus: 1.0
mem_limit: 512m
api-1:
<<: *api
environment:
<<: *api-environment
INSTANCE_ID: api-1
api-2:
<<: *api
environment:
<<: *api-environment
INSTANCE_ID: api-2
nginx:
image: nginx:1.29-alpine
ports:
- "8080:8080"
volumes:
- ./infra/nginx.conf:/etc/nginx/nginx.conf:ro
depends_on:
- api-1
- api-2
restart: unless-stopped
cpus: 0.5
mem_limit: 256m
secrets:
postgres_password:
file: ./secrets/postgres_password
database_url:
file: ./secrets/database_url
cache_url:
file: ./secrets/cache_url
minio_root_user:
file: ./secrets/minio_root_user
minio_root_password:
file: ./secrets/minio_root_password
s3_access_key_id:
file: ./secrets/s3_access_key_id
s3_secret_access_key:
file: ./secrets/s3_secret_access_key
volumes:
postgres_data:
redis_data:
s3_data:
+26
View File
@@ -0,0 +1,26 @@
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::messenger-attachments"
]
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::messenger-attachments/*"
]
}
]
}
+19
View File
@@ -0,0 +1,19 @@
#!/bin/sh
set -eu
ROOT_USER="$(cat /run/secrets/minio_root_user)"
ROOT_PASSWORD="$(cat /run/secrets/minio_root_password)"
APP_USER="$(cat /run/secrets/s3_access_key_id)"
APP_PASSWORD="$(cat /run/secrets/s3_secret_access_key)"
mc alias set local http://s3:9000 "$ROOT_USER" "$ROOT_PASSWORD"
mc mb --ignore-existing local/messenger-attachments
mc anonymous set private local/messenger-attachments
mc admin policy create local messenger-attachments-rw /config/attachments-policy.json
mc admin user add local "$APP_USER" "$APP_PASSWORD"
mc admin policy attach local messenger-attachments-rw --user "$APP_USER"
mc admin user info local "$APP_USER"
mc ls local/messenger-attachments
+37
View File
@@ -0,0 +1,37 @@
events {
worker_connections 1024;
}
http {
resolver 127.0.0.11 valid=5s ipv6=off;
resolver_timeout 2s;
upstream api_backend {
zone api_backend 64k;
server api-1:8080 resolve max_fails=1 fail_timeout=5s;
server api-2:8080 resolve max_fails=1 fail_timeout=5s;
}
server {
listen 8080;
client_max_body_size 12m;
location / {
proxy_pass http://api_backend;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 2s;
proxy_read_timeout 10s;
proxy_send_timeout 10s;
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2;
}
}
}
+1
View File
@@ -0,0 +1 @@
Generic single-database configuration with an async dbapi.
+50
View File
@@ -0,0 +1,50 @@
import asyncio
from alembic import context
from sqlalchemy import pool
from sqlalchemy.ext.asyncio import async_engine_from_config
config = context.config
DATABASE_URL_FILE = "/run/secrets/database_url"
def read_database_url() -> str:
with open(DATABASE_URL_FILE, encoding="utf-8") as file:
return file.read().strip()
config.set_main_option("sqlalchemy.url", read_database_url())
target_metadata = None
def do_run_migrations(connection) -> None:
context.configure(
connection=connection,
target_metadata=target_metadata,
)
with context.begin_transaction():
context.run_migrations()
async def run_async_migrations() -> None:
connectable = async_engine_from_config(
config.get_section(config.config_ini_section, {}),
prefix="sqlalchemy.",
poolclass=pool.NullPool,
)
async with connectable.connect() as connection:
await connection.run_sync(do_run_migrations)
await connectable.dispose()
def run_migrations_online() -> None:
asyncio.run(run_async_migrations())
run_migrations_online()
+28
View File
@@ -0,0 +1,28 @@
"""${message}
Revision ID: ${up_revision}
Revises: ${down_revision | comma,n}
Create Date: ${create_date}
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
${imports if imports else ""}
# revision identifiers, used by Alembic.
revision: str = ${repr(up_revision)}
down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
def upgrade() -> None:
"""Upgrade schema."""
${upgrades if upgrades else "pass"}
def downgrade() -> None:
"""Downgrade schema."""
${downgrades if downgrades else "pass"}
@@ -0,0 +1,61 @@
"""Message idempotency for lab 3.
Revision ID: b3a91c0e7d42
Revises: f7c51e1e945b
"""
from alembic import op
import sqlalchemy as sa
revision = "b3a91c0e7d42"
down_revision = "f7c51e1e945b"
branch_labels = None
depends_on = None
def upgrade() -> None:
op.create_table(
"message_idempotency",
sa.Column("user_id", sa.Uuid(), nullable=False),
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("key", sa.String(length=128), nullable=False),
sa.Column("request_hash", sa.String(length=64), nullable=False),
sa.Column("message_id", sa.Uuid(), nullable=False),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
server_default=sa.text("CURRENT_TIMESTAMP"),
nullable=False,
),
sa.ForeignKeyConstraint(
["user_id"],
["users.id"],
ondelete="CASCADE",
),
sa.ForeignKeyConstraint(
["chat_id"],
["chats.id"],
ondelete="CASCADE",
),
sa.ForeignKeyConstraint(
["message_id"],
["messages.id"],
ondelete="CASCADE",
),
sa.PrimaryKeyConstraint("user_id", "chat_id", "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")
@@ -0,0 +1,78 @@
from alembic import op
import sqlalchemy as sa
revision = "c8f42a19e6b0"
down_revision = "b3a91c0e7d42"
branch_labels = None
depends_on = None
def upgrade() -> None:
op.create_table(
"attachments",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("uploader_id", sa.Uuid(), nullable=False),
sa.Column("filename", sa.String(length=255), nullable=False),
sa.Column("content_type", sa.String(length=100), nullable=False),
sa.Column("size_bytes", sa.BigInteger(), nullable=False),
sa.Column("s3_key", sa.String(length=512), nullable=False),
sa.Column("status", sa.String(length=20), nullable=False),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
server_default=sa.text("CURRENT_TIMESTAMP"),
nullable=False,
),
sa.ForeignKeyConstraint(
["chat_id"],
["chats.id"],
ondelete="CASCADE",
),
sa.ForeignKeyConstraint(
["uploader_id"],
["users.id"],
ondelete="RESTRICT",
),
sa.PrimaryKeyConstraint("id"),
sa.UniqueConstraint("s3_key", name="uq_attachments_s3_key"),
sa.CheckConstraint(
"size_bytes > 0 AND size_bytes <= 10485760",
name="ck_attachments_size",
),
sa.CheckConstraint(
"status IN ('pending', 'ready')",
name="ck_attachments_status",
),
)
op.create_index(
"ix_attachments_chat_id",
"attachments",
["chat_id"],
)
op.create_table(
"message_attachments",
sa.Column("message_id", sa.Uuid(), nullable=False),
sa.Column("attachment_id", sa.Uuid(), nullable=False),
sa.ForeignKeyConstraint(
["message_id"],
["messages.id"],
ondelete="CASCADE",
),
sa.ForeignKeyConstraint(
["attachment_id"],
["attachments.id"],
ondelete="RESTRICT",
),
sa.PrimaryKeyConstraint("message_id", "attachment_id"),
)
def downgrade() -> None:
op.drop_table("message_attachments")
op.drop_index("ix_attachments_chat_id", table_name="attachments")
op.drop_table("attachments")
@@ -0,0 +1,80 @@
from alembic import op
import sqlalchemy as sa
revision = "d9e53b20f7c1"
down_revision = "c8f42a19e6b0"
branch_labels = None
depends_on = None
def upgrade() -> None:
op.alter_column(
"attachments",
"uploader_id",
new_column_name="owner_id",
)
op.add_column(
"attachments",
sa.Column(
"sha256",
sa.String(length=64),
nullable=False,
),
)
op.add_column(
"attachments",
sa.Column(
"variants",
sa.JSON(),
nullable=False,
server_default=sa.text("'[]'::json"),
),
)
op.add_column(
"attachments",
sa.Column(
"error_code",
sa.String(length=100),
nullable=True,
),
)
op.add_column(
"attachments",
sa.Column(
"updated_at",
sa.DateTime(timezone=True),
server_default=sa.text("CURRENT_TIMESTAMP"),
nullable=False,
),
)
op.create_check_constraint(
"ck_attachments_sha256",
"attachments",
"sha256 ~ '^[a-f0-9]{64}$'",
)
def downgrade() -> None:
op.drop_constraint(
"ck_attachments_sha256",
"attachments",
type_="check",
)
op.drop_column("attachments", "updated_at")
op.drop_column("attachments", "error_code")
op.drop_column("attachments", "variants")
op.drop_column("attachments", "sha256")
op.alter_column(
"attachments",
"owner_id",
new_column_name="uploader_id",
)
@@ -0,0 +1,110 @@
"""initial schema
Revision ID: f7c51e1e945b
Revises:
Create Date: 2026-10-07 18:33:37.771593
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
# revision identifiers, used by Alembic.
revision: str = "f7c51e1e945b"
down_revision: Union[str, Sequence[str], None] = None
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None
def upgrade() -> None:
op.create_table(
"users",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("username", sa.String(length=32), nullable=False),
sa.Column("display_name", sa.String(length=100), nullable=False),
sa.Column("password_hash", sa.Text(), nullable=False),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
server_default=sa.text("CURRENT_TIMESTAMP"),
nullable=False,
),
sa.PrimaryKeyConstraint("id"),
sa.UniqueConstraint("username", name="uq_users_username"),
)
op.create_table(
"chats",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("title", sa.String(length=100), nullable=False),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
server_default=sa.text("CURRENT_TIMESTAMP"),
nullable=False,
),
sa.PrimaryKeyConstraint("id"),
)
op.create_table(
"chat_members",
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("user_id", sa.Uuid(), nullable=False),
sa.ForeignKeyConstraint(
["chat_id"],
["chats.id"],
ondelete="CASCADE",
),
sa.ForeignKeyConstraint(
["user_id"],
["users.id"],
ondelete="CASCADE",
),
sa.PrimaryKeyConstraint("chat_id", "user_id"),
)
op.create_table(
"messages",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("chat_id", sa.Uuid(), nullable=False),
sa.Column("sender_id", sa.Uuid(), nullable=False),
sa.Column("text", sa.String(length=4000), nullable=False),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
server_default=sa.text("CURRENT_TIMESTAMP"),
nullable=False,
),
sa.ForeignKeyConstraint(
["chat_id"],
["chats.id"],
ondelete="CASCADE",
),
sa.ForeignKeyConstraint(
["sender_id"],
["users.id"],
ondelete="RESTRICT",
),
sa.PrimaryKeyConstraint("id"),
)
op.create_index(
"ix_messages_chat_created_id",
"messages",
["chat_id", "created_at", "id"],
unique=False,
)
def downgrade() -> None:
op.drop_index(
"ix_messages_chat_created_id",
table_name="messages",
)
op.drop_table("messages")
op.drop_table("chat_members")
op.drop_table("chats")
op.drop_table("users")
+22
View File
@@ -0,0 +1,22 @@
annotated-doc==0.0.5
annotated-types==0.8.0
anyio==4.15.1
click==8.5.0
fastapi==0.141.1
h11==0.16.0
idna==3.20
pydantic==2.13.5
pydantic_core==2.46.5
starlette==1.7.0
typing-inspection==0.4.4
typing_extensions==4.16.0
uvicorn==0.53.0
SQLAlchemy==2.1.4
asyncpg==0.32.0
alembic==1.20.0
greenlet==3.5.6
argon2-cffi==25.1.0
redis==7.0.1
boto3==1.43.120
Pillow==13.0.0
python-multipart==0.0.32
+40
View File
@@ -0,0 +1,40 @@
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/.."
mkdir -p secrets
chmod 700 secrets
umask 077
create_random_secret() {
local name="$1"
local value="$2"
if [[ ! -s "secrets/$name" ]]; then
printf '%s\n' "$value" > "secrets/$name"
fi
chmod 644 "secrets/$name"
}
create_random_secret postgres_password "$(python3 -c 'import secrets; print(secrets.token_hex(24))')"
if [[ ! -s secrets/database_url ]]; then
PASSWORD="$(cat secrets/postgres_password)"
printf 'postgresql+asyncpg://lab2:%s@postgres:5432/messenger\n' "$PASSWORD" > secrets/database_url
fi
create_random_secret cache_url 'redis://redis:6379/0'
create_random_secret minio_root_user "minio-$(python3 -c 'import secrets; print(secrets.token_hex(12))')"
create_random_secret minio_root_password "$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
create_random_secret s3_access_key_id "$(python3 -c 'import secrets; print(secrets.token_hex(20))')"
create_random_secret s3_secret_access_key "$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
chmod 644 secrets/*
if [[ ! -f .env ]]; then
cp .env.example .env
fi
docker compose config --quiet
+121
View File
@@ -0,0 +1,121 @@
import argparse
import asyncio
import json
import sys
import time
from datetime import datetime, timedelta, timezone
from sqlalchemy import text
from src.database import SessionFactory, engine
from src.storage import S3_BUCKET, s3_client
def list_s3_objects() -> dict:
objects = {}
paginator = s3_client.get_paginator("list_objects_v2")
for page in paginator.paginate(Bucket=S3_BUCKET):
for item in page.get("Contents", []):
objects[item["Key"]] = item["LastModified"]
return objects
async def list_db_keys() -> set[str]:
async with SessionFactory() as session:
result = await session.execute(text("SELECT s3_key FROM attachments"))
return set(result.scalars().all())
async def db_key_exists(key: str) -> bool:
async with SessionFactory() as session:
result = await session.execute(
text("SELECT 1 FROM attachments WHERE s3_key = :key"),
{"key": key},
)
return result.first() is not None
def inspect_object(key: str):
return s3_client.head_object(Bucket=S3_BUCKET, Key=key)
def remove_object(key: str) -> None:
s3_client.delete_object(Bucket=S3_BUCKET, Key=key)
async def reconcile(repair: bool, grace_hours: int) -> int:
started = time.perf_counter()
try:
db_keys, s3_objects = await asyncio.gather(
list_db_keys(),
asyncio.to_thread(list_s3_objects),
)
s3_keys = set(s3_objects)
orphan_keys = sorted(s3_keys - db_keys)
missing_keys = sorted(db_keys - s3_keys)
cutoff = datetime.now(timezone.utc) - timedelta(hours=grace_hours)
deleted = []
skipped = []
if repair:
for key in orphan_keys:
if s3_objects[key] > cutoff:
skipped.append({"key": key, "reason": "grace_period"})
continue
if await db_key_exists(key):
skipped.append({"key": key, "reason": "database_record_exists"})
continue
metadata = await asyncio.to_thread(inspect_object, key)
if metadata["LastModified"] > cutoff:
skipped.append({"key": key, "reason": "object_too_recent"})
continue
if await db_key_exists(key):
skipped.append({"key": key, "reason": "database_record_exists"})
continue
await asyncio.to_thread(remove_object, key)
deleted.append(key)
report = {
"mode": "repair" if repair else "dry-run",
"grace_hours": grace_hours,
"database_objects": len(db_keys),
"storage_objects": len(s3_keys),
"orphan_objects": orphan_keys,
"missing_objects": missing_keys,
"deleted_objects": deleted,
"skipped_objects": skipped,
"duration_seconds": round(time.perf_counter() - started, 4),
}
print(json.dumps(report, indent=2, ensure_ascii=False))
return 0
except Exception as error:
print(f"Reconciliation failed: {error}", file=sys.stderr)
return 1
finally:
await engine.dispose()
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("--repair", action="store_true")
parser.add_argument("--grace-hours", type=int, default=24)
args = parser.parse_args()
if args.grace_hours < 1:
parser.error("--grace-hours must be at least 1")
sys.exit(asyncio.run(reconcile(args.repair, args.grace_hours)))
+4
View File
@@ -0,0 +1,4 @@
#!/usr/bin/env bash
set -euo pipefail
docker compose restart postgres redis api-1 api-2
+14
View File
@@ -0,0 +1,14 @@
#!/usr/bin/env bash
set -euo pipefail
: "${TARGET_INSTANCE_ID:?}"
case "$TARGET_INSTANCE_ID" in
api-1|api-2)
docker compose stop "$TARGET_INSTANCE_ID"
;;
*)
echo "Unknown instance: $TARGET_INSTANCE_ID" >&2
exit 1
;;
esac
View File
+86
View File
@@ -0,0 +1,86 @@
import base64
import binascii
import json
from datetime import datetime
from uuid import UUID
def encode_cursor(
chat_id: UUID,
created_at: datetime,
message_id: UUID,
) -> str:
data = {
"chat_id": str(chat_id),
"created_at": created_at.isoformat(),
"message_id": str(message_id),
}
raw = json.dumps(
data,
separators=(",", ":"),
).encode("utf-8")
return base64.urlsafe_b64encode(raw).decode("ascii")
def decode_cursor(cursor: str) -> tuple[UUID, datetime, UUID]:
try:
raw = base64.urlsafe_b64decode(cursor.encode("ascii"))
data = json.loads(raw.decode("utf-8"))
if not isinstance(data, dict):
raise ValueError("Invalid cursor")
if set(data.keys()) != {
"chat_id",
"created_at",
"message_id",
}:
raise ValueError("Invalid cursor")
chat_id = UUID(data["chat_id"])
created_at = datetime.fromisoformat(data["created_at"])
message_id = UUID(data["message_id"])
if created_at.tzinfo is None or created_at.utcoffset() is None:
raise ValueError("Invalid cursor")
return chat_id, created_at, message_id
except (
ValueError,
KeyError,
TypeError,
UnicodeError,
binascii.Error,
json.JSONDecodeError,
) as exc:
raise ValueError("Invalid cursor") from exc
def encode_chat_cursor(user_id: UUID, created_at: datetime, chat_id: UUID) -> str:
data = {
"user_id": str(user_id),
"created_at": created_at.isoformat(),
"chat_id": str(chat_id),
}
raw = json.dumps(data, separators=(",", ":")).encode("utf-8")
return base64.urlsafe_b64encode(raw).decode("ascii")
def decode_chat_cursor(cursor: str) -> tuple[UUID, datetime, UUID]:
try:
raw = base64.b64decode(cursor.encode("ascii"), altchars=b"-_", validate=True)
data = json.loads(raw.decode("utf-8"))
if not isinstance(data, dict) or set(data) != {"user_id", "created_at", "chat_id"}:
raise ValueError("Invalid cursor")
user_id = UUID(data["user_id"])
created_at = datetime.fromisoformat(data["created_at"])
chat_id = UUID(data["chat_id"])
if created_at.tzinfo is None or created_at.utcoffset() is None:
raise ValueError("Invalid cursor")
return user_id, created_at, chat_id
except (ValueError, TypeError, KeyError, UnicodeError, binascii.Error, json.JSONDecodeError) as exc:
raise ValueError("Invalid cursor") from exc
+57
View File
@@ -0,0 +1,57 @@
from collections.abc import AsyncIterator
import socket
from sqlalchemy import text
from sqlalchemy.exc import SQLAlchemyError
from sqlalchemy.ext.asyncio import (
AsyncSession,
async_sessionmaker,
create_async_engine,
)
DATABASE_URL_FILE = "/run/secrets/database_url"
POOL_SIZE = 5
MAX_OVERFLOW = 5
POOL_TIMEOUT_SECONDS = 5
DB_CONNECT_TIMEOUT_SECONDS = 5
def read_database_url() -> str:
with open(DATABASE_URL_FILE, encoding="utf-8") as file:
return file.read().strip()
database_url = read_database_url()
engine = create_async_engine(
database_url,
pool_size=POOL_SIZE,
max_overflow=MAX_OVERFLOW,
pool_timeout=POOL_TIMEOUT_SECONDS,
connect_args={
"timeout": DB_CONNECT_TIMEOUT_SECONDS,
},
pool_pre_ping=True,
)
SessionFactory = async_sessionmaker(
bind=engine,
expire_on_commit=False,
)
async def get_db_session() -> AsyncIterator[AsyncSession]:
async with SessionFactory() as session:
yield session
async def ping_database() -> bool:
try:
async with engine.connect() as connection:
await connection.execute(text("SELECT 1"))
return True
except (SQLAlchemyError, OSError):
return False
+12
View File
@@ -0,0 +1,12 @@
class APIError(Exception):
def __init__(
self,
status_code: int,
code: str,
message: str,
headers: dict[str, str] | None = None,
):
self.status_code = status_code
self.code = code
self.message = message
self.headers = headers
+71
View File
@@ -0,0 +1,71 @@
import hashlib
import io
import os
from PIL import Image, UnidentifiedImageError
from src.errors import APIError
MAX_UPLOAD_BYTES = int(os.getenv("MAX_UPLOAD_BYTES", "10485760"))
MAX_IMAGE_PIXELS = int(os.getenv("MAX_IMAGE_PIXELS", "40000000"))
ALLOWED_FORMATS = {
"PNG": "image/png",
"JPEG": "image/jpeg",
}
def validate_image(body: bytes, content_type: str) -> tuple[int, str]:
if content_type not in ALLOWED_FORMATS.values():
raise APIError(
status_code=415,
code="unsupported_media_type",
message="Only PNG and JPEG images are supported",
)
size_bytes = len(body)
if size_bytes > MAX_UPLOAD_BYTES:
raise APIError(
status_code=413,
code="payload_too_large",
message="Image exceeds maximum upload size",
)
if size_bytes == 0:
raise APIError(
status_code=400,
code="invalid_request",
message="Image must not be empty",
)
try:
with Image.open(io.BytesIO(body)) as image:
if image.format not in ALLOWED_FORMATS:
raise ValueError("Unsupported image format")
if ALLOWED_FORMATS[image.format] != content_type:
raise ValueError("Content-Type does not match image format")
width, height = image.size
if width * height > MAX_IMAGE_PIXELS:
raise APIError(
status_code=413,
code="payload_too_large",
message="Image exceeds maximum pixel count",
)
image.load()
except APIError:
raise
except (UnidentifiedImageError, OSError, ValueError, Image.DecompressionBombError) as exc:
raise APIError(
status_code=400,
code="invalid_request",
message="Invalid image data",
) from exc
return size_bytes, hashlib.sha256(body).hexdigest()
+724
View File
@@ -0,0 +1,724 @@
from datetime import datetime, timedelta, timezone
from uuid import UUID, uuid4
import os
import re
import base64
import binascii
import asyncio
from fastapi import Depends, FastAPI, Request, Header, Query
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse, Response
from fastapi.security import (
HTTPAuthorizationCredentials,
HTTPBearer,
)
from botocore.exceptions import BotoCoreError, ClientError
from sqlalchemy.exc import IntegrityError, SQLAlchemyError
from sqlalchemy.ext.asyncio import AsyncSession
from starlette.exceptions import HTTPException as StarletteHTTPException
from contextlib import asynccontextmanager
from src.database import engine, get_db_session, ping_database, SessionFactory
from src.errors import APIError
from src.models import CreateUser, SessionResponse, User, CreateChat, Chat, ChatPage, CreateMessage, Message, MessagePage, Attachment
from src.repositories import (
create_chat,
list_chats,
create_user as create_user_in_db,
get_user_by_id,
get_chat_by_id,
get_user_credentials_by_username,
create_message,
get_messages,
create_attachment,
get_attachment,
attachment_key_exists,
)
from src.security import verify_password
from src.sessions import (
create_session,
delete_session,
get_session_user_id,
ping_session_store,
redis_client,
)
from src.images import MAX_UPLOAD_BYTES, validate_image
from src.storage import delete_object, put_object, get_object
@asynccontextmanager
async def lifespan(app: FastAPI):
yield
await redis_client.aclose()
await engine.dispose()
app = FastAPI(lifespan=lifespan)
INSTANCE_ID = os.getenv("INSTANCE_ID") or str(uuid4())
bearer_security = HTTPBearer(auto_error=False)
async def get_current_user(
credentials: HTTPAuthorizationCredentials | None = Depends(bearer_security),
session: AsyncSession = Depends(get_db_session),
) -> User:
if credentials is None or credentials.scheme.lower() != "bearer":
raise APIError(
status_code=401,
code="unauthorized",
message="Unauthorized",
headers={
"WWW-Authenticate": "Bearer",
},
)
user_id = await get_session_user_id(credentials.credentials)
if user_id is None:
raise APIError(
status_code=401,
code="unauthorized",
message="Unauthorized",
headers={
"WWW-Authenticate": "Bearer",
},
)
user = await get_user_by_id(session, user_id)
if user is None:
raise APIError(
status_code=401,
code="unauthorized",
message="Unauthorized",
headers={
"WWW-Authenticate": "Bearer",
},
)
return user
@app.middleware("http")
async def request_middleware(request: Request, call_next):
request_id = str(uuid4())
request.state.request_id = request_id
if request.method in {"POST", "PUT", "PATCH"}:
content_type = request.headers.get("content-type")
if content_type is not None:
media_type = content_type.split(";", 1)[0].strip().lower()
is_attachment_upload = (
request.method == "POST"
and re.fullmatch(
r"/api/v1/chats/[^/]+/attachments",
request.url.path,
) is not None
)
allowed_media_types = (
{"image/png", "image/jpeg"}
if is_attachment_upload
else {"application/json"}
)
if media_type not in allowed_media_types:
return JSONResponse(
status_code=415,
content={
"error": {
"code": "unsupported_media_type",
"message": "Unsupported media type",
"request_id": request_id,
}
},
headers={
"X-Request-Id": request_id,
"X-Instance-Id": INSTANCE_ID,
},
)
response = await call_next(request)
response.headers["X-Request-Id"] = request_id
response.headers["X-Instance-Id"] = INSTANCE_ID
return response
@app.exception_handler(RequestValidationError)
async def validation_exception_handler(
request: Request,
exc: RequestValidationError,
):
request_id = request.state.request_id
return JSONResponse(
status_code=400,
content={
"error": {
"code": "invalid_request",
"message": "Invalid request",
"request_id": request_id,
}
},
)
@app.exception_handler(APIError)
async def api_error_handler(request: Request, exc: APIError):
request_id = request.state.request_id
return JSONResponse(
status_code=exc.status_code,
content={
"error": {
"code": exc.code,
"message": exc.message,
"request_id": request_id,
}
},
headers=exc.headers,
)
@app.exception_handler(SQLAlchemyError)
async def database_exception_handler(
request: Request,
exc: SQLAlchemyError,
):
request_id = request.state.request_id
return JSONResponse(
status_code=503,
content={
"error": {
"code": "unavailable",
"message": "Database unavailable",
"request_id": request_id,
}
},
)
@app.exception_handler(OSError)
async def database_connection_exception_handler(
request: Request,
exc: OSError,
):
request_id = request.state.request_id
return JSONResponse(
status_code=503,
content={
"error": {
"code": "unavailable",
"message": "Database unavailable",
"request_id": request_id,
}
},
)
@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(
request: Request,
exc: StarletteHTTPException,
):
request_id = request.state.request_id
if exc.status_code == 404:
code = "not_found"
message = "Not found"
else:
code = "invalid_request"
message = "Invalid request"
return JSONResponse(
status_code=exc.status_code,
content={
"error": {
"code": code,
"message": message,
"request_id": request_id,
}
},
headers=exc.headers,
)
@app.exception_handler(Exception)
async def unexpected_exception_handler(
request: Request,
exc: Exception,
):
request_id = request.state.request_id
return JSONResponse(
status_code=500,
content={
"error": {
"code": "internal_error",
"message": "Internal server error",
"request_id": request_id,
}
},
)
@app.get("/health/live")
async def health_live():
return {"status": "ok"}
@app.get("/health/ready")
async def health_ready():
database_ready = await ping_database()
session_store_ready = await ping_session_store()
if not database_ready or not session_store_ready:
raise APIError(
status_code=503,
code="unavailable",
message="Service dependencies unavailable",
)
return {"status": "ok"}
@app.post("/api/v1/users", response_model=User, status_code=201)
async def create_user(
data: CreateUser,
session: AsyncSession = Depends(get_db_session),
):
try:
async with session.begin():
return await create_user_in_db(session, data)
except IntegrityError as exc:
raise APIError(
status_code=409,
code="conflict",
message="Username already exists",
) from exc
@app.get("/api/v1/users/me", response_model=User)
async def get_me(
current_user: User = Depends(get_current_user),
):
return current_user
@app.post(
"/api/v1/auth/sessions",
response_model=SessionResponse,
status_code=201,
)
async def create_auth_session(
authorization: str | None = Header(default=None),
session: AsyncSession = Depends(get_db_session),
):
credentials = None
if authorization is not None:
scheme, separator, encoded = authorization.partition(" ")
if separator and scheme.lower() == "basic":
try:
decoded = base64.b64decode(encoded.strip(), validate=True).decode("utf-8")
if ":" in decoded:
credentials = decoded.split(":", 1)
except (ValueError, UnicodeError, binascii.Error):
pass
if credentials is None:
raise APIError(
status_code=401,
code="unauthorized",
message="Unauthorized",
headers={
"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"',
},
)
user_credentials = await get_user_credentials_by_username(
session,
credentials[0],
)
if user_credentials is None:
raise APIError(
status_code=401,
code="unauthorized",
message="Unauthorized",
headers={
"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"',
},
)
if not verify_password(
user_credentials.password_hash,
credentials[1],
):
raise APIError(
status_code=401,
code="unauthorized",
message="Unauthorized",
headers={
"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"',
},
)
user = User(
id=user_credentials.id,
username=user_credentials.username,
display_name=user_credentials.display_name,
created_at=user_credentials.created_at,
)
token, ttl = await create_session(user.id)
expires_at = datetime.now(timezone.utc) + timedelta(seconds=ttl)
return SessionResponse(
token=token,
token_type="Bearer",
expires_at=expires_at,
user=user,
)
@app.delete(
"/api/v1/auth/sessions/current",
status_code=204,
)
async def delete_current_session(
credentials: HTTPAuthorizationCredentials | None = Depends(bearer_security),
current_user: User = Depends(get_current_user),
):
await delete_session(credentials.credentials)
@app.post(
"/api/v1/chats",
response_model=Chat,
status_code=201,
)
async def create_chat_endpoint(
data: CreateChat,
current_user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_db_session),
) -> Chat:
try:
chat = await create_chat(
session=session,
data=data,
current_user_id=current_user.id,
)
await session.commit()
except Exception:
await session.rollback()
raise
return chat
@app.get(
"/api/v1/chats",
response_model=ChatPage,
)
async def get_chats(
limit: int = 50,
cursor: str | None = None,
current_user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_db_session),
) -> ChatPage:
if limit < 1 or limit > 100:
raise APIError(
status_code=400,
code="invalid_request",
message="Limit must be between 1 and 100",
)
return await list_chats(
session=session,
current_user_id=current_user.id,
limit=limit,
cursor=cursor,
)
@app.get(
"/api/v1/chats/{chat_id}",
response_model=Chat,
)
async def get_chat_endpoint(
chat_id: UUID,
current_user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_db_session),
) -> Chat:
chat = await get_chat_by_id(
session=session,
chat_id=chat_id,
current_user_id=current_user.id,
)
if chat is None:
raise APIError(
status_code=404,
code="not_found",
message="Chat not found",
)
return chat
@app.post(
"/api/v1/chats/{chat_id}/messages",
response_model=Message,
status_code=201,
)
async def create_message_endpoint(
chat_id: UUID,
data: CreateMessage,
idempotency_key: str | None = Header(
default=None,
alias="Idempotency-Key",
),
current_user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_db_session),
) -> Message:
if (
idempotency_key is None
or re.fullmatch(
r"[A-Za-z0-9._:-]{1,128}",
idempotency_key,
) is None
):
raise APIError(
status_code=400,
code="invalid_request",
message="Invalid or missing Idempotency-Key",
)
try:
message = await create_message(
session=session,
chat_id=chat_id,
current_user_id=current_user.id,
data=data,
idempotency_key=idempotency_key,
)
await session.commit()
except Exception:
await session.rollback()
raise
return message
@app.get(
"/api/v1/chats/{chat_id}/messages",
response_model=MessagePage,
)
async def get_messages_endpoint(
chat_id: UUID,
limit: int = 50,
cursor: str | None = None,
current_user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_db_session),
) -> MessagePage:
if limit < 1 or limit > 100:
raise APIError(
status_code=400,
code="invalid_request",
message="Limit must be between 1 and 100",
)
return await get_messages(
session=session,
chat_id=chat_id,
current_user_id=current_user.id,
limit=limit,
cursor=cursor,
)
@app.post(
"/api/v1/chats/{chat_id}/attachments",
response_model=Attachment,
status_code=201,
)
async def upload_attachment_endpoint(
chat_id: UUID,
request: Request,
filename: str = Query(min_length=1, max_length=255),
current_user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_db_session),
) -> Attachment:
chat = await get_chat_by_id(
session=session,
chat_id=chat_id,
current_user_id=current_user.id,
)
if chat is None:
raise APIError(
status_code=404,
code="not_found",
message="Chat not found",
)
content_type = request.headers.get("content-type", "").split(";", 1)[0].strip().lower()
if content_type not in {"image/png", "image/jpeg"}:
raise APIError(
status_code=415,
code="unsupported_media_type",
message="Only PNG and JPEG images are supported",
)
body = bytearray()
async for chunk in request.stream():
if len(body) + len(chunk) > MAX_UPLOAD_BYTES:
raise APIError(
status_code=413,
code="payload_too_large",
message="Image exceeds maximum upload size",
)
body.extend(chunk)
image_bytes = bytes(body)
size_bytes, sha256 = validate_image(image_bytes, content_type)
attachment_id = uuid4()
extension = "png" if content_type == "image/png" else "jpg"
s3_key = f"attachments/{chat_id}/{attachment_id}.{extension}"
try:
await put_object(
key=s3_key,
body=image_bytes,
content_type=content_type,
)
except (BotoCoreError, ClientError, OSError, TimeoutError) as exc:
raise APIError(
status_code=503,
code="unavailable",
message="Object storage unavailable",
) from exc
try:
attachment = await create_attachment(
session=session,
attachment_id=attachment_id,
chat_id=chat_id,
owner_id=current_user.id,
filename=filename,
content_type=content_type,
size_bytes=size_bytes,
sha256=sha256,
s3_key=s3_key,
)
await session.commit()
except BaseException:
try:
await session.rollback()
except Exception:
pass
try:
async with SessionFactory() as verification_session:
exists = await attachment_key_exists(
verification_session,
s3_key,
)
except Exception:
exists = True
if not exists:
try:
await asyncio.shield(delete_object(s3_key))
except Exception:
pass
raise
return attachment
@app.get(
"/api/v1/attachments/{attachment_id}",
response_model=Attachment,
)
async def get_attachment_endpoint(
attachment_id: UUID,
current_user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_db_session),
) -> Attachment:
result = await get_attachment(
session=session,
attachment_id=attachment_id,
current_user_id=current_user.id,
)
if result is None:
raise APIError(
status_code=404,
code="not_found",
message="Attachment not found",
)
attachment, s3_key = result
return attachment
@app.get("/api/v1/attachments/{attachment_id}/content")
async def get_attachment_content_endpoint(
attachment_id: UUID,
current_user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_db_session),
):
result = await get_attachment(
session=session,
attachment_id=attachment_id,
current_user_id=current_user.id,
)
if result is None:
raise APIError(
status_code=404,
code="not_found",
message="Attachment not found",
)
attachment, s3_key = result
try:
body = await get_object(s3_key)
except (BotoCoreError, ClientError, OSError, TimeoutError) as exc:
raise APIError(
status_code=503,
code="unavailable",
message="Object storage unavailable",
) from exc
return Response(
content=body,
media_type=attachment.content_type,
headers={
"Cache-Control": "private, no-store",
"X-Content-Type-Options": "nosniff",
},
)
+152
View File
@@ -0,0 +1,152 @@
from datetime import datetime
from uuid import UUID
from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
class CreateUser(BaseModel):
model_config = ConfigDict(extra="forbid")
username: str = Field(
min_length=3,
max_length=32,
pattern=r"^[a-z0-9_]+$",
)
display_name: str = Field(
min_length=1,
max_length=100,
)
password: str = Field(
min_length=12,
max_length=128,
)
@field_validator("display_name")
@classmethod
def validate_display_name(cls, value: str) -> str:
if not value.strip():
raise ValueError("Display name must not be blank")
return value
class User(BaseModel):
id: UUID
username: str
display_name: str
created_at: datetime
class SessionResponse(BaseModel):
token: str
token_type: str
expires_at: datetime
user: User
class CreateChat(BaseModel):
model_config = ConfigDict(extra="forbid")
title: str = Field(
min_length=1,
max_length=100,
)
member_ids: list[UUID] = Field(
min_length=1,
max_length=100,
)
@field_validator("title")
@classmethod
def validate_title(cls, value: str) -> str:
if not value.strip():
raise ValueError("Chat title must not be blank")
return value
@field_validator("member_ids")
@classmethod
def validate_member_ids(cls, value: list[UUID]) -> list[UUID]:
if len(value) != len(set(value)):
raise ValueError("Member IDs must be unique")
return value
class Chat(BaseModel):
id: UUID
title: str
member_ids: list[UUID]
created_at: datetime
class ChatPage(BaseModel):
items: list[Chat]
next_cursor: str | None
class CreateMessage(BaseModel):
model_config = ConfigDict(extra="forbid")
text: str = Field(max_length=4000)
attachment_ids: list[UUID] = Field(default_factory=list, max_length=10)
@field_validator("attachment_ids")
@classmethod
def validate_attachment_ids(cls, value: list[UUID]) -> list[UUID]:
if len(value) != len(set(value)):
raise ValueError("Attachment IDs must be unique")
return value
@model_validator(mode="after")
def validate_content(self):
if not self.text.strip() and not self.attachment_ids:
raise ValueError("Message must contain text or attachments")
return self
class Message(BaseModel):
id: UUID
chat_id: UUID
sender_id: UUID
text: str
created_at: datetime
attachment_ids: list[UUID] = Field(default_factory=list)
class MessagePage(BaseModel):
items: list[Message]
next_cursor: str | None
class Variant(BaseModel):
model_config = ConfigDict(extra="forbid")
name: str = Field(pattern=r"^(thumbnail|crop|optimized)$")
content_type: str = Field(pattern=r"^image/(jpeg|png|webp)$")
size_bytes: int = Field(ge=1)
width: int = Field(ge=1)
height: int = Field(ge=1)
sha256: str = Field(pattern=r"^[a-f0-9]{64}$")
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: str = Field(pattern=r"^image/(png|jpeg)$")
size_bytes: int = Field(ge=1, le=10485760)
sha256: str = Field(pattern=r"^[a-f0-9]{64}$")
status: str = Field(pattern=r"^ready$")
variants: list[Variant]
error_code: str | None
created_at: datetime
updated_at: datetime
+876
View File
@@ -0,0 +1,876 @@
from uuid import UUID, uuid4
import hashlib
import json
from sqlalchemy import text
from sqlalchemy.ext.asyncio import AsyncSession
from src.models import Attachment, Chat, ChatPage, CreateChat, CreateUser, User, CreateMessage, Message, MessagePage
from src.security import hash_password
from src.errors import APIError
from src.cursor import decode_cursor, encode_cursor, decode_chat_cursor, encode_chat_cursor
async def create_user(
session: AsyncSession,
data: CreateUser,
) -> User:
user_id = uuid4()
password_hash = hash_password(data.password)
result = await session.execute(
text(
"""
INSERT INTO users (
id,
username,
display_name,
password_hash
)
VALUES (
:id,
:username,
:display_name,
:password_hash
)
RETURNING
id,
username,
display_name,
created_at
"""
),
{
"id": user_id,
"username": data.username,
"display_name": data.display_name,
"password_hash": password_hash,
},
)
row = result.one()
return User(
id=UUID(str(row.id)),
username=row.username,
display_name=row.display_name,
created_at=row.created_at,
)
async def get_user_credentials_by_username(
session: AsyncSession,
username: str,
):
result = await session.execute(
text(
"""
SELECT
id,
username,
display_name,
password_hash,
created_at
FROM users
WHERE username = :username
"""
),
{
"username": username,
},
)
return result.one_or_none()
async def get_user_by_id(
session: AsyncSession,
user_id: UUID,
) -> User | None:
result = await session.execute(
text(
"""
SELECT
id,
username,
display_name,
created_at
FROM users
WHERE id = :user_id
"""
),
{
"user_id": user_id,
},
)
row = result.one_or_none()
if row is None:
return None
return User(
id=UUID(str(row.id)),
username=row.username,
display_name=row.display_name,
created_at=row.created_at,
)
async def create_chat(
session: AsyncSession,
data: CreateChat,
current_user_id: UUID,
) -> Chat:
if current_user_id not in data.member_ids:
raise APIError(
status_code=400,
code="invalid_request",
message="Current user must be a chat member",
)
users_result = await session.execute(
text(
"""
SELECT id
FROM users
WHERE id = ANY(:member_ids)
"""
),
{
"member_ids": data.member_ids,
},
)
existing_user_ids = {
UUID(str(row.id))
for row in users_result
}
if existing_user_ids != set(data.member_ids):
raise APIError(
status_code=400,
code="invalid_request",
message="Unknown chat member",
)
chat_id = uuid4()
chat_result = await session.execute(
text(
"""
INSERT INTO chats (
id,
title
)
VALUES (
:id,
:title
)
RETURNING
id,
title,
created_at
"""
),
{
"id": chat_id,
"title": data.title,
},
)
chat_row = chat_result.one()
for member_id in data.member_ids:
await session.execute(
text(
"""
INSERT INTO chat_members (
chat_id,
user_id
)
VALUES (
:chat_id,
:user_id
)
"""
),
{
"chat_id": chat_id,
"user_id": member_id,
},
)
return Chat(
id=UUID(str(chat_row.id)),
title=chat_row.title,
member_ids=data.member_ids,
created_at=chat_row.created_at,
)
async def get_chat_by_id(
session: AsyncSession,
chat_id: UUID,
current_user_id: UUID,
) -> Chat | None:
chat_result = await session.execute(
text(
"""
SELECT
c.id,
c.title,
c.created_at
FROM chats AS c
JOIN chat_members AS cm
ON cm.chat_id = c.id
WHERE c.id = :chat_id
AND cm.user_id = :current_user_id
"""
),
{
"chat_id": chat_id,
"current_user_id": current_user_id,
},
)
chat_row = chat_result.one_or_none()
if chat_row is None:
return None
members_result = await session.execute(
text(
"""
SELECT user_id
FROM chat_members
WHERE chat_id = :chat_id
ORDER BY user_id
"""
),
{
"chat_id": chat_id,
},
)
member_ids = [
UUID(str(row.user_id))
for row in members_result
]
return Chat(
id=UUID(str(chat_row.id)),
title=chat_row.title,
member_ids=member_ids,
created_at=chat_row.created_at,
)
async def list_chats(
session: AsyncSession,
current_user_id: UUID,
limit: int,
cursor: str | None = None,
) -> ChatPage:
cursor_created_at = None
cursor_chat_id = None
if cursor is not None:
try:
cursor_user_id, cursor_created_at, cursor_chat_id = decode_chat_cursor(cursor)
except ValueError as exc:
raise APIError(status_code=400, code="invalid_request", message="Invalid cursor") from exc
if cursor_user_id != current_user_id:
raise APIError(status_code=400, code="invalid_request", message="Invalid cursor")
result = await session.execute(
text(
"""
SELECT c.id, c.title, c.created_at
FROM chats AS c
JOIN chat_members AS cm ON cm.chat_id = c.id
WHERE cm.user_id = :current_user_id
AND (
CAST(:cursor_created_at AS timestamptz) IS NULL
OR (c.created_at, c.id) > (
CAST(:cursor_created_at AS timestamptz),
CAST(:cursor_chat_id AS uuid)
)
)
ORDER BY c.created_at, c.id
LIMIT :fetch_limit
"""
),
{
"current_user_id": current_user_id,
"cursor_created_at": cursor_created_at,
"cursor_chat_id": cursor_chat_id,
"fetch_limit": limit + 1,
},
)
rows = result.all()
has_more = len(rows) > limit
page_rows = rows[:limit]
items = []
for chat_row in page_rows:
members_result = await session.execute(
text(
"""
SELECT user_id
FROM chat_members
WHERE chat_id = :chat_id
ORDER BY user_id
"""
),
{"chat_id": chat_row.id},
)
items.append(
Chat(
id=UUID(str(chat_row.id)),
title=chat_row.title,
member_ids=[UUID(str(row.user_id)) for row in members_result],
created_at=chat_row.created_at,
)
)
next_cursor = None
if has_more:
last = page_rows[-1]
next_cursor = encode_chat_cursor(
current_user_id, last.created_at, UUID(str(last.id))
)
return ChatPage(items=items, next_cursor=next_cursor)
async def create_message(
session: AsyncSession,
chat_id: UUID,
current_user_id: UUID,
data: CreateMessage,
idempotency_key: str,
) -> Message:
membership_result = await session.execute(
text("""
SELECT 1
FROM chat_members
WHERE chat_id = :chat_id
AND user_id = :user_id
"""),
{
"chat_id": chat_id,
"user_id": current_user_id,
},
)
if membership_result.scalar_one_or_none() is None:
raise APIError(
status_code=404,
code="not_found",
message="Chat not found",
)
canonical_body = json.dumps(
{
"text": data.text,
"attachment_ids": [str(attachment_id) for attachment_id in data.attachment_ids],
},
sort_keys=True,
ensure_ascii=False,
separators=(",", ":"),
)
request_hash = hashlib.sha256(
canonical_body.encode("utf-8")
).hexdigest()
scope = (
f"{current_user_id}:POST:"
f"/api/v1/chats/{chat_id}/messages:"
f"{idempotency_key}"
)
await session.execute(
text("""
SELECT pg_advisory_xact_lock(
hashtextextended(:scope, 0)
)
"""),
{"scope": scope},
)
await session.execute(
text("""
DELETE FROM message_idempotency
WHERE user_id = :user_id
AND chat_id = :chat_id
AND key = :key
AND created_at <=
clock_timestamp() - INTERVAL '24 hours'
"""),
{
"user_id": current_user_id,
"chat_id": chat_id,
"key": idempotency_key,
},
)
existing_result = await session.execute(
text("""
SELECT
i.request_hash,
m.id,
m.chat_id,
m.sender_id,
m.text,
m.created_at
FROM message_idempotency AS i
JOIN messages AS m
ON m.id = i.message_id
WHERE i.user_id = :user_id
AND i.chat_id = :chat_id
AND i.key = :key
"""),
{
"user_id": current_user_id,
"chat_id": chat_id,
"key": idempotency_key,
},
)
existing = existing_result.one_or_none()
if existing is not None:
if existing.request_hash != request_hash:
raise APIError(
status_code=409,
code="conflict",
message=(
"Idempotency key already used "
"with different request body"
),
)
attachment_result = await session.execute(
text("""
SELECT attachment_id
FROM message_attachments
WHERE message_id = :message_id
ORDER BY attachment_id
"""),
{"message_id": existing.id},
)
attachment_ids = [
UUID(str(row.attachment_id))
for row in attachment_result.all()
]
return Message(
id=UUID(str(existing.id)),
chat_id=UUID(str(existing.chat_id)),
sender_id=UUID(str(existing.sender_id)),
text=existing.text,
created_at=existing.created_at,
attachment_ids=attachment_ids,
)
if data.attachment_ids:
attachments_result = await session.execute(
text("""
SELECT id
FROM attachments
WHERE id = ANY (:attachment_ids)
AND chat_id = :chat_id
AND status = 'ready'
"""),
{
"attachment_ids": data.attachment_ids,
"chat_id": chat_id,
},
)
valid_attachment_ids = {
UUID(str(row.id))
for row in attachments_result.all()
}
if valid_attachment_ids != set(data.attachment_ids):
raise APIError(
status_code=400,
code="invalid_request",
message="Invalid attachments for this chat",
)
message_id = uuid4()
message_result = await session.execute(
text("""
INSERT INTO messages (
id,
chat_id,
sender_id,
text
)
VALUES (
:id,
:chat_id,
:sender_id,
:text
)
RETURNING
id,
chat_id,
sender_id,
text,
created_at
"""),
{
"id": message_id,
"chat_id": chat_id,
"sender_id": current_user_id,
"text": data.text,
},
)
row = message_result.one()
for attachment_id in data.attachment_ids:
await session.execute(
text("""
INSERT INTO message_attachments (message_id,
attachment_id)
VALUES (:message_id,
:attachment_id)
"""),
{
"message_id": message_id,
"attachment_id": attachment_id,
},
)
await session.execute(
text("""
INSERT INTO message_idempotency (
user_id,
chat_id,
key,
request_hash,
message_id
)
VALUES (
:user_id,
:chat_id,
:key,
:request_hash,
:message_id
)
"""),
{
"user_id": current_user_id,
"chat_id": chat_id,
"key": idempotency_key,
"request_hash": request_hash,
"message_id": message_id,
},
)
return Message(
id=UUID(str(row.id)),
chat_id=UUID(str(row.chat_id)),
sender_id=UUID(str(row.sender_id)),
text=row.text,
created_at=row.created_at,
attachment_ids=data.attachment_ids,
)
async def get_messages(
session: AsyncSession,
chat_id: UUID,
current_user_id: UUID,
limit: int,
cursor: str | None,
) -> MessagePage:
membership_result = await session.execute(
text(
"""
SELECT 1
FROM chat_members
WHERE chat_id = :chat_id
AND user_id = :current_user_id
"""
),
{
"chat_id": chat_id,
"current_user_id": current_user_id,
},
)
if membership_result.scalar_one_or_none() is None:
raise APIError(
status_code=404,
code="not_found",
message="Chat not found",
)
cursor_created_at = None
cursor_message_id = None
if cursor is not None:
try:
(
cursor_chat_id,
cursor_created_at,
cursor_message_id,
) = decode_cursor(cursor)
except ValueError:
raise APIError(
status_code=400,
code="invalid_request",
message="Invalid cursor",
)
if cursor_chat_id != chat_id:
raise APIError(
status_code=400,
code="invalid_request",
message="Cursor belongs to another chat",
)
if cursor is None:
messages_result = await session.execute(
text(
"""
SELECT
id,
chat_id,
sender_id,
text,
created_at
FROM messages
WHERE chat_id = :chat_id
ORDER BY created_at, id
LIMIT :fetch_limit
"""
),
{
"chat_id": chat_id,
"fetch_limit": limit + 1,
},
)
else:
messages_result = await session.execute(
text(
"""
SELECT
id,
chat_id,
sender_id,
text,
created_at
FROM messages
WHERE chat_id = :chat_id
AND (created_at, id) > (
:cursor_created_at,
:cursor_message_id
)
ORDER BY created_at, id
LIMIT :fetch_limit
"""
),
{
"chat_id": chat_id,
"cursor_created_at": cursor_created_at,
"cursor_message_id": cursor_message_id,
"fetch_limit": limit + 1,
},
)
rows = messages_result.all()
has_more = len(rows) > limit
rows = rows[:limit]
attachments_by_message = {}
if rows:
attachment_result = await session.execute(
text("""
SELECT message_id, attachment_id
FROM message_attachments
WHERE message_id = ANY(:message_ids)
ORDER BY message_id, attachment_id
"""),
{
"message_ids": [row.id for row in rows],
},
)
for attachment_row in attachment_result.all():
message_id = UUID(str(attachment_row.message_id))
attachment_id = UUID(str(attachment_row.attachment_id))
attachments_by_message.setdefault(
message_id, []
).append(attachment_id)
items = [
Message(
id=UUID(str(row.id)),
chat_id=UUID(str(row.chat_id)),
sender_id=UUID(str(row.sender_id)),
text=row.text,
created_at=row.created_at,
attachment_ids=attachments_by_message.get(
UUID(str(row.id)), []
),
)
for row in rows
]
next_cursor = None
if has_more:
last_message = items[-1]
next_cursor = encode_cursor(
chat_id=chat_id,
created_at=last_message.created_at,
message_id=last_message.id,
)
return MessagePage(
items=items,
next_cursor=next_cursor,
)
def attachment_from_row(row) -> Attachment:
return Attachment(
id=UUID(str(row.id)),
chat_id=UUID(str(row.chat_id)),
owner_id=UUID(str(row.owner_id)),
filename=row.filename,
content_type=row.content_type,
size_bytes=row.size_bytes,
sha256=row.sha256,
status=row.status,
variants=row.variants,
error_code=row.error_code,
created_at=row.created_at,
updated_at=row.updated_at,
)
async def create_attachment(
session: AsyncSession,
attachment_id: UUID,
chat_id: UUID,
owner_id: UUID,
filename: str,
content_type: str,
size_bytes: int,
sha256: str,
s3_key: str,
) -> Attachment:
result = await session.execute(
text(
"""
INSERT INTO attachments (
id,
chat_id,
owner_id,
filename,
content_type,
size_bytes,
sha256,
s3_key,
status
)
VALUES (
:id,
:chat_id,
:owner_id,
:filename,
:content_type,
:size_bytes,
:sha256,
:s3_key,
'ready'
)
RETURNING
id,
chat_id,
owner_id,
filename,
content_type,
size_bytes,
sha256,
status,
variants,
error_code,
created_at,
updated_at
"""
),
{
"id": attachment_id,
"chat_id": chat_id,
"owner_id": owner_id,
"filename": filename,
"content_type": content_type,
"size_bytes": size_bytes,
"sha256": sha256,
"s3_key": s3_key,
},
)
return attachment_from_row(result.one())
async def get_attachment(
session: AsyncSession,
attachment_id: UUID,
current_user_id: UUID,
):
result = await session.execute(
text(
"""
SELECT
a.id,
a.chat_id,
a.owner_id,
a.filename,
a.content_type,
a.size_bytes,
a.sha256,
a.s3_key,
a.status,
a.variants,
a.error_code,
a.created_at,
a.updated_at
FROM attachments AS a
JOIN chat_members AS cm
ON cm.chat_id = a.chat_id
WHERE a.id = :attachment_id
AND cm.user_id = :current_user_id
AND a.status = 'ready'
"""
),
{
"attachment_id": attachment_id,
"current_user_id": current_user_id,
},
)
row = result.one_or_none()
if row is None:
return None
return attachment_from_row(row), row.s3_key
async def attachment_key_exists(session: AsyncSession, s3_key: str) -> bool:
result = await session.execute(
text("SELECT 1 FROM attachments WHERE s3_key = :s3_key"),
{"s3_key": s3_key},
)
return result.first() is not None
+16
View File
@@ -0,0 +1,16 @@
from argon2 import PasswordHasher
from argon2.exceptions import VerifyMismatchError
password_hasher = PasswordHasher()
def hash_password(password: str) -> str:
return password_hasher.hash(password)
def verify_password(password_hash: str, password: str) -> bool:
try:
return password_hasher.verify(password_hash, password)
except VerifyMismatchError:
return False
+87
View File
@@ -0,0 +1,87 @@
import os
import secrets
from uuid import UUID
from redis.asyncio import Redis
from redis.exceptions import RedisError
from src.errors import APIError
CACHE_URL_FILE = "/run/secrets/cache_url"
DEFAULT_SESSION_TTL_SECONDS = 3600
def read_cache_url() -> str:
with open(CACHE_URL_FILE, encoding="utf-8") as file:
return file.read().strip()
def get_session_ttl_seconds() -> int:
return int(
os.getenv(
"SESSION_TTL_SECONDS",
str(DEFAULT_SESSION_TTL_SECONDS),
)
)
redis_client = Redis.from_url(
read_cache_url(),
decode_responses=True,
socket_connect_timeout=5,
socket_timeout=5,
)
def session_store_unavailable() -> APIError:
return APIError(
status_code=503,
code="unavailable",
message="Session store unavailable",
)
async def create_session(user_id: UUID) -> tuple[str, int]:
token = secrets.token_urlsafe(32)
ttl = get_session_ttl_seconds()
try:
await redis_client.set(
f"session:{token}",
str(user_id),
ex=ttl,
)
except RedisError as exc:
raise session_store_unavailable() from exc
return token, ttl
async def get_session_user_id(token: str) -> UUID | None:
try:
value = await redis_client.get(f"session:{token}")
except RedisError as exc:
raise session_store_unavailable() from exc
if value is None:
return None
try:
return UUID(value)
except ValueError:
return None
async def delete_session(token: str) -> None:
try:
await redis_client.delete(f"session:{token}")
except RedisError as exc:
raise session_store_unavailable() from exc
async def ping_session_store() -> bool:
try:
return bool(await redis_client.ping())
except RedisError:
return False
+71
View File
@@ -0,0 +1,71 @@
import asyncio
import os
from pathlib import Path
import boto3
from botocore.config import Config
def read_secret(env_name: str) -> str:
path = os.environ[env_name]
return Path(path).read_text(encoding="utf-8").strip()
s3_client = boto3.client(
"s3",
endpoint_url=os.environ["S3_ENDPOINT"],
region_name=os.getenv("S3_REGION", "us-east-1"),
aws_access_key_id=read_secret("S3_ACCESS_KEY_ID_FILE"),
aws_secret_access_key=read_secret("S3_SECRET_ACCESS_KEY_FILE"),
config=Config(
signature_version="s3v4",
connect_timeout=2,
read_timeout=3,
retries={"total_max_attempts": 1, "mode": "standard"},
s3={"addressing_style": "path"},
),
)
S3_BUCKET = os.environ["S3_BUCKET"]
async def put_object(key: str, body: bytes, content_type: str) -> None:
await asyncio.to_thread(
s3_client.put_object,
Bucket=S3_BUCKET,
Key=key,
Body=body,
ContentType=content_type,
)
async def get_object(key: str) -> bytes:
def download() -> bytes:
response = s3_client.get_object(Bucket=S3_BUCKET, Key=key)
stream = response["Body"]
try:
return stream.read()
finally:
stream.close()
return await asyncio.to_thread(download)
async def delete_object(key: str) -> None:
await asyncio.to_thread(
s3_client.delete_object,
Bucket=S3_BUCKET,
Key=key,
)
async def ping_storage() -> bool:
try:
await asyncio.to_thread(
s3_client.head_bucket,
Bucket=S3_BUCKET,
)
return True
except Exception:
return False
+255
View File
@@ -0,0 +1,255 @@
import asyncio
import io
import json
import unittest
from contextlib import redirect_stdout
from datetime import datetime, timedelta, timezone
from unittest.mock import AsyncMock, patch
from scripts import reconcile as reconciler
class ReconcileTests(unittest.IsolatedAsyncioTestCase):
async def test_dry_run_detects_orphan_without_deleting(self):
key = "reconciliation-test/orphan.png"
old_time = datetime.now(timezone.utc) - timedelta(hours=48)
output = io.StringIO()
with (
patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db,
patch.object(reconciler, "list_s3_objects", return_value={key: old_time}),
patch.object(reconciler, "remove_object") as remove,
patch("scripts.reconcile.engine") as mock_engine,
redirect_stdout(output),
):
mock_engine.dispose = AsyncMock()
db.return_value = set()
result = await reconciler.reconcile(repair=False, grace_hours=24)
report = json.loads(output.getvalue())
self.assertEqual(result, 0)
self.assertEqual(report["mode"], "dry-run")
self.assertEqual(report["orphan_objects"], [key])
self.assertEqual(report["deleted_objects"], [])
remove.assert_not_called()
async def test_repair_preserves_recent_orphan(self):
key = "reconciliation-test/recent-orphan.png"
recent_time = datetime.now(timezone.utc)
output = io.StringIO()
with (
patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db,
patch.object(reconciler, "list_s3_objects", return_value={key: recent_time}),
patch.object(reconciler, "remove_object") as remove,
patch("scripts.reconcile.engine") as mock_engine,
redirect_stdout(output),
):
mock_engine.dispose = AsyncMock()
db.return_value = set()
result = await reconciler.reconcile(repair=True, grace_hours=24)
report = json.loads(output.getvalue())
self.assertEqual(result, 0)
self.assertEqual(report["orphan_objects"], [key])
self.assertEqual(report["deleted_objects"], [])
self.assertEqual(
report["skipped_objects"],
[{"key": key, "reason": "grace_period"}],
)
remove.assert_not_called()
async def test_repair_preserves_registered_attachment(self):
key = "attachments/test/protected.png"
old_time = datetime.now(timezone.utc) - timedelta(hours=48)
output = io.StringIO()
with (
patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db,
patch.object(reconciler, "list_s3_objects", return_value={key: old_time}),
patch.object(reconciler, "remove_object") as remove,
patch("scripts.reconcile.engine") as mock_engine,
redirect_stdout(output),
):
mock_engine.dispose = AsyncMock()
db.return_value = {key}
result = await reconciler.reconcile(repair=True, grace_hours=24)
report = json.loads(output.getvalue())
self.assertEqual(result, 0)
self.assertEqual(report["database_objects"], 1)
self.assertEqual(report["storage_objects"], 1)
self.assertEqual(report["orphan_objects"], [])
self.assertEqual(report["missing_objects"], [])
self.assertEqual(report["deleted_objects"], [])
remove.assert_not_called()
async def test_repair_preserves_newly_registered_attachment(self):
key = "attachments/test/concurrent.png"
old_time = datetime.now(timezone.utc) - timedelta(hours=48)
output = io.StringIO()
with (
patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db,
patch.object(reconciler, "list_s3_objects", return_value={key: old_time}),
patch.object(reconciler, "db_key_exists", new_callable=AsyncMock) as exists,
patch.object(reconciler, "remove_object") as remove,
patch("scripts.reconcile.engine") as mock_engine,
redirect_stdout(output),
):
mock_engine.dispose = AsyncMock()
db.return_value = set()
exists.return_value = True
result = await reconciler.reconcile(repair=True, grace_hours=24)
report = json.loads(output.getvalue())
self.assertEqual(result, 0)
self.assertEqual(report["orphan_objects"], [key])
self.assertEqual(report["deleted_objects"], [])
self.assertEqual(
report["skipped_objects"],
[{"key": key, "reason": "database_record_exists"}],
)
exists.assert_awaited_once_with(key)
remove.assert_not_called()
async def test_repair_preserves_updated_object(self):
key = "reconciliation-test/updated-object.png"
old_time = datetime.now(timezone.utc) - timedelta(hours=48)
recent_time = datetime.now(timezone.utc)
output = io.StringIO()
with (
patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db,
patch.object(reconciler, "list_s3_objects", return_value={key: old_time}),
patch.object(reconciler, "db_key_exists", new_callable=AsyncMock) as exists,
patch.object(reconciler, "inspect_object", return_value={"LastModified": recent_time}) as inspect,
patch.object(reconciler, "remove_object") as remove,
patch("scripts.reconcile.engine") as mock_engine,
redirect_stdout(output),
):
mock_engine.dispose = AsyncMock()
db.return_value = set()
exists.return_value = False
result = await reconciler.reconcile(repair=True, grace_hours=24)
report = json.loads(output.getvalue())
self.assertEqual(result, 0)
self.assertEqual(report["orphan_objects"], [key])
self.assertEqual(report["deleted_objects"], [])
self.assertEqual(
report["skipped_objects"],
[{"key": key, "reason": "object_too_recent"}],
)
exists.assert_awaited_once_with(key)
inspect.assert_called_once_with(key)
remove.assert_not_called()
async def test_repair_deletes_old_orphan(self):
key = "reconciliation-test/old-orphan.png"
old_time = datetime.now(timezone.utc) - timedelta(hours=48)
output = io.StringIO()
with (
patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db,
patch.object(reconciler, "list_s3_objects", return_value={key: old_time}),
patch.object(reconciler, "db_key_exists", new_callable=AsyncMock) as exists,
patch.object(reconciler, "inspect_object", return_value={"LastModified": old_time}) as inspect,
patch.object(reconciler, "remove_object") as remove,
patch("scripts.reconcile.engine") as mock_engine,
redirect_stdout(output),
):
mock_engine.dispose = AsyncMock()
db.return_value = set()
exists.return_value = False
result = await reconciler.reconcile(repair=True, grace_hours=24)
report = json.loads(output.getvalue())
self.assertEqual(result, 0)
self.assertEqual(report["orphan_objects"], [key])
self.assertEqual(report["deleted_objects"], [key])
self.assertEqual(report["skipped_objects"], [])
self.assertEqual(exists.await_count, 2)
inspect.assert_called_once_with(key)
remove.assert_called_once_with(key)
async def test_repair_preserves_missing_object_metadata(self):
key = "reconciliation-test/missing-object.png"
output = io.StringIO()
with (
patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db,
patch.object(reconciler, "list_s3_objects", return_value={}),
patch.object(reconciler, "remove_object") as remove,
patch("scripts.reconcile.engine") as mock_engine,
redirect_stdout(output),
):
mock_engine.dispose = AsyncMock()
db.return_value = {key}
result = await reconciler.reconcile(repair=True, grace_hours=24)
report = json.loads(output.getvalue())
self.assertEqual(result, 0)
self.assertEqual(report["database_objects"], 1)
self.assertEqual(report["storage_objects"], 0)
self.assertEqual(report["orphan_objects"], [])
self.assertEqual(report["missing_objects"], [key])
self.assertEqual(report["deleted_objects"], [])
remove.assert_not_called()
async def test_repair_is_idempotent(self):
key = "reconciliation-test/idempotent-orphan.png"
old_time = datetime.now(timezone.utc) - timedelta(hours=48)
objects = {key: old_time}
deleted = []
reports = []
def fake_list_s3_objects():
return dict(objects)
def fake_inspect_object(candidate):
return {"LastModified": objects[candidate]}
def fake_remove_object(candidate):
deleted.append(candidate)
del objects[candidate]
with (
patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db,
patch.object(reconciler, "list_s3_objects", side_effect=fake_list_s3_objects),
patch.object(reconciler, "db_key_exists", new_callable=AsyncMock) as exists,
patch.object(reconciler, "inspect_object", side_effect=fake_inspect_object),
patch.object(reconciler, "remove_object", side_effect=fake_remove_object),
patch("scripts.reconcile.engine") as mock_engine,
):
mock_engine.dispose = AsyncMock()
db.return_value = set()
exists.return_value = False
for _ in range(2):
output = io.StringIO()
with redirect_stdout(output):
result = await reconciler.reconcile(
repair=True,
grace_hours=24,
)
self.assertEqual(result, 0)
reports.append(json.loads(output.getvalue()))
self.assertEqual(reports[0]["deleted_objects"], [key])
self.assertEqual(reports[1]["orphan_objects"], [])
self.assertEqual(reports[1]["deleted_objects"], [])
self.assertEqual(deleted, [key])
self.assertEqual(objects, {})
if __name__ == "__main__":
unittest.main()
+144
View File
@@ -0,0 +1,144 @@
import asyncio
import unittest
from unittest.mock import AsyncMock, MagicMock, patch
from uuid import uuid4
from src.main import upload_attachment_endpoint
class UploadCompensationTests(unittest.IsolatedAsyncioTestCase):
async def run_failure_scenario(
self,
failure_stage,
verification_result=False,
verification_error=None,
):
chat_id = uuid4()
user_id = uuid4()
uploaded_keys = []
deleted_keys = []
request = MagicMock()
request.headers = {"content-type": "image/png"}
async def stream():
yield b"test-image"
request.stream = stream
user = MagicMock()
user.id = user_id
session = MagicMock()
session.commit = AsyncMock()
session.rollback = AsyncMock()
async def fake_put_object(key, body, content_type):
uploaded_keys.append(key)
async def fake_delete_object(key):
deleted_keys.append(key)
with (
patch("src.main.get_chat_by_id", new_callable=AsyncMock) as get_chat,
patch("src.main.validate_image", return_value=(10, "test-sha256")),
patch("src.main.put_object", side_effect=fake_put_object),
patch("src.main.create_attachment", new_callable=AsyncMock) as create,
patch("src.main.delete_object", side_effect=fake_delete_object),
patch("src.main.SessionFactory") as session_factory,
patch("src.main.attachment_key_exists", new_callable=AsyncMock) as exists,
):
get_chat.return_value = MagicMock()
verification_session = AsyncMock()
session_factory.return_value.__aenter__.return_value = verification_session
if verification_error is not None:
exists.side_effect = verification_error
else:
exists.return_value = verification_result
if failure_stage == "insert":
create.side_effect = RuntimeError("Simulated INSERT failure")
expected_error = RuntimeError
elif failure_stage == "commit":
create.return_value = MagicMock()
session.commit.side_effect = RuntimeError("Simulated COMMIT failure")
expected_error = RuntimeError
elif failure_stage == "cancel":
create.side_effect = asyncio.CancelledError()
expected_error = asyncio.CancelledError
else:
raise ValueError("Unknown failure stage")
with self.assertRaises(expected_error):
await upload_attachment_endpoint(
chat_id=chat_id,
request=request,
filename="test.png",
current_user=user,
session=session,
)
self.assertEqual(len(uploaded_keys), 1)
self.assertTrue(
uploaded_keys[0].startswith(f"attachments/{chat_id}/")
)
session.rollback.assert_awaited_once()
exists.assert_awaited_once_with(
verification_session,
uploaded_keys[0],
)
if failure_stage == "commit":
session.commit.assert_awaited_once()
else:
session.commit.assert_not_awaited()
return uploaded_keys, deleted_keys
async def test_insert_failure_deletes_unregistered_object(self):
uploaded, deleted = await self.run_failure_scenario(
failure_stage="insert",
verification_result=False,
)
self.assertEqual(deleted, uploaded)
async def test_commit_failure_deletes_unregistered_object(self):
uploaded, deleted = await self.run_failure_scenario(
failure_stage="commit",
verification_result=False,
)
self.assertEqual(deleted, uploaded)
async def test_cancellation_deletes_unregistered_object(self):
uploaded, deleted = await self.run_failure_scenario(
failure_stage="cancel",
verification_result=False,
)
self.assertEqual(deleted, uploaded)
async def test_commit_failure_preserves_registered_object(self):
uploaded, deleted = await self.run_failure_scenario(
failure_stage="commit",
verification_result=True,
)
self.assertEqual(len(uploaded), 1)
self.assertEqual(deleted, [])
async def test_database_unavailable_preserves_object(self):
uploaded, deleted = await self.run_failure_scenario(
failure_stage="commit",
verification_error=ConnectionError("Database unavailable"),
)
self.assertEqual(len(uploaded), 1)
self.assertEqual(deleted, [])
if __name__ == "__main__":
unittest.main()