Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[chat-spec] Make user triggered ops deterministic in disconnected state #267

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

[chat-spec] Make user triggered ops deterministic in disconnected state #267

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1301ab1
Marked CHA-RL9 as deprecated, replaced it with CHA-RL11
sacOO7 Jan 14, 2025
0d893b2
Replaced existing duplicate usage of spec CHA-RL9 with CHA-RL11
sacOO7 Jan 14, 2025
88acfbb
Added missing spec references for CHA-RL11, related to realtime room ops
sacOO7 Jan 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 46 additions & 30 deletions textile/chat-features.textile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,10 +174,19 @@ 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 primarily testable via the points that refer to it.
** @(CHA-RL9a)@ @[Testable]@ 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)@ @[Testable]@ If the next room status received by the caller is @ATTACHED@, the operation shall proceed as normal.
** @(CHA-RL9c)@ @[Testable]@ 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.
* @(CHA-RL9)@ This specification point has been removed. It was superseded by @CHA-RL11@.
** @(CHA-RL9a)@ This specification point has been removed.
** @(CHA-RL9b)@ This specification point has been removed.
** @(CHA-RL9c)@ This specification point has been removed.
* @(CHA-RL11)@ Any room operation triggered using public API over a realtime channel will have it's result dependent on the given RoomStatus. This specification point is defined here to avoid unnecessary repetition. It is primarily testable via the points that refer to it.
** @(CHA-RL11a)@ @[Testable]@ When the room status is @ATTACHED@ at the point of operation commencement,
*** @(CHA-RL11a1)@ @[Testable]@ If underlying realtime connection state is not @CONNECTED@, an @ErrorInfo@ using the @RoomInInvalidState@ error code from the "chat-specific error codes":#error-codes with a status code of @400@ must be thrown. The message shall explain that the realtime connection is not active.
*** @(CHA-RL11a2)@ @[Testable]@ At this point, connection state is @CONNECTED@ and room status is @ATTACHED@, so operation should proceed as normal.
** @(CHA-RL11b)@ @[Testable]@ Operation will still attempt to proceed if the room is in an @ATTACHING@ status. However, it's ability to proceed will depend on the subsequent status that the room takes.
*** @(CHA-RL11b1)@ @[Testable]@ 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-RL11b2)@ @[Testable]@ If the next room status received by the caller is @ATTACHED@, the operation shall proceed as normal.
*** @(CHA-RL11b3)@ @[Testable]@ 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 message shall explain the given room status with error as per @CHA-RS2@.
** @(CHA-RL11c)@ @[Testable]@ If the room status is anything other than @Attached@ or @Attaching@, an @ErrorInfo@ using the @RoomInInvalidState@ error code from the "chat-specific error codes":#error-codes with a status code of @400@ must be thrown. The message shall explain the given room status with error as per @CHA-RS2@.
* @(CHA-RL10)@ @[Testable]@ When a specification point refers to operations on the underlying realtime channels (i.e. calls to attach and delete) being performed in sequence, the precedence of contributors must follow the order specified by @CHA-RC2e@.

