@everystack/server 0.2.14 → 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.14",
+  "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,

package/src/plugin.ts

@@ -111,6 +111,14 @@ export interface PluginLambdaHandlerOptions {
   actions?: Record<string, ActionHandler>;
   /** Override default Cache-Control headers */
   cache?: ServerCacheConfig;
+  /**
+   * Serve HTTP. Default true. Set false for an operator Lambda (server/ops.ts):
+   * routes are not built and HTTP-shaped events are rejected with 403 — the
+   * function answers `_action` invokes only. IAM (lambda:InvokeFunction) is the
+   * auth layer. Use with createAdminDb() so the privileged credential lives
+   * here, not in the HTTP-facing API function.
+   */
+  http?: boolean;
 }
 
 // --- Plugin Lambda Handler Implementation ---
@@ -118,9 +126,10 @@ export interface PluginLambdaHandlerOptions {
 export function createPluginLambdaHandler(
   options: PluginLambdaHandlerOptions
 ): (event: APIGatewayProxyEventV2 | Record<string, unknown>) => Promise<APIGatewayProxyStructuredResultV2 | unknown> {
+  const httpEnabled = options.http !== false;
   let cached: {
     ctx: PluginContext;
-    router: (path: string, method: string) => Handler;
+    router?: (path: string, method: string) => Handler;
     actions: Record<string, ActionHandler>;
     logSink?: LogSink;
   } | null = null;
@@ -136,11 +145,6 @@ export function createPluginLambdaHandler(
       contributions.push(await plugin(ctx));
     }
 
-    // Collect routes (plugin order = priority)
-    const pluginRoutes = contributions.flatMap(c => c.routes ?? []);
-    const appRoutes = options.routes?.(ctx) ?? [];
-    const allRoutes = [...pluginRoutes, ...appRoutes];
-
     // Collect actions (app-level takes precedence on collision)
     const pluginActions: Record<string, ActionHandler> = {};
     for (const contribution of contributions) {
@@ -150,6 +154,20 @@ export function createPluginLambdaHandler(
     }
     const allActions = { ...pluginActions, ...(options.actions ?? {}) };
 
+    // Operator mode (http: false) — actions only. Skip routing entirely;
+    // HTTP-shaped events are rejected below. Routes contributed by plugins
+    // are intentionally ignored.
+    if (!httpEnabled) {
+      cached = { ctx, actions: allActions };
+      log('info', 'Plugin handlers initialized (actions only)', { plugins: options.plugins.length });
+      return cached;
+    }
+
+    // Collect routes (plugin order = priority)
+    const pluginRoutes = contributions.flatMap(c => c.routes ?? []);
+    const appRoutes = options.routes?.(ctx) ?? [];
+    const allRoutes = [...pluginRoutes, ...appRoutes];
+
     // Collect log sink (first one wins)
     const logSink = contributions.find(c => c.logSink)?.logSink;
 
@@ -182,6 +200,20 @@ export function createPluginLambdaHandler(
       }
     }
 
+    // Operator mode — reject anything that isn't an `_action` invoke. A caller
+    // with IAM invoke rights can hand the function any event shape; refuse to
+    // route HTTP on the privileged connection.
+    if (!httpEnabled) {
+      if ('requestContext' in event || 'rawPath' in event) {
+        return {
+          statusCode: 403,
+          headers: { 'Content-Type': 'application/json', 'cache-control': 'no-store' },
+          body: JSON.stringify({ error: 'Forbidden' }),
+        };
+      }
+      return { error: 'Missing _action' };
+    }
+
     // HTTP event — Function URL or API Gateway
     const httpEvent = event as APIGatewayProxyEventV2;
     const requestId =
@@ -194,7 +226,7 @@ export function createPluginLambdaHandler(
       const request = eventToRequest(httpEvent);
       const path = httpEvent.rawPath;
       const method = httpEvent.requestContext.http.method;
-      const handlerFn = router(path, method);
+      const handlerFn = router!(path, method);
       const response = await handlerFn(request);
       const result = await responseToResult(response);
 
@@ -285,57 +317,19 @@ export interface OpsLambdaHandlerOptions {
 /**
  * Dedicated operator entrypoint — handles `_action` invokes only.
  *
+ * Thin alias for `createPluginLambdaHandler({ ...options, http: false })`.
  * Deploy as a separate Lambda (server/ops.ts) and link ADMIN_DATABASE_URL to
  * it instead of the API function. IAM (lambda:InvokeFunction) is the auth
- * layer, same as the API _action path. HTTP events are rejected: this
- * function must never be wired to a Function URL or the CDN.
+ * layer; HTTP-shaped events are rejected.
+ *
+ * @deprecated Prefer `createPluginLambdaHandler({ http: false })` directly.
  */
 export function createOpsLambdaHandler(
   options: OpsLambdaHandlerOptions
 ): (event: Record<string, unknown>) => Promise<unknown> {
-  let cached: { ctx: PluginContext; actions: Record<string, ActionHandler> } | null = null;
-
-  async function ensureInitialized() {
-    if (cached) return cached;
-    const ctx = await options.context();
-    const actions: Record<string, ActionHandler> = {};
-    for (const plugin of options.plugins) {
-      const contribution = await plugin(ctx);
-      if (contribution.actions) Object.assign(actions, contribution.actions);
-    }
-    Object.assign(actions, options.actions ?? {});
-    cached = { ctx, actions };
-    log('info', 'Ops handlers initialized', { actions: Object.keys(actions).length });
-    return cached;
-  }
-
-  return async (event: Record<string, unknown>): Promise<unknown> => {
-    if (!('_action' in event) || typeof event._action !== 'string') {
-      // Not an operator invoke. Reject HTTP-shaped events explicitly.
-      if ('requestContext' in event || 'rawPath' in event) {
-        return {
-          statusCode: 403,
-          headers: { 'Content-Type': 'application/json', 'cache-control': 'no-store' },
-          body: JSON.stringify({ error: 'Forbidden' }),
-        };
-      }
-      return { error: 'Missing _action' };
-    }
-
-    const { ctx, actions } = await ensureInitialized();
-    const actionName = event._action as string;
-    const actionHandler = actions[actionName];
-    if (!actionHandler) {
-      return { error: `Unknown action: ${actionName}` };
-    }
-    log('info', 'Ops action invoked', { action: actionName });
-    try {
-      return await actionHandler(event._payload, ctx);
-    } catch (error) {
-      log('error', 'Ops action error', { action: actionName, error: String(error) });
-      return { error: String(error) };
-    }
-  };
+  return createPluginLambdaHandler({ ...options, http: false }) as (
+    event: Record<string, unknown>
+  ) => Promise<unknown>;
 }
 
 // --- SSR Fallback Plugin ---