@everystack/server 0.2.1 → 0.2.3

package/README.md

@@ -156,14 +156,34 @@ 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')
+  validateKey?: (key: string) => boolean | Promise<boolean>;  // Optional key validator
+  s3Cache?: {              // Persist rendered images to S3 (skip Sharp on repeat requests)
+    enabled: boolean;
+    prefix?: string;       // S3 key prefix (default: 'cache/')
+  };
 }
 ```
 
 URL format: `/media/{key}?w=400&h=300&fit=cover&fm=webp&q=80&dpr=2`
 
 **Behavior:**
-- No transforms → 302 redirect to presigned S3 URL (avoids 6MB Lambda limit)
-- With transforms → fetch from S3, process with Sharp, return with immutable cache headers
+- Fetches original from S3, processes with Sharp, returns with cache headers
+- All images get EXIF auto-rotation and format conversion (default: webp q80)
+- With `s3Cache` enabled: checks S3 for a cached render before processing, writes result to S3 after first render. Subsequent requests from any CloudFront region skip Sharp entirely.
+
+### `deleteImageCache(bucket, key, options?)`
+
+Deletes all cached renders for an image key. Call when the original is deleted or replaced.
+
+```typescript
+import { deleteImageCache } from '@everystack/server/image';
+
+const deleted = await deleteImageCache('my-bucket', 'uploads/photo.jpg');
+// deleted = number of cached objects removed
+```
+
+Options: `{ region?: string; prefix?: string }` (prefix defaults to `'cache/'`).
 
 ### `parseParams(query)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/image.ts

@@ -16,6 +16,13 @@ import type {
 } from 'aws-lambda';
 import { log } from './index.js';
 
