Add option to set If-Match eTag for objects write requests

Author: seba-aln

examples/native_sync/using_etag.py

@@ -0,0 +1,55 @@
+import os
+
+from copy import deepcopy
+from pubnub.pubnub import PubNub
+from pubnub.pnconfiguration import PNConfiguration
+from pubnub.exceptions import PubNubException
+
+config = PNConfiguration()
+config.publish_key = os.getenv('PUBLISH_KEY', default='demo')
+config.subscribe_key = os.getenv('SUBSCRIBE_KEY', default='demo')
+config.user_id = "example"
+
+config_2 = deepcopy(config)
+config_2.user_id = "example_2"
+
+pubnub = PubNub(config)
+pubnub_2 = PubNub(config_2)
+
+sample_user = {
+    "uuid": "SampleUser",
+    "name": "John Doe",
+    "email": "[email protected]",
+    "custom": {"age": 42, "address": "123 Main St."},
+}
+
+set_result = pubnub.set_uuid_metadata(
+    **sample_user,
+    include_custom=True,
+    include_status=True,
+    include_type=True
+).sync()
+
+e_tag = set_result.result.data.get('eTag')
+
+overwrite_result = pubnub_2.set_uuid_metadata(uuid="SampleUser", name="Jane Doe").sync()
+new_e_tag = overwrite_result.result.data.get('eTag')
+
+# We get false because user is updated after it was read.
+print(f"{e_tag == new_e_tag=}")
+
+# We modify the user and try to update it.
+updated_user = {**sample_user, "custom": {"age": 43, "address": "321 Other St."}}
+
+
+try:
+    update_result = pubnub.set_uuid_metadata(
+        **updated_user,
+        include_custom=True,
+        include_status=True,
+        include_type=True
+    ).if_matches_etag(e_tag).sync()
+except PubNubException as e:
+    # We get an exception and after reading the error message we can see that the reason is that the eTag is outdated.
+    print(f"Update failed: {e.get_error_message().get('message')}")
+

pubnub/endpoints/endpoint.py

@@ -25,6 +25,7 @@ class Endpoint(object):
 
     __metaclass__ = ABCMeta
     _path = None
+    _custom_headers: dict = None
 
     def __init__(self, pubnub):
         self.pubnub = pubnub
@@ -100,6 +101,9 @@ def request_headers(self):
         if self.http_method() in [HttpMethod.POST, HttpMethod.PATCH]:
             headers["Content-type"] = "application/json"
 
+        if self._custom_headers:
+            headers.update(self._custom_headers)
+
         return headers
 
     def build_file_upload_request(self):

pubnub/endpoints/objects_v2/objects_endpoint.py

@@ -17,6 +17,10 @@ class ObjectsEndpoint(Endpoint):
 
     _includes: PNIncludes = None
 
+    __if_matches_etag: str = None
+
+    _custom_headers: dict = {}
+
     def __init__(self, pubnub):
         Endpoint.__init__(self, pubnub)
 
@@ -36,6 +40,11 @@ def validate_params(self):
     def validate_specific_params(self):
         pass
 
+    def if_matches_etag(self, etag: str):
+        self.__if_matches_etag = etag
+        self._custom_headers.update({"If-Match": etag})
+        return self
+
     def encoded_params(self):
         params = {}
         if isinstance(self, ListEndpoint):

pubnub/exceptions.py

@@ -1,3 +1,6 @@
+from json import loads, JSONDecodeError
+
+
 class PubNubException(Exception):
     def __init__(self, errormsg="", status_code=0, pn_error=None, status=None):
         self._errormsg = errormsg
@@ -19,6 +22,16 @@ def _status(self):
         raise DeprecationWarning
         return self.status
 
+    def get_status_code(self):
+        return self._status_code
+
+    def get_error_message(self):
+        try:
+            error = loads(self._errormsg)
+            return error.get('error')
+        except JSONDecodeError:
+            return self._errormsg
+
 
 class PubNubAsyncioException(Exception):
     def __init__(self, result, status):