Package io.smallrye.faulttolerance.api

Annotation Type RateLimit

@Inherited @Retention(RUNTIME) @Documented @InterceptorBinding @Target({METHOD,TYPE}) @Experimental("first attempt at providing rate limit") public @interface RateLimit
Rate limit restricts the number of invocations in a time window of some length. An invocation is permitted when the number of recent invocations is below the configured limit. An invocation that would cause the number of recent invocations to exceed the limit is rejected with RateLimitException.

What "recent" means differs based on the type of the time windows configured. By default, the time windows are fixed, which means that time is divided into a series of consecutive intervals of given length (time windows) and the limit is compared against the number of invocations in the current window. Two different time windows may be configured. With rolling time windows, each invocation has its own time window of given length, overlapping with time windows of previous invocations. This is more precise but requires more memory and may be slower. Using smooth time windows means that invocations are uniformly distributed over time under a calculated rate.

Additionally, a minimum spacing of invocations may be configured. If set, an invocation that happens too quickly after a previous invocation is always rejected with RateLimitException, even if the limit has not been exceeded yet.

With fixed and rolling time windows, rejected invocations always count towards the limit, so if a caller continuously invokes the guarded method faster than the configuration allows, all invocations are rejected until the caller slows down. With smooth time windows, rejected invocations do not count towards the recent rate of invocations.

See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    long
    minSpacing
    Minimum time between two consecutive invocations.
    ChronoUnit
    minSpacingUnit
    The unit of the minimum time between two consecutive invocations.
    RateLimitType
    type
    Type of time windows used for rate limiting.
    int
    value
    Maximum number of invocations in a time window.
    long
    window
    The time window length.
    ChronoUnit
    windowUnit
    The unit of length of a time window.

  • Element Details

    • value

      int value
      Maximum number of invocations in a time window.

      Value must be greater than 0.

      Returns:
      maximum number of invocations in a time window
      See Also:
      Default:
      100

    • window

      long window
      The time window length.

      Value must be greater than 0.

      Returns:
      the time window length
      See Also:
      Default:
      1L

    • windowUnit

      ChronoUnit windowUnit
      The unit of length of a time window.
      Returns:
      the unit of length
      See Also:
      Default:
      SECONDS

    • minSpacing

      long minSpacing
      Minimum time between two consecutive invocations. If the time between two consecutive invocations is shorter, the second invocation is rejected.

      Value must be greater than or equal to 0. When 0, the minimum time check is effectively disabled.

      Returns:
      minimum time between two consecutive invocations
      See Also:
      Default:
      0L

    • minSpacingUnit

      ChronoUnit minSpacingUnit
      The unit of the minimum time between two consecutive invocations.
      Returns:
      the unit of minimum time
      See Also:
      Default:
      SECONDS

    • type

      RateLimitType type
      Type of time windows used for rate limiting.
      Returns:
      the time window type
      See Also:
      Default:
      FIXED