Move types around and add docs

Author: sfackler

src/io.rs

@@ -0,0 +1,59 @@
+//! Types and traits for SSL adaptors.
+
+pub use priv_io::Stream;
+
+use openssl::ssl::{SslStream, SslContext};
+use std::error::Error;
+use std::io::prelude::*;
+
+/// A trait implemented by SSL adaptors.
+pub trait StreamWrapper: Read+Write+Send {
+    /// Returns a reference to the underlying `Stream`.
+    fn get_ref(&self) -> &Stream;
+
+    /// Returns a mutable reference to the underlying `Stream`.
+    fn get_mut(&mut self) -> &mut Stream;
+}
+
+impl StreamWrapper for SslStream<Stream> {
+    fn get_ref(&self) -> &Stream {
+        self.get_ref()
+    }
+
+    fn get_mut(&mut self) -> &mut Stream {
+        self.get_mut()
+    }
+}
+
+/// A trait implemented by types that can negotiate SSL over a Postgres stream.
+pub trait NegotiateSsl {
+    /// Negotiates an SSL session, returning a wrapper around the provided
+    /// stream.
+    ///
+    /// The host portion of the connection parameters is provided for hostname
+    /// verification.
+    fn negotiate_ssl(&mut self, host: &str, stream: Stream)
+                     -> Result<Box<StreamWrapper>, Box<Error>>;
+}
+
+impl NegotiateSsl for SslContext {
+    fn negotiate_ssl(&mut self, _: &str, stream: Stream)
+                     -> Result<Box<StreamWrapper>, Box<Error>> {
+        let stream = try!(SslStream::new(self, stream));
+        Ok(Box::new(stream))
+    }
+}
+
+/// An uninhabited type implementing `NegotiateSsl`.
+///
+/// `NoSsl` cannot be instantiated, so the only `SslMode<NoSslMode>` value that
+/// can exist is `SslMode::None`. `NoSsl` is the default value of `SslMode`'s
+/// parameter so `&mut SslMode::None` can always be passed into
+/// `Connection::connect` even if no SSL implementation is available.
+pub enum NoSsl {}
+
+impl NegotiateSsl for NoSsl {
+    fn negotiate_ssl(&mut self, _: &str, _: Stream) -> Result<Box<StreamWrapper>, Box<Error>> {
+        match *self {}
+    }
+}

src/lib.rs

@@ -66,7 +66,7 @@ use std::cell::{Cell, RefCell};
 use std::collections::{VecDeque, HashMap};
 use std::fmt;
 use std::iter::IntoIterator;
-use std::io;
+use std::io as std_io;
 use std::io::prelude::*;
 use std::mem;
 use std::slice;
@@ -79,7 +79,7 @@ use std::path::PathBuf;
 pub use error::{Error, ConnectError, SqlState, DbError, ErrorPosition};
 #[doc(inline)]
 pub use types::{Oid, Type, Kind, ToSql, FromSql};
-pub use io_util::{SslMode, NegotiateSsl, StreamWrapper, NoSsl, Stream};
+use io::{NoSsl, StreamWrapper, NegotiateSsl};
 use types::IsNull;
 #[doc(inline)]
 pub use types::Slice;
@@ -93,9 +93,10 @@ use url::Url;
 mod macros;
 
 mod error;
-mod io_util;
+pub mod io;
 mod message;
 mod ugh_privacy;
+mod priv_io;
 mod url;
 mod util;
 pub mod types;
