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

package/src/adapters/node/static-content-server.ts

@@ -1,239 +0,0 @@
-import { createServer, type IncomingMessage, type Server as NodeHttpServer, type ServerResponse } from 'node:http';
-import { extname, join, normalize, sep } from 'node:path';
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT, STATUS_MESSAGE } from '../../config/constants.ts';
-import { fileSystem } from '@ecopages/file-system';
-import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
-import { ServerUtils } from '../../utils/server-utils.module.ts';
-
-type NodeStaticContentServerOptions = {
-	hostname?: string;
-	port?: number;
-};
-
-/**
- * Serves prebuilt static Ecopages output through Node's HTTP server.
- *
- * @remarks
- * This server is used by the Node preview/build path once the app has already
- * emitted its static output. It intentionally stays small: path sanitization,
- * content-type selection, optional gzip serving, and 404 handling.
- */
-export class NodeStaticContentServer {
-	private readonly appConfig: EcoPagesAppConfig;
-	private readonly options: NodeStaticContentServerOptions;
-	private server: NodeHttpServer | null = null;
-
-	/**
-	 * Creates the Node static-content server for one built app output directory.
-	 */
-	constructor({ appConfig, options }: { appConfig: EcoPagesAppConfig; options?: NodeStaticContentServerOptions }) {
-		this.appConfig = appConfig;
-		this.options = {
-			hostname: options?.hostname ?? DEFAULT_ECOPAGES_HOSTNAME,
-			port: options?.port ?? DEFAULT_ECOPAGES_PORT,
-		};
-	}
-
-	/**
-	 * Returns whether the given content type should be served from a pre-gzipped
-	 * companion file when available.
-	 */
-	private shouldServeGzip(contentType: string): boolean {
-		return ['text/javascript', 'text/css'].includes(contentType);
-	}
-
-	/**
-	 * Normalizes a request pathname and rejects directory traversal attempts.
-	 */
-	private sanitizePath(pathname: string): string | null {
-		const withoutLeadingSlash = pathname.replace(/^\/+/, '');
-		const normalizedPath = normalize(withoutLeadingSlash);
-
-		if (normalizedPath.startsWith('..') || normalizedPath.includes(`..${sep}`)) {
-			return null;
-		}
-
-		return normalizedPath;
-	}
-
-	/**
-	 * Writes one HTTP response with the provided headers and optional body.
-	 */
-	private sendResponse(res: ServerResponse, status: number, headers: Record<string, string>, body?: Buffer): void {
-		res.statusCode = status;
-		for (const [key, value] of Object.entries(headers)) {
-			res.setHeader(key, value);
-		}
-
-		if (!body) {
-			res.end();
-			return;
-		}
-
-		res.end(body);
-	}
-
-	/**
-	 * Serves the generated 404 page when present, or a plain-text fallback.
-	 */
-	private sendNotFoundPage(req: IncomingMessage, res: ServerResponse): void {
-		const error404TemplatePath = join(this.appConfig.absolutePaths.distDir, '404.html');
-		const isHead = (req.method ?? 'GET').toUpperCase() === 'HEAD';
-
-		if (!fileSystem.exists(error404TemplatePath)) {
-			this.sendResponse(
-				res,
-				404,
-				{ 'Content-Type': 'text/plain' },
-				isHead ? undefined : Buffer.from(STATUS_MESSAGE[404]),
-			);
-			return;
-		}
-
-		const file = fileSystem.readFileAsBuffer(error404TemplatePath);
-		this.sendResponse(res, 404, { 'Content-Type': 'text/html' }, isHead ? undefined : file);
-	}
-
-	/**
-	 * Serves one concrete file path, honoring gzip and HEAD semantics.
-	 */
-	private serveFile(req: IncomingMessage, res: ServerResponse, filePath: string, status = 200): void {
-		const contentType = ServerUtils.getContentType(extname(filePath));
-		const acceptsGzip = req.headers['accept-encoding']?.includes('gzip');
-		const isHead = (req.method ?? 'GET').toUpperCase() === 'HEAD';
-
-		if (acceptsGzip && this.shouldServeGzip(contentType)) {
-			const gzipPath = `${filePath}.gz`;
-			if (fileSystem.exists(gzipPath)) {
-				const file = fileSystem.readFileAsBuffer(gzipPath);
-				this.sendResponse(
-					res,
-					status,
-					{
-						'Content-Type': contentType,
-						'Content-Encoding': 'gzip',
-						Vary: 'Accept-Encoding',
-					},
-					isHead ? undefined : file,
-				);
-				return;
-			}
-		}
-
-		if (!fileSystem.exists(filePath)) {
-			this.sendNotFoundPage(req, res);
-			return;
-		}
-
-		const file = fileSystem.readFileAsBuffer(filePath);
-		this.sendResponse(res, status, { 'Content-Type': contentType }, isHead ? undefined : file);
-	}
-
-	/**
-	 * Handles one incoming Node HTTP request against the built static output tree.
-	 */
-	private handleRequest(req: IncomingMessage, res: ServerResponse): void {
-		const method = (req.method ?? 'GET').toUpperCase();
-		const isHead = method === 'HEAD';
-		if (method !== 'GET' && method !== 'HEAD') {
-			this.sendResponse(
-				res,
-				405,
-				{ Allow: 'GET, HEAD', 'Content-Type': 'text/plain' },
-				isHead ? undefined : Buffer.from('Method Not Allowed'),
-			);
-			return;
-		}
-
-		const url = new URL(req.url ?? '/', 'http://localhost');
-		let decodedPathname = '/';
-		try {
-			decodedPathname = decodeURIComponent(url.pathname);
-		} catch {
-			this.sendResponse(
-				res,
-				400,
-				{ 'Content-Type': 'text/plain' },
-				isHead ? undefined : Buffer.from('Invalid path'),
-			);
-			return;
-		}
-
-		const pathname = decodedPathname === '/' ? '/index.html' : decodedPathname;
-		const relativePath = this.sanitizePath(pathname);
-
-		if (!relativePath) {
-			this.sendResponse(
-				res,
-				400,
-				{ 'Content-Type': 'text/plain' },
-				isHead ? undefined : Buffer.from('Invalid path'),
-			);
-			return;
-		}
-
-		const basePath = join(this.appConfig.absolutePaths.distDir, relativePath);
-
-		if (pathname.includes('.')) {
-			this.serveFile(req, res, basePath);
-			return;
-		}
-
-		const htmlCandidates = [`${basePath}.html`, join(basePath, 'index.html')];
-
-		for (const candidate of htmlCandidates) {
-			if (fileSystem.exists(candidate)) {
-				this.serveFile(req, res, candidate);
-				return;
-			}
-		}
-
-		this.sendNotFoundPage(req, res);
-	}
-
-	/**
-	 * Starts the static preview server.
-	 */
-	public async start(): Promise<NodeHttpServer> {
-		if (this.server) {
-			return this.server;
-		}
-
-		this.server = createServer(this.handleRequest.bind(this));
-		const hostname = this.options.hostname ?? DEFAULT_ECOPAGES_HOSTNAME;
-		const port = this.options.port ?? DEFAULT_ECOPAGES_PORT;
-
-		await new Promise<void>((resolve) => {
-			this.server!.listen(port, hostname, () => resolve());
-		});
-
-		return this.server;
-	}
-
-	/**
-	 * Stops the static preview server and optionally closes active connections.
-	 */
-	public async stop(force = true): Promise<void> {
-		if (!this.server) {
-			return;
-		}
-
-		const activeServer = this.server;
-		this.server = null;
-
-		await new Promise<void>((resolve, reject) => {
-			activeServer.close((error) => {
-				if (error) {
-					reject(error);
-					return;
-				}
-
-				resolve();
-			});
-
-			if (force) {
-				activeServer.closeAllConnections();
-			}
-		});
-	}
-}

