diff --git a/.env.example b/.env.example
index d99d26a..9b4f9ff 100644
--- a/.env.example
+++ b/.env.example
@@ -3,18 +3,34 @@
APP_HOST=0.0.0.0
APP_PORT=8080
APP_ENV=lab
+LOG_LEVEL=info
+SHUTDOWN_GRACE_SECONDS=10
SESSION_TTL_SECONDS=3600
-# Choose credentials locally. File paths contain no secret values.
-DATABASE_URL_FILE=/run/secrets/database_url
-# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
-SESSION_STORE=postgres
-CACHE_URL_FILE=/run/secrets/cache_url
+CACHE_TTL_SECONDS=60
+# Sessions live in Redis (lab2 grade 4 path carried from lab3). Not Postgres.
+SESSION_STORE=redis
API_REPLICAS=2
+API_CPUS=0.50
+API_MEM=256m
+POSTGRES_CPUS=1.0
+POSTGRES_MEM=512m
+DB_POOL_MAX=4
+LB_DRAIN_SECONDS=2
IDEMPOTENCY_TTL_SECONDS=86400
+
+# Compose interpolates these. Synthetic local values only; replace after copy.
+POSTGRES_PASSWORD=lab4-dev-only-change-me
+DATABASE_URL=postgresql://messenger:lab4-dev-only-change-me@postgres:5432/messenger
+REDIS_URL=redis://redis:6379/0
+
S3_ENDPOINT=http://s3:9000
S3_REGION=us-east-1
S3_BUCKET=messenger-attachments
-S3_ACCESS_KEY_ID_FILE=/run/secrets/s3_access_key_id
-S3_SECRET_ACCESS_KEY_FILE=/run/secrets/s3_secret_access_key
+# Root is used only by bucket bootstrap. The API uses the app key below.
+MINIO_ROOT_USER=lab4-minio-root
+MINIO_ROOT_PASSWORD=lab4-dev-only-change-me
+S3_ACCESS_KEY_ID=lab4appkey00000001
+S3_SECRET_ACCESS_KEY=lab4-dev-only-change-me
MAX_UPLOAD_BYTES=10485760
MAX_IMAGE_PIXELS=40000000
+ORPHAN_GRACE_SECONDS=120
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..65e21fb
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,29 @@
+FROM python:3.12.8-slim-bookworm AS runtime
+
+WORKDIR /app
+
+RUN groupadd --system app && useradd --system --gid app --home /app --shell /usr/sbin/nologin app \
+ && apt-get update \
+ && apt-get install -y --no-install-recommends curl \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY app ./app
+COPY migrations ./migrations
+COPY contracts/openapi.json ./contracts/openapi.json
+
+USER app
+
+ENV APP_HOST=0.0.0.0 \
+ APP_PORT=8080 \
+ APP_ENV=lab \
+ PYTHONUNBUFFERED=1
+
+EXPOSE 8080
+
+HEALTHCHECK --interval=5s --timeout=3s --start-period=15s --retries=12 \
+ CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)"
+
+CMD ["python", "-m", "app.main"]
diff --git a/app/__init__.py b/app/__init__.py
new file mode 100644
index 0000000..eeb0eb8
--- /dev/null
+++ b/app/__init__.py
@@ -0,0 +1 @@
+"""Messenger API (lab 2): PostgreSQL source of truth, Redis sessions/cache."""
diff --git a/app/cache.py b/app/cache.py
new file mode 100644
index 0000000..ed9261d
--- /dev/null
+++ b/app/cache.py
@@ -0,0 +1,151 @@
+import asyncio
+import json
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+from app import config, rediscli
+from app.errors import AppError
+
+T = TypeVar("T")
+CFG_SINGLEFLIGHT = "cfg:singleflight"
+CFG_INVALIDATE = "cfg:invalidate"
+CFG_DELAY_MS = "cfg:delay_ms"
+SQL_HISTORY = "metrics:sql:messages_select"
+
+
+class SingleFlight:
+ def __init__(self) -> None:
+ self._lock = asyncio.Lock()
+ self._inflight: dict[str, asyncio.Task] = {}
+
+ async def do(self, key: str, factory: Callable[[], Awaitable[T]]) -> T:
+ async with self._lock:
+ task = self._inflight.get(key)
+ if task is None:
+ task = asyncio.create_task(factory())
+ self._inflight[key] = task
+ owner = True
+ else:
+ owner = False
+ try:
+ return await asyncio.shield(task)
+ finally:
+ if owner:
+ async with self._lock:
+ self._inflight.pop(key, None)
+
+
+_sf = SingleFlight()
+
+
+async def _flag(name: str, default: bool = True) -> bool:
+ if not config.lab_mode():
+ return default
+ try:
+ raw = await rediscli.require().get(name)
+ except Exception:
+ return default
+ if raw is None:
+ return default
+ return raw not in {"0", "false", "off"}
+
+
+async def singleflight_enabled() -> bool:
+ return await _flag(CFG_SINGLEFLIGHT, True)
+
+
+async def invalidate_enabled() -> bool:
+ return await _flag(CFG_INVALIDATE, True)
+
+
+async def incr_history_sql() -> None:
+ try:
+ await rediscli.require().incr(SQL_HISTORY)
+ except Exception:
+ pass
+
+
+async def history_sql_count() -> int:
+ try:
+ return int(await rediscli.require().get(SQL_HISTORY) or 0)
+ except Exception:
+ return 0
+
+
+async def reset_history_sql_count() -> None:
+ try:
+ await rediscli.require().set(SQL_HISTORY, 0)
+ except Exception:
+ pass
+
+
+async def load_delay_seconds() -> float:
+ if not config.lab_mode():
+ return 0.0
+ try:
+ raw = await rediscli.require().get(CFG_DELAY_MS)
+ except Exception:
+ return 0.0
+ try:
+ return max(0.0, float(raw or 0) / 1000.0)
+ except (TypeError, ValueError):
+ return 0.0
+
+
+async def set_flags(
+ *,
+ singleflight: bool | None = None,
+ invalidate: bool | None = None,
+ delay_ms: int | None = None,
+) -> dict:
+ r = rediscli.require()
+ if singleflight is not None:
+ await r.set(CFG_SINGLEFLIGHT, "1" if singleflight else "0")
+ if invalidate is not None:
+ await r.set(CFG_INVALIDATE, "1" if invalidate else "0")
+ if delay_ms is not None:
+ await r.set(CFG_DELAY_MS, str(int(delay_ms)))
+ return {
+ "singleflight": await singleflight_enabled(),
+ "invalidate": await invalidate_enabled(),
+ "history_sql": await history_sql_count(),
+ "delay_ms": int((await load_delay_seconds()) * 1000),
+ }
+
+
+async def get_history_page(chat_id: str, cursor: str, limit: int, loader: Callable[[], Awaitable[dict]]) -> dict:
+ r = rediscli.require()
+ try:
+ version = await r.get("histver:" + chat_id) or "0"
+ key = f"hist:{chat_id}:{version}:{cursor}:{limit}"
+ cached = await r.get(key)
+ if cached:
+ return json.loads(cached)
+
+ async def load_and_store() -> dict:
+ delay = await load_delay_seconds()
+ if delay:
+ await asyncio.sleep(delay)
+ page = await loader()
+ try:
+ await r.set(key, json.dumps(page, ensure_ascii=False), ex=config.CACHE_TTL_SECONDS)
+ except Exception:
+ pass
+ return page
+
+ if await singleflight_enabled():
+ return await _sf.do(key, load_and_store)
+ return await load_and_store()
+ except AppError:
+ raise
+ except Exception:
+ return await loader()
+
+
+async def invalidate_history(chat_id: str) -> None:
+ if not await invalidate_enabled():
+ return
+ try:
+ await rediscli.require().incr("histver:" + chat_id)
+ except Exception:
+ pass
diff --git a/app/config.py b/app/config.py
new file mode 100644
index 0000000..b6d1f3b
--- /dev/null
+++ b/app/config.py
@@ -0,0 +1,42 @@
+import os
+import socket
+from pathlib import Path
+
+
+def _env(name: str, default: str = "") -> str:
+ value = os.environ.get(name)
+ return default if value is None or value == "" else value
+
+
+def _file_or_env(name: str, default: str = "") -> str:
+ path = os.environ.get(name + "_FILE")
+ if path:
+ return Path(path).read_text(encoding="utf-8").strip()
+ return _env(name, default)
+
+
+HOST = _env("APP_HOST", "0.0.0.0")
+PORT = int(_env("APP_PORT", "8080"))
+ENV = _env("APP_ENV", "lab")
+LOG_LEVEL = _env("LOG_LEVEL", "info").lower()
+SHUTDOWN_GRACE_SECONDS = float(_env("SHUTDOWN_GRACE_SECONDS", "10"))
+SESSION_TTL_SECONDS = int(_env("SESSION_TTL_SECONDS", "3600"))
+CACHE_TTL_SECONDS = int(_env("CACHE_TTL_SECONDS", "60"))
+DATABASE_URL = _file_or_env("DATABASE_URL")
+REDIS_URL = _file_or_env("REDIS_URL", "redis://redis:6379/0")
+SESSION_STORE = _env("SESSION_STORE", "redis")
+DB_POOL_MIN = int(_env("DB_POOL_MIN", "1"))
+DB_POOL_MAX = int(_env("DB_POOL_MAX", "10"))
+DB_COMMAND_TIMEOUT = float(_env("DB_COMMAND_TIMEOUT", "5"))
+DB_CONNECT_TIMEOUT = float(_env("DB_CONNECT_TIMEOUT", "5"))
+REDIS_SOCKET_TIMEOUT = float(_env("REDIS_SOCKET_TIMEOUT", "2"))
+IDEMPOTENCY_TTL_SECONDS = int(_env("IDEMPOTENCY_TTL_SECONDS", "86400"))
+MIGRATIONS_ON_START = _env("MIGRATIONS_ON_START", "1") == "1"
+LB_DRAIN_SECONDS = float(_env("LB_DRAIN_SECONDS", "2"))
+# Stable for the life of this process. Compose leaves it unset so each
+# container uses its own hostname; stop-one.sh maps that value to one replica.
+INSTANCE_ID = _env("INSTANCE_ID", socket.gethostname())
+
+
+def lab_mode() -> bool:
+ return ENV == "lab"
diff --git a/app/cursor_codec.py b/app/cursor_codec.py
new file mode 100644
index 0000000..40e6ce2
--- /dev/null
+++ b/app/cursor_codec.py
@@ -0,0 +1,112 @@
+import base64
+
+import json
+
+from datetime import datetime
+
+from typing import Any
+
+from uuid import UUID
+
+
+
+
+
+def encode_cursor(chat_id: str, created_at: str, entity_id: str) -> str:
+
+ payload = json.dumps({"c": chat_id, "t": created_at, "i": entity_id}, separators=(",", ":"))
+
+ return base64.urlsafe_b64encode(payload.encode("utf-8")).decode("ascii").rstrip("=")
+
+
+
+
+
+def _validate_cursor_timestamp(value: str) -> None:
+
+ if not value.endswith("Z"):
+
+ raise ValueError("invalid cursor timestamp")
+
+ try:
+
+ datetime.fromisoformat(value[:-1] + "+00:00")
+
+ except ValueError as exc:
+
+ raise ValueError("invalid cursor timestamp") from exc
+
+
+
+
+
+def _require_str_field(data: dict, key: str) -> str:
+
+ if key not in data:
+
+ raise ValueError("invalid cursor")
+
+ value = data[key]
+
+ if not isinstance(value, str):
+
+ raise ValueError("invalid cursor")
+
+ return value
+
+
+
+
+
+def decode_cursor(cursor: str, expected_chat_id: str) -> tuple[str, str]:
+
+ pad = "=" * (-len(cursor) % 4)
+
+ try:
+
+ raw = base64.urlsafe_b64decode((cursor + pad).encode("ascii"))
+
+ data: Any = json.loads(raw.decode("utf-8"))
+
+ except (ValueError, json.JSONDecodeError, UnicodeDecodeError) as exc:
+
+ raise ValueError("invalid cursor") from exc
+
+ if not isinstance(data, dict):
+
+ raise ValueError("invalid cursor")
+
+ try:
+
+ chat_id = _require_str_field(data, "c")
+
+ created_at = _require_str_field(data, "t")
+
+ entity_id = _require_str_field(data, "i")
+
+ except ValueError as exc:
+
+ raise ValueError("invalid cursor") from exc
+
+ if chat_id != expected_chat_id:
+
+ raise ValueError("cursor chat mismatch")
+
+ try:
+
+ UUID(entity_id)
+
+ except ValueError as exc:
+
+ raise ValueError("invalid cursor") from exc
+
+ try:
+
+ _validate_cursor_timestamp(created_at)
+
+ except ValueError as exc:
+
+ raise ValueError("invalid cursor") from exc
+
+ return created_at, entity_id
+
diff --git a/app/db.py b/app/db.py
new file mode 100644
index 0000000..f98fd34
--- /dev/null
+++ b/app/db.py
@@ -0,0 +1,87 @@
+from pathlib import Path
+
+import asyncpg
+
+from app import config
+from app.errors import AppError
+
+pool: asyncpg.Pool | None = None
+INTEGRITY = (
+ asyncpg.UniqueViolationError,
+ asyncpg.ForeignKeyViolationError,
+ asyncpg.CheckViolationError,
+)
+
+
+def _migrations_dir() -> Path:
+ here = Path(__file__).resolve().parent
+ for candidate in (here.parent / "migrations", Path("/app/migrations")):
+ if candidate.is_dir():
+ return candidate
+ raise RuntimeError("migrations directory not found")
+
+
+async def connect() -> asyncpg.Pool:
+ global pool
+ if not config.DATABASE_URL:
+ raise RuntimeError("DATABASE_URL is not set")
+ pool = await asyncpg.create_pool(
+ dsn=config.DATABASE_URL,
+ min_size=config.DB_POOL_MIN,
+ max_size=config.DB_POOL_MAX,
+ command_timeout=config.DB_COMMAND_TIMEOUT,
+ timeout=config.DB_CONNECT_TIMEOUT,
+ )
+ return pool
+
+
+async def close() -> None:
+ global pool
+ if pool is not None:
+ await pool.close()
+ pool = None
+
+
+def require() -> asyncpg.Pool:
+ if pool is None:
+ raise AppError(503, "service unavailable")
+ return pool
+
+
+async def ping() -> None:
+ try:
+ async with require().acquire() as conn:
+ await conn.execute("SELECT 1")
+ except AppError:
+ raise
+ except Exception:
+ raise AppError(503, "service unavailable") from None
+
+
+_MIGRATION_LOCK = 87133103
+
+
+async def apply_migrations() -> None:
+ """Apply pending SQL files once. A session advisory lock stops replica races."""
+ directory = _migrations_dir()
+ async with require().acquire() as conn:
+ await conn.execute("SELECT pg_advisory_lock($1)", _MIGRATION_LOCK)
+ try:
+ await conn.execute(
+ """
+ CREATE TABLE IF NOT EXISTS schema_migrations (
+ filename TEXT PRIMARY KEY,
+ applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+ )
+ """
+ )
+ applied = {row["filename"] for row in await conn.fetch("SELECT filename FROM schema_migrations")}
+ for path in sorted(p for p in directory.glob("*.sql") if p.is_file()):
+ 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(filename) VALUES($1)", path.name)
+ finally:
+ await conn.execute("SELECT pg_advisory_unlock($1)", _MIGRATION_LOCK)
diff --git a/app/docs.py b/app/docs.py
new file mode 100644
index 0000000..7f68e1d
--- /dev/null
+++ b/app/docs.py
@@ -0,0 +1,52 @@
+import json
+from functools import lru_cache
+from pathlib import Path
+
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, JSONResponse, Response
+
+_SPEC_CANDIDATES = (
+ Path(__file__).resolve().parents[1] / "contracts" / "openapi.json",
+ Path("/app/contracts/openapi.json"),
+)
+
+_SWAGGER_HTML = """
+
+
+
+ MTUSI Messenger — Swagger (lab2)
+
+
+
+
+
+
+
+
+"""
+
+
+@lru_cache(maxsize=1)
+def _load_spec() -> dict:
+ for path in _SPEC_CANDIDATES:
+ if path.is_file():
+ return json.loads(path.read_text(encoding="utf-8"))
+ return {"openapi": "3.1.0", "info": {"title": "MTUSI Messenger", "version": "1.2.0"}, "paths": {}}
+
+
+async def openapi_json(_: Request) -> Response:
+ return JSONResponse(_load_spec())
+
+
+async def swagger_ui(_: Request) -> Response:
+ return HTMLResponse(_SWAGGER_HTML)
diff --git a/app/errors.py b/app/errors.py
new file mode 100644
index 0000000..105e8ca
--- /dev/null
+++ b/app/errors.py
@@ -0,0 +1,49 @@
+from typing import Dict, Optional
+
+from starlette.responses import JSONResponse
+
+
+ERROR_CODES = {
+ 400: "invalid_request",
+ 401: "unauthorized",
+ 404: "not_found",
+ 409: "conflict",
+ 413: "payload_too_large",
+ 415: "unsupported_media_type",
+ 429: "rate_limited",
+ 503: "unavailable",
+ 500: "internal_error",
+}
+
+BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"'
+BEARER_CHALLENGE = 'Bearer realm="messenger"'
+
+
+class AppError(Exception):
+ def __init__(self, status: int, message: str, www_authenticate: str | None = None) -> None:
+ super().__init__(message)
+ self.status = status
+ self.message = message
+ self.www_authenticate = www_authenticate
+
+
+def error_response(
+ status: int,
+ message: str,
+ request_id: str,
+ extra_headers: Optional[Dict[str, str]] = None,
+) -> JSONResponse:
+ code = ERROR_CODES.get(status, "internal_error")
+ headers = {"X-Request-Id": request_id, "Content-Type": "application/json"}
+ if extra_headers:
+ headers.update(extra_headers)
+ return JSONResponse(
+ status_code=status,
+ headers=headers,
+ content={"error": {"code": code, "message": message, "request_id": request_id}},
+ )
+
+
+def from_app_error(exc: AppError, request_id: str) -> JSONResponse:
+ extra = {"WWW-Authenticate": exc.www_authenticate} if exc.www_authenticate else None
+ return error_response(exc.status, exc.message, request_id, extra)
diff --git a/app/main.py b/app/main.py
new file mode 100644
index 0000000..c59ca75
--- /dev/null
+++ b/app/main.py
@@ -0,0 +1,146 @@
+import asyncio
+import logging
+import signal
+import sys
+import uuid
+from pathlib import Path
+
+import uvicorn
+from starlette.applications import Starlette
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.routing import Route
+
+from app import config, db, rediscli
+from app.docs import openapi_json, swagger_ui
+from app.errors import AppError, error_response, from_app_error
+from app.middleware import RequestContextMiddleware
+from app.routes import (
+ create_chat,
+ create_message,
+ create_session,
+ current_user,
+ get_chat,
+ health_live,
+ health_ready,
+ lab_flags,
+ lab_metrics,
+ list_chats,
+ list_messages,
+ register_user,
+ revoke_session,
+)
+
+
+def _request_id(request: Request) -> str:
+ existing = getattr(request.state, "request_id", None)
+ if existing:
+ return existing
+ return request.headers.get("X-Request-Id") or str(uuid.uuid4())
+
+
+async def not_found_handler(request: Request, exc: HTTPException) -> Response:
+ return error_response(404, "not found", _request_id(request))
+
+
+async def app_error_handler(request: Request, exc: AppError) -> Response:
+ return from_app_error(exc, _request_id(request))
+
+
+def publish_instance_id() -> None:
+ path = Path(config._env("INSTANCE_ID_FILE", "/tmp/instance-id"))
+ try:
+ path.write_text(config.INSTANCE_ID, encoding="utf-8")
+ except OSError:
+ logging.getLogger("messenger").warning("instance id file was not written")
+
+
+async def startup() -> None:
+ publish_instance_id()
+ logging.getLogger("messenger").info("instance_id=%s", config.INSTANCE_ID)
+ await db.connect()
+ if config.MIGRATIONS_ON_START:
+ await db.apply_migrations()
+ await rediscli.connect()
+
+
+async def shutdown() -> None:
+ await rediscli.close()
+ await db.close()
+
+
+def build_app() -> Starlette:
+ app = Starlette(
+ routes=[
+ Route("/docs", swagger_ui, methods=["GET"]),
+ Route("/openapi.json", openapi_json, methods=["GET"]),
+ Route("/health/live", health_live, methods=["GET"]),
+ Route("/health/ready", health_ready, methods=["GET"]),
+ Route("/api/v1/users", register_user, methods=["POST"]),
+ Route("/api/v1/users/me", current_user, methods=["GET"]),
+ Route("/api/v1/auth/sessions", create_session, methods=["POST"]),
+ Route("/api/v1/auth/sessions/current", revoke_session, methods=["DELETE"]),
+ Route("/api/v1/chats", create_chat, methods=["POST"]),
+ Route("/api/v1/chats", list_chats, methods=["GET"]),
+ Route("/api/v1/chats/{chat_id}", get_chat, methods=["GET"]),
+ Route("/api/v1/chats/{chat_id}/messages", create_message, methods=["POST"]),
+ Route("/api/v1/chats/{chat_id}/messages", list_messages, methods=["GET"]),
+ Route("/api/v1/_lab/metrics", lab_metrics, methods=["GET"]),
+ Route("/api/v1/_lab/flags", lab_flags, methods=["POST"]),
+ ],
+ exception_handlers={404: not_found_handler, AppError: app_error_handler},
+ on_startup=[startup],
+ on_shutdown=[shutdown],
+ )
+ app.state.shutting_down = False
+ app.add_middleware(RequestContextMiddleware)
+ return app
+
+
+def configure_logging() -> None:
+ logging.basicConfig(
+ level=getattr(logging, config.LOG_LEVEL.upper(), logging.INFO),
+ format="%(asctime)s %(levelname)s %(name)s %(message)s",
+ stream=sys.stdout,
+ )
+
+
+def main() -> None:
+ configure_logging()
+ app = build_app()
+ loop = asyncio.new_event_loop()
+ asyncio.set_event_loop(loop)
+
+ server = uvicorn.Server(
+ uvicorn.Config(
+ app,
+ host=config.HOST,
+ port=config.PORT,
+ log_level=config.LOG_LEVEL,
+ access_log=False,
+ timeout_graceful_shutdown=int(config.SHUTDOWN_GRACE_SECONDS),
+ )
+ )
+
+ def _begin_shutdown() -> None:
+ if app.state.shutting_down:
+ return
+ logging.getLogger("messenger").info(
+ "shutdown signal received; readiness fails now, exit in %.1fs",
+ config.LB_DRAIN_SECONDS,
+ )
+ app.state.shutting_down = True
+ loop.call_later(config.LB_DRAIN_SECONDS, lambda: setattr(server, "should_exit", True))
+
+ for sig in (signal.SIGTERM, signal.SIGINT):
+ try:
+ loop.add_signal_handler(sig, _begin_shutdown)
+ except NotImplementedError:
+ signal.signal(sig, lambda *_: _begin_shutdown())
+
+ loop.run_until_complete(server.serve())
+
+
+if __name__ == "__main__":
+ main()
diff --git a/app/middleware.py b/app/middleware.py
new file mode 100644
index 0000000..4b05cca
--- /dev/null
+++ b/app/middleware.py
@@ -0,0 +1,48 @@
+import logging
+import time
+import uuid
+from typing import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+from app.config import INSTANCE_ID
+from app.errors import AppError, error_response, from_app_error
+
+logger = logging.getLogger("messenger.access")
+
+
+def _stamp(response: Response, request_id: str) -> Response:
+ response.headers["X-Request-Id"] = request_id
+ response.headers["X-Instance-Id"] = INSTANCE_ID
+ return response
+
+
+class RequestContextMiddleware(BaseHTTPMiddleware):
+ async def dispatch(self, request: Request, call_next: Callable) -> Response:
+ request_id = request.headers.get("X-Request-Id") or str(uuid.uuid4())
+ request.state.request_id = request_id
+
+ if request.app.state.shutting_down and request.url.path not in ("/health/live", "/health/ready"):
+ return _stamp(error_response(503, "service is shutting down", request_id), request_id)
+
+ started = time.perf_counter()
+ try:
+ response = await call_next(request)
+ except AppError as exc:
+ return _stamp(from_app_error(exc, request_id), request_id)
+ except Exception:
+ logger.exception("request_id=%s unhandled error path=%s", request_id, request.url.path)
+ return _stamp(error_response(500, "internal error", request_id), request_id)
+ elapsed_ms = (time.perf_counter() - started) * 1000
+ _stamp(response, request_id)
+ logger.info(
+ "request_id=%s method=%s path=%s status=%s duration_ms=%.2f",
+ request_id,
+ request.method,
+ request.url.path,
+ response.status_code,
+ elapsed_ms,
+ )
+ return response
diff --git a/app/migrate.py b/app/migrate.py
new file mode 100644
index 0000000..03bc8db
--- /dev/null
+++ b/app/migrate.py
@@ -0,0 +1,29 @@
+"""One-shot schema apply. API replicas do not run this on startup."""
+import asyncio
+import logging
+import sys
+
+from app import config, db
+
+
+async def _main() -> None:
+ if not config.DATABASE_URL:
+ raise SystemExit("DATABASE_URL is not set")
+ await db.connect()
+ try:
+ await db.apply_migrations()
+ finally:
+ await db.close()
+
+
+def main() -> None:
+ logging.basicConfig(
+ level=getattr(logging, config.LOG_LEVEL.upper(), logging.INFO),
+ format="%(asctime)s %(levelname)s %(name)s %(message)s",
+ stream=sys.stdout,
+ )
+ asyncio.run(_main())
+
+
+if __name__ == "__main__":
+ main()
diff --git a/app/passwords.py b/app/passwords.py
new file mode 100644
index 0000000..8a640cd
--- /dev/null
+++ b/app/passwords.py
@@ -0,0 +1,23 @@
+from argon2 import PasswordHasher
+from argon2.exceptions import InvalidHashError, VerifyMismatchError
+
+hasher = PasswordHasher(time_cost=2, memory_cost=8192, parallelism=1)
+_dummy = None
+
+
+def hash_password(password: str) -> str:
+ return hasher.hash(password)
+
+
+def dummy_hash() -> str:
+ global _dummy
+ if _dummy is None:
+ _dummy = hash_password("timing-dummy-password")
+ return _dummy
+
+
+def verify_password(password_hash: str, password: str) -> bool:
+ try:
+ return hasher.verify(password_hash, password)
+ except (VerifyMismatchError, InvalidHashError, TypeError, ValueError):
+ return False
diff --git a/app/rediscli.py b/app/rediscli.py
new file mode 100644
index 0000000..de17311
--- /dev/null
+++ b/app/rediscli.py
@@ -0,0 +1,40 @@
+import redis.asyncio as redis
+
+from app import config
+from app.errors import AppError
+
+client: redis.Redis | None = None
+
+
+async def connect() -> redis.Redis:
+ global client
+ client = redis.from_url(
+ config.REDIS_URL,
+ socket_connect_timeout=config.REDIS_SOCKET_TIMEOUT,
+ socket_timeout=config.REDIS_SOCKET_TIMEOUT,
+ decode_responses=True,
+ )
+ await client.ping()
+ return client
+
+
+async def close() -> None:
+ global client
+ if client is not None:
+ await client.close()
+ client = None
+
+
+def require() -> redis.Redis:
+ if client is None:
+ raise AppError(503, "service unavailable")
+ return client
+
+
+async def ping() -> None:
+ try:
+ await require().ping()
+ except AppError:
+ raise
+ except Exception:
+ raise AppError(503, "service unavailable") from None
diff --git a/app/routes.py b/app/routes.py
new file mode 100644
index 0000000..0b7bb30
--- /dev/null
+++ b/app/routes.py
@@ -0,0 +1,284 @@
+import base64
+import binascii
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from app import cache, config, db, rediscli, sessions, store
+from app.cursor_codec import decode_cursor, encode_cursor
+from app.errors import BASIC_CHALLENGE, BEARER_CHALLENGE, AppError, error_response
+from app.passwords import dummy_hash, hash_password, verify_password
+from app.validation import (
+ parse_json_body,
+ require_exact_keys,
+ validate_display_name,
+ validate_limit,
+ validate_idempotency_key,
+ validate_message_text,
+ validate_password,
+ validate_title,
+ validate_username,
+ validate_uuid,
+)
+
+
+def _json(data: dict, request_id: str, status: int = 200) -> JSONResponse:
+ return JSONResponse(status_code=status, headers={"X-Request-Id": request_id}, content=data)
+
+
+def _empty(request_id: str) -> Response:
+ return Response(status_code=204, headers={"X-Request-Id": request_id})
+
+
+async def _bearer_user(request: Request) -> dict:
+ header = request.headers.get("Authorization") or ""
+ scheme, _, rest = header.partition(" ")
+ if scheme.lower() != "bearer" or not rest.strip():
+ raise AppError(401, "authentication required", BEARER_CHALLENGE)
+ user_id = str(await sessions.resolve(rest.strip()))
+ user = await store.get_user(user_id)
+ if user is None:
+ raise AppError(401, "authentication required", BEARER_CHALLENGE)
+ return user
+
+
+async def health_live(request: Request) -> Response:
+ return _json({"status": "ok"}, request.state.request_id)
+
+
+async def health_ready(request: Request) -> Response:
+ rid = request.state.request_id
+ if request.app.state.shutting_down:
+ return error_response(503, "service is shutting down", rid)
+ await db.ping()
+ await rediscli.ping()
+ return _json({"status": "ok"}, rid)
+
+
+async def register_user(request: Request) -> Response:
+ rid = request.state.request_id
+ if request.headers.get("content-type", "").split(";")[0].strip().lower() not in ("application/json", ""):
+ if request.headers.get("content-type"):
+ return error_response(415, "unsupported media type", rid)
+ raw = await request.body()
+ body, err = parse_json_body(raw)
+ if err:
+ return error_response(400, err, rid)
+ assert body is not None
+ if require_exact_keys(body, {"username", "display_name", "password"}, {"username", "display_name", "password"}):
+ return error_response(400, "invalid user payload", rid)
+ if validate_username(body["username"]) or validate_display_name(body["display_name"]) or validate_password(body["password"]):
+ return error_response(400, "invalid user fields", rid)
+ user, conflict = await store.create_user(body["username"], body["display_name"], hash_password(body["password"]))
+ if conflict:
+ return error_response(409, "username already taken", rid)
+ assert user is not None
+ return _json(user, rid, 201)
+
+
+async def current_user(request: Request) -> Response:
+ user = await _bearer_user(request)
+ return _json(user, request.state.request_id)
+
+
+async def create_session(request: Request) -> Response:
+ rid = request.state.request_id
+ header = request.headers.get("Authorization") or ""
+ scheme, _, rest = header.partition(" ")
+ if scheme.lower() != "basic" or not rest.strip():
+ return error_response(401, "authentication required", rid, {"WWW-Authenticate": BASIC_CHALLENGE})
+ try:
+ decoded = base64.b64decode(rest.strip(), validate=True).decode("utf-8")
+ except (binascii.Error, UnicodeError, ValueError):
+ return error_response(401, "authentication required", rid, {"WWW-Authenticate": BASIC_CHALLENGE})
+ username, sep, password = decoded.partition(":")
+ if not sep:
+ return error_response(401, "authentication required", rid, {"WWW-Authenticate": BASIC_CHALLENGE})
+ row = await store.get_user_by_username(username)
+ password_hash = row["password_hash"] if row else dummy_hash()
+ if row is None or not verify_password(password_hash, password):
+ return error_response(401, "authentication required", rid, {"WWW-Authenticate": BASIC_CHALLENGE})
+ token, expires_at = await sessions.create(row["id"])
+ return _json(
+ {
+ "token": token,
+ "token_type": "Bearer",
+ "expires_at": expires_at,
+ "user": store.user_dict(row),
+ },
+ rid,
+ 201,
+ )
+
+
+async def revoke_session(request: Request) -> Response:
+ header = request.headers.get("Authorization") or ""
+ scheme, _, rest = header.partition(" ")
+ if scheme.lower() != "bearer" or not rest.strip():
+ raise AppError(401, "authentication required", BEARER_CHALLENGE)
+ await sessions.revoke(rest.strip())
+ return _empty(request.state.request_id)
+
+
+async def create_chat(request: Request) -> Response:
+ rid = request.state.request_id
+ user = await _bearer_user(request)
+ ct = request.headers.get("content-type", "").split(";")[0].strip().lower()
+ if ct and ct != "application/json":
+ return error_response(415, "unsupported media type", rid)
+ raw = await request.body()
+ body, err = parse_json_body(raw)
+ if err:
+ return error_response(400, err, rid)
+ assert body is not None
+ if require_exact_keys(body, {"title", "member_ids"}, {"title", "member_ids"}):
+ return error_response(400, "invalid chat payload", rid)
+ if validate_title(body["title"]):
+ return error_response(400, "invalid title", rid)
+ members = body["member_ids"]
+ if not isinstance(members, list) or not members:
+ return error_response(400, "invalid member_ids", rid)
+ if len(members) > 100:
+ return error_response(400, "too many members", rid)
+ for mid in members:
+ if validate_uuid(mid):
+ return error_response(400, "invalid member id", rid)
+ chat, create_err = await store.create_chat(body["title"], members, user["id"])
+ if create_err == "caller not in members":
+ return error_response(400, "caller must be a member", rid)
+ if create_err in ("duplicate members", "unknown member"):
+ return error_response(400, "invalid members", rid)
+ assert chat is not None
+ return _json(chat, rid, 201)
+
+
+async def list_chats(request: Request) -> Response:
+ rid = request.state.request_id
+ user = await _bearer_user(request)
+ limit, limit_err = validate_limit(request.query_params.get("limit"))
+ if limit_err:
+ return error_response(400, limit_err, rid)
+ assert limit is not None
+ cursor_raw = request.query_params.get("cursor")
+ after = None
+ if cursor_raw is not None:
+ if not cursor_raw.strip():
+ return error_response(400, "invalid cursor", rid)
+ try:
+ created_at, entity_id = decode_cursor(cursor_raw, user["id"])
+ except ValueError:
+ return error_response(400, "invalid cursor", rid)
+ after = (created_at, entity_id)
+ items, next_key = await store.list_chats(user["id"], limit, after)
+ next_cursor = None
+ if next_key is not None:
+ next_cursor = encode_cursor(user["id"], next_key[0], next_key[1])
+ return _json({"items": items, "next_cursor": next_cursor}, rid)
+
+
+async def get_chat(request: Request) -> Response:
+ rid = request.state.request_id
+ user = await _bearer_user(request)
+ chat_id = request.path_params["chat_id"]
+ if validate_uuid(chat_id):
+ return error_response(400, "invalid chat id", rid)
+ chat = await store.get_chat(chat_id, user["id"])
+ if chat is None:
+ return error_response(404, "chat not found", rid)
+ return _json(chat, rid)
+
+
+async def create_message(request: Request) -> Response:
+ rid = request.state.request_id
+ user = await _bearer_user(request)
+ chat_id = request.path_params["chat_id"]
+ if validate_uuid(chat_id):
+ return error_response(400, "invalid chat id", rid)
+ ct = request.headers.get("content-type", "").split(";")[0].strip().lower()
+ if ct and ct != "application/json":
+ return error_response(415, "unsupported media type", rid)
+ raw = await request.body()
+ body, err = parse_json_body(raw)
+ if err:
+ return error_response(400, err, rid)
+ assert body is not None
+ if require_exact_keys(body, {"text"}, {"text"}):
+ return error_response(400, "invalid message payload", rid)
+ if validate_message_text(body["text"]):
+ return error_response(400, "invalid message text", rid)
+ if validate_idempotency_key(request.headers.get("Idempotency-Key")):
+ return error_response(400, "invalid idempotency key", rid)
+ message, msg_err = await store.add_message(
+ chat_id,
+ user["id"],
+ body["text"],
+ request.headers.get("Idempotency-Key") or "",
+ request.url.path,
+ )
+ if msg_err == "not_found":
+ return error_response(404, "chat not found", rid)
+ if msg_err == "conflict":
+ return error_response(409, "idempotency key reused with a different body", rid)
+ assert message is not None
+ return _json(message, rid, 201)
+
+
+async def list_messages(request: Request) -> Response:
+ rid = request.state.request_id
+ user = await _bearer_user(request)
+ chat_id = request.path_params["chat_id"]
+ if validate_uuid(chat_id):
+ return error_response(400, "invalid chat id", rid)
+ limit, limit_err = validate_limit(request.query_params.get("limit"))
+ if limit_err:
+ return error_response(400, limit_err, rid)
+ assert limit is not None
+ cursor_raw = request.query_params.get("cursor")
+ after = None
+ if cursor_raw is not None:
+ if not cursor_raw.strip():
+ return error_response(400, "invalid cursor", rid)
+ try:
+ created_at, entity_id = decode_cursor(cursor_raw, chat_id)
+ except ValueError:
+ return error_response(400, "invalid cursor", rid)
+ after = (created_at, entity_id)
+ page, next_key, list_err = await store.list_messages(chat_id, user["id"], limit, after)
+ if list_err == "not_found":
+ return error_response(404, "chat not found", rid)
+ assert page is not None
+ next_cursor = None
+ if next_key is not None:
+ next_cursor = encode_cursor(chat_id, next_key[0], next_key[1])
+ return _json({"items": page, "next_cursor": next_cursor}, rid)
+
+
+async def lab_metrics(request: Request) -> Response:
+ if not config.lab_mode():
+ return error_response(404, "not found", request.state.request_id)
+ return _json(
+ {
+ "singleflight": await cache.singleflight_enabled(),
+ "invalidate": await cache.invalidate_enabled(),
+ "history_sql": await cache.history_sql_count(),
+ },
+ request.state.request_id,
+ )
+
+
+async def lab_flags(request: Request) -> Response:
+ if not config.lab_mode():
+ return error_response(404, "not found", request.state.request_id)
+ raw = await request.body()
+ body, err = parse_json_body(raw)
+ if err:
+ return error_response(400, err, request.state.request_id)
+ assert body is not None
+ if body.get("reset_sql"):
+ await cache.reset_history_sql_count()
+ flags = await cache.set_flags(
+ singleflight=body.get("singleflight"),
+ invalidate=body.get("invalidate"),
+ delay_ms=body.get("delay_ms"),
+ )
+ return _json(flags, request.state.request_id)
diff --git a/app/sessions.py b/app/sessions.py
new file mode 100644
index 0000000..b0e30b1
--- /dev/null
+++ b/app/sessions.py
@@ -0,0 +1,56 @@
+import hashlib
+import json
+import secrets
+from datetime import datetime, timedelta, timezone
+from uuid import UUID
+
+from app import config, rediscli
+from app.errors import AppError, BEARER_CHALLENGE
+
+
+def new_token() -> str:
+ return secrets.token_urlsafe(32)
+
+
+def _key(token: str) -> str:
+ return "sess:" + hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+def _fmt(dt: datetime) -> str:
+ return dt.astimezone(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+
+async def create(user_id: UUID) -> tuple[str, str]:
+ token = new_token()
+ expires = datetime.now(timezone.utc) + timedelta(seconds=config.SESSION_TTL_SECONDS)
+ payload = json.dumps({"user_id": str(user_id), "expires_at": _fmt(expires)})
+ try:
+ await rediscli.require().set(_key(token), payload, ex=config.SESSION_TTL_SECONDS)
+ except AppError:
+ raise
+ except Exception:
+ raise AppError(503, "service unavailable") from None
+ return token, _fmt(expires)
+
+
+async def resolve(token: str) -> UUID:
+ try:
+ raw = await rediscli.require().get(_key(token))
+ except AppError:
+ raise
+ except Exception:
+ raise AppError(503, "service unavailable") from None
+ if not raw:
+ raise AppError(401, "authentication required", BEARER_CHALLENGE)
+ return UUID(json.loads(raw)["user_id"])
+
+
+async def revoke(token: str) -> None:
+ try:
+ deleted = await rediscli.require().delete(_key(token))
+ except AppError:
+ raise
+ except Exception:
+ raise AppError(503, "service unavailable") from None
+ if not deleted:
+ raise AppError(401, "authentication required", BEARER_CHALLENGE)
diff --git a/app/store.py b/app/store.py
new file mode 100644
index 0000000..04e3755
--- /dev/null
+++ b/app/store.py
@@ -0,0 +1,361 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from typing import List, Optional, Tuple
+from uuid import UUID, uuid4
+
+import asyncpg
+
+from app import cache, config, db
+from app.errors import AppError
+
+
+def format_ts(dt: datetime) -> str:
+ if dt.tzinfo is None:
+ dt = dt.replace(tzinfo=timezone.utc)
+ return dt.astimezone(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+
+def user_dict(row) -> dict:
+ return {
+ "id": str(row["id"]),
+ "username": row["username"],
+ "display_name": row["display_name"],
+ "created_at": format_ts(row["created_at"]),
+ }
+
+
+def chat_dict(row, member_ids: List[str]) -> dict:
+ return {
+ "id": str(row["id"]),
+ "title": row["title"],
+ "member_ids": member_ids,
+ "created_at": format_ts(row["created_at"]),
+ }
+
+
+def message_dict(row) -> dict:
+ return {
+ "id": str(row["id"]),
+ "chat_id": str(row["chat_id"]),
+ "sender_id": str(row["sender_id"]),
+ "text": row["text"],
+ "created_at": format_ts(row["created_at"]),
+ }
+
+
+async def _run(coro):
+ try:
+ return await coro
+ except AppError:
+ raise
+ except db.INTEGRITY:
+ raise
+ except Exception:
+ raise AppError(503, "service unavailable") from None
+
+
+async def create_user(username: str, display_name: str, password_hash: str) -> Tuple[Optional[dict], Optional[str]]:
+ user_id = uuid4()
+ created = datetime.now(timezone.utc)
+ try:
+ async with db.require().acquire() as conn:
+ await conn.execute(
+ """
+ INSERT INTO users (id, username, display_name, password_hash, created_at)
+ VALUES ($1, $2, $3, $4, $5)
+ """,
+ user_id,
+ username,
+ display_name,
+ password_hash,
+ created,
+ )
+ except asyncpg.UniqueViolationError:
+ return None, "conflict"
+ except Exception:
+ raise AppError(503, "service unavailable") from None
+ return user_dict({"id": user_id, "username": username, "display_name": display_name, "created_at": created}), None
+
+
+async def get_user(user_id: str) -> Optional[dict]:
+ row = await _run(
+ _fetchrow("SELECT id, username, display_name, created_at FROM users WHERE id = $1", UUID(user_id))
+ )
+ return user_dict(row) if row else None
+
+
+async def get_user_by_username(username: str):
+ return await _run(
+ _fetchrow(
+ "SELECT id, username, display_name, password_hash, created_at FROM users WHERE username = $1",
+ username,
+ )
+ )
+
+
+async def _fetchrow(sql: str, *args):
+ async with db.require().acquire() as conn:
+ return await conn.fetchrow(sql, *args)
+
+
+async def _fetch(sql: str, *args):
+ async with db.require().acquire() as conn:
+ return await conn.fetch(sql, *args)
+
+
+async def member_ids_of(chat_id: UUID) -> List[str]:
+ rows = await _run(_fetch("SELECT user_id FROM chat_members WHERE chat_id = $1 ORDER BY user_id", chat_id))
+ return [str(r["user_id"]) for r in rows]
+
+
+async def create_chat(title: str, member_ids: List[str], caller_id: str) -> Tuple[Optional[dict], Optional[str]]:
+ if caller_id not in member_ids:
+ return None, "caller not in members"
+ if len(set(member_ids)) != len(member_ids):
+ return None, "duplicate members"
+ ids = [UUID(x) for x in member_ids]
+ chat_id = uuid4()
+ created = datetime.now(timezone.utc)
+ try:
+ async with db.require().acquire() as conn:
+ async with conn.transaction():
+ existing = await conn.fetch("SELECT id FROM users WHERE id = ANY($1::uuid[])", ids)
+ if len(existing) != len(ids):
+ return None, "unknown member"
+ await conn.execute(
+ "INSERT INTO chats (id, title, created_at) VALUES ($1, $2, $3)",
+ chat_id,
+ title,
+ created,
+ )
+ await conn.executemany(
+ "INSERT INTO chat_members (chat_id, user_id) VALUES ($1, $2)",
+ [(chat_id, mid) for mid in ids],
+ )
+ except AppError:
+ raise
+ except Exception:
+ raise AppError(503, "service unavailable") from None
+ return chat_dict({"id": chat_id, "title": title, "created_at": created}, member_ids), None
+
+
+async def get_chat(chat_id: str, user_id: str) -> Optional[dict]:
+ row = await load_chat_for_member(chat_id, user_id)
+ if row is None:
+ return None
+ return chat_dict(row, await member_ids_of(UUID(chat_id)))
+
+
+async def load_chat_for_member(chat_id: str, user_id: str):
+ return await _run(
+ _fetchrow(
+ """
+ SELECT c.id, c.title, c.created_at
+ FROM chats c
+ JOIN chat_members m ON m.chat_id = c.id AND m.user_id = $2
+ WHERE c.id = $1
+ """,
+ UUID(chat_id),
+ UUID(user_id),
+ )
+ )
+
+
+async def list_chats(user_id: str, limit: int, after: Optional[Tuple[str, str]] = None):
+ args: list = [UUID(user_id)]
+ clause = ""
+ if after is not None:
+ clause = "AND (c.created_at, c.id) > ($2, $3)"
+ args.extend([datetime.fromisoformat(after[0].replace("Z", "+00:00")), UUID(after[1])])
+ rows = await _run(
+ _fetch(
+ f"""
+ SELECT c.id, c.title, c.created_at
+ FROM chats c
+ JOIN chat_members me ON me.chat_id = c.id AND me.user_id = $1
+ WHERE 1=1 {clause}
+ ORDER BY c.created_at, c.id
+ LIMIT {int(limit) + 1}
+ """,
+ *args,
+ )
+ )
+ page = rows[:limit]
+ items = [chat_dict(row, await member_ids_of(row["id"])) for row in page]
+ next_key = None
+ if len(rows) > limit:
+ last = page[-1]
+ next_key = (format_ts(last["created_at"]), str(last["id"]))
+ return items, next_key
+
+
+def _canonical_message(text: str) -> str:
+ # Missing attachment_ids and [] are the same message. Key order does not matter.
+ return json.dumps(
+ {"attachment_ids": [], "text": text},
+ sort_keys=True,
+ ensure_ascii=False,
+ separators=(",", ":"),
+ )
+
+
+async def add_message(
+ chat_id: str,
+ sender_id: str,
+ text: str,
+ idem_key: str,
+ path: str,
+) -> Tuple[Optional[dict], Optional[str]]:
+ """Insert one message or replay the stored 201. The row and the result commit together.
+
+ Same user+method+path+key is serialized with a Postgres advisory lock so two
+ replicas cannot insert two messages. A failed transaction stores nothing.
+ """
+ digest = hashlib.sha256(_canonical_message(text).encode("utf-8")).hexdigest()
+ lock_key = f"{sender_id}|POST|{path}|{idem_key}"
+ payload: Optional[dict] = None
+ created_new = False
+ try:
+ async with db.require().acquire() as conn:
+ async with conn.transaction():
+ await conn.execute("SELECT pg_advisory_xact_lock(hashtextextended($1::text, 0))", lock_key)
+ member = await conn.fetchrow(
+ """
+ SELECT c.id
+ FROM chats c
+ JOIN chat_members m ON m.chat_id = c.id AND m.user_id = $2
+ WHERE c.id = $1
+ """,
+ UUID(chat_id),
+ UUID(sender_id),
+ )
+ if member is None:
+ return None, "not_found"
+ row = await conn.fetchrow(
+ """
+ SELECT request_hash, response_json, created_at
+ FROM idempotency_keys
+ WHERE user_id = $1 AND http_method = 'POST' AND path = $2 AND idem_key = $3
+ """,
+ UUID(sender_id),
+ path,
+ idem_key,
+ )
+ if row is not None:
+ created_at = row["created_at"]
+ if created_at.tzinfo is None:
+ created_at = created_at.replace(tzinfo=timezone.utc)
+ age = (datetime.now(timezone.utc) - created_at).total_seconds()
+ if age <= config.IDEMPOTENCY_TTL_SECONDS:
+ if row["request_hash"] != digest:
+ return None, "conflict"
+ return json.loads(row["response_json"]), None
+ await conn.execute(
+ """
+ DELETE FROM idempotency_keys
+ WHERE user_id = $1 AND http_method = 'POST' AND path = $2 AND idem_key = $3
+ """,
+ UUID(sender_id),
+ path,
+ idem_key,
+ )
+ message_id = uuid4()
+ created = datetime.now(timezone.utc)
+ await conn.execute(
+ """
+ INSERT INTO messages (id, chat_id, sender_id, text, created_at)
+ VALUES ($1, $2, $3, $4, $5)
+ """,
+ message_id,
+ UUID(chat_id),
+ UUID(sender_id),
+ text,
+ created,
+ )
+ payload = message_dict(
+ {
+ "id": message_id,
+ "chat_id": UUID(chat_id),
+ "sender_id": UUID(sender_id),
+ "text": text,
+ "created_at": created,
+ }
+ )
+ await conn.execute(
+ """
+ INSERT INTO idempotency_keys
+ (user_id, http_method, path, idem_key, request_hash, response_json, created_at)
+ VALUES ($1, 'POST', $2, $3, $4, $5, $6)
+ """,
+ UUID(sender_id),
+ path,
+ idem_key,
+ digest,
+ json.dumps(payload, ensure_ascii=False, separators=(",", ":")),
+ created,
+ )
+ created_new = True
+ except AppError:
+ raise
+ except Exception:
+ raise AppError(503, "service unavailable") from None
+ if created_new:
+ await cache.invalidate_history(chat_id)
+ return payload, None
+
+
+async def list_messages(chat_id: str, user_id: str, limit: int, after: Optional[Tuple[str, str]] = None):
+ if await load_chat_for_member(chat_id, user_id) is None:
+ return None, None, "not_found"
+ cursor = ""
+ after_ts = after_id = None
+ if after is not None:
+ cursor = after[0] + ":" + after[1]
+ after_ts = datetime.fromisoformat(after[0].replace("Z", "+00:00"))
+ after_id = UUID(after[1])
+
+ async def loader() -> dict:
+ await cache.incr_history_sql()
+ if after_ts is None:
+ rows = await _run(
+ _fetch(
+ """
+ SELECT id, chat_id, sender_id, text, created_at
+ FROM messages
+ WHERE chat_id = $1
+ ORDER BY created_at, id
+ LIMIT $2
+ """,
+ UUID(chat_id),
+ limit + 1,
+ )
+ )
+ else:
+ rows = await _run(
+ _fetch(
+ """
+ SELECT id, chat_id, sender_id, text, created_at
+ FROM messages
+ WHERE chat_id = $1 AND (created_at, id) > ($2, $3)
+ ORDER BY created_at, id
+ LIMIT $4
+ """,
+ UUID(chat_id),
+ after_ts,
+ after_id,
+ limit + 1,
+ )
+ )
+ page = rows[:limit]
+ items = [message_dict(r) for r in page]
+ next_key = None
+ if len(rows) > limit:
+ last = page[-1]
+ next_key = (format_ts(last["created_at"]), str(last["id"]))
+ return {"items": items, "next_key": next_key}
+
+ page = await cache.get_history_page(chat_id, cursor, limit, loader)
+ return page["items"], page.get("next_key"), None
diff --git a/app/tools/__init__.py b/app/tools/__init__.py
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/app/tools/__init__.py
@@ -0,0 +1 @@
+
diff --git a/app/tools/explain.py b/app/tools/explain.py
new file mode 100644
index 0000000..e649ad1
--- /dev/null
+++ b/app/tools/explain.py
@@ -0,0 +1,73 @@
+"""Seed ≥10 000 messages and print EXPLAIN (ANALYZE, BUFFERS) for keyset pagination."""
+import asyncio
+import os
+from uuid import uuid4
+
+import asyncpg
+
+from app.passwords import hash_password
+
+
+async def main() -> None:
+ conn = await asyncpg.connect(dsn=os.environ["DATABASE_URL"], timeout=10, command_timeout=120)
+ try:
+ alice = uuid4()
+ bob = uuid4()
+ chat = uuid4()
+ pwd = hash_password("Example-only-not-a-real-secret-123")
+ await conn.execute(
+ "INSERT INTO users (id, username, display_name, password_hash) VALUES ($1,$2,$3,$4),($5,$6,$7,$4)",
+ alice,
+ "explain_a_" + alice.hex[:8],
+ "Alice",
+ pwd,
+ bob,
+ "explain_b_" + bob.hex[:8],
+ "Bob",
+ )
+ await conn.execute("INSERT INTO chats (id, title) VALUES ($1,$2)", chat, "Explain chat")
+ await conn.execute(
+ "INSERT INTO chat_members (chat_id, user_id) VALUES ($1,$2),($1,$3)",
+ chat,
+ alice,
+ bob,
+ )
+ n = int(os.environ.get("EXPLAIN_MESSAGES", "10000"))
+ await conn.execute(
+ """
+ INSERT INTO messages (id, chat_id, sender_id, text, created_at)
+ SELECT gen_random_uuid(), $1, $2, 'seed-' || g, now() - (g || ' milliseconds')::interval
+ FROM generate_series(1, $3) AS g
+ """,
+ chat,
+ alice,
+ n,
+ )
+ count = await conn.fetchval("SELECT count(*) FROM messages WHERE chat_id = $1", chat)
+ print("seeded_messages", count, "chat_id", chat)
+ first = await conn.fetchrow(
+ "SELECT created_at, id FROM messages WHERE chat_id = $1 ORDER BY created_at, id LIMIT 1",
+ chat,
+ )
+ query = """
+ SELECT id, chat_id, sender_id, text, created_at
+ FROM messages
+ WHERE chat_id = $1 AND (created_at, id) > ($2, $3)
+ ORDER BY created_at, id
+ LIMIT 50
+ """
+ print("\n=== WITH index messages_chat_created_id_idx ===")
+ plan = await conn.fetch("EXPLAIN (ANALYZE, BUFFERS) " + query, chat, first["created_at"], first["id"])
+ print("\n".join(row[0] for row in plan))
+ await conn.execute("SET enable_indexscan = off")
+ await conn.execute("SET enable_bitmapscan = off")
+ await conn.execute("SET enable_indexonlyscan = off")
+ print("\n=== WITHOUT index scans (seq scan baseline) ===")
+ plan2 = await conn.fetch("EXPLAIN (ANALYZE, BUFFERS) " + query, chat, first["created_at"], first["id"])
+ print("\n".join(row[0] for row in plan2))
+ finally:
+ await conn.close()
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/app/validation.py b/app/validation.py
new file mode 100644
index 0000000..9723267
--- /dev/null
+++ b/app/validation.py
@@ -0,0 +1,102 @@
+import json
+import re
+from typing import Any, Dict, Optional, Tuple
+from uuid import UUID
+
+USERNAME_RE = re.compile(r"^[a-z0-9_]{3,32}$")
+IDEMPOTENCY_RE = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
+
+
+def parse_json_body(raw: bytes) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
+ if not raw:
+ return None, "empty body"
+ try:
+ data = json.loads(raw.decode("utf-8"))
+ except (UnicodeDecodeError, json.JSONDecodeError):
+ return None, "malformed JSON"
+ if not isinstance(data, dict):
+ return None, "JSON body must be an object"
+ return data, None
+
+
+def require_exact_keys(data: Dict[str, Any], allowed: set, required: set) -> Optional[str]:
+ keys = set(data.keys())
+ if keys - allowed:
+ return "unexpected fields"
+ if required - keys:
+ return "missing required fields"
+ return None
+
+
+def validate_username(value: Any) -> Optional[str]:
+ if not isinstance(value, str) or not USERNAME_RE.fullmatch(value):
+ return "invalid username"
+ return None
+
+
+def validate_display_name(value: Any) -> Optional[str]:
+ if not isinstance(value, str):
+ return "invalid display_name"
+ if not value.strip():
+ return "display_name must not be blank"
+ if len(value) > 100:
+ return "display_name too long"
+ return None
+
+
+def validate_password(value: Any) -> Optional[str]:
+ if not isinstance(value, str):
+ return "invalid password"
+ if not value.strip():
+ return "password must not be blank"
+ if len(value) < 12 or len(value) > 128:
+ return "password length"
+ return None
+
+
+def validate_title(value: Any) -> Optional[str]:
+ if not isinstance(value, str):
+ return "invalid title"
+ if not value.strip():
+ return "title must not be blank"
+ if len(value) > 100:
+ return "title too long"
+ return None
+
+
+def validate_uuid(value: Any) -> Optional[str]:
+ if not isinstance(value, str):
+ return "invalid uuid"
+ try:
+ UUID(value)
+ except ValueError:
+ return "invalid uuid"
+ return None
+
+
+def validate_idempotency_key(value: Optional[str]) -> Optional[str]:
+ if value is None or IDEMPOTENCY_RE.fullmatch(value) is None:
+ return "invalid idempotency key"
+ return None
+
+
+def validate_message_text(value: Any) -> Optional[str]:
+ if not isinstance(value, str):
+ return "invalid text"
+ if not value.strip():
+ return "text must not be blank"
+ if len(value) > 4000:
+ return "text too long"
+ return None
+
+
+def validate_limit(value: Optional[str], default: int = 50) -> Tuple[Optional[int], Optional[str]]:
+ if value is None:
+ return default, None
+ try:
+ limit = int(value)
+ except ValueError:
+ return None, "invalid limit"
+ if limit < 1 or limit > 100:
+ return None, "limit out of range"
+ return limit, None
diff --git a/compose.yaml b/compose.yaml
new file mode 100644
index 0000000..8a85ffb
--- /dev/null
+++ b/compose.yaml
@@ -0,0 +1,131 @@
+# Port of the lab3 stand. Client -> lb:8080 -> api (scale) -> shared Postgres and Redis.
+# API replicas do not publish host ports. Migrations run once in `migrate`.
+# Check period: HAProxy inter 1s, fall 2, rise 1. Worst detection of a dead
+# or not-ready replica is about 2s, plus the 1s DNS hold. API on SIGTERM
+# fails /health/ready immediately and exits after LB_DRAIN_SECONDS (default 2).
+
+services:
+ migrate:
+ build:
+ context: .
+ dockerfile: Dockerfile
+ image: mtusi-messenger:lab4
+ command: ["python", "-m", "app.migrate"]
+ environment:
+ APP_ENV: lab
+ LOG_LEVEL: info
+ DATABASE_URL: postgresql://messenger:${POSTGRES_PASSWORD}@postgres:5432/messenger
+ DB_POOL_MIN: "1"
+ DB_POOL_MAX: "2"
+ MIGRATIONS_ON_START: "1"
+ depends_on:
+ postgres:
+ condition: service_healthy
+ restart: "no"
+ mem_limit: 256m
+ cpus: "0.50"
+
+ api:
+ build:
+ context: .
+ dockerfile: Dockerfile
+ image: mtusi-messenger:lab4
+ environment:
+ APP_HOST: 0.0.0.0
+ APP_PORT: "8080"
+ APP_ENV: lab
+ LOG_LEVEL: info
+ SHUTDOWN_GRACE_SECONDS: "3"
+ LB_DRAIN_SECONDS: ${LB_DRAIN_SECONDS:-2}
+ SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
+ CACHE_TTL_SECONDS: ${CACHE_TTL_SECONDS:-60}
+ IDEMPOTENCY_TTL_SECONDS: ${IDEMPOTENCY_TTL_SECONDS:-86400}
+ SESSION_STORE: redis
+ DATABASE_URL: postgresql://messenger:${POSTGRES_PASSWORD}@postgres:5432/messenger
+ REDIS_URL: redis://redis:6379/0
+ DB_POOL_MIN: "1"
+ DB_POOL_MAX: ${DB_POOL_MAX:-4}
+ DB_COMMAND_TIMEOUT: "5"
+ DB_CONNECT_TIMEOUT: "5"
+ MIGRATIONS_ON_START: "0"
+ depends_on:
+ migrate:
+ condition: service_completed_successfully
+ postgres:
+ condition: service_healthy
+ redis:
+ condition: service_healthy
+ expose:
+ - "8080"
+ restart: unless-stopped
+ mem_limit: ${API_MEM:-256m}
+ cpus: ${API_CPUS:-0.50}
+ stop_grace_period: 8s
+ 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: 6
+ start_period: 5s
+
+ lb:
+ image: haproxy:2.8.14-alpine
+ volumes:
+ - ./infra/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
+ ports:
+ - "127.0.0.1:8080:8080"
+ depends_on:
+ api:
+ condition: service_started
+ restart: unless-stopped
+ mem_limit: 128m
+ cpus: "0.25"
+
+ postgres:
+ image: postgres:16.6-alpine
+ environment:
+ POSTGRES_USER: messenger
+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+ POSTGRES_DB: messenger
+ volumes:
+ - pg_data:/var/lib/postgresql/data
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"]
+ interval: 3s
+ timeout: 3s
+ retries: 20
+ restart: unless-stopped
+ mem_limit: ${POSTGRES_MEM:-512m}
+ cpus: ${POSTGRES_CPUS:-1.0}
+
+ redis:
+ image: redis:7.4.2-alpine
+ command:
+ - redis-server
+ - --appendonly
+ - "yes"
+ - --appendfsync
+ - everysec
+ - --save
+ - "60"
+ - "1"
+ volumes:
+ - redis_data:/data
+ healthcheck:
+ test: ["CMD", "redis-cli", "ping"]
+ interval: 3s
+ timeout: 3s
+ retries: 20
+ restart: unless-stopped
+ mem_limit: 128m
+ cpus: "0.50"
+
+volumes:
+ pg_data:
+ redis_data:
diff --git a/infra/haproxy.cfg b/infra/haproxy.cfg
new file mode 100644
index 0000000..24c99b8
--- /dev/null
+++ b/infra/haproxy.cfg
@@ -0,0 +1,35 @@
+global
+ log stdout format raw local0 info
+ maxconn 200
+
+defaults
+ log global
+ mode http
+ option httplog
+ timeout connect 2s
+ timeout client 10s
+ timeout server 10s
+ timeout http-request 5s
+ timeout check 2s
+ timeout queue 2s
+ retries 1
+
+resolvers docker
+ nameserver dns 127.0.0.11:53
+ resolve_retries 3
+ timeout resolve 1s
+ timeout retry 1s
+ hold valid 1s
+ accepted_payload_size 8192
+
+frontend fe_http
+ bind *:8080
+ default_backend be_api
+
+backend be_api
+ balance roundrobin
+ option httpchk
+ http-check send meth GET uri /health/ready ver HTTP/1.1 hdr host api
+ http-check expect status 200
+ default-server inter 1s fall 2 rise 1
+ server-template srv 8 api:8080 check resolvers docker init-addr none resolve-prefer ipv4
diff --git a/migrations/001_init.sql b/migrations/001_init.sql
new file mode 100644
index 0000000..2501dee
--- /dev/null
+++ b/migrations/001_init.sql
@@ -0,0 +1,49 @@
+-- Lab2 schema (written before application queries).
+-- Source of truth: PostgreSQL for users, chats, membership, messages.
+-- Transaction boundary: INSERT chat + INSERT members in one transaction (rollback together).
+-- Sessions are stored in Redis with AOF, not in this database.
+
+CREATE TABLE IF NOT EXISTS schema_migrations (
+ filename TEXT PRIMARY KEY,
+ applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE users (
+ id UUID PRIMARY KEY,
+ username TEXT NOT NULL,
+ display_name TEXT NOT NULL,
+ password_hash TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ CONSTRAINT users_username_format CHECK (username ~ '^[a-z0-9_]{3,32}$'),
+ CONSTRAINT users_display_name_len CHECK (char_length(display_name) BETWEEN 1 AND 100)
+);
+
+CREATE UNIQUE INDEX users_username_key ON users (username);
+
+CREATE TABLE chats (
+ id UUID PRIMARY KEY,
+ title TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ CONSTRAINT chats_title_len CHECK (char_length(title) BETWEEN 1 AND 100)
+);
+
+CREATE TABLE chat_members (
+ chat_id UUID NOT NULL REFERENCES chats (id) ON DELETE CASCADE,
+ user_id UUID NOT NULL REFERENCES users (id),
+ PRIMARY KEY (chat_id, user_id)
+);
+
+CREATE INDEX chat_members_user_id_idx ON chat_members (user_id);
+CREATE INDEX chats_created_at_id_idx ON chats (created_at, id);
+
+CREATE TABLE messages (
+ id UUID PRIMARY KEY,
+ 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(),
+ CONSTRAINT messages_text_len CHECK (char_length(text) BETWEEN 1 AND 4000)
+);
+
+-- Keyset history: WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT n
+CREATE INDEX messages_chat_created_id_idx ON messages (chat_id, created_at, id);
diff --git a/migrations/002_idempotency.sql b/migrations/002_idempotency.sql
new file mode 100644
index 0000000..acc555c
--- /dev/null
+++ b/migrations/002_idempotency.sql
@@ -0,0 +1,14 @@
+-- Shared idempotency for POST /messages. Scope: user + method + path + key.
+-- The message row and this result are committed in one transaction.
+-- A rolled-back request leaves no row, so a later retry with the same key can insert.
+
+CREATE TABLE IF NOT EXISTS idempotency_keys (
+ user_id UUID NOT NULL REFERENCES users (id),
+ http_method TEXT NOT NULL,
+ path TEXT NOT NULL,
+ idem_key TEXT NOT NULL,
+ request_hash TEXT NOT NULL,
+ response_json TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ PRIMARY KEY (user_id, http_method, path, idem_key)
+);
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..4a028eb
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,5 @@
+starlette==0.41.3
+uvicorn[standard]==0.32.1
+asyncpg==0.30.0
+redis==5.2.1
+argon2-cffi==23.1.0
diff --git a/scripts/restart.sh b/scripts/restart.sh
new file mode 100755
index 0000000..6a3be3a
--- /dev/null
+++ b/scripts/restart.sh
@@ -0,0 +1,10 @@
+#!/bin/sh
+# Restart API replicas and every store they use. Volumes are kept.
+set -eu
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+cd "$ROOT"
+if [ -f .env ]; then
+ docker compose --env-file .env restart postgres redis api
+else
+ docker compose restart postgres redis api
+fi
diff --git a/scripts/rolling-update.sh b/scripts/rolling-update.sh
new file mode 100755
index 0000000..d22d4a1
--- /dev/null
+++ b/scripts/rolling-update.sh
@@ -0,0 +1,55 @@
+#!/bin/sh
+# Replace API replicas one at a time. The other replica keeps serving.
+set -eu
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+cd "$ROOT"
+
+compose() {
+ if [ -f .env ]; then
+ docker compose --env-file .env "$@"
+ else
+ docker compose "$@"
+ fi
+}
+
+if command -v python3 >/dev/null 2>&1; then
+ PY=python3
+else
+ PY=python
+fi
+
+ids=$(compose ps -q api)
+count=0
+for id in $ids; do
+ count=$((count + 1))
+done
+if [ "$count" -lt 2 ]; then
+ echo "rolling update needs at least 2 running API replicas" >&2
+ exit 1
+fi
+
+for id in $ids; do
+ echo "replacing $(docker inspect -f '{{.Config.Hostname}}' "$id")"
+ docker stop -t 8 "$id" >/dev/null
+ docker rm "$id" >/dev/null
+ compose up -d --scale "api=$count" --no-deps --no-recreate api >/dev/null
+ ready=0
+ i=0
+ while [ "$i" -lt 40 ]; do
+ running=0
+ for cid in $(compose ps -q api); do
+ running=$((running + 1))
+ done
+ if [ "$running" -ge "$count" ] && "$PY" -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)" >/dev/null 2>&1; then
+ ready=1
+ break
+ fi
+ i=$((i + 1))
+ sleep 1
+ done
+ if [ "$ready" -ne 1 ]; then
+ echo "replacement did not become ready" >&2
+ exit 1
+ fi
+done
+echo "rolling update finished; replicas=$count"
diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh
new file mode 100755
index 0000000..707e422
--- /dev/null
+++ b/scripts/stop-one.sh
@@ -0,0 +1,32 @@
+#!/bin/sh
+# Stop the single API replica whose X-Instance-Id is TARGET_INSTANCE_ID.
+# Leaves it stopped. Does not touch the database, Redis, the load balancer, or volumes.
+set -eu
+: "${TARGET_INSTANCE_ID:?test provides target API instance alias}"
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+cd "$ROOT"
+
+compose() {
+ if [ -f .env ]; then
+ docker compose --env-file .env "$@"
+ else
+ docker compose "$@"
+ fi
+}
+
+found=0
+for id in $(compose ps -q api); do
+ iid=$(docker exec "$id" cat /tmp/instance-id 2>/dev/null | tr -d '\r\n' || true)
+ host=$(docker inspect -f '{{.Config.Hostname}}' "$id")
+ if [ "$iid" = "$TARGET_INSTANCE_ID" ] || [ "$host" = "$TARGET_INSTANCE_ID" ]; then
+ docker stop -t 5 "$id" >/dev/null
+ found=1
+ break
+ fi
+done
+
+if [ "$found" -ne 1 ]; then
+ echo "no running API replica matched TARGET_INSTANCE_ID" >&2
+ exit 1
+fi