Skip to main content

SurbAdmissionControl

Trait SurbAdmissionControl 

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

Source

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.

Source

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§

Source

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".

Implementors§