Skip to main content

MemorySurbStore

Struct MemorySurbStore 

Source
pub struct MemorySurbStore {
    pseudonym_openers: Cache<HoprPseudonym, Cache<HoprSurbId, ReplyOpener>>,
    admitted_surbs_per_pseudonym: Cache<HoprPseudonym, AdmittedRing>,
    quarantine_surbs: Cache<HoprPseudonym, SurbRingBuffer<HoprSurb>>,
    quarantine_budget: Arc<AtomicUsize>,
    invalidated_relayers: Arc<RwLock<HashSet<HoprKeyIdent>>>,
    generations: Cache<HoprPseudonym, Arc<AtomicU8>>,
    stats: Arc<EvictionStats>,
    cfg: Arc<SurbStoreConfig>,
}
Expand description

Basic SurbStore implementation based on an in-memory cache.

This SURB store offers no persistence, and all SURBs and Reply Openers are lost once dropped.

The instance can be cheaply cloned.

Fields§

§pseudonym_openers: Cache<HoprPseudonym, Cache<HoprSurbId, ReplyOpener>>§admitted_surbs_per_pseudonym: Cache<HoprPseudonym, AdmittedRing>

Receiving-side rings for admitted pseudonyms: those an established Session stands behind, entered only through SurbStore::admit and left through SurbStore::retire.

This cache is also the single source of truth for admission: there is no separate admission-marker cache for insert_surbs to route on, because a marker in one cache pointing at a ring in another can desync (an eviction on one side, an insert on the other) and admits can race inserts. SurbStore::insert_surbs takes the entry here, so a pseudonym is admitted exactly as long as it holds one — even an empty one, which is what admit inserts so that standing is known before the first SURB arrives.

The value carries the admission’s number next to the ring, so a deferred SurbStore::retire can prove it is retiring the admission it was created for and not a successor’s — see AdmittedRing. The number and the ring share one entry so the compare in retire and the removal are one atomic operation over the key.

§quarantine_surbs: Cache<HoprPseudonym, SurbRingBuffer<HoprSurb>>

Receiving-side rings for quarantined pseudonyms: whatever pseudonym a Final packet chose and no Session has claimed.

Physically separate from admitted_surbs_per_pseudonym rather than a tier of it, so quarantine churn — pseudonym flooding, short TTI expiries, budget drains — can never evict an admitted ring. That is a structural guarantee: the two caches share no capacity or eviction machinery.

§quarantine_budget: Arc<AtomicUsize>

Count of SURBs currently held in quarantine_surbs, across all its rings.

Drained at the two quarantine mutation sites (insert and find) and corrected by the eviction listener, so it needs no resync pass — an opportunistic resync would be a CPU/lock amplifier running on exactly the attacker-flooded state. It is a backstop, not the structural bound: the cache’s own max_capacity × quarantine_rb_capacity is the hard bound, and a few SURBs of drift between a ring.len() read and the listener cannot exceed it.

Refunds saturate at zero rather than wrapping: the refund sites read ring lengths without the ring lock, so a stale reader could otherwise drive the counter past zero and permanently lock out every quarantine insert — see refund_quarantine_budget.

§invalidated_relayers: Arc<RwLock<HashSet<HoprKeyIdent>>>

Relayers this node can no longer pay. Holds at most a handful of entries (our own closing channels), so a plain set behind an RwLock beats a concurrent map on this read-heavy path.

§generations: Cache<HoprPseudonym, Arc<AtomicU8>>

Current SURB-batch generation per pseudonym we originate for (sending side). Advanced on a return-path change so the replying side can drop SURBs for the superseded path.

This is sending-side state, so it is retained like the reply openers (pseudonym_openers) — not like the receiving-side admitted_surbs_per_pseudonym. If this entry were evicted while the peer still held SURBs of generation N, current_generation would fall back to 0; the peer’s SurbRingBuffer::push_counting then reads generation_is_newer(0, N) as false (for 1 <= N <= 128) and silently discards every fresh batch, stranding the reply path. Both dimensions are therefore taken from the sending-side reply-opener config, not the receiving-side SURB config: reply_opener_lifetime bounds how long we expect replies (hence outstanding SURBs) for a pseudonym, and it is >= the peer’s SURB idle window, so the serial outlives the SURBs it numbers; and the capacity matches the reply-opener pseudonym bound (max_openers_per_pseudonym, which covers maximum_managed_sessions) so LRU pressure from the unrelated receiving-side max_pseudonyms cannot evict a live sender’s generation.

§stats: Arc<EvictionStats>§cfg: Arc<SurbStoreConfig>

