Files
mtusi2026lab4/contracts/extensions.openapi.json
T

619 lines
21 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"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"
}
}
}
}
}
}