Source code
Revision control
Copy as Markdown
Other Tools
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
#include "mozIServicesLogSink.idl"
#include "nsISupports.idl"
interface nsIVariant;
// A generic callback called with a result. Variants are automatically unboxed
// in JavaScript: for example, a `UTF8String` will be passed as a string
// argument; an `Int32` or `Int64` as a number. Methods that don't return a
// value, like `setLastSync` or `setUploaded`, will pass a `null` variant to
// `handleSuccess`. For all callback types in this file, either `handleSuccess`
// or `handleError` is guaranteed to be called once.
[scriptable, uuid(9b7dd2a3-df99-4469-9ea9-61b222098695)]
interface mozIBridgedSyncEngineCallback : nsISupports {
void handleSuccess(in nsIVariant result);
void handleError(in nsresult code, in AUTF8String message);
};
// A callback called after the engine applies incoming records. This is separate
// from `mozIBridgedSyncEngineCallback` because variants can't hold an
// `Array<T>` type.
[scriptable, uuid(2776cdd5-799a-4009-b2f3-356d940a5244)]
interface mozIBridgedSyncEngineApplyCallback : nsISupports {
// Notifies Sync that the bridged engine has finished applying incoming
// records, and has outgoing records. Sync encrypts and uploads these
// records, and notifies the engine that the upload succeeded by
// calling `engine.setUploaded(uploadedOutgoingRecordIds, ...)`.
void handleSuccess(in Array<AUTF8String> outgoingEnvelopesAsJSON);
// Notifies Sync that the bridged engine failed to apply the staged records.
void handleError(in nsresult code, in AUTF8String message);
};
// A bridged engine is implemented in Rust. It handles storage internally, and
// exposes a minimal interface for the JS Sync code to control it.
[scriptable, uuid(3b2b80be-c30e-4498-8065-01809cfe8d47)]
interface mozIBridgedSyncEngine : nsISupports {
// The storage version for this engine's collection. If the version in the
// server's `meta/global` record is newer than ours, we'll refuse to sync,
// since we might not understand the data; if it's older, we'll wipe the
// collection on the server, and upload our data as if on a first sync.
readonly attribute long storageVersion;
// Whether this engine tolerates skipped records, where a "skipped" record
// is one that would cause the server's published limits to be exceeded
// (for example, a single record where the payload is larger than the
// server accepts.)
// If this returns true, we will just skip the record without even attempting
// to upload. If this is false, we'll abort the entire batch.
// If the engine allows this, it will need to detect this scenario by noticing
// the ID is not in the 'success' records reported to `setUploaded`.
// (Note that this is not to be confused with the fact server's can currently
// reject records as part of a POST - but we hope to remove this ability from
// the server API. Note also that this is not bullet-proof - if the count of
// records is high, it's possible that we will have committed a previous
// batch before we hit the relevant limits, so things might have been written.
// We hope to fix this by ensuring batch limits are such that this is
// impossible)
readonly attribute boolean allowSkippedRecord;
// Wires up the Sync logging machinery to the bridged engine. This can be
// `null`, in which case any logs from the engine will be discarded.
attribute mozIServicesLogSink logger;
// Returns the last sync time, in milliseconds, for this engine's
// collection. This is used to build the collection URL for fetching
// incoming records, and as the initial value of the `X-I-U-S` header on
// upload. If the engine persists incoming records in a permanent (non-temp)
// table, `getLastSync` can return a "high water mark" that's the newer of
// the collection's last sync time, and the most recent record modification
// time. This avoids redownloading incoming records that were previously
// downloaded, but not applied.
void getLastSync(in mozIBridgedSyncEngineCallback callback);
// Sets the last sync time, in milliseconds. This is used to fast-forward
// the last sync time for the engine's collection after fetching all
// records, and after each `setUploaded` call with the `X-L-M` header from
// the server. It may be called multiple times per sync.
void setLastSync(in long long lastSyncMillis,
in mozIBridgedSyncEngineCallback callback);
// Returns the sync ID for this engine's collection. Used for testing;
// Sync only calls `ensureCurrentSyncId` and `resetSyncId`. On success,
// calls `callback.handleSuccess(in AUTF8String currentSyncId)`.
void getSyncId(in mozIBridgedSyncEngineCallback callback);
// Generates a new sync ID for this engine, and resets all local Sync
// metadata, including the last sync time and any change flags, to start
// over as a first sync. On success, calls
// `callback.handleSuccess(newSyncId)`, where `newSyncId` is
// `AUTF8String` variant. Sync will upload the new sync ID in the
// `meta/global` record.
void resetSyncId(in mozIBridgedSyncEngineCallback callback);
// Ensures that the local sync ID for the engine matches the sync ID for
// the collection on the server. On a mismatch, the engine can:
// 1. Reset all local Sync state, adopt `newSyncId` as the new sync ID,
// and call `callback.handleSuccess(newSyncId)`. Most engines should
// do this.
// 2. Ignore the given `newSyncId`, use its existing local sync ID
// without resetting any state, and call
// `callback.handleSuccess(existingSyncId)`. This is useful if, for
// example, the underlying database has been restored from a backup,
// and the engine would like to force a reset and first sync on all
// other devices.
// 3. Ignore the given `newSyncId`, reset all local Sync state, and
// generate a fresh sync ID, as if `resetSyncId`. This resets the
// engine's state everywhere, locally and on all other devices.
// If the callback is called with a different sync ID than `newSyncId`,
// Sync will reupload `meta/global` with the different ID. Otherwise, it
// will assume that the engine has adopted the `newSyncId`, and do nothing.
void ensureCurrentSyncId(in AUTF8String newSyncId,
in mozIBridgedSyncEngineCallback callback);
// Notifies the engine that sync is starting. The engine can use this method
// to set up temp tables for merging, for example. This will only be called
// once per sync, and before any `storeIncoming` calls.
void syncStarted(in mozIBridgedSyncEngineCallback callback);
// Stages a batch of incoming records, and calls the `callback` when
// done. This method may be called multiple times per sync, once per
// incoming batch, and always after `syncStarted`. Flushing incoming records
// more often incurs more writes to disk, but avoids redownloading and
// reapplying more records if syncing is interrupted. Typically, engines
// will stage incoming records in an SQLite temp table, and merge them with
// the local database when `apply` is called.
void storeIncoming(in Array<AUTF8String> incomingEnvelopesAsJSON,
in mozIBridgedSyncEngineCallback callback);
// Applies all the staged records, and calls the `callback` with
// outgoing records to upload. This will always be called after
// `storeIncoming`, and only once per sync. Application should be atomic:
// either all incoming records apply successfully, or none.
void apply(in mozIBridgedSyncEngineApplyCallback callback);
// Notifies the engine that Sync successfully uploaded the records with the
// given IDs. This method may be called multiple times per sync, once per
// batch upload. This will always be called after `apply`.
void setUploaded(in long long newTimestampMillis,
in Array<AUTF8String> uploadedIds,
in mozIBridgedSyncEngineCallback callback);
// Notifies the engine that syncing has finished, and the engine shouldn't
// expect any more `setUploaded` calls. At this point, any outgoing records
// that weren't passed to `setUploaded` should be assumed failed. This is
// guaranteed to be called even if the sync fails. This will only be called
// once per sync.
void syncFinished(in mozIBridgedSyncEngineCallback callback);
// Resets all local Sync metadata, including the sync ID, last sync time,
// and any change flags, but preserves all data. After a reset, the engine will
// sync as if for the first time.
void reset(in mozIBridgedSyncEngineCallback callback);
// Erases all locally stored data and metadata for this engine.
void wipe(in mozIBridgedSyncEngineCallback callback);
};