From f3bcdad9e87ad23cbd3f3eb4581c8b0c12948ee9 Mon Sep 17 00:00:00 2001 From: casablanca Date: Wed, 28 Oct 2026 16:10:43 +0300 Subject: [PATCH 1/5] =?UTF-8?q?=D0=BF=D0=BE=D1=80=D1=82=20=D0=B8=D0=B7=203?= =?UTF-8?q?=20=D0=BB=D0=B0=D0=B1=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Dockerfile | 25 + alembic.ini | 149 ++++ compose.yaml | 119 ++++ infra/nginx.conf | 36 + migrations/README | 1 + migrations/env.py | 50 ++ migrations/script.py.mako | 28 + .../b3a91c0e7d42_message_idempotency.py | 61 ++ .../versions/f7c51e1e945b_initial_schema.py | 110 +++ requirements.txt | 20 + scripts/bootstrap.sh | 29 + scripts/restart.sh | 4 + scripts/stop-one.sh | 14 + src/__init__.py | 0 src/cursor.py | 86 +++ src/database.py | 57 ++ src/errors.py | 12 + src/main.py | 528 ++++++++++++++ src/models.py | 118 ++++ src/repositories.py | 655 ++++++++++++++++++ src/security.py | 16 + src/sessions.py | 87 +++ 22 files changed, 2205 insertions(+) create mode 100644 Dockerfile create mode 100644 alembic.ini create mode 100644 compose.yaml create mode 100644 infra/nginx.conf create mode 100644 migrations/README create mode 100644 migrations/env.py create mode 100644 migrations/script.py.mako create mode 100644 migrations/versions/b3a91c0e7d42_message_idempotency.py create mode 100644 migrations/versions/f7c51e1e945b_initial_schema.py create mode 100644 requirements.txt create mode 100755 scripts/bootstrap.sh create mode 100755 scripts/restart.sh create mode 100755 scripts/stop-one.sh create mode 100644 src/__init__.py create mode 100644 src/cursor.py create mode 100644 src/database.py create mode 100644 src/errors.py create mode 100644 src/main.py create mode 100644 src/models.py create mode 100644 src/repositories.py create mode 100644 src/security.py create mode 100644 src/sessions.py diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..99aff457 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,25 @@ +FROM python:3.13.15-slim + +ENV PYTHONDONTWRITEBYTECODE=1 +ENV PYTHONUNBUFFERED=1 + +WORKDIR /app + +COPY requirements.txt . + +RUN pip install --no-cache-dir -r requirements.txt + +COPY alembic.ini . +COPY migrations ./migrations +COPY src ./src + +RUN useradd --create-home --uid 10001 appuser + +USER appuser + +EXPOSE 8080 + +HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \ + CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2)" || exit 1 + +CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8080"] \ No newline at end of file diff --git a/alembic.ini b/alembic.ini new file mode 100644 index 00000000..017e41ad --- /dev/null +++ b/alembic.ini @@ -0,0 +1,149 @@ +# A generic, single database configuration. + +[alembic] +# path to migration scripts. +# this is typically a path given in POSIX (e.g. forward slashes) +# format, relative to the token %(here)s which refers to the location of this +# ini file +script_location = %(here)s/migrations + +# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s +# Uncomment the line below if you want the files to be prepended with date and time +# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file +# for all available tokens +# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s +# Or organize into date-based subdirectories (requires recursive_version_locations = true) +# file_template = %%(year)d/%%(month).2d/%%(day).2d_%%(hour).2d%%(minute).2d_%%(second).2d_%%(rev)s_%%(slug)s + +# sys.path path, will be prepended to sys.path if present. +# defaults to the current working directory. for multiple paths, the path separator +# is defined by "path_separator" below. +prepend_sys_path = . + +# timezone to use when rendering the date within the migration file +# as well as the filename. +# If specified, requires the tzdata library which can be installed by adding +# `alembic[tz]` to the pip requirements. +# string value is passed to ZoneInfo() +# leave blank for localtime +# timezone = + +# max length of characters to apply to the "slug" field +# truncate_slug_length = 40 + +# set to 'true' to run the environment during +# the 'revision' command, regardless of autogenerate +# revision_environment = false + +# set to 'true' to allow .pyc and .pyo files without +# a source .py file to be detected as revisions in the +# versions/ directory +# sourceless = false + +# version location specification; This defaults +# to /versions. When using multiple version +# directories, initial revisions must be specified with --version-path. +# The path separator used here should be the separator specified by "path_separator" +# below. +# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions + +# path_separator; This indicates what character is used to split lists of file +# paths, including version_locations and prepend_sys_path within configparser +# files such as alembic.ini. +# The default rendered in new alembic.ini files is "os", which uses os.pathsep +# to provide os-dependent path splitting. +# +# Note that in order to support legacy alembic.ini files, this default does NOT +# take place if path_separator is not present in alembic.ini. If this +# option is omitted entirely, fallback logic is as follows: +# +# 1. Parsing of the version_locations option falls back to using the legacy +# "version_path_separator" key, which if absent then falls back to the legacy +# behavior of splitting on spaces and/or commas. +# 2. Parsing of the prepend_sys_path option falls back to the legacy +# behavior of splitting on spaces, commas, or colons. +# +# Valid values for path_separator are: +# +# path_separator = : +# path_separator = ; +# path_separator = space +# path_separator = newline +# +# Use os.pathsep. Default configuration used for new projects. +path_separator = os + + +# set to 'true' to search source files recursively +# in each "version_locations" directory +# new in Alembic version 1.10 +# recursive_version_locations = false + +# the output encoding used when revision files +# are written from script.py.mako +# output_encoding = utf-8 + +# database URL. This is consumed by the user-maintained env.py script only. +# other means of configuring database URLs may be customized within the env.py +# file. +sqlalchemy.url = + + +[post_write_hooks] +# post_write_hooks defines scripts or Python functions that are run +# on newly generated revision scripts. See the documentation for further +# detail and examples + +# format using "black" - use the console_scripts runner, against the "black" entrypoint +# hooks = black +# black.type = console_scripts +# black.entrypoint = black +# black.options = -l 79 REVISION_SCRIPT_FILENAME + +# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module +# hooks = ruff +# ruff.type = module +# ruff.module = ruff +# ruff.options = check --fix REVISION_SCRIPT_FILENAME + +# Alternatively, use the exec runner to execute a binary found on your PATH +# hooks = ruff +# ruff.type = exec +# ruff.executable = ruff +# ruff.options = check --fix REVISION_SCRIPT_FILENAME + +# Logging configuration. This is also consumed by the user-maintained +# env.py script only. +[loggers] +keys = root,sqlalchemy,alembic + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = WARNING +handlers = console +qualname = + +[logger_sqlalchemy] +level = WARNING +handlers = +qualname = sqlalchemy.engine + +[logger_alembic] +level = INFO +handlers = +qualname = alembic + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(levelname)-5.5s [%(name)s] %(message)s +datefmt = %H:%M:%S diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..23d7d67e --- /dev/null +++ b/compose.yaml @@ -0,0 +1,119 @@ +x-api: &api + build: + context: . + dockerfile: Dockerfile + environment: + APP_ENV: lab + SESSION_TTL_SECONDS: 3600 + DATABASE_URL_FILE: /run/secrets/database_url + CACHE_URL_FILE: /run/secrets/cache_url + secrets: + - database_url + - cache_url + depends_on: + migrate: + condition: service_completed_successfully + redis: + condition: service_healthy + expose: + - "8080" + restart: unless-stopped + stop_grace_period: 15s + mem_limit: 512m + cpus: 1.0 + +services: + postgres: + image: postgres:17.6 + environment: + POSTGRES_DB: messenger + POSTGRES_USER: lab2 + POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password + secrets: + - postgres_password + volumes: + - postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U lab2 -d messenger"] + interval: 5s + timeout: 3s + retries: 10 + restart: unless-stopped + cpus: 1.0 + mem_limit: 768m + + redis: + image: redis:8.2.2 + command: + - redis-server + - --appendonly + - "yes" + - --appendfsync + - everysec + volumes: + - redis_data:/data + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 5s + timeout: 3s + retries: 10 + restart: unless-stopped + cpus: 0.5 + mem_limit: 256m + + migrate: + build: + context: . + dockerfile: Dockerfile + command: ["alembic", "upgrade", "head"] + secrets: + - database_url + depends_on: + postgres: + condition: service_healthy + restart: "no" + cpus: 1.0 + mem_limit: 512m + + api-1: + <<: *api + environment: + APP_ENV: lab + SESSION_TTL_SECONDS: 3600 + DATABASE_URL_FILE: /run/secrets/database_url + CACHE_URL_FILE: /run/secrets/cache_url + INSTANCE_ID: api-1 + + api-2: + <<: *api + environment: + APP_ENV: lab + SESSION_TTL_SECONDS: 3600 + DATABASE_URL_FILE: /run/secrets/database_url + CACHE_URL_FILE: /run/secrets/cache_url + INSTANCE_ID: api-2 + + nginx: + image: nginx:1.29-alpine + ports: + - "8080:8080" + volumes: + - ./infra/nginx.conf:/etc/nginx/nginx.conf:ro + depends_on: + - api-1 + - api-2 + restart: unless-stopped + cpus: 0.5 + mem_limit: 256m + +secrets: + postgres_password: + file: ./secrets/postgres_password + database_url: + file: ./secrets/database_url + cache_url: + file: ./secrets/cache_url + +volumes: + postgres_data: + redis_data: diff --git a/infra/nginx.conf b/infra/nginx.conf new file mode 100644 index 00000000..e3000e30 --- /dev/null +++ b/infra/nginx.conf @@ -0,0 +1,36 @@ +events { + worker_connections 1024; +} + +http { + resolver 127.0.0.11 valid=5s ipv6=off; + resolver_timeout 2s; + + upstream api_backend { + zone api_backend 64k; + + server api-1:8080 resolve max_fails=1 fail_timeout=5s; + server api-2:8080 resolve max_fails=1 fail_timeout=5s; + } + + server { + listen 8080; + + location / { + proxy_pass http://api_backend; + proxy_http_version 1.1; + + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + proxy_connect_timeout 2s; + proxy_read_timeout 10s; + proxy_send_timeout 10s; + + proxy_next_upstream error timeout http_502 http_503 http_504; + proxy_next_upstream_tries 2; + } + } +} \ No newline at end of file diff --git a/migrations/README b/migrations/README new file mode 100644 index 00000000..e0d0858f --- /dev/null +++ b/migrations/README @@ -0,0 +1 @@ +Generic single-database configuration with an async dbapi. \ No newline at end of file diff --git a/migrations/env.py b/migrations/env.py new file mode 100644 index 00000000..7125d778 --- /dev/null +++ b/migrations/env.py @@ -0,0 +1,50 @@ +import asyncio + +from alembic import context +from sqlalchemy import pool +from sqlalchemy.ext.asyncio import async_engine_from_config + + +config = context.config + +DATABASE_URL_FILE = "/run/secrets/database_url" + + +def read_database_url() -> str: + with open(DATABASE_URL_FILE, encoding="utf-8") as file: + return file.read().strip() + + +config.set_main_option("sqlalchemy.url", read_database_url()) + +target_metadata = None + + +def do_run_migrations(connection) -> None: + context.configure( + connection=connection, + target_metadata=target_metadata, + ) + + with context.begin_transaction(): + context.run_migrations() + + +async def run_async_migrations() -> None: + connectable = async_engine_from_config( + config.get_section(config.config_ini_section, {}), + prefix="sqlalchemy.", + poolclass=pool.NullPool, + ) + + async with connectable.connect() as connection: + await connection.run_sync(do_run_migrations) + + await connectable.dispose() + + +def run_migrations_online() -> None: + asyncio.run(run_async_migrations()) + + +run_migrations_online() \ No newline at end of file diff --git a/migrations/script.py.mako b/migrations/script.py.mako new file mode 100644 index 00000000..11016301 --- /dev/null +++ b/migrations/script.py.mako @@ -0,0 +1,28 @@ +"""${message} + +Revision ID: ${up_revision} +Revises: ${down_revision | comma,n} +Create Date: ${create_date} + +""" +from typing import Sequence, Union + +from alembic import op +import sqlalchemy as sa +${imports if imports else ""} + +# revision identifiers, used by Alembic. +revision: str = ${repr(up_revision)} +down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)} +branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)} +depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)} + + +def upgrade() -> None: + """Upgrade schema.""" + ${upgrades if upgrades else "pass"} + + +def downgrade() -> None: + """Downgrade schema.""" + ${downgrades if downgrades else "pass"} diff --git a/migrations/versions/b3a91c0e7d42_message_idempotency.py b/migrations/versions/b3a91c0e7d42_message_idempotency.py new file mode 100644 index 00000000..1a794894 --- /dev/null +++ b/migrations/versions/b3a91c0e7d42_message_idempotency.py @@ -0,0 +1,61 @@ +"""Message idempotency for lab 3. + +Revision ID: b3a91c0e7d42 +Revises: f7c51e1e945b +""" + +from alembic import op +import sqlalchemy as sa + + +revision = "b3a91c0e7d42" +down_revision = "f7c51e1e945b" +branch_labels = None +depends_on = None + + +def upgrade() -> None: + op.create_table( + "message_idempotency", + sa.Column("user_id", sa.Uuid(), nullable=False), + sa.Column("chat_id", sa.Uuid(), nullable=False), + sa.Column("key", sa.String(length=128), nullable=False), + sa.Column("request_hash", sa.String(length=64), nullable=False), + sa.Column("message_id", sa.Uuid(), nullable=False), + sa.Column( + "created_at", + sa.DateTime(timezone=True), + server_default=sa.text("CURRENT_TIMESTAMP"), + nullable=False, + ), + sa.ForeignKeyConstraint( + ["user_id"], + ["users.id"], + ondelete="CASCADE", + ), + sa.ForeignKeyConstraint( + ["chat_id"], + ["chats.id"], + ondelete="CASCADE", + ), + sa.ForeignKeyConstraint( + ["message_id"], + ["messages.id"], + ondelete="CASCADE", + ), + sa.PrimaryKeyConstraint("user_id", "chat_id", "key"), + ) + + op.create_index( + "ix_message_idempotency_created_at", + "message_idempotency", + ["created_at"], + ) + + +def downgrade() -> None: + op.drop_index( + "ix_message_idempotency_created_at", + table_name="message_idempotency", + ) + op.drop_table("message_idempotency") \ No newline at end of file diff --git a/migrations/versions/f7c51e1e945b_initial_schema.py b/migrations/versions/f7c51e1e945b_initial_schema.py new file mode 100644 index 00000000..5bc1512b --- /dev/null +++ b/migrations/versions/f7c51e1e945b_initial_schema.py @@ -0,0 +1,110 @@ +"""initial schema + +Revision ID: f7c51e1e945b +Revises: +Create Date: 2026-10-07 18:33:37.771593 + +""" + +from typing import Sequence, Union + +from alembic import op +import sqlalchemy as sa + + +# revision identifiers, used by Alembic. +revision: str = "f7c51e1e945b" +down_revision: Union[str, Sequence[str], None] = None +branch_labels: Union[str, Sequence[str], None] = None +depends_on: Union[str, Sequence[str], None] = None + + +def upgrade() -> None: + op.create_table( + "users", + sa.Column("id", sa.Uuid(), nullable=False), + sa.Column("username", sa.String(length=32), nullable=False), + sa.Column("display_name", sa.String(length=100), nullable=False), + sa.Column("password_hash", sa.Text(), nullable=False), + sa.Column( + "created_at", + sa.DateTime(timezone=True), + server_default=sa.text("CURRENT_TIMESTAMP"), + nullable=False, + ), + sa.PrimaryKeyConstraint("id"), + sa.UniqueConstraint("username", name="uq_users_username"), + ) + + op.create_table( + "chats", + sa.Column("id", sa.Uuid(), nullable=False), + sa.Column("title", sa.String(length=100), nullable=False), + sa.Column( + "created_at", + sa.DateTime(timezone=True), + server_default=sa.text("CURRENT_TIMESTAMP"), + nullable=False, + ), + sa.PrimaryKeyConstraint("id"), + ) + + op.create_table( + "chat_members", + sa.Column("chat_id", sa.Uuid(), nullable=False), + sa.Column("user_id", sa.Uuid(), nullable=False), + sa.ForeignKeyConstraint( + ["chat_id"], + ["chats.id"], + ondelete="CASCADE", + ), + sa.ForeignKeyConstraint( + ["user_id"], + ["users.id"], + ondelete="CASCADE", + ), + sa.PrimaryKeyConstraint("chat_id", "user_id"), + ) + + op.create_table( + "messages", + sa.Column("id", sa.Uuid(), nullable=False), + sa.Column("chat_id", sa.Uuid(), nullable=False), + sa.Column("sender_id", sa.Uuid(), nullable=False), + sa.Column("text", sa.String(length=4000), nullable=False), + sa.Column( + "created_at", + sa.DateTime(timezone=True), + server_default=sa.text("CURRENT_TIMESTAMP"), + nullable=False, + ), + sa.ForeignKeyConstraint( + ["chat_id"], + ["chats.id"], + ondelete="CASCADE", + ), + sa.ForeignKeyConstraint( + ["sender_id"], + ["users.id"], + ondelete="RESTRICT", + ), + sa.PrimaryKeyConstraint("id"), + ) + + op.create_index( + "ix_messages_chat_created_id", + "messages", + ["chat_id", "created_at", "id"], + unique=False, + ) + + +def downgrade() -> None: + op.drop_index( + "ix_messages_chat_created_id", + table_name="messages", + ) + op.drop_table("messages") + op.drop_table("chat_members") + op.drop_table("chats") + op.drop_table("users") \ No newline at end of file diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..2f27f572 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,20 @@ +annotated-doc==0.0.5 +annotated-types==0.8.0 +anyio==4.15.1 +click==8.5.0 +fastapi==0.141.1 +h11==0.16.0 +idna==3.20 +pydantic==2.13.5 +pydantic_core==2.46.5 +starlette==1.7.0 +typing-inspection==0.4.4 +typing_extensions==4.16.0 +uvicorn==0.53.0 +SQLAlchemy==2.1.4 +asyncpg==0.32.0 +alembic==1.20.0 +greenlet==3.5.6 + +argon2-cffi==25.1.0 +redis==7.0.1 diff --git a/scripts/bootstrap.sh b/scripts/bootstrap.sh new file mode 100755 index 00000000..33ebc3fe --- /dev/null +++ b/scripts/bootstrap.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +set -euo pipefail + +cd "$(dirname "$0")/.." + +mkdir -p secrets +chmod 700 secrets +umask 077 + +if [[ ! -f secrets/postgres_password ]]; then + python3 -c 'import secrets; print(secrets.token_hex(24))' > secrets/postgres_password +fi + +if [[ ! -f secrets/database_url ]]; then + PASSWORD="$(cat secrets/postgres_password)" + printf 'postgresql+asyncpg://lab2:%s@postgres:5432/messenger\n' "$PASSWORD" > secrets/database_url +fi + +if [[ ! -f secrets/cache_url ]]; then + printf 'redis://redis:6379/0\n' > secrets/cache_url +fi + +chmod 644 secrets/postgres_password secrets/database_url secrets/cache_url + +if [[ ! -f .env ]]; then + cp .env.example .env +fi + +docker compose config --quiet \ No newline at end of file diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..7ef0d531 --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,4 @@ +#!/usr/bin/env bash +set -euo pipefail + +docker compose restart postgres redis api-1 api-2 \ No newline at end of file diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100755 index 00000000..d1e8633b --- /dev/null +++ b/scripts/stop-one.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +set -euo pipefail + +: "${TARGET_INSTANCE_ID:?}" + +case "$TARGET_INSTANCE_ID" in + api-1|api-2) + docker compose stop "$TARGET_INSTANCE_ID" + ;; + *) + echo "Unknown instance: $TARGET_INSTANCE_ID" >&2 + exit 1 + ;; +esac \ No newline at end of file diff --git a/src/__init__.py b/src/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/src/cursor.py b/src/cursor.py new file mode 100644 index 00000000..23dfb48b --- /dev/null +++ b/src/cursor.py @@ -0,0 +1,86 @@ +import base64 +import binascii +import json +from datetime import datetime +from uuid import UUID + + +def encode_cursor( + chat_id: UUID, + created_at: datetime, + message_id: UUID, +) -> str: + data = { + "chat_id": str(chat_id), + "created_at": created_at.isoformat(), + "message_id": str(message_id), + } + + raw = json.dumps( + data, + separators=(",", ":"), + ).encode("utf-8") + + return base64.urlsafe_b64encode(raw).decode("ascii") + + +def decode_cursor(cursor: str) -> tuple[UUID, datetime, UUID]: + try: + raw = base64.urlsafe_b64decode(cursor.encode("ascii")) + + data = json.loads(raw.decode("utf-8")) + + if not isinstance(data, dict): + raise ValueError("Invalid cursor") + + if set(data.keys()) != { + "chat_id", + "created_at", + "message_id", + }: + raise ValueError("Invalid cursor") + + chat_id = UUID(data["chat_id"]) + created_at = datetime.fromisoformat(data["created_at"]) + message_id = UUID(data["message_id"]) + + if created_at.tzinfo is None or created_at.utcoffset() is None: + raise ValueError("Invalid cursor") + + return chat_id, created_at, message_id + + except ( + ValueError, + KeyError, + TypeError, + UnicodeError, + binascii.Error, + json.JSONDecodeError, + ) as exc: + raise ValueError("Invalid cursor") from exc + + +def encode_chat_cursor(user_id: UUID, created_at: datetime, chat_id: UUID) -> str: + data = { + "user_id": str(user_id), + "created_at": created_at.isoformat(), + "chat_id": str(chat_id), + } + raw = json.dumps(data, separators=(",", ":")).encode("utf-8") + return base64.urlsafe_b64encode(raw).decode("ascii") + + +def decode_chat_cursor(cursor: str) -> tuple[UUID, datetime, UUID]: + try: + raw = base64.b64decode(cursor.encode("ascii"), altchars=b"-_", validate=True) + data = json.loads(raw.decode("utf-8")) + if not isinstance(data, dict) or set(data) != {"user_id", "created_at", "chat_id"}: + raise ValueError("Invalid cursor") + user_id = UUID(data["user_id"]) + created_at = datetime.fromisoformat(data["created_at"]) + chat_id = UUID(data["chat_id"]) + if created_at.tzinfo is None or created_at.utcoffset() is None: + raise ValueError("Invalid cursor") + return user_id, created_at, chat_id + except (ValueError, TypeError, KeyError, UnicodeError, binascii.Error, json.JSONDecodeError) as exc: + raise ValueError("Invalid cursor") from exc diff --git a/src/database.py b/src/database.py new file mode 100644 index 00000000..95b01ffb --- /dev/null +++ b/src/database.py @@ -0,0 +1,57 @@ +from collections.abc import AsyncIterator + +import socket + +from sqlalchemy import text +from sqlalchemy.exc import SQLAlchemyError +from sqlalchemy.ext.asyncio import ( + AsyncSession, + async_sessionmaker, + create_async_engine, +) + + +DATABASE_URL_FILE = "/run/secrets/database_url" + +POOL_SIZE = 5 +MAX_OVERFLOW = 5 +POOL_TIMEOUT_SECONDS = 5 +DB_CONNECT_TIMEOUT_SECONDS = 5 + + +def read_database_url() -> str: + with open(DATABASE_URL_FILE, encoding="utf-8") as file: + return file.read().strip() + + +database_url = read_database_url() + +engine = create_async_engine( + database_url, + pool_size=POOL_SIZE, + max_overflow=MAX_OVERFLOW, + pool_timeout=POOL_TIMEOUT_SECONDS, + connect_args={ + "timeout": DB_CONNECT_TIMEOUT_SECONDS, + }, + pool_pre_ping=True, +) + +SessionFactory = async_sessionmaker( + bind=engine, + expire_on_commit=False, +) + + +async def get_db_session() -> AsyncIterator[AsyncSession]: + async with SessionFactory() as session: + yield session + + +async def ping_database() -> bool: + try: + async with engine.connect() as connection: + await connection.execute(text("SELECT 1")) + return True + except (SQLAlchemyError, OSError): + return False \ No newline at end of file diff --git a/src/errors.py b/src/errors.py new file mode 100644 index 00000000..8b853205 --- /dev/null +++ b/src/errors.py @@ -0,0 +1,12 @@ +class APIError(Exception): + def __init__( + self, + status_code: int, + code: str, + message: str, + headers: dict[str, str] | None = None, + ): + self.status_code = status_code + self.code = code + self.message = message + self.headers = headers \ No newline at end of file diff --git a/src/main.py b/src/main.py new file mode 100644 index 00000000..0295542b --- /dev/null +++ b/src/main.py @@ -0,0 +1,528 @@ +from datetime import datetime, timedelta, timezone +from uuid import UUID, uuid4 +import os +import re +import base64 +import binascii + +from fastapi import Depends, FastAPI, Request, Header +from fastapi.exceptions import RequestValidationError +from fastapi.responses import JSONResponse +from fastapi.security import ( + HTTPAuthorizationCredentials, + HTTPBearer, +) +from sqlalchemy.exc import IntegrityError, SQLAlchemyError +from sqlalchemy.ext.asyncio import AsyncSession +from starlette.exceptions import HTTPException as StarletteHTTPException +from contextlib import asynccontextmanager + +from src.database import engine, get_db_session, ping_database +from src.errors import APIError +from src.models import CreateUser, SessionResponse, User, CreateChat, Chat, ChatPage, CreateMessage, Message, MessagePage +from src.repositories import ( + create_chat, + list_chats, + create_user as create_user_in_db, + get_user_by_id, + get_chat_by_id, + get_user_credentials_by_username, + create_message, + get_messages, +) +from src.security import verify_password +from src.sessions import ( + create_session, + delete_session, + get_session_user_id, + ping_session_store, + redis_client, +) + + +@asynccontextmanager +async def lifespan(app: FastAPI): + yield + await redis_client.aclose() + await engine.dispose() + + +app = FastAPI(lifespan=lifespan) +INSTANCE_ID = os.getenv("INSTANCE_ID") or str(uuid4()) + +bearer_security = HTTPBearer(auto_error=False) + + +async def get_current_user( + credentials: HTTPAuthorizationCredentials | None = Depends(bearer_security), + session: AsyncSession = Depends(get_db_session), +) -> User: + if credentials is None or credentials.scheme.lower() != "bearer": + raise APIError( + status_code=401, + code="unauthorized", + message="Unauthorized", + headers={ + "WWW-Authenticate": "Bearer", + }, + ) + + user_id = await get_session_user_id(credentials.credentials) + + if user_id is None: + raise APIError( + status_code=401, + code="unauthorized", + message="Unauthorized", + headers={ + "WWW-Authenticate": "Bearer", + }, + ) + + user = await get_user_by_id(session, user_id) + + if user is None: + raise APIError( + status_code=401, + code="unauthorized", + message="Unauthorized", + headers={ + "WWW-Authenticate": "Bearer", + }, + ) + + return user + + +@app.middleware("http") +async def request_middleware(request: Request, call_next): + request_id = str(uuid4()) + request.state.request_id = request_id + + if request.method in {"POST", "PUT", "PATCH"}: + content_type = request.headers.get("content-type") + + if content_type is not None: + media_type = content_type.split(";", 1)[0].strip().lower() + + if media_type != "application/json": + return JSONResponse( + status_code=415, + content={ + "error": { + "code": "unsupported_media_type", + "message": "Unsupported media type", + "request_id": request_id, + } + }, + headers={ + "X-Request-Id": request_id, + "X-Instance-Id": INSTANCE_ID, + }, + ) + + response = await call_next(request) + + response.headers["X-Request-Id"] = request_id + response.headers["X-Instance-Id"] = INSTANCE_ID + + return response + + +@app.exception_handler(RequestValidationError) +async def validation_exception_handler( + request: Request, + exc: RequestValidationError, +): + request_id = request.state.request_id + + return JSONResponse( + status_code=400, + content={ + "error": { + "code": "invalid_request", + "message": "Invalid request", + "request_id": request_id, + } + }, + ) + + +@app.exception_handler(APIError) +async def api_error_handler(request: Request, exc: APIError): + request_id = request.state.request_id + + return JSONResponse( + status_code=exc.status_code, + content={ + "error": { + "code": exc.code, + "message": exc.message, + "request_id": request_id, + } + }, + headers=exc.headers, + ) + + +@app.exception_handler(SQLAlchemyError) +async def database_exception_handler( + request: Request, + exc: SQLAlchemyError, +): + request_id = request.state.request_id + + return JSONResponse( + status_code=503, + content={ + "error": { + "code": "unavailable", + "message": "Database unavailable", + "request_id": request_id, + } + }, + ) + + +@app.exception_handler(OSError) +async def database_connection_exception_handler( + request: Request, + exc: OSError, +): + request_id = request.state.request_id + + return JSONResponse( + status_code=503, + content={ + "error": { + "code": "unavailable", + "message": "Database unavailable", + "request_id": request_id, + } + }, + ) + + +@app.exception_handler(StarletteHTTPException) +async def http_exception_handler( + request: Request, + exc: StarletteHTTPException, +): + request_id = request.state.request_id + + if exc.status_code == 404: + code = "not_found" + message = "Not found" + else: + code = "invalid_request" + message = "Invalid request" + + return JSONResponse( + status_code=exc.status_code, + content={ + "error": { + "code": code, + "message": message, + "request_id": request_id, + } + }, + headers=exc.headers, + ) + + +@app.exception_handler(Exception) +async def unexpected_exception_handler( + request: Request, + exc: Exception, +): + request_id = request.state.request_id + + return JSONResponse( + status_code=500, + content={ + "error": { + "code": "internal_error", + "message": "Internal server error", + "request_id": request_id, + } + }, + ) + + +@app.get("/health/live") +async def health_live(): + return {"status": "ok"} + + +@app.get("/health/ready") +async def health_ready(): + database_ready = await ping_database() + session_store_ready = await ping_session_store() + + if not database_ready or not session_store_ready: + raise APIError( + status_code=503, + code="unavailable", + message="Service dependencies unavailable", + ) + + return {"status": "ok"} + + +@app.post("/api/v1/users", response_model=User, status_code=201) +async def create_user( + data: CreateUser, + session: AsyncSession = Depends(get_db_session), +): + try: + async with session.begin(): + return await create_user_in_db(session, data) + + except IntegrityError as exc: + raise APIError( + status_code=409, + code="conflict", + message="Username already exists", + ) from exc + + +@app.get("/api/v1/users/me", response_model=User) +async def get_me( + current_user: User = Depends(get_current_user), +): + return current_user + + +@app.post( + "/api/v1/auth/sessions", + response_model=SessionResponse, + status_code=201, +) +async def create_auth_session( + authorization: str | None = Header(default=None), + session: AsyncSession = Depends(get_db_session), +): + credentials = None + if authorization is not None: + scheme, separator, encoded = authorization.partition(" ") + if separator and scheme.lower() == "basic": + try: + decoded = base64.b64decode(encoded.strip(), validate=True).decode("utf-8") + if ":" in decoded: + credentials = decoded.split(":", 1) + except (ValueError, UnicodeError, binascii.Error): + pass + if credentials is None: + raise APIError( + status_code=401, + code="unauthorized", + message="Unauthorized", + headers={ + "WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"', + }, + ) + + user_credentials = await get_user_credentials_by_username( + session, + credentials[0], + ) + + if user_credentials is None: + raise APIError( + status_code=401, + code="unauthorized", + message="Unauthorized", + headers={ + "WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"', + }, + ) + + if not verify_password( + user_credentials.password_hash, + credentials[1], + ): + raise APIError( + status_code=401, + code="unauthorized", + message="Unauthorized", + headers={ + "WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"', + }, + ) + + user = User( + id=user_credentials.id, + username=user_credentials.username, + display_name=user_credentials.display_name, + created_at=user_credentials.created_at, + ) + + token, ttl = await create_session(user.id) + + expires_at = datetime.now(timezone.utc) + timedelta(seconds=ttl) + + return SessionResponse( + token=token, + token_type="Bearer", + expires_at=expires_at, + user=user, + ) + + +@app.delete( + "/api/v1/auth/sessions/current", + status_code=204, +) +async def delete_current_session( + credentials: HTTPAuthorizationCredentials | None = Depends(bearer_security), + current_user: User = Depends(get_current_user), +): + await delete_session(credentials.credentials) + + +@app.post( + "/api/v1/chats", + response_model=Chat, + status_code=201, +) +async def create_chat_endpoint( + data: CreateChat, + current_user: User = Depends(get_current_user), + session: AsyncSession = Depends(get_db_session), +) -> Chat: + try: + chat = await create_chat( + session=session, + data=data, + current_user_id=current_user.id, + ) + await session.commit() + except Exception: + await session.rollback() + raise + + return chat + + +@app.get( + "/api/v1/chats", + response_model=ChatPage, +) +async def get_chats( + limit: int = 50, + cursor: str | None = None, + current_user: User = Depends(get_current_user), + session: AsyncSession = Depends(get_db_session), +) -> ChatPage: + if limit < 1 or limit > 100: + raise APIError( + status_code=400, + code="invalid_request", + message="Limit must be between 1 and 100", + ) + + return await list_chats( + session=session, + current_user_id=current_user.id, + limit=limit, + cursor=cursor, + ) + + +@app.get( + "/api/v1/chats/{chat_id}", + response_model=Chat, +) +async def get_chat_endpoint( + chat_id: UUID, + current_user: User = Depends(get_current_user), + session: AsyncSession = Depends(get_db_session), +) -> Chat: + chat = await get_chat_by_id( + session=session, + chat_id=chat_id, + current_user_id=current_user.id, + ) + + if chat is None: + raise APIError( + status_code=404, + code="not_found", + message="Chat not found", + ) + + return chat + + +@app.post( + "/api/v1/chats/{chat_id}/messages", + response_model=Message, + status_code=201, +) +async def create_message_endpoint( + chat_id: UUID, + data: CreateMessage, + idempotency_key: str | None = Header( + default=None, + alias="Idempotency-Key", + ), + current_user: User = Depends(get_current_user), + session: AsyncSession = Depends(get_db_session), +) -> Message: + + if ( + idempotency_key is None + or re.fullmatch( + r"[A-Za-z0-9._:-]{1,128}", + idempotency_key, + ) is None + ): + raise APIError( + status_code=400, + code="invalid_request", + message="Invalid or missing Idempotency-Key", + ) + + try: + message = await create_message( + session=session, + chat_id=chat_id, + current_user_id=current_user.id, + data=data, + idempotency_key=idempotency_key, + ) + + await session.commit() + + except Exception: + await session.rollback() + raise + + return message + + +@app.get( + "/api/v1/chats/{chat_id}/messages", + response_model=MessagePage, +) +async def get_messages_endpoint( + chat_id: UUID, + limit: int = 50, + cursor: str | None = None, + current_user: User = Depends(get_current_user), + session: AsyncSession = Depends(get_db_session), +) -> MessagePage: + if limit < 1 or limit > 100: + raise APIError( + status_code=400, + code="invalid_request", + message="Limit must be between 1 and 100", + ) + + return await get_messages( + session=session, + chat_id=chat_id, + current_user_id=current_user.id, + limit=limit, + cursor=cursor, + ) diff --git a/src/models.py b/src/models.py new file mode 100644 index 00000000..5f2c2991 --- /dev/null +++ b/src/models.py @@ -0,0 +1,118 @@ +from datetime import datetime +from uuid import UUID + +from pydantic import BaseModel, ConfigDict, Field, field_validator + + +class CreateUser(BaseModel): + model_config = ConfigDict(extra="forbid") + + username: str = Field( + min_length=3, + max_length=32, + pattern=r"^[a-z0-9_]+$", + ) + + display_name: str = Field( + min_length=1, + max_length=100, + ) + + password: str = Field( + min_length=12, + max_length=128, + ) + + @field_validator("display_name") + @classmethod + def validate_display_name(cls, value: str) -> str: + if not value.strip(): + raise ValueError("Display name must not be blank") + + return value + + +class User(BaseModel): + id: UUID + username: str + display_name: str + created_at: datetime + + +class SessionResponse(BaseModel): + token: str + token_type: str + expires_at: datetime + user: User + + +class CreateChat(BaseModel): + model_config = ConfigDict(extra="forbid") + + title: str = Field( + min_length=1, + max_length=100, + ) + + member_ids: list[UUID] = Field( + min_length=1, + max_length=100, + ) + + @field_validator("title") + @classmethod + def validate_title(cls, value: str) -> str: + if not value.strip(): + raise ValueError("Chat title must not be blank") + + return value + + @field_validator("member_ids") + @classmethod + def validate_member_ids(cls, value: list[UUID]) -> list[UUID]: + if len(value) != len(set(value)): + raise ValueError("Member IDs must be unique") + + return value + + +class Chat(BaseModel): + id: UUID + title: str + member_ids: list[UUID] + created_at: datetime + + +class ChatPage(BaseModel): + items: list[Chat] + next_cursor: str | None + + +class CreateMessage(BaseModel): + model_config = ConfigDict(extra="forbid") + + text: str = Field( + min_length=1, + max_length=4000, + ) + + @field_validator("text") + @classmethod + def validate_text(cls, value: str) -> str: + if not value.strip(): + raise ValueError("Message text must not be blank") + + return value + + +class Message(BaseModel): + id: UUID + chat_id: UUID + sender_id: UUID + text: str + created_at: datetime + + +class MessagePage(BaseModel): + items: list[Message] + next_cursor: str | None \ No newline at end of file diff --git a/src/repositories.py b/src/repositories.py new file mode 100644 index 00000000..f0020c69 --- /dev/null +++ b/src/repositories.py @@ -0,0 +1,655 @@ +from uuid import UUID, uuid4 +import hashlib +import json + +from sqlalchemy import text +from sqlalchemy.ext.asyncio import AsyncSession + +from src.models import Chat, ChatPage, CreateChat, CreateUser, User, CreateMessage, Message, MessagePage +from src.security import hash_password +from src.errors import APIError +from src.cursor import decode_cursor, encode_cursor, decode_chat_cursor, encode_chat_cursor + + +async def create_user( + session: AsyncSession, + data: CreateUser, +) -> User: + user_id = uuid4() + password_hash = hash_password(data.password) + + result = await session.execute( + text( + """ + INSERT INTO users ( + id, + username, + display_name, + password_hash + ) + VALUES ( + :id, + :username, + :display_name, + :password_hash + ) + RETURNING + id, + username, + display_name, + created_at + """ + ), + { + "id": user_id, + "username": data.username, + "display_name": data.display_name, + "password_hash": password_hash, + }, + ) + + row = result.one() + + return User( + id=UUID(str(row.id)), + username=row.username, + display_name=row.display_name, + created_at=row.created_at, + ) + +async def get_user_credentials_by_username( + session: AsyncSession, + username: str, +): + result = await session.execute( + text( + """ + SELECT + id, + username, + display_name, + password_hash, + created_at + FROM users + WHERE username = :username + """ + ), + { + "username": username, + }, + ) + + return result.one_or_none() + + +async def get_user_by_id( + session: AsyncSession, + user_id: UUID, +) -> User | None: + result = await session.execute( + text( + """ + SELECT + id, + username, + display_name, + created_at + FROM users + WHERE id = :user_id + """ + ), + { + "user_id": user_id, + }, + ) + + row = result.one_or_none() + + if row is None: + return None + + return User( + id=UUID(str(row.id)), + username=row.username, + display_name=row.display_name, + created_at=row.created_at, + ) + + +async def create_chat( + session: AsyncSession, + data: CreateChat, + current_user_id: UUID, +) -> Chat: + if current_user_id not in data.member_ids: + raise APIError( + status_code=400, + code="invalid_request", + message="Current user must be a chat member", + ) + + users_result = await session.execute( + text( + """ + SELECT id + FROM users + WHERE id = ANY(:member_ids) + """ + ), + { + "member_ids": data.member_ids, + }, + ) + + existing_user_ids = { + UUID(str(row.id)) + for row in users_result + } + + if existing_user_ids != set(data.member_ids): + raise APIError( + status_code=400, + code="invalid_request", + message="Unknown chat member", + ) + + chat_id = uuid4() + + chat_result = await session.execute( + text( + """ + INSERT INTO chats ( + id, + title + ) + VALUES ( + :id, + :title + ) + RETURNING + id, + title, + created_at + """ + ), + { + "id": chat_id, + "title": data.title, + }, + ) + + chat_row = chat_result.one() + + for member_id in data.member_ids: + await session.execute( + text( + """ + INSERT INTO chat_members ( + chat_id, + user_id + ) + VALUES ( + :chat_id, + :user_id + ) + """ + ), + { + "chat_id": chat_id, + "user_id": member_id, + }, + ) + + return Chat( + id=UUID(str(chat_row.id)), + title=chat_row.title, + member_ids=data.member_ids, + created_at=chat_row.created_at, + ) + + +async def get_chat_by_id( + session: AsyncSession, + chat_id: UUID, + current_user_id: UUID, +) -> Chat | None: + chat_result = await session.execute( + text( + """ + SELECT + c.id, + c.title, + c.created_at + FROM chats AS c + JOIN chat_members AS cm + ON cm.chat_id = c.id + WHERE c.id = :chat_id + AND cm.user_id = :current_user_id + """ + ), + { + "chat_id": chat_id, + "current_user_id": current_user_id, + }, + ) + + chat_row = chat_result.one_or_none() + + if chat_row is None: + return None + + members_result = await session.execute( + text( + """ + SELECT user_id + FROM chat_members + WHERE chat_id = :chat_id + ORDER BY user_id + """ + ), + { + "chat_id": chat_id, + }, + ) + + member_ids = [ + UUID(str(row.user_id)) + for row in members_result + ] + + return Chat( + id=UUID(str(chat_row.id)), + title=chat_row.title, + member_ids=member_ids, + created_at=chat_row.created_at, + ) + + +async def list_chats( + session: AsyncSession, + current_user_id: UUID, + limit: int, + cursor: str | None = None, +) -> ChatPage: + cursor_created_at = None + cursor_chat_id = None + if cursor is not None: + try: + cursor_user_id, cursor_created_at, cursor_chat_id = decode_chat_cursor(cursor) + except ValueError as exc: + raise APIError(status_code=400, code="invalid_request", message="Invalid cursor") from exc + if cursor_user_id != current_user_id: + raise APIError(status_code=400, code="invalid_request", message="Invalid cursor") + + result = await session.execute( + text( + """ + SELECT c.id, c.title, c.created_at + FROM chats AS c + JOIN chat_members AS cm ON cm.chat_id = c.id + WHERE cm.user_id = :current_user_id + AND ( + CAST(:cursor_created_at AS timestamptz) IS NULL + OR (c.created_at, c.id) > ( + CAST(:cursor_created_at AS timestamptz), + CAST(:cursor_chat_id AS uuid) + ) + ) + ORDER BY c.created_at, c.id + LIMIT :fetch_limit + """ + ), + { + "current_user_id": current_user_id, + "cursor_created_at": cursor_created_at, + "cursor_chat_id": cursor_chat_id, + "fetch_limit": limit + 1, + }, + ) + rows = result.all() + has_more = len(rows) > limit + page_rows = rows[:limit] + items = [] + for chat_row in page_rows: + members_result = await session.execute( + text( + """ + SELECT user_id + FROM chat_members + WHERE chat_id = :chat_id + ORDER BY user_id + """ + ), + {"chat_id": chat_row.id}, + ) + items.append( + Chat( + id=UUID(str(chat_row.id)), + title=chat_row.title, + member_ids=[UUID(str(row.user_id)) for row in members_result], + created_at=chat_row.created_at, + ) + ) + next_cursor = None + if has_more: + last = page_rows[-1] + next_cursor = encode_chat_cursor( + current_user_id, last.created_at, UUID(str(last.id)) + ) + return ChatPage(items=items, next_cursor=next_cursor) + + +async def create_message( + session: AsyncSession, + chat_id: UUID, + current_user_id: UUID, + data: CreateMessage, + idempotency_key: str, +) -> Message: + membership_result = await session.execute( + text(""" + SELECT 1 + FROM chat_members + WHERE chat_id = :chat_id + AND user_id = :user_id + """), + { + "chat_id": chat_id, + "user_id": current_user_id, + }, + ) + + if membership_result.scalar_one_or_none() is None: + raise APIError( + status_code=404, + code="not_found", + message="Chat not found", + ) + + canonical_body = json.dumps( + {"text": data.text}, + sort_keys=True, + ensure_ascii=False, + separators=(",", ":"), + ) + + request_hash = hashlib.sha256( + canonical_body.encode("utf-8") + ).hexdigest() + + scope = ( + f"{current_user_id}:POST:" + f"/api/v1/chats/{chat_id}/messages:" + f"{idempotency_key}" + ) + + await session.execute( + text(""" + SELECT pg_advisory_xact_lock( + hashtextextended(:scope, 0) + ) + """), + {"scope": scope}, + ) + + await session.execute( + text(""" + DELETE FROM message_idempotency + WHERE user_id = :user_id + AND chat_id = :chat_id + AND key = :key + AND created_at <= + clock_timestamp() - INTERVAL '24 hours' + """), + { + "user_id": current_user_id, + "chat_id": chat_id, + "key": idempotency_key, + }, + ) + + existing_result = await session.execute( + text(""" + SELECT + i.request_hash, + m.id, + m.chat_id, + m.sender_id, + m.text, + m.created_at + FROM message_idempotency AS i + JOIN messages AS m + ON m.id = i.message_id + WHERE i.user_id = :user_id + AND i.chat_id = :chat_id + AND i.key = :key + """), + { + "user_id": current_user_id, + "chat_id": chat_id, + "key": idempotency_key, + }, + ) + + existing = existing_result.one_or_none() + + if existing is not None: + if existing.request_hash != request_hash: + raise APIError( + status_code=409, + code="conflict", + message=( + "Idempotency key already used " + "with different request body" + ), + ) + + return Message( + id=UUID(str(existing.id)), + chat_id=UUID(str(existing.chat_id)), + sender_id=UUID(str(existing.sender_id)), + text=existing.text, + created_at=existing.created_at, + ) + + message_id = uuid4() + + message_result = await session.execute( + text(""" + INSERT INTO messages ( + id, + chat_id, + sender_id, + text + ) + VALUES ( + :id, + :chat_id, + :sender_id, + :text + ) + RETURNING + id, + chat_id, + sender_id, + text, + created_at + """), + { + "id": message_id, + "chat_id": chat_id, + "sender_id": current_user_id, + "text": data.text, + }, + ) + + row = message_result.one() + + await session.execute( + text(""" + INSERT INTO message_idempotency ( + user_id, + chat_id, + key, + request_hash, + message_id + ) + VALUES ( + :user_id, + :chat_id, + :key, + :request_hash, + :message_id + ) + """), + { + "user_id": current_user_id, + "chat_id": chat_id, + "key": idempotency_key, + "request_hash": request_hash, + "message_id": message_id, + }, + ) + + return Message( + id=UUID(str(row.id)), + chat_id=UUID(str(row.chat_id)), + sender_id=UUID(str(row.sender_id)), + text=row.text, + created_at=row.created_at, + ) + + +async def get_messages( + session: AsyncSession, + chat_id: UUID, + current_user_id: UUID, + limit: int, + cursor: str | None, +) -> MessagePage: + membership_result = await session.execute( + text( + """ + SELECT 1 + FROM chat_members + WHERE chat_id = :chat_id + AND user_id = :current_user_id + """ + ), + { + "chat_id": chat_id, + "current_user_id": current_user_id, + }, + ) + + if membership_result.scalar_one_or_none() is None: + raise APIError( + status_code=404, + code="not_found", + message="Chat not found", + ) + + cursor_created_at = None + cursor_message_id = None + + if cursor is not None: + try: + ( + cursor_chat_id, + cursor_created_at, + cursor_message_id, + ) = decode_cursor(cursor) + except ValueError: + raise APIError( + status_code=400, + code="invalid_request", + message="Invalid cursor", + ) + + if cursor_chat_id != chat_id: + raise APIError( + status_code=400, + code="invalid_request", + message="Cursor belongs to another chat", + ) + + if cursor is None: + messages_result = await session.execute( + text( + """ + SELECT + id, + chat_id, + sender_id, + text, + created_at + FROM messages + WHERE chat_id = :chat_id + ORDER BY created_at, id + LIMIT :fetch_limit + """ + ), + { + "chat_id": chat_id, + "fetch_limit": limit + 1, + }, + ) + else: + messages_result = await session.execute( + text( + """ + SELECT + id, + chat_id, + sender_id, + text, + created_at + FROM messages + WHERE chat_id = :chat_id + AND (created_at, id) > ( + :cursor_created_at, + :cursor_message_id + ) + ORDER BY created_at, id + LIMIT :fetch_limit + """ + ), + { + "chat_id": chat_id, + "cursor_created_at": cursor_created_at, + "cursor_message_id": cursor_message_id, + "fetch_limit": limit + 1, + }, + ) + + rows = messages_result.all() + + has_more = len(rows) > limit + rows = rows[:limit] + + items = [ + Message( + id=UUID(str(row.id)), + chat_id=UUID(str(row.chat_id)), + sender_id=UUID(str(row.sender_id)), + text=row.text, + created_at=row.created_at, + ) + for row in rows + ] + + next_cursor = None + + if has_more: + last_message = items[-1] + + next_cursor = encode_cursor( + chat_id=chat_id, + created_at=last_message.created_at, + message_id=last_message.id, + ) + + return MessagePage( + items=items, + next_cursor=next_cursor, + ) diff --git a/src/security.py b/src/security.py new file mode 100644 index 00000000..0afbbf1a --- /dev/null +++ b/src/security.py @@ -0,0 +1,16 @@ +from argon2 import PasswordHasher +from argon2.exceptions import VerifyMismatchError + + +password_hasher = PasswordHasher() + + +def hash_password(password: str) -> str: + return password_hasher.hash(password) + + +def verify_password(password_hash: str, password: str) -> bool: + try: + return password_hasher.verify(password_hash, password) + except VerifyMismatchError: + return False \ No newline at end of file diff --git a/src/sessions.py b/src/sessions.py new file mode 100644 index 00000000..6c522cbe --- /dev/null +++ b/src/sessions.py @@ -0,0 +1,87 @@ +import os +import secrets +from uuid import UUID + +from redis.asyncio import Redis +from redis.exceptions import RedisError + +from src.errors import APIError + + +CACHE_URL_FILE = "/run/secrets/cache_url" +DEFAULT_SESSION_TTL_SECONDS = 3600 + + +def read_cache_url() -> str: + with open(CACHE_URL_FILE, encoding="utf-8") as file: + return file.read().strip() + + +def get_session_ttl_seconds() -> int: + return int( + os.getenv( + "SESSION_TTL_SECONDS", + str(DEFAULT_SESSION_TTL_SECONDS), + ) + ) + + +redis_client = Redis.from_url( + read_cache_url(), + decode_responses=True, + socket_connect_timeout=5, + socket_timeout=5, +) + + +def session_store_unavailable() -> APIError: + return APIError( + status_code=503, + code="unavailable", + message="Session store unavailable", + ) + + +async def create_session(user_id: UUID) -> tuple[str, int]: + token = secrets.token_urlsafe(32) + ttl = get_session_ttl_seconds() + + try: + await redis_client.set( + f"session:{token}", + str(user_id), + ex=ttl, + ) + except RedisError as exc: + raise session_store_unavailable() from exc + + return token, ttl + + +async def get_session_user_id(token: str) -> UUID | None: + try: + value = await redis_client.get(f"session:{token}") + except RedisError as exc: + raise session_store_unavailable() from exc + + if value is None: + return None + + try: + return UUID(value) + except ValueError: + return None + + +async def delete_session(token: str) -> None: + try: + await redis_client.delete(f"session:{token}") + except RedisError as exc: + raise session_store_unavailable() from exc + + +async def ping_session_store() -> bool: + try: + return bool(await redis_client.ping()) + except RedisError: + return False \ No newline at end of file -- 2.54.0 From 0ef8d739d7c843ac82f3843f11321d8732580a07 Mon Sep 17 00:00:00 2001 From: casablanca Date: Thu, 29 Oct 2026 02:56:13 +0300 Subject: [PATCH 2/5] =?UTF-8?q?=D0=BB=D0=B0=D0=B1=D0=B0=204?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Dockerfile | 2 + Makefile | 14 +- REPORT.md | 469 +++++++++++++++++- compose.yaml | 75 ++- infra/minio/attachments-policy.json | 26 + infra/minio/init.sh | 19 + infra/nginx.conf | 1 + .../versions/c8f42a19e6b0_attachments.py | 78 +++ .../d9e53b20f7c1_attachment_metadata.py | 80 +++ requirements.txt | 18 +- scripts/bootstrap.sh | 29 +- scripts/reconcile.py | 121 +++++ src/images.py | 71 +++ src/main.py | 206 +++++++- src/models.py | 54 +- src/repositories.py | 225 ++++++++- src/storage.py | 71 +++ tests/test_reconcile.py | 255 ++++++++++ tests/test_upload_compensation.py | 144 ++++++ 19 files changed, 1900 insertions(+), 58 deletions(-) create mode 100644 infra/minio/attachments-policy.json create mode 100755 infra/minio/init.sh create mode 100644 migrations/versions/c8f42a19e6b0_attachments.py create mode 100644 migrations/versions/d9e53b20f7c1_attachment_metadata.py create mode 100644 scripts/reconcile.py create mode 100644 src/images.py create mode 100644 src/storage.py create mode 100644 tests/test_reconcile.py create mode 100644 tests/test_upload_compensation.py diff --git a/Dockerfile b/Dockerfile index 99aff457..3f654ddc 100644 --- a/Dockerfile +++ b/Dockerfile @@ -12,6 +12,8 @@ RUN pip install --no-cache-dir -r requirements.txt COPY alembic.ini . COPY migrations ./migrations COPY src ./src +COPY scripts ./scripts +COPY tests ./tests RUN useradd --create-home --uid 10001 appuser diff --git a/Makefile b/Makefile index 5d86d171..c801d708 100644 --- a/Makefile +++ b/Makefile @@ -4,7 +4,7 @@ CA_FILE ?= ACTION_SCRIPT ?= TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",) -.PHONY: help check validate test load test-persistence test-failover +.PHONY: help check validate test load test-persistence test-failover test-reconcile test-compensation reconcile reconcile-repair help: @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes" @@ -28,3 +28,15 @@ test-persistence: test-failover: @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2) $(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) + +test-reconcile: + docker compose exec -T api-1 python -m unittest discover -s tests -p 'test_reconcile.py' -v + +test-compensation: + docker compose exec -T api-1 python -m unittest discover -s tests -p 'test_upload_compensation.py' -v + +reconcile: + docker compose exec -T api-1 python -m scripts.reconcile + +reconcile-repair: + docker compose exec -T api-1 python -m scripts.reconcile --repair \ No newline at end of file diff --git a/REPORT.md b/REPORT.md index 9ad2b84f..1cdc31d1 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,478 @@ # Отчёт — лабораторная 4 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- **Автор, группа:** Станислав Травкин, группа: БВТ2304. +- **Целевая оценка:** 5. +- **Выбранный трек оценки 5:** трек 2 — Two-store reconciliation (сверка метаданных PostgreSQL и объектов S3). +- **Commit/PR:** указать после финального коммита и публикации. +- **Использованные источники, библиотеки и помощь ИИ:** README и методические требования лабораторной работы; Python 3.13, FastAPI, SQLAlchemy, Alembic, PostgreSQL, Redis, boto3, Pillow, MinIO, Nginx, Docker Compose. ChatGPT использовался для обсуждения архитектуры, реализации, диагностики ошибок, подготовки тестовых сценариев и отчёта. Реализация проверялась запуском тестов и экспериментами в локальном окружении. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +### Окружение + +Разработка и испытания проводились в Ubuntu 22.04 под WSL2, с использованием Docker Engine, Docker Compose, Python 3.13 и виртуального окружения `.venv`. + +Используемые контейнерные образы: + +| Компонент | Образ | +| --- | --- | +| PostgreSQL | `postgres:17.6` | +| Redis | `redis:8.2.2` | +| MinIO | `dappros/minio:RELEASE.2025-09-07T16-13-09Z` | +| Nginx | `nginx:1.29-alpine` | +| API и миграции | Локальная сборка из `Dockerfile` | + +Для запуска необходимы Docker Engine, Docker Compose, Python с зависимостями проекта и свободные локальные порты 8080 и 9001. + +### Подготовка + +После клонирования репозитория необходимо перейти в каталог проекта, создать локальное виртуальное окружение и установить зависимости проекта. + +```bash +python3.13 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +pip install -r requirements-dev.txt +``` + +Оператор должен создать каталог `secrets` и семь файлов: + +```text +secrets/postgres_password +secrets/database_url +secrets/cache_url +secrets/minio_root_user +secrets/minio_root_password +secrets/s3_access_key_id +secrets/s3_secret_access_key +``` + +Содержимое файлов задаётся локально и не публикуется в репозитории. + +`database_url` содержит строку подключения к PostgreSQL с тем же паролем, который указан в `postgres_password`. `cache_url` содержит строку подключения к Redis. Учётные данные S3-приложения должны отличаться от учётных данных администратора MinIO. + +Файл `.env.example` является справочным описанием параметров. В текущей реализации Docker Compose передаёт настройки контейнерам непосредственно через `environment`, а секреты — через файлы в `/run/secrets`. Создание `.env` не требуется для запуска представленного `compose.yaml`. + +### Сборка и запуск + +```bash +docker compose config --quiet +docker compose build +docker compose up -d +docker compose ps -a +``` + +При первом запуске PostgreSQL создаёт базу данных, контейнер `migrate` применяет миграции Alembic, а `s3-init` создаёт приватный бакет и пользователя приложения с ограниченными правами. + +Оператор должен дождаться состояния `healthy` для PostgreSQL, Redis, MinIO и обеих API-реплик, а также успешного завершения `migrate` и `s3-init`. + +Проверка версии схемы: + +```bash +docker compose run --rm migrate alembic current +``` + +В испытаниях наблюдалась версия `d9e53b20f7c1 (head)`. + +### Проверка + +```bash +make check +make validate +make test +make test-reconcile +make test-compensation +make reconcile +``` + +Дополнительные испытания: + +```bash +make load +make test-failover ACTION_SCRIPT=./scripts/stop-one.sh +make test-persistence ACTION_SCRIPT=./scripts/restart.sh +``` + +Тест отказоустойчивости намеренно останавливает API-реплику; после него её необходимо запустить снова: + +```bash +docker compose up -d api-1 api-2 +``` + +Reconciler в обычном режиме ничего не удаляет. Для разрешённой оператором очистки устаревших незарегистрированных объектов предусмотрена команда: + +```bash +make reconcile-repair +``` + +По умолчанию применяется защитный период 24 часа. Перед очисткой рекомендуется выполнить `make reconcile` и изучить список расхождений. + +### Остановка + +Безопасная остановка без удаления данных: + +```bash +docker compose down +``` + +Намеренное удаление учебных данных, включая постоянные тома PostgreSQL, Redis и MinIO: + +```bash +docker compose down -v +``` + +Последняя команда необратимо удаляет данные в томах данного Compose-проекта и не должна использоваться при обычном перезапуске. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +### Схема компонентов + +```text +Клиент + | + v +Nginx :8080 + | + +------ API-1 :8080 + | + +------ API-2 :8080 + | + +------ PostgreSQL + | пользователи, чаты, + | сообщения, вложения + | + +------ Redis + | сессии + | + +------ MinIO (S3) + бинарные данные вложений +``` + +Nginx распределяет запросы между двумя экземплярами FastAPI. API-реплики не используют локальное состояние для хранения пользовательских данных. Метаданные сохраняются в PostgreSQL, сессии — в Redis, содержимое вложений — в приватном бакете MinIO. + +PostgreSQL является источником истины для регистрации вложений и их принадлежности чатам. S3 хранит бинарные данные, адресуемые через `s3_key`. + +### Что перенесено из лабораторной 3 + +Сохранены пользовательские операции, авторизация через сессии, чаты, сообщения, идемпотентность создания сообщений, две API-реплики, балансировщик Nginx, PostgreSQL и Redis. + +### Что добавлено в лабораторной 4 + +- Приватное S3-хранилище MinIO с постоянным томом. +- Идемпотентная инициализация бакета и ограниченной учётной записи приложения. +- Загрузка PNG/JPEG с проверкой MIME-типа, содержимого и имени файла. +- Ограничения: не более 10 МиБ и 40 млн пикселей. +- Метаданные вложений в PostgreSQL и связь вложений с сообщениями. +- Проверка принадлежности вложений чату. +- Компенсация при сбое записи метаданных после успешной загрузки в S3. +- Отдельный reconciler для обнаружения и обработки расхождений между PostgreSQL и MinIO. +- Тесты компенсации, безопасной сверки и исправления расхождений. + +### Транзакционные границы + +PostgreSQL и MinIO не участвуют в общей распределённой транзакции. + +При загрузке изображения сначала проверяются права пользователя и содержимое файла, затем объект записывается в S3, после чего создаётся запись PostgreSQL со статусом `ready`. + +Ответ `201 Created` возвращается только после успешной записи объекта и завершения транзакции PostgreSQL. + +Если запись в БД завершается ошибкой, приложение откатывает транзакцию и проверяет наличие зарегистрированного `s3_key` через отдельную сессию. Удаление объекта допускается только при подтверждённом отсутствии записи. Если состояние PostgreSQL невозможно проверить, объект сохраняется для последующей сверки. + +Это уменьшает риск удаления зарегистрированного вложения, но не обеспечивает атомарность двух хранилищ. Оставшиеся после аварий объекты обнаруживаются reconciler. + +### Reconciliation + +Утилита `scripts/reconcile.py` получает список ключей из таблицы `attachments` и перечень объектов S3. + +Она вычисляет: + +- `orphan_objects` — объекты S3 без соответствующей записи PostgreSQL; +- `missing_objects` — записи PostgreSQL, для которых отсутствует объект S3. + +Режим `dry-run` только сообщает о расхождениях. + +В режиме `--repair` допускается удаление устаревших незарегистрированных объектов. Для защиты данных используются период ожидания, повторная проверка существования записи PostgreSQL и повторная проверка метаданных объекта S3 непосредственно перед удалением. + +Отсутствующие объекты S3 не восстанавливаются автоматически: reconciler сообщает о них, не удаляя метаданные PostgreSQL. + +### Конфигурация + +Параметры S3 (`S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`), пути к секретам, `SESSION_TTL_SECONDS`, `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS` передаются через `compose.yaml`. + +`INSTANCE_ID` различает реплики `api-1` и `api-2`. + +Параметры `APP_HOST`, `APP_PORT`, `SESSION_STORE`, `API_REPLICAS` и `IDEMPOTENCY_TTL_SECONDS` из преподавательского `.env.example` не используются как управляющие настройки в текущем Compose-файле. Число реплик задаётся двумя сервисами, порт — конфигурацией контейнера и Nginx, а сессии фактически хранятся в Redis. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Публичный smoke | `make test` | PASS | `tests/smoke.py`, `REPORT.md` | +| Проверка структуры | `make check` | PASS | `scripts/check_contract.py`, `REPORT.md` | +| Проверка OpenAPI | `make validate` | PASS | `scripts/validate_openapi.py`, `REPORT.md` | +| Две API-реплики | `docker compose ps api-1 api-2` | Обе реплики healthy | `compose.yaml`, `REPORT.md` | +| PostgreSQL и Redis | `docker compose ps -a` | Хранилища healthy | `compose.yaml`, `REPORT.md` | +| Приватное S3-хранилище | Анонимный запрос списка объектов бакета | HTTP 403 AccessDenied | `infra/minio/attachments-policy.json`, `REPORT.md` | +| Ограниченные права приложения | Запрос политики бакета от имени S3-приложения | HTTP 403 AccessDenied | `infra/minio/attachments-policy.json`, `REPORT.md` | +| Идемпотентный bootstrap | Повторный `docker compose run --rm s3-init` | Успешное выполнение, существующие объекты сохранены | `infra/minio/init.sh`, `REPORT.md` | +| Повторные миграции | `docker compose run --rm migrate` | Успешно; схема на head | `migrations/versions/`, `REPORT.md` | +| Загрузка PNG/JPEG | POST изображения в чат | HTTP 201; объект S3 и запись БД созданы | `src/main.py`, `src/images.py`, `REPORT.md` | +| Ограничение 10 МиБ | POST изображения больше лимита | HTTP 413 | `src/images.py`, `REPORT.md` | +| Ограничение 40 млн пикселей | POST изображения с превышением лимита | HTTP 413 | `src/images.py`, `REPORT.md` | +| Неподдерживаемый формат | POST GIF | HTTP 415 | `src/images.py`, `REPORT.md` | +| Несоответствие MIME содержимому | PNG, заявленный как JPEG | HTTP 400 | `src/images.py`, `REPORT.md` | +| Повреждённое изображение | POST повреждённого файла | HTTP 400 | `src/images.py`, `REPORT.md` | +| Доступ только участникам чата | Запрос вложения посторонним пользователем | HTTP 404 | `src/main.py`, `src/repositories.py`, `REPORT.md` | +| Защита неавторизованного запроса | GET вложения без сессии | HTTP 401 | `src/main.py`, `REPORT.md` | +| Получение метаданных и содержимого | GET вложения участником чата | HTTP 200; SHA-256 содержимого совпал | `src/storage.py`, `REPORT.md` | +| Вложения в сообщениях | Создание сообщения с `attachment_ids` | HTTP 201 | `src/models.py`, `src/repositories.py`, `REPORT.md` | +| Некорректные вложения в сообщении | Передача недопустимых `attachment_ids` | HTTP 400 | `src/repositories.py`, `REPORT.md` | +| Идемпотентность сообщений | Повтор ключа с тем же содержимым / изменение содержимого | Повтор принят; конфликт HTTP 409 | `src/repositories.py`, `REPORT.md` | +| Отказ MinIO | Остановка S3 и попытка загрузки | HTTP 503; после восстановления загрузка HTTP 201 | `src/storage.py`, `REPORT.md` | +| Компенсация при ошибках | `make test-compensation` | 5 тестов, OK | `tests/test_upload_compensation.py`, `REPORT.md` | +| Параллельные загрузки | 10 одновременных загрузок изображений примерно по 4,13 МиБ | 10 ответов HTTP 201; OOM не наблюдался | `REPORT.md` | +| Отказ одной API-реплики | `make test-failover ACTION_SCRIPT=./scripts/stop-one.sh` | PASS; 95 успешных записей, 2 неудачные попытки | `scripts/stop-one.sh`, `REPORT.md` | +| Сохранность при перезапуске | `make test-persistence ACTION_SCRIPT=./scripts/restart.sh` | PASS при повторной проверке; данные и сессия сохранились | `scripts/restart.sh`, `REPORT.md` | +| Тесты reconciler | `make test-reconcile` | 8 тестов, OK | `tests/test_reconcile.py`, `REPORT.md` | +| Поиск orphan-объектов | Добавление объекта S3 без записи БД, запуск dry-run | Объект обнаружен | `scripts/reconcile.py`, `REPORT.md` | +| Поиск missing-объектов | Добавление записи БД без объекта S3 | Отсутствующий объект обнаружен | `scripts/reconcile.py`, `REPORT.md` | +| Безопасный repair | Искусственно состаренный тестовый orphan-объект | Объект удалён, повторная сверка чистая | `scripts/reconcile.py`, `REPORT.md` | +| Защита свежих объектов | Repair при действующем grace period | Свежий объект пропущен | `tests/test_reconcile.py`, `REPORT.md` | +| Защита зарегистрированных объектов | Повторная проверка БД перед удалением | Зарегистрированный объект сохранён | `tests/test_reconcile.py`, `REPORT.md` | +| Защита изменившихся объектов | Повторная проверка `LastModified` | Обновлённый объект сохранён | `tests/test_reconcile.py`, `REPORT.md` | +| Повторяемость reconciliation | Повторный dry-run после очистки тестовых объектов | Нет расхождений | `scripts/reconcile.py`, `REPORT.md` | +| Измерение стоимости сверки | 10 запусков на 28 и 128 объектах S3 | Медиана 5,161 и 13,029 мс соответственно | `REPORT.md` | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +Результаты ручных сценариев зафиксированы в настоящем отчёте; исходные файлы тестов и конфигурации позволяют воспроизвести соответствующие проверки. Для ручных сценариев, не автоматизированных отдельным скриптом, повторное выполнение требует подготовки тестовых пользователей, чатов и файлов. ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +### Гипотезы + +1. Использование двух API-реплик и общих хранилищ позволяет продолжить обслуживание запросов при остановке одной реплики. +2. Ограничение размера загружаемых файлов и ресурсов контейнеров позволяет выполнять параллельные загрузки без превышения лимита памяти. +3. Reconciler обнаруживает расхождения между PostgreSQL и S3, а защитный период и повторные проверки позволяют избежать удаления свежих и зарегистрированных объектов. +4. Увеличение количества объектов S3 повышает время полной сверки. + +### Условия испытаний + +Среда: WSL2, Ubuntu 22.04, Docker Engine и Docker Compose. + +Ресурсы контейнеров: + +| Сервис | CPU | RAM | +| --- | --- | --- | +| API-1 | 1 | 512 МиБ | +| API-2 | 1 | 512 МиБ | +| PostgreSQL | 1 | 768 МиБ | +| Redis | 0,5 | 256 МиБ | +| MinIO | 1 | 512 МиБ | +| Nginx | 0,5 | 256 МиБ | + +Модель процессора хост-машины, выделенная память WSL2 и показатели CPU во время нагрузочного теста отдельно не фиксировались. + +### Нагрузочный тест API + +Команда: + +```bash +make load +``` + +Сохранённая сводка одного успешного прогона: + +```text +duration_seconds: 30 +concurrency: 4 +successful_requests: 12959 +failed_requests: 0 +successful_rps: 431.857 +p50_ms: 8.592 +p95_ms: 11.866 +p99_ms: 16.363 +``` + +Тест выполнял синтетические операции записи. Показатель 431,857 RPS характеризует конкретный локальный сценарий, а не гарантированную производительность в производственной среде. + +Отдельные значения CPU/RAM для данного прогона не записывались. + +### Параллельная загрузка изображений + +Выполнены два прогона по 10 одновременных загрузок файлов размером приблизительно 4,13 МиБ. + +Все 10 запросов в каждом прогоне завершились HTTP 201. + +Наблюдаемая длительность прогонов — приблизительно 1,26 и 0,83 секунды. + +Зафиксированные максимальные значения потребления памяти API-контейнеров: + +```text +api-1: 154.71 MiB +api-2: 138.84 MiB +limit: 512 MiB per container +oom_kill: 0 +``` + +Значения максимума памяти получены из счётчиков контейнеров и отражают накопленный пик, а не обязательно только интервал данного эксперимента. + +### Измерение стоимости reconciliation + +Выполнены по 10 последовательных запусков полной сверки для двух размеров S3-хранилища. + +**Сценарий A:** 28 записей PostgreSQL и 28 объектов S3. + +```text +times_ms: +20.772, 5.299, 5.023, 4.952, 4.469, +5.794, 5.492, 4.698, 4.678, 5.451 + +min_ms: 4.469 +mean_ms: 6.663 +median_ms: 5.161 +max_ms: 20.772 +``` + +**Сценарий B:** 28 записей PostgreSQL и 128 объектов S3, включая 100 временных объектов. + +```text +times_ms: +46.378, 13.201, 13.230, 13.349, 14.940, +12.856, 12.455, 11.603, 12.088, 11.242 + +min_ms: 11.242 +mean_ms: 16.134 +median_ms: 13.029 +max_ms: 46.378 +``` + +Медианное время выросло приблизительно в 2,52 раза при увеличении числа объектов S3 с 28 до 128. + +Результат подтверждает увеличение стоимости полного обхода в исследованном диапазоне. Двух точек недостаточно для доказательства линейной асимптотики. Дополнительные временные объекты после эксперимента удалены. + +### Эксперименты с отказами | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| Остановка одной API-реплики | Оставшаяся реплика продолжает обслуживать запросы | Failover PASS, 95 успешных записей и 2 неудачные попытки | Первое восстановление успешных запросов через 0,89 с; подтверждённой потери сохранённых данных нет | +| Перезапуск PostgreSQL, Redis и двух API | Данные и сессии сохраняются | Persistence PASS при повторном запуске | Кратковременная недоступность; данные и сессия сохранились | +| Остановка MinIO | Загрузка временно недоступна | HTTP 503, после запуска S3 — HTTP 201 | Восстановление после запуска MinIO; подтверждённой потери ранее сохранённых объектов нет | +| Ошибка вставки или commit в PostgreSQL | Незарегистрированный объект компенсируется | Соответствующие модульные тесты OK | Удаление при подтверждённом отсутствии записи | +| Недоступность PostgreSQL при компенсации | Не удалять объект с неизвестным состоянием регистрации | Модульный тест OK | Объект сохраняется до последующей сверки | +| Добавление orphan-объекта | Reconciler обнаруживает лишний объект | Обнаружен; устаревший тестовый объект удалён при repair | Повторная сверка без расхождений | +| Добавление missing-записи | Reconciler обнаруживает отсутствие бинарных данных | Запись обнаружена; автоматическое удаление БД не выполнялось | Восстановление содержимого не реализовано | + +При отдельных запусках теста persistence возникал `TimeoutError` ещё до выполнения сценария перезапуска. В логах Nginx наблюдались ошибки разрешения имён Docker DNS для `api-2`, включая `wrong ident` и `could not be resolved`. Повторные проверки DNS и последующий запуск persistence прошли успешно. Причина нестабильности окончательно не установлена. ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +1. **Нет общей транзакции PostgreSQL и S3.** Компенсация и периодическая сверка снижают риск рассогласования, но не заменяют распределённую транзакцию. + +2. **Reconciler не восстанавливает отсутствующие бинарные данные.** При наличии метаданных без S3-объекта требуется вмешательство оператора, восстановление из резервной копии или отдельная процедура обработки повреждённого вложения. + +3. **Существует окно гонки между проверкой и удалением.** Перед удалением выполняются дополнительные проверки, однако полной атомарности операций между двумя хранилищами нет. + +4. **Grace period не гарантирует сохранность всех незарегистрированных объектов.** Он защищает недавно созданные объекты, но старые объекты без метаданных могут быть удалены при repair. Поэтому repair выполняется осознанно оператором. + +5. **Наблюдалась нестабильность Docker DNS.** Некоторые запуски persistence завершались ошибкой до воздействия на инфраструктуру. Проблема не была устойчиво воспроизведена и не считается устранённой. + +6. **Измерения выполнены локально.** Результаты RPS и задержек зависят от WSL2, ресурсов хоста, профиля нагрузки и размеров данных. Измерения не являются производственным бенчмарком. + +7. **Профиль reconciliation ограничен двумя размерами набора.** Для оценки масштабируемости нужны дополнительные точки, большие объёмы данных и повторения на разных состояниях хранилища. + +8. **Не реализованы распределённые блокировки и фоновое расписание reconciliation.** Утилита запускается оператором. Для производственного применения целесообразны планировщик, аудит удалений, метрики, оповещения и резервное копирование. + +## Демонстрация преподавателю + +Все команды выполняются из корня репозитория. Перед демонстрацией должны быть подготовлены локальные секреты и запущены контейнеры. + +### 1. Запуск и проверка инфраструктуры + +```bash +docker compose up -d +docker compose ps -a +docker compose run --rm migrate alembic current +``` + +Показать две работающие API-реплики, PostgreSQL, Redis, MinIO, Nginx и применённые миграции. + +### 2. Проверка API + +```bash +make check +make validate +make test +``` + +Показать успешные результаты проверки структуры, OpenAPI и публичного smoke-теста. + +### 3. Проверка компенсации и reconciler + +```bash +make test-compensation +make test-reconcile +make reconcile +``` + +Показать 5 успешных тестов компенсации, 8 успешных тестов reconciler и JSON-отчёт сверки в режиме `dry-run`. + +Последняя зафиксированная сверка: + +```json +{ + "mode": "dry-run", + "grace_hours": 24, + "database_objects": 33, + "storage_objects": 33, + "orphan_objects": [], + "missing_objects": [], + "deleted_objects": [], + "skipped_objects": [], + "duration_seconds": 0.0263 +} +``` + +Количество объектов зависит от текущих тестовых данных и при повторном запуске может отличаться. + +### 4. Демонстрация нагрузки + +```bash +make load +``` + +Показать количество успешных запросов, RPS, ошибки и задержки p50/p95/p99. + +### 5. Демонстрация отказа одной API-реплики + +```bash +make test-failover ACTION_SCRIPT=./scripts/stop-one.sh +docker compose up -d api-1 api-2 +docker compose ps api-1 api-2 +``` + +Показать, что сценарий действительно останавливает одну реплику, а затем восстановить обе. + +### 6. Демонстрация сохранности данных + +```bash +make test-persistence ACTION_SCRIPT=./scripts/restart.sh +``` + +Скрипт `scripts/restart.sh` перезапускает PostgreSQL, Redis, `api-1` и `api-2`. Проверка должна подтвердить сохранение данных и сессии после восстановления. + +### 7. Повторная проверка согласованности + +```bash +make reconcile +``` + +Показать отсутствие незарегистрированных и отсутствующих объектов после испытаний. + +**Режим `make reconcile-repair` во время защиты без предварительного просмотра и согласования не запускать:** он может удалять устаревшие незарегистрированные объекты. + +### 8. Завершение демонстрации + +```bash +docker compose down +``` + +Команда останавливает контейнеры, сохраняя данные PostgreSQL, Redis и MinIO. diff --git a/compose.yaml b/compose.yaml index 23d7d67e..6887b172 100644 --- a/compose.yaml +++ b/compose.yaml @@ -2,19 +2,30 @@ x-api: &api build: context: . dockerfile: Dockerfile - environment: + environment: &api-environment APP_ENV: lab SESSION_TTL_SECONDS: 3600 DATABASE_URL_FILE: /run/secrets/database_url CACHE_URL_FILE: /run/secrets/cache_url + S3_ENDPOINT: http://s3:9000 + S3_REGION: us-east-1 + S3_BUCKET: messenger-attachments + S3_ACCESS_KEY_ID_FILE: /run/secrets/s3_access_key_id + S3_SECRET_ACCESS_KEY_FILE: /run/secrets/s3_secret_access_key + MAX_UPLOAD_BYTES: 10485760 + MAX_IMAGE_PIXELS: 40000000 secrets: - database_url - cache_url + - s3_access_key_id + - s3_secret_access_key depends_on: migrate: condition: service_completed_successfully redis: condition: service_healthy + s3-init: + condition: service_completed_successfully expose: - "8080" restart: unless-stopped @@ -61,6 +72,49 @@ services: cpus: 0.5 mem_limit: 256m + s3: + image: dappros/minio:RELEASE.2025-09-07T16-13-09Z + command: server /data --console-address ":9001" + environment: + MINIO_ROOT_USER_FILE: /run/secrets/minio_root_user + MINIO_ROOT_PASSWORD_FILE: /run/secrets/minio_root_password + secrets: + - minio_root_user + - minio_root_password + - s3_access_key_id + - s3_secret_access_key + volumes: + - s3_data:/data + ports: + - "127.0.0.1:9001:9001" + healthcheck: + test: [ "CMD", "mc", "ready", "local" ] + interval: 10s + timeout: 5s + retries: 10 + start_period: 15s + restart: unless-stopped + cpus: 1.0 + mem_limit: 512m + + s3-init: + image: dappros/minio:RELEASE.2025-09-07T16-13-09Z + entrypoint: [ "/bin/sh", "/config/init.sh" ] + volumes: + - ./infra/minio/init.sh:/config/init.sh:ro + - ./infra/minio/attachments-policy.json:/config/attachments-policy.json:ro + secrets: + - minio_root_user + - minio_root_password + - s3_access_key_id + - s3_secret_access_key + depends_on: + s3: + condition: service_healthy + restart: "no" + cpus: 0.5 + mem_limit: 256m + migrate: build: context: . @@ -78,19 +132,13 @@ services: api-1: <<: *api environment: - APP_ENV: lab - SESSION_TTL_SECONDS: 3600 - DATABASE_URL_FILE: /run/secrets/database_url - CACHE_URL_FILE: /run/secrets/cache_url + <<: *api-environment INSTANCE_ID: api-1 api-2: <<: *api environment: - APP_ENV: lab - SESSION_TTL_SECONDS: 3600 - DATABASE_URL_FILE: /run/secrets/database_url - CACHE_URL_FILE: /run/secrets/cache_url + <<: *api-environment INSTANCE_ID: api-2 nginx: @@ -113,7 +161,16 @@ secrets: file: ./secrets/database_url cache_url: file: ./secrets/cache_url + minio_root_user: + file: ./secrets/minio_root_user + minio_root_password: + file: ./secrets/minio_root_password + s3_access_key_id: + file: ./secrets/s3_access_key_id + s3_secret_access_key: + file: ./secrets/s3_secret_access_key volumes: postgres_data: redis_data: + s3_data: \ No newline at end of file diff --git a/infra/minio/attachments-policy.json b/infra/minio/attachments-policy.json new file mode 100644 index 00000000..75631ec1 --- /dev/null +++ b/infra/minio/attachments-policy.json @@ -0,0 +1,26 @@ + +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket" + ], + "Resource": [ + "arn:aws:s3:::messenger-attachments" + ] + }, + { + "Effect": "Allow", + "Action": [ + "s3:GetObject", + "s3:PutObject", + "s3:DeleteObject" + ], + "Resource": [ + "arn:aws:s3:::messenger-attachments/*" + ] + } + ] +} diff --git a/infra/minio/init.sh b/infra/minio/init.sh new file mode 100755 index 00000000..8966b348 --- /dev/null +++ b/infra/minio/init.sh @@ -0,0 +1,19 @@ +#!/bin/sh +set -eu + +ROOT_USER="$(cat /run/secrets/minio_root_user)" +ROOT_PASSWORD="$(cat /run/secrets/minio_root_password)" +APP_USER="$(cat /run/secrets/s3_access_key_id)" +APP_PASSWORD="$(cat /run/secrets/s3_secret_access_key)" + +mc alias set local http://s3:9000 "$ROOT_USER" "$ROOT_PASSWORD" + +mc mb --ignore-existing local/messenger-attachments +mc anonymous set private local/messenger-attachments + +mc admin policy create local messenger-attachments-rw /config/attachments-policy.json +mc admin user add local "$APP_USER" "$APP_PASSWORD" +mc admin policy attach local messenger-attachments-rw --user "$APP_USER" + +mc admin user info local "$APP_USER" +mc ls local/messenger-attachments diff --git a/infra/nginx.conf b/infra/nginx.conf index e3000e30..dbc9892f 100644 --- a/infra/nginx.conf +++ b/infra/nginx.conf @@ -15,6 +15,7 @@ http { server { listen 8080; + client_max_body_size 12m; location / { proxy_pass http://api_backend; diff --git a/migrations/versions/c8f42a19e6b0_attachments.py b/migrations/versions/c8f42a19e6b0_attachments.py new file mode 100644 index 00000000..7463682c --- /dev/null +++ b/migrations/versions/c8f42a19e6b0_attachments.py @@ -0,0 +1,78 @@ + +from alembic import op +import sqlalchemy as sa + + +revision = "c8f42a19e6b0" +down_revision = "b3a91c0e7d42" +branch_labels = None +depends_on = None + + +def upgrade() -> None: + op.create_table( + "attachments", + sa.Column("id", sa.Uuid(), nullable=False), + sa.Column("chat_id", sa.Uuid(), nullable=False), + sa.Column("uploader_id", sa.Uuid(), nullable=False), + sa.Column("filename", sa.String(length=255), nullable=False), + sa.Column("content_type", sa.String(length=100), nullable=False), + sa.Column("size_bytes", sa.BigInteger(), nullable=False), + sa.Column("s3_key", sa.String(length=512), nullable=False), + sa.Column("status", sa.String(length=20), nullable=False), + sa.Column( + "created_at", + sa.DateTime(timezone=True), + server_default=sa.text("CURRENT_TIMESTAMP"), + nullable=False, + ), + sa.ForeignKeyConstraint( + ["chat_id"], + ["chats.id"], + ondelete="CASCADE", + ), + sa.ForeignKeyConstraint( + ["uploader_id"], + ["users.id"], + ondelete="RESTRICT", + ), + sa.PrimaryKeyConstraint("id"), + sa.UniqueConstraint("s3_key", name="uq_attachments_s3_key"), + sa.CheckConstraint( + "size_bytes > 0 AND size_bytes <= 10485760", + name="ck_attachments_size", + ), + sa.CheckConstraint( + "status IN ('pending', 'ready')", + name="ck_attachments_status", + ), + ) + + op.create_index( + "ix_attachments_chat_id", + "attachments", + ["chat_id"], + ) + + op.create_table( + "message_attachments", + sa.Column("message_id", sa.Uuid(), nullable=False), + sa.Column("attachment_id", sa.Uuid(), nullable=False), + sa.ForeignKeyConstraint( + ["message_id"], + ["messages.id"], + ondelete="CASCADE", + ), + sa.ForeignKeyConstraint( + ["attachment_id"], + ["attachments.id"], + ondelete="RESTRICT", + ), + sa.PrimaryKeyConstraint("message_id", "attachment_id"), + ) + + +def downgrade() -> None: + op.drop_table("message_attachments") + op.drop_index("ix_attachments_chat_id", table_name="attachments") + op.drop_table("attachments") diff --git a/migrations/versions/d9e53b20f7c1_attachment_metadata.py b/migrations/versions/d9e53b20f7c1_attachment_metadata.py new file mode 100644 index 00000000..72bb1460 --- /dev/null +++ b/migrations/versions/d9e53b20f7c1_attachment_metadata.py @@ -0,0 +1,80 @@ + +from alembic import op +import sqlalchemy as sa + + +revision = "d9e53b20f7c1" +down_revision = "c8f42a19e6b0" +branch_labels = None +depends_on = None + + +def upgrade() -> None: + op.alter_column( + "attachments", + "uploader_id", + new_column_name="owner_id", + ) + + op.add_column( + "attachments", + sa.Column( + "sha256", + sa.String(length=64), + nullable=False, + ), + ) + + op.add_column( + "attachments", + sa.Column( + "variants", + sa.JSON(), + nullable=False, + server_default=sa.text("'[]'::json"), + ), + ) + + op.add_column( + "attachments", + sa.Column( + "error_code", + sa.String(length=100), + nullable=True, + ), + ) + + op.add_column( + "attachments", + sa.Column( + "updated_at", + sa.DateTime(timezone=True), + server_default=sa.text("CURRENT_TIMESTAMP"), + nullable=False, + ), + ) + + op.create_check_constraint( + "ck_attachments_sha256", + "attachments", + "sha256 ~ '^[a-f0-9]{64}$'", + ) + + +def downgrade() -> None: + op.drop_constraint( + "ck_attachments_sha256", + "attachments", + type_="check", + ) + + op.drop_column("attachments", "updated_at") + op.drop_column("attachments", "error_code") + op.drop_column("attachments", "variants") + op.drop_column("attachments", "sha256") + + op.alter_column( + "attachments", + "owner_id", + new_column_name="uploader_id", + ) diff --git a/requirements.txt b/requirements.txt index 2f27f572..418ea3c4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -10,11 +10,13 @@ pydantic_core==2.46.5 starlette==1.7.0 typing-inspection==0.4.4 typing_extensions==4.16.0 -uvicorn==0.53.0 -SQLAlchemy==2.1.4 -asyncpg==0.32.0 -alembic==1.20.0 -greenlet==3.5.6 - -argon2-cffi==25.1.0 -redis==7.0.1 +uvicorn==0.53.0 +SQLAlchemy==2.1.4 +asyncpg==0.32.0 +alembic==1.20.0 +greenlet==3.5.6 +argon2-cffi==25.1.0 +redis==7.0.1 +boto3==1.43.120 +Pillow==13.0.0 +python-multipart==0.0.32 \ No newline at end of file diff --git a/scripts/bootstrap.sh b/scripts/bootstrap.sh index 33ebc3fe..8160e2df 100755 --- a/scripts/bootstrap.sh +++ b/scripts/bootstrap.sh @@ -7,23 +7,34 @@ mkdir -p secrets chmod 700 secrets umask 077 -if [[ ! -f secrets/postgres_password ]]; then - python3 -c 'import secrets; print(secrets.token_hex(24))' > secrets/postgres_password -fi +create_random_secret() { + local name="$1" + local value="$2" -if [[ ! -f secrets/database_url ]]; then + if [[ ! -s "secrets/$name" ]]; then + printf '%s\n' "$value" > "secrets/$name" + fi + + chmod 644 "secrets/$name" +} + +create_random_secret postgres_password "$(python3 -c 'import secrets; print(secrets.token_hex(24))')" + +if [[ ! -s secrets/database_url ]]; then PASSWORD="$(cat secrets/postgres_password)" printf 'postgresql+asyncpg://lab2:%s@postgres:5432/messenger\n' "$PASSWORD" > secrets/database_url fi -if [[ ! -f secrets/cache_url ]]; then - printf 'redis://redis:6379/0\n' > secrets/cache_url -fi +create_random_secret cache_url 'redis://redis:6379/0' +create_random_secret minio_root_user "minio-$(python3 -c 'import secrets; print(secrets.token_hex(12))')" +create_random_secret minio_root_password "$(python3 -c 'import secrets; print(secrets.token_hex(32))')" +create_random_secret s3_access_key_id "$(python3 -c 'import secrets; print(secrets.token_hex(20))')" +create_random_secret s3_secret_access_key "$(python3 -c 'import secrets; print(secrets.token_hex(32))')" -chmod 644 secrets/postgres_password secrets/database_url secrets/cache_url +chmod 644 secrets/* if [[ ! -f .env ]]; then cp .env.example .env fi -docker compose config --quiet \ No newline at end of file +docker compose config --quiet diff --git a/scripts/reconcile.py b/scripts/reconcile.py new file mode 100644 index 00000000..3a5e3b2a --- /dev/null +++ b/scripts/reconcile.py @@ -0,0 +1,121 @@ + +import argparse +import asyncio +import json +import sys +import time +from datetime import datetime, timedelta, timezone + +from sqlalchemy import text + +from src.database import SessionFactory, engine +from src.storage import S3_BUCKET, s3_client + + +def list_s3_objects() -> dict: + objects = {} + paginator = s3_client.get_paginator("list_objects_v2") + + for page in paginator.paginate(Bucket=S3_BUCKET): + for item in page.get("Contents", []): + objects[item["Key"]] = item["LastModified"] + + return objects + + +async def list_db_keys() -> set[str]: + async with SessionFactory() as session: + result = await session.execute(text("SELECT s3_key FROM attachments")) + return set(result.scalars().all()) + + +async def db_key_exists(key: str) -> bool: + async with SessionFactory() as session: + result = await session.execute( + text("SELECT 1 FROM attachments WHERE s3_key = :key"), + {"key": key}, + ) + return result.first() is not None + + +def inspect_object(key: str): + return s3_client.head_object(Bucket=S3_BUCKET, Key=key) + + +def remove_object(key: str) -> None: + s3_client.delete_object(Bucket=S3_BUCKET, Key=key) + + +async def reconcile(repair: bool, grace_hours: int) -> int: + started = time.perf_counter() + + try: + db_keys, s3_objects = await asyncio.gather( + list_db_keys(), + asyncio.to_thread(list_s3_objects), + ) + + s3_keys = set(s3_objects) + orphan_keys = sorted(s3_keys - db_keys) + missing_keys = sorted(db_keys - s3_keys) + + cutoff = datetime.now(timezone.utc) - timedelta(hours=grace_hours) + deleted = [] + skipped = [] + + if repair: + for key in orphan_keys: + if s3_objects[key] > cutoff: + skipped.append({"key": key, "reason": "grace_period"}) + continue + + if await db_key_exists(key): + skipped.append({"key": key, "reason": "database_record_exists"}) + continue + + metadata = await asyncio.to_thread(inspect_object, key) + + if metadata["LastModified"] > cutoff: + skipped.append({"key": key, "reason": "object_too_recent"}) + continue + + if await db_key_exists(key): + skipped.append({"key": key, "reason": "database_record_exists"}) + continue + + await asyncio.to_thread(remove_object, key) + deleted.append(key) + + report = { + "mode": "repair" if repair else "dry-run", + "grace_hours": grace_hours, + "database_objects": len(db_keys), + "storage_objects": len(s3_keys), + "orphan_objects": orphan_keys, + "missing_objects": missing_keys, + "deleted_objects": deleted, + "skipped_objects": skipped, + "duration_seconds": round(time.perf_counter() - started, 4), + } + + print(json.dumps(report, indent=2, ensure_ascii=False)) + return 0 + + except Exception as error: + print(f"Reconciliation failed: {error}", file=sys.stderr) + return 1 + + finally: + await engine.dispose() + + +if __name__ == "__main__": + parser = argparse.ArgumentParser() + parser.add_argument("--repair", action="store_true") + parser.add_argument("--grace-hours", type=int, default=24) + args = parser.parse_args() + + if args.grace_hours < 1: + parser.error("--grace-hours must be at least 1") + + sys.exit(asyncio.run(reconcile(args.repair, args.grace_hours))) diff --git a/src/images.py b/src/images.py new file mode 100644 index 00000000..2acf0f6f --- /dev/null +++ b/src/images.py @@ -0,0 +1,71 @@ +import hashlib +import io +import os + +from PIL import Image, UnidentifiedImageError + +from src.errors import APIError + + +MAX_UPLOAD_BYTES = int(os.getenv("MAX_UPLOAD_BYTES", "10485760")) +MAX_IMAGE_PIXELS = int(os.getenv("MAX_IMAGE_PIXELS", "40000000")) + +ALLOWED_FORMATS = { + "PNG": "image/png", + "JPEG": "image/jpeg", +} + + +def validate_image(body: bytes, content_type: str) -> tuple[int, str]: + if content_type not in ALLOWED_FORMATS.values(): + raise APIError( + status_code=415, + code="unsupported_media_type", + message="Only PNG and JPEG images are supported", + ) + + size_bytes = len(body) + + if size_bytes > MAX_UPLOAD_BYTES: + raise APIError( + status_code=413, + code="payload_too_large", + message="Image exceeds maximum upload size", + ) + + if size_bytes == 0: + raise APIError( + status_code=400, + code="invalid_request", + message="Image must not be empty", + ) + + try: + with Image.open(io.BytesIO(body)) as image: + if image.format not in ALLOWED_FORMATS: + raise ValueError("Unsupported image format") + + if ALLOWED_FORMATS[image.format] != content_type: + raise ValueError("Content-Type does not match image format") + + width, height = image.size + + if width * height > MAX_IMAGE_PIXELS: + raise APIError( + status_code=413, + code="payload_too_large", + message="Image exceeds maximum pixel count", + ) + + image.load() + + except APIError: + raise + except (UnidentifiedImageError, OSError, ValueError, Image.DecompressionBombError) as exc: + raise APIError( + status_code=400, + code="invalid_request", + message="Invalid image data", + ) from exc + + return size_bytes, hashlib.sha256(body).hexdigest() diff --git a/src/main.py b/src/main.py index 0295542b..cdce042f 100644 --- a/src/main.py +++ b/src/main.py @@ -4,22 +4,24 @@ import os import re import base64 import binascii +import asyncio -from fastapi import Depends, FastAPI, Request, Header +from fastapi import Depends, FastAPI, Request, Header, Query from fastapi.exceptions import RequestValidationError -from fastapi.responses import JSONResponse +from fastapi.responses import JSONResponse, Response from fastapi.security import ( HTTPAuthorizationCredentials, HTTPBearer, ) +from botocore.exceptions import BotoCoreError, ClientError from sqlalchemy.exc import IntegrityError, SQLAlchemyError from sqlalchemy.ext.asyncio import AsyncSession from starlette.exceptions import HTTPException as StarletteHTTPException from contextlib import asynccontextmanager -from src.database import engine, get_db_session, ping_database +from src.database import engine, get_db_session, ping_database, SessionFactory from src.errors import APIError -from src.models import CreateUser, SessionResponse, User, CreateChat, Chat, ChatPage, CreateMessage, Message, MessagePage +from src.models import CreateUser, SessionResponse, User, CreateChat, Chat, ChatPage, CreateMessage, Message, MessagePage, Attachment from src.repositories import ( create_chat, list_chats, @@ -29,6 +31,9 @@ from src.repositories import ( get_user_credentials_by_username, create_message, get_messages, + create_attachment, + get_attachment, + attachment_key_exists, ) from src.security import verify_password from src.sessions import ( @@ -38,6 +43,8 @@ from src.sessions import ( ping_session_store, redis_client, ) +from src.images import MAX_UPLOAD_BYTES, validate_image +from src.storage import delete_object, put_object, get_object @asynccontextmanager @@ -105,7 +112,21 @@ async def request_middleware(request: Request, call_next): if content_type is not None: media_type = content_type.split(";", 1)[0].strip().lower() - if media_type != "application/json": + is_attachment_upload = ( + request.method == "POST" + and re.fullmatch( + r"/api/v1/chats/[^/]+/attachments", + request.url.path, + ) is not None + ) + + allowed_media_types = ( + {"image/png", "image/jpeg"} + if is_attachment_upload + else {"application/json"} + ) + + if media_type not in allowed_media_types: return JSONResponse( status_code=415, content={ @@ -526,3 +547,178 @@ async def get_messages_endpoint( limit=limit, cursor=cursor, ) + + +@app.post( + "/api/v1/chats/{chat_id}/attachments", + response_model=Attachment, + status_code=201, +) +async def upload_attachment_endpoint( + chat_id: UUID, + request: Request, + filename: str = Query(min_length=1, max_length=255), + current_user: User = Depends(get_current_user), + session: AsyncSession = Depends(get_db_session), +) -> Attachment: + chat = await get_chat_by_id( + session=session, + chat_id=chat_id, + current_user_id=current_user.id, + ) + + if chat is None: + raise APIError( + status_code=404, + code="not_found", + message="Chat not found", + ) + + content_type = request.headers.get("content-type", "").split(";", 1)[0].strip().lower() + + if content_type not in {"image/png", "image/jpeg"}: + raise APIError( + status_code=415, + code="unsupported_media_type", + message="Only PNG and JPEG images are supported", + ) + + body = bytearray() + + async for chunk in request.stream(): + if len(body) + len(chunk) > MAX_UPLOAD_BYTES: + raise APIError( + status_code=413, + code="payload_too_large", + message="Image exceeds maximum upload size", + ) + + body.extend(chunk) + + image_bytes = bytes(body) + size_bytes, sha256 = validate_image(image_bytes, content_type) + + attachment_id = uuid4() + extension = "png" if content_type == "image/png" else "jpg" + s3_key = f"attachments/{chat_id}/{attachment_id}.{extension}" + + try: + await put_object( + key=s3_key, + body=image_bytes, + content_type=content_type, + ) + except (BotoCoreError, ClientError, OSError, TimeoutError) as exc: + raise APIError( + status_code=503, + code="unavailable", + message="Object storage unavailable", + ) from exc + + try: + attachment = await create_attachment( + session=session, + attachment_id=attachment_id, + chat_id=chat_id, + owner_id=current_user.id, + filename=filename, + content_type=content_type, + size_bytes=size_bytes, + sha256=sha256, + s3_key=s3_key, + ) + + await session.commit() + + except BaseException: + try: + await session.rollback() + except Exception: + pass + + try: + async with SessionFactory() as verification_session: + exists = await attachment_key_exists( + verification_session, + s3_key, + ) + except Exception: + exists = True + + if not exists: + try: + await asyncio.shield(delete_object(s3_key)) + except Exception: + pass + + raise + + return attachment + + + +@app.get( + "/api/v1/attachments/{attachment_id}", + response_model=Attachment, +) +async def get_attachment_endpoint( + attachment_id: UUID, + current_user: User = Depends(get_current_user), + session: AsyncSession = Depends(get_db_session), +) -> Attachment: + result = await get_attachment( + session=session, + attachment_id=attachment_id, + current_user_id=current_user.id, + ) + + if result is None: + raise APIError( + status_code=404, + code="not_found", + message="Attachment not found", + ) + + attachment, s3_key = result + return attachment + + +@app.get("/api/v1/attachments/{attachment_id}/content") +async def get_attachment_content_endpoint( + attachment_id: UUID, + current_user: User = Depends(get_current_user), + session: AsyncSession = Depends(get_db_session), +): + result = await get_attachment( + session=session, + attachment_id=attachment_id, + current_user_id=current_user.id, + ) + + if result is None: + raise APIError( + status_code=404, + code="not_found", + message="Attachment not found", + ) + + attachment, s3_key = result + + try: + body = await get_object(s3_key) + except (BotoCoreError, ClientError, OSError, TimeoutError) as exc: + raise APIError( + status_code=503, + code="unavailable", + message="Object storage unavailable", + ) from exc + + return Response( + content=body, + media_type=attachment.content_type, + headers={ + "Cache-Control": "private, no-store", + "X-Content-Type-Options": "nosniff", + }, + ) + diff --git a/src/models.py b/src/models.py index 5f2c2991..f579d3a4 100644 --- a/src/models.py +++ b/src/models.py @@ -1,7 +1,7 @@ from datetime import datetime from uuid import UUID -from pydantic import BaseModel, ConfigDict, Field, field_validator +from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator class CreateUser(BaseModel): @@ -91,19 +91,24 @@ class ChatPage(BaseModel): class CreateMessage(BaseModel): model_config = ConfigDict(extra="forbid") - text: str = Field( - min_length=1, - max_length=4000, - ) + text: str = Field(max_length=4000) + attachment_ids: list[UUID] = Field(default_factory=list, max_length=10) - @field_validator("text") + @field_validator("attachment_ids") @classmethod - def validate_text(cls, value: str) -> str: - if not value.strip(): - raise ValueError("Message text must not be blank") + def validate_attachment_ids(cls, value: list[UUID]) -> list[UUID]: + if len(value) != len(set(value)): + raise ValueError("Attachment IDs must be unique") return value + @model_validator(mode="after") + def validate_content(self): + if not self.text.strip() and not self.attachment_ids: + raise ValueError("Message must contain text or attachments") + + return self + class Message(BaseModel): id: UUID @@ -111,8 +116,37 @@ class Message(BaseModel): sender_id: UUID text: str created_at: datetime + attachment_ids: list[UUID] = Field(default_factory=list) class MessagePage(BaseModel): items: list[Message] - next_cursor: str | None \ No newline at end of file + next_cursor: str | None + + +class Variant(BaseModel): + model_config = ConfigDict(extra="forbid") + + name: str = Field(pattern=r"^(thumbnail|crop|optimized)$") + content_type: str = Field(pattern=r"^image/(jpeg|png|webp)$") + size_bytes: int = Field(ge=1) + width: int = Field(ge=1) + height: int = Field(ge=1) + sha256: str = Field(pattern=r"^[a-f0-9]{64}$") + + +class Attachment(BaseModel): + model_config = ConfigDict(extra="forbid") + + id: UUID + chat_id: UUID + owner_id: UUID + filename: str = Field(min_length=1, max_length=255) + content_type: str = Field(pattern=r"^image/(png|jpeg)$") + size_bytes: int = Field(ge=1, le=10485760) + sha256: str = Field(pattern=r"^[a-f0-9]{64}$") + status: str = Field(pattern=r"^ready$") + variants: list[Variant] + error_code: str | None + created_at: datetime + updated_at: datetime diff --git a/src/repositories.py b/src/repositories.py index f0020c69..258ac91f 100644 --- a/src/repositories.py +++ b/src/repositories.py @@ -5,7 +5,7 @@ import json from sqlalchemy import text from sqlalchemy.ext.asyncio import AsyncSession -from src.models import Chat, ChatPage, CreateChat, CreateUser, User, CreateMessage, Message, MessagePage +from src.models import Attachment, Chat, ChatPage, CreateChat, CreateUser, User, CreateMessage, Message, MessagePage from src.security import hash_password from src.errors import APIError from src.cursor import decode_cursor, encode_cursor, decode_chat_cursor, encode_chat_cursor @@ -367,7 +367,10 @@ async def create_message( ) canonical_body = json.dumps( - {"text": data.text}, + { + "text": data.text, + "attachment_ids": [str(attachment_id) for attachment_id in data.attachment_ids], + }, sort_keys=True, ensure_ascii=False, separators=(",", ":"), @@ -444,14 +447,57 @@ async def create_message( ), ) + attachment_result = await session.execute( + text(""" + SELECT attachment_id + FROM message_attachments + WHERE message_id = :message_id + ORDER BY attachment_id + """), + {"message_id": existing.id}, + ) + + attachment_ids = [ + UUID(str(row.attachment_id)) + for row in attachment_result.all() + ] + return Message( id=UUID(str(existing.id)), chat_id=UUID(str(existing.chat_id)), sender_id=UUID(str(existing.sender_id)), text=existing.text, created_at=existing.created_at, + attachment_ids=attachment_ids, ) + if data.attachment_ids: + attachments_result = await session.execute( + text(""" + SELECT id + FROM attachments + WHERE id = ANY (:attachment_ids) + AND chat_id = :chat_id + AND status = 'ready' + """), + { + "attachment_ids": data.attachment_ids, + "chat_id": chat_id, + }, + ) + + valid_attachment_ids = { + UUID(str(row.id)) + for row in attachments_result.all() + } + + if valid_attachment_ids != set(data.attachment_ids): + raise APIError( + status_code=400, + code="invalid_request", + message="Invalid attachments for this chat", + ) + message_id = uuid4() message_result = await session.execute( @@ -485,6 +531,20 @@ async def create_message( row = message_result.one() + for attachment_id in data.attachment_ids: + await session.execute( + text(""" + INSERT INTO message_attachments (message_id, + attachment_id) + VALUES (:message_id, + :attachment_id) + """), + { + "message_id": message_id, + "attachment_id": attachment_id, + }, + ) + await session.execute( text(""" INSERT INTO message_idempotency ( @@ -517,6 +577,7 @@ async def create_message( sender_id=UUID(str(row.sender_id)), text=row.text, created_at=row.created_at, + attachment_ids=data.attachment_ids, ) @@ -627,6 +688,29 @@ async def get_messages( has_more = len(rows) > limit rows = rows[:limit] + attachments_by_message = {} + + if rows: + attachment_result = await session.execute( + text(""" + SELECT message_id, attachment_id + FROM message_attachments + WHERE message_id = ANY(:message_ids) + ORDER BY message_id, attachment_id + """), + { + "message_ids": [row.id for row in rows], + }, + ) + + for attachment_row in attachment_result.all(): + message_id = UUID(str(attachment_row.message_id)) + attachment_id = UUID(str(attachment_row.attachment_id)) + + attachments_by_message.setdefault( + message_id, [] + ).append(attachment_id) + items = [ Message( id=UUID(str(row.id)), @@ -634,6 +718,9 @@ async def get_messages( sender_id=UUID(str(row.sender_id)), text=row.text, created_at=row.created_at, + attachment_ids=attachments_by_message.get( + UUID(str(row.id)), [] + ), ) for row in rows ] @@ -653,3 +740,137 @@ async def get_messages( items=items, next_cursor=next_cursor, ) + + +def attachment_from_row(row) -> Attachment: + return Attachment( + id=UUID(str(row.id)), + chat_id=UUID(str(row.chat_id)), + owner_id=UUID(str(row.owner_id)), + filename=row.filename, + content_type=row.content_type, + size_bytes=row.size_bytes, + sha256=row.sha256, + status=row.status, + variants=row.variants, + error_code=row.error_code, + created_at=row.created_at, + updated_at=row.updated_at, + ) + + +async def create_attachment( + session: AsyncSession, + attachment_id: UUID, + chat_id: UUID, + owner_id: UUID, + filename: str, + content_type: str, + size_bytes: int, + sha256: str, + s3_key: str, +) -> Attachment: + result = await session.execute( + text( + """ + INSERT INTO attachments ( + id, + chat_id, + owner_id, + filename, + content_type, + size_bytes, + sha256, + s3_key, + status + ) + VALUES ( + :id, + :chat_id, + :owner_id, + :filename, + :content_type, + :size_bytes, + :sha256, + :s3_key, + 'ready' + ) + RETURNING + id, + chat_id, + owner_id, + filename, + content_type, + size_bytes, + sha256, + status, + variants, + error_code, + created_at, + updated_at + """ + ), + { + "id": attachment_id, + "chat_id": chat_id, + "owner_id": owner_id, + "filename": filename, + "content_type": content_type, + "size_bytes": size_bytes, + "sha256": sha256, + "s3_key": s3_key, + }, + ) + + return attachment_from_row(result.one()) + + +async def get_attachment( + session: AsyncSession, + attachment_id: UUID, + current_user_id: UUID, +): + result = await session.execute( + text( + """ + SELECT + a.id, + a.chat_id, + a.owner_id, + a.filename, + a.content_type, + a.size_bytes, + a.sha256, + a.s3_key, + a.status, + a.variants, + a.error_code, + a.created_at, + a.updated_at + FROM attachments AS a + JOIN chat_members AS cm + ON cm.chat_id = a.chat_id + WHERE a.id = :attachment_id + AND cm.user_id = :current_user_id + AND a.status = 'ready' + """ + ), + { + "attachment_id": attachment_id, + "current_user_id": current_user_id, + }, + ) + + row = result.one_or_none() + + if row is None: + return None + + return attachment_from_row(row), row.s3_key + +async def attachment_key_exists(session: AsyncSession, s3_key: str) -> bool: + result = await session.execute( + text("SELECT 1 FROM attachments WHERE s3_key = :s3_key"), + {"s3_key": s3_key}, + ) + return result.first() is not None \ No newline at end of file diff --git a/src/storage.py b/src/storage.py new file mode 100644 index 00000000..1a48c07d --- /dev/null +++ b/src/storage.py @@ -0,0 +1,71 @@ + +import asyncio +import os +from pathlib import Path + +import boto3 +from botocore.config import Config + + +def read_secret(env_name: str) -> str: + path = os.environ[env_name] + return Path(path).read_text(encoding="utf-8").strip() + + +s3_client = boto3.client( + "s3", + endpoint_url=os.environ["S3_ENDPOINT"], + region_name=os.getenv("S3_REGION", "us-east-1"), + aws_access_key_id=read_secret("S3_ACCESS_KEY_ID_FILE"), + aws_secret_access_key=read_secret("S3_SECRET_ACCESS_KEY_FILE"), + config=Config( + signature_version="s3v4", + connect_timeout=2, + read_timeout=3, + retries={"total_max_attempts": 1, "mode": "standard"}, + s3={"addressing_style": "path"}, + ), +) + +S3_BUCKET = os.environ["S3_BUCKET"] + + +async def put_object(key: str, body: bytes, content_type: str) -> None: + await asyncio.to_thread( + s3_client.put_object, + Bucket=S3_BUCKET, + Key=key, + Body=body, + ContentType=content_type, + ) + + +async def get_object(key: str) -> bytes: + def download() -> bytes: + response = s3_client.get_object(Bucket=S3_BUCKET, Key=key) + stream = response["Body"] + try: + return stream.read() + finally: + stream.close() + + return await asyncio.to_thread(download) + + +async def delete_object(key: str) -> None: + await asyncio.to_thread( + s3_client.delete_object, + Bucket=S3_BUCKET, + Key=key, + ) + + +async def ping_storage() -> bool: + try: + await asyncio.to_thread( + s3_client.head_bucket, + Bucket=S3_BUCKET, + ) + return True + except Exception: + return False diff --git a/tests/test_reconcile.py b/tests/test_reconcile.py new file mode 100644 index 00000000..c4db9347 --- /dev/null +++ b/tests/test_reconcile.py @@ -0,0 +1,255 @@ +import asyncio +import io +import json +import unittest +from contextlib import redirect_stdout +from datetime import datetime, timedelta, timezone +from unittest.mock import AsyncMock, patch + +from scripts import reconcile as reconciler + + +class ReconcileTests(unittest.IsolatedAsyncioTestCase): + async def test_dry_run_detects_orphan_without_deleting(self): + key = "reconciliation-test/orphan.png" + old_time = datetime.now(timezone.utc) - timedelta(hours=48) + output = io.StringIO() + + with ( + patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db, + patch.object(reconciler, "list_s3_objects", return_value={key: old_time}), + patch.object(reconciler, "remove_object") as remove, + patch("scripts.reconcile.engine") as mock_engine, + redirect_stdout(output), + ): + mock_engine.dispose = AsyncMock() + db.return_value = set() + result = await reconciler.reconcile(repair=False, grace_hours=24) + + report = json.loads(output.getvalue()) + + self.assertEqual(result, 0) + self.assertEqual(report["mode"], "dry-run") + self.assertEqual(report["orphan_objects"], [key]) + self.assertEqual(report["deleted_objects"], []) + remove.assert_not_called() + + async def test_repair_preserves_recent_orphan(self): + key = "reconciliation-test/recent-orphan.png" + recent_time = datetime.now(timezone.utc) + output = io.StringIO() + + with ( + patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db, + patch.object(reconciler, "list_s3_objects", return_value={key: recent_time}), + patch.object(reconciler, "remove_object") as remove, + patch("scripts.reconcile.engine") as mock_engine, + redirect_stdout(output), + ): + mock_engine.dispose = AsyncMock() + db.return_value = set() + result = await reconciler.reconcile(repair=True, grace_hours=24) + + report = json.loads(output.getvalue()) + + self.assertEqual(result, 0) + self.assertEqual(report["orphan_objects"], [key]) + self.assertEqual(report["deleted_objects"], []) + self.assertEqual( + report["skipped_objects"], + [{"key": key, "reason": "grace_period"}], + ) + remove.assert_not_called() + + async def test_repair_preserves_registered_attachment(self): + key = "attachments/test/protected.png" + old_time = datetime.now(timezone.utc) - timedelta(hours=48) + output = io.StringIO() + + with ( + patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db, + patch.object(reconciler, "list_s3_objects", return_value={key: old_time}), + patch.object(reconciler, "remove_object") as remove, + patch("scripts.reconcile.engine") as mock_engine, + redirect_stdout(output), + ): + mock_engine.dispose = AsyncMock() + db.return_value = {key} + result = await reconciler.reconcile(repair=True, grace_hours=24) + + report = json.loads(output.getvalue()) + + self.assertEqual(result, 0) + self.assertEqual(report["database_objects"], 1) + self.assertEqual(report["storage_objects"], 1) + self.assertEqual(report["orphan_objects"], []) + self.assertEqual(report["missing_objects"], []) + self.assertEqual(report["deleted_objects"], []) + remove.assert_not_called() + + async def test_repair_preserves_newly_registered_attachment(self): + key = "attachments/test/concurrent.png" + old_time = datetime.now(timezone.utc) - timedelta(hours=48) + output = io.StringIO() + + with ( + patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db, + patch.object(reconciler, "list_s3_objects", return_value={key: old_time}), + patch.object(reconciler, "db_key_exists", new_callable=AsyncMock) as exists, + patch.object(reconciler, "remove_object") as remove, + patch("scripts.reconcile.engine") as mock_engine, + redirect_stdout(output), + ): + mock_engine.dispose = AsyncMock() + db.return_value = set() + exists.return_value = True + result = await reconciler.reconcile(repair=True, grace_hours=24) + + report = json.loads(output.getvalue()) + + self.assertEqual(result, 0) + self.assertEqual(report["orphan_objects"], [key]) + self.assertEqual(report["deleted_objects"], []) + self.assertEqual( + report["skipped_objects"], + [{"key": key, "reason": "database_record_exists"}], + ) + exists.assert_awaited_once_with(key) + remove.assert_not_called() + + async def test_repair_preserves_updated_object(self): + key = "reconciliation-test/updated-object.png" + old_time = datetime.now(timezone.utc) - timedelta(hours=48) + recent_time = datetime.now(timezone.utc) + output = io.StringIO() + + with ( + patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db, + patch.object(reconciler, "list_s3_objects", return_value={key: old_time}), + patch.object(reconciler, "db_key_exists", new_callable=AsyncMock) as exists, + patch.object(reconciler, "inspect_object", return_value={"LastModified": recent_time}) as inspect, + patch.object(reconciler, "remove_object") as remove, + patch("scripts.reconcile.engine") as mock_engine, + redirect_stdout(output), + ): + mock_engine.dispose = AsyncMock() + db.return_value = set() + exists.return_value = False + result = await reconciler.reconcile(repair=True, grace_hours=24) + + report = json.loads(output.getvalue()) + + self.assertEqual(result, 0) + self.assertEqual(report["orphan_objects"], [key]) + self.assertEqual(report["deleted_objects"], []) + self.assertEqual( + report["skipped_objects"], + [{"key": key, "reason": "object_too_recent"}], + ) + exists.assert_awaited_once_with(key) + inspect.assert_called_once_with(key) + remove.assert_not_called() + + async def test_repair_deletes_old_orphan(self): + key = "reconciliation-test/old-orphan.png" + old_time = datetime.now(timezone.utc) - timedelta(hours=48) + output = io.StringIO() + + with ( + patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db, + patch.object(reconciler, "list_s3_objects", return_value={key: old_time}), + patch.object(reconciler, "db_key_exists", new_callable=AsyncMock) as exists, + patch.object(reconciler, "inspect_object", return_value={"LastModified": old_time}) as inspect, + patch.object(reconciler, "remove_object") as remove, + patch("scripts.reconcile.engine") as mock_engine, + redirect_stdout(output), + ): + mock_engine.dispose = AsyncMock() + db.return_value = set() + exists.return_value = False + result = await reconciler.reconcile(repair=True, grace_hours=24) + + report = json.loads(output.getvalue()) + + self.assertEqual(result, 0) + self.assertEqual(report["orphan_objects"], [key]) + self.assertEqual(report["deleted_objects"], [key]) + self.assertEqual(report["skipped_objects"], []) + self.assertEqual(exists.await_count, 2) + inspect.assert_called_once_with(key) + remove.assert_called_once_with(key) + + async def test_repair_preserves_missing_object_metadata(self): + key = "reconciliation-test/missing-object.png" + output = io.StringIO() + + with ( + patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db, + patch.object(reconciler, "list_s3_objects", return_value={}), + patch.object(reconciler, "remove_object") as remove, + patch("scripts.reconcile.engine") as mock_engine, + redirect_stdout(output), + ): + mock_engine.dispose = AsyncMock() + db.return_value = {key} + result = await reconciler.reconcile(repair=True, grace_hours=24) + + report = json.loads(output.getvalue()) + + self.assertEqual(result, 0) + self.assertEqual(report["database_objects"], 1) + self.assertEqual(report["storage_objects"], 0) + self.assertEqual(report["orphan_objects"], []) + self.assertEqual(report["missing_objects"], [key]) + self.assertEqual(report["deleted_objects"], []) + remove.assert_not_called() + + async def test_repair_is_idempotent(self): + key = "reconciliation-test/idempotent-orphan.png" + old_time = datetime.now(timezone.utc) - timedelta(hours=48) + objects = {key: old_time} + deleted = [] + reports = [] + + def fake_list_s3_objects(): + return dict(objects) + + def fake_inspect_object(candidate): + return {"LastModified": objects[candidate]} + + def fake_remove_object(candidate): + deleted.append(candidate) + del objects[candidate] + + with ( + patch.object(reconciler, "list_db_keys", new_callable=AsyncMock) as db, + patch.object(reconciler, "list_s3_objects", side_effect=fake_list_s3_objects), + patch.object(reconciler, "db_key_exists", new_callable=AsyncMock) as exists, + patch.object(reconciler, "inspect_object", side_effect=fake_inspect_object), + patch.object(reconciler, "remove_object", side_effect=fake_remove_object), + patch("scripts.reconcile.engine") as mock_engine, + ): + mock_engine.dispose = AsyncMock() + db.return_value = set() + exists.return_value = False + + for _ in range(2): + output = io.StringIO() + + with redirect_stdout(output): + result = await reconciler.reconcile( + repair=True, + grace_hours=24, + ) + + self.assertEqual(result, 0) + reports.append(json.loads(output.getvalue())) + + self.assertEqual(reports[0]["deleted_objects"], [key]) + self.assertEqual(reports[1]["orphan_objects"], []) + self.assertEqual(reports[1]["deleted_objects"], []) + self.assertEqual(deleted, [key]) + self.assertEqual(objects, {}) + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_upload_compensation.py b/tests/test_upload_compensation.py new file mode 100644 index 00000000..7ef86b4b --- /dev/null +++ b/tests/test_upload_compensation.py @@ -0,0 +1,144 @@ +import asyncio +import unittest +from unittest.mock import AsyncMock, MagicMock, patch +from uuid import uuid4 + +from src.main import upload_attachment_endpoint + + +class UploadCompensationTests(unittest.IsolatedAsyncioTestCase): + async def run_failure_scenario( + self, + failure_stage, + verification_result=False, + verification_error=None, + ): + chat_id = uuid4() + user_id = uuid4() + uploaded_keys = [] + deleted_keys = [] + + request = MagicMock() + request.headers = {"content-type": "image/png"} + + async def stream(): + yield b"test-image" + + request.stream = stream + + user = MagicMock() + user.id = user_id + + session = MagicMock() + session.commit = AsyncMock() + session.rollback = AsyncMock() + + async def fake_put_object(key, body, content_type): + uploaded_keys.append(key) + + async def fake_delete_object(key): + deleted_keys.append(key) + + with ( + patch("src.main.get_chat_by_id", new_callable=AsyncMock) as get_chat, + patch("src.main.validate_image", return_value=(10, "test-sha256")), + patch("src.main.put_object", side_effect=fake_put_object), + patch("src.main.create_attachment", new_callable=AsyncMock) as create, + patch("src.main.delete_object", side_effect=fake_delete_object), + patch("src.main.SessionFactory") as session_factory, + patch("src.main.attachment_key_exists", new_callable=AsyncMock) as exists, + ): + get_chat.return_value = MagicMock() + + verification_session = AsyncMock() + session_factory.return_value.__aenter__.return_value = verification_session + + if verification_error is not None: + exists.side_effect = verification_error + else: + exists.return_value = verification_result + + if failure_stage == "insert": + create.side_effect = RuntimeError("Simulated INSERT failure") + expected_error = RuntimeError + elif failure_stage == "commit": + create.return_value = MagicMock() + session.commit.side_effect = RuntimeError("Simulated COMMIT failure") + expected_error = RuntimeError + elif failure_stage == "cancel": + create.side_effect = asyncio.CancelledError() + expected_error = asyncio.CancelledError + else: + raise ValueError("Unknown failure stage") + + with self.assertRaises(expected_error): + await upload_attachment_endpoint( + chat_id=chat_id, + request=request, + filename="test.png", + current_user=user, + session=session, + ) + + self.assertEqual(len(uploaded_keys), 1) + self.assertTrue( + uploaded_keys[0].startswith(f"attachments/{chat_id}/") + ) + session.rollback.assert_awaited_once() + exists.assert_awaited_once_with( + verification_session, + uploaded_keys[0], + ) + + if failure_stage == "commit": + session.commit.assert_awaited_once() + else: + session.commit.assert_not_awaited() + + return uploaded_keys, deleted_keys + + async def test_insert_failure_deletes_unregistered_object(self): + uploaded, deleted = await self.run_failure_scenario( + failure_stage="insert", + verification_result=False, + ) + + self.assertEqual(deleted, uploaded) + + async def test_commit_failure_deletes_unregistered_object(self): + uploaded, deleted = await self.run_failure_scenario( + failure_stage="commit", + verification_result=False, + ) + + self.assertEqual(deleted, uploaded) + + async def test_cancellation_deletes_unregistered_object(self): + uploaded, deleted = await self.run_failure_scenario( + failure_stage="cancel", + verification_result=False, + ) + + self.assertEqual(deleted, uploaded) + + async def test_commit_failure_preserves_registered_object(self): + uploaded, deleted = await self.run_failure_scenario( + failure_stage="commit", + verification_result=True, + ) + + self.assertEqual(len(uploaded), 1) + self.assertEqual(deleted, []) + + async def test_database_unavailable_preserves_object(self): + uploaded, deleted = await self.run_failure_scenario( + failure_stage="commit", + verification_error=ConnectionError("Database unavailable"), + ) + + self.assertEqual(len(uploaded), 1) + self.assertEqual(deleted, []) + + +if __name__ == "__main__": + unittest.main() -- 2.54.0 From ec4cf93b04506aba30f7ce8ec382edfac5b19a90 Mon Sep 17 00:00:00 2001 From: casablanca Date: Thu, 29 Oct 2026 03:08:58 +0300 Subject: [PATCH 3/5] =?UTF-8?q?=D0=A4=D0=B8=D0=BD=D0=B0=D0=BB=D0=B8=D0=B7?= =?UTF-8?q?=D0=B0=D1=86=D0=B8=D1=8F=20=D0=BE=D1=82=D1=87=D1=91=D1=82=D0=B0?= =?UTF-8?q?=20=D0=BB=D0=B0=D0=B1=D0=BE=D1=80=D0=B0=D1=82=D0=BE=D1=80=D0=BD?= =?UTF-8?q?=D0=BE=D0=B9=204?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- REPORT.md | 38 +++++++++++++++++++++----------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/REPORT.md b/REPORT.md index 1cdc31d1..df29b1d7 100644 --- a/REPORT.md +++ b/REPORT.md @@ -3,7 +3,7 @@ - **Автор, группа:** Станислав Травкин, группа: БВТ2304. - **Целевая оценка:** 5. - **Выбранный трек оценки 5:** трек 2 — Two-store reconciliation (сверка метаданных PostgreSQL и объектов S3). -- **Commit/PR:** указать после финального коммита и публикации. +- **Git:** ветка `solution/bvt2304-travkin`; опубликованный коммит реализации `0ef8d739d7c843ac82f3843f11321d8732580a07`. Финальный коммит с отчётом будет опубликован в той же ветке. **PR:** создаётся после публикации финальных изменений. - **Использованные источники, библиотеки и помощь ИИ:** README и методические требования лабораторной работы; Python 3.13, FastAPI, SQLAlchemy, Alembic, PostgreSQL, Redis, boto3, Pillow, MinIO, Nginx, Docker Compose. ChatGPT использовался для обсуждения архитектуры, реализации, диагностики ошибок, подготовки тестовых сценариев и отчёта. Реализация проверялась запуском тестов и экспериментами в локальном окружении. ## Запуск из чистого clone @@ -22,7 +22,7 @@ | Nginx | `nginx:1.29-alpine` | | API и миграции | Локальная сборка из `Dockerfile` | -Для запуска необходимы Docker Engine, Docker Compose, Python с зависимостями проекта и свободные локальные порты 8080 и 9001. +Для запуска необходимы Docker Engine, Docker Compose, Python 3.13, Bash и свободные локальные порты 8080 и 9001. Порт 9001 публикуется только на `127.0.0.1`; API MinIO доступен внутри сети Compose. ### Подготовка @@ -35,23 +35,17 @@ pip install -r requirements.txt pip install -r requirements-dev.txt ``` -Оператор должен создать каталог `secrets` и семь файлов: +Подготовить локальные секреты и конфигурацию командой: -```text -secrets/postgres_password -secrets/database_url -secrets/cache_url -secrets/minio_root_user -secrets/minio_root_password -secrets/s3_access_key_id -secrets/s3_secret_access_key +```bash +./scripts/bootstrap.sh ``` -Содержимое файлов задаётся локально и не публикуется в репозитории. +Скрипт создаёт каталог `secrets/` и семь файлов: `postgres_password`, `database_url`, `cache_url`, `minio_root_user`, `minio_root_password`, `s3_access_key_id`, `s3_secret_access_key`. Для отсутствующих секретов генерируются значения, а уже существующие непустые файлы сохраняются. `database_url` создаётся со значением для пользователя PostgreSQL `lab2` и паролем из `postgres_password`; `cache_url` указывает на Redis. Учётные данные S3-приложения отличаются от административных данных MinIO. -`database_url` содержит строку подключения к PostgreSQL с тем же паролем, который указан в `postgres_password`. `cache_url` содержит строку подключения к Redis. Учётные данные S3-приложения должны отличаться от учётных данных администратора MinIO. +Скрипт также копирует `.env.example` в `.env`, если локального `.env` ещё нет, и выполняет `docker compose config --quiet`. Параметры реального стенда задаются главным образом через `environment` в `compose.yaml`, а секреты подключаются как файлы `/run/secrets`. Вручную заполнять `.env` для текущего Compose не требуется. -Файл `.env.example` является справочным описанием параметров. В текущей реализации Docker Compose передаёт настройки контейнерам непосредственно через `environment`, а секреты — через файлы в `/run/secrets`. Создание `.env` не требуется для запуска представленного `compose.yaml`. +**Важно:** текущий bootstrap устанавливает для файлов `secrets/*` режим `644`, то есть локальные пользователи хоста могут получить право чтения. Это учебное ограничение: каталог имеет режим `700`, но права файлов следует ужесточить для многопользовательского хоста, предварительно обеспечив доступ непривилегированным контейнерам. Не публиковать содержимое `secrets/`, `.env`, пароли и токены. При повторном запуске на уже заполненных томах PostgreSQL/MinIO нельзя бездумно менять согласованные учётные данные. ### Сборка и запуск @@ -76,6 +70,14 @@ docker compose run --rm migrate alembic current ### Проверка +После запуска дождаться готовности API: + +```bash +curl --fail http://localhost:8080/health/ready +``` + +Затем выполнить: + ```bash make check make validate @@ -212,7 +214,7 @@ PostgreSQL и MinIO не участвуют в общей распределён | Проверка OpenAPI | `make validate` | PASS | `scripts/validate_openapi.py`, `REPORT.md` | | Две API-реплики | `docker compose ps api-1 api-2` | Обе реплики healthy | `compose.yaml`, `REPORT.md` | | PostgreSQL и Redis | `docker compose ps -a` | Хранилища healthy | `compose.yaml`, `REPORT.md` | -| Приватное S3-хранилище | Анонимный запрос списка объектов бакета | HTTP 403 AccessDenied | `infra/minio/attachments-policy.json`, `REPORT.md` | +| Приватное S3-хранилище | Анонимный запрос списка объектов бакета | HTTP 403 AccessDenied; прямой анонимный GET оригинала также должен быть запрещён | `infra/minio/attachments-policy.json`, `REPORT.md` | | Ограниченные права приложения | Запрос политики бакета от имени S3-приложения | HTTP 403 AccessDenied | `infra/minio/attachments-policy.json`, `REPORT.md` | | Идемпотентный bootstrap | Повторный `docker compose run --rm s3-init` | Успешное выполнение, существующие объекты сохранены | `infra/minio/init.sh`, `REPORT.md` | | Повторные миграции | `docker compose run --rm migrate` | Успешно; схема на head | `migrations/versions/`, `REPORT.md` | @@ -269,7 +271,7 @@ PostgreSQL и MinIO не участвуют в общей распределён | MinIO | 1 | 512 МиБ | | Nginx | 0,5 | 256 МиБ | -Модель процессора хост-машины, выделенная память WSL2 и показатели CPU во время нагрузочного теста отдельно не фиксировались. +Модель процессора хост-машины, выделенная память WSL2, показатели CPU во время нагрузочного теста и отдельная длительность прогрева не фиксировались. Эксперименты выполнялись в локальном учебном окружении; независимая проверка запуска на другом хосте не проводилась. ### Нагрузочный тест API @@ -379,7 +381,9 @@ max_ms: 46.378 7. **Профиль reconciliation ограничен двумя размерами набора.** Для оценки масштабируемости нужны дополнительные точки, большие объёмы данных и повторения на разных состояниях хранилища. -8. **Не реализованы распределённые блокировки и фоновое расписание reconciliation.** Утилита запускается оператором. Для производственного применения целесообразны планировщик, аудит удалений, метрики, оповещения и резервное копирование. +8. **Локальные секреты создаются с правами `644`.** Каталог `secrets/` ограничен режимом `700`, однако для многопользовательского хоста требуются более строгие права файлов и согласованная схема доступа контейнеров. + +9. **Не реализованы распределённые блокировки и фоновое расписание reconciliation.** Утилита запускается оператором. Для производственного применения целесообразны планировщик, аудит удалений, метрики, оповещения и резервное копирование. ## Демонстрация преподавателю -- 2.54.0 From cb17d6750562ed93b7fbbc65248d963f971f44ea Mon Sep 17 00:00:00 2001 From: casablanca Date: Thu, 29 Oct 2026 03:13:20 +0300 Subject: [PATCH 4/5] =?UTF-8?q?=D0=A3=D1=82=D0=BE=D1=87=D0=BD=D0=B5=D0=BD?= =?UTF-8?q?=D0=B8=D0=B5=20=D0=BD=D0=B0=D0=B7=D0=B2=D0=B0=D0=BD=D0=B8=D1=8F?= =?UTF-8?q?=20=D0=B2=D1=8B=D0=B1=D1=80=D0=B0=D0=BD=D0=BD=D0=BE=D0=B3=D0=BE?= =?UTF-8?q?=20=D1=82=D1=80=D0=B5=D0=BA=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- REPORT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/REPORT.md b/REPORT.md index df29b1d7..bf2de9ee 100644 --- a/REPORT.md +++ b/REPORT.md @@ -2,7 +2,7 @@ - **Автор, группа:** Станислав Травкин, группа: БВТ2304. - **Целевая оценка:** 5. -- **Выбранный трек оценки 5:** трек 2 — Two-store reconciliation (сверка метаданных PostgreSQL и объектов S3). +- **Выбранный трек оценки 5:** трек 2 — Согласованность двух хранилищ. - **Git:** ветка `solution/bvt2304-travkin`; опубликованный коммит реализации `0ef8d739d7c843ac82f3843f11321d8732580a07`. Финальный коммит с отчётом будет опубликован в той же ветке. **PR:** создаётся после публикации финальных изменений. - **Использованные источники, библиотеки и помощь ИИ:** README и методические требования лабораторной работы; Python 3.13, FastAPI, SQLAlchemy, Alembic, PostgreSQL, Redis, boto3, Pillow, MinIO, Nginx, Docker Compose. ChatGPT использовался для обсуждения архитектуры, реализации, диагностики ошибок, подготовки тестовых сценариев и отчёта. Реализация проверялась запуском тестов и экспериментами в локальном окружении. -- 2.54.0 From ef7b5bf1c39a5f1a911dbddb0ebbc510f9dc971e Mon Sep 17 00:00:00 2001 From: casablanca Date: Thu, 29 Oct 2026 12:49:19 +0300 Subject: [PATCH 5/5] =?UTF-8?q?=D1=84=D0=B8=D0=BA=D1=81=20=D1=80=D0=B5?= =?UTF-8?q?=D0=BF=D0=BE=D1=80=D1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- REPORT.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 62 insertions(+), 6 deletions(-) diff --git a/REPORT.md b/REPORT.md index bf2de9ee..f3cf907b 100644 --- a/REPORT.md +++ b/REPORT.md @@ -127,7 +127,9 @@ docker compose down -v ## Архитектура и решения -### Схема компонентов +### Оценка 3 — базовая функциональность + +#### Схема компонентов ```text Клиент @@ -154,11 +156,17 @@ Nginx распределяет запросы между двумя экземп PostgreSQL является источником истины для регистрации вложений и их принадлежности чатам. S3 хранит бинарные данные, адресуемые через `s3_key`. -### Что перенесено из лабораторной 3 +**Что мы сделали и зачем.** Сохранили две одинаковые реплики FastAPI за Nginx: запрос пользователя может попасть на любую из них, потому что данные не привязаны к памяти конкретного процесса. PostgreSQL хранит структурированную информацию, Redis — сессии авторизации, а MinIO — сами файлы изображений. Такое разделение позволяет не записывать большие бинарные файлы в таблицы сообщений и использовать единое хранилище вложений для обеих реплик. + +**Как проходит запрос с вложением.** Пользователь обращается к Nginx, тот направляет запрос на одну из API-реплик. API проверяет сессию и участие пользователя в чате, принимает и проверяет изображение, сохраняет его в MinIO и регистрирует метаданные в PostgreSQL. При последующем скачивании API снова проверяет права и получает содержимое из S3 по сохранённому ключу. Клиенту не выдаётся публичный адрес объекта в бакете. + +#### Что перенесено из лабораторной 3 Сохранены пользовательские операции, авторизация через сессии, чаты, сообщения, идемпотентность создания сообщений, две API-реплики, балансировщик Nginx, PostgreSQL и Redis. -### Что добавлено в лабораторной 4 +**Что это означает на практике.** Мы не создавали отдельное приложение только для изображений: расширили существующий мессенджер. Пользователи по-прежнему создают чаты и сообщения, авторизуются через сессии, а повторная отправка запроса с тем же ключом идемпотентности не должна создавать дублирующие сообщения. Существующие маршруты и публичные проверки предыдущей лабораторной сохранены. Это проверяется в том числе командой `make test`. + +#### Что добавлено в лабораторной 4 - Приватное S3-хранилище MinIO с постоянным томом. - Идемпотентная инициализация бакета и ограниченной учётной записи приложения. @@ -170,7 +178,15 @@ PostgreSQL является источником истины для регис - Отдельный reconciler для обнаружения и обработки расхождений между PostgreSQL и MinIO. - Тесты компенсации, безопасной сверки и исправления расхождений. -### Транзакционные границы +**Что относится непосредственно к базовой функциональности оценки 3.** В лабораторной №4 мы добавили возможность загрузить изображение PNG/JPEG размером до 10 МиБ и разрешением до 40 млн пикселей, получить ответ `201 Created`, а затем скачать тот же файл без изменения содержимого. Для контроля целостности сравнивался SHA-256. Запись PostgreSQL содержит метаданные вложения, включая ключ объекта S3; само изображение хранится в MinIO. Вложения можно указать при создании сообщения через `attachment_ids`, но использовать чужое вложение или получить файл из чужого чата нельзя. + +**Как мы это проверяли.** Проверяли успешную загрузку, получение метаданных и файла, совпадение SHA-256, привязку к сообщению, отказ в доступе постороннему пользователю (`404`) и отсутствие доступа без сессии (`401`). Проверяли работу двух реплик и сохранение данных после перезапуска контейнеров с постоянными Docker volumes. Результаты перечислены в таблице «Доказательства критериев» ниже. + +**Что добавлено сверх базового уровня.** Компенсация, обработка отказов, проверки предельных условий и reconciler тоже перечислены выше как части всей лабораторной, но подробнее относятся к оценкам 4 и 5 и раскрываются в следующих подразделах. + +### Оценка 4 — надёжность, безопасность и обработка ошибок + +#### Транзакционные границы PostgreSQL и MinIO не участвуют в общей распределённой транзакции. @@ -182,7 +198,21 @@ PostgreSQL и MinIO не участвуют в общей распределён Это уменьшает риск удаления зарегистрированного вложения, но не обеспечивает атомарность двух хранилищ. Оставшиеся после аварий объекты обнаруживаются reconciler. -### Reconciliation +#### Проверка входных данных и разграничение доступа + +**Что сделали.** Для загрузки предусмотрены проверки имени файла, заявленного MIME-типа и фактического содержимого изображения. Приложение принимает PNG/JPEG, отклоняет неподдерживаемые и повреждённые файлы, а также изображения, превышающие ограничения по размеру и числу пикселей. Доступ к вложению определяется членством в чате, а не одним лишь знанием идентификатора вложения. + +**Что проверили.** Файл больше 10 МиБ и изображение с более чем 40 млн пикселей приводили к `413`; GIF — к `415`; несовпадение MIME-типа и реального формата, а также повреждённый файл — к `400`. Для чужих вложений и недопустимых `attachment_ids` проверялись отказы, перечисленные в таблице доказательств. Приватность S3 проверялась анонимным запросом к бакету (`403 AccessDenied`). + +#### Отказы, компенсация и ограничение ресурсов + +**Зачем нужна компенсация.** Между успешной загрузкой объекта в MinIO и сохранением его метаданных в PostgreSQL возможен сбой. Если запись в БД точно отсутствует, приложение может удалить незарегистрированный объект; если подтвердить это нельзя, безопаснее сохранить объект и позднее обнаружить его reconciler. Для этих ситуаций подготовлены модульные тесты: `make test-compensation` — 5 успешных проверок. + +**Что ещё проверили.** Повторный запуск инициализации S3 не должен удалять существующие объекты; приложение использует отдельные ограниченные S3-учётные данные, а административная консоль MinIO не публикуется как общедоступный сервис. При остановке MinIO загрузка возвращала `503`, после восстановления — `201`. В испытании с десятью параллельными загрузками примерно по 4,13 МиБ все запросы завершились `201`; пиковое потребление API-реплик составило 154,71 и 138,84 МиБ при лимите 512 МиБ, без OOM. Также проверяли отказ одной API-реплики и сохранность данных после перезапуска. Подробные численные результаты приведены ниже в «Экспериментах и отказах». + +### Оценка 5 — трек 2. Согласованность двух хранилищ + +#### Reconciliation Утилита `scripts/reconcile.py` получает список ключей из таблицы `attachments` и перечень объектов S3. @@ -197,6 +227,32 @@ PostgreSQL и MinIO не участвуют в общей распределён Отсутствующие объекты S3 не восстанавливаются автоматически: reconciler сообщает о них, не удаляя метаданные PostgreSQL. +#### Как работает наш reconciler + +**Задача.** PostgreSQL и MinIO — независимые хранилища. После частичного сбоя их состояние может разойтись. Мы написали отдельную утилиту `scripts/reconcile.py`, которая сравнивает зарегистрированные ключи вложений с фактически существующими объектами бакета. + +**Два типа расхождений.** `orphan` — файл уже есть в S3, но соответствующей записи в PostgreSQL нет; такой объект мог остаться после сбоя сохранения метаданных. `missing` — запись в PostgreSQL существует, но файл в S3 отсутствует; например, он был удалён отдельно. В первом случае возможно безопасное удаление устаревшего незарегистрированного объекта, во втором автоматическое удаление записи БД не выполняется, поскольку это уничтожило бы сведения о проблеме. + +**Режимы работы.** `make reconcile` запускает сверку в режиме `dry-run`: выводит JSON с найденными расхождениями, но ничего не меняет. `make reconcile-repair` разрешает исправление устаревших orphan-объектов. По умолчанию действует защитный период 24 часа: свежие объекты не удаляются. Непосредственно перед удалением повторно проверяются наличие записи в PostgreSQL и состояние объекта в S3, в том числе время последнего изменения. + +#### Какие ошибки внедряли и что доказали + +- Создавали объект S3 без записи PostgreSQL: reconciler находил `orphan`. +- Создавали запись PostgreSQL без файла S3: reconciler находил `missing`, не удаляя запись автоматически. +- Проверяли удаление искусственно состаренного orphan-объекта при разрешённом repair. +- Проверяли, что свежие объекты внутри защитного периода сохраняются. +- Проверяли, что объект, зарегистрированный в БД до удаления, не удаляется. +- Проверяли, что изменившийся объект S3 сохраняется благодаря повторной проверке `LastModified`. +- Повторяли сверку после исправления: новых расхождений не оставалось. + +Эти сценарии отражены в `tests/test_reconcile.py` и ручных экспериментах; `make test-reconcile` завершился успешно — 8 тестов. + +#### Стоимость обхода и вывод + +Мы измерили время полной сверки на двух наборах данных, по 10 запусков на каждый: **28 объектов S3** — медиана **5,161 мс**; **128 объектов S3** — медиана **13,029 мс**. При увеличении числа объектов медианное время выросло примерно в **2,52 раза**. Это показывает увеличение стоимости обхода в измеренном диапазоне, но двух точек недостаточно, чтобы утверждать линейную асимптотику. + +**Итог трека 2.** Реализованы обнаружение расхождений двух хранилищ, безопасный режим просмотра, ограниченное автоматическое исправление, защита свежих и зарегистрированных вложений, повторяемость проверки и замеры времени. При этом утилита не восстанавливает потерянные файлы и не гарантирует полную атомарность PostgreSQL и S3 — эти ограничения отдельно указаны ниже. + ### Конфигурация Параметры S3 (`S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`), пути к секретам, `SESSION_TTL_SECONDS`, `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS` передаются через `compose.yaml`. @@ -385,7 +441,7 @@ max_ms: 46.378 9. **Не реализованы распределённые блокировки и фоновое расписание reconciliation.** Утилита запускается оператором. Для производственного применения целесообразны планировщик, аудит удалений, метрики, оповещения и резервное копирование. -## Демонстрация преподавателю +## Демонстрация Все команды выполняются из корня репозитория. Перед демонстрацией должны быть подготовлены локальные секреты и запущены контейнеры. -- 2.54.0