· 6 years ago · Oct 26, 2019, 11:16 PM
1# Summary:
2
3## API
4```
5class ChannelOptions
6 cipher?: (as before)
7 params?: Map<string, string>
8 modes?: Array<string>
9
10class Channels
11 get(string, channelOptions?): Channel
12 ...(other fields as now)
13
14class Channel
15 params: Map<string, string>
16 modes: Array<string>
17 channelOptions: ChannelOptions
18 setOptions(channelOptions, callback?)
19 attach(callback?)
20 ...(other fields as now)
21```
22
23## API notes
24- `ChannelOptions.params` - if provided these are sent to Ably in a new `params` property of the `ATTACH` protocol message. Realtime will echo back the applied params in the `ATTACHED` if that field was specified in the `ATTACH`
25- `ChannelOptions.modes` - optional typed array of modes. if a client lib doesn't include support for this, a user can get the same effect, albeit less developer-friendly, with `params.modes = 'string,separated,modes'`
26- `Channels.get(string, channelOptions?)` - raise an error if the channeloptions is one that would trigger a reattachment (that is, with a new set of params or modes passed in). Point is that this would not be a breaking change because those ChannelOptions properties are not supported now. So any such action would have to go through setOptions. TBD: Also shows a deprecation warning?
27- `Channel.setOptions(channelOptions, callback?)` - callback is called immediately if channel is not attached or attaching or if neither channelOptions.params nor channelOptions.modes is present, else sends an ATTACH and calls back on receipt of the ATTACHED (or state change to detached/failed, similar to attach())
28- `attach(callback?)` - sends this.channelOptions.params to realtime in a params property of the attach request. if client lib supports typed modes, encodes them in the flags
29
30## Other key points
31- client libraries always keep the last message on each channel unconditionally
32- Ably guarantees that the first message it sends after receiving an `ATTACH` request for an attached channel will be a full (non-delta) message
33- if a message arrives with an `extras.delta` field: compare the `extras.delta.from` with the stored last message ID; if they don't match, discard the message, log a warning, and send an `ATTACH` to Ably for the current channel (unless it has already done this for a previous message and not yet received the corresponding `ATTACHED`) with the `channelSerial` of the last message successfully received
34- Specific params:
35 - `modes`: comma-separated list of modes as a string, e.g. `"publish,subscribe,presence_subscribe"`. If present, the `flags` field of the `attach` request is ignored.
36 - `delta`
37
38## Questions:
39- `if client lib supports typed modes, encodes them in the flags` - Since flags could be discarded if `params.modes` are present doesn't it make more sense to encode them in the `params.modes`?
40- What if both `ChannelOptions.modes` and `ChannelOptions.params.modes` are specified? Does it make sense? What would be the precedence?