@everystack/server 0.2.16 → 0.2.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.2.16",
+  "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. */
@@ -232,19 +233,11 @@ export function createImageHandler(
     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 buildTimingHeaders('image', {
+      cache: opts.cache,
+      totalMs: opts.totalMs,
+      segments: { fetch: opts.fetchMs, render: opts.renderMs },
+    });
   }
 
   return async (event: APIGatewayProxyEventV2): Promise<APIGatewayProxyStructuredResultV2> => {

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;
+}