@xenterprises/fastify-ximagepipeline 1.0.0

package/README.md

@@ -0,0 +1,488 @@
+# xMedia Plugin for Fastify v5
+
+Fastify plugin for handling image uploads with automatic EXIF stripping, content moderation, WebP variant generation, and Cloudflare R2 storage using a job queue pattern.
+
+## Features
+
+✨ **Core Capabilities**
+- 🖼️ **Image Upload** - Multipart file upload with validation
+- 🔍 **EXIF Stripping** - Remove metadata while preserving orientation
+- 🎨 **Variant Generation** - Automatic WebP variants at multiple sizes
+- 📦 **R2 Storage** - Direct integration with Cloudflare R2 (S3-compatible)
+- ⏳ **Job Queue** - Database-backed processing queue with retry logic
+- 🔒 **Content Moderation** - Pluggable moderation API support
+- 🎯 **Focal Points** - Smart cropping hints for UI
+- 📊 **Blurhash** - Loading placeholders for instant UI feedback
+- 🧹 **Cleanup** - Automatic staging cleanup and stale job recovery
+
+## Installation
+
+```bash
+npm install @xenterprises/fastify-xmedia @fastify/multipart
+```
+
+## Setup
+
+### 1. Add Prisma Models
+
+Add these models to your `schema.prisma`:
+
+```prisma
+enum MediaStatus {
+  PENDING
+  PROCESSING
+  COMPLETE
+  REJECTED
+  FAILED
+}
+
+model MediaQueue {
+  id String @id @default(cuid())
+  status MediaStatus @default(PENDING)
+  sourceType String
+  sourceId String
+  stagingKey String
+  originalFilename String
+  mimeType String
+  fileSize Int
+  mediaId String?
+  media Media? @relation(fields: [mediaId], references: [id], onDelete: SetNull)
+  attempts Int @default(0)
+  maxAttempts Int @default(3)
+  errorMsg String?
+  moderationResult String?
+  moderationDetails Json?
+  lockedAt DateTime?
+  lockedBy String?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([status, createdAt])
+  @@index([sourceType, sourceId])
+}
+
+model Media {
+  id String @id @default(cuid())
+  urls Json @default("{}")
+  originalUrl String
+  width Int
+  height Int
+  format String
+  aspectRatio String
+  blurhash String
+  focalPoint Json @default("{\"x\": 0.5, \"y\": 0.5}")
+  sourceType String
+  sourceId String
+  originalFilename String
+  mimeType String
+  fileSize Int
+  exifStripped Boolean @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  queue MediaQueue[]
+
+  @@index([sourceType, sourceId])
+}
+```
+
+### 2. Register Plugin
+
+```javascript
+import Fastify from 'fastify';
+import xMedia from '@xenterprises/fastify-xmedia';
+import multipart from '@fastify/multipart';
+import { PrismaClient } from '@prisma/client';
+
+const fastify = Fastify();
+const prisma = new PrismaClient();
+
+await fastify.register(multipart);
+
+await fastify.register(xMedia, {
+  // R2 Configuration
+  r2: {
+    endpoint: process.env.R2_ENDPOINT,
+    region: 'auto',
+    accessKeyId: process.env.R2_ACCESS_KEY_ID,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
+    bucket: process.env.R2_BUCKET,
+  },
+
+  // Database connection
+  db: prisma,
+
+  // Optional: Content moderation
+  moderation: {
+    provider: 'rekognition', // or 'vision', 'sightengine', etc.
+    apiKey: process.env.MODERATION_API_KEY,
+    // provider-specific options...
+  },
+
+  // Optional: Customize variant specs
+  variants: {
+    xs: { width: 80, height: 80, fit: 'cover' },
+    sm: { width: 200, height: 200, fit: 'cover' },
+    md: { width: 600, height: null, fit: 'inside' },
+    lg: { width: 1200, height: null, fit: 'inside' },
+    xl: { width: 1920, height: null, fit: 'inside' },
+    '2xl': { width: 2560, height: null, fit: 'inside' },
+  },
+
+  // Optional: Worker configuration
+  worker: {
+    enabled: true,
+    pollInterval: 5000,        // 5 seconds
+    maxAttempts: 3,
+    lockTimeout: 300000,       // 5 minutes
+    failOnError: false,
+  },
+
+  // Optional: Storage paths
+  stagingPath: 'staging',
+  mediaPath: 'media',
+  originalsPath: 'originals',
+
+  // Optional: Limits
+  maxFileSize: 50 * 1024 * 1024, // 50MB
+  allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp', 'image/gif'],
+});
+```
+
+## API Endpoints
+
+### Upload Image
+
+```http
+POST /media/upload HTTP/1.1
+
+Content-Type: multipart/form-data; boundary=----WebKitFormBoundary
+
+------WebKitFormBoundary
+Content-Disposition: form-data; name="file"; filename="photo.jpg"
+Content-Type: image/jpeg
+
+[binary image data]
+------WebKitFormBoundary
+Content-Disposition: form-data; name="sourceType"
+
+avatar
+------WebKitFormBoundary
+Content-Disposition: form-data; name="sourceId"
+
+user123
+------WebKitFormBoundary--
+```
+
+**Response:** `202 Accepted`
+```json
+{
+  "jobId": "clh7k9w1j0000nv8zk9k9k9k9",
+  "message": "File uploaded. Processing started.",
+  "statusUrl": "/media/status/clh7k9w1j0000nv8zk9k9k9k9"
+}
+```
+
+### Check Processing Status
+
+```http
+GET /media/status/:jobId HTTP/1.1
+```
+
+**Responses:**
+
+While Processing (202):
+```json
+{
+  "jobId": "clh7k9w1j0000nv8zk9k9k9k9",
+  "status": "PROCESSING",
+  "sourceType": "avatar",
+  "sourceId": "user123",
+  "createdAt": "2024-01-15T10:30:00Z",
+  "updatedAt": "2024-01-15T10:30:02Z"
+}
+```
+
+When Complete (200):
+```json
+{
+  "jobId": "clh7k9w1j0000nv8zk9k9k9k9",
+  "status": "COMPLETE",
+  "sourceType": "avatar",
+  "sourceId": "user123",
+  "media": {
+    "id": "media-1705314600000-abc123",
+    "urls": {
+      "xs": "https://r2.example.com/media/avatar/user123/...-xs.webp",
+      "sm": "https://r2.example.com/media/avatar/user123/...-sm.webp",
+      "md": "https://r2.example.com/media/avatar/user123/...-md.webp"
+    },
+    "originalUrl": "https://r2.example.com/originals/avatar/user123/.../original.jpg",
+    "width": 2000,
+    "height": 2000,
+    "aspectRatio": "1:1",
+    "blurhash": "UeKUpMxua4t757oJodS3_3kCMd9F6p",
+    "focalPoint": { "x": 0.5, "y": 0.5 }
+  }
+}
+```
+
+When Rejected (400):
+```json
+{
+  "jobId": "clh7k9w1j0000nv8zk9k9k9k9",
+  "status": "REJECTED",
+  "reason": "REJECTED",
+  "moderationDetails": {
+    "flags": ["adult", "violence"],
+    "confidence": { "adult": 0.95 }
+  }
+}
+```
+
+When Failed (500):
+```json
+{
+  "jobId": "clh7k9w1j0000nv8zk9k9k9k9",
+  "status": "FAILED",
+  "error": "Failed to download from R2",
+  "attempts": 3
+}
+```
+
+## Source Types & Variant Presets
+
+The plugin comes with predefined source types and their variant presets:
+
+| Source Type | Variants | Use Case |
+|---|---|---|
+| `avatar` | xs, sm | User/band profile pictures |
+| `member_photo` | xs, sm, md | Member directory images |
+| `gallery` | md, lg, xl | Gallery display images |
+| `hero` | lg, xl, 2xl | Hero/banner backgrounds |
+| `content` | md, lg | Article/post images |
+
+Each source type generates only the specified variants. For example, `avatar` uploads will create `xs.webp` and `sm.webp` files.
+
+## Frontend Usage
+
+### React Example
+
+```jsx
+import { useEffect, useState } from 'react';
+
+function AvatarUpload({ userId }) {
+  const [jobId, setJobId] = useState(null);
+  const [status, setStatus] = useState(null);
+  const [loading, setLoading] = useState(false);
+
+  const handleUpload = async (file) => {
+    const formData = new FormData();
+    formData.append('file', file);
+    formData.append('sourceType', 'avatar');
+    formData.append('sourceId', userId);
+
+    const response = await fetch('/media/upload', {
+      method: 'POST',
+      body: formData,
+    });
+
+    const data = await response.json();
+    setJobId(data.jobId);
+  };
+
+  useEffect(() => {
+    if (!jobId) return;
+
+    const checkStatus = async () => {
+      const response = await fetch(`/media/status/${jobId}`);
+      const data = await response.json();
+      setStatus(data);
+
+      if (data.status === 'COMPLETE') {
+        setLoading(false);
+      }
+    };
+
+    const interval = setInterval(checkStatus, 2000);
+    return () => clearInterval(interval);
+  }, [jobId]);
+
+  return (
+    <div>
+      <input type="file" onChange={(e) => handleUpload(e.target.files[0])} />
+      {status?.media && (
+        <img src={status.media.urls.sm} alt="Avatar" />
+      )}
+      {status?.status === 'PROCESSING' && <p>Processing...</p>}
+      {status?.status === 'REJECTED' && <p>Image rejected: {status.reason}</p>}
+    </div>
+  );
+}
+```
+
+### Nuxt Example
+
+```vue
+<template>
+  <div>
+    <input type="file" @change="handleUpload" />
+
+    <div v-if="media">
+      <img :src="media.urls.sm" alt="Avatar" />
+      <div
+        v-if="media.blurhash"
+        :style="{ backgroundColor: blurhashColor }"
+        class="blur-placeholder"
+      />
+    </div>
+
+    <p v-if="status === 'PROCESSING'">Processing...</p>
+    <p v-if="status === 'REJECTED'">Image rejected</p>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const jobId = ref(null);
+const media = ref(null);
+const status = ref(null);
+
+const handleUpload = async (event) => {
+  const file = event.target.files[0];
+  const formData = new FormData();
+  formData.append('file', file);
+  formData.append('sourceType', 'avatar');
+  formData.append('sourceId', 'user123');
+
+  const response = await fetch('/media/upload', {
+    method: 'POST',
+    body: formData,
+  });
+
+  const { jobId: id } = await response.json();
+  jobId.value = id;
+  pollStatus();
+};
+
+const pollStatus = async () => {
+  const response = await fetch(`/media/status/${jobId.value}`);
+  const data = await response.json();
+  status.value = data.status;
+
+  if (data.status === 'COMPLETE') {
+    media.value = data.media;
+  } else if (data.status !== 'PROCESSING') {
+    setTimeout(pollStatus, 2000);
+  }
+};
+</script>
+```
+
+## Processing Pipeline
+
+1. **Upload** - File received at `/media/upload`
+2. **Queue** - Job created in database with `PENDING` status
+3. **Worker Polling** - Worker finds next job and locks it
+4. **Download** - File downloaded from staging bucket
+5. **EXIF Strip** - Metadata removed while preserving orientation
+6. **Moderation** - Content checked (if enabled)
+7. **Variants** - WebP variants generated at specified sizes
+8. **Blurhash** - Loading placeholder generated
+9. **Upload** - Variants and original uploaded to media bucket
+10. **Store** - Media record created with URLs and metadata
+11. **Cleanup** - Staging file deleted
+12. **Complete** - Job status updated to `COMPLETE`
+
+## Configuration
+
+### R2 Setup
+
+1. Create R2 bucket
+2. Generate API token
+3. Set CORS policy on bucket:
+   ```json
+   {
+     "CORSRules": [
+       {
+         "AllowedOrigins": ["https://yoursite.com"],
+         "AllowedMethods": ["GET"],
+         "AllowedHeaders": ["*"],
+         "MaxAgeSeconds": 3600
+       }
+     ]
+   }
+   ```
+
+4. Set lifecycle policy to clean staging:
+   ```
+   Delete objects in /staging/ older than 1 day
+   ```
+
+### Environment Variables
+
+```bash
+# R2
+R2_ENDPOINT=https://[account-id].r2.cloudflarestorage.com
+R2_ACCESS_KEY_ID=...
+R2_SECRET_ACCESS_KEY=...
+R2_BUCKET=my-media-bucket
+
+# Database (Prisma)
+DATABASE_URL=postgresql://...
+
+# Moderation (optional)
+MODERATION_PROVIDER=rekognition
+MODERATION_API_KEY=...
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## Performance Tips
+
+- 🚀 **Direct Upload**: Consider presigned URLs for large files to bypass server bandwidth
+- 🎯 **CDN**: Put R2 behind Cloudflare CDN for caching
+- ⚡ **Worker Pool**: Run multiple worker processes for faster processing
+- 📊 **Monitoring**: Monitor `MediaQueue` table for stuck jobs
+- 🧹 **Cleanup**: Run cleanup tasks regularly to remove orphaned files
+
+## Troubleshooting
+
+### Jobs stuck in PROCESSING
+
+Jobs are automatically recovered if locked > 5 minutes. To manually recover:
+
+```javascript
+import { recoverStaleLocks } from '@xenterprises/fastify-xmedia/workers/processor';
+
+await recoverStaleLocks(prisma, 5 * 60 * 1000);
+```
+
+### Missing variants
+
+Check that sourceType is in `getVariantPresets()`. Custom source types require variant config.
+
+### R2 upload failures
+
+- Verify credentials and bucket name
+- Check CORS policy
+- Ensure endpoint URL is correct
+
+## Future Enhancements
+
+- [ ] Direct browser-to-R2 uploads (presigned URLs)
+- [ ] Video support with thumbnails
+- [ ] Audio waveform generation
+- [ ] Batch uploads
+- [ ] AVIF format support
+- [ ] Face detection for smart cropping
+- [ ] Custom image filters/transforms
+- [ ] Analytics and usage tracking
+
+## License
+
+ISC

package/SCHEMA.prisma

@@ -0,0 +1,113 @@
+// This schema should be added to your main Prisma schema.prisma file
+// It defines the models needed for the xMedia pipeline
+
+enum MediaStatus {
+  PENDING
+  PROCESSING
+  COMPLETE
+  REJECTED
+  FAILED
+}
+
+enum ModerationResult {
+  APPROVED
+  REJECTED
+  FLAGGED
+}
+
+model MediaQueue {
+  id String @id @default(cuid())
+
+  // Job status
+  status MediaStatus @default(PENDING)
+
+  // Source information
+  sourceType String // avatar, gallery, hero, member_photo, content, etc.
+  sourceId String // userId, bandId, etc.
+
+  // File information
+  stagingKey String // Key in R2 staging bucket
+  originalFilename String
+  mimeType String
+  fileSize Int
+
+  // Processing results
+  mediaId String? // FK to Media after processing
+  media Media? @relation(fields: [mediaId], references: [id], onDelete: SetNull)
+
+  // Error tracking
+  attempts Int @default(0)
+  maxAttempts Int @default(3)
+  errorMsg String?
+
+  // Moderation results
+  moderationResult ModerationResult?
+  moderationDetails Json? // Full moderation API response
+
+  // Locking for worker process
+  lockedAt DateTime?
+  lockedBy String? // Worker ID that locked this job
+
+  // Timestamps
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([status, createdAt])
+  @@index([sourceType, sourceId])
+  @@index([lockedAt])
+}
+
+model Media {
+  id String @id @default(cuid())
+
+  // Variant URLs (object mapping variant name to URL)
+  // e.g., { "xs": "https://...", "sm": "https://...", "md": "https://..." }
+  urls Json @default("{}")
+  originalUrl String // URL to full-resolution original
+
+  // Image properties
+  width Int
+  height Int
+  format String // jpeg, png, webp, gif
+  aspectRatio String // e.g., "16:9", "4:3", "1:1"
+
+  // Loading placeholder
+  blurhash String // For instant UI placeholder
+
+  // For smart cropping
+  focalPoint Json @default("{\"x\": 0.5, \"y\": 0.5}") // { x: 0-1, y: 0-1 }
+
+  // Source information (denormalized for queries)
+  sourceType String
+  sourceId String
+
+  // File information
+  originalFilename String
+  mimeType String
+  fileSize Int
+
+  // Metadata
+  exifStripped Boolean @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Relations (optional - add as needed)
+  // User.avatar => Media
+  // Band.avatar => Media
+  // Gallery items, etc.
+
+  queue MediaQueue[]
+
+  @@index([sourceType, sourceId])
+  @@index([createdAt])
+}
+
+// Example: Add to User model
+// avatar Media? @relation(fields: [avatarId], references: [id], onDelete: SetNull)
+// avatarId String?
+
+// Example: Add to Band model
+// avatar Media? @relation(fields: [avatarId], references: [id], onDelete: SetNull)
+// avatarId String?
+// hero Media? @relation(fields: [heroId], references: [id], onDelete: SetNull)
+// heroId String?

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@xenterprises/fastify-ximagepipeline",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Fastify plugin for image uploads with EXIF stripping, moderation, variant generation, and R2 storage with job queue",
+  "main": "src/xImagePipeline.js",
+  "exports": {
+    ".": "./src/xImagePipeline.js",
+    "./image": "./src/utils/image.js",
+    "./s3": "./src/services/s3.js"
+  },
+  "scripts": {
+    "start": "fastify start -l info server/app.js",
+    "dev": "fastify start -w -l info -P server/app.js",
+    "test": "node --test test/xImagePipeline.test.js"
+  },
+  "keywords": [
+    "fastify",
+    "media",
+    "image",
+    "upload",
+    "s3",
+    "r2",
+    "cloudflare",
+    "exif",
+    "variants",
+    "moderation",
+    "sharp",
+    "webp"
+  ],
+  "author": "Tim Mushen",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git@gitlab.com:x-enterprises/fastify-plugins/fastify-x-imagepipeline.git"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/x-enterprises/fastify-plugins/fastify-x-imagepipeline/-/issues"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "blurhash": "^2.0.5",
+    "fastify-plugin": "^5.0.0",
+    "sharp": "^0.33.5"
+  },
+  "devDependencies": {
+    "@fastify/multipart": "^9.0.0",
+    "@types/node": "^22.7.4",
+    "fastify": "^5.1.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  }
+}