Skip to content

Commit ba47326

Browse files
ttypicclaude
andcommitted
Replace environment, restHost and realtimeHost with endpoint
2.0 adopts the REC1/REC2 host model (ADR-119): a single ClientOptions.endpoint selects where both REST requests and the realtime connection go, and the legacy environment, restHost and realtimeHost options are removed outright, so old code fails to compile rather than silently connecting to production. - endpoint resolves as: unset -> main.realtime.ably.net; a routing policy name -> [name].realtime.ably.net; nonprod:[name] -> [name].realtime.ably-nonprod.net; a hostname (contains '.' or '::', or is localhost) -> used as given. Default fallbacks follow the endpoint ([name].[a-e].fallback.ably-realtime[-nonprod].com) and a hostname has none. - Hosts now resolves from ClientOptions alone, so HttpCore and ConnectionManager share one primary domain. The restHost/environment conflict check, the rest.ably.io/realtime.ably.io defaults and the <env>-[a-e]-fallback hosts go with the legacy options. - An explicit fallbackHosts always replaces the defaults (REC2a2), and a custom port or tlsPort no longer suppresses the default fallbacks, as the spec has no such rule. - The server and device builders swap restHost(), realtimeHost() and environment() for endpoint(). The tests move to endpoint throughout: ABLY_ENV, ABLY_REST_HOST and ABLY_REALTIME_HOST become ABLY_ENDPOINT (default nonprod:sandbox), UTS and LiveObjects sandbox clients use the new SandboxApp.sandboxEndpoint, and mock/proxy clients use a localhost endpoint. Tests of the legacy host derivation and option conflicts are replaced by DefaultsTest/HostsTest cases for each endpoint form, custom fallbackHosts, and ports no longer disabling fallbacks. UPGRADING.md gains the migration table and the firewall allowlist note. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent 9632d59 commit ba47326

50 files changed

Lines changed: 468 additions & 448 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/skills/uts-to-kotlin/SKILL.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -676,13 +676,12 @@ Recognise a **proxy** spec by a reference to `create_proxy_session()`, proxy `ru
676676

677677
A **direct-sandbox** spec (no `create_proxy_session`, no rules — just happy-path interop against `nonprod:sandbox`) uses the same `SandboxApp` provisioning and the same `runTest` / `@BeforeAll`+`runBlocking` lifecycle as a proxy test, but **drops all proxy wiring**: no `ProxyManager.ensureProxy()`, no `ProxySession`, no `connectThroughProxy`. The client connects straight to the sandbox host. `ChannelHistoryTest` (realtime) and `ObjectsLifecycleTest` (liveobjects) are the reference examples — read one before translating a direct-sandbox spec.
678678

679-
**Client wiring** — point both transports at the sandbox host (explicit hosts auto-disable fallback hosts, so no `fallbackHosts`):
679+
**Client wiring** — point the client at the sandbox endpoint:
680680

681681
```kotlin
682682
private fun newClient(useBinaryProtocol: Boolean): AblyRealtime = TestRealtimeClient {
683683
key = app.defaultKey
684-
realtimeHost = SandboxApp.sandboxHost // sandbox.realtime.ably-nonprod.net
685-
restHost = SandboxApp.sandboxHost
684+
endpoint = SandboxApp.sandboxEndpoint // nonprod:sandbox
686685
this.useBinaryProtocol = useBinaryProtocol
687686
autoConnect = false
688687
}
@@ -728,7 +727,7 @@ Three helpers live under `uts/src/main/kotlin/io/ably/lib/uts/infra/integration/
728727

729728
- **`ProxyManager`** (`infra/integration/proxy/ProxyManager.kt`, package `io.ably.lib.uts.infra.integration.proxy`) — downloads/starts the shared `uts-proxy` process. Call `ProxyManager.ensureProxy()` once per suite in setup.
730729
- **`ProxySession`** (`infra/integration/proxy/ProxySession.kt`, same package) — one programmable session wrapping the proxy control API; also defines the `connectThroughProxy` extension and the rule-builder helpers.
731-
- **`SandboxApp`** (`infra/integration/SandboxApp.kt`, package `io.ably.lib.uts.infra.integration`) — provisions/deletes a sandbox test app from the shared `test-app-setup.json` in ably-common. `SandboxApp.create()` returns a `SandboxApp` with `appId`, `defaultKey`, and `keys` (`defaultKey` is a full-capability `appId.keyId:keySecret`); `app.delete()` tears it down. Provision in suite setup, delete in teardown. Also owns the single upstream sandbox host constant `SandboxApp.sandboxHost` (`sandbox.realtime.ably-nonprod.net`, the resolved `nonprod:sandbox` endpoint) — the default target of every `ProxySession` (both `realtimeHost` and `restHost`), and what direct-sandbox clients set `realtimeHost` / `restHost` from.
730+
- **`SandboxApp`** (`infra/integration/SandboxApp.kt`, package `io.ably.lib.uts.infra.integration`) — provisions/deletes a sandbox test app from the shared `test-app-setup.json` in ably-common. `SandboxApp.create()` returns a `SandboxApp` with `appId`, `defaultKey`, and `keys` (`defaultKey` is a full-capability `appId.keyId:keySecret`); `app.delete()` tears it down. Provision in suite setup, delete in teardown. Also owns `SandboxApp.sandboxEndpoint` (`nonprod:sandbox`), which direct-sandbox clients set as their `endpoint`, and `SandboxApp.sandboxHost` (`sandbox.realtime.ably-nonprod.net`, the hostname that endpoint resolves to) — the default upstream target of every `ProxySession`.
732731

733732
Import what the tier needs: a **direct-sandbox** test imports `io.ably.lib.uts.infra.integration.SandboxApp` plus `io.ably.lib.uts.infra.unit.TestRealtimeClient` and `io.ably.lib.uts.infra.{awaitState, pollUntil}`; a **proxy** test additionally imports `io.ably.lib.uts.infra.integration.proxy.{ProxyManager, ProxySession, connectThroughProxy}`.
734733

@@ -799,11 +798,11 @@ val client = TestRealtimeClient {
799798
}
800799
```
801800

