chat: room lifecycle specification #200

AndyTWF · 2024-08-05T16:52:42Z

Adds chat room lifecycle feature specification.
Also adds feature specs for presence, messages and room reactions

textile/chat-features.textile

lawrence-forooghian · 2024-08-27T15:55:06Z

I’ve started implementing this spec in the Swift SDK. In order to be sure that this spec is sufficiently detailed and unambigious, I’ve made the deliberate decision not to consult the JS implementation. I’ll post feedback here as it comes up 🙂

textile/chat-features.textile

lawrence-forooghian · 2024-08-28T08:23:59Z

textile/chat-features.textile

+** @(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-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.


Was it a conscious decision to not describe the API of the SDK in terms of signatures / types (e.g. the way that we do in the main spec, which also has the IDL)?

The IDL we have for the core SDKs is quite java-centric and in that sense may not be the most idiomatic approach for other ecosystems, so I tried to write the spec in a way that describes the intended interactions and behaviour, rather than prescribe an exact implementation.

Is it worth a note somewhere in the spec to treat the JS implementation as a reference implementation and explain the intention?

I believe having IDL for chat-SDK will be super helpful.
Almost all of the languages these days are encouraging use of types.
So, having language-agnostic types will surely help.

textile/chat-features.textile

lawrence-forooghian · 2024-08-28T08:28:15Z

textile/chat-features.textile

+
+* @(CHA-RL1)@ A room must be explicitly @ATTACHED@ to.
+** @(CHA-RL1a)@ @[Testable]@ If the room is already in the @ATTACHED@ status, then this operation is no-op.
+** @(CHA-RL1b)@ @[Testable]@ If the room is in the @RELEASING@ status, the operation shall be rejected with error code @102102@.


It's not clear what rejected with error code @102102@ means here. (I know from looking at the JS interface that it reuses the ErrorInfo type from the core SDK, but it would be good to make that explicit.)

Also, if the intention is to reuse ErrorInfo, then all of the places where this spec says to throw such an error should also specify the statusCode.

I can't see where the status codes are specified; it seems like you've only added one for CHA-RL1h2. It seems like there should be status codes specified for:

everything in the "Chat-specific Error Codes" section

all the places where we specify a numerical error code directly in the spec point (e.g. CHA-RC1c, CHA-RC2b, CHA-RL1b, CHA-RL1c).

textile/chat-features.textile

lawrence-forooghian · 2024-08-28T08:34:53Z

textile/chat-features.textile

+** @(CHA-RL1f)@ @[Testable]@ The underlying @contributors@ will have their Realtime Channels attached in sequence.
+** @(CHA-RL1g)@ When all @contributors@ Realtime Channels successfully attach, the operation is now complete and the room is considered attached.
+*** @(CHA-RL1g1)@ @[Testable]@ The room status shall be transitioned to @ATTACHED@.
+*** @(CHA-RL1g2)@ @[Testable]@ Any contributors to room that have a pending discontinuity event against them, must be notified of this fact, using the error that caused the original discontinuity.


Is there a spec point that describes what this means? (I might have not got there yet.) If so, it would be good to have a reference to it.

It sorta felt that it didn't fit into a spec point, but I've added some discussion/blurb at the head of the lifecycle section about it!

lawrence-forooghian · 2024-08-28T08:35:27Z

textile/chat-features.textile

+** @(CHA-RL1g)@ When all @contributors@ Realtime Channels successfully attach, the operation is now complete and the room is considered attached.
+*** @(CHA-RL1g1)@ @[Testable]@ The room status shall be transitioned to @ATTACHED@.
+*** @(CHA-RL1g2)@ @[Testable]@ Any contributors to room that have a pending discontinuity event against them, must be notified of this fact, using the error that caused the original discontinuity.
+*** @(CHA-RL1g3)@ @[Testable]@ Any transient disconnect timeouts shall be cleared.


Same question re whether there is a spec reference that could be added here.

Added some guidance / rationale text!

textile/chat-features.textile

lawrence-forooghian · 2024-08-28T08:52:16Z

textile/chat-features.textile

+*** @(CHA-RL1g3)@ @[Testable]@ Any transient disconnect timeouts shall be cleared.
+** @(CHA-RL1h)@ If a one of the @contributors@ Realtime Channels fails to attach, then the operation has failed and must be rolled back.
+*** @(CHA-RL1h1)@ @[Testable]@ The @attach@ call must throw an @ErrorInfo@. The code for this error is determined by the feature that failed (see the @ErrorCodes@ enum in the JS SDK for more information).
+*** @(CHA-RL1h2)@ @[Testable]@ If the underlying Realtime Channel entered the @SUSPENDED@ state, then the room status will transition to @SUSPENDED@, using the Realtime Channel error as the @cause@ field of the @ErrorInfo@.


This could be more explicit — does it mean "if the call to contributor.attach() fails, then check the contributor’s state. If it's SUSPENDED, then transition to SUSPENDED, using the contributor’s errorReason property as the cause field of the error of the emitted status change"?

Also, what code and statusCode should this error have?

Clarified on all points

"the Realtime Channel error" is still a bit unclear — it could mean the error that the contributor attach() call failed with. Can we explicitly say to use the contributor’s errorReason?

Sorry, I’m not sure what you’ve changed — CHA-RL1h2 doesn't seem to have changed from bcb7390 to b4a495e?

Is it meant to be using the same language as CHA-RL1h4 now uses — that is, to use the error thrown by channel attach()?

textile/chat-features.textile

lawrence-forooghian · 2024-09-25T18:53:00Z

textile/chat-features.textile

+*** @(CHA-RL4b4)@ @[Testable]@ If a channel lifecycle operation is in progress, the channel state is @ATTACHED@, the @resume@ flag is false but the contributor has never previouly reached the state of @ATTACHED@, then no action is taken.
+*** @(CHA-RL4b5)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @FAILED@, then the room status shall be transitioned to @FAILED@, using the @reason@ for the channel state change as the @error@ for the room status change. All @transient disconnect timeouts@ are cancelled and any non-detached contributors are detached.
+*** @(CHA-RL4b6)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @ATTACHING@ and a transient disconnect timeout exists for the contributor, then no action is needed.
+*** @(CHA-RL4b7)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @ATTACHING@ and no transient disconnect timeout exists for the contributor, then a timeout is created with a 5 second limit. Upon timeout, the room status is transitioned to @ATTACHING@, using the @reason@ from the initial channel state change as the error for the transition.


Suggested change

*** @(CHA-RL4b7)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @ATTACHING@ and no transient disconnect timeout exists for the contributor, then a timeout is created with a 5 second limit. Upon timeout, the room status is transitioned to @ATTACHING@, using the @reason@ from the initial channel state change as the error for the transition.

*** @(CHA-RL4b7)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @ATTACHING@ and no transient disconnect timeout exists for the contributor, then a transient disconnect timeout with a 5 second limit is created for the contributor. Upon timeout, the room status is transitioned to @ATTACHING@, using the @reason@ from the initial channel state change as the error for the transition.

lawrence-forooghian · 2024-09-26T13:48:29Z

textile/chat-features.textile

+*** @(CHA-RL4a3)@ @[Testable]@ If a room lifecycle operation is in progress, then a pending discontinuity event shall be recorded for this contributor. The @ErrorInfo@ associated with the discontinuity shall be the @reason@ for the underlying channel state change. The event will be notified to the contributor at a later point, as noted in this specification.
+*** @(CHA-RL4a4)@ @[Testable]@ If a room lifecycle operation is not in progress, then a discontinuity event will immediately be emitted to the contributor. The @ErrorInfo@ associated with the discontinuity shall be the @reason@ for the underlying channel state change.
+** @(CHA-RL4b)@ The state monitor must handle other channel state events.
+*** @(CHA-RL4b1)@ @[Testable]@ If a channel lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resume@ flag is false, @and@ the particular contributor has been attached previously, then a pending discontinuity event will be recorded for the contributor. The error associated with this event shall be the @reason@ for the channel state change.


Should all of the mentions of a "channel lifecycle operation" be "room lifecycle operation"?

lawrence-forooghian · 2024-09-26T14:37:36Z

textile/chat-features.textile

+*** @(CHA-RL4a2)@ @[Testable]@ If the given contributor has not yet successfully managed to attach its Realtime Channel, then no action should be taken.
+*** @(CHA-RL4a3)@ @[Testable]@ If a room lifecycle operation is in progress, then a pending discontinuity event shall be recorded for this contributor. The @ErrorInfo@ associated with the discontinuity shall be the @reason@ for the underlying channel state change. The event will be notified to the contributor at a later point, as noted in this specification.
+*** @(CHA-RL4a4)@ @[Testable]@ If a room lifecycle operation is not in progress, then a discontinuity event will immediately be emitted to the contributor. The @ErrorInfo@ associated with the discontinuity shall be the @reason@ for the underlying channel state change.
+** @(CHA-RL4b)@ The state monitor must handle other channel state events.


Suggested change

** @(CHA-RL4b)@ The state monitor must handle other channel state events.

** @(CHA-RL4b)@ The state monitor must handle non-@UPDATE@ channel state events.

lawrence-forooghian · 2024-09-26T14:42:29Z

textile/chat-features.textile

+*** @(CHA-RL4a4)@ @[Testable]@ If a room lifecycle operation is not in progress, then a discontinuity event will immediately be emitted to the contributor. The @ErrorInfo@ associated with the discontinuity shall be the @reason@ for the underlying channel state change.
+** @(CHA-RL4b)@ The state monitor must handle other channel state events.
+*** @(CHA-RL4b1)@ @[Testable]@ If a channel lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resume@ flag is false, @and@ the particular contributor has been attached previously, then a pending discontinuity event will be recorded for the contributor. The error associated with this event shall be the @reason@ for the channel state change.
+*** @(CHA-RL4b2)@ @[Testable]@ If a channel lifecycle operation is in progress and the new channel state is not @ATTACHED@, then no action is taken.


This spec point seems redundant given that all of the spec points in CHA-RL4b which specify an action to be taken are already predicated on there being or not being a room lifecycle operation in progress.

If the intention of this spec point is to explain the overall principle guiding those other spec points, then perhaps add it as a "here's the principle, which is implemented by the following spec points" part of the introductory CHA-RL4b.

lawrence-forooghian · 2024-09-26T15:57:29Z

textile/chat-features.textile

+** @(CHA-RL4b)@ The state monitor must handle other channel state events.
+*** @(CHA-RL4b1)@ @[Testable]@ If a channel lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resume@ flag is false, @and@ the particular contributor has been attached previously, then a pending discontinuity event will be recorded for the contributor. The error associated with this event shall be the @reason@ for the channel state change.
+*** @(CHA-RL4b2)@ @[Testable]@ If a channel lifecycle operation is in progress and the new channel state is not @ATTACHED@, then no action is taken.
+*** @(CHA-RL4b3)@ @[Testable]@ If a channel lifecycle operation is in progress, the channel state is @ATTACHED@ and the @resume@ flag is true, then no action is taken.


My interpretation of CHA-RL4b3 and CHA-RL4b4 is "if the conditions specified by CHA-RL4b1 aren’t met, then don’t perform the action described in CHA-4L4b1". This feels redundant. What was the motivation for these spec points?

lawrence-forooghian · 2024-09-26T16:09:39Z

textile/chat-features.textile

+
+* @(CHA-RL4)@ A room must monitor the state of its @contributors@ Realtime Channels and act upon any changes.
+** @(CHA-RL4a)@ The state monitor must handle @UPDATE@ events from each contributors underlying Realtime Channel
+*** @(CHA-RL4a1)@ @[Testable]@ If the @resume@ flag of the update is set to @true@, then no action should be taken.


In CHA-RL4a1 and CHA-RL4a2, is there a way to clarify the language of "no action should be taken", which I’ve taken as meaning "the behaviour described in CHA-RL4a3 and CHA-RL4a4 should not be performed"?

lawrence-forooghian · 2024-09-26T16:52:05Z

textile/chat-features.textile

+*** @(CHA-RL4b3)@ @[Testable]@ If a channel lifecycle operation is in progress, the channel state is @ATTACHED@ and the @resume@ flag is true, then no action is taken.
+*** @(CHA-RL4b4)@ @[Testable]@ If a channel lifecycle operation is in progress, the channel state is @ATTACHED@, the @resume@ flag is false but the contributor has never previouly reached the state of @ATTACHED@, then no action is taken.
+*** @(CHA-RL4b5)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @FAILED@, then the room status shall be transitioned to @FAILED@, using the @reason@ for the channel state change as the @error@ for the room status change. All @transient disconnect timeouts@ are cancelled and any non-detached contributors are detached.
+*** @(CHA-RL4b6)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @ATTACHING@ and a transient disconnect timeout exists for the contributor, then no action is needed.


Similar question to #200 (comment) (i.e. my interpretation of CHA-RL4b6 is "if the conditions specified by CHA-RL4b7 aren’t met, then don’t perform the action described in CHA-4L4b7"; is this a necessary spec point)?

lawrence-forooghian · 2024-09-26T17:15:22Z

textile/chat-features.textile

+*** @(CHA-RL4b2)@ @[Testable]@ If a channel lifecycle operation is in progress and the new channel state is not @ATTACHED@, then no action is taken.
+*** @(CHA-RL4b3)@ @[Testable]@ If a channel lifecycle operation is in progress, the channel state is @ATTACHED@ and the @resume@ flag is true, then no action is taken.
+*** @(CHA-RL4b4)@ @[Testable]@ If a channel lifecycle operation is in progress, the channel state is @ATTACHED@, the @resume@ flag is false but the contributor has never previouly reached the state of @ATTACHED@, then no action is taken.
+*** @(CHA-RL4b5)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @FAILED@, then the room status shall be transitioned to @FAILED@, using the @reason@ for the channel state change as the @error@ for the room status change. All @transient disconnect timeouts@ are cancelled and any non-detached contributors are detached.


any non-detached contributors are detached

any rules about how this should be done ("in sequence" as some other spec points say, or can it be concurrent?)

what happens if a contributor detach() call fails?

This is based on [1] at b4a495e. It’s generated some questions, which I’ve asked on that PR. Note that the spec has been through a few revisions since I started implementing this; I’ve tried to keep everything in sync but some older stuff might still be accidentally there. I’ve implemented most of the specified behaviour for the ATTACH, DETACH, and RELEASE operations. I have not yet implemented RETRY since it’s quite different to those three and I wanted to get eyes on this first chunk of work; have created #51 for implementing it. Of the operations that I have implemented, I have not implemented the following (this is accurately reflected by the @SPEC… tags in the tests): - Lifecycle behaviour that relates to another ongoing operation (created #52) - Lifecycle behaviour relating to “transient disconnect timeouts” (created #48) - Lifecycle behaviour that occurs “asynchronously” outside an operation (created #50) - CHA-RL1g2, which refers to emitting “discontinuity events” which are a concept not yet implemented; this will come in #53. The room lifecycle manager introduced by this commit is currently a standalone object, which is not integrated with the rest of the SDK. I’ve created #47 for doing this integration work. The @SPEC… tags are based on the on the JS rules [2] @ 8c9ce8b, but I camel-cased them and also decided that: - if a test doesn't relate to a spec point, it doesn't need any markers - there should be a way to know that a spec point is tested across multiple tests - there should be a way of marking a spec point as implemented but not tested (so that can show up differently in reporting; important given that we’re also going to use this report as a to-do list of what still needs to be implemented) Part of #28. [1] ably/specification#200 [2] https://github.com/ably/ably-js/blob/main/CONTRIBUTING.md#tests-alignment-with-the-ably-features-specification

lawrence-forooghian · 2024-09-30T23:29:05Z

textile/chat-features.textile

+** @(CHA-RL1f)@ @[Testable]@ The underlying @contributors@ will have their Realtime Channels attached in sequence - an attach call must complete successfully before the next is started.
+** @(CHA-RL1g)@ When all @contributors@ Realtime Channels successfully attach (the calls to @attach()@ complete successfully), the operation is now complete and the room is considered attached.
+*** @(CHA-RL1g1)@ @[Testable]@ The room status shall be transitioned to @ATTACHED@.
+*** @(CHA-RL1g2)@ @[Testable]@ Any contributors to room that have a pending discontinuity event against them, must be notified of this fact, using the error that caused the original discontinuity.


I assume that the pending discontinuities then get cleared, so as to not be emitted again?

lawrence-forooghian · 2024-09-30T23:35:27Z

textile/chat-features.textile

+** @(CHA-RL4a)@ The state monitor must handle @UPDATE@ events from each contributors underlying Realtime Channel
+*** @(CHA-RL4a1)@ @[Testable]@ If the @resume@ flag of the update is set to @true@, then no action should be taken.
+*** @(CHA-RL4a2)@ @[Testable]@ If the given contributor has not yet successfully managed to attach its Realtime Channel, then no action should be taken.
+*** @(CHA-RL4a3)@ @[Testable]@ If a room lifecycle operation is in progress, then a pending discontinuity event shall be recorded for this contributor. The @ErrorInfo@ associated with the discontinuity shall be the @reason@ for the underlying channel state change. The event will be notified to the contributor at a later point, as noted in this specification.


Is it possible for a given contributor to have more than one pending discontinuity event recorded against it at a given time, or if there is already one does it get replaced?

lawrence-forooghian · 2024-09-30T23:39:18Z

textile/chat-features.textile

+** @(CHA-RL5d)@ Once all channels have been detached, the room waits until the original channel that caused the retry loop naturally enters the @ATTACHED@ state.
+** @(CHA-RL5e)@ @[Testable]@ If the channel state becomes @FAILED@, then the room status is transitioned to @FAILED@ and the retry loop stops.
+** @(CHA-RL5f)@ @[Testable]@ If the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new attachment cycle.
+*** @(CHA-RL5f1)@ @[Testable]@ If the attachment cycle succeeds, then the room is transitioned to @ATTACHED@ and any discontinuity errors are broadcast to contributors.


Same question as https://github.com/ably/specification/pull/200/files#r1781917231:

I assume that the pending discontinuities then get cleared, so as to not be emitted again?

This is based on [1] at b4a495e. It’s generated some questions, which I’ve asked on that PR. Note that the spec has been through a few revisions since I started implementing this; I’ve tried to keep everything in sync but some older stuff might still be accidentally there. I’ve implemented most of the specified behaviour for the ATTACH, DETACH, and RELEASE operations. I have not yet implemented RETRY since it’s quite different to those three and I wanted to get eyes on this first chunk of work; have created #51 for implementing it. Of the operations that I have implemented, I have not implemented the following (this is accurately reflected by the @SPEC… tags in the tests): - Lifecycle behaviour that relates to another ongoing operation (created #52) - Lifecycle behaviour relating to “transient disconnect timeouts” (created #48) - Lifecycle behaviour that occurs “asynchronously” outside an operation (created #50) - CHA-RL1g2, which refers to emitting “discontinuity events” which are a concept not yet implemented; this will come in #53. The room lifecycle manager introduced by this commit is currently a standalone object, which is not integrated with the rest of the SDK. I’ve created #47 for doing this integration work. The @SPEC… tags are based on the on the JS rules [2] @ 8c9ce8b, but I camel-cased them and also decided that: - if a test doesn't relate to a spec point, it doesn't need any markers - there should be a way to know that a spec point is tested across multiple tests - there should be a way of marking a spec point as implemented but not tested (so that can show up differently in reporting; important given that we’re also going to use this report as a to-do list of what still needs to be implemented) Part of #28. [1] ably/specification#200 [2] https://github.com/ably/ably-js/blob/main/CONTRIBUTING.md#tests-alignment-with-the-ably-features-specification

lawrence-forooghian · 2024-10-01T21:16:39Z

textile/chat-features.textile

+
+  // Unable to perform operation;
+
+  // Cannot perform operation because the room is in a failed state.


Given your comment in another issue about wanting to reserve the term "state" for a larger, composite state, would it be more appropriate that the error name and message refer to "status" instead of "state"?

Actually, looking at this, should this be called RoomIsFailed for consistency with RoomIsReleasing and RoomIsReleased? (and question about error messages stands)

build: clean output directory on build

a6ffe20

github-actions bot temporarily deployed to staging/pull/200 August 5, 2024 16:53 Inactive

AndyTWF force-pushed the chat-lifecycle branch from 8c569ea to aa7455d Compare August 14, 2024 07:54

github-actions bot temporarily deployed to staging/pull/200 August 14, 2024 07:55 Inactive

AndyTWF changed the title ~~wip: chat features~~ chat: room lifecycle specification Aug 14, 2024

AndyTWF requested review from vladvelici and splindsay-92 August 14, 2024 07:55

splindsay-92 reviewed Aug 14, 2024

View reviewed changes