@everystack/server 0.2.4 → 0.2.6

package/README.md

@@ -156,7 +156,7 @@ interface ImageHandlerConfig {
   bucket: string;          // S3 bucket name
   region?: string;         // AWS region (default: AWS_REGION env)
   pathPrefix?: string;     // URL prefix (default: '/media/')
-  cacheControl?: string;   // Cache-Control header (default: 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5')
+  cacheControl?: string;   // Cache-Control header (default: 'public, max-age=86400, s-maxage=31536000, stale-while-revalidate=60')
   validateKey?: (key: string) => boolean | Promise<boolean>;  // Optional key validator
   s3Cache?: {              // Persist rendered images to S3 (skip Sharp on repeat requests)
     enabled: boolean;
@@ -185,6 +185,20 @@ const deleted = await deleteImageCache('my-bucket', 'uploads/photo.jpg');
 
 Options: `{ region?: string; prefix?: string }` (prefix defaults to `'cache/'`).
 
+### `purgeImage(bucket, key, options?)`
+
+Delete all S3 cached renders and invalidate CloudFront cache for an image. Combines `deleteImageCache` with KVS path invalidation.
+
+```typescript
+import { purgeImage } from '@everystack/server/image';
+
+const { deleted, invalidated } = await purgeImage('my-bucket', 'uploads/photo.jpg', {
+  kvsArn: process.env.KVS_ARN,
+});
+```
+
+Options: `{ region?: string; prefix?: string; kvsArn?: string; pathPrefix?: string }`. KVS invalidation is skipped when `kvsArn` is omitted.
+
 ### `parseParams(query)`
 
 Validates URL query params into transform options:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "publishConfig": {
@@ -65,6 +65,7 @@
     "@everystack/cli": ">=0.1.0",
     "drizzle-orm": "0.41.0",
     "postgres": "3.4.9",
+    "heic-decode": "2.1.0",
     "sharp": "0.34.5",
     "sst": "4.13.1"
   },
@@ -78,6 +79,9 @@
     "@everystack/cli": {
       "optional": true
     },
+    "heic-decode": {
+      "optional": true
+    },
     "sharp": {
       "optional": true
     },

package/src/heic-decode.d.ts

@@ -0,0 +1,9 @@
+declare module 'heic-decode' {
+  interface DecodedImage {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+  }
+  function decode(opts: { buffer: Buffer | ArrayBuffer }): Promise<DecodedImage>;
+  export default decode;
+}

package/src/image.ts

@@ -30,8 +30,8 @@ export interface ImageHandlerConfig {
   region?: string;
   /** URL path prefix to strip (defaults to '/media/') */
   pathPrefix?: string;
-  /** Cache-Control for image responses.
-   *  Default: 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5' */
+  /** Cache-Control for image responses and S3 cached renders.
+   *  Default: 'public, max-age=86400, s-maxage=31536000, stale-while-revalidate=60' */
   cacheControl?: string;
   /**
    * Optional key validator. Called before fetching from S3.
@@ -142,15 +142,17 @@ function isNotFound(error: any): boolean {
 
 export async function processImage(
   data: Buffer,
-  params: TransformParams
+  params: TransformParams,
+  raw?: { width: number; height: number; channels: 1 | 2 | 3 | 4 }
 ): Promise<{ data: Buffer; contentType: string }> {
   // Sharp is provided via Lambda layer
   const sharp = (await import('sharp')).default;
 
-  let pipeline = sharp(data);
+  let pipeline = raw ? sharp(data, { raw }) : sharp(data);
 
   // Auto-orient based on EXIF metadata (fixes rotated portrait thumbnails)
-  pipeline = pipeline.rotate();
+  // Skip for raw pixel input — no EXIF to orient
+  if (!raw) pipeline = pipeline.rotate();
 
   // Resize
   if (params.w || params.h) {
@@ -244,7 +246,7 @@ export function createImageHandler(
       const client = new S3Client({ region });
 
       const cacheHeaders = {
-        'Cache-Control': config.cacheControl ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5',
+        'Cache-Control': config.cacheControl ?? 'public, max-age=86400, s-maxage=31536000, stale-while-revalidate=60',
         'Vary': 'Accept',
       };
 
@@ -346,21 +348,52 @@ export function createImageHandler(
       const hasTransforms = params.w || params.h || params.fit || params.fm || params.q;
 
       // Process with Sharp — catch decode failures (e.g. HEIC without libheif)
-      let processed: { data: Buffer; contentType: string };
+      let processed: { data: Buffer; contentType: string } | undefined;
       try {
         processed = hasTransforms
           ? await processImage(originalData, params)
           : await processImage(originalData, { fm: 'webp', q: 80 });
       } catch (sharpError) {
-        log('error', 'Sharp processing failed', {
-          key, format: detectedFormat, contentType: originalContentType,
-          error: String(sharpError),
-        });
-        return {
-          statusCode: 422,
-          headers: errorHeaders,
-          body: JSON.stringify({ error: 'Unsupported image format' }),
-        };
+        // HEIC fallback: decode via WASM (heic-decode) then re-process with Sharp
+        if (detectedFormat === 'heif') {
+          try {
+            const decode = (await import('heic-decode')).default;
+            const { width, height, data } = await decode({ buffer: originalData });
+            const rawBuffer = Buffer.from(data.buffer);
+            const transformParams = hasTransforms ? params : { fm: 'webp' as const, q: 80 };
+            processed = await processImage(rawBuffer, transformParams, { width, height, channels: 4 });
+          } catch (heicError) {
+            log('warn', 'HEIC decode failed, passing through original', {
+              key, contentType: originalContentType,
+              error: String(heicError),
+            });
+          }
+        }
+
+        if (!processed) {
+          log('warn', 'Sharp decode failed, passing through original', {
+            key, format: detectedFormat, contentType: originalContentType,
+            error: String(sharpError),
+          });
+          // Can't decode — pass through original bytes (better than 422)
+          const MAX_PASSTHROUGH = 4_500_000;
+          if (originalData.length > MAX_PASSTHROUGH) {
+            return {
+              statusCode: 422,
+              headers: errorHeaders,
+              body: JSON.stringify({ error: 'Unsupported image format' }),
+            };
+          }
+          return {
+            statusCode: 200,
+            headers: {
+              'Content-Type': originalContentType || 'application/octet-stream',
+              ...cacheHeaders,
+            },
+            body: originalData.toString('base64'),
+            isBase64Encoded: true,
+          };
+        }
       }
 
       // --- Write rendered image to S3 cache (fire-and-forget) ---
@@ -372,7 +405,7 @@ export function createImageHandler(
               Key: s3CacheKey,
               Body: processed.data,
               ContentType: processed.contentType,
-              CacheControl: 'public, max-age=2592000',
+              CacheControl: cacheHeaders['Cache-Control'],
             })
           )
           .catch((err: unknown) => {
@@ -445,3 +478,42 @@ export async function deleteImageCache(
 
   return deleted;
 }
+
+/**
+ * Purge an image: delete all S3 cached renders and invalidate CloudFront.
+ *
+ * Call this when an original image is deleted or replaced. Combines
+ * `deleteImageCache()` (S3 cleanup) with KVS path invalidation
+ * (CloudFront cache expiry for all variants of the image).
+ *
+ * KVS invalidation is optional — when `kvsArn` is omitted, only S3
+ * cached renders are deleted.
+ */
+export async function purgeImage(
+  bucket: string,
+  key: string,
+  options?: {
+    region?: string;
+    /** S3 cache prefix. Default: 'cache/' */
+    prefix?: string;
+    /** CloudFront KVS ARN. When provided, invalidates CDN cache. */
+    kvsArn?: string;
+    /** URL path prefix for CDN invalidation. Default: '/media/' */
+    pathPrefix?: string;
+  }
+): Promise<{ deleted: number; invalidated: boolean }> {
+  const deleted = await deleteImageCache(bucket, key, {
+    region: options?.region,
+    prefix: options?.prefix,
+  });
+
+  let invalidated = false;
+  if (options?.kvsArn) {
+    const { invalidateKvsPaths } = await import('./kvs.js');
+    const mediaPath = (options.pathPrefix ?? '/media/') + key;
+    await invalidateKvsPaths(options.kvsArn, [mediaPath]);
+    invalidated = true;
+  }
+
+  return { deleted, invalidated };
+}