From 9ec2366870e7f4b49319dcab754f2cef2af8629c Mon Sep 17 00:00:00 2001
From: owenpearson <owen.pearson@ably.com>
Date: Wed, 28 Oct 2026 13:20:32 +0000
Subject: [PATCH 1/5] pubsub: take the millisecond timing options in seconds,
 as *_seconds

TO3l1, TO3l2, TO3l7, TO3l10 and TO3l11 count disconnectedRetryTimeout,
suspendedRetryTimeout, channelRetryTimeout, fallbackRetryTimeout and
realtimeRequestTimeout in milliseconds, and ably-python took
realtime_request_timeout, disconnected_retry_timeout,
suspended_retry_timeout, channel_retry_timeout and fallback_retry_timeout
in milliseconds too. Its three HTTP timing options took seconds, so a
client's options came in two units with nothing in their names to say
which.

The five options now take seconds, as an int or a float, and are renamed
realtime_request_timeout_seconds, disconnected_retry_timeout_seconds,
suspended_retry_timeout_seconds, channel_retry_timeout_seconds and
fallback_retry_timeout_seconds, defaulting to 10, 15, 30, 15 and 600.
They read back from Options under the new names. The clock still counts
milliseconds, so Options converts each one in a single place,
seconds_to_ms, behind a private _<option>_ms property that the
connection manager, the channel, the transport and the HTTP fallback
cache schedule with. It rounds to the microsecond rather than
truncating, so 0.0015 is 1.5 ms and 0.1 is exactly 100. The ping timeout,
which runs on the event loop's clock, reads the seconds directly. The
Defaults move to seconds under the new names; the internal millisecond
values in Defaults are unchanged.

Every UTS test that sets one of these options divides the
specification's value by 1000, and the RTC7 defaults test reads the
seconds back. test/uts/deviations.md records the renamed options as an
intentional naming-and-unit deviation under Adapted Tests. No gated test
changes, so its counts do not.

This is a breaking change: passing an old name raises TypeError, so a
3.x value fails at construction rather than meaning a timeout a thousand
times too long. Callers should rename the option and divide its value by
1000, as UPDATING.md shows. Token ttl, ConnectionDetails,
Auth.time_offset, timestamps and the result of ping() stay milliseconds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/uts-to-python/SKILL.md         |  25 +++--
 CLAUDE.md                                     |   6 +-
 UPDATING.md                                   |  39 ++++++-
 ably/pubsub/realtime/channel.py               |   5 +-
 ably/pubsub/realtime/connectionmanager.py     |  10 +-
 ably/pubsub/realtime/realtime.py              |  30 ++---
 ably/pubsub/request/http.py                   |   2 +-
 ably/pubsub/server/__init__.py                |  40 ++++---
 ably/pubsub/transport/defaults.py             |  14 +--
 ably/pubsub/transport/websockettransport.py   |   2 +-
 ably/pubsub/types/options.py                  | 105 +++++++++++++-----
 test/ably/http/httphttp_test.py               |   6 +-
 test/ably/http/httpinit_test.py               |   6 +-
 test/ably/realtime/realtimeauth_test.py       |   2 +-
 test/ably/realtime/realtimechannel_test.py    |  17 +--
 test/ably/realtime/realtimeconnection_test.py |  29 ++---
 test/ably/testapp.py                          |   2 +-
 test/unit/clock_test.py                       |   4 +-
 test/unit/http_test.py                        |   2 +-
 test/unit/options_test.py                     |  56 +++++++++-
 test/uts/deviations.md                        |  42 +++++--
 test/uts/helpers/mock_websocket_test.py       |  57 +++++-----
 .../integration/proxy/channel_faults_test.py  |  12 +-
 .../proxy/connection_open_failures_test.py    |  10 +-
 .../proxy/connection_resume_test.py           |   4 +-
 .../unit/auth/auth_callback_errors_test.py    |  18 +--
 .../unit/auth/connection_auth_test.py         |  12 +-
 .../unit/channels/channel_attach_test.py      |   7 +-
 .../channels/channel_connection_state_test.py |  14 +--
 .../unit/channels/channel_detach_test.py      |   8 +-
 .../unit/channels/channel_error_test.py       |   2 +-
 .../unit/channels/channel_properties_test.py  |   2 +-
 .../channels/channel_publish_pending_test.py  |   2 +-
 .../unit/channels/channel_publish_test.py     |   6 +-
 .../channel_server_initiated_detach_test.py   |  10 +-
 .../unit/client/realtime_timeouts_test.py     |  21 ++--
 .../unit/connection/backoff_jitter_test.py    |  57 +++++-----
 .../connection/connection_failures_test.py    |   6 +-
 .../unit/connection/connection_id_key_test.py |   2 +-
 .../connection_open_failures_test.py          |  14 +--
 .../unit/connection/connection_ping_test.py   |  45 ++++----
 .../connection/connection_recovery_test.py    |   4 +-
 .../unit/connection/error_reason_test.py      |   6 +-
 .../unit/connection/fallback_hosts_test.py    |   4 +-
 .../unit/connection/heartbeat_test.py         |   6 +-
 .../unit/connection/when_state_test.py        |   4 +-
 .../realtime_presence_channel_state_test.py   |  10 +-
 .../presence/realtime_presence_get_test.py    |   4 +-
 .../realtime_presence_reentry_test.py         |   8 +-
 test/uts/rest/unit/fallback_test.py           |   6 +-
 50 files changed, 498 insertions(+), 307 deletions(-)

diff --git a/.claude/skills/uts-to-python/SKILL.md b/.claude/skills/uts-to-python/SKILL.md
index 48f18fc9..ac88adc0 100644
--- a/.claude/skills/uts-to-python/SKILL.md
+++ b/.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()`
@@ -896,10 +896,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 +930,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
diff --git a/CLAUDE.md b/CLAUDE.md
index 510e61cf..b71b47cb 100644
--- a/CLAUDE.md
+++ b/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.
diff --git a/UPDATING.md b/UPDATING.md
index 9595b77f..c6530074 100644
--- a/UPDATING.md
+++ b/UPDATING.md
@@ -773,7 +773,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 +782,43 @@ 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(),
+)
+```
+
 ## 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:
diff --git a/ably/pubsub/realtime/channel.py b/ably/pubsub/realtime/channel.py
index 1fd9e29c..404ee57a 100644
--- a/ably/pubsub/realtime/channel.py
+++ b/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:
diff --git a/ably/pubsub/realtime/connectionmanager.py b/ably/pubsub/realtime/connectionmanager.py
index cf72e389..ce19e7e5 100644
--- a/ably/pubsub/realtime/connectionmanager.py
+++ b/ably/pubsub/realtime/connectionmanager.py
@@ -147,7 +147,7 @@ def __init__(self, realtime: DefaultPubSubRealtimeClient, initial_state):
         self.__ably = realtime
         self.__state: ConnectionState = initial_state
         self.__pending_pings: dict[str, PendingPing] = {}
-        self.__timeout_in_secs: float = self.options.realtime_request_timeout / 1000
+        self.__timeout_in_secs: float = self.options.realtime_request_timeout_seconds
         self.transport: WebSocketTransport | None = None
         self.__connection_details: ConnectionDetails | None = None
         self.connection_id: str | None = None
