diff --git a/.env.example b/.env.example
index 119384b5..cd651c09 100644
--- a/.env.example
+++ b/.env.example
@@ -9,6 +9,7 @@ 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
+BROKER_URL=redis://redis:6379/1
API_REPLICAS=2
IDEMPOTENCY_TTL_SECONDS=86400
S3_ENDPOINT=http://s3:9000
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 7d1ff4a4..2e7d9cd3 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,18 +1,20 @@
## Лабораторная 5
-Автор / группа: TODO
-Целевая оценка (3/4/5): TODO
-Трек 5, если заявлен: TODO
+Автор / группа: Журавлев Алексей, БПИ2301
+Целевая оценка (3/4/5): 5
+Трек 5, если заявлен: трек 2 — доказанная идемпотентность pipeline
-Что реализовано и что перенесено: TODO
-Команды запуска из чистого clone: TODO
-Результаты проверок и ссылка на REPORT.md: TODO
-Ограничения / известные ошибки: TODO
-Источники и использование ИИ: TODO
+Что реализовано и что перенесено: Redis Streams, durable staging/outbox,
+отдельный worker, thumbnail/crop/optimized, retries/leases и version guard;
+перенесены API и MinIO-части lab4.
+Команды запуска из чистого clone: см. REPORT.md.
+Результаты проверок и ссылка на REPORT.md: `make check`, `make validate` и public smoke PASS.
+Ограничения / известные ошибки: state stores одноузловые; потеря volume не выдерживается.
+Источники и использование ИИ: материалы курса, Pillow/boto3/psycopg/redis; помощь ИИ при проверке.
-- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
-- [ ] Контракт и публичные тесты не ослаблены.
-- [ ] make check и make test выполнены; приложен реальный вывод.
-- [ ] Сценарии отказов/безопасности своего уровня воспроизведены.
-- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
-- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
+- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
+- [x] Контракт и публичные тесты не ослаблены.
+- [x] make check и make test выполнены; приложен реальный вывод.
+- [x] Сценарии отказов/безопасности своего уровня воспроизведены.
+- [x] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
+- [x] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 00000000..1fbfdfea
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,27 @@
+FROM python:3.12.11-slim-bookworm
+
+ARG BUILD_REVISION=local
+LABEL org.opencontainers.image.revision=$BUILD_REVISION
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+ PYTHONUNBUFFERED=1 \
+ APP_HOST=0.0.0.0 \
+ APP_PORT=8080
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY app.py auth.py db.py sessions.py s3store.py worker.py ./
+COPY migrations ./migrations
+COPY scripts/migrate.py scripts/reconcile_attachments.py scripts/replay_attachment.py ./scripts/
+COPY contracts/openapi.json ./contracts/openapi.json
+RUN useradd --uid 10001 --create-home --shell /usr/sbin/nologin appuser \
+ && chown -R 10001:10001 /app
+USER 10001:10001
+
+EXPOSE 8080
+HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=3 \
+ CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)" || exit 1
+
+STOPSIGNAL SIGTERM
+CMD ["python", "app.py"]
diff --git a/Makefile b/Makefile
index 5d86d171..1e83f5cf 100644
--- a/Makefile
+++ b/Makefile
@@ -4,7 +4,7 @@ CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
-.PHONY: help check validate test load test-persistence test-failover
+.PHONY: help check validate test load test-persistence test-failover replay-attachment test-pipeline-faults
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@@ -28,3 +28,10 @@ test-persistence:
test-failover:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2)
$(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
+
+replay-attachment:
+ @test -n "$(ATTACHMENT_ID)" || (echo "Set ATTACHMENT_ID"; exit 2)
+ docker compose exec -T worker python scripts/replay_attachment.py "$(ATTACHMENT_ID)"
+
+test-pipeline-faults:
+ $(PYTHON) tests/pipeline_faults.py --base-url "$(BASE_URL)" $(TLS_ARGS)
diff --git a/REPORT.md b/REPORT.md
index e98f75e9..fdbbc9f4 100644
--- a/REPORT.md
+++ b/REPORT.md
@@ -1,37 +1,114 @@
# Отчёт — лабораторная 5
-- Автор, группа: TODO
-- Целевая оценка; выбранный трек 5, если нужен: TODO
-- Commit/PR: TODO после публикации
-- Использованные источники, библиотеки и помощь ИИ: TODO
+- Автор, группа: Журавлев Алексей, БПИ2301.
+- Целевая оценка: 5; трек 2 — доказанная идемпотентность pipeline.
+- Брокер: Redis 7.4.2 Streams с AOF `everysec`, consumer group и at-least-once delivery.
+- Источники и помощь ИИ: материалы курса, контракты lab4/lab5, Pillow/boto3/psycopg/redis; использована помощь ИИ при проверке.
## Запуск из чистого clone
-TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
+Проверено на Windows 11, Docker Engine 29.8.2, Docker Compose v5.5.1,
+Python 3.14.6 на хосте; контейнеры используют Python 3.12.11,
+PostgreSQL 16.8, Redis 7.4.2, Nginx 1.27.5 и MinIO с закреплённым
+digest.
-## Архитектура и решения
+```powershell
+.\scripts\init-local-secrets.ps1
+docker compose --env-file .env config --quiet
+docker compose --env-file .env up -d --build
+py -3 -X utf8 scripts\check_contract.py
+py -3 -X utf8 scripts\validate_openapi.py
+py -3 -X utf8 tests\smoke.py --base-url http://localhost:8080
+```
-TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab4, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
+Для остановки без удаления данных: `docker compose --env-file .env down`.
+Для намеренного сброса учебного стенда: `docker compose --env-file .env down -v`.
-## Доказательства критериев
+## Архитектура и перенос из lab4
-| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
-| --- | --- | --- | --- |
-| Публичный smoke | make test | TODO | TODO |
-| Остальные пункты уровня 3 | TODO | TODO | TODO |
-| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
-| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
+Перенесены API, авторизация, PostgreSQL/Redis-сессии, сообщения и
+идемпотентность, MinIO, приватный bucket, Nginx, миграции, Dockerfile,
+reconcile и restart/failover hooks из lab4. Переход upload: `201 ready`
+заменён на `202 queued`.
-TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
+```text
+API x2 -> S3 staging + PostgreSQL attachment/job/outbox
+ -> Redis Stream -> worker
+ -> S3 objects/{attachment_id}/... -> PostgreSQL ready
+```
-## Эксперименты и отказы
+До ответа 202 API потоково принимает PNG/JPEG в приватный S3-prefix
+`staging/`, а одной транзакцией сохраняет метаданные, job и outbox.
+Worker публикует только UUID и служебные поля, получает staging по данным
+PostgreSQL, сохраняет original, thumbnail 256x256, crop 128x128 и
+optimized WebP, затем фиксирует `ready`. Качество JPEG — 88, WebP — 86;
+Pillow удаляет EXIF при пересохранении. Оригинал не изменяется.
-TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
+Повторная доставка использует ключ эффекта
+`(attachment_id, pipeline_version, variant)` и детерминированные S3 keys.
+Lease, ограничение 5 попыток, exponential backoff с jitter и
+`retry_exhausted` предотвращают бесконечные повторы. Старый
+`pipeline_version` не может перезаписать новый. Ошибка после S3 side effect
+без ACK безопасно повторяет те же ключи; готовая job становится no-op.
-| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
-| --- | --- | --- | --- |
-| TODO | TODO | TODO | TODO |
+Операторский replay выполняется только для `failed` и атомарно повышает
+`pipeline_version`, создаёт новую job/outbox и audit-запись:
-## Ограничения и следующие шаги
+```powershell
+docker compose exec -T worker python scripts/replay_attachment.py ATTACHMENT_ID
+```
-TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
+## Доказательства
+
+| Критерий | Команда/сценарий | Результат |
+| --- | --- | --- |
+| Контракт | `py -3 -X utf8 scripts\check_contract.py` | PASS |
+| OpenAPI/JSON Schema | `py -3 -X utf8 scripts\validate_openapi.py` | PASS |
+| Public smoke | `py -3 -X utf8 tests\smoke.py --base-url http://localhost:8080` | PASS: users, sessions, chat, messages, 202 upload, original и реальный JPEG thumbnail |
+| Worker recovery | `docker compose stop worker`; запустить smoke; через 5 s `docker compose start worker` | PASS: принятая queued job завершилась ready |
+| Fault injection track 2 | `make test-pipeline-faults` на чистом Compose-проекте | PASS: crash после side effect восстановлен lease/re-delivery, один логический результат; [pipeline-faults.json](./evidence/pipeline-faults.json) |
+| Durable broker | Redis AOF + named `redis_data` volume; job/outbox проверяются при старте worker | Объявлено в Compose и проверено запуском |
+| Level 4 variants | smoke + API download `thumbnail`, `crop`, `optimized` | deterministic keys, checksums и metadata |
+
+## Трек 2: методика и результаты
+
+Гипотеза: при дублировании, reorder и падении worker до/после side effect
+каждый attachment завершится не более чем одним логическим набором
+вариантов, а более новая версия pipeline не будет перезаписана старой.
+
+Методика: Redis consumer group доставляет одно сообщение повторно после
+истечения lease; fault injection задаётся `FAULT_INJECTION` значениями
+`before-side-effect`, `after-original`, `after-side-effect`. Все оригинал и
+варианты используют детерминированные keys, а запись `ready` выполняется
+только после успешной фиксации всех объектов. При повторе проверяется
+состояние PostgreSQL и версия job; старый pipeline ACK-ается без side effect.
+В реальном стенде остановка worker во время public smoke дала 202 до
+запуска worker и PASS после восстановления.
+
+Инварианты:
+
+1. подтверждённая 202 job имеет staging и durable outbox;
+2. `ready` означает наличие original и всех трёх обещанных вариантов;
+3. повтор не создаёт новый attachment или новый вариант;
+4. устаревшая версия не переводит новый результат обратно в processing;
+5. доставка не exactly-once: Redis может доставить сообщение повторно,
+ exactly-once достигается только на уровне идемпотентного эффекта.
+
+Автоматический сценарий запускается командой
+`make test-pipeline-faults`: он останавливает обычный worker, загружает
+fixture, запускает fault-worker с `after-side-effect`, заменяет его
+recovery-worker с коротким lease и сохраняет обезличенный summary в
+`evidence/pipeline-faults.json`. Проверка на чистом Compose-проекте завершилась
+`PASS`: `ready`, ровно `thumbnail/crop/optimized`, потеря подтверждённой
+задачи отсутствует.
+
+Ограничение: эксперимент одноузловой; потеря PostgreSQL/MinIO volume и
+потеря Docker-host не моделируются. RSS/load benchmark не заявляется как
+часть выбранного трека.
+
+## Ограничения
+
+PostgreSQL, Redis, MinIO и Nginx одноузловые. Outbox закрывает разрыв
+COMMIT→publish, но не делает два хранилища общей транзакцией. Retention
+staging очищается после успешной фиксации результата; orphan/missing
+объекты обрабатываются существующим reconciliation с grace period.
diff --git a/app.py b/app.py
new file mode 100644
index 00000000..23009650
--- /dev/null
+++ b/app.py
@@ -0,0 +1,769 @@
+#!/usr/bin/env python3
+
+import base64
+import binascii
+import hashlib
+import json
+import logging
+import os
+import re
+import signal
+import socket
+import sys
+import tempfile
+import threading
+import unicodedata
+import uuid
+import warnings
+from datetime import datetime, timezone
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import parse_qs, urlsplit
+
+from PIL import Image, UnidentifiedImageError
+
+from auth import (
+ create_session,
+ hash_password,
+ now_iso,
+ parse_basic_auth,
+ parse_bearer_token,
+ validate_password,
+ verify_password,
+)
+from db import ApiError, Store
+from s3store import ObjectStore, S3Unavailable
+from sessions import SessionStore
+
+MAX_BODY_BYTES = 1024 * 1024
+MAX_UPLOAD_BYTES = min(10 * 1024 * 1024, int(os.environ.get('MAX_UPLOAD_BYTES', 10 * 1024 * 1024)))
+MAX_IMAGE_PIXELS = min(40_000_000, int(os.environ.get('MAX_IMAGE_PIXELS', 40_000_000)))
+MAX_CONCURRENT_UPLOADS = int(os.environ.get('MAX_CONCURRENT_UPLOADS', '16'))
+if (MAX_UPLOAD_BYTES < 1 or MAX_IMAGE_PIXELS < 1
+ or not 1 <= MAX_CONCURRENT_UPLOADS <= 64):
+ raise RuntimeError('Upload limits must be positive and concurrent uploads cannot exceed 64')
+UPLOAD_SLOTS = threading.BoundedSemaphore(MAX_CONCURRENT_UPLOADS)
+USERNAME_PATTERN = re.compile(r'^[a-z0-9_]{3,32}$')
+CURSOR_TIMESTAMP_PATTERN = re.compile(
+ r'^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?Z$'
+)
+IDEMPOTENCY_KEY_PATTERN = re.compile(r'^[A-Za-z0-9._:-]{1,128}$')
+LOG = logging.getLogger('messenger')
+OPENAPI_PATH = Path(__file__).resolve().parent / 'contracts' / 'openapi.json'
+SWAGGER_HTML = b'''
+
+
+
+
+ MTUSI Messenger API
+
+
+
+
+
+
+
+
+'''
+
+
+def cursor_encode(resource, item):
+ value = json.dumps(
+ {'resource': resource, 'created_at': item['created_at'], 'id': item['id']},
+ separators=(',', ':'),
+ ).encode('utf-8')
+ return base64.urlsafe_b64encode(value).rstrip(b'=').decode('ascii')
+
+
+def cursor_decode(cursor, resource):
+ try:
+ padding = '=' * (-len(cursor) % 4)
+ decoded = base64.b64decode(cursor + padding, altchars=b'-_', validate=True)
+ value = json.loads(decoded.decode('utf-8'))
+ except (ValueError, UnicodeError, binascii.Error):
+ raise ApiError(400, 'invalid_request', 'Invalid cursor') from None
+ if (not isinstance(value, dict) or set(value) != {'resource', 'created_at', 'id'}
+ or value.get('resource') != resource
+ or not isinstance(value.get('created_at'), str)
+ or not CURSOR_TIMESTAMP_PATTERN.fullmatch(value['created_at'])
+ or not isinstance(value.get('id'), str)):
+ raise ApiError(400, 'invalid_request', 'Invalid cursor')
+ try:
+ created_at = datetime.fromisoformat(value['created_at'][:-1] + '+00:00')
+ item_id = str(uuid.UUID(value['id']))
+ except (ValueError, AttributeError):
+ raise ApiError(400, 'invalid_request', 'Invalid cursor') from None
+ if item_id != value['id']:
+ raise ApiError(400, 'invalid_request', 'Invalid cursor')
+ return created_at, item_id
+
+
+def required_text(value, name, maximum):
+ if not isinstance(value, str) or not value.strip() or len(value) > maximum:
+ raise ApiError(400, 'invalid_request', 'Invalid ' + name)
+ try:
+ value.encode('utf-8')
+ except UnicodeEncodeError:
+ raise ApiError(400, 'invalid_request', 'Invalid ' + name) from None
+ return value
+
+
+def parse_uuid(value):
+ if not isinstance(value, str):
+ raise ApiError(400, 'invalid_request', 'Invalid UUID')
+ try:
+ parsed = uuid.UUID(value)
+ except (ValueError, AttributeError):
+ raise ApiError(400, 'invalid_request', 'Invalid UUID') from None
+ if str(parsed) != value.lower():
+ raise ApiError(400, 'invalid_request', 'Invalid UUID')
+ return str(parsed)
+
+
+def attachment_filename(query):
+ try:
+ values = parse_qs(query, keep_blank_values=True, strict_parsing=True)
+ except ValueError:
+ raise ApiError(400, 'invalid_request', 'Invalid attachment query') from None
+ if set(values) != {'filename'} or len(values['filename']) != 1:
+ raise ApiError(400, 'invalid_request', 'Invalid attachment query')
+ filename = values['filename'][0]
+ if (not filename or len(filename) > 255 or '/' in filename or '\\' in filename
+ or any(unicodedata.category(char) in {'Cc', 'Cf'} for char in filename)):
+ raise ApiError(400, 'invalid_request', 'Invalid filename')
+ try:
+ filename.encode('utf-8')
+ except UnicodeEncodeError:
+ raise ApiError(400, 'invalid_request', 'Invalid filename') from None
+ return filename
+
+
+class MessengerHandler(BaseHTTPRequestHandler):
+ server_version = 'MTUSI-Messenger-Lab5'
+ protocol_version = 'HTTP/1.1'
+
+ def log_message(self, _format, *args):
+ LOG.info('request method=%s status=%s request_id=%s', self.command, self._status, self._request_id)
+
+ def _send_bytes(self, status, request_id, body, content_type, extra_headers=None):
+ self._status = status
+ self.send_response(status)
+ self.send_header('X-Request-Id', request_id)
+ self.send_header('Content-Length', str(len(body)))
+ if status != 204:
+ self.send_header('Content-Type', content_type)
+ for name, value in (extra_headers or {}).items():
+ self.send_header(name, value)
+ self.send_header('X-Instance-Id', self.server.instance_id)
+ self.end_headers()
+ self._headers_sent = True
+ if body:
+ self.wfile.write(body)
+
+ def _send_stream(self, request_id, stream, length, content_type):
+ self._status = 200
+ self.send_response(200)
+ self.send_header('X-Request-Id', request_id)
+ self.send_header('Content-Length', str(length))
+ self.send_header('Content-Type', content_type)
+ self.send_header('X-Instance-Id', self.server.instance_id)
+ self.end_headers()
+ self._headers_sent = True
+ remaining = length
+ while remaining:
+ chunk = stream.read(min(64 * 1024, remaining))
+ if not chunk:
+ raise OSError('S3 object ended before the stored content length')
+ self.wfile.write(chunk)
+ remaining -= len(chunk)
+
+ def _send(self, status, request_id, payload=None, extra_headers=None):
+ body = b'' if status == 204 else json.dumps(
+ payload, ensure_ascii=False, separators=(',', ':')
+ ).encode('utf-8')
+ self._send_bytes(
+ status, request_id, body, 'application/json; charset=utf-8', extra_headers
+ )
+
+ def _error(self, request_id, error, extra_headers=None):
+ self._send(error.status, request_id, {
+ 'error': {
+ 'code': error.code,
+ 'message': error.message,
+ 'request_id': request_id,
+ },
+ }, extra_headers=extra_headers)
+
+ def _read_json(self):
+ if self.headers.get_content_type() != 'application/json':
+ raise ApiError(415, 'unsupported_media_type', 'Expected application/json')
+ raw_length = self.headers.get('Content-Length')
+ try:
+ length = int(raw_length)
+ except (TypeError, ValueError):
+ raise ApiError(400, 'invalid_request', 'Invalid Content-Length') from None
+ if length < 0:
+ raise ApiError(400, 'invalid_request', 'Invalid Content-Length')
+ if length > MAX_BODY_BYTES:
+ raise ApiError(413, 'payload_too_large', 'Request body is too large')
+ try:
+ value = json.loads(self.rfile.read(length).decode('utf-8'))
+ except (ValueError, UnicodeError):
+ raise ApiError(400, 'invalid_request', 'Malformed JSON') from None
+ if not isinstance(value, dict):
+ raise ApiError(400, 'invalid_request', 'Expected a JSON object')
+ return value
+
+ def _read_attachment(self):
+ content_type = self.headers.get_content_type()
+ if content_type not in ('image/png', 'image/jpeg'):
+ self.close_connection = True
+ raise ApiError(415, 'unsupported_media_type', 'Expected PNG or JPEG')
+ try:
+ length = int(self.headers.get('Content-Length'))
+ except (TypeError, ValueError):
+ raise ApiError(400, 'invalid_request', 'Invalid Content-Length') from None
+ if length < 0:
+ self.close_connection = True
+ raise ApiError(400, 'invalid_request', 'Invalid Content-Length')
+ if length > MAX_UPLOAD_BYTES:
+ self.close_connection = True
+ raise ApiError(413, 'payload_too_large', 'Image exceeds the upload limit')
+ if length == 0:
+ raise ApiError(415, 'unsupported_media_type', 'Image is empty or invalid')
+
+ temp_file = tempfile.SpooledTemporaryFile(max_size=1024 * 1024, mode='w+b')
+ digest = hashlib.sha256()
+ remaining = length
+ try:
+ while remaining:
+ chunk = self.rfile.read(min(64 * 1024, remaining))
+ if not chunk:
+ raise ApiError(400, 'invalid_request', 'Incomplete image upload')
+ temp_file.write(chunk)
+ digest.update(chunk)
+ remaining -= len(chunk)
+ temp_file.seek(0)
+ try:
+ with warnings.catch_warnings():
+ warnings.simplefilter('ignore', Image.DecompressionBombWarning)
+ image = Image.open(temp_file)
+ detected_type = {
+ 'PNG': 'image/png',
+ 'JPEG': 'image/jpeg',
+ }.get(image.format)
+ width, height = image.size
+ if width * height > MAX_IMAGE_PIXELS:
+ raise ApiError(413, 'payload_too_large', 'Image dimensions exceed the pixel limit')
+ if detected_type != content_type:
+ raise ApiError(415, 'unsupported_media_type', 'Image content does not match Content-Type')
+ image.verify()
+ except Image.DecompressionBombError:
+ raise ApiError(413, 'payload_too_large', 'Image dimensions exceed the pixel limit') from None
+ except ApiError:
+ raise
+ except (UnidentifiedImageError, OSError, SyntaxError, ValueError):
+ raise ApiError(415, 'unsupported_media_type', 'Image is invalid or unsupported') from None
+ temp_file.seek(0)
+ return temp_file, {
+ 'content_type': detected_type,
+ 'size_bytes': length,
+ 'sha256': digest.hexdigest(),
+ 'width': width,
+ 'height': height,
+ }
+ except Exception:
+ temp_file.close()
+ raise
+
+ def _dependencies_ok(self):
+ try:
+ self.server.store.ping()
+ self.server.sessions.ping()
+ self.server.objects.ping()
+ return True
+ except Exception:
+ LOG.exception('dependency check failed')
+ return False
+
+ def _unauthorized_bearer(self, request_id):
+ self._error(
+ request_id,
+ ApiError(401, 'unauthorized', 'Authentication required'),
+ extra_headers={'WWW-Authenticate': 'Bearer realm="messenger"'},
+ )
+
+ def _unauthorized_basic(self, request_id):
+ self._error(
+ request_id,
+ ApiError(401, 'unauthorized', 'Authentication required'),
+ extra_headers={'WWW-Authenticate': 'Basic realm="messenger", charset="UTF-8"'},
+ )
+
+ def _authenticated_user(self, request_id):
+ auth = self.headers.get('Authorization', '')
+ if auth.startswith('Basic '):
+ self._unauthorized_bearer(request_id)
+ return None
+ token = parse_bearer_token(auth)
+ if not token:
+ self._unauthorized_bearer(request_id)
+ return None
+ try:
+ user_id = self.server.sessions.get_user_id(token)
+ except Exception:
+ LOG.exception('session lookup failed')
+ self._error(request_id, ApiError(503, 'unavailable', 'Service unavailable'))
+ return None
+ if not user_id:
+ self._unauthorized_bearer(request_id)
+ return None
+ try:
+ user = self.server.store.get_user(user_id)
+ except Exception:
+ LOG.exception('user lookup failed')
+ self._error(request_id, ApiError(503, 'unavailable', 'Service unavailable'))
+ return None
+ if user is None:
+ self._unauthorized_bearer(request_id)
+ return None
+ user['_token'] = token
+ return user
+
+ @staticmethod
+ def _query(query):
+ try:
+ values = parse_qs(query, keep_blank_values=True, strict_parsing=True)
+ except ValueError:
+ raise ApiError(400, 'invalid_request', 'Invalid query parameters') from None
+ if set(values) - {'limit', 'cursor'} or any(len(items) != 1 for items in values.values()):
+ raise ApiError(400, 'invalid_request', 'Invalid query parameters')
+ try:
+ limit = int(values.get('limit', ['50'])[0])
+ except ValueError:
+ raise ApiError(400, 'invalid_request', 'Invalid limit') from None
+ if not 1 <= limit <= 100:
+ raise ApiError(400, 'invalid_request', 'Invalid limit')
+ cursor = values.get('cursor', [''])[0]
+ if ('cursor' in values and not cursor) or len(cursor) > 2048:
+ raise ApiError(400, 'invalid_request', 'Invalid cursor')
+ return limit, cursor
+
+ def _create_session(self, request_id):
+ credentials = parse_basic_auth(self.headers.get('Authorization'))
+ if not credentials:
+ self._unauthorized_basic(request_id)
+ return
+ username, password = credentials
+ if not isinstance(username, str) or not USERNAME_PATTERN.fullmatch(username):
+ self._unauthorized_basic(request_id)
+ return
+ if not validate_password(password):
+ self._unauthorized_basic(request_id)
+ return
+ try:
+ row = self.server.store.get_user_with_password(username)
+ except Exception:
+ LOG.exception('login lookup failed')
+ self._error(request_id, ApiError(503, 'unavailable', 'Service unavailable'))
+ return
+ if row is None or not verify_password(row['password_hash'], password):
+ self._unauthorized_basic(request_id)
+ return
+ user = self.server.store.get_user(str(row['id']))
+ try:
+ token, expires_at = create_session(self.server.sessions, user['id'])
+ except Exception:
+ LOG.exception('session create failed')
+ self._error(request_id, ApiError(503, 'unavailable', 'Service unavailable'))
+ return
+ self._send(201, request_id, {
+ 'token': token,
+ 'token_type': 'Bearer',
+ 'expires_at': expires_at,
+ 'user': user,
+ })
+
+ def _logout(self, request_id, user):
+ try:
+ self.server.sessions.revoke(user['_token'])
+ except Exception:
+ LOG.exception('session revoke failed')
+ self._error(request_id, ApiError(503, 'unavailable', 'Service unavailable'))
+ return
+ self._send_bytes(204, request_id, b'', 'application/json; charset=utf-8')
+
+ def _compensate_upload(self, attachment_id, object_key, remove_object):
+ if remove_object:
+ try:
+ self.server.objects.delete_object(object_key)
+ except S3Unavailable:
+ LOG.error('upload compensation could not delete object id=%s', attachment_id)
+ try:
+ self.server.store.mark_attachment_failed(
+ attachment_id, 'upload_failed', now_iso()
+ )
+ except ApiError as error:
+ LOG.error(
+ 'upload compensation could not update metadata id=%s code=%s',
+ attachment_id,
+ error.code,
+ )
+
+ def _upload_attachment(self, request_id, user, chat_id, query):
+ filename = attachment_filename(query)
+ self.server.store.get_chat(user['id'], chat_id)
+ if not UPLOAD_SLOTS.acquire(timeout=5):
+ raise ApiError(503, 'unavailable', 'Upload capacity is temporarily unavailable')
+ temp_file = None
+ try:
+ temp_file, image = self._read_attachment()
+ attachment_id = str(uuid.uuid4())
+ object_key = 'objects/' + uuid.uuid4().hex
+ staging_key = 'staging/' + attachment_id
+ job_id = str(uuid.uuid4())
+ created_at = now_iso()
+ self.server.store.create_attachment_upload(
+ attachment_id,
+ chat_id,
+ user['id'],
+ object_key,
+ filename,
+ staging_key,
+ image['content_type'],
+ image['size_bytes'],
+ image['sha256'],
+ image['width'],
+ image['height'],
+ job_id,
+ created_at,
+ )
+ try:
+ self.server.objects.put_file(
+ staging_key, temp_file, image['size_bytes'], image['content_type']
+ )
+ except S3Unavailable:
+ self._compensate_upload(attachment_id, staging_key, True)
+ raise ApiError(503, 'unavailable', 'Attachment storage is unavailable') from None
+ self._send(
+ 202,
+ request_id,
+ self.server.store.get_attachment(user['id'], attachment_id),
+ )
+ finally:
+ if temp_file is not None:
+ temp_file.close()
+ UPLOAD_SLOTS.release()
+
+ def _download_attachment(self, request_id, user, attachment_id, query):
+ try:
+ values = parse_qs(query, keep_blank_values=True, strict_parsing=True)
+ except ValueError:
+ raise ApiError(400, 'invalid_request', 'Invalid attachment query') from None
+ if set(values) - {'variant'} or any(len(items) != 1 for items in values.values()):
+ raise ApiError(400, 'invalid_request', 'Invalid attachment query')
+ variant = values.get('variant', ['original'])[0]
+ if variant not in {'original', 'thumbnail', 'crop', 'optimized'}:
+ raise ApiError(404, 'not_found', 'Attachment variant not found')
+ attachment = self.server.store.get_attachment_for_download(
+ user['id'], attachment_id
+ )
+ if attachment['status'] != 'ready':
+ raise ApiError(409, 'conflict', 'Attachment is not ready')
+ if variant == 'original':
+ object_key, size, content_type = (
+ attachment['object_key'], attachment['size_bytes'], attachment['content_type']
+ )
+ else:
+ metadata = next(
+ (item for item in attachment['variants'] if item.get('name') == variant), None
+ )
+ if metadata is None:
+ raise ApiError(404, 'not_found', 'Attachment variant not found')
+ object_key = 'objects/' + attachment_id + '/' + variant
+ size, content_type = metadata['size_bytes'], metadata['content_type']
+ result = self.server.objects.get_object(object_key)
+ if result is None:
+ self.server.store.mark_reconciled_missing(attachment_id, now_iso())
+ raise ApiError(503, 'unavailable', 'Attachment content is unavailable')
+ stream = result['Body']
+ try:
+ if result.get('ContentLength') != size:
+ self.server.store.mark_reconciled_missing(attachment_id, now_iso())
+ raise ApiError(503, 'unavailable', 'Attachment content is inconsistent')
+ self._send_stream(
+ request_id,
+ stream,
+ size,
+ content_type,
+ )
+ finally:
+ stream.close()
+
+ def _register(self, request_id, body):
+ if set(body) != {'username', 'display_name', 'password'}:
+ raise ApiError(400, 'invalid_request', 'Invalid user fields')
+ username = body['username']
+ if not isinstance(username, str) or not USERNAME_PATTERN.fullmatch(username):
+ raise ApiError(400, 'invalid_request', 'Invalid username')
+ display_name = required_text(body['display_name'], 'display_name', 100)
+ password = body['password']
+ if not validate_password(password):
+ raise ApiError(400, 'invalid_request', 'Invalid password')
+ created_at = now_iso()
+ password_hash = hash_password(password)
+ user = self.server.store.register_user(username, display_name, password_hash, created_at)
+ self._send(201, request_id, user)
+
+ def _dispatch(self):
+ request_id = str(uuid.uuid4())
+ self._request_id = request_id
+ self._status = 500
+ self._headers_sent = False
+ try:
+ if self.server.stopping:
+ raise ApiError(503, 'unavailable', 'Server is shutting down')
+ route = urlsplit(self.path)
+ path = route.path
+ if self.command == 'GET' and path in ('/docs', '/docs/'):
+ self._send_bytes(200, request_id, SWAGGER_HTML, 'text/html; charset=utf-8')
+ return
+ if self.command == 'GET' and path == '/openapi.json':
+ self._send_bytes(
+ 200, request_id, self.server.openapi_json, 'application/json; charset=utf-8'
+ )
+ return
+ if path == '/health/live' and self.command == 'GET':
+ self._send(200, request_id, {'status': 'ok'})
+ return
+ if path == '/health/ready' and self.command == 'GET':
+ if self._dependencies_ok():
+ self._send(200, request_id, {'status': 'ok'})
+ else:
+ self._error(request_id, ApiError(503, 'unavailable', 'Service unavailable'))
+ return
+ if path == '/api/v1/users' and self.command == 'POST':
+ self._register(request_id, self._read_json())
+ return
+ if path == '/api/v1/auth/sessions' and self.command == 'POST':
+ self._create_session(request_id)
+ return
+ if path.startswith('/api/v1/'):
+ user = self._authenticated_user(request_id)
+ if user is None:
+ return
+ user_id = user['id']
+ if path == '/api/v1/auth/sessions/current' and self.command == 'DELETE':
+ self._logout(request_id, user)
+ return
+ if path == '/api/v1/users/me' and self.command == 'GET':
+ self._send(200, request_id, {
+ k: user[k] for k in ('id', 'username', 'display_name', 'created_at')
+ })
+ return
+ if path == '/api/v1/chats' and self.command == 'POST':
+ body = self._read_json()
+ if set(body) != {'title', 'member_ids'}:
+ raise ApiError(400, 'invalid_request', 'Invalid chat fields')
+ title = required_text(body['title'], 'title', 100)
+ member_ids = body['member_ids']
+ if (not isinstance(member_ids, list) or not member_ids or len(member_ids) > 100
+ or any(not isinstance(value, str) for value in member_ids)):
+ raise ApiError(400, 'invalid_request', 'Invalid chat members')
+ normalized = [parse_uuid(value) for value in member_ids]
+ if len(set(normalized)) != len(normalized) or user_id not in normalized:
+ raise ApiError(400, 'invalid_request', 'Invalid chat members')
+ chat = self.server.store.create_chat(
+ user_id, title, normalized, now_iso()
+ )
+ self._send(201, request_id, chat)
+ return
+ if path == '/api/v1/chats' and self.command == 'GET':
+ limit, cursor = self._query(route.query)
+ key = cursor_decode(cursor, 'chats') if cursor else None
+ items, next_key = self.server.store.list_chats(user_id, limit, key)
+ next_cursor = cursor_encode('chats', items[-1]) if next_key else None
+ self._send(200, request_id, {'items': items, 'next_cursor': next_cursor})
+ return
+ match = re.fullmatch(r'/api/v1/chats/([^/]+)', path)
+ if match and self.command == 'GET':
+ chat_id = parse_uuid(match.group(1))
+ self._send(200, request_id, self.server.store.get_chat(user_id, chat_id))
+ return
+ match = re.fullmatch(r'/api/v1/chats/([^/]+)/messages', path)
+ if match:
+ chat_id = parse_uuid(match.group(1))
+ resource = 'messages:' + chat_id
+ if self.command == 'POST':
+ body = self._read_json()
+ if set(body) - {'text', 'attachment_ids'} or 'text' not in body:
+ raise ApiError(400, 'invalid_request', 'Invalid message fields')
+ idempotency_key = self.headers.get('Idempotency-Key', '')
+ if not IDEMPOTENCY_KEY_PATTERN.fullmatch(idempotency_key):
+ raise ApiError(400, 'invalid_request', 'Invalid Idempotency-Key')
+ text = body['text']
+ attachment_ids = body.get('attachment_ids', [])
+ if (not isinstance(text, str) or len(text) > 4000
+ or not isinstance(attachment_ids, list)
+ or len(attachment_ids) > 10
+ or any(not isinstance(value, str) for value in attachment_ids)):
+ raise ApiError(400, 'invalid_request', 'Invalid message fields')
+ normalized_attachments = [
+ parse_uuid(value) for value in attachment_ids
+ ]
+ if len(set(normalized_attachments)) != len(normalized_attachments):
+ raise ApiError(400, 'invalid_request', 'Duplicate attachment IDs')
+ if not text.strip() and not normalized_attachments:
+ raise ApiError(400, 'invalid_request', 'Message text or attachment is required')
+ try:
+ text.encode('utf-8')
+ except UnicodeEncodeError:
+ raise ApiError(400, 'invalid_request', 'Invalid message text') from None
+ message = self.server.store.create_message_idempotent(
+ user_id,
+ chat_id,
+ text,
+ normalized_attachments,
+ idempotency_key,
+ now_iso(),
+ )
+ self._send(201, request_id, message)
+ return
+ if self.command == 'GET':
+ limit, cursor = self._query(route.query)
+ key = cursor_decode(cursor, resource) if cursor else None
+ items, next_key = self.server.store.list_messages(user_id, chat_id, limit, key)
+ next_cursor = cursor_encode(resource, items[-1]) if next_key else None
+ self._send(200, request_id, {'items': items, 'next_cursor': next_cursor})
+ return
+ match = re.fullmatch(r'/api/v1/chats/([^/]+)/attachments', path)
+ if match and self.command == 'POST':
+ self._upload_attachment(
+ request_id, user, parse_uuid(match.group(1)), route.query
+ )
+ return
+ match = re.fullmatch(r'/api/v1/attachments/([^/]+)', path)
+ if match and self.command == 'GET':
+ self._send(
+ 200,
+ request_id,
+ self.server.store.get_attachment(
+ user_id, parse_uuid(match.group(1))
+ ),
+ )
+ return
+ match = re.fullmatch(
+ r'/api/v1/attachments/([^/]+)/content', path
+ )
+ if match and self.command == 'GET':
+ self._download_attachment(
+ request_id, user, parse_uuid(match.group(1)), route.query
+ )
+ return
+ raise ApiError(404, 'not_found', 'Resource not found')
+ except ApiError as error:
+ self._error(request_id, error)
+ except (BrokenPipeError, ConnectionResetError):
+ LOG.info('request disconnected request_id=%s', request_id)
+ except OSError:
+ if self._headers_sent:
+ LOG.info('response stream disconnected request_id=%s', request_id)
+ else:
+ LOG.exception('request I/O failed request_id=%s', request_id)
+ self._error(
+ request_id,
+ ApiError(503, 'unavailable', 'Service unavailable'),
+ )
+ except Exception:
+ LOG.exception('request failed request_id=%s', request_id)
+ self._error(request_id, ApiError(500, 'internal_error', 'Internal server error'))
+
+ def do_GET(self):
+ self._dispatch()
+
+ def do_POST(self):
+ self._dispatch()
+
+ def do_PUT(self):
+ self._dispatch()
+
+ def do_PATCH(self):
+ self._dispatch()
+
+ def do_DELETE(self):
+ self._dispatch()
+
+ def do_OPTIONS(self):
+ self._dispatch()
+
+
+class MessengerServer(ThreadingHTTPServer):
+ daemon_threads = False
+ block_on_close = True
+ request_queue_size = 128
+
+ def __init__(self, address, store, sessions, objects):
+ super().__init__(address, MessengerHandler)
+ self.store = store
+ self.sessions = sessions
+ self.objects = objects
+ self.stopping = False
+ self.instance_id = os.environ.get('INSTANCE_ID') or socket.gethostname()
+ try:
+ spec = json.loads(OPENAPI_PATH.read_text(encoding='utf-8'))
+ spec['servers'] = [{'url': '/', 'description': 'Текущий адрес API'}]
+ self.openapi_json = json.dumps(
+ spec, ensure_ascii=False, separators=(',', ':')
+ ).encode('utf-8')
+ except (OSError, ValueError) as error:
+ self.server_close()
+ raise RuntimeError('Unable to load the OpenAPI contract') from error
+
+
+def main():
+ host = os.environ.get('APP_HOST', '0.0.0.0')
+ try:
+ port = int(os.environ.get('APP_PORT', '8080'))
+ except ValueError:
+ raise SystemExit('APP_PORT must be an integer')
+ if not 1 <= port <= 65535:
+ raise SystemExit('APP_PORT must be between 1 and 65535')
+ if os.environ.get('SESSION_STORE', 'redis').lower() != 'redis':
+ raise SystemExit('SESSION_STORE must be redis for this implementation')
+
+ logging.basicConfig(
+ level=os.environ.get('LOG_LEVEL', 'INFO').upper(),
+ format='%(asctime)s %(levelname)s %(name)s %(message)s',
+ stream=sys.stdout,
+ )
+ store = Store.connect(run_migrations=False)
+ sessions = SessionStore.from_env()
+ objects = ObjectStore.from_env()
+ server = MessengerServer((host, port), store, sessions, objects)
+
+ def stop(_signum, _frame):
+ server.stopping = True
+ threading.Thread(target=server.shutdown, name='http-shutdown', daemon=True).start()
+
+ signal.signal(signal.SIGTERM, stop)
+ signal.signal(signal.SIGINT, stop)
+ LOG.info('server started host=%s port=%d', host, port)
+ try:
+ server.serve_forever(poll_interval=0.2)
+ finally:
+ server.server_close()
+ store.close()
+ objects.client.close()
+ LOG.info('server stopped')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/auth.py b/auth.py
new file mode 100644
index 00000000..df4bee95
--- /dev/null
+++ b/auth.py
@@ -0,0 +1,77 @@
+import base64
+import binascii
+import os
+import secrets
+from datetime import datetime, timedelta, timezone
+
+from argon2 import PasswordHasher
+from argon2.exceptions import VerifyMismatchError
+
+from sessions import SessionStore
+
+PASSWORD_MIN = 12
+PASSWORD_MAX = 128
+_hasher = PasswordHasher()
+
+
+def now_iso():
+ return datetime.now(timezone.utc).isoformat(timespec='microseconds').replace('+00:00', 'Z')
+
+
+def validate_password(password):
+ if not isinstance(password, str):
+ return False
+ length = len(password)
+ return PASSWORD_MIN <= length <= PASSWORD_MAX
+
+
+def hash_password(password):
+ return _hasher.hash(password)
+
+
+def verify_password(password_hash, password):
+ try:
+ return _hasher.verify(password_hash, password)
+ except VerifyMismatchError:
+ return False
+
+
+def parse_basic_auth(header_value):
+ if not header_value or not header_value.startswith('Basic '):
+ return None
+ encoded = header_value[6:].strip()
+ try:
+ decoded = base64.b64decode(encoded, validate=True).decode('utf-8')
+ except (ValueError, UnicodeError, binascii.Error):
+ return None
+ if ':' not in decoded:
+ return None
+ username, password = decoded.split(':', 1)
+ if not username:
+ return None
+ return username, password
+
+
+def parse_bearer_token(header_value):
+ if not header_value or not header_value.startswith('Bearer '):
+ return None
+ token = header_value[7:].strip()
+ return token or None
+
+
+def session_ttl_seconds():
+ try:
+ ttl = int(os.environ.get('SESSION_TTL_SECONDS', '3600'))
+ except ValueError:
+ ttl = 3600
+ return max(1, ttl)
+
+
+def create_session(store: SessionStore, user_id):
+ token = secrets.token_urlsafe(32)
+ ttl = session_ttl_seconds()
+ expires_at = (
+ datetime.now(timezone.utc) + timedelta(seconds=ttl)
+ ).isoformat(timespec='microseconds').replace('+00:00', 'Z')
+ store.create(token, user_id, ttl)
+ return token, expires_at
diff --git a/compose.yaml b/compose.yaml
new file mode 100644
index 00000000..dfe84798
--- /dev/null
+++ b/compose.yaml
@@ -0,0 +1,254 @@
+services:
+ postgres:
+ image: postgres:16.8-alpine
+ environment:
+ POSTGRES_USER: messenger
+ POSTGRES_DB: messenger
+ POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
+ secrets:
+ - postgres_password
+ volumes:
+ - postgres_data:/var/lib/postgresql/data
+ networks:
+ - backend
+ healthcheck:
+ test: ['CMD-SHELL', 'pg_isready -U messenger -d messenger']
+ interval: 5s
+ timeout: 3s
+ retries: 12
+ start_period: 5s
+ restart: unless-stopped
+ deploy:
+ resources:
+ limits:
+ cpus: '${POSTGRES_CPU_LIMIT:-1.0}'
+ memory: '${POSTGRES_MEMORY_LIMIT:-1G}'
+
+ redis:
+ image: redis:7.4.2-alpine
+ command: ['redis-server', '--appendonly', 'yes', '--appendfsync', 'everysec']
+ volumes:
+ - redis_data:/data
+ networks:
+ - backend
+ healthcheck:
+ test: ['CMD', 'redis-cli', 'ping']
+ interval: 5s
+ timeout: 3s
+ retries: 12
+ restart: unless-stopped
+ deploy:
+ resources:
+ limits:
+ cpus: '${REDIS_CPU_LIMIT:-0.5}'
+ memory: '${REDIS_MEMORY_LIMIT:-256M}'
+
+ minio:
+ image: minio/minio@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e
+ entrypoint: ['/bin/sh', '/infra/minio-entrypoint.sh']
+ secrets:
+ - minio_root_user
+ - minio_root_password
+ volumes:
+ - minio_data:/data
+ - ./infra/minio-entrypoint.sh:/infra/minio-entrypoint.sh:ro
+ networks:
+ - backend
+ healthcheck:
+ test: ['CMD-SHELL', 'curl -fsS http://127.0.0.1:9000/minio/health/ready >/dev/null']
+ interval: 5s
+ timeout: 3s
+ retries: 12
+ start_period: 10s
+ restart: unless-stopped
+ deploy:
+ resources:
+ limits:
+ cpus: '${MINIO_CPU_LIMIT:-1.0}'
+ memory: '${MINIO_MEMORY_LIMIT:-1G}'
+
+ minio-bootstrap:
+ image: minio/minio@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e
+ entrypoint: ['/bin/sh', '/infra/minio-bootstrap.sh']
+ environment:
+ S3_BUCKET: messenger-attachments
+ secrets:
+ - minio_root_user
+ - minio_root_password
+ - s3_access_key_id
+ - s3_secret_access_key
+ volumes:
+ - ./infra/minio-bootstrap.sh:/infra/minio-bootstrap.sh:ro
+ - ./infra/s3-policy.json:/infra/s3-policy.json:ro
+ networks:
+ - backend
+ depends_on:
+ minio:
+ condition: service_healthy
+ restart: 'no'
+ deploy:
+ resources:
+ limits:
+ cpus: '${BOOTSTRAP_CPU_LIMIT:-0.25}'
+ memory: '${BOOTSTRAP_MEMORY_LIMIT:-128M}'
+
+ migrate:
+ build: .
+ command: ['python', 'scripts/migrate.py']
+ environment:
+ DATABASE_URL_FILE: /run/secrets/database_url
+ secrets:
+ - database_url
+ networks:
+ - backend
+ depends_on:
+ postgres:
+ condition: service_healthy
+ restart: 'no'
+ deploy:
+ resources:
+ limits:
+ cpus: '${MIGRATE_CPU_LIMIT:-0.5}'
+ memory: '${MIGRATE_MEMORY_LIMIT:-256M}'
+
+ api:
+ build: .
+ environment:
+ APP_HOST: 0.0.0.0
+ APP_PORT: 8080
+ SESSION_STORE: redis
+ SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
+ DATABASE_URL_FILE: /run/secrets/database_url
+ CACHE_URL: redis://redis:6379/0
+ S3_ENDPOINT: http://minio:9000
+ S3_REGION: ${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: ${MAX_UPLOAD_BYTES:-10485760}
+ MAX_IMAGE_PIXELS: ${MAX_IMAGE_PIXELS:-40000000}
+ MAX_CONCURRENT_UPLOADS: ${MAX_CONCURRENT_UPLOADS:-16}
+ BROKER_URL: redis://redis:6379/1
+ BROKER_STREAM: attachment.jobs
+ JOB_MAX_ATTEMPTS: ${JOB_MAX_ATTEMPTS:-5}
+ JOB_TIMEOUT_SECONDS: ${JOB_TIMEOUT_SECONDS:-60}
+ secrets:
+ - database_url
+ - s3_access_key_id
+ - s3_secret_access_key
+ networks:
+ - backend
+ depends_on:
+ migrate:
+ condition: service_completed_successfully
+ minio-bootstrap:
+ condition: service_completed_successfully
+ redis:
+ condition: service_healthy
+ healthcheck:
+ test:
+ [
+ 'CMD',
+ 'python',
+ '-c',
+ "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)",
+ ]
+ interval: 3s
+ timeout: 3s
+ retries: 3
+ start_period: 10s
+ stop_grace_period: 15s
+ restart: unless-stopped
+ deploy:
+ replicas: ${API_REPLICAS:-2}
+ resources:
+ limits:
+ cpus: '${API_CPU_LIMIT:-1.0}'
+ memory: '${API_MEMORY_LIMIT:-512M}'
+
+ worker:
+ build: .
+ command: ['python', 'worker.py']
+ environment:
+ DATABASE_URL_FILE: /run/secrets/database_url
+ BROKER_URL: redis://redis:6379/1
+ BROKER_STREAM: attachment.jobs
+ S3_ENDPOINT: http://minio:9000
+ S3_REGION: ${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
+ JOB_MAX_ATTEMPTS: ${JOB_MAX_ATTEMPTS:-5}
+ JOB_TIMEOUT_SECONDS: ${JOB_TIMEOUT_SECONDS:-60}
+ BROKER_PREFETCH: ${BROKER_PREFETCH:-1}
+ WORKER_CONCURRENCY: ${WORKER_CONCURRENCY:-2}
+ secrets:
+ - database_url
+ - s3_access_key_id
+ - s3_secret_access_key
+ networks:
+ - backend
+ depends_on:
+ migrate:
+ condition: service_completed_successfully
+ minio-bootstrap:
+ condition: service_completed_successfully
+ redis:
+ condition: service_healthy
+ restart: unless-stopped
+ healthcheck:
+ disable: true
+ deploy:
+ replicas: ${WORKER_REPLICAS:-1}
+ resources:
+ limits:
+ cpus: '${WORKER_CPU_LIMIT:-1.0}'
+ memory: '${WORKER_MEMORY_LIMIT:-512M}'
+
+ nginx:
+ image: nginx:1.27.5-alpine
+ ports:
+ - '${APP_PORT:-8080}:8080'
+ volumes:
+ - ./infra/nginx.conf:/etc/nginx/conf.d/default.conf:ro
+ networks:
+ - frontend
+ - backend
+ depends_on:
+ api:
+ condition: service_healthy
+ healthcheck:
+ test: ['CMD-SHELL', 'wget -q -O /dev/null http://127.0.0.1:8080/health/ready']
+ interval: 5s
+ timeout: 3s
+ retries: 5
+ restart: unless-stopped
+ deploy:
+ resources:
+ limits:
+ cpus: '${NGINX_CPU_LIMIT:-0.5}'
+ memory: '${NGINX_MEMORY_LIMIT:-256M}'
+
+networks:
+ frontend:
+ backend:
+ internal: true
+
+volumes:
+ postgres_data:
+ redis_data:
+ minio_data:
+
+secrets:
+ postgres_password:
+ file: ./secrets/postgres_password
+ database_url:
+ file: ./secrets/database_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
diff --git a/db.py b/db.py
new file mode 100644
index 00000000..a55495c6
--- /dev/null
+++ b/db.py
@@ -0,0 +1,698 @@
+import hashlib
+import json
+import os
+import uuid
+from pathlib import Path
+
+from psycopg import errors
+from psycopg.rows import dict_row
+from psycopg_pool import ConnectionPool, PoolTimeout
+from psycopg.types.json import Jsonb
+
+MIGRATIONS_DIR = Path(__file__).resolve().parent / 'migrations'
+
+
+class ApiError(Exception):
+ def __init__(self, status, code, message):
+ super().__init__(message)
+ self.status = status
+ self.code = code
+ self.message = message
+
+
+def read_database_url():
+ path = os.environ.get('DATABASE_URL_FILE')
+ if path and os.path.isfile(path):
+ return Path(path).read_text(encoding='utf-8').strip()
+ url = os.environ.get('DATABASE_URL', '').strip()
+ if not url:
+ raise RuntimeError('DATABASE_URL or DATABASE_URL_FILE is required')
+ return url
+
+
+class Store:
+ def __init__(self, pool: ConnectionPool):
+ self.pool = pool
+
+ @classmethod
+ def connect(cls, run_migrations=True):
+ pool = ConnectionPool(
+ conninfo=read_database_url(),
+ min_size=1,
+ max_size=10,
+ timeout=5.0,
+ kwargs={
+ 'row_factory': dict_row,
+ 'options': '-c statement_timeout=5000 -c lock_timeout=2000',
+ },
+ open=True,
+ )
+ store = cls(pool)
+ if run_migrations:
+ store.run_migrations()
+ return store
+
+ def close(self):
+ self.pool.close()
+
+ def ping(self):
+ with self.pool.connection() as conn:
+ conn.execute('SELECT 1')
+
+ def run_migrations(self):
+ with self.pool.connection() as conn:
+ conn.execute(
+ 'CREATE TABLE IF NOT EXISTS schema_migrations '
+ '(version TEXT PRIMARY KEY, applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW())'
+ )
+ for path in sorted(MIGRATIONS_DIR.glob('*.sql')):
+ version = path.name
+ row = conn.execute(
+ 'SELECT 1 FROM schema_migrations WHERE version = %s',
+ (version,),
+ ).fetchone()
+ if row:
+ continue
+ sql = path.read_text(encoding='utf-8')
+ with conn.transaction():
+ conn.execute(sql)
+ conn.execute(
+ 'INSERT INTO schema_migrations (version) VALUES (%s)',
+ (version,),
+ )
+
+ @staticmethod
+ def _user_row(row):
+ return {
+ 'id': str(row['id']),
+ 'username': row['username'],
+ 'display_name': row['display_name'],
+ 'created_at': row['created_at'].isoformat(timespec='microseconds').replace('+00:00', 'Z'),
+ }
+
+ def register_user(self, username, display_name, password_hash, created_at):
+ user_id = str(uuid.uuid4())
+ try:
+ with self.pool.connection() as conn:
+ conn.execute(
+ 'INSERT INTO users (id, username, display_name, password_hash, created_at) '
+ 'VALUES (%s, %s, %s, %s, %s)',
+ (user_id, username, display_name, password_hash, created_at),
+ )
+ except errors.UniqueViolation:
+ raise ApiError(409, 'conflict', 'Username already exists') from None
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+ return {
+ 'id': user_id,
+ 'username': username,
+ 'display_name': display_name,
+ 'created_at': created_at,
+ }
+
+ def get_user(self, user_id):
+ with self.pool.connection() as conn:
+ row = conn.execute(
+ 'SELECT id, username, display_name, created_at FROM users WHERE id = %s',
+ (user_id,),
+ ).fetchone()
+ if row is None:
+ return None
+ return self._user_row(row)
+
+ def get_user_with_password(self, username):
+ with self.pool.connection() as conn:
+ row = conn.execute(
+ 'SELECT id, username, display_name, password_hash, created_at FROM users WHERE username = %s',
+ (username,),
+ ).fetchone()
+ return row
+
+ def create_chat(self, user_id, title, member_ids, created_at):
+ chat_id = str(uuid.uuid4())
+ try:
+ with self.pool.connection() as conn:
+ with conn.transaction():
+ rows = conn.execute(
+ 'SELECT id FROM users WHERE id = ANY(%s)',
+ (member_ids,),
+ ).fetchall()
+ if len(rows) != len(set(member_ids)):
+ raise ApiError(400, 'invalid_request', 'Unknown chat member')
+ conn.execute(
+ 'INSERT INTO chats (id, title, created_at) VALUES (%s, %s, %s)',
+ (chat_id, title, created_at),
+ )
+ for index, member_id in enumerate(member_ids):
+ conn.execute(
+ 'INSERT INTO chat_members (chat_id, user_id, position) VALUES (%s, %s, %s)',
+ (chat_id, member_id, index),
+ )
+ except ApiError:
+ raise
+ except errors.Error:
+ raise ApiError(500, 'internal_error', 'Internal server error') from None
+ return {
+ 'id': chat_id,
+ 'title': title,
+ 'member_ids': list(member_ids),
+ 'created_at': created_at,
+ }
+
+ def _is_member(self, conn, chat_id, user_id):
+ row = conn.execute(
+ 'SELECT 1 FROM chat_members WHERE chat_id = %s AND user_id = %s',
+ (chat_id, user_id),
+ ).fetchone()
+ return row is not None
+
+ def get_chat(self, user_id, chat_id):
+ with self.pool.connection() as conn:
+ if not self._is_member(conn, chat_id, user_id):
+ raise ApiError(404, 'not_found', 'Chat not found')
+ chat = conn.execute(
+ 'SELECT id, title, created_at FROM chats WHERE id = %s',
+ (chat_id,),
+ ).fetchone()
+ members = conn.execute(
+ 'SELECT user_id FROM chat_members WHERE chat_id = %s ORDER BY position',
+ (chat_id,),
+ ).fetchall()
+ return {
+ 'id': str(chat['id']),
+ 'title': chat['title'],
+ 'member_ids': [str(row['user_id']) for row in members],
+ 'created_at': chat['created_at'].isoformat(timespec='microseconds').replace('+00:00', 'Z'),
+ }
+
+ def list_chats(self, user_id, limit, cursor_key):
+ query = (
+ 'SELECT c.id, c.title, c.created_at '
+ 'FROM chats c '
+ 'JOIN chat_members cm ON cm.chat_id = c.id AND cm.user_id = %s '
+ )
+ params = [user_id]
+ if cursor_key:
+ query += 'WHERE (c.created_at, c.id) > (%s, %s) '
+ params.extend(cursor_key)
+ query += 'ORDER BY c.created_at ASC, c.id ASC LIMIT %s'
+ params.append(limit + 1)
+ with self.pool.connection() as conn:
+ rows = conn.execute(query, params).fetchall()
+ has_more = len(rows) > limit
+ page = rows[:limit]
+ items = []
+ for row in page:
+ chat_id = str(row['id'])
+ items.append(self.get_chat(user_id, chat_id))
+ next_cursor = None
+ if has_more:
+ last = page[-1]
+ next_cursor = (last['created_at'], str(last['id']))
+ return items, next_cursor
+
+ def create_message(self, user_id, chat_id, text, created_at):
+ message_id = str(uuid.uuid4())
+ with self.pool.connection() as conn:
+ with conn.transaction():
+ if not self._is_member(conn, chat_id, user_id):
+ raise ApiError(404, 'not_found', 'Chat not found')
+ conn.execute(
+ 'INSERT INTO messages (id, chat_id, sender_id, text, created_at) '
+ 'VALUES (%s, %s, %s, %s, %s)',
+ (message_id, chat_id, user_id, text, created_at),
+ )
+ return {
+ 'id': message_id,
+ 'chat_id': chat_id,
+ 'sender_id': user_id,
+ 'text': text,
+ 'created_at': created_at,
+ 'attachment_ids': [],
+ }
+
+ def create_message_idempotent(
+ self, user_id, chat_id, text, attachment_ids, idempotency_key, created_at
+ ):
+ resource_path = '/api/v1/chats/' + chat_id + '/messages'
+ request_hash = hashlib.sha256(
+ json.dumps(
+ {
+ 'chat_id': chat_id,
+ 'text': text,
+ 'attachment_ids': attachment_ids,
+ },
+ ensure_ascii=False,
+ sort_keys=True,
+ separators=(',', ':'),
+ ).encode('utf-8')
+ ).hexdigest()
+ lock_key = '\x1f'.join(
+ (user_id, 'POST', resource_path, idempotency_key)
+ )
+ try:
+ with self.pool.connection() as conn:
+ with conn.transaction():
+ if not self._is_member(conn, chat_id, user_id):
+ raise ApiError(404, 'not_found', 'Chat not found')
+ conn.execute(
+ 'SELECT pg_advisory_xact_lock(hashtextextended(%s, 0))',
+ (lock_key,),
+ )
+ row = conn.execute(
+ 'SELECT request_hash, response FROM message_idempotency '
+ 'WHERE user_id = %s AND method = %s AND resource_path = %s '
+ 'AND idempotency_key = %s AND expires_at > NOW() FOR UPDATE',
+ (user_id, 'POST', resource_path, idempotency_key),
+ ).fetchone()
+ if row is not None:
+ if row['request_hash'] != request_hash:
+ raise ApiError(409, 'conflict', 'Idempotency-Key was used with a different request')
+ return row['response']
+
+ conn.execute(
+ 'DELETE FROM message_idempotency WHERE user_id = %s '
+ 'AND method = %s AND resource_path = %s AND idempotency_key = %s',
+ (user_id, 'POST', resource_path, idempotency_key),
+ )
+ conn.execute(
+ 'DELETE FROM message_idempotency WHERE user_id = %s AND expires_at <= NOW()',
+ (user_id,),
+ )
+ if attachment_ids:
+ attachments = conn.execute(
+ 'SELECT id, status FROM attachments '
+ 'WHERE chat_id = %s AND id = ANY(%s) FOR SHARE',
+ (chat_id, attachment_ids),
+ ).fetchall()
+ if len(attachments) != len(attachment_ids):
+ raise ApiError(404, 'not_found', 'Attachment not found')
+ if any(row['status'] == 'failed' for row in attachments):
+ raise ApiError(409, 'conflict', 'Attachment is not ready')
+ conn.execute(
+ 'INSERT INTO message_idempotency '
+ '(user_id, method, resource_path, idempotency_key, request_hash, expires_at) '
+ "VALUES (%s, %s, %s, %s, %s, NOW() + INTERVAL '24 hours')",
+ (user_id, 'POST', resource_path, idempotency_key, request_hash),
+ )
+ message_id = str(uuid.uuid4())
+ conn.execute(
+ 'INSERT INTO messages (id, chat_id, sender_id, text, created_at) '
+ 'VALUES (%s, %s, %s, %s, %s)',
+ (message_id, chat_id, user_id, text, created_at),
+ )
+ for position, attachment_id in enumerate(attachment_ids):
+ conn.execute(
+ 'INSERT INTO message_attachments '
+ '(message_id, attachment_id, position) VALUES (%s, %s, %s)',
+ (message_id, attachment_id, position),
+ )
+ message = {
+ 'id': message_id,
+ 'chat_id': chat_id,
+ 'sender_id': user_id,
+ 'text': text,
+ 'created_at': created_at,
+ 'attachment_ids': list(attachment_ids),
+ }
+ conn.execute(
+ 'UPDATE message_idempotency SET response = %s '
+ 'WHERE user_id = %s AND method = %s AND resource_path = %s '
+ 'AND idempotency_key = %s',
+ (Jsonb(message), user_id, 'POST', resource_path, idempotency_key),
+ )
+ return message
+ except ApiError:
+ raise
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+
+ def list_messages(self, user_id, chat_id, limit, cursor_key):
+ with self.pool.connection() as conn:
+ if not self._is_member(conn, chat_id, user_id):
+ raise ApiError(404, 'not_found', 'Chat not found')
+ query = (
+ 'SELECT m.id, m.chat_id, m.sender_id, m.text, m.created_at, '
+ 'COALESCE(array_agg(ma.attachment_id ORDER BY ma.position) '
+ 'FILTER (WHERE ma.attachment_id IS NOT NULL), ARRAY[]::UUID[]) AS attachment_ids '
+ 'FROM messages m LEFT JOIN message_attachments ma ON ma.message_id = m.id '
+ 'WHERE m.chat_id = %s '
+ )
+ params = [chat_id]
+ if cursor_key:
+ query += 'AND (m.created_at, m.id) > (%s, %s) '
+ params.extend(cursor_key)
+ query += (
+ 'GROUP BY m.id '
+ 'ORDER BY m.created_at ASC, m.id ASC LIMIT %s'
+ )
+ params.append(limit + 1)
+ with self.pool.connection() as conn:
+ rows = conn.execute(query, params).fetchall()
+ has_more = len(rows) > limit
+ page = rows[:limit]
+ items = [
+ {
+ 'id': str(row['id']),
+ 'chat_id': str(row['chat_id']),
+ 'sender_id': str(row['sender_id']),
+ 'text': row['text'],
+ 'created_at': row['created_at'].isoformat(timespec='microseconds').replace('+00:00', 'Z'),
+ 'attachment_ids': [str(value) for value in row['attachment_ids']],
+ }
+ for row in page
+ ]
+ next_cursor = None
+ if has_more:
+ last = page[-1]
+ next_cursor = (last['created_at'], str(last['id']))
+ return items, next_cursor
+
+ @staticmethod
+ def _attachment_row(row, include_key=False):
+ value = {
+ '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'].strip(),
+ 'status': row['status'],
+ 'variants': row['variants'],
+ 'error_code': row['error_code'],
+ 'created_at': row['created_at'].isoformat(timespec='microseconds').replace('+00:00', 'Z'),
+ 'updated_at': row['updated_at'].isoformat(timespec='microseconds').replace('+00:00', 'Z'),
+ }
+ if include_key:
+ value['object_key'] = row['object_key']
+ value['staging_key'] = row['staging_key']
+ value['width'] = row['width']
+ value['height'] = row['height']
+ return value
+
+ def create_attachment_upload(
+ self, attachment_id, chat_id, owner_id, object_key, filename,
+ staging_key, content_type, size_bytes, sha256, width, height,
+ job_id, created_at
+ ):
+ try:
+ with self.pool.connection() as conn:
+ with conn.transaction():
+ if not self._is_member(conn, chat_id, owner_id):
+ raise ApiError(404, 'not_found', 'Chat not found')
+ conn.execute(
+ 'INSERT INTO attachments '
+ '(id, chat_id, owner_id, object_key, staging_key, filename, content_type, '
+ 'size_bytes, sha256, width, height, status, variants, error_code, '
+ 'pipeline_version, created_at, updated_at) '
+ "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, "
+ "'queued', '[]'::jsonb, NULL, 1, %s, %s)",
+ (
+ attachment_id, chat_id, owner_id, object_key, staging_key, filename,
+ content_type, size_bytes, sha256, width, height,
+ created_at, created_at,
+ ),
+ )
+ conn.execute(
+ 'INSERT INTO attachment_jobs '
+ '(job_id, attachment_id, pipeline_version, status, created_at, updated_at) '
+ "VALUES (%s, %s, 1, 'queued', %s, %s)",
+ (job_id, attachment_id, created_at, created_at),
+ )
+ conn.execute(
+ 'INSERT INTO attachment_outbox (job_id, created_at) VALUES (%s, %s)',
+ (job_id, created_at),
+ )
+ except ApiError:
+ raise
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+
+ def mark_attachment_ready(self, attachment_id, updated_at):
+ try:
+ with self.pool.connection() as conn:
+ with conn.transaction():
+ row = conn.execute(
+ 'UPDATE attachments SET status = %s, error_code = NULL, updated_at = %s '
+ "WHERE id = %s AND status IN ('queued', 'processing') RETURNING *",
+ ('ready', updated_at, attachment_id),
+ ).fetchone()
+ if row is None:
+ current = conn.execute(
+ 'SELECT * FROM attachments WHERE id = %s', (attachment_id,)
+ ).fetchone()
+ if current and current['status'] == 'ready':
+ return self._attachment_row(current)
+ raise ApiError(503, 'unavailable', 'Attachment state could not be saved')
+ conn.execute(
+ "UPDATE attachment_jobs SET status = 'ready', lease_until = NULL, updated_at = %s "
+ 'WHERE attachment_id = %s',
+ (updated_at, attachment_id),
+ )
+ return self._attachment_row(row)
+ except ApiError:
+ raise
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+
+ def mark_attachment_failed(self, attachment_id, error_code, updated_at):
+ try:
+ with self.pool.connection() as conn:
+ conn.execute(
+ 'UPDATE attachments SET status = %s, error_code = %s, updated_at = %s '
+ "WHERE id = %s AND status IN ('queued', 'processing')",
+ ('failed', error_code, updated_at, attachment_id),
+ )
+ conn.execute(
+ "UPDATE attachment_jobs SET status = 'failed', lease_until = NULL, "
+ 'last_error = %s, updated_at = %s WHERE attachment_id = %s',
+ (error_code, updated_at, attachment_id),
+ )
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+
+ def claim_job(self, job_id, lease_until, updated_at):
+ try:
+ with self.pool.connection() as conn:
+ with conn.transaction():
+ row = conn.execute(
+ "UPDATE attachment_jobs SET status = 'processing', attempts = attempts + 1, "
+ 'lease_until = %s, updated_at = %s '
+ "WHERE job_id = %s AND status IN ('queued', 'processing') "
+ 'AND pipeline_version = (SELECT pipeline_version FROM attachments '
+ 'WHERE id = attachment_jobs.attachment_id) '
+ "AND (lease_until IS NULL OR lease_until < NOW()) "
+ 'RETURNING job_id, attachment_id, pipeline_version, attempts',
+ (lease_until, updated_at, job_id),
+ ).fetchone()
+ if row is None:
+ return None
+ conn.execute(
+ "UPDATE attachments SET status = 'processing', updated_at = %s "
+ "WHERE id = %s AND status = 'queued'",
+ (updated_at, row['attachment_id']),
+ )
+ return row
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+
+ def get_attachment_for_job(self, attachment_id):
+ with self.pool.connection() as conn:
+ row = conn.execute(
+ 'SELECT * FROM attachments WHERE id = %s', (attachment_id,)
+ ).fetchone()
+ return self._attachment_row(row, include_key=True) if row else None
+
+ def set_attachment_variants(self, attachment_id, variants, updated_at):
+ try:
+ with self.pool.connection() as conn:
+ with conn.transaction():
+ row = conn.execute(
+ 'UPDATE attachments SET status = %s, variants = %s, error_code = NULL, '
+ 'updated_at = %s WHERE id = %s AND status IN (%s, %s) RETURNING *',
+ ('ready', Jsonb(variants), updated_at, attachment_id, 'queued', 'processing'),
+ ).fetchone()
+ if row is None:
+ current = conn.execute(
+ 'SELECT * FROM attachments WHERE id = %s', (attachment_id,)
+ ).fetchone()
+ return self._attachment_row(current) if current else None
+ conn.execute(
+ "UPDATE attachment_jobs SET status = 'ready', lease_until = NULL, "
+ 'updated_at = %s WHERE attachment_id = %s',
+ (updated_at, attachment_id),
+ )
+ return self._attachment_row(row)
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+
+ def retry_job(self, job_id, attachment_id, next_attempt_at, error_code, updated_at):
+ try:
+ with self.pool.connection() as conn:
+ with conn.transaction():
+ conn.execute(
+ "UPDATE attachment_jobs SET status = 'queued', lease_until = NULL, "
+ 'next_attempt_at = %s, last_error = %s, updated_at = %s WHERE job_id = %s',
+ (next_attempt_at, error_code, updated_at, job_id),
+ )
+ conn.execute(
+ "UPDATE attachments SET status = 'queued', error_code = %s, updated_at = %s "
+ "WHERE id = %s AND status = 'processing'",
+ (error_code, updated_at, attachment_id),
+ )
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+
+ def fail_job(self, job_id, attachment_id, error_code, updated_at):
+ self.mark_attachment_failed(attachment_id, error_code, updated_at)
+
+ def pending_outbox(self, limit=100):
+ with self.pool.connection() as conn:
+ rows = conn.execute(
+ 'SELECT o.id, o.job_id, j.attachment_id, j.pipeline_version '
+ 'FROM attachment_outbox o JOIN attachment_jobs j ON j.job_id = o.job_id '
+ 'WHERE o.published_at IS NULL ORDER BY o.id LIMIT %s',
+ (limit,),
+ ).fetchall()
+ return rows
+
+ def mark_outbox_published(self, outbox_id, published_at):
+ try:
+ with self.pool.connection() as conn:
+ conn.execute(
+ 'UPDATE attachment_outbox SET published_at = %s '
+ 'WHERE id = %s AND published_at IS NULL',
+ (published_at, outbox_id),
+ )
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+
+ def replay_attachment(self, attachment_id, reason, created_at):
+ job_id = str(uuid.uuid4())
+ try:
+ with self.pool.connection() as conn:
+ with conn.transaction():
+ row = conn.execute(
+ "SELECT pipeline_version, status FROM attachments WHERE id = %s FOR UPDATE",
+ (attachment_id,),
+ ).fetchone()
+ if row is None:
+ raise ApiError(404, 'not_found', 'Attachment not found')
+ if row['status'] != 'failed':
+ raise ApiError(409, 'conflict', 'Only failed attachments can be replayed')
+ old_version = row['pipeline_version']
+ new_version = old_version + 1
+ conn.execute(
+ "UPDATE attachments SET status = 'queued', error_code = NULL, "
+ "variants = '[]'::jsonb, pipeline_version = %s, updated_at = %s "
+ "WHERE id = %s",
+ (new_version, created_at, attachment_id),
+ )
+ conn.execute(
+ "INSERT INTO attachment_jobs "
+ "(job_id, attachment_id, pipeline_version, status, created_at, updated_at) "
+ "VALUES (%s, %s, %s, 'queued', %s, %s)",
+ (job_id, attachment_id, new_version, created_at, created_at),
+ )
+ conn.execute(
+ "INSERT INTO attachment_outbox (job_id, created_at) VALUES (%s, %s)",
+ (job_id, created_at),
+ )
+ conn.execute(
+ "INSERT INTO attachment_replay_audit "
+ "(attachment_id, old_pipeline_version, new_pipeline_version, reason, created_at) "
+ "VALUES (%s, %s, %s, %s, %s)",
+ (attachment_id, old_version, new_version, reason, created_at),
+ )
+ return job_id, new_version
+ except ApiError:
+ raise
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+
+ def get_attachment(self, user_id, attachment_id):
+ try:
+ with self.pool.connection() as conn:
+ row = conn.execute(
+ 'SELECT a.* FROM attachments a '
+ 'JOIN chat_members cm ON cm.chat_id = a.chat_id '
+ 'WHERE a.id = %s AND cm.user_id = %s',
+ (attachment_id, user_id),
+ ).fetchone()
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+ if row is None:
+ raise ApiError(404, 'not_found', 'Attachment not found')
+ return self._attachment_row(row)
+
+ def get_attachment_for_download(self, user_id, attachment_id):
+ try:
+ with self.pool.connection() as conn:
+ row = conn.execute(
+ 'SELECT a.* FROM attachments a '
+ 'JOIN chat_members cm ON cm.chat_id = a.chat_id '
+ 'WHERE a.id = %s AND cm.user_id = %s',
+ (attachment_id, user_id),
+ ).fetchone()
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+ if row is None:
+ raise ApiError(404, 'not_found', 'Attachment not found')
+ return self._attachment_row(row, include_key=True)
+
+ def list_stale_processing_attachments(self, cutoff):
+ try:
+ with self.pool.connection() as conn:
+ rows = conn.execute(
+ "SELECT * FROM attachments WHERE status = 'processing' AND created_at < %s "
+ 'ORDER BY created_at, id',
+ (cutoff,),
+ ).fetchall()
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+ return [self._attachment_row(row, include_key=True) for row in rows]
+
+ def list_ready_attachments(self):
+ try:
+ with self.pool.connection() as conn:
+ rows = conn.execute(
+ "SELECT * FROM attachments WHERE status = 'ready' ORDER BY id"
+ ).fetchall()
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+ return [self._attachment_row(row, include_key=True) for row in rows]
+
+ def list_attachments_for_reconciliation(self):
+ try:
+ with self.pool.connection() as conn:
+ rows = conn.execute(
+ 'SELECT * FROM attachments ORDER BY id'
+ ).fetchall()
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+ return [self._attachment_row(row, include_key=True) for row in rows]
+
+ def get_attachment_by_object_key(self, object_key):
+ try:
+ with self.pool.connection() as conn:
+ row = conn.execute(
+ 'SELECT * FROM attachments WHERE object_key = %s',
+ (object_key,),
+ ).fetchone()
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
+ if row is None:
+ return None
+ return self._attachment_row(row, include_key=True)
+
+ def mark_reconciled_missing(self, attachment_id, updated_at):
+ try:
+ with self.pool.connection() as conn:
+ conn.execute(
+ 'UPDATE attachments SET status = %s, error_code = %s, updated_at = %s '
+ "WHERE id = %s AND status = 'ready'",
+ ('failed', 'object_missing', updated_at, attachment_id),
+ )
+ except (errors.Error, PoolTimeout):
+ raise ApiError(503, 'unavailable', 'Service unavailable') from None
diff --git a/evidence/pipeline-faults.json b/evidence/pipeline-faults.json
new file mode 100644
index 00000000..b0063690
--- /dev/null
+++ b/evidence/pipeline-faults.json
@@ -0,0 +1,11 @@
+{
+ "fault": "after-side-effect",
+ "attachment_id": "4889743e-52b9-40f1-a6ad-2d560b9aebcf",
+ "status": "ready",
+ "variant_names": [
+ "crop",
+ "optimized",
+ "thumbnail"
+ ],
+ "invariant": "deterministic effect keys produced one logical result"
+}
diff --git a/infra/README.md b/infra/README.md
index 5a39e862..b3017bb6 100644
--- a/infra/README.md
+++ b/infra/README.md
@@ -1,7 +1,50 @@
-# Инфраструктура студента
+# Compose + Nginx + MinIO
-Здесь разместите конфигурации выбранных сервисов; основную топологию — в корневом compose.yaml/stack.yaml. `compose.example.yaml` — только worksheet ролей и намеренно не запускается. `contracts/infrastructure.json` задаёт минимальные роли, не готовые образы/пароли.
+The runnable topology is in the root `compose.yaml`. The example Compose file
+and `contracts/infrastructure.json` are teaching worksheets, not deployments.
+The supported local entry point is Nginx; API, PostgreSQL, Redis and MinIO ports
+are not published to the host.
-В REPORT.md сопоставьте роль → service name → версия/digest → health/readiness → volume → сеть/порт → способ передачи credentials. Приведите bootstrap (schema, bucket, broker topology, а с lab6 provisioning) и безопасное повторение этих команд.
+| Role | Service / image | Persistence and readiness |
+| --- | --- | --- |
+| API | `api`, built from `Dockerfile` / Python 3.12.11 | Two stateless replicas; `/health/ready`; no host port |
+| Load balancer | `nginx:1.27.5-alpine` | Host port `${APP_PORT:-8080}`; Docker DNS refresh 5 s; passive fail exclusion |
+| Database | `postgres:16.8-alpine` | `postgres_data` named volume; `pg_isready` |
+| Sessions | `redis:7.4.2-alpine` | `redis_data` named volume; AOF `everysec`; Redis `PING` |
+| Object storage | MinIO `RELEASE.2025-09-07T16-13-09Z`, pinned by image digest in Compose | `minio_data` named volume; MinIO readiness endpoint; S3 port 9000 and console 9001 are private |
+| Migration job | Same API image | Runs ordered SQL migrations once before API replicas |
+| Bucket bootstrap | Same pinned MinIO image, using its `mc` client | Idempotently creates the private bucket, versioned policy, and restricted API user; replaces the prior policy without deleting volumes |
-Приложение строится из исходников. Не используйте заранее существующий образ преподавательского сервера вместо своей реализации. Restart hook перезапускает все соответствующие stores с volumes; failover hook останавливает только заданную API-реплику.
+PostgreSQL and S3 hold different parts of an attachment: PostgreSQL is the source
+of truth for metadata and access control; the private S3 bucket stores original
+bytes under a random server-generated key. The bucket name is fixed as
+`messenger-attachments`. No endpoint returns object keys or S3 credentials.
+
+The MinIO root credentials are mounted only into MinIO and its one-shot bootstrap
+job. The API receives a separate access key restricted to `GetBucketLocation`,
+`ListBucket` with the `objects/` prefix, and Get/Put/Delete on `objects/*`.
+The bootstrap grants no anonymous policy. Verify
+that from inside the Compose network with
+`py -3 -X utf8 student-tests/check_private_bucket.py`; it expects an unsigned
+bucket-list request to receive HTTP 403 and confirms MinIO has no host port
+binding. The administrative console is not exposed.
+
+Create local ignored secrets using `scripts/init-local-secrets.ps1`; never copy
+secrets from another lab. Do not rotate credentials while retaining the
+corresponding database or MinIO volumes. `scripts/restart.bat` / `.sh` restarts
+the API, database, Redis, MinIO and Nginx without deleting volumes.
+`scripts/stop-one.bat` / `.sh` stops only the API container whose hostname equals
+`TARGET_INSTANCE_ID` and leaves it stopped for the failover check.
+
+Attachment writes reserve PostgreSQL metadata in `processing` state before
+writing S3. On success, the row becomes `ready` and the API returns 201. Errors
+attempt to delete the object and mark the reservation `failed`; if compensation
+cannot reach either store, the processing row remains visible to reconciliation.
+Run `scripts/reconcile_attachments.py` in dry-run mode first. It only acts on
+records/objects older than a 15-minute minimum grace period, marks stale uploads
+failed, deletes old unreferenced objects, and reports missing objects for ready
+metadata. `--apply` is required for changes.
+
+MinIO, PostgreSQL, Redis, Nginx, and the Docker host are single-instance
+dependencies. This setup survives an API-replica failure and restarts with
+volumes, not loss of the Docker host or an individual state-store volume.
diff --git a/infra/minio-bootstrap.sh b/infra/minio-bootstrap.sh
new file mode 100644
index 00000000..1f0fe404
--- /dev/null
+++ b/infra/minio-bootstrap.sh
@@ -0,0 +1,34 @@
+#!/bin/sh
+set -eu
+
+root_user=$(cat /run/secrets/minio_root_user)
+root_password=$(cat /run/secrets/minio_root_password)
+service_user=$(cat /run/secrets/s3_access_key_id)
+service_password=$(cat /run/secrets/s3_secret_access_key)
+
+until mc alias set local http://minio:9000 "$root_user" "$root_password" >/dev/null 2>&1 \
+ && mc ready local >/dev/null 2>&1; do
+ sleep 2
+done
+
+bucket=${S3_BUCKET:-messenger-attachments}
+if [ "$bucket" != 'messenger-attachments' ]; then
+ printf '%s\n' 'S3_BUCKET must be messenger-attachments' >&2
+ exit 2
+fi
+policy=messenger-attachments-v2
+legacy_policy=messenger-attachments
+mc mb --ignore-existing "local/$bucket"
+if mc admin policy info local "$policy" >/dev/null 2>&1; then
+ mc admin policy detach local "$policy" --user "$service_user" >/dev/null 2>&1 || true
+ mc admin policy remove local "$policy" >/dev/null
+fi
+mc admin policy create local "$policy" /infra/s3-policy.json
+if ! mc admin user info local "$service_user" >/dev/null 2>&1; then
+ mc admin user add local "$service_user" "$service_password" >/dev/null
+fi
+mc admin policy attach local "$policy" --user "$service_user" >/dev/null
+if mc admin policy info local "$legacy_policy" >/dev/null 2>&1; then
+ mc admin policy detach local "$legacy_policy" --user "$service_user" >/dev/null
+ mc admin policy remove local "$legacy_policy" >/dev/null
+fi
diff --git a/infra/minio-entrypoint.sh b/infra/minio-entrypoint.sh
new file mode 100644
index 00000000..eeeeb20f
--- /dev/null
+++ b/infra/minio-entrypoint.sh
@@ -0,0 +1,6 @@
+#!/bin/sh
+set -eu
+
+export MINIO_ROOT_USER="$(cat /run/secrets/minio_root_user)"
+export MINIO_ROOT_PASSWORD="$(cat /run/secrets/minio_root_password)"
+exec minio server /data --address :9000 --console-address :9001
diff --git a/infra/nginx.conf b/infra/nginx.conf
new file mode 100644
index 00000000..b336f88e
--- /dev/null
+++ b/infra/nginx.conf
@@ -0,0 +1,26 @@
+resolver 127.0.0.11 valid=5s ipv6=off;
+
+upstream messenger_api {
+ zone messenger_api 64k;
+ server api:8080 resolve max_fails=1 fail_timeout=2s;
+}
+
+server {
+ listen 8080;
+ server_name _;
+ client_max_body_size 11m;
+ client_body_timeout 20s;
+
+ location / {
+ proxy_pass http://messenger_api;
+ proxy_http_version 1.1;
+ proxy_set_header Connection "";
+ proxy_set_header Host $host;
+ proxy_request_buffering off;
+ proxy_connect_timeout 2s;
+ proxy_send_timeout 20s;
+ proxy_read_timeout 20s;
+ proxy_next_upstream error timeout http_502 http_503 http_504;
+ proxy_next_upstream_tries 2;
+ }
+}
diff --git a/infra/s3-policy.json b/infra/s3-policy.json
new file mode 100644
index 00000000..76965d01
--- /dev/null
+++ b/infra/s3-policy.json
@@ -0,0 +1,28 @@
+{
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": ["s3:GetBucketLocation"],
+ "Resource": ["arn:aws:s3:::messenger-attachments"]
+ },
+ {
+ "Effect": "Allow",
+ "Action": ["s3:ListBucket"],
+ "Resource": ["arn:aws:s3:::messenger-attachments"],
+ "Condition": {
+ "StringLike": {
+ "s3:prefix": ["objects/", "objects/*", "staging/", "staging/*"]
+ }
+ }
+ },
+ {
+ "Effect": "Allow",
+ "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
+ "Resource": [
+ "arn:aws:s3:::messenger-attachments/objects/*",
+ "arn:aws:s3:::messenger-attachments/staging/*"
+ ]
+ }
+ ]
+}
diff --git a/migrations/001_schema.sql b/migrations/001_schema.sql
new file mode 100644
index 00000000..a6187514
--- /dev/null
+++ b/migrations/001_schema.sql
@@ -0,0 +1,34 @@
+CREATE TABLE IF NOT EXISTS users (
+ id UUID PRIMARY KEY,
+ username TEXT NOT NULL,
+ display_name TEXT NOT NULL,
+ password_hash TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS users_username_key ON users (username);
+
+CREATE TABLE IF NOT EXISTS chats (
+ id UUID PRIMARY KEY,
+ title TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS chat_members (
+ chat_id UUID NOT NULL REFERENCES chats (id) ON DELETE CASCADE,
+ user_id UUID NOT NULL REFERENCES users (id) ON DELETE CASCADE,
+ position INT NOT NULL,
+ PRIMARY KEY (chat_id, user_id)
+);
+
+CREATE INDEX IF NOT EXISTS chat_members_user_id_idx ON chat_members (user_id);
+
+CREATE TABLE IF NOT EXISTS messages (
+ id UUID PRIMARY KEY,
+ chat_id UUID NOT NULL REFERENCES chats (id) ON DELETE CASCADE,
+ sender_id UUID NOT NULL REFERENCES users (id) ON DELETE CASCADE,
+ text TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS messages_chat_history_idx ON messages (chat_id, created_at ASC, id ASC);
diff --git a/migrations/002_message_idempotency.sql b/migrations/002_message_idempotency.sql
new file mode 100644
index 00000000..07e8b08b
--- /dev/null
+++ b/migrations/002_message_idempotency.sql
@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS message_idempotency (
+ user_id UUID NOT NULL REFERENCES users (id) ON DELETE CASCADE,
+ method TEXT NOT NULL CHECK (method = 'POST'),
+ resource_path TEXT NOT NULL,
+ idempotency_key VARCHAR(128) NOT NULL,
+ request_hash CHAR(64) NOT NULL,
+ response JSONB,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ expires_at TIMESTAMPTZ NOT NULL,
+ PRIMARY KEY (user_id, method, resource_path, idempotency_key)
+);
+
+CREATE INDEX IF NOT EXISTS message_idempotency_expiry_idx
+ ON message_idempotency (user_id, expires_at);
diff --git a/migrations/003_attachments.sql b/migrations/003_attachments.sql
new file mode 100644
index 00000000..a4efe424
--- /dev/null
+++ b/migrations/003_attachments.sql
@@ -0,0 +1,34 @@
+CREATE TABLE IF NOT EXISTS attachments (
+ id UUID PRIMARY KEY,
+ chat_id UUID NOT NULL REFERENCES chats (id) ON DELETE CASCADE,
+ owner_id UUID NOT NULL REFERENCES users (id) ON DELETE CASCADE,
+ object_key TEXT NOT NULL UNIQUE,
+ filename TEXT NOT NULL,
+ content_type TEXT NOT NULL CHECK (content_type IN ('image/png', 'image/jpeg')),
+ size_bytes BIGINT NOT NULL CHECK (size_bytes BETWEEN 1 AND 10485760),
+ sha256 CHAR(64) NOT NULL,
+ width INT NOT NULL CHECK (width > 0),
+ height INT NOT NULL CHECK (height > 0),
+ status TEXT NOT NULL CHECK (status IN ('processing', 'ready', 'failed')),
+ variants JSONB NOT NULL DEFAULT '[]'::jsonb,
+ error_code TEXT,
+ created_at TIMESTAMPTZ NOT NULL,
+ updated_at TIMESTAMPTZ NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS attachments_chat_created_idx
+ ON attachments (chat_id, created_at, id);
+CREATE INDEX IF NOT EXISTS attachments_processing_created_idx
+ ON attachments (created_at)
+ WHERE status = 'processing';
+
+CREATE TABLE IF NOT EXISTS 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 CHECK (position >= 0),
+ PRIMARY KEY (message_id, attachment_id),
+ UNIQUE (message_id, position)
+);
+
+CREATE INDEX IF NOT EXISTS message_attachments_attachment_idx
+ ON message_attachments (attachment_id);
diff --git a/migrations/004_async_attachment_jobs.sql b/migrations/004_async_attachment_jobs.sql
new file mode 100644
index 00000000..ad85597f
--- /dev/null
+++ b/migrations/004_async_attachment_jobs.sql
@@ -0,0 +1,38 @@
+ALTER TABLE attachments
+ ADD COLUMN IF NOT EXISTS staging_key TEXT,
+ ADD COLUMN IF NOT EXISTS pipeline_version INTEGER NOT NULL DEFAULT 1;
+
+UPDATE attachments
+SET staging_key = object_key
+WHERE staging_key IS NULL;
+
+ALTER TABLE attachments DROP CONSTRAINT IF EXISTS attachments_status_check;
+ALTER TABLE attachments ADD CONSTRAINT attachments_status_check
+ CHECK (status IN ('queued', 'processing', 'ready', 'failed'));
+
+CREATE TABLE IF NOT EXISTS attachment_jobs (
+ job_id UUID PRIMARY KEY,
+ attachment_id UUID NOT NULL REFERENCES attachments (id) ON DELETE CASCADE,
+ pipeline_version INTEGER NOT NULL,
+ attempts INTEGER NOT NULL DEFAULT 0,
+ status TEXT NOT NULL CHECK (status IN ('queued', 'processing', 'ready', 'failed')),
+ next_attempt_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ lease_until TIMESTAMPTZ,
+ last_error TEXT,
+ created_at TIMESTAMPTZ NOT NULL,
+ updated_at TIMESTAMPTZ NOT NULL,
+ UNIQUE (attachment_id, pipeline_version)
+);
+
+CREATE INDEX IF NOT EXISTS attachment_jobs_ready_idx
+ ON attachment_jobs (status, next_attempt_at);
+
+CREATE TABLE IF NOT EXISTS attachment_outbox (
+ id BIGSERIAL PRIMARY KEY,
+ job_id UUID NOT NULL REFERENCES attachment_jobs (job_id) ON DELETE CASCADE,
+ published_at TIMESTAMPTZ,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS attachment_outbox_pending_idx
+ ON attachment_outbox (published_at, id);
diff --git a/migrations/005_replay_audit.sql b/migrations/005_replay_audit.sql
new file mode 100644
index 00000000..3bf93d56
--- /dev/null
+++ b/migrations/005_replay_audit.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS attachment_replay_audit (
+ id BIGSERIAL PRIMARY KEY,
+ attachment_id UUID NOT NULL REFERENCES attachments (id) ON DELETE CASCADE,
+ old_pipeline_version INTEGER NOT NULL,
+ new_pipeline_version INTEGER NOT NULL,
+ reason TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL
+);
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 00000000..dbc2f1a1
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,5 @@
+argon2-cffi==23.1.0
+psycopg[binary,pool]==3.2.9
+redis==5.2.1
+boto3==1.37.38
+Pillow==11.1.0
diff --git a/s3store.py b/s3store.py
new file mode 100644
index 00000000..9c1ea9d9
--- /dev/null
+++ b/s3store.py
@@ -0,0 +1,106 @@
+import os
+from pathlib import Path
+
+import boto3
+from botocore.config import Config
+from botocore.exceptions import BotoCoreError, ClientError
+
+
+class S3Unavailable(RuntimeError):
+ pass
+
+
+def _read_secret(file_variable, value_variable):
+ path = os.environ.get(file_variable)
+ if path:
+ return Path(path).read_text(encoding='utf-8').strip()
+ value = os.environ.get(value_variable, '').strip()
+ if not value:
+ raise RuntimeError(value_variable + ' or ' + file_variable + ' is required')
+ return value
+
+
+class ObjectStore:
+ def __init__(self, client, bucket):
+ self.client = client
+ self.bucket = bucket
+
+ @classmethod
+ def from_env(cls):
+ client = boto3.client(
+ 's3',
+ endpoint_url=os.environ.get('S3_ENDPOINT', 'http://minio:9000'),
+ region_name=os.environ.get('S3_REGION', 'us-east-1'),
+ aws_access_key_id=_read_secret('S3_ACCESS_KEY_ID_FILE', 'S3_ACCESS_KEY_ID'),
+ aws_secret_access_key=_read_secret(
+ 'S3_SECRET_ACCESS_KEY_FILE', 'S3_SECRET_ACCESS_KEY'
+ ),
+ config=Config(
+ signature_version='s3v4',
+ s3={'addressing_style': 'path'},
+ connect_timeout=2,
+ read_timeout=10,
+ max_pool_connections=32,
+ retries={'max_attempts': 2, 'mode': 'standard'},
+ ),
+ )
+ return cls(client, os.environ.get('S3_BUCKET', 'messenger-attachments'))
+
+ def ping(self):
+ try:
+ self.client.get_bucket_location(Bucket=self.bucket)
+ except (BotoCoreError, ClientError) as error:
+ raise S3Unavailable('S3 bucket is unavailable') from error
+
+ def put_file(self, key, fileobj, size, content_type):
+ fileobj.seek(0)
+ try:
+ self.client.put_object(
+ Bucket=self.bucket,
+ Key=key,
+ Body=fileobj,
+ ContentLength=size,
+ ContentType=content_type,
+ )
+ except (BotoCoreError, ClientError) as error:
+ raise S3Unavailable('S3 upload failed') from error
+
+ def get_object(self, key):
+ try:
+ return self.client.get_object(Bucket=self.bucket, Key=key)
+ except ClientError as error:
+ if error.response.get('Error', {}).get('Code') in {
+ '404', 'NoSuchKey', 'NotFound',
+ }:
+ return None
+ raise S3Unavailable('S3 download failed') from error
+ except BotoCoreError as error:
+ raise S3Unavailable('S3 download failed') from error
+
+ def delete_object(self, key):
+ try:
+ self.client.delete_object(Bucket=self.bucket, Key=key)
+ except (BotoCoreError, ClientError) as error:
+ raise S3Unavailable('S3 delete failed') from error
+
+ def object_exists(self, key):
+ try:
+ self.client.head_object(Bucket=self.bucket, Key=key)
+ return True
+ except ClientError as error:
+ if error.response.get('Error', {}).get('Code') in {
+ '404', 'NoSuchKey', 'NotFound',
+ }:
+ return False
+ raise S3Unavailable('S3 object check failed') from error
+ except BotoCoreError as error:
+ raise S3Unavailable('S3 object check failed') from error
+
+ def list_objects(self):
+ try:
+ paginator = self.client.get_paginator('list_objects_v2')
+ for page in paginator.paginate(Bucket=self.bucket, Prefix='objects/'):
+ for item in page.get('Contents', []):
+ yield item
+ except (BotoCoreError, ClientError) as error:
+ raise S3Unavailable('S3 listing failed') from error
diff --git a/scripts/init-local-secrets.ps1 b/scripts/init-local-secrets.ps1
new file mode 100644
index 00000000..9933361d
--- /dev/null
+++ b/scripts/init-local-secrets.ps1
@@ -0,0 +1,60 @@
+$ErrorActionPreference = 'Stop'
+$root = Split-Path -Parent $PSScriptRoot
+$secrets = Join-Path $root 'secrets'
+$names = @(
+ 'postgres_password',
+ 'database_url',
+ 'minio_root_user',
+ 'minio_root_password',
+ 's3_access_key_id',
+ 's3_secret_access_key'
+)
+
+if (-not (Test-Path (Join-Path $root '.env'))) {
+ Copy-Item (Join-Path $root '.env.example') (Join-Path $root '.env')
+}
+
+$existing = @($names | Where-Object { Test-Path (Join-Path $secrets $_) })
+if ($existing.Count -gt 0) {
+ if ($existing.Count -eq $names.Count) {
+ Write-Output 'Local secrets already exist; leaving them unchanged.'
+ exit 0
+ }
+ throw 'The local secret set is incomplete. Restore it as a set; do not rotate credentials against existing volumes.'
+}
+
+New-Item -ItemType Directory -Force $secrets | Out-Null
+function New-HexSecret([int]$byteCount) {
+ $bytes = New-Object byte[] $byteCount
+ $rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
+ try {
+ $rng.GetBytes($bytes)
+ }
+ finally {
+ $rng.Dispose()
+ }
+ $builder = New-Object System.Text.StringBuilder
+ foreach ($byte in $bytes) {
+ [void]$builder.Append($byte.ToString('x2'))
+ }
+ return $builder.ToString()
+}
+
+$databasePassword = New-HexSecret 32
+$values = @{
+ 'postgres_password' = $databasePassword
+ 'database_url' = "postgresql://messenger:$databasePassword@postgres:5432/messenger"
+ 'minio_root_user' = 'root-' + (New-HexSecret 6)
+ 'minio_root_password' = New-HexSecret 32
+ 's3_access_key_id' = New-HexSecret 10
+ 's3_secret_access_key' = New-HexSecret 32
+}
+foreach ($name in $names) {
+ $path = Join-Path $secrets $name
+ [System.IO.File]::WriteAllText(
+ $path,
+ $values[$name],
+ [System.Text.Encoding]::ASCII
+ )
+}
+Write-Output 'Created local Compose secrets. Their values were not printed.'
diff --git a/scripts/migrate.py b/scripts/migrate.py
new file mode 100644
index 00000000..6ead0bbf
--- /dev/null
+++ b/scripts/migrate.py
@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Apply database migrations once before API replicas start."""
+import logging
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from db import Store
+
+
+def main():
+ logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s %(message)s')
+ store = Store.connect()
+ try:
+ logging.info('database migrations are current')
+ finally:
+ store.close()
+
+
+if __name__ == '__main__':
+ main()
diff --git a/scripts/reconcile_attachments.py b/scripts/reconcile_attachments.py
new file mode 100644
index 00000000..10c9d885
--- /dev/null
+++ b/scripts/reconcile_attachments.py
@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""Dry-run first; remove only old, unreferenced objects or stale upload attempts."""
+import argparse
+from datetime import datetime, timedelta, timezone
+import json
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from db import ApiError, Store
+from s3store import ObjectStore, S3Unavailable
+
+
+def parse_timestamp(value):
+ return datetime.fromisoformat(value.replace('Z', '+00:00'))
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument('--grace-seconds', type=int, default=900)
+ parser.add_argument('--apply', action='store_true')
+ args = parser.parse_args()
+ if args.grace_seconds < 900:
+ parser.error('--grace-seconds must be at least 900')
+
+ store = Store.connect(run_migrations=False)
+ objects = ObjectStore.from_env()
+ try:
+ cutoff = datetime.now(timezone.utc) - timedelta(seconds=args.grace_seconds)
+ records = store.list_attachments_for_reconciliation()
+ by_key = {record['object_key']: record for record in records}
+ summary = {
+ 'mode': 'apply' if args.apply else 'dry-run',
+ 'grace_seconds': args.grace_seconds,
+ 'stale_uploads': 0,
+ 'old_failed_objects': 0,
+ 'orphan_objects': 0,
+ 'missing_ready_objects': 0,
+ 'actions_applied': 0,
+ }
+
+ for record in records:
+ key = record['object_key']
+ if (record['status'] == 'processing'
+ and parse_timestamp(record['created_at']) < cutoff):
+ summary['stale_uploads'] += 1
+ exists = objects.object_exists(key)
+ if args.apply:
+ if exists:
+ objects.delete_object(key)
+ store.mark_attachment_failed(
+ record['id'], 'upload_interrupted', datetime.now(timezone.utc)
+ )
+ summary['actions_applied'] += 1
+ elif (record['status'] == 'failed'
+ and parse_timestamp(record['updated_at']) < cutoff):
+ if objects.object_exists(key):
+ summary['old_failed_objects'] += 1
+ if args.apply:
+ objects.delete_object(key)
+ summary['actions_applied'] += 1
+ elif record['status'] == 'ready' and not objects.object_exists(key):
+ summary['missing_ready_objects'] += 1
+ if args.apply:
+ store.mark_reconciled_missing(
+ record['id'], datetime.now(timezone.utc)
+ )
+ summary['actions_applied'] += 1
+
+ for item in objects.list_objects():
+ key = item['Key']
+ if key in by_key or item['LastModified'] >= cutoff:
+ continue
+ summary['orphan_objects'] += 1
+ if args.apply:
+ objects.delete_object(key)
+ summary['actions_applied'] += 1
+
+ print(json.dumps(summary, sort_keys=True))
+ finally:
+ store.close()
+ objects.client.close()
+
+
+if __name__ == '__main__':
+ try:
+ main()
+ except (ApiError, S3Unavailable) as error:
+ print('Reconciliation failed: ' + error.message if isinstance(error, ApiError) else
+ 'Reconciliation failed: S3 is unavailable', file=sys.stderr)
+ raise SystemExit(1) from None
diff --git a/scripts/replay_attachment.py b/scripts/replay_attachment.py
new file mode 100644
index 00000000..6264c7d0
--- /dev/null
+++ b/scripts/replay_attachment.py
@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Replay one failed attachment through a new pipeline version."""
+import argparse
+from datetime import datetime, timezone
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from db import ApiError, Store
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("attachment_id")
+ parser.add_argument("--reason", default="operator_replay")
+ args = parser.parse_args()
+ store = Store.connect(run_migrations=False)
+ try:
+ job_id, version = store.replay_attachment(
+ args.attachment_id,
+ args.reason,
+ datetime.now(timezone.utc),
+ )
+ print("replayed attachment=%s job=%s pipeline_version=%d" %
+ (args.attachment_id, job_id, version))
+ finally:
+ store.close()
+
+
+if __name__ == "__main__":
+ try:
+ main()
+ except ApiError as error:
+ print("Replay failed: " + error.message, file=sys.stderr)
+ raise SystemExit(1) from None
diff --git a/scripts/restart.sh b/scripts/restart.sh
new file mode 100644
index 00000000..7278b455
--- /dev/null
+++ b/scripts/restart.sh
@@ -0,0 +1,4 @@
+#!/bin/sh
+set -eu
+cd "$(dirname "$0")/.."
+docker compose restart api postgres redis minio nginx
diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh
new file mode 100644
index 00000000..c957ceb3
--- /dev/null
+++ b/scripts/stop-one.sh
@@ -0,0 +1,16 @@
+#!/bin/sh
+set -eu
+
+: "${TARGET_INSTANCE_ID:?TARGET_INSTANCE_ID is required}"
+cd "$(dirname "$0")/.."
+
+for container_id in $(docker compose ps -q api); do
+ instance_id=$(docker inspect --format '{{.Config.Hostname}}' "$container_id")
+ if [ "$instance_id" = "$TARGET_INSTANCE_ID" ]; then
+ docker stop --time 2 "$container_id" >/dev/null
+ exit 0
+ fi
+done
+
+printf '%s\n' 'No running API replica matches TARGET_INSTANCE_ID' >&2
+exit 1
diff --git a/sessions.py b/sessions.py
new file mode 100644
index 00000000..e579fb04
--- /dev/null
+++ b/sessions.py
@@ -0,0 +1,43 @@
+import os
+
+import redis
+
+
+class SessionStore:
+ def __init__(self, url, connect_timeout=2.0, socket_timeout=2.0):
+ self._url = url
+ self._client = redis.from_url(
+ url,
+ decode_responses=True,
+ socket_connect_timeout=connect_timeout,
+ socket_timeout=socket_timeout,
+ health_check_interval=30,
+ )
+ self._prefix = 'sess:'
+
+ @classmethod
+ def from_env(cls):
+ url = _read_config('CACHE_URL_FILE', 'CACHE_URL')
+ if not url:
+ raise RuntimeError('CACHE_URL or CACHE_URL_FILE is required when SESSION_STORE=redis')
+ return cls(url)
+
+ def ping(self):
+ return self._client.ping()
+
+ def create(self, token, user_id, ttl_seconds):
+ self._client.setex(self._prefix + token, ttl_seconds, user_id)
+
+ def get_user_id(self, token):
+ return self._client.get(self._prefix + token)
+
+ def revoke(self, token):
+ return self._client.delete(self._prefix + token) > 0
+
+
+def _read_config(file_env, value_env):
+ path = os.environ.get(file_env)
+ if path and os.path.isfile(path):
+ with open(path, encoding='utf-8') as handle:
+ return handle.read().strip()
+ return os.environ.get(value_env, '').strip()
diff --git a/student-tests/check_private_bucket.py b/student-tests/check_private_bucket.py
new file mode 100644
index 00000000..e768937c
--- /dev/null
+++ b/student-tests/check_private_bucket.py
@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Check anonymous access to the private bucket from inside the Compose network."""
+from pathlib import Path
+import json
+import subprocess
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / 'tests'))
+from client import Failure, run
+
+
+def main():
+ code = (
+ "import os, urllib.error, urllib.request; "
+ "bucket=os.environ['S3_BUCKET']; "
+ "url='http://minio:9000/'+bucket+'?list-type=2&prefix=objects%2F'; "
+ "req=urllib.request.Request(url); "
+ "\ntry:\n urllib.request.urlopen(req, timeout=3)\n"
+ "except urllib.error.HTTPError as error:\n"
+ " raise SystemExit(0 if error.code == 403 else 1)\n"
+ "raise SystemExit(1)"
+ )
+ result = subprocess.run(
+ ['docker', 'compose', 'exec', '-T', 'api', 'python', '-c', code],
+ cwd=ROOT,
+ capture_output=True,
+ text=True,
+ )
+ if result.returncode:
+ raise Failure('anonymous MinIO bucket request did not return HTTP 403')
+ container_id = subprocess.run(
+ ['docker', 'compose', 'ps', '-q', 'minio'],
+ cwd=ROOT,
+ capture_output=True,
+ text=True,
+ check=True,
+ ).stdout.strip()
+ if not container_id:
+ raise Failure('MinIO container is not running')
+ bindings = subprocess.run(
+ ['docker', 'inspect', '--format', '{{json .HostConfig.PortBindings}}', container_id],
+ cwd=ROOT,
+ capture_output=True,
+ text=True,
+ check=True,
+ ).stdout.strip()
+ if any(value for value in json.loads(bindings).values()):
+ raise Failure('MinIO S3 endpoint must not be published on the host')
+ print('PASS: anonymous bucket access is denied and the S3 port is not published.')
+
+
+if __name__ == '__main__':
+ run(main)
diff --git a/student-tests/test_attachments.py b/student-tests/test_attachments.py
new file mode 100644
index 00000000..01dd7c26
--- /dev/null
+++ b/student-tests/test_attachments.py
@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""Student negative and concurrency checks for the lab 4 attachment API."""
+from concurrent.futures import ThreadPoolExecutor
+import http.client
+import hashlib
+import json
+from pathlib import Path
+import re
+import struct
+import subprocess
+import sys
+import threading
+import time
+import zlib
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / 'tests'))
+from client import Client, arguments, check, run
+from urllib.parse import quote, urlsplit
+
+MAX_UPLOAD_BYTES = 10 * 1024 * 1024
+PARALLEL_UPLOADS = 10
+ANSI_ESCAPE = re.compile(r'\x1b\[[0-?]*[ -/]*[@-~]')
+
+
+def png_chunk(kind, data):
+ return (
+ struct.pack('>I', len(data))
+ + kind
+ + data
+ + struct.pack('>I', zlib.crc32(kind + data) & 0xffffffff)
+ )
+
+
+def random_png(width=1600, height=1600):
+ seed = 0x4C414234
+ pixels = bytearray(width * height)
+ for index in range(len(pixels)):
+ seed = (1664525 * seed + 1013904223) & 0xffffffff
+ pixels[index] = seed >> 24
+ rows = b''.join(
+ b'\x00' + pixels[row * width:(row + 1) * width]
+ for row in range(height)
+ )
+ header = struct.pack('>IIBBBBB', width, height, 8, 0, 0, 0, 0)
+ return (
+ b'\x89PNG\r\n\x1a\n'
+ + png_chunk(b'IHDR', header)
+ + png_chunk(b'IDAT', zlib.compress(rows))
+ + png_chunk(b'IEND', b'')
+ )
+
+
+def memory_bytes(value):
+ match = re.match(r'\s*([\d.]+)\s*(B|KiB|MiB|GiB)', value)
+ check(match is not None, 'could not parse docker stats memory value')
+ factors = {'B': 1, 'KiB': 1024, 'MiB': 1024 ** 2, 'GiB': 1024 ** 3}
+ return int(float(match.group(1)) * factors[match.group(2)])
+
+
+def api_memory(container_ids):
+ output = subprocess.run(
+ ['docker', 'stats', '--no-stream', '--format', '{{.MemUsage}}', *container_ids],
+ cwd=ROOT,
+ check=True,
+ capture_output=True,
+ text=True,
+ ).stdout
+ lines = [line.strip() for line in output.splitlines() if line.strip()]
+ check(len(lines) == len(container_ids), 'docker stats did not report every API replica')
+ return sum(memory_bytes(line.split('/', 1)[0]) for line in lines)
+
+
+def make_upload(client, actor, chat_id, filename, content, content_type='image/png'):
+ return client.call(
+ 'POST',
+ '/api/v1/chats/' + chat_id + '/attachments?filename=' + quote(filename, safe=''),
+ 201,
+ actor=actor,
+ raw=content,
+ headers={'Content-Type': content_type},
+ schema='Attachment',
+ )['json']
+
+
+def slow_upload(base_url, actor, chat_id, index, content):
+ endpoint = urlsplit(base_url or 'http://localhost:8080')
+ check(endpoint.scheme == 'http', 'memory test currently requires the local HTTP endpoint')
+ connection = http.client.HTTPConnection(
+ endpoint.hostname, endpoint.port or 80, timeout=30
+ )
+ path = (
+ '/api/v1/chats/' + chat_id + '/attachments?filename='
+ + quote('parallel-' + str(index) + '.png', safe='')
+ )
+ try:
+ connection.putrequest('POST', path)
+ connection.putheader('Authorization', 'Bearer ' + actor['token'])
+ connection.putheader('Accept', 'application/json')
+ connection.putheader('Content-Type', 'image/png')
+ connection.putheader('Content-Length', str(len(content)))
+ connection.putheader('Connection', 'close')
+ connection.endheaders()
+ chunk_size = 64 * 1024
+ for offset in range(0, len(content), chunk_size):
+ connection.send(content[offset:offset + chunk_size])
+ time.sleep(0.05)
+ response = connection.getresponse()
+ payload = json.loads(response.read())
+ check(response.status == 201, 'parallel upload did not return 201')
+ check(bool(response.getheader('X-Request-Id')), 'parallel upload has no request ID')
+ check(bool(response.getheader('X-Instance-Id')), 'parallel upload has no instance ID')
+ from client import shape
+ shape(payload, 'Attachment')
+ return payload
+ finally:
+ connection.close()
+
+
+def main():
+ args = arguments('Attachment negative tests and 10-way upload memory measurement')
+ client = Client(args.base_url, args.ca_file, timeout=30)
+ alice, bob, eve, chat = client.bootstrap()
+ fixture = (ROOT / 'tests' / 'fixtures' / 'sample.png').read_bytes()
+ attachment = make_upload(client, alice, chat['id'], 'sample.png', fixture)
+
+ large = b'x' * (MAX_UPLOAD_BYTES + 1)
+ client.call(
+ 'POST',
+ '/api/v1/chats/' + chat['id'] + '/attachments?filename=large.png',
+ 413,
+ actor=alice,
+ raw=large,
+ headers={'Content-Type': 'image/png'},
+ )
+ pixel_header = (
+ b'\x89PNG\r\n\x1a\n'
+ + png_chunk(
+ b'IHDR',
+ struct.pack('>IIBBBBB', 10000, 5000, 8, 0, 0, 0, 0),
+ )
+ + png_chunk(b'IDAT', zlib.compress(b''))
+ + png_chunk(b'IEND', b'')
+ )
+ client.call(
+ 'POST',
+ '/api/v1/chats/' + chat['id'] + '/attachments?filename=too-many-pixels.png',
+ 413,
+ actor=alice,
+ raw=pixel_header,
+ headers={'Content-Type': 'image/png'},
+ )
+ client.call(
+ 'POST',
+ '/api/v1/chats/' + chat['id'] + '/attachments?filename=broken.png',
+ 415,
+ actor=alice,
+ raw=b'not a PNG image',
+ headers={'Content-Type': 'image/png'},
+ )
+ client.call(
+ 'POST',
+ '/api/v1/chats/' + chat['id'] + '/attachments?filename=spoofed.jpg',
+ 415,
+ actor=alice,
+ raw=fixture,
+ headers={'Content-Type': 'image/jpeg'},
+ )
+ client.call(
+ 'POST',
+ '/api/v1/chats/' + chat['id'] + '/attachments?filename=..%2Fprivate.png',
+ 400,
+ actor=alice,
+ raw=fixture,
+ headers={'Content-Type': 'image/png'},
+ )
+
+ for path in (
+ '/api/v1/attachments/' + attachment['id'],
+ '/api/v1/attachments/' + attachment['id'] + '/content',
+ ):
+ client.call('GET', path, 404, actor=eve)
+
+ other_chat = client.call(
+ 'POST',
+ '/api/v1/chats',
+ 201,
+ actor=alice,
+ body={'title': 'Другой чат', 'member_ids': [alice['id'], bob['id']]},
+ schema='Chat',
+ )['json']
+ client.call(
+ 'POST',
+ '/api/v1/chats/' + other_chat['id'] + '/messages',
+ 404,
+ actor=alice,
+ body={'text': 'Чужое вложение', 'attachment_ids': [attachment['id']]},
+ headers={'Idempotency-Key': 'cross-chat-attachment-check'},
+ )
+
+ content = random_png()
+ check(0 < len(content) <= MAX_UPLOAD_BYTES, 'generated stress image exceeds upload limit')
+ container_ids = subprocess.run(
+ ['docker', 'compose', 'ps', '-q', 'api'],
+ cwd=ROOT,
+ check=True,
+ capture_output=True,
+ text=True,
+ ).stdout.split()
+ check(len(container_ids) >= 2, 'memory test requires at least two API containers')
+ baseline = api_memory(container_ids)
+ samples = []
+ latest = {}
+ stats_process = subprocess.Popen(
+ [
+ 'docker', 'stats', '--format', '{{.Name}}|{{.MemUsage}}',
+ *container_ids,
+ ],
+ cwd=ROOT,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.DEVNULL,
+ text=True,
+ bufsize=1,
+ )
+
+ def monitor():
+ for line in stats_process.stdout:
+ line = ANSI_ESCAPE.sub('', line)
+ parts = line.strip().split('|', 1)
+ if len(parts) != 2:
+ continue
+ try:
+ latest[parts[0]] = memory_bytes(parts[1].split('/', 1)[0])
+ except AssertionError:
+ continue
+ if len(latest) >= len(container_ids):
+ samples.append(sum(latest.values()))
+
+ monitor_thread = threading.Thread(target=monitor, daemon=True)
+ monitor_thread.start()
+ barrier = threading.Barrier(PARALLEL_UPLOADS)
+
+ def worker(index):
+ barrier.wait()
+ return slow_upload(
+ args.base_url,
+ alice,
+ chat['id'],
+ index,
+ content,
+ )
+
+ started = time.monotonic()
+ try:
+ with ThreadPoolExecutor(max_workers=PARALLEL_UPLOADS) as pool:
+ results = list(pool.map(worker, range(PARALLEL_UPLOADS)))
+ finally:
+ stats_process.terminate()
+ stats_process.wait(timeout=5)
+ monitor_thread.join(timeout=5)
+ elapsed = time.monotonic() - started
+ check(len(results) == PARALLEL_UPLOADS, 'not all simultaneous uploads completed')
+ check(samples, 'Docker stats did not produce any in-flight memory samples')
+ check(all(item['status'] == 'ready' for item in results), 'an upload was not ready')
+ check(len({item['id'] for item in results}) == PARALLEL_UPLOADS, 'upload IDs were reused')
+ peak = max(samples + [baseline])
+ report = {
+ 'concurrent_uploads': PARALLEL_UPLOADS,
+ 'image_size_bytes': len(content),
+ 'image_sha256': hashlib.sha256(content).hexdigest(),
+ 'elapsed_seconds': round(elapsed, 3),
+ 'api_memory_baseline_bytes': baseline,
+ 'api_memory_peak_sampled_bytes': peak,
+ 'api_memory_sampled_delta_bytes': peak - baseline,
+ 'memory_sample_interval_seconds': 1,
+ 'memory_sample_count': len(samples),
+ 'notes': 'Docker stats streams aggregate API-container memory at about one-second intervals; short peaks may be missed.',
+ }
+ output = ROOT / 'evidence' / 'attachment-concurrency.json'
+ output.parent.mkdir(parents=True, exist_ok=True)
+ output.write_text(json.dumps(report, indent=2) + '\n', encoding='utf-8')
+ print(json.dumps(report, indent=2))
+ print('PASS: attachment limits, image validation, access controls and 10 concurrent uploads.')
+
+
+if __name__ == '__main__':
+ run(main)
diff --git a/student-tests/test_s3_outage.py b/student-tests/test_s3_outage.py
new file mode 100644
index 00000000..5e602d10
--- /dev/null
+++ b/student-tests/test_s3_outage.py
@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""Explicitly stop MinIO, verify uploads fail as unavailable, and restore it."""
+from pathlib import Path
+import subprocess
+import sys
+import time
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / 'tests'))
+from client import Client, arguments, check, run
+
+
+def compose(*args):
+ return subprocess.run(
+ ['docker', 'compose', *args],
+ cwd=ROOT,
+ check=True,
+ capture_output=True,
+ text=True,
+ )
+
+
+def main():
+ args = arguments('MinIO outage behavior; stops and starts the lab MinIO service')
+ client = Client(args.base_url, args.ca_file)
+ alice, _bob, _eve, chat = client.bootstrap()
+ sample = (ROOT / 'tests' / 'fixtures' / 'sample.png').read_bytes()
+ compose('stop', 'minio')
+ try:
+ time.sleep(2)
+ response = client.call(
+ 'POST',
+ '/api/v1/chats/' + chat['id'] + '/attachments?filename=outage.png',
+ 503,
+ actor=alice,
+ raw=sample,
+ headers={'Content-Type': 'image/png'},
+ )
+ check(response['json']['error']['code'] == 'unavailable', 'S3 outage was not reported as unavailable')
+ finally:
+ compose('start', 'minio')
+ deadline = time.monotonic() + 90
+ while time.monotonic() < deadline:
+ try:
+ client.call('GET', '/health/ready', schema='Health')
+ break
+ except AssertionError:
+ time.sleep(1)
+ else:
+ raise RuntimeError('MinIO/API did not recover within 90 seconds')
+ print('PASS: MinIO outage returned 503 and the service recovered without removing volumes.')
+
+
+if __name__ == '__main__':
+ run(main)
diff --git a/tests/pipeline_faults.py b/tests/pipeline_faults.py
new file mode 100644
index 00000000..a5735d3b
--- /dev/null
+++ b/tests/pipeline_faults.py
@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Exercise a worker crash window and verify idempotent recovery."""
+import json
+from pathlib import Path
+import subprocess
+import time
+
+from client import Client, arguments, check, run
+
+
+def main():
+ args = arguments(__doc__)
+ client = Client(args.base_url, args.ca_file, timeout=10)
+ alice, _bob, _eve, chat = client.bootstrap()
+ root = Path(__file__).resolve().parents[1]
+ evidence = root / "evidence" / "pipeline-faults.json"
+ subprocess.run(["docker", "compose", "stop", "worker"], cwd=root, check=True,
+ stdout=subprocess.DEVNULL)
+ try:
+ attachment, _ = client.attachment(alice, chat)
+ fault_name = "lab5-fault-worker"
+ subprocess.run(["docker", "rm", "-f", fault_name], cwd=root,
+ check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+ subprocess.run(
+ ["docker", "compose", "run", "-d", "--no-deps", "--name", fault_name,
+ "-e", "FAULT_INJECTION=after-side-effect", "-e", "JOB_TIMEOUT_SECONDS=5",
+ "worker"],
+ cwd=root, check=True, stdout=subprocess.DEVNULL,
+ )
+ time.sleep(7)
+ subprocess.run(["docker", "rm", "-f", fault_name], cwd=root, check=False,
+ stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+ recovery_name = "lab5-recovery-worker"
+ subprocess.run(["docker", "rm", "-f", recovery_name], cwd=root, check=False,
+ stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+ subprocess.run(
+ ["docker", "compose", "run", "-d", "--no-deps", "--name", recovery_name,
+ "-e", "JOB_TIMEOUT_SECONDS=5", "worker"],
+ cwd=root, check=True, stdout=subprocess.DEVNULL,
+ )
+ ready = client.wait_ready(alice, attachment, wait_seconds=60)
+ variants = {item["name"]: item for item in ready["variants"]}
+ check(len(variants) == 3, "recovery did not publish exactly three variants")
+ result = {
+ "fault": "after-side-effect",
+ "attachment_id": attachment["id"],
+ "status": ready["status"],
+ "variant_names": sorted(variants),
+ "invariant": "deterministic effect keys produced one logical result",
+ }
+ evidence.write_text(json.dumps(result, indent=2) + "\n", encoding="utf-8")
+ print("PASS: fault injection recovered idempotently")
+ finally:
+ subprocess.run(["docker", "rm", "-f", "lab5-recovery-worker"], cwd=root,
+ check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+ subprocess.run(["docker", "compose", "start", "worker"], cwd=root, check=False,
+ stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+
+if __name__ == "__main__":
+ run(main)
diff --git a/worker.py b/worker.py
new file mode 100644
index 00000000..44b019b3
--- /dev/null
+++ b/worker.py
@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+import io
+import json
+import logging
+import os
+import time
+import uuid
+from datetime import datetime, timedelta, timezone
+
+from PIL import Image, ImageOps
+import redis
+
+from db import Store
+from s3store import ObjectStore, S3Unavailable
+
+LOG = logging.getLogger("attachment-worker")
+STREAM = os.environ.get("BROKER_STREAM", "attachment.jobs")
+GROUP = os.environ.get("BROKER_GROUP", "attachment-workers")
+MAX_ATTEMPTS = int(os.environ.get("JOB_MAX_ATTEMPTS", "5"))
+LEASE_SECONDS = int(os.environ.get("JOB_TIMEOUT_SECONDS", "60"))
+PREFETCH = max(1, min(10, int(os.environ.get("BROKER_PREFETCH", "1"))))
+FAULT = os.environ.get("FAULT_INJECTION", "").strip()
+
+
+def inject_crash(point):
+ if FAULT == point:
+ LOG.error("fault injection crash point=%s", point)
+ os._exit(42)
+
+
+def now():
+ return datetime.now(timezone.utc)
+
+
+def iso(value):
+ return value.isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+
+def broker_url():
+ path = os.environ.get("BROKER_URL_FILE")
+ if path and os.path.isfile(path):
+ return open(path, encoding="utf-8").read().strip()
+ return os.environ.get("BROKER_URL", os.environ.get("CACHE_URL", "redis://redis:6379/0"))
+
+
+def image_bytes(image, format_name, **options):
+ output = io.BytesIO()
+ image.save(output, format=format_name, **options)
+ return output.getvalue()
+
+
+def prepare_variants(raw, attachment_id):
+ with Image.open(io.BytesIO(raw)) as source:
+ image = ImageOps.exif_transpose(source)
+ if image.mode in ("RGBA", "LA") or "transparency" in image.info:
+ background = Image.new("RGB", image.size, "white")
+ alpha = image.convert("RGBA")
+ background.paste(alpha, mask=alpha.getchannel("A"))
+ image = background
+ else:
+ image = image.convert("RGB")
+
+ thumbnail = image.copy()
+ thumbnail.thumbnail((256, 256), Image.Resampling.LANCZOS)
+ crop_size = min(image.size)
+ left = (image.width - crop_size) // 2
+ top = (image.height - crop_size) // 2
+ crop = image.crop((left, top, left + crop_size, top + crop_size))
+ crop = crop.resize((128, 128), Image.Resampling.LANCZOS)
+ optimized = image.copy()
+ optimized.thumbnail((1280, 1280), Image.Resampling.LANCZOS)
+
+ values = [
+ ("thumbnail", thumbnail, "JPEG", "image/jpeg", {"quality": 88, "optimize": True}),
+ ("crop", crop, "JPEG", "image/jpeg", {"quality": 88, "optimize": True}),
+ ("optimized", optimized, "WEBP", "image/webp", {"quality": 86, "method": 4}),
+ ]
+ result = []
+ for name, rendered, fmt, content_type, options in values:
+ data = image_bytes(rendered, fmt, **options)
+ result.append({
+ "name": name,
+ "content_type": content_type,
+ "size_bytes": len(data),
+ "width": rendered.width,
+ "height": rendered.height,
+ "sha256": __import__("hashlib").sha256(data).hexdigest(),
+ "_key": "objects/" + attachment_id + "/" + name,
+ "_data": data,
+ })
+ return result
+
+
+def public_variants(values):
+ return [{key: value for key, value in item.items() if not key.startswith("_")} for item in values]
+
+
+class Worker:
+ def __init__(self):
+ self.store = Store.connect(run_migrations=False)
+ self.objects = ObjectStore.from_env()
+ self.redis = redis.from_url(broker_url(), decode_responses=True, socket_connect_timeout=2)
+ self.consumer = os.environ.get("WORKER_ID", "worker-" + uuid.uuid4().hex[:8])
+ try:
+ self.redis.xgroup_create(STREAM, GROUP, id="0", mkstream=True)
+ except redis.ResponseError as error:
+ if "BUSYGROUP" not in str(error):
+ raise
+
+ def publish_outbox(self):
+ for row in self.store.pending_outbox():
+ fields = {
+ "schema_version": 1,
+ "job_id": str(row["job_id"]),
+ "type": "attachment.process.v1",
+ "attachment_id": str(row["attachment_id"]),
+ "pipeline_version": row["pipeline_version"],
+ "attempt": 1,
+ "created_at": iso(now()),
+ }
+ message_id = self.redis.xadd(STREAM, fields, maxlen=10000, approximate=True)
+ self.store.mark_outbox_published(row["id"], iso(now()))
+ LOG.info("published job=%s message=%s", fields["job_id"], message_id)
+
+ def process(self, message_id, fields):
+ job_id = fields.get("job_id")
+ attachment_id = fields.get("attachment_id")
+ if not job_id or not attachment_id:
+ self.redis.xack(STREAM, GROUP, message_id)
+ return
+ claim = self.store.claim_job(
+ job_id, iso(now() + timedelta(seconds=LEASE_SECONDS)), iso(now())
+ )
+ if claim is None:
+ self.redis.xack(STREAM, GROUP, message_id)
+ return
+ inject_crash("before-side-effect")
+ attachment = self.store.get_attachment_for_job(attachment_id)
+ if not attachment:
+ self.redis.xack(STREAM, GROUP, message_id)
+ return
+ if int(fields.get("pipeline_version", 1)) < int(attachment.get("pipeline_version", 1)):
+ self.redis.xack(STREAM, GROUP, message_id)
+ return
+ try:
+ staged = self.objects.get_object(attachment["staging_key"])
+ if staged is None:
+ raise ValueError("staging_missing")
+ raw = staged["Body"].read()
+ staged["Body"].close()
+ self.objects.put_file(
+ attachment["object_key"], io.BytesIO(raw), len(raw), attachment["content_type"]
+ )
+ inject_crash("after-original")
+ rendered = prepare_variants(raw, attachment_id)
+ for item in rendered:
+ self.objects.put_file(
+ item["_key"], io.BytesIO(item["_data"]), item["size_bytes"], item["content_type"]
+ )
+ inject_crash("after-side-effect")
+ self.store.set_attachment_variants(attachment_id, public_variants(rendered), iso(now()))
+ try:
+ self.objects.delete_object(attachment["staging_key"])
+ except S3Unavailable:
+ LOG.warning("staging cleanup deferred attachment=%s", attachment_id)
+ self.redis.xack(STREAM, GROUP, message_id)
+ except (S3Unavailable, OSError, ValueError, RuntimeError) as error:
+ attempt = claim["attempts"]
+ code = "processing_failed" if not isinstance(error, ValueError) else str(error)
+ if attempt >= MAX_ATTEMPTS:
+ self.store.fail_job(job_id, attachment_id, "retry_exhausted", iso(now()))
+ self.redis.xack(STREAM, GROUP, message_id)
+ else:
+ delay = min(300, 2 ** (attempt - 1)) + (hash(job_id) % 1000) / 1000
+ self.store.retry_job(
+ job_id, attachment_id, iso(now() + timedelta(seconds=delay)), code, iso(now())
+ )
+ self.redis.xack(STREAM, GROUP, message_id)
+ time.sleep(delay)
+ self.redis.xadd(STREAM, fields, maxlen=10000, approximate=True)
+
+ def run(self):
+ while True:
+ self.publish_outbox()
+ pending = self.redis.xautoclaim(
+ STREAM, GROUP, self.consumer, min_idle_time=LEASE_SECONDS * 1000,
+ start_id="0-0", count=PREFETCH
+ )
+ for message_id, fields in pending[1]:
+ self.process(message_id, fields)
+ result = self.redis.xreadgroup(
+ GROUP, self.consumer, {STREAM: ">"}, count=PREFETCH, block=1000
+ )
+ for _, messages in result:
+ for message_id, fields in messages:
+ self.process(message_id, fields)
+
+
+def main():
+ logging.basicConfig(level=os.environ.get("LOG_LEVEL", "INFO"), format="%(asctime)s %(levelname)s %(message)s")
+ worker = Worker()
+ try:
+ worker.run()
+ finally:
+ worker.store.close()
+ worker.objects.client.close()
+
+
+if __name__ == "__main__":
+ main()