alepha 0.13.0 → 0.13.1

package/dist/server-proxy/index.d.cts

@@ -1,234 +0,0 @@
-import * as alepha1 from "alepha";
-import { Alepha, Async, Descriptor, KIND } from "alepha";
-import { ServerHandler, ServerRequest, ServerRouterProvider } from "alepha/server";
-import * as alepha_logger0 from "alepha/logger";
-
-//#region src/server-proxy/descriptors/$proxy.d.ts
-
-/**
- * Creates a proxy descriptor to forward requests to another server.
- *
- * This descriptor enables you to create reverse proxy functionality, allowing your Alepha server
- * to forward requests to other services while maintaining a unified API surface. It's particularly
- * useful for microservice architectures, API gateways, or when you need to aggregate multiple
- * services behind a single endpoint.
- *
- * **Key Features**
- *
- * - **Path-based routing**: Match specific paths or patterns to proxy
- * - **Dynamic targets**: Support both static and dynamic target resolution
- * - **Request/Response hooks**: Modify requests before forwarding and responses after receiving
- * - **URL rewriting**: Transform URLs before forwarding to the target
- * - **Conditional proxying**: Enable/disable proxies based on environment or conditions
- *
- * @example
- * **Basic proxy setup:**
- * ```ts
- * import { $proxy } from "alepha/server/proxy";
- *
- * class ApiGateway {
- *   // Forward all /api/* requests to external service
- *   api = $proxy({
- *     path: "/api/*",
- *     target: "https://api.example.com"
- *   });
- * }
- * ```
- *
- * @example
- * **Dynamic target with environment-based routing:**
- * ```ts
- * class ApiGateway {
- *   // Route to different environments based on configuration
- *   api = $proxy({
- *     path: "/api/*",
- *     target: () => process.env.NODE_ENV === "production"
- *       ? "https://api.prod.example.com"
- *       : "https://api.dev.example.com"
- *   });
- * }
- * ```
- *
- * @example
- * **Advanced proxy with request/response modification:**
- * ```ts
- * class SecureProxy {
- *   secure = $proxy({
- *     path: "/secure/*",
- *     target: "https://secure-api.example.com",
- *     beforeRequest: async (request, proxyRequest) => {
- *       // Add authentication headers
- *       proxyRequest.headers = {
- *         ...proxyRequest.headers,
- *         'Authorization': `Bearer ${await getServiceToken()}`,
- *         'X-Forwarded-For': request.headers['x-forwarded-for'] || request.ip
- *       };
- *     },
- *     afterResponse: async (request, proxyResponse) => {
- *       // Log response for monitoring
- *       console.log(`Proxied ${request.url} -> ${proxyResponse.status}`);
- *     },
- *     rewrite: (url) => {
- *       // Remove /secure prefix when forwarding
- *       url.pathname = url.pathname.replace('/secure', '');
- *     }
- *   });
- * }
- * ```
- *
- * @example
- * **Conditional proxy based on feature flags:**
- * ```ts
- * class FeatureProxy {
- *   newApi = $proxy({
- *     path: "/v2/*",
- *     target: "https://new-api.example.com",
- *     disabled: !process.env.ENABLE_V2_API // Disable if feature flag is off
- *   });
- * }
- * ```
- */
-declare const $proxy: {
-  (options: ProxyDescriptorOptions): ProxyDescriptor;
-  [KIND]: typeof ProxyDescriptor;
-};
-type ProxyDescriptorOptions = {
-  /**
-   * Path pattern to match for proxying requests.
-   *
-   * Supports wildcards and path parameters:
-   * - `/api/*` - Matches all paths starting with `/api/`
-   * - `/api/v1/*` - Matches all paths starting with `/api/v1/`
-   * - `/users/:id` - Matches `/users/123`, `/users/abc`, etc.
-   *
-   * @example "/api/*"
-   * @example "/secure/admin/*"
-   * @example "/users/:id/posts"
-   */
-  path: string;
-  /**
-   * Target URL to which matching requests should be forwarded.
-   *
-   * Can be either:
-   * - **Static string**: A fixed URL like `"https://api.example.com"`
-   * - **Dynamic function**: A function that returns the URL, enabling runtime target resolution
-   *
-   * The target URL will be combined with the remaining path from the original request.
-   *
-   * @example "https://api.example.com"
-   * @example () => process.env.API_URL || "http://localhost:3001"
-   */
-  target: string | (() => string);
-  /**
-   * Whether this proxy is disabled.
-   *
-   * When `true`, requests matching the path will not be proxied and will be handled
-   * by other routes or return 404. Useful for feature toggles or conditional proxying.
-   *
-   * @default false
-   * @example !process.env.ENABLE_PROXY
-   */
-  disabled?: boolean;
-  /**
-   * Hook called before forwarding the request to the target server.
-   *
-   * Use this to:
-   * - Add authentication headers
-   * - Modify request headers or body
-   * - Add request tracking/logging
-   * - Transform the request before forwarding
-   *
-   * @param request - The original incoming server request
-   * @param proxyRequest - The request that will be sent to the target (modifiable)
-   *
-   * @example
-   * ```ts
-   * beforeRequest: async (request, proxyRequest) => {
-   *   proxyRequest.headers = {
-   *     ...proxyRequest.headers,
-   *     'Authorization': `Bearer ${await getToken()}`,
-   *     'X-Request-ID': generateRequestId()
-   *   };
-   * }
-   * ```
-   */
-  beforeRequest?: (request: ServerRequest, proxyRequest: RequestInit) => Async<void>;
-  /**
-   * Hook called after receiving the response from the target server.
-   *
-   * Use this to:
-   * - Log response details for monitoring
-   * - Add custom headers to the response
-   * - Transform response data
-   * - Handle error responses
-   *
-   * @param request - The original incoming server request
-   * @param proxyResponse - The response received from the target server
-   *
-   * @example
-   * ```ts
-   * afterResponse: async (request, proxyResponse) => {
-   *   console.log(`Proxy ${request.method} ${request.url} -> ${proxyResponse.status}`);
-   *
-   *   if (!proxyResponse.ok) {
-   *     await logError(`Proxy error: ${proxyResponse.status}`, { request, response: proxyResponse });
-   *   }
-   * }
-   * ```
-   */
-  afterResponse?: (request: ServerRequest, proxyResponse: Response) => Async<void>;
-  /**
-   * Function to rewrite the URL before sending to the target server.
-   *
-   * Use this to:
-   * - Remove or add path prefixes
-   * - Transform path parameters
-   * - Modify query parameters
-   * - Change the URL structure entirely
-   *
-   * The function receives a mutable URL object and should modify it in-place.
-   *
-   * @param url - The URL object to modify (mutable)
-   *
-   * @example
-   * ```ts
-   * // Remove /api prefix when forwarding
-   * rewrite: (url) => {
-   *   url.pathname = url.pathname.replace('/api', '');
-   * }
-   * ```
-   *
-   * @example
-   * ```ts
-   * // Add version prefix
-   * rewrite: (url) => {
-   *   url.pathname = `/v2${url.pathname}`;
-   * }
-   * ```
-   */
-  rewrite?: (url: URL) => void;
-};
-declare class ProxyDescriptor extends Descriptor<ProxyDescriptorOptions> {}
-//#endregion
-//#region src/server-proxy/providers/ServerProxyProvider.d.ts
-declare class ServerProxyProvider {
-  protected readonly log: alepha_logger0.Logger;
-  protected readonly routerProvider: ServerRouterProvider;
-  protected readonly alepha: Alepha;
-  protected readonly configure: alepha1.HookDescriptor<"configure">;
-  createProxy(options: ProxyDescriptorOptions): void;
-  createProxyHandler(target: string, options: Omit<ProxyDescriptorOptions, "path">): ServerHandler;
-  private getRawRequestBody;
-}
-//#endregion
-//#region src/server-proxy/index.d.ts
-/**
- * Plugin for Alepha that provides a proxy server functionality.
- *
- * @see {@link $proxy}
- * @module alepha.server.proxy
- */
-declare const AlephaServerProxy: alepha1.Service<alepha1.Module>;
-//#endregion
-export { $proxy, AlephaServerProxy, ProxyDescriptor, ProxyDescriptorOptions, ServerProxyProvider };
-//# sourceMappingURL=index.d.cts.map

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

