tidy module structure and docs

src/cli/args.rs

@@ -44,7 +44,7 @@ pub(crate) struct CliArgs {
 
     // CLIENT-ONLY OPTIONS =================================================================
     #[command(flatten)]
-    pub client: crate::client::args::ClientOptions,
+    pub client: crate::client::Options,
 
     // NETWORK OPTIONS =====================================================================
     #[command(flatten)]

src/cli/cli_main.rs

@@ -18,6 +18,8 @@ use tracing::error_span;
 /// Main CLI entrypoint
 ///
 /// Call this from `main`. It reads argv.
+/// # Exit status
+/// 0 indicates success; non-zero indicates failure.
 #[tokio::main(flavor = "current_thread")]
 #[allow(clippy::missing_panics_doc)]
 pub async fn cli() -> anyhow::Result<ExitCode> {

src/client/args.rs

@@ -1,4 +1,4 @@
-//! Parameters specific to qcp client-mode
+//! Options specific to qcp client-mode
 // (c) 2024 Ross Younger
 
 use clap::Parser;
@@ -7,10 +7,10 @@ use crate::{protocol::control::ConnectionType, util::PortRange};
 
 use super::job::FileSpec;
 
-/// Options for client mode
+/// Options specific to qcp client mode
 #[derive(Debug, Parser, Clone)]
 #[allow(clippy::struct_excessive_bools)]
-pub struct ClientOptions {
+pub struct Options {
     /// Quiet mode
     ///
     /// Switches off progress display and statistics; reports only errors
@@ -89,7 +89,7 @@ pub struct ClientOptions {
     pub destination: Option<FileSpec>,
 }
 
-impl ClientOptions {
+impl Options {
     pub(crate) fn address_family(&self) -> Option<ConnectionType> {
         if self.ipv4 {
             Some(ConnectionType::Ipv4)

src/client/control.rs

@@ -14,19 +14,18 @@ use tracing::{debug, trace, warn};
 use crate::{
     protocol::control::{ClientMessage, ClosedownReport, ConnectionType, ServerMessage, BANNER},
     transport::{BandwidthParams, QuicParams},
-    util::cert::Credentials,
+    util::Credentials,
 };
 
-use super::args::ClientOptions;
+use super::args::Options;
 
 /// Control channel abstraction
 #[derive(Debug)]
-#[allow(clippy::module_name_repetitions)]
-pub struct ControlChannel {
+pub struct Channel {
     process: tokio::process::Child,
 }
 
-impl ControlChannel {
+impl Channel {
     /// A reasonably controlled shutdown.
     /// (If you want to be rough, simply drop the `ControlChannel`.)
     pub async fn close(&mut self) -> Result<()> {
@@ -36,14 +35,14 @@ impl ControlChannel {
     }
 
     /// Opens the control channel, checks the banner, sends the Client Message, reads the Server Message.
-    pub(crate) async fn transact(
+    pub async fn transact(
         credentials: &Credentials,
         server_address: IpAddr,
         display: &MultiProgress,
-        client: &ClientOptions,
+        client: &Options,
         bandwidth: BandwidthParams,
         quic: QuicParams,
-    ) -> Result<(ControlChannel, ServerMessage)> {
+    ) -> Result<(Channel, ServerMessage)> {
         trace!("opening control channel");
         let mut new1 = Self::launch(display, client, bandwidth, quic)?;
         new1.wait_for_banner().await?;
@@ -79,7 +78,7 @@ impl ControlChannel {
     /// This is effectively a constructor. At present, it launches a subprocess.
     fn launch(
         display: &MultiProgress,
-        client: &ClientOptions,
+        client: &Options,
         bandwidth: BandwidthParams,
         quic: QuicParams,
     ) -> Result<Self> {
@@ -181,7 +180,8 @@ impl ControlChannel {
         Ok(())
     }
 
-    pub(crate) async fn read_closedown_report(&mut self) -> Result<ClosedownReport> {
+    /// Retrieves the closedown report
+    pub async fn read_closedown_report(&mut self) -> Result<ClosedownReport> {
         let pipe = self
             .process
             .stdout

src/client/job.rs

@@ -5,7 +5,7 @@ use std::str::FromStr;
 
 use crate::transport::ThroughputMode;
 
-use super::args::ClientOptions;
+use super::args::Options;
 
 /// A file source or destination specified by the user
 #[derive(Debug, Clone, Default)]
@@ -72,10 +72,10 @@ impl CopyJobSpec {
     }
 }
 
-impl TryFrom<&ClientOptions> for CopyJobSpec {
+impl TryFrom<&Options> for CopyJobSpec {
     type Error = anyhow::Error;
 
-    fn try_from(args: &ClientOptions) -> Result<Self, Self::Error> {
+    fn try_from(args: &Options) -> Result<Self, Self::Error> {
         let source = args
             .source
             .as_ref()

src/client/main_loop.rs

@@ -1,15 +1,14 @@
 // qcp client event loop
 // (c) 2024 Ross Younger
 
-use crate::client::control::ControlChannel;
+use crate::client::control::Channel;
 use crate::protocol::session::session_capnp::Status;
 use crate::protocol::session::{FileHeader, FileTrailer, Response};
 use crate::protocol::{RawStreamPair, StreamPair};
 use crate::transport::{BandwidthParams, QuicParams, ThroughputMode};
-use crate::util::cert::Credentials;
-use crate::util::time::Stopwatch;
-use crate::util::PortRange;
-use crate::util::{self, lookup_host_by_family, time::StopwatchChain};
+use crate::util::{
+    self, lookup_host_by_family, time::Stopwatch, time::StopwatchChain, Credentials, PortRange,
+};
 
 use anyhow::{Context, Result};
 use futures_util::TryFutureExt as _;
@@ -26,16 +25,16 @@ use tokio::time::Instant;
 use tokio::{self, io::AsyncReadExt, time::timeout, time::Duration};
 use tracing::{debug, error, info, span, trace, trace_span, warn, Instrument as _, Level};
 
-use super::args::ClientOptions;
+use super::args::Options;
 use super::job::CopyJobSpec;
 
 const SHOW_TIME: &str = "file transfer";
 
-/// Main CLI entrypoint
+/// Main client mode event loop
 // Caution: As we are using ProgressBar, anything to be printed to console should use progress.println() !
 #[allow(clippy::module_name_repetitions)]
 pub async fn client_main(
-    options: ClientOptions,
+    options: Options,
     bandwidth: BandwidthParams,
     quic: QuicParams,
     display: MultiProgress,
@@ -52,7 +51,7 @@ pub async fn client_main(
 
     // Control channel ---------------
     timers.next("control channel");
-    let (mut control, server_message) = ControlChannel::transact(
+    let (mut control, server_message) = Channel::transact(
         &credentials,
         server_address,
         &display,

src/client/mod.rs

@@ -1,8 +1,15 @@
 //! client-side (_initiator_) main loop and supporting structures
 
-pub mod args;
-pub mod control;
-pub mod job;
+mod args;
+pub use args::Options;
+
+mod control;
+pub use control::Channel;
+
+mod job;
+pub use job::CopyJobSpec;
+pub use job::FileSpec;
+
 mod main_loop;
 mod meter;
 mod progress;

src/lib.rs

@@ -59,9 +59,10 @@ pub mod util;
 
 pub mod doc;
 
-mod os;
+pub mod os;
 
 /// Build-time info (autogenerated by `built`)
-pub mod build_info {
+#[allow(unreachable_pub)]
+mod build_info {
     include!(concat!(env!("OUT_DIR"), "/built.rs"));
 }

src/os/mod.rs

@@ -1,10 +1,10 @@
-// OS abstraction layer for qcp
+//! OS abstraction layer
 // (c) 2024 Ross Younger
 
 use anyhow::Result;
 
 /// OS abstraction trait providing access to socket options
-pub(crate) trait SocketOptions {
+pub trait SocketOptions {
     /// Wrapper for getsockopt `SO_SNDBUF`.
     /// On Linux, this call halves the number returned from the kernel.
     /// This takes account of kernel behaviour: the internal buffer
@@ -28,10 +28,10 @@ pub(crate) trait SocketOptions {
     fn force_recvbuf(&mut self, size: usize) -> Result<()>;
 }
 
-#[cfg(unix)]
+#[cfg(any(unix, doc))]
 mod unix;
 
-#[cfg(unix)]
+#[cfg(any(unix, doc))]
 pub(crate) use unix::*;
 
 static_assertions::assert_cfg!(unix, "This OS is not yet supported");

src/server.rs

@@ -1,4 +1,4 @@
-//! qcp server event loop
+//! server-side _(remote)_ event loop
 // (c) 2024 Ross Younger
 
 use std::path::PathBuf;
@@ -8,8 +8,8 @@ use crate::protocol::control::{ClientMessage, ClosedownReport, ServerMessage};
 use crate::protocol::session::{session_capnp::Status, Command, FileHeader, FileTrailer, Response};
 use crate::protocol::{self, StreamPair};
 use crate::transport::BandwidthParams;
-use crate::util::cert::Credentials;
 use crate::util::socket::bind_range_for_family;
+use crate::util::Credentials;
 use crate::util::PortRange;
 use crate::{transport, util};
 
@@ -25,7 +25,7 @@ use tokio::task::JoinSet;
 use tokio::time::timeout;
 use tracing::{debug, error, info, trace, trace_span, warn, Instrument};
 
-/// Server main loop
+/// Server event loop
 #[allow(clippy::module_name_repetitions)]
 pub async fn server_main(
     bandwidth: crate::transport::BandwidthParams,

src/util/cert.rs

@@ -4,7 +4,7 @@
 use anyhow::Result;
 use rustls_pki_types::{CertificateDer, PrivateKeyDer};
 
-/// In-memory represenatation of X509 credentials (for TLS)
+/// In-memory representation of X509 credentials (for TLS)
 #[derive(Debug)]
 pub struct Credentials {
     /// X509 certificate

src/util/dns.rs

@@ -7,6 +7,7 @@ use crate::protocol::control::ConnectionType;
 use anyhow::Context as _;
 
 /// DNS lookup helper
+///
 /// Results can be restricted to a given address family.
 /// Only the first matching result is returned.
 /// If there are no matching records of the required type, returns an error.

src/util/mod.rs

@@ -4,7 +4,9 @@
 mod dns;
 pub use dns::lookup_host_by_family;
 
-pub mod cert;
+mod cert;
+pub use cert::Credentials;
+
 pub mod io;
 pub mod socket;
 pub mod stats;

src/util/stats.rs

@@ -51,7 +51,7 @@ impl Display for DataRate {
 }
 
 /// Output the end-of-game statistics
-pub(crate) fn process_statistics(
+pub fn process_statistics(
     stats: &ConnectionStats,
     payload_bytes: u64,
     transport_time: Option<Duration>,

src/util/tracing.rs

@@ -42,10 +42,13 @@ fn filter_for(trace_level: &str, key: &str) -> anyhow::Result<FilterResult> {
 }
 
 /// Set up rust tracing, to console (via an optional `MultiProgress`) and optionally to file.
+///
 /// By default we log only our events (qcp), at a given trace level.
 /// This can be overridden by setting `RUST_LOG`.
+///
 /// For examples, see <https://docs.rs/tracing-subscriber/0.3.18/tracing_subscriber/fmt/index.html#filtering-events-with-environment-variables>
-/// CAUTION: If this function fails, tracing won't be set up; callers must take extra care to report the error.
+///
+/// **CAUTION:** If this function fails, tracing won't be set up; callers must take extra care to report the error.
 pub fn setup(
     trace_level: &str,
     display: Option<&MultiProgress>,