create-phoenixjs 0.1.0

package/template/framework/gateway/GatewayManager.ts

@@ -0,0 +1,150 @@
+/**
+ * PhoenixJS - GatewayManager
+ * 
+ * Manages gateway registration, transport adapters, and lifecycle.
+ */
+
+import type { Application } from '@framework/core/Application';
+import type { Gateway, GatewayTransport, TransportAdapter } from './Gateway';
+
+export class GatewayManager {
+	private app: Application;
+	private gateways: Map<string, Gateway> = new Map();
+	private adapters: Map<GatewayTransport, TransportAdapter> = new Map();
+	private booted = false;
+
+	constructor(app: Application) {
+		this.app = app;
+	}
+
+	/**
+	 * Register a gateway
+	 */
+	register(gateway: Gateway): this {
+		if (this.gateways.has(gateway.name)) {
+			throw new Error(`Gateway "${gateway.name}" is already registered`);
+		}
+
+		this.gateways.set(gateway.name, gateway);
+		gateway.register(this.app);
+
+		// If already booted, boot the gateway immediately
+		if (this.booted && gateway.boot) {
+			gateway.boot(this.app);
+		}
+
+		return this;
+	}
+
+	/**
+	 * Register a transport adapter
+	 */
+	registerAdapter(adapter: TransportAdapter): this {
+		if (this.adapters.has(adapter.transport)) {
+			throw new Error(`Transport adapter for "${adapter.transport}" is already registered`);
+		}
+
+		this.adapters.set(adapter.transport, adapter);
+		return this;
+	}
+
+	/**
+	 * Get a gateway by name
+	 */
+	get(name: string): Gateway | undefined {
+		return this.gateways.get(name);
+	}
+
+	/**
+	 * Get a transport adapter
+	 */
+	getAdapter(transport: GatewayTransport): TransportAdapter | undefined {
+		return this.adapters.get(transport);
+	}
+
+	/**
+	 * Check if a gateway exists
+	 */
+	has(name: string): boolean {
+		return this.gateways.has(name);
+	}
+
+	/**
+	 * Get all registered gateways
+	 */
+	all(): Gateway[] {
+		return Array.from(this.gateways.values());
+	}
+
+	/**
+	 * Get gateways by transport type
+	 */
+	getByTransport(transport: GatewayTransport): Gateway[] {
+		return this.all().filter(g => g.transport === transport);
+	}
+
+	/**
+	 * Find a gateway by path
+	 */
+	findByPath(path: string): Gateway | undefined {
+		return this.all().find(g => g.path === path);
+	}
+
+	/**
+	 * Boot all gateways
+	 */
+	boot(): void {
+		if (this.booted) {
+			return;
+		}
+
+		for (const gateway of this.gateways.values()) {
+			if (gateway.boot) {
+				gateway.boot(this.app);
+			}
+		}
+
+		this.booted = true;
+	}
+
+	/**
+	 * Start all transport adapters
+	 */
+	start(): void {
+		// Group gateways by transport
+		const transports = new Set(this.all().map(g => g.transport));
+
+		for (const transport of transports) {
+			const adapter = this.adapters.get(transport);
+			if (adapter) {
+				const gateways = this.getByTransport(transport);
+				adapter.start(gateways);
+			}
+		}
+	}
+
+	/**
+	 * Stop all transport adapters
+	 */
+	stop(): void {
+		for (const adapter of this.adapters.values()) {
+			if (adapter.isRunning()) {
+				adapter.stop();
+			}
+		}
+	}
+
+	/**
+	 * Check if manager is booted
+	 */
+	isBooted(): boolean {
+		return this.booted;
+	}
+
+	/**
+	 * Get gateway count
+	 */
+	count(): number {
+		return this.gateways.size;
+	}
+}

package/template/framework/gateway/WebSocketAdapter.ts

