@telorun/http-server 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @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
+
+- a8c99ab: Generic dispatch tracing: trace every capability dispatch (invoke and run) through one instrumented chokepoint and carry trace data in a structured event payload instead of the event name.
+
+  - Dispatch events drop the kind from the name (`<name>.Invoked` / `.Run`, plus error/cancel variants). The payload now carries `{ spanId, parentSpanId, capability, phase, outcome, ref: { kind, name }, … }`; consumers read the payload and never parse the dotted name. Lifecycle events (`Kind.name.Created` / `.Initialized` / `.Teardown`) are unchanged.
+  - `run()` is now span-instrumented like `invoke()`: it mints and propagates a trace id, so Runnables (e.g. a `Run.Sequence` boot target) appear in the trace and their nested invokes re-parent correctly instead of detaching as false roots. Long-lived Services emit a `<name>.Running` start span. Run failures emit `<name>.RunFailed` (rethrown, never swallowed).
+  - Invoke/run emit a `<name>.Invoking` / `.Running` start span when tracing is on.
+  - SDK: new `REF_IDENTITY` / `stampRefIdentity` / `getRefIdentity`. The kernel stamps a resolved `!ref`'s kind+name onto the injected instance so `executeInvokeStep` routes pre-injected live instances through the traced chokepoint instead of calling `.invoke()` directly and escaping instrumentation.
+  - The boot `targets` run is wrapped in an application span (`<appName>.Run`, `ref.kind: "Telo.Application"`), so the application is the trace root with its targets nested beneath. Pre-resolved `!ref` boot targets now dispatch through a new `EvaluationContext.runResolved` (the `run()` analog of `invokeResolved`) instead of calling `instance.run()` directly, so they emit their own run spans nested under the app.
+  - A `Telo.Service`'s long-lived `run()` no longer establishes the cancellation/trace ALS scope (its token is delivered via the explicit `run(invokeCtx)` argument instead). This stops the boot scope leaking onto async resources the service creates — e.g. an HTTP server's socket — so inbound work (each request) starts as its own root trace with no inherited boot cancellation token, instead of nesting under the bootstrap trace. Runnables keep the ALS scope so their steps still nest and inherit cancellation.
+  - `EventBus.emit` short-circuits in O(1) when there are no subscribers, keeping the always-through-the-chokepoint dispatch effectively free when nobody is listening.
+  - OpenTelemetry-ready trace model: every span carries a `traceId` (OTel-compatible 16-byte hex), minted at the root and inherited by descendants, so an exporter groups a trace without walking the parent chain. New generic `ctx.openSpan(base, { ref, label, attributes, inbound? })` primitive opens an inbound-boundary span (capability `"request"`) that roots its own trace; `inbound` allows continuing an upstream distributed trace later. The `TracePayload` gains `traceId`, `label`, and `attributes`.
+  - `http-server`: each inbound request opens a request span attributed to the `Http.Api` and labelled with the route (`"POST /feedback"`, attributes `{ method, path }`); the handler invoke and its subtree nest under it, as a trace separate from the bootstrap.
+  - Trace context capture: a trace's root span carries `payload.context` — a redacted snapshot of the CEL root scope available to the trace (`variables`, `resources` snapshots, `ports`, and `secrets` with values masked to `"[secret]"`; host `env` omitted). Lets a debug consumer see what data an execution could reference beyond its own inputs/outputs. The UI renders it as an "Available context" section on the root node.
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.1
+
 ## 0.11.1
 
 ### Patch Changes

package/README.md

@@ -24,8 +24,8 @@ Language- and framework-agnostic HTTP server for Telo. Declarative routes, schem
 kind: Telo.Application
 metadata: { name: hello-http, version: 1.0.0 }
 imports:
-  Http: std/http-server@0.12.0
-  JS: std/javascript@0.5.0
+  Http: std/http-server@<version>
+  JS: std/javascript@<version>
 targets: [ !ref Server ]
 ---
 kind: Http.Server
@@ -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.d.ts

