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
impl MemorySurbStore
Sourcepub fn new(cfg: SurbStoreConfig) -> Self
pub fn new(cfg: SurbStoreConfig) -> Self
Creates a new instance with the given configuration.
Sourcepub fn is_relayer_invalidated(&self, relayer: &HoprKeyIdent) -> bool
pub fn is_relayer_invalidated(&self, relayer: &HoprKeyIdent) -> bool
Whether relayer is currently unusable as a return path’s first hop.
Sourcepub fn admitted_ring_ceiling(&self, pseudonym: &HoprPseudonym) -> Option<usize>
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.
Sourcefn admitted_ring_capacity(&self, expected_surbs: usize) -> usize
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.
Sourcepub fn raise_admitted_capacity(
&self,
pseudonym: &HoprPseudonym,
token: u64,
expected_surbs: usize,
)
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.
Sourcefn ring_len(&self, pseudonym: &HoprPseudonym) -> usize
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.
Sourcefn record_ring_overflow(
&self,
outcome: &SurbInsertOutcome,
replaced_shares: usize,
)
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.
Sourcefn take_quarantine_ring(
&self,
pseudonym: &HoprPseudonym,
) -> Option<SurbRingBuffer<HoprSurb>>
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.
Sourcefn fold_quarantine_into(
&self,
pseudonym: &HoprPseudonym,
admitted: &SurbRingBuffer<HoprSurb>,
) -> Option<SurbInsertOutcome>
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.
Sourcefn push_into_admitted(
&self,
pseudonym: &HoprPseudonym,
admitted: &AdmittedRing,
surbs: Vec<(HoprSurbId, HoprSurb)>,
generation: u8,
) -> SurbInsertOutcome
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.
Sourcefn push_into_quarantine(
&self,
pseudonym: &HoprPseudonym,
surbs: Vec<(HoprSurbId, HoprSurb)>,
generation: u8,
) -> SurbInsertOutcome
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.
Sourcefn drain_quarantine_budget(&self, incoming: usize) -> usize
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.
Sourcefn insert_surbs_into_quarantine(
&self,
pseudonym: &HoprPseudonym,
surbs: Vec<(HoprSurbId, HoprSurb)>,
generation: u8,
) -> SurbInsertOutcome
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.
Sourcefn insert_surbs_into_admitted(
&self,
pseudonym: &HoprPseudonym,
admitted: AdmittedRing,
surbs: Vec<(HoprSurbId, HoprSurb)>,
generation: u8,
) -> SurbInsertOutcome
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.
Sourcefn is_surb_usable(&self, surb: &HoprSurb) -> bool
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
impl Clone for MemorySurbStore
Source§fn clone(&self) -> MemorySurbStore
fn clone(&self) -> MemorySurbStore
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read moreSource§impl Default for MemorySurbStore
impl Default for MemorySurbStore
Source§impl SurbStore for MemorySurbStore
impl SurbStore for MemorySurbStore
Source§fn admit(&self, pseudonym: &HoprPseudonym, expected_surbs: usize) -> u64
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)
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
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 insert_surbs(
&self,
pseudonym: HoprPseudonym,
surbs: Vec<(HoprSurbId, HoprSurb)>,
) -> SurbInsertOutcome
fn insert_surbs( &self, pseudonym: HoprPseudonym, surbs: Vec<(HoprSurbId, HoprSurb)>, ) -> SurbInsertOutcome
Source§fn tier_lens(&self, pseudonym: &HoprPseudonym) -> Option<(usize, usize)>
fn tier_lens(&self, pseudonym: &HoprPseudonym) -> Option<(usize, usize)>
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 moreSource§fn insert_reply_opener(&self, sender_id: HoprSenderId, opener: ReplyOpener)
fn insert_reply_opener(&self, sender_id: HoprSenderId, opener: ReplyOpener)
Source§fn invalidate_relayer(&self, relayer: &HoprKeyIdent)
fn invalidate_relayer(&self, relayer: &HoprKeyIdent)
relayer as unusable, so stored SURBs whose return path
starts there are no longer handed out. Read moreSource§fn revalidate_relayer(&self, relayer: &HoprKeyIdent)
fn revalidate_relayer(&self, relayer: &HoprKeyIdent)
Source§fn find_reply_opener(&self, sender_id: &HoprSenderId) -> Option<ReplyOpener>
fn find_reply_opener(&self, sender_id: &HoprSenderId) -> Option<ReplyOpener>
Source§fn remove_reply_opener(&self, sender_id: &HoprSenderId)
fn remove_reply_opener(&self, sender_id: &HoprSenderId)
ReplyOpener that has been used to deliver a reply. Read moreSource§fn current_generation(&self, pseudonym: &HoprPseudonym) -> u8
fn current_generation(&self, pseudonym: &HoprPseudonym) -> u8
pseudonym. Read moreSource§fn bump_generation(&self, pseudonym: &HoprPseudonym) -> u8
fn bump_generation(&self, pseudonym: &HoprPseudonym) -> u8
pseudonym and returns the new value. Read moreAuto Trait Implementations§
impl !RefUnwindSafe for MemorySurbStore
impl !UnwindSafe for MemorySurbStore
impl Freeze for MemorySurbStore
impl Send for MemorySurbStore
impl Sync for MemorySurbStore
impl Unpin for MemorySurbStore
impl UnsafeUnpin for MemorySurbStore
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<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