@telorun/http-server 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @telorun/http-server
 
+## 0.13.0
+
+### Minor Changes
+
+- 95f168e: Cache, rate-limit, and background-task primitives, plus a comprehensive URL-shortener example.
+
+  - New `cache` family: the backend-pluggable `Cache.Store` abstract with `Cache.Lookup` / `Cache.Entry` (freshness-aware: `ttl` fresh window + optional `staleTtl` grace window, `state` of `miss`/`fresh`/`stale`) and the `Cache.View` read-through decorator (single-flight background revalidation). Backends ship as `cache-memory` (`CacheMemory.Store`) and `cache-redis` (`CacheRedis.Store`, with observable degrade-to-`fallback`).
+  - New `rate-limit` module: `RateLimit.Guard`, a non-throwing sliding-window limiter whose counters live in any `Cache.Store`.
+  - `run` gains `Run.Detach` (generic, zero-config fire-and-forget).
+  - SDK + kernel: `ResourceContext.runDetached(fn)` runs a function detached from the caller's cancellation/trace scope; the kernel tracks each detached task against its owning resource and drains it (bounded) when that resource tears down, routing failures to the EventBus. Used by `Run.Detach` and `Cache.View`'s background revalidation.
+  - `http-server`: `Http.Server.trustProxy` and a derived `request.ip` in the handler CEL context (canonical client address for rate-limit keys).
+
+### Patch Changes
+
+- 95f168e: Fix OpenAPI documentation conflating routes from different mounts.
+
+  Each `Http.Api` route is now registered at its full `<mountPrefix><path>` instead of inside a Fastify `{ prefix }`-encapsulated context, and the generated OpenAPI `servers` block is a single origin (`baseUrl`, the forwarded host, or relative `/`) rather than one entry per mount prefix. Previously `@fastify/swagger` stripped each mount's prefix from the documented path while the prefixes were hoisted into `servers`, so different APIs mounted at different prefixes collapsed together — e.g. an `Http.Api` mounted at `/admin` was documented at `/links` instead of `/admin/links`. Actual request routing was unaffected; this corrects only the generated document.
+
+  - @telorun/http-dispatch@0.4.1
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -210,15 +210,18 @@ request:
 ### 5. External URL & OpenAPI `servers`
 
 A server is usually reached through a reverse proxy / ingress, so its own bound
-`host:port` is not the URL clients use. The generated OpenAPI `servers` block MUST
-follow this resolution, identically across runtimes (Node/Rust/Go) — the inputs
-are standard HTTP, never a framework's proxy-config object:
+`host:port` is not the URL clients use. The generated OpenAPI `servers` block is a
+**single origin** — each operation is documented at its full `<mountPrefix><path>`,
+so different APIs mounted at different prefixes stay distinct (an `Http.Api` mounted
+at `/admin` is documented at `/admin/...`, never flattened to `/...`). The origin
+resolves identically across runtimes (Node/Rust/Go) — the inputs are standard HTTP,
+never a framework's proxy-config object:
 
 | Manifest | `servers[].url` |
 | --- | --- |
-| `baseUrl: <url>` | `<url><mountPrefix>` — explicit, fixed; wins over everything |
-| `trustForwardedHeaders: true` | `<X-Forwarded-Proto>://<X-Forwarded-Host><mountPrefix>`, derived per request |
-| neither (default) | `<mountPrefix>` — **relative**; the client resolves it against the origin the document was loaded from |
+| `baseUrl: <url>` | `<url>` — explicit, fixed; wins over everything |
+| `trustForwardedHeaders: true` | `<X-Forwarded-Proto>://<X-Forwarded-Host>`, derived per request |
+| neither (default) | `/` — **relative**; the client resolves it against the origin the document was loaded from |
 
 - The default is **relative** so the document is correct behind any proxy, ingress,
   or origin with zero configuration.

package/dist/http-api-controller.js

