tower/discover/mod.rs
1//! Service discovery
2//!
3//! This module provides the [`Change`] enum, which indicates the arrival or departure of a service
4//! from a collection of similar services. Most implementations should use the [`Discover`] trait
5//! in their bounds to indicate that they can handle services coming and going. [`Discover`] itself
6//! is primarily a convenience wrapper around [`TryStream<Ok = Change>`][`TryStream`].
7//!
8//! Every discovered service is assigned an identifier that is distinct among the currently active
9//! services. If that service later goes away, a [`Change::Remove`] is yielded with that service's
10//! identifier. From that point forward, the identifier may be re-used.
11//!
12//! # Examples
13//!
14//! ```rust
15//! use futures_util::{future::poll_fn, pin_mut};
16//! use tower::discover::{Change, Discover};
17//! async fn services_monitor<D: Discover>(services: D) {
18//! pin_mut!(services);
19//! while let Some(Ok(change)) = poll_fn(|cx| services.as_mut().poll_discover(cx)).await {
20//! match change {
21//! Change::Insert(key, svc) => {
22//! // a new service with identifier `key` was discovered
23//! # let _ = (key, svc);
24//! }
25//! Change::Remove(key) => {
26//! // the service with identifier `key` has gone away
27//! # let _ = (key);
28//! }
29//! }
30//! }
31//! }
32//! ```
33//!
34//! [`TryStream`]: https://docs.rs/futures/latest/futures/stream/trait.TryStream.html
35
36mod list;
37
38pub use self::list::ServiceList;
39
40use crate::sealed::Sealed;
41use futures_core::TryStream;
42use std::{
43 pin::Pin,
44 task::{Context, Poll},
45};
46
47/// A dynamically changing set of related services.
48///
49/// As new services arrive and old services are retired,
50/// [`Change`]s are returned which provide unique identifiers
51/// for the services.
52///
53/// See the module documentation for more details.
54pub trait Discover: Sealed<Change<(), ()>> {
55 /// A unique identifier for each active service.
56 ///
57 /// An identifier can be re-used once a [`Change::Remove`] has been yielded for its service.
58 type Key: Eq;
59
60 /// The type of [`Service`] yielded by this [`Discover`].
61 ///
62 /// [`Service`]: crate::Service
63 type Service;
64
65 /// Error produced during discovery
66 type Error;
67
68 /// Yields the next discovery change set.
69 fn poll_discover(
70 self: Pin<&mut Self>,
71 cx: &mut Context<'_>,
72 ) -> Poll<Option<Result<Change<Self::Key, Self::Service>, Self::Error>>>;
73}
74
75impl<K, S, E, D: ?Sized> Sealed<Change<(), ()>> for D
76where
77 D: TryStream<Ok = Change<K, S>, Error = E>,
78 K: Eq,
79{
80}
81
82impl<K, S, E, D: ?Sized> Discover for D
83where
84 D: TryStream<Ok = Change<K, S>, Error = E>,
85 K: Eq,
86{
87 type Key = K;
88 type Service = S;
89 type Error = E;
90
91 fn poll_discover(
92 self: Pin<&mut Self>,
93 cx: &mut Context<'_>,
94 ) -> Poll<Option<Result<D::Ok, D::Error>>> {
95 TryStream::try_poll_next(self, cx)
96 }
97}
98
99/// A change in the service set.
100#[derive(Debug, Clone)]
101pub enum Change<K, V> {
102 /// A new service identified by key `K` was identified.
103 Insert(K, V),
104 /// The service identified by key `K` disappeared.
105 Remove(K),
106}