@octanejs/app-core 0.0.1

package/src/server/component-wrappers.js

@@ -0,0 +1,99 @@
+// @ts-check
+/**
+ * Server component composition for the octane renderer.
+ *
+ * octane's server ABI is PROPS-FIRST (matching the client): a component body is
+ * `(props, scope, extra) => string`. `render(Component, props)` invokes the ROOT
+ * directly as `Component(props, rootScope, undefined)` and does NOT wrap it in
+ * block markers — and `hydrateRoot()` adopts the container's FIRST CHILD as the
+ * root's own node. So the wrapper must call the top-level component DIRECTLY
+ * (wrapping it in `ssrComponent` would add an extra `<!--[-->…<!--]-->` layer that
+ * `clone()` then mis-adopts on hydrate).
+ *
+ * Only the layout's `{children}` is a nested hole: the compiled layout emits
+ * `ssrChild(props.children, scope)`, and `ssrChild` invokes a FUNCTION child as
+ * `children({}, scope, undefined)` wrapped in one `<!--[-->…<!--]-->` range. So
+ * `children` is a ComponentBody that calls the page directly, and any page data
+ * (params) rides its CLOSURE — `ssrChild` supplies only `{}`. The client
+ * `childSlot` applies the identical rule (bare function = ComponentBody, `{}`
+ * props, one marker range), so server markers and client adoption line up.
+ *
+ * @typedef {(props?: any, scope?: any, extra?: any) => string | void} ServerComponent
+ */
+
+/**
+ * Wrap a page component, baking in its route props.
+ *
+ * @param {ServerComponent} Page
+ * @param {Record<string, unknown>} pageProps
+ * @returns {ServerComponent}
+ */
+export function createPropsWrapper(Page, pageProps) {
+	return function Root(_props, scope) {
+		return Page(pageProps, scope, undefined);
+	};
+}
+
+/**
+ * Compose a layout with a page: the layout's `{children}` renders the page.
+ *
+ * @param {ServerComponent} Layout
+ * @param {ServerComponent} Page
+ * @param {Record<string, unknown>} pageProps
+ * @returns {ServerComponent}
+ */
+export function createLayoutWrapper(Layout, Page, pageProps) {
+	return function Root(_props, scope) {
+		// `children` is a ComponentBody closing over pageProps; the layout's
+		// `{children}` hole runs it via ssrChild (which supplies `{}` props and
+		// wraps the output in one block range), so the page still gets its real
+		// route props through the closure. PROPS-FIRST: childSlot/ssrChild call it
+		// as `({}, scope, extra)`, so the page's real props are passed explicitly.
+		const children = (/** @type {any} */ _cprops, /** @type {any} */ cscope) =>
+			Page(pageProps, cscope, undefined);
+		return Layout({ ...pageProps, children }, scope, undefined);
+	};
+}
+
+/**
+ * Add the configured app-wide Suspense/ErrorBoundary around a route root.
+ * The same composition helper is used by dev SSR, production SSR, and the
+ * generated browser hydrate entry, so all three produce/adopt the same nested
+ * marker shape.
+ *
+ * @param {ServerComponent} Content
+ * @param {{ pending?: ServerComponent | null, catch?: ServerComponent | null }} boundary
+ * @param {{ Suspense: ServerComponent, ErrorBoundary: ServerComponent, createElement: Function }} runtime
+ * @returns {ServerComponent}
+ */
+export function createRootBoundaryWrapper(Content, boundary, runtime) {
+	let body = Content;
+
+	if (boundary.pending) {
+		const child = body;
+		const Pending = boundary.pending;
+		body = function RootSuspense(props, scope) {
+			const children = (/** @type {any} */ _props, /** @type {any} */ childScope) =>
+				child(props, childScope, undefined);
+			return runtime.Suspense(
+				{ fallback: runtime.createElement(Pending, {}), children },
+				scope,
+				undefined,
+			);
+		};
+	}
+
+	if (boundary.catch) {
+		const child = body;
+		const Catch = boundary.catch;
+		body = function RootErrorBoundary(props, scope) {
+			const children = (/** @type {any} */ _props, /** @type {any} */ childScope) =>
+				child(props, childScope, undefined);
+			const fallback = (/** @type {unknown} */ error, /** @type {() => void} */ reset) =>
+				runtime.createElement(Catch, { error, reset });
+			return runtime.ErrorBoundary({ fallback, children }, scope, undefined);
+		};
+	}
+
+	return body;
+}

