shep_client/lib.rs
1//! Async client for the shep daemon: connect-or-spawn state machine, typed
2//! wrappers for every RPC verb, and event-bus subscription streams. This is
3//! the programmatic API embedders use; the CLI is a thin consumer of it.
4//!
5//! Re-exports [`shep_core`] so downstream users need a single dependency.
6//!
7//! # Quick start
8//! ```
9//! use shep_client::shep_core::prelude::MemSize;
10//!
11//! let limit: MemSize = "512M".parse().unwrap();
12//! assert_eq!(limit.bytes(), 512 << 20);
13//! ```
14//!
15//! Module-by-module design: `docs/systematic-refactor/refactor-workspace/map.md`.
16
17#![doc(test(attr(deny(warnings))))]
18#![forbid(unsafe_code)]
19
20// the `dog_config` attribute expands to `impl ::shep_client::dogs::DogConfig`,
21// a path this crate has no other way to name for its own tests
22extern crate self as shep_client;
23
24// portable: `connection` names `shep_core::transport::ClientStream`, not
25// `tokio::net::UnixStream`, so the OS choice is made one crate down.
26// `spawn`'s exit-code contract reads `ExitStatus::code()`, portable already.
27mod actor;
28mod client;
29mod connection;
30// public: a dog is a third-party binary, so this module is the API it's
31// written against; kept as a module rather than flattened, like `spawn`
32pub mod dogs;
33mod events;
34mod reconnect;
35mod ssh;
36// inherent methods on `Client` and `ReconnectingClient`, one per typed request
37mod typed;
38// public module, not a flattened re-export, so `spawn::DAEMON_ALREADY_RUNNING`
39// reads as a qualified cross-crate contract. Plain `//`, not `///`: an outer
40// doc on a `mod` item merges into the crate root and breaks this module's
41// own intra-doc links.
42pub mod spawn;
43pub use client::{
44 Client, DEADLINE_GRACE, DEFAULT_DEADLINE, LOG_PLANE_DEADLINE, RELOAD_DEADLINE, RequestError,
45 START_DEADLINE, STOP_DEADLINE, TRIGGER_DEADLINE,
46};
47pub use connection::{ConnectError, HANDSHAKE_TIMEOUT};
48pub use events::{EventStream, Lagged};
49/// The trait [`EventStream`] implements.
50///
51/// Re-exported because there is no stable `core::stream::Stream`. The trait
52/// is otherwise unnameable in a caller's bound without a `futures-util`
53/// dependency. Pulling one event at a time needs no import:
54/// [`EventStream::next`] is an inherent method.
55///
56/// # Example
57///
58/// Writing the bound with no `futures-util` in the caller's own manifest:
59///
60/// ```
61/// use shep_client::{EventStream, Stream};
62///
63/// fn _pending_hint<S: Stream>(stream: &S) -> Option<usize> {
64/// stream.size_hint().1
65/// }
66///
67/// // And the type that bound exists to accept. A live one comes from
68/// // `Client::subscribe`, which needs a daemon; naming it does not.
69/// fn _accepts(events: &EventStream) -> Option<usize> {
70/// _pending_hint(events)
71/// }
72/// ```
73#[doc(inline)]
74pub use futures_util::Stream;
75pub use reconnect::{
76 LinkLost, LinkState, RECONNECT_MAX_DELAY, RECONNECT_MIN_DELAY, Reconnected, ReconnectingClient,
77};
78pub use ssh::{SshCause, SshOptions};
79
80// Portable for the same reason as `connection` above: every fake here binds
81// a `shep_core::transport::Listener` rather than a `UnixListener`.
82#[cfg(any(test, feature = "test-support"))]
83pub mod testing;
84
85pub use shep_core;
86
87// Pins the `schema` feature's forward to `shep-core/schema`: a dog reaches
88// these two through the re-export above, so a missing forward costs it a
89// second dependency it should never name. Workspace feature unification
90// hides that everywhere except `cargo check -p shep-client`.
91#[cfg(feature = "schema")]
92const _: () = {
93 const fn assert_json_schema<T: schemars::JsonSchema>() {}
94 assert_json_schema::<shep_core::values::MemSize>();
95 assert_json_schema::<shep_core::values::UpDuration>();
96};
97
98/// The wire protocol this client speaks, re-exported from
99/// [`shep_core::protocol::PROTOCOL_VERSION`].
100///
101/// Reachable from this crate's own root because a dog depends on this
102/// crate and nothing else, and `docs/dogs.md` asks every dog to print it.
103/// A re-export rather than a copy: a second definition could disagree with
104/// the value the handshake compares.
105pub use shep_core::protocol::PROTOCOL_VERSION;
106
107#[cfg(test)]
108mod tests {
109 /// Not an assertion, just a line of output where a wrong number would
110 /// otherwise pass in silence.
111 ///
112 /// The five integration binaries require `test-support`. Cargo skips a
113 /// target whose required features are off without a word. A bare
114 /// `cargo test -p shep-client` then reports a fraction of this crate's
115 /// tests as the whole. This case compiles only when the feature is off.
116 #[cfg(not(feature = "test-support"))]
117 #[test]
118 fn heads_up_five_integration_binaries_need_test_support_and_are_not_running() {
119 assert!(
120 !cfg!(feature = "test-support"),
121 "compiled only when the feature is off"
122 );
123 }
124}