ably-cocoa [ECO-5551] Use endpoint as default connection option (ADR-119)

Summary by CodeRabbit

New Features
- Added endpoint-based configuration with derived primary domain and fallback domains.
- Exposed connectivity check URL and agent identifier utilities; surfaced library/platform metadata.
- Added public defaults helpers for domains, versions, ports, TTLs, and timeouts.
Deprecations
- Deprecated environment, restHost, and realtimeHost in favor of endpoint.
Breaking Changes
- Host resolution and fallback behavior now driven by endpoint/domains; defaults target main.realtime.ably.net and ably.com where applicable.
Tests
- Updated test suite to endpoint-driven domains and new defaults.
Chores
- CI integration tests target nonprod:sandbox; Ruby toolchain set to 3.3.9.

Sep 11 '25 21:09 maratal

Walkthrough

Replaces ARTFallbackHosts with a new ARTDomainSelector; introduces endpoint and connectivityCheckUrl options on ARTClientOptions; routes REST/Realtime/WebSocket host resolution and fallback logic through ARTDomainSelector; updates tests, project/module maps, CI, and scripts to endpoint/primaryDomain semantics.

Changes

Cohort / File(s)	Summary
Domain selector & new class `Source/ARTDomainSelector.h`, `Source/ARTDomainSelector.m`, `Source/PrivateHeaders/Ably/ARTDomainSelector.h`	New ARTDomainSelector class and private header: parses endpoint/environment/rest/realtime/fallback options and exposes `primaryDomain`, `fallbackDomains`, `defaultFallbackDomains`.
Client options & private API `Source/ARTClientOptions.m`, `Source/include/Ably/ARTClientOptions.h`, `Source/PrivateHeaders/Ably/ARTClientOptions+Private.h`	Adds public `endpoint` and `connectivityCheckUrl`; integrates ARTDomainSelector; adds domain-derived accessors (primaryDomain, fallbackDomains), deprecates legacy environment/restHost/realtimeHost usage, adds setDefaultEndpoint:, and enforces mutual-exclusion with legacy options.
Defaults & connectivity `Source/ARTDefault.m`, `Source/PrivateHeaders/Ably/ARTDefault+Private.h`, `Source/include/Ably/ARTDefault.h`	Introduces ARTDefault connectivity constants and connectivityCheckUrl; moves rest/realtime/fallback resolution toward DomainSelector-driven logic and exposes fallback APIs and setters.
Removed legacy fallback `Source/ARTFallbackHosts.m`, `Source/PrivateHeaders/Ably/ARTFallbackHosts.h`	Removes ARTFallbackHosts implementation and header; fallback derivation migrated into ARTDomainSelector.
Runtime clients & transport updates `Source/ARTRealtime.m`, `Source/ARTRest.m`, `Source/ARTWebSocketTransport.m`, `Source/ARTConnection.m`	Shift fallback resolution to `options.domainSelector.fallbackDomains`; simplify retry/fallback checks; ARTRest uses configurable connectivityCheckUrl and adds `+deviceAccessQueue`; WebSocket transport introduces internal host backing field initialized from domainSelector.primaryDomain; connection maxMessageSize uses ARTDefault constant.
Build & module updates `Ably.xcodeproj/project.pbxproj`, `Source/Ably.modulemap`, `Source/include/module.modulemap`	Adds ARTDomainSelector.m/.h to project and module maps; removes ARTFallbackHosts references from project and module maps.
Tests & utilities `Test/AblyTests/**`, `Examples/Tests/TestsTests/TestsTests.swift`, `Test/AblyTests/Test Utilities/TestUtilities.swift`, `Test/AblyTests/Tests/ARTDomainSelectorTests.swift`	Tests and helpers updated to use `endpoint`/`primaryDomain`; added comprehensive ARTDomainSelectorTests; updated many test expectations and deprecation annotations; sandbox endpoint set to `nonprod:sandbox`.
CI & scripts `.github/workflows/integration-test.yaml`, `Scripts/log-environment-information.sh`	CI ABLY_ENV changed to `nonprod:sandbox`; scripts updated to reference `sandbox.realtime.ably-nonprod.net`.
Project file entries (repeat) `Ably.xcodeproj/project.pbxproj`	Adds ARTDomainSelector.m/.h to build graph and removes ARTFallbackHosts.m/.h references.

