Documented swimos_remote crate.

Author: horned-sphere

client/fixture/src/lib.rs

@@ -21,7 +21,7 @@ use swimos_recon::print_recon;
 use swimos_remote::dns::{BoxDnsResolver, DnsResolver};
 use swimos_remote::websocket::{RatchetError, WebsocketClient, WebsocketServer, WsOpenFuture};
 use swimos_remote::{
-    ClientConnections, ConnResult, ConnectionError, Listener, ListenerError, Scheme,
+    ClientConnections, ConnectionError, ConnectionResult, Listener, ListenerError, Scheme,
 };
 use tokio::io::{AsyncRead, AsyncWrite, DuplexStream};
 use tokio::sync::mpsc;
@@ -71,7 +71,7 @@ impl ClientConnections for MockClientConnections {
         _scheme: Scheme,
         _host: Option<&str>,
         addr: SocketAddr,
-    ) -> BoxFuture<'_, ConnResult<Self::ClientSocket>> {
+    ) -> BoxFuture<'_, ConnectionResult<Self::ClientSocket>> {
         async move {
             self.inner
                 .lock()

client/runtime/src/commander/mod.rs

@@ -22,7 +22,7 @@ use ratchet::{
 };
 use swimos_form::write::StructuralWritable;
 use swimos_recon::print_recon_compact;
-use swimos_remote::{BadUrl, SchemeHostPort};
+use swimos_remote::{BadWarpUrl, SchemeHostPort};
 use thiserror::Error;
 use tokio::net::TcpStream;
 
@@ -31,7 +31,7 @@ pub enum CommandError {
     #[error("Failed to send command: {0}")]
     Ratchet(#[from] ratchet::Error),
     #[error("Invalid URL: {0}")]
-    Url(#[from] BadUrl),
+    Url(#[from] BadWarpUrl),
 }
 
 impl From<std::io::Error> for CommandError {

runtime/swimos_remote/src/dns.rs

@@ -31,7 +31,10 @@ pub trait DnsResolver {
     fn resolve(&self, host: String, port: u16) -> Self::ResolveFuture;
 }
 
+#[doc(hidden)]
 pub type DnsFut = BoxFuture<'static, io::Result<Vec<SocketAddr>>>;
+
+#[doc(hidden)]
 pub type BoxDnsResolver = Box<dyn DnsResolver<ResolveFuture = DnsFut> + Send + 'static>;
 
 impl<R> DnsResolver for Box<R>
@@ -72,6 +75,8 @@ impl DnsResolver for GetAddressInfoResolver {
     }
 }
 
+/// The default DNS resolver. If the `trust-dns` feature flag is enabled, this will use the `trust_dns`
+/// implementation, otherwise it will use the operating system's built-in DNS support.
 #[derive(Debug, Clone)]
 pub struct Resolver {
     #[cfg(not(feature = "trust-dns"))]

runtime/swimos_remote/src/lib.rs

@@ -38,9 +38,11 @@ mod ws;
 pub use task::RemoteTask;
 
 pub use net::{
-    BadUrl, ClientConnections, ConnResult, ConnectionError, ExternalConnections, Listener,
-    ListenerError, ListenerResult, Scheme, SchemeHostPort, ServerConnections,
+    BadWarpUrl, ClientConnections, ConnectionError, ExternalConnections, Listener, ListenerError,
+    Scheme, SchemeHostPort, ServerConnections,
 };
+#[doc(hidden)]
+pub use net::{ConnectionResult, ListenerResult};
 
 /// Bindings to use the [`ratchet`] web-sockets crate with the networking abstraction in this crate.
 pub mod websocket {

runtime/swimos_remote/src/net/mod.rs

@@ -32,7 +32,8 @@ use crate::dns::BoxDnsResolver;
 #[cfg(test)]
 mod tests;
 
-pub type ConnResult<T> = Result<T, ConnectionError>;
+#[doc(hidden)]
+pub type ConnectionResult<T> = Result<T, ConnectionError>;
 
 /// Error to indicate why attempting to open a new connection failed.
 #[derive(Debug, Error)]
@@ -85,6 +86,7 @@ impl From<std::io::Error> for ListenerError {
     }
 }
 
+#[doc(hidden)]
 pub type ListenerResult<T> = Result<T, ListenerError>;
 
 /// Trait for servers that listen for incoming remote connections. This is primarily used to
@@ -106,7 +108,7 @@ pub trait ClientConnections: Clone + Send + Sync + 'static {
         scheme: Scheme,
         host: Option<&str>,
         addr: SocketAddr,
-    ) -> BoxFuture<'_, ConnResult<Self::ClientSocket>>;
+    ) -> BoxFuture<'_, ConnectionResult<Self::ClientSocket>>;
 
     fn dns_resolver(&self) -> BoxDnsResolver;
     fn lookup(
@@ -127,7 +129,7 @@ where
         scheme: Scheme,
         host: Option<&str>,
         addr: SocketAddr,
-    ) -> BoxFuture<'_, ConnResult<Self::ClientSocket>> {
+    ) -> BoxFuture<'_, ConnectionResult<Self::ClientSocket>> {
         (**self).try_open(scheme, host, addr)
     }
 
@@ -152,7 +154,7 @@ pub trait ServerConnections: Clone + Send + Sync + 'static {
     fn bind(
         &self,
         addr: SocketAddr,
-    ) -> BoxFuture<'static, ConnResult<(SocketAddr, Self::ListenerType)>>;
+    ) -> BoxFuture<'static, ConnectionResult<(SocketAddr, Self::ListenerType)>>;
 }
 
 impl<C> ServerConnections for Arc<C>
