Struct BalancerStateValues 

pub struct BalancerStateValues {
    pub target_surb_buffer_size: AtomicU64,
    pub max_surbs_per_sec: AtomicU64,
    pub decay_duration_msec: AtomicU64,
    pub decay_volume_pct: AtomicU8,
    pub buffer_level: AtomicU64,
    pub sustain_on_return_path_loss: AtomicBool,
    pub counterparty_buffer_capacity: AtomicU64,
    pub return_path_degraded_until_ms: AtomicU64,
    pub counterparty_in_surb_distress: AtomicBool,
}

Runtime state of the SurbBalancer.

Fields

target_surb_buffer_size: AtomicU64

max_surbs_per_sec: AtomicU64

decay_duration_msec: AtomicU64

decay_volume_pct: AtomicU8

buffer_level: AtomicU64

sustain_on_return_path_loss: AtomicBool

Whether this session opted into sustaining production through return-path loss.

counterparty_buffer_capacity: AtomicU64

How many SURBs the counterparty can physically hold, or 0 when unknown.

The estimate is produced - consumed, and consumption is only observed once a reply arrives – so a return path that drops replies lets the believed level grow without bound. The counterparty’s store is a ring buffer that evicts the oldest entry on overflow, so everything above its capacity was discarded on arrival and was never a real level. Measured during an outage: 51 917 believed against a 15 000-entry store.

Why evictions are not subtracted from the level

The counterparty reports its evictions (num_evicted_surbs on the incoming packet), so the level could be corrected to the exact truth instead of merely bounded here. It deliberately is not, because the clamp below is max(capacity, target) rather than capacity: a level inflated past a full buffer still climbs to the target and shuts organic production off, whereas an accurate level pins at the counterparty’s real capacity. If that capacity is below the target – which nothing prevents, since this figure is the local store size and the counterparty may be smaller – the accurate level never reaches the target, production never stops, and the buffer evicts forever. The imprecise estimate fails safe and the precise one does not, so the eviction count stays an observability signal.

return_path_degraded_until_ms: AtomicU64

Milliseconds from the crate-internal EPOCH monotonic origin until which the return path counts as degraded.

A deadline rather than a flag: it is set by a layer that observes the return path and read here, and nothing is guaranteed to come back and clear it. Expiring on its own bounds the damage of a marker that is never withdrawn to a short over-production instead of a session that mints forever.

counterparty_in_surb_distress: AtomicBool

Whether the counterparty’s last packet said it was running low on SURBs of its own.

A plain flag with no deadline, unlike return_path_degraded_until_ms above, because the two fail in opposite directions: a degraded-path marker that is never withdrawn makes this side mint forever, whereas a distress flag that is never withdrawn merely keeps organic production at one SURB per packet — the behaviour that predates the gate. A flag whose stuck state is the old behaviour does not need to expire.

It clears on its own in the normal case: the counterparty recomputes both SURB signals on every return packet and strips them once its pool recovers, so the next healthy packet resets this.

Last write wins, and the signal is recorded at dispatch – ahead of Session sequencing – so a reordered clean packet can clear a distress signal the counterparty sent after it. That costs the safety valve rather than the recovery: surb_decay subtracts from the level estimate on a timer regardless of what any packet says, so once the estimate falls back under target both this gate and the keep-alives reopen on their own.

How long that takes is a property of the configuration, not a guarantee of this type. It scales with the decay rate and with how far above target the estimate sits, and the max(capacity, target) clamp bounds the latter only while counterparty_buffer_capacity is known – its 0 (“unknown”) arm leaves the estimate unclamped. With decay switched off the estimate does not drain on its own at all, and only a fresh distress signal or observed consumption reopens the gate.

Sequencing the flag would buy a faster reopen, at the cost of making a hot-path signal depend on the Session’s reassembly.

Implementations

impl BalancerStateValues

pub fn new(cfg: SurbBalancerConfig) -> Self

Constructor from a SurbBalancerConfig.

pub fn update(&self, cfg: &SurbBalancerConfig)

Performs update of the BalancerStateValues from the SurbBalancerConfig and enables it.

pub fn set_counterparty_buffer_capacity(&self, capacity: u64)

Declares how many SURBs the counterparty’s store can hold, bounding the level estimate.

Taken from the session manager’s maximum_surb_buffer_size, which is the same capacity already used to clamp a counterparty’s requested target. Zero leaves the estimate unbounded.

fn clamp_to_counterparty_capacity(&self, level: u64) -> u64

Caps level at what the counterparty can actually hold.

Never below the configured target: a target above the counterparty’s capacity is unreachable by construction, and clamping to capacity there would hold the error permanently negative and pin production at maximum forever – a worse failure than the unbounded estimate this exists to prevent. In that configuration the capacity figure is simply not usable for this session.

pub fn observe_counterparty_signals(&self, signals: PacketSignals)

Records what the counterparty’s latest packet said about its own SURB supply.

Takes the whole signal set rather than a bool so the containment rule lives here: OutOfSurbs is a superset of SurbDistress on the wire, so contains catches both, whereas an equality match against SurbDistress would silently ignore the more severe of the two.

pub fn organic_surbs_per_packet(&self) -> usize

Returns the number of organic SURBs to attach to an outgoing Session data packet.

Only the Entry uses this value. Return 0 when the estimated counterparty buffer has reached its target. Return 1 when balancing is disabled, the estimate is below target, or the counterparty signals SURB distress.

This method uses the raw buffer estimate. During return-path loss, a zero estimate correctly keeps organic SURB production enabled.

pub fn mark_return_path_degraded(&self, grace: Duration)

Marks the return path as degraded for the next grace period.

Called by whichever layer can actually tell a dead return path from a quiet peer – from here the two are indistinguishable, since neither delivers replies. Re-marking simply extends the window.

pub fn return_path_estimate_is_stale(&self) -> bool

Whether buffer_level is currently an instruction rather than a measurement.

While this holds, the controller deliberately writes 0 into the level to drive production to its maximum. That zero says “produce flat out”, not “the counterparty holds nothing”, so anything reading the level as a supply ceiling must consult this first or it will read the instruction as an order to send nothing.

True only when both the opt-in (sustain_on_return_path_loss) and live evidence (mark_return_path_degraded, within its window) are present: without the opt-in this is not our behaviour to change, and without evidence there is nothing to tell a dead return path from an idle one.

pub because it is not only the controller’s business — hence the emphasis above on what the flag does not mean. It is not a general “the return path is degraded” signal.

fn should_sustain_through_return_path_loss(&self) -> bool

pub fn as_config(&self) -> SurbBalancerConfig

Extracts the SurbBalancerConfig from the BalancerStateValues.

pub fn is_disabled(&self) -> bool

Checks if SURB balancing is disabled (no target buffer size set).

pub fn surb_decay(&self) -> Option<(Duration, f64)>

Extracts the SURB decay configuration from the BalancerStateValues.

pub fn buffer_level(&self) -> u64

Gets the current estimated SURB buffer level.

pub fn controller_bounds(&self) -> BalancerControllerBounds

Returns the current BalancerControllerBounds from the BalancerStateValues.

Trait Implementations

impl Debug for BalancerStateValues

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BalancerStateValues

fn default() -> BalancerStateValues

Returns the “default value” for a type.

impl From<SurbBalancerConfig> for BalancerStateValues

fn from(cfg: SurbBalancerConfig) -> Self

Converts to this type from the input type.