code: Deprecate unusable methods and protocol intrinsics

cli/src/main.rs

@@ -996,7 +996,7 @@ async fn receive_inner_v1(
     }
 
     // TODO validate untrusted input here
-    let file_path = std::path::Path::new(target_dir).join(&req.file_name());
+    let file_path = std::path::Path::new(target_dir).join(req.file_name());
 
     let pb = create_progress_bar(req.file_size());
 

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;
 

src/core.rs

@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 pub(super) mod key;
 pub mod rendezvous;
 mod server_messages;
@@ -252,6 +254,7 @@ impl<V: serde::Serialize + Send + Sync + 'static> MailboxConnection<V> {
 
 #[derive(Debug)]
 pub struct Wormhole {
+    #[allow(deprecated)]
     server: RendezvousServer,
     phase: u64,
     key: key::Key<key::WormholeKey>,
@@ -336,7 +339,7 @@ impl Wormhole {
         } = mailbox_connection;
 
         /* Send PAKE */
-        let (pake_state, pake_msg_ser) = key::make_pake(&code.0, &config.id);
+        let (pake_state, pake_msg_ser) = key::make_pake(code.as_ref(), &config.id);
         server.send_peer_message(Phase::PAKE, pake_msg_ser).await?;
 
         /* Receive PAKE */
@@ -382,11 +385,6 @@ impl Wormhole {
         })
     }
 
-    /** TODO */
-    pub async fn connect_with_seed() {
-        todo!()
-    }
-
     /** Send an encrypted message to peer */
     pub async fn send(&mut self, plaintext: Vec<u8>) -> Result<(), WormholeError> {
         let phase_string = Phase::numeric(self.phase);
@@ -499,7 +497,7 @@ impl Wormhole {
     }
 
     /**
-     * Our "app version" information that we sent. See the [`peer_version`] for more information.
+     * Our "app version" information that we sent. See the [`peer_version`](Self::peer_version()) for more information.
      */
     pub fn our_version(&self) -> &(dyn std::any::Any + Send + Sync) {
         #[allow(deprecated)]
@@ -579,7 +577,11 @@ impl<V: serde::Serialize> AppConfig<V> {
     PartialEq, Eq, Clone, Debug, Deserialize, Serialize, derive_more::Display, derive_more::Deref,
 )]
 #[deref(forward)]
-pub struct AppID(#[deref] pub Cow<'static, str>);
+pub struct AppID(
+    #[deref]
+    #[deprecated(since = "0.7.0", note = "use the AsRef<str> implementation")]
+    pub Cow<'static, str>,
+);
 
 impl AppID {
     pub fn new(id: impl Into<Cow<'static, str>>) -> Self {
@@ -593,12 +595,22 @@ impl From<String> for AppID {
     }
 }
 
+impl AsRef<str> for AppID {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
 // MySide is used for the String that we send in all our outbound messages
 #[derive(
     PartialEq, Eq, Clone, Debug, Deserialize, Serialize, derive_more::Display, derive_more::Deref,
 )]
 #[serde(transparent)]
 #[display(fmt = "MySide({})", "&*_0")]
+#[deprecated(
+    since = "0.7.0",
+    note = "This will be a private type in the future. Open an issue if you require access to protocol intrinsics in the future"
+)]
 pub struct MySide(EitherSide);
 
 impl MySide {
@@ -625,6 +637,10 @@ impl MySide {
 )]
 #[serde(transparent)]
 #[display(fmt = "TheirSide({})", "&*_0")]
