alepha 0.15.0 → 0.15.2

package/dist/server/rate-limit/index.d.ts

@@ -1,7 +1,7 @@
 import * as alepha1 from "alepha";
 import { KIND, Primitive, Static } from "alepha";
 import { ServerRequest, ServerRouterProvider } from "alepha/server";
-import * as alepha_cache0 from "alepha/cache";
+import { CacheProvider } from "alepha/cache";
 import * as alepha_logger0 from "alepha/logger";
 
 //#region ../../src/server/rate-limit/providers/ServerRateLimitProvider.d.ts
@@ -34,40 +34,35 @@ declare class ServerRateLimitProvider {
     RATE_LIMIT_WINDOW_MS: number;
     RATE_LIMIT_MAX_REQUESTS: number;
   };
-  protected readonly cache: alepha_cache0.CachePrimitiveFn<RateLimitData, any[]>;
+  protected readonly cacheProvider: CacheProvider;
   protected readonly globalOptions: Readonly<{
     windowMs?: number | undefined;
     max?: number | undefined;
     skipFailedRequests?: boolean | undefined;
     skipSuccessfulRequests?: boolean | undefined;
   }>;
+  protected static readonly CACHE_NAME = "rate-limit";
   /**
-       * Registered rate limit configurations with their path patterns
-       */
+   * Registered rate limit configurations with their path patterns
+   */
   readonly registeredConfigs: RateLimitPrimitiveOptions[];
   /**
-       * Register a rate limit configuration (called by primitives)
-       */
+   * Register a rate limit configuration (called by primitives)
+   */
   registerRateLimit(config: RateLimitPrimitiveOptions): void;
   protected readonly onStart: alepha1.HookPrimitive<"start">;
   readonly onRequest: alepha1.HookPrimitive<"server:onRequest">;
   readonly onActionRequest: alepha1.HookPrimitive<"action:onRequest">;
   /**
-       * Build complete rate limit options by merging with global defaults
-       */
+   * Build complete rate limit options by merging with global defaults
+   */
   protected buildRateLimitOptions(config: RateLimitPrimitiveOptions): RateLimitOptions;
   /**
-       * Set rate limit headers on the response
-       */
+   * Set rate limit headers on the response
+   */
   protected setRateLimitHeaders(request: ServerRequest, result: RateLimitResult): void;
   checkLimit(req: ServerRequest, options?: RateLimitOptions): Promise<RateLimitResult>;
   protected generateKey(req: ServerRequest): string;
-  protected getClientIP(req: ServerRequest): string;
-}
-interface RateLimitData {
-  count: number;
-  windowStart: number;
-  hits: number[];
 }
 //#endregion
 //#region ../../src/server/rate-limit/primitives/$rateLimit.d.ts
@@ -102,9 +97,13 @@ declare const $rateLimit: {
   [KIND]: typeof RateLimitPrimitive;
 };
 interface RateLimitPrimitiveOptions extends RateLimitOptions {
-  /** Name identifier for this rate limit (default: property key) */
+  /**
+   * Name identifier for this rate limit (default: property key).
+   */
   name?: string;
-  /** Path patterns to match (supports wildcards like /api/*) */
+  /**
+   * Path patterns to match (supports wildcards like /api/*).
+   */
   paths?: string[];
 }
 interface AbstractRateLimitPrimitive {
@@ -117,8 +116,8 @@ declare class RateLimitPrimitive extends Primitive<RateLimitPrimitiveOptions> im
   get name(): string;
   protected onInit(): void;
   /**
-       * Checks rate limit for the given request using this primitive's configuration.
-       */
+   * Checks rate limit for the given request using this primitive's configuration.
+   */
   check(request: ServerRequest, options?: RateLimitOptions): Promise<RateLimitResult>;
 }
 //#endregion
@@ -126,55 +125,51 @@ declare class RateLimitPrimitive extends Primitive<RateLimitPrimitiveOptions> im
 declare module "alepha/server" {
   interface ActionPrimitiveOptions<TConfig> {
     /**
-             * Rate limiting configuration for this action.
-             * When specified, the action will be rate limited according to these settings.
-             */
+     * Rate limiting configuration for this action.
+     * When specified, the action will be rate limited according to these settings.
+     */
     rateLimit?: RateLimitOptions;
   }
   interface ServerRoute {
     /**
-             * Route-specific rate limit configuration.
-             * If set, overrides the global rate limit options for this route.
-             */
+     * Route-specific rate limit configuration.
+     * If set, overrides the global rate limit options for this route.
+     */
     rateLimit?: RateLimitOptions;
   }
 }
 interface RateLimitOptions {
-  /** Maximum number of requests per window (default: 100) */
+  /**
+   * Maximum number of requests per window (default: 100).
+   */
   max?: number;
-  /** Window duration in milliseconds (default: 15 minutes) */
+  /**
+   * Window duration in milliseconds (default: 15 minutes).
+   */
   windowMs?: number;
-  /** Custom key generator function */
+  /**
+   * Custom key generator function.
+   */
   keyGenerator?: (req: any) => string;
-  /** Skip rate limiting for failed requests */
+  /**
+   * Skip rate limiting for failed requests.
+   */
   skipFailedRequests?: boolean;
-  /** Skip rate limiting for successful requests */
+  /**
+   * Skip rate limiting for successful requests.
+   */
   skipSuccessfulRequests?: boolean;
 }
 /**
- * Provides rate limiting capabilities for server routes and actions with configurable limits and windows.
- *
- * The server-rate-limit module enables per-route and per-action rate limiting using either:
- * - The `$rateLimit` primitive with `paths` option for path-based rate limiting
- * - The `rateLimit` option in action primitives for action-specific limiting
- *
- * It offers sliding window rate limiting, custom key generation, and seamless integration with server routes.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * @example
- * ```ts
- * import { $rateLimit, AlephaServerRateLimit } from "alepha/server/rate-limit";
+ * Request rate limiting on actions.
  *
- * class ApiService {
- *   // Path-specific rate limiting
- *   apiRateLimit = $rateLimit({
- *     paths: ["/api/*"],
- *     max: 100,
- *     windowMs: 15 * 60 * 1000, // 15 minutes
- *   });
- * }
- * ```
+ * **Features:**
+ * - Rate limit configuration per action
  *
- * @see {@link $rateLimit}
  * @module alepha.server.rate-limit
  */
 declare const AlephaServerRateLimit: alepha1.Service<alepha1.Module>;

