sync_database_plugin.h (9721B)
1 /* 2 This file is part of GNU Taler 3 Copyright (C) 2019, 2021 Taler Systems SA 4 5 Taler is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Lesser General Public License as published by the Free Software 7 Foundation; either version 3, or (at your option) any later version. 8 9 Taler is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU General Public License for more details. 12 13 You should have received a copy of the GNU General Public License along with 14 Taler; see the file COPYING.GPL. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file include/sync_database_plugin.h 18 * @brief database access for Sync 19 * @author Christian Grothoff 20 */ 21 #ifndef SYNC_DATABASE_PLUGIN_H 22 #define SYNC_DATABASE_PLUGIN_H 23 24 #include <gnunet/gnunet_util_lib.h> 25 #include <gnunet/gnunet_db_lib.h> 26 #include "sync_service.h" 27 #include <jansson.h> 28 #include <taler/taler_util.h> 29 30 31 /** 32 * Possible status codes returned from the SYNC database. 33 */ 34 enum SYNC_DB_QueryStatus 35 { 36 /** 37 * Client claimed to be updating an existing backup, but we have none. 38 */ 39 SYNC_DB_OLD_BACKUP_MISSING = -5, 40 41 /** 42 * Update failed because the old backup hash does not match what we previously had in the DB. 43 */ 44 SYNC_DB_OLD_BACKUP_MISMATCH = -4, 45 46 /** 47 * Account is unpaid / does not exist. 48 */ 49 SYNC_DB_PAYMENT_REQUIRED = -3, 50 51 /** 52 * Hard database issue, retries futile. 53 */ 54 SYNC_DB_HARD_ERROR = -2, 55 56 /** 57 * Soft database error, retrying may help. 58 */ 59 SYNC_DB_SOFT_ERROR = -1, 60 61 /** 62 * Database succeeded, but no results. 63 */ 64 SYNC_DB_NO_RESULTS = 0, 65 66 /** 67 * Database succeeded, one change or result. 68 */ 69 SYNC_DB_ONE_RESULT = 1 70 }; 71 72 73 /** 74 * Function called on all pending payments for an account. 75 * 76 * @param cls closure 77 * @param timestamp for how long have we been waiting 78 * @param order_id order id in the backend 79 * @param token claim token, or NULL for none 80 * @param amount how much is the order for 81 */ 82 typedef void 83 (*SYNC_DB_PaymentPendingIterator)(void *cls, 84 struct GNUNET_TIME_Timestamp timestamp, 85 const char *order_id, 86 const struct TALER_ClaimTokenP *token, 87 const struct TALER_Amount *amount); 88 89 90 /** 91 * Handle to interact with the database. 92 * 93 * Functions ending with "_TR" run their OWN transaction scope 94 * and MUST NOT be called from within a transaction setup by the 95 * caller. Functions ending with "_NT" require the caller to 96 * setup a transaction scope. Functions without a suffix are 97 * simple, single SQL queries that MAY be used either way. 98 */ 99 struct SYNC_DatabasePlugin 100 { 101 102 /** 103 * Closure for all callbacks. 104 */ 105 void *cls; 106 107 /** 108 * Name of the library which generated this plugin. Set by the 109 * plugin loader. 110 */ 111 char *library_name; 112 113 /** 114 * Drop sync tables. Used for testcases. 115 * 116 * @param cls closure 117 * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure 118 */ 119 enum GNUNET_GenericReturnValue 120 (*drop_tables)(void *cls); 121 122 123 /** 124 * Create the necessary tables if they are not present 125 * 126 * @param cls the @e cls of this struct with the plugin-specific state 127 * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure 128 */ 129 enum GNUNET_GenericReturnValue 130 (*create_tables)(void *cls); 131 132 133 /** 134 * Do a pre-flight check that we are not in an uncommitted transaction. 135 * If we are, try to commit the previous transaction and output a warning. 136 * Does not return anything, as we will continue regardless of the outcome. 137 * 138 * @param cls the `struct PostgresClosure` with the plugin-specific state 139 * @return #GNUNET_OK if everything is fine 140 * #GNUNET_NO if a transaction was rolled back 141 * #GNUNET_SYSERR on hard errors 142 */ 143 enum GNUNET_GenericReturnValue 144 (*preflight)(void *cls); 145 146 147 /** 148 * Function called to perform "garbage collection" on the 149 * database, expiring records we no longer require. Deletes 150 * all user records that are not paid up (and by cascade deletes 151 * the associated recovery documents). Also deletes expired 152 * truth and financial records older than @a fin_expire. 153 * 154 * @param cls closure 155 * @param expire_backups backups older than the given time stamp should be garbage collected 156 * @param expire_pending_payments payments still pending from since before 157 * this value should be garbage collected 158 * @return transaction status 159 */ 160 enum GNUNET_DB_QueryStatus 161 (*gc)(void *cls, 162 struct GNUNET_TIME_Absolute expire, 163 struct GNUNET_TIME_Absolute expire_pending_payments); 164 165 166 /** 167 * Store backup. Only applicable for the FIRST backup under 168 * an @a account_pub. Use @e update_backup_TR to update an 169 * existing backup. 170 * 171 * @param cls closure 172 * @param account_pub account to store @a backup under 173 * @param account_sig signature affirming storage request 174 * @param backup_hash hash of @a backup 175 * @param backup_size number of bytes in @a backup 176 * @param backup raw data to backup 177 * @return transaction status 178 */ 179 enum SYNC_DB_QueryStatus 180 (*store_backup_TR)(void *cls, 181 const struct SYNC_AccountPublicKeyP *account_pub, 182 const struct SYNC_AccountSignatureP *account_sig, 183 const struct GNUNET_HashCode *backup_hash, 184 size_t backup_size, 185 const void *backup); 186 187 188 /** 189 * Store payment. Used to begin a payment, not indicative 190 * that the payment actually was made. (That is done 191 * when we increment the account's lifetime.) 192 * 193 * @param cls closure 194 * @param account_pub account to store @a backup under 195 * @param order_id order we created 196 * @param token claim token, or NULL for none 197 * @param amount how much we asked for 198 * @return transaction status 199 */ 200 enum SYNC_DB_QueryStatus 201 (*store_payment_TR)(void *cls, 202 const struct SYNC_AccountPublicKeyP *account_pub, 203 const char *order_id, 204 const struct TALER_ClaimTokenP *token, 205 const struct TALER_Amount *amount); 206 207 208 /** 209 * Lookup pending payments by account. 210 * 211 * @param cls closure 212 * @param account_pub account to look for pending payments under 213 * @param it iterator to call on all pending payments 214 * @param it_cls closure for @a it 215 * @return transaction status 216 */ 217 enum GNUNET_DB_QueryStatus 218 (*lookup_pending_payments_by_account_TR)(void *cls, 219 const struct 220 SYNC_AccountPublicKeyP *account_pub, 221 SYNC_DB_PaymentPendingIterator it, 222 void *it_cls); 223 224 /** 225 * Update backup. 226 * 227 * @param cls closure 228 * @param account_pub account to store @a backup under 229 * @param account_sig signature affirming storage request 230 * @param old_backup_hash hash of the previous backup (must match) 231 * @param backup_hash hash of @a backup 232 * @param backup_size number of bytes in @a backup 233 * @param backup raw data to backup 234 * @return transaction status 235 */ 236 enum SYNC_DB_QueryStatus 237 (*update_backup_TR)(void *cls, 238 const struct SYNC_AccountPublicKeyP *account_pub, 239 const struct GNUNET_HashCode *old_backup_hash, 240 const struct SYNC_AccountSignatureP *account_sig, 241 const struct GNUNET_HashCode *backup_hash, 242 size_t backup_size, 243 const void *backup); 244 245 246 /** 247 * Lookup an account and associated backup meta data. 248 * 249 * @param cls closure 250 * @param account_pub account to store @a backup under 251 * @param backup_hash[OUT] set to hash of @a backup 252 * @return transaction status 253 */ 254 enum SYNC_DB_QueryStatus 255 (*lookup_account_TR)(void *cls, 256 const struct SYNC_AccountPublicKeyP *account_pub, 257 struct GNUNET_HashCode *backup_hash); 258 259 260 /** 261 * Obtain backup. 262 * 263 * @param cls closure 264 * @param account_pub account to store @a backup under 265 * @param account_sig[OUT] set to signature affirming storage request 266 * @param prev_hash[OUT] set to hash of the previous @a backup (all zeros if none) 267 * @param backup_hash[OUT] set to hash of @a backup 268 * @param backup_size[OUT] set to number of bytes in @a backup 269 * @param backup[OUT] set to raw data to backup, caller MUST FREE 270 */ 271 enum SYNC_DB_QueryStatus 272 (*lookup_backup_TR)(void *cls, 273 const struct SYNC_AccountPublicKeyP *account_pub, 274 struct SYNC_AccountSignatureP *account_sig, 275 struct GNUNET_HashCode *prev_hash, 276 struct GNUNET_HashCode *backup_hash, 277 size_t *backup_size, 278 void **backup); 279 280 /** 281 * Increment account lifetime and mark the associated payment 282 * as successful. 283 * 284 * @param cls closure 285 * @param account_pub which account received a payment 286 * @param order_id order which was paid, must be unique and match pending payment 287 * @param lifetime for how long is the account now paid (increment) 288 * @return transaction status 289 */ 290 enum SYNC_DB_QueryStatus 291 (*increment_lifetime_TR)(void *cls, 292 const struct SYNC_AccountPublicKeyP *account_pub, 293 const char *order_id, 294 struct GNUNET_TIME_Relative lifetime); 295 296 }; 297 #endif