@martel/calyx 1.4.0 → 1.6.0

package/src/schedule/schedule.module.ts

@@ -0,0 +1,13 @@
+import { Module, DynamicModule } from '../core/decorators.ts';
+
+@Module({})
+export class ScheduleModule {
+  static forRoot(): DynamicModule {
+    return {
+      module: ScheduleModule,
+      providers: [],
+      exports: [],
+      global: true,
+    };
+  }
+}

package/src/security/cors.middleware.ts

@@ -0,0 +1,50 @@
+import { CalyxResponse } from '../http/application.ts';
+
+export interface CorsOptions {
+  origin?: string | string[] | boolean;
+  methods?: string | string[];
+  allowedHeaders?: string | string[];
+  exposedHeaders?: string | string[];
+  credentials?: boolean;
+  maxAge?: number;
+}
+
+export function cors(options: CorsOptions = {}) {
+  const origin = options.origin ?? '*';
+  const methods = options.methods ?? 'GET,HEAD,PUT,PATCH,POST,DELETE';
+  const allowedHeaders = options.allowedHeaders ?? '*';
+  const credentials = options.credentials ?? false;
+  const maxAge = options.maxAge;
+
+  return (req: Request, res: CalyxResponse, next: () => void) => {
+    const reqOrigin = req.headers.get('origin');
+
+    if (origin === '*') {
+      res.headers['access-control-allow-origin'] = '*';
+    } else if (typeof origin === 'string') {
+      res.headers['access-control-allow-origin'] = origin;
+    } else if (Array.isArray(origin) && reqOrigin && origin.includes(reqOrigin)) {
+      res.headers['access-control-allow-origin'] = reqOrigin;
+    } else if (origin === true && reqOrigin) {
+      res.headers['access-control-allow-origin'] = reqOrigin;
+    }
+
+    res.headers['access-control-allow-methods'] = Array.isArray(methods) ? methods.join(',') : methods;
+    res.headers['access-control-allow-headers'] = Array.isArray(allowedHeaders) ? allowedHeaders.join(',') : allowedHeaders;
+
+    if (credentials) {
+      res.headers['access-control-allow-credentials'] = 'true';
+    }
+
+    if (maxAge !== undefined) {
+      res.headers['access-control-max-age'] = String(maxAge);
+    }
+
+    if (req.method === 'OPTIONS') {
+      res.status(204).send('');
+      return;
+    }
+
+    next();
+  };
+}

package/src/security/hashing.service.ts

@@ -0,0 +1,12 @@
+import { Injectable } from '../core/decorators.ts';
+
+@Injectable()
+export class HashingService {
+  async hash(data: string, algorithm: 'bcrypt' | 'argon2id' | 'argon2i' | 'argon2d' = 'bcrypt'): Promise<string> {
+    return Bun.password.hash(data, algorithm);
+  }
+
+  async verify(data: string, hash: string): Promise<boolean> {
+    return Bun.password.verify(data, hash);
+  }
+}

package/src/security/helmet.middleware.ts

@@ -0,0 +1,45 @@
+import { CalyxResponse } from '../http/application.ts';
+
+export interface HelmetOptions {
+  contentSecurityPolicy?: boolean | string;
+  crossOriginOpenerPolicy?: string;
+  crossOriginResourcePolicy?: string;
+  referrerPolicy?: string;
+  xContentTypeOptions?: string;
+  xDnsPrefetchControl?: string;
+  xFrameOptions?: string;
+  xXssProtection?: string;
+}
+
+export function helmet(options: HelmetOptions = {}) {
+  const headers: Record<string, string> = {
+    'cross-origin-opener-policy': options.crossOriginOpenerPolicy ?? 'same-origin',
+    'cross-origin-resource-policy': options.crossOriginResourcePolicy ?? 'same-origin',
+    'origin-agent-cluster': '?1',
+    'referrer-policy': options.referrerPolicy ?? 'no-referrer',
+    'strict-transport-security': 'max-age=15552000; includeSubDomains',
+    'x-content-type-options': options.xContentTypeOptions ?? 'nosniff',
+    'x-dns-prefetch-control': options.xDnsPrefetchControl ?? 'off',
+    'x-download-options': 'noopen',
+    'x-frame-options': options.xFrameOptions ?? 'SAMEORIGIN',
+    'x-permitted-cross-domain-policies': 'none',
+    'x-xss-protection': options.xXssProtection ?? '0',
+  };
+
+  const csp = options.contentSecurityPolicy;
+  if (csp !== false) {
+    headers['content-security-policy'] = typeof csp === 'string'
+      ? csp
+      : "default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests";
+  }
+
+  const headerPairs = Object.entries(headers);
+
+  return (req: Request, res: CalyxResponse, next: () => void) => {
+    for (let i = 0; i < headerPairs.length; i++) {
+      const pair = headerPairs[i];
+      res.headers[pair[0]] = pair[1];
+    }
+    next();
+  };
+}

package/src/security/index.ts

@@ -0,0 +1,3 @@
+export * from './hashing.service.ts';
+export * from './cors.middleware.ts';
+export * from './helmet.middleware.ts';

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/config-event.test.ts

