rate

type BurstLimiter interface {
	Limiter

	// TakeN returns a new Token that allows to consume n tokens at once. This should not consume the token and not consider
	// the Token in availability calculation. Token should be reusable and time resistant and not usable only once it was got.
	// The context will be passed down to token which will use it if required for calculations.
	TakeN(ctx context.Context, n uint64) (Token, error)

	// Burst is the maximum number of tokens that can be consumed in a single call to TakeN, so higher Burst
	// value allow more events to happen at once. This is not the maximum available value to be consumed. Use Tokens
	// if you need such value.
	Burst() uint64
}

type BurstReservationLimiter interface {
	BurstLimiter
	ReservationLimiter

	// ReserveN returns a new CancellableToken that allows to consume n tokens at once. This should not consume the token
	// but would potentially consider in availability calculation. CancellableToken should not be reusable and used for one-time only.
	// The context will be passed down to token which will use it if required for calculations.
	ReserveN(ctx context.Context, n uint64) (CancellableToken, error)
}

type CancellableToken interface {
	Token

	// Cancel frees up tokens to ReservationLimiter without actually consuming the token. Cancellation does not
	// allow to consume the token and Use function will return ErrTokenCancelled error.
	Cancel()
}

type Clock interface {
	Now() time.Time
}

type Limiter interface {
	// Take returns a new Token. This should not consume the token and not consider the Token in availability calculation.
	// Token should be reusable and time resistant and not usable only once it was got. The context will be passed down to
	// token which will use it if required for calculations.
	Take(ctx context.Context) (Token, error)

	// Tokens should return the remaining token amount that can be consumed at now time with Take, so higher
	// Tokens value allow more events to happen without a delay. A zero value means none token can be consumed now.
	Tokens(ctx context.Context) (uint64, error)

	// Limit should return the maximum amount of token that can be consumed within defined period with Take, so higher Limit
	// value allow more events to happen without a limit delay.
	Limit() uint64
}

type LimiterAlgorithm func() Limiter

type LimiterStore interface {
	// Limit returns Limiter that was persisted before in store with corresponding key string.
	// If there was no entry found it should return default Limiter and persist it with specified key.
	Limit(ctx context.Context, key string) (Limiter, error)
}

type ReservationLimiter interface {
	Limiter

	// Reserve returns a new CancellableToken that allows to consume token. This should not consume the token
	// but would potentially consider in availability calculation. CancellableToken should not be reusable and used for one-time only.
	// The context will be passed down to token which will use it if required for calculations.
	Reserve(ctx context.Context) (CancellableToken, error)
}

type Token interface {
	// Use consumes token and returns no error if succeeded. Returns ErrRateLimitExceeded when limit rate was exceeded.
	// If used with BurstLimiter it will not consume tokens below the limit before returning error. It will return ErrInvalidTokenValue
	// when Limit in BurstLimiter is lower than value provided in TakeN.
	Use() error

	// Allow reports whether an token can be consumed at this moment.
	Allow() bool

	// ResetsAt returns a time when token will be available to be consumed. At returned time Allow() should report true.
	ResetsAt() time.Time

	// Context returns the token's context. To change the context, use WithContext.
	// The returned context should be always non-nil; it defaults to the background context.
	// Since the token is controlled by Limiter, the context should be the value passed in Limiter.Take.
	// The token's context is immutable. To change it create a new Token using Limiter.Take.
	Context() context.Context
}