@telorun/http-server 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @telorun/http-server
 
+## 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
+
+- 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

package/README.md

@@ -24,28 +24,48 @@ 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.9.0
+  JS: std/javascript@0.4.1
+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 }
 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 }
+    handler: !ref Greet
     returns:
       - 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-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 `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>;
+}
 type CorsOptions = {
     origin?: string | boolean | string[];
     methods?: string | string[];
@@ -33,7 +40,7 @@ type HttpServerResource = RuntimeResource & {
     };
     mounts?: Array<{
         path?: string;
-        type?: string;
+        mount?: 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.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.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`);
             }
             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.1",
+  "version": "0.10.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-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 `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>;
+}
 
 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.
+    mount?: 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.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.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`,
+        );
       }
       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(() => {});
+    }
+  });
+});