gromov/image-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: добавить генерацию image variants

Browse Source 
- добавлен shared config presets, custom transforms и allowlist hosts
- реализованы Backend endpoints для assets, presets и variants
- добавлена orchestration через PostgreSQL, RabbitMQ, S3 и worker
- обновлён Gateway read-through flow с L1 cache и корректным Vary: Accept
- добавлена миграция resize_mode для variants lookup
- обновлены dev scripts, env template, lockfile и документация
This commit is contained in:
Сергей Громов
2026-05-05 13:25:28 +03:00
parent bcadb85a83
commit 1c0e8277a3
59 changed files with 3526 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
apps/backend/src/assets/asset-response.dto.ts Normal file
View File

@@ -0,0 +1,93 @@
import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger"
export class AssetResponseDto {
@ApiProperty({ description: "Внутренний UUID asset.", example: "59fcf4f6-9891-4df4-8bb7-a4dbe570bb66" })
id!: string
@ApiProperty({ description: "Публичный идентификатор asset.", example: "asset_demo" })
publicId!: string
@ApiProperty({ description: "Текущая версия source image.", example: 1 })
currentVersion!: number
@ApiProperty({ description: "Статус asset.", enum: ["active", "disabled", "deleted"], example: "active" })
status!: string
@ApiProperty({ description: "Source URL текущей версии.", example: "https://storage.yandexcloud.net/shared1318/img/1.jpg" })
sourceUrl!: string
@ApiProperty({ description: "Hostname source URL текущей версии.", example: "storage.yandexcloud.net" })
sourceHost!: string
@ApiProperty({ description: "Дата создания asset.", example: "2026-05-05T12:00:00.000Z" })
createdAt!: string
@ApiProperty({ description: "Дата обновления asset.", example: "2026-05-05T12:00:00.000Z" })
updatedAt!: string
}
export class AssetVariantResponseDto {
@ApiProperty({ description: "Внутренний UUID variant.", example: "7748d24e-5f30-4064-8ee8-4745a4d2aef1" })
id!: string
@ApiProperty({ description: "Preset или `custom`.", example: "card" })
preset!: string
@ApiProperty({ description: "Версия source image, для которой создан variant.", example: 1 })
version!: number
@ApiProperty({ description: "Ширина variant.", example: 640 })
width!: number
@ApiProperty({ description: "Высота variant. `0` означает auto height.", example: 0 })
height!: number
@ApiProperty({ description: "Режим resize.", enum: ["fit", "fill"], example: "fit" })
resize!: string
@ApiProperty({ description: "Качество variant.", example: 80 })
quality!: number
@ApiProperty({ description: "Запрошенный формат.", enum: ["auto", "avif", "webp", "jpg", "png"], example: "webp" })
requestedFormat!: string
@ApiProperty({ description: "Фактический формат bytes.", enum: ["avif", "webp", "jpg", "png"], example: "webp" })
format!: string
@ApiProperty({ description: "Статус генерации.", enum: ["pending", "processing", "ready", "failed"], example: "ready" })
status!: string
@ApiProperty({ description: "Публичный Gateway URL для variant.", example: "http://localhost:8888/images/asset_demo/v1/card?w=640&q=80&f=webp" })
url!: string
@ApiProperty({ description: "S3 key variant object.", example: "variants/asset_demo/v1/abc.webp" })
s3Key!: string
@ApiPropertyOptional({ description: "Content-Type готового object.", example: "image/webp" })
contentType!: string | null
@ApiPropertyOptional({ description: "Размер готового object в bytes.", example: 71844 })
sizeBytes!: number | null
@ApiPropertyOptional({ description: "Ошибка последней генерации, если status=`failed`." })
error!: string | null
@ApiProperty({ description: "Дата создания variant.", example: "2026-05-05T12:00:00.000Z" })
createdAt!: string
@ApiProperty({ description: "Дата обновления variant.", example: "2026-05-05T12:00:00.000Z" })
updatedAt!: string
}
export class AssetVariantsResponseDto {
@ApiProperty({ description: "Публичный идентификатор asset.", example: "asset_demo" })
publicId!: string
@ApiProperty({ description: "Список variants.", type: [AssetVariantResponseDto] })
variants!: AssetVariantResponseDto[]
}
export class AssetsListResponseDto {
@ApiProperty({ description: "Список assets.", type: [AssetResponseDto] })
assets!: AssetResponseDto[]
}

