Module engine 

This module is used by crates which need to implement a “sync engine”. At a high-level, a “sync engine” is code which knows how to take records from a sync server, apply and reconcile them with the local data, then provide records which should be uploaded to the server.

Note that the “sync engine” does not itself talk to the server, nor does it manage the state of the remote server, nor does it do any of the encryption/decryption - that is the responsbility of the “sync client”, as implemented in the [client] module (or in some cases, implemented externally)

There are currently 2 types of engine:

• Code which implements the crate::engine::sync_engine::SyncEngine trait. These are the “original” Rust engines, designed to be used with the crate::client(sync client)
• Code which implements the crate::engine::bridged_engine::BridgedEngine trait. These engines are a “bridge” between the Desktop JS Sync world and this rust code.

While these engines end up doing the same thing, the difference is due to implementation differences between the Desktop Sync client and the Rust client.

We intend merging these engines - the first step will be to merge the types and payload management used by these traits, then to combine the requirements into a single trait that captures both use-cases.

Steps so far, and what’s left:

• bridged_engine::BridgedEngineAdaptor lets a crate implement only SyncEngine (plus a tiny adaptor) and get a bridged_engine::BridgedEngine for free.
• bridged_engine::BridgedEngineWrapper + the uniffi_bridged_engine! macro remove the per-crate UniFFI facade boilerplate (the JSON<->BSO marshalling and method delegation).
• Still to do (#2841): remove BridgedEngine/BridgedEngineAdaptor/ApplyResults entirely and have Desktop consume SyncEngine directly. This is blocked on a coordinated mozilla-central change: Desktop must move off explicit timestamp handling (last_sync/set_last_sync) to the get_collection_request model, and the per-crate UDL interface *BridgedEngine blocks (the Desktop-visible contract consumed via mozIBridgedSyncEngine) must be updated in lockstep.

Structs

ApplyResults

BridgedEngineWrapper

Wraps a Box<dyn BridgedEngine> and centralizes the work every consuming crate’s UniFFI-facing bridged engine needs to do: the JSON String <-> BSO marshalling that crosses the FFI boundary, and 1:1 delegation to the wrapped engine. Rather than each crate hand-writing this (it was ~100 identical lines per crate), they expose a thin newtype around this via the [uniffi_bridged_engine!] macro.

CollSyncIds

CollectionRequest

Enums

EngineSyncAssociation

Defines how an engine is associated with a particular set of records on a sync storage server. It’s either disconnected, or believes it is connected with a specific set of GUIDs. If the server and the engine don’t agree on the exact GUIDs, the engine will assume something radical happened so it can’t believe anything it thinks it knows about the state of the server (ie, it will “reset” then do a full reconcile)

RequestOrder

SyncEngineId

The concrete SyncEngine implementations

Traits

BridgedEngine

A BridgedEngine acts as a bridge between application-services, rust implemented sync engines and sync engines as defined by Desktop Firefox.

BridgedEngineAdaptor

SyncEngine

A “sync engine” is a thing that knows how to sync. It’s often implemented by a “store” (which is the generic term responsible for all storage associated with a component, including storage required for sync.)