Files
mtusi2026lab4/openspec/changes/add-lab4-image-attachments/proposal.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

5.5 KiB

Why

Решение лабы 3 хранит только текст. Рубрика «3» README.md лабы 4 требует вложения-изображения: S3-сервер в общем стенде, метаданные в PostgreSQL, байты в приватном bucket, 201 ready только после сохранения, побайтное скачивание участником, 404 постороннему, лимиты 10 MiB / 40 млн пикселей и тип по содержимому, переживание остановки обслужившей реплики, рестарта стенда и недоступности S3. Контракт 1.4.0 добавляет три операции и обязательное Message.attachment_ids. Изменение закрывает уровень «3» и строки 3.1–3.9 REPORT.md.

What Changes

  • Новая доменная зона attachments: POST /api/v1/chats/{chat_id}/attachments?filename=… (сырые байты PNG/JPEG, 201 Attachment со status=ready), GET /api/v1/attachments/{id}, GET /api/v1/attachments/{id}/content?variant=original (байты через API, без redirect). Доступ — только участникам чата, иначе 404.
  • Лимиты до неограниченного чтения и декодирования: Content-Length и потоковый счётчик (413), размер по заголовку изображения (413), сигнатура и проверка файла (415), filename (400). Object key attachments/<uuid> назначает сервер.
  • Порядок записи: строка-намерение pending → PutObject → ready и COMMIT → 201. Недоступный S3 — 503 за ограниченное время; тексты продолжают работать, /health/ready от S3 не зависит.
  • Зона messaging: attachment_ids (0–10 уникальных, только вложения этого чата, иначе 400/404) в отправке, ответе, повторе и истории; text="" допустим только с вложением; отсутствующий attachment_ids и [] — одно тело для Idempotency-Key.
  • Миграция 0003_attachments.sql: таблицы attachments и message_attachments, ослабление messages_text_check до ≤ 4000.
  • Стенд: RustFS 1.0.4 (s3, volume s3data, без портов, консоль выключена), одноразовый s3-init (rc: bucket, anonymous private, пользователь API с политикой на один bucket), s3-cli под профилем tools; S3-переменные и ключи API у api; restart.sh перезапускает и S3.
  • Сценарии scripts/lab4_scenarios.py (failover-upload, s3-outage), scripts/s3-check.sh, цели Makefile, сбор доказательств.

Capabilities

New Capabilities

  • lab4-attachments: upload, лимиты и проверка содержимого, метаданные, скачивание оригинала, доступ участников, порядок записи PostgreSQL ↔ S3, поведение при недоступном S3.
  • lab4-object-storage: S3-сервер в стенде, приватный bucket и его bootstrap, раздельные ключи root и API, байты не в БД и не на диске реплики, переживание остановки реплики и рестарта.

Modified Capabilities

  • lab1-messenger-history: «Отправка сообщения» — attachment_ids и пустой текст с вложением; «Чтение истории keyset-курсором» — элементы несут attachment_ids.
  • lab3-idempotent-messages: «Повтор возвращает исходный результат» — attachment_ids входит в тело, отсутствующий равен [].
  • lab3-load-balancing: «Рестарт стенда» — хук перезапускает и S3, ждёт его готовности.
  • lab2-persistent-storage: «Данные и сессии переживают рестарт» — вложения и их байты; «Воспроизводимый стенд» — S3 без портов, root-ключи только у S3-сервисов.

Impact

  • Код: новая зона attachments, зона messaging, платформа (лимит тела по маршруту), main.py (порт членства), миграция 0003; зависимости aiobotocore и Pillow.
  • Стенд: compose.yaml, infra/s3/, scripts/, Makefile, .env.example, CI.
  • Тесты: upload и лимиты, подмена MIME, filename, доступ, attachment_ids, идемпотентность, адаптер S3 против RustFS.
  • Отчёт: строки 3.1–3.9 в REPORT.md, evidence/.

Non-goals

Компенсация сбоя между S3 и БД, очистка pending, замер памяти под ≥10 загрузками, доказательство ограниченных ключей — уровень «4»; reconciler — трек 2; оба — следующие изменения. Из Out of scope не появляется ничего: 202 queued, worker и варианты (лаба 5), presigned upload (трек 1), удаление вложений, TLS (лаба 7).