@everystack/server 0.2.1 → 0.2.2

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.2",
   "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 = {};
 
@@ -186,12 +226,47 @@ 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;
       try {
         const result = await client.send(
@@ -220,12 +295,28 @@ export function createImageHandler(
       // Process with Sharp
       const processed = await processImage(originalData, params);
 
+      // --- 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 +331,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;
+}