taler-merchant-httpd_helper.h (12213B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2021-2023 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero 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 Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file taler-merchant-httpd_helper.h 18 * @brief helpers for shared logic 19 * @author Florian Dold 20 * @author Benedikt Mueller 21 * @author Christian Grothoff 22 */ 23 #ifndef TALER_MERCHANT_HTTPD_HELPER_H 24 #define TALER_MERCHANT_HTTPD_HELPER_H 25 26 #define TMH_MAX_FRACTIONAL_PRECISION_LEVEL 6 27 28 29 #include "taler-merchant-httpd.h" 30 #include "taler/taler_merchant_util.h" 31 32 /** 33 * check @a accounts for well-formedness 34 * 35 * @param accounts JSON array of merchant accounts (presumably) 36 * @return true if they are all valid accounts 37 */ 38 bool 39 TMH_accounts_array_valid (const json_t *accounts); 40 41 42 /** 43 * Check if @a location is a valid Location object in the sense of Taler's API 44 * definition. 45 * 46 * @param location object to check 47 * @return true if @a location is an object 48 * representing a Location. 49 */ 50 bool 51 TMH_location_object_valid (const json_t *location); 52 53 54 /** 55 * Check if @a products is an array of valid Product(s) in the sense of 56 * Taler's API definition. 57 * 58 * @param products array to check 59 * @return true if @a products is an array and all 60 * entries are valid Products. 61 */ 62 bool 63 TMH_products_array_valid (const json_t *products); 64 65 66 /** 67 * Parse decimal quantity expressed as string for request handling. 68 * 69 * @param value string to parse 70 * @param[out] integer_part result integer component 71 * @param[out] fractional_part result fractional component (0..MERCHANT_UNIT_FRAC_BASE-1) 72 * @return #GNUNET_OK on success, #GNUNET_SYSERR on validation failure 73 */ 74 enum GNUNET_GenericReturnValue 75 TMH_parse_fractional_string (const char *value, 76 int64_t *integer_part, 77 uint32_t *fractional_part); 78 79 /** 80 * Check that no two prices use the same currency. 81 * 82 * @param prices price list to check 83 * @param prices_len length of @a prices 84 * @return #GNUNET_OK if unique, #GNUNET_SYSERR otherwise 85 */ 86 enum GNUNET_GenericReturnValue 87 TMH_validate_unit_price_array (const struct TALER_Amount *prices, 88 size_t prices_len); 89 90 91 /** 92 * Set of category IDs. 93 */ 94 struct TMH_CategorySet 95 { 96 /** 97 * Category IDs. 98 */ 99 uint64_t *ids; 100 101 /** 102 * Number of entries in @e ids. 103 */ 104 unsigned int len; 105 }; 106 107 /** 108 * Set of unit identifiers. 109 */ 110 struct TMH_UnitSet 111 { 112 /** 113 * Unit identifiers. 114 */ 115 char **units; 116 117 /** 118 * Number of entries in @e units. 119 */ 120 unsigned int len; 121 }; 122 /** 123 * Check if a category set already contains a given ID. 124 * 125 * @param set category set 126 * @param id category id 127 * @return true if present 128 */ 129 bool 130 TMH_category_set_contains (const struct TMH_CategorySet *set, 131 uint64_t id); 132 133 /** 134 * Add a category ID to a set if not already present. 135 * 136 * @param set category set 137 * @param id category id 138 */ 139 void 140 TMH_category_set_add (struct TMH_CategorySet *set, 141 uint64_t id); 142 143 /** 144 * Check if a unit set already contains a given unit. 145 * 146 * @param set unit set 147 * @param unit unit identifier 148 * @return true if present 149 */ 150 bool 151 TMH_unit_set_contains (const struct TMH_UnitSet *set, 152 const char *unit); 153 154 /** 155 * Add a unit identifier to a set if not already present. 156 * 157 * @param set unit set 158 * @param unit unit identifier 159 */ 160 void 161 TMH_unit_set_add (struct TMH_UnitSet *set, 162 const char *unit); 163 164 /** 165 * Clear a unit set and free its contents. 166 * 167 * @param set unit set to clear 168 */ 169 void 170 TMH_unit_set_clear (struct TMH_UnitSet *set); 171 172 173 /** 174 * Lookup the defaults for @a unit within @a mi and fall back to sane 175 * values (disallow fractional quantities, zero precision) if no data 176 * is available. 177 * 178 * @param mi merchant instance whose defaults should be consulted (must not be NULL) 179 * @param unit textual unit name (must not be NULL or empty) 180 * @param allow_fractional updated with whether fractional quantities are allowed (must not be NULL) 181 * @param precision_level updated with the supported precision (must not be NULL) 182 */ 183 void 184 TMH_quantity_defaults_from_unit (const struct TMH_MerchantInstance *mi, 185 const char *unit, 186 bool *allow_fractional, 187 uint32_t *precision_level); 188 189 /** 190 * Query the database for precision defaults tied to @a unit within 191 * @a mi. Returns #GNUNET_OK even if no unit information exists, in 192 * which case the out-parameters remain at their implicit defaults. 193 * 194 * @param mi merchant instance whose unit table is inspected (must not be NULL) 195 * @param unit textual unit name (must not be NULL or empty) 196 * @param allow_fractional updated with whether fractional quantities are allowed (must not be NULL) 197 * @param precision_level updated with the supported precision (must not be NULL) 198 * @return #GNUNET_OK on success, #GNUNET_SYSERR on database failure 199 */ 200 enum GNUNET_GenericReturnValue 201 TMH_unit_defaults_for_instance (const struct TMH_MerchantInstance *mi, 202 const char *unit, 203 bool *allow_fractional, 204 uint32_t *precision_level); 205 206 207 /** 208 * Setup new wire method for the given @ payto_uri. 209 * 210 * @param payto_uri already validated payto URI 211 * @param credit_facade_url where to download credit information for this account (can be NULL) 212 * @param credit_facade_credentials credentials for the @a credit_facade_url 213 * @return new wire method object, never fails 214 */ 215 struct TMH_WireMethod * 216 TMH_setup_wire_account ( 217 struct TALER_FullPayto payto_uri, 218 const char *credit_facade_url, 219 const json_t *credit_facade_credentials); 220 221 222 /** 223 * Test if JSON spec @a account for a wire method is equal to the given @a wm. 224 * 225 * @param account JSON spec for a merchant account 226 * @param wm known wire method 227 * @return #GNUNET_YES if both specifications are equal 228 * #GNUNET_NO if the specifications are for 229 * the same account but differ in the credit facade 230 * #GNUNET_SYSERR if the specs are for different accounts 231 * or if @a account is malformed 232 */ 233 enum GNUNET_GenericReturnValue 234 TMH_cmp_wire_account ( 235 const json_t *account, 236 const struct TMH_WireMethod *wm); 237 238 239 /** 240 * Check that the provided authentication configuration 241 * is valid. 242 * 243 * @param connection connection to use for returning errors 244 * @param jauth JSON with authentication data 245 * @param[out] auth_token set to the authentication token 246 * @return #GNUNET_OK on success, 247 * #GNUNET_NO if an error was returned on @a connection 248 * #GNUNET_SYSERR if we failed to return an error on @a connection 249 */ 250 enum GNUNET_GenericReturnValue 251 TMH_check_auth_config (struct MHD_Connection *connection, 252 const json_t *jauth, 253 const char **auth_token); 254 255 256 /** 257 * Generate binary UUID from client-provided UUID-string. 258 * 259 * @param uuids string intpu 260 * @param[out] uuid set to binary UUID 261 */ 262 void 263 TMH_uuid_from_string (const char *uuids, 264 struct GNUNET_Uuid *uuid); 265 266 267 /** 268 * Initializes a buffer with 269 * the ``http[s]://$HOST/[$PATH/][instances/$INSTANCE/]`` 270 * string using $HOST and $PATH from @a connection. 271 * 272 * @param[in] connection connection to base the construction on 273 * @param instance instance to set, NULL for none 274 * @param[out] buf buffer to initialize 275 * @return #GNUNET_OK on success 276 */ 277 enum GNUNET_GenericReturnValue 278 TMH_base_url_by_connection (struct MHD_Connection *connection, 279 const char *instance, 280 struct GNUNET_Buffer *buf); 281 282 283 /** 284 * Initializes a buffer with 285 * the ``taler[+http]://$METHOD/$HOST/[instances/$INSTANCE/]`` 286 * string using $HOST from @a connection. 287 * 288 * @param[in] connection connection to base the construction on 289 * @param method taler-URI method to inject 290 * @param instance instance to set, NULL for none 291 * @param[out] buf buffer to initialize 292 * @return #GNUNET_OK on success 293 */ 294 enum GNUNET_GenericReturnValue 295 TMH_taler_uri_by_connection (struct MHD_Connection *connection, 296 const char *method, 297 const char *instance, 298 struct GNUNET_Buffer *buf); 299 300 301 /** 302 * Create a taler://pay/ URI for the given @a con and @a order_id 303 * and @a session_id and @a instance_id. 304 * 305 * @param con HTTP connection 306 * @param order_id the order id 307 * @param session_id session, may be NULL 308 * @param instance_id instance, may be "default" 309 * @param claim_token claim token for the order, may be NULL 310 * @return corresponding taler://pay/ URI, or NULL on missing "host" 311 */ 312 char * 313 TMH_make_taler_pay_uri (struct MHD_Connection *con, 314 const char *order_id, 315 const char *session_id, 316 const char *instance_id, 317 struct TALER_ClaimTokenP *claim_token); 318 319 /** 320 * Create a http(s) URL for the given @a con and @a order_id 321 * and @a instance_id to display the /orders/{order_id} page. 322 * 323 * @param con HTTP connection 324 * @param order_id the order id 325 * @param session_id session, may be NULL 326 * @param instance_id instance, may be "default" 327 * @param claim_token claim token for the order, may be NULL 328 * @param h_contract contract hash for authentication, may be NULL 329 * @return corresponding http(s):// URL, or NULL on missing "host" 330 */ 331 char * 332 TMH_make_order_status_url (struct MHD_Connection *con, 333 const char *order_id, 334 const char *session_id, 335 const char *instance_id, 336 struct TALER_ClaimTokenP *claim_token, 337 struct TALER_PrivateContractHashP *h_contract); 338 339 340 /** 341 * Put data from an exchange's HTTP response into 342 * a JSON reply 343 * 344 * @param hr a `TALER_EXCHANGE_HttpResponse` 345 */ 346 #define TMH_pack_exchange_reply(hr) \ 347 GNUNET_JSON_pack_uint64 ("exchange_code", (hr)->ec), \ 348 GNUNET_JSON_pack_uint64 ("exchange_http_status", (hr)->http_status), \ 349 GNUNET_JSON_pack_uint64 ("exchange_ec", (hr)->ec), /* LEGACY */ \ 350 GNUNET_JSON_pack_uint64 ("exchange_hc", (hr)->http_status), /* LEGACY */ \ 351 GNUNET_JSON_pack_allow_null ( \ 352 GNUNET_JSON_pack_object_incref ("exchange_reply", (json_t *) (hr)-> \ 353 reply)) 354 355 356 /** 357 * TMH_trigger_webhook is a function that need to be use when someone 358 * pay. Merchant need to have a notification. 359 * 360 * @param instance that we need to send the webhook as a notification 361 * @param event of the webhook 362 * @param args argument of the function 363 */ 364 enum GNUNET_DB_QueryStatus 365 TMH_trigger_webhook (const char *instance, 366 const char *action, 367 const json_t *args); 368 369 370 /** 371 * Return JSON array with all of the exchange accounts 372 * that support the given @a wire_method. 373 * 374 * @param master_pub master public key to match exchange by 375 * @param wire_method NULL for any 376 * @return JSON array with information about all matching accounts 377 */ 378 json_t * 379 TMH_exchange_accounts_by_method ( 380 const struct TALER_MasterPublicKeyP *master_pub, 381 const char *wire_method); 382 383 /** 384 * Check validity of login @a token for the given @a instance_id. 385 * 386 * @param token the login token given in the request 387 * @param instance_id the instance the login is to be checked against 388 * @param[out] as set to scope of the token if it is valid 389 * @return TALER_EC_NONE on success 390 */ 391 enum TALER_ErrorCode 392 TMH_check_token (const char *token, 393 const char *instance_id, 394 enum TMH_AuthScope *as); 395 396 #endif