feat(sns): add SnsSubscriptionMessage for confirmation message types

Add a separate SnsSubscriptionMessage struct for handling SubscriptionConfirmation
and UnsubscribeConfirmation SNS message types. This is a non-breaking change that
keeps the existing SnsMessage struct unchanged.

Changes:
- Add SnsSubscriptionMessage struct with subscribe_url (Option) and token fields
- Add documentation to SnsMessage/SnsMessageObj clarifying they are for Notification only
- Add test fixtures for both SubscriptionConfirmation and UnsubscribeConfirmation
- Add tests verifying deserialization of both confirmation types

The new struct distinguishes confirmation types by:
- sns_message_type field ("SubscriptionConfirmation" or "UnsubscribeConfirmation")
- subscribe_url: Some(url) for SubscriptionConfirmation, None for UnsubscribeConfirmation

Fixes #966

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: abhu85

lambda-events/src/event/sns/mod.rs

@@ -56,7 +56,11 @@ pub struct SnsRecord {
     pub other: serde_json::Map<String, Value>,
 }
 
-/// SnsMessage stores information about each record of a SNS event
+/// SnsMessage stores information about SNS **Notification** type messages only.
+///
+/// **Important**: This struct is designed specifically for handling SNS Notification messages
+/// (where `Type` field equals "Notification"). For handling SubscriptionConfirmation or
+/// UnsubscribeConfirmation messages, use [`SnsSubscriptionMessage`] instead.
 #[non_exhaustive]
 #[cfg_attr(feature = "builders", derive(Builder))]
 #[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