@@ -166,7 +168,7 @@ where
     fn bind(
         &self,
         addr: SocketAddr,
-    ) -> BoxFuture<'static, ConnResult<(SocketAddr, Self::ListenerType)>> {
+    ) -> BoxFuture<'static, ConnectionResult<(SocketAddr, Self::ListenerType)>> {
         (**self).bind(addr)
     }
 }
@@ -180,13 +182,13 @@ pub trait ExternalConnections: Clone + Send + Sync + 'static {
     fn bind(
         &self,
         addr: SocketAddr,
-    ) -> BoxFuture<'static, ConnResult<(SocketAddr, Self::ListenerType)>>;
+    ) -> BoxFuture<'static, ConnectionResult<(SocketAddr, Self::ListenerType)>>;
     fn try_open(
         &self,
         scheme: Scheme,
         host: Option<&str>,
         addr: SocketAddr,
-    ) -> BoxFuture<'_, ConnResult<Self::Socket>>;
+    ) -> BoxFuture<'_, ConnectionResult<Self::Socket>>;
 
     fn dns_resolver(&self) -> BoxDnsResolver;
     fn lookup(
@@ -207,7 +209,7 @@ where
     fn bind(
         &self,
         addr: SocketAddr,
-    ) -> BoxFuture<'static, ConnResult<(SocketAddr, Self::ListenerType)>> {
+    ) -> BoxFuture<'static, ConnectionResult<(SocketAddr, Self::ListenerType)>> {
         <Self as ServerConnections>::bind(self, addr)
     }
 
@@ -216,7 +218,7 @@ where
         scheme: Scheme,
         host: Option<&str>,
         addr: SocketAddr,
-    ) -> BoxFuture<'_, ConnResult<Self::Socket>> {
+    ) -> BoxFuture<'_, ConnectionResult<Self::Socket>> {
         <Self as ClientConnections>::try_open(self, scheme, host, addr)
     }
 
@@ -233,10 +235,11 @@ where
     }
 }
 
+/// Error type indicating that host URL is not valid for the Warp protocol.
 #[derive(Debug, PartialEq, Eq, Error)]
