@telorun/http-server 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @telorun/http-server
 
+## 0.18.0
+
+### Minor Changes
+
+- d23de89: Layered module artifacts: a published module is now one artifact of several layers instead of one tarball, and each layer is materialized only when something needs it.
+
+  `telo.yaml` gets its own layer, so reading a manifest no longer downloads (and discards) the whole payload. The rest of `files:` is partitioned into one layer per bundled-controller selector — `format` plus optional `os`/`arch`/`libc` PURL qualifiers — plus an `assets` layer for what the new optional `assets:` list claims and a `common` layer for everything else. A Node kernel never fetches a `napi` layer, a `linux/amd64` host never fetches the `darwin/arm64` binary, and an app that imports a module for its API alone never fetches its frontend.
+
+  This fixes a cold-start failure: bundled controllers used to resolve against an `oci://` base URI that was read as a filesystem path, because the payload was written to disk by a CLI hook running _after_ `kernel.load()`. The first run of any OCI-imported module with bundled controllers failed and the second succeeded. Controller layers now materialize at resolve time through a module-scoped `ModuleArtifact`, built during load where the pinned import ref and the verified manifest are both available — so verification stays anchored to the importer's `#sha256-` pin rather than to whatever is in the cache.
+
+  `ctx.resolveModuleFile(relative)` is the new, URI-returning way to reach a file that ships with a module; it materializes the asset layer on first use. `Http.Static`, `mcp-client`, `assert`'s manifest loader and `Test.Suite` all use it, which also fixes a silent bug where a non-`file://` module resolved a relative root against the process working directory and served the wrong directory instead of failing.
+
+  Also: `telo install --platform os/arch[/libc]` pre-fetches layers for a platform other than the build machine's, the layer index and selector grammar are specified normatively in `kernel/specs/module-artifact.md`, and the cross-process cache lock is shared between the npm loader and layer materialization instead of duplicated.
+
+  Modules published before layers keep resolving: the manifest read path still accepts a single-blob artifact, which contains `telo.yaml` — so nothing that ships no payload needs anything done to it, and npm-backed modules are entirely unaffected. What such an artifact cannot supply is a layer index, so a module that _does_ ship a payload resolves its manifest and then fails at the controller with an actionable "republish" error. That is the six modules shipping `files:` — `oauth-client`, `scheduler`, `kv-store-memory`, `kv-store-redis`, `kv-store-sql`, `idempotency` — which must be republished, with consumers bumping to the new versions.
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.2
+
+## 0.17.1
+
+### Patch Changes
+
+- Updated dependencies [f3b044d]
+  - @telorun/http-dispatch@0.4.2
+
 ## 0.17.0
 
 ### Minor Changes

package/README.md

@@ -27,8 +27,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@<version>
-  JS: std/javascript@<version>
+  Http: std/http-server@0.19.1
+  JS: std/javascript@0.7.0
 targets: [ !ref Server ]
 ---
 kind: Http.Server
@@ -56,7 +56,7 @@ routes:
               description: Name to greet.
               examples: [ "Ada" ]
     inputs:
-      name: "${{ request.params.name }}"
+      name: !cel "request.params.name"
     handler: !ref Greet
     returns:
       - status: 200
@@ -69,7 +69,7 @@ routes:
                   type: string
                   description: The greeting.
                   examples: [ "Hello, Ada!" ]
-            body: { message: "${{ result.message }}" }
+            body: { message: !cel "result.message" }
 ---
 kind: JS.Script
 metadata: { name: Greet }

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

@@ -2,7 +2,7 @@ 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
+ *  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>;

package/dist/http-server-controller.js

