ns_router/
lib.rs

1//! A full-featured router for abstract-ns
2//!
3//! A router should be an entry point for your application. It solves two
4//! purposes:
5//!
6//! 1. Allow to use different name resolution mechanisms without cluttering
7//!    your app with too much generics
8//! 2. Optimize performance: we connect to resolvers via channels, so polling
9//!    an `ResolveFuture` or `AddrStream` is cheap.
10//!
11//! # Example
12//!
13//! A simple resolver you should start with:
14//!
15//! ```rust
16//! # use std::time::Duration;
17//! # extern crate tokio_core;
18//! extern crate abstract_ns;
19//! extern crate ns_router;
20//! extern crate ns_std_threaded;
21//! use abstract_ns::HostResolve;
22//! use ns_router::SubscribeExt;
23//!
24//! # fn main() {
25//! # let core = tokio_core::reactor::Core::new().unwrap();
26//! let ns = ns_router::Router::from_config(&ns_router::Config::new()
27//!     .set_fallthrough(ns_std_threaded::ThreadedResolver::new()
28//!         .null_service_resolver()
29//!         .interval_subscriber(Duration::new(1, 0), &core.handle()))
30//!     .done(),
31//!     &core.handle());
32//! # }
33//!
34//! ```
35//!
36//! This is a bit verbose, but this means:
37//!
38//! 1. Use stdlib resolver
39//! 2. Do not resolve SRV (stdlib resolver can't do that)
40//! 3. Poll for a new address every second (for subscriptions)
41//!
42//! # Names in Configs
43//!
44//! You should use [`resolve_auto`] and [`subscribe_many`] for resolving
45//! names that come from configuration files. In it's simplest form it
46//! accepts a string:
47//!
48//! ```rust,ignore
49//! ns.resolve_auto("localhost:8080")
50//! ns.resolve_auto("_xmpp-server._tcp.gmail.com")   // if resolver has SRV
51//! ```
52//!
53//! But you may force specific mode:
54//! ```rust.ignore
55//! use ns_router::AutoName::*;
56//! ns.resolve_auto(Service("localhost"));   // resolve bare `localhost` as SRV
57//! ```
58//!
59//! All the same forms work for `subscribe_many` and `subscribe_many_stream`
60//!
61//! # Updating Names
62//!
63//! If you're writing server you might need to react on name changes.
64//! `abstract-ns` gives you a way to `subscribe` for the name.
65//!
66//! Router gives you a little bit more:
67//!
68//! 1. You can create router with [`from_stream`] or [`updating_config`] and
69//!    push configuration updates to router.
70//! 2. The [`subscribe_many_stream`] method allows to subsribe to a stream of
71//!    names: i.e. every time your user changes list of names to be used for
72//!    some service, new names are resolved and applied immediately.
73//!
74//! Both kinds of updates are delivered to the application as a next update
75//! in a stream without any additional code on receiver side.
76//!
77//! [`resolve_auto`]: struct.Router.html#method.resolve_auto
78//! [`subscribe_many`]: struct.Router.html#method.subscribe_many
79//! [`subscribe_many_stream`]: struct.Router.html#method.subscribe_many_stream
80//! [`from_stream`]: struct.Router.html#method.from_stream
81//! [`updating_config`]: struct.Router.html#method.updating_config
82//!
83//! # Configuring Router
84//!
85//! To show you an example how router can be configured:
86//!
87//! ```rust,ignore
88//! let cfg = &Config::new()
89//!     // resolution of hosts from memory for performance or tests
90//!     .add_host(&"localhost".parse().unwrap(),
91//!               vec!["127.0.0.1".parse().unwrap()])
92//!     // resolve `.consul` names via consul DNS SRV or HTTP
93//!     .add_suffix("consul", consul_resolver)
94//!     // use stdlib for other things
95//!     .set_fallthrough(std_resolver)
96//!     .done();
97//!
98//! ```
99//!
100#![warn(missing_docs)]
101#![warn(missing_debug_implementations)]
102
103extern crate abstract_ns;
104extern crate async_slot;
105extern crate futures;
106extern crate tokio_core;
107extern crate void;
108#[macro_use] extern crate log;
109#[macro_use] extern crate quick_error;
110
111mod config;
112mod coroutine;
113mod fuse;
114mod internal;
115mod internal_traits;
116mod multisubscr;
117mod name;
118mod router;
119mod subscr;
120pub mod future;
121pub mod subscribe_ext;
122
123pub use router::Router;
124pub use config::Config;
125pub use name::{AutoName, IntoNameIter};
126pub use subscribe_ext::SubscribeExt;
127
128trait AssertTraits: Clone + Send + Sync {}
129impl AssertTraits for Router {}
ns_router/lib.rs

ns_router/
lib.rs