package/src/adapters/node/static-preview-host.test.ts

@@ -1,89 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
-import { NodeStaticPreviewHost } from './static-preview-host.ts';
-
-type TestPreviewServer = {
-	start: ReturnType<typeof vi.fn>;
-	stop: ReturnType<typeof vi.fn>;
-};
-
-/**
- * Creates a constructable preview-server class so the host can instantiate the
- * test double through the same code path it uses in production.
- */
-function createPreviewServerFactory(previewServer: TestPreviewServer) {
-	/**
-	 * Constructable preview-server wrapper used by the host tests.
-	 */
-	return class TestPreviewServerFactory {
-		constructor(_args: unknown) {}
-
-		public start = previewServer.start;
-		public stop = previewServer.stop;
-	};
-}
-
-/**
- * Returns the smallest app config surface required by the preview-host tests.
- */
-function createAppConfig(): EcoPagesAppConfig {
-	return {
-		rootDir: '/tmp/app',
-		distDir: '.ecopages',
-		runtime: {},
-	} as unknown as EcoPagesAppConfig;
-}
-
-describe('NodeStaticPreviewHost', () => {
-	it('coalesces overlapping stop calls onto one server shutdown', async () => {
-		let resolveStop: (() => void) | undefined;
-		const previewServer: TestPreviewServer = {
-			start: vi.fn().mockResolvedValue({
-				address: () => ({ port: 4173 }),
-			}),
-			stop: vi.fn().mockImplementation(
-				() =>
-					new Promise<void>((resolve) => {
-						resolveStop = resolve;
-					}),
-			),
-		};
-
-		const host = new NodeStaticPreviewHost(createPreviewServerFactory(previewServer) as never);
-
-		await host.start({
-			appConfig: createAppConfig(),
-			hostname: 'localhost',
-			port: 4173,
-		});
-
-		const firstStop = host.stop();
-		const secondStop = host.stop();
-
-		expect(previewServer.stop).toHaveBeenCalledTimes(1);
-
-		resolveStop?.();
-		await Promise.all([firstStop, secondStop]);
-	});
-
-	it('keeps the active server reference when shutdown fails so stop can be retried', async () => {
-		const previewServer: TestPreviewServer = {
-			start: vi.fn().mockResolvedValue({
-				address: () => ({ port: 4173 }),
-			}),
-			stop: vi.fn().mockRejectedValueOnce(new Error('close failed')).mockResolvedValueOnce(undefined),
-		};
-
-		const host = new NodeStaticPreviewHost(createPreviewServerFactory(previewServer) as never);
-
-		await host.start({
-			appConfig: createAppConfig(),
-			hostname: 'localhost',
-			port: 4173,
-		});
-
-		await expect(host.stop()).rejects.toThrow('close failed');
-		await expect(host.stop()).resolves.toBeUndefined();
-		expect(previewServer.stop).toHaveBeenCalledTimes(2);
-	});
-});