sequenceDiagram
    participant Client as Client / Tests
    participant Options as ARTClientOptions
    participant Selector as ARTDomainSelector
    participant Rest as ARTRest
    participant Realtime as ARTRealtime

    Note over Client,Options: Client configures options (endpoint or legacy fields)
    Client->>Options: set endpoint / restHost / realtimeHost / fallbackHosts
    Options->>Selector: initWithEndpointClientOption(..., fallbackHostsUseDefault: ...)
    Selector-->>Options: primaryDomain / fallbackDomains

    Client->>Rest: REST request (host = selector.primaryDomain)
    Rest->>Selector: on failure check fallbackDomains
    alt fallback available
      Rest->>Rest: switch host -> next fallback and retry
      Rest->>Client: return retry result
    else no fallback
      Rest->>Client: report no-fallback error
    end

    Client->>Realtime: open realtime (host = selector.primaryDomain)
    Realtime->>Selector: on transport failure get fallbackDomains
    Realtime->>Realtime: reconnect using fallback hosts

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45–75 minutes

Areas needing careful review:
- Source/ARTDomainSelector.m — parsing rules, routing-policy edge cases, fallback generation and priority.
- Source/ARTClientOptions.m — mutual-exclusion enforcement, domainSelector lifecycle, copy semantics.
- Source/ARTRest.m and Source/ARTRealtime.m — host switching, fallback iteration, connectivityCheckUrl behavior and device access queue.
- Tests (Test/AblyTests/**) — broad expectation changes and new ARTDomainSelectorTests.
- Project/module updates (Ably.xcodeproj/project.pbxproj, module maps) — ensure headers/sources are correctly registered.

Poem

🐰 I hopped through endpoints and sniffed the code,

Policy names and hosts in a tidy row.
Five fallback doors that spin when storms blow,
Old names tucked gently under new nets grown,
nonprod:sandbox — a cheerful hop back home.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 63.33% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'ECO-5551 Use endpoint as default connection option (ADR-119)' directly summarizes the main change: implementing endpoint as the default connection option per ADR-119, which aligns with the PR's primary objective.
Linked Issues check	✅ Passed	The PR comprehensively implements all core coding requirements from #2098/ECO-5551: adds endpoint option accepting routing policy names and FQDNs, enforces incompatibility with legacy options, creates ARTDomainSelector for domain resolution per ADR-119 spec, maintains legacy option compatibility, and switches to ably.net domain by default.
Out of Scope Changes check	✅ Passed	All changes are within scope of ADR-119 implementation. Workflow updates reflect endpoint changes, test updates validate new functionality, and infrastructure changes (modulemap, build files) support the new ARTDomainSelector class. Script update aligns with new domain names.

✨ Finishing touches

🧪 Generate unit tests (beta)

[ ] Create PR with unit tests
[ ] Post copyable unit tests in a comment
[ ] Commit unit tests in branch 2098-ADR-119

[!WARNING]

Review ran into problems

🔥 Problems

Errors were encountered while retrieving linked issues.

Errors (1)

ADR-119: Request failed with status code 404

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Sep 11 '25 21:09 coderabbitai[bot]

@maratal please could you tidy up the commits here? Also it would be great if we could isolate most of this domain selection logic to a new class instead of having to further complicate our existing classes. See e.g. how WIP ably-swift does it: https://github.com/ably/ably-swift/blob/main/Sources/Ably/Options/DomainSelectionPolicy.swift (the ably-cocoa equivalent would be more complicated because you have to handle some deprecated client options too)

Nov 06 '25 13:11 lawrence-forooghian

The log-environment-information.sh script needs updating for the new sandbox domain name.

Nov 26 '25 12:11 lawrence-forooghian

Also there's a compilation failure in the "Examples Test" CI job.

Nov 26 '25 12:11 lawrence-forooghian