Use custom {de,}serialization for operation/response envelopes

src/types/get_folder.rs

@@ -5,18 +5,32 @@
 use serde::Deserialize;
 use xml_struct::XmlSerialize;
 
-use crate::{BaseFolderId, Folder, FolderShape, ResponseClass};
+use crate::{
+    types::sealed::EnvelopeBodyContents, BaseFolderId, Folder, FolderShape, Operation,
+    OperationResponse, ResponseClass, MESSAGES_NS_URI,
+};
 
-/// The request to get one or more folder(s).
+/// A request to get information on one or more folders.
 ///
 /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/getfolder>
 #[derive(Debug, XmlSerialize)]
+#[xml_struct(default_ns = MESSAGES_NS_URI)]
 pub struct GetFolder {
     pub folder_shape: FolderShape,
     pub folder_ids: Vec<BaseFolderId>,
 }
 
-/// The response to a GetFolder request.
+impl Operation for GetFolder {
+    type Response = GetFolderResponse;
+}
+
+impl EnvelopeBodyContents for GetFolder {
+    fn name() -> &'static str {
+        "GetFolder"
+    }
+}
+
+/// A response to a [`GetFolder`] request.
 ///
 /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/getfolderresponse>
 #[derive(Debug, Deserialize)]
@@ -25,14 +39,24 @@ pub struct GetFolderResponse {
     pub response_messages: ResponseMessages,
 }
 
-/// A collection of response messages from a GetFolder response.
+impl OperationResponse for GetFolderResponse {}
+
+impl EnvelopeBodyContents for GetFolderResponse {
+    fn name() -> &'static str {
+        "GetFolderResponse"
+    }
+}
+
+/// A collection of responses for individual entities within a request.
+///
+/// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/responsemessages>
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "PascalCase")]
 pub struct ResponseMessages {
     pub get_folder_response_message: Vec<GetFolderResponseMessage>,
 }
 
-/// A message in a GetFolder response.
+/// A response to a request for an individual folder within a [`GetFolder`] operation.
 ///
 /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/getfolderresponsemessage>
 #[derive(Debug, Deserialize)]
@@ -43,7 +67,7 @@ pub struct GetFolderResponseMessage {
     pub folders: Folders,
 }
 
-/// A list of folders in a GetFolder response message.
+/// A collection of information on Exchange folders.
 ///
 /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/folders-ex15websvcsotherref>
 #[derive(Debug, Deserialize)]

src/types/operations.rs

@@ -5,38 +5,39 @@
 use serde::Deserialize;
 use xml_struct::XmlSerialize;
 
