path: root/src/backenddb/merchant-0004.sql

--
-- This file is part of TALER
-- Copyright (C) 2021 Taler Systems SA
--
-- TALER is free software; you can redistribute it and/or modify it under the
-- terms of the GNU General Public License as published by the Free Software
-- Foundation; either version 3, or (at your option) any later version.
--
-- TALER is distributed in the hope that it will be useful, but WITHOUT ANY
-- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
-- A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
--
-- You should have received a copy of the GNU General Public License along with
-- TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
--

*/
/**
 * @file merchant-004.sql
 * @brief database helper functions for postgres used by the merchant and funtion for plugin_merchantdb_postgres.c
 * @author Priscilla Huang
 */

-- Everything in one big transaction
BEGIN;

-- Check patch versioning is in place.
SELECT _v.register_patch('merchant-0004', NULL, NULL);

SET search_path TO merchant;

-- create table here!

CREATE TABLE IF NOT EXISTS merchant_template
  (template_serial BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY
  ,merchant_serial BIGINT NOT NULL
    REFERENCES merchant_instances (merchant_serial) ON DELETE CASCADE
  ,template_id VARCHAR NOT NULL
  ,template_description VARCHAR NOT NULL
  ,image BYTEA
  ,template_contract VARCHAR NOT NULL -- in JSON format
  ,UNIQUE (merchant_serial, template_id)
  );
COMMENT ON TABLE merchant_template
  IS 'template used by the merchant (may be incomplete, frontend can override)';
COMMENT ON COLUMN merchant_template.template_description
  IS 'Human-readable template description';
COMMENT ON COLUMN merchant_template.image
  IS 'NOT NULL, but can be 0 bytes; must contain an ImageDataUrl';
COMMENT ON COLUMN merchant_template.template_contract
  IS 'The template contract will contains some additional information.'


-- C CODE

/**
 * Delete information about a template.
 *
 * @param cls closure
 * @param instance_id instance to delete product of
 * @param template_id template to delete
 * @return DB status code, #GNUNET_DB_STATUS_SUCCESS_NO_RESULTS
 *           if template unknow.
 */
static enum GNUNET_DB_QueryStatus
postgres_delete_template (void *cls,
                         const char *instance_id,
                         const char *template_id)
{
  struct PostgresClosure *pg = cls;
  struct GNUNET_PQ_QueryParam params[] = {
    GNUNET_PQ_query_param_string (instance_id),
    GNUNET_PQ_query_param_string (template_id),
    GNUNET_PQ_query_param_end
  };

  check_connection (pg);
  return GNUNET_PQ_eval_prepared_non_select (pg->conn,
                                             "delete_template",
                                             params);
}

/**
 * Insert details about a particular template.
 *
 * @param cls closure
 * @param instance_id instance to insert template for
 * @param template_id template identifier of template to insert
 * @param pd the template details to insert
 * @return database result code
 */
static enum GNUNET_DB_QueryStatus
postgres_insert_template (void *cls,
                         const char *instance_id,
                         const char *template_id,
                         const struct TALER_MERCHANTDB_TemplateDetails *pd)
{
  struct PostgresClosure *pg = cls;
  struct GNUNET_PQ_QueryParam params[] = {
    GNUNET_PQ_query_param_string (instance_id),
    GNUNET_PQ_query_param_string (template_id),
    GNUNET_PQ_query_param_string (pd->template_description),
    GNUNET_PQ_query_param_string (pd->image),
    GNUNET_PQ_query_param_string (pd->template_contract),
    GNUNET_PQ_query_param_end

  };

  check_connection (pg);
  return GNUNET_PQ_eval_prepared_non_select (pg->conn,
                                             "insert_template",
                                             params);
}

/**
 * Update details about a particular template.
 *
 * @param cls closure
 * @param instance_id instance to update template for
 * @param template_id template to update
 * @param pd update to the template details on success, can be NULL
 *             (in that case we only want to check if the template exists)
 * @return database result code, #GNUNET_DB_STATUS_SUCCESS_NO_RESULTS if the template
 *         does not yet exist.
 */
