@ecopages/core 0.2.0-alpha.53 → 0.2.0-alpha.54

package/src/adapters/create-app.ts

@@ -0,0 +1,91 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.ts';
+import { AbstractApplicationAdapter } from './abstract/application-adapter.ts';
+import type { ApiHandler } from '../types/public-types.ts';
+import type { ApplicationAdapterOptions } from './abstract/application-adapter.ts';
+import { SharedApplicationAdapter } from './shared/application-adapter.ts';
+import { createApp as createBunApp } from './bun/create-app.ts';
+import { createNodeApp } from './node/create-app.ts';
+
+export interface EcopagesAppOptions extends ApplicationAdapterOptions {
+	appConfig: EcoPagesAppConfig;
+	serverOptions?: Record<string, any>;
+}
+
+export type UniversalEcopagesApp = AbstractApplicationAdapter<EcopagesAppOptions, unknown, Request>;
+
+async function createRuntimeApp<WebSocketData = undefined>(options: EcopagesAppOptions): Promise<UniversalEcopagesApp> {
+	const bun = (globalThis as { Bun?: unknown }).Bun;
+
+	if (bun) {
+		return (await createBunApp<WebSocketData>(options)) as unknown as UniversalEcopagesApp;
+	}
+
+	return (await createNodeApp(options)) as unknown as UniversalEcopagesApp;
+}
+
+export async function createApp<WebSocketData = undefined>(options: EcopagesAppOptions): Promise<UniversalEcopagesApp> {
+	return createRuntimeApp<WebSocketData>(options);
+}
+
+export class EcopagesApp extends SharedApplicationAdapter<EcopagesAppOptions, unknown, Request> {
+	private readonly appOptions: EcopagesAppOptions;
+	private runtimeApp: UniversalEcopagesApp | null = null;
+	private runtimeAppPromise: Promise<UniversalEcopagesApp> | null = null;
+
+	constructor(options: EcopagesAppOptions) {
+		super(options);
+		this.appOptions = options;
+	}
+
+	private async getRuntimeApp(): Promise<UniversalEcopagesApp> {
+		if (this.runtimeApp) {
+			return this.runtimeApp;
+		}
+
+		if (!this.runtimeAppPromise) {
+			this.runtimeAppPromise = createRuntimeApp({
+				...this.appOptions,
+				clearOutput: false,
+			}).then((app) => {
+				for (const handler of this.apiHandlers) {
+					app.add(handler as ApiHandler<string, Request, any>);
+				}
+
+				for (const route of this.staticRoutes) {
+					app.static(route.path, route.loader);
+				}
+
+				if (this.errorHandler) {
+					app.onError(this.errorHandler);
+				}
+
+				this.runtimeApp = app;
+				return app;
+			});
+		}
+
+		return this.runtimeAppPromise;
+	}
+
+	protected async initializeServerAdapter(): Promise<UniversalEcopagesApp> {
+		return this.getRuntimeApp();
+	}
+
+	async start(): Promise<unknown> {
+		const runtimeApp = await this.getRuntimeApp();
+		return runtimeApp.start();
+	}
+
+	async fetch(request: Request): Promise<Response> {
+		const runtimeApp = await this.getRuntimeApp();
+		const candidate = runtimeApp as UniversalEcopagesApp & {
+			fetch?: (request: Request) => Promise<Response>;
+		};
+
+		if (!candidate.fetch) {
+			throw new Error('The selected runtime adapter does not expose fetch()');
+		}
+
+		return candidate.fetch(request);
+	}
+}

package/src/adapters/index.ts

@@ -0,0 +1,2 @@
+export { EcopagesApp, createApp } from './create-app.ts';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from './shared/define-api-handler.ts';

package/src/adapters/node/create-app.test.ts

