@xenterprises/fastify-ximagepipeline 1.0.0

package/src/routes/status.js

@@ -0,0 +1,88 @@
+// src/routes/status.js
+
+/**
+ * Register status routes
+ * GET /image-pipeline/status/:jobId - Get processing job status
+ */
+export async function setupStatusRoute(fastify, context) {
+  fastify.get("/image-pipeline/status/:jobId", async (request, reply) => {
+    try {
+      const { jobId } = request.params;
+
+      if (!jobId) {
+        return reply.status(400).send({
+          error: "jobId parameter required",
+        });
+      }
+
+      // Fetch job from database
+      const job = await context.db.mediaQueue.findUnique({
+        where: { id: jobId },
+        include: {
+          media: true,
+        },
+      });
+
+      if (!job) {
+        return reply.status(404).send({
+          error: "Job not found",
+        });
+      }
+
+      // Build response based on job status
+      const response = {
+        jobId: job.id,
+        status: job.status,
+        sourceType: job.sourceType,
+        sourceId: job.sourceId,
+        createdAt: job.createdAt,
+        updatedAt: job.updatedAt,
+      };
+
+      // Add processing details if available
+      if (job.status === "COMPLETE" && job.media) {
+        response.media = {
+          id: job.media.id,
+          urls: job.media.urls,
+          originalUrl: job.media.originalUrl,
+          width: job.media.width,
+          height: job.media.height,
+          aspectRatio: job.media.aspectRatio,
+          blurhash: job.media.blurhash,
+          focalPoint: job.media.focalPoint,
+        };
+      }
+
+      if (job.status === "REJECTED") {
+        response.reason = job.moderationResult || "Unknown";
+        if (job.moderationDetails) {
+          response.moderationDetails = job.moderationDetails;
+        }
+      }
+
+      if (job.status === "FAILED") {
+        response.error = job.errorMsg;
+        response.attempts = job.attempts;
+      }
+
+      // 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
+      } else if (job.status === "REJECTED") {
+        statusCode = 400; // Bad request (content rejected)
+      } else if (job.status === "FAILED") {
+        statusCode = 500; // Server error
+      }
+
+      return reply.status(statusCode).send(response);
+    } catch (error) {
+      console.error("Status check error:", error);
+      return reply.status(500).send({
+        error: "Failed to check job status",
+      });
+    }
+  });
+}

package/src/routes/upload.js

@@ -0,0 +1,132 @@
+// src/routes/upload.js
+import { uploadToS3, getPublicUrl } from "../services/s3.js";
+import { getVariantPresets } from "../xImagePipeline.js";
+
+/**
+ * Register upload routes
+ * POST /image-pipeline/upload - Upload image file and create processing job
+ */
+export async function setupUploadRoute(fastify, context) {
+  fastify.post("/image-pipeline/upload", async (request, reply) => {
+    try {
+      const data = await request.file();
+
+      if (!data) {
+        return reply.status(400).send({
+          error: "No file provided",
+        });
+      }
+
+      const {
+        file,
+        filename,
+        mimetype,
+        fields,
+      } = data;
+
+      // Validate file type
+      if (!context.allowedMimeTypes.includes(mimetype)) {
+        return reply.status(400).send({
+          error: `File type ${mimetype} not allowed. Allowed types: ${context.allowedMimeTypes.join(", ")}`,
+        });
+      }
+
+      // Get source information from request
+      const sourceType = fields.sourceType?.value;
+      const sourceId = fields.sourceId?.value;
+
+      if (!sourceType || !sourceId) {
+        return reply.status(400).send({
+          error: "sourceType and sourceId are required",
+        });
+      }
+
+      // Validate sourceType is in variant presets
+      const presets = getVariantPresets();
+      if (!presets[sourceType]) {
+        return reply.status(400).send({
+          error: `Unknown sourceType: ${sourceType}. Allowed types: ${Object.keys(presets).join(", ")}`,
+        });
+      }
+
+      // Read file buffer
+      const buffer = await file.toBuffer();
+
+      // Validate file size
+      if (buffer.length > context.maxFileSize) {
+        return reply.status(413).send({
+          error: `File too large. Maximum size: ${context.maxFileSize / 1024 / 1024}MB`,
+        });
+      }
+
+      // Generate unique staging key
+      const timestamp = Date.now();
+      const randomId = Math.random().toString(36).substring(7);
+      const stagingKey = `${context.stagingPath}/${sourceType}/${sourceId}/${timestamp}-${randomId}`;
+
+      // Upload to R2 staging bucket
+      try {
+        await uploadToS3(context.s3Client, context.r2Config.bucket, stagingKey, buffer, {
+          contentType: mimetype,
+          metadata: {
+            sourceType,
+            sourceId,
+            originalFilename: filename,
+          },
+        });
+      } catch (err) {
+        console.error("R2 upload failed:", err.message);
+        return reply.status(500).send({
+          error: "Failed to upload file to storage",
+        });
+      }
+
+      // Create processing job in database
+      let jobId;
+      try {
+        const job = await context.db.mediaQueue.create({
+          data: {
+            sourceType,
+            sourceId,
+            stagingKey,
+            originalFilename: filename,
+            mimeType: mimetype,
+            fileSize: buffer.length,
+            status: "PENDING",
+          },
+        });
+
+        jobId = job.id;
+      } catch (err) {
+        console.error("Database create failed:", err.message);
+        // Try to clean up uploaded file
+        try {
+          await deleteFromS3(context.s3Client, context.r2Config.bucket, stagingKey);
+        } catch {
+          // Ignore cleanup errors
+        }
+
+        return reply.status(500).send({
+          error: "Failed to create processing job",
+        });
+      }
+
+      // Return 202 Accepted with job ID
+      return reply.status(202).send({
+        jobId,
+        message: "File uploaded. Processing started.",
+        statusUrl: `/image-pipeline/status/${jobId}`,
+      });
+    } catch (error) {
+      console.error("Upload error:", error);
+      return reply.status(500).send({
+        error: "Upload failed",
+      });
+    }
+  });
+}
+
+/**
+ * Helper function to delete from S3 (imported from service)
+ */
+import { deleteFromS3 } from "../services/s3.js";

