lab6: базовый коммит из lab5 (0790599)

Перенесено дерево 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.
This commit is contained in:
2026-11-09 16:44:21 +03:00
parent 470d9d6f1e
commit 6889e77ab4
203 changed files with 27707 additions and 13 deletions
+618
View File
@@ -0,0 +1,618 @@
{
"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"
}
}
}
}
}
}