static enum GNUNET_DB_QueryStatus
postgres_update_template (void *cls,
                         const char *instance_id,
                         const char *template_id,
                         const struct TALER_MERCHANTDB_TemplateDetails *pd)
{
  struct PostgresClosure *pg = cls;
  struct GNUNET_PQ_QueryParam params[] = {
    GNUNET_PQ_query_param_string (instance_id),
    GNUNET_PQ_query_param_string (template_id),
    GNUNET_PQ_query_param_string (pd->template_description),
    GNUNET_PQ_query_param_string (pd->image),
    GNUNET_PQ_query_param_string (pd->template_contract),
    GNUNET_PQ_query_param_end
  };

  {
    GNUNET_break (0);
    return GNUNET_DB_STATUS_HARD_ERROR;
  }
  check_connection (pg);
  return GNUNET_PQ_eval_prepared_non_select (pg->conn,
                                             "update_template",
                                             params);
}




/**
 * Context used for postgres_lookup_template().
 */
struct LookupTemplateContext
{
  /**
   * Function to call with the results.
   */
  TALER_MERCHANTDB_TemplateCallback cb;

  /**
   * Closure for @a cb.
   */
  void *cb_cls;

  /**
   * Did database result extraction fail?
   */
  bool extract_failed;
};


/**
 * Function to be called with the results of a SELECT statement
 * that has returned @a num_results results about template.
 *
 * @param[in,out] cls of type `struct LookupTemplateContext *`
 * @param result the postgres result
 * @param num_results the number of results in @a result
 */
static void
lookup_templates_cb (void *cls,
                    PGresult *result,
                    unsigned int num_results)
{
  struct LookupTemplateContext *tlc = cls;

  for (unsigned int i = 0; i < num_results; i++)
  {
    char *template_id;
    struct GNUNET_PQ_ResultSpec rs[] = {
      GNUNET_PQ_result_spec_string ("template_id",
                                    &template_id),
      GNUNET_PQ_result_spec_string ("template_description",
                                   &template_description),
      GNUNET_PQ_result_spec_end
    };

    if (GNUNET_OK !=
        GNUNET_PQ_extract_result (result,
                                  rs,
                                  i))
    {
      GNUNET_break (0);
      tlc->extract_failed = true;
      return;
    }
    tlc->cb (tlc->cb_cls,
             template_id);
    GNUNET_PQ_cleanup_result (rs);
  }
}


/**
 * Lookup all of the templates the given instance has configured.
 *
 * @param cls closure
 * @param instance_id instance to lookup template for
 * @param cb function to call on all template found
 * @param cb_cls closure for @a cb
 * @return database result code
 */
static enum GNUNET_DB_QueryStatus
postgres_lookup_templates (void *cls,
                          const char *instance_id,
                          TALER_MERCHANTDB_TemplateCallback cb,
                          void *cb_cls)
{
  struct PostgresClosure *pg = cls;
  struct LookupTemplateContext tlc = {
    .cb = cb,
    .cb_cls = cb_cls,
    /* Can be overwritten by the lookup_template_cb */
    .extract_failed = false,
  };
  struct GNUNET_PQ_QueryParam params[] = {
    GNUNET_PQ_query_param_string (instance_id),
    GNUNET_PQ_query_param_end
  };
  enum GNUNET_DB_QueryStatus qs;

  check_connection (pg);
  qs = GNUNET_PQ_eval_prepared_multi_select (pg->conn,
                                             "lookup_templates",
                                             params,
                                             &lookup_templates_cb,
                                             &tlc);
  /* If there was an error inside lookup_template_cb, return a hard error. */
  if (tlc.extract_failed)
    return GNUNET_DB_STATUS_HARD_ERROR;
  return qs;
}

/**
 * Lookup details about a particular template.
 *
 * @param cls closure
 * @param instance_id instance to lookup template for
 * @param template_id template to lookup
 * @param[out] pd set to the template details on success, can be NULL
 *             (in that case we only want to check if the template exists)
 * @return database result code
 */
static enum GNUNET_DB_QueryStatus
postgres_lookup_template (void *cls,
                         const char *instance_id,
                         const char *template_id,
                         struct TALER_MERCHANTDB_TemplateDetails *pd)
{
  struct PostgresClosure *pg = cls;
  struct GNUNET_PQ_QueryParam params[] = {
    GNUNET_PQ_query_param_string (instance_id),
    GNUNET_PQ_query_param_string (template_id),
    GNUNET_PQ_query_param_end
  };

