UTS: migrate rest/unit mock HTTP to the handler idiom and fix /time response shape

[owenpearson]

Fixes two coupled UTS test-spec defects in uts/rest/unit/, reported as #523 and #524.

#523 — migrate the queue-based mock idiom to the handler idiom

Replaces every use of the undefined/banned queue API (queue_response, queue_responses, queue_response_for_host, queue_response_for_url, queue_timeout, queue_delayed_response, and mock_http.captured_requests) with the onRequest/onConnectionAttempt handler idiom plus a LOCAL captured_requests array (with local request_count/captured_hosts where needed), matching the contract in helpers/mock_http.md and the already-migrated blocks in fallback.md. In the same pass:

• Error-body fixtures repaired to the full { "error": { "message", "code", "statusCode" } } shape, including the CloudFront fixture whose error was a bare string.
• The two pinned-fallback-host tests (RSC15f/successful-fallback-cached-0, RSC15f/cached-fallback-expires-1) now dispatch on req.url.host and bind assertions to the observed fallback host rather than a hard-coded name, resolving the 1/5-flaky pin against RSC15a's random ordering.
• Mock-contract cross-references retargeted from rest_client.md to helpers/mock_http.md at fallback.md:10 and request.md:10,16; dropped the fallback.md:12-15 block requesting capabilities the contract deliberately omits.

#524 — fix the /time response shape

/time returns a single-element ARRAY [server_time_ms], not {"time": N}. Corrected at every site, contract file first (helpers/mock_http.md, then writing-test-specs.md, then the specs), including rest_client.md's msgpack site which becomes msgpack_encode([1234567890000]). Migrated handlers from #523 emit the array shape so the two fixes converge; no object-shaped /time fixture remains anywhere under uts/.

Files changed

• uts/rest/unit/fallback.md — full migration + error-body repair + host-pin fix + array shape (+707/-… lines)
• uts/rest/unit/request.md — RSC19d/HP + RSC19b/c/e/f migration, array shape, non-array redirect
• uts/rest/unit/rest_client.md — 12 queue sites + msgpack /time + array shape
• uts/rest/unit/request_endpoint.md — local captured_requests + array shape
• uts/rest/unit/helpers/mock_http.md — 4 /time sites
• uts/rest/unit/auth/authorize.md — 1 /time site
• uts/docs/writing-test-specs.md — 3 /time sites in the authoring guide

Judgment calls

• RSC15l dedup (rest/unit/fallback.md is half-migrated: it uses a queue_response mock API that helpers/mock_http.md does not define and writing-test-specs.md bans, which makes four of its tests unsatisfiable #523 (a)): The unmigrated RSC15l/qualifying-errors-trigger-fallback-0 block covered HTTP 500–504 (retry), 400/401/404 (no retry), and timeout. Every one of those scenarios is fully covered by the migrated blocks at the former :215-402 (connection-refused-fallback-0, dns-error-fallback-1, connection-timeout-fallback-2, request-timeout-fallback-3, http-5xx-triggers-fallback-4, http-4xx-no-fallback-5), under distinct Test IDs. Confirmed fully redundant, so the duplicate block was deleted rather than migrated. This removes the qualifying-errors-trigger-fallback-0 Test ID (its scenarios survive under the other IDs).
• request.md:788 redirect (/time is mocked as {"time": N} in 48 places across six rest/unit specs; the endpoint returns [server_time_ms], so a typed SDK cannot derive those tests as written #524 (4)): The RSC19d/non-array-response-handling-7 test exercised a non-array response but fetched it from /time, which can only return an array. Repointed it at a channel-status path (/channels/test) that genuinely returns a JSON object, and replaced the hedged ASSERT items.length == 1 OR items["time"] == … # Implementation may vary with a single definite assertion (items.length == 1 and items[0]["channelId"] == "test").
• request.md RSC19d 500 rows (rest/unit/fallback.md is half-migrated: it uses a queue_response mock API that helpers/mock_http.md does not define and writing-test-specs.md bans, which makes four of its tests unsatisfiable #523 (b)): Both status-code tables include a 500 row; 500 is a qualifying error that triggers fallback retries. The handler now answers every attempt with the same status so the final response carries the expected code, and the per-iteration mock is constructed inside the loop (the previous reset() form no longer applies).
• request.md:916 (RSC19e/fallback-on-server-error-3): Retained its single-entry fallbackHosts: ["fallback.ably-realtime.com"] and host assertion — per rest/unit/fallback.md is half-migrated: it uses a queue_response mock API that helpers/mock_http.md does not define and writing-test-specs.md bans, which makes four of its tests unsatisfiable #523 this is a legitimate configured fallback, not an instance of the pinning defect.

Merge order

This is PR 1 of 7 and should merge FIRST. It conflicts with the spec-point-references PR on auth/authorize.md and with the housekeeping PR on fallback.md/rest_client.md.

No features.md change is required or made.

Closes #523
Closes #524

🤖 Generated with Claude Code