h4(#rooms-lifecycle-monitoring). Room Lifecycle Monitoring
Expand Down Expand Up @@ -356,39 +365,43 @@ 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-PR3b)@ This specification point has been removed.
** @(CHA-PR3c)@ This specification point has been removed.
*** @(CHA-PR3c1) 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 operation shall invoke a @CHA-RL9@ pending room status operation and wait for it to complete. If this operation fails, then the error from @CHA-RL9@ must be raised. If this succeeds (i.e the room becomes @ATTACHED@), the library must invoke the underlying @presence.enter()@ call.
** @(CHA-PR3h)@ @[Testable]@ If the room status is anything other than @Attached@ or @Attaching@, an @ErrorInfo@ using the @RoomInInvalidState@ error code from the "chat-specific error codes":#error-codes with a status code of @400@ must be thrown. The message shall explain that attach must be called first.
** @(CHA-PR3e)@ @[Testable]@ If the room status is @Attached@, then the @enter@ call will invoke the underlying @presence.enter()@ call.
** @(CHA-PR3f)@ This specification point has been removed. It was superseded by @CHA-PR3h@.
** @(CHA-PR3g)@ This specification point has been removed. It was superseded by @CHA-PR3h@.
** @(CHA-PR3d)@ This specification point has been removed. It was superseded by @CHA-PR3i@.
** @(CHA-PR3h)@ This specification point has been removed. It was superseded by @CHA-PR3i@.
** @(CHA-PR3e)@ This specification point has been removed. It was superseded by @CHA-PR3i@.
** @(CHA-PR3f)@ This specification point has been removed.
** @(CHA-PR3g)@ This specification point has been removed.
** @(CHA-PR3i)@ Underlying @presence.enter()@ call should be invoked based on the given room status as per @CHA-RL11@.
* @(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-PR10b)@ This specification point has been removed.
** @(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 operation shall invoke a @CHA-RL9@ pending room status operation and wait for it to complete. If this operation fails, then the error from @CHA-RL9@ must be raised. If this succeeds (i.e the room becomes @ATTACHED@), the library must invoke the underlying @presence.update()@ call.
** @(CHA-PR10h)@ @[Testable]@ If the room status is anything other than @Attached@ or @Attaching@, an @ErrorInfo@ using the @RoomInInvalidState@ error code from the "chat-specific error codes":#error-codes with a status code of @400@ must be thrown. The message shall explain that attach must be called first.
** @(CHA-PR10e)@ @[Testable]@ If the room status is @Attached@, then the @update@ call will invoke the underlying @presence.enter()@ call.
** @(CHA-PR10f)@ This specification point has been removed. It was superseded by @CHA-PR10h@.
** @(CHA-PR10g)@ This specification point has been removed. It was superseded by @CHA-PR10h@.
** @(CHA-PR10d)@ This specification point has been removed. It was superseded by @CHA-PR10i@.
** @(CHA-PR10h)@ This specification point has been removed. It was superseded by @CHA-PR10i@.
** @(CHA-PR10e)@ This specification point has been removed. It was superseded by @CHA-PR10i@.
** @(CHA-PR10f)@ This specification point has been removed.
** @(CHA-PR10g)@ This specification point has been removed.
** @(CHA-PR10i)@ Underlying @presence.update()@ call should be invoked based on the given room status as per @CHA-RL11@.
* @(CHA-PR4)@ Users may leave presence.
** @(CHA-PR4a)@ @[Testable]@ Users may choose to leave presence, which results in them being removed from the Realtime presence set.
*** @(CHA-PR4a1)@ @[Testable]@ Underlying @presence.leave()@ call should be invoked based on the given room status as per @CHA-RL11@.
* @(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-PR6a)@ This specification point has been removed.
** @(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 operation shall invoke a @CHA-RL9@ pending room status operation and wait for it to complete. If this operation fails, then the error from @CHA-RL9@ must be raised. If this succeeds (i.e the room becomes @ATTACHED@), the library must invoke the underlying @presence.get()@ call.
** @(CHA-PR6h)@ @[Testable]@ If the room status is anything other than @Attached@ or @Attaching@, an @ErrorInfo@ using the @RoomInInvalidState@ error code from the "chat-specific error codes":#error-codes with a status code of @400@ must be thrown. The message shall explain that attach must be called first.
** @(CHA-PR6d)@ @[Testable]@ If the room status is @Attached@, then the @get@ call will invoke the underlying @presence.get()@ call.
** @(CHA-PR6e)@ This specification point has been removed. It was superseded by @CHA-PR6h@.
** @(CHA-PR6f)@ This specification point has been removed. It was superseded by @CHA-PR6h@.
** @(CHA-PR6c)@ This specification point has been removed. It was superseded by @CHA-PR6g@.
** @(CHA-PR6h)@ This specification point has been removed. It was superseded by @CHA-PR6g@.
** @(CHA-PR6d)@ This specification point has been removed. It was superseded by @CHA-PR6g@.
** @(CHA-PR6e)@ This specification point has been removed.
** @(CHA-PR6f)@ This specification point has been removed.
** @(CHA-PR6g)@ Underlying @presence.get()@ call should be invoked based on the given room status as per @CHA-RL11@.
* @(CHA-PR7)@ Users may subscribe to presence events.
** @(CHA-PR7a)@ @[Testable]@ Users may provide a listener to subscribe to all "presence events":#chat-structs-presence-event in a room.
** @(CHA-PR7b)@ @[Testable]@ Users may provide a listener and a list of selected "presence events":#chat-structs-presence-event, to subscribe to just those events in a room.
Expand All @@ -409,20 +422,23 @@ 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 operation shall invoke a @CHA-RL9@ pending room status operation and wait for it to complete. If this operation fails, then the error from @CHA-RL9@ must be raised. If this succeeds (i.e the room becomes @ATTACHED@), the library must invoke the underlying @presence.get()@ call.
** @(CHA-T2g)@ @[Testable]@ If the room status is anything other than @Attached@ or @Attaching@, an @ErrorInfo@ using the @RoomInInvalidState@ error code from the "chat-specific error codes":#error-codes with a status code of @400@ must be thrown. The message shall explain that attach must be called first.
** @(CHA-T2d)@ @[Testable]@ If the room status is @Attached@, then the @get@ call shall invoke the underlying @presence.enter()@ call.
** @(CHA-T2e)@ This specification point has been removed. It was superseded by @CHA-T2g@.
** @(CHA-T2f)@ This specification point has been removed. It was superseded by @CHA-T2g@.
** @(CHA-T2c)@ This specification point has been removed. It was superseded by @CHA-T2h@.
** @(CHA-T2g)@ This specification point has been removed. It was superseded by @CHA-T2h@.
** @(CHA-T2d)@ This specification point has been removed. It was superseded by @CHA-T2h@.
** @(CHA-T2e)@ This specification point has been removed.
** @(CHA-T2f)@ This specification point has been removed.
** @(CHA-T2h)@ Underlying @presence.get()@ call should be invoked based on the given room status as per @CHA-RL11@.
* @(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.
* @(CHA-T4)@ Users may indicate that they have started typing.
** @(CHA-T4a)@ @[Testable]@ If typing is not already in progress, per explicit cancellation or the timeout interval in (@CHA-T3@), then a new typing session is started.
*** @(CHA-T4a1)@ @[Testable]@ When a typing session is started, the client is entered into presence on the typing channel.
*** @(CHA-T4a3)@ @[Testable]@ When a typing session is started, underlying @presence.enter()@ call should be invoked based on the given room status as per @CHA-RL11@.
*** @(CHA-T4a1)@ @[Testable]@ This specification point has been removed. It was superseded by @CHA-T4a3@.
*** @(CHA-T4a2)@ @[Testable]@ When a typing session is started, a timeout is set according to the @CHA-T3@ timeout interval. When this timeout expires, the typing session is automatically ended by leaving presence.
** @(CHA-T4b)@ @[Testable]@ If typing is already in progress, the @CHA-T3@ timeout is extended to be @timeoutMs@ from now.
* @(CHA-T5)@ Users may indicate that they have stopped typing.
** @(CHA-T5a)@ @[Testable]@ If typing is not in progress, this operation is no-op.
** @(CHA-T5b)@ @[Testable]@ If typing is in progress, he @CHA-T3@ timeout is cancelled. The client then leaves presence.
** @(CHA-T5c)@ @[Testable]@ If typing is in progress, underlying @presence.leave()@ call should be invoked based on the given room status as per @CHA-RL11@ and @CHA-T3@ timeout is cancelled.
** @(CHA-T5b)@ @[Testable]@ This specification point has been removed. It was superseded by @CHA-T5c@.
* @(CHA-T6)@ Users may subscribe to typing events - updates to a set of clientIDs that are typing. This operation, like all subscription operations, has no side-effects in relation to room lifecycle.
** @(CHA-T6a)@ @[Testable]@ Users may provide a listener to subscribe to "typing events":#chat-structs-typing-event in a room.
** @(CHA-T6b)@ @[Testable]@ A subscription to typing may be removed, after which it shall receive no further events.
Expand Down
Loading