holon-sh 0.0.1-dev.14 → 0.0.1-dev.15

package/README.md

@@ -122,6 +122,18 @@ A refused subscription is answered Forbidden, and access is checked again at eac
 
 Poll and push delivery are here, with targeted emits, subscription hooks, authorization, ending subscriptions, limits, paged listing and removing event types. Webhook delivery and check functions, which read a source that keeps its own history, are not, and neither are typed event names. Clients are not told when the event types change: they list them again.
 
+## Run an app without Holon
+
+`holon-sh/serve` serves an app's module at the paths Holon gives it, so the app also runs wherever Node does:
+
+```ts
+import { serve } from "holon-sh/serve";
+
+await serve(await import("./server.ts"));
+```
+
+The MCP endpoint is at `/mcp` and `/mcp/<app>`, and the files of `frontend` are at every other path. `PORT` and `HOST` change where it listens, 127.0.0.1:3000 unless they are set. Holon answers clients of the 2025 MCP versions in front of an app, and here the app's handler answers them, so create it without `legacy: "reject"`.
+
 ## Community
 
 Ask questions and share what you're building on the [Holon Discord](https://discord.gg/jXExyBdy).

package/dist/serve.d.ts

@@ -0,0 +1,22 @@
+import { type Server } from "node:http";
+/** An app's module: the MCP handler it exports by default, and the directory of its page. */
+export interface App {
+    default: {
+        fetch(request: Request): Promise<Response>;
+    };
+    /** The directory of the page's files, as a file URL. */
+    frontend?: URL;
+}
+/**
+ * Runs an app without Holon, at the paths Holon gives it: the MCP endpoint at `/mcp` and `/mcp/<app>`, and the page's
+ * files everywhere else. Listens on `PORT` and `HOST`, or else on 127.0.0.1:3000.
+ *
+ * ```ts
+ * await serve(await import("./server.ts"));
+ * ```
+ *
+ * Holon answers clients of the 2025 MCP versions in front of an app. Here the handler answers them, so create it
+ * without `legacy: "reject"`.
+ */
+export declare function serve({ default: handler, frontend }: App): Promise<Server>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAMjG,6FAA6F;AAC7F,MAAM,WAAW,GAAG;IAClB,OAAO,EAAE;QAAE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAC;IACxD,wDAAwD;IACxD,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBhF"}

package/dist/serve.js

@@ -0,0 +1,74 @@
+import { once } from "node:events";
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import mime from "mime";
+/**
+ * Runs an app without Holon, at the paths Holon gives it: the MCP endpoint at `/mcp` and `/mcp/<app>`, and the page's
+ * files everywhere else. Listens on `PORT` and `HOST`, or else on 127.0.0.1:3000.
+ *
+ * ```ts
+ * await serve(await import("./server.ts"));
+ * ```
+ *
+ * Holon answers clients of the 2025 MCP versions in front of an app. Here the handler answers them, so create it
+ * without `legacy: "reject"`.
+ */
+export async function serve({ default: handler, frontend }) {
+    const { PORT = "3000", HOST = "127.0.0.1" } = process.env;
+    // A directory's URL ends in `/`. Without it, a name would resolve beside the directory instead of in it.
+    const directory = frontend && new URL(frontend.href.replace(/\/?$/, "/"));
+    const server = createServer((req, res) => respond(handler, directory, req, res).catch((error) => {
+        console.error(error);
+        if (!res.headersSent)
+            res.writeHead(500);
+        res.end();
+    }));
+    server.listen(Number(PORT), HOST);
+    await once(server, "listening");
+    const { port } = server.address();
+    const origin = `http://${HOST.includes(":") ? `[${HOST}]` : HOST}:${port}`;
+    console.log(`Serving ${origin}/ with the MCP endpoint at ${origin}/mcp`);
+    return server;
+}
+async function respond(handler, directory, req, res) {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    if (/^\/mcp(\/[^/]+)?$/.test(url.pathname)) {
+        const gone = new AbortController();
+        res.on("close", () => gone.abort());
+        const headers = new Headers();
+        for (const [name, values = []] of Object.entries(req.headersDistinct))
+            for (const value of values)
+                headers.append(name, value);
+        // Holon forwards the origin it serves the app at. Here that is this server, unless a proxy in front forwards its own.
+        if (!headers.has("x-forwarded-host"))
+            headers.set("x-forwarded-host", url.host);
+        if (!headers.has("x-forwarded-proto"))
+            headers.set("x-forwarded-proto", "http");
+        const body = req.method === "GET" || req.method === "HEAD" ? undefined : req;
+        const response = await handler.fetch(new Request(url, { method: req.method, headers, body, duplex: "half", signal: gone.signal }));
+        res.setHeaders(response.headers).writeHead(response.status);
+        // When the client leaves, pipeline cancels the body, so a stream between events ends then and not at its next
+        // write. Either side failing ends the response, which is all there is to do.
+        if (response.body)
+            await pipeline(Readable.fromWeb(response.body), res).catch(() => { });
+        else
+            res.end();
+        return;
+    }
+    if (!directory || (req.method !== "GET" && req.method !== "HEAD"))
+        return void res.writeHead(404).end();
+    const name = url.pathname.endsWith("/") ? `${url.pathname}index.html` : url.pathname;
+    // The URL parser has resolved every `..`, and a file URL may not encode `/`, so no name leads out of the directory.
+    // Like Holon, serve nothing hidden, however its dot is spelled, and treat what cannot be read, such as a directory, as
+    // not found.
+    const contents = /\/(\.|%2e)/i.test(name) ? undefined : await readFile(new URL(`.${name}`, directory)).catch(() => undefined);
+    if (!contents)
+        return void res.writeHead(404).end();
+    // Like Holon, take the type from the MIME database, and call text UTF-8, which a built page is.
+    const type = mime.getType(name) ?? "application/octet-stream";
+    const contentType = type.startsWith("text/") ? `${type}; charset=utf-8` : type;
+    res.writeHead(200, { "content-type": contentType, "x-content-type-options": "nosniff" }).end(contents);
+}
+//# sourceMappingURL=serve.js.map

