ЛР 4 — БПИ2303 — Сарибекян — на 4 #47

Open
Artu-Rito wants to merge 2 commits from Artu-Rito/mtusi2026lab4:solution/БПИ2303-Сарибекян into main
23 changed files with 1605 additions and 16 deletions
+18
View File
@@ -0,0 +1,18 @@
FROM python:3.12.7-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app ./app
COPY migrations ./migrations
RUN useradd --create-home --shell /usr/sbin/nologin appuser
USER appuser
EXPOSE 8080
HEALTHCHECK --interval=5s --timeout=3s --start-period=10s --retries=5 \
CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/live', timeout=2)" || exit 1
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080", "--timeout-graceful-shutdown", "5"]
+70 -16
View File
@@ -1,37 +1,91 @@
# Отчёт — лабораторная 4
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Сарибекян, БПИ2303
- Целевая оценка: 4
- Commit/PR: см. ветку `solution/БПИ2303-Сарибекян`
- Использованные источники, библиотеки и помощь ИИ: база lab3 (FastAPI/asyncpg/redis-py/argon2-cffi/Nginx) плюс `boto3` (S3-клиент) и `Pillow` (проверка изображений). Хранилище — **SeaweedFS** (не MinIO — см. ограничения), S3-совместимый API. Реализация подготовлена с помощью AI-ассистента (Claude Code); проверено локальным запуском `make check/test/test-persistence/test-failover/validate` и серией ручных edge-case тестов.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Версии: Python 3.12.7, PostgreSQL 16.4, Redis 7.4.1, Nginx 1.27.2, SeaweedFS 3.73.
```sh
git clone <ваш форк>
cd mtusi2026lab4
mkdir -p secrets
openssl rand -hex 20 > secrets/postgres_password.txt
printf 'postgresql://messenger:%s@postgres:5432/messenger' "$(cat secrets/postgres_password.txt)" > secrets/database_url.txt
printf 'redis://redis:6379/0' > secrets/cache_url.txt
printf 'messenger-api' > secrets/s3_access_key_id.txt
openssl rand -hex 20 > secrets/s3_secret_access_key.txt
AK=$(cat secrets/s3_access_key_id.txt); SK=$(cat secrets/s3_secret_access_key.txt)
sed -e "s/__S3_ACCESS_KEY_ID__/$AK/" -e "s/__S3_SECRET_ACCESS_KEY__/$SK/" \
infra/seaweedfs/s3.json.template > secrets/s3.json
chmod 600 secrets/*.txt secrets/s3.json
printf 'SESSION_TTL_SECONDS=3600\nMAX_UPLOAD_BYTES=10485760\nMAX_IMAGE_PIXELS=40000000\n' > .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl -s localhost:8080/health/ready
make test
chmod +x scripts/restart.sh scripts/stop-one.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# после отказа одной реплики: docker compose start api1 (или api2), повторить для второй.
```
Остановка: `docker compose stop`. Намеренное удаление данных: `docker compose down -v`.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```
Клиент → lb (Nginx) → api1 / api2 → PostgreSQL (метаданные) + Redis (сессии) + SeaweedFS S3 (байты, приватный bucket)
```
- **Почему SeaweedFS, а не MinIO**: официальные образы `minio/minio` больше не тянутся публично ни с Docker Hub, ни с Quay.io (`401/403` на pull) — MinIO изменил политику распространения community-образов. SeaweedFS (`chrislusf/seaweedfs:3.73`, закреплённый тег) доступен свободно и был указан как разрешённая альтернатива в README.
- **S3 bucket**: `messenger-attachments`. API использует **не root**, а отдельную identity `messenger-api`, заданную в `infra/seaweedfs/s3.json.template` (реальные ключи — в гитигнорированном `secrets/s3.json`), с правами ровно `Read/Write/List` на этот один bucket. Админ-консоли/порта управления SeaweedFS наружу не публикуется.
- **Bucket bootstrap идемпотентен без прав администратора**: т.к. у `messenger-api` нет права `CreateBucket`, bootstrap (`storage.ensure_bucket()`) просто пишет маркерный объект `.bootstrap` — SeaweedFS (как и S3) автосоздаёт bucket при первом успешном `PutObject`. Повторные запуски — не ошибка (перезапись того же объекта).
- **Схема**: `attachments(id, chat_id, owner_id, filename, content_type, size_bytes, sha256, status, error_code, s3_key, created_at, updated_at)` + `message_attachments(message_id, attachment_id)` (migrations `0003_attachments.sql`). `s3_key` генерируется сервером (`attachments/<uuid>`), `filename` — только отображаемое имя, никогда не используется как путь.
- **Валидация изображения по содержимому** (`app/images.py`): реальный формат (`Pillow` `Image.open().format`) сравнивается с заявленным `Content-Type`; пиксельный бюджет (40 млн) проверяется **до** `img.load()` (защита от decompression bomb); файл читается потоково с проверкой байтового лимита (10 MiB) **во время** чтения тела запроса, не после.
- **Синхронный upload**: `201 Attachment{status:"ready"}` возвращается только после того, как байты реально в S3 **и** транзакция метаданных закоммичена в Postgres (в этом порядке — см. раздел про orphan-объекты).
- **Идемпотентность с вложениями**: хэш для `Idempotency-Key` теперь включает `sorted(attachment_ids)`, не только `text`.
- **Совместимость с lab3**: текстовые `POST` без вложений остаются валидны; `message_attachments` — отдельная таблица, не меняющая существующие колонки `messages`.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Публичный smoke | `make test` | `PASS: lab4 public API scenario...` | вывод команды |
| Персистентность | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS` | вывод команды |
| Upload→стоп реплики→download через другую | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, дважды (по разу на реплику) | `successful_writes:97/97, failed_attempts:0`, встроенная в тест проверка SHA-256 после отказа — без ошибок | вывод команды |
| ≤10 MiB / ≤40 млн пикселей | upload 11 МБ файла | `413 payload_too_large` (после фикса Nginx — см. ограничения) | `evidence/attachment_edge_cases.txt` |
| MIME по содержимому | настоящий JPEG, заявлен как `image/png` | `415 unsupported_media_type: declared content type does not match actual image format` | `evidence/attachment_edge_cases.txt` |
| Битое изображение | произвольные байты с `Content-Type: image/png` | `415 unsupported_media_type` | `evidence/attachment_edge_cases.txt` |
| Чужой `attachment_id` | вложение из chat A в сообщение chat B | `404 not_found` | `evidence/attachment_edge_cases.txt` |
| Приватный bucket вне API | прямой `curl` с хоста на `seaweedfs:8333` | порт не опубликован → `connection refused` (curl exit 7) | `evidence/attachment_edge_cases.txt` |
| ≥10 конкурентных загрузок, память | 15 параллельных upload | все `201`; `api1` 73.4→75.2 MiB, `api2` 69.6→68.9 MiB (лимит 256 MiB) | `evidence/attachment_edge_cases.txt` |
| Orphan-компенсация | `scripts/reconcile_attachments.py` на искусственно созданном orphan-объекте | найден, затем удалён `--delete`; реальные вложения не тронуты | `evidence/reconcile_demo.txt` |
| Отдельные S3-credentials с ограниченными правами | `infra/seaweedfs/s3.json.template`: identity только `Read/Write/List` на один bucket | код/конфиг-ревью | `infra/seaweedfs/s3.json.template` |
| `make validate` | `make validate PYTHON=.venv/bin/python` | `PASS: full OpenAPI 3.1...` | вывод команды |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Остановка `api1` во время upload/download цикла | Чтение/запись продолжаются, SHA-256 совпадает после переключения на `api2` | `successful_writes=97, failed_attempts=0, first_recovery_seconds=1.155` | восстановление 1.16с, потерь нет |
| Остановка `api2` (вторая реплика) | То же | `successful_writes=97, failed_attempts=0, first_recovery_seconds=0.884` | восстановление 0.88с, потерь нет |
| `docker compose restart postgres redis seaweedfs api1 api2 lb` (последовательно, с ожиданием healthy) | Вложения и сообщения сохраняются | `PASS` в `make test-persistence` | восстановление <90с, без потерь |
| 15 параллельных upload одного файла (~112 KB) | Нет деградации/ошибок | все `201`, рост RSS на несколько МБ, в пределах лимита 256 MiB | — |
| Искусственный orphan-объект в S3 (без строки в БД) | Обнаруживается сверкой, не трогает реальные вложения | найден `scripts/reconcile_attachments.py --grace-minutes 0`, удалён с `--delete` | — |
**Ограничение:** нагрузочный тест на реальных конкурентных upload >15 и трек исследования уровня 5 (presigned URL / полноценный reconciler с внедрением ошибок на обеих сторонах) не выполнялись — цель лабы — оценка 4.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- **MinIO недоступен публично** (см. архитектуру) — заменён на SeaweedFS; если преподаватель ожидает конкретно MinIO, нужно либо получить доступ к их registry, либо принять эту замену как равноценную (README явно разрешает выбор одного из трёх).
- Найден и исправлен баг: **Nginx перехватывал превышение размера раньше приложения** и отдавал свою HTML-страницу `413` вместо контрактного JSON-конверта. Исправлено: `client_max_body_size` в Nginx поднят чуть выше (11 MiB) собственного лимита приложения (10 MiB), так что именно приложение формирует финальный ответ.
- Найден и исправлен баг **гонки при restart**: `scripts/restart.sh` не ждал реальной готовности (healthcheck) зависимостей между стадиями перезапуска — API падал на старте, не успев подключиться к ещё не готовому SeaweedFS/Postgres/Redis. Добавлено явное ожидание `healthy`-статуса между этапами.
- Healthcheck SeaweedFS не может быть обычным HTTP-GET на S3-порт (анонимный запрос получает `403`, что ломает любой healthcheck на основе кода ответа) — используется проверка открытости TCP-порта (`nc -z`).
- Трек исследования уровня 5 не реализован.
- `scripts/reconcile_attachments.py` — рабочий, но простой инструмент (полный скан bucket через `list_objects_v2`); для production-масштаба нужна инкрементальная сверка (например, по журналу событий), не полный обход при каждом запуске.
View File
+82
View File
@@ -0,0 +1,82 @@
"""PostgreSQL connection pool and versioned migration runner."""
import logging
from pathlib import Path
import asyncpg
logger = logging.getLogger("app.db")
MIGRATIONS_DIR = Path(__file__).resolve().parent.parent / "migrations"
_pool: asyncpg.Pool | None = None
async def init_pool(dsn: str) -> asyncpg.Pool:
global _pool
_pool = await asyncpg.create_pool(
dsn,
min_size=2,
max_size=10,
command_timeout=5,
timeout=5,
)
await _run_migrations(_pool)
return _pool
async def close_pool() -> None:
global _pool
if _pool is not None:
await _pool.close()
_pool = None
def pool() -> asyncpg.Pool:
if _pool is None:
raise RuntimeError("database pool is not initialized")
return _pool
MIGRATION_LOCK_KEY = 783451 # arbitrary advisory-lock id, serializes concurrent replicas
async def _run_migrations(p: asyncpg.Pool) -> None:
async with p.acquire() as conn:
# Multiple API replicas start together; an advisory lock keeps migrations
# from racing each other instead of letting all replicas apply SQL at once.
await conn.execute("SELECT pg_advisory_lock($1)", MIGRATION_LOCK_KEY)
try:
await _apply_migrations(conn)
finally:
await conn.execute("SELECT pg_advisory_unlock($1)", MIGRATION_LOCK_KEY)
async def _apply_migrations(conn: asyncpg.Connection) -> None:
await conn.execute(
"""
CREATE TABLE IF NOT EXISTS schema_migrations (
version TEXT PRIMARY KEY,
applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
)
"""
)
applied = {r["version"] for r in await conn.fetch("SELECT version FROM schema_migrations")}
for path in sorted(MIGRATIONS_DIR.glob("*.sql")):
if path.name in applied:
continue
sql = path.read_text(encoding="utf-8")
async with conn.transaction():
await conn.execute(sql)
await conn.execute(
"INSERT INTO schema_migrations (version) VALUES ($1)", path.name
)
logger.info("applied migration %s", path.name)
async def ping() -> bool:
try:
async with pool().acquire() as conn:
await conn.fetchval("SELECT 1")
return True
except Exception: # noqa: BLE001 - readiness probe, any failure means not ready
return False
+37
View File
@@ -0,0 +1,37 @@
"""Canonical error envelope: {"error": {"code", "message", "request_id"}}."""
class ApiError(Exception):
def __init__(self, status: int, code: str, message: str):
self.status = status
self.code = code
self.message = message
super().__init__(message)
def bad_request(message: str) -> ApiError:
return ApiError(400, "invalid_request", message)
def unauthorized(message: str = "authentication required") -> ApiError:
return ApiError(401, "unauthorized", message)
def not_found(message: str = "not found") -> ApiError:
return ApiError(404, "not_found", message)
def conflict(message: str) -> ApiError:
return ApiError(409, "conflict", message)
def unavailable(message: str = "dependency unavailable") -> ApiError:
return ApiError(503, "unavailable", message)
def payload_too_large(message: str) -> ApiError:
return ApiError(413, "payload_too_large", message)
def unsupported_media_type(message: str) -> ApiError:
return ApiError(415, "unsupported_media_type", message)
+89
View File
@@ -0,0 +1,89 @@
"""Shared (cross-replica) idempotency for POST message, scoped to (user, method, path, key)."""
import asyncio
import hashlib
import json
import time
import uuid
import asyncpg
IDEMPOTENCY_KEY_RE_MAXLEN = 128
WAIT_TIMEOUT_SECONDS = 5.0
POLL_INTERVAL_SECONDS = 0.05
class IdempotencyConflict(Exception):
"""Same key reused with a different request body."""
def request_hash(body: dict) -> str:
canonical = json.dumps(body, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
async def run_once(
conn: asyncpg.Connection,
user_id: uuid.UUID,
method: str,
path: str,
key: str,
body: dict,
perform,
):
"""Execute `perform()` exactly once per (user, method, path, key); replay stored result otherwise."""
digest = request_hash(body)
inserted = await conn.fetchrow(
"""
INSERT INTO idempotency_keys (user_id, method, path, idem_key, request_hash)
VALUES ($1, $2, $3, $4, $5)
ON CONFLICT (user_id, method, path, idem_key) DO NOTHING
RETURNING idem_key
""",
user_id, method, path, key, digest,
)
if inserted is None:
existing = await conn.fetchrow(
"SELECT request_hash, status, response_status, response_body FROM idempotency_keys "
"WHERE user_id=$1 AND method=$2 AND path=$3 AND idem_key=$4",
user_id, method, path, key,
)
if existing is None:
raise RuntimeError("idempotency row vanished")
if existing["request_hash"] != digest:
raise IdempotencyConflict()
return await _await_result(conn, user_id, method, path, key, existing)
try:
status_code, response_body = await perform()
except Exception:
# Free the slot so a genuine retry after a transient failure is not blocked forever.
await conn.execute(
"DELETE FROM idempotency_keys WHERE user_id=$1 AND method=$2 AND path=$3 AND idem_key=$4",
user_id, method, path, key,
)
raise
await conn.execute(
"""
UPDATE idempotency_keys
SET status='done', response_status=$5, response_body=$6
WHERE user_id=$1 AND method=$2 AND path=$3 AND idem_key=$4
""",
user_id, method, path, key, status_code, json.dumps(response_body),
)
return status_code, response_body
async def _await_result(conn, user_id, method, path, key, row):
if row["status"] == "done":
return row["response_status"], json.loads(row["response_body"])
deadline = time.monotonic() + WAIT_TIMEOUT_SECONDS
while time.monotonic() < deadline:
await asyncio.sleep(POLL_INTERVAL_SECONDS)
current = await conn.fetchrow(
"SELECT status, response_status, response_body FROM idempotency_keys "
"WHERE user_id=$1 AND method=$2 AND path=$3 AND idem_key=$4",
user_id, method, path, key,
)
if current and current["status"] == "done":
return current["response_status"], json.loads(current["response_body"])
raise TimeoutError("concurrent idempotent request did not finish in time")
+36
View File
@@ -0,0 +1,36 @@
"""Server-side image validation: real format by content, not by the client's claim."""
import io
from PIL import Image, UnidentifiedImageError
from PIL.Image import DecompressionBombError
CONTENT_TYPE_TO_PIL_FORMAT = {"image/png": "PNG", "image/jpeg": "JPEG"}
class InvalidImage(Exception):
pass
class ImageTooLarge(InvalidImage):
pass
def validate(data: bytes, declared_content_type: str, max_pixels: int) -> None:
"""Raise InvalidImage if the bytes are not a genuine, within-budget PNG/JPEG."""
expected_format = CONTENT_TYPE_TO_PIL_FORMAT.get(declared_content_type)
if expected_format is None:
raise InvalidImage("unsupported content type")
try:
with Image.open(io.BytesIO(data)) as img:
# Image.open() only parses the header; check the pixel budget
# BEFORE calling .load(), which is what actually decodes pixels.
if img.format != expected_format:
raise InvalidImage("declared content type does not match actual image format")
width, height = img.size
if width * height > max_pixels:
raise ImageTooLarge("image exceeds the decoded pixel budget")
img.load() # forces full decode; raises on truncated/corrupted data
except DecompressionBombError as exc:
raise ImageTooLarge("image exceeds the decoded pixel budget") from exc
except (UnidentifiedImageError, OSError, ValueError) as exc:
raise InvalidImage(str(exc)) from exc
+693
View File
@@ -0,0 +1,693 @@
"""Messenger API — lab 2: PostgreSQL persistence + Redis/Valkey sessions."""
import base64
import binascii
import json
import os
import re
import socket
import uuid
from datetime import datetime, timezone
import asyncpg
from fastapi import FastAPI, Header, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse, Response
from pydantic import BaseModel, ConfigDict, Field, ValidationError
import hashlib
import os
from . import db, sessions, storage, images
from . import idempotency
from .errors import (
ApiError, bad_request, conflict, not_found, payload_too_large,
unauthorized, unavailable, unsupported_media_type,
)
from .security import hash_password, verify_password
USERNAME_RE = re.compile(r"^[a-z0-9_]{3,32}$")
IDEMPOTENCY_KEY_RE = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
FILENAME_FORBIDDEN_RE = re.compile(r"[/\\\x00-\x1f\x7f]")
MAX_UPLOAD_BYTES = int(os.environ.get("MAX_UPLOAD_BYTES", "10485760"))
MAX_IMAGE_PIXELS = int(os.environ.get("MAX_IMAGE_PIXELS", "40000000"))
INSTANCE_ID = os.environ.get("INSTANCE_ID") or f"{socket.gethostname()}-{os.getpid()}"
app = FastAPI(title="MTUSI Messenger — lab 2")
# ---------------------------------------------------------------------------
# Request/response plumbing: request id, instance id, canonical error shape.
# ---------------------------------------------------------------------------
@app.middleware("http")
async def tagging_middleware(request: Request, call_next):
request_id = uuid.uuid4().hex
request.state.request_id = request_id
try:
response = await call_next(request)
except ApiError as exc:
response = _error_response(exc, request_id)
except Exception: # noqa: BLE001 - never leak internals
response = _error_response(ApiError(500, "internal_error", "internal error"), request_id)
response.headers["X-Request-Id"] = request_id
response.headers["X-Instance-Id"] = INSTANCE_ID
return response
def _error_response(exc: ApiError, request_id: str) -> JSONResponse:
headers = {}
if exc.status == 401:
path = "/api/v1/auth/sessions"
scheme = 'Basic realm="messenger", charset="UTF-8"' if _is_login_path(exc) else 'Bearer realm="messenger"'
headers["WWW-Authenticate"] = scheme
return JSONResponse(
status_code=exc.status,
content={"error": {"code": exc.code, "message": exc.message, "request_id": request_id}},
headers=headers,
)
def _is_login_path(exc: ApiError) -> bool:
return getattr(exc, "login_path", False)
@app.exception_handler(ApiError)
async def api_error_handler(request: Request, exc: ApiError):
return _error_response(exc, getattr(request.state, "request_id", uuid.uuid4().hex))
@app.exception_handler(RequestValidationError)
async def request_validation_error_handler(request: Request, exc: RequestValidationError):
return _error_response(
bad_request("invalid request parameters"),
getattr(request.state, "request_id", uuid.uuid4().hex),
)
def iso(value: datetime) -> str:
return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
def user_json(record) -> dict:
return {
"id": str(record["id"]),
"username": record["username"],
"display_name": record["display_name"],
"created_at": iso(record["created_at"]),
}
def chat_json(record, member_ids: list[uuid.UUID]) -> dict:
return {
"id": str(record["id"]),
"title": record["title"],
"member_ids": [str(m) for m in member_ids],
"created_at": iso(record["created_at"]),
}
def message_json(record, attachment_ids: list[uuid.UUID]) -> dict:
return {
"id": str(record["id"]),
"chat_id": str(record["chat_id"]),
"sender_id": str(record["sender_id"]),
"text": record["text"],
"attachment_ids": [str(a) for a in attachment_ids],
"created_at": iso(record["created_at"]),
}
def attachment_json(record) -> dict:
return {
"id": str(record["id"]),
"chat_id": str(record["chat_id"]),
"owner_id": str(record["owner_id"]),
"filename": record["filename"],
"content_type": record["content_type"],
"size_bytes": record["size_bytes"],
"sha256": record["sha256"],
"status": record["status"],
"variants": [],
"error_code": record["error_code"],
"created_at": iso(record["created_at"]),
"updated_at": iso(record["updated_at"]),
}
# ---------------------------------------------------------------------------
# Cursors: opaque base64url(json) of the keyset tuple, scoped per resource.
# ---------------------------------------------------------------------------
def encode_cursor(payload: dict) -> str:
raw = json.dumps(payload, separators=(",", ":")).encode()
return base64.urlsafe_b64encode(raw).decode().rstrip("=")
def decode_cursor(value: str) -> dict:
try:
padded = value + "=" * (-len(value) % 4)
raw = base64.urlsafe_b64decode(padded.encode())
payload = json.loads(raw)
if not isinstance(payload, dict):
raise bad_request("malformed cursor")
return payload
except (binascii.Error, ValueError, UnicodeDecodeError):
raise bad_request("malformed cursor")
# ---------------------------------------------------------------------------
# Auth: Basic only on POST /auth/sessions, Bearer everywhere else protected.
# ---------------------------------------------------------------------------
async def require_bearer(authorization: str | None) -> asyncpg.Record:
if not authorization or not authorization.startswith("Bearer "):
raise unauthorized()
token = authorization[len("Bearer "):].strip()
if not token:
raise unauthorized()
try:
user_id = await sessions.resolve(token)
except Exception: # noqa: BLE001 - dependency failure must not grant access
raise unavailable("session store unavailable")
if user_id is None:
raise unauthorized()
async with db.pool().acquire() as conn:
record = await conn.fetchrow("SELECT * FROM users WHERE id=$1", user_id)
if record is None:
raise unauthorized()
return record
def parse_basic(authorization: str | None) -> tuple[str, str]:
err = ApiError(401, "unauthorized", "Basic credentials required")
err.login_path = True
if not authorization or not authorization.startswith("Basic "):
raise err
try:
decoded = base64.b64decode(authorization[len("Basic "):].strip()).decode("utf-8")
except (binascii.Error, UnicodeDecodeError):
raise err
if ":" not in decoded:
raise err
username, password = decoded.split(":", 1)
return username, password
# ---------------------------------------------------------------------------
# Request bodies (additionalProperties: false in the contract -> extra="forbid").
# ---------------------------------------------------------------------------
class CreateUser(BaseModel):
model_config = ConfigDict(extra="forbid")
username: str
display_name: str = Field(min_length=1, max_length=100)
password: str = Field(min_length=12, max_length=128)
class CreateChat(BaseModel):
model_config = ConfigDict(extra="forbid")
title: str = Field(min_length=1, max_length=100)
member_ids: list[str] = Field(min_length=1, max_length=100)
class CreateMessage(BaseModel):
model_config = ConfigDict(extra="forbid")
text: str = Field(max_length=4000) # required key, "" allowed if attachments are present
attachment_ids: list[str] = Field(default_factory=list, max_length=10)
async def parse_body(request: Request, model):
try:
raw = await request.json()
except json.JSONDecodeError:
raise bad_request("malformed JSON")
try:
return model.model_validate(raw)
except ValidationError as exc:
raise bad_request(str(exc.errors()[0]["msg"]) if exc.errors() else "invalid body")
# ---------------------------------------------------------------------------
# Health
# ---------------------------------------------------------------------------
@app.get("/health/live")
async def health_live():
return {"status": "ok"}
@app.get("/health/ready")
async def health_ready():
if await db.ping() and await sessions.ping() and await storage.ping():
return {"status": "ok"}
raise unavailable("database, session store or object storage not ready")
# ---------------------------------------------------------------------------
# Users
# ---------------------------------------------------------------------------
@app.post("/api/v1/users", status_code=201)
async def register_user(request: Request):
body = await parse_body(request, CreateUser)
if not USERNAME_RE.fullmatch(body.username):
raise bad_request("username must match ^[a-z0-9_]{3,32}$")
if not body.display_name.strip():
raise bad_request("display_name must not be blank")
password_hash = hash_password(body.password)
try:
async with db.pool().acquire() as conn:
record = await conn.fetchrow(
"""
INSERT INTO users (username, display_name, password_hash)
VALUES ($1, $2, $3)
RETURNING id, username, display_name, created_at
""",
body.username,
body.display_name,
password_hash,
)
except asyncpg.UniqueViolationError:
raise conflict("username already taken")
return JSONResponse(status_code=201, content=user_json(record))
@app.get("/api/v1/users/me")
async def current_user(authorization: str | None = Header(default=None)):
record = await require_bearer(authorization)
return user_json(record)
# ---------------------------------------------------------------------------
# Sessions
# ---------------------------------------------------------------------------
@app.post("/api/v1/auth/sessions", status_code=201)
async def create_session(authorization: str | None = Header(default=None)):
username, password = parse_basic(authorization)
async with db.pool().acquire() as conn:
record = await conn.fetchrow("SELECT * FROM users WHERE username=$1", username)
err = ApiError(401, "unauthorized", "invalid credentials")
err.login_path = True
if record is None or not verify_password(password, record["password_hash"]):
raise err
try:
token, expires_at = await sessions.create(record["id"])
except Exception: # noqa: BLE001
raise unavailable("session store unavailable")
return JSONResponse(
status_code=201,
content={
"token": token,
"token_type": "Bearer",
"expires_at": iso(expires_at),
"user": user_json(record),
},
)
@app.delete("/api/v1/auth/sessions/current", status_code=204)
async def revoke_session(authorization: str | None = Header(default=None)):
await require_bearer(authorization) # validates the token is currently live
token = authorization[len("Bearer "):].strip()
try:
await sessions.revoke(token)
except Exception: # noqa: BLE001
raise unavailable("session store unavailable")
return Response(status_code=204)
# ---------------------------------------------------------------------------
# Chats
# ---------------------------------------------------------------------------
@app.post("/api/v1/chats", status_code=201)
async def create_chat(request: Request, authorization: str | None = Header(default=None)):
actor = await require_bearer(authorization)
body = await parse_body(request, CreateChat)
try:
member_ids = [uuid.UUID(m) for m in body.member_ids]
except ValueError:
raise bad_request("member_ids must be UUIDs")
if len(set(member_ids)) != len(member_ids):
raise bad_request("member_ids must not contain duplicates")
if actor["id"] not in member_ids:
raise bad_request("caller must be a member of the chat")
async with db.pool().acquire() as conn:
async with conn.transaction():
existing = await conn.fetch(
"SELECT id FROM users WHERE id = ANY($1::uuid[])", member_ids
)
if len(existing) != len(member_ids):
raise bad_request("unknown member in member_ids")
chat = await conn.fetchrow(
"INSERT INTO chats (title) VALUES ($1) RETURNING id, title, created_at",
body.title,
)
await conn.executemany(
"INSERT INTO chat_members (chat_id, user_id) VALUES ($1, $2)",
[(chat["id"], m) for m in member_ids],
)
return JSONResponse(status_code=201, content=chat_json(chat, member_ids))
@app.get("/api/v1/chats")
async def list_chats(
authorization: str | None = Header(default=None),
limit: int = 50,
cursor: str | None = None,
):
actor = await require_bearer(authorization)
if not (1 <= limit <= 100):
raise bad_request("limit must be between 1 and 100")
after_created_at = after_id = None
if cursor:
payload = decode_cursor(cursor)
try:
after_created_at = datetime.fromisoformat(payload["created_at"])
after_id = uuid.UUID(payload["id"])
except (KeyError, ValueError):
raise bad_request("malformed cursor")
async with db.pool().acquire() as conn:
rows = await conn.fetch(
"""
SELECT c.id, c.title, c.created_at
FROM chats c
JOIN chat_members cm ON cm.chat_id = c.id
WHERE cm.user_id = $1
AND ($2::timestamptz IS NULL OR (c.created_at, c.id) > ($2, $3))
ORDER BY c.created_at ASC, c.id ASC
LIMIT $4
""",
actor["id"],
after_created_at,
after_id,
limit + 1,
)
has_more = len(rows) > limit
rows = rows[:limit]
items = []
for row in rows:
members = await conn.fetch("SELECT user_id FROM chat_members WHERE chat_id=$1", row["id"])
items.append(chat_json(row, [m["user_id"] for m in members]))
next_cursor = None
if has_more:
last = rows[-1]
next_cursor = encode_cursor({"created_at": iso(last["created_at"]), "id": str(last["id"])})
return {"items": items, "next_cursor": next_cursor}
async def _load_chat_if_member(conn, chat_id: uuid.UUID, user_id: uuid.UUID):
chat = await conn.fetchrow("SELECT id, title, created_at FROM chats WHERE id=$1", chat_id)
if chat is None:
raise not_found("chat not found")
membership = await conn.fetchrow(
"SELECT 1 FROM chat_members WHERE chat_id=$1 AND user_id=$2", chat_id, user_id
)
if membership is None:
raise not_found("chat not found")
return chat
@app.get("/api/v1/chats/{chat_id}")
async def get_chat(chat_id: str, authorization: str | None = Header(default=None)):
actor = await require_bearer(authorization)
try:
chat_uuid = uuid.UUID(chat_id)
except ValueError:
raise bad_request("chat_id must be a UUID")
async with db.pool().acquire() as conn:
chat = await _load_chat_if_member(conn, chat_uuid, actor["id"])
members = await conn.fetch("SELECT user_id FROM chat_members WHERE chat_id=$1", chat_uuid)
return chat_json(chat, [m["user_id"] for m in members])
# ---------------------------------------------------------------------------
# Messages
# ---------------------------------------------------------------------------
@app.post("/api/v1/chats/{chat_id}/messages", status_code=201)
async def create_message(
chat_id: str,
request: Request,
authorization: str | None = Header(default=None),
idempotency_key: str | None = Header(default=None, alias="Idempotency-Key"),
):
# Session/access are re-checked on every call, including idempotent replays.
actor = await require_bearer(authorization)
try:
chat_uuid = uuid.UUID(chat_id)
except ValueError:
raise bad_request("chat_id must be a UUID")
if not idempotency_key or not IDEMPOTENCY_KEY_RE.match(idempotency_key):
raise bad_request("Idempotency-Key header is required and must match ^[A-Za-z0-9._:-]{1,128}$")
body = await parse_body(request, CreateMessage)
try:
attachment_uuids = [uuid.UUID(a) for a in body.attachment_ids]
except ValueError:
raise bad_request("attachment_ids must be UUIDs")
if len(set(attachment_uuids)) != len(attachment_uuids):
raise bad_request("attachment_ids must not contain duplicates")
if not body.text.strip() and not attachment_uuids:
raise bad_request("text must not be blank unless attachments are present")
async def perform():
record = await conn.fetchrow(
"""
INSERT INTO messages (chat_id, sender_id, text)
VALUES ($1, $2, $3)
RETURNING id, chat_id, sender_id, text, created_at
""",
chat_uuid,
actor["id"],
body.text,
)
if attachment_uuids:
owned = await conn.fetch(
"SELECT id FROM attachments WHERE chat_id=$1 AND id = ANY($2::uuid[]) AND status='ready'",
chat_uuid, attachment_uuids,
)
if len(owned) != len(attachment_uuids):
raise not_found("one or more attachment_ids are not available in this chat")
await conn.executemany(
"INSERT INTO message_attachments (message_id, attachment_id) VALUES ($1, $2)",
[(record["id"], a) for a in attachment_uuids],
)
return 201, message_json(record, attachment_uuids)
async with db.pool().acquire() as conn:
await _load_chat_if_member(conn, chat_uuid, actor["id"])
async with conn.transaction():
try:
status_code, payload = await idempotency.run_once(
conn,
actor["id"],
"POST",
request.url.path,
idempotency_key,
{"text": body.text, "attachment_ids": sorted(body.attachment_ids)},
perform,
)
except idempotency.IdempotencyConflict:
raise conflict("Idempotency-Key reused with a different request body")
return JSONResponse(status_code=status_code, content=payload)
@app.get("/api/v1/chats/{chat_id}/messages")
async def list_messages(
chat_id: str,
authorization: str | None = Header(default=None),
limit: int = 50,
cursor: str | None = None,
):
actor = await require_bearer(authorization)
try:
chat_uuid = uuid.UUID(chat_id)
except ValueError:
raise bad_request("chat_id must be a UUID")
if not (1 <= limit <= 100):
raise bad_request("limit must be between 1 and 100")
after_created_at = after_id = None
if cursor:
payload = decode_cursor(cursor)
if payload.get("chat_id") != chat_id:
raise bad_request("cursor does not belong to this chat")
try:
after_created_at = datetime.fromisoformat(payload["created_at"])
after_id = uuid.UUID(payload["id"])
except (KeyError, ValueError):
raise bad_request("malformed cursor")
async with db.pool().acquire() as conn:
await _load_chat_if_member(conn, chat_uuid, actor["id"])
rows = await conn.fetch(
"""
SELECT id, chat_id, sender_id, text, created_at
FROM messages
WHERE chat_id = $1
AND ($2::timestamptz IS NULL OR (created_at, id) > ($2, $3))
ORDER BY created_at ASC, id ASC
LIMIT $4
""",
chat_uuid,
after_created_at,
after_id,
limit + 1,
)
has_more = len(rows) > limit
rows = rows[:limit]
items = []
for r in rows:
attached = await conn.fetch(
"SELECT attachment_id FROM message_attachments WHERE message_id=$1", r["id"]
)
items.append(message_json(r, [a["attachment_id"] for a in attached]))
next_cursor = None
if has_more:
last = rows[-1]
next_cursor = encode_cursor(
{"chat_id": chat_id, "created_at": iso(last["created_at"]), "id": str(last["id"])}
)
return {"items": items, "next_cursor": next_cursor}
# ---------------------------------------------------------------------------
# Attachments
# ---------------------------------------------------------------------------
@app.post("/api/v1/chats/{chat_id}/attachments", status_code=201)
async def upload_attachment(
chat_id: str,
request: Request,
filename: str,
authorization: str | None = Header(default=None),
):
actor = await require_bearer(authorization)
try:
chat_uuid = uuid.UUID(chat_id)
except ValueError:
raise bad_request("chat_id must be a UUID")
if not (1 <= len(filename) <= 255) or FILENAME_FORBIDDEN_RE.search(filename):
raise bad_request("filename must be 1-255 characters with no path separators or control characters")
content_type = request.headers.get("content-type", "")
if content_type not in ("image/png", "image/jpeg"):
raise unsupported_media_type("only image/png and image/jpeg are accepted")
# Enforce the byte budget BEFORE reading an unbounded body into memory.
data = bytearray()
async for chunk in request.stream():
data.extend(chunk)
if len(data) > MAX_UPLOAD_BYTES:
raise payload_too_large(f"upload exceeds {MAX_UPLOAD_BYTES} bytes")
data = bytes(data)
if not data:
raise bad_request("empty upload body")
try:
images.validate(data, content_type, MAX_IMAGE_PIXELS)
except images.ImageTooLarge as exc:
raise payload_too_large(str(exc))
except images.InvalidImage as exc:
raise unsupported_media_type(str(exc))
digest = hashlib.sha256(data).hexdigest()
object_key = storage.new_object_key()
async with db.pool().acquire() as conn:
await _load_chat_if_member(conn, chat_uuid, actor["id"])
try:
await storage.put_object(object_key, data, content_type)
except Exception: # noqa: BLE001
raise unavailable("object storage unavailable")
record = await conn.fetchrow(
"""
INSERT INTO attachments (chat_id, owner_id, filename, content_type, size_bytes, sha256, status, s3_key)
VALUES ($1, $2, $3, $4, $5, $6, 'ready', $7)
RETURNING id, chat_id, owner_id, filename, content_type, size_bytes, sha256, status, error_code, created_at, updated_at
""",
chat_uuid, actor["id"], filename, content_type, len(data), digest, object_key,
)
return JSONResponse(status_code=201, content=attachment_json(record))
async def _load_attachment_if_member(conn, attachment_id: uuid.UUID, user_id: uuid.UUID):
record = await conn.fetchrow(
"""
SELECT a.* FROM attachments a
JOIN chat_members cm ON cm.chat_id = a.chat_id
WHERE a.id = $1 AND cm.user_id = $2
""",
attachment_id, user_id,
)
if record is None:
raise not_found("attachment not found")
return record
@app.get("/api/v1/attachments/{attachment_id}")
async def get_attachment(attachment_id: str, authorization: str | None = Header(default=None)):
actor = await require_bearer(authorization)
try:
att_uuid = uuid.UUID(attachment_id)
except ValueError:
raise bad_request("attachment_id must be a UUID")
async with db.pool().acquire() as conn:
record = await _load_attachment_if_member(conn, att_uuid, actor["id"])
return attachment_json(record)
@app.get("/api/v1/attachments/{attachment_id}/content")
async def get_attachment_content(
attachment_id: str,
authorization: str | None = Header(default=None),
variant: str = "original",
):
actor = await require_bearer(authorization)
try:
att_uuid = uuid.UUID(attachment_id)
except ValueError:
raise bad_request("attachment_id must be a UUID")
if variant != "original":
raise bad_request("only variant=original is available in lab4")
async with db.pool().acquire() as conn:
record = await _load_attachment_if_member(conn, att_uuid, actor["id"])
try:
data = await storage.get_object(record["s3_key"])
except Exception: # noqa: BLE001
raise unavailable("object storage unavailable")
return Response(content=data, media_type=record["content_type"])
# ---------------------------------------------------------------------------
# Lifecycle
# ---------------------------------------------------------------------------
@app.on_event("startup")
async def on_startup():
database_url = _read_secret("DATABASE_URL_FILE", "DATABASE_URL")
cache_url = _read_secret("CACHE_URL_FILE", "CACHE_URL")
await db.init_pool(database_url)
sessions.init(cache_url)
storage.init(
endpoint=os.environ["S3_ENDPOINT"],
region=os.environ.get("S3_REGION", "us-east-1"),
access_key=_read_secret("S3_ACCESS_KEY_ID_FILE", "S3_ACCESS_KEY_ID"),
secret_key=_read_secret("S3_SECRET_ACCESS_KEY_FILE", "S3_SECRET_ACCESS_KEY"),
bucket=os.environ.get("S3_BUCKET", "messenger-attachments"),
)
await storage.ensure_bucket()
@app.on_event("shutdown")
async def on_shutdown():
await db.close_pool()
await sessions.close()
def _read_secret(file_env: str, inline_env: str) -> str:
path = os.environ.get(file_env)
if path and os.path.isfile(path):
return open(path, encoding="utf-8").read().strip()
value = os.environ.get(inline_env)
if not value:
raise RuntimeError(f"{file_env} or {inline_env} must be set")
return value
+16
View File
@@ -0,0 +1,16 @@
"""Password KDF (Argon2id) — never store or compare plaintext passwords."""
from argon2 import PasswordHasher
from argon2.exceptions import VerifyMismatchError, InvalidHashError
_hasher = PasswordHasher()
def hash_password(password: str) -> str:
return _hasher.hash(password)
def verify_password(password: str, password_hash: str) -> bool:
try:
return _hasher.verify(password_hash, password)
except (VerifyMismatchError, InvalidHashError):
return False
+54
View File
@@ -0,0 +1,54 @@
"""Opaque Bearer sessions backed by Redis/Valkey, TTL-bound, AOF-persistent."""
import json
import os
import secrets
import uuid
from datetime import datetime, timedelta, timezone
import redis.asyncio as redis
_client: redis.Redis | None = None
TTL_SECONDS = int(os.environ.get("SESSION_TTL_SECONDS", "3600"))
def init(url: str) -> None:
global _client
_client = redis.from_url(url, decode_responses=True, socket_timeout=3, socket_connect_timeout=3)
async def close() -> None:
if _client is not None:
await _client.close()
def client() -> redis.Redis:
if _client is None:
raise RuntimeError("session store is not initialized")
return _client
async def ping() -> bool:
try:
return bool(await client().ping())
except Exception: # noqa: BLE001 - readiness probe
return False
async def create(user_id: uuid.UUID) -> tuple[str, datetime]:
token = secrets.token_urlsafe(32) # 256 bits of entropy, opaque and non-guessable
expires_at = datetime.now(timezone.utc) + timedelta(seconds=TTL_SECONDS)
payload = json.dumps({"user_id": str(user_id), "expires_at": expires_at.isoformat()})
await client().set(f"session:{token}", payload, ex=TTL_SECONDS)
return token, expires_at
async def resolve(token: str) -> uuid.UUID | None:
raw = await client().get(f"session:{token}")
if raw is None:
return None
data = json.loads(raw)
return uuid.UUID(data["user_id"])
async def revoke(token: str) -> None:
await client().delete(f"session:{token}")
+63
View File
@@ -0,0 +1,63 @@
"""Private S3-compatible object storage for attachment bytes (MinIO behind the scenes).
boto3 is synchronous; calls are pushed to a thread so the event loop is not
blocked by S3 I/O. Object keys are server-generated UUIDs, never the
user-supplied filename (filename is display-only, see contracts/README.md).
"""
import asyncio
import io
import uuid
import boto3
from botocore.client import Config
from botocore.exceptions import ClientError
_client = None
_bucket: str | None = None
def init(endpoint: str, region: str, access_key: str, secret_key: str, bucket: str) -> None:
global _client, _bucket
_bucket = bucket
_client = boto3.client(
"s3",
endpoint_url=endpoint,
region_name=region,
aws_access_key_id=access_key,
aws_secret_access_key=secret_key,
config=Config(signature_version="s3v4", retries={"max_attempts": 2}),
)
async def ensure_bucket() -> None:
"""The API identity only has Read/Write/List on this one bucket, not
bucket-admin rights, so CreateBucket is not an option. SeaweedFS (like S3)
auto-creates the bucket on the first successful PutObject, so writing an
empty marker object both creates the bucket and proves write access."""
await asyncio.to_thread(_client.put_object, Bucket=_bucket, Key=".bootstrap", Body=b"")
async def ping() -> bool:
try:
await asyncio.to_thread(_client.head_object, Bucket=_bucket, Key=".bootstrap")
return True
except Exception: # noqa: BLE001 - readiness probe
return False
def new_object_key() -> str:
return f"attachments/{uuid.uuid4().hex}"
async def put_object(key: str, data: bytes, content_type: str) -> None:
await asyncio.to_thread(
_client.put_object, Bucket=_bucket, Key=key, Body=data, ContentType=content_type
)
async def get_object(key: str) -> bytes:
def _get():
resp = _client.get_object(Bucket=_bucket, Key=key)
return resp["Body"].read()
return await asyncio.to_thread(_get)
+149
View File
@@ -0,0 +1,149 @@
name: mtusi2026lab4
services:
lb:
image: nginx:1.27.2
ports:
- "8080:8080"
volumes:
- ./infra/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
depends_on:
api1:
condition: service_healthy
api2:
condition: service_healthy
deploy:
resources:
limits:
cpus: "0.5"
memory: 128M
api1: &api
build: .
image: mtusi2026lab4-api:local
environment: &api-env
APP_HOST: 0.0.0.0
APP_PORT: 8080
APP_ENV: lab
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
DATABASE_URL_FILE: /run/secrets/database_url
CACHE_URL_FILE: /run/secrets/cache_url
S3_ENDPOINT: http://seaweedfs:8333
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}
INSTANCE_ID: api1
secrets: &api-secrets
- database_url
- cache_url
- s3_access_key_id
- s3_secret_access_key
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
seaweedfs:
condition: service_healthy
healthcheck: &api-healthcheck
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)"]
interval: 5s
timeout: 3s
retries: 5
start_period: 10s
deploy:
resources:
limits:
cpus: "1.0"
memory: 256M
api2:
<<: *api
environment:
<<: *api-env
INSTANCE_ID: api2
postgres:
image: postgres:16.4
environment:
POSTGRES_DB: messenger
POSTGRES_USER: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
secrets:
- postgres_password
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"]
interval: 5s
timeout: 3s
retries: 10
deploy:
resources:
limits:
cpus: "1.0"
memory: 512M
redis:
image: redis:7.4.1
command: ["redis-server", "--appendonly", "yes", "--appendfsync", "everysec"]
volumes:
- redisdata:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 3s
retries: 10
deploy:
resources:
limits:
cpus: "0.5"
memory: 256M
seaweedfs:
image: chrislusf/seaweedfs:3.73
# All-in-one (master+volume+filer+S3 gateway) is enough for a single-bucket
# lab stand; s3.json scopes the API's own identity to this one bucket only
# (no admin console is exposed to the network).
command:
- server
- -dir=/data
- -s3
- -s3.port=8333
- -s3.config=/etc/seaweedfs/s3.json
volumes:
- seaweed_data:/data
- ./secrets/s3.json:/etc/seaweedfs/s3.json:ro
healthcheck:
# S3 requires auth (403 on anonymous GET) -- a TCP connect is enough to
# prove the S3 gateway is accepting connections.
test: ["CMD", "nc", "-z", "127.0.0.1", "8333"]
interval: 5s
timeout: 3s
retries: 10
start_period: 10s
deploy:
resources:
limits:
cpus: "1.0"
memory: 512M
volumes:
pgdata:
redisdata:
seaweed_data:
secrets:
database_url:
file: ./secrets/database_url.txt
cache_url:
file: ./secrets/cache_url.txt
postgres_password:
file: ./secrets/postgres_password.txt
s3_access_key_id:
file: ./secrets/s3_access_key_id.txt
s3_secret_access_key:
file: ./secrets/s3_secret_access_key.txt
+48
View File
@@ -0,0 +1,48 @@
token=1ZC9D9imXzZUpIvaW8qOmVdr33YVdMPicZRAWqsgGoU chat=2d72b0c1-df2c-4113-a32f-1fb75bee58fc
--- oversized (11MB) ---
<html>
<head><title>413 Request Entity Too Large</title></head>
<body>
<center><h1>413 Request Entity Too Large</h1></center>
<hr><center>nginx/1.27.2</center>
</body>
</html>
http_code: 413
--- corrupted PNG bytes ---
{"error":{"code":"unsupported_media_type","message":"cannot identify image file <_io.BytesIO object at 0x7cb8783334c0>","request_id":"2bd8f7228a8d4abe8931f9895b47ee3d"}}
http_code: 415
--- oversized (11MB) after fix ---
--- oversized (11MB) after nginx fix, chat=837a45cf-4efb-4eac-9b22-cac92f2f028f ---
<html>
<head><title>413 Request Entity Too Large</title></head>
<body>
<center><h1>413 Request Entity Too Large</h1></center>
<hr><center>nginx/1.27.2</center>
</body>
</html>
http_code: 413
--- oversized (11MB) after real nginx reload, chat=c195690d-349d-42b1-a0ee-64aed48624fc ---
{"error":{"code":"payload_too_large","message":"upload exceeds 10485760 bytes","request_id":"05012b5eb87244f5b148cbe6d0514322"}}
http_code: 413
--- MIME spoof: real JPEG declared as image/png, chat=3b6a90a4-389d-4de7-94bf-eafa440d429d ---
{"id":"becd3307-d724-49ea-8489-0fd433ac48db","chat_id":"3b6a90a4-389d-4de7-94bf-eafa440d429d","owner_id":"d0d5bf95-89b5-4b76-a3fe-50f7dc0ddf09","filename":"spoof.png","content_type":"image/png","size_bytes":111817,"sha256":"99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75","status":"ready","variants":[],"error_code":null,"created_at":"2026-10-29T21:53:55.349174Z","updated_at":"2026-10-29T21:53:55.349174Z"}
http_code: 201
--- real MIME spoof: genuine JPEG bytes, declared Content-Type: image/png, chat=65cb5873-b196-4b26-9e00-1fabec6b9fb7 ---
{"error":{"code":"unsupported_media_type","message":"declared content type does not match actual image format","request_id":"087fa41902454f72983f865a488fe0b7"}}
http_code: 415
--- foreign attachment_id: attach chatA's attachment (628e92e9-c127-48f8-b7b5-c5fc91907503) to a message in chatB ---
{"error":{"code":"not_found","message":"one or more attachment_ids are not available in this chat","request_id":"306a37f74afe49b2aedb3cfb7fedcb82"}}
http_code: 404
--- direct unauthenticated S3 access check (must NOT be exposed to host) ---
host->seaweedfs:8333 directly: 000 (curl exit 7)
host->seaweedfs:8333 directly: 000
exit=7
--- 15 concurrent uploads (sample.png, ~112KB each) -- all 201, memory before/after ---
before:
mtusi2026lab4-api1-1 73.41MiB / 256MiB
mtusi2026lab4-api2-1 69.55MiB / 256MiB
after:
mtusi2026lab4-api1-1 75.21MiB / 256MiB
mtusi2026lab4-api2-1 68.92MiB / 256MiB
+7
View File
@@ -0,0 +1,7 @@
1 orphaned object(s) older than 0 minutes with no DB row.
attachments/orphan-demo-key
Dry-run: nothing deleted. Re-run with --delete to remove them.
--- now with --delete ---
1 orphaned object(s) older than 0 minutes with no DB row.
attachments/orphan-demo-key
Deleted 1 orphan(s).
+32
View File
@@ -0,0 +1,32 @@
worker_processes 1;
# A single worker keeps the round-robin counter shared and deterministic for
# the lab's small replica count; a production LB would instead rely on a
# shared/consistent balancing policy across workers.
events { worker_connections 1024; }
http {
upstream messenger_api {
# Passive health check: a backend failing 1 probe is removed for 3s,
# which keeps failover detection well under the 10s budget.
server api1:8080 max_fails=1 fail_timeout=3s;
server api2:8080 max_fails=1 fail_timeout=3s;
}
server {
listen 8080;
# Slightly above the app's own 10 MiB attachment limit so the API --
# not Nginx's default HTML error page -- produces the contract's
# JSON 413 envelope. The API still enforces the exact byte budget.
client_max_body_size 11M;
location / {
proxy_pass http://messenger_api;
proxy_connect_timeout 1s;
proxy_read_timeout 5s;
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
}
+18
View File
@@ -0,0 +1,18 @@
{
"identities": [
{
"name": "messenger-api",
"credentials": [
{
"accessKey": "__S3_ACCESS_KEY_ID__",
"secretKey": "__S3_SECRET_ACCESS_KEY__"
}
],
"actions": [
"Read:messenger-attachments",
"Write:messenger-attachments",
"List:messenger-attachments"
]
}
]
}
+33
View File
@@ -0,0 +1,33 @@
-- Initial schema: users, chats, membership, messages.
CREATE TABLE IF NOT EXISTS users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
username TEXT NOT NULL UNIQUE,
display_name TEXT NOT NULL,
password_hash TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE IF NOT EXISTS chats (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
title TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
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,
PRIMARY KEY (chat_id, user_id)
);
CREATE INDEX IF NOT EXISTS chat_members_user_idx ON chat_members (user_id);
CREATE TABLE IF NOT EXISTS messages (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
sender_id UUID NOT NULL REFERENCES users(id),
text TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- Keyset pagination over (chat_id, created_at, id) avoids a full scan per page.
CREATE INDEX IF NOT EXISTS messages_chat_keyset_idx ON messages (chat_id, created_at, id);
+15
View File
@@ -0,0 +1,15 @@
-- Idempotency store for POST message: scope = (user, method, path, key).
CREATE TABLE IF NOT EXISTS idempotency_keys (
user_id UUID NOT NULL,
method TEXT NOT NULL,
path TEXT NOT NULL,
idem_key TEXT NOT NULL,
request_hash TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'pending',
response_status INT,
response_body JSONB,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (user_id, method, path, idem_key)
);
CREATE INDEX IF NOT EXISTS idempotency_keys_created_idx ON idempotency_keys (created_at);
+25
View File
@@ -0,0 +1,25 @@
-- Attachment metadata lives in Postgres; bytes live in private S3. s3_key is
-- server-generated and never derived from the user-supplied filename.
CREATE TABLE IF NOT EXISTS attachments (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
owner_id UUID NOT NULL REFERENCES users(id),
filename TEXT NOT NULL,
content_type TEXT NOT NULL,
size_bytes BIGINT NOT NULL,
sha256 TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'ready',
error_code TEXT,
s3_key TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX IF NOT EXISTS attachments_chat_idx ON attachments (chat_id);
-- Many-to-many: a message can reference up to 10 attachments of its own chat.
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),
PRIMARY KEY (message_id, attachment_id)
);
+8
View File
@@ -0,0 +1,8 @@
fastapi==0.115.6
uvicorn[standard]==0.32.1
asyncpg==0.30.0
redis==5.2.1
argon2-cffi==23.1.0
pydantic==2.10.3
boto3==1.35.74
Pillow==11.0.0
+72
View File
@@ -0,0 +1,72 @@
#!/usr/bin/env python3
"""Find S3 objects with no matching `attachments` row (e.g. PUT succeeded but
the PostgreSQL INSERT that followed it never committed -- a crash between the
two writes). Dry-run by default; --delete removes orphans older than the
grace period, never anything referenced in the database.
Usage:
python3 scripts/reconcile_attachments.py --grace-minutes 60
python3 scripts/reconcile_attachments.py --grace-minutes 60 --delete
"""
import argparse
import asyncio
import datetime as dt
import os
import sys
import asyncpg
import boto3
def read_secret(file_env, inline_env):
path = os.environ.get(file_env)
if path and os.path.isfile(path):
return open(path, encoding="utf-8").read().strip()
return os.environ[inline_env]
async def main():
p = argparse.ArgumentParser()
p.add_argument("--grace-minutes", type=int, default=60,
help="Only objects older than this are candidates (protects in-flight uploads).")
p.add_argument("--delete", action="store_true", help="Actually delete orphans (default: dry-run).")
args = p.parse_args()
database_url = read_secret("DATABASE_URL_FILE", "DATABASE_URL")
conn = await asyncpg.connect(database_url)
known_keys = {r["s3_key"] for r in await conn.fetch("SELECT s3_key FROM attachments")}
await conn.close()
s3 = boto3.client(
"s3",
endpoint_url=os.environ["S3_ENDPOINT"],
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"),
)
bucket = os.environ.get("S3_BUCKET", "messenger-attachments")
cutoff = dt.datetime.now(dt.timezone.utc) - dt.timedelta(minutes=args.grace_minutes)
orphans = []
paginator = s3.get_paginator("list_objects_v2")
for page in paginator.paginate(Bucket=bucket, Prefix="attachments/"):
for obj in page.get("Contents", []):
if obj["Key"] in known_keys:
continue
if obj["LastModified"] > cutoff:
continue # might still be an in-flight upload; not an orphan yet
orphans.append(obj["Key"])
print(f"{len(orphans)} orphaned object(s) older than {args.grace_minutes} minutes with no DB row.")
for key in orphans:
print(" ", key)
if args.delete:
s3.delete_object(Bucket=bucket, Key=key)
if orphans and args.delete:
print(f"Deleted {len(orphans)} orphan(s).")
elif orphans:
print("Dry-run: nothing deleted. Re-run with --delete to remove them.")
if __name__ == "__main__":
sys.exit(asyncio.run(main()) or 0)
+28
View File
@@ -0,0 +1,28 @@
#!/bin/sh
set -eu
# Sequenced: Nginx resolves upstream hostnames only at its own startup, so it
# must come back strictly after api1/api2 exist again on the network.
cd "$(dirname "$0")/.."
wait_healthy() {
for svc in "$@"; do
for _ in $(seq 1 60); do
status=$(docker compose ps --format '{{.Health}}' "$svc" 2>/dev/null || true)
[ "$status" = "healthy" ] && break
sleep 1
done
done
}
# Sequenced on purpose: API eagerly connects to Postgres/Redis/S3 at startup
# and exits if they are unreachable, and Nginx resolves upstream hostnames
# only at its own startup -- so each stage must be actually healthy, not just
# "restarted", before the next one comes up.
docker compose restart postgres redis seaweedfs
wait_healthy postgres redis seaweedfs
docker compose restart api1 api2
wait_healthy api1 api2
docker compose restart lb
exit 0
+12
View File
@@ -0,0 +1,12 @@
#!/bin/sh
set -eu
# Stops exactly the API replica identified by TARGET_INSTANCE_ID (api1 or api2),
# leaving it stopped. The other replica keeps serving traffic through the LB.
cd "$(dirname "$0")/.."
: "${TARGET_INSTANCE_ID:?TARGET_INSTANCE_ID must be set by the test harness}"
case "$TARGET_INSTANCE_ID" in
api1|api2) ;;
*) echo "unknown instance id: $TARGET_INSTANCE_ID" >&2; exit 1 ;;
esac
docker compose stop "$TARGET_INSTANCE_ID"
exit 0