forked from mtusi2026/mtusi2026lab4
586 lines
19 KiB
JSON
586 lines
19 KiB
JSON
{
|
||
"openapi": "3.1.0",
|
||
"info": {
|
||
"title": "MTUSI Messenger — расширение lab4: прямая загрузка",
|
||
"version": "1.4.0-ext.1",
|
||
"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), читает заголовок изображения (до 1 MiB) и сверяет тип и число пикселей. При несоответствии заявка и объект удаляются, повторный complete даёт 404. Повторный 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": "Хранилище недоступно",
|
||
"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"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"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"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|