@telorun/http-server 0.14.1 → 0.15.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @telorun/http-server
 
+## 0.15.1
+
+### Patch Changes
+
+- 06c675b: Fix CORS preflight returning 404. `Http.Server` forwarded every `cors` option to `@fastify/cors`, including the ones the manifest left unset — spreading `preflight: undefined` (and friends) clobbered the plugin's own default `preflight: true`, so its `OPTIONS *` handler `callNotFound()`'d and the preflight came back 404. Browsers reject that ("Response to preflight request … does not have HTTP ok status") and block every cross-origin `POST`. Now only the fields actually set on `cors` are passed through, so unset options keep the plugin's defaults and preflight replies 204.
+
+## 0.15.0
+
+### Minor Changes
+
+- a9ac4ba: Add optional `operationId`, `summary`, `description`, and `tags` fields to `Http.Api` routes. They are passed through to the underlying framework and rendered into the generated OpenAPI document.
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.1
+
 ## 0.14.1
 
 ### Patch Changes

package/README.md

@@ -8,6 +8,7 @@ Language- and framework-agnostic HTTP server for Telo. Declarative routes, schem
 - **OpenAPI-style paths** — `/users/{id}` syntax everywhere; the adapter translates to its native router.
 - **Schema-driven validation** — `request.schema` (`body`, `query`, `params`, `headers`) yields a standardized HTTP 400 with `details[]` on failure.
 - **Typed returns and catches** — render successful values and structured `InvokeError`s into status + headers + per-MIME bodies via CEL.
+- **OpenAPI operation metadata** — a route may declare `operationId`, `summary`, `description`, and `tags`; they are rendered into the generated OpenAPI document.
 - **Composable mounts** — attach `Telo.Mount` resources (HTTP APIs, MCP endpoints, custom mounts) under any path prefix.
 - **Serve a frontend** — `Http.Static` serves a directory of assets (a built SPA, plain HTML) so one application delivers both its API and its UI.
 - **CORS and content-type parsers** — first-class manifest fields; no controller code needed.

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

@@ -38,6 +38,10 @@ declare const HttpApiManifest: import("@sinclair/typebox").TObject<{
                 headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
             }>>>;
         }>>>;
+        operationId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        summary: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     }>>;
 }>;
 type HttpApiManifest = Static<typeof HttpApiManifest>;

package/dist/http-api-controller.js