@@ -94,26 +98,99 @@ pub struct SnsMessage {
     pub signing_cert_url: String,
 
     /// A URL that you can use to unsubscribe the endpoint from this topic. If you visit this URL, Amazon SNS unsubscribes the endpoint and stops sending notifications to this endpoint.
-    ///
-    /// Note: This field is only present in Notification messages. It is not present in SubscriptionConfirmation or UnsubscribeConfirmation messages.
     #[serde(alias = "UnsubscribeURL")]
+    pub unsubscribe_url: String,
+
+    /// The Message value specified when the notification was published to the topic.
+    pub message: String,
+
+    /// This is a HashMap of defined attributes for a message. Additional details can be found in the [SNS Developer Guide](https://docs.aws.amazon.com/sns/latest/dg/sns-message-attributes.html)
+    #[serde(deserialize_with = "deserialize_lambda_map")]
+    #[serde(default)]
+    pub message_attributes: HashMap<String, MessageAttribute>,
+
+    /// Catchall to catch any additional fields that were present but not explicitly defined by this struct.
+    /// Enabled with Cargo feature `catch-all-fields`.
+    /// If `catch-all-fields` is disabled, any additional fields that are present will be ignored.
+    #[cfg(feature = "catch-all-fields")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "catch-all-fields")))]
+    #[serde(flatten)]
+    #[cfg_attr(feature = "builders", builder(default))]
+    pub other: serde_json::Map<String, Value>,
+}
+
+/// SnsSubscriptionMessage stores information about SNS SubscriptionConfirmation and
+/// UnsubscribeConfirmation type messages.
+///
+/// Use this struct when handling messages where the `Type` field equals "SubscriptionConfirmation"
+/// or "UnsubscribeConfirmation". For handling Notification messages, use [`SnsMessage`] instead.
+///
+/// # Distinguishing SubscriptionConfirmation from UnsubscribeConfirmation
+///
+/// Both message types use this same struct. You can distinguish them by:
+/// - Checking the `sns_message_type` field ("SubscriptionConfirmation" or "UnsubscribeConfirmation")
+/// - Checking `subscribe_url`: `Some(url)` for SubscriptionConfirmation, `None` for UnsubscribeConfirmation
+///
+/// # Example
+///
+/// ```ignore
+/// use aws_lambda_events::event::sns::SnsSubscriptionMessage;
+///
+/// fn handle_confirmation(msg: SnsSubscriptionMessage) {
+///     if let Some(url) = &msg.subscribe_url {
+///         // SubscriptionConfirmation - visit URL or use token to confirm
+///         println!("Confirm subscription at: {}", url);
+///     } else {
+///         // UnsubscribeConfirmation
+///         println!("Unsubscribe confirmed");
+///     }
+/// }
+/// ```
+#[non_exhaustive]
+#[cfg_attr(feature = "builders", derive(Builder))]
+#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "PascalCase")]
+pub struct SnsSubscriptionMessage {
+    /// The type of SNS message. Will be "SubscriptionConfirmation" or "UnsubscribeConfirmation".
+    #[serde(rename = "Type")]
+    pub sns_message_type: String,
+
+    /// A Universally Unique Identifier, unique for each message published.
+    pub message_id: String,
+
+    /// The Amazon Resource Name (ARN) for the topic that this message was published to.
+    pub topic_arn: String,
+
+    /// The Subject parameter specified when the notification was published to the topic.
     #[serde(default)]
-    pub unsubscribe_url: Option<String>,
+    pub subject: Option<String>,
+
+    /// The time (UTC) when the message was sent.
+    pub timestamp: DateTime<Utc>,
+
+    /// Version of the Amazon SNS signature used.
+    pub signature_version: String,
+
+    /// Base64-encoded SHA1withRSA signature of the Message, MessageId, Subject (if present), Type, Timestamp, and TopicArn values.
+    pub signature: String,
 
-    /// A URL that you can visit to re-confirm the subscription or confirm the unsubscription.
+    /// The URL to the certificate that was used to sign the message.
+    #[serde(alias = "SigningCertURL")]
+    pub signing_cert_url: String,
+
+    /// A URL that you can visit to confirm the subscription. Present only for SubscriptionConfirmation messages.
     ///
-    /// Note: This field is only present in SubscriptionConfirmation and UnsubscribeConfirmation messages.
+    /// For UnsubscribeConfirmation messages, this field will be `None`.
     #[serde(alias = "SubscribeURL")]
     #[serde(default)]
     pub subscribe_url: Option<String>,
 
-    /// A value you can use with the ConfirmSubscription action to re-confirm the subscription.
-    ///
-    /// Note: This field is only present in SubscriptionConfirmation and UnsubscribeConfirmation messages.
-    #[serde(default)]
-    pub token: Option<String>,
+    /// A value you can use with the ConfirmSubscription action to confirm the subscription.
+    /// Alternatively, you can simply visit the `subscribe_url`.
+    #[serde(rename = "Token")]
+    pub token: String,
 
-    /// The Message value specified when the notification was published to the topic.
+    /// The Message value containing a description of the subscription confirmation.
     pub message: String,
 
     /// This is a HashMap of defined attributes for a message. Additional details can be found in the [SNS Developer Guide](https://docs.aws.amazon.com/sns/latest/dg/sns-message-attributes.html)
@@ -181,7 +258,11 @@ pub struct SnsRecordObj<T: Serialize> {
     pub other: serde_json::Map<String, Value>,
 }
 
-/// Alternate version of `SnsMessage` to use in conjunction with `SnsEventObj<T>` and `SnsRecordObj<T>` for deserializing the message into a struct of type `T`
+/// Alternate version of `SnsMessage` to use in conjunction with `SnsEventObj<T>` and `SnsRecordObj<T>` for deserializing the message into a struct of type `T`.
+///
+/// **Important**: This struct is designed specifically for handling SNS Notification messages
+/// (where `Type` field equals "Notification"). For handling SubscriptionConfirmation or
+/// UnsubscribeConfirmation messages, use [`SnsSubscriptionMessage`] instead.
 #[non_exhaustive]
 #[cfg_attr(feature = "builders", derive(Builder))]
 #[serde_with::serde_as]
@@ -221,24 +302,8 @@ pub struct SnsMessageObj<T: Serialize> {
     pub signing_cert_url: String,
 
     /// A URL that you can use to unsubscribe the endpoint from this topic. If you visit this URL, Amazon SNS unsubscribes the endpoint and stops sending notifications to this endpoint.
-    ///
-    /// Note: This field is only present in Notification messages. It is not present in SubscriptionConfirmation or UnsubscribeConfirmation messages.
     #[serde(alias = "UnsubscribeURL")]
-    #[serde(default)]
-    pub unsubscribe_url: Option<String>,
-
-    /// A URL that you can visit to re-confirm the subscription or confirm the unsubscription.
-    ///
-    /// Note: This field is only present in SubscriptionConfirmation and UnsubscribeConfirmation messages.
-    #[serde(alias = "SubscribeURL")]
-    #[serde(default)]
-    pub subscribe_url: Option<String>,
-
-    /// A value you can use with the ConfirmSubscription action to re-confirm the subscription.
-    ///
-    /// Note: This field is only present in SubscriptionConfirmation and UnsubscribeConfirmation messages.
-    #[serde(default)]
-    pub token: Option<String>,
+    pub unsubscribe_url: String,
 
     /// Deserialized into a `T` from nested JSON inside the SNS message string. `T` must implement the `Deserialize` or `DeserializeOwned` trait.
     #[serde_as(as = "serde_with::json::JsonString")]
@@ -498,41 +563,36 @@ mod test {
     #[test]
     #[cfg(feature = "sns")]
     fn my_example_sns_subscription_confirmation() {
-        // Test for issue #966: SnsMessage struct fails with SubscriptionConfirmation types
-        // SubscriptionConfirmation messages have SubscribeURL and Token fields instead of UnsubscribeURL
+        // Test for issue #966: SnsSubscriptionMessage for SubscriptionConfirmation types
         let data = include_bytes!("../../fixtures/example-sns-subscription-confirmation.json");
-        let parsed: SnsEvent = serde_json::from_slice(data).unwrap();
-        assert_eq!(1, parsed.records.len());
+        let parsed: SnsSubscriptionMessage = serde_json::from_slice(data).unwrap();
 
-        let sns_message = &parsed.records[0].sns;
-        assert_eq!("SubscriptionConfirmation", sns_message.sns_message_type);
-        assert!(sns_message.unsubscribe_url.is_none());
-        assert!(sns_message.subscribe_url.is_some());
-        assert!(sns_message.token.is_some());
+        assert_eq!("SubscriptionConfirmation", parsed.sns_message_type);
+        assert!(parsed.subscribe_url.is_some());
         assert_eq!(
             "https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-east-1:123456789012:MyTopic&Token=2336412f37fb687f5d51e6e2425dacbbffff",
-            sns_message.subscribe_url.as_ref().unwrap()
-        );
-        assert_eq!(
-            "2336412f37fb687f5d51e6e2425dacbbffff",
-            sns_message.token.as_ref().unwrap()
+            parsed.subscribe_url.as_ref().unwrap()
         );
+        assert_eq!("2336412f37fb687f5d51e6e2425dacbbffff", parsed.token);
 
         let output: String = serde_json::to_string(&parsed).unwrap();
-        let reparsed: SnsEvent = serde_json::from_slice(output.as_bytes()).unwrap();
+        let reparsed: SnsSubscriptionMessage = serde_json::from_slice(output.as_bytes()).unwrap();
         assert_eq!(parsed, reparsed);
     }
 
     #[test]
     #[cfg(feature = "sns")]
-    fn my_example_sns_notification_has_unsubscribe_url() {
-        // Verify that Notification messages still have unsubscribe_url
-        let data = include_bytes!("../../fixtures/example-sns-event.json");
-        let parsed: SnsEvent = serde_json::from_slice(data).unwrap();
-        let sns_message = &parsed.records[0].sns;
-        assert_eq!("Notification", sns_message.sns_message_type);
-        assert!(sns_message.unsubscribe_url.is_some());
-        assert!(sns_message.subscribe_url.is_none());
-        assert!(sns_message.token.is_none());
+    fn my_example_sns_unsubscribe_confirmation() {
+        // Test for UnsubscribeConfirmation messages - subscribe_url should be None
+        let data = include_bytes!("../../fixtures/example-sns-unsubscribe-confirmation.json");
+        let parsed: SnsSubscriptionMessage = serde_json::from_slice(data).unwrap();
+
+        assert_eq!("UnsubscribeConfirmation", parsed.sns_message_type);
+        assert!(parsed.subscribe_url.is_none());
+        assert_eq!("2336412f37fb687f5d51e6e2425dacbbeeee", parsed.token);
+
+        let output: String = serde_json::to_string(&parsed).unwrap();
+        let reparsed: SnsSubscriptionMessage = serde_json::from_slice(output.as_bytes()).unwrap();
+        assert_eq!(parsed, reparsed);
     }
 }

lambda-events/src/fixtures/example-sns-subscription-confirmation.json

@@ -1,23 +1,14 @@
 {
-  "Records": [
-    {
-      "EventVersion": "1.0",
-      "EventSubscriptionArn": "arn:aws:sns:us-east-1:123456789012:MyTopic:00000000-0000-0000-0000-000000000000",
-      "EventSource": "aws:sns",
-      "Sns": {
-        "Type": "SubscriptionConfirmation",
-        "MessageId": "165545c9-2a5c-472c-8df2-7ff2be2b3b1b",
-        "TopicArn": "arn:aws:sns:us-east-1:123456789012:MyTopic",
-        "Message": "You have chosen to subscribe to the topic arn:aws:sns:us-east-1:123456789012:MyTopic.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
-        "Timestamp": "2012-04-26T20:45:04.751Z",
-        "SignatureVersion": "1",
-        "Signature": "EXAMPLEpH+DcEwjAPg8O9mY8dReBSwksfg2S7WKQcikcNKWLQjwu6A4VbeS0QHVCkhRS7fUQvi2egU3N858fiTDN6bkkOxYDVrY0Ad8L10Hs3zH81mtnPk5uvvolIC1CXGu43obcgFxeL3khZl8IKvO61GWB6jI9b5+gLPoBc1Q=",
-        "SigningCertURL": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-f3ecfb7224c7233fe7bb5f59f96de52f.pem",
-        "SubscribeURL": "https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-east-1:123456789012:MyTopic&Token=2336412f37fb687f5d51e6e2425dacbbffff",
-        "Token": "2336412f37fb687f5d51e6e2425dacbbffff",
-        "Subject": null,
-        "MessageAttributes": {}
-      }
-    }
-  ]
+  "Type": "SubscriptionConfirmation",
+  "MessageId": "165545c9-2a5c-472c-8df2-7ff2be2b3b1b",
+  "TopicArn": "arn:aws:sns:us-east-1:123456789012:MyTopic",
+  "Message": "You have chosen to subscribe to the topic arn:aws:sns:us-east-1:123456789012:MyTopic.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
+  "Timestamp": "2012-04-26T20:45:04.751Z",
+  "SignatureVersion": "1",
+  "Signature": "EXAMPLEpH+DcEwjAPg8O9mY8dReBSwksfg2S7WKQcikcNKWLQjwu6A4VbeS0QHVCkhRS7fUQvi2egU3N858fiTDN6bkkOxYDVrY0Ad8L10Hs3zH81mtnPk5uvvolIC1CXGu43obcgFxeL3khZl8IKvO61GWB6jI9b5+gLPoBc1Q=",
+  "SigningCertURL": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-f3ecfb7224c7233fe7bb5f59f96de52f.pem",
+  "SubscribeURL": "https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-east-1:123456789012:MyTopic&Token=2336412f37fb687f5d51e6e2425dacbbffff",
+  "Token": "2336412f37fb687f5d51e6e2425dacbbffff",
+  "Subject": null,
+  "MessageAttributes": {}
 }

lambda-events/src/fixtures/example-sns-unsubscribe-confirmation.json

@@ -0,0 +1,13 @@
+{
+  "Type": "UnsubscribeConfirmation",
+  "MessageId": "47138184-6831-46b8-8466-7168d3b90898",
+  "TopicArn": "arn:aws:sns:us-east-1:123456789012:MyTopic",
+  "Message": "You have chosen to deactivate subscription arn:aws:sns:us-east-1:123456789012:MyTopic:00000000-0000-0000-0000-000000000000.\nTo cancel this operation and restore the subscription, visit the SubscribeURL included in this message.",
+  "Timestamp": "2012-04-26T20:45:04.751Z",
+  "SignatureVersion": "1",
+  "Signature": "EXAMPLEpH+DcEwjAPg8O9mY8dReBSwksfg2S7WKQcikcNKWLQjwu6A4VbeS0QHVCkhRS7fUQvi2egU3N858fiTDN6bkkOxYDVrY0Ad8L10Hs3zH81mtnPk5uvvolIC1CXGu43obcgFxeL3khZl8IKvO61GWB6jI9b5+gLPoBc1Q=",
+  "SigningCertURL": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-f3ecfb7224c7233fe7bb5f59f96de52f.pem",
+  "Token": "2336412f37fb687f5d51e6e2425dacbbeeee",
+  "Subject": null,
+  "MessageAttributes": {}
+}