@elysiumjs/core 0.1.0

package/src/wamp.ts

@@ -0,0 +1,388 @@
+// Copyright (c) 2025-present Workbud Technologies Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { Class } from 'type-fest';
+
+import { Elysia } from 'elysia';
+import { omit } from 'radash';
+// @ts-expect-error The Wampy type definitions are not up to date
+import Wampy from 'wampy';
+
+import { Event } from './event';
+import { Service } from './service';
+import { nextTick, Symbols } from './utils';
+
+// FIXME: Temporary solution for Bun to properly fill the protocol field. Remove this once oven-sh/bun#18744 is fixed.
+class WampWebsocket extends WebSocket {
+	public constructor(
+		url: string,
+		private readonly protocols?: string | string[]
+	) {
+		super(url, protocols);
+	}
+
+	public get protocol(): string {
+		return this.protocols?.[0] ?? 'wamp.2.json';
+	}
+}
+
+/**
+ * Options used to register a WAMP RPC for invocation.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampRegistrationOptions = {
+	/**
+	 * The match policy to use for the registration.
+	 * @default 'exact'
+	 */
+	match?: 'prefix' | 'exact' | 'wildcard';
+
+	/**
+	 * The invocation policy to use for the registration.
+	 * @default 'single'
+	 */
+	invoke?: 'single' | 'first' | 'last' | 'roundrobin' | 'random';
+};
+
+/**
+ * Options used to subscribe to a WAMP topic.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampSubscriptionOptions = Omit<WampRegistrationOptions, 'invoke'>;
+
+/**
+ * Properties required when declaring a WAMP controller using the `@wamp()` decorator.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampProps = {
+	/**
+	 * The URL to the WAMP server.
+	 */
+	url: string;
+
+	/**
+	 * The name of the realm to connect to.
+	 */
+	realm: string;
+
+	/**
+	 * Whether to automatically reconnect to the WAMP server on connection loss.
+	 */
+	autoReconnect?: boolean;
+
+	/**
+	 * The maximum number of times to retry connecting to the WAMP server.
+	 */
+	maxRetries?: number;
+
+	/**
+	 * The interval to wait between retries when connecting to the WAMP server.
+	 */
+	retryInterval?: number;
+};
+
+/**
+ * Data sent to a WAMP RPC.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampRegistrationHandlerArgs = {
+	/**
+	 * The arguments passed to the RPC or subscription.
+	 */
+	argsList: any[];
+
+	/**
+	 * The keyword arguments passed to the RPC or subscription.
+	 */
+	argsDict: any;
+
+	/**
+	 * The WAMP details object.
+	 */
+	details: {
+		receive_progress?: boolean;
+		trustlevel?: number;
+	};
+
+	/**
+	 * The result handler for the RPC. Use this to send progressive results.
+	 * @param value
+	 */
+	result_handler: (value: any) => void;
+
+	/**
+	 * The error handler for the RPC when working with progressive results.
+	 * @param error The thrown error.
+	 */
+	error_handler: (error: any) => void;
+};
+
+/**
+ * Data sent to a WAMP subscription.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampSubscriptionHandlerArgs = Omit<
+	WampRegistrationHandlerArgs,
+	'result_handler' | 'error_handler'
+>;
+
+/**
+ * The WAMP RPC handler function.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param data The data sent to the handler.
+ */
+export type WampRegistrationHandler = <T = any>(data: WampRegistrationHandlerArgs) => T;
+
+/**
+ * The WAMP subscription handler function.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param data The data sent to the handler.
+ */
+export type WampSubscriptionHandler = <T = any>(data: WampSubscriptionHandlerArgs) => T;
+
+/**
+ * Metadata for a WAMP RPC.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+type WampRegistration = {
+	/**
+	 * The topic to register the RPC for.
+	 */
+	topic: string;
+
+	/**
+	 * The registration options for the RPC.
+	 */
+	options?: WampRegistrationOptions;
+
+	/**
+	 * The RPC handler function.
+	 */
+	handler: WampRegistrationHandler;
+};
+
+/**
+ * Metadata for a WAMP subscription.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+type WampSubscription = {
+	/**
+	 * The topic to subscribe to.
+	 */
+	topic: string;
+
+	/**
+	 * The subscription options for the subscription.
+	 */
+	options?: WampSubscriptionOptions;
+
+	/**
+	 * The subscription handler function.
+	 */
+	handler: WampSubscriptionHandler;
+};
+
+export namespace Wamp {
+	/**
+	 * Marks a class as a WAMP controller.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param options The decorator options.
+	 */
+	export const controller = (options: WampProps) => {
+		return function (target: Class<any>) {
+			async function handleWamp(): Promise<Elysia> {
+				// TODO: Use the logger service here
+				console.log(`Registering Wamp route for ${options.url} using ${target.name}`);
+				await nextTick();
+
+				const controller = Service.make(target);
+
+				const metadata = Reflect.getMetadata(Symbols.wamp, target) ?? {};
+
+				const w = new Wampy(options.url, {
+					ws: WampWebsocket,
+					...omit(options, ['url']),
+					onClose: metadata.close?.bind(controller),
+					onError() {
+						metadata.error?.call(controller);
+						// TODO: Add more details like controller name and url
+						Event.emit('elysium:error', new Error('Wamp connection error'));
+					},
+					onReconnect: metadata.reconnect?.bind(controller),
+					onReconnectSuccess: metadata.reconnectSuccess?.bind(controller)
+				});
+
+				const registrations: WampRegistration[] = metadata.registrations ?? [];
+				const subscriptions: WampSubscription[] = metadata.subscriptions ?? [];
+
+				for (const registration of registrations) {
+					w.register(
+						registration.topic,
+						registration.handler.bind(controller),
+						registration.options
+					).then((r: { topic: string; requestId: string; registrationId: string }) => {
+						// TODO: Use the logger service here
+						console.log(`Registered ${registration.topic} with id ${r.registrationId}`);
+					});
+				}
+
+				for (const subscription of subscriptions) {
+					w.subscribe(
+						subscription.topic,
+						subscription.handler.bind(controller),
+						subscription.options
+					).then(
+						(s: {
+							topic: string;
+							requestId: string;
+							subscriptionId: string;
+							subscriptionKey: string;
+						}) => {
+							// TODO: Use the logger service here
+							console.log(`Subscribed ${subscription.topic} with id ${s.subscriptionId}`);
+						}
+					);
+				}
+
+				const app = new Elysia();
+
+				app.onStart(async (_) => {
+					await w.connect();
+					metadata.open?.call(controller);
+				});
+
+				return app;
+			}
+
+			Reflect.defineMetadata(Symbols.elysiaPlugin, handleWamp, target);
+		};
+	};
+
+	/**
+	 * Registers a method as a WAMP RPC.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param topic The RPC topic to register.
+	 * @param options The registration options.
+	 */
+	export const register = (topic: string, options?: WampRegistrationOptions): MethodDecorator => {
+		return function (target, _propertyKey, descriptor) {
+			const metadata = Reflect.getMetadata(Symbols.wamp, target.constructor) ?? {};
+
+			metadata.registrations ??= [];
+			metadata.registrations.push({
+				topic,
+				options,
+				handler: descriptor.value as WampRegistrationHandler
+			});
+
+			Reflect.defineMetadata(Symbols.wamp, metadata, target.constructor);
+		};
+	};
+
+	/**
+	 * Subscribes to a WAMP topic.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param topic The topic to subscribe to.
+	 * @param options The subscription options.
+	 */
+	export const subscribe = (topic: string, options?: WampSubscriptionOptions): MethodDecorator => {
+		return function (target, _propertyKey, descriptor) {
+			const metadata = Reflect.getMetadata(Symbols.wamp, target.constructor) ?? {};
+
+			metadata.subscriptions ??= [];
+			metadata.subscriptions.push({
+				topic,
+				options,
+				handler: descriptor.value as WampRegistrationHandler
+			});
+
+			Reflect.defineMetadata(Symbols.wamp, metadata, target.constructor);
+		};
+	};
+
+	/**
+	 * Marks a method as the WAMP "open" event handler.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 *
+	 * This decorator should be used on a WAMP controller method. Only one "open" event handler
+	 * can be defined per WAMP controller.
+	 */
+	export const onOpen = (): MethodDecorator => {
+		return function (target, _propertyKey, descriptor) {
+			const metadata = Reflect.getMetadata(Symbols.wamp, target.constructor) ?? {};
+			metadata.open = descriptor.value;
+			Reflect.defineMetadata(Symbols.wamp, metadata, target.constructor);
+		};
+	};
+
+	/**
+	 * Marks a method as the WAMP "close" event handler.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 *
+	 * This decorator should be used on a WAMP controller method. Only one "close" event handler
+	 * can be defined per WAMP controller.
+	 */
+	export const onClose = (): MethodDecorator => {
+		return function (target, _propertyKey, descriptor) {
+			const metadata = Reflect.getMetadata(Symbols.wamp, target.constructor) ?? {};
+			metadata.close = descriptor.value;
+			Reflect.defineMetadata(Symbols.wamp, metadata, target.constructor);
+		};
+	};
+
+	/**
+	 * Marks a method as the WAMP "error" event handler.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 *
+	 * This decorator should be used on a WAMP controller method. Only one "error" event handler
+	 * can be defined per WAMP controller.
+	 */
+	export const onError = (): MethodDecorator => {
+		return function (target, _propertyKey, descriptor) {
+			const metadata = Reflect.getMetadata(Symbols.wamp, target.constructor) ?? {};
+			metadata.error = descriptor.value;
+			Reflect.defineMetadata(Symbols.wamp, metadata, target.constructor);
+		};
+	};
+
+	/**
+	 * Marks a method as the WAMP "reconnect" event handler.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 *
+	 * This decorator should be used on a WAMP controller method. Only one "reconnect" event handler
+	 * can be defined per WAMP controller.
+	 */
+	export const onReconnect = (): MethodDecorator => {
+		return function (target, _propertyKey, descriptor) {
+			const metadata = Reflect.getMetadata(Symbols.wamp, target.constructor) ?? {};
+			metadata.reconnect = descriptor.value;
+			Reflect.defineMetadata(Symbols.wamp, metadata, target.constructor);
+		};
+	};
+
+	/**
+	 * Marks a method as the WAMP "reconnectSuccess" event handler.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 *
+	 * This decorator should be used on a WAMP controller method. Only one "reconnectSuccess" event handler
+	 * can be defined per WAMP controller.
+	 */
+	export const onReconnectSuccess = (): MethodDecorator => {
+		return function (target, _propertyKey, descriptor) {
+			const metadata = Reflect.getMetadata(Symbols.wamp, target.constructor) ?? {};
+			metadata.reconnectSuccess = descriptor.value;
+			Reflect.defineMetadata(Symbols.wamp, metadata, target.constructor);
+		};
+	};
+}

