Skip to main content

MemorySurbStore

Struct MemorySurbStore 

Source
pub struct MemorySurbStore {
    pseudonym_openers: Cache<SimplePseudonym, Cache<[u8; 8], ReplyOpener>>,
    admitted_surbs_per_pseudonym: Cache<SimplePseudonym, AdmittedRing>,
    quarantine_surbs: Cache<SimplePseudonym, SurbRingBuffer<SURB<Ed25519Suite, HoprSphinxHeaderSpec>>>,
    quarantine_budget: Arc<Atomic<usize>>,
    invalidated_relayers: Arc<RwLock<RawRwLock, HashSet<KeyIdent>>>,
    generations: Cache<SimplePseudonym, Arc<Atomic<u8>>>,
    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<SimplePseudonym, Cache<[u8; 8], ReplyOpener>>§admitted_surbs_per_pseudonym: Cache<SimplePseudonym, AdmittedRing>§quarantine_surbs: Cache<SimplePseudonym, SurbRingBuffer<SURB<Ed25519Suite, HoprSphinxHeaderSpec>>>§quarantine_budget: Arc<Atomic<usize>>§invalidated_relayers: Arc<RwLock<RawRwLock, HashSet<KeyIdent>>>§generations: Cache<SimplePseudonym, Arc<Atomic<u8>>>§stats: Arc<EvictionStats>§cfg: Arc<SurbStoreConfig>

Implementations§

Source§

impl MemorySurbStore

Source

pub fn new(cfg: SurbStoreConfig) -> MemorySurbStore

Creates a new instance with the given configuration.

Source

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

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

Source

pub fn admitted_ring_ceiling( &self, pseudonym: &SimplePseudonym, ) -> 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

pub fn raise_admitted_capacity( &self, pseudonym: &SimplePseudonym, 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.

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

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

impl SurbStore for MemorySurbStore

Source§

fn admit(&self, pseudonym: &SimplePseudonym, 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: &SimplePseudonym, 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: SimplePseudonym, surbs: Vec<([u8; 8], SURB<Ed25519Suite, HoprSphinxHeaderSpec>)>, ) -> SurbInsertOutcome

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

fn tier_lens(&self, pseudonym: &SimplePseudonym) -> 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: &KeyIdent)

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: &KeyIdent)

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: &SimplePseudonym) -> u8

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

fn bump_generation(&self, pseudonym: &SimplePseudonym) -> 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
§

impl<T> Conv for T

§

fn conv<T>(self) -> T
where Self: Into<T>,

Converts self into T using Into<T>. Read more
Source§

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

§

impl<T> FmtForward for T

§

fn fmt_binary(self) -> FmtBinary<Self>
where Self: Binary,

Causes self to use its Binary implementation when Debug-formatted.
§

fn fmt_display(self) -> FmtDisplay<Self>
where Self: Display,

Causes self to use its Display implementation when Debug-formatted.
§

fn fmt_lower_exp(self) -> FmtLowerExp<Self>
where Self: LowerExp,

Causes self to use its LowerExp implementation when Debug-formatted.
§

fn fmt_lower_hex(self) -> FmtLowerHex<Self>
where Self: LowerHex,

Causes self to use its LowerHex implementation when Debug-formatted.
§

fn fmt_octal(self) -> FmtOctal<Self>
where Self: Octal,

Causes self to use its Octal implementation when Debug-formatted.
§

fn fmt_pointer(self) -> FmtPointer<Self>
where Self: Pointer,

Causes self to use its Pointer implementation when Debug-formatted.
§

fn fmt_upper_exp(self) -> FmtUpperExp<Self>
where Self: UpperExp,

Causes self to use its UpperExp implementation when Debug-formatted.
§

fn fmt_upper_hex(self) -> FmtUpperHex<Self>
where Self: UpperHex,

Causes self to use its UpperHex implementation when Debug-formatted.
§

fn fmt_list(self) -> FmtList<Self>
where &'a Self: for<'a> IntoIterator,

Formats each item in a sequence. 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> Pipe for T
where T: ?Sized,

§

fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> R
where Self: Sized,

Pipes by value. This is generally the method you want to use. Read more
§

fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> R
where R: 'a,

Borrows self and passes that borrow into the pipe function. Read more
§

fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> R
where R: 'a,

Mutably borrows self and passes that borrow into the pipe function. Read more
§

fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
where Self: Borrow<B>, B: 'a + ?Sized, R: 'a,

Borrows self, then passes self.borrow() into the pipe function. Read more
§

fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R, ) -> R
where Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more
§

fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
where Self: AsRef<U>, U: 'a + ?Sized, R: 'a,

Borrows self, then passes self.as_ref() into the pipe function.
§

fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
where Self: AsMut<U>, U: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.as_mut() into the pipe function.
§

fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
where Self: Deref<Target = T>, T: 'a + ?Sized, R: 'a,

Borrows self, then passes self.deref() into the pipe function.
§

fn pipe_deref_mut<'a, T, R>( &'a mut self, func: impl FnOnce(&'a mut T) -> R, ) -> R
where Self: DerefMut<Target = T> + Deref, T: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.deref_mut() into the pipe function.
§

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
§

impl<T> Tap for T

§

fn tap(self, func: impl FnOnce(&Self)) -> Self

Immutable access to a value. Read more
§

fn tap_mut(self, func: impl FnOnce(&mut Self)) -> Self

Mutable access to a value. Read more
§

fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Immutable access to the Borrow<B> of a value. Read more
§

fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Mutable access to the BorrowMut<B> of a value. Read more
§

fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Immutable access to the AsRef<R> view of a value. Read more
§

fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Mutable access to the AsMut<R> view of a value. Read more
§

fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Immutable access to the Deref::Target of a value. Read more
§

fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Mutable access to the Deref::Target of a value. Read more
§

fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self

Calls .tap() only in debug builds, and is erased in release builds.
§

fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self

Calls .tap_mut() only in debug builds, and is erased in release builds.
§

fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Calls .tap_borrow() only in debug builds, and is erased in release builds.
§

fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds.
§

fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Calls .tap_ref() only in debug builds, and is erased in release builds.
§

fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Calls .tap_ref_mut() only in debug builds, and is erased in release builds.
§

fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Calls .tap_deref() only in debug builds, and is erased in release builds.
§

fn tap_deref_mut_dbg<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Calls .tap_deref_mut() only in debug builds, and is erased in release builds.
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
§

impl<T> TryConv for T

§

fn try_conv<T>(self) -> Result<T, Self::Error>
where Self: TryInto<T>,

Attempts to convert self into T using TryInto<T>. 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