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
- Variables
- func Classify(err error) string
- func ParseRedisURL(rawURL string) error
- func RetryAfterSeconds(wait time.Duration) int64
- type Backend
- type Bucket
- type BucketName
- type BucketOverride
- type Charge
- type Decision
- type Document
- type Exceeded
- type Limiter
- type LimiterConfig
- type MemoryBackend
- type Outcome
- type Override
- type Policy
- type RedisBackend
- type RedisClient
- type Reporter
- type Request
- type Table
- type TakeResult
Constants ¶
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).
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.
const ( ReasonTimeout = "timeout" ReasonConnection = "connection" ReasonScript = "script" )
Failure reason classes. They never contain backend addresses or credentials.
Variables ¶
var ChangeKinds = []string{"REPLACE", "DELETE", "EXTEND", "PRUNE"}
ChangeKinds are the zone PATCH change types DANS forwards.
Functions ¶
func ParseRedisURL ¶
ParseRedisURL validates a Redis connection URL without contacting the server. Its error never repeats the URL, which may contain a password.
func RetryAfterSeconds ¶
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 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.
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.
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.
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 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 ¶
ChangeCost returns the change-throughput cost of one request.
func (Policy) MaxRequestChangeCost ¶
MaxRequestChangeCost is the largest change cost one request can have.
func (Policy) OperationBucket ¶
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 ¶
NewReporter creates a reporter. A nil clock uses time.Now.
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 ¶
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.