@ayepi/node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philip Diffenderfer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @ayepi/node
+
+Node.js adapter for [`@ayepi/core`](https://www.npmjs.com/package/@ayepi/core).
+Bridges `node:http` `IncomingMessage`/`ServerResponse` to the web-standard
+`Request`/`Response` ayepi speaks, and serves WebSocket upgrades via the
+[`ws`](https://github.com/websockets/ws) package. (Node is the one runtime
+without a built-in WebSocket server, which is why this adapter needs `ws`.)
+
+```sh
+pnpm add @ayepi/node @ayepi/core ws
+```
+
+```ts
+import { serve } from '@ayepi/node'
+
+const close = serve(app, { port: 3000, path: '/ws' })
+process.on('SIGTERM', () => void close())
+```
+
+Bodies stream both ways without buffering, response writes respect backpressure,
+and a client disconnect aborts your handler's `signal`. Also exports
+`createRequestListener(app)` and `handleUpgrade(app, server, path)` for mounting
+on an existing server.
+
+See the [full documentation](https://github.com/pdiffenderfer/ayepi#running-it).
+
+## For AI coding agents
+
+This package ships dense, machine-oriented reference docs written for **AI coding agents**
+(Claude Code, Cursor, and the like) to understand and drive the package — point your agent at them:
+
+- [`ayepi-node.md`](./ayepi-node.md)
+
+They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/node) and are **not** shipped in the npm tarball.
+
+## License
+
+MIT © Philip Diffenderfer

package/dist/index.cjs

@@ -0,0 +1,214 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let node_http = require("node:http");
+node_http = __toESM(node_http, 1);
+let node_stream = require("node:stream");
+let ws = require("ws");
+//#region src/index.ts
+/**
+* # ayepi-node
+*
+* Node.js adapter for an ayepi {@link Server}. Bridges the `node:http`
+* `IncomingMessage`/`ServerResponse` world to the web-standard
+* `Request`/`Response` the ayepi core speaks, and serves WebSocket upgrades via
+* the [`ws`](https://github.com/websockets/ws) package wired to
+* `app.ws.open`/`message`/`close`.
+*
+* Bodies stream in both directions without buffering, response writes respect
+* backpressure (`res.write` / `'drain'`), and a client disconnect aborts the
+* per-request `AbortSignal` (the `signal` your handlers receive).
+*
+* ```ts
+* import { serve } from 'ayepi-node'
+* const close = serve(app, { port: 3000, path: '/ws' })
+* // …later
+* await close()
+* ```
+*
+* HTTP/1.1 only for v0.
+*
+* @module
+*/
+/** Build a fetch `Request` from a Node `IncomingMessage`, wiring an abort `signal`. */
+function toRequest(req, signal) {
+	const url = `${req.socket.encrypted ? "https" : "http"}://${req.headers.host ?? "localhost"}${req.url ?? "/"}`;
+	const method = req.method ?? "GET";
+	const headers = new Headers();
+	for (const [k, v] of Object.entries(req.headers)) {
+		if (v === void 0) continue;
+		if (Array.isArray(v)) for (const vv of v) headers.append(k, vv);
+		else headers.set(k, v);
+	}
+	const hasBody = method !== "GET" && method !== "HEAD";
+	const init = {
+		method,
+		headers,
+		signal
+	};
+	if (hasBody) {
+		init.body = node_stream.Readable.toWeb(req);
+		init.duplex = "half";
+	}
+	return new Request(url, init);
+}
+/** Resolve once the response can accept more writes, or the socket closes. */
+function whenWritable(res) {
+	return new Promise((resolve) => {
+		const done = () => {
+			res.off("drain", done);
+			res.off("close", done);
+			resolve();
+		};
+		res.once("drain", done);
+		res.once("close", done);
+	});
+}
+/** Stream a fetch `Response` out through a Node `ServerResponse`, honoring backpressure. */
+async function sendResponse(res, response) {
+	res.statusCode = response.status;
+	const setCookies = response.headers.getSetCookie?.() ?? [];
+	response.headers.forEach((value, key) => {
+		if (key.toLowerCase() === "set-cookie") return;
+		res.setHeader(key, value);
+	});
+	if (setCookies.length > 0) res.setHeader("set-cookie", setCookies);
+	if (!response.body) {
+		res.end();
+		return;
+	}
+	const reader = response.body.getReader();
+	res.once("close", () => void reader.cancel().catch(() => {}));
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (res.writableEnded || res.destroyed) break;
+			if (!res.write(value)) await whenWritable(res);
+		}
+	} catch {} finally {
+		if (!res.writableEnded) res.end();
+	}
+}
+/**
+* Create a `node:http` request listener for an ayepi app — useful for mounting on
+* an existing server, behind a proxy, or alongside other routes.
+*
+* Each request gets an `AbortController` whose signal aborts when the client
+* disconnects before the response finishes; that signal is the `signal` your
+* handlers receive.
+*
+* @example
+* ```ts
+* http.createServer(createRequestListener(app)).listen(3000)
+* ```
+*/
+function createRequestListener(app) {
+	return (req, res) => {
+		const ac = new AbortController();
+		res.on("close", () => {
+			if (!res.writableFinished) ac.abort();
+		});
+		app.fetch(toRequest(req, ac.signal)).then((response) => sendResponse(res, response)).catch((err) => {
+			if (!res.headersSent) {
+				res.statusCode = 500;
+				res.setHeader("content-type", "application/json");
+				res.end(JSON.stringify({ error: {
+					code: "INTERNAL",
+					message: err instanceof Error ? err.message : "internal error"
+				} }));
+			} else if (!res.writableEnded) res.end();
+		});
+	};
+}
+/**
+* Attach an ayepi app's WebSocket handling to an `http.Server`'s `upgrade` event.
+*
+* Each upgraded socket becomes a {@link WsConn} via `app.ws.open`; inbound text
+* frames are forwarded to `app.ws.message`, and a socket close calls
+* `app.ws.close`. The upgrade `Request` (with its headers) is handed to
+* `app.ws.open`, so subscription guards can authenticate from it.
+*
+* @param app    - the ayepi app.
+* @param server - the HTTP server to listen for upgrades on.
+* @param path   - when set, only upgrades on this pathname are accepted.
+* @returns the underlying {@link WebSocketServer} (call `.close()` to stop).
+*/
+function handleUpgrade(app, server, path) {
+	const wss = new ws.WebSocketServer({ noServer: true });
+	server.on("upgrade", (req, socket, head) => {
+		if (path !== void 0) {
+			if (new URL(req.url ?? "/", "http://localhost").pathname !== path) {
+				socket.destroy();
+				return;
+			}
+		}
+		wss.handleUpgrade(req, socket, head, (ws$1) => {
+			const request = toRequest(req, new AbortController().signal);
+			const conn = app.ws.open((frame) => {
+				if (ws$1.readyState === ws$1.OPEN) ws$1.send(frame);
+			}, request);
+			ws$1.on("message", (data) => {
+				app.ws.message(conn, String(data));
+			});
+			ws$1.on("close", () => app.ws.close(conn));
+			ws$1.on("error", () => app.ws.close(conn));
+		});
+	});
+	return wss;
+}
+/**
+* Boot an ayepi app on a real HTTP + WebSocket port.
+*
+* @returns a `close()` function that stops accepting connections, terminates
+* live WebSockets, and resolves once the server has shut down.
+*
+* @example
+* ```ts
+* const close = serve(app, { port: 3000, path: '/ws', onListen: ({ port }) => console.log(`:${port}`) })
+* process.on('SIGTERM', () => void close())
+* ```
+*/
+function serve(app, opts) {
+	const server = node_http.default.createServer(createRequestListener(app));
+	const wss = handleUpgrade(app, server, opts.path);
+	const hostname = opts.hostname ?? "0.0.0.0";
+	server.listen(opts.port, hostname, () => {
+		const addr = server.address();
+		const port = typeof addr === "object" && addr ? addr.port : opts.port;
+		opts.onListen?.({
+			port,
+			hostname
+		});
+	});
+	return () => new Promise((resolve, reject) => {
+		for (const ws$2 of wss.clients) ws$2.terminate();
+		wss.close(() => {
+			server.close((err) => err ? reject(err) : resolve());
+		});
+	});
+}
+//#endregion
+exports.createRequestListener = createRequestListener;
+exports.handleUpgrade = handleUpgrade;
+exports.serve = serve;