Etag support for users and channels

A new optional parameter `ifMatchesEtag` is added to `setUUIDMetadata` and `setChannelMetadata`.
When provided, the server checks the argument value with the ETag on the server and if they don't match a HTTP 412 error is returned.

Author: wkal-pubnub

pubnub-gson/pubnub-gson-api/src/main/java/com/pubnub/api/java/endpoints/objects_api/channel/SetChannelMetadata.java

@@ -3,6 +3,7 @@
 import com.pubnub.api.java.endpoints.BuilderSteps;
 import com.pubnub.api.java.endpoints.Endpoint;
 import com.pubnub.api.java.models.consumer.objects_api.channel.PNSetChannelMetadataResult;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.Map;
 
@@ -19,6 +20,14 @@ public interface SetChannelMetadata extends Endpoint<PNSetChannelMetadataResult>
 
     SetChannelMetadata includeCustom(boolean includeCustom);
 
+    /**
+     * Optional entity tag from a previously received `PNChannelMetadata`. The request
+     * will fail if this parameter is specified and the ETag value on the server doesn't match.
+     * @param etag from PNChannelMetadata
+     * @return this builder
+     */
+    SetChannelMetadata ifMatchesEtag(@Nullable String etag);
+
     interface Builder extends BuilderSteps.ChannelStep<SetChannelMetadata> {
         @Override
         SetChannelMetadata channel(String channel);

pubnub-gson/pubnub-gson-api/src/main/java/com/pubnub/api/java/endpoints/objects_api/uuid/SetUUIDMetadata.java

@@ -2,6 +2,7 @@
 
 import com.pubnub.api.java.endpoints.Endpoint;
 import com.pubnub.api.java.models.consumer.objects_api.uuid.PNSetUUIDMetadataResult;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.Map;
 
@@ -23,4 +24,12 @@ public interface SetUUIDMetadata extends Endpoint<PNSetUUIDMetadataResult> {
     SetUUIDMetadata type(String type);
 
     SetUUIDMetadata status(String status);
+
+    /**
+     * Optional entity tag from a previously received `PNUUIDMetadata`. The request
+     * will fail if this parameter is specified and the ETag value on the server doesn't match.
+     * @param etag from PNUUIDMetadata
+     * @return this builder
+     */
+    SetUUIDMetadata ifMatchesEtag(@Nullable String etag);
 }

pubnub-gson/pubnub-gson-impl/src/main/java/com/pubnub/internal/java/endpoints/objects_api/channel/SetChannelMetadataImpl.java

@@ -12,6 +12,7 @@
 import lombok.Setter;
 import lombok.experimental.Accessors;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.HashMap;
 import java.util.Map;
@@ -46,7 +47,8 @@ protected Endpoint<PNChannelMetadataResult> createRemoteAction() {
                 custom,
                 includeCustom,
                 type,
-                status
+                status,
+                ifMatchesEtag
         );
     }
 