package/src/server/html-stream.js

@@ -0,0 +1,74 @@
+// @ts-check
+
+/**
+ * Compose an HTML template around the renderer without draining it eagerly.
+ * Each consumer pull advances at most one visible chunk (prefix, one render
+ * chunk, suffix), so backpressure reaches the core stream. Cancellation goes
+ * through the locked reader and therefore reaches the renderer's source.
+ *
+ * @param {string} prefix
+ * @param {ReadableStream<Uint8Array>} renderStream
+ * @param {string} suffix
+ * @returns {ReadableStream<Uint8Array>}
+ */
+export function composeHtmlStream(prefix, renderStream, suffix) {
+	const encoder = new TextEncoder();
+	const reader = renderStream.getReader();
+	let phase = 0; // 0 prefix, 1 renderer, 2 suffix, 3 closed
+	let released = false;
+
+	function release() {
+		if (released) return;
+		released = true;
+		reader.releaseLock();
+	}
+
+	return new ReadableStream(
+		{
+			async pull(controller) {
+				try {
+					for (;;) {
+						if (phase === 0) {
+							phase = 1;
+							if (prefix !== '') {
+								controller.enqueue(encoder.encode(prefix));
+								return;
+							}
+						}
+
+						if (phase === 1) {
+							const { done, value } = await reader.read();
+							if (!done) {
+								controller.enqueue(value);
+								return;
+							}
+							release();
+							phase = 2;
+						}
+
+						if (phase === 2) {
+							phase = 3;
+							if (suffix !== '') controller.enqueue(encoder.encode(suffix));
+							controller.close();
+							return;
+						}
+						return;
+					}
+				} catch (error) {
+					release();
+					phase = 3;
+					controller.error(error);
+				}
+			},
+			async cancel(reason) {
+				phase = 3;
+				try {
+					await reader.cancel(reason);
+				} finally {
+					release();
+				}
+			},
+		},
+		{ highWaterMark: 0 },
+	);
+}

package/src/server/html-template.js

