@agilesyndrome/cf-genai-base 0.1.1 → 0.1.3

package/CONTRACT.md

@@ -4,8 +4,7 @@ Every site built from this foundation follows the same edge contract.
 
 ## Worker entrypoint
 
-`createWorker({ fetch, auth?, scheduled?, security? })` owns the Worker lifecycle.
-The site router owns pages, APIs, D1 queries, and R2 object keys. `scheduled`
+`createWorker({ fetch, features?, middleware?, auth?, scheduled?, security? })` owns the Worker lifecycle. Features run in declaration order and may call `next()` or return a response. The site router owns pages, APIs, D1 queries, and R2 object keys. `scheduled`
 is optional and must use `ctx.waitUntil` for background work.
 
 ## Routes

package/README.md

@@ -1,21 +1,29 @@
-# `@easleyowl/cf-genai-base`
+# `@agilesyndrome/cf-genai-base`
 
 Opinionated startup boilerplate for small Cloudflare Workers.
 
 The base is deliberately small: a site still owns its router, HTML, D1
-queries, R2 keys, and scheduled jobs. `createWorker` composes an optional auth
-handler, normalizes uncaught failures, and applies baseline response headers.
+queries, R2 keys, and scheduled jobs. `createWorker` composes ordered feature middleware, normalizes uncaught failures, and applies baseline response headers.
 Use D1 bindings for durable application data and R2 bindings for binary assets;
 do not put either into module-level state.
 
 ```js
-import { createWorker, healthResponse } from "@easleyowl/cf-genai-base";
+import { createWorker, healthResponse } from "@agilesyndrome/cf-genai-base";
 
 export default createWorker({
-  auth: (request, env) => auth.handle(request, env),
+  features: [auth],
   fetch: async (request, env) => {
     if (new URL(request.url).pathname === "/health") return healthResponse(env);
     return router(request, env);
   },
 });
 ```
+
+Features expose `middleware(request, env, ctx, next, state)` and may short-circuit reserved routes, attach request state, or call `next()`.
+
+## Shared platform helpers
+
+`createWorker` can own `/health` and `/api/health`, run a boot validator before
+requests, and optionally deliver server-side PostHog events. Use
+`assertBoot(env, { bindings: ["DB"], required: ["AUTH_SESSION_SECRET"] })` in a
+site initializer to fail closed when its Cloudflare configuration is incomplete.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agilesyndrome/cf-genai-base",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "exports": {
     ".": "./src/index.js"
@@ -8,7 +8,8 @@
   "description": "Lean Worker lifecycle and security helpers for Cloudflare sites.",
   "license": "MIT",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "files": [
     "src",

package/src/index.js

@@ -1,23 +1,56 @@
 /**
- * Small, opinionated Worker composition layer shared by the Easley Owl sites.
- * Site code owns routing and data access; this owns lifecycle and the edges.
+ * Lean, opinionated Worker composition for Cloudflare sites.
+ * Site code owns domain routes and data; this owns lifecycle and edge concerns.
  */
-export function createWorker({ fetch, scheduled, auth, security = true }) {
+export function createWorker({ fetch, scheduled, auth, middleware = [], features = [], health, boot, metrics, security = true }) {
+  if (typeof fetch !== "function") throw new TypeError("createWorker requires a fetch handler");
+  const chain = [
+    ...features.flatMap((feature) => feature?.middleware ? [feature.middleware.bind(feature)] : []),
+    ...middleware,
+    ...(auth ? [(request, env, ctx, next) => auth(request, env, ctx, next)] : []),
+  ].filter(Boolean);
   return {
     async fetch(request, env, ctx) {
       try {
-        const authResponse = auth ? await auth(request, env, ctx) : null;
-        const response = authResponse || await fetch(request, env, ctx);
+        if (boot) await boot(env, { request, ctx });
+        const url = new URL(request.url);
+        const state = Object.create(null);
+        const dispatch = async (index, currentRequest = request) => {
+          const layer = chain[index];
+          if (!layer) {
+            if (url.pathname === "/health" || url.pathname === "/api/health") {
+              const details = health ? await health(env, { request: currentRequest, ctx, state }) : {};
+              return healthResponse(env, details);
+            }
+            return fetch(currentRequest, env, ctx, state);
+          }
+          if (typeof layer !== "function") throw new TypeError("Worker middleware must be a function");
+          return layer(currentRequest, env, ctx, (nextRequest = currentRequest) => dispatch(index + 1, nextRequest), state);
+        };
+        const response = await dispatch(0);
+        if (metrics) metrics.request(request, response, env, ctx);
         return security ? secureResponse(response) : response;
       } catch (error) {
         console.error("[worker] request failed", error);
-        return secureResponse(Response.json({ error: "Internal server error" }, { status: 500 }));
+        return secureResponse(Response.json({ error: "Internal server error" }, { status: 500, headers: { "Cache-Control": "no-store" } }));
       }
     },
     ...(scheduled ? { scheduled } : {}),
   };
 }
 
+export function validateBoot(env, { bindings = [], required = [] } = {}) {
+  const missingBindings = bindings.filter((name) => !env?.[name]);
+  const missingValues = required.filter((name) => !env?.[name] || String(env[name]).startsWith("replace-with-"));
+  return { ok: missingBindings.length === 0 && missingValues.length === 0, missingBindings, missingValues };
+}
+
+export function assertBoot(env, spec = {}) {
+  const result = validateBoot(env, spec);
+  if (!result.ok) throw new Error(`Worker boot validation failed: ${[...result.missingBindings, ...result.missingValues].join(", ")}`);
+  return result;
+}
+
 export function secureResponse(response) {
   const headers = new Headers(response.headers);
   headers.set("X-Content-Type-Options", "nosniff");
@@ -34,10 +67,26 @@ export function methodNotAllowed(allow = "GET") {
 }
 
 export function healthResponse(env, details = {}) {
-  return Response.json({
-    ok: true,
-    version: String(env.BUILD_SHA || "unknown").slice(0, 7),
-    build_number: env.BUILD_NUMBER ? String(env.BUILD_NUMBER) : null,
-    ...details,
-  }, { headers: { "Cache-Control": "no-store" } });
+  return Response.json({ ok: true, version: String(env.BUILD_SHA || "unknown").slice(0, 7), build_number: env.BUILD_NUMBER ? String(env.BUILD_NUMBER) : null, ...details }, { headers: { "Cache-Control": "no-store" } });
+}
+
+export function createMetrics({ tokenEnv = "POSTHOG_TOKEN", host = "https://us.i.posthog.com" } = {}) {
+  return {
+    request(request, response, env, ctx) {
+      if (!env?.[tokenEnv] || !ctx?.waitUntil || new URL(request.url).pathname === "/health") return;
+      const event = response.status >= 500 ? "server_error" : "request";
+      ctx.waitUntil(track(env, event, { path: new URL(request.url).pathname, method: request.method, status: response.status }, { tokenEnv, host }));
+    },
+    track: (env, event, properties, ctx) => ctx?.waitUntil?.(track(env, event, properties, { tokenEnv, host })),
+  };
+}
+
+async function track(env, event, properties, { tokenEnv, host }) {
+  try {
+    const token = String(env?.[tokenEnv] || "");
+    if (!token) return;
+    await fetch(`${host.replace(/\/+$/, "")}/capture/`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ api_key: token, event, properties: { ...properties, distinct_id: properties?.distinct_id || "anonymous" } }) });
+  } catch (error) {
+    console.error("[metrics] delivery failed", error);
+  }
 }