@macrocallback request(
  bucket_id :: any(),
  sub_buckets :: %{
    required(name :: atom()) =>
      {request_interval :: pos_integer(), burst :: pos_integer()}
  },
  cost_factor :: integer(),
  opts :: keyword()
) :: {AtomicBucket.verdict(), :atomics.atomics_ref()}

Checks if the request is allowed according to multiple rate limits.

Uses simplified algorithm, where each rate is represented as request interval in milliseconds instead of window and requests. The bucket is updated in a single atomic operation. By default fixed request cost is assumed, but variable cost is also supported via cost factor.

Multiple buckets are initialized in full state. Every request will refill each bucket if needed and check if all buckets have enough tokens to make the request. If true, the request tokens are removed from each bucket and the call returns {:allow, bucket_ref}. Otherwise, each bucket is left untouched and the call returns {:deny, bucket_ref}. bucket_ref is a reference to the bucket atomic.

There must be no duplicate intervals inside the sub-buckets, and lower rate buckets must have bigger bursts (otherwise they kick in too soon).

Arguments:

• bucket_id any id unique within the bucket table

• sub_buckets a map describing sub-buckets, with sub-bucket names as keys and {request interval in milliseconds, burst requests} tuples as values

• cost_factor integer multiplier for the request cost

Options:

• ref bucket atomic reference. If provided, the call will try to use it instead of refetching.

@macrocallback request_details(
  bucket_id :: any(),
  sub_buckets :: %{
    required(name :: atom()) =>
      {request_interval :: pos_integer(), burst :: pos_integer()}
  },
  cost_factor :: integer(),
  opts :: keyword()
) ::
  {:allow, %{required(name :: any()) => non_neg_integer()},
   :atomics.atomics_ref()}
  | {:deny,
     %{required(name :: any()) => {AtomicBucket.verdict(), non_neg_integer()}},
     :atomics.atomics_ref()}

Checks if the request is allowed according to multiple rate limits and returns results of each bucket check.

Unless you really need the results, consider using request/4 instead, which skips unnecessary calculations.

Multiple buckets are initialized in full state. Every request will refill each bucket if needed and check if all buckets have enough tokens to make the request. If true, the call returns {:allow, requests, bucket_ref}, where requests is a map with remaining requests of each sub-bucket. Otherwise, each bucket is left untouched and the call returns {:deny, results, bucket_ref}, where results is a map with sub-bucket name keys and result tuples ({:allow, remaining requests} or {:deny, timeout}) as values.

Note that remaining requests in the result tuple reflect final number of available requests in the sub-bucket after the call.

There must be no duplicate intervals inside the sub-buckets, and lower rate buckets must have bigger bursts (otherwise they kick in too soon).

Arguments:

• bucket_id any id unique within the bucket table

• sub_buckets a map describing sub-buckets, with sub-bucket names as keys and {request interval in milliseconds, burst requests} tuples as values.

• cost_factor integer multiplier for the request cost

Options:

• ref bucket atomic reference. If provided, the call will try to use it instead of refetching.

@callback start_link() :: GenServer.on_start()

Starts AtomicBucket server managing buckets for the limiter.

Normally users don't need to call this function directly - instead the implementing module can be added to a supervision tree and the server is then started by a supervisor.