@telorun/http-server 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @telorun/http-server
 
+## 0.14.0
+
+### Minor Changes
+
+- ca095ac: Add `Http.Static`, a `Telo.Mount` that serves a directory of static assets (a built SPA, plain HTML, images, …). Mount it on an `Http.Server` alongside an `Http.Api` so one application delivers both its API and its frontend. Supports a manifest-relative `root` (assets ship with the app), `index`, `spaFallback` for client-side routing, and `maxAge` / `immutable` cache control. Backed by `@fastify/static` (MIME, ETag, conditional and range requests).
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.1
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -9,6 +9,7 @@ Language- and framework-agnostic HTTP server for Telo. Declarative routes, schem
 - **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.
 - **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.
 
 ## Kinds
@@ -17,6 +18,7 @@ Language- and framework-agnostic HTTP server for Telo. Declarative routes, schem
 | --- | --- |
 | `Http.Server` | Long-lived HTTP listener that hosts mounts on configured paths and ports. |
 | `Http.Api` | Mountable router exposing route definitions with returns/catches rendering. |
+| `Http.Static` | Mountable static-file server for a directory of assets (built SPA, plain HTML, images). |
 
 ## Example
 
@@ -77,6 +79,7 @@ code: |
 ## Reference
 
 - [`Http.Server` / `Http.Api` returns & catches](docs/returns-and-catches.md) — outcome lists, MIME negotiation, stream mode.
+- [Serving static files & frontends](docs/static-files.md) — `Http.Static`, manifest-relative roots, SPA fallback, asset caching.
 
 ## Implementation Contract
 

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

@@ -0,0 +1,10 @@
+import { type ResourceContext, type ResourceInstance, type RuntimeResource } from "@telorun/sdk";
+type HttpStaticResource = RuntimeResource & {
+    root: string;
+    index?: string;
+    spaFallback?: boolean;
+    maxAge?: number;
+    immutable?: boolean;
+};
+export declare function create(resource: HttpStaticResource, ctx: ResourceContext): Promise<ResourceInstance>;
+export {};

package/dist/http-static-controller.js

