API spec: add zone option, and enable the client to determine fallback hosts based on environment #908
Conversation
…k hosts based on environment
paddybyers
force-pushed
the
feature/auto-fallbacks
branch
from
4d2929d to
9d0bd7d
Compare
|
@paddybyers is there somewhere I can see the docs rendered? |
@lmars it's linked above: https://ably-docs-feature-auto--j6jqid.herokuapp.com/client-lib-development-guide/features/ |
|
Ah thanks, I completely missed that 😐 |
| * @(RAS1)@ Clients access the Ably service via multiple endpoints. A set of "@ClientOptions@":#options are supported that allow users to specify non-default values for the hostnames for those endpoints. REST operations are performed against a primary REST host and, for realtime client, connections are made against a primary realtime host. | ||
| * @(RAS2)@ The primary REST host and primary realtime host are determined based on the supplied @ClientOptions@ as follows. | ||
| ** @(RAS2a)@ If the @ClientOptions#restHost@ option is set, the specified host is the primary REST host. It is not valid for @ClientOptions#restHost@ to be specified in conjunction with either a @ClientOptions#environment@ or @ClientOptions#zone@ option. | ||
| ** @(RAS2b)@ If the @ClientOptions#realHost@ option is set, the specified host is the primary realtime host. It is not valid for @ClientOptions#realHost@ to be specified in conjunction with either a @ClientOptions#environment@ or @ClientOptions#zone@ option. |
There was a problem hiding this comment.
ClientOptions#realHost
Is this an intentional change from the existing realtimeHost? (I'm guessing not since realtimeHost is used lower down)
| **** @(RAS2b2a)@ For a @zone@ value of @production@, an @environment@ value of @production@ corresponds to @rest@ and @realtime@ subdomains of the PD for the REST and realtime primary hosts respectively. That is, the primary hosts are @rest.ably.io@ and @realtime.ably.io@. | ||
| **** @(RAS2b2b)@ For a @zone@ value of @production@, any other @environment@ value corresponds to subdomains @<environment>-rest@ and @<environment>-realtime@ for REST and realtime hosts respectively. For example, an @environment@ value of @sandbox@ corresponds to primary hosts @sandbox-rest.ably.io@ and @sandbox-realtime.ably.io@. | ||
| **** @(RAS2b2c)@ For any other @zone@ value, both REST and realtime operations use the same primary host, in which the subdomain equals the @environment@. | ||
| ** @(RAS2c)@ The resulting value of the primary host is obtained by combining the PD and subdomains. For example, an @environment@ value of @sandbox@ and @zone@ value of @production@ corresponds to an host of @sandbox-rest.ably.io@. An @environment@ value of @loadtest@ and a @zone@ value of @dev@ corresponds to an host of @loadtest-rest.ably-dev.net@. |
There was a problem hiding this comment.
An @environment@ value of @loadtest@ and a @zone@ value of @dev@ corresponds to an host of @loadtest-rest.ably-dev.net@.
This contradicts RAS2b2c above, which has that "both REST and realtime operations use the same primary host, in which the subdomain equals the environment", which would imply loadtest.ably-dev.net not loadtest-rest.ably-dev.net
| * @(RAS3)@ Host Fallback | ||
| ** @(RAS3b)@ The client may be configured so as to be able to use alternative hosts ("fallback hosts") in the case that an operation attempted against the primary host fails. The client determines the set of fallback hosts as follows. | ||
| *** @(RAS3b1)@ If the @ClientOptions#fallbackHosts@ option is specified, then the fallback hosts are the value of that option. The expected value of @ClientOptions#fallbackHosts@ is an array of hostname strings. | ||
| *** @(RAS3b2)@ If the @ClientOptions#disableFallbackHosts@ option is @true@, or if the @ClientOptions#restHost@ option is specified, then the set of fallback hosts is empty. |
There was a problem hiding this comment.
if the ClientOptions#restHost option is specified, then the set of fallback hosts is empty.
This needs a "If fallbackHosts are not explicitly specified in clientOptions#fallbackHosts" or "unless RAS3b1 applies" qualification, or it sounds like it's saying that restHost should suppress even explicit fallbackHosts.
Actually -- all these RAS3bx's are semantically an else if cascade, which should be made clearer - spec items on the same level don't usually have semantically-meaningful ordering
| ** @(RAS2b)@ Otherwise, the primary hosts are determined by first determining values for @zone@ and @environment@ as follows. | ||
| *** @(RAS2b1)@ The value of @zone@ determines the principal domain (PD) of the primary hosts. If the @ClientOptions#zone@ option is set to the value @production@, or is unset, then the @zone@ is @production@. Otherwise, the value of @zone@ is the value of the @ClientOptions#zone@ option. | ||
| **** @(RAS2b1a)@ A @zone@ value of @production@ corresponds to a PD of @ably.io@. | ||
| **** @(RAS2b1b)@ A @zone@ value of @dev@ corresponds to a PD of @ably-dev.net@. |
There was a problem hiding this comment.
Is it an unneccessary complication in client libraries to have them understand zone as a concept? AIUI all the client library is doing with it is mapping it to a PD and a fallbackPD. Might it be simpler to just have clientOptions for primaryDomain and fallbackDomain, and assume the ones for production if those aren't specified? Given that the only users of the dev zone will be us. (Keep RAS2b2c for calculating the host when a custom domain is specified).
|
@paddybyers @SimonWoolf - this one was a bit before my time - what needs to be done here to get this resolved, if anything? |
See internal discussion: https://ably.atlassian.net/browse/SEC-49