services/interfaces/mozIBridgedSyncEngine.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "mozIServicesLogSink.idl"
   6 #include "nsISupports.idl"
   7
   8 interface nsIVariant;
   9
  10 // A generic callback called with a result. Variants are automatically unboxed
  11 // in JavaScript: for example, a `UTF8String` will be passed as a string
  12 // argument; an `Int32` or `Int64` as a number. Methods that don't return a
  13 // value, like `setLastSync` or `setUploaded`, will pass a `null` variant to
  14 // `handleSuccess`. For all callback types in this file, either `handleSuccess`
  15 // or `handleError` is guaranteed to be called once.
  16 [scriptable, uuid(9b7dd2a3-df99-4469-9ea9-61b222098695)]
  17 interface mozIBridgedSyncEngineCallback : nsISupports {
  18     void handleSuccess(in nsIVariant result);
  19     void handleError(in nsresult code, in AUTF8String message);
  20 };
  21
  22 // A callback called after the engine applies incoming records. This is separate
  23 // from `mozIBridgedSyncEngineCallback` because variants can't hold an
  24 // `Array<T>` type.
  25 [scriptable, uuid(2776cdd5-799a-4009-b2f3-356d940a5244)]
  26 interface mozIBridgedSyncEngineApplyCallback : nsISupports {
  27     // Notifies Sync that the bridged engine has finished applying incoming
  28     // records, and has outgoing records. Sync encrypts and uploads these
  29     // records, and notifies the engine that the upload succeeded by
  30     // calling `engine.setUploaded(uploadedOutgoingRecordIds, ...)`.
  31     void handleSuccess(in Array<AUTF8String> outgoingEnvelopesAsJSON);
  32
  33     // Notifies Sync that the bridged engine failed to apply the staged records.
  34     void handleError(in nsresult code, in AUTF8String message);
  35 };
  36
  37 // A bridged engine is implemented in Rust. It handles storage internally, and
  38 // exposes a minimal interface for the JS Sync code to control it.
  39 [scriptable, uuid(3b2b80be-c30e-4498-8065-01809cfe8d47)]
  40 interface mozIBridgedSyncEngine : nsISupports {
  41     // The storage version for this engine's collection. If the version in the
  42     // server's `meta/global` record is newer than ours, we'll refuse to sync,
  43     // since we might not understand the data; if it's older, we'll wipe the
  44     // collection on the server, and upload our data as if on a first sync.
  45     readonly attribute long storageVersion;
  46
  47     // Whether this engine tolerates skipped records, where a "skipped" record
  48     // is one that would cause the server's published limits to be exceeded
  49     // (for example, a single record where the payload is larger than the
  50     // server accepts.)
  51     // If this returns true, we will just skip the record without even attempting
  52     // to upload. If this is false, we'll abort the entire batch.
  53     // If the engine allows this, it will need to detect this scenario by noticing
  54     // the ID is not in the 'success' records reported to `setUploaded`.
  55     // (Note that this is not to be confused with the fact server's can currently
  56     // reject records as part of a POST - but we hope to remove this ability from
  57     // the server API. Note also that this is not bullet-proof - if the count of
  58     // records is high, it's possible that we will have committed a previous
  59     // batch before we hit the relevant limits, so things might have been written.
  60     // We hope to fix this by ensuring batch limits are such that this is
  61     // impossible)
  62     readonly attribute boolean allowSkippedRecord;
  63
  64     // Wires up the Sync logging machinery to the bridged engine. This can be
  65     // `null`, in which case any logs from the engine will be discarded.
  66     attribute mozIServicesLogSink logger;
  67
  68     // Returns the last sync time, in milliseconds, for this engine's
  69     // collection. This is used to build the collection URL for fetching
  70     // incoming records, and as the initial value of the `X-I-U-S` header on
  71     // upload. If the engine persists incoming records in a permanent (non-temp)
  72     // table, `getLastSync` can return a "high water mark" that's the newer of
  73     // the collection's last sync time, and the most recent record modification
  74     // time. This avoids redownloading incoming records that were previously
  75     // downloaded, but not applied.
  76     void getLastSync(in mozIBridgedSyncEngineCallback callback);
  77
  78     // Sets the last sync time, in milliseconds. This is used to fast-forward
  79     // the last sync time for the engine's collection after fetching all
  80     // records, and after each `setUploaded` call with the `X-L-M` header from
  81     // the server. It may be called multiple times per sync.
  82     void setLastSync(in long long lastSyncMillis,
  83                      in mozIBridgedSyncEngineCallback callback);
  84
  85     // Returns the sync ID for this engine's collection. Used for testing;
  86     // Sync only calls `ensureCurrentSyncId` and `resetSyncId`. On success,
  87     // calls `callback.handleSuccess(in AUTF8String currentSyncId)`.
  88     void getSyncId(in mozIBridgedSyncEngineCallback callback);
  89
  90     // Generates a new sync ID for this engine, and resets all local Sync
  91     // metadata, including the last sync time and any change flags, to start
  92     // over as a first sync. On success, calls
  93     // `callback.handleSuccess(newSyncId)`, where `newSyncId` is
  94     // `AUTF8String` variant. Sync will upload the new sync ID in the
  95     // `meta/global` record.
  96     void resetSyncId(in mozIBridgedSyncEngineCallback callback);
  97
  98     // Ensures that the local sync ID for the engine matches the sync ID for
  99     // the collection on the server. On a mismatch, the engine can:
 100     //   1. Reset all local Sync state, adopt `newSyncId` as the new sync ID,
 101     //      and call `callback.handleSuccess(newSyncId)`. Most engines should
 102     //      do this.
 103     //   2. Ignore the given `newSyncId`, use its existing local sync ID
 104     //      without resetting any state, and call
 105     //      `callback.handleSuccess(existingSyncId)`. This is useful if, for
 106     //      example, the underlying database has been restored from a backup,
 107     //      and the engine would like to force a reset and first sync on all
 108     //      other devices.
 109     //   3. Ignore the given `newSyncId`, reset all local Sync state, and
 110     //      generate a fresh sync ID, as if `resetSyncId`. This resets the
 111     //      engine's state everywhere, locally and on all other devices.
 112     // If the callback is called with a different sync ID than `newSyncId`,
 113     // Sync will reupload `meta/global` with the different ID. Otherwise, it
 114     // will assume that the engine has adopted the `newSyncId`, and do nothing.
 115     void ensureCurrentSyncId(in AUTF8String newSyncId,
 116                              in mozIBridgedSyncEngineCallback callback);
 117
 118     // Notifies the engine that sync is starting. The engine can use this method
 119     // to set up temp tables for merging, for example. This will only be called
 120     // once per sync, and before any `storeIncoming` calls.
 121     void syncStarted(in mozIBridgedSyncEngineCallback callback);
 122
 123     // Stages a batch of incoming records, and calls the `callback` when
 124     // done. This method may be called multiple times per sync, once per
 125     // incoming batch, and always after `syncStarted`. Flushing incoming records
 126     // more often incurs more writes to disk, but avoids redownloading and
 127     // reapplying more records if syncing is interrupted. Typically, engines
 128     // will stage incoming records in an SQLite temp table, and merge them with
 129     // the local database when `apply` is called.
 130     void storeIncoming(in Array<AUTF8String> incomingEnvelopesAsJSON,
 131                        in mozIBridgedSyncEngineCallback callback);
 132
 133     // Applies all the staged records, and calls the `callback` with
 134     // outgoing records to upload. This will always be called after
 135     // `storeIncoming`, and only once per sync. Application should be atomic:
 136     // either all incoming records apply successfully, or none.
 137     void apply(in mozIBridgedSyncEngineApplyCallback callback);
 138
 139     // Notifies the engine that Sync successfully uploaded the records with the
 140     // given IDs. This method may be called multiple times per sync, once per
 141     // batch upload. This will always be called after `apply`.
 142     void setUploaded(in long long newTimestampMillis,
 143                      in Array<AUTF8String> uploadedIds,
 144                      in mozIBridgedSyncEngineCallback callback);
 145
 146     // Notifies the engine that syncing has finished, and the engine shouldn't
 147     // expect any more `setUploaded` calls. At this point, any outgoing records
 148     // that weren't passed to `setUploaded` should be assumed failed. This is
 149     // guaranteed to be called even if the sync fails. This will only be called
 150     // once per sync.
 151     void syncFinished(in mozIBridgedSyncEngineCallback callback);
 152
 153     // Resets all local Sync metadata, including the sync ID, last sync time,
 154     // and any change flags, but preserves all data. After a reset, the engine will
 155     // sync as if for the first time.
 156     void reset(in mozIBridgedSyncEngineCallback callback);
 157
 158     // Erases all locally stored data and metadata for this engine.
 159     void wipe(in mozIBridgedSyncEngineCallback callback);
 160 };