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>
21 KiB
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 несёт поток, и все проверки идут в обработчике в порядке «дешёвое раньше»:
401— guard конвейера (как в лабе 3);- объявленный
Content-Lengthбольше лимита маршрута →413в конвейере, тело не читается; - членство через порт →
404; Filename(1–255 code points, не пробельный, без/,\, категорийCc) →400;Content-Type(тип без параметров, регистр не важен) ∈ {image/png,image/jpeg} → иначе415;- чтение потока в
bytearrayсо счётчиком и инкрементальным SHA-256: на байтеMAX_UPLOAD_BYTES + 1→413, дальше не читаем; - проверка изображения (D4) →
415/413; - запись (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/WarningPillow (выше его собственного порога) тоже →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:
- транзакция:
INSERT attachments (…, status='pending', object_key='attachments/<uuid7>'),COMMIT; PutObject(Key=object_key, Body=буфер, ContentType);- транзакция:
UPDATE attachments SET status='ready', updated_at=$2 WHERE id=$1 AND status='pending',COMMIT; событиеAttachmentStored; 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, volumes3data:/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, aliasesroot,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 (без:/@, они идут в URLRC_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.