@carno.js/core 1.1.1 → 1.2.0

package/src/compression/CompressionMiddleware.ts

@@ -0,0 +1,221 @@
+import type { Context } from '../context/Context';
+import type { CarnoMiddleware, CarnoClosure } from '../middleware/CarnoMiddleware';
+import { brotliCompressSync, constants } from 'zlib';
+
+type GzipLevel = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+type BrotliQuality = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11;
+
+/**
+ * Compression configuration.
+ */
+export interface CompressionConfig {
+  /**
+   * Minimum response size in bytes to trigger compression.
+   * Responses smaller than this are sent uncompressed.
+   * @default 1024
+   */
+  threshold?: number;
+
+  /**
+   * Preferred encoding order. Client's Accept-Encoding is matched against this list.
+   * @default ['br', 'gzip']
+   */
+  encodings?: ('br' | 'gzip' | 'deflate')[];
+
+  /**
+   * Content-Type patterns that should be compressed.
+   * Matched using string includes (case-insensitive).
+   * @default ['text/', 'application/json', 'application/javascript', 'application/xml', 'image/svg+xml']
+   */
+  compressibleTypes?: string[];
+
+  /**
+   * Brotli compression quality (0-11). Higher = better compression, slower.
+   * @default 4
+   */
+  brotliQuality?: BrotliQuality;
+
+  /**
+   * Gzip compression level (-1 to 9). Higher = better compression, slower.
+   * @default 6
+   */
+  gzipLevel?: GzipLevel;
+}
+
+const DEFAULT_THRESHOLD = 1024;
+const DEFAULT_ENCODINGS: ('br' | 'gzip' | 'deflate')[] = ['br', 'gzip'];
+const DEFAULT_COMPRESSIBLE_TYPES = [
+  'text/',
+  'application/json',
+  'application/javascript',
+  'application/xml',
+  'application/xhtml+xml',
+  'image/svg+xml',
+];
+const DEFAULT_BROTLI_QUALITY: BrotliQuality = 4;
+const DEFAULT_GZIP_LEVEL: GzipLevel = 6;
+
+type CompressFn = (data: Uint8Array<ArrayBuffer>) => Uint8Array<ArrayBuffer>;
+
+/**
+ * Compression middleware for Carno.
+ *
+ * Supports **gzip**, **brotli** and **deflate** using Bun's native APIs
+ * (zero external dependencies).
+ *
+ * Does NOT touch the hot path — runs entirely as a middleware in the
+ * onion chain. Routes without middleware remain untouched.
+ *
+ * All configuration is resolved once at construction time (startup)
+ * so the per-request overhead is minimal: one header check +
+ * one compression call for eligible responses.
+ *
+ * @example
+ * ```ts
+ * import { Carno, CompressionMiddleware } from '@carno.js/core';
+ *
+ * const app = new Carno()
+ *   .middlewares([new CompressionMiddleware()])
+ *   .controllers([MyController]);
+ *
+ * app.listen(3000);
+ * ```
+ *
+ * @example Custom configuration:
+ * ```ts
+ * new CompressionMiddleware({
+ *   threshold: 512,
+ *   encodings: ['gzip'],
+ *   gzipLevel: 9,
+ * })
+ * ```
+ */
+export class CompressionMiddleware implements CarnoMiddleware {
+  private readonly threshold: number;
+  private readonly compressibleTypes: string[];
+  private readonly compressors: Map<string, CompressFn>;
+  private readonly encodingOrder: string[];
+
+  constructor(config?: CompressionConfig) {
+    this.threshold = config?.threshold ?? DEFAULT_THRESHOLD;
+    this.compressibleTypes = (config?.compressibleTypes ?? DEFAULT_COMPRESSIBLE_TYPES)
+      .map(t => t.toLowerCase());
+
+    const encodings = config?.encodings ?? DEFAULT_ENCODINGS;
+    this.encodingOrder = encodings;
+
+    const brotliQuality = config?.brotliQuality ?? DEFAULT_BROTLI_QUALITY;
+    const gzipLevel = config?.gzipLevel ?? DEFAULT_GZIP_LEVEL;
+
+    // Pre-build compressor functions at construction time (startup only)
+    this.compressors = new Map();
+
+    for (const enc of encodings) {
+      switch (enc) {
+        case 'br':
+          this.compressors.set('br', (data: Uint8Array<ArrayBuffer>) => {
+            const buf = brotliCompressSync(data, {
+              params: { [constants.BROTLI_PARAM_QUALITY]: brotliQuality },
+            });
+            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+          });
+          break;
+        case 'gzip':
+          this.compressors.set('gzip', (data: Uint8Array<ArrayBuffer>) =>
+            Bun.gzipSync(data, { level: gzipLevel }),
+          );
+          break;
+        case 'deflate':
+          this.compressors.set('deflate', (data: Uint8Array<ArrayBuffer>) =>
+            Bun.deflateSync(data),
+          );
+          break;
+      }
+    }
+  }
+
+  async handle(ctx: Context, next: CarnoClosure): Promise<Response | void> {
+    const response = await next();
+
+    // Fast-exit: no Accept-Encoding header
+    const acceptEncoding = ctx.req.headers.get('accept-encoding');
+    if (!acceptEncoding) {
+      return response;
+    }
+
+    // Already encoded — skip
+    if (response.headers.get('content-encoding')) {
+      return response;
+    }
+
+    // Non-compressible content type — skip
+    const contentType = response.headers.get('content-type');
+    if (!contentType || !this.isCompressible(contentType)) {
+      return response;
+    }
+
+    // Negotiate encoding
+    const encoding = this.negotiateEncoding(acceptEncoding);
+    if (!encoding) {
+      return response;
+    }
+
+    // Read body bytes (consumes the response body)
+    const buffer = await response.arrayBuffer();
+
+    // Below threshold — reconstruct original response
+    if (buffer.byteLength < this.threshold) {
+      return new Response(buffer, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+      });
+    }
+
+    const compressor = this.compressors.get(encoding)!;
+    const bodyBytes = new Uint8Array(buffer);
+    const compressed = compressor(bodyBytes);
+
+    // If compressed is not smaller, return original uncompressed
+    if (compressed.byteLength >= buffer.byteLength) {
+      return new Response(buffer, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+      });
+    }
+
+    const headers = new Headers(response.headers);
+    headers.set('Content-Encoding', encoding);
+    headers.set('Content-Length', String(compressed.byteLength));
+    headers.set('Vary', this.buildVaryHeader(headers.get('Vary')));
+
+    return new Response(compressed, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
+
+  private isCompressible(contentType: string): boolean {
+    const lower = contentType.toLowerCase();
+    for (const pattern of this.compressibleTypes) {
+      if (lower.includes(pattern)) return true;
+    }
+    return false;
+  }
+
+  private negotiateEncoding(acceptEncoding: string): string | null {
+    const lower = acceptEncoding.toLowerCase();
+    for (const encoding of this.encodingOrder) {
+      if (lower.includes(encoding)) return encoding;
+    }
+    return null;
+  }
+
+  private buildVaryHeader(existing: string | null): string {
+    if (!existing) return 'Accept-Encoding';
+    if (existing.toLowerCase().includes('accept-encoding')) return existing;
+    return `${existing}, Accept-Encoding`;
+  }
+}

