Merge pull request #87 from firebase/error-handling-revamp

Introducing the platform-wide error codes

Author: hiranya911

FirebaseAdmin/FirebaseAdmin.Tests/FirebaseAppTest.cs

@@ -13,10 +13,7 @@
 // limitations under the License.
 
 using System;
-using System.Threading.Tasks;
-using FirebaseAdmin;
 using Google.Apis.Auth.OAuth2;
-using Google.Apis.Http;
 using Xunit;
 
 namespace FirebaseAdmin.Tests

FirebaseAdmin/FirebaseAdmin.Tests/FirebaseExceptionTest.cs

@@ -0,0 +1,97 @@
+// Copyright 2019, Google Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System;
+using System.Collections.Generic;
+using System.Net.Http;
+using System.Net.Sockets;
+using Xunit;
+
+namespace FirebaseAdmin.Tests
+{
+    public class FirebaseExceptionTest
+    {
+        [Fact]
+        public void ErrorCodeAndMessage()
+        {
+            var exception = new FirebaseException(ErrorCode.Internal, "Test error message");
+
+            Assert.Equal(ErrorCode.Internal, exception.ErrorCode);
+            Assert.Equal("Test error message", exception.Message);
+            Assert.Null(exception.InnerException);
+        }
+
+        [Fact]
+        public void InnerException()
+        {
+            var inner = new Exception("Inner exception");
+            var exception = new FirebaseException(ErrorCode.Internal, "Test error message", inner);
+
+            Assert.Equal(ErrorCode.Internal, exception.ErrorCode);
+            Assert.Equal("Test error message", exception.Message);
+            Assert.Same(inner, exception.InnerException);
+        }
+
+        [Fact]
+        public void TimeOutError()
+        {
+            var socketError = new SocketException((int)SocketError.TimedOut);
+            var httpError = new HttpRequestException("Test error message", socketError);
+            var exception = httpError.ToFirebaseException();
+
+            Assert.Equal(ErrorCode.DeadlineExceeded, exception.ErrorCode);
+            Assert.Equal(
+                "Timed out while making an API call: Test error message", exception.Message);
+            Assert.Same(httpError, exception.InnerException);
+        }
+
+        [Fact]
+        public void NetworkUnavailableError()
+        {
+            var socketErrorCodes = new List<SocketError>()
+            {
+                SocketError.HostDown,
+                SocketError.HostNotFound,
+                SocketError.HostUnreachable,
+                SocketError.NetworkDown,
+                SocketError.NetworkUnreachable,
+            };
+
+            foreach (var code in socketErrorCodes)
+            {
+                var socketError = new SocketException((int)code);
+                var httpError = new HttpRequestException("Test error message", socketError);
+                var exception = httpError.ToFirebaseException();
+
+                Assert.Equal(ErrorCode.Unavailable, exception.ErrorCode);
+                Assert.Equal(
+                    "Failed to establish a connection: Test error message", exception.Message);
+                Assert.Same(httpError, exception.InnerException);
+            }
+        }
+
+        [Fact]
+        public void UnknownLowLevelError()
+        {
+            var httpError = new HttpRequestException("Test error message");
+            var exception = httpError.ToFirebaseException();
+
+            Assert.Equal(ErrorCode.Unknown, exception.ErrorCode);
+            Assert.Equal(
+                "Unknown error while making a remote service call: Test error message",
+                exception.Message);
+            Assert.Same(httpError, exception.InnerException);
+        }
+    }
+}

FirebaseAdmin/FirebaseAdmin/AppOptions.cs

@@ -12,8 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-using System;
-using System.Collections.Generic;
 using Google.Apis.Auth.OAuth2;
 using Google.Apis.Http;
 

FirebaseAdmin/FirebaseAdmin/ErrorCode.cs

