Skip to main content

SurbStoreConfig

Struct SurbStoreConfig 

Source
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: usize

Size 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: SurbPopOrder

Pop 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: usize

Threshold for the number of SURBs in the ring buffer, below which it is considered low (“SURB distress”).

Default is 500.

§max_openers_per_pseudonym: usize

Maximum 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: usize

Retained 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: Duration

Maximum 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: Duration

Maximum 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: Duration

How 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: u64

Evictions 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: usize

Per-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: usize

Capacity 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: Duration

How 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: usize

Backstop 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: usize

Capacity 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: u32

Headroom 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: u64

Byte 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

Source§

fn clone(&self) -> SurbStoreConfig

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Copy for SurbStoreConfig

Source§

impl Debug for SurbStoreConfig

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for SurbStoreConfig

Source§

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() }

Source§

impl Eq for SurbStoreConfig

Source§

impl PartialEq for SurbStoreConfig

Source§

fn eq(&self, other: &SurbStoreConfig) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl PartialOrd for SurbStoreConfig

Source§

fn partial_cmp(&self, other: &SurbStoreConfig) -> Option<Ordering>

This method returns an ordering between self and other values if one exists. Read more
1.0.0 (const: unstable) · Source§

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator. Read more
1.0.0 (const: unstable) · Source§

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 (const: unstable) · Source§

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 (const: unstable) · Source§

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator. Read more
Source§

impl StructuralPartialEq for SurbStoreConfig

Source§

impl Validate for SurbStoreConfig

Source§

fn validate(&self) -> Result<(), ValidationErrors>

Source§

impl<'v_a> ValidateArgs<'v_a> for SurbStoreConfig

Source§

type Args = ()

Source§

fn validate_with_args(&self, args: Self::Args) -> Result<(), ValidationErrors>

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DynClone for T
where T: Clone,

§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> FutureExt for T

§

fn with_context(self, otel_cx: Context) -> WithContext<Self>

Attaches the provided Context to this type, returning a WithContext wrapper. Read more
§

fn with_current_context(self) -> WithContext<Self>

Attaches the current Context to this type, returning a WithContext wrapper. Read more
§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts 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
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

impl<T> PolicyExt for T
where T: ?Sized,

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more