@astrale-os/sdk 0.1.6 → 0.1.7

package/src/server/worker-entry.ts

@@ -6,11 +6,13 @@
  *   • resolve the serving URL (== `iss`), canonicalize it (so the value matches
  *     what `createRemoteServer` signs with and the kernel pins), and cache the
  *     built app per distinct URL;
- *   • optional self-binding routing: when a `SELF` service binding is provided,
- *     route same-host subrequests (e.g. `ctx.callRemote` back into this domain)
- *     through it — Cloudflare forbids a Worker fetching its own hostname. This is
- *     the ONLY reason a `globalThis.fetch` override is installed, and only when a
- *     `selfBinding` is configured;
+ *   • optional subrequest routing: a `globalThis.fetch` override (installed ONLY
+ *     when `selfBinding` and/or `routeSubrequest` is configured) redirects
+ *     certain outbound fetches through a caller-supplied binding — `selfBinding`
+ *     for same-host fetches (a Worker can't fetch its own hostname), and the
+ *     vendor-neutral `routeSubrequest` for any caller policy (e.g. instance
+ *     hostnames a same-zone Worker→Worker fetch would 522 on). The SDK names no
+ *     backend or topology; the caller owns the predicate + the fetcher;
  *   • optional SPA hook (e.g. `/ui/*` served from an `ASSETS` binding).
  *
  * The worker's OWN JWKS (`<url>/.well-known/jwks.json`) is served as a normal
@@ -49,6 +51,17 @@ export interface WorkerEntryConfig<TDeps> {
   resolveUrl?: (env: TDeps, requestOrigin: string) => string
   /** Optional: the `SELF` service binding used to route same-host subrequests. */
   selfBinding?: (env: TDeps) => Fetcher | null | undefined
+  /**
+   * Optional, vendor-neutral: route an OUTBOUND subrequest through a
+   * caller-supplied fetcher instead of the network — for hosts a Worker can't
+   * reach directly over the edge (e.g. a platform router on the SAME zone:
+   * Cloudflare 522s a same-zone Worker→Worker public `fetch`). Return a `Fetcher`
+   * to route the request through, or null/undefined to fall through to the normal
+   * fetch. The SDK names no backend or topology — the CALLER owns BOTH the
+   * predicate (which hosts) and the fetcher (the binding). This generalizes
+   * `selfBinding` (same-origin → SELF) to any caller policy; both are honored.
+   */
+  routeSubrequest?: (url: URL, env: TDeps) => Fetcher | null | undefined
   /**
    * Optional: handle a request before it reaches the kernel app — e.g. serve a
    * SPA under `/ui/*` or a same-origin `/api/*` endpoint the view calls. Return
@@ -91,6 +104,46 @@ export function clientOrigin(url: URL, request: Request): string {
   return scheme === 'https' ? `https://${url.host}` : url.origin
 }
 
+/**
+ * Build a `before` hook that serves a static-asset `binding` (e.g. a Workers
+ * Assets binding) mounted under `base` (default `/ui`) — the runtime half of a
+ * domain's `client` binding. Returns `undefined` for non-matching paths (and
+ * when no binding is present) so the request falls through to domain dispatch.
+ *
+ * Asset URLs are rooted at `base` (a client bundler sets `base: '<base>/'`);
+ * this hook strips that prefix before delegating to the binding, so
+ * `<base>/x.js` resolves from the binding's root. When `devProxy` yields a URL
+ * (local dev), requests are proxied there instead — the seam for a bundler's
+ * HMR dev server. Whether unknown sub-paths fall back to `index.html` is the
+ * binding's own concern (e.g. wrangler's `not_found_handling`), not baked in
+ * here.
+ *
+ * Lives here, type-checked and testable, instead of being emitted as a string
+ * by every adapter's worker codegen.
+ */
+export function assets<TDeps>(opts: {
+  base?: string
+  binding: (env: TDeps) => Fetcher | null | undefined
+  devProxy?: (env: TDeps) => string | null | undefined
+}): (env: TDeps, url: URL, request: Request) => Response | Promise<Response> | undefined {
+  const base = (opts.base ?? '/ui').replace(/\/+$/, '')
+  const prefix = `${base}/`
+  return (env, url, request) => {
+    const binding = opts.binding(env)
+    if (!binding) return undefined
+    if (url.pathname !== base && !url.pathname.startsWith(prefix)) return undefined
+    const devUrl = opts.devProxy?.(env)
+    if (devUrl) {
+      const devBase = devUrl.replace(/\/+$/, '')
+      return fetch(new Request(`${devBase}${url.pathname}${url.search}`, request))
+    }
+    // `<base>` → `/`, `<base>/x` → `/x`: serve from the binding's root.
+    const stripped = url.pathname.slice(base.length) || '/'
+    const rewritten = new URL(stripped + url.search, url.origin)
+    return binding.fetch(new Request(rewritten, request))
+  }
+}
+
 export function createWorkerEntry<TDeps>(config: WorkerEntryConfig<TDeps>): WorkerEntry<TDeps> {
   // Cache the built app per distinct resolved URL — plural and bounded. On the
   // request-origin fallback the URL legitimately alternates for one worker
@@ -101,6 +154,7 @@ export function createWorkerEntry<TDeps>(config: WorkerEntryConfig<TDeps>): Work
   const MAX_CACHED_APPS = 4
   const apps = new Map<string, { origin: string; app: App }>()
   let self: Fetcher | null = null
+  let routeEnv: TDeps | null = null
 
   function getApp(url: string, env: TDeps): App {
     const cached = apps.get(url)
@@ -114,26 +168,31 @@ export function createWorkerEntry<TDeps>(config: WorkerEntryConfig<TDeps>): Work
     return app
   }
 
-  // A Worker can't fetch its own hostname. When a SELF service binding is
-  // configured, route same-host subrequests (e.g. `ctx.callRemote` back into
-  // this domain) through it. This is the only reason to override
-  // `globalThis.fetch` — workers without a `selfBinding` get no global mutation.
-  // (A self-issued credential's JWKS is resolved in-memory by the verifier, not
-  // fetched — see `auth/verify.ts` — so no self-JWKS interception is needed.)
-  if (config.selfBinding) {
+  // A Worker can't fetch its own hostname (SELF), nor — on Cloudflare — a
+  // same-zone hostname routed to another Worker (the `routeSubrequest` case).
+  // When either is configured, override `globalThis.fetch` to redirect those
+  // subrequests through the caller's fetcher. Workers with neither get no global
+  // mutation. (A self-issued credential's JWKS is resolved in-memory by the
+  // verifier, not fetched — see `auth/verify.ts` — so no self-JWKS shim is needed.)
+  if (config.selfBinding || config.routeSubrequest) {
     const originalFetch = globalThis.fetch
     globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
-      if (apps.size > 0 && self) {
-        const href =
-          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
-        try {
-          const origin = new URL(href).origin
+      const href = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+      try {
+        const u = new URL(href)
+        // same-origin → SELF (a Worker can't fetch its own hostname)
+        if (self && apps.size > 0) {
           for (const cached of apps.values()) {
-            if (cached.origin === origin) return self.fetch(new Request(input, init))
+            if (cached.origin === u.origin) return self.fetch(new Request(input, init))
           }
-        } catch {
-          // non-absolute URL — fall through to the original fetch
         }
+        // caller policy → its fetcher (e.g. a platform router on the same zone)
+        if (config.routeSubrequest && routeEnv) {
+          const via = config.routeSubrequest(u, routeEnv)
+          if (via) return via.fetch(new Request(input, init))
+        }
+      } catch {
+        // non-absolute URL — fall through to the original fetch
       }
       return originalFetch(input, init)
     }) as typeof fetch
@@ -142,6 +201,7 @@ export function createWorkerEntry<TDeps>(config: WorkerEntryConfig<TDeps>): Work
   return {
     async fetch(request: Request, env: TDeps): Promise<Response> {
       if (config.selfBinding) self ??= config.selfBinding(env) ?? null
+      if (config.routeSubrequest) routeEnv = env
       // Only parse the request URL when a hook actually needs it.
       const requestUrl = config.before || config.resolveUrl ? new URL(request.url) : null
       if (config.before && requestUrl) {