@elysiumjs/core 0.3.2 → 0.4.1

package/src/wamp.ts

@@ -12,7 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import type { Class } from 'type-fest';
+import type { Class, Primitive } from 'type-fest';
+
+import { setInterval } from 'node:timers/promises';
 
 import { Elysia } from 'elysia';
 import { omit } from 'radash';
@@ -66,6 +68,18 @@ export type WampSubscriptionOptions = Omit<WampRegistrationOptions, 'invoke'>;
  * @author Axel Nana <axel.nana@workbud.com>
  */
 export type WampProps = {
+	/**
+	 * The name of the connection to use. This connection must be registered in the application properties.
+	 * @default 'default'
+	 */
+	connection?: string;
+};
+
+/**
+ * Properties required when declaring a WAMP client in the application properties.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type WampClientProps = {
 	/**
 	 * The URL to the WAMP server.
 	 */
@@ -90,22 +104,157 @@ export type WampProps = {
 	 * The interval to wait between retries when connecting to the WAMP server.
 	 */
 	retryInterval?: number;
+
+	/**
+	 * The authentication ID to use in challenges.
+	 */
+	authid?: string;
+
+	/**
+	 * An array of supported authentication methods.
+	 */
+	authmethods?: string[];
+
+	/**
+	 * Callback for handling WAMP authentication challenges.
+	 * @param method The authentication method.
+	 * @param extra Authentication metadata.
+	 */
+	onChallenge?(method: string, extra: any): string | null;
+
+	/**
+	 * Callback for handling the WAMP connection open event.
+	 */
+	onOpen?(): void;
+
+	/**
+	 * Callback for handling the WAMP connection close event.
+	 */
+	onClose?(): void;
+
+	/**
+	 * Callback for handling the WAMP connection error event.
+	 */
+	onError?(): void;
+
+	/**
+	 * Callback for handling the WAMP connection reconnect event.
+	 */
+	onReconnect?(): void;
+
+	/**
+	 * Callback for handling the WAMP connection reconnect success event.
+	 */
+	onReconnectSuccess?(): void;
+};
+
+export type WampClient = {
+	/**
+	 * Disconnects from WAMP server. Clears all queues, subscriptions and calls.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 */
+	disconnect(): Promise<void>;
+
+	subscribe(
+		topic: string,
+		handler: WampSubscriptionHandler,
+		options?: WampSubscriptionOptions
+	): Promise<{
+		topic: string;
+		requestId: string;
+		subscriptionId: string;
+		subscriptionKey: string;
+	}>;
+
+	unsubscribe(
+		subscriptionIdOrKey: string,
+		handler?: WampSubscriptionHandler
+	): Promise<{
+		topic: string;
+		requestId: string;
+	}>;
+
+	publish(
+		topic: string,
+		params?:
+			| Primitive
+			| Array<any>
+			| Record<string, Primitive | Array<any>>
+			| { argsList: Array<any>; argsDict: Record<string, any> },
+		options?: {
+			exclude?: number | number[];
+			exclude_authid?: string | string[];
+			exclude_authrole?: string | string[];
+			eligible?: number | number[];
+			eligible_authid?: string | string[];
+			eligible_authrole?: string | string[];
+			exclude_me?: boolean;
+			disclose_me?: boolean;
+			ppt_scheme?: string;
+			ppt_serializer?: string;
+			ppt_cipher?: string;
+			ppt_keyid?: string;
+		}
+	): Promise<{
+		topic: string;
+		requestId: string;
+		publicationId: string;
+	}>;
+
+	call(
+		procedure: string,
+		params?:
+			| Primitive
+			| Array<any>
+			| Record<string, Primitive | Array<any>>
+			| { argsList: Array<any>; argsDict: Record<string, any> },
+		options?: {
+			disclose_me?: boolean;
+			progress_callback?(args: { argsList: Array<any>; argsDict: Record<string, any> }): void;
+			timeout?: number;
+			ppt_scheme?: string;
+			ppt_serializer?: string;
+			ppt_cipher?: string;
+			ppt_keyid?: string;
+		}
+	): Promise<{
+		details: Record<string, any>;
+		argsList?: Array<any>;
+		argsDict?: Record<string, any>;
+	}>;
+
+	cancel(requestId: string, options?: { mode?: 'kill' | 'killnowait' | 'skip' }): true;
+
+	register(
+		topic: string,
+		handler: WampRegistrationHandler,
+		options?: WampRegistrationOptions
+	): Promise<{
+		topic: string;
+		requestId: string;
+		registrationId: string;
+	}>;
+
+	unregister(registrationId: string): Promise<{
+		topic: string;
+		requestId: string;
+	}>;
 };
 
 /**
  * Data sent to a WAMP RPC.
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export type WampRegistrationHandlerArgs = {
+export type WampRegistrationHandlerArgs<TList = any[], TDict = any> = {
 	/**
 	 * The arguments passed to the RPC or subscription.
 	 */
-	argsList: any[];
+	argsList: TList;
 
 	/**
 	 * The keyword arguments passed to the RPC or subscription.
 	 */