93
apps/backend/src/assets/assets.controller.ts Normal file
View File

@@ -0,0 +1,93 @@
import { Body, Controller, Get, Param, Post, Query } from "@nestjs/common"
import {
ApiBadRequestResponse,
ApiConflictResponse,
ApiCreatedResponse,
ApiNotFoundResponse,
ApiOkResponse,
ApiOperation,
ApiParam,
ApiQuery,
ApiTags,
} from "@nestjs/swagger"
import { AssetsService } from "./assets.service"
import { AssetResponseDto, AssetVariantsResponseDto, AssetsListResponseDto } from "./asset-response.dto"
import { CreateAssetVariantsRequestDto, CreateAssetVariantsResponseDto } from "./create-asset-variants.dto"
import { CreateAssetRequestDto, CreateAssetResponseDto } from "./create-asset.dto"
@ApiTags("assets")
@Controller("assets")
export class AssetsController {
constructor(private readonly assets: AssetsService) {}
@Get()
@ApiOperation({
summary: "получить список assets",
description: "Возвращает последние зарегистрированные assets вместе с source URL текущей версии.",
})
@ApiQuery({ description: "Максимальное количество assets в ответе.", example: 50, name: "limit", required: false })
@ApiQuery({ description: "Смещение для простого paging.", example: 0, name: "offset", required: false })
@ApiOkResponse({ description: "Список assets возвращён.", type: AssetsListResponseDto })
listAssets(@Query("limit") limit?: string, @Query("offset") offset?: string): Promise<AssetsListResponseDto> {
return this.assets.listAssets({ limit, offset })
}
@Post()
@ApiOperation({
summary: "зарегистрировать исходное изображение",
description:
"Создаёт asset и первую версию source image. Source URL сохраняется в PostgreSQL, а публичный image URL строится через Gateway без раскрытия исходной ссылки клиенту.",
})
@ApiCreatedResponse({ description: "Asset создан, версия source image зарегистрирована.", type: CreateAssetResponseDto })
@ApiBadRequestResponse({ description: "Некорректный sourceUrl, publicId или source host запрещён настройками." })
@ApiConflictResponse({ description: "Asset с таким publicId уже существует." })
createAsset(@Body() request: CreateAssetRequestDto): Promise<CreateAssetResponseDto> {
return this.assets.createAsset(request)
}
@Get(":publicId")
@ApiOperation({
summary: "получить asset по publicId",
description: "Возвращает metadata asset и source URL текущей версии.",
})
@ApiParam({ description: "Публичный идентификатор asset.", example: "asset_demo", name: "publicId" })
@ApiOkResponse({ description: "Asset найден.", type: AssetResponseDto })
@ApiNotFoundResponse({ description: "Asset не найден." })
getAsset(@Param("publicId") publicId: string): Promise<AssetResponseDto> {
return this.assets.getAsset(publicId)
}
@Get(":publicId/variants")
@ApiOperation({
summary: "получить variants asset",
description: "Возвращает variants asset: preset/custom параметры, status, S3 key, public URL и ошибку генерации, если она была.",
})
@ApiParam({ description: "Публичный идентификатор asset.", example: "asset_demo", name: "publicId" })
@ApiQuery({ description: "Версия source image. Если не передана, возвращаются variants всех версий.", example: 1, name: "version", required: false })
@ApiOkResponse({ description: "Variants возвращены.", type: AssetVariantsResponseDto })
@ApiNotFoundResponse({ description: "Asset не найден." })
listAssetVariants(
@Param("publicId") publicId: string,
@Query("version") version?: string,
): Promise<AssetVariantsResponseDto> {
return this.assets.listAssetVariants(publicId, version)
}
@Post(":publicId/variants")
@ApiOperation({
summary: "поставить generation jobs для variants",
description:
"Business endpoint для явной подготовки variants. В режиме `single` создаёт один variant, в режиме `family` создаёт набор variants preset по всем разрешённым widths/formats. Endpoint не ждёт bytes, а возвращает созданные/переиспользованные rows и public URLs.",
})
@ApiParam({ description: "Публичный идентификатор asset.", example: "asset_demo", name: "publicId" })
@ApiCreatedResponse({ description: "Variants созданы или переиспользованы, jobs поставлены при необходимости.", type: CreateAssetVariantsResponseDto })
@ApiBadRequestResponse({ description: "Некорректный preset/custom transform config." })
@ApiNotFoundResponse({ description: "Asset или version не найдены." })
createAssetVariants(
@Param("publicId") publicId: string,
@Body() request: CreateAssetVariantsRequestDto,
): Promise<CreateAssetVariantsResponseDto> {
return this.assets.createAssetVariants(publicId, request)
}
}

