diff --git a/.gitignore b/.gitignore index f101a4f..79b556b 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ .env .env.* !.env.example +/compose.local.yaml secrets/ certs/private/ *.key diff --git a/REPORT.md b/REPORT.md index 9ad2b84..332286d 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,55 @@ # Отчёт — лабораторная 4 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Самохвалов Андрей Ремович, БПИ-2302. +- Целевая оценка: 5, трек 2 «Согласованность двух хранилищ». Пока реализованы перенос lab3 и приватное S3; остальные блоки выполняются далее. +- Ветка: `solution/bpi2302-samohvalov`; commit/PR указываются после публикации. +- Источники: `README.md`, `COURSE.md`, `contracts/README.md`, `contracts/openapi.json`, публичные тесты, [MinIO release](https://github.com/minio/minio/releases/tag/RELEASE.2025-10-15T17-29-55Z), [образ](https://hub.docker.com/r/alpine/minio/tags), документация MinIO для IAM. Python/FastAPI, PostgreSQL, MinIO Python SDK; проект подготовлен с помощью ИИ Codex с локальной проверкой ниже. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Требуются Docker Compose и Python 3.9+. Стенд использует только синтетические данные и слушает `127.0.0.1` на `APP_PORT` (по умолчанию 8080). В репозитории нет паролей: + +```sh +cp .env.example .env +python3 scripts/setup-local-secrets.py +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build --wait --scale api=2 +make check +# make test — после реализации upload в следующем блоке +``` + +`setup-local-secrets.py` создаёт отсутствующие secret-файлы с правами 0600 и не перезаписывает существующие. Миграции выполняет одноразовый `migrate` под PostgreSQL advisory lock. `s3-volume-init` задаёт владельца нового volume, затем MinIO стартует без root; одноразовый `s3-bootstrap` идемпотентно создаёт закрытый bucket и две ограниченные учётные записи. Повторный `docker compose --env-file .env run --rm s3-bootstrap` безопасен. Для остановки — `docker compose --env-file .env down` без `-v`; для намеренного удаления **только учебных данных** после проверки — `docker compose --env-file .env down -v`. + +Версии: Python 3.12.12, PostgreSQL 17.6, HAProxy 3.0.11, MinIO `RELEASE.2025-10-15T17-29-55Z` (образ закреплён digest), MinIO Client `2025.7.21-debian-12-r3` (digest). Проверенный локальный стенд — Colima/arm64 macOS, 2 CPU, 2 054 840 320 байт памяти. Локальная сеть не разрешала DNS `files.pythonhosted.org`, поэтому сборка для проверки использовала **только локальный ignored** `compose.local.yaml` с временным IP CDN; в чистом clone он не нужен при обычном доступе к PyPI. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +Клиент → HAProxy → две API-реплики. PostgreSQL хранит пользователей, сессии, чаты, сообщения, ключи идемпотентности и метаданные вложений. MinIO хранит только байты оригиналов в private bucket `messenger-attachments`; локальная файловая система API не хранит оригиналы. Миграция `004_attachments.sql` связывает вложение с чатом; состав сообщения хранится в `message_attachments` с FK по паре `(id, chat_id)`, чтобы исключить межчатовые ссылки на уровне БД. Статусы таблицы допускают дальнейший переход к асинхронной lab5, но lab4 будет возвращать только `ready` после обеих устойчивых записей. + +| Сервис | Образ/роль | Health и volume | Секреты и доступ | +| --- | --- | --- | --- | +| `lb` | HAProxy 3.0.11, единственный host port | проверка backend, без volume | секретов нет | +| `api ×2` | Python 3.12.12, 0,5 CPU/256 MiB на реплику | `/health/ready`, без volume | только DB URL и ограниченные S3 credentials | +| `postgres` | PostgreSQL 17.6 | `pg_isready`, `postgres_data` | только DB password | +| `migrate` | одноразовый Python | завершение 0 | только DB URL | +| `s3` | MinIO security release, 0,5 CPU/384 MiB | `/minio/health/ready`, `s3_data` | только root credentials, наружный порт и консоль не опубликованы | +| `s3-bootstrap` | одноразовый MinIO Client | завершение 0 | root и создаваемые ограниченные credentials | +| `s3-volume-init` | одноразовая настройка владельца volume | завершение 0 | секретов нет | + +`infra/minio-api-policy.json` разрешает только операции над объектами одного bucket и чтение его location; создание bucket, изменение IAM и административные операции не разрешены. Отдельная maintenance policy добавляет list для будущей сверки. Bucket не имеет анонимного чтения. Приватность bucket не заменяет проверку членства в чате на API: эта проверка добавляется в блоках upload/download. ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +| Критерий README | Команда/сценарий | Наблюдаемый результат | Доказательство | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | - -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +| Перенос lab3 | Compose ×2, текстовая часть `make test`, `make test-persistence`, адресный failover обеих реплик | Текстовый API совместим, прежний токен/сообщение после restart; восстановление записи после остановки каждой реплики 3,123 и 3,149 с | локальные тесты U1; полный smoke остановился на ещё не реализованном upload | +| Приватный S3 и bootstrap | `docker compose run --rm s3-bootstrap` дважды; `docker compose exec -T api python - < student-tests/test_storage_bootstrap.py` | Два повтора завершились 0; S3 PUT/GET ограниченным API пользователем совпадают по байтам, анонимный GET — 403, создание чужого bucket — AccessDenied | `evidence/storage-bootstrap-2026-10-02.txt` | +| Миграция и транзакции | `docker compose exec -T api python - < student-tests/test_database.py`; `... test_auth.py` | Миграции 1–4 применены повторяемо, 2 DB и 3 auth теста PASS | `evidence/storage-bootstrap-2026-10-02.txt` | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. - -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +Запись S3/БД, компенсация после ошибки, ACL, failover файла, параллельные upload и reconciler ещё должны быть проверены. Пока `GET /health/ready` отражает обязательную PostgreSQL зависимость, а готовность MinIO проверяет Compose при запуске; после появления attachment path доступность S3 будет явно учтена в сценариях. ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +Полный `make test` сейчас ожидаемо получает 415 на `POST attachments`: синхронный upload, скачивание и привязка ещё не реализованы. Проверки уровня 4 и трека 5 не заявляются завершёнными до отдельных fault tests и воспроизводимых измерений. Один MinIO/PostgreSQL/LB и один Docker-host остаются одиночными точками отказа. Локальный HTTP допустим только для изолированного стенда с синтетическими данными; удалённой демонстрации нужен TLS. diff --git a/compose.yaml b/compose.yaml index e91d213..982f3ff 100644 --- a/compose.yaml +++ b/compose.yaml @@ -26,6 +26,54 @@ services: condition: service_healthy restart: "no" + s3-volume-init: + image: alpine/minio:RELEASE.2025-10-15T17-29-55Z@sha256:cf23643a6cf9ce159c57643ceb88279e431262282428c9e0bf3a7ef1a97e84b4 + user: "0:0" + entrypoint: ["/bin/sh", "-c"] + command: ["chown -R 100:100 /data"] + volumes: [s3_data:/data] + restart: "no" + + s3: + image: alpine/minio:RELEASE.2025-10-15T17-29-55Z@sha256:cf23643a6cf9ce159c57643ceb88279e431262282428c9e0bf3a7ef1a97e84b4 + 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] + volumes: [s3_data:/data] + depends_on: + s3-volume-init: + condition: service_completed_successfully + healthcheck: + test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:9000/minio/health/ready"] + interval: 2s + timeout: 2s + retries: 30 + cpus: 0.5 + mem_limit: 384m + + s3-bootstrap: + image: bitnamilegacy/minio-client:2025.7.21-debian-12-r3@sha256:73bd39f7899a0cef12b8dd5df13aa93a3ed1aaa44236542442e9ac76819ac158 + user: "0:0" + entrypoint: ["/bin/sh", "/bootstrap.sh"] + command: [] + volumes: + - ./infra/bootstrap-s3.sh:/bootstrap.sh:ro + - ./infra/minio-api-policy.json:/policies/minio-api-policy.json:ro + - ./infra/minio-maintenance-policy.json:/policies/minio-maintenance-policy.json:ro + secrets: + - minio_root_user + - minio_root_password + - s3_access_key_id + - s3_secret_access_key + - s3_maintenance_key_id + - s3_maintenance_secret_key + depends_on: + s3: + condition: service_healthy + restart: "no" + api: build: . scale: 2 @@ -34,10 +82,16 @@ services: APP_PORT: 8080 DATABASE_URL_FILE: /run/secrets/database_url SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} - secrets: [database_url] + S3_ENDPOINT: s3:9000 + 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 + secrets: [database_url, s3_access_key_id, s3_secret_access_key] depends_on: migrate: condition: service_completed_successfully + s3-bootstrap: + condition: service_completed_successfully healthcheck: test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2).close()"] interval: 2s @@ -65,6 +119,19 @@ secrets: file: ./secrets/postgres_password database_url: file: ./secrets/database_url + minio_root_user: + file: ./secrets/minio_root_user + minio_root_password: + file: ./secrets/minio_root_password + s3_access_key_id: + file: ./secrets/s3_access_key_id + s3_secret_access_key: + file: ./secrets/s3_secret_access_key + s3_maintenance_key_id: + file: ./secrets/s3_maintenance_key_id + s3_maintenance_secret_key: + file: ./secrets/s3_maintenance_secret_key volumes: postgres_data: + s3_data: diff --git a/evidence/storage-bootstrap-2026-10-02.txt b/evidence/storage-bootstrap-2026-10-02.txt new file mode 100644 index 0000000..aeb9b8d --- /dev/null +++ b/evidence/storage-bootstrap-2026-10-02.txt @@ -0,0 +1,12 @@ +Lab 4 U2 local Colima/arm64; 2 CPU, 2054840320 bytes RAM; synthetic data only. +Image: alpine/minio:RELEASE.2025-10-15T17-29-55Z, digest sha256:cf23643a6cf9ce159c57643ceb88279e431262282428c9e0bf3a7ef1a97e84b4. +The official minio/minio tag could not be pulled (repository unavailable); pinned alpine/minio security-release build was used. +Build used ignored local compose.local.yaml with temporary PyPI CDN DNS override; ordinary compose.yaml remains independent of this host workaround. + +docker compose --env-file .env config --quiet: PASS. +docker compose --env-file .env up -d --wait --scale api=2: PASS after adding one-time s3-volume-init for non-root MinIO write permissions. +docker compose --env-file .env run --rm s3-bootstrap: PASS, repeated twice after initial bootstrap, no duplicate/failure. +docker compose --env-file .env exec -T api python - < student-tests/test_storage_bootstrap.py: 1 PASS; PUT/GET exact bytes, anonymous GET 403, foreign bucket create AccessDenied. +docker compose --env-file .env exec -T api python - < student-tests/test_database.py: 2 PASS; migrations 1-4, race/rollback/keyset history. +docker compose --env-file .env exec -T api python - < student-tests/test_auth.py: 3 PASS; Basic/Bearer and short TTL. +No credentials, session tokens or object keys are included in this evidence. diff --git a/infra/bootstrap-s3.sh b/infra/bootstrap-s3.sh new file mode 100644 index 0000000..becaf21 --- /dev/null +++ b/infra/bootstrap-s3.sh @@ -0,0 +1,16 @@ +#!/bin/sh +set -eu + +read_secret() { + tr -d '\n' < "/run/secrets/$1" +} + +mc alias set local http://s3:9000 "$(read_secret minio_root_user)" "$(read_secret minio_root_password)" >/dev/null +mc mb --ignore-existing local/messenger-attachments >/dev/null +mc anonymous set none local/messenger-attachments >/dev/null +mc admin policy create local messenger-api /policies/minio-api-policy.json >/dev/null +mc admin policy create local messenger-maintenance /policies/minio-maintenance-policy.json >/dev/null +mc admin user add local "$(read_secret s3_access_key_id)" "$(read_secret s3_secret_access_key)" >/dev/null +mc admin policy attach local messenger-api --user "$(read_secret s3_access_key_id)" >/dev/null +mc admin user add local "$(read_secret s3_maintenance_key_id)" "$(read_secret s3_maintenance_secret_key)" >/dev/null +mc admin policy attach local messenger-maintenance --user "$(read_secret s3_maintenance_key_id)" >/dev/null diff --git a/infra/minio-api-policy.json b/infra/minio-api-policy.json new file mode 100644 index 0000000..54be94d --- /dev/null +++ b/infra/minio-api-policy.json @@ -0,0 +1,15 @@ +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": ["s3:GetBucketLocation"], + "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-maintenance-policy.json b/infra/minio-maintenance-policy.json new file mode 100644 index 0000000..6beb6bd --- /dev/null +++ b/infra/minio-maintenance-policy.json @@ -0,0 +1,15 @@ +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": ["s3:GetBucketLocation", "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/migrations/004_attachments.sql b/migrations/004_attachments.sql new file mode 100644 index 0000000..576f30b --- /dev/null +++ b/migrations/004_attachments.sql @@ -0,0 +1,32 @@ +CREATE TABLE attachments ( + id uuid PRIMARY KEY, + chat_id uuid NOT NULL REFERENCES chats(id) ON DELETE CASCADE, + filename text NOT NULL, + object_key text NOT NULL UNIQUE, + content_type text NOT NULL CHECK (content_type IN ('image/png', 'image/jpeg')), + size_bytes bigint NOT NULL CHECK (size_bytes BETWEEN 1 AND 10485760), + sha256 text NOT NULL CHECK (sha256 ~ '^[0-9a-f]{64}$'), + status text NOT NULL DEFAULT 'ready' CHECK (status IN ('queued', 'processing', 'ready', 'failed')), + error_code text, + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + UNIQUE (id, chat_id) +); + +CREATE INDEX attachments_chat_idx ON attachments (chat_id, created_at); + +ALTER TABLE messages DROP CONSTRAINT messages_text_check; +ALTER TABLE messages ADD CONSTRAINT messages_text_check CHECK (char_length(text) BETWEEN 0 AND 4000); +ALTER TABLE messages ADD CONSTRAINT messages_id_chat_unique UNIQUE (id, chat_id); + +CREATE TABLE message_attachments ( + message_id uuid NOT NULL, + chat_id uuid NOT NULL, + attachment_id uuid NOT NULL, + position smallint NOT NULL CHECK (position BETWEEN 0 AND 9), + PRIMARY KEY (message_id, attachment_id), + UNIQUE (message_id, position), + FOREIGN KEY (message_id, chat_id) REFERENCES messages(id, chat_id) ON DELETE CASCADE, + FOREIGN KEY (attachment_id, chat_id) REFERENCES attachments(id, chat_id) +); + +CREATE INDEX message_attachments_attachment_idx ON message_attachments (attachment_id); diff --git a/requirements.txt b/requirements.txt index 58563cf..882107d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,3 +4,4 @@ uvicorn==0.38.0 psycopg[binary,pool]==3.2.12 psycopg-pool==3.3.3 argon2-cffi==25.1.0 +minio==7.2.20 diff --git a/scripts/setup-local-secrets.py b/scripts/setup-local-secrets.py new file mode 100644 index 0000000..8692470 --- /dev/null +++ b/scripts/setup-local-secrets.py @@ -0,0 +1,42 @@ +"""Create local Compose secrets without printing or overwriting existing values.""" + +import os +import secrets +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] / "secrets" + + +def write(name: str, value: str) -> None: + fd = os.open(ROOT / name, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600) + with os.fdopen(fd, "w") as out: + out.write(value) + + +def main() -> None: + ROOT.mkdir(mode=0o700, exist_ok=True) + db_names = {"postgres_password", "database_url"} + s3_names = { + "minio_root_user", "minio_root_password", "s3_access_key_id", "s3_secret_access_key", + "s3_maintenance_key_id", "s3_maintenance_secret_key", + } + for names in (db_names, s3_names): + existing = {name for name in names if (ROOT / name).exists()} + if existing and existing != names: + raise SystemExit(f"Incomplete secret group: {', '.join(sorted(names - existing))}") + if not (ROOT / "postgres_password").exists(): + password = secrets.token_urlsafe(32) + write("postgres_password", password) + write("database_url", f"postgresql://messenger:{password}@postgres:5432/messenger") + if not (ROOT / "minio_root_user").exists(): + write("minio_root_user", "lab4admin") + write("minio_root_password", secrets.token_urlsafe(32)) + write("s3_access_key_id", secrets.token_hex(10)) + write("s3_secret_access_key", secrets.token_urlsafe(32)) + write("s3_maintenance_key_id", secrets.token_hex(10)) + write("s3_maintenance_secret_key", secrets.token_urlsafe(32)) + + +if __name__ == "__main__": + main() diff --git a/src/attachments.py b/src/attachments.py new file mode 100644 index 0000000..8f4e3c6 --- /dev/null +++ b/src/attachments.py @@ -0,0 +1,25 @@ +"""Private S3 access shared by attachment routes and maintenance jobs.""" + +import os +from functools import lru_cache +from pathlib import Path + +from minio import Minio + + +BUCKET = "messenger-attachments" + + +def secret(name: str) -> str: + return Path(os.environ[f"{name}_FILE"]).read_text(encoding="utf-8").strip() + + +@lru_cache(maxsize=1) +def storage() -> Minio: + return Minio( + os.environ.get("S3_ENDPOINT", "s3:9000"), + access_key=secret("S3_ACCESS_KEY_ID"), + secret_key=secret("S3_SECRET_ACCESS_KEY"), + secure=False, + region="us-east-1", + ) diff --git a/student-tests/test_auth.py b/student-tests/test_auth.py index e9fcdf0..ca0031a 100644 --- a/student-tests/test_auth.py +++ b/student-tests/test_auth.py @@ -14,12 +14,13 @@ import urllib.request from uuid import uuid4 import psycopg +from src.db import database_url -URL = os.environ.get("DATABASE_URL") +URL = database_url() if os.environ.get("DATABASE_URL") or os.environ.get("DATABASE_URL_FILE") else None -@unittest.skipUnless(URL, "set DATABASE_URL to a disposable PostgreSQL database") +@unittest.skipUnless(URL, "set DATABASE_URL or DATABASE_URL_FILE to a disposable PostgreSQL database") class AuthTests(unittest.TestCase): @classmethod def setUpClass(cls): diff --git a/student-tests/test_database.py b/student-tests/test_database.py index 132318f..13067ee 100644 --- a/student-tests/test_database.py +++ b/student-tests/test_database.py @@ -9,13 +9,14 @@ from uuid import uuid4 import psycopg +from src.db import database_url from src.store import Store -URL = os.environ.get("DATABASE_URL") +URL = database_url() if os.environ.get("DATABASE_URL") or os.environ.get("DATABASE_URL_FILE") else None -@unittest.skipUnless(URL, "set DATABASE_URL to a disposable PostgreSQL database") +@unittest.skipUnless(URL, "set DATABASE_URL or DATABASE_URL_FILE to a disposable PostgreSQL database") class DatabaseTests(unittest.TestCase): @classmethod def setUpClass(cls): @@ -30,7 +31,7 @@ class DatabaseTests(unittest.TestCase): def test_migration_and_unique_username_race(self): with psycopg.connect(URL) as conn: versions = conn.execute("SELECT version FROM schema_migrations").fetchall() - self.assertEqual(versions, [(1,), (2,), (3,)]) + self.assertEqual(versions, [(1,), (2,), (3,), (4,)]) name = "u_" + uuid4().hex[:16] def register(_): diff --git a/student-tests/test_storage_bootstrap.py b/student-tests/test_storage_bootstrap.py new file mode 100644 index 0000000..726fd51 --- /dev/null +++ b/student-tests/test_storage_bootstrap.py @@ -0,0 +1,38 @@ +"""Run inside an API container after S3 bootstrap.""" + +import io +import unittest +from uuid import uuid4 +from urllib.error import HTTPError +from urllib.request import urlopen + +from minio.error import S3Error + +from src.attachments import BUCKET, storage + + +class StorageBootstrapTests(unittest.TestCase): + def test_private_bucket_and_scoped_api_credentials(self): + client = storage() + key = "test-bootstrap/" + uuid4().hex + data = b"private attachment fixture" + client.put_object(BUCKET, key, io.BytesIO(data), len(data), content_type="application/octet-stream") + try: + response = client.get_object(BUCKET, key) + try: + self.assertEqual(response.read(), data) + finally: + response.close() + response.release_conn() + with self.assertRaises(HTTPError) as denied: + urlopen(f"http://s3:9000/{BUCKET}/{key}", timeout=3) + self.assertEqual(denied.exception.code, 403) + with self.assertRaises(S3Error) as forbidden: + client.make_bucket("forbidden-" + uuid4().hex) + self.assertEqual(forbidden.exception.code, "AccessDenied") + finally: + client.remove_object(BUCKET, key) + + +if __name__ == "__main__": + unittest.main()