@buenojs/bueno 0.8.5 → 0.8.7

package/src/graphql/subscription-handler.ts

@@ -0,0 +1,283 @@
+/**
+ * GraphQL Subscription Handler
+ *
+ * Implements the graphql-transport-ws protocol over Bun's native WebSocket.
+ * Registered via app.setWebSocketHandler() so subscriptions run on the same
+ * port as the HTTP server — no separate port needed.
+ *
+ * Protocol spec: https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md
+ *
+ * ## Usage
+ * Automatically configured by GraphQLModule.setup() when subscriptions: true.
+ * Requires an engine with supportsSubscriptions = true (e.g. GraphQLJsAdapter).
+ */
+
+import type { GraphQLEngine, GraphQLContext, ResolvedSchema } from "./types";
+import type { Container } from "../container";
+import type { Guard, Interceptor } from "./execution-pipeline";
+import { buildGraphQLContext } from "./context-builder";
+
+// ============= Protocol Message Types =============
+
+interface ConnectionInitMessage {
+	type: "connection_init";
+	payload?: Record<string, unknown>;
+}
+interface ConnectionAckMessage {
+	type: "connection_ack";
+}
+interface SubscribeMessage {
+	type: "subscribe";
+	id: string;
+	payload: {
+		query: string;
+		variables?: Record<string, unknown>;
+		operationName?: string;
+	};
+}
+interface NextMessage {
+	type: "next";
+	id: string;
+	payload: { data?: unknown; errors?: unknown[] };
+}
+interface ErrorMessage {
+	type: "error";
+	id: string;
+	payload: Array<{ message: string }>;
+}
+interface CompleteMessage {
+	type: "complete";
+	id?: string;
+}
+
+type ServerMessage = ConnectionAckMessage | NextMessage | ErrorMessage | CompleteMessage;
+type ClientMessage = ConnectionInitMessage | SubscribeMessage | CompleteMessage;
+
+// ============= Connection State =============
+
+interface SubscriptionState {
+	generator: AsyncGenerator<unknown>;
+}
+
+interface ConnectionState {
+	subscriptions: Map<string, SubscriptionState>;
+	initialized: boolean;
+}
+
+// ============= WebSocket Data =============
+
+interface WsData {
+	connectionId: string;
+}
+
+// ============= Subscription Handler =============
+
+export class SubscriptionHandler {
+	private connections = new Map<string, ConnectionState>();
+
+	constructor(
+		private engine: GraphQLEngine,
+		private engineSchema: unknown,
+		private graphqlPath: string,
+		private container: Container,
+		private globalGuards: Guard[],
+		private globalInterceptors: Interceptor[],
+	) {}
+
+	/**
+	 * Returns a Bun WebSocketHandler to register on the server via app.setWebSocketHandler().
+	 * Attaches an __upgradeHandler so Application.listen() can delegate WebSocket upgrades.
+	 */
+	getWebSocketConfig(): Bun.WebSocketHandler<WsData> & { __upgradeHandler: (req: Request, srv: Bun.Server) => Response | undefined } {
+		const upgradeHandler = this.handleUpgrade.bind(this);
+		return {
+			__upgradeHandler: upgradeHandler,
+			open: (ws) => {
+				this.connections.set(ws.data.connectionId, {
+					subscriptions: new Map(),
+					initialized: false,
+				});
+			},
+
+			message: async (ws, raw) => {
+				try {
+					const text =
+						typeof raw === "string" ? raw : new TextDecoder().decode(raw as ArrayBuffer);
+					const msg = JSON.parse(text) as ClientMessage;
+					await this.handleMessage(ws, msg);
+				} catch (err) {
+					this.send(ws, {
+						type: "error",
+						id: "",
+						payload: [{ message: `Protocol error: ${(err as Error).message}` }],
+					});
+				}
+			},
+
+			close: (ws) => {
+				const state = this.connections.get(ws.data.connectionId);
+				if (state) {
+					// Cancel all active subscriptions
+					for (const sub of state.subscriptions.values()) {
+						sub.generator.return?.(undefined);
+					}
+					this.connections.delete(ws.data.connectionId);
+				}
+			},
+
+			error: (ws, error) => {
+				console.error("[GraphQL WS] WebSocket error:", error);
+			},
+		};
+	}
+
+	/**
+	 * Middleware-like upgrade handler.
+	 * Call this from the app's fetch function for WebSocket upgrade requests.
+	 * Returns a Response if not a GraphQL WS path, undefined if upgraded.
+	 */
+	handleUpgrade(req: Request, server: Bun.Server): Response | undefined {
+		const url = new URL(req.url);
+		if (url.pathname !== this.graphqlPath) {
+			return undefined; // Not our path — let normal routing handle it
+		}
+
+		const protocol = req.headers.get("sec-websocket-protocol") ?? "";
+		if (!protocol.includes("graphql-transport-ws")) {
+			return new Response("Unsupported WebSocket protocol", { status: 426 });
+		}
+
+		const connectionId = crypto.randomUUID();
+		const upgraded = server.upgrade<WsData>(req, {
+			headers: {
+				"Sec-WebSocket-Protocol": "graphql-transport-ws",
+			},
+			data: { connectionId },
+		});
+
+		return upgraded ? undefined : new Response("WebSocket upgrade failed", { status: 400 });
+	}
+
+	// ============= Message Handlers =============
+
+	private async handleMessage(
+		ws: Bun.ServerWebSocket<WsData>,
+		msg: ClientMessage,
+	): Promise<void> {
+		const state = this.connections.get(ws.data.connectionId);
+		if (!state) return;
+
+		switch (msg.type) {
+			case "connection_init":
+				if (state.initialized) {
+					// Already initialized — send error and close
+					ws.close(4429, "Too many initialisation requests");
+					return;
+				}
+				state.initialized = true;
+				this.send(ws, { type: "connection_ack" });
+				break;
+
+			case "subscribe":
+				if (!state.initialized) {
+					ws.close(4401, "Unauthorized: connection not initialized");
+					return;
+				}
+				if (state.subscriptions.has(msg.id)) {
+					ws.close(4409, `Subscriber for ${msg.id} already exists`);
+					return;
+				}
+				await this.handleSubscribe(ws, state, msg);
+				break;
+
+			case "complete":
+				if (msg.id) {
+					const sub = state.subscriptions.get(msg.id);
+					if (sub) {
+						sub.generator.return?.(undefined);
+						state.subscriptions.delete(msg.id);
+					}
+				}
+				break;
+		}
+	}
+
+	private async handleSubscribe(
+		ws: Bun.ServerWebSocket<WsData>,
+		state: ConnectionState,
+		msg: SubscribeMessage,
+	): Promise<void> {
+		if (!this.engine.subscribe) {
+			this.send(ws, {
+				type: "error",
+				id: msg.id,
+				payload: [
+					{
+						message:
+							"Subscriptions are not supported by the configured GraphQL engine. " +
+							"Use GraphQLJsAdapter for subscription support.",
+					},
+				],
+			});
+			return;
+		}
+
+		const context: GraphQLContext = {
+			request: new Request(`ws://localhost${this.graphqlPath}`),
+			user: undefined,
+			httpContext: null,
+		};
+
+		let generator: AsyncGenerator<unknown>;
+		try {
+			generator = await this.engine.subscribe(
+				this.engineSchema,
+				msg.payload.query,
+				msg.payload.variables ?? {},
+				context,
+				msg.payload.operationName,
+			);
+		} catch (err) {
+			this.send(ws, {
+				type: "error",
+				id: msg.id,
+				payload: [{ message: (err as Error).message }],
+			});
+			return;
+		}
+
+		state.subscriptions.set(msg.id, { generator });
+
+		// Stream results
+		(async () => {
+			try {
+				for await (const result of generator) {
+					if (!state.subscriptions.has(msg.id)) break; // Cancelled
+					this.send(ws, {
+						type: "next",
+						id: msg.id,
+						payload: result as { data?: unknown; errors?: unknown[] },
+					});
+				}
+				// Subscription completed
+				this.send(ws, { type: "complete", id: msg.id });
+				state.subscriptions.delete(msg.id);
+			} catch (err) {
+				this.send(ws, {
+					type: "error",
+					id: msg.id,
+					payload: [{ message: (err as Error).message }],
+				});
+				state.subscriptions.delete(msg.id);
+			}
+		})();
+	}
+
+	private send(ws: Bun.ServerWebSocket<WsData>, msg: ServerMessage): void {
+		try {
+			ws.send(JSON.stringify(msg));
+		} catch {
+			// Connection may have closed — ignore
+		}
+	}
+}

