tor-browser

mozIBridgedSyncEngine.idl (8951B)

---

/* 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
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#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;

   // 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);
};