802-
ably-java has **no `endpoint` ClientOptions field**; `connectThroughProxy` sets the discrete host fields for you:
801+
`connectThroughProxy` sets the proxy-def options for you:
803802

804803
| Proxy-def option | What `connectThroughProxy` sets |
805804
|---|---|
806-
| `endpoint: "localhost"` | `realtimeHost` **and** `restHost` = `session.proxyHost` (`"localhost"`) |
805+
| `endpoint: "localhost"` | `endpoint = session.proxyHost` (`"localhost"`) |
807806
| `port: proxy_port` | `port = session.proxyPort` |
808807
| `tls: false` | `tls = false` |
809808
| `useBinaryProtocol: false` | already the `ClientOptionsBuilder` default — left untouched |

‎.claude/skills/uts-to-kotlin/references/objects-mapping.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -623,10 +623,9 @@ REST provisioning" convention survives even though the module's internals are vi
623623
> envelope on the legacy `sandbox-rest.ably.io` host; both were aligned upstream — to this V2 shape and to
624624
> the canonical nonprod sandbox host `sandbox.realtime.ably-nonprod.net` — in ably/specification#497.
625625
>
626-
> **Sandbox host.** `provisionObjectsViaRest` sets `restHost = SandboxApp.sandboxHost`
627-
> (`sandbox.realtime.ably-nonprod.net`) — the same nonprod host `SandboxApp` and the realtime clients use,
628-
> **not** `environment="sandbox"` (which resolves to the legacy `sandbox-rest.ably.io`, and
629-
> can't be combined with `restHost` per `Hosts.java` TO3k2/TO3k3). The REST call hits the live sandbox
626+
> **Sandbox host.** `provisionObjectsViaRest` sets `endpoint = SandboxApp.sandboxEndpoint`
627+
> (`nonprod:sandbox`, resolving to `sandbox.realtime.ably-nonprod.net`) — the same endpoint `SandboxApp`
628+
> and the realtime clients use. The REST call hits the live sandbox
630629
> today, and the realtime client observes the provisioned data through the SDK's OBJECT_SYNC +
631630
> `RealtimeObject.get()` (both implemented).
632631

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -190,11 +190,11 @@ for the JRE-specific library:
190190

191191
./gradlew core:testRealtimeSuite
192192

193-
To run tests against a specific host, specify in the environment:
193+
To run tests against a specific endpoint, specify it in the environment:
194194

195-
env ABLY_ENV=staging ./gradlew testRealtimeSuite
195+
env ABLY_ENDPOINT=nonprod:staging ./gradlew testRealtimeSuite
196196

197-
Tests will run against the sandbox environment by default.
197+
Tests will run against the `nonprod:sandbox` endpoint by default.
198198

199199
Tests can be run on the Android-specific library. An Android device must be connected,
200200
either a real device or the Android emulator.

‎UPGRADING.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,3 +149,53 @@ find src -name '*.java' -o -name '*.kt' | xargs sed -i \
149149
| `TokenDetails.fromJSON(…)`, `TokenRequest.fromJSON(…)` | `fromJsonElement(…)` |
150150
| `ClientOptions.fallbackHostsUseDefault` | Drop it. Default fallback hosts apply automatically; set `fallbackHosts` only for custom hosts. |
151151
| `RegistrationToken.Type.GCM` (Android) | `RegistrationToken.Type.FCM` |
152+
153+
## 5. Choose the host with `endpoint`
154+
155+
2.0 replaces `ClientOptions.environment`, `restHost` and `realtimeHost` with a single
156+
`ClientOptions.endpoint` option, and the builder methods `environment(…)`, `restHost(…)` and
157+
`realtimeHost(…)` with `endpoint(…)`. REST requests and the realtime connection now always use the
158+
same host.
159+
160+
| 1.x | 2.0 |
161+
|-----|-----|
162+
| No host options | No change; traffic moves to `main.realtime.ably.net` (see below) |
163+
| `environment = "sandbox"` | `endpoint = "nonprod:sandbox"` |
164+
| `environment = "acme"` (dedicated cluster) | `endpoint = "acme"` |
165+
| `restHost` / `realtimeHost = "localhost"` | `endpoint = "localhost"` |
166+
| `restHost` and `realtimeHost` set to the same custom host | `endpoint = "<that host>"` |
167+
| `restHost` and `realtimeHost` set to different hosts | Not supported; use one host that serves both, or contact Ably |
168+
| Custom `fallbackHosts` | Unchanged |
169+
170+
How `endpoint` resolves:
171+
172+
| `endpoint` | Primary host | Default fallback hosts |
173+
|------------|--------------|------------------------|
174+
| Unset | `main.realtime.ably.net` | `main.[a-e].fallback.ably-realtime.com` |
175+
| A routing policy name, e.g. `acme` | `acme.realtime.ably.net` | `acme.[a-e].fallback.ably-realtime.com` |
176+
| `nonprod:` plus a name, e.g. `nonprod:sandbox` | `sandbox.realtime.ably-nonprod.net` | `sandbox.[a-e].fallback.ably-realtime-nonprod.com` |
177+
| A hostname (contains `.` or `::`, or is `localhost`) | The value as given | None |
178+
179+
An explicit `fallbackHosts` always replaces the default fallback hosts. A custom `port` or `tlsPort`
180+
no longer disables the default fallback hosts.
181+
182+
**Before (1.x):**
183+
184+
```java
185+
ClientOptions options = new ClientOptions("xVLyHw.MHOCLg:...");
186+
options.environment = "sandbox";
187+
AblyRealtime realtime = new AblyRealtime(options);
188+
```
189+
190+
**After (2.0):**
191+
192+
```java
193+
PubSubRealtimeClient realtime = PubSubServer.realtimeClientBuilder()
194+
.key("xVLyHw.MHOCLg:...")
195+
.endpoint("nonprod:sandbox")
196+
.build();
197+
```
198+
199+
**Firewalls and proxies.** 1.x connected to `rest.ably.io`, `realtime.ably.io` and
200+
`[a-e].ably-realtime.com` by default. If your network restricts outbound traffic, allow
201+
`*.realtime.ably.net` and `*.fallback.ably-realtime.com` before upgrading.

‎core-android/src/androidTest/java/io/ably/pubsub/test/android/AndroidSuite.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ public void android_http_header_test() {
5656
ClientOptions opts = new ClientOptions(testVars.keys[0].keyStr);
5757
opts.tls = false;
5858
opts.port = server.getListeningPort();
59-
opts.restHost = "localhost";
59+
opts.endpoint = "localhost";
6060
PubSubHttpClient ably = HttpClientFactory.create(opts);
6161

6262
ably.time();

‎core-android/src/main/java/io/ably/pubsub/push/ActivationContext.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ PubSubHttpClient getAbly() throws AblyException {
7777
throw AblyException.fromErrorInfo(new ErrorInfo("Unable to get Ably library instance; no device identity token", 400, 40000));
7878
}
7979
Log.v(TAG, "getAbly(): returning Ably instance using deviceIdentityToken");
80-
// TODO: We need to persist Ably client options such as the environment with `deviceIdentityToken` and use these options during initialization.
80+
// TODO: We need to persist Ably client options such as the endpoint with `deviceIdentityToken` and use these options during initialization.
8181
return (ably = HttpClientFactory.create(new ClientOptions(deviceIdentityToken)));
8282
}
8383

‎device/src/commonMain/kotlin/io/ably/pubsub/device/PubSubDevice.kt‎

Lines changed: 3 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -193,12 +193,12 @@ public object PubSubDevice {
193193
public fun headers(headers: Map<String, String>): ClientBuilder = apply { options.headers = headers }
194194

195195
/**
196-
* Sets [ClientOptions.restHost].
196+
* Sets [ClientOptions.endpoint].
197197
*
198-
* @param restHost the value to set.
198+
* @param endpoint the value to set.
199199
* @return this builder.
200200
*/
201-
public fun restHost(restHost: String): ClientBuilder = apply { options.restHost = restHost }
201+
public fun endpoint(endpoint: String): ClientBuilder = apply { options.endpoint = endpoint }
202202

203203
/**
204204
* Sets [ClientOptions.port].
@@ -232,14 +232,6 @@ public object PubSubDevice {
232232
*/
233233
public fun proxy(proxy: ProxyOptions): ClientBuilder = apply { options.proxy = proxy }
234234

235-
/**
236-
* Sets [ClientOptions.environment].
237-
*
238-
* @param environment the value to set.
239-
* @return this builder.
240-
*/
241-
public fun environment(environment: String): ClientBuilder = apply { options.environment = environment }
242-
243235
/**
244236
* Sets [ClientOptions.idempotentRestPublishing].
245237
*
@@ -344,14 +336,6 @@ public object PubSubDevice {
344336
*/
345337
public fun agents(agents: Map<String, String?>): ClientBuilder = apply { options.agents = agents }
346338

347-
/**
348-
* Sets [ClientOptions.realtimeHost].
349-
*
350-
* @param realtimeHost the value to set.
351-
* @return this builder.
352-
*/
353-
public fun realtimeHost(realtimeHost: String): ClientBuilder = apply { options.realtimeHost = realtimeHost }
354-
355339
/**
356340
* Sets [ClientOptions.autoConnect].
357341
*

‎examples/src/main/kotlin/com/ably/example/MainActivity.kt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,13 +27,13 @@ class MainActivity : ComponentActivity() {
2727
// A throwaway client that only signs a token; it never connects.
2828
PubSubDevice.clientBuilder()
2929
.key(apiKey)
30-
.environment("sandbox")
30+
.endpoint("nonprod:sandbox")
3131
.autoConnect(false)
3232
.build()
3333
.use { it.auth.requestToken(null, null) }
3434
}
3535
)
36-
environment("sandbox")
36+
endpoint("nonprod:sandbox")
3737
} else {
3838
key(BuildConfig.ABLY_KEY)
3939
}

‎examples/src/main/kotlin/com/ably/example/screen/MainScreen.kt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ import io.ably.pubsub.realtime.PubSubRealtimeClient
1414
@Composable
1515
fun MainScreen(realtimeClient: PubSubRealtimeClient) {
1616
var selectedTab by remember { mutableIntStateOf(0) }
17-
val isSandbox = realtimeClient.options.environment == "sandbox"
17+
val isSandbox = realtimeClient.options.endpoint == "nonprod:sandbox"
1818

1919
val tabs = listOf(
2020
TabItem("Color Voting", Icons.Default.Favorite),

‎lib/src/main/java/io/ably/pubsub/debug/DebugOptions.java‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,7 @@ public DebugOptions copy() {
5050
copied.logLevel = logLevel;
5151
copied.logHandler = logHandler;
5252
copied.tls = tls;
53-
copied.restHost = restHost;
54-
copied.realtimeHost = realtimeHost;
53+
copied.endpoint = endpoint;
5554
copied.port = port;
5655
copied.tlsPort = tlsPort;
5756
copied.autoConnect = autoConnect;
@@ -60,7 +59,6 @@ public DebugOptions copy() {
6059
copied.echoMessages = echoMessages;
6160
copied.recover = recover;
6261
copied.proxy = proxy;
63-
copied.environment = environment;
6462
copied.idempotentRestPublishing = idempotentRestPublishing;
6563
copied.httpOpenTimeout = httpOpenTimeout;
6664
copied.httpRequestTimeout = httpRequestTimeout;

0 commit comments

Comments
 (0)