@@ -0,0 +1,159 @@
+/**
+ * PhoenixJS - WebSocketAdapter
+ * 
+ * Built-in transport adapter for Bun's native WebSocket support.
+ */
+
+import type { ServerWebSocket } from 'bun';
+import type {
+	Gateway,
+	TransportAdapter,
+	WebSocketGatewayInterface,
+	WebSocketData,
+	GatewayOptions
+} from './Gateway';
+
+// Type for Bun server
+type BunServer = ReturnType<typeof Bun.serve>;
+
+export class WebSocketAdapter implements TransportAdapter {
+	readonly name = 'websocket';
+	readonly transport = 'websocket' as const;
+
+	private gateways: WebSocketGatewayInterface[] = [];
+	private server: BunServer | null = null;
+	private options: GatewayOptions;
+
+	constructor(options: GatewayOptions = {}) {
+		this.options = {
+			idleTimeout: options.idleTimeout ?? 120,
+			maxPayloadLength: options.maxPayloadLength ?? 1024 * 1024, // 1MB
+			perMessageDeflate: options.perMessageDeflate ?? false,
+		};
+	}
+
+	/**
+	 * Start the WebSocket adapter
+	 */
+	start(gateways: Gateway[]): void {
+		this.gateways = gateways.filter(
+			(g): g is WebSocketGatewayInterface => g.transport === 'websocket'
+		);
+	}
+
+	/**
+	 * Stop the WebSocket adapter
+	 */
+	stop(): void {
+		this.gateways = [];
+		this.server = null;
+	}
+
+	/**
+	 * Check if adapter is running
+	 */
+	isRunning(): boolean {
+		return this.server !== null;
+	}
+
+	/**
+	 * Set the server reference
+	 */
+	setServer(server: BunServer): void {
+		this.server = server;
+	}
+
+	/**
+	 * Get the Bun websocket handlers configuration
+	 */
+	getWebSocketConfig() {
+		const self = this;
+
+		return {
+			idleTimeout: this.options.idleTimeout,
+			maxPayloadLength: this.options.maxPayloadLength,
+			perMessageDeflate: this.options.perMessageDeflate,
+
+			open(ws: ServerWebSocket<WebSocketData>) {
+				const gateway = self.findGateway(ws.data.gateway);
+				if (gateway?.onOpen) {
+					gateway.onOpen(ws);
+				}
+			},
+
+			message(ws: ServerWebSocket<WebSocketData>, message: string | Buffer) {
+				const gateway = self.findGateway(ws.data.gateway);
+				if (gateway?.onMessage) {
+					gateway.onMessage(ws, message);
+				}
+			},
+
+			close(ws: ServerWebSocket<WebSocketData>, code: number, reason: string) {
+				const gateway = self.findGateway(ws.data.gateway);
+				if (gateway?.onClose) {
+					gateway.onClose(ws, code, reason);
+				}
+			},
+
+			drain(ws: ServerWebSocket<WebSocketData>) {
+				const gateway = self.findGateway(ws.data.gateway);
+				if (gateway?.onDrain) {
+					gateway.onDrain(ws);
+				}
+			},
+		};
+	}
+
+	/**
+	 * Handle WebSocket upgrade request
+	 */
+	handleUpgrade(
+		request: Request,
+		server: BunServer,
+		customData?: Record<string, unknown>
+	): boolean {
+		const url = new URL(request.url);
+		const gateway = this.findGatewayByPath(url.pathname);
+
+		if (!gateway) {
+			return false;
+		}
+
+		const data: WebSocketData = {
+			gateway: gateway.name,
+			connectionId: crypto.randomUUID(),
+			connectedAt: Date.now(),
+			...customData,
+		};
+
+		return server.upgrade(request, { data });
+	}
+
+	/**
+	 * Find a gateway by name
+	 */
+	findGateway(name: string): WebSocketGatewayInterface | undefined {
+		return this.gateways.find(g => g.name === name);
+	}
+
+	/**
+	 * Find a gateway by path
+	 */
+	findGatewayByPath(path: string): WebSocketGatewayInterface | undefined {
+		return this.gateways.find(g => g.path === path);
+	}
+
+	/**
+	 * Get all registered gateways
+	 */
+	getGateways(): WebSocketGatewayInterface[] {
+		return this.gateways;
+	}
+
+	/**
+	 * Check if a path has a registered gateway
+	 */
+	hasGatewayForPath(path: string): boolean {
+		return this.findGatewayByPath(path) !== undefined;
+	}
+}

package/template/framework/gateway/WebSocketGateway.ts

