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

Easy-to-use modern TypeScript framework for building many kind of applications.

import { Middleware, Static } from "alepha";
import { ServerRequest, ServerRouterProvider } from "alepha/server";
import { CacheProvider } from "alepha/cache";
import { DateTimeProvider } from "alepha/datetime";
//#region ../../src/server/rate-limit/primitives/$rateLimit.d.ts
interface RateLimitMiddlewareOptions extends RateLimitOptions {
  /**
   * Custom key function. Receives the handler arguments.
   * When provided, bypasses request-based key generation — works outside `$action`.
   */
  key?: (...args: any[]) => string;
}
/**
 * Middleware that enforces rate limiting.
 *
 * **Key resolution** (in order):
 * 1. Explicit `key` function — user controls the key. Works anywhere (`$action`, `$job`, `$pipeline`).
 * 2. Auto-detect `request.ip` from ALS — default for `$action` context.
 * 3. `"global"` fallback — when no request context and no `key`. All calls share one bucket.
 *
 * Sets `X-RateLimit-*` response headers when a request context is available.
 * Throws `HttpError(429)` when the limit is exceeded.
 *
 * ```typescript
 * // In $action: automatically rate limits by IP
 * $action({ use: [$rateLimit({ max: 100, windowMs: 60000 })] })
 *
 * // In $action: rate limit by custom key
 * $action({ use: [$rateLimit({ max: 10, windowMs: 60000, key: (req) => req.user?.id })] })
 *
 * // In $job: rate limit all executions globally
 * $job({ use: [$rateLimit({ max: 5, windowMs: 3600000 })] })
 * ```
 */
declare const $rateLimit: (options?: RateLimitMiddlewareOptions) => Middleware;
//#endregion
//#region ../../src/server/rate-limit/providers/ServerRateLimitProvider.d.ts
interface RateLimitResult {
  allowed: boolean;
  limit: number;
  remaining: number;
  resetTime: number;
  retryAfter?: number;
}
/**
 * Rate limit configuration atom (global defaults)
 */
declare const rateLimitOptions: import("alepha").Atom<import("zod").ZodObject<{
  windowMs: import("zod").ZodDefault<import("zod").ZodNumber>;
  max: import("zod").ZodDefault<import("zod").ZodNumber>;
  skipFailedRequests: import("zod").ZodOptional<import("zod").ZodBoolean>;
  skipSuccessfulRequests: import("zod").ZodOptional<import("zod").ZodBoolean>;
}, import("zod/v4/core").$strip>, "alepha.server.rate-limit.options">;
type RateLimitAtomOptions = Static<typeof rateLimitOptions.schema>;
declare module "alepha" {
  interface State {
    [rateLimitOptions.key]: RateLimitAtomOptions;
  }
}
interface RateLimitRegistration extends RateLimitOptions {
  /**
   * Name identifier for this rate limit.
   */
  name?: string;
  /**
   * Path patterns to match (supports wildcards like /api/*).
   */
  paths?: string[];
}
declare class ServerRateLimitProvider {
  protected readonly log: import("alepha/logger").Logger;
  protected readonly dateTime: DateTimeProvider;
  protected readonly serverRouterProvider: ServerRouterProvider;
  protected readonly cacheProvider: CacheProvider;
  protected readonly globalOptions: Readonly<{
    windowMs: number;
    max: number;
    skipFailedRequests?: boolean | undefined;
    skipSuccessfulRequests?: boolean | undefined;
  }>;
  protected static readonly CACHE_NAME = "rate-limit";
  /**
   * Registered rate limit configurations with their path patterns
   */
  readonly registeredConfigs: RateLimitRegistration[];
  /**
   * Register a rate limit configuration (called by primitives)
   */
  registerRateLimit(config: RateLimitRegistration): void;
  protected readonly onStart: import("alepha").HookPrimitive<"start">;
  readonly onRequest: import("alepha").HookPrimitive<"server:onRequest">;
  readonly onActionRequest: import("alepha").HookPrimitive<"action:onRequest">;
  /**
   * Build complete rate limit options by merging with global defaults
   */
  protected buildRateLimitOptions(config: RateLimitRegistration): RateLimitOptions;
  /**
   * Set rate limit headers on the response
   */
  setRateLimitHeaders(request: ServerRequest, result: RateLimitResult): void;
  checkLimit(req: Pick<ServerRequest, "ip">, options?: RateLimitOptions): Promise<RateLimitResult>;
  /**
   * Check rate limit by an explicit key string.
   * Useful when no request context is available (e.g. `$job`, `$pipeline`).
   */
  checkLimitByKey(baseKey: string, options?: RateLimitOptions): Promise<RateLimitResult>;
  protected generateKey(req: Pick<ServerRequest, "ip">): string;
}
//#endregion
//#region ../../src/server/rate-limit/index.d.ts
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.
     */
    rateLimit?: RateLimitOptions;
  }
  interface ServerRoute {
    /**
     * 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).
   */
  max?: number;
  /**
   * Window duration in milliseconds (default: 15 minutes).
   */
  windowMs?: number;
  /**
   * Custom key generator function.
   */
  keyGenerator?: (req: any) => string;
  /**
   * Skip rate limiting for failed requests.
   */
  skipFailedRequests?: boolean;
  /**
   * Skip rate limiting for successful requests.
   */
  skipSuccessfulRequests?: boolean;
}
/**
 * Request rate limiting on actions.
 *
 * **Features:**
 * - Rate limit configuration per action
 *
 * @module alepha.server.rate-limit
 */
declare const AlephaServerRateLimit: import("alepha").Service<import("alepha").Module>;
//#endregion
export { $rateLimit, AlephaServerRateLimit, RateLimitAtomOptions, RateLimitMiddlewareOptions, RateLimitOptions, RateLimitRegistration, RateLimitResult, ServerRateLimitProvider, rateLimitOptions };
//# sourceMappingURL=index.d.ts.map