Add dedicated exception for basic.return messages.

Fixes #1831

This PR adds the `PublishReturnException` class that includes the
originating exchange and routing key for a `basic.return` message. It
should be backwards-compatible in the API.

Author: lukebakken

projects/RabbitMQ.Client/Exceptions/PublishException.cs

@@ -63,4 +63,55 @@ public PublishException(ulong publishSequenceNumber, bool isReturn) : base()
         /// </summary>
         public ulong PublishSequenceNumber => _publishSequenceNumber;
     }
+
+    /// <summary>
+    /// Class for exceptions related to publisher confirmations
+    /// or the <c>mandatory</c> flag, when <c>basic.return</c> is
+    /// sent from the broker.
+    /// </summary>
+    public class PublishReturnException : PublishException
+    {
+        private readonly string _exchange;
+        private readonly string _routingKey;
+
+        public PublishReturnException(ulong publishSequenceNumber, string exchange, string routingKey)
+            : base(publishSequenceNumber, true)
+        {
+            _exchange = exchange;
+            _routingKey = routingKey;
+        }
+
+        /// <summary>
+        /// Get the Exchange associated with this <c>basic.return</c>
+        /// </summary>
+        public string Exchange => _exchange;
+
+        /// <summary>
+        /// Get the RoutingKey associated with this <c>basic.return</c>
+        /// </summary>
+        public string RoutingKey => _routingKey;
+    }
+
+    internal static class PublishExceptionFactory
+    {
+        internal static PublishException Create(bool isReturn,
+            ulong deliveryTag, string? exchange = null, string? routingKey = null)
+        {
+            if (isReturn)
+            {
+                if (exchange is not null && routingKey is not null)
+                {
+                    return new PublishReturnException(deliveryTag, exchange, routingKey);
+                }
+                else
+                {
+                    return new PublishException(deliveryTag, isReturn);
+                }
+            }
+            else
+            {
+                return new PublishException(deliveryTag, isReturn);
+            }
+        }
+    }
 }

projects/RabbitMQ.Client/Impl/Channel.PublisherConfirms.cs

@@ -200,7 +200,8 @@ private void HandleAck(ulong deliveryTag, bool multiple)
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        private void HandleNack(ulong deliveryTag, bool multiple, bool isReturn)
+        private void HandleNack(ulong deliveryTag, bool multiple, bool isReturn,
+            string? exchange = null, string? routingKey = null)
         {
             if (ShouldHandleAckOrNack(deliveryTag))
             {
@@ -210,7 +211,8 @@ private void HandleNack(ulong deliveryTag, bool multiple, bool isReturn)
                     {
                         if (pair.Key <= deliveryTag)
                         {
-                            pair.Value.SetException(new PublishException(pair.Key, isReturn));
+                            PublishException ex = PublishExceptionFactory.Create(isReturn, pair.Key, exchange, routingKey);
+                            pair.Value.SetException(ex);
                             _confirmsTaskCompletionSources.Remove(pair.Key, out _);
                         }
                     }
@@ -219,7 +221,8 @@ private void HandleNack(ulong deliveryTag, bool multiple, bool isReturn)
                 {
                     if (_confirmsTaskCompletionSources.Remove(deliveryTag, out TaskCompletionSource<bool>? tcs))
                     {
-                        tcs.SetException(new PublishException(deliveryTag, isReturn));
+                        PublishException ex = PublishExceptionFactory.Create(isReturn, deliveryTag);
+                        tcs.SetException(ex);
                     }
                 }
             }
@@ -249,7 +252,8 @@ private void HandleReturn(BasicReturnEventArgs basicReturnEvent)
                     }
                 }
 
-                HandleNack(publishSequenceNumber, multiple: false, isReturn: true);
+                HandleNack(publishSequenceNumber, multiple: false, isReturn: true,
+                    exchange: basicReturnEvent.Exchange, routingKey: basicReturnEvent.RoutingKey);
             }
         }
 

projects/RabbitMQ.Client/PublicAPI.Unshipped.txt

@@ -0,0 +1,4 @@
+RabbitMQ.Client.Exceptions.PublishReturnException
+RabbitMQ.Client.Exceptions.PublishReturnException.Exchange.get -> string!
+RabbitMQ.Client.Exceptions.PublishReturnException.PublishReturnException(ulong publishSequenceNumber, string! exchange, string! routingKey) -> void
+RabbitMQ.Client.Exceptions.PublishReturnException.RoutingKey.get -> string!