@telorun/http-server 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @telorun/http-server
 
+## 0.9.0
+
+### Minor Changes
+
+- 8586b39: Resolve resource references uniformly across import boundaries and execution scopes.
+
+  - **http-server**: `mounts[].type` is now an injected `Telo.Mount` reference (`!ref <name>`, or `!ref <Alias>.<name>` for a mount exported by an imported library) instead of a dotted kind-string. The server consumes the live injected instance, so an `Http.Api` / `Mcp.HttpEndpoint` defined in another library can be mounted across the boundary. The bare `Kind.Name` string form is removed.
+  - **s3**: `bucketRef` is now an `x-telo-ref: "std/s3#Bucket"` slot (`!ref <bucket>` / `!ref <Alias>.<bucket>`); controllers consume the injected `S3.Bucket` instance, so S3 operations can reference a bucket exported by another library. The `{ name }` form is removed.
+  - **analyzer**: `resolveRefSentinels` recurses into `x-telo-scope` resources, so a `!ref` inside a scoped resource (e.g. a `Run.Sequence` `with:` server's mount) is canonicalized to `{kind, name}` like any top-level slot.
+  - **kernel**: Phase-5 dependency injection targets the (compile-CEL-expanded) resource the controller actually receives, so injected instances reach reference fields that also carry `x-telo-eval: compile` (e.g. `Http.Server.mounts`).
+  - **sdk**: `CreatedResource` gains an optional `resource`, letting a factory return the expanded manifest the controller was created with.
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.1
+
+## 0.8.1
+
+### Patch Changes
+
+- e3146f3: Fix spurious request cancellation (HTTP 499) for body-bearing requests whose handler awaits before replying. Per-request cancellation was wired to the request stream's `close` event, which fires as normal cleanup once a request body has been fully received — so any `PUT`/`POST` whose handler did async work (e.g. a DB query) before sending a response was cancelled mid-flight and answered with 499. Cancellation now listens on the response socket, which only closes early on a genuine client disconnect; normal completions and synchronous rejects are unaffected.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -38,7 +38,20 @@ mounts:
 kind: Http.Api
 metadata: { name: Api }
 routes:
-  - request: { method: GET, path: /hello/{name} }
+  # Declare request.schema and the response content.schema so the route is
+  # type-checked AND fully described in the generated OpenAPI document. Put
+  # `examples` on each field so the spec shows sample payloads.
+  - request:
+      method: GET
+      path: /hello/{name}
+      schema:
+        params:
+          type: object
+          properties:
+            name:
+              type: string
+              description: Name to greet.
+              examples: [ "Ada" ]
     inputs:
       name: "${{ request.params.name }}"
     handler: { kind: JS.Script, name: Greet }
@@ -46,6 +59,13 @@ routes:
       - status: 200
         content:
           application/json:
+            schema:
+              type: object
+              properties:
+                message:
+                  type: string
+                  description: The greeting.
+                  examples: [ "Hello, Ada!" ]
             body: { message: "${{ result.message }}" }
 ---
 kind: JS.Script

package/dist/http-api-controller.js

@@ -107,9 +107,13 @@ export class HttpServerApi {
                 };
                 const sink = fastifyReplySink(reply);
                 // Per-request cancellation: abandon downstream work when the client
-                // disconnects before the response is sent.
+                // disconnects before the response is sent. Listen on the response
+                // socket, not the request stream — the latter's `close` fires as normal
+                // cleanup once a request body has been fully received, which would
+                // cancel any body-bearing request that awaits (e.g. a DB call) before
+                // replying. The response socket only closes early on a real disconnect.
                 const cancellation = this.ctx.createCancellationSource();
-                request.raw.on("close", () => {
+                reply.raw.on("close", () => {
                     if (!reply.sent)
                         cancellation.cancel("client-disconnect");
                 });

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

@@ -1,5 +1,12 @@
 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
+ *  resolve to an imported library's exported mount — and every mountable exposes register(). */
+interface Mountable {
+    register(app: FastifyInstance, prefix: string): void | Promise<void>;
+}
 type CorsOptions = {
     origin?: string | boolean | string[];
     methods?: string | string[];
@@ -33,7 +40,7 @@ type HttpServerResource = RuntimeResource & {
     };
     mounts?: Array<{
         path?: string;
-        type?: string;
+        type?: Mountable;
     }>;
     notFoundHandler?: {
         invoke: KindRef<Invocable>;

package/dist/http-server-controller.js

@@ -118,12 +118,12 @@ class HttpServer {
         const mounts = this.resource.mounts || [];
         // const resolveSchema = createSchemaResolver(this.ctx);
         for (const mount of mounts) {
-            const type = mount.type || "";
-            const { kind, name } = parseType(type);
             const prefix = mount.path || "";
-            const api = this.ctx.moduleContext.getInstance(name);
-            if (!api) {
-                throw new Error(`Failed to mount Http.Api at "${prefix}": ${type} not found`);
+            // `mount.type` 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;
+            if (!api || typeof api.register !== "function") {
+                throw new Error(`Failed to mount at "${prefix}": mount target did not resolve to a Telo.Mount instance`);
             }
             api.register(this.app, prefix);
         }
@@ -234,13 +234,6 @@ export async function create(resource, ctx) {
     }
     return new HttpServer(resource, ctx, resolvedNotFoundHandler);
 }
-function parseType(type) {
-    const separator = type.lastIndexOf(".");
-    if (separator <= 0 || separator === type.length - 1) {
-        return { kind: "", name: "" };
-    }
-    return { kind: type.slice(0, separator), name: type.slice(separator + 1) };
-}
 /**
  * Converts Fastify validation errors to standardized Telo format
  * Returns null if the error is not a validation error

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.8.0",
+  "version": "0.9.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.19.0"
+    "@telorun/sdk": "0.23.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-api-controller.ts

@@ -148,9 +148,13 @@ export class HttpServerApi implements ResourceInstance {
         const sink = fastifyReplySink(reply);
 
         // Per-request cancellation: abandon downstream work when the client
-        // disconnects before the response is sent.
+        // disconnects before the response is sent. Listen on the response
+        // socket, not the request stream — the latter's `close` fires as normal
+        // cleanup once a request body has been fully received, which would
+        // cancel any body-bearing request that awaits (e.g. a DB call) before
+        // replying. The response socket only closes early on a real disconnect.
         const cancellation = this.ctx.createCancellationSource();
-        request.raw.on("close", () => {
+        reply.raw.on("close", () => {
           if (!reply.sent) cancellation.cancel("client-disconnect");
         });
 

package/src/http-server-controller.ts

@@ -18,7 +18,13 @@ import {
 import addFormats from "ajv-formats";
 import Fastify, { FastifyInstance } from "fastify";
 import { fastifyReplySink } from "./fastify-reply-sink.js";
-import { HttpServerApi } from "./http-api-controller.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
+ *  resolve to an imported library's exported mount — and every mountable exposes register(). */
+interface Mountable {
+  register(app: FastifyInstance, prefix: string): void | Promise<void>;
+}
 
 type CorsOptions = {
   origin?: string | boolean | string[];
@@ -50,7 +56,9 @@ type HttpServerResource = RuntimeResource & {
   };
   mounts?: Array<{
     path?: string;
-    type?: 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;
   }>;
   notFoundHandler?: {
     invoke: KindRef<Invocable>;
@@ -192,14 +200,14 @@ class HttpServer implements ResourceInstance {
     const mounts = this.resource.mounts || [];
     // const resolveSchema = createSchemaResolver(this.ctx);
     for (const mount of mounts) {
-      const type = mount.type || "";
-      const { kind, name } = parseType(type);
       const prefix = mount.path || "";
-
-      const api = this.ctx.moduleContext.getInstance(name) as unknown as HttpServerApi;
-
-      if (!api) {
-        throw new Error(`Failed to mount Http.Api at "${prefix}": ${type} not found`);
+      // `mount.type` 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;
+      if (!api || typeof api.register !== "function") {
+        throw new Error(
+          `Failed to mount at "${prefix}": mount target did not resolve to a Telo.Mount instance`,
+        );
       }
       api.register(this.app, prefix);
     }
@@ -341,14 +349,6 @@ export async function create(
   return new HttpServer(resource, ctx, resolvedNotFoundHandler);
 }
 
-function parseType(type: string): { kind: string; name: string } {
-  const separator = type.lastIndexOf(".");
-  if (separator <= 0 || separator === type.length - 1) {
-    return { kind: "", name: "" };
-  }
-  return { kind: type.slice(0, separator), name: type.slice(separator + 1) };
-}
-
 /**
  * Converts Fastify validation errors to standardized Telo format
  * Returns null if the error is not a validation error

package/tests/request-cancel.test.ts

@@ -0,0 +1,98 @@
+import { ERR_INVOKE_CANCELLED, InvokeError, createCancellationSource } from "@telorun/sdk";
+import Fastify from "fastify";
+import net from "node:net";
+import type { AddressInfo } from "node:net";
+import { describe, expect, it } from "vitest";
+import { create } from "../src/http-api-controller.js";
+
+/**
+ * The route handler must be cancelled when the client disconnects before the
+ * response is sent. The controller wires per-request cancellation to the
+ * response socket's `close`; this drives the real controller end-to-end (real
+ * Fastify, real socket) and asserts the cancellation token reached the handler.
+ *
+ * Node-only by nature: Bun's `node:http` does not fire the response-socket
+ * `close` before the response on a disconnect, so this can't be observed there.
+ * That's why it lives here (vitest, run under Node) rather than as a YAML test
+ * in the Bun-run suite. The bug fix it guards — cancelling on the *response*
+ * socket so a fully-read-but-still-connected request is NOT spuriously
+ * cancelled — is exercised by the registry e2e on both runtimes.
+ */
+describe("http-server request cancellation", () => {
+  it("cancels the handler when the client disconnects mid-request", async () => {
+    let handlerEntered = false;
+    let handlerCancelled = false;
+
+    const handler = {
+      async invoke(_input: unknown, invokeCtx?: { cancellation?: any }) {
+        handlerEntered = true;
+        await new Promise<void>((resolve, reject) => {
+          const timer = setTimeout(resolve, 3000);
+          invokeCtx?.cancellation?.onCancelled(() => {
+            clearTimeout(timer);
+            handlerCancelled = true;
+            reject(new InvokeError(ERR_INVOKE_CANCELLED, "cancelled while waiting"));
+          });
+        });
+        return { ok: true };
+      },
+      snapshot: () => ({}),
+    };
+
+    // Minimal ResourceContext: just the surface the controller touches.
+    const ctx = {
+      validateSchema: () => {},
+      resolveChildren: () => ({ kind: "Test.Handler", name: "SlowWork" }),
+      moduleContext: { expandWith: (value: unknown) => value },
+      createCancellationSource: () => createCancellationSource(),
+      invokeResolved: (_kind: string, _name: string, h: typeof handler, input: unknown, c: unknown) =>
+        h.invoke(input, c as { cancellation?: any }),
+      emitEvent: () => {},
+    } as unknown as Parameters<typeof create>[1];
+
+    const resource = {
+      metadata: { name: "SlowApi", module: "test" },
+      routes: [
+        {
+          request: { path: "/slow", method: "PUT", schema: { body: { type: "string" } } },
+          handler,
+          inputs: {},
+          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 {
+      await new Promise<void>((resolve, reject) => {
+        const socket = net.connect({ host: "127.0.0.1", port });
+        socket.on("error", reject);
+        socket.on("connect", () => {
+          const body = "x";
+          socket.write(
+            `PUT /slow HTTP/1.1\r\nHost: 127.0.0.1:${port}\r\n` +
+              `Content-Type: text/plain\r\nContent-Length: ${body.length}\r\n\r\n${body}`,
+          );
+          // Let the handler enter its wait, then hard-close (real disconnect).
+          setTimeout(() => {
+            socket.destroy();
+            resolve();
+          }, 200);
+        });
+      });
+
+      // Allow the response-socket close → cancellation → handler rejection to settle.
+      await new Promise((r) => setTimeout(r, 400));
+
+      expect(handlerEntered).toBe(true);
+      expect(handlerCancelled).toBe(true);
+    } finally {
+      await app.close().catch(() => {});
+    }
+  });
+});