@@ -390,7 +391,7 @@ pub fn cancel_query<T, N>(params: T, ssl: &mut SslMode<N>, data: CancelData)
                           -> result::Result<(), ConnectError>
         where T: IntoConnectParams, N: NegotiateSsl {
     let params = try!(params.into_connect_params());
-    let mut socket = try!(io_util::initialize_stream(&params, ssl));
+    let mut socket = try!(priv_io::initialize_stream(&params, ssl));
 
     try!(socket.write_message(&CancelRequest {
         code: message::CANCEL_CODE,
@@ -456,6 +457,16 @@ impl IsolationLevel {
     }
 }
 
+/// Specifies the SSL support requested for a new connection.
+pub enum SslMode<N = NoSsl> {
+    /// The connection will not use SSL.
+    None,
+    /// The connection will use SSL if the backend supports it.
+    Prefer(N),
+    /// The connection must use SSL.
+    Require(N),
+}
+
 #[derive(Clone)]
 struct CachedStatement {
     name: String,
@@ -490,7 +501,7 @@ impl InnerConnection {
                      -> result::Result<InnerConnection, ConnectError>
             where T: IntoConnectParams, N: NegotiateSsl {
         let params = try!(params.into_connect_params());
-        let stream = try!(io_util::initialize_stream(&params, ssl));
+        let stream = try!(priv_io::initialize_stream(&params, ssl));
 
         let ConnectParams { user, database, mut options, .. } = params;
 
@@ -570,15 +581,15 @@ impl InnerConnection {
         }
     }
 
-    fn write_messages(&mut self, messages: &[FrontendMessage]) -> io::Result<()> {
+    fn write_messages(&mut self, messages: &[FrontendMessage]) -> std_io::Result<()> {
         debug_assert!(!self.desynchronized);
         for message in messages {
             try_desync!(self, self.stream.write_message(message));
         }
         Ok(try_desync!(self, self.stream.flush()))
     }
 
-    fn read_one_message(&mut self) -> io::Result<Option<BackendMessage>> {
+    fn read_one_message(&mut self) -> std_io::Result<Option<BackendMessage>> {
         debug_assert!(!self.desynchronized);
         match try_desync!(self, self.stream.read_message()) {
             NoticeResponse { fields } => {
@@ -595,15 +606,15 @@ impl InnerConnection {
         }
     }
 
-    fn read_message_with_notification(&mut self) -> io::Result<BackendMessage> {
+    fn read_message_with_notification(&mut self) -> std_io::Result<BackendMessage> {
         loop {
             if let Some(msg) = try!(self.read_one_message()) {
                 return Ok(msg);
             }
         }
     }
 
-    fn read_message(&mut self) -> io::Result<BackendMessage> {
+    fn read_message(&mut self) -> std_io::Result<BackendMessage> {
         loop {
             match try!(self.read_message_with_notification()) {
                 NotificationResponse { pid, channel, payload } => {

src/io_util.rs src/priv_io.rssrc/io_util.rs renamed to src/priv_io.rs

@@ -1,19 +1,18 @@
-use openssl::ssl::{SslStream, SslContext};
-use std::error::Error;
+use byteorder::ReadBytesExt;
 use std::io;
 use std::io::prelude::*;
 use std::net::TcpStream;
 #[cfg(feature = "unix_socket")]
 use unix_socket::UnixStream;
-use byteorder::ReadBytesExt;
 
-use {ConnectParams, ConnectTarget, ConnectError};
-use message;
-use message::WriteMessage;
+use {SslMode, ConnectError, ConnectParams, ConnectTarget};
+use io::{NegotiateSsl, StreamWrapper};
+use message::{self, WriteMessage};
 use message::FrontendMessage::SslRequest;
 
 const DEFAULT_PORT: u16 = 5432;
 
+/// A connection to the Postgres server.
 pub struct Stream(InternalStream);
 
 impl Read for Stream {
@@ -42,53 +41,7 @@ impl StreamWrapper for Stream {
     }
 }
 
-pub trait StreamWrapper: Read+Write+Send {
-    fn get_ref(&self) -> &Stream;
-    fn get_mut(&mut self) -> &mut Stream;
-}
-
-impl StreamWrapper for SslStream<Stream> {
-    fn get_ref(&self) -> &Stream {
-        self.get_ref()
-    }
-
-    fn get_mut(&mut self) -> &mut Stream {
-        self.get_mut()
-    }
-}
-
-pub trait NegotiateSsl {
-    fn negotiate_ssl(&mut self, host: &str, stream: Stream)
-                     -> Result<Box<StreamWrapper>, Box<Error>>;
-}
-
-impl NegotiateSsl for SslContext {
-    fn negotiate_ssl(&mut self, _: &str, stream: Stream)
-                     -> Result<Box<StreamWrapper>, Box<Error>> {
-        let stream = try!(SslStream::new(self, stream));
-        Ok(Box::new(stream))
-    }
-}
-
-/// Specifies the SSL support requested for a new connection.
-pub enum SslMode<N = NoSsl> {
-    /// The connection will not use SSL.
-    None,
-    /// The connection will use SSL if the backend supports it.
-    Prefer(N),
-    /// The connection must use SSL.
-    Require(N),
-}
-
-pub enum NoSsl {}
-
-impl NegotiateSsl for NoSsl {
-    fn negotiate_ssl(&mut self, _: &str, _: Stream) -> Result<Box<StreamWrapper>, Box<Error>> {
-        match *self {}
-    }
-}
-
-pub enum InternalStream {
+enum InternalStream {
     Tcp(TcpStream),
     #[cfg(feature = "unix_socket")]
     Unix(UnixStream),