Implementations§

Source§

impl MemorySurbStore

Source

pub fn new(cfg: SurbStoreConfig) -> Self

Creates a new instance with the given configuration.

Source

pub fn is_relayer_invalidated(&self, relayer: &HoprKeyIdent) -> bool

Whether relayer is currently unusable as a return path’s first hop.

Source

pub fn admitted_ring_ceiling(&self, pseudonym: &HoprPseudonym) -> Option<usize>

Ceiling on how many SURBs the admitted ring for pseudonym can hold, or None when it holds no admitted ring.

Observability seam: the ceiling is what an announced target has to raise, since a Session whose ring is too narrow loses SURBs — and, under PIX, the shares they carried — the moment the Entry mints past it.

Note this is a cache get, so it records recency on the admitted cache’s LRU. Every live Session holds a ring and the cache is sized for that census, so a read here cannot evict one; it is only a diagnostic, not a hot path.

Source

fn admitted_ring_capacity(&self, expected_surbs: usize) -> usize

Capacity for a newly created admitted ring, derived from the Session’s announced SURB target.

The target gets SurbStoreConfig::admitted_headroom_percent of headroom — the balancer aims below the ring’s ceiling, so a ring exactly the size of the target would overflow on ordinary overshoot — then is floored at quarantine_rb_capacity and ceiled at the operator’s rb_capacity. An announced target of 0 means “no announcement” and gets the floor: a ring of one is a trap the very next packet overflows, and nothing cheaper than the quarantine floor is worth admitting.

Source

pub fn raise_admitted_capacity( &self, pseudonym: &HoprPseudonym, token: u64, expected_surbs: usize, )

Widens pseudonym’s admitted ring for an announced SURB target that changed mid-Session.

