feat: Checkpoint Requests

[stevensJourney]

Overview

This is the Swift SDK implementation of the Request Checkpoint proposal: https://github.com/orgs/powersync-ja/discussions/324

Related to:

• feat: Checkpoint Requests powersync-service#696
• feat: checkpoint requests powersync-sqlite-core#198

This adds a new requestCheckpoint method which returns a CheckpointRequest. The CheckpointRequest instance exposes a waitForSync method which resolves once the requested checkpoint has been synced and applied locally.

func refreshFromRemote(timeout: TimeInterval = 30) async throws {
    let checkpoint = try await powerSync.requestCheckpoint()
    try await checkpoint.waitForSync(timeout: timeout)
}

The SDK is updated to cater for the Rust core and PowerSync service changes. ConnectOptions now has a checkpointMode, and checkpoint requests are enabled by connecting with checkpointMode: .requests(). In request mode the sync client posts checkpoint requests to the service, tracks the latest applied checkpoint request ID from core sync status, retries unapplied requests with a delay, and cancels pending waits when the sync client disconnects or closes.

For backends that process uploads asynchronously, this also adds CustomCheckpointRequestConnector. A connector can implement this to handle checkpoint requests itself and return the effective checkpoint request ID accepted by the backend.

These APIs are documented as alpha and may change in future releases.

Demo

The PowerSyncExample has been updated to include a pull-to-refresh action which shows a loading spinner until a checkpoint request has been resolved.

In order to showcase the functionality a bit better, a new Admin page has been added to the demo which conveys the SyncStatus. In the demo below, we go offline, create 50k todos which will be synced, then connect and await a checkpoint request. We can see the download progress reach 100%, but the data is only available after the checkpoint has been applied locally. The checkpoint request correctly keeps the operation in a loading state until the data is actually available.

request-checkpoint.mp4

There is also a small SwiftPM command-line demo under Demos/CustomCheckpointDemo which shows a custom checkpoint request connector against the Node.js todo backend.

Testing

I added coverage for creating and waiting on checkpoint requests, timeout/error behavior, unsupported service responses, reconnects, seeded/reseeded checkpoint request state, retry timing, disconnect cancellation, custom checkpoint request connectors, upload integration, and the mock HTTP client hook used by these tests.

---

AI disclosure: This work was assisted by Codex. I manually guided and reviewed the changes.