Implemented IID delete API (#95)

hiranya911 · web-flow · commit 3b6b6137a83b · 2017-12-20T11:10:29.000-08:00
* Implemented IID delete API

* Implemented better error handling

* Improved error handling

* Resolved TODO regarding backend errors

* Fixing typo

* Improved error handling

* Updated error message format
diff --git a/firebase_admin/instance_id.py b/firebase_admin/instance_id.py
@@ -0,0 +1,106 @@
+# Copyright 2017 Google Inc.
+#
+# 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.
+
+"""Firebase Instance ID module.
+
+This module enables deleting instance IDs associated with Firebase projects.
+"""
+
+import requests
+import six
+
+from firebase_admin import _http_client
+from firebase_admin import _utils
+
+
+_IID_SERVICE_URL = 'https://console.firebase.google.com/v1/'
+_IID_ATTRIBUTE = '_iid'
+
+
+def _get_iid_service(app):
+    return _utils.get_app_service(app, _IID_ATTRIBUTE, _InstanceIdService)
+
+
+def delete_instance_id(instance_id, app=None):
+    """Deletes the specified instance ID from Firebase.
+
+    This can be used to delete an instance ID and associated user data from a Firebase project,
+    pursuant to the General Data Protection Regulation (GDPR).
+
+    Args:
+      instance_id: A non-empty instance ID string.
+      app: An App instance (optional).
+
+    Raises:
+      InstanceIdError: If an error occurs while invoking the backend instance ID service.
+      ValueError: If the specified instance ID or app is invalid.
+    """
+    _get_iid_service(app).delete_instance_id(instance_id)
+
+
+class ApiCallError(Exception):
+    """Represents an Exception encountered while invoking the Firebase instance ID service."""
+
+    def __init__(self, message, error):
+        Exception.__init__(self, message)
+        self.detail = error
+
+
+class _InstanceIdService(object):
+    """Provides methods for interacting with the remote instance ID service."""
+
+    error_codes = {
+        400: 'Malformed instance ID argument.',
+        401: 'Request not authorized.',
+        403: 'Project does not match instance ID or the client does not have '
+             'sufficient privileges.',
+        404: 'Failed to find the instance ID.',
+        409: 'Already deleted.',
+        429: 'Request throttled out by the backend server.',
+        500: 'Internal server error.',
+        503: 'Backend servers are over capacity. Try again later.'
+    }
+
+    def __init__(self, app):
+        project_id = app.project_id
+        if not project_id:
+            raise ValueError(
+                'Project ID is required to access Instance ID service. Either set the projectId '
+                'option, or use service account credentials. Alternatively, set the '
+                'GCLOUD_PROJECT environment variable.')
+        elif not isinstance(project_id, six.string_types):
+            raise ValueError(
+                'Invalid project ID: "{0}". project ID must be a string.'.format(project_id))
+        self._project_id = project_id
+        self._client = _http_client.JsonHttpClient(
+            credential=app.credential.get_credential(), base_url=_IID_SERVICE_URL)
+
+    def delete_instance_id(self, instance_id):
+        if not isinstance(instance_id, six.string_types) or not instance_id:
+            raise ValueError('Instance ID must be a non-empty string.')
+        path = 'project/{0}/instanceId/{1}'.format(self._project_id, instance_id)
+        try:
+            self._client.request('delete', path)
+        except requests.exceptions.RequestException as error:
+            raise ApiCallError(self._extract_message(instance_id, error), error)
+
+    def _extract_message(self, instance_id, error):
+        if error.response is None:
+            return str(error)
+        status = error.response.status_code
+        msg = self.error_codes.get(status)
+        if msg:
+            return 'Instance ID "{0}": {1}'.format(instance_id, msg)
+        else:
+            return str(error)
diff --git a/integration/test_instance_id.py b/integration/test_instance_id.py
@@ -0,0 +1,24 @@
+# Copyright 2017 Google Inc.
+#
+# 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.
+
+"""Integration tests for firebase_admin.instance_id module."""
+
+import pytest
+
+from firebase_admin import instance_id
+
+def test_delete_non_existing():
+    with pytest.raises(instance_id.ApiCallError) as excinfo:
+        instance_id.delete_instance_id('non-existing')
+    assert str(excinfo.value) == 'Instance ID "non-existing": Failed to find the instance ID.'
diff --git a/tests/test_instance_id.py b/tests/test_instance_id.py
@@ -0,0 +1,114 @@
+# Copyright 2017 Google Inc.
+#
+# 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.
+
+"""Tests for firebase_admin.instance_id."""
+
+import os
+
+import pytest
+
+import firebase_admin
+from firebase_admin import instance_id
+from tests import testutils
+
+
+http_errors = {
+    404: 'Instance ID "test_iid": Failed to find the instance ID.',
+    409: 'Instance ID "test_iid": Already deleted.',
+    429: 'Instance ID "test_iid": Request throttled out by the backend server.',
+    500: 'Instance ID "test_iid": Internal server error.',
+}
+
+class TestDeleteInstanceId(object):
+
+    def teardown_method(self):
+        testutils.cleanup_apps()
+
+    def _instrument_iid_service(self, app, status=200, payload='True'):
+        iid_service = instance_id._get_iid_service(app)
+        recorder = []
+        iid_service._client.session.mount(
+            instance_id._IID_SERVICE_URL,
+            testutils.MockAdapter(payload, status, recorder))
+        return iid_service, recorder
+
+    def _get_url(self, project_id, iid):
+        return instance_id._IID_SERVICE_URL + 'project/{0}/instanceId/{1}'.format(project_id, iid)
+
+    def test_no_project_id(self):
+        env_var = 'GCLOUD_PROJECT'
+        gcloud_project = os.environ.get(env_var)
+        if gcloud_project:
+            del os.environ[env_var]
+        try:
+            firebase_admin.initialize_app(testutils.MockCredential())
+            with pytest.raises(ValueError):
+                instance_id.delete_instance_id('test')
+        finally:
+            if gcloud_project:
+                os.environ[env_var] = gcloud_project
+
+    def test_delete_instance_id(self):
+        cred = testutils.MockCredential()
+        app = firebase_admin.initialize_app(cred, {'projectId': 'explicit-project-id'})
+        _, recorder = self._instrument_iid_service(app)
+        instance_id.delete_instance_id('test_iid')
+        assert len(recorder) == 1
+        assert recorder[0].method == 'DELETE'
+        assert recorder[0].url == self._get_url('explicit-project-id', 'test_iid')
+
+    def test_delete_instance_id_with_explicit_app(self):
+        cred = testutils.MockCredential()
+        app = firebase_admin.initialize_app(cred, {'projectId': 'explicit-project-id'})
+        _, recorder = self._instrument_iid_service(app)
+        instance_id.delete_instance_id('test_iid', app)
+        assert len(recorder) == 1
+        assert recorder[0].method == 'DELETE'
+        assert recorder[0].url == self._get_url('explicit-project-id', 'test_iid')
+
+    @pytest.mark.parametrize('status', http_errors.keys())
+    def test_delete_instance_id_error(self, status):
+        cred = testutils.MockCredential()
+        app = firebase_admin.initialize_app(cred, {'projectId': 'explicit-project-id'})
+        _, recorder = self._instrument_iid_service(app, status, 'some error')
+        with pytest.raises(instance_id.ApiCallError) as excinfo:
+            instance_id.delete_instance_id('test_iid')
+        assert str(excinfo.value) == http_errors.get(status)
+        assert excinfo.value.detail is not None
+        assert len(recorder) == 1
+        assert recorder[0].method == 'DELETE'
+        assert recorder[0].url == self._get_url('explicit-project-id', 'test_iid')
+
+    def test_delete_instance_id_unexpected_error(self):
+        cred = testutils.MockCredential()
+        app = firebase_admin.initialize_app(cred, {'projectId': 'explicit-project-id'})
+        _, recorder = self._instrument_iid_service(app, 501, 'some error')
+        with pytest.raises(instance_id.ApiCallError) as excinfo:
+            instance_id.delete_instance_id('test_iid')
+        url = self._get_url('explicit-project-id', 'test_iid')
+        message = '501 Server Error: None for url: {0}'.format(url)
+        assert str(excinfo.value) == message
+        assert excinfo.value.detail is not None
+        assert len(recorder) == 1
+        assert recorder[0].method == 'DELETE'
+        assert recorder[0].url == url
+
+    @pytest.mark.parametrize('iid', [None, '', 0, 1, True, False, list(), dict(), tuple()])
+    def test_invalid_instance_id(self, iid):
+        cred = testutils.MockCredential()
+        app = firebase_admin.initialize_app(cred, {'projectId': 'explicit-project-id'})
+        _, recorder = self._instrument_iid_service(app)
+        with pytest.raises(ValueError):
+            instance_id.delete_instance_id(iid)
+        assert len(recorder) is 0
