throughput

README

server/throughput

Import path: github.com/InsideGallery/core/server/throughput

throughput tracks per-key request throughput and can reject requests that exceed per-second or 30-day rolling limits.

Main APIs

• Tier constants: Tier0 through Tier3.
• Limit constants: Tier0RPS, Tier1RPS, Tier2RPS, Tier3RPS and matching Tier*RPM values.
• GetRPS(tier) and GetRPM(tier): return configured limits.
• Storage: interface for counters, tiers, increments, and resets.
• MemoryStorage: in-memory implementation backed by ordered maps and atomic counters.
• New(ctx, storage): creates a Throughput validator.
• Throughput.Validate(name): increments and returns whether the key is within limits.
• Throughput.Loop(): resets per-second counters every second until the context is cancelled.
• Throughput.Middleware(parameter): Fiber middleware that reads a string from c.Locals(parameter) and returns HTTP 429 when validation fails.

Usage

storage := throughput.NewMemoryStorage()
storage.Add("client-1", throughput.Tier1)

limiter := throughput.New(ctx, storage)
go limiter.Loop()

if !limiter.Validate("client-1") {
	return errors.New("too many requests")
}

Operational Notes

The Fiber middleware logs high latency and rejected requests with the short instance ID from server/instance. Callers must set the configured local value to a string before the middleware runs.

Documentation

Index

• Constants
• func GetRPM(tier int) uint64
• func GetRPS(tier int) uint64
• type MemoryStorage
  • func NewMemoryStorage() *MemoryStorage
  • func (s *MemoryStorage) Add(key string, tier int)
  • func (s *MemoryStorage) Incr(key string)
  • func (s *MemoryStorage) RPM(key string) uint64
  • func (s *MemoryStorage) RPS(key string) uint64
  • func (s *MemoryStorage) Reset()
  • func (s *MemoryStorage) Tier(key string) int
• type Storage
• type Throughput
  • func New(ctx context.Context, storage Storage) *Throughput
  • func (t *Throughput) Loop()
  • func (t *Throughput) Middleware(parameter string) func(next fiber.Handler) fiber.Handler
  • func (t *Throughput) Validate(name string) bool

Constants

const (
	Tier0 = iota
	Tier1
	Tier2
	Tier3

	Tier0RPS uint64 = 10
	Tier1RPS uint64 = 50
	Tier2RPS uint64 = 250
	Tier3RPS uint64 = 1250

	Tier0RPM uint64 = 1000000
	Tier1RPM uint64 = 5000000
	Tier2RPM uint64 = 25000000
	Tier3RPM uint64 = 125000000
)

const Days30 = time.Hour * 24 * 30

Functions

func GetRPM

func GetRPM(tier int) uint64

func GetRPS

func GetRPS(tier int) uint64

Types

type MemoryStorage

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

func NewMemoryStorage

func NewMemoryStorage() *MemoryStorage

func (*MemoryStorage) Add

func (s *MemoryStorage) Add(key string, tier int)

func (*MemoryStorage) Incr

func (s *MemoryStorage) Incr(key string)

func (*MemoryStorage) RPM

func (s *MemoryStorage) RPM(key string) uint64

func (*MemoryStorage) RPS

func (s *MemoryStorage) RPS(key string) uint64

func (*MemoryStorage) Reset

func (s *MemoryStorage) Reset()

func (*MemoryStorage) Tier

func (s *MemoryStorage) Tier(key string) int

type Storage

type Storage interface {
	RPS(key string) uint64
	RPM(key string) uint64
	Add(key string, tier int)
	Incr(key string)
	Tier(key string) int
	Reset()
}

type Throughput

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

func New

func New(ctx context.Context, storage Storage) *Throughput

func (*Throughput) Loop

func (t *Throughput) Loop()

func (*Throughput) Middleware

func (t *Throughput) Middleware(parameter string) func(next fiber.Handler) fiber.Handler

func (*Throughput) Validate

func (t *Throughput) Validate(name string) bool