Docs and cleanup

Author: sfackler

src/authentication.rs

@@ -4,6 +4,9 @@ use md5::Context;
 
 /// Hashes authentication information in a way suitable for use in response
 /// to an `AuthenticationMd5Password` message.
+///
+/// The resulting string should be sent back to the database in a
+/// `PasswordMessage` message.
 #[inline]
 pub fn md5_hash(username: &[u8], password: &[u8], salt: [u8; 4]) -> String {
     let mut context = Context::new();

src/lib.rs

@@ -1,4 +1,14 @@
 //! Low level Postgres protocol APIs.
+//!
+//! This crate implements the low level components of Postgres's communication
+//! protocol, including message and value serialization and deserialization.
+//! It is designed to be used as a building block by higher level APIs such as
+//! `rust-postgres`, and should not typically be used directly.
+//!
+//! # Note
+//!
+//! This library assumes that the `client_encoding` backend parameter has been
+//! set to `UTF8`. It will most likely not behave properly if that is not the case.
 #![warn(missing_docs)]
 extern crate byteorder;
 extern crate fallible_iterator;

src/types.rs

@@ -625,7 +625,10 @@ pub fn empty_range_to_sql(buf: &mut Vec<u8>) {
 }
 
 /// Serializes a range value.
-pub fn range_to_sql<F, G>(lower: F, upper: G, buf: &mut Vec<u8>) -> Result<(), Box<Error + Sync + Send>>
+pub fn range_to_sql<F, G>(lower: F,
+                          upper: G,
+                          buf: &mut Vec<u8>)
+                          -> Result<(), Box<Error + Sync + Send>>
     where F: FnOnce(&mut Vec<u8>) -> Result<RangeBound<IsNull>, Box<Error + Sync + Send>>,
           G: FnOnce(&mut Vec<u8>) -> Result<RangeBound<IsNull>, Box<Error + Sync + Send>>
 {
@@ -701,11 +704,19 @@ pub fn range_from_sql<'a>(mut buf: &'a [u8]) -> Result<Range<'a>, Box<Error + Sy
     let lower = try!(read_bound(&mut buf, tag, RANGE_LOWER_UNBOUNDED, RANGE_LOWER_INCLUSIVE));
     let upper = try!(read_bound(&mut buf, tag, RANGE_UPPER_UNBOUNDED, RANGE_UPPER_INCLUSIVE));
 
+    if !buf.is_empty() {
+        return Err("invalid message size".into());
+    }
+
     Ok(Range::Nonempty(lower, upper))
 }
 
 #[inline]
-fn read_bound<'a>(buf: &mut &'a [u8], tag: u8, unbounded: u8, inclusive: u8) -> Result<RangeBound<Option<&'a [u8]>>, Box<Error + Sync + Send>> {
+fn read_bound<'a>(buf: &mut &'a [u8],
+                  tag: u8,
+                  unbounded: u8,
+                  inclusive: u8)
+                  -> Result<RangeBound<Option<&'a [u8]>>, Box<Error + Sync + Send>> {
     if tag & unbounded != 0 {
         Ok(RangeBound::Unbounded)
     } else {