throttle

Documentation

Overview

Package throttle is a persistent, cross-process circuit-breaker. An agent invokes a fresh rivr process per call, so an in-memory timer is a no-op — state lives in $XDG_STATE_HOME/rivr/. Default behavior is FAIL-FAST (a hung CLI deadlocks an agent loop); waiting is opt-in. Used to back off after a provider quota/block response so the next process doesn't waste a credit or deepen a block. See contract / cli-implement §1.

Index

• func Block(provider string, seconds int, now time.Time)
• func Clear(provider string)
• func Save(provider string, s State)
• func Touch(provider string, now time.Time)
• type State
  • func Load(provider string) State
  • func (s State) RetryAfter(now time.Time) int

Functions

func Block

func Block(provider string, seconds int, now time.Time)

Block records a cooldown of `seconds` for a provider, starting now.

func Clear

func Clear(provider string)

Clear removes any active block (e.g. after a successful request).

func Save

func Save(provider string, s State)

Save persists the breaker state (best-effort; failures are non-fatal).

func Touch

func Touch(provider string, now time.Time)

Touch records that a request was just made (for min-interval pacing by callers).

Types

type State

type State struct {
	LastRequestUnix  int64 `json:"lastRequestUnix"`
	BlockedUntilUnix int64 `json:"blockedUntilUnix"`
}

State is the persisted per-provider breaker state.

func Load

func Load(provider string) State

Load reads the breaker state for a provider (zero value if absent/unreadable).

func (State) RetryAfter

func (s State) RetryAfter(now time.Time) int

RetryAfter returns seconds remaining on an active block (0 if not blocked).