schema: spec-driven context: | # Лабораторная 4 «S3-хранилище и вложения» — контекст проекта ## Что это Skeleton лабораторной 4 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение в ветке `solution/bpi2303-kostylev`, построенное переносом решения лабы 3. Skeleton содержит задание (`README.md`), нормативный контракт (`contracts/`, версия 1.4.0) и публичные black-box проверки (`tests/`). Целевая оценка — «5»: весь уровень 4 плюс трек 2 «Согласованность двух хранилищ (reconciler)». ## Границы (менять нельзя) In scope лабы 4: вложения-изображения. Синхронный upload сырых байтов одного PNG/JPEG (`POST /api/v1/chats/{chat_id}/attachments?filename=…`, ≤10 MiB, ≤40 млн пикселей, тип по содержимому, лимиты до неограниченного чтения и декодирования), метаданные вложения в PostgreSQL, байты в приватном bucket S3-совместимого сервера внутри стенда, object key назначает сервер, `201 ready` только после записи объекта и `COMMIT`; метаданные и скачивание оригинала через API только участникам чата; `attachment_ids` в сообщениях; переживание остановки реплики и рестарта стенда; поведение при недоступном S3. Уровень «4» — компенсация и очистка с grace period, потоковые лимиты и замер памяти, идемпотентный bootstrap и ограниченные ключи API. Трек 2 — reconciler PostgreSQL ↔ S3. Весь обязательный минимум lab1–lab3 (PostgreSQL, Basic → Bearer, Argon2id, TTL и отзыв сессий, keyset-пагинация, HAProxy и ≥2 реплики, `X-Instance-Id`, общий `Idempotency-Key`, хуки отказов) сохраняется с объявленными переходами. Out of scope (не проектировать, не закладывать «на будущее»): `202 queued`, worker, брокер, thumbnail, crop, optimized и любые варианты кроме `original` (лаба 5); presigned upload/download (трек 1, не выбран); OTel и Grafana (лаба 6); TLS, mTLS, OpenBao и непрозрачный alias реплики (лаба 7); Docker Swarm, несколько узлов, erasure coding и репликация S3, HA PostgreSQL и резервирование балансировщика; удаление вложений и сообщений, Web UI, WebSocket, Kubernetes. ## Стек Python 3.14 (аннотации вычисляются лениво по PEP 649, `TYPE_CHECKING` и `from __future__ import annotations` не используются), FastAPI, gunicorn с несколькими `UvicornWorker` (пакет `uvicorn-worker`), dishka (DI), pydantic v2 + pydantic-settings, structlog, SQLAlchemy 2 async (ORM/Core, asyncpg как драйвер), Alembic, redis-py (`redis.asyncio`) для Valkey, argon2-cffi, aiobotocore (S3 path-style, SigV4, таймауты connect/read, checksum `when_required`), Pillow (разбор заголовка и проверка изображения), pytest + pytest-asyncio + httpx. Зависимости — uv и `uv.lock`; ruff и ty обязательны на `src/`, `student-tests/` и Python-обвязке стенда; `scripts/*.py` держат синтаксис Python 3.9 и stdlib. Инфраструктура — Docker Compose: `lb` (HAProxy 3.2 LTS по digest, единственные опубликованные порты — HTTP и статистика на 127.0.0.1, `GET /health/ready`, `server-template` с Docker DNS), `api` (один compose-service с `deploy.replicas`, без `container_name` и портов, `X-Instance-Id` = hostname, non-root, read-only, лимиты), одноразовый `migrate`, `postgres` (17.x-alpine по digest, volume), `valkey` (8.x-alpine по digest, AOF), `s3` (RustFS 1.0.4 по digest, volume `s3data`, без опубликованных портов, консоль выключена, non-root, read-only), одноразовый `s3-init` (`rc` по digest: bucket, anonymous private, политика и пользователь API), `s3-cli` под профилем `tools` для проверок, `k6` под профилем `bench`, одноразовый `reconciler` (образ API, сверка PostgreSQL ↔ S3) под профилем `reconcile`. Сети `edge` и `backend` (internal). Секреты — compose secrets из gitignored `secrets/`, приложение читает их через `*_FILE`; root-ключи S3 получают только `s3`, `s3-init` и `s3-cli`. ## Архитектура Монолит с тремя доменными зонами по книге Персиваля и Грегори (`openspec/notes/architecture-patterns-python.md`), развёрнутый N одинаковыми репликами: main.py сборка приложения: собирает вклады зон в один процесс, связывает зоны портами alembic/ одноразовые версионированные миграции под advisory lock, проверка legacy-схемы gunicorn_conf.py конфигурация процесса: воркеры, окно вывода из ротации по SIGTERM (флаг вывода — shared/infrastructure/readiness) identity/ пользователи, пароли и сессии messaging/ чаты, история и идемпотентная отправка, ссылки сообщения на вложения attachments/ вложения: метаданные, проверка изображения, порт объектного хранилища и его адаптер S3, свой HTTP-слой upload, метаданных и скачивания shared/ только платформа: часы, id, журнал, движок и сессии PostgreSQL, UoW-база, готовность за портом Readiness, конвейер, health, ошибки, настройки, идентификатор реплики Стрелки указывают внутрь: `domain/` не импортирует инфраструктуру, `application/` зависит только от портов, адаптеры подключаются в `ioc.py` зоны. Ядро `shared/` не импортирует веб-фреймворк. Зоны не импортируют друг друга; общая точка — схема БД: внешние ключи между таблицами зон допустимы как ограничение целостности, но SQL одной зоны не читает таблицы другой. Вопрос одной зоны к другой (членство в чате) — порт зоны-потребителя, адаптер которого собирает `main.py`. Реплика не держит состояния, от которого зависит корректность: PostgreSQL — источник истины для всего, включая метаданные вложений; S3 — источник истины только для байтов; Valkey — кэш сессий. Отправка сообщения — одна команда SQL адаптера `PostgresMessageLog` за портом `MessageLog`: блокировка строки чата, членство, отметка времени, квитанция ключа, сообщение и ссылки на вложения фиксируются вместе; агрегат `Chat` в записи не участвует, эти правила держат SQL и интеграционные тесты. ## Источники норм - `contracts/README.md` — нормативная семантика API, включая «Вложения (с lab4)». - `contracts/openapi.json` — OpenAPI 3.1.0, обязательный минимум. - `contracts/infrastructure.json`, `infra/README.md` — роли инфраструктуры и что о них отчитать. - `README.md` — рубрика уровней «3» / «4» / «5». - `COURSE.md` — карта курса и объявленные переходы API между лабами. - `openspec/notes/architecture-patterns-python.md` — словарь паттернов и их компромиссов. При расхождении артефакта с `contracts/` источником считается `contracts/`. Подгонка контракта или публичных тестов под реализацию решением не является. rules: proposal: - "Пиши на русском; идентификаторы, поля, коды ошибок и имена файлов — в оригинальном виде." - "Держи в пределах 400 слов: Why / What changes / Impact без воды." - "Указывай, какой уровень рубрики закрывает изменение: «3», «4» или заявленный трек «5»." - "Обязательна секция «Non-goals» со ссылкой на Out of scope; не тащи в лабу 4 возможности лаб 5–7 и трека 1." - "Связывай изменение с конкретным пунктом рубрики `README.md` и строкой таблицы доказательств `REPORT.md`." - "Если изменение трогает `contracts/`, `tests/`, `README.md` или `COURSE.md` — это запрещено, оформляй как вопрос преподавателю." specs: - "Имя capability начинается с префикса лабы, в которой требование введено: `lab-<имя>`, например `lab1-messenger-history`. Номер берётся из `lab.json`." - "Префикс означает происхождение, а не срок действия: требование с `lab1-` продолжает действовать в лабах 2–7, пока его явно не изменит новая дельта." - "Требование существующей capability правится дельтой к ней же, под её исходным префиксом; новый префикс заводится только для по-настоящему нового поведения." - "Дельта-спека описывает только наблюдаемое поведение, не реализацию." - "Требования о границах доменных зон формулируй как наблюдаемые: через поведение API или через проверяемый граф зависимостей модулей." - "Формулируй требования как `### Requirement:` плюс `#### Scenario:` в форме WHEN/THEN на русском." - "Для API-требований фиксируй метод, путь, коды ответов, заголовки и форму тела ошибки." - "Каждое требование трассируется на пункт `contracts/README.md` или на критерий рубрики `README.md`." - "Сценарии обязаны покрывать негативные пути: файл ровно 10485760 и 10485761 байт (с `Content-Length` и chunked), больше 40 млн пикселей, битый и обрезанный PNG/JPEG, подмена MIME, отсутствующий или иной `Content-Type`, опасный и пустой `filename`, чужое и неизвестное вложение, вложение другого чата, 11 и повторяющиеся `attachment_ids`, посторонний на метаданных и скачивании, недоступный S3, остановленная реплика, а также прежние: отсутствующий и неверный `Idempotency-Key`, тот же ключ с другим телом, malformed JSON, лишние поля, чужой чат (404, не 403), истёкший токен." - "Для инфраструктурных требований фиксируй наблюдаемое: какие порты опубликованы, где лежат байты (bucket, volume), что видит анонимный клиент S3, какие реплики видны по `X-Instance-Id`, что показывает `docker ps -a`." - "Не вводи в контракт поля и коды, которых нет в `contracts/openapi.json`." design: - "Создавай, если изменение затрагивает границы доменных зон, слои, агрегаты, конкурентность, идемпотентность, согласованность двух хранилищ, балансировку, поведение при сигналах или конфигурацию контейнера." - "Для каждого введённого паттерна отвечай по формуле книги: что за это получаем и чего это стоит." - "Явно называй порт, его адаптеры и точку сборки; проверяй правило зависимостей: домен не импортирует инфраструктуру." - "Указывай, к какой доменной зоне относится изменение; если оно задевает несколько — объясняй, каким портом, событием или внешним ключом они связаны." - "Всё, что кладётся в `shared/`, обосновывай отдельно: туда попадает только платформа и механизм связи, но не доменные понятия." - "Ошибки, события и команды принадлежат зоне; в `shared/` живут лишь их базовые типы, без кодов контракта." - "Для пары PostgreSQL + S3 фиксируй источник истины каждого факта, порядок записи (intent → PUT → COMMIT), что остаётся после сбоя на каждом шаге и кто это убирает; `201` — только после обеих записей." - "Для обработки файлов фиксируй, где и в каком порядке применяются лимиты (заголовок, поток, заголовок изображения, декодирование), сколько памяти занимает одна загрузка и сколько их идёт одновременно." - "Для балансировщика и S3-клиента фиксируй цепочку таймаутов клиент > LB > приложение > БД/S3 и политику повторов: какие запросы можно повторить и почему." - "Секреты, токены, ключи S3 и реальные данные в артефакт не попадают — только плейсхолдеры и имена переменных окружения." - "Отмечай, что требуется от контейнера: пользователь, закрепление версий, healthcheck, обработка SIGTERM, лимиты, опубликованные порты, переменные окружения." - "Для каждого хранилища называй источник истины, границы транзакций, поведение при недоступности (503 или обход) и что переживает рестарт." - "SQL описывай вместе с индексом, который его обслуживает, и ожидаемым планом; схему, ограничения и индексы фиксируй до запросов; миграции — аддитивные (expand/contract), совместимые с работающей версией." tasks: - "Задачи — атомарные шаги не длиннее 2 часов, в порядке исполнения." - "Группируй по слоям и артефактам: схема и миграции, доменные зоны, приложение, инфраструктура, точка входа, стенд, хуки отказов, тесты, измерения, отчёт." - "Одна задача не пересекает границу доменной зоны; связь зон (порт, событие или внешний ключ схемы) оформляется отдельной задачей." - "Первой в цепочке идёт задача уровня «3», задачи уровня «4» и трека «5» — после неё." - "Каждая группа завершается задачей проверки: какой командой убедиться, что критерий рубрики выполнен." - "Не создавай задач, меняющих `contracts/`, `tests/`, `README.md`, `COURSE.md` или рубрику." operations: apply: guidance: - "Соблюдай правило зависимостей: адаптер добавляется за существующим портом, а не импортом инфраструктуры в домен." - "Новый код кладётся в свою доменную зону вместе со своими ошибками, событиями, командами и HTTP-фасадом." - "`shared/` пополняется только платформой и механизмом связи; доменное понятие туда не попадает никогда." - "Коды контракта и HTTP-статусы объявляет зона в своём `entrypoints/errors.py`; платформа только применяет реестр." - "Роутер, провайдер DI, журнал, отображение ошибок и настройки зоны лежат в её `entrypoints/` и `config.py`." - "Ядро `shared/` (domain, application, infrastructure) не импортирует веб-фреймворк: транспорт живёт только в `shared/entrypoints/` и в `entrypoints/` зон." - "Отдельного каталога точек входа на верхнем уровне не заводи: общее кладётся в `shared/`, доменное — в зону, сборка и связывание зон портами — в `main.py`." - "Зоны не импортируют модули друг друга, включая объявления событий, — это проверяется тестом; в БД связь зон — только внешний ключ, SQL зоны читает лишь свои таблицы." - "Пиши под Python 3.14 с ленивыми аннотациями: без `TYPE_CHECKING` и без `from __future__ import annotations`." - "Логирование — только через порт `Logger`; второй логгер в приложении не заводится. Object key, ключи S3 и содержимое файлов в журнал не пишутся." - "Код приложения — в `src/`, конфигурация LB, нагрузки и S3 — в `infra/`, собственные тесты — в `student-tests/`, обезличенные доказательства — в `evidence/`." - "Перед коммитом прогоняй `make lint`, `make student-test` и `make check`." - "SQL только через SQLAlchemy ORM/Core с параметрами; text() только для системного каталога и специальных операций; миграции Alembic." - "Тело загрузки читается потоком со счётчиком до лимита; изображение не декодируется целиком до проверки размера по заголовку; тяжёлая проверка идёт в потоке под ограничением параллелизма." - "Реплика не хранит в памяти процесса и на своём диске ничего, от чего зависит корректность ответа другой реплики: сессии, ключи идемпотентности, курсоры и файлы — через общее хранилище или общий секрет." - "Ошибка зависимости (PostgreSQL, Valkey, S3) превращается в `503 unavailable` за ограниченное время; отказ кэша обходится и никогда не превращается в анонимный доступ." - "Схема меняется только новым файлом миграции; применённую миграцию не редактируют; миграция совместима с работающей предыдущей версией." - "Публичные `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` запускаются против поднятого стенда (`make up`) через LB после готовности всех реплик; после failover реплика возвращается `make restore`." - "Каждый заявленный критерий рубрики подтверждай командой и наблюдаемым результатом в `REPORT.md`; PASS без команды доказательством не считается." - "Отмечай выполнение в `tasks.md`; резюме держи кратким." archive: guidance: - "Имя архивной папки начинается с даты архивации в формате `ГГГГ-ММ-ДД`, а не с даты создания change." - "В `.openspec.yaml` архивной папки проставь `archived: <дата архивации>` и `lab: <номер из lab.json>` — по ним видно, когда и в какой лабе изменение закрыто." - "Перед архивацией сверься с рубрикой `README.md`: какой уровень закрывает изменение и каким файлом доказательства." - "Убедись, что `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` и сценарии отказов лабы против стенда проходят." - "Сохранившиеся дальше требования должны попасть в `openspec/specs/`, иначе исчезнут вместе с архивом." - "Зафиксируй, что именно демонстрируется в сценарии защиты и какие измерения приложены к треку «5»."