package/dist/server/rate-limit/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/server/rate-limit/providers/ServerRateLimitProvider.ts","../../../src/server/rate-limit/primitives/$rateLimit.ts","../../../src/server/rate-limit/index.ts"],"mappings":";;;;;;;UAaiB,eAAA;EAAA,OAAA;EAAA,KAAA;EAAA,SAAA;EAAA,SAAA;EAAA,UAAA;AAAA;AAAA;AAWjB;;AAXiB,cAWJ,gBAAA,EAAgB,OAAA,CAAA,IAAA,SAAA,OAAA;EAAA,QAAA,oBAyB3B,OAAA,CAAA,OAAA;EAAA,GAAA;;;;KAEU,oBAAA,GAAuB,MAAA,QAAc,gBAAA,CAAiB,MAAA;AAAA;EAAA,UAAA,KAAA;IAAA,CAI7D,gBAAA,CAAiB,GAAA,GAAM,oBAAA;EAAA;AAAA;AAAA,cAiBf,uBAAA;EAAA,mBAAA,GAAA,EAAuB,cAAA,CACZ,MAAA;EAAA,mBAAA,oBAAA,EACiB,oBAAA;EAAA,mBAAA,GAAA;IAAA,oBAAA;IAAA,uBAAA;EAAA;EAAA,mBAAA,KAAA,EAGf,aAAA,CAAA,gBAAA,CAAA,aAAA;EAAA,mBAAA,aAAA,EAKQ,QAAA;IAAA,QAAA;IAAA,GAAA;IAAA,kBAAA;IAAA,sBAAA;EAAA;EAAA;;;EAAA,SAAA,iBAAA,EAKG,yBAAA;EAAA;;;EAAA,kBAAA,MAAA,EAKF,yBAAA;EAAA,mBAAA,OAAA,EAAyB,OAAA,CAIhC,aAAA;EAAA,SAAA,SAAA,EAAA,OAAA,CAuBD,aAAA;EAAA,SAAA,eAAA,EAAA,OAAA,CAuBM,aAAA;EAAA;;;EAAA,UAAA,sBAAA,MAAA,EA4BrB,yBAAA,GACP,gBAAA;EAAA;;;EAAA,UAAA,oBAAA,OAAA,EAiBQ,aAAA,EAAA,MAAA,EACD,eAAA;EAAA,WAAA,GAAA,EAkBH,aAAA,EAAA,OAAA,GACI,gBAAA,GACR,OAAA,CAAQ,eAAA;EAAA,UAAA,YAAA,GAAA,EAiDgB,aAAA;EAAA,UAAA,YAAA,GAAA,EAMA,aAAA;AAAA;AAAA,UAanB,aAAA;EAAA,KAAA;EAAA,WAAA;EAAA,IAAA;AAAA;;;;ACnPV;;;;;;AAQA;AAOA;;;;;;;AASA;;;;;;;;;;;cAxBa,UAAA;EAAA,CAAA,OAAA,GACF,yBAAA,GACR,0BAAA;EAAA;;UAMc,yBAAA,SAAkC,gBAAA;EAAA;EAAA,IAAA;EAAA;EAAA,KAAA;AAAA;AAAA,UAOlC,0BAAA;EAAA,SAAA,IAAA;EAAA,SAAA,OAAA,EAEG,yBAAA;EAAA,KAAA,CAAA,OAAA,EAEP,aAAA,EAAA,OAAA,GACC,gBAAA,GACT,OAAA,CAAQ,eAAA;AAAA;AAAA,cAGA,kBAAA,SACH,SAAA,CAAU,yBAAA,aACP,0BAAA;EAAA,mBAAA,uBAAA,EAE+B,uBAAA;EAAA,IAAA,KAAA;EAAA,UAAA,OAAA;EAAA;;;EAAA,MAAA,OAAA,EAe/B,aAAA,EAAA,OAAA,GACC,gBAAA,GACT,OAAA,CAAQ,eAAA;AAAA;;;;;;ACvE0C;;;gBAUvC,gBAAA;EAAA;EAAA,UAAA,WAAA;IAAA;;;AAchB;IAdgB,SAAA,GAQA,gBAAA;EAAA;AAAA;AAAA,UAMC,gBAAA;EAAA;EAAA,GAAA;EAAA;EAAA,QAAA;EAAA;EAAA,YAAA,IAAA,GAAA;EAAA;EAAA,kBAAA;EAAA;EAAA,sBAAA;AAAA;AAAA;AAuCjB;;;;;;;;;;;;;;;;;;;;;;;;;AAvCiB,cAuCJ,qBAAA,EAAqB,OAAA,CAAA,OAAA,CAIhC,OAAA,CAJgC,MAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/server/rate-limit/providers/ServerRateLimitProvider.ts","../../../src/server/rate-limit/primitives/$rateLimit.ts","../../../src/server/rate-limit/index.ts"],"mappings":";;;;;;;UAaiB,eAAA;EACf,OAAA;EACA,KAAA;EACA,SAAA;EACA,SAAA;EACA,UAAA;AAAA;;;;cAMW,gBAAA,EAAgB,OAAA,CAAA,IAAA,SAAA,OAAA;8BAyB3B,OAAA,CAAA,OAAA;;;;;KAEU,oBAAA,GAAuB,MAAA,QAAc,gBAAA,CAAiB,MAAA;AAAA;EAAA,UAGtD,KAAA;IAAA,CACP,gBAAA,CAAiB,GAAA,GAAM,oBAAA;EAAA;AAAA;AAAA,cAiBf,uBAAA;EAAA,mBACQ,GAAA,EADe,cAAA,CACZ,MAAA;EAAA,mBACH,oBAAA,EAAoB,oBAAA;EAAA,mBACpB,GAAA;;;;qBACA,aAAA,EAAa,aAAA;EAAA,mBACb,aAAA,EAAa,QAAA;;;;;;4BAEN,UAAA;;;;WAKV,iBAAA,EAAmB,yBAAA;;;;EAK5B,iBAAA,CAAkB,MAAA,EAAQ,yBAAA;EAAA,mBAId,OAAA,EAJuC,OAAA,CAIhC,aAAA;EAAA,SAuBV,SAAA,EAvBU,OAAA,CAuBD,aAAA;EAAA,SAuBT,eAAA,EAvBS,OAAA,CAuBM,aAAA;EAxFE;;;EAAA,UAmHvB,qBAAA,CACR,MAAA,EAAQ,yBAAA,GACP,gBAAA;EArHmE;AAAE;;EAAF,UAqI5D,mBAAA,CACR,OAAA,EAAS,aAAA,EACT,MAAA,EAAQ,eAAA;EAiBG,UAAA,CACX,GAAA,EAAK,aAAA,EACL,OAAA,GAAS,gBAAA,GACR,OAAA,CAAQ,eAAA;EAAA,UAqCD,WAAA,CAAY,GAAA,EAAK,aAAA;AAAA;;;;;;AAtO7B;;;;;;;;;;;AAWA;;;;;;;;;;;;cCUa,UAAA;EAAA,WACF,yBAAA,GACR,0BAAA;EAAA;;UAMc,yBAAA,SAAkC,gBAAA;;;;EAIjD,IAAA;;;;EAIA,KAAA;AAAA;AAAA,UAGe,0BAAA;EAAA,SACN,IAAA;EAAA,SACA,OAAA,EAAS,yBAAA;EAClB,KAAA,CACE,OAAA,EAAS,aAAA,EACT,OAAA,GAAU,gBAAA,GACT,OAAA,CAAQ,eAAA;AAAA;AAAA,cAGA,kBAAA,SACH,SAAA,CAAU,yBAAA,aACP,0BAAA;EAAA,mBAEQ,uBAAA,EAAuB,uBAAA;EAAA,IAE/B,IAAA,CAAA;EAAA,UAID,MAAA,CAAA;EDrBuB;;;EC6BpB,KAAA,CACX,OAAA,EAAS,aAAA,EACT,OAAA,GAAU,gBAAA,GACT,OAAA,CAAQ,eAAA;AAAA;;;;YCtED,sBAAA;;;;AFAZ;IEKI,SAAA,GAAY,gBAAA;EAAA;EAAA,UAGJ,WAAA;IFPV;;;;IEYE,SAAA,GAAY,gBAAA;EAAA;AAAA;AAAA,UAMC,gBAAA;EFiBf;;;EEbA,GAAA;;;;EAIA,QAAA;;;;EAIA,YAAA,IAAgB,GAAA;EFpBW;;;EEwB3B,kBAAA;;;;EAIA,sBAAA;AAAA;;;;;;;;;;AFDF;;;cEgBa,qBAAA,EAAqB,OAAA,CAAA,OAAA,CAIhC,OAAA,CAJgC,MAAA"}