package/src/graphql/types.ts

@@ -0,0 +1,324 @@
+/**
+ * GraphQL Module Types
+ *
+ * Core type definitions for the Bueno GraphQL integration layer.
+ */
+
+// ============= Constructor Type =============
+
+export type Constructor<T = unknown> = new (...args: unknown[]) => T;
+
+// ============= Scalar Types =============
+
+/**
+ * Represents a GraphQL scalar type via its JS constructor.
+ * Usage: () => String, () => Number, () => Boolean, () => GraphQLID
+ */
+export type GraphQLScalar =
+	| StringConstructor
+	| NumberConstructor
+	| BooleanConstructor
+	| typeof GraphQLID
+	| typeof GraphQLInt
+	| typeof GraphQLFloat;
+
+/**
+ * A thunk that returns a type constructor or array of constructors.
+ * Used to avoid circular reference issues in type definitions.
+ *
+ * @example
+ * () => String        // GraphQL String scalar
+ * () => Number        // GraphQL Float scalar
+ * () => [User]        // [User!]! list
+ * () => User          // User object type
+ */
+export type TypeFn = () => Constructor | Constructor[] | GraphQLScalar;
+
+// ============= Scalar Sentinels =============
+
+/**
+ * Sentinel class representing GraphQL ID scalar.
+ * Usage: @Field(() => GraphQLID)
+ */
+export class GraphQLID {
+	static readonly __type = "ID";
+}
+
+/**
+ * Sentinel class representing GraphQL Int scalar.
+ * Usage: @Field(() => GraphQLInt)
+ */
+export class GraphQLInt {
+	static readonly __type = "Int";
+}
+
+/**
+ * Sentinel class representing GraphQL Float scalar.
+ * Usage: @Field(() => GraphQLFloat)
+ */
+export class GraphQLFloat {
+	static readonly __type = "Float";
+}
+
+// ============= Metadata Shapes =============
+
+/** Options for @Field decorator */
+export interface FieldDecoratorOptions {
+	/** Whether the field can be null (default: false → non-null) */
+	nullable?: boolean;
+	/** Human-readable description */
+	description?: string;
+	/** Deprecation reason */
+	deprecationReason?: string;
+	/** Default value for input types */
+	defaultValue?: unknown;
+}
+
+/** Options for @Query/@Mutation/@Subscription decorators */
+export interface FieldOptions extends FieldDecoratorOptions {
+	/** GraphQL field name override (default: method name) */
+	name?: string;
+}
+
+/** Metadata stored per @Field-decorated property */
+export interface FieldMetadata {
+	propertyKey: string;
+	typeFn: TypeFn;
+	nullable: boolean;
+	description?: string;
+	deprecationReason?: string;
+	defaultValue?: unknown;
+}
+
+/** Metadata for a single resolver method parameter */
+export interface ParamMetadata {
+	index: number;
+	kind: "args" | "argsObject" | "context";
+	/** For @Args('name') — the specific argument name */
+	argName?: string;
+	/** For @Args('name', InputType) — the input object type */
+	inputTypeFn?: TypeFn;
+}
+
+/** Metadata stored per @Query/@Mutation/@Subscription method */
+export interface ResolverFieldMetadata {
+	/** Actual method name on the class */
+	methodName: string;
+	/** GraphQL field name (defaults to methodName) */
+	fieldName: string;
+	typeFn: TypeFn;
+	kind: "query" | "mutation" | "subscription";
+	nullable: boolean;
+	description?: string;
+	deprecationReason?: string;
+	paramMetadata: ParamMetadata[];
+}
+
+/** Metadata stored per @Resolver-decorated class */
+export interface ResolverClassMetadata {
+	/** GraphQL type name (default: class name) */
+	name: string;
+}
+
+/** Metadata stored per @ObjectType / @InputType class */
+export interface TypeClassMetadata {
+	name: string;
+	kind: "object" | "input";
+	description?: string;
+}
+
+// ============= Schema Representation =============
+
+/** A single resolvable field in the built schema */
+export interface ResolvedField {
+	resolverInstance: unknown;
+	methodName: string;
+	paramMetadata: ParamMetadata[];
+	typeFn: TypeFn;
+	nullable: boolean;
+}
+
+/** Internal schema representation consumed by the built-in engine */
+export interface ResolvedSchema {
+	queryFields: Map<string, ResolvedField>;
+	mutationFields: Map<string, ResolvedField>;
+	subscriptionFields: Map<string, ResolvedField>;
+}
+
+// ============= GraphQL Context =============
+
+/** Context available inside resolver methods */
+export interface GraphQLContext {
+	/** The original HTTP Request */
+	request: Request;
+	/** Authenticated user (set by auth guards via context.set('user', ...)) */
+	user?: unknown;
+	/** Reference to the HTTP Context for advanced use */
+	httpContext: unknown;
+	/** Allow arbitrary values */
+	[key: string]: unknown;
+}
+
+// ============= Execution Results =============
+
+/** A GraphQL error entry in the response */
+export interface GraphQLError {
+	message: string;
+	locations?: Array<{ line: number; column: number }>;
+	path?: Array<string | number>;
+	extensions?: Record<string, unknown>;
+}
+
+/** The GraphQL response envelope */
+export interface GraphQLResult {
+	data?: Record<string, unknown> | null;
+	errors?: GraphQLError[];
+}
+
+// ============= Engine Interface =============
+
+/**
+ * Pluggable GraphQL execution engine.
+ * Implement this interface to use graphql-js, GraphQL Yoga, Mercurius, etc.
+ *
+ * @example
+ * ```typescript
+ * import * as graphqlJs from 'graphql';
+ * import { GraphQLJsAdapter } from '@buenojs/bueno/graphql';
+ *
+ * GraphQLModule.setup(app, {
+ *   engine: new GraphQLJsAdapter(graphqlJs),
+ *   resolvers: [UserResolver],
+ * });
+ * ```
+ */
+export interface GraphQLEngine {
+	/**
+	 * Build the internal schema representation from resolver and type metadata.
+	 * Returns an opaque schema object that is passed back to execute().
+	 */
+	buildSchema(
+		resolvers: ResolverFieldsByType,
+		types: Map<string, FieldMetadata[]>,
+		sdl: string,
+	): unknown;
+
+	/**
+	 * Execute a GraphQL query or mutation.
+	 */
+	execute(
+		schema: unknown,
+		query: string,
+		variables: Record<string, unknown>,
+		context: GraphQLContext,
+		operationName?: string,
+	): Promise<GraphQLResult>;
+
+	/**
+	 * Execute a GraphQL subscription (optional).
+	 * Returns an async generator that yields results.
+	 */
+	subscribe?(
+		schema: unknown,
+		query: string,
+		variables: Record<string, unknown>,
+		context: GraphQLContext,
+		operationName?: string,
+	): Promise<AsyncGenerator<GraphQLResult>>;
+
+	/**
+	 * Whether this engine supports introspection queries.
+	 * Used to determine if the GraphQL Playground should be enabled.
+	 */
+	readonly supportsIntrospection: boolean;
+
+	/**
+	 * Whether this engine supports subscriptions.
+	 */
+	readonly supportsSubscriptions: boolean;
+}
+
+/** Resolver fields organized by root type */
+export interface ResolverFieldsByType {
+	queries: Map<string, ResolvedField>;
+	mutations: Map<string, ResolvedField>;
+	subscriptions: Map<string, ResolvedField>;
+}
+
+// ============= Module Options =============
+
+/**
+ * Options passed to GraphQLModule.setup()
+ */
+export interface GraphQLModuleOptions {
+	/**
+	 * Resolver classes to register.
+	 * Dependencies are resolved from the DI container.
+	 */
+	resolvers: Constructor[];
+
+	/**
+	 * GraphQL engine adapter (default: built-in lightweight engine).
+	 * Use GraphQLJsAdapter for full spec compliance.
+	 */
+	engine?: GraphQLEngine;
+
+	/**
+	 * HTTP path for the GraphQL endpoint (default: '/graphql').
+	 */
+	path?: string;
+
+	/**
+	 * Enable GraphiQL playground UI at GET <path>.
+	 * Default: true when using an engine with supportsIntrospection,
+	 *          false when using the built-in engine.
+	 * Set to true to force-enable even with the built-in engine (with warning).
+	 */
+	playground?: boolean;
+
+	/**
+	 * Serve the SDL at GET <path>/schema (default: true).
+	 */
+	introspection?: boolean;
+
+	/**
+	 * Enable WebSocket subscriptions (default: false).
+	 * Requires an engine with supportsSubscriptions.
+	 */
+	subscriptions?: boolean;
+
+	/**
+	 * Sync @Field metadata to the OpenAPI property store (default: false).
+	 * Enables unified types: one class works for both GraphQL and REST/OpenAPI.
+	 * Requires @buenojs/bueno/openapi to be in scope.
+	 */
+	syncOpenAPI?: boolean;
+
+	/** Maximum query complexity score (default: 1000) */
+	complexityLimit?: number;
+
+	/** Maximum query depth (default: 10) */
+	maxDepth?: number;
+}
+
+// ============= Config Interface =============
+
+/**
+ * GraphQL configuration added to BuenoConfig.
+ */
+export interface GraphQLConfig {
+	/** Enable GraphQL support (default: false) */
+	enabled?: boolean;
+	/** HTTP path (default: '/graphql') */
+	path?: string;
+	/** Enable playground (default: auto) */
+	playground?: boolean;
+	/** Enable introspection SDL endpoint (default: true) */
+	introspection?: boolean;
+	/** Maximum query complexity (default: 1000) */
+	complexityLimit?: number;
+	/** Maximum query depth (default: 10) */
+	maxDepth?: number;
+	/** Enable subscriptions (default: false) */
+	subscriptions?: boolean;
+}