@@ -0,0 +1,92 @@
+import fastifyStatic from "@fastify/static";
+import { readFile } from "node:fs/promises";
+import { dirname, 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
+ *  concatenates the prefix onto each route path on the root app), this serves
+ *  from an encapsulated `register({ prefix })`, which needs a non-empty prefix —
+ *  hence root maps to `"/"`, not `""`. */
+function normalizeMountPrefix(prefix) {
+    const trimmed = prefix.replace(/\/+$/, "");
+    if (!trimmed)
+        return "/";
+    return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+/** Serves a directory of static assets (a built SPA, plain HTML, images, …) as a
+ *  Telo.Mount. Mirrors Http.Api's `register(app, prefix)` contract so it slots into
+ *  Http.Server.mounts identically. Backed by @fastify/static, which handles MIME,
+ *  ETag, conditional requests, and range requests. */
+class HttpStatic {
+    root;
+    index;
+    spaFallback;
+    maxAge;
+    immutable;
+    constructor(resource, ctx) {
+        this.root = resolveRoot(resource.root, ctx);
+        this.index = resource.index ?? "index.html";
+        this.spaFallback = resource.spaFallback === true;
+        this.maxAge = resource.maxAge;
+        this.immutable = resource.immutable === true;
+    }
+    async init() { }
+    register(app, prefix = "") {
+        const mountPrefix = normalizeMountPrefix(prefix);
+        const root = this.root;
+        const index = this.index;
+        const spaFallback = this.spaFallback;
+        const cacheControl = this.maxAge != null;
+        // @fastify/static takes maxAge in milliseconds; the manifest declares seconds.
+        const maxAge = this.maxAge != null ? this.maxAge * 1000 : undefined;
+        const immutable = this.immutable;
+        // Encapsulated scope so the static plugin, its routes, and the SPA not-found
+        // handler are confined to this mount's prefix and don't collide with sibling
+        // mounts or the server-level notFoundHandler. `decorateReply: false` keeps
+        // multiple static mounts from fighting over the shared `reply.sendFile`
+        // decorator — the SPA fallback reads the index file directly instead.
+        app.register(async (scope) => {
+            await scope.register(fastifyStatic, {
+                root,
+                prefix: "/",
+                index,
+                // With spaFallback we want unmatched paths to fall through to the
+                // not-found handler (client-side routing); the wildcard glob route
+                // would otherwise 404 them itself.
+                wildcard: !spaFallback,
+                cacheControl,
+                maxAge,
+                immutable,
+                decorateReply: false,
+            });
+            if (spaFallback) {
+                const indexPath = join(root, index);
+                // Deep-link/refresh navigations are the common path for a client-routed
+                // SPA, so read the index once and serve the cached buffer — mirroring
+                // the caching @fastify/static does for real files. (A build that swaps
+                // index.html while the server runs isn't picked up, consistent with
+                // @fastify/static's own behavior.)
+                let indexHtml = null;
+                scope.setNotFoundHandler(async (_request, reply) => {
+                    if (indexHtml === null)
+                        indexHtml = await readFile(indexPath);
+                    return reply.type("text/html").send(indexHtml);
+                });
+            }
+        }, { 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) {
+    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);
+}
+export async function create(resource, ctx) {
+    return new HttpStatic(resource, ctx);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Telo HTTP Server module - HTTP server and API resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -33,10 +33,16 @@
       "types": "./dist/http-api-controller.d.ts",
       "bun": "./src/http-api-controller.ts",
       "import": "./dist/http-api-controller.js"
+    },
+    "./http-static": {
+      "types": "./dist/http-static-controller.d.ts",
+      "bun": "./src/http-static-controller.ts",
+      "import": "./dist/http-static-controller.js"
     }
   },
   "dependencies": {
     "@fastify/cors": "^11.2.0",
+    "@fastify/static": "^8.0.0",
     "@fastify/swagger": "^9.6.1",
     "@scalar/fastify-api-reference": "^1.44.6",
     "@sinclair/typebox": "^0.34.48",
@@ -49,7 +55,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.33.0"
+    "@telorun/sdk": "0.34.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-static-controller.ts

@@ -0,0 +1,113 @@
+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 { fileURLToPath } from "node:url";
+
+type HttpStaticResource = RuntimeResource & {
+  root: string;
+  index?: string;
+  spaFallback?: boolean;
+  maxAge?: number;
+  immutable?: boolean;
+};
+
+/** Collapse a mount prefix to a single leading slash with no trailing slash;
+ *  an empty/`"/"` prefix becomes `"/"`. Unlike Http.Api (which returns `""` and
+ *  concatenates the prefix onto each route path on the root app), this serves
+ *  from an encapsulated `register({ prefix })`, which needs a non-empty prefix —
+ *  hence root maps to `"/"`, not `""`. */
+function normalizeMountPrefix(prefix: string): string {
+  const trimmed = prefix.replace(/\/+$/, "");
+  if (!trimmed) return "/";
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+/** Serves a directory of static assets (a built SPA, plain HTML, images, …) as a
+ *  Telo.Mount. Mirrors Http.Api's `register(app, prefix)` contract so it slots into
+ *  Http.Server.mounts identically. Backed by @fastify/static, which handles MIME,
+ *  ETag, conditional requests, and range requests. */
+class HttpStatic implements ResourceInstance {
+  private readonly root: string;
+  private readonly index: string;
+  private readonly spaFallback: boolean;
+  private readonly maxAge?: number;
+  private readonly immutable: boolean;
+
+  constructor(resource: HttpStaticResource, ctx: ResourceContext) {
+    this.root = resolveRoot(resource.root, ctx);
+    this.index = resource.index ?? "index.html";
+    this.spaFallback = resource.spaFallback === true;
+    this.maxAge = resource.maxAge;
+    this.immutable = resource.immutable === true;
+  }
+
+  async init() {}
+
+  register(app: FastifyInstance, prefix = ""): void {
+    const mountPrefix = normalizeMountPrefix(prefix);
+    const root = this.root;
+    const index = this.index;
+    const spaFallback = this.spaFallback;
+    const cacheControl = this.maxAge != null;
+    // @fastify/static takes maxAge in milliseconds; the manifest declares seconds.
+    const maxAge = this.maxAge != null ? this.maxAge * 1000 : undefined;
+    const immutable = this.immutable;
+
+    // Encapsulated scope so the static plugin, its routes, and the SPA not-found
+    // handler are confined to this mount's prefix and don't collide with sibling
+    // mounts or the server-level notFoundHandler. `decorateReply: false` keeps
+    // multiple static mounts from fighting over the shared `reply.sendFile`
+    // decorator — the SPA fallback reads the index file directly instead.
+    app.register(
+      async (scope) => {
+        await scope.register(fastifyStatic, {
+          root,
+          prefix: "/",
+          index,
+          // With spaFallback we want unmatched paths to fall through to the
+          // not-found handler (client-side routing); the wildcard glob route
+          // would otherwise 404 them itself.
+          wildcard: !spaFallback,
+          cacheControl,
+          maxAge,
+          immutable,
+          decorateReply: false,
+        });
+
+        if (spaFallback) {
+          const indexPath = join(root, index);
+          // Deep-link/refresh navigations are the common path for a client-routed
+          // SPA, so read the index once and serve the cached buffer — mirroring
+          // the caching @fastify/static does for real files. (A build that swaps
+          // index.html while the server runs isn't picked up, consistent with
+          // @fastify/static's own behavior.)
+          let indexHtml: Buffer | null = null;
+          scope.setNotFoundHandler(async (_request, reply) => {
+            if (indexHtml === null) indexHtml = await readFile(indexPath);
+            return reply.type("text/html").send(indexHtml);
+          });
+        }
+      },
+      { 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: string, ctx: ResourceContext): 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);
+}
+
+export async function create(
+  resource: HttpStaticResource,
+  ctx: ResourceContext,
+): Promise<ResourceInstance> {
+  return new HttpStatic(resource, ctx);
+}