package/src/adapters/node/static-preview-host.ts

@@ -1,101 +0,0 @@
-import type { AddressInfo } from 'node:net';
-import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
-import type { StaticPreviewHost, StaticPreviewHostStartOptions } from '../shared/static-preview-host.ts';
-import { NodeStaticContentServer } from './static-content-server.ts';
-
-type NodeStaticPreviewServer = {
-	start(): Promise<{ address(): AddressInfo | string | null }>;
-	stop(force?: boolean): Promise<void>;
-};
-
-type NodeStaticPreviewServerFactory = new (args: {
-	appConfig: EcoPagesAppConfig;
-	options?: {
-		hostname?: string;
-		port?: number;
-	};
-}) => NodeStaticPreviewServer;
-
-/**
- * Node preview-host wrapper that manages the lifecycle of the static preview
- * server used after a build.
- *
- * @remarks
- * The host separates preview-server construction from lifecycle control so the
- * Node server adapter can restart preview serving safely across repeated build
- * and preview flows.
- */
-export class NodeStaticPreviewHost implements StaticPreviewHost {
-	private previewServer: NodeStaticPreviewServer | null = null;
-	private stopPromise: Promise<void> | null = null;
-
-	/**
-	 * Creates the preview host with an injectable preview-server constructor.
-	 */
-	constructor(private readonly previewServerFactory: NodeStaticPreviewServerFactory = NodeStaticContentServer) {}
-
-	/**
-	 * Starts the Node preview host after fully draining any previous preview server
-	 * shutdown that may still be in flight.
-	 *
-	 * @remarks
-	 * The host only publishes a new preview server after `start()` succeeds. That
-	 * keeps failed startup attempts from replacing the last known-good server with a
-	 * half-initialized instance.
-	 */
-	public async start(options: StaticPreviewHostStartOptions): Promise<number | null> {
-		await this.stop();
-
-		const previewServer = new this.previewServerFactory({
-			appConfig: options.appConfig,
-			options: {
-				hostname: options.hostname,
-				port: options.port,
-			},
-		});
-
-		const server = await previewServer.start();
-		this.previewServer = previewServer;
-		const address = server.address();
-
-		if (address && typeof address === 'object') {
-			return address.port;
-		}
-
-		return options.port;
-	}
-
-	/**
-	 * Stops the active preview server and coalesces overlapping stop requests onto
-	 * the same shutdown promise.
-	 *
-	 * @remarks
-	 * The host keeps the server reference until shutdown succeeds. If shutdown
-	 * fails, callers can still retry `stop()` or inspect the same live instance
-	 * instead of losing the handle during a rejected async stop.
-	 */
-	public async stop(force = true): Promise<void> {
-		if (this.stopPromise) {
-			await this.stopPromise;
-			return;
-		}
-
-		if (!this.previewServer) {
-			return;
-		}
-
-		const activePreviewServer = this.previewServer;
-		this.stopPromise = activePreviewServer
-			.stop(force)
-			.then(() => {
-				if (this.previewServer === activePreviewServer) {
-					this.previewServer = null;
-				}
-			})
-			.finally(() => {
-				this.stopPromise = null;
-			});
-
-		await this.stopPromise;
-	}
-}