+#[deprecated(
+    since = "0.7.0",
+    note = "This will be a private type in the future. Open an issue if you require access to protocol intrinsics in the future"
+)]
 pub struct TheirSide(EitherSide);
 
 impl<S: Into<String>> From<S> for TheirSide {
@@ -639,6 +655,10 @@ impl<S: Into<String>> From<S> for TheirSide {
 #[serde(transparent)]
 #[deref(forward)]
 #[display(fmt = "{}", "&*_0")]
+#[deprecated(
+    since = "0.7.0",
+    note = "This will be a private type in the future. Open an issue if you require access to protocol intrinsics in the future"
+)]
 pub struct EitherSide(pub String);
 
 impl<S: Into<String>> From<S> for EitherSide {
@@ -649,7 +669,11 @@ impl<S: Into<String>> From<S> for EitherSide {
 
 #[derive(PartialEq, Eq, Clone, Debug, Hash, Deserialize, Serialize, derive_more::Display)]
 #[serde(transparent)]
-pub struct Phase(pub Cow<'static, str>);
+#[deprecated(
+    since = "0.7.0",
+    note = "This will be a private type in the future. Open an issue if you require access to protocol intrinsics in the future"
+)]
+pub struct Phase(Cow<'static, str>);
 
 impl Phase {
     pub const VERSION: Self = Phase(Cow::Borrowed("version"));
@@ -659,19 +683,33 @@ impl Phase {
         Phase(phase.to_string().into())
     }
 
+    #[allow(dead_code)]
     pub fn is_version(&self) -> bool {
         self == &Self::VERSION
     }
+
+    #[allow(dead_code)]
     pub fn is_pake(&self) -> bool {
         self == &Self::PAKE
     }
+
     pub fn to_num(&self) -> Option<u64> {
         self.0.parse().ok()
     }
 }
 
+impl AsRef<str> for Phase {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
 #[derive(PartialEq, Eq, Clone, Debug, Deserialize, Serialize, derive_more::Display)]
 #[serde(transparent)]
+#[deprecated(
+    since = "0.7.0",
+    note = "This will be a private type in the future. Open an issue if you require access to protocol intrinsics in the future"
+)]
 pub struct Mailbox(pub String);
 
 #[derive(
@@ -680,20 +718,38 @@ pub struct Mailbox(pub String);
 #[serde(transparent)]
 #[deref(forward)]
 #[display(fmt = "{}", _0)]
-pub struct Nameplate(pub String);
+pub struct Nameplate(
+    #[deprecated(since = "0.7.0", note = "use the AsRef<str> implementation")] pub String,
+);
 
+#[allow(deprecated)]
 impl Nameplate {
     pub fn new(n: &str) -> Self {
         Nameplate(String::from(n))
     }
 }
 
+#[allow(deprecated)]
 impl From<Nameplate> for String {
     fn from(value: Nameplate) -> Self {
         value.0
     }
 }
 
+#[allow(deprecated)]
+impl From<String> for Nameplate {
+    fn from(value: String) -> Self {
+        Self(value)
+    }
+}
+
+#[allow(deprecated)]
+impl AsRef<str> for Nameplate {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
 /** A wormhole code à la 15-foo-bar
  *
  * The part until the first dash is called the "nameplate" and is purely numeric.
@@ -702,8 +758,11 @@ impl From<Nameplate> for String {
  */
 #[derive(PartialEq, Eq, Clone, Debug, derive_more::Display, derive_more::Deref)]
 #[display(fmt = "{}", _0)]
-pub struct Code(pub String);
+pub struct Code(
+    #[deprecated(since = "0.7.0", note = "use the AsRef<str> implementation")] pub String,
+);
 
+#[allow(deprecated)]
 impl Code {
     pub fn new(nameplate: &Nameplate, password: &str) -> Self {
         Code(format!("{}-{}", nameplate, password))
@@ -720,3 +779,23 @@ impl Code {
         Nameplate::new(self.0.split('-').next().unwrap())
     }
 }
+
+#[allow(deprecated)]
+impl From<Code> for String {
+    fn from(value: Code) -> Self {
+        value.0
+    }
+}
+
+impl From<String> for Code {
+    fn from(value: String) -> Self {
+        Self(value)
+    }
+}
+
+#[allow(deprecated)]
+impl AsRef<str> for Code {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}

src/core/key.rs

@@ -13,15 +13,27 @@ use spake2::{Ed25519Group, Identity, Password, Spake2};
 ///
 /// See [`Key`].
 // TODO Once const generics are stabilized, try out if a const string generic may replace this.
+#[deprecated(
+    since = "0.7.0",
+    note = "This will be a private type in the future. Open an issue if you require access to protocol intrinsics in the future"
+)]
 pub trait KeyPurpose: std::fmt::Debug {}
 
 /// The type of main key of the Wormhole
 #[derive(Debug)]
+#[deprecated(
+    since = "0.7.0",
+    note = "This will be a private type in the future. Open an issue if you require access to protocol intrinsics in the future"
+)]
 pub struct WormholeKey;
 impl KeyPurpose for WormholeKey {}
 
 /// A generic key purpose for ad-hoc subkeys or if you don't care.
 #[derive(Debug)]
+#[deprecated(
+    since = "0.7.0",
+    note = "This will be a private type in the future. Open an issue if you require access to protocol intrinsics in the future"
+)]
 pub struct GenericKey;
 impl KeyPurpose for GenericKey {}
 
