Перенесено дерево lab5 целиком: NestJS-приложение (API + worker,
RabbitMQ, outbox, S3), Dockerfile, compose.yaml, infra/{haproxy,minio,
rabbitmq}, стендовые скрипты, scripts/lab4, scripts/lab5,
evidence/lab4, evidence/lab5 и contracts/extensions.openapi.json.
Задание lab6 оставлено своим: README, REPORT, COURSE, lab.json,
contracts/{openapi,infrastructure,jobs.schema,attachment-states,
examples,observability}, tests, compose.example.yaml, infra/otel,
.github/pull_request_template.md.
Адаптации при переносе:
- docker-проект mtusi-lab5 -> mtusi-lab6 и тег образа
mtusi-messenger:lab6 (compose.yaml, scripts/stop-one.sh, .env.example,
infra/README.md), чтобы тома и контейнеры не пересекались с lab5;
- Makefile: цели lab5 сохранены целиком (skeleton lab6 не отличается
от skeleton lab5);
- .env.example: переменные приложения и стенда lab5 + блок lab6
(OTEL_*) из skeleton.
619 lines
21 KiB
JSON
619 lines
21 KiB
JSON
{
|
||
"openapi": "3.1.0",
|
||
"info": {
|
||
"title": "MTUSI Messenger — расширение lab4: прямая загрузка",
|
||
"version": "1.4.0-ext.2",
|
||
"description": "Трек 1. Не меняет обязательный контракт openapi.json: POST /api/v1/chats/{chat_id}/attachments остаётся основным путём. Клиент получает presigned PUT URL и отправляет байты прямо в приватный bucket MinIO, минуя API. Подписаны заголовки content-type, content-length и x-amz-checksum-sha256: хранилище само отвергает тело с другим размером (403 SignatureDoesNotMatch) или другим SHA-256 (400 XAmzContentChecksumMismatch), объект при этом не создаётся. TTL URL — DIRECT_UPLOAD_URL_TTL_SECONDS (300 с по умолчанию). Ключ объекта attachments/<attachment_id>/original раскрывает только UUID вложения; bucket приватный, анонимный доступ запрещён. Незавершённые и отклонённые заявки и их объекты убирает уборщик через ATTACHMENT_SWEEP_GRACE_SECONDS после истечения. Вложение видно участникам чата только после успешного complete (status=ready)."
|
||
},
|
||
"servers": [
|
||
{
|
||
"url": "http://localhost:8080",
|
||
"description": "Локальный учебный стенд"
|
||
}
|
||
],
|
||
"security": [
|
||
{
|
||
"bearerAuth": []
|
||
}
|
||
],
|
||
"paths": {
|
||
"/api/v1/chats/{chat_id}/attachments/direct-uploads": {
|
||
"post": {
|
||
"operationId": "initDirectUpload",
|
||
"summary": "Заявка на прямую загрузку: вернуть presigned PUT URL",
|
||
"parameters": [
|
||
{
|
||
"name": "chat_id",
|
||
"in": "path",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string",
|
||
"format": "uuid"
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateDirectUpload"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "Заявка создана; вложение pending и не видно никому, кроме загрузки",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/DirectUpload"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "Некорректное тело, filename или sha256",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "Нет или неверен токен",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "Чат недоступен",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"413": {
|
||
"description": "size_bytes больше 10 MiB",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"415": {
|
||
"description": "content_type не image/png и не image/jpeg",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"429": {
|
||
"description": "Слишком много незавершённых прямых загрузок пользователя; Retry-After — секунды до освобождения слота (TTL URL).",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"Retry-After": {
|
||
"description": "Секунды до повтора.",
|
||
"schema": {
|
||
"type": "integer",
|
||
"minimum": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"503": {
|
||
"description": "Зависимость недоступна",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v1/attachments/{attachment_id}/complete": {
|
||
"post": {
|
||
"operationId": "completeDirectUpload",
|
||
"summary": "Подтвердить прямую загрузку: HEAD объекта, полное чтение и декод изображения",
|
||
"description": "Только владелец заявки. Сверяет размер и подписанный SHA-256 объекта (HEAD), затем читает объект целиком: структурная проверка PNG/JPEG и полный декод (повреждённые и усечённые изображения отвергаются, даже если checksum совпадает). При несоответствии объект удаляется, а заявка получает внутренний статус rejected до истечения URL и grace-периода уборщика (повторный PUT по ещё действующему URL не оставит неучтённый объект); повторный complete отклонённой заявки — 404. Если объект ещё не загружен — 409, заявка не меняется. Повторный и параллельный complete готового вложения идемпотентен (200).",
|
||
"parameters": [
|
||
{
|
||
"name": "attachment_id",
|
||
"in": "path",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string",
|
||
"format": "uuid"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Вложение готово; тело идентично Attachment из openapi.json",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Attachment"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "Некорректный attachment_id",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "Нет или неверен токен",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "Заявка не найдена, не принадлежит пользователю или уже удалена",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"409": {
|
||
"description": "Объект не получен или не совпадает с заявленным размером/SHA-256",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"413": {
|
||
"description": "Слишком много пикселей",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"415": {
|
||
"description": "Содержимое не PNG/JPEG или не совпадает с content_type",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"503": {
|
||
"description": "Хранилище недоступно или не ответило за S3_REQUEST_TIMEOUT_MS / UPLOAD_TIMEOUT_MS",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"429": {
|
||
"description": "Реплика проверяет слишком много изображений одновременно (UPLOAD_MAX_IN_FLIGHT) или у пользователя слишком много одновременных проверок (UPLOAD_MAX_IN_FLIGHT_PER_USER); Retry-After — секунды до повтора.",
|
||
"headers": {
|
||
"X-Request-Id": {
|
||
"description": "Идентификатор запроса.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"X-Instance-Id": {
|
||
"description": "Идентификатор реплики.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
"Retry-After": {
|
||
"description": "Секунды до повтора.",
|
||
"schema": {
|
||
"type": "integer",
|
||
"minimum": 1
|
||
}
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "openapi.json#/components/schemas/Error"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"components": {
|
||
"securitySchemes": {
|
||
"bearerAuth": {
|
||
"type": "http",
|
||
"scheme": "bearer",
|
||
"bearerFormat": "opaque session token"
|
||
}
|
||
},
|
||
"schemas": {
|
||
"CreateDirectUpload": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"required": [
|
||
"filename",
|
||
"content_type",
|
||
"size_bytes",
|
||
"sha256"
|
||
],
|
||
"properties": {
|
||
"filename": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
},
|
||
"content_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"image/png",
|
||
"image/jpeg"
|
||
]
|
||
},
|
||
"size_bytes": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 10485760
|
||
},
|
||
"sha256": {
|
||
"type": "string",
|
||
"pattern": "^[a-f0-9]{64}$"
|
||
}
|
||
}
|
||
},
|
||
"DirectUpload": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"required": [
|
||
"attachment_id",
|
||
"method",
|
||
"url",
|
||
"headers",
|
||
"expires_at"
|
||
],
|
||
"properties": {
|
||
"attachment_id": {
|
||
"type": "string",
|
||
"format": "uuid"
|
||
},
|
||
"method": {
|
||
"type": "string",
|
||
"enum": [
|
||
"PUT"
|
||
]
|
||
},
|
||
"url": {
|
||
"type": "string",
|
||
"format": "uri",
|
||
"description": "Presigned URL; содержит подпись, не логировать."
|
||
},
|
||
"headers": {
|
||
"type": "object",
|
||
"description": "Заголовки, которые клиент обязан отправить как есть. Content-Length клиент ставит сам; тело должно быть ровно size_bytes.",
|
||
"properties": {
|
||
"Content-Type": {
|
||
"type": "string"
|
||
},
|
||
"x-amz-checksum-sha256": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": [
|
||
"Content-Type",
|
||
"x-amz-checksum-sha256"
|
||
]
|
||
},
|
||
"expires_at": {
|
||
"type": "string",
|
||
"format": "date-time"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|