ratelimitx

package
v0.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 7, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package ratelimitx defines Kernel's rate limit provider contract.

It separates policy semantics from middleware wiring. MEMORY is local to one process/pod and is safe for demos or per-instance self-protection. Cluster-wide quotas must use REDIS or EXTERNAL providers and are validated by bootx/serverx or clientpolicyx before the service starts.

Index

Constants

This section is empty.

Variables

View Source 
var ErrLimited = errorx.TooManyRequests("RATE_LIMIT_EXCEEDED", "request rejected by rate limit")

ErrLimited is the canonical cross-protocol error returned by rate-limit middleware.

Functions

This section is empty.

Types

type Backend 

type Backend string

Backend selects where limiter state lives. 

const (
	BackendMemory   Backend = "memory"
	BackendRedis    Backend = "redis"
	BackendExternal Backend = "external"
)

type Decision 

type Decision struct {
	Allowed    bool
	RetryAfter time.Duration
	Reason     string
}

Decision is returned by a limiter provider.

type FailMode 

type FailMode string

FailMode controls behavior when a distributed provider is unavailable. 

const (
	FailOpen   FailMode = "open"
	FailClosed FailMode = "closed"
)

type KeyStrategy 

type KeyStrategy string

KeyStrategy names how middleware should derive a limiter key. 

const (
	KeyOperation KeyStrategy = "operation"
	KeyPrincipal KeyStrategy = "principal"
	KeyTenant    KeyStrategy = "tenant"
	KeyCaller    KeyStrategy = "caller"
	KeyCustom    KeyStrategy = "custom"
)

type Limiter 

type Limiter interface {
	Allow(ctx context.Context, key string, cost int) (Decision, error)
}

Limiter is the runtime interface used by middleware.

func NewMemoryLimiter 

func NewMemoryLimiter(policy Policy) Limiter

NewMemoryLimiter creates a local token bucket limiter.

type MemoryProvider 

type MemoryProvider struct{}

MemoryProvider implements per-process token buckets. It is intentionally local and must not be used for cluster-wide quotas.

func NewMemoryProvider 

func NewMemoryProvider() *MemoryProvider

func (*MemoryProvider) NewLimiter 

func (p *MemoryProvider) NewLimiter(policy Policy) (Limiter, error)

type Policy 

type Policy struct {
	Name     string
	Enabled  bool
	Backend  Backend
	Scope    Scope
	Key      KeyStrategy
	QPS      float64
	Burst    int
	FailMode FailMode
}

Policy is the normalized rate-limit contract used by server and client autowire.

func (Policy) Normalize 

func (p Policy) Normalize() Policy

Normalize fills production-safe defaults without weakening the declared scope.

func (Policy) Validate 

func (p Policy) Validate() error

Validate checks the policy independently from deployment topology.

func (Policy) ValidateForDeployment 

func (p Policy) ValidateForDeployment(replicas int) error

ValidateForDeployment checks topology-sensitive constraints.

type Provider 

type Provider interface {
	NewLimiter(policy Policy) (Limiter, error)
}

Provider creates limiters from policies.

type Scope 

type Scope string

Scope defines whether a limit is local to this instance or shared cluster-wide. 

const (
	ScopeLocalInstance Scope = "local_instance"
	ScopeGlobalCluster Scope = "global_cluster"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.