@telorun/http-server 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @telorun/http-server
 
+## 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
+
+- dded615: Templated definitions can now produce a mountable HTTP surface, and their dispatch targets are created once instead of per call.
+
+  - **`mount:` template dispatch** — a `Telo.Definition` with `capability: Telo.Mount` may declare `mount: <child>` (sibling to `invoke:` / `run:` / `provide:`) naming a `resources:` entry that is itself a `Telo.Mount` (e.g. an `Http.Api`). The template instance's `register()` delegates to that persistent child, so a library can ship a self-contained, declarative HTTP resource. The analyzer validates the new field (`MOUNT_ON_NON_MOUNT`, `MOUNT_DISPATCHER_CONFLICT`, `MOUNT_TARGET_UNKNOWN`, `MOUNT_TARGET_NOT_MOUNTABLE`).
+  - **Persistent dispatch targets** — the template controller no longer re-creates its `invoke:` / `run:` / `provide:` target on every call (`withEphemeral` is removed). Every `resources:` entry is created once at `init()` and reused; per-call data flows exclusively through the top-level `inputs:` sibling. A resource body may reference only `self`; `${{ inputs.* }}` inside a target body is no longer supported (move it to the top-level `inputs:`).
+  - **Library-scoped child resolution** — a template's `resources:` are spawned in a child context rooted on the _defining_ library's module context (new `EvaluationContext.spawnChildContext()`), so their internal kind aliases and `!ref`s resolve against the library's own imports rather than the consumer's.
+  - **http-server** — a route declared at `/` now sits at the mount root (`/todos` + `/` → `/todos`) instead of a trailing-slash variant Fastify treats as a distinct, unmatched URL, so collection-style mounts respond at the mount path itself.
+  - @telorun/http-dispatch@0.4.1
+
 ## 0.14.0
 
 ### Minor 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),
@@ -55,7 +59,7 @@ export class HttpServerApi {
         const handlerRef = this.handlerRefs.get(route);
         const handlerKind = handlerRef?.kind ?? "";
         const handlerName = handlerRef?.name ?? "";
-        const translatedPath = prefix + translateOpenApiPath(route.request.path);
+        const translatedPath = joinMountPath(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
@@ -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
@@ -205,6 +219,15 @@ function normalizeMountPrefix(prefix) {
         return "";
     return prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
 }
+/** Join a normalized mount prefix with a translated route path. A collection
+ *  route declared at `/` sits at the mount root itself (`/todos` + `/` → `/todos`),
+ *  not a trailing-slash variant Fastify would treat as a distinct, unmatched URL.
+ *  An empty prefix (root mount) keeps `/`. */
+function joinMountPath(prefix, path) {
+    if (path === "/")
+        return prefix || "/";
+    return prefix + path;
+}
 /**
  * Wraps an incoming request's raw body as a `Stream<Uint8Array>`. Requires a
  * stream content-type parser (`contentTypeParsers[].stream`) for the request's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "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.34.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>;
 
@@ -87,7 +91,7 @@ export class HttpServerApi implements ResourceInstance {
     const handlerRef = this.handlerRefs.get(route as unknown as object);
     const handlerKind = handlerRef?.kind ?? "";
     const handlerName = handlerRef?.name ?? "";
-    const translatedPath = prefix + translateOpenApiPath(route.request.path);
+    const translatedPath = joinMountPath(prefix, translateOpenApiPath(route.request.path));
 
     const schema: any = { response: {} };
 
@@ -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
@@ -269,6 +280,15 @@ function normalizeMountPrefix(prefix: string): string {
   return prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
 }
 
+/** Join a normalized mount prefix with a translated route path. A collection
+ *  route declared at `/` sits at the mount root itself (`/todos` + `/` → `/todos`),
+ *  not a trailing-slash variant Fastify would treat as a distinct, unmatched URL.
+ *  An empty prefix (root mount) keeps `/`. */
+function joinMountPath(prefix: string, path: string): string {
+  if (path === "/") return prefix || "/";
+  return prefix + path;
+}
+
 /**
  * Wraps an incoming request's raw body as a `Stream<Uint8Array>`. Requires a
  * stream content-type parser (`contentTypeParsers[].stream`) for the request's