@@ -33,6 +45,10 @@ impl KeyPurpose for GenericKey {}
 #[derive(Debug, Clone, derive_more::Display, derive_more::Deref)]
 #[display(fmt = "{:?}", _0)]
 #[deref(forward)]
+#[deprecated(
+    since = "0.7.0",
+    note = "This will be a private type in the future. Open an issue if you require access to protocol intrinsics in the future"
+)]
 pub struct Key<P: KeyPurpose>(
     #[deref] pub Box<secretbox::Key>,
     #[deref(ignore)] std::marker::PhantomData<P>,

src/core/rendezvous.rs

@@ -313,12 +313,17 @@ impl MailboxMachine {
     }
 }
 
+#[deprecated(
+    since = "0.7.0",
+    note = "This will be a private type in the future. Open an issue if you require access to protocol intrinsics in the future"
+)]
 pub struct RendezvousServer {
     connection: WsConnection,
     state: Option<MailboxMachine>,
     side: MySide,
 }
 
+#[allow(deprecated)]
 impl std::fmt::Debug for RendezvousServer {
     fn fmt(&self, fmt: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         fmt.debug_struct("RendezvousServer")
@@ -328,6 +333,7 @@ impl std::fmt::Debug for RendezvousServer {
     }
 }
 
+#[allow(deprecated)]
 impl RendezvousServer {
     /**
      * Connect to the rendezvous server
@@ -410,7 +416,7 @@ impl RendezvousServer {
     }
 
     /** A random unique string for this session */
-    pub fn side(&self) -> &MySide {
+    pub(crate) fn side(&self) -> &MySide {
         &self.side
     }
 
@@ -426,7 +432,7 @@ impl RendezvousServer {
             .await
     }
 
-    pub async fn send_peer_message(
+    pub(crate) async fn send_peer_message(
         &mut self,
         phase: Phase,
         body: Vec<u8>,
@@ -435,15 +441,19 @@ impl RendezvousServer {
             .await
     }
 
-    pub async fn next_peer_message_some(&mut self) -> Result<EncryptedMessage, RendezvousError> {
+    pub(crate) async fn next_peer_message_some(
+        &mut self,
+    ) -> Result<EncryptedMessage, RendezvousError> {
         loop {
             if let Some(message) = self.next_peer_message().await? {
                 return Ok(message);
             }
         }
     }
 
-    pub async fn next_peer_message(&mut self) -> Result<Option<EncryptedMessage>, RendezvousError> {
+    pub(crate) async fn next_peer_message(
+        &mut self,
+    ) -> Result<Option<EncryptedMessage>, RendezvousError> {
         let machine = &mut self
             .state
             .as_mut()

src/core/server_messages.rs

@@ -113,7 +113,7 @@ pub struct HashcashPermission {
     phase,
     "crate::util::DisplayBytes(body)"
 )]
-pub struct EncryptedMessage {
+pub(crate) struct EncryptedMessage {
     pub side: TheirSide,
     pub phase: Phase,
     #[serde(deserialize_with = "hex::serde::deserialize")]

src/forwarding.rs

@@ -3,7 +3,7 @@
 //! This is a new (and still slightly experimental feature) that allows you to forward TCP connections over a wormhole
 //! `transit` connection.
 //!
-//! It is bound to an [`APPID`](APPID), which is distinct to the one used for file transfer. Therefore, the codes used
+//! It is bound to an [`APPID`], which is distinct to the one used for file transfer. Therefore, the codes used
 //! for port forwarding are in an independent namespace than those for sending files.
 //!
 //! At its core, "peer messages" are exchanged over an established wormhole connection with the other side.
@@ -13,6 +13,8 @@
 //! and received as they come in, no additional buffering is applied. (Under the assumption that those applications
 //! that need buffering already do it on their side, and those who don't, don't.)
 
+#![allow(deprecated)]
+
 use super::*;
 use async_std::net::{TcpListener, TcpStream};
 use futures::{AsyncReadExt, AsyncWriteExt, Future, SinkExt, StreamExt, TryStreamExt};

src/lib.rs

@@ -36,8 +36,9 @@ pub mod transit;
 #[cfg(feature = "transfer")]
 pub mod uri;
 
+#[allow(deprecated)]
 pub use crate::core::{
     key::{GenericKey, Key, KeyPurpose, WormholeKey},
     rendezvous, AppConfig, AppID, Code, MailboxConnection, Mood, Nameplate, Wormhole,
-    WormholeError,
+    WormholeError, WormholeWelcome,
 };