@telorun/http-server 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @telorun/http-server
 
+## 0.11.0
+
+### Minor Changes
+
+- b1dd65c: `Http.Server`: the generated OpenAPI `servers` URL now defaults to a **relative** path (the mount prefix), so the reference UI and spec are correct behind any proxy/ingress/origin with no configuration — fixing the previous hardcoded `http://<bind-host>:<port>` that didn't match the reachable URL. Add an opt-in `trustForwardedHeaders` boolean: when enabled the server honors the standard `X-Forwarded-Proto` / `X-Forwarded-Host` headers and advertises an absolute `servers` URL (and request protocol/host) matching the fronting proxy. An explicit `baseUrl` still overrides both.
+
+## 0.10.0
+
+### Minor Changes
+
+- ee8926f: Unify resource references on the `!ref` YAML tag. The object form `{ kind, name }`
+  and bare-string references are removed: the analyzer rejects them up front
+  (`INVALID_REFERENCE_FORM`) and `!ref <name>` / `!ref <Alias>.<name>` is the only
+  authored shape. `resolveRefSentinels` now resolves `!ref` sentinels across the
+  whole manifest tree (including step `invoke`s and refs nested in inline
+  definitions), so every consumer sees the uniform resolved shape. The
+  http-server mount slot is renamed `mounts[].type` → `mounts[].mount`, and the
+  mcp transports / clients read their Phase-5-injected ref instances directly.
+
+  Schema validation (analyzer and kernel) now drops the stale scalar `type` a ref
+  slot may still pin (older published modules encode references as `type: string`)
+  before running AJV, so a resolved reference object validates against a legacy
+  `x-telo-ref` slot. This keeps an app that consumes a not-yet-republished
+  dependency analyzable and bootable during the migration. Object-typed ref slots
+  that also accept an inline value (e.g. `inputType` / `outputType`) are left
+  untouched.
+
+  `Run.Sequence` reference slots are brought onto the same enforcement path: a
+  step `invoke` and a scope `targets` entry now require a `!ref` (the `targets`
+  slot gains an `x-telo-ref` constraint and the `with` scope's visibility extends
+  to `/targets`), so a bare-string ref at either is rejected with
+  `INVALID_REFERENCE_FORM` at `telo check` — uniform with `Telo.Application`
+  targets — instead of failing as an obscure runtime error. The controller reads
+  the resolved reference rather than a bare name.
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -24,16 +24,16 @@ Language- and framework-agnostic HTTP server for Telo. Declarative routes, schem
 kind: Telo.Application
 metadata: { name: hello-http, version: 1.0.0 }
 imports:
-  Http: pkg:npm/@telorun/http-server@^1.0.0
-  JS: pkg:npm/@telorun/javascript@^1.0.0
-targets: [Server]
+  Http: std/http-server@0.11.0
+  JS: std/javascript@0.5.0
+targets: [ !ref Server ]
 ---
 kind: Http.Server
 metadata: { name: Server }
 port: 8080
 mounts:
   - path: /api
-    type: Api
+    mount: !ref Api
 ---
 kind: Http.Api
 metadata: { name: Api }
@@ -54,7 +54,7 @@ routes:
               examples: [ "Ada" ]
     inputs:
       name: "${{ request.params.name }}"
-    handler: { kind: JS.Script, name: Greet }
+    handler: !ref Greet
     returns:
       - status: 200
         content:
@@ -206,3 +206,26 @@ request:
           description: "Validation schema for the request payload"
   required: ["path", "method"]
 ```
+
+### 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:
+
+| 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 |
+
+- The default is **relative** so the document is correct behind any proxy, ingress,
+  or origin with zero configuration.
+- `trustForwardedHeaders` is a **boolean** on purpose: the only portable cross-runtime
+  signal is the standard `X-Forwarded-Proto` / `X-Forwarded-Host` (RFC 7239 `Forwarded`)
+  headers. Fine-grained "trusted proxy IP/CIDR/hop" lists are framework-specific and
+  MUST NOT leak into the manifest. Default `false`; only enable behind a trusted proxy
+  (a client with direct network access could otherwise spoof the headers).
+- When `trustForwardedHeaders` is set, the request protocol/host exposed to handlers
+  MUST also reflect the forwarded headers.

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

@@ -2,7 +2,7 @@ import { CatchEntry, ReturnEntry } from "@telorun/http-dispatch";
 import { type Invocable, type KindRef, type ResourceContext, type ResourceInstance, type RuntimeResource } from "@telorun/sdk";
 import { FastifyInstance } from "fastify";
 /** A mounted Telo.Mount instance (Http.Api, Mcp.HttpEndpoint, …). The kernel injects the
- *  live instance into a mount's `type` slot (x-telo-ref "telo#Mount") — cross-module refs
+ *  live instance into a mount's `mount` slot (x-telo-ref "telo#Mount") — cross-module refs
  *  resolve to an imported library's exported mount — and every mountable exposes register(). */
 interface Mountable {
     register(app: FastifyInstance, prefix: string): void | Promise<void>;
@@ -25,6 +25,7 @@ type HttpServerResource = RuntimeResource & {
     host?: string;
     port?: number;
     baseUrl?: string;
+    trustForwardedHeaders?: boolean;
     logger?: boolean;
     cors?: CorsOptions;
     contentTypeParsers?: Array<{
@@ -40,7 +41,7 @@ type HttpServerResource = RuntimeResource & {
     };
     mounts?: Array<{
         path?: string;
-        type?: Mountable;
+        mount?: Mountable;
     }>;
     notFoundHandler?: {
         invoke: KindRef<Invocable>;

package/dist/http-server-controller.js

@@ -13,6 +13,7 @@ class HttpServer {
     host;
     port;
     baseUrl;
+    trustForwardedHeaders;
     resource;
     ctx;
     resolvedNotFoundHandler;
@@ -22,12 +23,16 @@ class HttpServer {
         this.host = resource.host || "0.0.0.0";
         this.port = Number(resource.port || 0);
         this.baseUrl = resource.baseUrl ?? `http://${this.host}:${this.port}`;
