@martel/calyx 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.6.0](https://github.com/bmartel/calyx/compare/v1.5.0...v1.6.0) (2026-07-01)
+
+
+### Features
+
+* **websockets,microservices:** implement WebSocketGateways, TCP Microservices, and context switching for Guards/Interceptors ([a8cde0d](https://github.com/bmartel/calyx/commit/a8cde0d68411a3ab736fe1df00ae04672588b1af))
+
 # [1.5.0](https://github.com/bmartel/calyx/compare/v1.4.0...v1.5.0) (2026-07-01)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martel/calyx",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "High-performance Bun-native NestJS-compatible framework",
   "main": "src/index.ts",
   "bin": {

package/src/http/application.ts

@@ -99,6 +99,9 @@ export class CalyxApplication {
   private middlewareConfigurations: MiddlewareConfiguration[] = [];
   private hostPool = new ObjectPool<CalyxArgumentsHost>(() => new CalyxArgumentsHost());
   private contextPool = new ObjectPool<CalyxExecutionContext>(() => new CalyxExecutionContext());
+  private sharedWebSockets: any[] = [];
+  private hasWebSockets = false;
+  private serverPort = 3000;
 
   use(...middlewares: any[]) {
     this.globalMiddlewares.push(...middlewares);
@@ -149,6 +152,9 @@ export class CalyxApplication {
     // Register Scheduled tasks
     this.registerScheduledTasks();
 
+    // Register WebSocket Gateways
+    this.registerWebSocketGateways();
+
     // Call OnModuleInit hooks
     await this.runOnModuleInit();
 
@@ -928,11 +934,43 @@ export class CalyxApplication {
   }
 
   async listen(port: number): Promise<any> {
+    this.serverPort = port;
     await this.init();
-    this.server = Bun.serve({
+
+    const fetchHandler = (req: Request, server: any) => {
+      if (this.hasWebSockets && req.headers.get('upgrade') === 'websocket') {
+        const success = server.upgrade(req);
+        if (success) return undefined;
+      }
+      return this.handleRequest(req);
+    };
+
+    const serveOptions: any = {
       port,
-      fetch: (req) => this.handleRequest(req),
-    });
+      fetch: fetchHandler,
+    };
+
+    if (this.hasWebSockets) {
+      serveOptions.websocket = {
+        open: (ws: any) => {
+          for (const gateway of this.sharedWebSockets) {
+            this.dispatchWsConnection(gateway, ws);
+          }
+        },
+        message: (ws: any, message: any) => {
+          for (const gateway of this.sharedWebSockets) {
+            this.dispatchWsMessage(gateway, ws, message);
+          }
+        },
+        close: (ws: any) => {
+          for (const gateway of this.sharedWebSockets) {
+            this.dispatchWsDisconnect(gateway, ws);
+          }
+        }
+      };
+    }
+
+    this.server = Bun.serve(serveOptions);
     return this.server;
   }
 
@@ -1103,5 +1141,185 @@ export class CalyxApplication {
       }
     }
   }
+
+  private registerWebSocketGateways() {
+    const instances = this.container.getProviderAndControllerInstances();
+    for (const instance of instances) {
+      if (!instance || !instance.constructor) continue;
+      const metadata = Reflect.getMetadata('calyx:websocket_gateway', instance.constructor);
+      if (!metadata) continue;
+
+      const handlers = new Map<string, { propertyKey: string | symbol; paramMapping: any[] }>();
+
+      const subMessages: { event: string; propertyKey: string | symbol }[] =
+        Reflect.getMetadata('calyx:subscribe_message', instance.constructor) || [];
+
+      const bodyParams: { propertyKey: string | symbol; parameterIndex: number }[] =
+        Reflect.getMetadata('calyx:message_body', instance.constructor) || [];
+
+      const socketParams: { propertyKey: string | symbol; parameterIndex: number }[] =
+        Reflect.getMetadata('calyx:connected_socket', instance.constructor) || [];
+
+      for (const sub of subMessages) {
+        const paramMapping: any[] = [];
+        
+        for (const bp of bodyParams) {
+          if (bp.propertyKey === sub.propertyKey) {
+            paramMapping[bp.parameterIndex] = 'body';
+          }
+        }
+        for (const sp of socketParams) {
+          if (sp.propertyKey === sub.propertyKey) {
+            paramMapping[sp.parameterIndex] = 'socket';
+          }
+        }
+
+        const classGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, instance.constructor) || [];
+        const methodGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, instance.constructor.prototype, sub.propertyKey) || [];
+        const guards = this.compileLifecycleItems(this.rootModule, [...this.globalGuards, ...classGuards, ...methodGuards]);
+
+        const classInterceptors = Reflect.getMetadata(METADATA_KEYS.INTERCEPTORS, instance.constructor) || [];
+        const methodInterceptors = Reflect.getMetadata(METADATA_KEYS.INTERCEPTORS, instance.constructor.prototype, sub.propertyKey) || [];
+        const interceptors = this.compileLifecycleItems(this.rootModule, [...this.globalInterceptors, ...classInterceptors, ...methodInterceptors]);
+
+        handlers.set(sub.event, {
+          propertyKey: sub.propertyKey,
+          paramMapping,
+          guards,
+          interceptors,
+          gatewayClass: instance.constructor,
+        });
+      }
+
+      const gatewayInfo = {
+        instance,
+        metadata,
+        handlers,
+      };
+
+      if (metadata.port && metadata.port !== this.serverPort) {
+        this.startDedicatedWebSocketServer(gatewayInfo);
+      } else {
+        this.sharedWebSockets.push(gatewayInfo);
+        this.hasWebSockets = true;
+      }
+    }
+  }
+
+  private startDedicatedWebSocketServer(gateway: any) {
+    const port = gateway.metadata.port;
+    const self = this;
+    const wsServer = Bun.serve({
+      port,
+      fetch(req, server) {
+        if (server.upgrade(req)) {
+          return undefined;
+        }
+        return new Response('Expected upgrade to websocket', { status: 400 });
+      },
+      websocket: {
+        open: (ws: any) => {
+          self.dispatchWsConnection(gateway, ws);
+        },
+        message: (ws: any, message: any) => {
+          self.dispatchWsMessage(gateway, ws, message);
+        },
+        close: (ws: any) => {
+          self.dispatchWsDisconnect(gateway, ws);
+        }
+      }
+    });
+
+    this.cleanupListeners.push(() => wsServer.stop());
+
+    if (typeof gateway.instance.afterInit === 'function') {
+      gateway.instance.afterInit(wsServer);
+    }
+  }
+
+  private dispatchWsConnection(gateway: any, ws: any) {
+    if (typeof gateway.instance.handleConnection === 'function') {
+      gateway.instance.handleConnection(ws);
+    }
+  }
+
+  private dispatchWsDisconnect(gateway: any, ws: any) {
+    if (typeof gateway.instance.handleDisconnect === 'function') {
+      gateway.instance.handleDisconnect(ws);
+    }
+  }
+
+  private async dispatchWsMessage(gateway: any, ws: any, message: any) {
+    let messageStr = '';
+    if (typeof message === 'string') {
+      messageStr = message;
+    } else if (message instanceof Uint8Array || message instanceof ArrayBuffer) {
+      messageStr = new TextDecoder().decode(message);
+    } else {
+      return;
+    }
+
+    try {
+      const parsed = JSON.parse(messageStr);
+      const event = parsed.event;
+      const data = parsed.data;
+
+      const handlerInfo = gateway.handlers.get(event);
+      if (handlerInfo) {
+        const args: any[] = [];
+        for (let i = 0; i < handlerInfo.paramMapping.length; i++) {
+          const type = handlerInfo.paramMapping[i];
+          if (type === 'body') {
+            args[i] = data;
+          } else if (type === 'socket') {
+            args[i] = ws;
+          }
+        }
+
+        const context = this.contextPool.acquire();
+        context.resetContextWs(ws, data, handlerInfo.gatewayClass, gateway.instance[handlerInfo.propertyKey]);
+
+        try {
+          for (const guard of handlerInfo.guards) {
+            const canActive = await guard.instance.canActivate(context);
+            if (!canActive) {
+              return; // Block event
+            }
+          }
+
+          const nextCall = {
+            handle: async () => {
+              return gateway.instance[handlerInfo.propertyKey](...args);
+            }
+          };
+
+          let chain = nextCall.handle;
+          for (let i = handlerInfo.interceptors.length - 1; i >= 0; i--) {
+            const interceptor = handlerInfo.interceptors[i];
+            const currentChain = chain;
+            chain = async () => {
+              return interceptor.instance.intercept(context, {
+                handle: () => currentChain()
+              });
+            };
+          }
+
+          const result = await chain();
+
+          if (result !== undefined) {
+            ws.send(JSON.stringify(result));
+          }
+        } catch (err: any) {
+          // ignore or log
+        } finally {
+          context.clearContext();
+          this.contextPool.release(context);
+        }
+      }
+    } catch {
+      // ignore non-json
+    }
+  }
 }
 
+

package/src/http/factory.ts

@@ -1,8 +1,15 @@
 import { CalyxApplication } from './application.ts';
+import { CalyxMicroservice } from '../microservices/microservice.ts';
+import { MicroserviceOptions } from '../microservices/interfaces.ts';
 
 export class CalyxFactory {
   static async create(rootModule: any): Promise<CalyxApplication> {
     const app = new CalyxApplication(rootModule);
     return app;
   }
+
+  static async createMicroservice(rootModule: any, options?: MicroserviceOptions): Promise<CalyxMicroservice> {
+    const app = new CalyxMicroservice(rootModule, options);
+    return app;
+  }
 }

package/src/index.ts

@@ -6,3 +6,5 @@ export * from './config/index.ts';
 export * from './event-emitter/index.ts';
 export * from './security/index.ts';
 export * from './schedule/index.ts';
+export * from './websockets/index.ts';
+export * from './microservices/index.ts';

package/src/lifecycle/context.ts

@@ -4,6 +4,10 @@ import { Type } from '../core/metadata.ts';
 export class CalyxArgumentsHost implements ArgumentsHost {
   protected req!: Request;
   protected res!: any;
+  protected type: 'http' | 'ws' | 'rpc' = 'http';
+  protected wsClient: any = null;
+  protected rpcContext: any = null;
+  protected data: any = null;
 
   constructor(req?: Request, res?: any) {
     if (req && res) {
@@ -12,16 +16,47 @@ export class CalyxArgumentsHost implements ArgumentsHost {
   }
 
   reset(req: Request, res: any) {
+    this.type = 'http';
     this.req = req;
     this.res = res;
+    this.wsClient = null;
+    this.rpcContext = null;
+    this.data = null;
+  }
+
+  resetWs(client: any, data: any) {
+    this.type = 'ws';
+    this.wsClient = client;
+    this.data = data;
+    this.req = null as any;
+    this.res = null;
+    this.rpcContext = null;
+  }
+
+  resetRpc(ctx: any, data: any) {
+    this.type = 'rpc';
+    this.rpcContext = ctx;
+    this.data = data;
+    this.req = null as any;
+    this.res = null;
+    this.wsClient = null;
   }
 
   clear() {
     this.req = null as any;
     this.res = null;
+    this.wsClient = null;
+    this.rpcContext = null;
+    this.data = null;
   }
 
   getArgs<T extends any[] = any[]>(): T {
+    if (this.type === 'ws') {
+      return [this.wsClient, this.data] as unknown as T;
+    }
+    if (this.type === 'rpc') {
+      return [this.data, this.rpcContext] as unknown as T;
+    }
     return [this.req, this.res] as unknown as T;
   }
 
@@ -36,6 +71,24 @@ export class CalyxArgumentsHost implements ArgumentsHost {
       getNext: <T = any>() => (() => {}) as unknown as T,
     };
   }
+
+  switchToWs(): any {
+    return {
+      getClient: <T = any>() => this.wsClient as T,
+      getData: <T = any>() => this.data as T,
+    };
+  }
+
+  switchToRpc(): any {
+    return {
+      getContext: <T = any>() => this.rpcContext as T,
+      getData: <T = any>() => this.data as T,
+    };
+  }
+
+  getType<TContextType extends string = string>(): TContextType {
+    return this.type as TContextType;
+  }
 }
 
 export class CalyxExecutionContext extends CalyxArgumentsHost implements ExecutionContext {
@@ -65,6 +118,28 @@ export class CalyxExecutionContext extends CalyxArgumentsHost implements Executi
     this.handlerMethod = handlerMethod;
   }
 
+  resetContextWs(
+    client: any,
+    data: any,
+    targetClass: Type<any>,
+    handlerMethod: Function
+  ) {
+    this.resetWs(client, data);
+    this.targetClass = targetClass;
+    this.handlerMethod = handlerMethod;
+  }
+
+  resetContextRpc(
+    ctx: any,
+    data: any,
+    targetClass: Type<any>,
+    handlerMethod: Function
+  ) {
+    this.resetRpc(ctx, data);
+    this.targetClass = targetClass;
+    this.handlerMethod = handlerMethod;
+  }
+
   clearContext() {
     this.clear();
     this.targetClass = null as any;

package/src/lifecycle/interfaces.ts

@@ -4,6 +4,9 @@ export interface ArgumentsHost {
   getArgs<T extends any[] = any[]>(): T;
   getArgByIndex<T = any>(index: number): T;
   switchToHttp(): HttpArgumentsHost;
+  switchToWs(): any;
+  switchToRpc(): any;
+  getType<TContextType extends string = string>(): TContextType;
 }
 
 export interface HttpArgumentsHost {

package/src/microservices/client-proxy.ts

@@ -0,0 +1,7 @@
+import { Observable } from 'rxjs';
+
+export abstract class ClientProxy {
+  abstract send<TResult = any, TInput = any>(pattern: any, data: TInput): Observable<TResult>;
+  abstract emit<TResult = any, TInput = any>(pattern: any, data: TInput): Observable<TResult>;
+  abstract close(): void;
+}

package/src/microservices/client-tcp.ts

@@ -0,0 +1,127 @@
+import { ClientProxy } from './client-proxy.ts';
+import { Observable } from 'rxjs';
+
+export class ClientTcp extends ClientProxy {
+  private socket: any;
+  private readonly host: string;
+  private readonly port: number;
+  private messageId = 0;
+  private pendingRequests = new Map<string, { next: (val: any) => void; error: (err: any) => void; complete: () => void }>();
+  private socketPromise: Promise<any> | null = null;
+  private buffer = '';
+
+  constructor(options: { host?: string; port?: number }) {
+    super();
+    this.host = options.host ?? '127.0.0.1';
+    this.port = options.port ?? 3000;
+  }
+
+  private async getSocket(): Promise<any> {
+    if (this.socket) return this.socket;
+    if (this.socketPromise) return this.socketPromise;
+
+    this.socketPromise = (async () => {
+      const self = this;
+      const socket = await Bun.connect({
+        hostname: this.host,
+        port: this.port,
+        socket: {
+          data(socket, data) {
+            self.handleData(data);
+          },
+          error(socket, error) {
+            self.handleError(error);
+          },
+          close(socket) {
+            self.socket = null;
+            self.socketPromise = null;
+          }
+        }
+      });
+      this.socket = socket;
+      return socket;
+    })();
+
+    return this.socketPromise;
+  }
+
+  private handleData(data: Uint8Array) {
+    this.buffer += new TextDecoder().decode(data);
+    let boundary = this.buffer.indexOf('\n');
+    while (boundary !== -1) {
+      const messageStr = this.buffer.substring(0, boundary).trim();
+      this.buffer = this.buffer.substring(boundary + 1);
+
+      if (messageStr) {
+        try {
+          const parsed = JSON.parse(messageStr);
+          const { id, response, error, isDisposed } = parsed;
+
+          const pending = this.pendingRequests.get(id);
+          if (pending) {
+            if (error) {
+              pending.error(new Error(error));
+              this.pendingRequests.delete(id);
+            } else if (isDisposed) {
+              pending.complete();
+              this.pendingRequests.delete(id);
+            } else {
+              pending.next(response);
+            }
+          }
+        } catch (err) {
+          // ignore parsing errors for partial or malformed frames
+        }
+      }
+      boundary = this.buffer.indexOf('\n');
+    }
+  }
+
+  private handleError(error: any) {
+    for (const pending of this.pendingRequests.values()) {
+      pending.error(error);
+    }
+    this.pendingRequests.clear();
+  }
+
+  send<TResult = any, TInput = any>(pattern: any, data: TInput): Observable<TResult> {
+    return new Observable<TResult>((observer) => {
+      this.messageId++;
+      const id = String(this.messageId);
+      this.pendingRequests.set(id, observer);
+
+      this.getSocket().then((socket) => {
+        const packet = JSON.stringify({ pattern, data, id }) + '\n';
+        socket.write(packet);
+      }).catch((err) => {
+        observer.error(err);
+      });
+
+      return () => {
+        this.pendingRequests.delete(id);
+      };
+    });
+  }
+
+  emit<TResult = any, TInput = any>(pattern: any, data: TInput): Observable<TResult> {
+    return new Observable<TResult>((observer) => {
+      this.getSocket().then((socket) => {
+        const packet = JSON.stringify({ pattern, data }) + '\n';
+        socket.write(packet);
+        observer.next(undefined as any);
+        observer.complete();
+      }).catch((err) => {
+        observer.error(err);
+      });
+    });
+  }
+
+  close() {
+    if (this.socket) {
+      this.socket.end();
+      this.socket = null;
+    }
+    this.socketPromise = null;
+    this.pendingRequests.clear();
+  }
+}

package/src/microservices/decorators.ts

@@ -0,0 +1,19 @@
+import 'reflect-metadata';
+
+export function MessagePattern(pattern: any): MethodDecorator {
+  return (target, propertyKey) => {
+    const constructor = target.constructor;
+    const existing = Reflect.getOwnMetadata('calyx:message_pattern', constructor) || [];
+    existing.push({ pattern, propertyKey });
+    Reflect.defineMetadata('calyx:message_pattern', existing, constructor);
+  };
+}
+
+export function EventPattern(pattern: any): MethodDecorator {
+  return (target, propertyKey) => {
+    const constructor = target.constructor;
+    const existing = Reflect.getOwnMetadata('calyx:event_pattern', constructor) || [];
+    existing.push({ pattern, propertyKey });
+    Reflect.defineMetadata('calyx:event_pattern', existing, constructor);
+  };
+}

package/src/microservices/index.ts

@@ -0,0 +1,6 @@
+export * from './interfaces.ts';
+export * from './client-proxy.ts';
+export * from './client-tcp.ts';
+export * from './decorators.ts';
+export * from './server-tcp.ts';
+export * from './microservice.ts';

package/src/microservices/interfaces.ts

@@ -0,0 +1,11 @@
+export enum Transport {
+  TCP = 0,
+}
+
+export interface MicroserviceOptions {
+  transport?: Transport;
+  options?: {
+    host?: string;
+    port?: number;
+  };
+}

package/src/microservices/microservice.ts

@@ -0,0 +1,114 @@
+import { CalyxContainer } from '../core/container.ts';
+import { ServerTcp } from './server-tcp.ts';
+import { MicroserviceOptions, Transport } from './interfaces.ts';
+
+export class CalyxMicroservice {
+  private readonly container = new CalyxContainer();
+  private readonly server: ServerTcp;
+  private isListening = false;
+  private cleanupListeners: (() => void)[] = [];
+  private readonly globalGuards: any[] = [];
+  private readonly globalInterceptors: any[] = [];
+
+  constructor(private readonly rootModule: any, options: MicroserviceOptions = {}) {
+    const transport = options.transport ?? Transport.TCP;
+    if (transport !== Transport.TCP) {
+      throw new Error(`Calyx microservice: Transport algorithm "${transport}" not supported`);
+    }
+    this.server = new ServerTcp(options.options);
+  }
+
+  useGlobalGuards(...guards: any[]) {
+    this.globalGuards.push(...guards);
+    return this;
+  }
+
+  useGlobalInterceptors(...interceptors: any[]) {
+    this.globalInterceptors.push(...interceptors);
+    return this;
+  }
+
+  async listen(): Promise<any> {
+    if (this.isListening) return;
+
+    this.container.bootstrap(this.rootModule);
+    this.server.registerHandlers(this.container, this.globalGuards, this.globalInterceptors);
+
+    const hostInfo = await this.server.listen();
+    this.isListening = true;
+
+    await this.runOnModuleInit();
+    await this.runOnApplicationBootstrap();
+
+    return hostInfo;
+  }
+
+  async close() {
+    if (!this.isListening) return;
+
+    await this.runShutdownHooks();
+
+    for (const cleanup of this.cleanupListeners) {
+      cleanup();
+    }
+    this.cleanupListeners = [];
+
+    this.server.close();
+    this.isListening = false;
+  }
+
+  enableShutdownHooks(signals: string[] = ['SIGTERM', 'SIGINT']) {
+    const handler = async (signal: string) => {
+      await this.close();
+      process.exit(0);
+    };
+
+    for (const signal of signals) {
+      const listener = () => handler(signal);
+      process.on(signal as any, listener);
+      this.cleanupListeners.push(() => {
+        process.off(signal as any, listener);
+      });
+    }
+  }
+
+  private async runOnModuleInit() {
+    const instances = this.container.getProviderAndControllerInstances();
+    for (const instance of instances) {
+      if (instance && typeof instance.onModuleInit === 'function') {
+        await instance.onModuleInit();
+      }
+    }
+  }
+
+  private async runOnApplicationBootstrap() {
+    const instances = this.container.getProviderAndControllerInstances();
+    for (const instance of instances) {
+      if (instance && typeof instance.onApplicationBootstrap === 'function') {
+        await instance.onApplicationBootstrap();
+      }
+    }
+  }
+
+  private async runShutdownHooks() {
+    const instances = this.container.getProviderAndControllerInstances();
+    
+    for (const instance of instances) {
+      if (instance && typeof instance.onModuleDestroy === 'function') {
+        await instance.onModuleDestroy();
+      }
+    }
+
+    for (const instance of instances) {
+      if (instance && typeof instance.beforeApplicationShutdown === 'function') {
+        await instance.beforeApplicationShutdown();
+      }
+    }
+
+    for (const instance of instances) {
+      if (instance && typeof instance.onApplicationShutdown === 'function') {
+        await instance.onApplicationShutdown();
+      }
+    }
+  }
+}

package/src/microservices/server-tcp.ts

@@ -0,0 +1,210 @@
+import { CalyxContainer } from '../core/container.ts';
+import { METADATA_KEYS } from '../core/metadata.ts';
+import { CalyxExecutionContext } from '../lifecycle/context.ts';
+
+export class ServerTcp {
+  private server: any;
+  private readonly host: string;
+  private readonly port: number;
+  private readonly messageHandlers = new Map<string, {
+    instance: any;
+    propertyKey: string | symbol;
+    guards: any[];
+    interceptors: any[];
+    controllerClass: any;
+  }>();
+  private readonly eventHandlers = new Map<string, { instance: any; propertyKey: string | symbol }>();
+
+  constructor(options: { host?: string; port?: number } = {}) {
+    this.host = options.host ?? '127.0.0.1';
+    this.port = options.port ?? 3000;
+  }
+
+  registerHandlers(
+    container: CalyxContainer,
+    globalGuards: any[] = [],
+    globalInterceptors: any[] = []
+  ) {
+    const instances = container.getProviderAndControllerInstances();
+    for (const instance of instances) {
+      if (!instance || !instance.constructor) continue;
+
+      const msgPatterns: { pattern: any; propertyKey: string | symbol }[] =
+        Reflect.getMetadata('calyx:message_pattern', instance.constructor) || [];
+      for (const handler of msgPatterns) {
+        const patternStr = typeof handler.pattern === 'string' ? handler.pattern : JSON.stringify(handler.pattern);
+
+        const classGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, instance.constructor) || [];
+        const methodGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, instance.constructor.prototype, handler.propertyKey) || [];
+        const guards = this.compileLifecycleItems(container, [...globalGuards, ...classGuards, ...methodGuards]);
+
+        const classInterceptors = Reflect.getMetadata(METADATA_KEYS.INTERCEPTORS, instance.constructor) || [];
+        const methodInterceptors = Reflect.getMetadata(METADATA_KEYS.INTERCEPTORS, instance.constructor.prototype, handler.propertyKey) || [];
+        const interceptors = this.compileLifecycleItems(container, [...globalInterceptors, ...classInterceptors, ...methodInterceptors]);
+
+        this.messageHandlers.set(patternStr, {
+          instance,
+          propertyKey: handler.propertyKey,
+          guards,
+          interceptors,
+          controllerClass: instance.constructor,
+        });
+      }
+
+      const eventPatterns: { pattern: any; propertyKey: string | symbol }[] =
+        Reflect.getMetadata('calyx:event_pattern', instance.constructor) || [];
+      for (const handler of eventPatterns) {
+        const patternStr = typeof handler.pattern === 'string' ? handler.pattern : JSON.stringify(handler.pattern);
+        this.eventHandlers.set(patternStr, { instance, propertyKey: handler.propertyKey });
+      }
+    }
+  }
+
+  private compileLifecycleItems(
+    container: CalyxContainer,
+    items: any[]
+  ): any[] {
+    return items.map((item) => {
+      if (typeof item === 'function') {
+        const proto = item.prototype;
+        const hasLifecycle = proto && (proto.canActivate || proto.intercept);
+        if (hasLifecycle) {
+          try {
+            return { instance: container.resolveTokenGlobally(item) };
+          } catch {
+            return { instance: new item() };
+          }
+        }
+        return { instance: { canActivate: item, intercept: item } };
+      }
+      return { instance: item };
+    });
+  }
+
+  listen(): Promise<any> {
+    const self = this;
+    return new Promise((resolve, reject) => {
+      try {
+        this.server = Bun.listen({
+          hostname: this.host,
+          port: this.port,
+          socket: {
+            data(socket, data) {
+              self.handleSocketData(socket, data);
+            },
+            error(socket, err) {
+              console.error(`Microservice socket error:`, err);
+            }
+          }
+        });
+        resolve(this.server);
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  private handleSocketData(socket: any, data: Uint8Array) {
+    if (!socket.data) {
+      socket.data = { buffer: '' };
+    }
+
+    socket.data.buffer += new TextDecoder().decode(data);
+    let boundary = socket.data.buffer.indexOf('\n');
+    while (boundary !== -1) {
+      const messageStr = socket.data.buffer.substring(0, boundary).trim();
+      socket.data.buffer = socket.data.buffer.substring(boundary + 1);
+
+      if (messageStr) {
+        this.handleMessage(socket, messageStr);
+      }
+      boundary = socket.data.buffer.indexOf('\n');
+    }
+  }
+
+  private async handleMessage(socket: any, messageStr: string) {
+    try {
+      const parsed = JSON.parse(messageStr);
+      const { pattern, data, id } = parsed;
+      const patternStr = typeof pattern === 'string' ? pattern : JSON.stringify(pattern);
+
+      if (id !== undefined) {
+        const handler = this.messageHandlers.get(patternStr);
+        if (!handler) {
+          socket.write(JSON.stringify({ id, error: `Handler for pattern "${patternStr}" not found` }) + '\n');
+          return;
+        }
+
+        const context = new CalyxExecutionContext();
+        context.resetContextRpc(socket, data, handler.controllerClass, handler.instance[handler.propertyKey]);
+
+        try {
+          for (const guard of handler.guards) {
+            const canActive = await guard.instance.canActivate(context);
+            if (!canActive) {
+              throw new Error('Forbidden resource');
+            }
+          }
+
+          const nextCall = {
+            handle: async () => {
+              return handler.instance[handler.propertyKey](data);
+            }
+          };
+
+          let chain = nextCall.handle;
+          for (let i = handler.interceptors.length - 1; i >= 0; i--) {
+            const interceptor = handler.interceptors[i];
+            const currentChain = chain;
+            chain = async () => {
+              return interceptor.instance.intercept(context, {
+                handle: () => currentChain()
+              });
+            };
+          }
+
+          const result = await chain();
+          
+          if (result && typeof result.subscribe === 'function') {
+            result.subscribe({
+              next: (val: any) => {
+                socket.write(JSON.stringify({ id, response: val }) + '\n');
+              },
+              error: (err: any) => {
+                socket.write(JSON.stringify({ id, error: err.message }) + '\n');
+              },
+              complete: () => {
+                socket.write(JSON.stringify({ id, isDisposed: true }) + '\n');
+              }
+            });
+          } else {
+            socket.write(JSON.stringify({ id, response: result }) + '\n');
+            socket.write(JSON.stringify({ id, isDisposed: true }) + '\n');
+          }
+        } catch (err: any) {
+          socket.write(JSON.stringify({ id, error: err.message }) + '\n');
+        } finally {
+          context.clearContext();
+        }
+      } else {
+        const handler = this.eventHandlers.get(patternStr);
+        if (handler) {
+          try {
+            handler.instance[handler.propertyKey](data);
+          } catch (err) {
+            console.error(`Error executing EventPattern handler for pattern "${patternStr}":`, err);
+          }
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  close() {
+    if (this.server) {
+      this.server.stop();
+      this.server = null;
+    }
+  }
+}

package/src/websockets/decorators.ts

@@ -0,0 +1,49 @@
+import 'reflect-metadata';
+
+export interface GatewayMetadata {
+  port?: number;
+  namespace?: string;
+  cors?: any;
+}
+
+export function WebSocketGateway(portOrOptions?: number | GatewayMetadata): ClassDecorator {
+  return (target) => {
+    let metadata: GatewayMetadata = {};
+    if (typeof portOrOptions === 'number') {
+      metadata.port = portOrOptions;
+    } else if (portOrOptions) {
+      metadata = portOrOptions;
+    }
+    Reflect.defineMetadata('calyx:websocket_gateway', metadata, target);
+    Reflect.defineMetadata('calyx:injectable', true, target);
+  };
+}
+
+export function SubscribeMessage(event: string): MethodDecorator {
+  return (target, propertyKey) => {
+    const constructor = target.constructor;
+    const existing = Reflect.getOwnMetadata('calyx:subscribe_message', constructor) || [];
+    existing.push({ event, propertyKey });
+    Reflect.defineMetadata('calyx:subscribe_message', existing, constructor);
+  };
+}
+
+export function MessageBody(): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    if (!propertyKey) return;
+    const constructor = target.constructor;
+    const existing = Reflect.getOwnMetadata('calyx:message_body', constructor) || [];
+    existing.push({ propertyKey, parameterIndex });
+    Reflect.defineMetadata('calyx:message_body', existing, constructor);
+  };
+}
+
+export function ConnectedSocket(): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    if (!propertyKey) return;
+    const constructor = target.constructor;
+    const existing = Reflect.getOwnMetadata('calyx:connected_socket', constructor) || [];
+    existing.push({ propertyKey, parameterIndex });
+    Reflect.defineMetadata('calyx:connected_socket', existing, constructor);
+  };
+}

package/src/websockets/gateway.ts

@@ -0,0 +1,11 @@
+export interface OnGatewayInit {
+  afterInit(server: any): void;
+}
+
+export interface OnGatewayConnection {
+  handleConnection(client: any, ...args: any[]): void;
+}
+
+export interface OnGatewayDisconnect {
+  handleDisconnect(client: any): void;
+}

package/src/websockets/index.ts

@@ -0,0 +1,2 @@
+export * from './decorators.ts';
+export * from './gateway.ts';

package/tests/microservices.test.ts

@@ -0,0 +1,105 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { of, Observable } from 'rxjs';
+import {
+  Module,
+  Controller,
+  CalyxFactory,
+  MessagePattern,
+  EventPattern,
+  ClientTcp,
+  Transport,
+} from '../src/index.ts';
+
+let eventReceived = false;
+let eventPayload: any = null;
+
+@Controller()
+class MathController {
+  @MessagePattern('sum')
+  accumulate(data: number[]): number {
+    return (data || []).reduce((a, b) => a + b, 0);
+  }
+
+  @MessagePattern('stream')
+  streamData(data: string): Observable<string> {
+    return of(`echo1: ${data}`, `echo2: ${data}`);
+  }
+
+  @MessagePattern('error_test')
+  throwError(data: any) {
+    throw new Error('This is a simulated RPC error');
+  }
+
+  @EventPattern('log_event')
+  handleLogEvent(data: any) {
+    eventReceived = true;
+    eventPayload = data;
+  }
+}
+
+@Module({
+  controllers: [MathController],
+})
+class MicroserviceModule {}
+
+describe('TCP Microservices (ClientTcp, ServerTcp, MessagePattern, EventPattern)', () => {
+  let server: any;
+  let client: ClientTcp;
+  const PORT = 3899;
+
+  beforeAll(async () => {
+    // 1. Create and start microservice server
+    server = await CalyxFactory.createMicroservice(MicroserviceModule, {
+      transport: Transport.TCP,
+      options: { port: PORT },
+    });
+    await server.listen();
+
+    // 2. Initialize client
+    client = new ClientTcp({ port: PORT });
+  });
+
+  afterAll(async () => {
+    client.close();
+    await server.close();
+  });
+
+  test('should exchange request-response message and calculate sum', async () => {
+    const res = await client.send<number, number[]>('sum', [1, 2, 3, 4]).toPromise();
+    expect(res).toBe(10);
+  });
+
+  test('should handle streaming response from RxJS Observable', async () => {
+    const results: string[] = [];
+    await new Promise<void>((resolve, reject) => {
+      client.send<string, string>('stream', 'hello').subscribe({
+        next: (val) => results.push(val),
+        error: (err) => reject(err),
+        complete: () => resolve(),
+      });
+    });
+    expect(results).toEqual(['echo1: hello', 'echo2: hello']);
+  });
+
+  test('should propagate error message from RPC back to client', async () => {
+    try {
+      await client.send('error_test', {}).toPromise();
+      expect().fail('Expected send to throw error');
+    } catch (err: any) {
+      expect(err.message).toBe('This is a simulated RPC error');
+    }
+  });
+
+  test('should dispatch event pattern messages asynchronously', async () => {
+    eventReceived = false;
+    eventPayload = null;
+
+    await client.emit('log_event', { status: 'ok', code: 200 }).toPromise();
+
+    // Wait a tick for TCP event handling
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(eventReceived).toBe(true);
+    expect(eventPayload).toEqual({ status: 'ok', code: 200 });
+  });
+});

package/tests/rpc-ws-context.test.ts

@@ -0,0 +1,135 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { of, Observable } from 'rxjs';
+import {
+  Module,
+  CalyxFactory,
+  WebSocketGateway,
+  SubscribeMessage,
+  MessageBody,
+  UseGuards,
+  UseInterceptors,
+  CanActivate,
+  ExecutionContext,
+  NestInterceptor,
+  CallHandler,
+  ClientTcp,
+  Transport,
+  MessagePattern,
+  Controller,
+} from '../src/index.ts';
+
+class SecurityGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const type = context.getType();
+    if (type === 'ws') {
+      const data = context.switchToWs().getData();
+      return data.user === 'admin';
+    }
+    if (type === 'rpc') {
+      const data = context.switchToRpc().getData();
+      return data.role === 'admin';
+    }
+    return false;
+  }
+}
+
+class LoggingInterceptor implements NestInterceptor {
+  async intercept(context: ExecutionContext, next: CallHandler): Promise<any> {
+    const type = context.getType();
+    const result = await next.handle();
+    return { type, original: result };
+  }
+}
+
+@WebSocketGateway(3915)
+class SecureGateway {
+  @SubscribeMessage('ping')
+  @UseGuards(SecurityGuard)
+  @UseInterceptors(LoggingInterceptor)
+  handlePing(@MessageBody() data: any) {
+    return 'pong';
+  }
+}
+
+@Controller()
+class SecureController {
+  @MessagePattern('ping_rpc')
+  @UseGuards(SecurityGuard)
+  @UseInterceptors(LoggingInterceptor)
+  handlePingRpc(data: any) {
+    return 'pong_rpc';
+  }
+}
+
+@Module({
+  controllers: [SecureController],
+  providers: [SecureGateway],
+})
+class TestApp {}
+
+describe('Guards and Interceptors for WS and RPC contexts', () => {
+  let wsApp: any;
+  let rpcApp: any;
+  let client: ClientTcp;
+  const PORT = 3889;
+  const RPC_PORT = 3916;
+
+  beforeAll(async () => {
+    // 1. Start standard app for HTTP/WS
+    wsApp = await CalyxFactory.create(TestApp);
+    await wsApp.listen(PORT);
+
+    // 2. Start dedicated microservice for RPC
+    rpcApp = await CalyxFactory.createMicroservice(TestApp, {
+      transport: Transport.TCP,
+      options: { port: RPC_PORT },
+    });
+    await rpcApp.listen();
+
+    client = new ClientTcp({ port: RPC_PORT });
+  });
+
+  afterAll(async () => {
+    client.close();
+    await rpcApp.close();
+    await wsApp.close();
+  });
+
+  test('should pass or deny WS events using context switching in guards/interceptors', async () => {
+    const ws = new WebSocket('ws://localhost:3915');
+
+    await new Promise<void>((resolve, reject) => {
+      ws.onopen = () => resolve();
+      ws.onerror = (err) => reject(err);
+    });
+
+    ws.send(JSON.stringify({ event: 'ping', data: { user: 'admin' } }));
+    const successRes = await new Promise<any>((resolve) => {
+      ws.onmessage = (event) => resolve(JSON.parse(event.data));
+    });
+    expect(successRes).toEqual({ type: 'ws', original: 'pong' });
+
+    let receivedMessage = false;
+    ws.onmessage = () => {
+      receivedMessage = true;
+    };
+    ws.send(JSON.stringify({ event: 'ping', data: { user: 'guest' } }));
+    
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(receivedMessage).toBe(false);
+
+    ws.close();
+  });
+
+  test('should pass or deny RPC messages using context switching in guards/interceptors', async () => {
+    const successRes = await client.send('ping_rpc', { role: 'admin' }).toPromise();
+    expect(successRes).toEqual({ type: 'rpc', original: 'pong_rpc' });
+
+    try {
+      await client.send('ping_rpc', { role: 'guest' }).toPromise();
+      expect().fail('Expected send to throw error');
+    } catch (err: any) {
+      expect(err.message).toBe('Forbidden resource');
+    }
+  });
+});

package/tests/websockets.test.ts

@@ -0,0 +1,125 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import {
+  Module,
+  CalyxFactory,
+  WebSocketGateway,
+  SubscribeMessage,
+  MessageBody,
+  ConnectedSocket,
+} from '../src/index.ts';
+
+let clientConnected = false;
+let clientDisconnected = false;
+let messageReceived: any = null;
+
+// 1. Shared Port Gateway
+@WebSocketGateway()
+class SharedEventsGateway {
+  handleConnection(client: any) {
+    clientConnected = true;
+  }
+
+  handleDisconnect(client: any) {
+    clientDisconnected = true;
+  }
+
+  @SubscribeMessage('events')
+  onEvents(@MessageBody() data: any, @ConnectedSocket() client: any) {
+    messageReceived = data;
+    return { event: 'events', data: `echo: ${data}` };
+  }
+}
+
+// 2. Dedicated Port Gateway
+let dedicatedConnected = false;
+@WebSocketGateway(3912)
+class DedicatedEventsGateway {
+  handleConnection(client: any) {
+    dedicatedConnected = true;
+  }
+
+  @SubscribeMessage('dedicated_event')
+  onDedicatedEvent(@MessageBody() data: any) {
+    return { event: 'dedicated_response', data: `dedicated echo: ${data}` };
+  }
+}
+
+@Module({
+  providers: [SharedEventsGateway, DedicatedEventsGateway],
+})
+class TestApp {}
+
+describe('WebSocket Gateways (Bun.serve, SubscribeMessage, MessageBody, ConnectedSocket)', () => {
+  let app: any;
+  const PORT = 3889;
+
+  beforeAll(async () => {
+    app = await CalyxFactory.create(TestApp);
+    await app.listen(PORT);
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('should connect and handle message exchange on shared port', async () => {
+    clientConnected = false;
+    clientDisconnected = false;
+    messageReceived = null;
+
+    const ws = new WebSocket(`ws://localhost:${PORT}`);
+
+    // Wait for connection to open
+    await new Promise<void>((resolve, reject) => {
+      ws.onopen = () => resolve();
+      ws.onerror = (err) => reject(err);
+    });
+
+    expect(clientConnected).toBe(true);
+
+    // Send a message
+    ws.send(JSON.stringify({ event: 'events', data: 'hello calyx' }));
+
+    // Wait for response message
+    const response = await new Promise<any>((resolve) => {
+      ws.onmessage = (event) => {
+        resolve(JSON.parse(event.data));
+      };
+    });
+
+    expect(messageReceived).toBe('hello calyx');
+    expect(response).toEqual({ event: 'events', data: 'echo: hello calyx' });
+
+    // Close connection
+    ws.close();
+
+    // Wait a tick for disconnect event
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(clientDisconnected).toBe(true);
+  });
+
+  test('should connect and handle message exchange on dedicated port', async () => {
+    dedicatedConnected = false;
+
+    const ws = new WebSocket('ws://localhost:3912');
+
+    await new Promise<void>((resolve, reject) => {
+      ws.onopen = () => resolve();
+      ws.onerror = (err) => reject(err);
+    });
+
+    expect(dedicatedConnected).toBe(true);
+
+    ws.send(JSON.stringify({ event: 'dedicated_event', data: 'secure channel' }));
+
+    const response = await new Promise<any>((resolve) => {
+      ws.onmessage = (event) => {
+        resolve(JSON.parse(event.data));
+      };
+    });
+
+    expect(response).toEqual({ event: 'dedicated_response', data: 'dedicated echo: secure channel' });
+
+    ws.close();
+  });
+});