@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import { afterEach, describe, it, vi } from 'vitest';
+import type { NodeServerAdapterParams, NodeServerAdapterResult } from './server-adapter.ts';
+import { NodeEcopagesApp } from './create-app.ts';
+import { NodeHttpRequestBridge } from './http-request-bridge.ts';
+import { NodeRuntimeHost } from './runtime-host.ts';
+
+class TestNodeEcopagesApp extends NodeEcopagesApp {
+	public capturedParams: NodeServerAdapterParams | undefined;
+
+	constructor(options: ConstructorParameters<typeof NodeEcopagesApp>[0]) {
+		super(options, {
+			runtimeHost: new NodeRuntimeHost(new NodeHttpRequestBridge()),
+		});
+	}
+
+	protected override async createServerAdapter(params: NodeServerAdapterParams): Promise<NodeServerAdapterResult> {
+		this.capturedParams = params;
+		return {
+			getServerOptions: () => params.serveOptions,
+			completeInitialization: async () => {},
+			handleRequest: async () => new Response(null, { status: 204 }),
+			buildStatic: async () => {},
+		};
+	}
+
+	public async initializeForTest(): Promise<void> {
+		await this.initializeServerAdapter();
+	}
+}
+
+afterEach(() => {
+	process.env.NODE_ENV = undefined;
+	process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME = undefined;
+	process.env.ECOPAGES_PORT = '';
+	process.env.ECOPAGES_HOSTNAME = '';
+	vi.restoreAllMocks();
+});
+
+describe('node embedded app bootstrap', () => {
+	it('keeps watch mode enabled for embedded development runtimes', async () => {
+		process.env.NODE_ENV = 'development';
+
+		const app = new TestNodeEcopagesApp({
+			appConfig: {
+				runtime: {},
+			} as any,
+			runtime: {
+				embedded: true,
+			},
+		});
+
+		await app.initializeForTest();
+
+		assert.equal(app.capturedParams?.options?.watch, true);
+		assert.deepEqual(app.capturedParams?.serveOptions, {
+			port: 3000,
+			hostname: 'localhost',
+		});
+	});
+
+	it('preserves the configured hostname in the reported runtime origin', () => {
+		const runtimeHost = new NodeRuntimeHost(new NodeHttpRequestBridge());
+		const server = {
+			address: () => ({ address: '::1', port: 3000, family: 'IPv6' }),
+		} as any;
+
+		assert.equal(
+			runtimeHost.getOrigin(server, {
+				hostname: 'localhost',
+				port: 3000,
+			}),
+			'http://localhost:3000',
+		);
+	});
+});

package/src/adapters/node/create-app.ts

@@ -0,0 +1,116 @@
+import { appLogger } from '../../global/app-logger.ts';
+import type { StaticRoute } from '../../types/public-types.ts';
+import { SharedApplicationAdapter } from '../shared/application-adapter.ts';
+import { resolveRuntimeBinding } from '../shared/runtime-app-bootstrap.ts';
+import type { RuntimeHost } from '../shared/runtime-host.ts';
+import type { EcopagesAppOptions } from '../create-app.ts';
+import { type NodeServerAdapterResult, createNodeServerAdapter } from './server-adapter.ts';
+import { NodeHttpRequestBridge } from './http-request-bridge.ts';
+import type { NodeServerInstance } from './server-adapter.ts';
+import { NodeRuntimeHost } from './runtime-host.ts';
+
+export class NodeEcopagesApp extends SharedApplicationAdapter<EcopagesAppOptions, NodeServerInstance, Request> {
+	serverAdapter: NodeServerAdapterResult | undefined;
+	private server: NodeServerInstance | null = null;
+	private runtimeOrigin = '';
+	private readonly runtimeHost: RuntimeHost<NodeServerInstance, { port?: number; hostname?: string }>;
+
+	constructor(
+		options: EcopagesAppOptions,
+		dependencies: {
+			runtimeHost: RuntimeHost<NodeServerInstance, { port?: number; hostname?: string }>;
+		},
+	) {
+		super(options);
+		this.runtimeHost = dependencies.runtimeHost;
+	}
+
+	protected createServerAdapter(
+		params: Parameters<typeof createNodeServerAdapter>[0],
+	): Promise<NodeServerAdapterResult> {
+		return createNodeServerAdapter(params);
+	}
+
+	public async stop(force = true): Promise<void> {
+		if (!this.server) {
+			return;
+		}
+
+		const activeServer = this.server;
+		this.server = null;
+		await this.runtimeHost.stop(activeServer, { force });
+	}
+
+	protected async initializeServerAdapter(): Promise<NodeServerAdapterResult> {
+		const binding = resolveRuntimeBinding({
+			cliArgs: this.cliArgs,
+			serverOptions: this.serverOptions,
+		});
+		this.runtimeOrigin = binding.runtimeOrigin;
+
+		return this.createServerAdapter({
+			runtimeOrigin: this.runtimeOrigin,
+			appConfig: this.appConfig,
+			apiHandlers: this.apiHandlers,
+			staticRoutes: this.staticRoutes as StaticRoute[],
+			errorHandler: this.errorHandler,
+			options: { watch: binding.watch },
+			serveOptions: binding.serveOptions,
+		});
+	}
+
+	public async start(): Promise<NodeServerInstance | void> {
+		if (!this.serverAdapter) {
+			this.serverAdapter = await this.initializeServerAdapter();
+		}
+
+		if (this.server) {
+			return this.server;
+		}
+
+		const { build, preview } = this.cliArgs;
+
+		if (build || preview) {
+			appLogger.debugTime('Building static pages');
+			await this.serverAdapter.buildStatic({ preview });
+			await this.stop(true);
+			appLogger.debugTimeEnd('Building static pages');
+
+			if (build) {
+				process.exit(0);
+			}
+			return;
+		}
+
+		const serveOptions = this.serverAdapter.getServerOptions();
+		this.server = await this.runtimeHost.start({
+			serveOptions,
+			handleRequest: async (request) => await this.serverAdapter!.handleRequest(request),
+			onError: async () => {},
+		});
+		this.runtimeOrigin = this.runtimeHost.getOrigin(this.server, serveOptions);
+
+		await this.serverAdapter.completeInitialization(this.server);
+		appLogger.info(`Node server running at ${this.runtimeOrigin}`);
+
+		return this.server;
+	}
+
+	public async fetch(request: Request): Promise<Response> {
+		if (!this.serverAdapter) {
+			this.serverAdapter = await this.initializeServerAdapter();
+		}
+
+		return this.serverAdapter.handleRequest(request);
+	}
+}
+
+export async function createNodeApp(options: EcopagesAppOptions): Promise<NodeEcopagesApp> {
+	return new NodeEcopagesApp(options, {
+		runtimeHost: new NodeRuntimeHost(new NodeHttpRequestBridge()),
+	});
+}
+
+export async function createApp(options: EcopagesAppOptions): Promise<NodeEcopagesApp> {
+	return createNodeApp(options);
+}

