pubsub: breaking changes to timing option names and units

.claude/skills/uts-to-python/SKILL.md

@@ -603,7 +603,7 @@ from CONNECTED (`loop.call_soon`, not a timer), so DISCONNECTED is gone before t
 `await` returns and `await_connection_state(client, DISCONNECTED)` times out. Record
 the sequence with `connection.on(...)` and assert on the list, as `mock_websocket.md`
 says. To *rest* in DISCONNECTED, use `drop_transport(...)`, or fail the immediate retry
-and raise `disconnected_retry_timeout`.
+and raise `disconnected_retry_timeout_seconds`.
 
 **5. Deadlock: `await connection.once_async(SUSPENDED)` before calling `advance()`
 hangs forever** — nothing fires timers but `advance`. Record with `connection.on(...)`,
@@ -621,7 +621,7 @@ a small `maxIdleInterval` in `connected_message(...)`, on real time. For every *
 
 **7. `ping()`'s timeout is real loop time, not the seam.**
 `connectionmanager.py:375` is `asyncio.wait_for(pending_ping.future, timeout)`, so
-`advance()` will not move it. Use a short real `realtime_request_timeout`.
+`advance()` will not move it. Use a short real `realtime_request_timeout_seconds`.
 
 **8. `clock.settle()` is twenty event-loop yields, not true quiescence.** The
 disconnect path chains `create_task` several levels deep. If a derived test shows a
@@ -640,7 +640,7 @@ the attempt hangs until the transition timer fires with a generic 50003/504, and
 one leaks a `connect_base` task. `respond_with_dns_error()` is the only fast, caught
 failure — 40000/400 with the real cause — so **prefer it** whenever you just need "the
 connect failed", and note the substitution at the site. Keep
-`realtime_request_timeout` short in any test that does wait a refusal out.
+`realtime_request_timeout_seconds` short in any test that does wait a refusal out.
 
 **11. Keep the fallback hosts empty** unless the spec is about them.
 `check_connection()` is a module-level, **synchronous** `httpx.get` that no seam
@@ -699,7 +699,7 @@ failure; do not chase them.
 a bare `simulate_disconnect()` leaves the channel ATTACHED. And RTL4f's channel attach
 timeout and the connection's transition timeout are the **same option** (TO3l11), so a
 test that needs the connection to suspend before the channel does must set
-`realtime_request_timeout` very high.
+`realtime_request_timeout_seconds` very high.
 
 **21. `presence.subscribe()` and `annotations.subscribe()` are coroutines that
 attach.** They must be awaited, and they cannot run before `connect()`. `unsubscribe()`
@@ -755,7 +755,7 @@ Infrastructure Limitation. RTN23a via `send_to_client(HEARTBEAT_MESSAGE)` works.
   response processor decodes the body through `Response.to_native()`. A native dict or
   list body gets one automatically.
 - **The mock enforces the client's read timeout**, so `respond_with_delay` beyond
-  `http_request_timeout` raises rather than arriving late.
+  `http_request_timeout_seconds` raises rather than arriving late.
 - **Several client options are missing entirely** — `max_message_size` and
   `log_handler` among them — and raise `TypeError` rather than being ignored. Check
   `ably/types/options.py` first.
@@ -861,14 +861,13 @@ Established against the real proxy and the real sandbox while deriving
   same client adds its own `http_request` events. In `RSL1k4` the log is read
   **before** the history call, and the history read is a `wall_clock_poll_until` rather
   than a single fetch, because a published message does not reach history at once.
-- **`httpRequestTimeout` is milliseconds in the specification and seconds in
-  ably-python.** `ably/http/http.py:193` hands `(http_open_timeout,
-  http_request_timeout)` to `httpx`, which reads seconds, so the specification's
-  `http_request_timeout=3000` is a 3000-second deadline: measured, the request sat out
-  the proxy's whole 20-second delay and then succeeded on the primary host, and no
-  fallback was attempted. Passing `3` makes the same test pass in 3.1s, so only the
-  unit is wrong. The test is written as the specification has it and gated with
-  `@deviation`; `test/uts/deviations.md` carries the entry.
+- **`httpRequestTimeout` is milliseconds in the specification and
+  `http_request_timeout_seconds` is seconds in ably-python**, as are
+  `http_open_timeout_seconds` and `http_max_retry_duration_seconds`. Divide the
+  specification's value by 1000: passed undivided, `httpRequestTimeout: 3000` is a
+  3000-second deadline, and measured, the request sat out the proxy's whole 20-second
+  delay and then succeeded on the primary host with no fallback attempted. `3` makes
+  the same test pass in 3.1s.
 
 ## Traps found while deriving the realtime integration tier
 
