Add REST Objects API specification proposal#475
Draft
paddybyers wants to merge 62 commits into
Draft
Conversation
Add ably-common as a git submodule at submodules/ably-common, pinned to 6ff9a1a. This provides shared test fixtures and protocol definitions used by the UTS (Universal Test Suite) specs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add portable, language-independent test specifications covering the REST client: authentication (RSA), channels (RSL/RSP), encoding, batch publish, pagination, stats, time, fallback hosts, push admin, and type definitions. Includes a mock HTTP helper spec and a README documenting the UTS framework. These specs serve as the source of truth for expected SDK behaviour, independent of any specific programming language implementation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add test specs covering connection failures (RTN14/RTN15), open failures, error reason handling, fallback hosts (RSC15), heartbeats, update events, whenState helper, and a connection lifecycle integration test.
Ensure mock WebSocket connections are properly closed in connection failure and open-failure test specs to prevent resource leaks in tests.
…kill Separate the mock WebSocket specification into its own file for reuse across test specs, and add a skill document for writing test specs.
Replace TRY/CATCH error characterisation patterns with declarative EXPECT_THROW assertions for clearer, more portable test specifications.
…ence Add UNIQUE_CHANNEL_NAME() calls and randomised channel names throughout the test specs. Also adds new test specs for channel attach (RTL4), detach (RTL6), channel options, state events, and channels collection.
Substantially rework the heartbeat test specs for better coverage of RTN23 (heartbeat monitoring) and extend the mock WebSocket helper with additional transport simulation capabilities. Update the write-test-spec skill with improved patterns.
Correct the test approach for RTN15a immediate reconnection behaviour and update the write-test-spec skill with refined patterns.
Correct small errors in channel_attach and channel_state_events specs.
Add test specs for channel connection state handling, channel error reporting, server-initiated detach, channel properties (RTL15/RTL16), connection ID/key (RTN8/RTN9), and connection ping (RTN13). Also adds a completion-status tracker for spec point coverage.
Add comprehensive test specs covering channel message subscription, filtering, listener management, and unsubscribe behaviour.
Add test specs covering channel message publishing, including message encoding, connection state requirements, and error handling.
… specs Add realtime test spec stubs for stats (RSC6a) and time (RSC16) that reference the existing REST test specs, since behaviour is identical.
Add test specs covering the Realtime.request() method for making arbitrary REST requests through the realtime client.
Add test coverage for message queueing during connection state changes, publish behaviour across different connection states, and message delivery ordering guarantees.
…istory) Add specs covering connection state recovery options and realtime channel history retrieval.
Add specs covering log level configuration, log handler callbacks, and default logging behaviour for REST and Realtime clients.
Complete the authentication test spec coverage with specs for token reauth, auth error handling, and edge cases.
Add comprehensive test specs covering presence enter, leave, update, subscribe, presence map synchronisation, and presence history.
Update test specs to use encode_uri_component() for channel names in URL paths, ensuring correct handling of special characters. Add a README documenting the convention and update the write-test-spec skill.
Refine presence test specs based on implementation experience, add integration test specs for presence operations against a live server, and fix various issues in the presence specs.
Extend the skill documentation to note the importance of keeping UTS portable test specs synchronised with language-specific tests.
Add specs covering the batch presence API for retrieving presence state across multiple channels in a single request.
Add specs covering the revokeTokens API for invalidating issued authentication tokens.
Add specs covering the handling of channel UPDATE protocol messages, including resumed and non-resumed flag behaviour.
Add specs covering delta compression for channel messages using the VCDIFF format, including encoding, decoding, and error recovery.
…connect Add test specs for channel attributes (RTL15), channel whenState helper, realtime client timeout configuration, auto-connect behaviour (RTC1b), and REST channel attributes.
Add specs covering the mutable messages feature including message update and delete operations, action fields, and event handling.
Add specs covering push notification administration including device registration management and push channel subscription management.
New specs: - RTB1: backoff and jitter for connection retries - RSA4a: token expiry with non-renewable tokens - RSA4c/d/f: auth callback error handling - RTN16: connection recovery (recovery key, msgSerial, channelSerials) - RTN20: network change events (browser-only) - RSF1/RTF1: forwards compatibility (unknown fields/actions) - RSH7: push channel subscriptions (unit + integration) Extended specs: - RTL22/MFI: message filter subscriptions (channel_subscribe) - RTN7e: error reason on publish failure (channel_publish) - CHD2/CHM2: all ChannelMetrics fields (rest_channel_attributes) - RTN16d/RTN16l: proxy-based recovery tests (connection_resume) Updates completion-status.md and README spec counts. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…uccess Tests that a request completing successfully against a cached fallback host after fallbackRetryTimeout has expired does not re-pin that host. Uses the existing onRequest handler with a held PendingRequest pattern rather than introducing a new mock primitive. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…rame Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The Go test proxy has moved to https://github.com/ably/uts-proxy. Updated references in README, writing guide, and proxy infrastructure spec to point to the external repo. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Per specification#466, RSA4c1 (setting errorReason with code 80019) should only apply to RSA4c2 (CONNECTING case), not RSA4c3 (CONNECTED case). When auth fails while CONNECTED, the connection is still healthy — the existing token is valid. Setting errorReason with no state change is misleading. The failure will naturally surface when the token expires. Changes: - RSA4c3 test now asserts errorReason is null and no events are emitted - RSA4c1 references replaced with RSA4c2 throughout (error definition absorbed into RSA4c2) - Notes updated to explain the rationale Ref: #466 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
connectionId is a top-level ProtocolMessage field, not inside connectionDetails. RTN24's "connectionDetails must override stored details" does not apply to it — connection.id never changes for an in-progress connection. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
TM3 is about fromEncoded/fromEncodedArray, not generic fromJson. TM4 is about Message constructors, not toJson serialization. TM5 is about MessageAction enum, not message equality. Removed toJson tests (no spec point requires a toJson method) and replaced TM4 section with constructor tests per spec. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
With X-Ably-Version >= 3, the server returns a BatchResult envelope
({successCount, failureCount, results}) with HTTP 200 for all batch
responses including mixed success/failure. The UTS specs were
incorrectly mocking the legacy format (plain arrays + batchResponse
with HTTP 400) which is only used without a version header.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…5l4) Proxy-based tests that exercise fallback behaviour through the real HTTP client: request timeout triggers fallback (RSC15l2), and CloudFront Server header should trigger fallback (RSC15l4). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds tests for unreachable endpoint, connection drop, 5xx with/without error body, 4xx not retried, and RSL1k4 idempotent publish (pending proxy enhancement). Extracts token auth helper used across all tests. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Format: <category>/<spec-point>/<descriptive-name>-<n>
Categories: rest/unit, rest/integration, rest/proxy,
realtime/unit, realtime/integration, realtime/proxy
Also updates writing-test-specs.md and writing-derived-tests.md
with the Test ID convention and placement rules.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The proxy already supports this action — remove the "proxy limitation" section and update the test pseudocode to use http_replace_response. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Integration tests: endpoint: "sandbox" → "nonprod:sandbox" - Unit tests: endpoint: "sandbox" → "test" (clearly not a real environment) - Update host assertions in unit tests to match (test.realtime.ably.net etc.) - Leave environment: "sandbox" tests unchanged (testing deprecated option) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace deprecated sandbox-rest.ably.io with sandbox.realtime.ably-nonprod.net in all UTS test spec provisioning blocks and documentation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Establish a convention for running data-path integration tests with both JSON and msgpack protocols. Each annotated spec gets a Protocol Variants section and uses PROTOCOL == "msgpack" instead of hardcoded useBinaryProtocol: false. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Portable test spec for verifying decode and round-trip of ably-common msgpack_test_fixtures.json across SDK implementations. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Complete portable test suite covering the LiveObjects path-based API: 21 files across unit tests (pure + mock WebSocket), integration tests (sandbox), and proxy integration tests. Covers PathObject, Instance, BatchContext, LiveCounter/LiveMap CRDTs, ObjectsPool sync state machine, value types, subscriptions, and GC. Includes table-driven validation tests, bytes/binary data coverage, and REST fixture provisioning. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove client-side allocated_port/port_base patterns from all proxy test specs and helper docs. Port is now auto-assigned by the proxy when omitted from create_proxy_session(). Matches uts-proxy v0.2.0. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Proposes spec additions for the LiveObjects REST API (RestObject#get, publish, generateObjectId) with types, behavioral assertions derived from the ably-js test suite, and open design questions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
paddybyers
changed the title
paddybyers
requested review from
VeskeR,
lawrence-forooghian,
mschristensen,
ttypic and
zknill
paddybyers
force-pushed
the
uts-liveobjects
branch
from
f8f1b71 to
08789a6
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR contains an outline proposal for what the specification looks like for the LiveObjects REST API. Comments welcome.