Merge pull request #115 from ably-labs/112-wait-to-be-able-to-do-pres…

…ence

[ECO-5114] Provide mechanism for waiting to be able to perform presence operations

Sources/AblyChat/Errors.swift

@@ -11,6 +11,8 @@ public let errorDomain = "AblyChatErrorDomain"
  The error codes for errors in the ``errorDomain`` error domain.
  */
 public enum ErrorCode: Int {
+    case nonspecific = 40000
+
     /// ``Rooms.get(roomID:options:)`` was called with a different set of room options than was used on a previous call. You must first release the existing room instance using ``Rooms.release(roomID:)``.
     ///
     /// TODO this code is a guess, revisit in https://github.com/ably-labs/ably-chat-swift/issues/32
@@ -36,7 +38,8 @@ public enum ErrorCode: Int {
     internal var statusCode: Int {
         // TODO: These are currently a guess, revisit once outstanding spec question re status codes is answered (https://github.com/ably/specification/pull/200#discussion_r1755222945), and also revisit in https://github.com/ably-labs/ably-chat-swift/issues/32
         switch self {
-        case .inconsistentRoomOptions,
+        case .nonspecific,
+             .inconsistentRoomOptions,
              .messagesDetachmentFailed,
              .presenceDetachmentFailed,
              .reactionsDetachmentFailed,
@@ -69,6 +72,8 @@ internal enum ChatError {
     case roomInFailedState
     case roomIsReleasing
     case roomIsReleased
+    case presenceOperationRequiresRoomAttach(feature: RoomFeature)
+    case presenceOperationDisallowedForCurrentRoomStatus(feature: RoomFeature)
 
     /// The ``ARTErrorInfo.code`` that should be returned for this error.
     internal var code: ErrorCode {
@@ -107,20 +112,14 @@ internal enum ChatError {
             .roomIsReleasing
         case .roomIsReleased:
             .roomIsReleased
+        case .presenceOperationRequiresRoomAttach,
+             .presenceOperationDisallowedForCurrentRoomStatus:
+            .nonspecific
         }
     }
 
-    /// A helper type for parameterising the construction of error messages.
-    private enum AttachOrDetach {
-        case attach
-        case detach
-    }
-
-    private static func localizedDescription(
-        forFailureOfOperation operation: AttachOrDetach,
-        feature: RoomFeature
-    ) -> String {
-        let featureDescription = switch feature {
+    private static func descriptionOfFeature(_ feature: RoomFeature) -> String {
+        switch feature {
         case .messages:
             "messages"
         case .occupancy:
@@ -132,15 +131,26 @@ internal enum ChatError {
         case .typing:
             "typing"
         }
+    }
+
+    /// A helper type for parameterising the construction of error messages.
+    private enum AttachOrDetach {
+        case attach
+        case detach
+    }
 
+    private static func localizedDescription(
+        forFailureOfOperation operation: AttachOrDetach,
+        feature: RoomFeature
+    ) -> String {
         let operationDescription = switch operation {
         case .attach:
             "attach"
         case .detach:
             "detach"
         }
 
-        return "The \(featureDescription) feature failed to \(operationDescription)."
+        return "The \(descriptionOfFeature(feature)) feature failed to \(operationDescription)."
     }
 
     /// The ``ARTErrorInfo.localizedDescription`` that should be returned for this error.
@@ -158,6 +168,10 @@ internal enum ChatError {
             "Cannot perform operation because the room is in a releasing state."
         case .roomIsReleased:
             "Cannot perform operation because the room is in a released state."
+        case let .presenceOperationRequiresRoomAttach(feature):
+            "To perform this \(Self.descriptionOfFeature(feature)) operation, you must first attach the room."
+        case let .presenceOperationDisallowedForCurrentRoomStatus(feature):
+            "This \(Self.descriptionOfFeature(feature)) operation can not be performed given the current room status."
         }
     }
 
@@ -171,7 +185,9 @@ internal enum ChatError {
         case .inconsistentRoomOptions,
              .roomInFailedState,
              .roomIsReleasing,
-             .roomIsReleased:
+             .roomIsReleased,
+             .presenceOperationRequiresRoomAttach,
+             .presenceOperationDisallowedForCurrentRoomStatus:
             nil
         }
     }

Sources/AblyChat/Room.swift

@@ -84,15 +84,17 @@ internal actor DefaultRoom<LifecycleManagerFactory: RoomLifecycleManagerFactory>
             throw ARTErrorInfo.create(withCode: 40000, message: "Ensure your Realtime instance is initialized with a clientId.")
         }
 
-        let featureChannels = Self.createFeatureChannels(roomID: roomID, roomOptions: options, realtime: realtime)
-        channels = featureChannels.mapValues(\.channel)
-        let contributors = featureChannels.values.map(\.contributor)
+        let featureChannelPartialDependencies = Self.createFeatureChannelPartialDependencies(roomID: roomID, roomOptions: options, realtime: realtime)
+        channels = featureChannelPartialDependencies.mapValues(\.channel)
+        let contributors = featureChannelPartialDependencies.values.map(\.contributor)
 
         lifecycleManager = await lifecycleManagerFactory.createManager(
             contributors: contributors,
             logger: logger
         )
 
+        let featureChannels = Self.createFeatureChannels(partialDependencies: featureChannelPartialDependencies, lifecycleManager: lifecycleManager)
+
         // TODO: Address force unwrapping of `channels` within feature initialisation below: https://github.com/ably-labs/ably-chat-swift/issues/105
 
         messages = await DefaultMessages(
@@ -124,7 +126,12 @@ internal actor DefaultRoom<LifecycleManagerFactory: RoomLifecycleManagerFactory>
         ) : nil
     }
 
-    private static func createFeatureChannels(roomID: String, roomOptions: RoomOptions, realtime: RealtimeClient) -> [RoomFeature: DefaultFeatureChannel] {
+    private struct FeatureChannelPartialDependencies {
+        internal var channel: RealtimeChannelProtocol
+        internal var contributor: DefaultRoomLifecycleContributor
+    }
+
+    private static func createFeatureChannelPartialDependencies(roomID: String, roomOptions: RoomOptions, realtime: RealtimeClient) -> [RoomFeature: FeatureChannelPartialDependencies] {
         .init(uniqueKeysWithValues: [
             RoomFeature.messages,
             RoomFeature.reactions,
@@ -156,6 +163,16 @@ internal actor DefaultRoom<LifecycleManagerFactory: RoomLifecycleManagerFactory>
         })
     }
 
+    private static func createFeatureChannels(partialDependencies: [RoomFeature: FeatureChannelPartialDependencies], lifecycleManager: RoomLifecycleManager) -> [RoomFeature: DefaultFeatureChannel] {
+        partialDependencies.mapValues { partialDependencies in
+            .init(
+                channel: partialDependencies.channel,
+                contributor: partialDependencies.contributor,
+                roomLifecycleManager: lifecycleManager
+            )
+        }
+    }
+
     public nonisolated var presence: any Presence {
         guard let _presence else {
             fatalError("Presence is not enabled for this room")

Sources/AblyChat/RoomFeature.swift

@@ -31,19 +31,38 @@ internal enum RoomFeature {
 
 /// Provides all of the channel-related functionality that a room feature (e.g. an implementation of ``Messages``) needs.
 ///
-/// This mishmash exists to give a room feature access to both:
+/// This mishmash exists to give a room feature access to:
 ///
 /// - a `RealtimeChannelProtocol` object (this is the interface that our features are currently written against, as opposed to, say, `RoomLifecycleContributorChannel`)
 /// - the discontinuities emitted by the room lifecycle
+/// - the presence-readiness wait mechanism supplied by the room lifecycle
 internal protocol FeatureChannel: Sendable, EmitsDiscontinuities {
     var channel: RealtimeChannelProtocol { get }
+
+    /// Waits until we can perform presence operations on the contributors of this room without triggering an implicit attach.
+    ///
+    /// Implements the checks described by CHA-PR3d, CHA-PR3e, CHA-PR3f, and CHA-PR3g (and similar ones described by other functionality that performs contributor presence operations). Namely:
+    ///
+    /// - CHA-PR3d, CHA-PR10d, CHA-PR6c, CHA-T2c: If the room is in the ATTACHING status, it waits for the current ATTACH to complete and then returns. If the current ATTACH fails, then it re-throws that operation’s error.
+    /// - CHA-PR3e, CHA-PR11e, CHA-PR6d, CHA-T2d: If the room is in the ATTACHED status, it returns immediately.
+    /// - CHA-PR3f, CHA-PR11f, CHA-PR6e, CHA-T2e: If the room is in the DETACHED status, it throws an `ARTErrorInfo` derived from ``ChatError.presenceOperationRequiresRoomAttach(feature:)``.
+    /// - // CHA-PR3g, CHA-PR11g, CHA-PR6f, CHA-T2f: If the room is in any other status, it throws an `ARTErrorInfo` derived from ``ChatError.presenceOperationDisallowedForCurrentRoomStatus(feature:)``.
+    ///
+    /// - Parameters:
+    ///   - requester: The room feature that wishes to perform a presence operation. This is only used for customising the message of the thrown error.
+    func waitToBeAbleToPerformPresenceOperations(requestedByFeature requester: RoomFeature) async throws(ARTErrorInfo)
 }
 
 internal struct DefaultFeatureChannel: FeatureChannel {
     internal var channel: RealtimeChannelProtocol
     internal var contributor: DefaultRoomLifecycleContributor
+    internal var roomLifecycleManager: RoomLifecycleManager
 
     internal func subscribeToDiscontinuities() async -> Subscription<ARTErrorInfo> {
         await contributor.subscribeToDiscontinuities()
     }
+
+    internal func waitToBeAbleToPerformPresenceOperations(requestedByFeature requester: RoomFeature) async throws(ARTErrorInfo) {
+        try await roomLifecycleManager.waitToBeAbleToPerformPresenceOperations(requestedByFeature: requester)
+    }
 }