-
Notifications
You must be signed in to change notification settings - Fork 4
/
features.textile
2356 lines (2110 loc) · 258 KB
/
features.textile
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
title: Features spec
section: client-lib-development-guide
index: 1
anchor_specs: true
languages:
- none
jump_to:
General:
- Test guidelines
REST client library:
- RestClient
- Auth#rest-auth
- Channels#rest-channels
- RestChannel#rest-channel
- Plugins#plugins
- RestPresence#rest-presence
- Encryption#rest-encryption
- Forwards compatibility#rest-compatibility
- Batch Operations#batch-operations
Realtime client library:
- RealtimeClient
- Connection#realtime-connection
- Channels#realtime-channels
- RealtimeChannel#realtime-channel
- RealtimePresence#realtime-presence
- EventEmitter#eventemitter
- Forwards compatibility#realtime-compatibility
- State conditions and operations#state-conditions-and-operations
Push notifications:
- Push notifications#push-notifications
- Push channels#push-channels
- Activation state machine#activation-state-machine
Types:
- Data types#types
- Options#options
- Push notifications#types-push
Interface Definition:
- Complete API IDL#idl
Previous version:
- Old specs
---
This document outlines the complete feature set of both the REST and Realtime client libraries. It is expected that every client library developer refers to this document to ensure that their client library provides the same API and features as the existing Ably client libraries. In addition to this, it is essential that there is test coverage over all of the features described below. As an example, see the Ruby library "test specification and coverage":https://github.com/ably/ably-ruby/blob/main/SPEC.md generated from the test suite.
We recommend you use the "IDL (Interface Definition Language)":#idl and refer to other existing libraries that adhere to this spec as a reference when reviewing how the API has been implemented.
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 .
__Please note we maintain a separate Google Sheet that keeps track of which features are implemented and matching test coverage for each client library. If you intend to work on an Ably client library, please "contact us":https://ably.com/contact for access to this Google Sheet as it is useful as a reference and also needs to be kept up to date__
h2(#test-guidelines). Test guidelines
* @(G1)@ Every test should be executed using all supported protocols (i.e. JSON and "MessagePack":https://msgpack.org/ if supported). This includes both sending & receiving data
* @(G2)@ All tests by default are run against a special Ably sandbox environment. This environment allows apps to be provisioned without any authentication that can then be used for client library testing. Bear in mind that all apps created in the sandbox environment are automatically deleted after 60 minutes and have low limits to prevent abuse. Apps are configured by sending a @POST@ request to @https://sandbox-rest.ably.io/apps@ with a JSON body that specifies the keys and their associated capabilities, channel namespace rules and any presence fixture data that is required; see "ably-common test-app-setup.json":https://github.com/ably/ably-common/blob/main/test-resources/test-app-setup.json. Presence fixture data is necessary for the REST library presence tests as there is no way to register presence on a channel in the REST library
* @(G3)@ Testing statistics can be tricky due to timing issues and slow test suites as a result of sending requests to generate statistics. As such, we provide a special stats endpoint in our sandbox environment that allows stats to be injected into our metrics system so that stats tests can make predictable assertions. To create stats you must send an authenticated @POST@ request to the stats JSON to @https://sandbox-rest.ably.io/stats@ with the stats data you wish to create. See the "JavaScript stats fixture":https://github.com/ably/ably-js/blob/4e65d4e13eb8750a375b9511e4dd059092c0e481/spec/rest/stats.test.js#L8-L51 and "setup helper":https://github.com/ably/ably-js/blob/4e65d4e13eb8750a375b9511e4dd059092c0e481/spec/common/modules/testapp_manager.js#L158-L182 as an example
* @(G4)@ This spec defines API version 1.2. A client library must identify to Ably the version of the spec it uses in all requests and connections, per "RSC7a":#RSC7a and "RTN2f":#RTN2f. The spec it uses is defined as the latest API version for which the library implements all spec items relating to the wire protocol
** @(G4a)@ When sending the API version to Ably, the SDK must send the exact string specified in @G4@. Therefore, it is recommended that the SDK treat the version opaquely, as a string, not a float.
h2(#rest). REST client library
h3(#restclient). RestClient
* @(RSC1)@ The constructor accepts a set of "@ClientOptions@":#options or, in languages that support overloaded constructors, a string which may be a token string or an API key.
** @(RSC1a)@ If a single string argument is supplied when constructing the library then the library must determine whether this is a key or a token by checking for the presence of the ':' (colon) delimiter present in an API key. Any other string must be treated as a token string.
** @(RSC1b)@ If invalid arguments are provided such as no API key, no token and no means to create a token, then this will result in an error with error code 40106 and an informative message.
** @(RSC1c)@ Tests must exist that in each overloaded library constructor the library correctly determines an API key to be a key, and each type of token string is determined to be a token.
* @(RSC2)@ The logger by default outputs to @STDOUT@ (or other logging medium as appropriate to the platform) and the log level is set to warning
* @(RSC3)@ The log level can be changed
* @(RSC4)@ A custom logger can be provided in the constructor
* @(RSC5)@ @RestClient#auth@ attribute provides access to the @Auth@ object that was instantiated with the @ClientOptions@ provided in the @RestClient@ constructor
* @(RSC6)@ @RestClient#stats@ function:
** @(RSC6a)@ Returns a @PaginatedResult@ page containing @Stats@ objects in the @PaginatedResult#items@ attribute returned from the stats request
** @(RSC6b)@ Supports the following params:
*** @(RSC6b1)@ @start@ and @end@ are optional timestamp fields represented as milliseconds since epoch, or where suitable to the language, Date or Time objects. @start@, if provided, must be equal to or less than @end@ if provided or to the current time otherwise, and is unaffected by the request direction
*** @(RSC6b2)@ @direction@ backwards or forwards; if omitted the direction defaults to the REST API default (backwards)
*** @(RSC6b3)@ @limit@ supports up to 1,000 items; if omitted the limit defaults to the REST API default (100)
*** @(RSC6b4)@ @unit@ is the period for which the stats will be aggregated by, values supported are @minute@, @hour@, @day@ or @month@; if omitted the unit defaults to the REST API default (@minute@)
* @(RSC16)@ @RestClient#time@ function sends a get request to @rest.ably.io/time@ and returns the server time in milliseconds since epoch or as a Date/Time object where suitable
* @(RSC21)@ @RestClient#push@ attribute provides access to the @Push@ object that was instantiated with the @ClientOptions@ provided in the @RestClient@ constructor
* @(RSC22)@ @RestClient#batch@ attribute provides access to the @BatchOperations@ object that was instantiated with the @ClientOptions@ provided in the @RestClient@ constructor
* @(RSC7)@ Sends REST requests over HTTP and HTTPS to the REST endpoint @rest.ably.io@
** @(RSC7a)@ The header @X-Ably-Version: 1.2@ must be included in all REST requests to the Ably endpoint
** @(RSC7b)@ (Please note this clause and the associated header have now been superseded by "RCS7d":#RSC7d) The header @X-Ably-Lib: [lib][.optional variant]?-[version]@ should be included in all REST requests to the Ably endpoint where @[lib]@ is the name of the library such as @js@ for @ably-js@, @[.optional variant]@ is an optional library variant, such as @laravel@ for the @php@ library, which is always delimited with a period such as @php.laravel@, and where @[version]@ is the full client library version using "Semver":http://semver.org/ such as @1.0.2@. For example, the 1.0.0 version of the JavaScript library would use the header @X-Ably-Lib: js-1.0.0@.
*** @(RSC7b1)@ When it is not possible to send the @X-Ably-Lib@ header, such as for @JSONP@ requests, the library version should be sent as a query param such as @lib=js-1.0.0@
** @(RSC7c)@ If the @addRequestIds@ client option is enabled, every REST request to Ably should include in a @request_id@ query string parameter a random string obtained by url-safe base64-encoding a sequence of at least 9 bytes obtained from a source of randomness. This request ID must remain the same if a request is retried to a fallback host per @RSC15@. Any log messages associated with the request should include the request ID. If the request fails, the request ID must be included in the @ErrorInfo@ returned to the user.
** @(RSC7d)@ An @Agent@ library identifier is used to identify the library type and version, as well as relevant information describing any underlying layers and the client platform.
*** @(RSC7d1)@ The @Agent@ library identifier is composed of a series of @key[/value]@ entries joined by spaces where @key@ is the name of a product and @value@ is an optional version of the associated product. This must include at least the @<library name>/<library version>@ entry plus, optionally, the @name[/version]@ entry for underlying library layer or platform layers. An example would be @ably-flutter/1.2.0 ably-java/1.2.1 android/24@.
*** @(RSC7d2)@ Where possible, the @Agent@ library identifier should be included in all HTTP and WebSocket requests to the Ably endpoint via an @Ably-Agent@ HTTP header.
*** @(RSC7d3)@ Where the library is unable to specify a header when making a request (such as for @JSONP@ requests), the @Agent@ library identifier should be sent via an @agent@ query param whose value is the URI-encoded @Agent@ library identifier.
*** @(RSC7d4)@ Where possible, product versions should be represented as a valid "semantic version":https://semver.org/. This is best-effort as we recognise that strict SemVer is not always available, or otherwise possible to derive from information available at runtime, especially in the case of products that represent operating system versions.
*** @(RSC7d5)@ Products must be added to the canonical @agents@ data file in our common repository. See "Agents in ably-common":https://github.com/ably/ably-common/tree/main/protocol#agents for more information.
*** @(RSC7d6)@ Libraries may offer a @ClientOptions#agents@ property, for use only by other Ably-authored SDKs, on a need-to-have basis.
**** @(RSC7d6a)@ The product/version key-value pairs supplied to that property should be injected into all @Agent@ library identifiers emitted by connections made as a result of REST or Realtime instances created using those @ClientOptions@.
**** @(RSC7d6b)@ An API commentary must be provided for this property. This commentary must make it clear that this interface is only to be used by Ably-authored SDKs.
* @(RSC18)@ If @ClientOptions#tls@ is true, then all communication is over HTTPS. If false, all communication is over HTTP however "Basic Auth":https://en.wikipedia.org/wiki/Basic_access_authentication over HTTP will result in an error as private keys cannot be submitted over an insecure connection. See @Auth@ below
* @(RSC8)@ Supports two protocols:
** @(RSC8a)@ "MessagePack":https://msgpack.org/ binary protocol (this is the default for environments having a suitable level or support for binary data)
** @(RSC8b)@ JSON text protocol (used when @useBinaryProtocol@ option is false)
** @(RSC8c)@ The library sets the @Accept@ and @Content-Type@ request headers, to reflect whether the client is configured to use a binary or JSON based protocol, to @application/x-msgpack@ or @application/json@ respectively.
** @(RSC8d)@ If a server response indicates a @Content-Type@ that does not match the type request by the library (see "RSC8c":#RSC8c), but is a type that the library supports, then the client should process the response based on the indicated @Content-Type@.
** @(RSC8e)@ If the library is unable to process the specified content type, then the library processes the response as follows.
*** @(RSC8e1)@ In the case of a response with a @statusCode@ >= 400, an error with that @statusCode@ must be propagated back to the caller with an error message indicating that the content type is unsupported. In order to help to diagnose the cause of the error, the error message should also include text obtained by truncating the response body to a maximum of 512 bytes followed by base64-encoding.
*** @(RSC8e2)@ In the case of a response with a @statusCode@ less than 400, an error must be propagated back to the caller with a @statusCode@ of 400, a @code@ of @40013@ and an error message containing the original @statusCode@ with an error message indicating that the content type is unsupported. In order to help to diagnose the cause of the error, the error message should also include text obtained by truncating the response body to a maximum of 512 bytes followed by base64-encoding.
* @(RSC9)@ Uses @Auth@ to establish what authentication scheme to use, how to authenticate, and automatic issuing of tokens when necessary
* @(RSC10)@ If a REST request responds with a token error (401 HTTP status code and an Ably error value @40140 <= code < 40150@), then the Auth class is responsible for reissuing a token and the request should be reattempted, see "RSA4a":#RSA4a and "RSA4b":#RSA4b
* @(RSC11)@ Requests are sent to the default endpoint @rest.ably.io@. However, this endpoint can be overriden by setting either the @restHost@ or @environment@ option. See "TO3k2":#TO3k2 for constraints.
** @(RSC11a)@ If @restHost@ is set, send requests to the specified host
** @(RSC11b)@ If @environment@ is set to a value other than "production", send requests to @[environment]-rest.ably.io@. For example, if the @environment@ is set to @sandbox@, send requests to @sandbox-rest.ably.io@
* @(RSC12)@ REST endpoint host is configurable in the Client constructor with the option @restHost@
* @(RSC13)@ The client library must use the connection and request timeouts specified in the @ClientOptions@, falling back to the defaults described in @ClientOptions@ below
* @(RSC15)@ Host Fallback
** @(RSC15b)@ The fallback behavior described by this section, "RSC15":#RSC15, only applies when either:
*** @(RSC15b1)@ @ClientOptions#restHost@ has not been set to an explicit value (see "RSC11a":#RSC11a) and @ClientOptions#port@ is not set and @ClientOptions#tlsPort@ is not set
*** @(RSC15b2)@ An array of @ClientOptions#fallbackHosts@ is provided
*** @(RSC15b3)@ the deprecated @ClientOptions#fallbackHostsUseDefault@ option is set to @true@
** @(RSC15k)@ When none of the statements in "RSC15b":#RSC15b are true then host fallback does not apply, and failing HTTP requests that would have "qualified for a retry against a fallback host (see RSC15d)":#RSC15d will instead result in an error immediately
** @(RSC15e)@ The primary host is by default @rest.ably.io@ (unless overriden in @ClientOptions#environment@ or @ClientOptions#restHost@), which, through DNS, is automatically routed to the client's closest datacenter. New HTTP requests (except where @RSC15f@ applies and a cached fallback host is in effect) are first attempted against the primary host.
** @(RSC15a)@ In the case of an error necessitating use of an alternative host (see "RSC15d":#RSC15d), try fallback hosts in random order, continuing to try further hosts if "qualifying errors":#RSC15d occur, failing when all have been tried or the configured @httpMaxRetryCount@ has been reached (see "TO3l@":#TO3l5). This ensures that a client library is able to work around routing or other problems for the user's closest datacenter. For example, if a @POST@ request to @rest.ably.io@ fails because the default endpoint is unreachable or unserviceable, then the @POST@ request should be retried again against the fallback hosts in attempt to find an alternate healthy datacenter to service the request
** @(RSC15g)@ When the use of fallbacks applies, the set of fallback hosts is chosen as follows:
*** @(RSC15g1)@ If @ClientOptions#fallbackHosts@ is set to an array, use those as the fallback hosts. See "TO3k6":#TO3k6 for constraints
*** @(RSC15g2)@ If @ClientOptions#environment@ is set to a value other than "production" and @ClientOptions#fallbackHosts@ is not set, use the environment fallback hosts (see "RSC15i":#RSC15i)
*** @(RSC15g3)@ If both @ClientOptions#fallbackHosts@ and @ClientOptions#environment@ are not set, use the default fallback hosts (see "RSC15h":#RSC15h)
*** @(RSC15g4)@ For backwards-compatibility only, if @ClientOptions#fallbackHostsUseDefault@ is set to @true@ and @ClientOptions#fallbackHosts@ is not set, do not consider the value of the @ClientOptions#environment@ option and use the default fallback hosts (see "RSC15h":#RSC15h)
** @(RSC15h)@ The default fallback hosts are @a.ably-realtime.com@, @b.ably-realtime.com@, @c.ably-realtime.com@, @d.ably-realtime.com@, and @e.ably-realtime.com@
** @(RSC15i)@ The environment fallback hosts have the format @[environment]-[a-e]-fallback.ably-realtime.com@. For example, if @ClientOptions#environment@ is set to @sandbox@, the environment fallback hosts are @sandbox-a-fallback.ably-realtime.com@, @sandbox-b-fallback.ably-realtime.com@, @sandbox-c-fallback.ably-realtime.com@, @sandbox-d-fallback.ably-realtime.com@, and @sandbox-e-fallback.ably-realtime.com@
** @(RSC15j)@ Requests to fallback hosts must use a matching Host header as this is necessary when fallbacks are proxied through a CDN. For example, if a request to @rest.ably.io@ fails and will be retried to @c.ably-realtime.com@, the Host header must be set to @c.ably-realtime.com@ in the retried request
** @(RSC15d)@ Errors that necessitate use of an alternative host include: host unresolvable or unreachable, request timeout, or a response but with an applicable HTTP status code in the range @500 <= code <= 504@. Resending requests that have failed for other failure conditions will not fix the problem and will simply increase the load on other datacenters unnecessarily
** @(RSC15f)@ Once/if a given fallback host succeeds, the client should store that successful fallback host for @ClientOptions.fallbackRetryTimeout@. Future HTTP requests during that period should use that host. If during this period a "qualifying errors":#RSC15d occurs on that host, or after @fallbackRetryTimeout@ has expired, it should be un-stored, and the fallback sequence begun again from scratch, starting with the default primary host (@rest.ably.io@ or @ClientOptions#restHost@) or, in the case of an existing fallback realtime connection as per (RTN17e), with the current fallback realtime host.
* @(RSC17)@ When instantiating a @RestClient@, if a @clientId@ attribute is set in @ClientOptions@, then the @Auth#clientId@ attribute will contain the provided @clientId@
* @(RSC19)@ @RestClient#request@ function is provided as a convenience for customers who wish to use REST API functionality that is either not documented or is not included in the API for our client libraries. The REST client library provides a function to issue HTTP requests to the Ably endpoints with all the built in functionality of the library such as authentication, paging, fallback hosts, MsgPack and JSON support etc. The function:
** @(RSC19a)@ Method signature is @request(string method, string path, Dict<String, String> params?, JsonObject | JsonArray body?, Dict<String, String> headers?) -> HttpPaginatedResponse@ with arguments: @method@ is a valid "HTTP verb":https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html (must support @"GET"@, @"POST"@, and @"PUT"@, should support @"PATCH"@ and @"DELETE", may support others); @path@ is the path component of the URL such as @"/channels"@; @params@ and @headers@ are optional arguments containing pairs of key value strings (multi-valued headers are not supported) that will result in query params and HTTP headers being added respectively in the request (the argument types can be idiomatic for the language such as @Object@ in the case of JavaScript); @body@ is an optional @JsonObject@ or @JsonArray@ like object argument that can be easily serialized to MsgPack or JSON
** @(RSC19b)@ All requests will unconditionally use the default authentication mechanism configured for the REST client i.e. basic or token authentication (see "Auth":#rest-auth)
** @(RSC19c)@ The library will configure the @Accept@ and @Content-Type@ type headers to reflect whether the client is configured to use a binary or JSON based protocol (see "RSC8":#RSC8). All requests are encoded and decoded into Json or MsgPack as appropriate automatically by the library. Binary @body@ payloads are not supported at this time
** @(RSC19d)@ @request@ method returns an @HttpPaginatedResponse@ object that inherits from the @PaginatedResult@ object to provide details on the response plus paging support where applicable. See "HP1":#HP1 for more details
** @(RSC19e)@ If the HTTP network request fails for reasons such as a timeout (after the underlying fallback host attempts have failed where applicable, see "RSC15":#RSC15), then the @request@ method should indicate an error in an idiomatic way for the platform
* @(RSC20)@ (deprectated) Unexpected internal library exception handling:
** @(RSC20a)@ The library must make every attempt to handle unexpected internal exceptions as gracefully as possible. For the avoidance of doubt, unexpected internal exceptions do not include request timeouts, invalid argument values, invalid responses from third parties or exceptions in code run in callbacks registered by applications. However, any unexpected failures or unhandled exceptions in our own code that typically could trigger a crash or raise an exception in our customer's code, is considered an unexpected internal exception
** @(RSC20b)@ The library may optionally report unexpected internal exceptions to the Ably exception reporting service. Exception reporting, when supported, is enabled by default, but can be disabled using the @logExceptionReportingUrl@ @ClientOption@ documented in "@TO3m@":#TO3m. When enabled, the client library must:
*** @(RSC20b1)@ At startup log a message with the equivalent of @info@ log level with the message "Ably client library exception reporting enabled. Unhandled failures will be automatically submitted to errors.ably.io to help improve our service. To find out more about this feature, see https://help.ably.io/exceptions". The @info@ log level is preferred as customers can hide this entry by configuring the client library log level to @warning@, yet will, by default, see this notice when using a client library with exception reporting enabled
*** @(RSC20b2)@ Any unhandled internal exceptions should automatically submit bug reports to the @logExceptionReportingUrl@ using the "@Sentry API@":https://docs.sentry.io/clientdev/ either via a raw HTTP request or by using an embedded "Sentry exception reporting client library":https://docs.sentry.io/clients/. A message at @info@ log level should be logged if the request succeeds or fails i.e. a failure to submit an exception should not be logged as a failure / error. Where possible, the exception GUID returned from the Sentry API should be logged so that the specific error can be tracked
** @(RSC20c)@ Exceptions reported must additionally include the following tags: @ably-lib@ with the value defined in "@RSC7b@":#RSC7b, @ably-version@ with the value defined in "@RSC7a@":#RSC7a, @appId@ if known from either the token or API key currently being used.
** @(RSC20d)@ All personally identifiable information, as much as is practicable, must be redacted or stripped completely before being submitted to Ably. Our intent is only to capture necessary information to debug issues in our own code
** @(RSC20e)@ Failures to log exceptions to the @errors.ably.io@ endpoint must be handled gracefully. This includes for example DNS failures, TCP/HTTP requests rejected, slow requests and internal failure errors. Additionally, as specified in @RSC20b2@, a failure to log an exception is logged with log level @info@ i.e. an exception reporting failure is not consider a client library @error@ or @warning@
** @(RSC20f)@ Any errors emitted by the library as a result of an internal failure must contain a status code @500@, an error code in the range @51000@ to @51999@ and a suitable error message. The error code must match one of "our common error codes":https://github.com/ably/ably-common/blob/main/protocol/errors.json
h3(#rest-auth). Auth
* @(RSA1)@ "Basic Auth":https://en.wikipedia.org/wiki/Basic_access_authentication connects over HTTPS by default. Any attempt to use Basic Auth over HTTP without TLS will result in an error
* @(RSA11)@ When using Basic Auth, the API key is Base64 encoded and included in an @Authorization@ header, as specified in "RFC7235":https://tools.ietf.org/html/rfc7235. The API key follows the format @"KEY_NAME:KEY_SECRET"@ so when authenticating using "Basic Auth":https://en.wikipedia.org/wiki/Basic_access_authentication, the key name can be used as the username and the key secret as the password
* @(RSA2)@ "Basic Auth":https://en.wikipedia.org/wiki/Basic_access_authentication is the default authentication scheme if an API key exists
* @(RSA3)@ Token Auth:
** @(RSA3a)@ Can be used over HTTP or HTTPs
** @(RSA3b)@ For REST requests, the token string is optionally Base64-encoded and used in the @Authorization: Bearer@ header
** @(RSA3c)@ For Realtime "websocket connections":https://ably.com/topic/websockets, the querystring param @accessToken@ is appended to the URL endpoint
** @(RSA3d)@ A test must exist that each type of token string is correctly passed in requests (ie according to @(RSA3b)@ and @(RSA3c)@)
* @(RSA4)@ Token Auth is used if @useTokenAuth@ is set to true, or if @useTokenAuth@ is unspecified and any one of @authUrl@, @authCallback@, @token@, or @TokenDetails@ is provided
** @(RSA4a)@ When a @token@ or @tokenDetails@ is used to instantiate the library, and no means to renew the token is provided (either an API key, @authCallback@ or @authUrl@):
*** @(RSA4a1)@ At instantiation time, a message at @info@ log level with error code @40171@ should be logged indicating that no means has been provided to renew the supplied token, including an associated url per @TI5@
*** @(RSA4a2)@ if the server responds with a token error (401 HTTP status code and an Ably error value @40140 <= code < 40150@), then the client library should indicate an error with error code @40171@, not retry the request and, in the case of the realtime library, transition the connection to the @FAILED@ state
** @(RSA4b)@ When the client does have a means to renew the token automatically, and the server has responded with a token error (@statusCode@ value of 401 and error @code@ value in the range @40140 <= code < 40150@) or the client library has optionally detected the current token has expired (see "RSA4b1":#RSA4b1), then the client should automatically make a single attempt to reissue the token and resend the request using the new token. If the token creation failed or the subsequent request with the new token failed due to a token error, then the request should result in an error (in the case of a realtime library, follow @RSA4c@)
*** @(RSA4b1)@ Client libraries can optionally save a round-trip request to the Ably service for expired tokens by detecting when a token has expired when all of the following applies: the current token is a @TokenDetails@ object with an @expires@ attribute; the library has previously queried the time from the Ably service and persisted the local clock offset according to "RSA10k":#RSA10k; the @expires@ time has passed based on the Ably service time and not the local clock (which is not guaranteed to be accurate)
** @(RSA4c)@ If an attempt by the realtime client library to authenticate is made using the @authUrl@ or @authCallback@, and the request to @authUrl@ fails (unless @RSA4d@ applies), the callback @authCallback@ results in an error (unless "RSA4d":#RSA4d applies), an attempt to exchange a @TokenRequest@ for a @TokenDetails@ results in an error (unless "RSA4d":#RSA4d applies), the provided token is in an invalid format (as defined in "RSA4e":#RSA4e), or the attempt times out after "@realtimeRequestTimeout@":#TO3l11, then:
*** @(RSA4c1)@An @ErrorInfo@ with @code@ @80019@, @statusCode@ 401, and @cause@ set to the underlying cause should be emitted with the state change if there is one (per @RSA4c2/3@) and set as the connection @errorReason@
*** @(RSA4c2)@If the connection is @CONNECTING@, then the connection attempt should be treated as unsuccessful, and as such the connection should transition to the @DISCONNECTED@ or @SUSPENDED@ state as defined in "RTN14":#RTN14 and "RTN15":#RTN15
*** @(RSA4c3)@If the connection is @CONNECTED@, then the connection should remain @CONNECTED@
** @(RSA4d)@ If a request by a realtime client to an @authUrl@ results in an HTTP 403 response, or any of an @authUrl@ request, an @authCallback@, or a request to Ably to exchange a @TokenRequest@ for a @TokenDetails@ result in an @ErrorInfo@ with @statusCode@ 403, as part of an attempt by the realtime client to authenticate, then the client library should transition to the @FAILED@ state, with an @ErrorInfo@ (with @code@ @80019@, @statusCode@ 403, and @cause@ set to the underlying cause) emitted with the state change and set as the connection @errorReason@
*** @(RSA4d1)@ An "attempt by the realtime client to authenticate" in @RSA4c@ and @RSA4d@ includes getting a token as part of the connect sequence, an @RTN22@ online reauth, and an explicit @authorize()@ call, but _not_ an explicit @requestToken@ call, which should have no effect on library state
** @(RSA4e)@ If in the course of a REST request (or explicit call to @requestToken@) an attempt to authenticate using @authUrl@ or @authCallback@ fails due to a timeout, network error, a token in an invalid format (per "RSA4f":#RSA4f), or some other auth error condition other than an explicit @ErrorInfo@ from Ably, the request should result in an error with @code@ 40170, @statusCode@ 401, and a suitable error message
** @(RSA4f)@ The following conditions imply that the token is in an invalid format: the @authUrl@ response content type is not one of @text/plain@, @application/json@ or @application/jwt@; the object passed by @authCallback@ is neither a @String@, @JsonObject@, @TokenRequest@ object, nor @TokenDetails@ object; the token string or the JSON stringified @JsonObject@, @TokenRequest@ or @TokenDetails@ is greater than 128KiB.
** @(RSA4g)@ If multiple @authOptions@ are used to initialize the library, the preference ordering among them is identical to @Auth#authorize@, defined in @RSA10e@
* @(RSA14)@ If Token Auth is selected, yet a token is not provided and there is no means to generate a token, then this will result in an error. For example, if only the option @useTokenAuth@ is specified, and a @key@ is not provided, then the client library is unable to authenticate or issue a token
* @(RSA15)@ If Token Auth is selected and @clientId@ has been set in the @ClientOptions@ when the library was instantiated:
** @(RSA15a)@ Any @clientId@ provided in @ClientOptions@ must match any non wildcard (@'*'@) @clientId@ value in @TokenDetails@ or @connectionDetails@ of the @CONNECTED@ @ProtocolMessage@, where applicable
** @(RSA15b)@ If the clientId from @TokenDetails@ or @connectionDetails@ contains only a wildcard string '*', then the client is permitted to be either unidentified (i.e. authorised to act on behalf of any clientId) or identified by providing a @clientId@ when communicating with Ably
** @(RSA15c)@ Following an auth request which uses a @TokenDetails@ or @TokenRequest@ object that contains an incompatible @clientId@, the library should in the case of Realtime transition the connection state to @FAILED@, and in the case of REST result in an appropriate error response
* @(RSA5)@ TTL for new tokens is specified in milliseconds. If the user-provided @tokenParams@ does not specify a TTL, the TTL field should be omitted from the @tokenRequest@, and Ably will supply a token with a TTL of 60 minutes. See "TK2a":#TK2a
* @(RSA6)@ The @capability@ for new tokens is JSON stringified. If If the user-provided @tokenParams@ does not specify capabilities, the @capability@ field should be omitted from the @tokenRequest@, and Ably will supply a token with the capabilities of the underlying key. See "TK2b":#TK2b
* @(RSA7)@ @clientId@ and authenticated clients:
** @(RSA7d)@ If @clientId@ is provided in @ClientOptions@ and @RSA4@ indicates that token auth is to be used, the @clientId@ field in the @TokenParams@ (@TK2c@) should be set to that @clientId@ when requesting a token
** @(RSA7e)@ If @clientId@ is provided in @ClientOptions@ and @RSA4@ indicates that basic auth is to be used, then:
*** @(RSA7e1)@ For realtime clients, the connect request should include the @clientId@ as a querystring parameter, @clientId@
*** @(RSA7e2)@ For REST clients, all requests should include an @X-Ably-ClientId@ header with value set to the @clientId@, Base64 encoded
** @(RSA7a)@ A client is considered to be identified if a @clientId@ is implicit in either the connection or the authentication scheme; that is, is present in the current authentication token (with the exception of the wildcard @clientId@ @'*'@), is set by a header per @RSA7e2@, or is specified when initiating a realtime connection per @RSA7e1@. The following applies to identified clients:
*** @(RSA7a1)@ All operations (such as message publishing or presence) carried out by an identified client will have an implicit @clientId@. The Ably service automatically updates the @clientId@ attribute (when empty) for all @Message@ and @PresenceMessage@ messages received from that client. Client libraries should therefore not explicitly set the @clientId@ field on messages published from an identified client
*** @(RSA7a4)@ When a @clientId@ value is provided in both @ClientOptions#clientId@ and @ClientOptions#defaultTokenParams@, the @ClientOptions#clientId@ takes precedence and is used for all Auth operations
** @(RSA12)@ @Auth#clientId@ attribute is @null@ when:
*** @(RSA12a)@ The @clientId@ attribute of a @TokenRequest@ or @TokenDetails@ used for authentication is @null@, or @ConnectionDetails#clientId@ is @null@ following a connection to Ably. In this case, the @null@ value indicates that a @clientId@ identity may not be assumed by this client i.e. the client is anonymous for all operations
*** @(RSA12b)@ The client was instantiated without assigning a value for @ClientOptions#clientId@ (@null@), and the client has not yet authenticated or connected to Ably. In this case, the @null@ value indicates that the client has not yet been able to confirm its identity, and therefore may change and become identified following later authentication or establishment of a connection with Ably
** @(RSA7b)@ @Auth#clientId@ is not @null@ when:
*** @(RSA7b1)@ A @clientId@ is provided in the @ClientOptions@. @clientId@ should be a string
*** @(RSA7b2)@ Token authentication is being used, and the @TokenRequest@ or @TokenDetails@ object, used for authentication, has a @clientId@ value that is not @null@
*** @(RSA7b3)@ Following a realtime connection being established, if the @CONNECTED@ @ProtocolMessages@ contains a @clientId@ that is not @null@. @clientId@ is an attribute of @ProtocolMessage#connectionDetails@ within a @CONNECTED@ @ProtocolMessage@
*** @(RSA7b4)@ When a wildcard string @'*'@ is present in the @TokenRequest@, @TokenDetails@, or @ProtocolMessage#connectionDetails@ object, then the client does not have an identity but is allowed to assume an identity when performing operations with Ably. As such, @Auth#clientId@ should contain the string value @'*'@ indicating that the current client is allowed to perform operations on behalf of any @clientId@
** @(RSA7c)@ A @clientId@ provided in the @ClientOptions@ when instantiating a @RestClient@ must be either @null@ or a string, and cannot contain only a wildcard @'*'@ string value as that client ID value is reserved
* @(RSA8)@ @Auth#requestToken@ function:
** @(RSA8e)@ Method signature is @requestToken(TokenParams, AuthOptions)@. @TokenParams@ and @AuthOptions@ are optional. When @TokenParams@ or @AuthOptions@ are provided, the values of each attribute are not merged with the configured client library defaults, but rather are used instead of the stored values (even when @null@). If the object arguments are omitted, the client library configured defaults are used
** @(RSA8a)@ Implicitly creates a @TokenRequest@ if required, and requests a token from Ably if required. Returns a @TokenDetails@ object
** @(RSA8b)@ Supports all @TokenParams@ in the function arguments, which override defaults for @Client@ @Auth@
** @(RSA8c)@ When @authUrl@ option is set, it will query the provided URL to obtain a @TokenRequest@ or the token itself (either a token string or a @TokenDetails@). The query is performed using the given URL using the HTTP method in @authMethod@, headers (from @authHeaders@) and supplementary params (from @authParams@). The token retrieved is assumed by the library to be a token string if the response has @Content-Type@ @"text/plain"@ or @"application/jwt"@, or taken to be a @TokenRequest@ or @TokenDetails@ object if the response has @Content-Type@ @"application/json"@. @authMethod@ can be either @GET@ or @POST@, or if not specified, will default to @GET@. It can be quite difficult to add test coverage for these scenarios - as such, we have developed a simple echo server that can be used in your tests, see the "ably-js authUrl echo tests":https://github.com/ably/ably-js/commit/e77b2c6c197bc71f3d27084fe54524724a00bc92
*** @(RSA8c1)@ @TokenParams@ and any configured @authParams@ and @authHeaders@ are always sent to the @authUrl@ as follows:
**** @(RSA8c1a)@ When the @authMethod@ is @GET@ or unspecified, the @TokenParams@ and @authParams@ are merged and appended to the URL as query string params, and the @authHeaders@ are sent as HTTP headers
**** @(RSA8c1b)@ When the @authMethod@ is @POST@, the @TokenParams@ and @authParams@ are merged and sent form-encoded in the body of the @POST@ request, and the @authHeaders@ are sent as HTTP headers
**** @(RSA8c1c)@ If the given @authUrl@ includes any querystring params, they should be preserved. In the @GET@ case, @authParams@/@tokenParams@ should be merged with them. If a name conflict occurs, @authParams@/@tokenParams@ should take precedence
*** @(RSA8c2)@ @TokenParams@ take precedence over any configured @authParams@ when a name conflict occurs
*** @(RSA8c3)@ Specifying @authParams@ or @authHeaders@ as part of @AuthOptions@ replaces any configured @authParams@ or @authHeaders@ specified in @ClientOptions@ respectively. As the provided key/value pairs are not merged with the @ClientOptions@ configured key/value pairs, this enables a developer to delete @authParams@ or @authHeaders@ where necessary by providing an entire new set of key/value pairs
** @(RSA8d)@ When @authCallback@ option is set, it will invoke the callback, passing in the @TokenParams@, and expects either a token string, a @TokenDetails@ object or a @TokenRequest@ object to be returned, which will in turn be used to request a token from Ably
** @(RSA8f)@ A test should exist for the following:
*** @(RSA8f1)@ Request a token with a @null@ value @clientId@, authenticate a client with the token, publish a message without an explicit @clientId@, and ensure the message published does not have a @clientId@. Check that @Auth#clientId@ is @null@
*** @(RSA8f2)@ Request a token with a @null@ value @clientId@, authenticate a client with the token, publish a message with an explicit @clientId@ value, and ensure that the message is rejected
*** @(RSA8f3)@ Request a token with a wildcard @'*'@ value @clientId@, authenticate a client with the token, publish a message without an explicit @clientId@, and ensure the message published does not have a @clientId@. Check that @Auth#clientId@ is a string with value @'*'@
*** @(RSA8f4)@ Request a token with a wildcard @'*'@ value @clientId@, authenticate a client with the token, publish a message with an explicit @clientId@ value, and ensure that the message published has the provided @clientId@
** @(RSA8g)@ Tests must exist to verify both the @authCallback@ and @authURL@ mechanisms where the returned token string value is a JWT token string and an Ably token string.
* @(RSA9)@ @Auth#createTokenRequest@ function:
** @(RSA9h)@ Method signature is @createTokenRequest(TokenParams, AuthOptions)@. @TokenParams@ and @AuthOptions@ are optional.When @TokenParams@ or @AuthOptions@ are provided, the values of each attribute are not merged with the configured client library defaults, but rather are used instead of the stored values (even when @null@). If the object arguments are omitted, the client library configured defaults are used
** @(RSA9a)@ Returns a signed @TokenRequest@ object that can be used to obtain a token from Ably. This is useful for servers that can create a @TokenRequest@ signed with the API key without communicating with Ably directly. The @TokenRequest@ can then be passed to a designated client that is then responsible for communicating with Ably and requesting a token for authentication from that @TokenRequest@
** @(RSA9c)@ Generates a unique 16+ character @nonce@ if none is provided; the nonce is used to protect against replay attacks
** @(RSA9d)@ Generates a @timestamp@ from current time if not provided, will retrieve the server time if @queryTime@ is true
** @(RSA9e)@ TTL is optional and specified in milliseconds
** @(RSA9f)@ Capability JSON text can be provided that specifies the rights of the token in terms of the channel(s) authorized and the permitted operations on each
** @(RSA9g)@ A valid HMAC is created using the key secret (using the key from the passed-in @AuthOptions@ if supplied) to sign the @TokenRequest@ so that it can be used by any client to request a token without having or exchanging any secrets
** @(RSA9i)@ Adheres to all requirements in @RSA8@ relating to @TokenParams@
* @(RSA10)@ @Auth#authorize@ function:
** @(RSA10a)@ Instructs the library to create a token immediately and ensures Token Auth is used for all future requests. See "RTC8":#RTC8 for re-authentication behavior when called for a realtime client
** @(RSA10j)@ Method signature is @authorize(TokenParams, AuthOptions)@. @TokenParams@ and @AuthOptions@ are optional. When the arguments are present, even if empty, the @TokenParams@ and @AuthOptions@ supersede any previously client library configured @TokenParams@ and @AuthOptions@. For example, if a client is initialized with @TokenParams#ttl@ configured with a custom value, and a @TokenParams@ object is passed in as an argument to @#authorize@ with a @null@ or missing value for @ttl@, then the @ttl@ used for every subsequent authorization will be @null@
** @(RSA10b)@ Supports all @AuthOptions@ and @TokenParams@ in the function arguments
** @(RSA10k)@ If the @AuthOption@ argument's @queryTime@ attribute is true, it will obtain the server time once and persist the offset from the local clock. All future token requests generated directly or indirectly via a call to @authorize@ will not obtain the server time, but instead use the local clock offset to calculate the server time. The client library itself MAY internally discard the cached local clock offset in situations in which it may have been invalidated, such as if there is a local change to the date, time, or timezone, of the client device. For clarity however, there is no requirement for this cache invalidation to be available to consumers of the client library API.
** @(RSA10e)@ If the @authOptions@ contains a way of obtaining a token (an @authCallback@, @authUrl@, or @key@), that should be used to obtain a new token, as per @requestToken@ (@RSA8@). If it contains a token (@token@ or @tokenDetails@), that should be used as-is. If it contains both a token and a way of obtaining a token, the token should be used, with the way of obtaining a token being stored per @RSA10g@ for when the token expires. (Ordering of preference within those groups is not defined and is left up to individual implementations)
** @(RSA10f)@ Returns a @TokenDetails@ object that contains the token string + token metadata
** @(RSA10g)@ Stores the @AuthOptions@ and @TokenParams@ arguments as defaults for subsequent authorizations with the exception of the attributes @TokenParams#timestamp@ and @AuthOptions#queryTime@
** @(RSA10h)@ Will use the value from @Auth#clientId@ by default, if not @null@
** @(RSA10i)@ Adheres to all requirements in @RSA8@ relating to @TokenParams@, @authCallback@ and @authUrl@
** @(RSA10l)@ Has an alias method @RestClient#authorise@ and @RealtimeClient#authorise@ that will log a deprecation warning stating that this alias method will be removed in @v1.0@ and the user should instead use @authorize@
* @(RSA16)@ @Auth#tokenDetails@:
** @(RSA16a)@ Holds a @TokenDetails@ representing the token currently in use by the library, if any;
** @(RSA16b)@ If the library is provided with a token without the corresponding @TokenDetails@, then this holds a @TokenDetails@ instance in which only the @token@ attribute is populated with that token string
** @(RSA16c)@ Is set with the current token (if applicable) on instantiation and each time it is replaced, whether the result of an explicit @Auth#authorize@ operation, or a library-initiated renewal resulting from expiry or a token error response
** @(RSA16d)@ Is @null@ if there is no current token, including after a previous token has been determined to be invalid or expired, or if the library is using basic auth
h3(#rest-channels). Channels
* @(RSN1)@ @Channels@ is a collection of @RestChannel@ objects accessible through @RestClient#channels@
* @(RSN2)@ Methods should exist to check if a channel exists or iterate through the existing channels
* @(RSN3)@ @Channels#get@ function:
** @(RSN3a)@ Creates a new @RestChannel@ object for the specified channel if none exists, or returns the existing channel. @ChannelOptions@ can be provided in an optional second argument
** @(RSN3b)@ If options are provided, the options are set on the @RestChannel@
** @(RSN3c)@ Accessing an existing @RestChannel@ with options in the form @Channels#get(channel, options)@ will update the options on the channel and then return the existing @RestChannel@ object. (Note that this is soft-deprecated and may be removed in a future release, so should not be implemented in new client libraries. The supported way to update a set of @ChannelOptions@ is @RestChannel#setOptions@)
* @(RSN4)@ @Channels#release@ function:
** @(RSN4a)@ Takes one argument, the channel name, and releases the corresponding channel entity (that is, deletes it to allow it to be garbage collected)
** @(RSN4b)@ Calling @release()@ with a channel name that does not correspond to an extant channel entity must return without error
** @(RSN4c)@ This clause has been deleted.
h3(#rest-channel). RestChannel
* @(RSL9)@ @RestChannel#name@ attribute is a string containing the channel’s name
* @(RSL1)@ @RestChannel#publish@ function:
** @(RSL1a)@ Expects either a @Message@ object, an array of @Message@ objects, or a @name@ string and @data@ payload
** @(RSL1b)@ When @name@ and @data@ (or a @Message@) is provided, a single message is published to Ably
** @(RSL1c)@ When an array of @Message@ objects is provided, a single request is made to Ably
** @(RSL1d)@ Indicates an error if the message was not successfully published to Ably
** @(RSL1e)@ Allows @name@ and/or @data@ to be @null@. If any of the values are @null@, that property is not sent to Ably, e.g. a payload with a @null@ value for @data@ would be sent as @{"name":"click"}@
** @(RSL1m)@ The @Message.clientId@ must be left alone (that is, it will be there if it was set in the @Message@ object passed to @publish()@, else left unset). The client library must not try and set it from the client-library-wide @clientId@; that is achieved by @RSA7e@ for basic auth or implicit in the credentials for token auth. The following tests can be used to check for correct clientId handling:
*** @(RSL1m1)@ Publishing a @Message@ with no clientId when the clientId is set to some value in the client options should result in a message received with the @clientId@ property set to that value
*** @(RSL1m2)@ Publishing a @Message@ with a clientId set to the same value as the clientId in the client options should result in a message received with the @clientId@ property set to that value
*** @(RSL1m3)@ Publishing a @Message@ with a clientId set to a value from an unidentified client (no clientId in the client options and credentials that can assume any clientId) should result in a message received with the @clientId@ property set to that value
*** @(RSL1m4)@ Publishing a @Message@ with a clientId set to a different value from the clientId in the client options should result in a message being rejected by the server
** @(RSL1h)@ The @publish(name, data)@ form should not take any additional arguments. If a client library has supported additional arguments to the @(name, data)@ form (e.g. separate arguments for @clientId@ and @extras@, or a single @attributes@ argument) in any 1.x version, it should continue to do so until version 2.0.
** @(RSL1i)@ If the total size of the message or (if publishing an array) messages, calculated per "TO3l8":#TO3l8, exceeds the @maxMessageSize@, then the client library should reject the publish and indicate an error with code 40009
** @(RSL1j)@ When @Message@ objects are provided, any valid @Message@ attribute (that is, an attribute specified in "TM2":#TM2) that is supplied by the caller must be included in the encoded message. (This does not mean it must be included _unaltered_; for example the @data@ and @encoding@ will be subject to processing per "RSL4":#RSL4)
** @(RSL1k)@ Idempotent publishing via REST is supported by populating the @id@ attribute of @Message@ instances passed to @publish()@:
*** @(RSL1k1)@ Idempotent publishing via library-generated @Message@ @id@ s is supported if @idempotentRestPublishing@ (see "TO3n":#TO3n) is enabled and one or more @Message@ instances are passed to @publish()@ and all @Message@ s have an empty @id@ attribute. The library generates a base @id@ string by base64-encoding a sequence of at least 9 bytes obtained from a source of randomness. Each individual @Message@ in the set of messages to be published is assigned a unique @id@ of the form <base id>:<serial> (where @serial@ is the zero-based index into the set).
*** @(RSL1k2)@ Idempotent publishing via client-supplied @Message@ @id@ s is supported where a single @Message@ is passed to @publish()@ and it contains a non-empty @id@. The @id@ is preserved on sending the message.
*** @(RSL1k3)@ If more than one @Message@ is passed to @publish()@ and one or more of those messages contains a non-empty @id@ attribute, then all message ids (present or absent) are preserved on sending the batch of messages.
*** @(RSL1k4)@ An explicit test for idempotency of publishes with library-generated ids shall exist that simulates an error response to a successful publish of a batch of messages, expects an automatic retry by the library, and verifies that the net outcome is that the batch is published only once.
*** @(RSL1k5)@ An explicit test for idempotency of publishes with client-supplied ids shall exist that involves multiple explicit publish requests for a given message and verifies that the net outcome is that the message is published only once.
** @(RSL1l)@ The @publish(Message)@ and @publish(Message[])@ forms of the method should take an extra @Dict<String, Stringifiable>@ argument. These parameters should be encoded using normal querystring-encoding and sent as part of the query string of the REST publish. (@Stringifiable@ is defined in @RTC1f@)
*** @(RSL1l1)@ Publish params can be tested by publishing with a @_forceNack=true@ parameter, which will result in the publish being rejected with a @40099@ error code
* @(RSL2)@ @RestChannel#history@ function:
** @(RSL2a)@ Returns a @PaginatedResult@ page containing the first page of messages in the @PaginatedResult#items@ attribute returned from the history request
** @(RSL2b)@ Supports the following params:
*** @(RSL2b1)@ @start@ and @end@ are timestamp fields represented as milliseconds since epoch, or where suitable to the language, Time objects. @start@ must be equal to or less than @end@ and is unaffected by the request direction
*** @(RSL2b2)@ @direction@ backwards or forwards; if omitted the direction defaults to the REST API default (backwards)
*** @(RSL2b3)@ @limit@ supports up to 1,000 items; if omitted the direction defaults to the REST API default (100)
* @(RSL3)@ @RestChannel#presence@ attribute contains a @RestPresence@ object for this channel
* @(RSL4)@ Message encoding
** @(RSL4a)@ Payloads must be binary, strings, or objects capable of JSON representation, or can be empty (omitted). Any other data type should not be permitted and result in an error
** @(RSL4b)@ If a message is encoded, the @encoding@ attribute represents the encoding(s) applied in right to left format i.e. "utf-8/base64" indicates that the original payload has "utf-8" encoding and has subsequently been encoded in Base64 format
** @(RSL4c)@ When using MessagePack Message encoding
*** @(RSL4c1)@ a binary Message payload is encoded as MessagePack binary type
*** @(RSL4c2)@ a string Message payload is encoded as MessagePack string type
*** @(RSL4c3)@ a JSON Message payload is stringified either as a JSON Object or Array and encoded as MessagePack string type and the @encoding@ attribute is set to "json"
*** @(RSL4c4)@ All messages received will deliver payloads in the format they were sent in i.e. binary, string, or a structured type containing the parsed JSON
** @(RSL4d)@ When using JSON Message encoding
*** @(RSL4d1)@ a binary Message payload is encoded as Base64 and represented as a JSON string the @encoding@ attribute is set to "base64"
*** @(RSL4d2)@ a string Message payload is represented as a JSON string
*** @(RSL4d3)@ a JSON Message payload is stringified either as a JSON Object or Array and represented as a JSON string and the @encoding@ attribute is set to "json"
*** @(RSL4d4)@ All messages received will be decoded based on the @encoding@ field and deliver payloads in the format they were sent in i.e. binary, string, or a structured type containing the parsed JSON
* @(RSL5)@ Message payload encryption
** @(RSL5a)@ When a @RestChannel@ is instantiated with a (non-null) @cipher@ channelOption, message payloads will be automatically encrypted when sent to Ably and decrypted when received on this channel, using the @cipher@ configuration
** @(RSL5b)@ AES 256 and 128 CBC encryption must be supported
** @(RSL5c)@ Tests must exist that encrypt and decrypt the following fixture data for "AES 128":https://github.com/ably/ably-common/blob/main/test-resources/crypto-data-128.json and "AES 256":https://github.com/ably/ably-common/blob/main/test-resources/crypto-data-256.json to ensure the client library encryption is compatible across libraries
* @(RSL6)@ Message decoding
** @(RSL6a)@ All messages received will be decoded automatically based on the @encoding@ field and the payloads will be converted into the format they were originally sent using i.e. binary, string, or JSON
*** @(RSL6a1)@ A set of tests must exist to ensure that the client library provides data encoding & decoding interoperability with other client libraries. The tests must use the "set of predefined interoperability message fixtures":https://github.com/ably/ably-common/blob/main/test-resources/messages-encoding.json to 1) publish a raw message to the REST API using the JSON transport and subscribe to the message using Realtime to ensure the @data@ attribute matches the fixture; 2) publish a message using the REST client library and retrieve the raw message using the history REST API using the JSON transport ensuring the @data@ matches the fixture; 3) perform the client library operation using both @JSON@ and @MsgPack@ transports. For reference, see the "Ruby":https://github.com/ably/ably-ruby/pull/94 and "iOS":https://github.com/ably/ably-cocoa/pull/459 implementations
*** @(RSL6a2)@ A set of tests must exist to ensure that the client library provides interoperability for the @extras@ field which is a JSON-encodable object (ie a value that represents a JSON @object@ value and supports serialization to and from JSON text). The test, at a minimum, should publish a message with an @extras@ object such as @{"push":[{"title":"Testing"}]}@ and ensure it is received with an equivalent JSON-encodable object
** @(RSL6b)@ If, for example, incompatible encryption details are provided or invalid Base64 is detected in the message payload, an error message will be sent to the logger, but the message will still be delivered with last successful decoding and the @encoding@ field. For example, if a message had a decoding of "utf-8/cipher+aes-128-cbc/base64", and the payload was successfully Base64 decoded but the payload could not be decrypted because the @CipherParam@ details were not configured, the message would be delivered with a binary payload and an @encoding@ with the value "utf-8/cipher+aes-128-cbc". Additional steps need to be taken if decoding failed on "vcdiff" encoding; see "RTL18":#RTL18
* @(RSL7)@ @RestChannel#setOptions@ takes a @ChannelOptions@ object and sets or updates the stored channel options, then indicates success
* @(RSL8)@ @RestChannel#status@ function: makes a http get request to @<restHost>/channels/<channelId>@ where @<restHost>@ represents the current rest host as described by "@RSC11@":#RSC11
** @(RSL8a)@ Returns a @ChannelDetails@ object
h3(#plugins). Plugins
* @(PC1)@ Specific client library features that are not commonly used may be supplied as independent libraries, as plugins, in order to avoid excessively bloating the client library. Although such plugins are packaged as independent libraries, they are still considered logically to be part of the client library code and, as such, may be tightly coupled with the client library implementation. The client library can be assumed to be aware of the plugin specific type and capabilities, and such plugins may by design be coupled to a specific version of the client library.
* @(PC2)@ No generic plugin interface is specified, and therefore there is no common API exposed by all plugins. However, for type-safety, the opaque interface @Plugin@ should be used in strongly-typed languages as the type of the @ClientOptions.plugins@ collection as per "TO3o":#TO3o.
* @(PC3)@ A plugin provided with the @PluginType@ enum key value of @vcdiff@ should be capable of decoding "vcdiff"-encoded messages. It must implement the @VCDiffDecoder@ interface and the client library must be able to use it by casting it to this interface.
** @(PC3a)@ The base argument of the @VCDiffDecoder.decode@ method should receive the stored base payload of the last message on a channel as specified by "RTL19":#RTL19. If the base payload is a string it should be encoded to binary using UTF-8 before being passed as base argument of the @VCDiffDecoder.decode@ method.
h3(#plugin-type). PluginType
* @(PT1)@ @PluginType@ is an enum describing the different types of plugins that the library supports. See the @ClientOptions#plugins@ property ("TO3o":#TO3o).
* @(PT2)@ @PluginType@ takes one of the following values:
** @(PT2a)@ @vcdiff@ – see "PC3":#PC3.
h3(#vcdiff-decoder). VCDiffDecoder
* @(VD1)@ @VCDiffDecoder@ provides an interface for decoding "vcdiff"-encoded message payloads.
* @(VD2)@ @VCDiffDecoder@ has the following interface:
** @(VD2a)@ class method @decode([byte] delta, [byte] base) -> [byte]@ - as described by "PC3a":#PC3a, given a base payload and the delta provided by a subsequent message, this returns the payload of that message
h3(#rest-presence). RestPresence
* @(RSP1)@ RestPresence object is associated with a single channel and is accessible through @RestChannel#presence@
* @(RSP2)@ There is no way to register a member as present on a channel via the REST API
* @(RSP3)@ @RestPresence#get@ function:
** @(RSP3a)@ Returns a @PaginatedResult@ page containing the first page of members present in the @PaginatedResult#items@ attribute returned from the presence request. Each member is represented as a @PresenceMessage@. Supports the following params:
*** @(RSP3a1)@ @limit@ supports up to 1,000 items; if unspecified it defaults to the REST API default (100)
*** @(RSP3a2)@ @clientId@ filters members by the provided @clientId@
*** @(RSP3a3)@ @connectionId@ filters members by the provided @connectionId@
* @(RSP4)@ @RestPresence#history@ function:
** @(RSP4a)@ Returns a @PaginatedResult@ page containing the first page of messages in the @PaginatedResult#items@ attribute returned from the presence request
** @(RSP4b)@ Supports the following params:
*** @(RSP4b1)@ @start@ and @end@ are timestamp fields represented as milliseconds since epoch, or where appropriate to the language, Date/Time objects. @start@ must be equal to or less than @end@ and is unaffected by the request direction
*** @(RSP4b2)@ @direction@ backwards or forwards; if unspecified defaults to the REST API default (backwards)
*** @(RSP4b3)@ @limit@ supports up to 1,000 items; if unspecified defaults to the REST API default (100)
* @(RSP5)@ Presence Messages retrieved are decoded in the same way that messages are decoded
h3(#rest-encryption). Encryption
* @(RSE1)@ @Crypto::getDefaultParams@ function:
** @(RSE1a)@ Returns a complete @CipherParams@ instance, using the default values for any field not supplied
** @(RSE1b)@ Takes a @CipherParamOptions@ instance.
** @(RSE1c)@ The @key@ must be either a binary (e.g. a byte array, depending on the language), or a base64-encoded string. If the key is a string, the function should base64-decode it into a binary. Since the conversion to base64 is not under Ably control, this should be done leniently -- in particular, it should work with base64url (RFC 4648 s.5, which uses @-@ and @_@ instead of @+@ and @/@) as well as base64 (RFC 4648 s.4)
** @(RSE1d)@ Calculates a @keyLength@ from the key (its size in bits).
** @(RSE1e)@ Checks that the provided options are valid and self-consistent as best it can, raises an exception if not. At a minimum, this should include checking the calculated @keyLength@ is a valid key length for the encryption algorithm (for example, 128 or 256 for @AES@)
* @(RSE2)@ @Crypto::generateRandomKey@ function
** @(RSE2a)@ Takes an optional @keyLength@ parameter, which is the length in bits of the key to be generated. If unspecified, this is equal to the default @keyLength@ of the default algorithm: for @AES@, 256 bits.
** @(RSE2b)@ Returns (or calls back with, if the language cryptographic randomness primitives are blocking or async) the key as a binary (e.g. a byte array, depending on the language)
h3(#rest-compatibility). Forwards compatibility
* @(RSF1)@ The library must apply the "robustness principle":https://en.wikipedia.org/wiki/Robustness_principle in its processing of requests and responses with the Ably system. In particular, deserialization of Messages and related types, and associated enums, must be tolerant to unrecognised attributes or enum values. Such unrecognised values must be ignored.
h3(#batch-operations). Batch Operations
* @(BO1)@ The batch operations functions must use the REST endpoints in Batch Mode, sending a single request containing all specified data
* @(BO2)@ Batch operations must be able to be performed for the following:
** @(BO2a)@ @BatchOperations::publish@ publishes messages against one or more channels with one or more messages
*** @(B02a1)@ Functions should be provided to pass either an array or a single @BatchSpec@ object. In languages where function overloading is not possible, an array is preferred.
** @(BO2b)@ @BatchOperations::getPresence@ retrieves the presence data for one or more channels
* @(BO3)@ When a batch operation only contains one batch, the underlying request is functionally identical to its non-batch equivalent, but the returned result should be a @BatchResponse@ object.
h2(#realtime). Realtime client library features
The Ably Realtime client libraries establish and maintain a persistent connection to Ably and provide methods to publish and subscribe to messages over a low latency realtime connection.
The Realtime library is a super-set of the REST library and as such all Realtime libraries provide the functionality available in the REST library in addition to Realtime-specific features.
The threading and/or asynchronous model for each realtime library will vary by language and it is therefore up to the developer to decide on the best approach for each given client library. For example, Node.js and Ruby (EventMachine) use a similar callback single threaded evented approach that ensures all public methods are non-blocking. Java and .NET use a threaded model whereby the @Connection@ runs in its own thread. Go makes extensive use of goroutines and channels.
h3(#realtimeclient). RealtimeClient
* @(RTC12)@ Has the same constructors as @RestClient@, as defined in "RSC1":#RSC1
* @(RTC1)@ Supports all the same @ClientOptions@ as the @RestClient@ in addition to:
** @(RTC1a)@ @echoMessages@ boolean is true by default. If false, it prevents messages originating from this connection being echoed back on the same connection
** @(RTC1b)@ @autoConnect@ boolean is true by default. If true, as soon as the client library is instantiated, it will connect to Ably. If false, the client library will wait for an explicit @Connection#connect@ to be called before connecting
** @(RTC1c)@ @recover@ string, when set, will attempt to recover the connection state of a previous connection
** @(RTC1d)@ @realtimeHost@ string, when set, will modify the realtime endpoint host used by this client library
** @(RTC1e)@ @environment@ string, when set to a value other than "production", use @[environment]-rest.ably.io@ as the REST endpoint and @[environment]-realtime.ably.io@ as the realtime endpoint. For example, a @RealtimeClient@ with an @environment@ of "sandbox" would use "sandbox-rest.ably.io" as the REST endpoint and @sandbox-realtime.ably.io@ as the realtime endpoint. See "TO3k3":#TO3k3 for constraints.
** @(RTC1f)@ @transportParams@ map or equivalent, additional parameters to be sent in the querystring when initiating a realtime connection. Keys are @Strings@, values are @Stringifiable@ (a value that can be coerced to a string in order to be sent as a querystring parameter. Supported values should be at least strings, numbers, and booleans, with booleans stringified as @true@ and @false@. If this is unidiomatic to the language, the implementer may consider this as equivalent to @String@).
*** @(RTC1f1)@ If a key in @transportParams@ is one the library sends by default (for example, @v@ or @heartbeats@), the value in @transportParams@ takes precedence.
* @(RTC2)@ @RealtimeClient#connection@ attribute provides access to the underlying @Connection@ object
* @(RTC15)@ @RealtimeClient#connect@ function:
** @(RTC15a)@ Calls @#connect@ on the underlying @Connection@ object
* @(RTC16)@ @RealtimeClient#close@ function:
** @(RTC16a)@ Calls @#close@ on the underlying @Connection@ object
* @(RTC3)@ @RealtimeClient#channels@ attribute provides access to the underlying @Channels@ object
* @(RTC4)@ @RealtimeClient#auth@ attribute provides access to the @Auth@ object that was instantiated with the @ClientOptions@ provided in the @RealtimeClient@ constructor
** @(RTC4a)@ Unlike the stateless REST client library, the @Auth#clientId@ is populated when the connection is established. The @CONNECTED@ @ProtocolMessage@ contains the confirmed @clientId@ for this connected client i.e. the client is considered identified. See "@RSA7b@":#RSA7b and "@RSA12@":#RSA12 for further info
* @(RTC5)@ @RealtimeClient#stats@ function:
** @(RTC5a)@ Proxy to @RestClient#stats@ presented with an async or threaded interface as appropriate
** @(RTC5b)@ Accepts all the same params as @RestClient#stats@ and provides all the same functionality
* @(RTC6)@ @RealtimeClient#time@ function:
** @(RTC6a)@ Proxy to @RestClient#time@ presented with an async or threaded interface as appropriate
* @(RTC13)@ @RealtimeClient#push@ attribute provides access to the @Push@ object that was instantiated with the @ClientOptions@ provided in the @RealtimeClient@ constructor
* @(RTC14)@ @RealtimeClient#batch@ attribute provides access to the @BatchOperations@ object that was instantiated with the @ClientOptions@ provided in the @RealtimeClient@ constructor
* @(RTC7)@ The client library must use the configured timeouts specified in the @ClientOptions@, falling back to the "client library defaults":#defaults and defaults described in @ClientOptions@ below
* @(RTC8)@ For a realtime client, @Auth#authorize@ instructs the library to obtain a token using the provided @tokenParams@ and @authOptions@ and alter the current connection to use that token; or if not currently connected, to connect with the token.
** @(RTC8a)@ If the connection is in the @CONNECTED@ state and @auth#authorize@ is called or Ably requests a re-authentication (see "RTN22":#RTN22), the client must obtain a new token, then send an @AUTH@ @ProtocolMessage@ to Ably with an @auth@ attribute containing an @AuthDetails@ object with the token string
*** @(RTC8a1)@ If the authentication token change is successful, then Ably will send a new @CONNECTED@ @ProtocolMessage@. The @connectionDetails@ provided in the @CONNECTED@ @ProtocolMessage@ must override any existing defaults, see "RTN21":#RTN21. The @Connection@ should emit an @UPDATE@ event per @RTN24@. A test should exist that performs a change of capabilities without any loss of continuity or connectivity during the process. Another test should exist where the capabilities are downgraded resulting in Ably sending an @ERROR@ @ProtocolMessage@ with a @channel@ property, causing the channel to enter the @FAILED@ state. That test must assert that the channel becomes failed soon after the token update and the reason is included in the channel state change event
*** @(RTC8a2)@ If the authentication token change fails, then Ably will send an @ERROR@ @ProtocolMessage@ triggering the connection to transition to the @FAILED@ state. A test should exist for a token change that fails (such as sending a new token with an incompatible @clientId@)
*** @(RTC8a3)@ The @authorize@ call should be indicated as completed with the new token or error only once realtime has responded to the @AUTH@ with either a @CONNECTED@ or @ERROR@ respectively.
*** @(RTC8a4)@ Tests must exist that verify the inband reauthorization mechanism described in @RTC8a@ succeeds in the cases of an Ably token string and a JWT token string.
** @(RTC8b)@ If the connection is in the @CONNECTING@ state when @auth#authorize@ is called, all current connection attempts should be halted, and after obtaining a new token the library should immediately initiate a connection attempt using the new token
*** @(RTC8b1)@ The @authorize@ call should be indicated as completed with the new token once the connection has moved to the @CONNECTED@ state, or with an error if the connection instead moves to the @FAILED@, @SUSPENDED@, or @CLOSED@ states
** @(RTC8c)@ If the connection is in the @DISCONNECTED@, @SUSPENDED@, @FAILED@, or @CLOSED@ state when @auth#authorize@ is called, after obtaining a token the library should move to the @CONNECTING@ state and initiate a connection attempt using the new token, and @RTC8b1@ applies.
* @(RTC9)@ @RealtimeClient#request@ is a wrapper around @RestClient#request@ (see "RSC19":#RSC19) delivered in an idiomatic way for the realtime library, e.g. in the case of Ruby, with an evented async callback interface
* @(RTC17)@ @RealtimeClient#clientId@ attribute:
** @(RTC17a)@ Returns the current value of the @#clientId@ attribute of the @RealtimeClient@ object’s @#auth@ attribute
* @(RTC10)@ The client library should never register any listeners for internal use with the public @EventEmitter@ interfaces (such as @Connection#on@) or message/event subscription interfaces (such as @RealtimeChannel#subscribe@) in such a way that a user of the library calling @Connection#off()@ or @RealtimeChannel#unsubscribe()@ to remove all listeners would result in the library not working as expected
* @(RTC11)@ Unexpected internal exceptions, as defined in "@RSC20@":#RSC20, must be handled as gracefully as possible and reported to Ably's error reporting service when enabled. The aim when handling unexpected exceptions should be to ensure that no invalid or inconsistent state can potentially be left after handling the exception; depending on circumstances the remedial action could include failing the transport, failing the connection, rejecting a message, reinitialising the library completely, etc.
h3(#realtime-connection). Connection
* @(RTN1)@ @Connection@ connects to the Ably service using a "websocket":https://ably.com/topic/websockets connection. The "ably-js library":https://github.com/ably/ably-js supports additional transports such as Comet and XHR streaming; however non-browser client libraries typically use only a websocket transport
* @(RTN2)@ The default host used for realtime "websocket":https://ably.com/topic/websockets connections is @realtime.ably.io@, and the following query string params should be used when opening a new connection:
** @(RTN2a)@ @format@ should be @msgpack@ (default) or @json@
** @(RTN2b)@ @echo@ should be @true@ by default; @false@ will prevent messages published by the client being echoed back
** @(RTN2d)@ @clientId@ contains the provided @clientId@ option of @ClientOptions@, unless @clientId@ is @null@
** @(RTN2e)@ Depending on the authentication scheme, either @accessToken@ contains the token string, or @key@ contains the API key
** @(RTN2f)@ API version param @v@ should be the API version per "G4":#G4
** @(RTN2g)@ The library and version (in the form described in "RSC7b":#RSC7b) should be included as the value of a @lib@ querystring param. For example, the 1.0.0 version of the JavaScript library would use the param @lib=js-1.0.0@
* @(RTN3)@ If connection option @autoConnect@ is true, a connection is initiated immediately; otherwise a connection is only initiated following an explicit call to @connect()@
* @(RTN4)@ The @Connection@ implements @EventEmitter@ and emits @ConnectionEvent@ events, where a @ConnectionEvent@ is either a @ConnectionState@ or @UPDATE@, and a @ConnectionState@ is either @INITIALIZED@, @CONNECTING@, @CONNECTED@, @DISCONNECTED@, @SUSPENDED@, @CLOSING@, @CLOSED@, or @FAILED@
** @(RTN4a)@ It emits a @ConnectionState@ @ConnectionEvent@ for every connection state change
** @(RTN4h)@ It emits an @UPDATE@ @ConnectionEvent@ for changes to connection conditions for which the @ConnectionState@ (e.g. @CONNECTED@) does not change. (The library must never emit a @ConnectionState@ @ConnectionEvent@ for a state equal to the previous state)
** @(RTN4b)@ A new connection will emit the following events in order when connecting: @CONNECTING@, then @CONNECTED@
** @(RTN4c)@ A connection will emit the following events when closing the connection: @CLOSING@, then @CLOSED@
** @(RTN4d)@ @Connection#state@ attribute is the current state of the connection
** @(RTN4e)@ A @ConnectionStateChange@ object is emitted as the first argument for every @ConnectionEvent@ (including both @RTN4a@ connection state changes and @RTL4h@ @UPDATE@ events)
** @(RTN4f)@ The @ConnectionStateChange@ object may contain a @reason@ consisting of an @ErrorInfo@ object with details of the error that has occurred for the @Connection@. Any state change triggered by a @ProtocolMessage@ that contains an @error@ member should populate the @reason@ with that error in the corresponding state change event
** @(RTN4i)@ Optionally, for backwards compatibility with 0.8 libraries, the @Connection@ @EventEmitter@ can provide an overloaded method that supports @on(ConnectionState)@, but must issue a deprecation warning
* @(RTN5)@ A test should exist that instantiates many (50+) clients simultaneously and performs a few basic operations such as attaching to a channel, publishing a message, and expecting all of those messages to arrive on all clients to ensure that there are no concurrency issues with the client library
* @(RTN6)@ A @Connection@ is successful and considered @CONNECTED@ once the "websocket":https://ably.com/topic/websockets connection is open and the initial @CONNECTED@ @ProtocolMessage@ has been received
* @(RTN21)@ If the @CONNECTED@ @ProtocolMessage@ contains a @connectionDetails@ property, the attributes within @ConnectionDetails@ will be used as the defaults for this client library, overriding any configured options at the time the @CONNECTED@ @ProtocolMessage@ is received
* @(RTN7)@ @ACK@ and @NACK@:
** @(RTN7a)@ All @ProtocolMessage@ @Presence@ and @Message@ objects sent to Ably expect either an @ACK@ or @NACK@ from Ably to confirm successful receipt and acceptance or failure respectively. For clarity, it is unnecessary to fail the publish operation of a message using a timer. Instead the client library can rely on: the realtime system will send an @ACK@ or @NACK@ when connected; the client library will fail all awaiting messages once @SUSPENDED@ (see "RTN7c":#RTN7c); upon reconnecting, the client will resend all message awaiting a response, and the realtime system in turn will respond with an @ACK@ or @NACK@ (see "RTN19a":#RTN19a)
** @(RTN7b)@ Every @ProtocolMessage@ that expects an @ACK@ or @NACK@ sent must contain a unique serially incrementing @msgSerial@ integer value starting at zero. The @msgSerial@ along with the @count@ for incoming @ACK@ and @NACK@ @ProtocolMessages@ indicates which messages succeeded or failed to be delivered
** @(RTN7c)@ If a connection enters the @SUSPENDED@, @CLOSED@ or @FAILED@ state, or if the connection state is lost, and an @ACK@ or @NACK@ has not yet been received for a message, the client should consider the delivery of those messages as failed
* @(RTN22)@ Ably can request that a connected client re-authenticates by sending the client an @AUTH@ @ProtocolMessage@. The client must then immediately start a new authentication process as described in "RTC8":#RTC8
** @(RTN22a)@ Ably reserves the right to forcibly disconnect a client that does not re-authenticate within an acceptable period of time, or at any time the token is deemed no longer valid. A client is forcibly disconnected following a @DISCONNECTED@ message containing an error code in the range @40140 <= code < 40150@. This will in effect force the client to re-authenticate and resume the connection immediately, see "RTN15h":#RTN15h
* @(RTN8)@ @Connection#id@ attribute:
** @(RTN8a)@ Is unset until connected
** @(RTN8b)@ Is a unique string provided by Ably. You should have a test to ensure multiple connected clients have unique connection IDs
* @(RTN9)@ @Connection#key@ attribute:
** @(RTN9a)@ Is unset until connected
** @(RTN9b)@ Is a unique private connection key provided by Ably that is used to reconnect and retain connection state following an unexpected disconnection. You should have a test to ensure multiple connected clients have unique connection keys
* @(RTN10)@ @Connection#serial@ attribute:
** @(RTN10a)@ Is unset until connected, and is then set from the @connectionSerial@ attribute of the @CONNECTED@ @ProtocolMessage@
** @(RTN10b)@ Continues to be updated by every @ProtocolMessage@ received from Ably that contains a @connectionSerial@. A test should exist that checks that the serial is updated when a @ProtocolMessage@ is received with the value from that @ProtocolMessage@. It should not otherwise change; in particular, unlike the library-internal @msgSerial@, it should not change as a result of publishing a message or receiving an @ACK@.
* @(RTN11)@ @Connection#connect@ function:
** @(RTN11a)@ Explicitly connects to the Ably service if not already connected
** @(RTN11b)@ If the state is @CLOSING@, the client should make a new connection with a new transport instance and remove all references to the old one. In particular, it should make sure that, when the @CLOSED@ @ProtocolMessage@ arrives for the old connection, it doesn't affect the new one.
** @(RTN11c)@ If the state is @DISCONNECTED@ or @SUSPENDED@, skips the ongoing wait in the retry process described in "RTN14d":#RTN14d and "RTN14e":#RTN14e, so that the next reconnection attempt happens immediately.
** @(RTN11d)@ If the state is @CLOSED@ or @FAILED@, transitions all the channels to @INITIALIZED@ and unsets their @RealtimeChannel.errorReason@, unsets the @Connection.errorReason@, clears all connection state (including in particular @Connection.recoveryKey@), and resets the @msgSerial@ to @0@
* @(RTN12)@ @Connection#close@ function:
** @(RTN12f)@ If the connection state is @CONNECTING@, moves immediately to @CLOSING@. If the connection attempt succeeds, ie. a @CONNECTED@ @ProtocolMessage@ arrives from Ably, then do as specified in "RTN12a":#RTN12a. If it doesn't succeed, move to @CLOSED@.
** @(RTN12a)@ If the connection state is @CONNECTED@, sends a @CLOSE@ @ProtocolMessage@ to the server, transitions the state to @CLOSING@ and waits for a @CLOSED@ @ProtocolMessage@ to be received
** @(RTN12b)@ If the @CLOSED@ @ProtocolMessage@ is not received within the "default realtime request timeout":#defaults, the transport will be disconnected and the connection will automatically transition to the @CLOSED@ state
** @(RTN12c)@ If the transport is abruptly closed following a @CLOSE@ @ProtocolMessage@ being sent, then the connection will automatically transition to the @CLOSED@ state
** @(RTN12d)@ If the connection state is @DISCONNECTED@ or @SUSPENDED@, aborts the retry process described in "RTN14d":#RTN14d and "RTN14e":#RTN14e and transitions the connection immediately to the @CLOSED@ state
* @(RTN13)@ @Connection#ping@ function:
** @(RTN13d)@ If the connection state is @CONNECTING@ or @DISCONNECTED@, do the operation once the connection state is @CONNECTED@
** @(RTN13a)@ Will send a @ProtocolMessage@ with action @HEARTBEAT@ the Ably service when connected and expects a @HEARTBEAT@ message in response. If the client library language supports callbacks, then the callback will be called with the response time or error
** @(RTN13b)@ Will indicate an error if in, or has transitioned to, the @INITIALIZED@, @SUSPENDED@, @CLOSING@, @CLOSED@ or @FAILED@ state
** @(RTN13c)@ Will fail if a @HEARTBEAT@ @ProtocolMessage@ is not received within the "default realtime request timeout":#defaults
** @(RTN13e)@ The @ProtocolMessage@ sent should include an @id@ property, with value a random string. If so, only a @HEARTBEAT@ response which includes an @id@ property with the same value should be considered a response to that ping, in order to disambiguate from normal heartbeats and other pings.
* @(RTN14)@ @Connection@ opening failures:
** @(RTN14a)@ If an API key is invalid, then the connection will transition to the @FAILED@ state and the @Connection#errorReason@ will be set on the @Connection@ object as well as the emitted @ConnectionStateChange@
** @(RTN14b)@ If a connection request fails due to an @ERROR@ @ProtocolMessage@ being received by the client containing a token error (@statusCode@ value of 401 and error @code@ value in the range @40140 <= code < 40150@) and an empty @channel@ attribute, then if the token is renewable, a single attempt to create a new token should be made and a new connection attempt initiated using the newly created token. If the attempt to create a new token fails, or the subsequent connection attempt fails due to another token error, then the connection will transition to the @DISCONNECTED@ state, and the @Connection#errorReason@ should be set. (If no means to renew the token is provided, @RSA4a@ applies)
** @(RTN14g)@ If an @ERROR@ @ProtocolMessage@ with an empty @channel@ attribute is received for any reason other than "RTN14b":#RTN14b, then the connection will transition to the @FAILED@ state and the server will terminate the connection. Additionally the @Connection#errorReason@ must be set with the error from the @ERROR@ @ProtocolMessage@
** @(RTN14c)@ A new connection attempt will fail if not connected within the "default realtime request timeout":#defaults
** @(RTN14d)@ If a connection attempt fails for any recoverable reason (i.e. a network failure, a timeout such as "RTN14c":#RTN14c, or a disconnected response, other than a token failure "RTN14b":#RTN14b), the @Connection#state@ will transition to @DISCONNECTED@, the @Connection#errorReason@ will be updated, a @ConnectionStateChange@ with the @reason@ will be emitted, and new connection attempts will periodically be made until the maximum time in that state threshold is reached. The @retryIn@ attribute of the @ConnectionStateChange@ object will contain the time in milliseconds until the next connection attempt. @retryIn@ should be calculated as described in "@RTB1@":#RTB1. Each time a new connection attempt is made the state will transition to @CONNECTING@ and then to @CONNECTED@ if successful, or @DISCONNECTED@ if unsuccessful and the "default @connectionStateTtl@":#defaults has not been exceeded. Fallback hosts are used for new connection attempts in accordance with "RTN17":#RTN17.
** @(RTN14e)@ Once the connection state has been in the @DISCONNECTED@ state for more than the "default @connectionStateTtl@":#defaults, the state will change to @SUSPENDED@ and be emitted with the @reason@, and the @Connection#errorReason@ will be updated. In this state, a new connection attempt will be made periodically as specified within @suspendedRetryTimeout@ of @ClientOptions@
** @(RTN14f)@ The connection will remain in the @SUSPENDED@ state indefinitely, whilst periodically attempting to reestablish a connection
* @(RTN15)@ @Connection@ failures once @CONNECTED@:
** @(RTN15h)@ If a @DISCONNECTED@ message is received from Ably, then that transport will subsequently be closed by Ably
*** @(RTN15h1)@ If the @DISCONNECTED@ message contains a token error (@statusCode@ value of 401 and error @code@ value in the range @40140 <= code < 40150@) and the library does not have a means to renew the token, the connection will transition to the @FAILED@ state and the @Connection#errorReason@ will be set
*** @(RTN15h2)@ If the @DISCONNECTED@ message contains a token error (@statusCode@ value of 401 and error @code@ value in the range @40140 <= code < 40150@) and the library has the means to renew the token, a single attempt to create a new token should be made and a new connection attempt initiated using the new token. If the token creation fails or the next connection attempt fails due to a token error, the connection will transition to the @DISCONNECTED@ state and the @Connection#errorReason@ will be set.
** @(RTN15i)@ If an @ERROR@ @ProtocolMessage@ is received, this indicates a fatal error in the connection. The server will close the transport immediately after. The client should transition to the @FAILED@ state triggering all attached channels to transition to the @FAILED@ state as well. Additionally the @Connection#errorReason@ should be set with the error received from Ably
** @(RTN15a)@ If a @Connection@ transport is disconnected unexpectedly or because a token has expired, then the @Connection@ manager will immediately attempt to reconnect and restore the connection state. Connection state recovery is provided by the Ably service and ensures that whilst the client is disconnected, all events are queued and channel state is retained on the Ably servers. When a new connection is made with the correct connection recovery key, the client is able to catch up by receiving the queued @ProtocolMessages@ from Ably.
** @(RTN15g)@ Connection state is only maintained server-side for a brief period, given by the @connectionStateTtl@ in the @connectionDetails@, see "CD2f":#CD2f. If a client has been disconnected for longer than the @connectionStateTtl@, it should not attempt to resume. Instead, it should clear the local connection state, and any connection attempts should be made as for a fresh connection
*** @(RTN15g1)@ This check should be made before each connection attempt. It is generally not sufficient to merely clear the connection state when moving to @SUSPENDED@ state (though that may be done too), since the device may have been sleeping / suspended, in which case it may have been many hours since it was last actually connected, even though, having been in the @CONNECTED@ state when it was put to sleep, it has only moved out of that state very recently (after waking up and noticing it's no longer connected)
*** @(RTN15g2)@ Another consequence of that is that the measure of whether the client been disconnected for too long (for the purpose of this check) cannot just be whether the client left the @CONNECTED@ state more than @connectionStateTtl@ ago. Instead, it should be whether the difference between the current time and the last activity time is greater than the sum of the @connectionStateTtl@ and the @maxIdleInterval@, where the last activity time is the time of the last known actual sign of activity from Ably per "RTN23a":#RTN23a
*** @(RTN15g3)@ When a connection attempt succeeds after the connection state has been cleared in this way, channels that were previously @ATTACHED@, @ATTACHING@, or @SUSPENDED@ must be automatically reattached, just as if the connection was a resume attempt which failed per "RTN15c3":#RTN15c3
** @(RTN15b)@ In order for a connection to be resumed and connection state to be recovered, the client must have received a @CONNECTED@ ProtocolMessage which will include a private connection key. To resume that connection, the library reconnects to the "websocket":https://ably.com/topic/websockets endpoint with two additional querystring params:
*** @(RTN15b1)@ @resume@ is the @ProtocolMessage#connectionKey@ from the most recent @CONNECTED@ @ProtocolMessage@ received
*** @(RTN15b2)@ @connectionSerial@ is the most recent @ProtocolMessage#connectionSerial@ (from any message, not just a @CONNECTED@) received from Ably (equivalently, the @Connection#serial@)
** @(RTN15c)@ The system's response to a resume request will be one of the following:
**** @(RTN15c1)@ @CONNECTED@ @ProtocolMessage@ with the same @connectionId@ as the current client, and no @error@. In this case, the server is indicating that the resume succeeded, all channels are still attached, and all backlog messages are available. The client should not change the state of attached channels, and immediately process any messages queued by the connection
**** @(RTN15c2)@ @CONNECTED@ @ProtocolMessage@ with the same @connectionId@ as the current client, and an @error@. In this case, the server is indicating that the resume succeeded but with a non-fatal error, all channels are still attached, and some backlog messages may be unavailable. The @ErrorInfo@ received should be set as the @reason@ in the @CONNECTED@ event, and the @Connection#errorReason@ should be set. The client should not change the state of attached channels, and immediately process any messages queued by the connection. Any channels that are not resumed in full may receive an @ATTACHED@ @ProtocolMessage@ with an @error@, see "RTL12":#RTL12
**** @(RTN15c3)@ @CONNECTED@ @ProtocolMessage@ with a new @connectionId@ (and usually an @ErrorInfo@ in the @error@ field). In this case, a new connection has been established, the resume was unsuccessful, the channels are no longer attached, and the error indicates the cause of the unsuccessful resume. The @error@ if present should be set as the @reason@ in the @CONNECTED@ event, and as the @Connection#errorReason@. The client library should initiate an attach for channels that are in the @SUSPENDED@ state. For all channels in the @ATTACHING@ or @ATTACHED@ state, the client library should initiate a new attach (i.e. a new @ATTACH@ @ProtocolMessage@ sent for each channel). Finally, the internal @msgSerial@ counter is reset so that the first message published to Ably will contain a @msgSerial@ value of @0@
**** @(RTN15c5)@ @ERROR@ @ProtocolMessage@ indicating a failure to authenticate as a result of a token error (see "RTN15h":#RTN15h). The transport will be closed by the server. The spec described in "RTN15h":#RTN15h must be followed for a connection being resumed with a token error
**** @(RTN15c4)@ Any other @ERROR@ @ProtocolMessage@ indicating a fatal error in the connection. The server will close the transport immediately after. The client should transition to the @FAILED@ state triggering all attached channels to transition to the @FAILED@ state as well. Additionally the @Connection#errorReason@ will be set should be set with the error received from Ably
** @(RTN15f)@ @ACK@ and @NACK@ responses for published messages can only ever be received on the transport connection on which those messages were sent. Therefore, once a transport drops, the client library must re-attempt by re-sending the messages on a new transport if the resume was successful (i.e. the @CONNECTED@ response includes the expected @connectionId@) as mandated by "RTN19":#RTN19.
** @(RTN15d)@ Client libraries should have test coverage to ensure connection state recovery is working as expected by forcibly disconnecting a client and checking that messages published on channels are delivered once the connection is resumed
** @(RTN15e)@ When a connection is resumed, the @Connection#key@ may change and will be provided in the first @CONNECTED@ @ProtocolMessage#connectionDetails@ when the connection is established. The client library must update the @Connection#key@ value with the new @connectionKey@ value every time
* @(RTN20)@ When the client library can subscribe to the Operating System events for network/internet connectivity changes:
** @(RTN20a)@ When @CONNECTED@, @CONNECTING@ or @DISCONNECTING@, if the operating system indicates that the underlying internet connection is no longer available, then the client library should immediately transition the state to @DISCONNECTED@ with emit a state change with an appropriate @reason@. This state change will automatically trigger the client library to attempt to reconnect, see @RTN15@ above
** @(RTN20b)@ When @DISCONNECTED@ or @SUSPENDED@, if the operating system indicates that the underlying internet connection is now available, the client library should immediately attempt to connect
* @(RTN16)@ @Connection@ recovery:
** @(RTN16a)@ Connection recovery follows the resume spec "RTN15c":#RTN15c in respect to the expected response from the server. However, connection recovery is different in that the library has no state at the time of connection and recovers the connection based as a result of @recover@ key being explicitly provided to the Realtime library when instantiated. Once a connection is recovered, all channels must be explicitly attached by the developer
** @(RTN16b)@ @Connection#recoveryKey@ is an attribute composed of the @connectionKey@, and the latest @connectionSerial@ received on the connection, and the current @msgSerial@
** @(RTN16c)@ @Connection#recoveryKey@ becomes @Null@ when a connection is explicitly @CLOSED@ or @CLOSED@ by the server, as connection state is not retained for connections closed intentionally. The @Connection#key@ and @Connection#id@ is set to @Null@
** @(RTN16d)@ When a connection is successfully recovered, the @Connection#id@ will be identical to the @id@ of the connection that was recovered, and @Connection#key@ will always be updated to the @ConnectionDetails#connectionKey@ provided in the first @CONNECTED@ @ProtocolMessage@
** @(RTN16e)@ If the @recover@ option is missing or no longer valid when connecting to Ably, the client will connect anyway, but emit a @ConnectionStateChange@ with a @reason@, and will additionally set the @Connection#errorReason@ with an @ErrorInfo@ object describing the failure
** @(RTN16f)@ The @msgSerial@ component of the @recoveryKey@, unlike the other two components, is not sent to Ably, but rather is used to set the library internal @msgSerial@. (If the recover fails, the counter should be reset to 0 per "RTN15c3":#RTN15c3 )
* @(RTN17)@ Host Fallback
** @(RTN17b)@ The fallback behavior described by this section, "RTN17":#RTN17, only applies when either:
*** @(RTN17b1)@ @ClientOptions#realtimeHost@ has not been set to an explicit value (see "RTC1d":#RTC1d) and @ClientOptions#port@ is not set and @ClientOptions#tlsPort@ is not set
*** @(RTN17b2)@ An array of @ClientOptions#fallbackHosts@ is provided
*** @(RTN17b3)@ The deprecated @ClientOptions#fallbackHostsUseDefault@ option is set to @true@
** @(RTN17a)@ By default, every connection attempt is first attempted to the default primary host @realtime.ably.io@ (unless overriden in @ClientOptions#environment@ or @ClientOptions#realtimeHost@), which, through DNS, is automatically routed to the client's closest datacenter. The client library must always prefer the default endpoint (closest datacenter), even if a previous connection attempt to that endpoint has failed. (That is, @RSC15f@ does not apply)
** @(RTN17c)@ In the case of an error necessitating use of an alternative host (see "RTN17d":#RTN17d), the @Connection@ manager should first check if an internet connection is available by issuing a @GET@ request to @https://internet-up.ably-realtime.com/is-the-internet-up.txt@. If the request succeeds and the text "yes" is included in the body, then the client library can assume it has a viable internet connection and should then immediately retry the connection against fallback hosts in random order to find an alternative healthy datacenter. Fallback hosts are chosen as per "RSC15g":#RSC15g, and must use a matching Host header as per "RSC15j":#RSC15j
** @(RTN17d)@ Errors that necessitate use of an alternative host include: host unresolvable or unreachable, connection timeout, or a @DISCONNECTED@ response with an @error.statusCode@ in the range @500 <= code <= 504@ or HTTP response status code in the range @500 <= code <= 504@. Attempting to reconnect to a fallback host for other failure conditions will not fix the problem and will simply increase the load on other data-centers unnecessarily
** @(RTN17e)@ If the realtime client is connected to a fallback host endpoint, then for the duration that the transport is connected to that host, all HTTP requests, such as history or token requests, should be first attempted to the same datacenter the realtime connection is established with i.e. the same fallback host must be used as the default HTTP request host. If however the HTTP request against that fallback host fails, then the normal fallback host behavior should be followed attempting the request against another fallback host as described in "RSC15":#RSC15
* @(RTN19)@ Transport state side effects - when a transport is disconnected for any reason:
** @(RTN19a)@ Any @ProtocolMessage@ that is awaiting an @ACK@/@NACK@ on the old transport will not receive the @ACK@/@NACK@ on the new transport. The client library must therefore resend any @ProtocolMessage@ that is awaiting a @ACK@/@NACK@ to Ably in order to receive the expected @ACK@/@NACK@ for that message. The Ably service is responsible for keeping track of messages, ignoring duplicates and responding with suitable @ACK@/@NACK@ messages
** @(RTN19b)@ If there are any pending channels i.e. in the @ATTACHING@ or @DETACHING@ state, the respective @ATTACH@ or @DETACH@ message should be resent to Ably
* @(RTN23)@ Heartbeats
** @(RTN23a)@ If a transport does not receive any indication of activity on a transport for a period greater than the sum of the @maxIdleInterval@ (which will be sent in the @connectionDetails@ of the most recent @CONNECTED@ message received on that transport) and the @realtimeRequestTimeout@, that transport should be disconnected. Any message (or non-message indicator, see @RTN23b@) received counts as an indication of activity and should reset the timer, not merely heartbeat messages. However, it must be received (that is, sent from the server to the client); client-sent data does not count.
** @(RTN23b)@ When initiating a connection, the client may send a @heartbeats@ param in the querystring, with value @true@ or @false@. If the value is true, the server will use Ably protocol messages (for example, a message with a @HEARTBEAT@ action) to satisfy the @maxIdleInterval@ requirement. If it is false or unspecified, the server is permitted to use any transport-level mechanism (for example, "websocket":https://ably.com/topic/websockets ping frames) to satisfy this. So for example, for "websocket transports":https://ably.com/topic/websockets, if the client is able to observe websocket pings, then it should send @heartbeats=false@. If not, it should send @heartbeats=true@.
* @(RTN24)@ A connected client may receive a @CONNECTED@ @ProtocolMessage@ from Ably at any point (though is typically triggered by a reauth, see @RTC8a@). The @connectionDetails@ in the @ProtocolMessage@ must override any stored details, see @RTN21@. The @Connection@ should emit an @UPDATE@ event with a @ConnectionStateChange@ object, which should have both @previous@ and @current@ attributes set to @CONNECTED@, and the @reason@ attribute set to to the @error@ member of the @CONNECTED@ @ProtocolMessage@ (if any). (Note that @UPDATE@ should be the only event emitted: in particular, the library must not emit an @CONNECTED@ event if the client was already connected, see @RTN4h@).
* @(RTN25)@ @Connection#errorReason@ attribute is an optional @ErrorInfo@ object which is set by the library when an error occurs on the connection, as described by "RSA4c1":#RSA4c1, "RSA4d":#RSA4d, "RTN11d":#RTN11d, "RTN14a":#RTN14a, "RTN14b":#RTN14b, "RTN14e":#RTN14e, "RTN14g":#RTN14g, "RTN15c2":#RTN15c2, "RTN15c3":#RTN15c3, "RTN15c4":#RTN15c4, "RTN15d":#RTN15d, "RTN15h":#RTN15h, "RTN15i":#RTN15i, "RTN16e":#RTN16e.
h3(#realtime-channels). Channels
* @(RTS1)@ @Channels@ is a collection of @RealtimeChannel@ objects accessible through @RealtimeClient#channels@
* @(RTS2)@ Methods should exist to check if a channel exists or iterate through the existing channels
* @(RTS3)@ @Channels#get@ function:
** @(RTS3a)@ Creates a new @RealtimeChannel@ object for the specified channel if none exists, or returns the existing channel. @ChannelOptions@ can be provided in an optional second argument
** @(RTS3b)@ If options are provided, the options are set on the @RealtimeChannel@ when creating a new @RealtimeChannel@
** @(RTS3c)@ Accessing an existing @RealtimeChannel@ with options in the form @Channels#get(channel, options)@ will update the options on the channel and then return the existing @RealtimeChannel@ object. (Note that this is soft-deprecated and may be removed in a future release, so should not be implemented in new client libraries. The supported way to update a set of @ChannelOptions@ is @RealtimeChannel#setOptions@)
*** @(RTS3c1)@ If a new set of @ChannelOptions@ is supplied to @Channels#get@ that would trigger a reattachment of the channel if supplied to @RealtimeChannel#setOptions@ per "@RTL16a@":#RTL16a, it must raise an error, informing the user that they must use @RealtimeChannel#setOptions@ instead
* @(RTS4)@ @Channels#release@ function:
** @(RTS4a)@ Detaches the channel and then releases the channel resource i.e. it's deleted and can then be garbage collected
h3(#realtime-channel). RealtimeChannel
* @(RTL23)@ @RealtimeChannel#name@ attribute is a string containing the channel’s name
* @(RTL1)@ As soon as a @RealtimeChannel@ becomes attached, all incoming messages and presence messages (where 'incoming' is defined as 'received from Ably over the realtime transport') are processed and emitted where applicable. @PRESENCE@ and @SYNC@ messages are passed to the @RealtimePresence@ object ensuring it maintains a map of current members on a channel in realtime
* @(RTL2)@ The @RealtimeChannel@ implements @EventEmitter@ and emits @ChannelEvent@ events, where a @ChannelEvent@ is either a @ChannelState@ or @UPDATE@, and a @ChannelState@ is either @INITIALIZED@, @ATTACHING@, @ATTACHED@, @DETACHING@, @DETACHED@, @SUSPENDED@ and @FAILED@
** @(RTL2a)@ It emits a @ChannelState@ @ChannelEvent@ for every channel state change
** @(RTL2g)@ It emits an @UPDATE@ @ChannelEvent@ for changes to channel conditions for which the @ChannelState@ (e.g. @ATTACHED@) does not change, unless explicitly prevented by a more specific condition (see "RTL12":#RTL12). (The library must never emit a @ChannelState@ @ChannelEvent@ for a state equal to the previous state)
** @(RTL2b)@ @RealtimeChannel#state@ attribute is the current state of the channel, of type @ChannelState@
** @(RTL2d)@ A @ChannelStateChange@ object is emitted as the first argument for every @ChannelEvent@ (including both @RTL2a@ state changes and @RTL2g@ @UPDATE@ events). It may optionally contain a @reason@ consisting of an @ErrorInfo@ object; any state change triggered by a @ProtocolMessage@ that contains an @error@ member should populate the @reason@ with that error in the corresponding state change event
** @(RTL2f)@ When a channel @ATTACHED@ @ProtocolMessage@ is received, the @ProtocolMessage@ may contain a @RESUMED@ bit flag indicating that the channel has been resumed. The corresponding @ChannelStateChange@ (either @ATTACHED@ per @RTL2a@, or @UPDATE@ per @RTL12@) will contain a @resumed@ boolean attribute with value @true@ if the bit flag @RESUMED@ was included. When @resumed@ is @true@, this indicates that the channel attach resumed the channel state from an existing connection and there has been no loss of message continuity. In all other cases, @resumed@ is false. A test should exist to ensure that @resumed@ is always false when a channel first becomes @ATTACHED@, it is @true@ when the channel is @ATTACHED@ following a successful "connection recovery":#RTN16, and is @false@ when the channel is @ATTACHED@ following a failed "connection recovery":#RTN16
** @(RTL2h)@ Optionally, for backwards compatibility with 0.8 libraries, the @RealtimeChannel@ @EventEmitter@ can provide an overloaded method that supports @on(ChannelState)@, but must issue a deprecation warning
* @(RTL3)@ Connection state change side effects:
** @(RTL3e)@ If the connection state enters the @DISCONNECTED@ state, it will have no effect on the channel states.
** @(RTL3a)@ If the connection state enters the @FAILED@ state, then an @ATTACHING@ or @ATTACHED@ channel state will transition to @FAILED@ and set the @RealtimeChannel#errorReason@
** @(RTL3b)@ If the connection state enters the @CLOSED@ state, then an @ATTACHING@ or @ATTACHED@ channel state will transition to @DETACHED@
** @(RTL3c)@ If the connection state enters the @SUSPENDED@ state, then an @ATTACHING@ or @ATTACHED@ channel state will transition to @SUSPENDED@
** @(RTL3d)@ If the connection state enters the @CONNECTED@ state, then a @SUSPENDED@ channel will initiate an attach operation and transition to @ATTACHING@. If the attach operation times out, the channel should return to the @SUSPENDED@ state (see "RTL4f":#RTL4f)
* @(RTL11)@ If a channel enters the @DETACHED@, @SUSPENDED@ or @FAILED@ state, then all presence actions that are still queued for send on that channel per "RTP16b":#RTP16b should be deleted from the queue, and any callback passed to the corresponding presence method invocation should be called with an @ErrorInfo@ indicating the failure
** @(RTL11a)@ For clarity, any messages awaiting an @ACK@ or @NACK@ are unaffected by channel state changes i.e. a channel that becomes detached following an explicit request to detach may still receive an @ACK@ or @NACK@ for messages published on that channel later
* @(RTL4)@ @RealtimeChannel#attach@ function:
** @(RTL4a)@ If already @ATTACHED@ nothing is done
** @(RTL4h)@ If the channel is in a pending state @DETACHING@ or @ATTACHING@, do the attach operation after the completion of the pending request
** @(RTL4g)@ If the channel is in the @FAILED@ state, the @attach@ request sets its @errorReason@ to @null@, and proceeds with a channel attach described in "RTL4b":#RTL4b, "RTL4i":#RTL4i and "RTL4c":#RTL4c
** @(RTL4b)@ If the connection state is @INITIALIZED@, @CLOSED@, @CLOSING@, @SUSPENDED@ or @FAILED@, the @attach@ request results in an error
*** @(RTL4b1)@ Note that an attach attempt immediately after the library is instantiated, assuming @autoConnect@ (@TO3e@)is not set to @false@, should not raise an error (that is, should fall under @RTL4i@, not @RTL4b@), since the library should be in a @CONNECTING@ state at that point
** @(RTL4i)@ If the connection state is @CONNECTING@ or @DISCONNECTED@, do the operation once the connection state is @CONNECTED@
** @(RTL4c)@ Otherwise an @ATTACH@ ProtocolMessage is sent to the server, the state transitions to @ATTACHING@ and the channel becomes @ATTACHED@ when the confirmation @ATTACHED@ ProtocolMessage is received
** @(RTL4f)@ Once an @ATTACH@ @ProtocolMessage@ is sent, if an @ATTACHED@ @ProtocolMessage@ is not received within the "default realtime request timeout":#defaults, the attach request should be treated as though it has failed and the channel should transition to the @SUSPENDED@ state. The channel will then be subsequently automatically re-attached as described in "RTL13":#RTL13
** @(RTL4d)@ A callback (or other language-idiomatic equivalent) can be provided that is called when the channel next moves to one of @ATTACHED@, @DETACHED@, @SUSPENDED@, or @FAILED@ states. In the case of @ATTACHED@ the callback is called with no argument. In all other cases it is called with an @ErrorInfo@ corresponding to the @ChannelStateChange.reason@ of the state change (or a fallback if there is no @reason@) to indicate that the attach has failed. (Note: when combined with RTL4f, this means that if the connection is @CONNECTED@, the callback is guaranteed to be called within @realtimeRequestTimeout@ of the @attach()@ call)
** @(RTL4e)@ If the user does not have sufficient permissions to attach to the channel, the channel will transition to @FAILED@ and set the @RealtimeChannel#errorReason@
** @(RTL4j)@ If the attach is not a clean attach (defined in @RTL4j1@), for example an automatic reattach triggered by "@RTN15c3@":#RTN15c3 or "@RTL13a@":#RTL13a (non-exhaustive), the library should set the "@ATTACH_RESUME@":#TR3f flag in the @ATTACH@ message
*** @(RTL4j1)@ A 'clean attach' is an attach attempt where the channel has either not previously been attached or has been explicitly detached since the last time it was attached. Note that this is not purely a function of the immediate previous channel state. An example implementation would be to set the flag from an @attachResume@ private boolean variable on the channel, that starts out set to @false@, is set to @true@ when the channel moves to the @ATTACHED@ state, and set to @false@ when the channel moves to the @DETACHING@ or @FAILED@ states.
*** @(RTL4j2)@ The client library can test that the flag is being correctly encoded (and that @RTL4k@ channel params are correctly included) by publishing a message on a channel, then having another two clients attach to that channel both specifying a @rewind@ channel param of @"1"@, one of which has the @ATTACH_RESUME@ flag forcibly set, other doesn't. The client without the flag set should receive the previously-published message once the attach succeeds; the one with that flag set should not
** @(RTL4k)@ If the user has specified a non-empty @params@ object in the @ChannelOptions@ ("@TB2c@":#TB2c), it must be included in a @params@ field of the @ATTACH@ @ProtocolMessage@
*** @(RTL4k1)@ If any channel parameters are requested (which may be through the @params@ field of the @ATTACH@ message or some other way opaque to the client library), the @ATTACHED@ (and any subsequent @ATTACHED@ s) will include a @params@ property (also a @Dict<String, String>@) containing the subset of those params that the server has recognised and validated. This should be exposed as a read-only @params@ field of the @RealtimeChannel@ (or a @getParams()@ method where that is more idiomatic). An @ATTACHED@ message with no @params@ property must be treated as equivalent to a @params@ of @{}@ (that is, @RealtimeChannel.params@ should be set to the empty dict)
** @(RTL4l)@ If the user has specified a @modes@ array in the @ChannelOptions@ ("@TB2d@":#TB2d), it must be encoded as a bitfield per "@TR3@":#TR3 and set as the @flags@ field of the @ATTACH@ @ProtocolMessage@. (For the avoidance of doubt, when multiple different spec items require flags to be set in the @ATTACH@, the final @flags@ field should be the bitwise OR of them all)
** @(RTL4m)@ On receipt of an @ATTACHED@, the client library should decode the @flags@ into an array of @ChannelMode@ s (that is, the same format as @ChannelOptions.modes@) and expose it as a read-only @modes@ field of the @RealtimeChannel@ (or a @getModes()@ method where that is more idiomatic). This should only contain @ChannelMode@ s: it should not contain flags which are not modes (see "@TB2d@":#TB2d)
* @(RTL5)@ @RealtimeChannel#detach@ function:
** @(RTL5a)@ If the channel state is @INITIALIZED@ or @DETACHED@ nothing is done
** @(RTL5i)@ If the channel is in a pending state @DETACHING@ or @ATTACHING@, do the detach operation after the completion of the pending request
** @(RTL5b)@ If the channel state is @FAILED@, the @detach@ request results in an error
** @(RTL5j)@ If the channel state is @SUSPENDED@, the @detach@ request transitions the channel immediately to the @DETACHED@ state
** @(RTL5g)@ If the connection state is @CLOSING@ or @FAILED@, the @detach@ request results in an error
** @(RTL5h)@ If the connection state is @CONNECTING@ or @DISCONNECTED@, do the detach operation once the connection state is @CONNECTED@
** @(RTL5d)@ Otherwise a @DETACH@ ProtocolMessage is sent to the server, the state transitions to @DETACHING@ and the channel becomes @DETACHED@ when the confirmation @DETACHED@ ProtocolMessage is received
** @(RTL5f)@ Once a @DETACH@ @ProtocolMessage@ is sent, if a @DETACHED@ @ProtocolMessage@ is not received within the "default realtime request timeout":#defaults, the detach request should be treated as though it has failed and the channel will return to its previous state
** @(RTL5k)@ If the channel receives an @ATTACHED@ message while in the @DETACHING@ or @DETACHED@ state, it should send a new @DETACH@ message and remain in (or transition to) the @DETACHING@ state
** @(RTL5e)@ If the language permits, a callback can be provided that is called when the channel is detached successfully or the detach fails and the @ErrorInfo@ error is passed as an argument to the callback
* @(RTL6)@ @RealtimeChannel#publish@ function:
** @(RTL6a)@ Messages are encoded in the same way as the @RestChannel#publish@ method, and "RSL1g":#RSL1g (size limit) applies similarly
*** @(RTL6a1)@ "RSL1k":#RSL1k (@idempotentRestPublishing@ option), "RSL1j1":#RSL1j1 (idempotent publishing test), and "RSL1l":#RSL1l (@publish(Message, params)@ form) do not apply to realtime publishes
** @(RTL6b)@ An optional callback can be provided to the @#publish@ method that is called when the message is successfully delivered or upon failure with the appropriate @ErrorInfo@ error. A test should exist to publish lots of messages on a few connections to ensure all message success callbacks are called for all messages published
** @(RTL6i)@ Expects either a @Message@ object, an array of @Message@ objects, or a @name@ string and @data@ payload:
*** @(RTL6i1)@ When @name@ and @data@ (or a @Message@) is provided, a single @ProtocolMessage@ containing one @Message@ is published to Ably
*** @(RTL6i2)@ When an array of @Message@ objects is provided, a single @ProtocolMessage@ is used to publish all @Message@ objects in the array.
*** @(RTL6i3)@ Allows @name@ and or @data@ to be @null@. If any of the values are @null@, then key is not sent to Ably i.e. a payload with a @null@ value for @data@ would be sent as follows @{ "name": "click" }@
** @(RTL6c)@ Connection and channel state conditions:
*** @(RTL6c1)@ If the connection is @CONNECTED@ and the channel is @INITIALIZED@, @ATTACHED@, @DETACHED@, @ATTACHING@, or @DETACHING@ then the messages are published immediately
*** @(RTL6c2)@ If the connection is @INITIALIZED@, @CONNECTING@ or @DISCONNECTED@; and the channel is @INITIALIZED@, @ATTACHED@, @DETACHED@, @ATTACHING@, or @DETACHING@; and @ClientOptions#queueMessages@ has not been explicitly set to false; then the message will be placed in a connection-wide message queue to be delivered as soon as the connection is @CONNECTED@. (The recommended implementation is to have the message be sent from the channel to the connection if it fulfils the channel state condition; the connection can then dispatch, queue, or reject it according to its own state and @queueMessages@)
*** @(RTL6c4)@ In any other case the operation should result in an error
*** @(RTL6c5)@ A publish should not trigger an implicit attach (in contrast to earlier version of this spec)
** @(RTL6d)@ The protocol permits @Message@ s that have been queued to be sent in a single @ProtocolMessage@ , by bundling them into the @ProtocolMessage#messages@ or @ProtocolMessage#presence@ array. In general, the client library SHOULD NOT do this. If it does, it MUST conform to all of the following constraints:
*** @(RTL6d1)@ The resulting @ProtocolMessage@ must not exceed the @maxMessageSize@
*** @(RTL6d2)@ Messages can only be bundled together if they have the same @clientId@ value (or both have no @clientId@ set). (Note that this constraint only applies to what the client library can autonomously do as part of queuing messages, not to what the user can do by publishing an array of @Messages@. It exists because if any @Message@ in a @ProtocolMessage@ has an invalid @clientId@, the entire @ProtocolMessage@ is rejected. This is fine if the user has deliberately published the @Messages@ together – they requested atomicity – but not if the client library has bundled them without the user's knowledge)
*** @(RTL6d3)@ Messages can only be bundled together if they are for the same @channel@
*** @(RTL6d4)@ Messages can only be bundled together if they are of the same type (that is, @Message@ versus @PresenceMessage@)
*** @(RTL6d5)@ Only contiguous messages in the queue can be bundled together. For example, if the user publishes three messages, A, B, and C, of which A and C could be bundled together under @RTL6d1-4@ but B could not, then no bundling should occur
*** @(RTL6d6)@ The order of messages in the resulting @ProtocolMessage@ Messages must match the publish order. For example, if the user publishes @Message@ D, then the @Message@ array [E, F], then @Message@ G, the final @messages@ array should be [D, E, F, G]
*** @(RTL6d7)@ Messages must not be bundled if any have had had their @Message.id@ property set
** @(RTL6e)@ Unidentified clients using "Basic Auth":https://en.wikipedia.org/wiki/Basic_access_authentication (i.e. any @clientId@ is permitted as no @clientId@ specified):
*** @(RTL6e1)@ When a @Message@ with a @clientId@ value is published, Ably will accept and publish that message with the provided @clientId@. A test should assert that the @clientId@ of the published @Message@ is populated
** @(RTL6g)@ Identified clients with a @clientId@ (as a result of either an explicitly configured @clientId@ in @ClientOptions@, or implicitly through Token Auth):
*** @(RTL6g1)@ When publishing a @Message@ with the @clientId@ attribute set to @null@:
**** @(RTL6g1a)@ It is unnecessary for the client to set the @clientId@ of the @Message@ before publishing
**** @(RTL6g1b)@ Ably will assign a @clientId@ upon receiving the @Message@. A test should assert that the @clientId@ value is populated for the @Message@ when received
*** @(RTL6g2)@ When publishing a @Message@ with the @clientId@ attribute value set to the identified client's @clientId@, Ably will accept the message and publish it. A test should assert that the @clientId@ value is populated for the @Message@ when received
*** @(RTL6g3)@ When publishing a @Message@ with a different @clientId@ attribute value from the identified client's @clientId@, the client library should reject that publish operation immediately. The message should not be sent to Ably and it should result in an error, typically in the form of an error callback. The connection and channel must remain available for further operations
*** @(RTL6g4)@ When using Token Auth, unless a @clientId@ has been provided in @ClientOptions@ or inferred following authentication, the client library is unidentified and will not be constrained when publishing messages with any explicit @clientId@. If a @Message@ with a @clientId@ value is published before the @clientId@ is configured or inferred following authentication, the client library should not reject any explicit @clientId@ specified in a message. A test should instantiate a client without an explicit @clientId@ and an @authCallback@ that returns a @tokenDetails@ object with a @clientId@, then publish a message with the same @clientId@ before authentication, and ensure that the message is published following authentication and received back with the @clientId@ intact. A further test should follow the same sequence of events, but should instead use an incompatible @clientId@ in the message, expecting that the message is rejected by the Ably service and the message error should contain the server error message, and the connection and channel should remain available for further operations
** @(RTL6h)@ The @publish(name, data)@ form should not take any arguments other than those two. If a client library has supported additional arguments to the @(name, data)@ form (e.g. separate arguments for @clientId@ and @extras@, or a single @attributes@ argument) in any 1.x version, it should continue to do so until version 2.0.
** @(RTL6f)@ @Message#connectionId@ should match the current @Connection#id@ for all published messages, a test should exist to ensure the @connectionId@ for received messages matches that of the publisher
* @(RTL7)@ @RealtimeChannel#subscribe@ function:
** @(RTL7a)@ Subscribe with a single listener argument subscribes a listener to all messages
** @(RTL7b)@ Subscribe with a name argument and a listener argument subscribes a listener to only messages whose @name@ member matches the string name
** @(RTL7c)@ Implicitly attaches the @RealtimeChannel@ if the channel is in the @INITIALIZED@ state. The optional callback, if provided, is called according to "@RTL4d@":#RTL4d based on the implicit attach operation. The listener will always be registered regardless of the implicit attach result
** @(RTL7d)@ Messages delivered are automatically decoded based on the @encoding@ attribute; see @RestChannel@ encoding features. Tests should exist to publish and subscribe to encoded messages using the "AES 128":https://github.com/ably/ably-common/blob/main/test-resources/crypto-data-128.json and "AES 256":https://github.com/ably/ably-common/blob/main/test-resources/crypto-data-256.json fixture test data
** @(RTL7e)@ If a message cannot be decoded or decrypted successfully, it should be delivered to the listener with the @encoding@ attribute set indicating the residual encoding state, and an error should be logged
** @(RTL7f)@ A test should exist ensuring published messages are not echoed back to the subscriber when @echoMessages@ is set to false in the @RealtimeClient@ library constructor
* @(RTL8)@ @RealtimeChannel#unsubscribe@ function:
** @(RTL8c)@ Unsubscribe with no arguments unsubscribes all listeners
** @(RTL8a)@ Unsubscribe with a single listener argument unsubscribes the provided listener to all messages if subscribed
** @(RTL8b)@ Unsubscribe with a name argument and a listener argument unsubscribes the provided listener if previously subscribed with a name-specific subscription
* @(RTL9)@ @RealtimeChannel#presence@ attribute:
** @(RTL9a)@ Returns the @RealtimePresence@ object for this channel
* @(RTL10)@ @RealtimeChannel#history@ function:
** @(RTL10a)@ Supports all the same params as @RestChannel#history@
** @(RTL10b)@ Additionally supports the param @untilAttach@, which if true, will only retrieve messages prior to the moment that the channel was attached or emitted an @UPDATE@ indicating loss of continuity. This bound is specified by passing the querystring param @fromSerial@ with the @RealtimeChannel#properties.attachSerial@ assigned to the channel in the @ATTACHED@ @ProtocolMessage@ (see "RTL15a":#RTL15a). If the @untilAttach@ param is specified when the channel is not attached, it results in an error
** @(RTL10c)@ Returns a @PaginatedResult@ page containing the first page of messages in the @PaginatedResult#items@ attribute returned from the history request
** @(RTL10d)@ A test should exist that publishes messages from one client, and upon confirmation of message delivery, a history request should be made on another client to ensure all messages are available
* @(RTL12)@ An attached channel may receive an additional @ATTACHED@ @ProtocolMessage@ from Ably at any point. (This is typically triggered following a transport being resumed to indicate a partial loss of message continuity on that channel, in which case the @ProtocolMessage@ will have a @resumed@ flag set to false). If and only if the @resumed@ flag is false, this should result in the channel emitting an @UPDATE@ event with a @ChannelStateChange@ object. The @ChannelStateChange@ object should have both @previous@ and @current@ attributes set to @attached@, the @reason@ attribute set to to the @error@ member of the @ATTACHED@ @ProtocolMessage@ (if any), and the @resumed@ attribute set per the @RESUMED@ bitflag of the @ATTACHED@ @ProtocolMessage@. (Note that @UPDATE@ should be the only event emitted: in particular, the library must not emit an @ATTACHED@ event if the channel was already attached, see @RTL2g@).
* @(RTL15)@ @RealtimeChannel#properties@ attribute is a @ChannelProperties@ object representing properties of the channel state. @properties@ is a publicly accessible member of the channel, but it is an experimental and unstable API. It has the following attributes:
** @(RTL15a)@ @attachSerial@ is unset when the channel is instantiated, and is updated with the @channelSerial@ from each @ATTACHED@ @ProtocolMessage@ received from Ably with a matching @channel@ attribute. The @attachSerial@ value is used for @untilAttach@ queries, see "RTL10b":#RTL10b
* @(RTL13)@ If the channel receives a server initiated @DETACHED@ message when it is in the @ATTACHING@, @ATTACHED@ or @SUSPENDED@ state (i.e. the client has not explicitly requested a detach putting the channel into the @DETACHING@ state), then the following applies:
** @(RTL13a)@ If the channel is in the @ATTACHED@ or @SUSPENDED@ states, an attempt to reattach the channel should be made immediately by sending a new @ATTACH@ message and the channel should transition to the @ATTACHING@ state with the error emitted in the @ChannelStateChange@ event.
** @(RTL13b)@ If the attempt to re-attach fails, or if the channel was already in the @ATTACHING@ state, the channel will transition to the @SUSPENDED@ state and the error will be emitted in the @ChannelStateChange@ event. An attempt to re-attach the channel automatically will then be made after the period defined by "@RTB1@":#RTB1. When re-attaching the channel, the channel will transition to the @ATTACHING@ state. If that request to attach fails i.e. it times out or a @DETACHED@ message is received, then the process described here in @RTL13b@ will be repeated, indefinitely
** @(RTL13c)@ If the connection is no longer @CONNECTED@, then the automatic attempts to re-attach the channel described in "RTL13b":#RTL13b must be cancelled as any implicit channel state changes subsequently will be covered by "RTL3":#RTL3
* @(RTL14)@ If an @ERROR ProtocolMessage@ is received for this channel (the channel attribute matches this channel's name), then the channel should immediately transition to the FAILED state, and the @RealtimeChannel.errorReason@ should be set
* @(RTL16)@ @RealtimeChannel#setOptions@ takes a @ChannelOptions@ object and sets or updates the stored channel options.
** @(RTL16a)@ If the user has provided either @ChannelOptions.params@ or @ChannelOptions.modes@ and the channel is in either the @attached@ or @attaching@ state, @RealtimeChannel#setOptions@ sends an @ATTACH@ message to the server with the params & modes encoded per "@RTL4@":#RTL4, and indicates success once the server has replied with an @ATTACHED@ (or indicates failure if the channel becomes detached or failed before that happens, as with @RealtimeChannel#attach@); else it indicates success immediately
* @(RTL17)@ No messages should be passed to subscribers if the channel is in any state other than @ATTACHED@.
* @(RTL18)@ Given "vcdiff"-encoded deltas are applied to the previous message published on a channel, when a "vcdiff" encoding fails to be decoded, it makes it impossible for a client to apply subsequent deltas received from that point of failure forward. As such, the client must automatically execute the following recovery procedure in lieu of "RTL7e":#"RTL7e":
** @(RTL18a)@ Log error with code 40018
** @(RTL18b)@ Discard the message
** @(RTL18c)@ Send an @ATTACH@ @ProtocolMessage@ with the @channelSerial@ set to the previous message to the message for which "vcdiff" decoding failed to the server, transitioning the channel state to @ATTACHING@, and waiting for a confirmation @ATTACHED@, as per @RTL4c@ and @RTL4f@. @ChannelStateChange.reason@ should be set to @ErrorInfo@ object with with code 40018.
* @(RTL19)@ The data payload of the last message on each channel must be stored at all times since it will be needed to decode any subsequent message that has a "vcdiff" encoding step. The stored value is the "base payload" of the most recent message; this is the @data@ member of the message, in string or binary form, once all application-level encoding steps have been applied. The base payload is derived initially by processing a non-delta message; the processing and bookkeeping rules are as follows:
** @(RTL19a)@ When processing any message (whether a delta or a full message), if the message @encoding@ string ends in @base64@, the message @data@ should be base64-decoded (and the @encoding@ string modified accordingly per "RSL6":#RSL6).
** @(RTL19b)@ In the case of a non-delta message, the resulting @data@ value is stored as the base payload.
** @(RTL19c)@ In the case of a delta message with a @vcdiff@ @encoding@ step, the @vcdiff@ decoder must be used to decode the base payload of the of delta message, applying that delta to the stored base payload. The direct result of that vcdiff delta application, before performing any further decoding steps, is stored as the updated base payload.
* @(RTL20)@ The @id@ of the last received message on each channel must be stored along with the base payload. When processing a delta message (i.e. one whose @encoding@ contains @vcdiff@ step) the stored last message @id@ must be compared against the delta reference @id@, indicated in the @Message.extras.delta.from@ field of the delta message. If the delta reference @id@ of the received delta message does not equal the stored @id@ corresponding to the base payload, the message decoding must fail. The recovery procedure from "RTL18":#RTL18 must be executed.
* @(RTL21)@ The messages in the @messages@ array of a @ProtocolMessage@ should each be decoded in ascending order of their index in the array.
* @(RTL22)@ Methods must be provided for attaching and removing a listener which only executes when the message matches a set of criteria.
** @(RTL22a)@ The method must allow for filters matching one or more of: @extras.ref.timeserial@, @extras.ref.type@ or @name@. See #MFI1 for an object implementation.
** @(RTL22b)@ The method must allow for matching only messages which do not have @extras.ref@.
** @(RTL22c)@ The listener must only execute if all provided criteria are met.
** @(RTL22d)@ The method should use the @MessageFilter@ object if possible and idiomatic for the language.
* @(RTL24)@ @RealtimeChannel#errorReason@ attribute is an optional @ErrorInfo@ object which is set by the library when an error occurs on the channel, as described by "RTN11d":#RTN11d, "RTL3a":#RTL3a, "RTL4e":#RTL4e, "RTL4g":#RTL4g, "RTL14":#RTL14.
h3(#realtime-presence). RealtimePresence
* @(RTP1)@ When a channel @ATTACHED@ @ProtocolMessage@ is received, the @ProtocolMessage@ may contain a @HAS_PRESENCE@ bit flag indicating that it will perform a presence sync, see "TR3":#TR3 . (Note that this does not imply that there are definitely members present, only that there may be; the sync may be empty). If the flag is 1, the server will shortly perform a @SYNC@ operation as described in "RTP18":#RTP18 . If that flag is 0 or there is no @flags@ field, the presence map should be considered in sync immediately with no members present on the channel
* @(RTP2)@ A @PresenceMap@ should be used to maintain a list of members present on a channel. Broadly, this is is a map of "memberKeys":#TP3h to presence messages, all with @PRESENT@ actions (during a sync there may also be ones with an @ABSENT@ action, see "RTP2f":#RTP2f).
** @(RTP2a)@ All incoming presence messages must be compared for newness with the matching member already in the @PresenceMap@, if one exists, where "matching" means they share the same @memberKey@ (or equivalently, they share both @connectionId@ and @clientId@)
** @(RTP2b)@ To compare for newness:
*** @(RTP2b1)@ If either presence message has a @connectionId@ which is not an initial substring of its @id@, compare them by @timestamp@ numerically. (This will be the case when one of them is a 'synthesized leave' event sent by realtime to indicate a connection disconnected unexpectedly 15s ago. Such messages will have an @id@ that does not correspond to its @connectionId@, as it wasn't actually published by that connection)
*** @(RTP2b2)@ Else split the @id@ of both presence messages (which will be of the form @connid:msgSerial:index@, e.g. @aaaaaa:0:0@) on the separator @:@, and parse the latter two as integers. Compare them first by @msgSerial@ numerically, then (if @msgSerial@ is equal) by @index@ numerically, larger being newer in both cases
** @(RTP2c)@ As there are no guarantees that during a @SYNC@ operation presence events will arrive in order, all presence messages from a @SYNC@ must also be compared for newness in the same way as they would from a @PRESENCE@
** @(RTP2d)@ When a presence message with an action of @ENTER@, @UPDATE@, or @PRESENT@ arrives, it should be added to the presence map with the action set to @PRESENT@
** @(RTP2e)@ If a @SYNC@ is not in progress, then when a presence message with an action of @LEAVE@ arrives, that @memberKey@ should be deleted from the presence map, if present
** @(RTP2f)@ If a @SYNC@ is in progress, then when a presence message with an action of @LEAVE@ arrives, it should be stored in the presence map with the action set to @ABSENT@. When the @SYNC@ completes, any @ABSENT@ members should be deleted from the presence map. (This is because in a @SYNC@, we might receive a @LEAVE@ before the corresponding @ENTER@).
** @(RTP2g)@ Any incoming presence message that passes the newness check should be emitted on the @RealtimePresence@ object, with an event name set to its original action. Note: this action may not be the same one that it will have when stored in the presence map. For example: an incoming presence message with an @ENTER@ action will be emitted as an @enter@ event, and the emitted presence message will have its action set to @ENTER@. However, it will be stored in the presence map with a @PRESENT@ action.
* @(RTP18)@ The realtime system reserves the right to initiate a sync of the presence members at any point once a channel is attached. A server initiated sync provides Ably with a means to send a complete list of members present on the channel at any point
** @(RTP18a)@ The client library determines that a new sync has started whenever a @SYNC@ @ProtocolMessage@ is received with a @channel@ attribute and a new sync sequence identifier in the @channelSerial@ attribute. The @channelSerial@ is used as the sync cursor and is a two-part identifier @<sync sequence id>:<cursor value>@. If a new sequence identifier is sent from Ably, then the client library must consider that to be the start of a new sync sequence and any previous in-flight sync should be discarded
** @(RTP18b)@ The sync operation for that sequence identifier has completed once the cursor is empty; that is, when the @channelSerial@ looks like @<sync sequence id>:@
** @(RTP18c)@ a @SYNC@ may also be sent with no @channelSerial@ attribute. In this case, the sync data is entirely contained within that @ProtocolMessage@
* @(RTP19)@ If the @PresenceMap@ has existing members when a @SYNC@ is started, the client library must ensure that members no longer present on the channel are removed from the local @PresenceMap@ once the sync is complete. In order to do this, the client library must keep track of any members that have not been added or updated in the @PresenceMap@ during the sync process. Note that a member can be added or updated when received in a @SYNC@ message or when received in a @PRESENCE@ message during the sync process. Once the sync is complete, the members in the @PresenceMap@ that have not been added or updated should be removed from the @PresenceMap@ and a @LEAVE@ event should be published for each. The @PresenceMessage@ published should contain the original attributes of the presence member with the @action@ set to @LEAVE@, @PresenceMessage#id@ set to @null@, and the @timestamp@ set to the current time. This behavior should be tested as follows: @ENTER@ presence on a channel, wait for @SYNC@ to complete, inject a member directly into the local @PresenceMap@ so that it only exists locally and not on the server, send a @SYNC@ message with the @channel@ attribute populated with the current channel which will trigger a server initiated @SYNC@. A @LEAVE@ event should then be published for the injected member, and checking the @PresenceMap@ should reveal that the member was removed and the valid member entered for this connection is still present
** @(RTP19a)@ If the @PresenceMap@ has existing members when an @ATTACHED@ message is received without a @HAS_PRESENCE@ flag, the client library should emit a @LEAVE@ event for each existing member, and the @PresenceMessage@ published should contain the original attributes of the presence member with the @action@ set to @LEAVE@, @PresenceMessage#id@ set to @null@, and the @timestamp@ set to the current time. Once complete, all members in the @PresenceMap@ should be removed as there are no members present on the channel
* @(RTP17)@ The RealtimePresence object should also keep a second @PresenceMap@ containing only members that match the current @connectionId@. Any incoming presence message that satisfies @RTP17b@ should be applied to this object in the same way as for the normal @PresenceMap@. This object should be private and is used to maintain a list of members that need to be automatically re-entered by the @RealtimePresence@ object when required to by @RTP17c@.
** @(RTP17a)@ All members belonging to the current connection are published as a @PresenceMessage@ on the @RealtimeChannel@ by the server irrespective of whether the client has permission to subscribe or the @RealtimeChannel@ is configured to publish presence events. A test should exist that attaches to a @RealtimeChannel@ with a @presence@ capability and without a @subscribe@ capability. It should then enter the @RealtimeChannel@ and ensure that the member entered from the current connection is present in the internal and public presence set available via "@RealtimePresence#get@":#RTP11
** @(RTP17b)@ The events that should be applied to the @RTP17@ presence map are: any @ENTER@, @PRESENT@ or @UPDATE@ event with a @connectionId@ that matches the current client's @connectionId@; any @LEAVE@ event with a @connectionId@ that matches the current client's @connectionId@ and is not a 'synthesized leave' (an event that has a connectionId which is not an initial substring of its id, per "@RTP2b1@":#RTP2b1 )
** @(RTP17c)@ The RealtimePresence object should perform automatic re-entry in the following situations:
*** @(RTP17c1)@ After a @SYNC@ operation has completed, per "@RTP18b@":#RTP18b
*** @(RTP17c2)@ When an @ATTACHED@ message is received with no "@HAS_PRESENCE@":#TR3a flag (so no @SYNC@ is expected as the server does not believe anyone is currently present)
** @(RTP17d)@ Automatic re-entry consists of, for each member of the @RTP17@ internal @PresenceMap@ whose @memberKey@ is not also a member of the normal @PresenceMap@, publishing a @PresenceMessage@ with an @ENTER@ action using the @clientId@ and @data@ attributes from that member, and removing that member from the internal @PresenceMap@
** @(RTP17e)@ If the publish attempt fails for an automatic presence @ENTER@ (for example, by Ably rejecting it with a @NACK@), an @UPDATE@ event should be emitted on the channel with @resumed@ set to true and @reason@ set to an @ErrorInfo@ object with @code@ @91004@, a @message@ indicating that an automatic re-enter has failed and indicating the @clientId@, and @cause@ set to the reason for the enter failure. The error should also be logged at @warn@ level or higher.
* @(RTP4)@ Ensure a test exists that enters 250 members using @RealtimePresence#enterClient@ on a single connection, and checks for @PRESENT@ events to be emitted on another connection for each member, and once sync is complete, all 250 members should be present in a @RealtimePresence#get@ request
* @(RTP5)@ RealtimeChannel state change side effects:
** @(RTP5a)@ If the channel enters the @DETACHED@ or @FAILED@ state then all queued presence messages will fail immediately, and the @PresenceMap@ and "internal PresenceMap (see RTP17)":#RTP17 is cleared. The latter ensures members are not automatically re-entered if the @RealtimeChannel@ later becomes attached. Since channels in the @DETACHED@ and @FAILED@ states will not receive any presence updates from Ably, presence events (specifically @LEAVE@) should not be emitted when the @PresenceMap@ is cleared as each presence member's state is unknown
** @(RTP5f)@ If the channel enters the @SUSPENDED@ state then all queued presence messages will fail immediately, and the @PresenceMap@ is maintained. This ensures that if the channel later becomes @ATTACHED@, it will only publish presence events for the changes in the @PresenceMap@ that have occurred whilst the client was disconnected. A test should exist for a channel that is in the @SUSPENDED@ state containing presence members to transition to the @ATTACHED@ state, and following the @SYNC@ process after attaching, any members present before and after the sync should not emit presence events, all other changes should be reflected in the @PresenceMap@ and should emit presence events on the channel
** @(RTP5b)@ If a channel enters the @ATTACHED@ state then all queued presence messages will be sent immediately. A presence @SYNC@ may be initiated per "@RTP1@":#RTP1
* @(RTP16)@ Connection state conditions:
** @(RTP16a)@ If the channel is @ATTACHED@ then the presence messages are handled per @RTL6c2@. (That is: they should be sent to the connection, to be published immediately if the connection is @CONNECTED@, else if the connection state and @queueMessages@ option allows they may be placed in a connection-wide queue to be published once the connection becomes @CONNECTED@, else rejected)
** @(RTP16b)@ If the channel is @ATTACHING@ or @INITIALIZED@, then if @ClientOptions.queueMessages@ has not been explicitly set to @false@, the presence messages should be queued at a channel level, to be handled per @RTP16a@ once the channel becomes @ATTACHED@, or failed if the channel state becomes @SUSPENDED@, @FAILED@, or @DETACHED@ first
** @(RTP16c)@ In any other case the operation should result in an error
* @(RTP6)@ @RealtimePresence#subscribe@ function:
** @(RTP6a)@ Subscribe with a single listener argument subscribes a listener to all presence messages
** @(RTP6b)@ Subscribe with an action argument and a listener argument - such as @ENTER@, @LEAVE@, @UPDATE@ or @PRESENT@ - subscribes a listener to receive only presence messages with that action. In lanuages where method overloading is supported the action argument may also be an array of actions to receive only presence messages with an action included in the supplied array.
** @(RTP6c)@ Implicitly attaches the @RealtimeChannel@ if the channel is in the @INITIALIZED@ state. The optional callback, if provided, is called according to "@RTL4d@":#RTL4d based on the implicit attach operation. The listener will always be registered regardless of the implicit attach result
* @(RTP7)@ @RealtimePresence#unsubscribe@ function:
** @(RTP7c)@ Unsubscribe with no arguments unsubscribes all listeners
** @(RTP7a)@ Unsubscribe with a single listener argument unsubscribes the listener if previously subscribed with an action-specific subscription
** @(RTP7b)@ Unsubscribe with an action argument and a listener argument unsubscribes the provided listener to all presence messages for that action
* @(RTP8)@ @RealtimePresence#enter@ function:
** @(RTP8a)@ Enters the current client into this channel, optionally with the data and/or extras provided
** @(RTP8b)@ Optionally a callback can be provided that is called for both success or failure to enter
** @(RTP8c)@ A @PRESENCE ProtocolMessage@ with a @PresenceMessage@ with the action @ENTER@ is sent to the Ably service. The @clientId@ attribute of the @PresenceMessage@ must not be present. Entering without an explicit @PresenceMessage#clientId@, implicitly uses the @clientId@ for the current connection
** @(RTP8d)@ Implicitly attaches the @RealtimeChannel@ if the channel is in the @INITIALIZED@ state. However, if the channel is in the @DETACHED@ or @FAILED@ state, the @enter@ request results in an error
** @(RTP8e)@ Optional data and/or extras can be included when entering a channel that will be encoded and decoded as with normal messages. A test should exist to ensure data and extras used with enter are encoded & decoded correctly. Also, when data and/or extras is provided when entering, but neither data nor extras are provided when leaving, the data attribute should be emitted in the @LEAVE@ event for this client
** @(RTP8f)@ If the client library is authenticated but unidentified (i.e. @clientId@ is a wildcard @'*'@ or client is anonymous), the @enter@ request results in an error immediately
** @(RTP8g)@ If the channel is @DETACHED@ or @FAILED@, the @enter@ request results in an error immediately
** @(RTP8h)@ If the Ably service determines that the client does not have required presence permission, a @NACK@ is sent to the client resulting in an error
** @(RTP8i)@ If the Ably service determines that the client is unidentified, a @NACK@ is sent to the client resulting in an error
* @(RTP9)@ @RealtimePresence#update@ function:
** @(RTP9a)@ Updates the data and/or extras for the present member with an updated value or empty value (eg @null@)
** @(RTP9b)@ If the client was not already entered, it enters this client into this channel
** @(RTP9c)@ Optionally a callback can be provided that is called for both success or failure to update
** @(RTP9d)@ A @PRESENCE ProtocolMessage@ with a @PresenceMessage@ with the action @UPDATE@ is sent to the Ably service. The @clientId@ attribute of the @PresenceMessage@ must not be present. Updating without an explicit @PresenceMessage#clientId@, implicitly uses the @clientId@ for the current connection
** @(RTP9e)@ In all other ways, this method is identical to @RealtimePresence#enter@ and should have matching tests
* @(RTP10)@ @RealtimePresence#leave@ function:
** @(RTP10a)@ Leaves this client from the channel and the data and/or extras will be updated with the values provided. If the language permits the data argument to be omitted, then the previously set data value will be sent as a convenience
** @(RTP10b)@ Optionally a callback can be provided that is called for both success or failure to leave
** @(RTP10c)@ A @PRESENCE ProtocolMessage@ with a @PresenceMessage@ with the action @LEAVE@ is sent to the Ably service. The @clientId@ attribute of the @PresenceMessage@ must not be present. Leaving without an explicit @PresenceMessage#clientId@, implicitly uses the @clientId@ for the current connection
** @(RTP10d)@ If the client is not currently @ENTERED@, Ably will respond with an @ACK@ and the request will succeed (i.e. the outcome of asking to @LEAVE@ when not present vs being present is the same)
** @(RTP10e)@ In all other ways, this method is identical to @RealtimePresence#enter@ and should have matching tests
* @(RTP11)@ @RealtimePresence#get@ function:
** @(RTP11a)@ Returns the list of current members on the channel in a callback. By default, will wait for the @SYNC@ to be completed, see "RTP11c1":#RTP11c1
** @(RTP11b)@ Implicitly attaches the @RealtimeChannel@ if the channel is in the @INITIALIZED@ state. However, if the channel is in or enters the @DETACHED@ or @FAILED@ state before the operation succeeds, it will result in an error
** @(RTP11d)@ If the @RealtimeChannel@ is in the @SUSPENDED@ state then the @get@ function will by default, or if @waitForSync@ is set to @true@, result in an error with @code@ @91005@ and a @message@ stating that the presence state is out of sync due to the channel being in a @SUSPENDED@ state. If however the @get@ function is called with @waitForSync@ set to @false@, then it immediately returns the members currently stored in the @PresenceMap@ giving developers access to the members that were present at the time the channel became @SUSPENDED@
** @(RTP11c)@ An optional set of params can be provided:
*** @(RTP11c1)@ @waitForSync@ (default @true@). When @true@, method will wait until @SYNC@ is complete before returning a list of members. When @false@, known set of presence members is returned immediately, which may be incomplete if the @SYNC@ is not finished
*** @(RTP11c2)@ @clientId@ filters members by the provided @clientId@
*** @(RTP11c3)@ @connectionId@ filters members by the provided @connectionId@
* @(RTP12)@ @RealtimePresence#history@ function:
** @(RTP12a)@ Supports all the same params as @RestPresence#history@
** @(RTP12c)@ Returns a @PaginatedResult@ page containing the first page of messages in the @PaginatedResult#items@ attribute returned from the history request
** @(RTP12d)@ A test should exist that registers presence with a few clients, and upon confirmation of entering the channel for all clients, a presence history request should be made using another client to ensure all presence events are available
* @(RTP13)@ @RealtimePresence#syncComplete@ attribute is @true@ if the initial @SYNC@ operation has completed for the members present on the channel
* @(RTP14)@ @RealtimePresence#enterClient@ function:
** @(RTP14a)@ Enters into presence on a channel on behalf of another @clientId@. This allows a single client with suitable permissions to register presence on behalf of any number of clients using a single connection
** @(RTP14b)@ Optionally a callback can be provided that is called for both success or failure to enter
** @(RTP14c)@ Data can optionally be provided when entering and will follow the normal encoding & decoding rules
** @(RTP14d)@ A test should exist that registers a number of members each with a different @clientId@ on a presence channel, and then a @RealtimePresence#get@ should be used to verify that all members are present as expected
* @(RTP15)@ @RealtimePresence#enterClient@ @RealtimePresence#updateClient@ and @RealtimePresence#leaveClient@ function:
** @(RTP15a)@ Performs an enter, update or leave for given @clientId@. These methods apply if the Realtime library was not initialized with a specific @clientId@. This allows a single client with suitable permissions to update presence on behalf of any number of clients using a single connection. Otherwise these are functionality equivalent to the corresponding @enter@, @update@ and @leave@ methods, and equivalent test coverage should be provided
** @(RTP15b)@ Tests should use @enterClient@, @updateClient@ and @leaveClient@ for many members from one @RealtimeClient@ instance and check that the operations are reflected in the presence map and the expected events are emitted on a separate client
** @(RTP15c)@ Tests should also ensure that using these methods has no side effects on a client that has entered normally using @RealtimePresence#enter@
** @(RTP15d)@ A callback can be provided that will be called upon success or failure
** @(RTP15e)@ Implicitly attaches the @RealtimeChannel@ if the channel is in the @INITIALIZED@ state. However, if the channel is in or enters the @DETACHED@ or @FAILED@ state before the operation succeeds, it will result in an error
** @(RTP15f)@ If the client is identified and has a valid @clientId@, and the @clientId@ argument does not match the client's @clientId@, then it should indicate an error. The connection and channel remain available for further operations
h3(#eventemitter). EventEmitter mixin / interface
* @(RTE1)@ @EventEmitter@ is a generic interface for event registration and delivery used in a number of the types in the Realtime client library. For example, the @Connection@ object emits events for connection state using the @EventEmitter@ pattern
* @(RTE2)@ Where objects provide @subscribe@ or @unsubscribe@ methods, they should follow the specification for the @EventEmitter#on@ and @EventEmitter#off@ methods respectively
* @(RTE3)@ @EventEmitter#on@ registers the provided listener for either all events when no @event@ argument is provided, or for only a single named event when an @event@ argument is provided. If @on@ is called more than once with the same listener and @event@, the listener is added multiple times to its listener registry. Therefore, as an example, assuming the same listener is registered twice using @on@, and an event is emitted once, the listener would be invoked twice
* @(RTE4)@ @EventEmitter#once@ registers the provided listener for either the first event that is emitted when no @event@ argument is provided, or for only the first occurrence of a single named event when an @event@ argument is provided. If @once@ is called more than once with the same listener, the listener is added multiple times to its listener registry. Therefore, as an example, assuming the same listener is registered twice using @once@, and an event is emitted once, the listener would be invoked twice. However, all subsequent events emitted would not invoke the listener as @once@ ensures that each registration is only invoked once
* @(RTE5)@ @EventEmitter#off@ deregisters a listener. If called with a specific event and a listener, it removes all registrations that match both the given listener and the given event; if called only with a listener, it removes all registrations matching the given listener, regardless of whether they are associated with an event or not; if called with no arguments, it removes all registrations, for all events and listeners
* @(RTE6)@ @EventEmitter#emit@ emits an event, calling registered listeners with the given event name and any other given arguments. If an exception is raised in any of the listeners, the exception is caught by the @EventEmitter@ and the exception is logged to the Ably logger. Tests must exist to ensure exceptions raised in client code do not propagate and inhibit other event processing within the client library. This method is internal to the SDK and should not be exposed in its public interface.
** @(RTE6a)@ The set of listeners called by @emit@ must not change over the course of the @emit@. That is: If a listener being called by @emit@ registers another listener, that second listener should not be called by that invocation of @emit@ (even if it would have been called had it already been present); and if a listener being called by @emit@ removes other listeners, but those other listeners would otherwise have been called during that @emit@ invocation, they should still be called. Tests should exist for both adding and removing. See "https://goo.gl/OVTtjO":https://goo.gl/OVTtjO
h3(#backoff-jitter). Incremental backoff and jitter
* @(RTB1)@ For connections in the @DISCONNECTED@ state and realtime channels in the @SUSPENDED@ state the time until retry is calculated as the product of the initial retry timeout (for @DISCONNECTED@ connections this is the @disconnectedRetryTimeout@, for @SUSPENDED@ channels this is the @channelRetryTimeout@), the backoff coefficient as defined by "@RTB1a@":#RTB1a, and the jitter coefficient as defined by "@RTB1b@":#RTB1b.
** @(RTB1a)@ The backoff coefficient for the nth retry is calculated as the minimum of @(n + 2) / 3@ and @2@ (resulting in the sequence @[1, 4/3, 5/3, 2, 2, ...]@).
** @(RTB1b)@ The jitter coefficient is a random number between 0.8 and 1. The randomness of this number doesn't need to be cryptographically secure but should be approximately uniformly distributed.
h3(#realtime-compatibility). Forwards compatibility
* @(RTF1)@ The library must apply the "robustness principle":https://en.wikipedia.org/wiki/Robustness_principle in its processing of requests and responses with the Ably system. In particular, deserialization of ProtocolMessages and related types, and associated enums, must be tolerant to unrecognised attributes or enum values. Such unrecognised values must be ignored.
h2(#state-conditions-and-operations). State conditions and operations
h3(#connection-states-operations). @Connection.state@ effects on realtime operations
<table>
<tr>
<th></th>
<th>Initialized</th>
<th>Connecting</th>
<th>Connected</th>
<th>Disconnected</th>
<th>Suspended</th>
<th>Closing</th>
<th>Closed</th>
<th>Failed</th>
</tr>
<tr>
<td>@connect@</td>
<!-- When INITIALIZED -->
<td>"RTN11a":#RTN11a</td>
<!-- When CONNECTING -->
<td>No-op</td>
<!-- When CONNECTED -->
<td>No-op</td>
<!-- When DISCONNECTED -->
<td>"RTN11c":#RTN11c</td>
<!-- When SUSPENDED -->
<td>"RTN11c":#RTN11c</td>
<!-- When CLOSING -->
<td>"RTN11b":#RTN11b</td>
<!-- When CLOSED -->
<td>"RTN11a":#RTN11a</td>
<!-- When FAILED -->
<td>"RTN11d":#RTN11d</td>
</tr>
<tr>
<td>@close@</td>
<!-- When INITIALIZED -->
<td>No-op</td>
<!-- When CONNECTING -->
<td>"RTN12f":#RTN12f</td>
<!-- When CONNECTED -->
<td>"RTN12a":#RTN12a</td>
<!-- When DISCONNECTED -->
<td>"RTN12d":#RTN12d</td>
<!-- When SUSPENDED -->
<td>"RTN12d":#RTN12d</td>
<!-- When CLOSING -->
<td>No-op</td>
<!-- When CLOSED -->
<td>No-op</td>
<!-- When FAILED -->
<td>No-op</td>
</tr>
<tr>
<td>@ping@</td>
<!-- When INITIALIZED -->
<td>"RTN13b":#RTN13b</td>
<!-- When CONNECTING -->
<td>"RTN13c":#RTN13c</td>
<!-- When CONNECTED -->
<td>"RTN13a":#RTN13a</td>
<!-- When DISCONNECTED -->
<td>"RTN13c":#RTN13c</td>
<!-- When SUSPENDED -->
<td>"RTN13b":#RTN13b</td>
<!-- When CLOSING -->
<td>"RTN13b":#RTN13b</td>
<!-- When CLOSED -->
<td>"RTN13b":#RTN13b</td>
<!-- When FAILED -->
<td>"RTN13b":#RTN13b</td>
</tr>
<tr>
<td>RealtimeChannel @attach@</td>
<!-- When INITIALIZED -->
<td>"RTL4h":#RTL4h</td>
<!-- When CONNECTING -->
<td>"RTL4h":#RTL4h</td>
<!-- When CONNECTED -->
<td>"See channel states table":#channel-states-operations</td>
<!-- When DISCONNECTED -->
<td>"RTL4h":#RTL4h</td>
<!-- When SUSPENDED -->
<td>"RTL4b":#RTL4b</td>
<!-- When CLOSING -->
<td>"RTL4b":#RTL4b</td>
<!-- When CLOSED -->
<td>"RTL4b":#RTL4b</td>
<!-- When FAILED -->
<td>"RTL4b":#RTL4b</td>
</tr>
<tr>
<td>RealtimeChannel @detach@</td>
<!-- When INITIALIZED -->
<td>"RTL5h":#RTL5h</td>
<!-- When CONNECTING -->
<td>"RTL5h":#RTL5h</td>
<!-- When CONNECTED -->
<td>"See channel states table":#channel-states-operations</td>
<!-- When DISCONNECTED -->
<td>"RTL5h":#RTL5h</td>
<!-- When SUSPENDED -->
<td>"See channel states table":#channel-states-operations</td>
<!-- When CLOSING -->
<td>"RTL5g":#RTL5g</td>
<!-- When CLOSED -->
<td>"See channel states table":#channel-states-operations</td>
<!-- When FAILED -->
<td>"RTL5g":#RTL5g</td>
</tr>
<tr>
<td>RealtimeChannel @publish@</td>
<!-- When INITIALIZED -->
<td>"RTL6c2":#RTL6c2</td>
<!-- When CONNECTING -->
<td>"RTL6c2":#RTL6c2</td>
<!-- When CONNECTED -->
<td>"See channel states table":#channel-states-operations</td>
<!-- When DISCONNECTED -->
<td>"RTL6c2":#RTL6c2</td>
<!-- When SUSPENDED -->
<td>"RTL6c4":#RTL6c4</td>
<!-- When CLOSING -->
<td>"RTL6c4":#RTL6c4</td>
<!-- When CLOSED -->
<td>"RTL6c4":#RTL6c4</td>
<!-- When FAILED -->
<td>"RTL6c4":#RTL6c4</td>
</tr>
<tr>
<td>Presence ops.</td>
<!-- When INITIALIZED -->
<td>"RTP16b":#RTP16b</td>
<!-- When CONNECTING -->
<td>"RTP16b":#RTP16b</td>
<!-- When CONNECTED -->
<td>"See channel states table":#channel-states-operations</td>
<!-- When DISCONNECTED -->
<td>"RTP16b":#RTP16b</td>
<!-- When SUSPENDED -->
<td>"RTP16c":#RTP16c</td>
<!-- When CLOSING -->
<td>"RTP16c":#RTP16c</td>
<!-- When CLOSED -->
<td>"RTP16c":#RTP16c</td>
<!-- When FAILED -->
<td>"RTP16c":#RTP16c</td>
</tr>
</table>
h3(#channel-states-operations). @RealtimeChannel.state@ effects on channel operations
<table>
<tr>
<th></th>
<th>Initialized</th>
<th>Attaching</th>
<th>Attached</th>
<th>Suspended</th>
<th>Detaching</th>
<th>Detached</th>
<th>Failed</th>
</tr>
<tr>
<td>@attach@</td>
<!-- When INITIALIZED -->
<td>"RTL4c":#RTL4c</td>
<!-- When ATTACHING -->
<td>"RTL4h":#RTL4h</td>
<!-- When ATTACHED -->
<td>"RTL4a":#RTL4a</td>
<!-- When SUSPENDED -->
<td>"RTL4c":#RTL4c</td>
<!-- When DETACHING -->
<td>"RTL4h":#RTL4h</td>
<!-- When DETACHED -->
<td>"RTL4c":#RTL4c</td>
<!-- When FAILED -->
<td>"RTL4g":#RTL4g</td>
</tr>
<tr>
<td>@detach@</td>
<!-- When INITIALIZED -->
<td>"RTL5h":#RTL5h</td>
<!-- When ATTACHING -->
<td>"RTL5i":#RTL5i</td>
<!-- When ATTACHED -->
<td>"RTL5d":#RTL5d</td>
<!-- When SUSPENDED -->
<td>"RTL5j":#RTL5j</td>
<!-- When DETACHING -->
<td>"RTL5i":#RTL5i</td>
<!-- When DETACHED -->