@@ -69,6 +71,10 @@ protected Endpoint<PNChannelMetadataResult> createRemoteAction() {
     @Setter
     private boolean includeCustom;
 
+    @Setter
+    @Nullable
+    private String ifMatchesEtag;
+
     @Override
     public SetChannelMetadata custom(Map<String, Object> custom) {
         final HashMap<String, Object> customHashMap = new HashMap<>();

pubnub-gson/pubnub-gson-impl/src/main/java/com/pubnub/internal/java/endpoints/objects_api/uuid/SetUUIDMetadataImpl.java

@@ -12,6 +12,7 @@
 import lombok.Setter;
 import lombok.experimental.Accessors;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.HashMap;
 import java.util.Map;
@@ -37,6 +38,10 @@ public class SetUUIDMetadataImpl extends DelegatingEndpoint<PNUUIDMetadataResult
     @Setter
     private String status;
 
+    @Setter
+    @Nullable
+    private String ifMatchesEtag;
+
     public SetUUIDMetadataImpl(final PubNub pubnub) {
         super(pubnub);
     }
@@ -63,7 +68,8 @@ protected Endpoint<PNUUIDMetadataResult> createRemoteAction() {
                 custom,
                 includeCustom,
                 type,
-                status
+                status,
+                ifMatchesEtag
         );
     }
 

pubnub-kotlin/pubnub-kotlin-api/config/ktlint/baseline.xml

@@ -6,9 +6,6 @@
     <file name="src/commonMain/kotlin/com/pubnub/api/models/consumer/objects/membership/MembershipInclude.kt">
         <error line="20" column="5" source="standard:function-naming" />
     </file>
-    <file name="src/commonTest/kotlin/com/pubnub/test/integration/MembersTest.kt">
-        <error line="18" column="1" source="standard:blank-line-before-declaration" />
-    </file>
     <file name="src/jsMain/kotlin/Pubnub.d.kt">
         <error line="156" column="40" source="standard:comment-wrapping" />
         <error line="411" column="15" source="standard:class-naming" />
@@ -22,19 +19,17 @@
         <error line="849" column="13" source="standard:property-naming" />
         <error line="1034" column="15" source="standard:class-naming" />
         <error line="1040" column="15" source="standard:class-naming" />
-        <error line="1161" column="13" source="standard:property-naming" />
-        <error line="1169" column="13" source="standard:property-naming" />
+        <error line="1163" column="13" source="standard:property-naming" />
         <error line="1171" column="13" source="standard:property-naming" />
-        <error line="1234" column="39" source="standard:comment-wrapping" />
-        <error line="1319" column="15" source="standard:class-naming" />
-        <error line="1347" column="42" source="standard:comment-wrapping" />
-        <error line="1397" column="37" source="standard:comment-wrapping" />
-        <error line="1418" column="13" source="standard:property-naming" />
-        <error line="1419" column="13" source="standard:property-naming" />
-        <error line="1423" column="13" source="standard:property-naming" />
-        <error line="1424" column="13" source="standard:property-naming" />
-        <error line="1443" column="9" source="standard:property-naming" />
-        <error line="1444" column="9" source="standard:property-naming" />
+        <error line="1173" column="13" source="standard:property-naming" />
+        <error line="1236" column="39" source="standard:comment-wrapping" />
+        <error line="1321" column="15" source="standard:class-naming" />
+        <error line="1349" column="42" source="standard:comment-wrapping" />
+        <error line="1399" column="37" source="standard:comment-wrapping" />
+        <error line="1420" column="13" source="standard:property-naming" />
+        <error line="1421" column="13" source="standard:property-naming" />
+        <error line="1425" column="13" source="standard:property-naming" />
+        <error line="1426" column="13" source="standard:property-naming" />
         <error line="1445" column="9" source="standard:property-naming" />
         <error line="1446" column="9" source="standard:property-naming" />
         <error line="1447" column="9" source="standard:property-naming" />
@@ -46,8 +41,8 @@
         <error line="1453" column="9" source="standard:property-naming" />
         <error line="1454" column="9" source="standard:property-naming" />
         <error line="1455" column="9" source="standard:property-naming" />
-        <error line="1459" column="9" source="standard:property-naming" />
-        <error line="1460" column="9" source="standard:property-naming" />
+        <error line="1456" column="9" source="standard:property-naming" />
+        <error line="1457" column="9" source="standard:property-naming" />
         <error line="1461" column="9" source="standard:property-naming" />
         <error line="1462" column="9" source="standard:property-naming" />
         <error line="1463" column="9" source="standard:property-naming" />
@@ -82,8 +77,7 @@
         <error line="1492" column="9" source="standard:property-naming" />
         <error line="1493" column="9" source="standard:property-naming" />
         <error line="1494" column="9" source="standard:property-naming" />
-    </file>
-    <file name="src/jsMain/kotlin/com/pubnub/api/PubNubImpl.kt">
-        <error line="1446" column="12" source="standard:no-multi-spaces" />
+        <error line="1495" column="9" source="standard:property-naming" />
+        <error line="1496" column="9" source="standard:property-naming" />
     </file>
 </baseline>

pubnub-kotlin/pubnub-kotlin-api/src/appleMain/kotlin/com/pubnub/api/PubNubImpl.kt

@@ -513,7 +513,8 @@ class PubNubImpl(private val pubNubObjC: KMPPubNub) : PubNub {
         custom: CustomObject?,
         includeCustom: Boolean,
         type: String?,
-        status: String?
+        status: String?,
+        ifMatchesEtag: String?,
     ): SetChannelMetadata {
         return SetChannelMetadataImpl(
             pubnub = pubNubObjC,
@@ -523,7 +524,8 @@ class PubNubImpl(private val pubNubObjC: KMPPubNub) : PubNub {
             custom = custom,
             includeCustom = includeCustom,
             type = type,
-            status = status
+            status = status,
+            ifMatchesEtag = ifMatchesEtag,
         )
     }
 
@@ -570,7 +572,8 @@ class PubNubImpl(private val pubNubObjC: KMPPubNub) : PubNub {
         custom: CustomObject?,
         includeCustom: Boolean,
         type: String?,
-        status: String?
+        status: String?,
+        ifMatchesEtag: String?,
     ): SetUUIDMetadata {
         return SetUUIDMetadataImpl(
             pubnub = pubNubObjC,
@@ -582,7 +585,8 @@ class PubNubImpl(private val pubNubObjC: KMPPubNub) : PubNub {
             custom = custom,
             includeCustom = includeCustom,
             type = type,
-            status = status
+            status = status,
+            ifMatchesEtag = ifMatchesEtag,
         )
     }
 

pubnub-kotlin/pubnub-kotlin-api/src/appleMain/kotlin/com/pubnub/api/endpoints/objects/channel/SetChannelMetadata.ios.kt

@@ -28,7 +28,8 @@ class SetChannelMetadataImpl(
     private val custom: CustomObject?,
     private val includeCustom: Boolean,
     private val type: String?,
-    private val status: String?
+    private val status: String?,
+    private val ifMatchesEtag: String? = null,
 ) : SetChannelMetadata {
     override fun async(callback: Consumer<Result<PNChannelMetadataResult>>) {
         pubnub.setChannelMetadataWithMetadataId(
@@ -43,6 +44,7 @@ class SetChannelMetadataImpl(
             ),
             type = type,
             status = status,
+            ifMatchesEtag = ifMatchesEtag,
             onSuccess = callback.onSuccessHandler {
                 PNChannelMetadataResult(
                     status = 200,

pubnub-kotlin/pubnub-kotlin-api/src/appleMain/kotlin/com/pubnub/api/endpoints/objects/uuid/SetUUIDMetadata.ios.kt

@@ -30,7 +30,8 @@ class SetUUIDMetadataImpl(
     private val custom: CustomObject?,
     private val includeCustom: Boolean,
     private val type: String?,
-    private val status: String?
+    private val status: String?,
+    private val ifMatchesEtag: String? = null,
 ) : SetUUIDMetadata {
     override fun async(callback: Consumer<Result<PNUUIDMetadataResult>>) {
         pubnub.setUserMetadataWithMetadataId(
@@ -47,6 +48,7 @@ class SetUUIDMetadataImpl(
             ),
             type = type,
             status = status,
+            ifMatchesEtag = ifMatchesEtag,
             onSuccess = callback.onSuccessHandler {
                 PNUUIDMetadataResult(
                     status = 200,

pubnub-kotlin/pubnub-kotlin-api/src/commonMain/kotlin/com/pubnub/api/PubNub.kt

@@ -268,6 +268,7 @@ expect interface PubNub {
         includeCustom: Boolean = false,
         type: String? = null,
         status: String? = null,
+        ifMatchesEtag: String? = null,
     ): SetChannelMetadata
 
     fun removeChannelMetadata(channel: String): RemoveChannelMetadata
@@ -296,6 +297,7 @@ expect interface PubNub {
         includeCustom: Boolean = false,
         type: String? = null,
         status: String? = null,
+        ifMatchesEtag: String? = null,
     ): SetUUIDMetadata
 
     fun removeUUIDMetadata(uuid: String? = null): RemoveUUIDMetadata

pubnub-kotlin/pubnub-kotlin-api/src/commonTest/kotlin/com/pubnub/test/integration/ChannelMetadataTest.kt

@@ -52,6 +52,58 @@ class ChannelMetadataTest : BaseIntegrationTest() {
         assertEquals(description, pnuuidMetadata.description?.value)
     }
 
+    @Test
+    fun set_metadata_ifMatch_allows_change() = runTest {
+        // given
+        val result = pubnub.setChannelMetadata(
+            channel,
+            name = name,
+            status = status,
+            custom = custom,
+            includeCustom = includeCustom,
+            type = type,
+            description = description
+        ).await()
+
+        val pnChannelMetadata = result.data
+
+        // when
+        val newData = pubnub.setChannelMetadata(
+            channel,
+            status = "someNewStatus",
+            ifMatchesEtag = pnChannelMetadata.eTag?.value
+        ).await().data
+
+        // then
+        assertEquals("someNewStatus", newData.status?.value)
+    }
+
+    @Test
+    fun set_metadata_ifMatch_prohibits_change() = runTest {
+        // given
+        val result = pubnub.setChannelMetadata(
+            channel,
+            name = name,
+            status = status,
+            custom = custom,
+            includeCustom = includeCustom,
+            type = type,
+            description = description
+        ).await()
+
+        val pnChannelMetadata = result.data
+
+        pubnub.setChannelMetadata(channel, name = "someNewName").await()
+
+        // when
+        val ex = assertFailsWith<PubNubException> {
+            pubnub.setChannelMetadata(channel, status = "someNewStatus", ifMatchesEtag = pnChannelMetadata.eTag?.value).await()
+        }
+
+        // then
+        assertEquals(HTTP_PRECONDITION_FAILED, ex.statusCode)
+    }
+
     @Test
     fun can_receive_set_metadata_event() = runTest {
         pubnub.test(backgroundScope) {