pub trait SurbAdmissionControl:
Send
+ Sync
+ 'static {
// Required methods
fn admit(
&self,
pseudonym: &SessionId,
expected_surbs: usize,
) -> AdmissionToken;
fn retire(&self, pseudonym: &SessionId, token: AdmissionToken);
// Provided method
fn raise_target(
&self,
_pseudonym: &SessionId,
_token: AdmissionToken,
_expected_surbs: usize,
) { ... }
}Expand description
Hands a SessionId in and out of the SURB store’s admission classes.
Without it every SURB that arrives for a Final packet — including the ones an established
Session legitimately depends on — lands in the un-admitted quarantine class, which caps
pseudonyms at a few SURBs each and expires them quickly (hoprnet#8515). The manager calls
admit at the point a Session becomes established — the slot
guard’s commit, not slot allocation, so that no peer is admitted before the Start handshake has
authenticated it — and retire at every teardown point.
Declared here rather than in the SURB store’s own crate because the two crates depend on each
other the wrong way round: the store cannot name the session crate, and this crate cannot name
hopr-protocol-hopr. hopr-transport is the only crate that sees both, so it supplies the
implementation bridging the two. Both methods are expected to be cheap and non-blocking; the
store side is idempotent, so a retire for a pseudonym that was never admitted is a no-op.
retire may run some time after the teardown that asked for it
— the closing Session’s own return-routed notification still needs its ring while the packet
pipeline resolves the route — and is therefore matched against the token admit returned: it
must be a no-op once token no longer names the pseudonym’s current admission, because a
successor Session can have been admitted on the same pseudonym in the meantime.
Required Methods§
Sourcefn admit(&self, pseudonym: &SessionId, expected_surbs: usize) -> AdmissionToken
fn admit(&self, pseudonym: &SessionId, expected_surbs: usize) -> AdmissionToken
Admits pseudonym into the store’s admitted class, sized for expected_surbs, and returns
the token naming this admission.
expected_surbs is the Session’s announced SURB buffer target, or the largest the node allows
when the Entry announced none; the store owns the headroom arithmetic and the floor, so a value
of 0 (target unknown) still yields a usable ring.
Calling this twice for the same pseudonym must not discard what the admitted ring already
holds, and invalidates the token the earlier admission returned.
Sourcefn retire(&self, pseudonym: &SessionId, token: AdmissionToken)
fn retire(&self, pseudonym: &SessionId, token: AdmissionToken)
Returns pseudonym to the un-admitted class, on behalf of the admission token names.
A no-op when token no longer names pseudonym’s current admission — a successor Session
was admitted in the meantime, and its ring is not this retire’s to release. Idempotent.
Provided Methods§
Sourcefn raise_target(
&self,
_pseudonym: &SessionId,
_token: AdmissionToken,
_expected_surbs: usize,
)
fn raise_target( &self, _pseudonym: &SessionId, _token: AdmissionToken, _expected_surbs: usize, )
Widens the ring of the admission token names to fit a target expected_surbs announced
after establishment.
The counterpart of admit for a target that changes mid-Session. A peer may
raise its SURB balancer target and say so in a keep-alive; the gnosis_vpn client ramps from a
ping tier to a main tier seconds after the Session opens (gnosis/gnosis_vpn#739). Without
this, the ring keeps the target the Session was admitted with, and every SURB minted toward
the larger one is evicted on arrival — under PIX, together with the share it carried.
Like retire, a token that no longer names the pseudonym’s current
admission is a no-op: a successor Session’s ring is not this announcement’s to widen. Widening
must keep the resident SURBs and the admission number, so that the token the Session holds
still names its admission and its teardown still releases it.
Defaults to a no-op, for implementations that do not size a per-Session ring.
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".