@@ -682,9 +682,9 @@ def notify_state(self, state: ConnectionState, reason: AblyException | None = No
         if retry_immediately:
             self.options.loop.call_soon(self.request_state, ConnectionState.CONNECTING)
         elif state == ConnectionState.DISCONNECTED:
-            self.start_retry_timer(self.options.disconnected_retry_timeout)
+            self.start_retry_timer(self.options._disconnected_retry_timeout_ms)
         elif state == ConnectionState.SUSPENDED:
-            self.start_retry_timer(self.options.suspended_retry_timeout)
+            self.start_retry_timer(self.options._suspended_retry_timeout_ms)
 
         if (state == ConnectionState.DISCONNECTED and not retry_immediately) or state == ConnectionState.SUSPENDED:
             self.disconnect_transport()
@@ -721,7 +721,7 @@ def start_transition_timer(self, state: ConnectionState, fail_state: ConnectionS
         if fail_state is None:
             fail_state = self.__fail_state if state != ConnectionState.CLOSING else ConnectionState.CLOSED
 
-        timeout = self.options.realtime_request_timeout
+        timeout = self.options._realtime_request_timeout_ms
 
         def on_transition_timer_expire():
             if self.transition_timer:
@@ -774,7 +774,7 @@ def cancel_suspend_timer(self) -> None:
             self.suspend_timer.cancel()
             self.suspend_timer = None
 
-    def start_retry_timer(self, interval: int) -> None:
+    def start_retry_timer(self, interval: float) -> None:
         def on_retry_timeout():
             log.info('ConnectionManager retry timer expired, retrying')
             self.retry_timer = None
diff --git a/ably/pubsub/realtime/realtime.py b/ably/pubsub/realtime/realtime.py
index 291c6331..4a076aa6 100644
--- a/ably/pubsub/realtime/realtime.py
+++ b/ably/pubsub/realtime/realtime.py
@@ -55,24 +55,26 @@ def __init__(self, key: Optional[str] = None, loop: Optional[asyncio.AbstractEve
         **kwargs: client options
             endpoint: str
                 Endpoint specifies either a routing policy name or fully qualified domain name to connect to Ably.
-            realtime_request_timeout: float
-                Timeout (in milliseconds) for the wait of acknowledgement for operations performed via a realtime
-                connection. Operations include establishing a connection with Ably, or sending a HEARTBEAT,
-                CONNECT, ATTACH, DETACH or CLOSE request. The default is 10 seconds(10000 milliseconds).
-            disconnected_retry_timeout: float
-                If the connection is still in the DISCONNECTED state after this delay, the client library will
-                attempt to reconnect automatically. The default is 15 seconds.
-            channel_retry_timeout: float
-                When a channel becomes SUSPENDED following a server initiated DETACHED, after this delay, if the
-                channel is still SUSPENDED and the connection is in CONNECTED, the client library will attempt to
-                re-attach the channel automatically. The default is 15 seconds.
+            realtime_request_timeout_seconds: float
+                TO3l11 realtimeRequestTimeout, in seconds: the wait for acknowledgement of operations performed
+                via a realtime connection. Operations include establishing a connection with Ably, or sending a
+                HEARTBEAT, CONNECT, ATTACH, DETACH or CLOSE request. The default is 10.
+            disconnected_retry_timeout_seconds: float
+                TO3l1 disconnectedRetryTimeout, in seconds: if the connection is still in the DISCONNECTED state
+                after this delay, the client library will attempt to reconnect automatically. The default is 15.
+            channel_retry_timeout_seconds: float
+                TO3l7 channelRetryTimeout, in seconds: when a channel becomes SUSPENDED following a server
+                initiated DETACHED, after this delay, if the channel is still SUSPENDED and the connection is in
+                CONNECTED, the client library will attempt to re-attach the channel automatically. The default
+                is 15.
             fallback_hosts: list[str]
                 An array of fallback hosts to be used in the case of an error necessitating the use of an
                 alternative host. If you have been provided a set of custom fallback hosts by Ably, please specify
                 them here.
-            suspended_retry_timeout: float
-                When the connection enters the SUSPENDED state, after this delay, if the state is still SUSPENDED,
-                the client library attempts to reconnect automatically. The default is 30 seconds.
+            suspended_retry_timeout_seconds: float
+                TO3l2 suspendedRetryTimeout, in seconds: when the connection enters the SUSPENDED state, after
+                this delay, if the state is still SUSPENDED, the client library attempts to reconnect
+                automatically. The default is 30.
             connectivity_check_url: string
                 Override the URL used by the realtime client to check if the internet is available.
                 In the event of a failure to connect to the primary endpoint, the client will send a
diff --git a/ably/pubsub/request/http.py b/ably/pubsub/request/http.py
index 9e19e6e0..a29ee185 100644
--- a/ably/pubsub/request/http.py
+++ b/ably/pubsub/request/http.py
@@ -247,7 +247,7 @@ def should_stop_retrying(retry_count=retry_count):
                     # Keep fallback host for later (RSC15f)
                     if retry_count > 0 and host != self.options.get_host():
                         self.__host = host
-                        self.__host_expires = self.__clock.now_ms() + self.options.fallback_retry_timeout
+                        self.__host_expires = self.__clock.now_ms() + self.options._fallback_retry_timeout_ms
 
                     return Response(response)
                 except AblyException as e:
diff --git a/ably/pubsub/server/__init__.py b/ably/pubsub/server/__init__.py
index 0582dcf4..6dca0aa7 100644
--- a/ably/pubsub/server/__init__.py
+++ b/ably/pubsub/server/__init__.py
@@ -125,9 +125,10 @@ def create_http_client(**kwargs) -> PubSubHttpClient:
         fallback_hosts: list[str]
             Hosts to fall back to when the primary endpoint is unreachable. Set this only
             if Ably has provided you with a custom set.
-        fallback_retry_timeout: float
-            How long (in milliseconds) a fallback host stays preferred once the client has
-            failed over to it. The default is 10 minutes (600000 milliseconds).
+        fallback_retry_timeout_seconds: float
+            TO3l10 fallbackRetryTimeout, in seconds: how long a fallback host stays
+            preferred once the client has failed over to it. The default is 600 (10
+            minutes).
 
         **HTTP behaviour**
 
@@ -205,21 +206,24 @@ def create_realtime_client(**kwargs) -> PubSubRealtimeClient:
 
         **Timeouts and retries**
 
-        realtime_request_timeout: float
-            How long (in milliseconds) to wait for acknowledgement of an operation
-            performed over the realtime connection, such as establishing a connection or
-            sending a HEARTBEAT, CONNECT, ATTACH, DETACH or CLOSE request. The default is
-            10 seconds (10000 milliseconds).
-        disconnected_retry_timeout: float
-            How long (in milliseconds) to stay DISCONNECTED before attempting to reconnect
-            automatically. The default is 15 seconds (15000 milliseconds).
-        suspended_retry_timeout: float
-            How long (in milliseconds) to stay SUSPENDED before attempting to reconnect
-            automatically. The default is 30 seconds (30000 milliseconds).
-        channel_retry_timeout: float
-            How long (in milliseconds) a channel stays SUSPENDED, following a server
-            initiated DETACHED, before the client re-attaches it — provided the connection
-            is CONNECTED. The default is 15 seconds (15000 milliseconds).
+        The timeouts are in seconds, where the Ably specification counts milliseconds, and
+        their names say so; a `datetime.timedelta` converts with `.total_seconds()`.
+
+        realtime_request_timeout_seconds: float
+            TO3l11 realtimeRequestTimeout, in seconds: how long to wait for
+            acknowledgement of an operation performed over the realtime connection, such
+            as establishing a connection or sending a HEARTBEAT, CONNECT, ATTACH, DETACH
+            or CLOSE request. The default is 10.
+        disconnected_retry_timeout_seconds: float
+            TO3l1 disconnectedRetryTimeout, in seconds: how long to stay DISCONNECTED
+            before attempting to reconnect automatically. The default is 15.
+        suspended_retry_timeout_seconds: float
+            TO3l2 suspendedRetryTimeout, in seconds: how long to stay SUSPENDED before
+            attempting to reconnect automatically. The default is 30.
+        channel_retry_timeout_seconds: float
+            TO3l7 channelRetryTimeout, in seconds: how long a channel stays SUSPENDED,
+            following a server initiated DETACHED, before the client re-attaches it —
+            provided the connection is CONNECTED. The default is 15.
         connectivity_check_url: str
             The URL the client requests to decide whether the internet is reachable. On
             failing to reach the primary endpoint, a success response from this URL tells
diff --git a/ably/pubsub/transport/defaults.py b/ably/pubsub/transport/defaults.py
index cdb93d73..2d9b349a 100644
--- a/ably/pubsub/transport/defaults.py
+++ b/ably/pubsub/transport/defaults.py
@@ -11,22 +11,22 @@ class Defaults:
     suspended_timeout = 60000
     comet_recv_timeout = 90000
     comet_send_timeout = 10000
-    realtime_request_timeout = 10000
-    channel_retry_timeout = 15000
-    disconnected_retry_timeout = 15000
     connection_state_ttl = 120000
-    suspended_retry_timeout = 30000
 
     transports = []  # ["web_socket", "comet"]
 
-    # The HTTP timeouts are in seconds, unlike the realtime ones above
+    # The defaults of the timing client options, in seconds where the values above are milliseconds
+    realtime_request_timeout_seconds = 10
+    channel_retry_timeout_seconds = 15
+    disconnected_retry_timeout_seconds = 15
+    suspended_retry_timeout_seconds = 30
+    fallback_retry_timeout_seconds = 600  # 10min
+
     http_open_timeout = 4
     http_request_timeout = 10
     http_max_retry_count = 3
     http_max_retry_duration = 15
 
-    fallback_retry_timeout = 600000  # 10min
-
     max_message_size = 65536  # 64KiB
 
     @staticmethod
diff --git a/ably/pubsub/transport/websockettransport.py b/ably/pubsub/transport/websockettransport.py
index 785bae46..75f55a44 100644
--- a/ably/pubsub/transport/websockettransport.py
+++ b/ably/pubsub/transport/websockettransport.py
@@ -157,7 +157,7 @@ async def on_protocol_message(self, msg):
 
             max_idle_interval = connection_details.max_idle_interval
             if max_idle_interval:
-                self.max_idle_interval = max_idle_interval + self.options.realtime_request_timeout
+                self.max_idle_interval = max_idle_interval + self.options._realtime_request_timeout_ms
                 self.on_activity()
             self.is_connected = True
             if self.host != self.options.get_host():  # RTN17e
diff --git a/ably/pubsub/types/options.py b/ably/pubsub/types/options.py
index 4ff30c99..20e1fe51 100644
--- a/ably/pubsub/types/options.py
+++ b/ably/pubsub/types/options.py
@@ -8,6 +8,18 @@
 log = logging.getLogger(__name__)
 
 
+def seconds_to_ms(seconds):
+    """Converts a timing option from seconds to the milliseconds the clock counts in.
+
+    This is the one place a timing option is converted. It rounds to the microsecond
+    rather than truncating, so 0.0015 is 1.5 ms rather than 1, and float error cannot
+    leave 0.1 a hair over 100 ms, where a timer would miss a deadline the clock is
+    advanced to exactly. A whole number of milliseconds comes back as an int.
+    """
+    ms = round(seconds * 1000, 3)
+    return int(ms) if ms == int(ms) else ms
+
+
 class VCDiffDecoder(ABC):
     """
     The VCDiffDecoder class defines the interface for delta decoding operations.
@@ -25,25 +37,39 @@ def decode(self, delta: bytes, base: bytes) -> bytes:
 
 
 class Options(AuthOptions):
+    """The client options, as the factories in `ably.pubsub.server` document them.
+
+    The timing options are in seconds, where the Ably specification counts
+    milliseconds, and each name ends in `_seconds` to say so. Each reads back the value
+    in effect, its default if it was not given:
+
+    - `realtime_request_timeout_seconds`: TO3l11 realtimeRequestTimeout, default 10
+    - `disconnected_retry_timeout_seconds`: TO3l1 disconnectedRetryTimeout, default 15
+    - `suspended_retry_timeout_seconds`: TO3l2 suspendedRetryTimeout, default 30
+    - `channel_retry_timeout_seconds`: TO3l7 channelRetryTimeout, default 15
+    - `fallback_retry_timeout_seconds`: TO3l10 fallbackRetryTimeout, default 600
+    """
+
     def __init__(self, client_id=None, tls=True, port=0,
                  tls_port=0, use_binary_protocol=True, queue_messages=True, endpoint=None,
                  http_open_timeout=None, http_request_timeout=None,
-                 realtime_request_timeout=None, http_max_retry_count=None, http_max_retry_duration=None,
-                 fallback_hosts=None, fallback_retry_timeout=None, disconnected_retry_timeout=None,
+                 realtime_request_timeout_seconds=None, http_max_retry_count=None, http_max_retry_duration=None,
+                 fallback_hosts=None, fallback_retry_timeout_seconds=None, disconnected_retry_timeout_seconds=None,
                  idempotent_rest_publishing=None, loop=None, auto_connect=True,
-                 suspended_retry_timeout=None, connectivity_check_url=None,
-                 channel_retry_timeout=Defaults.channel_retry_timeout, add_request_ids=False,
+                 suspended_retry_timeout_seconds=None, connectivity_check_url=None,
+                 channel_retry_timeout_seconds=None, add_request_ids=False,
                  vcdiff_decoder: VCDiffDecoder = None, transport_params=None, echo_messages=True,
                  max_message_size=None, _test_options=None, **kwargs):
 
         super().__init__(**kwargs)
 
-        # TODO check these defaults
-        if fallback_retry_timeout is None:
-            fallback_retry_timeout = Defaults.fallback_retry_timeout
+        # TO3l10, TO3l11, TO3l1, TO3l2 and TO3l7 count milliseconds, and these options take
+        # seconds. The clock counts milliseconds, which the _ms properties convert to
+        if fallback_retry_timeout_seconds is None:
+            fallback_retry_timeout_seconds = Defaults.fallback_retry_timeout_seconds
 
-        if realtime_request_timeout is None:
-            realtime_request_timeout = Defaults.realtime_request_timeout
+        if realtime_request_timeout_seconds is None:
+            realtime_request_timeout_seconds = Defaults.realtime_request_timeout_seconds
 
         # RTC7: the HTTP defaults are resolved here too, so they read back from the options
         if http_open_timeout is None:
@@ -58,14 +84,17 @@ def __init__(self, client_id=None, tls=True, port=0,
         if http_max_retry_duration is None:
             http_max_retry_duration = Defaults.http_max_retry_duration
 
-        if disconnected_retry_timeout is None:
-            disconnected_retry_timeout = Defaults.disconnected_retry_timeout
+        if disconnected_retry_timeout_seconds is None:
+            disconnected_retry_timeout_seconds = Defaults.disconnected_retry_timeout_seconds
 
         if connectivity_check_url is None:
             connectivity_check_url = Defaults.connectivity_check_url
 
-        if suspended_retry_timeout is None:
-            suspended_retry_timeout = Defaults.suspended_retry_timeout
+        if suspended_retry_timeout_seconds is None:
+            suspended_retry_timeout_seconds = Defaults.suspended_retry_timeout_seconds
+
+        if channel_retry_timeout_seconds is None:
+            channel_retry_timeout_seconds = Defaults.channel_retry_timeout_seconds
 
         # TO3l8
         if max_message_size is None:
@@ -90,19 +119,19 @@ def __init__(self, client_id=None, tls=True, port=0,
         self.__endpoint = endpoint
         self.__http_open_timeout = http_open_timeout
         self.__http_request_timeout = http_request_timeout
-        self.__realtime_request_timeout = realtime_request_timeout
+        self.__realtime_request_timeout_seconds = realtime_request_timeout_seconds
         self.__http_max_retry_count = http_max_retry_count
         self.__http_max_retry_duration = http_max_retry_duration
         # Field for internal use only
         self.__fallback_host = None
         self.__fallback_hosts = fallback_hosts
-        self.__fallback_retry_timeout = fallback_retry_timeout
-        self.__disconnected_retry_timeout = disconnected_retry_timeout
-        self.__channel_retry_timeout = channel_retry_timeout
+        self.__fallback_retry_timeout_seconds = fallback_retry_timeout_seconds
+        self.__disconnected_retry_timeout_seconds = disconnected_retry_timeout_seconds
+        self.__channel_retry_timeout_seconds = channel_retry_timeout_seconds
         self.__idempotent_rest_publishing = idempotent_rest_publishing
         self.__loop = loop
         self.__auto_connect = auto_connect
-        self.__suspended_retry_timeout = suspended_retry_timeout
+        self.__suspended_retry_timeout_seconds = suspended_retry_timeout_seconds
         self.__connectivity_check_url = connectivity_check_url
         self.__add_request_ids = add_request_ids
         self.__vcdiff_decoder = vcdiff_decoder
@@ -181,8 +210,12 @@ def http_request_timeout(self):
         return self.__http_request_timeout
 
     @property
-    def realtime_request_timeout(self):
-        return self.__realtime_request_timeout
+    def realtime_request_timeout_seconds(self):
+        return self.__realtime_request_timeout_seconds
+
+    @property
+    def _realtime_request_timeout_ms(self):
+        return seconds_to_ms(self.__realtime_request_timeout_seconds)
 
     @http_request_timeout.setter
     def http_request_timeout(self, value):
@@ -209,16 +242,28 @@ def fallback_hosts(self):
         return self.__fallback_hosts
 
     @property
-    def fallback_retry_timeout(self):
-        return self.__fallback_retry_timeout
+    def fallback_retry_timeout_seconds(self):
+        return self.__fallback_retry_timeout_seconds
+
+    @property
+    def _fallback_retry_timeout_ms(self):
+        return seconds_to_ms(self.__fallback_retry_timeout_seconds)
+
+    @property
+    def disconnected_retry_timeout_seconds(self):
+        return self.__disconnected_retry_timeout_seconds
 
     @property
-    def disconnected_retry_timeout(self):
-        return self.__disconnected_retry_timeout
+    def _disconnected_retry_timeout_ms(self):
+        return seconds_to_ms(self.__disconnected_retry_timeout_seconds)
 
     @property
-    def channel_retry_timeout(self):
-        return self.__channel_retry_timeout
+    def channel_retry_timeout_seconds(self):
+        return self.__channel_retry_timeout_seconds
+
+    @property
+    def _channel_retry_timeout_ms(self):
+        return seconds_to_ms(self.__channel_retry_timeout_seconds)
 
     @property
     def idempotent_rest_publishing(self):
@@ -234,8 +279,12 @@ def auto_connect(self):
         return self.__auto_connect
 
     @property
-    def suspended_retry_timeout(self):
-        return self.__suspended_retry_timeout
+    def suspended_retry_timeout_seconds(self):
+        return self.__suspended_retry_timeout_seconds
+
+    @property
+    def _suspended_retry_timeout_ms(self):
+        return seconds_to_ms(self.__suspended_retry_timeout_seconds)
 
     @property
     def connectivity_check_url(self):
diff --git a/test/ably/http/httphttp_test.py b/test/ably/http/httphttp_test.py
index 0336d0ef..81615f97 100644
--- a/test/ably/http/httphttp_test.py
+++ b/test/ably/http/httphttp_test.py
@@ -104,8 +104,8 @@ async def test_no_host_fallback_nor_retries_if_custom_host(self):
 
     # RSC15f
     async def test_cached_fallback(self):
-        timeout = 2000
-        ably = await TestApp.get_ably_rest(fallback_retry_timeout=timeout)
+        timeout = 2
+        ably = await TestApp.get_ably_rest(fallback_retry_timeout_seconds=timeout)
         host = ably.options.get_host()
 
         state = {'errors': 0}
@@ -130,7 +130,7 @@ async def side_effect(*args, **kwargs):
             assert state['errors'] == 1
 
             # The cached host has expired, we've an error again
-            time.sleep(timeout / 1000.0)
+            time.sleep(timeout)
             await ably.time()
             assert state['errors'] == 2
 
diff --git a/test/ably/http/httpinit_test.py b/test/ably/http/httpinit_test.py
index 702cafac..b7cf5e7a 100644
--- a/test/ably/http/httpinit_test.py
+++ b/test/ably/http/httpinit_test.py
@@ -113,9 +113,9 @@ def test_fallback_hosts(self):
 
         # RSC15f
         ably = create_http_client(token='foo')
-        assert 600000 == ably.options.fallback_retry_timeout
-        ably = create_http_client(token='foo', fallback_retry_timeout=1000)
-        assert 1000 == ably.options.fallback_retry_timeout
+        assert 600 == ably.options.fallback_retry_timeout_seconds
+        ably = create_http_client(token='foo', fallback_retry_timeout_seconds=1)
+        assert 1 == ably.options.fallback_retry_timeout_seconds
 
     @dont_vary_protocol
     def test_specified_host(self):
diff --git a/test/ably/realtime/realtimeauth_test.py b/test/ably/realtime/realtimeauth_test.py
index 781e379b..4e8bebba 100644
--- a/test/ably/realtime/realtimeauth_test.py
+++ b/test/ably/realtime/realtimeauth_test.py
@@ -431,7 +431,7 @@ async def auth_callback(_):
 
         await auth_callback_failure({
             'auth_callback': auth_callback,
-            'realtime_request_timeout': 100,
+            'realtime_request_timeout_seconds': 0.1,
         })
 
     async def test_auth_callback_nothing(self):
diff --git a/test/ably/realtime/realtimechannel_test.py b/test/ably/realtime/realtimechannel_test.py
index 477f412a..ea4cc8ba 100644
--- a/test/ably/realtime/realtimechannel_test.py
+++ b/test/ably/realtime/realtimechannel_test.py
@@ -253,7 +253,7 @@ def listener(msg):
         await rest.close()
 
     async def test_realtime_request_timeout_attach(self):
-        ably = await TestApp.get_ably_realtime(realtime_request_timeout=2000)
+        ably = await TestApp.get_ably_realtime(realtime_request_timeout_seconds=2)
         await asyncio.wait_for(ably.connection.once_async(ConnectionState.CONNECTED), timeout=5)
         original_send_protocol_message = ably.connection.connection_manager.send_protocol_message
 
@@ -271,7 +271,7 @@ async def new_send_protocol_message(msg):
         await ably.close()
 
     async def test_realtime_request_timeout_detach(self):
-        ably = await TestApp.get_ably_realtime(realtime_request_timeout=2000)
+        ably = await TestApp.get_ably_realtime(realtime_request_timeout_seconds=2)
         await asyncio.wait_for(ably.connection.once_async(ConnectionState.CONNECTED), timeout=5)
         original_send_protocol_message = ably.connection.connection_manager.send_protocol_message
 
@@ -290,7 +290,7 @@ async def new_send_protocol_message(msg):
         await ably.close()
 
     async def test_channel_detached_once_connection_closed(self):
-        ably = await TestApp.get_ably_realtime(realtime_request_timeout=2000)
+        ably = await TestApp.get_ably_realtime(realtime_request_timeout_seconds=2)
         await asyncio.wait_for(ably.connection.once_async(ConnectionState.CONNECTED), timeout=5)
         channel = ably.channels.get(random_string(5))
         await channel.attach()
@@ -299,7 +299,7 @@ async def test_channel_detached_once_connection_closed(self):
         assert channel.state == ChannelState.DETACHED
 
     async def test_channel_failed_once_connection_failed(self):
-        ably = await TestApp.get_ably_realtime(realtime_request_timeout=2000)
+        ably = await TestApp.get_ably_realtime(realtime_request_timeout_seconds=2)
         await asyncio.wait_for(ably.connection.once_async(ConnectionState.CONNECTED), timeout=5)
         channel = ably.channels.get(random_string(5))
         await channel.attach()
@@ -310,7 +310,7 @@ async def test_channel_failed_once_connection_failed(self):
         await ably.close()
 
     async def test_channel_suspended_once_connection_suspended(self):
-        ably = await TestApp.get_ably_realtime(realtime_request_timeout=2000)
+        ably = await TestApp.get_ably_realtime(realtime_request_timeout_seconds=2)
         await asyncio.wait_for(ably.connection.once_async(ConnectionState.CONNECTED), timeout=5)
         channel = ably.channels.get(random_string(5))
         await channel.attach()
@@ -329,7 +329,7 @@ async def test_attach_while_connecting(self):
 
     # RTL13a
     async def test_channel_attach_retry_immediately_on_unexpected_detached(self):
-        ably = await TestApp.get_ably_realtime(channel_retry_timeout=500)
+        ably = await TestApp.get_ably_realtime(channel_retry_timeout_seconds=0.5)
         channel_name = random_string(5)
         channel = ably.channels.get(channel_name)
         await channel.attach()
@@ -352,7 +352,8 @@ async def test_channel_attach_retry_immediately_on_unexpected_detached(self):
 
     # RTL13b
     async def test_channel_attach_retry_after_unsuccessful_attach(self):
-        ably = await TestApp.get_ably_realtime(channel_retry_timeout=500, realtime_request_timeout=1000)
+        ably = await TestApp.get_ably_realtime(channel_retry_timeout_seconds=0.5,
+                                               realtime_request_timeout_seconds=1)
         channel_name = random_string(5)
         channel = ably.channels.get(channel_name)
         call_count = 0
@@ -371,7 +372,7 @@ async def new_send_protocol_message(msg):
         with pytest.raises(AblyException):
             await channel.attach()
 
-        # The channel should become SUSPENDED but will still retry again after channel_retry_timeout
+        # The channel should become SUSPENDED but will still retry again after channel_retry_timeout_seconds
         assert channel.state == ChannelState.SUSPENDED
 
         # Make sure the channel sucessfully re-attaches
diff --git a/test/ably/realtime/realtimeconnection_test.py b/test/ably/realtime/realtimeconnection_test.py
index e6507e6a..46261815 100644
--- a/test/ably/realtime/realtimeconnection_test.py
+++ b/test/ably/realtime/realtimeconnection_test.py
@@ -186,7 +186,7 @@ async def test_connection_state_change_reason(self):
         await ably.close()
 
     async def test_realtime_request_timeout_connect(self):
-        ably = await TestApp.get_ably_realtime(realtime_request_timeout=0.000001)
+        ably = await TestApp.get_ably_realtime(realtime_request_timeout_seconds=1e-9)
         state_change = await ably.connection.once_async()
         assert state_change.reason is not None
         assert state_change.reason.code == 50003
@@ -196,7 +196,7 @@ async def test_realtime_request_timeout_connect(self):
         await ably.close()
 
     async def test_realtime_request_timeout_ping(self):
-        ably = await TestApp.get_ably_realtime(realtime_request_timeout=2000)
+        ably = await TestApp.get_ably_realtime(realtime_request_timeout_seconds=2)
         await asyncio.wait_for(ably.connection.once_async(ConnectionState.CONNECTED), timeout=5)
 
         original_send_protocol_message = ably.connection.connection_manager.send_protocol_message
@@ -235,11 +235,11 @@ async def test_ping_after_invalid_state_ping(self):
 
     async def test_ping_survives_connection_drop(self):
         # RTN13d: a heartbeat lost with a dropped connection is sent again once the connection is
-        # back, rather than the ping failing or waiting out realtime_request_timeout
+        # back, rather than the ping failing or waiting out realtime_request_timeout_seconds
         outage_secs = 1
         async with WsProxy(self.test_vars["host"]) as proxy:
             ably = await TestApp.get_ably_realtime(
-                realtime_request_timeout=20000,
+                realtime_request_timeout_seconds=20,
                 tls=False,
                 endpoint=proxy.endpoint,
                 port=proxy.port,
@@ -276,7 +276,7 @@ async def drop_heartbeats(protocol_message):
 
     async def test_ping_fails_when_connection_closes(self):
         # RTN13b: a ping cannot complete once the connection has transitioned to CLOSING
-        ably = await TestApp.get_ably_realtime(realtime_request_timeout=20000)
+        ably = await TestApp.get_ably_realtime(realtime_request_timeout_seconds=20)
         await asyncio.wait_for(ably.connection.once_async(ConnectionState.CONNECTED), timeout=5)
 
         connection_manager = ably.connection.connection_manager
@@ -318,7 +318,7 @@ async def test_concurrent_pings(self):
         await ably.close()
 
     async def test_disconnected_retry_timeout(self):
-        ably = await TestApp.get_ably_realtime(disconnected_retry_timeout=2000, auto_connect=False)
+        ably = await TestApp.get_ably_realtime(disconnected_retry_timeout_seconds=2, auto_connect=False)
         original_connect = ably.connection.connection_manager.connect_base
         call_count = 0
 
@@ -360,7 +360,7 @@ async def test_connectivity_check_bad_status(self):
         assert ably.connection.connection_manager.check_connection() is False
 
     async def test_unroutable_host(self):
-        ably = await TestApp.get_ably_realtime(endpoint="10.255.255.1", realtime_request_timeout=3000)
+        ably = await TestApp.get_ably_realtime(endpoint="10.255.255.1", realtime_request_timeout_seconds=3)
         state_change = await ably.connection.once_async()
         assert state_change.reason
         assert state_change.reason.code == 50003
@@ -418,7 +418,7 @@ async def on_transport_pending(transport):
         await ably.close()
 
     async def test_max_idle_interval(self):
-        ably = await TestApp.get_ably_realtime(realtime_request_timeout=2000)
+        ably = await TestApp.get_ably_realtime(realtime_request_timeout_seconds=2)
 
         def on_transport_pending(transport):
             original_on_protocol_message = transport.on_protocol_message
@@ -446,8 +446,8 @@ async def on_protocol_message(msg):
     async def test_retry_immediately_upon_unexpected_disconnection(self):
         # Set timeouts to 500s so that if the client uses retry delay the test will fail with a timeout
         ably = await TestApp.get_ably_realtime(
-            disconnected_retry_timeout=500_000,
-            suspended_retry_timeout=500_000
+            disconnected_retry_timeout_seconds=500,
+            suspended_retry_timeout_seconds=500
         )
 
         # Wait for the client to connect
@@ -548,7 +548,8 @@ async def test_connection_client_id_query_params(self):
         await ably.close()
 
     async def test_lost_connection_lifecycle(self):
-        ably = await TestApp.get_ably_realtime(realtime_request_timeout=2000, disconnected_retry_timeout=2000)
+        ably = await TestApp.get_ably_realtime(realtime_request_timeout_seconds=2,
+                                               disconnected_retry_timeout_seconds=2)
 
         # when client connectivity is lost, the transport will become aware of a connectivity issue
         # when it stops seeing activity from realtime within maxIdleInterval, therefore setting the max idle
@@ -569,7 +570,7 @@ async def on_protocol_message(msg):
         # should transition to disconnected due to lack of activity from realtime
         await ably.connection.once_async(ConnectionState.DISCONNECTED)
 
-        # should re-establish connection after disconnected_retry_timeout
+        # should re-establish connection after disconnected_retry_timeout_seconds
         await asyncio.wait_for(ably.connection.once_async(ConnectionState.CONNECTED), timeout=5)
 
         await ably.close()
@@ -651,8 +652,8 @@ async def test_normal_ws_close_triggers_immediate_reconnection(self):
         """
         async with WsProxy(self.test_vars["host"]) as proxy:
             ably = await TestApp.get_ably_realtime(
-                disconnected_retry_timeout=500_000,
-                suspended_retry_timeout=500_000,
+                disconnected_retry_timeout_seconds=500,
+                suspended_retry_timeout_seconds=500,
                 tls=False,
                 endpoint=proxy.endpoint,
                 port=proxy.port,
diff --git a/test/ably/testapp.py b/test/ably/testapp.py
index 30a0b6d9..2a4c1efb 100644
--- a/test/ably/testapp.py
+++ b/test/ably/testapp.py
@@ -81,7 +81,7 @@ async def get_ably_realtime(**kw):
         # timer expires. The default interval is longer than the timeout most tests allow
         # for reaching CONNECTED, so a short one keeps a single failed attempt from using
         # up the whole budget. Tests that assert on retry timing set their own value.
-        options.setdefault('disconnected_retry_timeout', 1000)
+        options.setdefault('disconnected_retry_timeout_seconds', 1)
         return ably.pubsub.server.create_realtime_client(**options)
 
     @staticmethod
diff --git a/test/unit/clock_test.py b/test/unit/clock_test.py
index b02a5fb6..e363291b 100644
--- a/test/unit/clock_test.py
+++ b/test/unit/clock_test.py
@@ -67,10 +67,10 @@ def test_a_client_without_test_options_reads_the_real_clock():
 
 
 async def test_the_cached_fallback_host_expires_on_the_clock():
-    # RSC15f: the cache lasts fallback_retry_timeout milliseconds
+    # RSC15f: the cache lasts fallback_retry_timeout_seconds, which the clock counts in milliseconds
     clock = FakeClock()
     transport = RecordingTransport()
-    ably = create_http_client(token='foo', fallback_retry_timeout=2000,
+    ably = create_http_client(token='foo', fallback_retry_timeout_seconds=2,
                               _test_options=TestOptions(http_transport=transport, clock=clock))
     primary = ably.options.get_host()
     transport.refusing = (primary,)
diff --git a/test/unit/http_test.py b/test/unit/http_test.py
index 91960630..cc9196d4 100644
--- a/test/unit/http_test.py
+++ b/test/unit/http_test.py
@@ -167,7 +167,7 @@ async def test_realtime_token_request_network_errors_reach_the_connection_wrappe
     mock_http = MockHttpClient(on_connection_attempt=lambda conn: conn.respond_with_refused())
     mock_ws = MockWebSocket()
     client = realtime_client(mock_ws, mock_http, key="appId.keyId:keySecret", use_token_auth=True,
-                             disconnected_retry_timeout=600000)
+                             disconnected_retry_timeout_seconds=600)
     try:
         client.connect()
         await await_connection_state(client, ConnectionState.DISCONNECTED)
diff --git a/test/unit/options_test.py b/test/unit/options_test.py
index fb68159f..fca93a06 100644
--- a/test/unit/options_test.py
+++ b/test/unit/options_test.py
@@ -1,7 +1,7 @@
 import pytest
 
 from ably.pubsub.server import create_http_client
-from ably.pubsub.types.options import Options
+from ably.pubsub.types.options import Options, seconds_to_ms
 from ably.pubsub.util.exceptions import AblyException
 
 
@@ -154,3 +154,57 @@ def test_invalid_client_arguments_raise_40106(kwargs, status_code):
     assert exinfo.value.code == 40106
     assert exinfo.value.status_code == status_code
     assert isinstance(exinfo.value, ValueError)
+
+
+# TO3l1, TO3l2, TO3l7, TO3l10, TO3l11: the realtime timing options are seconds where the
+# specification counts milliseconds, and named for it
+REALTIME_TIMING_DEFAULTS = {
+    'realtime_request_timeout_seconds': 10,
+    'disconnected_retry_timeout_seconds': 15,
+    'suspended_retry_timeout_seconds': 30,
+    'channel_retry_timeout_seconds': 15,
+    'fallback_retry_timeout_seconds': 600,
+}
+
+
+@pytest.mark.parametrize('option, default', REALTIME_TIMING_DEFAULTS.items())
+def test_realtime_timing_options_read_back_their_defaults_in_seconds(option, default):
+    opts = Options()
+    assert getattr(opts, option) == default
+    assert getattr(opts, '_' + option.replace('_seconds', '_ms')) == default * 1000
+
+
+@pytest.mark.parametrize('option', REALTIME_TIMING_DEFAULTS)
+def test_realtime_timing_options_read_back_what_was_given(option):
+    opts = Options(**{option: 0.25})
+    assert getattr(opts, option) == 0.25
+    assert getattr(opts, '_' + option.replace('_seconds', '_ms')) == 250
+
+
+@pytest.mark.parametrize('option', ['realtime_request_timeout', 'disconnected_retry_timeout',
+                                    'suspended_retry_timeout', 'channel_retry_timeout',
+                                    'fallback_retry_timeout'])
+def test_options_should_reject_the_millisecond_names(option):
+    with pytest.raises(TypeError):
+        Options(**{option: 15000})
+
+
+@pytest.mark.parametrize('seconds, ms', [
+    (15, 15000),
+    (0.1, 100),
+    (0.3, 300),
+    (0.7, 700),
+    (2.3, 2300),
+    (0.0015, 1.5),
+    (0.0005, 0.5),
+    (600, 600000),
+    (0, 0),
+])
+def test_seconds_convert_to_milliseconds_exactly(seconds, ms):
+    assert seconds_to_ms(seconds) == ms
+
+
+def test_a_whole_number_of_milliseconds_is_an_int():
+    assert type(seconds_to_ms(0.1)) is int
+    assert type(seconds_to_ms(15)) is int
+    assert type(seconds_to_ms(0.0015)) is float
diff --git a/test/uts/deviations.md b/test/uts/deviations.md
index 936d3b54..586a498a 100644
--- a/test/uts/deviations.md
+++ b/test/uts/deviations.md
@@ -1838,7 +1838,7 @@ except (WebSocketException, socket.gaierror) as e:
 `ConnectionManager.try_host` awaits is completed only by the `connected` or `failed` events,
 so it never completes; the `except` clause in `connect_base` that would enter
 `connect_with_fallback_hosts` is never reached; and the attempt is ended only by the
-transition timer. Measured, with `fallback_hosts=[]` and `realtime_request_timeout=1000`:
+transition timer. Measured, with `fallback_hosts=[]` and `realtime_request_timeout_seconds=1`:
 
 | injected | state at settle | state change | reason |
 |---|---|---|---|
@@ -1927,7 +1927,7 @@ has `uts-proxy` replace the first CONNECTED with one carrying `connectionStateTt
 drops the socket and refuses the retry. Measured: the replacement did reach
 `connection_details.connection_state_ttl == 2000`, and SUSPENDED still did not arrive
 within 45 s — the client sat DISCONNECTED and reconnected on the fifteen-second
-`disconnected_retry_timeout`. Honouring the TTL will not on its own turn that test green.
+`disconnected_retry_timeout_seconds`. Honouring the TTL will not on its own turn that test green.
 `#### The connection id, key and details are cleared on SUSPENDED` means a suspended client
 stops sending `resume`, which is precisely what RTN14h asserts it still does, and
 `"connectionKey": "__PASSTHROUGH__"` in the fixture is not substituted by uts-proxy v0.3.0
@@ -2054,6 +2054,31 @@ adapted.
 
 **Status:** adapted; the gap itself is the open issue recorded above.
 
+### Timing options are seconds, and named for it
+
+Intentional. TO3l counts every timing option in milliseconds; ably-python takes seconds,
+which is what a Python caller expects, and names each option with a `_seconds` suffix so
+the unit is on the page. A 3.x caller passing the old name gets a `TypeError` at
+construction, rather than a value a thousand times too long. The wire values the
+specification also counts in milliseconds are unchanged: token `ttl`, `ConnectionDetails`,
+`Auth.time_offset`, timestamps and the result of `ping()`.
+
+Every derived test that sets one of these options divides the specification's value by
+1000, so `disconnectedRetryTimeout: 100` is `disconnected_retry_timeout_seconds=0.1`, and
+every test reading a default back reads the seconds. Everything else stays in the
+specification's milliseconds: `ADVANCE_TIME`, `maxIdleInterval`, `connectionStateTtl` and
+every `FakeClock` value. `Options` converts each option for the clock in one place,
+rounding to the microsecond, so 0.1 schedules exactly 100 ms and a timer due on the
+boundary of an `ADVANCE_TIME` still fires.
+
+| Spec point | Specification | ably-python | Tests |
+|---|---|---|---|
+| TO3l11 | `realtimeRequestTimeout`, ms, default 10000 | `realtime_request_timeout_seconds`, default 10 | `test_rtc7_default_timeouts_applied`, and every realtime test that shortens the request timeout |
+| TO3l1 | `disconnectedRetryTimeout`, ms, default 15000 | `disconnected_retry_timeout_seconds`, default 15 | `test_rtc7_default_timeouts_applied`, and every realtime test that shortens or lengthens the retry |
+| TO3l2 | `suspendedRetryTimeout`, ms, default 30000 | `suspended_retry_timeout_seconds`, default 30 | `test_rtc7_default_timeouts_applied`, and every realtime test that sets it |
+| TO3l7 | `channelRetryTimeout`, ms, default 15000 | `channel_retry_timeout_seconds`, default 15 | every channel test that sets it, among them the RTL13b and RTB1 tests |
+| TO3l10 | `fallbackRetryTimeout`, ms, default 600000 | `fallback_retry_timeout_seconds`, default 600 | the RSC15f tests in `rest/unit/fallback_test.py` |
+
 ### Channel and presence behaviours asserted as they are
 
 | Spec points | Specification | ably-python | Tests |
@@ -2063,7 +2088,7 @@ adapted.
 | RTL7g | `channel.subscribe(listener)` registers the listener even when the implicit attach is rejected | the listener *is* registered (`channel.py:279-282`), and then `subscribe` awaits `attach()`, which re-raises the failure (`:150`). So `await channel.subscribe(...)` raises where the specification's fire-and-forget call returns. The RTL7g requirement itself holds | `test_rtl7g_listener_registered_attach_fails`, `test_rtl7g_no_attach_when_attaching` |
 | RTL10b | an `AblyException` when `untilAttach` is used on an unattached channel | an `AblyException`, but for the wrong reason: `history` takes no `until_attach`, and `catch_all` wraps the `TypeError` as `50000 500 Unexpected exception` whatever the channel's state. The test also asserts that no HTTP request was made | `test_rtl10b_errors_when_not_attached` |
 | RTL19b, RTL19c, RTL20, RTL21, PC3 | a vcdiff-decoded payload equals a string literal | a `bytearray`. `EncodeDataMixin.decode` (`mixins.py:106`) leaves the vcdiff result binary because no further encoding step turns it back into text, which is correct — the specification's own `RTL19b/json-wire-form-base-1`, which does carry `utf-8/vcdiff`, receives a string. Five tests assert `b'second message'` where the specification writes the string | 5 in `channel_delta_decoding_test.py` |
-| RTB1b | 1000 jitter samples | 24, because there is no jitter generator to sample and each sample costs a whole reconnection cycle. A cycle takes up to `disconnectedRetryTimeout * 2` plus the request timeout, and every one of them has to finish before the 120000 ms suspend timer moves the retries onto `suspended_retry_timeout`, which affords 29. The standard error of the mean is 0.013 against a ±0.05 allowance, so the test still separates a uniform generator from a degenerate one | `test_rtb1b_jitter_coefficient_range` |
+| RTB1b | 1000 jitter samples | 24, because there is no jitter generator to sample and each sample costs a whole reconnection cycle. A cycle takes up to `disconnectedRetryTimeout * 2` plus the request timeout, and every one of them has to finish before the 120000 ms suspend timer moves the retries onto `suspended_retry_timeout_seconds`, which affords 29. The standard error of the mean is 0.013 against a ±0.05 allowance, so the test still separates a uniform generator from a degenerate one | `test_rtb1b_jitter_coefficient_range` |
 | RTB1 | the channel test provokes its re-attach with a channel `ERROR`, citing RTL13b | RTL14 takes a channel ERROR straight to FAILED, which is correct (see *Investigated and not defects*), so the channel never suspends and no retry timer starts. The derived test provokes the re-attach with a server-initiated DETACHED instead, which RTL13a does answer with `_request_state(ATTACHING)`; from there the scenario runs as written | `test_rtb1_suspended_channel_retry_delay` |
 
 ### Translation notes that are not deviations
@@ -2073,7 +2098,7 @@ pseudocode is not mistaken for non-compliance.
 
 | Subject | Note |
 |---|---|
-| DISCONNECTED as a restable state | RTN15a retries a drop from CONNECTED through `loop.call_soon` (`connectionmanager.py:668`) with no time passing, so DISCONNECTED is left within the same turn of the event loop and a listener registered afterwards never sees it. The heartbeat specification says so itself, under "Verifying Transient States"; tests record the whole sequence with `connection.on(...)` and assert `CONTAINS_IN_ORDER`. Where a test needs the connection to *rest* in DISCONNECTED it fails the immediate retry and raises `disconnected_retry_timeout`. Correct RTN15a behaviour |
+| DISCONNECTED as a restable state | RTN15a retries a drop from CONNECTED through `loop.call_soon` (`connectionmanager.py:668`) with no time passing, so DISCONNECTED is left within the same turn of the event loop and a listener registered afterwards never sees it. The heartbeat specification says so itself, under "Verifying Transient States"; tests record the whole sequence with `connection.on(...)` and assert `CONTAINS_IN_ORDER`. Where a test needs the connection to *rest* in DISCONNECTED it fails the immediate retry and raises `disconnected_retry_timeout_seconds`. Correct RTN15a behaviour |
 | `Channels.__iter__` | annotated `Iterator[str]`, but yields the `Channel` objects rather than their names |
 | `RealtimeChannel.publish()` | positional-only (`*args`, `channel.py:342`). The keyword form the specifications write raises `ValueError`, although `RestChannel.publish()` accepts it. Every test uses the positional form |
 | ACK `res` | every ACK in the specifications is written `res: { "serials": [...] }`, a single object. `WebSocketTransport` (`websockettransport.py:191-193`) reads `res` as a list, one entry per acknowledged ProtocolMessage, which matches the protocol definition. The specification's single object is shorthand for the one-message case |
@@ -2105,7 +2130,7 @@ pseudocode is not mistaken for non-compliance.
 | TO3l8, CD2c | `maxMessageSize` is a client option, default 65536, which `connectionDetails.maxMessageSize` overrides for realtime publishes | The option and its default match, and REST and realtime publishes both measure per TM6 and raise 40009. `ConnectionDetails.from_dict` does not parse `maxMessageSize`, so a realtime publish is checked against the client option alone. No test asserts CD2c; `test_rtn24_connection_details_override` sends the field and reads back only the details ably-python parses | Open bug, CD2c only |
 | RTN15, RTN23 | A DISCONNECTED `ErrorInfo` needs no `statusCode` | `ConnectionManager.on_disconnected` evaluates `exception.status_code >= 500` unguarded, so a DISCONNECTED whose error omits `statusCode` raises `TypeError` in a task whose exception is only logged, and the connection silently stays CONNECTED. `DISCONNECTED_MESSAGE` supplies 400 | Open bug |
 | TO3l4, TO3l5 | `httpRequestTimeout` defaults to 10000 and `httpMaxRetryCount` to 3 on the options object | Both are defaulted on `Options`. `http_max_retry_count` reads back as 3 and matches; `http_request_timeout` reads back as 10, because ably-python's is seconds where the spec's is milliseconds, on the value a caller passes as much as on the default — gated, with the measurement, under *`httpRequestTimeout` is seconds where the specification counts milliseconds* in Failing Tests | The unit is an open bug, recorded there |
-| RTC7 (TO3l3, TO3l4) | `client.options.httpOpenTimeout == 4000` and `httpRequestTimeout == 10000` | 4 and 10: both are defaulted on `Options`, in seconds where TO3l3 and TO3l4 count milliseconds. The three realtime timeouts the same test checks are milliseconds and match | Open bug, and the unit reaches the wire — `rest/proxy/RSC15l2/timeout-triggers-fallback-0` measures a request outliving its configured timeout by a factor of a thousand. Gated under *`httpRequestTimeout` is seconds where the specification counts milliseconds* in Failing Tests. Moving the HTTP durations to milliseconds is breaking, and is held back from 4.0.0 pending a decision on units across the options |
+| RTC7 (TO3l3, TO3l4) | `client.options.httpOpenTimeout == 4000` and `httpRequestTimeout == 10000` | 4 and 10: both are defaulted on `Options`, in seconds where TO3l3 and TO3l4 count milliseconds. The three realtime timeouts the same test checks read back as `realtime_request_timeout_seconds == 10`, `disconnected_retry_timeout_seconds == 15` and `suspended_retry_timeout_seconds == 30`, which is intentional: see *Timing options are seconds, and named for it* | Open bug for the HTTP pair, and the unit reaches the wire — `rest/proxy/RSC15l2/timeout-triggers-fallback-0` measures a request outliving its configured timeout by a factor of a thousand. Gated under *`httpRequestTimeout` is seconds where the specification counts milliseconds* in Failing Tests. Moving the HTTP durations to milliseconds is breaking, and is held back from 4.0.0 pending a decision on units across the options |
 | RTC1f | a `transportParams` boolean appears as `"true"` / `"false"` | `True` / `False`, because `WebSocketTransport.connect` builds the query string with `urllib.parse.urlencode`, which renders each value through `str()` (`websockettransport.py:89`). Integers are unaffected | Open bug. A caller can pass the strings directly, but a bool is what the spec's Stringifiable type admits |
 
 ### LiveObjects: the internal shapes the unit specifications assume — S-1 to S-6
@@ -2958,8 +2983,8 @@ module-level factory would outlive the test that set it and be shared by every
 client the suite builds.
 
 A derived test reaches for it where nothing else reaches the behaviour.
-`realtime_request_timeout`, `disconnected_retry_timeout`,
-`suspended_retry_timeout` and `channel_retry_timeout` are client options, so a
+`realtime_request_timeout_seconds`, `disconnected_retry_timeout_seconds`,
+`suspended_retry_timeout_seconds` and `channel_retry_timeout_seconds` are client options, so a
 real short value drives those and the test stays free of the interaction
 between faked time and the real `await`s around it. Two things have no such
 handle: `connection_state_ttl`, which is not a constructor parameter and which
@@ -3090,7 +3115,8 @@ renaming; the function name makes failures readable without it.
 `enable_fake_timers()` and `ADVANCE_TIME(ms)` correspond to the clock a client
 reads, which `rest_client(mock_http, clock=...)` replaces. The derived REST tests
 shorten the interval through a client option instead, which is what the
-specifications themselves do for `fallback_retry_timeout`, and reach for the clock
+specifications themselves do for `fallbackRetryTimeout` (`fallback_retry_timeout_seconds`
+here), and reach for the clock
 only where no option exposes the interval; see the fake time section above.
 
 ### A TokenDetails payload is recognised by its `token`, not only by `issued`
diff --git a/test/uts/helpers/mock_websocket_test.py b/test/uts/helpers/mock_websocket_test.py
index 6ecb74a3..8faeb955 100644
--- a/test/uts/helpers/mock_websocket_test.py
+++ b/test/uts/helpers/mock_websocket_test.py
@@ -35,11 +35,12 @@
 CLOSE = int(ProtocolMessageAction.CLOSE)
 
 # Short enough that a test which waits out a connect timeout stays quick, and
-# long enough that it never pre-empts a response the test means to give.
-SHORT_REQUEST_TIMEOUT = 300
+# long enough that it never pre-empts a response the test means to give. Seconds,
+# like NO_RETRY.
+SHORT_REQUEST_TIMEOUT = 0.3
 
 # Long enough that no test reconnects behind its own assertions.
-NO_RETRY = 60000
+NO_RETRY = 60
 
 
 def succeeding(message=CONNECTED_MESSAGE):
@@ -57,7 +58,7 @@ async def wait_for(predicate, timeout=3.0):
 
 async def connected(mock, **kwargs):
     """A client which has reached CONNECTED through `mock`."""
-    kwargs.setdefault('disconnected_retry_timeout', NO_RETRY)
+    kwargs.setdefault('disconnected_retry_timeout_seconds', NO_RETRY)
     client = realtime_client(mock, **kwargs)
     client.connect()
     await await_connection_state(client, ConnectionState.CONNECTED)
@@ -83,7 +84,7 @@ async def test_respond_with_success_alone_leaves_the_client_connecting():
     # A connection that opens and then says nothing is a silent server, which
     # the client waits out rather than treating as a failure
     mock = MockWebSocket(on_connection_attempt=lambda connection: connection.respond_with_success())
-    client = realtime_client(mock, realtime_request_timeout=NO_RETRY)
+    client = realtime_client(mock, realtime_request_timeout_seconds=NO_RETRY)
 
     client.connect()
     await wait_for(lambda: len(mock.connections) == 1)
@@ -93,7 +94,7 @@ async def test_respond_with_success_alone_leaves_the_client_connecting():
 
 async def test_an_unanswered_attempt_succeeds_with_no_messages():
     mock = MockWebSocket()
-    client = realtime_client(mock, realtime_request_timeout=NO_RETRY)
+    client = realtime_client(mock, realtime_request_timeout_seconds=NO_RETRY)
 
     client.connect()
     await wait_for(lambda: len(mock.connections) == 1)
@@ -107,8 +108,8 @@ async def test_respond_with_refused_is_indistinguishable_from_a_silent_server():
     # ConnectionRefusedError a refused TCP connection raises never reaches the
     # transport's failure path; the connect timeout is what ends the attempt
     mock = MockWebSocket(on_connection_attempt=lambda connection: connection.respond_with_refused())
-    client = realtime_client(mock, realtime_request_timeout=SHORT_REQUEST_TIMEOUT,
-                             disconnected_retry_timeout=NO_RETRY)
+    client = realtime_client(mock, realtime_request_timeout_seconds=SHORT_REQUEST_TIMEOUT,
+                             disconnected_retry_timeout_seconds=NO_RETRY)
 
     client.connect()
     await await_connection_state(client, ConnectionState.DISCONNECTED)
@@ -120,8 +121,8 @@ async def test_respond_with_refused_is_indistinguishable_from_a_silent_server():
 
 async def test_respond_with_timeout_reaches_the_same_generic_timeout():
     mock = MockWebSocket(on_connection_attempt=lambda connection: connection.respond_with_timeout())
-    client = realtime_client(mock, realtime_request_timeout=SHORT_REQUEST_TIMEOUT,
-                             disconnected_retry_timeout=NO_RETRY)
+    client = realtime_client(mock, realtime_request_timeout_seconds=SHORT_REQUEST_TIMEOUT,
+                             disconnected_retry_timeout_seconds=NO_RETRY)
 
     client.connect()
     await await_connection_state(client, ConnectionState.DISCONNECTED)
@@ -131,8 +132,8 @@ async def test_respond_with_timeout_reaches_the_same_generic_timeout():
 
 async def test_respond_with_dns_error_fails_the_attempt_with_its_cause():
     mock = MockWebSocket(on_connection_attempt=lambda connection: connection.respond_with_dns_error())
-    client = realtime_client(mock, realtime_request_timeout=NO_RETRY,
-                             disconnected_retry_timeout=NO_RETRY)
+    client = realtime_client(mock, realtime_request_timeout_seconds=NO_RETRY,
+                             disconnected_retry_timeout_seconds=NO_RETRY)
 
     client.connect()
     await await_connection_state(client, ConnectionState.DISCONNECTED)
@@ -146,7 +147,7 @@ async def test_respond_with_dns_error_fails_the_attempt_with_its_cause():
 async def test_respond_with_error_fails_the_connection():
     mock = MockWebSocket(on_connection_attempt=lambda connection: connection.respond_with_error(
         ERROR_MESSAGE(40000, 'Bad request')))
-    client = realtime_client(mock, realtime_request_timeout=NO_RETRY)
+    client = realtime_client(mock, realtime_request_timeout_seconds=NO_RETRY)
 
     client.connect()
     await await_connection_state(client, ConnectionState.FAILED)
@@ -158,7 +159,7 @@ async def test_respond_with_error_fails_the_connection():
 async def test_respond_with_error_can_leave_the_connection_open():
     mock = MockWebSocket(on_connection_attempt=lambda connection: connection.respond_with_error(
         ERROR_MESSAGE(40000, 'Bad request'), then_close=False))
-    client = realtime_client(mock, realtime_request_timeout=NO_RETRY)
+    client = realtime_client(mock, realtime_request_timeout_seconds=NO_RETRY)
 
     client.connect()
     await await_connection_state(client, ConnectionState.FAILED)
@@ -275,7 +276,7 @@ async def test_events_of_type_filters_the_timeline():
 
 async def test_simulate_disconnect_drops_the_transport():
     mock = MockWebSocket(on_connection_attempt=succeeding())
-    client = await connected(mock, disconnected_retry_timeout=NO_RETRY)
+    client = await connected(mock, disconnected_retry_timeout_seconds=NO_RETRY)
     states = []
     client.connection.on(lambda change: states.append(change.current))
 
@@ -302,7 +303,7 @@ async def test_simulate_disconnect_carries_its_error_to_the_state_change():
 
 async def test_send_to_client_and_close_delivers_the_message_before_the_close():
     mock = MockWebSocket(on_connection_attempt=succeeding())
-    client = await connected(mock, disconnected_retry_timeout=NO_RETRY)
+    client = await connected(mock, disconnected_retry_timeout_seconds=NO_RETRY)
 
     mock.send_to_client_and_close(ERROR_MESSAGE(40000, 'Bad request'))
     await await_connection_state(client, ConnectionState.FAILED)
@@ -316,7 +317,7 @@ async def test_send_to_client_and_close_delivers_the_message_before_the_close():
 
 async def test_a_server_sent_closed_message_leaves_the_connection_state_alone():
     mock = MockWebSocket(on_connection_attempt=succeeding())
-    client = await connected(mock, disconnected_retry_timeout=NO_RETRY)
+    client = await connected(mock, disconnected_retry_timeout_seconds=NO_RETRY)
 
     mock.send_to_client_and_close(CLOSED_MESSAGE)
     await wait_for(lambda: mock.connections[0].closed)
@@ -329,7 +330,7 @@ async def test_a_server_sent_closed_message_leaves_the_connection_state_alone():
 
 async def test_a_closed_connection_ignores_a_second_server_close():
     mock = MockWebSocket(on_connection_attempt=succeeding())
-    client = await connected(mock, disconnected_retry_timeout=NO_RETRY)
+    client = await connected(mock, disconnected_retry_timeout_seconds=NO_RETRY)
     connection = mock.active_connection
 
     states = []
@@ -372,7 +373,7 @@ async def test_a_client_close_clears_the_active_connection():
 
 async def test_await_connection_attempt_hands_the_attempt_to_the_test():
     mock = MockWebSocket()
-    client = realtime_client(mock, realtime_request_timeout=NO_RETRY)
+    client = realtime_client(mock, realtime_request_timeout_seconds=NO_RETRY)
 
     waiting = mock.await_connection_attempt(timeout=2)
     client.connect()
@@ -386,7 +387,7 @@ async def test_await_connection_attempt_hands_the_attempt_to_the_test():
 async def test_a_waiting_test_takes_precedence_over_the_connection_handler():
     handled = []
     mock = MockWebSocket(on_connection_attempt=handled.append)
-    client = realtime_client(mock, realtime_request_timeout=NO_RETRY)
+    client = realtime_client(mock, realtime_request_timeout_seconds=NO_RETRY)
 
     waiting = mock.await_connection_attempt(timeout=2)
     client.connect()
@@ -399,8 +400,8 @@ async def test_a_waiting_test_takes_precedence_over_the_connection_handler():
 
 async def test_a_second_attempt_is_caught_by_awaiting_before_responding():
     mock = MockWebSocket()
-    client = realtime_client(mock, realtime_request_timeout=NO_RETRY,
-                             disconnected_retry_timeout=50)
+    client = realtime_client(mock, realtime_request_timeout_seconds=NO_RETRY,
+                             disconnected_retry_timeout_seconds=0.05)
 
     first_attempt = mock.await_connection_attempt(timeout=2)
     client.connect()
@@ -440,8 +441,8 @@ def broken(connection):
         raise TypeError('a handler bug')
 
     mock = MockWebSocket(on_connection_attempt=broken)
-    client = realtime_client(mock, realtime_request_timeout=NO_RETRY,
-                             disconnected_retry_timeout=NO_RETRY)
+    client = realtime_client(mock, realtime_request_timeout_seconds=NO_RETRY,
+                             disconnected_retry_timeout_seconds=NO_RETRY)
 
     client.connect()
     await await_connection_state(client, ConnectionState.DISCONNECTED)
@@ -467,8 +468,8 @@ def connect(connection):
             connection.respond_with_success(CONNECTED_MESSAGE)
 
     mock = MockWebSocket(on_connection_attempt=connect)
-    client = realtime_client(mock, realtime_request_timeout=NO_RETRY,
-                             disconnected_retry_timeout=50)
+    client = realtime_client(mock, realtime_request_timeout_seconds=NO_RETRY,
+                             disconnected_retry_timeout_seconds=0.05)
 
     client.connect()
     await await_connection_state(client, ConnectionState.CONNECTED)
@@ -488,7 +489,7 @@ async def test_the_message_handler_receives_every_message_from_the_client():
 
 async def test_the_handlers_can_be_assigned_after_construction():
     mock = MockWebSocket()
-    client = realtime_client(mock, realtime_request_timeout=NO_RETRY)
+    client = realtime_client(mock, realtime_request_timeout_seconds=NO_RETRY)
 
     mock.on_connection_attempt = succeeding()
     client.connect()
@@ -701,7 +702,7 @@ async def transport():
 
 async def test_a_server_close_reaches_the_client_on_a_later_turn():
     mock = MockWebSocket(on_connection_attempt=succeeding())
-    client = await connected(mock, disconnected_retry_timeout=NO_RETRY)
+    client = await connected(mock, disconnected_retry_timeout_seconds=NO_RETRY)
     states = []
     client.connection.on(lambda change: states.append(change.current))
 
diff --git a/test/uts/realtime/integration/proxy/channel_faults_test.py b/test/uts/realtime/integration/proxy/channel_faults_test.py
index 09ae9907..1878f220 100644
--- a/test/uts/realtime/integration/proxy/channel_faults_test.py
+++ b/test/uts/realtime/integration/proxy/channel_faults_test.py
@@ -39,10 +39,10 @@
 )
 from test.uts.helpers.sandbox import extract_key_name, extract_key_secret, generate_jwt, random_id
 
-# The specification's `realtimeRequestTimeout: 3000`, in the milliseconds the client
-# option takes. It is the deadline on both the attach and the detach the two timeout
-# tests provoke (TO3l11).
-REALTIME_REQUEST_TIMEOUT_MS = 3000
+# The specification's `realtimeRequestTimeout: 3000`, in the seconds the client option
+# takes. It is the deadline on both the attach and the detach the two timeout tests
+# provoke (TO3l11).
+REALTIME_REQUEST_TIMEOUT_SECONDS = 3
 
 # The specification's `AWAIT_STATE ... WITH timeout` values, as wall-clock seconds.
 CONNECT_TIMEOUT = 15.0
@@ -119,7 +119,7 @@ async def test_rtl4f_attach_timeout_suppressed(realtime_sandbox, proxy_session):
     }])
 
     client = proxied_client(realtime_sandbox.key_str, session,
-                            realtime_request_timeout=REALTIME_REQUEST_TIMEOUT_MS)
+                            realtime_request_timeout_seconds=REALTIME_REQUEST_TIMEOUT_SECONDS)
     channel = client.channels.get(channel_name)
 
     # Record channel state changes for sequence verification
@@ -226,7 +226,7 @@ async def test_rtl5f_detach_timeout_suppressed(realtime_sandbox, proxy_session):
     session = await proxy_session(rules=[])
 
     client = proxied_client(realtime_sandbox.key_str, session,
-                            realtime_request_timeout=REALTIME_REQUEST_TIMEOUT_MS)
+                            realtime_request_timeout_seconds=REALTIME_REQUEST_TIMEOUT_SECONDS)
     channel = client.channels.get(channel_name)
 
     # Record channel state changes for sequence verification
diff --git a/test/uts/realtime/integration/proxy/connection_open_failures_test.py b/test/uts/realtime/integration/proxy/connection_open_failures_test.py
index 9b7de332..800d3014 100644
--- a/test/uts/realtime/integration/proxy/connection_open_failures_test.py
+++ b/test/uts/realtime/integration/proxy/connection_open_failures_test.py
@@ -39,9 +39,9 @@
 RECOVERY_TIMEOUT = 30
 
 # The specification's `realtimeRequestTimeout: 3000` and
-# `disconnectedRetryTimeout: 2000`. Both are milliseconds in ably-python too.
-REALTIME_REQUEST_TIMEOUT_MS = 3000
-DISCONNECTED_RETRY_TIMEOUT_MS = 2000
+# `disconnectedRetryTimeout: 2000`, in the seconds ably-python's options take.
+REALTIME_REQUEST_TIMEOUT_SECONDS = 3
+DISCONNECTED_RETRY_TIMEOUT_SECONDS = 2
 
 
 def connection_id(client):
@@ -228,7 +228,7 @@ async def test_rtn14d_retry_after_refused(realtime_sandbox, proxy_session):
         tls=False,
         use_binary_protocol=False,
         auto_connect=False,
-        disconnected_retry_timeout=DISCONNECTED_RETRY_TIMEOUT_MS,
+        disconnected_retry_timeout_seconds=DISCONNECTED_RETRY_TIMEOUT_SECONDS,
     )
     state_changes = record_states(client)
 
@@ -320,7 +320,7 @@ async def test_rtn14c_connection_timeout(realtime_sandbox, proxy_session):
         tls=False,
         use_binary_protocol=False,
         auto_connect=False,
-        realtime_request_timeout=REALTIME_REQUEST_TIMEOUT_MS,
+        realtime_request_timeout_seconds=REALTIME_REQUEST_TIMEOUT_SECONDS,
     )
     state_changes = record_states(client)
 
diff --git a/test/uts/realtime/integration/proxy/connection_resume_test.py b/test/uts/realtime/integration/proxy/connection_resume_test.py
index 6f93dff8..5e11cbfa 100644
--- a/test/uts/realtime/integration/proxy/connection_resume_test.py
+++ b/test/uts/realtime/integration/proxy/connection_resume_test.py
@@ -643,8 +643,8 @@ async def test_rtn14h_resume_after_ttl_expiry(realtime_sandbox, proxy_session):
         },
     ])
 
-    # A short `suspended_retry_timeout` so the test does not wait long after SUSPENDED.
-    client = proxy_realtime_client(session, realtime_sandbox.key_str, suspended_retry_timeout=1000)
+    # A short `suspended_retry_timeout_seconds` so the test does not wait long after SUSPENDED.
+    client = proxy_realtime_client(session, realtime_sandbox.key_str, suspended_retry_timeout_seconds=1)
     state_changes = record_states(client.connection)
 
     # Connect through proxy -- first CONNECTED is replaced with short TTL and known connectionId
diff --git a/test/uts/realtime/unit/auth/auth_callback_errors_test.py b/test/uts/realtime/unit/auth/auth_callback_errors_test.py
index 768cd870..1bfbacd6 100644
--- a/test/uts/realtime/unit/auth/auth_callback_errors_test.py
+++ b/test/uts/realtime/unit/auth/auth_callback_errors_test.py
@@ -21,8 +21,8 @@
 AUTH_MESSAGE = {'action': int(ProtocolMessageAction.AUTH)}
 
 # A retry far enough out that a DISCONNECTED connection does not reconnect
-# behind the assertions.
-NO_RECONNECT = 60000
+# behind the assertions, in seconds.
+NO_RECONNECT = 60
 
 # The specification's 128KiB limit, exceeded by one character.
 OVERSIZED_TOKEN = 'x' * 131073
@@ -60,7 +60,7 @@ async def auth_callback(params):
 
     mock_ws = MockWebSocket(on_connection_attempt=connect_successfully())
     client = realtime_client(mock_ws, auth_callback=auth_callback, use_binary_protocol=False,
-                             disconnected_retry_timeout=NO_RECONNECT)
+                             disconnected_retry_timeout_seconds=NO_RECONNECT)
 
     state_changes = []
     client.connection.on(lambda change: state_changes.append(change))
@@ -92,8 +92,8 @@ async def auth_callback(params):
     clock = FakeClock()
     mock_ws = MockWebSocket(on_connection_attempt=connect_successfully())
     client = realtime_client(mock_ws, clock=clock, auth_callback=auth_callback,
-                             realtime_request_timeout=10000, use_binary_protocol=False,
-                             disconnected_retry_timeout=NO_RECONNECT)
+                             realtime_request_timeout_seconds=10, use_binary_protocol=False,
+                             disconnected_retry_timeout_seconds=NO_RECONNECT)
 
     state_changes = []
     client.connection.on(lambda change: state_changes.append(change))
@@ -162,7 +162,7 @@ def on_connection_attempt(conn):
 
     mock_ws = MockWebSocket(on_connection_attempt=on_connection_attempt)
     client = realtime_client(mock_ws, auth_callback=auth_callback, use_binary_protocol=False,
-                             disconnected_retry_timeout=NO_RECONNECT)
+                             disconnected_retry_timeout_seconds=NO_RECONNECT)
 
     state_changes = []
     client.connection.on(lambda change: state_changes.append(change))
@@ -203,7 +203,7 @@ async def auth_callback(params):
 
     mock_ws = MockWebSocket(on_connection_attempt=connect_successfully())
     client = realtime_client(mock_ws, auth_callback=auth_callback, use_binary_protocol=False,
-                             disconnected_retry_timeout=NO_RECONNECT)
+                             disconnected_retry_timeout_seconds=NO_RECONNECT)
 
     client.connect()
     await await_connection_state(client, ConnectionState.CONNECTED)
@@ -227,7 +227,7 @@ async def auth_callback(params):
 
     mock_ws = MockWebSocket(on_connection_attempt=connect_successfully())
     client = realtime_client(mock_ws, auth_callback=auth_callback, use_binary_protocol=False,
-                             disconnected_retry_timeout=NO_RECONNECT)
+                             disconnected_retry_timeout_seconds=NO_RECONNECT)
 
     client.connect()
     await await_connection_state(client, ConnectionState.DISCONNECTED)
@@ -250,7 +250,7 @@ async def auth_callback(params):
 
     mock_ws = MockWebSocket(on_connection_attempt=connect_successfully())
     client = realtime_client(mock_ws, auth_callback=auth_callback, use_binary_protocol=False,
-                             disconnected_retry_timeout=NO_RECONNECT)
+                             disconnected_retry_timeout_seconds=NO_RECONNECT)
 
     client.connect()
     await await_connection_state(client, ConnectionState.DISCONNECTED)
diff --git a/test/uts/realtime/unit/auth/connection_auth_test.py b/test/uts/realtime/unit/auth/connection_auth_test.py
index 3ce4fd42..9402fa64 100644
--- a/test/uts/realtime/unit/auth/connection_auth_test.py
+++ b/test/uts/realtime/unit/auth/connection_auth_test.py
@@ -16,8 +16,8 @@
 AUTH_MESSAGE = {'action': int(ProtocolMessageAction.AUTH)}
 
 # A retry far enough out that a DISCONNECTED connection does not reconnect
