@telorun/http-server 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @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

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.9.0
-  JS: std/javascript@0.4.1
+  Http: std/http-server@0.11.0
+  JS: std/javascript@0.5.0
 targets: [ !ref Server ]
 ---
 kind: Http.Server
@@ -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

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

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,
             });
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.10.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

@@ -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 }>;
@@ -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,
       });
     }
   }