-pub enum BadUrl {
+pub enum BadWarpUrl {
     #[error("Malformed URL: {0}")]
-    BadUrl(String),
+    MalformedUrl(String),
     #[error("A WARP URL must have a scheme.")]
     MissingScheme,
     #[error("{0} is not a valid WARP scheme.")]
@@ -245,9 +248,9 @@ pub enum BadUrl {
     NoHost,
 }
 
-impl From<InvalidUri> for BadUrl {
+impl From<InvalidUri> for BadWarpUrl {
     fn from(value: InvalidUri) -> Self {
-        BadUrl::BadUrl(value.to_string())
+        BadWarpUrl::MalformedUrl(value.to_string())
     }
 }
 
@@ -259,13 +262,13 @@ pub enum Scheme {
 }
 
 impl TryFrom<&str> for Scheme {
-    type Error = BadUrl;
+    type Error = BadWarpUrl;
 
     fn try_from(value: &str) -> Result<Self, Self::Error> {
         match value {
             "ws" | "swimos" | "warp" => Ok(Scheme::Ws),
             "wss" | "swims" | "warps" => Ok(Scheme::Wss),
-            _ => Err(BadUrl::BadScheme(value.to_owned())),
+            _ => Err(BadWarpUrl::BadScheme(value.to_owned())),
         }
     }
 }
@@ -331,15 +334,16 @@ impl Display for SchemeHostPort {
 }
 
 impl FromStr for SchemeHostPort {
-    type Err = BadUrl;
+    type Err = BadWarpUrl;
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         let uri = s.parse::<Uri>()?;
 
         let scheme = if let Some(scheme_part) = uri.scheme_str() {
-            Scheme::try_from(scheme_part).map_err(|_| BadUrl::BadScheme(scheme_part.to_string()))?
+            Scheme::try_from(scheme_part)
+                .map_err(|_| BadWarpUrl::BadScheme(scheme_part.to_string()))?
         } else {
-            return Err(BadUrl::MissingScheme);
+            return Err(BadWarpUrl::MissingScheme);
         };
 
         match (uri.host(), uri.port_u16()) {
@@ -354,7 +358,7 @@ impl FromStr for SchemeHostPort {
                     default_port,
                 ))
             }
-            _ => Err(BadUrl::NoHost),
+            _ => Err(BadWarpUrl::NoHost),
         }
     }
 }