611
apps/backend/src/assets/assets.service.ts Normal file
View File

@@ -0,0 +1,611 @@
import { BadRequestException, ConflictException, Injectable, NotFoundException } from "@nestjs/common"
import { imageAssets, imageAssetVersions, imageVariants } from "@image-platform/database"
import {
CUSTOM_PRESET_NAME,
ImageTransformConfigError,
getImagePreset,
isAllowedSourceHost,
loadAllowedSourceHostsFromEnv,
normalizeImageTransform,
parseBooleanFlag,
type ActualImageFormat,
type NormalizedImageTransform,
} from "@image-platform/image-config"
import { buildVariantImageKey } from "@image-platform/storage"
import { and, desc, eq } from "drizzle-orm"
import { createHash, randomUUID } from "node:crypto"
import { DatabaseService } from "../infra/database.service"
import { QueueService } from "../infra/queue.service"
import type { AssetResponseDto, AssetVariantResponseDto, AssetVariantsResponseDto, AssetsListResponseDto } from "./asset-response.dto"
import type { CreateAssetVariantsRequestDto, CreateAssetVariantsResponseDto } from "./create-asset-variants.dto"
import type { CreateAssetRequestDto, CreateAssetResponseDto } from "./create-asset.dto"
import { normalizeSourceUrl } from "./source-url"
type AssetVersionRow = {
assetId: string
currentVersion: number
publicId: string
status: "active" | "deleted" | "disabled"
versionId: string
version: number
}
type VariantRow = typeof imageVariants.$inferSelect
type VariantTransform = NormalizedImageTransform & {
version: number
}
@Injectable()
export class AssetsService {
private readonly allowedHosts = loadAllowedSourceHostsFromEnv()
private readonly allowCustomTransforms = parseBooleanFlag(process.env.IMAGE_ALLOW_CUSTOM_TRANSFORMS, false)
private readonly allowUnregisteredHosts = parseBooleanFlag(process.env.SOURCE_HOST_ALLOW_ALL, false)
private readonly publicImageBaseUrl = process.env.PUBLIC_IMAGE_BASE_URL ?? "http://localhost:8888"
constructor(
private readonly database: DatabaseService,
private readonly queue: QueueService,
) {}
async listAssets(input: { limit?: string; offset?: string }): Promise<AssetsListResponseDto> {
const limit = parsePaginationInteger(input.limit, 50, 1, 100)
const offset = parsePaginationInteger(input.offset, 0, 0, 10_000)
const rows = await this.database.db
.select({
createdAt: imageAssets.createdAt,
currentVersion: imageAssets.currentVersion,
id: imageAssets.id,
publicId: imageAssets.publicId,
sourceHost: imageAssetVersions.sourceHost,
sourceUrl: imageAssetVersions.sourceUrl,
status: imageAssets.status,
updatedAt: imageAssets.updatedAt,
})
.from(imageAssets)
.innerJoin(
imageAssetVersions,
and(eq(imageAssetVersions.assetId, imageAssets.id), eq(imageAssetVersions.version, imageAssets.currentVersion)),
)
.orderBy(desc(imageAssets.createdAt))
.limit(limit)
.offset(offset)
return {
assets: rows.map(mapAssetResponse),
}
}
async createAsset(request: CreateAssetRequestDto): Promise<CreateAssetResponseDto> {
const source = normalizeSourceUrl(request.sourceUrl)
await this.assertAllowedHost(source.hostname)
const publicId = request.publicId ? normalizePublicId(request.publicId) : generatePublicId()
const sourceHash = createHash("sha256").update(source.sourceUrl).digest("hex")
try {
const result = await this.database.db.transaction(async (tx) => {
const [asset] = await tx
.insert(imageAssets)
.values({ publicId })
.returning({ id: imageAssets.id, publicId: imageAssets.publicId })
if (!asset) {
throw new Error("failed to create image asset")
}
const [version] = await tx
.insert(imageAssetVersions)
.values({
assetId: asset.id,
sourceHash,
sourceHost: source.hostname,
sourceUrl: source.sourceUrl,
version: 1,
})
.returning({ sourceHost: imageAssetVersions.sourceHost, version: imageAssetVersions.version })
if (!version) {
throw new Error("failed to create image asset version")
}
return { asset, version }
})
return {
id: result.asset.id,
imageBasePath: `/images/${result.asset.publicId}/v${result.version.version}/card`,
publicId: result.asset.publicId,
sourceHost: result.version.sourceHost,
version: result.version.version,
}
} catch (error) {
if (isUniqueViolation(error)) {
throw new ConflictException("publicId already exists")
}
throw error
}
}
async getAsset(publicId: string): Promise<AssetResponseDto> {
const asset = await this.loadAsset(publicId)
return mapAssetResponse(asset)
}
async listAssetVariants(publicId: string, versionInput?: string): Promise<AssetVariantsResponseDto> {
const asset = await this.loadAssetVersion(publicId, parseOptionalVersion(versionInput))
const conditions = [eq(imageVariants.assetId, asset.assetId)]
if (versionInput !== undefined) {
conditions.push(eq(imageVariants.assetVersion, asset.version))
}
const variants = await this.database.db
.select()
.from(imageVariants)
.where(and(...conditions))
.orderBy(desc(imageVariants.createdAt))
return {
publicId: asset.publicId,
variants: variants.map((variant) => this.mapVariantResponse(asset.publicId, variant)),
}
}
async createAssetVariants(
publicId: string,
request: CreateAssetVariantsRequestDto,
): Promise<CreateAssetVariantsResponseDto> {
const asset = await this.loadAssetVersion(publicId, request.version)
const transforms = this.buildVariantTransforms(request, asset.version)
const variants: AssetVariantResponseDto[] = []
for (const transform of transforms) {
const variant = await this.findOrCreateVariant(asset, transform)
if (variant.status === "failed") {
const pending = await this.markVariantPending(variant.id)
this.queue.publishGenerateVariant(pending.id)
variants.push(this.mapVariantResponse(asset.publicId, pending))
continue
}
if (variant.status === "pending") {
this.queue.publishGenerateVariant(variant.id)
}
variants.push(this.mapVariantResponse(asset.publicId, variant))
}
return {
publicId: asset.publicId,
variants,
version: asset.version,
}
}
private async loadAsset(publicId: string) {
const normalizedPublicId = normalizePublicId(publicId)
const [asset] = await this.database.db
.select({
createdAt: imageAssets.createdAt,
currentVersion: imageAssets.currentVersion,
id: imageAssets.id,
publicId: imageAssets.publicId,
sourceHost: imageAssetVersions.sourceHost,
sourceUrl: imageAssetVersions.sourceUrl,
status: imageAssets.status,
updatedAt: imageAssets.updatedAt,
})
.from(imageAssets)
.innerJoin(
imageAssetVersions,
and(eq(imageAssetVersions.assetId, imageAssets.id), eq(imageAssetVersions.version, imageAssets.currentVersion)),
)
.where(eq(imageAssets.publicId, normalizedPublicId))
.limit(1)
if (!asset) {
throw new NotFoundException("asset not found")
}
return asset
}
private async loadAssetVersion(publicId: string, versionInput: number | null | undefined): Promise<AssetVersionRow> {
const normalizedPublicId = normalizePublicId(publicId)
const [asset] = await this.database.db
.select({
assetId: imageAssets.id,
currentVersion: imageAssets.currentVersion,
publicId: imageAssets.publicId,
status: imageAssets.status,
})
.from(imageAssets)
.where(eq(imageAssets.publicId, normalizedPublicId))
.limit(1)
if (!asset || asset.status !== "active") {
throw new NotFoundException("asset not found")
}
const version = versionInput ?? asset.currentVersion
const [assetVersion] = await this.database.db
.select({ id: imageAssetVersions.id, version: imageAssetVersions.version })
.from(imageAssetVersions)
.where(and(eq(imageAssetVersions.assetId, asset.assetId), eq(imageAssetVersions.version, version)))
.limit(1)
if (!assetVersion) {
throw new NotFoundException("asset version not found")
}
return {
...asset,
version: assetVersion.version,
versionId: assetVersion.id,
}
}
private buildVariantTransforms(request: CreateAssetVariantsRequestDto, version: number): VariantTransform[] {
const mode = request.mode ?? "single"
if (mode !== "single" && mode !== "family") {
throw new BadRequestException("mode must be single or family")
}
if (mode === "family") {
return this.buildFamilyTransforms(request, version)
}
const format = request.format ?? selectDefaultFormat(request.preset, this.allowCustomTransforms)
return [
this.normalizeTransform({
format,
height: request.height,
preset: request.preset,
quality: request.quality,
resize: request.resize,
version,
width: request.width,
}),
]
}
private buildFamilyTransforms(request: CreateAssetVariantsRequestDto, version: number): VariantTransform[] {
if (request.preset === CUSTOM_PRESET_NAME) {
throw new BadRequestException("custom transforms do not support family mode")
}
const preset = getImagePreset(request.preset)
if (!preset) {
throw new BadRequestException(`unknown image preset: ${request.preset}`)
}
if (request.width !== undefined || request.height !== undefined || request.resize !== undefined) {
throw new BadRequestException("width, height and resize are not accepted in family mode")
}
const formats = [...new Set(request.formats?.length ? request.formats : preset.formats)]
for (const format of formats) {
if (!preset.formats.includes(format)) {
throw new BadRequestException(`format ${format} is not allowed for preset ${request.preset}`)
}
}
const widths = preset.mode === "fixed" ? [preset.width] : preset.widths
if (!widths?.length) {
throw new BadRequestException(`preset ${request.preset} has no widths configured`)
}
return widths.flatMap((width) =>
formats.map((format) =>
this.normalizeTransform({
format,
preset: request.preset,
quality: request.quality,
version,
width: preset.mode === "fixed" ? undefined : width,
}),
),
)
}
private normalizeTransform(input: {
format: ActualImageFormat
height?: number
preset: string
quality?: number
resize?: "fill" | "fit"
version: number
width?: number
}): VariantTransform {
try {
const transform = normalizeImageTransform({
allowCustomTransforms: this.allowCustomTransforms,
format: input.format,
height: input.height,
preset: input.preset,
quality: input.quality,
requestedFormat: input.format,
resize: input.resize,
width: input.width,
})
return {
...transform,
version: input.version,
}
} catch (error) {
if (error instanceof ImageTransformConfigError) {
throw new BadRequestException(error.message)
}
throw error
}
}
private async findOrCreateVariant(asset: AssetVersionRow, transform: VariantTransform): Promise<VariantRow> {
const existing = await this.findVariant(asset.assetId, transform)
if (existing) {
return existing
}
const variantHash = createVariantHash(asset.publicId, transform)
const s3Key = buildVariantImageKey({
assetId: asset.publicId,
format: transform.format,
variantHash,
version: asset.version,
})
const [created] = await this.database.db
.insert(imageVariants)
.values({
assetId: asset.assetId,
assetVersion: asset.version,
assetVersionId: asset.versionId,
format: transform.format,
height: transform.height,
preset: transform.preset,
quality: transform.quality,
requestedFormat: transform.requestedFormat,
resizeMode: transform.resize,
s3Key,
status: "pending",
variantHash,
width: transform.width,
})
.onConflictDoNothing({
target: [
imageVariants.assetId,
imageVariants.assetVersion,
imageVariants.preset,
imageVariants.width,
imageVariants.height,
imageVariants.resizeMode,
imageVariants.quality,
imageVariants.format,
],
})
.returning()
if (created) {
return created
}
const raced = await this.findVariant(asset.assetId, transform)
if (!raced) {
throw new Error("failed to create image variant")
}
return raced
}
private async findVariant(assetId: string, transform: VariantTransform): Promise<VariantRow | null> {
const [variant] = await this.database.db
.select()
.from(imageVariants)
.where(
and(
eq(imageVariants.assetId, assetId),
eq(imageVariants.assetVersion, transform.version),
eq(imageVariants.preset, transform.preset),
eq(imageVariants.width, transform.width),
eq(imageVariants.height, transform.height),
eq(imageVariants.resizeMode, transform.resize),
eq(imageVariants.quality, transform.quality),
eq(imageVariants.format, transform.format),
),
)
.limit(1)
return variant ?? null
}
private async markVariantPending(variantId: string): Promise<VariantRow> {
const [variant] = await this.database.db
.update(imageVariants)
.set({ error: null, status: "pending", updatedAt: new Date() })
.where(eq(imageVariants.id, variantId))
.returning()
if (!variant) {
throw new NotFoundException("variant not found")
}
return variant
}
private mapVariantResponse(publicId: string, variant: VariantRow): AssetVariantResponseDto {
return {
contentType: variant.contentType,
createdAt: variant.createdAt.toISOString(),
error: variant.error,
format: variant.format,
height: variant.height ?? 0,
id: variant.id,
preset: variant.preset,
quality: variant.quality,
requestedFormat: variant.requestedFormat,
resize: variant.resizeMode,
s3Key: variant.s3Key,
sizeBytes: variant.sizeBytes,
status: variant.status,
updatedAt: variant.updatedAt.toISOString(),
url: buildPublicImageUrl(this.publicImageBaseUrl, publicId, variant),
version: variant.assetVersion,
width: variant.width,
}
}
private async assertAllowedHost(hostname: string) {
if (this.allowUnregisteredHosts) {
return
}
if (!isAllowedSourceHost(hostname, this.allowedHosts)) {
throw new BadRequestException("sourceUrl host is not allowed")
}
}
}
function mapAssetResponse(row: {
createdAt: Date
currentVersion: number
id: string
publicId: string
sourceHost: string
sourceUrl: string
status: "active" | "deleted" | "disabled"
updatedAt: Date
}): AssetResponseDto {
return {
createdAt: row.createdAt.toISOString(),
currentVersion: row.currentVersion,
id: row.id,
publicId: row.publicId,
sourceHost: row.sourceHost,
sourceUrl: row.sourceUrl,
status: row.status,
updatedAt: row.updatedAt.toISOString(),
}
}
function generatePublicId() {
return `asset_${randomUUID().replaceAll("-", "").slice(0, 16)}`
}
function normalizePublicId(publicId: string) {
const normalized = publicId.trim()
if (!/^[a-zA-Z0-9_-]{3,128}$/.test(normalized)) {
throw new BadRequestException("publicId must be 3-128 chars and contain only letters, digits, _ or -")
}
return normalized
}
function isUniqueViolation(error: unknown) {
return typeof error === "object" && error !== null && "code" in error && error.code === "23505"
}
function parsePaginationInteger(value: string | undefined, fallback: number, min: number, max: number) {
if (value === undefined) {
return fallback
}
if (!/^\d+$/.test(value)) {
throw new BadRequestException("pagination params must be integers")
}
const parsed = Number.parseInt(value, 10)
if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
throw new BadRequestException(`pagination param must be between ${min} and ${max}`)
}
return parsed
}
function parseOptionalVersion(value: string | undefined) {
if (value === undefined) {
return undefined
}
if (!/^\d+$/.test(value)) {
throw new BadRequestException("version must be a positive integer")
}
const parsed = Number.parseInt(value, 10)
if (!Number.isSafeInteger(parsed) || parsed < 1) {
throw new BadRequestException("version must be a positive integer")
}
return parsed
}
function selectDefaultFormat(preset: string, allowCustomTransforms: boolean): ActualImageFormat {
const config = getImagePreset(preset)
if (config) {
return config.formats.includes("webp") ? "webp" : config.formats[0]
}
if (preset === CUSTOM_PRESET_NAME && allowCustomTransforms) {
return "webp"
}
throw new BadRequestException(`unknown image preset: ${preset}`)
}
function createVariantHash(publicId: string, transform: VariantTransform) {
return createHash("sha256")
.update(
[
publicId,
transform.version,
transform.preset,
transform.width,
transform.height,
transform.resize,
transform.quality,
transform.format,
].join(":"),
)
.digest("hex")
.slice(0, 32)
}
function buildPublicImageUrl(baseUrl: string, publicId: string, variant: VariantRow) {
const url = new URL(`/images/${publicId}/v${variant.assetVersion}/${variant.preset}`, baseUrl)
const isFixedPresetUrl = variant.preset !== CUSTOM_PRESET_NAME && variant.height && variant.height > 0
if (!isFixedPresetUrl || variant.preset === CUSTOM_PRESET_NAME) {
url.searchParams.set("w", variant.width.toString())
}
if (variant.preset === CUSTOM_PRESET_NAME && variant.height) {
url.searchParams.set("h", variant.height.toString())
url.searchParams.set("fit", variant.resizeMode)
}
if (!isFixedPresetUrl || variant.quality !== 80) {
url.searchParams.set("q", variant.quality.toString())
}
url.searchParams.set("f", variant.format)
return url.toString()
}

