1 /*
2  * Copyright (c) 2021 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #ifndef KV_STORE_NB_DELEGATE_H
17 #define KV_STORE_NB_DELEGATE_H
18 
19 #include <functional>
20 #include <map>
21 #include <string>
22 
23 #include "cloud/cloud_store_types.h"
24 #include "cloud/icloud_db.h"
25 #include "intercepted_data.h"
26 #include "iprocess_system_api_adapter.h"
27 #include "kv_store_nb_conflict_data.h"
28 #include "kv_store_observer.h"
29 #include "kv_store_result_set.h"
30 #include "query.h"
31 #include "store_types.h"
32 
33 namespace DistributedDB {
34 using KvStoreNbPublishOnConflict = std::function<void (const Entry &local, const Entry *sync, bool isLocalLastest)>;
35 using KvStoreNbConflictNotifier = std::function<void (const KvStoreNbConflictData &data)>;
36 
37 class KvStoreNbDelegate {
38 public:
39     struct Option {
40         bool createIfNecessary = true;
41         bool isMemoryDb = false;
42         bool isEncryptedDb = false;
43         CipherType cipher = CipherType::DEFAULT;
44         CipherPassword passwd;
45         std::string schema = "";
46         bool createDirByStoreIdOnly = false;
47         SecurityOption secOption; // Add data security level parameter
48         KvStoreObserver *observer = nullptr;
49         Key key; // The key that needs to be subscribed on obsever, empty means full subscription
50         unsigned int mode = 0; // obsever mode
51         int conflictType = 0;
52         KvStoreNbConflictNotifier notifier = nullptr;
53         int conflictResolvePolicy = LAST_WIN;
54         bool isNeedIntegrityCheck = false;
55         bool isNeedRmCorruptedDb = false;
56         bool isNeedCompressOnSync = false;
57         uint8_t compressionRate = 100; // Valid in [1, 100].
58         bool syncDualTupleMode = false; // communicator label use dualTuple hash or not
59         bool localOnly = false; // active sync module
60         std::string storageEngineType = SQLITE; // use gaussdb_rd as storage engine
61         Rdconfig rdconfig;
62     };
63 
64     struct DatabaseStatus {
65         bool isRebuild = false;
66     };
67 
~KvStoreNbDelegate()68     DB_API virtual ~KvStoreNbDelegate() {}
69 
70     // Public zone interfaces
71     // Get value from the public zone of this store according to the key.
72     DB_API virtual DBStatus Get(const Key &key, Value &value) const = 0;
73 
74     // Get entries from the public zone of this store by key prefix.
75     // If 'keyPrefix' is empty, It would return all the entries in the zone.
76     DB_API virtual DBStatus GetEntries(const Key &keyPrefix, std::vector<Entry> &entries) const = 0;
77 
78     // Get entries from the public zone of this store by key prefix.
79     // If 'keyPrefix' is empty, It would return all the entries in the zone.
80     DB_API virtual DBStatus GetEntries(const Key &keyPrefix, KvStoreResultSet *&resultSet) const = 0;
81 
82     // Get entries from the public zone of this store by query.
83     // If 'query' is empty, It would return all the entries in the zone.
84     DB_API virtual DBStatus GetEntries(const Query &query, std::vector<Entry> &entries) const = 0;
85 
86     // Get entries from the public zone of this store by query.
87     // If query is empty, It would return all the entries in the zone.
88     DB_API virtual DBStatus GetEntries(const Query &query, KvStoreResultSet *&resultSet) const = 0;
89 
90     // Get count from the public zone of this store those meet conditions.
91     // If query is empty, It would return all the entries count in the zone.
92     DB_API virtual DBStatus GetCount(const Query &query, int &count) const = 0;
93 
94     // Close the result set returned by GetEntries().
95     DB_API virtual DBStatus CloseResultSet(KvStoreResultSet *&resultSet) = 0;
96 
97     // Put one key-value entry into the public zone of this store.
98     DB_API virtual DBStatus Put(const Key &key, const Value &value) = 0;
99 
100     // Put a batch of entries into the public zone of this store.
101     DB_API virtual DBStatus PutBatch(const std::vector<Entry> &entries) = 0;
102 
103     // Delete a batch of entries from the public zone of this store.
104     DB_API virtual DBStatus DeleteBatch(const std::vector<Key> &keys) = 0;
105 
106     // Delete one key-value entry from the public zone of this store according to the key.
107     DB_API virtual DBStatus Delete(const Key &key) = 0;
108 
109     // Local zone interfaces
110     // Get value from the local zone of this store according to the key.
111     DB_API virtual DBStatus GetLocal(const Key &key, Value &value) const = 0;
112 
113     // Get key-value entries from the local zone of this store by key prefix.
114     // If keyPrefix is empty, It would return all the entries in the local zone.
115     DB_API virtual DBStatus GetLocalEntries(const Key &keyPrefix, std::vector<Entry> &entries) const = 0;
116 
117     // Put one key-value entry into the local zone of this store.
118     DB_API virtual DBStatus PutLocal(const Key &key, const Value &value) = 0;
119 
120     // Delete one key-value entry from the local zone of this store according to the key.
121     DB_API virtual DBStatus DeleteLocal(const Key &key) = 0;
122 
123     // Migrating(local zone <-> public zone) interfaces
124     // Publish a local key-value entry.
125     // Migrate the entry from the local zone to public zone.
126     DB_API virtual DBStatus PublishLocal(const Key &key, bool deleteLocal, bool updateTimestamp,
127         const KvStoreNbPublishOnConflict &onConflict) = 0;
128 
129     // Unpublish a public key-value entry.
130     // Migrate the entry from the public zone to local zone.
131     DB_API virtual DBStatus UnpublishToLocal(const Key &key, bool deletePublic, bool updateTimestamp) = 0;
132 
133     // Observer interfaces
134     // Register one observer which concerns the key and the changed data mode.
135     // If key is empty, observer would get all the changed data of the mode.
136     // There are three mode: native changes of nb syncable kv store,
137     //                       synced data changes from remote devices,
138     //                       local changes of local kv store.
139     DB_API virtual DBStatus RegisterObserver(const Key &key, unsigned int mode, KvStoreObserver *observer) = 0;
140 
141     // UnRegister the registered observer.
142     DB_API virtual DBStatus UnRegisterObserver(const KvStoreObserver *observer) = 0;
143 
144     // Remove the device data synced from remote.
145     DB_API virtual DBStatus RemoveDeviceData(const std::string &device) = 0;
146 
147     // Other interfaces
148     DB_API virtual std::string GetStoreId() const = 0;
149 
150     // Sync function interface, if wait set true, this function will be blocked until sync finished
151     DB_API virtual DBStatus Sync(const std::vector<std::string> &devices, SyncMode mode,
152         const std::function<void(const std::map<std::string, DBStatus> &devicesMap)> &onComplete,
153         bool wait = false) = 0;
154 
155     // Special pragma interface, see PragmaCmd and PragmaData,
156     DB_API virtual DBStatus Pragma(PragmaCmd cmd, PragmaData &paramData) = 0;
157 
158     // Set the conflict notifier for getting the specified type conflict data.
159     DB_API virtual DBStatus SetConflictNotifier(int conflictType,
160         const KvStoreNbConflictNotifier &notifier) = 0;
161 
162     // Used to rekey the database.
163     // Warning rekey may reopen database file, file handle may lose while locked
164     DB_API virtual DBStatus Rekey(const CipherPassword &password) = 0;
165 
166     // Empty passwords represent non-encrypted files.
167     // Export existing database files to a specified database file in the specified directory.
168     DB_API virtual DBStatus Export(const std::string &filePath, const CipherPassword &passwd, bool force = false) = 0;
169 
170     // Import the existing database files to the specified database file in the specified directory.
171     // Warning Import may reopen database file in locked state
172     DB_API virtual DBStatus Import(const std::string &filePath, const CipherPassword &passwd) = 0;
173 
174     // Start a transaction
175     DB_API virtual DBStatus StartTransaction() = 0;
176 
177     // Commit a transaction
178     DB_API virtual DBStatus Commit() = 0;
179 
180     // Rollback a transaction
181     DB_API virtual DBStatus Rollback() = 0;
182 
183     // Put a batch of entries into the local zone of this store.
184     DB_API virtual DBStatus PutLocalBatch(const std::vector<Entry> &entries) = 0;
185 
186     // Delete a batch of entries from the local zone of this store according to the keys.
187     DB_API virtual DBStatus DeleteLocalBatch(const std::vector<Key> &keys) = 0;
188 
189     // Get the SecurityOption of this kvStore.
190     DB_API virtual DBStatus GetSecurityOption(SecurityOption &option) const = 0;
191 
192     // Set a notify callback, it will be called when remote push or push_pull finished.
193     // If Repeat set, subject to the last time.
194     // If set nullptr, means unregister the notify.
195     DB_API virtual DBStatus SetRemotePushFinishedNotify(const RemotePushFinishedNotifier &notifier) = 0;
196 
197     // Sync function interface, if wait set true, this function will be blocked until sync finished.
198     // Param query used to filter the records to be synchronized.
199     // Now just support push mode and query by prefixKey.
200     // If Query.limit is used, its query cache will not be recorded, In the same way below,
201     // the synchronization will still take the full amount.
202     DB_API virtual DBStatus Sync(const std::vector<std::string> &devices, SyncMode mode,
203         const std::function<void(const std::map<std::string, DBStatus> &devicesMap)> &onComplete,
204         const Query &query, bool wait) = 0;
205 
206     // Check the integrity of this kvStore.
207     DB_API virtual DBStatus CheckIntegrity() const = 0;
208 
209     // Set an equal identifier for this database, After this called, send msg to the target will use this identifier
210     DB_API virtual DBStatus SetEqualIdentifier(const std::string &identifier,
211         const std::vector<std::string> &targets) = 0;
212 
213     // This API is not recommended. Before using this API, you need to understand the API usage rules.
214     // Set pushdatainterceptor. The interceptor works when send data.
215     DB_API virtual DBStatus SetPushDataInterceptor(const PushDataInterceptor &interceptor) = 0;
216 
217     // Register a subscriber query on peer devices. The data in the peer device meets the subscriber query condition
218     // will automatically push to the local device when it's changed.
219     DB_API virtual DBStatus SubscribeRemoteQuery(const std::vector<std::string> &devices,
220         const std::function<void(const std::map<std::string, DBStatus> &devicesMap)> &onComplete,
221         const Query &query, bool wait) = 0;
222 
223     // Unregister a subscriber query on peer devices.
224     DB_API virtual DBStatus UnSubscribeRemoteQuery(const std::vector<std::string> &devices,
225         const std::function<void(const std::map<std::string, DBStatus> &devicesMap)> &onComplete,
226         const Query &query, bool wait) = 0;
227 
228     // Remove all other device data synced from other remote devices.
229     DB_API virtual DBStatus RemoveDeviceData() = 0;
230 
231     // Get keys from the public zone of this store by key prefix.
232     // If 'keyPrefix' is empty, It would return all the keys in the zone.
233     DB_API virtual DBStatus GetKeys(const Key &keyPrefix, std::vector<Key> &keys) const = 0;
234 
235     // calculate full sync sync data size after Serialize;
236     // return 1M while sync data size is larger than 1M, otherwise return actualy size
237     DB_API virtual size_t GetSyncDataSize(const std::string &device) const = 0;
238 
239     // update all key in sync_data which is not deleted data
240     DB_API virtual DBStatus UpdateKey(const UpdateKeyCallback &callback) = 0;
241 
242     // get full watermark by device which is not contain query watermark
243     // this api get watermark from cache which reload in get kv store
244     DB_API virtual std::pair<DBStatus, WatermarkInfo> GetWatermarkInfo(const std::string &device) = 0;
245 
246     // sync with cloud
247     DB_API virtual DBStatus Sync(const CloudSyncOption &option, const SyncProcessCallback &onProcess) = 0;
248 
249     // set cloud db with user
250     DB_API virtual DBStatus SetCloudDB(const std::map<std::string, std::shared_ptr<ICloudDb>> &cloudDBs) = 0;
251 
252     // set cloud schema
253     DB_API virtual DBStatus SetCloudDbSchema(const std::map<std::string, DataBaseSchema> &schema) = 0;
254 
255     // remove device data for cloud
256     DB_API virtual DBStatus RemoveDeviceData(const std::string &device, ClearMode mode) = 0;
257 
258     // remove device data for cloud and user
259     DB_API virtual DBStatus RemoveDeviceData(const std::string &device, const std::string &user, ClearMode mode) = 0;
260 
261     // get all sync task count
262     DB_API virtual int32_t GetTaskCount() = 0;
263 
264     // set generate cloud version callback
265     DB_API virtual void SetGenCloudVersionCallback(const GenerateCloudVersionCallback &callback) = 0;
266 
267     // get cloud version by device
268     DB_API virtual std::pair<DBStatus, std::map<std::string, std::string>> GetCloudVersion(
269         const std::string &device) = 0;
270 
271     // This API is not recommended. Before using this API, you need to understand the API usage rules.
272     // The interceptor works when receive data.
273     DB_API virtual DBStatus SetReceiveDataInterceptor(const DataInterceptor &interceptor) = 0;
274 
275     // set the config for cloud sync task
276     DB_API virtual DBStatus SetCloudSyncConfig(const CloudSyncConfig &config) = 0;
277 
278     // Get Entries by the device(uuid) in sync_data.
279     // If device is empty, it would return all the entries which was written by local device.
280     DB_API virtual DBStatus GetDeviceEntries(const std::string &device, std::vector<Entry> &entries) const = 0;
281 
GetDatabaseStatus()282     DB_API virtual DatabaseStatus GetDatabaseStatus() const
283     {
284         return {};
285     }
286 };
287 } // namespace DistributedDB
288 
289 #endif // KV_STORE_NB_DELEGATE_H
290