@hexabot-ai/api 3.0.0-alpha.3

package/src/websocket/adapters/redis-io.adapter.ts

@@ -0,0 +1,43 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { IoAdapter } from '@nestjs/platform-socket.io';
+import { createAdapter } from '@socket.io/redis-adapter';
+import { createClient, RedisClientOptions } from 'redis';
+import { ServerOptions } from 'socket.io';
+
+import { config } from '@/config';
+
+export class RedisIoAdapter extends IoAdapter {
+  private adapter: ReturnType<typeof createAdapter>;
+
+  async connectToRedis(): Promise<void> {
+    // @todo : add zod validation
+    const redisConfig: RedisClientOptions = {
+      socket: {
+        host: config.cache.host,
+        port: config.cache.port,
+      },
+    };
+    const pubClient = createClient(redisConfig);
+    const subClient = pubClient.duplicate();
+    pubClient.on('error', (error) => {
+      throw error;
+    });
+    subClient.on('error', (error) => {
+      throw error;
+    });
+    await Promise.all([pubClient.connect(), subClient.connect()]);
+    this.adapter = createAdapter(pubClient, subClient);
+  }
+
+  createIOServer(port: number, options?: ServerOptions): any {
+    const server = super.createIOServer(port, options);
+    server.adapter(this.adapter);
+
+    return server;
+  }
+}

package/src/websocket/decorators/socket-method.decorator.ts

@@ -0,0 +1,105 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { SocketEventMetadataStorage } from '../storage/socket-event-metadata.storage';
+
+export const SocketGet = (path: string): MethodDecorator => {
+  return (
+    target: object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) => {
+    SocketEventMetadataStorage.addEventMetadata(target, propertyKey, {
+      socketMethod: 'get',
+      path,
+      method: descriptor.value,
+    });
+  };
+};
+
+export const SocketPost = (path: string): MethodDecorator => {
+  return (
+    target: object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) => {
+    SocketEventMetadataStorage.addEventMetadata(target, propertyKey, {
+      socketMethod: 'post',
+      path,
+      method: descriptor.value,
+    });
+  };
+};
+
+export const SocketPut = (path: string): MethodDecorator => {
+  return (
+    target: object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) => {
+    SocketEventMetadataStorage.addEventMetadata(target, propertyKey, {
+      socketMethod: 'put',
+      path,
+      method: descriptor.value,
+    });
+  };
+};
+
+export const SocketPatch = (path: string): MethodDecorator => {
+  return (
+    target: object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) => {
+    SocketEventMetadataStorage.addEventMetadata(target, propertyKey, {
+      socketMethod: 'patch',
+      path,
+      method: descriptor.value,
+    });
+  };
+};
+
+export const SocketDelete = (path: string): MethodDecorator => {
+  return (
+    target: object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) => {
+    SocketEventMetadataStorage.addEventMetadata(target, propertyKey, {
+      socketMethod: 'delete',
+      path,
+      method: descriptor.value,
+    });
+  };
+};
+
+export const SocketOptions = (path: string): MethodDecorator => {
+  return (
+    target: object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) => {
+    SocketEventMetadataStorage.addEventMetadata(target, propertyKey, {
+      socketMethod: 'options',
+      path,
+      method: descriptor.value,
+    });
+  };
+};
+
+export const SocketHead = (path: string): MethodDecorator => {
+  return (
+    target: object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) => {
+    SocketEventMetadataStorage.addEventMetadata(target, propertyKey, {
+      socketMethod: 'head',
+      path,
+      method: descriptor.value,
+    });
+  };
+};

package/src/websocket/decorators/socket-req.decorator.ts

@@ -0,0 +1,15 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+
+export const SocketReq = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext) => {
+    const client = ctx.switchToWs().getClient<any>();
+
+    return client.request; // Assuming `request` is attached to the client object
+  },
+);

package/src/websocket/decorators/socket-res.decorator.ts

@@ -0,0 +1,15 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+
+export const SocketRes = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext) => {
+    const client = ctx.switchToWs().getClient<any>();
+
+    return client.response; // Assuming `response` is attached to the client object
+  },
+);

package/src/websocket/decorators/websocket-exceptions.filter.ts

