ratelimit

package
v0.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: AGPL-3.0 Imports: 20 Imported by: 0

Documentation

Overview

Package ratelimit meters identity request rate and DNS change throughput with Route 53-style token buckets shared by every API instance.

Index

Constants

View Source
const (
	// DefaultOperationKey names the bucket for operations without their own entry.
	DefaultOperationKey = "*"
	// PatchZoneOperation is charged by change kind rather than a flat cost.
	PatchZoneOperation = "patchZone"
	// MaxBatchRRsets is the largest zone PATCH batch DANS accepts.
	MaxBatchRRsets = 100
)

Built-in defaults mirror "Throttling for Amazon Route 53 API requests" (https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/throttling-api-requests.html), verified on 2026-10-06. AWS has changed these limits before, so re-check the page before changing them. Only operations DANS exposes are listed: createZone mirrors CreateHostedZone, deleteZone mirrors DeleteHostedZone, and zone PATCH change kinds mirror ChangeResourceRecordSets (REPLACE as UPSERT; EXTEND and PRUNE as single-value CREATE/DELETE equivalents).

View Source
const (
	EventFailOpen  = "rate_limit.fail_open"
	EventRecovered = "rate_limit.recovered"

	// DefaultWarningInterval bounds fail-open warnings during an outage.
	DefaultWarningInterval = 10 * time.Second
)

Log event names are a documented operational contract.

View Source
const (
	ReasonTimeout    = "timeout"
	ReasonConnection = "connection"
	ReasonScript     = "script"
)

Failure reason classes. They never contain backend addresses or credentials.

Variables

View Source
var ChangeKinds = []string{"REPLACE", "DELETE", "EXTEND", "PRUNE"}

ChangeKinds are the zone PATCH change types DANS forwards.

Functions

func Classify

func Classify(err error) string

Classify maps a backend error to a reason class without exposing its text.

func ParseRedisURL

func ParseRedisURL(rawURL string) error

ParseRedisURL validates a Redis connection URL without contacting the server. Its error never repeats the URL, which may contain a password.

func RetryAfterSeconds

func RetryAfterSeconds(wait time.Duration) int64

RetryAfterSeconds converts a wait into a whole-second Retry-After of at least 1.

Types

type Backend

type Backend interface {
	Take(context.Context, []Charge) (TakeResult, error)
}

Backend atomically checks and consumes every charge, or none of them.

type Bucket

type Bucket struct {
	Capacity        int64
	RefillPerSecond float64
}

Bucket is one token bucket's burst capacity and sustained refill rate.

type BucketName

type BucketName string

BucketName is the public name of a bucket in headers, errors, and logs.

const (
	BucketRequests  BucketName = "requests"
	BucketOperation BucketName = "operation"
	BucketChanges   BucketName = "changes"
)

type BucketOverride

type BucketOverride struct {
	Capacity        *int64   `json:"capacity"`
	RefillPerSecond *float64 `json:"refill_per_second"`
}

BucketOverride sets either or both bucket values.

type Charge

type Charge struct {
	Name   BucketName
	Key    string
	Bucket Bucket
	Cost   int64
}

Charge is one bucket a request must pay.

func Charges

func Charges(policy Policy, request Request) []Charge

Charges lists the buckets one request pays, in public bucket order.

type Decision

type Decision struct {
	Outcome     Outcome
	Short       []BucketName
	Exceeded    []Exceeded
	RetryAfter  time.Duration
	RequestCost int64
	ChangeCost  int64
	Latency     time.Duration
}

Decision is the rate-limit result for one request.

type Document

type Document struct {
	Defaults   *Override           `json:"defaults"`
	Identities map[string]Override `json:"identities"`
}

Document is the strict JSON rate-limit policy file.

func (Document) Resolve

func (document Document) Resolve(operations map[string]struct{}) (*Table, []string, error)

Resolve validates the document and applies identity > defaults > built-in precedence field by field.

type Exceeded

type Exceeded struct {
	Bucket   BucketName
	Cost     int64
	Capacity int64
}

Exceeded reports a bucket whose capacity is smaller than the request cost.

type Limiter

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

Limiter applies policies, computes costs, and fails open around a backend.

func NewLimiter

func NewLimiter(config LimiterConfig) (*Limiter, error)

NewLimiter validates its dependencies.

func (*Limiter) Admit

func (limiter *Limiter) Admit(ctx context.Context, request Request) Decision

Admit meters one request. It never returns an error: backend failures produce an unmetered decision so throttling fails open.

type LimiterConfig

type LimiterConfig struct {
	Table    *Table
	Backend  Backend
	Timeout  time.Duration
	Reporter *Reporter
	Now      func() time.Time
}

LimiterConfig assembles a Limiter.

type MemoryBackend

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

MemoryBackend is a single-process reference backend with an injectable clock. It implements the same arithmetic as the Redis script.