43
apps/backend/src/assets/create-asset-variants.dto.ts Normal file
View File

@@ -0,0 +1,43 @@
import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger"
import { AssetVariantResponseDto } from "./asset-response.dto"
export class CreateAssetVariantsRequestDto {
@ApiProperty({ description: "Preset для генерации или `custom`.", example: "card" })
preset!: string
@ApiPropertyOptional({ description: "Режим генерации: один variant или вся family preset.", enum: ["single", "family"], example: "single" })
mode?: "family" | "single"
@ApiPropertyOptional({ description: "Версия source image. Если не передана, используется currentVersion asset.", example: 1 })
version?: number
@ApiPropertyOptional({ description: "Ширина variant. Обязательна для responsive preset в mode=`single` и custom.", example: 640 })
width?: number
@ApiPropertyOptional({ description: "Высота variant для custom. `0` или отсутствие означает auto height.", example: 333 })
height?: number
@ApiPropertyOptional({ description: "Качество. Если не передано, берётся из preset/custom config.", example: 80 })
quality?: number
@ApiPropertyOptional({ description: "Фактический формат для single generation.", enum: ["avif", "webp", "jpg", "png"], example: "webp" })
format?: "avif" | "jpg" | "png" | "webp"
@ApiPropertyOptional({ description: "Форматы для family generation. Если не переданы, используются все форматы preset.", enum: ["avif", "webp", "jpg", "png"], isArray: true })
formats?: Array<"avif" | "jpg" | "png" | "webp">
@ApiPropertyOptional({ description: "Resize mode для custom transforms.", enum: ["fit", "fill"], example: "fill" })
resize?: "fill" | "fit"
}
export class CreateAssetVariantsResponseDto {
@ApiProperty({ description: "Публичный идентификатор asset.", example: "asset_demo" })
publicId!: string
@ApiProperty({ description: "Версия source image, для которой поставлены jobs.", example: 1 })
version!: number
@ApiProperty({ description: "Созданные или переиспользованные variants.", type: [AssetVariantResponseDto] })
variants!: AssetVariantResponseDto[]
}

