Struct Router

pub struct Router { /* private fields */ }

An actual router class

Note: when router is shut down (when config stream is closed), all futures and subscriptions are canceled.

Since 0.1.3: when all instances of Router are dropped the underlying futures and streams continue to work, until all of them finish (for subscriptions it means subscriber is dropped). In previous versions this dropped all requests immediately. This was common source of confusion and we consider this a bug. If you want to force close all futures and subscriptions create a router with from_stream or updating_config and send EOS on stream or drop UpdatingSink respectively.

Implementations

impl Router

pub fn from_config(config: &Arc<Config>, handle: &Handle) -> Router

Create a router for a static config

pub fn from_stream<S>(stream: S, handle: &Handle) -> Router

where S: Stream<Item = Arc<Config>, Error = Void> + 'static,

Create a router with updating config

Note: router is defunctional until first config is received in a stream. By defunctional we mean that every request will wait, until configured.

Note 2: when stream is closed router is shut down, so usually the stream must be infinite.

pub fn updating_config( config: &Arc<Config>, handle: &Handle, ) -> (Router, UpdateSink)

Create a router and update channel

Note: router is shut down when UpdateSink is dropped. So keep it somewhere so you can update config.

pub fn subscribe_many<'x, I>(&self, iter: I, default_port: u16) -> AddrStream

where I: IntoIterator, I::Item: Into<AutoName<'x>>,

Subscribes to a list of names

This is intended to keep list of services in configuration file, like this (yaml):

addresses:
- example.org:8080
- _my._svc.example.org  # SVC record
- example.net           # default port

You can also specify a way to resolve the service by providing iterator over AutoName instances instead of plain &str (both are accepted in this method).

pub fn subscribe_many_stream<'x, S>( &self, stream: S, default_port: u16, ) -> AddrStream

where S: Stream + Send + 'static, S::Item: IntoIterator, S::Error: Display, <S::Item as IntoIterator>::Item: Into<AutoName<'x>>,

👎Deprecated since 0.1.1: use subscribe_stream()

Subscribes to a stream that yields lists of names

See the description of subscribe_many for the description of the list of names that must be yielded from the stream.

Note: this is meant for configuration update scenario. I.e. when configuration is reloaded and new list of names is received, it should be pushed to this stream. The items received in the stream are non-cumulative and replace previous list.

Note 2: If stream is errored or end-of-stream reached, this means name is not needed any more and its AddrStream will be shut down, presumably shutting down everything that depends on it.

pub fn subscribe_stream<S>(&self, stream: S, default_port: u16) -> AddrStream

where S: Stream + Send + 'static, S::Error: Display, for<'x> S::Item: IntoNameIter<'x>,

Subscribes to a stream that yields lists of names

See the description of subscribe_many for the description of the list of names that must be yielded from the stream.

Note: this is meant for configuration update scenario. I.e. when configuration is reloaded and new list of names is received, it should be pushed to this stream. The items received in the stream are non-cumulative and replace previous list.

Note 2: If stream is errored or end-of-stream reached, this means name is not needed any more and its AddrStream will be shut down, presumably shutting down everything that depends on it.

pub fn resolve_auto<'x, N: Into<AutoName<'x>>>( &self, name: N, default_port: u16, ) -> ResolveFuture

Resolve a string or other things into an address

See description of subscribe_many to find out how names are parsed

See AutoName for supported types

AutoName:

Trait Implementations

impl Clone for Router

fn clone(&self) -> Router

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Router

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl HostResolve for Router

type HostFuture = ResolveHostFuture

A future returned from resolve()

fn resolve_host(&self, name: &Name) -> ResolveHostFuture

Resolve a name to an address once

fn frozen_host_subscriber(self) -> FrozenSubscriber<Self>

where Self: Sized,

Create a subscriber that resolves once using this resolver and never updates a stream

fn null_service_resolver(self) -> NullResolver<Self>

where Self: Sized,

Create a thing that implements Resolve+HostResolve but returns NameNotFound on resolve

impl HostSubscribe for Router

type HostError = Void

An error type returned by a stream

type HostStream = HostStream

A stream returned from subscribe()

fn subscribe_host(&self, name: &Name) -> HostStream

Resolve a name and subscribe to the updates

impl Resolve for Router

type Future = ResolveFuture

A future returned from resolve()

fn resolve(&self, name: &Name) -> ResolveFuture

Resolve a name to an address once

fn frozen_subscriber(self) -> FrozenSubscriber<Self>

where Self: Sized + Resolve,

Create a subscriber that resolves once using this resolver and never updates a stream

fn frozen_service_subscriber(self) -> FrozenSubscriber<Self>

where Self: Sized,

Create a subscriber that resolves once using this resolver and never updates a stream

fn null_host_resolver(self) -> NullHostResolver<Self>

where Self: Sized,

Create a thing that implements Resolve+HostResolve but returns NameNotFound on resolve_host

impl Subscribe for Router

type Error = Void

An error type returned by a stream

type Stream = AddrStream

A stream returned from subscribe()

fn subscribe(&self, name: &Name) -> AddrStream

Resolve a name and subscribe to the updates