Class BSV::Overlay::HostReputationTracker ¶

Inherits: Object

Tracks per-host reputation for overlay query dispatch.

Records success and failure events per host, maintains an EWMA latency estimate, applies exponential backoff after repeated failures, and ranks a candidate host list so callers can prefer fast, reliable hosts.

Thread-safe via an internal Mutex.

An optional store adapter may be supplied for persistence. The adapter must respond to +#get(key)+ and +#set(key, value)+. When provided, each updated entry is persisted and unknown hosts are loaded on first access.

Constants¶

BASE_BACKOFF_MS ¶

Starting backoff duration in milliseconds.

DEFAULT_LATENCY_MS ¶

Fallback latency used when no measurements exist yet, or when an invalid (negative / non-finite) value is reported.

FAILURE_BACKOFF_GRACE ¶

Number of consecutive failures that are forgiven before backoff kicks in. A host may fail this many times without being penalised with a backoff window.

FAILURE_PENALTY_MS ¶

Latency penalty added to a host's score per consecutive failure.

LATENCY_SMOOTHING_FACTOR ¶

EWMA smoothing factor (α). Higher values give more weight to recent observations; lower values produce a smoother, more stable estimate.

MAX_BACKOFF_MS ¶

Maximum backoff duration in milliseconds (60 seconds).

SUCCESS_BONUS_MS ¶

Latency bonus subtracted from a host's score per recorded success, capped at half the current average latency.

Public Instance Methods¶

initialize(store: = nil) ¶

• @param store [#get, #set, nil] optional persistence adapter
• @return [HostReputationTracker] a new instance of HostReputationTracker

rank_hosts(hosts, now = Time.now) ¶

Ranks hosts for query dispatch.

Steps: 1. Filter nil and empty-string entries. 2. Deduplicate preserving first occurrence order. 3. Compute a score for each host. 4. Sort: available hosts first (score asc, then total_successes desc, then original position asc), followed by backed-off hosts (backoff_until asc). - @param hosts [Array] candidate host list - @param now [Time] reference time (default: Time.now) - @return [Array]

record_failure(host, reason = nil) ¶

Records a failed request to host.

Increments failure counters. Once consecutive failures exceed FAILURE_BACKOFF_GRACE, an exponential backoff window is set.

DNS-level errors (SocketError, Errno::ECONNREFUSED, or messages containing 'getaddrinfo' or 'Failed to fetch') skip the grace period entirely — backoff is applied from the very first such failure. - @param host [String] hostname or URL - @param reason [Exception, String, nil] error that caused the failure

record_success(host, latency_ms) ¶

Records a successful request to host.

Updates the EWMA latency estimate (first success sets the average directly; subsequent successes apply smoothing). Resets consecutive failure count and clears any active backoff window. - @param host [String] hostname or URL - @param latency_ms [Numeric] observed round-trip time in milliseconds

reset() ¶

Clears all in-memory reputation data.

snapshot(host) ¶

Returns a frozen copy of the internal entry hash for host, or nil if the host is unknown and not in the store. - @param host [String] - @return [Hash, nil]