ЛР6 - БВТ2301 - Дыханова - на 3 #57

Closed
dykhanovaa wants to merge 1 commits from dykhanovaa/mtusi2026lab6:solution/bvt2301-dykhanova into main
29 changed files with 1663 additions and 54 deletions
+2 -16
View File
@@ -1,20 +1,6 @@
.git
.github
.env
.env.*
!.env.example
secrets
certs
volumes
data
backups
*.key
*.pem
*.p12
*.pfx
*.jks
.venv
.env
secrets
__pycache__
node_modules
evidence
.DS_Store
+7 -14
View File
@@ -1,18 +1,11 @@
## Лабораторная 6
Автор / группа: TODO
Целевая оценка (3/4/5): TODO
Трек 5, если заявлен: TODO
Автор — Дыханова Алина, БВТ2301. Целевая оценка — 3.
Что реализовано и что перенесено: TODO
Команды запуска из чистого clone: TODO
Результаты проверок и ссылка на REPORT.md: TODO
Ограничения / известные ошибки: TODO
Источники и использование ИИ: TODO
Стенд включает API и worker на Python, PostgreSQL, SeaweedFS, RabbitMQ,
HAProxy с двумя API-репликами, OpenTelemetry Collector, Prometheus, Loki, Tempo и Grafana.
Команды запуска и результаты описаны в [REPORT.md](../REPORT.md).
- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [ ] Контракт и публичные тесты не ослаблены.
- [ ] make check и make test выполнены; приложен реальный вывод.
- [ ] Сценарии отказов/безопасности своего уровня воспроизведены.
- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
- [x] Проверены структура проекта и конфигурация Compose.
- [x] Зафиксированы результаты smoke, сохранности данных, отказа API-реплики и поступления телеметрии.
- [x] Подтверждён опыт с остановкой worker и собраны наблюдения Grafana для двух отказов.
+8
View File
@@ -0,0 +1,8 @@
FROM python:3.12.10-slim
ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
WORKDIR /srv
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt && useradd --uid 10001 --create-home messenger
COPY app app
USER messenger
CMD ["uvicorn", "app.api:app", "--host", "0.0.0.0", "--port", "8080", "--no-access-log"]
+4 -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-failover-repeatable
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@@ -28,3 +28,6 @@ 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-failover-repeatable:
PYTHON="$(PYTHON)" BASE_URL="$(BASE_URL)" sh scripts/test-failover.sh
+311 -23
View File
@@ -1,37 +1,325 @@
# Отчёт — лабораторная 6
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
Автор — Дыханова Алина, БВТ2301. Целевая оценка — **3**.
Реализация: Python 3.12.10, FastAPI 0.115.12, OpenTelemetry SDK/exporter 1.33.1.
Зависимости закреплены в requirements.txt; версии инфраструктуры — в compose.yaml.
## Запуск из чистого clone
## Запуск
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Требуются Docker Compose v2, запущенный Docker, Python 3.9+ и make.
В каталоге репозитория:
## Архитектура и решения
```sh
sh scripts/bootstrap.sh
# .env создаётся один раз со случайными локальными паролями, в Git не входит.
docker compose config --quiet
docker compose up -d --build
# Дождитесь HTTP 200 от этой команды перед запуском тестов.
curl -fsS http://localhost:8080/health/ready
make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover-repeatable
python3 tests/load.py --duration 30 --concurrency 4 --output evidence/load.json
```
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab5, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Команда `test-failover-repeatable` сначала запускает обе реплики, ждёт их ответов
через балансировщик и затем выполняет неизменённый публичный failover-тест.
После завершения (в том числе при ошибке) обе реплики запускаются снова.
Обычный `test-failover` намеренно оставляет выбранную реплику остановленной.
## Доказательства критериев
Миграции выполняются API/worker автоматически под PostgreSQL advisory lock.
Одноразовый s3-init создаёт приватный bucket, не удаляя существующие объекты.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
API: http://localhost:8080; Grafana: http://localhost:3000 (admin; пароль GRAFANA_PASSWORD
из локального .env). Dashboard **Messenger observability** provisioning импортирует автоматически.
Prometheus: http://localhost:9090; Loki: localhost:3100; Tempo: localhost:3200.
Порты привязаны к loopback, внутренние API/БД/broker/S3 наружу не опубликованы.
Не публиковать `docker compose config` без `--quiet`: вывод содержит пароли.
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Безопасная остановка: `docker compose down` (volumes остаются).
Намеренное удаление всех учебных данных: `docker compose down -v`.
После прямого запуска `make test-failover` восстановить обе реплики командой
`docker compose start api1 api2`.
## Эксперименты и отказы
## Архитектура
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
HAProxy проверяет `/health/ready`, распределяет запросы между готовыми репликами
`api1` и `api2` по round robin и обновляет их адреса через DNS Docker.
PostgreSQL хранит пользователей, сессии (SHA-256 случайного токена), чаты, сообщения,
метаданные, idempotency и transactional outbox. Пароли — scrypt с индивидуальной солью.
API не хранит пользовательские данные на локальном диске. Сессии общие для реплик.
Idempotency сериализован advisory lock; сообщение и его ответ фиксируются одной транзакцией.
Keyset pagination по `(created_at,id)` не обеспечивает snapshot при конкурентных вставках.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
S3 реализован через chrislusf/seaweedfs:3.85: master, volume, filer и S3 gateway
работают в одном процессе. Filer LevelDB и объекты сохраняются в volume seaweed.
scripts/bootstrap.sh создаёт конфигурацию ключей в secrets/seaweed-s3.json вне Git;
анонимная identity не настроена. s3-init использует boto3 из образа приложения.
## Ограничения и следующие шаги
При upload сначала проверяется PNG/JPEG и сохраняется полный оригинал в SeaweedFS staging,
затем в одной транзакции PostgreSQL сохраняются queued-метаданные и outbox. Только после COMMIT
возвращается 202. Relay в отдельном потоке worker публикует persistent RabbitMQ message
в durable queue с publisher confirm; затем отмечает outbox sent. Разрыв после publish до
COMMIT даёт повторную доставку. Worker держит row lock, публикует оригинал и JPEG thumbnail
по детерминированным ключам и атомарно сохраняет ready. Ack — после COMMIT.
Повтор уже готовой job не меняет результат. Смерть worker откатывает транзакцию,
RabbitMQ повторно доставляет unacked job. Ручной replay уровня 4 не заявлен.
Thumbnail: EXIF transpose, вписывание в 256×256 без увеличения, alpha на белом, JPEG quality 85.
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Readiness требует DB и S3: без них синхронный путь небезопасен. Broker/worker могут временно
не работать: PostgreSQL outbox сохраняет намерение. Telemetry не участвует в readiness.
Образы, конфиги и persistent volumes всех трёх сигналов находятся в Compose.
API и worker отправляют метрики, логи и трассы в Collector по OTLP/HTTP.
Prometheus считывает метрики с Collector каждые 5 с. Collector отправляет логи
в Loki по OTLP/HTTP, а трассы в Tempo по OTLP/gRPC.
Grafana запрашивает эти три источника и хранит собственные настройки, а не сами сигналы.
Collector применяет memory_limiter и batch. Для экспортёров Loki и Tempo
заданы очереди по 512 и 30-секундный предел повторных попыток. SDK использует
очереди по 2048 для логов и трасс и тайм-аут 3 с для каждого OTLP-экспортёра. При длительном сбое возможны
потери telemetry; это не заявляется как экспериментально проверенная отказоустойчивость.
Prometheus/Tempo хранят историю 7 дней; у Loki в учебном стенде автоматическое удаление не настроено.
## Сигналы и поиск
| SDK → Prometheus | Тип / единица | Измерения |
| --- | --- | --- |
| http_requests → http_requests_total | counter, запросы | method, route, status_class |
| http_duration → http_duration_seconds_bucket/sum/count | histogram, секунды | те же |
| worker_jobs → worker_jobs_total | counter, попытки jobs | job_type, outcome |
| worker_job_duration → worker_job_duration_seconds_bucket/sum/count | histogram, секунды | те же |
Counter не имеет unit suffix; histogram SDK unit=s переводится в seconds.
У failed/retry попыток outcome=error; успешная попытка и безопасный duplicate no-op — success.
Worker histogram включает задержку перед retry. Dashboard считает API p95 по histogram всех реплик,
RPS и 5xx/s, worker success/error и p95. Пустая серия error до первой ошибки нормальна.
API ошибки здесь — 5xx; 4xx не считаются серверным отказом. Health исключён из API графиков.
Resource: service.name, service.version=1.0.0, service.instance.id, deployment.environment.name=lab.
Идентификаторы пользователей/чата/сообщений, URL и filename отсутствуют в labels метрик.
Логи идут в OTLP с timestamp, severity, resource, event, trace_id/span_id активного span.
Только выделенный application logger экспортируется; тела, auth headers, пароли, исключения
с внутренними значениями и изображения не записываются. Технические request_id/job_id допустимы
для корреляции синтетического опыта, но не являются labels метрик.
Фактическое поступление метрик, логов и трасс подтверждено скриншотами Grafana.
API log связан с health trace, worker log — с полной трассой загрузки;
идентификаторы и наблюдаемые значения приведены в разделе разбора скриншотов.
W3C traceparent передаётся в разрешённых полях job. Spans: server HTTP, consumer
attachment.process, S3 stage/read/publish и db.ready. Отдельный producer span уровня 4 не заявлен.
Для ручного поиска: в Grafana Explore выбрать Tempo, запросить trace ID из X-Trace-Id
контролируемого upload; в Loki использовать:
```logql
{service_name=~"messenger-api|messenger-worker"} | trace_id="TRACE_ID"
```
Request ID из X-Request-Id находится в structured metadata API log. Для worker event=job.completed.
Пример PromQL: `sum by (outcome) (rate(worker_jobs_total[1m]))`.
## Фактические результаты
| Проверка | Результат | Доказательство |
| --- | --- | --- |
| make check | PASS, структура/ссылки/синтаксис | локальная проверка |
| docker compose config --quiet | PASS | локальная проверка |
| docker compose ps -a | Обе API healthy, DB/broker healthy, worker и все telemetry-сервисы Up; s3-init Exited (0) | evidence/operator-results.md |
| make test | PASS: lab6 public API scenario | evidence/operator-results.md |
| make test-persistence ACTION_SCRIPT=scripts/restart.sh | PASS: данные и существующая сессия сохранены | evidence/operator-results.md |
| make test-failover ACTION_SCRIPT=scripts/stop-one.sh | PASS: 2 реплики, 54 успешные записи, 4 неудачные попытки; восстановление записи 2.696 с | evidence/operator-results.md |
| Нагрузка: 30 с, 4 клиента | 12773 успешных запроса, 0 ошибок, 424.445 RPS | evidence/load.json |
| Метрики, связанные логи и реальные traces | Подтверждены dashboard, логами API/worker и трассами Tempo | раздел «Что показала Grafana» |
| make test-failover-repeatable (20.11.2026) | PASS: 2 реплики до отказа, 54 успешные записи, 4 неудачные попытки, первая успешная запись через 2,355 с от запуска hook | evidence/operator-results.md |
| Отказ worker | PASS: при остановленном worker вложение осталось queued, после запуска перешло в ready, оригинал совпал побайтно | раздел «Наблюдения при остановке worker» |
| Диагностика отказов по телеметрии | Для worker подтверждена связь запроса API и обработки по одному trace ID в Loki и Tempo. В Loki за интервал failover подтверждена успешная запись через api2 | сценарии в разделе «Повторяемые инциденты после запуска» |
Persistence hook перезапускает api1/api2, worker, PostgreSQL, S3, broker,
Collector, Prometheus, Loki, Tempo, Grafana и LB без удаления volumes.
Вывод теста подтверждает сохранность данных и сессии. Для отдельного
подтверждения перезапуска PostgreSQL нужны значения `StartedAt` до и после теста.
### Результаты нагрузки
Длительность по часам клиента — 30.093 с. p50 = 8.683 мс, p95 = 12.634 мс,
p99 = 23.901 мс, error ratio = 0. Это closed-loop тест POST сообщений без retry,
percentile относится только к успешным запросам. Один запуск не определяет
максимальную производительность; CPU/RAM и повторные измерения не собирались.
## Что показала Grafana
В наблюдениях ниже указано время, которое отображалось в Grafana. Данные относятся к сервисам `messenger-api` и `messenger-worker`.
### Dashboard Messenger observability
На первом снимке видны RPS, API p95, worker success и часть нижних панелей.
Второй снимок дополняет его целиком видимым worker p95 и панелью логов.
Легенда RPS содержит api1/api2, кривые близки и местами перекрываются. Видны
всплески нагрузки и успешной фоновой обработки. Worker серия имеет outcome=success;
ошибочная попытка worker отдельным экспериментом не продемонстрирована.
API 5xx/s показывает `No data`. Это отсутствие результата запроса за выбранное
окно, а не доказательство точного нулевого числа всех ошибок. В частности, ошибки
соединения/ответы HAProxy во время остановки API не обязаны попадать в счётчик API.
Число неудачных клиентских попыток измерено отдельно в failover-тесте.
API p95 и worker p95 на dashboard находятся примерно около 4.75 с, тогда как
индивидуальные логи показывают десятки миллисекунд. Эти числа нельзя считать
точным измерением p95: в текущем SDK используются стандартные границы histogram,
слишком грубые для таких задержек. Интерполяция внутри широкого bucket может дать
около 4.75 с даже для быстрых запросов. Следует подобрать границы histogram под
миллисекундные операции и повторить измерение; на этих снимках подтверждены
поступление histogram и построение графика, но не точность percentile.
Клиентские p95/p99 нагрузки приведены отдельно в evidence/load.json.
### Структурный лог API
| Поле | Наблюдаемое значение |
| --- | --- |
| event | http.request |
| service_name / instance | messenger-api / api2 |
| method / route | GET /health/ready |
| status_code / status_class | 200 / 2xx |
| severity_text | INFO |
| duration_seconds | 0.023972624999942127, около 23.97 мс |
| request_id | 4356468e1d0445369fc7a545391650f8 |
| trace_id | 0bfcaa8384a34151aee4ae0d4387441d |
| span_id | efba4f6db4f921fa |
| service_version / SDK | 1.0.0 / OpenTelemetry Python 1.33.1 |
Видны технические атрибуты, а также переход Tempo с тем же trace ID.
В показанной записи нет Authorization, пароля, session token или тела сообщения.
Это наблюдение по данной записи, а не исчерпывающая проверка всей истории логов.
### Трасса API, найденная по логу
Tempo показывает trace `0bfcaa8384a34151aee4ae0d4387441d`, один span
`messenger-api GET /health/ready`, ответ 200, длительность 24.3 мс;
отображённое начало — 16.11.2026 23:41:24.138. Идентификатор совпадает с приведённым выше логом API. Поэтому подтверждён поиск реальной трассы по структурному логу API.
Различие 23.97 мс в логе и 24.3 мс в span допустимо: длительность span включает
небольшую дополнительную работу внутри instrumentation после измерения handler.
Health не порождает job, поэтому отсутствие worker здесь ожидаемо.
### Поиск логов фоновой обработки
Запрос `{service_name="messenger-worker"} |= "job.completed"` за выбранный час
вернул шесть записей уровня INFO. На снимке видны события в 23:21:36.777,
23:31:51.507, 23:32:25.454, 23:32:44.937, 23:32:51.303 и 23:36:07.536.
Это подтверждает поступление логов отдельного worker в Loki, а не только логов API.
### Структурный лог успешной job
| Поле | Наблюдаемое значение |
| --- | --- |
| event / service_name | job.completed / messenger-worker |
| job_type | attachment.process.v1 |
| job_id | a2423f62-c19f-440a-9bde-f3d430562449 |
| attempt / outcome | 1 / success |
| duration_seconds | 0.028629083000168976, около 28.63 мс |
| severity_text | INFO |
| trace_id | 0dc6e36ad05603919332b5957929c909 |
| span_id | cd3240b3016bc139 |
Job ID используется для корреляции лога, не как label метрики. Переход Tempo
содержит тот же trace ID. Подтверждены структурные поля, исход обработки и связь
job с трассой.
### Сквозная трасса upload → worker → S3/DB
В Tempo открыт trace `0dc6e36ad05603919332b5957929c909`, совпадающий с идентификатором в логе worker.
Начало — 16.11.2026 23:36:07.305, API вернул 202. В трассе семь spans:
| Сервис / операция | Длительность на снимке |
| --- | --- |
| messenger-api POST /api/v1/chats/{chat_id}/attachments | 10.96 мс |
| s3.stage | 4.78 мс |
| messenger-worker attachment.process | 28.55 мс |
| s3.read_staging | 9.93 мс |
| image.thumbnail | 2.61 мс |
| s3.publish | 7.25 мс |
| db.ready | 255.96 мкс |
Общая временная протяжённость trace — 231.67 мс. Это не длительность HTTP-ответа:
в неё входит интервал между API и запуском фоновой обработки. Его нельзя напрямую
объявлять метрикой глубины/возраста очереди. Вложенность worker под API показывает
перенос trace context; длительности consumer log и span близки. Видны этапы
чтения исходника, thumbnail, записи результата и публикации ready в БД.
Повторная попытка (retry) в этом опыте отсутствует; уровень 4 целиком не заявляется.
## Повторяемые инциденты после запуска
1. Запустить `python3 scripts/test-worker-outage.py`. Скрипт останавливает worker,
загружает PNG, проверяет статус queued и печатает trace ID. Затем он запускает worker,
дожидается ready и сверяет загруженный оригинал байт в байт. В Tempo найдите HTTP span
загрузки и последующий `attachment.process` по напечатанному trace ID. В Loki
найдите `http.request` и `job.completed` по тому же идентификатору. Интервал между
HTTP span и worker span показывает ожидание обработки в этом опыте.
2. Запустить `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`. Hook останавливает именно
реплику TARGET_INSTANCE_ID; тест проверяет запись через другую реплику и отсутствие дублей.
По метрикам отдельных service_instance_id и логам определить исчезнувшую реплику.
Восстановить `docker compose start api1 api2`. Сохранить результат и запросы наблюдений.
### Наблюдения при остановке worker
Проверка прошла 20 ноября 2026 года с 17:31:25 до 17:31:37 МСК. API принял
вложение в статусе `queued` при остановленном worker. После запуска worker
скрипт дождался `ready` и подтвердил побайтовое совпадение скачанного файла с оригиналом.
В Loki запрос по `trace_id=dc807159c626aaf72c9ae58641117383` вернул две записи:
| Время UTC | Сервис | Событие |
| --- | --- | --- |
| 14:31:33.540 | messenger-api | `http.request` |
| 14:31:34.694 | messenger-worker | `job.completed` |
Между записями прошло 1,154 с. Интервал измерен от записи события HTTP
до записи завершения задания и включает ожидание и обработку.
В Tempo та же трасса содержит семь spans. API принял загрузку с HTTP 202
за 16,07 мс, включая запись исходника в S3 staging за 5,61 мс. После
запуска worker операция `attachment.process` заняла 79,61 мс. Внутри неё
видны чтение исходника из staging (65,4 мс), создание миниатюры (4,26 мс),
публикация в S3 (5,18 мс) и запись статуса `ready` в БД (240,54 мкс).
Вся трасса заняла около 1,17 с, включая интервал между ответом API и
началом фоновой обработки.
### Наблюдения при отказе API-реплики
Повторная проверка прошла 20 ноября 2026 года с 17:41:06 до 17:41:32 МСК.
До остановки `api1` балансировщик обслуживал запросы через обе реплики.
После остановки запись продолжилась через `api2`. За прогон получено 54 успешных
записи и 4 неудачные клиентские попытки. Первая успешная запись после завершения
hook зафиксирована через 2,355 с от его запуска. Тест подтвердил сохранность
подтверждённых сообщений и существующей сессии. После завершения сценарий
запустил `api1`. При проверке состояния `api2` была healthy, а `api1` ещё
проходила проверку готовности (health: starting).
В Loki запрос ниже показал, что в 17:41:28.589 МСК реплика `api2`
успешно обработала создание сообщения с ответом HTTP 201 за 10,35 мс.
Идентификатор трассы — `82a1d11fa18230512035ebcd76cb3a35`.
```logql
{service_name="messenger-api"} |= "http.request" | method="POST" | route="/api/v1/chats/{chat_id}/messages" | status_code="201"
```
## Ограничения
Один экземпляр DB/S3/broker/LB и один Docker host: их HA не обеспечено. Обработка изображения
держит DB транзакцию; statement_timeout 10s, job deadline отдельно не реализован. Staging пока
сохраняется для повторов без автоматического cleanup; STAGING_RETENTION_SECONDS из skeleton
не реализован. Старые outbox/idempotency/session rows автоматически не чистятся; expiry проверяется
при использовании. Диск следует освобождать осознанным сбросом учебного стенда.
Не заявлены queue lag/pool metrics, SLO, alert rules, sampling research и прочие требования 4/5.
Внешние credentials передаются контейнерам через локальный .env; интерфейс *_FILE поддерживается
приложением, но Compose использует прямые переменные. Прочие переменные .env.example — варианты
контракта skeleton, а не обещание реализации: APP_PORT фиксирован 8080, реплик ровно две,
worker имеет один consumer, SESSION_STORE=PostgreSQL. Никакой Redis для этой оценки не требуется.
## Первичные материалы
- https://opentelemetry.io/docs/collector/configuration/
- https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.128.0/exporter/prometheusexporter
- https://grafana.com/docs/loki/latest/send-data/otel/
- https://grafana.com/docs/grafana/latest/administration/provisioning/
- https://www.rabbitmq.com/docs/reliability
View File
+339
View File
@@ -0,0 +1,339 @@
import base64
import binascii
import hashlib
import hmac
import json
import re
import secrets
import time
import uuid
from contextlib import asynccontextmanager
from datetime import datetime, timedelta, timezone
from urllib.parse import parse_qs
import psycopg
from psycopg.types.json import Jsonb
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse, Response
from starlette.concurrency import run_in_threadpool
from opentelemetry import propagate, trace
from opentelemetry.trace import SpanKind, Status, StatusCode
from app.common import (db, migrate, get, put, now, config, s3, bucket, sha,
inspect_image, InvalidImage, ImageTooLarge)
from app.telemetry import setup, INSTANCE
tracer, meter, logger, providers = setup('messenger-api')
requests_count = meter.create_counter('http_requests', unit='{request}')
http_duration = meter.create_histogram('http_duration', unit='s')
class APIError(Exception):
def __init__(self, status, code):
self.status, self.code = status, code
def require(condition, status=400, code='invalid_request'):
if not condition:
raise APIError(status, code)
def uid(value):
try:
return str(uuid.UUID(value))
except (ValueError, TypeError, AttributeError):
raise APIError(400, 'invalid_request') from None
def text(value, maximum, minimum=1):
require(isinstance(value, str) and minimum <= len(value) <= maximum)
require(bool(value.strip()) or minimum == 0)
return value
def fields(body, required, optional=()):
require(isinstance(body, dict) and set(required) <= body.keys() and not body.keys()-set(required)-set(optional))
def ids(value, maximum, minimum=0):
require(isinstance(value, list) and minimum <= len(value) <= maximum)
result = [uid(x) for x in value]
require(len(result) == len(set(result)))
return result
def public_user(conn, user_id):
return get(conn, 'user', user_id)
def authenticate(conn, headers):
auth = headers.get('authorization', '')
require(auth.startswith('Bearer ') and bool(auth[7:]), 401, 'unauthorized')
row = conn.execute('SELECT user_id FROM sessions WHERE token_hash=%s AND expires_at>now()', (sha(auth[7:].encode()),)).fetchone()
require(row is not None, 401, 'unauthorized')
return row['user_id']
def chat_access(conn, chat_id, actor):
chat = get(conn, 'chat', uid(chat_id))
require(chat is not None and actor in chat['member_ids'], 404, 'not_found')
return chat
def attachment_access(conn, attachment_id, actor):
att = get(conn, 'attachment', uid(attachment_id))
require(att is not None, 404, 'not_found')
chat_access(conn, att['chat_id'], actor)
return att
def page(conn, kind, scope, query, actor):
raw_limit = query.get('limit', ['50'])
require(len(raw_limit) == 1 and re.fullmatch(r'[0-9]+', raw_limit[0]) is not None)
limit = int(raw_limit[0])
require(1 <= limit <= 100)
resource = scope if kind == 'message' else 'chats:'+actor
boundary = None
if 'cursor' in query:
try:
require(len(query['cursor']) == 1)
cursor = json.loads(base64.urlsafe_b64decode(query['cursor'][0].encode()+b'==='))
require(isinstance(cursor, list) and len(cursor) == 3 and cursor[0] == resource)
uid(cursor[2])
require(isinstance(cursor[1], str) and cursor[1].endswith('Z'))
datetime.fromisoformat(cursor[1].replace('Z', '+00:00'))
boundary = cursor[1:]
except (ValueError, TypeError, binascii.Error, UnicodeError):
raise APIError(400, 'invalid_request') from None
if kind == 'message':
condition, params = "data->>'chat_id'=%s", [scope]
else:
condition, params = "data->'member_ids' ? %s", [actor]
if boundary:
condition += " AND (data->>'created_at',id)>(%s,%s)"
params.extend(boundary)
rows = conn.execute("SELECT data FROM objects WHERE kind=%s AND "+condition+" ORDER BY data->>'created_at',id LIMIT %s",
[kind]+params+[limit+1]).fetchall()
items = [r['data'] for r in rows[:limit]]
next_cursor = None
if len(rows)>limit:
next_cursor = base64.urlsafe_b64encode(json.dumps([resource, items[-1]['created_at'], items[-1]['id']]).encode()).decode()
return {'items': items, 'next_cursor': next_cursor}
def dispatch(method, path, params, query, headers, raw):
if path == '/health/live':
return 200, {'status': 'ok'}
if path == '/health/ready':
with db() as conn:
conn.execute('SELECT 1')
s3().head_bucket(Bucket=bucket())
# Durable DB outbox accepts uploads while RabbitMQ/worker are unavailable.
return 200, {'status': 'ok'}
with db() as conn:
if path == '/api/v1/auth/sessions' and method == 'POST':
require(not raw, 400)
try:
auth = headers.get('authorization', '')
require(auth.startswith('Basic '), 401, 'unauthorized')
username, password = base64.b64decode(auth[6:], validate=True).decode('utf-8').split(':', 1)
except (ValueError, UnicodeError, binascii.Error):
raise APIError(401, 'unauthorized') from None
row = conn.execute('SELECT * FROM usernames WHERE username=%s', (username,)).fetchone()
encoded = row['password_hash'] if row else DUMMY_HASH
salt, expected = encoded.split(':')
valid = False
if 12 <= len(password) <= 128:
computed = hashlib.scrypt(password.encode(), salt=bytes.fromhex(salt), n=16384, r=8, p=1).hex()
valid = hmac.compare_digest(computed, expected)
require(row is not None and valid, 401, 'unauthorized')
token = secrets.token_urlsafe(32)
expires = datetime.now(timezone.utc)+timedelta(seconds=int(config('SESSION_TTL_SECONDS', '3600')))
conn.execute('INSERT INTO sessions VALUES(%s,%s,%s)', (sha(token.encode()), row['user_id'], expires))
return 201, {'token': token, 'token_type': 'Bearer', 'expires_at': expires.isoformat().replace('+00:00','Z'),
'user': public_user(conn, row['user_id'])}
# Authentication precedes validation of resource identifiers / body.
actor = None if path == '/api/v1/users' and method == 'POST' else authenticate(conn, headers)
body = None
if method == 'POST' and not path.endswith('/attachments'):
try:
require(headers.get('content-type', '').split(';')[0] == 'application/json')
body = json.loads(raw)
except (ValueError, UnicodeError):
raise APIError(400, 'invalid_request') from None
if path == '/api/v1/users' and method == 'POST':
fields(body, ('username','display_name','password'))
username = text(body['username'], 32, 3)
require(re.fullmatch('[a-z0-9_]{3,32}', username) is not None)
display = text(body['display_name'], 100)
password = text(body['password'], 128, 12)
salt = secrets.token_bytes(16)
hashed = salt.hex()+':'+hashlib.scrypt(password.encode(), salt=salt, n=16384, r=8, p=1).hex()
user = {'id': str(uuid.uuid4()), 'username': username, 'display_name': display, 'created_at': now()}
conn.execute('INSERT INTO usernames VALUES(%s,%s,%s)', (username, user['id'], hashed))
put(conn, 'user', user)
return 201, user
if path == '/api/v1/users/me':
return 200, public_user(conn, actor)
if path == '/api/v1/auth/sessions/current':
conn.execute('DELETE FROM sessions WHERE token_hash=%s', (sha(headers['authorization'][7:].encode()),))
return 204, None
if path == '/api/v1/chats':
if method == 'GET':
return 200, page(conn, 'chat', None, query, actor)
fields(body, ('title','member_ids'))
members = ids(body['member_ids'], 100, 1)
require(actor in members and all(public_user(conn, x) for x in members))
chat = {'id': str(uuid.uuid4()), 'title': text(body['title'], 100), 'member_ids': members, 'created_at': now()}
put(conn, 'chat', chat)
return 201, chat
if 'chat_id' in params:
chat = chat_access(conn, params['chat_id'], actor)
if path == '/api/v1/chats/{chat_id}':
return 200, chat
if path.endswith('/messages'):
if method == 'GET':
return 200, page(conn, 'message', chat['id'], query, actor)
fields(body, ('text',), ('attachment_ids',))
message_text = text(body['text'], 4000, 0)
attachments = ids(body.get('attachment_ids', []), 10)
require(message_text.strip() or attachments)
key = headers.get('idempotency-key', '')
require(re.fullmatch(r'[A-Za-z0-9._:-]{1,128}', key) is not None)
payload = {'text': message_text, 'attachment_ids': attachments}
scope = actor+':POST:'+chat['id']+':'+key
# Cross-replica serialization. Hash collision merely serializes unrelated keys.
conn.execute('SELECT pg_advisory_xact_lock(hashtextextended(%s,0))', (scope,))
old = conn.execute("SELECT * FROM idempotency WHERE scope=%s AND created_at>now()-interval '24 hours'", (scope,)).fetchone()
if old:
require(old['payload'] == payload, 409, 'conflict')
return 201, old['response']
for aid in attachments:
att = attachment_access(conn, aid, actor)
require(att['chat_id'] == chat['id'], 404, 'not_found')
require(att['status'] != 'failed', 409, 'conflict')
message = {'id': str(uuid.uuid4()), 'chat_id': chat['id'], 'sender_id': actor,
**payload, 'created_at': now()}
put(conn, 'message', message)
conn.execute('DELETE FROM idempotency WHERE scope=%s', (scope,))
conn.execute('INSERT INTO idempotency(scope,payload,response) VALUES(%s,%s,%s)', (scope, Jsonb(payload), Jsonb(message)))
return 201, message
if path.endswith('/attachments'):
filename = query.get('filename', [''])[0]
text(filename, 255)
require(not any(x in filename for x in ('/', '\\')) and all(ord(x)>=32 and ord(x)!=127 for x in filename))
content_type = headers.get('content-type', '').split(';')[0]
require(content_type in ('image/png','image/jpeg'), 415, 'unsupported_media_type')
require(bool(raw), 415, 'unsupported_media_type')
inspect_image(raw, content_type)
aid, stamp = str(uuid.uuid4()), now()
att = {'id': aid, 'chat_id': chat['id'], 'owner_id': actor, 'filename': filename,
'content_type': content_type, 'size_bytes': len(raw), 'sha256': sha(raw),
'status': 'queued', 'variants': [], 'error_code': None, 'created_at': stamp, 'updated_at': stamp}
with tracer.start_as_current_span('s3.stage', record_exception=False, set_status_on_exception=False):
s3().put_object(Bucket=bucket(), Key='staging/'+aid, Body=raw, ContentType=content_type)
put(conn, 'attachment', att)
job = {'schema_version': 1, 'job_id': str(uuid.uuid4()), 'type': 'attachment.process.v1',
'attachment_id': aid, 'pipeline_version': 1, 'attempt': 1, 'created_at': stamp}
propagate.inject(job)
conn.execute('INSERT INTO outbox(id,payload) VALUES(%s,%s)', (job['job_id'], Jsonb(job)))
return 202, att
if 'attachment_id' in params:
att = attachment_access(conn, params['attachment_id'], actor)
if not path.endswith('/content'):
return 200, att
require(att['status'] == 'ready', 409, 'conflict')
variant = query.get('variant', ['original'])[0]
meta = att if variant == 'original' else next((v for v in att['variants'] if v['name']==variant), None)
require(meta is not None, 404, 'not_found')
with tracer.start_as_current_span('s3.download', record_exception=False, set_status_on_exception=False):
data = s3().get_object(Bucket=bucket(), Key='final/'+att['id']+'/'+variant)['Body'].read()
return 200, (data, meta['content_type'])
raise APIError(404, 'not_found')
DUMMY_HASH = '00'*16+':'+hashlib.scrypt(b'nonexistent-password', salt=bytes(16), n=16384, r=8, p=1).hex()
@asynccontextmanager
async def lifespan(app):
await run_in_threadpool(migrate)
yield
for provider in providers:
provider.shutdown()
app = FastAPI(lifespan=lifespan, docs_url=None, redoc_url=None, openapi_url=None)
async def endpoint(request: Request):
raw = bytearray()
async for chunk in request.stream():
raw.extend(chunk)
if len(raw)>int(config('MAX_UPLOAD_BYTES', '10485760')):
raise APIError(413, 'payload_too_large')
code, result = await run_in_threadpool(dispatch, request.method, request.scope['route'].path,
request.path_params, parse_qs(request.url.query, keep_blank_values=True), request.headers, bytes(raw))
if code == 204:
return Response(status_code=204)
if isinstance(result, tuple):
return Response(result[0], media_type=result[1], status_code=code)
return JSONResponse(result, status_code=code)
for path, methods in [('/health/live',['GET']),('/health/ready',['GET']),('/api/v1/users',['POST']),
('/api/v1/users/me',['GET']),('/api/v1/auth/sessions',['POST']),('/api/v1/auth/sessions/current',['DELETE']),
('/api/v1/chats',['GET','POST']),('/api/v1/chats/{chat_id}',['GET']),
('/api/v1/chats/{chat_id}/messages',['GET','POST']),('/api/v1/chats/{chat_id}/attachments',['POST']),
('/api/v1/attachments/{attachment_id}',['GET']),('/api/v1/attachments/{attachment_id}/content',['GET'])]:
app.add_api_route(path, endpoint, methods=methods)
def error_response(request, status, code):
response = JSONResponse({'error': {'code': code, 'message': code.replace('_',' '),
'request_id': request.state.request_id}}, status_code=status)
if status == 401:
scheme = 'Basic' if request.url.path == '/api/v1/auth/sessions' else 'Bearer'
response.headers['WWW-Authenticate'] = scheme+' realm="messenger"'+(', charset="UTF-8"' if scheme=='Basic' else '')
return response
@app.exception_handler(APIError)
async def api_error(request, exc):
return error_response(request, exc.status, exc.code)
@app.middleware('http')
async def observe(request, call_next):
request.state.request_id = uuid.uuid4().hex
started = time.monotonic()
with tracer.start_as_current_span('HTTP', context=propagate.extract(dict(request.headers)), kind=SpanKind.SERVER,
record_exception=False, set_status_on_exception=False) as span:
try:
response = await call_next(request)
except psycopg.errors.UniqueViolation:
response = error_response(request, 409, 'conflict')
except ImageTooLarge:
response = error_response(request, 413, 'payload_too_large')
except InvalidImage:
response = error_response(request, 415, 'unsupported_media_type')
except Exception as exc:
from botocore.exceptions import BotoCoreError, ClientError
unavailable = isinstance(exc, (psycopg.Error, BotoCoreError, ClientError))
response = error_response(request, 503 if unavailable else 500, 'unavailable' if unavailable else 'internal_error')
route = getattr(request.scope.get('route'), 'path', 'unmatched')
# Method is allowlisted too, to avoid attacker-controlled metric cardinality.
method = request.method if request.method in ('GET','POST','DELETE','HEAD','OPTIONS','PUT','PATCH') else 'OTHER'
labels = {'method': method, 'route': route, 'status_class': str(response.status_code//100)+'xx'}
elapsed = time.monotonic()-started
requests_count.add(1, labels)
http_duration.record(elapsed, labels)
span.update_name(method+' '+route)
span.set_attributes({**labels, 'http.response.status_code': response.status_code, 'request_id': request.state.request_id})
if response.status_code>=500:
span.set_status(Status(StatusCode.ERROR))
logger.log(40 if response.status_code>=500 else 20, 'http.request', extra={
'event': 'http.request', 'request_id': request.state.request_id, **labels,
'status_code': response.status_code, 'duration_seconds': elapsed})
response.headers['X-Request-Id'] = request.state.request_id
response.headers['X-Instance-Id'] = INSTANCE
response.headers['X-Trace-Id'] = format(span.get_span_context().trace_id, '032x')
return response
+117
View File
@@ -0,0 +1,117 @@
import hashlib
import io
import json
import os
import warnings
from contextlib import contextmanager
from datetime import datetime, timezone
from pathlib import Path
import boto3
from botocore.config import Config
import psycopg
from psycopg.rows import dict_row
from psycopg.types.json import Jsonb
from PIL import Image, ImageOps, UnidentifiedImageError
def config(name, default=None):
filename = os.getenv(name+'_FILE')
return Path(filename).read_text().strip() if filename else os.getenv(name, default)
def now():
return datetime.now(timezone.utc).isoformat(timespec='microseconds').replace('+00:00', 'Z')
@contextmanager
def db():
with psycopg.connect(config('DATABASE_URL'), row_factory=dict_row, connect_timeout=3,
options='-c statement_timeout=10000') as conn:
yield conn
def migrate():
with db() as conn:
conn.execute('SELECT pg_advisory_xact_lock(6006)')
conn.execute('''CREATE TABLE IF NOT EXISTS objects (
kind text NOT NULL, id text NOT NULL, data jsonb NOT NULL,
PRIMARY KEY(kind,id))''')
conn.execute('''CREATE TABLE IF NOT EXISTS usernames (
username text PRIMARY KEY, user_id text NOT NULL, password_hash text NOT NULL)''')
conn.execute('''CREATE TABLE IF NOT EXISTS sessions (
token_hash text PRIMARY KEY, user_id text NOT NULL, expires_at timestamptz NOT NULL)''')
conn.execute('''CREATE TABLE IF NOT EXISTS idempotency (
scope text PRIMARY KEY, payload jsonb NOT NULL, response jsonb NOT NULL,
created_at timestamptz NOT NULL DEFAULT now())''')
conn.execute('''CREATE TABLE IF NOT EXISTS outbox (
id text PRIMARY KEY, payload jsonb NOT NULL, sent boolean NOT NULL DEFAULT false)''')
def get(conn, kind, oid, lock=False):
row = conn.execute('SELECT data FROM objects WHERE kind=%s AND id=%s'+(' FOR UPDATE' if lock else ''), (kind, oid)).fetchone()
return row['data'] if row else None
def put(conn, kind, value):
conn.execute('INSERT INTO objects(kind,id,data) VALUES(%s,%s,%s) ON CONFLICT(kind,id) DO UPDATE SET data=excluded.data',
(kind, value['id'], Jsonb(value)))
def sha(data):
return hashlib.sha256(data).hexdigest()
def s3():
return boto3.client('s3', endpoint_url=config('S3_ENDPOINT', 'http://s3:9000'),
aws_access_key_id=config('S3_ACCESS_KEY_ID'), aws_secret_access_key=config('S3_SECRET_ACCESS_KEY'),
region_name=config('S3_REGION', 'us-east-1'), config=Config(
connect_timeout=3, read_timeout=10, retries={'max_attempts': 2},
request_checksum_calculation='when_required', response_checksum_validation='when_required',
s3={'addressing_style': 'path'}))
def bucket():
return config('S3_BUCKET', 'messenger-attachments')
class InvalidImage(Exception):
pass
class ImageTooLarge(Exception):
pass
def inspect_image(data, content_type=None):
try:
with warnings.catch_warnings():
warnings.simplefilter('error', Image.DecompressionBombWarning)
with Image.open(io.BytesIO(data)) as image:
if image.width * image.height > int(config('MAX_IMAGE_PIXELS', '40000000')):
raise ImageTooLarge()
mime = {'PNG': 'image/png', 'JPEG': 'image/jpeg'}.get(image.format)
if not mime or (content_type and mime != content_type):
raise InvalidImage()
image.verify()
with Image.open(io.BytesIO(data)) as image:
image.load()
return mime
except (Image.DecompressionBombError, Image.DecompressionBombWarning):
raise ImageTooLarge() from None
except (UnidentifiedImageError, OSError, ValueError, SyntaxError):
raise InvalidImage() from None
def thumbnail(data):
with Image.open(io.BytesIO(data)) as image:
image = ImageOps.exif_transpose(image).convert('RGBA')
scale = min(1, 256/image.width, 256/image.height)
size = (max(1, int(image.width*scale)), max(1, int(image.height*scale)))
image = image.resize(size, Image.Resampling.LANCZOS)
canvas = Image.new('RGB', size, 'white')
canvas.paste(image, mask=image.getchannel('A'))
output = io.BytesIO()
canvas.save(output, format='JPEG', quality=85)
result = output.getvalue()
return result, {'name': 'thumbnail', 'content_type': 'image/jpeg',
'width': size[0], 'height': size[1], 'size_bytes': len(result), 'sha256': sha(result)}
+26
View File
@@ -0,0 +1,26 @@
"""Bounded, authenticated S3 bucket bootstrap, without MinIO client images."""
import time
from botocore.exceptions import ClientError
from app.common import s3, bucket
def main():
for attempt in range(60):
try:
client = s3()
try:
client.head_bucket(Bucket=bucket())
except ClientError as exc:
if exc.response['Error']['Code'] not in ('404', 'NoSuchBucket', 'NotFound'):
raise
client.create_bucket(Bucket=bucket())
print('S3 bucket ready')
return
except Exception:
if attempt == 59:
raise SystemExit('S3 bootstrap failed; check storage configuration') from None
time.sleep(2)
if __name__ == '__main__':
main()
+38
View File
@@ -0,0 +1,38 @@
"""Explicit allowlist instrumentation: never export bodies, headers or exception text."""
import logging
import os
import socket
import uuid
from opentelemetry import metrics, trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
INSTANCE = os.getenv('INSTANCE_ID', socket.gethostname() + '-' + uuid.uuid4().hex[:8])
def setup(service):
resource = Resource.create({'service.name': service, 'service.version': '1.0.0',
'service.instance.id': INSTANCE, 'deployment.environment.name': 'lab'})
endpoint = os.getenv('OTEL_EXPORTER_OTLP_ENDPOINT', 'http://otel-collector:4318').rstrip('/')
tp = TracerProvider(resource=resource)
tp.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint+'/v1/traces', timeout=3), max_queue_size=2048))
trace.set_tracer_provider(tp)
mp = MeterProvider(resource=resource, metric_readers=[PeriodicExportingMetricReader(
OTLPMetricExporter(endpoint=endpoint+'/v1/metrics', timeout=3), export_interval_millis=5000)])
metrics.set_meter_provider(mp)
lp = LoggerProvider(resource=resource)
lp.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter(endpoint=endpoint+'/v1/logs', timeout=3), max_queue_size=2048))
logger = logging.getLogger(service)
logger.setLevel(logging.INFO)
logger.addHandler(LoggingHandler(logger_provider=lp))
# Only this application logger is exported; SDK/boto/SQL logs cannot leak secrets.
logger.propagate = False
meter = metrics.get_meter(service)
return trace.get_tracer(service), meter, logger, (tp, mp, lp)
+130
View File
@@ -0,0 +1,130 @@
"""DB outbox relay + durable RabbitMQ consumer; redeliveries are idempotent."""
import json
import threading
import time
import pika
from opentelemetry import propagate
from opentelemetry.trace import SpanKind, Status, StatusCode
from psycopg.types.json import Jsonb
from app.common import db, migrate, get, put, config, s3, bucket, thumbnail, now
from app.telemetry import setup
tracer, meter, logger, providers = setup('messenger-worker')
count = meter.create_counter('worker_jobs', unit='{job}')
duration = meter.create_histogram('worker_job_duration', unit='s')
QUEUE = 'attachments'
def connection():
params = pika.URLParameters(config('BROKER_URL'))
params.heartbeat = 120
params.blocked_connection_timeout = 10
params.socket_timeout = 5
conn = pika.BlockingConnection(params)
channel = conn.channel()
channel.queue_declare(queue=QUEUE, durable=True)
channel.confirm_delivery()
return conn, channel
def relay():
while True:
try:
conn, channel = connection()
try:
while True:
with db() as database:
row = database.execute('SELECT id,payload FROM outbox WHERE NOT sent LIMIT 1 FOR UPDATE SKIP LOCKED').fetchone()
if row:
channel.basic_publish(exchange='', routing_key=QUEUE, body=json.dumps(row['payload']),
properties=pika.BasicProperties(delivery_mode=2, content_type='application/json'), mandatory=True)
database.execute('UPDATE outbox SET sent=true WHERE id=%s', (row['id'],))
conn.process_data_events(time_limit=0.1)
if not row:
time.sleep(0.3)
finally:
if conn.is_open:
conn.close()
except Exception:
logger.warning('outbox.retry', extra={'event': 'outbox.retry'})
time.sleep(2)
def process(job):
# Lock serializes deliveries, including multiple worker processes.
# If killed, transaction rolls back; deterministic S3 keys are safe to overwrite.
with db() as database:
att = get(database, 'attachment', job['attachment_id'], lock=True)
if not att or att['status'] in ('ready','failed'):
return
att['status'] = 'processing'
put(database, 'attachment', att)
with tracer.start_as_current_span('s3.read_staging', record_exception=False, set_status_on_exception=False):
raw = s3().get_object(Bucket=bucket(), Key='staging/'+att['id'])['Body'].read()
with tracer.start_as_current_span('image.thumbnail', record_exception=False, set_status_on_exception=False):
thumb, meta = thumbnail(raw)
with tracer.start_as_current_span('s3.publish', record_exception=False, set_status_on_exception=False):
client = s3()
for name, data, mime in [('original', raw, att['content_type']), ('thumbnail', thumb, 'image/jpeg')]:
client.put_object(Bucket=bucket(), Key='final/'+att['id']+'/'+name, Body=data, ContentType=mime)
att.update(status='ready', variants=[meta], updated_at=now(), error_code=None)
with tracer.start_as_current_span('db.ready', record_exception=False, set_status_on_exception=False):
put(database, 'attachment', att)
def consume(channel, method, properties, body):
job = json.loads(body)
start = time.monotonic()
outcome = 'success'
with tracer.start_as_current_span('attachment.process', context=propagate.extract(job), kind=SpanKind.CONSUMER,
record_exception=False, set_status_on_exception=False) as span:
try:
process(job)
except Exception:
outcome = 'error'
span.set_status(Status(StatusCode.ERROR))
if job['attempt'] < int(config('JOB_MAX_ATTEMPTS', '5')):
job['attempt'] += 1
# Transactional retry intent is saved before acknowledging this delivery.
with db() as database:
database.execute('INSERT INTO outbox(id,payload) VALUES(%s,%s) ON CONFLICT(id) DO UPDATE SET payload=excluded.payload,sent=false',
(job['job_id'], Jsonb(job)))
else:
with db() as database:
att = get(database, 'attachment', job['attachment_id'], lock=True)
if att and att['status'] != 'ready':
att.update(status='failed', error_code='retry_exhausted', updated_at=now())
put(database, 'attachment', att)
time.sleep(min(job['attempt'], 5))
finally:
labels = {'job_type': 'attachment.process.v1', 'outcome': outcome}
count.add(1, labels)
elapsed = time.monotonic()-start
duration.record(elapsed, labels)
span.set_attributes(labels)
logger.log(40 if outcome=='error' else 20, 'job.completed', extra={
'event': 'job.completed', 'job_id': job['job_id'], 'attempt': job['attempt'],
'duration_seconds': elapsed, **labels})
channel.basic_ack(method.delivery_tag)
def main():
migrate()
threading.Thread(target=relay, daemon=True).start()
while True:
try:
conn, channel = connection()
try:
channel.basic_qos(prefetch_count=1)
channel.basic_consume(queue=QUEUE, on_message_callback=consume)
channel.start_consuming()
finally:
if conn.is_open:
conn.close()
except Exception:
logger.warning('consumer.retry', extra={'event': 'consumer.retry'})
time.sleep(2)
if __name__ == '__main__':
main()
+124
View File
@@ -0,0 +1,124 @@
name: mtusi2026lab6
x-app: &app
build: .
restart: unless-stopped
environment: &env
DATABASE_URL: postgresql://messenger:${POSTGRES_PASSWORD:?Run scripts/bootstrap.sh}@postgres:5432/messenger
S3_ENDPOINT: http://s3:9000
S3_BUCKET: messenger-attachments
S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID}
S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY}
BROKER_URL: amqp://messenger:${BROKER_PASSWORD}@broker:5672/%2F
OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
depends_on:
postgres: {condition: service_healthy}
broker: {condition: service_healthy}
s3-init: {condition: service_completed_successfully}
otel-collector: {condition: service_started}
healthcheck:
test: [CMD, python, -c, "import urllib.request; urllib.request.urlopen('http://localhost:8080/health/ready', timeout=15)"]
interval: 10s
timeout: 20s
retries: 5
services:
api1:
<<: *app
environment:
<<: *env
INSTANCE_ID: api1
api2:
<<: *app
environment:
<<: *env
INSTANCE_ID: api2
worker:
<<: *app
command: [python, -m, app.worker]
healthcheck: {disable: true}
lb:
image: haproxy:3.0.11-alpine
ports: ['127.0.0.1:8080:8080']
volumes: ['./infra/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro']
depends_on: [api1, api2]
restart: unless-stopped
postgres:
image: postgres:17.5-alpine
environment:
POSTGRES_DB: messenger
POSTGRES_USER: messenger
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes: [postgres:/var/lib/postgresql/data]
healthcheck:
test: [CMD-SHELL, 'pg_isready -U messenger -d messenger']
interval: 5s
timeout: 3s
retries: 30
s3:
image: chrislusf/seaweedfs:3.85
command: [server, '-dir=/data', '-ip=s3', '-ip.bind=0.0.0.0', '-volume.max=5', '-s3', '-s3.port=9000', '-s3.config=/etc/seaweedfs/s3.json']
volumes:
- seaweed:/data
- ./secrets/seaweed-s3.json:/etc/seaweedfs/s3.json:ro
- ./infra/seaweedfs/filer.toml:/etc/seaweedfs/filer.toml:ro
restart: unless-stopped
s3-init:
build: .
depends_on: [s3]
environment:
S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID}
S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY}
S3_ENDPOINT: http://s3:9000
S3_BUCKET: messenger-attachments
command: [python, -m, app.init_storage]
broker:
image: rabbitmq:4.1.0-alpine
environment:
RABBITMQ_DEFAULT_USER: messenger
RABBITMQ_DEFAULT_PASS: ${BROKER_PASSWORD}
volumes: [broker:/var/lib/rabbitmq]
healthcheck:
test: [CMD, rabbitmq-diagnostics, -q, ping]
interval: 10s
timeout: 5s
retries: 30
otel-collector:
image: otel/opentelemetry-collector-contrib:0.128.0
command: ['--config=/etc/otelcol/config.yaml']
volumes: ['./infra/otel/collector.yaml:/etc/otelcol/config.yaml:ro']
depends_on: [loki, tempo]
restart: unless-stopped
prometheus:
image: prom/prometheus:v3.4.0
command: ['--config.file=/etc/prometheus/prometheus.yml', '--storage.tsdb.retention.time=7d']
volumes: ['./infra/prometheus.yaml:/etc/prometheus/prometheus.yml:ro', 'prometheus:/prometheus']
ports: ['127.0.0.1:9090:9090']
loki:
image: grafana/loki:3.5.0
command: ['-config.file=/etc/loki/local.yaml']
volumes: ['./infra/loki.yaml:/etc/loki/local.yaml:ro', 'loki:/loki']
ports: ['127.0.0.1:3100:3100']
tempo:
image: grafana/tempo:2.7.2
command: ['-config.file=/etc/tempo.yaml']
volumes: ['./infra/tempo.yaml:/etc/tempo.yaml:ro', 'tempo:/var/tempo']
ports: ['127.0.0.1:3200:3200']
grafana:
image: grafana/grafana:12.0.1
environment:
GF_SECURITY_ADMIN_USER: admin
GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
GF_USERS_ALLOW_SIGN_UP: 'false'
ports: ['127.0.0.1:3000:3000']
volumes:
- grafana:/var/lib/grafana
- ./infra/grafana/provisioning:/etc/grafana/provisioning:ro
- ./infra/grafana/dashboards:/var/lib/grafana/dashboards:ro
volumes:
postgres:
s3:
seaweed:
broker:
prometheus:
loki:
tempo:
grafana:
+17
View File
@@ -0,0 +1,17 @@
{
"lab": 6,
"workload": "closed-loop POST messages; no automatic retries",
"requested_duration_seconds": 30.0,
"elapsed_seconds": 30.093,
"concurrency": 4,
"successful_requests": 12773,
"failed_requests": 0,
"error_ratio": 0.0,
"successful_rps": 424.445,
"successful_latency_ms": {
"p50": 8.683,
"p95": 12.634,
"p99": 23.901
},
"note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead."
}
+94
View File
@@ -0,0 +1,94 @@
# Результаты проверок 16 и 20 ноября 2026 года
Источник — вывод команд на стенде. Секреты и сессионные токены не сохранены.
## Состояние до проверок
`docker compose ps -a`: api1/api2 — Up 10 minutes (healthy), postgres и broker —
healthy; worker, lb, grafana, loki, tempo, prometheus, otel-collector, s3 — Up;
s3-init — Exited (0). Полный набор ролей запущен. После restart состояния не присланы.
## Smoke
```
make test
PASS: lab6 public API scenario; infrastructure and grading evidence remain separate.
```
## Persistence
```
make test-persistence ACTION_SCRIPT=scripts/restart.sh
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
```
## Failover
```
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 54, "failed_attempts": 4, "first_recovery_seconds": 2.696}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
```
## Нагрузка
Команда: `python3 tests/load.py --duration 30 --concurrency 4 --output evidence/load.json`.
Результаты нагрузки из `evidence/load.json` приведены ниже.
12773 успеха, 0 ошибок, 424.445 RPS; p50/p95/p99 = 8.683/12.634/23.901 мс.
## Повторяемый failover — дополнительный запуск
```text
make test-failover-repeatable
Both API replicas are ready through the load balancer
{"observed_instances_before": 2, "successful_writes": 72, "failed_attempts": 3, "first_recovery_seconds": 2.355}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
```
В заключительном выводе Docker api1 имеет статус Started; обёртка запускает обе
реплики после завершения теста.
## Скриншоты Grafana
В REPORT.md описаны наблюдения по семи скриншотам Grafana: два вида
дашборда, лог и трасса API, поиск логов worker, лог обработки и трасса загрузки.
API trace ID: 0bfcaa8384a34151aee4ae0d4387441d.
Upload/worker trace ID: 0dc6e36ad05603919332b5957929c909.
Job outcome=success, attempt=1, duration=28.63 мс; в upload trace семь spans.
Графики p95 имеют грубые histogram buckets, их значения не трактуются как точные percentile.
## Повторная проверка failover 20.11.2026
Интервал — 17:41:06–17:41:32 МСК. Команда `make test-failover-repeatable`.
```text
Both API replicas are ready through the load balancer
{"observed_instances_before": 2, "successful_writes": 54, "failed_attempts": 4, "first_recovery_seconds": 2.355}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
```
После теста сценарий запустил `api1`. При проверке `docker compose ps api1 api2`
реплика `api1` имела статус health: starting, а `api2` — healthy.
В Loki в 17:41:28.589 МСК зафиксировано создание сообщения через `api2`
с HTTP 201 за 10,35 мс. Trace ID — `82a1d11fa18230512035ebcd76cb3a35`.
## Проверка остановки worker 20.11.2026
Интервал — 17:31:25–17:31:37 МСК. Команда `python3 scripts/test-worker-outage.py`.
```text
worker stopped, attachment queued, trace_id=dc807159c626aaf72c9ae58641117383
PASS: attachment ready, original verified, trace_id=dc807159c626aaf72c9ae58641117383
```
События `http.request` и `job.completed` найдены в Loki, семь spans той же
операции — в Tempo. Измерения приведены в REPORT.md.
## Доказательство перезапуска PostgreSQL
Тест сохранности завершился с PASS. Значения `StartedAt` контейнера PostgreSQL
до и после запуска hook пока не зафиксированы.
+169
View File
@@ -0,0 +1,169 @@
{
"uid": "messenger",
"title": "Messenger observability",
"schemaVersion": 41,
"version": 1,
"refresh": "5s",
"time": {
"from": "now-15m",
"to": "now"
},
"panels": [
{
"id": 1,
"title": "API requests / second",
"type": "timeseries",
"datasource": {
"uid": "prometheus",
"type": "prometheus"
},
"gridPos": {
"x": 0,
"y": 0,
"w": 12,
"h": 8
},
"targets": [
{
"expr": "sum by (service_instance_id) (rate(http_requests_total{route!~\"/health/.*\"}[1m]))",
"refId": "A",
"legendFormat": "{{outcome}} {{service_instance_id}}"
}
],
"fieldConfig": {
"defaults": {
"unit": "reqps"
}
}
},
{
"id": 2,
"title": "API 5xx / second",
"type": "timeseries",
"datasource": {
"uid": "prometheus",
"type": "prometheus"
},
"gridPos": {
"x": 12,
"y": 0,
"w": 12,
"h": 8
},
"targets": [
{
"expr": "sum(rate(http_requests_total{status_class=\"5xx\",route!~\"/health/.*\"}[1m]))",
"refId": "A",
"legendFormat": "{{outcome}} {{service_instance_id}}"
}
],
"fieldConfig": {
"defaults": {
"unit": "reqps"
}
}
},
{
"id": 3,
"title": "API p95 duration",
"type": "timeseries",
"datasource": {
"uid": "prometheus",
"type": "prometheus"
},
"gridPos": {
"x": 0,
"y": 8,
"w": 12,
"h": 8
},
"targets": [
{
"expr": "histogram_quantile(0.95, sum by (le) (rate(http_duration_seconds_bucket{route!~\"/health/.*\"}[1m])))",
"refId": "A",
"legendFormat": "{{outcome}} {{service_instance_id}}"
}
],
"fieldConfig": {
"defaults": {
"unit": "s"
}
}
},
{
"id": 4,
"title": "Worker jobs / second",
"type": "timeseries",
"datasource": {
"uid": "prometheus",
"type": "prometheus"
},
"gridPos": {
"x": 12,
"y": 8,
"w": 12,
"h": 8
},
"targets": [
{
"expr": "sum by (outcome) (rate(worker_jobs_total[1m]))",
"refId": "A",
"legendFormat": "{{outcome}} {{service_instance_id}}"
}
],
"fieldConfig": {
"defaults": {
"unit": "ops"
}
}
},
{
"id": 5,
"title": "Worker p95 duration",
"type": "timeseries",
"datasource": {
"uid": "prometheus",
"type": "prometheus"
},
"gridPos": {
"x": 0,
"y": 16,
"w": 12,
"h": 8
},
"targets": [
{
"expr": "histogram_quantile(0.95, sum by (le,outcome) (rate(worker_job_duration_seconds_bucket[1m])))",
"refId": "A",
"legendFormat": "{{outcome}} {{service_instance_id}}"
}
],
"fieldConfig": {
"defaults": {
"unit": "s"
}
}
},
{
"id": 6,
"title": "API and worker structured logs",
"type": "logs",
"datasource": {
"uid": "loki",
"type": "loki"
},
"gridPos": {
"x": 12,
"y": 16,
"w": 12,
"h": 8
},
"targets": [
{
"expr": "{service_name=~\"messenger-api|messenger-worker\"}",
"refId": "A"
}
]
}
]
}
@@ -0,0 +1,6 @@
apiVersion: 1
providers:
- name: Messenger
type: file
options:
path: /var/lib/grafana/dashboards
@@ -0,0 +1,25 @@
apiVersion: 1
datasources:
- name: Prometheus
uid: prometheus
type: prometheus
access: proxy
url: http://prometheus:9090
isDefault: true
- name: Loki
uid: loki
type: loki
access: proxy
url: http://loki:3100
jsonData:
derivedFields:
- name: TraceID
matcherType: label
matcherRegex: trace_id
datasourceUid: tempo
url: '$${__value.raw}'
- name: Tempo
uid: tempo
type: tempo
access: proxy
url: http://tempo:3200
+20
View File
@@ -0,0 +1,20 @@
global
maxconn 1024
defaults
mode http
timeout connect 2s
timeout client 30s
timeout server 30s
resolvers docker
nameserver embedded 127.0.0.11:53
hold valid 2s
frontend http
bind :8080
default_backend api
backend api
balance roundrobin
option httpchk GET /health/ready
http-check expect status 200
default-server inter 2s fall 2 rise 1 resolvers docker init-addr libc,none
server api1 api1:8080 check
server api2 api2:8080 check
+23
View File
@@ -0,0 +1,23 @@
auth_enabled: false
server:
http_listen_port: 3100
common:
path_prefix: /loki
replication_factor: 1
ring:
kvstore:
store: inmemory
schema_config:
configs:
- from: '2024-04-01'
store: tsdb
object_store: filesystem
schema: v13
index:
prefix: index_
period: 24h
storage_config:
filesystem:
directory: /loki/chunks
limits_config:
allow_structured_metadata: true
+45
View File
@@ -0,0 +1,45 @@
receivers:
otlp:
protocols:
http:
endpoint: 0.0.0.0:4318
processors:
memory_limiter:
check_interval: 1s
limit_mib: 256
spike_limit_mib: 64
batch:
timeout: 2s
exporters:
prometheus:
endpoint: 0.0.0.0:8889
resource_to_telemetry_conversion:
enabled: true
otlphttp/loki:
endpoint: http://loki:3100/otlp
sending_queue:
queue_size: 512
retry_on_failure:
max_elapsed_time: 30s
otlp/tempo:
endpoint: tempo:4317
tls:
insecure: true
sending_queue:
queue_size: 512
retry_on_failure:
max_elapsed_time: 30s
service:
pipelines:
metrics:
receivers: [otlp]
processors: [memory_limiter, batch]
exporters: [prometheus]
logs:
receivers: [otlp]
processors: [memory_limiter, batch]
exporters: [otlphttp/loki]
traces:
receivers: [otlp]
processors: [memory_limiter, batch]
exporters: [otlp/tempo]
+6
View File
@@ -0,0 +1,6 @@
global:
scrape_interval: 5s
scrape_configs:
- job_name: messenger
static_configs:
- targets: ['otel-collector:8889']
+3
View File
@@ -0,0 +1,3 @@
[leveldb2]
enabled = true
dir = "/data/filer"
+20
View File
@@ -0,0 +1,20 @@
server:
http_listen_port: 3200
distributor:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
storage:
trace:
backend: local
wal:
path: /var/tempo/wal
local:
path: /var/tempo/blocks
compactor:
compaction:
block_retention: 168h
+8
View File
@@ -0,0 +1,8 @@
fastapi==0.115.12
uvicorn==0.34.2
psycopg[binary]==3.2.9
boto3==1.38.23
pika==1.3.2
Pillow==11.2.1
opentelemetry-sdk==1.33.1
opentelemetry-exporter-otlp-proto-http==1.33.1
+27
View File
@@ -0,0 +1,27 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
python3 - <<'PY'
from pathlib import Path
import secrets
import json
p = Path('.env')
if not p.exists():
p.write_text('\n'.join(k+'='+secrets.token_hex(20) for k in (
'POSTGRES_PASSWORD','BROKER_PASSWORD','S3_ACCESS_KEY_ID','S3_SECRET_ACCESS_KEY','GRAFANA_PASSWORD'))+'\n')
p.chmod(0o600)
print('Created local .env')
else:
print('Keeping existing .env')
values = dict(line.split('=', 1) for line in p.read_text().splitlines()
if line.strip() and not line.lstrip().startswith('#') and '=' in line)
folder = Path('secrets')
folder.mkdir(exist_ok=True, mode=0o700)
config = folder / 'seaweed-s3.json'
config.write_text(json.dumps({'identities': [{'name': 'messenger',
'credentials': [{'accessKey': values['S3_ACCESS_KEY_ID'].strip(),
'secretKey': values['S3_SECRET_ACCESS_KEY'].strip()}],
'actions': ['Admin', 'Read', 'Write', 'List', 'Tagging']}]}))
config.chmod(0o600)
print('Configured authenticated SeaweedFS storage')
PY
+4
View File
@@ -0,0 +1,4 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
docker compose restart api1 api2 worker postgres s3 broker otel-collector prometheus loki tempo grafana lb
+7
View File
@@ -0,0 +1,7 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
case "${TARGET_INSTANCE_ID:-}" in
api1|api2) docker compose stop "$TARGET_INSTANCE_ID" ;;
*) exit 2 ;;
esac
+34
View File
@@ -0,0 +1,34 @@
#!/bin/sh
# Restore both replicas before and after the unchanged public failure test.
set -eu
cd "$(dirname "$0")/.."
restore() {
docker compose start api1 api2
}
trap restore EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
restore
"${PYTHON:-python3}" - <<'PY'
import os
import time
import urllib.request
base = os.environ.get('BASE_URL', 'http://localhost:8080').rstrip('/')
seen = set()
deadline = time.monotonic() + 90
while time.monotonic() < deadline:
try:
with urllib.request.urlopen(base + '/health/ready', timeout=3) as response:
instance = response.headers.get('X-Instance-Id')
if response.status == 200 and instance:
seen.add(instance)
if {'api1', 'api2'} <= seen:
print('Both API replicas are ready through the load balancer')
break
except OSError:
pass
time.sleep(0.3)
else:
raise SystemExit('Both API replicas did not become ready within 90 seconds')
PY
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
+49
View File
@@ -0,0 +1,49 @@
#!/usr/bin/env python3
"""Check that an upload survives a temporary worker outage."""
from pathlib import Path
import subprocess
import sys
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / 'tests'))
from client import Client, arguments, check, run
def compose(action):
try:
subprocess.run(['docker', 'compose', action, 'worker'], cwd=ROOT, check=True)
except subprocess.CalledProcessError as exc:
raise SystemExit(f'docker compose {action} worker failed ({exc.returncode})') from None
def main():
args = arguments(__doc__)
client = Client(args.base_url, args.ca_file)
alice, _, _, chat = client.bootstrap()
content = (ROOT / 'tests/fixtures/sample.png').read_bytes()
try:
compose('stop')
upload = client.call(
'POST', f'/api/v1/chats/{chat["id"]}/attachments?filename=sample.png',
expected=202, actor=alice, raw=content,
headers={'Content-Type': 'image/png'}, schema='Attachment',
)
trace_id = upload['headers'].get('X-Trace-Id')
check(bool(trace_id), 'missing upload trace ID')
attachment = upload['json']
path = f'/api/v1/attachments/{attachment["id"]}'
metadata = client.call('GET', path, actor=alice, schema='Attachment')['json']
check(metadata['status'] == 'queued', 'expected queued while worker is stopped')
print(f'worker stopped, attachment queued, trace_id={trace_id}', flush=True)
finally:
compose('start')
client.wait_ready(alice, attachment)
original = client.call('GET', f'{path}/content', actor=alice)['bytes']
check(original == content, 'downloaded original differs from the upload')
print(f'PASS: attachment ready, original verified, trace_id={trace_id}')
if __name__ == '__main__':
run(main)