package/src/adapters/shared/api-response.test.ts

@@ -1,97 +0,0 @@
-import { beforeEach, describe, expect, it } from 'vitest';
-import { ApiResponseBuilder } from './api-response';
-
-describe('ApiResponseBuilder', () => {
-	let builder: ApiResponseBuilder;
-
-	beforeEach(() => {
-		builder = new ApiResponseBuilder();
-	});
-
-	describe('json()', () => {
-		it('should create JSON response with correct content type and data', async () => {
-			const data = { foo: 'bar' };
-			const response = builder.json(data);
-
-			expect(response.headers.get('Content-Type')).toBe('application/json; charset=utf-8');
-			expect(await response.json()).toEqual(data);
-			expect(response.status).toBe(200);
-		});
-	});
-
-	describe('text()', () => {
-		it('should create text response with correct content type and data', async () => {
-			const text = 'Hello World';
-			const response = builder.text(text);
-
-			expect(response.headers.get('Content-Type')).toBe('text/plain; charset=utf-8');
-			expect(await response.text()).toBe(text);
-			expect(response.status).toBe(200);
-		});
-	});
-
-	describe('html()', () => {
-		it('should create HTML response with correct content type and data', async () => {
-			const html = '<h1>Hello</h1>';
-			const response = builder.html(html);
-
-			expect(response.headers.get('Content-Type')).toBe('text/html; charset=utf-8');
-			expect(await response.text()).toBe(html);
-			expect(response.status).toBe(200);
-		});
-	});
-
-	describe('status()', () => {
-		it('should set custom status code', () => {
-			const response = builder.status(404).json({ message: 'Not Found' });
-			expect(response.status).toBe(404);
-		});
-	});
-
-	describe('headers()', () => {
-		it('should set custom headers', () => {
-			const response = builder.headers({ 'X-Custom': 'Value' }).json({});
-			expect(response.headers.get('X-Custom')).toBe('Value');
-		});
-	});
-
-	describe('redirect()', () => {
-		it('should create redirect response with location header', () => {
-			const url = 'https://example.com';
-			const response = builder.redirect(url);
-
-			expect(response.headers.get('Location')).toBe(url);
-			expect(response.status).toBe(302);
-		});
-
-		it('should use explicit status for redirect', () => {
-			const response = builder.redirect('https://example.com', 301);
-			expect(response.status).toBe(301);
-		});
-	});
-
-	describe('error()', () => {
-		it('should create JSON error response for object data', async () => {
-			const error = { code: 'ERR_1', message: 'Error occurred' };
-			const response = builder.error(error);
-
-			expect(response.headers.get('Content-Type')).toBe('application/json; charset=utf-8');
-			expect(await response.json()).toEqual({ error });
-			expect(response.status).toBe(500);
-		});
-
-		it('should create text error response for string data', async () => {
-			const error = 'Error occurred';
-			const response = builder.error(error);
-
-			expect(response.headers.get('Content-Type')).toBe('text/plain; charset=utf-8');
-			expect(await response.text()).toBe(error);
-			expect(response.status).toBe(500);
-		});
-
-		it('should use explicit status for error', () => {
-			const response = builder.error('Not Found', 404);
-			expect(response.status).toBe(404);
-		});
-	});
-});

