RUST-2229 Expose raw deserializer (#584)

Author: isabelatkinson

src/de.rs

@@ -21,7 +21,7 @@
 
 //! Deserializer
 
-mod raw;
+pub(crate) mod raw;
 mod serde;
 
 pub use self::serde::Deserializer;
@@ -40,9 +40,6 @@ use ::serde::{de::DeserializeOwned, Deserialize};
 
 pub(crate) use self::serde::{convert_unsigned_to_signed_raw, BsonVisitor};
 
-#[cfg(test)]
-pub(crate) use self::raw::Deserializer as RawDeserializer;
-
 /// Hint provided to the deserializer via `deserialize_newtype_struct` as to the type of thing
 /// being deserialized.
 #[derive(Debug, Clone, Copy)]
@@ -108,11 +105,11 @@ pub fn deserialize_from_slice<'de, T>(bytes: &'de [u8]) -> Result<T>
 where
     T: Deserialize<'de>,
 {
-    deserialize_from_raw(raw::Deserializer::new(bytes)?)
+    deserialize_from_raw(raw::RawDeserializer::new(bytes)?)
 }
 
 pub(crate) fn deserialize_from_raw<'de, T: Deserialize<'de>>(
-    deserializer: raw::Deserializer<'de>,
+    deserializer: raw::RawDeserializer<'de>,
 ) -> Result<T> {
     #[cfg(feature = "serde_path_to_error")]
     {

src/de/raw.rs

@@ -37,8 +37,8 @@ use crate::{
 use super::{DeserializerHint, Error, Result};
 use crate::de::serde::MapDeserializer;
 
-/// Deserializer mapping from raw bson to serde's data model.
-pub(crate) struct Deserializer<'de> {
+/// Deserializer for deserializing raw BSON bytes.
+pub struct RawDeserializer<'de> {
     element: RawElement<'de>,
     options: DeserializerOptions,
 }
@@ -49,8 +49,10 @@ struct DeserializerOptions {
     human_readable: bool,
 }
 
-impl<'de> Deserializer<'de> {
-    pub(crate) fn new(buf: &'de [u8]) -> Result<Self> {
+impl<'de> RawDeserializer<'de> {
+    /// Construct a `RawDeserializer` with the provided bytes. Returns an error if the basic
+    /// structure of the bytes is invalid.
+    pub fn new(buf: &'de [u8]) -> Result<Self> {
         Ok(Self {
             element: RawElement::toplevel(buf)?,
             options: DeserializerOptions {
@@ -199,7 +201,7 @@ impl<'de> Deserializer<'de> {
     }
 }
 
-impl<'de> serde::de::Deserializer<'de> for Deserializer<'de> {
+impl<'de> serde::de::Deserializer<'de> for RawDeserializer<'de> {
     type Error = Error;
 
     #[inline]
@@ -336,7 +338,7 @@ impl<'de> DocumentAccess<'de> {
         Ok(())
     }
 
-    fn deserializer(self) -> Result<Deserializer<'de>> {
+    fn deserializer(self) -> Result<RawDeserializer<'de>> {
         let elem = match self.elem {
             Some(e) => e,
             None => {
@@ -345,7 +347,7 @@ impl<'de> DocumentAccess<'de> {
                 ))
             }
         };
-        Ok(Deserializer {
+        Ok(RawDeserializer {
             element: elem,
             options: self.options,
         })
@@ -374,7 +376,7 @@ impl<'de> serde::de::MapAccess<'de> for DocumentAccess<'de> {
     {
         match &self.elem {
             None => Err(Error::deserialization("too many values requested")),
-            Some(elem) => seed.deserialize(Deserializer {
+            Some(elem) => seed.deserialize(RawDeserializer {
                 element: elem.clone(),
                 options: self.options.clone(),
             }),
@@ -396,7 +398,7 @@ impl<'de> serde::de::SeqAccess<'de> for DocumentAccess<'de> {
         match &self.elem {
             None => Ok(None),
             Some(elem) => seed
-                .deserialize(Deserializer {
+                .deserialize(RawDeserializer {
                     element: elem.clone(),
                     options: self.options.clone(),
                 })

src/de/serde.rs

@@ -588,7 +588,7 @@ where
     }
 }
 
-/// Serde Deserializer
+/// Deserializer for deserializing a [`Bson`] value.
 pub struct Deserializer {
     value: Option<Bson>,
     options: DeserializerOptions,
@@ -604,7 +604,7 @@ pub(crate) struct DeserializerOptions {
 }
 
 impl Deserializer {
-    /// Construct a new [`Deserializer`] using the default options.
+    /// Construct a `Deserializer` with the provided [`Bson`] value.
     pub fn new(value: Bson) -> Deserializer {
         Deserializer::new_with_options(value, Default::default())
     }

src/lib.rs

@@ -407,6 +407,7 @@ pub use self::{
         deserialize_from_document,
         deserialize_from_reader,
         deserialize_from_slice,
+        raw::RawDeserializer,
         Deserializer,
     },
     ser::{

src/tests/spec/corpus.rs

@@ -185,7 +185,7 @@ fn run_test(test: TestFile) {
             if !description.contains("$regex query operator") {
                 // deserialize the field from raw Bytes into a RawBson
                 let deserializer_raw =
-                    crate::de::RawDeserializer::new(canonical_bson.as_slice()).unwrap();
+                    crate::RawDeserializer::new(canonical_bson.as_slice()).unwrap();
                 let raw_bson_field = deserializer_raw
                     .deserialize_any(FieldVisitor(test_key.as_str(), PhantomData::<RawBsonRef>))
                     .expect(&description);
@@ -197,7 +197,7 @@ fn run_test(test: TestFile) {
 
                 // deserialize the field from raw Bytes into an OwnedRawBson
                 let deserializer_raw =
-                    crate::de::RawDeserializer::new(canonical_bson.as_slice()).unwrap();
+                    crate::RawDeserializer::new(canonical_bson.as_slice()).unwrap();
                 let owned_raw_bson_field = deserializer_raw
                     .deserialize_any(FieldVisitor(test_key.as_str(), PhantomData::<RawBson>))
                     .expect(&description);
@@ -207,7 +207,7 @@ fn run_test(test: TestFile) {
 
                 // deserialize the field from raw Bytes into a Bson
                 let deserializer_value =
-                    crate::de::RawDeserializer::new(canonical_bson.as_slice()).unwrap();
+                    crate::RawDeserializer::new(canonical_bson.as_slice()).unwrap();
                 let bson_field = deserializer_value
                     .deserialize_any(FieldVisitor(test_key.as_str(), PhantomData::<Bson>))
                     .expect(&description);