Error handling revamp (v3 release)

CHANGELOG.md

@@ -1,6 +1,9 @@
 # Unreleased
 
--
+- [added] Added the new `firebase_admin.exceptions` module containing the
+  base exception types and global error codes.
+- [changed] Updated the `firebase_admin.instance_id` module to use the new
+  shared exception types. The type `instance_id.ApiCallError` was removed.
 
 # v2.18.0
 

README.md

@@ -36,13 +36,15 @@ pip install firebase-admin
 
 Please refer to the [CONTRIBUTING page](./CONTRIBUTING.md) for more information
 about how you can contribute to this project. We welcome bug reports, feature
-requests, code review feedback, and also pull requests. 
+requests, code review feedback, and also pull requests.
 
 
 ## Supported Python Versions
 
-We support Python 2.7 and Python 3.3+. Firebase Admin Python SDK is also tested
-on PyPy and [Google App Engine](https://cloud.google.com/appengine/) environments.
+We currently support Python 2.7 and Python 3.4+. However, Python 2.7 support is
+being phased out, and the developers are advised to use latest Python 3.
+Firebase Admin Python SDK is also tested on PyPy and
+[Google App Engine](https://cloud.google.com/appengine/) environments.
 
 
 ## Documentation

firebase_admin/_auth_utils.py

@@ -20,6 +20,9 @@
 import six
 from six.moves import urllib
 
+from firebase_admin import exceptions
+from firebase_admin import _utils
+
 
 MAX_CLAIMS_PAYLOAD_SIZE = 1000
 RESERVED_CLAIMS = set([
@@ -188,3 +191,121 @@ def validate_action_type(action_type):
         raise ValueError('Invalid action type provided action_type: {0}. \
             Valid values are {1}'.format(action_type, ', '.join(VALID_EMAIL_ACTION_TYPES)))
     return action_type
+
+
+class UidAlreadyExistsError(exceptions.AlreadyExistsError):
+    """The user with the provided uid already exists."""
+
+    default_message = 'The user with the provided uid already exists'
+
+    def __init__(self, message, cause, http_response):
+        exceptions.AlreadyExistsError.__init__(self, message, cause, http_response)
+
+
+class EmailAlreadyExistsError(exceptions.AlreadyExistsError):
+    """The user with the provided email already exists."""
+
+    default_message = 'The user with the provided email already exists'
+
+    def __init__(self, message, cause, http_response):
+        exceptions.AlreadyExistsError.__init__(self, message, cause, http_response)
+
+
+class InvalidDynamicLinkDomainError(exceptions.InvalidArgumentError):
+    """Dynamic link domain in ActionCodeSettings is not authorized."""
+
+    default_message = 'Dynamic link domain specified in ActionCodeSettings is not authorized'
+
+    def __init__(self, message, cause, http_response):
+        exceptions.InvalidArgumentError.__init__(self, message, cause, http_response)
+
+
+class InvalidIdTokenError(exceptions.InvalidArgumentError):
+    """The provided ID token is not a valid Firebase ID token."""
+
+    default_message = 'The provided ID token is invalid'
+
+    def __init__(self, message, cause=None, http_response=None):
+        exceptions.InvalidArgumentError.__init__(self, message, cause, http_response)
+
+
+class PhoneNumberAlreadyExistsError(exceptions.AlreadyExistsError):
+    """The user with the provided phone number already exists."""
+
+    default_message = 'The user with the provided phone number already exists'
+
+    def __init__(self, message, cause, http_response):
+        exceptions.AlreadyExistsError.__init__(self, message, cause, http_response)
+
+
+class UnexpectedResponseError(exceptions.UnknownError):
+    """Backend service responded with an unexpected or malformed response."""
+
+    def __init__(self, message, cause=None, http_response=None):
+        exceptions.UnknownError.__init__(self, message, cause, http_response)
+
+
+class UserNotFoundError(exceptions.NotFoundError):
+    """No user record found for the specified identifier."""
+
+    default_message = 'No user record found for the given identifier'
+
+    def __init__(self, message, cause=None, http_response=None):
+        exceptions.NotFoundError.__init__(self, message, cause, http_response)
+
+
+_CODE_TO_EXC_TYPE = {
+    'DUPLICATE_EMAIL': EmailAlreadyExistsError,
+    'DUPLICATE_LOCAL_ID': UidAlreadyExistsError,
+    'INVALID_DYNAMIC_LINK_DOMAIN': InvalidDynamicLinkDomainError,
+    'INVALID_ID_TOKEN': InvalidIdTokenError,
+    'PHONE_NUMBER_EXISTS': PhoneNumberAlreadyExistsError,
+    'USER_NOT_FOUND': UserNotFoundError,
+}
+
+
+def handle_auth_backend_error(error):
+    """Converts a requests error received from the Firebase Auth service into a FirebaseError."""
+    if error.response is None:
+        raise _utils.handle_requests_error(error)
+
+    code, custom_message = _parse_error_body(error.response)
+    if not code:
+        msg = 'Unexpected error response: {0}'.format(error.response.content.decode())
+        raise _utils.handle_requests_error(error, message=msg)
+
+    exc_type = _CODE_TO_EXC_TYPE.get(code)
+    msg = _build_error_message(code, exc_type, custom_message)
+    if not exc_type:
+        return _utils.handle_requests_error(error, message=msg)
+
+    return exc_type(msg, cause=error, http_response=error.response)
+
+
+def _parse_error_body(response):
+    """Parses the given error response to extract Auth error code and message."""
+    error_dict = {}
+    try:
+        parsed_body = response.json()
+        if isinstance(parsed_body, dict):
+            error_dict = parsed_body.get('error', {})
+    except ValueError:
+        pass
+
+    # Auth error response format: {"error": {"message": "AUTH_ERROR_CODE: Optional text"}}
+    code = error_dict.get('message') if isinstance(error_dict, dict) else None
+    custom_message = None
+    if code:
+        separator = code.find(':')
+        if separator != -1:
+            custom_message = code[separator + 1:].strip()
+            code = code[:separator]
+
+    return code, custom_message
+
+
+def _build_error_message(code, exc_type, custom_message):
+    default_message = exc_type.default_message if (
+        exc_type and hasattr(exc_type, 'default_message')) else 'Error while calling Auth service'
+    ext = ' {0}'.format(custom_message) if custom_message else ''
+    return '{0} ({1}).{2}'.format(default_message, code, ext)

firebase_admin/_http_client.py

@@ -109,6 +109,10 @@ def headers(self, method, url, **kwargs):
         resp = self.request(method, url, **kwargs)
         return resp.headers
 
+    def body_and_response(self, method, url, **kwargs):
+        resp = self.request(method, url, **kwargs)
+        return self.parse_body(resp), resp
+
     def body(self, method, url, **kwargs):
         resp = self.request(method, url, **kwargs)
         return self.parse_body(resp)

firebase_admin/_messaging_utils.py

@@ -22,6 +22,8 @@
 
 import six
 
+from firebase_admin import exceptions
+
 
 class Message(object):
     """A message that can be sent via Firebase Cloud Messaging.
@@ -921,3 +923,33 @@ def encode_fcm_options(cls, fcm_options):
         }
         result = cls.remove_null_values(result)
         return result
+
+
+class ThirdPartyAuthError(exceptions.UnauthenticatedError):
+    """APNs certificate or web push auth key was invalid or missing."""
+
+    def __init__(self, message, cause=None, http_response=None):
+        exceptions.UnauthenticatedError.__init__(self, message, cause, http_response)
+
+
+class QuotaExceededError(exceptions.ResourceExhaustedError):
+    """Sending limit exceeded for the message target."""
+
+    def __init__(self, message, cause=None, http_response=None):
+        exceptions.ResourceExhaustedError.__init__(self, message, cause, http_response)
+
+
+class SenderIdMismatchError(exceptions.PermissionDeniedError):
+    """The authenticated sender ID is different from the sender ID for the registration token."""
+
+    def __init__(self, message, cause=None, http_response=None):
+        exceptions.PermissionDeniedError.__init__(self, message, cause, http_response)
+
+
+class UnregisteredError(exceptions.NotFoundError):
+    """App instance was unregistered from FCM.
+
+    This usually means that the token used is no longer valid and a new one must be used."""
+
+    def __init__(self, message, cause=None, http_response=None):
+        exceptions.NotFoundError.__init__(self, message, cause, http_response)