+        this.trustForwardedHeaders = resource.trustForwardedHeaders === true;
         this.resolvedNotFoundHandler = resolvedNotFoundHandler;
         if (!this.port) {
             throw new Error("Http.Server port is required");
         }
         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,
             ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default] },
         });
     }
@@ -91,16 +96,15 @@ class HttpServer {
             throw error;
         });
         if (this.resource.openapi) {
-            const servers = [];
-            // const routesByName = new Map<string, HttpRouteResource>();
             const mounts = this.resource.mounts || [];
-            const prefixes = new Set();
-            for (const mount of mounts) {
-                prefixes.add(mount.path || "");
-            }
-            for (const prefix of prefixes) {
-                servers.push({ url: this.baseUrl + prefix });
-            }
+            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 || "/",
+            }));
             await this.app.register(swagger, {
                 openapi: {
                     openapi: "3.0.0",
@@ -108,8 +112,45 @@ class HttpServer {
                     servers,
                 },
             });
+            const referencePrefix = "/reference";
+            // `trustForwardedHeaders` (and no fixed baseUrl) upgrades the relative
+            // default to absolute URLs built per-request from the now-trusted
+            // X-Forwarded-* headers, so the served spec advertises the real proxy URL.
+            if (this.trustForwardedHeaders && !this.resource.baseUrl) {
+                // Couples to the Scalar plugin's default spec endpoint
+                // (`<routePrefix>/openapi.json`); if it ever served the doc elsewhere the
+                // rewrite would no-op and the relative default would still apply. The
+                // `openapi-server-url` integration test guards this path.
+                const specPath = `${referencePrefix}/openapi.json`;
+                this.app.addHook("onSend", async (request, reply, payload) => {
+                    if (request.url.split("?")[0] !== specPath)
+                        return payload;
+                    const text = typeof payload === "string"
+                        ? payload
+                        : Buffer.isBuffer(payload)
+                            ? payload.toString("utf8")
+                            : null;
+                    if (text === null)
+                        return payload;
+                    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}`,
+                            }));
+                            const out = JSON.stringify(doc);
+                            reply.header("content-length", Buffer.byteLength(out));
+                            return out;
+                        }
+                    }
+                    catch {
+                        // Not a JSON document we can rewrite — leave the response untouched.
+                    }
+                    return payload;
+                });
+            }
             await this.app.register(apiReference, {
-                routePrefix: "/reference",
+                routePrefix: referencePrefix,
             });
         }
     }
@@ -119,9 +160,9 @@ class HttpServer {
         // const resolveSchema = createSchemaResolver(this.ctx);
         for (const mount of mounts) {
             const prefix = mount.path || "";
-            // `mount.type` is the live Telo.Mount instance injected by the kernel at Phase 5
+            // `mount.mount` is the live Telo.Mount instance injected by the kernel at Phase 5
             // (x-telo-ref "telo#Mount") — a same-module or imported-library mount, uniformly.
-            const api = mount.type;
+            const api = mount.mount;
             if (!api || typeof api.register !== "function") {
                 throw new Error(`Failed to mount at "${prefix}": mount target did not resolve to a Telo.Mount instance`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.9.0",
+  "version": "0.11.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.23.0"
+    "@telorun/sdk": "0.26.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-server-controller.ts

@@ -20,7 +20,7 @@ import Fastify, { FastifyInstance } from "fastify";
 import { fastifyReplySink } from "./fastify-reply-sink.js";
 
 /** A mounted Telo.Mount instance (Http.Api, Mcp.HttpEndpoint, …). The kernel injects the
- *  live instance into a mount's `type` slot (x-telo-ref "telo#Mount") — cross-module refs
+ *  live instance into a mount's `mount` slot (x-telo-ref "telo#Mount") — cross-module refs
  *  resolve to an imported library's exported mount — and every mountable exposes register(). */
 interface Mountable {
   register(app: FastifyInstance, prefix: string): void | Promise<void>;
@@ -45,6 +45,7 @@ type HttpServerResource = RuntimeResource & {
   host?: string;
   port?: number;
   baseUrl?: string;
+  trustForwardedHeaders?: boolean;
   logger?: boolean;
   cors?: CorsOptions;
   contentTypeParsers?: Array<{ contentType: string; parser?: Invocable; stream?: boolean }>;
@@ -58,7 +59,7 @@ type HttpServerResource = RuntimeResource & {
     path?: string;
     // x-telo-ref "telo#Mount": Phase 5 replaces this slot with the live mounted
     // instance (Http.Api, Mcp.HttpEndpoint, …), local or imported.
-    type?: Mountable;
+    mount?: Mountable;
   }>;
   notFoundHandler?: {
     invoke: KindRef<Invocable>;
@@ -83,6 +84,7 @@ class HttpServer implements ResourceInstance {
   private readonly host: string;
   private readonly port: number;
   private readonly baseUrl: string;
+  private readonly trustForwardedHeaders: boolean;
   private readonly resource: HttpServerResource;
   private readonly ctx: ResourceContext;
   private readonly resolvedNotFoundHandler: ResolvedHandler | null;
@@ -97,6 +99,7 @@ class HttpServer implements ResourceInstance {
     this.host = resource.host || "0.0.0.0";
     this.port = Number(resource.port || 0);
     this.baseUrl = resource.baseUrl ?? `http://${this.host}:${this.port}`;
+    this.trustForwardedHeaders = resource.trustForwardedHeaders === true;
     this.resolvedNotFoundHandler = resolvedNotFoundHandler;
 
     if (!this.port) {
@@ -104,6 +107,9 @@ class HttpServer implements ResourceInstance {
     }
     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,
       ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default as any] },
     });
   }