package/src/container/Container.ts

@@ -1,168 +1,168 @@
-/**
- * Lightweight DI Container for Turbo.
- * 
- * Features:
- * - Constructor injection via reflect-metadata
- * - Singleton scope by default
- * - Request scope support
- * - Lazy instantiation
- */
-
-export type Token<T = any> = new (...args: any[]) => T;
-
-export enum Scope {
-    SINGLETON = 'singleton', // Always the same instance
-    REQUEST = 'request',     // New instance per request
-    INSTANCE = 'instance'    // New instance per dependency injection
-}
-
-export interface ProviderConfig<T = any> {
-    token: Token<T>;
-    useClass?: Token<T>;
-    useValue?: T;
-    scope?: Scope;
-}
-
-interface ProviderEntry {
-    config: ProviderConfig;
-    instance: any | null;
-}
-
-export class Container {
-    private configs = new Map<Token, ProviderConfig>();
-    private instances = new Map<Token, any>();
-    private resolving = new Set<Token>();
-
-    register<T>(config: ProviderConfig<T> | Token<T>): this {
-        const normalized = this.normalizeConfig(config);
-
-        this.configs.set(normalized.token, normalized);
-
-        if (normalized.useValue !== undefined) {
-            this.instances.set(normalized.token, normalized.useValue);
-        }
-
-        return this;
-    }
-
-    get<T>(token: Token<T>): T {
-        const cached = this.instances.get(token);
-
-        if (cached !== undefined) {
-            return cached;
-        }
-
-        const res = this.resolveInternal(token);
-        return res.instance;
-    }
-
-    has(token: Token): boolean {
-        return this.configs.has(token);
-    }
-
-    /**
-     * Resolves a token to return instance and its effective scope.
-     */
-    private resolveInternal<T>(token: Token<T>, requestLocals?: Map<Token, any>): { instance: T, scope: Scope } {
-        // 1. Check Request Cache
-        if (requestLocals?.has(token)) {
-            return { instance: requestLocals.get(token), scope: Scope.REQUEST };
-        }
-
-        // 2. Check Singleton Cache
-        const cached = this.instances.get(token);
-        if (cached !== undefined) {
-            return { instance: cached, scope: Scope.SINGLETON };
-        }
-
-        const config = this.configs.get(token);
-
-        if (!config) {
-            throw new Error(`Provider not found: ${token.name}`);
-        }
-
-        // 3. Create Instance with Scope Bubbling
-        const creation = this.createInstance(config, requestLocals);
-
-        // 4. Cache based on Effective Scope
-        if (creation.scope === Scope.SINGLETON) {
-            this.instances.set(token, creation.instance);
-        } else if (creation.scope === Scope.REQUEST && requestLocals) {
-            requestLocals.set(token, creation.instance);
-        }
-        // INSTANCE scope is never cached
-
-        return creation;
-    }
-
-    private createInstance(config: ProviderConfig, requestLocals?: Map<Token, any>): { instance: any, scope: Scope } {
-        const target = config.useClass ?? config.token;
-
-        if (this.resolving.has(target)) {
-            throw new Error(`Circular dependency detected: ${target.name}`);
-        }
-
-        this.resolving.add(target);
-
-        try {
-            const depsToken = this.getDependencies(target);
-
-            if (depsToken.length === 0) {
-                // No deps: Scope is as configured
-                return { instance: new target(), scope: config.scope || Scope.SINGLETON };
-            }
-
-            const args: any[] = [];
-            let effectiveScope = config.scope || Scope.SINGLETON;
-
-            for (const depToken of depsToken) {
-                const depResult = this.resolveInternal(depToken, requestLocals);
-                args.push(depResult.instance);
-
-                // Scope Bubbling Logic:
-                // If a dependency is REQUEST scoped, the parent MUST become REQUEST scoped (if it was Singleton)
-                // to avoid holding a stale reference to a request-bound instance.
-                if (depResult.scope === Scope.REQUEST && effectiveScope === Scope.SINGLETON) {
-                    effectiveScope = Scope.REQUEST;
-                }
-
-                // Note: INSTANCE scope dependencies do not force bubbling because they are transient and safe to hold (usually),
-                // unless semantic logic dictates otherwise. For now, strictly bubbling REQUEST scope.
-            }
-
-            return { instance: new target(...args), scope: effectiveScope };
-        } finally {
-            this.resolving.delete(target);
-        }
-    }
-
-    private getDependencies(target: Token): Token[] {
-        const types = Reflect.getMetadata('design:paramtypes', target) || [];
-        return types.filter((t: any) => t && typeof t === 'function' && !this.isPrimitive(t));
-    }
-
-    private isPrimitive(type: any): boolean {
-        return type === String || type === Number || type === Boolean || type === Object || type === Array || type === Symbol;
-    }
-
-    private normalizeConfig<T>(config: ProviderConfig<T> | Token<T>): ProviderConfig<T> {
-        if (typeof config === 'function') {
-            return {
-                token: config,
-                useClass: config,
-                scope: Scope.SINGLETON
-            };
-        }
-
-        return {
-            ...config,
-            useClass: config.useClass ?? config.token,
-            scope: config.scope ?? Scope.SINGLETON
-        };
-    }
-
-    clear(): void {
-        this.configs.clear();
-        this.instances.clear();
-    }
-}
+/**
+ * Lightweight DI Container for Turbo.
+ * 
+ * Features:
+ * - Constructor injection via reflect-metadata
+ * - Singleton scope by default
+ * - Request scope support
+ * - Lazy instantiation
+ */
+
+export type Token<T = any> = new (...args: any[]) => T;
+
+export enum Scope {
+    SINGLETON = 'singleton', // Always the same instance
+    REQUEST = 'request',     // New instance per request
+    INSTANCE = 'instance'    // New instance per dependency injection
+}
+
+export interface ProviderConfig<T = any> {
+    token: Token<T>;
+    useClass?: Token<T>;
+    useValue?: T;
+    scope?: Scope;
+}
+
+interface ProviderEntry {
+    config: ProviderConfig;
+    instance: any | null;
+}
+
+export class Container {
+    private configs = new Map<Token, ProviderConfig>();
+    private instances = new Map<Token, any>();
+    private resolving = new Set<Token>();
+
+    register<T>(config: ProviderConfig<T> | Token<T>): this {
+        const normalized = this.normalizeConfig(config);
+
+        this.configs.set(normalized.token, normalized);
+
+        if (normalized.useValue !== undefined) {
+            this.instances.set(normalized.token, normalized.useValue);
+        }
+
+        return this;
+    }
+
+    get<T>(token: Token<T>): T {
+        const cached = this.instances.get(token);
+
+        if (cached !== undefined) {
+            return cached;
+        }
+
+        const res = this.resolveInternal(token);
+        return res.instance;
+    }
+
+    has(token: Token): boolean {
+        return this.configs.has(token);
+    }
+
+    /**
+     * Resolves a token to return instance and its effective scope.
+     */
+    private resolveInternal<T>(token: Token<T>, requestLocals?: Map<Token, any>): { instance: T, scope: Scope } {
+        // 1. Check Request Cache
+        if (requestLocals?.has(token)) {
+            return { instance: requestLocals.get(token), scope: Scope.REQUEST };
+        }
+
+        // 2. Check Singleton Cache
+        const cached = this.instances.get(token);
+        if (cached !== undefined) {
+            return { instance: cached, scope: Scope.SINGLETON };
+        }
+
+        const config = this.configs.get(token);
+
+        if (!config) {
+            throw new Error(`Provider not found: ${token.name}`);
+        }
+
+        // 3. Create Instance with Scope Bubbling
+        const creation = this.createInstance(config, requestLocals);
+
+        // 4. Cache based on Effective Scope
+        if (creation.scope === Scope.SINGLETON) {
+            this.instances.set(token, creation.instance);
+        } else if (creation.scope === Scope.REQUEST && requestLocals) {
+            requestLocals.set(token, creation.instance);
+        }
+        // INSTANCE scope is never cached
+
+        return creation;
+    }
+
+    private createInstance(config: ProviderConfig, requestLocals?: Map<Token, any>): { instance: any, scope: Scope } {
+        const target = config.useClass ?? config.token;
+
+        if (this.resolving.has(target)) {
+            throw new Error(`Circular dependency detected: ${target.name}`);
+        }
+
+        this.resolving.add(target);
+
+        try {
+            const depsToken = this.getDependencies(target);
+
+            if (depsToken.length === 0) {
+                // No deps: Scope is as configured
+                return { instance: new target(), scope: config.scope || Scope.SINGLETON };
+            }
+
+            const args: any[] = [];
+            let effectiveScope = config.scope || Scope.SINGLETON;
+
+            for (const depToken of depsToken) {
+                const depResult = this.resolveInternal(depToken, requestLocals);
+                args.push(depResult.instance);
+
+                // Scope Bubbling Logic:
+                // If a dependency is REQUEST scoped, the parent MUST become REQUEST scoped (if it was Singleton)
+                // to avoid holding a stale reference to a request-bound instance.
+                if (depResult.scope === Scope.REQUEST && effectiveScope === Scope.SINGLETON) {
+                    effectiveScope = Scope.REQUEST;
+                }
+
+                // Note: INSTANCE scope dependencies do not force bubbling because they are transient and safe to hold (usually),
+                // unless semantic logic dictates otherwise. For now, strictly bubbling REQUEST scope.
+            }
+
+            return { instance: new target(...args), scope: effectiveScope };
+        } finally {
+            this.resolving.delete(target);
+        }
+    }
+
+    private getDependencies(target: Token): Token[] {
+        const types = Reflect.getMetadata('design:paramtypes', target) || [];
+        return types.filter((t: any) => t && typeof t === 'function' && !this.isPrimitive(t));
+    }
+
+    private isPrimitive(type: any): boolean {
+        return type === String || type === Number || type === Boolean || type === Object || type === Array || type === Symbol;
+    }
+
+    private normalizeConfig<T>(config: ProviderConfig<T> | Token<T>): ProviderConfig<T> {
+        if (typeof config === 'function') {
+            return {
+                token: config,
+                useClass: config,
+                scope: Scope.SINGLETON
+            };
+        }
+
+        return {
+            ...config,
+            useClass: config.useClass ?? config.token,
+            scope: config.scope ?? Scope.SINGLETON
+        };
+    }
+
+    clear(): void {
+        this.configs.clear();
+        this.instances.clear();
+    }
+}