dynomite-engine 0.0.1

Embeddable Dynamo-style distributed replication engine: token-ring partitioning, gossip cluster, hinted handoff, anti-entropy, RediSearch FT.* surface.
Documentation 
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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

//! Public embedding API for the Dynomite engine.
//!
//! `dynomite::embed` is the surface an embedding program uses to
//! construct, run, observe, and shut down a Dynomite engine
//! in-process. The same surface drives the [`dynomited`] binary;
//! the binary is a thin wrapper around this module rather than a
//! parallel code path.
//!
//! # Two-tier API
//!
//! 1. [`Server::builder`] returns a [`ServerBuilder`] - a typed,
//!    fluent, validated-at-`build` builder that mirrors every
//!    YAML-visible [`crate::conf::ConfPool`] field plus typed
//!    setters for hook traits with no YAML form.
//! 2. [`Server::start`] returns immediately; the tokio runtime
//!    owns the background work. The caller drives the running
//!    server through a [`ServerHandle`].
//!
//! # Hooks
//!
//! Five public traits expose every cross-cutting concern an
//! embedder may want to override:
//!
//! * [`hooks::Datastore`] - backing store (Redis / Memcache /
//!   custom).
//! * [`hooks::SeedsProvider`] - service discovery integration.
//! * [`hooks::CryptoProvider`] - HSM / KMS integration.
//! * [`hooks::MetricsSink`] - exporter integration.
//! * [`crate::io::reactor::Transport`] - already exposed by
//!   `io::reactor`; re-exported here as
//!   [`Transport`](crate::embed::Transport) for discoverability.
//!
//! Every trait has at least one default implementation shipped
//! in-crate, and the crate-root re-exports below mean a typical
//! embedder writes
//! `use dynomite::embed::{Server, ServerBuilder, ServerHandle};`
//! without reaching into the submodules.
//!
//! # Examples
//!
//! ```no_run
//! use dynomite::embed::{Server, ServerBuilder};
//! use dynomite::conf::DataStore;
//! # tokio::runtime::Builder::new_multi_thread().enable_all().build().unwrap().block_on(async {
//! let server: Server = ServerBuilder::new("dyn_o_mite")
//!     .listen("127.0.0.1:0".parse().unwrap())
//!     .dyn_listen("127.0.0.1:0".parse().unwrap())
//!     .data_store(DataStore::Redis)
//!     .servers(vec![dynomite::conf::ConfServer::parse("127.0.0.1:6379:1").unwrap()])
//!     .tokens_str("0")
//!     .build()
//!     .unwrap();
//! let handle = server.start().await.unwrap();
//! assert_eq!(handle.peers().len(), 1);
//! handle.shutdown().await.unwrap();
//! # });
//! ```
//!
//! [`dynomited`]: ../../dynomited/index.html

pub mod builder;
pub mod error;
pub mod events;
pub mod hooks;
pub mod server;
pub mod snapshots;

pub use crate::io::reactor::{ConnRole, TcpTransport, Transport};

pub use self::builder::ServerBuilder;
pub use self::error::EmbedError;
pub use self::events::{
    CloseReason, ConnId, ConnRoleTag, EventStream, PeerDownReason, PeerId, ServerEvent,
};
pub use self::hooks::{
    BoxFuture, CryptoProvider, CryptoProviderError, Datastore, DatastoreError, DnsSeedsProvider,
    FloridaSeedsProvider, LoggingMetricsSink, MemcacheDatastore, MemoryDatastore, MetricsError,
    MetricsSink, Protocol, RedisDatastore, RustCryptoProvider, SeedsProvider, SimpleSeedsProvider,
};
pub use self::server::{Server, ServerHandle};
pub use self::snapshots::{DatacenterSnapshot, PeerSnapshot, RackSnapshot, RingSnapshot};

impl Server {
    /// Convenience entry point.
    ///
    /// # Examples
    ///
    /// ```
    /// use dynomite::embed::Server;
    /// let _b = Server::builder("dyn_o_mite");
    /// ```
    #[must_use]
    pub fn builder(pool_name: impl Into<String>) -> ServerBuilder {
        ServerBuilder::new(pool_name)
    }

    /// One-shot "validate, build, and start" helper.
    ///
    /// Equivalent to calling `builder.build()?.start().await`. The
    /// chained-call form remains available for embedders that
    /// want to inspect the [`Server`] before spawning tasks; this
    /// helper exists because most embedders only ever build then
    /// immediately start.
    ///
    /// # Errors
    ///
    /// Returns the same [`EmbedError`] variants that
    /// [`ServerBuilder::build`] and [`Server::start`] surface.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use dynomite::embed::{Server, ServerBuilder};
    /// use dynomite::conf::DataStore;
    /// # tokio::runtime::Builder::new_multi_thread().enable_all().build().unwrap().block_on(async {
    /// let builder = ServerBuilder::new("dyn_o_mite")
    ///     .listen("127.0.0.1:0".parse().unwrap())
    ///     .dyn_listen("127.0.0.1:0".parse().unwrap())
    ///     .data_store(DataStore::Redis)
    ///     .servers(vec![dynomite::conf::ConfServer::parse("127.0.0.1:6379:1").unwrap()])
    ///     .tokens_str("0");
    /// let handle = Server::start_with(builder).await.unwrap();
    /// handle.shutdown().await.unwrap();
    /// # });
    /// ```
    pub async fn start_with(builder: ServerBuilder) -> Result<ServerHandle, EmbedError> {
        builder.build()?.start().await
    }
}