refactor extensions: config -> manifest

1 files changed, 149 insertions, 31 deletions

diff --git a/src/include/taler_extensions.h b/src/include/taler_extensions.h
index f81b9653..646d5a84 100644
--- a/src/include/taler_extensions.h
+++ b/src/include/taler_extensions.h
@@ -31,11 +31,11 @@
 
 enum TALER_Extension_Type
 {
-  TALER_Extension_AgeRestriction = 0,
-  TALER_Extension_PolicyRefund   = 1,
-  TALER_Extension_PolicyAuction  = 2,
-  TALER_Extension_PolicyEscrow   = 3,
-  TALER_Extension_MaxPredefined  = 4 // Must be last of the predefined
+  TALER_Extension_AgeRestriction             = 0,
+  TALER_Extension_PolicyMerchantRefund       = 1,
+  TALER_Extension_PolicyBrandtVickeryAuction = 2,
+  TALER_Extension_PolicyEscrowedPayment      = 3,
+  TALER_Extension_MaxPredefined              = 4 // Must be last of the predefined
 };
 
 
@@ -52,42 +52,149 @@ struct TALER_Extensions
 /*
  * @brief Represents the implementation of an extension.
  *
- * TODO: add documentation
+ * An "Extension" is an optional feature for the Exchange.
+ * There are only two types of extensions:
+ *
+ * a) Age restriction:  This is a special feature that directly interacts with
+ * denominations and coins, but is not define policies during deposits, see b).
+ * The implementation of this extension doesn't have to implement any of the
+ * http- or depost-handlers in the struct.
+ *
+ * b) Policies for deposits:  These are extensions that define policies (such
+ * as refund, escrow or auctions) for deposit requests.  These extensions have
+ * to implement at least the deposit- and post-http-handler in the struct to be
+ * functional.
+ *
+ * In addition to the handlers defined in this struct, an extension must also
+ * be a plugin in the GNUNET_Plugin sense.  That is, it must implement the
+ * functions
+ *    1: (void *ext)libtaler_extension_<name>_init(void *cfg)
+ * and
+ *    2: (void *)libtaler_extension_<name>_done(void *)
+ *
+ * In 1:, the input will be the GNUNET_CONFIGURATION_Handle to the TALER
+ * configuration and the output must be the struct TALER_Extension * on
+ * success, NULL otherwise.
+ *
+ * In 2:, no arguments are passed and NULL is expected to be returned.
  */
 struct TALER_Extension
 {
+  /**
+   * Type of the extension.  Only one extension of a type can be loaded
+   * at any time.
+   */
   enum TALER_Extension_Type type;
+
+  /**
+   * The name of the extension, must be unique among all loaded extensions.  It
+   * is used in URLs for /extension/$NAME as well.
+   */
   char *name;
+
+  /**
+   * Criticality of the extension.  It has the same semantics as "critical" has
+   * for extensions in X.509:
+   * - if "true", the client must "understand" the extension before proceeding,
+   * - if "false", clients can safely skip extensions they do not understand.
+   * (see https://datatracker.ietf.org/doc/html/rfc5280#section-4.2)
+   */
   bool critical;
+
+  /**
+   * Version of the extension must be provided in Taler's protocol verison ranges notation, see
+   * https://docs.taler.net/core/api-common.html#protocol-version-ranges
+   */
   char *version;
-  void *config;
+
+  /**
+   * If the extension is marked as enabled, it will be listed in the
+   * "extensions" field in the "/keys" response.
+   */
   bool enabled;
-  bool has_config; /* some extension might not have a configuration */
-  json_t *config_json;
 
-  void (*disable)(struct TALER_Extension *ext);
+  /**
+   * Opaque (public) configuration object, set by the extension.
+   */
+  void *config;
 
-  enum GNUNET_GenericReturnValue (*test_json_config)(
-    const json_t *config);
 
-  enum GNUNET_GenericReturnValue (*load_json_config)(
+  /**
+   * @brief Handler to to disable the extension.
+   *
+   * @param ext The current extension object
+   */
+  void (*disable)(struct TALER_Extension *ext);
+
+  /**
+   * @brief Handler to read an extension-specific configuration in JSON
+   * encoding and enable the extension.  Must be implemented by the extension.
+   *
+   * @param ext The extension object. If NULL, the configuration will only be checked.
+   * @param config A JSON blob
+   * @return GNUNET_OK if the json was a valid configuration for the extension.
+   */
+  enum GNUNET_GenericReturnValue (*load_config)(
     struct TALER_Extension *ext,
     json_t *config);
 
-  json_t *(*config_to_json)(
+  /**
+   * @brief Handler to return the manifest of the extension in JSON encoding.
+   *
+   * See
+   * https://docs.taler.net/design-documents/006-extensions.html#tsref-type-Extension
+   * for the definition.
+   *
+   * @param ext The extension object
+   * @return The JSON encoding of the extension, if enabled, NULL otherwise.
+   */
+  json_t *(*manifest)(
     const struct TALER_Extension *ext);
 
+  /**
+   * @brief Handler for /{batch}-deposit requests.  Can be NULL.
+   *
+   * When a deposit request refers to this extension in its policy
+   * (see https://docs.taler.net/core/api-exchange.html#deposit), this handler
+   * will be called during the deposit operation.
+   *
+   * @param[in] input The policy/extension specific data, provided by the client in
+   * the policy-field of the deposit request.
+   * @param[out] output Potential output by the extension to be provided to the
+   * client as part of the response to the deposit request.  Can be NULL.
+   * @return GNUNET_OK if the data was accepted by the extension.
+   */
+  enum GNUNET_GenericReturnValue (*deposit_handler)(
+    json_t *input,
+    json_t **output);
+
+  /**
+   * @brief Handler for POST-requests to the /policy/$name endpoint. Can be NULL.
+   *
+   * @param connection The current connection
+   * @param root The JSON body from the request
+   * @param args Additional query parameters of the request.
+   * @return MDH result
+   */
   MHD_RESULT (*http_post_handler)(
     struct MHD_Connection *connection,
     const json_t *root,
     const char *const args[]);
 
+  /**
+   * @brief Handler for GET-requests to the /policy/$name endpoint.  Can be NULL.
+   *
+   * @param connection The current connection
+   * @param root The JSON body from the request
+   * @param args Additional query parameters of the request.
+   * @return MDH result
+   */
   MHD_RESULT (*http_get_handler)(
     struct MHD_Connection *connection,
     const char *const args[]);
-
 };
 
+
 /**
  * Generic functions for extensions
  */
@@ -101,39 +208,38 @@ struct TALER_Extension
  *         or any particular configuration couldn't be parsed.
  */
 enum GNUNET_GenericReturnValue
-TALER_extensions_load (
+TALER_extensions_init (
   const struct GNUNET_CONFIGURATION_Handle *cfg);
 
 /*
- * @brief Checks the given obj to be a valid extension object and fill the
- * fields accordingly.
+ * @brief Parses a given JSON object as an extension manifest.
  *
- * @param[in] obj Object to verify is a valid extension
+ * @param[in] obj JSON object to parse as an extension manifest
  * @param{out] critical will be set to 1 if the extension is critical according to obj
  * @param[out] version will be set to the version of the extension according to obj
  * @param[out] config will be set to the configuration of the extension according to obj
  * @return OK on success, Error otherwise
  */
 enum GNUNET_GenericReturnValue
-TALER_extensions_is_json_config (
+TALER_extensions_parse_manifest (
   json_t *obj,
   int *critical,
   const char **version,
   json_t **config);
 
 /*
- * @brief Sets the configuration of the extensions from a given JSON object.
+ * @brief Loads extensions according to the manifests.
  *
- * The JSON object must be of type ExchangeKeysResponse as described in
- * https://docs.taler.net/design-documents/006-extensions.html#exchange
+ * The JSON object must be of type ExtensionsManifestsResponse as described
+ * in https://docs.taler.net/design-documents/006-extensions.html#exchange
  *
- * @param cfg JSON object containing the configuration for all extensions
+ * @param cfg JSON object containing the manifests for all extensions
  * @return #GNUNET_OK on success, #GNUNET_SYSERR if unknown extensions were
  *  found or any particular configuration couldn't be parsed.
  */
 enum GNUNET_GenericReturnValue
-TALER_extensions_load_json_config (
-  json_t *cfg);
+TALER_extensions_load_manifests (
+  json_t *manifests);
 
 /*
  * @brief Returns the head of the linked list of extensions.
@@ -186,7 +292,7 @@ TALER_extensions_is_enabled (
  * Verify the signature of a given JSON object for extensions with the master
  * key of the exchange.
  *
- * The JSON object must be of type ExchangeKeysResponse as described in
+ * The JSON object must be of type ExtensionsManifestsResponse as described in
  * https://docs.taler.net/design-documents/006-extensions.html#exchange
  *
  * @param extensions JSON object with the extension configuration
@@ -196,8 +302,8 @@ TALER_extensions_is_enabled (
  * and GNUNET_NO if the signature couldn't be verified.
  */
 enum GNUNET_GenericReturnValue
-TALER_extensions_verify_json_config_signature (
-  json_t *extensions,
+TALER_extensions_verify_manifests_signature (
+  json_t *manifests,
   struct TALER_MasterSignatureP *extensions_sig,
   struct TALER_MasterPublicKeyP *master_pub);
 
@@ -207,6 +313,8 @@ TALER_extensions_verify_json_config_signature (
  *
  * This extension is special insofar as it directly interacts with coins and
  * denominations.
+ *
+ * At the same time, it doesn't implement and http- or deposit-handlers.
  */
 
 #define TALER_EXTENSION_SECTION_AGE_RESTRICTION (TALER_EXTENSION_SECTION_PREFIX  \
@@ -228,7 +336,6 @@ TALER_extensions_verify_json_config_signature (
  */
 struct TALER_AgeRestrictionConfig
 {
-  bool enabled;
   struct TALER_AgeMask mask;
   uint8_t num_groups;
 };
@@ -260,7 +367,18 @@ TALER_extensions_get_age_restriction_mask ();
 
 
 /*
- * TODO: Add Peer2Peer Extension
+ * ================================
+ * Brandt-Vickrey Auctions
+ * ================================
+ */
+/*
+ * @brief Configuration for Brandt-Vickrey auctions
  */
+struct TALER_BrandtVickreyAuction
+{
+  uint16_t max_bidders;
+  uint16_t max_prices;
+  struct TALER_Amount auction_fee;
+};
 
 #endif