@@ -0,0 +1,145 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import {
+  Module,
+  Controller,
+  Get,
+  Injectable,
+  CalyxFactory,
+  ConfigModule,
+  ConfigService,
+  EventEmitterModule,
+  EventEmitter,
+  OnEvent,
+} from '../src/index.ts';
+
+// 1. Config Test classes
+@Injectable()
+class ConfigTestService {
+  constructor(private readonly config: ConfigService) {}
+
+  getDbUser(): string {
+    return this.config.get('DB_USER', 'default');
+  }
+
+  getDbPort(): number {
+    return this.config.get('DB_PORT', 5432);
+  }
+
+  getDebugMode(): boolean {
+    return this.config.get('DEBUG_MODE', false);
+  }
+}
+
+// 2. Event emitter test classes
+let orderCreatedCount = 0;
+let anyOrderCount = 0;
+
+@Injectable()
+class OrderService {
+  constructor(private readonly emitter: EventEmitter) {}
+
+  createOrder() {
+    this.emitter.emit('order.created', { id: 101, total: 50.0 });
+  }
+
+  cancelOrder() {
+    this.emitter.emit('order.cancelled', { id: 101 });
+  }
+}
+
+@Injectable()
+class NotificationService {
+  @OnEvent('order.created')
+  handleOrderCreated(payload: any) {
+    orderCreatedCount++;
+    expect(payload.id).toBe(101);
+  }
+
+  @OnEvent('order.*')
+  handleAnyOrder(payload: any) {
+    anyOrderCount++;
+  }
+}
+
+@Controller('test')
+class TestController {
+  constructor(
+    private readonly configTest: ConfigTestService,
+    private readonly orders: OrderService
+  ) {}
+
+  @Get('config')
+  getConfig() {
+    return {
+      user: this.configTest.getDbUser(),
+      port: this.configTest.getDbPort(),
+      debug: this.configTest.getDebugMode(),
+    };
+  }
+
+  @Get('trigger-event')
+  triggerEvent() {
+    this.orders.createOrder();
+    this.orders.cancelOrder();
+    return { triggered: true };
+  }
+}
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      load: [
+        () => ({
+          DB_USER: 'calyx_admin',
+          DB_PORT: '8080',
+          DEBUG_MODE: 'true',
+        }),
+      ],
+    }),
+    EventEmitterModule.forRoot(),
+  ],
+  controllers: [TestController],
+  providers: [ConfigTestService, OrderService, NotificationService],
+})
+class AppModule {}
+
+describe('Config and Event Modules Parity', () => {
+  let app: any;
+  let baseUrl: string;
+  const PORT = 3866;
+
+  beforeAll(async () => {
+    app = await CalyxFactory.create(AppModule);
+    await app.listen(PORT);
+    baseUrl = `http://localhost:${PORT}`;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('should resolve custom environment variables via ConfigService', async () => {
+    const res = await fetch(`${baseUrl}/test/config`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({
+      user: 'calyx_admin',
+      port: 8080,
+      debug: true,
+    });
+  });
+
+  test('should trigger event and notify OnEvent listeners, including wildcards', async () => {
+    orderCreatedCount = 0;
+    anyOrderCount = 0;
+
+    const res = await fetch(`${baseUrl}/test/trigger-event`);
+    expect(res.status).toBe(200);
+    
+    // Wait for event loop ticks
+    await new Promise(resolve => setTimeout(resolve, 50));
+
+    expect(orderCreatedCount).toBe(1);
+    expect(anyOrderCount).toBe(2); // Matches order.created and order.cancelled
+  });
+});

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/schedule.test.ts

@@ -0,0 +1,64 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import {
+  Module,
+  CalyxFactory,
+  ScheduleModule,
+  Cron,
+  Interval,
+  Timeout,
+  Injectable,
+} from '../src/index.ts';
+
+let cronCalls = 0;
+let intervalCalls = 0;
+let timeoutCalls = 0;
+
+@Injectable()
+class TaskService {
+  @Cron('*/1 * * * * *') // Every second
+  handleCron() {
+    cronCalls++;
+  }
+
+  @Interval(100) // Every 100ms
+  handleInterval() {
+    intervalCalls++;
+  }
+
+  @Timeout(250) // After 250ms
+  handleTimeout() {
+    timeoutCalls++;
+  }
+}
+
+@Module({
+  imports: [ScheduleModule.forRoot()],
+  providers: [TaskService],
+})
+class TestApp {}
+
+describe('Task Scheduler (ScheduleModule, Cron, Interval, Timeout)', () => {
+  let app: any;
+
+  beforeAll(async () => {
+    cronCalls = 0;
+    intervalCalls = 0;
+    timeoutCalls = 0;
+
+    app = await CalyxFactory.create(TestApp);
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('should fire intervals, timeouts, and cron jobs on schedule', async () => {
+    // Wait 500ms
+    await new Promise((resolve) => setTimeout(resolve, 550));
+
+    expect(cronCalls).toBeGreaterThanOrEqual(0);
+    expect(intervalCalls).toBeGreaterThan(3);
+    expect(timeoutCalls).toBe(1);
+  });
+});