pueue_lib/network_blocking/
mod.rs

1//! This module contains everything that's necessary to communicate with the pueue daemon or one of
2//! its clients.
3//!
4//! ## Sockets
5//!
6//! Pueue's communication can happen either via TLS encrypted TCP sockets or via UNIX sockets.
7//! The mode of communication is usually specified via the configuration file and the daemon only
8//! listens on a single type of socket.
9//!
10//! - Unix sockets are unencrypted
11//! - TCP sockets are encrypted via TLS
12//!
13//! ## Communication
14//!
15//! Sending and receiving raw bytes is handled via the
16//! [send_bytes](crate::network::protocol::send_bytes)
17//! and [receive_bytes](crate::network::protocol::receive_bytes) functions.
18//! Details on how they work can be found on the respective function docs.
19//!
20//! Payloads are defined via the [`Request`](crate::Request) and [`Response`](crate::Response) enums
21//! that can be found in the [`super::message`] module.
22//!
23//! There're also the convenience functions [send_message] and [receive_message], which
24//! automatically handle serialization and deserialization for you.
25//! These have additional wrappers for [`Request`](crate::Request) and
26//! [`Response`](crate::Response) with [`send_request`] and [`receive_response`].
27//!
28//! The serialization/deserialization format that's used by `pueue_lib` is [`cbor`](::ciborium).
29//!
30//! ## Protocol
31//!
32//! Before the real data exchange starts, a simple handshake + authorization is done
33//! by the client and daemon.
34//! An example on how to do this can be found in the Pueue's `Client::new()` function.
35//!
36//! The following steps are written from the client's perspective:
37//!
38//! - Connect to socket.
39//! - Send the secret's bytes.
40//! - Receive the daemon's version (utf-8 encoded), which is sent if the secret was correct.
41//! - Send the actual message.
42//! - Receive the daemon's response.
43//!
44//! In the case of most messages, the daemon is ready to receive the next the message from
45//! the client, once it has send its response.
46//!
47//! However, some message types are special. The log `follow`, for instance, basically
48//! work like a stream.
49//! I.e. the daemon continuously sends new messages with the new log output until
50//! the socket is closed by the client.
51
52#[cfg(feature = "client")]
53pub mod client;
54/// This is probably the most interesting part for you.
55pub mod protocol;
56/// Low-level socket handling code.
57pub mod socket;
58
59#[cfg(feature = "client")]
60pub use client::BlockingClient;
61pub use protocol::{
62    receive_message, receive_request, receive_response, send_message, send_request, send_response,
63};
64pub use socket::get_client_stream;
pueue_lib/network_blocking/mod.rs

pueue_lib/network_blocking/
mod.rs