@@ -896,10 +895,11 @@ Each was established against the sandbox, or against the sandbox behind `uts-pro
   `respond_with_refused`. The proxy answers the upgrade with HTTP 502, `websockets`
   raises, and the SDK reports `40000/400 'Error opening websocket connection: server
   rejected WebSocket connection: HTTP 502'` at once. No timeout shortening is needed.
-- **`realtime_request_timeout` is milliseconds at the client option**, and `Timer`
-  divides by 1000, so a specification's `realtimeRequestTimeout: 3000` maps straight
-  across. That is the opposite of `http_request_timeout`, which the REST proxy tier found
-  is applied as seconds; the defect does not generalise, so do not carry it over.
+- **The realtime timing options are seconds, and named `*_seconds`.** A specification's
+  `realtimeRequestTimeout: 3000` is `realtime_request_timeout_seconds=3`, and the same
+  division by 1000 applies to `disconnectedRetryTimeout`, `suspendedRetryTimeout` and
+  `channelRetryTimeout`. Only the options move: `ADVANCE_TIME`, `maxIdleInterval`,
+  `connectionStateTtl` and every `FakeClock` value stay milliseconds.
 - **The proxy's event timestamps are RFC 3339 with a variable number of fractional
   digits.** Comparing them as strings is wrong, and `datetime.fromisoformat` will not
   take the trailing `Z` on Python 3.9. Order the log by position rather than by timestamp
@@ -929,12 +929,14 @@ Three regimes; pick by tier.
 `rest_client(mock_http, clock=...)` replaces it: a stand-in supplies `now_ms()`,
 `monotonic_ms()` and `timer(timeout_ms, callback)`, and is where a spec's
 `enable_fake_timers()` / `ADVANCE_TIME(ms)` goes. Where a spec shortens an interval
-through a client option instead (`fallback_retry_timeout=100`), follow the spec.
+through a client option instead (`fallbackRetryTimeout: 100`, which is
+`fallback_retry_timeout_seconds=0.1`), follow the spec.
 
 **Realtime unit.** The same seam, with `realtime_client(mock, clock=clock)` installing a
 `FakeClock` on it. Still prefer a short real interval through a client option
-(`realtime_request_timeout`, `disconnected_retry_timeout`, `suspended_retry_timeout`,
-`channel_retry_timeout`) or through `connected_message(maxIdleInterval=...)`, and reach
+(`realtime_request_timeout_seconds`, `disconnected_retry_timeout_seconds`,
+`suspended_retry_timeout_seconds`, `channel_retry_timeout_seconds`, each the spec's
+milliseconds divided by 1000) or through `connected_message(maxIdleInterval=...)`, and reach
 for `FakeClock` where nothing else reaches the elapsing: `connection_state_ttl`, whose
 default costs 120 real seconds, and the transport's idle detection, which measures the
 silence against the same clock it arms its timer on. See the fake-time section of

CLAUDE.md

@@ -16,7 +16,11 @@ arithmetic on the unix epoch, are not clock readings and stay as they are.
 
 `asyncio.wait_for` in `ConnectionManager.ping` is the one delay that runs on the event
 loop's clock rather than this one; a test which waits it out sets a short real
-`realtime_request_timeout`.
+`realtime_request_timeout_seconds`.
+
+The timing client options are seconds, named `*_seconds`, where the clock counts
+milliseconds. `Options` converts them in one place, `seconds_to_ms`, behind a private
+`_<option>_ms` property for each, and code scheduling on the clock reads those.
 
 `Auth._timestamp` signs a token request the server validates, so a client which reads a
 fake clock talks to a mock rather than to the sandbox.

UPDATING.md