-# behind the assertions.
-NO_RECONNECT = 60000
+# behind the assertions, in seconds.
+NO_RECONNECT = 60
 
 
 def now():
@@ -77,7 +77,7 @@ def on_connection_attempt(conn):
         conn.respond_with_success(connected_message('connection-id', connectionKey='connection-key'))
 
     mock_ws = MockWebSocket(on_connection_attempt=on_connection_attempt)
-    client = realtime_client(mock_ws, auth_callback=auth_callback, disconnected_retry_timeout=NO_RECONNECT)
+    client = realtime_client(mock_ws, auth_callback=auth_callback, disconnected_retry_timeout_seconds=NO_RECONNECT)
 
     client.connect()
     await await_connection_state(client, ConnectionState.DISCONNECTED)
@@ -146,7 +146,7 @@ async def auth_callback(params):
         return TokenDetails(token=f'valid-token-{auth_callback_count}', expires=now() + 3600000)
 
     mock_ws = MockWebSocket(on_connection_attempt=connect_successfully())
-    client = realtime_client(mock_ws, auth_callback=auth_callback, disconnected_retry_timeout=NO_RECONNECT)
+    client = realtime_client(mock_ws, auth_callback=auth_callback, disconnected_retry_timeout_seconds=NO_RECONNECT)
 
     client.connect()
     await await_connection_state(client, ConnectionState.DISCONNECTED)
@@ -202,7 +202,7 @@ async def auth_callback(params):
         raise AblyException('Account disabled', 403, 40300)
 
     mock_ws = MockWebSocket(on_connection_attempt=connect_successfully())
-    client = realtime_client(mock_ws, auth_callback=auth_callback, disconnected_retry_timeout=NO_RECONNECT)
+    client = realtime_client(mock_ws, auth_callback=auth_callback, disconnected_retry_timeout_seconds=NO_RECONNECT)
 
     client.connect()
     await await_connection_state(client, ConnectionState.FAILED)
@@ -226,7 +226,7 @@ async def auth_callback(params):
         raise AblyException('Account suspended', 403, 40300)
 
     mock_ws = MockWebSocket(on_connection_attempt=connect_successfully())
-    client = realtime_client(mock_ws, auth_callback=auth_callback, disconnected_retry_timeout=NO_RECONNECT)
+    client = realtime_client(mock_ws, auth_callback=auth_callback, disconnected_retry_timeout_seconds=NO_RECONNECT)
 
     client.connect()
     await await_connection_state(client, ConnectionState.CONNECTED)
diff --git a/test/uts/realtime/unit/channels/channel_attach_test.py b/test/uts/realtime/unit/channels/channel_attach_test.py
index 4401c58d..cf10be0f 100644
--- a/test/uts/realtime/unit/channels/channel_attach_test.py
+++ b/test/uts/realtime/unit/channels/channel_attach_test.py
@@ -214,7 +214,7 @@ def on_message_from_client(msg):
 
     mock_ws.on_message_from_client = on_message_from_client
     client = realtime_client(
-        mock_ws, clock=clock, realtime_request_timeout=300, suspended_retry_timeout=2000)
+        mock_ws, clock=clock, realtime_request_timeout_seconds=0.3, suspended_retry_timeout_seconds=2)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -290,7 +290,8 @@ async def test_rtl4b_fails_connection_suspended():
     clock = FakeClock()
 
     mock_ws = MockWebSocket(on_connection_attempt=lambda conn: conn.respond_with_refused())
-    client = realtime_client(mock_ws, clock=clock, realtime_request_timeout=300, channel_retry_timeout=100)
+    client = realtime_client(mock_ws, clock=clock, realtime_request_timeout_seconds=0.3,
+                             channel_retry_timeout_seconds=0.1)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -438,7 +439,7 @@ async def test_rtl4f_timeout_to_suspended():
     mock_ws = MockWebSocket(
         on_connection_attempt=lambda conn: conn.respond_with_success(CONNECTED_MESSAGE_NO_IDLE),
     )
-    client = realtime_client(mock_ws, clock=clock, realtime_request_timeout=100)
+    client = realtime_client(mock_ws, clock=clock, realtime_request_timeout_seconds=0.1)
     channel = client.channels.get(channel_name)
 
     client.connect()
diff --git a/test/uts/realtime/unit/channels/channel_connection_state_test.py b/test/uts/realtime/unit/channels/channel_connection_state_test.py
index d700fce5..0eaaa6bf 100644
--- a/test/uts/realtime/unit/channels/channel_connection_state_test.py
+++ b/test/uts/realtime/unit/channels/channel_connection_state_test.py
@@ -332,7 +332,7 @@ async def test_rtl3c_suspended_attached_to_suspended():
     # A refused attempt is only given up on when the connecting transition timer
     # expires, so a short request timeout keeps each retry cycle short
     client = realtime_client(
-        mock_ws, clock=clock, disconnected_retry_timeout=1000, realtime_request_timeout=300)
+        mock_ws, clock=clock, disconnected_retry_timeout_seconds=1, realtime_request_timeout_seconds=0.3)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -371,7 +371,7 @@ async def test_rtl3c_suspended_attaching_to_suspended():
     # RTL4f suspends the channel on its own before the connection gets there,
     # and the transition RTL3c is about never happens
     client = realtime_client(
-        mock_ws, clock=clock, disconnected_retry_timeout=1000, realtime_request_timeout=300000)
+        mock_ws, clock=clock, disconnected_retry_timeout_seconds=1, realtime_request_timeout_seconds=300)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -409,7 +409,7 @@ async def test_rtl3d_reattach_attached_with_serial():
     )
     mock_ws.on_message_from_client = echo_attach_and_detach(
         mock_ws, attach_messages, channelSerial='serial-001')
-    client = await connected_client(mock_ws, disconnected_retry_timeout=100)
+    client = await connected_client(mock_ws, disconnected_retry_timeout_seconds=0.1)
     channel = client.channels.get(channel_name)
 
     await asyncio.wait_for(channel.attach(), OPERATION_TIMEOUT)
@@ -444,8 +444,8 @@ async def test_rtl3d_reattach_suspended_channels():
     )
     mock_ws.on_message_from_client = echo_attach_and_detach(mock_ws, attach_messages)
     client = realtime_client(
-        mock_ws, clock=clock, disconnected_retry_timeout=1000, suspended_retry_timeout=2000,
-        realtime_request_timeout=300)
+        mock_ws, clock=clock, disconnected_retry_timeout_seconds=1, suspended_retry_timeout_seconds=2,
+        realtime_request_timeout_seconds=0.3)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -486,7 +486,7 @@ async def test_rtl3d_init_detached_not_reattached():
         on_connection_attempt=lambda conn: conn.respond_with_success(CONNECTED_MESSAGE),
     )
     mock_ws.on_message_from_client = echo_attach_and_detach(mock_ws, attach_messages)
-    client = await connected_client(mock_ws, disconnected_retry_timeout=100)
+    client = await connected_client(mock_ws, disconnected_retry_timeout_seconds=0.1)
     initialized_channel = client.channels.get(initialized_channel_name)
     detached_channel = client.channels.get(detached_channel_name)
 
@@ -524,7 +524,7 @@ async def test_rtl3d_multiple_channels_reattached():
         on_connection_attempt=lambda conn: conn.respond_with_success(CONNECTED_MESSAGE),
     )
     mock_ws.on_message_from_client = echo_attach_and_detach(mock_ws, attach_messages)
-    client = await connected_client(mock_ws, disconnected_retry_timeout=100)
+    client = await connected_client(mock_ws, disconnected_retry_timeout_seconds=0.1)
     channel1 = client.channels.get(channel1_name)
     channel2 = client.channels.get(channel2_name)
 
diff --git a/test/uts/realtime/unit/channels/channel_detach_test.py b/test/uts/realtime/unit/channels/channel_detach_test.py
index fe176595..36266a01 100644
--- a/test/uts/realtime/unit/channels/channel_detach_test.py
+++ b/test/uts/realtime/unit/channels/channel_detach_test.py
@@ -229,7 +229,7 @@ def on_message_from_client(msg):
             detach_messages.append(msg)
 
     mock_ws.on_message_from_client = on_message_from_client
-    client = realtime_client(mock_ws, clock=clock, realtime_request_timeout=100)
+    client = realtime_client(mock_ws, clock=clock, realtime_request_timeout_seconds=0.1)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -293,7 +293,7 @@ async def test_rtl5l_detach_attached_when_disconnected():
         on_connection_attempt=lambda conn: conn.respond_with_success(CONNECTED_MESSAGE_NO_IDLE),
     )
     client = realtime_client(
-        mock_ws, clock=clock, realtime_request_timeout=300, disconnected_retry_timeout=60000)
+        mock_ws, clock=clock, realtime_request_timeout_seconds=0.3, disconnected_retry_timeout_seconds=60)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -379,7 +379,7 @@ def on_message_from_client(msg):
             mock_ws.send_to_client(attached_message(channel_name))
 
     mock_ws.on_message_from_client = on_message_from_client
-    client = realtime_client(mock_ws, clock=clock, realtime_request_timeout=100)
+    client = realtime_client(mock_ws, clock=clock, realtime_request_timeout_seconds=0.1)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -421,7 +421,7 @@ def on_message_from_client(msg):
                 mock_ws.send_to_client(detached_message(channel_name))
 
     mock_ws.on_message_from_client = on_message_from_client
-    client = await connected_client(mock_ws, realtime_request_timeout=300)
+    client = await connected_client(mock_ws, realtime_request_timeout_seconds=0.3)
     channel = client.channels.get(channel_name)
 
     await asyncio.wait_for(channel.attach(), OPERATION_TIMEOUT)
diff --git a/test/uts/realtime/unit/channels/channel_error_test.py b/test/uts/realtime/unit/channels/channel_error_test.py
index 268eca60..442ac7a9 100644
--- a/test/uts/realtime/unit/channels/channel_error_test.py
+++ b/test/uts/realtime/unit/channels/channel_error_test.py
@@ -220,7 +220,7 @@ def on_message_from_client(msg):
 
     mock_ws.on_message_from_client = on_message_from_client
     client = realtime_client(
-        mock_ws, clock=clock, realtime_request_timeout=100, channel_retry_timeout=200)
+        mock_ws, clock=clock, realtime_request_timeout_seconds=0.1, channel_retry_timeout_seconds=0.2)
     channel = client.channels.get(channel_name)
 
     client.connect()
diff --git a/test/uts/realtime/unit/channels/channel_properties_test.py b/test/uts/realtime/unit/channels/channel_properties_test.py
index 212f6f79..7d8d8783 100644
--- a/test/uts/realtime/unit/channels/channel_properties_test.py
+++ b/test/uts/realtime/unit/channels/channel_properties_test.py
@@ -342,7 +342,7 @@ def on_message_from_client(msg):
             # A second ATTACH goes unanswered, so it times out into SUSPENDED
 
     mock_ws.on_message_from_client = on_message_from_client
-    client = realtime_client(mock_ws, clock=clock, realtime_request_timeout=100)
+    client = realtime_client(mock_ws, clock=clock, realtime_request_timeout_seconds=0.1)
     channel = client.channels.get(channel_name)
 
     client.connect()
diff --git a/test/uts/realtime/unit/channels/channel_publish_pending_test.py b/test/uts/realtime/unit/channels/channel_publish_pending_test.py
index 337edfd2..d38c79e6 100644
--- a/test/uts/realtime/unit/channels/channel_publish_pending_test.py
+++ b/test/uts/realtime/unit/channels/channel_publish_pending_test.py
@@ -78,7 +78,7 @@ def on_connection_attempt(conn):
 
     mock_ws = MockWebSocket(on_connection_attempt=on_connection_attempt)
     mock_ws.on_message_from_client = attach_only_server(mock_ws)
-    client = await connected_client(mock_ws, clock=clock, disconnected_retry_timeout=1000)
+    client = await connected_client(mock_ws, clock=clock, disconnected_retry_timeout_seconds=1)
     channel = client.channels.get(channel_name)
 
     await channel.attach()
diff --git a/test/uts/realtime/unit/channels/channel_publish_test.py b/test/uts/realtime/unit/channels/channel_publish_test.py
index bd531b82..4de7161c 100644
--- a/test/uts/realtime/unit/channels/channel_publish_test.py
+++ b/test/uts/realtime/unit/channels/channel_publish_test.py
@@ -367,7 +367,7 @@ def on_connection_attempt(conn):
     mock_ws = MockWebSocket(on_connection_attempt=on_connection_attempt)
     mock_ws.on_message_from_client = attaching_server(mock_ws, captured_messages)
     # A retry timeout longer than the test keeps the connection in DISCONNECTED
-    client = await connected_client(mock_ws, disconnected_retry_timeout=60000)
+    client = await connected_client(mock_ws, disconnected_retry_timeout_seconds=60)
     channel = client.channels.get(channel_name)
 
     state_changes = []
@@ -431,7 +431,7 @@ async def test_rtl6c4_fails_conn_suspended():
     channel_name = f'test-RTL6c4-suspended-{random_id()}'
     clock = FakeClock()
     mock_ws = MockWebSocket(on_connection_attempt=lambda conn: conn.respond_with_refused())
-    client = realtime_client(mock_ws, clock=clock, disconnected_retry_timeout=1000)
+    client = realtime_client(mock_ws, clock=clock, disconnected_retry_timeout_seconds=1)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -497,7 +497,7 @@ def on_message_from_client(msg):
     mock_ws = MockWebSocket(
         on_connection_attempt=lambda conn: conn.respond_with_success(CONNECTED_MESSAGE),
         on_message_from_client=on_message_from_client)
-    client = await connected_client(mock_ws, clock=clock, realtime_request_timeout=100)
+    client = await connected_client(mock_ws, clock=clock, realtime_request_timeout_seconds=0.1)
     channel = client.channels.get(channel_name)
 
     attach_task = asyncio.ensure_future(channel.attach())
diff --git a/test/uts/realtime/unit/channels/channel_server_initiated_detach_test.py b/test/uts/realtime/unit/channels/channel_server_initiated_detach_test.py
index 5b7e10c5..623ffdd1 100644
--- a/test/uts/realtime/unit/channels/channel_server_initiated_detach_test.py
+++ b/test/uts/realtime/unit/channels/channel_server_initiated_detach_test.py
@@ -127,7 +127,7 @@ def on_message_from_client(msg):
 
     mock_ws.on_message_from_client = on_message_from_client
     client = realtime_client(
-        mock_ws, clock=clock, realtime_request_timeout=100, channel_retry_timeout=60000)
+        mock_ws, clock=clock, realtime_request_timeout_seconds=0.1, channel_retry_timeout_seconds=60)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -172,7 +172,7 @@ def on_message_from_client(msg):
 
     mock_ws.on_message_from_client = on_message_from_client
     client = realtime_client(
-        mock_ws, clock=clock, realtime_request_timeout=100, channel_retry_timeout=200)
+        mock_ws, clock=clock, realtime_request_timeout_seconds=0.1, channel_retry_timeout_seconds=0.2)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -236,7 +236,7 @@ def on_message_from_client(msg):
 
     mock_ws.on_message_from_client = on_message_from_client
     client = realtime_client(
-        mock_ws, clock=clock, realtime_request_timeout=500, channel_retry_timeout=200)
+        mock_ws, clock=clock, realtime_request_timeout_seconds=0.5, channel_retry_timeout_seconds=0.2)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -292,7 +292,7 @@ def on_message_from_client(msg):
 
     mock_ws.on_message_from_client = on_message_from_client
     client = realtime_client(
-        mock_ws, clock=clock, realtime_request_timeout=100, channel_retry_timeout=200)
+        mock_ws, clock=clock, realtime_request_timeout_seconds=0.1, channel_retry_timeout_seconds=0.2)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -359,7 +359,7 @@ def on_message_from_client(msg):
 
     mock_ws.on_message_from_client = on_message_from_client
     client = realtime_client(
-        mock_ws, clock=clock, realtime_request_timeout=100, channel_retry_timeout=200)
+        mock_ws, clock=clock, realtime_request_timeout_seconds=0.1, channel_retry_timeout_seconds=0.2)
     channel = client.channels.get(channel_name)
 
     client.connect()
diff --git a/test/uts/realtime/unit/client/realtime_timeouts_test.py b/test/uts/realtime/unit/client/realtime_timeouts_test.py
index 09da81d4..c466f7fb 100644
--- a/test/uts/realtime/unit/client/realtime_timeouts_test.py
+++ b/test/uts/realtime/unit/client/realtime_timeouts_test.py
@@ -28,7 +28,8 @@
 IDLE_FREE_CONNECTED_MESSAGE = connected_message(
     'connection-id', connectionKey='connection-key', maxIdleInterval=0, connectionStateTtl=120000)
 
-CUSTOM_REQUEST_TIMEOUT = 500
+# The specification's `realtimeRequestTimeout: 500`, in seconds
+CUSTOM_REQUEST_TIMEOUT = 0.5
 
 
 def attached_message(channel_name):
@@ -49,7 +50,7 @@ async def test_rtc7_attach_request_timeout():
     )
     clock = FakeClock()
     client = realtime_client(mock_ws, clock=clock, key=SPEC_KEY, auto_connect=False,
-                             realtime_request_timeout=CUSTOM_REQUEST_TIMEOUT)
+                             realtime_request_timeout_seconds=CUSTOM_REQUEST_TIMEOUT)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -89,7 +90,7 @@ def on_message_from_client(message):
     )
     clock = FakeClock()
     client = realtime_client(mock_ws, clock=clock, key=SPEC_KEY, auto_connect=False,
-                             realtime_request_timeout=CUSTOM_REQUEST_TIMEOUT)
+                             realtime_request_timeout_seconds=CUSTOM_REQUEST_TIMEOUT)
     channel = client.channels.get(channel_name)
 
     client.connect()
@@ -125,7 +126,7 @@ def on_connection_attempt(conn):
         else:
             # The spec refuses the attempt. `ws_connect` catches only WebSocketException
             # and socket.gaierror, so a refused connection is left to the transition
-            # timer and takes `realtime_request_timeout` to surface; a DNS failure
+            # timer and takes `realtime_request_timeout_seconds` to surface; a DNS failure
             # fails fast and reaches the retry logic the same way. See
             # deviations.md.
             conn.respond_with_dns_error()
@@ -138,7 +139,7 @@ def on_connection_attempt(conn):
     )
     clock = FakeClock()
     client = realtime_client(mock_ws, mock_http=mock_http, clock=clock, key=SPEC_KEY,
-                             auto_connect=False, disconnected_retry_timeout=2000, fallback_hosts=[])
+                             auto_connect=False, disconnected_retry_timeout_seconds=2, fallback_hosts=[])
 
     client.connect()
     await await_connection_state(client, ConnectionState.CONNECTED)
@@ -168,9 +169,13 @@ def on_connection_attempt(conn):
 async def test_rtc7_default_timeouts_applied():
     client = realtime_client(key=SPEC_KEY, auto_connect=False)
 
-    assert client.options.realtime_request_timeout == 10000
-    assert client.options.disconnected_retry_timeout == 15000
-    assert client.options.suspended_retry_timeout == 30000
+    # DEVIATION: the spec asserts realtimeRequestTimeout == 10000, disconnectedRetryTimeout
+    # == 15000 and suspendedRetryTimeout == 30000. ably-python's timing options are in
+    # seconds and named for it, so the same defaults read back as 10, 15 and 30 under
+    # `*_seconds` names. See deviations.md.
+    assert client.options.realtime_request_timeout_seconds == 10
+    assert client.options.disconnected_retry_timeout_seconds == 15
+    assert client.options.suspended_retry_timeout_seconds == 30
 
     # DEVIATION: the spec asserts httpOpenTimeout == 4000 and httpRequestTimeout ==
     # 10000. ably-python's HTTP timeouts are in seconds rather than milliseconds, so the
diff --git a/test/uts/realtime/unit/connection/backoff_jitter_test.py b/test/uts/realtime/unit/connection/backoff_jitter_test.py
index eee5a880..015618cc 100644
--- a/test/uts/realtime/unit/connection/backoff_jitter_test.py
+++ b/test/uts/realtime/unit/connection/backoff_jitter_test.py
@@ -23,12 +23,13 @@
 CONNECTED_MESSAGE = connected_message('connection-id', connectionKey='connection-key')
 
 # Short enough that a refused attempt, which reaches no failure path of its own and
-# so ends on the transition timer, does not crowd out the retry delays being measured
+# so ends on the transition timer, does not crowd out the retry delays being measured.
+# Milliseconds, like every duration here but the client options
 REQUEST_TIMEOUT = 50
 
 # The connection is suspended once it has been disconnected for
 # `Defaults.connection_state_ttl`, after which retries move to
-# `suspended_retry_timeout`; every sample has to be taken before that
+# `suspended_retry_timeout_seconds`; every sample has to be taken before that
 CONNECTION_STATE_TTL = 120000
 
 
@@ -57,7 +58,7 @@ def retry_delays(transitions, scheduling_state, retrying_state):
     return delays
 
 
-async def measure_disconnected_retry_delays(count, disconnected_retry_timeout):
+async def measure_disconnected_retry_delays(count, disconnected_retry_timeout_ms):
     """Drives a connection through repeated failed reconnections, returning the
     delay before each retry."""
     connection_attempts = []
@@ -73,8 +74,8 @@ def on_connection_attempt(conn):
     clock = FakeClock()
     client = realtime_client(
         mock_ws, clock=clock, key='appId.keyId:keySecret', use_binary_protocol=False,
-        disconnected_retry_timeout=disconnected_retry_timeout,
-        realtime_request_timeout=REQUEST_TIMEOUT,
+        disconnected_retry_timeout_seconds=disconnected_retry_timeout_ms / 1000,
+        realtime_request_timeout_seconds=REQUEST_TIMEOUT / 1000,
     )
 
     transitions = []
@@ -87,7 +88,7 @@ def on_connection_attempt(conn):
     await settle()
 
     while clock.now < CONNECTION_STATE_TTL:
-        await clock.advance(disconnected_retry_timeout * 2 + REQUEST_TIMEOUT)
+        await clock.advance(disconnected_retry_timeout_ms * 2 + REQUEST_TIMEOUT)
         delays = retry_delays(transitions, ConnectionState.DISCONNECTED, ConnectionState.CONNECTING)
         if len(delays) >= count:
             return delays
@@ -149,32 +150,32 @@ async def test_rtb1b_jitter_coefficient_range():
 # UTS: realtime/unit/RTB1/disconnected-retry-delay-0
 @deviation
 async def test_rtb1_disconnected_retry_delay():
-    disconnected_retry_timeout = 2000
-    retry_delays_observed = await measure_disconnected_retry_delays(5, disconnected_retry_timeout)
+    disconnected_retry_timeout_ms = 2000
+    retry_delays_observed = await measure_disconnected_retry_delays(5, disconnected_retry_timeout_ms)
 
     assert len(retry_delays_observed) >= 5
 
-    assert retry_delays_observed[0] >= disconnected_retry_timeout * 1.0 * 0.8
-    assert retry_delays_observed[0] <= disconnected_retry_timeout * 1.0
+    assert retry_delays_observed[0] >= disconnected_retry_timeout_ms * 1.0 * 0.8
+    assert retry_delays_observed[0] <= disconnected_retry_timeout_ms * 1.0
 
-    assert retry_delays_observed[1] >= disconnected_retry_timeout * (4.0 / 3.0) * 0.8
-    assert retry_delays_observed[1] <= disconnected_retry_timeout * (4.0 / 3.0)
+    assert retry_delays_observed[1] >= disconnected_retry_timeout_ms * (4.0 / 3.0) * 0.8
+    assert retry_delays_observed[1] <= disconnected_retry_timeout_ms * (4.0 / 3.0)
 
-    assert retry_delays_observed[2] >= disconnected_retry_timeout * (5.0 / 3.0) * 0.8
-    assert retry_delays_observed[2] <= disconnected_retry_timeout * (5.0 / 3.0)
+    assert retry_delays_observed[2] >= disconnected_retry_timeout_ms * (5.0 / 3.0) * 0.8
+    assert retry_delays_observed[2] <= disconnected_retry_timeout_ms * (5.0 / 3.0)
 
-    assert retry_delays_observed[3] >= disconnected_retry_timeout * 2.0 * 0.8
-    assert retry_delays_observed[3] <= disconnected_retry_timeout * 2.0
+    assert retry_delays_observed[3] >= disconnected_retry_timeout_ms * 2.0 * 0.8
+    assert retry_delays_observed[3] <= disconnected_retry_timeout_ms * 2.0
 
-    assert retry_delays_observed[4] >= disconnected_retry_timeout * 2.0 * 0.8
-    assert retry_delays_observed[4] <= disconnected_retry_timeout * 2.0
+    assert retry_delays_observed[4] >= disconnected_retry_timeout_ms * 2.0 * 0.8
+    assert retry_delays_observed[4] <= disconnected_retry_timeout_ms * 2.0
 
 
 # UTS: realtime/unit/RTB1/suspended-channel-retry-delay-1
 @deviation
 async def test_rtb1_suspended_channel_retry_delay():
     channel_name = 'test-RTB1-channel'
