@xenterprises/fastify-ximagepipeline 1.1.1 → 1.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xenterprises/fastify-ximagepipeline",
   "type": "module",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Fastify plugin for image uploads with EXIF stripping, moderation, variant generation, and R2 storage with job queue",
   "main": "src/xImagePipeline.js",
   "exports": {
@@ -29,7 +29,7 @@
     "webp"
   ],
   "author": "Tim Mushen",
-  "license": "ISC",
+  "license": "UNLICENSED",
   "repository": {
     "type": "git",
     "url": "git@gitlab.com:x-enterprises/fastify-plugins/fastify-x-imagepipeline.git"

package/src/routes/status.js

@@ -11,7 +11,7 @@ export async function setupStatusRoute(fastify, context) {
 
       if (!jobId) {
         return reply.status(400).send({
-          error: "jobId parameter required",
+          error: "[xImagePipeline] jobId parameter required",
         });
       }
 
@@ -25,7 +25,7 @@ export async function setupStatusRoute(fastify, context) {
 
       if (!job) {
         return reply.status(404).send({
-          error: "Job not found",
+          error: "[xImagePipeline] Job not found",
         });
       }
 
@@ -68,20 +68,18 @@ export async function setupStatusRoute(fastify, context) {
       // Determine HTTP status code
       let statusCode = 200;
       if (job.status === "PENDING" || job.status === "PROCESSING") {
-        statusCode = 202; // Still processing
-      } else if (job.status === "COMPLETE") {
-        statusCode = 200; // Done
+        statusCode = 202;
       } else if (job.status === "REJECTED") {
-        statusCode = 400; // Bad request (content rejected)
+        statusCode = 400;
       } else if (job.status === "FAILED") {
-        statusCode = 500; // Server error
+        statusCode = 500;
       }
 
       return reply.status(statusCode).send(response);
     } catch (error) {
-      console.error("Status check error:", error);
+      fastify.log.error({ err: error }, "[xImagePipeline] Status check error");
       return reply.status(500).send({
-        error: "Failed to check job status",
+        error: "[xImagePipeline] Failed to check job status",
       });
     }
   });

package/src/routes/upload.js

@@ -1,5 +1,5 @@
 // src/routes/upload.js
-import { uploadToS3, getPublicUrl } from "../services/s3.js";
+import { uploadToS3, deleteFromS3 } from "../services/s3.js";
 import { getVariantPresets } from "../xImagePipeline.js";
 
 /**
@@ -13,7 +13,7 @@ export async function setupUploadRoute(fastify, context) {
 
       if (!data) {
         return reply.status(400).send({
-          error: "No file provided",
+          error: "[xImagePipeline] No file provided",
         });
       }
 
@@ -27,7 +27,7 @@ export async function setupUploadRoute(fastify, context) {
       // Validate file type
       if (!context.allowedMimeTypes.includes(mimetype)) {
         return reply.status(400).send({
-          error: `File type ${mimetype} not allowed. Allowed types: ${context.allowedMimeTypes.join(", ")}`,
+          error: `[xImagePipeline] File type ${mimetype} not allowed. Allowed types: ${context.allowedMimeTypes.join(", ")}`,
         });
       }
 
@@ -37,7 +37,7 @@ export async function setupUploadRoute(fastify, context) {
 
       if (!sourceType || !sourceId) {
         return reply.status(400).send({
-          error: "sourceType and sourceId are required",
+          error: "[xImagePipeline] sourceType and sourceId are required",
         });
       }
 
@@ -45,7 +45,7 @@ export async function setupUploadRoute(fastify, context) {
       const presets = getVariantPresets();
       if (!presets[sourceType]) {
         return reply.status(400).send({
-          error: `Unknown sourceType: ${sourceType}. Allowed types: ${Object.keys(presets).join(", ")}`,
+          error: `[xImagePipeline] Unknown sourceType: ${sourceType}. Allowed types: ${Object.keys(presets).join(", ")}`,
         });
       }
 
@@ -55,7 +55,7 @@ export async function setupUploadRoute(fastify, context) {
       // Validate file size
       if (buffer.length > context.maxFileSize) {
         return reply.status(413).send({
-          error: `File too large. Maximum size: ${context.maxFileSize / 1024 / 1024}MB`,
+          error: `[xImagePipeline] File too large. Maximum size: ${context.maxFileSize / 1024 / 1024}MB`,
         });
       }
 
@@ -75,9 +75,9 @@ export async function setupUploadRoute(fastify, context) {
           },
         });
       } catch (err) {
-        console.error("R2 upload failed:", err.message);
+        fastify.log.error({ err, stagingKey }, "[xImagePipeline] R2 upload failed");
         return reply.status(500).send({
-          error: "Failed to upload file to storage",
+          error: "[xImagePipeline] Failed to upload file to storage",
         });
       }
 
@@ -98,7 +98,7 @@ export async function setupUploadRoute(fastify, context) {
 
         jobId = job.id;
       } catch (err) {
-        console.error("Database create failed:", err.message);
+        fastify.log.error({ err, stagingKey }, "[xImagePipeline] Database create failed");
         // Try to clean up uploaded file
         try {
           await deleteFromS3(context.s3Client, context.r2Config.bucket, stagingKey);
@@ -107,7 +107,7 @@ export async function setupUploadRoute(fastify, context) {
         }
 
         return reply.status(500).send({
-          error: "Failed to create processing job",
+          error: "[xImagePipeline] Failed to create processing job",
         });
       }
 
@@ -118,15 +118,10 @@ export async function setupUploadRoute(fastify, context) {
         statusUrl: `/image-pipeline/status/${jobId}`,
       });
     } catch (error) {
-      console.error("Upload error:", error);
+      fastify.log.error({ err: error }, "[xImagePipeline] Upload error");
       return reply.status(500).send({
-        error: "Upload failed",
+        error: "[xImagePipeline] Upload failed",
       });
     }
   });
 }
-
-/**
- * Helper function to delete from S3 (imported from service)
- */
-import { deleteFromS3 } from "../services/s3.js";

package/src/utils/image.js

@@ -4,34 +4,28 @@ import { encode } from "blurhash";
 
 /**
  * Strip EXIF data from image while preserving orientation
- * Ensures the image is properly rotated according to EXIF orientation before stripping
+ * Sharp automatically rotates based on EXIF orientation before stripping
+ * @param {Buffer} buffer - Image buffer
+ * @returns {Promise<Buffer>} Cleaned image buffer
  */
 export async function stripExif(buffer) {
   try {
-    const image = sharp(buffer);
-
-    // Get metadata including orientation
-    const metadata = await image.metadata();
-
-    // Sharp automatically rotates based on EXIF orientation, then removes EXIF
-    // when we don't include metadata in output
-    const result = await image
-      .withMetadata(false) // This removes all EXIF/metadata
+    return await sharp(buffer)
+      .withMetadata(false)
       .toBuffer();
-
-    return result;
   } catch (error) {
-    throw new Error(`Failed to strip EXIF: ${error.message}`);
+    throw new Error(`[xImagePipeline] Failed to strip EXIF: ${error.message}`);
   }
 }
 
 /**
  * Get image metadata
+ * @param {Buffer} buffer - Image buffer
+ * @returns {Promise<{width: number, height: number, format: string, colorspace: string, hasAlpha: boolean, density: number}>}
  */
 export async function getImageMetadata(buffer) {
   try {
     const metadata = await sharp(buffer).metadata();
-
     return {
       width: metadata.width,
       height: metadata.height,
@@ -41,56 +35,58 @@ export async function getImageMetadata(buffer) {
       density: metadata.density,
     };
   } catch (error) {
-    throw new Error(`Failed to get image metadata: ${error.message}`);
+    throw new Error(`[xImagePipeline] Failed to get image metadata: ${error.message}`);
   }
 }
 
 /**
  * Compress image to JPEG format for storage
- * Used for storing originals in a space-efficient format
  * @param {Buffer} buffer - Image buffer
- * @param {number} quality - JPEG quality (0-100, default 85)
+ * @param {number} [quality=85] - JPEG quality (0-100)
+ * @returns {Promise<Buffer>}
  */
 export async function compressToJpeg(buffer, quality = 85) {
   try {
-    const compressed = await sharp(buffer)
+    return await sharp(buffer)
       .jpeg({ quality, mozjpeg: true })
       .toBuffer();
-
-    return compressed;
   } catch (error) {
-    throw new Error(`Failed to compress image to JPEG: ${error.message}`);
+    throw new Error(`[xImagePipeline] Failed to compress to JPEG: ${error.message}`);
   }
 }
 
 /**
  * Generate image variants in WebP format
- * Only generates variants where source is larger than target
+ * Only generates variants where source is larger than target.
+ * Expects a pre-cleaned buffer (EXIF already stripped).
+ *
+ * @param {Buffer} buffer - Image buffer (should already be EXIF-stripped)
+ * @param {Object} variantSpecs - { name: { width, height, fit } }
+ * @param {string} sourceType - Source type name (for logging)
+ * @param {number} [quality=85] - WebP quality (0-100)
+ * @returns {Promise<Object<string, Buffer>>} Variant name -> buffer map
  */
-export async function generateVariants(buffer, variantSpecs, sourceType) {
+export async function generateVariants(buffer, variantSpecs, sourceType, quality = 85) {
   try {
-    // First strip EXIF
-    const cleanBuffer = await stripExif(buffer);
-
-    // Get original dimensions
-    const originalMetadata = await getImageMetadata(cleanBuffer);
+    const originalMetadata = await getImageMetadata(buffer);
     const { width: srcWidth, height: srcHeight } = originalMetadata;
 
     const variants = {};
 
-    // Generate each variant
     for (const [variantName, spec] of Object.entries(variantSpecs)) {
       const { width: targetWidth, height: targetHeight, fit } = spec;
 
       // Skip if source is too small
-      if (srcWidth < targetWidth || (targetHeight && srcHeight < targetHeight)) {
+      if (targetWidth && srcWidth < targetWidth) {
+        continue;
+      }
+      if (targetHeight && srcHeight < targetHeight) {
         continue;
       }
 
       try {
-        let sharpInstance = sharp(cleanBuffer);
+        let sharpInstance = sharp(buffer);
 
-        // Apply resize
         if (fit === "cover") {
           sharpInstance = sharpInstance.resize(targetWidth, targetHeight, {
             fit: "cover",
@@ -103,54 +99,55 @@ export async function generateVariants(buffer, variantSpecs, sourceType) {
           });
         }
 
-        // Convert to WebP
         const variantBuffer = await sharpInstance
-          .webp({ quality: 85 })
+          .webp({ quality })
           .toBuffer();
 
         variants[variantName] = variantBuffer;
       } catch (err) {
-        console.error(`Failed to generate variant ${variantName}:`, err.message);
-        // Continue with other variants
+        // Continue with other variants on individual failure
       }
     }
 
     return variants;
   } catch (error) {
-    throw new Error(`Failed to generate variants: ${error.message}`);
+    throw new Error(`[xImagePipeline] Failed to generate variants: ${error.message}`);
   }
 }
 
 /**
  * Generate blurhash for image (used as loading placeholder)
- * Creates a low-quality placeholder for quick loading
+ * @param {Buffer} buffer - Image buffer
+ * @returns {Promise<string>} Blurhash string
  */
 export async function generateBlurhash(buffer) {
   try {
-    // Resize to small thumbnail for blurhash (10x10 is typical)
-    const thumbnail = await sharp(buffer)
+    const { data, info } = await sharp(buffer)
       .resize(10, 10, { fit: "inside" })
+      .ensureAlpha()
       .raw()
       .toBuffer({ resolveWithObject: true });
 
-    const { data, info } = thumbnail;
-    const blurhashValue = encode(
+    return encode(
       new Uint8ClampedArray(data),
       info.width,
       info.height,
-      4, // x components
-      3  // y components
+      4,
+      3
     );
-
-    return blurhashValue;
   } catch (error) {
-    throw new Error(`Failed to generate blurhash: ${error.message}`);
+    throw new Error(`[xImagePipeline] Failed to generate blurhash: ${error.message}`);
   }
 }
 
 /**
  * Calculate optimal dimensions for fit="inside"
  * Maintains aspect ratio while fitting within maxWidth x maxHeight
+ * @param {number} srcWidth
+ * @param {number} srcHeight
+ * @param {number} maxWidth
+ * @param {number} maxHeight
+ * @returns {{ width: number, height: number }}
  */
 export function calculateFitDimensions(srcWidth, srcHeight, maxWidth, maxHeight) {
   const aspectRatio = srcWidth / srcHeight;
@@ -158,10 +155,8 @@ export function calculateFitDimensions(srcWidth, srcHeight, maxWidth, maxHeight)
   let height = maxHeight;
 
   if (aspectRatio > maxWidth / maxHeight) {
-    // Image is wider - fit to width
     height = Math.round(maxWidth / aspectRatio);
   } else {
-    // Image is taller - fit to height
     width = Math.round(maxHeight * aspectRatio);
   }
 
@@ -170,6 +165,9 @@ export function calculateFitDimensions(srcWidth, srcHeight, maxWidth, maxHeight)
 
 /**
  * Get aspect ratio string (e.g., "16:9", "4:3", "1:1")
+ * @param {number} width
+ * @param {number} height
+ * @returns {string}
  */
 export function getAspectRatio(width, height) {
   const gcd = (a, b) => (b === 0 ? a : gcd(b, a % b));
@@ -178,15 +176,21 @@ export function getAspectRatio(width, height) {
 }
 
 /**
- * Validate image buffer
+ * Validate image buffer against constraints
+ * @param {Buffer} buffer - Image buffer
+ * @param {Object} [options]
+ * @param {number} [options.minWidth]
+ * @param {number} [options.maxWidth]
+ * @param {number} [options.minHeight]
+ * @param {number} [options.maxHeight]
+ * @param {string[]} [options.allowedFormats]
+ * @returns {Promise<{ valid: boolean, errors?: string[], metadata: Object|null }>}
  */
 export async function validateImage(buffer, options = {}) {
   try {
     const metadata = await getImageMetadata(buffer);
-
     const errors = [];
 
-    // Check dimensions
     if (options.minWidth && metadata.width < options.minWidth) {
       errors.push(`Image width must be at least ${options.minWidth}px`);
     }
@@ -199,8 +203,6 @@ export async function validateImage(buffer, options = {}) {
     if (options.maxHeight && metadata.height > options.maxHeight) {
       errors.push(`Image height must not exceed ${options.maxHeight}px`);
     }
-
-    // Check format
     if (options.allowedFormats && !options.allowedFormats.includes(metadata.format)) {
       errors.push(`Image format ${metadata.format} is not allowed`);
     }
@@ -220,35 +222,25 @@ export async function validateImage(buffer, options = {}) {
 }
 
 /**
- * Process image with configurable variants and formats
- * Returns all generated variants and metadata
+ * Process image with configurable variants and formats.
+ * Full pipeline: strip EXIF, extract metadata, generate variants, blurhash, optional original.
  *
- * @param {Buffer} buffer - Image buffer
- * @param {string} sourceType - Source type (avatar, background, etc.)
- * @param {Object} config - Configuration object
- * @param {Object} config.sourceTypeConfig - Source type specific config
- * @param {Array<string>} config.sourceTypeConfig.variants - Variant names to generate
- * @param {Array<string>} config.sourceTypeConfig.formats - Formats to generate ['webp', 'avif']
- * @param {number} config.sourceTypeConfig.quality - Quality (0-100)
- * @param {boolean} config.sourceTypeConfig.storeOriginal - Whether to store original
- * @param {Object} config.variantSpecs - Variant dimension specs
- * @returns {Promise<Object>} Processed image data with variants, metadata, blurhash
+ * @param {Buffer} buffer - Raw image buffer
+ * @param {string} sourceType - Source type name
+ * @param {Object} config - { sourceTypeConfig, variantSpecs }
+ * @returns {Promise<Object>} { metadata, blurhash, variants: { webp, avif? }, original? }
  */
 export async function processImage(buffer, sourceType, config) {
   try {
     const sourceTypeConfig = config.sourceTypeConfig;
 
     if (!sourceTypeConfig) {
-      throw new Error(`No configuration found for source type: ${sourceType}`);
+      throw new Error(`[xImagePipeline] No configuration found for source type: ${sourceType}`);
     }
 
-    // Step 1: Strip EXIF
     const cleanBuffer = await stripExif(buffer);
-
-    // Step 2: Get metadata
     const metadata = await getImageMetadata(cleanBuffer);
 
-    // Step 3: Generate variants
     const variantSpecs = {};
     for (const variantName of sourceTypeConfig.variants) {
       if (config.variantSpecs[variantName]) {
@@ -256,12 +248,10 @@ export async function processImage(buffer, sourceType, config) {
       }
     }
 
-    const webpVariants = await generateVariants(cleanBuffer, variantSpecs, sourceType);
-
-    // Step 4: Generate blurhash
+    const quality = sourceTypeConfig.quality || 85;
+    const webpVariants = await generateVariants(cleanBuffer, variantSpecs, sourceType, quality);
     const blurhash = await generateBlurhash(cleanBuffer);
 
-    // Step 5: Prepare result object
     const result = {
       metadata,
       blurhash,
@@ -270,29 +260,25 @@ export async function processImage(buffer, sourceType, config) {
       },
     };
 
-    // Step 6: Handle original (if configured)
     if (sourceTypeConfig.storeOriginal) {
-      const originalCompressed = await compressToJpeg(cleanBuffer, sourceTypeConfig.quality);
+      const originalCompressed = await compressToJpeg(cleanBuffer, quality);
       result.original = {
-        format: 'jpeg',
+        format: "jpeg",
         buffer: originalCompressed,
       };
     }
 
-    // Step 7: Generate AVIF variants if configured (only for small files)
-    if (sourceTypeConfig.formats.includes('avif')) {
+    if (sourceTypeConfig.formats.includes("avif")) {
       const avifVariants = {};
       for (const [variantName, webpBuffer] of Object.entries(webpVariants)) {
         try {
-          // Only generate AVIF if WebP is under 100KB
           if (webpBuffer.length < 100 * 1024) {
             const avifBuffer = await sharp(webpBuffer)
-              .avif({ quality: sourceTypeConfig.quality })
+              .avif({ quality })
               .toBuffer();
             avifVariants[variantName] = avifBuffer;
           }
-        } catch (err) {
-          console.warn(`Failed to generate AVIF for ${variantName}: ${err.message}`);
+        } catch {
           // Continue with WebP only
         }
       }
@@ -303,6 +289,6 @@ export async function processImage(buffer, sourceType, config) {
 
     return result;
   } catch (error) {
-    throw new Error(`Failed to process image: ${error.message}`);
+    throw new Error(`[xImagePipeline] Failed to process image: ${error.message}`);
   }
 }