nautilus_network/socket/
mod.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Raw TCP clients with suffix framing, optional TLS, heartbeats, and automatic reconnection.
17//!
18//! # Architecture
19//!
20//! [`SocketClient`] uses a controller to own connection lifecycle. One reader task splits the byte
21//! stream into complete messages for [`TcpMessageHandler`], while one writer task serializes sends
22//! from concurrent callers. Optional heartbeat traffic passes through the same writer.
23//!
24//! # Framing and liveness
25//!
26//! [`SocketConfig::suffix`] frames both directions. The writer appends it to application and
27//! heartbeat messages, and the reader strips it before dispatch. An empty suffix is rejected. A
28//! partial frame that exceeds 10 MiB stops the reader and triggers reconnect. An optional idle
29//! timeout detects a connection that remains open without delivering bytes.
30//!
31//! # State reporting and explicit reconnect
32//!
33//! An optional [`crate::SocketStateSink`] publishes ordered `Connected` and `Disconnected`
34//! availability edges for initial connection, transport loss, and recovery. It omits retry attempts
35//! and deliberate shutdown. [`SocketReconnectHandle`] lets adapter tasks request transport
36//! replacement without owning the client and reports whether each request was accepted, already
37//! reconnecting, disconnecting, or closed.
38//!
39//! # Reconnection and replay
40//!
41//! Initial connection establishment retries failures with exponential backoff. When a connected
42//! transport fails, the controller reconnects with configurable backoff, jitter, timeout,
43//! and attempt limits. The writer buffers application messages in FIFO order. A
44//! [`SocketReconnectReplay`] can place protocol setup messages before that buffer on the replacement
45//! connection, and a post-reconnection callback runs after the writer, buffer, and reader are ready.
46//!
47//! # Transport policy
48//!
49//! Connections support plain TCP or `rustls`, enable `TCP_NODELAY`, and accept either a raw
50//! `host:port` address or a URL. A certificate directory can add trusted roots and supply a matching
51//! client certificate and key.
52
53pub mod client;
54pub mod config;
55pub mod types;
56
57pub use client::{SocketClient, SocketReconnectHandle, SocketReconnectReplay};
58pub use config::{SocketConfig, SocketHeartbeat};
59pub use types::{TcpMessageHandler, TcpReader, TcpWriter, WriterCommand};
nautilus_network/socket/mod.rs

nautilus_network/socket/
mod.rs