-    channel_retry_timeout = 3000
+    channel_retry_timeout_ms = 3000
 
     mock_ws = MockWebSocket(
         on_connection_attempt=lambda conn: conn.respond_with_success(CONNECTED_MESSAGE),
@@ -182,7 +183,7 @@ async def test_rtb1_suspended_channel_retry_delay():
     clock = FakeClock()
     client = realtime_client(
         mock_ws, clock=clock, key='appId.keyId:keySecret', use_binary_protocol=False,
-        channel_retry_timeout=channel_retry_timeout,
+        channel_retry_timeout_seconds=channel_retry_timeout_ms / 1000,
     )
 
     attach_count = []
@@ -237,14 +238,14 @@ def on_message_from_client(message):
 
     assert len(delays) >= 4
 
-    assert delays[0] >= channel_retry_timeout * 1.0 * 0.8
-    assert delays[0] <= channel_retry_timeout * 1.0
+    assert delays[0] >= channel_retry_timeout_ms * 1.0 * 0.8
+    assert delays[0] <= channel_retry_timeout_ms * 1.0
 
-    assert delays[1] >= channel_retry_timeout * (4.0 / 3.0) * 0.8
-    assert delays[1] <= channel_retry_timeout * (4.0 / 3.0)
+    assert delays[1] >= channel_retry_timeout_ms * (4.0 / 3.0) * 0.8
+    assert delays[1] <= channel_retry_timeout_ms * (4.0 / 3.0)
 
-    assert delays[2] >= channel_retry_timeout * (5.0 / 3.0) * 0.8
-    assert delays[2] <= channel_retry_timeout * (5.0 / 3.0)
+    assert delays[2] >= channel_retry_timeout_ms * (5.0 / 3.0) * 0.8
+    assert delays[2] <= channel_retry_timeout_ms * (5.0 / 3.0)
 
-    assert delays[3] >= channel_retry_timeout * 2.0 * 0.8
-    assert delays[3] <= channel_retry_timeout * 2.0
+    assert delays[3] >= channel_retry_timeout_ms * 2.0 * 0.8
+    assert delays[3] <= channel_retry_timeout_ms * 2.0
diff --git a/test/uts/realtime/unit/connection/connection_failures_test.py b/test/uts/realtime/unit/connection/connection_failures_test.py
index ffbcd2c8..df62626e 100644
--- a/test/uts/realtime/unit/connection/connection_failures_test.py
+++ b/test/uts/realtime/unit/connection/connection_failures_test.py
@@ -343,10 +343,10 @@ def on_connection_attempt(conn):
     clock = FakeClock()
     client = realtime_client(
         mock_ws, clock=clock, key='appId.keyId:keySecret',
-        disconnected_retry_timeout=1000, suspended_retry_timeout=2000,
+        disconnected_retry_timeout_seconds=1, suspended_retry_timeout_seconds=2,
         # A refused connection reaches no failure path of its own, so each attempt
         # ends on the transition timer; a short one keeps the retry cycle turning
-        realtime_request_timeout=1000,
+        realtime_request_timeout_seconds=1,
     )
 
     states = []
@@ -402,7 +402,7 @@ def on_connection_attempt(conn):
     # A token error met while CONNECTING is retried on the retry timer rather than
     # immediately, so the retry interval is kept short
     client = realtime_client(mock_ws, mock_http=mock_http, key='appId.keyId:keySecret',
-                             disconnected_retry_timeout=100)
+                             disconnected_retry_timeout_seconds=0.1)
 
     client.connect()
     await await_connection_state(client, ConnectionState.CONNECTED)
diff --git a/test/uts/realtime/unit/connection/connection_id_key_test.py b/test/uts/realtime/unit/connection/connection_id_key_test.py
index 32f1ecbc..0fa8a63a 100644
--- a/test/uts/realtime/unit/connection/connection_id_key_test.py
+++ b/test/uts/realtime/unit/connection/connection_id_key_test.py
@@ -179,7 +179,7 @@ def on_connection_attempt(conn):
     mock_ws = MockWebSocket(on_connection_attempt=on_connection_attempt)
     clock = FakeClock()
     client = realtime_client(
-        mock_ws, clock=clock, disconnected_retry_timeout=1000, suspended_retry_timeout=100)
+        mock_ws, clock=clock, disconnected_retry_timeout_seconds=1, suspended_retry_timeout_seconds=0.1)
 
     client.connect()
     await await_connection_state(client, ConnectionState.CONNECTED)
diff --git a/test/uts/realtime/unit/connection/connection_open_failures_test.py b/test/uts/realtime/unit/connection/connection_open_failures_test.py
index 0224e5b1..f1310bf4 100644
--- a/test/uts/realtime/unit/connection/connection_open_failures_test.py
+++ b/test/uts/realtime/unit/connection/connection_open_failures_test.py
@@ -83,7 +83,7 @@ def on_connection_attempt(conn):
     # A token error met while CONNECTING is retried on the retry timer rather than
     # immediately, so the retry interval is kept short
     client = realtime_client(mock_ws, mock_http=mock_http, key='appId.keyId:keySecret',
-                             disconnected_retry_timeout=100)
+                             disconnected_retry_timeout_seconds=0.1)
 
     client.connect()
 
@@ -118,7 +118,7 @@ def on_connection_attempt(conn):
     # The retry that follows the failed renewal would ask the auth callback again,
     # so it is held off until the assertions have run
     client = realtime_client(mock_ws, auth_callback=auth_callback,
-                             disconnected_retry_timeout=60000)
+                             disconnected_retry_timeout_seconds=60)
 
     states = []
     client.connection.on(lambda change: states.append(change.current))
@@ -155,7 +155,7 @@ async def test_rtn14c_connection_timeout():
     mock_ws = MockWebSocket(on_connection_attempt=lambda conn: conn.respond_with_success())
     clock = FakeClock()
     client = realtime_client(mock_ws, clock=clock, key='appId.keyId:keySecret',
-                             realtime_request_timeout=1000)
+                             realtime_request_timeout_seconds=1)
 
     client.connect()
 
@@ -186,7 +186,7 @@ def on_connection_attempt(conn):
     # no failure path of its own, so the first attempt ends on the transition timer
     # rather than at once, and the test advances to it
     client = realtime_client(mock_ws, clock=clock, key='appId.keyId:keySecret',
-                             disconnected_retry_timeout=1000, realtime_request_timeout=1000)
+                             disconnected_retry_timeout_seconds=1, realtime_request_timeout_seconds=1)
 
     client.connect()
     await settle()
@@ -211,7 +211,7 @@ async def test_rtn14e_disconnected_to_suspended():
     mock_ws = MockWebSocket(on_connection_attempt=lambda conn: conn.respond_with_refused())
     clock = FakeClock()
     client = realtime_client(mock_ws, clock=clock, key='appId.keyId:keySecret',
-                             disconnected_retry_timeout=1000, realtime_request_timeout=1000)
+                             disconnected_retry_timeout_seconds=1, realtime_request_timeout_seconds=1)
 
     states = []
     client.connection.on(lambda change: states.append(change.current))
@@ -251,8 +251,8 @@ def on_connection_attempt(conn):
     mock_ws = MockWebSocket(on_connection_attempt=on_connection_attempt)
     clock = FakeClock()
     client = realtime_client(mock_ws, clock=clock, key='appId.keyId:keySecret',
-                             disconnected_retry_timeout=500, suspended_retry_timeout=1000,
-                             realtime_request_timeout=1000)
+                             disconnected_retry_timeout_seconds=0.5, suspended_retry_timeout_seconds=1,
+                             realtime_request_timeout_seconds=1)
 
     def on_state_change(change):
         states.append(change.current)
diff --git a/test/uts/realtime/unit/connection/connection_ping_test.py b/test/uts/realtime/unit/connection/connection_ping_test.py
index e7a503cd..9cbc7ad0 100644
--- a/test/uts/realtime/unit/connection/connection_ping_test.py
+++ b/test/uts/realtime/unit/connection/connection_ping_test.py
@@ -3,8 +3,8 @@
 Spec points: RTN13, RTN13a, RTN13b, RTN13c, RTN13d, RTN13e
 
 `ping()`'s own timeout does not run on the timer seam — `ConnectionManager.ping`
-awaits `asyncio.wait_for(..., realtime_request_timeout / 1000)` on the loop
-clock — so the tests that wait one out use a short real `realtime_request_timeout`
+awaits `asyncio.wait_for(..., realtime_request_timeout_seconds)` on the loop
+clock — so the tests that wait one out use a short real `realtime_request_timeout_seconds`
 rather than a `FakeClock`. The fake clock is still installed where a
 specification advances past `connectionStateTtl` to reach SUSPENDED, which no
 client option reaches.
@@ -29,9 +29,10 @@
 HEARTBEAT = int(ProtocolMessageAction.HEARTBEAT)
 
 # Long enough that a ping which is meant to resolve is never cut short, short
-# enough that a ping which is meant to time out does so quickly
-REQUEST_TIMEOUT = 2000
-SHORT_REQUEST_TIMEOUT = 300
+# enough that a ping which is meant to time out does so quickly, in the seconds the
+# client option takes
+REQUEST_TIMEOUT_SECONDS = 2
+SHORT_REQUEST_TIMEOUT_SECONDS = 0.3
 
 # `Defaults.connection_state_ttl` is 120 s and is read directly by the suspend
 # timer, which is the one interval no client option reaches
@@ -80,7 +81,7 @@ async def test_rtn13a_ping_heartbeat_roundtrip():
     mock_ws = MockWebSocket(
         on_connection_attempt=lambda conn: conn.respond_with_success(connected()))
     mock_ws.on_message_from_client = echo_heartbeats(mock_ws)
-    client = realtime_client(mock_ws, realtime_request_timeout=REQUEST_TIMEOUT)
+    client = realtime_client(mock_ws, realtime_request_timeout_seconds=REQUEST_TIMEOUT_SECONDS)
 
     client.connect()
     await await_connection_state(client, ConnectionState.CONNECTED)
@@ -107,7 +108,7 @@ def on_message_from_client(message):
             mock_ws.send_to_client({'action': HEARTBEAT, 'id': message.get('id')})
 
     mock_ws.on_message_from_client = on_message_from_client
-    client = realtime_client(mock_ws, realtime_request_timeout=REQUEST_TIMEOUT)
+    client = realtime_client(mock_ws, realtime_request_timeout_seconds=REQUEST_TIMEOUT_SECONDS)
 
     client.connect()
     await await_connection_state(client, ConnectionState.CONNECTED)
@@ -132,7 +133,7 @@ def on_message_from_client(message):
             mock_ws.send_to_client({'action': HEARTBEAT, 'id': message.get('id')})
 
     mock_ws.on_message_from_client = on_message_from_client
-    client = realtime_client(mock_ws, realtime_request_timeout=REQUEST_TIMEOUT)
+    client = realtime_client(mock_ws, realtime_request_timeout_seconds=REQUEST_TIMEOUT_SECONDS)
 
     client.connect()
     await await_connection_state(client, ConnectionState.CONNECTED)
@@ -148,7 +149,7 @@ async def test_rtn13e_concurrent_pings_unique_ids():
     mock_ws = MockWebSocket(
         on_connection_attempt=lambda conn: conn.respond_with_success(connected()))
     mock_ws.on_message_from_client = echo_heartbeats(mock_ws)
-    client = realtime_client(mock_ws, realtime_request_timeout=REQUEST_TIMEOUT)
+    client = realtime_client(mock_ws, realtime_request_timeout_seconds=REQUEST_TIMEOUT_SECONDS)
 
     client.connect()
     await await_connection_state(client, ConnectionState.CONNECTED)
@@ -170,10 +171,10 @@ async def test_rtn13e_concurrent_pings_unique_ids():
 # UTS: realtime/unit/RTN13c/ping-timeout-0
 async def test_rtn13c_ping_timeout():
     # The server answers no HEARTBEAT, so the ping runs out its
-    # `realtime_request_timeout`, which is real time here rather than advanced
+    # `realtime_request_timeout_seconds`, which is real time here rather than advanced
     mock_ws = MockWebSocket(
         on_connection_attempt=lambda conn: conn.respond_with_success(connected()))
-    client = realtime_client(mock_ws, realtime_request_timeout=SHORT_REQUEST_TIMEOUT)
+    client = realtime_client(mock_ws, realtime_request_timeout_seconds=SHORT_REQUEST_TIMEOUT_SECONDS)
 
     client.connect()
     await await_connection_state(client, ConnectionState.CONNECTED)
@@ -206,8 +207,8 @@ async def test_rtn13b_ping_error_suspended():
     # A retry timeout past `connectionStateTtl` leaves the suspend timer as the
     # only thing the advance below fires
     client = realtime_client(
-        mock_ws, clock=clock, disconnected_retry_timeout=CONNECTION_STATE_TTL * 2,
-        suspended_retry_timeout=CONNECTION_STATE_TTL * 2)
+        mock_ws, clock=clock, disconnected_retry_timeout_seconds=CONNECTION_STATE_TTL * 2 / 1000,
+        suspended_retry_timeout_seconds=CONNECTION_STATE_TTL * 2 / 1000)
 
     client.connect()
     await await_connection_state(client, ConnectionState.DISCONNECTED)
@@ -225,7 +226,7 @@ async def test_rtn13b_ping_error_suspended():
 async def test_rtn13b_ping_error_closed():
     mock_ws = MockWebSocket(
         on_connection_attempt=lambda conn: conn.respond_with_success(connected()))
-    client = realtime_client(mock_ws, realtime_request_timeout=REQUEST_TIMEOUT)
+    client = realtime_client(mock_ws, realtime_request_timeout_seconds=REQUEST_TIMEOUT_SECONDS)
 
     client.connect()
     await await_connection_state(client, ConnectionState.CONNECTED)
@@ -243,7 +244,7 @@ async def test_rtn13b_ping_error_failed():
     mock_ws = MockWebSocket(
         on_connection_attempt=lambda conn: conn.respond_with_error(
             ERROR_MESSAGE(80000, 'Fatal error', status_code=400)))
-    client = realtime_client(mock_ws, realtime_request_timeout=REQUEST_TIMEOUT)
+    client = realtime_client(mock_ws, realtime_request_timeout_seconds=REQUEST_TIMEOUT_SECONDS)
 
     client.connect()
     await await_connection_state(client, ConnectionState.FAILED)
@@ -258,7 +259,7 @@ async def test_rtn13d_ping_deferred_connecting():
     attempts = []
     mock_ws = MockWebSocket(on_connection_attempt=attempts.append)
     mock_ws.on_message_from_client = echo_heartbeats(mock_ws)
-    client = realtime_client(mock_ws, realtime_request_timeout=REQUEST_TIMEOUT)
+    client = realtime_client(mock_ws, realtime_request_timeout_seconds=REQUEST_TIMEOUT_SECONDS)
 
     client.connect()
     # `connect()` sets CONNECTING before the attempt is scheduled, so the attempt
@@ -299,8 +300,8 @@ def on_connection_attempt(conn):
 
     mock_ws = MockWebSocket(on_connection_attempt=on_connection_attempt)
     mock_ws.on_message_from_client = echo_heartbeats(mock_ws)
-    client = realtime_client(mock_ws, clock=clock, disconnected_retry_timeout=500,
-                             realtime_request_timeout=REQUEST_TIMEOUT)
+    client = realtime_client(mock_ws, clock=clock, disconnected_retry_timeout_seconds=0.5,
+                             realtime_request_timeout_seconds=REQUEST_TIMEOUT_SECONDS)
 
     client.connect()
     await await_connection_state(client, ConnectionState.DISCONNECTED)
@@ -327,7 +328,7 @@ def on_connection_attempt(conn):
 async def test_rtn13b_deferred_ping_error_failed():
     attempts = []
     mock_ws = MockWebSocket(on_connection_attempt=attempts.append)
-    client = realtime_client(mock_ws, realtime_request_timeout=REQUEST_TIMEOUT)
+    client = realtime_client(mock_ws, realtime_request_timeout_seconds=REQUEST_TIMEOUT_SECONDS)
 
     client.connect()
     await poll_until(lambda: len(attempts) == 1, description='a connection attempt')
@@ -349,8 +350,8 @@ async def test_rtn13b_deferred_ping_error_suspended():
     clock = FakeClock()
     mock_ws = MockWebSocket(on_connection_attempt=lambda conn: conn.respond_with_dns_error())
     client = realtime_client(
-        mock_ws, clock=clock, disconnected_retry_timeout=CONNECTION_STATE_TTL * 2,
-        suspended_retry_timeout=CONNECTION_STATE_TTL * 2)
+        mock_ws, clock=clock, disconnected_retry_timeout_seconds=CONNECTION_STATE_TTL * 2 / 1000,
+        suspended_retry_timeout_seconds=CONNECTION_STATE_TTL * 2 / 1000)
 
     client.connect()
     await await_connection_state(client, ConnectionState.DISCONNECTED)
@@ -377,7 +378,7 @@ async def test_rtn13c_deferred_ping_timeout():
     mock_ws = MockWebSocket(on_connection_attempt=attempts.append)
     # The clock holds the CONNECTING transition timer, leaving the real interval
     # below as the only thing the connection waits on
-    client = realtime_client(mock_ws, clock=clock, realtime_request_timeout=400)
+    client = realtime_client(mock_ws, clock=clock, realtime_request_timeout_seconds=0.4)
     timeout_in_secs = 0.4
 
     client.connect()
diff --git a/test/uts/realtime/unit/connection/connection_recovery_test.py b/test/uts/realtime/unit/connection/connection_recovery_test.py
index c862c14b..b4791db5 100644
--- a/test/uts/realtime/unit/connection/connection_recovery_test.py
+++ b/test/uts/realtime/unit/connection/connection_recovery_test.py
@@ -149,8 +149,8 @@ def on_connection_attempt(conn):
 
     suspended_ws = MockWebSocket(on_connection_attempt=on_connection_attempt)
     client_suspended = realtime_client(
-        suspended_ws, clock=clock, disconnected_retry_timeout=500,
-        suspended_retry_timeout=CONNECTION_STATE_TTL * 2)
+        suspended_ws, clock=clock, disconnected_retry_timeout_seconds=0.5,
+        suspended_retry_timeout_seconds=CONNECTION_STATE_TTL * 2 / 1000)
 
     client_suspended.connect()
     await await_connection_state(client_suspended, ConnectionState.CONNECTED)
diff --git a/test/uts/realtime/unit/connection/error_reason_test.py b/test/uts/realtime/unit/connection/error_reason_test.py
index a0a3622e..38bce98c 100644
--- a/test/uts/realtime/unit/connection/error_reason_test.py
+++ b/test/uts/realtime/unit/connection/error_reason_test.py
@@ -50,7 +50,7 @@ async def test_rtn25_error_reason_disconnected():
     mock_ws = MockWebSocket(on_connection_attempt=lambda conn: conn.respond_with_refused())
     # A refused connect reaches DISCONNECTED when the connecting transition
     # timer expires, so a short request timeout keeps that wait small
-    client = realtime_client(mock_ws, realtime_request_timeout=300)
+    client = realtime_client(mock_ws, realtime_request_timeout_seconds=0.3)
 
     client.connect()
     await await_connection_state(client, ConnectionState.DISCONNECTED)
@@ -63,7 +63,7 @@ async def test_rtn25_error_reason_disconnected():
 async def test_rtn25_error_reason_suspended():
     mock_ws = MockWebSocket(on_connection_attempt=lambda conn: conn.respond_with_refused())
     clock = FakeClock()
-    client = realtime_client(mock_ws, clock=clock, disconnected_retry_timeout=500)
+    client = realtime_client(mock_ws, clock=clock, disconnected_retry_timeout_seconds=0.5)
 
     client.connect()
     await settle()
@@ -107,7 +107,7 @@ def on_connection_attempt(conn):
     mock_ws = MockWebSocket(on_connection_attempt=on_connection_attempt)
     clock = FakeClock()
     client = realtime_client(
-        mock_ws, clock=clock, disconnected_retry_timeout=100, realtime_request_timeout=300)
+        mock_ws, clock=clock, disconnected_retry_timeout_seconds=0.1, realtime_request_timeout_seconds=0.3)
 
     client.connect()
     await settle()
diff --git a/test/uts/realtime/unit/connection/fallback_hosts_test.py b/test/uts/realtime/unit/connection/fallback_hosts_test.py
index b24dfb68..70471806 100644
--- a/test/uts/realtime/unit/connection/fallback_hosts_test.py
+++ b/test/uts/realtime/unit/connection/fallback_hosts_test.py
@@ -211,8 +211,8 @@ def on_connection_attempt(conn):
     # REC2c2: a custom domain has no fallback set of its own. The spec sets realtimeHost,
     # which ably-python omits (TO3k3); endpoint names the same host
     client = fallback_client(
-        mock_ws, endpoint='custom.example.com', realtime_request_timeout=300,
-        disconnected_retry_timeout=60000)
+        mock_ws, endpoint='custom.example.com', realtime_request_timeout_seconds=0.3,
+        disconnected_retry_timeout_seconds=60)
 
     client.connect()
     await await_connection_state(client, ConnectionState.DISCONNECTED, timeout=5.0)
diff --git a/test/uts/realtime/unit/connection/heartbeat_test.py b/test/uts/realtime/unit/connection/heartbeat_test.py
index 42b0efd5..b72a5a6f 100644
--- a/test/uts/realtime/unit/connection/heartbeat_test.py
+++ b/test/uts/realtime/unit/connection/heartbeat_test.py
@@ -29,7 +29,7 @@
     message_protocol_message,
 )
 
-# The specification's `maxIdleInterval` and `realtimeRequestTimeout`
+# The specification's `maxIdleInterval` and `realtimeRequestTimeout`, in milliseconds
 MAX_IDLE_INTERVAL = 2000
 REQUEST_TIMEOUT = 1000
 
@@ -73,8 +73,8 @@
 
 def liveness_client(mock_websocket, clock=None, **kwargs):
     """A client whose connection drops `IDLE_TIMEOUT` after the last message."""
-    kwargs.setdefault('realtime_request_timeout', REQUEST_TIMEOUT)
-    kwargs.setdefault('disconnected_retry_timeout', 500)
+    kwargs.setdefault('realtime_request_timeout_seconds', REQUEST_TIMEOUT / 1000)
+    kwargs.setdefault('disconnected_retry_timeout_seconds', 0.5)
     return realtime_client(mock_websocket, clock=clock, **kwargs)
 
 
diff --git a/test/uts/realtime/unit/connection/when_state_test.py b/test/uts/realtime/unit/connection/when_state_test.py
index d41c4fc1..adb15540 100644
--- a/test/uts/realtime/unit/connection/when_state_test.py
+++ b/test/uts/realtime/unit/connection/when_state_test.py
@@ -98,7 +98,7 @@ def on_connection_attempt(conn):
             connected_message(f'connection-id-{index}', connectionKey=f'connection-key-{index}'))
 
     mock_ws = MockWebSocket(on_connection_attempt=on_connection_attempt)
-    client = realtime_client(mock_ws, disconnected_retry_timeout=100)
+    client = realtime_client(mock_ws, disconnected_retry_timeout_seconds=0.1)
 
     invocations = []
 
@@ -168,7 +168,7 @@ async def test_rtn26_whenstate_different_states():
     mock_ws = MockWebSocket(on_connection_attempt=lambda conn: conn.respond_with_refused())
     # A refused connect reaches DISCONNECTED when the connecting transition
     # timer expires, so a short request timeout keeps that wait small
-    client = realtime_client(mock_ws, realtime_request_timeout=300)
+    client = realtime_client(mock_ws, realtime_request_timeout_seconds=0.3)
 
     initialized = when_state(client.connection, ConnectionState.INITIALIZED)
     connecting = when_state(client.connection, ConnectionState.CONNECTING)
diff --git a/test/uts/realtime/unit/presence/realtime_presence_channel_state_test.py b/test/uts/realtime/unit/presence/realtime_presence_channel_state_test.py
index 15d50b36..49d029e9 100644
--- a/test/uts/realtime/unit/presence/realtime_presence_channel_state_test.py
+++ b/test/uts/realtime/unit/presence/realtime_presence_channel_state_test.py
@@ -139,7 +139,7 @@ def on_message_from_client(msg):
                 mock_ws.send_to_client(attached_message(channel_name))
 
     mock_ws.on_message_from_client = on_message_from_client
-    client = await connected_client(mock_ws, disconnected_retry_timeout=100)
+    client = await connected_client(mock_ws, disconnected_retry_timeout_seconds=0.1)
     channel = client.channels.get(channel_name)
 
     await asyncio.wait_for(channel.attach(), OPERATION_TIMEOUT)
@@ -318,8 +318,8 @@ def on_message_from_client(msg):
 
     mock_ws.on_message_from_client = on_message_from_client
     client = await connected_client(
-        mock_ws, clock=clock, realtime_request_timeout=300000,
-        disconnected_retry_timeout=1000, suspended_retry_timeout=600000)
+        mock_ws, clock=clock, realtime_request_timeout_seconds=300,
+        disconnected_retry_timeout_seconds=1, suspended_retry_timeout_seconds=600)
     channel = client.channels.get(channel_name)
 
     await asyncio.wait_for(channel.attach(), OPERATION_TIMEOUT)
@@ -455,8 +455,8 @@ def on_message_from_client(msg):
     # channel is to follow the connection to SUSPENDED rather than time its own
     # attach out first
     client = await connected_client(
-        mock_ws, clock=clock, client_id='my-client', realtime_request_timeout=300000,
-        disconnected_retry_timeout=1000, suspended_retry_timeout=600000)
+        mock_ws, clock=clock, client_id='my-client', realtime_request_timeout_seconds=300,
+        disconnected_retry_timeout_seconds=1, suspended_retry_timeout_seconds=600)
     channel = client.channels.get(channel_name)
 
     # The ATTACH is left unanswered, holding the channel in ATTACHING
diff --git a/test/uts/realtime/unit/presence/realtime_presence_get_test.py b/test/uts/realtime/unit/presence/realtime_presence_get_test.py
index d0afbf7c..906754d5 100644
--- a/test/uts/realtime/unit/presence/realtime_presence_get_test.py
+++ b/test/uts/realtime/unit/presence/realtime_presence_get_test.py
@@ -84,8 +84,8 @@ async def suspended_channel(channel_name):
         present_member('alice', 'c1', 'c1:0:0'),
     ]))
     client = await connected_client(
-        mock_ws, clock=clock, realtime_request_timeout=300,
-        disconnected_retry_timeout=1000, suspended_retry_timeout=600000)
+        mock_ws, clock=clock, realtime_request_timeout_seconds=0.3,
+        disconnected_retry_timeout_seconds=1, suspended_retry_timeout_seconds=600)
     channel = client.channels.get(channel_name)
 
     await channel.attach()