@@ -0,0 +1,108 @@
+// Copyright 2019, Google Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace FirebaseAdmin
+{
+    /// <summary>
+    /// Platform-wide error codes that can be raised by Admin SDK APIs.
+    /// </summary>
+    public enum ErrorCode
+    {
+        /// <summary>
+        /// Client specified an invalid argument.
+        /// </summary>
+        InvalidArgument,
+
+        /// <summary>
+        /// Request can not be executed in the current system state, such as deleting a non-empty
+        /// directory.
+        /// </summary>
+        FailedPrecondition,
+
+        /// <summary>
+        /// Client specified an invalid range.
+        /// </summary>
+        OutOfRange,
+
+        /// <summary>
+        /// Request not authenticated due to missing, invalid, or expired OAuth token.
+        /// </summary>
+        Unauthenticated,
+
+        /// <summary>
+        /// Client does not have sufficient permission. This can happen because the OAuth token
+        /// does not have the right scopes, the client doesn't have permission, or the API has not
+        /// been enabled for the client project.
+        /// </summary>
+        PermissionDenied,
+
+        /// <summary>
+        /// A specified resource is not found, or the request is rejected due to undisclosed
+        /// reasons, such as whitelisting.
+        /// </summary>
+        NotFound,
+
+        /// <summary>
+        /// Concurrency conflict, such as read-modify-write conflict.
+        /// </summary>
+        Conflict,
+
+        /// <summary>
+        /// Concurrency conflict, such as read-modify-write conflict.
+        /// </summary>
+        Aborted,
+
+        /// <summary>
+        /// The resource that a client tried to create already exists.
+        /// </summary>
+        AlreadyExists,
+
+        /// <summary>
+        /// Either out of resource quota or reaching rate limiting.
+        /// </summary>
+        ResourceExhausted,
+
+        /// <summary>
+        /// Request cancelled by the client.
+        /// </summary>
+        Cancelled,
+
+        /// <summary>
+        /// Unrecoverable data loss or data corruption.
+        /// </summary>
+        DataLoss,
+
+        /// <summary>
+        /// Unknown server error.
+        /// </summary>
+        Unknown,
+
+        /// <summary>
+        /// Internal server error.
+        /// </summary>
+        Internal,
+
+        /// <summary>
+        /// Service unavailable. Typically the server is down.
+        /// </summary>
+        Unavailable,
+
+        /// <summary>
+        /// Request deadline exceeded. This will happen only if the caller sets a deadline that is
+        /// shorter than the method's default deadline (i.e. requested deadline is not enough for
+        /// the server to process the request) and the request did not finish within the deadline.
+        /// </summary>
+        DeadlineExceeded,
+    }
+}

FirebaseAdmin/FirebaseAdmin/Extensions.cs

@@ -14,7 +14,9 @@
 
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Net.Http;
+using System.Net.Sockets;
 using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
@@ -30,6 +32,16 @@ namespace FirebaseAdmin
     /// </summary>
     internal static class Extensions
     {
+        private static readonly IReadOnlyList<SocketError> NetworkAvailabilityErrors =
+            new List<SocketError>()
+            {
+                SocketError.HostDown,
+                SocketError.HostNotFound,
+                SocketError.HostUnreachable,
+                SocketError.NetworkDown,
+                SocketError.NetworkUnreachable,
+            };
+
         /// <summary>
         /// Extracts and returns the underlying <see cref="ServiceAccountCredential"/> from a
         /// <see cref="GoogleCredential"/>. Returns null if the <c>GoogleCredential</c> is not
@@ -153,5 +165,27 @@ public static IReadOnlyDictionary<TKey, TValue> Copy<TKey, TValue>(
 
             return copy;
         }
+
+        public static FirebaseException ToFirebaseException(this HttpRequestException exception)
+        {
+            ErrorCode code = ErrorCode.Unknown;
+            string message = "Unknown error while making a remote service call";
+            if (exception.InnerException is SocketException)
+            {
+                var socketException = (SocketException)exception.InnerException;
+                if (socketException.SocketErrorCode == SocketError.TimedOut)
+                {
+                    code = ErrorCode.DeadlineExceeded;
+                    message = "Timed out while making an API call";
+                }
+                else if (NetworkAvailabilityErrors.Contains(socketException.SocketErrorCode))
+                {
+                    code = ErrorCode.Unavailable;
+                    message = "Failed to establish a connection";
+                }
+            }
+
+            return new FirebaseException(code, $"{message}: {exception.Message}", exception);
+        }
     }
 }

FirebaseAdmin/FirebaseAdmin/FirebaseException.cs

@@ -22,9 +22,20 @@ namespace FirebaseAdmin
     public sealed class FirebaseException : Exception
     {
         internal FirebaseException(string message)
-        : base(message) { }
+        : base(message) { } // TODO: Remove this constructor
 
         internal FirebaseException(string message, Exception inner)
-        : base(message, inner) { }
+        : base(message, inner) { } // TODO: Remove this constructor
+
+        internal FirebaseException(ErrorCode code, string message, Exception inner = null)
+        : base(message, inner)
+        {
+            this.ErrorCode = code;
+        }
+
+        /// <summary>
+        /// Gets the platform-wide error code associated with this exception.
+        /// </summary>
+        internal ErrorCode ErrorCode { get; private set; } // TODO: Expose this as public
     }
 }

FirebaseAdmin/FirebaseAdmin/Messaging/FirebaseMessagingClient.cs

@@ -105,6 +105,7 @@ public async Task<string> SendAsync(
                 var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
                 if (!response.IsSuccessStatusCode)
                 {
+                    // TODO(hkj): Handle error responses.
                     var error = "Response status code does not indicate success: "
                             + $"{(int)response.StatusCode} ({response.StatusCode})"
                             + $"{Environment.NewLine}{json}";
@@ -116,7 +117,7 @@ public async Task<string> SendAsync(
             }
             catch (HttpRequestException e)
             {
-                throw new FirebaseException("Error while calling the FCM service.", e);
+                throw e.ToFirebaseException();
             }
         }