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

examples/native_sync/using_etag.py

@@ -0,0 +1,60 @@
+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."},
+}
+
+# One client creates a metada for the user "SampleUser" and successfully writes it to the server.
+set_result = pubnub.set_uuid_metadata(
+    **sample_user,
+    include_custom=True,
+    include_status=True,
+    include_type=True
+).sync()
+
+# We store the eTag for the user for further updates.
+original_e_tag = set_result.result.data.get('eTag')
+
+# Another client sets the user meta with the same UUID but different data.
+overwrite_result = pubnub_2.set_uuid_metadata(uuid="SampleUser", name="Jane Doe").sync()
+new_e_tag = overwrite_result.result.data.get('eTag')
+
+# We can verify that there is a new eTag for the user.
+print(f"{original_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(original_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')}\nHTTP Status Code: {e.get_status_code()}")
+
+
+except Exception as e:
+    print(f"Unexpected error: {e}")

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):

pubnub/pubnub_core.py

@@ -288,9 +288,9 @@ def set_uuid_metadata(self, uuid: str = None, include_custom: bool = None, custo
                        include_type=include_type, status=status, type=type, name=name, email=email,
                        external_id=external_id, profile_url=profile_url)
 
-    def get_uuid_metadata(self, uuud: str = None, include_custom: bool = None, include_status: bool = True,
+    def get_uuid_metadata(self, uuid: str = None, include_custom: bool = None, include_status: bool = True,
                           include_type: bool = True) -> GetUuid:
-        return GetUuid(self, uuid=uuud, include_custom=include_custom, include_status=include_status,
+        return GetUuid(self, uuid=uuid, include_custom=include_custom, include_status=include_status,
                        include_type=include_type)
 
     def remove_uuid_metadata(self, uuid: str = None) -> RemoveUuid:

tests/integrational/asyncio/objects_v2/test_channel.py

@@ -0,0 +1,215 @@
+import pytest
+from pubnub.endpoints.endpoint import Endpoint
+from pubnub.endpoints.objects_v2.channel.get_all_channels import GetAllChannels
+from pubnub.endpoints.objects_v2.channel.get_channel import GetChannel
+from pubnub.endpoints.objects_v2.channel.remove_channel import RemoveChannel
+from pubnub.endpoints.objects_v2.channel.set_channel import SetChannel
+from pubnub.exceptions import PubNubException
+from pubnub.models.consumer.common import PNStatus
+from pubnub.models.consumer.objects_v2.channel import PNSetChannelMetadataResult, PNGetChannelMetadataResult, \
+    PNRemoveChannelMetadataResult, PNGetAllChannelMetadataResult
+from pubnub.models.consumer.objects_v2.sort import PNSortKey, PNSortKeyValue
+from pubnub.pubnub_asyncio import PubNubAsyncio
+from pubnub.models.envelopes import AsyncioEnvelope
+from tests.helper import pnconf_env_copy
+from tests.integrational.vcr_helper import pn_vcr
+
+
+def _pubnub():
+    config = pnconf_env_copy()
+    return PubNubAsyncio(config)
+
+
+class TestObjectsV2Channel:
+    _some_channel_id = "somechannelid"
+    _some_name = "Some name"
+    _some_description = "Some description"
+    _some_custom = {
+        "key1": "val1",
+        "key2": "val2"
+    }
+
+    def test_set_channel_endpoint_available(self):
+        pn = _pubnub()
+        set_channel = pn.set_channel_metadata()
+        assert set_channel is not None
+        assert isinstance(set_channel, SetChannel)
+        assert isinstance(set_channel, Endpoint)
+
+    def test_set_channel_is_endpoint(self):
+        pn = _pubnub()
+        set_channel = pn.set_channel_metadata()
+        assert isinstance(set_channel, SetChannel)
+        assert isinstance(set_channel, Endpoint)
+
+    @pn_vcr.use_cassette('tests/integrational/fixtures/asyncio/objects_v2/channel/set_channel.json',
+                         filter_query_parameters=['uuid', 'pnsdk', 'l_obj'], serializer='pn_json')
+    @pytest.mark.asyncio
+    async def test_set_channel_happy_path(self):
+        pn = _pubnub()
+
+        set_channel_result = await pn.set_channel_metadata() \
+            .include_custom(True) \
+            .channel(TestObjectsV2Channel._some_channel_id) \
+            .set_name(TestObjectsV2Channel._some_name) \
+            .description(TestObjectsV2Channel._some_description) \
+            .custom(TestObjectsV2Channel._some_custom) \
+            .future()
+
+        assert isinstance(set_channel_result, AsyncioEnvelope)
+        assert isinstance(set_channel_result.result, PNSetChannelMetadataResult)
+        assert isinstance(set_channel_result.status, PNStatus)
+        assert not set_channel_result.status.is_error()
+        data = set_channel_result.result.data
+        assert data['id'] == TestObjectsV2Channel._some_channel_id
+        assert data['name'] == TestObjectsV2Channel._some_name
+        assert data['description'] == TestObjectsV2Channel._some_description
+        assert data['custom'] == TestObjectsV2Channel._some_custom
+
+    def test_get_channel_endpoint_available(self):
+        pn = _pubnub()
+        get_channel = pn.get_channel_metadata()
+        assert get_channel is not None
+        assert isinstance(get_channel, GetChannel)
+        assert isinstance(get_channel, Endpoint)
+
+    def test_get_channel_is_endpoint(self):
+        pn = _pubnub()
+        get_channel = pn.get_channel_metadata()
+        assert isinstance(get_channel, GetChannel)
+        assert isinstance(get_channel, Endpoint)
+
+    @pn_vcr.use_cassette('tests/integrational/fixtures/asyncio/objects_v2/channel/get_channel.json',
+                         filter_query_parameters=['uuid', 'pnsdk', 'l_obj'], serializer='pn_json')
+    @pytest.mark.asyncio
+    async def test_get_channel_happy_path(self):
+        pn = _pubnub()
+
+        get_channel_result = await pn.get_channel_metadata() \
+            .include_custom(True) \
+            .channel(TestObjectsV2Channel._some_channel_id) \
+            .future()
+
+        assert isinstance(get_channel_result, AsyncioEnvelope)
+        assert isinstance(get_channel_result.result, PNGetChannelMetadataResult)
+        assert isinstance(get_channel_result.status, PNStatus)
+        assert not get_channel_result.status.is_error()
+        data = get_channel_result.result.data
+        assert data['id'] == TestObjectsV2Channel._some_channel_id
+        assert data['name'] == TestObjectsV2Channel._some_name
+        assert data['description'] == TestObjectsV2Channel._some_description
+        assert data['custom'] == TestObjectsV2Channel._some_custom
+
+    def test_remove_channel_endpoint_available(self):
+        pn = _pubnub()
+        remove_channel = pn.remove_channel_metadata()
+        assert remove_channel is not None
+        assert isinstance(remove_channel, RemoveChannel)
+        assert isinstance(remove_channel, Endpoint)
+
+    def test_remove_channel_is_endpoint(self):
+        pn = _pubnub()
+        remove_channel = pn.remove_channel_metadata()
+        assert isinstance(remove_channel, RemoveChannel)
+        assert isinstance(remove_channel, Endpoint)
+
+    @pn_vcr.use_cassette('tests/integrational/fixtures/asyncio/objects_v2/channel/remove_channel.json',
+                         filter_query_parameters=['uuid', 'pnsdk', 'l_obj'], serializer='pn_json')
+    @pytest.mark.asyncio
+    async def test_remove_channel_happy_path(self):
+        pn = _pubnub()
+
+        remove_uid_result = await pn.remove_channel_metadata() \
+            .channel(TestObjectsV2Channel._some_channel_id) \
+            .future()
+
+        assert isinstance(remove_uid_result, AsyncioEnvelope)
+        assert isinstance(remove_uid_result.result, PNRemoveChannelMetadataResult)
+        assert isinstance(remove_uid_result.status, PNStatus)
+        assert not remove_uid_result.status.is_error()
+
+    def test_get_all_channel_endpoint_available(self):
+        pn = _pubnub()
+        get_all_channel = pn.get_all_channel_metadata()
+        assert get_all_channel is not None
+        assert isinstance(get_all_channel, GetAllChannels)
+        assert isinstance(get_all_channel, Endpoint)
+
+    def test_get_all_channel_is_endpoint(self):
+        pn = _pubnub()
+        get_all_channel = pn.get_all_channel_metadata()
+        assert isinstance(get_all_channel, GetAllChannels)
+        assert isinstance(get_all_channel, Endpoint)
+
+    @pn_vcr.use_cassette('tests/integrational/fixtures/asyncio/objects_v2/channel/get_all_channel.json',
+                         filter_query_parameters=['uuid', 'pnsdk', 'l_obj'], serializer='pn_json')
+    @pytest.mark.asyncio
+    async def test_get_all_channel_happy_path(self):
+        pn = _pubnub()
+
+        await pn.set_channel_metadata() \
+            .include_custom(True) \
+            .channel(TestObjectsV2Channel._some_channel_id) \
+            .set_name(TestObjectsV2Channel._some_name) \
+            .description(TestObjectsV2Channel._some_description) \
+            .custom(TestObjectsV2Channel._some_custom) \
+            .future()
+
+        get_all_channel_result = await pn.get_all_channel_metadata() \
+            .include_custom(True) \
+            .limit(10) \
+            .include_total_count(True) \
+            .sort(PNSortKey.asc(PNSortKeyValue.ID), PNSortKey.desc(PNSortKeyValue.UPDATED)) \
+            .page(None) \
+            .future()
+
+        assert isinstance(get_all_channel_result, AsyncioEnvelope)
+        assert isinstance(get_all_channel_result.result, PNGetAllChannelMetadataResult)
+        assert isinstance(get_all_channel_result.status, PNStatus)
+        assert not get_all_channel_result.status.is_error()
+        data = get_all_channel_result.result.data
+        assert isinstance(data, list)
+        assert get_all_channel_result.result.total_count != 0
+        assert get_all_channel_result.result.next is not None
+        assert get_all_channel_result.result.prev is None
+
+    @pn_vcr.use_cassette('tests/integrational/fixtures/asyncio/objects_v2/channel/if_matches_etag.json',
+                         filter_query_parameters=['uuid', 'pnsdk', 'l_obj'], serializer='pn_json')
+    @pytest.mark.asyncio
+    async def test_if_matches_etag(self):
+        pubnub = _pubnub()
+
+        set_channel = await pubnub.set_channel_metadata(channel=self._some_channel_id, name=self._some_name).future()
+        original_etag = set_channel.result.data.get('eTag')
+        get_channel = await pubnub.get_channel_metadata(channel=self._some_channel_id).future()
+        assert original_etag == get_channel.result.data.get('eTag')
+
+        # Update without eTag should be possible
+        set_channel = await pubnub.set_channel_metadata(channel=self._some_channel_id, name=f"{self._some_name}-2") \
+            .future()
+
+        # Response should contain new eTag
+        new_etag = set_channel.result.data.get('eTag')
+        assert original_etag != new_etag
+        assert set_channel.result.data.get('name') == f"{self._some_name}-2"
+
+        get_channel = await pubnub.get_channel_metadata(channel=self._some_channel_id).future()
+        assert original_etag != get_channel.result.data.get('eTag')
+        assert get_channel.result.data.get('name') == f"{self._some_name}-2"
+
+        # Update with correct eTag should be possible
+        set_channel = await pubnub.set_channel_metadata(channel=self._some_channel_id, name=f"{self._some_name}-3") \
+            .if_matches_etag(new_etag) \
+            .future()
+        assert set_channel.result.data.get('name') == f"{self._some_name}-3"
+
+        try:
+            # Update with original - now outdated - eTag should fail
+            set_channel = await pubnub.set_channel_metadata(
+                channel=self._some_channel_id,
+                name=f"{self._some_name}-3"
+            ).if_matches_etag(original_etag).future()
+
+        except PubNubException as e:
+            assert e.get_status_code() == 412
+            assert e.get_error_message().get('message') == 'Channel to update has been modified after it was read.'