@martel/calyx 1.7.0 → 1.9.0

package/src/http/application.ts

@@ -11,6 +11,12 @@ import { cors, CorsOptions } from '../security/cors.middleware.ts';
 import { helmet, HelmetOptions } from '../security/helmet.middleware.ts';
 import { CronMatcher } from '../schedule/cron.matcher.ts';
 import { SerializationCompiler } from '../validation/compiler.ts';
+import { VersioningOptions, VersioningType, VersionExtractor, VERSION_METADATA_KEY } from '../versioning/versioning.ts';
+import { QueueManager, PROCESSOR_METADATA_KEY } from '../queue/queue.module.ts';
+import { parseCookies, formatCookie } from '../cookies/cookies.ts';
+import { StreamableFile } from '../streaming/streamable-file.ts';
+import { defaultRenderEngine, ViewEngine } from '../mvc/mvc.ts';
+import { join } from 'path';
 
 class ObjectPool<T> {
   private pool: T[] = [];
@@ -53,6 +59,13 @@ export class CalyxResponse {
     this.headers[name.toLowerCase()] = value;
     return this;
   }
+
+  cookiesList: string[] = [];
+
+  cookie(name: string, value: string, options?: any) {
+    this.cookiesList.push(formatCookie(name, value, options));
+    return this;
+  }
 }
 
 interface CompiledLifecycleItem {
@@ -85,6 +98,8 @@ interface HandlerConfig {
   interceptorsList: CompiledLifecycleItem[];
   filtersList: CompiledLifecycleItem[];
   middlewaresList: CompiledLifecycleItem[];
+  renderTemplate?: string;
+  isSse?: boolean;
 }
 
 export class CalyxApplication {
@@ -103,6 +118,34 @@ export class CalyxApplication {
   private sharedWebSockets: any[] = [];
   private hasWebSockets = false;
   private serverPort = 3000;
+  private graphqlSchema: any = null;
+  private isInitialized = false;
+  private versioningOptions?: VersioningOptions;
+
+  enableVersioning(options: VersioningOptions) {
+    this.versioningOptions = options;
+    return this;
+  }
+
+  private compressionEnabled = false;
+
+  enableCompression() {
+    this.compressionEnabled = true;
+    return this;
+  }
+
+  private viewsDir = 'views';
+  private viewEngine: ViewEngine = defaultRenderEngine;
+
+  setViewsDir(dir: string) {
+    this.viewsDir = dir;
+    return this;
+  }
+
+  setViewEngine(engine: ViewEngine) {
+    this.viewEngine = engine;
+    return this;
+  }
 
   use(...middlewares: any[]) {
     this.globalMiddlewares.push(...middlewares);
@@ -138,6 +181,9 @@ export class CalyxApplication {
   constructor(private rootModule: any) {}
 
   async init() {
+    if (this.isInitialized) return;
+    this.isInitialized = true;
+
     // Bootstrap the dependency injection container
     this.container.bootstrap(this.rootModule);
 
@@ -150,6 +196,9 @@ export class CalyxApplication {
     // Register Event listeners
     this.registerEventListeners();
 
+    // Register Queue Processors
+    this.registerQueueProcessors();
+
     // Register Scheduled tasks
     this.registerScheduledTasks();
 
@@ -161,9 +210,18 @@ export class CalyxApplication {
 
     // Call OnApplicationBootstrap hooks
     await this.runOnApplicationBootstrap();
+
+    // Build GraphQL Schema if GraphQLModule is loaded
+    try {
+      const { GraphQLModule } = await import('../graphql/graphql.module.ts');
+      this.graphqlSchema = GraphQLModule.buildSchema(this.container);
+    } catch {
+      // ignore
+    }
   }
 
   private buildRoutes() {
+    this.router.clear();
     const modules = this.container.getModules();
     for (const [moduleClass, record] of modules.entries()) {
       for (const controllerClass of record.controllers) {
@@ -245,26 +303,64 @@ export class CalyxApplication {
             hasReqScopedPipe ||
             hasReqScopedMiddleware;
 
-          this.router.insert(routeMeta.method, fullPath, {
-            controllerClass,
-            moduleClass,
-            instance: singletonInstance,
-            methodName: method,
-            paramsConfig: compiledParamsConfig,
-            httpCode,
-            headers,
-            redirect,
-            hasBodyParam,
-            hasQueryParam,
-            hasResParam,
-            isPassthrough,
-            isRequestScoped: isRouteRequestScoped,
-            hasLifecycleMetadata,
-            guardsList,
-            interceptorsList,
-            filtersList,
-            middlewaresList,
-          });
+          const methodFn = controllerClass.prototype[method];
+          // Compile versions if versioning is enabled
+          let versions: string[] = [];
+          if (this.versioningOptions) {
+            const rawVersion = Reflect.getMetadata(VERSION_METADATA_KEY, controllerClass.prototype, method) ??
+                               Reflect.getMetadata(VERSION_METADATA_KEY, methodFn) ??
+                               Reflect.getMetadata(VERSION_METADATA_KEY, controllerClass);
+            if (rawVersion !== undefined && rawVersion !== null) {
+              versions = Array.isArray(rawVersion) ? rawVersion : [rawVersion];
+            } else if (this.versioningOptions.defaultVersion !== undefined && this.versioningOptions.defaultVersion !== null) {
+              const defaultV = this.versioningOptions.defaultVersion;
+              versions = Array.isArray(defaultV) ? defaultV : [defaultV];
+            }
+          }
+
+          const renderTemplate = Reflect.getMetadata('calyx:render_template', controllerClass.prototype, method) ??
+                                 Reflect.getMetadata('calyx:render_template', methodFn);
+          const isSse = Reflect.hasMetadata('calyx:sse', controllerClass.prototype, method) ||
+                        Reflect.hasMetadata('calyx:sse', methodFn);
+
+          const insertRoute = (methodStr: string, pathStr: string) => {
+            this.router.insert(methodStr, pathStr, {
+              controllerClass,
+              moduleClass,
+              instance: singletonInstance,
+              methodName: method,
+              paramsConfig: compiledParamsConfig,
+              httpCode,
+              headers,
+              redirect,
+              hasBodyParam,
+              hasQueryParam,
+              hasResParam,
+              isPassthrough,
+              isRequestScoped: isRouteRequestScoped,
+              hasLifecycleMetadata,
+              guardsList,
+              interceptorsList,
+              filtersList,
+              middlewaresList,
+              renderTemplate,
+              isSse,
+            });
+          };
+
+          if (this.versioningOptions && this.versioningOptions.type === VersioningType.URI && versions.length > 0) {
+            for (const version of versions) {
+              const versionPrefix = `/v${version}`;
+              const versionedPath = '/' + [versionPrefix.replace(/^\/|\/$/g, ''), normalizedPrefix, normalizedPath].filter(Boolean).join('/');
+              insertRoute(routeMeta.method, versionedPath);
+            }
+          } else if (this.versioningOptions && (this.versioningOptions.type === VersioningType.HEADER || this.versioningOptions.type === VersioningType.MEDIA_TYPE) && versions.length > 0) {
+            for (const version of versions) {
+              insertRoute(`${routeMeta.method}:v${version}`, fullPath);
+            }
+          } else {
+            insertRoute(routeMeta.method, fullPath);
+          }
         }
       }
     }
@@ -382,6 +478,10 @@ export class CalyxApplication {
   private handleRequest(req: Request): Response | Promise<Response> {
     try {
       const urlStr = req.url;
+      // Parse cookies
+      const cookieHeader = req.headers.get('cookie') || '';
+      (req as any).cookies = parseCookies(cookieHeader);
+
       // Fast path parsing
       let pathname = '/';
       let search = '';
@@ -398,7 +498,20 @@ export class CalyxApplication {
         pathname = pathname.substring(0, queryIdx);
       }
 
-      const matched = this.router.match(req.method, pathname);
+      if (this.graphqlSchema && pathname === '/graphql' && req.method === 'POST') {
+        return this.handleGraphQLRequest(req);
+      }
+
+      let matched = null;
+      if (this.versioningOptions && this.versioningOptions.type !== VersioningType.URI) {
+        const version = VersionExtractor.extract(req, this.versioningOptions.type, this.versioningOptions);
+        if (version) {
+          matched = this.router.match(`${req.method}:v${version}`.toUpperCase(), pathname);
+        }
+      }
+      if (!matched) {
+        matched = this.router.match(req.method, pathname);
+      }
       if (!matched) {
         if (this.globalMiddlewares.length > 0) {
           return this.handleGlobalMiddlewaresAnd404(req, pathname);
@@ -466,6 +579,8 @@ export class CalyxApplication {
         } catch {
           body = {};
         }
+      } else if (contentType.includes('multipart/form-data')) {
+        body = null;
       } else {
         try {
           body = await req.text();
@@ -558,39 +673,41 @@ export class CalyxApplication {
         query = {};
       }
 
-      // Execute pipes for each argument
-      const args: any[] = [];
-      for (const config of paramsConfig) {
-        let val: any;
-        switch (config.type) {
-          case 'req': val = req; break;
-          case 'res': val = resWrapper; break;
-          case 'param': val = config.name ? params[config.name] : params; break;
-          case 'query': val = config.name ? query?.[config.name] : query; break;
-          case 'body': val = config.name ? body?.[config.name] : body; break;
-          case 'headers': val = config.name ? req.headers.get(config.name) : Object.fromEntries(req.headers.entries()); break;
-          case 'custom': val = config.factory ? config.factory(config.name, context) : undefined; break;
-        }
+      const resolveArgs = async (): Promise<any[]> => {
+        const args: any[] = [];
+        for (const config of paramsConfig) {
+          let val: any;
+          switch (config.type) {
+            case 'req': val = req; break;
+            case 'res': val = resWrapper; break;
+            case 'param': val = config.name ? params[config.name] : params; break;
+            case 'query': val = config.name ? query?.[config.name] : query; break;
+            case 'body': val = config.name ? body?.[config.name] : body; break;
+            case 'headers': val = config.name ? req.headers.get(config.name) : Object.fromEntries(req.headers.entries()); break;
+            case 'custom': val = config.factory ? config.factory(config.name, context) : undefined; break;
+          }
 
-        // Apply pipes
-        for (const pipe of config.pipesList) {
-          const pipeInstance = pipe.isReqScoped
-            ? this.container.resolveTokenInModuleContext(moduleClass, pipe.token, requestContext)
-            : pipe.instance;
-          const transformed = pipeInstance.transform(val, {
-            type: config.type,
-            metatype: config.paramType,
-            data: config.name,
-          });
-          if (transformed instanceof Promise) {
-            val = await transformed;
-          } else {
-            val = transformed;
+          // Apply pipes
+          for (const pipe of config.pipesList) {
+            const pipeInstance = pipe.isReqScoped
+              ? this.container.resolveTokenInModuleContext(moduleClass, pipe.token, requestContext)
+              : pipe.instance;
+            const transformed = pipeInstance.transform(val, {
+              type: config.type,
+              metatype: config.paramType,
+              data: config.name,
+            });
+            if (transformed instanceof Promise) {
+              val = await transformed;
+            } else {
+              val = transformed;
+            }
           }
-        }
 
-        args[config.index] = val;
-      }
+          args[config.index] = val;
+        }
+        return args;
+      };
 
       let result: any;
       if (handler.interceptorsList.length > 0) {
@@ -603,21 +720,23 @@ export class CalyxApplication {
               : interceptor.instance;
             return interceptorInstance.intercept(context, { handle: () => executeHandler() });
           }
+          const args = await resolveArgs();
           return instance[methodName](...args);
         };
         result = await executeHandler();
       } else {
+        const args = await resolveArgs();
         result = instance[methodName](...args);
         if (result instanceof Promise) {
           result = await result;
         }
       }
 
-      if (this.isObservable(result)) {
+      if (this.isObservable(result) && !handler.isSse) {
         result = await this.resolveObservable(result);
       }
 
-      return this.processResult(req, result, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam);
+      return this.processResult(req, result, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam, handler.renderTemplate, handler.isSse);
     } catch (err: any) {
       return await this.handleLifecycleError(err, host, handler, requestContext);
     } finally {
@@ -757,6 +876,8 @@ export class CalyxApplication {
         } catch {
           body = {};
         }
+      } else if (contentType.includes('multipart/form-data')) {
+        body = null;
       } else {
         try {
           body = await req.text();
@@ -826,15 +947,54 @@ export class CalyxApplication {
 
     let result = instance[methodName](...args);
 
-    if (this.isObservable(result)) {
+    if (this.isObservable(result) && !handler.isSse) {
       result = this.resolveObservable(result);
     }
 
     if (result instanceof Promise) {
-      return result.then((resolvedResult) => this.processResult(req, resolvedResult, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam));
+      return result.then((resolvedResult) => this.processResult(req, resolvedResult, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam, handler.renderTemplate, handler.isSse));
     }
 
-    return this.processResult(req, result, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam);
+    return this.processResult(req, result, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam, handler.renderTemplate, handler.isSse);
+  }
+
+  private compressResponseIfNeeded(req: Request, body: any, headers: Headers, resWrapper: CalyxResponse | null): any {
+    const isEnabled = this.compressionEnabled || (resWrapper && (resWrapper as any).compressionEnabled);
+    if (!isEnabled) return body;
+
+    const acceptEncoding = req.headers.get('accept-encoding') || '';
+    if (!acceptEncoding.includes('gzip')) return body;
+
+    if (!body) return body;
+
+    const contentType = headers.get('content-type') || '';
+    const isCompressible = contentType.includes('text/') ||
+                          contentType.includes('json') ||
+                          contentType.includes('javascript') ||
+                          contentType.includes('xml') ||
+                          contentType === '';
+
+    if (!isCompressible) return body;
+
+    try {
+      let dataToCompress: Uint8Array;
+      if (typeof body === 'string') {
+        dataToCompress = new TextEncoder().encode(body);
+      } else if (body instanceof Uint8Array) {
+        dataToCompress = body;
+      } else if (body instanceof ArrayBuffer) {
+        dataToCompress = new Uint8Array(body);
+      } else {
+        dataToCompress = new TextEncoder().encode(JSON.stringify(body));
+      }
+
+      const compressed = Bun.gzipSync(dataToCompress);
+      headers.set('content-encoding', 'gzip');
+      headers.set('content-length', String(compressed.length));
+      return compressed;
+    } catch {
+      return body;
+    }
   }
 
   private processResult(
@@ -845,23 +1005,47 @@ export class CalyxApplication {
     headers: { name: string; value: string }[],
     redirect: { url: string; statusCode?: number } | undefined,
     isPassthrough = false,
-    hasResParam = false
-  ): Response {
+    hasResParam = false,
+    renderTemplate?: string,
+    isSse = false
+  ): Response | Promise<Response> {
     if (redirect) {
       return Response.redirect(redirect.url, redirect.statusCode || 302);
     }
 
     if (resWrapper) {
       if (resWrapper.sent && !isPassthrough) {
-        return new Response(resWrapper.body, {
+        const responseHeaders = new Headers();
+        for (const [k, v] of Object.entries(resWrapper.headers)) {
+          responseHeaders.set(k, v);
+        }
+        for (const c of resWrapper.cookiesList) {
+          responseHeaders.append('Set-Cookie', c);
+        }
+        if ((req as any).finalizeSession) {
+          (req as any).finalizeSession(responseHeaders);
+        }
+        const finalBody = this.compressResponseIfNeeded(req, resWrapper.body, responseHeaders, resWrapper);
+        return new Response(finalBody, {
           status: resWrapper.statusCode,
-          headers: resWrapper.headers,
+          headers: responseHeaders,
         });
       }
       if (hasResParam && !isPassthrough) {
-        return new Response(resWrapper.body, {
+        const responseHeaders = new Headers();
+        for (const [k, v] of Object.entries(resWrapper.headers)) {
+          responseHeaders.set(k, v);
+        }
+        for (const c of resWrapper.cookiesList) {
+          responseHeaders.append('Set-Cookie', c);
+        }
+        if ((req as any).finalizeSession) {
+          (req as any).finalizeSession(responseHeaders);
+        }
+        const finalBody = this.compressResponseIfNeeded(req, resWrapper.body, responseHeaders, resWrapper);
+        return new Response(finalBody, {
           status: resWrapper.statusCode,
-          headers: resWrapper.headers,
+          headers: responseHeaders,
         });
       }
     }
@@ -871,12 +1055,73 @@ export class CalyxApplication {
       : (httpCode ?? (req.method === 'POST' ? 201 : 200));
 
     // Build headers as a plain object Record<string, string>
-    const responseHeaders: Record<string, string> = resWrapper 
-      ? { ...resWrapper.headers } 
-      : {};
+    const responseHeaders = new Headers();
+    if (resWrapper) {
+      for (const [k, v] of Object.entries(resWrapper.headers)) {
+        responseHeaders.set(k, v);
+      }
+      for (const c of resWrapper.cookiesList) {
+        responseHeaders.append('Set-Cookie', c);
+      }
+    }
+
+    if ((req as any).finalizeSession) {
+      (req as any).finalizeSession(responseHeaders);
+    }
 
     for (const header of headers) {
-      responseHeaders[header.name.toLowerCase()] = header.value;
+      responseHeaders.set(header.name.toLowerCase(), header.value);
+    }
+
+    if (isSse) {
+      responseHeaders.set('content-type', 'text/event-stream');
+      responseHeaders.set('cache-control', 'no-cache');
+      responseHeaders.set('connection', 'keep-alive');
+
+      let subscription: any;
+      const stream = new ReadableStream({
+        start(controller) {
+          subscription = result.subscribe({
+            next(event: any) {
+              let msg = '';
+              if (event.id) msg += `id: ${event.id}\n`;
+              if (event.type) msg += `event: ${event.type}\n`;
+              if (event.retry) msg += `retry: ${event.retry}\n`;
+              const dataStr = typeof event.data === 'object' ? JSON.stringify(event.data) : String(event.data);
+              msg += `data: ${dataStr}\n\n`;
+              controller.enqueue(new TextEncoder().encode(msg));
+            },
+            error(err: any) {
+              controller.error(err);
+            },
+            complete() {
+              controller.close();
+            }
+          });
+        },
+        cancel() {
+          if (subscription) {
+            subscription.unsubscribe();
+          }
+        }
+      });
+
+      return new Response(stream, { status, headers: responseHeaders });
+    }
+
+    if (renderTemplate) {
+      const templatePath = join(this.viewsDir, renderTemplate + (renderTemplate.includes('.') ? '' : '.html'));
+      const renderResult = this.viewEngine(templatePath, result);
+      if (renderResult instanceof Promise) {
+        return renderResult.then((html) => {
+          responseHeaders.set('content-type', 'text/html');
+          const finalBody = this.compressResponseIfNeeded(req, html, responseHeaders, resWrapper);
+          return new Response(finalBody, { status, headers: responseHeaders });
+        });
+      }
+      responseHeaders.set('content-type', 'text/html');
+      const finalBody = this.compressResponseIfNeeded(req, renderResult, responseHeaders, resWrapper);
+      return new Response(finalBody, { status, headers: responseHeaders });
     }
 
     if (result === undefined || result === null) {
@@ -884,24 +1129,46 @@ export class CalyxApplication {
     }
 
     if (result instanceof Response) {
+      if (resWrapper && resWrapper.cookiesList.length > 0) {
+        for (const c of resWrapper.cookiesList) {
+          result.headers.append('Set-Cookie', c);
+        }
+      }
+      if ((req as any).finalizeSession) {
+        (req as any).finalizeSession(result.headers);
+      }
       return result;
     }
 
+    if (result instanceof StreamableFile) {
+      const fileHeaders = result.getHeaders();
+      for (const [k, v] of Object.entries(fileHeaders)) {
+        responseHeaders.set(k, v);
+      }
+      const finalBody = this.compressResponseIfNeeded(req, result.getStream(), responseHeaders, resWrapper);
+      return new Response(finalBody, { status, headers: responseHeaders });
+    }
+
     if (typeof result === 'object') {
-      responseHeaders['content-type'] = 'application/json';
+      responseHeaders.set('content-type', 'application/json');
       const constructor = result.constructor;
       if (constructor) {
         const hasRules = Reflect.hasMetadata('calyx:validation_rules', constructor);
         const hasExpose = Reflect.hasMetadata('calyx:expose_properties', constructor);
         if (hasRules || hasExpose) {
           const serialize = SerializationCompiler.compile(constructor);
-          return new Response(serialize(result), { status, headers: responseHeaders });
+          const serialized = serialize(result);
+          const finalBody = this.compressResponseIfNeeded(req, serialized, responseHeaders, resWrapper);
+          return new Response(finalBody, { status, headers: responseHeaders });
         }
       }
-      return new Response(JSON.stringify(result), { status, headers: responseHeaders });
+      const serialized = JSON.stringify(result);
+      const finalBody = this.compressResponseIfNeeded(req, serialized, responseHeaders, resWrapper);
+      return new Response(finalBody, { status, headers: responseHeaders });
     }
 
-    return new Response(String(result), { status, headers: responseHeaders });
+    const finalBody = this.compressResponseIfNeeded(req, String(result), responseHeaders, resWrapper);
+    return new Response(finalBody, { status, headers: responseHeaders });
   }
 
   private isObservable(obj: any): boolean {
@@ -943,8 +1210,36 @@ export class CalyxApplication {
     );
   }
 
+  private async handleGraphQLRequest(req: Request): Promise<Response> {
+    try {
+      const body = await req.json() as any;
+      const { query, variables } = body;
+
+      const { graphql } = await import('graphql');
+      const result = await graphql({
+        schema: this.graphqlSchema,
+        source: query,
+        variableValues: variables,
+      });
+
+      return new Response(JSON.stringify(result), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    } catch (err: any) {
+      return new Response(
+        JSON.stringify({ errors: [{ message: err.message }] }),
+        {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }
+      );
+    }
+  }
+
   async listen(port: number): Promise<any> {
     this.serverPort = port;
+    this.buildRoutes();
     await this.init();
 
     const fetchHandler = (req: Request, server: any) => {
@@ -1058,6 +1353,17 @@ export class CalyxApplication {
     }
   }
 
+  private registerQueueProcessors() {
+    const instances = this.container.getProviderAndControllerInstances();
+    for (const instance of instances) {
+      if (!instance || !instance.constructor) continue;
+      const queueName = Reflect.getMetadata(PROCESSOR_METADATA_KEY, instance.constructor);
+      if (queueName) {
+        QueueManager.registerProcessor(queueName, instance);
+      }
+    }
+  }
+
   private registerEventListeners() {
     let eventEmitter: EventEmitter;
     try {
@@ -1330,6 +1636,10 @@ export class CalyxApplication {
       // ignore non-json
     }
   }
+
+  getRoutes() {
+    return this.router.getRoutes();
+  }
 }
 
 

package/src/http/factory.ts

@@ -5,6 +5,7 @@ import { MicroserviceOptions } from '../microservices/interfaces.ts';
 export class CalyxFactory {
   static async create(rootModule: any): Promise<CalyxApplication> {
     const app = new CalyxApplication(rootModule);
+    await app.init();
     return app;
   }
 

package/src/http/router.ts

@@ -16,8 +16,21 @@ export class RadixRouter<T> {
   private staticRoutes = new Map<string, T>();
   private handlersArray: T[] = [];
   private compiledMatch: ((method: string, path: string) => RouteMatch<T> | null) | null = null;
+  private routesList: { method: string; path: string; handler: T }[] = [];
+
+  getRoutes() {
+    return this.routesList;
+  }
+
+  clear() {
+    this.root = new RouterNode<T>();
+    this.staticRoutes.clear();
+    this.routesList = [];
+    this.compiledMatch = null;
+  }
 
   insert(method: string, path: string, handler: T) {
+    this.routesList.push({ method, path, handler });
     const hasParams = path.includes(':') || path.includes('*');
     if (!hasParams) {
       this.staticRoutes.set(method.toUpperCase() + ' ' + path, handler);