@@ -51,7 +51,8 @@ export declare class HttpServerApi implements ResourceInstance {
     private readonly ctx;
     readonly manifest: HttpApiManifest;
     private readonly handlerRefs;
-    constructor(ctx: ResourceContext, manifest: HttpApiManifest, handlerRefs: WeakMap<object, HandlerRef>);
+    private readonly apiName;
+    constructor(ctx: ResourceContext, manifest: HttpApiManifest, handlerRefs: WeakMap<object, HandlerRef>, apiName: string);
     init(): Promise<void>;
     register(app: FastifyInstance, prefix?: string): void;
     private registerRoutes;

package/dist/http-api-controller.js

@@ -26,35 +26,36 @@ export class HttpServerApi {
     ctx;
     manifest;
     handlerRefs;
-    constructor(ctx, manifest, handlerRefs) {
+    apiName;
+    constructor(ctx, manifest, handlerRefs, apiName) {
         this.ctx = ctx;
         this.manifest = manifest;
         this.handlerRefs = handlerRefs;
+        this.apiName = apiName;
     }
     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
@@ -95,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();
@@ -118,22 +122,35 @@ export class HttpServerApi {
                     if (!reply.sent)
                         cancellation.cancel("client-disconnect");
                 });
+                // Open a request span rooting this request's own trace: the handler (and
+                // its nested invokes) nest under it, and it's labelled with the route so
+                // the trace shows the actual method+path, attributed to this Http.Api.
+                const span = await this.ctx.openSpan(cancellation.context, {
+                    ref: { kind: "Http.Api", name: this.apiName },
+                    label: `${route.request.method} ${route.request.path}`,
+                    attributes: { method: route.request.method, path: route.request.path },
+                });
                 let result;
                 try {
                     result = handler
-                        ? await this.ctx.invokeResolved(handlerKind, handlerName, handler, invokeInput, cancellation.context)
+                        ? await this.ctx.invokeResolved(handlerKind, handlerName, handler, invokeInput, span.context)
                         : undefined;
                 }
                 catch (err) {
                     if (isCancellationError(err)) {
+                        await span.settle("cancelled");
                         if (!reply.sent)
                             reply.code(499).send();
                         return;
                     }
-                    if (!isInvokeError(err))
+                    if (!isInvokeError(err)) {
+                        await span.settle("failed");
                         throw err;
+                    }
+                    await span.settle("rejected");
                     return dispatchCatches(route.catches, { code: err.code, message: err.message, data: err.data }, requestContext, acceptHeader, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), sink);
                 }
+                await span.settle("ok");
                 return dispatchReturns(route.returns, result, requestContext, acceptHeader, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), sink, (err, errCtx) => this.ctx.emitEvent("Http.Api.streamFailed", {
                     path: route.request.path,
                     method: route.request.method,
@@ -169,7 +186,7 @@ export async function create(resource, ctx) {
             handlerRefs.set(route, { kind: "", name: h });
         }
     }
-    return new HttpServerApi(ctx, resource, handlerRefs);
+    return new HttpServerApi(ctx, resource, handlerRefs, resource?.metadata?.name ?? "");
 }
 /**
  * Translates OpenAPI path format {paramName} to Fastify format :paramName
@@ -178,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.11.1",
+  "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.31.0"
+    "@telorun/sdk": "0.33.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-api-controller.ts

@@ -59,37 +59,35 @@ export class HttpServerApi implements ResourceInstance {
     private readonly ctx: ResourceContext,
     readonly manifest: HttpApiManifest,
     private readonly handlerRefs: WeakMap<object, HandlerRef>,
+    private readonly apiName: string,
   ) {}
 
   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: {} };
 
@@ -130,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 = (
@@ -159,6 +160,15 @@ export class HttpServerApi implements ResourceInstance {
           if (!reply.sent) cancellation.cancel("client-disconnect");
         });
 
+        // Open a request span rooting this request's own trace: the handler (and
+        // its nested invokes) nest under it, and it's labelled with the route so
+        // the trace shows the actual method+path, attributed to this Http.Api.
+        const span = await this.ctx.openSpan(cancellation.context, {
+          ref: { kind: "Http.Api", name: this.apiName },
+          label: `${route.request.method} ${route.request.path}`,
+          attributes: { method: route.request.method, path: route.request.path },
+        });
+
         let result: unknown;
         try {
           result = handler
@@ -167,15 +177,20 @@ export class HttpServerApi implements ResourceInstance {
                 handlerName,
                 handler,
                 invokeInput,
-                cancellation.context,
+                span.context,
               )
             : undefined;
         } catch (err) {
           if (isCancellationError(err)) {
+            await span.settle("cancelled");
             if (!reply.sent) reply.code(499).send();
             return;
           }
-          if (!isInvokeError(err)) throw err;
+          if (!isInvokeError(err)) {
+            await span.settle("failed");
+            throw err;
+          }
+          await span.settle("rejected");
           return dispatchCatches(
             route.catches,
             { code: err.code, message: err.message, data: err.data },
@@ -187,6 +202,7 @@ export class HttpServerApi implements ResourceInstance {
           );
         }
 
+        await span.settle("ok");
         return dispatchReturns(
           route.returns,
           result,
@@ -232,7 +248,7 @@ export async function create(resource: any, ctx: ResourceContext): Promise<HttpS
       handlerRefs.set(route, { kind: "", name: h });
     }
   }
-  return new HttpServerApi(ctx, resource, handlerRefs);
+  return new HttpServerApi(ctx, resource, handlerRefs, resource?.metadata?.name ?? "");
 }
 
 /**
@@ -243,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;

package/tests/request-cancel.test.ts

@@ -48,6 +48,7 @@ describe("http-server request cancellation", () => {
       invokeResolved: (_kind: string, _name: string, h: typeof handler, input: unknown, c: unknown) =>
         h.invoke(input, c as { cancellation?: any }),
       emitEvent: () => {},
+      openSpan: async (base: unknown) => ({ context: base, settle: async () => {} }),
     } as unknown as Parameters<typeof create>[1];
 
     const resource = {

package/tests/request-span.test.ts

@@ -0,0 +1,82 @@
+import { createCancellationSource } from "@telorun/sdk";
+import Fastify from "fastify";
+import type { AddressInfo } from "node:net";
+import { describe, expect, it } from "vitest";
+import { create } from "../src/http-api-controller.js";
+
+/**
+ * Each inbound request opens a trace span attributed to the Http.Api and labelled
+ * with the route, under which the handler invoke nests. This drives the real
+ * controller (real Fastify) with a mock ResourceContext that captures the
+ * `openSpan` call, asserting the controller passes the route's `{kind,name}`,
+ * label and `{method,path}` attributes — and settles the span on success.
+ *
+ * The generic span mechanics (rooting a detached trace, nesting, trace id) are a
+ * kernel concern, tested there; this test owns only the HTTP-specific wiring.
+ */
+describe("http-server request span", () => {
+  it("opens a route-labelled span and dispatches the handler under it", async () => {
+    const spanCalls: any[] = [];
+    const settled: string[] = [];
+
+    const handler = {
+      async invoke(input: unknown) {
+        return { echoed: (input as { value: number }).value };
+      },
+      snapshot: () => ({}),
+    };
+
+    const ctx = {
+      validateSchema: () => {},
+      resolveChildren: () => ({ kind: "JS.Script", name: "Echo" }),
+      moduleContext: { expandWith: (value: unknown) => value },
+      createCancellationSource: () => createCancellationSource(),
+      invokeResolved: (_kind: string, _name: string, h: typeof handler, input: unknown) =>
+        h.invoke(input),
+      emitEvent: () => {},
+      openSpan: async (base: unknown, opts: unknown) => {
+        spanCalls.push(opts);
+        return {
+          context: base,
+          settle: async (outcome: string) => {
+            settled.push(outcome);
+          },
+        };
+      },
+    } as unknown as Parameters<typeof create>[1];
+
+    const resource = {
+      metadata: { name: "EchoApi", module: "test" },
+      routes: [
+        {
+          request: { path: "/echo", method: "GET" },
+          handler,
+          inputs: { value: 1 },
+          returns: [{ status: 200, content: { "application/json": { body: { ok: true } } } }],
+        },
+      ],
+    };
+
+    const api = await create(resource, ctx);
+    const app = Fastify({ logger: false });
+    api.register(app);
+    await app.listen({ host: "127.0.0.1", port: 0 });
+    const { port } = app.server.address() as AddressInfo;
+
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/echo`);
+      expect(res.status).toBe(200);
+      await res.json();
+
+      expect(spanCalls).toHaveLength(1);
+      expect(spanCalls[0]).toEqual({
+        ref: { kind: "Http.Api", name: "EchoApi" },
+        label: "GET /echo",
+        attributes: { method: "GET", path: "/echo" },
+      });
+      expect(settled).toEqual(["ok"]);
+    } finally {
+      await app.close().catch(() => {});
+    }
+  });
+});