package/src/services/s3.js

@@ -0,0 +1,154 @@
+// src/services/s3.js
+import { S3Client, PutObjectCommand, DeleteObjectCommand, GetObjectCommand, ListObjectsV2Command } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+
+/**
+ * Initialize S3 client for Cloudflare R2 or AWS S3
+ * R2 is S3-compatible with a different endpoint
+ */
+export function initializeS3Client(config) {
+  if (!config.endpoint || !config.accessKeyId || !config.secretAccessKey || !config.bucket) {
+    throw new Error("R2 configuration must include: endpoint, accessKeyId, secretAccessKey, bucket");
+  }
+
+  return new S3Client({
+    region: config.region || "auto", // R2 uses "auto"
+    endpoint: config.endpoint,
+    credentials: {
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+    },
+  });
+}
+
+/**
+ * Upload buffer to S3/R2
+ */
+export async function uploadToS3(s3Client, bucket, key, buffer, options = {}) {
+  const command = new PutObjectCommand({
+    Bucket: bucket,
+    Key: key,
+    Body: buffer,
+    ContentType: options.contentType || "application/octet-stream",
+    Metadata: options.metadata || {},
+    CacheControl: options.cacheControl || "max-age=31536000", // 1 year for immutable content
+  });
+
+  try {
+    const response = await s3Client.send(command);
+    return {
+      key,
+      etag: response.ETag,
+      versionId: response.VersionId,
+    };
+  } catch (error) {
+    throw new Error(`Failed to upload to R2: ${error.message}`);
+  }
+}
+
+/**
+ * Download buffer from S3/R2
+ */
+export async function downloadFromS3(s3Client, bucket, key) {
+  const command = new GetObjectCommand({
+    Bucket: bucket,
+    Key: key,
+  });
+
+  try {
+    const response = await s3Client.send(command);
+    return response.Body.transformToByteArray();
+  } catch (error) {
+    throw new Error(`Failed to download from R2: ${error.message}`);
+  }
+}
+
+/**
+ * Delete object from S3/R2
+ */
+export async function deleteFromS3(s3Client, bucket, key) {
+  const command = new DeleteObjectCommand({
+    Bucket: bucket,
+    Key: key,
+  });
+
+  try {
+    await s3Client.send(command);
+    return true;
+  } catch (error) {
+    throw new Error(`Failed to delete from R2: ${error.message}`);
+  }
+}
+
+/**
+ * List objects with prefix (for batch operations)
+ */
+export async function listFromS3(s3Client, bucket, prefix) {
+  const command = new ListObjectsV2Command({
+    Bucket: bucket,
+    Prefix: prefix,
+  });
+
+  try {
+    const response = await s3Client.send(command);
+    return response.Contents || [];
+  } catch (error) {
+    throw new Error(`Failed to list from R2: ${error.message}`);
+  }
+}
+
+/**
+ * Get signed URL for S3 object (for private/protected content)
+ */
+export async function getSignedUrlForS3(s3Client, bucket, key, expiresIn = 3600) {
+  const command = new GetObjectCommand({
+    Bucket: bucket,
+    Key: key,
+  });
+
+  try {
+    return await getSignedUrl(s3Client, command, { expiresIn });
+  } catch (error) {
+    throw new Error(`Failed to generate signed URL: ${error.message}`);
+  }
+}
+
+/**
+ * Generate public URL for R2 object
+ * Assumes bucket is publicly accessible for media/originals paths
+ */
+export function getPublicUrl(r2Config, key) {
+  // Remove trailing slash from endpoint if present
+  const endpoint = r2Config.endpoint.endsWith("/")
+    ? r2Config.endpoint.slice(0, -1)
+    : r2Config.endpoint;
+
+  return `${endpoint}/${r2Config.bucket}/${key}`;
+}
+
+/**
+ * Batch delete objects with prefix
+ */
+export async function batchDeleteFromS3(s3Client, bucket, prefix) {
+  try {
+    const objects = await listFromS3(s3Client, bucket, prefix);
+
+    if (objects.length === 0) {
+      return { deleted: 0 };
+    }
+
+    // Delete up to 1000 at a time (S3 batch limit)
+    let deleted = 0;
+    for (let i = 0; i < objects.length; i += 1000) {
+      const batch = objects.slice(i, i + 1000);
+      await Promise.all(
+        batch.map((obj) => deleteFromS3(s3Client, bucket, obj.Key))
+      );
+      deleted += batch.length;
+    }
+
+    return { deleted };
+  } catch (error) {
+    throw new Error(`Failed to batch delete from R2: ${error.message}`);
+  }
+}

