[AIT-207] Partial object sync

[lawrence-forooghian]

Note: This PR is based on top of #114; please review that one first.

Implements the following spec commits, which allow the server to split a large object over multiple OBJECT_SYNC messages.

• ably/specification@1f22417
• ably/specification@9f4d7de
• ably/specification@963ec30

See commit message for more details.

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • Enhanced robustness of object synchronization sequence handling with improved validation of object state transitions.

• Tests

  • Expanded test coverage for OBJECT_SYNC sequences with support for multi-message synchronization, partial object updates, and unknown object type handling.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: ff27ae6d-901b-4816-a578-2b9da5977049

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

A refactoring replaces array-based sync object storage with a dedicated SyncObjectsPool type that manages partial sync message merging and accumulation. SyncObjectsPool validates, merges map entries, and handles counter states during OBJECT_SYNC sequences.

Changes

Cohort / File(s)	Summary
Core Sync Pool Implementation Sources/AblyLiveObjects/Internal/SyncObjectsPool.swift	New internal struct implementing Sequence protocol to accumulate and merge partial object sync data (RTO5f), with logic for map merging, tombstone handling, counter validation, and iterator support.
Sync Pool Integration Sources/AblyLiveObjects/Internal/InternalDefaultRealtimeObjects.swift, Sources/AblyLiveObjects/Internal/ObjectsPool.swift	Updated SyncSequence to use SyncObjectsPool instead of array. Modified nosync_applySyncObjectsPool to accept SyncObjectsPool and changed error handling from warning+nil to preconditionFailure for invalid states.
Removed Legacy Type Sources/AblyLiveObjects/Internal/SyncObjectsPoolEntry.swift	Deleted internal struct SyncObjectsPoolEntry, replaced by SyncObjectsPool.Entry nested type.
Test Helpers & Infrastructure Tests/AblyLiveObjectsTests/Helpers/TestFactories.swift, Tests/AblyLiveObjectsTests/ObjectsPoolTests.swift	Extended inboundObjectMessage factory with optional serialTimestamp parameter. Added testsOnly_fromStates helper to build SyncObjectsPool from state pairs for tests.
Test Coverage Tests/AblyLiveObjectsTests/SyncObjectsPoolTests.swift, Tests/AblyLiveObjectsTests/JS Integration Tests/ObjectsIntegrationTests.swift	New comprehensive unit tests for SyncObjectsPool accumulation, merging, and iteration. Added integration tests validating multi-message OBJECT_SYNC sequences, partial map merges, and unknown object type handling.
Test Specifications Tests/AblyLiveObjectsTests/InternalDefaultRealtimeObjectsTests.swift	Updated spec annotation from RTO5b to RTO5f in HandleObjectSyncProtocolMessageTests.

Sequence Diagram

sequenceDiagram
    participant Channel
    participant InternalDefaultRealtimeObjects
    participant SyncObjectsPool
    participant ObjectsPool
    
    Channel->>InternalDefaultRealtimeObjects: Receive OBJECT_SYNC message
    InternalDefaultRealtimeObjects->>SyncObjectsPool: accumulate(objectMessage)
    activate SyncObjectsPool
    Note over SyncObjectsPool: Validate state & object type<br/>Merge map entries / handle tombstone<br/>Store or update entry
    SyncObjectsPool-->>InternalDefaultRealtimeObjects: Pool updated
    deactivate SyncObjectsPool
    
    Channel->>InternalDefaultRealtimeObjects: Receive next OBJECT_SYNC (or end)
    InternalDefaultRealtimeObjects->>SyncObjectsPool: accumulate(objectMessage)
    activate SyncObjectsPool
    Note over SyncObjectsPool: Continue merging partial data
    SyncObjectsPool-->>InternalDefaultRealtimeObjects: Pool updated
    deactivate SyncObjectsPool
    
    InternalDefaultRealtimeObjects->>ObjectsPool: nosync_applySyncObjectsPool(pool)
    activate ObjectsPool
    loop For each entry in pool
        ObjectsPool->>ObjectsPool: Create/update object with merged state
    end
    ObjectsPool-->>InternalDefaultRealtimeObjects: Objects applied
    deactivate ObjectsPool

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Poem

🐰 Pools of sync data merge and flow,
Partial messages now can grow,
Maps accumulate without a fuss,
Tombstones clear and entries gush,
Ably's objects dance on cue! 🌊

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 84.21% which is sufficient. The required threshold is 80.00%.
Title check	✅ Passed	The PR title "AIT-207 Partial object sync" directly corresponds to the main objective, which is implementing partial object sync support (RTO5f) that allows servers to split large objects across multiple OBJECT_SYNC messages.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch AIT-207-partial-object-sync

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[lawrence-forooghian]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[ttypic]

Can we split the method into existing / non-existing object branches? It's getting pretty big

[lawrence-forooghian]

This method hasn't really been made larger by this PR but sure, seems like a good idea anyway — added 650f876

[ttypic]

LGTM