Push activation: spec enhancements (token variants, updateToken, unified PATCH sync) + full UTS test suite

[paddybyers]

Two related workstreams in three commits, developed and validated together: a set of push-spec enhancements, and the complete portable (UTS) test suite for the push activation half of the RSH spec — previously untested (the completion-matrix rows for RSH2, RSH3, RSH4–5, RSH6, RSH8 and the push types were blank).

1. Spec enhancements (specifications/features.md)

Push#updateToken (RSH2f–RSH2f3, new)

Specifies the API through which the application delivers a rotated or additional platform token — established by ably-js in ably/ably-js#2267 but previously unspecced. Covers the validation guard and activation-required guard (both 40000, no side effects), and the apply-to-recipient + persist + GotPushDeviceDetails (RSH8g) flow. This is the delivery mechanism for FCM onTokenRefresh, APNs re-registration, and ActivityKit token updates.

APNs token slots on the recipient (PCP3a, new)

iOS has multiple flavours of device token — default, location-push, and Live Activity push-to-start. ably-cocoa has already shipped support (ARTAPNSDeviceTokenTypes, recipient carrying an apnsDeviceTokens map) with no spec backing — and the nested map doesn't fit PCP3's "map of string key/value pairs" wording. PCP3a codifies the shipped wire shape: apnsDeviceTokens (slot name → token) alongside/instead of the legacy deviceToken (≡ apnsDeviceTokens.default); well-known slots default/location/pushToStart, with slot names open/extensible (a token "type" is a registration slot/delivery route, not a capability set — the default token serves alert + background pushes selected per-request via apns-push-type, while other routes are forcibly distinct tokens; an open namespace absorbs future flavours, e.g. per-attributes-type push-to-start tokens whose granularity Apple doesn't document, without spec surgery).

Device-side variant lifecycle (RSH8l–RSH8l4, new)

Variants are recipient-related attributes for RSH8a persistence; registering/updating any variant is an RSH8g change whose sync carries the complete recipient (RSH8l2); RSH8i verification applies per variant; RSH8l4 (non-normative) records the deliberate exclusion of per-activity Live Activity update tokens — their lifetime is an activity instance, and updates flow over APNs broadcast channels (RSH1e), so only the device-scoped push-to-start token needs registering.

PushDeviceToken type (PDT1–PDT4, new)

{transportType: "fcm"|"apns"|"web", token, apnsTokenType?} + IDL for it and updateToken.

Unified PATCH registration sync (RSH3a2a3, RSH3d3b, RSH8f amended)

With RSH8l2 requiring every sync to carry the complete recipient, the payload distinction between the RSH3a2a3 re-activation PUT and the RSH3d3b changed-fields PATCH mostly disappears. RSH3d3b becomes the canonical sync (complete recipient + other changed attributes, e.g. a late-set clientId per RSH8d — resolving a pre-existing ambiguity in the RSH8e flow); RSH3a2a3 performs the same sync, with the full-body PUT retained as a permitted legacy equivalent — ably-java/ably-cocoa remain conformant unchanged, and ably-js (which PATCHes) becomes conformant. RSH8f generalised to accept a clientId from sync responses (verified: the PATCH response returns the full DeviceDetails).

RSH6a clarification

The X-Ably-DeviceToken value is the raw token, not base64-encoded, with a non-normative note that the historical base64 encoding (ably-java, ably-cocoa) is tolerated by the service but not conformant. Verified empirically against the sandbox: raw and base64 both accepted; garbage rejected (400/40005).

2. UTS test suite (10 spec files, 75 tests)

• Helper: rest/unit/helpers/mock_push_platform.md — the portable push platform primitives (PushKeyValueStoragegetItem/setItem/removeItem + requestToken, matching the ably-js React Native seam from [AIT-850] feat: react native push plugin ably-js#2262), the standard ably.push.* storage keys and value encodings, install_push_platform() (consistent with the transport-mock conventions; injection mechanism SDK-specific by design), and the MockPushStorage mock (dump/seed/fault flags/onOperation with local-array capture).
• Unit (7 files, 62 tests): the full RSH3 state-machine transition matrix incl. both registrar branches and RSH3d2c1 classification (push_activation_state_machine.md, 23), LocalDevice attributes + clientId lifecycle (local_device.md, 6), persistence/rehydration incl. RSH8a1 corruption discard (push_activation_persistence.md, 6), RSH4/RSH5 queue semantics incl. the spec's own worked example (push_activation_event_queue.md, 3), updateToken incl. the RSH8l2 variant tests (push_update_token.md, 12), device auth incl. the RSH1b/RSH1c own-device clauses (push_device_auth.md, 5), and the PCD/PCP/PCS types (types/push_types.md, 7). Black-box style throughout: public API + held mock requests; state observed via requests and settled persisted state.
• Integration (7 tests): real-sandbox round-trips using storage pre-seeded with an ablyChannel recipient (rides RSH3a2c, so no FCM/APNs credentials needed), including end-to-end delivery of an admin publish and a device-auth server-acceptance check made load-bearing via a push-subscribe-capability key.
• Proxy (6 tests): fault injection on the registration endpoints — the RSH3d2c1 classifications proven client-side by a direct admin client observing the registration survive an intercepted DELETE, rollback/retry flows, and the RSH4 queue against a delayed registration.

Validation

Every test is derived and validated in ably-js (full UTS unit suite: 1428 passing / 73 pending; genuine non-conformances recorded in its test/uts/deviations.md — 13 push entries) and ably-dart (fully conformant implementation of the extended spec, including the token variants: unit 1274 passing, integration + proxy 10 passing + 3 pending-deploy skips). Validation surfaced and fed back: one spec-test bug (5xx fault injection tripping RSC15 fallback retries — now a non-retriable 4xx), two ably-dart implementation bugs (fixed), several ably-js conformance gaps (recorded as deviations, fix PRs planned), and one server-side bug — the registration-update PATCH rejected any device whose stored recipient was ablyChannel — fixed in ably/realtime#8591; the affected derived tests are skipped pending its sandbox deploy (the specs carry "known server issue" notes).

Review points

1. RSH8l4 cross-references RSH1e (APNs broadcast channels), which currently exists only on the AIT-794/live-activity branch — this PR should land after it, or the cross-ref be softened.
2. PCP3a's open slot namespace constrains servers to tolerate unknown slots — flagging for explicit agreement.
3. Remaining small gaps to close before undrafting (or as follow-ups): api-docstrings.md entries for updateToken/PushDeviceToken, and dedicated PDT type tests in push_types.md.

🤖 Generated with Claude Code