@@ -0,0 +1,182 @@
+/**
+ * PhoenixJS - WebSocketGateway
+ * 
+ * Abstract base class for WebSocket gateways with pub/sub support.
+ */
+
+import type { ServerWebSocket } from 'bun';
+import type { Application } from '@framework/core/Application';
+import type { WebSocketGatewayInterface, WebSocketData, GatewayOptions } from './Gateway';
+
+export abstract class WebSocketGateway implements WebSocketGatewayInterface {
+	readonly transport = 'websocket' as const;
+
+	/** Gateway name - must be unique */
+	abstract readonly name: string;
+
+	/** Gateway path (e.g., '/ws', '/chat') */
+	abstract readonly path: string;
+
+	/** Application instance */
+	protected app!: Application;
+
+	/** Active connections */
+	protected connections: Map<string, ServerWebSocket<WebSocketData>> = new Map();
+
+	/** Gateway options */
+	protected options: GatewayOptions = {};
+
+	/**
+	 * Called when gateway is registered
+	 */
+	register(app: Application): void {
+		this.app = app;
+		this.onRegister();
+	}
+
+	/**
+	 * Called after all gateways are registered
+	 */
+	boot(app: Application): void {
+		this.onBoot();
+	}
+
+	/**
+	 * Override to perform actions during registration
+	 */
+	protected onRegister(): void { }
+
+	/**
+	 * Override to perform actions during boot
+	 */
+	protected onBoot(): void { }
+
+	/**
+	 * Called when a connection is opened
+	 */
+	onOpen(ws: ServerWebSocket<WebSocketData>): void {
+		this.connections.set(ws.data.connectionId, ws);
+	}
+
+	/**
+	 * Called when a message is received - override in subclass
+	 */
+	onMessage(ws: ServerWebSocket<WebSocketData>, message: string | Buffer): void {
+		// Override in subclass
+	}
+
+	/**
+	 * Called when a connection is closed
+	 */
+	onClose(ws: ServerWebSocket<WebSocketData>, code: number, reason: string): void {
+		this.connections.delete(ws.data.connectionId);
+	}
+
+	/**
+	 * Called when an error occurs
+	 */
+	onError(ws: ServerWebSocket<WebSocketData>, error: Error): void {
+		console.error(`[${this.name}] WebSocket error:`, error);
+	}
+
+	/**
+	 * Called when the socket is ready to receive more data
+	 */
+	onDrain(ws: ServerWebSocket<WebSocketData>): void {
+		// Override if needed
+	}
+
+	/**
+	 * Send a message to a specific connection
+	 */
+	protected send(ws: ServerWebSocket<WebSocketData>, data: string | Uint8Array): number {
+		return ws.send(data as string);
+	}
+
+	/**
+	 * Send JSON data to a connection
+	 */
+	protected sendJson(ws: ServerWebSocket<WebSocketData>, data: unknown): number {
+		return ws.send(JSON.stringify(data));
+	}
+
+	/**
+	 * Subscribe a connection to a topic
+	 */
+	protected subscribe(ws: ServerWebSocket<WebSocketData>, topic: string): void {
+		ws.subscribe(topic);
+	}
+
+	/**
+	 * Unsubscribe a connection from a topic
+	 */
+	protected unsubscribe(ws: ServerWebSocket<WebSocketData>, topic: string): void {
+		ws.unsubscribe(topic);
+	}
+
+	/**
+	 * Publish a message to a topic
+	 */
+	protected publish(topic: string, data: string | Uint8Array, compress?: boolean): void {
+		for (const ws of this.connections.values()) {
+			ws.publish(topic, data as string, compress);
+			return; // Only need to publish once
+		}
+	}
+
+	/**
+	 * Broadcast a message to all connected clients
+	 */
+	protected broadcast(data: string | Uint8Array, exclude?: ServerWebSocket<WebSocketData>): void {
+		for (const ws of this.connections.values()) {
+			if (ws !== exclude) {
+				ws.send(data as string);
+			}
+		}
+	}
+
+	/**
+	 * Broadcast JSON data to all connected clients
+	 */
+	protected broadcastJson(data: unknown, exclude?: ServerWebSocket<WebSocketData>): void {
+		this.broadcast(JSON.stringify(data), exclude);
+	}
+
+	/**
+	 * Get all active connections
+	 */
+	protected getConnections(): ServerWebSocket<WebSocketData>[] {
+		return Array.from(this.connections.values());
+	}
+
+	/**
+	 * Get connection count
+	 */
+	protected getConnectionCount(): number {
+		return this.connections.size;
+	}
+
+	/**
+	 * Get a connection by ID
+	 */
+	protected getConnection(connectionId: string): ServerWebSocket<WebSocketData> | undefined {
+		return this.connections.get(connectionId);
+	}
+
+	/**
+	 * Close a connection
+	 */
+	protected closeConnection(ws: ServerWebSocket<WebSocketData>, code?: number, reason?: string): void {
+		ws.close(code, reason);
+	}
+
+	/**
+	 * Close all connections
+	 */
+	protected closeAll(code?: number, reason?: string): void {
+		for (const ws of this.connections.values()) {
+			ws.close(code, reason);
+		}
+		this.connections.clear();
+	}
+}