@everystack/server 0.2.15 → 0.2.16

package/README.md

@@ -163,6 +163,7 @@ interface ImageHandlerConfig {
     enabled: boolean;
     prefix?: string;       // S3 key prefix (default: 'cache/')
   };
+  observability?: boolean; // Emit cache-state + timing headers (default: true)
 }
 ```
 
@@ -173,6 +174,36 @@ URL format: `/media/{key}?w=400&h=300&fit=cover&fm=webp&q=80&dpr=2`
 - 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.
 
+#### Observability headers
+
+When `observability` is enabled (default), image responses carry additive,
+non-sensitive headers that double as production render-time monitoring. They do
+not change `Cache-Control`, `Vary`, status, or body.
+
+| Header           | Set on            | Meaning                                          |
+| ---------------- | ----------------- | ------------------------------------------------ |
+| `x-image-cache`  | both image paths  | `hit` = served from S3 render cache (no Sharp); `render` = freshly rendered |
+| `x-render-ms`    | render path only  | ms spent in Sharp                                |
+| `x-image-ms`     | both image paths  | total handler wall time (entry → response)       |
+| `x-fetch-ms`     | both image paths  | ms to GET the original/cached object from S3     |
+| `Server-Timing`  | both image paths  | devtools mirror: `cache;desc=…, s3;dur=…, render;dur=…, total;dur=…` |
+
+**Telling the three pipeline states apart** — CloudFront edge hit vs. S3
+render-cache hit vs. fresh render. Read CloudFront's `x-cache` **first**:
+
+| `x-cache` (CloudFront) | `x-image-cache` (Lambda) | meaning                              |
+| ---------------------- | ------------------------ | ------------------------------------ |
+| `Hit from cloudfront`  | (ignore — stale)         | EDGE HIT, Lambda not invoked         |
+| `Miss from cloudfront` | `hit`                    | S3 RENDER-CACHE HIT, no Sharp        |
+| `Miss from cloudfront` | `render`                 | FRESH RENDER (`x-render-ms` = Sharp time) |
+
+> **Caveat:** CloudFront caches the response *including* these headers and
+> replays them on edge hits, so on an edge hit `x-image-cache` reflects the
+> *original* render, not this request. The `x-image-*` headers are authoritative
+> only when `x-cache` is a `Miss`. Always read `x-cache` first.
+
+Set `observability: false` to suppress all of the above.
+
 ### `deleteImageCache(bucket, key, options?)`
 
 Deletes all cached renders for an image key. Call when the original is deleted or replaced.

package/package.json

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

package/src/image.ts

@@ -45,6 +45,29 @@ export interface ImageHandlerConfig {
    * via S3 lifecycle rules (configure on the bucket, not here).
    */
   s3Cache?: S3CacheConfig;
+  /**
+   * Emit additive cache-state + timing headers on image responses
+   * (`x-image-cache`, `x-render-ms`, `x-image-ms`, `x-fetch-ms`,
+   * `Server-Timing`). Default: true.
+   *
+   * These headers are non-sensitive (cache state + timings) and double
+   * as production render-time monitoring, so default-on is intended.
+   *
+   * CONSUMER TRUTH TABLE — three pipeline states, read x-cache FIRST:
+   *
+   *   x-cache (CloudFront) | x-image-cache (Lambda) | meaning
+   *   ---------------------|------------------------|----------------------------
+   *   Hit from cloudfront  | (ignore — stale)       | EDGE HIT, Lambda not invoked
+   *   Miss from cloudfront | hit                    | S3 RENDER-CACHE HIT, no Sharp
+   *   Miss from cloudfront | render                 | FRESH RENDER (x-render-ms = Sharp time)
+   *
+   * CRITICAL CAVEAT: CloudFront caches the response INCLUDING these
+   * headers and replays them on edge hits, so on an edge hit
+   * `x-image-cache` reflects the ORIGINAL render, not this request.
+   * Consumers MUST read CloudFront's `x-cache` first — `x-image-*` are
+   * authoritative only when `x-cache` is a Miss.
+   */
+  observability?: boolean;
 }
 
 export interface TransformParams {
@@ -196,8 +219,36 @@ export function createImageHandler(
 ): (event: APIGatewayProxyEventV2) => Promise<APIGatewayProxyStructuredResultV2> {
   const { bucket, pathPrefix = '/media/', validateKey } = config;
   const region = config.region || process.env.AWS_REGION;
+  const observability = config.observability !== false;
+
+  /**
+   * Build additive cache-state + timing headers. Returns {} when
+   * observability is disabled so responses are byte-identical to before.
+   */
+  function timingHeaders(opts: {
+    cache?: 'hit' | 'render';
+    fetchMs?: number;
+    renderMs?: number;
+    totalMs: number;
+  }): Record<string, string> {
+    if (!observability) return {};
+    const headers: Record<string, string> = { 'x-image-ms': String(opts.totalMs) };
+    if (opts.cache) headers['x-image-cache'] = opts.cache;
+    if (opts.fetchMs !== undefined) headers['x-fetch-ms'] = String(opts.fetchMs);
+    if (opts.renderMs !== undefined) headers['x-render-ms'] = String(opts.renderMs);
+
+    // Server-Timing mirror — nice for browser devtools.
+    const timings: string[] = [];
+    if (opts.cache) timings.push(`cache;desc=${opts.cache}`);
+    if (opts.fetchMs !== undefined) timings.push(`s3;dur=${opts.fetchMs}`);
+    if (opts.renderMs !== undefined) timings.push(`render;dur=${opts.renderMs}`);
+    timings.push(`total;dur=${opts.totalMs}`);
+    headers['Server-Timing'] = timings.join(', ');
+    return headers;
+  }
 
   return async (event: APIGatewayProxyEventV2): Promise<APIGatewayProxyStructuredResultV2> => {
+    const t0 = Date.now();
     try {
       // Extract key from path: /media/uploads/abc.jpg → uploads/abc.jpg
       const path = event.rawPath;
@@ -258,16 +309,20 @@ export function createImageHandler(
       if (useCache) {
         s3CacheKey = computeCacheKey(key, params, cachePrefix, queryParams._v);
         try {
+          const fetchStart = Date.now();
           const cached = await client.send(
             new GetObjectCommand({ Bucket: bucket, Key: s3CacheKey })
           );
           if (cached.Body) {
             const bytes = await cached.Body.transformToByteArray();
+            const fetchMs = Date.now() - fetchStart;
             return {
               statusCode: 200,
               headers: {
                 'Content-Type': cached.ContentType || FORMAT_CONTENT_TYPES[params.fm || 'webp'],
                 ...cacheHeaders,
+                // S3 render-cache hit — no Sharp ran. See truth table on ImageHandlerConfig.observability.
+                ...timingHeaders({ cache: 'hit', fetchMs, totalMs: Date.now() - t0 }),
               },
               body: Buffer.from(bytes).toString('base64'),
               isBase64Encoded: true,
@@ -282,7 +337,9 @@ export function createImageHandler(
       // --- Fetch original from S3 for processing ---
       let originalData: Buffer;
       let originalContentType: string | undefined;
+      let fetchMs: number | undefined;
       try {
+        const fetchStart = Date.now();
         const result = await client.send(
           new GetObjectCommand({ Bucket: bucket, Key: key })
         );
@@ -296,6 +353,7 @@ export function createImageHandler(
         originalContentType = result.ContentType || undefined;
         const bytes = await result.Body.transformToByteArray();
         originalData = Buffer.from(bytes);
+        fetchMs = Date.now() - fetchStart;
       } catch (error: any) {
         if (isNotFound(error)) {
           return {
@@ -338,6 +396,7 @@ export function createImageHandler(
           headers: {
             'Content-Type': originalContentType || 'application/octet-stream',
             ...cacheHeaders,
+            ...timingHeaders({ fetchMs, totalMs: Date.now() - t0 }),
           },
           body: originalData.toString('base64'),
           isBase64Encoded: true,
@@ -348,7 +407,9 @@ 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)
+      // Time spent here is the Sharp render cost reported as x-render-ms.
       let processed: { data: Buffer; contentType: string } | undefined;
+      const renderStart = Date.now();
       try {
         processed = hasTransforms
           ? await processImage(originalData, params)
@@ -389,6 +450,7 @@ export function createImageHandler(
             headers: {
               'Content-Type': originalContentType || 'application/octet-stream',
               ...cacheHeaders,
+              ...timingHeaders({ fetchMs, totalMs: Date.now() - t0 }),
             },
             body: originalData.toString('base64'),
             isBase64Encoded: true,
@@ -396,6 +458,8 @@ export function createImageHandler(
         }
       }
 
+      const renderMs = Date.now() - renderStart;
+
       // --- Write rendered image to S3 cache (fire-and-forget) ---
       if (useCache && s3CacheKey) {
         client
@@ -418,6 +482,8 @@ export function createImageHandler(
         headers: {
           'Content-Type': processed.contentType,
           ...cacheHeaders,
+          // Fresh render — Sharp ran. x-render-ms is the Sharp cost.
+          ...timingHeaders({ cache: 'render', fetchMs, renderMs, totalMs: Date.now() - t0 }),
         },
         body: processed.data.toString('base64'),
         isBase64Encoded: true,