+export interface S3CacheConfig {
+  /** Enable S3 origin cache for processed images. Default: false. */
+  enabled: boolean;
+  /** S3 key prefix for cached renders. Default: 'cache/' */
+  prefix?: string;
+}
+
 export interface ImageHandlerConfig {
   /** S3 bucket name for media storage */
   bucket: string;
@@ -32,6 +39,12 @@ export interface ImageHandlerConfig {
    * Use this to verify the key exists in your database or matches an allowed prefix.
    */
   validateKey?: (key: string) => boolean | Promise<boolean>;
+  /**
+   * Persist processed images to S3 so subsequent requests from any
+   * CloudFront region skip Sharp entirely. Cached renders auto-expire
+   * via S3 lifecycle rules (configure on the bucket, not here).
+   */
+  s3Cache?: S3CacheConfig;
 }
 
 export interface TransformParams {
@@ -53,6 +66,33 @@ const FORMAT_CONTENT_TYPES: Record<string, string> = {
 };
 const MAX_DIMENSION = 4096;
 
+/**
+ * Build a deterministic S3 key from parsed params (post-DPR).
+ * Includes the _v epoch when present so cache versioning invalidates correctly.
+ *
+ * Examples:
+ *   computeCacheKey('uploads/photo.jpg', {w:400, fm:'webp'}, 'cache/', '1778646364')
+ *   → 'cache/uploads/photo.jpg/v1778646364/w400_webp_q80.webp'
+ */
+export function computeCacheKey(
+  key: string,
+  params: TransformParams,
+  prefix: string,
+  version?: string
+): string {
+  const segments: string[] = [];
+  if (params.w) segments.push(`w${params.w}`);
+  if (params.h) segments.push(`h${params.h}`);
+  if (params.fit) segments.push(params.fit);
+  const format = params.fm || 'webp';
+  segments.push(format);
+  segments.push(`q${params.q || 80}`);
+
+  const variant = segments.join('_');
+  const versionSegment = version ? `v${version}/` : '';
+  return `${prefix}${key}/${versionSegment}${variant}.${format}`;
+}
+
 export function parseParams(query: Record<string, string | undefined>): TransformParams {
   const params: TransformParams = {};
 
@@ -64,8 +104,11 @@ export function parseParams(query: Record<string, string | undefined>): Transfor
     const h = parseInt(query.h, 10);
     if (h > 0 && h <= MAX_DIMENSION) params.h = h;
   }
-  if (query.fit && VALID_FITS.includes(query.fit as any)) {
-    params.fit = query.fit as TransformParams['fit'];
+  if (query.fit) {
+    const fit = query.fit === 'crop' ? 'cover' : query.fit;
+    if (VALID_FITS.includes(fit as any)) {
+      params.fit = fit as TransformParams['fit'];
+    }
   }
   if (query.fm && VALID_FORMATS.includes(query.fm as any)) {
     params.fm = query.fm as TransformParams['fm'];
@@ -111,11 +154,12 @@ export async function processImage(
 
   // Resize
   if (params.w || params.h) {
+    const fit = params.fit || 'cover';
     pipeline = pipeline.resize({
       width: params.w,
       height: params.h,
-      fit: params.fit || 'cover',
-      withoutEnlargement: true,
+      fit,
+      withoutEnlargement: fit !== 'cover' && fit !== 'fill',
     });
   }
 
@@ -186,13 +230,49 @@ export function createImageHandler(
         }
       }
 
-      const params = parseParams(event.queryStringParameters || {});
+      const queryParams = event.queryStringParameters || {};
+      const params = parseParams(queryParams);
 
-      const { S3Client, GetObjectCommand } = await import('@aws-sdk/client-s3');
+      const { S3Client, GetObjectCommand, PutObjectCommand } = await import('@aws-sdk/client-s3');
       const client = new S3Client({ region });
 
-      // Fetch original from S3 for processing
+      const cacheHeaders = {
+        'Cache-Control': config.cacheControl ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5',
+        'Vary': 'Accept',
+      };
+
+      // --- S3 origin cache: check for existing render ---
+      const useCache = config.s3Cache?.enabled === true;
+      const cachePrefix = config.s3Cache?.prefix ?? 'cache/';
+      let s3CacheKey: string | undefined;
+
+      if (useCache) {
+        s3CacheKey = computeCacheKey(key, params, cachePrefix, queryParams._v);
+        try {
+          const cached = await client.send(
+            new GetObjectCommand({ Bucket: bucket, Key: s3CacheKey })
+          );
+          if (cached.Body) {
+            const bytes = await cached.Body.transformToByteArray();
+            return {
+              statusCode: 200,
+              headers: {
+                'Content-Type': cached.ContentType || FORMAT_CONTENT_TYPES[params.fm || 'webp'],
+                ...cacheHeaders,
+              },
+              body: Buffer.from(bytes).toString('base64'),
+              isBase64Encoded: true,
+            };
+          }
+        } catch (error: any) {
+          // Cache miss — fall through to process
+          if (!isNotFound(error)) throw error;
+        }
+      }
+
+      // --- Fetch original from S3 for processing ---
       let originalData: Buffer;
+      let originalContentType: string | undefined;
       try {
         const result = await client.send(
           new GetObjectCommand({ Bucket: bucket, Key: key })
@@ -204,6 +284,7 @@ export function createImageHandler(
             body: JSON.stringify({ error: 'Image not found' }),
           };
         }
+        originalContentType = result.ContentType || undefined;
         const bytes = await result.Body.transformToByteArray();
         originalData = Buffer.from(bytes);
       } catch (error: any) {
@@ -217,15 +298,51 @@ export function createImageHandler(
         throw error;
       }
 
+      // Pass through non-image files (fonts, CSS, etc.) without processing
+      const isImage = originalContentType?.startsWith('image/') ??
+        /\.(jpe?g|png|webp|avif|gif|tiff?|svg)$/i.test(key);
+      if (!isImage) {
+        return {
+          statusCode: 200,
+          headers: {
+            'Content-Type': originalContentType || 'application/octet-stream',
+            ...cacheHeaders,
+          },
+          body: originalData.toString('base64'),
+          isBase64Encoded: true,
+        };
+      }
+
+      // No transform params — serve original image as-is (EXIF-corrected webp)
+      const hasTransforms = params.w || params.h || params.fit || params.fm || params.q;
+
       // Process with Sharp
-      const processed = await processImage(originalData, params);
+      const processed = hasTransforms
+        ? await processImage(originalData, params)
+        : await processImage(originalData, { fm: 'webp', q: 80 });
+
+      // --- Write rendered image to S3 cache (fire-and-forget) ---
+      if (useCache && s3CacheKey) {
+        client
+          .send(
+            new PutObjectCommand({
+              Bucket: bucket,
+              Key: s3CacheKey,
+              Body: processed.data,
+              ContentType: processed.contentType,
+              CacheControl: 'public, max-age=2592000',
+            })
+          )
+          .catch((err: unknown) => {
+            log('warn', 'S3 cache write failed', { key: s3CacheKey, error: String(err) });
+          });
+      }
 
       return {
         statusCode: 200,
         headers: {
           'Content-Type': processed.contentType,
-          'Cache-Control': config.cacheControl ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5',
-          'Vary': 'Accept',
+          ...cacheHeaders,
         },
         body: processed.data.toString('base64'),
         isBase64Encoded: true,
@@ -240,3 +357,49 @@ export function createImageHandler(
     }
   };
 }
+
+/**
+ * Delete all cached renders for an image key.
+ * Call this when the original image is deleted or replaced.
+ *
+ * Returns the number of cached objects deleted.
+ */
+export async function deleteImageCache(
+  bucket: string,
+  key: string,
+  options?: { region?: string; prefix?: string }
+): Promise<number> {
+  const { S3Client, ListObjectsV2Command, DeleteObjectsCommand } = await import('@aws-sdk/client-s3');
+  const client = new S3Client({ region: options?.region || process.env.AWS_REGION });
+  const cachePrefix = (options?.prefix ?? 'cache/') + key + '/';
+
+  let deleted = 0;
+  let continuationToken: string | undefined;
+
+  do {
+    const list = await client.send(
+      new ListObjectsV2Command({
+        Bucket: bucket,
+        Prefix: cachePrefix,
+        ContinuationToken: continuationToken,
+      })
+    );
+
+    if (list.Contents?.length) {
+      await client.send(
+        new DeleteObjectsCommand({
+          Bucket: bucket,
+          Delete: {
+            Objects: list.Contents.map((obj) => ({ Key: obj.Key })),
+            Quiet: true,
+          },
+        })
+      );
+      deleted += list.Contents.length;
+    }
+
+    continuationToken = list.NextContinuationToken;
+  } while (continuationToken);
+
+  return deleted;
+}