Use endpoint as default connection option (ADR-119)

[surminus]

This implements ADR-119[1], which specifies the client connection options to update requests to the endpoints implemented as part of ADR-042[2].

The endpoint may be one of the following:

• a routing policy name (such as main)
• a nonprod routing policy name (such as nonprod:sandbox)
• a FQDN such as foo.example.com

The endpoint option is not valid with any of environment, restHost or realtimeHost, but we still intend to support the legacy options.

If the client has been configured to use any of these legacy options, then they should continue to work in the same way, using the same primary and fallback hostnames.

If the client has not been explicitly configured, then the hostnames will change to the new ably.net domain when the package is upgraded.

Notes on implementation

This is still a work in progress, I'm opening a PR to allow tests to run.

I've tried to change as little as possible, but we already had a method named endpoint so I've switched that to uri (open to better naming suggestions).

I haven't yet added any explicit tests for using endpoint, and tried to limit changes to the existing to the updated hostname.

[1] https://ably.atlassian.net/wiki/spaces/ENG/pages/3428810778/ADR-119+ClientOptions+for+new+DNS+structure
[2] https://ably.atlassian.net/wiki/spaces/ENG/pages/1791754276/ADR-042+DNS+Restructure

[lawrence-forooghian]

Thanks @surminus! A few thoughts from an initial review:

• do you think you could split out the rename of the endpoint method into a separate, preceding commit? it would help with readability if the functional changes and the refactor were separate
• please could you add comments to mention the spec points (see Updates for ADR-119: updated ClientOptions for new domains specification#213) that the new code relates to?
• please could you add tests for the new functionality (i.e. for the endpoint client option), again with reference to the relevant spec points
• where spec points have been removed or replaced (e.g. RTN17b, a bunch under RSC15) please could you update the corresponding code and tests that make reference to these spec points?

[surminus]

@lawrence-forooghian thanks for the review, these all seem like good points, I will try to get to them in the next week or two!

[surminus]

@lawrence-forooghian I've broken out the commit for renaming the endpoint method.

RE: tests, even though in my initial comment I said I hadn't added tests, I do seem to have added a new context for using endpoint in the client initializer[1], is this sufficient? Or do we want to include new contexts everywhere we use an environment option? I think really they should just behave the same way so not sure if we're gaining much value from them.

I'm going to look at updating the spec references now.

[1]

ably-ruby/spec/shared/client_initializer_behaviour.rb

Lines 269 to 312 in f8eba18

	context 'endpoint' do
	context 'when set without custom fallback hosts configured' do
	let(:endpoint) { 'foo' }
	let(:client_options) { default_options.merge(endpoint: endpoint) }
	let(:default_fallbacks) { %w(a b c d e).map { |id| "#{endpoint}.#{id}.fallback.ably-realtime.com" } }
	it 'sets the endpoint attribute' do
	expect(subject.endpoint).to eql(endpoint)
	end
	it 'uses the default fallback hosts (#TBC, see https://github.com/ably/wiki/issues/361)' do
	expect(subject.fallback_hosts.sort).to eql(default_fallbacks)
	end
	end
	context 'when set with custom fallback hosts configured' do
	let(:endpoint) { 'foo' }
	let(:custom_fallbacks) { %w(a b c).map { |id| "#{endpoint}-#{id}.foo.com" } }
	let(:client_options) { default_options.merge(endpoint: endpoint, fallback_hosts: custom_fallbacks) }
	it 'sets the endpoint attribute' do
	expect(subject.endpoint).to eql(endpoint)
	end
	it 'uses the custom provided fallback hosts (#RSC15a)' do
	expect(subject.fallback_hosts.sort).to eql(custom_fallbacks)
	end
	end
	context 'when set with fallback_hosts_use_default' do
	let(:endpoint) { 'foo' }
	let(:custom_fallbacks) { %w(a b c).map { |id| "#{endpoint}-#{id}.foo.com" } }
	let(:default_production_fallbacks) { %w(a b c d e).map { |id| "main.#{id}.fallback.ably-realtime.com" } }
	let(:client_options) { default_options.merge(endpoint: endpoint, fallback_hosts_use_default: true) }
	it 'sets the endpoint attribute' do
	expect(subject.endpoint).to eql(endpoint)
	end
	it 'uses the production default fallback hosts (#RTN17b)' do
	expect(subject.fallback_hosts.sort).to eql(default_production_fallbacks)
	end
	end
	end

[surminus]

@lawrence-forooghian I've updated the specs where they seem relevant, but there weren't actually that many references? It seemed a little inconsistent in the way they were applied. Do I need to also update SPEC.md?

[lawrence-forooghian]

@surminus as discussed on Slack, please could you make sure that this PR implements / tests the updates to REC1b2 from ably/specification#302? Thanks!

[surminus]

@lawrence-forooghian I've updated the tests and added appropriate annotations