Files
mtusi2026lab6/src/messenger/api.py
T
2026-11-01 20:38:50 +03:00

428 lines
26 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""HTTP-слой: маршруты из contracts/openapi.json, проверка входных данных, единый формат ошибок.
Здесь нет правил предметной области (кто может писать в чат и т.п.) — они в store.py.
Что изменилось с lab2:
- в каждом ответе заголовок X-Instance-Id: какая реплика API обслужила запрос;
- POST сообщения требует Idempotency-Key: повтор того же запроса не создаёт второе сообщение;
- миграции больше не применяются при старте: их применяет отдельный сервис migrate,
а реплика только ждёт актуальную схему (db.wait_for_schema);
- по SIGTERM /health/ready сразу отвечает 503 (флаг draining, см. __main__.py).
В памяти процесса нет ничего, от чего зависит правильность ответа: данные и сессии —
в PostgreSQL, кэш сессий — в общем Valkey. Поэтому любой запрос может обслужить любая реплика.
Что добавилось в lab4:
- вложения: POST /chats/{id}/attachments (сырые байты PNG/JPEG), GET /attachments/{id}
и /content. Байты — в приватном S3 (objects.py), метаданные — в PostgreSQL (store.py),
на диске реплики оригинала нет;
- в сообщении поле attachment_ids; текст может быть пустым, если есть вложение;
- фоновый уборщик незавершённых загрузок (cleanup.py).
Что изменилось в lab5:
- POST вложения отвечает 202 queued: оригинал в staging S3, задание и outbox в PostgreSQL
(attachments.py). Картинку обрабатывает отдельный процесс worker (worker.py);
- в каждой реплике фоновый relay отправляет outbox в брокер (relay.py);
- GET вложения показывает любое состояние (queued/processing/ready/failed), варианты и error_code;
/content отвечает 409, пока вложение не готово, и умеет variant=thumbnail|crop|optimized;
- /health/ready проверяет и S3: без него не принять файл в staging (обязательный путь).
Брокер в readiness не входит: благодаря outbox его недоступность не мешает приёму;
- уборщик объектов S3 переехал в worker.
Что добавилось в lab6 (наблюдаемость, telemetry.py):
- каждый HTTP-запрос — server span (инструментация FastAPI, __main__.py) и точка в гистограмме
http.server.request.duration (метод, маршрут-шаблон, код ответа); /health/* не учитывается;
- строка лога на запрос — структурная (JSON в stdout и OTLP-лог): event=http.request, маршрут-шаблон,
код, длительность, request_id, а trace_id/span_id добавляются автоматически. X-Request-Id ответа
записан и в span (messenger.request_id), и в лог — по нему HTTP-ошибка находится в логах и трассах;
- у загрузки в span записан attachment_id, а в строку outbox — traceparent этого span (jobs.enqueue):
по нему relay и worker продолжают ту же трассу (upload -> publish -> consume -> S3/DB);
- метрики очереди и outbox (queuestats.py) и пула соединений с БД.
"""
import hashlib
import json
import logging
import threading
import time
import uuid
from contextlib import asynccontextmanager
from dataclasses import asdict
from typing import Annotated
from fastapi import BackgroundTasks, Depends, FastAPI, Header, Query, Request, Response
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse, StreamingResponse
from pydantic import AfterValidator, BaseModel, ConfigDict, Field, model_validator
from starlette.concurrency import run_in_threadpool
from starlette.exceptions import HTTPException as StarletteHTTPException
from opentelemetry import trace
from . import attachments, config, db, faults, images, objects, security, telemetry
from .queuestats import QueueStats
from .cursor import decode_cursor, encode_cursor
from .errors import AppError, InvalidRequest, Unauthorized, Unavailable
from .relay import OutboxRelay
from .sessions import AuthContext, SessionCache, Sessions
from .store import VARIANT_ORDER, PostgresStore, User, sort_key
log = logging.getLogger("messenger")
# Один набор объектов на процесс. Пул соединений открывается при старте (lifespan).
pool = db.create_pool()
store = PostgresStore(pool)
cache = SessionCache(config.CACHE_URL)
sessions = Sessions(store, cache, config.SESSION_TTL_SECONDS)
relay = OutboxRelay() # outbox -> брокер (с lab5)
queue_stats = QueueStats() # метрики очереди заданий и outbox (с lab6)
# Выставляется по SIGTERM (__main__.py): реплика уходит из балансировки, но ещё отвечает.
draining = threading.Event()
monitors_stop = threading.Event() # остановка фоновой проверки S3
@asynccontextmanager
async def lifespan(_app: FastAPI):
config.validate()
config.validate_s3()
config.validate_broker()
await run_in_threadpool(db.wait_for_schema) # миграции применяет сервис migrate, мы только ждём
pool.open()
cache.start_monitor() # фоновая проверка Valkey раз в CACHE_CHECK_INTERVAL_SECONDS
objects.start_monitor(monitors_stop) # фоновая проверка S3 для /health/ready (с lab5)
relay.start() # отправка outbox в брокер (с lab5)
telemetry.observe_pool(pool, "messenger-api") # метрики пула соединений (с lab6)
queue_stats.start() # метрики очереди и outbox (с lab6)
log.info("Реплика %s запущена: версия %s, env=%s, TTL сессии=%s c, кэш сессий: %s",
config.INSTANCE_ID, config.APP_VERSION, config.APP_ENV, config.SESSION_TTL_SECONDS,
"Valkey" if cache.enabled else "выключен", extra={"event": "api.started"})
yield
queue_stats.stop()
relay.stop() # строки, которые не успели отправить, остаются в outbox
monitors_stop.set()
pool.close() # аккуратно закрываем соединения с БД при остановке
log.info("Реплика %s остановлена: соединения с PostgreSQL закрыты, данные остаются в базе",
config.INSTANCE_ID, extra={"event": "api.stopped"})
app = FastAPI(title="MTUSI Messenger, lab6", lifespan=lifespan)
# ---------- ошибки и служебная обёртка каждого запроса ----------
def error_response(request: Request, status: int, code: str, message: str,
headers: dict[str, str] | None = None) -> JSONResponse:
body = {"error": {"code": code, "message": message, "request_id": request.state.request_id}}
return JSONResponse(body, status_code=status, headers=headers)
# Эти два адреса доступны без токена. Всё остальное под /api/ требует Bearer.
PUBLIC_ENDPOINTS = {("POST", "/api/v1/users"), ("POST", "/api/v1/auth/sessions")}
def needs_bearer(request: Request) -> bool:
return request.url.path.startswith("/api/") and (request.method, request.url.path) not in PUBLIC_ENDPOINTS
def authenticate(authorization: str | None) -> AuthContext:
"""Bearer-токен -> пользователь. Любая проблема с токеном -> 401 с WWW-Authenticate: Bearer."""
token = security.parse_bearer(authorization)
auth = sessions.authenticate(token) if token else None
if auth is None:
raise Unauthorized("Нужен действующий Bearer-токен сессии")
return auth
@app.middleware("http")
async def request_context(request: Request, call_next):
"""Выполняется вокруг каждого запроса: X-Request-Id, X-Instance-Id, аутентификация, лог.
Аутентификация стоит здесь, а не в обработчике: она выполняется ДО разбора тела
и поиска чата. Так соблюдается порядок из контракта: сначала «кто ты» (401),
потом «можно ли тебе этот объект» (404) и «правильный ли запрос» (400).
"""
request.state.request_id = uuid.uuid4().hex
started = time.perf_counter()
# Server span создан инструментацией FastAPI снаружи этого middleware (для /health/* его нет).
span = trace.get_current_span()
span.set_attribute("messenger.request_id", request.state.request_id)
try:
if needs_bearer(request):
# Проверка токена ходит в Valkey/PostgreSQL (блокирующий код) — выполняем в пуле потоков.
request.state.auth = await run_in_threadpool(authenticate, request.headers.get("Authorization"))
response = await call_next(request)
except AppError as exc: # 401 от аутентификации или 503, если хранилище недоступно
response = error_response(request, exc.status, exc.code, exc.message, exc.headers)
except Exception:
# Подробности (stack trace) — только в лог сервера, клиенту — общий ответ 500.
log.exception("Необработанная ошибка, request_id=%s", request.state.request_id,
extra={"event": "http.unhandled_error", "request_id": request.state.request_id})
response = error_response(request, 500, "internal_error", "Внутренняя ошибка сервера")
response.headers["X-Request-Id"] = request.state.request_id
# С lab3: в каждом ответе (и в ошибках, и в health) — какая реплика его создала.
response.headers["X-Instance-Id"] = config.INSTANCE_ID
# В лог не пишем тела, query-параметры, заголовки и даже сам путь (в нём ID чатов):
# только маршрут-шаблон. Успешные проверки /health/* балансировщика (2 в секунду) не пишем.
route = getattr(request.scope.get("route"), "path", None) or "unmatched"
if not (route.startswith("/health/") and response.status_code == 200):
duration_ms = round((time.perf_counter() - started) * 1000, 1)
log.log(logging.WARNING if response.status_code >= 500 else logging.INFO,
"%s %s -> %d (%.1f ms) request_id=%s", request.method, route, response.status_code,
duration_ms, request.state.request_id,
extra={"event": "http.request", "http.request.method": request.method, "http.route": route,
"http.response.status_code": response.status_code, "duration_ms": duration_ms,
"request_id": request.state.request_id})
return response
@app.exception_handler(AppError)
async def handle_app_error(request: Request, exc: AppError):
return error_response(request, exc.status, exc.code, exc.message, exc.headers)
@app.exception_handler(RequestValidationError)
async def handle_validation_error(request: Request, exc: RequestValidationError):
# FastAPI по умолчанию отвечает 422 со своим форматом; контракт требует 400 и наш формат.
# Детали pydantic клиенту не отдаём: в них может быть эхо входных данных (например, пароль).
first = exc.errors()[0]
if first["type"] == "json_invalid":
message = "Тело запроса не является корректным JSON"
else:
message = "Неверное значение: " + ".".join(str(part) for part in first["loc"])
return error_response(request, 400, "invalid_request", message)
@app.exception_handler(StarletteHTTPException)
async def handle_http_error(request: Request, exc: StarletteHTTPException):
# Ошибки, которые создаёт сам фреймворк: неизвестный путь (404), не тот метод (405) и т.п.
if exc.status_code == 404:
return error_response(request, 404, "not_found", "Ресурс не найден")
return error_response(request, exc.status_code, "invalid_request", "Запрос не может быть обработан")
# ---------- входные данные (схемы из contracts/openapi.json) ----------
def _not_blank(value: str) -> str:
if not value.strip():
raise ValueError("строка состоит только из пробелов")
return value
# Длины в символах Unicode (code points): len("👋") == 1 в Python.
Name = Annotated[str, Field(min_length=1, max_length=100), AfterValidator(_not_blank)]
Text = Annotated[str, Field(min_length=1, max_length=4000), AfterValidator(_not_blank)]
Password = Annotated[str, Field(min_length=security.PASSWORD_MIN, max_length=security.PASSWORD_MAX),
AfterValidator(_not_blank)]
class StrictModel(BaseModel):
model_config = ConfigDict(extra="forbid") # лишние поля в JSON -> 400
class CreateUser(StrictModel):
username: Annotated[str, Field(pattern=r"^[a-z0-9_]{3,32}$")]
display_name: Name
password: Password
class CreateChat(StrictModel):
title: Name
member_ids: Annotated[list[uuid.UUID], Field(min_length=1, max_length=100)]
class CreateMessage(StrictModel):
# Поля sender_id нет: прислать его = лишнее поле = 400.
# С lab4 текст может быть пустым, но только если есть хотя бы одно вложение.
text: Annotated[str, Field(max_length=4000)]
# Отсутствующий attachment_ids равен []: model_dump даёт одинаковый отпечаток для повтора.
attachment_ids: Annotated[list[uuid.UUID], Field(max_length=10)] = []
@model_validator(mode="after")
def text_or_attachments(self):
if len(set(self.attachment_ids)) != len(self.attachment_ids):
raise ValueError("attachment_ids повторяются")
if not self.attachment_ids and not self.text.strip():
raise ValueError("нужен непустой текст или хотя бы одно вложение")
return self
# Ключ идемпотентности (с lab3): ASCII [A-Za-z0-9._:-], 1–128 символов. Нет или неверный -> 400.
IdempotencyKey = Annotated[str, Header(alias="Idempotency-Key", min_length=1, max_length=128,
pattern=r"^[A-Za-z0-9._:-]+$")]
def request_fingerprint(body: BaseModel) -> bytes:
"""SHA-256 «смысла» запроса: тело после разбора, ключи по алфавиту, без лишних пробелов.
Поэтому порядок полей и форматирование JSON не важны: {"text":"a"} и { "text" : "a" }
дают одинаковый отпечаток. Сравнивается при повторе с тем же Idempotency-Key.
"""
canonical = json.dumps(body.model_dump(mode="json"), sort_keys=True, ensure_ascii=False,
separators=(",", ":"))
return hashlib.sha256(canonical.encode("utf-8")).digest()
# ---------- текущий пользователь ----------
def current_auth(request: Request) -> AuthContext:
"""Сессия, которую middleware уже проверил для этого запроса."""
auth = getattr(request.state, "auth", None)
if auth is None: # защита от ошибки в PUBLIC_ENDPOINTS: без проверки токена доступа нет
raise Unauthorized("Нужен действующий Bearer-токен сессии")
return auth
def current_user(auth: Annotated[AuthContext, Depends(current_auth)]) -> User:
return auth.user
CurrentAuth = Annotated[AuthContext, Depends(current_auth)]
CurrentUser = Annotated[User, Depends(current_user)]
Limit = Annotated[int, Query(ge=1, le=100)]
Cursor = Annotated[str | None, Query(min_length=1)]
def page_response(scope: str, items: list, has_more: bool) -> dict:
next_cursor = encode_cursor(scope, sort_key(items[-1])) if has_more else None
return {"items": [asdict(item) for item in items], "next_cursor": next_cursor}
# ---------- маршруты ----------
# Обработчики объявлены через def (не async def): FastAPI запускает их в пуле потоков,
# поэтому запросы обрабатываются параллельно. Согласованность данных обеспечивает
# PostgreSQL (транзакции и ограничения), а не замок в памяти процесса.
@app.get("/health/live")
def health_live():
return {"status": "ok"} # процесс жив; от зависимостей не зависит
@app.get("/health/ready")
def health_ready():
# Готовность = можно обслужить обязательный синхронный путь. Критичны:
# - PostgreSQL (всё, что API хранит, и outbox);
# - S3 (с lab5): без него нельзя принять файл в staging, а без staging нельзя честно ответить 202.
# Не критичны: Valkey (без кэша сессий API работает через PostgreSQL) и брокер
# (задания копятся в outbox и уйдут в брокер, когда он вернётся), worker (задания ждут в очереди).
if draining.is_set():
# Получен SIGTERM: просим балансировщик больше не присылать запросы (см. __main__.py).
raise Unavailable("Реплика останавливается")
store.ping() # если БД недоступна -> Unavailable -> 503 в общем формате ошибки
if not objects.healthy():
raise Unavailable("Хранилище файлов недоступно")
return {"status": "ok"}
@app.post("/api/v1/users", status_code=201)
def register_user(body: CreateUser):
password_hash = security.hash_password(body.password) # сам пароль нигде не сохраняется
return asdict(store.create_user(body.username, body.display_name, password_hash))
@app.post("/api/v1/auth/sessions", status_code=201)
def create_session(response: Response, authorization: Annotated[str | None, Header()] = None):
credentials = security.parse_basic(authorization)
result = sessions.login(*credentials) if credentials else None
if result is None:
# Один и тот же ответ для «нет такого пользователя», «неверный пароль» и «кривой заголовок».
raise Unauthorized("Неверное имя пользователя или пароль", Unauthorized.BASIC)
token, expires_at, user = result
response.headers["Cache-Control"] = "no-store" # ответ с токеном нельзя кэшировать
return {"token": token, "token_type": "Bearer", "expires_at": expires_at, "user": asdict(user)}
@app.delete("/api/v1/auth/sessions/current", status_code=204)
def revoke_session(auth: CurrentAuth):
sessions.logout(auth)
return Response(status_code=204)
@app.get("/api/v1/users/me")
def get_me(user: CurrentUser):
return asdict(user)
@app.post("/api/v1/chats", status_code=201)
def create_chat(body: CreateChat, user: CurrentUser):
member_ids = [str(member_id) for member_id in body.member_ids]
return asdict(store.create_chat(user.id, body.title, member_ids))
@app.get("/api/v1/chats")
def list_chats(user: CurrentUser, limit: Limit = 50, cursor: Cursor = None):
scope = f"chats:{user.id}"
items, has_more = store.list_chats(user.id, decode_cursor(scope, cursor), limit)
return page_response(scope, items, has_more)
@app.get("/api/v1/chats/{chat_id}")
def get_chat(chat_id: uuid.UUID, user: CurrentUser):
return asdict(store.get_chat(user.id, str(chat_id)))
@app.post("/api/v1/chats/{chat_id}/messages", status_code=201)
def send_message(chat_id: uuid.UUID, body: CreateMessage, user: CurrentUser,
idempotency_key: IdempotencyKey):
# Учебная точка отказа (lab6, инцидент 2): медленный обработчик при здоровой БД.
# Отдельного span нет намеренно: в трассе это «пустое» время server span без дочерних SQL-спанов.
time.sleep(faults.number("api_slow_handler"))
# Область ключа из контракта: пользователь + метод + путь чата + ключ.
# Метод и путь у этого обработчика всегда одни, поэтому в БД ключ уникален в паре (чат, отправитель).
message, replayed = store.add_message(user.id, str(chat_id), body.text,
idempotency_key, request_fingerprint(body),
tuple(str(a) for a in body.attachment_ids))
if replayed:
log.info("Повтор с тем же Idempotency-Key: возвращаю уже сохранённое сообщение %s", message.id,
extra={"event": "message.idempotent_replay"})
return asdict(message)
@app.get("/api/v1/chats/{chat_id}/messages")
def list_messages(chat_id: uuid.UUID, user: CurrentUser, limit: Limit = 50, cursor: Cursor = None):
scope = f"messages:{chat_id}"
items, has_more = store.list_messages(user.id, str(chat_id), decode_cursor(scope, cursor), limit)
return page_response(scope, items, has_more)
# ---------- вложения (с lab4; с lab5 — асинхронная обработка) ----------
@app.post("/api/v1/chats/{chat_id}/attachments", status_code=202)
async def upload_attachment(request: Request, chat_id: uuid.UUID, user: CurrentUser, background: BackgroundTasks,
filename: Annotated[str | None, Query()] = None):
# async: тело читается потоком (attachments.receive_body), а блокирующие шаги
# (проверка структуры, S3, БД) идут в пуле потоков. Дешёвые проверки — до чтения тела.
# 202 = файл принят на обработку (staging + задание сохранены), а не «готов».
chat = str(chat_id)
await run_in_threadpool(store.get_chat, user.id, chat) # посторонний -> 404, тело не читаем
name = images.check_filename(filename) # 400
declared = images.declared_type(request.headers.get("Content-Type")) # 415
attachments.check_content_length(request.headers.get("Content-Length")) # 413 до чтения тела
attachment = await attachments.upload(request, store, user.id, chat, name, declared)
# По attachment_id трасса загрузки находится в Tempo (технический ID синтетических данных, не label метрик).
trace.get_current_span().set_attribute("messenger.attachment.id", attachment.id)
# Разбудить relay ПОСЛЕ отправки ответа: задание уже в outbox, отправка в брокер — следующий шаг.
background.add_task(relay.nudge)
return asdict(attachment)
@app.get("/api/v1/attachments/{attachment_id}")
def get_attachment(attachment_id: uuid.UUID, user: CurrentUser):
attachment, _key = store.get_attachment(user.id, str(attachment_id))
return asdict(attachment)
@app.get("/api/v1/attachments/{attachment_id}/content")
def download_attachment(attachment_id: uuid.UUID, user: CurrentUser, variant: str = "original"):
if variant != "original" and variant not in VARIANT_ORDER:
raise InvalidRequest("Неверное значение: variant")
# Не участник -> 404; не готово (queued/processing/failed) -> 409; нет такого варианта -> 404.
key, content_type, size = store.get_content(user.id, str(attachment_id), variant)
try:
body = objects.open_stream(key)
except objects.MissingObject:
log.error("Нет объекта в S3 для готового вложения %s (%s)", attachment_id, variant,
extra={"event": "attachment.object_missing"})
raise Unavailable("Файл временно недоступен") from None
# Через API, без redirect на S3: доступ проверен выше. Отдаём кусками, без чтения в память целиком.
return StreamingResponse(objects.iter_chunks(body), media_type=content_type, headers={
"Content-Length": str(size),
"Cache-Control": "private, no-store",
"X-Content-Type-Options": "nosniff",
})