admit sizes the ring once, from the target in force at establishment, and a peer may raise that target afterwards: the gnosis_vpn client ramps its balancer from a ping tier to a main tier seconds into the Session and announces each step (see gnosis/gnosis_vpn#739). Left alone, the ring keeps the first tier’s ceiling while the Entry mints toward the new one — every SURB past the ceiling is evicted on arrival, and under PIX so is the share it carried, which is unrecoverable.

The re-admission path already grows a ring in place (SurbRingBuffer::raise_capacity is a fetch_max, so it only ever widens). This is that path, for a peer rather than a successor Session: it mints no new admission number, so the token the Session already holds still names this admission and its teardown retires it as before. A token that no longer names the pseudonym’s current admission is a no-op, for the same reason a stale retire is.

expected_surbs is the announced target, not a ring size: the headroom, floor and ceiling arithmetic is this store’s, exactly as in admit.

Source

fn ring_len(&self, pseudonym: &HoprPseudonym) -> usize

SURBs held for pseudonym across both classes.

Sums the two caches rather than asking one, so the brief dual-ring state around a promotion — a batch that routed to the quarantine just before admit installed the admitted entry, and that sits there until its insert’s post-push re-check folds it in — cannot under-report what the pseudonym holds.

Source

fn record_ring_overflow( &self, outcome: &SurbInsertOutcome, replaced_shares: usize, )

Books what a ring-buffer push dropped into the eviction summary, split by what it cost, and the replaced_shares a generation change took out of play.

Source

fn take_quarantine_ring( &self, pseudonym: &HoprPseudonym, ) -> Option<SurbRingBuffer<HoprSurb>>

Removes pseudonym’s quarantine ring, if it has one, and refunds what it held to the budget.

The removal is an and_compute_with, not a plain remove, because that is what serialises it against push_into_quarantine: moka runs computes on one key one at a time, but a remove does not join that queue. With a plain remove, a push that had already looked the ring up could land its batch after the removal had drained the ring — in a ring no cache holds any more, where no lookup ever finds it. Serialised, a push either finishes before the removal (and its batch leaves with the ring) or starts after it (and creates a fresh ring, which its own post-push re-check then folds).

Op::Remove is an explicit removal the quarantine listener skips, so the refund is made here.

Source

fn fold_quarantine_into( &self, pseudonym: &HoprPseudonym, admitted: &SurbRingBuffer<HoprSurb>, ) -> Option<SurbInsertOutcome>

Moves everything pseudonym’s quarantine ring holds into admitted, removing the quarantine ring. Returns what the push into admitted did, or None if there was nothing to move.

The ring is drained as it stands: a promoted SURB already earned its slot, and the push into admitted is judged against the admitted ceiling, not the quarantine’s.

Source

fn push_into_admitted( &self, pseudonym: &HoprPseudonym, admitted: &AdmittedRing, surbs: Vec<(HoprSurbId, HoprSurb)>, generation: u8, ) -> SurbInsertOutcome

Pushes a batch into an admitted ring, after folding in whatever a quarantine ring for the same pseudonym still holds.

The fold-in is re-done here rather than left to admit, because an insert that routed to the quarantine just before admit installed this entry can leave a ring behind there — and because admit itself must not be called again: it would mint a fresh admission number the manager’s token no longer names, leaving the Session’s deferred retire matching nothing while the entry it stamped holds a number no retire will ever present.

It is also why only admit creates an admitted entry: an insert that minted one itself would have no admission number to stamp, and a ring stamped with the sentinel is one no retire ever removes.

The outcome adds what the fold-in evicted and superseded to what the push did, as the quarantine arm does: those SURBs were booked when their packets arrived, and the decoder can book their leaving only from this outcome.

Source

fn push_into_quarantine( &self, pseudonym: &HoprPseudonym, surbs: Vec<(HoprSurbId, HoprSurb)>, generation: u8, ) -> SurbInsertOutcome

Pushes a batch into pseudonym’s quarantine ring, creating the ring if it has none, and books the change in the quarantine budget.

The push runs inside an and_compute_with so it is serialised against take_quarantine_ring — see there for the batch a plain lookup would lose. The budget is booked inside the compute too: a promotion queued behind this push refunds what the ring holds as soon as the compute ends, and an increment landing after that refund would count SURBs the quarantine no longer holds. The delta is taken against this ring’s own length, read in the same compute, so a push that evicted and re-inserted nets out.

Source

fn drain_quarantine_budget(&self, incoming: usize) -> usize

Sheds whole quarantine rings until incoming more SURBs fit under the quarantine budget, or no ring that holds anything is left. Returns how many rings it shed.

The victims are uniformly untrusted, so their order is arbitrary — moka’s iter gives no order to lean on. Rings a lookup has already emptied are skipped: they free no budget, and choosing them would spend a pass on nothing while rings that do hold SURBs stay put. Each pass sheds a bounded number of rings, so an insert at saturation frees room for several after it rather than draining one ring per insert; passes repeat only while the batch still does not fit, and their number is capped by what the cache can hold, so a counter that drifted above what the rings actually hold costs one sweep of the quarantine, not a loop.

The rings are collected before any is removed: moka holds the cache lock for a live iter, so a removal inside it would deadlock against itself.

Source

fn insert_surbs_into_quarantine( &self, pseudonym: &HoprPseudonym, surbs: Vec<(HoprSurbId, HoprSurb)>, generation: u8, ) -> SurbInsertOutcome

The quarantine arm of SurbStore::insert_surbs, split out so a test can drive it directly: it is reached when insert_surbs’ admission lookup found no entry, and the interesting case — admit landing between that lookup and the push here — cannot be forced from outside.

That case is why the push is followed by a re-check. admit installs the admitted entry first and promotes the quarantine ring second, so a batch pushed here either lands before the promotion (and is promoted with the ring) or after it, when the entry is already in place and the re-check below finds it and folds the batch in. Without the re-check the batch would sit in a quarantine ring that find_surb no longer consults — it reads the admitted ring once one exists — until a later admitted insert happened to fold it in, or the quarantine’s TTI, cap or budget drain discarded it.

Source

fn insert_surbs_into_admitted( &self, pseudonym: &HoprPseudonym, admitted: AdmittedRing, surbs: Vec<(HoprSurbId, HoprSurb)>, generation: u8, ) -> SurbInsertOutcome

The admitted arm of SurbStore::insert_surbs, split out so a test can drive it directly: it is reached when insert_surbs’ admission lookup finds an entry, which is only ever the one admit installed — no insert may create one — and cannot be forced from outside.

admitted is the entry the real admit installed, carrying the admission number the SessionManager threads back to retire. It is used as it stands rather than admit being called again: a second admit would mint a fresh number the manager’s token no longer names, and the deferred retire would then match nothing, leaking the Session’s ring until its teardown never comes. What is re-done here is only the fold-in of a quarantine ring, which an insert that routed there just before admit installed this entry can have left behind.

Source

fn is_surb_usable(&self, surb: &HoprSurb) -> bool

Whether a stored SURB can still be used to reply: its first relayer must still be payable.

A direct return path is exempt — its “first relayer” is the final recipient, which needs no channel (RFC-0003 §3.2, RFC-0006 §6.1). Without that exemption, closing an unrelated channel to a session’s originator would discard perfectly good SURBs.

Trait Implementations§

Source§

impl Clone for MemorySurbStore

Source§

fn clone(&self) -> MemorySurbStore

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 Default for MemorySurbStore

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl SurbStore for MemorySurbStore

Source§

fn admit(&self, pseudonym: &HoprPseudonym, expected_surbs: usize) -> u64

Admits pseudonym into the store’s admitted class, behind an established Session.

Called once the Session over the pseudonym is established, and never on a mere packet’s say-so, so the admitted class stays out of any unauthenticated peer’s reach. expected_surbs is the Session’s announced SURB target; the store adds its own headroom and floors at quarantine_rb_capacity — an unknown target (0) is treated as “no announcement” and gets the floor, not a one-SURB ring.

Returns the number naming this admission, which the caller threads to SurbStore::retire. Every call mints a fresh one and invalidates the previous, so a retire issued on behalf of a superseded admission matches nothing — that is the guard that makes the deferred retire safe to schedule.

Any quarantine ring for the pseudonym is promoted rather than left behind to expire: the SURBs arrived for this very Session. A ring arrives here only while the pseudonym is unadmitted (insert_surbs routes on admission), so an admitted entry this finds already in place is one a previous admission left behind — insert_surbs never creates one — and the promotion fills it rather than discarding what it holds.

The admitted entry is installed before the quarantine ring is promoted, not after. That order is what lets an insert racing this admission re-check after its quarantine push: a push that lands after the promotion can only do so once the entry is already in place, so the insert’s re-check finds it and folds the batch in. Promoting first would leave a window — promotion done, entry not yet installed — in which a push and its re-check could both slip through, stranding the batch in a quarantine ring find_surb no longer consults.

Source§

fn retire(&self, pseudonym: &HoprPseudonym, token: u64)

Retires pseudonym from the admitted class: its Session is over.

Only the admitted class is touched — a rolled-back or unestablished Session’s preload SURBs belong to the quarantine, where their short TTI expires them without any teardown bookkeeping. Idempotent: retiring a pseudonym that holds no admitted ring is a no-op.

token names the admission the teardown is retiring, and the retire is honoured only while it still matches the pseudonym’s current one. The retire runs deferred, past the packet pipeline’s SURB-resolution window, because the closing Session’s own return-routed notification still needs its ring — long enough for a successor Session to have been admitted on the same client-chosen pseudonym. Dropping the successor’s ring there would silently degrade its return path with nothing logged anywhere, which is exactly what the token exists to prevent: a stale retire leaves the successor’s ring, and its epoch, exactly as they are.

Source§

fn surbs_held(&self) -> usize

Total SURBs held across both classes. Test and observability seam, not a hot path: it walks the admitted cache and reads the quarantine budget.

Source§

fn find_surb(&self, matcher: SurbMatcher) -> Option<FoundSurb>

Tries to find SURB using the given matcher. Read more
Source§

fn insert_surbs( &self, pseudonym: HoprPseudonym, surbs: Vec<(HoprSurbId, HoprSurb)>, ) -> SurbInsertOutcome

Stores the surbs and associates them with the given pseudonym. Read more
Source§

fn tier_lens(&self, pseudonym: &HoprPseudonym) -> Option<(usize, usize)>

How many SURBs are held for pseudonym in each of the store’s tiers, as (share-bearing, share-less), or None if the store holds no SURBs for it or does not tell its SURBs apart that way. Read more
Source§

fn insert_reply_opener(&self, sender_id: HoprSenderId, opener: ReplyOpener)

Stores the given opener for the given sender_id. Read more
Source§

fn invalidate_relayer(&self, relayer: &HoprKeyIdent)

Marks the edge from this node to relayer as unusable, so stored SURBs whose return path starts there are no longer handed out. Read more
Source§

fn revalidate_relayer(&self, relayer: &HoprKeyIdent)

Reverts SurbStore::invalidate_relayer once the channel towards relayer re-opens. Read more
Source§

fn find_reply_opener(&self, sender_id: &HoprSenderId) -> Option<ReplyOpener>

Tries to find a ReplyOpener given the sender_id, without consuming it. Read more
Source§

fn remove_reply_opener(&self, sender_id: &HoprSenderId)

Removes a ReplyOpener that has been used to deliver a reply. Read more
Source§

fn current_generation(&self, pseudonym: &HoprPseudonym) -> u8

Current SURB-batch generation to stamp into SURBs minted for pseudonym. Read more
Source§

fn bump_generation(&self, pseudonym: &HoprPseudonym) -> u8

Advances the SURB-batch generation for pseudonym and returns the new value. Read more

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,

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