@@ -0,0 +1,29 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  Catch,
+  ArgumentsHost,
+  ExceptionFilter,
+  NotFoundException,
+} from '@nestjs/common';
+
+import { SocketResponse } from '../utils/socket-response';
+
+@Catch()
+export class WebSocketExceptionsFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToWs();
+    const client = ctx.getClient<any>();
+    const response = new SocketResponse(client);
+
+    if (exception instanceof NotFoundException) {
+      response.status(404).json({ error: 'Not Found' });
+    } else {
+      response.status(500).json({ error: 'Internal Server Error' });
+    }
+  }
+}

package/src/websocket/index.ts

@@ -0,0 +1,33 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export * from './adapters/redis-io.adapter';
+
+export * from './decorators/socket-method.decorator';
+
+export * from './decorators/socket-req.decorator';
+
+export * from './decorators/socket-res.decorator';
+
+export * from './decorators/websocket-exceptions.filter';
+
+export * from './pipes/io-message.pipe';
+
+export * from './services/socket-event-dispatcher.service';
+
+export * from './storage/socket-event-metadata.storage';
+
+export * from './types';
+
+export * from './utils/gateway-options';
+
+export * from './utils/socket-request';
+
+export * from './utils/socket-response';
+
+export * from './websocket.gateway';
+
+export * from './websocket.module';

package/src/websocket/pipes/io-message.pipe.ts

@@ -0,0 +1,73 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  ArgumentMetadata,
+  BadRequestException,
+  Injectable,
+  PipeTransform,
+} from '@nestjs/common';
+
+import { config } from '@/config';
+
+import { Room } from '../types';
+
+export interface IOOutgoingMessage {
+  statusCode: number;
+  body: any;
+  headers: Record<string, string>;
+}
+
+export interface IOIncomingMessage {
+  method: string;
+  headers: Record<string, string>;
+  data: Record<string, any>;
+  params: Record<string, any>;
+  url: string;
+}
+
+export interface IOOutgoingSubscribeMessage {
+  success: boolean;
+  subscribe: Room;
+}
+
+@Injectable()
+export class IOMessagePipe implements PipeTransform<string, IOIncomingMessage> {
+  transform(value: string, _metadata: ArgumentMetadata): IOIncomingMessage {
+    let message: IOIncomingMessage;
+    try {
+      // TODO: Investigate why it arrives parsed
+      message =
+        typeof value === 'string'
+          ? JSON.parse(value)
+          : (value as any as IOIncomingMessage);
+    } catch (_error) {
+      throw new BadRequestException('Invalid JSON format');
+    }
+
+    if (!message.method || !message.url) {
+      throw new BadRequestException('Missing required fields: method, url');
+    }
+
+    const url = message.url.startsWith('http')
+      ? message.url
+      : `${config.apiBaseUrl}${message.url}`;
+
+    if (!URL.canParse(url)) {
+      throw new BadRequestException('Cannot parse url');
+    }
+
+    if (
+      !['get', 'post', 'put', 'delete', 'patch', 'options', 'head'].includes(
+        message.method,
+      )
+    ) {
+      throw new BadRequestException('Invalid method!');
+    }
+
+    return message;
+  }
+}

package/src/websocket/services/socket-event-dispatcher.service.ts

