@astrale-os/sdk 0.1.5 → 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
@@ -40,10 +42,26 @@ export interface WorkerEntryConfig<TDeps> {
    * Resolve the raw serving URL from `env` (+ the per-request origin, for workers
    * that fall back to the request host). Defaults to the `WORKER_URL` env var.
    * The result is always canonicalized before use.
+   *
+   * The `requestOrigin` honors an `X-Forwarded-Proto: https` upgrade (see
+   * `clientOrigin`), so a dev worker behind a TLS-terminating proxy (cloudflared
+   * tunnel, reverse proxy) resolves its public `https://` origin, not the raw
+   * `http://` one workerd sees.
    */
   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
@@ -67,34 +85,114 @@ export interface WorkerEntry<TDeps> {
   fetch(request: Request, env: TDeps): Response | Promise<Response>
 }
 
+/**
+ * The request origin as the CLIENT reached it — i.e. the origin a fallback
+ * serving URL (and therefore the `iss`) may be derived from. Behind a
+ * TLS-terminating proxy (a cloudflared tunnel in front of `wrangler dev`, any
+ * reverse proxy) the worker sees plain HTTP, so `request.url` says `http://…`
+ * while the public URL is `https://…`; the proxy advertises the original
+ * scheme via `X-Forwarded-Proto`. Honoring it is restricted to the http→https
+ * UPGRADE of the SAME host (never a downgrade, never a host change), so a
+ * spoofed header can at worst derive an `iss` the kernel's JWKS check then
+ * fails — it can never make this worker speak for another origin.
+ */
+export function clientOrigin(url: URL, request: Request): string {
+  if (url.protocol !== 'http:') return url.origin
+  const forwarded = request.headers.get('x-forwarded-proto')
+  // Multiple proxies append: "https, http" — the first hop is the client-facing one.
+  const scheme = forwarded?.split(',')[0]?.trim().toLowerCase()
+  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> {
-  let cache: { url: string; origin: string; app: App } | null = null
+  // Cache the built app per distinct resolved URL — plural and bounded. On the
+  // request-origin fallback the URL legitimately alternates for one worker
+  // (direct http hits vs https-upgraded tunnel hits, workers.dev + custom
+  // domain), and a single slot would tear down and rebuild the whole app on
+  // 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 }>()
   let self: Fetcher | null = null
+  let routeEnv: TDeps | null = null
 
   function getApp(url: string, env: TDeps): App {
-    if (cache && cache.url === url) return cache.app
+    const cached = apps.get(url)
+    if (cached) return cached.app
     const { app } = createRemoteServer<TDeps>(config.build(url, env))
-    cache = { url, origin: new URL(url).origin, app }
+    if (apps.size >= MAX_CACHED_APPS) {
+      const oldest = apps.keys().next().value
+      if (oldest !== undefined) apps.delete(oldest)
+    }
+    apps.set(url, { origin: new URL(url).origin, app })
     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 (cache && self) {
-        const href =
-          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
-        try {
-          if (new URL(href).origin === cache.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 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 === u.origin) return self.fetch(new Request(input, init))
+          }
+        }
+        // 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
@@ -103,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) {
@@ -112,7 +211,7 @@ export function createWorkerEntry<TDeps>(config: WorkerEntryConfig<TDeps>): Work
         if (handled !== undefined) return handled
       }
       const raw = config.resolveUrl
-        ? config.resolveUrl(env, requestUrl!.origin)
+        ? config.resolveUrl(env, clientOrigin(requestUrl!, request))
         : requireEnv(env, 'WORKER_URL', "the worker's public serving URL (its iss identity)")
       const url = canonicalizeServingUrl(raw)
       const dispatched = config.rewriteRequest ? config.rewriteRequest(env, request) : request