package/dist/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holon-sh",
-  "version": "0.0.1-dev.14",
+  "version": "0.0.1-dev.15",
   "description": "Typed MCP clients, MCP Events, and the caller of an MCP request, for Node.js.",
   "repository": {
     "type": "git",
@@ -35,6 +35,10 @@
     "./ext/files": {
       "types": "./dist/ext/files.d.ts",
       "import": "./dist/ext/files.js"
+    },
+    "./serve": {
+      "types": "./dist/serve.d.ts",
+      "import": "./dist/serve.js"
     }
   },
   "typesVersions": {
@@ -53,6 +57,9 @@
       ],
       "ext/files": [
         "./dist/ext/files.d.ts"
+      ],
+      "serve": [
+        "./dist/serve.d.ts"
       ]
     }
   },
@@ -73,6 +80,7 @@
   "dependencies": {
     "@modelcontextprotocol/client": "^2.3.1",
     "ipaddr.js": "^2.5.0",
+    "mime": "^4.1.2",
     "undici": "^7.16.0"
   },
   "peerDependencies": {

package/src/serve.ts

@@ -0,0 +1,76 @@
+import { once } from "node:events";
+import { readFile } from "node:fs/promises";
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import mime from "mime";
+
+/** An app's module: the MCP handler it exports by default, and the directory of its page. */
+export interface App {
+  default: { fetch(request: Request): Promise<Response> };
+  /** The directory of the page's files, as a file URL. */
+  frontend?: URL;
+}
+
+/**
+ * Runs an app without Holon, at the paths Holon gives it: the MCP endpoint at `/mcp` and `/mcp/<app>`, and the page's
+ * files everywhere else. Listens on `PORT` and `HOST`, or else on 127.0.0.1:3000.
+ *
+ * ```ts
+ * await serve(await import("./server.ts"));
+ * ```
+ *
+ * Holon answers clients of the 2025 MCP versions in front of an app. Here the handler answers them, so create it
+ * without `legacy: "reject"`.
+ */
+export async function serve({ default: handler, frontend }: App): Promise<Server> {
+  const { PORT = "3000", HOST = "127.0.0.1" } = process.env;
+  // A directory's URL ends in `/`. Without it, a name would resolve beside the directory instead of in it.
+  const directory = frontend && new URL(frontend.href.replace(/\/?$/, "/"));
+  const server = createServer((req, res) =>
+    respond(handler, directory, req, res).catch((error: unknown) => {
+      console.error(error);
+      if (!res.headersSent) res.writeHead(500);
+      res.end();
+    }),
+  );
+  server.listen(Number(PORT), HOST);
+  await once(server, "listening");
+  const { port } = server.address() as AddressInfo;
+  const origin = `http://${HOST.includes(":") ? `[${HOST}]` : HOST}:${port}`;
+  console.log(`Serving ${origin}/ with the MCP endpoint at ${origin}/mcp`);
+  return server;
+}
+
+async function respond(handler: App["default"], directory: URL | undefined, req: IncomingMessage, res: ServerResponse) {
+  const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+  if (/^\/mcp(\/[^/]+)?$/.test(url.pathname)) {
+    const gone = new AbortController();
+    res.on("close", () => gone.abort());
+    const headers = new Headers();
+    for (const [name, values = []] of Object.entries(req.headersDistinct)) for (const value of values) headers.append(name, value);
+    // Holon forwards the origin it serves the app at. Here that is this server, unless a proxy in front forwards its own.
+    if (!headers.has("x-forwarded-host")) headers.set("x-forwarded-host", url.host);
+    if (!headers.has("x-forwarded-proto")) headers.set("x-forwarded-proto", "http");
+    const body = req.method === "GET" || req.method === "HEAD" ? undefined : req;
+    const response = await handler.fetch(new Request(url, { method: req.method, headers, body, duplex: "half", signal: gone.signal }));
+    res.setHeaders(response.headers).writeHead(response.status);
+    // When the client leaves, pipeline cancels the body, so a stream between events ends then and not at its next
+    // write. Either side failing ends the response, which is all there is to do.
+    if (response.body) await pipeline(Readable.fromWeb(response.body), res).catch(() => {});
+    else res.end();
+    return;
+  }
+  if (!directory || (req.method !== "GET" && req.method !== "HEAD")) return void res.writeHead(404).end();
+  const name = url.pathname.endsWith("/") ? `${url.pathname}index.html` : url.pathname;
+  // The URL parser has resolved every `..`, and a file URL may not encode `/`, so no name leads out of the directory.
+  // Like Holon, serve nothing hidden, however its dot is spelled, and treat what cannot be read, such as a directory, as
+  // not found.
+  const contents = /\/(\.|%2e)/i.test(name) ? undefined : await readFile(new URL(`.${name}`, directory)).catch(() => undefined);
+  if (!contents) return void res.writeHead(404).end();
+  // Like Holon, take the type from the MIME database, and call text UTF-8, which a built page is.
+  const type = mime.getType(name) ?? "application/octet-stream";
+  const contentType = type.startsWith("text/") ? `${type}; charset=utf-8` : type;
+  res.writeHead(200, { "content-type": contentType, "x-content-type-options": "nosniff" }).end(contents);
+}