Updated documentation; Throwing only FirebaseMessagingException from FCM APIs

Author: hiranya911

FirebaseAdmin/FirebaseAdmin.Tests/Messaging/FirebaseMessagingClientTest.cs

@@ -15,6 +15,7 @@
 using System;
 using System.Linq;
 using System.Net;
+using System.Net.Http;
 using System.Threading.Tasks;
 using FirebaseAdmin.Tests;
 using Google.Apis.Auth.OAuth2;
@@ -464,6 +465,38 @@ public async Task HttpErrorNonJsonAsync()
             Assert.Equal(1, handler.Calls);
         }
 
+        [Fact]
+        public async Task TransportError()
+        {
+            var handler = new MockMessageHandler()
+            {
+                Exception = new HttpRequestException("Transport error"),
+            };
+            var factory = new MockHttpClientFactory(handler);
+            var client = new FirebaseMessagingClient(factory, MockCredential, "test-project");
+            var message = new Message()
+            {
+                Topic = "test-topic",
+            };
+
+            var ex = await Assert.ThrowsAsync<FirebaseMessagingException>(
+                async () => await client.SendAsync(message));
+
+            Assert.Equal(ErrorCode.Unknown, ex.ErrorCode);
+            Assert.Equal(
+                "Unknown error while making a remote service call: Transport error",
+                ex.Message);
+            Assert.Null(ex.MessagingErrorCode);
+            Assert.Null(ex.HttpResponse);
+            Assert.Same(handler.Exception, ex.InnerException);
+
+            var req = JsonConvert.DeserializeObject<FirebaseMessagingClient.SendRequest>(
+                handler.LastRequestBody);
+            Assert.Equal("test-topic", req.Message.Topic);
+            Assert.False(req.ValidateOnly);
+            Assert.Equal(1, handler.Calls);
+        }
+
         private int CountLinesWithPrefix(string body, string linePrefix)
         {
             return body.Split('\n').Count((line) => line.StartsWith(linePrefix));

FirebaseAdmin/FirebaseAdmin.Tests/MockMessageHandler.cs

@@ -78,6 +78,12 @@ public HttpRequestHeaders LastRequestHeaders
         /// </summary>
         public object Response { get; set; }
 
+        /// <summary>
+        /// Gets or sets an exception to simulate low-level network errors. When specified, all invocations
+        /// of this message handler will fail by throwing this exception.
+        /// </summary>
+        public Exception Exception { get; set; }
+
         /// <summary>
         /// Gets or sets the function for modifying the response headers.
         /// </summary>
@@ -89,6 +95,13 @@ protected override async Task<HttpResponseMessage> DoSendAsync(
             var incomingRequest = await IncomingRequest.CreateAsync(request);
             this.requests.Add(incomingRequest);
 
+            var tcs = new TaskCompletionSource<HttpResponseMessage>();
+            if (this.Exception != null)
+            {
+                tcs.SetException(this.Exception);
+                return await tcs.Task;
+            }
+
             string json;
             if (this.Response is byte[])
             {
@@ -116,7 +129,6 @@ protected override async Task<HttpResponseMessage> DoSendAsync(
                 this.ApplyHeaders(resp.Headers, content.Headers);
             }
 
-            var tcs = new TaskCompletionSource<HttpResponseMessage>();
             tcs.SetResult(resp);
             return await tcs.Task;
         }

FirebaseAdmin/FirebaseAdmin/HttpErrorHandler.cs

@@ -52,18 +52,18 @@ internal void ThrowIfError(HttpResponseMessage response, string body)
                 return;
             }
 
-            var info = this.ExtractErrorInfo(response, body);
-            var args = new FirebaseExceptionArgs()
-            {
-                Code = info.Code,
-                Message = info.Message,
-                HttpResponse = response,
-                ResponseBody = body,
-            };
+            var args = this.CreateExceptionArgs(response, body);
             throw this.CreateException(args);
         }
 