package/src/adapters/node/http-request-bridge.test.ts

@@ -0,0 +1,146 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { PassThrough, Writable } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import { NodeClientAbortError, NodeHttpRequestBridge } from './http-request-bridge.ts';
+
+class MockIncomingMessage extends PassThrough {
+	public url = '/submit?ok=1';
+	public method = 'POST';
+	public headers: Record<string, string | string[] | undefined> = {
+		'content-type': 'application/json',
+		'x-test': 'one',
+	};
+
+	public emitAbort(): void {
+		this.emit('aborted');
+	}
+
+	public emitNodeError(code: string): void {
+		const error = new Error(code) as NodeJS.ErrnoException;
+		error.code = code;
+		this.emit('error', error);
+	}
+}
+
+/**
+ * Writable test double that captures streamed response output and headers for
+ * bridge assertions.
+ */
+class MockServerResponse extends Writable {
+	public statusCode = 200;
+	public headers = new Map<string, string>();
+	public chunks: Buffer[] = [];
+
+	public setHeader(name: string, value: string): void {
+		this.headers.set(name, value);
+	}
+
+	public override _write(
+		chunk: string | Buffer,
+		_encoding: BufferEncoding,
+		callback: (error?: Error | null) => void,
+	): void {
+		this.chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+		callback();
+	}
+}
+
+describe('NodeHttpRequestBridge', () => {
+	it('creates a streaming Web Request for non-GET request bodies', async () => {
+		const bridge = new NodeHttpRequestBridge();
+		const req = new MockIncomingMessage();
+
+		const request = bridge.createWebRequest(req as unknown as IncomingMessage, 'http://localhost:3000');
+		const bodyRead = request.text();
+
+		req.end('{"hello":"world"}');
+
+		expect(request.method).toBe('POST');
+		expect(request.url).toBe('http://localhost:3000/submit?ok=1');
+		expect(request.headers.get('content-type')).toBe('application/json');
+		expect(request.headers.get('x-test')).toBe('one');
+		await expect(bodyRead).resolves.toBe('{"hello":"world"}');
+	});
+
+	it('does not attach a body for GET requests', () => {
+		const bridge = new NodeHttpRequestBridge();
+		const req = new MockIncomingMessage();
+		req.method = 'GET';
+
+		const request = bridge.createWebRequest(req as unknown as IncomingMessage, 'http://localhost:3000');
+
+		expect(request.method).toBe('GET');
+		expect(request.body).toBeNull();
+	});
+
+	it('normalizes aborted request bodies into NodeClientAbortError', async () => {
+		const bridge = new NodeHttpRequestBridge();
+		const req = new MockIncomingMessage();
+
+		const request = bridge.createWebRequest(req as unknown as IncomingMessage, 'http://localhost:3000');
+		const bodyRead = request.text();
+
+		req.emitAbort();
+
+		await expect(bodyRead).rejects.toBeInstanceOf(NodeClientAbortError);
+	});
+
+	it('normalizes ECONNRESET request stream errors into NodeClientAbortError', async () => {
+		const bridge = new NodeHttpRequestBridge();
+		const req = new MockIncomingMessage();
+
+		const request = bridge.createWebRequest(req as unknown as IncomingMessage, 'http://localhost:3000');
+		const bodyRead = request.text();
+
+		req.emitNodeError('ECONNRESET');
+
+		await expect(bodyRead).rejects.toBeInstanceOf(NodeClientAbortError);
+	});
+
+	it('streams response bodies to the Node response without buffering through arrayBuffer', async () => {
+		const bridge = new NodeHttpRequestBridge();
+		const response = new Response(
+			new ReadableStream({
+				start(controller) {
+					controller.enqueue(new TextEncoder().encode('hello '));
+					controller.enqueue(new TextEncoder().encode('world'));
+					controller.close();
+				},
+			}),
+			{
+				status: 206,
+				headers: {
+					'content-type': 'text/plain; charset=utf-8',
+				},
+			},
+		);
+
+		const arrayBufferSpy = vi.spyOn(response, 'arrayBuffer');
+		const res = new MockServerResponse();
+
+		await bridge.sendNodeResponse(res as unknown as ServerResponse, response);
+
+		expect(res.statusCode).toBe(206);
+		expect(res.headers.get('content-type')).toBe('text/plain; charset=utf-8');
+		expect(Buffer.concat(res.chunks).toString('utf8')).toBe('hello world');
+		expect(arrayBufferSpy).not.toHaveBeenCalled();
+	});
+
+	it('normalizes closed response streams into NodeClientAbortError', async () => {
+		const bridge = new NodeHttpRequestBridge();
+		const response = new Response(
+			new ReadableStream({
+				start(controller) {
+					controller.enqueue(new TextEncoder().encode('hello world'));
+					controller.close();
+				},
+			}),
+		);
+		const res = new MockServerResponse();
+		res.destroy();
+
+		await expect(bridge.sendNodeResponse(res as unknown as ServerResponse, response)).rejects.toBeInstanceOf(
+			NodeClientAbortError,
+		);
+	});
+});

