Files
mtusi2026lab2/openspec/changes/add-lab4-image-attachments/design.md
T
ArtyomandClaude Opus 5.5 d7fb96bb70 Propose image attachments as an openspec change
Plan grade 3 of lab 4 as one change: a third domain zone for
attachments that takes the raw bytes of one PNG or JPEG, applies the
size limit before reading the whole body and the pixel limit before
decoding, checks the type by content, writes a pending row, the object
and then the ready row and only then answers 201, and serves metadata
and the original only to chat members through the API. Messages gain
attachment_ids, linked by a foreign key to attachments of the same chat
so the messaging zone never reads the attachments table, and the zone
asks messaging about membership through a port wired in main.py.

The stand gains RustFS with a private bucket, a one-off bootstrap with
a separate API key, and a restart hook that waits for S3. The specs add
lab4-attachments and lab4-object-storage and modify message sending,
history, idempotent replay, the restart hook and stand persistence.

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

21 KiB
Raw Blame History

Context

Мотивация — в proposal.md. Решение лабы 3 — две зоны (identity, messaging) за HAProxy с ≥2 репликами, PostgreSQL как источник истины, Valkey как кэш сессий, ASGI-конвейер с лимитом тела 1 MiB по Content-Length, UoW с событиями. Реплики уже не держат состояния; вложения добавляют второе хранилище, где транзакции PostgreSQL не действуют. Инфраструктура S3, хуки и сценарии заранее проверены на заглушке в .prep/lab4 и встраиваются, а не пишутся заново: MinIO community на arm64 не скачивается (minio/minio удалён с Docker Hub, quay отвечает 401), поэтому выбран RustFS 1.0.4 + rc v0.1.36.

Goals / Non-Goals

Goals:

  • Байты — только в bucket, метаданные — только в PostgreSQL; ни одна реплика не держит файл, от которого зависит ответ другой.
  • Каждый лимит применяется раньше дорогого шага: заголовок → поток → заголовок изображения → проверка файла.
  • 201 ровно тогда, когда обе записи подтверждены; любой сбой оставляет только невидимое клиенту состояние.
  • Зоны по-прежнему не импортируют друг друга и не читают чужие таблицы.

Non-Goals:

  • Компенсирующий DeleteObject, очистка pending по grace period, лимит одновременных загрузок и замер памяти — уровень «4».
  • Reconciler, карантин и глубокая сверка — трек 2.

Decisions

D1. Зона attachments и связь с messaging

Новая зона attachments/ со слоями domain (агрегат Attachment, значения Filename, ImageKind, ImageInfo, ошибки, событие AttachmentStored), application (команда UploadAttachment, запросы GetAttachment и OpenAttachment, порты), infrastructure (PostgreSQL, S3, Pillow) и entrypoints (роутер, схемы, DI, журнал, реестр ошибок).

Зоне нужен один ответ от messaging: «входит ли пользователь в чат». Порт ChatMembership.is_member(chat_id, user_id) объявлен в attachments/application/ports.py; адаптер MessagingMembership поверх ChatDirectory.chat_for_member зоны messaging и его провайдер dishka живут в main.py — единственном месте, которое знает обе зоны. Целостность в БД держат внешние ключи, а не чужие SELECT:

  • attachments (chat_id, owner_id) → chat_members (chat_id, user_id): загрузить можно только в свой чат, гонка с проверкой порта ловится ForeignKeyViolationError → 404;
  • message_attachments (attachment_id, chat_id) → attachments (id, chat_id) ON DELETE RESTRICT: сообщение ссылается только на вложение своего чата, а удалить используемое вложение нельзя. Нарушение (message_attachments_attachment_fkey) → UnknownAttachment зоны messaging → 404.

Что получаем: SQL каждой зоны читает только свои таблицы, тест графа импортов остаётся строгим, проверка «вложение этого чата» атомарна с INSERT сообщения без чтения таблицы attachments из messaging. Чего стоит: два запроса (строка вложения + членство) вместо одного JOIN на метаданных и скачивании, лишний уникальный индекс (id, chat_id). Отвергнуто: JOIN chat_members в SQL зоны attachments (нарушает границу), проекция членства через события в памяти (не переживает рестарт, расходится между репликами), SELECT count(*) FROM attachments из messaging (чтение чужой таблицы; внешний ключ даёт то же атомарно).

D2. Схема — миграция 0003_attachments.sql

