qlara 0.1.5 → 0.1.7

package/dist/aws.cjs

@@ -449,7 +449,7 @@ function buildTemplate(config) {
               CachePolicyId: { Ref: "CachePolicy" },
               LambdaFunctionAssociations: [
                 {
-                  EventType: "origin-response",
+                  EventType: "origin-request",
                   LambdaFunctionARN: { Ref: "EdgeHandlerVersion" },
                   IncludeBody: false
                 }
@@ -764,7 +764,7 @@ async function updateCloudFrontEdgeVersion(cf, distributionId, newVersionArn) {
   const lambdaAssociations = config.DefaultCacheBehavior?.LambdaFunctionAssociations;
   if (lambdaAssociations?.Items) {
     for (const assoc of lambdaAssociations.Items) {
-      if (assoc.EventType === "origin-response") {
+      if (assoc.EventType === "origin-request") {
         assoc.LambdaFunctionARN = newVersionArn;
       }
     }

package/dist/aws.js

@@ -446,7 +446,7 @@ function buildTemplate(config) {
               CachePolicyId: { Ref: "CachePolicy" },
               LambdaFunctionAssociations: [
                 {
-                  EventType: "origin-response",
+                  EventType: "origin-request",
                   LambdaFunctionARN: { Ref: "EdgeHandlerVersion" },
                   IncludeBody: false
                 }
@@ -760,7 +760,7 @@ async function updateCloudFrontEdgeVersion(cf, distributionId, newVersionArn) {
   const lambdaAssociations = config.DefaultCacheBehavior?.LambdaFunctionAssociations;
   if (lambdaAssociations?.Items) {
     for (const assoc of lambdaAssociations.Items) {
-      if (assoc.EventType === "origin-response") {
+      if (assoc.EventType === "origin-request") {
         assoc.LambdaFunctionARN = newVersionArn;
       }
     }

package/dist/cli.js

@@ -457,7 +457,7 @@ function buildTemplate(config) {
               CachePolicyId: { Ref: "CachePolicy" },
               LambdaFunctionAssociations: [
                 {
-                  EventType: "origin-response",
+                  EventType: "origin-request",
                   LambdaFunctionARN: { Ref: "EdgeHandlerVersion" },
                   IncludeBody: false
                 }
@@ -768,7 +768,7 @@ async function updateCloudFrontEdgeVersion(cf, distributionId, newVersionArn) {
   const lambdaAssociations = config.DefaultCacheBehavior?.LambdaFunctionAssociations;
   if (lambdaAssociations?.Items) {
     for (const assoc of lambdaAssociations.Items) {
-      if (assoc.EventType === "origin-response") {
+      if (assoc.EventType === "origin-request") {
         assoc.LambdaFunctionARN = newVersionArn;
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qlara",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Runtime ISR for static React apps — dynamic routing and SEO metadata for statically exported Next.js apps on AWS",
   "license": "MIT",
   "keywords": [

package/src/provider/aws/edge-handler.ts

@@ -1,23 +1,27 @@
 /**
- * Lambda@Edge origin-response handler for Qlara.
+ * Lambda@Edge origin-request handler for Qlara.
  *
  * This file is bundled into a self-contained ZIP and deployed to Lambda@Edge.
  * It does NOT run in the developer's Node.js — it runs at CloudFront edge locations.
  *
  * Config values are injected at bundle time via esbuild `define` (Lambda@Edge has no env vars).
  *
+ * Runs as an **origin-request** trigger. The handler NEVER generates responses —
+ * it always forwards the request to S3 origin. This ensures CloudFront caches
+ * the S3 origin response natively, with identical behavior for build-time and
+ * renderer-generated pages.
+ *
  * Flow for a request to /product/5:
  * 1. CloudFront viewer-request rewrites /product/5 → /product/5.html
- * 2. S3 returns 403 (file doesn't exist, OAC treats missing as 403)
- * 3. This origin-response handler intercepts:
- *    a. Invokes the renderer Lambda synchronously
- *    b. Renderer fetches metadata from the data source, patches fallback HTML with SEO metadata
- *    c. Renderer uploads product/5.html to S3 and returns the rendered HTML
- *    d. Edge handler serves the fully rendered HTML (first request gets full SEO)
- *    e. Subsequent requests hit S3 directly (page is cached)
+ * 2. CloudFront checks edge cache → miss → fires this origin-request handler
+ * 3. Handler checks S3 for product/5.html:
+ *    a. File exists → forward to S3 origin (CloudFront caches the S3 response)
+ *    b. File doesn't exist → invoke renderer (uploads to S3) → forward to S3 origin
+ * 4. CloudFront caches the S3 response at the edge
+ * 5. Subsequent requests hit CloudFront edge cache directly (~10-30ms)
  */
 
-import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
+import { S3Client, HeadObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
 import { LambdaClient, InvokeCommand } from '@aws-sdk/client-lambda';
 
 // ── Injected at bundle time by esbuild define ────────────────────
@@ -43,30 +47,24 @@ interface RouteMatch {
   params: Record<string, string>;
 }
 
-interface CloudFrontResponse {
-  status: string;
-  statusDescription: string;
-  headers: Record<string, Array<{ key: string; value: string }>>;
-  body?: string;
-}
-
 interface CloudFrontRequest {
   uri: string;
   querystring: string;
+  method: string;
+  headers: Record<string, Array<{ key: string; value: string }>>;
+  origin?: Record<string, unknown>;
 }
 
-interface CloudFrontResponseEvent {
+interface CloudFrontRequestEvent {
   Records: Array<{
     cf: {
       request: CloudFrontRequest;
-      response: CloudFrontResponse;
     };
   }>;
 }
 
 // ── Constants ────────────────────────────────────────────────────
 
-const FALLBACK_FILENAME = '_fallback.html';
 const FALLBACK_PLACEHOLDER = '__QLARA_FALLBACK__';
 
 // ── Caching ──────────────────────────────────────────────────────
@@ -77,10 +75,8 @@ interface CacheEntry<T> {
 }
 
 const MANIFEST_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
-const FALLBACK_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
 
 let manifestCache: CacheEntry<QlaraManifest> = { data: null, expiry: 0 };
-const fallbackCache: Map<string, CacheEntry<string>> = new Map();
 
 // ── Route matching (inlined from routes.ts) ──────────────────────
 
@@ -131,77 +127,37 @@ async function getManifest(): Promise<QlaraManifest | null> {
 }
 
 /**
- * Get the fallback HTML for a route.
- * Looks up the _fallback.html file in the route's directory in S3.
- *
- * '/product/:id' → reads 'product/_fallback.html' from S3
+ * Check if a file exists in S3 using HEAD request (no body transfer).
  */
-async function getFallbackHtml(route: ManifestRoute): Promise<string | null> {
-  // Derive the fallback S3 key from the route pattern
-  const parts = route.pattern.replace(/^\//, '').split('/');
-  const dirParts = parts.filter(p => !p.startsWith(':'));
-  const fallbackKey = [...dirParts, FALLBACK_FILENAME].join('/');
-
-  // Check cache
-  const cached = fallbackCache.get(fallbackKey);
-  if (cached?.data && Date.now() < cached.expiry) {
-    return cached.data;
-  }
-
+async function fileExistsInS3(key: string): Promise<boolean> {
   try {
-    const response = await s3.send(
-      new GetObjectCommand({
+    await s3.send(
+      new HeadObjectCommand({
         Bucket: __QLARA_BUCKET_NAME__,
-        Key: fallbackKey,
+        Key: key,
       })
     );
-    const body = await response.Body?.transformToString('utf-8');
-    if (!body) return null;
-
-    fallbackCache.set(fallbackKey, {
-      data: body,
-      expiry: Date.now() + FALLBACK_CACHE_TTL,
-    });
-    return body;
+    return true;
   } catch {
-    return null;
+    return false;
   }
 }
 
-/**
- * Patch the fallback HTML by replacing __QLARA_FALLBACK__ with actual param values.
- */
-function patchFallback(html: string, params: Record<string, string>): string {
-  let patched = html;
-
-  // For now, all params use the same placeholder. Replace with the last param value
-  // (which is the dynamic segment — e.g., the product ID).
-  // For multi-param routes like /blog/:year/:slug, we'd need per-param placeholders.
-  const paramValues = Object.values(params);
-  const lastParam = paramValues[paramValues.length - 1] || '';
-
-  patched = patched.replace(new RegExp(FALLBACK_PLACEHOLDER, 'g'), lastParam);
-
-  return patched;
-}
-
 // ── Renderer invocation ──────────────────────────────────────────
 
 const lambda = new LambdaClient({ region: __QLARA_REGION__ });
 
 /**
- * Invoke the renderer Lambda synchronously and return the rendered HTML.
+ * Invoke the renderer Lambda synchronously.
  * The renderer fetches metadata from the data source, patches the fallback HTML,
- * uploads to S3, and returns the fully rendered HTML.
+ * and uploads the final HTML to S3.
  *
- * This ensures the first request for a new page gets full SEO metadata —
- * critical for crawlers that only visit once.
- *
- * Returns null if the renderer fails (caller falls back to unpatched HTML).
+ * We wait for the renderer to complete so the file exists in S3 before
+ * CloudFront forwards the request to origin.
  */
-async function invokeRenderer(uri: string, match: RouteMatch): Promise<string | null> {
+async function invokeRenderer(uri: string, match: RouteMatch): Promise<void> {
   try {
-    const result = await lambda.send(
+    await lambda.send(
       new InvokeCommand({
         FunctionName: __QLARA_RENDERER_ARN__,
         InvocationType: 'RequestResponse',
@@ -213,99 +169,61 @@ async function invokeRenderer(uri: string, match: RouteMatch): Promise<string |
         }),
       })
     );
-
-    if (result.FunctionError || !result.Payload) {
-      return null;
-    }
-
-    const payload = JSON.parse(new TextDecoder().decode(result.Payload));
-    return payload.html || null;
   } catch {
-    return null;
-  }
-}
-
-// ── Response builder ─────────────────────────────────────────────
-
-// Lambda@Edge read-only headers — must be preserved from the original response
-const READ_ONLY_HEADERS = ['transfer-encoding', 'via'];
-
-function buildHtmlResponse(
-  html: string,
-  originalResponse: CloudFrontResponse
-): CloudFrontResponse {
-  const headers: Record<string, Array<{ key: string; value: string }>> = {
-    'content-type': [
-      { key: 'Content-Type', value: 'text/html; charset=utf-8' },
-    ],
-    'cache-control': [
-      { key: 'Cache-Control', value: `public, max-age=0, s-maxage=${__QLARA_CACHE_TTL__}, stale-while-revalidate=60` },
-    ],
-  };
-
-  // Preserve read-only headers from the original response to avoid 502
-  for (const headerName of READ_ONLY_HEADERS) {
-    if (originalResponse.headers[headerName]) {
-      headers[headerName] = originalResponse.headers[headerName];
-    }
+    // Renderer failed — S3 will return 403/404, which is acceptable
   }
-
-  return {
-    status: '200',
-    statusDescription: 'OK',
-    headers,
-    body: html,
-  };
 }
 
 // ── Handler ──────────────────────────────────────────────────────
 
+/**
+ * Origin-request handler.
+ *
+ * ALWAYS returns the request object (forward to S3 origin).
+ * Never generates responses — CloudFront caches S3 origin responses natively.
+ *
+ * For dynamic routes where the file doesn't exist yet, the renderer is invoked
+ * synchronously to upload the HTML to S3 before forwarding.
+ */
 export async function handler(
-  event: CloudFrontResponseEvent
-): Promise<CloudFrontResponse> {
-  const record = event.Records[0].cf;
-  const response = record.response;
-  const request = record.request;
+  event: CloudFrontRequestEvent
+): Promise<CloudFrontRequest> {
+  const request = event.Records[0].cf.request;
   const uri = request.uri;
-  const status = parseInt(response.status, 10);
 
-  // 1. If response is 200 (file exists in S3), pass through
-  if (status !== 403 && status !== 404) {
-    return response;
+  // 1. Non-HTML file requests → forward to S3 origin directly
+  //    e.g. /product/20.txt (RSC flight data), JS, CSS, images, etc.
+  const nonHtmlExt = uri.match(/\.([a-z0-9]+)$/)?.[1];
+  if (nonHtmlExt && nonHtmlExt !== 'html') {
+    return request;
   }
 
-  // At this point, the file does NOT exist in S3 (403 from OAC or 404)
+  // 2. Check if the HTML file exists in S3 (HEAD — no body transfer)
+  const s3Key = uri.replace(/^\//, '');
+  let fileExists = false;
 
-  // 2. Skip non-HTML file requests — these are never dynamic routes
-  //    e.g. /product/20.txt (RSC flight data), /product/20.json, etc.
-  const nonHtmlExt = uri.match(/\.([a-z0-9]+)$/)?.[1];
-  if (nonHtmlExt && nonHtmlExt !== 'html') {
-    return response;
+  if (s3Key) {
+    fileExists = await fileExistsInS3(s3Key);
   }
 
-  // 3. Fetch manifest and check if this URL matches a Qlara dynamic route
-  const manifest = await getManifest();
-  // Strip .html suffix that the URL rewrite function adds before matching
+  // 3. File exists → forward to S3 (CloudFront will cache the S3 response)
+  if (fileExists) {
+    return request;
+  }
+
+  // 4. File missing → check if this matches a dynamic route
   const cleanUri = uri.replace(/\.html$/, '');
+  const manifest = await getManifest();
   const match = manifest ? matchRoute(cleanUri, manifest.routes) : null;
 
-  // 4. If route matches: invoke renderer synchronously to get fully rendered HTML
   if (match) {
-    // Try to render with full SEO metadata (synchronous — waits for result)
-    const renderedHtml = await invokeRenderer(cleanUri, match);
-
-    if (renderedHtml) {
-      return buildHtmlResponse(renderedHtml, response);
-    }
-
-    // Renderer failed — fall back to unpatched fallback HTML (no SEO, but page still works)
-    const fallbackHtml = await getFallbackHtml(match.route);
-    if (fallbackHtml) {
-      const patchedHtml = patchFallback(fallbackHtml, match.params);
-      return buildHtmlResponse(patchedHtml, response);
-    }
+    // 5. Invoke renderer synchronously — it uploads the HTML to S3
+    await invokeRenderer(cleanUri, match);
+    // File now exists in S3 — forward to S3 origin
   }
 
-  // 5. No match or no fallback — return original error
-  return response;
+  // 6. Forward to S3 origin
+  //    - If renderer succeeded: S3 returns 200 → CloudFront caches ✅
+  //    - If renderer failed or no match: S3 returns 403/404
+  return request;
 }