feat(ffi): expose Client.sync()

[tumata]

Expose sync v2 API through FFI via Client.sync() and Client.sync_once() #6348

Mobile clients can now sync using the traditional /sync v2 endpoint through the FFI bindings, without requiring Sliding Sync (MSC4186) support on the homeserver.

This PR introduces a new API (non-breaking change).

Implementation notes

I chose to expose only the list of room IDs (invited, joined, left, knocked) in the SyncResponse, rather than forwarding the full per-room event payloads. This keeps the FFI surface simple. Clients that need room details can query them through the existing Room APIs after being notified of changes via the listener.

Two entry points are provided:

• Client.sync(settings, listener) starts a continuous sync loop, returning a TaskHandle for cancellation. The SyncListener callback fires after each successful sync response.
• Client.sync_once(settings) performs a single sync call, useful for initial sync or one-off use cases.

SyncSettings exposes timeout_ms and full_state

Build

I verified building the XCFramework

cargo xtask swift build-framework --ios-deployment-target 15.0

I also verified integrating this build into our test iOS application and used the new API, with success.

Use of AI

I used AI as a reference while making this change. I reviewed and validated the implementation myself, and take full accountability for it.

Closes #6348

• I've documented the public API Changes in the appropriate CHANGELOG.md files.
• This PR was made with the help of AI.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.86%. Comparing base (02c41e2) to head (6356ef2).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6359      +/-   ##
==========================================
- Coverage   89.87%   89.86%   -0.01%     
==========================================
  Files         376      376              
  Lines      103093   103093              
  Branches   103093   103093              
==========================================
- Hits        92657    92649       -8     
- Misses       6863     6872       +9     
+ Partials     3573     3572       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[codspeed]

Merging this PR will improve performance by 49.34%

⚡ 1 improved benchmark
✅ 49 untouched benchmarks

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
⚡	Simulation	Restore session [memory store]	167.3 ms	112 ms	+49.34%

---

_{Comparing tumata:feat/6348-sync (6356ef2) with main (02c41e2)}

[bnjbvr]

Code looks fine to me. I'm a bit curious about how it would be used, as returning the room IDs in the sync responses seem very minimal.

As an opportunity to not flood the client.rs file which is already a bit big, can you move this code to a new sync_v2.rs sub-module?

Also, I think it'd be nice to make it clear that this is the previous sync mechanism, so can you include a v2 suffix to all the methods and types, please? (e.g. SyncSettingsV2, sync_v2(), sync_once_v2(), etc.)

Thanks!

[bnjbvr]

PR number is wrong here

[tumata]

Fixed: 028080c

[bnjbvr]

Curious, but are these annotations any useful? I'd imagine that uniffi uses the Default::default implementation for each type by default, which will set to None/false for these two types?

[tumata]

I wanted to provided sensible defaults on the Swift side. This is meant to avoid having to provide a default value when constructing the Swift structure. Otherwise the implementor has to provide the arguments, such as nil in this particular line.

// Without the annotations:
SyncSettings(timeoutMs: nil, fullState: false)  // must provide all args

// With #[uniffi(default = ...)]:
SyncSettings() // can provide no args
SyncSettings(timeoutMs: 0) // ... some args only
SyncSettings(fullState: false)
SyncSettings(timeoutMs: 0, fullState: false) // or all args

[bnjbvr]

Sweet, thanks for explaining!

[bnjbvr]

Curious about your use case; is it sufficient to only get room IDs here? How do you get new events/timelines for these rooms, out of curiosity?

[tumata]

Here's the flow I tested and that suits our needs:

1. Call sync and register a SyncListener
2. When SyncListener.on_update is called:
   • For all invited rooms: join via client.joinRoomById, then subscribe to the room timeline
   • For all joined rooms: subscribe to the room timeline

From there, the TimelineListener callback gives me the events, state events, and such.

[tumata]

@bnjbvr
Note that I am relying on what does not seems like a production-ready API to get the data I need from the event (EventTimelineItem)

event.lazyProvider.debugInfo().originalJson

Unfortunately I could not find another API to get the raw event data. Any suggestions? I was going to create another issue to tackle this specific request.

[bnjbvr]

Interesting. Out of curiosity, why do you need the raw event data? That makes sense to me for custom events, even though we could probably provide some new variant of TimelineItemContent for those. But for other events, you should have everything you need as part of the EventTimelineItem::content, likely?

[tumata]

Yes, we need it exactly to handle custom events.

I created a PR and provided explanation there: #6387

[tumata]

@bnjbvr I actually started with "v2" in the names, but then reverted back to sync because:

1. sync is also what's used at the rust layer
2. I was thinking that "v2" might make it appear like it was newer/preferred over the Sliding Sync option, which it isn't.

Sounds like you're fine with it though, so I will proceed with your suggestion 👍

[tumata]

The PR is ready for another review. I addressed the requested changes in 6356ef2. Thanks

[bnjbvr]

Thank you! Feel free to ask extra questions in our dev room :-)