code: Add docs and deprecation notices

Cargo.toml

@@ -32,6 +32,9 @@ license.workspace = true
 rust-version.workspace = true
 edition.workspace = true
 
+[package.metadata.docs.rs]
+features = ["all"]
+
 [dependencies]
 serde = { version = "1.0.120", features = ["rc"] }
 serde_json = "1.0.61"
@@ -89,9 +92,6 @@ if-addrs = { version = "0.13", optional = true }
 
 # Transfer
 
-async-tar = { version = "0.4", optional = true }
-zstd = { version = "0.13", optional = true }
-
 [target.'cfg(target_family = "wasm")'.dependencies]
 wasm-timer = "0.2.5"
 ws_stream_wasm = "0.7.3"
@@ -104,16 +104,16 @@ eyre = "0.6.5"
 
 [features]
 transit = [
-    "socket2",
-    "stun_codec",
-    "if-addrs",
-    "bytecodec",
-    "async-trait",
-    "noise-protocol",
-    "noise-rust-crypto",
+    "dep:noise-rust-crypto",
+    "dep:noise-protocol",
+    "dep:socket2",
+    "dep:stun_codec",
+    "dep:if-addrs",
+    "dep:bytecodec",
+    "dep:async-trait",
 ]
-transfer = ["transit", "tar", "async-tar", "rmp-serde", "zstd"]
-forwarding = ["transit", "rmp-serde"]
+transfer = ["transit", "dep:tar", "dep:rmp-serde"]
+forwarding = ["transit", "dep:rmp-serde"]
 default = ["transit", "transfer"]
 all = ["default", "forwarding"]
 
@@ -122,6 +122,7 @@ all = ["default", "forwarding"]
 tls = ["async-tungstenite/async-tls"]
 native-tls = ["async-tungstenite/async-native-tls"]
 # Enable experimental transfer-v2 support. The protocol is not yet finalized and is subject to change.
+# By enabling this option you are opting out of semver stability.
 experimental-transfer-v2 = []
 experimental = ["experimental-transfer-v2"]
 

changelog.md

@@ -2,16 +2,24 @@
 
 ## Unreleased
 
+- \[lib\]\[deprecated\] `magic_wormhole::transfer::send_*` and `request_file` methods to take an `OfferSend` and `OfferReceive` instead of using separate methods for files and folders. Use `transfer::send()` and `transfer::receive()` for the new methods.
+- \[lib\]\[breaking\] struct `transfer::ReceiveRequest` became an enum to prepare for transfer v2
+
+## Version 0.7.0
+
 - \[all\]\[breaking\] By default websocket TLS support is now disabled in the library crate. TLS is required for secure websocket connections to the mailbox server (`wss://`). As the handshake protocol itself is encrypted, this extra layer of encryption is superfluous. Most WASM targets however refuse to connect to non-TLS websockets. For maximum compatibility with all mailbox servers, or for web browser support, select a TLS implementation by specifying the feature flag `tls` for a statically linked implementation via the `ring` crate, or `native-tls` for dynamically linking with the system-native TLS implementation.
-- \[all\] For experimental (unstable) `transfer-v2` protocol support, enable feature flag `experimental-transfer-v2`. The protocol is not yet finalized. 
+- \[all\] For experimental (unstable) `transfer-v2` protocol support, enable feature flag `experimental-transfer-v2`. The protocol is not yet finalized.
 - \[all\] Added compilation support for WASM targets.
 - \[lib\]\[breaking\] replaced `transit::TransitInfo` with a struct containing the address and a `conn_type` field which contains the old enum as `transit::ConnectionType`
+- \[lib\]\[breaking\] changed the signature of the `transit_handler` function to take just the newly combined `transit::TransitInfo`
+- \[lib\]\[breaking\] changed the signature of the `file_name` argument to `transfer::send_*` to take `Into<String>` instead of `Into<PathBuf>`
 - \[lib\]\[breaking\] replaced `transfer::AppVersion` with a struct with private fields that implements `std::default::Default`