package/src/adapters/shared/api-response.ts

@@ -1,104 +0,0 @@
-/**
- * A builder class for creating Response objects fluently.
- */
-export class ApiResponseBuilder {
-	private _status: Response['status'] = 200;
-	private _headers: Headers = new Headers();
-
-	/**
-	 * Sets the HTTP status code for the response.
-	 * @param code - The HTTP status code.
-	 * @returns The builder instance for chaining.
-	 */
-	status(code: Response['status']): this {
-		this._status = code;
-		return this;
-	}
-
-	/**
-	 * Adds or merges headers for the response.
-	 * @param headersInit - Headers to add or merge.
-	 * @returns The builder instance for chaining.
-	 */
-	headers(headersInit: HeadersInit): this {
-		const inputHeaders = new Headers(headersInit);
-		inputHeaders.forEach((value, key) => {
-			this._headers.set(key, value);
-		});
-		return this;
-	}
-
-	/**
-	 * Creates a JSON response using the configured status and headers.
-	 * @param data - The data to serialize.
-	 * @returns A Response object.
-	 */
-	json(data: any): Response {
-		if (!this._headers.has('Content-Type')) {
-			this._headers.set('Content-Type', 'application/json; charset=utf-8');
-		}
-		return new Response(JSON.stringify(data), { status: this._status, headers: this._headers });
-	}
-
-	/**
-	 * Creates a plain text response using the configured status and headers.
-	 * @param data - The text content.
-	 * @returns A Response object.
-	 */
-	text(data: string): Response {
-		if (!this._headers.has('Content-Type')) {
-			this._headers.set('Content-Type', 'text/plain; charset=utf-8');
-		}
-		return new Response(data, { status: this._status, headers: this._headers });
-	}
-
-	/**
-	 * Creates an HTML response using the configured status and headers.
-	 * @param data - The HTML content.
-	 * @returns A Response object.
-	 */
-	html(data: string): Response {
-		if (!this._headers.has('Content-Type')) {
-			this._headers.set('Content-Type', 'text/html; charset=utf-8');
-		}
-		return new Response(data, { status: this._status, headers: this._headers });
-	}
-
-	/**
-	 * Creates a redirect response.
-	 * @param url - The URL to redirect to.
-	 * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 302 if not set via status().
-	 * @returns A Response object.
-	 */
-	redirect(url: string, explicitStatus?: Response['status']): Response {
-		const redirectStatus = explicitStatus ?? (this._status === 200 ? 302 : this._status); // Default to 302 if status wasn't explicitly set
-		this._headers.set('Location', url);
-		return new Response(null, { status: redirectStatus, headers: this._headers });
-	}
-
-	/**
-	 * Creates an error response using the configured status and headers.
-	 * If data is an object, it's treated as JSON, otherwise as text.
-	 * @param data - The error data (string or object).
-	 * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 500 if not set via status().
-	 * @returns A Response object.
-	 */
-	error(data: string | object, explicitStatus?: Response['status']): Response {
-		const errorStatus = explicitStatus ?? (this._status === 200 ? 500 : this._status); // Default to 500 if status wasn't explicitly set
-		this.status(errorStatus);
-
-		if (typeof data === 'object' && data !== null) {
-			if (!this._headers.has('Content-Type')) {
-				this._headers.set('Content-Type', 'application/json; charset=utf-8');
-			}
-			return new Response(JSON.stringify({ error: data }), {
-				status: this._status,
-				headers: this._headers,
-			});
-		}
-		if (!this._headers.has('Content-Type')) {
-			this._headers.set('Content-Type', 'text/plain; charset=utf-8');
-		}
-		return new Response(String(data), { status: this._status, headers: this._headers });
-	}
-}