Package org.apache.juneau.rest.server.guard

Class RateLimitGuard.Builder

java.lang.Object
org.apache.juneau.rest.server.guard.RateLimitGuard.Builder
Enclosing class:
RateLimitGuard
public static class RateLimitGuard.Builder extends Object
Builder for RateLimitGuard.

  • Constructor Details

    • Builder

      protected Builder()
      Constructor.

  • Method Details

    • permitsPerSecond

      public RateLimitGuard.Builder permitsPerSecond(int value)
      Sets the steady-state refill rate in permits per second.
      Parameters:
      value - Permits per second. Must be > 0.
      Returns:
      This object.

    • permitsPerMinute

      public RateLimitGuard.Builder permitsPerMinute(int value)
      Sets the steady-state refill rate in permits per minute.

      Equivalent to permitsPerSecond(value / 60.0).

      Parameters:
      value - Permits per minute. Must be > 0.
      Returns:
      This object.

    • permitsPerHour

      public RateLimitGuard.Builder permitsPerHour(int value)
      Sets the steady-state refill rate in permits per hour.

      Equivalent to permitsPerSecond(value / 3600.0).

      Parameters:
      value - Permits per hour. Must be > 0.
      Returns:
      This object.

    • burst

      public RateLimitGuard.Builder burst(int value)
      Sets the burst capacity (maximum tokens a bucket can hold).
      Parameters:
      value - Burst capacity. Must be > 0.
      Returns:
      This object.

    • keyBy

      public RateLimitGuard.Builder keyBy(Function<RestRequest,String> value)
      Sets the per-request key resolver.

      Default is ServletRequestWrapper.getRemoteAddr(). Common alternatives include the user-principal name, an API-key header, or a tenant id. When the resolver returns null the empty string is used.

      Parameters:
      value - Resolver function. Must not be null.
      Returns:
      This object.

    • xForwardedForAware

      public RateLimitGuard.Builder xForwardedForAware(boolean value)
      Enables X-Forwarded-For-aware key resolution.

      When enabled, the first comma-separated hop of the X-Forwarded-For header takes precedence over the configured keyBy(Function) resolver. Only opt in when a trusted reverse proxy strips and rewrites the header; otherwise clients can spoof it to defeat IP-based throttling.

      Parameters:
      value - true to honor X-Forwarded-For.
      Returns:
      This object.

    • exemptPaths

      public RateLimitGuard.Builder exemptPaths(String... values)
      Sets the set of request paths that bypass throttling.

      Matched against HttpServletRequestWrapper.getPathInfo() and RestRequest.getServletPath() (exact match). Defaults to /healthz, /readyz, /livez — the built-in probe paths. Pass an empty array to clear the defaults.

      Parameters:
      values - Exempt paths. Must not be null.
      Returns:
      This object.

    • whenLimitExceeded

      public RateLimitGuard.Builder whenLimitExceeded(BiConsumer<RestRequest,RateLimitGuard.RateLimitInfo> value)
      Sets a callback invoked when a request is rejected due to an empty bucket.

      Useful for structured logging or metrics emission. The callback runs before TooManyRequests is thrown and must not block. Exceptions raised inside the callback propagate to the caller.

      Parameters:
      value - Callback. Must not be null.
      Returns:
      This object.

    • storage

      public RateLimitGuard.Builder storage(RateLimitGuard.Storage value)
      Sets the bucket-state storage backend.

      Default is RateLimitGuard.Storage.inMemory(). Substitute a distributed backend (Redis, DynamoDB, etc.) when running multiple pods that share a single rate envelope.

      Parameters:
      value - Storage backend. Must not be null.
      Returns:
      This object.

    • build

      public RateLimitGuard build()
      Builds the guard.
      Returns:
      A new RateLimitGuard.