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