-	argsDict: any;
+	argsDict: TDict;
 
 	/**
 	 * The WAMP details object.
@@ -194,6 +343,127 @@ type WampSubscription = {
 };
 
 export namespace Wamp {
+	/**
+	 * Creates a service name for a WAMP connection.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param name The name of the connection.
+	 * @returns A service name for the connection.
+	 */
+	const getConnectionName = (name: string) => {
+		return `wamp.connection.${name}`;
+	};
+
+	/**
+	 * Retrieves the client for a WAMP connection.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param name The name of the connection.
+	 * @returns The Wampy client for the connection with the given name.
+	 */
+	export const getConnection = (name: string) => {
+		if (!Service.exists(getConnectionName(name))) {
+			// TODO: Use logger service here
+			console.error(
+				`No WAMP connection with name ${name} found. Please make sure to register the connection before using it.`
+			);
+			process.exit(1);
+		}
+
+		return Service.get<WampClient>(getConnectionName(name))!;
+	};
+
+	/**
+	 * Creates and registers a new WAMP client.
+	 *
+	 * This will make the registered connection available for dependency injection with
+	 * the key `wamp.connection.{name}`, where `{name}` is replaced with the given name.
+	 *
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 *
+	 * @param name The name of the connection.
+	 * @param config The configuration for the WAMP client.
+	 * @returns The newly created and configured WAMP client for the given connection.
+	 */
+	export const registerConnection = (name: string, config: WampClientProps) => {
+		if (Service.exists(getConnectionName(name))) {
+			// TODO: Use logger service here
+			console.error(
+				`A WAMP connection with name ${name} already exists. Please ensure to register a new connection before overwriting it.`
+			);
+			process.exit(1);
+		}
+
+		const client = new Wampy(config.url, {
+			ws: WampWebsocket,
+			...omit(config, ['url']),
+			onError() {
+				config.onError?.();
+				// TODO: Add more details like controller name and url
+				Event.emit('elysium:error', new Error(`An error occurred in WAMP connection ${name}`));
+			}
+		});
+
+		const maxRetries = config.maxRetries ?? 5;
+		const retryInterval = config.retryInterval ?? 5000;
+		let retryCount = 0;
+
+		const tryConnect = async () => {
+			try {
+				await client.connect();
+			} catch (e) {
+				console.error(
+					`Failed to connect to WAMP server (attempt ${retryCount + 1}/${maxRetries}):`,
+					e
+				);
+
+				if (retryCount < maxRetries) {
+					retryCount++;
+					setTimeout(tryConnect, retryInterval);
+				} else {
+					console.error(`Max retry attempts (${maxRetries}) reached. Giving up.`);
+					Event.emit(
+						'elysium:error',
+						new Error(`Failed to establish WAMP connection ${name} after ${maxRetries} attempts`)
+					);
+				}
+			}
+		};
+
+		tryConnect();
+
+		return Service.instance<WampClient>(getConnectionName(name), client);
+	};
+
+	/**
+	 * Checks if a WAMP connection with the given name exists.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param name The name of the connection.
+	 * @returns `true` if the connection exists, `false` otherwise.
+	 */
+	export const connectionExists = (name: string) => {
+		return Service.exists(getConnectionName(name));
+	};
+
+	/**
+	 * Retrieves the default WAMP connection.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @returns The default WAMP connection.
+	 */
+	export const getDefaultConnection = () => {
+		return getConnection('default');
+	};
+
+	/**
+	 * Sets the default WAMP connection.
+	 * @author Axel Nana <axel.nana@workbud.com>
+	 * @param name The name of the connection to set as default.
+	 * @returns The default WAMP connection.
+	 */
+	export const setDefaultConnection = (name: string) => {
+		const serviceName = getConnectionName('default');
+		Service.remove(serviceName);
+		return Service.instance<WampClient>(serviceName, getConnection(name));
+	};
+
 	/**
 	 * Marks a class as a WAMP controller.
 	 * @author Axel Nana <axel.nana@workbud.com>
@@ -203,66 +473,50 @@ export namespace Wamp {
 		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}`);
+				console.log(
+					`Registering Wamp controller for connection ${options.connection} 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 w = Wamp.getConnection(options.connection ?? 'default');
 
 				const app = new Elysia();
 
 				app.onStart(async (_) => {
-					try {
-						await w.connect();
-						metadata.open?.call(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 }) => {
+					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(`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}`);
-								}
-							);
-						}
-					} catch (error) {
-						// noop
+								console.log(`Subscribed ${subscription.topic} with id ${s.subscriptionId}`);
+							}
+						);
 					}
 				});
 
@@ -314,79 +568,4 @@ export namespace Wamp {
 			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/tsconfig.json

@@ -0,0 +1,47 @@
+// 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.
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "allowJs": true,
+    "types": [
+      "bun-types",
+      "type-fest"
+    ],
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": false,
+    "forceConsistentCasingInFileNames": true,
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noPropertyAccessFromIndexSignature": false,
+  },
+  "exclude": [
+    "node_modules",
+    "dist",
+  ],
+}