create-phoenixjs 0.1.0

package/template/framework/http/Response.ts

@@ -0,0 +1,525 @@
+/**
+ * PhoenixJS - Response Helper
+ * 
+ * Static helper class and fluent builder for creating HTTP responses.
+ */
+
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+export interface ResponseOptions {
+	status?: number;
+	headers?: Record<string, string>;
+}
+
+export interface CookieOptions {
+	maxAge?: number;
+	expires?: Date;
+	path?: string;
+	domain?: string;
+	secure?: boolean;
+	httpOnly?: boolean;
+	sameSite?: 'Strict' | 'Lax' | 'None';
+}
+
+interface Cookie {
+	name: string;
+	value: string;
+	options: CookieOptions;
+}
+
+/**
+ * Fluent Response Builder
+ * Allows chaining methods to build a response
+ */
+export class ResponseBuilder {
+	private statusCode = 200;
+	private responseHeaders: Map<string, string> = new Map();
+	private responseCookies: Cookie[] = [];
+
+	/**
+	 * Set the response status code
+	 */
+	status(code: number): this {
+		this.statusCode = code;
+		return this;
+	}
+
+	/**
+	 * Add a header to the response
+	 */
+	header(name: string, value: string): this {
+		this.responseHeaders.set(name, value);
+		return this;
+	}
+
+	/**
+	 * Add multiple headers
+	 */
+	withHeaders(headers: Record<string, string>): this {
+		for (const [name, value] of Object.entries(headers)) {
+			this.responseHeaders.set(name, value);
+		}
+		return this;
+	}
+
+	/**
+	 * Set a cookie
+	 */
+	cookie(name: string, value: string, options: CookieOptions = {}): this {
+		this.responseCookies.push({ name, value, options });
+		return this;
+	}
+
+	/**
+	 * Remove a cookie (set it to expire immediately)
+	 */
+	withoutCookie(name: string, options: CookieOptions = {}): this {
+		this.responseCookies.push({
+			name,
+			value: '',
+			options: { ...options, maxAge: 0 },
+		});
+		return this;
+	}
+
+	/**
+	 * Set CORS headers
+	 */
+	cors(origin: string = '*', options: {
+		methods?: string[];
+		headers?: string[];
+		credentials?: boolean;
+		maxAge?: number;
+	} = {}): this {
+		this.header('Access-Control-Allow-Origin', origin);
+
+		if (options.methods) {
+			this.header('Access-Control-Allow-Methods', options.methods.join(', '));
+		}
+		if (options.headers) {
+			this.header('Access-Control-Allow-Headers', options.headers.join(', '));
+		}
+		if (options.credentials) {
+			this.header('Access-Control-Allow-Credentials', 'true');
+		}
+		if (options.maxAge) {
+			this.header('Access-Control-Max-Age', options.maxAge.toString());
+		}
+
+		return this;
+	}
+
+	/**
+	 * Set cache control headers
+	 */
+	cache(maxAge: number, options: {
+		public?: boolean;
+		private?: boolean;
+		noStore?: boolean;
+		mustRevalidate?: boolean;
+	} = {}): this {
+		const directives: string[] = [];
+
+		if (options.public) directives.push('public');
+		if (options.private) directives.push('private');
+		if (options.noStore) directives.push('no-store');
+		if (options.mustRevalidate) directives.push('must-revalidate');
+
+		directives.push(`max-age=${maxAge}`);
+
+		this.header('Cache-Control', directives.join(', '));
+		return this;
+	}
+
+	/**
+	 * Disable caching
+	 */
+	noCache(): this {
+		this.header('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate');
+		this.header('Pragma', 'no-cache');
+		this.header('Expires', '0');
+		return this;
+	}
+
+	/**
+	 * Build and return a JSON response
+	 */
+	json(data: unknown): Response {
+		this.header('Content-Type', 'application/json');
+		return this.build(JSON.stringify(data));
+	}
+
+	/**
+	 * Build and return a text response
+	 */
+	text(content: string): Response {
+		this.header('Content-Type', 'text/plain');
+		return this.build(content);
+	}
+
+	/**
+	 * Build and return an HTML response
+	 */
+	html(content: string): Response {
+		this.header('Content-Type', 'text/html');
+		return this.build(content);
+	}
+
+	/**
+	 * Build and return an XML response
+	 */
+	xml(content: string): Response {
+		this.header('Content-Type', 'application/xml');
+		return this.build(content);
+	}
+
+	/**
+	 * Build and return a file download response
+	 */
+	download(content: Buffer | string | Uint8Array, filename: string, mimeType?: string): Response {
+		const contentType = mimeType ?? 'application/octet-stream';
+		this.header('Content-Type', contentType);
+		this.header('Content-Disposition', `attachment; filename="${filename}"`);
+		return this.build(content);
+	}
+
+	/**
+	 * Build and return an inline file response (displayed in browser)
+	 */
+	file(content: Buffer | Uint8Array, mimeType: string, filename?: string): Response {
+		this.header('Content-Type', mimeType);
+		if (filename) {
+			this.header('Content-Disposition', `inline; filename="${filename}"`);
+		}
+		return this.build(content);
+	}
+
+	/**
+	 * Build and return a streaming response
+	 */
+	stream(readable: ReadableStream, mimeType: string = 'application/octet-stream'): Response {
+		this.header('Content-Type', mimeType);
+		return new Response(readable, {
+			status: this.statusCode,
+			headers: this.buildHeaders(),
+		});
+	}
+
+	/**
+	 * Build and return a redirect response
+	 */
+	redirect(url: string, permanent: boolean = false): Response {
+		this.statusCode = permanent ? 301 : 302;
+		this.header('Location', url);
+		return this.build(null);
+	}
+
+	/**
+	 * Build and return a 204 No Content response
+	 */
+	noContent(): Response {
+		this.statusCode = 204;
+		return this.build(null);
+	}
+
+	/**
+	 * Build the final response
+	 */
+	build(body?: string | ArrayBuffer | Uint8Array | ReadableStream | null): Response {
+		return new Response(body, {
+			status: this.statusCode,
+			headers: this.buildHeaders(),
+		});
+	}
+
+	/**
+	 * Build headers including cookies
+	 */
+	private buildHeaders(): Headers {
+		const headers = new Headers();
+
+		for (const [name, value] of this.responseHeaders) {
+			headers.set(name, value);
+		}
+
+		// Add cookies as Set-Cookie headers
+		for (const cookie of this.responseCookies) {
+			headers.append('Set-Cookie', this.serializeCookie(cookie));
+		}
+
+		return headers;
+	}
+
+	/**
+	 * Serialize a cookie to a Set-Cookie header value
+	 */
+	private serializeCookie(cookie: Cookie): string {
+		const parts = [`${encodeURIComponent(cookie.name)}=${encodeURIComponent(cookie.value)}`];
+		const opts = cookie.options;
+
+		if (opts.maxAge !== undefined) {
+			parts.push(`Max-Age=${opts.maxAge}`);
+		}
+		if (opts.expires) {
+			parts.push(`Expires=${opts.expires.toUTCString()}`);
+		}
+		if (opts.path) {
+			parts.push(`Path=${opts.path}`);
+		}
+		if (opts.domain) {
+			parts.push(`Domain=${opts.domain}`);
+		}
+		if (opts.secure) {
+			parts.push('Secure');
+		}
+		if (opts.httpOnly) {
+			parts.push('HttpOnly');
+		}
+		if (opts.sameSite) {
+			parts.push(`SameSite=${opts.sameSite}`);
+		}
+
+		return parts.join('; ');
+	}
+}
+
+/**
+ * Static Response Helper
+ * Provides shorthand methods for common responses
+ */
+export class FrameworkResponse {
+	/**
+	 * Create a new ResponseBuilder for fluent API
+	 */
+	static create(): ResponseBuilder {
+		return new ResponseBuilder();
+	}
+
+	/**
+	 * Create a JSON response
+	 */
+	static json(data: unknown, status = 200, headers: Record<string, string> = {}): Response {
+		return new Response(JSON.stringify(data), {
+			status,
+			headers: {
+				'Content-Type': 'application/json',
+				...headers,
+			},
+		});
+	}
+
+	/**
+	 * Create a text response
+	 */
+	static text(content: string, status = 200, headers: Record<string, string> = {}): Response {
+		return new Response(content, {
+			status,
+			headers: {
+				'Content-Type': 'text/plain',
+				...headers,
+			},
+		});
+	}
+
+	/**
+	 * Create an HTML response
+	 */
+	static html(content: string, status = 200, headers: Record<string, string> = {}): Response {
+		return new Response(content, {
+			status,
+			headers: {
+				'Content-Type': 'text/html',
+				...headers,
+			},
+		});
+	}
+
+	/**
+	 * Create an XML response
+	 */
+	static xml(content: string, status = 200, headers: Record<string, string> = {}): Response {
+		return new Response(content, {
+			status,
+			headers: {
+				'Content-Type': 'application/xml',
+				...headers,
+			},
+		});
+	}
+
+	/**
+	 * Create a redirect response
+	 */
+	static redirect(url: string, status = 302): Response {
+		return new Response(null, {
+			status,
+			headers: {
+				Location: url,
+			},
+		});
+	}
+
+	/**
+	 * Create a permanent redirect (301)
+	 */
+	static permanentRedirect(url: string): Response {
+		return FrameworkResponse.redirect(url, 301);
+	}
+
+	/**
+	 * Create a 204 No Content response
+	 */
+	static noContent(): Response {
+		return new Response(null, { status: 204 });
+	}
+
+	/**
+	 * Create an error response
+	 */
+	static error(message: string, status = 500, details?: Record<string, unknown>): Response {
+		const body: Record<string, unknown> = {
+			error: true,
+			message,
+		};
+		if (details) {
+			body.details = details;
+		}
+		return FrameworkResponse.json(body, status);
+	}
+
+	/**
+	 * Create a 400 Bad Request response
+	 */
+	static badRequest(message: string, details?: Record<string, unknown>): Response {
+		return FrameworkResponse.error(message, 400, details);
+	}
+
+	/**
+	 * Create a 401 Unauthorized response
+	 */
+	static unauthorized(message = 'Unauthorized'): Response {
+		return FrameworkResponse.error(message, 401);
+	}
+
+	/**
+	 * Create a 403 Forbidden response
+	 */
+	static forbidden(message = 'Forbidden'): Response {
+		return FrameworkResponse.error(message, 403);
+	}
+
+	/**
+	 * Create a 404 Not Found response
+	 */
+	static notFound(message = 'Not Found'): Response {
+		return FrameworkResponse.error(message, 404);
+	}
+
+	/**
+	 * Create a 405 Method Not Allowed response
+	 */
+	static methodNotAllowed(message = 'Method Not Allowed', allowed?: string[]): Response {
+		const headers: Record<string, string> = {};
+		if (allowed) {
+			headers['Allow'] = allowed.join(', ');
+		}
+		return new Response(JSON.stringify({ error: true, message }), {
+			status: 405,
+			headers: {
+				'Content-Type': 'application/json',
+				...headers,
+			},
+		});
+	}
+
+	/**
+	 * Create a 409 Conflict response
+	 */
+	static conflict(message = 'Conflict', details?: Record<string, unknown>): Response {
+		return FrameworkResponse.error(message, 409, details);
+	}
+
+	/**
+	 * Create a 422 Unprocessable Entity response (validation errors)
+	 */
+	static validationError(errors: Record<string, string[]>): Response {
+		return FrameworkResponse.json({
+			error: true,
+			message: 'Validation failed',
+			errors,
+		}, 422);
+	}
+
+	/**
+	 * Create a 429 Too Many Requests response
+	 */
+	static tooManyRequests(message = 'Too Many Requests', retryAfter?: number): Response {
+		const headers: Record<string, string> = {};
+		if (retryAfter) {
+			headers['Retry-After'] = retryAfter.toString();
+		}
+		return new Response(JSON.stringify({ error: true, message }), {
+			status: 429,
+			headers: {
+				'Content-Type': 'application/json',
+				...headers,
+			},
+		});
+	}
+
+	/**
+	 * Create a 500 Internal Server Error response
+	 */
+	static serverError(message = 'Internal Server Error', details?: Record<string, unknown>): Response {
+		return FrameworkResponse.error(message, 500, details);
+	}
+
+	/**
+	 * Create a 502 Bad Gateway response
+	 */
+	static badGateway(message = 'Bad Gateway'): Response {
+		return FrameworkResponse.error(message, 502);
+	}
+
+	/**
+	 * Create a 503 Service Unavailable response
+	 */
+	static serviceUnavailable(message = 'Service Unavailable', retryAfter?: number): Response {
+		const headers: Record<string, string> = {};
+		if (retryAfter) {
+			headers['Retry-After'] = retryAfter.toString();
+		}
+		return new Response(JSON.stringify({ error: true, message }), {
+			status: 503,
+			headers: {
+				'Content-Type': 'application/json',
+				...headers,
+			},
+		});
+	}
+
+	/**
+	 * Create a file download response
+	 */
+	static download(content: Buffer | string | Uint8Array, filename: string, mimeType = 'application/octet-stream'): Response {
+		return new Response(content, {
+			status: 200,
+			headers: {
+				'Content-Type': mimeType,
+				'Content-Disposition': `attachment; filename="${filename}"`,
+			},
+		});
+	}
+
+	/**
+	 * Create a streaming response
+	 */
+	static stream(readable: ReadableStream, mimeType = 'application/octet-stream'): Response {
+		return new Response(readable, {
+			status: 200,
+			headers: {
+				'Content-Type': mimeType,
+			},
+		});
+	}
+}