diff --git a/test/uts/realtime/unit/presence/realtime_presence_reentry_test.py b/test/uts/realtime/unit/presence/realtime_presence_reentry_test.py
index 0de3607e..305961ad 100644
--- a/test/uts/realtime/unit/presence/realtime_presence_reentry_test.py
+++ b/test/uts/realtime/unit/presence/realtime_presence_reentry_test.py
@@ -124,7 +124,7 @@ async def test_rtp17i_auto_reentry_on_attached():
     echoing_server(mock_ws, channel_name, connections, captured_presence)
 
     client = await connected_client(
-        mock_ws, client_id='my-client', disconnected_retry_timeout=100)
+        mock_ws, client_id='my-client', disconnected_retry_timeout_seconds=0.1)
     channel = client.channels.get(channel_name)
 
     await asyncio.wait_for(channel.attach(), OPERATION_TIMEOUT)
@@ -165,7 +165,7 @@ async def test_rtp17g_reentry_publishes_enter_with_data():
     # RTP15f has a client with a concrete clientId refused `enterClient` for any
     # other one, so the client entering alice and bob on their behalf holds the
     # wildcard clientId the specification's own note allows for
-    client = await connected_client(mock_ws, client_id='*', disconnected_retry_timeout=100)
+    client = await connected_client(mock_ws, client_id='*', disconnected_retry_timeout_seconds=0.1)
     channel = client.channels.get(channel_name)
 
     await asyncio.wait_for(channel.attach(), OPERATION_TIMEOUT)
@@ -217,7 +217,7 @@ async def test_rtp17g1_reentry_omits_id_new_connid():
     echoing_server(mock_ws, channel_name, connections, captured_presence)
 
     client = await connected_client(
-        mock_ws, client_id='my-client', disconnected_retry_timeout=100)
+        mock_ws, client_id='my-client', disconnected_retry_timeout_seconds=0.1)
     channel = client.channels.get(channel_name)
 
     await asyncio.wait_for(channel.attach(), OPERATION_TIMEOUT)
@@ -298,7 +298,7 @@ def on_message_from_client(msg):
     mock_ws.on_message_from_client = on_message_from_client
 
     client = await connected_client(
-        mock_ws, client_id='my-client', disconnected_retry_timeout=100)
+        mock_ws, client_id='my-client', disconnected_retry_timeout_seconds=0.1)
     channel = client.channels.get(channel_name)
 
     await asyncio.wait_for(channel.attach(), OPERATION_TIMEOUT)
diff --git a/test/uts/rest/unit/fallback_test.py b/test/uts/rest/unit/fallback_test.py
index 477d79f0..403d67d2 100644
--- a/test/uts/rest/unit/fallback_test.py
+++ b/test/uts/rest/unit/fallback_test.py
@@ -349,7 +349,7 @@ async def test_rsc15f_successful_fallback_cached():
         mock_http.queue_response_for_host(host, 200, TIME_BODY)
         mock_http.queue_response_for_host(host, 200, TIME_BODY)
 
-    client = rest_client(mock_http, fallback_retry_timeout=60000)
+    client = rest_client(mock_http, fallback_retry_timeout_seconds=60)
 
     # First request - triggers fallback
     await client.time()
@@ -378,7 +378,7 @@ async def test_rsc15f_cached_fallback_expires():
     # After timeout, primary should be tried again
     mock_http.queue_response_for_host(PRIMARY_HOST, 200, TIME_BODY)
 
-    client = rest_client(mock_http, fallback_retry_timeout=100)
+    client = rest_client(mock_http, fallback_retry_timeout_seconds=0.1)
 
     # First request triggers fallback
     await client.time()
@@ -421,7 +421,7 @@ def on_request(req):
             req.respond_with(200, TIME_BODY)
 
     mock_http = MockHttpClient(on_connection_attempt=connect_successfully, on_request=on_request)
-    client = rest_client(mock_http, fallback_retry_timeout=100)
+    client = rest_client(mock_http, fallback_retry_timeout_seconds=0.1)
 
     # Request 1+2: primary fails -> fallback succeeds -> fallback cached
     await client.time()

From 2c03eea171076c02c76eeb6bc0aee83167218937 Mon Sep 17 00:00:00 2001
From: owenpearson <owen.pearson@ably.com>
Date: Wed, 28 Oct 2026 13:25:18 +0000
Subject: [PATCH 2/5] pubsub: name the HTTP timing options for their unit, as
 *_seconds

TO3l3, TO3l4 and TO3l6 count httpOpenTimeout, httpRequestTimeout and
httpMaxRetryDuration in milliseconds. ably-python's http_open_timeout,
http_request_timeout and http_max_retry_duration have always been
seconds, with nothing in their names to say so. A caller following the
specification's units passed http_request_timeout=3000 and got a deadline
of fifty minutes: rest/proxy/RSC15l2/timeout-triggers-fallback-0, which
does exactly that, sat out the proxy's 20-second delay on the primary
host and never fell back, so it was gated as an open bug.

The three options are renamed http_open_timeout_seconds,
http_request_timeout_seconds and http_max_retry_duration_seconds, with
their units and defaults of 4, 10 and 15 unchanged, to match the
realtime timing options. They read back from Options, and from the Http
properties, under the new names, and still reach the httpx Timeout and
the RSC15 retry budget as seconds.

The RSC15l2 test now passes httpRequestTimeout: 3000 as
http_request_timeout_seconds=3, and is un-gated: it passes against the
proxy, timing out at about three seconds and succeeding on the
fallback. test/uts/deviations.md removes its Failing Tests entry and
candidate issue I.3, records the HTTP options with the others as an
intentional naming-and-unit deviation, keeps the rest of #709 open, and
updates its counts for one fewer gated test and REST root cause.

This is a breaking change: passing an old name raises TypeError. Callers
should rename the option and keep its value, as UPDATING.md shows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/uts-to-python/SKILL.md         |  17 ++-
 UPDATING.md                                   |  45 +++++++-
 ably/pubsub/request/http.py                   |  18 +--
 ably/pubsub/server/__init__.py                |  20 ++--
 ably/pubsub/transport/defaults.py             |   6 +-
 ably/pubsub/types/options.py                  |  56 +++++-----
 test/ably/http/httphttp_test.py               |  18 +--
 test/ably/http/httpinit_test.py               |  10 +-
 test/ably/http/httprequest_test.py            |   6 +-
 test/unit/clock_test.py                       |   4 +-
 test/unit/http_test.py                        |   2 +-
 test/unit/options_test.py                     |  25 ++++-
 test/uts/deviations.md                        | 104 +++++-------------
 test/uts/helpers/mock_http_test.py            |   4 +-
 .../unit/client/realtime_timeouts_test.py     |   8 +-
 .../integration/proxy/rest_fallback_test.py   |   8 +-
 test/uts/rest/unit/fallback_test.py           |   8 +-
 test/uts/rest/unit/request_test.py            |   4 +-
 test/uts/rest/unit/rest_client_test.py        |   6 +-
 .../uts/rest/unit/types/options_types_test.py |  15 +--
 20 files changed, 197 insertions(+), 187 deletions(-)

diff --git a/.claude/skills/uts-to-python/SKILL.md b/.claude/skills/uts-to-python/SKILL.md
index ac88adc0..8cd3a404 100644
--- a/.claude/skills/uts-to-python/SKILL.md
+++ b/.claude/skills/uts-to-python/SKILL.md
@@ -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
 
diff --git a/UPDATING.md b/UPDATING.md
index c6530074..9d97eead 100644
--- a/UPDATING.md
+++ b/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
@@ -819,6 +821,37 @@ pubsub_realtime_client = create_realtime_client(
 )
 ```
 
+### 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(),
+)
+```
+
 ## 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:
