chat: add CHA-RL9 to explain "attaching piggyback"

Closes #228

textile/chat-features.textile

@@ -144,6 +144,10 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations
 *** @(CHA-RL7a1)@ The @RETRY@ operation - an internal process.
 *** @(CHA-RL7a2)@ The @RELEASE@ operation.
 *** @(CHA-RL7a3)@ The @ATTACH@ and @DETACH@ operations have equal precedence.
+* @(CHA-RL9)@ Many operations in the Chat SDK will still attempt to proceed if the room is in an @ATTACHING@ status. However, their ability to proceed will depend on the subsequent status that the room takes. This specification point is defined here to avoid unnecessary repetition. It is testable via the points that refer to it.
+** @(CHA-RL9a)@ When the room status is @ATTACHING@ at the point of operation commencement, the caller will subscribe a one-time listener to the room status.
+** @(CHA-RL9b)@ If the next room status received by the caller is @ATTACHED@, the operation shall proceed as normal.
+** @(CHA-RL9c)@ If the next room status received is any other value, the operation must throw an error. The @ErrorInfo@ shall have the @RoomInInvalidState@ error code from the "chat-specific error codes":#error-codes, with a status code of @500@. The @cause@ field must contain any error associated with the room status change, if present.
 
 h4(#rooms-lifecycle-monitoring). Room Lifecycle Monitoring
 
@@ -284,7 +288,7 @@ Presence allows chat room users to indicate to others that they're online, as we
 ** @(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-PR3d)@ @[Testable]@ If the room status is @Attaching@, then the operation shall enter a @CHA-RL9@ pending room status operation. If this succeeds (i.e the room becomes @ATTACHED@), the library must invoke the underlying @presence.enter()@ call.
 ** @(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.
@@ -294,7 +298,7 @@ Presence allows chat room users to indicate to others that they're online, as we
 ** @(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-PR10d)@ @[Testable]@ If the room status is @Attaching@, then the operation shall enter a @CHA-RL9@ pending room status operation. If this succeeds (i.e the room becomes @ATTACHED@), the library must invoke the underlying @presence.update()@ call.
 ** @(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.
 ** @(CHA-PR10g)@ @[Testable]@ For any other room status, an @ErrorInfo@ with code 40000 will be thrown.
@@ -306,8 +310,8 @@ Presence allows chat room users to indicate to others that they're online, as we
 ** @(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-PR6c)@ @[Testable]@ If the room status is @Attaching@, then the operation shall enter a @CHA-RL9@ pending room status operation. If this succeeds (i.e the room becomes @ATTACHED@), the library must invoke the underlying @presence.get()@ call.
+** @(CHA-PR6d)@ @[Testable]@ If the room status is @Attached@, then the @get@ call will invoke the underlying @presence.get()@ 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.
 ** @(CHA-PR6f)@ @[Testable]@ For any other room status, an @ErrorInfo@ with code 40000 will be thrown.
 * @(CHA-PR7)@ Users may subscribe to presence events.
@@ -330,7 +334,7 @@ Typing Indicators allow chat room users to indicate to others that they are typi
 ** @(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-T2c)@ @[Testable]@ If the room status is @ATTACHING@, then the operation shall enter a @CHA-RL9@ pending room status operation. If this succeeds (i.e the room becomes @ATTACHED@), the library must invoke the underlying @presence.get()@ call.
 ** @(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.
@@ -675,5 +679,8 @@ For non-chat-specific codes, the status code for the error should align with the
 
   // Room was released before the operation could complete.
   // To be accompanied with status code 400.
-  RoomReleasedBeforeOperationCompleted = 102106,
+  RoomReleasedBeforeOperationCompleted = 102106
+
+  // The room operation failed because the room was in an invalid state
+  RoomInInvalidState = 102107
 </pre>