pub struct SurbStoreConfig {Show 16 fields
pub rb_capacity: usize,
pub pop_order: SurbPopOrder,
pub distress_threshold: usize,
pub max_openers_per_pseudonym: usize,
pub max_pseudonyms: usize,
pub pseudonyms_lifetime: Duration,
pub reply_opener_lifetime: Duration,
pub eviction_report_interval: Duration,
pub eviction_report_threshold: u64,
pub quarantine_rb_capacity: usize,
pub quarantine_max_pseudonyms: usize,
pub quarantine_lifetime: Duration,
pub quarantine_surb_budget: usize,
pub admitted_max_pseudonyms: usize,
pub admitted_headroom_percent: u32,
pub pending_surb_max_bytes: u64,
}Expand description
Configuration for the SURB cache.
The configuration options affect both the sending side (SURB creator) and the replying side (SURB consumer).
In the classical scenario (Entry - Relay 1 -... - Exit), the sending side is
the Entry and the replying side is the Exit.
Fields§
§rb_capacity: usizeSize of the SURB ring buffer per pseudonym.
Affects only the replying side.
This indicates how many SURBs can be at most held to be used to send a reply back to the sending side.
Once the buffer is full, a push evicts share-less SURBs first (oldest first); only when none
remain does it evict the oldest share-bearing SURB. An evicted SURB is never used. With PIX,
evicting one that carries a share is not merely a wasted SURB: a partial SSA share is only
delivered to the reconstructor when its SURB is used, so the share is lost for good. The
capacity is therefore sized well above what any Session’s SURB balancer targets — see
maximum_surb_buffer_size in hopr-transport, which is derived from this value with
headroom left for balancer overshoot.
This is a ceiling rather than a reservation: the internal SurbRingBuffer allocates with
occupancy, so a pseudonym holding three SURBs costs three, and only one that genuinely fills
up pays rb_capacity × ~400 B. That property is what makes a large default safe here — see
the “Why the capacity is a ceiling, not a reservation” section on SurbRingBuffer.
Default is 100 000.
pop_order: SurbPopOrderPop order of the per-pseudonym buffer; see SurbPopOrder.
FIFO is the only order, so this setting changes nothing. It is retained for configuration
compatibility — a file that spells out pop_order: fifo keeps loading — and is a candidate for
removal in a later major version. pop_order: lifo is no longer accepted and fails to load as an
unknown variant: PIX cannot work with LIFO, see SurbPopOrder for why.
Affects only the replying side. Default is SurbPopOrder::Fifo.
distress_threshold: usizeThreshold for the number of SURBs in the ring buffer, below which it is considered low (“SURB distress”).
Default is 500.
max_openers_per_pseudonym: usizeMaximum number of reply openers (SURB counterparts) per pseudonym.
Affects only the sending side when decrypting a received reply.
This mostly affects Sessions, as they use a fixed pseudonym. It reflects how many reply openers the initiator-side of a Session can hold, until the oldest ones are dropped. If the other party uses a SURB corresponding to a dropped reply opener, the reply message will be undecryptable by the initiator-side.
Default is 100 000.
max_pseudonyms: usizeRetained for configuration back-compat only; no longer bounds the SURB ring cache.
This used to size the single receiving-side SURB cache. The store now splits the receiving
side into the quarantine (bounded by SurbStoreConfig::quarantine_max_pseudonyms) and the
admitted class (bounded by SurbStoreConfig::admitted_max_pseudonyms), and this field
sizes nothing on the SURB path. Lowering it no longer bounds SURB memory — set those two
fields instead. It keeps its validator and serde default so an operator file that spells it
out still loads, and a later major version can remove it.
Default is 10 000.
pseudonyms_lifetime: DurationMaximum lifetime of ring-buffer for each pseudonym.
§Effects on sending side
This is the period for which we hold all reply openers for a pseudonym. If no more messages carrying SURBs are sent during this period, the entire stash of reply openers is dropped. Preventing receiving any more replies for that pseudonym.
§Effects on replying side
If a pseudonym has not received any SURBs for this period,
the entire ring buffer with rb_capacity (= all SURBs for this pseudonym) is dropped.
Preventing from sending any more replies for that pseudonym.
Default is 600 seconds.
reply_opener_lifetime: DurationMaximum lifetime of a reply opener.
Affects only the sending side.
A reply opener is distinguished using [HoprSurbId] and a pseudonym it belongs to.
If a reply opener is not used to decrypt the received packet within this period,
it is dropped. If the replying side uses the corresponding SURB to send a reply,
it won’t be possible to decrypt it when received.
Default is 3600 seconds.
eviction_report_interval: DurationHow often cache evictions are summarised in the log, per cache and cause, instead of per entry.
Affects both sides. Default is 60 seconds.
eviction_report_threshold: u64Evictions from one cache per report interval above which the summary is a warning rather than debug.
Lost PIX shares (ring_share) are exempt: they are permanent, so any count warns, however high
this is set. Dropped share-less SURBs (ring_plain) are not.
Affects both sides. Default is 1000.
quarantine_rb_capacity: usizePer-ring cap for quarantined pseudonyms — those no established Session stands behind.
Every HoprPacket::Final carrying SURBs reaches the store with no ticket verification on the
Final arm, so the pseudonym the packet names is chosen by the sender. An unadmitted batch
lands here, capped per ring so one pseudonym cannot reserve more than a packet’s worth of
return path (MAX_SURBS_IN_PACKET is 8, so 16 leaves headroom). A pseudonym is promoted out
of quarantine once a Session over it is established and SurbStore::admit fires; anything
left here expires after SurbStoreConfig::quarantine_lifetime.
Default is 16.
quarantine_max_pseudonyms: usizeCapacity of the quarantine cache: how many distinct unadmitted pseudonyms may hold a ring.
The quarantine is the only store an unauthenticated peer can write into, so it — not the
admitted cache below — is what pseudonym churn must be absorbed by. 1024 ×
quarantine_rb_capacity × ~400 B is a few MB. Beyond this many distinct pseudonyms, the
least-recently-used quarantine rings are shed; their SURBs are unadmitted, so nothing with a
Session behind it is lost.
Default is 1024.
quarantine_lifetime: DurationHow long a quarantined ring survives with no SURBs arriving for it.
Bounds the unadmitted class from the time side, the way SurbStoreConfig::pseudonyms_lifetime
bounds the admitted one. Must cover the worst-case Session-initiation window — the span between
the first Final packet minting a quarantine ring and the Session over it being established
(which promotes the ring) — i.e. roughly 2 × initiation_timeout_base × RoutingOptions::MAX_INTERMEDIATE_HOPS; the 60 s default clears that at both the 500 ms and the
5 s base for up to 3 intermediate hops.
Default is 60 seconds.
quarantine_surb_budget: usizeBackstop on the total number of unadmitted SURBs held across the whole quarantine cache.
The quarantine cache’s own entry and per-ring caps are the structural bound
(quarantine_max_pseudonyms × quarantine_rb_capacity); this counter is drained at insert time
and, when exhausted, sheds whole quarantine rings before refusing the batch. It exists so a
peer cannot rely on eviction timing: the accounting is exact at the mutation sites, so the two
bounds together cap the unadmitted class regardless of eviction scheduling. A backstop above
the cache’s own bound needs no precision — a refused batch costs only unadmitted SURBs, never
one an established Session is holding.
Default is 65 536.
admitted_max_pseudonyms: usizeCapacity of the admitted cache: how many pseudonyms with an established Session may hold a ring.
Admission goes through SurbStore::admit, which only an established Session triggers, so
unlike the quarantine this bound cannot be inflated by an unauthenticated peer. It is a
structural ceiling, not a per-insert counter: an admitted insert is never refused and an
admitted ring is never evicted to satisfy a counter. This value must be at least the node’s
maximum_managed_sessions; the transport logs an error at startup if it is not, and an
overflow here is reported as an admitted_overflow metric event.
Default is 10 000.
admitted_headroom_percent: u32Headroom the store adds over a Session’s announced SURB target when sizing its admitted ring.
A Session announces the buffer target it was configured with; the store admits a ring of
expected × (1 + admitted_headroom_percent / 100), floored at quarantine_rb_capacity and
ceiled at SurbStoreConfig::rb_capacity. The inverse relation to surb_buffer_target_ceiling
in hopr-transport (which sets the announced target at rb_capacity × 2/3) means an Entry
announcing its maximum yields a full-rb_capacity admitted ring at the default 50 %.
Default is 50.
pending_surb_max_bytes: u64Byte budget for each of the two Entry-side maps that remember minted SURBs until their reply comes home: the pending map and the written-off-legs map. Sending side only.
Each map holds as many records as fit in the budget at its own record size, evicting a random
record to admit a new one when full. The default 256 MiB holds about 454 000 pending records per
map (some 23 deployed-size stocks); both maps fill from it, so the pair peaks at about twice the
budget. Records the pending map could not hold are counted by hopr_surb_pending_lost_total, so
an undersized budget is visible.
The validator rejects a value outside MINIMUM_PENDING_SURB_MAX_BYTES (85 MB) to
MAXIMUM_PENDING_SURB_MAX_BYTES (4 GiB). MemorySurbStore does not read this field; only
hopr-transport’s HoprTransport::new does.
Default is 256 MiB.
Trait Implementations§
Source§impl Clone for SurbStoreConfig
impl Clone for SurbStoreConfig
Source§fn clone(&self) -> SurbStoreConfig
fn clone(&self) -> SurbStoreConfig
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read moreimpl Copy for SurbStoreConfig
Source§impl Debug for SurbStoreConfig
impl Debug for SurbStoreConfig
Source§impl Default for SurbStoreConfig
impl Default for SurbStoreConfig
Source§fn default() -> Self
fn default() -> Self
Return SurbStoreConfig { rb_capacity: default_rb_capacity(), pop_order: Default::default(), distress_threshold: default_distress_threshold(), max_openers_per_pseudonym: default_max_openers_per_pseudonym(), max_pseudonyms: default_max_pseudonyms(), pseudonyms_lifetime: default_pseudonyms_lifetime(), reply_opener_lifetime: default_reply_opener_lifetime(), eviction_report_interval: default_eviction_report_interval(), eviction_report_threshold: default_eviction_report_threshold(), quarantine_rb_capacity: default_quarantine_rb_capacity(), quarantine_max_pseudonyms: default_quarantine_max_pseudonyms(), quarantine_lifetime: default_quarantine_lifetime(), quarantine_surb_budget: default_quarantine_surb_budget(), admitted_max_pseudonyms: default_admitted_max_pseudonyms(), admitted_headroom_percent: default_admitted_headroom_percent(), pending_surb_max_bytes: default_pending_surb_max_bytes() }
impl Eq for SurbStoreConfig
Source§impl PartialEq for SurbStoreConfig
impl PartialEq for SurbStoreConfig
Source§impl PartialOrd for SurbStoreConfig
impl PartialOrd for SurbStoreConfig
impl StructuralPartialEq for SurbStoreConfig
Auto Trait Implementations§
impl Freeze for SurbStoreConfig
impl RefUnwindSafe for SurbStoreConfig
impl Send for SurbStoreConfig
impl Sync for SurbStoreConfig
impl Unpin for SurbStoreConfig
impl UnsafeUnpin for SurbStoreConfig
impl UnwindSafe for SurbStoreConfig
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key and return true if they are equal.§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
§impl<T> FutureExt for T
impl<T> FutureExt for T
§fn with_context(self, otel_cx: Context) -> WithContext<Self>
fn with_context(self, otel_cx: Context) -> WithContext<Self>
§fn with_current_context(self) -> WithContext<Self>
fn with_current_context(self) -> WithContext<Self>
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more