runtime/swimos_remote/src/net/tests.rs

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use crate::net::{BadUrl, Scheme, SchemeHostPort};
+use crate::net::{BadWarpUrl, Scheme, SchemeHostPort};
 
 #[test]
 fn parse_insecure_warp_url() {
@@ -51,11 +51,11 @@ fn parse_secure_warp_url() {
 #[test]
 fn parse_unqualified_warp_url() {
     let result = "localhost:8080".parse::<SchemeHostPort>();
-    assert_eq!(result, Err(BadUrl::MissingScheme));
+    assert_eq!(result, Err(BadWarpUrl::MissingScheme));
 }
 
 #[test]
 fn parse_bad_warp_url_scheme() {
     let result = "ftp://localhost:8080".parse::<SchemeHostPort>();
-    assert_eq!(result, Err(BadUrl::BadScheme("ftp".to_string())));
+    assert_eq!(result, Err(BadWarpUrl::BadScheme("ftp".to_string())));
 }

runtime/swimos_remote/src/plain.rs

@@ -27,7 +27,7 @@ use std::sync::Arc;
 use tokio::net::{TcpListener, TcpStream};
 
 use crate::dns::BoxDnsResolver;
-use crate::net::{ClientConnections, ConnResult, ListenerResult, ServerConnections};
+use crate::net::{ClientConnections, ConnectionResult, ListenerResult, ServerConnections};
 
 /// Implementation of [`ServerConnections`] and [`ClientConnections`], using [`TcpListener`]
 /// and [`TcpStream`] from Tokio.
@@ -42,7 +42,7 @@ impl TokioPlainTextNetworking {
     }
 }
 
-async fn bind_to(addr: SocketAddr) -> ConnResult<(SocketAddr, TcpListener)> {
+async fn bind_to(addr: SocketAddr) -> ConnectionResult<(SocketAddr, TcpListener)> {
     let listener = TcpListener::bind(addr).await?;
     let addr = listener.local_addr()?;
     Ok((addr, listener))
@@ -58,7 +58,7 @@ impl ClientConnections for TokioPlainTextNetworking {
         scheme: Scheme,
         _host: Option<&str>,
         addr: SocketAddr,
-    ) -> BoxFuture<'static, ConnResult<Self::ClientSocket>> {
+    ) -> BoxFuture<'static, ConnectionResult<Self::ClientSocket>> {
         async move {
             match scheme {
                 Scheme::Ws => Ok(TcpStream::connect(addr).await?),
@@ -89,16 +89,18 @@ impl ServerConnections for TokioPlainTextNetworking {
     fn bind(
         &self,
         addr: SocketAddr,
-    ) -> BoxFuture<'static, ConnResult<(SocketAddr, Self::ListenerType)>> {
+    ) -> BoxFuture<'static, ConnectionResult<(SocketAddr, Self::ListenerType)>> {
         bind_to(addr).boxed()
     }
 }
 
+/// Wrapper around [`TcpListener`] that attaches the [`Scheme`] used for the incoming connection
+/// to the stream and peer address.
 #[pin_project]
 #[derive(Debug)]
-pub struct WithPeer(#[pin] TcpListener);
+pub struct WithScheme(#[pin] TcpListener);
 
-impl Stream for WithPeer {
+impl Stream for WithScheme {
     type Item = ListenerResult<(TcpStream, Scheme, SocketAddr)>;
 
     fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
@@ -110,9 +112,9 @@ impl Stream for WithPeer {
 }
 
 impl Listener<TcpStream> for TcpListener {
-    type AcceptStream = WithPeer;
+    type AcceptStream = WithScheme;
 
     fn into_stream(self) -> Self::AcceptStream {
-        WithPeer(self)
+        WithScheme(self)
     }
 }

runtime/swimos_remote/src/tls/config/mod.rs

@@ -18,7 +18,7 @@ pub enum CertFormat {
     Der,
 }
 
-/// An (unvalidated)) TLS certificate (or list of certificates for a PEM file).
+/// An unvalidated TLS certificate (or list of certificates for a PEM file).
 pub struct CertificateFile {
     pub format: CertFormat,
     pub body: Vec<u8>,
@@ -41,7 +41,7 @@ impl CertificateFile {
 /// A chain of TLS certificates (starting with the server certificate and ending with the CA).
 pub struct CertChain(pub Vec<CertificateFile>);
 
-/// An (unvalidated) private key for a server.
+/// An unvalidated private key for a server.
 pub struct PrivateKey {
     pub format: CertFormat,
     pub body: Vec<u8>,

runtime/swimos_remote/src/tls/errors.rs

@@ -14,16 +14,22 @@
 
 use thiserror::Error;
 
+/// Error type indicating that establishing a TLS connection failed.
 #[derive(Debug, Error)]
 pub enum TlsError {
+    /// A certificate PEM file was invalid.
     #[error("Error reading PEM file: {0}")]
     InvalidPem(std::io::Error),
+    /// The provided private key is invalid.
     #[error("The provided input did not contain a valid private key.")]
     InvalidPrivateKey,
+    /// Certificate validation failed.
     #[error("Invalid certificate: {0}")]
     BadCertificate(#[from] webpki::Error),
+    /// The provided host name was invalid.
     #[error("Invalid DNS host name.")]
     BadHostName,
+    /// Performing the TLS handshake failed.
     #[error("TLS handshake failed: {0}")]
     HandshakeFailed(std::io::Error),
 }

runtime/swimos_remote/src/tls/maybe/mod.rs

@@ -25,7 +25,7 @@ use tokio::{
 };
 use tokio_rustls::TlsStream;
 
-/// Either a simple, unencrypted [`tokio::TcpStream`] or a [`TlsStream`].
+/// Either a simple, unencrypted [`TcpStream`] or a [`TlsStream`].
 #[pin_project(project = MaybeTlsProj)]
 pub enum MaybeTlsStream {
     Plain(#[pin] TcpStream),