Add support for when setting Channel and User metadata

Sources/PubNub/APIs/Objects+PubNub.swift

@@ -537,24 +537,29 @@ public extension PubNub {
   ///
   ///  Set metadata for a User in the database, optionally including the custom data object for each.
   /// - Parameters:
-  ///   - user: The `PubNubUserMetadata` to set
+  ///   - metadata: The `PubNubUserMetadata` to set
+  ///   - ifMatchesEtag: The entity tag to be used for the `If-Match` HTTP header to enable conditional requests
   ///   - include: Include respective additional fields in the response.
   ///   - custom: Custom configuration overrides for this request
   ///   - completion: The async `Result` of the method call
   ///     - **Success**: The `PubNubUserMetadata` containing the set changes
   ///     - **Failure**: An `Error` describing the failure
   func setUserMetadata(
     _ metadata: PubNubUserMetadata,
+    ifMatchesEtag: String? = nil,
     include: UserIncludeFields = UserIncludeFields(),
     custom requestConfig: RequestConfiguration = RequestConfiguration(),
     completion: ((Result<PubNubUserMetadata, Error>) -> Void)?
   ) {
+    let customHeadersIfAny = if let entityTag = ifMatchesEtag {
+      [Constant.ifMatchHeaderKey: entityTag]
+    } else {
+      [String: String]()
+    }
     let router = ObjectsUserRouter(
-      .set(
-        metadata: metadata,
-        include: include.includeFields
-      ),
-      configuration: requestConfig.customConfiguration ?? configuration
+      .set(metadata: metadata, include: include.includeFields),
+      configuration: requestConfig.customConfiguration ?? configuration,
+      customHeaders: customHeadersIfAny
     )
 
     route(
@@ -760,20 +765,28 @@ public extension PubNub {
   ///
   /// - Parameters:
   ///   - metadata: The `PubNubChannelMetadata` to set
+  ///   - ifMatchesEtag: The entity tag to be used for the `If-Match` HTTP header to enable conditional requests
   ///   - include: Include respective additional fields in the response.
   ///   - custom: Custom configuration overrides for this request
   ///   - completion: The async `Result` of the method call
   ///     - **Success**: The `PubNubChannelMetadata` containing the set changes
   ///     - **Failure**: An `Error` describing the failure
   func setChannelMetadata(
     _ metadata: PubNubChannelMetadata,
+    ifMatchesEtag: String? = nil,
     include: ChannelIncludeFields = ChannelIncludeFields(),
     custom requestConfig: RequestConfiguration = RequestConfiguration(),
     completion: ((Result<PubNubChannelMetadata, Error>) -> Void)?
   ) {
+    let customHeadersIfAny = if let entityTag = ifMatchesEtag {
+      [Constant.ifMatchHeaderKey: entityTag]
+    } else {
+      [String: String]()
+    }
     let router = ObjectsChannelRouter(
       .set(metadata: metadata, include: include.includeFields),
-      configuration: requestConfig.customConfiguration ?? configuration
+      configuration: requestConfig.customConfiguration ?? configuration,
+      customHeaders: customHeadersIfAny
     )
 
     route(

Sources/PubNub/Helpers/Constants.swift

@@ -167,6 +167,12 @@ public extension Constant {
   /// [RFC6585 section 4](https://datatracker.ietf.org/doc/html/rfc6585#section-4)
   static let retryAfterHeaderKey = "Retry-After"
 
+  /// The HTTP `If-Match` request header makes a request conditional. A server will return resources for `GET` and `HEAD` methods, or upload resource for `PUT` and other non-safe methods, only if the resource
+  /// matches one of the `ETag` values in the `If-Match` request header. If the conditional does not match, the `412 Precondition Failed` response is returned instead.
+  ///
+  /// [RFC7232 section 3.1](https://datatracker.ietf.org/doc/html/rfc7232#section-3.1)
+  static let ifMatchHeaderKey = "If-Match"
+
   internal static let defaultUserAgentHeader: String = {
     let userAgent: String = {
       let appNameVersion = "\(Constant.appBundleId)/\(Constant.appVersion)"

Sources/PubNub/KMP/KMPPubNub+AppContext.swift

@@ -164,6 +164,7 @@ public extension KMPPubNub {
     custom: KMPAnyJSON?,
     type: String?,
     status: String?,
+    ifMatchesEtag: String?,
     include includeFields: KMPChannelIncludeFields,
     onSuccess: @escaping ((KMPChannelMetadata) -> Void),
     onFailure: @escaping ((Error) -> Void)
@@ -255,6 +256,7 @@ public extension KMPPubNub {
     custom: KMPAnyJSON?,
     type: String?,
     status: String?,
+    ifMatchesEtag: String?,
     include includeFields: KMPUserIncludeFields,
     onSuccess: @escaping ((KMPUserMetadata) -> Void),
     onFailure: @escaping ((Error) -> Void)
@@ -269,7 +271,7 @@ public extension KMPPubNub {
       email: email,
       custom: convertDictionaryToScalars(custom?.asMap())
     )
-    pubnub.setUserMetadata(userMetadata, include: mapToPubNubUserIncludeFields(from: includeFields)) {
+    pubnub.setUserMetadata(userMetadata, ifMatchesEtag: ifMatchesEtag, include: mapToPubNubUserIncludeFields(from: includeFields)) {
       switch $0 {
       case .success(let metadata):
         onSuccess(KMPUserMetadata(metadata: metadata))

Sources/PubNub/Networking/Routers/ObjectsChannelRouter.swift

@@ -57,13 +57,15 @@ public struct ObjectsChannelRouter: HTTPRouter {
   }
 
   // Init
-  public init(_ endpoint: Endpoint, configuration: RouterConfiguration) {
+  public init(_ endpoint: Endpoint, configuration: RouterConfiguration, customHeaders: [String: String] = [:]) {
     self.endpoint = endpoint
     self.configuration = configuration
+    self.customHeaders = customHeaders
   }
 
   public var endpoint: Endpoint
   public var configuration: RouterConfiguration
+  public var customHeaders: [String: String]
 
   // Protocol Properties
   public var service: PubNubService {
@@ -74,6 +76,10 @@ public struct ObjectsChannelRouter: HTTPRouter {
     return endpoint.description
   }
 
+  public var additionalHeaders: [String: String] {
+    customHeaders
+  }
+
   public var path: Result<String, Error> {
     let path: String
 

Sources/PubNub/Networking/Routers/ObjectsUserRouter.swift

@@ -64,13 +64,15 @@ public struct ObjectsUserRouter: HTTPRouter {
   }
 
   // Init
-  public init(_ endpoint: Endpoint, configuration: RouterConfiguration) {
+  public init(_ endpoint: Endpoint, configuration: RouterConfiguration, customHeaders: [String: String] = [:]) {
     self.endpoint = endpoint
     self.configuration = configuration
+    self.customHeaders = customHeaders
   }
 
   public var endpoint: Endpoint
   public var configuration: RouterConfiguration
+  public var customHeaders: [String: String]
 
   // Protocol Properties
   public var service: PubNubService {
@@ -81,6 +83,10 @@ public struct ObjectsUserRouter: HTTPRouter {
     return endpoint.description
   }
 
+  public var additionalHeaders: [String: String] {
+    customHeaders
+  }
+
   public var path: Result<String, Error> {
     let path: String