-- \[lib\]\[breaking\] split `Wormhole` in `MailboxConnection` and `Wormhole`. `Wormhole` now uses accessor methods for the previously exposed fields.
-- \[lib\]\[breaking\] `WormholeWelcome` now uses accessor methods for the previously exposed fields.
-- \[lib\]\[breaking\] refactor `magic_wormhole::transfer::` methods to take an `OfferSend` and `OfferReceive` instead of using separate methods for files and folders. Use `transfer::send()` and `transfer::receive()`.
-- \[lib\]\[breaking\] struct `transfer::ReceiveRequest` became an enum to prepare for transfer v2
-- \[lib\]\[breaking\] removed `transit::log_transit_connection` and implemented `Display` on `TransitInfo` instead.
+- \[lib\]\[breaking\] split `Wormhole` in `MailboxConnection` and `Wormhole`
+- \[lib\]\[deprecated\] `ReceiveRequest.filename` is deprecated and replaced by `ReceiveRequest.file_name(..)`
+- \[lib\]\[deprecated\] `ReceiveRequest.filesize` is deprecated and replaced by `ReceiveRequest.file_size(..)`
+- \[lib\]\[deprecated\] `Wormhole` public struct fields. Use the provided accessor methods instead.
+- \[lib\]\[deprecated\] `transit::log_transit_connection` and implemented `Display` on `TransitInfo` instead.
+- \[lib\]\[deprecated\] `transfer::PeerMessage` will be removed in the future with no planned public replacement.
 
 ## Version 0.6.1
 

cli/src/main.rs

