@junejs/server 0.1.2 → 0.2.0

package/src/worker.ts

@@ -17,18 +17,35 @@ import type { DocumentConfig } from "@junejs/core/document";
 import type { I18nConfig } from "@junejs/core/i18n";
 import type { Resources } from "@junejs/core/resources";
 
+import type { Channel, ChannelFactory } from "@junejs/core/agent-config";
+import { blobFileStore } from "@junejs/core/agent-files";
+
 import { createPipeline, type ExtraHandler, type LayoutComponent, type LoadingComponent, type Resolved, type ResolvedResource, type ResourceHandler } from "./pipeline";
-import { durableAgentSurface, type DurableObjectNamespace } from "./agent-durable";
+import { durableAgentSurface, durableChannelSurface, type DurableObjectNamespace } from "./agent-durable";
+import { acceptTarget } from "./negotiate";
+import { compareRoutePatterns, parseSegment } from "./route-rank";
 import { contentTypeFor, RESERVED_PREFIX, safeRelativePath } from "./static-files";
 
+// The slice of workerd's ExecutionContext the worker threads through: webhook
+// channels ACK fast and finish their work (post the reply out-of-band) on
+// waitUntil — without it a floating promise can be killed when the isolate is
+// reclaimed. Optional end to end; a host without it (tests, other targets)
+// simply doesn't extend the invocation.
+export type WorkerExecutionContext = { waitUntil?(p: Promise<unknown>): void };
+
 export type WorkerManifest = {
   // Static paths → route definitions ("/", "/users", ...).
   routes: Record<string, BrandedRoute>;
   // Dynamic patterns in file-route syntax ("/posts/[slug]", "/docs/[...path]").
   dynamicRoutes?: Array<{ pattern: string; def: BrandedRoute }>;
   // Resource routes (app/**/route.*): a raw-Response handler keyed by its pattern
-  // (static or dynamic). Matched after pages, so a page never gets shadowed.
+  // (static or dynamic). Ranked with the pages by segment shape (route-rank.ts),
+  // exactly as `june dev` resolves; a page wins only at the SAME pattern.
   resourceRoutes?: Array<{ pattern: string; handler: ResourceHandler }>;
+  // Patterns scanned from .june/routes/ (framework-generated, e.g. Kura). Dev
+  // consults app/ first and falls back to .june/routes/, so every one of these
+  // ranks after every app/ route. Absent → all routes are app/ routes.
+  generatedRoutes?: string[];
   // Layout chains (root→leaf) keyed by route path / dynamic pattern. The build
   // freezes the same chain the dev server loads from app/layout.* files.
   layoutChains?: Record<string, LayoutComponent[]>;
@@ -45,6 +62,13 @@ export type WorkerManifest = {
   // by the build when an agent/ directory exists; absent → no durable agent on
   // the edge. The DO namespace binding is `env.AGENT`.
   agentName?: string;
+  // The agent's channels (Channel or `(env) => Channel` factories, from the
+  // compiled agent module) — mounted as webhook routes on the worker via
+  // durableChannelSurface when agent.runtime.channels is on. The SAME factories
+  // are also wired into the DO (DoAgentDef.channels) by the generated entry, so
+  // capability tools and host-side delivery work; this field is the WORKER half
+  // (verify the webhook, run the turn on the DO, reply on waitUntil).
+  agentChannels?: (Channel | ChannelFactory)[];
   // Locale routing config, frozen from june.config.ts `i18n`. The locales table
   // is plain data; a `resolveLocale` hook survives the in-process freeze (parity
   // test) but not JSON codegen — worker hook support lands with the codegen pass.
@@ -66,7 +90,13 @@ export type WorkerManifest = {
   services?: (env?: unknown) => unknown;
 };
 
-type Compiled = { regex: RegExp; names: string[]; def: BrandedRoute; pattern: string };
+// One row of the worker's route table: a page (def) or a resource route (handler).
+type Compiled = {
+  regex: RegExp;
+  names: string[];
+  pattern: string;
+  generated: boolean;
+} & ({ def: BrandedRoute; handler?: undefined } | { def?: undefined; handler: ResourceHandler });
 
 // "/posts/[slug]" | "/docs/[...path]" | "/notes/[[tag]]" → matcher. Optional
 // segments ([[x]], [[...x]]) wrap slash + capture together so absence matches;
@@ -76,52 +106,47 @@ function compilePattern(pattern: string): { regex: RegExp; names: string[] } {
   let source = "";
   let allOptional = true;
   for (const seg of pattern.split("/").filter(Boolean)) {
-    const oca = seg.match(/^\[\[\.\.\.(\w+)\]\]$/);
-    if (oca) {
-      names.push(oca[1]!);
-      source += "(?:/(.+))?";
-      continue;
-    }
-    const ca = seg.match(/^\[\.\.\.(\w+)\]$/);
-    if (ca) {
-      names.push(ca[1]!);
-      source += "/(.+)";
+    // Same grammar as the dev matcher (route-rank.ts parseSegment).
+    const { kind, name } = parseSegment(seg);
+    if (name) names.push(name);
+    if (kind === "optionalCatchAll") source += "(?:/(.+))?";
+    else if (kind === "optional") source += "(?:/([^/]+))?";
+    else {
+      if (kind === "catchAll") source += "/(.+)";
+      else if (kind === "param") source += "/([^/]+)";
+      // A static segment matches literally: escape every RegExp metacharacter,
+      // brackets included (`docs[v2`, `[slug].png` are static names).
+      else source += "/" + seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
       allOptional = false;
-      continue;
     }
-    const op = seg.match(/^\[\[(\w+)\]\]$/);
-    if (op) {
-      names.push(op[1]!);
-      source += "(?:/([^/]+))?";
-      continue;
-    }
-    const p = seg.match(/^\[(\w+)\]$/);
-    if (p) {
-      names.push(p[1]!);
-      source += "/([^/]+)";
-      allOptional = false;
-      continue;
-    }
-    source += "/" + seg.replace(/[.*+?^${}()|\\]/g, "\\$&");
-    allOptional = false;
   }
   if (source === "") return { regex: /^\/$/, names };
   return { regex: new RegExp(allOptional ? `^(?:${source}|/)$` : `^${source}$`), names };
 }
 
+// opts.staticBuild: set only by the static() build's in-process prerender worker
+// (see PipelineConfig.staticBuild) — never by a deployed entry.
 export function createWorker(
   manifest: WorkerManifest,
-): { fetch(request: Request, env?: unknown): Promise<Response> } {
-  const dynamic: Compiled[] = (manifest.dynamicRoutes ?? []).map((d) => ({
-    ...compilePattern(d.pattern),
-    def: d.def,
-    pattern: d.pattern,
-  }));
-  const resources = (manifest.resourceRoutes ?? []).map((r) => ({
-    ...compilePattern(r.pattern),
-    handler: r.handler,
-    pattern: r.pattern,
-  }));
+  opts: { staticBuild?: boolean } = {},
+): { fetch(request: Request, env?: unknown, ctx?: WorkerExecutionContext): Promise<Response> } {
+  // Pages and resource routes in ONE table, ordered the way `june dev` resolves
+  // (#312): app/ before .june/routes/, then segment shape (static > [param] >
+  // [...catchAll], required before optional), then a page before a resource
+  // route at the same pattern. The kind of route never outranks the shape.
+  const generated = new Set(manifest.generatedRoutes ?? []);
+  const row = (pattern: string) => ({ ...compilePattern(pattern), pattern, generated: generated.has(pattern) });
+  const table: Compiled[] = [
+    ...Object.entries(manifest.routes).map(([pattern, def]) => ({ ...row(pattern), def })),
+    ...(manifest.dynamicRoutes ?? []).map((d) => ({ ...row(d.pattern), def: d.def })),
+    ...(manifest.resourceRoutes ?? []).map((r) => ({ ...row(r.pattern), handler: r.handler })),
+  ];
+  table.sort(
+    (a, b) =>
+      Number(a.generated) - Number(b.generated) ||
+      compareRoutePatterns(a.pattern, b.pattern) ||
+      Number(!!a.handler) - Number(!!b.handler),
+  );
   const routeList = [
     ...Object.keys(manifest.routes),
     ...(manifest.dynamicRoutes ?? []).map((d) => d.pattern),
@@ -131,11 +156,28 @@ export function createWorker(
   const loadingFor = (key: string): LoadingComponent | undefined => manifest.loadings?.[key];
   const boundaryFor = (key: string): { index: number; key: string } | null =>
     manifest.layoutBoundaries?.[key] ?? null;
+  const resolvedPage = (def: BrandedRoute, key: string, params: Record<string, string>): Resolved => {
+    const b = boundaryFor(key);
+    return {
+      def,
+      params,
+      chain: chainFor(key),
+      boundaryIndex: b?.index ?? null,
+      boundaryKey: b?.key ?? null,
+      loading: loadingFor(key),
+    };
+  };
 
   // The worker's env (D1/KV/R2 bindings) arrives per fetch and is stable across
   // requests in an isolate; we capture the latest and hand it to the env-aware
-  // provider, which memoizes the opened handles on first call.
+  // provider, which memoizes the opened handles on first call. That "latest"
+  // pattern is safe ONLY for per-isolate-stable values — concurrent fetches
+  // interleave at await points, so anything per-INVOCATION (the execution
+  // context, and env used at a specific moment) must come from request-scoped
+  // storage instead: `requestLocals`, keyed by the Request identity that flows
+  // unchanged from fetch() through the pipeline to the agent surface.
   let currentEnv: unknown;
+  const requestLocals = new WeakMap<Request, { env: unknown; ctx?: WorkerExecutionContext }>();
   const provider = manifest.resources;
 
   // App services: the build sets a raw `(env) => services` factory here; memoize it per
@@ -144,18 +186,52 @@ export function createWorker(
   const servicesProvider = manifest.services;
   let servicesCache: { v: unknown } | undefined;
 
-  // Durable agent (edge): route the chat endpoint to the per-session DO bound at
-  // env.AGENT. Built only when the app has an agent (manifest.agentName) and the
-  // runtime is enabled; the surface is inert (null → fall through) until env.AGENT
-  // is present, so a worker without the DO binding is unaffected.
+  // Durable agent (edge): route the chat endpoint — and the agent's channel
+  // webhooks — to the per-session DO bound at env.AGENT. Built only when the app
+  // has an agent (manifest.agentName) and the runtime is enabled; the surface is
+  // inert (null → fall through) until env.AGENT is present, so a worker without
+  // the DO binding is unaffected.
   const agentSurface =
     manifest.agent.runtime.enabled && manifest.agentName
       ? (() => {
-          const route = durableAgentSurface(
-            () => (currentEnv as { AGENT?: DurableObjectNamespace } | undefined)?.AGENT,
-            { agentName: manifest.agentName, chatPath: manifest.agent.runtime.chat.path },
-          );
-          return (req: Request) => route(req);
+          const agentName = manifest.agentName;
+          const wantChannels = manifest.agent.runtime.channels !== false && (manifest.agentChannels?.length ?? 0) > 0;
+          return async (req: Request): Promise<Response | null> => {
+            // REQUEST-scoped, not isolate-scoped: the pipeline awaits between
+            // fetch() and this call, so a concurrent fetch may have run since —
+            // a module-level "current request" variable here would hand this
+            // webhook ANOTHER request's env (wrong AGENT namespace, factories
+            // resolved against foreign secrets) and register its background
+            // work on another invocation's waitUntil. Everything below reads
+            // THIS request's locals.
+            const locals = requestLocals.get(req);
+            const ns = () => (locals?.env as { AGENT?: DurableObjectNamespace } | undefined)?.AGENT;
+            const chat = durableAgentSurface(ns, { agentName, chatPath: manifest.agent.runtime.chat.path });
+            const chatRes = await chat(req);
+            if (chatRes) return chatRes;
+            if (!wantChannels) return null;
+            // Constructed per request — cheap by design: resolveChannel is a
+            // call, and resolveServices memoizes the app services bag per
+            // (env, agentName), exactly for this construction pattern (see
+            // durableChannelSurface's services doc).
+            const channels = durableChannelSurface(ns, {
+              agentName,
+              channels: manifest.agentChannels!,
+              env: locals?.env,
+              services: servicesProvider,
+              waitUntil: locals?.ctx?.waitUntil?.bind(locals.ctx),
+              // The blob resource the agent's Durable Object stores files in, opened from
+              // this isolate's env — the channels read attached files back from it.
+              files: provider
+                ? blobFileStore(async () => {
+                    const blob = (await provider(locals?.env)).blob;
+                    if (!blob) throw new Error(`agent "${agentName}": no blob resource bound in this isolate — attached files can't be read`);
+                    return blob;
+                  })
+                : undefined,
+            });
+            return channels(req);
+          };
         })()
       : undefined;
 
@@ -165,6 +241,7 @@ export function createWorker(
     agentSurface,
     i18n: manifest.i18n,
     routeList: () => routeList,
+    staticBuild: opts.staticBuild,
     earlyHints: manifest.earlyHints,
     htmlCacheControl: manifest.htmlCacheControl,
     notFoundComponent: manifest.notFound,
@@ -172,60 +249,30 @@ export function createWorker(
     resources: provider ? () => provider(currentEnv) : undefined,
     services: servicesProvider ? () => (servicesCache ??= { v: servicesProvider(currentEnv) }).v : undefined,
     resolve: async (pathname): Promise<Resolved | ResolvedResource | null> => {
+      // Fast path: an app/ static page outranks every other route for its path.
       const staticDef = manifest.routes[pathname];
-      if (staticDef) {
-        const b = boundaryFor(pathname);
-        return {
-          def: staticDef,
-          params: {},
-          chain: chainFor(pathname),
-          boundaryIndex: b?.index ?? null,
-          boundaryKey: b?.key ?? null,
-          loading: loadingFor(pathname),
-        };
-      }
-      for (const d of dynamic) {
-        const m = pathname.match(d.regex);
-        if (m) {
-          // Optional segments leave their capture undefined — the param is
-          // then absent, matching the dev matcher's semantics.
-          const params = Object.fromEntries(
-            d.names.flatMap((n, i) => {
-              const v = m[i + 1];
-              return v === undefined ? [] : [[n, decodeURIComponent(v)]];
-            }),
-          );
-          const b = boundaryFor(d.pattern);
-          return {
-            def: d.def,
-            params,
-            chain: chainFor(d.pattern),
-            boundaryIndex: b?.index ?? null,
-            boundaryKey: b?.key ?? null,
-            loading: loadingFor(d.pattern),
-          };
-        }
-      }
-      // Resource routes after pages (so a page is never shadowed by one).
-      for (const r of resources) {
+      if (staticDef && !generated.has(pathname)) return resolvedPage(staticDef, pathname, {});
+      for (const r of table) {
         const m = pathname.match(r.regex);
-        if (m) {
-          const params = Object.fromEntries(
-            r.names.flatMap((n, i) => {
-              const v = m[i + 1];
-              return v === undefined ? [] : [[n, decodeURIComponent(v)]];
-            }),
-          );
-          return { handler: r.handler, params };
-        }
+        if (!m) continue;
+        // Optional segments leave their capture undefined — the param is
+        // then absent, matching the dev matcher's semantics.
+        const params = Object.fromEntries(
+          r.names.flatMap((n, i) => {
+            const v = m[i + 1];
+            return v === undefined ? [] : [[n, decodeURIComponent(v)]];
+          }),
+        );
+        return r.handler ? { handler: r.handler, params } : resolvedPage(r.def, r.pattern, params);
       }
       return null;
     },
   });
 
   return {
-    fetch(request, env) {
-      currentEnv = env;
+    fetch(request, env, ctx) {
+      currentEnv = env; // per-isolate-stable consumers only (resources/services)
+      requestLocals.set(request, { env, ctx }); // per-invocation consumers (agent surface)
       return pipeline.fetch(request);
     },
   };
@@ -234,43 +281,71 @@ export function createWorker(
 // --- the deployed worker's outermost layer (run_worker_first) ---------------
 // Prerendered pages are served as static ASSETS, which bypass the pipeline —
 // so the agent-ready signals the asset layer can't produce get added HERE:
-//   1. `Accept: text/markdown` on a page → the prerendered `.md` asset.
+//   1. a negotiated projection on a page (Accept: text/markdown / application/
+//      json → the prerendered .md / .json asset; else, and for the client
+//      router's fragment, the pipeline — never the page's HTML asset).
 //   2. a `Link` header on every HTML response (RFC 8288/9727 discovery).
 //   3. `x-markdown-tokens` on markdown responses.
 // Static assets are served by the ASSETS binding (no re-render); only genuinely
 // dynamic routes reach the pipeline. With no ASSETS binding (no prerender), this
 // is a transparent pass-through to the pipeline.
 type AssetEnv = { ASSETS?: { fetch(request: Request): Promise<Response> } };
-type FetchPipeline = { fetch(request: Request, env?: unknown): Promise<Response> };
+type FetchPipeline = { fetch(request: Request, env?: unknown, ctx?: WorkerExecutionContext): Promise<Response> };
 
 const estimateTokens = (s: string) => String(Math.ceil(s.length / 4));
 
+// Add Accept to a response's Vary, keeping whatever the asset layer already set.
+function varyAccept(headers: Headers): void {
+  const vary = headers.get("vary");
+  if (!vary) headers.set("vary", "accept");
+  else if (vary.trim() !== "*" && !vary.split(",").some((v) => v.trim().toLowerCase() === "accept")) {
+    headers.set("vary", `${vary}, accept`);
+  }
+}
+
 export function withAssets(
   pipeline: FetchPipeline,
   opts: { link?: string | null } = {},
-): { fetch(request: Request, env?: AssetEnv): Promise<Response> } {
+): { fetch(request: Request, env?: AssetEnv, ctx?: WorkerExecutionContext): Promise<Response> } {
   return {
-    async fetch(request, env) {
+    async fetch(request, env, ctx) {
       const assets = env?.ASSETS;
       const url = new URL(request.url);
       const isPagePath = !/\.[a-z0-9]+$/i.test(url.pathname); // no file extension
-      const accept = request.headers.get("accept") ?? "";
+      // The pipeline's own Accept decision (q-values included). A page path that
+      // negotiates a projection other than the HTML view must get THAT projection
+      // or the pipeline's answer for it — never the prerendered HTML asset.
+      const target = isPagePath ? acceptTarget(request.headers.get("accept") ?? "") : null;
 
-      // 1. Markdown content negotiation on a page path → prerendered .md asset.
-      if (assets && request.method === "GET" && isPagePath && /text\/markdown/.test(accept)) {
-        const base = url.pathname === "/" ? "/index" : url.pathname.replace(/\/+$/, "");
-        const mdUrl = new URL(url);
-        mdUrl.pathname = `${base}.md`;
-        const a = await assets.fetch(new Request(mdUrl.toString(), { headers: request.headers }));
-        if (a.ok) {
-          const body = await a.text();
-          const headers = new Headers(a.headers);
-          headers.set("content-type", "text/markdown; charset=utf-8");
-          headers.set("x-markdown-tokens", estimateTokens(body));
-          if (opts.link) headers.set("link", opts.link);
-          return new Response(body, { status: 200, headers });
+      // 1. Negotiated projections on a page path.
+      if (target && (request.method === "GET" || request.method === "HEAD")) {
+        // md / json → the prerendered <path>.md / <path>.json asset when the build
+        // emitted one (.md unless md = false; .json only for a json() route). Only
+        // the flat file — never <path>/index.*, a distinct /path/index route's twin
+        // (locale homes' <locale>/index.* are a static()-target artifact; this
+        // workers()-only layer never has them).
+        if (assets && request.method === "GET" && (target === "md" || target === "json")) {
+          const base = url.pathname === "/" ? "/index" : url.pathname.replace(/\/+$/, "");
+          const assetUrl = new URL(url);
+          assetUrl.pathname = `${base}.${target}`;
+          const a = await assets.fetch(new Request(assetUrl.toString(), { headers: request.headers }));
+          if (a.ok) {
+            const headers = new Headers(a.headers);
+            if (opts.link) headers.set("link", opts.link);
+            varyAccept(headers);
+            if (target === "json") return new Response(a.body, { status: 200, headers });
+            const body = await a.text();
+            headers.set("content-type", "text/markdown; charset=utf-8");
+            headers.set("x-markdown-tokens", estimateTokens(body));
+            return new Response(body, { status: 200, headers });
+          }
         }
-        // no prerendered .md → fall through; a dynamic route renders it below.
+        // No such asset (or a fragment, or HEAD) → the pipeline (step 3). It renders
+        // a dynamic route's projection, derives .json from the loader data, 404s a
+        // disabled projection, and renders the client router's soft-nav fragment —
+        // the HTML asset is a full DOCUMENT, which the router would morph into its
+        // [data-june-root] as if it were the root's inner HTML.
+        return pipeline.fetch(request, env, ctx);
       }
 
       // 2. Static assets (prerendered HTML/.md/.json, /client.js, hashed CSS)
@@ -287,10 +362,15 @@ export function withAssets(
           // URL changes when the bytes do, so the browser may cache forever and
           // never revalidate (no 304 round-trip, no stale window).
           const immutable = /\.[a-f0-9]{8,}\.(css|js)$/.test(url.pathname);
-          if (addLink || immutable) {
+          // A page path answers HTML here but Markdown under Accept: text/markdown
+          // (step 1) — the same URL, so caches must key on Accept or they hand an
+          // agent the HTML (or a browser the Markdown).
+          const negotiated = isPagePath && ct.includes("text/html");
+          if (addLink || immutable || negotiated) {
             const headers = new Headers(a.headers);
             if (addLink) headers.set("link", opts.link!);
             if (immutable) headers.set("cache-control", "public, max-age=31536000, immutable");
+            if (negotiated) varyAccept(headers);
             return new Response(a.body, { status: a.status, headers });
           }
           return a;
@@ -299,7 +379,7 @@ export function withAssets(
 
       // 3. Dynamic routes → the render pipeline (already sets Link + negotiates).
       // Env flows through so the pipeline's resources get the D1/KV/R2 bindings.
-      return pipeline.fetch(request, env);
+      return pipeline.fetch(request, env, ctx);
     },
   };
 }