  if (NULL == pd)
  {
    struct GNUNET_PQ_ResultSpec rs_null[] = {
      GNUNET_PQ_result_spec_end
    };

    check_connection (pg);
    return GNUNET_PQ_eval_prepared_singleton_select (pg->conn,
                                                     "lookup_template",
                                                     params,
                                                     rs_null);
  }
  else
  {
    struct GNUNET_PQ_ResultSpec rs[] = {
      GNUNET_PQ_result_spec_string ("template_description",
                                    &pd->template_description),
      GNUNET_PQ_result_spec_string ("image",
                                    &pd->image),
      GNUNET_PQ_result_spec_string ("template_contract",
                                    &pd->template_contract),
      GNUNET_PQ_result_spec_end
    };

    check_connection (pg);
    return GNUNET_PQ_eval_prepared_singleton_select (pg->conn,
                                                     "lookup_template",
                                                     params,
                                                     rs);
  }
}



------------------------------API--------------------------------

/**
 * Typically called by `lookup_templates`.
 *
 * @param cls a `json_t *` JSON array to build
 * @param template_id ID of the template
 */
typedef void
(*TALER_MERCHANTDB_TemplatesCallback)(void *cls,
                                     const char *template_id,
                                     const char *template_description);


/**
 * Details about a template.
 */
struct TALER_MERCHANTDB_TemplateDetails
{
  /**
   * Description of the template.
   */
  const char *template_description;

  /**
   * Base64-encoded product image, or NULL.
   */
  const char *image;

  /**
   * In this template contract, we can have additional information.
   */
  const json_t *template_contract;
};



/**
 * Lookup all of the templates the given instance has configured.
 *
 * @param cls closure
 * @param instance_id instance to lookup template for
 * @param cb function to call on all template found
 * @param cb_cls closure for @a cb
 * @return database result code
 */
enum GNUNET_DB_QueryStatus
(*lookup_templates) (void *cls,
                          const char *instance_id,
                          TALER_MERCHANTDB_TemplateCallback cb,
                          void *cb_cls);


/**
 * Lookup details about a particular template.
 *
 * @param cls closure
 * @param instance_id instance to lookup template for
 * @param template_id template to lookup
 * @param[out] pd set to the template details on success, can be NULL
 *             (in that case we only want to check if the template exists)
 * @return database result code
 */
enum GNUNET_DB_QueryStatus
(*lookup_template) (void *cls,
                         const char *instance_id,
                         const char *template_id,
                         struct TALER_MERCHANTDB_TemplateDetails *pd);

/**
 * Delete information about a template.
 *
 * @param cls closure
 * @param instance_id instance to delete product of
 * @param template_id template to delete
 * @return DB status code, #GNUNET_DB_STATUS_SUCCESS_NO_RESULTS
 *           if template unknow.
 */
enum GNUNET_DB_QueryStatus
(*delete_template) (void *cls,
                         const char *instance_id,
                         const char *template_id);



/**
 * Insert details about a particular template.
 *
 * @param cls closure
 * @param instance_id instance to insert template for
 * @param template_id template identifier of template to insert
 * @param pd the template details to insert
 * @return database result code
 */
enum GNUNET_DB_QueryStatus
(*insert_template) (void *cls,
                         const char *instance_id,
                         const char *template_id,
                         const struct TALER_MERCHANTDB_TemplateDetails *pd);



/**
 * Update details about a particular template.
 *
 * @param cls closure
 * @param instance_id instance to update template for
 * @param template_id template to update
 * @param pd update to the template details on success, can be NULL
 *             (in that case we only want to check if the template exists)
 * @return database result code, #GNUNET_DB_STATUS_SUCCESS_NO_RESULTS if the template
 *         does not yet exist.
 */

enum GNUNET_DB_QueryStatus
(*update_template) (void *cls,
                         const char *instance_id,
                         const char *template_id,
                         const struct TALER_MERCHANTDB_TemplateDetails *pd)