package/src/websocket.ts

@@ -0,0 +1,186 @@
+// Copyright (c) 2025-present Workbud Technologies Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { ServerWebSocket } from 'bun';
+import type { Context, ErrorContext, TSchema } from 'elysia';
+import type { Class, ConditionalPick, JsonObject, Primitive } from 'type-fest';
+import type { Route } from './http';
+
+import { Elysia } from 'elysia';
+
+import { Event } from './event';
+import { Service } from './service';
+import { nextTick, Symbols } from './utils';
+
+/**
+ * Properties required when declaring a websocket controller using the `@websocket()` decorator.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WebsocketProps = {
+	/**
+	 * The path of the websocket route.
+	 */
+	path: Route;
+
+	/**
+	 * The options for the websocket server.
+	 */
+	options?: ConditionalPick<Bun.WebSocketHandler, Primitive | JsonObject>;
+};
+
+/**
+ * The websocket connection instance.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @template TData Additional data stored in the websocket connection.
+ */
+export type WS<TData = unknown> = ServerWebSocket<
+	{
+		/**
+		 * Unique identifier for the websocket connection.
+		 */
+		id: string;
+	} & Context &
+		TData
+>;
+
+/**
+ * The data generated when an error occurs in a websocket connection.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WSError = ErrorContext & { error: Readonly<Error> };
+
+export namespace Websocket {
+	/**
+	 * Marks a class as a websocket controller.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param props The websocket route properties.
+	 */
+	export const controller = (props: WebsocketProps) => {
+		return function (target: Class<any>) {
+			async function handleWebsocket(): Promise<Elysia> {
+				// TODO: Use the logger service here
+				console.log(`Registering Websocket route for ${props.path} using ${target.name}`);
+				await nextTick();
+
+				const controller = Service.make(target);
+
+				const metadata = Reflect.getMetadata(Symbols.websocket, target) ?? {};
+				const open = metadata.open?.bind(controller);
+				const close = metadata.close?.bind(controller);
+				const message = metadata.message?.bind(controller);
+				const drain = metadata.drain?.bind(controller);
+				const error =
+					metadata.error?.bind(controller) ??
+					((e: WSError) => Event.emit('elysium:error', e.error));
+
+				const app = new Elysia();
+
+				// TODO: Add middlewares here
+				app.ws(props.path, {
+					// TODO: beforeHandle
+					// TODO: afterHandle
+					open,
+					close,
+					message,
+					drain,
+					error,
+					body: metadata.body,
+					...props.options
+				});
+
+				return app;
+			}
+
+			Reflect.defineMetadata(Symbols.elysiaPlugin, handleWebsocket, target);
+		};
+	};
+
+	/**
+	 * Marks a method as the websocket "open" event handler.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 *
+	 * This decorator should be used on a websocket controller method. Only one "open" event handler
+	 * can be defined per websocket controller.
+	 */
+	export const onOpen = (): MethodDecorator => {
+		return function (target, propertyKey, descriptor) {
+			const metadata = Reflect.getMetadata(Symbols.websocket, target.constructor) ?? {};
+			metadata.open = descriptor.value;
+			Reflect.defineMetadata(Symbols.websocket, metadata, target.constructor);
+		};
+	};
+
+	/**
+	 * Marks a method as the websocket "close" event handler.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 *
+	 * This decorator should be used on a websocket controller method. Only one "close" event handler
+	 * can be defined per websocket controller.
+	 */
+	export const onClose = (): MethodDecorator => {
+		return function (target, propertyKey, descriptor) {
+			const metadata = Reflect.getMetadata(Symbols.websocket, target.constructor) ?? {};
+			metadata.close = descriptor.value;
+			Reflect.defineMetadata(Symbols.websocket, metadata, target.constructor);
+		};
+	};
+
+	/**
+	 * Marks a method as the websocket "message" event handler.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 *
+	 * This decorator should be used on a websocket controller method. Only one "message" event handler
+	 * can be defined per websocket controller.
+	 *
+	 * @param schema The schema of the message body.
+	 */
+	export const onMessage = (schema: TSchema): MethodDecorator => {
+		return function (target, propertyKey, descriptor) {
+			const metadata = Reflect.getMetadata(Symbols.websocket, target.constructor) ?? {};
+			metadata.message = descriptor.value;
+			metadata.body = schema;
+			Reflect.defineMetadata(Symbols.websocket, metadata, target.constructor);
+		};
+	};
+
+	/**
+	 * Marks a method as the websocket "drain" event handler.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 *
+	 * This decorator should be used on a websocket controller method. Only one "drain" event handler
+	 * can be defined per websocket controller.
+	 */
+	export const onDrain = (): MethodDecorator => {
+		return function (target, propertyKey, descriptor) {
+			const metadata = Reflect.getMetadata(Symbols.websocket, target.constructor) ?? {};
+			metadata.drain = descriptor.value;
+			Reflect.defineMetadata(Symbols.websocket, metadata, target.constructor);
+		};
+	};
+
+	/**
+	 * Marks a method as the websocket "error" event handler.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 *
+	 * This decorator should be used on a websocket controller method. Only one "error" event handler
+	 * can be defined per websocket controller.
+	 */
+	export const onError = (): MethodDecorator => {
+		return function (target, propertyKey, descriptor) {
+			const metadata = Reflect.getMetadata(Symbols.websocket, target.constructor) ?? {};
+			metadata.error = descriptor.value;
+			Reflect.defineMetadata(Symbols.websocket, metadata, target.constructor);
+		};
+	};
+}