36
apps/backend/src/assets/create-asset.dto.ts Normal file
View File

@@ -0,0 +1,36 @@
import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger"
export class CreateAssetRequestDto {
@ApiPropertyOptional({
description:
"Публичный стабильный идентификатор asset. Если не передан, Backend сгенерирует идентификатор автоматически.",
example: "asset_123",
})
publicId?: string
@ApiProperty({
description: "Постоянная ссылка на исходное изображение. Сейчас поддерживаются только публичные http/https URL.",
example: "https://storage.yandexcloud.net/shared1318/img/1.jpg",
})
sourceUrl!: string
}
export class CreateAssetResponseDto {
@ApiProperty({ description: "Внутренний UUID asset в PostgreSQL.", example: "59fcf4f6-9891-4df4-8bb7-a4dbe570bb66" })
id!: string
@ApiProperty({ description: "Публичный идентификатор asset для Gateway URL.", example: "asset_123" })
publicId!: string
@ApiProperty({ description: "Номер версии source image. Используется в URL как `v{version}`.", example: 1 })
version!: number
@ApiProperty({ description: "Нормализованный hostname исходного изображения.", example: "storage.yandexcloud.net" })
sourceHost!: string
@ApiProperty({
description: "Базовый путь Gateway для запроса variant. Width, quality и format передаются query params.",
example: "/images/asset_123/v1/card",
})
imageBasePath!: string
}

