@nanobpm/urban 0.76.0 → 0.77.1

package/src/runtime/core/modules/surfaces.test.ts

@@ -4,9 +4,10 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { mountSurfaces } from "./surfaces.ts";
-import type { EngineClient, HostContext, HttpRequest, HttpResponse } from "../host.ts";
+import type { EngineClient, HostContext, HttpResponse } from "../host.ts";
 import { DataLayer } from "./datasource.ts";
 import { createLogger } from "../logger.ts";
+import type { Route } from "../router.ts";
 
 function ctxWith(surfaces: Record<string, unknown>): Parameters<typeof mountSurfaces>[0] {
   const host: HostContext = {
@@ -63,7 +64,7 @@ const fakeApp: Parameters<typeof mountSurfaces>[1] = {
   log: createLogger(() => {}),
 };
 
-async function render(route: { handler: (req: HttpRequest) => HttpResponse | Promise<HttpResponse> }): Promise<string> {
+async function render(route: Route): Promise<string> {
   const res = await route.handler({
     method: "GET",
     path: "/",
@@ -71,6 +72,7 @@ async function render(route: { handler: (req: HttpRequest) => HttpResponse | Pro
     headers: new Headers(),
     text: async () => "",
   });
+  assert.ok(res, "handler should not decline");
   return String(res.body);
 }
 
@@ -118,16 +120,18 @@ function appWith(engine: EngineClient): Parameters<typeof mountSurfaces>[1] {
 
 /** Invoke a route handler with an optional query string and POST body. */
 async function call(
-  route: { handler: (req: HttpRequest) => HttpResponse | Promise<HttpResponse> },
+  route: Route,
   opts: { method?: string; query?: string; body?: string } = {},
 ): Promise<HttpResponse> {
-  return route.handler({
+  const res = await route.handler({
     method: opts.method ?? "GET",
     path: "/",
     query: new URLSearchParams(opts.query ?? ""),
     headers: new Headers(),
     text: async () => opts.body ?? "",
   });
+  assert.ok(res, "handler should not decline");
+  return res;
 }
 
 function inboxRoutes(engine: EngineClient) {

package/src/runtime/core/router.ts

@@ -4,12 +4,25 @@
 
 import type { HttpHandler, HttpRequest, HttpResponse } from "./host.ts";
 
+/**
+ * A route handler that may DECLINE a matched request by returning `undefined`
+ * (or a promise of it). The router then treats the route as if it had not matched
+ * and continues to the next route (fall-through). This lets a broad prefix route —
+ * e.g. the pages surface's nested static serve at `/` — claim only the requests it
+ * can actually satisfy (a real, safe asset) and let everything else (`/healthz`, an
+ * app's own trigger routes registered *after* it) resolve to their own handlers,
+ * instead of a root catch-all silently swallowing them. A handler that returns a
+ * concrete `HttpResponse` (including a 404) still short-circuits as before, so this
+ * is backwards-compatible with every existing handler (none return `undefined`).
+ */
+export type RouteHandler = (req: HttpRequest) => Promise<HttpResponse | undefined> | HttpResponse | undefined;
+
 export interface Route {
   method: string;
   path: string;
   /** When true, match any path that starts with `path`. */
   prefix?: boolean;
-  handler: HttpHandler;
+  handler: RouteHandler;
   /** For diagnostics / inspect(). */
   source?: string;
 }
@@ -61,7 +74,13 @@ function matches(route: Route, req: HttpRequest): boolean {
 export function makeRouter(routes: Route[]): HttpHandler {
   return async (req: HttpRequest): Promise<HttpResponse> => {
     for (const route of routes) {
-      if (matches(route, req)) return route.handler(req);
+      if (matches(route, req)) {
+        // A handler may DECLINE by returning `undefined` (see RouteHandler): treat the
+        // route as unmatched and keep looking, so a broad prefix serve can't shadow a
+        // later exact route (`/healthz`, a trigger) it didn't actually satisfy.
+        const res = await route.handler(req);
+        if (res !== undefined) return res;
+      }
     }
     return text("not found", 404);
   };