pool

Documentation

Overview

Package pool implements a concurrency-safe rotating pool of tokens with per-token health, cooldown, and JSON state persistence.

Index

• type Lease
• type Options
• type Pool
  • func New(o Options) *Pool
  • func (p *Pool) Entries() []Lease
  • func (p *Pool) LoadState() error
  • func (p *Pool) MarkChecked(id string, live bool)
  • func (p *Pool) Penalize(id string, d time.Duration)
  • func (p *Pool) Quarantine(id string, d time.Duration)
  • func (p *Pool) RecordUse(id string, status int)
  • func (p *Pool) Release(id string, ok bool)
  • func (p *Pool) Save() error
  • func (p *Pool) SetTokens(lines []string)
  • func (p *Pool) SetValue(id, value string)
  • func (p *Pool) Status() Snapshot
  • func (p *Pool) Take() (Lease, bool)
• type Snapshot
• type Status
• type Token
• type TokenView

Types

type Lease

type Lease struct {
	ID    string
	Value string
}

Lease is a token handed out by Take.

type Options

type Options struct {
	Rotation  string        // lru | round_robin | random (default lru)
	Cooldown  time.Duration // rest period applied on Take and on failed Release
	StateFile string        // JSON state file; empty disables persistence
	Now       func() time.Time
	Rand      *rand.Rand
}

Options configures a Pool. Now and Rand are injectable for tests.

type Pool

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

Pool is a thread-safe token pool.

func New

func New(o Options) *Pool

New builds an empty pool. Add tokens with SetTokens.

func (*Pool) Entries

func (p *Pool) Entries() []Lease

Entries returns a snapshot of id/value pairs for iteration (e.g. rechecks).

func (*Pool) LoadState

func (p *Pool) LoadState() error

LoadState applies persisted state onto the current tokens, matched by id. Call after SetTokens so values come from the tokens file.

func (*Pool) MarkChecked

func (p *Pool) MarkChecked(id string, live bool)

MarkChecked records a health-check outcome. A live result revives a token, including one in quarantine.

func (*Pool) Penalize

func (p *Pool) Penalize(id string, d time.Duration)

Penalize keeps a token alive but rests it for d (on top of any current cooldown). Use for soft failures such as 429 or 5xx, where the key is fine but should back off briefly.

func (*Pool) Quarantine

func (p *Pool) Quarantine(id string, d time.Duration)

Quarantine pulls a token out of rotation for d after a hard failure (e.g. a 401/403 auth rejection). A subsequent passing health check revives it.

func (*Pool) RecordUse

func (p *Pool) RecordUse(id string, status int)

RecordUse accounts a request made with a token: it bumps the request count, records the last status, and counts anything >=400 (or 0 for a transport error) as an error.

func (*Pool) Release

func (p *Pool) Release(id string, ok bool)

Release returns a token. ok=false marks it dead and starts a cooldown.

func (*Pool) Save

func (p *Pool) Save() error

Save atomically writes token state (without values) to the state file.

func (*Pool) SetTokens

func (p *Pool) SetTokens(lines []string)

SetTokens reconciles the pool with the given lines. Each non-empty, non-comment line is "id,value" or "value" (id derived from a value hash). Existing tokens keep their state; missing ones are dropped.

func (*Pool) SetValue

func (p *Pool) SetValue(id, value string)

SetValue updates a token's value (used after a refresh) and revives it.

func (*Pool) Status

func (p *Pool) Status() Snapshot

Status returns aggregate counters and a per-token view.

func (*Pool) Take

func (p *Pool) Take() (Lease, bool)

Take returns an available token per the rotation policy and puts it on cooldown. It returns false if none are available.

type Snapshot

type Snapshot struct {
	Total       int         `json:"total"`
	Live        int         `json:"live"`
	Dead        int         `json:"dead"`
	Unknown     int         `json:"unknown"`
	Quarantined int         `json:"quarantined"`
	Cooling     int         `json:"cooling"`
	Tokens      []TokenView `json:"tokens"`
}

Snapshot is an aggregate + per-token view of the pool.

type Status

type Status string

Status is a token's health state.

const (
	Unknown     Status = "unknown"     // not yet checked
	Live        Status = "live"        // last check passed
	Dead        Status = "dead"        // last check or use failed
	Quarantined Status = "quarantined" // pulled after a hard auth failure (401/403)
)

type Token

type Token struct {
	ID           string    `json:"id"`
	Value        string    `json:"-"`
	Weight       int       `json:"weight"`
	Status       Status    `json:"status"`
	LastCheck    time.Time `json:"last_check"`
	LastUsed     time.Time `json:"last_used"`
	CoolingUntil time.Time `json:"cooling_until"`
	Fails        int       `json:"fails"`
	Requests     int64     `json:"requests"`
	Errors       int64     `json:"errors"`
	LastStatus   int       `json:"last_status"`
}

Token holds a value and its runtime state. Value is never persisted.

type TokenView

type TokenView struct {
	ID         string    `json:"id"`
	Weight     int       `json:"weight"`
	Status     Status    `json:"status"`
	LastCheck  time.Time `json:"last_check"`
	LastUsed   time.Time `json:"last_used"`
	Cooling    bool      `json:"cooling"`
	Fails      int       `json:"fails"`
	Requests   int64     `json:"requests"`
	Errors     int64     `json:"errors"`
	LastStatus int       `json:"last_status"`
}

TokenView is a persistence/reporting projection of a Token.