258 lines
11 KiB
TypeScript
258 lines
11 KiB
TypeScript
// AK-P4a §4 — file-preview service (BullMQ `toolctrl.file-preview`).
|
|
//
|
|
// Mirrors scanService.ts: a dedicated AWS S3 client built from STORAGE_* env
|
|
// GETs the original, renders the preview and PUTs preview/thumb into the same
|
|
// private bucket (AD-23). previewStatus is written back onto the File row
|
|
// (pending -> generating -> ready|failed|not_supported).
|
|
//
|
|
// Format matrix v1 (designer brief 2026-06-12):
|
|
// image/heic|heif -> heic-convert -> JPG -> preview.jpg + thumb.webp
|
|
// image/jpeg|png|gif|webp -> sharp -> WebP -> preview.webp + thumb.webp
|
|
// application/pdf -> pdf-to-png -> PNG -> preview.png + thumb.webp
|
|
// text/plain | markdown -> ready (inline render from bytes, no file)
|
|
// anything else -> not_supported
|
|
//
|
|
// The native render libs (sharp, heic-convert, pdf-to-png-converter) are loaded
|
|
// via dynamic string import (same pattern as qdrant/sentry in index.ts) so
|
|
// typecheck/build stay green before they are installed.
|
|
// ACTIVATION: `pnpm add sharp heic-convert pdf-to-png-converter -F @toolctrl/worker`.
|
|
// If a lib is missing at runtime the service falls back cleanly to
|
|
// previewStatus=failed (no hard crash) and the user can regenerate from detail.
|
|
|
|
import { GetObjectCommand, PutObjectCommand, S3Client as AwsS3Client } from "@aws-sdk/client-s3";
|
|
import type { EnvRecord } from "@toolctrl/config";
|
|
import type { FilePreviewJob } from "@toolctrl/queue";
|
|
import { buildFilePreviewKey, buildFileStorageKeys, type FilePreviewExtension } from "@toolctrl/storage";
|
|
|
|
import { withTenantRLS } from "../db/tenantRls.js";
|
|
import type { FilePreviewServiceResult } from "../handlers.js";
|
|
|
|
export interface FilePreviewServiceEnv {
|
|
STORAGE_ENDPOINT?: string;
|
|
STORAGE_REGION?: string;
|
|
STORAGE_ACCESS_KEY_ID?: string;
|
|
STORAGE_SECRET_ACCESS_KEY?: string;
|
|
STORAGE_SESSION_TOKEN?: string;
|
|
STORAGE_FORCE_PATH_STYLE?: string;
|
|
}
|
|
|
|
type PreviewLogger = {
|
|
info: (fields: Record<string, unknown>, msg: string) => void;
|
|
warn: (fields: Record<string, unknown>, msg: string) => void;
|
|
error: (fields: Record<string, unknown>, msg: string) => void;
|
|
};
|
|
|
|
/**
|
|
* The File write surface the preview status write-back uses. `$executeRaw` is
|
|
* required so the helper can set `app.tenant_id` on the transaction (AK-P4a RLS
|
|
* prep). `data` stays string-typed to avoid coupling to the generated Prisma
|
|
* enum types (keeps the dynamic-import build green before native libs install).
|
|
*/
|
|
interface FilePreviewTx {
|
|
$executeRaw(query: TemplateStringsArray, ...values: unknown[]): Promise<number>;
|
|
file: {
|
|
update(args: {
|
|
where: { id: string };
|
|
data: {
|
|
previewStatus?: string;
|
|
previewStorageKey?: string | null;
|
|
thumbnailStorageKey?: string | null;
|
|
};
|
|
}): Promise<unknown>;
|
|
};
|
|
}
|
|
|
|
/** Minimal Prisma surface the service needs (tenant transaction). */
|
|
export interface FilePreviewPrisma {
|
|
$transaction<T>(fn: (tx: FilePreviewTx) => Promise<T>): Promise<T>;
|
|
}
|
|
|
|
export interface FilePreviewService {
|
|
generatePreview(payload: FilePreviewJob): Promise<FilePreviewServiceResult>;
|
|
}
|
|
|
|
const THUMBNAIL_MAX_DIMENSION = 480;
|
|
const PREVIEW_MAX_DIMENSION = 2048;
|
|
|
|
const RASTER_IMAGE_TYPES = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
|
|
const HEIC_TYPES = new Set(["image/heic", "image/heif"]);
|
|
const TEXT_TYPES = new Set(["text/plain", "text/markdown", "text/csv"]);
|
|
|
|
function normalizeMime(mimeType: string): string {
|
|
return mimeType.split(";")[0]?.trim().toLowerCase() ?? "";
|
|
}
|
|
|
|
/**
|
|
* Builds the preview service from STORAGE_* env. Returns undefined when the S3
|
|
* credentials are missing (the bootstrap wiring then skips it and the handler
|
|
* refuses jobs with a config error instead of running blind).
|
|
*/
|
|
export function createWorkerFilePreviewService(
|
|
env: EnvRecord & FilePreviewServiceEnv,
|
|
options: { prisma: FilePreviewPrisma; logger: PreviewLogger },
|
|
): FilePreviewService | undefined {
|
|
if (!env.STORAGE_REGION || !env.STORAGE_ACCESS_KEY_ID || !env.STORAGE_SECRET_ACCESS_KEY) {
|
|
return undefined;
|
|
}
|
|
|
|
const { prisma, logger } = options;
|
|
const s3 = new AwsS3Client({
|
|
endpoint: env.STORAGE_ENDPOINT,
|
|
region: env.STORAGE_REGION,
|
|
forcePathStyle: env.STORAGE_FORCE_PATH_STYLE === "true",
|
|
credentials: {
|
|
accessKeyId: env.STORAGE_ACCESS_KEY_ID,
|
|
secretAccessKey: env.STORAGE_SECRET_ACCESS_KEY,
|
|
sessionToken: env.STORAGE_SESSION_TOKEN,
|
|
},
|
|
});
|
|
|
|
async function loadOriginal(bucket: string, key: string): Promise<Buffer> {
|
|
const result = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
|
|
const body = result.Body;
|
|
if (!body) {
|
|
throw new Error(`S3 GET ${bucket}/${key} returned an empty body`);
|
|
}
|
|
// The AWS SDK exposes transformToByteArray() on the Node stream body.
|
|
const bytes = await (body as { transformToByteArray(): Promise<Uint8Array> }).transformToByteArray();
|
|
return Buffer.from(bytes);
|
|
}
|
|
|
|
async function putRendered(bucket: string, key: string, body: Buffer, contentType: string): Promise<void> {
|
|
await s3.send(new PutObjectCommand({ Bucket: bucket, Key: key, Body: body, ContentType: contentType }));
|
|
}
|
|
|
|
async function writeStatus(
|
|
tenantId: string,
|
|
fileId: string,
|
|
data: { previewStatus: string; previewStorageKey?: string | null; thumbnailStorageKey?: string | null },
|
|
): Promise<void> {
|
|
// Set the tenant GUC so the write satisfies the File RLS policy once it is
|
|
// activated (P5 cutover). Preview jobs always carry a tenantId.
|
|
await withTenantRLS(prisma, tenantId, (tx) => tx.file.update({ where: { id: fileId }, data }));
|
|
}
|
|
|
|
return {
|
|
async generatePreview(payload: FilePreviewJob): Promise<FilePreviewServiceResult> {
|
|
const mime = normalizeMime(payload.mimeType);
|
|
const keys = buildFileStorageKeys(payload.tenantId, payload.fileId);
|
|
|
|
// Plain text / markdown: detail view renders inline from bytes, no
|
|
// rendered preview file needed.
|
|
if (TEXT_TYPES.has(mime)) {
|
|
await writeStatus(payload.tenantId, payload.fileId, { previewStatus: "ready", previewStorageKey: null, thumbnailStorageKey: null });
|
|
return { previewStatus: "ready" };
|
|
}
|
|
|
|
const isHeic = HEIC_TYPES.has(mime);
|
|
const isRaster = RASTER_IMAGE_TYPES.has(mime);
|
|
const isPdf = mime === "application/pdf";
|
|
|
|
if (!isHeic && !isRaster && !isPdf) {
|
|
await writeStatus(payload.tenantId, payload.fileId, { previewStatus: "not_supported", previewStorageKey: null, thumbnailStorageKey: null });
|
|
return { previewStatus: "not_supported" };
|
|
}
|
|
|
|
await writeStatus(payload.tenantId, payload.fileId, { previewStatus: "generating" });
|
|
|
|
try {
|
|
const original = await loadOriginal(payload.bucket, payload.storageKey);
|
|
let previewBuffer: Buffer;
|
|
let previewExt: FilePreviewExtension;
|
|
let previewContentType: string;
|
|
|
|
if (isHeic) {
|
|
// HEIC -> JPG (mandatory for iPhone field-worker photos).
|
|
const jpg = await heicToJpeg(original);
|
|
previewBuffer = await rasterToFormat(jpg, "jpeg", PREVIEW_MAX_DIMENSION);
|
|
previewExt = "jpg";
|
|
previewContentType = "image/jpeg";
|
|
} else if (isPdf) {
|
|
const png = await pdfFirstPageToPng(original);
|
|
previewBuffer = await rasterToFormat(png, "png", PREVIEW_MAX_DIMENSION);
|
|
previewExt = "png";
|
|
previewContentType = "image/png";
|
|
} else {
|
|
previewBuffer = await rasterToFormat(original, "webp", PREVIEW_MAX_DIMENSION);
|
|
previewExt = "webp";
|
|
previewContentType = "image/webp";
|
|
}
|
|
|
|
const thumbnail = await rasterToFormat(previewBuffer, "webp", THUMBNAIL_MAX_DIMENSION);
|
|
|
|
const previewKey = buildFilePreviewKey(payload.tenantId, payload.fileId, previewExt);
|
|
const thumbnailKey = keys.thumbnail;
|
|
|
|
await putRendered(payload.bucket, previewKey, previewBuffer, previewContentType);
|
|
await putRendered(payload.bucket, thumbnailKey, thumbnail, "image/webp");
|
|
|
|
await writeStatus(payload.tenantId, payload.fileId, {
|
|
previewStatus: "ready",
|
|
previewStorageKey: previewKey,
|
|
thumbnailStorageKey: thumbnailKey,
|
|
});
|
|
|
|
return { previewStatus: "ready", previewStorageKey: previewKey, thumbnailStorageKey: thumbnailKey };
|
|
} catch (error) {
|
|
const reason = error instanceof Error ? error.message : String(error);
|
|
logger.warn({ fileId: payload.fileId, tenantId: payload.tenantId, mime }, "file preview generation failed");
|
|
await writeStatus(payload.tenantId, payload.fileId, { previewStatus: "failed" });
|
|
return { previewStatus: "failed", reason };
|
|
}
|
|
},
|
|
};
|
|
}
|
|
|
|
// --- dynamic native-lib loaders (kept untyped so build stays green pre-install) ---
|
|
|
|
type SharpFactory = (input: Buffer) => {
|
|
rotate(): ReturnType<SharpFactory>;
|
|
resize(opts: { width: number; height: number; fit: "inside"; withoutEnlargement: boolean }): ReturnType<SharpFactory>;
|
|
jpeg(opts: { quality: number }): ReturnType<SharpFactory>;
|
|
png(): ReturnType<SharpFactory>;
|
|
webp(opts: { quality: number }): ReturnType<SharpFactory>;
|
|
toBuffer(): Promise<Buffer>;
|
|
};
|
|
|
|
let sharpModule: SharpFactory | undefined;
|
|
async function loadSharp(): Promise<SharpFactory> {
|
|
if (sharpModule) return sharpModule;
|
|
const moduleName = "sharp";
|
|
const loaded = (await import(/* @vite-ignore */ moduleName)) as { default?: SharpFactory } & SharpFactory;
|
|
sharpModule = (loaded.default ?? loaded) as SharpFactory;
|
|
return sharpModule;
|
|
}
|
|
|
|
async function rasterToFormat(input: Buffer, format: "jpeg" | "png" | "webp", maxDimension: number): Promise<Buffer> {
|
|
const sharp = await loadSharp();
|
|
const pipeline = sharp(input)
|
|
.rotate()
|
|
.resize({ width: maxDimension, height: maxDimension, fit: "inside", withoutEnlargement: true });
|
|
if (format === "jpeg") return pipeline.jpeg({ quality: 82 }).toBuffer();
|
|
if (format === "png") return pipeline.png().toBuffer();
|
|
return pipeline.webp({ quality: 80 }).toBuffer();
|
|
}
|
|
|
|
async function heicToJpeg(input: Buffer): Promise<Buffer> {
|
|
const moduleName = "heic-convert";
|
|
const loaded = (await import(/* @vite-ignore */ moduleName)) as
|
|
| { default: (opts: { buffer: Buffer; format: "JPEG"; quality: number }) => Promise<ArrayBuffer | Buffer> }
|
|
| ((opts: { buffer: Buffer; format: "JPEG"; quality: number }) => Promise<ArrayBuffer | Buffer>);
|
|
const convert = typeof loaded === "function" ? loaded : loaded.default;
|
|
const out = await convert({ buffer: input, format: "JPEG", quality: 0.85 });
|
|
return Buffer.from(out as ArrayBuffer);
|
|
}
|
|
|
|
async function pdfFirstPageToPng(input: Buffer): Promise<Buffer> {
|
|
const moduleName = "pdf-to-png-converter";
|
|
const loaded = (await import(/* @vite-ignore */ moduleName)) as {
|
|
pdfToPng: (input: Buffer, opts: Record<string, unknown>) => Promise<Array<{ content: Buffer }>>;
|
|
};
|
|
const pages = await loaded.pdfToPng(input, { pagesToProcess: [1], viewportScale: 2.0 });
|
|
const first = pages[0];
|
|
if (!first) {
|
|
throw new Error("PDF rendered no pages");
|
|
}
|
|
return Buffer.from(first.content);
|
|
}
|