Beignet API reference
    Preparing search index...

    Interface RateLimitOptions<Ctx>

    Options for createRateLimitHooks(...).

    interface RateLimitOptions<Ctx> {
        earlyKey?: (
            args: { req: HttpRequestLike; scope: EarlyRateLimitScope },
        ) => string;
        ipSource?: RateLimitIpSource;
        key?: (
            args: { ctx: Ctx; req: HttpRequestLike; scope: RateLimitScope },
        ) => string;
        trustedProxy?: TrustedProxyConfig;
    }

    Type Parameters

    • Ctx
    Index
    earlyKey? ipSource? key? trustedProxy?
    earlyKey?: (
        args: { req: HttpRequestLike; scope: EarlyRateLimitScope },
    ) => string

    Build a rate-limit key before request parsing and context creation.

    This is used for global and IP-scoped limits. The returned value is the complete key and is not automatically namespaced by contract.

    ipSource?: RateLimitIpSource

    Resolve the client IP for ip-scoped limits.

    There is no default: when any contract declares an ip-scoped rate limit and neither the server-level trustedProxy.clientIp, this hook's trustedProxy.clientIp, ipSource, nor a custom earlyKey is configured, the hook fails at startup. Prefer the server-level policy for production proxy headers; keep these hook-local options for an intentional override or custom keying.

    key?: (
        args: { ctx: Ctx; req: HttpRequestLike; scope: RateLimitScope },
    ) => string

    Build a rate-limit key after context exists.

    This is used for user-scoped limits and any late key strategy. The returned value is the complete key and is not automatically namespaced by contract.

    trustedProxy?: TrustedProxyConfig

    Hook-local trusted-proxy policy used to resolve client IPs when ipSource is not set. This overrides the server-level policy.

    Configure this only when the app is always behind a platform or reverse proxy that strips or normalizes forwarding headers. For ip-scoped rate limits, set trustedProxy.clientIp to the header source written by that trusted edge.

    Settings
    Member Visibility

    On This Page
    Properties