@@ -189,7 +189,7 @@ class HttpServer {
         for (const mount of mounts) {
             const prefix = mount.path || "";
             // `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.
+            // (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`);

package/dist/http-static-controller.js

@@ -1,6 +1,6 @@
 import fastifyStatic from "@fastify/static";
 import { readFile } from "node:fs/promises";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 /** Collapse a mount prefix to a single leading slash with no trailing slash;
  *  an empty/`"/"` prefix becomes `"/"`. Unlike Http.Api (which returns `""` and
@@ -23,8 +23,8 @@ class HttpStatic {
     spaFallback;
     maxAge;
     immutable;
-    constructor(resource, ctx) {
-        this.root = resolveRoot(resource.root, ctx);
+    constructor(resource, root) {
+        this.root = root;
         this.index = resource.index ?? "index.html";
         this.spaFallback = resource.spaFallback === true;
         this.maxAge = resource.maxAge;
@@ -76,17 +76,33 @@ class HttpStatic {
         }, { prefix: mountPrefix });
     }
 }
-/** Resolve the asset root relative to the manifest that declared the resource, so
- *  the frontend ships co-located with the app (same pattern as mcp-client). */
-function resolveRoot(root, ctx) {
+/**
+ * Resolve the asset root against the declaring module's own directory, so the
+ * frontend ships co-located with the app.
+ *
+ * `ctx.resolveModuleFile` is the only correct way to do this: for a published
+ * module the manifest URL is not where its payload lives, and it also materializes
+ * the module's asset layer on first access. Deriving the directory from
+ * `moduleContext.source` by hand silently fell back to the process working
+ * directory for any non-`file://` module — serving the wrong files instead of
+ * failing.
+ */
+async function resolveRoot(root, ctx) {
     if (isAbsolute(root))
         return root;
-    const source = ctx.moduleContext.source;
-    if (!source.startsWith("file://"))
-        return resolve(root);
-    const baseDir = dirname(fileURLToPath(source));
-    return resolve(baseDir, root);
+    // A directory reference: the trailing slash keeps URL resolution from treating
+    // the last segment as a sibling file.
+    // A module whose files cannot be located raises its own actionable error from
+    // `resolveModuleFile` (naming republication), so this only guards a scheme that
+    // resolved fine but is not servable from disk.
+    const uri = await ctx.resolveModuleFile(root.endsWith("/") ? root : `${root}/`);
+    if (!uri.startsWith("file://")) {
+        throw new Error(`Http.Static root '${root}' resolved to '${uri}'. A static root must be a local ` +
+            `directory, and this runtime can only serve files from one.`);
+    }
+    // Strip the trailing separator the directory form introduced.
+    return resolve(fileURLToPath(uri));
 }
 export async function create(resource, ctx) {
-    return new HttpStatic(resource, ctx);
+    return new HttpStatic(resource, await resolveRoot(resource.root, ctx));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Telo HTTP Server module - HTTP server and API resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -49,13 +49,13 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "fastify": "^5.7.2",
-    "@telorun/http-dispatch": "0.4.1"
+    "@telorun/http-dispatch": "0.4.2"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.54.0"
+    "@telorun/sdk": "0.60.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-server-controller.ts

@@ -22,7 +22,7 @@ import Fastify, { FastifyInstance } from "fastify";
 import { fastifyReplySink } from "./fastify-reply-sink.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
+ *  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>;
@@ -59,7 +59,7 @@ type HttpServerResource = RuntimeResource & {
   };
   mounts?: Array<{
     path?: string;
-    // x-telo-ref "telo#Mount": Phase 5 replaces this slot with the live mounted
+    // x-telo-ref `Telo.Mount`: Phase 5 replaces this slot with the live mounted
     // instance (Http.Api, Mcp.HttpEndpoint, …), local or imported.
     mount?: Mountable;
   }>;
@@ -270,7 +270,7 @@ class HttpServer implements ResourceInstance {
     for (const mount of mounts) {
       const prefix = mount.path || "";
       // `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.
+      // (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(

package/src/http-static-controller.ts

@@ -2,7 +2,7 @@ import fastifyStatic from "@fastify/static";
 import { type ResourceContext, type ResourceInstance, type RuntimeResource } from "@telorun/sdk";
 import { FastifyInstance } from "fastify";
 import { readFile } from "node:fs/promises";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 type HttpStaticResource = RuntimeResource & {
@@ -35,8 +35,8 @@ class HttpStatic implements ResourceInstance {
   private readonly maxAge?: number;
   private readonly immutable: boolean;
 
-  constructor(resource: HttpStaticResource, ctx: ResourceContext) {
-    this.root = resolveRoot(resource.root, ctx);
+  constructor(resource: HttpStaticResource, root: string) {
+    this.root = root;
     this.index = resource.index ?? "index.html";
     this.spaFallback = resource.spaFallback === true;
     this.maxAge = resource.maxAge;
@@ -95,19 +95,38 @@ class HttpStatic implements ResourceInstance {
   }
 }
 
-/** Resolve the asset root relative to the manifest that declared the resource, so
- *  the frontend ships co-located with the app (same pattern as mcp-client). */
-function resolveRoot(root: string, ctx: ResourceContext): string {
+/**
+ * Resolve the asset root against the declaring module's own directory, so the
+ * frontend ships co-located with the app.
+ *
+ * `ctx.resolveModuleFile` is the only correct way to do this: for a published
+ * module the manifest URL is not where its payload lives, and it also materializes
+ * the module's asset layer on first access. Deriving the directory from
+ * `moduleContext.source` by hand silently fell back to the process working
+ * directory for any non-`file://` module — serving the wrong files instead of
+ * failing.
+ */
+async function resolveRoot(root: string, ctx: ResourceContext): Promise<string> {
   if (isAbsolute(root)) return root;
-  const source = ctx.moduleContext.source;
-  if (!source.startsWith("file://")) return resolve(root);
-  const baseDir = dirname(fileURLToPath(source));
-  return resolve(baseDir, root);
+  // A directory reference: the trailing slash keeps URL resolution from treating
+  // the last segment as a sibling file.
+  // A module whose files cannot be located raises its own actionable error from
+  // `resolveModuleFile` (naming republication), so this only guards a scheme that
+  // resolved fine but is not servable from disk.
+  const uri = await ctx.resolveModuleFile(root.endsWith("/") ? root : `${root}/`);
+  if (!uri.startsWith("file://")) {
+    throw new Error(
+      `Http.Static root '${root}' resolved to '${uri}'. A static root must be a local ` +
+        `directory, and this runtime can only serve files from one.`,
+    );
+  }
+  // Strip the trailing separator the directory form introduced.
+  return resolve(fileURLToPath(uri));
 }
 
 export async function create(
   resource: HttpStaticResource,
   ctx: ResourceContext,
 ): Promise<ResourceInstance> {
-  return new HttpStatic(resource, ctx);
+  return new HttpStatic(resource, await resolveRoot(resource.root, ctx));
 }