@@ -17,6 +17,10 @@ const HttpApiRouteManifest = Type.Object({
     inputs: Type.Optional(Type.Record(Type.String(), Type.Any())),
     returns: Type.Array(ReturnEntry),
     catches: Type.Optional(Type.Array(CatchEntry)),
+    operationId: Type.Optional(Type.String()),
+    summary: Type.Optional(Type.String()),
+    description: Type.Optional(Type.String()),
+    tags: Type.Optional(Type.Array(Type.String())),
 });
 const HttpApiManifest = Type.Object({
     routes: Type.Array(HttpApiRouteManifest),
@@ -69,6 +73,16 @@ export class HttpServerApi {
             schema.body = route.request.schema.body;
         if (route.request.schema?.headers)
             schema.headers = route.request.schema.headers;
+        // OpenAPI operation metadata — @fastify/swagger reads these off the route
+        // schema and renders them into the generated document.
+        if (route.operationId)
+            schema.operationId = route.operationId;
+        if (route.summary)
+            schema.summary = route.summary;
+        if (route.description)
+            schema.description = route.description;
+        if (route.tags)
+            schema.tags = route.tags;
         // Response schemas: register the FIRST content[mime].schema we find for
         // each status. Multiple MIMEs per status all get the same response shape
         // (Fastify's response schema is per-status, not per-MIME); the per-MIME

package/dist/http-server-controller.js

@@ -73,20 +73,31 @@ class HttpServer {
             }
         }
         if (this.resource.cors) {
-            await this.app.register(cors, {
-                origin: this.resource.cors.origin,
-                methods: this.resource.cors.methods,
-                allowedHeaders: this.resource.cors.allowedHeaders,
-                exposedHeaders: this.resource.cors.exposedHeaders,
-                credentials: this.resource.cors.credentials,
-                maxAge: this.resource.cors.maxAge,
-                cacheControl: this.resource.cors.cacheControl,
-                preflightContinue: this.resource.cors.preflightContinue,
-                optionsSuccessStatus: this.resource.cors.optionsSuccessStatus,
-                preflight: this.resource.cors.preflight,
-                strictPreflight: this.resource.cors.strictPreflight,
-                hideOptionsRoute: this.resource.cors.hideOptionsRoute,
-            });
+            // Only forward the fields the manifest actually set. Spreading `undefined`
+            // for an unset option overrides @fastify/cors's own defaults with
+            // `undefined` — notably `preflight: undefined` disables the preflight 204
+            // reply (its `OPTIONS *` handler then `callNotFound()`s → 404), which a
+            // browser reports as "preflight … does not have HTTP ok status".
+            const cfg = this.resource.cors;
+            const corsOptions = {};
+            for (const key of [
+                "origin",
+                "methods",
+                "allowedHeaders",
+                "exposedHeaders",
+                "credentials",
+                "maxAge",
+                "cacheControl",
+                "preflightContinue",
+                "optionsSuccessStatus",
+                "preflight",
+                "strictPreflight",
+                "hideOptionsRoute",
+            ]) {
+                if (cfg[key] !== undefined)
+                    corsOptions[key] = cfg[key];
+            }
+            await this.app.register(cors, corsOptions);
         }
         // Register custom error handler for validation errors
         this.app.setErrorHandler((error, request, reply) => {

package/package.json

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

package/src/http-api-controller.ts

@@ -40,6 +40,10 @@ const HttpApiRouteManifest = Type.Object({
   inputs: Type.Optional(Type.Record(Type.String(), Type.Any())),
   returns: Type.Array(ReturnEntry),
   catches: Type.Optional(Type.Array(CatchEntry)),
+  operationId: Type.Optional(Type.String()),
+  summary: Type.Optional(Type.String()),
+  description: Type.Optional(Type.String()),
+  tags: Type.Optional(Type.Array(Type.String())),
 });
 type HttpApiRouteManifest = Static<typeof HttpApiRouteManifest>;
 
@@ -101,6 +105,13 @@ export class HttpServerApi implements ResourceInstance {
     if (route.request.schema?.body && !streamBody) schema.body = route.request.schema.body;
     if (route.request.schema?.headers) schema.headers = route.request.schema.headers;
 
+    // OpenAPI operation metadata — @fastify/swagger reads these off the route
+    // schema and renders them into the generated document.
+    if (route.operationId) schema.operationId = route.operationId;
+    if (route.summary) schema.summary = route.summary;
+    if (route.description) schema.description = route.description;
+    if (route.tags) schema.tags = route.tags;
+
     // Response schemas: register the FIRST content[mime].schema we find for
     // each status. Multiple MIMEs per status all get the same response shape
     // (Fastify's response schema is per-status, not per-MIME); the per-MIME

package/src/http-server-controller.ts

@@ -155,20 +155,30 @@ class HttpServer implements ResourceInstance {
     }
 
     if (this.resource.cors) {
-      await this.app.register(cors, {
-        origin: this.resource.cors.origin,
-        methods: this.resource.cors.methods,
-        allowedHeaders: this.resource.cors.allowedHeaders,
-        exposedHeaders: this.resource.cors.exposedHeaders,
-        credentials: this.resource.cors.credentials,
-        maxAge: this.resource.cors.maxAge,
-        cacheControl: this.resource.cors.cacheControl,
-        preflightContinue: this.resource.cors.preflightContinue,
-        optionsSuccessStatus: this.resource.cors.optionsSuccessStatus,
-        preflight: this.resource.cors.preflight,
-        strictPreflight: this.resource.cors.strictPreflight,
-        hideOptionsRoute: this.resource.cors.hideOptionsRoute,
-      });
+      // Only forward the fields the manifest actually set. Spreading `undefined`
+      // for an unset option overrides @fastify/cors's own defaults with
+      // `undefined` — notably `preflight: undefined` disables the preflight 204
+      // reply (its `OPTIONS *` handler then `callNotFound()`s → 404), which a
+      // browser reports as "preflight … does not have HTTP ok status".
+      const cfg = this.resource.cors;
+      const corsOptions: Record<string, unknown> = {};
+      for (const key of [
+        "origin",
+        "methods",
+        "allowedHeaders",
+        "exposedHeaders",
+        "credentials",
+        "maxAge",
+        "cacheControl",
+        "preflightContinue",
+        "optionsSuccessStatus",
+        "preflight",
+        "strictPreflight",
+        "hideOptionsRoute",
+      ] as const) {
+        if (cfg[key] !== undefined) corsOptions[key] = cfg[key];
+      }
+      await this.app.register(cors, corsOptions);
     }
 
     // Register custom error handler for validation errors