diff --git a/ably/pubsub/request/http.py b/ably/pubsub/request/http.py
index a29ee185..a3627d72 100644
--- a/ably/pubsub/request/http.py
+++ b/ably/pubsub/request/http.py
@@ -196,8 +196,8 @@ async def make_request(self, method, path, version=None, headers=None, body=None
             all_headers.update(headers)
 
         # TO3l3 bounds opening the connection, and TO3l4 each read, write and wait for a pooled connection
-        timeout = httpx.Timeout(self.http_request_timeout, connect=self.http_open_timeout)
-        http_max_retry_duration = self.http_max_retry_duration
+        timeout = httpx.Timeout(self.http_request_timeout_seconds, connect=self.http_open_timeout_seconds)
+        http_max_retry_duration_seconds = self.http_max_retry_duration_seconds
         requested_at = self.__clock.now_ms()
 
         hosts = self.get_hosts()
@@ -205,7 +205,7 @@ async def make_request(self, method, path, version=None, headers=None, body=None
             def should_stop_retrying(retry_count=retry_count):
                 time_passed = (self.__clock.now_ms() - requested_at) / 1000
                 # if it's the last try or cumulative timeout is done, we stop retrying
-                return retry_count == len(hosts) - 1 or time_passed > http_max_retry_duration
+                return retry_count == len(hosts) - 1 or time_passed > http_max_retry_duration_seconds
 
             base_url = f"{self.preferred_scheme}://{HttpUtils.host_for_url(host)}:{self.preferred_port}"
             url = urljoin(base_url, path)
@@ -311,17 +311,17 @@ def preferred_scheme(self):
         return Defaults.get_scheme(self.options)
 
     @property
-    def http_open_timeout(self):
-        return self.options.http_open_timeout
+    def http_open_timeout_seconds(self):
+        return self.options.http_open_timeout_seconds
 
     @property
-    def http_request_timeout(self):
-        return self.options.http_request_timeout
+    def http_request_timeout_seconds(self):
+        return self.options.http_request_timeout_seconds
 
     @property
     def http_max_retry_count(self):
         return self.options.http_max_retry_count
 
     @property
-    def http_max_retry_duration(self):
-        return self.options.http_max_retry_duration
+    def http_max_retry_duration_seconds(self):
+        return self.options.http_max_retry_duration_seconds
diff --git a/ably/pubsub/server/__init__.py b/ably/pubsub/server/__init__.py
index 6dca0aa7..0eb7711b 100644
--- a/ably/pubsub/server/__init__.py
+++ b/ably/pubsub/server/__init__.py
@@ -132,14 +132,18 @@ def create_http_client(**kwargs) -> PubSubHttpClient:
 
         **HTTP behaviour**
 
-        http_open_timeout: float
-            Timeout (in seconds) for establishing an HTTP connection. The default is 4
-            seconds.
-        http_request_timeout: float
-            Timeout (in seconds) for a complete HTTP request. The default is 10 seconds.
-        http_max_retry_duration: float
-            How long (in seconds) the client keeps retrying a request across hosts before
-            giving up. The default is 15 seconds.
+        The timeouts are in seconds, where the Ably specification counts milliseconds, and
+        their names say so; a `datetime.timedelta` converts with `.total_seconds()`.
+
+        http_open_timeout_seconds: float
+            TO3l3 httpOpenTimeout, in seconds: the timeout for establishing an HTTP
+            connection. The default is 4.
+        http_request_timeout_seconds: float
+            TO3l4 httpRequestTimeout, in seconds: the timeout for each read and write of
+            an HTTP request, and for a free pooled connection. The default is 10.
+        http_max_retry_duration_seconds: float
+            TO3l6 httpMaxRetryDuration, in seconds: how long the client keeps retrying a
+            request across hosts before giving up. The default is 15.
         http_max_retry_count: int
             The most fallback hosts the client will try for a single request, after the
             primary endpoint. The default is 3; 0 tries the primary endpoint only.
diff --git a/ably/pubsub/transport/defaults.py b/ably/pubsub/transport/defaults.py
index 2d9b349a..9e382014 100644
--- a/ably/pubsub/transport/defaults.py
+++ b/ably/pubsub/transport/defaults.py
@@ -21,11 +21,11 @@ class Defaults:
     disconnected_retry_timeout_seconds = 15
     suspended_retry_timeout_seconds = 30
     fallback_retry_timeout_seconds = 600  # 10min
+    http_open_timeout_seconds = 4
+    http_request_timeout_seconds = 10
+    http_max_retry_duration_seconds = 15
 
-    http_open_timeout = 4
-    http_request_timeout = 10
     http_max_retry_count = 3
-    http_max_retry_duration = 15
 
     max_message_size = 65536  # 64KiB
 
diff --git a/ably/pubsub/types/options.py b/ably/pubsub/types/options.py
index 20e1fe51..a758404e 100644
--- a/ably/pubsub/types/options.py
+++ b/ably/pubsub/types/options.py
@@ -43,6 +43,9 @@ class Options(AuthOptions):
     milliseconds, and each name ends in `_seconds` to say so. Each reads back the value
     in effect, its default if it was not given:
 
+    - `http_open_timeout_seconds`: TO3l3 httpOpenTimeout, default 4
+    - `http_request_timeout_seconds`: TO3l4 httpRequestTimeout, default 10
+    - `http_max_retry_duration_seconds`: TO3l6 httpMaxRetryDuration, default 15
     - `realtime_request_timeout_seconds`: TO3l11 realtimeRequestTimeout, default 10
     - `disconnected_retry_timeout_seconds`: TO3l1 disconnectedRetryTimeout, default 15
     - `suspended_retry_timeout_seconds`: TO3l2 suspendedRetryTimeout, default 30
@@ -52,8 +55,9 @@ class Options(AuthOptions):
 
     def __init__(self, client_id=None, tls=True, port=0,
                  tls_port=0, use_binary_protocol=True, queue_messages=True, endpoint=None,
-                 http_open_timeout=None, http_request_timeout=None,
-                 realtime_request_timeout_seconds=None, http_max_retry_count=None, http_max_retry_duration=None,
+                 http_open_timeout_seconds=None, http_request_timeout_seconds=None,
+                 realtime_request_timeout_seconds=None, http_max_retry_count=None,
+                 http_max_retry_duration_seconds=None,
                  fallback_hosts=None, fallback_retry_timeout_seconds=None, disconnected_retry_timeout_seconds=None,
                  idempotent_rest_publishing=None, loop=None, auto_connect=True,
                  suspended_retry_timeout_seconds=None, connectivity_check_url=None,
@@ -72,17 +76,17 @@ def __init__(self, client_id=None, tls=True, port=0,
             realtime_request_timeout_seconds = Defaults.realtime_request_timeout_seconds
 
         # RTC7: the HTTP defaults are resolved here too, so they read back from the options
-        if http_open_timeout is None:
-            http_open_timeout = Defaults.http_open_timeout
+        if http_open_timeout_seconds is None:
+            http_open_timeout_seconds = Defaults.http_open_timeout_seconds
 
-        if http_request_timeout is None:
-            http_request_timeout = Defaults.http_request_timeout
+        if http_request_timeout_seconds is None:
+            http_request_timeout_seconds = Defaults.http_request_timeout_seconds
 
         if http_max_retry_count is None:
             http_max_retry_count = Defaults.http_max_retry_count
 
-        if http_max_retry_duration is None:
-            http_max_retry_duration = Defaults.http_max_retry_duration
+        if http_max_retry_duration_seconds is None:
+            http_max_retry_duration_seconds = Defaults.http_max_retry_duration_seconds
 
         if disconnected_retry_timeout_seconds is None:
             disconnected_retry_timeout_seconds = Defaults.disconnected_retry_timeout_seconds
@@ -117,11 +121,11 @@ def __init__(self, client_id=None, tls=True, port=0,
         self.__queue_messages = queue_messages
         self.__echo_messages = echo_messages
         self.__endpoint = endpoint
-        self.__http_open_timeout = http_open_timeout
-        self.__http_request_timeout = http_request_timeout
+        self.__http_open_timeout_seconds = http_open_timeout_seconds
+        self.__http_request_timeout_seconds = http_request_timeout_seconds
         self.__realtime_request_timeout_seconds = realtime_request_timeout_seconds
         self.__http_max_retry_count = http_max_retry_count
-        self.__http_max_retry_duration = http_max_retry_duration
+        self.__http_max_retry_duration_seconds = http_max_retry_duration_seconds
         # Field for internal use only
         self.__fallback_host = None
         self.__fallback_hosts = fallback_hosts
@@ -198,16 +202,16 @@ def endpoint(self):
         return self.__endpoint
 
     @property
-    def http_open_timeout(self):
-        return self.__http_open_timeout
+    def http_open_timeout_seconds(self):
+        return self.__http_open_timeout_seconds
 
-    @http_open_timeout.setter
-    def http_open_timeout(self, value):
-        self.__http_open_timeout = value
+    @http_open_timeout_seconds.setter
+    def http_open_timeout_seconds(self, value):
+        self.__http_open_timeout_seconds = value
 
     @property
-    def http_request_timeout(self):
-        return self.__http_request_timeout
+    def http_request_timeout_seconds(self):
+        return self.__http_request_timeout_seconds
 
     @property
     def realtime_request_timeout_seconds(self):
@@ -217,9 +221,9 @@ def realtime_request_timeout_seconds(self):
     def _realtime_request_timeout_ms(self):
         return seconds_to_ms(self.__realtime_request_timeout_seconds)
 
-    @http_request_timeout.setter
-    def http_request_timeout(self, value):
-        self.__http_request_timeout = value
+    @http_request_timeout_seconds.setter
+    def http_request_timeout_seconds(self, value):
+        self.__http_request_timeout_seconds = value
 
     @property
     def http_max_retry_count(self):
@@ -230,12 +234,12 @@ def http_max_retry_count(self, value):
         self.__http_max_retry_count = value
 
     @property
-    def http_max_retry_duration(self):
-        return self.__http_max_retry_duration
+    def http_max_retry_duration_seconds(self):
+        return self.__http_max_retry_duration_seconds
 
-    @http_max_retry_duration.setter
-    def http_max_retry_duration(self, value):
-        self.__http_max_retry_duration = value
+    @http_max_retry_duration_seconds.setter
+    def http_max_retry_duration_seconds(self, value):
+        self.__http_max_retry_duration_seconds = value
 
     @property
     def fallback_hosts(self):
diff --git a/test/ably/http/httphttp_test.py b/test/ably/http/httphttp_test.py
index 81615f97..5490c149 100644
--- a/test/ably/http/httphttp_test.py
+++ b/test/ably/http/httphttp_test.py
@@ -30,8 +30,8 @@ async def test_host_for_url_brackets_only_ipv6_literals(self):
 
     async def test_max_retry_attempts_and_timeouts_defaults(self):
         ably = create_http_client(token="foo")
-        assert ably.options.http_open_timeout == Defaults.http_open_timeout
-        assert ably.options.http_request_timeout == Defaults.http_request_timeout
+        assert ably.options.http_open_timeout_seconds == Defaults.http_open_timeout_seconds
+        assert ably.options.http_request_timeout_seconds == Defaults.http_request_timeout_seconds
 
         with mock.patch('httpx.AsyncClient.send', side_effect=httpx.RequestError('')) as send_mock:
             with pytest.raises(AblyException, match="network error"):
@@ -44,9 +44,9 @@ async def test_max_retry_attempts_and_timeouts_defaults(self):
 
     async def test_cumulative_timeout(self):
         ably = create_http_client(token="foo")
-        assert ably.options.http_max_retry_duration == Defaults.http_max_retry_duration
+        assert ably.options.http_max_retry_duration_seconds == Defaults.http_max_retry_duration_seconds
 
-        ably.options.http_max_retry_duration = 0.5
+        ably.options.http_max_retry_duration_seconds = 0.5
 
         def sleep_and_raise(*args, **kwargs):
             time.sleep(0.51)
@@ -176,13 +176,13 @@ async def test_500_errors(self):
 
     def test_custom_http_timeouts(self):
         ably = create_http_client(
-            token="foo", http_request_timeout=30, http_open_timeout=8,
-            http_max_retry_count=6, http_max_retry_duration=20)
+            token="foo", http_request_timeout_seconds=30, http_open_timeout_seconds=8,
+            http_max_retry_count=6, http_max_retry_duration_seconds=20)
 
-        assert ably.http.http_request_timeout == 30
-        assert ably.http.http_open_timeout == 8
+        assert ably.http.http_request_timeout_seconds == 30
+        assert ably.http.http_open_timeout_seconds == 8
         assert ably.http.http_max_retry_count == 6
-        assert ably.http.http_max_retry_duration == 20
+        assert ably.http.http_max_retry_duration_seconds == 20
 
     # RSC7a, RSC7b
     async def test_request_headers(self):
diff --git a/test/ably/http/httpinit_test.py b/test/ably/http/httpinit_test.py
index b7cf5e7a..c957ce1e 100644
--- a/test/ably/http/httpinit_test.py
+++ b/test/ably/http/httpinit_test.py
@@ -218,10 +218,10 @@ async def test_environment(self):
     @dont_vary_protocol
     def test_accepts_custom_http_timeouts(self):
         ably = create_http_client(
-            token="foo", http_request_timeout=30, http_open_timeout=8,
-            http_max_retry_count=6, http_max_retry_duration=20)
+            token="foo", http_request_timeout_seconds=30, http_open_timeout_seconds=8,
+            http_max_retry_count=6, http_max_retry_duration_seconds=20)
 
-        assert ably.options.http_request_timeout == 30
-        assert ably.options.http_open_timeout == 8
+        assert ably.options.http_request_timeout_seconds == 30
+        assert ably.options.http_open_timeout_seconds == 8
         assert ably.options.http_max_retry_count == 6
-        assert ably.options.http_max_retry_duration == 20
+        assert ably.options.http_max_retry_duration_seconds == 20
diff --git a/test/ably/http/httprequest_test.py b/test/ably/http/httprequest_test.py
index 107ecae7..015d6063 100644
--- a/test/ably/http/httprequest_test.py
+++ b/test/ably/http/httprequest_test.py
@@ -106,9 +106,9 @@ async def test_headers(self):
     async def test_timeout(self):
         # Timeout
         timeout = 0.000001
-        ably = create_http_client(token="foo", http_request_timeout=timeout)
-        assert ably.http.http_request_timeout == timeout
-        # `http_open_timeout` keeps its four-second default, so the request carries a
+        ably = create_http_client(token="foo", http_request_timeout_seconds=timeout)
+        assert ably.http.http_request_timeout_seconds == timeout
+        # `http_open_timeout_seconds` keeps its four-second default, so the request carries a
         # connect budget as well as a read budget and either can be the one to expire
         with pytest.raises(AblyException) as excinfo:
             await ably.request('GET', '/time', version=Defaults.protocol_version)
diff --git a/test/unit/clock_test.py b/test/unit/clock_test.py
index e363291b..8ba499e5 100644
--- a/test/unit/clock_test.py
+++ b/test/unit/clock_test.py
@@ -109,10 +109,10 @@ async def test_every_host_is_tried_while_the_retry_budget_lasts():
 
 
 async def test_retrying_stops_once_the_retry_budget_is_spent():
-    # RSC15l: http_max_retry_duration is seconds where the clock is milliseconds
+    # RSC15l: http_max_retry_duration_seconds is a budget in seconds, read off a clock in milliseconds
     clock = FakeClock(step_ms=1000)
     transport = RecordingTransport()
-    ably = create_http_client(token='foo', http_max_retry_duration=0.5,
+    ably = create_http_client(token='foo', http_max_retry_duration_seconds=0.5,
                               _test_options=TestOptions(http_transport=transport, clock=clock))
     transport.refusing = tuple(ably.http.get_hosts())
 
diff --git a/test/unit/http_test.py b/test/unit/http_test.py
index cc9196d4..2d8b2f1d 100644
--- a/test/unit/http_test.py
+++ b/test/unit/http_test.py
@@ -53,7 +53,7 @@ async def test_http_sends_requests_through_an_injected_transport():
 
 async def test_http_bounds_every_phase_of_a_request():
     transport = RecordingTransport(lambda request: httpx.Response(200, json=[1500000000000]))
-    ably = create_http_client(token="foo", http_open_timeout=2, http_request_timeout=7,
+    ably = create_http_client(token="foo", http_open_timeout_seconds=2, http_request_timeout_seconds=7,
                               _test_options=TestOptions(http_transport=transport))
 
     await ably.time()
diff --git a/test/unit/options_test.py b/test/unit/options_test.py
index fca93a06..c612e82b 100644
--- a/test/unit/options_test.py
+++ b/test/unit/options_test.py
@@ -181,10 +181,31 @@ def test_realtime_timing_options_read_back_what_was_given(option):
     assert getattr(opts, '_' + option.replace('_seconds', '_ms')) == 250
 
 
+# TO3l3, TO3l4, TO3l6: the HTTP timing options were always seconds, and are now named for it
+HTTP_TIMING_DEFAULTS = {
+    'http_open_timeout_seconds': 4,
+    'http_request_timeout_seconds': 10,
+    'http_max_retry_duration_seconds': 15,
+}
+
+
+@pytest.mark.parametrize('option, default', HTTP_TIMING_DEFAULTS.items())
+def test_http_timing_options_read_back_their_defaults_in_seconds(option, default):
+    assert getattr(Options(), option) == default
+    assert getattr(Options(**{option: 2.5}), option) == 2.5
+
+
+def test_the_http_layer_reads_the_timing_options_in_seconds():
+    ably = create_http_client(token='foo', http_open_timeout_seconds=2.5, http_request_timeout_seconds=7)
+    assert ably.http.http_open_timeout_seconds == 2.5
+    assert ably.http.http_request_timeout_seconds == 7
+
+
 @pytest.mark.parametrize('option', ['realtime_request_timeout', 'disconnected_retry_timeout',
                                     'suspended_retry_timeout', 'channel_retry_timeout',
-                                    'fallback_retry_timeout'])
-def test_options_should_reject_the_millisecond_names(option):
+                                    'fallback_retry_timeout', 'http_open_timeout',
+                                    'http_request_timeout', 'http_max_retry_duration'])
+def test_options_should_reject_the_old_timing_names(option):
     with pytest.raises(TypeError):
         Options(**{option: 15000})
 
diff --git a/test/uts/deviations.md b/test/uts/deviations.md
index 586a498a..0bb08cf9 100644
--- a/test/uts/deviations.md
+++ b/test/uts/deviations.md
@@ -33,8 +33,8 @@ parametrized over a table of fixtures the specification gives inline; and five
 `objects/unit` tests are parametrized, three over a table and two over the scenarios the
 specification loops through. That turns 1481 derived tests into 1608 pytest cases.
 
-Of **1472 Test IDs, derived as 1481 tests and run as 1608 pytest cases**: 1303 Test IDs
-(1312 tests, 1437 cases) pass, 142 (142 tests, 144 cases) are gated behind
+Of **1472 Test IDs, derived as 1481 tests and run as 1608 pytest cases**: 1304 Test IDs
+(1313 tests, 1438 cases) pass, 141 (141 tests, 143 cases) are gated behind
 `RUN_DEVIATIONS`, and 27 (27 tests, 27 cases) cannot be run at all. The three groups are
 disjoint: two Test IDs have a gated part and a passing part — `TI1`, as two functions, and
 `TO/endpoint-affects-host`, as one parametrized test — and are counted with the gated,
@@ -45,16 +45,16 @@ the Test IDs come from `uts/rest/unit` (503 tests, 536 cases), 482 from
 `uts/rest/integration` (84, 122), 73 from `uts/realtime/integration` (73, 95) and 17 from
 `uts/objects/integration` (17, 29); 8 of the REST integration ids (8, 8), 30 of the
 realtime ones (30, 30) and 5 of the objects ones (5, 5) come from the `proxy` package
-within each. Of the gated Test IDs 64 are REST and 78 realtime, which is 65 REST cases
+within each. Of the gated Test IDs 63 are REST and 78 realtime, which is 64 REST cases
 and 79 realtime. None of the 339 objects Test IDs is gated or unrunnable.
 A further 148 pytest cases cover the harness itself and are not derived from a
 specification: 130 under `helpers/`, for the mocks, and 18 under `objects/helpers/`, for
 the objects builders and the synced-channel mock.
 
-The 131 gated Test IDs that record SDK non-compliance — 131 tests, 133 cases — reduce to
-**55 distinct root causes**, 18 on the REST side and 37 on the realtime side. One further
+The 130 gated Test IDs that record SDK non-compliance — 130 tests, 132 cases — reduce to
+**54 distinct root causes**, 17 on the REST side and 37 on the realtime side. One further
 defect is recorded below with no test of its own, because the specification's test
-cannot discriminate (RTP18a), so the file carries **56 SDK root causes** in all. The
+cannot discriminate (RTP18a), so the file carries **55 SDK root causes** in all. The
 remaining 11 gated Test IDs are specification faults, and reduce to 8. The objects tier
 records no SDK non-compliance; its specification faults are all corrected or worked
 around in tests that pass, and reduce to the seven candidate issues O.1–O.7, none of
@@ -1713,54 +1713,6 @@ final response is raised or returned.
 |---|---|
 | TO3 | `endpoint` is left unset when none is given, per `TO/endpoint-affects-host-0`. `Options.__init__` resolves the default eagerly to the REC1a routing policy id `main`, so the attribute never reads back as null. Only the default case is gated; the two that name an endpoint are derived and pass |
 
-#### `httpRequestTimeout` is seconds where the specification counts milliseconds — 1 test
-
-**Spec points:** TO3l4, RSC15l2, `rest/proxy/RSC15l2/timeout-triggers-fallback-0`.
-
-`Http.make_request` (`ably/pubsub/request/http.py`) builds `timeout =
-httpx.Timeout(self.http_request_timeout, connect=self.http_open_timeout)` and hands it
-to `httpx`, which reads both as **seconds**.
-TO3l4's `httpRequestTimeout` is milliseconds, default 10000, and
-`Defaults.http_request_timeout` holds `10`. So a caller passing the value the published
-specification describes gets a deadline a thousand times longer than the one asked for:
-`http_request_timeout=3000` is three thousand seconds. The **defaults** come out right
-by coincidence — 10 seconds is TO3l4's 10000 ms, and `http_open_timeout`'s 4 is TO3l3's
-4000 — which is why only a client that configures the option is affected, and why the
-mismatch reads as cosmetic anywhere it is only compared against `options`.
-
-Measured through the proxy. Against a session delaying the first `/time` by 20 seconds,
-a client built with the specification's `httpRequestTimeout: 3000` sat out the whole
-delay, succeeded on the primary host, and tried no fallback — one `/time` request in the
-event log where the test asserts two, which is the `assert 1 >= 2` the gated run shows.
-Passing `3` in its place makes the same test pass in 3.1 seconds: the timeout fires, the
-retry goes to the fallback host and succeeds. So RSC15l2's fallback path is compliant and
-the unit is the whole of the defect.
-
-The same mismatch is recorded twice under *Adapted Tests*, at `TO3l4, TO3l5` and at
-`RTC7 (TO3l3, TO3l4)` in *REST behaviours asserted as they are*, where it is why the
-defaults read back from `options` as 4 and 10. This is that defect seen from outside:
-the same line of `http.py`, reached through a public client option rather than through an
-attribute, so a caller is affected whether or not they ever read `options`. It is counted
-as one root cause, here, because it is the only gated test on it; neither Adapted Tests
-row is counted again.
-
-**Tests affected:** `test_rsc15l2_timeout_triggers_fallback`, the one gated test in
-`rest/integration/proxy`. The test is written exactly as the specification has it, with
-`http_request_timeout=3000`, so removing the gate is all that is needed once the unit is
-fixed.
-
-**Status:** open bug. The fix converts at the boundary — `Http` dividing the option by
-1000 before it reaches `httpx`, with the `Defaults` restated in
-milliseconds — and has to move `http_open_timeout` (TO3l3) with it, since both are
-read the same way. Moving the unit is breaking, and is held back from 4.0.0 pending a
-decision on units across the options. That same line carries a second, filed defect:
-[#709](https://github.com/ably/ably-python/issues/709) is that the value, in whatever
-unit, bounds one socket read rather than the request, so a connection that keeps
-producing frames is never timed out. Of #709's three parts, only the unbounded `write`
-and `pool` timeouts are fixed, both now taking `http_request_timeout`. The rest of it and
-the unit want fixing together, since both change what one attempt may spend of the
-RSC15 retry budget.
-
 ### Requests
 
 | Spec points | Behaviour |
@@ -2078,6 +2030,19 @@ boundary of an `ADVANCE_TIME` still fires.
 | TO3l2 | `suspendedRetryTimeout`, ms, default 30000 | `suspended_retry_timeout_seconds`, default 30 | `test_rtc7_default_timeouts_applied`, and every realtime test that sets it |
 | TO3l7 | `channelRetryTimeout`, ms, default 15000 | `channel_retry_timeout_seconds`, default 15 | every channel test that sets it, among them the RTL13b and RTB1 tests |
 | TO3l10 | `fallbackRetryTimeout`, ms, default 600000 | `fallback_retry_timeout_seconds`, default 600 | the RSC15f tests in `rest/unit/fallback_test.py` |
+| TO3l3 | `httpOpenTimeout`, ms, default 4000 | `http_open_timeout_seconds`, default 4 | `test_rtc7_default_timeouts_applied` |
+| TO3l4 | `httpRequestTimeout`, ms, default 10000 | `http_request_timeout_seconds`, default 10 | `test_to3_client_options_attributes`, `test_rtc7_default_timeouts_applied`, the RSC13, RSC15l and RSC19e unit tests, and `test_rsc15l2_timeout_triggers_fallback`, whose `httpRequestTimeout: 3000` is `http_request_timeout_seconds=3` |
+| TO3l6 | `httpMaxRetryDuration`, ms, default 15000 | `http_max_retry_duration_seconds`, default 15 | none sets it; `test/unit` covers the budget |
+
+The HTTP options were already seconds, under names that did not say so, which put
+`rest/proxy/RSC15l2/timeout-triggers-fallback-0` behind `RUN_DEVIATIONS`: written with the
+specification's `httpRequestTimeout: 3000`, its request sat out the proxy's whole 20-second
+delay on the primary host, where 3 seconds times out at 3.1 and the retry succeeds on the
+fallback. RSC15l2's fallback path was compliant throughout. Of
+[#709](https://github.com/ably/ably-python/issues/709), filed on the same line of
+`http.py`, the unbounded `write` and `pool` timeouts are fixed; that the value bounds one
+socket read rather than the request, and that the RSC15 retry budget is not consulted while
+an attempt is in flight, are not.
 
 ### Channel and presence behaviours asserted as they are
 
@@ -2129,8 +2094,8 @@ pseudocode is not mistaken for non-compliance.
 | CHM2g, CHM2h | `objectPublishers` and `objectSubscribers` on `ChannelMetrics` | Neither is modelled, so both are dropped on parsing. The test asserts their absence, and turns red once they are added | Open bug |
 | TO3l8, CD2c | `maxMessageSize` is a client option, default 65536, which `connectionDetails.maxMessageSize` overrides for realtime publishes | The option and its default match, and REST and realtime publishes both measure per TM6 and raise 40009. `ConnectionDetails.from_dict` does not parse `maxMessageSize`, so a realtime publish is checked against the client option alone. No test asserts CD2c; `test_rtn24_connection_details_override` sends the field and reads back only the details ably-python parses | Open bug, CD2c only |
 | RTN15, RTN23 | A DISCONNECTED `ErrorInfo` needs no `statusCode` | `ConnectionManager.on_disconnected` evaluates `exception.status_code >= 500` unguarded, so a DISCONNECTED whose error omits `statusCode` raises `TypeError` in a task whose exception is only logged, and the connection silently stays CONNECTED. `DISCONNECTED_MESSAGE` supplies 400 | Open bug |
-| TO3l4, TO3l5 | `httpRequestTimeout` defaults to 10000 and `httpMaxRetryCount` to 3 on the options object | Both are defaulted on `Options`. `http_max_retry_count` reads back as 3 and matches; `http_request_timeout` reads back as 10, because ably-python's is seconds where the spec's is milliseconds, on the value a caller passes as much as on the default — gated, with the measurement, under *`httpRequestTimeout` is seconds where the specification counts milliseconds* in Failing Tests | The unit is an open bug, recorded there |
-| RTC7 (TO3l3, TO3l4) | `client.options.httpOpenTimeout == 4000` and `httpRequestTimeout == 10000` | 4 and 10: both are defaulted on `Options`, in seconds where TO3l3 and TO3l4 count milliseconds. The three realtime timeouts the same test checks read back as `realtime_request_timeout_seconds == 10`, `disconnected_retry_timeout_seconds == 15` and `suspended_retry_timeout_seconds == 30`, which is intentional: see *Timing options are seconds, and named for it* | Open bug for the HTTP pair, and the unit reaches the wire — `rest/proxy/RSC15l2/timeout-triggers-fallback-0` measures a request outliving its configured timeout by a factor of a thousand. Gated under *`httpRequestTimeout` is seconds where the specification counts milliseconds* in Failing Tests. Moving the HTTP durations to milliseconds is breaking, and is held back from 4.0.0 pending a decision on units across the options |
+| TO3l4, TO3l5 | `httpRequestTimeout` defaults to 10000 and `httpMaxRetryCount` to 3 on the options object | Both are defaulted on `Options`. `http_max_retry_count` reads back as 3 and matches; `http_request_timeout_seconds` reads back as 10, the same default in the seconds ably-python's timing options take | Intentional: see *Timing options are seconds, and named for it* |
+| RTC7 (TO3l3, TO3l4) | `client.options.httpOpenTimeout == 4000` and `httpRequestTimeout == 10000`, with the three realtime timeouts at 10000, 15000 and 30000 | `http_open_timeout_seconds == 4` and `http_request_timeout_seconds == 10`, and `realtime_request_timeout_seconds == 10`, `disconnected_retry_timeout_seconds == 15` and `suspended_retry_timeout_seconds == 30`: the same defaults, in seconds | Intentional: see *Timing options are seconds, and named for it* |
 | RTC1f | a `transportParams` boolean appears as `"true"` / `"false"` | `True` / `False`, because `WebSocketTransport.connect` builds the query string with `urllib.parse.urlencode`, which renders each value through `str()` (`websockettransport.py:89`). Integers are unaffected | Open bug. A caller can pass the strings directly, but a bool is what the spec's Stringifiable type admits |
 
 ### LiveObjects: the internal shapes the unit specifications assume — S-1 to S-6
@@ -2512,7 +2477,7 @@ is missing accessors over correct behaviour. Within a tier the order is blast ra
 | [#706](https://github.com/ably/ably-python/issues/706) | the fabricated `"None:0"` message id | 3.3 |
 | [#658](https://github.com/ably/ably-python/issues/658) | presence messages sent on reconnection before reattach | adjacent to 3.13, which is the other half of RTP17 automatic re-entry |
 | [#656](https://github.com/ably/ably-python/issues/656) | `utcfromtimestamp` deprecation | none: `PresenceMessage.timestamp` is now milliseconds since the epoch, the synthesized LEAVE's included, and no `utcfromtimestamp` remains |
-| [#709](https://github.com/ably/ably-python/issues/709)–[#712](https://github.com/ably/ably-python/issues/712) | REST request timeout, token-request nonce reuse, single-host retry, `dispose()` teardown | adjacent to I.3, which is a second defect on the line #709 is about and is not covered by it; otherwise none, these having been filed from the REST derivation |
+| [#709](https://github.com/ably/ably-python/issues/709)–[#712](https://github.com/ably/ably-python/issues/712) | REST request timeout, token-request nonce reuse, single-host retry, `dispose()` teardown | none, these having been filed from the REST derivation. The timeout's unit, once a second defect on #709's line, is settled by the `_seconds` options; see *Timing options are seconds, and named for it* |
 
 Every reproduction below is prefixed by:
 
@@ -2779,11 +2744,10 @@ none of these shows up as a failure — which is why they are easy to lose.
 
 The five tiers above classify the realtime unit derivation; the REST unit derivation's
 candidates went upstream as [#709](https://github.com/ably/ably-python/issues/709)–[#712](https://github.com/ably/ably-python/issues/712).
-Four further defects came out of the two integration tiers, and none of them is filed; each
+Three further defects came out of the two integration tiers, and none of them is filed; each
 keeps the label it was first given. I.1 is tier 2 by the ranking above — an error where
-there should be none — and I.3 is tier 1 for a client that configures the option it
-concerns, since the call does not come back when the caller asked for it to. I.6 is tier 2
-as well; I.5 is tier 3, a presence member silently leaving the set with nothing to report it.
+there should be none — and so is I.6; I.5 is tier 3, a presence member silently leaving the
+set with nothing to report it.
 
 The realtime integration tier also put four defects the unit tier had already recorded in
 front of the real server, and those extend the entries above rather than opening issues of
@@ -2802,20 +2766,6 @@ offset. The same expired token renews correctly through `publish()`. A fix has t
 the two meanings `raise_on_error` carries.
 `test/uts/rest/integration/auth_test.py -k rsc10`
 
-**I.3 `httpRequestTimeout` is applied as seconds where the specification counts
-milliseconds.** TO3l4, TO3l3, RSC15l2. `Http.make_request` hands `http_open_timeout`
-and `http_request_timeout` to `httpx`, which reads seconds, so a client
-built with the specification's `httpRequestTimeout: 3000` waits three thousand seconds.
-Measured through `uts-proxy` against a session delaying `/time` by 20 seconds: the
-request sat out the whole delay, succeeded on the primary host and attempted no
-fallback, where `http_request_timeout=3` timed out at 3.1 seconds and the fallback retry
-succeeded. The defaults are unaffected, 4 and 10 seconds being TO3l3's and TO3l4's 4000
-and 10000 ms, so this reaches only a client that sets the option — but such a client gets
-no timeout and no fallback at all. Distinct from
-[#709](https://github.com/ably/ably-python/issues/709), which is about the same value
-bounding a single socket read rather than the request; a fix wants to settle both.
-`test/uts/rest/integration/proxy/rest_fallback_test.py -k rsc15l2`
-
 **I.5 RTP17i re-entry never runs on a channel that is already ATTACHED.** RTP17i, RTP17g.
 `RealtimePresence.on_attached()` is reached only from `RealtimeChannel._notify_state()`, and
 an ATTACHED arriving on an already-attached channel takes the RTL12 branch
@@ -3408,8 +3358,8 @@ The header states how many derived tests there are, how many pass, how many are
 gated and how many cannot run. Those numbers are the check that the file is still
 true: in pytest cases, the gated count must equal the number of failures under
 `RUN_DEVIATIONS=1`, and gated plus unrunnable must equal the number of skips without
-it. As of this writing that is 144 failures, 1585 passes and 27 skips with the variable
-set, and 171 skips and 1585 passes without it, the 1585 being 1437 derived cases and 148
+it. As of this writing that is 143 failures, 1586 passes and 27 skips with the variable
+set, and 170 skips and 1586 passes without it, the 1586 being 1438 derived cases and 148
 harness ones — 130 under `helpers/` and 18 under `objects/helpers/`. Those figures need
 the `submodules` checkout CI makes: without it, three `rest/unit/encoding` tests that read
 the ably-common fixtures skip as well. The tiers are told apart by the junit report's
diff --git a/test/uts/helpers/mock_http_test.py b/test/uts/helpers/mock_http_test.py
index e48d65a8..ea1ec0da 100644
--- a/test/uts/helpers/mock_http_test.py
+++ b/test/uts/helpers/mock_http_test.py
@@ -614,7 +614,7 @@ async def test_queue_response_for_url_matches_a_key_written_with_a_default_port(
 async def test_a_delayed_response_beyond_the_read_budget_times_out():
     mock = MockHttpClient()
     mock.queue_delayed_response(5000, 200, [1])
-    ably = rest_client(mock, http_request_timeout=0.05)
+    ably = rest_client(mock, http_request_timeout_seconds=0.05)
 
     started = time.monotonic()
     with pytest.raises(AblyException):
@@ -629,7 +629,7 @@ async def test_a_delayed_response_beyond_the_read_budget_times_out():
 async def test_a_delayed_response_within_the_read_budget_arrives():
     mock = MockHttpClient()
     mock.queue_delayed_response(20, 200, [7])
-    ably = rest_client(mock, http_request_timeout=5)
+    ably = rest_client(mock, http_request_timeout_seconds=5)
 
     assert await ably.time() == 7
 
diff --git a/test/uts/realtime/unit/client/realtime_timeouts_test.py b/test/uts/realtime/unit/client/realtime_timeouts_test.py
index c466f7fb..989e3454 100644
--- a/test/uts/realtime/unit/client/realtime_timeouts_test.py
+++ b/test/uts/realtime/unit/client/realtime_timeouts_test.py
@@ -178,7 +178,7 @@ async def test_rtc7_default_timeouts_applied():
     assert client.options.suspended_retry_timeout_seconds == 30
 
     # DEVIATION: the spec asserts httpOpenTimeout == 4000 and httpRequestTimeout ==
-    # 10000. ably-python's HTTP timeouts are in seconds rather than milliseconds, so the
-    # same defaults read back as 4 and 10. See deviations.md.
-    assert client.options.http_open_timeout == 4
-    assert client.options.http_request_timeout == 10
+    # 10000. ably-python's HTTP timeouts are in seconds and named for it, so the same
+    # defaults read back as 4 and 10 under `*_seconds` names. See deviations.md.
+    assert client.options.http_open_timeout_seconds == 4
+    assert client.options.http_request_timeout_seconds == 10
diff --git a/test/uts/rest/integration/proxy/rest_fallback_test.py b/test/uts/rest/integration/proxy/rest_fallback_test.py
index afafb084..1e684c94 100644
--- a/test/uts/rest/integration/proxy/rest_fallback_test.py
+++ b/test/uts/rest/integration/proxy/rest_fallback_test.py
@@ -22,15 +22,14 @@
 from ably.pubsub.server import create_http_client
 from ably.pubsub.util.exceptions import AblyException
 from test.uts.helpers.client import sandbox_rest_client, wall_clock_poll_until
-from test.uts.helpers.deviations import deviation
 from test.uts.helpers.sandbox import SANDBOX_ENDPOINT, random_id
 
 # The specification's `non_listening_port`: a port nothing is bound to, so that
 # connecting to it is refused rather than answered.
 NON_LISTENING_PORT = 19999
 
-# The specification's `httpRequestTimeout: 3000`.
-HTTP_REQUEST_TIMEOUT_MS = 3000
+# The specification's `httpRequestTimeout: 3000`, in the seconds the client option takes.
+HTTP_REQUEST_TIMEOUT_SECONDS = 3
 
 
 def token_auth_callback(api_key):
@@ -75,7 +74,6 @@ def http_responses(log):
     return [event for event in log if event['type'] == 'http_response']
 
 
-@deviation
 # UTS: rest/proxy/RSC15l2/timeout-triggers-fallback-0
 async def test_rsc15l2_timeout_triggers_fallback(sandbox, proxy_session):
     session = await proxy_session(rules=[{
@@ -95,7 +93,7 @@ async def test_rsc15l2_timeout_triggers_fallback(sandbox, proxy_session):
         port=session.proxy_port,
         tls=False,
         use_binary_protocol=False,
-        http_request_timeout=HTTP_REQUEST_TIMEOUT_MS,
+        http_request_timeout_seconds=HTTP_REQUEST_TIMEOUT_SECONDS,
     )
 
     result = await client.time()
diff --git a/test/uts/rest/unit/fallback_test.py b/test/uts/rest/unit/fallback_test.py
index 403d67d2..1a60a8ee 100644
--- a/test/uts/rest/unit/fallback_test.py
+++ b/test/uts/rest/unit/fallback_test.py
@@ -138,8 +138,8 @@ async def test_rsc15l_qualifying_errors_trigger_fallback_request_timeout():
     mock_http.queue_timeout()
     mock_http.queue_response(200, TIME_BODY)
 
-    # The spec sets httpRequestTimeout to 1000; ably-python takes seconds
-    client = rest_client(mock_http, http_request_timeout=1)
+    # The spec sets httpRequestTimeout to 1000 ms, which is 1 in seconds
+    client = rest_client(mock_http, http_request_timeout_seconds=1)
 
     await client.time()
 
@@ -235,7 +235,7 @@ def on_connection_attempt(conn):
         on_connection_attempt=on_connection_attempt,
         on_request=lambda req: req.respond_with(200, TIME_BODY),
     )
-    client = rest_client(mock_http, http_request_timeout=1)
+    client = rest_client(mock_http, http_request_timeout_seconds=1)
 
     result = await client.time()
 
@@ -263,7 +263,7 @@ def on_request(req):
             req.respond_with(200, TIME_BODY)
 
     mock_http = MockHttpClient(on_connection_attempt=on_connection_attempt, on_request=on_request)
-    client = rest_client(mock_http, http_request_timeout=1)
+    client = rest_client(mock_http, http_request_timeout_seconds=1)
 
     result = await client.time()
 
diff --git a/test/uts/rest/unit/request_test.py b/test/uts/rest/unit/request_test.py
index 612dfe8c..6aa38968 100644
--- a/test/uts/rest/unit/request_test.py
+++ b/test/uts/rest/unit/request_test.py
@@ -433,14 +433,14 @@ async def test_rsc19e_network_error_propagated():
 # UTS: rest/unit/RSC19e/timeout-error-handling-1
 async def test_rsc19e_timeout_error_handling():
     # NOTE: the spec drives this with a 5s delayed response against a 1s
-    # http_request_timeout (which it gives in milliseconds; ably-python takes seconds).
+    # httpRequestTimeout, which is http_request_timeout_seconds=1 here.
     # An injected transport is responsible for enforcing httpx timeouts, and the mock
     # does not implement them, so a delayed response would simply be waited out.
     # queue_timeout() raises the read timeout the client would otherwise have seen.
     mock_http = MockHttpClient(on_connection_attempt=succeed)
     mock_http.queue_timeout()
 
-    client = rest_client(mock_http, key=SPEC_KEY, http_request_timeout=1, fallback_hosts=[])
+    client = rest_client(mock_http, key=SPEC_KEY, http_request_timeout_seconds=1, fallback_hosts=[])
 
     with pytest.raises(AblyException) as excinfo:
         await client.request('GET', '/test', version='3')
diff --git a/test/uts/rest/unit/rest_client_test.py b/test/uts/rest/unit/rest_client_test.py
index fd3454c5..2702a0fc 100644
--- a/test/uts/rest/unit/rest_client_test.py
+++ b/test/uts/rest/unit/rest_client_test.py
@@ -223,14 +223,14 @@ async def test_rsc8_error_decoded_from_msgpack():
 
 # UTS: rest/unit/RSC13/request-timeout-enforced-0
 async def test_rsc13_request_timeout_enforced():
-    # NOTE: http_request_timeout is seconds in ably-python where the spec counts milliseconds,
-    # so the spec's 1000ms is shortened to 0.1 to keep the test quick.
+    # NOTE: the spec's httpRequestTimeout of 1000 ms would be http_request_timeout_seconds=1;
+    # it is shortened to 0.1 to keep the test quick.
     # Every host delays, because a timed-out request sends the client on to the next one.
     mock_http = MockHttpClient(
         on_connection_attempt=connect_successfully,
         on_request=lambda request: request.respond_with_delay(5000, 200, TIME_RESPONSE),
     )
-    client = rest_client(mock_http, http_request_timeout=0.1)
+    client = rest_client(mock_http, http_request_timeout_seconds=0.1)
 
     with pytest.raises(AblyException) as excinfo:
         await client.time()
diff --git a/test/uts/rest/unit/types/options_types_test.py b/test/uts/rest/unit/types/options_types_test.py
index 93a9c520..24bef56b 100644
--- a/test/uts/rest/unit/types/options_types_test.py
+++ b/test/uts/rest/unit/types/options_types_test.py
@@ -36,10 +36,10 @@ async def test_to3_client_options_attributes():
     assert options.auth_method == 'GET'
     assert options.tls is True
 
-    # DEVIATION: the spec asserts httpRequestTimeout == 10000. ably-python's
-    # http_request_timeout is in seconds rather than milliseconds, so the same default
-    # reads back as 10. See deviations.md.
-    assert options.http_request_timeout == 10
+    # DEVIATION: the spec asserts httpRequestTimeout == 10000. ably-python's timing
+    # options are in seconds and named for it, so the same default reads back as
+    # http_request_timeout_seconds == 10. See deviations.md.
+    assert options.http_request_timeout_seconds == 10
     assert options.http_max_retry_count == 3
 
     assert options.use_binary_protocol is True
@@ -52,7 +52,7 @@ async def test_to3_client_options_attributes():
     # The HTTP layer applies the defaults the options hold: 10 seconds, and the primary
     # host plus 3 fallbacks to try (TO3l5).
     client = rest_client(mock_http_client())
-    assert client.http.http_request_timeout == 10
+    assert client.http.http_request_timeout_seconds == 10
     assert len(client.options.get_hosts()) == 4
 
     options = Options(
@@ -60,7 +60,8 @@ async def test_to3_client_options_attributes():
         client_id='my-client',
         endpoint='test',
         tls=False,
-        http_request_timeout=30000,
+        # The specification's httpRequestTimeout: 30000, in seconds
+        http_request_timeout_seconds=30,
         use_binary_protocol=False,
         idempotent_rest_publishing=False,
         add_request_ids=True,
@@ -71,7 +72,7 @@ async def test_to3_client_options_attributes():
     assert options.client_id == 'my-client'
     assert options.endpoint == 'test'
     assert options.tls is False
-    assert options.http_request_timeout == 30000
+    assert options.http_request_timeout_seconds == 30
     assert options.use_binary_protocol is False
     assert options.idempotent_rest_publishing is False
     assert options.add_request_ids is True

From f8bfcedf70fc9fa80d7fa5add12486a32aad4892 Mon Sep 17 00:00:00 2001
From: owenpearson <owen.pearson@ably.com>
Date: Wed, 28 Oct 2026 13:26:23 +0000
Subject: [PATCH 3/5] pubsub: name the replacement when a renamed timing option
 is passed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The two commits before this one rename the eight timing options with a
_seconds suffix. Options passes the keyword arguments it does not know
on to AuthOptions, so a 3.x name already raised TypeError at
construction, but with Python's bare "unexpected keyword argument",
which says nothing about the rename or the change of unit.

Options now checks for the eight 3.x names before anything else and
raises a TypeError naming the replacement. For the five options that
took milliseconds it also converts the value passed, for instance
"`disconnected_retry_timeout` was renamed to
`disconnected_retry_timeout_seconds` in 4.0 and is now in seconds
(15000 ms → 15)", falling back to the 3.x default where the value is
not a finite number; for the three HTTP options it says the unit is
unchanged. The factories reach it through Options, so it covers both
clients and Options itself. It is still a TypeError, so nothing that
raised before stops raising or raises something else, and a missing
credential is still reported first, as 40106.

UPDATING.md shows the messages and the eight renames together, and
test/uts/deviations.md notes the hint. No UTS test passes an old name,
so the counts do not change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 UPDATING.md                  | 27 +++++++++++++++++++++++++
 ably/pubsub/types/options.py | 35 ++++++++++++++++++++++++++++++++
 test/unit/options_test.py    | 39 +++++++++++++++++++++++++++++++-----
 test/uts/deviations.md       |  3 ++-
 4 files changed, 98 insertions(+), 6 deletions(-)

diff --git a/UPDATING.md b/UPDATING.md
index 9d97eead..d10f6923 100644
--- a/UPDATING.md
+++ b/UPDATING.md
@@ -852,6 +852,33 @@ pubsub_http_client = create_http_client(
 )
 ```
 
+### 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.
+
 ## 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:
diff --git a/ably/pubsub/types/options.py b/ably/pubsub/types/options.py
index a758404e..b5a8aee6 100644
--- a/ably/pubsub/types/options.py
+++ b/ably/pubsub/types/options.py
@@ -1,4 +1,5 @@
 import logging
+import math
 import random
 from abc import ABC, abstractmethod
 
@@ -20,6 +21,39 @@ def seconds_to_ms(seconds):
     return int(ms) if ms == int(ms) else ms
 
 
+# The timing options renamed in 4.0, by their 3.x name, with the 3.x unit and default
+_RENAMED_TIMING_OPTIONS = {
+    'realtime_request_timeout': ('ms', 10000),
+    'disconnected_retry_timeout': ('ms', 15000),
+    'suspended_retry_timeout': ('ms', 30000),
+    'channel_retry_timeout': ('ms', 15000),
+    'fallback_retry_timeout': ('ms', 600000),
+    'http_open_timeout': ('s', 4),
+    'http_request_timeout': ('s', 10),
+    'http_max_retry_duration': ('s', 15),
+}
+
+
+def _reject_renamed_timing_options(kwargs):
+    """Raises a TypeError naming the replacement for a timing option's 3.x name.
+
+    An unknown option raises TypeError anyway; this one says what to pass instead, and for
+    an option that took milliseconds, what the value passed comes to in seconds.
+    """
+    for name, (unit, default) in _RENAMED_TIMING_OPTIONS.items():
+        if name not in kwargs:
+            continue
+        message = f'`{name}` was renamed to `{name}_seconds` in 4.0'
+        if unit == 's':
+            raise TypeError(f'{message}; it is still in seconds')
+        value = kwargs[name]
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+            value = default
+        seconds = value / 1000
+        seconds = int(seconds) if seconds == int(seconds) else seconds
+        raise TypeError(f'{message} and is now in seconds ({value} ms → {seconds})')
+
+
 class VCDiffDecoder(ABC):
     """
     The VCDiffDecoder class defines the interface for delta decoding operations.
@@ -65,6 +99,7 @@ def __init__(self, client_id=None, tls=True, port=0,
                  vcdiff_decoder: VCDiffDecoder = None, transport_params=None, echo_messages=True,
                  max_message_size=None, _test_options=None, **kwargs):
 
+        _reject_renamed_timing_options(kwargs)
         super().__init__(**kwargs)
 
         # TO3l10, TO3l11, TO3l1, TO3l2 and TO3l7 count milliseconds, and these options take
diff --git a/test/unit/options_test.py b/test/unit/options_test.py
index c612e82b..4a8d9d53 100644
--- a/test/unit/options_test.py
+++ b/test/unit/options_test.py
@@ -1,6 +1,8 @@
+from datetime import timedelta
+
 import pytest
 
-from ably.pubsub.server import create_http_client
+from ably.pubsub.server import create_http_client, create_realtime_client
 from ably.pubsub.types.options import Options, seconds_to_ms
 from ably.pubsub.util.exceptions import AblyException
 
@@ -203,11 +205,38 @@ def test_the_http_layer_reads_the_timing_options_in_seconds():
 
 @pytest.mark.parametrize('option', ['realtime_request_timeout', 'disconnected_retry_timeout',
                                     'suspended_retry_timeout', 'channel_retry_timeout',
-                                    'fallback_retry_timeout', 'http_open_timeout',
-                                    'http_request_timeout', 'http_max_retry_duration'])
-def test_options_should_reject_the_old_timing_names(option):
-    with pytest.raises(TypeError):
+                                    'fallback_retry_timeout'])
+def test_a_millisecond_name_raises_naming_its_replacement_and_the_value_in_seconds(option):
+    with pytest.raises(TypeError) as excinfo:
         Options(**{option: 15000})
+    assert str(excinfo.value) == (f'`{option}` was renamed to `{option}_seconds` in 4.0 and is now '
+                                  'in seconds (15000 ms → 15)')
+
+
+@pytest.mark.parametrize('option', ['http_open_timeout', 'http_request_timeout', 'http_max_retry_duration'])
+def test_an_http_name_raises_naming_its_replacement(option):
+    with pytest.raises(TypeError) as excinfo:
+        Options(**{option: 4})
+    assert str(excinfo.value) == f'`{option}` was renamed to `{option}_seconds` in 4.0; it is still in seconds'
+
+
+@pytest.mark.parametrize('value, seconds', [(2500, '2.5'), (100, '0.1'), (1234, '1.234'), (0, '0')])
+def test_the_rename_hint_converts_the_value_given(value, seconds):
+    with pytest.raises(TypeError, match=f'[(]{value} ms → {seconds}[)]$'):
+        Options(disconnected_retry_timeout=value)
+
+
+@pytest.mark.parametrize('value', ['15000', None, True, float('nan'), float('inf'), timedelta(seconds=15)])
+def test_the_rename_hint_falls_back_to_the_default_for_a_value_it_cannot_convert(value):
+    with pytest.raises(TypeError, match='[(]15000 ms → 15[)]$'):
+        Options(disconnected_retry_timeout=value)
+
+
+def test_the_factories_raise_the_rename_hint():
+    with pytest.raises(TypeError, match='`realtime_request_timeout_seconds`'):
+        create_http_client(key='appId.keyId:keySecret', realtime_request_timeout=10000)
+    with pytest.raises(TypeError, match='`suspended_retry_timeout_seconds`'):
+        create_realtime_client(key='appId.keyId:keySecret', auto_connect=False, suspended_retry_timeout=30000)
 
 
 @pytest.mark.parametrize('seconds, ms', [
diff --git a/test/uts/deviations.md b/test/uts/deviations.md
index 0bb08cf9..b1910c43 100644
--- a/test/uts/deviations.md
+++ b/test/uts/deviations.md
@@ -2011,7 +2011,8 @@ adapted.
 Intentional. TO3l counts every timing option in milliseconds; ably-python takes seconds,
 which is what a Python caller expects, and names each option with a `_seconds` suffix so
 the unit is on the page. A 3.x caller passing the old name gets a `TypeError` at
-construction, rather than a value a thousand times too long. The wire values the
+construction that names the replacement and, for an option that took milliseconds, gives
+the value passed in seconds, rather than a value a thousand times too long. The wire values the
 specification also counts in milliseconds are unchanged: token `ttl`, `ConnectionDetails`,
 `Auth.time_offset`, timestamps and the result of `ping()`.
 

From ba567a0937a191ef92adb33af3a29c7c0afafcda Mon Sep 17 00:00:00 2001
From: owenpearson <owen.pearson@ably.com>
Date: Wed, 28 Oct 2026 13:28:12 +0000
Subject: [PATCH 4/5] pubsub: validate the timing options when the client is
 created

Options stored whatever it was given for a timing option, and nothing
checked it until it was used. 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 a TypeError inside the timer task, where it was
only logged, so the retry it was meant to schedule never ran.

Options now validates the eight _seconds options once their defaults are
resolved, and the setters of the three HTTP ones validate too. Each must
be a finite, non-negative int or float; a bool, a string, a negative
number, NaN, an infinity or a timedelta raises InvalidArgumentException
with status 400 and code 40000, the code push.admin.publish already uses
for invalid arguments, which is also a ValueError. A timedelta's message
says to pass its total_seconds(). Zero is accepted, and no magnitude is
warned about. None still means the default, since validation runs after
the defaults are resolved.

The factory docstrings name the 40000 and the TypeError a renamed
option raises. UPDATING.md and test/uts/deviations.md describe the
accepted values. No UTS test passes an invalid value, so the counts do
not change.

This is a breaking change: a client given an invalid timing option now
fails to construct instead of misbehaving later.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 UPDATING.md                    | 33 ++++++++++++++++++++++
 ably/pubsub/server/__init__.py | 11 ++++++--
 ably/pubsub/server/sync.py     |  4 ++-
 ably/pubsub/types/options.py   | 40 ++++++++++++++++++++++++--
 test/unit/options_test.py      | 51 +++++++++++++++++++++++++++++++++-
 test/uts/deviations.md         |  5 +++-
 6 files changed, 136 insertions(+), 8 deletions(-)

diff --git a/UPDATING.md b/UPDATING.md
index d10f6923..0aa037be 100644
--- a/UPDATING.md
+++ b/UPDATING.md
@@ -879,6 +879,39 @@ All eight renames together:
 
 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())
+```
+
 ## 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:
diff --git a/ably/pubsub/server/__init__.py b/ably/pubsub/server/__init__.py
index 0eb7711b..a544c857 100644
--- a/ably/pubsub/server/__init__.py
+++ b/ably/pubsub/server/__init__.py
@@ -172,9 +172,14 @@ def create_http_client(**kwargs) -> PubSubHttpClient:
     ------
     AblyException
         With code 40106, if no means of authenticating is given, or if `key` is
-        combined with `key_name` or `key_secret`. It is also a ValueError.
+        combined with `key_name` or `key_secret`; with code 40000 if a `*_seconds`
+        timing option is not a finite, non-negative int or float. It is also a
+        ValueError.
     IncompatibleClientIdException
         If `client_id` conflicts with the client ID of `token_details`.
+    TypeError
+        If an option is passed under a name it does not have, including a timing
+        option's 3.x name, which the message names the replacement for.
     """
     with factory_construction():
         return _DefaultPubSubHttpClient(**kwargs)
@@ -248,7 +253,9 @@ def create_realtime_client(**kwargs) -> PubSubRealtimeClient:
     ------
     AblyException
         With code 40106, if no means of authenticating is given, or if `key` is
-        combined with `key_name` or `key_secret`. It is also a ValueError.
+        combined with `key_name` or `key_secret`; with code 40000 if a `*_seconds`
+        timing option is not a finite, non-negative int or float. It is also a
+        ValueError.
     """
     with factory_construction():
         return _DefaultPubSubRealtimeClient(**kwargs)
diff --git a/ably/pubsub/server/sync.py b/ably/pubsub/server/sync.py
index 75039039..f4a76223 100644
--- a/ably/pubsub/server/sync.py
+++ b/ably/pubsub/server/sync.py
@@ -55,7 +55,9 @@ def create_http_client(**kwargs) -> PubSubHttpClient:
     ------
     AblyException
         With code 40106, if no means of authenticating is given, or if `key` is
-        combined with `key_name` or `key_secret`. It is also a ValueError.
+        combined with `key_name` or `key_secret`; with code 40000 if a `*_seconds`
+        timing option is not a finite, non-negative int or float. It is also a
+        ValueError.
     """
     with factory_construction():
         return _DefaultPubSubHttpClientSync(**kwargs)
diff --git a/ably/pubsub/types/options.py b/ably/pubsub/types/options.py
index b5a8aee6..cacf205f 100644
--- a/ably/pubsub/types/options.py
+++ b/ably/pubsub/types/options.py
@@ -2,9 +2,11 @@
 import math
 import random
 from abc import ABC, abstractmethod
+from datetime import timedelta
 
 from ably.pubsub.transport.defaults import Defaults
 from ably.pubsub.types.authoptions import AuthOptions
+from ably.pubsub.util.exceptions import InvalidArgumentException
 
 log = logging.getLogger(__name__)
 
@@ -21,6 +23,21 @@ def seconds_to_ms(seconds):
     return int(ms) if ms == int(ms) else ms
 
 
+def validate_seconds(name, value):
+    """Returns `value` if it is a valid timing option, and raises if it is not.
+
+    A timing option is a finite, non-negative int or float of seconds. A bool is an int to
+    Python but not a duration, and a `timedelta` is rejected here rather than reaching a
+    timer that cannot schedule it.
+    """
+    if (isinstance(value, bool) or not isinstance(value, (int, float))
+            or not math.isfinite(value) or value < 0):
+        hint = '; pass a timedelta as its total_seconds()' if isinstance(value, timedelta) else ''
+        raise InvalidArgumentException(
+            f'{name} must be a finite, non-negative number of seconds, not {value!r}{hint}', 400, 40000)
+    return value
+
+
 # The timing options renamed in 4.0, by their 3.x name, with the 3.x unit and default
 _RENAMED_TIMING_OPTIONS = {
     'realtime_request_timeout': ('ms', 10000),
@@ -85,6 +102,9 @@ class Options(AuthOptions):
     - `suspended_retry_timeout_seconds`: TO3l2 suspendedRetryTimeout, default 30
     - `channel_retry_timeout_seconds`: TO3l7 channelRetryTimeout, default 15
     - `fallback_retry_timeout_seconds`: TO3l10 fallbackRetryTimeout, default 600
+
+    Each takes a finite, non-negative int or float, and anything else, a `bool` or a
+    `timedelta` among them, raises an `InvalidArgumentException` with code 40000.
     """
 
     def __init__(self, client_id=None, tls=True, port=0,
@@ -148,6 +168,20 @@ def __init__(self, client_id=None, tls=True, port=0,
         if endpoint is None:
             endpoint = Defaults.endpoint
 
+        # The timing options, given or defaulted, before anything schedules with them
+        timing_options = {
+            'realtime_request_timeout_seconds': realtime_request_timeout_seconds,
+            'disconnected_retry_timeout_seconds': disconnected_retry_timeout_seconds,
+            'suspended_retry_timeout_seconds': suspended_retry_timeout_seconds,
+            'channel_retry_timeout_seconds': channel_retry_timeout_seconds,
+            'fallback_retry_timeout_seconds': fallback_retry_timeout_seconds,
+            'http_open_timeout_seconds': http_open_timeout_seconds,
+            'http_request_timeout_seconds': http_request_timeout_seconds,
+            'http_max_retry_duration_seconds': http_max_retry_duration_seconds,
+        }
+        for name, value in timing_options.items():
+            validate_seconds(name, value)
+
         self.__client_id = client_id
         self.__tls = tls
         self.__port = port
@@ -242,7 +276,7 @@ def http_open_timeout_seconds(self):
 
     @http_open_timeout_seconds.setter
     def http_open_timeout_seconds(self, value):
-        self.__http_open_timeout_seconds = value
+        self.__http_open_timeout_seconds = validate_seconds('http_open_timeout_seconds', value)
 
     @property
     def http_request_timeout_seconds(self):
@@ -258,7 +292,7 @@ def _realtime_request_timeout_ms(self):
 
     @http_request_timeout_seconds.setter
     def http_request_timeout_seconds(self, value):
-        self.__http_request_timeout_seconds = value
+        self.__http_request_timeout_seconds = validate_seconds('http_request_timeout_seconds', value)
 
     @property
     def http_max_retry_count(self):
@@ -274,7 +308,7 @@ def http_max_retry_duration_seconds(self):
 
     @http_max_retry_duration_seconds.setter
     def http_max_retry_duration_seconds(self, value):
-        self.__http_max_retry_duration_seconds = value
+        self.__http_max_retry_duration_seconds = validate_seconds('http_max_retry_duration_seconds', value)
 
     @property
     def fallback_hosts(self):
diff --git a/test/unit/options_test.py b/test/unit/options_test.py
index 4a8d9d53..4ffa00ce 100644
--- a/test/unit/options_test.py
+++ b/test/unit/options_test.py
@@ -4,7 +4,7 @@
 
 from ably.pubsub.server import create_http_client, create_realtime_client
 from ably.pubsub.types.options import Options, seconds_to_ms
-from ably.pubsub.util.exceptions import AblyException
+from ably.pubsub.util.exceptions import AblyException, InvalidArgumentException
 
 
 # TO3k1-3: the deprecated environment, rest_host and realtime_host options are omitted,
@@ -258,3 +258,52 @@ def test_a_whole_number_of_milliseconds_is_an_int():
     assert type(seconds_to_ms(0.1)) is int
     assert type(seconds_to_ms(15)) is int
     assert type(seconds_to_ms(0.0015)) is float
+
+
+TIMING_OPTIONS = list(REALTIME_TIMING_DEFAULTS) + list(HTTP_TIMING_DEFAULTS)
+
+
+@pytest.mark.parametrize('option', TIMING_OPTIONS)
+@pytest.mark.parametrize('value', [0, 1, 0.0015, 2.5, 600])
+def test_timing_options_accept_finite_non_negative_ints_and_floats(option, value):
+    assert getattr(Options(**{option: value}), option) == value
+
+
+@pytest.mark.parametrize('option', TIMING_OPTIONS)
+@pytest.mark.parametrize('value', [True, False, '15', b'15', [15], -1, -0.001, float('nan'), float('inf'),
+                                   float('-inf'), timedelta(seconds=15)])
+def test_timing_options_reject_anything_else_with_a_40000(option, value):
+    with pytest.raises(InvalidArgumentException) as excinfo:
+        Options(**{option: value})
+    assert excinfo.value.code == 40000
+    assert excinfo.value.status_code == 400
+    assert isinstance(excinfo.value, ValueError)
+    assert option in excinfo.value.message
+
+
+def test_a_timedelta_is_rejected_with_a_hint():
+    # 3.x accepted a timedelta and then failed inside the timer task, so the retry never fired
+    with pytest.raises(InvalidArgumentException, match=r'total_seconds\(\)'):
+        Options(disconnected_retry_timeout_seconds=timedelta(seconds=15))
+
+
+def test_none_takes_the_default_rather_than_failing_validation():
+    opts = Options(**dict.fromkeys(TIMING_OPTIONS))
+    for option, default in {**REALTIME_TIMING_DEFAULTS, **HTTP_TIMING_DEFAULTS}.items():
+        assert getattr(opts, option) == default
+
+
+@pytest.mark.parametrize('option', list(HTTP_TIMING_DEFAULTS))
+def test_the_http_timing_setters_validate_too(option):
+    opts = Options()
+    setattr(opts, option, 0.5)
+    assert getattr(opts, option) == 0.5
+    with pytest.raises(InvalidArgumentException):
+        setattr(opts, option, -1)
+
+
+def test_the_factories_raise_the_validation_error():
+    with pytest.raises(InvalidArgumentException, match='http_request_timeout_seconds'):
+        create_http_client(key='appId.keyId:keySecret', http_request_timeout_seconds='10')
+    with pytest.raises(InvalidArgumentException, match='channel_retry_timeout_seconds'):
+        create_realtime_client(key='appId.keyId:keySecret', auto_connect=False, channel_retry_timeout_seconds=-15)
diff --git a/test/uts/deviations.md b/test/uts/deviations.md
index b1910c43..2b52dfaf 100644
--- a/test/uts/deviations.md
+++ b/test/uts/deviations.md
@@ -2012,7 +2012,10 @@ Intentional. TO3l counts every timing option in milliseconds; ably-python takes
 which is what a Python caller expects, and names each option with a `_seconds` suffix so
 the unit is on the page. A 3.x caller passing the old name gets a `TypeError` at
 construction that names the replacement and, for an option that took milliseconds, gives
-the value passed in seconds, rather than a value a thousand times too long. The wire values the
+the value passed in seconds, rather than a value a thousand times too long. TO3l types
+each option as an integer; ably-python takes a finite, non-negative `int` or `float`, so a
+fraction of a second can be given, and rejects anything else at construction with an
+`InvalidArgumentException`, 400/40000, as `push.admin.publish` does for its invalid arguments. The wire values the
 specification also counts in milliseconds are unchanged: token `ttl`, `ConnectionDetails`,
 `Auth.time_offset`, timestamps and the result of `ping()`.
 

From 585d28e130b224f537d0600df7226ad5fbec24fe Mon Sep 17 00:00:00 2001
From: owenpearson <owen.pearson@ably.com>
Date: Wed, 28 Oct 2026 14:11:51 +0000
Subject: [PATCH 5/5] pubsub: send a timedelta ttl to the millisecond

TK2a counts a token's ttl in milliseconds. A ttl given as a timedelta
was converted through total_seconds() and int(), which truncates, so
1,482 of the whole-millisecond values from 0 to 200,000 were sent one
millisecond short: timedelta(milliseconds=1001) was requested as 1000.
Both conversions did this, the one in create_token_request and the one
that sends the token params to an auth_url.

Both now go through ttl_ms, which divides by timedelta(milliseconds=1)
and so stays in integer arithmetic. A ttl given as a number is sent as
before. New unit tests check every millisecond up to 200 seconds and
both call sites. No UTS test changes state, so deviations.md does not
change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 UPDATING.md                 | 10 ++++++++++
 ably/pubsub/http/auth.py    | 17 +++++++++++++----
 test/unit/token_ttl_test.py | 35 +++++++++++++++++++++++++++++++++++
 3 files changed, 58 insertions(+), 4 deletions(-)
 create mode 100644 test/unit/token_ttl_test.py

diff --git a/UPDATING.md b/UPDATING.md
index 0aa037be..c089c4ef 100644
--- a/UPDATING.md
+++ b/UPDATING.md
@@ -912,6 +912,16 @@ 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:
diff --git a/ably/pubsub/http/auth.py b/ably/pubsub/http/auth.py
index 3f0399e7..372cfa2d 100644
--- a/ably/pubsub/http/auth.py
+++ b/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
diff --git a/test/unit/token_ttl_test.py b/test/unit/token_ttl_test.py
new file mode 100644
index 00000000..8909546b
--- /dev/null
+++ b/test/unit/token_ttl_test.py
@@ -0,0 +1,35 @@
+from datetime import timedelta
+
+import pytest
+
+from ably.pubsub.http.auth import Auth, ttl_ms
+from ably.pubsub.server import create_http_client
+
+
+# TK2a: a ttl given as a timedelta is sent as its exact count of milliseconds
+@pytest.mark.parametrize('ms', [1, 999, 1001, 1003, 59_999, 3_600_000])
+def test_ttl_ms_converts_a_timedelta_exactly(ms):
+    assert ttl_ms(timedelta(milliseconds=ms)) == ms
+
+
+def test_ttl_ms_keeps_milliseconds_given_as_a_number():
+    assert ttl_ms(3_600_000) == 3_600_000
+    assert ttl_ms('1001') == 1001
+
+
+def test_ttl_ms_is_exact_for_every_millisecond_up_to_200_seconds():
+    assert [ms for ms in range(200_001) if ttl_ms(timedelta(milliseconds=ms)) != ms] == []
+
+
+async def test_create_token_request_sends_a_timedelta_ttl_exactly():
+    client = create_http_client(key='app.key:secret')
+    try:
+        token_request = await client.auth.create_token_request({'ttl': timedelta(milliseconds=1001)})
+        assert token_request.ttl == 1001
+    finally:
+        await client.close()
+
+
+def test_auth_url_params_send_a_timedelta_ttl_exactly():
+    params = Auth._auth_url_token_params({'ttl': timedelta(milliseconds=1001)})
+    assert params['ttl'] == 1001