score

Documentation

Overview

Package score implements cc-pool's account-selection scoring. Higher is better; select picks argmax. There are no roles — the best account across the whole pool wins.

Index

• Variables
• func SoonestReset(results []Result) (time.Time, bool)
• func UsableForSticky(r Result) bool
• type Components
• type Input
• type Result
  • func Pick(ranked []Result) (Result, bool)
  • func Rank(inputs []Input, now time.Time) []Result
  • func Score(in Input, now time.Time) Result

Variables

var (
	W5h          = 0.70
	W7d          = 0.25
	WSession     = 2.00
	PenRateLimit = 100.0
	PenStale     = 20.0
	StaleAfter   = 90 * time.Second

	// FiveHourWindow / SevenDayWindow are the window lengths used to credit an
	// imminent reset: depletion is discounted by how much of the window is still
	// ahead before it refills.
	FiveHourWindow = 5 * time.Hour
	SevenDayWindow = 7 * 24 * time.Hour

	// BarrierKnee is the remaining-% below which a convex low-headroom penalty
	// kicks in (so a nearly-exhausted window can't be masked by the other).
	BarrierKnee = 20.0

	// RunwayWeight / RunwayHorizon shape the burn-rate term: an account whose
	// effective 5h headroom would be drained within RunwayHorizon is downranked,
	// up to RunwayWeight points.
	RunwayWeight  = 15.0
	RunwayHorizon = 5 * time.Hour

	// StickyMinEff5 is the effective-5h-remaining floor (percent) below which a
	// sticky selection is abandoned: with this little headroom the resumed
	// session would hit the limit anyway, so cache continuity is worthless.
	StickyMinEff5 = 10.0
)

Scoring coefficients and knobs. All are package vars so they can be tuned or disabled in tests. Setting BarrierKnee=0 and RunwayWeight=0 reduces the score to the exact baseline 0.70·rem5 + 0.25·rem7 − 2·sessions − 100·rl − 20·stale.

Functions

func SoonestReset

func SoonestReset(results []Result) (time.Time, bool)

SoonestReset returns the earliest non-zero 5h reset across results, used by `select --wait`. ok=false if no reset time is known.

func UsableForSticky

func UsableForSticky(r Result) bool

UsableForSticky reports whether a previously-selected account can keep serving a sticky session: it must be available (not rate-limited) and have at least StickyMinEff5 effective 5h headroom.

Types

type Components

type Components struct {
	Eff5             float64 // reset-aware effective 5h remaining
	Eff7             float64 // reset-aware effective 7d remaining
	Remaining5h      float64 // W5h · Eff5 (weighted contribution)
	Remaining7d      float64 // W7d · Eff7
	SessionPenalty   float64
	RateLimitPenalty float64
	StalePenalty     float64
	Barrier5h        float64
	Barrier7d        float64
	RunwayPenalty    float64
}

Components is the per-term breakdown, for `status` and debugging.

type Input

type Input struct {
	AccountID int

	HasUsage bool      // false if we have never sampled this account
	SampleTS time.Time // when the latest usage sample was taken
	Util5h   float64   // percent used 0..100 of the 5-hour window
	Util7d   float64   // percent used 0..100 of the 7-day window
	Resets5h time.Time // when the 5-hour window resets (also the tie-break)
	Resets7d time.Time // when the 7-day window resets

	// Burn5hPerHour is the recent rate of change of util_5h in percent/hour,
	// from usage history. Zero means unknown or idle (no runway penalty).
	Burn5hPerHour float64

	ActiveSessions int
	RateLimited    bool // a live 429 / rate-limit observed
	RefreshFailed  bool // the most recent refresh attempt failed
}

Input is everything the scorer needs about one account.

type Result

type Result struct {
	AccountID   int
	Score       float64
	Components  Components
	Resets5h    time.Time
	Stale       bool
	RateLimited bool
	Available   bool // false only if rate-limited (cannot serve right now)
}

Result is a scored account.

func Pick

func Pick(ranked []Result) (Result, bool)

Pick returns the best AVAILABLE account from ranked results. ok=false if no account is currently available (all rate-limited or the pool is empty).

func Rank

func Rank(inputs []Input, now time.Time) []Result

Rank scores all inputs and returns results sorted best-first. Ties on score break toward the soonest 5-hour reset (an account about to reset is freshest to drain first); a zero Resets5h sorts last among ties.

func Score

func Score(in Input, now time.Time) Result

Score computes the score for one account. For a healthy account (windows far from a reset and well above the barrier knee, no measured burn) it equals the baseline 0.70·rem5 + 0.25·rem7 − penalties; the reset-aware, barrier, and runway terms only engage near limits.