Low Level ETag API (#59)

* New functionality for handling transactions.

* Changes to transaction function, and other minor fixes.

* Refactored existing code, and added integration tests.

* Added integration test and minor fixes.

* A few minor changes.

* Added lower level functionality for accessing ETag.

* Refactored methods.

* A few small fixes.

* Preliminary changes to API.

* Changes to get_if_changed function.

* Removed etag method.

Author: Alexander Whatley

firebase_admin/db.py

@@ -125,31 +125,58 @@ def child(self, path):
         full_path = self._pathurl + '/' + path
         return Reference(client=self._client, path=full_path)
 
-    def get(self):
-        """Returns the value at the current location of the database.
+    def get(self, etag=False):
+        """Returns the value, and possibly the ETag, at the current location of the database.
 
         Returns:
-          object: Decoded JSON value of the current database Reference.
+          object: Decoded JSON value of the current database Reference if etag=False, otherwise
+              the decoded JSON value and the corresponding ETag.
 
         Raises:
           ApiCallError: If an error occurs while communicating with the remote database server.
         """
-        return self._client.request('get', self._add_suffix())
+        if etag:
+            data, headers = self._client.request('get', self._add_suffix(),
+                                                 headers={'X-Firebase-ETag' : 'true'},
+                                                 resp_headers=True)
+            etag = headers.get('ETag')
+            return data, etag
+        else:
+            return self._client.request('get', self._add_suffix())
+
+    def get_if_changed(self, etag):
+        """Get data in this location if the ETag no longer matches.
+
+        Args:
+          etag: The ETag value we want to check against the ETag in the current location.
+
+        Returns:
+          object: Tuple of boolean of whether the request was successful, current location's etag,
+           and snapshot of location's data if passed in etag does not match.
+
+        Raises:
+          ValueError: If the ETag is not a string.
+        """
+        #pylint: disable=protected-access
+        if not isinstance(etag, six.string_types):
+            raise ValueError('ETag must be a string.')
 
-    def _get_with_etag(self):
-        """Returns the value at the current location of the database, along with its ETag."""
-        data, headers = self._client.request(
-            'get', self._add_suffix(), headers={'X-Firebase-ETag' : 'true'}, resp_headers=True)
-        etag = headers.get('ETag')
-        return etag, data
+        resp = self._client._do_request('get', self._add_suffix(),
+                                        headers={'if-none-match': etag})
+        if resp.status_code == 200:
+            value, headers = resp.json(), resp.headers
+            new_etag = headers.get('ETag')
+            return True, new_etag, value
+        elif resp.status_code == 304:
+            return False, None, None
 
     def set(self, value):
         """Sets the data at this location to the given value.
 
         The value must be JSON-serializable and not None.
 
         Args:
-          value: JSON-serialable value to be set at this location.
+          value: JSON-serializable value to be set at this location.
 
         Raises:
           ValueError: If the value is None.
@@ -160,6 +187,41 @@ def set(self, value):
             raise ValueError('Value must not be None.')
         self._client.request_oneway('put', self._add_suffix(), json=value, params='print=silent')
 
+    def set_if_unchanged(self, expected_etag, value):
+        """Sets the data at this location to the given value, if expected_etag is the same as the
+        correct ETag value.
+
+        Args:
+          expected_etag: Value of ETag we want to check.
+          value: JSON-serializable value to be set at this location.
+
+        Returns:
+          object: Tuple of boolean of whether the request was successful, current location's etag,
+           and snapshot of location's data if passed in etag does not match.
+
+        Raises:
+          ValueError: If the value is None, or if expected_etag is not a string.
+          ApiCallError: If an error occurs while communicating with the remote database server.
+        """
+        # pylint: disable=missing-raises-doc
+        if not isinstance(expected_etag, six.string_types):
+            raise ValueError('Expected ETag must be a string.')
+        if value is None:
+            raise ValueError('Value must not be none.')
+
+        try:
+            self._client.request_oneway('put', self._add_suffix(),
+                                        json=value, headers={'if-match': expected_etag})
+            return True, expected_etag, value
+        except ApiCallError as error:
+            detail = error.detail
+            if detail.response is not None and 'ETag' in detail.response.headers:
+                etag = detail.response.headers['ETag']
+                snapshot = detail.response.json()
+                return False, etag, snapshot
+            else:
+                raise error
+
     def push(self, value=''):
         """Creates a new child node.
 
@@ -197,25 +259,8 @@ def update(self, value):
             raise ValueError('Value argument must be a non-empty dictionary.')
         if None in value.keys() or None in value.values():
             raise ValueError('Dictionary must not contain None keys or values.')
-        self._client.request_oneway('patch', self._add_suffix(), json=value, params='print=silent')
-
-    def _update_with_etag(self, value, etag):
-        """Sets the data at this location to the specified value, if the etag matches."""
-        if not isinstance(etag, six.string_types):
-            raise ValueError('ETag must be a string.')
-
-        try:
-            self._client.request_oneway(
-                'put', self._add_suffix(), json=value, headers={'if-match': etag})
-            return True, etag, value
-        except ApiCallError as error:
-            detail = error.detail
-            if detail.response is not None and 'ETag' in detail.response.headers:
-                etag = detail.response.headers['ETag']
-                snapshot = detail.response.json()
-                return False, etag, snapshot
-            else:
-                raise error
+        self._client.request_oneway('patch', self._add_suffix(), json=value,
+                                    params='print=silent')
 
     def delete(self):
         """Deletes this node from the database.
@@ -253,16 +298,15 @@ def transaction(self, transaction_update):
         Raises:
             TransactionError: If the transaction aborts after exhausting all retry attempts.
             ValueError: If transaction_update is not a function.
-
         """
         if not callable(transaction_update):
             raise ValueError('transaction_update must be a function.')
 
         tries = 0
-        etag, data = self._get_with_etag()
+        data, etag = self.get(etag=True)
         while tries < _TRANSACTION_MAX_RETRIES:
             new_data = transaction_update(data)
-            success, etag, data = self._update_with_etag(new_data, etag)
+            success, etag, data = self.set_if_unchanged(etag, new_data)
             if success:
                 return new_data
             tries += 1
@@ -480,14 +524,14 @@ def __init__(self, message, error):
         Exception.__init__(self, message)
         self.detail = error
 
-
 class TransactionError(Exception):
     """Represents an Exception encountered while performing a transaction."""
 
     def __init__(self, message):
         Exception.__init__(self, message)
 
 
+
 class _Sorter(object):
     """Helper class for sorting query results."""
 
@@ -674,8 +718,11 @@ def from_app(cls, app):
 
     def request(self, method, urlpath, **kwargs):
         resp_headers = kwargs.pop('resp_headers', False)
+        params = kwargs.get('params', None)
         resp = self._do_request(method, urlpath, **kwargs)
-        if resp_headers:
+        if resp_headers and params == 'print=silent':
+            return resp.headers
+        elif resp_headers:
             return resp.json(), resp.headers
         else:
             return resp.json()

integration/test_db.py

@@ -150,23 +150,34 @@ def test_update_nested_children(self, testref):
         assert edward.get() == {'name' : 'Edward Cope', 'since' : 1840}
         assert jack.get() == {'name' : 'Jack Horner', 'since' : 1946}
 
-    def test_get_and_update_with_etag(self, testref):
+    def test_get_if_changed(self, testref):
         python = testref.parent
         push_data = {'name' : 'Edward Cope', 'since' : 1800}
         edward = python.child('users').push(push_data)
-        etag, data = edward._get_with_etag()
+        changed_data = edward.get_if_changed('wrong_etag')
+        assert changed_data[0]
+        assert changed_data[2] == push_data
+
+        unchanged_data = edward.get_if_changed(changed_data[1])
+        assert unchanged_data == (False, None, None)
+
+    def test_get_and_set_with_etag(self, testref):
+        python = testref.parent
+        push_data = {'name' : 'Edward Cope', 'since' : 1800}
+        edward = python.child('users').push(push_data)
+        data, etag = edward.get(etag=True)
         assert data == push_data
         assert isinstance(etag, six.string_types)
 
         update_data = {'name' : 'Jack Horner', 'since' : 1940}
-        failed_update = edward._update_with_etag(update_data, 'invalid-etag')
+        failed_update = edward.set_if_unchanged('invalid-etag', update_data)
         assert failed_update == (False, etag, push_data)
 
-        successful_update = edward._update_with_etag(update_data, etag)
+        successful_update = edward.set_if_unchanged(etag, update_data)
         assert successful_update[0]
         assert successful_update[2] == update_data
 
-    def test_transation(self, testref):
+    def test_transaction(self, testref):
         python = testref.parent
         def transaction_update(snapshot):
             snapshot['name'] += ' Owen'

tests/test_db.py

@@ -34,13 +34,17 @@ def __init__(self, data, status, recorder):
 
     def send(self, request, **kwargs):
         if_match = request.headers.get('if-match')
+        if_none_match = request.headers.get('if-none-match')
         if if_match and if_match != MockAdapter._ETAG:
             response = Response()
             response._content = request.body
             response.headers = {'ETag': MockAdapter._ETAG}
             raise exceptions.RequestException(response=response)
+
         resp = super(MockAdapter, self).send(request, **kwargs)
         resp.headers = {'ETag': MockAdapter._ETAG}
+        if if_none_match and if_none_match == MockAdapter._ETAG:
+            resp.status_code = 304
         return resp
 
 
@@ -146,13 +150,28 @@ def test_get_value(self, data):
     def test_get_with_etag(self, data):
         ref = db.reference('/test')
         recorder = self.instrument(ref, json.dumps(data))
-        assert ref._get_with_etag() == ('0', data)
+        assert ref.get(etag=True) == (data, '0')
         assert len(recorder) == 1
         assert recorder[0].method == 'GET'
         assert recorder[0].url == 'https://test.firebaseio.com/test.json'
         assert recorder[0].headers['Authorization'] == 'Bearer mock-token'
         assert recorder[0].headers['User-Agent'] == db._USER_AGENT
 
+    @pytest.mark.parametrize('data', valid_values)
+    def test_get_if_changed(self, data):
+        ref = db.reference('/test')
+        recorder = self.instrument(ref, json.dumps(data))
+
+        assert ref.get_if_changed('1') == (True, '0', data)
+        assert len(recorder) == 1
+        assert recorder[0].method == 'GET'
+        assert recorder[0].url == 'https://test.firebaseio.com/test.json'
+
+        assert ref.get_if_changed('0') == (False, None, None)
+        assert len(recorder) == 2
+        assert recorder[0].method == 'GET'
+        assert recorder[0].url == 'https://test.firebaseio.com/test.json'
+
     @pytest.mark.parametrize('data', valid_values)
     def test_order_by_query(self, data):
         ref = db.reference('/test')
@@ -229,19 +248,19 @@ def test_update_children(self):
         assert json.loads(recorder[0].body.decode()) == data
         assert recorder[0].headers['Authorization'] == 'Bearer mock-token'
 
-    def test_update_with_etag(self):
+    def test_set_with_etag(self):
         ref = db.reference('/test')
         data = {'foo': 'bar'}
         recorder = self.instrument(ref, json.dumps(data))
-        vals = ref._update_with_etag(data, '0')
+        vals = ref.set_if_unchanged('0', data)
         assert vals == (True, '0', data)
         assert len(recorder) == 1
         assert recorder[0].method == 'PUT'
         assert recorder[0].url == 'https://test.firebaseio.com/test.json'
         assert json.loads(recorder[0].body.decode()) == data
         assert recorder[0].headers['Authorization'] == 'Bearer mock-token'
 
-        vals = ref._update_with_etag(data, '1')
+        vals = ref.set_if_unchanged('1', data)
         assert vals == (False, '0', data)
         assert len(recorder) == 1