package/src/utils/image.js

@@ -0,0 +1,308 @@
+// src/utils/image.js
+import sharp from "sharp";
+import { encode } from "blurhash";
+
+/**
+ * Strip EXIF data from image while preserving orientation
+ * Ensures the image is properly rotated according to EXIF orientation before stripping
+ */
+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
+      .toBuffer();
+
+    return result;
+  } catch (error) {
+    throw new Error(`Failed to strip EXIF: ${error.message}`);
+  }
+}
+
+/**
+ * Get image metadata
+ */
+export async function getImageMetadata(buffer) {
+  try {
+    const metadata = await sharp(buffer).metadata();
+
+    return {
+      width: metadata.width,
+      height: metadata.height,
+      format: metadata.format,
+      colorspace: metadata.space,
+      hasAlpha: metadata.hasAlpha,
+      density: metadata.density,
+    };
+  } catch (error) {
+    throw new Error(`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)
+ */
+export async function compressToJpeg(buffer, quality = 85) {
+  try {
+    const compressed = await sharp(buffer)
+      .jpeg({ quality, mozjpeg: true })
+      .toBuffer();
+
+    return compressed;
+  } catch (error) {
+    throw new Error(`Failed to compress image to JPEG: ${error.message}`);
+  }
+}
+
+/**
+ * Generate image variants in WebP format
+ * Only generates variants where source is larger than target
+ */
+export async function generateVariants(buffer, variantSpecs, sourceType) {
+  try {
+    // First strip EXIF
+    const cleanBuffer = await stripExif(buffer);
+
+    // Get original dimensions
+    const originalMetadata = await getImageMetadata(cleanBuffer);
+    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)) {
+        continue;
+      }
+
+      try {
+        let sharpInstance = sharp(cleanBuffer);
+
+        // Apply resize
+        if (fit === "cover") {
+          sharpInstance = sharpInstance.resize(targetWidth, targetHeight, {
+            fit: "cover",
+            position: "center",
+          });
+        } else if (fit === "inside") {
+          sharpInstance = sharpInstance.resize(targetWidth, targetHeight, {
+            fit: "inside",
+            withoutEnlargement: true,
+          });
+        }
+
+        // Convert to WebP
+        const variantBuffer = await sharpInstance
+          .webp({ quality: 85 })
+          .toBuffer();
+
+        variants[variantName] = variantBuffer;
+      } catch (err) {
+        console.error(`Failed to generate variant ${variantName}:`, err.message);
+        // Continue with other variants
+      }
+    }
+
+    return variants;
+  } catch (error) {
+    throw new Error(`Failed to generate variants: ${error.message}`);
+  }
+}
+
+/**
+ * Generate blurhash for image (used as loading placeholder)
+ * Creates a low-quality placeholder for quick loading
+ */
+export async function generateBlurhash(buffer) {
+  try {
+    // Resize to small thumbnail for blurhash (10x10 is typical)
+    const thumbnail = await sharp(buffer)
+      .resize(10, 10, { fit: "inside" })
+      .raw()
+      .toBuffer({ resolveWithObject: true });
+
+    const { data, info } = thumbnail;
+    const blurhashValue = encode(
+      new Uint8ClampedArray(data),
+      info.width,
+      info.height,
+      4, // x components
+      3  // y components
+    );
+
+    return blurhashValue;
+  } catch (error) {
+    throw new Error(`Failed to generate blurhash: ${error.message}`);
+  }
+}
+
+/**
+ * Calculate optimal dimensions for fit="inside"
+ * Maintains aspect ratio while fitting within maxWidth x maxHeight
+ */
+export function calculateFitDimensions(srcWidth, srcHeight, maxWidth, maxHeight) {
+  const aspectRatio = srcWidth / srcHeight;
+  let width = maxWidth;
+  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);
+  }
+
+  return { width, height };
+}
+
+/**
+ * Get aspect ratio string (e.g., "16:9", "4:3", "1:1")
+ */
+export function getAspectRatio(width, height) {
+  const gcd = (a, b) => (b === 0 ? a : gcd(b, a % b));
+  const divisor = gcd(width, height);
+  return `${width / divisor}:${height / divisor}`;
+}
+
+/**
+ * Validate image buffer
+ */
+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`);
+    }
+    if (options.maxWidth && metadata.width > options.maxWidth) {
+      errors.push(`Image width must not exceed ${options.maxWidth}px`);
+    }
+    if (options.minHeight && metadata.height < options.minHeight) {
+      errors.push(`Image height must be at least ${options.minHeight}px`);
+    }
+    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`);
+    }
+
+    if (errors.length > 0) {
+      return { valid: false, errors, metadata };
+    }
+
+    return { valid: true, metadata };
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [error.message],
+      metadata: null,
+    };
+  }
+}
+
+/**
+ * Process image with configurable variants and formats
+ * Returns all generated variants and metadata
+ *
+ * @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
+ */
+export async function processImage(buffer, sourceType, config) {
+  try {
+    const sourceTypeConfig = config.sourceTypeConfig;
+
+    if (!sourceTypeConfig) {
+      throw new Error(`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]) {
+        variantSpecs[variantName] = config.variantSpecs[variantName];
+      }
+    }
+
+    const webpVariants = await generateVariants(cleanBuffer, variantSpecs, sourceType);
+
+    // Step 4: Generate blurhash
+    const blurhash = await generateBlurhash(cleanBuffer);
+
+    // Step 5: Prepare result object
+    const result = {
+      metadata,
+      blurhash,
+      variants: {
+        webp: webpVariants,
+      },
+    };
+
+    // Step 6: Handle original (if configured)
+    if (sourceTypeConfig.storeOriginal) {
+      const originalCompressed = await compressToJpeg(cleanBuffer, sourceTypeConfig.quality);
+      result.original = {
+        format: 'jpeg',
+        buffer: originalCompressed,
+      };
+    }
+
+    // Step 7: Generate AVIF variants if configured (only for small files)
+    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 })
+              .toBuffer();
+            avifVariants[variantName] = avifBuffer;
+          }
+        } catch (err) {
+          console.warn(`Failed to generate AVIF for ${variantName}: ${err.message}`);
+          // Continue with WebP only
+        }
+      }
+      if (Object.keys(avifVariants).length > 0) {
+        result.variants.avif = avifVariants;
+      }
+    }
+
+    return result;
+  } catch (error) {
+    throw new Error(`Failed to process image: ${error.message}`);
+  }
+}