Skip to content

chore: fix typographical errors and improve consistency in features.md #438

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ttypic merged 1 commit into from
Mar 11, 2026
Merged

chore: fix typographical errors and improve consistency in features.md #438

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions specifications/features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ The key words "must", "must not", "required", "shall", "shall not", "should", "s
- `(RSC15n)` When the use of fallbacks applies, the set of `fallback domains` is determined by [`REC2`](#REC2).
- `(RSC15b)` This clause has been replaced by [`RSC15j`](#RSC15j) as of specification version 4.0.0.
- `(RSC15e)` This clause has been replaced by [`RSC25`](#RSC25) as of specification version 4.0.0.
- `(RSC15a)` In the case of an error necessitating use of an alternative host (see [RSC15d](#RSC15d)), try `fallback domains` in random order, continuing to try further domains 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 `main.realtime.ably.net` 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
- `(RSC15a)` In the case of an error necessitating use of an alternative host (see [RSC15d](#RSC15d)), try `fallback domains` in random order, continuing to try further domains 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 `main.realtime.ably.net` 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)` This clause has been replaced by [`RSC15n`](#RSC15n) as of specification version 4.0.0.
- `(RSC15g1)` This clause has been replaced by [`RSC15n`](#RSC15n) as of specification version 4.0.0.
- `(RSC15g2)` This clause has been replaced by [`RSC15n`](#RSC15n) as of specification version 4.0.0.
Expand All @@ -145,7 +145,7 @@ The key words "must", "must not", "required", "shall", "shall not", "should", "s
- `(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)` This clause has been replaced by [`RSC19f`](#RSC19f). It was valid up to and including specification version `2.1`.
- `(RSC19f)` Method signature is `request(String method, String path, Int version, 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 key-value pairs of strings (multi-valued headers are not supported) that will respectively result in querystring params and HTTP headers being added to 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
- `(RSC19f)` Method signature is `request(String method, String path, Int version, 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 key-value pairs of strings (multi-valued headers are not supported) that will respectively result in querystring params and HTTP headers being added to 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
- `(RSC19f1)` The `version` parameter specifies the protocol version that the Ably service should use when interpreting the request. The library must include an `X-Ably-Version` header in the request that it sends, with value given by this argument. (Therefore, `request()` does not use the [`CSV2b`](#CSV2b) version number.)
- `(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
Expand Down Expand Up @@ -229,7 +229,7 @@ The key words "must", "must not", "required", "shall", "shall not", "should", "s
- `(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
- `(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
Expand Down Expand Up @@ -639,12 +639,12 @@ The threading and/or asynchronous model for each realtime library will vary by l
- `(RTN17f1)` a `DISCONNECTED` response with an `error.statusCode` in the range `500 <= code <= 504`
- `(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 (subject to `RTN7e`/@RTN7d`). The Ably service is responsible for keeping track of messages, ignoring duplicates and responding with suitable `ACK@/@NACK@ messages
- `(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 (subject to `RTN7e`/`RTN7d`). The Ably service is responsible for keeping track of messages, ignoring duplicates and responding with suitable `ACK`/`NACK` messages
- `(RTN19a1)` One possible implementation of this requirement would be to add any in-flight messages to the `RTL6c2` connection-wide queue of messages that will be sent once the connection next becomes `CONNECTED`
- `(RTN19a2)` In the case of an `RTN15c6` successful resume, the `msgSerial` of the reattempted `ProtocolMessage`s should remain the same as for the original attempt. In the case of an `RTN15c7` failed resume, the message must be assigned a new `msgSerial` from the SDK's internal counter.
- `(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`](#TO3l11@), 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.
- `(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`](#TO3l11), 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), [RTN15c7](#RTN15c7), [RTN15c4](#RTN15c4), [RTN15d](#RTN15d), [RTN15h](#RTN15h), [RTN15i](#RTN15i), [RTN16e](#RTN16e).
Expand Down Expand Up @@ -854,7 +854,7 @@ The threading and/or asynchronous model for each realtime library will vary by l
- `(RTP17f)` This clause has been replaced by [`RTP17i`](#RTP17i). It was valid up to and including specification version `3.0`.
- `(RTP17i)` The `RealtimePresence` object should perform automatic re-entry whenever the channel receives an `ATTACHED` `ProtocolMessage`, except in the case where the channel is already attached and the `ProtocolMessage` has the `RESUMED` bit flag set.
- `(RTP17g)` Automatic re-entry consists of, for each member of the `RTP17` internal `PresenceMap`, publishing a `PresenceMessage` with an `ENTER` action using the `clientId`, `data`, and `id` (subject to `RTP17g1) attributes from that member.
*** `(RTP17g1)@ If the current connection `id` is different from the `connectionId` attribute of the stored member, the published `PresenceMessage` must not have its `id` set.
- `(RTP17g1)` If the current connection `id` is different from the `connectionId` attribute of the stored member, the published `PresenceMessage` must not have its `id` set.
- `(RTP17c)` This clause has been replaced by [`RTP17f`](#RTP17f). It was valid up to and including specification version `1.2`.
- `(RTP17c1)` This clause has been deleted. It was valid up to and including specification version `1.2`.
- `(RTP17c2)` This clause has been deleted. It was valid up to and including specification version `1.2`.
Expand Down Expand Up @@ -953,7 +953,7 @@ Reserved for `RealtimeObjects` feature specification, see [objects-features](../
- `(RTAN4a)` Should support the same set of type signatures as `RealtimeChannel#subscribe` (`RTL7`), except that the `name` event-name argument is here called `type`
- `(RTAN4b)` When the library receives a `ProtocolMessage` with an action of `ANNOTATION`, every member of the `annotations` array (decoded into a `Annotation` objects) should be delivered to registered listeners
- `(RTAN4c)` Analagously to `name`-filtering with `RealtimeChannel#subscribe`, if the user subscribes with a `type` (or array of `type`s) the SDK must deliver only annotations whose `type` field exactly equals the requested `type`
- `(RTAN4d)` Has the same connection and channel state preconditions and return value as `RealtimeChannel#subscribe`, including implicitly attaching unless the user requests otherwise per `RTL7g`/@RTL7h@
- `(RTAN4d)` Has the same connection and channel state preconditions and return value as `RealtimeChannel#subscribe`, including implicitly attaching unless the user requests otherwise per `RTL7g`/`RTL7h`
- `(RTAN4e)` Has one additional channel state condition: once the channel is in the `attached` state, the `RTL4m` channel modes are checked for the presence of the `ANNOTATION_SUBSCRIBE` mode. (Note: the thing being checked is the mode set actually granted, according to the server, not the set of modes requested by the user per `TB2d`). If this mode is missing, the library should log a warning indicating that the user has tried to add an annotation listener without having requested the `ANNOTATION_SUBSCRIBE` channel mode in ChannelOptions, which will not work
- `(RTAN4e1)` This check does not apply if `attachOnSubscribe` has been set to `false` and the channel is not attached
- `(RTAN5)` `RealtimeAnnotations#unsubscribe` function:
Expand Down Expand Up @@ -1748,7 +1748,7 @@ The core SDK provides an API for wrapper SDKs to supply Ably with analytics info
- `(CHO1)` Is a type that contain channel metrics
- `(CH02)` This clause has been renamed to #CHO2.
- `(CHO2)` The attributes of `ChannelOccupancy` consist of:
- `(CHO2a)`metrics@ `ChannelMetrics`
- `(CHO2a)` metrics `ChannelMetrics`

#### ChannelMetrics

Expand Down Expand Up @@ -1870,7 +1870,7 @@ The core SDK provides an API for wrapper SDKs to supply Ably with analytics info
- `(TO3a)` `clientId` string - the id of the client represented by this instance
- `(TO3b)` `logLevel` - controls the level of verbosity of log messages from the library. The implementation of this is likely to vary by platform
- `(TO3c)` `logHandler` - allows the client to intercept log messages and handle them in a client-specific way. The implementation of this is likely to vary by platform
- `(TO3m)` `logExceptionReportingUrl` (deprecated) - defaults to a string value for an Ably error reporting DSN (Data Source Name), which is typically a URL in the format `<code>`{=html}https://\[KEY\]:\[SECRET\]`errors.ably.io/[ID]</code>. When set to `null`, `false@ or an empty string (depending on what is idiomatic for the platform), exception reporting is disabled
- `(TO3m)` `logExceptionReportingUrl` (deprecated) - defaults to a string value for an Ably error reporting DSN (Data Source Name), which is typically a URL in the format `https://\[KEY\]:\[SECRET\]errors.ably.io/[ID]`. When set to `null`, `false` or an empty string (depending on what is idiomatic for the platform), exception reporting is disabled
- `(TO3d)` `tls` boolean - defaults to true. If false, will not use TLS for all connections
- `(TO3e)` `autoConnect` boolean - defaults to true. If false, suppresses the automatic initiation of a connection when the library is instantiated
- `(TO3f)` `useBinaryProtocol` boolean - defaults to true. If false, forces the library to use the JSON encoding for REST and Realtime operations, instead of the default binary msgpack encoding
Expand Down
Loading