@@ -0,0 +1,167 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  HttpException,
+  HttpStatus,
+  Injectable,
+  OnModuleInit,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { ModulesContainer } from '@nestjs/core';
+import { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper';
+import { EventEmitter2, OnEvent } from '@nestjs/event-emitter';
+import { Mutex } from 'async-mutex';
+import { Socket } from 'socket.io';
+
+import { LoggerService } from '@/logger/logger.service';
+
+import { SocketEventMetadataStorage } from '../storage/socket-event-metadata.storage';
+import { SocketRequest } from '../utils/socket-request';
+import { SocketResponse } from '../utils/socket-response';
+
+type Handler = (req: any, res: SocketResponse) => Promise<any>;
+
+export type SocketMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | string;
+
+@Injectable()
+export class SocketEventDispatcherService implements OnModuleInit {
+  private routeHandlers: { [key: SocketMethod]: Map<string, Handler> } = {
+    get: new Map(),
+    post: new Map(),
+    put: new Map(),
+    patch: new Map(),
+    delete: new Map(),
+  };
+
+  constructor(
+    private readonly eventEmitter: EventEmitter2,
+    private readonly modulesContainer: ModulesContainer,
+    private readonly logger: LoggerService,
+  ) {}
+
+  @OnEvent('hook:websocket:connection')
+  handleConnection(client: Socket) {
+    client.data.mutex = new Mutex();
+  }
+
+  async handleEvent(
+    socketMethod: SocketMethod,
+    path: string,
+    req: SocketRequest,
+    res: SocketResponse,
+  ) {
+    // Prevent racing conditions from the same socket
+    const socketData = req.socket.data;
+    const release = await socketData.mutex.acquire();
+
+    try {
+      const handlers = this.routeHandlers[socketMethod];
+      const foundHandler = Array.from(handlers.entries()).find(([key, _]) => {
+        const urlPathname = new URL(req.url, 'http://localhost').pathname;
+        const keyUrlPathName = new URL(key, 'http://localhost').pathname;
+
+        return urlPathname === keyUrlPathName;
+      });
+
+      if (!foundHandler) {
+        return res.status(HttpStatus.NOT_FOUND).send({ message: 'Not Found' });
+      }
+
+      const [_, handler] = foundHandler;
+
+      await new Promise<Error | void>(async (resolve, reject) => {
+        req.session.reload((error) => {
+          if (error) {
+            reject(new UnauthorizedException());
+          } else {
+            resolve();
+          }
+        });
+      });
+
+      const response = await handler(req, res);
+
+      // Update session object (similar to what is done in express-session)
+      await new Promise<void>((resolve) => {
+        req.session.save((err) => {
+          if (err) {
+            this.logger.error('WS : Unable to update session!', err);
+          }
+          resolve();
+        });
+      });
+
+      return response;
+    } catch (error) {
+      this.logger.error('Error while handling Web-socket event', error);
+
+      return this.handleException(error, req, res);
+    } finally {
+      release();
+    }
+  }
+
+  onModuleInit() {
+    const allProviders = Array.from(this.modulesContainer.values())
+      .map(
+        (module) =>
+          module.providers.values() as MapIterator<InstanceWrapper<object>>,
+      )
+      .reduce(
+        (prev, curr) => prev.concat(Array.from(curr)),
+        [] as InstanceWrapper<object>[],
+      )
+      .filter((provider) => !!provider.instance)
+      .filter((provider, idx, self) => {
+        const matchIdx = self.findIndex((p) => p.name === provider.name);
+
+        return matchIdx === idx;
+      });
+
+    for (const provider of allProviders) {
+      const instance = provider.instance;
+      const events = SocketEventMetadataStorage.getMetadataFor(instance);
+      events.forEach((event) => {
+        // Error Handling
+        if (this.routeHandlers[event.socketMethod] === undefined) {
+          throw new Error(`Invalid event type: ${event.socketMethod}`);
+        }
+
+        if (this.routeHandlers[event.socketMethod].has(event.path)) {
+          throw new Error(
+            `Duplicate event: ${event.socketMethod} ${event.path}`,
+          );
+        }
+
+        // add event handler
+        this.routeHandlers[event.socketMethod].set(
+          event.path,
+          // bind the method to the instance
+          event.method.bind(instance),
+        );
+      });
+    }
+  }
+
+  private handleException(
+    error: Error,
+    { socket }: SocketRequest,
+    res: SocketResponse,
+  ) {
+    this.eventEmitter.emit('hook:websocket:error', socket, error);
+
+    if (error instanceof HttpException) {
+      // Handle known HTTP exceptions
+      return res.status(error.getStatus()).send(error.getResponse());
+    } else {
+      // Handle generic errors
+      return res
+        .status(HttpStatus.INTERNAL_SERVER_ERROR)
+        .send({ message: 'Internal Server Error' });
+    }
+  }
+}

package/src/websocket/storage/socket-event-metadata.storage.ts

@@ -0,0 +1,44 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Socket } from 'socket.io-client';
+
+import { IOIncomingMessage } from '../pipes/io-message.pipe';
+
+type SocketEventMetadata = {
+  path: string;
+  method: (payload: IOIncomingMessage, client: Socket) => Promise<any>;
+  propertyKey: string | symbol;
+  socketMethod:
+    | 'get'
+    | 'post'
+    | 'put'
+    | 'patch'
+    | 'delete'
+    | 'options'
+    | 'head';
+};
+
+export class SocketEventMetadataStorage {
+  private static metadata = new Map<string, SocketEventMetadata[]>();
+
+  static addEventMetadata(
+    target: object,
+    propertyKey: SocketEventMetadata['propertyKey'],
+    metadata: Omit<SocketEventMetadata, 'propertyKey'>,
+  ) {
+    const key = target.constructor.name;
+    if (!this.metadata.has(key)) {
+      this.metadata.set(key, []);
+    }
+
+    this.metadata.get(key)?.push({ propertyKey, ...metadata });
+  }
+
+  static getMetadataFor(target: object) {
+    return this.metadata.get(target.constructor.name) || [];
+  }
+}

