@rhythmjs/router 0.0.11 → 0.0.12

package/README.md

@@ -1,17 +1,17 @@
 # @rhythmjs/router
 
-Web-standard HTTP routing on top of `@rhythmjs/rhythm`. `RhythmRouter` matches routes with [rou3](https://github.com/h3js/rou3), the router that powers h3 (a static segment always wins over a `:param` segment, regardless of registration order), supports prefixes and nested routers, and mounts flat into a parent `Rhythm` app via `.use(router.middleware())`, so an unmatched request correctly falls through to whatever's registered after it.
+The HTTP layer of Rhythm, the Bun-native backend framework: web-standard (`Request`/`Response`) routing on top of the `@rhythmjs/rhythm` kernel, served on `Bun.serve`. `RhythmRouter` matches routes with [rou3](https://github.com/h3js/rou3), the router that powers h3 (a static segment always wins over a `:param` segment, regardless of registration order), supports prefixes and nested routers, and mounts flat into a parent `Rhythm` app via `.use(router.middleware())`, so an unmatched request correctly falls through to whatever's registered after it.
 
 Route patterns follow rou3's conventions: `:name` params (`:name?` optional, `:id(\\d+)` regex-constrained), `*` for one unnamed segment (captured as `params["0"]`), and `**` for the rest of the path (`params._`, or `params.name` with `**:name`). Param values are the raw path segments, undecoded.
 
-`RhythmRouter` is not an app and does not extend `Rhythm` — it is a controller that compiles routes and middleware down to a single middleware (`.middleware()`). It shares the core middleware contract (`compose`, `Middleware`, `next(extra)`), but has no `provide()` or `register()`, and it can't be served on its own: a `Rhythm` app is always the host that owns the lifecycle and the adapters.
+`RhythmRouter` is not an app and does not extend `Rhythm`; it is a controller that compiles routes and middleware down to a single middleware (`.middleware()`). It shares the core middleware contract (`compose`, `Middleware`, `next(extra)`), but has no `provide()` or `register()`, and it can't be served on its own: a `Rhythm` app is always the host that owns the lifecycle and the adapters.
 
 ## Example
 
 ```ts
 import { Rhythm } from "@rhythmjs/rhythm";
 import { RhythmRouter } from "@rhythmjs/router";
-import { serve } from "@rhythmjs/router/serve";
+import { toFetchHandler } from "@rhythmjs/router/fetch";
 import type { RhythmHttpContext } from "@rhythmjs/router/context";
 
 const usersRouter = new RhythmRouter({ prefix: "/users" }).get("/:id", (ctx) => {
@@ -19,77 +19,80 @@ const usersRouter = new RhythmRouter({ prefix: "/users" }).get("/:id", (ctx) =>
 });
 
 const app = new Rhythm<RhythmHttpContext>().use(usersRouter.middleware());
-serve(app, { port: 3000 });
+Bun.serve({ port: 3000, fetch: toFetchHandler(app) });
 ```
 
 A fuller runnable version, including nested prefixes and a fallback route, is at [`examples/router`](../../examples/router).
 
 ## Concepts
 
-- **`ctx.response`** is a plain mutable object (`status`, `statusText`, `headers`, `body`) — set it directly rather than constructing a `Response` yourself. The adapter converts it to a real `Response` at the end.
-- **Response helpers** — `ctx.json(data, status?)`, `ctx.text(body, status?)`, `ctx.html(body, status?)`, `ctx.error(status, message?)`, and `ctx.redirect(url, status = 302)` set the content type, body, and status on `ctx.response` in one call. `error()` defaults the message from the status code (`ctx.error(404)` → `"Not Found"`). They're sugar over `ctx.response`, so mixing both styles is fine, and later writes win.
-- **`ctx.params`** — captured `:name` path segments, added once a route matches.
-- **Nesting is `.use(child.middleware())`** — a router mounts into another router (or into the app) as a compiled middleware. The mount is opaque, so the parent's prefix is **not** applied to the child's routes: the child carries its own absolute prefix (`new RhythmRouter({ prefix: "/api/users" })`). On a miss the child falls through to `next()`, so the parent's later middleware and routes still run, and the child keeps working standalone.
-- **Registration order is execution order** — a `.use()` middleware wraps only the routes registered after it; routes registered before it are untouched, and a matched route that doesn't call `next()` returns without reaching anything registered later. Consecutive routes share one rou3 lookup; an unmatched request falls through, entry by entry, to the outer `next()`.
-- **A router is a controller, not a module** — it has no `provide()` or `register()`, and it cannot be `register()`ed into a `Rhythm` app either; `register()` composes `Rhythm` modules only. A router mounts into an app exactly one way: koa-style, via `.use(router.middleware())`.
+- **`ctx.response`** is a plain mutable object (`status`, `statusText`, `headers`, `body`): set it directly rather than constructing a `Response` yourself. The adapter converts it to a real `Response` at the end.
+- **Response helpers**: `ctx.json(data, status?)`, `ctx.text(body, status?)`, `ctx.html(body, status?)`, `ctx.error(status, message?)`, and `ctx.redirect(url, status = 302)` set the content type, body, and status on `ctx.response` in one call. `error()` defaults the message from the status code (`ctx.error(404)` → `"Not Found"`). They're sugar over `ctx.response`, so mixing both styles is fine, and later writes win.
+- **`ctx.params`**: captured `:name` path segments, added once a route matches.
+- **Nesting is `.use(child.middleware())`**: a router mounts into another router (or into the app) as a compiled middleware. The mount is opaque, so the parent's prefix is **not** applied to the child's routes: the child carries its own absolute prefix (`new RhythmRouter({ prefix: "/api/users" })`). On a miss the child falls through to `next()`, so the parent's later middleware and routes still run, and the child keeps working standalone.
+- **Registration order is execution order**: a `.use()` middleware wraps only the routes registered after it; routes registered before it are untouched, and a matched route that doesn't call `next()` returns without reaching anything registered later. Consecutive routes share one rou3 lookup; an unmatched request falls through, entry by entry, to the outer `next()`.
+- **A router is a controller, not a module**: it has no `provide()` or `register()`, and it cannot be `register()`ed into a `Rhythm` app either; `register()` composes `Rhythm` modules only. A router mounts into an app exactly one way: koa-style, via `.use(router.middleware())`.
 
 ## API
 
-- `new RhythmRouter(options?)` — `options.prefix`.
-- `.get/.post/.put/.patch/.delete(path, ...handlers)` — register a route; `path` may contain `:param` segments.
-- `.use(fn)` — plain middleware; it takes only functions, so a nested router mounts as `.use(child.middleware())`.
-- `.middleware()` — this router compiled to a plain middleware: the one form that mounts anywhere, into a `Rhythm` app or into another router. Because the compiled form is opaque, the mounting router's prefix is not applied to it — give the child its full prefix.
-- `ctx.json/.text/.html(body, status?)`, `ctx.error(status, message?)`, `ctx.redirect(url, status?)` — response helpers built into the context (`createHttpContext` in `@rhythmjs/router/context`).
-- `toFetchHandler(app)` — bridges a `Rhythm` app to a Web-standard `(Request) => Promise<Response>` handler.
+- `new RhythmRouter(options?)`: `options.prefix`.
+- `.get/.post/.put/.patch/.delete(path, ...handlers)`: register a route; `path` may contain `:param` segments.
+- `.use(fn)`: plain middleware; it takes only functions, so a nested router mounts as `.use(child.middleware())`.
+- `.middleware()`: this router compiled to a plain middleware: the one form that mounts anywhere, into a `Rhythm` app or into another router. Because the compiled form is opaque, the mounting router's prefix is not applied to it, so give the child its full prefix.
+- `ctx.json/.text/.html(body, status?)`, `ctx.error(status, message?)`, `ctx.redirect(url, status?)`: response helpers built into the context (`createHttpContext` in `@rhythmjs/router/context`).
+- `toFetchHandler(app)`: bridges a `Rhythm` app to a Web-standard `(Request) => Promise<Response>` handler.
 
-## Serving
+## Serving: your Bun.serve, no wrapper
 
-Two primitives turn an app into a server, both coupled to [Bun](https://bun.com) on purpose:
+There is no `serve()` helper and no static-file helper. You write `Bun.serve` in your own `main.ts`, and the package gives you exactly two plain pieces for its `fetch`:
 
-- **`serve(app, options)`** (`@rhythmjs/router/serve`) — starts the app on `Bun.serve` and returns Bun's `Server` (`server.port`, `server.url`, `server.publish`, `server.stop()`).
-- **`toFetchHandler(app)`** (`@rhythmjs/router/fetch`) — the raw `(Request) => Promise<Response>` handler, for composing and testing without a listener.
+- **`toFetchHandler(app)`** (`@rhythmjs/router/fetch`): the app as a `(Request) => Promise<Response>` handler.
+- **`errorToResponse(error)`** (`@rhythmjs/router/fetch`): maps a thrown error to a Response: the error's own `status`/`statusCode` when set, else a logged `500`.
 
-`serve()` passes the server fields through to `Bun.serve` — `port`, `hostname`, `unix`, `tls`, `reusePort`, `idleTimeout`, `development`, `maxRequestBodySize` (an over-limit body is rejected without crashing) — plus the extension points below. Every request gets a lazy `request.ip` (from `server.requestIP()`), the field `@rhythmjs/security`'s rate limit and `@rhythmjs/http`'s proxy key off. Errors thrown in the middleware chain are answered with `500` (or the error's own `status`) without crashing the process; override the mapping with `options.error`.
+Everything wired, explicitly:
 
-### Static assets
+```ts
+import { toFetchHandler, errorToResponse } from "@rhythmjs/router/fetch";
 
-The `static` option serves files with `Bun.file` before the app runs; a request no folder answers falls through to your routes. It takes one folder config or an array — folders are probed in order, first match wins:
+const handler = toFetchHandler(app);
 
-```ts
-serve(app, {
+const server = Bun.serve({
   port: 3000,
-  static: [{ dir: "dist/client", maxAge: 31536000, immutable: true }, { dir: "public" }],
+  async fetch(request, srv) {
+    // Optional: expose the client address as request.ip, the field
+    // @rhythmjs/security's rate limit and @rhythmjs/http's proxy key off.
+    Object.defineProperty(request, "ip", {
+      configurable: true,
+      get: () => srv.requestIP(request)?.address,
+    });
+    try {
+      return await handler(request);
+    } catch (error) {
+      return errorToResponse(error);
+    }
+  },
 });
 ```
 
-Each entry (`StaticMiddlewareOptions`, also exported from `@rhythmjs/router/static`) takes `dir`, `prefix` (mount point, default the site root), `index` (default `index.html`, served for directory paths), `maxAge`/`immutable` cache control, and `ETag` revalidation with `304`s (`etag`, on by default). Content types come from `Bun.file`. Path traversal is normalized away. `middleware` you pass runs before and wraps the static handlers, so CORS or logging cover asset responses too.
-
-### Extending: CORS, WebSockets, and similar
-
-- **`middleware`** — serve middlewares (`(request, next) => Response`) run around the whole app, the natural place for CORS, logging, or auth gates:
+Since `Bun.serve` is yours, all of Bun's server options (`port`, `hostname`, `unix`, `tls`, `idleTimeout`, `maxRequestBodySize`, `reusePort`, `development`, …) and the `Server` itself (`server.url`, `server.publish`, `server.stop()`) are used directly; nothing is proxied or renamed.
 
-  ```ts
-  serve(app, {
-    middleware: [
-      async (request, next) => {
-        if (request.method === "OPTIONS")
-          return new Response(null, { status: 204, headers: { "access-control-allow-origin": "*" } });
-        const response = await next();
-        response.headers.set("access-control-allow-origin", "*");
-        return response;
-      },
-    ],
-  });
-  ```
+### Static files
 
-- **`upgrade` + `websocket`** — the seams for Bun's native WebSockets, shaped for [`@rhythmjs/ws`](https://github.com/rhythmjs/ws). Requests with an `upgrade: websocket` header divert to `upgrade(request, server)` before the app runs (return a `Response` to reject, or `undefined` after `server.upgrade()`); `websocket` is Bun's behavior object, passed through:
+Use Bun's built-in `routes`; there is nothing to import:
 
-  ```ts
-  import { websocket } from "@rhythmjs/ws";
+```ts
+const server = Bun.serve({
+  routes: {
+    "/": new Response(Bun.file("public/index.html")), // one known file
+    "/static/*": { dir: "./public" }, // a whole folder
+  },
+  fetch: toFetchHandler(app), // everything else is the app
+});
+```
 
-  serve(app, { upgrade: ws.upgrade, websocket: websocket() });
-  ```
+Directory routes (`{ dir }`, path must end in `/*`) come with content types, `Last-Modified` + weak `ETag` with `304` revalidation, `Range` requests, `index.html` for trailing-slash requests (and a `301` to add the slash), and `404` for missing or non-canonical (traversal) paths.
 
-- **`error`** — replace the default error-to-response mapping.
+> **Warning: never mount a directory at `"/*"`.** A directory route answers its own `404`s: with `"/*": { dir }`, every URL that isn't a file dies there and your app's `fetch` never runs. Keep folders on dedicated prefixes (`/static/*`, `/assets/*`) and let `fetch` stay the app's. For root-level files (favicon, robots.txt), map each one explicitly: `"/favicon.svg": new Response(Bun.file("public/favicon.svg"))`.
+### WebSockets
 
-Anything else fetch-shaped composes with the raw primitive: `toFetchHandler(app)` from `@rhythmjs/router/fetch`.
+[`@rhythmjs/ws`](https://github.com/rhythmjs/ws) plugs into the same hand-wired `fetch`: its `upgrade()` returns `null` synchronously for non-websocket requests, so it composes as `ws.upgrade(request, srv) ?? handler(request)`, with `websocket: ws.websocket` on the same `Bun.serve` call.

package/dist/fetch.d.ts

@@ -1,3 +1,4 @@
 import type { Rhythm } from "@rhythmjs/rhythm";
 import { type RhythmHttpContext } from "./context";
 export declare function toFetchHandler<TContext extends RhythmHttpContext, TProviders extends object = {}>(app: Rhythm<RhythmHttpContext, TContext, TProviders>): (request: Request) => Promise<Response>;
+export declare function errorToResponse(error: unknown): Response;

package/dist/fetch.js

@@ -1,8 +1,32 @@
 // @bun
 import {
-  toFetchHandler2
-} from "./rhythm-router-88dtq5mx.js";
-import"./rhythm-router-yj4ffyyg.js";
+  createHttpContext2
+} from "./rhythm-router-yj4ffyyg.js";
+
+// src/fetch.ts
+function toFetchHandler(app) {
+  const run = app.callback();
+  return async (request) => {
+    const ctx = await run(createHttpContext2(request));
+    const response = ctx.response;
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
+  };
+}
+function errorToResponse(error) {
+  const status = error.status ?? error.statusCode ?? 500;
+  const message = status >= 500 ? "Internal Server Error" : error instanceof Error ? error.message : String(error);
+  if (status >= 500)
+    console.error(error);
+  return new Response(message, {
+    status,
+    headers: { "content-type": "text/plain; charset=utf-8" }
+  });
+}
 export {
-  toFetchHandler2 as toFetchHandler
+  errorToResponse,
+  toFetchHandler
 };

package/dist/static.d.ts

@@ -1,10 +1,13 @@
-import type { ServeMiddleware } from "./serve";
-export interface StaticMiddlewareOptions {
+export interface ServeStaticOptions {
     dir: string;
+    /** URL mount point (default the site root). */
     prefix?: string;
+    /** Directory index filename served for trailing-slash requests (default "index.html"). */
     index?: string;
+    /** Emit `Cache-Control: max-age=<n>`, with ", immutable" appended when `immutable` is set. */
     maxAge?: number;
     immutable?: boolean;
-    etag?: boolean;
 }
-export declare function staticMiddleware(options: StaticMiddlewareOptions): ServeMiddleware;
+/** A Response for a hit, null for a miss — chain with `??` into your app handler. */
+export type StaticHandler = (request: Request) => Promise<Response | null>;
+export declare function serveStatic(options: ServeStaticOptions): StaticHandler;

package/dist/static.js

@@ -1,7 +1,67 @@
 // @bun
-import {
-  staticMiddleware2
-} from "./rhythm-router-n08cmxbj.js";
+// src/static.ts
+import { join, normalize, sep } from "path";
+function normalizePrefix(prefix) {
+  const withLeading = prefix.startsWith("/") ? prefix : `/${prefix}`;
+  return withLeading.endsWith("/") ? withLeading.slice(0, -1) : withLeading;
+}
+function serveStatic(options) {
+  const prefix = normalizePrefix(options.prefix ?? "/");
+  const index = options.index ?? "index.html";
+  const cacheControl = options.maxAge === undefined ? undefined : `max-age=${options.maxAge}${options.immutable ? ", immutable" : ""}`;
+  return async (request) => {
+    if (request.method !== "GET" && request.method !== "HEAD")
+      return null;
+    let pathname;
+    try {
+      pathname = decodeURIComponent(new URL(request.url).pathname);
+    } catch {
+      return null;
+    }
+    if (prefix !== "" && pathname !== prefix && !pathname.startsWith(`${prefix}/`))
+      return null;
+    const relative = normalize(pathname.slice(prefix.length));
+    if (relative.includes("\x00") || relative === ".." || relative.startsWith(`..${sep}`))
+      return null;
+    const path = pathname.endsWith("/") ? join(options.dir, relative, index) : join(options.dir, relative);
+    const file = Bun.file(path);
+    if (!await file.exists())
+      return null;
+    const size = file.size;
+    const mtime = Math.floor(file.lastModified);
+    const etag = `W/"${size.toString(16)}-${mtime.toString(16)}"`;
+    const headers = new Headers({
+      etag,
+      "last-modified": new Date(mtime).toUTCString(),
+      "accept-ranges": "bytes"
+    });
+    if (cacheControl !== undefined)
+      headers.set("cache-control", cacheControl);
+    const ifNoneMatch = request.headers.get("if-none-match");
+    if (ifNoneMatch !== null) {
+      if (ifNoneMatch.split(/\s*,\s*/).includes(etag))
+        return new Response(null, { status: 304, headers });
+    } else {
+      const ifModifiedSince = request.headers.get("if-modified-since");
+      if (ifModifiedSince !== null && Date.parse(ifModifiedSince) >= mtime - mtime % 1000) {
+        return new Response(null, { status: 304, headers });
+      }
+    }
+    const range = request.method === "GET" ? request.headers.get("range") : null;
+    const match = range === null ? null : /^bytes=(\d*)-(\d*)$/.exec(range);
+    if (match !== null && (match[1] !== "" || match[2] !== "")) {
+      const start = match[1] === "" ? Math.max(size - Number(match[2]), 0) : Number(match[1]);
+      const end = match[1] !== "" && match[2] !== "" ? Math.min(Number(match[2]), size - 1) : size - 1;
+      if (start >= size || start > end) {
+        headers.set("content-range", `bytes */${size}`);
+        return new Response(null, { status: 416, headers });
+      }
+      headers.set("content-range", `bytes ${start}-${end}/${size}`);
+      return new Response(file.slice(start, end + 1), { status: 206, headers });
+    }
+    return new Response(file, { headers });
+  };
+}
 export {
-  staticMiddleware2 as staticMiddleware
+  serveStatic
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhythmjs/router",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Bun-native HTTP router for the Rhythm middleware kernel, matching with rou3 and serving with Bun.serve.",
   "homepage": "https://rhythm.js.org/router",
   "license": "ISC",
@@ -27,14 +27,6 @@
       "types": "./dist/fetch.d.ts",
       "default": "./dist/fetch.js"
     },
-    "./serve": {
-      "types": "./dist/serve.d.ts",
-      "default": "./dist/serve.js"
-    },
-    "./static": {
-      "types": "./dist/static.d.ts",
-      "default": "./dist/static.js"
-    },
     "./adapters/context": {
       "types": "./dist/context.d.ts",
       "default": "./dist/context.js"
@@ -46,7 +38,7 @@
   },
   "dependencies": {
     "rou3": "^0.11.0",
-    "@rhythmjs/rhythm": "0.0.11"
+    "@rhythmjs/rhythm": "0.0.12"
   },
   "devDependencies": {
     "@types/bun": "^1.2.0",
@@ -57,7 +49,7 @@
     "bun": ">=1.2.0"
   },
   "scripts": {
-    "build": "bun build src/rhythm-router.ts src/context.ts src/fetch.ts src/serve.ts src/static.ts --outdir dist --root src --format esm --target bun --packages external --splitting && tsc -p tsconfig.build.json",
+    "build": "bun build src/rhythm-router.ts src/context.ts src/fetch.ts --outdir dist --root src --format esm --target bun --packages external --splitting && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   }