@telorun/http-server 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @telorun/http-server
 
+## 0.12.0
+
+### Minor Changes
+
+- a8c99ab: Generic dispatch tracing: trace every capability dispatch (invoke and run) through one instrumented chokepoint and carry trace data in a structured event payload instead of the event name.
+
+  - Dispatch events drop the kind from the name (`<name>.Invoked` / `.Run`, plus error/cancel variants). The payload now carries `{ spanId, parentSpanId, capability, phase, outcome, ref: { kind, name }, … }`; consumers read the payload and never parse the dotted name. Lifecycle events (`Kind.name.Created` / `.Initialized` / `.Teardown`) are unchanged.
+  - `run()` is now span-instrumented like `invoke()`: it mints and propagates a trace id, so Runnables (e.g. a `Run.Sequence` boot target) appear in the trace and their nested invokes re-parent correctly instead of detaching as false roots. Long-lived Services emit a `<name>.Running` start span. Run failures emit `<name>.RunFailed` (rethrown, never swallowed).
+  - Invoke/run emit a `<name>.Invoking` / `.Running` start span when tracing is on.
+  - SDK: new `REF_IDENTITY` / `stampRefIdentity` / `getRefIdentity`. The kernel stamps a resolved `!ref`'s kind+name onto the injected instance so `executeInvokeStep` routes pre-injected live instances through the traced chokepoint instead of calling `.invoke()` directly and escaping instrumentation.
+  - The boot `targets` run is wrapped in an application span (`<appName>.Run`, `ref.kind: "Telo.Application"`), so the application is the trace root with its targets nested beneath. Pre-resolved `!ref` boot targets now dispatch through a new `EvaluationContext.runResolved` (the `run()` analog of `invokeResolved`) instead of calling `instance.run()` directly, so they emit their own run spans nested under the app.
+  - A `Telo.Service`'s long-lived `run()` no longer establishes the cancellation/trace ALS scope (its token is delivered via the explicit `run(invokeCtx)` argument instead). This stops the boot scope leaking onto async resources the service creates — e.g. an HTTP server's socket — so inbound work (each request) starts as its own root trace with no inherited boot cancellation token, instead of nesting under the bootstrap trace. Runnables keep the ALS scope so their steps still nest and inherit cancellation.
+  - `EventBus.emit` short-circuits in O(1) when there are no subscribers, keeping the always-through-the-chokepoint dispatch effectively free when nobody is listening.
+  - OpenTelemetry-ready trace model: every span carries a `traceId` (OTel-compatible 16-byte hex), minted at the root and inherited by descendants, so an exporter groups a trace without walking the parent chain. New generic `ctx.openSpan(base, { ref, label, attributes, inbound? })` primitive opens an inbound-boundary span (capability `"request"`) that roots its own trace; `inbound` allows continuing an upstream distributed trace later. The `TracePayload` gains `traceId`, `label`, and `attributes`.
+  - `http-server`: each inbound request opens a request span attributed to the `Http.Api` and labelled with the route (`"POST /feedback"`, attributes `{ method, path }`); the handler invoke and its subtree nest under it, as a trace separate from the bootstrap.
+  - Trace context capture: a trace's root span carries `payload.context` — a redacted snapshot of the CEL root scope available to the trace (`variables`, `resources` snapshots, `ports`, and `secrets` with values masked to `"[secret]"`; host `env` omitted). Lets a debug consumer see what data an execution could reference beyond its own inputs/outputs. The UI renders it as an "Available context" section on the root node.
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.1
+
 ## 0.11.1
 
 ### Patch 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.12.0
-  JS: std/javascript@0.5.0
+  Http: std/http-server@<version>
+  JS: std/javascript@<version>
 targets: [ !ref Server ]
 ---
 kind: Http.Server

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

