{ "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//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" } } } } } }