@agilesyndrome/cf-genai-base 0.1.0 → 0.1.2

package/README.md

@@ -19,3 +19,10 @@ export default createWorker({
   },
 });
 ```
+
+## 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.0",
+  "version": "0.1.2",
   "type": "module",
   "exports": {
     ".": "./src/index.js"
@@ -18,7 +18,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/agilesyndrome/cf-genai-base.git"
+    "url": "git+https://github.com/agilesyndrome/cf-genai-base.git"
   },
   "homepage": "https://github.com/agilesyndrome/cf-genai-base#readme"
 }

package/src/index.js

@@ -1,23 +1,47 @@
 /**
- * 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, health, boot, metrics, security = true }) {
+  if (typeof fetch !== "function") throw new TypeError("createWorker requires a fetch handler");
   return {
     async fetch(request, env, ctx) {
       try {
+        if (boot) await boot(env, { request, ctx });
+        const url = new URL(request.url);
         const authResponse = auth ? await auth(request, env, ctx) : null;
-        const response = authResponse || await fetch(request, env, ctx);
+        let response = authResponse;
+        if (!response) {
+          if (url.pathname === "/health" || url.pathname === "/api/health") {
+            const details = health ? await health(env, { request, ctx }) : {};
+            response = healthResponse(env, details);
+          } else {
+            response = await fetch(request, env, ctx);
+          }
+        }
+        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 +58,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);
+  }
 }