Перенесено дерево lab4 целиком: NestJS-приложение с вложениями и S3,
Dockerfile, compose.yaml, infra/{haproxy,minio}, стендовые скрипты,
scripts/lab4, evidence/lab4 и contracts/extensions.openapi.json.
Задание lab5 оставлено своим: README, REPORT, COURSE, lab.json,
contracts/{openapi,infrastructure,jobs.schema,attachment-states,examples},
tests, compose.example.yaml, .github/pull_request_template.md.
Адаптации при переносе:
- docker-проект mtusi-lab4 -> mtusi-lab5 и тег образа mtusi-messenger:lab5,
чтобы тома и контейнеры не пересекались с lab4 (scripts/stop-one.sh:
LAB_PROJECT вместо LAB4_PROJECT);
- Makefile: цели lab5 сохранены, добавлены стендовые (stand-up/down,
wait-ready, init-env, test-e2e, test-dependencies, s3-security,
consistency, bench);
- .env.example: реальные переменные приложения и стенда lab4 (без них
compose.yaml не поднимается) + блок lab5 (BROKER_URL_FILE, WORKER_*).
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"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|