Files

S.Gromov 56d551b43b feat: добавить endpoint picture/srcset

- добавлен contract DTO для picture sources и fallback image
- реализована выдача versioned Gateway URLs по static presets
- обновлена документация business API и dev smoke flow

2026-05-05 13:35:25 +03:00

10 KiB

Raw Blame History

Черновик Backend Контракта

Это черновик бизнес-контракта для NestJS backend. Сейчас реализованы system endpoints, Swagger, POST /api/assets и internal image ensure MVP.

System

GET /api/health
GET /docs
GET /docs-json

NestJS backend отдаёт JSON, metadata, statuses и URLs. Public image origin находится в Fastify Gateway. Backend владеет PostgreSQL, S3 orchestration и RabbitMQ jobs.

Internal Image Ensure

Этот internal endpoint вызывается Gateway на L1 miss. Gateway не ходит в DB/S3 напрямую.

POST /api/internal/images/ensure

Текущий статус реализации - MVP реализован: Backend создаёт/переиспользует variant row, публикует RabbitMQ job, ждёт ready до timeout и возвращает image bytes из S3.

Request body:

{
  "assetId": "asset_123",
  "version": 4,
  "preset": "card",
  "width": 640,
  "height": 0,
  "quality": 80,
  "requestedFormat": "auto",
  "resize": "fit",
  "format": "webp"
}

Query params:

Param	Описание
`w`	целевая ширина; обязательна для responsive presets и custom, запрещена/фиксирована для fixed presets
`h`	целевая высота; используется для custom, для fixed preset берётся из config
`q`	качество; если не передано, берётся из preset, иначе должно входить в allowlist preset
`f`	`auto`, `avif`, `webp`, `jpg`; для Next/image по умолчанию `auto`
`fit`	`fit` или `fill`; используется только для custom transforms

Responsibilities:

проверить assetId и статический preset/custom transform config;
нормализовать width, height, resize, quality и format;
вычислить deterministic variantHash;
проверить PostgreSQL и S3;
если variant готов в S3, вернуть bytes или stream metadata для Gateway;
если variant отсутствует, создать/переиспользовать variant row;
поставить generate-variant job в RabbitMQ;
дождаться ready до timeout, чтобы первый next/image request мог получить картинку;
вернуть image response или metadata для Gateway.

Response headers:

Content-Type: image/avif | image/webp | image/jpeg
Cache-Control: public, max-age=31536000, immutable
Vary: Accept
ETag: "..."

Ошибки:

Status	Когда
`400`	некорректные query params
`404`	asset или preset не найден
`502`	external imgproxy недоступен или S3 object отсутствует после `ready`
`504`	generation не завершилась до `IMAGE_ENSURE_WAIT_MS`

Public endpoint реализуется в Fastify Gateway, internal ensure endpoint - в Backend:

