sdre_stubborn_io/
lib.rs

1//! Contains the ingredients needed to create wrappers over tokio AsyncRead/AsyncWrite items
2//! to automatically reconnect upon failures. This is done so that a user can use them without worrying
3//! that their application logic will terminate simply due to an event like a temporary network failure.
4//!
5//! This crate will try to provide commonly used io items, for example, the [StubbornTcpStream](StubbornTcpStream).
6//! If you need to create your own, you simply need to implement the [UnderlyingIo](crate::tokio::UnderlyingIo) trait.
7//! Once implemented, you can construct it easily by creating a [StubbornIo](crate::tokio::StubbornIo) type as seen below.
8//!
9//! *This crate requires at least version 1.39 of the Rust compiler.*
10//!
11//! ### Motivations
12//! This crate was created because I was working on a service that needed to fetch data from a remote server
13//! via a tokio TcpConnection. It normally worked perfectly (as does all of my code ☺), but every time the
14//! remote server had a restart or turnaround, my application logic would stop working.
15//! **stubborn-io** was born because I did not want to complicate my service's logic with TcpStream
16//! reconnect and disconnect handling code. With stubborn-io, I can keep the service exactly the same,
17//! knowing that the StubbornTcpStream's sensible defaults will perform reconnects in a way to keep my service running.
18//! Once I realized that the implementation could apply to all IO items and not just TcpStream, I made it customizable as
19//! seen below.
20//!
21//! ## Example on how a Stubborn IO item might be created
22//! ```
23//! use std::io;
24//! use std::future::Future;
25//! use std::path::PathBuf;
26//! use std::pin::Pin;
27//! use sdre_stubborn_io::tokio::{StubbornIo, UnderlyingIo};
28//! use tokio::fs::File;
29//!
30//! struct MyFile(File); // Struct must implement AsyncRead + AsyncWrite
31//!
32//! impl UnderlyingIo<PathBuf> for MyFile {
33//!     // Establishes an io connection.
34//!     // Additionally, this will be used when reconnect tries are attempted.
35//!     fn establish(path: PathBuf) -> Pin<Box<dyn Future<Output = io::Result<Self>> + Send>> {
36//!         Box::pin(async move {
37//!             // In this case, we are trying to "connect" a file that
38//!             // should exist on the system
39//!             let tokio_file = File::open(path).await?;
40//!             Ok(MyFile(tokio_file))
41//!         })
42//!     }
43//! }
44//!
45//! # async fn test() -> io::Result<()> {
46//! // Because StubbornIo implements deref, you are able to invoke
47//! // the original methods on the File struct.
48//! type HomemadeStubbornFile = StubbornIo<MyFile, PathBuf>;
49//! let path = PathBuf::from("./foo/bar.txt");
50//!
51//! let stubborn_file = HomemadeStubbornFile::connect(path).await?;
52//! // ... application logic here!
53//!  # Ok(())
54//!  # }
55//! ```
56
57pub mod config;
58pub mod strategies;
59
60// in the future, there may be a mod for synchronous regular io too, which is why
61// tokio is specifically chosen to place the async stuff
62pub mod tokio;
63
64#[doc(inline)]
65pub use self::config::ReconnectOptions;
66#[doc(inline)]
67pub use self::tokio::StubbornTcpStream;
sdre_stubborn_io/lib.rs

sdre_stubborn_io/
lib.rs
