Files
mtusi2026lab2/openspec/config.yaml
T
ArtyomandClaude Opus 5.5 b0f463ac5c Carry over the agent context and openspec history from lab 3
Bring the Claude Code settings, the lint hook, the opsx commands and
skills, the architecture notes, the lab 1 to lab 3 specs and the
archived lab 1 to lab 3 changes into the lab 4 skeleton, so lab 4
continues the same spec history instead of starting from scratch. The
files come from the lab 3 solution commit 61c0c28.

Rewrite AGENTS.md and the openspec context and rules for lab 4: image
attachments with metadata in PostgreSQL and bytes in a private RustFS
bucket inside the stand, a third domain zone for attachments that asks
the messaging zone about chat membership through a port wired in
main.py, upload limits applied before unbounded reading or decoding,
201 only after both the object write and the commit, Out of scope moved
to labs 5-7 plus presigned uploads, and rules on the write order between
the two stores and on root S3 keys staying out of the API.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-28 20:16:50 +03:00

158 lines
23 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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,
asyncpg (параметризованный SQL без ORM), 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`. Сети `edge` и `backend` (internal). Секреты —
compose secrets из gitignored `secrets/`, приложение читает их через `*_FILE`; root-ключи S3
получают только `s3`, `s3-init` и `s3-cli`.
## Архитектура
Монолит с тремя доменными зонами по книге Персиваля и Грегори
(`openspec/notes/architecture-patterns-python.md`), развёрнутый N одинаковыми репликами:
main.py сборка приложения: собирает вклады зон в один процесс, связывает зоны портами
migrate.py одноразовая точка входа: применяет SQL-миграции под advisory lock
identity/ пользователи, пароли и сессии
messaging/ чаты, история и идемпотентная отправка, ссылки сообщения на вложения
attachments/ вложения: метаданные, проверка изображения, порт объектного хранилища и его
адаптер S3, свой HTTP-слой upload, метаданных и скачивания
shared/ только платформа: часы, id, журнал, пул PostgreSQL, UoW-база, конвейер, health,
ошибки, настройки, идентификатор реплики
Стрелки указывают внутрь: `domain/` не импортирует инфраструктуру, `application/` зависит только
от портов, адаптеры подключаются в `ioc.py` зоны. Ядро `shared/` не импортирует веб-фреймворк.
Зоны не импортируют друг друга; общая точка — схема БД: внешние ключи между таблицами зон
допустимы как ограничение целостности, но SQL одной зоны не читает таблицы другой. Вопрос одной
зоны к другой (членство в чате) — порт зоны-потребителя, адаптер которого собирает `main.py`.
Реплика не держит состояния, от которого зависит корректность: PostgreSQL — источник истины для
всего, включая метаданные вложений; S3 — источник истины только для байтов; Valkey — кэш сессий.
## Источники норм
- `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<N>-<имя>`, например `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 только параметризованный (`$1`, `$2`); значения из запроса никогда не склеиваются в текст запроса."
- "Тело загрузки читается потоком со счётчиком до лимита; изображение не декодируется целиком до проверки размера по заголовку; тяжёлая проверка идёт в потоке под ограничением параллелизма."
- "Реплика не хранит в памяти процесса и на своём диске ничего, от чего зависит корректность ответа другой реплики: сессии, ключи идемпотентности, курсоры и файлы — через общее хранилище или общий секрет."
- "Ошибка зависимости (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»."