package/src/adapters/node/http-request-bridge.ts

@@ -0,0 +1,176 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+/**
+ * Signals that the remote client closed the HTTP exchange before the Node
+ * adapter finished reading or writing the body.
+ *
+ * @remarks
+ * This error represents a transport-level disconnect, not an application
+ * failure. Higher layers may safely suppress logging for this error when the
+ * client socket is already gone and no meaningful response can still be sent.
+ */
+export class NodeClientAbortError extends Error {
+	/**
+	 * Creates the canonical Node transport abort error used across request-body
+	 * reads and response-body writes.
+	 */
+	constructor() {
+		super('Client closed the request');
+		this.name = 'ClientAbortError';
+	}
+}
+
+/**
+ * Returns whether a Node stream error code corresponds to a normal client-side
+ * disconnect rather than a server fault.
+ *
+ * @remarks
+ * The allowlist is intentionally narrow. Only socket and stream shutdown codes
+ * that are expected after browser aborts or navigation churn are treated as
+ * suppressible client disconnects.
+ */
+function isNodeClientDisconnectCode(code: string | undefined): boolean {
+	return [
+		'ECONNRESET',
+		'EPIPE',
+		'ERR_STREAM_DESTROYED',
+		'ERR_STREAM_PREMATURE_CLOSE',
+		'ERR_STREAM_UNABLE_TO_PIPE',
+	].includes(code ?? '');
+}
+
+/**
+ * Type guard for the canonical client-abort error used by the Node adapter.
+ *
+ * @remarks
+ * Runtime hosts use this guard before logging so only explicitly classified
+ * client disconnects are muted. All other failures continue through the normal
+ * error-reporting path.
+ */
+export function isNodeClientAbortError(error: unknown): error is NodeClientAbortError {
+	return error instanceof NodeClientAbortError;
+}
+
+/**
+ * Normalizes low-level Node socket and stream shutdown errors into the shared
+ * `NodeClientAbortError` abstraction used by the adapter stack.
+ *
+ * @remarks
+ * This normalization exists at the transport boundary because Node exposes
+ * several host-specific error codes for the same underlying event: the client
+ * disappeared before the response stream finished. Converting them here keeps
+ * the rest of the adapter stack independent from those Node-specific details.
+ */
+function toNodeClientAbortError(error: unknown): NodeClientAbortError | null {
+	if (error instanceof NodeClientAbortError) {
+		return error;
+	}
+
+	if (typeof error === 'object' && error !== null && 'code' in error) {
+		const code = typeof error.code === 'string' ? error.code : undefined;
+		if (isNodeClientDisconnectCode(code)) {
+			return new NodeClientAbortError();
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Bridges Node's `IncomingMessage` / `ServerResponse` pair to the Web
+ * `Request` / `Response` contract used by the shared routing pipeline.
+ *
+ * @remarks
+ * This class is the Node transport boundary. It owns the translation of request
+ * headers and bodies into Web primitives and the reverse translation of Web
+ * responses back onto Node streams, including client-abort normalization.
+ */
+export class NodeHttpRequestBridge {
+	/**
+	 * Converts one incoming Node request into the Web `Request` shape consumed by
+	 * the shared server adapter.
+	 *
+	 * @remarks
+	 * Non-GET/HEAD requests retain streaming semantics via a `ReadableStream` so
+	 * large request bodies do not need to be buffered before route handling begins.
+	 */
+	public createWebRequest(req: IncomingMessage, runtimeOrigin: string): Request {
+		const url = new URL(req.url ?? '/', runtimeOrigin);
+		const headers = new Headers();
+
+		for (const [key, value] of Object.entries(req.headers)) {
+			if (Array.isArray(value)) {
+				for (const item of value) {
+					headers.append(key, item);
+				}
+				continue;
+			}
+
+			if (value !== undefined) {
+				headers.set(key, value);
+			}
+		}
+
+		const method = (req.method ?? 'GET').toUpperCase();
+		const requestInit: RequestInit & { duplex?: 'half' } = {
+			method,
+			headers,
+		};
+
+		if (method !== 'GET' && method !== 'HEAD') {
+			const body = new ReadableStream({
+				start(controller) {
+					req.on('data', (chunk: Buffer) => controller.enqueue(chunk));
+					req.once('end', () => controller.close());
+					req.once('aborted', () => {
+						controller.error(new NodeClientAbortError());
+					});
+					req.once('error', (err) => {
+						const isClientAbort = (err as NodeJS.ErrnoException).code === 'ECONNRESET';
+						controller.error(isClientAbort ? new NodeClientAbortError() : err);
+					});
+				},
+				cancel() {
+					req.destroy();
+				},
+			});
+
+			requestInit.body = body;
+			requestInit.duplex = 'half';
+		}
+
+		return new Request(url, requestInit);
+	}
+
+	/**
+	 * Sends a Web `Response` through Node's `ServerResponse` without buffering the
+	 * full body in memory first.
+	 *
+	 * @remarks
+	 * Streaming responses matter for large payloads and long-lived transports such
+	 * as server-sent events. The bridge therefore forwards the `ReadableStream`
+	 * directly into the Node writable response instead of materializing an
+	 * intermediate `ArrayBuffer`.
+	 */
+	public async sendNodeResponse(res: ServerResponse, response: Response): Promise<void> {
+		res.statusCode = response.status;
+
+		response.headers.forEach((value, key) => {
+			res.setHeader(key, value);
+		});
+
+		if (!response.body) {
+			res.end();
+			return;
+		}
+
+		const responseBody = response.body as unknown as Parameters<typeof Readable.fromWeb>[0];
+		try {
+			await pipeline(Readable.fromWeb(responseBody), res);
+		} catch (error) {
+			throw toNodeClientAbortError(error) ?? error;
+		}
+	}
+}