- upload, metadata and download endpoints for PNG/JPEG attachments:
limits before reading and decompression, type by content,
structural integrity check without decoding pixels, safe filename
- write order: pending row with object key -> PUT to S3 -> ready;
per-step DB sessions so no pool connection is held during transfers
- attachment_ids in messages (validation, idempotency hash, history);
whitespace-only text allowed with an attachment (teacher, 2026-10-20)
- migration: attachments and message_attachments tables, text length
CHECK relaxed with NOT VALID
- student tests, fault checks and driver commands for attachments;
rollout profile starts from e1161f7 and checks the commit first
- sync attachments deltas into main specs; rules, AGENTS.md, PLAN.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
9.6 KiB
messages Specification
Purpose
Текстовые сообщения в чате: отправка от имени текущего пользователя и
чтение истории чата его участниками в порядке (created_at, id).
Requirements
Requirement: Отправка сообщения
POST /api/v1/chats/{chat_id}/messages SHALL принимать тело
{"text": ..., "attachment_ids": [...]} с заголовком Idempotency-Key.
attachment_ids необязателен, по умолчанию []. При успехе ответ SHALL
быть 201 с объектом Message: id, chat_id, sender_id, text,
created_at, attachment_ids, без других полей.
sender_idSHALL быть текущим пользователем;textSHALL совпадать с отправленным;attachment_idsSHALL совпадать с отправленными, в том же порядке, без поля в запросе —[].
Формат ключа, повтор и конфликт описаны в capability idempotency,
проверка вложений — в требовании «Вложения в сообщении».
Scenario: Участник отправляет сообщение
- WHEN Алиса отправляет
"Привет, мир 👋"в свой чат с новымIdempotency-Key - THEN ответ 201,
sender_id— Алиса,chat_id— этот чат,textравен"Привет, мир 👋",attachment_ids—[]
Scenario: Сообщение с вложениями
- WHEN Алиса загрузила в чат вложения A и B и отправляет текст с
attachment_ids[B, A] - THEN ответ 201,
attachment_ids—[B, A]
Requirement: Валидация текста
text SHALL содержать не больше 4000 Unicode code points. Пустой
текст — пустая строка или строка из одних пробельных символов — SHALL
допускаться только вместе с хотя бы одним вложением, без вложений он MUST
NOT приниматься (согласовано с преподавателем 2026-10-20, AGENTS.md,
«Согласования с преподавателем»). Текст SHALL сохраняться и
возвращаться как прислан, без обрезки и нормализации. Поле sender_id
в теле MUST NOT приниматься. Нарушения SHALL давать 400
invalid_request.
Scenario: Пустой текст
- WHEN участник отправляет
{"text": ""} - THEN ответ 400
Scenario: Граница длины
- WHEN текст из 4000 code points, затем из 4001
- THEN первый запрос даёт 201, второй — 400
Scenario: Попытка подменить отправителя
- WHEN тело содержит
sender_idдругого пользователя - THEN ответ 400, сообщение не создаётся
Scenario: Пустой текст с вложением
- WHEN участник отправляет
{"text": "", "attachment_ids": [A]}с готовым вложением A своего чата - THEN ответ 201,
text— пустая строка,attachment_ids—[A]
Scenario: Пробелы с вложением
- WHEN участник отправляет
{"text": " ", "attachment_ids": [A]}с готовым вложением A своего чата, а затем{"text": " "}без вложений - THEN первый ответ 201,
text— те же три пробела,attachment_ids—[A]; второй — 400invalid_request, и это сообщение не создаётся
Requirement: Писать и читать могут только участники
Отправка и чтение истории SHALL быть доступны только участникам чата.
Посторонний и запрос к несуществующему чату SHALL получать одинаковый
404 not_found; сообщение при этом MUST NOT создаваться.
Scenario: Посторонний пишет
- WHEN Ева отправляет сообщение в чат Алисы и Боба
- THEN ответ 404, в истории чата новых сообщений нет
Scenario: Посторонний читает
- WHEN Ева запрашивает историю чата Алисы и Боба
- THEN ответ 404
Requirement: История чата
GET /api/v1/chats/{chat_id}/messages SHALL возвращать сообщения чата
в порядке (created_at, id) по возрастанию, с постраничным выводом по
capability pagination. Любой участник SHALL видеть все сообщения
чата, в том числе чужие. Каждое сообщение SHALL содержать
attachment_ids в порядке отправки.
Scenario: Два участника, две страницы
- WHEN Алиса и Боб отправили по сообщению, и Боб читает историю с
limit=1, а затем продолжает по курсору - THEN первая страница содержит одно сообщение и непустой
next_cursor, вторая — второе сообщение иnext_cursornull, а порядок совпадает с(created_at, id)
Scenario: Вложения в истории
- WHEN Алиса отправила сообщение с
attachment_ids[B, A], а Боб — текстовое сообщение - THEN в истории у первого
attachment_ids—[B, A], у второго —[]
Requirement: Подтверждённое сообщение сразу видно
Сообщение, на которое сервис ответил 201, SHALL присутствовать в любом следующем чтении истории этого чата.
Scenario: Чтение после записи
- WHEN участник получил 201 на отправку и сразу читает историю
- THEN сообщение есть в истории
Requirement: Вложения в сообщении
attachment_ids SHALL содержать от 0 до 10 уникальных идентификаторов
в записи UUID (api-conventions, «UUID на входе»). Повтор
идентификатора, в том числе в другом регистре букв, больше 10
элементов, элемент не UUID и не массив — 400 invalid_request.
Каждое вложение SHALL быть готовым вложением этого чата. Одинаковый 404
not_found дают:
- неизвестное вложение;
- вложение другого чата, в том числе чата, где отправитель не состоит;
- вложение, загрузка которого не завершена.
Сообщение при этом MUST NOT создаваться. Сервис SHALL принимать ссылку на вложение чата от любого его участника, а не только от владельца, и одно вложение SHALL входить в несколько сообщений. Сообщение и его связи с вложениями SHALL сохраняться одной транзакцией.
Scenario: Вложение другого участника
- WHEN Алиса загрузила вложение в чат с Бобом, и Боб отправляет сообщение с этим вложением
- THEN ответ 201
Scenario: Вложение другого чата
- WHEN Алиса состоит в чатах X и Y, загрузила вложение в Y и отправляет в X сообщение с ним
- THEN ответ 404
not_found, в истории X нового сообщения нет
Scenario: Чужое вложение
- WHEN Ева загрузила вложение в свой чат, а Алиса отправляет в свой чат сообщение с ним
- THEN ответ 404
not_found, сообщение не создано
Scenario: Неизвестное вложение
- WHEN участник отправляет сообщение со случайным UUID в
attachment_ids - THEN ответ 404
not_found, сообщение не создано
Scenario: Неверный список вложений
- WHEN участник отправляет
attachment_idsс повтором одного вложения, с тем же вложением в верхнем регистре, из 11 элементов, строкой вместо массива и с элементом123 - THEN каждый ответ 400
invalid_request, сообщений не создано
Scenario: Одно вложение в двух сообщениях
- WHEN участник дважды отправляет сообщение с одним и тем же вложением
- THEN оба ответа 201, у обоих сообщений это вложение в
attachment_ids