@hraness/slopcamera 3.2.4

package/src/vectorize/pixels.ts

@@ -0,0 +1,323 @@
+import { constants } from "node:fs"
+import { open, realpath, type FileHandle } from "node:fs/promises"
+import { resolve } from "node:path"
+import sharp from "sharp"
+import { type VectorizeDeadline } from "./limits.js"
+import { sha256 } from "./metrics.js"
+import { VectorizeError, type VectorizeInput, type VectorizeLimits } from "./types.js"
+
+const allowedFormats = new Set(["avif", "gif", "heif", "jpeg", "png", "tiff", "webp"])
+const METRIC_MAX_EDGE = 512
+export const VECTORIZE_SHARP_CONCURRENCY = 1
+
+export function configureVectorizeSharpConcurrency(): void {
+  // Each isolated vectorizer declares one host CPU unit. Bind libvips to the
+  // same budget inside that worker without mutating an SDK caller's Sharp pool.
+  const actual = sharp.concurrency(VECTORIZE_SHARP_CONCURRENCY)
+  if (actual !== VECTORIZE_SHARP_CONCURRENCY) {
+    throw new VectorizeError(
+      "trace_failed",
+      "The vectorization worker could not bind its Sharp CPU budget.",
+    )
+  }
+}
+
+export interface LoadedRaster {
+  readonly bytes: Uint8Array
+  readonly format: string
+  readonly height: number
+  readonly inputBytes: number
+  readonly pixels: Uint8Array
+  readonly scoreHeight: number
+  readonly scorePixels: Uint8Array
+  readonly scoreWidth: number
+  readonly sourceSha256: string
+  readonly width: number
+}
+
+export async function loadRaster(
+  input: VectorizeInput,
+  limits: Readonly<VectorizeLimits>,
+  deadline: VectorizeDeadline,
+): Promise<LoadedRaster> {
+  deadline.assert("input read")
+  const bytes = await readInputBytes(input, limits.maxInputBytes, deadline)
+  deadline.assert("input metadata")
+  try {
+    const metadata = await sharp(bytes, {
+      failOn: "error",
+      limitInputPixels: limits.maxDecodedPixels,
+      sequentialRead: true,
+    }).metadata()
+    const format = metadata.format
+    if (format === undefined || !allowedFormats.has(format)) {
+      throw new VectorizeError(
+        "invalid_input",
+        `Expected a supported raster image, received ${format ?? "an unknown format"}.`,
+      )
+    }
+    if ((metadata.pages ?? 1) !== 1) {
+      throw new VectorizeError("invalid_input", "Animated and multipage raster inputs are rejected.")
+    }
+    if (
+      metadata.width === undefined ||
+      metadata.height === undefined ||
+      metadata.width < 1 ||
+      metadata.height < 1
+    ) {
+      throw new VectorizeError("invalid_input", "Raster dimensions are missing or invalid.")
+    }
+    assertDimensions(metadata.width, metadata.height, limits)
+
+    const decoded = await sharp(bytes, {
+      failOn: "error",
+      limitInputPixels: limits.maxDecodedPixels,
+      sequentialRead: true,
+    })
+      .rotate()
+      .ensureAlpha()
+      .raw()
+      .toBuffer({ resolveWithObject: true })
+    const { channels, height, width } = decoded.info
+    if (channels !== 4) {
+      throw new VectorizeError("invalid_input", "Raster decoding did not produce RGBA pixels.")
+    }
+    assertDimensions(width, height, limits)
+    const pixels = Uint8Array.from(decoded.data)
+    if (!containsVisiblePixel(pixels)) {
+      throw new VectorizeError("invalid_input", "A fully transparent image cannot be vectorized.")
+    }
+    deadline.assert("raster decode")
+
+    const scoreScale = Math.min(1, METRIC_MAX_EDGE / Math.max(width, height))
+    const scoreWidth = Math.max(1, Math.round(width * scoreScale))
+    const scoreHeight = Math.max(1, Math.round(height * scoreScale))
+    const scorePixels =
+      scoreWidth === width && scoreHeight === height
+        ? pixels
+        : Uint8Array.from(
+            await sharp(pixels, { raw: { channels: 4, height, width } })
+              .resize(scoreWidth, scoreHeight, { fit: "fill", kernel: "lanczos3" })
+              .raw()
+              .toBuffer(),
+          )
+    deadline.assert("metric sample")
+    return {
+      bytes,
+      format,
+      height,
+      inputBytes: bytes.byteLength,
+      pixels,
+      scoreHeight,
+      scorePixels,
+      scoreWidth,
+      sourceSha256: sha256(bytes),
+      width,
+    }
+  } catch (error) {
+    if (error instanceof VectorizeError) throw error
+    throw new VectorizeError("invalid_input", "Raster input could not be decoded safely.", {}, {
+      cause: error,
+    })
+  }
+}
+
+async function readInputBytes(
+  input: VectorizeInput,
+  maximumBytes: number,
+  deadline: VectorizeDeadline,
+): Promise<Uint8Array> {
+  if (typeof input === "string") {
+    return readRegularInput(resolve(input), maximumBytes, deadline)
+  }
+  const view = input instanceof ArrayBuffer ? new Uint8Array(input) : input
+  if (view.byteLength === 0) {
+    throw new VectorizeError("invalid_input", "Raster input is empty.")
+  }
+  if (view.byteLength > maximumBytes) {
+    throw new VectorizeError(
+      "input_limit",
+      `Raster input exceeds the ${maximumBytes}-byte limit.`,
+      { bytes: view.byteLength, maximumBytes },
+    )
+  }
+  deadline.assert("input read")
+  const bytes = Uint8Array.from(view)
+  deadline.assert("input read")
+  return bytes
+}
+
+async function readRegularInput(
+  path: string,
+  maximumBytes: number,
+  deadline: VectorizeDeadline,
+): Promise<Uint8Array> {
+  let handle: FileHandle | undefined
+  try {
+    deadline.assert("input read")
+    const targetPath = await realpath(path)
+    deadline.assert("input read")
+    handle = await open(targetPath, boundedReadFlags())
+    const metadata = await handle.stat()
+    if (!metadata.isFile()) {
+      throw new VectorizeError("invalid_input", `Raster input is not a file: ${path}`)
+    }
+    if (metadata.size < 1) {
+      throw new VectorizeError("invalid_input", "Raster input is empty.")
+    }
+    if (metadata.size > maximumBytes) {
+      throw new VectorizeError(
+        "input_limit",
+        `Raster input exceeds the ${maximumBytes}-byte limit.`,
+        { bytes: metadata.size, maximumBytes },
+      )
+    }
+
+    const chunk = Buffer.allocUnsafe(Math.min(64 * 1_024, maximumBytes + 1))
+    const chunks: Buffer[] = []
+    let bytes = 0
+    while (true) {
+      deadline.assert("input read")
+      const maximumRead = Math.min(chunk.byteLength, maximumBytes - bytes + 1)
+      const { bytesRead } = await handle.read(chunk, 0, maximumRead, null)
+      if (bytesRead === 0) break
+      bytes += bytesRead
+      if (bytes > maximumBytes) {
+        throw new VectorizeError(
+          "input_limit",
+          `Raster input exceeds the ${maximumBytes}-byte limit.`,
+          { bytes, maximumBytes },
+        )
+      }
+      chunks.push(Buffer.from(chunk.subarray(0, bytesRead)))
+    }
+    if (bytes === 0) {
+      throw new VectorizeError("invalid_input", "Raster input is empty.")
+    }
+    deadline.assert("input read")
+    return Buffer.concat(chunks, bytes)
+  } catch (error) {
+    if (error instanceof VectorizeError) throw error
+    throw new VectorizeError(
+      "invalid_input",
+      "Raster input could not be read safely.",
+      {},
+      { cause: error },
+    )
+  } finally {
+    await handle?.close().catch(() => undefined)
+  }
+}
+
+function assertDimensions(
+  width: number,
+  height: number,
+  limits: Readonly<VectorizeLimits>,
+): void {
+  if (
+    !Number.isInteger(width) ||
+    !Number.isInteger(height) ||
+    width < 1 ||
+    height < 1 ||
+    width > limits.maxDimension ||
+    height > limits.maxDimension ||
+    width * height > limits.maxDecodedPixels
+  ) {
+    throw new VectorizeError(
+      "input_limit",
+      `Raster dimensions must fit ${limits.maxDimension}px and ${limits.maxDecodedPixels} decoded pixels.`,
+      { height, width },
+    )
+  }
+}
+
+function containsVisiblePixel(rgba: Uint8Array): boolean {
+  for (let index = 3; index < rgba.length; index += 4) {
+    if (rgba[index]! > 0) return true
+  }
+  return false
+}
+
+function boundedReadFlags(): number {
+  if (process.platform === "win32") return constants.O_RDONLY
+  return constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW
+}
+
+export async function encodeTracePng(
+  pixels: Uint8Array,
+  width: number,
+  height: number,
+): Promise<Uint8Array> {
+  return Uint8Array.from(
+    await sharp(pixels, { raw: { channels: 4, height, width } })
+      .png({ adaptiveFiltering: false, compressionLevel: 9, palette: false })
+      .toBuffer(),
+  )
+}
+
+export async function renderSvgRgba(
+  svg: string,
+  width: number,
+  height: number,
+  maxDecodedPixels: number,
+): Promise<Uint8Array> {
+  try {
+    return Uint8Array.from(
+      await sharp(Buffer.from(svg), {
+        density: 72,
+        failOn: "error",
+        limitInputPixels: maxDecodedPixels,
+      })
+        .resize(width, height, { fit: "fill" })
+        .ensureAlpha()
+        .raw()
+        .toBuffer(),
+    )
+  } catch (error) {
+    throw new VectorizeError(
+      "trace_failed",
+      "Canonical SVG could not be rendered for quality measurement.",
+      {},
+      { cause: error },
+    )
+  }
+}
+
+export function sharpProvenance(): Readonly<{
+  sharp: string
+  sharpVersions: Readonly<Record<string, string>>
+  vips: string
+}> {
+  const sharpVersions = normalizedPixelToolchain(sharp.versions)
+  const sharpVersion = sharpVersions.sharp
+  const vipsVersion = sharpVersions.vips
+  if (sharpVersion === undefined || vipsVersion === undefined) {
+    throw new VectorizeError(
+      "tool_version",
+      "Sharp must report its own and libvips version metadata.",
+    )
+  }
+  return {
+    sharp: sharpVersion,
+    sharpVersions,
+    vips: vipsVersion,
+  }
+}
+
+export function normalizedPixelToolchain(
+  versions: Readonly<Record<string, string | undefined>>,
+): Readonly<Record<string, string>> {
+  const entries = Object.entries(versions)
+    .filter((entry): entry is [string, string] => entry[1] !== undefined)
+    .sort(([left], [right]) => left.localeCompare(right))
+  if (
+    entries.length === 0 ||
+    entries.some(([name, version]) => name.length === 0 || version.length === 0)
+  ) {
+    throw new VectorizeError(
+      "tool_version",
+      "Pixel toolchain versions must be nonempty strings.",
+    )
+  }
+  return Object.freeze(Object.fromEntries(entries))
+}