package/dist/server/rate-limit/index.js

@@ -1,6 +1,6 @@
 import { $atom, $env, $hook, $inject, $module, $use, KIND, Primitive, createPrimitive, t } from "alepha";
 import { AlephaServer, HttpError, ServerRouterProvider } from "alepha/server";
-import { $cache } from "alepha/cache";
+import { CacheProvider } from "alepha/cache";
 import { $logger } from "alepha/logger";
 
 //#region ../../src/server/rate-limit/providers/ServerRateLimitProvider.ts
@@ -27,15 +27,13 @@ const envSchema = t.object({
 		description: "Maximum requests per window"
 	})
 });
-var ServerRateLimitProvider = class {
+var ServerRateLimitProvider = class ServerRateLimitProvider {
 	log = $logger();
 	serverRouterProvider = $inject(ServerRouterProvider);
 	env = $env(envSchema);
-	cache = $cache({
-		name: "server-rate-limit",
-		ttl: [this.env.RATE_LIMIT_WINDOW_MS, "milliseconds"]
-	});
+	cacheProvider = $inject(CacheProvider);
 	globalOptions = $use(rateLimitOptions);
+	static CACHE_NAME = "rate-limit";
 	/**
 	* Registered rate limit configurations with their path patterns
 	*/
@@ -104,45 +102,24 @@ var ServerRateLimitProvider = class {
 	async checkLimit(req, options = {}) {
 		const windowMs = options.windowMs ?? this.env.RATE_LIMIT_WINDOW_MS;
 		const max = options.max ?? this.env.RATE_LIMIT_MAX_REQUESTS;
-		const key = this.generateKey(req);
+		const baseKey = this.generateKey(req);
 		const now = Date.now();
-		const windowStart = now - windowMs;
-		const currentData = await this.cache.get(key) || {
-			count: 0,
-			windowStart: now,
-			hits: []
-		};
-		const validHits = currentData.hits.filter((hit) => hit >= windowStart);
-		const allowed = validHits.length < max;
-		const remaining = Math.max(0, max - validHits.length);
-		const resetTime = Math.max(...validHits, windowStart) + windowMs;
-		if (allowed) {
-			validHits.push(now);
-			await this.cache.set(key, {
-				count: validHits.length,
-				windowStart: Math.min(currentData.windowStart, windowStart),
-				hits: validHits
-			});
-		}
+		const windowStart = Math.floor(now / windowMs) * windowMs;
+		const resetTime = windowStart + windowMs;
+		const key = `${baseKey}:${windowStart}`;
+		const count = await this.cacheProvider.incr(ServerRateLimitProvider.CACHE_NAME, key, 1);
+		const allowed = count <= max;
 		const result = {
 			allowed,
 			limit: max,
-			remaining: allowed ? remaining - 1 : remaining,
+			remaining: Math.max(0, max - count),
 			resetTime
 		};
 		if (!allowed) result.retryAfter = Math.ceil((resetTime - now) / 1e3);
 		return result;
 	}
 	generateKey(req) {
-		return `ip:${this.getClientIP(req)}`;
-	}
-	getClientIP(req) {
-		const forwarded = req.headers?.["x-forwarded-for"];
-		if (forwarded) {
-			const firstIp = forwarded.split(",")[0].trim();
-			if (firstIp) return firstIp;
-		}
-		return req.ip || "unknown";
+		return `ip:${req.ip || "unknown"}`;
 	}
 };
 
@@ -201,29 +178,15 @@ $rateLimit[KIND] = RateLimitPrimitive;
 //#endregion
 //#region ../../src/server/rate-limit/index.ts
 /**
-* Provides rate limiting capabilities for server routes and actions with configurable limits and windows.
-*
-* The server-rate-limit module enables per-route and per-action rate limiting using either:
-* - The `$rateLimit` primitive with `paths` option for path-based rate limiting
-* - The `rateLimit` option in action primitives for action-specific limiting
+* | type | quality | stability |
+* |------|---------|-----------|
+* | backend | standard | stable |
 *
-* It offers sliding window rate limiting, custom key generation, and seamless integration with server routes.
-*
-* @example
-* ```ts
-* import { $rateLimit, AlephaServerRateLimit } from "alepha/server/rate-limit";
+* Request rate limiting on actions.
 *
-* class ApiService {
-*   // Path-specific rate limiting
-*   apiRateLimit = $rateLimit({
-*     paths: ["/api/*"],
-*     max: 100,
-*     windowMs: 15 * 60 * 1000, // 15 minutes
-*   });
-* }
-* ```
+* **Features:**
+* - Rate limit configuration per action
 *
-* @see {@link $rateLimit}
 * @module alepha.server.rate-limit
 */
 const AlephaServerRateLimit = $module({

package/dist/server/rate-limit/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/server/rate-limit/providers/ServerRateLimitProvider.ts","../../../src/server/rate-limit/primitives/$rateLimit.ts","../../../src/server/rate-limit/index.ts"],"sourcesContent":["import { $atom, $env, $hook, $inject, $use, type Static, t } from \"alepha\";\nimport { $cache } from \"alepha/cache\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  HttpError,\n  type ServerRequest,\n  ServerRouterProvider,\n} from \"alepha/server\";\nimport type { RateLimitOptions } from \"../index.ts\";\nimport type { RateLimitPrimitiveOptions } from \"../primitives/$rateLimit.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface RateLimitResult {\n  allowed: boolean;\n  limit: number;\n  remaining: number;\n  resetTime: number;\n  retryAfter?: number;\n}\n\n/**\n * Rate limit configuration atom (global defaults)\n */\nexport const rateLimitOptions = $atom({\n  name: \"alepha.server.rate-limit.options\",\n  schema: t.object({\n    windowMs: t.optional(\n      t.number({\n        description: \"Window duration in milliseconds\",\n      }),\n    ),\n    max: t.optional(\n      t.number({\n        description: \"Maximum number of requests per window\",\n      }),\n    ),\n    skipFailedRequests: t.optional(\n      t.boolean({\n        description: \"Skip rate limiting for failed requests\",\n      }),\n    ),\n    skipSuccessfulRequests: t.optional(\n      t.boolean({\n        description: \"Skip rate limiting for successful requests\",\n      }),\n    ),\n  }),\n  default: {},\n});\n\nexport type RateLimitAtomOptions = Static<typeof rateLimitOptions.schema>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [rateLimitOptions.key]: RateLimitAtomOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nconst envSchema = t.object({\n  RATE_LIMIT_WINDOW_MS: t.number({\n    default: 15 * 60 * 1000, // 15 minutes\n    description: \"Rate limit window in milliseconds\",\n  }),\n  RATE_LIMIT_MAX_REQUESTS: t.number({\n    default: 100,\n    description: \"Maximum requests per window\",\n  }),\n});\n\nexport class ServerRateLimitProvider {\n  protected readonly log = $logger();\n  protected readonly serverRouterProvider = $inject(ServerRouterProvider);\n  protected readonly env = $env(envSchema);\n\n  protected readonly cache = $cache<RateLimitData>({\n    name: \"server-rate-limit\",\n    ttl: [this.env.RATE_LIMIT_WINDOW_MS, \"milliseconds\"],\n  });\n\n  protected readonly globalOptions = $use(rateLimitOptions);\n\n  /**\n   * Registered rate limit configurations with their path patterns\n   */\n  public readonly registeredConfigs: RateLimitPrimitiveOptions[] = [];\n\n  /**\n   * Register a rate limit configuration (called by primitives)\n   */\n  public registerRateLimit(config: RateLimitPrimitiveOptions): void {\n    this.registeredConfigs.push(config);\n  }\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      // Apply path-specific rate limit configs to routes\n      for (const config of this.registeredConfigs) {\n        if (config.paths) {\n          for (const pattern of config.paths) {\n            const matchedRoutes = this.serverRouterProvider.getRoutes(pattern);\n            for (const route of matchedRoutes) {\n              route.rateLimit = this.buildRateLimitOptions(config);\n            }\n          }\n        }\n      }\n\n      if (this.registeredConfigs.length > 0) {\n        this.log.info(\n          `Initialized with ${this.registeredConfigs.length} registered rate-limit configurations.`,\n        );\n      }\n    },\n  });\n\n  public readonly onRequest = $hook({\n    on: \"server:onRequest\",\n    handler: async ({ route, request }) => {\n      // Use route-specific rate limit if defined, otherwise use global options\n      const rateLimitConfig = route.rateLimit ?? this.globalOptions;\n\n      // Skip if no rate limiting configured\n      if (!rateLimitConfig.max && !rateLimitConfig.windowMs) {\n        return;\n      }\n\n      const result = await this.checkLimit(request, rateLimitConfig);\n      this.setRateLimitHeaders(request, result);\n\n      if (!result.allowed) {\n        throw new HttpError({\n          status: 429,\n          message: \"Too Many Requests\",\n        });\n      }\n    },\n  });\n\n  public readonly onActionRequest = $hook({\n    on: \"action:onRequest\",\n    handler: async ({ action, request }) => {\n      // Check if this action has rate limiting enabled\n      const rateLimit = action.options?.rateLimit;\n      if (!rateLimit) {\n        return; // No rate limiting for this action\n      }\n\n      const result = await this.checkLimit(request, rateLimit);\n\n      if (!result.allowed) {\n        // Actions are internal - don't set HTTP headers\n        // Only throw error to prevent action execution\n        throw new HttpError({\n          status: 429,\n          message: \"Too Many Requests\",\n        });\n      }\n\n      // Action allowed - no headers to set since actions are internal\n    },\n  });\n\n  /**\n   * Build complete rate limit options by merging with global defaults\n   */\n  protected buildRateLimitOptions(\n    config: RateLimitPrimitiveOptions,\n  ): RateLimitOptions {\n    return {\n      max: config.max ?? this.globalOptions.max,\n      windowMs: config.windowMs ?? this.globalOptions.windowMs,\n      keyGenerator: config.keyGenerator,\n      skipFailedRequests:\n        config.skipFailedRequests ?? this.globalOptions.skipFailedRequests,\n      skipSuccessfulRequests:\n        config.skipSuccessfulRequests ??\n        this.globalOptions.skipSuccessfulRequests,\n    };\n  }\n\n  /**\n   * Set rate limit headers on the response\n   */\n  protected setRateLimitHeaders(\n    request: ServerRequest,\n    result: RateLimitResult,\n  ): void {\n    request.reply.setHeader(\"X-RateLimit-Limit\", result.limit.toString());\n    request.reply.setHeader(\n      \"X-RateLimit-Remaining\",\n      result.remaining.toString(),\n    );\n    request.reply.setHeader(\n      \"X-RateLimit-Reset\",\n      Math.ceil(result.resetTime / 1000).toString(),\n    );\n\n    if (!result.allowed && result.retryAfter) {\n      request.reply.setHeader(\"Retry-After\", result.retryAfter.toString());\n    }\n  }\n\n  public async checkLimit(\n    req: ServerRequest,\n    options: RateLimitOptions = {},\n  ): Promise<RateLimitResult> {\n    const windowMs = options.windowMs ?? this.env.RATE_LIMIT_WINDOW_MS;\n    const max = options.max ?? this.env.RATE_LIMIT_MAX_REQUESTS;\n    const key = this.generateKey(req);\n\n    const now = Date.now();\n    const windowStart = now - windowMs;\n\n    // Get current rate limit data\n    const currentData = (await this.cache.get(key)) || {\n      count: 0,\n      windowStart: now,\n      hits: [],\n    };\n\n    // Clean old hits outside the current window\n    const validHits = currentData.hits.filter(\n      (hit: number) => hit >= windowStart,\n    );\n\n    // Check if limit exceeded\n    const allowed = validHits.length < max;\n    const remaining = Math.max(0, max - validHits.length);\n    const resetTime = Math.max(...validHits, windowStart) + windowMs;\n\n    // If allowed, record this request\n    if (allowed) {\n      validHits.push(now);\n      await this.cache.set(key, {\n        count: validHits.length,\n        windowStart: Math.min(currentData.windowStart, windowStart),\n        hits: validHits,\n      });\n    }\n\n    const result: RateLimitResult = {\n      allowed,\n      limit: max,\n      remaining: allowed ? remaining - 1 : remaining,\n      resetTime,\n    };\n\n    if (!allowed) {\n      result.retryAfter = Math.ceil((resetTime - now) / 1000);\n    }\n\n    return result;\n  }\n\n  protected generateKey(req: ServerRequest): string {\n    // Default to IP-based rate limiting\n    const ip = this.getClientIP(req);\n    return `ip:${ip}`;\n  }\n\n  protected getClientIP(req: ServerRequest): string {\n    // Check x-forwarded-for header first (for proxies/load balancers)\n    const forwarded = req.headers?.[\"x-forwarded-for\"];\n    if (forwarded) {\n      // x-forwarded-for can contain multiple IPs, get the first one (original client)\n      const firstIp = forwarded.split(\",\")[0].trim();\n      if (firstIp) return firstIp;\n    }\n\n    return req.ip || \"unknown\";\n  }\n}\n\ninterface RateLimitData {\n  count: number;\n  windowStart: number;\n  hits: number[];\n}\n","import { $inject, createPrimitive, KIND, Primitive } from \"alepha\";\nimport type { ServerRequest } from \"alepha/server\";\nimport type { RateLimitOptions } from \"../index.ts\";\nimport {\n  type RateLimitResult,\n  ServerRateLimitProvider,\n} from \"../providers/ServerRateLimitProvider.ts\";\n\n/**\n * Declares rate limiting for server routes or custom usage.\n * This primitive provides methods to check rate limits and configure behavior\n * within the server request/response cycle.\n *\n * @example\n * ```ts\n * class ApiService {\n *   // Apply rate limiting to specific paths\n *   apiRateLimit = $rateLimit({\n *     paths: [\"/api/*\"],\n *     max: 100,\n *     windowMs: 15 * 60 * 1000, // 15 minutes\n *   });\n *\n *   // Or use check() method for manual rate limiting\n *   customAction = $action({\n *     handler: async (req) => {\n *       const result = await this.apiRateLimit.check(req);\n *       if (!result.allowed) throw new Error(\"Rate limited\");\n *       return \"ok\";\n *     },\n *   });\n * }\n * ```\n */\nexport const $rateLimit = (\n  options: RateLimitPrimitiveOptions = {},\n): AbstractRateLimitPrimitive => {\n  return createPrimitive(RateLimitPrimitive, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface RateLimitPrimitiveOptions extends RateLimitOptions {\n  /** Name identifier for this rate limit (default: property key) */\n  name?: string;\n  /** Path patterns to match (supports wildcards like /api/*) */\n  paths?: string[];\n}\n\nexport interface AbstractRateLimitPrimitive {\n  readonly name: string;\n  readonly options: RateLimitPrimitiveOptions;\n  check(\n    request: ServerRequest,\n    options?: RateLimitOptions,\n  ): Promise<RateLimitResult>;\n}\n\nexport class RateLimitPrimitive\n  extends Primitive<RateLimitPrimitiveOptions>\n  implements AbstractRateLimitPrimitive\n{\n  protected readonly serverRateLimitProvider = $inject(ServerRateLimitProvider);\n\n  public get name(): string {\n    return this.options.name ?? `${this.config.propertyKey}`;\n  }\n\n  protected onInit() {\n    // Register this rate limit configuration with the provider\n    this.serverRateLimitProvider.registerRateLimit(this.options);\n  }\n\n  /**\n   * Checks rate limit for the given request using this primitive's configuration.\n   */\n  public async check(\n    request: ServerRequest,\n    options?: RateLimitOptions,\n  ): Promise<RateLimitResult> {\n    const mergedOptions = { ...this.options, ...options };\n    return this.serverRateLimitProvider.checkLimit(request, mergedOptions);\n  }\n}\n\n$rateLimit[KIND] = RateLimitPrimitive;\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\nimport { $rateLimit } from \"./primitives/$rateLimit.ts\";\nimport { ServerRateLimitProvider } from \"./providers/ServerRateLimitProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$rateLimit.ts\";\nexport * from \"./providers/ServerRateLimitProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha/server\" {\n  interface ActionPrimitiveOptions<TConfig> {\n    /**\n     * Rate limiting configuration for this action.\n     * When specified, the action will be rate limited according to these settings.\n     */\n    rateLimit?: RateLimitOptions;\n  }\n\n  interface ServerRoute {\n    /**\n     * Route-specific rate limit configuration.\n     * If set, overrides the global rate limit options for this route.\n     */\n    rateLimit?: RateLimitOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface RateLimitOptions {\n  /** Maximum number of requests per window (default: 100) */\n  max?: number;\n  /** Window duration in milliseconds (default: 15 minutes) */\n  windowMs?: number;\n  /** Custom key generator function */\n  keyGenerator?: (req: any) => string;\n  /** Skip rate limiting for failed requests */\n  skipFailedRequests?: boolean;\n  /** Skip rate limiting for successful requests */\n  skipSuccessfulRequests?: boolean;\n}\n\n/**\n * Provides rate limiting capabilities for server routes and actions with configurable limits and windows.\n *\n * The server-rate-limit module enables per-route and per-action rate limiting using either:\n * - The `$rateLimit` primitive with `paths` option for path-based rate limiting\n * - The `rateLimit` option in action primitives for action-specific limiting\n *\n * It offers sliding window rate limiting, custom key generation, and seamless integration with server routes.\n *\n * @example\n * ```ts\n * import { $rateLimit, AlephaServerRateLimit } from \"alepha/server/rate-limit\";\n *\n * class ApiService {\n *   // Path-specific rate limiting\n *   apiRateLimit = $rateLimit({\n *     paths: [\"/api/*\"],\n *     max: 100,\n *     windowMs: 15 * 60 * 1000, // 15 minutes\n *   });\n * }\n * ```\n *\n * @see {@link $rateLimit}\n * @module alepha.server.rate-limit\n */\nexport const AlephaServerRateLimit = $module({\n  name: \"alepha.server.rate-limit\",\n  primitives: [$rateLimit],\n  services: [AlephaServer, ServerRateLimitProvider],\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/server/rate-limit/providers/ServerRateLimitProvider.ts","../../../src/server/rate-limit/primitives/$rateLimit.ts","../../../src/server/rate-limit/index.ts"],"sourcesContent":["import { $atom, $env, $hook, $inject, $use, type Static, t } from \"alepha\";\nimport { CacheProvider } from \"alepha/cache\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  HttpError,\n  type ServerRequest,\n  ServerRouterProvider,\n} from \"alepha/server\";\nimport type { RateLimitOptions } from \"../index.ts\";\nimport type { RateLimitPrimitiveOptions } from \"../primitives/$rateLimit.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface RateLimitResult {\n  allowed: boolean;\n  limit: number;\n  remaining: number;\n  resetTime: number;\n  retryAfter?: number;\n}\n\n/**\n * Rate limit configuration atom (global defaults)\n */\nexport const rateLimitOptions = $atom({\n  name: \"alepha.server.rate-limit.options\",\n  schema: t.object({\n    windowMs: t.optional(\n      t.number({\n        description: \"Window duration in milliseconds\",\n      }),\n    ),\n    max: t.optional(\n      t.number({\n        description: \"Maximum number of requests per window\",\n      }),\n    ),\n    skipFailedRequests: t.optional(\n      t.boolean({\n        description: \"Skip rate limiting for failed requests\",\n      }),\n    ),\n    skipSuccessfulRequests: t.optional(\n      t.boolean({\n        description: \"Skip rate limiting for successful requests\",\n      }),\n    ),\n  }),\n  default: {},\n});\n\nexport type RateLimitAtomOptions = Static<typeof rateLimitOptions.schema>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [rateLimitOptions.key]: RateLimitAtomOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nconst envSchema = t.object({\n  RATE_LIMIT_WINDOW_MS: t.number({\n    default: 15 * 60 * 1000, // 15 minutes\n    description: \"Rate limit window in milliseconds\",\n  }),\n  RATE_LIMIT_MAX_REQUESTS: t.number({\n    default: 100,\n    description: \"Maximum requests per window\",\n  }),\n});\n\nexport class ServerRateLimitProvider {\n  protected readonly log = $logger();\n  protected readonly serverRouterProvider = $inject(ServerRouterProvider);\n  protected readonly env = $env(envSchema);\n  protected readonly cacheProvider = $inject(CacheProvider);\n  protected readonly globalOptions = $use(rateLimitOptions);\n\n  protected static readonly CACHE_NAME = \"rate-limit\";\n\n  /**\n   * Registered rate limit configurations with their path patterns\n   */\n  public readonly registeredConfigs: RateLimitPrimitiveOptions[] = [];\n\n  /**\n   * Register a rate limit configuration (called by primitives)\n   */\n  public registerRateLimit(config: RateLimitPrimitiveOptions): void {\n    this.registeredConfigs.push(config);\n  }\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      // Apply path-specific rate limit configs to routes\n      for (const config of this.registeredConfigs) {\n        if (config.paths) {\n          for (const pattern of config.paths) {\n            const matchedRoutes = this.serverRouterProvider.getRoutes(pattern);\n            for (const route of matchedRoutes) {\n              route.rateLimit = this.buildRateLimitOptions(config);\n            }\n          }\n        }\n      }\n\n      if (this.registeredConfigs.length > 0) {\n        this.log.info(\n          `Initialized with ${this.registeredConfigs.length} registered rate-limit configurations.`,\n        );\n      }\n    },\n  });\n\n  public readonly onRequest = $hook({\n    on: \"server:onRequest\",\n    handler: async ({ route, request }) => {\n      // Use route-specific rate limit if defined, otherwise use global options\n      const rateLimitConfig = route.rateLimit ?? this.globalOptions;\n\n      // Skip if no rate limiting configured\n      if (!rateLimitConfig.max && !rateLimitConfig.windowMs) {\n        return;\n      }\n\n      const result = await this.checkLimit(request, rateLimitConfig);\n      this.setRateLimitHeaders(request, result);\n\n      if (!result.allowed) {\n        throw new HttpError({\n          status: 429,\n          message: \"Too Many Requests\",\n        });\n      }\n    },\n  });\n\n  public readonly onActionRequest = $hook({\n    on: \"action:onRequest\",\n    handler: async ({ action, request }) => {\n      // Check if this action has rate limiting enabled\n      const rateLimit = action.options?.rateLimit;\n      if (!rateLimit) {\n        return; // No rate limiting for this action\n      }\n\n      const result = await this.checkLimit(request, rateLimit);\n\n      if (!result.allowed) {\n        // Actions are internal - don't set HTTP headers\n        // Only throw error to prevent action execution\n        throw new HttpError({\n          status: 429,\n          message: \"Too Many Requests\",\n        });\n      }\n\n      // Action allowed - no headers to set since actions are internal\n    },\n  });\n\n  /**\n   * Build complete rate limit options by merging with global defaults\n   */\n  protected buildRateLimitOptions(\n    config: RateLimitPrimitiveOptions,\n  ): RateLimitOptions {\n    return {\n      max: config.max ?? this.globalOptions.max,\n      windowMs: config.windowMs ?? this.globalOptions.windowMs,\n      keyGenerator: config.keyGenerator,\n      skipFailedRequests:\n        config.skipFailedRequests ?? this.globalOptions.skipFailedRequests,\n      skipSuccessfulRequests:\n        config.skipSuccessfulRequests ??\n        this.globalOptions.skipSuccessfulRequests,\n    };\n  }\n\n  /**\n   * Set rate limit headers on the response\n   */\n  protected setRateLimitHeaders(\n    request: ServerRequest,\n    result: RateLimitResult,\n  ): void {\n    request.reply.setHeader(\"X-RateLimit-Limit\", result.limit.toString());\n    request.reply.setHeader(\n      \"X-RateLimit-Remaining\",\n      result.remaining.toString(),\n    );\n    request.reply.setHeader(\n      \"X-RateLimit-Reset\",\n      Math.ceil(result.resetTime / 1000).toString(),\n    );\n\n    if (!result.allowed && result.retryAfter) {\n      request.reply.setHeader(\"Retry-After\", result.retryAfter.toString());\n    }\n  }\n\n  public async checkLimit(\n    req: ServerRequest,\n    options: RateLimitOptions = {},\n  ): Promise<RateLimitResult> {\n    const windowMs = options.windowMs ?? this.env.RATE_LIMIT_WINDOW_MS;\n    const max = options.max ?? this.env.RATE_LIMIT_MAX_REQUESTS;\n    const baseKey = this.generateKey(req);\n\n    const now = Date.now();\n    // Fixed window: round down to nearest window boundary\n    const windowStart = Math.floor(now / windowMs) * windowMs;\n    const resetTime = windowStart + windowMs;\n\n    // Include window timestamp in key for automatic expiration of old windows\n    const key = `${baseKey}:${windowStart}`;\n\n    // Atomic increment - returns the new count after incrementing\n    const count = await this.cacheProvider.incr(\n      ServerRateLimitProvider.CACHE_NAME,\n      key,\n      1,\n    );\n\n    const allowed = count <= max;\n    const remaining = Math.max(0, max - count);\n\n    const result: RateLimitResult = {\n      allowed,\n      limit: max,\n      remaining,\n      resetTime,\n    };\n\n    if (!allowed) {\n      result.retryAfter = Math.ceil((resetTime - now) / 1000);\n    }\n\n    return result;\n  }\n\n  protected generateKey(req: ServerRequest): string {\n    // Use req.ip which is resolved by ServerRequestParser with proper trust proxy handling\n    return `ip:${req.ip || \"unknown\"}`;\n  }\n}\n","import { $inject, createPrimitive, KIND, Primitive } from \"alepha\";\nimport type { ServerRequest } from \"alepha/server\";\nimport type { RateLimitOptions } from \"../index.ts\";\nimport {\n  type RateLimitResult,\n  ServerRateLimitProvider,\n} from \"../providers/ServerRateLimitProvider.ts\";\n\n/**\n * Declares rate limiting for server routes or custom usage.\n * This primitive provides methods to check rate limits and configure behavior\n * within the server request/response cycle.\n *\n * @example\n * ```ts\n * class ApiService {\n *   // Apply rate limiting to specific paths\n *   apiRateLimit = $rateLimit({\n *     paths: [\"/api/*\"],\n *     max: 100,\n *     windowMs: 15 * 60 * 1000, // 15 minutes\n *   });\n *\n *   // Or use check() method for manual rate limiting\n *   customAction = $action({\n *     handler: async (req) => {\n *       const result = await this.apiRateLimit.check(req);\n *       if (!result.allowed) throw new Error(\"Rate limited\");\n *       return \"ok\";\n *     },\n *   });\n * }\n * ```\n */\nexport const $rateLimit = (\n  options: RateLimitPrimitiveOptions = {},\n): AbstractRateLimitPrimitive => {\n  return createPrimitive(RateLimitPrimitive, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface RateLimitPrimitiveOptions extends RateLimitOptions {\n  /**\n   * Name identifier for this rate limit (default: property key).\n   */\n  name?: string;\n  /**\n   * Path patterns to match (supports wildcards like /api/*).\n   */\n  paths?: string[];\n}\n\nexport interface AbstractRateLimitPrimitive {\n  readonly name: string;\n  readonly options: RateLimitPrimitiveOptions;\n  check(\n    request: ServerRequest,\n    options?: RateLimitOptions,\n  ): Promise<RateLimitResult>;\n}\n\nexport class RateLimitPrimitive\n  extends Primitive<RateLimitPrimitiveOptions>\n  implements AbstractRateLimitPrimitive\n{\n  protected readonly serverRateLimitProvider = $inject(ServerRateLimitProvider);\n\n  public get name(): string {\n    return this.options.name ?? `${this.config.propertyKey}`;\n  }\n\n  protected onInit() {\n    // Register this rate limit configuration with the provider\n    this.serverRateLimitProvider.registerRateLimit(this.options);\n  }\n\n  /**\n   * Checks rate limit for the given request using this primitive's configuration.\n   */\n  public async check(\n    request: ServerRequest,\n    options?: RateLimitOptions,\n  ): Promise<RateLimitResult> {\n    const mergedOptions = { ...this.options, ...options };\n    return this.serverRateLimitProvider.checkLimit(request, mergedOptions);\n  }\n}\n\n$rateLimit[KIND] = RateLimitPrimitive;\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\nimport { $rateLimit } from \"./primitives/$rateLimit.ts\";\nimport { ServerRateLimitProvider } from \"./providers/ServerRateLimitProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$rateLimit.ts\";\nexport * from \"./providers/ServerRateLimitProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha/server\" {\n  interface ActionPrimitiveOptions<TConfig> {\n    /**\n     * Rate limiting configuration for this action.\n     * When specified, the action will be rate limited according to these settings.\n     */\n    rateLimit?: RateLimitOptions;\n  }\n\n  interface ServerRoute {\n    /**\n     * Route-specific rate limit configuration.\n     * If set, overrides the global rate limit options for this route.\n     */\n    rateLimit?: RateLimitOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface RateLimitOptions {\n  /**\n   * Maximum number of requests per window (default: 100).\n   */\n  max?: number;\n  /**\n   * Window duration in milliseconds (default: 15 minutes).\n   */\n  windowMs?: number;\n  /**\n   * Custom key generator function.\n   */\n  keyGenerator?: (req: any) => string;\n  /**\n   * Skip rate limiting for failed requests.\n   */\n  skipFailedRequests?: boolean;\n  /**\n   * Skip rate limiting for successful requests.\n   */\n  skipSuccessfulRequests?: boolean;\n}\n\n/**\n * | type | quality | stability |\n * |------|---------|-----------|\n * | backend | standard | stable |\n *\n * Request rate limiting on actions.\n *\n * **Features:**\n * - Rate limit configuration per action\n *\n * @module alepha.server.rate-limit\n */\nexport const AlephaServerRateLimit = $module({\n  name: \"alepha.server.rate-limit\",\n  primitives: [$rateLimit],\n  services: [AlephaServer, ServerRateLimitProvider],\n});\n"],"mappings":"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"}

package/dist/server/static/index.d.ts

@@ -1,9 +1,9 @@
 import * as alepha1 from "alepha";
-import { Alepha, KIND, Primitive } from "alepha";
+import { Alepha, Json, KIND, Primitive } from "alepha";
 import { ServerHandler, ServerRouterProvider } from "alepha/server";
 import { DateTimeProvider, DurationLike } from "alepha/datetime";
-import { FileDetector } from "alepha/file";
 import * as alepha_logger0 from "alepha/logger";
+import { Readable } from "node:stream";
 
 //#region ../../src/server/static/primitives/$serve.d.ts
 /**
@@ -15,76 +15,203 @@ declare const $serve: {
 };
 interface ServePrimitiveOptions {
   /**
-       * Prefix for the served path.
-       *
-       * @default "/"
-       */
+   * Prefix for the served path.
+   *
+   * @default "/"
+   */
   path?: string;
   /**
-       * Path to the directory to serve.
-       *
-       * @default process.cwd()
-       */
+   * Path to the directory to serve.
+   *
+   * @default process.cwd()
+   */
   root?: string;
   /**
-       * If true, primitive will be ignored.
-       *
-       * @default false
-       */
+   * If true, primitive will be ignored.
+   *
+   * @default false
+   */
   disabled?: boolean;
   /**
-       * Whether to keep dot files (e.g. `.gitignore`, `.env`) in the served directory.
-       *
-       * @default true
-       */
+   * Whether to keep dot files (e.g. `.gitignore`, `.env`) in the served directory.
+   *
+   * @default true
+   */
   ignoreDotEnvFiles?: boolean;
   /**
-       * Whether to use the index.html file when the path is a directory.
-       *
-       * @default true
-       */
+   * Whether to use the index.html file when the path is a directory.
+   *
+   * @default true
+   */
   indexFallback?: boolean;
   /**
-       * Force all requests "not found" to be served with the index.html file.
-       * This is useful for single-page applications (SPAs) that use client-side only routing.
-       */
+   * Force all requests "not found" to be served with the index.html file.
+   * This is useful for single-page applications (SPAs) that use client-side only routing.
+   */
   historyApiFallback?: boolean;
   /**
-       * Optional name of the primitive.
-       * This is used for logging and debugging purposes.
-       *
-       * @default Key name.
-       */
+   * Optional name of the primitive.
+   * This is used for logging and debugging purposes.
+   *
+   * @default Key name.
+   */
   name?: string;
   /**
-       * Whether to use cache control headers.
-       *
-       * @default {}
-       */
+   * Whether to use cache control headers.
+   *
+   * @default {}
+   */
   cacheControl?: Partial<CacheControlOptions> | false;
 }
 interface CacheControlOptions {
   /**
-       * Whether to use cache control headers.
-       *
-       * @default [.js, .css]
-       */
+   * Whether to use cache control headers.
+   *
+   * @default [.js, .css]
+   */
   fileTypes: string[];
   /**
-       * The maximum age of the cache in seconds.
-       *
-       * @default 60 * 60 * 24 * 2 // 2 days
-       */
+   * The maximum age of the cache in seconds.
+   *
+   * @default 60 * 60 * 24 * 2 // 2 days
+   */
   maxAge: DurationLike;
   /**
-       * Whether to use immutable cache control headers.
-       *
-       * @default true
-       */
+   * Whether to use immutable cache control headers.
+   *
+   * @default true
+   */
   immutable: boolean;
 }
 declare class ServePrimitive extends Primitive<ServePrimitiveOptions> {}
 //#endregion
+//#region ../../src/system/services/FileDetector.d.ts
+interface FileTypeResult {
+  /**
+   * The detected MIME type
+   */
+  mimeType: string;
+  /**
+   * The detected file extension
+   */
+  extension: string;
+  /**
+   * Whether the file type was verified by magic bytes
+   */
+  verified: boolean;
+  /**
+   * The stream (potentially wrapped to allow re-reading)
+   */
+  stream: Readable;
+}
+/**
+ * Service for detecting file types and getting content types.
+ *
+ * @example
+ * ```typescript
+ * const detector = alepha.inject(FileDetector);
+ *
+ * // Get content type from filename
+ * const mimeType = detector.getContentType("image.png"); // "image/png"
+ *
+ * // Detect file type by magic bytes
+ * const stream = createReadStream('image.png');
+ * const result = await detector.detectFileType(stream, 'image.png');
+ * console.log(result.mimeType); // 'image/png'
+ * console.log(result.verified); // true if magic bytes match
+ * ```
+ */
+declare class FileDetector {
+  /**
+   * Magic byte signatures for common file formats.
+   * Each signature is represented as an array of bytes or null (wildcard).
+   */
+  protected static readonly MAGIC_BYTES: Record<string, {
+    signature: (number | null)[];
+    mimeType: string;
+  }[]>;
+  /**
+   * All possible format signatures for checking against actual file content
+   */
+  protected static readonly ALL_SIGNATURES: {
+    signature: (number | null)[];
+    mimeType: string;
+    ext: string;
+  }[];
+  /**
+   * MIME type map for file extensions.
+   *
+   * Can be used to get the content type of file based on its extension.
+   * Feel free to add more mime types in your project!
+   */
+  static readonly mimeMap: Record<string, string>;
+  /**
+   * Reverse MIME type map for looking up extensions from MIME types.
+   * Prefers shorter, more common extensions when multiple exist.
+   */
+  protected static readonly reverseMimeMap: Record<string, string>;
+  /**
+   * Returns the file extension for a given MIME type.
+   *
+   * @param mimeType - The MIME type to look up
+   * @returns The file extension (without dot), or "bin" if not found
+   *
+   * @example
+   * ```typescript
+   * const detector = alepha.inject(FileDetector);
+   * const ext = detector.getExtensionFromMimeType("image/png"); // "png"
+   * const ext2 = detector.getExtensionFromMimeType("application/octet-stream"); // "bin"
+   * ```
+   */
+  getExtensionFromMimeType(mimeType: string): string;
+  /**
+   * Returns the content type of file based on its filename.
+   *
+   * @param filename - The filename to check
+   * @returns The MIME type
+   *
+   * @example
+   * ```typescript
+   * const detector = alepha.inject(FileDetector);
+   * const mimeType = detector.getContentType("image.png"); // "image/png"
+   * ```
+   */
+  getContentType(filename: string): string;
+  /**
+   * Detects the file type by checking magic bytes against the stream content.
+   *
+   * @param stream - The readable stream to check
+   * @param filename - The filename (used to get the extension)
+   * @returns File type information including MIME type, extension, and verification status
+   *
+   * @example
+   * ```typescript
+   * const detector = alepha.inject(FileDetector);
+   * const stream = createReadStream('image.png');
+   * const result = await detector.detectFileType(stream, 'image.png');
+   * console.log(result.mimeType); // 'image/png'
+   * console.log(result.verified); // true if magic bytes match
+   * ```
+   */
+  detectFileType(stream: Readable, filename: string): Promise<FileTypeResult>;
+  /**
+   * Reads all bytes from a stream and returns the first N bytes along with a new stream containing all data.
+   * This approach reads the entire stream upfront to avoid complex async handling issues.
+   *
+   * @protected
+   */
+  protected peekBytes(stream: Readable, numBytes: number): Promise<{
+    buffer: Buffer;
+    stream: Readable;
+  }>;
+  /**
+   * Checks if a buffer matches a magic byte signature.
+   *
+   * @protected
+   */
+  protected matchesSignature(buffer: Buffer, signature: (number | null)[]): boolean;
+}
+//#endregion
 //#region ../../src/server/static/providers/ServerStaticProvider.d.ts
 declare class ServerStaticProvider {
   protected readonly alepha: Alepha;
@@ -110,9 +237,15 @@ interface ServeDirectory {
 //#endregion
 //#region ../../src/server/static/index.d.ts
 /**
- * Create static file server with `$static()`.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
+ *
+ * Static file serving.
+ *
+ * **Features:**
+ * - Serve static files from directory
  *
- * @see {@link ServerStaticProvider}
  * @module alepha.server.static
  */
 declare const AlephaServerStatic: alepha1.Service<alepha1.Module>;