@@ -553,7 +553,7 @@ async fn main() -> eyre::Result<()> {
 
 fn parse_transit_args(args: &CommonArgs) -> transit::Abilities {
     match (args.force_direct, args.force_relay) {
-        (false, false) => transit::Abilities::ALL_ABILITIES,
+        (false, false) => transit::Abilities::ALL,
         (true, false) => transit::Abilities::FORCE_DIRECT,
         (false, true) => transit::Abilities::FORCE_RELAY,
         (true, true) => unreachable!("These flags are mutually exclusive"),
@@ -648,7 +648,7 @@ async fn parse_and_connect(
 async fn make_send_offer(
     mut files: Vec<PathBuf>,
     file_name: Option<String>,
-) -> eyre::Result<transfer::OfferSend> {
+) -> eyre::Result<transfer::offer::OfferSend> {
     for file in &files {
         eyre::ensure!(
             async_std::path::Path::new(&file).exists().await,
@@ -662,7 +662,7 @@ async fn make_send_offer(
         (0, _) => unreachable!("Already checked by CLI parser"),
         (1, Some(file_name)) => {
             let file = files.remove(0);
-            Ok(transfer::OfferSend::new_file_or_folder(file_name, file).await?)
+            Ok(transfer::offer::OfferSend::new_file_or_folder(file_name, file).await?)
         },
         (1, None) => {
             let file = files.remove(0);
@@ -674,7 +674,7 @@ async fn make_send_offer(
                 .to_str()
                 .ok_or_else(|| eyre::format_err!("File path must be a valid UTF-8 string"))?
                 .to_owned();
-            Ok(transfer::OfferSend::new_file_or_folder(file_name, file).await?)
+            Ok(transfer::offer::OfferSend::new_file_or_folder(file_name, file).await?)
         },
         (_, Some(_)) => Err(eyre::format_err!(
             "Can't customize file name when sending multiple files"
@@ -689,7 +689,7 @@ async fn make_send_offer(
                     );
                 }
             }
-            Ok(transfer::OfferSend::new_paths(files).await?)
+            Ok(transfer::offer::OfferSend::new_paths(files).await?)
         },
     }
 }
@@ -793,7 +793,7 @@ fn server_print_code(
 async fn send(
     wormhole: Wormhole,
     relay_hints: Vec<transit::RelayHint>,
-    offer: transfer::OfferSend,
+    offer: transfer::offer::OfferSend,
     transit_abilities: transit::Abilities,
     ctrl_c: impl Fn() -> futures::future::BoxFuture<'static, ()>,
 ) -> eyre::Result<()> {
@@ -879,7 +879,7 @@ async fn send_many(
 
     async fn send_in_background(
         relay_hints: Vec<transit::RelayHint>,
-        offer: transfer::OfferSend,
+        offer: transfer::offer::OfferSend,
         wormhole: Wormhole,
         mut term: Term,
         mp: &MultiProgress,
@@ -929,19 +929,34 @@ async fn receive(
     transit_abilities: transit::Abilities,
     ctrl_c: impl Fn() -> futures::future::BoxFuture<'static, ()>,
 ) -> eyre::Result<()> {
-    let req = transfer::request(wormhole, relay_hints, transit_abilities, ctrl_c())
-        .await
-        .context("Could not get an offer")?;
-    /* If None, the task got cancelled */
-    match req {
-        Some(transfer::ReceiveRequest::V1(req)) => {
+    #[cfg(not(feature = "experimental-transfer-v2"))]
+    {
+        let req = transfer::request_file(wormhole, relay_hints, transit_abilities, ctrl_c())
+            .await
+            .context("Could not get an offer")?;
+        /* If None, the task got cancelled */
+        if let Some(req) = req {
             receive_inner_v1(req, target_dir, noconfirm, ctrl_c).await
-        },
-        #[cfg(feature = "experimental-transfer-v2")]
-        Some(transfer::ReceiveRequest::V2(req)) => {
-            receive_inner_v2(req, target_dir, noconfirm, ctrl_c).await
-        },
-        None => Ok(()),
+        } else {
+            Ok(())
+        }
+    }
+    #[cfg(feature = "experimental-transfer-v2")]
+    {
+        let req = transfer::request(wormhole, relay_hints, transit_abilities, ctrl_c())
+            .await
+            .context("Could not get an offer")?;
+
+        match req {
+            Some(transfer::ReceiveRequest::V1(req)) => {
+                receive_inner_v1(req, target_dir, noconfirm, ctrl_c).await
+            },
+            #[cfg(feature = "experimental-transfer-v2")]
+            Some(transfer::ReceiveRequest::V2(req)) => {
+                receive_inner_v2(req, target_dir, noconfirm, ctrl_c).await
+            },
+            None => Ok(()),
+        }
     }
 }
 
@@ -966,8 +981,8 @@ async fn receive_inner_v1(
         || util::ask_user(
             format!(
                 "Receive file '{}' ({})?",
-                req.filename,
-                match NumberPrefix::binary(req.filesize as f64) {
+                req.file_name(),
+                match NumberPrefix::binary(req.file_size() as f64) {
                     NumberPrefix::Standalone(bytes) => format!("{} bytes", bytes),
                     NumberPrefix::Prefixed(prefix, n) =>
                         format!("{:.1} {}B in size", n, prefix.symbol()),
@@ -981,9 +996,9 @@ async fn receive_inner_v1(
     }
 
     // TODO validate untrusted input here
-    let file_path = std::path::Path::new(target_dir).join(&req.filename);
+    let file_path = std::path::Path::new(target_dir).join(req.file_name());
 
-    let pb = create_progress_bar(req.filesize);
+    let pb = create_progress_bar(req.file_size());
 
     /* Then, accept if the file exists */
     if !file_path.exists() || noconfirm {
@@ -996,8 +1011,8 @@ async fn receive_inner_v1(
         return req
             .accept(
                 &transit_handler,
-                &mut file,
                 create_progress_handler(pb),
+                &mut file,
                 ctrl_c(),
             )
             .await
@@ -1022,8 +1037,8 @@ async fn receive_inner_v1(
         .await?;
     req.accept(
         &transit_handler,
-        &mut file,
         create_progress_handler(pb),
+        &mut file,
         ctrl_c(),
     )
     .await

cli/src/util.rs

@@ -52,7 +52,7 @@ pub async fn cancellable<T>(
     }
 }
 
-/// Indicator that the [`Cancellable`] task was cancelled.
+/// Indicator that the cancellable task was cancelled.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct Cancelled;