spec: Add spec items for environment fallback hosts #965
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: Lewis Marshall <lewis@lmars.net>
mattheworiordan
temporarily deployed
to
ably-docs-environment-f-8q7hha
paddybyers
reviewed
Sep 11, 2020
| * @(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 below only applies when the default @rest.ably.io@ endpoint is being used and has not been overriden (see "RSC11":#RSC11), @ClientOptions#fallbackHostsUseDefault@ is @true@, or an array of @ClientOptions#fallbackHosts@ is provided. If host fallback is not supported, failing HTTP requests that would have "qualified for a retry against a fallback host (see RSC15d)":#RSC15d, will instead result in an error immediately | ||
| ** @(RSC15b)@ The fallback behavior described below only applies when either @ClientOptions#restHost@ has not been set to an explicit value (see "RSC11a":#RSC11a), the deprecated @ClientOptions#fallbackHostsUseDefault@ option is set to @true@, or an array of @ClientOptions#fallbackHosts@ is provided. If host fallback is not supported, failing HTTP requests that would have "qualified for a retry against a fallback host (see RSC15d)":#RSC15d, will instead result in an error immediately |
There was a problem hiding this comment.
"is not supported" -> "does not apply" ?
| ** @(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 (with a matching Host header as this is necessary when fallbacks are proxied through a CDN) 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. The five default fallback hosts are @[a-e].ably-realtime.com@. If an array of custom fallback hosts are provided in @ClientOptions#fallbackHosts@, then they will be used instead. If an empty array of fallback hosts is provided, then fallback host functionality is disabled | ||
| ** @(RSC15a)@ In the case of an error necessitating use of an alternative host (see "RSC15d":#RSC15d), try fallback hosts (with a matching Host header as this is necessary when fallbacks are proxied through a CDN) 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 |
There was a problem hiding this comment.
I know that this text was already there, but do we really need to say that you include a host header for a given target? Or if it does need to be said, maybe it is stated as a standalone requirement somewhere?
There was a problem hiding this comment.
I'm going off the assumption that it was added for a reason, and I don't think it does any harm do be explicit, so I've moved it out into RSC15j in 482fba5.
| ** @(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 (with a matching Host header as this is necessary when fallbacks are proxied through a CDN) 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. The five default fallback hosts are @[a-e].ably-realtime.com@. If an array of custom fallback hosts are provided in @ClientOptions#fallbackHosts@, then they will be used instead. If an empty array of fallback hosts is provided, then fallback host functionality is disabled | ||
| ** @(RSC15a)@ In the case of an error necessitating use of an alternative host (see "RSC15d":#RSC15d), try fallback hosts (with a matching Host header as this is necessary when fallbacks are proxied through a CDN) 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)@ Fallback hosts are chosen as follows: |
There was a problem hiding this comment.
Maybe ftaod this should state explicitly "When the use of fallbacks applies, the set of fallback hosts is chosen ...".
There was a problem hiding this comment.
Yes I think that's better, updated in 24ddec3
| ** @(RSC15g)@ Fallback hosts are 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 @ClientOptions#fallbackHosts@ and @ClientOptions#environment@ are not set, use the default fallback hosts (see "RSC15h":#RSC15h) |
| ** @(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 all fallback hosts to find an alternative healthy datacenter. The five default fallback hosts are @[a-e].ably-realtime.com@ and should be attempted in random order. The connection requests must include a matching Host header as this is necessary when fallbacks are proxied through a CDN. See "RSC15a":#RSC15a for details on how custom fallback hosts are specified and used | ||
| ** @(RTN17b)@ The fallback behavior described below only applies when either @ClientOptions#realtimeHost@ has not been set to an explicit value (see "RTC1d":#RTC1d), the deprecated @ClientOptions#fallbackHostsUseDefault@ option is set to @true@, or an array of @ClientOptions#fallbackHosts@ is provided. | ||
| ** @(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 (with a matching Host header as this is necessary when fallbacks are proxied through a CDN) in random order to find an alternative healthy datacenter. Fallback hosts are chosen as per "RSC15g":#RSC15g |
There was a problem hiding this comment.
Same comment as above re Host header
Signed-off-by: Lewis Marshall <lewis@lmars.net>
Signed-off-by: Lewis Marshall <lewis@lmars.net>
Signed-off-by: Lewis Marshall <lewis@lmars.net>
mattheworiordan
temporarily deployed
to
ably-docs-environment-f-t9isli
lmars
added a commit
to ably/ably-js
that referenced
this pull request
Sep 12, 2020
As per `RSC15g` introduced in ably/docs#965 Signed-off-by: Lewis Marshall <lewis@lmars.net>
lmars
added a commit
to ably/ably-js
that referenced
this pull request
Sep 12, 2020
As per `RSC15g` introduced in ably/docs#965 Signed-off-by: Lewis Marshall <lewis@lmars.net>
SimonWoolf
approved these changes
Sep 14, 2020
This was referenced Sep 17, 2020
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This adds spec items describing how clients should generate fallback hosts when
ClientOptions#environmentis set (which take the form<environment>-[a-e]-fallback.ably-realtime.com).It also deprecates the
ClientOptions#fallbackHostsUseDefaultbecause it is unlikely that ifClientOptions#restHostorClientOptions#environmentare explicitly set that the default fallbacks should be used.Closes #818.