pub struct PathPlanner<Surb, R, S> {
me: OffchainPublicKey,
pub surb_store: Surb,
paths: Arc<PathBuilder<R, S>>,
cache: Cache<(OffchainPublicKey, OffchainPublicKey, u32), Arc<(u64, WeightedCollection<ValidatedPath>)>>,
refresh_period: Duration,
probe_budget: Arc<ProbeBudget>,
observer: Option<TransportObserver>,
}Expand description
Path planner that resolves [DestinationRouting] to [ResolvedTransportRouting].
The planner delegates path discovery to any PathSelector implementation and
owns the moka cache of fully-validated [ValidatedPath] objects paired with
their traversal cost, keyed by (source: NodeId, destination: NodeId, hops: u32).
On a cache miss the planner calls the selector, validates every candidate against
the chain resolver, and stores an Arc<WeightedCollection<ValidatedPath>> in the
cache. On a cache hit a candidate is picked via weighted random selection (higher
cost = higher quality = higher probability).
A background sweep (background_refresh) can be spawned to
proactively re-warm the cache for all previously-seen keys.
Fields§
§me: OffchainPublicKey§surb_store: Surb§paths: Arc<PathBuilder<R, S>>§cache: Cache<(OffchainPublicKey, OffchainPublicKey, u32), Arc<(u64, WeightedCollection<ValidatedPath>)>>§refresh_period: Duration§probe_budget: Arc<ProbeBudget>See IMPLAUSIBLE_PROBE_INTERVAL; shared by every clone of the planner.
observer: Option<TransportObserver>Implementations§
Source§impl<Surb, R, S> PathPlanner<Surb, R, S>
impl<Surb, R, S> PathPlanner<Surb, R, S>
Sourcepub fn new(
me: OffchainPublicKey,
surb_store: Surb,
resolver: R,
selector: S,
config: PathPlannerConfig,
) -> Self
pub fn new( me: OffchainPublicKey, surb_store: Surb, resolver: R, selector: S, config: PathPlannerConfig, ) -> Self
Create a new path planner.
me is this node’s OffchainPublicKey; it is used as the source in path queries.
Sourcepub fn with_observer(self, observer: TransportObserver) -> Self
pub fn with_observer(self, observer: TransportObserver) -> Self
Report path resolves to observer. Attach it before the planner is shared.
Sourcepub(crate) fn configure_selector(&mut self, configure: impl FnOnce(&mut S))
pub(crate) fn configure_selector(&mut self, configure: impl FnOnce(&mut S))
Configure the owned selector without changing existing planner clones.
Sourcefn record_resolution(
&self,
source: NodeId,
destination: NodeId,
succeeded: bool,
)
fn record_resolution( &self, source: NodeId, destination: NodeId, succeeded: bool, )
Report an outcome using canonical peer identity, retaining unresolved chain addresses.
Sourceasync fn resolve_node_id_to_offchain_key(
&self,
node_id: &NodeId,
) -> Result<OffchainPublicKey>
async fn resolve_node_id_to_offchain_key( &self, node_id: &NodeId, ) -> Result<OffchainPublicKey>
Resolve a [NodeId] to an OffchainPublicKey.
Sourceasync fn resolve_path(
&self,
source: NodeId,
destination: NodeId,
options: RoutingOptions,
) -> Result<ValidatedPath>
async fn resolve_path( &self, source: NodeId, destination: NodeId, options: RoutingOptions, ) -> Result<ValidatedPath>
Report the result of each forward resolution, including cache hits and failures.
Sourceasync fn resolve_path_inner(
&self,
source: NodeId,
destination: NodeId,
options: RoutingOptions,
) -> Result<ValidatedPath>
async fn resolve_path_inner( &self, source: NodeId, destination: NodeId, options: RoutingOptions, ) -> Result<ValidatedPath>
Resolve cached or newly selected paths while retaining validation and cache semantics.
Sourceasync fn cached_paths(
&self,
source: NodeId,
destination: NodeId,
hops: BoundedSize<{ RoutingOptions::MAX_INTERMEDIATE_HOPS }>,
) -> Result<Arc<(u64, WeightedCollection<ValidatedPath>)>>
async fn cached_paths( &self, source: NodeId, destination: NodeId, hops: BoundedSize<{ RoutingOptions::MAX_INTERMEDIATE_HOPS }>, ) -> Result<Arc<(u64, WeightedCollection<ValidatedPath>)>>
Cached weighted collection of validated hops-hop paths from source to destination,
computed on a miss.
Single-path callers draw with pick_one; batch callers (see
PathPlanner::resolve_diverse_return_paths) work over the collection directly, paying one
cache lookup instead of one per path.
Sourcepub(crate) async fn refresh_cached_paths(&self)
pub(crate) async fn refresh_cached_paths(&self)
Runs one background sweep now: called when relayer health in the graph changes, so cached
paths follow it at once instead of up to PathPlannerConfig::refresh_period later.
Sourcepub async fn recompute_paths_from(&self, source: &OffchainPublicKey) -> usize
pub async fn recompute_paths_from(&self, source: &OffchainPublicKey) -> usize
Rebuilds every cached entry whose paths originate at source, replacing each in place.
Return paths are cached under (counterparty, me, hops), so this is how a caller that has
just learned a counterparty’s return traffic went silent forces those weights to be rebuilt
from the current graph, instead of waiting up to
PathPlannerConfig::refresh_period for the background sweep to reach them.
Entries are replaced, never dropped: one that rebuilds to nothing keeps serving what it already holds. Dropping them was measured to collapse a healthy session from 100 % to 0.14 %, because a live session draws its next return path from this very entry.
Returns how many entries came back with a materially different share of the draws – not how many were rebuilt. Callers use this to decide whether the re-plan achieved anything worth acting on, and on a healthy graph a rebuild always succeeds, so counting rebuilds would answer “something moved” every time.
Sourceasync fn resolve_diverse_return_paths(
&self,
destination: NodeId,
options: RoutingOptions,
count: usize,
) -> Result<Vec<ValidatedPath>>
async fn resolve_diverse_return_paths( &self, destination: NodeId, options: RoutingOptions, count: usize, ) -> Result<Vec<ValidatedPath>>
Resolves count return paths from destination back to this node, drawn weighted-random
over PathPlannerConfig::return_path_weight_temper-flattened path values.
Tempering is what bounds the blast radius of losing one relay: raw path values concentrate a session’s SURBs on the few best candidates, so the flatter the effective distribution, the smaller any single relay’s share of the return stream.
Draws are independent — deliberately. Spreading a batch over K distinct relayers was tried
and cannot work: a batch is the SURBs that fit in one packet (HoprPacket::PAYLOAD_SIZE / HoprSurb::SIZE, a handful at most), so K was capped by it whatever the configuration said,
while each packet re-drew independently regardless. Tempering has no such ceiling.
Neither spreads anything the candidates do not offer: the selector searches each first
relayer’s paths separately (compute_paths_spread), so a pool names every first relayer
the graph allows rather than the one or two a single depth-first search reached first.
Only Hops routing has alternatives to draw over — an explicit path resolves to itself, so
those fall back to plain repeated resolution.
Sourceasync fn resolve_diverse_return_paths_inner(
&self,
destination: NodeId,
options: RoutingOptions,
count: usize,
) -> Result<Vec<ValidatedPath>>
async fn resolve_diverse_return_paths_inner( &self, destination: NodeId, options: RoutingOptions, count: usize, ) -> Result<Vec<ValidatedPath>>
Draw return paths from cached or rebuilt candidates while preserving path diversity.
Sourcepub async fn resolve_routing(
&self,
size_hint: usize,
max_surbs: usize,
routing: DestinationRouting,
) -> Result<(ResolvedTransportRouting<HoprSurb>, Option<usize>, Option<u8>)>
pub async fn resolve_routing( &self, size_hint: usize, max_surbs: usize, routing: DestinationRouting, ) -> Result<(ResolvedTransportRouting<HoprSurb>, Option<usize>, Option<u8>)>
Resolve a [DestinationRouting] to a [ResolvedTransportRouting].
Returns the resolved routing and, for Return variants, the number of remaining SURBs.
Trait Implementations§
Source§impl<Surb, R, S> BackgroundPathCacheRefreshable for PathPlanner<Surb, R, S>
impl<Surb, R, S> BackgroundPathCacheRefreshable for PathPlanner<Surb, R, S>
Source§fn run_background_refresh(&self) -> impl Future<Output = ()> + Send + 'static
fn run_background_refresh(&self) -> impl Future<Output = ()> + Send + 'static
Returns a future that runs the background path-cache refresh loop.
The returned future iterates over all keys currently in the planner’s cache and recomputes their paths on a configurable schedule, so that steady-state traffic is always served from cache.
Auto Trait Implementations§
impl<Surb, R, S> !RefUnwindSafe for PathPlanner<Surb, R, S>
impl<Surb, R, S> !UnwindSafe for PathPlanner<Surb, R, S>
impl<Surb, R, S> Freeze for PathPlanner<Surb, R, S>where
Surb: Freeze,
impl<Surb, R, S> Send for PathPlanner<Surb, R, S>
impl<Surb, R, S> Sync for PathPlanner<Surb, R, S>
impl<Surb, R, S> Unpin for PathPlanner<Surb, R, S>where
Surb: Unpin,
impl<Surb, R, S> UnsafeUnpin for PathPlanner<Surb, R, S>where
Surb: UnsafeUnpin,
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> Conv for T
impl<T> Conv for T
§impl<T> FmtForward for T
impl<T> FmtForward for T
§fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
self to use its Binary implementation when Debug-formatted.§fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
self to use its Display implementation when
Debug-formatted.§fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
self to use its LowerExp implementation when
Debug-formatted.§fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
self to use its LowerHex implementation when
Debug-formatted.§fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
self to use its Octal implementation when Debug-formatted.§fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
self to use its Pointer implementation when
Debug-formatted.§fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
self to use its UpperExp implementation when
Debug-formatted.§fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
self to use its UpperHex implementation when
Debug-formatted.§fn fmt_list(self) -> FmtList<Self>where
&'a Self: for<'a> IntoIterator,
fn fmt_list(self) -> FmtList<Self>where
&'a Self: for<'a> IntoIterator,
§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§impl<T> Pipe for Twhere
T: ?Sized,
impl<T> Pipe for Twhere
T: ?Sized,
§fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
§fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
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) -> Rwhere
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
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
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
§fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R,
) -> R
fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R, ) -> R
§fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
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
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
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
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
self, then passes self.deref() into the pipe function.§impl<T> Pointable for T
impl<T> Pointable for T
§impl<T> PolicyExt for Twhere
T: ?Sized,
impl<T> PolicyExt for Twhere
T: ?Sized,
impl<T> Read<Exclusive, BecauseExclusive> for Twhere
T: ?Sized,
§impl<T> Tap for T
impl<T> Tap for T
§fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
Borrow<B> of a value. Read more§fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
BorrowMut<B> of a value. Read more§fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
AsRef<R> view of a value. Read more§fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
AsMut<R> view of a value. Read more§fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
Deref::Target of a value. Read more§fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
Deref::Target of a value. Read more§fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
.tap() only in debug builds, and is erased in release builds.§fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
.tap_mut() only in debug builds, and is erased in release
builds.§fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
.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
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
.tap_borrow_mut() only in debug builds, and is erased in release
builds.§fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
.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
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
.tap_ref_mut() only in debug builds, and is erased in release
builds.§fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
.tap_deref() only in debug builds, and is erased in release
builds.