limiter

README

Limiter

Fork of ulule/limiter with many features and integrations removed.

Documentation

Index

• Constants
• Variables
• func GetIP(r *http.Request, options ...Options) net.IP
• func GetIPWithMask(r *http.Request, options ...Options) net.IP
• type Context
• type Limiter
  • func New(store Store, rate Rate, options ...Option) *Limiter
  • func (limiter *Limiter) Get(ctx context.Context, key string) (Context, error)
  • func (limiter *Limiter) GetIP(r *http.Request) net.IP
  • func (limiter *Limiter) GetIPKey(r *http.Request) string
  • func (limiter *Limiter) GetIPWithMask(r *http.Request) net.IP
  • func (limiter *Limiter) Peek(ctx context.Context, key string) (Context, error)
  • func (limiter *Limiter) Reset(ctx context.Context, key string) (Context, error)
• type Option
  • func WithIPv4Mask(mask net.IPMask) Option
  • func WithIPv6Mask(mask net.IPMask) Option
  • func WithTrustForwardHeader(enable bool) Option
• type Options
• type Rate
  • func NewRateFromFormatted(formatted string) (Rate, error)
• type Store
• type StoreOptions

Constants

const (
	// DefaultPrefix is the default prefix to use for the key in the store.
	DefaultPrefix = "limiter"

	// DefaultMaxRetry is the default maximum number of key retries under
	// race condition (mainly used with database-based stores).
	DefaultMaxRetry = 3

	// DefaultCleanUpInterval is the default time duration for cleanup.
	DefaultCleanUpInterval = 30 * time.Second
)

Variables

var (
	// DefaultIPv4Mask defines the default IPv4 mask used to obtain user IP.
	DefaultIPv4Mask = net.CIDRMask(32, 32)
	// DefaultIPv6Mask defines the default IPv6 mask used to obtain user IP.
	DefaultIPv6Mask = net.CIDRMask(128, 128)
)

Functions

func GetIP

func GetIP(r *http.Request, options ...Options) net.IP

GetIP returns IP address from request. If options is defined and TrustForwardHeader is true, it will lookup IP in X-Forwarded-For and X-Real-IP headers.

func GetIPWithMask

func GetIPWithMask(r *http.Request, options ...Options) net.IP

GetIPWithMask returns IP address from request by applying a mask.

Types

type Context

type Context struct {
	Limit     int64
	Remaining int64
	Reset     int64
	Reached   bool
}

Context is the limit context.

type Limiter

type Limiter struct {
	Store   Store
	Rate    Rate
	Options Options
}

Limiter is the limiter instance.

func New

func New(store Store, rate Rate, options ...Option) *Limiter

New returns an instance of Limiter.

func (*Limiter) Get

func (limiter *Limiter) Get(ctx context.Context, key string) (Context, error)

Get returns the limit for given identifier.

func (*Limiter) GetIP

func (limiter *Limiter) GetIP(r *http.Request) net.IP

GetIP returns IP address from request.

func (*Limiter) GetIPKey

func (limiter *Limiter) GetIPKey(r *http.Request) string

GetIPKey extracts IP from request and returns hashed IP to use as store key.

func (*Limiter) GetIPWithMask

func (limiter *Limiter) GetIPWithMask(r *http.Request) net.IP

GetIPWithMask returns IP address from request by applying a mask.

func (*Limiter) Peek

func (limiter *Limiter) Peek(ctx context.Context, key string) (Context, error)

Peek returns the limit for given identifier, without modification on current values.

func (*Limiter) Reset

func (limiter *Limiter) Reset(ctx context.Context, key string) (Context, error)

Reset sets the limit for given identifier to zero.

type Option

type Option func(*Options)

Option is a functional option.

func WithIPv4Mask

func WithIPv4Mask(mask net.IPMask) Option

WithIPv4Mask will configure the limiter to use given mask for IPv4 address.

func WithIPv6Mask

func WithIPv6Mask(mask net.IPMask) Option

WithIPv6Mask will configure the limiter to use given mask for IPv6 address.

func WithTrustForwardHeader

func WithTrustForwardHeader(enable bool) Option

WithTrustForwardHeader will configure the limiter to trust X-Real-IP and X-Forwarded-For headers.

type Options

type Options struct {
	// IPv4Mask defines the mask used to obtain a IPv4 address.
	IPv4Mask net.IPMask
	// IPv6Mask defines the mask used to obtain a IPv6 address.
	IPv6Mask net.IPMask
	// TrustForwardHeader enable parsing of X-Real-IP and X-Forwarded-For headers to obtain user IP.
	TrustForwardHeader bool
}

Options are limiter options.

type Rate

type Rate struct {
	Formatted string
	Period    time.Duration
	Limit     int64
}

Rate is the rate.

func NewRateFromFormatted

func NewRateFromFormatted(formatted string) (Rate, error)

NewRateFromFormatted returns the rate from the formatted version.

type Store

type Store interface {
	// Get returns the limit for given identifier.
	Get(ctx context.Context, key string, rate Rate) (Context, error)
	// Peek returns the limit for given identifier, without modification on current values.
	Peek(ctx context.Context, key string, rate Rate) (Context, error)
	// Reset resets the limit to zero for given identifier.
	Reset(ctx context.Context, key string, rate Rate) (Context, error)
}

Store is the common interface for limiter stores.

type StoreOptions

type StoreOptions struct {
	// Prefix is the prefix to use for the key.
	Prefix string

	// MaxRetry is the maximum number of retry under race conditions.
	MaxRetry int

	// CleanUpInterval is the interval for cleanup.
	CleanUpInterval time.Duration
}

StoreOptions are options for store.