func NewMemoryBackend

func NewMemoryBackend(now func() time.Time) *MemoryBackend

NewMemoryBackend creates an empty backend. A nil clock uses time.Now.

func (*MemoryBackend) Stored

func (backend *MemoryBackend) Stored(key string) (float64, bool)

Stored reports a key's stored tokens, for tests that assert untouched state.

func (*MemoryBackend) Take

func (backend *MemoryBackend) Take(ctx context.Context, charges []Charge) (TakeResult, error)

Take atomically checks and consumes every charge, or none of them.

type Outcome

type Outcome string

Outcome is the rate-limit result recorded for a metered request.

const (
	OutcomeAdmitted        Outcome = "admitted"
	OutcomeThrottled       Outcome = "throttled"
	OutcomeExceedsCapacity Outcome = "exceeds_capacity"
	OutcomeUnmetered       Outcome = "unmetered"
)

type Override

type Override struct {
	Requests       *BucketOverride           `json:"requests"`
	Operations     map[string]BucketOverride `json:"operations"`
	Changes        *BucketOverride           `json:"changes"`
	ChangeCosts    costOverrides             `json:"change_costs"`
	OperationCosts costOverrides             `json:"operation_costs"`
}

Override sets any subset of a policy's values; omitted values are inherited.

type Policy

type Policy struct {
	Requests         Bucket
	DefaultOperation Bucket
	Operations       map[string]Bucket
	Changes          Bucket
	ChangeCosts      map[string]int64
	OperationCosts   map[string]int64
}

Policy is the fully resolved set of limits for one identity.

func BuiltinPolicy

func BuiltinPolicy() Policy

BuiltinPolicy returns an independent copy of the Route 53-derived defaults.

func (Policy) ChangeCost

func (policy Policy) ChangeCost(operation string, changeKinds []string) int64

ChangeCost returns the change-throughput cost of one request.

func (Policy) MaxRequestChangeCost

func (policy Policy) MaxRequestChangeCost() int64

MaxRequestChangeCost is the largest change cost one request can have.

func (Policy) OperationBucket

func (policy Policy) OperationBucket(operation string) Bucket

OperationBucket returns the request bucket for an operation ID.

type RedisBackend

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

RedisBackend runs the check-and-consume script on a Redis-protocol server.

func NewRedisBackend

func NewRedisBackend(client *RedisClient) (*RedisBackend, error)

NewRedisBackend wraps a client.

func (*RedisBackend) Take

func (backend *RedisBackend) Take(ctx context.Context, charges []Charge) (TakeResult, error)

Take runs the script once. Any error, including a deadline, is returned so the limiter can fail open.

type RedisClient

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

RedisClient is a fail-fast connection pool. Every network wait is bounded by the configured timeout, commands are never retried, no connection is opened until the first request, and broken connections are discarded so the pool redials on demand once Redis is reachable again.

func NewRedisClient

func NewRedisClient(rawURL string, timeout time.Duration) (*RedisClient, error)

NewRedisClient builds a pool from a redis:// or rediss:// URL whose user information and path carry the ACL user, password, and database.

func (*RedisClient) Close

func (client *RedisClient) Close() error

Close releases every pooled connection.

func (*RedisClient) Timeout

func (client *RedisClient) Timeout() time.Duration

Timeout reports the per-operation network timeout.

type Reporter

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

Reporter turns backend failures into bounded warnings and one recovery event.

func NewReporter

func NewReporter(logger *slog.Logger, interval time.Duration, now func() time.Time) *Reporter

NewReporter creates a reporter. A nil clock uses time.Now.

func (*Reporter) Failure

func (reporter *Reporter) Failure(err error)

Failure records one fail-open admission caused by err.

func (*Reporter) Success

func (reporter *Reporter) Success()

Success records a metered request and emits a recovery event after an outage.

type Request

type Request struct {
	IdentityID string
	Operation  string
	// ChangeKinds lists each RRset change kind of an accepted zone PATCH batch.
	ChangeKinds []string
}

Request describes one authenticated request to meter.

type Table

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

Table resolves the immutable policy for every identity.

func NewBuiltinTable

func NewBuiltinTable() *Table

NewBuiltinTable returns a table that applies built-in defaults to everyone.

func ParsePolicy

func ParsePolicy(data []byte, operations map[string]struct{}) (*Table, []string, error)

ParsePolicy strictly decodes and validates a policy document. operations is the set of contract operation IDs a policy may name. It returns the resolved table and warnings for capacities that some request can never fit.

func (*Table) For

func (table *Table) For(identityID string) Policy

For returns the policy for an identity resource ID.

type TakeResult

type TakeResult struct {
	Admitted bool
	// Short holds indexes into the charges that lacked tokens.
	Short []int
	Wait  time.Duration
}

TakeResult is a backend's atomic check-and-consume outcome.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL