shep-client 0.22.0

Async client for the shep daemon: typed requests, event subscriptions, and starting a shepherd that is not running yet
Documentation
//! Async client for the shep daemon: connect-or-spawn state machine, typed
//! wrappers for every RPC verb, and event-bus subscription streams. This is
//! the programmatic API embedders use; the CLI is a thin consumer of it.
//!
//! Re-exports [`shep_core`] so downstream users need a single dependency.
//!
//! # Quick start
//! ```
//! use shep_client::shep_core::prelude::MemSize;
//!
//! let limit: MemSize = "512M".parse().unwrap();
//! assert_eq!(limit.bytes(), 512 << 20);
//! ```
//!
//! Module-by-module design: `docs/systematic-refactor/refactor-workspace/map.md`.

#![doc(test(attr(deny(warnings))))]
#![forbid(unsafe_code)]

// the `dog_config` attribute expands to `impl ::shep_client::dogs::DogConfig`,
// a path this crate has no other way to name for its own tests
extern crate self as shep_client;

// portable: `connection` names `shep_core::transport::ClientStream`, not
// `tokio::net::UnixStream`, so the OS choice is made one crate down.
// `spawn`'s exit-code contract reads `ExitStatus::code()`, portable already.
mod actor;
mod client;
mod connection;
// public: a dog is a third-party binary, so this module is the API it's
// written against; kept as a module rather than flattened, like `spawn`
pub mod dogs;
mod events;
mod reconnect;
mod ssh;
// inherent methods on `Client` and `ReconnectingClient`, one per typed request
mod typed;
// public module, not a flattened re-export, so `spawn::DAEMON_ALREADY_RUNNING`
// reads as a qualified cross-crate contract. Plain `//`, not `///`: an outer
// doc on a `mod` item merges into the crate root and breaks this module's
// own intra-doc links.
pub mod spawn;
pub use client::{
    Client, DEADLINE_GRACE, DEFAULT_DEADLINE, LOG_PLANE_DEADLINE, RELOAD_DEADLINE, RequestError,
    START_DEADLINE, STOP_DEADLINE, TRIGGER_DEADLINE,
};
pub use connection::{ConnectError, HANDSHAKE_TIMEOUT};
pub use events::{EventStream, Lagged};
/// The trait [`EventStream`] implements.
///
/// Re-exported because there is no stable `core::stream::Stream`. The trait
/// is otherwise unnameable in a caller's bound without a `futures-util`
/// dependency. Pulling one event at a time needs no import:
/// [`EventStream::next`] is an inherent method.
///
/// # Example
///
/// Writing the bound with no `futures-util` in the caller's own manifest:
///
/// ```
/// use shep_client::{EventStream, Stream};
///
/// fn _pending_hint<S: Stream>(stream: &S) -> Option<usize> {
///     stream.size_hint().1
/// }
///
/// // And the type that bound exists to accept. A live one comes from
/// // `Client::subscribe`, which needs a daemon; naming it does not.
/// fn _accepts(events: &EventStream) -> Option<usize> {
///     _pending_hint(events)
/// }
/// ```
#[doc(inline)]
pub use futures_util::Stream;
pub use reconnect::{
    LinkLost, LinkState, RECONNECT_MAX_DELAY, RECONNECT_MIN_DELAY, Reconnected, ReconnectingClient,
};
pub use ssh::{SshCause, SshOptions};

// Portable for the same reason as `connection` above: every fake here binds
// a `shep_core::transport::Listener` rather than a `UnixListener`.
#[cfg(any(test, feature = "test-support"))]
pub mod testing;

pub use shep_core;

// Pins the `schema` feature's forward to `shep-core/schema`: a dog reaches
// these two through the re-export above, so a missing forward costs it a
// second dependency it should never name. Workspace feature unification
// hides that everywhere except `cargo check -p shep-client`.
#[cfg(feature = "schema")]
const _: () = {
    const fn assert_json_schema<T: schemars::JsonSchema>() {}
    assert_json_schema::<shep_core::values::MemSize>();
    assert_json_schema::<shep_core::values::UpDuration>();
};

/// The wire protocol this client speaks, re-exported from
/// [`shep_core::protocol::PROTOCOL_VERSION`].
///
/// Reachable from this crate's own root because a dog depends on this
/// crate and nothing else, and `docs/dogs.md` asks every dog to print it.
/// A re-export rather than a copy: a second definition could disagree with
/// the value the handshake compares.
pub use shep_core::protocol::PROTOCOL_VERSION;

#[cfg(test)]
mod tests {
    /// Not an assertion, just a line of output where a wrong number would
    /// otherwise pass in silence.
    ///
    /// The four integration binaries require `test-support`. Cargo skips a
    /// target whose required features are off without a word. A bare
    /// `cargo test -p shep-client` then reports a fraction of this crate's
    /// tests as the whole. This case compiles only when the feature is off.
    #[cfg(not(feature = "test-support"))]
    #[test]
    fn heads_up_four_integration_binaries_need_test_support_and_are_not_running() {
        assert!(
            !cfg!(feature = "test-support"),
            "compiled only when the feature is off"
        );
    }
}