@@ -51,7 +51,8 @@ export declare class HttpServerApi implements ResourceInstance {
     private readonly ctx;
     readonly manifest: HttpApiManifest;
     private readonly handlerRefs;
-    constructor(ctx: ResourceContext, manifest: HttpApiManifest, handlerRefs: WeakMap<object, HandlerRef>);
+    private readonly apiName;
+    constructor(ctx: ResourceContext, manifest: HttpApiManifest, handlerRefs: WeakMap<object, HandlerRef>, apiName: string);
     init(): Promise<void>;
     register(app: FastifyInstance, prefix?: string): void;
     private registerRoutes;

package/dist/http-api-controller.js

@@ -26,10 +26,12 @@ export class HttpServerApi {
     ctx;
     manifest;
     handlerRefs;
-    constructor(ctx, manifest, handlerRefs) {
+    apiName;
+    constructor(ctx, manifest, handlerRefs, apiName) {
         this.ctx = ctx;
         this.manifest = manifest;
         this.handlerRefs = handlerRefs;
+        this.apiName = apiName;
     }
     async init() { }
     register(app, prefix = "") {
@@ -118,22 +120,35 @@ export class HttpServerApi {
                     if (!reply.sent)
                         cancellation.cancel("client-disconnect");
                 });
+                // Open a request span rooting this request's own trace: the handler (and
+                // its nested invokes) nest under it, and it's labelled with the route so
+                // the trace shows the actual method+path, attributed to this Http.Api.
+                const span = await this.ctx.openSpan(cancellation.context, {
+                    ref: { kind: "Http.Api", name: this.apiName },
+                    label: `${route.request.method} ${route.request.path}`,
+                    attributes: { method: route.request.method, path: route.request.path },
+                });
                 let result;
                 try {
                     result = handler
-                        ? await this.ctx.invokeResolved(handlerKind, handlerName, handler, invokeInput, cancellation.context)
+                        ? await this.ctx.invokeResolved(handlerKind, handlerName, handler, invokeInput, span.context)
                         : undefined;
                 }
                 catch (err) {
                     if (isCancellationError(err)) {
+                        await span.settle("cancelled");
                         if (!reply.sent)
                             reply.code(499).send();
                         return;
                     }
-                    if (!isInvokeError(err))
+                    if (!isInvokeError(err)) {
+                        await span.settle("failed");
                         throw err;
+                    }
+                    await span.settle("rejected");
                     return dispatchCatches(route.catches, { code: err.code, message: err.message, data: err.data }, requestContext, acceptHeader, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), sink);
                 }
+                await span.settle("ok");
                 return dispatchReturns(route.returns, result, requestContext, acceptHeader, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), sink, (err, errCtx) => this.ctx.emitEvent("Http.Api.streamFailed", {
                     path: route.request.path,
                     method: route.request.method,
@@ -169,7 +184,7 @@ export async function create(resource, ctx) {
             handlerRefs.set(route, { kind: "", name: h });
         }
     }
-    return new HttpServerApi(ctx, resource, handlerRefs);
+    return new HttpServerApi(ctx, resource, handlerRefs, resource?.metadata?.name ?? "");
 }
 /**
  * Translates OpenAPI path format {paramName} to Fastify format :paramName

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.11.1",
+  "version": "0.12.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.31.0"
+    "@telorun/sdk": "0.32.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-api-controller.ts

@@ -59,6 +59,7 @@ export class HttpServerApi implements ResourceInstance {
     private readonly ctx: ResourceContext,
     readonly manifest: HttpApiManifest,
     private readonly handlerRefs: WeakMap<object, HandlerRef>,
+    private readonly apiName: string,
   ) {}
 
   async init() {}
@@ -159,6 +160,15 @@ export class HttpServerApi implements ResourceInstance {
           if (!reply.sent) cancellation.cancel("client-disconnect");
         });
 
+        // Open a request span rooting this request's own trace: the handler (and
+        // its nested invokes) nest under it, and it's labelled with the route so
+        // the trace shows the actual method+path, attributed to this Http.Api.
+        const span = await this.ctx.openSpan(cancellation.context, {
+          ref: { kind: "Http.Api", name: this.apiName },
+          label: `${route.request.method} ${route.request.path}`,
+          attributes: { method: route.request.method, path: route.request.path },
+        });
+
         let result: unknown;
         try {
           result = handler
@@ -167,15 +177,20 @@ export class HttpServerApi implements ResourceInstance {
                 handlerName,
                 handler,
                 invokeInput,
-                cancellation.context,
+                span.context,
               )
             : undefined;
         } catch (err) {
           if (isCancellationError(err)) {
+            await span.settle("cancelled");
             if (!reply.sent) reply.code(499).send();
             return;
           }
-          if (!isInvokeError(err)) throw err;
+          if (!isInvokeError(err)) {
+            await span.settle("failed");
+            throw err;
+          }
+          await span.settle("rejected");
           return dispatchCatches(
             route.catches,
             { code: err.code, message: err.message, data: err.data },
@@ -187,6 +202,7 @@ export class HttpServerApi implements ResourceInstance {
           );
         }
 
+        await span.settle("ok");
         return dispatchReturns(
           route.returns,
           result,
@@ -232,7 +248,7 @@ export async function create(resource: any, ctx: ResourceContext): Promise<HttpS
       handlerRefs.set(route, { kind: "", name: h });
     }
   }
-  return new HttpServerApi(ctx, resource, handlerRefs);
+  return new HttpServerApi(ctx, resource, handlerRefs, resource?.metadata?.name ?? "");
 }
 
 /**

package/tests/request-cancel.test.ts

@@ -48,6 +48,7 @@ describe("http-server request cancellation", () => {
       invokeResolved: (_kind: string, _name: string, h: typeof handler, input: unknown, c: unknown) =>
         h.invoke(input, c as { cancellation?: any }),
       emitEvent: () => {},
+      openSpan: async (base: unknown) => ({ context: base, settle: async () => {} }),
     } as unknown as Parameters<typeof create>[1];
 
     const resource = {

package/tests/request-span.test.ts

@@ -0,0 +1,82 @@
+import { createCancellationSource } from "@telorun/sdk";
+import Fastify from "fastify";
+import type { AddressInfo } from "node:net";
+import { describe, expect, it } from "vitest";
+import { create } from "../src/http-api-controller.js";
+
+/**
+ * Each inbound request opens a trace span attributed to the Http.Api and labelled
+ * with the route, under which the handler invoke nests. This drives the real
+ * controller (real Fastify) with a mock ResourceContext that captures the
+ * `openSpan` call, asserting the controller passes the route's `{kind,name}`,
+ * label and `{method,path}` attributes — and settles the span on success.
+ *
+ * The generic span mechanics (rooting a detached trace, nesting, trace id) are a
+ * kernel concern, tested there; this test owns only the HTTP-specific wiring.
+ */
+describe("http-server request span", () => {
+  it("opens a route-labelled span and dispatches the handler under it", async () => {
+    const spanCalls: any[] = [];
+    const settled: string[] = [];
+
+    const handler = {
+      async invoke(input: unknown) {
+        return { echoed: (input as { value: number }).value };
+      },
+      snapshot: () => ({}),
+    };
+
+    const ctx = {
+      validateSchema: () => {},
+      resolveChildren: () => ({ kind: "JS.Script", name: "Echo" }),
+      moduleContext: { expandWith: (value: unknown) => value },
+      createCancellationSource: () => createCancellationSource(),
+      invokeResolved: (_kind: string, _name: string, h: typeof handler, input: unknown) =>
+        h.invoke(input),
+      emitEvent: () => {},
+      openSpan: async (base: unknown, opts: unknown) => {
+        spanCalls.push(opts);
+        return {
+          context: base,
+          settle: async (outcome: string) => {
+            settled.push(outcome);
+          },
+        };
+      },
+    } as unknown as Parameters<typeof create>[1];
+
+    const resource = {
+      metadata: { name: "EchoApi", module: "test" },
+      routes: [
+        {
+          request: { path: "/echo", method: "GET" },
+          handler,
+          inputs: { value: 1 },
+          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 {
+      const res = await fetch(`http://127.0.0.1:${port}/echo`);
+      expect(res.status).toBe(200);
+      await res.json();
+
+      expect(spanCalls).toHaveLength(1);
+      expect(spanCalls[0]).toEqual({
+        ref: { kind: "Http.Api", name: "EchoApi" },
+        label: "GET /echo",
+        attributes: { method: "GET", path: "/echo" },
+      });
+      expect(settled).toEqual(["ok"]);
+    } finally {
+      await app.close().catch(() => {});
+    }
+  });
+});