generateThumbs.ts

generateThumbs.tsapps/worker/src/processors/files/generateThumbs.tsraw ← files7,835 B← Back to the app
1/**
2 * apps/worker — thumbnail generation (TASK-0102 §5).
3 *
4 * Consumes the PURE plan from `@factory/storage` `planThumbnails` (keys,
5 * target widths, output mime, `source` kind) and does the REAL pixel work the
6 * storage package deliberately doesn't ship (its header reads only PNG/JPEG):
7 *
8 *   - image           → sharp resize (same output format; webp/avif/heic/tiff
9 *                       rasterized to PNG — the plan's `mime` for those is the
10 *                       rasterized format, so we follow the plan, never the
11 *                       source container)
12 *   - pdf-page-1      → pdfjs-dist (legacy build) renders page 1 to a
13 *                       node-canvas canvas; sharp normalizes to 1280w PNG
14 *   - video-first-frame → ffmpeg `-frames:v 1` PNG; sharp normalizes to 1280w
15 *
16 * Every artifact is written to the `thumbs` bucket by the caller
17 * (finalize/thumbnails step) at its planned key — key-idempotent (re-running
18 * a READY file's job is a no-op upstream, so these keys are never overwritten
19 * with different bytes). `File.thumbnailKey` = the 480 variant (primary UI
20 * thumb); `File.thumbnailUrl` is regenerated on read (never stored).
21 *
22 * Licensing (AGENTS.md rule 17): `sharp` (Apache-2.0 + bundled libvips —
23 * image decode/resize), `pdfjs-dist` (Apache-2.0 — PDF page model + render),
24 * `canvas` (MIT — the canvas2d context pdfjs renders into), `ffmpeg`
25 * (LGPL, system binary in the worker image — video frame grab).
26 */
27import { execFile } from "node:child_process";
28import { promisify } from "node:util";
29import { unlink } from "node:fs/promises";
30import { randomUUID } from "node:crypto";
31import { planThumbnails } from "@factory/storage";
32import { getSharp } from "../../lib/sharp.js";
33import { getLogger } from "../../logger.js";
34import { FatalError } from "./errors.js";
35 
36const log = getLogger("files.thumbs");
37const pExecFile = promisify(execFile);
38 
39/** One produced artifact (key in the thumbs bucket + its bytes). */
40export interface ThumbArtifact {
41  key: string;
42  body: Buffer;
43  mime: string;
44}
45 
46export interface GenerateThumbsArgs {
47  /** Path to the on-disk copy of the object. */
48  sourcePath: string;
49  /** The re-sniffed (authoritative) mime. */
50  mime: string;
51  workspaceId: string;
52  fileId: string;
53  /** Original name (stem is derived inside planThumbnails). */
54  name: string;
55  /** Source image width (skips upscale — from the metadata step). */
56  sourceWidth?: number;
57}
58 
59/**
60 * Produce every planned thumbnail. Returns the artifacts (NOT yet uploaded)
61 * — the caller writes them (keeps this module I/O-light for tests).
62 *
63 * Throws FatalError on a corrupt/undecodable source (the object's kind was
64 * identified by magic bytes, so a decode failure here is a permanent,
65 * non-retryable condition — the row goes FAILED).
66 */
67export async function generateThumbs(
68  args: GenerateThumbsArgs
69): Promise<{ artifacts: ThumbArtifact[]; primaryKey: string | null }> {
70  const plan = planThumbnails({
71    mime: args.mime,
72    workspaceId: args.workspaceId,
73    fileId: args.fileId,
74    name: args.name,
75    ...(args.sourceWidth !== undefined ? { sourceWidth: args.sourceWidth } : {})
76  });
77  if (plan.length === 0) return { artifacts: [], primaryKey: null };
78 
79  const artifacts: ThumbArtifact[] = [];
80  for (const item of plan) {
81    let body: Buffer;
82    if (item.source === "image") {
83      body = await renderImage(args.sourcePath, item.targetWidth, item.mime);
84    } else if (item.source === "pdf-page-1") {
85      body = await renderPdfPage1(args.sourcePath, item.targetWidth);
86    } else {
87      body = await renderVideoFrame(args.sourcePath, item.targetWidth);
88    }
89    artifacts.push({ key: item.key, body, mime: item.mime });
90  }
91 
92  const primaryKey =
93    artifacts.find((a) => a.key.includes("/480/"))?.key ??
94    artifacts[0]?.key ??
95    null;
96  log.info(
97    {
98      fileId: args.fileId,
99      count: artifacts.length,
100      primaryKey,
101      bytes: artifacts.reduce((n, a) => n + a.body.length, 0)
102    },
103    "thumbnails generated"
104  );
105  return { artifacts, primaryKey };
106}
107 
108// ── image (sharp) ───────────────────────────────────────────────────────────
109 
110/** Resize an image to `targetWidth` in `format` (e.g. "jpeg", "webp", "png"). */
111async function renderImage(sourcePath: string, targetWidth: number, format: string): Promise<Buffer> {
112  const sharp = await getSharp();
113  const formatName = outputFormatName(format);
114  const pipe = sharp(sourcePath)
115    .rotate() // honor EXIF orientation
116    .resize({ width: targetWidth, withoutEnlargement: true });
117  try {
118    return await pipe.toFormat(formatName).toBuffer();
119  } catch (err) {
120    throw new FatalError(
121      `image thumbnail failed: ${(err as Error).message}`,
122      "corrupt_object"
123    );
124  }
125}
126 
127/** The plan's mime → sharp format name (mime's subtype minus parameters). */
128function outputFormatName(mime: string): string {
129  const sub = mime.split("/")[1] ?? "png";
130  const name = sub.split(";")[0]!.trim().toLowerCase();
131  // sharp understands "jpeg" (not "jpg").
132  return name === "jpg" ? "jpeg" : name;
133}
134 
135// ── PDF first page (pdfjs + node-canvas → sharp) ────────────────────────────
136 
137/** Render PDF page 1 to a PNG of `targetWidth` width. */
138async function renderPdfPage1(sourcePath: string, targetWidth: number): Promise<Buffer> {
139  const { getDocument } = await import("pdfjs-dist/legacy/build/pdf.mjs");
140  const { createCanvas } = await import("canvas");
141  const sharp = await getSharp();
142  const { readFile } = await import("node:fs/promises");
143 
144  const data = new Uint8Array(await readFile(sourcePath));
145  const doc = await getDocument({
146    data,
147    useSystemFonts: true,
148    disableFontFace: true,
149  }).promise;
150  try {
151    const page = await doc.getPage(1);
152    const baseW = page.getViewport({ scale: 1 }).width || 1;
153    const vp = page.getViewport({ scale: targetWidth / baseW });
154    const canvas = createCanvas(Math.max(1, Math.floor(vp.width)), Math.max(1, Math.floor(vp.height)));
155    await page.render({
156      canvasContext: canvas.getContext("2d"),
157      viewport: vp
158    } as never).promise;
159    // The canvas is already ~targetWidth; sharp normalizes exactly (and
160    // de-alpha-composites to a clean PNG).
161    const png = await sharp(canvas.toBuffer("image/png")).png().toBuffer();
162    return png;
163  } catch (err) {
164    throw new FatalError(
165      `pdf thumbnail failed: ${(err as Error).message}`,
166      "corrupt_object"
167    );
168  }
169}
170 
171// ── video first frame (ffmpeg → sharp) ──────────────────────────────────────
172 
173/** Grab the first video frame as a PNG of `targetWidth` width. */
174async function renderVideoFrame(sourcePath: string, targetWidth: number): Promise<Buffer> {
175  const sharp = await getSharp();
176  const tmpPng = `/tmp/thumb-frame-${randomUUID()}.png`;
177  try {
178    await pExecFile(
179      "ffmpeg",
180      [
181        "-v", "error",
182        "-ss", "0",
183        "-i", sourcePath,
184        "-frames:v", "1",
185        "-q:v", "2",
186        "-y",
187        tmpPng
188      ],
189      { timeout: 30_000, maxBuffer: 1024 * 1024 }
190    );
191    const sharpInstance = sharp(tmpPng)
192      .rotate()
193      .resize({ width: targetWidth, withoutEnlargement: true });
194    return await sharpInstance.png().toBuffer();
195  } catch (err) {
196    // ffmpeg exits non-zero with stderr when the stream has no video frame
197    // (audio-only file claimed as video, or corrupt container).
198    const msg = err instanceof Error ? err.message : String(err);
199    throw new FatalError(`video thumbnail failed: ${msg}`, "corrupt_object");
200  } finally {
201    await unlink(tmpPng).catch(() => {});
202  }
203}
204