@@ -408,7 +408,9 @@ await pubsub_http_client.auth.request_token({'ttl': 600000, 'capability': capabi
 `http_open_timeout`, `http_request_timeout`, `http_max_retry_count` and
 `http_max_retry_duration` on `client.options` used to read `None` unless you set them, while
 the client applied defaults of its own. They now read back the values in effect: 4, 10, 3 and
-15 by default. The timeouts and the retry duration are still in seconds. Code that tested an
+15 by default. The timeouts and the retry duration are still in seconds, and are renamed
+`http_open_timeout_seconds`, `http_request_timeout_seconds` and
+`http_max_retry_duration_seconds`, as described below. Code that tested an
 option for `None`, to tell whether it had been set, will no longer find it so.
 
 ### Requests no longer take a `timeout` argument
@@ -427,21 +429,21 @@ await rest.time(timeout=5)
 
 Example 4.0.0 code:
 ```python
-pubsub_http_client = create_http_client(key='xxx', http_request_timeout=5)
+pubsub_http_client = create_http_client(key='xxx', http_request_timeout_seconds=5)
 await pubsub_http_client.time()
 ```
 
-### `http_request_timeout` bounds writes and connection-pool waits
+### `http_request_timeout_seconds` bounds writes and connection-pool waits
 
 In 3.x, `http_open_timeout` bounded connecting and `http_request_timeout` bounded each read
 of a response, while writing a request body and waiting for a free pooled connection had no
-timeout at all. `http_request_timeout` now bounds those too, so a request stuck writing to,
+timeout at all. `http_request_timeout_seconds` now bounds those too, so a request stuck writing to,
 or waiting for, a wedged connection raises `httpx.TimeoutException` and is retried against a
 fallback host instead of hanging. If you publish large bodies over a slow link, raise
-`http_request_timeout` to fit:
+`http_request_timeout_seconds` to fit:
 
 ```python
-pubsub_http_client = create_http_client(key='xxx', http_request_timeout=30)
+pubsub_http_client = create_http_client(key='xxx', http_request_timeout_seconds=30)
 ```
 
 ### `http_max_retry_count` counts fallback hosts only
@@ -773,7 +775,7 @@ except AblyException:
 
 `await connection.ping()` raised an `AblyException` with code 40000 at once when the connection
 was `DISCONNECTED`. In 4.0.0 it waits for the connection to reconnect, as it already did while
-`CONNECTING`, and then times out `realtime_request_timeout` after its heartbeat goes out. It
+`CONNECTING`, and then times out `realtime_request_timeout_seconds` after its heartbeat goes out. It
 still fails if the connection becomes `SUSPENDED`, `CLOSED` or `FAILED` first, which can be up to
 two minutes later. Bound the wait yourself if you need an answer sooner:
 
@@ -782,6 +784,144 @@ Example 4.0.0 code:
 response_time_ms = await asyncio.wait_for(pubsub_realtime_client.connection.ping(), timeout=5)
 ```
 
+### The millisecond timing options take seconds, and end in `_seconds`
+
+**Passing an old name raises `TypeError`, so a missed rename fails at construction rather
+than silently scheduling a timeout a thousand times too long.** Four realtime timing options
+and `fallback_retry_timeout`, which the HTTP client reads too, took milliseconds, where the
+HTTP timeouts took seconds. They now take seconds, as an `int` or a `float`, and each is
+renamed with a `_seconds` suffix so the unit is in the name. They read back from
+`client.options` under the new names:
+
+| 3.x option | Unit | 4.0.0 option | Unit | Default |
+|---|---|---|---|---|
+| `realtime_request_timeout` | ms | `realtime_request_timeout_seconds` | s | 10 |
+| `disconnected_retry_timeout` | ms | `disconnected_retry_timeout_seconds` | s | 15 |
+| `suspended_retry_timeout` | ms | `suspended_retry_timeout_seconds` | s | 30 |
+| `channel_retry_timeout` | ms | `channel_retry_timeout_seconds` | s | 15 |
+| `fallback_retry_timeout` | ms | `fallback_retry_timeout_seconds` | s | 600 |
+
+Divide a 3.x value by 1000, or pass a `timedelta`'s `total_seconds()`. The values the Ably
+protocol carries are still milliseconds: a token's `ttl`, `connection.connection_details`,
+`auth.time_offset`, every timestamp and the round trip `connection.ping()` returns.
+
+Example 3.x code:
+```python
+realtime = AblyRealtime(key='xxx', disconnected_retry_timeout=5000, realtime_request_timeout=2500)
+```
+
+Example 4.0.0 code:
+```python
+from datetime import timedelta
+
+pubsub_realtime_client = create_realtime_client(
+    key='xxx',
+    disconnected_retry_timeout_seconds=5,
+    realtime_request_timeout_seconds=timedelta(milliseconds=2500).total_seconds(),
+)
+```
+
+### The HTTP timing options end in `_seconds`
+
+**Passing an old name raises `TypeError`.** The HTTP timing options were already seconds, and
+still are, but their names did not say so where the other timing options were milliseconds.
+Each is renamed with a `_seconds` suffix, to match the options above, and reads back from
+`client.options` under the new name. Only the name changes:
+
+| 3.x option | Unit | 4.0.0 option | Unit | Default |
+|---|---|---|---|---|
+| `http_open_timeout` | s | `http_open_timeout_seconds` | s | 4 |
+| `http_request_timeout` | s | `http_request_timeout_seconds` | s | 10 |
+| `http_max_retry_duration` | s | `http_max_retry_duration_seconds` | s | 15 |
+
+Keep a 3.x value as it is, or pass a `timedelta`'s `total_seconds()`.
+
+Example 3.x code:
+```python
+rest = AblyRest(key='xxx', http_open_timeout=2, http_request_timeout=5)
+```
+
+Example 4.0.0 code:
+```python
+from datetime import timedelta
+
+pubsub_http_client = create_http_client(
+    key='xxx',
+    http_open_timeout_seconds=2,
+    http_request_timeout_seconds=timedelta(seconds=5).total_seconds(),
+)
+```
+
+### An old timing option name says what to pass instead
+
+Passing a timing option under its 3.x name raises a `TypeError` that names its replacement
+and, where the unit changed, converts the value you passed, so a 3.x configuration fails at
+construction with the fix in the message. Unknown options already raised `TypeError`, so
+code that caught it still does:
+
+```
+TypeError: `disconnected_retry_timeout` was renamed to `disconnected_retry_timeout_seconds` in 4.0 and is now in seconds (15000 ms → 15)
+TypeError: `http_request_timeout` was renamed to `http_request_timeout_seconds` in 4.0; it is still in seconds
+```
+
+All eight renames together:
+
+| 3.x option | Unit | 4.0.0 option | Unit |
+|---|---|---|---|
+| `realtime_request_timeout` | ms | `realtime_request_timeout_seconds` | s |
+| `disconnected_retry_timeout` | ms | `disconnected_retry_timeout_seconds` | s |
+| `suspended_retry_timeout` | ms | `suspended_retry_timeout_seconds` | s |
+| `channel_retry_timeout` | ms | `channel_retry_timeout_seconds` | s |
+| `fallback_retry_timeout` | ms | `fallback_retry_timeout_seconds` | s |
+| `http_open_timeout` | s | `http_open_timeout_seconds` | s |
+| `http_request_timeout` | s | `http_request_timeout_seconds` | s |
+| `http_max_retry_duration` | s | `http_max_retry_duration_seconds` | s |
+
+A value held as a `timedelta` converts with `total_seconds()`, whichever option it is for.
+
+### Timing options are validated when the client is created
+
+The eight `_seconds` timing options must each be a finite, non-negative `int` or `float`.
+Anything else raises an `InvalidArgumentException`, an `AblyException` with code 40000 that
+is also a `ValueError`, when the client is created. In 3.x nothing was checked: a string or
+a negative number failed later or not at all, and a `timedelta` passed to a realtime option
+was accepted and then raised inside the timer, so the retry it scheduled never ran. Zero is
+accepted, and no value is too small or too large to pass.
+
+| 3.x option | Unit | 4.0.0 option | Unit | Accepts |
+|---|---|---|---|---|
+| `realtime_request_timeout` | ms | `realtime_request_timeout_seconds` | s | `int` or `float`, ≥ 0 |
+| `disconnected_retry_timeout` | ms | `disconnected_retry_timeout_seconds` | s | `int` or `float`, ≥ 0 |
+| `suspended_retry_timeout` | ms | `suspended_retry_timeout_seconds` | s | `int` or `float`, ≥ 0 |
+| `channel_retry_timeout` | ms | `channel_retry_timeout_seconds` | s | `int` or `float`, ≥ 0 |
+| `fallback_retry_timeout` | ms | `fallback_retry_timeout_seconds` | s | `int` or `float`, ≥ 0 |
+| `http_open_timeout` | s | `http_open_timeout_seconds` | s | `int` or `float`, ≥ 0 |
+| `http_request_timeout` | s | `http_request_timeout_seconds` | s | `int` or `float`, ≥ 0 |
+| `http_max_retry_duration` | s | `http_max_retry_duration_seconds` | s | `int` or `float`, ≥ 0 |
+
+Convert a `timedelta` with `total_seconds()`:
+
+Example 3.x code:
+```python
+realtime = AblyRealtime(key='xxx', disconnected_retry_timeout=timedelta(seconds=5))
+```
+
+Example 4.0.0 code:
+```python
+pubsub_realtime_client = create_realtime_client(
+    key='xxx', disconnected_retry_timeout_seconds=timedelta(seconds=5).total_seconds())
+```
+
+### A `timedelta` ttl is sent to the millisecond
+
+A token `ttl` given as a `timedelta` is now converted to milliseconds exactly. 3.x went through
+`total_seconds()` and truncated, so many values were sent one millisecond short: a ttl of
+`timedelta(milliseconds=1001)` was requested as 1000. Whole seconds were unaffected. This applies
+to token requests and to the params sent to an `auth_url`. A `ttl` given as a number of
+milliseconds is sent as before.
+
+No change is needed.
+
 ## Version 2.x to 3.0.0
 
 The 3.0.0 version of ably-python introduces several breaking changes to improve the realtime experience and align the API with the Ably specification. These include:

ably/pubsub/http/auth.py

@@ -31,6 +31,17 @@
 log = logging.getLogger(__name__)
 
 
+def ttl_ms(ttl):
+    """Returns a token ttl as an int of milliseconds (TK2a)
+
+    A timedelta is converted with integer arithmetic. Going through total_seconds() truncated
+    many whole-millisecond values by one, so 1001 ms was sent as 1000.
+    """
+    if isinstance(ttl, timedelta):
+        return ttl // timedelta(milliseconds=1)
+    return int(ttl)
+
+
 class Auth:
     class Method:
         BASIC = "BASIC"
@@ -299,9 +310,7 @@ async def create_token_request(self, token_params: dict | str | None = None, key
 
         ttl = token_params.get('ttl')
         if ttl is not None:
-            if isinstance(ttl, timedelta):
-                ttl = ttl.total_seconds() * 1000
-            token_request['ttl'] = int(ttl)
+            token_request['ttl'] = ttl_ms(ttl)
 
         capability = token_params.get('capability')
         if capability is not None:
@@ -437,7 +446,7 @@ def _auth_url_token_params(token_params):
             if name == 'client_id':
                 name = 'clientId'
             elif name == 'ttl' and isinstance(value, timedelta):
-                value = int(value.total_seconds() * 1000)
+                value = ttl_ms(value)
             elif name == 'capability' and not isinstance(value, str):
                 value = str(Capability(value))
             params[name] = value

ably/pubsub/realtime/channel.py

@@ -903,7 +903,8 @@ def on_timeout() -> None:
                 self.__state_timer = None
                 self.__timeout_pending_state()
 
-            self.__state_timer = self.__clock.timer(self.__realtime.options.realtime_request_timeout, on_timeout)
+            self.__state_timer = self.__clock.timer(
+                self.__realtime.options._realtime_request_timeout_ms, on_timeout)
 
     def __clear_state_timer(self) -> None:
         if self.__state_timer:
@@ -924,7 +925,7 @@ def __start_retry_timer(self) -> None:
             return
 
         self.__retry_timer = self.__clock.timer(
-            self.ably.options.channel_retry_timeout, self.__on_retry_timer_expire)
+            self.ably.options._channel_retry_timeout_ms, self.__on_retry_timer_expire)
 
     def __cancel_retry_timer(self) -> None:
         if self.__retry_timer: