throttle

type APILimits struct {
	// ByAPIKey, ByAccount and ByTenant apply to a caller who said who they
	// were. A machine integration is usually allowed the most, one person the
	// least, and the tenant ceiling is what stops one customer's batch job
	// starving the others.
	//
	// The first two are alternatives rather than a pair: a request made with a
	// key is counted as that key and not also as the account the key acts as.
	// Otherwise the tighter of the two — the account, on any sane ladder —
	// decides every key-authenticated request and the key's own number is
	// decoration. ByTenant applies either way, because it is a different
	// question: one customer's whole share.
	ByAPIKey  Limit
	ByAccount Limit
	ByTenant  Limit

	// ByIP applies only to a caller who did not say who they were.
	//
	// Only, and deliberately. An address is a poor name for a person — an
	// office behind one NAT is one address and a phone changes address between
	// requests — so once a request carries an identity, that identity is the
	// better key and the address is noise. It is also the weakest key there is,
	// which is worth saying out loud: addresses are cheap, and an attacker with
	// many of them is limited many times over rather than once.
	ByIP Limit

	// Routes are extra limits on particular route patterns, counted against the
	// caller's narrowest identity and on top of whatever the limits above
	// allow. The key is the pattern net/http matched, for example
	// "POST /api/v1/todos".
	Routes map[string]Limit

	// Exempt are patterns nothing applies to. A route whose whole job is to be
	// called constantly — a health check somebody put behind the API, a
	// long-lived stream — is better named here than given a number that has to
	// be guessed.
	Exempt map[string]bool
}

type Caller struct {
	APIKey  string
	Account string
	Tenant  string
	IP      string
}

type Check struct {
	Limit Limit
	Key   Key
}

type Counter interface {
	// Count returns how many of the limit's events happened for the key
	// strictly after since, and when the earliest of them was. The earliest is
	// the zero time when the count is zero.
	//
	// An occurrence of the limit's ClearedBy event resets the window: anything
	// at or before the most recent one does not count.
	//
	// The lower bound excludes since so that a window closes when it says it
	// will. An event the limiter promised would expire at 12:15 must not still
	// be counted at 12:15, or the Retry-After it handed out was a lie.
	Count(ctx context.Context, limit Limit, key Key, since time.Time) (n int, earliest time.Time, err error)
}

type Decision struct {
	Allowed bool
	// Limit and Key are whichever check this decision came from: the one that
	// refused, or the one closest to refusing.
	Limit Limit
	Key   Key

	Used      int
	Remaining int

	// RetryAfter is how long until a slot frees. Zero when allowed.
	RetryAfter time.Duration
	ResetAt    time.Time
}

type Defaults struct {
	// LoginByEmail locks one account after a handful of wrong codes.
	LoginByEmail Limit
	// LoginByIP throttles one source spraying many accounts.
	LoginByIP Limit

	// EmailCodeRequest bounds how often one address may be mailed a code.
	EmailCodeRequest Limit
	// EmailCodeByIP bounds how many codes one source may ask for, across every
	// address.
	//
	// The pair again, and the asymmetry is the same one — but this is the limit
	// that matters most, because with provisioning on, asking for a code writes
	// a person. Without it one script makes ten thousand identities.
	EmailCodeByIP Limit

	VerificationResend Limit

	// InvitationPreview bounds reading an invitation link, which is the one
	// unauthenticated endpoint keyed by a secret rather than by an address.
	// Nothing clears it: what it bounds is one source walking the token space,
	// and a preview that found something is as much evidence of that as one
	// that did not.
	InvitationPreview Limit

	// Refresh bounds one session's rotations. A client refreshing sixty times
	// a minute is looping, not working.
	Refresh Limit

	APIKeyFailures Limit
}

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

type Key struct {
	Kind  string
	Value string
}

type Limit struct {
	// Name identifies the limit in errors and headers, for example
	// "login.email".
	Name string
	// Event is what is being counted. For the generated auth log it is an
	// event name such as "LoginFailed".
	Event string
	// ClearedBy is the event that resets the window, if any.
	//
	// It is what keeps a limit from punishing the wrong thing: somebody who
	// mistypes a password four times, gets it right, and mistypes once more is
	// not locked out, because the success wiped the earlier failures. Empty
	// means nothing clears the window — right for a limit whose event is not a
	// failure at all, such as bounding how often one session may refresh.
	ClearedBy string
	// Max is how many are allowed inside Window. The Max+1st is refused.
	Max int
	// Window is how far back the count reaches.
	Window time.Duration
}

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

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

type LocalConfig struct {
	// Interval is how long a replica may hold increments before publishing
	// them. It is the overshoot, stated as time: the limiter can miss up to one
	// Interval of traffic per replica.
	//
	// Publishing on a schedule is not an optimisation, it is what makes the
	// limit a limit. Ten replicas each quietly counting a fifth of the budget
	// are each under it and together at twice it.
	//
	// Zero means one second.
	Interval time.Duration

	// Threshold is the fraction of a limit above which a caller is reconciled
	// on every request regardless of Interval, so enforcement tightens as
	// somebody approaches their limit rather than after they pass it.
	//
	// Zero means 0.5.
	Threshold float64

	// MaxKeys bounds the map. Past it, new keys go straight to the recorder
	// rather than being remembered — slower, and the alternative is a process
	// whose memory is chosen by whoever is calling.
	//
	// Zero means 100_000.
	MaxKeys int
}

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

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

type PostgresConfig struct {
	// Table is the log table, for example "rig_auth_log".
	Table string
	// EventColumn holds the event name.
	EventColumn string
	// AtColumn holds when the event happened.
	AtColumn string

	// Match maps a [Key.Kind] onto the SQL that selects rows about it, with $1
	// bound to the key's value.
	//
	// It is an expression rather than a column name so that a comparison can
	// say what it means: an email address is matched case-insensitively and an
	// address needs a cast, and neither is expressible as a bare column.
	Match map[string]string
}

type Recorder interface {
	// Incr adds delta events for the key at now and returns the total inside
	// the limit's window, with the instant that window's oldest part expires.
	//
	// delta is a count rather than an implied one so that a caller which held
	// events back can flush them together. Zero is legal and asks the question
	// without spending anything.
	Incr(ctx context.Context, limit Limit, key Key, now time.Time, delta int) (total int, resetAt time.Time, err error)
}

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

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

type TallyConfig struct {
	// Table is the counter table. Empty means rig_throttle.
	Table string
}