@@ -35,28 +35,27 @@ export class HttpServerApi {
     }
     async init() { }
     register(app, prefix = "") {
-        if (prefix) {
-            app.register(async (scoped) => {
-                this.registerRoutes(scoped);
-            }, { prefix });
-        }
-        else {
-            this.registerRoutes(app);
-        }
+        // Register each route at its full `prefix + path` on the root app rather than
+        // inside a `{ prefix }`-encapsulated context. Fastify encapsulation makes
+        // @fastify/swagger strip the prefix from the documented path, which conflates
+        // routes from different mounts (e.g. an Api at `/admin` documented as `/links`).
+        // Carrying the prefix on the path keeps the OpenAPI doc unambiguous for any mix
+        // of mounts; a single `servers` origin is set by the server controller.
+        this.registerRoutes(app, normalizeMountPrefix(prefix));
     }
-    registerRoutes(app) {
+    registerRoutes(app, prefix) {
         const routes = this.manifest.routes || [];
         for (const route of routes) {
-            this.registerRoute(app, route);
+            this.registerRoute(app, route, prefix);
         }
     }
-    registerRoute(app, route) {
+    registerRoute(app, route, prefix) {
         // After Phase 5 injection, KindRef<Invocable> is replaced with the live Invocable instance.
         const handler = route.handler;
         const handlerRef = this.handlerRefs.get(route);
         const handlerKind = handlerRef?.kind ?? "";
         const handlerName = handlerRef?.name ?? "";
-        const translatedPath = translateOpenApiPath(route.request.path);
+        const translatedPath = prefix + translateOpenApiPath(route.request.path);
         const schema = { response: {} };
         // A stream-marked body is delivered as a raw `Stream<Uint8Array>` (see the
         // server's `contentTypeParsers[].stream`); it is opaque to AJV, so skip
@@ -97,6 +96,9 @@ export class HttpServerApi {
                         query: request.query || {},
                         headers: normalizeHeaders(request.headers),
                         body: streamBody ? toByteStream(request) : request.body,
+                        // Canonical client address — honours X-Forwarded-For per the
+                        // server's `trustProxy` setting (Fastify resolves it).
+                        ip: request.ip,
                     },
                 };
                 const acceptHeader = request.headers["accept"]?.toString();
@@ -193,6 +195,16 @@ export async function create(resource, ctx) {
 function translateOpenApiPath(openApiPath) {
     return openApiPath.replace(/{([a-zA-Z_][a-zA-Z0-9_]*)}/g, ":$1");
 }
+/**
+ * Normalizes a mount prefix into a path segment that prepends cleanly to a route
+ * path: the root mount (`""` / `"/"`) contributes nothing, and a trailing slash
+ * is dropped so `"/admin" + "/links"` is `/admin/links`, never `/admin//links`.
+ */
+function normalizeMountPrefix(prefix) {
+    if (!prefix || prefix === "/")
+        return "";
+    return prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+}
 /**
  * Wraps an incoming request's raw body as a `Stream<Uint8Array>`. Requires a
  * stream content-type parser (`contentTypeParsers[].stream`) for the request's

package/dist/http-server-controller.d.ts

@@ -26,6 +26,7 @@ type HttpServerResource = RuntimeResource & {
     port?: number;
     baseUrl?: string;
     trustForwardedHeaders?: boolean;
+    trustProxy?: boolean | number;
     logger?: boolean;
     cors?: CorsOptions;
     contentTypeParsers?: Array<{

package/dist/http-server-controller.js

@@ -28,11 +28,14 @@ class HttpServer {
         if (!this.port) {
             throw new Error("Http.Server port is required");
         }
+        // `trustProxy` is the single Fastify knob behind both the forwarded
+        // protocol/host (request.protocol/host) and the canonical client address
+        // (request.ip). An explicit `trustProxy` (boolean / hop-count) wins; absent
+        // it, the legacy `trustForwardedHeaders` boolean still applies.
+        const trustProxy = resource.trustProxy ?? this.trustForwardedHeaders;
         this.app = Fastify({
             logger: resource.logger,
-            // Honour X-Forwarded-Proto / X-Forwarded-Host so request.protocol/host (and
-            // the OpenAPI servers derived from them) reflect a fronting proxy's URL.
-            trustProxy: this.trustForwardedHeaders,
+            trustProxy,
             ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default] },
         });
     }
@@ -96,15 +99,13 @@ class HttpServer {
             throw error;
         });
         if (this.resource.openapi) {
-            const mounts = this.resource.mounts || [];
-            const prefixes = [...new Set(mounts.map((mount) => mount.path || ""))];
-            // Server URL precedence: an explicit `baseUrl` is an absolute, fixed
-            // override; otherwise the URLs are relative (just the mount prefix) so the
-            // doc is correct behind any proxy/ingress/origin without configuration —
-            // the client resolves them against wherever the reference was loaded.
-            const servers = prefixes.map((prefix) => ({
-                url: this.resource.baseUrl ? this.resource.baseUrl + prefix : prefix || "/",
-            }));
+            // Each route is documented at its full `mount-prefix + path` (see
+            // http-api-controller), so the server is a single origin, not one entry per
+            // mount. Server URL precedence: an explicit `baseUrl` is an absolute, fixed
+            // override; otherwise the URL is relative (`/`) so the doc is correct behind
+            // any proxy/ingress/origin — the client resolves it against wherever the
+            // reference was loaded.
+            const servers = [{ url: this.resource.baseUrl ?? "/" }];
             await this.app.register(swagger, {
                 openapi: {
                     openapi: "3.0.0",
@@ -135,9 +136,7 @@ class HttpServer {
                     try {
                         const doc = JSON.parse(text);
                         if (doc && typeof doc === "object" && Array.isArray(doc.servers)) {
-                            doc.servers = prefixes.map((prefix) => ({
-                                url: `${request.protocol}://${request.host}${prefix}`,
-                            }));
+                            doc.servers = [{ url: `${request.protocol}://${request.host}` }];
                             const out = JSON.stringify(doc);
                             reply.header("content-length", Buffer.byteLength(out));
                             return out;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Telo HTTP Server module - HTTP server and API resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -49,7 +49,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.32.0"
+    "@telorun/sdk": "0.33.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-api-controller.ts

@@ -65,32 +65,29 @@ export class HttpServerApi implements ResourceInstance {
   async init() {}
 
   register(app: FastifyInstance, prefix = "") {
-    if (prefix) {
-      app.register(
-        async (scoped) => {
-          this.registerRoutes(scoped);
-        },
-        { prefix },
-      );
-    } else {
-      this.registerRoutes(app);
-    }
+    // Register each route at its full `prefix + path` on the root app rather than
+    // inside a `{ prefix }`-encapsulated context. Fastify encapsulation makes
+    // @fastify/swagger strip the prefix from the documented path, which conflates
+    // routes from different mounts (e.g. an Api at `/admin` documented as `/links`).
+    // Carrying the prefix on the path keeps the OpenAPI doc unambiguous for any mix
+    // of mounts; a single `servers` origin is set by the server controller.
+    this.registerRoutes(app, normalizeMountPrefix(prefix));
   }
 
-  private registerRoutes(app: FastifyInstance) {
+  private registerRoutes(app: FastifyInstance, prefix: string) {
     const routes = this.manifest.routes || [];
     for (const route of routes) {
-      this.registerRoute(app, route);
+      this.registerRoute(app, route, prefix);
     }
   }
 
-  private registerRoute(app: FastifyInstance, route: HttpApiRouteManifest) {
+  private registerRoute(app: FastifyInstance, route: HttpApiRouteManifest, prefix: string) {
     // After Phase 5 injection, KindRef<Invocable> is replaced with the live Invocable instance.
     const handler = route.handler as unknown as ResourceInstance | undefined;
     const handlerRef = this.handlerRefs.get(route as unknown as object);
     const handlerKind = handlerRef?.kind ?? "";
     const handlerName = handlerRef?.name ?? "";
-    const translatedPath = translateOpenApiPath(route.request.path);
+    const translatedPath = prefix + translateOpenApiPath(route.request.path);
 
     const schema: any = { response: {} };
 
@@ -131,6 +128,9 @@ export class HttpServerApi implements ResourceInstance {
             query: request.query || {},
             headers: normalizeHeaders(request.headers),
             body: streamBody ? toByteStream(request) : request.body,
+            // Canonical client address — honours X-Forwarded-For per the
+            // server's `trustProxy` setting (Fastify resolves it).
+            ip: request.ip,
           },
         };
         const acceptHeader = (
@@ -259,6 +259,16 @@ function translateOpenApiPath(openApiPath: string): string {
   return openApiPath.replace(/{([a-zA-Z_][a-zA-Z0-9_]*)}/g, ":$1");
 }
 
+/**
+ * Normalizes a mount prefix into a path segment that prepends cleanly to a route
+ * path: the root mount (`""` / `"/"`) contributes nothing, and a trailing slash
+ * is dropped so `"/admin" + "/links"` is `/admin/links`, never `/admin//links`.
+ */
+function normalizeMountPrefix(prefix: string): string {
+  if (!prefix || prefix === "/") return "";
+  return prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+}
+
 /**
  * Wraps an incoming request's raw body as a `Stream<Uint8Array>`. Requires a
  * stream content-type parser (`contentTypeParsers[].stream`) for the request's

package/src/http-server-controller.ts

@@ -46,6 +46,7 @@ type HttpServerResource = RuntimeResource & {
   port?: number;
   baseUrl?: string;
   trustForwardedHeaders?: boolean;
+  trustProxy?: boolean | number;
   logger?: boolean;
   cors?: CorsOptions;
   contentTypeParsers?: Array<{ contentType: string; parser?: Invocable; stream?: boolean }>;
@@ -105,11 +106,14 @@ class HttpServer implements ResourceInstance {
     if (!this.port) {
       throw new Error("Http.Server port is required");
     }
+    // `trustProxy` is the single Fastify knob behind both the forwarded
+    // protocol/host (request.protocol/host) and the canonical client address
+    // (request.ip). An explicit `trustProxy` (boolean / hop-count) wins; absent
+    // it, the legacy `trustForwardedHeaders` boolean still applies.
+    const trustProxy = resource.trustProxy ?? this.trustForwardedHeaders;
     this.app = Fastify({
       logger: resource.logger,
-      // Honour X-Forwarded-Proto / X-Forwarded-Host so request.protocol/host (and
-      // the OpenAPI servers derived from them) reflect a fronting proxy's URL.
-      trustProxy: this.trustForwardedHeaders,
+      trustProxy,
       ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default as any] },
     });
   }
@@ -178,15 +182,13 @@ class HttpServer implements ResourceInstance {
       throw error;
     });
     if (this.resource.openapi) {
-      const mounts = this.resource.mounts || [];
-      const prefixes = [...new Set(mounts.map((mount) => mount.path || ""))];
-      // Server URL precedence: an explicit `baseUrl` is an absolute, fixed
-      // override; otherwise the URLs are relative (just the mount prefix) so the
-      // doc is correct behind any proxy/ingress/origin without configuration —
-      // the client resolves them against wherever the reference was loaded.
-      const servers = prefixes.map((prefix) => ({
-        url: this.resource.baseUrl ? this.resource.baseUrl + prefix : prefix || "/",
-      }));
+      // Each route is documented at its full `mount-prefix + path` (see
+      // http-api-controller), so the server is a single origin, not one entry per
+      // mount. Server URL precedence: an explicit `baseUrl` is an absolute, fixed
+      // override; otherwise the URL is relative (`/`) so the doc is correct behind
+      // any proxy/ingress/origin — the client resolves it against wherever the
+      // reference was loaded.
+      const servers = [{ url: this.resource.baseUrl ?? "/" }];
       await this.app.register(swagger, {
         openapi: {
           openapi: "3.0.0",
@@ -216,9 +218,7 @@ class HttpServer implements ResourceInstance {
           try {
             const doc = JSON.parse(text);
             if (doc && typeof doc === "object" && Array.isArray(doc.servers)) {
-              doc.servers = prefixes.map((prefix) => ({
-                url: `${request.protocol}://${request.host}${prefix}`,
-              }));
+              doc.servers = [{ url: `${request.protocol}://${request.host}` }];
               const out = JSON.stringify(doc);
               reply.header("content-length", Buffer.byteLength(out));
               return out;