-        protected virtual ErrorInfo ExtractErrorInfo(HttpResponseMessage response, string body)
+        /// <summary>
+        /// Parses the given HTTP response to extract an error code and message from it.
+        /// </summary>
+        /// <param name="response">HTTP response message to process.</param>
+        /// <param name="body">The response body read from the message.</param>
+        /// <returns>A <see cref="FirebaseExceptionArgs"/> object containing error code and message.
+        /// Both the code and the message should not be null or empty.</returns>
+        protected virtual FirebaseExceptionArgs CreateExceptionArgs(HttpResponseMessage response, string body)
         {
             ErrorCode code;
             if (!HttpErrorCodes.TryGetValue(response.StatusCode, out code))
@@ -74,25 +74,26 @@ protected virtual ErrorInfo ExtractErrorInfo(HttpResponseMessage response, strin
             var message = "Unexpected HTTP response with status: "
                 + $"{(int)response.StatusCode} ({response.StatusCode})"
                 + $"{Environment.NewLine}{body}";
-            return new ErrorInfo()
+            return new FirebaseExceptionArgs()
             {
                 Code = code,
                 Message = message,
+                HttpResponse = response,
+                ResponseBody = body,
             };
         }
 
+        /// <summary>
+        /// Creates a new <see cref="FirebaseException"/> from the specified arguments.
+        /// </summary>
+        /// <param name="args">A <see cref="FirebaseExceptionArgs"/> instance containing error
+        /// code, message and other details.</param>
+        /// <returns>A <see cref="FirebaseException"/> object.</returns>
         protected virtual FirebaseException CreateException(FirebaseExceptionArgs args)
         {
             return new FirebaseException(args.Code, args.Message, response: args.HttpResponse);
         }
 
-        internal sealed class ErrorInfo
-        {
-            internal ErrorCode Code { get; set; }
-
-            internal string Message { get; set; }
-        }
-
         internal sealed class FirebaseExceptionArgs
         {
             internal ErrorCode Code { get; set; }

FirebaseAdmin/FirebaseAdmin/Messaging/FirebaseMessaging.cs

@@ -83,7 +83,7 @@ public static FirebaseMessaging GetMessaging(FirebaseApp app)
         /// <exception cref="ArgumentNullException">If the message argument is null.</exception>
         /// <exception cref="ArgumentException">If the message contains any invalid
         /// fields.</exception>
-        /// <exception cref="FirebaseException">If an error occurs while sending the
+        /// <exception cref="FirebaseMessagingException">If an error occurs while sending the
         /// message.</exception>
         /// <param name="message">The message to be sent. Must not be null.</param>
         public async Task<string> SendAsync(Message message)
@@ -102,7 +102,7 @@ public async Task<string> SendAsync(Message message)
         /// <exception cref="ArgumentNullException">If the message argument is null.</exception>
         /// <exception cref="ArgumentException">If the message contains any invalid
         /// fields.</exception>
-        /// <exception cref="FirebaseException">If an error occurs while sending the
+        /// <exception cref="FirebaseMessagingException">If an error occurs while sending the
         /// message.</exception>
         /// <param name="message">The message to be sent. Must not be null.</param>
         /// <param name="cancellationToken">A cancellation token to monitor the asynchronous
@@ -127,7 +127,7 @@ public async Task<string> SendAsync(Message message, CancellationToken cancellat
         /// <exception cref="ArgumentNullException">If the message argument is null.</exception>
         /// <exception cref="ArgumentException">If the message contains any invalid
         /// fields.</exception>
-        /// <exception cref="FirebaseException">If an error occurs while sending the
+        /// <exception cref="FirebaseMessagingException">If an error occurs while sending the
         /// message.</exception>
         /// <param name="message">The message to be sent. Must not be null.</param>
         /// <param name="dryRun">A boolean indicating whether to perform a dry run (validation
@@ -153,7 +153,7 @@ public async Task<string> SendAsync(Message message, bool dryRun)
         /// <exception cref="ArgumentNullException">If the message argument is null.</exception>
         /// <exception cref="ArgumentException">If the message contains any invalid
         /// fields.</exception>
-        /// <exception cref="FirebaseException">If an error occurs while sending the
+        /// <exception cref="FirebaseMessagingException">If an error occurs while sending the
         /// message.</exception>
         /// <param name="message">The message to be sent. Must not be null.</param>
         /// <param name="dryRun">A boolean indicating whether to perform a dry run (validation
@@ -173,6 +173,8 @@ public async Task<string> SendAsync(
         /// send the entire list as a single RPC call. Compared to the <see cref="SendAsync(Message)"/>
         /// method, this is a significantly more efficient way to send multiple messages.
         /// </summary>
+        /// <exception cref="FirebaseMessagingException">If an error occurs while sending the
+        /// messages.</exception>
         /// <param name="messages">Up to 100 messages to send in the batch. Cannot be null.</param>
         /// <returns>A <see cref="BatchResponse"/> containing details of the batch operation's
         /// outcome.</returns>
@@ -186,6 +188,8 @@ public async Task<BatchResponse> SendAllAsync(IEnumerable<Message> messages)
         /// send the entire list as a single RPC call. Compared to the <see cref="SendAsync(Message)"/>
         /// method, this is a significantly more efficient way to send multiple messages.
         /// </summary>
+        /// <exception cref="FirebaseMessagingException">If an error occurs while sending the
+        /// messages.</exception>
         /// <param name="messages">Up to 100 messages to send in the batch. Cannot be null.</param>
         /// <param name="cancellationToken">A cancellation token to monitor the asynchronous
         /// operation.</param>
@@ -201,6 +205,8 @@ public async Task<BatchResponse> SendAllAsync(IEnumerable<Message> messages, Can
         /// send the entire list as a single RPC call. Compared to the <see cref="SendAsync(Message)"/>
         /// method, this is a significantly more efficient way to send multiple messages.
         /// </summary>
+        /// <exception cref="FirebaseMessagingException">If an error occurs while sending the
+        /// messages.</exception>
         /// <param name="messages">Up to 100 messages to send in the batch. Cannot be null.</param>
         /// <param name="dryRun">A boolean indicating whether to perform a dry run (validation
         /// only) of the send. If set to true, the message will be sent to the FCM backend service,
@@ -217,6 +223,8 @@ public async Task<BatchResponse> SendAllAsync(IEnumerable<Message> messages, boo
         /// send the entire list as a single RPC call. Compared to the <see cref="SendAsync(Message)"/>
         /// method, this is a significantly more efficient way to send multiple messages.
         /// </summary>
+        /// <exception cref="FirebaseMessagingException">If an error occurs while sending the
+        /// messages.</exception>
         /// <param name="messages">Up to 100 messages to send in the batch. Cannot be null.</param>
         /// <param name="dryRun">A boolean indicating whether to perform a dry run (validation
         /// only) of the send. If set to true, the message will be sent to the FCM backend service,
@@ -233,6 +241,8 @@ public async Task<BatchResponse> SendAllAsync(IEnumerable<Message> messages, boo
         /// <summary>
         /// Sends the given multicast message to all the FCM registration tokens specified in it.
         /// </summary>
+        /// <exception cref="FirebaseMessagingException">If an error occurs while sending the
+        /// messages.</exception>
         /// <param name="message">The message to be sent. Must not be null.</param>
         /// <returns>A <see cref="BatchResponse"/> containing details of the batch operation's
         /// outcome.</returns>
@@ -244,6 +254,8 @@ public async Task<BatchResponse> SendMulticastAsync(MulticastMessage message)
         /// <summary>
         /// Sends the given multicast message to all the FCM registration tokens specified in it.
         /// </summary>
+        /// <exception cref="FirebaseMessagingException">If an error occurs while sending the
+        /// messages.</exception>
         /// <param name="message">The message to be sent. Must not be null.</param>
         /// <param name="cancellationToken">A cancellation token to monitor the asynchronous
         /// operation.</param>
@@ -261,6 +273,8 @@ public async Task<BatchResponse> SendMulticastAsync(MulticastMessage message, Ca
         /// validations, and emulates the send operation. This is a good way to check if a
         /// certain message will be accepted by FCM for delivery.</para>
         /// </summary>
+        /// <exception cref="FirebaseMessagingException">If an error occurs while sending the
+        /// messages.</exception>
         /// <param name="message">The message to be sent. Must not be null.</param>
         /// <param name="dryRun">A boolean indicating whether to perform a dry run (validation
         /// only) of the send. If set to true, the message will be sent to the FCM backend service,
@@ -279,6 +293,8 @@ public async Task<BatchResponse> SendMulticastAsync(MulticastMessage message, bo
         /// validations, and emulates the send operation. This is a good way to check if a
         /// certain message will be accepted by FCM for delivery.</para>
         /// </summary>
+        /// <exception cref="FirebaseMessagingException">If an error occurs while sending the
+        /// messages.</exception>
         /// <param name="message">The message to be sent. Must not be null.</param>
         /// <param name="dryRun">A boolean indicating whether to perform a dry run (validation
         /// only) of the send. If set to true, the message will be sent to the FCM backend service,

FirebaseAdmin/FirebaseAdmin/Messaging/FirebaseMessagingClient.cs

@@ -112,7 +112,7 @@ public async Task<string> SendAsync(
             }
             catch (HttpRequestException e)
             {
-                throw e.ToFirebaseException();
+                throw this.ToFirebaseMessagingException(e);
             }
         }
 
@@ -152,7 +152,7 @@ public async Task<BatchResponse> SendAllAsync(
             }
             catch (HttpRequestException e)
             {
-                throw e.ToFirebaseException();
+                throw this.ToFirebaseMessagingException(e);
             }
         }
 
@@ -193,7 +193,7 @@ private async Task<BatchResponse> SendBatchRequestAsync(
                     SendResponse sendResponse;
                     if (error != null)
                     {
-                        sendResponse = SendResponse.FromException(await this.CreateExceptionFor(message));
+                        sendResponse = SendResponse.FromException(await this.CreateException(message));
                     }
                     else if (content != null)
                     {
@@ -234,7 +234,7 @@ private BatchRequest CreateBatchRequest(
             return batch;
         }
 
-        private async Task<FirebaseMessagingException> CreateExceptionFor(HttpResponseMessage response)
+        private async Task<FirebaseMessagingException> CreateException(HttpResponseMessage response)
         {
             var json = await response.Content.ReadAsStringAsync();
             try
@@ -248,6 +248,17 @@ private async Task<FirebaseMessagingException> CreateExceptionFor(HttpResponseMe
             }
         }
 
+        private FirebaseMessagingException ToFirebaseMessagingException(
+            HttpRequestException exception)
+        {
+            var temp = exception.ToFirebaseException();
+            return new FirebaseMessagingException(
+                temp.ErrorCode,
+                temp.Message,
+                inner: temp.InnerException,
+                response: temp.HttpResponse);
+        }
+
         /// <summary>
         /// Represents the envelope message accepted by the FCM backend service, including the message
         /// payload and other options like <c>validate_only</c>.

FirebaseAdmin/FirebaseAdmin/PlatformErrorHandler.cs

@@ -19,6 +19,13 @@
 
 namespace FirebaseAdmin
 {
+    /// <summary>
+    /// Base class for handling HTTP error responses returned by Google Cloud Platform APIs.
+    /// See <a href="https://cloud.google.com/apis/design/errors">Errors</a> for more details on
+    /// how Google Cloud Platform APIs report back error codes and details. If this class fails
+    /// to determine an error code or message from a given API response, it falls back to the
+    /// error handling logic defined in the parent <see cref="HttpErrorHandler"/> class.
+    /// </summary>
     internal class PlatformErrorHandler : HttpErrorHandler
     {
         private static readonly IReadOnlyDictionary<string, ErrorCode> PlatformErrorCodes =
@@ -31,11 +38,11 @@ internal class PlatformErrorHandler : HttpErrorHandler
                 { "UNAVAILABLE", ErrorCode.Unavailable },
             };
 
-        protected sealed override ErrorInfo ExtractErrorInfo(HttpResponseMessage response, string body)
+        protected sealed override FirebaseExceptionArgs CreateExceptionArgs(HttpResponseMessage response, string body)
         {
             var parsedResponse = this.ParseResponseBody(body);
             var status = parsedResponse.Error?.Status ?? string.Empty;
-            var defaults = base.ExtractErrorInfo(response, body);
+            var defaults = base.CreateExceptionArgs(response, body);
 
             ErrorCode code;
             if (!PlatformErrorCodes.TryGetValue(status, out code))
@@ -49,10 +56,12 @@ protected sealed override ErrorInfo ExtractErrorInfo(HttpResponseMessage respons
                 message = defaults.Message;
             }
 
-            return new ErrorInfo()
+            return new FirebaseExceptionArgs()
             {
                 Code = code,
                 Message = message,
+                HttpResponse = response,
+                ResponseBody = body,
             };
         }