ЛР6: OTel SDK, Collector, Prometheus/Loki/Tempo, Grafana, alerts, dashboard, тесты инцидентов

This commit is contained in:
2026-11-16 22:14:42 +03:00
commit e617ce2caa
87 changed files with 8695 additions and 0 deletions
+20
View File
@@ -0,0 +1,20 @@
.git
.github
.env
.env.*
!.env.example
secrets
certs
volumes
data
backups
*.key
*.pem
*.p12
*.pfx
*.jks
.venv
__pycache__
node_modules
evidence
.DS_Store
+30
View File
@@ -0,0 +1,30 @@
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
# These are logical interface suggestions; map actual framework names in REPORT.md.
APP_HOST=0.0.0.0
APP_PORT=8080
APP_ENV=lab
SESSION_TTL_SECONDS=3600
# Choose credentials locally. File paths contain no secret values.
DATABASE_URL_FILE=/run/secrets/database_url
# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
SESSION_STORE=postgres
CACHE_URL_FILE=/run/secrets/cache_url
API_REPLICAS=2
IDEMPOTENCY_TTL_SECONDS=86400
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
BROKER_URL_FILE=/run/secrets/broker_url
WORKER_CONCURRENCY=2
JOB_MAX_ATTEMPTS=5
JOB_TIMEOUT_SECONDS=60
STAGING_RETENTION_SECONDS=86400
OTEL_SERVICE_NAME=messenger-api
# Worker must set a distinct service.name.
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=lab
+18
View File
@@ -0,0 +1,18 @@
## Лабораторная 6
Автор / группа: TODO
Целевая оценка (3/4/5): TODO
Трек 5, если заявлен: TODO
Что реализовано и что перенесено: TODO
Команды запуска из чистого clone: TODO
Результаты проверок и ссылка на REPORT.md: TODO
Ограничения / известные ошибки: TODO
Источники и использование ИИ: TODO
- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [ ] Контракт и публичные тесты не ослаблены.
- [ ] make check и make test выполнены; приложен реальный вывод.
- [ ] Сценарии отказов/безопасности своего уровня воспроизведены.
- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
+16
View File
@@ -0,0 +1,16 @@
name: Skeleton contracts
on: [push, pull_request]
permissions:
contents: read
jobs:
contracts:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- run: python -m pip install -r requirements-dev.txt
- run: make check validate PYTHON=python
# This job validates the skeleton, not a student solution.
# Add build, readiness and make test in a separate application job.
+34
View File
@@ -0,0 +1,34 @@
# Local/private state
.env
.env.*
!.env.example
secrets/
certs/private/
*.key
*.p12
*.pfx
*.jks
*.pem
*.tfstate*
volumes/
data/
backups/
# Runtime/build artifacts
.venv/
__pycache__/
*.py[cod]
node_modules/
dist/
build/
target/
bin/
obj/
coverage/
*.log
.DS_Store
.idea/
.vscode/
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
venv/
+19
View File
@@ -0,0 +1,19 @@
# Работа через fork и pull request
1. После публикации преподавателем сделайте fork репозитория **текущей** лабораторной в своём аккаунте и clone своего fork. URL преподаватель выдаёт отдельно.
2. Создайте ветку `solution/<group>-<surname>` от исходной ветки skeleton. Ветка преподавателя и файлы контракта остаются основой проверки.
3. Для lab2–7 перенесите из своей предыдущей лабы только исходники, миграции, собственные тесты, Dockerfile и нужные конфигурации. Не копируйте `.git`, `.env`, credentials, volumes, `README.md`, `COURSE.md`, публичные `tests/` и `contracts/` поверх новой версии. Сначала сравните изменения API в `COURSE.md`.
4. Реализуйте задание, добавьте свою инструкцию запуска и заполните `REPORT.md`. Публичные проверки дополняйте отдельными тестами, не ослабляйте assertions.
5. Выполните `make check`, запустите свой стенд, затем `make test`. Выполните сценарии отказов текущей лабы. Их запуск всегда явный: scaffold сам не останавливает контейнеры.
6. Commit и push делайте в свой fork. Откройте PR в исходный репозиторий преподавателя, заголовок: `ЛР N — Группа — Фамилия — на 3/4/5`. Выберите правильную базовую ветку и заполните шаблон.
7. После замечаний обновляйте тот же PR. Чужие решения не переносите без указания источника и согласованных правил курса.
Платформа может называть PR «merge request» — процесс тот же. `.github/` содержит необязательные удобства для GitHub; проверки локально от платформы не зависят. Инициализация и публикация исходных Git-репозиториев выполняются преподавателем отдельно.
## Правила изменения skeleton
Не удаляйте обязательные endpoint, поля, рубрику и публичные проверки. Изменение контракта согласуйте отдельным комментарием/PR; обход тестов не является решением. Код приложения размещайте в `src/` либо в принятой для языка структуре. Собственные тесты — `student-tests/` или штатный каталог фреймворка. Ссылки на результаты проверки и команды запуска должны переживать clone на другой машине.
## CI
Готовый GitHub workflow проверяет целостность контракта и синтаксис Python-проверок. Он **не запускает отсутствующее приложение** и **не подтверждает оценку**. Студент добавляет сборку своего приложения, запуск/готовность стенда и `make test` в отдельный job. Не используйте `pull_request_target` для запуска кода из fork, не выдавайте CI секреты или доступ к общему Docker-host.
+53
View File
@@ -0,0 +1,53 @@
# Сквозной проект: мессенджер под нагрузкой
Семь самостоятельных репозиториев содержат задания и проверяемые контракты одной системы. Вы переносите собственную реализацию между лабораторными. Язык, фреймворк и библиотеки выбираете сами. Web UI, WebSocket, редактирование/удаление сообщений, публичный поиск пользователей и Kubernetes не входят в обязательный минимум: достаточно REST API.
| Лаба | Новая инженерная задача | Что появляется в системе |
| --- | --- | --- |
| 1 | Контракт, процессы и контейнер | In-memory API, Dockerfile, HTTP smoke |
| 2 | Сохранность и идентификация | PostgreSQL, Basic → сессия; Redis/Valkey на 4 |
| 3 | Горизонтальное масштабирование | Балансировщик, ≥2 API-реплики, общие сессии, идемпотентность |
| 4 | Бинарные данные | Приватное S3-совместимое хранилище и вложения |
| 5 | Фоновая работа | Брокер, worker, состояния вложений и преобразование изображений |
| 6 | Диагностика | OTel Collector, хранилища сигналов, Grafana |
| 7 | Защита и эксплуатация | Argon2id, TLS/mTLS, OpenBao, минимальные привилегии |
## Как оценивать
Оценки накопительные **внутри лабораторной**: 4 = весь уровень 3 + весь уровень 4; 5 = весь уровень 4 + **один** полностью выполненный трек 5 на выбор. Несколько недоделанных треков не заменяют один завершённый. Условие «весь уровень» включает реализацию, проверку и объяснение на защите. Красивые схемы и дополнительные технологии не компенсируют неработающий обязательный сценарий.
Для начала следующей лабы достаточно обязательного минимума предыдущей. Сохраняются предыдущие обязательные возможности, с явно описанными переходами API ниже. Не требуется сначала получить 5 за все ранние лабы. Можно исправлять свою базу по ходу курса; такие исправления выделяйте в PR. Реализация на 3 работоспособна, но не претендует на промышленную готовность. Даже 5 в lab7 — учебная доказанная защита в заявленной модели угроз, а не сертификат полной безопасности.
На 3 студент самостоятельно собирает рабочую систему. На 4 показывает практики, ожидаемые от стажёра/джуна в команде: воспроизводимость, диагностику, обработку ошибок и проверки отказов. На 5 формулирует гипотезу, ставит эксперимент, приводит измерения и обсуждает границы решения — это предмет конкретной похвалы магистранту.
## Контракт и совместимость
`contracts/openapi.json` — OpenAPI 3.1.0, `contracts/README.md` — нормативная семантика. Контракт каждого репозитория самодостаточен; соседние папки на машине преподавателя не нужны. `tests/` — публичные проверки, а не эталонное решение. Контракт, рубрика и публичные тесты имеют приоритет над случайным поведением библиотек. При противоречии создайте вопрос преподавателю; не подгоняйте тест под приложение.
Три объявленных изменения обязательного API:
1. **1 → 2:** регистрация требует `password`; `X-User-Id` заменяется Bearer. Basic используется только при создании сессии.
2. **2 → 3:** `Idempotency-Key` обязателен для отправки сообщения; ответы API содержат `X-Instance-Id`.
3. **4 → 5:** загрузка вложения возвращает `202` вместо `201`, состояние становится асинхронным. Клиент опрашивает метаданные. Старое текстовое сообщение остаётся валидным: `attachment_ids` по умолчанию `[]`.
У lab7 меняется транспорт на HTTPS, бизнес-эндпоинты остаются прежними. Внутреннее mTLS не заменяет пользовательскую сессию. Новые возможности на 4/5 добавляйте обратно совместимо, в отдельном `contracts/extensions.openapi.json` или документе; обязательный контракт сохраняйте.
## Общая предметная модель
Пользователь (`username`, `display_name`) состоит в чатах. Список участников задаётся при создании чата и в обязательном API не изменяется. В чате отправляются сообщения, с lab4 — со ссылками на вложения этого чата. Сервер назначает UUID и время. Порядок истории — `(created_at, id)` по возрастанию. Для защиты достаточно показать взаимодействие нескольких API-клиентов; фронтенд не требуется.
С lab2 данные PostgreSQL — источник истины. Сессии могут храниться в PostgreSQL или Redis/Valkey, если выполняют контракт срока жизни и перезапуска. Файлы с lab4 живут в S3, метаданные — в PostgreSQL. Redis и Valkey — альтернативы: оба одновременно не нужны. Аналогично выбирается одно S3-хранилище, один брокер и один основной путь оркестрации.
## Воспроизводимость и честные измерения
- Укажите версии runtime и контейнерных образов, аппаратную конфигурацию, CPU/RAM-лимиты, команду запуска и время прогрева. Для образов используйте явный тег версии или digest, не `latest`.
- Все тестовые пользователи и изображения синтетические. `make test` создаёт данные: запускайте его на учебном стенде. Не публикуйте пароли, токены, приватные ключи, персональные данные или подписанные URL.
- Минимальный отчёт о нагрузке: длительность, конкуренция/интенсивность, успешные RPS, доля ошибок, p50/p95/p99, CPU/RAM, размер набора данных. Универсального проходного RPS для разных ноутбуков нет.
- Сравнивайте одинаковые запросы при одинаковых ресурсах. Успешный `/health/live` не доказывает сохранность сообщений, а HTTP `202` — окончание обработки.
- Один Docker-host не обеспечивает отказоустойчивость к потере этого host. Несколько API-процессов не делают единственную БД или LB высокодоступными. Отдельно называйте, какие отказы выдерживает эксперимент.
## Что сдавать
Исходники, Dockerfile, нужные манифесты и конфигурации, миграции, собственные тесты, заполненный `REPORT.md`, сведения об использовании внешнего кода и ИИ. Уметь объяснить и изменить своё решение на защите обязательно. Приложите команды и текстовые результаты; скриншоты — дополнение, а не единственное доказательство.
PR должен собираться из чистого clone по инструкции автора. Секреты создаются отдельно; тестовые fixtures и открытые конфигурации хранятся в репозитории. Перенос кода между лабами описан в [CONTRIBUTING.md](CONTRIBUTING.md).
+21
View File
@@ -0,0 +1,21 @@
FROM python:3.11.9-slim
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1 PIP_DISABLE_PIP_VERSION_CHECK=1
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY main.py .
COPY app ./app
COPY scripts ./scripts
RUN useradd --system --uid 10001 --no-create-home --shell /usr/sbin/nologin appuser
USER 10001
EXPOSE 8080
HEALTHCHECK --interval=5s --timeout=3s --start-period=15s --retries=10 \
CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/live', timeout=2)"]
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080", "--timeout-graceful-shutdown", "10"]
+8
View File
@@ -0,0 +1,8 @@
# Teaching outline, not a runnable Dockerfile. Implement your own Dockerfile.
# 1. Choose a runtime/toolchain version and pin the base image tag/digest.
# 2. Copy dependency manifests first; install from the language lockfile.
# 3. Copy source and build. For compiled languages use a separate runtime stage.
# 4. Run the HTTP process as PID 1; listen on 0.0.0.0:8080.
# 5. Add non-root, signals and healthcheck according to the current rubric.
# 6. Pass runtime config/secrets at startup, never COPY .env or secret files.
# This file deliberately has no FROM/CMD: selecting/implementing them is the task.
+38
View File
@@ -0,0 +1,38 @@
# Памятка преподавателю — лабораторная 6
## Что подготовлено
Язык реализации не задан. README содержит накопительные уровни 3/4/5, сценарий защиты и вопросы. В каждой лабе собственная полная версия OpenAPI, поэтому fork не зависит от соседних каталогов. Публичный HTTP smoke не содержит реализации сервера; Dockerfile.example и compose.example.yaml (если есть) — задания/ориентиры, не готовый deployment.
## Перед публикацией
1. Выберите GitHub/GitLab и организацию, опубликуйте каждый каталог как отдельный template/skeleton repository, сообщите студентам URL и правила именования PR/MR. Эти материалы не публикуют репозитории автоматически.
2. Задайте default branch, защиту исходных материалов и правила приёма. `.github/` уже содержит шаблон PR и CI контракта; в GitLab перенесите эквивалентные настройки, локальные Makefile-команды одинаковы.
3. Сообщите, индивидуальная работа или командная, сроки, правила использования стороннего кода/ИИ и ресурсы демонстрационного стенда. Эти организационные решения намеренно не выдуманы в задании.
4. Уточните ограничения площадки (например доступна ли виртуализация/несколько узлов). Для 5 предусмотрено по два трека: один можно выполнить без настоящего multi-node cloud. Универсальный проходной RPS не установлен.
## Что проверять
| Проверка | Что подтверждает | Чего не подтверждает |
| --- | --- | --- |
| make check | Структура файлов, JSON, локальные refs, синтаксис Python | Реализация/запуск API |
| make validate | Полная OpenAPI 3.1, JSON Schema и примеры | Поведение сервера |
| make test | Один сквозной контрактный сценарий текущей лабы | Все ошибки, persistence, HA, security |
| test-persistence (lab2+) | Данные/прежний токен после вызова restart hook | Реальный перезапуск, если hook — no-op |
| test-failover (lab3+) | Смена обслуживающей реплики, сохранность, retry без дубля | Несколько физических узлов, HA DB/LB |
| test-security (lab7) | Доверенный HTTPS и отказ недоверенного CA | Внутреннее mTLS/identity/ACL/OpenBao |
| Защита и тесты студента | Реальность инфраструктуры и критерии выбранного уровня | Неограниченная промышленная безопасность |
Проверяйте реальные контейнеры/логи процессов и данные до/после отказа: одного X-Instance-Id недостаточно. Для 4 требуются все пункты 3+4, для 5 — все пункты 3+4 и один **завершённый** трек 5. Сравнивайте подтверждённые результаты со сформулированными критериями, а не количество установленных сервисов.
## Приём PR
Проверка запускается на изолированном учебном окружении с синтетическими secrets, не на общей production БД. Студенческие Dockerfile/hooks/CI — выполняемый код: обычный fork workflow без секретов и без доступа к общему Docker socket. Не запускайте PR через pull_request_target с привилегиями преподавателя.
Исходные README/контракт/публичные tests сохраняются, реализация переносится студентом между лабами через собственные исходники и миграции. Исправление общей спецификации публикуйте отдельным изменением, объясняя влияние на все затронутые лабораторные.
## Проверка этой версии skeleton
На 2026-09-10 выполнены структурные проверки и полная валидация всех семи OpenAPI/JSON Schema, проверка локальных Markdown-ссылок/YAML и декодирование PNG fixture. HTTP-клиенты проверены на временном изолированном тестовом стенде: позитивный smoke 1–7, отрицательные варианты неправильного sender, pagination, ACL, logout, bytes и пустого API; также пути persistence/failover/load и внешнего TLS.
Временный стенд не включён в студенческие каталоги и не является эталонным решением. Реальное приложение, Compose, PostgreSQL/S3/broker и mTLS/OpenBao в skeleton отсутствуют: их работоспособность не заявляется. Docker CLI в среде подготовки не был доступен. Это проверка материалов и тестовых драйверов, не приёмка будущих решений студентов.
+30
View File
@@ -0,0 +1,30 @@
PYTHON ?= python3
BASE_URL ?= http://localhost:8080
CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
.PHONY: help check validate test load test-persistence test-failover
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
check:
$(PYTHON) scripts/check_contract.py
validate:
$(PYTHON) scripts/validate_openapi.py
test:
$(PYTHON) tests/smoke.py --base-url "$(BASE_URL)" $(TLS_ARGS)
load:
$(PYTHON) tests/load.py --base-url "$(BASE_URL)" $(TLS_ARGS)
test-persistence:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable restart hook"; exit 2)
$(PYTHON) tests/resilience.py --mode persistence --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
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)
+105
View File
@@ -0,0 +1,105 @@
# Лабораторная 6. Наблюдаемость: OpenTelemetry и Grafana
Научиться находить причину деградации через метрики, логи и трассы всей системы, включая фоновую обработку.
Это **skeleton**, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; UI не обязателен.
[Карта курса](COURSE.md) · [Процесс fork/PR](CONTRIBUTING.md) · [OpenAPI](contracts/openapi.json) · [Семантика API](contracts/README.md) · [Проверки](tests/README.md) · [Отчёт](REPORT.md) · [Примеры JSON](contracts/examples.json) · [Памятка преподавателю](MAINTAINERS.md)
## Откуда начинаем
Перенесите минимум lab5. Бизнес-API не меняется. Должны оставаться API-реплики, БД, S3, broker и worker.
**Архитектура:** API/worker → OTLP → OTel Collector → хранилища metrics/logs/traces → Grafana; queue context связывает API и worker.
## Что сделать
1. Выберите хранилища: например Prometheus для метрик, Loki для логов, Tempo для трасс. Разрешена другая совместимая комбинация с Grafana; Grafana сама не хранит все три сигнала.
2. Добавьте SDK-инструментацию API и worker и отдельный Collector в общий Compose/Swarm; настройте receivers/processors/exporters и хранение данных.
3. Реализуйте набор сигналов contracts/observability.md и импортируемые dashboard/datasources. Не используйте user_id/chat_id/message_id как labels метрик.
4. Проверьте связь запроса, структурного лога и обработки задания. Секреты, тела сообщений и изображения не должны попадать в telemetry.
5. Создайте нагрузку, внедрите два ограниченных отказа и найдите их причину только с помощью сохранённых наблюдений; приложите доказательства.
## Оценка «3»: работающий минимум
- Весь минимум lab5 работает. Collector, хранилища трёх сигналов и Grafana включены в общий воспроизводимый стенд; конфиги и provisioning лежат в Git, persistent volumes сохраняют нужную историю.
- API и worker отдают OTLP в Collector. В Grafana видны: RPS/errors/duration API, успешные/ошибочные jobs и duration worker; доступны структурные логи и реальные трассы API и worker.
- Есть импортируемый dashboard, а не только screenshot. Сохраняются низкокардинальные атрибуты и идентификаторы trace/span в логах; содержимое сообщений, пароли/токены не экспортируются.
- На контролируемом запросе можно найти trace и связанный лог; на job — worker trace и лог. make test проходит при включённой телеметрии. Объяснено назначение каждого хранилища.
## Оценка «4»: уровень стажёра/джуна
Весь уровень 3 **и все** пункты ниже:
- W3C trace context переносится API → broker → worker; видны producer/consumer spans с корректной связью parent или link. По одному upload найдена цепочка до S3/DB результата, включая retry.
- Dashboard показывает p50/p95/p99, долю ошибок, queue depth/возраст старейшей job, DB pool и saturation worker. Приведены запросы и единицы измерения; percentile вычисляется из histogram, не средних.
- Задан проверяемый SLI/SLO и окно; сохранены alert rules минимум для высокого error rate и растущего queue lag. Alerts проверены искусственным отказом; доставка наружу не нужна, достаточно локального состояния firing/resolved.
- Collector имеет memory limiter/batch и ограниченную буферизацию/поведение при недоступном backend. Остановка telemetry-хранилища не ломает сообщения и не вызывает бесконечный рост RAM. Отчёт содержит разбор двух инцидентов и шаги диагностики.
## Оценка «5»: исследование и доказанный результат
Весь уровень 4 **и один законченный трек на выбор**. Приведите гипотезу, повторяемую методику, результаты и ограничения.
**Трек 1. Цена наблюдаемости.** Сравните telemetry off/on и ≥2 sampling/aggregation настройки при одинаковой нагрузке: latency, CPU/RAM, объём ingest, потери spans. Объясните, какие ошибки и редкие медленные запросы теряются; предложите и проверьте сбалансированную конфигурацию.
**Трек 2. SLO и обнаружение инцидентов.** Обоснуйте SLO для API и времени до ready, реализуйте burn-rate alerts с несколькими окнами, воспроизведите краткий всплеск и длительную деградацию. Измерьте время обнаружения/восстановления, ложные срабатывания и покажите runbook, по которому другой студент находит причину.
## Как начать и проверить
```sh
# Работает прямо в skeleton, Python 3.9+; приложение не запускается:
make check
# После реализации запустите свой сервер/стенд по REPORT.md.
# По умолчанию тест использует http://localhost:8080.
make test
```
`.env.example`, `compose.example.yaml` и `contracts/infrastructure.json` описывают настройки и роли компонентов. **compose.example.yaml — список ролей с пустым services, не запускаемый стенд.** Реализуйте свой `compose.yaml`/`stack.yaml`, закрепите версии образов, заполните локальный `.env` и опишите bootstrap/миграции. Все зависимости поднимаются из этого репозитория; ссылка «у меня БД уже установлена» не заменяет воспроизводимость.
```sh
# Compose-вариант после реализации:
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождитесь /health/ready; затем make test.
# Для Swarm укажите эквивалентные build/push/deploy-команды в REPORT.md.
```
Примеры запросов доступны в `examples/requests.http`, примеры JSON — в `contracts/examples.json`. Для полной проверки схемы (по желанию локально; CI делает её автоматически):
```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
```
Smoke не выставляет оценку автоматически. Проверку сохранности/отказов запускайте явно по [tests/README.md](tests/README.md), остальные доказательства приведите в отчёте.
## Сценарий защиты
1. С нуля поднять стенд, импортировать provisioning без ручного набора dashboard, запустить smoke и нагрузку.
2. Показать свежие метрики, одну трассу и соответствующий структурный лог API и worker; проверить, что это данные своего приложения.
3. Для 4: пройти от upload до worker в одном trace/связанных traces, остановить worker или ограничить DB, увидеть firing и затем resolved.
4. Остановить telemetry backend, проверить сохранение работы API и ограниченное поведение exporter. Для 5: повторить эксперимент.
## Что должно быть в PR
Collector configuration, конфиги backend, Grafana provisioning/dashboards, alert rules по уровню, схема сигналов и отчёт инцидентов.
Заполните `REPORT.md` и [шаблон PR](.github/pull_request_template.md), укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах [объявленных переходов](COURSE.md).
## Вопросы на защите
- Чем лог, метрика и trace отвечают на разные вопросы об одном инциденте?
- Почему chat_id в labels может исчерпать хранилище?
- Как очередь переносит причинную связь между процессами?
- Почему среднее latency не заменяет p99 и почему нельзя усреднять p99 реплик?
## Первичные материалы
- [OTel Collector configuration](https://opentelemetry.io/docs/collector/configuration/)
- [OTel propagation](https://opentelemetry.io/docs/concepts/context-propagation/)
- [W3C Trace Context](https://www.w3.org/TR/trace-context/)
- [Prometheus histograms](https://prometheus.io/docs/practices/histograms/)
- [Grafana provisioning](https://grafana.com/docs/grafana/latest/administration/provisioning/)
+37
View File
@@ -0,0 +1,37 @@
# Отчёт — лабораторная 6
- Автор, группа: Никифорова Екатерина, БВТ2301
- Целевая оценка: **4** (уровни 3 и 4, трек 5 не заявлен)
- Commit/PR: https://gitea.privcloud.tech/eqktrin/mtusi2026lab6 (PR после публикации)
- Источники, библиотеки, помощь ИИ: FastAPI 0.115, Uvicorn 0.30, PostgreSQL 17.6,
Valkey 8.1.3, Silo (`pgsty/silo`), RabbitMQ 3.13-management-alpine, Nginx 1.27,
psycopg 3.2, boto3 1.43.107, Pillow 12.3.0, pika 1.3.2, Argon2id;
OpenTelemetry SDK 1.27.0, `opentelemetry-exporter-otlp-proto-http` 1.27.0,
`opentelemetry-instrumentation-{fastapi,psycopg,botocore,pika,logging}` 0.48b0;
OTel Collector Contrib 0.105.0, Prometheus 2.54.1, Loki 3.1.1, Tempo 2.6.0,
Grafana 11.2.0. Помощь ИИ при написании кода и отчёта.
## Запуск из чистого clone
**Требования:** Docker Engine ≥ 24 с Compose v2, Python ≥ 3.9,
PowerShell (Windows) или sh (Linux), `PYTHONUTF8=1` для публичных тестов
на Windows.
```powershell
git clone https://gitea.privcloud.tech/eqktrin/mtusi2026lab6.git
cd mtusi2026lab6
# секреты: см. README, генерируются локально через init-secrets (PowerShell/sh).
# Проверить наличие secrets/grafana_admin_password, secrets/broker_url,
# secrets/rabbitmq_password и т.д.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# дождаться /health/ready у API (и healthy у rabbitmq, которая при первом
# старте на пустом volume инициализирует mnesia до 60 сек)
Invoke-RestMethod http://localhost:8080/health/ready
# Публичный smoke (lab5-функциональность, кумулятивно)
$env:PYTHONUTF8 = "1"
python tests/smoke.py --base-url http://localhost:8080
# Свои тесты lab6 (нагрузка + 2 инцидента + telemetry-down)
python student-tests/test_lab6.py --base-url http://localhost:8080
View File
+139
View File
@@ -0,0 +1,139 @@
"""lab5: API только принимает staging + пишет job. Ресайз ушёл в worker."""
import hashlib
import io
import logging
import uuid
from PIL import Image, UnidentifiedImageError
from . import config, db, jobs, repo, s3
from .errors import ApiError, bad_request, not_found
log = logging.getLogger("attachments")
ALLOWED_FORMATS = {"PNG": "image/png", "JPEG": "image/jpeg"}
Image.MAX_IMAGE_PIXELS = config.MAX_IMAGE_PIXELS
def validate_filename(filename):
if not isinstance(filename, str) or not (1 <= len(filename) <= 255):
raise bad_request("Некорректное имя файла")
for c in filename:
if c in ("/", "\\", "\x00") or ord(c) < 0x20 or ord(c) == 0x7F:
raise bad_request("Недопустимое имя файла")
return filename
def inspect_image_header(fileobj, total_bytes):
"""Только заголовок: формат и размеры. Полное декодирование — в worker.
load() в API не вызываем — дорого и не нужно для 202.
"""
if total_bytes == 0:
raise bad_request("Пустой файл")
if total_bytes > config.MAX_UPLOAD_BYTES:
raise ApiError(413, "payload_too_large", "Файл больше 10 MiB")
fileobj.seek(0)
try:
with Image.open(fileobj) as img:
fmt = img.format
width, height = img.size
except UnidentifiedImageError:
raise ApiError(415, "unsupported_media_type", "Неизвестный формат изображения")
except Image.DecompressionBombError:
raise ApiError(413, "payload_too_large", "Слишком много пикселей")
finally:
fileobj.seek(0)
if fmt not in ALLOWED_FORMATS:
raise ApiError(415, "unsupported_media_type", "Ожидается PNG или JPEG")
if width <= 0 or height <= 0:
raise ApiError(415, "unsupported_media_type", "Повреждённое изображение")
if width * height > config.MAX_IMAGE_PIXELS:
raise ApiError(413, "payload_too_large", "Слишком много пикселей")
return ALLOWED_FORMATS[fmt]
def upload_to_staging(chat_id, owner_id, filename, fileobj, total_bytes, digest, content_type):
"""POST /attachments: staging в S3 → INSERT attachments(queued) + job + outbox → 202."""
validate_filename(filename)
staging_key = "staging/%s/%s" % (chat_id, uuid.uuid4().hex)
with db.connection() as conn:
if not repo.is_member(conn, chat_id, owner_id):
raise not_found()
# 1. staging в S3 — до INSERT, чтобы не было queued без байтов.
try:
fileobj.seek(0)
s3.put_object(staging_key, fileobj, content_type, content_length=total_bytes)
except Exception as exc:
log.warning("staging PUT failed: %s", type(exc).__name__)
raise ApiError(503, "unavailable", "Хранилище временно недоступно")
# 2. Одна транзакция: attachments + job + outbox.
try:
with db.connection() as conn:
row = repo.insert_attachment_queued(
conn, chat_id, owner_id, filename, content_type,
total_bytes, digest, staging_key)
jobs.create_job_for_attachment(conn, row["id"], config.PIPELINE_VERSION)
except Exception:
# Компенсация: удалить staging, чтобы не оставить orphan.
s3.delete_object(staging_key)
raise
# 3. Публикуем outbox сразу — если брокер жив, latency короче.
# Если упадёт — worker или API-поток подхватит на следующей итерации.
try:
with db.connection() as conn:
jobs.publish_pending_outbox(conn, _broker_publish)
except Exception:
log.warning("inline outbox publish failed, будет повторено")
return row
def _broker_publish(payload):
from . import broker
broker.publish(payload)
def download_original(attachment_id, user_id):
with db.connection() as conn:
row = repo.get_attachment_for_member(conn, attachment_id, user_id)
if row is None:
raise not_found()
if row["status"] in ("queued", "processing"):
raise ApiError(409, "conflict", "Вложение ещё не готово")
if row["status"] == "failed":
raise ApiError(409, "conflict", "Вложение недоступно")
if not row["object_key"]:
raise ApiError(409, "conflict", "Вложение ещё не готово")
try:
body = s3.get_object(row["object_key"])
except Exception as exc:
log.warning("S3 GET original failed: %s", type(exc).__name__)
raise ApiError(503, "unavailable", "Хранилище временно недоступно")
return row, body
def download_variant(attachment_id, user_id, variant_name):
with db.connection() as conn:
row = repo.get_attachment_for_member(conn, attachment_id, user_id)
if row is None:
raise not_found()
if row["status"] in ("queued", "processing"):
raise ApiError(409, "conflict", "Вложение ещё не готово")
if row["status"] == "failed":
raise ApiError(409, "conflict", "Вложение недоступно")
with db.connection() as conn:
v = repo.get_variant(conn, attachment_id, variant_name)
if v is None:
raise not_found()
try:
body = s3.get_object(v["object_key"])
except Exception as exc:
log.warning("S3 GET variant failed: %s", type(exc).__name__)
raise ApiError(503, "unavailable", "Хранилище временно недоступно")
return v, body
+104
View File
@@ -0,0 +1,104 @@
"""RabbitMQ: publish с publisher confirm, consume с ручным ack.
Topology:
exchange: lab5 (direct, durable)
routing_key: attachment.process.v1 → queue attachment.process.v1 (durable)
DLX: lab5.dlx (direct)
routing_key: attachment.failed → queue attachment.failed (durable)
"""
import json
import logging
import threading
import time
import pika
from . import config
log = logging.getLogger("broker")
EXCHANGE = "lab5"
DLX = "lab5.dlx"
QUEUE = "attachment.process.v1"
FAILED_QUEUE = "attachment.failed"
_lock = threading.Lock()
_channel = None
def _connect():
params = pika.URLParameters(config.BROKER_URL)
params.heartbeat = 30
params.blocked_connection_timeout = 30
return pika.BlockingConnection(params)
def get_channel():
"""Один канал на процесс; worker также использует для consume."""
global _channel
if _channel is None or _channel.is_closed:
with _lock:
if _channel is None or _channel.is_closed:
conn = _connect()
ch = conn.channel()
ch.exchange_declare(EXCHANGE, exchange_type="direct", durable=True)
ch.exchange_declare(DLX, exchange_type="direct", durable=True)
ch.queue_declare(
QUEUE, durable=True,
arguments={"x-dead-letter-exchange": DLX,
"x-dead-letter-routing-key": "attachment.failed"})
ch.queue_declare(FAILED_QUEUE, durable=True)
ch.queue_bind(QUEUE, EXCHANGE, routing_key=QUEUE)
ch.queue_bind(FAILED_QUEUE, DLX, routing_key="attachment.failed")
_channel = ch
return _channel
def publish(job_payload: dict) -> None:
"""Publish с publisher confirm + W3C trace context в headers.
Заголовки `traceparent`/`tracestate` создаёт OTel propagator из текущего span.
Worker их извлечёт и создаст child span — сквозная трасса API → broker → worker.
"""
from . import telemetry
ch = get_channel()
ch.confirm_delivery()
body = json.dumps(job_payload, separators=(",", ":")).encode("utf-8")
headers = {}
telemetry.inject_headers(headers)
ch.basic_publish(
exchange=EXCHANGE,
routing_key=QUEUE,
body=body,
properties=pika.BasicProperties(
content_type="application/json",
delivery_mode=2,
message_id=job_payload["job_id"],
headers=headers or None,
),
mandatory=True,
)
def declare_only() -> None:
"""Идемпотентное создание topology (при старте API и worker)."""
get_channel()
def wait_ready(timeout=30) -> bool:
"""Проверка брокера для /health/ready."""
deadline = time.monotonic() + timeout
last = None
while time.monotonic() < deadline:
try:
conn = _connect()
try:
conn.channel().queue_declare(QUEUE, passive=True)
return True
finally:
conn.close()
except Exception as exc:
last = exc
time.sleep(0.5)
log.warning("broker not ready: %s", type(last).__name__ if last else "timeout")
return False
+52
View File
@@ -0,0 +1,52 @@
"""Тонкая обёртка над Redis/Valkey."""
import logging
import threading
import time
import redis
from . import config
log = logging.getLogger("cache")
_client = None
_down_until = 0.0
_lock = threading.Lock()
def _get_client():
global _client
if not config.CACHE_URL:
return None
if _client is None:
with _lock:
if _client is None:
_client = redis.Redis.from_url(
config.CACHE_URL, socket_timeout=config.CACHE_TIMEOUT,
socket_connect_timeout=config.CACHE_TIMEOUT, max_connections=20,
decode_responses=True, retry_on_timeout=False)
return _client
def _call(fn):
global _down_until
client = _get_client()
if client is None or time.monotonic() < _down_until:
return None
try:
return fn(client)
except redis.RedisError as exc:
_down_until = time.monotonic() + config.CACHE_BACKOFF
log.warning("cache unavailable (%s); bypassing for %.0fs", type(exc).__name__, config.CACHE_BACKOFF)
return None
def get(key):
return _call(lambda c: c.get(key))
def set_if_absent(key, value, ttl_ms):
return _call(lambda c: c.set(key, value, nx=True, px=ttl_ms))
def set_always(key, value, ttl_ms):
return _call(lambda c: c.set(key, value, px=ttl_ms))
+72
View File
@@ -0,0 +1,72 @@
"""Конфигурация из переменных окружения. Секреты читаются из файлов (*_FILE)."""
import os
import socket
from pathlib import Path
def _read(name):
path = os.environ.get(name + "_FILE")
if path:
return Path(path).read_text(encoding="utf-8").strip()
return os.environ.get(name) or None
def _int(name, default, low, high):
value = int(os.environ.get(name, default))
if not low <= value <= high:
raise ValueError("%s must be in %d..%d" % (name, low, high))
return value
APP_HOST = os.environ.get("APP_HOST", "0.0.0.0")
APP_PORT = _int("APP_PORT", 8080, 1, 65535)
APP_ENV = os.environ.get("APP_ENV", "lab")
SESSION_TTL_SECONDS = _int("SESSION_TTL_SECONDS", 3600, 1, 30 * 24 * 3600)
SESSION_STORE = os.environ.get("SESSION_STORE", "postgres+cache")
SESSION_CACHE_TTL_SECONDS = _int("SESSION_CACHE_TTL_SECONDS", 60, 1, 3600)
DATABASE_URL = _read("DATABASE_URL")
CACHE_URL = _read("CACHE_URL") if SESSION_STORE == "postgres+cache" else None
DB_POOL_MIN = _int("DB_POOL_MIN", 1, 0, 50)
DB_POOL_MAX = _int("DB_POOL_MAX", 16, 1, 50)
DB_POOL_TIMEOUT = float(os.environ.get("DB_POOL_TIMEOUT", "3"))
DB_STATEMENT_TIMEOUT_MS = _int("DB_STATEMENT_TIMEOUT_MS", 5000, 100, 60000)
CACHE_TIMEOUT = float(os.environ.get("CACHE_TIMEOUT", "0.25"))
CACHE_BACKOFF = float(os.environ.get("CACHE_BACKOFF", "2"))
ARGON2_MEMORY_KIB = _int("ARGON2_MEMORY_KIB", 19456, 8, 1048576)
ARGON2_TIME_COST = _int("ARGON2_TIME_COST", 2, 1, 10)
MAX_BODY_BYTES = 64 * 1024
THREAD_LIMIT = _int("THREAD_LIMIT", 24, 1, 200)
HASH_CONCURRENCY = _int("HASH_CONCURRENCY", 4, 1, 32)
# lab3
INSTANCE_ID = os.environ.get("INSTANCE_ID") or socket.gethostname()
IDEMPOTENCY_TTL_SECONDS = _int("IDEMPOTENCY_TTL_SECONDS", 86400, 60, 86400 * 7)
# lab4: S3
S3_ENDPOINT = os.environ.get("S3_ENDPOINT", "http://minio:9000")
S3_REGION = os.environ.get("S3_REGION", "us-east-1")
S3_BUCKET = os.environ.get("S3_BUCKET", "messenger-attachments")
S3_ACCESS_KEY_ID = _read("S3_ACCESS_KEY_ID")
S3_SECRET_ACCESS_KEY = _read("S3_SECRET_ACCESS_KEY")
S3_CONNECT_TIMEOUT = float(os.environ.get("S3_CONNECT_TIMEOUT", "3"))
S3_READ_TIMEOUT = float(os.environ.get("S3_READ_TIMEOUT", "30"))
MAX_UPLOAD_BYTES = _int("MAX_UPLOAD_BYTES", 10485760, 1, 10485760)
MAX_IMAGE_PIXELS = _int("MAX_IMAGE_PIXELS", 40000000, 1, 40000000)
S3_ORPHAN_GRACE_SECONDS = _int("S3_ORPHAN_GRACE_SECONDS", 3600, 60, 7 * 24 * 3600)
UPLOAD_CHUNK_BYTES = _int("UPLOAD_CHUNK_BYTES", 256 * 1024, 4096, 4 * 1024 * 1024)
UPLOAD_READ_TIMEOUT_SECONDS = float(os.environ.get("UPLOAD_READ_TIMEOUT", "30"))
# lab5: broker / worker / jobs
BROKER_URL = _read("BROKER_URL")
WORKER_CONCURRENCY = _int("WORKER_CONCURRENCY", 2, 1, 32)
JOB_MAX_ATTEMPTS = _int("JOB_MAX_ATTEMPTS", 5, 1, 100)
JOB_TIMEOUT_SECONDS = _int("JOB_TIMEOUT_SECONDS", 60, 10, 3600)
STAGING_RETENTION_SECONDS = _int("STAGING_RETENTION_SECONDS", 86400, 60, 30 * 24 * 3600)
PIPELINE_VERSION = _int("PIPELINE_VERSION", 1, 1, 100)
OTEL_ENABLED = os.environ.get("OTEL_SDK_DISABLED", "false").lower() != "true"
OTEL_SERVICE_VERSION = os.environ.get("OTEL_SERVICE_VERSION", "1.6.0")
+27
View File
@@ -0,0 +1,27 @@
"""Непрозрачный keyset-курсор (created_at, id)."""
import base64
import json
import uuid
from datetime import datetime, timezone
from .errors import bad_request
def encode(kind, scope, created_at, row_id):
payload = {"k": kind, "s": str(scope), "t": created_at.astimezone(timezone.utc).isoformat(), "i": str(row_id)}
return base64.urlsafe_b64encode(json.dumps(payload, separators=(",", ":")).encode()).rstrip(b"=").decode()
def decode(value, kind, scope):
if not value:
raise bad_request("Некорректный cursor")
try:
raw = base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
payload = json.loads(raw.decode("utf-8"))
created_at = datetime.fromisoformat(payload["t"])
row_id = uuid.UUID(payload["i"])
if payload["k"] != kind or payload["s"] != str(scope) or created_at.tzinfo is None:
raise ValueError("scope mismatch")
return created_at, row_id
except (ValueError, KeyError, TypeError, UnicodeDecodeError):
raise bad_request("Некорректный cursor")
+53
View File
@@ -0,0 +1,53 @@
"""Пул соединений PostgreSQL."""
import threading
import psycopg
from psycopg.rows import dict_row
from psycopg_pool import ConnectionPool, PoolClosed, PoolTimeout
from . import config
TRANSIENT = (psycopg.OperationalError, PoolTimeout, PoolClosed, psycopg.errors.QueryCanceled,
psycopg.errors.LockNotAvailable)
_pool = None
_lock = threading.Lock()
def get_pool():
global _pool
if _pool is None:
with _lock:
if _pool is None:
if not config.DATABASE_URL:
raise RuntimeError("DATABASE_URL(_FILE) is not configured")
options = ("-c statement_timeout=%d -c lock_timeout=3000 "
"-c idle_in_transaction_session_timeout=10000" % config.DB_STATEMENT_TIMEOUT_MS)
pool = ConnectionPool(
config.DATABASE_URL,
min_size=config.DB_POOL_MIN, max_size=config.DB_POOL_MAX,
timeout=config.DB_POOL_TIMEOUT, max_lifetime=1800, max_idle=300,
reconnect_timeout=5,
check=ConnectionPool.check_connection,
kwargs={"row_factory": dict_row, "connect_timeout": 3, "options": options,
"application_name": "messenger-api"},
open=False)
pool.open(wait=False)
_pool = pool
return _pool
def connection(timeout=None):
return get_pool().connection(timeout=timeout)
def ping():
with connection(timeout=1.5) as conn:
conn.execute("SELECT 1")
def close():
global _pool
if _pool is not None:
_pool.close(timeout=5)
_pool = None
+20
View File
@@ -0,0 +1,20 @@
class ApiError(Exception):
def __init__(self, status, code, message, headers=None):
super().__init__(message)
self.status, self.code, self.message, self.headers = status, code, message, headers or {}
BASIC_CHALLENGE = {"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"'}
BEARER_CHALLENGE = {"WWW-Authenticate": 'Bearer realm="messenger"'}
def bad_request(message="Некорректный запрос"):
return ApiError(400, "invalid_request", message)
def unauthorized(challenge):
return ApiError(401, "unauthorized", "Требуется аутентификация", challenge)
def not_found():
return ApiError(404, "not_found", "Объект не найден")
+66
View File
@@ -0,0 +1,66 @@
"""Логика идемпотентности для POST запросов."""
import hashlib
import json
import re
from .errors import ApiError, bad_request
# Контракт: ASCII [A-Za-z0-9._:-]{1,128}
_IDEM_KEY_RE = re.compile(r"[A-Za-z0-9._:-]{1,128}")
def get_request_hash(data: dict) -> str:
"""Хеш тела, независимый от порядка ключей.
Отсутствующий attachment_ids семантически равен [] — нормализуем,
иначе {"text":"x"} и {"text":"x","attachment_ids":[]} дают разные хеши.
"""
normalized = dict(data)
normalized.setdefault("attachment_ids", [])
return hashlib.sha256(json.dumps(normalized, sort_keys=True).encode("utf-8")).hexdigest()
def check_and_lock(conn, user_id: str, method: str, path: str, key: str, req_hash: str):
if not key:
raise bad_request("Missing Idempotency-Key")
if not _IDEM_KEY_RE.fullmatch(key):
raise bad_request("Invalid Idempotency-Key format")
lock_id = f"{user_id}:{method}:{path}:{key}"
conn.execute("SELECT pg_advisory_xact_lock(hashtext(%s))", (lock_id,))
row = conn.execute("""
SELECT request_hash, status_code, response_body
FROM idempotency_keys
WHERE user_id = %s AND method = %s AND path = %s AND key = %s
""", (user_id, method, path, key)).fetchone()
if row:
if row["request_hash"] != req_hash:
raise ApiError(409, "conflict", "Idempotency-Key conflict: body differs")
if row["status_code"] is not None and row["response_body"] is not None:
return False, json.loads(row["response_body"])
return True, None
return True, None
def save_result(conn, user_id, method, path, key, req_hash, status_code, response_body):
conn.execute("""
INSERT INTO idempotency_keys (user_id, method, path, key, request_hash, status_code, response_body)
VALUES (%s, %s, %s, %s, %s, %s, %s)
ON CONFLICT (user_id, method, path, key) DO UPDATE
SET status_code = EXCLUDED.status_code, response_body = EXCLUDED.response_body
""", (user_id, method, path, key, req_hash, status_code, json.dumps(response_body)))
def cleanup(conn, ttl_seconds: int):
conn.execute("""
DELETE FROM idempotency_keys
WHERE (user_id, method, path, key) IN (
SELECT user_id, method, path, key
FROM idempotency_keys
WHERE created_at < now() - make_interval(secs => %s)
LIMIT 100
)
""", (ttl_seconds,))
+170
View File
@@ -0,0 +1,170 @@
"""Репозиторий jobs и outbox + реестр failed + replay."""
import json
import logging
import uuid
from datetime import datetime, timezone
from . import config, repo
log = logging.getLogger("jobs")
# --- создание задания (API) ----------------------------------------------
def create_job_for_attachment(conn, attachment_id: uuid.UUID, pipeline_version: int = 1) -> dict:
"""INSERT job + INSERT outbox в одной транзакции.
Вызывается API после того, как staging-объект сохранён и строка attachments
вставлена со status='queued' и staging_key.
"""
job_id = uuid.uuid4()
job = conn.execute(
"""INSERT INTO jobs (job_id, attachment_id, pipeline_version, status, max_attempts)
VALUES (%s, %s, %s, 'queued', %s)
ON CONFLICT (attachment_id, pipeline_version) DO NOTHING
RETURNING job_id, attachment_id, pipeline_version, attempt, type""",
(job_id, attachment_id, pipeline_version, config.JOB_MAX_ATTEMPTS)).fetchone()
if job is None:
# Уже есть — идемпотентно, но outbox тоже не создаём.
return None
payload = {
"schema_version": 1,
"job_id": str(job["job_id"]),
"type": job["type"],
"attachment_id": str(job["attachment_id"]),
"pipeline_version": job["pipeline_version"],
"attempt": 1,
"created_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ"),
}
# INSERT без RETURNING — НЕ вызываем .fetchone().
conn.execute(
"""INSERT INTO outbox (topic, payload) VALUES (%s, %s::jsonb)""",
(job["type"], json.dumps(payload)))
return payload
# --- outbox publisher -----------------------------------------------------
def publish_pending_outbox(conn, publish_fn) -> int:
"""Публикует неопубликованные outbox-записи. Возвращает число опубликованных.
Ошибки не роняют цикл — запись помечается attempts+1 и last_error.
"""
rows = conn.execute(
"""SELECT id, topic, payload FROM outbox
WHERE published_at IS NULL AND attempts < 20
ORDER BY id LIMIT 50 FOR UPDATE SKIP LOCKED""").fetchall()
published = 0
for row in rows:
try:
publish_fn(row["payload"] if isinstance(row["payload"], dict) else json.loads(row["payload"]))
except Exception as exc:
conn.execute(
"""UPDATE outbox SET attempts = attempts + 1, last_error = %s WHERE id = %s""",
(type(exc).__name__, row["id"]))
log.warning("outbox %s publish failed: %s", row["id"], type(exc).__name__)
break # стоп — брокер, возможно, недоступен
conn.execute(
"""UPDATE outbox SET published_at = clock_timestamp() WHERE id = %s""",
(row["id"],))
published += 1
return published
# --- worker: claim, processing, retry, failed ----------------------------
def claim_job(conn, job_id: uuid.UUID) -> dict:
"""Атомарно переводит queued → processing, выдаёт lease.
Возвращает строку job, если claim успешен (attempt++). Иначе None —
значит, задачу уже взял другой worker или она в другом статусе.
"""
return conn.execute(
"""UPDATE jobs
SET status = 'processing',
attempt = attempt + 1,
lease_until = clock_timestamp() + make_interval(secs => %s),
updated_at = clock_timestamp()
WHERE job_id = %s
AND status = 'queued'
AND (next_attempt_at IS NULL OR next_attempt_at <= clock_timestamp())
RETURNING job_id, attachment_id, pipeline_version, attempt, max_attempts, type""",
(config.JOB_TIMEOUT_SECONDS, job_id)).fetchone()
def mark_ready(conn, job_id: uuid.UUID) -> None:
conn.execute(
"""UPDATE jobs SET status = 'ready', error_code = NULL, lease_until = NULL,
updated_at = clock_timestamp()
WHERE job_id = %s""", (job_id,))
def mark_retry(conn, job_id: uuid.UUID, error_code: str, backoff_seconds: float) -> None:
conn.execute(
"""UPDATE jobs
SET status = 'queued',
lease_until = NULL,
next_attempt_at = clock_timestamp() + make_interval(secs => %s),
error_code = %s,
updated_at = clock_timestamp()
WHERE job_id = %s""",
(backoff_seconds, error_code, job_id))
def mark_failed(conn, job_id: uuid.UUID, error_code: str) -> None:
conn.execute(
"""UPDATE jobs SET status = 'failed', error_code = %s, lease_until = NULL,
updated_at = clock_timestamp()
WHERE job_id = %s""", (error_code, job_id))
def find_expired_leases(conn, limit: int = 50):
"""Возвращает job, у которых истёк lease — зависший processing."""
return conn.execute(
"""SELECT job_id, attachment_id, attempt, max_attempts
FROM jobs
WHERE status = 'processing' AND lease_until < clock_timestamp()
ORDER BY lease_until LIMIT %s
FOR UPDATE SKIP LOCKED""", (limit,)).fetchall()
def requeue_expired(conn, row) -> str:
"""Expired lease: attempt уже инкрементирован при claim. Если попытки исчерпаны — failed,
иначе — queued с backoff."""
if row["attempt"] >= row["max_attempts"]:
mark_failed(conn, row["job_id"], "worker_timeout")
return "failed"
backoff = min(60.0, 2.0 ** row["attempt"]) * (0.5 + 0.5 * (uuid.uuid4().int & 0xFFFF) / 0xFFFF)
mark_retry(conn, row["job_id"], "worker_timeout", backoff)
return "queued"
# --- operator replay ------------------------------------------------------
def replay_failed(conn, job_id: uuid.UUID) -> dict:
"""Операторский replay: failed → queued, attempt=0, INSERT outbox.
Не перезапускает успешные задачи. Ошибки не глушит.
"""
row = conn.execute(
"""UPDATE jobs
SET status = 'queued', attempt = 0, error_code = NULL,
lease_until = NULL, next_attempt_at = NULL, updated_at = clock_timestamp()
WHERE job_id = %s AND status = 'failed'
RETURNING job_id, attachment_id, pipeline_version, type""",
(job_id,)).fetchone()
if row is None:
return None
payload = {
"schema_version": 1,
"job_id": str(row["job_id"]),
"type": row["type"],
"attachment_id": str(row["attachment_id"]),
"pipeline_version": row["pipeline_version"],
"attempt": 1,
"created_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ"),
}
conn.execute("INSERT INTO outbox (topic, payload) VALUES (%s, %s::jsonb)",
(row["type"], json.dumps(payload)))
return payload
+61
View File
@@ -0,0 +1,61 @@
"""Версионируемые миграции."""
import hashlib
import logging
import sys
import time
from pathlib import Path
import psycopg
from . import config
LOCK_ID = 727_002_001
log = logging.getLogger("migrate")
def migration_files():
return sorted((Path(__file__).parent / "migrations").glob("[0-9][0-9][0-9][0-9]_*.sql"))
def apply_all(conninfo):
files = migration_files()
with psycopg.connect(conninfo, connect_timeout=3) as conn:
conn.execute("SELECT pg_advisory_xact_lock(%s)", (LOCK_ID,))
conn.execute("""CREATE TABLE IF NOT EXISTS schema_migrations (
version text PRIMARY KEY,
checksum text NOT NULL,
applied_at timestamptz NOT NULL DEFAULT now())""")
applied = dict(conn.execute("SELECT version, checksum FROM schema_migrations").fetchall())
done = []
for path in files:
sql = path.read_text(encoding="utf-8")
checksum = hashlib.sha256(sql.encode()).hexdigest()
if path.stem in applied:
if applied[path.stem] != checksum:
raise RuntimeError("migration %s was modified after being applied" % path.stem)
continue
conn.execute(sql)
conn.execute("INSERT INTO schema_migrations (version, checksum) VALUES (%s, %s)", (path.stem, checksum))
done.append(path.stem)
return done
def main():
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(message)s")
if not config.DATABASE_URL:
sys.exit("DATABASE_URL(_FILE) is not configured")
deadline = time.monotonic() + 60
while True:
try:
done = apply_all(config.DATABASE_URL)
break
except psycopg.OperationalError as exc:
if time.monotonic() > deadline:
raise
log.info("database not ready (%s), retrying", type(exc).__name__)
time.sleep(1)
log.info("applied: %s", ", ".join(done) if done else "nothing to do (schema is up to date)")
if __name__ == "__main__":
main()
+39
View File
@@ -0,0 +1,39 @@
CREATE TABLE users (
id uuid PRIMARY KEY,
username text NOT NULL,
display_name text NOT NULL,
password_hash text NOT NULL,
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
CONSTRAINT users_username_key UNIQUE (username),
CONSTRAINT users_username_format CHECK (username ~ '^[a-z0-9_]{3,32}$'),
CONSTRAINT users_display_name_length CHECK (char_length(display_name) BETWEEN 1 AND 100)
);
CREATE TABLE chats (
id uuid PRIMARY KEY,
title text NOT NULL,
created_by uuid NOT NULL REFERENCES users (id),
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
CONSTRAINT chats_title_length CHECK (char_length(title) BETWEEN 1 AND 100)
);
CREATE INDEX chats_created_at_id_idx ON chats (created_at, id);
CREATE TABLE chat_members (
chat_id uuid NOT NULL REFERENCES chats (id) ON DELETE CASCADE,
user_id uuid NOT NULL REFERENCES users (id),
added_at timestamptz NOT NULL DEFAULT clock_timestamp(),
PRIMARY KEY (chat_id, user_id)
);
CREATE INDEX chat_members_user_chat_idx ON chat_members (user_id, chat_id);
CREATE TABLE messages (
id uuid PRIMARY KEY,
chat_id uuid NOT NULL,
sender_id uuid NOT NULL,
text text NOT NULL,
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
CONSTRAINT messages_text_length CHECK (char_length(text) BETWEEN 1 AND 4000),
CONSTRAINT messages_sender_is_member FOREIGN KEY (chat_id, sender_id)
REFERENCES chat_members (chat_id, user_id)
);
CREATE INDEX messages_chat_created_id_idx ON messages (chat_id, created_at, id);
+10
View File
@@ -0,0 +1,10 @@
CREATE TABLE sessions (
token_hash bytea PRIMARY KEY,
user_id uuid NOT NULL REFERENCES users (id),
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
expires_at timestamptz NOT NULL,
CONSTRAINT sessions_hash_length CHECK (octet_length(token_hash) = 32),
CONSTRAINT sessions_expiry_after_creation CHECK (expires_at > created_at)
);
CREATE INDEX sessions_expires_at_idx ON sessions (expires_at);
CREATE INDEX sessions_user_idx ON sessions (user_id);
+13
View File
@@ -0,0 +1,13 @@
CREATE TABLE idempotency_keys (
user_id uuid NOT NULL REFERENCES users(id),
method text NOT NULL,
path text NOT NULL,
key text NOT NULL,
request_hash text NOT NULL,
status_code int,
response_body text,
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
PRIMARY KEY (user_id, method, path, key)
);
CREATE INDEX idempotency_keys_created_at_idx ON idempotency_keys (created_at);
+36
View File
@@ -0,0 +1,36 @@
CREATE TABLE attachments (
id uuid PRIMARY KEY,
chat_id uuid NOT NULL REFERENCES chats (id) ON DELETE CASCADE,
owner_id uuid NOT NULL REFERENCES users (id),
filename text NOT NULL,
content_type text NOT NULL,
size_bytes bigint NOT NULL,
sha256 char(64) NOT NULL,
object_key text NOT NULL,
status text NOT NULL,
error_code text,
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
updated_at timestamptz NOT NULL DEFAULT clock_timestamp(),
CONSTRAINT attachments_filename_length CHECK (char_length(filename) BETWEEN 1 AND 255),
CONSTRAINT attachments_content_type CHECK (content_type IN ('image/png', 'image/jpeg')),
CONSTRAINT attachments_size_positive CHECK (size_bytes > 0 AND size_bytes <= 10485760),
CONSTRAINT attachments_sha256_format CHECK (sha256 ~ '^[a-f0-9]{64}$'),
CONSTRAINT attachments_object_key_unique UNIQUE (object_key),
CONSTRAINT attachments_status CHECK (status IN ('pending', 'ready', 'failed')),
CONSTRAINT attachments_error_code CHECK (
(status = 'ready' AND error_code IS NULL) OR
(status = 'failed' AND error_code IS NOT NULL) OR
(status = 'pending')
)
);
CREATE INDEX attachments_chat_created_idx ON attachments (chat_id, created_at);
CREATE INDEX attachments_pending_idx ON attachments (created_at) WHERE status = 'pending';
CREATE TABLE message_attachments (
message_id uuid NOT NULL REFERENCES messages (id) ON DELETE CASCADE,
attachment_id uuid NOT NULL REFERENCES attachments (id) ON DELETE RESTRICT,
position int NOT NULL,
PRIMARY KEY (message_id, attachment_id),
CONSTRAINT message_attachments_position CHECK (position >= 0)
);
CREATE INDEX message_attachments_attachment_idx ON message_attachments (attachment_id);
@@ -0,0 +1,5 @@
-- lab4: разрешаем пустой text, если есть вложения. Проверка «text или вложения»
-- делается в приложении, а БД гарантирует только верхнюю границу.
ALTER TABLE messages DROP CONSTRAINT messages_text_length;
ALTER TABLE messages ADD CONSTRAINT messages_text_length
CHECK (char_length(text) BETWEEN 0 AND 4000);
@@ -0,0 +1,75 @@
-- lab5: статусы queued/processing, variants, jobs, outbox, staging_key.
-- 1. Расширяем статусы attachment (было pending/ready/failed).
ALTER TABLE attachments DROP CONSTRAINT attachments_status;
ALTER TABLE attachments ADD CONSTRAINT attachments_status
CHECK (status IN ('queued', 'processing', 'ready', 'failed'));
-- 2. Существующие pending → queued (совместимость с lab4).
UPDATE attachments SET status = 'queued' WHERE status = 'pending';
-- 3. Разделяем staging и финальный объект.
-- object_key = финальный путь (ставит worker после копирования).
-- staging_key = куда API положил байты при upload.
ALTER TABLE attachments ADD COLUMN staging_key text;
ALTER TABLE attachments ALTER COLUMN object_key DROP NOT NULL;
ALTER TABLE attachments ADD CONSTRAINT attachments_ready_has_object
CHECK (status <> 'ready' OR object_key IS NOT NULL);
-- 4. Варианты (thumbnail, crop, optimized).
CREATE TABLE attachment_variants (
attachment_id uuid NOT NULL REFERENCES attachments (id) ON DELETE CASCADE,
name text NOT NULL,
object_key text NOT NULL,
content_type text NOT NULL,
size_bytes bigint NOT NULL,
width int NOT NULL,
height int NOT NULL,
sha256 char(64) NOT NULL,
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
PRIMARY KEY (attachment_id, name),
CONSTRAINT attachment_variants_name CHECK (name IN ('thumbnail', 'crop', 'optimized')),
CONSTRAINT attachment_variants_type CHECK (content_type IN ('image/jpeg', 'image/png', 'image/webp')),
CONSTRAINT attachment_variants_size CHECK (size_bytes > 0),
CONSTRAINT attachment_variants_dims CHECK (width > 0 AND height > 0),
CONSTRAINT attachment_variants_sha CHECK (sha256 ~ '^[a-f0-9]{64}$')
);
-- 5. Jobs: одна логическая работа на (attachment_id, pipeline_version).
-- job_id — стабильный идентификатор; attempt растёт при retry.
-- lease_until защищает от двух воркеров на одной задаче.
CREATE TABLE jobs (
job_id uuid PRIMARY KEY,
attachment_id uuid NOT NULL REFERENCES attachments (id) ON DELETE CASCADE,
pipeline_version int NOT NULL DEFAULT 1,
type text NOT NULL DEFAULT 'attachment.process.v1',
status text NOT NULL DEFAULT 'queued',
attempt int NOT NULL DEFAULT 0,
max_attempts int NOT NULL DEFAULT 5,
lease_until timestamptz,
next_attempt_at timestamptz,
error_code text,
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
updated_at timestamptz NOT NULL DEFAULT clock_timestamp(),
CONSTRAINT jobs_status CHECK (status IN ('queued', 'processing', 'ready', 'failed')),
CONSTRAINT jobs_type CHECK (type = 'attachment.process.v1'),
CONSTRAINT jobs_attempt CHECK (attempt >= 0),
CONSTRAINT jobs_max_att CHECK (max_attempts BETWEEN 1 AND 100),
CONSTRAINT jobs_pipeline CHECK (pipeline_version >= 1),
UNIQUE (attachment_id, pipeline_version)
);
CREATE INDEX jobs_claim_idx ON jobs (status, next_attempt_at) WHERE status = 'queued';
CREATE INDEX jobs_lease_idx ON jobs (lease_until) WHERE status = 'processing';
-- 6. Transactional outbox: INSERT в той же транзакции, что и jobs.
-- Отдельный publisher читает непубликованные и подтверждает.
CREATE TABLE outbox (
id bigserial PRIMARY KEY,
topic text NOT NULL,
payload jsonb NOT NULL,
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
published_at timestamptz,
attempts int NOT NULL DEFAULT 0,
last_error text
);
CREATE INDEX outbox_pending_idx ON outbox (id) WHERE published_at IS NULL;
@@ -0,0 +1,6 @@
-- lab5: constraint attachments_error_code должен знать про queued/processing.
-- Идемпотентно: DROP IF EXISTS — можно применять повторно.
ALTER TABLE attachments DROP CONSTRAINT IF EXISTS attachments_error_code;
ALTER TABLE attachments ADD CONSTRAINT attachments_error_code CHECK (
(status = 'failed') = (error_code IS NOT NULL)
);
+99
View File
@@ -0,0 +1,99 @@
"""Обработка изображений: thumbnail 256×256, crop 128×128, optimized WebP."""
import hashlib
import io
import logging
from PIL import Image, ImageOps
from . import config
log = logging.getLogger("pipeline")
PIPELINE_VERSION = 1
Image.MAX_IMAGE_PIXELS = config.MAX_IMAGE_PIXELS
THUMB_MAX = (256, 256)
CROP_SIDE = 128
OPT_MAX = (1280, 1280)
OPT_QUALITY = 82
JPEG_QUALITY = 85
def _open_normalized(data: bytes) -> Image.Image:
"""Открывает, применяет EXIF orientation, приводит к RGB с белым фоном для alpha."""
img = Image.open(io.BytesIO(data))
img = ImageOps.exif_transpose(img)
if img.mode in ("RGBA", "LA") or (img.mode == "P" and "transparency" in img.info):
background = Image.new("RGB", img.size, (255, 255, 255))
img_rgba = img.convert("RGBA")
background.paste(img_rgba, mask=img_rgba.split()[-1])
img = background
elif img.mode != "RGB":
img = img.convert("RGB")
img.load()
return img
def _encode_jpeg(img: Image.Image) -> bytes:
buf = io.BytesIO()
img.save(buf, format="JPEG", quality=JPEG_QUALITY, optimize=True, progressive=True)
return buf.getvalue()
def _encode_webp(img: Image.Image) -> bytes:
buf = io.BytesIO()
img.save(buf, format="WEBP", quality=OPT_QUALITY, method=4)
return buf.getvalue()
def _make_thumbnail(img: Image.Image):
thumb = img.copy()
thumb.thumbnail(THUMB_MAX, Image.Resampling.LANCZOS)
if thumb.width < 1 or thumb.height < 1:
raise ValueError("thumbnail degenerate")
return _encode_jpeg(thumb), thumb.width, thumb.height
def _make_crop(img: Image.Image):
side = CROP_SIDE
# ImageOps.fit центрирует и ресайзит; для маленьких исходников увеличивает — разрешено.
crop = ImageOps.fit(img, (side, side), Image.Resampling.LANCZOS)
return _encode_jpeg(crop), side, side
def _make_optimized(img: Image.Image):
opt = img.copy()
opt.thumbnail(OPT_MAX, Image.Resampling.LANCZOS)
return _encode_webp(opt), opt.width, opt.height
def process(data: bytes):
"""Возвращает список вариантов: [{name, content_type, bytes, width, height, sha256, size_bytes}]."""
img = _open_normalized(data)
if img.width * img.height > config.MAX_IMAGE_PIXELS:
raise ValueError("too many pixels")
results = []
thumb_bytes, tw, th = _make_thumbnail(img)
results.append({
"name": "thumbnail", "content_type": "image/jpeg",
"bytes": thumb_bytes, "width": tw, "height": th,
"sha256": hashlib.sha256(thumb_bytes).hexdigest(), "size_bytes": len(thumb_bytes),
})
crop_bytes, cw, ch = _make_crop(img)
results.append({
"name": "crop", "content_type": "image/jpeg",
"bytes": crop_bytes, "width": cw, "height": ch,
"sha256": hashlib.sha256(crop_bytes).hexdigest(), "size_bytes": len(crop_bytes),
})
opt_bytes, ow, oh = _make_optimized(img)
results.append({
"name": "optimized", "content_type": "image/webp",
"bytes": opt_bytes, "width": ow, "height": oh,
"sha256": hashlib.sha256(opt_bytes).hexdigest(), "size_bytes": len(opt_bytes),
})
return results
+205
View File
@@ -0,0 +1,205 @@
"""Доступ к данным. Добавлены queued-статусы, variants, json с variants."""
import uuid
from . import cursor
from .errors import bad_request, not_found
from .sessions import fmt_ts
# ---------- пользователи / чаты (без изменений) ----------
def username_exists(conn, username):
return conn.execute("SELECT 1 FROM users WHERE username = %s", (username,)).fetchone() is not None
def insert_user(conn, username, display_name, password_hash):
return conn.execute(
"""INSERT INTO users (id, username, display_name, password_hash) VALUES (%s, %s, %s, %s)
RETURNING id, username, display_name, created_at""",
(uuid.uuid4(), username, display_name, password_hash)).fetchone()
def user_for_login(conn, username):
return conn.execute(
"SELECT id, username, display_name, password_hash, created_at FROM users WHERE username = %s",
(username,)).fetchone()
def update_password_hash(conn, user_id, new_hash):
conn.execute("UPDATE users SET password_hash = %s WHERE id = %s", (new_hash, user_id))
def chat_json(row):
return {"id": str(row["id"]), "title": row["title"],
"member_ids": [str(x) for x in row["member_ids"]],
"created_at": fmt_ts(row["created_at"])}
def create_chat(conn, creator_id, title, member_ids, check_members=True):
if check_members:
found = conn.execute("SELECT count(*) AS n FROM users WHERE id = ANY(%s)",
(member_ids,)).fetchone()["n"]
if found != len(member_ids):
raise bad_request("Неизвестный участник чата")
chat = conn.execute(
"INSERT INTO chats (id, title, created_by) VALUES (%s, %s, %s) RETURNING id, title, created_at",
(uuid.uuid4(), title, creator_id)).fetchone()
conn.execute("INSERT INTO chat_members (chat_id, user_id) SELECT %s, unnest(%s::uuid[])",
(chat["id"], member_ids))
chat["member_ids"] = sorted(member_ids)
return chat
def get_chat(conn, chat_id, user_id):
return conn.execute(
"""SELECT c.id, c.title, c.created_at,
ARRAY(SELECT m.user_id FROM chat_members m WHERE m.chat_id = c.id ORDER BY m.user_id) AS member_ids
FROM chats c
WHERE c.id = %s AND EXISTS (SELECT 1 FROM chat_members me WHERE me.chat_id = c.id AND me.user_id = %s)""",
(chat_id, user_id)).fetchone()
def is_member(conn, chat_id, user_id):
return conn.execute("SELECT 1 FROM chat_members WHERE chat_id = %s AND user_id = %s",
(chat_id, user_id)).fetchone() is not None
def list_chats(conn, user_id, after, limit):
base = """SELECT c.id, c.title, c.created_at,
ARRAY(SELECT m.user_id FROM chat_members m WHERE m.chat_id = c.id ORDER BY m.user_id) AS member_ids
FROM chat_members me JOIN chats c ON c.id = me.chat_id
WHERE me.user_id = %s"""
params = [user_id]
if after:
base += " AND (c.created_at, c.id) > (%s, %s)"
params += list(after)
rows = conn.execute(base + " ORDER BY c.created_at, c.id LIMIT %s", params + [limit + 1]).fetchall()
page, more = rows[:limit], len(rows) > limit
nxt = cursor.encode("chats", user_id, page[-1]["created_at"], page[-1]["id"]) if more else None
return [chat_json(r) for r in page], nxt
# ---------- сообщения (без изменений логики) ----------
def _message_json(row):
return {"id": str(row["id"]), "chat_id": str(row["chat_id"]), "sender_id": str(row["sender_id"]),
"text": row["text"], "created_at": fmt_ts(row["created_at"]),
"attachment_ids": [str(x) for x in (row.get("attachment_ids") or [])]}
def message_json(row):
return _message_json(row)
def insert_message(conn, chat_id, sender_id, text, attachment_ids=None):
attachment_ids = attachment_ids or []
if attachment_ids:
rows = conn.execute(
"""SELECT id, status FROM attachments WHERE id = ANY(%s) AND chat_id = %s""",
(attachment_ids, chat_id)).fetchall()
by_id = {r["id"]: r for r in rows}
if len(by_id) != len(attachment_ids):
raise not_found()
for att_id in attachment_ids:
if by_id[att_id]["status"] == "failed":
raise bad_request("Нельзя прикрепить failed-вложение")
# queued/processing разрешены с lab5 — можно ссылаться до готовности.
row = conn.execute(
"""INSERT INTO messages (id, chat_id, sender_id, text) VALUES (%s, %s, %s, %s)
RETURNING id, chat_id, sender_id, text, created_at""",
(uuid.uuid4(), chat_id, sender_id, text)).fetchone()
if attachment_ids:
conn.execute(
"""INSERT INTO message_attachments (message_id, attachment_id, position)
SELECT %s, unnest(%s::uuid[]), generate_subscripts(%s::uuid[], 1) - 1""",
(row["id"], attachment_ids, attachment_ids))
row["attachment_ids"] = attachment_ids
return row
def list_messages(conn, chat_id, after, limit):
sql = """SELECT m.id, m.chat_id, m.sender_id, m.text, m.created_at,
ARRAY(SELECT ma.attachment_id FROM message_attachments ma
WHERE ma.message_id = m.id ORDER BY ma.position) AS attachment_ids
FROM messages m WHERE m.chat_id = %s"""
params = [chat_id]
if after:
sql += " AND (m.created_at, m.id) > (%s, %s)"
params += list(after)
rows = conn.execute(sql + " ORDER BY m.created_at, m.id LIMIT %s", params + [limit + 1]).fetchall()
page, more = rows[:limit], len(rows) > limit
nxt = cursor.encode("messages", chat_id, page[-1]["created_at"], page[-1]["id"]) if more else None
return [_message_json(r) for r in page], nxt
# ---------- вложения lab5 ----------
def insert_attachment_queued(conn, chat_id, owner_id, filename, content_type,
size_bytes, sha256, staging_key):
return conn.execute(
"""INSERT INTO attachments
(id, chat_id, owner_id, filename, content_type, size_bytes, sha256,
staging_key, status)
VALUES (%s, %s, %s, %s, %s, %s, %s, %s, 'queued')
RETURNING id, chat_id, owner_id, filename, content_type, size_bytes, sha256,
status, error_code, created_at, updated_at""",
(uuid.uuid4(), chat_id, owner_id, filename, content_type, size_bytes, sha256, staging_key)
).fetchone()
def mark_attachment_failed(conn, attachment_id, error_code):
conn.execute(
"""UPDATE attachments
SET status='failed', error_code=%s, updated_at=clock_timestamp()
WHERE id=%s AND status IN ('queued','processing')""",
(error_code, attachment_id))
def get_attachment_for_member(conn, attachment_id, user_id):
return conn.execute(
"""SELECT a.id, a.chat_id, a.owner_id, a.filename, a.content_type, a.size_bytes, a.sha256,
a.object_key, a.staging_key, a.status, a.error_code, a.created_at, a.updated_at
FROM attachments a
WHERE a.id = %s
AND EXISTS (SELECT 1 FROM chat_members m WHERE m.chat_id = a.chat_id AND m.user_id = %s)""",
(attachment_id, user_id)).fetchone()
def get_variant(conn, attachment_id, variant_name):
return conn.execute(
"""SELECT attachment_id, name, object_key, content_type, size_bytes, width, height, sha256
FROM attachment_variants WHERE attachment_id = %s AND name = %s""",
(attachment_id, variant_name)).fetchone()
def list_variants(conn, attachment_id):
return conn.execute(
"""SELECT name, content_type, size_bytes, width, height, sha256
FROM attachment_variants WHERE attachment_id = %s ORDER BY name""",
(attachment_id,)).fetchall()
def attachment_json(row, variants=None):
return {
"id": str(row["id"]),
"chat_id": str(row["chat_id"]),
"owner_id": str(row["owner_id"]),
"filename": row["filename"],
"content_type": row["content_type"],
"size_bytes": row["size_bytes"],
"sha256": row["sha256"],
"status": row["status"],
"variants": [
{
"name": v["name"],
"content_type": v["content_type"],
"size_bytes": v["size_bytes"],
"width": v["width"],
"height": v["height"],
"sha256": v["sha256"],
} for v in (variants or [])
],
"error_code": row["error_code"],
"created_at": fmt_ts(row["created_at"]),
"updated_at": fmt_ts(row["updated_at"]),
}
+74
View File
@@ -0,0 +1,74 @@
"""S3-совместимое хранилище (Silo/MinIO): потоковые put/get, копирование, удаление."""
import logging
import threading
import boto3
from botocore.config import Config
from botocore.exceptions import BotoCoreError, ClientError
from . import config
log = logging.getLogger("s3")
_client = None
_lock = threading.Lock()
def _get_client():
global _client
if _client is None:
with _lock:
if _client is None:
_client = boto3.client(
"s3",
endpoint_url=config.S3_ENDPOINT,
aws_access_key_id=config.S3_ACCESS_KEY_ID,
aws_secret_access_key=config.S3_SECRET_ACCESS_KEY,
region_name=config.S3_REGION,
config=Config(
signature_version="s3v4",
s3={"addressing_style": "path"},
retries={"max_attempts": 3, "mode": "standard"},
connect_timeout=config.S3_CONNECT_TIMEOUT,
read_timeout=config.S3_READ_TIMEOUT,
),
)
return _client
def ensure_bucket():
client = _get_client()
try:
client.head_bucket(Bucket=config.S3_BUCKET)
except ClientError as exc:
if exc.response.get("Error", {}).get("Code") in ("404", "NoSuchBucket"):
client.create_bucket(Bucket=config.S3_BUCKET)
else:
raise
def put_object(key: str, body, content_type: str, content_length: int):
client = _get_client()
client.put_object(
Bucket=config.S3_BUCKET, Key=key, Body=body,
ContentType=content_type, ContentLength=content_length,
)
def get_object(key: str):
"""Возвращает StreamingBody."""
client = _get_client()
resp = client.get_object(Bucket=config.S3_BUCKET, Key=key)
return resp["Body"]
def delete_object(key: str):
client = _get_client()
try:
client.delete_object(Bucket=config.S3_BUCKET, Key=key)
except (ClientError, BotoCoreError):
log.warning("failed to delete object %s", key)
def ping():
client = _get_client()
client.head_bucket(Bucket=config.S3_BUCKET)
+72
View File
@@ -0,0 +1,72 @@
"""Пароли (Argon2id), токены, разбор заголовка Authorization."""
import base64
import binascii
import hashlib
import re
import secrets
import threading
from argon2 import PasswordHasher, Type
from argon2.exceptions import InvalidHashError, VerificationError
from . import config
_hasher = PasswordHasher(time_cost=config.ARGON2_TIME_COST, memory_cost=config.ARGON2_MEMORY_KIB,
parallelism=1, hash_len=32, salt_len=16, type=Type.ID)
_DUMMY_HASH = _hasher.hash("dummy-password-for-constant-time")
_hash_slots = threading.BoundedSemaphore(config.HASH_CONCURRENCY)
_TOKEN_RE = re.compile(r"[A-Za-z0-9._~+/=-]{16,512}")
def hash_password(password):
with _hash_slots:
return _hasher.hash(password)
def verify_password(stored_hash, password):
with _hash_slots:
try:
_hasher.verify(stored_hash, password)
except (VerificationError, InvalidHashError):
return False, None
return True, (_hasher.hash(password) if _hasher.check_needs_rehash(stored_hash) else None)
def burn_verify(password):
with _hash_slots:
try:
_hasher.verify(_DUMMY_HASH, password)
except VerificationError:
pass
def new_token():
return secrets.token_urlsafe(32)
def token_hash(token):
return hashlib.sha256(token.encode("ascii")).digest()
def parse_basic(header):
if not header:
return None
scheme, _, rest = header.partition(" ")
if scheme.lower() != "basic":
return None
try:
text = base64.b64decode(rest.strip(), validate=True).decode("utf-8")
except (binascii.Error, UnicodeDecodeError, ValueError):
return None
username, sep, password = text.partition(":")
return (username, password) if sep else None
def parse_bearer(header):
if not header:
return None
scheme, _, rest = header.partition(" ")
token = rest.strip()
if scheme.lower() != "bearer" or not _TOKEN_RE.fullmatch(token):
return None
return token
+81
View File
@@ -0,0 +1,81 @@
"""Сессии: PostgreSQL — источник истины, Redis/Valkey — read-through кэш."""
import json
import time
from datetime import timezone
from . import cache, config, db, security
from .errors import ApiError
TOMBSTONE = "revoked"
_KEY = "sess:v1:"
def fmt_ts(value):
return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
def user_json(row):
return {"id": str(row["id"]), "username": row["username"], "display_name": row["display_name"],
"created_at": fmt_ts(row["created_at"])}
def _ttl_ms(expires_epoch):
remaining = expires_epoch - time.time()
return int(min(config.SESSION_CACHE_TTL_SECONDS, remaining) * 1000) if remaining > 0 else 0
def create(conn, user_row):
token = security.new_token()
row = conn.execute(
"""INSERT INTO sessions (token_hash, user_id, expires_at)
VALUES (%s, %s, clock_timestamp() + make_interval(secs => %s))
RETURNING expires_at""",
(security.token_hash(token), user_row["id"], config.SESSION_TTL_SECONDS)).fetchone()
conn.execute("""DELETE FROM sessions WHERE token_hash IN (
SELECT token_hash FROM sessions WHERE expires_at < now() - interval '1 hour' LIMIT 100)""")
return token, row["expires_at"]
def warm(token, user, expires_at):
entry = {"user": user, "exp": expires_at.timestamp()}
ttl = _ttl_ms(entry["exp"])
if ttl > 0:
cache.set_if_absent(_KEY + security.token_hash(token).hex(), json.dumps(entry), ttl)
def lookup(token):
digest = security.token_hash(token)
key = _KEY + digest.hex()
cached = cache.get(key)
if cached == TOMBSTONE:
return None
if cached:
try:
entry = json.loads(cached)
if entry["exp"] > time.time():
return {"user": entry["user"], "digest": digest}
return None
except (ValueError, KeyError, TypeError):
pass
with db.connection() as conn:
row = conn.execute(
"""SELECT u.id, u.username, u.display_name, u.created_at,
extract(epoch FROM s.expires_at) AS exp
FROM sessions s JOIN users u ON u.id = s.user_id
WHERE s.token_hash = %s AND s.expires_at > clock_timestamp()""", (digest,)).fetchone()
if row is None:
return None
user = user_json(row)
ttl = _ttl_ms(float(row["exp"]))
if ttl > 0:
cache.set_if_absent(key, json.dumps({"user": user, "exp": float(row["exp"])}), ttl)
return {"user": user, "digest": digest}
def revoke(digest):
if config.CACHE_URL:
wrote = cache.set_always(_KEY + digest.hex(), TOMBSTONE, config.SESSION_CACHE_TTL_SECONDS * 1000)
if not wrote:
raise ApiError(503, "unavailable", "Сервис временно недоступен")
with db.connection() as conn:
conn.execute("DELETE FROM sessions WHERE token_hash = %s", (digest,))
+98
View File
@@ -0,0 +1,98 @@
"""lab6: общая инициализация OTel для API и worker.
Каждый процесс вызывает init(service_name=...) один раз. После этого:
- get_tracer() / get_meter() — SDK-хендлы;
- inject_headers(dict) / extract_context(dict) — W3C trace context через RabbitMQ.
"""
import logging
import os
from opentelemetry import metrics, trace
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
from opentelemetry.propagate import inject as _inject, extract as _extract
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import Resource, SERVICE_NAME, SERVICE_VERSION
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry._logs import set_logger_provider
log = logging.getLogger("telemetry")
_initialized = False
def init(service_name: str) -> None:
"""Идемпотентная инициализация. Если OTEL выключен — no-op.
Ресурс: service.name, service.version, deployment.environment.name, service.instance.id.
"""
global _initialized
if _initialized:
return
# OTEL_SDK_DISABLED=true отключает SDK полностью (для теста «telemetry off»).
if os.environ.get("OTEL_SDK_DISABLED", "false").lower() == "true":
log.info("OTel disabled by OTEL_SDK_DISABLED, using no-op providers")
_initialized = True
return
endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "http://otel-collector:4318")
version = os.environ.get("OTEL_SERVICE_VERSION", "1.6.0")
instance_id = os.environ.get("HOSTNAME") or os.environ.get("INSTANCE_ID") or "unknown"
resource = Resource.create({
SERVICE_NAME: service_name,
SERVICE_VERSION: version,
"deployment.environment.name": "lab",
"service.instance.id": instance_id,
})
# Traces
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(
BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint + "/v1/traces")))
trace.set_tracer_provider(tracer_provider)
# Metrics — периодический экспорт каждые 10 секунд.
reader = PeriodicExportingMetricReader(
OTLPMetricExporter(endpoint=endpoint + "/v1/metrics"),
export_interval_millis=10_000)
meter_provider = MeterProvider(resource=resource, metric_readers=[reader])
metrics.set_meter_provider(meter_provider)
# Logs — OTLP HTTP в Collector → Loki. Формат структурный, JSON.
logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(
BatchLogRecordProcessor(OTLPLogExporter(endpoint=endpoint + "/v1/logs")))
set_logger_provider(logger_provider)
# Прикрепляем OTel handler к root logger, чтобы все наши log.info(...)
# уходили в Collector. Существующий StreamHandler остаётся — логи видны и в docker logs.
root = logging.getLogger()
root.addHandler(LoggingHandler(level=logging.INFO, logger_provider=logger_provider))
_initialized = True
log.info("OTel initialized: service=%s endpoint=%s", service_name, endpoint)
def get_tracer(name: str = None):
return trace.get_tracer(name or "messenger")
def get_meter(name: str = None):
return metrics.get_meter(name or "messenger")
def inject_headers(carrier: dict) -> dict:
"""W3C traceparent/tracestate → headers брокера. Level 4: сквозная связь."""
_inject(carrier)
return carrier
def extract_context(carrier: dict):
"""Из headers брокера → OTel Context. Используется в worker."""
return _extract(carrier or {})
+83
View File
@@ -0,0 +1,83 @@
"""Строгая валидация входа."""
import json
import re
import uuid
from .errors import ApiError, bad_request
_UUID_RE = re.compile(r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}")
_USERNAME_RE = re.compile(r"[a-z0-9_]{3,32}")
_INT_RE = re.compile(r"[0-9]{1,6}")
def parse_uuid(value):
if isinstance(value, str) and _UUID_RE.fullmatch(value):
return uuid.UUID(value)
return None
def require_uuid(value, name="id"):
parsed = parse_uuid(value)
if parsed is None:
raise bad_request("Некорректный %s" % name)
return parsed
def _reject_constant(name):
raise ValueError("non-finite number")
def _no_duplicates(pairs):
result = {}
for key, value in pairs:
if key in result:
raise ValueError("duplicate key")
result[key] = value
return result
def json_body(content_type, raw, allowed, required):
if content_type.split(";")[0].strip().lower() != "application/json":
raise ApiError(415, "unsupported_media_type", "Ожидается Content-Type: application/json")
try:
data = json.loads(raw.decode("utf-8"), parse_constant=_reject_constant, object_pairs_hook=_no_duplicates)
except (ValueError, UnicodeDecodeError, RecursionError):
raise bad_request("Некорректный JSON")
if not isinstance(data, dict) or set(data) - set(allowed) or not set(required) <= set(data):
raise bad_request("Некорректный набор полей")
return data
def text_field(value, name, low, high, allow_blank=False):
if not isinstance(value, str):
raise bad_request("Поле %s должно быть строкой" % name)
if "\x00" in value or not _encodable(value):
raise bad_request("Поле %s содержит недопустимые символы" % name)
if not low <= len(value) <= high:
raise bad_request("Поле %s: длина должна быть %d–%d" % (name, low, high))
if not allow_blank and not value.strip():
raise bad_request("Поле %s не должно состоять только из пробелов" % name)
return value
def _encodable(value):
try:
value.encode("utf-8")
return True
except UnicodeEncodeError:
return False
def username_field(value):
if not isinstance(value, str) or not _USERNAME_RE.fullmatch(value):
raise bad_request("username должен соответствовать [a-z0-9_]{3,32}")
return value
def limit_param(params):
raw = params.get("limit")
if raw is None:
return 50
if not _INT_RE.fullmatch(raw) or not 1 <= int(raw) <= 100:
raise bad_request("limit должен быть целым числом 1–100")
return int(raw)
+373
View File
@@ -0,0 +1,373 @@
"""Worker lab6: consume из RabbitMQ, обработка изображения, OTel-инструментация."""
import hashlib
import json
import logging
import signal
import sys
import threading
import time
import uuid
import pika
from opentelemetry import trace
from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor
from opentelemetry.trace import SpanKind
from . import broker, config, db, jobs, pipeline, repo, s3, telemetry
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")
logging.getLogger("pika").setLevel(logging.WARNING)
logging.getLogger("opentelemetry").setLevel(logging.WARNING)
log = logging.getLogger("worker")
_stop = threading.Event()
# OTel-хендлы и метрики инициализируются один раз в main().
_tracer = None
_m_jobs = None
_m_duration = None
_m_time_to_ready = None
_m_busy = None
def _init_metrics():
global _tracer, _m_jobs, _m_duration, _m_time_to_ready, _m_busy
if _tracer is not None:
return
_tracer = telemetry.get_tracer("messenger-worker")
meter = telemetry.get_meter("messenger-worker")
_m_jobs = meter.create_counter(
"messenger_jobs_processed_total",
description="Jobs processed, by outcome")
_m_duration = meter.create_histogram(
"messenger_job_processing_duration_seconds",
description="Job processing duration",
unit="s")
_m_time_to_ready = meter.create_histogram(
"messenger_time_to_ready_seconds",
description="Upload accepted -> status ready",
unit="s")
_m_busy = meter.create_up_down_counter(
"messenger_worker_busy",
description="Worker slots in use")
def _on_sigterm(signum, frame):
log.info("SIGTERM received, stopping after current message")
_stop.set()
def _backoff(attempt: int) -> float:
"""Экспоненциальный backoff с jitter: 2^attempt секунд ± 50%."""
base = min(60.0, 2.0 ** min(attempt, 6))
jitter = 0.5 + 0.5 * (uuid.uuid4().int & 0xFFFF) / 0xFFFF
return base * jitter
def _is_permanent(exc: Exception) -> bool:
if isinstance(exc, ValueError):
return True
return False
def _load_attachment(conn, attachment_id: uuid.UUID):
return conn.execute(
"""SELECT id, chat_id, owner_id, filename, content_type, size_bytes, sha256,
object_key, staging_key, status
FROM attachments WHERE id = %s""", (attachment_id,)).fetchone()
def _already_ready(conn, attachment_id: uuid.UUID) -> bool:
"""Идемпотентность: если ready и есть все три варианта — no-op."""
row = conn.execute(
"""SELECT a.status,
(SELECT count(*) FROM attachment_variants v WHERE v.attachment_id = a.id) AS n
FROM attachments a WHERE a.id = %s""", (attachment_id,)).fetchone()
if row is None:
return False
return row["status"] == "ready" and row["n"] >= 3
def _process_one(conn, job_row) -> None:
"""Один job: скачать staging, обработать, залить финал+варианты, транзакционно записать."""
attachment_id = job_row["attachment_id"]
job_id = job_row["job_id"]
if _already_ready(conn, attachment_id):
jobs.mark_ready(conn, job_id)
log.info("job %s: already ready, ack", job_id)
return
att = _load_attachment(conn, attachment_id)
if att is None:
jobs.mark_failed(conn, job_id, "attachment_missing")
return
if not att["staging_key"]:
jobs.mark_failed(conn, job_id, "staging_missing")
return
# 1. Прочитать staging из S3. BotocoreInstrumentor создаст client span.
body = s3.get_object(att["staging_key"])
try:
data = body.read()
finally:
body.close()
if hashlib.sha256(data).hexdigest() != att["sha256"]:
raise RuntimeError("staging checksum mismatch")
# 2. Обработать (thumbnail, crop, optimized). Не инструментируется отдельно —
# CPU-bound, метрика duration уже покрывает всё.
variants = pipeline.process(data)
# 3. Финализировать: original + варианты в S3.
final_key = "originals/%s/%s" % (att["chat_id"], uuid.uuid4().hex)
s3.put_object(final_key, data, att["content_type"], content_length=len(data))
for v in variants:
v_key = "variants/%s/%s" % (attachment_id, v["name"])
s3.put_object(v_key, v["bytes"], v["content_type"], content_length=len(v["bytes"]))
v["object_key"] = v_key
# 4. Зафиксировать в БД атомарно.
with db.connection() as txn:
check = txn.execute(
"""SELECT status FROM attachments WHERE id = %s FOR UPDATE""",
(attachment_id,)).fetchone()
if check["status"] == "ready":
jobs.mark_ready(txn, job_id)
return
for v in variants:
txn.execute(
"""INSERT INTO attachment_variants
(attachment_id, name, object_key, content_type, size_bytes, width, height, sha256)
VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
ON CONFLICT (attachment_id, name) DO UPDATE
SET object_key = EXCLUDED.object_key,
content_type = EXCLUDED.content_type,
size_bytes = EXCLUDED.size_bytes,
width = EXCLUDED.width,
height = EXCLUDED.height,
sha256 = EXCLUDED.sha256""",
(attachment_id, v["name"], v["object_key"], v["content_type"],
v["size_bytes"], v["width"], v["height"], v["sha256"]))
txn.execute(
"""UPDATE attachments
SET status = 'ready', object_key = %s, error_code = NULL,
staging_key = NULL, updated_at = clock_timestamp()
WHERE id = %s""",
(final_key, attachment_id))
jobs.mark_ready(txn, job_id)
# 5. После COMMIT — удалить staging (best-effort).
try:
s3.delete_object(att["staging_key"])
except Exception:
log.warning("staging delete failed for %s", att["staging_key"])
def _record_time_to_ready(attachment_id: uuid.UUID) -> None:
"""histogram: from attachments.created_at (upload accepted) to now (ready)."""
try:
with db.connection() as conn:
row = conn.execute(
"""SELECT EXTRACT(EPOCH FROM now() - created_at)::float AS delta
FROM attachments WHERE id = %s""",
(attachment_id,)).fetchone()
if row and row["delta"] is not None:
_m_time_to_ready.record(float(row["delta"]),
{"pipeline.version": "1"})
except Exception:
pass
def _handle_message(ch, method, properties, body):
"""Consumer: span + W3C trace context + ack только после COMMIT."""
_init_metrics()
# W3C trace context из headers. Pika хранит значения как bytes — декодируем.
raw_headers = (properties.headers or {}) if properties else {}
headers = {}
for k, v in raw_headers.items():
if isinstance(v, bytes):
headers[k] = v.decode("utf-8", errors="replace")
else:
headers[k] = v
ctx = telemetry.extract_context(headers)
try:
payload = json.loads(body)
job_id = uuid.UUID(payload["job_id"])
except Exception:
log.error("malformed job payload, drop")
ch.basic_nack(method.delivery_tag, requeue=False)
return
with _tracer.start_as_current_span(
"attachment.process",
context=ctx,
kind=SpanKind.CONSUMER,
attributes={
"messaging.system": "rabbitmq",
"messaging.destination.name": broker.QUEUE,
"messaging.message.id": str(job_id),
"messaging.operation": "process",
"job.id": str(job_id),
"attachment.id": payload.get("attachment_id", ""),
"service.instance.id": config.INSTANCE_ID,
}) as span:
t0 = time.monotonic()
_m_busy.add(1, {"worker": config.INSTANCE_ID})
try:
with db.connection() as conn:
job_row = jobs.claim_job(conn, job_id)
if job_row is None:
span.set_attribute("job.skip", "not_claimable")
ch.basic_ack(method.delivery_tag)
return
if job_row["attempt"] > job_row["max_attempts"]:
with db.connection() as conn:
jobs.mark_failed(conn, job_id, "retry_exhausted")
_m_jobs.add(1, {"outcome": "failed", "job.type": "attachment.process.v1"})
span.set_attribute("job.outcome", "failed")
span.set_attribute("job.error_code", "retry_exhausted")
ch.basic_ack(method.delivery_tag)
return
with db.connection() as conn:
_process_one(conn, job_row)
duration = time.monotonic() - t0
_m_duration.record(duration,
{"outcome": "ready", "job.type": "attachment.process.v1"})
_m_jobs.add(1, {"outcome": "ready", "job.type": "attachment.process.v1"})
_record_time_to_ready(job_row["attachment_id"])
span.set_attribute("job.outcome", "ready")
span.set_attribute("job.attempt", job_row["attempt"])
span.set_attribute("job.duration_seconds", round(duration, 3))
ch.basic_ack(method.delivery_tag)
log.info("job %s: done (attempt %d, %.2fs)", job_id, job_row["attempt"], duration)
except Exception as exc:
span.set_attribute("job.outcome", "error")
span.record_exception(exc)
log.warning("job %s: error %s", job_id, type(exc).__name__)
permanent = _is_permanent(exc)
attempt = 1
max_attempts = config.JOB_MAX_ATTEMPTS
try:
with db.connection() as conn:
row = conn.execute(
"SELECT attempt, max_attempts FROM jobs WHERE job_id = %s",
(job_id,)).fetchone()
if row:
attempt = row["attempt"]
max_attempts = row["max_attempts"]
if permanent or attempt >= max_attempts:
jobs.mark_failed(conn, job_id,
"invalid_image" if permanent else "retry_exhausted")
_m_jobs.add(1, {"outcome": "failed", "job.type": "attachment.process.v1"})
span.set_attribute("job.error_code",
"invalid_image" if permanent else "retry_exhausted")
else:
jobs.mark_retry(conn, job_id, "processing_failed", _backoff(attempt))
_m_jobs.add(1, {"outcome": "retry", "job.type": "attachment.process.v1"})
span.set_attribute("job.error_code", "processing_failed")
span.set_attribute("job.retry_after", round(_backoff(attempt), 1))
finally:
ch.basic_ack(method.delivery_tag)
finally:
_m_busy.add(-1, {"worker": config.INSTANCE_ID})
def _reaper_loop():
"""Возвращает в queued задачи с истёкшим lease."""
while not _stop.wait(30):
try:
with db.connection() as conn:
rows = jobs.find_expired_leases(conn)
for row in rows:
outcome = jobs.requeue_expired(conn, row)
log.info("lease reaper: job %s -> %s", row["job_id"], outcome)
except Exception as exc:
log.warning("reaper error: %s", type(exc).__name__)
def _outbox_loop():
"""Публикует outbox — на случай, если API упал между COMMIT и publish."""
while not _stop.wait(3):
try:
with db.connection() as conn:
jobs.publish_pending_outbox(conn, broker.publish)
except Exception as exc:
log.warning("outbox error: %s", type(exc).__name__)
def main():
signal.signal(signal.SIGTERM, _on_sigterm)
signal.signal(signal.SIGINT, _on_sigterm)
# lab6: OTel. service.name=messenger-worker (отличается от API).
telemetry.init("messenger-worker")
PsycopgInstrumentor().instrument()
BotocoreInstrumentor().instrument()
_init_metrics()
# Ждём broker до 120 секунд — на случай рестарта RabbitMQ.
ready = False
for attempt in range(60):
if _stop.is_set():
return
try:
broker.declare_only()
ready = True
break
except Exception as exc:
log.warning("broker not ready (attempt %d): %s",
attempt + 1, type(exc).__name__)
if _stop.wait(2):
return
if not ready:
log.error("broker unavailable after 120s, exiting")
sys.exit(1)
log.info("worker started, queue=%s concurrency=%d",
broker.QUEUE, config.WORKER_CONCURRENCY)
threading.Thread(target=_reaper_loop, daemon=True).start()
threading.Thread(target=_outbox_loop, daemon=True).start()
# Consume с ручным ack и ограниченным prefetch.
conn = pika.BlockingConnection(pika.URLParameters(config.BROKER_URL))
ch = conn.channel()
ch.basic_qos(prefetch_count=config.WORKER_CONCURRENCY)
ch.basic_consume(queue=broker.QUEUE, on_message_callback=_handle_message, auto_ack=False)
while not _stop.is_set():
try:
conn.process_data_events(time_limit=1)
except pika.exceptions.AMQPConnectionError:
log.warning("broker connection lost, reconnecting in 2s")
time.sleep(2)
try:
conn = pika.BlockingConnection(pika.URLParameters(config.BROKER_URL))
ch = conn.channel()
ch.basic_qos(prefetch_count=config.WORKER_CONCURRENCY)
ch.basic_consume(queue=broker.QUEUE, on_message_callback=_handle_message,
auto_ack=False)
except Exception as exc:
log.warning("reconnect failed: %s", type(exc).__name__)
try:
ch.stop_consuming()
conn.close()
except Exception:
pass
db.close()
log.info("worker stopped")
if __name__ == "__main__":
main()
+17
View File
@@ -0,0 +1,17 @@
# Topology worksheet, deliberately NOT a runnable stack (no application supplied).
# Implement compose.yaml or stack.yaml; do not submit this empty file as deployment.
# Service names below are logical roles, not imposed container names.
x-lab-number: 6
x-required-roles:
- api
- postgres
- load_balancer
- s3
- broker
- worker
- otel_collector
- telemetry_storage
- grafana
# TODO: implement real images/builds, network wiring, volumes, healthchecks,
# credentials and bootstrap. Details: contracts/infrastructure.json and README.md.
services: {}
+334
View File
@@ -0,0 +1,334 @@
name: messenger-lab6
x-app-env: &app-env
APP_HOST: "0.0.0.0"
APP_PORT: "8080"
APP_ENV: ${APP_ENV:-lab}
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
SESSION_STORE: ${SESSION_STORE:-postgres+cache}
SESSION_CACHE_TTL_SECONDS: ${SESSION_CACHE_TTL_SECONDS:-60}
DATABASE_URL_FILE: /run/secrets/database_url
CACHE_URL_FILE: /run/secrets/cache_url
IDEMPOTENCY_TTL_SECONDS: ${IDEMPOTENCY_TTL_SECONDS:-86400}
S3_ENDPOINT: http://minio:9000
S3_REGION: ${S3_REGION:-us-east-1}
S3_BUCKET: ${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: ${MAX_UPLOAD_BYTES:-10485760}
MAX_IMAGE_PIXELS: ${MAX_IMAGE_PIXELS:-40000000}
S3_ORPHAN_GRACE_SECONDS: ${S3_ORPHAN_GRACE_SECONDS:-3600}
BROKER_URL_FILE: /run/secrets/broker_url
WORKER_CONCURRENCY: ${WORKER_CONCURRENCY:-2}
JOB_MAX_ATTEMPTS: ${JOB_MAX_ATTEMPTS:-5}
JOB_TIMEOUT_SECONDS: ${JOB_TIMEOUT_SECONDS:-60}
STAGING_RETENTION_SECONDS: ${STAGING_RETENTION_SECONDS:-86400}
# lab6: OTEL — общие значения, каждый сервис переопределяет OTEL_SERVICE_NAME
OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
OTEL_EXPORTER_OTLP_PROTOCOL: http/protobuf
OTEL_RESOURCE_ATTRIBUTES: deployment.environment.name=lab,service.version=1.6.0
OTEL_TRACES_SAMPLER: parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG: "1.0"
OTEL_METRICS_EXPORTER: otlp
OTEL_LOGS_EXPORTER: otlp
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED: "true"
services:
postgres:
image: postgres:17.6-alpine
restart: unless-stopped
environment:
POSTGRES_DB: messenger
POSTGRES_USER: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
secrets: [postgres_password]
command: ["postgres", "-c", "fsync=on", "-c", "synchronous_commit=on",
"-c", "full_page_writes=on", "-c", "max_connections=100"]
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"]
interval: 3s
timeout: 3s
retries: 20
stop_grace_period: 30s
networks: [backend]
mem_limit: 1g
cpus: 1.0
valkey:
image: valkey/valkey:8.1.3-alpine
restart: unless-stopped
secrets: [valkey_password]
command:
- sh
- -c
- >-
exec valkey-server --requirepass "$$(cat /run/secrets/valkey_password)"
--appendonly yes --appendfsync everysec --save ""
--maxmemory 64mb --maxmemory-policy volatile-ttl
volumes:
- valkeydata:/data
healthcheck:
test: ["CMD-SHELL", "REDISCLI_AUTH=\"$$(cat /run/secrets/valkey_password)\" valkey-cli ping | grep -q PONG"]
interval: 3s
timeout: 3s
retries: 20
networks: [backend]
mem_limit: 256m
cpus: 0.5
rabbitmq:
image: rabbitmq:3.13-management-alpine
restart: unless-stopped
secrets: [rabbitmq_password]
entrypoint: ["/bin/sh", "-c"]
command:
- |
export RABBITMQ_DEFAULT_USER=messenger
export RABBITMQ_DEFAULT_PASS="$$(cat /run/secrets/rabbitmq_password)"
exec docker-entrypoint.sh rabbitmq-server
volumes:
- rabbitmqdata:/var/lib/rabbitmq
healthcheck:
test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
interval: 5s
timeout: 5s
retries: 20
start_period: 60s
stop_grace_period: 30s
networks: [backend]
mem_limit: 512m
cpus: 0.5
minio:
image: pgsty/silo:latest
restart: unless-stopped
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]
volumes:
- miniodata:/data
healthcheck:
test: ["CMD", "silo", "healthcheck", "ready"]
interval: 5s
timeout: 3s
retries: 20
start_period: 10s
networks: [backend]
mem_limit: 512m
cpus: 0.5
minio-init:
image: pgsty/mc:latest
depends_on:
minio: {condition: service_healthy}
secrets: [minio_root_user, minio_root_password, s3_access_key_id, s3_secret_access_key]
entrypoint: ["/bin/sh", "-c"]
command:
- |
set -eu
ROOT_USER=$$(cat /run/secrets/minio_root_user)
ROOT_PASS=$$(cat /run/secrets/minio_root_password)
APP_KEY=$$(cat /run/secrets/s3_access_key_id)
APP_SECRET=$$(cat /run/secrets/s3_secret_access_key)
mc alias set local http://minio:9000 "$$ROOT_USER" "$$ROOT_PASS"
mc mb --ignore-existing --with-lock=false local/messenger-attachments
mc anonymous set none local/messenger-attachments
mc admin user add local "$$APP_KEY" "$$APP_SECRET" || true
cat >/tmp/app-policy.json <<EOF
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket"],
"Resource": [
"arn:aws:s3:::messenger-attachments",
"arn:aws:s3:::messenger-attachments/*"
]
}]
}
EOF
mc admin policy create local app-attachment-only /tmp/app-policy.json || true
mc admin policy attach local app-attachment-only --user "$$APP_KEY" || true
restart: "no"
networks: [backend]
migrate:
build: .
command: ["python", "-m", "app.migrate"]
environment: *app-env
secrets: [database_url, cache_url, s3_access_key_id, s3_secret_access_key, broker_url]
depends_on:
postgres: {condition: service_healthy}
restart: "no"
networks: [backend]
api:
build: .
restart: unless-stopped
environment:
<<: *app-env
OTEL_SERVICE_NAME: messenger-api
secrets: [database_url, cache_url, s3_access_key_id, s3_secret_access_key, broker_url]
depends_on:
migrate: {condition: service_completed_successfully}
postgres: {condition: service_healthy}
valkey: {condition: service_started}
minio-init: {condition: service_completed_successfully}
rabbitmq: {condition: service_healthy}
otel-collector: {condition: service_started}
read_only: true
tmpfs: ["/tmp", "/dev/shm"]
cap_drop: [ALL]
security_opt: ["no-new-privileges:true"]
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request as u; u.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)"]
interval: 5s
timeout: 3s
retries: 20
start_period: 30s
stop_grace_period: 25s
networks: [backend]
deploy:
replicas: 2
mem_limit: 512m
cpus: 1.0
worker:
build: .
command: ["python", "-m", "app.worker"]
healthcheck:
disable: true
restart: unless-stopped
environment:
<<: *app-env
OTEL_SERVICE_NAME: messenger-worker
secrets: [database_url, cache_url, s3_access_key_id, s3_secret_access_key, broker_url]
depends_on:
migrate: {condition: service_completed_successfully}
postgres: {condition: service_healthy}
minio-init: {condition: service_completed_successfully}
rabbitmq: {condition: service_healthy}
otel-collector: {condition: service_started}
read_only: true
tmpfs: ["/tmp", "/dev/shm"]
cap_drop: [ALL]
security_opt: ["no-new-privileges:true"]
stop_grace_period: 60s
networks: [backend]
mem_limit: 768m
cpus: 1.0
nginx:
image: nginx:1.27-alpine
ports: ["127.0.0.1:8080:80"]
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
depends_on:
api: {condition: service_healthy}
networks: [backend]
mem_limit: 128m
cpus: 0.25
# ---------------- telemetry stack (lab6) ----------------
otel-collector:
image: otel/opentelemetry-collector-contrib:0.105.0
restart: unless-stopped
command: ["--config=/etc/otelcol/config.yaml"]
volumes:
- ./infra/otel-collector.yaml:/etc/otelcol/config.yaml:ro
networks: [backend]
mem_limit: 256m
cpus: 0.5
# Порты НЕ публикуем: 4317/4318/8889 доступны только внутри backend.
prometheus:
image: prom/prometheus:v2.54.1
restart: unless-stopped
command:
- "--config.file=/etc/prometheus/prometheus.yaml"
- "--storage.tsdb.path=/prometheus"
- "--storage.tsdb.retention.time=24h"
- "--web.enable-lifecycle"
volumes:
- ./infra/prometheus.yaml:/etc/prometheus/prometheus.yaml:ro
- ./infra/alert-rules.yml:/etc/prometheus/alert-rules.yml:ro
- prometheusdata:/prometheus
networks: [backend]
mem_limit: 512m
cpus: 0.5
loki:
image: grafana/loki:3.1.1
restart: unless-stopped
command: ["-config.file=/etc/loki/loki.yaml"]
volumes:
- ./infra/loki.yaml:/etc/loki/loki.yaml:ro
- lokidata:/loki
networks: [backend]
mem_limit: 512m
cpus: 0.5
tempo:
image: grafana/tempo:2.6.0
restart: unless-stopped
command: ["-config.file=/etc/tempo/tempo.yaml"]
volumes:
- ./infra/tempo.yaml:/etc/tempo/tempo.yaml:ro
- tempodata:/var/tempo
networks: [backend]
mem_limit: 512m
cpus: 0.5
grafana:
image: grafana/grafana:11.2.0
restart: unless-stopped
ports: ["127.0.0.1:3000:3000"]
environment:
GF_SECURITY_ADMIN_USER: admin
GF_SECURITY_ADMIN_PASSWORD_FILE: /run/secrets/grafana_admin_password
GF_USERS_ALLOW_SIGN_UP: "false"
GF_AUTH_ANONYMOUS_ENABLED: "false"
GF_ANALYTICS_REPORTING_ENABLED: "false"
secrets: [grafana_admin_password]
volumes:
- ./infra/grafana/provisioning:/etc/grafana/provisioning:ro
- ./infra/grafana/dashboards:/var/lib/grafana/dashboards:ro
- grafanadata:/var/lib/grafana
depends_on:
prometheus: {condition: service_started}
loki: {condition: service_started}
tempo: {condition: service_started}
networks: [backend]
mem_limit: 256m
cpus: 0.5
networks:
backend: {}
volumes:
pgdata: {}
valkeydata: {}
miniodata: {}
rabbitmqdata: {}
prometheusdata: {}
lokidata: {}
tempodata: {}
grafanadata: {}
secrets:
postgres_password: {file: ./secrets/postgres_password}
valkey_password: {file: ./secrets/valkey_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}
rabbitmq_password: {file: ./secrets/rabbitmq_password}
broker_url: {file: ./secrets/broker_url}
grafana_admin_password: {file: ./secrets/grafana_admin_password}
+61
View File
@@ -0,0 +1,61 @@
# Семантика API
Этот текст дополняет [openapi.json](openapi.json). Обязательный API соответствует уровню 3 текущей лабораторной. Факультативный crop или rate limiting не становятся обязательными только из-за наличия допустимого имени варианта или кода ошибки в схеме.
## Формат и ошибки
- JSON — UTF-8, `Content-Type: application/json`. UUID — строка; время — RFC 3339 UTC с `Z`, назначается сервером. Часы не считаются уникальным ID.
- Каждый ответ API, включая ошибки и health, содержит непустой `X-Request-Id`. Тело ошибки: `{"error":{"code":"invalid_request","message":"...","request_id":"..."}}`; `request_id` совпадает с заголовком. Сообщение ошибки не раскрывает stack trace, SQL, credentials или наличие чужого объекта.
- Обязательные строки не состоят только из пробельных символов. `username` строго `[a-z0-9_]{3,32}`, уникален; `display_name` — 1–100 Unicode code points. JSON с лишними полями или неверными типами — `400`; malformed JSON также `400`.
- `400 invalid_request` — неверные поля, UUID, cursor, limit; `401 unauthorized` — нет действительной идентификации/сессии; `404 not_found` — объекта нет или он чужой; `409 conflict` — username занят, повторный ключ с другим сообщением, объект ещё не готов; `413 payload_too_large`; `415 unsupported_media_type`; `429 rate_limited`; `503 unavailable`. Неожиданное исключение — `500 internal_error` без внутренних деталей.
- Сначала аутентификация, затем доступ к конкретному ресурсу. Любой аутентифицированный участник чата может читать его историю и вложения и писать в него; посторонний получает `404`. Списки содержат только доступные объекты. Не используйте `403` для раскрытия существования чужого чата.
- `GET /health/live` проверяет только жизнь процесса, возвращает `200 {"status":"ok"}`. `GET /health/ready` возвращает 200, если приложение может безопасно обслуживать обязательный синхронный путь; иначе 503 в общем формате ошибки. Какие зависимости критичны, зафиксируйте в отчёте; недоступность Grafana не должна останавливать API.
## Пользователи, чаты и сообщения
- `POST /users` публичен; возвращает `201 User`. Пароль/его hash и сессионные данные никогда не входят в User.
- `POST /chats` принимает title и явный список существующих `member_ids`, включая вызывающего. Дубликаты, неизвестные участники и отсутствие вызывающего — 400. Чат создаётся атомарно. GET списка чатов сортируется по `(created_at, id)` по возрастанию.
- Отправитель сообщения выводится из текущей идентификации, поле `sender_id` в запросе не принимается. Текст — до 4000 Unicode code points. Нельзя отправить пустой/пробельный текст без вложений.
- История использует keyset cursor: `(created_at, id)`, по возрастанию; `limit` — целое 1–100, по умолчанию 50. Ответ `{"items":[...],"next_cursor":null}`. Непустой cursor — непрозрачная для клиента строка; последний элемент предыдущей страницы не повторяется. Cursor привязан к ресурсу/запросу: от другого чата — 400. Изменять `limit` при продолжении можно.
- `next_cursor` равен null, если на момент чтения следующей записи нет. Гарантируется отсутствие повторов при обходе неизменной истории; snapshot изоляция между несколькими HTTP-запросами не требуется. При конкурентных вставках опишите выбранную семантику и ограничения часов.
- Подтверждённое сообщение видно следующему чтению через любую API-реплику. Допускается кэш, но он не должен возвращать устаревшую историю после успешной записи. Удаление и изменение участников в обязательный API не входят.
## Идентификация и сессии
**Lab1:** защищённые endpoint требуют `X-User-Id: <UUID существующего пользователя>`; отсутствие/неизвестный ID — 401. Это учебный выбор пользователя: любой клиент может выдать себя за другого.
**Lab2–7:** `POST /auth/sessions` принимает только `Authorization: Basic <base64(username:password)>`, без JSON body. Username ограничен ASCII; пароль кодируется UTF-8, 12–128 code points, двоеточие в пароле допустимо. Неверные credentials — одинаковый 401 и `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`.
Вход возвращает `201 {"token":"...","token_type":"Bearer","expires_at":"...Z","user":{...}}`. Токен — непрозрачное случайное значение, не username/UUID и не обязательный JWT; энтропия не менее 256 бит. Храните серверную сессию с expiry; TTL задаётся `SESSION_TTL_SECONDS`, по умолчанию 3600 (в тесте истечения можно 2). В обычном smoke TTL должен быть не менее 300.
Все защищённые endpoint принимают только `Authorization: Bearer <token>`. Истёкший/отозванный/неизвестный токен — 401 с `WWW-Authenticate: Bearer realm="messenger"`. Basic на бизнес-endpoint — 401. `X-User-Id` с lab2 игнорируется: он не меняет владельца сессии и сам по себе не даёт доступ. `DELETE /auth/sessions/current` отзывает текущий токен и возвращает 204 без тела; повтор с отозванным токеном — 401.
Пользователи, чаты, сообщения и ещё действительные сессии переживают перезапуск приложения и используемых хранилищ с сохранёнными volumes. TTL не продлевается из-за рестарта. Пароли уже с lab2 хешируются библиотечным password KDF (Argon2id, scrypt или bcrypt с учётом ограничений библиотеки), не SHA-256 и не plaintext. Если bcrypt не поддерживает весь диапазон UTF-8 паролей без усечения, выберите другую библиотечную схему. В lab7 обязателен Argon2id.
Basic — это кодирование, не шифрование. HTTP lab1–6 допускается только для локального изолированного стенда с синтетическими данными; для удалённой демонстрации нужен TLS. Lab7 использует HTTPS обязательно. См. [RFC 7617](https://www.rfc-editor.org/info/rfc7617/).
## Балансировка и повторная отправка (с lab3)
- Каждый ответ, созданный API, содержит `X-Instance-Id`; значение стабильно для жизни процесса. Ошибки соединения, созданные самим LB, могут не иметь этого заголовка. В lab7 используйте случайный alias реплики без раскрытия hostname/IP.
- Для POST сообщения обязателен `Idempotency-Key` (ASCII `[A-Za-z0-9._:-]{1,128}`). Нет/неверный ключ — 400. Область уникальности: текущий пользователь + HTTP-метод + путь чата + ключ.
- При повторе того же валидного JSON в течение 24 часов сервер возвращает тот же код 201 и то же Message. Порядок ключей JSON и отсутствующий `attachment_ids` вместо `[]` семантически равны. Другой body при том же ключе — 409. Разные пользователи/чаты могут использовать одинаковый ключ независимо.
- Одновременные повторы через разные реплики создают ровно одно сообщение. Повтор снова проверяет действительность сессии и доступ. Транзиентные 5xx не фиксируются как окончательный результат; побочный эффект и запись результата должны быть атомарны.
- Ключ обязателен только для сообщений. Самостоятельный retry загрузки файла или создания чата может создать ещё один объект; не добавляйте прозрачные повторы этих POST без расширения контракта.
## Вложения (с lab4)
- `POST /chats/{chat_id}/attachments?filename=photo.png`: сырые bytes одного PNG/JPEG; `Content-Type: image/png` или `image/jpeg`. Не multipart. Максимум **10 MiB = 10 485 760 байт**. MIME проверяется по содержимому; заведомо повреждённые/чужие форматы — 415, превышение bytes — 413. Не более 40 миллионов декодированных пикселей (превышение — 413). Устанавливайте лимит до полной распаковки изображения.
- `filename` — отображаемое имя (1–255 code points). Не используйте его как путь/ключ S3. Имя с `/`, `\`, NUL или управляющими символами — 400. Bucket приватен; object key генерирует сервер. Оригинал возвращается побайтно, его lowercase SHA-256 и размер соответствуют исходному файлу.
- Lab4 возвращает `201 Attachment` со `status=ready`, `variants=[]`, `error_code=null` только после сохранения оригинала и метаданных. Lab5–7 возвращают `202 Attachment` со снимком `status=queued`; готовность определяется последующим GET метаданных. Быстрый worker может закончить до первого GET — это нормально.
- Файл заранее привязан к чату. В POST сообщения добавляется `attachment_ids` (0–10 уникальных ID, по умолчанию []). Можно отправить `text=""` с хотя бы одним вложением. Все вложения должны принадлежать этому чату; чужое/неизвестное — 404. Любой участник может ссылаться на доступное вложение чата. Failed-вложение прикреплять нельзя (409); queued/processing с lab5 можно.
- `GET /attachments/{id}` и `/content` доступны только участникам чата. Download возвращает байты с истинным Content-Type, через авторизованный API, **без redirect** в обязательном контракте. Приватный bucket сам по себе не заменяет эту проверку. `variant` по умолчанию original. Для queued/processing content — 409; для failed — 409. Отсутствующий вариант ready-объекта — 404.
- В ready-метаданных `error_code=null`. В failed — краткий машинный код (например `invalid_image`, `processing_failed`, `retry_exhausted`), без stack trace. `size_bytes`, `sha256`, `content_type` всегда описывают оригинал; у вариантов отдельные поля. Публичный API не раскрывает ключи бакета, внутренние адреса и credentials.
- Прямой upload/download по временной подписи — факультативное расширение. Его дополняют ограничение срока/размера, уникальный ключ и подтверждение реально загруженного объекта; он не заменяет стандартный endpoint. Особенности подписанных URL: [S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html).
## Фоновая обработка (с lab5)
До 202 все байты приняты в **устойчивый staging**, а намерение обработать файл надёжно сохранено. HTTP-передача клиента не исчезает и не становится мгновенной. Staging — приватный S3-prefix либо общий persistent volume, доступный worker; локальная память/API ephemeral disk не подходит. Worker асинхронно переносит/публикует оригинал в конечный S3-prefix и создаёт варианты; если staging уже в S3, опишите эту границу честно.
Обязательный thumbnail: JPEG, изображение вписано в 256×256 с сохранением пропорций, без увеличения маленьких исходников, EXIF orientation применяется; alpha компонуется на белый. Размеры округляются вниз, минимум 1 px. Fixture 320×200 должен дать 256×160. Статус ready ставится после сохранения оригинала и thumbnail. Crop на 4: JPEG, центрированный квадрат 128×128 (для маленьких исходников допускается увеличение). Optimized на 4: WebP, вписан в 1280×1280 без увеличения, параметры качества и удаления EXIF документируются; не обещайте уменьшение каждого маленького файла.
Допустимые состояния и события описаны в `jobs.schema.json` и `attachment-states.md`. Доставка — at least once; обработка идемпотентна, повторы не размножают варианты. Финальные ошибки наблюдаемы, бесконечный немой retry недопустим. Обязательный smoke ждёт ready до 60 секунд; это бюджет локального smoke для одного файла при свободном worker, не универсальный production SLA. В очередь идут ссылки/ID, не бинарное содержимое.
+21
View File
@@ -0,0 +1,21 @@
# Состояния вложения и договор между producer/worker
Сообщение broker соответствует [jobs.schema.json](jobs.schema.json). Можно применять native headers брокера для trace context, но семантика carrier сохраняется; для проверки покажите отображение полей. `job_id` идентифицирует одну логическую работу и не меняется при redelivery; `attempt` начинается с 1 и отражает управляемую попытку обработки (broker redelivery сам по себе не создаёт новый job_id). Ключ эффекта — `(attachment_id, pipeline_version, variant)`.
| Переход | Условие | Что устойчиво сохранено |
| --- | --- | --- |
| нет → queued | Принимаем upload; только после durable handoff отвечаем 202 | Полный проверенный оригинал в staging, метаданные, намерение обработки |
| queued → processing | Worker захватил/арендовал работу | Попытка, lease/deadline или эквивалентная защита |
| processing → queued | Временная ошибка и остались попытки | Причина без секретов, время следующей попытки |
| processing → ready | Все обязательные объекты записаны и результат атомарно опубликован | Оригинал, thumbnail (на 4 ещё crop/optimized), метаданные/checksums |
| processing → failed | Ошибка постоянная или попытки исчерпаны | error_code и запись, доступная оператору |
| processing → queued | Истёк lease после смерти worker | Восстановленная работа, без дублирования эффектов |
| failed → queued | Явный операторский replay, доступен на 4 | Audit, новая попытка, прежний логический эффект защищён от дубля |
Повторная доставка уже ready-задачи — no-op с ack после проверки завершённого эффекта. Конкурентные попытки не перезаписывают более новый pipeline_version. Основной курс использует pipeline_version=1; версионирование нескольких pipeline — трек 5. Заявляйте готовность только когда все обещанные уровнем варианты доступны. Нельзя откатывать ready в processing из-за старого дубля.
**Окна отказа для защиты:** после staging до записи задания; после COMMIT до publish; после publish до confirm; после записи S3 до COMMIT результата; после COMMIT результата до ack. На 3 покажите сохранность успешно принятой работы и повторную доставку; на 4 автоматическое восстановление разрыва DB/broker (outbox/эквивалент) и зависшего processing.
Staging не удаляется до безопасной публикации результатов. Неуспешные/непривязанные исходники имеют документированный retention и cleanup; он не удаляет текущую работу. Broker принимает только ID/служебные данные, не произвольный URL для скачивания и не путь из клиентского filename. Worker берёт доверенные storage metadata из БД.
Ack подтверждает устойчивую обработку, publisher confirm — приём брокером; это разные границы. См. [RabbitMQ reliability](https://www.rabbitmq.com/docs/reliability). At-least-once + идемпотентный эффект не означает exactly-once доставку.
+60
View File
@@ -0,0 +1,60 @@
{
"CreateUser": {
"username": "alice",
"display_name": "Алиса",
"password": "Example-only-not-a-real-secret-123"
},
"User": {
"id": "11111111-1111-4111-8111-111111111111",
"username": "alice",
"display_name": "Алиса",
"created_at": "2026-09-01T12:00:00Z"
},
"CreateChat": {
"title": "Проект по ВНП",
"member_ids": [
"11111111-1111-4111-8111-111111111111",
"22222222-2222-4222-8222-222222222222"
]
},
"Chat": {
"title": "Проект по ВНП",
"member_ids": [
"11111111-1111-4111-8111-111111111111",
"22222222-2222-4222-8222-222222222222"
],
"id": "33333333-3333-4333-8333-333333333333",
"created_at": "2026-09-01T12:00:00Z"
},
"CreateMessage": {
"text": "Привет, Боб!"
},
"Message": {
"id": "44444444-4444-4444-8444-444444444444",
"chat_id": "33333333-3333-4333-8333-333333333333",
"sender_id": "11111111-1111-4111-8111-111111111111",
"text": "Привет, Боб!",
"created_at": "2026-09-01T12:00:00Z",
"attachment_ids": []
},
"MessagePage": {
"items": [
{
"id": "44444444-4444-4444-8444-444444444444",
"chat_id": "33333333-3333-4333-8333-333333333333",
"sender_id": "11111111-1111-4111-8111-111111111111",
"text": "Привет, Боб!",
"created_at": "2026-09-01T12:00:00Z",
"attachment_ids": []
}
],
"next_cursor": null
},
"Error": {
"error": {
"code": "not_found",
"message": "Объект не найден",
"request_id": "example-request-id"
}
}
}
+88
View File
@@ -0,0 +1,88 @@
{
"lab": 6,
"kind": "requirements, not runnable deployment",
"required_for_grade_3": [
{
"role": "api",
"count_min": 2,
"student_implements": true,
"persistent_local_state": false
},
{
"role": "postgres",
"purpose": "users/chats/membership/messages/metadata",
"persistent_volume": true
},
{
"role": "load_balancer",
"public_entrypoint": true,
"backend_readiness": true
},
{
"role": "s3",
"choose_one": [
"MinIO",
"SeaweedFS",
"RustFS"
],
"private_bucket": true,
"persistent_volume": true
},
{
"role": "broker",
"choose_one": [
"RabbitMQ",
"Redis Streams",
"Valkey Streams",
"NATS JetStream",
"documented durable equivalent"
],
"persistent_volume": true,
"delivery": "at-least-once"
},
{
"role": "worker",
"separate_process": true
},
{
"role": "otel_collector",
"signals": [
"metrics",
"logs",
"traces"
]
},
{
"role": "telemetry_storage",
"signals": [
"metrics",
"logs",
"traces"
],
"possible_combination": [
"Prometheus",
"Loki",
"Tempo"
],
"persistent_volume": true
},
{
"role": "grafana",
"provisioning_in_git": true
}
],
"optional_components": [
{
"role": "redis_or_valkey",
"required_for_lab2_grade4": true,
"note": "Choose one; if only store of sessions, configure durable persistence."
}
],
"rules": [
"Choose Compose or Swarm for lab3+; do not need both.",
"Never publish internal API replica ports in bypass of LB from lab3.",
"Versions/digests must be fixed in implementation.",
"Do not remove volumes in restart/failover checks.",
"Document service names, healthchecks, bootstrap/migrations and credentials."
]
}
+63
View File
@@ -0,0 +1,63 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "urn:mtusi:messenger:attachment-job:v1",
"title": "Durable attachment processing job v1",
"type": "object",
"additionalProperties": false,
"required": [
"schema_version",
"job_id",
"type",
"attachment_id",
"pipeline_version",
"attempt",
"created_at"
],
"properties": {
"schema_version": {
"const": 1
},
"job_id": {
"type": "string",
"format": "uuid"
},
"type": {
"const": "attachment.process.v1"
},
"attachment_id": {
"type": "string",
"format": "uuid"
},
"pipeline_version": {
"type": "integer",
"minimum": 1
},
"attempt": {
"type": "integer",
"minimum": 1
},
"created_at": {
"type": "string",
"format": "date-time"
},
"traceparent": {
"type": "string",
"pattern": "^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$"
},
"tracestate": {
"type": "string",
"maxLength": 512
}
},
"examples": [
{
"schema_version": 1,
"job_id": "11111111-1111-4111-8111-111111111111",
"type": "attachment.process.v1",
"attachment_id": "22222222-2222-4222-8222-222222222222",
"pipeline_version": 1,
"attempt": 1,
"created_at": "2026-09-01T12:00:00Z"
}
]
}
+28
View File
@@ -0,0 +1,28 @@
# Контракт наблюдаемости
Ниже логические сигналы. Допустимы стандартные semantic conventions выбранного SDK и их native metric names: зафиксируйте соответствие в `REPORT.md`, dashboard обязан ссылаться на реально существующие имена/единицы. Переименование SDK не повод дублировать одну метрику двумя инструментами. Версии SDK, semantic conventions, Collector distribution и backend закрепляются в решении.
| Сигнал | Минимальные поля/измерения | Уровень |
| --- | --- | --- |
| HTTP requests | method, route template, status class; counter | 3 |
| HTTP duration | histogram в секундах или документированное преобразование из ms | 3 |
| Jobs processed / failed | job type, outcome, counter | 3 |
| Job processing duration | job type, outcome, histogram | 3 |
| API и worker logs | timestamp, severity, service.name, event, trace_id, span_id при активном span | 3 |
| API и worker traces | реальные server/consumer spans, duration, outcome; не искусственный статический trace | 3 |
| Queue depth / oldest job age | queue name, количество / секунды | 4 |
| Pool/saturation | DB pool used/waiting, worker busy/capacity, process/container CPU/RAM | 4 |
| Сквозная связь upload → publish → consume → S3/DB | W3C traceparent/tracestate; parent-child или link по выбранной семантике | 4 |
| End-to-end time to ready | от durable acceptance до публикации ready, histogram | 4 |
Resource attributes: `service.name` (messenger-api / messenger-worker), `service.version`, `service.instance.id`, `deployment.environment.name=lab`. Список имён может отличаться, если явно сопоставлен. `X-Request-Id` коррелирует HTTP-ошибку с логом; trace_id — не замена всех request IDs.
**Не labels метрик:** user_id, chat_id, message_id, attachment_id, request_id, raw URL, filename, текст. Для маршрута используйте `/api/v1/chats/{chat_id}/messages`, не реальный UUID. В логах/трассах допустимы ограниченные технические ID для учебных синтетических данных, если обоснована необходимость; пароли, Authorization, session token, body сообщения, картинка, private key и signed URL запрещены.
Для HTTP error ratio заранее определите numerator/denominator: например 5xx/все бизнес-запросы, исключая health; не смешивайте неверный пароль клиента с отказом БД. p95 агрегируется из histogram buckets всех нужных реплик, а не средних p95. Границы buckets должны соответствовать ожидаемым задержкам. Backlog — не queue processing latency.
В Git находятся Collector config, backend configs, datasources/dashboard provisioning, dashboard JSON и на 4 alert rules. У alerts есть условие, окно, порог, `for` при необходимости, описание и локальный runbook. Отправка сообщений в почту/мессенджер не требуется.
Минимальные контролируемые инциденты для 4: (1) остановить worker и увидеть рост возраста задач; (2) сделать DB медленной/недоступной и отличить её от медленного HTTP handler по trace/метрикам. После восстановления backlog уменьшается, alerts resolved. Третий сценарий — недоступность backend telemetry: SDK/Collector ограничивают RAM/очередь, API сохраняет работу, потери telemetry считаются и объясняются.
Collector — получатель/обработчик/экспортёр, не долговременная БД. Grafana — интерфейс и запросы к источникам. Логи можно отправлять OTLP в совместимый backend; не закладывайте удалённый/устаревший exporter без проверки текущей сборки. См. [Collector configuration](https://opentelemetry.io/docs/collector/configuration/), [Trace Context](https://www.w3.org/TR/trace-context/) и [histograms](https://prometheus.io/docs/practices/histograms/).
File diff suppressed because it is too large Load Diff
+5
View File
@@ -0,0 +1,5 @@
# Доказательства
Храните небольшие обезличенные результаты: команды и stdout проверок, JSON/CSV агрегатов нагрузки, EXPLAIN, dashboard JSON, текст разбора отказа. Укажите дату, commit, аппаратные лимиты и профиль нагрузки.
Не добавляйте .env, session tokens, cookies, приватные ключи, credentials, реальные сообщения, raw dumps и signed URLs. Для скриншотов скрывайте секреты. Большие логи/бинарные traces сохраняйте отдельно по правилам преподавателя; одного скриншота без методики недостаточно.
+53
View File
@@ -0,0 +1,53 @@
# Optional HTTP-client worksheet; no extension is required by the course.
# Replace IDs/token locally from real responses; do not commit filled-in credentials.
# Canonical API: contracts/openapi.json and contracts/README.md.
@baseUrl = http://localhost:8080
@aliceId = REPLACE_WITH_CREATED_ALICE_UUID
@bobId = REPLACE_WITH_CREATED_BOB_UUID
@chatId = REPLACE_WITH_CREATED_CHAT_UUID
@sessionToken = REPLACE_LOCALLY_DO_NOT_COMMIT
### Liveness
GET {{baseUrl}}/health/live
### Register Alice (repeat with username bob/display_name Боб)
POST {{baseUrl}}/api/v1/users
Content-Type: application/json
{
"username": "alice",
"display_name": "Алиса",
"password": "Example-only-not-a-real-secret-123"
}
### Create session: generate the Base64 value locally, do not commit credentials
# Base64 of UTF-8 username:password; only this endpoint accepts Basic.
POST {{baseUrl}}/api/v1/auth/sessions
Authorization: Basic REPLACE_WITH_LOCAL_BASE64_CREDENTIAL
### Create chat; both UUIDs must be real registered users
POST {{baseUrl}}/api/v1/chats
Authorization: Bearer {{sessionToken}}
Content-Type: application/json
{"title":"Проект по ВНП","member_ids":["{{aliceId}}","{{bobId}}"]}
### Send message
POST {{baseUrl}}/api/v1/chats/{{chatId}}/messages
Authorization: Bearer {{sessionToken}}
Idempotency-Key: example-message-001
Content-Type: application/json
{"text":"Привет, Боб!"}
### Read first page
GET {{baseUrl}}/api/v1/chats/{{chatId}}/messages?limit=50
Authorization: Bearer {{sessionToken}}
### Binary upload; HTTP file-client syntax for reading local fixture
POST {{baseUrl}}/api/v1/chats/{{chatId}}/attachments?filename=sample.png
Authorization: Bearer {{sessionToken}}
Content-Type: image/png
< ../tests/fixtures/sample.png
+7
View File
@@ -0,0 +1,7 @@
# Инфраструктура студента
Здесь разместите конфигурации выбранных сервисов; основную топологию — в корневом compose.yaml/stack.yaml. `compose.example.yaml` — только worksheet ролей и намеренно не запускается. `contracts/infrastructure.json` задаёт минимальные роли, не готовые образы/пароли.
В REPORT.md сопоставьте роль → service name → версия/digest → health/readiness → volume → сеть/порт → способ передачи credentials. Приведите bootstrap (schema, bucket, broker topology, а с lab6 provisioning) и безопасное повторение этих команд.
Приложение строится из исходников. Не используйте заранее существующий образ преподавательского сервера вместо своей реализации. Restart hook перезапускает все соответствующие stores с volumes; failover hook останавливает только заданную API-реплику.
+44
View File
@@ -0,0 +1,44 @@
groups:
- name: messenger-api
interval: 15s
rules:
# Доля 5xx среди бизнес-запросов (health исключён) > 5% за 2 минуты.
- alert: ApiHighErrorRate
expr: |
(
sum(rate(http_server_duration_milliseconds_count{
http_status_code=~"5..",
http_target!~"/health/.*"
}[2m]))
/
sum(rate(http_server_duration_milliseconds_count{
http_target!~"/health/.*"
}[2m]))
) > 0.05
for: 2m
labels:
severity: warning
annotations:
summary: "API error rate > 5% за 2 минуты"
description: "5xx доля бизнес-запросов превысила 5% в течение 2 минут."
runbook: "Проверить /api/v1 logs в Loki по trace_id из ошибки; проверить health БД/S3/broker."
- alert: QueueLagHigh
expr: messenger_queue_oldest_job_age_seconds > 60
for: 2m
labels:
severity: warning
annotations:
summary: "Очередь обработки отстаёт > 60s"
description: "Самая старая задача в queued старше 60 секунд."
runbook: "Проверить worker (docker compose ps worker, logs worker); проверить RabbitMQ; проверить S3/DB latency."
- alert: QueueLagCritical
expr: messenger_queue_oldest_job_age_seconds > 300
for: 1m
labels:
severity: critical
annotations:
summary: "Очередь обработки отстаёт > 5 минут"
description: "Обработка не продвигается; возможен отказ worker."
runbook: "Остановить worker → проверить логи; проверить RabbitMQ; replay failed."
+64
View File
@@ -0,0 +1,64 @@
{
"annotations": {"list": []},
"editable": true,
"fiscalYearStartMonth": 0,
"graphTooltip": 1,
"links": [],
"panels": [
{"type":"row","title":"API HTTP","gridPos":{"h":1,"w":24,"x":0,"y":0},"collapsed":false,"panels":[]},
{"type":"timeseries","title":"RPS по route template","gridPos":{"h":8,"w":12,"x":0,"y":1},"datasource":{"type":"prometheus","uid":"PBFA97CFB590B2093"},
"fieldConfig":{"defaults":{"unit":"reqps","custom":{"drawStyle":"line","fillOpacity":10}},"overrides":[]},
"targets":[{"expr":"sum by (http_target) (rate(http_server_duration_milliseconds_count{http_target!~\"/health/.*\"}[1m]))","legendFormat":"{{http_target}}"}]},
{"type":"timeseries","title":"Error ratio (5xx / всё, health исключён)","gridPos":{"h":8,"w":12,"x":12,"y":1},"datasource":{"type":"prometheus","uid":"PBFA97CFB590B2093"},
"fieldConfig":{"defaults":{"unit":"percentunit","custom":{"drawStyle":"line","fillOpacity":10}},"overrides":[]},
"targets":[{"expr":"(sum(rate(http_server_duration_milliseconds_count{http_status_code=~\"5..\",http_target!~\"/health/.*\"}[2m])) or vector(0)) / sum(rate(http_server_duration_milliseconds_count{http_target!~\"/health/.*\"}[2m]))","legendFormat":"5xx ratio"}]},
{"type":"timeseries","title":"Latency p50/p95/p99 (API, ms)","gridPos":{"h":8,"w":24,"x":0,"y":9},"datasource":{"type":"prometheus","uid":"PBFA97CFB590B2093"},
"fieldConfig":{"defaults":{"unit":"ms","custom":{"drawStyle":"line","fillOpacity":0}},"overrides":[]},
"targets":[
{"expr":"histogram_quantile(0.50, sum by (le) (rate(http_server_duration_milliseconds_bucket{http_target!~\"/health/.*\"}[2m])))","legendFormat":"p50"},
{"expr":"histogram_quantile(0.95, sum by (le) (rate(http_server_duration_milliseconds_bucket{http_target!~\"/health/.*\"}[2m])))","legendFormat":"p95"},
{"expr":"histogram_quantile(0.99, sum by (le) (rate(http_server_duration_milliseconds_bucket{http_target!~\"/health/.*\"}[2m])))","legendFormat":"p99"}
]},
{"type":"row","title":"Worker / Queue","gridPos":{"h":1,"w":24,"x":0,"y":17},"collapsed":false,"panels":[]},
{"type":"timeseries","title":"Jobs по outcome (rate, 1m)","gridPos":{"h":8,"w":12,"x":0,"y":18},"datasource":{"type":"prometheus","uid":"PBFA97CFB590B2093"},
"fieldConfig":{"defaults":{"unit":"ops","custom":{"drawStyle":"line","fillOpacity":10}},"overrides":[]},
"targets":[{"expr":"sum by (outcome) (rate(messenger_jobs_processed_total[1m]))","legendFormat":"{{outcome}}"}]},
{"type":"timeseries","title":"Job processing duration p50/p95/p99 (s)","gridPos":{"h":8,"w":12,"x":12,"y":18},"datasource":{"type":"prometheus","uid":"PBFA97CFB590B2093"},
"fieldConfig":{"defaults":{"unit":"s","custom":{"drawStyle":"line","fillOpacity":0}},"overrides":[]},
"targets":[
{"expr":"histogram_quantile(0.50, sum by (le) (rate(messenger_job_processing_duration_seconds_bucket[5m])))","legendFormat":"p50"},
{"expr":"histogram_quantile(0.95, sum by (le) (rate(messenger_job_processing_duration_seconds_bucket[5m])))","legendFormat":"p95"},
{"expr":"histogram_quantile(0.99, sum by (le) (rate(messenger_job_processing_duration_seconds_bucket[5m])))","legendFormat":"p99"}
]},
{"type":"timeseries","title":"Queue depth (queued)","gridPos":{"h":8,"w":8,"x":0,"y":26},"datasource":{"type":"prometheus","uid":"PBFA97CFB590B2093"},
"fieldConfig":{"defaults":{"unit":"short","custom":{"drawStyle":"line","fillOpacity":10}},"overrides":[]},
"targets":[{"expr":"sum(messenger_queue_depth)","legendFormat":"depth"}]},
{"type":"timeseries","title":"Oldest job age (s)","gridPos":{"h":8,"w":8,"x":8,"y":26},"datasource":{"type":"prometheus","uid":"PBFA97CFB590B2093"},
"fieldConfig":{"defaults":{"unit":"s","custom":{"drawStyle":"line","fillOpacity":10},"thresholds":{"mode":"absolute","steps":[{"color":"green","value":null},{"color":"yellow","value":60},{"color":"red","value":300}]}},"overrides":[]},
"targets":[{"expr":"max(messenger_queue_oldest_job_age_seconds)","legendFormat":"oldest age"}]},
{"type":"timeseries","title":"Time to ready p50/p95 (s)","gridPos":{"h":8,"w":8,"x":16,"y":26},"datasource":{"type":"prometheus","uid":"PBFA97CFB590B2093"},
"fieldConfig":{"defaults":{"unit":"s","custom":{"drawStyle":"line","fillOpacity":0}},"overrides":[]},
"targets":[
{"expr":"histogram_quantile(0.50, sum by (le) (rate(messenger_time_to_ready_seconds_bucket[5m])))","legendFormat":"p50"},
{"expr":"histogram_quantile(0.95, sum by (le) (rate(messenger_time_to_ready_seconds_bucket[5m])))","legendFormat":"p95"}
]},
{"type":"row","title":"Saturation","gridPos":{"h":1,"w":24,"x":0,"y":34},"collapsed":false,"panels":[]},
{"type":"timeseries","title":"Worker busy slots (capacity 2)","gridPos":{"h":8,"w":8,"x":0,"y":35},"datasource":{"type":"prometheus","uid":"PBFA97CFB590B2093"},
"fieldConfig":{"defaults":{"unit":"short","custom":{"drawStyle":"line","fillOpacity":10},"max":2},"overrides":[]},
"targets":[{"expr":"sum(messenger_worker_busy)","legendFormat":"busy"}]},
{"type":"timeseries","title":"DB pool (available / waiting)","gridPos":{"h":8,"w":8,"x":8,"y":35},"datasource":{"type":"prometheus","uid":"PBFA97CFB590B2093"},
"fieldConfig":{"defaults":{"unit":"short","custom":{"drawStyle":"line","fillOpacity":10}},"overrides":[]},
"targets":[{"expr":"sum by (state) (messenger_db_pool)","legendFormat":"{{state}}"}]},
{"type":"timeseries","title":"Active HTTP requests","gridPos":{"h":8,"w":8,"x":16,"y":35},"datasource":{"type":"prometheus","uid":"PBFA97CFB590B2093"},
"fieldConfig":{"defaults":{"unit":"short","custom":{"drawStyle":"line","fillOpacity":10}},"overrides":[]},
"targets":[{"expr":"sum(http_server_active_requests)","legendFormat":"active"}]}
],
"refresh": "10s",
"schemaVersion": 39,
"tags": ["messenger","lab6"],
"templating": {"list": []},
"time": {"from": "now-15m", "to": "now"},
"timezone": "browser",
"title": "Messenger — lab6",
"uid": "messenger-lab6"
}
@@ -0,0 +1,12 @@
apiVersion: 1
providers:
- name: messenger
orgId: 1
folder: Messenger
type: file
disableDeletion: false
updateIntervalSeconds: 30
options:
path: /var/lib/grafana/dashboards
foldersFromFilesStructure: false
@@ -0,0 +1,31 @@
apiVersion: 1
datasources:
- name: Prometheus
type: prometheus
access: proxy
url: http://prometheus:9090
isDefault: true
jsonData:
timeInterval: 10s
- name: Loki
type: loki
access: proxy
url: http://loki:3100
jsonData:
derivedFields:
- datasourceUid: tempo
matcherRegex: '"trace_id":"([a-f0-9]+)"'
name: TraceID
url: "$${__value.raw}"
- name: Tempo
type: tempo
access: proxy
url: http://tempo:3200
uid: tempo
jsonData:
tracesToLogsV2:
datasourceUid: loki
filterByTraceID: true
serviceMap:
datasourceUid: prometheus
+38
View File
@@ -0,0 +1,38 @@
auth_enabled: false
server:
http_listen_port: 3100
grpc_listen_port: 9096
log_level: warn
common:
path_prefix: /loki
storage:
filesystem:
chunks_directory: /loki/chunks
rules_directory: /loki/rules
replication_factor: 1
ring:
instance_addr: 127.0.0.1
kvstore:
store: inmemory
schema_config:
configs:
- from: 2024-01-01
store: tsdb
object_store: filesystem
schema: v13
index:
prefix: index_
period: 24h
limits_config:
allow_structured_metadata: true
retention_period: 24h
reject_old_samples: false
compactor:
working_directory: /loki/compactor
retention_enabled: true
delete_request_store: filesystem
+61
View File
@@ -0,0 +1,61 @@
receivers:
otlp:
protocols:
http:
endpoint: 0.0.0.0:4318
grpc:
endpoint: 0.0.0.0:4317
processors:
# Ограничивает RAM коллектора: если превысили — начинает отбрасывать данные,
# а не падает по OOM. Это требование lab6 уровня 4.
memory_limiter:
check_interval: 1s
limit_mib: 200
spike_limit_mib: 50
# Батчинг: уменьшает число запросов к backend.
batch:
timeout: 5s
send_batch_size: 1024
# Ограничивает кардинальность метрик: удаляет потенциально опасные атрибуты.
attributes/scrub:
actions:
- key: http.request.header.authorization
action: delete
- key: http.request.header.cookie
action: delete
exporters:
# Метрики — в формате Prometheus. Prometheus сам scrape'ит :8889.
prometheus:
endpoint: 0.0.0.0:8889
resource_to_telemetry_conversion:
enabled: true
# Логи — в Loki через OTLP endpoint (Loki 3.x умеет /otlp).
otlphttp/loki:
endpoint: http://loki:3100/otlp
tls:
insecure: true
# Трассы — в Tempo через OTLP gRPC.
otlp/tempo:
endpoint: tempo:4317
tls:
insecure: true
service:
pipelines:
traces:
receivers: [otlp]
processors: [memory_limiter, batch]
exporters: [otlp/tempo]
metrics:
receivers: [otlp]
processors: [memory_limiter, batch, attributes/scrub]
exporters: [prometheus]
logs:
receivers: [otlp]
processors: [memory_limiter, batch, attributes/scrub]
exporters: [otlphttp/loki]
telemetry:
logs:
level: info
+7
View File
@@ -0,0 +1,7 @@
# Конфигурация наблюдаемости — реализовать
Добавьте `collector.yaml` с OTLP receivers, processors и exporters выбранной версии Collector. Укажите явные bind endpoints, внутренние сети, memory limits/batch и поведение при backpressure по уровню. Сопоставьте все три pipeline с реально развёрнутыми backend.
Добавьте конфигурации storage, Grafana provisioning/datasources, provisioning/dashboards и импортируемые dashboard JSON. На 4 — alert rules и runbooks. Пустой dashboard или debug exporter, который только печатает данные в stdout, не заменяют хранилища/доказательства из `contracts/observability.md`.
Не публикуйте OTLP/metrics/административные ports в общую сеть без необходимости. В lab7 реализуйте TLS/mTLS по trust matrix; экспорт Authorization и message bodies запрещён.
+16
View File
@@ -0,0 +1,16 @@
global:
scrape_interval: 10s
evaluation_interval: 10s
rule_files:
- /etc/prometheus/alert-rules.yml
scrape_configs:
# Метрики от OTel Collector (он в формате Prometheus на :8889).
- job_name: otel-collector
static_configs:
- targets: ['otel-collector:8889']
# Сам Prometheus — для наблюдения за собой.
- job_name: prometheus
static_configs:
- targets: ['localhost:9090']
+35
View File
@@ -0,0 +1,35 @@
server:
http_listen_port: 3200
grpc_listen_port: 9095
log_level: warn
distributor:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
ingester:
max_block_duration: 5m
compactor:
compaction:
block_retention: 24h
storage:
trace:
backend: local
local:
path: /var/tempo/traces
wal:
path: /var/tempo/wal
metrics_generator:
registry:
external_labels:
source: tempo
storage:
path: /var/tempo/generator/wal
+8
View File
@@ -0,0 +1,8 @@
{
"number": 6,
"title": "Наблюдаемость: OpenTelemetry и Grafana",
"contract_version": "1.6.0",
"default_base_url": "http://localhost:8080",
"grading": "3; 4 includes 3; 5 includes 4 plus one completed research track",
"scaffold_has_application": false
}
+482
View File
@@ -0,0 +1,482 @@
"""Мессенджер, лабораторная 6: lab5 + OpenTelemetry-инструментация."""
import hashlib
import logging
import re
import tempfile
import threading
import uuid
from contextlib import asynccontextmanager
from typing import NamedTuple
from urllib.parse import quote
import anyio.to_thread
import psycopg
from fastapi import Depends, FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse, Response
from opentelemetry import metrics as metrics_module
from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor
from starlette.exceptions import HTTPException as StarletteHTTPException
from app import (attachments, broker, config, cursor, db, idempotency, jobs,
repo, security, sessions, s3, telemetry, validation)
from app.errors import (BASIC_CHALLENGE, BEARER_CHALLENGE, ApiError,
bad_request, not_found, unauthorized)
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")
for _noisy in ("pika", "aiohttp", "urllib3", "botocore", "opentelemetry"):
_l = logging.getLogger(_noisy)
_l.setLevel(logging.WARNING)
_l.propagate = False
log = logging.getLogger("api")
_REQUEST_ID_RE = re.compile(r"[A-Za-z0-9._-]{1,64}")
INSTANCE_ID = config.INSTANCE_ID
_stop = threading.Event()
def _outbox_loop():
"""API тоже публикует outbox — снижает latency до broker."""
while not _stop.wait(2):
try:
with db.connection() as conn:
jobs.publish_pending_outbox(conn, broker.publish)
except Exception:
pass
def _register_metrics():
"""Observable gauges: SDK сам вызывает callbacks при каждом экспорте.
Никакого отдельного потока не нужно — MeterProvider с PeriodicExportingMetricReader
сам опрашивает при экспорте.
"""
meter = telemetry.get_meter("messenger-api")
def _queue_depth(_options):
try:
with db.connection() as conn:
row = conn.execute(
"SELECT count(*) AS c FROM jobs WHERE status='queued'").fetchone()
yield metrics_module.Observation(
int(row["c"] or 0), {"queue.name": broker.QUEUE})
except Exception:
return
def _queue_age(_options):
try:
with db.connection() as conn:
row = conn.execute(
"""SELECT EXTRACT(EPOCH FROM
COALESCE(now() - min(created_at), '0'::interval))::float AS age
FROM jobs WHERE status='queued'""").fetchone()
yield metrics_module.Observation(
float(row["age"] or 0.0), {"queue.name": broker.QUEUE})
except Exception:
return
def _db_pool(_options):
try:
stats = db.get_pool().get_stats()
yield metrics_module.Observation(
int(stats.get("pool_available", 0)), {"state": "available"})
yield metrics_module.Observation(
int(stats.get("requests_waiting", 0)), {"state": "waiting"})
except Exception:
return
meter.create_observable_gauge(
"messenger_queue_depth", callbacks=[_queue_depth],
description="Jobs in queued status")
meter.create_observable_gauge(
"messenger_queue_oldest_job_age_seconds", callbacks=[_queue_age],
description="Age of oldest queued job (seconds)")
meter.create_observable_gauge(
"messenger_db_pool", callbacks=[_db_pool],
description="DB pool state (available/waiting)")
@asynccontextmanager
async def lifespan(_app):
anyio.to_thread.current_default_thread_limiter().total_tokens = config.THREAD_LIMIT
# Psycopg/Botocore можно инструментировать и здесь — они не привязаны к ASGI-приложению.
PsycopgInstrumentor().instrument()
BotocoreInstrumentor().instrument()
_register_metrics()
threading.Thread(target=_outbox_loop, daemon=True).start()
try:
broker.declare_only()
except Exception as exc:
log.warning("broker topology init failed: %s", type(exc).__name__)
yield
_stop.set()
db.close()
app = FastAPI(lifespan=lifespan, docs_url=None, redoc_url=None, openapi_url=None)
# lab6: OTel инициализируется до старта приложения.
# FastAPIInstrumentor.instrument_app() обязан вызываться ДО первого запроса,
# иначе Starlette не даёт добавить middleware.
telemetry.init("messenger-api")
FastAPIInstrumentor.instrument_app(app, excluded_urls="health")
def make_error(code, message, request_id):
return {"error": {"code": code, "message": message, "request_id": request_id}}
def _rid(request):
return getattr(request.state, "request_id", None) or uuid.uuid4().hex
def error_response(request, status, code, message, headers=None):
rid = _rid(request)
out = {"X-Request-Id": rid, "X-Instance-Id": INSTANCE_ID, "Cache-Control": "no-store"}
out.update(headers or {})
return JSONResponse(status_code=status, content=make_error(code, message, rid), headers=out)
@app.middleware("http")
async def add_request_id(request: Request, call_next):
incoming = request.headers.get("X-Request-Id", "")
rid = incoming if _REQUEST_ID_RE.fullmatch(incoming) else uuid.uuid4().hex
request.state.request_id = rid
response = await call_next(request)
response.headers["X-Request-Id"] = rid
response.headers["X-Instance-Id"] = INSTANCE_ID
response.headers["Cache-Control"] = "no-store"
return response
@app.exception_handler(ApiError)
async def api_error_handler(request: Request, exc: ApiError):
return error_response(request, exc.status, exc.code, exc.message, exc.headers)
@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc):
return error_response(request, 400, "invalid_request", "Некорректный запрос")
@app.exception_handler(StarletteHTTPException)
async def http_exc_handler(request: Request, exc: StarletteHTTPException):
mapping = {404: ("not_found", "Объект не найден"), 405: ("invalid_request", "Метод не поддерживается")}
code, message = mapping.get(exc.status_code, ("invalid_request", "Ошибка запроса"))
return error_response(request, exc.status_code, code, message)
@app.exception_handler(Exception)
async def generic_handler(request: Request, exc: Exception):
if isinstance(exc, db.TRANSIENT):
log.warning("dependency unavailable [%s]: %s", _rid(request), type(exc).__name__)
return error_response(request, 503, "unavailable", "Сервис временно недоступен")
log.error("unhandled error [%s]", _rid(request), exc_info=exc)
return error_response(request, 500, "internal_error", "Внутренняя ошибка сервера")
class Auth(NamedTuple):
user: dict
user_id: uuid.UUID
digest: bytes
def authenticated(request: Request) -> Auth:
token = security.parse_bearer(request.headers.get("Authorization"))
if token is None:
raise unauthorized(BEARER_CHALLENGE)
found = sessions.lookup(token)
if found is None:
raise unauthorized(BEARER_CHALLENGE)
return Auth(found["user"], uuid.UUID(found["user"]["id"]), found["digest"])
class RawBody(NamedTuple):
content_type: str
data: bytes
async def raw_body(request: Request) -> RawBody:
declared = request.headers.get("content-length")
if declared is not None and declared.isdigit() and int(declared) > config.MAX_BODY_BYTES:
raise ApiError(413, "payload_too_large", "Тело запроса слишком большое")
chunks, size = [], 0
async for chunk in request.stream():
size += len(chunk)
if size > config.MAX_BODY_BYTES:
raise ApiError(413, "payload_too_large", "Тело запроса слишком большое")
chunks.append(chunk)
return RawBody(request.headers.get("content-type", ""), b"".join(chunks))
@app.get("/health/live")
def live():
return {"status": "ok"}
@app.get("/health/ready")
def ready():
try:
db.ping()
except Exception:
raise ApiError(503, "unavailable", "PostgreSQL недоступен")
try:
s3.ping()
except Exception:
raise ApiError(503, "unavailable", "S3 недоступен")
try:
if not broker.wait_ready(timeout=2):
raise ApiError(503, "unavailable", "Broker недоступен")
except ApiError:
raise
except Exception:
raise ApiError(503, "unavailable", "Broker недоступен")
return {"status": "ok"}
# ---------- пользователи / сессии / чаты ----------
@app.post("/api/v1/users", status_code=201)
def create_user(body: RawBody = Depends(raw_body)):
data = validation.json_body(body.content_type, body.data,
{"username", "display_name", "password"},
{"username", "display_name", "password"})
username = validation.username_field(data["username"])
display_name = validation.text_field(data["display_name"], "display_name", 1, 100)
password = validation.text_field(data["password"], "password", 12, 128)
with db.connection() as conn:
if repo.username_exists(conn, username):
raise ApiError(409, "conflict", "Имя пользователя занято")
password_hash = security.hash_password(password)
try:
with db.connection() as conn:
row = repo.insert_user(conn, username, display_name, password_hash)
except psycopg.errors.UniqueViolation:
raise ApiError(409, "conflict", "Имя пользователя занято")
return sessions.user_json(row)
@app.get("/api/v1/users/me")
def get_me(auth: Auth = Depends(authenticated)):
return auth.user
@app.post("/api/v1/auth/sessions", status_code=201)
def login(request: Request):
creds = security.parse_basic(request.headers.get("Authorization"))
if creds is None:
raise unauthorized(BASIC_CHALLENGE)
username, password = creds
with db.connection() as conn:
user = repo.user_for_login(conn, username) if validation._USERNAME_RE.fullmatch(username) else None
if user is None:
security.burn_verify(password)
raise unauthorized(BASIC_CHALLENGE)
ok, new_hash = security.verify_password(user["password_hash"], password)
if not ok:
raise unauthorized(BASIC_CHALLENGE)
with db.connection() as conn:
if new_hash:
repo.update_password_hash(conn, user["id"], new_hash)
token, expires_at = sessions.create(conn, user)
user_json = sessions.user_json(user)
sessions.warm(token, user_json, expires_at)
return {"token": token, "token_type": "Bearer",
"expires_at": sessions.fmt_ts(expires_at), "user": user_json}
@app.delete("/api/v1/auth/sessions/current")
def logout(auth: Auth = Depends(authenticated)):
sessions.revoke(auth.digest)
return Response(status_code=204)
@app.post("/api/v1/chats", status_code=201)
def create_chat(auth: Auth = Depends(authenticated), body: RawBody = Depends(raw_body)):
data = validation.json_body(body.content_type, body.data,
{"title", "member_ids"}, {"title", "member_ids"})
title = validation.text_field(data["title"], "title", 1, 100)
raw = data["member_ids"]
if not isinstance(raw, list) or not 1 <= len(raw) <= 100:
raise bad_request("member_ids: от 1 до 100 элементов")
members = [validation.require_uuid(x, "member_id") for x in raw]
if len(set(members)) != len(members) or auth.user_id not in members:
raise bad_request("member_ids должны быть уникальны и включать вызывающего")
with db.connection() as conn:
chat = repo.create_chat(conn, auth.user_id, title, members)
return repo.chat_json(chat)
@app.get("/api/v1/chats")
def list_chats(request: Request, auth: Auth = Depends(authenticated)):
limit = validation.limit_param(request.query_params)
raw = request.query_params.get("cursor")
after = cursor.decode(raw, "chats", auth.user_id) if raw is not None else None
with db.connection() as conn:
items, nxt = repo.list_chats(conn, auth.user_id, after, limit)
return {"items": items, "next_cursor": nxt}
@app.get("/api/v1/chats/{chat_id}")
def get_chat(chat_id: str, auth: Auth = Depends(authenticated)):
cid = validation.require_uuid(chat_id, "chat_id")
with db.connection() as conn:
chat = repo.get_chat(conn, cid, auth.user_id)
if chat is None:
raise not_found()
return repo.chat_json(chat)
# ---------- сообщения ----------
def _parse_attachment_ids(data):
raw = data.get("attachment_ids", [])
if not isinstance(raw, list) or len(raw) > 10:
raise bad_request("attachment_ids: до 10 элементов")
ids = [validation.require_uuid(x, "attachment_id") for x in raw]
if len(set(ids)) != len(ids):
raise bad_request("attachment_ids должны быть уникальны")
return ids
@app.post("/api/v1/chats/{chat_id}/messages", status_code=201)
def create_message(chat_id: str, request: Request, auth: Auth = Depends(authenticated),
body: RawBody = Depends(raw_body)):
cid = validation.require_uuid(chat_id, "chat_id")
with db.connection() as conn:
if not repo.is_member(conn, cid, auth.user_id):
raise not_found()
data = validation.json_body(body.content_type, body.data,
{"text", "attachment_ids"}, {"text"})
text = validation.text_field(data["text"], "text", 0, 4000, allow_blank=True)
attachment_ids = _parse_attachment_ids(data)
if not text.strip() and not attachment_ids:
raise bad_request("Пустое сообщение без вложений")
idem_key = request.headers.get("Idempotency-Key")
path = "/api/v1/chats/%s/messages" % chat_id
req_hash = idempotency.get_request_hash(data)
with db.connection() as conn:
idempotency.cleanup(conn, config.IDEMPOTENCY_TTL_SECONDS)
need_exec, cached = idempotency.check_and_lock(
conn, str(auth.user_id), "POST", path, idem_key, req_hash)
if not need_exec:
return JSONResponse(status_code=201, content=cached)
msg = repo.insert_message(conn, cid, auth.user_id, text, attachment_ids)
msg_json = repo.message_json(msg)
idempotency.save_result(conn, str(auth.user_id), "POST", path, idem_key,
req_hash, 201, msg_json)
return msg_json
@app.get("/api/v1/chats/{chat_id}/messages")
def list_messages(chat_id: str, request: Request, auth: Auth = Depends(authenticated)):
cid = validation.require_uuid(chat_id, "chat_id")
limit = validation.limit_param(request.query_params)
raw = request.query_params.get("cursor")
after = cursor.decode(raw, "messages", cid) if raw is not None else None
with db.connection() as conn:
if not repo.is_member(conn, cid, auth.user_id):
raise not_found()
items, nxt = repo.list_messages(conn, cid, after, limit)
return {"items": items, "next_cursor": nxt}
# ---------- вложения (lab5: 202 queued) ----------
@app.post("/api/v1/chats/{chat_id}/attachments", status_code=202)
async def upload_attachment(chat_id: str, request: Request, auth: Auth = Depends(authenticated)):
cid = validation.require_uuid(chat_id, "chat_id")
filename = request.query_params.get("filename")
if filename is None:
raise bad_request("filename обязателен")
declared = request.headers.get("content-type", "").split(";")[0].strip().lower()
if declared not in ("image/png", "image/jpeg"):
raise ApiError(415, "unsupported_media_type", "Ожидается image/png или image/jpeg")
def _check_member():
with db.connection() as conn:
return repo.is_member(conn, cid, auth.user_id)
if not await anyio.to_thread.run_sync(_check_member):
raise not_found()
declared_len = request.headers.get("content-length")
if declared_len is not None and declared_len.isdigit() and int(declared_len) > config.MAX_UPLOAD_BYTES:
raise ApiError(413, "payload_too_large", "Файл больше 10 MiB")
spool = tempfile.SpooledTemporaryFile(max_size=1024 * 1024)
hasher = hashlib.sha256()
total = 0
try:
async for chunk in request.stream():
total += len(chunk)
if total > config.MAX_UPLOAD_BYTES:
raise ApiError(413, "payload_too_large", "Файл больше 10 MiB")
hasher.update(chunk)
spool.write(chunk)
if total == 0:
raise bad_request("Пустой файл")
spool.seek(0)
digest = hasher.hexdigest()
def _process():
actual = attachments.inspect_image_header(spool, total)
if actual != declared:
raise ApiError(415, "unsupported_media_type", "MIME не соответствует содержимому")
return attachments.upload_to_staging(
cid, auth.user_id, filename, spool, total, digest, actual)
row = await anyio.to_thread.run_sync(_process)
return repo.attachment_json(row)
finally:
spool.close()
@app.get("/api/v1/attachments/{attachment_id}")
def get_attachment(attachment_id: str, auth: Auth = Depends(authenticated)):
aid = validation.require_uuid(attachment_id, "attachment_id")
with db.connection() as conn:
row = repo.get_attachment_for_member(conn, aid, auth.user_id)
if row is None:
raise not_found()
variants = repo.list_variants(conn, aid)
return repo.attachment_json(row, variants)
@app.get("/api/v1/attachments/{attachment_id}/content")
async def download_attachment(attachment_id: str, request: Request,
auth: Auth = Depends(authenticated)):
aid = validation.require_uuid(attachment_id, "attachment_id")
variant_name = request.query_params.get("variant", "original")
if variant_name not in ("original", "thumbnail", "crop", "optimized"):
raise bad_request("variant: original|thumbnail|crop|optimized")
def _read_all():
if variant_name == "original":
row, body = attachments.download_original(aid, auth.user_id)
try:
data = body.read()
finally:
body.close()
return row, data
v, body = attachments.download_variant(aid, auth.user_id, variant_name)
try:
data = body.read()
finally:
body.close()
return v, data
row, data = await anyio.to_thread.run_sync(_read_all)
if variant_name == "original":
headers = {"Content-Disposition": "attachment; filename*=UTF-8''%s" % quote(row["filename"], safe="")}
return Response(content=data, media_type=row["content_type"], headers=headers)
return Response(content=data, media_type=row["content_type"])
+44
View File
@@ -0,0 +1,44 @@
worker_processes auto;
events { worker_connections 1024; }
http {
# Nginx OSS резолвит DNS в upstream один раз при старте.
# Поэтому перечисляем обе реплики явно по DNS-именам контейнеров Compose.
upstream api_pool {
server messenger-lab6-api-1:8080 max_fails=1 fail_timeout=5s;
server messenger-lab6-api-2:8080 max_fails=1 fail_timeout=5s;
keepalive 16;
}
server {
listen 80;
location / {
proxy_pass http://api_pool;
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 Connection "";
# Retry только на connection errors/timeouts (backend не ответил).
proxy_next_upstream error timeout;
proxy_next_upstream_tries 2;
proxy_connect_timeout 2s;
# 15s вместо 60s: мёртвый backend помечается быстрее,
# failover укладывается в 10-секундный бюджет.
proxy_send_timeout 15s;
proxy_read_timeout 15s;
# 11m, а не 10m: пропускаем до backend, чтобы он сам вернул 413
# с X-Request-Id и телом ошибки. Верхний лимит 10 MiB — в приложении.
client_max_body_size 11m;
# ВАЖНО: on, а не off. С off nginx стримит тело в backend
# и не может повторить POST на живую реплику, если backend умер
# посреди запроса.
proxy_request_buffering on;
}
}
}
+2
View File
@@ -0,0 +1,2 @@
# Only for full OpenAPI/JSON Schema validation; HTTP tests use stdlib.
openapi-spec-validator==0.7.2
+37
View File
@@ -0,0 +1,37 @@
boto3==1.43.107
Pillow==12.3.0
annotated-types==0.8.0
anyio==4.15.1
argon2-cffi==25.1.0
argon2-cffi-bindings==26.1.0
cffi==2.1.1
click==8.5.0
fastapi==0.115.0
h11==0.16.0
httptools==0.9.0
idna==3.20
psycopg==3.2.9
psycopg-binary==3.2.9
psycopg-pool==3.2.6
pycparser==3.11
pydantic==2.14.1
pydantic_core==2.50.1
python-dotenv==1.2.4
PyYAML==6.0.3
redis==6.4.0
starlette==0.38.6
typing-inspection==0.4.4
typing_extensions==4.16.0
uvicorn==0.30.6
uvloop==0.23.0
watchfiles==1.3.0
websockets==17.2
pika==1.3.2
opentelemetry-api==1.27.0
opentelemetry-sdk==1.27.0
opentelemetry-exporter-otlp-proto-http==1.27.0
opentelemetry-instrumentation-fastapi==0.48b0
opentelemetry-instrumentation-psycopg==0.48b0
opentelemetry-instrumentation-botocore==0.48b0
opentelemetry-instrumentation-pika==0.48b0
opentelemetry-instrumentation-logging==0.48b0
+54
View File
@@ -0,0 +1,54 @@
#!/usr/bin/env python3
"""Offline structural checks; full schema validation is a separate target."""
import ast
import json
from pathlib import Path
import re
ROOT = Path(__file__).resolve().parents[1]
def main():
lab = json.loads((ROOT/'lab.json').read_text())['number']
spec = json.loads((ROOT/'contracts/openapi.json').read_text())
assert spec['openapi']=='3.1.0'
assert spec['info']['version']=='1.%d.0'%lab
operation_ids = set()
def walk(value):
if isinstance(value,dict):
if '$ref' in value:
pointer = value['$ref']
assert pointer.startswith('#/'), 'unexpected external reference'
target = spec
for part in pointer[2:].split('/'):
target = target[part.replace('~1','/').replace('~0','~')]
for v in value.values():
walk(v)
elif isinstance(value,list):
for v in value:
walk(v)
walk(spec)
for route,methods in spec['paths'].items():
placeholders = set(re.findall(r'\{([^}]+)\}',route))
for method,op in methods.items():
assert op['operationId'] not in operation_ids, 'duplicate operationId'
operation_ids.add(op['operationId'])
params = {p['name'] for p in op.get('parameters',[]) if p['in']=='path' and p.get('required')}
assert placeholders==params, 'path parameter mismatch: '+route
for response in op['responses'].values():
assert 'X-Request-Id' in response['headers']
if lab>=3:
assert 'X-Instance-Id' in response['headers']
assert ('/api/v1/auth/sessions' in spec['paths']) == (lab>=2)
assert ('/api/v1/attachments/{attachment_id}' in spec['paths']) == (lab>=4)
for file in list((ROOT/'tests').glob('*.py'))+list((ROOT/'scripts').glob('*.py')):
ast.parse(file.read_text(),filename=str(file))
for file in ROOT.rglob('*.json'):
if any(part in {'.git','.venv','node_modules','vendor','output'} for part in file.parts):
continue
json.loads(file.read_text())
for required in ('README.md','COURSE.md','CONTRIBUTING.md','REPORT.md','contracts/README.md','tests/smoke.py','tests/README.md'):
assert (ROOT/required).is_file(), 'missing '+required
print('PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.')
if __name__=='__main__':
main()
+56
View File
@@ -0,0 +1,56 @@
#!/bin/sh
set -eu
umask 077
cd "$(dirname "$0")/.."
mkdir -p secrets
gen() { head -c 32 /dev/urandom | base64 | tr -d '/+=\n' | cut -c1-32; }
ensure() {
f="secrets/$1"
if [ ! -s "$f" ]; then
printf '%s' "$2" > "$f"
chmod 600 "$f"
echo "created $f"
fi
}
PG_PASS=$(cat secrets/postgres_password 2>/dev/null || gen)
VALKEY_PASS=$(cat secrets/valkey_password 2>/dev/null || gen)
MINIO_ROOT_PASS=$(cat secrets/minio_root_password 2>/dev/null || gen)
S3_KEY=$(cat secrets/s3_access_key_id 2>/dev/null || "app$(gen | cut -c1-20)")
S3_SECRET=$(cat secrets/s3_secret_access_key 2>/dev/null || gen)
RMQ_PASS=$(cat secrets/rabbitmq_password 2>/dev/null || gen)
ensure postgres_password "$PG_PASS"
ensure valkey_password "$VALKEY_PASS"
ensure minio_root_user "minioadmin"
ensure minio_root_password "$MINIO_ROOT_PASS"
ensure s3_access_key_id "$S3_KEY"
ensure s3_secret_access_key "$S3_SECRET"
ensure rabbitmq_password "$RMQ_PASS"
ensure database_url "postgresql://messenger:${PG_PASS}@postgres:5432/messenger"
ensure cache_url "redis://:${VALKEY_PASS}@valkey:6379/0"
ensure broker_url "amqp://messenger:${RMQ_PASS}@rabbitmq:5672/%2F"
if [ ! -f .env ]; then
cat > .env <<'EOF'
APP_ENV=lab
SESSION_TTL_SECONDS=3600
SESSION_STORE=postgres+cache
SESSION_CACHE_TTL_SECONDS=60
IDEMPOTENCY_TTL_SECONDS=86400
API_REPLICAS=2
S3_REGION=us-east-1
S3_BUCKET=messenger-attachments
MAX_UPLOAD_BYTES=10485760
MAX_IMAGE_PIXELS=40000000
S3_ORPHAN_GRACE_SECONDS=3600
WORKER_CONCURRENCY=2
JOB_MAX_ATTEMPTS=5
JOB_TIMEOUT_SECONDS=60
STAGING_RETENTION_SECONDS=86400
EOF
echo "created .env"
fi
+115
View File
@@ -0,0 +1,115 @@
#!/usr/bin/env python3
"""Сверка S3 и метаданных PostgreSQL.
Классы проблем:
orphan_object — объект в S3 без строки attachments (или с pending > grace)
missing_object — attachments.status=ready, но объекта в S3 нет
failed_referenced — attachments.status=failed, объект всё ещё лежит в S3
Действия:
orphan_object → DELETE объекта (только старше grace)
missing_object → UPDATE status='failed', error_code='object_missing'
failed_referenced → DELETE объекта
Использование:
python scripts/reconcile_s3.py --dry-run
python scripts/reconcile_s3.py --apply
"""
import argparse
import sys
import time
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
from app import config, db, repo, s3 # noqa: E402
def _paginate(client, prefix):
"""Возвращает {key: last_modified}."""
token = None
out = {}
while True:
kwargs = {"Bucket": config.S3_BUCKET, "Prefix": prefix}
if token:
kwargs["ContinuationToken"] = token
resp = client.list_objects_v2(**kwargs)
for obj in resp.get("Contents", []):
out[obj["Key"]] = obj["LastModified"]
if not resp.get("IsTruncated"):
return out
token = resp["NextContinuationToken"]
def reconcile(dry_run: bool, grace_seconds: int):
client = s3._get_client()
now = time.time()
report = {"orphans_deleted": [], "orphans_skipped_fresh": [],
"missing_marked_failed": [], "failed_objects_deleted": []}
with db.connection() as conn:
rows = conn.execute(
"""SELECT id, object_key, status, created_at,
extract(epoch FROM created_at) AS created_epoch
FROM attachments""").fetchall()
by_key = {r["object_key"]: r for r in rows}
referenced = set(by_key)
for key, last_modified in _paginate(client, "originals/").items():
if key in referenced:
continue
age = now - last_modified.timestamp()
if age < grace_seconds:
report["orphans_skipped_fresh"].append(key)
continue
report["orphans_deleted"].append(key)
if not dry_run:
s3.delete_object(key)
for row in rows:
key = row["object_key"]
if row["status"] == "ready" and key not in _paginate(client, key):
report["missing_marked_failed"].append(key)
if not dry_run:
with db.connection() as conn:
conn.execute(
"""UPDATE attachments
SET status='failed', error_code='object_missing',
updated_at=clock_timestamp()
WHERE id=%s AND status='ready'""", (row["id"],))
elif row["status"] == "failed":
if key in _paginate(client, key):
report["failed_objects_deleted"].append(key)
if not dry_run:
s3.delete_object(key)
elif row["status"] == "pending":
age = now - float(row["created_epoch"])
if age >= grace_seconds and key in _paginate(client, key):
# pending дольше grace, а объект есть → API упал между S3 PUT и COMMIT
report["orphans_deleted"].append(key)
if not dry_run:
with db.connection() as conn:
repo.mark_attachment_failed(conn, row["id"], "orphaned_pending")
s3.delete_object(key)
import json
print(json.dumps(report, ensure_ascii=False, indent=2, default=str))
print("dry-run" if dry_run else "applied")
def main():
p = argparse.ArgumentParser()
p.add_argument("--apply", action="store_true")
p.add_argument("--dry-run", action="store_true")
p.add_argument("--grace-seconds", type=int, default=config.S3_ORPHAN_GRACE_SECONDS)
args = p.parse_args()
if args.apply and args.dry_run:
sys.exit("use --apply or --dry-run, not both")
if not (args.apply or args.dry_run):
sys.exit("choose --dry-run or --apply")
reconcile(dry_run=not args.apply, grace_seconds=args.grace_seconds)
if __name__ == "__main__":
main()
+28
View File
@@ -0,0 +1,28 @@
#!/usr/bin/env python3
"""Операторский replay failed-job. Запуск: python scripts/replay-failed.py <job_id>."""
import sys
import uuid
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
from app import db, jobs # noqa: E402
def main():
if len(sys.argv) != 2:
sys.exit("usage: replay-failed.py <job_id>")
try:
job_id = uuid.UUID(sys.argv[1])
except ValueError:
sys.exit("invalid job_id")
with db.connection() as conn:
payload = jobs.replay_failed(conn, job_id)
if payload is None:
sys.exit("job not found or not in failed state")
print("requeued:", payload["job_id"])
if __name__ == "__main__":
main()
+6
View File
@@ -0,0 +1,6 @@
@echo off
cd /d "%~dp0\.."
docker compose --env-file .env stop
timeout /t 2 /nobreak >nul
docker compose --env-file .env up -d
exit /b 0
+10
View File
@@ -0,0 +1,10 @@
#!/bin/sh
set -eu
# TODO: copy to restart.sh and implement using YOUR compose/stack services.
# Restart API and ALL used state stores (DB, sessions, S3, broker as applicable).
# Preserve persistent volumes and schema/data; never down -v / flush / re-seed.
# Allow operator unseal if required in lab7; do not print credentials.
# Exit 0 only after the intended action; test waits for API readiness separately.
printf '%s
' 'TODO: implement restart.sh for your infrastructure' >&2
exit 2
+17
View File
@@ -0,0 +1,17 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
docker compose --env-file .env stop
sleep 2
docker compose --env-file .env up -d
for i in $(seq 1 120); do
if curl -fs -o /dev/null http://127.0.0.1:8080/health/ready 2>/dev/null; then
echo "stack ready after ${i}s"
exit 0
fi
sleep 1
done
echo "stack not ready in 120s" >&2
exit 1
+19
View File
@@ -0,0 +1,19 @@
@echo off
REM Остановить одну API-реплику по её X-Instance-Id (== Hostname контейнера).
setlocal
if "%TARGET_INSTANCE_ID%"=="" (
echo TARGET_INSTANCE_ID is not set
exit /b 1
)
for /f "tokens=*" %%c in ('docker ps -q --filter "name=messenger-lab4-api"') do (
for /f "tokens=*" %%h in ('docker inspect -f "{{.Config.Hostname}}" %%c') do (
if "%%h"=="%TARGET_INSTANCE_ID%" (
echo Stopping container %%c
docker stop %%c
exit /b 0
)
)
)
echo Container with instance ID %TARGET_INSTANCE_ID% not found
exit /b 1
+10
View File
@@ -0,0 +1,10 @@
#!/bin/sh
set -eu
# TODO: copy to stop-one.sh, map TARGET_INSTANCE_ID to ONE API container/task.
# Stop that instance and leave it stopped; no stop of DB/LB/volumes.
# Return quickly (within 10 s); the test sends requests during this script.
# Restore the replica explicitly after the test. Never print credentials.
: "${TARGET_INSTANCE_ID:?test provides target API instance alias}"
printf '%s
' 'TODO: implement stop-one.sh for your infrastructure' >&2
exit 2
+30
View File
@@ -0,0 +1,30 @@
#!/bin/sh
# Останавливает конкретную реплику API по её X-Instance-Id.
set -eu
if [ -z "${TARGET_INSTANCE_ID:-}" ]; then
echo "TARGET_INSTANCE_ID is not set" >&2
exit 1
fi
# INSTANCE_ID = socket.gethostname(), в Docker это короткий ID контейнера.
cid=$(docker ps -q --filter "id=$TARGET_INSTANCE_ID" || true)
if [ -z "$cid" ]; then
# Fallback: искать по имени проекта и сверять hostname
for c in $(docker ps -q --filter "name=messenger-lab4"); do
h=$(docker inspect -f '{{.Config.Hostname}}' "$c")
if [ "$h" = "$TARGET_INSTANCE_ID" ]; then
cid="$c"
break
fi
done
fi
if [ -n "$cid" ]; then
echo "Stopping container $cid (Instance ID: $TARGET_INSTANCE_ID)"
docker stop "$cid"
else
echo "Container with instance ID $TARGET_INSTANCE_ID not found" >&2
exit 1
fi
+4
View File
@@ -0,0 +1,4 @@
@echo off
cd /d "%~dp0\.."
docker compose --env-file .env stop worker
echo worker stopped
+5
View File
@@ -0,0 +1,5 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")/.."
docker compose --env-file .env stop worker
echo "worker stopped"
+23
View File
@@ -0,0 +1,23 @@
#!/usr/bin/env python3
"""Full OpenAPI and JSON Schema checks; install requirements-dev.txt first."""
import json
from pathlib import Path
from openapi_spec_validator import validate
from jsonschema import Draft202012Validator
root = Path(__file__).resolve().parents[1]
spec = json.loads((root/'contracts/openapi.json').read_text())
validate(spec)
from referencing import Registry, Resource
# The base URI resolves local #/components references inside examples.
resource = dict(spec, **{'$schema': 'https://json-schema.org/draft/2020-12/schema'})
registry = Registry().with_resource('urn:mtusi:openapi', Resource.from_contents(resource))
for name, example in json.loads((root/'contracts/examples.json').read_text()).items():
schema = {'$ref': 'urn:mtusi:openapi#/components/schemas/' + name}
Draft202012Validator(schema, registry=registry).validate(example)
for path in (root/'contracts').glob('*.schema.json'):
schema = json.loads(path.read_text())
Draft202012Validator.check_schema(schema)
for example in schema.get('examples',[]):
Draft202012Validator(schema).validate(example)
print('PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.')
+148
View File
@@ -0,0 +1,148 @@
#!/usr/bin/env python3
"""Lab6: controlled incidents + observability correlation."""
import base64, hashlib, json, os, subprocess, sys, time, urllib.request
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "tests"))
from client import Client, Failure, arguments, check, run # noqa: E402
def prom(expr):
"""Запрос к Prometheus через docker exec."""
url = f"http://localhost:9090/api/v1/query?query={urllib.parse.quote(expr)}"
r = subprocess.run(
["docker", "compose", "--env-file", ".env", "exec", "-T", "prometheus",
"wget", "-qO-", url],
capture_output=True, text=True, cwd=ROOT, timeout=15)
if r.returncode != 0:
return None
try:
return json.loads(r.stdout)["data"]["result"]
except Exception:
return None
def compose(*args, timeout=120):
r = subprocess.run(["docker", "compose", "--env-file", ".env", *args],
capture_output=True, text=True, cwd=ROOT, timeout=timeout)
return r.returncode, r.stdout + r.stderr
def loki(service_name):
url = ("http://localhost:3100/loki/api/v1/query_range?"
"query=%7Bservice_name%3D%22" + service_name + "%22%7D&limit=5")
r = subprocess.run(
["docker", "compose", "--env-file", ".env", "exec", "-T", "loki",
"wget", "-qO-", url], capture_output=True, text=True, cwd=ROOT, timeout=15)
return r.stdout
def tempo():
r = subprocess.run(
["docker", "compose", "--env-file", ".env", "exec", "-T", "tempo",
"wget", "-qO-", "http://localhost:3200/api/search?limit=10"],
capture_output=True, text=True, cwd=ROOT, timeout=15)
return r.stdout
def main():
args = arguments("Lab6 controlled incidents")
c = Client(args.base_url, args.ca_file)
# 1. Smoke: данные текут.
alice, bob, eve, chat = c.bootstrap()
print("1. bootstrap OK, chat:", chat["id"])
att, _ = c.attachment(alice, chat)
ready = c.wait_ready(bob, att, wait_seconds=60)
check(ready["status"] == "ready", "worker pipeline not ready")
# 2. Метрики существуют.
jobs = prom('messenger_jobs_processed_total{outcome="ready"}')
check(jobs and len(jobs) > 0, "messenger_jobs_processed_total missing")
print("2. jobs metric OK:", jobs[0]["value"][1])
http_count = prom('sum(http_server_duration_milliseconds_count{http_target!~"/health/.*"})')
check(http_count and len(http_count) > 0, "http_server_duration_milliseconds_count missing")
print(" http metric OK:", http_count[0]["value"][1])
# 3. Корреляция trace → log.
l = loki("messenger-api")
check("trace_id" in l, "no trace_id in Loki logs")
print("3. Loki correlation OK (trace_id present in logs)")
t = tempo()
check("traces" in t and "messenger-api" in t, "no traces in Tempo")
print(" Tempo traces OK")
# 4. Инцидент 1: остановить worker → очередь растёт.
print("4. stopping worker...")
compose("stop", "worker", timeout=60)
time.sleep(2)
for _ in range(5):
c.attachment(alice, chat)
print(" 5 uploads queued")
# Ждём, пока alert станет firing (for: 2m).
firing = False
deadline = time.monotonic() + 200
while time.monotonic() < deadline:
time.sleep(15)
rules = subprocess.run(
["docker", "compose", "--env-file", ".env", "exec", "-T", "prometheus",
"wget", "-qO-", "http://localhost:9090/api/v1/rules"],
capture_output=True, text=True, cwd=ROOT, timeout=15).stdout
if '"name":"QueueLagHigh"' in rules and '"state":"firing"' in rules:
firing = True
break
check(firing, "QueueLagHigh did not reach firing")
print(" QueueLagHigh firing ✓")
# 5. Инцидент 2: восстановить worker → alert resolved.
print("5. starting worker...")
compose("start", "worker", timeout=60)
resolved = False
deadline = time.monotonic() + 180
while time.monotonic() < deadline:
time.sleep(15)
rules = subprocess.run(
["docker", "compose", "--env-file", ".env", "exec", "-T", "prometheus",
"wget", "-qO-", "http://localhost:9090/api/v1/rules"],
capture_output=True, text=True, cwd=ROOT, timeout=15).stdout
if ('"name":"QueueLagHigh"' in rules
and '"state":"inactive"' in rules.split('"name":"QueueLagHigh"')[1][:2000]):
resolved = True
break
check(resolved, "QueueLagHigh did not resolve after worker restart")
print(" QueueLagHigh resolved ✓")
# 6. Backlog рассосался.
time.sleep(5)
depth = prom("sum(messenger_queue_depth)")
if depth and depth[0]["value"][1]:
check(float(depth[0]["value"][1]) == 0.0, "queue not drained: " + depth[0]["value"][1])
print("6. queue drained")
# 7. Телеметрия-бэкенд недоступен → API продолжает работать.
print("7. stopping telemetry backends (loki, tempo)...")
compose("stop", "loki", "tempo", timeout=60)
time.sleep(3)
# smoke через API — должен пройти, несмотря на потерю traces/logs.
# В этом состоянии в api пойдёт WARN от exporter — но оно не падает.
a2, b2, e2, chat2 = c.bootstrap()
att2, _ = c.attachment(a2, chat2)
ready2 = c.wait_ready(b2, att2, wait_seconds=60)
check(ready2["status"] == "ready", "API broken when telemetry down")
print(" API still works with telemetry down ✓")
compose("start", "loki", "tempo", timeout=60)
time.sleep(10)
print("\nPASS: lab6 observability (metrics, traces, logs, alerts firing→resolved, telemetry-down resilience)")
if __name__ == "__main__":
run(main)
+57
View File
@@ -0,0 +1,57 @@
# Публичные проверки
Python **3.9+**, стандартная библиотека. Сервер уже должен быть запущен; проверки не создают готовое приложение и сами не управляют Docker. `make check` можно выполнить на исходном skeleton, `make test` — только после реализации API. Полная OpenAPI-валидация отдельно: `make validate` после установки `requirements-dev.txt` в venv.
```sh
make check
make test BASE_URL=http://localhost:8080
# без make:
python3 tests/smoke.py --base-url http://localhost:8080
```
`smoke.py` выполняет **один сквозной сценарий**, автоматически выбирая профиль из `lab.json`: health → три пользователя → вход с lab2 → чат → сообщения → пагинация → ошибки доступа → идемпотентность с lab3 → файл с lab4 → thumbnail с lab5 → logout. Он проверяет JSON по используемому подмножеству схемы, коды/headers, Unicode, SHA-256 оригинала и фактические JPEG-размеры thumbnail. Это публичный минимум, не полный fuzz/security/load suite.
Каждый запуск создаёт уникальных синтетических пользователей, чат и сообщения. Данные автоматически не удаляются: в API курса нет delete. Для чистого повтора используйте отдельный тестовый стенд/volume и осознанный сброс своего окружения. Session tokens хранятся только в памяти процесса и не печатаются/не сохраняются.
## Проверка сохранности, lab2+
Скопируйте `scripts/restart.example.sh` в `scripts/restart.sh`, реализуйте перезапуск **API и всех используемых хранилищ** с сохранением volumes и задайте executable bit. Скрипт может опираться на ваш compose.yaml или stack.yaml. Он не должен удалять volumes, повторно seed-ить БД или менять тестовые данные.
```sh
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
```
Тест создаёт данные и сессию, запускает указанный файл без shell interpolation, ожидает готовности и проверяет те же данные **с прежним токеном**. В lab4+ также проверяется исходный файл. Hook может работать до 90 секунд, готовность затем ожидается до 90 секунд. TTL сессии для этого теста — минимум 300 секунд. Успех не доказывает, что hook действительно перезапустил БД: приложите команды/состояния контейнеров до и после.
## Проверка отказа, lab3+
Реализуйте `scripts/stop-one.sh` на основе примера. `TARGET_INSTANCE_ID` в окружении содержит alias обслужившей тест API-реплики: сопоставьте его своему контейнеру/Swarm task и остановите именно его. Скрипт должен быстро вернуть 0 и **оставить эту реплику остановленной**; восстановление выполняйте отдельно. Swarm может создать новую task с другим ID — это допустимо.
```sh
chmod +x scripts/stop-one.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
```
Перед отказом тест наблюдает ≥2 API-реплики; 15 секунд отправляет сообщения параллельно выполнению hook, повторяет неопределённый POST с тем же ключом, проверяет восстановление записи за ≤10 секунд, отсутствие остановленной реплики в последних ответах, сохранность подтверждённых сообщений и отсутствие дублей. Ошибки переходного периода учитываются. Затем восстановите реплику и повторите для другой. Скрипт — проверка одного отказа API, не гарантия HA БД/LB/host. Вывод hook скрыт, чтобы не утекли секреты; отлаживайте его отдельно с безопасным выводом.
## Нагрузка
```sh
python3 tests/load.py --duration 30 --concurrency 4 --output evidence/load.json
```
Это простой **closed-loop** генератор POST сообщений; он ограничен производительностью клиента и страдает coordinated omission. Он выдаёт successful RPS, ошибки и p50/p95/p99 **только успешных запросов**. Во время нагрузки нет прозрачных retry; timeout мог скрыть совершённую запись, поэтому это throughput HTTP-подтверждений, не точный счётчик COMMIT. Изменение размера истории входит в профиль. Для серьёзного исследования используйте k6/Locust/wrk либо свой обоснованный генератор, а не выводите максимальную пропускную способность из одного запуска этого скрипта. Для нагрузки pipeline изображений нужен отдельный сценарий студента.
## HTTPS, lab7
```sh
make test BASE_URL=https://localhost:8443 CA_FILE=/absolute/path/to/ca.crt
make test-security BASE_URL=https://localhost:8443 CA_FILE=/absolute/path/to/ca.crt
```
Все скрипты принимают `--ca-file`/`CA_FILE` и проверяют серверный сертификат и hostname. `--insecure` отсутствует. TLS-тест сначала проверяет рабочее доверенное соединение, затем намеренно пустой trust store и именно ошибку проверки сертификата; network timeout не засчитывается как правильный отказ. **Внутреннее mTLS, identity/authorization, OpenBao policy и hardening проверяют отдельные тесты студента** по trust matrix. Клиентский сертификат внешнему учебному REST-клиенту не требуется: mTLS находится на внутренних связях.
## Что ещё остаётся доказать
Smoke не доказывает persistence, число реальных контейнеров, durability брокера, outbox, отсутствие утечек/уязвимостей, полноту telemetry или выполнение уровня 4/5. Конкурентные/нагрузочные/негативные проверки своего решения добавляйте отдельно. Список защиты текущей лабы находится в README.md. Проверки рассчитаны на localhost-стенд, не на production.
+217
View File
@@ -0,0 +1,217 @@
"""HTTP helpers for public black-box tests; Python 3.9+, standard library only."""
import base64
import datetime as dt
import hashlib
import json
import os
from pathlib import Path
import re
import ssl
import time
import urllib.error
import urllib.request
import uuid
ROOT = Path(__file__).resolve().parents[1]
LAB = json.loads((ROOT / 'lab.json').read_text())['number']
SPEC = json.loads((ROOT / 'contracts/openapi.json').read_text())
class Failure(AssertionError):
pass
def check(condition, message):
if not condition:
raise Failure(message)
def timestamp(value):
check(isinstance(value, str) and value.endswith('Z'), 'timestamp must be UTC ending in Z')
try:
return dt.datetime.fromisoformat(value[:-1] + '+00:00')
except ValueError as exc:
raise Failure('invalid RFC3339 timestamp') from exc
def validate(value, schema, where='response'):
"""Validate the JSON Schema subset used by the supplied contract, not arbitrary OpenAPI."""
if '$ref' in schema:
target = SPEC
for part in schema['$ref'].split('/')[1:]:
target = target[part]
return validate(value, target, where)
kinds = schema.get('type', [])
if isinstance(kinds, str):
kinds = [kinds]
matches = {'null':value is None, 'boolean':isinstance(value,bool), 'integer':isinstance(value,int) and not isinstance(value,bool), 'number':isinstance(value,(int,float)) and not isinstance(value,bool), 'string':isinstance(value,str), 'array':isinstance(value,list), 'object':isinstance(value,dict)}
if kinds:
check(any(matches.get(k,False) for k in kinds), where + ': incorrect type')
if 'enum' in schema:
check(value in schema['enum'], where + ': invalid enum')
if 'const' in schema:
check(value == schema['const'], where + ': invalid const')
if isinstance(value,dict):
props = schema.get('properties',{})
check(all(k in value for k in schema.get('required',[])), where + ': missing required fields')
if schema.get('additionalProperties') is False:
check(not set(value).difference(props), where + ': unexpected fields')
for key, sub in props.items():
if key in value:
validate(value[key], sub, where + '.' + key)
if isinstance(value,list):
check(len(value) >= schema.get('minItems',0), where + ': too few items')
check(len(value) <= schema.get('maxItems',float('inf')), where + ': too many items')
if schema.get('uniqueItems'):
encoded = [json.dumps(x,sort_keys=True) for x in value]
check(len(encoded)==len(set(encoded)), where + ': duplicate items')
if 'items' in schema:
for item in value:
validate(item, schema['items'], where + '[]')
if isinstance(value,str):
check(len(value) >= schema.get('minLength',0), where + ': too short')
check(len(value) <= schema.get('maxLength',float('inf')), where + ': too long')
if 'pattern' in schema:
check(re.search(schema['pattern'], value) is not None, where + ': pattern mismatch')
if schema.get('format') == 'uuid':
try:
uuid.UUID(value)
except ValueError as exc:
raise Failure(where + ': invalid UUID') from exc
if schema.get('format') == 'date-time':
timestamp(value)
if isinstance(value,(int,float)) and not isinstance(value,bool):
check(value >= schema.get('minimum',-float('inf')), where + ': below minimum')
check(value <= schema.get('maximum',float('inf')), where + ': above maximum')
if 'anyOf' in schema:
for alternative in schema['anyOf']:
try:
validate(value, alternative, where)
break
except Failure:
pass
else:
raise Failure(where + ': no anyOf branch matches')
def shape(value, name):
validate(value, SPEC['components']['schemas'][name])
return value
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
class Client:
def __init__(self, base_url=None, ca_file=None, timeout=10):
self.base = (base_url or os.environ.get('BASE_URL') or ('https://localhost:8443' if LAB==7 else 'http://localhost:8080')).rstrip('/')
check(self.base.startswith(('http://','https://')), 'BASE_URL must be HTTP(S)')
check(LAB != 7 or self.base.startswith('https://'), 'lab7 requires HTTPS')
self.timeout = timeout
context = ssl.create_default_context(cafile=ca_file or os.environ.get('CA_FILE') or None)
self.opener = urllib.request.build_opener(NoRedirect(), urllib.request.HTTPSHandler(context=context))
def call(self, method, path, expected=200, body=None, actor=None, headers=None, raw=None, schema=None):
h = {'Accept':'application/json'}
if actor:
h['X-User-Id' if LAB==1 else 'Authorization'] = actor['id'] if LAB==1 else 'Bearer ' + actor['token']
if body is not None:
raw = json.dumps(body,ensure_ascii=False).encode('utf-8')
h['Content-Type'] = 'application/json'
h.update(headers or {})
req = urllib.request.Request(self.base + path, data=raw, headers=h, method=method)
start = time.monotonic()
try:
response = self.opener.open(req, timeout=self.timeout)
except urllib.error.HTTPError as error:
response = error
except (urllib.error.URLError,TimeoutError,OSError) as exc:
# Do not print URL query, headers, request body, or credentials.
raise Failure(method + ' ' + path.split('?')[0] + ': connection/TLS failure (' + type(exc).__name__ + ')') from None
with response:
status = response.code
rh = response.headers
data = response.read(16*1024*1024 + 1)
check(len(data) <= 16*1024*1024, 'response exceeds test safety limit')
allowed = [expected] if isinstance(expected,int) else expected
check(status in allowed, method + ' ' + path.split('?')[0] + ': expected ' + str(allowed) + ', received ' + str(status))
check(bool(rh.get('X-Request-Id')), 'missing X-Request-Id')
if LAB>=3:
check(bool(rh.get('X-Instance-Id')), 'missing X-Instance-Id')
payload = None
if schema or status>=400:
check(rh.get_content_type()=='application/json', 'expected application/json')
try:
payload = json.loads(data)
except (ValueError,UnicodeError):
raise Failure('invalid response JSON') from None
shape(payload, 'Error' if status>=400 else schema)
if status>=400:
check(payload['error']['request_id']==rh.get('X-Request-Id'),'error request_id differs from header')
if status==401 and LAB>=2:
scheme = 'Basic' if path=='/api/v1/auth/sessions' else 'Bearer'
check(rh.get('WWW-Authenticate','').lower().startswith(scheme.lower()), 'incorrect WWW-Authenticate challenge')
if status==204:
check(not data, '204 must not contain body')
return {'status':status,'headers':rh,'json':payload,'bytes':data,'elapsed':time.monotonic()-start}
def user(self, label):
username = 'u_' + label + '_' + uuid.uuid4().hex[:12]
password = 'T3st-' + uuid.uuid4().hex
body = {'username':username,'display_name':'Студент ' + label}
if LAB>=2:
body['password'] = password
user = self.call('POST','/api/v1/users',201,body=body,schema='User')['json']
check(user['username']==username,'username changed')
actor = {'id':user['id'],'user':user,'registration':body}
if LAB>=2:
credential = base64.b64encode((username+':'+password).encode()).decode()
session = self.call('POST','/api/v1/auth/sessions',201,headers={'Authorization':'Basic '+credential},schema='Session')['json']
check(session['user']==user,'session user mismatch')
check(timestamp(session['expires_at']) > dt.datetime.now(dt.timezone.utc),'session already expired')
actor['token'] = session['token']
return actor
def bootstrap(self):
self.call('GET','/health/live',schema='Health')
self.call('GET','/health/ready',schema='Health')
alice, bob, eve = (self.user(label) for label in ('alice','bob','eve'))
chat = self.call('POST','/api/v1/chats',201,actor=alice,body={'title':'Контрактный тест','member_ids':[alice['id'],bob['id']]},schema='Chat')['json']
check(set(chat['member_ids'])=={alice['id'],bob['id']},'chat member mismatch')
return alice,bob,eve,chat
def message(self, actor, chat, text, key=None, attachments=None):
body = {'text':text}
if attachments is not None:
body['attachment_ids'] = attachments
headers = {'Idempotency-Key':key or uuid.uuid4().hex} if LAB>=3 else {}
return self.call('POST','/api/v1/chats/'+chat['id']+'/messages',201,actor=actor,body=body,headers=headers,schema='Message')
def attachment(self, actor, chat):
content = (ROOT / 'tests/fixtures/sample.png').read_bytes()
att = self.call('POST','/api/v1/chats/'+chat['id']+'/attachments?filename=sample.png',201 if LAB==4 else 202,actor=actor,raw=content,headers={'Content-Type':'image/png'},schema='Attachment')['json']
check(att['status']==('ready' if LAB==4 else 'queued'),'incorrect upload status')
check(att['chat_id']==chat['id'] and att['owner_id']==actor['id'],'attachment ownership mismatch')
check(att['sha256']==hashlib.sha256(content).hexdigest() and att['size_bytes']==len(content),'original checksum/size mismatch')
return att,content
def wait_ready(self, actor, att, wait_seconds=60):
deadline = time.monotonic()+wait_seconds
while time.monotonic()<deadline:
att = self.call('GET','/api/v1/attachments/'+att['id'],actor=actor,schema='Attachment')['json']
check(att['status']!='failed','attachment reached failed')
if att['status']=='ready':
return att
time.sleep(0.3)
raise Failure('attachment did not become ready within test deadline')
def arguments(description, configure=None):
import argparse
p = argparse.ArgumentParser(description=description)
p.add_argument('--base-url', default=None)
p.add_argument('--ca-file', default=None)
if configure:
configure(p)
return p.parse_args()
def run(main):
try:
main()
except (Failure,ValueError,OSError) as exc:
print('FAIL:', str(exc))
raise SystemExit(1)
+9
View File
@@ -0,0 +1,9 @@
# Синтетический fixture
sample.png: RGB PNG 320×200, создан программно специально для курса, без персональных данных и EXIF. Можно свободно использовать и менять в собственных тестах; исходный публичный fixture сохраните.
- Размер: 111817 байт.
- SHA-256: `99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75`.
- Обязательный thumbnail с lab5: JPEG 256×160.
Проверяющий читает SHA-256 оригинала, metadata вариантов и реальные размеры JPEG, а не только JSON-обещание сервера. Повреждённые, oversized и decompression-bomb fixtures для собственного negative suite создавайте отдельно; не храните огромные файлы в Git.
BIN
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 109 KiB

+26
View File
@@ -0,0 +1,26 @@
"""Read JPEG SOF dimensions without external libraries; not a full image decoder."""
from client import Failure, check
def jpeg_size(data):
check(data[:2]==b'\xff\xd8','thumbnail is not JPEG')
i = 2
sof = {0xc0,0xc1,0xc2,0xc3,0xc5,0xc6,0xc7,0xc9,0xca,0xcb,0xcd,0xce,0xcf}
while i < len(data):
check(data[i]==0xff,'invalid JPEG marker')
while i<len(data) and data[i]==0xff:
i += 1
check(i<len(data),'truncated JPEG marker')
marker = data[i]
i += 1
if marker in {0xd9,0xda}:
break
if marker in {0x01,0xd8} or 0xd0<=marker<=0xd7:
continue
check(i+2<=len(data),'truncated JPEG segment')
length = int.from_bytes(data[i:i+2],'big')
check(length>=2 and i+length<=len(data),'invalid JPEG segment length')
if marker in sof:
check(length>=8,'invalid JPEG SOF')
return (int.from_bytes(data[i+5:i+7],'big'),int.from_bytes(data[i+3:i+5],'big'))
i += length
raise Failure('JPEG dimensions not found')
+58
View File
@@ -0,0 +1,58 @@
#!/usr/bin/env python3
"""Small closed-loop HTTP write benchmark; not an open-loop capacity proof."""
from concurrent.futures import ThreadPoolExecutor
import json
import math
from pathlib import Path
import threading
import time
from client import Client, Failure, LAB, arguments, check, run
def main():
def configure(p):
p.add_argument('--duration',type=float,default=30)
p.add_argument('--concurrency',type=int,default=4)
p.add_argument('--output',default=None,help='Optional JSON metrics, no session tokens')
args = arguments('Synthetic POST message load, closed loop; creates users/messages',configure)
check(1<=args.duration<=3600,'duration must be 1..3600 seconds')
check(1<=args.concurrency<=128,'concurrency must be 1..128')
c = Client(args.base_url,args.ca_file)
alice,bob,eve,chat = c.bootstrap()
barrier = threading.Barrier(args.concurrency)
def worker(worker_id):
local = Client(args.base_url,args.ca_file,timeout=5)
barrier.wait()
deadline = time.monotonic()+args.duration
latencies,errors = [],0
index = 0
while time.monotonic()<deadline:
start = time.monotonic()
try:
local.message(alice,chat,'load-%s-%s' % (worker_id,index))
latencies.append(time.monotonic()-start)
except Failure:
errors += 1
index += 1
return latencies,errors
started = time.monotonic()
with ThreadPoolExecutor(max_workers=args.concurrency) as pool:
results = list(pool.map(worker,range(args.concurrency)))
elapsed = time.monotonic()-started
latencies = sorted(x for values,_ in results for x in values)
errors = sum(n for _,n in results)
total = len(latencies)+errors
def percentile(p):
return round(1000*latencies[max(0,math.ceil(p*len(latencies))-1)],3) if latencies else None
report = {'lab':LAB,'workload':'closed-loop POST messages; no automatic retries','requested_duration_seconds':args.duration,'elapsed_seconds':round(elapsed,3),'concurrency':args.concurrency,'successful_requests':len(latencies),'failed_requests':errors,'error_ratio':round(errors/total,6) if total else None,'successful_rps':round(len(latencies)/elapsed,3),'successful_latency_ms':{'p50':percentile(.50),'p95':percentile(.95),'p99':percentile(.99)},'note':'Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead.'}
text = json.dumps(report,ensure_ascii=False,indent=2)
if args.output:
dest = Path(args.output)
dest.parent.mkdir(parents=True,exist_ok=True)
dest.write_text(text+'\n')
print(text)
check(bool(latencies),'no successful writes')
# Errors are reported, not treated as a universal load-test threshold.
if __name__=='__main__':
run(main)
+129
View File
@@ -0,0 +1,129 @@
#!/usr/bin/env python3
"""Explicit operator-authored hook; tokens remain in memory, volumes are never removed by this test."""
import json
import os
from pathlib import Path
import subprocess
import time
import uuid
from urllib.parse import quote
from client import Client, Failure, LAB, arguments, check, run
def history(c, actor, chat):
path = '/api/v1/chats/'+chat['id']+'/messages?limit=100'
result = []
seen = set()
for _ in range(1000):
page = c.call('GET',path,actor=actor,schema='MessagePage')['json']
result.extend(page['items'])
cursor = page['next_cursor']
if cursor is None:
return result
check(cursor not in seen,'cursor cycle')
seen.add(cursor)
path = '/api/v1/chats/'+chat['id']+'/messages?limit=100&cursor='+quote(cursor,safe='')
raise Failure('history pagination exceeded safety bound')
def main():
def configure(p):
p.add_argument('--mode', choices=['persistence','failover'], required=True)
p.add_argument('--action-script',required=True,help='Executable script authored by student; restarts stack or stops ONE API replica')
args = arguments('Explicit restart/failover scenario; modifies only synthetic API data',configure)
check(LAB>=2,'persistence requires lab2+')
check(args.mode!='failover' or LAB>=3,'failover requires lab3+')
script = Path(args.action_script).expanduser().resolve()
check(script.is_file() and os.access(script,os.X_OK),'action script must exist and be executable (chmod +x)')
check('.example.' not in script.name,'copy and implement the example hook first')
c = Client(args.base_url,args.ca_file,timeout=2)
alice,bob,eve,chat = c.bootstrap()
sent = c.message(alice,chat,'Сохранить при отказе')
original = sent['json']
target = sent['headers'].get('X-Instance-Id','')
attachment = content = None
if LAB>=4:
attachment,content = c.attachment(alice,chat)
if LAB>=5:
attachment = c.wait_ready(alice,attachment)
env = dict(os.environ)
env['TARGET_INSTANCE_ID'] = target
observed = set()
if args.mode=='failover':
for _ in range(40):
observed.add(c.call('GET','/api/v1/users/me',actor=alice,schema='User')['headers']['X-Instance-Id'])
check(len(observed)>=2,'less than two API instances observed before failure; verify LB/session affinity')
print('Executing explicit '+args.mode+' hook; hook output suppressed to avoid leaking secrets.')
# No shell interpolation and no Docker commands in this test.
proc = subprocess.Popen([str(script)],env=env,stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)
started = time.monotonic()
successes,failures,after_instances = [],0,[]
try:
if args.mode=='persistence':
try:
code = proc.wait(timeout=90)
except subprocess.TimeoutExpired:
raise Failure('restart hook exceeded 90 seconds') from None
check(code==0,'restart hook failed (inspect your script locally)')
deadline = time.monotonic()+90
while True:
try:
c.call('GET','/health/ready',schema='Health')
c.call('GET','/api/v1/users/me',actor=alice,schema='User')
break
except Failure:
check(time.monotonic()<deadline,'stack/session did not recover within 90 seconds')
time.sleep(0.5)
else:
first_recovery = None
key = uuid.uuid4().hex
text = 'Запись во время отказа ' + key
while time.monotonic()-started < 15:
code = proc.poll()
check(code is None or code==0,'stop-one hook failed (inspect your script locally)')
check(code is not None or time.monotonic()-started<10,'stop-one hook must return within 10 seconds')
try:
response = c.message(alice,chat,text,key=key)
msg = response['json']
if code==0:
if first_recovery is None:
first_recovery = time.monotonic()-started
after_instances.append(response['headers']['X-Instance-Id'])
successes.append(msg)
key = uuid.uuid4().hex
text = 'Запись во время отказа ' + key
except Failure:
failures += 1
# Keep SAME key/body after an uncertain POST result.
time.sleep(0.1)
check(proc.poll()==0,'stop-one hook did not finish successfully')
check(first_recovery is not None and first_recovery<=10,'writes did not recover within 10 seconds from hook start')
check(len(after_instances)>=5,'too few successful writes after stop')
check(target not in after_instances[-5:],'target replica still serves requests; hook must leave it stopped')
print(json.dumps({'observed_instances_before':len(observed),'successful_writes':len(successes),'failed_attempts':failures,'first_recovery_seconds':round(first_recovery,3)},ensure_ascii=False))
# Existing token, no re-login. Read all confirmations and reject duplicates.
messages = history(c,bob,chat)
ids = [m['id'] for m in messages]
check(len(ids)==len(set(ids)),'duplicated message IDs in history')
check(any(m==original for m in messages),'confirmed pre-failure message lost or altered')
for msg in successes:
check(any(m==msg for m in messages),'confirmed in-flight message lost or altered')
# Bodies are unique in this scenario: an uncertain request may exist once, never twice.
texts = [m['text'] for m in messages]
check(len(texts)==len(set(texts)),'uncertain retry created duplicate message')
if attachment:
c.call('GET','/api/v1/attachments/'+attachment['id'],actor=bob,schema='Attachment')
downloaded = c.call('GET','/api/v1/attachments/'+attachment['id']+'/content',actor=bob)
check(downloaded['bytes']==content,'attachment lost or changed across failure')
print('PASS: '+args.mode+' preserved confirmed data and existing session. Hook scope needs operator evidence.')
finally:
if proc.poll() is None:
proc.terminate()
try:
proc.wait(timeout=5)
except subprocess.TimeoutExpired:
proc.kill()
proc.wait()
if __name__=='__main__':
run(main)
+82
View File
@@ -0,0 +1,82 @@
#!/usr/bin/env python3
"""One complete public acceptance scenario, cumulative by lab number."""
import base64
import hashlib
import uuid
from client import Client, LAB, arguments, check, run, timestamp
def main():
args = arguments('Messenger public smoke; creates synthetic users and messages')
c = Client(args.base_url,args.ca_file)
alice,bob,eve,chat = c.bootstrap()
path = '/api/v1/chats/'+chat['id']
c.call('POST','/api/v1/users',409,body=alice['registration'])
c.call('GET','/api/v1/users/me',401)
c.call('GET',path,404,actor=eve)
me = c.call('GET','/api/v1/users/me',actor=alice,schema='User')['json']
check(me==alice['user'],'current user mismatch')
listed = c.call('GET','/api/v1/chats?limit=100',actor=bob,schema='ChatPage')['json']
check(any(x['id']==chat['id'] for x in listed['items']),'member cannot list chat')
hidden = c.call('GET','/api/v1/chats?limit=100',actor=eve,schema='ChatPage')['json']
check(all(x['id']!=chat['id'] for x in hidden['items']),'chat leaks to outsider')
key = uuid.uuid4().hex
first = c.message(alice,chat,'Привет, мир 👋',key=key)['json']
second = c.message(bob,chat,'Сообщение Боба')['json']
check(first['sender_id']==alice['id'] and second['sender_id']==bob['id'],'sender was not derived from actor')
check(first['chat_id']==second['chat_id']==chat['id'],'wrong chat in message')
check(first['text']=='Привет, мир 👋' and second['text']=='Сообщение Боба','message text changed')
page1 = c.call('GET',path+'/messages?limit=1',actor=bob,schema='MessagePage')['json']
check(len(page1['items'])==1 and page1['next_cursor'],'first page must have one item and cursor')
from urllib.parse import quote
page2 = c.call('GET',path+'/messages?limit=1&cursor='+quote(page1['next_cursor'],safe=''),actor=alice,schema='MessagePage')['json']
check(len(page2['items'])==1 and page2['next_cursor'] is None,'second page must finish history')
ordered = sorted([first,second],key=lambda x:(timestamp(x['created_at']),uuid.UUID(x['id']).int))
check(page1['items']+page2['items']==ordered,'pagination lost, duplicated or reordered a message')
h = {'Idempotency-Key':uuid.uuid4().hex} if LAB>=3 else {}
c.call('POST',path+'/messages',400,actor=alice,body={'text':''},headers=h)
c.call('POST',path+'/messages',404,actor=eve,body={'text':'чужое'},headers=h)
c.call('GET',path+'/messages?limit=0',400,actor=alice)
if LAB>=2:
bad = base64.b64encode((alice['registration']['username']+':wrong-password').encode()).decode()
c.call('POST','/api/v1/auth/sessions',401,headers={'Authorization':'Basic '+bad})
good = base64.b64encode((alice['registration']['username']+':'+alice['registration']['password']).encode()).decode()
c.call('GET','/api/v1/users/me',401,headers={'Authorization':'Basic '+good})
c.call('GET','/api/v1/users/me',401,headers={'X-User-Id':alice['id']})
me = c.call('GET','/api/v1/users/me',actor=alice,headers={'X-User-Id':eve['id']},schema='User')['json']
check(me['id']==alice['id'],'X-User-Id overrode bearer identity')
if LAB>=3:
replay = c.message(alice,chat,first['text'],key=key)['json']
check(replay==first,'idempotency replay differs')
c.call('POST',path+'/messages',409,actor=alice,body={'text':'другой body'},headers={'Idempotency-Key':key})
c.call('POST',path+'/messages',400,actor=alice,body={'text':'без ключа'})
if LAB>=4:
att,content = c.attachment(alice,chat)
# A queued attachment must already be linkable to its own chat.
attached = c.message(alice,chat,'',attachments=[att['id']])['json']
check(attached['attachment_ids']==[att['id']],'message lost attachment')
ready = c.wait_ready(bob,att) if LAB>=5 else att
check(ready['error_code'] is None,'ready attachment has an error')
download = c.call('GET','/api/v1/attachments/'+att['id']+'/content',actor=bob)
check(download['bytes']==content,'download differs from original')
check(download['headers'].get_content_type()=='image/png','original content type mismatch')
for suffix in ('','/content'):
c.call('GET','/api/v1/attachments/'+att['id']+suffix,404,actor=eve)
if LAB>=5:
variants = [x for x in ready['variants'] if x['name']=='thumbnail']
check(len(variants)==1,'expected exactly one thumbnail')
v = variants[0]
check((v['width'],v['height'])==(256,160),'thumbnail metadata has wrong dimensions')
thumb = c.call('GET','/api/v1/attachments/'+att['id']+'/content?variant=thumbnail',actor=bob)
check(thumb['headers'].get_content_type()=='image/jpeg','thumbnail content type mismatch')
check(len(thumb['bytes'])==v['size_bytes'] and hashlib.sha256(thumb['bytes']).hexdigest()==v['sha256'],'thumbnail checksum mismatch')
from image_probe import jpeg_size
check(jpeg_size(thumb['bytes'])==(256,160),'actual JPEG dimensions mismatch')
if LAB>=2:
c.call('DELETE','/api/v1/auth/sessions/current',204,actor=alice)
c.call('GET','/api/v1/users/me',401,actor=alice)
c.call('DELETE','/api/v1/auth/sessions/current',401,actor=alice)
print('PASS: lab%d public API scenario; infrastructure and grading evidence remain separate.' % LAB)
if __name__=='__main__':
run(main)