@@ -172,16 +178,15 @@ class HttpServer implements ResourceInstance {
       throw error;
     });
     if (this.resource.openapi) {
-      const servers = [];
-      // const routesByName = new Map<string, HttpRouteResource>();
       const mounts = this.resource.mounts || [];
-      const prefixes = new Set();
-      for (const mount of mounts) {
-        prefixes.add(mount.path || "");
-      }
-      for (const prefix of prefixes) {
-        servers.push({ url: this.baseUrl + prefix });
-      }
+      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 || "/",
+      }));
       await this.app.register(swagger, {
         openapi: {
           openapi: "3.0.0",
@@ -189,8 +194,43 @@ class HttpServer implements ResourceInstance {
           servers,
         },
       });
+      const referencePrefix = "/reference";
+      // `trustForwardedHeaders` (and no fixed baseUrl) upgrades the relative
+      // default to absolute URLs built per-request from the now-trusted
+      // X-Forwarded-* headers, so the served spec advertises the real proxy URL.
+      if (this.trustForwardedHeaders && !this.resource.baseUrl) {
+        // Couples to the Scalar plugin's default spec endpoint
+        // (`<routePrefix>/openapi.json`); if it ever served the doc elsewhere the
+        // rewrite would no-op and the relative default would still apply. The
+        // `openapi-server-url` integration test guards this path.
+        const specPath = `${referencePrefix}/openapi.json`;
+        this.app.addHook("onSend", async (request, reply, payload) => {
+          if (request.url.split("?")[0] !== specPath) return payload;
+          const text =
+            typeof payload === "string"
+              ? payload
+              : Buffer.isBuffer(payload)
+                ? payload.toString("utf8")
+                : null;
+          if (text === null) return payload;
+          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}`,
+              }));
+              const out = JSON.stringify(doc);
+              reply.header("content-length", Buffer.byteLength(out));
+              return out;
+            }
+          } catch {
+            // Not a JSON document we can rewrite — leave the response untouched.
+          }
+          return payload;
+        });
+      }
       await this.app.register(apiReference, {
-        routePrefix: "/reference",
+        routePrefix: referencePrefix,
       });
     }
   }
@@ -201,9 +241,9 @@ class HttpServer implements ResourceInstance {
     // const resolveSchema = createSchemaResolver(this.ctx);
     for (const mount of mounts) {
       const prefix = mount.path || "";
-      // `mount.type` is the live Telo.Mount instance injected by the kernel at Phase 5
+      // `mount.mount` is the live Telo.Mount instance injected by the kernel at Phase 5
       // (x-telo-ref "telo#Mount") — a same-module or imported-library mount, uniformly.
-      const api = mount.type;
+      const api = mount.mount;
       if (!api || typeof api.register !== "function") {
         throw new Error(
           `Failed to mount at "${prefix}": mount target did not resolve to a Telo.Mount instance`,