chat: room lifecycle specification

[AndyTWF]

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

[lawrence-forooghian]

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

[lawrence-forooghian]

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

[AndyTWF]

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

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

[sacOO7]

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

[lawrence-forooghian]

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

[lawrence-forooghian]

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

[AndyTWF]

Done!

[lawrence-forooghian]

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

• everything in the "Chat-specific Error Codes" section
• all the places where we specify a numerical error code directly in the spec point (e.g. CHA-RC1c, CHA-RC2b, CHA-RL1b, CHA-RL1c).

[lawrence-forooghian]

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

[AndyTWF]

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

[lawrence-forooghian]

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

[AndyTWF]

Added some guidance / rationale text!

[lawrence-forooghian]

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

Also, what code and statusCode should this error have?

[AndyTWF]

Clarified on all points

[lawrence-forooghian]

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

[AndyTWF]

Done!

[lawrence-forooghian]

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

[lawrence-forooghian]

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

[lawrence-forooghian]

And the RETRY operation terminates?

[AndyTWF]

Correct

[lawrence-forooghian]

The term "attachment cycle" is not defined and I am struggling to even guess what it means. I thought that perhaps this spec point was basically just saying "perform the ATTACH operation again", but that wouldn't make sense because we'd end up in deadlock (because CHA-RL1d would prevent ATTACH from proceeding due to the in-progress RETRY). So I guess it means something else?

[AndyTWF]

Sorry I will clarify on this one - essentially it's "begin the actual process of attaching, but without the need to lock a mutex to prevent other operations". In chat-js it's essentially just calling _doAttach for reference

[sacOO7]

Too confusing statement ->
Chat features should be exposed in the public API as properties of their parent.

I think following terms should be explained properly

1. Chat feature
2. Chat contributor
3. Parent of chat feature
4. What is a property exactly? This is a language idiomatic statement and can't be generalized

[sacOO7]

When I look at public API, all of the operations are focused on room which is Atomic element of chat.
But not sure why we use chat feature, chat contributor, this makes spec more confusing : (

[sacOO7]

Instead we could call it room feature, room object etc

[ttypic]

This is a language idiomatic statement and can't be generalized

Why do you think it can’t be generalized? I believe that all OOP languages have some concept of properties (members, attributes).

Chat feature
Chat contributor

What is not clear for you in Room Lifecycle where Chat "feature" an "contributor" are explained?

Parent of chat feature

Maybe it’s not the best choice of words, but it’s pretty clear that features are properties of an object, right? This object is essentially the parent.

[sacOO7]

I can agree with member or attribute, property has a different meaning in dotnet. They have getters and setters only.

[ttypic]

property has a different meaning in dotnet.

dotnet's property is exactly what we want here

Missing IDL can also be one of the reasons people will face issues understanding the spec.

Why do you need IDL? We already have all public interfaces and data structures defined

[sacOO7]

We have it defined, but inconsistent naming makes it difficult to understand. Like DefaultRoom, DefaultMessages class etc. Only when we look at public API, we understand the use-case

[sacOO7]

property is a technical term that is only applicable for dotnet, kotlin etc. For like java, go languages, member as a generalised term would make more sense.

[AndyTWF]

property often broadly describes a member that is accessible via getters and setters, whilst it has special meaning in some languages, it's quite a general term. In any case, the C# idiom is exactly what we want here (albeit, private setters).

Note that we also use the term property extensively throughout the core spec in the same way.

[sacOO7]

Yeah but it also mentions parent child relationship at the same time,
ParentObject#property, which is way easier to understand.
I would loved if we list out exact types of contributors that exists and their relationship with parent.
i.e. in our case, there's only one -> room

[sacOO7]

Can we please use some other keyword than contributors, this is a super confusing keyword and takes spec into whole different direction.

[sacOO7]

You can rather use room elements, room objects etc

[sacOO7]

I am open to any other keyword but surely not contributor

[AndyTWF]

The term contributor was chosen because in the context of the Room Lifecycle, a contributor is something that contributes to the room lifecycle and status. I clarify this point in the pointed room lifecycle section - which I can try to make clearer.

Element and Object are non-descriptive of what the things actually do or mean.

[sacOO7]

sure, element, and object are non-descriptive when used individually, but they do mean something when we say room object or room element, although less descriptive, they convey the meaning.

[sacOO7]

When contributor is used individually, it's difficult to guess if it's related to chat object or room object.
Our current implementation is mainly resolved around room, so it will be great if we can make it explicit there.

[umair-ably]

@AndyTWF can this be extended to include Typing Indicators please?

I expect to get to this a week today if that's okay? 🙏

[sacOO7]

Hi @AndyTWF, general question, We mutex lock/ priority queue executor in chat-js, which seems imp. part of room lifecycle.
It runs internal/external operations based on priority of execution

enum LifecycleOperationPrecedence {
  Internal = 0,
  Release = 1,
  AttachOrDetach = 2,
}

I am not sure why it's not mentioned in the chat spec