ALTER TABLE messages DROP CONSTRAINT messages_text_check,
    ADD CONSTRAINT messages_text_check CHECK (char_length(text) <= 4000);

CREATE TABLE attachments (
    id uuid PRIMARY KEY,
    chat_id uuid NOT NULL,
    owner_id uuid NOT NULL,
    filename text NOT NULL CHECK (char_length(filename) BETWEEN 1 AND 255),
    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}$'),
    width integer NOT NULL CHECK (width > 0),
    height integer NOT NULL CHECK (height > 0),
    object_key text COLLATE "C" NOT NULL UNIQUE,
    status text NOT NULL CHECK (status IN ('pending', 'ready')),
    created_at timestamptz NOT NULL,
    updated_at timestamptz NOT NULL,
    CONSTRAINT attachments_chat_key UNIQUE (id, chat_id),
    CONSTRAINT attachments_owner_fkey FOREIGN KEY (chat_id, owner_id) REFERENCES chat_members (chat_id, user_id)
);
CREATE INDEX attachments_pending_idx ON attachments (created_at) WHERE status = 'pending';

CREATE TABLE message_attachments (
    message_id uuid NOT NULL REFERENCES messages (id) ON DELETE CASCADE,
    position smallint NOT NULL CHECK (position BETWEEN 0 AND 9),
    chat_id uuid NOT NULL,
    attachment_id uuid NOT NULL,
    PRIMARY KEY (message_id, position),
    UNIQUE (message_id, attachment_id),
    CONSTRAINT message_attachments_attachment_fkey FOREIGN KEY (attachment_id, chat_id)
        REFERENCES attachments (id, chat_id) ON DELETE RESTRICT
);
CREATE INDEX message_attachments_attachment_idx ON message_attachments (attachment_id);

Ни одного bytea. object_key с COLLATE "C" — байтовый порядок, как у листинга S3 (пригодится reconciler). Частичный индекс по pending обслуживает будущую очистку и не растёт вместе с готовыми вложениями. UNIQUE (message_id, attachment_id) запрещает дубль внутри сообщения; одно вложение в нескольких сообщениях допустимо. Индекс по attachment_id обслуживает проверку RESTRICT. CHECK текста ослаблен до ≤ 4000: пустой текст с вложением легален, а пустой без вложений по-прежнему отсекает домен (400). Миграция аддитивна для кода лабы 3: старая версия не пишет пустой текст и не знает новых таблиц.

Запросы и индексы: метаданные — SELECT … FROM attachments WHERE id = $1 AND status = 'ready' (PK); членство — chat_members по PK; история и повтор добавляют ARRAY(SELECT attachment_id FROM message_attachments WHERE message_id = m.id ORDER BY position) — коррелированный подзапрос по PK (message_id, position), не больше 100 index scan на страницу, без N+1 запросов из приложения.

D3. Загрузка: порядок проверок и память

Эндпоинт не объявляет тела: FastAPI его не читает, обработчик получает request.stream(). Команда UploadAttachment несёт поток, и все проверки идут в обработчике в порядке «дешёвое раньше»:

  1. 401 — guard конвейера (как в лабе 3);
  2. объявленный Content-Length больше лимита маршрута → 413 в конвейере, тело не читается;
  3. членство через порт → 404;
  4. Filename (1–255 code points, не пробельный, без /, \, категорий Cc) → 400;
  5. Content-Type (тип без параметров, регистр не важен) ∈ {image/png, image/jpeg} → иначе 415;
  6. чтение потока в bytearray со счётчиком и инкрементальным SHA-256: на байте MAX_UPLOAD_BYTES + 1 → 413, дальше не читаем;
  7. проверка изображения (D4) → 415/413;
  8. запись (D5).

Лимит тела в конвейере становится зависимым от маршрута: платформа получает пары «шаблон пути → лимит», а main.py передаёт шаблон upload из attachments/entrypoints и MAX_UPLOAD_BYTES; остальным маршрутам остаётся 1 MiB. Память одной загрузки — до 10 MiB буфера без копий: тот же буфер отдаётся и в проверку, и в PutObject. Диск не используется (read_only, tmpfs только для heartbeat). Сколько загрузок идёт одновременно, на уровне «3» не ограничено — лимит и замер на уровне «4».

D4. Проверка изображения — Pillow за портом ImageInspector

