@astrale-os/sdk 0.1.6 → 0.1.8

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
@@ -29,6 +31,54 @@ import { canonicalizeServingUrl } from './serving-url'
 type Fetcher = { fetch(request: Request): Response | Promise<Response> }
 type App = { fetch(request: Request): Response | Promise<Response> }
 
+/** A built app cached by its serving URL: `origin` for same-origin matching,
+ * `app` for in-process self-dispatch. */
+type CachedApp = { origin: string; app: App }
+
+/**
+ * Choose where an OUTBOUND subrequest to `u` is routed — or `null` to let the
+ * real `fetch` handle it. Order matters and same-origin wins FIRST: a call to
+ * this worker's OWN serving origin is a self-dispatch, not an edge fetch — and
+ * the caller's `routeSubrequest` policy may itself match our own host (e.g. an
+ * `isInstanceHost` predicate matches every `*.svc.astrale.ai`, ours included),
+ * so it must never get first look at a same-origin call.
+ *
+ *   • same-origin + SELF binding present → the SELF fetcher: a fresh same-script
+ *     invocation. The normal Cloudflare path — a Worker can't fetch its own
+ *     hostname over the edge, so it re-enters itself through the binding.
+ *   • same-origin + NO SELF binding → the cached app, dispatched IN-PROCESS. A
+ *     Workers-for-Platforms dispatch-namespace tenant can't service-bind to
+ *     itself (its script name is platform-renamed), so it has no SELF binding; an
+ *     in-process dispatch reaches the same script with no edge hop and no binding.
+ *     `App` and the SELF `Fetcher` share the `{ fetch(request) }` shape, so the
+ *     caller drives both identically.
+ *   • else, the caller's `routeSubrequest` policy matched → its fetcher.
+ *   • else → `null`: passthrough to the real network fetch.
+ *
+ * Pure (no closure over instance state) so the routing decision is unit-testable
+ * without standing up a real app.
+ */
+export function selectSubrequestTarget<TDeps>(
+  u: URL,
+  ctx: {
+    self: Fetcher | null
+    apps: Iterable<CachedApp>
+    routeEnv: TDeps | null
+    routeSubrequest?: (url: URL, env: TDeps) => Fetcher | null | undefined
+  },
+): { fetch(request: Request): Response | Promise<Response> } | null {
+  // Same-origin self-subrequest → the same script (SELF binding, else in-process).
+  for (const cached of ctx.apps) {
+    if (cached.origin === u.origin) return ctx.self ?? cached.app
+  }
+  // Caller policy (e.g. a platform router on the same zone) → its fetcher.
+  if (ctx.routeSubrequest && ctx.routeEnv) {
+    const via = ctx.routeSubrequest(u, ctx.routeEnv)
+    if (via) return via
+  }
+  return null
+}
+
 export interface WorkerEntryConfig<TDeps> {
   /**
    * Build the `createRemoteServer` config for the resolved serving `url`. Called
@@ -49,6 +99,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 +152,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
@@ -99,8 +200,9 @@ export function createWorkerEntry<TDeps>(config: WorkerEntryConfig<TDeps>): Work
   // every alternation. The bound caps abuse via attacker-minted Host /
   // X-Forwarded-Proto values on that same fallback path.
   const MAX_CACHED_APPS = 4
-  const apps = new Map<string, { origin: string; app: App }>()
+  const apps = new Map<string, CachedApp>()
   let self: Fetcher | null = null
+  let routeEnv: TDeps | null = null
 
   function getApp(url: string, env: TDeps): App {
     const cached = apps.get(url)
@@ -114,26 +216,27 @@ 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 over the edge, 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 right target (see `selectSubrequestTarget`). Workers
+  // with neither selfBinding nor routeSubrequest 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
-          for (const cached of apps.values()) {
-            if (cached.origin === origin) return self.fetch(new Request(input, init))
-          }
-        } catch {
-          // non-absolute URL — fall through to the original fetch
-        }
+      const href = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+      try {
+        const target = selectSubrequestTarget(new URL(href), {
+          self,
+          apps: apps.values(),
+          routeEnv,
+          routeSubrequest: config.routeSubrequest,
+        })
+        if (target) return target.fetch(new Request(input, init))
+      } catch {
+        // non-absolute URL — fall through to the original fetch
       }
       return originalFetch(input, init)
     }) as typeof fetch
@@ -142,6 +245,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) {