package/src/vectorize/supervisor.ts

@@ -0,0 +1,339 @@
+import { fileURLToPath } from "node:url"
+import { mkdtemp, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { dirname, join } from "node:path"
+import { runBoundedCommand } from "./command.js"
+import { resolveVectorizeLimits } from "./limits.js"
+import {
+  MAX_VECTORIZE_REQUEST_BYTES,
+  MAX_VECTORIZE_RESPONSE_BYTES,
+  VECTORIZE_WORKER_PROTOCOL,
+  type VectorizeWorkerRequest,
+  type VectorizeWorkerResponse,
+} from "./worker-protocol.js"
+import {
+  VectorizeError,
+  vectorizeProfileNames,
+  type VectorizeErrorCode,
+  type VectorizeInput,
+  type VectorizeOptions,
+  type VectorizeResult,
+} from "./types.js"
+
+const vectorizeErrorCodes = new Set<VectorizeErrorCode>([
+  "input_limit",
+  "invalid_input",
+  "output_limit",
+  "quality_limit",
+  "timeout",
+  "tool_download",
+  "tool_integrity",
+  "tool_platform",
+  "tool_version",
+  "trace_failed",
+  "unsafe_svg",
+])
+const WORKER_SHUTDOWN_RESERVE_MS = 250
+const WORKER_RESPONSE_RESERVE_MS = 100
+
+export async function runVectorizeWorker(
+  input: VectorizeInput,
+  options: VectorizeOptions,
+): Promise<VectorizeResult> {
+  const startedAt = performance.now()
+  const limits = resolveVectorizeLimits(options.limits)
+  if (process.platform === "win32") {
+    throw new VectorizeError(
+      "tool_platform",
+      "Bounded VTracer streaming is unavailable on Windows.",
+      { platform: process.platform },
+    )
+  }
+  const workerInput = encodeInput(input, limits.maxInputBytes)
+  const temporaryRoot = await mkdtemp(join(tmpdir(), "slopcamera-vectorize-"))
+  let result: VectorizeResult
+  try {
+    result = await executeVectorizeWorker(
+      workerInput,
+      options,
+      limits,
+      startedAt,
+      temporaryRoot,
+    )
+  } finally {
+    await removeTemporaryRoot(temporaryRoot)
+  }
+  if (performance.now() - startedAt >= limits.maxDurationMs) {
+    throw new VectorizeError(
+      "timeout",
+      "Vectorization exceeded the conversion time limit during cleanup.",
+    )
+  }
+  return result
+}
+
+async function executeVectorizeWorker(
+  workerInput: VectorizeWorkerRequest["input"],
+  options: VectorizeOptions,
+  limits: ReturnType<typeof resolveVectorizeLimits>,
+  startedAt: number,
+  temporaryRoot: string,
+): Promise<VectorizeResult> {
+  const preparationRemainingMs =
+    limits.maxDurationMs - (performance.now() - startedAt)
+  if (
+    preparationRemainingMs <=
+    WORKER_SHUTDOWN_RESERVE_MS + WORKER_RESPONSE_RESERVE_MS
+  ) {
+    throw new VectorizeError(
+      "timeout",
+      "Vectorization has no remaining budget for isolated worker execution.",
+    )
+  }
+  const workerDurationMs = Math.floor(
+    preparationRemainingMs -
+      WORKER_SHUTDOWN_RESERVE_MS -
+      WORKER_RESPONSE_RESERVE_MS,
+  )
+  const inheritedFileDescriptors = inheritedDescriptors(
+    options.inheritedFileDescriptors,
+  )
+  const workerInheritedFileDescriptors = inheritedFileDescriptors.map(
+    (_descriptor, index) => index + 3,
+  )
+  const request: VectorizeWorkerRequest = {
+    input: workerInput,
+    options: cloneOptions(
+      options,
+      workerDurationMs,
+      workerInheritedFileDescriptors,
+    ),
+    protocol: VECTORIZE_WORKER_PROTOCOL,
+    temporaryRoot,
+  }
+  const requestBytes = Buffer.from(JSON.stringify(request))
+  if (requestBytes.byteLength > MAX_VECTORIZE_REQUEST_BYTES) {
+    throw new VectorizeError(
+      "input_limit",
+      "The vectorization worker request exceeds its IPC limit.",
+      {
+        bytes: requestBytes.byteLength,
+        maximumBytes: MAX_VECTORIZE_REQUEST_BYTES,
+      },
+    )
+  }
+  const remainingMs = limits.maxDurationMs - (performance.now() - startedAt)
+  if (remainingMs <= WORKER_SHUTDOWN_RESERVE_MS) {
+    throw new VectorizeError(
+      "timeout",
+      "Vectorization has no remaining budget for isolated worker startup and cleanup.",
+    )
+  }
+
+  const { stdout } = await runBoundedCommand(
+    [process.execPath, workerEntryPath()],
+    Math.floor(remainingMs - WORKER_SHUTDOWN_RESERVE_MS),
+    "trace_failed",
+    {
+      ...(inheritedFileDescriptors.length === 0
+        ? {}
+        : { inheritedFileDescriptors }),
+      maxStdoutBytes: MAX_VECTORIZE_RESPONSE_BYTES,
+      stdin: requestBytes,
+    },
+  )
+  if (performance.now() - startedAt >= limits.maxDurationMs) {
+    throw new VectorizeError(
+      "timeout",
+      "Vectorization exceeded the conversion time limit.",
+    )
+  }
+  const response = parseResponse(stdout)
+  if (!response.ok) {
+    throw new VectorizeError(
+      response.error.code,
+      response.error.message,
+      response.error.details,
+    )
+  }
+  assertResult(response.result, limits.maxOutputBytes)
+  if (performance.now() - startedAt >= limits.maxDurationMs) {
+    throw new VectorizeError(
+      "timeout",
+      "Vectorization exceeded the conversion time limit.",
+    )
+  }
+  return response.result
+}
+
+async function removeTemporaryRoot(temporaryRoot: string): Promise<void> {
+  try {
+    await rm(temporaryRoot, { force: true, recursive: true })
+  } catch (error) {
+    throw new VectorizeError(
+      "trace_failed",
+      "The isolated vectorization directory could not be removed.",
+      { temporaryRoot },
+      { cause: error },
+    )
+  }
+}
+
+function encodeInput(
+  input: VectorizeInput,
+  maximumInputBytes: number,
+): VectorizeWorkerRequest["input"] {
+  return typeof input === "string"
+    ? { kind: "path", value: input }
+    : encodeBytes(input, maximumInputBytes)
+}
+
+function encodeBytes(
+  input: Uint8Array | ArrayBuffer,
+  maximumInputBytes: number,
+): Readonly<{ kind: "bytes"; value: string }> {
+  const view = input instanceof ArrayBuffer ? new Uint8Array(input) : input
+  if (view.byteLength < 1) {
+    throw new VectorizeError("invalid_input", "Raster input is empty.")
+  }
+  if (view.byteLength > maximumInputBytes) {
+    throw new VectorizeError(
+      "input_limit",
+      `Raster input exceeds the ${maximumInputBytes}-byte limit.`,
+      { bytes: view.byteLength, maximumBytes: maximumInputBytes },
+    )
+  }
+  return {
+    kind: "bytes",
+    value: Buffer.from(view.buffer, view.byteOffset, view.byteLength).toString("base64"),
+  }
+}
+
+function cloneOptions(
+  options: VectorizeOptions,
+  workerDurationMs: number,
+  inheritedFileDescriptors: readonly number[],
+): VectorizeOptions {
+  return {
+    ...(options.alphaCutoff === undefined ? {} : { alphaCutoff: options.alphaCutoff }),
+    ...(options.cacheDirectory === undefined
+      ? {}
+      : { cacheDirectory: options.cacheDirectory }),
+    ...(options.duotone === undefined
+      ? {}
+      : { duotone: [options.duotone[0], options.duotone[1]] as const }),
+    ...(inheritedFileDescriptors.length === 0
+      ? {}
+      : { inheritedFileDescriptors }),
+    limits: {
+      ...options.limits,
+      maxDurationMs: workerDurationMs,
+    },
+    ...(options.outputPath === undefined ? {} : { outputPath: options.outputPath }),
+  }
+}
+
+function inheritedDescriptors(
+  value: readonly number[] | undefined,
+): readonly number[] {
+  const descriptors = value ?? []
+  if (
+    descriptors.length > 16
+    || descriptors.some((descriptor, index) => (
+      !Number.isSafeInteger(descriptor)
+      || descriptor < 0
+      || descriptor > 2_147_483_647
+      || descriptors.indexOf(descriptor) !== index
+    ))
+  ) {
+    throw new VectorizeError(
+      "invalid_input",
+      "Inherited vectorizer descriptors must be unique bounded integers.",
+    )
+  }
+  return Object.freeze([...descriptors])
+}
+
+function workerEntryPath(): string {
+  const modulePath = fileURLToPath(import.meta.url)
+  return modulePath.endsWith(".ts")
+    ? join(dirname(modulePath), "worker.ts")
+    : join(dirname(modulePath), "vectorize", "worker.js")
+}
+
+function parseResponse(stdout: string): VectorizeWorkerResponse {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(stdout)
+  } catch (error) {
+    throw new VectorizeError(
+      "trace_failed",
+      "The vectorization worker returned malformed output.",
+      {},
+      { cause: error },
+    )
+  }
+  if (!isRecord(parsed) || parsed.protocol !== VECTORIZE_WORKER_PROTOCOL) {
+    throw new VectorizeError(
+      "trace_failed",
+      "The vectorization worker returned an incompatible response.",
+    )
+  }
+  if (parsed.ok === true && isVectorizeResult(parsed.result)) {
+    return parsed as unknown as VectorizeWorkerResponse
+  }
+  if (
+    parsed.ok === false &&
+    isRecord(parsed.error) &&
+    typeof parsed.error.code === "string" &&
+    vectorizeErrorCodes.has(parsed.error.code as VectorizeErrorCode) &&
+    typeof parsed.error.message === "string" &&
+    isRecord(parsed.error.details)
+  ) {
+    return parsed as unknown as VectorizeWorkerResponse
+  }
+  throw new VectorizeError(
+    "trace_failed",
+    "The vectorization worker returned an invalid response.",
+  )
+}
+
+function assertResult(result: VectorizeResult, maximumOutputBytes: number): void {
+  const bytes = Buffer.byteLength(result.svg)
+  if (
+    bytes < 1 ||
+    bytes > maximumOutputBytes ||
+    result.receipt.bytes !== bytes ||
+    result.receipt.svgSha256.length !== 64
+  ) {
+    throw new VectorizeError(
+      "trace_failed",
+      "The vectorization worker response violates its output contract.",
+      { bytes, maximumOutputBytes },
+    )
+  }
+}
+
+function isVectorizeResult(value: unknown): value is VectorizeResult {
+  if (
+    !isRecord(value) ||
+    (value.outputPath !== null && typeof value.outputPath !== "string") ||
+    typeof value.svg !== "string" ||
+    !isRecord(value.receipt)
+  ) {
+    return false
+  }
+  const profile = value.receipt.profile
+  return (
+    typeof value.receipt.bytes === "number" &&
+    typeof value.receipt.svgSha256 === "string" &&
+    typeof profile === "string" &&
+    vectorizeProfileNames.includes(
+      profile as (typeof vectorizeProfileNames)[number],
+    )
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}