client -> CDN -> Gateway /images/* -> Backend ensure -> RabbitMQ -> Worker -> imgproxy -> S3

Важно: /images/* не должен жить в NestJS /api. Gateway остаётся public image origin, Backend остаётся управлением процессов. Public image URL versioned: /images/{assetId}/v{version}/{preset}?w={width}&q={quality}&f=auto.

Примеры:

/images/asset_demo/v1/card?w=640&q=80&f=auto
/images/asset_demo/v1/avatar?f=auto
/images/asset_demo/v1/custom?w=777&h=333&q=72&fit=fill&f=webp

Allowed Hosts

GET /allowed-hosts
POST /allowed-hosts
PATCH /allowed-hosts/:id
DELETE /allowed-hosts/:id

Assets

POST /assets
GET /assets
GET /assets/:publicId
POST /assets/:publicId/versions
GET /assets/:publicId/picture
GET /assets/:publicId/variants
POST /assets/:publicId/variants
DELETE /assets/:id

Сейчас реализованы POST /assets, GET /assets, GET /assets/:publicId, POST /assets/:publicId/versions, GET /assets/:publicId/picture, GET /assets/:publicId/variants, POST /assets/:publicId/variants.

POST /assets request:

{
  "sourceUrl": "https://storage.yandexcloud.net/shared1318/img/1.jpg",
  "publicId": "asset_demo"
}

Response:

{
  "id": "59fcf4f6-9891-4df4-8bb7-a4dbe570bb66",
  "publicId": "asset_demo",
  "version": 1,
  "sourceHost": "storage.yandexcloud.net",
  "imageBasePath": "/images/asset_demo/v1/card"
}

Responsibilities:

validate source URL;
check mock allowlist SOURCE_ALLOWED_HOSTS, если SOURCE_HOST_ALLOW_ALL=false;
создать image_assets row;
создать image_asset_versions row версии 1;
optionally save original to S3 later.

GET /assets response:

{
  "assets": [
    {
      "id": "59fcf4f6-9891-4df4-8bb7-a4dbe570bb66",
      "publicId": "asset_demo",
      "currentVersion": 1,
      "status": "active",
      "sourceUrl": "https://storage.yandexcloud.net/shared1318/img/1.jpg",
      "sourceHost": "storage.yandexcloud.net",
      "createdAt": "2026-05-05T12:00:00.000Z",
      "updatedAt": "2026-05-05T12:00:00.000Z"
    }
  ]
}

GET /assets/:publicId/variants возвращает rows из image_variants с public Gateway URL, S3 key и status.

POST /assets/:publicId/versions request:

{
  "sourceUrl": "https://storage.yandexcloud.net/shared1318/img/1.jpg"
}

Response:

{
  "assetId": "59fcf4f6-9891-4df4-8bb7-a4dbe570bb66",
  "versionId": "3b5da974-bb7f-4d73-b172-d6ad9c244528",
  "publicId": "asset_demo",
  "previousVersion": 1,
  "version": 2,
  "sourceUrl": "https://storage.yandexcloud.net/shared1318/img/1.jpg",
  "sourceHost": "storage.yandexcloud.net",
  "imageBasePath": "/images/asset_demo/v2/card",
  "createdAt": "2026-05-05T12:00:00.000Z"
}

Новая версия становится currentVersion asset. Старые Gateway URLs с /v1/ остаются immutable и не требуют purge.

GET /assets/:publicId/picture?preset=card&sizes=100vw response:

{
  "publicId": "asset_demo",
  "preset": "card",
  "version": 2,
  "quality": 80,
  "sizes": "100vw",
  "widths": [320, 640, 960],
  "image": {
    "src": "http://localhost:8888/images/asset_demo/v2/card?w=960&q=80&f=jpg",
    "format": "jpg",
    "type": "image/jpeg",
    "width": 960,
    "height": 0
  },
  "sources": [
    {
      "format": "avif",
      "type": "image/avif",
      "srcSet": "http://localhost:8888/images/asset_demo/v2/card?w=320&q=80&f=avif 320w, http://localhost:8888/images/asset_demo/v2/card?w=640&q=80&f=avif 640w, http://localhost:8888/images/asset_demo/v2/card?w=960&q=80&f=avif 960w"
    }
  ]
}

Endpoint не ставит generation jobs: Gateway lazy path сгенерирует bytes на первом запросе или отдаст cache/S3.

Variants

GET /assets/:publicId/variants
POST /assets/:publicId/variants
POST /variants/:id/regenerate
DELETE /variants/:id

POST /assets/:publicId/variants request:

{
  "preset": "card",
  "mode": "single",
  "format": "webp",
  "width": 640,
  "quality": 80
}

Family generation:

{
  "preset": "card",
  "mode": "family"
}

Для family Backend создаёт набор variants по разрешённым widths/formats static preset и ставит RabbitMQ jobs. Endpoint не ждёт image bytes, в отличие от internal ensure.

Response:

{
  "publicId": "asset_demo",
  "version": 1,
  "variants": [
    {
      "id": "variant_123",
      "preset": "card",
      "version": 1,
      "width": 640,
      "height": 0,
      "resize": "fit",
      "quality": 80,
      "requestedFormat": "webp",
      "format": "webp",
      "status": "pending",
      "url": "http://localhost:8888/images/asset_demo/v1/card?w=640&q=80&f=webp",
      "s3Key": "variants/asset_demo/v1/abc.webp"
    }
  ]
}

Presets

GET /presets

Возвращает static presets, custom transform limits и mock allowlist source hosts.

{
  "presets": [
    {
      "name": "card",
      "mode": "responsive",
      "formats": ["avif", "webp", "jpg"],
      "qualities": [75, 80],
      "quality": 80,
      "resize": "fit",
      "widths": [320, 640, 960]
    }
  ],
  "custom": {
    "enabled": true,
    "formats": ["avif", "webp", "jpg", "png"],
    "maxWidth": 4096,
    "maxHeight": 4096,
    "quality": 80
  },
  "allowedSourceHosts": ["storage.yandexcloud.net"]
}

Image URLs For UI

Для ручного UI можно добавить endpoint, который возвращает готовый набор URLs для <picture>/srcset. Для next/image основным контрактом остаётся custom loader из docs/next-image-provider.md.

GET /assets/:id/picture?preset=card

Example response:

{
  "assetId": "asset_123",
  "preset": "card",
  "sources": [
    {
      "type": "image/avif",
      "srcset": "http://localhost:8888/images/asset_123/v4/card?w=320&q=80&f=avif 320w, http://localhost:8888/images/asset_123/v4/card?w=640&q=80&f=avif 640w"
    },
    {
      "type": "image/webp",
      "srcset": "http://localhost:8888/images/asset_123/v4/card?w=320&q=80&f=webp 320w, http://localhost:8888/images/asset_123/v4/card?w=640&q=80&f=webp 640w"
    }
  ],
  "fallback": {
    "src": "http://localhost:8888/images/asset_123/v4/card?w=640&q=80&f=jpg",
    "width": 640,
    "height": null
  }
}

Worker Lifecycle

Worker выполняет задачи из RabbitMQ. Задачи создаёт Backend.

RabbitMQ topology:

exchange: image-platform.jobs
queue: image.generate-variant
dead-letter exchange: image-platform.jobs.dlx
dead-letter queue: image.generate-variant.dlq

Job payload должен быть минимальным:

{
  "jobId": "job_123",
  "variantId": "variant_123"
}

Worker читает детали variant из PostgreSQL, вызывает imgproxy, пишет результат в S3 и обновляет status в PostgreSQL.

Если генерация тяжёлая или не успела завершиться до timeout, Backend может вернуть Gateway 504, а job продолжит выполняться/retry по очереди.

PostgreSQL может выступить первой очередью:

SELECT * FROM image_variants
WHERE status = 'pending'
FOR UPDATE SKIP LOCKED
LIMIT 1

PostgreSQL-backed очередь не используется как основной механизм: для jobs выбран RabbitMQ.

10 KiB Raw Blame History Unescape Escape

Черновик Backend Контракта

System

Internal Image Ensure

Allowed Hosts

Assets

Variants

Presets

Image URLs For UI

Worker Lifecycle

10 KiB

Raw Blame History