Etag support for users and channels (#328)

* 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.

* PubNub SDK v10.4.0 release.

---------

Co-authored-by: PubNub Release Bot <[email protected]>

Author: wkal-pubnub

.github/workflows/commands-handler.yml

@@ -35,6 +35,9 @@ jobs:
           ref: v1
           token: ${{ secrets.GH_TOKEN }}
           path: .github/.release/actions
+      - name: Update CocoaPods trunk
+        run: |
+          pod repo update
       - name: Process changelog entries
         if: steps.user-check.outputs.expected-user == 'true'
         uses: ./.github/.release/actions/actions/commands

.github/workflows/release.yml

@@ -55,6 +55,9 @@ jobs:
           ref: v1
           token: ${{ secrets.GH_TOKEN }}
           path: .github/.release/actions
+      - name: Update CocoaPods trunk
+        run: |
+          pod repo update
       - name: Publish to Maven
         uses: ./.github/.release/actions/actions/services/maven
         with:

.github/workflows/run-tests.yml

@@ -33,6 +33,9 @@ jobs:
           key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
           restore-keys: |
             ${{ runner.os }}-gradle-
+      - name: Update CocoaPods trunk
+        run: |
+          pod repo update
       - name: Build and run tests
         run: |
           ./gradlew check

.github/workflows/run-validations.yml

@@ -53,6 +53,9 @@ jobs:
           key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
           restore-keys: |
             ${{ runner.os }}-gradle-
+      - name: Update CocoaPods trunk
+        run: |
+          pod repo update
       - name: Validate clean build
         run: ./gradlew ktlintFormat publishAllPublicationsToRepoRepository -PRELEASE_SIGNING_ENABLED=false
       - name: Cancel workflow runs for commit on error

.pubnub.yml

@@ -1,9 +1,9 @@
 name: kotlin
-version: 10.3.4
+version: 10.4.0
 schema: 1
 scm: github.com/pubnub/kotlin
 files:
-  - build/libs/pubnub-kotlin-10.3.4-all.jar
+  - build/libs/pubnub-kotlin-10.4.0-all.jar
 sdks:
   - 
       type: library
@@ -23,8 +23,8 @@ sdks:
             -
               distribution-type: library
               distribution-repository: maven
-              package-name: pubnub-kotlin-10.3.4
-              location: https://repo.maven.apache.org/maven2/com/pubnub/pubnub-kotlin/10.3.4/pubnub-kotlin-10.3.4.jar
+              package-name: pubnub-kotlin-10.4.0
+              location: https://repo.maven.apache.org/maven2/com/pubnub/pubnub-kotlin/10.4.0/pubnub-kotlin-10.4.0.jar
               supported-platforms:
                 supported-operating-systems:
                   Android:
@@ -121,6 +121,11 @@ sdks:
                   license-url: https://www.apache.org/licenses/LICENSE-2.0.txt
                   is-required: Required
 changelog:
+  - date: 2025-01-21
+    version: v10.4.0
+    changes:
+      - type: feature
+        text: "A new optional parameter `ifMatchesEtag` is added to `setUUIDMetadata` and `setChannelMetadata`. When provided, the server compares the argument value with the ETag on the server and if they don't match a HTTP 412 error is returned."
   - date: 2025-01-13
     version: v10.3.4
     changes:

CHANGELOG.md

@@ -1,3 +1,9 @@
+## v10.4.0
+January 21 2025
+
+#### Added
+- A new optional parameter `ifMatchesEtag` is added to `setUUIDMetadata` and `setChannelMetadata`. When provided, the server compares the argument value with the ETag on the server and if they don't match a HTTP 412 error is returned.
+
 ## v10.3.4
 January 13 2025
 

README.md

@@ -20,7 +20,7 @@ You will need the publish and subscribe keys to authenticate your app. Get your
      <dependency>
         <groupId>com.pubnub</groupId>
         <artifactId>pubnub-kotlin</artifactId>
-        <version>10.3.4</version>
+        <version>10.4.0</version>
      </dependency>
      ```
 

gradle.properties

@@ -18,7 +18,7 @@ RELEASE_SIGNING_ENABLED=true
 SONATYPE_HOST=DEFAULT
 SONATYPE_AUTOMATIC_RELEASE=false
 GROUP=com.pubnub
-VERSION_NAME=10.3.4
+VERSION_NAME=10.4.0
 POM_PACKAGING=jar
 
 POM_NAME=PubNub SDK

gradle/libs.versions.toml

@@ -12,8 +12,8 @@ ktlint = "12.1.0"
 dokka = "1.9.20"
 kotlinx_datetime = "0.6.1"
 kotlinx_coroutines = "1.9.0"
-pubnub_js = "8.4.1"
-pubnub_swift = "8.2.4"
+pubnub_js = "8.6.0"
+pubnub_swift = "8.3.0"
 
 [libraries]
 retrofit2 = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit2" }

kotlin-js-store/yarn.lock

@@ -659,10 +659,26 @@ proxy-from-env@^1.1.0:
   resolved "https://registry.yarnpkg.com/proxy-from-env/-/proxy-from-env-1.1.0.tgz#e102f16ca355424865755d2c9e8ea4f24d58c3e2"
   integrity sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==
 
-[email protected]:
-  version "8.4.0"
-  resolved "https://registry.yarnpkg.com/pubnub/-/pubnub-8.4.0.tgz#8a5fdd3af9783abb1de44ea4145107e296c8394d"
-  integrity sha512-HvkFhn4XcfR1wdJv4paX94I0TT4UBHW/vIuYnS+6XuoSx0AunJMCk5wbKnSesmdbzYUZa8Ag3H1mJQZKuyRy8Q==
+[email protected]:
+  version "8.4.1"
+  resolved "https://registry.yarnpkg.com/pubnub/-/pubnub-8.4.1.tgz#5f6f19e84d3187dc8aee0a458bd6b05e90d43e6a"
+  integrity sha512-mPlwVoHJDWPasZx52UfSMiPX5TATm5A+ficSogyqDqTQ4w5EQnwxH+PJdsWc0mPnlT051jM1vIISMeM0fQ30CQ==
+  dependencies:
+    agentkeepalive "^3.5.2"
+    buffer "^6.0.3"
+    cbor-js "^0.1.0"
+    cbor-sync "^1.0.4"
+    form-data "^4.0.0"
+    lil-uuid "^0.1.1"
+    node-fetch "^2.7.0"
+    proxy-agent "^6.3.0"
+    react-native-url-polyfill "^2.0.0"
+    text-encoding "^0.7.0"
+
+[email protected]:
+  version "8.6.0"
+  resolved "https://registry.yarnpkg.com/pubnub/-/pubnub-8.6.0.tgz#75524e7ed3653090652d160ce83ac089362a0379"
+  integrity sha512-LBCglooxiLkNT3ArUOvSJnLKK6/QdeshWY60IWlSQ+SkXlzEjt74wAnX5XriEXKsmza2yw9mFGG6+B5SlczRzA==
   dependencies:
     agentkeepalive "^3.5.2"
     buffer "^6.0.3"

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,