Адаптер PillowImageInspector выполняет проверку в asyncio.to_thread под asyncio.Semaphore(IMAGE_CHECK_CONCURRENCY), чтобы не блокировать event loop и не декодировать много файлов разом:

  • Image.open(..., formats=("PNG", "JPEG")) читает только заголовок; GIF, WebP, текст, пустое тело → 415;
  • формат по сигнатуре ≠ заявленный Content-Type → 415 (подмена MIME);
  • width * height > MAX_IMAGE_PIXELS → 413 до любого декодирования; DecompressionBombError/Warning Pillow (выше его собственного порога) тоже → 413;
  • PNG: verify() — обход всех чанков с проверкой CRC и IEND без распаковки пикселей; JPEG: draft("RGB", (w/8, h/8)) + load() — полное декодирование потока в масштабе 1/8 (≈1/64 памяти). Ошибка → 415. LOAD_TRUNCATED_IMAGES остаётся False, обрезанный файл — ошибка.

Что получаем: тип и целостность по содержимому, память проверки — килобайты для PNG и ≤2 MB для JPEG 40 MP. Чего стоит: verify() не распаковывает IDAT, поэтому PNG с правильными CRC, но испорченным zlib-потоком будет принят — оригинал отдаётся побайтно, вреда серверу нет, ограничение записано в отчёт. Отвергнуто: полное декодирование PNG (до 160 MB на 40 MP), python-magic (только сигнатура, без структуры).

D5. Порядок записи PostgreSQL ↔ S3

UploadAttachmentHandler:

  1. транзакция: INSERT attachments (…, status='pending', object_key='attachments/<uuid7>'), COMMIT;
  2. PutObject(Key=object_key, Body=буфер, ContentType);
  3. транзакция: UPDATE attachments SET status='ready', updated_at=$2 WHERE id=$1 AND status='pending', COMMIT; событие AttachmentStored;
  4. 201 Attachment.
Сбой Что остаётся Ответ клиенту
до шага 1 (обрыв, 413, 415) ничего ошибка или обрыв
шаг 1 ничего 503
шаг 2 строка pending без объекта 503
шаг 3 строка pending и объект 503
после шага 3 готовое вложение 201 (или обрыв уже после фиксации)

pending не видно ни в метаданных, ни в скачивании (404), а сообщение на него сослаться не может: id отдаётся клиенту только в 201. Намерение до PUT гарантирует, что у любого объекта под attachments/ есть строка с тем же ключом, — поэтому на уровне «4» правило «объект без строки старше grace — мусор» безопасно. Отвергнуто: PUT до INSERT (объект без строки неотличим от свежей загрузки), одна транзакция вокруг PUT (соединение PostgreSQL держится на время сети S3).

D6. Адаптер S3 — aiobotocore за портом ObjectStorage

Порт: put(key, data, content_type), open(key) -> ObjectContent(size, chunks), delete(key). Адаптер S3ObjectStorage держит один клиент aiobotocore на воркер (scope APP dishka, async-генератор закрывает клиент при остановке): signature_version="s3v4", addressing_style="path" (RustFS без virtual host), регион из S3_REGION, connect_timeout=1, read_timeout=2, retries={"mode": "standard", "max_attempts": 2}, request_checksum_calculation/response_checksum_validation="when_required" (CRC и aws-chunked botocore ≥1.36 ломают часть S3-совместимых серверов). Худший случай операции — 2 × (1 + 2) = 6 с < REQUEST_TIMEOUT_SECONDS=8 < timeout server 10s HAProxy. NoSuchKey/404 → ObjectMissing порта; BotoCoreError, прочие ClientError, OSError, TimeoutError → Unavailable платформы → 503. Ключи читаются из *_FILE настройками зоны и в журнал не попадают.

LB не повторяет upload: в лабе 3 disable-l7-retry снят только для GET и POST …/messages с ключом; повтор PutObject клиентом botocore безопасен, ключ тот же.

D7. Метаданные и скачивание

GetAttachment: строка ready по PK → членство → Attachment, иначе 404. OpenAttachment: то же + storage.open(key) до отправки заголовков, поэтому 404 (объект пропал, событие attachment.object_missing в журнал) и 503 (S3 недоступен) ещё возможны; затем StreamingResponse по кускам 64 KiB с Content-Type из метаданных, Content-Length из S3, X-Content-Type-Options: nosniff, Cache-Control: private, no-store. Accept не учитывается, redirect нет. X-Request-Id и X-Instance-Id ставит конвейер на http.response.start, значит и на поток. variant — Literal["original"], иное → 400.

