Merge pull request #217 from ably/chat-async-rooms

chat: add async rooms spec

textile/chat-features.textile

@@ -39,7 +39,6 @@ h3(#rooms-status). Room Statuses
 The status of any given Chat Room is the combination of the states of all of its constituent contributors. For more information on this, see "@Room Lifecycle@":#rooms-lifecycle.
 
 * @(CHA-RS1)@ Every room has a @status@, which describes the current status of the room.
-** @(CHA-RS1j)@ The @INITIALIZING@ status is the initial status as the room is setting itself up.
 ** @(CHA-RS1a)@ The @INITIALIZED@ status is the initial status before any attachment operations have taken place.
 ** @(CHA-RS1b)@ The @ATTACHING@ status is used when the room is in the process of attaching to Ably.
 ** @(CHA-RS1c)@ The @ATTACHED@ status means that the room is fully connected to Ably and functioning normally.
@@ -49,6 +48,7 @@ The status of any given Chat Room is the combination of the states of all of its
 ** @(CHA-RS1g)@ The @FAILED@ status means that something has gone wrong with the room (such as lack of permissions). The room will not attempt to connect to Ably and will require user intervention.
 ** @(CHA-RS1h)@ The @RELEASING@ status means that the room is being released and the underlying resources are being cleaned up.
 ** @(CHA-RS1i)@ The @RELEASED@ status means that the room has been cleaned up and the object can no longer be used.
+** @(CHA-RS1j)@ The @INITIALIZING@ status is reserved for React uses, and should not be included outside of the JS/TS SDK.
 * @(CHA-RS2)@ A room must expose its current status.
 ** @(CHA-RS2a)@ @[Testable]@ A room must expose its current status, a single value from the list provided above.
 ** @(CHA-RS2b)@ A room must expose the latest error, if any, associated with its current status.
@@ -80,7 +80,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations
 
 * @(CHA-RL1)@ A room must be explicitly attached via the @ATTACH@ operation.
 ** @(CHA-RL1a)@ @[Testable]@ If the room is already in the @ATTACHED@ status, then this operation is no-op.
-** @(CHA-RL1j)@ If the room is in the @INITIALIZING@ status, then it must wait for the in-progress @RELEASING@ operation from a previous room instance to complete before proceeding.
+** @(CHA-RL1j)@ This specification point has been removed.
 ** @(CHA-RL1b)@ @[Testable]@ If the room is in the @RELEASING@ status, the operation shall be rejected with an @ErrorInfo@ with the @RoomIsReleasing@ error code from the "chat-specific error codes":#error-codes.
 ** @(CHA-RL1c)@ @[Testable]@ If the room is in the @RELEASED@ status, the operation shall be rejected with an @ErrorInfo@ with the @RoomIsReleased@ error code from the "chat-specific error codes":#error-codes.
 ** @(CHA-RL1d)@ @[Testable]@ If a room lifecycle operation is already in progress, this operation shall wait until the current operation completes before continuing, subject to @CHA-RL7@.
@@ -110,12 +110,12 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations
 ** @(CHA-RL2h)@ If during detachment, a channel fails to detach (i.e. the call to @detach()@ returns an error), different operations are performed based on the nature of the detach.
 *** @(CHA-RL2h1)@ @[Testable]@ If a channel enters the @FAILED@ state during detachment (i.e. the @detach()@ operation fails and upon subsequently checking the channel state, it is @FAILED@), then the room will transition to the @FAILED@ status. The detach operation continues until, for every channel, either a call to @detach()@ has succeeded, or the channel enters the @FAILED@ state, with the operation throwing an @ErrorInfo@ with the feature-specific error code of the first feature to fail, using the error returned by the call to @detach()@ as the @cause@. The same @ErrorInfo@ must accompany the @FAILED@ room status.
 *** @(CHA-RL2h2)@ @[Testable]@ If the room is already in a @FAILED@ status during the detach operation and another channel fails, the @FAILED@ status will not be emitted twice.
-*** @(CHA-RL2h3)@ @[Testable]@ If a channel enters another state during detachment (namely @ATTACHED@, which happens when detach times out), then the @CHA-RL2f@ detachment cycle will be retried after a 250ms pause. This is indicated by the @detach()@ call returning an error, at which point the current state may be inspected on the channel object. The rooms status will not change during this process.
+*** @(CHA-RL2h3)@ @[Testable]@ A channel may enter another state during detachment (namely @ATTACHED@, which happens when detach times out), whereby the call to @detach()@ on the realtime channel will throw an error and the channel status can be ascertained by inspecting the channel object. If this happens, the @CHA-RL2f@ detachment cycle shall be retried after a 250ms pause. The room status shall not change during this retry process.
 ** @(CHA-RL2i)@ @[Testable]@ If a room lifecycle operation is already in progress, this operation shall wait until the current operation completes before continuing, subject to @CHA-RL7@.
 * @(CHA-RL3)@ A room must be explicitly released via the @RELEASE@ operation. This operation is not performed directly on a Room object by the client, but is described here.
 ** @(CHA-RL3a)@ @[Testable]@ If the room is already in the @RELEASED@ status, this operation is no-op.
 ** @(CHA-RL3b)@ @[Testable]@ If the room is in the @DETACHED@ status, then the room is immediately transitioned to @RELEASED@ and the operation succeeds.
-** @(CHA-RL3i)@ @[Testable]@ If the room is in the @INITIALIZING@ status, then the room is immediately transitioned to @RELEASED@ and the operation succeeds.
+** @(CHA-RL3i)@ This specification point has been removed.
 ** @(CHA-RL3j)@ @[Testable]@ If the room is in the @INITIALIZED@ status, then the room is immediately transitioned to @RELEASED@ and the operation succeeds.
 ** @(CHA-RL3c)@ @[Testable]@ If the room is in the @RELEASING@ status, then the operation will return the result of the pending @release@ operation, or throw any exception that it throws.
 ** @(CHA-RL3l)@ @[Testable]@ When the release operation commences, the room will transition into the @RELEASING@ status and any transient disconnect timeouts shall be cleared.
@@ -136,8 +136,9 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations
 *** @(CHA-RL5f1)@ This specification point has been removed. Refer to the @CHA-RL1e@ attachment cycle.
 *** @(CHA-RL5f2)@ This specification point has been removed. Refer to the @CHA-RL1e@ attachment cycle.
 *** @(CHA-RL5f3)@ This specification point has been removed. Refer to the @CHA-RL1e@ attachment cycle.
-* @(CHA-RL6)@ @[Testable]@ A room begins its lifetime in the @INTIIALIZING@ state.
-* @(CHA-RL6a)@ @[Testable]@ It enters @INITIALIZED@ when any @RELEASE@ operations for a previous instance of a room are completed.
+* @(CHA-RL6)@ This specification point has been removed. It was superseded by @CHA-RL8@.
+* @(CHA-RL6a)@ This specification point has been removed. It was superseded by @CHA-RL8@.
+* @(CHA-RL8)@ @[Testable]@ A room begins its lifetime in the @INITIALIZED@ state.
 * @(CHA-RL7)@ Room lifecycle operations are atomic and exclusive operations: one operation must complete (whether that's failure or success) before the next one may begin.
 ** @(CHA-RL7a)@ @[Testable]@ Room lifecycle operations have a precedence. If multiple operations are scheduled to run, they run in the following order:
 *** @(CHA-RL7a1)@ The @RETRY@ operation - an internal process.
@@ -172,12 +173,25 @@ h2(#room-configuration). Room Configuration
 Each chat room can be configured individually, allowing options to be passed as to which features are enabled and also feature-specific settings.
 
 * @(CHA-RC1)@ Chat Rooms are singleton objects with respect to the Chat Client on which they are created.
-** @(CHA-RC1a)@ @[Testable]@ Requesting a room from the Chat Client will provide an instance of a room with the provided id.
-** @(CHA-RC1b)@ @[Testable]@ Once a room has been created on the Chat Client, assuming it is not subsequently released, then the client will return the same room instance on subsequent calls for the same room ID.
-** @(CHA-RC1c)@ @[Testable]@ If a room is requested with different options to an existing room of the same id, then an @ErrorInfo@ with code @40000@ is thrown.
-** @(CHA-RC1d)@ @[Testable]@ If a room is requested to be released, it is immediately removed from the SDKs room map - meaning subsequent calls to get an instance of a room for the same ID shall produce a new object.
-*** @(CHA-RC1d1)@ @[Testable]@ Any attach operations on the new room instance must not commence until the release operation fully completes (including any Realtime channel releasing). This is to avoid resource leakage and accidentally removing the underlying channels during transition.
-** @(CHA-RC1e)@ @[Testable]@ Pursuant to @CHA-RC1d@, the room releasing lifecycle operations (see "@CHA-RL3@"#CHA-RL3) shall occur @AFTER@ the room is removed from the room map, but shall complete before the call to release the room completes.
+** @(CHA-RC1a)@ This specification point has been removed. It was superseded by CHA-RC1f.
+** @(CHA-RC1f)@ @[Testable]@ Requesting a room from the Chat Client shall return a future, that eventually resolves to an instance of a room with the provided id and options.
+*** @(CHA-RC1f1)@ @[Testable]@ If the room id exists in the room map, but the room has been requested with different options, then an @ErrorInfo@ with code @40000@ is thrown.
+*** @(CHA-RC1f2)@ @[Testable]@ If the room id exists in the room map, and it is requested with the same options, then the same instance of the room must be reused.
+*** @(CHA-RC1f3)@ @[Testable]@ If no @CHA-RC1g@ release operation is in progress, a new room instance shall be created, added to the room map and returned as the future value.
+*** @(CHA-RC1f4)@ @[Testable]@ If a @CHA-RC1g@ release operation is in progress, the entry shall be added to the room map, but the new room instance must not be created until the release operation has resolved. The future shall then subsequently resolve with the new room value.
+*** @(CHA-RC1f5)@ In relation to @CHA-RC1f4@, we recommend storing a future in the room map.
+*** @(CHA-RC1f6)@ It should be noted that the "get" operations in this section are interruptible by a @CHA-RC1f@ release call.
+** @(CHA-RC1b)@ This specification point has been removed, it was superseded by @CHA-RC1f2@
+** @(CHA-RC1c)@ This specification point has been removed, it was superseded by @CHA-RC1f3@
+** @(CHA-RC1d)@ This specification point has been removed.
+*** @(CHA-RC1d1)@ This specification point has been removed.
+** @(CHA-RC1e)@ This specification point has been removed.
+** @(CHA-RC1g)@ A room may be @released@, which causes it to be disposed of and eligible for garbage collection.
+*** @(CHA-RC1g1)@ The release operation returns a future that shall resolve when the operation completes. 
+*** @(CHA-RC1g2)@ @[Testable]@ If the room does not exist in the room map, and no release operation is in progress, this operation is no-op.
+*** @(CHA-RC1g3)@ @[Testable]@ If the room does not exist in the room map, and a release operation is already in progress, then the associated future will be returned.
+*** @(CHA-RC1g4)@ @[Testable]@ If a release operation is already in progress, any pending @CHA-RC1f@ future shall be rejected / throw an error. The error must use the @RoomReleasedBeforeOperationCompleted@ error code from the "chat-specific error codes":#error-codes and a @statusCode@ of 400. The room shall be removed from the room map and the operation must return the future associated with the previous operation.
+*** @(CHA-RC1g5)@ @[Testable]@ The room is removed from the room map and a @CHA-RL3@ release operation is initiated for the room object. A future is returned which resolves when the release operation completes.
 * @(CHA-RC2)@ Chat rooms are configurable, so as to enable or disable certain features. When requesting a room, options as to which features should be enabled, and the configuration they should take, must be provided (@RoomOptions@).
 ** @(CHA-RC2a)@ @[Testable]@ If a room is requested with invalid configuration, for example: a negative typing timeout, an @ErrorInfo@ with code @40001@ must be thrown.
 ** @(CHA-RC2b)@ @[Testable]@ If a room is configured to have a given feature disabled, then attempting to use that feature must result in an @ErrorInfo@ with code @40000@ being thrown.
@@ -267,19 +281,19 @@ Presence allows chat room users to indicate to others that they're online, as we
 * @(CHA-PR3)@ Users may enter presence. The behaviour depends on the current room status, as presence operations in a Realtime Client cause implicit attaches.
 ** @(CHA-PR3a)@ @[Testable]@ Users may choose to enter presence, optionally providing custom data to enter with. The overall presence data must retain the format specified in @CHA-PR2@.
 ** @(CHA-PR3b)@ This clause has been replaced by @CHA-PR3c - CHA-PR3g@.
-** @(CHA-PR3c)@ If the room status is @Initialized@ or @Initializing@, behaviour depends on whether attach has been called.
-*** @(CHA-PR3c1)@ @[Testable]@ If the attach has been called, then the @enter@ call will wait for the attach operation to succeed and then call the underlying presence @enter@ operation. It will throw an error if the attach fails.
-*** @(CHA-PR3c2)@ @[Testable]@ If the attach has not been called, then the @enter@ call will throw an error.
+** @(CHA-PR3c)@ This specification point has been removed.
+*** @(CHA-PR3c1) This specification point has been removed.
+*** @(CHA-PR3c2)@ This specification point has been removed.
 ** @(CHA-PR3d)@ @[Testable]@ If the room status is @Attaching@, then the @enter@ call will wait for the attach operation to succeed and then call the underlying presence @enter@ operation. It will throw an error if the attach fails.
 ** @(CHA-PR3e)@ @[Testable]@ If the room status is @Attached@, then the @enter@ call will invoke the underlying @presence.enter()@ call.
 ** @(CHA-PR3f)@ @[Testable]@ If the room status is @Detached@, an @ErrorInfo@ with code 40000, explaining that attach must be called first, will be thrown.
 ** @(CHA-PR3g)@ @[Testable]@ For any other room status, an @ErrorInfo@ with code 40000 will be thrown.
 * @(CHA-PR10)@ Users may update their presence data. The behaviour depends on the current room status, as presence operations in a Realtime Client cause implicit attaches.
 ** @(CHA-PR10a)@ @[Testable]@ Users may choose to update their presence data, optionally providing custom data to update with. The overall presence data must retain the format specified in @CHA-PR2@.
 ** @(CHA-PR10b)@ This clause has been replaced by @CHA-PR10c - CHA-PR10g@.
-** @(CHA-PR10c)@ If the room status is @Initialized@ or @Initializing@, behaviour depends on whether attach has been called.
-*** @(CHA-PR10c1)@ @[Testable]@ If the attach has been called, then the @update@ call will wait for the attach operation to succeed and then call the underlying presence @update@ operation. It will throw an error if the attach fails.
-*** @(CHA-PR10c2)@ @[Testable]@ If the attach has not been called, then the @update@ call will throw an error.
+** @(CHA-PR10c)@ This specification point has been removed.
+*** @(CHA-PR10c1)@ This specification point has been removed.
+*** @(CHA-PR10c2)@ This specification point has been removed.
 ** @(CHA-PR10d)@ @[Testable]@ If the room status is @Attaching@, then the @update@ call will wait for the attach operation to succeed and then call the underlying presence @update@ operation. It will throw an error if the attach fails.
 ** @(CHA-PR10e)@ @[Testable]@ If the room status is @Attached@, then the @update@ call will invoke the underlying @presence.enter()@ call.
 ** @(CHA-PR10f)@ @[Testable]@ If the room status is @Detached@, an @ErrorInfo@ with code 40000, explaining that attach must be called first, will be thrown.
@@ -289,9 +303,9 @@ Presence allows chat room users to indicate to others that they're online, as we
 * @(CHA-PR5)@ @[Testable]@ It must be possible to query if a given clientId is in the presence set.
 * @(CHA-PR6)@ @[Testable]@ It must be possible to retrieve all the "@Members":#chat-structs-presence-member of the presence set. The behaviour depends on the current room status, as presence operations in a Realtime Client cause implicit attaches.
 ** @(CHA-PR6a)@ This clause has been replaced by @CHA-PR6b - CHA-PR6f@.
-** @(CHA-PR6b)@ If the room status is @Initialized@ or @Initializing@, behaviour depends on whether attach has been called.
-*** @(CHA-PR6b1)@ @[Testable]@ If the attach has been called, then the @get@ call will wait for the attach operation to succeed and then call the underlying presence @get@ operation. It will throw an error if the attach fails.
-*** @(CHA-PR6b2)@ @[Testable]@ If the attach has not been called, then the @get@ call will throw an error.
+** @(CHA-PR6b)@ This specification point has been removed.
+*** @(CHA-PR6b1)@ This specification point has been removed.
+*** @(CHA-PR6b2)@ This specification point has been removed.
 ** @(CHA-PR6c)@ @[Testable]@ If the room status is @Attaching@, then the @get@ call will wait for the attach operation to succeed and then call the underlying presence @get@ operation. It will throw an error if the attach fails.
 ** @(CHA-PR6d)@ @[Testable]@ If the room status is @Attached@, then the @get@ call will invoke the underlying @presence.enter()@ call.
 ** @(CHA-PR6e)@ @[Testable]@ If the room status is @Detached@, an @ErrorInfo@ with code 40000, explaining that attach must be called first, will be thrown.
@@ -313,11 +327,11 @@ Typing Indicators allow chat room users to indicate to others that they are typi
 
 * @(CHA-T1)@ Typing Indicators for a Room is exposed on a dedicated Realtime channel. These channels use the format @<roomId>::$chat::$typingIndicators@. For example, if your room id is @my-room@ then the typing channel will be @my-room::$chat::$typingIndicators@.
 * @(CHA-T2)@ @[Testable]@ Users may retrieve a list of the currently typing client IDs. The behaviour depends on the current room status, as presence operations in a Realtime Client cause implicit attaches.
-** @(CHA-T2b)@ If the room status is @Initialized@ or @Initializing@, behaviour depends on whether attach has been called.
-*** @(CHA-T2b1)@ @[Testable]@ If the attach has been called, then the @get@ call will wait for the attach operation to succeed and then call the underlying presence @get@ operation. It will throw an error if the attach fails.
-*** @(CHA-T2b2)@ @[Testable]@ If the attach has not been called, then the @get@ call will throw an error.
-** @(CHA-T2c)@ @[Testable]@ If the room status is @Attaching@, then the @get@ call will wait for the attach operation to succeed and then call the underlying presence @get@ operation. It will throw an error if the attach fails.
-** @(CHA-T2d)@ @[Testable]@ If the room status is @Attached@, then the @get@ call will invoke the underlying @presence.enter()@ call.
+** @(CHA-T2b)@ This specification point has been removed.
+*** @(CHA-T2b1)@ This specification point has been removed.
+*** @(CHA-T2b2)@ This specification point has been removed.
+** @(CHA-T2c)@ @[Testable]@ If the room status is @ATTACHING@, then the @get@ call shall wait for the attach operation to succeed and then call the underlying presence @get@ operation. It must throw an error if the attach fails.
+** @(CHA-T2d)@ @[Testable]@ If the room status is @Attached@, then the @get@ call shall invoke the underlying @presence.enter()@ call.
 ** @(CHA-T2e)@ @[Testable]@ If the room status is @Detached@, an @ErrorInfo@ with code 40000, explaining that attach must be called first, will be thrown.
 ** @(CHA-T2f)@ @[Testable]@ For any other room status, an @ErrorInfo@ with code 40000 will be thrown.
 * @(CHA-T3)@ @[Testable]@ Users may configure a timeout interval for when they are typing. This configuration is provided as part of the @RoomOptions@ @typing.timeoutMs@ property, or idiomatic equivalent. The default is 5000ms.
@@ -658,4 +672,8 @@ For non-chat-specific codes, the status code for the error should align with the
   // An unknown error has happened in the room lifecycle.
   // To be accompanied with status code 500.
   RoomLifecycleError = 102105
+
+  // Room was released before the operation could complete.
+  // To be accompanied with status code 400.
+  RoomReleasedBeforeOperationCompleted = 102106,
 </pre>