@everystack/server 0.2.15 → 0.2.17

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.17",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/image.ts

@@ -15,6 +15,7 @@ import type {
   APIGatewayProxyStructuredResultV2,
 } from 'aws-lambda';
 import { log } from './log';
+import { buildTimingHeaders } from './timing';
 
 export interface S3CacheConfig {
   /** Enable S3 origin cache for processed images. Default: false. */
@@ -45,6 +46,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 +220,28 @@ 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 {};
+    return buildTimingHeaders('image', {
+      cache: opts.cache,
+      totalMs: opts.totalMs,
+      segments: { fetch: opts.fetchMs, render: opts.renderMs },
+    });
+  }
 
   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 +302,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 +330,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 +346,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 +389,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 +400,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 +443,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 +451,8 @@ export function createImageHandler(
         }
       }
 
+      const renderMs = Date.now() - renderStart;
+
       // --- Write rendered image to S3 cache (fire-and-forget) ---
       if (useCache && s3CacheKey) {
         client
@@ -418,6 +475,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/index.ts

@@ -16,6 +16,10 @@ import type {
 } from 'aws-lambda';
 
 import { log } from './log';
+import { buildTimingHeaders } from './timing';
+
+export { buildTimingHeaders } from './timing';
+export type { TimingHeaderOptions } from './timing';
 
 // --- Types ---
 
@@ -80,6 +84,8 @@ export interface LambdaHandlerOptions {
   /** Optional log sink — writes structured request logs to S3 or other storage.
    *  Non-blocking: if the sink fails, logs still go to CloudWatch via stdout. */
   logSink?: LogSink;
+  /** Emit Server-Timing headers on responses. Default true. */
+  observability?: boolean;
 }
 
 // --- Event Adapter ---
@@ -224,10 +230,14 @@ export function createLambdaHandler(
     }
     // HTTP event — Function URL or API Gateway
     const httpEvent = event as APIGatewayProxyEventV2;
+    // Prefer the CloudFront edge request id: it also lands in the CDN access
+    // logs (x-edge-request-id), so app logs join to platform_requests rows.
     const requestId =
+      httpEvent.headers?.['x-amz-cf-id'] ||
       httpEvent.headers?.['x-amzn-trace-id'] ||
       httpEvent.headers?.['x-request-id'] ||
       crypto.randomUUID();
+    const t0 = Date.now();
 
     try {
       const { router } = await ensureInitialized();
@@ -241,6 +251,11 @@ export function createLambdaHandler(
       // Propagate request ID
       result.headers = { ...result.headers, 'x-request-id': requestId };
 
+      // Timing observability — additive, mirrors the image handler's headers
+      if (options.observability !== false && !result.headers['Server-Timing']) {
+        Object.assign(result.headers, buildTimingHeaders('server', { totalMs: Date.now() - t0 }));
+      }
+
       // Set Cache-Control if not already set by the handler
       if (!result.headers['cache-control']) {
         if (method === 'GET' || method === 'HEAD') {

package/src/migrate.ts

@@ -1,16 +1,92 @@
 /**
- * @everystack/server/migrate — Drizzle migration runner.
+ * @everystack/server/migrate — Drizzle migration runner that cannot lie.
+ *
+ * drizzle's migrate() only runs what meta/_journal.json lists, and reports
+ * nothing either way. A SQL file missing from the journal silently never
+ * applies — a failure mode that is miserable to debug. This wrapper:
+ *
+ *   - warns about migration files with no journal entry (the silent skip)
+ *   - fails fast, by name, on journal entries with no SQL file
+ *   - reports exactly which migrations applied this run
  *
  * Called directly from onAction handler (CLI → IAM → Lambda invoke).
  * No HTTP, no auth — IAM is the authorization layer.
  */
 
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sql } from 'drizzle-orm';
 import { migrate } from 'drizzle-orm/postgres-js/migrator';
 
+export interface MigrationResult {
+  success: boolean;
+  message: string;
+  /** Journal tags applied in this run. */
+  applied: string[];
+  /** Drift warnings — surface these to the operator, always. */
+  warnings: string[];
+}
+
+interface JournalEntry {
+  tag: string;
+  when: number;
+}
+
+function extractRows(result: unknown): Array<Record<string, unknown>> {
+  if (Array.isArray(result)) return result as Array<Record<string, unknown>>;
+  return ((result as { rows?: unknown[] })?.rows ?? []) as Array<Record<string, unknown>>;
+}
+
+/** Highest created_at in drizzle's ledger, or -1 before the first run. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function lastAppliedWhen(db: any): Promise<number> {
+  try {
+    const result = await db.execute(
+      sql`SELECT max(created_at)::bigint AS max FROM drizzle.__drizzle_migrations`,
+    );
+    const max = extractRows(result)[0]?.max;
+    return max === null || max === undefined ? -1 : Number(max);
+  } catch {
+    return -1; // ledger table doesn't exist yet — nothing applied
+  }
+}
+
 export async function runMigrations(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   db: any,
   migrationsFolder: string
-): Promise<{ success: boolean; message: string }> {
+): Promise<MigrationResult> {
+  const journal = JSON.parse(
+    readFileSync(join(migrationsFolder, 'meta/_journal.json'), 'utf8'),
+  ) as { entries: JournalEntry[] };
+  const entries = journal.entries ?? [];
+  const files = readdirSync(migrationsFolder).filter((f) => /^\d{4}_.+\.sql$/.test(f));
+  const tags = new Set(entries.map((e) => e.tag));
+
+  // Journal entry without a file: drizzle would die with an opaque ENOENT.
+  const ghosts = entries.filter((e) => !files.includes(`${e.tag}.sql`)).map((e) => e.tag);
+  if (ghosts.length > 0) {
+    throw new Error(
+      `Journal entries with no SQL file (broken journal): ${ghosts.join(', ')}`,
+    );
+  }
+
+  // File without a journal entry: drizzle will silently NEVER apply it.
+  const warnings = files
+    .filter((f) => !tags.has(f.replace(/\.sql$/, '')))
+    .map((f) => `${f} has no entry in meta/_journal.json — drizzle will NEVER apply it`);
+
+  const before = await lastAppliedWhen(db);
   await migrate(db, { migrationsFolder });
-  return { success: true, message: 'Migrations applied' };
+
+  const applied = entries
+    .filter((e) => e.when > before)
+    .map((e) => e.tag);
+
+  const message =
+    applied.length > 0
+      ? `Applied ${applied.length} migration(s): ${applied.join(', ')}`
+      : 'Already up to date — no new migrations';
+
+  return { success: true, message, applied, warnings };
 }

package/src/plugin.ts

@@ -216,7 +216,10 @@ export function createPluginLambdaHandler(
 
     // HTTP event — Function URL or API Gateway
     const httpEvent = event as APIGatewayProxyEventV2;
+    // Prefer the CloudFront edge request id: it also lands in the CDN access
+    // logs (x-edge-request-id), so app logs join to platform_requests rows.
     const requestId =
+      httpEvent.headers?.['x-amz-cf-id'] ||
       httpEvent.headers?.['x-amzn-trace-id'] ||
       httpEvent.headers?.['x-request-id'] ||
       crypto.randomUUID();

package/src/timing.ts

@@ -0,0 +1,39 @@
+/**
+ * Cache-state + timing observability headers.
+ *
+ * One builder for every handler (image, SSR, API): prefixed x-<name>-ms
+ * headers for machines, a Server-Timing mirror for browser devtools.
+ * Additive only — callers gate on their own observability flag and spread
+ * the result into response headers.
+ */
+
+export interface TimingHeaderOptions {
+  /** Cache state, e.g. 'hit' | 'render'. Emitted as x-<prefix>-cache. */
+  cache?: string;
+  /** Total handler wall time. Emitted as x-<prefix>-ms. */
+  totalMs: number;
+  /** Named sub-timings, each emitted as x-<name>-ms. Undefined values skip. */
+  segments?: Record<string, number | undefined>;
+}
+
+export function buildTimingHeaders(
+  prefix: string,
+  options: TimingHeaderOptions,
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    [`x-${prefix}-ms`]: String(options.totalMs),
+  };
+  if (options.cache) headers[`x-${prefix}-cache`] = options.cache;
+
+  const timings: string[] = [];
+  if (options.cache) timings.push(`cache;desc=${options.cache}`);
+  for (const [name, ms] of Object.entries(options.segments ?? {})) {
+    if (ms === undefined) continue;
+    headers[`x-${name}-ms`] = String(ms);
+    timings.push(`${name};dur=${ms}`);
+  }
+  timings.push(`total;dur=${options.totalMs}`);
+  headers['Server-Timing'] = timings.join(', ');
+
+  return headers;
+}