API Review feedback; fixed a bunch of type documentation; reduced type visibility in public API surface. (Azure#2100)

* Moved public AMQP types to the root of AMQP; fixed a bunch of type documentation

* Refactored ProducerClient and ConsumerClient to use builder pattern.

Author: LarryOsterman

sdk/core/azure_core_amqp/examples/connection.rs

@@ -13,10 +13,7 @@
 //      cargo run --example connection --package azure_core_amqp
 
 use azure_core::Url;
-use azure_core_amqp::{
-    connection::{AmqpConnection, AmqpConnectionApis},
-    value::AmqpSymbol,
-};
+use azure_core_amqp::{AmqpConnection, AmqpConnectionApis, AmqpSymbol};
 
 async fn amqp_connection_open() {
     let connection = AmqpConnection::new();

sdk/core/azure_core_amqp/src/fe2o3/messaging/mod.rs

@@ -1,10 +1,10 @@
 // Copyright (c) Microsoft Corporation. All Rights reserved
 // Licensed under the MIT license.
 
-pub mod message_fields;
-pub mod message_source;
-pub mod message_target;
-pub mod messaging_types;
+pub(crate) mod message_fields;
+pub(crate) mod message_source;
+pub(crate) mod message_target;
+pub(crate) mod messaging_types;
 
 use crate::{
     messaging::{AmqpMessage, AmqpMessageBody},

sdk/core/azure_core_amqp/src/fe2o3/mod.rs

@@ -1,11 +1,11 @@
 // Copyright (c) Microsoft Corporation. All Rights reserved
 // Licensed under the MIT license.
-pub mod cbs;
-pub mod connection;
-pub mod error;
-pub mod management;
-pub mod messaging;
-pub mod receiver;
-pub mod sender;
-pub mod session;
-pub mod value;
+pub(crate) mod cbs;
+pub(crate) mod connection;
+pub(crate) mod error;
+pub(crate) mod management;
+pub(crate) mod messaging;
+pub(crate) mod receiver;
+pub(crate) mod sender;
+pub(crate) mod session;
+pub(crate) mod value;

sdk/core/azure_core_amqp/src/fe2o3/value.rs

@@ -203,14 +203,14 @@ impl From<AmqpValue> for fe2o3_amqp_types::primitives::Value {
             #[cfg(feature = "cplusplus")]
             AmqpValue::Composite(d) => fe2o3_amqp_types::primitives::Value::Described(Box::new(
                 serde_amqp::described::Described {
-                    descriptor: d.descriptor.clone().into(),
-                    value: d.value.clone().into(),
+                    descriptor: d.descriptor().clone().into(),
+                    value: d.value().clone().into(),
                 },
             )),
             AmqpValue::Described(d) => fe2o3_amqp_types::primitives::Value::Described(Box::new(
                 serde_amqp::described::Described {
-                    descriptor: d.descriptor.clone().into(),
-                    value: d.value.clone().into(),
+                    descriptor: d.descriptor().clone().into(),
+                    value: d.value().clone().into(),
                 },
             )),
             AmqpValue::Unknown => todo!(),
@@ -268,7 +268,7 @@ impl From<fe2o3_amqp_types::primitives::Value> for AmqpValue {
                         AmqpDescriptor::Name(symbol.into())
                     }
                 };
-                AmqpValue::Described(Box::new(AmqpDescribed { descriptor, value }))
+                AmqpValue::Described(Box::new(AmqpDescribed::new(descriptor, value)))
             }
             fe2o3_amqp_types::primitives::Value::Decimal128(_) => todo!(),
             fe2o3_amqp_types::primitives::Value::Decimal32(_) => todo!(),
@@ -281,7 +281,7 @@ impl PartialEq<AmqpDescribed>
     for serde_amqp::described::Described<fe2o3_amqp_types::primitives::Value>
 {
     fn eq(&self, other: &AmqpDescribed) -> bool {
-        self.descriptor == other.descriptor && self.value == other.value
+        self.descriptor == *other.descriptor() && self.value == *other.value()
     }
 }
 

sdk/core/azure_core_amqp/src/lib.rs

@@ -5,19 +5,31 @@ mod fe2o3;
 #[cfg(any(not(feature = "fe2o3-amqp"), target_arch = "wasm32"))]
 mod noop;
 
-pub mod cbs;
-pub mod connection;
-pub mod error;
-pub mod management;
-pub mod messaging;
-pub mod receiver;
-pub mod sender;
-pub mod session;
-pub mod value;
-
-pub use uuid::Uuid;
+pub(crate) mod cbs;
+pub(crate) mod connection;
+pub(crate) mod error;
+pub(crate) mod management;
+pub(crate) mod messaging;
+pub(crate) mod receiver;
+pub(crate) mod sender;
+pub(crate) mod session;
+pub(crate) mod value;
 
+pub use cbs::{AmqpClaimsBasedSecurity, AmqpClaimsBasedSecurityApis};
+pub use connection::{AmqpConnection, AmqpConnectionApis, AmqpConnectionOptions};
+pub use error::Error;
+pub use management::{AmqpManagement, AmqpManagementApis};
+pub use messaging::{
+    AmqpAnnotationKey, AmqpAnnotations, AmqpDelivery, AmqpDeliveryApis, AmqpMessage,
+    AmqpMessageBody, AmqpMessageHeader, AmqpMessageId, AmqpMessageProperties, AmqpSource,
+    AmqpSourceFilter, AmqpTarget,
+};
+pub use receiver::{AmqpReceiver, AmqpReceiverApis, AmqpReceiverOptions, ReceiverCreditMode};
+pub use sender::{AmqpSendOptions, AmqpSender, AmqpSenderApis, AmqpSenderOptions};
+pub use session::{AmqpSession, AmqpSessionApis, AmqpSessionOptions};
 use std::fmt::Debug;
+pub use uuid::Uuid;
+pub use value::{AmqpDescribed, AmqpList, AmqpOrderedMap, AmqpSymbol, AmqpTimestamp, AmqpValue};
 
 // AMQP Settle mode:
 // https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-transport-v1.0-os.html#type-sender-settle-mode

sdk/core/azure_core_amqp/src/messaging.rs

@@ -1081,7 +1081,7 @@ impl AmqpMessage {
     /// # Examples
     ///
     /// ```
-    /// use azure_core_amqp::messaging::AmqpMessage;
+    /// use azure_core_amqp::AmqpMessage;
     ///
     /// let mut message = AmqpMessage::default();
     /// message.set_message_id(uuid::Uuid::new_v4());
@@ -1110,8 +1110,8 @@ impl AmqpMessage {
     ///
     /// # Examples
     /// ```
-    /// use azure_core_amqp::messaging::AmqpMessage;
-    /// use azure_core_amqp::value::AmqpSymbol;
+    /// use azure_core_amqp::AmqpMessage;
+    /// use azure_core_amqp::AmqpSymbol;
     /// let mut message = AmqpMessage::default();
     /// message.add_message_annotation(AmqpSymbol::from("key"), "value");
     /// ```
@@ -1138,8 +1138,8 @@ impl AmqpMessage {
     /// # Examples
     ///
     /// ```
-    /// use azure_core_amqp::messaging::AmqpMessage;
-    /// use azure_core_amqp::messaging::AmqpMessageBody;
+    /// use azure_core_amqp::AmqpMessage;
+    /// use azure_core_amqp::AmqpMessageBody;
     ///
     /// let mut message = AmqpMessage::default();
     /// message.set_message_body(AmqpMessageBody::Value("Hello, world!".into()));
@@ -1229,7 +1229,7 @@ impl Deserializable<AmqpMessage> for AmqpMessage {
     }
 }
 
-pub mod builders {
+mod builders {
     use super::*;
 
     pub struct AmqpSourceBuilder {

sdk/core/azure_core_amqp/src/value.rs

@@ -16,15 +16,12 @@ use crate::{Deserializable, Serializable};
 #[cfg(feature = "cplusplus")]
 use azure_core::Result;
 
+/// An AMQP symbol.
+///
+/// Symbols are used to identify a type of data. They are similar to strings, and represent symbolic values from a constrained domain.
 #[derive(Debug, PartialEq, Clone, Default, Eq)]
 pub struct AmqpSymbol(pub String);
 
-// impl PartialEq<str> for AmqpSymbol {
-//     fn eq(&self, other: &str) -> bool {
-//         self.0.as_str() == other
-//     }
-// }
-
 impl PartialEq<AmqpSymbol> for str {
     fn eq(&self, other: &AmqpSymbol) -> bool {
         self == other.0.as_str()
@@ -77,6 +74,7 @@ impl Borrow<str> for AmqpSymbol {
     }
 }
 
+/// A sequence of AMQP values
 #[derive(Debug, PartialEq, Clone, Default)]
 pub struct AmqpList(pub Vec<AmqpValue>);
 
@@ -132,6 +130,10 @@ impl From<std::time::SystemTime> for AmqpTimestamp {
     }
 }
 
+/// An ordered mapping from distinct keys to values.
+///
+/// This is a simple implementation of a map that is backed by a vector.
+/// It is not intended to be used for large maps, but rather for small maps where the order of the keys is important.
 #[derive(Debug, PartialEq, Clone, Default)]
 pub struct AmqpOrderedMap<K, V>
 where
@@ -164,8 +166,8 @@ where
 
 #[derive(Debug, PartialEq, Clone)]
 pub struct AmqpDescribed {
-    pub descriptor: AmqpDescriptor,
-    pub value: AmqpValue,
+    descriptor: AmqpDescriptor,
+    value: AmqpValue,
 }
 
 impl AmqpDescribed {
@@ -185,12 +187,18 @@ impl AmqpDescribed {
     }
 }
 
+/// An AMQP Composite type.
+/// This is a complex type that is composed of a descriptor and a value.
+/// The descriptor is used to identify the type of the value.
+/// The value is the actual value.
 #[derive(Debug, PartialEq, Clone)]
+#[cfg(feature = "cplusplus")]
 pub struct AmqpComposite {
-    pub descriptor: AmqpDescriptor,
-    pub value: AmqpList,
+    descriptor: AmqpDescriptor,
+    value: AmqpList,
 }
 
+#[cfg(feature = "cplusplus")]
 impl AmqpComposite {
     pub fn new(descriptor: impl Into<AmqpDescriptor>, value: impl Into<AmqpList>) -> Self {
         Self {
@@ -212,26 +220,48 @@ impl AmqpComposite {
 pub enum AmqpValue {
     #[default]
     Null,
+    /// A boolean (true/false) value.
     Boolean(bool),
+    /// An unsigned byte value.
     UByte(u8),
+    /// An unsigned short value.
     UShort(u16),
+    /// An unsigned integer value.
     UInt(u32),
+    /// An unsigned long value.
     ULong(u64),
+    /// A signed byte value.
     Byte(i8),
+    /// A signed short value.
     Short(i16),
+    /// A signed integer value.
     Int(i32),
+    /// A signed long value.
     Long(i64),
+    /// A 32-bit floating point value.
     Float(f32),
+    /// A 64-bit floating point value.
     Double(f64),
+    /// A single Unicode character.
     Char(char),
+    /// A point in time.
     TimeStamp(AmqpTimestamp),
+    /// A universally unique identifier.
     Uuid(Uuid),
+    /// A sequence of octets.
     Binary(Vec<u8>),
+    /// A sequence of Unicode characters.
     String(String),
+    /// An AMQP Symbol.
     Symbol(AmqpSymbol),
+
+    /// An ordered list of AMQP values.
     List(AmqpList),
+    /// An ordered map of AMQP values.
     Map(AmqpOrderedMap<AmqpValue, AmqpValue>),
+    /// An array of AMQP values.
     Array(Vec<AmqpValue>),
+    /// A described value.
     Described(Box<AmqpDescribed>),
     #[cfg(feature = "cplusplus")]
     Composite(Box<AmqpComposite>),
@@ -509,7 +539,6 @@ where
 mod tests {
     use super::*;
     use std::vec;
-    use Uuid;
 
     #[test]
     fn test_value_create_specific() {
@@ -889,4 +918,16 @@ mod tests {
         assert_eq!(unknown_value, AmqpValue::Unknown);
         assert_eq!(AmqpValue::Unknown, unknown_value);
     }
+
+    #[test]
+    #[cfg(feature = "cplusplus")]
+    fn amqp_composite() {
+        let composite =
+            AmqpComposite::new(0x270, AmqpList::from(vec![AmqpValue::from("String value")]));
+        assert_eq!(composite.descriptor(), &AmqpDescriptor::Code(0x270));
+        assert_eq!(
+            composite.value(),
+            &AmqpList::from(vec![AmqpValue::from("String value")])
+        );
+    }
 }