ratelimit

Documentation

Overview

Package ratelimit provides four-tier rate limiting for NACK requests:

1. Per-IP token bucket (overall flood protection).
2. Per-(srcIP, HashKey) sliding window (per-flow NACK storm cap).
3. Per-SeqNum sliding window (per-gap retry cap).
4. Per-(srcIP, groupIdx) token bucket (post-lookup retransmit bandwidth cap).

Tiers 1-3 are pre-lookup (call Allow + AllowChain before cache access). Tier 4 is post-lookup (call AllowGroup after cache hit, before Retransmit).

Index

• type Config
• type Level
• type Limiter
  • func New(cfg Config) *Limiter
  • func (r *Limiter) Allow(srcIP net.IP, startSeq uint64) (bool, Level)
  • func (r *Limiter) AllowChain(srcIP net.IP, hashKey uint64) bool
  • func (r *Limiter) AllowGroup(srcIP net.IP, groupIdx uint32) bool

Types

type Config

type Config struct {
	IPRate         float64       // Tokens per second per source IP
	IPBurst        int           // Burst size per source IP
	SenderRate     float64       // Alias for ChainRate (backward-compat)
	SenderWindow   time.Duration // Alias for ChainWindow (backward-compat)
	ChainRate      float64       // Max NACKs per ChainWindow per (srcIP, HashKey)
	ChainWindow    time.Duration // Sliding window for chain limiter
	SequenceMax    int           // Max requests per SeqNum per SequenceWindow
	SequenceWindow time.Duration // Sliding window for sequence limiter
	GroupRate      float64       // Retransmits per second per (srcIP, groupIdx)
	GroupBurst     int           // Burst size per (srcIP, groupIdx)
}

Config holds rate limiting configuration.

type Level

type Level string

Level represents the rate limiting tier that rejected a request.

const (
	LevelIP       Level = "ip"
	LevelChain    Level = "chain"
	LevelSequence Level = "sequence"
	LevelGroup    Level = "group"
)

type Limiter

type Limiter struct {
	// contains filtered or unexported fields
}

Limiter provides four-tier rate limiting.

func New

func New(cfg Config) *Limiter

New constructs a new Limiter.

func (*Limiter) Allow

func (r *Limiter) Allow(srcIP net.IP, startSeq uint64) (bool, Level)

Allow checks the IP and sequence tiers (pre-lookup). srcIP is the listener source address; startSeq is the StartSeq field from the NACK datagram (SeqNum of the missing frame). Returns (true, "") if allowed.

func (*Limiter) AllowChain

func (r *Limiter) AllowChain(srcIP net.IP, hashKey uint64) bool

AllowChain checks the chain tier (pre-lookup, between IP and sequence). hashKey is the HashKey field from the NACK datagram. 0 means the frame was not stamped by the proxy (unstamped); rate-limiting on HashKey=0 would bucket all such unattributed gaps together and prematurely exhaust a shared limit, so the check is skipped.

func (*Limiter) AllowGroup

func (r *Limiter) AllowGroup(srcIP net.IP, groupIdx uint32) bool

AllowGroup checks the group tier (post-lookup, before Retransmit). groupIdx is derived from the frame's TxID. Returns true if the retransmit should proceed; false means throttle the retransmit (answered with THROTTLED when the throttle response is enabled, silence otherwise).