package/src/websocket/types.ts

@@ -0,0 +1,15 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export enum Room {
+  MESSAGE = 'Message',
+  SUBSCRIBER = 'Subscriber',
+}
+
+export type SocketErrorResponse = {
+  statusCode: number;
+  message: string;
+};

package/src/websocket/utils/gateway-options.ts

@@ -0,0 +1,85 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import util from 'util';
+
+import type { ServerOptions } from 'socket.io';
+
+import { AppInstance } from '@/app.instance';
+import { config } from '@/config';
+import { SettingService } from '@/setting/services/setting.service';
+
+export const buildWebSocketGatewayOptions = (): Partial<ServerOptions> => {
+  const opts: Partial<ServerOptions> = {
+    allowEIO3: true, // Allows support for Engine.io v3 clients.
+    path: config.sockets.path,
+    ...(typeof config.sockets.serveClient !== 'undefined' && {
+      serveClient: config.sockets.serveClient,
+    }),
+    ...(config.sockets.beforeConnect && {
+      allowRequest: (handshake, cb) => {
+        try {
+          const result = config.sockets.beforeConnect(handshake);
+
+          return cb(null, result);
+        } catch (e) {
+          // eslint-disable-next-line no-console
+          console.log(
+            `A socket was rejected via the config.sockets.beforeConnect function.\n` +
+              `It attempted to connect with headers:\n` +
+              `${util.inspect(handshake.headers, { depth: null })}\n` +
+              `Details: ${e}`,
+          );
+
+          return cb(e, false);
+        }
+      },
+    }),
+    ...(config.sockets.pingTimeout && {
+      pingTimeout: config.sockets.pingTimeout,
+    }),
+    ...(config.sockets.pingInterval && {
+      pingInterval: config.sockets.pingInterval,
+    }),
+    ...(config.sockets.maxHttpBufferSize && {
+      maxHttpBufferSize: config.sockets.maxHttpBufferSize,
+    }),
+    ...(config.sockets.transports && { transports: config.sockets.transports }),
+    ...(config.sockets.allowUpgrades && {
+      allowUpgrades: config.sockets.allowUpgrades,
+    }),
+    ...(config.sockets.cookie && { cookie: config.sockets.cookie }),
+    cors: {
+      origin: async (origin, cb) => {
+        if (config.env === 'test') {
+          cb(null, true);
+        } else {
+          // Retrieve the allowed origins from the settings
+          const app = AppInstance.getApp();
+          const settingService = app.get<SettingService>(SettingService);
+
+          await settingService
+            .getAllowedOrigins()
+            .then((allowedOrigins) => {
+              if (origin && allowedOrigins.includes(origin)) {
+                cb(null, true);
+              } else {
+                // eslint-disable-next-line no-console
+                console.log(
+                  `A socket was rejected via the config.sockets.onlyAllowOrigins array.\n` +
+                    `It attempted to connect with origin: ${origin}`,
+                );
+                cb(new Error('Origin not allowed'), false);
+              }
+            })
+            .catch(cb);
+        }
+      },
+    },
+  };
+
+  return opts;
+};