D8. attachment_ids в messaging

  • CreateMessageRequest.attachment_ids: list[UUID] = [] — без max_length на границе, чтобы членство (404) проверялось раньше содержимого; отпечаток model_dump_json включает attachment_ids, поэтому отсутствующий и [] дают один отпечаток, а порядок значим.
  • Chat.post(..., attachment_ids): членство → 404; больше 10 или повторы → InvalidAttachmentList (400); MessageText разрешает пустую строку, но не пробельную; пустой текст без вложений → 400. Message.attachment_ids: tuple[UUID, ...].
  • APPEND_MESSAGE добавляет в тот же оператор INSERT INTO message_attachments SELECT … FROM unnest($8::uuid[]) WITH ORDINALITY; внешний ключ проверяется в конце оператора, нарушение откатывает и сообщение, и ключ идемпотентности. RECEIPT и история читают attachment_ids подзапросом по PK.

D9. Стенд

  • s3: rustfs/rustfs:1.0.4@sha256:ed9210d6…, uid 10001, read_only + tmpfs /tmp, cap_drop: ALL, RUSTFS_CONSOLE_ENABLE=false, логи в stdout, root-ключи из *_FILE, volume s3data:/data, healthcheck /health/ready, 1 CPU / 512M, сеть backend (internal), портов нет.
  • s3-init: rustfs/rc:v0.1.36@sha256:ab024bfe…, infra/s3/init.sh — bucket create --ignore-existing, anonymous set private, политика messenger-api из infra/s3/api-policy.json (Get/Put/DeleteObject, multipart abort/list, ListBucket, GetBucketLocation на один bucket), пользователь API, lifecycle «abort incomplete multipart за 1 день», самопроверка. s3-cli — тот же образ под профилем tools, aliases root, api, anon.
  • api: якорь x-s3-env подмешивается в environment (ключ сервиса заменяет ключ якоря целиком, поэтому не через x-app), секреты s3_access_key_id, s3_secret_access_key, depends_on: s3-init: service_completed_successfully.
  • scripts/secrets.sh создаёт hex-секреты S3 (без :/@, они идут в URL RC_HOST_*); scripts/restart.sh перезапускает и s3, up --wait ждёт его healthy, поэтому однократное чтение вложения после хука проходит.
  • Готовность: /health/ready от S3 не зависит. Иначе при падении S3 LB вывел бы все реплики и отказали бы даже тексты, а ответы LB не несут X-Instance-Id. Upload и скачивание при этом получают 503 от приложения.

D10. Сценарии и доказательства

scripts/lab4_scenarios.py (stdlib, Python 3.9, импортирует tests/client.py для проверки схем и заголовков): failover-upload — upload, stop-one.sh по X-Instance-Id ответа upload, скачивание через другую реплику и сравнение SHA-256, --restore; s3-outage — docker compose stop s3, коды и время upload/скачивания/метаданных/текста/готовности, возврат S3 и повторное скачивание. scripts/s3-check.sh — анонимный доступ, порты, консоль, двойной s3-init, права ключа API. scripts/evidence-attachments.sh — \d attachments, листинг bucket, ReadonlyRootfs и mounts реплик, сверка байтов вне API. Цели Makefile: scenario, s3-check, attachments-evidence.

Risks / Trade-offs

  • [Строки pending после сбоя S3 или COMMIT остаются до уровня «4»] → они невидимы клиенту и не мешают ссылкам; компенсация и очистка с grace — следующее изменение.
  • [Ранний 413/404 до конца тела: клиент, ещё отправляющий 10 MiB, может получить reset] → собственные тесты проверяют 413 через Content-Length; поведение описано в отчёте.
  • [verify() PNG не распаковывает пиксели] → принято осознанно (D4), записано в ограничениях.
  • [RustFS молод (GA 2026-09), одиночный узел без parity — SPOF] → версия и digest закреплены, данные на volume, ограничение в отчёте.
  • [Одновременные загрузки без лимита держат по 10 MiB каждая] → API_MEMORY=512m; лимит параллелизма и замер — уровень «4».

Migration Plan

make up на существующем стенде лабы 3: migrate применяет 0003 под advisory lock, s3-init создаёт bucket, реплики стартуют после обоих. Откат: предыдущий образ работает с новой схемой (новые таблицы ему не нужны, ослабленный CHECK его не задевает); make reset-data удаляет и s3data.