@@ -0,0 +1,136 @@
+// @ts-check
+
+import { OCTANE_NONCE_STATE_KEY } from '../constants.js';
+
+const HEAD_MARKER = '<!--ssr-head-->';
+const BODY_MARKER = '<!--ssr-body-->';
+export const HYDRATION_NONCE_PLACEHOLDER = '__OCTANE_REQUEST_NONCE__';
+// A real (hidden) element survives bundler HTML module-script rewrites, unlike
+// attributes on the script itself and empty template/comment sentinels. It is
+// removed per request before the document is served.
+const HYDRATION_MARKER = '<div hidden data-octane-hydrate-marker></div>';
+
+/** @param {string} value */
+function escapeAttribute(value) {
+	return value
+		.replace(/&/g, '&amp;')
+		.replace(/"/g, '&quot;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;');
+}
+
+/**
+ * Validate the structural contract needed by SSR and hydration.
+ * @param {string} html
+ */
+export function validateSsrTemplate(html) {
+	const headMarkerCount = html.split(HEAD_MARKER).length - 1;
+	if (headMarkerCount !== 1) {
+		throw new Error(
+			`[octane] index.html must contain exactly one ${HEAD_MARKER}; found ${headMarkerCount}.`,
+		);
+	}
+	validateSsrBodyContract(html);
+}
+
+/** @param {string} html */
+function validateSsrBodyContract(html) {
+	const markerCount = html.split(BODY_MARKER).length - 1;
+	if (markerCount !== 1) {
+		throw new Error(
+			`[octane] index.html must contain exactly one ${BODY_MARKER}; found ${markerCount}.`,
+		);
+	}
+	const bodyCloseCount = html.match(/<\/body\s*>/gi)?.length ?? 0;
+	if (bodyCloseCount !== 1) {
+		throw new Error(
+			`[octane] index.html must contain exactly one closing </body> tag for hydration injection; found ${bodyCloseCount}.`,
+		);
+	}
+}
+
+/**
+ * @param {string} html
+ * @param {string} source
+ * @param {string | null} nonce
+ */
+export function injectHydrationEntry(html, source, nonce) {
+	validateSsrTemplate(html);
+	const nonceAttr = nonce === null ? '' : ` nonce="${escapeAttribute(nonce)}"`;
+	const script = `<script type="module" data-octane-hydrate src="${escapeAttribute(source)}"${nonceAttr}></script>`;
+	const marker = nonce === HYDRATION_NONCE_PLACEHOLDER ? HYDRATION_MARKER : '';
+	return html.replace(/<\/body\s*>/i, `${marker}${script}\n</body>`);
+}
+
+/**
+ * Split a validated template around its one SSR body marker.
+ * @param {string} html
+ */
+export function splitSsrTemplate(html) {
+	// The head marker has already been replaced with request data at this point.
+	validateSsrBodyContract(html);
+	const at = html.indexOf(BODY_MARKER);
+	return [html.slice(0, at), html.slice(at + BODY_MARKER.length)];
+}
+
+/**
+ * Add the request nonce to the production hydrate script the integration built. The
+ * data attribute is inserted before build so this remains robust after the
+ * script src is hashed/reordered.
+ * @param {string} html
+ * @param {string | null} nonce
+ */
+export function applyHydrationNonce(html, nonce) {
+	const tags = html.match(/<script\b[^>]*>/gi) ?? [];
+	let hydrationTags = tags.filter(
+		(tag) => /\bdata-octane-hydrate\b/i.test(tag) || tag.includes(HYDRATION_NONCE_PLACEHOLDER),
+	);
+	const markerCount = html.split(HYDRATION_MARKER).length - 1;
+	if (hydrationTags.length === 0 && markerCount === 1) {
+		// Bundlers may coalesce/hoist HTML module entries into the head, so the hydrate
+		// module may no longer be adjacent to its marker (and may share an entry
+		// chunk with user scripts). Nonce every built module-entry tag: they all
+		// participate in the same CSP-protected bootstrap graph.
+		hydrationTags = tags.filter((tag) => /\btype\s*=\s*(?:"module"|'module'|module)/i.test(tag));
+	}
+	const invalidMarkerContract =
+		markerCount > 0 ? markerCount !== 1 || hydrationTags.length === 0 : hydrationTags.length !== 1;
+	if (invalidMarkerContract) {
+		throw new Error(
+			`[octane] Built SSR template must identify its hydration module script; found ${hydrationTags.length}.`,
+		);
+	}
+	let output = html.replace(HYDRATION_MARKER, '');
+	for (const oldTag of hydrationTags) {
+		let nextTag = oldTag.replace(/\snonce\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/i, '');
+		if (!/\bdata-octane-hydrate\b/i.test(nextTag)) {
+			nextTag = nextTag.replace(/^<script\b/i, '<script data-octane-hydrate');
+		}
+		if (nonce !== null) {
+			nextTag = nextTag.replace(/^<script\b/i, `<script nonce="${escapeAttribute(nonce)}"`);
+		}
+		output = output.replace(oldTag, nextTag);
+	}
+	return output;
+}
+
+/** @param {string | null} nonce */
+export function nonceAttribute(nonce) {
+	return nonce === null ? '' : ` nonce="${escapeAttribute(nonce)}"`;
+}
+
+/**
+ * Read and validate the documented middleware state key.
+ * @param {{ state: Map<string, unknown> }} context
+ * @returns {string | null}
+ */
+export function getContextNonce(context) {
+	const value = context.state.get(OCTANE_NONCE_STATE_KEY);
+	if (value === undefined) return null;
+	if (typeof value !== 'string' || value.length === 0) {
+		throw new Error(
+			`[octane] Context.state.get('${OCTANE_NONCE_STATE_KEY}') must be a non-empty string.`,
+		);
+	}
+	return value;
+}

package/src/server/middleware.js

@@ -0,0 +1,127 @@
+// @ts-check
+/**
+ * @typedef {import('@octanejs/app-core').Context} Context
+ * @typedef {import('@octanejs/app-core').Middleware} Middleware
+ * @typedef {import('@octanejs/app-core').NextFunction} NextFunction
+ */
+
+/**
+ * Compose multiple middlewares into a single middleware
+ * Follows Koa-style execution: request flows down, response flows back up
+ *
+ * @param {Middleware[]} middlewares
+ * @returns {(context: Context, finalHandler: () => Promise<Response>) => Promise<Response>}
+ */
+export function compose(middlewares) {
+	return function composed(context, finalHandler) {
+		let index = -1;
+
+		/**
+		 * @param {number} i
+		 * @returns {Promise<Response>}
+		 */
+		function dispatch(i) {
+			if (i <= index) {
+				return Promise.reject(new Error('next() called multiple times'));
+			}
+			index = i;
+
+			/** @type {Middleware | (() => Promise<Response>) | undefined} */
+			let fn;
+
+			if (i < middlewares.length) {
+				fn = middlewares[i];
+			} else if (i === middlewares.length) {
+				fn = finalHandler;
+			}
+
+			if (!fn) {
+				return Promise.reject(new Error('No handler provided'));
+			}
+
+			try {
+				// For the final handler, we don't pass next
+				if (i === middlewares.length) {
+					return Promise.resolve(/** @type {() => Promise<Response>} */ (fn)());
+				}
+				// For middlewares, pass context and next
+				return Promise.resolve(/** @type {Middleware} */ (fn)(context, () => dispatch(i + 1)));
+			} catch (err) {
+				return Promise.reject(err);
+			}
+		}
+
+		return dispatch(0);
+	};
+}
+
+/**
+ * Create a context object for the request
+ * @param {Request} request
+ * @param {Record<string, string>} params
+ * @returns {Context}
+ */
+export function createContext(request, params) {
+	return {
+		request,
+		params,
+		url: new URL(request.url),
+		state: new Map(),
+	};
+}
+
+/**
+ * Run middlewares with a final handler
+ * Combines global middlewares, route-level before/after, and the handler
+ *
+ * @param {Context} context
+ * @param {Middleware[]} globalMiddlewares
+ * @param {Middleware[]} beforeMiddlewares
+ * @param {() => Promise<Response>} handler
+ * @param {Middleware[]} afterMiddlewares
+ * @returns {Promise<Response>}
+ */
+export async function runMiddlewareChain(
+	context,
+	globalMiddlewares,
+	beforeMiddlewares,
+	handler,
+	afterMiddlewares = [],
+) {
+	// Combine global + before middlewares
+	const allMiddlewares = [...globalMiddlewares, ...beforeMiddlewares];
+
+	// If there are after middlewares, wrap the handler to run them
+	const wrappedHandler =
+		afterMiddlewares.length > 0
+			? async () => {
+					const response = await handler();
+					// After middlewares can inspect/modify the response
+					// but have limited ability to change it in our model
+					// We run them for side-effects (logging, etc.)
+					return runAfterMiddlewares(context, afterMiddlewares, response);
+				}
+			: handler;
+
+	const composed = compose(allMiddlewares);
+	return composed(context, wrappedHandler);
+}
+
+/**
+ * Run after middlewares with the response
+ * After middlewares run in order and can intercept/modify the response
+ *
+ * @param {Context} context
+ * @param {Middleware[]} middlewares
+ * @param {Response} response
+ * @returns {Promise<Response>}
+ */
+async function runAfterMiddlewares(context, middlewares, response) {
+	let currentResponse = response;
+
+	for (const middleware of middlewares) {
+		currentResponse = await middleware(context, async () => currentResponse);
+	}
+
+	return currentResponse;
+}

package/src/server/node-http.js

@@ -0,0 +1,262 @@
+// @ts-check
+/**
+ * Node HTTP glue — shared by the dev middleware (src/index.js), the generated
+ * production server entry (its `nodeHandler` export for serverless wrappers),
+ * and the built-in production server (`createNodeServer`, the no-adapter
+ * default boot). Exported as '@octanejs/app-core/node'.
+ *
+ * This module may import node builtins (unlike server/production.js, which is
+ * platform-agnostic) — it IS the Node platform layer.
+ */
+
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+
+/**
+ * Convert a Node.js IncomingMessage to a Web Request.
+ * @param {import('node:http').IncomingMessage} nodeRequest
+ * @returns {Request}
+ */
+export function nodeRequestToWebRequest(nodeRequest) {
+	const host = nodeRequest.headers.host || 'localhost';
+	const url = new URL(nodeRequest.url || '/', `http://${host}`);
+
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(nodeRequest.headers)) {
+		if (value == null) continue;
+		if (Array.isArray(value)) {
+			for (const v of value) headers.append(key, v);
+		} else {
+			headers.set(key, value);
+		}
+	}
+
+	const method = (nodeRequest.method || 'GET').toUpperCase();
+	/** @type {RequestInit & { duplex?: 'half' }} */
+	const init = { method, headers };
+	const abortController = new AbortController();
+	const abortRequest = () => {
+		if (!abortController.signal.aborted) {
+			abortController.abort(new Error('The client disconnected before the request completed.'));
+		}
+	};
+	if (nodeRequest.aborted || (nodeRequest.destroyed && !nodeRequest.complete)) {
+		abortRequest();
+	} else {
+		nodeRequest.once('aborted', abortRequest);
+		nodeRequest.once('close', () => {
+			if (!nodeRequest.complete) abortRequest();
+		});
+	}
+	init.signal = abortController.signal;
+	if (method !== 'GET' && method !== 'HEAD') {
+		// node:stream/web's ReadableStream and the DOM lib's are structurally the
+		// same at runtime; the lib types disagree on BYOB details.
+		init.body = /** @type {ReadableStream} */ (
+			/** @type {unknown} */ (Readable.toWeb(nodeRequest))
+		);
+		init.duplex = 'half';
+	}
+	return new Request(url, init);
+}
+
+/**
+ * Pipe a Web Response to a Node.js ServerResponse. Streams chunk-by-chunk so a
+ * streaming SSR body flushes as it renders (no buffering).
+ *
+ * @param {import('node:http').ServerResponse} nodeResponse
+ * @param {Response} webResponse
+ */
+export async function sendWebResponse(nodeResponse, webResponse) {
+	nodeResponse.statusCode = webResponse.status;
+	if (webResponse.statusText) nodeResponse.statusMessage = webResponse.statusText;
+	webResponse.headers.forEach((value, key) => {
+		nodeResponse.setHeader(key, value);
+	});
+	if (webResponse.body) {
+		const reader = webResponse.body.getReader();
+		let disconnected = nodeResponse.destroyed;
+		let disconnectReason = new Error('The client disconnected while streaming the response.');
+		/** @type {Promise<void> | null} */
+		let cancelPromise = null;
+		const cancelReader = (/** @type {unknown} */ reason) => {
+			disconnectReason = reason instanceof Error ? reason : disconnectReason;
+			return (cancelPromise ??= reader.cancel(reason).catch(() => {}));
+		};
+		const onClose = () => {
+			if (nodeResponse.writableEnded) return;
+			disconnected = true;
+			void cancelReader(disconnectReason);
+		};
+		const onError = (/** @type {Error} */ error) => {
+			disconnected = true;
+			void cancelReader(error);
+		};
+		nodeResponse.once('close', onClose);
+		nodeResponse.once('error', onError);
+		try {
+			if (disconnected) await cancelReader(disconnectReason);
+			while (!disconnected) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				const accepted = nodeResponse.write(value);
+				if (!accepted && !disconnected) await waitForDrain(nodeResponse);
+			}
+		} catch (error) {
+			if (!disconnected) throw error;
+		} finally {
+			nodeResponse.off('close', onClose);
+			nodeResponse.off('error', onError);
+			if (disconnected) await cancelReader(disconnectReason);
+			reader.releaseLock();
+		}
+	}
+	if (!nodeResponse.destroyed) nodeResponse.end();
+}
+
+/**
+ * Pause source reads until Node's writable buffer drains. A disconnect/error
+ * rejects the wait; sendWebResponse's socket listeners cancel the web reader.
+ * @param {import('node:http').ServerResponse} response
+ */
+function waitForDrain(response) {
+	if (response.destroyed) {
+		return Promise.reject(new Error('The client disconnected while waiting for drain.'));
+	}
+	return new Promise((resolve, reject) => {
+		const cleanup = () => {
+			response.off('drain', onDrain);
+			response.off('close', onClose);
+			response.off('error', onError);
+		};
+		const onDrain = () => {
+			cleanup();
+			resolve(undefined);
+		};
+		const onClose = () => {
+			cleanup();
+			reject(new Error('The client disconnected while waiting for drain.'));
+		};
+		const onError = (/** @type {Error} */ error) => {
+			cleanup();
+			reject(error);
+		};
+		response.once('drain', onDrain);
+		response.once('close', onClose);
+		response.once('error', onError);
+	});
+}
+
+// Static-file MIME map (the common web set; anything else falls back to
+// octet-stream, which is correct for downloads).
+/** @type {Record<string, string>} */
+const MIME_TYPES = {
+	'.html': 'text/html; charset=utf-8',
+	'.css': 'text/css; charset=utf-8',
+	'.js': 'text/javascript; charset=utf-8',
+	'.mjs': 'text/javascript; charset=utf-8',
+	'.json': 'application/json; charset=utf-8',
+	'.png': 'image/png',
+	'.jpg': 'image/jpeg',
+	'.jpeg': 'image/jpeg',
+	'.gif': 'image/gif',
+	'.svg': 'image/svg+xml',
+	'.ico': 'image/x-icon',
+	'.woff': 'font/woff',
+	'.woff2': 'font/woff2',
+	'.ttf': 'font/ttf',
+	'.otf': 'font/otf',
+	'.webp': 'image/webp',
+	'.avif': 'image/avif',
+	'.mp4': 'video/mp4',
+	'.webm': 'video/webm',
+	'.txt': 'text/plain; charset=utf-8',
+	'.xml': 'application/xml',
+	'.wasm': 'application/wasm',
+	'.map': 'application/json',
+};
+
+/**
+ * Serve a static file from `staticDir` if the request path maps to one.
+ * Hash-named build assets (Vite's /assets/ and Rsbuild's /static/) get
+ * immutable caching; other files (favicon, robots.txt, …) revalidate.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {string} staticDir
+ * @returns {boolean} true when the request was handled as a static file
+ */
+export function serveStaticFile(req, res, staticDir) {
+	const method = (req.method || 'GET').toUpperCase();
+	if (method !== 'GET' && method !== 'HEAD') return false;
+
+	const pathname = decodeURIComponent(new URL(req.url || '/', 'http://localhost').pathname);
+	// Resolve inside staticDir only — a `..` escape must not leave the client dir.
+	const filePath = path.normalize(path.join(staticDir, pathname));
+	if (!filePath.startsWith(path.normalize(staticDir + path.sep))) return false;
+
+	/** @type {fs.Stats} */
+	let stat;
+	try {
+		stat = fs.statSync(filePath);
+	} catch {
+		return false;
+	}
+	if (!stat.isFile()) return false;
+
+	const ext = path.extname(filePath).toLowerCase();
+	res.statusCode = 200;
+	res.setHeader('Content-Type', MIME_TYPES[ext] || 'application/octet-stream');
+	res.setHeader('Content-Length', stat.size);
+	res.setHeader(
+		'Cache-Control',
+		pathname.startsWith('/assets/') || pathname.startsWith('/static/')
+			? 'public, max-age=31536000, immutable'
+			: 'public, max-age=0, must-revalidate',
+	);
+	if (method === 'HEAD') {
+		res.end();
+	} else {
+		fs.createReadStream(filePath).pipe(res);
+	}
+	return true;
+}
+
+/**
+ * Minimal production HTTP server: static files from `staticDir` first (built
+ * client assets), then the fetch-style SSR handler. This is the DEFAULT boot
+ * when octane.config.ts has no adapter — an adapter's `serve()` replaces it.
+ *
+ * @param {(request: Request) => Response | Promise<Response>} handler
+ * @param {{ staticDir?: string }} [options]
+ * @returns {{ listen: (port?: number) => import('node:http').Server, close: () => void }}
+ */
+export function createNodeServer(handler, options = {}) {
+	const staticDir = options.staticDir;
+
+	const server = http.createServer((req, res) => {
+		(async () => {
+			if (staticDir && serveStaticFile(req, res, staticDir)) return;
+			const response = await handler(nodeRequestToWebRequest(req));
+			await sendWebResponse(res, response);
+		})().catch((error) => {
+			console.error('[octane] Request error:', error);
+			if (!res.headersSent) {
+				res.statusCode = 500;
+				res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+			}
+			res.end('Internal Server Error');
+		});
+	});
+
+	return {
+		listen(port = 3000) {
+			return server.listen(port);
+		},
+		close() {
+			server.close();
+		},
+	};
+}