package/src/index.ts

@@ -418,6 +418,9 @@ export {
 	type ObservabilityConfig,
 } from "./observability";
 
+// GraphQL
+export type { GraphQLConfig } from "./graphql/types";
+
 // Types
 export type {
 	HTTPMethod,

package/src/modules/index.ts

@@ -356,6 +356,8 @@ export class Application {
 		new Map();
 	private moduleLoader: ModuleLoader;
 	private loadedLazyModules = new Set<Constructor>();
+	// biome-ignore lint/suspicious/noExplicitAny: WebSocket data type is user-defined
+	private websocketHandler: Bun.WebSocketHandler<any> | null = null;
 
 	constructor(moduleClass: Constructor) {
 		this.container = new Container();
@@ -385,6 +387,37 @@ export class Application {
 		return this;
 	}
 
+	/**
+	 * Get the list of global guards (live reference).
+	 * Used by the GraphQL module to run guards on resolver methods.
+	 */
+	getGlobalGuards(): Guard[] {
+		return this.globalGuards;
+	}
+
+	/**
+	 * Get the list of global interceptors (live reference).
+	 * Used by the GraphQL module to run interceptors on resolver methods.
+	 */
+	getGlobalInterceptors(): Interceptor[] {
+		return this.globalInterceptors;
+	}
+
+	/**
+	 * Register a WebSocket handler to be used when the server starts.
+	 * Called by the GraphQL module to enable subscriptions on the same port.
+	 *
+	 * @example
+	 * ```typescript
+	 * app.setWebSocketHandler(subscriptionHandler.getWebSocketConfig());
+	 * await app.listen(3000);
+	 * ```
+	 */
+	// biome-ignore lint/suspicious/noExplicitAny: WebSocket data type is user-defined
+	setWebSocketHandler(handler: Bun.WebSocketHandler<any>): void {
+		this.websocketHandler = handler;
+	}
+
 	/**
 	 * Add global pipes that apply to all parameters
 	 * Global pipes run before parameter decorator pipes
@@ -793,7 +826,21 @@ export class Application {
 		this.server = Bun.serve({
 			port,
 			hostname,
-			fetch: async (request: Request) => {
+			...(this.websocketHandler ? { websocket: this.websocketHandler } : {}),
+			fetch: async (request: Request, server: Bun.Server) => {
+				// Handle WebSocket upgrade requests for subscriptions
+				if (
+					this.websocketHandler &&
+					request.headers.get("upgrade")?.toLowerCase() === "websocket"
+				) {
+					// The GraphQL subscription handler may have registered an upgrade callback
+					const wsUpgradeHandler = (this.websocketHandler as unknown as { __upgradeHandler?: (req: Request, srv: Bun.Server) => Response | undefined }).__upgradeHandler;
+					if (wsUpgradeHandler) {
+						const response = wsUpgradeHandler(request, server);
+						if (response) return response;
+					}
+				}
+
 				// Reject new requests during shutdown
 				if (this.isShuttingDown) {
 					return new Response("Service Unavailable", { status: 503 });