-use crate::{
-    get_folder::{GetFolder, GetFolderResponse},
-    sync_folder_hierarchy::{SyncFolderHierarchy, SyncFolderHierarchyResponse},
-    MESSAGES_NS_URI,
-};
-
-/// Available EWS operations (requests) that can be performed against an
-/// Exchange server.
-#[derive(Debug, XmlSerialize)]
-#[xml_struct(default_ns = MESSAGES_NS_URI)]
-pub enum Operation {
-    /// Retrieve information regarding one or more folder(s).
-    ///
-    /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/getfolder-operation#getfolder-request-example>
-    GetFolder(GetFolder),
-
-    /// Retrieve the latest changes in the folder hierarchy for this mailbox.
-    ///
-    /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/syncfolderhierarchy-operation#syncfolderhierarchy-request-example>
-    SyncFolderHierarchy(SyncFolderHierarchy),
+/// A marker trait for EWS operations.
+///
+/// Types implementing this trait may appear in requests to EWS as the operation
+/// to be performed.
+///
+/// # Usage
+///
+/// See [`Envelope`] for details.
+///
+/// [`Envelope`]: crate::soap::Envelope
+pub trait Operation: XmlSerialize + sealed::EnvelopeBodyContents {
+    /// The structure returned by EWS in response to requests containing this
+    /// operation.
+    type Response: OperationResponse;
 }
 
-/// Responses to available operations.
-#[derive(Debug, Deserialize)]
-pub enum OperationResponse {
-    /// The response to a GetFolder operation.
-    ///
-    /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/getfolder-operation#getfolder-response-example>
-    GetFolderResponse(GetFolderResponse),
+/// A marker trait for EWS operation responses.
+///
+/// Types implementing this trait may appear in responses from EWS after
+/// requesting an operation be performed.
+///
+/// # Usage
+///
+/// See [`Envelope`] for details.
+///
+/// [`Envelope`]: crate::soap::Envelope
+pub trait OperationResponse: for<'de> Deserialize<'de> + sealed::EnvelopeBodyContents {}
 
-    /// The response to a SyncFolderHierarchy operation.
-    ///
-    /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/syncfolderhierarchy-operation#successful-syncfolderhierarchy-response>
-    SyncFolderHierarchyResponse(SyncFolderHierarchyResponse),
+pub(super) mod sealed {
+    /// A trait for structures which may appear in the body of a SOAP envelope.
+    pub trait EnvelopeBodyContents {
+        /// Gets the name of the element enclosing the contents of this
+        /// structure when represented in XML.
+        fn name() -> &'static str;
+    }
 }

src/types/soap.rs

@@ -6,10 +6,13 @@ use quick_xml::{
     events::{BytesDecl, BytesEnd, BytesStart, Event},
     Reader, Writer,
 };
-use serde::Deserialize;
-use xml_struct::XmlSerialize;
 
-use crate::{Error, MessageXml, ResponseCode, SOAP_NS_URI, TYPES_NS_URI};
+use crate::{
+    Error, MessageXml, Operation, OperationResponse, ResponseCode, SOAP_NS_URI, TYPES_NS_URI,
+};
+
+mod de;
+use self::de::DummyEnvelope;
 
 /// A SOAP envelope wrapping an EWS operation.
 ///
@@ -21,10 +24,13 @@ pub struct Envelope<B> {
 
 impl<B> Envelope<B>
 where
-    B: XmlSerialize,
+    B: Operation,
 {
     /// Serializes the SOAP envelope as a complete XML document.
     pub fn as_xml_document(&self) -> Result<Vec<u8>, Error> {
+        const SOAP_ENVELOPE: &str = "soap:Envelope";
+        const SOAP_BODY: &str = "soap:Body";
+
         let mut writer = {
             let inner: Vec<u8> = Default::default();
             Writer::new(inner)
@@ -33,39 +39,30 @@ where
         // All EWS examples use XML 1.0 with UTF-8, so stick to that for now.
         writer.write_event(Event::Decl(BytesDecl::new("1.0", Some("utf-8"), None)))?;
 
-        // To get around having to make `Envelope` itself implement
-        // `XmlSerialize`
+        // We manually write these elements in order to control the name we
+        // write the body with.
         writer.write_event(Event::Start(
-            BytesStart::new("soap:Envelope")
+            BytesStart::new(SOAP_ENVELOPE)
                 .with_attributes([("xmlns:soap", SOAP_NS_URI), ("xmlns:t", TYPES_NS_URI)]),
         ))?;
+        writer.write_event(Event::Start(BytesStart::new(SOAP_BODY)))?;
 
-        self.body.serialize_as_element(&mut writer, "soap:Body")?;
+        // Write the operation itself.
+        self.body.serialize_as_element(&mut writer, B::name())?;
 
-        writer.write_event(Event::End(BytesEnd::new("soap:Envelope")))?;
+        writer.write_event(Event::End(BytesEnd::new(SOAP_BODY)))?;
+        writer.write_event(Event::End(BytesEnd::new(SOAP_ENVELOPE)))?;
 
         Ok(writer.into_inner())
     }
 }
 
 impl<B> Envelope<B>
 where
-    B: for<'de> Deserialize<'de>,
+    B: OperationResponse,
 {
     /// Populates an [`Envelope`] from raw XML.
     pub fn from_xml_document(document: &[u8]) -> Result<Self, Error> {
-        #[derive(Deserialize)]
-        #[serde(rename_all = "PascalCase")]
-        struct DummyEnvelope<T> {
-            body: DummyBody<T>,
-        }
-
-        #[derive(Deserialize)]
-        struct DummyBody<T> {
-            #[serde(rename = "$value")]
-            inner: T,
-        }
-
         // The body of an envelope can contain a fault, indicating an error with
         // a request. We want to parse that and return it as the `Err` portion
         // of a result. However, Microsoft includes a field in their fault
@@ -83,7 +80,7 @@ where
         let envelope: DummyEnvelope<B> = quick_xml::de::from_reader(document)?;
 
         Ok(Envelope {
-            body: envelope.body.inner,
+            body: envelope.body,
         })
     }
 }
@@ -391,7 +388,7 @@ pub struct FaultDetail {
 mod tests {
     use serde::Deserialize;
 
-    use crate::Error;
+    use crate::{types::sealed::EnvelopeBodyContents, Error, OperationResponse};
 
     use super::Envelope;
 
@@ -405,6 +402,14 @@ mod tests {
             _other_field: (),
         }
 
+        impl OperationResponse for SomeStruct {}
+
+        impl EnvelopeBodyContents for SomeStruct {
+            fn name() -> &'static str {
+                "Foo"
+            }
+        }
+
         // This XML is contrived, with a custom structure defined in order to
         // test the generic behavior of the interface.
         let xml = r#"<?xml version="1.0" encoding="utf-8"?><s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><foo:Foo><text>testing content</text><other_field/></foo:Foo></s:Body></s:Envelope>"#;
@@ -421,10 +426,21 @@ mod tests {
 
     #[test]
     fn deserialize_envelope_with_schema_fault() {
+        #[derive(Debug, Deserialize)]
+        struct Foo;
+
+        impl OperationResponse for Foo {}
+
+        impl EnvelopeBodyContents for Foo {
+            fn name() -> &'static str {
+                "Foo"
+            }
+        }
+
         // This XML is drawn from testing data for `evolution-ews`.
         let xml = r#"<?xml version="1.0" encoding="utf-8"?><s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><s:Fault><faultcode xmlns:a="http://schemas.microsoft.com/exchange/services/2006/types">a:ErrorSchemaValidation</faultcode><faultstring xml:lang="en-US">The request failed schema validation: The 'Id' attribute is invalid - The value 'invalidparentid' is invalid according to its datatype 'http://schemas.microsoft.com/exchange/services/2006/types:DistinguishedFolderIdNameType' - The Enumeration constraint failed.</faultstring><detail><e:ResponseCode xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">ErrorSchemaValidation</e:ResponseCode><e:Message xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">The request failed schema validation.</e:Message><t:MessageXml xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"><t:LineNumber>2</t:LineNumber><t:LinePosition>630</t:LinePosition><t:Violation>The 'Id' attribute is invalid - The value 'invalidparentid' is invalid according to its datatype 'http://schemas.microsoft.com/exchange/services/2006/types:DistinguishedFolderIdNameType' - The Enumeration constraint failed.</t:Violation></t:MessageXml></detail></s:Fault></s:Body></s:Envelope>"#;
 
-        let err = <Envelope<()>>::from_xml_document(xml.as_bytes())
+        let err = <Envelope<Foo>>::from_xml_document(xml.as_bytes())
             .expect_err("should return error when body contains fault");
 
         if let Error::RequestFault(fault) = err {
@@ -463,12 +479,23 @@ mod tests {
 
     #[test]
     fn deserialize_envelope_with_server_busy_fault() {
+        #[derive(Debug, Deserialize)]
+        struct Foo;
+
+        impl OperationResponse for Foo {}
+
+        impl EnvelopeBodyContents for Foo {
+            fn name() -> &'static str {
+                "Foo"
+            }
+        }
+
         // This XML is contrived based on what's known of the shape of
         // `ErrorServerBusy` responses. It should be replaced when we have
         // real-life examples.
         let xml = r#"<?xml version="1.0" encoding="utf-8"?><s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><s:Fault><faultcode xmlns:a="http://schemas.microsoft.com/exchange/services/2006/types">a:ErrorServerBusy</faultcode><faultstring xml:lang="en-US">I made this up because I don't have real testing data. 🙃</faultstring><detail><e:ResponseCode xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">ErrorServerBusy</e:ResponseCode><e:Message xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">Who really knows?</e:Message><t:MessageXml xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"><t:Value Name="BackOffMilliseconds">25</t:Value></t:MessageXml></detail></s:Fault></s:Body></s:Envelope>"#;
 
-        let err = <Envelope<()>>::from_xml_document(xml.as_bytes())
+        let err = <Envelope<Foo>>::from_xml_document(xml.as_bytes())
             .expect_err("should return error when body contains fault");
 
         // The testing here isn't as thorough as the invalid schema test due to

src/types/soap/de.rs

@@ -0,0 +1,80 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+use std::marker::PhantomData;
+
+use serde::{de::Visitor, Deserialize, Deserializer};
+
+use crate::OperationResponse;
+
+#[derive(Deserialize)]
+#[serde(rename_all = "PascalCase")]
+pub(super) struct DummyEnvelope<T>
+where
+    T: OperationResponse,
+{
+    #[serde(deserialize_with = "deserialize_body")]
+    pub body: T,
+}
+
+fn deserialize_body<'de, D, T>(body: D) -> Result<T, D::Error>
+where
+    D: Deserializer<'de>,
+    T: OperationResponse,
+{
+    body.deserialize_map(BodyVisitor::<T>(PhantomData))
+}
+
+/// A visitor for custom name-based deserialization of operation responses.
+struct BodyVisitor<T>(PhantomData<T>);
+
+impl<'de, T> Visitor<'de> for BodyVisitor<T>
+where
+    T: OperationResponse,
+{
+    type Value = T;
+
+    fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
+        formatter.write_str("EWS operation response body")
+    }
+
+    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
+    where
+        A: serde::de::MapAccess<'de>,
+    {
+        match map.next_key::<String>()? {
+            Some(name) => {
+                // We expect the body of the response to contain a single
+                // element with the name of the expected operation response.
+                let expected = T::name();
+                if name.as_str() != expected {
+                    return Err(serde::de::Error::custom(format_args!(
+                        "unknown field `{}`, expected {}",
+                        name, expected
+                    )));
+                }
+
+                let value = map.next_value()?;
+
+                // To satisfy quick-xml's serde impl, we need to consume the
+                // final `None` key value in order to successfully complete.
+                match map.next_key::<String>()? {
+                    Some(name) => {
+                        // The response body contained more than one element,
+                        // which violates our expectations.
+                        Err(serde::de::Error::custom(format_args!(
+                            "unexpected field `{}`",
+                            name
+                        )))
+                    }
+                    None => Ok(value),
+                }
+            }
+            None => Err(serde::de::Error::invalid_type(
+                serde::de::Unexpected::Map,
+                &self,
+            )),
+        }
+    }
+}