From deeaf0047661204f7f0d909d571233bab1257909 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 5 Aug 2024 16:46:50 +0100 Subject: [PATCH 01/73] build: clean output directory on build --- package.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index c16464d9c..758ae314a 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,8 @@ "name": "@ably/specification-build", "version": "1.0.0", "scripts": { - "build": "npm-run-all build:generate build:tailwind", + "clean": "rm -rf ./output", + "build": "npm-run-all clean build:generate build:tailwind", "build:generate": "./scripts/build", "build:tailwind": "tailwindcss -i ./templates/main.css -o ./output/tailwind.css --minify", "lint": "npm-run-all format:*:check", From da3846b2c8bdc0eb9351441344bd834e18e1be1c Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 5 Aug 2024 16:48:09 +0100 Subject: [PATCH 02/73] chat: chat room lifecycle feature specification --- textile/chat-features.textile | 207 +++++++++++++++++++++++++++++++++- 1 file changed, 206 insertions(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 9bb52afca..a00395042 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -9,5 +9,210 @@ jump_to: h2(#overview). Overview -Section dedicated to new chat feature development. TBC +This document outlines the feature specification for the Ably Chat product. +The key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" (whether lowercased or uppercased) in this document are to be interpreted as described in "RFC 2119":https://tools.ietf.org/html/rfc2119. + +The over-the-wire protocol for Chat, as well as implementation details, may be found on the chat protocol page. + +h2(#overview). Chat Specification Version + +* @(CHA-V1)@ **Specification Version**: This document defines the Ably chat library features specification ('features spec'). +** @(CHA-V1a)@ The current version of the Chat library feature specification is version @0.1.0@. + +h2(#general). General Principles + +* @(CHA-GP1)@ As far as is practicable, the implementation details such as underlying Realtime Channels should be hidden from the public API. This allows developers to interact with Chat without having to understand many low-level primitives. +* @(CHA-GP2)@ The public API should avoid implicit operations as a side-effect to some other operation. For example, adding a subscriber to messages in a Chat Room should not automatically trigger that Room to attach. This is in contrast to the current core SDKs. Avoiding side-effects provides a clean, easy to understand API. +* @(CHA-GP3)@ Wherever possible, Chat features should be exposed in the public API as properties of their parent. For example, @messages@ would be considered a property of a @room@ object. This allows for greater composability and extensibility in the future. + +h2(#rooms). Rooms + +h3(#rooms-general). General Information + +A Room is the atomic unit of Chat. All chat operations are performed in the context of a room that a client is currently attached to. As the Room is the atomic unit, its state should be considered as the combination of the states of underlying resources. + +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-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. +** @(CHA-RS1d)@ The @DETACHING@ status is used when the room is in the process of detaching from Ably. +** @(CHA-RS1e)@ The @DETACHED@ status means that the room has been detached from Ably by a user-initiated request. It will not attempt to re-connect without explicit intervention. +** @(CHA-RS1f)@ The @SUSPENDED@ status is when the room has been detached from Ably for an extended period of time. The room will periodically attempt to reconnect. +** @(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-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. +*** @(CHA-RS2b1)@ @[Testable]@ If an error is associated with the current status, then this must be exposed. +*** @(CHA-RS2b2)@ @[Testable]@ If there is no error is associated with the current status, then the room status should not expose any errors. +* @(CHA-RS3)@ @[Testable]@ A newly created room must have a current status of @INITIALIZED@. +* @(CHA-RS4)@ A room must allow changes to room status to be observed by clients. +** @(CHA-RS4a)@ @[Testable]@ Room status update events must contain the newly entered room status. +** @(CHA-RS4b)@ @[Testable]@ Room status update events must contain the previous room status. +** @(CHA-RS4c)@ @[Testable]@ Room status update events must not contain an error, where that error pertains to the current status. +** @(CHA-RS4d)@ @[Testable]@ Room status update events must contain an error, where that error pertains to the current status. +** @(CHA-RS4e)@ @[Testable]@ Clients must be able to register a listener for room status updates and receive such events. +** @(CHA-RS4f)@ @[Testable]@ Clients must be able to unregister a listener for room status updates and from that point onwards, cease to receive such events on that listener only. +** @(CHA-RS4g)@ @[Testable]@ Clients must be able to unregister all listeners for room status updates and from that point onwards, cease to receive such events on all listeners. + +h3(#rooms-lifecycle). Room Lifecycle + +Rooms are considered the atomic unit of chat and comprise of potentially multiple underlying realtime channels. The status of the room is, broadly speaking, the combination of the respective underlying channel states (the rooms @contributors@). We present one unified status, rather than statuses for multiple individual features, as this is easier for developers to reason about. + +Chat features are spread across multiple Realtime Channels. For the purpose of this section, a @contributor@ is a feature in Chat that is considered as part of the overall room status, as well as its lifecycle. A @contributor@ might share its realtime channel with another (e.g. messages and occupancy), or it might be entirely standalone (room reactions). In that sense, implementations of Room Lifecycle @MUST@ make no assumptions over which realtime channels are in use or being shared, and treat every @contributor@ as being entirely standalone. + +There are four room lifecycle operations: @ATTACH@, @DETACH@, @RELEASE@ and @RETRY@. @RETRY@ is an internal-only operation. These operations are intended to be atomic and not interfere with each other, in order to preserve chat room integrity. How this is achieved is described in further specification items. + +Discontinuities in Realtime connections happen - whereby continuity of message delivery is disrupted. Therefore each feature may also experience discontinuity events - where the user may need to take some action to restore continuity in their application. In Chat, we explicitly tell the user when there's a discontinuity, rather than require them to implement the monitoring themselves. As such are events are normally associated with something going wrong, we only want to tell them that a discontinuity happened when everything has fixed itself. Therefore, when a discontinuity is noticed by us, we might not notify the user immediately, instead preferring to hold the event in pending until the right time. For more information on how to handle discontinuities, consult the room lifecycle specification points. + +In the same sense as discontinuities, sometimes connections drop momentarily - due to connection balancing by the Realtime system or simply bad internet connections. In Chat we try to avoid broadcasting these transient disconnects to users, so long as they don't affect continuity. Therefore, we tend to handle disconnections or detachments optimistically at first - hoping that they will resolve themselves, and only informing the user when it is clear that it may take longer than anticipated. + +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-RL1b)@ @[Testable]@ If the room is in the @RELEASING@ status, the operation shall be rejected with an @ErrorInfo@ with code @102102@. +** @(CHA-RL1c)@ @[Testable]@ If the room is in the @RELEASED@ status, the operation shall be rejected with an @ErrorInfo@ with code @102103@. +** @(CHA-RL1d)@ @[Testable]@ If a room lifecycle operation is already in progress, this operation shall wait until the current operation completes before continuing. +** @(CHA-RL1e)@ @[Testable]@ Notwithstanding the above points, when the attachment operation begins, the room shall be transitioned to the @ATTACHING@ status. +** @(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. +*** @(CHA-RL1g3)@ @[Testable]@ Any transient disconnect timeouts shall be cleared. +** @(CHA-RL1h)@ If a one of the @contributors@ Realtime Channels fails to attach (i.e. the call to @attach()@ returns an error), then the operation has failed and must be rolled back. The procedure to roll back is described in subsequent points. +*** @(CHA-RL1h1)@ @[Testable]@ The @attach@ call must throw an @ErrorInfo@. The code for this error is determined by the feature that failed (see "here":#error-codes for more information on error codes). +*** @(CHA-RL1h2)@ @[Testable]@ If the underlying Realtime Channel entered the @SUSPENDED@ state (i.e. the @attach()@ operation fails and upon subsequently checking the channel state, it is @SUSPENDED@), then the room status will transition to @SUSPENDED@. The state transition @ErrorInfo@ will use the Realtime Channel error as the @cause@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. +*** @(CHA-RL1h3)@ @[Testable]@ When the room enters the @SUSPENDED@ status as a result of @CHA-RL1h2@ the attach operation shall fail using the @ErrorInfo@ associated with the @SUSPENDED@ room status as the error. The room lifecycle shall asnychronously enter the recovery loop (per "@CHA-RL5@":#CHA-RL5) and attempt to re-establish attachment. +*** @(CHA-RL1h4)@ @[Testable]@ If the underlying Realtime Channel entered the @FAILED@ state, then the room status will transition to @FAILED@, using the Realtime Channel error as the @cause@ field of the @ErrorInfo@. The same error shall be thrown as the result of the @ATTACH@ operation. +*** @(CHA-RL1h5)@ @[Testable]@ When the room enters the @FAILED@ status as a result of @CHA-RL1h4@, then the room will detach all channels that are not in the @FAILED@ state. +*** @(CHA-RL1h6)@ @[Testable]@ When the room enters the @FAILED@ status as a result of @CHA-RL1h4@, and a channel fails to detach on command, then the detach operation will be repeated until such a time that all channels have detached successfully. +* @(CHA-RL2)@ A room must be explicitly detached via the @DETACH@ operation. +** @(CHA-RL2a)@ @[Testable]@ If the room status is already @DETACHED@, then this operation is a no-op. +** @(CHA-RL2b)@ @[Testable]@ If the room is in the @RELEASING@ status, the operation shall be rejected with an @ErrorInfo@ with code @102102@. +** @(CHA-RL2c)@ @[Testable]@ If the room is in the @RELEASED@ status, the operation shall be rejected with an @ErrorInfo@ with code @102103@. +** @(CHA-RL2d)@ @[Testable]@ If the room is in the @FAILED@ status, the operation shall be rejected with an @ErrorInfo@ with code @102101@. +** @(CHA-RL2e)@ @[Testable]@ Notwithstanding the above points, when the detachment operation begins, the room shall be transitioned to the @DETACHING@ status and any transient disconnect timeouts cleared. +** @(CHA-RL2f)@ @[Testable]@ The underlying @contributors@ Realtime Channels will be detached in sequence. +** @(CHA-RL2g)@ @[Testable]@ If all channel detachments complete successfully, then the room shall transition to the @DETACHED@ status. +** @(CHA-RL2h)@ If during detachment, a channel fails to detach, different operations are performed based on the nature of the detach. +*** @(CHA-RL2h1)@ @[Testable]@ If a channel enters the @FAILED@ state during detachment, then the room will transition to the @FAILED@ status. The detach operation continues until all channels are either @DETACHED@ or @FAILED@, with the operation throwing an @ErrorInfo@ with the feature-specific error code of the first feature to fail, using the underlying channel error 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 detachment cycle will be retried after a short pause. The rooms status will not change during this process. +* @(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-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-RL3c)@ @[Testable]@ When the release operation commences, the room will transition into the @RELEASING@ status any any transient disconnect timeouts shall be cleared. +** @(CHA-RL3d)@ @[Testable]@ All features channels are detached in sequence. +** @(CHA-RL3e)@ @[Testable]@ If a channel is in the @FAILED@ state when it is time to detach, it shall be ignored. +** @(CHA-RL3f)@ @[Testable]@ If a channel fails to detach, the channel detach sequence will be retried after a short wait. +** @(CHA-RL3g)@ @[Testable]@ Once all channels have entered the @DETACHED@ state, then the room state is transitioned to @RELEASED@ and the operation completes. +** @(CHA-RL3h)@ @[Testable]@ Upon operation completion, the underlying Realtime Channels are released from the core SDK prevent leakage. +* @(CHA-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. +** @(CHA-RL5a)@ @[Testable]@ When entering a retry-loop, the room must first @DETACH@ all contributors underlying realtime channels. +** @(CHA-RL5b)@ @[Testable]@ If the operation above fails, then it must be retried after a short wait. +** @(CHA-RL5c)@ @[Testable]@ If the operation above fails because a channel has entered the @FAILED@ state, then the retry loop must stop and the room must be placed in the @FAILED@ status. +** @(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. +*** @(CHA-RL5f2)@ @[Testable]@ If the attachment cycle fails because a channel entered @FAILED@, then the room is transitioned to @FAILED@ and the retry loop terminates. +*** @(CHA-RL5f3)@ @[Testable]@ If the attachment cycle fails because a channel entered @SUSPENDED@, then the room is transitioned to @SUSPENDED@ and the retry loop restarted using the @SUSPENDED@ channel as the subject. + +h4(#rooms-lifecycle-monitoring). Room Lifecycle Monitoring + +As well as user-initiated operations, the room must monitor its underlying resources and act accordingly. This includes handling transient or long-term disconnection from Ably, as well as discontinuities in channel messages. + +* @(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. +*** @(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. +*** @(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. +*** @(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. +*** @(CHA-RL4b7)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @ATTACHED@ and a transient disconnect timeout exists for the contributor, the timeout is cleared. +*** @(CHA-RL4b8)@ @[Testable]@ If a channel lifecycle operation is not in progress, the channel state is @ATTACHED@, the room status is NOT @ATTACHED@ and all contibutors channel are now @ATTACHED@, the room status is transitioned to @ATTACHED@. +*** @(CHA-RL4b9)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @SUSPENDED@, then the room status is transitioned to @SUSPENDED@, using the @reason@ of the channel state change as the error. Any transient disconnect timeouts are cancelled and the room enters the @RETRY@ loop. + + +h2(#room-configuration). Room Configuration + +* @(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-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. +** @(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. + +h2(#error-codes). Chat-specific Error Codes + +This section contains error codes that are specific to Chat. If a specific error code is not listed for a given circumstance, the most appropriate general error code shall be used. For example @400xx@ for client errors or @500xx@ for server errors. + +
+  // The messages feature failed to attach.
+  MessagesAttachmentFailed = 102001
+
+  // The presence feature failed to attach.
+  PresenceAttachmentFailed = 102002
+
+  // The reactions feature failed to attach.
+  ReactionsAttachmentFailed = 102003
+
+  // The occupancy feature failed to attach.
+  OccupancyAttachmentFailed = 102004
+
+  // The typing feature failed to attach.
+  TypingAttachmentFailed = 102005
+  // 102006 - 102049 reserved for future use for attachment errors
+
+  // The messages feature failed to detach.
+  MessagesDetachmentFailed = 102050
+
+  // The presence feature failed to detach.
+  PresenceDetachmentFailed = 102051
+
+  // The reactions feature failed to detach.
+  ReactionsDetachmentFailed = 102052
+
+  // The occupancy feature failed to detach.
+  OccupancyDetachmentFailed = 102053
+
+  // The typing feature failed to detach.
+  TypingDetachmentFailed = 102054
+  // 102055 - 102099 reserved for future use for detachment errors
+
+  // The room has experienced a discontinuity.
+  RoomDiscontinuity = 102100
+
+  // Unable to perform operation;
+
+  // Cannot perform operation because the room is in a failed state.
+  RoomInFailedState = 102101
+
+  // Cannot perform operation because the room is in a releasing state.
+  RoomIsReleasing = 102102
+
+  // Cannot perform operation because the room is in a released state.
+  RoomIsReleased = 102103
+
+  // Cannot perform operation because the previous operation failed.
+  PreviousOperationFailed = 102104
+
+  // An unknown error has happened in the room lifecycle.
+  RoomLifecycleError = 102105
+
From 340630c859c65e1854e26b96ece3e6fde0ad2d78 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Wed, 14 Aug 2024 08:54:15 +0100 Subject: [PATCH 03/73] chat: remove protocol page Its easier to follow the chat specification if everythings in one place. --- textile/chat-protocol.textile | 12 ------------ 1 file changed, 12 deletions(-) delete mode 100644 textile/chat-protocol.textile diff --git a/textile/chat-protocol.textile b/textile/chat-protocol.textile deleted file mode 100644 index 2e62e618c..000000000 --- a/textile/chat-protocol.textile +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Chat Protocol -section: client-lib-development-guide -index: 50 -jump_to: - Help with: - - Chat Protocol Overview#overview ---- - -h2(#overview). Overview - -Section dedicated to new chat protocol development. TBC From 30ec60f06a97d5dccde95a3716f123d78fd22e53 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Tue, 3 Sep 2024 16:14:14 +0100 Subject: [PATCH 04/73] chat: add spec points clarifying release behaviour --- textile/chat-features.textile | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index a00395042..ac272ee48 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -93,6 +93,8 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations *** @(CHA-RL1h4)@ @[Testable]@ If the underlying Realtime Channel entered the @FAILED@ state, then the room status will transition to @FAILED@, using the Realtime Channel error as the @cause@ field of the @ErrorInfo@. The same error shall be thrown as the result of the @ATTACH@ operation. *** @(CHA-RL1h5)@ @[Testable]@ When the room enters the @FAILED@ status as a result of @CHA-RL1h4@, then the room will detach all channels that are not in the @FAILED@ state. *** @(CHA-RL1h6)@ @[Testable]@ When the room enters the @FAILED@ status as a result of @CHA-RL1h4@, and a channel fails to detach on command, then the detach operation will be repeated until such a time that all channels have detached successfully. +** @(CHA-RL1i)@ Because of the singleton pattern that the core SDKs implement with regards to channels, subsequent instances of a room will use the same underlying realtime channels if the realtime channels are not properly @released@ as part of cleaning up the previous room instance before the new instance is used. Therefore, it is important to ensure that releasing operations (per "@CHA-RC1d@"#CHA-RC1d) have completed before a new room can be attached (to avoid channel objects leaking between instances of rooms). +*** @(CHA-RL1i1)@ @[Testable]@ If a room instance is in the process of being released and cleaned up (per "@CHA-RC1d@"#CHA-RC1d), then the @ATTACH@ operation of a subsequent instance of the same room shall wait for the release operation of the previous to complete before commencing. * @(CHA-RL2)@ A room must be explicitly detached via the @DETACH@ operation. ** @(CHA-RL2a)@ @[Testable]@ If the room status is already @DETACHED@, then this operation is a no-op. ** @(CHA-RL2b)@ @[Testable]@ If the room is in the @RELEASING@ status, the operation shall be rejected with an @ErrorInfo@ with code @102102@. @@ -155,9 +157,11 @@ h2(#room-configuration). Room Configuration ** @(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-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-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. ** @(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. +** @(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. h2(#error-codes). Chat-specific Error Codes From 290a84a41ff56870146cecfc9f1703a5a494188f Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Fri, 13 Sep 2024 13:28:06 +0100 Subject: [PATCH 05/73] chat: various clarifications on room lifecycle --- textile/chat-features.textile | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index ac272ee48..a390d5577 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -77,8 +77,8 @@ 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-RL1b)@ @[Testable]@ If the room is in the @RELEASING@ status, the operation shall be rejected with an @ErrorInfo@ with code @102102@. -** @(CHA-RL1c)@ @[Testable]@ If the room is in the @RELEASED@ status, the operation shall be rejected with an @ErrorInfo@ with code @102103@. +** @(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. ** @(CHA-RL1e)@ @[Testable]@ Notwithstanding the above points, when the attachment operation begins, the room shall be transitioned to the @ATTACHING@ status. ** @(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. @@ -89,20 +89,20 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL1h)@ If a one of the @contributors@ Realtime Channels fails to attach (i.e. the call to @attach()@ returns an error), then the operation has failed and must be rolled back. The procedure to roll back is described in subsequent points. *** @(CHA-RL1h1)@ @[Testable]@ The @attach@ call must throw an @ErrorInfo@. The code for this error is determined by the feature that failed (see "here":#error-codes for more information on error codes). *** @(CHA-RL1h2)@ @[Testable]@ If the underlying Realtime Channel entered the @SUSPENDED@ state (i.e. the @attach()@ operation fails and upon subsequently checking the channel state, it is @SUSPENDED@), then the room status will transition to @SUSPENDED@. The state transition @ErrorInfo@ will use the Realtime Channel error as the @cause@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. -*** @(CHA-RL1h3)@ @[Testable]@ When the room enters the @SUSPENDED@ status as a result of @CHA-RL1h2@ the attach operation shall fail using the @ErrorInfo@ associated with the @SUSPENDED@ room status as the error. The room lifecycle shall asnychronously enter the recovery loop (per "@CHA-RL5@":#CHA-RL5) and attempt to re-establish attachment. -*** @(CHA-RL1h4)@ @[Testable]@ If the underlying Realtime Channel entered the @FAILED@ state, then the room status will transition to @FAILED@, using the Realtime Channel error as the @cause@ field of the @ErrorInfo@. The same error shall be thrown as the result of the @ATTACH@ operation. -*** @(CHA-RL1h5)@ @[Testable]@ When the room enters the @FAILED@ status as a result of @CHA-RL1h4@, then the room will detach all channels that are not in the @FAILED@ state. -*** @(CHA-RL1h6)@ @[Testable]@ When the room enters the @FAILED@ status as a result of @CHA-RL1h4@, and a channel fails to detach on command, then the detach operation will be repeated until such a time that all channels have detached successfully. +*** @(CHA-RL1h3)@ @[Testable]@ When the room enters the @SUSPENDED@ status as a result of @CHA-RL1h2@ the @attach()@ operation shall fail using the error from @CHA-RL1h2@. The room lifecycle shall asynchronously (non-blocking to the @ATTACH@ operation) enter the recovery loop (per "@CHA-RL5@":#CHA-RL5) and attempt to re-establish attachment. +*** @(CHA-RL1h4)@ @[Testable]@ If the underlying Realtime Channel entered the @FAILED@ state, then the room status will transition to @FAILED@, using the error from the realtime channels `attach()` call as the @cause@ field of the @ErrorInfo@. The state transition @ErrorInfo@ will use the Realtime Channel error as the @cause@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. The same error shall be thrown as the result of the @ATTACH@ operation. +*** @(CHA-RL1h5)@ @[Testable]@ When the room enters the @FAILED@ status as a result of @CHA-RL1h4@, asynchronously with respect to @CHA-RL1h4@, then the room will detach all channels that are not in the @FAILED@ state. +*** @(CHA-RL1h6)@ @[Testable]@ If, when performing @CHA-RL1h5@, a channel fails to detach on command, then the detach operation will be repeated until such a time that all channels have detached successfully. ** @(CHA-RL1i)@ Because of the singleton pattern that the core SDKs implement with regards to channels, subsequent instances of a room will use the same underlying realtime channels if the realtime channels are not properly @released@ as part of cleaning up the previous room instance before the new instance is used. Therefore, it is important to ensure that releasing operations (per "@CHA-RC1d@"#CHA-RC1d) have completed before a new room can be attached (to avoid channel objects leaking between instances of rooms). *** @(CHA-RL1i1)@ @[Testable]@ If a room instance is in the process of being released and cleaned up (per "@CHA-RC1d@"#CHA-RC1d), then the @ATTACH@ operation of a subsequent instance of the same room shall wait for the release operation of the previous to complete before commencing. * @(CHA-RL2)@ A room must be explicitly detached via the @DETACH@ operation. ** @(CHA-RL2a)@ @[Testable]@ If the room status is already @DETACHED@, then this operation is a no-op. -** @(CHA-RL2b)@ @[Testable]@ If the room is in the @RELEASING@ status, the operation shall be rejected with an @ErrorInfo@ with code @102102@. -** @(CHA-RL2c)@ @[Testable]@ If the room is in the @RELEASED@ status, the operation shall be rejected with an @ErrorInfo@ with code @102103@. -** @(CHA-RL2d)@ @[Testable]@ If the room is in the @FAILED@ status, the operation shall be rejected with an @ErrorInfo@ with code @102101@. +** @(CHA-RL2b)@ @[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-RL2c)@ @[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-RL2d)@ @[Testable]@ If the room is in the @FAILED@ status, the operation shall be rejected with an @ErrorInfo@ with @RoomInFailedState@ error code from the "chat-specific error codes":#error-codes. ** @(CHA-RL2e)@ @[Testable]@ Notwithstanding the above points, when the detachment operation begins, the room shall be transitioned to the @DETACHING@ status and any transient disconnect timeouts cleared. -** @(CHA-RL2f)@ @[Testable]@ The underlying @contributors@ Realtime Channels will be detached in sequence. -** @(CHA-RL2g)@ @[Testable]@ If all channel detachments complete successfully, then the room shall transition to the @DETACHED@ status. +** @(CHA-RL2f)@ @[Testable]@ The underlying @contributors@ Realtime Channels will be detached in sequence - a call to @detach()@ must complete before the next call begins. +** @(CHA-RL2g)@ @[Testable]@ If all channel detachments complete successfully (all calls @detach()@ return successfully), then the room shall transition to the @DETACHED@ status. ** @(CHA-RL2h)@ If during detachment, a channel fails to detach, different operations are performed based on the nature of the detach. *** @(CHA-RL2h1)@ @[Testable]@ If a channel enters the @FAILED@ state during detachment, then the room will transition to the @FAILED@ status. The detach operation continues until all channels are either @DETACHED@ or @FAILED@, with the operation throwing an @ErrorInfo@ with the feature-specific error code of the first feature to fail, using the underlying channel error 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. From a596114eb8c0dd81c08dde9b5306fe617344a521 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Fri, 13 Sep 2024 14:49:53 +0100 Subject: [PATCH 06/73] chat: add messages specification --- textile/chat-features.textile | 150 ++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index a390d5577..f98ae9faa 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -25,6 +25,7 @@ h2(#general). General Principles * @(CHA-GP1)@ As far as is practicable, the implementation details such as underlying Realtime Channels should be hidden from the public API. This allows developers to interact with Chat without having to understand many low-level primitives. * @(CHA-GP2)@ The public API should avoid implicit operations as a side-effect to some other operation. For example, adding a subscriber to messages in a Chat Room should not automatically trigger that Room to attach. This is in contrast to the current core SDKs. Avoiding side-effects provides a clean, easy to understand API. * @(CHA-GP3)@ Wherever possible, Chat features should be exposed in the public API as properties of their parent. For example, @messages@ would be considered a property of a @room@ object. This allows for greater composability and extensibility in the future. +* @(CHA-GP4)@ Avoid overloading methods and optional parameters. Prefer object-type parameters wherever practical and idiomatic. h2(#rooms). Rooms @@ -163,6 +164,155 @@ h2(#room-configuration). Room Configuration ** @(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. +h2(#messages). Messages + +Messages are the quintessential component of a chat room - the purpose of chat is for users to talk to each other! + +Broadly speaking, messages are published via REST calls to the Chat HTTP API and message events are received in Realtime over a corresponding realtime channel. + +@Messages@ shall be exposed to consumers via the @messages@ property of a @Room@. + +* @(CHA-M1)@ Chat messages for a Room are sent on a corresponding realtime channel @::$chat::$chatMessages@. For example, if your room id is @my-room@ then then messages channel will be @my-room::$chat::$chatMessages@. +* @(CHA-M2)@ A @Message@ corresponds to a single message in a chat room. This is analogous to a single user-specified message on an Ably channel (NOTE: **not** a @ProtocolMessage@). +** @(CHA-M2a)@ @[Testable]@ A @Message@ is considered before another @Message@ in the global order if the @timeserial@ of the corresponding realtime channel message comes first. +** @(CHA-M2b)@ @[Testable]@ A @Message@ is considered after another @Message@ in the global order if the @timeserial@ of the corresponding realtime channel message comes second. +** @(CHA-M2c)@ @[Testable]@ A @Message@ is considered to be equal to another @Message@ if they have the same timeserial. +* @(CHA-M3)@ Messages are sent to Ably via the Chat REST API, using the @send@ method. +** @(CHA-M3a)@ @[Testable]@ When a message is sent successfully, the caller shall receive a struct representing the "@Message@":#chat-structs-message in response (as if it were received via Realtime event). +** @(CHA-M3b)@ @[Testable]@ A message may be sent without @metadata@ or @headers@. When these are not specified by the user, they must be omitted from the REST payload. +** @(CHA-M3c)@ @[Testable]@ @metadata@ must not contain the key @ably-chat@. This is reserved for future internal use. If this key is present, the send call shall terminate by throwing an @ErrorInfo@ with code @40001@. +** @(CHA-M3d)@ @[Testable]@ @headers@ must not contain a key prefixed with @ably-chat@. This is reserved for future internal use. If this key is present, the send call shall terminate by throwing an @ErrorInfo@ with code @40001@. +** @(CHA-M3e)@ @[Testable]@ If an error is returned from the REST API, its @ErrorInfo@ representation shall be thrown as the result of the @send@ call. +* @(CHA-M4)@ Messages can be received via a subscription in realtime. +** @(CHA-M4a)@ @[Testable]@ A subscription can be registered to receive incoming messages. Adding a subscription has no side effects on the status of the room or the underlying realtime channel. +** @(CHA-M4b)@ @[Testable]@ A subscription can de-registered from incoming messages. Removing a subscription has no side effects on the status of the room or the underlying realtime channel. +** @(CHA-M4c)@ @[Testable]@ When a realtime message with @name@ set to @message.created@ is received, it is translated into a message event, which contains a @type@ field with the event type as well as a @message@ field containing the "@Message Struct@":#chat-structs-message. This event is then broadcast to all subscribers. +** @(CHA-M4d)@ @[Testable]@ If a realtime message with an unknown @name@ is received, the SDK shall silently discard the message, though it may log at @DEBUG@ or @TRACE@ level. +* @(CHA-M5)@ For a given subscription, messages prior to the point of subscription can be retrieved in a history-like request. Note that this is the point in the message flow @(subscription point)@ at which the subscription was made, NOT the channel attachment point. +** @(CHA-M5a)@ @[Testable]@ If a subscription is added when the underlying realtime channel is @ATTACHED@, then the @subscription point@ is the current @channelSerial@ of the realtime channel. +** @(CHA-M5b)@ @[Testable]@ If a subscription is added when the underlying realtime channel is in any other state, then its @subscription point@ becomes the @attachSerial@ at the the point of channel attachment. +** @(CHA-M5c)@ @[Testable]@ If a channel leaves the @ATTACHED@ state and then re-enters @ATTACHED@ with @resumed=false@, then it must be assumed that messages have been missed. The @subscription point@ of any subscribers must be reset to the @attachSerial@. +** @(CHA-M5d)@ @[Testable]@ If a channel @UPDATE@ event is received and @resumed=false@, then it must be assumed that messages have been missed. The @subscription point@ of any subscribers must be reset to the @attachSerial@. +** @(CHA-M5e)@ Each subscription shall expose a method or callback that allows for messages to be queried. These messages are queried via the "REST API"#rest-fetching-messages. +** @(CHA-M5f)@ @[Testable]@ This method must accept any of the standard history query options, except for @direction@, which must always be @backwards@. +** @(CHA-M5g)@ @[Testable]@ The subscribers @subscription point@ must be additionally specified (internally, by us) in the @fromSerial@ query parameter. +** @(CHA-M5h)@ @[Testable]@ The method must return a standard @PaginatedResult@ , which can be further inspected to paginate across results. +** @(CHA-M5i)@ @[Testable]@ If the REST API returns an error, then the method must throw its @ErrorInfo@ representation. +** @(CHA-M5j)@ @[Testable]@ If the @end@ parameter is specified and is more recent than the @subscription point@ timeserial, the method must throw an @ErrorInfo@ with code @40000@. +* @(CHA-M6)@ Messages should be queryable from a paginated REST API. +* @(CHA-M6a)@ @[Testable]@ A method must be exposed that accepts the standard Ably REST API query parameters. It shall call the "REST API"#rest-fetching-messages and return a @PaginatedResult@ containing messages, which can then be paginated through. +* @(CHA-M6b)@ @[Testable]@ If the REST API returns an error, then the method must throw its @ErrorInfo@ representation. + + + +h2(#rest-api). Chat HTTP REST API + +h3(#rest-general). General + +* @(CHA-RST1)@ REST API requests shall be made via the @request()@ method on the underling Ably SDK. +* @(CHA-RST2)@ REST API requests shall use API Protocol Version @3@ +* @(CHA-RST3)@ @[Testable]@ REST API requests must be supported using @JSON@ and @msgpack@ as a @Content-Type@ (@useBinaryProtocol@ on the underlying Ably SDK) + +h3(#rest-sending-messages). Sending Messages + +h4(#rest-sending-messages-request). Request + +Below is the full REST payload format. The @metadata@ and @headers@ keys are optional. + +
+  POST /chat/v1/rooms//messages
+  {
+    "text": "the message text",
+    "metadata": {
+      "foo": {
+        "bar": 1
+      }
+    },
+    "headers": {
+      "baz": "qux"
+    }
+  }
+
+ +h4(#rest-sending-messages-request). Response + +A successful request shall result in status code @201 Created@. + +The response body is as follows. + +
+  {
+    "timeserial": "cbfqxperABgItU52203559@1726232498871-0",
+    "createdAt": 1726232498871
+  }
+
+ +h4(#rest-sending-messages-request). Corresponding Realtime Event + +
+  {
+    "name": "message.created"
+    "encoding": "json"
+    "data": {
+      "text": "the message text",
+      "metadata": {
+        "foo": {
+          "bar": 1
+        }
+      }
+    },
+    "timestamp": "1726232498871",
+    "extras": {
+      "headers": {
+        "baz": "qux"
+      },
+      "timeserial": "cbfqxperABgItU52203559@1726232498871-0"
+    }
+  }
+
+ +h3(#rest-fetching-messages). Fetching Message History + +h4(#rest-fetching-messages-request). Request + +
+  GET /chat/v1/rooms//messages
+
+ +The method accepts query parameters identical to the standard Ably REST API. + +h4(#rest-fetching-messages-response). Response + +An array of "@Message@ structs":#chat-structs-message + + +h2(#chat-structs). Chat Structs and Types + +This section contains an overview of the key types in Chat. This is not intended to be prescriptive to implementation and different ecosystems may expose the underlying properties +in whichever format is most idiomatic to the platform. + +h3(#chat-structs-message). Messages + +
+  {
+    "timeserial": "cbfqxperABgItU52203559@1726232498871-0",
+    "roomId": "my-room",
+    "clientId": "who-sent-the-message",
+    "text": "my-message",
+    "createdAt": DateTime(),
+    "metadata": {
+      "foo": {
+        "bar": 1
+      }
+    },
+    "headers": {
+      "baz": "qux"
+    }
+  }
+
+ +Determining the global order of messages may be achieved vi + h2(#error-codes). Chat-specific Error Codes This section contains error codes that are specific to Chat. If a specific error code is not listed for a given circumstance, the most appropriate general error code shall be used. For example @400xx@ for client errors or @500xx@ for server errors. From ae1a8e99e47a11748a35afdbde67ff3dadeb174d Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Fri, 13 Sep 2024 15:32:12 +0100 Subject: [PATCH 07/73] chat: add presence and ephemeral room reactions spec --- textile/chat-features.textile | 137 +++++++++++++++++++++++++++++++++- 1 file changed, 134 insertions(+), 3 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index f98ae9faa..8d446f283 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -172,7 +172,7 @@ Broadly speaking, messages are published via REST calls to the Chat HTTP API and @Messages@ shall be exposed to consumers via the @messages@ property of a @Room@. -* @(CHA-M1)@ Chat messages for a Room are sent on a corresponding realtime channel @::$chat::$chatMessages@. For example, if your room id is @my-room@ then then messages channel will be @my-room::$chat::$chatMessages@. +* @(CHA-M1)@ Chat messages for a Room are sent on a corresponding realtime channel @::$chat::$chatMessages@. For example, if your room id is @my-room@ then the messages channel will be @my-room::$chat::$chatMessages@. * @(CHA-M2)@ A @Message@ corresponds to a single message in a chat room. This is analogous to a single user-specified message on an Ably channel (NOTE: **not** a @ProtocolMessage@). ** @(CHA-M2a)@ @[Testable]@ A @Message@ is considered before another @Message@ in the global order if the @timeserial@ of the corresponding realtime channel message comes first. ** @(CHA-M2b)@ @[Testable]@ A @Message@ is considered after another @Message@ in the global order if the @timeserial@ of the corresponding realtime channel message comes second. @@ -188,6 +188,7 @@ Broadly speaking, messages are published via REST calls to the Chat HTTP API and ** @(CHA-M4b)@ @[Testable]@ A subscription can de-registered from incoming messages. Removing a subscription has no side effects on the status of the room or the underlying realtime channel. ** @(CHA-M4c)@ @[Testable]@ When a realtime message with @name@ set to @message.created@ is received, it is translated into a message event, which contains a @type@ field with the event type as well as a @message@ field containing the "@Message Struct@":#chat-structs-message. This event is then broadcast to all subscribers. ** @(CHA-M4d)@ @[Testable]@ If a realtime message with an unknown @name@ is received, the SDK shall silently discard the message, though it may log at @DEBUG@ or @TRACE@ level. +** @(CHA-M5d)@ @[Testable]@ Incoming realtime events that are malformed (unknown field should be ignored) shall not be emitted to subscribers. * @(CHA-M5)@ For a given subscription, messages prior to the point of subscription can be retrieved in a history-like request. Note that this is the point in the message flow @(subscription point)@ at which the subscription was made, NOT the channel attachment point. ** @(CHA-M5a)@ @[Testable]@ If a subscription is added when the underlying realtime channel is @ATTACHED@, then the @subscription point@ is the current @channelSerial@ of the realtime channel. ** @(CHA-M5b)@ @[Testable]@ If a subscription is added when the underlying realtime channel is in any other state, then its @subscription point@ becomes the @attachSerial@ at the the point of channel attachment. @@ -202,15 +203,72 @@ Broadly speaking, messages are published via REST calls to the Chat HTTP API and * @(CHA-M6)@ Messages should be queryable from a paginated REST API. * @(CHA-M6a)@ @[Testable]@ A method must be exposed that accepts the standard Ably REST API query parameters. It shall call the "REST API"#rest-fetching-messages and return a @PaginatedResult@ containing messages, which can then be paginated through. * @(CHA-M6b)@ @[Testable]@ If the REST API returns an error, then the method must throw its @ErrorInfo@ representation. +* @(CHA-M7)@ @[Testable]@ Users may subscribe to discontinuity events to know when there's been a break in messages that they need to resolve. Their listener will be called when a discontinuity event is triggered from the room lifecycle. +h2(#reactions). Ephemeral Room Reactions +Ephemeral room reactions are one-time events that are sent to the room, such as thumbs-up or heart emojis. They are supposed to capture the current emotions in the room (e.g. everyone spamming the :tada: emoji when a team scores the winning goal). + +They are ephemeral as we do not currently store these messages do not support server-authoritative counting. + +All ephemeral room reactions are handled over the Realtime connection. + +@Reactions@ shall be exposed to consumers via the @reactions@ property of a @Room@. + +* @(CHA-ER1)@ Reactions for a Room are sent on a corresponding realtime channel @::$chat::$roomReactions@. For example, if your room id is @my-room@ then the reactions channel will be @my-room::$chat::$roomReactions@. +* @(CHA-ER2)@ A @Reaction@ corresponds to a single reaction in a chat room. This is analogous to a single user-specified message on an Ably channel (NOTE: **not** a @ProtocolMessage@). +* @(CHA-ER3)@ Ephemeral room reactions are sent to Ably via the Realtime connection via a @send@ method. +** @(CHA-ER3a)@ @[Testable]@ Reactions are sent on the channel using a message in "this format":#realtime-room-reactions. +** @(CHA-ER3b)@ @[Testable]@ @metadata@ must not contain the key @ably-chat@. This is reserved for future internal use. If this key is present, the @send@ call shall terminate by throwing an @ErrorInfo@ with code @40001@. +** @(CHA-ER3c)@ @[Testable]@ @headers@ must not contain a key prefixed with @ably-chat@. This is reserved for future internal use. If this key is present, the send call shall terminate by throwing an @ErrorInfo@ with code @40001@. +* @(CHA-ER4)@ A user may subscribe to reaction events in Realtime. +** @(CHA-ER4a)@ @[Testable]@ A user may provide a listener to subscribe to reaction events. This operation must have no side-effects in relation to room or underlying status. When a "realtime message":#realtime-room-reactions with name @roomReaction@ is received, this message is converted into a "reaction object":#chat-structs-ephemeral-reactions and emitted to subscribers. +** @(CHA-ER4b)@ @[Testable]@ A user may unsubscribe a registered listener. This operation must have no side-effects in relation to room or underlying status. Once unsubscribed, subsequent reaction events must not be emitted to this listener. +** @(CHA-ER4c)@ @[Testable]@ Realtime events with an unknown @name@ shall be silently discarded. +** @(CHA-ER4d)@ @[Testable]@ Realtime events that are malformed (unknown fields should be ignored) shall not be emitted to listeners. +* @(CHA-ER5)@ @[Testable]@ Users may subscribe to discontinuity events to know when there's been a break in reactions that they need to resolve. Their listener will be called when a discontinuity event is triggered from the room lifecycle. + +h2(#presence). Online Status (Presence) + +Presence allows chat room users to indicate to others that they're online, as well as other information including their profile picture URL etc. + +@Presence@ shall be exposed to consumers via the @presence@ property of a @Room@. + +* @(CHA-PR1)@ Presence for a Room is exposed on the realtime channel used for chat messages, in the format @::$chat::$chatMessages@. For example, if your room id is @my-room@ then the presence channel will be @my-room::$chat::$chatMessages@. +* @(CHA-PR2)@ The presence payload for Chat is opinionated, so that we may add or change fields later without needing to consider how customers are using presence. +** @(CHA-PR2a)@ @[Testable]@ The presence data format is a JSON object as described below. Customers may specify content of an arbitrary type to be placed in the @userCustomData@ field. + +
+  {
+    "userCustomData": {
+      // Some user specified type, does not have to be object.
+    }
+  }
+
+ +* @(CHA-PR3)@ Users may enter presence. +** @(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)@ @[Testable]@ If the underlying realtime channel is not attached at the time of the @enter@ call, then the @enter@ call must not call @enter@ on the realtime channel, as this triggers an implicit attach. The call must either be delayed until such a time that the channel is already attached. +* @(CHA-PR3)@ Users may update their presence data. +** @(CHA-PR3a)@ @[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-PR3b)@ @[Testable]@ If the underlying realtime channel is not attached at the time of the @update@ call, then the @update@ call must not call @update@ on the realtime channel, as this triggers an implicit attach. The call must either be delayed until such a time that the channel is already attached. +* @(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-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. +** @(CHA-PR6a)@ @[Testable] As the underlying @presence.get@ operation performs an implicit attach, this operation must not return or call @presence.get@ until the underlying channel is in the attached state. +* @(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. +** @(CHA-PR7b)@ @[Testable]@ A subscription to presence may be removed, after which it shall receive no further events. +* @(CHA-PR8)@ @[Testable]@ Users may subscribe to discontinuity events to know when there's been a break in presence. Their listener will be called when a discontinuity event is triggered from the room lifecycle. For presence, there shouldn't need to be user action as the underlying core SDK will heal the presence set. h2(#rest-api). Chat HTTP REST API h3(#rest-general). General * @(CHA-RST1)@ REST API requests shall be made via the @request()@ method on the underling Ably SDK. -* @(CHA-RST2)@ REST API requests shall use API Protocol Version @3@ +* @(CHA-RST2)@ REST API requests shall use the API Protocol Version of the underlying core SDK. * @(CHA-RST3)@ @[Testable]@ REST API requests must be supported using @JSON@ and @msgpack@ as a @Content-Type@ (@useBinaryProtocol@ on the underlying Ably SDK) h3(#rest-sending-messages). Sending Messages @@ -285,6 +343,33 @@ h4(#rest-fetching-messages-response). Response An array of "@Message@ structs":#chat-structs-message +h2(#realtime-api). Chat Realtime API + +This section describes the message formats for chat events that occur over a Realtime connection. + +h3(#realtime-room-reactions). Ephemeral Room Reactions + +
+  {
+    "name": "roomReaction"
+    "encoding": "json"
+    "data": {
+      "type": ":heart:",
+      "metadata": {
+        "foo": {
+          "bar": 1
+        }
+      }
+    },
+    "timestamp": "1726232498871", // Only on incoming messages
+    "extras": {
+      "headers": {
+        "baz": "qux"
+      },
+    }
+  }
+
+ h2(#chat-structs). Chat Structs and Types @@ -311,7 +396,53 @@ h3(#chat-structs-message). Messages } -Determining the global order of messages may be achieved vi +Determining the global order of messages may be achieved by comparing the timeserials. See @CHA-M2@ for more information. + +h3(#chat-structs-ephemeral-reactions). Ephemeral Room Reactions + +
+  {
+    "type": ":heart:",
+    "roomId": "my-room",
+    "clientId": "who-sent-the-message",
+    "createdAt": DateTime(),
+    "metadata": {
+      "foo": {
+        "bar": 1
+      }
+    },
+    "headers": {
+      "baz": "qux"
+    }
+  }
+
+ +h3(#chat-structs-presence-member). Presence Member + +
+  {
+    "clientId": "who-sent-the-message",
+    "action": "enter",
+    "updatedAt": DateTime(),
+    "data": {}, // Whatever the user-provided data is. It must be destructured from the internal format we use.
+    "extras": {
+      "headers": {
+        "baz": "qux"
+      }
+    }
+  }
+
+ +h3(#chat-structs-presence-event). Presence Event + +
+  {
+    "clientId": "who-is-in-presence",
+    "action": "enter",
+    "timestamp": DateTime(),
+    "data": {}, // Whatever the user-provided data is. It must be destructured from the internal format we use.
+  }
+
h2(#error-codes). Chat-specific Error Codes From 4d3969755fb64366eba5573aec4fbc1d5feb1f7e Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Fri, 11 Oct 2024 14:02:18 +0100 Subject: [PATCH 08/73] add typing indicators spec --- textile/chat-features.textile | 40 ++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 8d446f283..7d41222a7 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -154,13 +154,15 @@ As well as user-initiated operations, the room must monitor its underlying resou 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-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-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. +* @(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. @@ -263,6 +265,31 @@ Presence allows chat room users to indicate to others that they're online, as we ** @(CHA-PR7b)@ @[Testable]@ A subscription to presence may be removed, after which it shall receive no further events. * @(CHA-PR8)@ @[Testable]@ Users may subscribe to discontinuity events to know when there's been a break in presence. Their listener will be called when a discontinuity event is triggered from the room lifecycle. For presence, there shouldn't need to be user action as the underlying core SDK will heal the presence set. +h2(#typing). Typing Indicators + +Typing Indicators allow chat room users to indicate to others that they are typing. This is most common in 1:1 and community chat, where the client would display "Alice and Bob are typing..." to users. This system is presence-based, to avoid the cost of heartbeat/polling messages, with entering presence deemed to mean "started typing" and leaving presence deemed to mean "stopped typing". + +@Typing Indicators@ shall be exposed to consumers via the @typing@ property of a @Room@. + +* @(CHA-T1)@ Typing Indicators for a Room is exposed on a dedicated Realtime channel. These channels use the format @::$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. +* @(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. +* @(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-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, then the client leaves presence. Upon successful completion of the presence leave operation, the @CHA-T3@ timeout is cancelled. +* @(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. +** @(CHA-T6c)@ @[Testable]@ When a presence event is received from the realtime client, the Chat client will perform a @presence.get()@ operation to get the current presence set. This guarantees that we get a fully synced presence set. This is then used to emit the typing clients to the subscriber. +*** @(CHA-T6c1)@ @[Testable]@ If the @presence.get()@ operation fails, then it shall be retried using a backoff with jitter, up to a timeout of 30 seconds. +*** @(CHA-T6c2)@ @[Testable]@ If multiple presence events are received resulting in concurrent @presence.get()@ calls, then we guarantee that only the "latest" event is emitted. That is to say, if presence event A and B occur in that order, then only the typing event generated by B's call to @presence.get()@ will be emitted to typing subscribers. +* @(CHA-T7)@ @[Testable]@ Users may subscribe to discontinuity events to know when there's been a break in typing indicators. Their listener will be called when a discontinuity event is triggered from the room lifecycle. For typing, there shouldn't need to be user action as the underlying core SDK will heal the presence set. + h2(#rest-api). Chat HTTP REST API h3(#rest-general). General @@ -444,6 +471,17 @@ h3(#chat-structs-presence-event). Presence Event } +h3(#chat-structs-typing-event). Typing Event + +
+  {
+    "currentlyTyping": ["clientId-1", "clientID-2"],
+    "action": "enter",
+    "timestamp": DateTime(),
+    "data": {}, // Whatever the user-provided data is. It must be destructured from the internal format we use.
+  }
+
+ h2(#error-codes). Chat-specific Error Codes This section contains error codes that are specific to Chat. If a specific error code is not listed for a given circumstance, the most appropriate general error code shall be used. For example @400xx@ for client errors or @500xx@ for server errors. From 49de6b00474506a1bb8b3578d6aa17a439af485b Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Fri, 11 Oct 2024 14:08:47 +0100 Subject: [PATCH 09/73] add CHA-PR9 for presence permissions --- textile/chat-features.textile | 3 +++ 1 file changed, 3 insertions(+) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 7d41222a7..605912c83 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -264,6 +264,9 @@ Presence allows chat room users to indicate to others that they're online, as we ** @(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. ** @(CHA-PR7b)@ @[Testable]@ A subscription to presence may be removed, after which it shall receive no further events. * @(CHA-PR8)@ @[Testable]@ Users may subscribe to discontinuity events to know when there's been a break in presence. Their listener will be called when a discontinuity event is triggered from the room lifecycle. For presence, there shouldn't need to be user action as the underlying core SDK will heal the presence set. +* @(CHA-PR9)@ Users may configure their presence options via the @RoomOptions@ provided at room configuration time. +** @(CHA-PR9a)@ @[Testable]@ Setting @enter@ to false prevents the user from entering presence by means of the @ChannelMode@ on the underlying realtime channel. Entering presence will result in an error. The default is true. +** @(CHA-PR9b)@ @[Testable]@ Setting @subscribe@ to false prevents the user from subscribing to presence by means of the @ChannelMode@ on the underlying realtime channel. This does not prevent them from receiving their own presence messages, but they will not receive them from others. The default is true. h2(#typing). Typing Indicators From c4b057f02bff668bc24afbe9c57f03491a1899d3 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Fri, 11 Oct 2024 14:08:58 +0100 Subject: [PATCH 10/73] Add typing event struct for chat --- textile/chat-features.textile | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 605912c83..4e8d47776 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -276,7 +276,7 @@ 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 @::$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. -* @(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. +* @(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. @@ -406,6 +406,24 @@ h2(#chat-structs). Chat Structs and Types This section contains an overview of the key types in Chat. This is not intended to be prescriptive to implementation and different ecosystems may expose the underlying properties in whichever format is most idiomatic to the platform. +h3(#chat-structs-room-options). RoomOptions + +The RoomOptions struct describes configuration options for a Chat room. A property being set to a non-null value means that the feature is enabled. Some features have specific configuration. + +
+  {
+    "presence": {
+      "enter": boolean,
+      "subscribe": boolean,
+    },
+    "typing": {
+      "timeoutMs": number
+    },
+    "reactions": {}, // No properties, but must be non-null to enable feature.
+    "occupancy": {} 
+  }
+
+ h3(#chat-structs-message). Messages 
@@ -479,9 +497,6 @@ h3(#chat-structs-typing-event). Typing Event
 
   {
     "currentlyTyping": ["clientId-1", "clientID-2"],
-    "action": "enter",
-    "timestamp": DateTime(),
-    "data": {}, // Whatever the user-provided data is. It must be destructured from the internal format we use.
   }
 

 

From 3f347555ccccf3bf2e90857ffe1f1321a625524f Mon Sep 17 00:00:00 2001
From: Andy Ford 
Date: Fri, 11 Oct 2024 14:32:30 +0100
Subject: [PATCH 11/73] clarify presence get behaviour

---
 textile/chat-features.textile | 46 ++++++++++++++++++++++++++++-------
 1 file changed, 37 insertions(+), 9 deletions(-)

diff --git a/textile/chat-features.textile b/textile/chat-features.textile
index 4e8d47776..113c830b3 100644
--- a/textile/chat-features.textile
+++ b/textile/chat-features.textile
@@ -248,17 +248,38 @@ Presence allows chat room users to indicate to others that they're online, as we
   }
-* @(CHA-PR3)@ Users may enter presence. +* @(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)@ @[Testable]@ If the underlying realtime channel is not attached at the time of the @enter@ call, then the @enter@ call must not call @enter@ on the realtime channel, as this triggers an implicit attach. The call must either be delayed until such a time that the channel is already attached. -* @(CHA-PR3)@ Users may update their presence data. -** @(CHA-PR3a)@ @[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-PR3b)@ @[Testable]@ If the underlying realtime channel is not attached at the time of the @update@ call, then the @update@ call must not call @update@ on the realtime channel, as this triggers an implicit attach. The call must either be delayed until such a time that the channel is already attached. +** @(CHA-PR3b)@ This specification item has been removed in favour of @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-PR3c1)@ @[Testable]@ If the attach has not been called, then the @enter@ call will throw an error. +** @(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)@ @[Testable]@ This specification item has been removed in favour of @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-PR10c1)@ @[Testable]@ If the attach has not been called, then the @update@ call will throw an error. +** @(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. +** @(CHA-PR10g)@ @[Testable]@ For any other room status, an @ErrorInfo@ with code 40000 will be thrown. * @(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-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. -** @(CHA-PR6a)@ @[Testable] As the underlying @presence.get@ operation performs an implicit attach, this operation must not return or call @presence.get@ until the underlying channel is in the attached state. +* @(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)@ @[Testable] This requirement has been removed in favour of @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-PR6b1)@ @[Testable]@ If the attach has not been called, then the @get@ call will throw an error. +** @(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. +** @(CHA-PR6f)@ @[Testable]@ For any other room status, an @ErrorInfo@ with code 40000 will be thrown. * @(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. @@ -275,7 +296,14 @@ Typing Indicators allow chat room users to indicate to others that they are typi @Typing Indicators@ shall be exposed to consumers via the @typing@ property of a @Room@. * @(CHA-T1)@ Typing Indicators for a Room is exposed on a dedicated Realtime channel. These channels use the format @::$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. +* @(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-T2b1)@ @[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-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. * @(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. @@ -284,7 +312,7 @@ Typing Indicators allow chat room users to indicate to others that they are typi ** @(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, then the client leaves presence. Upon successful completion of the presence leave operation, the @CHA-T3@ timeout is cancelled. +** @(CHA-T5b)@ @[Testable]@ If typing is in progress, he @CHA-T3@ timeout is cancelled. The client then leaves presence. * @(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. From ad8934b382da697fbf1dea305853b92a1a6236a2 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Fri, 11 Oct 2024 14:48:11 +0100 Subject: [PATCH 12/73] additional chat room lifecycle clarifications --- textile/chat-features.textile | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 113c830b3..d4003a943 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -38,6 +38,7 @@ 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. @@ -78,6 +79,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-RL1h)@ 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-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. @@ -111,6 +113,8 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations * @(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)@ @[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-RL3c)@ @[Testable]@ When the release operation commences, the room will transition into the @RELEASING@ status any any transient disconnect timeouts shall be cleared. ** @(CHA-RL3d)@ @[Testable]@ All features channels are detached in sequence. @@ -128,6 +132,8 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations *** @(CHA-RL5f1)@ @[Testable]@ If the attachment cycle succeeds, then the room is transitioned to @ATTACHED@ and any discontinuity errors are broadcast to contributors. *** @(CHA-RL5f2)@ @[Testable]@ If the attachment cycle fails because a channel entered @FAILED@, then the room is transitioned to @FAILED@ and the retry loop terminates. *** @(CHA-RL5f3)@ @[Testable]@ If the attachment cycle fails because a channel entered @SUSPENDED@, then the room is transitioned to @SUSPENDED@ and the retry loop restarted using the @SUSPENDED@ channel as the subject. +* @(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. h4(#rooms-lifecycle-monitoring). Room Lifecycle Monitoring @@ -161,6 +167,7 @@ Each chat room can be configured individually, allowing options to be passed as ** @(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)@ 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-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. From 4e648d3766bc9b817912c5518687611a5344ab02 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Fri, 18 Oct 2024 14:37:45 +0100 Subject: [PATCH 13/73] chat: clarify room lifecycle operation precedence --- textile/chat-features.textile | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index d4003a943..35862d0ac 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -82,7 +82,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL1h)@ 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-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. +** @(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@. ** @(CHA-RL1e)@ @[Testable]@ Notwithstanding the above points, when the attachment operation begins, the room shall be transitioned to the @ATTACHING@ status. ** @(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. @@ -110,6 +110,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations *** @(CHA-RL2h1)@ @[Testable]@ If a channel enters the @FAILED@ state during detachment, then the room will transition to the @FAILED@ status. The detach operation continues until all channels are either @DETACHED@ or @FAILED@, with the operation throwing an @ErrorInfo@ with the feature-specific error code of the first feature to fail, using the underlying channel error 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 detachment cycle will be retried after a short pause. The rooms status will not change during this 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. @@ -122,6 +123,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL3f)@ @[Testable]@ If a channel fails to detach, the channel detach sequence will be retried after a short wait. ** @(CHA-RL3g)@ @[Testable]@ Once all channels have entered the @DETACHED@ state, then the room state is transitioned to @RELEASED@ and the operation completes. ** @(CHA-RL3h)@ @[Testable]@ Upon operation completion, the underlying Realtime Channels are released from the core SDK prevent leakage. +** @(CHA-RL3i)@ @[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-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. ** @(CHA-RL5a)@ @[Testable]@ When entering a retry-loop, the room must first @DETACH@ all contributors underlying realtime channels. ** @(CHA-RL5b)@ @[Testable]@ If the operation above fails, then it must be retried after a short wait. @@ -134,6 +136,11 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations *** @(CHA-RL5f3)@ @[Testable]@ If the attachment cycle fails because a channel entered @SUSPENDED@, then the room is transitioned to @SUSPENDED@ and the retry loop restarted using the @SUSPENDED@ channel as the subject. * @(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-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. +*** @(CHA-RL7a2)@ The @RELEASE@ operation. +*** @(CHA-RL7a3)@ The @ATTACH@ and @DETACH@ operations have equal precedence. h4(#rooms-lifecycle-monitoring). Room Lifecycle Monitoring From cb40920c550ddb1239fd94b0432f9c475cc2a643 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Fri, 18 Oct 2024 15:13:05 +0100 Subject: [PATCH 14/73] chat: add occupancy spec --- textile/chat-features.textile | 40 +++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 35862d0ac..af0418232 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -335,6 +335,24 @@ Typing Indicators allow chat room users to indicate to others that they are typi *** @(CHA-T6c2)@ @[Testable]@ If multiple presence events are received resulting in concurrent @presence.get()@ calls, then we guarantee that only the "latest" event is emitted. That is to say, if presence event A and B occur in that order, then only the typing event generated by B's call to @presence.get()@ will be emitted to typing subscribers. * @(CHA-T7)@ @[Testable]@ Users may subscribe to discontinuity events to know when there's been a break in typing indicators. Their listener will be called when a discontinuity event is triggered from the room lifecycle. For typing, there shouldn't need to be user action as the underlying core SDK will heal the presence set. +h2(#occupancy). Occupancy + +Occupancy allows chat room users to find out how many people are currently online in the Chat Room, which is useful for showing statistics such as the viewer count in a livestream. It allows this to happen without +the overhead of having everyone in presence. + +@Occupancy@ shall be exposed to consumers via the @occupancy@ property of a @Room@. + +* @(CHA-O1)@ Occupancy for a room is exposed on the realtime channel used for chat messages, in the format @::$chat::$chatMessages@. For example, if your room id is @my-room@ then the presence channel will be @my-room::$chat::$chatMessages@. +* @(CHA-O2)@ The occupancy event format is shown "here":#chat-structs-occupancy-event +* @(CHA-O3)@ @[Testable]@ Users can request an instantaneous occupancy check via the REST API. The request is detailed "here":#rest-occupancy-request, with the response format being a simple "occupancy event":#chat-structs-occupancy-event +* @(CHA-O4)@ Users can subscribe to in-band, realtime occupancy updates. +** @(CHA-04a)@ @[Testable]@ Users may register a listener that receives occupancy events in realtime. +** @(CHA-04b)@ @[Testable]@ A subscription to occupancy events may be removed, after which it shall receive no further events. +** @(CHA-04c)@ @[Testable]@ When a regular occupancy event is received on the channel (a standard PubSub occupancy event per the docs), the SDK will convert it into "occupancy event":#chat-structs-occupancy-event format and broadcast it to subscribers. +** @(CHA-04d)@ @[Testable]@ If an invalid occupancy event is received on the channel, it shall be dropped. +to typing subscribers. +* @(CHA-O5)@ @[Testable]@ Users may subscribe to discontinuity events to know when there's been a break in occupancy. Their listener will be called when a discontinuity event is triggered from the room lifecycle. For occupancy, there shouldn't need to be user action as most channels will send occupancy updates regularly as clients churn. + h2(#rest-api). Chat HTTP REST API h3(#rest-general). General @@ -415,6 +433,7 @@ h4(#rest-fetching-messages-response). Response An array of "@Message@ structs":#chat-structs-message + h2(#realtime-api). Chat Realtime API This section describes the message formats for chat events that occur over a Realtime connection. @@ -442,6 +461,18 @@ h3(#realtime-room-reactions). Ephemeral Room Reactions } +h3(#rest-occupancy). Occupancy + +h4(#rest-occupancy-request). Request + +
+  GET /chat/v1/rooms//occupancy
+
+ +h4(#rest-occupancy-response). Response + +An "@OccupancyEvent@ struct":#chat-structs-occupancy + h2(#chat-structs). Chat Structs and Types @@ -542,6 +573,15 @@ h3(#chat-structs-typing-event). Typing Event } +h3(#chat-structs-occupancy-event). Occupancy Event + +
+  {
+    "connections": 5,
+    "presenceMembers" 2,
+  }
+
+ h2(#error-codes). Chat-specific Error Codes This section contains error codes that are specific to Chat. If a specific error code is not listed for a given circumstance, the most appropriate general error code shall be used. For example @400xx@ for client errors or @500xx@ for server errors. From 4014a30fef37982bf529fe069cfdf19fe5592b19 Mon Sep 17 00:00:00 2001 From: Steven Lindsay Date: Wed, 23 Oct 2024 13:41:14 +0100 Subject: [PATCH 15/73] materialization: Remove reserved namespace from metadata and headers. - As of [CHADR-066], it was decided that metadata and headers will no longer have the reserved `ably-chat` namespace. - Removed this for both chat messages and room reactions. --- textile/chat-features.textile | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index af0418232..6e141a62f 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -196,9 +196,7 @@ Broadly speaking, messages are published via REST calls to the Chat HTTP API and * @(CHA-M3)@ Messages are sent to Ably via the Chat REST API, using the @send@ method. ** @(CHA-M3a)@ @[Testable]@ When a message is sent successfully, the caller shall receive a struct representing the "@Message@":#chat-structs-message in response (as if it were received via Realtime event). ** @(CHA-M3b)@ @[Testable]@ A message may be sent without @metadata@ or @headers@. When these are not specified by the user, they must be omitted from the REST payload. -** @(CHA-M3c)@ @[Testable]@ @metadata@ must not contain the key @ably-chat@. This is reserved for future internal use. If this key is present, the send call shall terminate by throwing an @ErrorInfo@ with code @40001@. -** @(CHA-M3d)@ @[Testable]@ @headers@ must not contain a key prefixed with @ably-chat@. This is reserved for future internal use. If this key is present, the send call shall terminate by throwing an @ErrorInfo@ with code @40001@. -** @(CHA-M3e)@ @[Testable]@ If an error is returned from the REST API, its @ErrorInfo@ representation shall be thrown as the result of the @send@ call. +** @(CHA-M3c)@ @[Testable]@ If an error is returned from the REST API, its @ErrorInfo@ representation shall be thrown as the result of the @send@ call. * @(CHA-M4)@ Messages can be received via a subscription in realtime. ** @(CHA-M4a)@ @[Testable]@ A subscription can be registered to receive incoming messages. Adding a subscription has no side effects on the status of the room or the underlying realtime channel. ** @(CHA-M4b)@ @[Testable]@ A subscription can de-registered from incoming messages. Removing a subscription has no side effects on the status of the room or the underlying realtime channel. @@ -235,8 +233,6 @@ All ephemeral room reactions are handled over the Realtime connection. * @(CHA-ER2)@ A @Reaction@ corresponds to a single reaction in a chat room. This is analogous to a single user-specified message on an Ably channel (NOTE: **not** a @ProtocolMessage@). * @(CHA-ER3)@ Ephemeral room reactions are sent to Ably via the Realtime connection via a @send@ method. ** @(CHA-ER3a)@ @[Testable]@ Reactions are sent on the channel using a message in "this format":#realtime-room-reactions. -** @(CHA-ER3b)@ @[Testable]@ @metadata@ must not contain the key @ably-chat@. This is reserved for future internal use. If this key is present, the @send@ call shall terminate by throwing an @ErrorInfo@ with code @40001@. -** @(CHA-ER3c)@ @[Testable]@ @headers@ must not contain a key prefixed with @ably-chat@. This is reserved for future internal use. If this key is present, the send call shall terminate by throwing an @ErrorInfo@ with code @40001@. * @(CHA-ER4)@ A user may subscribe to reaction events in Realtime. ** @(CHA-ER4a)@ @[Testable]@ A user may provide a listener to subscribe to reaction events. This operation must have no side-effects in relation to room or underlying status. When a "realtime message":#realtime-room-reactions with name @roomReaction@ is received, this message is converted into a "reaction object":#chat-structs-ephemeral-reactions and emitted to subscribers. ** @(CHA-ER4b)@ @[Testable]@ A user may unsubscribe a registered listener. This operation must have no side-effects in relation to room or underlying status. Once unsubscribed, subsequent reaction events must not be emitted to this listener. From 210c95626f37e60e0e5eaa1d97a3c1ca15d940b5 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Wed, 30 Oct 2024 13:54:55 -0300 Subject: [PATCH 16/73] Restore CHA-M3e MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Revert 6118c46’s rename of this spec point, which it did after deleting some spec points. We should be avoiding renaming spec points where possible, because we already have SDK implementations referring to these points. --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 6e141a62f..bbcf81663 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -196,7 +196,7 @@ Broadly speaking, messages are published via REST calls to the Chat HTTP API and * @(CHA-M3)@ Messages are sent to Ably via the Chat REST API, using the @send@ method. ** @(CHA-M3a)@ @[Testable]@ When a message is sent successfully, the caller shall receive a struct representing the "@Message@":#chat-structs-message in response (as if it were received via Realtime event). ** @(CHA-M3b)@ @[Testable]@ A message may be sent without @metadata@ or @headers@. When these are not specified by the user, they must be omitted from the REST payload. -** @(CHA-M3c)@ @[Testable]@ If an error is returned from the REST API, its @ErrorInfo@ representation shall be thrown as the result of the @send@ call. +** @(CHA-M3e)@ @[Testable]@ If an error is returned from the REST API, its @ErrorInfo@ representation shall be thrown as the result of the @send@ call. * @(CHA-M4)@ Messages can be received via a subscription in realtime. ** @(CHA-M4a)@ @[Testable]@ A subscription can be registered to receive incoming messages. Adding a subscription has no side effects on the status of the room or the underlying realtime channel. ** @(CHA-M4b)@ @[Testable]@ A subscription can de-registered from incoming messages. Removing a subscription has no side effects on the status of the room or the underlying realtime channel. From 9f517da0da642378741978046a8a7a90576e2ae7 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Tue, 17 Sep 2024 16:10:02 -0300 Subject: [PATCH 17/73] Update duplicate-finding script to handle Chat too MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit That is, multiple spec files and hyphens in spec point identifiers. Rename the existing duplicates (I’ll add a comment on the PR so that consumers of the spec can update their implementations.) --- scripts/find-duplicate-spec-items | 41 ++++++++++++++++++++----------- textile/chat-features.textile | 24 +++++++++--------- 2 files changed, 39 insertions(+), 26 deletions(-) diff --git a/scripts/find-duplicate-spec-items b/scripts/find-duplicate-spec-items index 977e4f765..1185731a7 100755 --- a/scripts/find-duplicate-spec-items +++ b/scripts/find-duplicate-spec-items @@ -3,20 +3,33 @@ # Script to detect duplicate spec IDs in the client library spec # This tends to happen when concurrent spec PRs are merged -SPEC_PATH = File.expand_path('../../textile/features.textile', __FILE__) - -File.read(SPEC_PATH).scan(/\*\s\@\((\w+)\)\@/).group_by do |match| - match -end.select do |spec_id, matches| - matches.count > 1 -end.each do |spec_id, matches| - puts "#{spec_id.first} has #{matches.count - 1} duplicate(s)" -end.tap do |matches| - if matches.empty? - puts "✓ Spec is valid. No duplicates found" - else - puts "\n✘ INVALID SPEC: #{matches.count} duplicate(s) found" - exit 1 +SPEC_FILES = ["features", "chat-features"] + +has_errors = false + +SPEC_FILES.each_with_index do |spec_file, i| + file_name = "#{spec_file}.textile" + + puts "Checking #{file_name}" + + spec_path = File.expand_path("../../textile/#{file_name}", __FILE__) + + File.read(spec_path).scan(/\*\s\@\(([\w-]+)\)\@/).group_by do |match| + match + end.select do |spec_id, matches| + matches.count > 1 + end.each do |spec_id, matches| + puts "#{spec_id.first} has #{matches.count - 1} duplicate(s)" + end.tap do |matches| + if matches.empty? + puts "✓ Spec is valid. No duplicates found" + else + puts "\n✘ INVALID SPEC: #{matches.count} duplicate(s) found" + has_errors = true + end end + + puts if i < SPEC_FILES.count - 1 end +exit 1 if has_errors diff --git a/textile/chat-features.textile b/textile/chat-features.textile index bbcf81663..ff3349ce7 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -37,7 +37,7 @@ 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-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. @@ -79,7 +79,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-RL1h)@ 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)@ 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-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@. @@ -115,15 +115,15 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(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)@ @[Testable]@ If the room is in the @INITIALIZED@ status, then the room is immediately transitioned to @RELEASED@ and the operation succeeds. +** @(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-RL3c)@ @[Testable]@ When the release operation commences, the room will transition into the @RELEASING@ status any any transient disconnect timeouts shall be cleared. +** @(CHA-RL3l)@ @[Testable]@ When the release operation commences, the room will transition into the @RELEASING@ status any any transient disconnect timeouts shall be cleared. ** @(CHA-RL3d)@ @[Testable]@ All features channels are detached in sequence. ** @(CHA-RL3e)@ @[Testable]@ If a channel is in the @FAILED@ state when it is time to detach, it shall be ignored. ** @(CHA-RL3f)@ @[Testable]@ If a channel fails to detach, the channel detach sequence will be retried after a short wait. ** @(CHA-RL3g)@ @[Testable]@ Once all channels have entered the @DETACHED@ state, then the room state is transitioned to @RELEASED@ and the operation completes. ** @(CHA-RL3h)@ @[Testable]@ Upon operation completion, the underlying Realtime Channels are released from the core SDK prevent leakage. -** @(CHA-RL3i)@ @[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-RL3k)@ @[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-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. ** @(CHA-RL5a)@ @[Testable]@ When entering a retry-loop, the room must first @DETACH@ all contributors underlying realtime channels. ** @(CHA-RL5b)@ @[Testable]@ If the operation above fails, then it must be retried after a short wait. @@ -160,7 +160,7 @@ As well as user-initiated operations, the room must monitor its underlying resou *** @(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. -*** @(CHA-RL4b7)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @ATTACHED@ and a transient disconnect timeout exists for the contributor, the timeout is cleared. +*** @(CHA-RL4b10)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @ATTACHED@ and a transient disconnect timeout exists for the contributor, the timeout is cleared. *** @(CHA-RL4b8)@ @[Testable]@ If a channel lifecycle operation is not in progress, the channel state is @ATTACHED@, the room status is NOT @ATTACHED@ and all contibutors channel are now @ATTACHED@, the room status is transitioned to @ATTACHED@. *** @(CHA-RL4b9)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @SUSPENDED@, then the room status is transitioned to @SUSPENDED@, using the @reason@ of the channel state change as the error. Any transient disconnect timeouts are cancelled and the room enters the @RETRY@ loop. @@ -202,7 +202,7 @@ Broadly speaking, messages are published via REST calls to the Chat HTTP API and ** @(CHA-M4b)@ @[Testable]@ A subscription can de-registered from incoming messages. Removing a subscription has no side effects on the status of the room or the underlying realtime channel. ** @(CHA-M4c)@ @[Testable]@ When a realtime message with @name@ set to @message.created@ is received, it is translated into a message event, which contains a @type@ field with the event type as well as a @message@ field containing the "@Message Struct@":#chat-structs-message. This event is then broadcast to all subscribers. ** @(CHA-M4d)@ @[Testable]@ If a realtime message with an unknown @name@ is received, the SDK shall silently discard the message, though it may log at @DEBUG@ or @TRACE@ level. -** @(CHA-M5d)@ @[Testable]@ Incoming realtime events that are malformed (unknown field should be ignored) shall not be emitted to subscribers. +** @(CHA-M5k)@ @[Testable]@ Incoming realtime events that are malformed (unknown field should be ignored) shall not be emitted to subscribers. * @(CHA-M5)@ For a given subscription, messages prior to the point of subscription can be retrieved in a history-like request. Note that this is the point in the message flow @(subscription point)@ at which the subscription was made, NOT the channel attachment point. ** @(CHA-M5a)@ @[Testable]@ If a subscription is added when the underlying realtime channel is @ATTACHED@, then the @subscription point@ is the current @channelSerial@ of the realtime channel. ** @(CHA-M5b)@ @[Testable]@ If a subscription is added when the underlying realtime channel is in any other state, then its @subscription point@ becomes the @attachSerial@ at the the point of channel attachment. @@ -263,7 +263,7 @@ Presence allows chat room users to indicate to others that they're online, as we ** @(CHA-PR3b)@ This specification item has been removed in favour of @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-PR3c1)@ @[Testable]@ If the attach has not been called, then the @enter@ call will throw an error. +*** @(CHA-PR3c2)@ @[Testable]@ If the attach has not been called, then the @enter@ call will throw an error. ** @(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. @@ -273,7 +273,7 @@ Presence allows chat room users to indicate to others that they're online, as we ** @(CHA-PR10b)@ @[Testable]@ This specification item has been removed in favour of @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-PR10c1)@ @[Testable]@ If the attach has not been called, then the @update@ call will throw an error. +*** @(CHA-PR10c2)@ @[Testable]@ If the attach has not been called, then the @update@ call will throw an error. ** @(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. @@ -285,7 +285,7 @@ Presence allows chat room users to indicate to others that they're online, as we ** @(CHA-PR6a)@ @[Testable] This requirement has been removed in favour of @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-PR6b1)@ @[Testable]@ If the attach has not been called, then the @get@ call will throw an error. +*** @(CHA-PR6b2)@ @[Testable]@ If the attach has not been called, then the @get@ call will throw an error. ** @(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. @@ -293,7 +293,7 @@ Presence allows chat room users to indicate to others that they're online, as we * @(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. -** @(CHA-PR7b)@ @[Testable]@ A subscription to presence may be removed, after which it shall receive no further events. +** @(CHA-PR7c)@ @[Testable]@ A subscription to presence may be removed, after which it shall receive no further events. * @(CHA-PR8)@ @[Testable]@ Users may subscribe to discontinuity events to know when there's been a break in presence. Their listener will be called when a discontinuity event is triggered from the room lifecycle. For presence, there shouldn't need to be user action as the underlying core SDK will heal the presence set. * @(CHA-PR9)@ Users may configure their presence options via the @RoomOptions@ provided at room configuration time. ** @(CHA-PR9a)@ @[Testable]@ Setting @enter@ to false prevents the user from entering presence by means of the @ChannelMode@ on the underlying realtime channel. Entering presence will result in an error. The default is true. @@ -309,7 +309,7 @@ Typing Indicators allow chat room users to indicate to others that they are typi * @(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-T2b1)@ @[Testable]@ If the attach has not been called, then the @get@ call will throw an error. +*** @(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-T2e)@ @[Testable]@ If the room status is @Detached@, an @ErrorInfo@ with code 40000, explaining that attach must be called first, will be thrown. From 46b503af11aea228d98d3968b4e284e1405408ca Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Wed, 30 Oct 2024 16:17:01 -0300 Subject: [PATCH 18/73] Restore IDs of deleted spec points MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These spec points were deleted in 6118c46; restore their IDs so that we don’t accidentally reuse these identifiers, and so that these don’t look like invalid IDs in the Swift repo (where these spec points had been implemented). I’ve used the same language as in CONTRIBUTING.md for deleting these spec points (so that automated tools know they should consider these spec points as deleted), but I don’t have anything to put for the “it was valid up to and including” part. --- textile/chat-features.textile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index ff3349ce7..2f357c0fc 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -196,6 +196,8 @@ Broadly speaking, messages are published via REST calls to the Chat HTTP API and * @(CHA-M3)@ Messages are sent to Ably via the Chat REST API, using the @send@ method. ** @(CHA-M3a)@ @[Testable]@ When a message is sent successfully, the caller shall receive a struct representing the "@Message@":#chat-structs-message in response (as if it were received via Realtime event). ** @(CHA-M3b)@ @[Testable]@ A message may be sent without @metadata@ or @headers@. When these are not specified by the user, they must be omitted from the REST payload. +** @(CHA-M3c)@ This clause has been deleted. +** @(CHA-M3d)@ This clause has been deleted. ** @(CHA-M3e)@ @[Testable]@ If an error is returned from the REST API, its @ErrorInfo@ representation shall be thrown as the result of the @send@ call. * @(CHA-M4)@ Messages can be received via a subscription in realtime. ** @(CHA-M4a)@ @[Testable]@ A subscription can be registered to receive incoming messages. Adding a subscription has no side effects on the status of the room or the underlying realtime channel. @@ -233,6 +235,8 @@ All ephemeral room reactions are handled over the Realtime connection. * @(CHA-ER2)@ A @Reaction@ corresponds to a single reaction in a chat room. This is analogous to a single user-specified message on an Ably channel (NOTE: **not** a @ProtocolMessage@). * @(CHA-ER3)@ Ephemeral room reactions are sent to Ably via the Realtime connection via a @send@ method. ** @(CHA-ER3a)@ @[Testable]@ Reactions are sent on the channel using a message in "this format":#realtime-room-reactions. +** @(CHA-ER3b)@ This clause has been deleted. +** @(CHA-ER3c)@ This clause has been deleted. * @(CHA-ER4)@ A user may subscribe to reaction events in Realtime. ** @(CHA-ER4a)@ @[Testable]@ A user may provide a listener to subscribe to reaction events. This operation must have no side-effects in relation to room or underlying status. When a "realtime message":#realtime-room-reactions with name @roomReaction@ is received, this message is converted into a "reaction object":#chat-structs-ephemeral-reactions and emitted to subscribers. ** @(CHA-ER4b)@ @[Testable]@ A user may unsubscribe a registered listener. This operation must have no side-effects in relation to room or underlying status. Once unsubscribed, subsequent reaction events must not be emitted to this listener. From bd7094622b1d8728c63417f9ba333d2689eee79c Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Wed, 30 Oct 2024 16:30:01 -0300 Subject: [PATCH 19/73] =?UTF-8?q?Don=E2=80=99t=20mark=20deleted=20clauses?= =?UTF-8?q?=20as=20Testable?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit So as not to confuse automated tools that assess an implementation’s spec coverage (such as the one I’m currently writing for Swift). --- textile/chat-features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 2f357c0fc..bf23495c0 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -274,7 +274,7 @@ Presence allows chat room users to indicate to others that they're online, as we ** @(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)@ @[Testable]@ This specification item has been removed in favour of @CHA-PR10c - CHA-PR10g@. +** @(CHA-PR10b)@ This specification item has been removed in favour of @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. @@ -286,7 +286,7 @@ Presence allows chat room users to indicate to others that they're online, as we ** @(CHA-PR4a)@ @[Testable]@ Users may choose to leave presence, which results in them being removed from the Realtime presence set. * @(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)@ @[Testable] This requirement has been removed in favour of @CHA-PR6b - CHA-PR6f@ +** @(CHA-PR6a)@ This requirement has been removed in favour of @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. From 36a1cf210c6c43d6d41190b596366898950d7654 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Wed, 30 Oct 2024 16:49:28 -0300 Subject: [PATCH 20/73] Fix language for replaced spec points Used the same language as 9d8cb43. --- textile/chat-features.textile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index bf23495c0..b3741c4d5 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -264,7 +264,7 @@ 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 specification item has been removed in favour of @CHA-PR3c - CHA-PR3g@. +** @(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. @@ -274,7 +274,7 @@ Presence allows chat room users to indicate to others that they're online, as we ** @(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 specification item has been removed in favour of @CHA-PR10c - CHA-PR10g@. +** @(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. @@ -286,7 +286,7 @@ Presence allows chat room users to indicate to others that they're online, as we ** @(CHA-PR4a)@ @[Testable]@ Users may choose to leave presence, which results in them being removed from the Realtime presence set. * @(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 requirement has been removed in favour of @CHA-PR6b - CHA-PR6f@ +** @(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. From 71440ba42a65782864ee4db1e3afcdab44667aeb Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:20:31 +0000 Subject: [PATCH 21/73] clarify status codes accompanying chat specific errors --- textile/chat-features.textile | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index b3741c4d5..c547f2202 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -586,56 +586,74 @@ h2(#error-codes). Chat-specific Error Codes This section contains error codes that are specific to Chat. If a specific error code is not listed for a given circumstance, the most appropriate general error code shall be used. For example @400xx@ for client errors or @500xx@ for server errors. +For non-chat-specific codes, the status code for the error should align with the error code. For example, error code @40000@ should hav status code @400@. + 
   // The messages feature failed to attach.
+  // To be accompanied with status code 500.
   MessagesAttachmentFailed = 102001
 
   // The presence feature failed to attach.
+  // To be accompanied with status code 500.
   PresenceAttachmentFailed = 102002
 
   // The reactions feature failed to attach.
+  // To be accompanied with status code 500.
   ReactionsAttachmentFailed = 102003
 
   // The occupancy feature failed to attach.
+  // To be accompanied with status code 500.
   OccupancyAttachmentFailed = 102004
 
   // The typing feature failed to attach.
+  // To be accompanied with status code 500.
   TypingAttachmentFailed = 102005
   // 102006 - 102049 reserved for future use for attachment errors
 
   // The messages feature failed to detach.
+  // To be accompanied with status code 500.
   MessagesDetachmentFailed = 102050
 
   // The presence feature failed to detach.
+  // To be accompanied with status code 500.
   PresenceDetachmentFailed = 102051
 
   // The reactions feature failed to detach.
+  // To be accompanied with status code 500.
   ReactionsDetachmentFailed = 102052
 
   // The occupancy feature failed to detach.
+  // To be accompanied with status code 500.
   OccupancyDetachmentFailed = 102053
 
   // The typing feature failed to detach.
+  // To be accompanied with status code 500.
   TypingDetachmentFailed = 102054
   // 102055 - 102099 reserved for future use for detachment errors
 
   // The room has experienced a discontinuity.
+  // To be accompanied with status code 500.
   RoomDiscontinuity = 102100
 
   // Unable to perform operation;
 
   // Cannot perform operation because the room is in a failed state.
+  // To be accompanied with status code 400.
   RoomInFailedState = 102101
 
   // Cannot perform operation because the room is in a releasing state.
+  // To be accompanied with status code 400.
   RoomIsReleasing = 102102
 
   // Cannot perform operation because the room is in a released state.
+  // To be accompanied with status code 400.
   RoomIsReleased = 102103
 
   // Cannot perform operation because the previous operation failed.
+  // To be accompanied with status code 500.
   PreviousOperationFailed = 102104
 
   // An unknown error has happened in the room lifecycle.
+  // To be accompanied with status code 500.
   RoomLifecycleError = 102105
From b8eb314cbd163dd1e38b997562c9c0b5fa9a078f Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:23:09 +0000 Subject: [PATCH 22/73] clarify CHA-RL1h2 error --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index c547f2202..0f2054f6c 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -91,7 +91,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations *** @(CHA-RL1g3)@ @[Testable]@ Any transient disconnect timeouts shall be cleared. ** @(CHA-RL1h)@ If a one of the @contributors@ Realtime Channels fails to attach (i.e. the call to @attach()@ returns an error), then the operation has failed and must be rolled back. The procedure to roll back is described in subsequent points. *** @(CHA-RL1h1)@ @[Testable]@ The @attach@ call must throw an @ErrorInfo@. The code for this error is determined by the feature that failed (see "here":#error-codes for more information on error codes). -*** @(CHA-RL1h2)@ @[Testable]@ If the underlying Realtime Channel entered the @SUSPENDED@ state (i.e. the @attach()@ operation fails and upon subsequently checking the channel state, it is @SUSPENDED@), then the room status will transition to @SUSPENDED@. The state transition @ErrorInfo@ will use the Realtime Channel error as the @cause@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. +*** @(CHA-RL1h2)@ @[Testable]@ If the underlying Realtime Channel entered the @SUSPENDED@ state (i.e. the @attach()@ operation fails and upon subsequently checking the channel state, it is @SUSPENDED@), then the room status will transition to @SUSPENDED@. The state transition @ErrorInfo@ will use the error from the realtime channels `attach()` as the @cause@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. *** @(CHA-RL1h3)@ @[Testable]@ When the room enters the @SUSPENDED@ status as a result of @CHA-RL1h2@ the @attach()@ operation shall fail using the error from @CHA-RL1h2@. The room lifecycle shall asynchronously (non-blocking to the @ATTACH@ operation) enter the recovery loop (per "@CHA-RL5@":#CHA-RL5) and attempt to re-establish attachment. *** @(CHA-RL1h4)@ @[Testable]@ If the underlying Realtime Channel entered the @FAILED@ state, then the room status will transition to @FAILED@, using the error from the realtime channels `attach()` call as the @cause@ field of the @ErrorInfo@. The state transition @ErrorInfo@ will use the Realtime Channel error as the @cause@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. The same error shall be thrown as the result of the @ATTACH@ operation. *** @(CHA-RL1h5)@ @[Testable]@ When the room enters the @FAILED@ status as a result of @CHA-RL1h4@, asynchronously with respect to @CHA-RL1h4@, then the room will detach all channels that are not in the @FAILED@ state. From dd9c009aabcd874a4b6ebd8733c217799d67817c Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:24:32 +0000 Subject: [PATCH 23/73] CHA-RL1h4: remove duplicate text --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 0f2054f6c..4271bb655 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -93,7 +93,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations *** @(CHA-RL1h1)@ @[Testable]@ The @attach@ call must throw an @ErrorInfo@. The code for this error is determined by the feature that failed (see "here":#error-codes for more information on error codes). *** @(CHA-RL1h2)@ @[Testable]@ If the underlying Realtime Channel entered the @SUSPENDED@ state (i.e. the @attach()@ operation fails and upon subsequently checking the channel state, it is @SUSPENDED@), then the room status will transition to @SUSPENDED@. The state transition @ErrorInfo@ will use the error from the realtime channels `attach()` as the @cause@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. *** @(CHA-RL1h3)@ @[Testable]@ When the room enters the @SUSPENDED@ status as a result of @CHA-RL1h2@ the @attach()@ operation shall fail using the error from @CHA-RL1h2@. The room lifecycle shall asynchronously (non-blocking to the @ATTACH@ operation) enter the recovery loop (per "@CHA-RL5@":#CHA-RL5) and attempt to re-establish attachment. -*** @(CHA-RL1h4)@ @[Testable]@ If the underlying Realtime Channel entered the @FAILED@ state, then the room status will transition to @FAILED@, using the error from the realtime channels `attach()` call as the @cause@ field of the @ErrorInfo@. The state transition @ErrorInfo@ will use the Realtime Channel error as the @cause@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. The same error shall be thrown as the result of the @ATTACH@ operation. +*** @(CHA-RL1h4)@ @[Testable]@ If the underlying Realtime Channel entered the @FAILED@ state, then the room status will transition to @FAILED@, using the error from the realtime channels `attach()` call as the @cause@ field of the @ErrorInfo@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. The same error shall be thrown as the result of the @ATTACH@ operation. *** @(CHA-RL1h5)@ @[Testable]@ When the room enters the @FAILED@ status as a result of @CHA-RL1h4@, asynchronously with respect to @CHA-RL1h4@, then the room will detach all channels that are not in the @FAILED@ state. *** @(CHA-RL1h6)@ @[Testable]@ If, when performing @CHA-RL1h5@, a channel fails to detach on command, then the detach operation will be repeated until such a time that all channels have detached successfully. ** @(CHA-RL1i)@ Because of the singleton pattern that the core SDKs implement with regards to channels, subsequent instances of a room will use the same underlying realtime channels if the realtime channels are not properly @released@ as part of cleaning up the previous room instance before the new instance is used. Therefore, it is important to ensure that releasing operations (per "@CHA-RC1d@"#CHA-RC1d) have completed before a new room can be attached (to avoid channel objects leaking between instances of rooms). From fdf195ad946c9faab1fce6265d21c509206f32ed Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:25:55 +0000 Subject: [PATCH 24/73] CHA-RL2h1: clarify failed state entry --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 4271bb655..83739eb7f 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -107,7 +107,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL2f)@ @[Testable]@ The underlying @contributors@ Realtime Channels will be detached in sequence - a call to @detach()@ must complete before the next call begins. ** @(CHA-RL2g)@ @[Testable]@ If all channel detachments complete successfully (all calls @detach()@ return successfully), then the room shall transition to the @DETACHED@ status. ** @(CHA-RL2h)@ If during detachment, a channel fails to detach, different operations are performed based on the nature of the detach. -*** @(CHA-RL2h1)@ @[Testable]@ If a channel enters the @FAILED@ state during detachment, then the room will transition to the @FAILED@ status. The detach operation continues until all channels are either @DETACHED@ or @FAILED@, with the operation throwing an @ErrorInfo@ with the feature-specific error code of the first feature to fail, using the underlying channel error as the @cause@. The same @ErrorInfo@ must accompany the @FAILED@ room status. +*** @(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 all channels are either @DETACHED@ or @FAILED@, with the operation throwing an @ErrorInfo@ with the feature-specific error code of the first feature to fail, using the underlying channel error 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 detachment cycle will be retried after a short pause. The rooms status will not change during this 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@. From bc88743e69fd629d1607ccc6a3e2b62a46e60063 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:27:45 +0000 Subject: [PATCH 25/73] CHA-RL2h: clarify detach failure --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 83739eb7f..6cfe761e2 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -106,7 +106,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL2e)@ @[Testable]@ Notwithstanding the above points, when the detachment operation begins, the room shall be transitioned to the @DETACHING@ status and any transient disconnect timeouts cleared. ** @(CHA-RL2f)@ @[Testable]@ The underlying @contributors@ Realtime Channels will be detached in sequence - a call to @detach()@ must complete before the next call begins. ** @(CHA-RL2g)@ @[Testable]@ If all channel detachments complete successfully (all calls @detach()@ return successfully), then the room shall transition to the @DETACHED@ status. -** @(CHA-RL2h)@ If during detachment, a channel fails to detach, different operations are performed based on the nature of the detach. +** @(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 all channels are either @DETACHED@ or @FAILED@, with the operation throwing an @ErrorInfo@ with the feature-specific error code of the first feature to fail, using the underlying channel error 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 detachment cycle will be retried after a short pause. The rooms status will not change during this process. From 4ac726086823e4d797b371f2fea98ebc1ca0d2b7 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:30:15 +0000 Subject: [PATCH 26/73] CHA-RL2h1: clarify meaning of detachment --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 6cfe761e2..277518320 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -107,7 +107,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL2f)@ @[Testable]@ The underlying @contributors@ Realtime Channels will be detached in sequence - a call to @detach()@ must complete before the next call begins. ** @(CHA-RL2g)@ @[Testable]@ If all channel detachments complete successfully (all calls @detach()@ return successfully), then the room shall transition to the @DETACHED@ status. ** @(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 all channels are either @DETACHED@ or @FAILED@, with the operation throwing an @ErrorInfo@ with the feature-specific error code of the first feature to fail, using the underlying channel error as the @cause@. The same @ErrorInfo@ must accompany the @FAILED@ room status. +*** @(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 underlying channel error 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 detachment cycle will be retried after a short pause. The rooms status will not change during this 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@. From 6394ca27d3780abdbb9727f00a232567ea327994 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:34:30 +0000 Subject: [PATCH 27/73] CHA-RL2h1: clarify error usage --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 277518320..d3958d197 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -107,7 +107,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL2f)@ @[Testable]@ The underlying @contributors@ Realtime Channels will be detached in sequence - a call to @detach()@ must complete before the next call begins. ** @(CHA-RL2g)@ @[Testable]@ If all channel detachments complete successfully (all calls @detach()@ return successfully), then the room shall transition to the @DETACHED@ status. ** @(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 underlying channel error as the @cause@. The same @ErrorInfo@ must accompany the @FAILED@ room status. +*** @(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 detachment cycle will be retried after a short pause. The rooms status will not change during this 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@. From ba4f075cc09a7684342e44a2ec4b89398f1a1ca2 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:39:40 +0000 Subject: [PATCH 28/73] CHA-RL2h3: clarify relation to CHA-RL2f --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index d3958d197..352bef726 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -109,7 +109,7 @@ 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 detachment cycle will be retried after a short pause. The rooms status will not change during this process. +*** @(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 short 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-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. From 2a81e856ee84e916fdfaae4c7240fec5fef2b0d5 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:43:16 +0000 Subject: [PATCH 29/73] CHA-RL2h3: specify pause duration --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 352bef726..e0f721ed0 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -109,7 +109,7 @@ 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 short 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]@ 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-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. From ab828f6e525de011cf3bb9b049df22c6eb7c7537 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:43:53 +0000 Subject: [PATCH 30/73] CHA-RL3d: make statement a MUST --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index e0f721ed0..303e51b44 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -118,7 +118,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(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 any any transient disconnect timeouts shall be cleared. -** @(CHA-RL3d)@ @[Testable]@ All features channels are detached in sequence. +** @(CHA-RL3d)@ @[Testable]@ All features channels must be detached in sequence. ** @(CHA-RL3e)@ @[Testable]@ If a channel is in the @FAILED@ state when it is time to detach, it shall be ignored. ** @(CHA-RL3f)@ @[Testable]@ If a channel fails to detach, the channel detach sequence will be retried after a short wait. ** @(CHA-RL3g)@ @[Testable]@ Once all channels have entered the @DETACHED@ state, then the room state is transitioned to @RELEASED@ and the operation completes. From d2c8f8ad449ec8bfd32c7962d3b970afeb03b875 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:44:27 +0000 Subject: [PATCH 31/73] CHA-RL3f: specify delay --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 303e51b44..3ec17d3ac 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -120,7 +120,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL3l)@ @[Testable]@ When the release operation commences, the room will transition into the @RELEASING@ status any any transient disconnect timeouts shall be cleared. ** @(CHA-RL3d)@ @[Testable]@ All features channels must be detached in sequence. ** @(CHA-RL3e)@ @[Testable]@ If a channel is in the @FAILED@ state when it is time to detach, it shall be ignored. -** @(CHA-RL3f)@ @[Testable]@ If a channel fails to detach, the channel detach sequence will be retried after a short wait. +** @(CHA-RL3f)@ @[Testable]@ If a channel fails to detach, the channel detach sequence will be retried after a 250ms delay. ** @(CHA-RL3g)@ @[Testable]@ Once all channels have entered the @DETACHED@ state, then the room state is transitioned to @RELEASED@ and the operation completes. ** @(CHA-RL3h)@ @[Testable]@ Upon operation completion, the underlying Realtime Channels are released from the core SDK prevent leakage. ** @(CHA-RL3k)@ @[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@. From b2087019f0c7b7054c66e7e5c5416db668141574 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:46:24 +0000 Subject: [PATCH 32/73] CHA-RL3f: clarify relation to CHA-RL3d --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 3ec17d3ac..c8c3e3d65 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -120,7 +120,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL3l)@ @[Testable]@ When the release operation commences, the room will transition into the @RELEASING@ status any any transient disconnect timeouts shall be cleared. ** @(CHA-RL3d)@ @[Testable]@ All features channels must be detached in sequence. ** @(CHA-RL3e)@ @[Testable]@ If a channel is in the @FAILED@ state when it is time to detach, it shall be ignored. -** @(CHA-RL3f)@ @[Testable]@ If a channel fails to detach, the channel detach sequence will be retried after a 250ms delay. +** @(CHA-RL3f)@ @[Testable]@ If a channel fails to detach (i.e. the call to @detach()@ returns an error), the @CHA-RL3d@ channel detach sequence will be retried after a 250ms delay. ** @(CHA-RL3g)@ @[Testable]@ Once all channels have entered the @DETACHED@ state, then the room state is transitioned to @RELEASED@ and the operation completes. ** @(CHA-RL3h)@ @[Testable]@ Upon operation completion, the underlying Realtime Channels are released from the core SDK prevent leakage. ** @(CHA-RL3k)@ @[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@. From 7f1de9daabde32c0c403654b02568012ea3759f3 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:47:48 +0000 Subject: [PATCH 33/73] CHA-RL3f: clarify relation to CHA-RL3g --- textile/chat-features.textile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index c8c3e3d65..a4373e684 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -111,7 +111,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations *** @(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-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-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. @@ -120,8 +120,8 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL3l)@ @[Testable]@ When the release operation commences, the room will transition into the @RELEASING@ status any any transient disconnect timeouts shall be cleared. ** @(CHA-RL3d)@ @[Testable]@ All features channels must be detached in sequence. ** @(CHA-RL3e)@ @[Testable]@ If a channel is in the @FAILED@ state when it is time to detach, it shall be ignored. -** @(CHA-RL3f)@ @[Testable]@ If a channel fails to detach (i.e. the call to @detach()@ returns an error), the @CHA-RL3d@ channel detach sequence will be retried after a 250ms delay. -** @(CHA-RL3g)@ @[Testable]@ Once all channels have entered the @DETACHED@ state, then the room state is transitioned to @RELEASED@ and the operation completes. +** @(CHA-RL3f)@ @[Testable]@ If a channel fails to detach (i.e. the call to @detach()@ returns an error), the @CHA-RL3d@ channel detach sequence will be retried after a 250ms delay. Retries are continued until @CHA-RL3g@ is met. +** @(CHA-RL3g)@ @[Testable]@ Once all channels have entered the @DETACHED@ or @FAILED@ state, then the room state is transitioned to @RELEASED@ and the operation completes. ** @(CHA-RL3h)@ @[Testable]@ Upon operation completion, the underlying Realtime Channels are released from the core SDK prevent leakage. ** @(CHA-RL3k)@ @[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-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. From 13a3e25e697b7e368a1ff7b6e964bbc0c6952c84 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:55:38 +0000 Subject: [PATCH 34/73] CHA-RL3g: clarify what constitutes a terminal condition --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index a4373e684..68793dad2 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -121,7 +121,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL3d)@ @[Testable]@ All features channels must be detached in sequence. ** @(CHA-RL3e)@ @[Testable]@ If a channel is in the @FAILED@ state when it is time to detach, it shall be ignored. ** @(CHA-RL3f)@ @[Testable]@ If a channel fails to detach (i.e. the call to @detach()@ returns an error), the @CHA-RL3d@ channel detach sequence will be retried after a 250ms delay. Retries are continued until @CHA-RL3g@ is met. -** @(CHA-RL3g)@ @[Testable]@ Once all channels have entered the @DETACHED@ or @FAILED@ state, then the room state is transitioned to @RELEASED@ and the operation completes. +** @(CHA-RL3g)@ @[Testable]@ Once all channels have entered the @DETACHED@ (i.e. the call to @detach()@ succeeds) or @FAILED@ (i.e. the call to @detach()@ fails and the channel state is subsequently @FAILED@) state, then the room state is transitioned to @RELEASED@ and the operation completes. ** @(CHA-RL3h)@ @[Testable]@ Upon operation completion, the underlying Realtime Channels are released from the core SDK prevent leakage. ** @(CHA-RL3k)@ @[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-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. From 8a6148a1379a8528368df54bc21d781007efb70a Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:58:32 +0000 Subject: [PATCH 35/73] CHA-RL1h1: make non-testable --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 68793dad2..0f1a942d7 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -90,7 +90,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations *** @(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. ** @(CHA-RL1h)@ If a one of the @contributors@ Realtime Channels fails to attach (i.e. the call to @attach()@ returns an error), then the operation has failed and must be rolled back. The procedure to roll back is described in subsequent points. -*** @(CHA-RL1h1)@ @[Testable]@ The @attach@ call must throw an @ErrorInfo@. The code for this error is determined by the feature that failed (see "here":#error-codes for more information on error codes). +*** @(CHA-RL1h1)@ The @attach@ call must throw an @ErrorInfo@. The code for this error is determined by the feature that failed and the status of the underlying channel (see "here":#error-codes for more information on error codes). *** @(CHA-RL1h2)@ @[Testable]@ If the underlying Realtime Channel entered the @SUSPENDED@ state (i.e. the @attach()@ operation fails and upon subsequently checking the channel state, it is @SUSPENDED@), then the room status will transition to @SUSPENDED@. The state transition @ErrorInfo@ will use the error from the realtime channels `attach()` as the @cause@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. *** @(CHA-RL1h3)@ @[Testable]@ When the room enters the @SUSPENDED@ status as a result of @CHA-RL1h2@ the @attach()@ operation shall fail using the error from @CHA-RL1h2@. The room lifecycle shall asynchronously (non-blocking to the @ATTACH@ operation) enter the recovery loop (per "@CHA-RL5@":#CHA-RL5) and attempt to re-establish attachment. *** @(CHA-RL1h4)@ @[Testable]@ If the underlying Realtime Channel entered the @FAILED@ state, then the room status will transition to @FAILED@, using the error from the realtime channels `attach()` call as the @cause@ field of the @ErrorInfo@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. The same error shall be thrown as the result of the @ATTACH@ operation. From 1f25d7f7a70ac4c3e2a767ab15f4a3d5eabf8e3e Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 17:59:56 +0000 Subject: [PATCH 36/73] chat: fix typo in resumed flag --- textile/chat-features.textile | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 0f1a942d7..eb33bf381 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -148,15 +148,15 @@ As well as user-initiated operations, the room must monitor its underlying resou * @(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. +*** @(CHA-RL4a1)@ @[Testable]@ If the @resumed@ 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. *** @(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-RL4b1)@ @[Testable]@ If a channel lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resumed@ 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. -*** @(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-RL4b3)@ @[Testable]@ If a channel lifecycle operation is in progress, the channel state is @ATTACHED@ and the @resumed@ 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 @resumed@ 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. From 99d8fd43c1d9942db3d2a94732eb11c8f7fc0276 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 18:02:15 +0000 Subject: [PATCH 37/73] CHA-RL4a2: clarify when a channel is deemed to have attached once --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index eb33bf381..adfb4f7b0 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -149,7 +149,7 @@ As well as user-initiated operations, the room must monitor its underlying resou * @(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 @resumed@ 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-RL4a2)@ @[Testable]@ If the given contributor has not yet successfully managed to attach its Realtime Channel (i.e. a call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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. From 02967fdebe20afbdde9e5afd1eaff79d659113f7 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 18:03:35 +0000 Subject: [PATCH 38/73] CHA-RL4b1: clarify relation to CHA-RL1f --- textile/chat-features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index adfb4f7b0..eff66fd73 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -149,11 +149,11 @@ As well as user-initiated operations, the room must monitor its underlying resou * @(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 @resumed@ 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 (i.e. a call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), then no action should be taken. +*** @(CHA-RL4a2)@ @[Testable]@ If the given contributor has not yet successfully managed to attach its Realtime Channel (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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. -*** @(CHA-RL4b1)@ @[Testable]@ If a channel lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resumed@ 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-RL4b1)@ @[Testable]@ If a channel lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resumed@ flag is false, @and@ the particular contributor has been attached previously (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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 @resumed@ 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 @resumed@ flag is false but the contributor has never previouly reached the state of @ATTACHED@, then no action is taken. From b3c0d11f51b062f623a87d42fc3a5a3db2f4fb1a Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 18:05:14 +0000 Subject: [PATCH 39/73] CHA-RL4b4: link to CHA-RL1f --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index eff66fd73..1a46c1c11 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -156,7 +156,7 @@ As well as user-initiated operations, the room must monitor its underlying resou *** @(CHA-RL4b1)@ @[Testable]@ If a channel lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resumed@ flag is false, @and@ the particular contributor has been attached previously (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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 @resumed@ 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 @resumed@ flag is false but the contributor has never previouly reached the state of @ATTACHED@, then no action is taken. +*** @(CHA-RL4b4)@ @[Testable]@ If a channel lifecycle operation is in progress, the channel state is @ATTACHED@, the @resumed@ flag is false but the contributor has never previously reached the state of @ATTACHED@ (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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. From 89fcb6b1ebed2ddd4b46d6130850f2ba116033cb Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 18:06:19 +0000 Subject: [PATCH 40/73] CHA-RL4b7: clarify transient disconnect timeouts --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 1a46c1c11..74c765289 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -159,7 +159,7 @@ As well as user-initiated operations, the room must monitor its underlying resou *** @(CHA-RL4b4)@ @[Testable]@ If a channel lifecycle operation is in progress, the channel state is @ATTACHED@, the @resumed@ flag is false but the contributor has never previously reached the state of @ATTACHED@ (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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. +*** @(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. *** @(CHA-RL4b10)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @ATTACHED@ and a transient disconnect timeout exists for the contributor, the timeout is cleared. *** @(CHA-RL4b8)@ @[Testable]@ If a channel lifecycle operation is not in progress, the channel state is @ATTACHED@, the room status is NOT @ATTACHED@ and all contibutors channel are now @ATTACHED@, the room status is transitioned to @ATTACHED@. *** @(CHA-RL4b9)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @SUSPENDED@, then the room status is transitioned to @SUSPENDED@, using the @reason@ of the channel state change as the error. Any transient disconnect timeouts are cancelled and the room enters the @RETRY@ loop. From 1b48f5275fa260c322e79da9137f2113a2e5eb80 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 18:07:05 +0000 Subject: [PATCH 41/73] CHA-RL4b*: change channel lifecycle to room lifecycle --- textile/chat-features.textile | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 74c765289..40aa1be69 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -153,16 +153,16 @@ As well as user-initiated operations, the room must monitor its underlying resou *** @(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 @resumed@ flag is false, @and@ the particular contributor has been attached previously (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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 @resumed@ 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 @resumed@ flag is false but the contributor has never previously reached the state of @ATTACHED@ (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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 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. -*** @(CHA-RL4b10)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @ATTACHED@ and a transient disconnect timeout exists for the contributor, the timeout is cleared. -*** @(CHA-RL4b8)@ @[Testable]@ If a channel lifecycle operation is not in progress, the channel state is @ATTACHED@, the room status is NOT @ATTACHED@ and all contibutors channel are now @ATTACHED@, the room status is transitioned to @ATTACHED@. -*** @(CHA-RL4b9)@ @[Testable]@ If a channel lifecycle operation is not in progress and the channel state is @SUSPENDED@, then the room status is transitioned to @SUSPENDED@, using the @reason@ of the channel state change as the error. Any transient disconnect timeouts are cancelled and the room enters the @RETRY@ loop. +*** @(CHA-RL4b1)@ @[Testable]@ If a room lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resumed@ flag is false, @and@ the particular contributor has been attached previously (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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 room lifecycle operation is in progress and the new channel state is not @ATTACHED@, then no action is taken. +*** @(CHA-RL4b3)@ @[Testable]@ If a room lifecycle operation is in progress, the channel state is @ATTACHED@ and the @resumed@ flag is true, then no action is taken. +*** @(CHA-RL4b4)@ @[Testable]@ If a room lifecycle operation is in progress, the channel state is @ATTACHED@, the @resumed@ flag is false but the contributor has never previously reached the state of @ATTACHED@ (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), then no action is taken. +*** @(CHA-RL4b5)@ @[Testable]@ If a room 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 room 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 room 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. +*** @(CHA-RL4b10)@ @[Testable]@ If a room lifecycle operation is not in progress and the channel state is @ATTACHED@ and a transient disconnect timeout exists for the contributor, the timeout is cleared. +*** @(CHA-RL4b8)@ @[Testable]@ If a room lifecycle operation is not in progress, the channel state is @ATTACHED@, the room status is NOT @ATTACHED@ and all contibutors channel are now @ATTACHED@, the room status is transitioned to @ATTACHED@. +*** @(CHA-RL4b9)@ @[Testable]@ If a room lifecycle operation is not in progress and the channel state is @SUSPENDED@, then the room status is transitioned to @SUSPENDED@, using the @reason@ of the channel state change as the error. Any transient disconnect timeouts are cancelled and the room enters the @RETRY@ loop. h2(#room-configuration). Room Configuration From ec1d5d1f406e593ba3db396b9a6a8d3ee5ead0f1 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 18:07:36 +0000 Subject: [PATCH 42/73] CHA-RL4b: specify non-update events --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 40aa1be69..5dedff212 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -152,7 +152,7 @@ As well as user-initiated operations, the room must monitor its underlying resou *** @(CHA-RL4a2)@ @[Testable]@ If the given contributor has not yet successfully managed to attach its Realtime Channel (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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. +** @(CHA-RL4b)@ The state monitor must handle non-@UPDATE@ channel state events. *** @(CHA-RL4b1)@ @[Testable]@ If a room lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resumed@ flag is false, @and@ the particular contributor has been attached previously (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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 room lifecycle operation is in progress and the new channel state is not @ATTACHED@, then no action is taken. *** @(CHA-RL4b3)@ @[Testable]@ If a room lifecycle operation is in progress, the channel state is @ATTACHED@ and the @resumed@ flag is true, then no action is taken. From c95a314568fde7d61d378ccdfd2c00c27ea02df5 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 18:11:15 +0000 Subject: [PATCH 43/73] CHA-RL4b2 remove from spec --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 5dedff212..3b51de714 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -154,7 +154,7 @@ As well as user-initiated operations, the room must monitor its underlying resou *** @(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 non-@UPDATE@ channel state events. *** @(CHA-RL4b1)@ @[Testable]@ If a room lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resumed@ flag is false, @and@ the particular contributor has been attached previously (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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 room lifecycle operation is in progress and the new channel state is not @ATTACHED@, then no action is taken. +*** @(CHA-RL4b2)@ This specification point has been removed. *** @(CHA-RL4b3)@ @[Testable]@ If a room lifecycle operation is in progress, the channel state is @ATTACHED@ and the @resumed@ flag is true, then no action is taken. *** @(CHA-RL4b4)@ @[Testable]@ If a room lifecycle operation is in progress, the channel state is @ATTACHED@, the @resumed@ flag is false but the contributor has never previously reached the state of @ATTACHED@ (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), then no action is taken. *** @(CHA-RL4b5)@ @[Testable]@ If a room 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. From d0588155c5c83bf9797639a4baeddf81281bb43e Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 18:13:43 +0000 Subject: [PATCH 44/73] CHA-RL4b3/4: remove --- textile/chat-features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 3b51de714..c6ed3450e 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -155,8 +155,8 @@ As well as user-initiated operations, the room must monitor its underlying resou ** @(CHA-RL4b)@ The state monitor must handle non-@UPDATE@ channel state events. *** @(CHA-RL4b1)@ @[Testable]@ If a room lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resumed@ flag is false, @and@ the particular contributor has been attached previously (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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)@ This specification point has been removed. -*** @(CHA-RL4b3)@ @[Testable]@ If a room lifecycle operation is in progress, the channel state is @ATTACHED@ and the @resumed@ flag is true, then no action is taken. -*** @(CHA-RL4b4)@ @[Testable]@ If a room lifecycle operation is in progress, the channel state is @ATTACHED@, the @resumed@ flag is false but the contributor has never previously reached the state of @ATTACHED@ (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), then no action is taken. +*** @(CHA-RL4b3)@ This specification point has been removed. +*** @(CHA-RL4b4)@ This specification point has been removed. *** @(CHA-RL4b5)@ @[Testable]@ If a room 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 room 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 room 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. From 079294335d2645263e4b7e951b80d1e6d658b5f9 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 18:15:24 +0000 Subject: [PATCH 45/73] CHA-RL4a1/2: relate to CHA-RL4a3/4 --- textile/chat-features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index c6ed3450e..77c5363bc 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -148,8 +148,8 @@ As well as user-initiated operations, the room must monitor its underlying resou * @(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 @resumed@ 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 (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), then no action should be taken. +*** @(CHA-RL4a1)@ @[Testable]@ If the @resumed@ flag of the update is set to @true@, then no action should be taken (i.e. @CHA-RL4a3@ and @CHA-RL4a4@ behaviours are not performed). +*** @(CHA-RL4a2)@ @[Testable]@ If the given contributor has not yet successfully managed to attach its Realtime Channel (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), then no action should be taken (i.e. @CHA-RL4a3@ and @CHA-RL4a4@ behaviours are not performed). *** @(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 non-@UPDATE@ channel state events. From 956b7723ea0518865e8cd4a35613e4d125dcb69a Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 18:16:10 +0000 Subject: [PATCH 46/73] CHA-RL4b6: remove specification point --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 77c5363bc..1d46d9082 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -158,7 +158,7 @@ As well as user-initiated operations, the room must monitor its underlying resou *** @(CHA-RL4b3)@ This specification point has been removed. *** @(CHA-RL4b4)@ This specification point has been removed. *** @(CHA-RL4b5)@ @[Testable]@ If a room 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 room 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-RL4b6)@ This specification point has been removed. *** @(CHA-RL4b7)@ @[Testable]@ If a room 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. *** @(CHA-RL4b10)@ @[Testable]@ If a room lifecycle operation is not in progress and the channel state is @ATTACHED@ and a transient disconnect timeout exists for the contributor, the timeout is cleared. *** @(CHA-RL4b8)@ @[Testable]@ If a room lifecycle operation is not in progress, the channel state is @ATTACHED@, the room status is NOT @ATTACHED@ and all contibutors channel are now @ATTACHED@, the room status is transitioned to @ATTACHED@. From 8ddeea5b5eceda133fd24fc6e70abe682233aad7 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 18:17:51 +0000 Subject: [PATCH 47/73] CHA-RL4b5: link to CHA-RL2f --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 1d46d9082..61a6998a1 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -157,7 +157,7 @@ As well as user-initiated operations, the room must monitor its underlying resou *** @(CHA-RL4b2)@ This specification point has been removed. *** @(CHA-RL4b3)@ This specification point has been removed. *** @(CHA-RL4b4)@ This specification point has been removed. -*** @(CHA-RL4b5)@ @[Testable]@ If a room 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-RL4b5)@ @[Testable]@ If a room 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 a @CHA-RL2f@ detach procedure is performed. *** @(CHA-RL4b6)@ This specification point has been removed. *** @(CHA-RL4b7)@ @[Testable]@ If a room 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. *** @(CHA-RL4b10)@ @[Testable]@ If a room lifecycle operation is not in progress and the channel state is @ATTACHED@ and a transient disconnect timeout exists for the contributor, the timeout is cleared. From e14a9f8e91c9694e99007a9747dd5e2acee02ea0 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 18:18:49 +0000 Subject: [PATCH 48/73] CHA-RL1g2: add double notification clause --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 61a6998a1..c90d0642f 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -87,7 +87,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(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. +*** @(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. These are then cleared to prevent double-notification. *** @(CHA-RL1g3)@ @[Testable]@ Any transient disconnect timeouts shall be cleared. ** @(CHA-RL1h)@ If a one of the @contributors@ Realtime Channels fails to attach (i.e. the call to @attach()@ returns an error), then the operation has failed and must be rolled back. The procedure to roll back is described in subsequent points. *** @(CHA-RL1h1)@ The @attach@ call must throw an @ErrorInfo@. The code for this error is determined by the feature that failed and the status of the underlying channel (see "here":#error-codes for more information on error codes). From 48d7378d8029422ba348163743ace2ea84c771bb Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Thu, 31 Oct 2024 18:21:20 +0000 Subject: [PATCH 49/73] CHA-RL4a3: prefer first discontinuity event --- textile/chat-features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index c90d0642f..378df4611 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -87,7 +87,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(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. These are then cleared to prevent double-notification. +*** @(CHA-RL1g2)@ @[Testable]@ Any contributors to rooms that have a pending discontinuity event against them, must be notified of this fact, using the error that caused the original discontinuity. These are then cleared to prevent double-notification. *** @(CHA-RL1g3)@ @[Testable]@ Any transient disconnect timeouts shall be cleared. ** @(CHA-RL1h)@ If a one of the @contributors@ Realtime Channels fails to attach (i.e. the call to @attach()@ returns an error), then the operation has failed and must be rolled back. The procedure to roll back is described in subsequent points. *** @(CHA-RL1h1)@ The @attach@ call must throw an @ErrorInfo@. The code for this error is determined by the feature that failed and the status of the underlying channel (see "here":#error-codes for more information on error codes). @@ -150,7 +150,7 @@ As well as user-initiated operations, the room must monitor its underlying resou ** @(CHA-RL4a)@ The state monitor must handle @UPDATE@ events from each contributors underlying Realtime Channel *** @(CHA-RL4a1)@ @[Testable]@ If the @resumed@ flag of the update is set to @true@, then no action should be taken (i.e. @CHA-RL4a3@ and @CHA-RL4a4@ behaviours are not performed). *** @(CHA-RL4a2)@ @[Testable]@ If the given contributor has not yet successfully managed to attach its Realtime Channel (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), then no action should be taken (i.e. @CHA-RL4a3@ and @CHA-RL4a4@ behaviours are not performed). -*** @(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-RL4a3)@ @[Testable]@ If a room lifecycle operation is in progress, then a pending discontinuity event shall be recorded for this contributor - though it must not overwrite any existing discontinuity event. 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 non-@UPDATE@ channel state events. *** @(CHA-RL4b1)@ @[Testable]@ If a room lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resumed@ flag is false, @and@ the particular contributor has been attached previously (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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. From ce8844998746c4e8891d510e7317f207db043fef Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 4 Nov 2024 16:03:07 +0000 Subject: [PATCH 50/73] CHA-RL5b: add wait time --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 378df4611..1b5cacdbd 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -126,7 +126,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL3k)@ @[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-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. ** @(CHA-RL5a)@ @[Testable]@ When entering a retry-loop, the room must first @DETACH@ all contributors underlying realtime channels. -** @(CHA-RL5b)@ @[Testable]@ If the operation above fails, then it must be retried after a short wait. +** @(CHA-RL5b)@ @[Testable]@ If the operation above fails, then it must be retried after a short wait of 250ms ** @(CHA-RL5c)@ @[Testable]@ If the operation above fails because a channel has entered the @FAILED@ state, then the retry loop must stop and the room must be placed in the @FAILED@ status. ** @(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. From 4806634bf0ba2fdece6bde3ae8f4de7911c4e53f Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 4 Nov 2024 16:07:59 +0000 Subject: [PATCH 51/73] chat: link retry loop failure to detach --- textile/chat-features.textile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 1b5cacdbd..33970ab8f 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -125,9 +125,9 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL3h)@ @[Testable]@ Upon operation completion, the underlying Realtime Channels are released from the core SDK prevent leakage. ** @(CHA-RL3k)@ @[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-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. -** @(CHA-RL5a)@ @[Testable]@ When entering a retry-loop, the room must first @DETACH@ all contributors underlying realtime channels. -** @(CHA-RL5b)@ @[Testable]@ If the operation above fails, then it must be retried after a short wait of 250ms -** @(CHA-RL5c)@ @[Testable]@ If the operation above fails because a channel has entered the @FAILED@ state, then the retry loop must stop and the room must be placed in the @FAILED@ status. +** @(CHA-RL5a)@ @[Testable]@ When entering a retry-loop, the room must first @DETACH@ all contributors underlying realtime channels using a @CHA-RL2f@ detachment cycle. +** @(CHA-RL5b)@ @[Testable]@ If the operation above fails, then it must be retried after a short wait of 250ms. +** @(CHA-RL5c)@ @[Testable]@ If the operation above fails such that the room enters the @FAILED@ state, then the retry loop must stop. ** @(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. From af0c1223d52c3f5613ab04c4cfac654b5df59777 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Tue, 5 Nov 2024 13:59:47 +0000 Subject: [PATCH 52/73] CHA-RL5e: clarify error source --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 33970ab8f..716c86b0a 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -129,7 +129,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL5b)@ @[Testable]@ If the operation above fails, then it must be retried after a short wait of 250ms. ** @(CHA-RL5c)@ @[Testable]@ If the operation above fails such that the room enters the @FAILED@ state, then the retry loop must stop. ** @(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-RL5e)@ @[Testable]@ If the channel state becomes @FAILED@, then the room status is transitioned to @FAILED@ and the retry loop stops. The error associated with the transition is the error from the Realtime @ChannelStateChange@. ** @(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. *** @(CHA-RL5f2)@ @[Testable]@ If the attachment cycle fails because a channel entered @FAILED@, then the room is transitioned to @FAILED@ and the retry loop terminates. From 67496b3f482a47ac2cb06be3cb5f7cbad3a8348a Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Wed, 6 Nov 2024 09:27:20 +0000 Subject: [PATCH 53/73] chat: clarify retry behaviour --- textile/chat-features.textile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 716c86b0a..ed0ce2fdf 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -130,10 +130,10 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL5c)@ @[Testable]@ If the operation above fails such that the room enters the @FAILED@ state, then the retry loop must stop. ** @(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. The error associated with the transition is the error from the Realtime @ChannelStateChange@. -** @(CHA-RL5f)@ @[Testable]@ If the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new attachment cycle. +** @(CHA-RL5f)@ @[Testable]@ If the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new @CHA-RL1e@ 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. -*** @(CHA-RL5f2)@ @[Testable]@ If the attachment cycle fails because a channel entered @FAILED@, then the room is transitioned to @FAILED@ and the retry loop terminates. -*** @(CHA-RL5f3)@ @[Testable]@ If the attachment cycle fails because a channel entered @SUSPENDED@, then the room is transitioned to @SUSPENDED@ and the retry loop restarted using the @SUSPENDED@ channel as the subject. +*** @(CHA-RL5f2)@ @[Testable]@ If the attachment cycle fails because a channel entered @FAILED@, then the room is transitioned to @FAILED@ and the retry loop terminates. The error associated with the transition is the error from the Realtime @ChannelStateChange@. +*** @(CHA-RL5f3)@ @[Testable]@ If the attachment cycle fails because a channel entered @SUSPENDED@, then the room is transitioned to @SUSPENDED@ and the retry loop restarted using the @SUSPENDED@ channel as the subject. The error associated with the transition is the error from the Realtime @ChannelStateChange@. * @(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-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. From 6c246a628c5382655726cc88dc7ac253295da51e Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Wed, 6 Nov 2024 09:32:34 +0000 Subject: [PATCH 54/73] CHA-RL5f1: clarify clearing errors --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index ed0ce2fdf..d39c63b73 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -131,7 +131,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(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. The error associated with the transition is the error from the Realtime @ChannelStateChange@. ** @(CHA-RL5f)@ @[Testable]@ If the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new @CHA-RL1e@ 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. +*** @(CHA-RL5f1)@ @[Testable]@ If the attachment cycle succeeds, then the room is transitioned to @ATTACHED@ and any discontinuity errors are broadcast to contributors. These are then cleared to prevent double-notification. *** @(CHA-RL5f2)@ @[Testable]@ If the attachment cycle fails because a channel entered @FAILED@, then the room is transitioned to @FAILED@ and the retry loop terminates. The error associated with the transition is the error from the Realtime @ChannelStateChange@. *** @(CHA-RL5f3)@ @[Testable]@ If the attachment cycle fails because a channel entered @SUSPENDED@, then the room is transitioned to @SUSPENDED@ and the retry loop restarted using the @SUSPENDED@ channel as the subject. The error associated with the transition is the error from the Realtime @ChannelStateChange@. * @(CHA-RL6)@ @[Testable]@ A room begins its lifetime in the @INTIIALIZING@ state. From 3554a235030e000e5504f04f66afdc96dd3ae50c Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Wed, 6 Nov 2024 13:46:32 -0300 Subject: [PATCH 55/73] Fix typo --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index d39c63b73..8763efe0f 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -117,7 +117,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL3i)@ @[Testable]@ If the room is in the @INITIALIZING@ status, then the room is immediately transitioned to @RELEASED@ and the operation succeeds. ** @(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 any any transient disconnect timeouts shall be cleared. +** @(CHA-RL3l)@ @[Testable]@ When the release operation commences, the room will transition into the @RELEASING@ status and any transient disconnect timeouts shall be cleared. ** @(CHA-RL3d)@ @[Testable]@ All features channels must be detached in sequence. ** @(CHA-RL3e)@ @[Testable]@ If a channel is in the @FAILED@ state when it is time to detach, it shall be ignored. ** @(CHA-RL3f)@ @[Testable]@ If a channel fails to detach (i.e. the call to @detach()@ returns an error), the @CHA-RL3d@ channel detach sequence will be retried after a 250ms delay. Retries are continued until @CHA-RL3g@ is met. From d6b22b0a819bb8071c98343b62ea7d46743d22a6 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Thu, 7 Nov 2024 16:18:40 -0300 Subject: [PATCH 56/73] Mark CHA-RL1d1 as Testable --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 8763efe0f..b19afefd3 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -174,7 +174,7 @@ Each chat room can be configured individually, allowing options to be passed as ** @(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)@ 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-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-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. From 6b1027f519069d15379ce1431daf607660fa06be Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Thu, 7 Nov 2024 16:21:23 -0300 Subject: [PATCH 57/73] Disable implicit attach for Chat --- textile/chat-features.textile | 1 + 1 file changed, 1 insertion(+) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index b19afefd3..e4f7c137c 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -24,6 +24,7 @@ h2(#general). General Principles * @(CHA-GP1)@ As far as is practicable, the implementation details such as underlying Realtime Channels should be hidden from the public API. This allows developers to interact with Chat without having to understand many low-level primitives. * @(CHA-GP2)@ The public API should avoid implicit operations as a side-effect to some other operation. For example, adding a subscriber to messages in a Chat Room should not automatically trigger that Room to attach. This is in contrast to the current core SDKs. Avoiding side-effects provides a clean, easy to understand API. +** @(CHA-GP2a)@ @[Testable]@ Whenever the Chat SDK fetches a realtime channel, it must do so with the @attachOnSubscribe@ channel option set to @false@. * @(CHA-GP3)@ Wherever possible, Chat features should be exposed in the public API as properties of their parent. For example, @messages@ would be considered a property of a @room@ object. This allows for greater composability and extensibility in the future. * @(CHA-GP4)@ Avoid overloading methods and optional parameters. Prefer object-type parameters wherever practical and idiomatic. From b576809137d9af6f25657054254f2b5afdae4556 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Wed, 6 Nov 2024 09:34:37 +0000 Subject: [PATCH 58/73] CHA-RL5a: dont include channel that is suspended --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index e4f7c137c..a0d6e54b9 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -126,7 +126,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL3h)@ @[Testable]@ Upon operation completion, the underlying Realtime Channels are released from the core SDK prevent leakage. ** @(CHA-RL3k)@ @[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-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. -** @(CHA-RL5a)@ @[Testable]@ When entering a retry-loop, the room must first @DETACH@ all contributors underlying realtime channels using a @CHA-RL2f@ detachment cycle. +** @(CHA-RL5a)@ @[Testable]@ When entering a retry-loop, the room must first @DETACH@ all contributors underlying realtime channels using a @CHA-RL2f@ detachment cycle, with the exception of the channel that became @SUSPENDED@. ** @(CHA-RL5b)@ @[Testable]@ If the operation above fails, then it must be retried after a short wait of 250ms. ** @(CHA-RL5c)@ @[Testable]@ If the operation above fails such that the room enters the @FAILED@ state, then the retry loop must stop. ** @(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. From 0e5a27224cb54fb6c90d624026f4a37ba4e2481a Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 11 Nov 2024 15:57:35 +0000 Subject: [PATCH 59/73] CHA-RL1h1: remove confusing spec point --- textile/chat-features.textile | 1 - 1 file changed, 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index a0d6e54b9..3de4468b0 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -91,7 +91,6 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations *** @(CHA-RL1g2)@ @[Testable]@ Any contributors to rooms that have a pending discontinuity event against them, must be notified of this fact, using the error that caused the original discontinuity. These are then cleared to prevent double-notification. *** @(CHA-RL1g3)@ @[Testable]@ Any transient disconnect timeouts shall be cleared. ** @(CHA-RL1h)@ If a one of the @contributors@ Realtime Channels fails to attach (i.e. the call to @attach()@ returns an error), then the operation has failed and must be rolled back. The procedure to roll back is described in subsequent points. -*** @(CHA-RL1h1)@ The @attach@ call must throw an @ErrorInfo@. The code for this error is determined by the feature that failed and the status of the underlying channel (see "here":#error-codes for more information on error codes). *** @(CHA-RL1h2)@ @[Testable]@ If the underlying Realtime Channel entered the @SUSPENDED@ state (i.e. the @attach()@ operation fails and upon subsequently checking the channel state, it is @SUSPENDED@), then the room status will transition to @SUSPENDED@. The state transition @ErrorInfo@ will use the error from the realtime channels `attach()` as the @cause@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. *** @(CHA-RL1h3)@ @[Testable]@ When the room enters the @SUSPENDED@ status as a result of @CHA-RL1h2@ the @attach()@ operation shall fail using the error from @CHA-RL1h2@. The room lifecycle shall asynchronously (non-blocking to the @ATTACH@ operation) enter the recovery loop (per "@CHA-RL5@":#CHA-RL5) and attempt to re-establish attachment. *** @(CHA-RL1h4)@ @[Testable]@ If the underlying Realtime Channel entered the @FAILED@ state, then the room status will transition to @FAILED@, using the error from the realtime channels `attach()` call as the @cause@ field of the @ErrorInfo@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. The same error shall be thrown as the result of the @ATTACH@ operation. From d81eebef14e3175089d3d7198a0709ac86441be7 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 11 Nov 2024 15:58:36 +0000 Subject: [PATCH 60/73] CHA-RL4b1: negate condition --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 3de4468b0..8bb8a5c17 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -153,7 +153,7 @@ As well as user-initiated operations, the room must monitor its underlying resou *** @(CHA-RL4a3)@ @[Testable]@ If a room lifecycle operation is in progress, then a pending discontinuity event shall be recorded for this contributor - though it must not overwrite any existing discontinuity event. 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 non-@UPDATE@ channel state events. -*** @(CHA-RL4b1)@ @[Testable]@ If a room lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resumed@ flag is false, @and@ the particular contributor has been attached previously (i.e. no call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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-RL4b1)@ @[Testable]@ If a room lifecycle operation is in progress, and the new channel state is @ATTACHED@, and the @resumed@ flag is false, @and@ the particular contributor has been attached previously (i.e. a previous call to @attach()@ on the channel, per @CHA-RL1f@, has succeeded), 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)@ This specification point has been removed. *** @(CHA-RL4b3)@ This specification point has been removed. *** @(CHA-RL4b4)@ This specification point has been removed. From 659aa04a5a9f4e2d13a3cea10ee14909d444bf2f Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 11 Nov 2024 16:02:23 +0000 Subject: [PATCH 61/73] CHA-RL5: clarify relation to attach and suspend --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 8bb8a5c17..b43ea5599 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -124,7 +124,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL3g)@ @[Testable]@ Once all channels have entered the @DETACHED@ (i.e. the call to @detach()@ succeeds) or @FAILED@ (i.e. the call to @detach()@ fails and the channel state is subsequently @FAILED@) state, then the room state is transitioned to @RELEASED@ and the operation completes. ** @(CHA-RL3h)@ @[Testable]@ Upon operation completion, the underlying Realtime Channels are released from the core SDK prevent leakage. ** @(CHA-RL3k)@ @[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-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. +* @(CHA-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. This specification point describes the behavior that is executed as a result of @CHA-RL4b9@ and @CHA-RL1h3@. ** @(CHA-RL5a)@ @[Testable]@ When entering a retry-loop, the room must first @DETACH@ all contributors underlying realtime channels using a @CHA-RL2f@ detachment cycle, with the exception of the channel that became @SUSPENDED@. ** @(CHA-RL5b)@ @[Testable]@ If the operation above fails, then it must be retried after a short wait of 250ms. ** @(CHA-RL5c)@ @[Testable]@ If the operation above fails such that the room enters the @FAILED@ state, then the retry loop must stop. From 502a88b79f98ed20bce9f5d11830566883df84b1 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 11 Nov 2024 16:05:58 +0000 Subject: [PATCH 62/73] CHA-RL5a: add clarification on detaching, clarify retry loop language --- textile/chat-features.textile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index b43ea5599..a8c829c92 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -125,7 +125,8 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL3h)@ @[Testable]@ Upon operation completion, the underlying Realtime Channels are released from the core SDK prevent leakage. ** @(CHA-RL3k)@ @[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-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. This specification point describes the behavior that is executed as a result of @CHA-RL4b9@ and @CHA-RL1h3@. -** @(CHA-RL5a)@ @[Testable]@ When entering a retry-loop, the room must first @DETACH@ all contributors underlying realtime channels using a @CHA-RL2f@ detachment cycle, with the exception of the channel that became @SUSPENDED@. +** @(CHA-RL5a)@ @[Testable]@ When entering a @RETRY@ operation, the room must first @DETACH@ all contributors underlying realtime channels using a @CHA-RL2f@ detachment cycle, with the exception of the channel that became @SUSPENDED@. +*** @(CHA-RL5a1)@ NOTE: As many chat features share channels, the equality of contributors when deciding not to detach is based on their realtime channel, and not the contributor themselves. i.e. if two features share a realtime channel, and that channel is suspended, then that channel should not be detached. ** @(CHA-RL5b)@ @[Testable]@ If the operation above fails, then it must be retried after a short wait of 250ms. ** @(CHA-RL5c)@ @[Testable]@ If the operation above fails such that the room enters the @FAILED@ state, then the retry loop must stop. ** @(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. From 863c895bfa698a036c5de06fd102a82bb6b9664b Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 11 Nov 2024 16:07:43 +0000 Subject: [PATCH 63/73] CHA-RL5: add summary clause --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index a8c829c92..372ce2808 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -124,7 +124,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL3g)@ @[Testable]@ Once all channels have entered the @DETACHED@ (i.e. the call to @detach()@ succeeds) or @FAILED@ (i.e. the call to @detach()@ fails and the channel state is subsequently @FAILED@) state, then the room state is transitioned to @RELEASED@ and the operation completes. ** @(CHA-RL3h)@ @[Testable]@ Upon operation completion, the underlying Realtime Channels are released from the core SDK prevent leakage. ** @(CHA-RL3k)@ @[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-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. This specification point describes the behavior that is executed as a result of @CHA-RL4b9@ and @CHA-RL1h3@. +* @(CHA-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. This specification point describes the behavior that is executed as a result of @CHA-RL4b9@ and @CHA-RL1h3@. The @RETRY@ operation is summarized as a loop that terminates either when a realtime channel enters the @FAILED@ state, or all channels are back in @ATTACHED@. ** @(CHA-RL5a)@ @[Testable]@ When entering a @RETRY@ operation, the room must first @DETACH@ all contributors underlying realtime channels using a @CHA-RL2f@ detachment cycle, with the exception of the channel that became @SUSPENDED@. *** @(CHA-RL5a1)@ NOTE: As many chat features share channels, the equality of contributors when deciding not to detach is based on their realtime channel, and not the contributor themselves. i.e. if two features share a realtime channel, and that channel is suspended, then that channel should not be detached. ** @(CHA-RL5b)@ @[Testable]@ If the operation above fails, then it must be retried after a short wait of 250ms. From a56ee6d6b1efeb8d340e1d2318e28167e5e912d0 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 11 Nov 2024 16:16:46 +0000 Subject: [PATCH 64/73] CHA-RL5b/c: clarify detach failure --- textile/chat-features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 372ce2808..5a9d437f7 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -127,8 +127,8 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations * @(CHA-RL5)@ A room must @RETRY@ whenever it enters the @SUSPENDED@ state. This specification point describes the behavior that is executed as a result of @CHA-RL4b9@ and @CHA-RL1h3@. The @RETRY@ operation is summarized as a loop that terminates either when a realtime channel enters the @FAILED@ state, or all channels are back in @ATTACHED@. ** @(CHA-RL5a)@ @[Testable]@ When entering a @RETRY@ operation, the room must first @DETACH@ all contributors underlying realtime channels using a @CHA-RL2f@ detachment cycle, with the exception of the channel that became @SUSPENDED@. *** @(CHA-RL5a1)@ NOTE: As many chat features share channels, the equality of contributors when deciding not to detach is based on their realtime channel, and not the contributor themselves. i.e. if two features share a realtime channel, and that channel is suspended, then that channel should not be detached. -** @(CHA-RL5b)@ @[Testable]@ If the operation above fails, then it must be retried after a short wait of 250ms. -** @(CHA-RL5c)@ @[Testable]@ If the operation above fails such that the room enters the @FAILED@ state, then the retry loop must stop. +** @(CHA-RL5b)@ @[Testable]@ If the operation above fails (i.e. the call to the @CHA-RL2f@ detach procedure fails), room status is still @SUSPENDED@, then it must be retried after a short wait of 250ms. +** @(CHA-RL5c)@ @[Testable]@ If the operation above fails (i.e. the call to the @CHA-RL2f@ detach procedure fails), such that the room enters the @FAILED@ state, then the retry loop must stop. ** @(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. The error associated with the transition is the error from the Realtime @ChannelStateChange@. ** @(CHA-RL5f)@ @[Testable]@ If the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new @CHA-RL1e@ attachment cycle. From a7b66c645152e74a6fa1372d7ffca973d3234ead Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 11 Nov 2024 16:20:16 +0000 Subject: [PATCH 65/73] CHA-RL5D: include reference to realtime SDK retrying --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 5a9d437f7..24c8e8680 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -129,7 +129,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations *** @(CHA-RL5a1)@ NOTE: As many chat features share channels, the equality of contributors when deciding not to detach is based on their realtime channel, and not the contributor themselves. i.e. if two features share a realtime channel, and that channel is suspended, then that channel should not be detached. ** @(CHA-RL5b)@ @[Testable]@ If the operation above fails (i.e. the call to the @CHA-RL2f@ detach procedure fails), room status is still @SUSPENDED@, then it must be retried after a short wait of 250ms. ** @(CHA-RL5c)@ @[Testable]@ If the operation above fails (i.e. the call to the @CHA-RL2f@ detach procedure fails), such that the room enters the @FAILED@ state, then the retry loop must stop. -** @(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-RL5d)@ Once all channels (except the channel that entered @SUSPENDED@, per @CHA-RL5a@) have been detached, the room waits until the original channel that caused the retry loop naturally enters the @ATTACHED@ state. This is handled by the underlying Realtime SDK. ** @(CHA-RL5e)@ @[Testable]@ If the channel state becomes @FAILED@, then the room status is transitioned to @FAILED@ and the retry loop stops. The error associated with the transition is the error from the Realtime @ChannelStateChange@. ** @(CHA-RL5f)@ @[Testable]@ If the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new @CHA-RL1e@ 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. These are then cleared to prevent double-notification. From 349eed808297742eeab95c31f31bb38cf3acc506 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 11 Nov 2024 16:21:17 +0000 Subject: [PATCH 66/73] CHA-RL5e/f: link to CHA-RL5d --- textile/chat-features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 24c8e8680..1206ecb9d 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -130,8 +130,8 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL5b)@ @[Testable]@ If the operation above fails (i.e. the call to the @CHA-RL2f@ detach procedure fails), room status is still @SUSPENDED@, then it must be retried after a short wait of 250ms. ** @(CHA-RL5c)@ @[Testable]@ If the operation above fails (i.e. the call to the @CHA-RL2f@ detach procedure fails), such that the room enters the @FAILED@ state, then the retry loop must stop. ** @(CHA-RL5d)@ Once all channels (except the channel that entered @SUSPENDED@, per @CHA-RL5a@) have been detached, the room waits until the original channel that caused the retry loop naturally enters the @ATTACHED@ state. This is handled by the underlying Realtime SDK. -** @(CHA-RL5e)@ @[Testable]@ If the channel state becomes @FAILED@, then the room status is transitioned to @FAILED@ and the retry loop stops. The error associated with the transition is the error from the Realtime @ChannelStateChange@. -** @(CHA-RL5f)@ @[Testable]@ If the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new @CHA-RL1e@ attachment cycle. +** @(CHA-RL5e)@ @[Testable]@ If, during the @CHA-RL5d wait, the channel state becomes @FAILED@, then the room status is transitioned to @FAILED@ and the retry loop stops. The error associated with the transition is the error from the Realtime @ChannelStateChange@. +** @(CHA-RL5f)@ @[Testable]@ If, during the @CHA-RL5d wait, the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new @CHA-RL1e@ 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. These are then cleared to prevent double-notification. *** @(CHA-RL5f2)@ @[Testable]@ If the attachment cycle fails because a channel entered @FAILED@, then the room is transitioned to @FAILED@ and the retry loop terminates. The error associated with the transition is the error from the Realtime @ChannelStateChange@. *** @(CHA-RL5f3)@ @[Testable]@ If the attachment cycle fails because a channel entered @SUSPENDED@, then the room is transitioned to @SUSPENDED@ and the retry loop restarted using the @SUSPENDED@ channel as the subject. The error associated with the transition is the error from the Realtime @ChannelStateChange@. From a5557b5f05e254d37519ea73b674446967c49226 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 11 Nov 2024 16:21:50 +0000 Subject: [PATCH 67/73] CHA-RL5f1: add termination statement --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 1206ecb9d..6c7ab5716 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -132,7 +132,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL5d)@ Once all channels (except the channel that entered @SUSPENDED@, per @CHA-RL5a@) have been detached, the room waits until the original channel that caused the retry loop naturally enters the @ATTACHED@ state. This is handled by the underlying Realtime SDK. ** @(CHA-RL5e)@ @[Testable]@ If, during the @CHA-RL5d wait, the channel state becomes @FAILED@, then the room status is transitioned to @FAILED@ and the retry loop stops. The error associated with the transition is the error from the Realtime @ChannelStateChange@. ** @(CHA-RL5f)@ @[Testable]@ If, during the @CHA-RL5d wait, the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new @CHA-RL1e@ 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. These are then cleared to prevent double-notification. +*** @(CHA-RL5f1)@ @[Testable]@ If the attachment cycle succeeds, then the room is transitioned to @ATTACHED@ and any discontinuity errors are broadcast to contributors. These are then cleared to prevent double-notification. The retry loop now terminates. *** @(CHA-RL5f2)@ @[Testable]@ If the attachment cycle fails because a channel entered @FAILED@, then the room is transitioned to @FAILED@ and the retry loop terminates. The error associated with the transition is the error from the Realtime @ChannelStateChange@. *** @(CHA-RL5f3)@ @[Testable]@ If the attachment cycle fails because a channel entered @SUSPENDED@, then the room is transitioned to @SUSPENDED@ and the retry loop restarted using the @SUSPENDED@ channel as the subject. The error associated with the transition is the error from the Realtime @ChannelStateChange@. * @(CHA-RL6)@ @[Testable]@ A room begins its lifetime in the @INTIIALIZING@ state. From d3b1042f7008f2be08b8189c77fdaf4bd347ea11 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 11 Nov 2024 16:25:05 +0000 Subject: [PATCH 68/73] CHA-RL5f2: include failed detaching behaviour --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 6c7ab5716..a580a4763 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -133,7 +133,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL5e)@ @[Testable]@ If, during the @CHA-RL5d wait, the channel state becomes @FAILED@, then the room status is transitioned to @FAILED@ and the retry loop stops. The error associated with the transition is the error from the Realtime @ChannelStateChange@. ** @(CHA-RL5f)@ @[Testable]@ If, during the @CHA-RL5d wait, the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new @CHA-RL1e@ 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. These are then cleared to prevent double-notification. The retry loop now terminates. -*** @(CHA-RL5f2)@ @[Testable]@ If the attachment cycle fails because a channel entered @FAILED@, then the room is transitioned to @FAILED@ and the retry loop terminates. The error associated with the transition is the error from the Realtime @ChannelStateChange@. +*** @(CHA-RL5f2)@ @[Testable]@ If the attachment cycle fails because a channel entered @FAILED@, then the room is transitioned to @FAILED@ and the retry loop terminates. The error associated with the transition is the error from the Realtime @ChannelStateChange@. A @CHA-RL1h5@ detachment of non-failed channels is performed. *** @(CHA-RL5f3)@ @[Testable]@ If the attachment cycle fails because a channel entered @SUSPENDED@, then the room is transitioned to @SUSPENDED@ and the retry loop restarted using the @SUSPENDED@ channel as the subject. The error associated with the transition is the error from the Realtime @ChannelStateChange@. * @(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. From 95a0d20c946ef61e53513f41b53b7b30ecdc1ba0 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 11 Nov 2024 16:30:18 +0000 Subject: [PATCH 69/73] CHA-RL5f1-3: remove as copies of CHA-RL1e --- textile/chat-features.textile | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index a580a4763..5f396a73d 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -131,10 +131,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL5c)@ @[Testable]@ If the operation above fails (i.e. the call to the @CHA-RL2f@ detach procedure fails), such that the room enters the @FAILED@ state, then the retry loop must stop. ** @(CHA-RL5d)@ Once all channels (except the channel that entered @SUSPENDED@, per @CHA-RL5a@) have been detached, the room waits until the original channel that caused the retry loop naturally enters the @ATTACHED@ state. This is handled by the underlying Realtime SDK. ** @(CHA-RL5e)@ @[Testable]@ If, during the @CHA-RL5d wait, the channel state becomes @FAILED@, then the room status is transitioned to @FAILED@ and the retry loop stops. The error associated with the transition is the error from the Realtime @ChannelStateChange@. -** @(CHA-RL5f)@ @[Testable]@ If, during the @CHA-RL5d wait, the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new @CHA-RL1e@ 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. These are then cleared to prevent double-notification. The retry loop now terminates. -*** @(CHA-RL5f2)@ @[Testable]@ If the attachment cycle fails because a channel entered @FAILED@, then the room is transitioned to @FAILED@ and the retry loop terminates. The error associated with the transition is the error from the Realtime @ChannelStateChange@. A @CHA-RL1h5@ detachment of non-failed channels is performed. -*** @(CHA-RL5f3)@ @[Testable]@ If the attachment cycle fails because a channel entered @SUSPENDED@, then the room is transitioned to @SUSPENDED@ and the retry loop restarted using the @SUSPENDED@ channel as the subject. The error associated with the transition is the error from the Realtime @ChannelStateChange@. +** @(CHA-RL5f)@ @[Testable]@ If, during the @CHA-RL5d wait, the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new @CHA-RL1e@ attachment cycle. On successful completion, or terminal condition (room status is @FAILED@) the @RETRY@ loop terminates. * @(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-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. From b2b26ecdb065d070724516d582f87df36ef4db71 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 11 Nov 2024 16:31:30 +0000 Subject: [PATCH 70/73] CHA-RL5: add removal notice --- textile/chat-features.textile | 3 +++ 1 file changed, 3 insertions(+) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 5f396a73d..1d2c0babb 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -132,6 +132,9 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL5d)@ Once all channels (except the channel that entered @SUSPENDED@, per @CHA-RL5a@) have been detached, the room waits until the original channel that caused the retry loop naturally enters the @ATTACHED@ state. This is handled by the underlying Realtime SDK. ** @(CHA-RL5e)@ @[Testable]@ If, during the @CHA-RL5d wait, the channel state becomes @FAILED@, then the room status is transitioned to @FAILED@ and the retry loop stops. The error associated with the transition is the error from the Realtime @ChannelStateChange@. ** @(CHA-RL5f)@ @[Testable]@ If, during the @CHA-RL5d wait, the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new @CHA-RL1e@ attachment cycle. On successful completion, or terminal condition (room status is @FAILED@) the @RETRY@ loop terminates. +*** @(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-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. From bd1df9e6fd96cd064e7606a6d385d17e43f95ad3 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Mon, 11 Nov 2024 22:02:22 -0300 Subject: [PATCH 71/73] Restore ID of deleted spec point CHA-RL1h1 As in 9d8cb43. Spec point deleted in 9558698. --- textile/chat-features.textile | 1 + 1 file changed, 1 insertion(+) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 1d2c0babb..6619a940e 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -91,6 +91,7 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations *** @(CHA-RL1g2)@ @[Testable]@ Any contributors to rooms that have a pending discontinuity event against them, must be notified of this fact, using the error that caused the original discontinuity. These are then cleared to prevent double-notification. *** @(CHA-RL1g3)@ @[Testable]@ Any transient disconnect timeouts shall be cleared. ** @(CHA-RL1h)@ If a one of the @contributors@ Realtime Channels fails to attach (i.e. the call to @attach()@ returns an error), then the operation has failed and must be rolled back. The procedure to roll back is described in subsequent points. +*** @(CHA-RL1h1)@ This clause has been deleted. *** @(CHA-RL1h2)@ @[Testable]@ If the underlying Realtime Channel entered the @SUSPENDED@ state (i.e. the @attach()@ operation fails and upon subsequently checking the channel state, it is @SUSPENDED@), then the room status will transition to @SUSPENDED@. The state transition @ErrorInfo@ will use the error from the realtime channels `attach()` as the @cause@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. *** @(CHA-RL1h3)@ @[Testable]@ When the room enters the @SUSPENDED@ status as a result of @CHA-RL1h2@ the @attach()@ operation shall fail using the error from @CHA-RL1h2@. The room lifecycle shall asynchronously (non-blocking to the @ATTACH@ operation) enter the recovery loop (per "@CHA-RL5@":#CHA-RL5) and attempt to re-establish attachment. *** @(CHA-RL1h4)@ @[Testable]@ If the underlying Realtime Channel entered the @FAILED@ state, then the room status will transition to @FAILED@, using the error from the realtime channels `attach()` call as the @cause@ field of the @ErrorInfo@. The status code shall be @500@ and the error code whatever attachment error code corresponds to the feature that has failed, per "the error code list":#error-codes. The same error shall be thrown as the result of the @ATTACH@ operation. From aa55efdaaa82742960bbed9be7a0d94d64cf4f65 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Tue, 12 Nov 2024 11:40:33 -0300 Subject: [PATCH 72/73] Fix formatting --- textile/chat-features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 6619a940e..50204f572 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -131,8 +131,8 @@ h4(#rooms-lifecycle-operations). Room Lifecycle Operations ** @(CHA-RL5b)@ @[Testable]@ If the operation above fails (i.e. the call to the @CHA-RL2f@ detach procedure fails), room status is still @SUSPENDED@, then it must be retried after a short wait of 250ms. ** @(CHA-RL5c)@ @[Testable]@ If the operation above fails (i.e. the call to the @CHA-RL2f@ detach procedure fails), such that the room enters the @FAILED@ state, then the retry loop must stop. ** @(CHA-RL5d)@ Once all channels (except the channel that entered @SUSPENDED@, per @CHA-RL5a@) have been detached, the room waits until the original channel that caused the retry loop naturally enters the @ATTACHED@ state. This is handled by the underlying Realtime SDK. -** @(CHA-RL5e)@ @[Testable]@ If, during the @CHA-RL5d wait, the channel state becomes @FAILED@, then the room status is transitioned to @FAILED@ and the retry loop stops. The error associated with the transition is the error from the Realtime @ChannelStateChange@. -** @(CHA-RL5f)@ @[Testable]@ If, during the @CHA-RL5d wait, the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new @CHA-RL1e@ attachment cycle. On successful completion, or terminal condition (room status is @FAILED@) the @RETRY@ loop terminates. +** @(CHA-RL5e)@ @[Testable]@ If, during the @CHA-RL5d@ wait, the channel state becomes @FAILED@, then the room status is transitioned to @FAILED@ and the retry loop stops. The error associated with the transition is the error from the Realtime @ChannelStateChange@. +** @(CHA-RL5f)@ @[Testable]@ If, during the @CHA-RL5d@ wait, the channel state becomes @ATTACHED@, then the room status is transitioned to @ATTACHING@ to begin a new @CHA-RL1e@ attachment cycle. On successful completion, or terminal condition (room status is @FAILED@) the @RETRY@ loop terminates. *** @(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. From 3b576d39464efa0b71e5094ea5e6084e18fc63fe Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Tue, 12 Nov 2024 11:54:49 -0300 Subject: [PATCH 73/73] Remove trailing space My editor keep removing this for me (not quite sure why), so just let it. --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 50204f572..da9110872 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -495,7 +495,7 @@ The RoomOptions struct describes configuration options for a Chat room. A proper "timeoutMs": number }, "reactions": {}, // No properties, but must be non-null to enable feature. - "occupancy": {} + "occupancy": {} }