package/template/framework/http/Server.ts

@@ -0,0 +1,161 @@
+/**
+ * PhoenixJS - HTTP Server
+ * 
+ * Wraps Bun.serve with lifecycle hooks and configuration.
+ */
+
+import { Kernel } from '@framework/core/Kernel';
+import { Application } from '@framework/core/Application';
+import { WebSocketAdapter } from '@framework/gateway/WebSocketAdapter';
+import type { WebSocketData } from '@framework/gateway/Gateway';
+
+// Use the inferred type from Bun.serve to avoid generic type issues
+type BunServer = ReturnType<typeof Bun.serve>;
+
+export interface ServerConfig {
+	port: number;
+	host: string;
+	development?: boolean;
+}
+
+export interface ServerHooks {
+	onStart?: (server: BunServer) => void;
+	onStop?: () => void;
+	onError?: (error: Error) => void;
+}
+
+export class Server {
+	private kernel: Kernel;
+	private app: Application;
+	private config: ServerConfig;
+	private hooks: ServerHooks;
+	private server: BunServer | null = null;
+	private wsAdapter: WebSocketAdapter;
+
+	constructor(kernel: Kernel, config?: Partial<ServerConfig>, hooks?: ServerHooks) {
+		this.kernel = kernel;
+		this.app = kernel.getApplication();
+		this.config = {
+			port: config?.port ?? this.app.getConfig('port'),
+			host: config?.host ?? this.app.getConfig('host'),
+			development: config?.development ?? this.app.getConfig('env') === 'development',
+		};
+		this.hooks = hooks ?? {};
+		this.wsAdapter = new WebSocketAdapter();
+	}
+
+	/**
+	 * Start the server
+	 */
+	start(): BunServer {
+		const kernel = this.kernel;
+		const hooks = this.hooks;
+		const wsAdapter = this.wsAdapter;
+
+		// Initialize WebSocket gateways
+		const gatewayManager = this.app.getGatewayManager();
+		gatewayManager.registerAdapter(wsAdapter);
+		wsAdapter.start(gatewayManager.getByTransport('websocket'));
+
+		this.server = Bun.serve<WebSocketData>({
+			port: this.config.port,
+			hostname: this.config.host,
+			development: this.config.development,
+
+			fetch: async (request: Request, server: BunServer): Promise<Response | undefined> => {
+				// Check for WebSocket upgrade
+				const url = new URL(request.url);
+				if (wsAdapter.hasGatewayForPath(url.pathname)) {
+					const upgraded = wsAdapter.handleUpgrade(request, server);
+					if (upgraded) {
+						return undefined;
+					}
+					return new Response('WebSocket upgrade failed', { status: 400 });
+				}
+
+				return kernel.handle(request);
+			},
+
+			websocket: wsAdapter.getWebSocketConfig(),
+
+			error: (error: Error): Response => {
+				if (hooks.onError) {
+					hooks.onError(error);
+				}
+				console.error('[Server Error]', error);
+				return new Response('Internal Server Error', { status: 500 });
+			},
+		});
+
+		wsAdapter.setServer(this.server);
+
+		if (this.hooks.onStart) {
+			this.hooks.onStart(this.server);
+		}
+
+		this.logStartup();
+		return this.server;
+	}
+
+	/**
+	 * Log server startup information
+	 */
+	private logStartup(): void {
+		const appName = this.app.getConfig('name');
+		const env = this.app.environment();
+
+		console.log('');
+		console.log(`🚀 ${appName} started successfully!`);
+		console.log('');
+		console.log(`   Local:       http://${this.config.host}:${this.config.port}`);
+		console.log(`   Environment: ${env}`);
+		console.log(`   Debug:       ${this.app.isDebug() ? 'enabled' : 'disabled'}`);
+		console.log('');
+		console.log('   Press Ctrl+C to stop');
+		console.log('');
+	}
+
+	/**
+	 * Stop the server
+	 */
+	stop(): void {
+		if (this.server) {
+			this.server.stop();
+			this.server = null;
+
+			if (this.hooks.onStop) {
+				this.hooks.onStop();
+			}
+
+			console.log('Server stopped');
+		}
+	}
+
+	/**
+	 * Get the underlying Bun server
+	 */
+	getServer(): BunServer | null {
+		return this.server;
+	}
+
+	/**
+	 * Check if server is running
+	 */
+	isRunning(): boolean {
+		return this.server !== null;
+	}
+
+	/**
+	 * Get the port
+	 */
+	getPort(): number {
+		return this.config.port;
+	}
+
+	/**
+	 * Get the host
+	 */
+	getHost(): string {
+		return this.config.host;
+	}
+}