@@ -1,241 +0,0 @@
-let alepha = require("alepha");
-let alepha_server = require("alepha/server");
-let alepha_cache = require("alepha/cache");
-let alepha_logger = require("alepha/logger");
-
-//#region src/server-rate-limit/providers/ServerRateLimitProvider.ts
-/**
-* Rate limit configuration atom (global defaults)
-*/
-const rateLimitOptions = (0, alepha.$atom)({
-	name: "alepha.server.rate-limit.options",
-	schema: alepha.t.object({
-		windowMs: alepha.t.optional(alepha.t.number({ description: "Window duration in milliseconds" })),
-		max: alepha.t.optional(alepha.t.number({ description: "Maximum number of requests per window" })),
-		skipFailedRequests: alepha.t.optional(alepha.t.boolean({ description: "Skip rate limiting for failed requests" })),
-		skipSuccessfulRequests: alepha.t.optional(alepha.t.boolean({ description: "Skip rate limiting for successful requests" }))
-	}),
-	default: {}
-});
-const envSchema = alepha.t.object({
-	RATE_LIMIT_WINDOW_MS: alepha.t.number({
-		default: 900 * 1e3,
-		description: "Rate limit window in milliseconds"
-	}),
-	RATE_LIMIT_MAX_REQUESTS: alepha.t.number({
-		default: 100,
-		description: "Maximum requests per window"
-	})
-});
-var ServerRateLimitProvider = class {
-	log = (0, alepha_logger.$logger)();
-	serverRouterProvider = (0, alepha.$inject)(alepha_server.ServerRouterProvider);
-	env = (0, alepha.$env)(envSchema);
-	cache = (0, alepha_cache.$cache)({
-		name: "server-rate-limit",
-		ttl: [this.env.RATE_LIMIT_WINDOW_MS, "milliseconds"]
-	});
-	globalOptions = (0, alepha.$use)(rateLimitOptions);
-	/**
-	* Registered rate limit configurations with their path patterns
-	*/
-	registeredConfigs = [];
-	/**
-	* Register a rate limit configuration (called by descriptors)
-	*/
-	registerRateLimit(config) {
-		this.registeredConfigs.push(config);
-	}
-	onStart = (0, alepha.$hook)({
-		on: "start",
-		handler: async () => {
-			for (const config of this.registeredConfigs) if (config.paths) for (const pattern of config.paths) {
-				const matchedRoutes = this.serverRouterProvider.getRoutes(pattern);
-				for (const route of matchedRoutes) route.rateLimit = this.buildRateLimitOptions(config);
-			}
-			if (this.registeredConfigs.length > 0) this.log.info(`Initialized with ${this.registeredConfigs.length} registered rate-limit configurations.`);
-		}
-	});
-	onRequest = (0, alepha.$hook)({
-		on: "server:onRequest",
-		handler: async ({ route, request }) => {
-			const rateLimitConfig = route.rateLimit ?? this.globalOptions;
-			if (!rateLimitConfig.max && !rateLimitConfig.windowMs) return;
-			const result = await this.checkLimit(request, rateLimitConfig);
-			this.setRateLimitHeaders(request, result);
-			if (!result.allowed) throw new alepha_server.HttpError({
-				status: 429,
-				message: "Too Many Requests"
-			});
-		}
-	});
-	onActionRequest = (0, alepha.$hook)({
-		on: "action:onRequest",
-		handler: async ({ action, request }) => {
-			const rateLimit = action.options?.rateLimit;
-			if (!rateLimit) return;
-			if (!(await this.checkLimit(request, rateLimit)).allowed) throw new alepha_server.HttpError({
-				status: 429,
-				message: "Too Many Requests"
-			});
-		}
-	});
-	/**
-	* Build complete rate limit options by merging with global defaults
-	*/
-	buildRateLimitOptions(config) {
-		return {
-			max: config.max ?? this.globalOptions.max,
-			windowMs: config.windowMs ?? this.globalOptions.windowMs,
-			keyGenerator: config.keyGenerator,
-			skipFailedRequests: config.skipFailedRequests ?? this.globalOptions.skipFailedRequests,
-			skipSuccessfulRequests: config.skipSuccessfulRequests ?? this.globalOptions.skipSuccessfulRequests
-		};
-	}
-	/**
-	* Set rate limit headers on the response
-	*/
-	setRateLimitHeaders(request, result) {
-		request.reply.setHeader("X-RateLimit-Limit", result.limit.toString());
-		request.reply.setHeader("X-RateLimit-Remaining", result.remaining.toString());
-		request.reply.setHeader("X-RateLimit-Reset", Math.ceil(result.resetTime / 1e3).toString());
-		if (!result.allowed && result.retryAfter) request.reply.setHeader("Retry-After", result.retryAfter.toString());
-	}
-	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 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 result = {
-			allowed,
-			limit: max,
-			remaining: allowed ? remaining - 1 : remaining,
-			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";
-	}
-};
-
-//#endregion
-//#region src/server-rate-limit/descriptors/$rateLimit.ts
-/**
-* Declares rate limiting for server routes or custom usage.
-* This descriptor provides methods to check rate limits and configure behavior
-* within the server request/response cycle.
-*
-* @example
-* ```ts
-* class ApiService {
-*   // Apply rate limiting to specific paths
-*   apiRateLimit = $rateLimit({
-*     paths: ["/api/*"],
-*     max: 100,
-*     windowMs: 15 * 60 * 1000, // 15 minutes
-*   });
-*
-*   // Or use check() method for manual rate limiting
-*   customAction = $action({
-*     handler: async (req) => {
-*       const result = await this.apiRateLimit.check(req);
-*       if (!result.allowed) throw new Error("Rate limited");
-*       return "ok";
-*     },
-*   });
-* }
-* ```
-*/
-const $rateLimit = (options = {}) => {
-	return (0, alepha.createDescriptor)(RateLimitDescriptor, options);
-};
-var RateLimitDescriptor = class extends alepha.Descriptor {
-	serverRateLimitProvider = (0, alepha.$inject)(ServerRateLimitProvider);
-	get name() {
-		return this.options.name ?? `${this.config.propertyKey}`;
-	}
-	onInit() {
-		this.serverRateLimitProvider.registerRateLimit(this.options);
-	}
-	/**
-	* Checks rate limit for the given request using this descriptor's configuration.
-	*/
-	async check(request, options) {
-		const mergedOptions = {
-			...this.options,
-			...options
-		};
-		return this.serverRateLimitProvider.checkLimit(request, mergedOptions);
-	}
-};
-$rateLimit[alepha.KIND] = RateLimitDescriptor;
-
-//#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` descriptor with `paths` option for path-based rate limiting
-* - The `rateLimit` option in action descriptors for action-specific limiting
-*
-* 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";
-*
-* class ApiService {
-*   // Path-specific rate limiting
-*   apiRateLimit = $rateLimit({
-*     paths: ["/api/*"],
-*     max: 100,
-*     windowMs: 15 * 60 * 1000, // 15 minutes
-*   });
-* }
-* ```
-*
-* @see {@link $rateLimit}
-* @module alepha.server.rate-limit
-*/
-const AlephaServerRateLimit = (0, alepha.$module)({
-	name: "alepha.server.rate-limit",
-	descriptors: [$rateLimit],
-	services: [alepha_server.AlephaServer, ServerRateLimitProvider]
-});
-
-//#endregion
-exports.$rateLimit = $rateLimit;
-exports.AlephaServerRateLimit = AlephaServerRateLimit;
-exports.RateLimitDescriptor = RateLimitDescriptor;
-exports.ServerRateLimitProvider = ServerRateLimitProvider;
-exports.rateLimitOptions = rateLimitOptions;
-//# sourceMappingURL=index.cjs.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"index.cjs","names":["t","ServerRouterProvider","HttpError","result: RateLimitResult","Descriptor","KIND","AlephaServer"],"sources":["../../src/server-rate-limit/providers/ServerRateLimitProvider.ts","../../src/server-rate-limit/descriptors/$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 { RateLimitDescriptorOptions } from \"../descriptors/$rateLimit.ts\";\nimport type { RateLimitOptions } from \"../index.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: RateLimitDescriptorOptions[] = [];\n\n  /**\n   * Register a rate limit configuration (called by descriptors)\n   */\n  public registerRateLimit(config: RateLimitDescriptorOptions): 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: RateLimitDescriptorOptions,\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, createDescriptor, Descriptor, KIND } 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 descriptor 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: RateLimitDescriptorOptions = {},\n): AbstractRateLimitDescriptor => {\n  return createDescriptor(RateLimitDescriptor, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface RateLimitDescriptorOptions 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 AbstractRateLimitDescriptor {\n  readonly name: string;\n  readonly options: RateLimitDescriptorOptions;\n  check(\n    request: ServerRequest,\n    options?: RateLimitOptions,\n  ): Promise<RateLimitResult>;\n}\n\nexport class RateLimitDescriptor\n  extends Descriptor<RateLimitDescriptorOptions>\n  implements AbstractRateLimitDescriptor\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 descriptor'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] = RateLimitDescriptor;\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\nimport { $rateLimit } from \"./descriptors/$rateLimit.ts\";\nimport { ServerRateLimitProvider } from \"./providers/ServerRateLimitProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./descriptors/$rateLimit.ts\";\nexport * from \"./providers/ServerRateLimitProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha/server\" {\n  interface ActionDescriptorOptions<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` descriptor with `paths` option for path-based rate limiting\n * - The `rateLimit` option in action descriptors 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  descriptors: [$rateLimit],\n  services: [AlephaServer, ServerRateLimitProvider],\n});\n"],"mappings":"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"}