OLD | NEW |
| (Empty) |
1 // Copyright 2012 The Chromium Authors. All rights reserved. | |
2 // Use of this source code is governed by a BSD-style license that can be | |
3 // found in the LICENSE file. | |
4 | |
5 #ifndef SYNC_INTERNAL_API_PUBLIC_SYNC_MANAGER_H_ | |
6 #define SYNC_INTERNAL_API_PUBLIC_SYNC_MANAGER_H_ | |
7 | |
8 #include <stdint.h> | |
9 | |
10 #include <memory> | |
11 #include <string> | |
12 #include <vector> | |
13 | |
14 #include "base/callback.h" | |
15 #include "base/files/file_path.h" | |
16 #include "base/memory/ref_counted.h" | |
17 #include "base/memory/scoped_vector.h" | |
18 #include "base/task_runner.h" | |
19 #include "base/threading/thread_checker.h" | |
20 #include "google_apis/gaia/oauth2_token_service.h" | |
21 #include "sync/base/sync_export.h" | |
22 #include "sync/internal_api/public/base/invalidation_interface.h" | |
23 #include "sync/internal_api/public/base/model_type.h" | |
24 #include "sync/internal_api/public/change_record.h" | |
25 #include "sync/internal_api/public/configure_reason.h" | |
26 #include "sync/internal_api/public/connection_status.h" | |
27 #include "sync/internal_api/public/engine/model_safe_worker.h" | |
28 #include "sync/internal_api/public/engine/sync_status.h" | |
29 #include "sync/internal_api/public/events/protocol_event.h" | |
30 #include "sync/internal_api/public/http_post_provider_factory.h" | |
31 #include "sync/internal_api/public/internal_components_factory.h" | |
32 #include "sync/internal_api/public/model_type_connector.h" | |
33 #include "sync/internal_api/public/shutdown_reason.h" | |
34 #include "sync/internal_api/public/sync_encryption_handler.h" | |
35 #include "sync/internal_api/public/util/weak_handle.h" | |
36 #include "sync/protocol/sync_protocol_error.h" | |
37 | |
38 class GURL; | |
39 | |
40 namespace sync_pb { | |
41 class EncryptedData; | |
42 } // namespace sync_pb | |
43 | |
44 namespace syncer { | |
45 | |
46 class BaseTransaction; | |
47 class CancelationSignal; | |
48 class DataTypeDebugInfoListener; | |
49 class Encryptor; | |
50 class ExtensionsActivity; | |
51 class InternalComponentsFactory; | |
52 class JsBackend; | |
53 class JsEventHandler; | |
54 class ProtocolEvent; | |
55 class SyncEncryptionHandler; | |
56 class SyncScheduler; | |
57 class TypeDebugInfoObserver; | |
58 class UnrecoverableErrorHandler; | |
59 struct Experiments; | |
60 struct UserShare; | |
61 | |
62 namespace sessions { | |
63 class SyncSessionSnapshot; | |
64 } // namespace sessions | |
65 | |
66 // Contains everything needed to talk to and identify a user account. | |
67 struct SYNC_EXPORT SyncCredentials { | |
68 SyncCredentials(); | |
69 SyncCredentials(const SyncCredentials& other); | |
70 ~SyncCredentials(); | |
71 | |
72 // Account_id of signed in account. | |
73 std::string account_id; | |
74 | |
75 // The email associated with this account. | |
76 std::string email; | |
77 | |
78 // The raw authentication token's bytes. | |
79 std::string sync_token; | |
80 | |
81 // The set of scopes to use when talking to sync server. | |
82 OAuth2TokenService::ScopeSet scope_set; | |
83 }; | |
84 | |
85 // SyncManager encapsulates syncable::Directory and serves as the parent of all | |
86 // other objects in the sync API. If multiple threads interact with the same | |
87 // local sync repository (i.e. the same sqlite database), they should share a | |
88 // single SyncManager instance. The caller should typically create one | |
89 // SyncManager for the lifetime of a user session. | |
90 // | |
91 // Unless stated otherwise, all methods of SyncManager should be called on the | |
92 // same thread. | |
93 class SYNC_EXPORT SyncManager { | |
94 public: | |
95 // An interface the embedding application implements to be notified | |
96 // on change events. Note that these methods may be called on *any* | |
97 // thread. | |
98 class SYNC_EXPORT ChangeDelegate { | |
99 public: | |
100 // Notify the delegate that changes have been applied to the sync model. | |
101 // | |
102 // This will be invoked on the same thread as on which ApplyChanges was | |
103 // called. |changes| is an array of size |change_count|, and contains the | |
104 // ID of each individual item that was changed. |changes| exists only for | |
105 // the duration of the call. If items of multiple data types change at | |
106 // the same time, this method is invoked once per data type and |changes| | |
107 // is restricted to items of the ModelType indicated by |model_type|. | |
108 // Because the observer is passed a |trans|, the observer can assume a | |
109 // read lock on the sync model that will be released after the function | |
110 // returns. | |
111 // | |
112 // The SyncManager constructs |changes| in the following guaranteed order: | |
113 // | |
114 // 1. Deletions, from leaves up to parents. | |
115 // 2. Updates to existing items with synced parents & predecessors. | |
116 // 3. New items with synced parents & predecessors. | |
117 // 4. Items with parents & predecessors in |changes|. | |
118 // 5. Repeat #4 until all items are in |changes|. | |
119 // | |
120 // Thus, an implementation of OnChangesApplied should be able to | |
121 // process the change records in the order without having to worry about | |
122 // forward dependencies. But since deletions come before reparent | |
123 // operations, a delete may temporarily orphan a node that is | |
124 // updated later in the list. | |
125 virtual void OnChangesApplied(ModelType model_type, | |
126 int64_t model_version, | |
127 const BaseTransaction* trans, | |
128 const ImmutableChangeRecordList& changes) = 0; | |
129 | |
130 // OnChangesComplete gets called when the TransactionComplete event is | |
131 // posted (after OnChangesApplied finishes), after the transaction lock | |
132 // and the change channel mutex are released. | |
133 // | |
134 // The purpose of this function is to support processors that require | |
135 // split-transactions changes. For example, if a model processor wants to | |
136 // perform blocking I/O due to a change, it should calculate the changes | |
137 // while holding the transaction lock (from within OnChangesApplied), buffer | |
138 // those changes, let the transaction fall out of scope, and then commit | |
139 // those changes from within OnChangesComplete (postponing the blocking | |
140 // I/O to when it no longer holds any lock). | |
141 virtual void OnChangesComplete(ModelType model_type) = 0; | |
142 | |
143 protected: | |
144 virtual ~ChangeDelegate(); | |
145 }; | |
146 | |
147 // Like ChangeDelegate, except called only on the sync thread and | |
148 // not while a transaction is held. For objects that want to know | |
149 // when changes happen, but don't need to process them. | |
150 class SYNC_EXPORT ChangeObserver { | |
151 public: | |
152 // Ids referred to in |changes| may or may not be in the write | |
153 // transaction specified by |write_transaction_id|. If they're | |
154 // not, that means that the node didn't actually change, but we | |
155 // marked them as changed for some other reason (e.g., siblings of | |
156 // re-ordered nodes). | |
157 // | |
158 // TODO(sync, long-term): Ideally, ChangeDelegate/Observer would | |
159 // be passed a transformed version of EntryKernelMutation instead | |
160 // of a transaction that would have to be used to look up the | |
161 // changed nodes. That is, ChangeDelegate::OnChangesApplied() | |
162 // would still be called under the transaction, but all the needed | |
163 // data will be passed down. | |
164 // | |
165 // Even more ideally, we would have sync semantics such that we'd | |
166 // be able to apply changes without being under a transaction. | |
167 // But that's a ways off... | |
168 virtual void OnChangesApplied(ModelType model_type, | |
169 int64_t write_transaction_id, | |
170 const ImmutableChangeRecordList& changes) = 0; | |
171 | |
172 virtual void OnChangesComplete(ModelType model_type) = 0; | |
173 | |
174 protected: | |
175 virtual ~ChangeObserver(); | |
176 }; | |
177 | |
178 // An interface the embedding application implements to receive | |
179 // notifications from the SyncManager. Register an observer via | |
180 // SyncManager::AddObserver. All methods are called only on the | |
181 // sync thread. | |
182 class SYNC_EXPORT Observer { | |
183 public: | |
184 // A round-trip sync-cycle took place and the syncer has resolved any | |
185 // conflicts that may have arisen. | |
186 virtual void OnSyncCycleCompleted( | |
187 const sessions::SyncSessionSnapshot& snapshot) = 0; | |
188 | |
189 // Called when the status of the connection to the sync server has | |
190 // changed. | |
191 virtual void OnConnectionStatusChange(ConnectionStatus status) = 0; | |
192 | |
193 // Called when initialization is complete to the point that SyncManager can | |
194 // process changes. This does not necessarily mean authentication succeeded | |
195 // or that the SyncManager is online. | |
196 // IMPORTANT: Creating any type of transaction before receiving this | |
197 // notification is illegal! | |
198 // WARNING: Calling methods on the SyncManager before receiving this | |
199 // message, unless otherwise specified, produces undefined behavior. | |
200 | |
201 virtual void OnInitializationComplete( | |
202 const WeakHandle<JsBackend>& js_backend, | |
203 const WeakHandle<DataTypeDebugInfoListener>& debug_info_listener, | |
204 bool success, | |
205 ModelTypeSet restored_types) = 0; | |
206 | |
207 virtual void OnActionableError( | |
208 const SyncProtocolError& sync_protocol_error) = 0; | |
209 | |
210 virtual void OnMigrationRequested(ModelTypeSet types) = 0; | |
211 | |
212 virtual void OnProtocolEvent(const ProtocolEvent& event) = 0; | |
213 | |
214 protected: | |
215 virtual ~Observer(); | |
216 }; | |
217 | |
218 // Arguments for initializing SyncManager. | |
219 struct SYNC_EXPORT InitArgs { | |
220 InitArgs(); | |
221 ~InitArgs(); | |
222 | |
223 // Path in which to create or open sync's sqlite database (aka the | |
224 // directory). | |
225 base::FilePath database_location; | |
226 | |
227 // Used to propagate events to chrome://sync-internals. Optional. | |
228 WeakHandle<JsEventHandler> event_handler; | |
229 | |
230 // URL of the sync server. | |
231 GURL service_url; | |
232 | |
233 // Used to communicate with the sync server. | |
234 std::unique_ptr<HttpPostProviderFactory> post_factory; | |
235 | |
236 std::vector<scoped_refptr<ModelSafeWorker> > workers; | |
237 | |
238 // Must outlive SyncManager. | |
239 ExtensionsActivity* extensions_activity; | |
240 | |
241 // Must outlive SyncManager. | |
242 ChangeDelegate* change_delegate; | |
243 | |
244 // Credentials to be used when talking to the sync server. | |
245 SyncCredentials credentials; | |
246 | |
247 // Unqiuely identifies this client to the invalidation notification server. | |
248 std::string invalidator_client_id; | |
249 | |
250 // Used to boostrap the cryptographer. | |
251 std::string restored_key_for_bootstrapping; | |
252 std::string restored_keystore_key_for_bootstrapping; | |
253 | |
254 std::unique_ptr<InternalComponentsFactory> internal_components_factory; | |
255 | |
256 // Must outlive SyncManager. | |
257 Encryptor* encryptor; | |
258 | |
259 WeakHandle<UnrecoverableErrorHandler> unrecoverable_error_handler; | |
260 base::Closure report_unrecoverable_error_function; | |
261 | |
262 // Carries shutdown requests across threads and will be used to cut short | |
263 // any network I/O and tell the syncer to exit early. | |
264 // | |
265 // Must outlive SyncManager. | |
266 CancelationSignal* cancelation_signal; | |
267 | |
268 // Optional nigori state to be restored. | |
269 std::unique_ptr<SyncEncryptionHandler::NigoriState> saved_nigori_state; | |
270 }; | |
271 | |
272 typedef base::Callback<void(void)> ClearServerDataCallback; | |
273 | |
274 SyncManager(); | |
275 virtual ~SyncManager(); | |
276 | |
277 // Initialize the sync manager using arguments from |args|. | |
278 // | |
279 // Note, args is passed by non-const pointer because it contains objects like | |
280 // unique_ptr. | |
281 virtual void Init(InitArgs* args) = 0; | |
282 | |
283 virtual ModelTypeSet InitialSyncEndedTypes() = 0; | |
284 | |
285 // Returns those types within |types| that have an empty progress marker | |
286 // token. | |
287 virtual ModelTypeSet GetTypesWithEmptyProgressMarkerToken( | |
288 ModelTypeSet types) = 0; | |
289 | |
290 // Purge from the directory those types with non-empty progress markers | |
291 // but without initial synced ended set. | |
292 // Returns false if an error occurred, true otherwise. | |
293 virtual bool PurgePartiallySyncedTypes() = 0; | |
294 | |
295 // Update tokens that we're using in Sync. Email must stay the same. | |
296 virtual void UpdateCredentials(const SyncCredentials& credentials) = 0; | |
297 | |
298 // Put the syncer in normal mode ready to perform nudges and polls. | |
299 virtual void StartSyncingNormally( | |
300 const ModelSafeRoutingInfo& routing_info, | |
301 base::Time last_poll_time) = 0; | |
302 | |
303 // Switches the mode of operation to CONFIGURATION_MODE and performs | |
304 // any configuration tasks needed as determined by the params. Once complete, | |
305 // syncer will remain in CONFIGURATION_MODE until StartSyncingNormally is | |
306 // called. | |
307 // Data whose types are not in |new_routing_info| are purged from sync | |
308 // directory, unless they're part of |to_ignore|, in which case they're left | |
309 // untouched. The purged data is backed up in delete journal for recovery in | |
310 // next session if its type is in |to_journal|. If in |to_unapply| | |
311 // only the local data is removed; the server data is preserved. | |
312 // |ready_task| is invoked when the configuration completes. | |
313 // |retry_task| is invoked if the configuration job could not immediately | |
314 // execute. |ready_task| will still be called when it eventually | |
315 // does finish. | |
316 virtual void ConfigureSyncer( | |
317 ConfigureReason reason, | |
318 ModelTypeSet to_download, | |
319 ModelTypeSet to_purge, | |
320 ModelTypeSet to_journal, | |
321 ModelTypeSet to_unapply, | |
322 const ModelSafeRoutingInfo& new_routing_info, | |
323 const base::Closure& ready_task, | |
324 const base::Closure& retry_task) = 0; | |
325 | |
326 // Inform the syncer of a change in the invalidator's state. | |
327 virtual void SetInvalidatorEnabled(bool invalidator_enabled) = 0; | |
328 | |
329 // Inform the syncer that its cached information about a type is obsolete. | |
330 virtual void OnIncomingInvalidation( | |
331 syncer::ModelType type, | |
332 std::unique_ptr<syncer::InvalidationInterface> invalidation) = 0; | |
333 | |
334 // Adds a listener to be notified of sync events. | |
335 // NOTE: It is OK (in fact, it's probably a good idea) to call this before | |
336 // having received OnInitializationCompleted. | |
337 virtual void AddObserver(Observer* observer) = 0; | |
338 | |
339 // Remove the given observer. Make sure to call this if the | |
340 // Observer is being destroyed so the SyncManager doesn't | |
341 // potentially dereference garbage. | |
342 virtual void RemoveObserver(Observer* observer) = 0; | |
343 | |
344 // Status-related getter. May be called on any thread. | |
345 virtual SyncStatus GetDetailedStatus() const = 0; | |
346 | |
347 // Call periodically from a database-safe thread to persist recent changes | |
348 // to the syncapi model. | |
349 virtual void SaveChanges() = 0; | |
350 | |
351 // Issue a final SaveChanges, and close sqlite handles. | |
352 virtual void ShutdownOnSyncThread(ShutdownReason reason) = 0; | |
353 | |
354 // May be called from any thread. | |
355 virtual UserShare* GetUserShare() = 0; | |
356 | |
357 // Returns an instance of the main interface for non-blocking sync types. | |
358 virtual std::unique_ptr<syncer_v2::ModelTypeConnector> | |
359 GetModelTypeConnectorProxy() = 0; | |
360 | |
361 // Returns the cache_guid of the currently open database. | |
362 // Requires that the SyncManager be initialized. | |
363 virtual const std::string cache_guid() = 0; | |
364 | |
365 // Reads the nigori node to determine if any experimental features should | |
366 // be enabled. | |
367 // Note: opens a transaction. May be called on any thread. | |
368 virtual bool ReceivedExperiment(Experiments* experiments) = 0; | |
369 | |
370 // Uses a read-only transaction to determine if the directory being synced has | |
371 // any remaining unsynced items. May be called on any thread. | |
372 virtual bool HasUnsyncedItems() = 0; | |
373 | |
374 // Returns the SyncManager's encryption handler. | |
375 virtual SyncEncryptionHandler* GetEncryptionHandler() = 0; | |
376 | |
377 virtual std::unique_ptr<base::ListValue> GetAllNodesForType( | |
378 syncer::ModelType type) = 0; | |
379 | |
380 // Ask the SyncManager to fetch updates for the given types. | |
381 virtual void RefreshTypes(ModelTypeSet types) = 0; | |
382 | |
383 // Returns any buffered protocol events. Does not clear the buffer. | |
384 virtual ScopedVector<syncer::ProtocolEvent> GetBufferedProtocolEvents() = 0; | |
385 | |
386 // Functions to manage registrations of DebugInfoObservers. | |
387 virtual void RegisterDirectoryTypeDebugInfoObserver( | |
388 syncer::TypeDebugInfoObserver* observer) = 0; | |
389 virtual void UnregisterDirectoryTypeDebugInfoObserver( | |
390 syncer::TypeDebugInfoObserver* observer) = 0; | |
391 virtual bool HasDirectoryTypeDebugInfoObserver( | |
392 syncer::TypeDebugInfoObserver* observer) = 0; | |
393 | |
394 // Request that all current counter values be emitted as though they had just | |
395 // been updated. Useful for initializing new observers' state. | |
396 virtual void RequestEmitDebugInfo() = 0; | |
397 | |
398 // Clears server data and invokes |callback| when complete. | |
399 // | |
400 // This is an asynchronous operation that requires interaction with the sync | |
401 // server. The operation will automatically be retried with backoff until it | |
402 // completes successfully or sync is shutdown. | |
403 virtual void ClearServerData(const ClearServerDataCallback& callback) = 0; | |
404 | |
405 // Updates Sync's tracking of whether the cookie jar has a mismatch with the | |
406 // chrome account. See ClientConfigParams proto message for more info. | |
407 // Note: this does not trigger a sync cycle. It just updates the sync context. | |
408 virtual void OnCookieJarChanged(bool account_mismatch, bool empty_jar) = 0; | |
409 }; | |
410 | |
411 } // namespace syncer | |
412 | |
413 #endif // SYNC_INTERNAL_API_PUBLIC_SYNC_MANAGER_H_ | |
OLD | NEW |