65
apps/backend/src/assets/source-url.ts Normal file
View File

@@ -0,0 +1,65 @@
import { BadRequestException } from "@nestjs/common"
import { isIP } from "node:net"
const LOCAL_HOSTNAMES = new Set(["localhost", "localhost.localdomain"])
export type NormalizedSourceUrl = {
hostname: string
sourceUrl: string
}
export function normalizeSourceUrl(input: string): NormalizedSourceUrl {
let url: URL
try {
url = new URL(input)
} catch {
throw new BadRequestException("sourceUrl must be a valid URL")
}
if (url.protocol !== "http:" && url.protocol !== "https:") {
throw new BadRequestException("sourceUrl must use http or https")
}
const hostname = url.hostname.toLowerCase().replace(/\.$/, "")
if (isPrivateOrLocalHostname(hostname)) {
throw new BadRequestException("sourceUrl host must be public")
}
url.hostname = hostname
url.hash = ""
return {
hostname,
sourceUrl: url.toString(),
}
}
function isPrivateOrLocalHostname(hostname: string) {
if (LOCAL_HOSTNAMES.has(hostname) || hostname.endsWith(".localhost")) {
return true
}
const ipVersion = isIP(hostname)
if (ipVersion === 0) {
return false
}
if (ipVersion === 6) {
return true
}
const [a = 0, b = 0] = hostname.split(".").map((part) => Number.parseInt(part, 10))
return (
a === 0 ||
a === 10 ||
a === 127 ||
(a === 100 && b >= 64 && b <= 127) ||
(a === 169 && b === 254) ||
(a === 172 && b >= 16 && b <= 31) ||
(a === 192 && b === 168)
)
}