Skip to content
Distlimit

Limiter API Reference

Package distlimit provides the core thread-safe rate-limiting coordinator.

import "github.com/balramadan/distlimit"

Limiter Struct

Section titled “Limiter Struct”

Limiter coordinates rate-limiting checks between storage drivers, rate rules, and algorithm strategies.

type Limiter struct
  • Thread Safety: Limiter is 100% thread-safe and designed for concurrent use across multiple goroutines.

Constructor

Section titled “Constructor”

New

Section titled “New”

Creates and initializes a new Limiter instance.

func New(driver Driver, opts ...Option) (*Limiter, error)

Parameters

Section titled “Parameters”
  • driver (Driver): Storage backend driver (must not be nil).
  • opts (...Option): Zero or more functional configuration options.

Errors

Section titled “Errors”
  • ErrNilDriver: Returned if driver is nil.
  • ErrInvalidLimit: Returned if WithLimit is $\le 0$.
  • ErrInvalidWindow: Returned if WithWindow is $\le 0$.

Core Evaluation Methods

Section titled “Core Evaluation Methods”

AllowKey

Section titled “AllowKey”

Evaluates rate limit quota for an explicitly provided key string.

func (l *Limiter) AllowKey(ctx context.Context, key string) (Result, error)

Parameters

Section titled “Parameters”
  • ctx (context.Context): Execution context (carried to observers or storage drivers).
  • key (string): The identifier key to rate limit (e.g. user_123, 192.168.1.1). Defaults to "global" if key is empty.

Return Value

Section titled “Return Value”

Returns a Result struct containing evaluation metadata:

type Result struct {
    Allowed   bool          // true if request is permitted, false if blocked
    Limit     int64         // Configured maximum quota capacity
    Remaining int64         // Remaining requests available in current window
    ResetIn   time.Duration // Time remaining until quota resets
}

Allow

Section titled “Allow”

Evaluates rate limit quota using the key extracted by the configured KeyFunc.

func (l *Limiter) Allow(ctx context.Context) (Result, error)

ResetKey

Section titled “ResetKey”

Resets the accumulated rate limit quota and clears state for a specific key across the storage driver.

func (l *Limiter) ResetKey(ctx context.Context, key string) error

UpdatePolicy

Section titled “UpdatePolicy”

Atomically updates default rate-limiting limits at runtime with zero lock contention.

func (l *Limiter) UpdatePolicy(limit int64, window time.Duration)