[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] [taler-exchange] branch master updated (f7deeac -> 027da0f)
|
From: |
gnunet |
|
Subject: |
[GNUnet-SVN] [taler-exchange] branch master updated (f7deeac -> 027da0f) |
|
Date: |
Mon, 28 May 2018 15:44:09 +0200 |
This is an automated email from the git hooks/post-receive script.
marcello pushed a change to branch master
in repository exchange.
from f7deeac minor edit
new 9c896fe Commenting "fakebank transfer" CMDs
new 1ecef98 Commenting the "deposit" CMD.
new 12801e2 Commenting the "refund" CMD.
new 26be871 Commenting the "signal" CMD.
new 25ca8f9 Commenting the "reserve status" CMD.
new d08d25e Commenting the "track"(s) CMDs.
new 027da0f Commenting the "wire" CMD.
The 7 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
src/exchange-lib/testing_api_cmd_deposit.c | 82 +++++----
.../testing_api_cmd_fakebank_transfer.c | 194 ++++++++++++++------
src/exchange-lib/testing_api_cmd_refund.c | 62 ++++---
src/exchange-lib/testing_api_cmd_signal.c | 21 ++-
src/exchange-lib/testing_api_cmd_status.c | 44 ++---
src/exchange-lib/testing_api_cmd_track.c | 195 ++++++++++++---------
src/exchange-lib/testing_api_cmd_wire.c | 70 ++++----
7 files changed, 401 insertions(+), 267 deletions(-)
diff --git a/src/exchange-lib/testing_api_cmd_deposit.c
b/src/exchange-lib/testing_api_cmd_deposit.c
index 5854bf8..70d41a3 100644
--- a/src/exchange-lib/testing_api_cmd_deposit.c
+++ b/src/exchange-lib/testing_api_cmd_deposit.c
@@ -30,6 +30,10 @@
#include "taler_testing_lib.h"
#include "taler_signatures.h"
+
+/**
+ * State for a "deposit" CMD.
+ */
struct DepositState
{
@@ -44,13 +48,14 @@ struct DepositState
const char *coin_reference;
/**
- * If this @e coin_ref refers to an operation that generated
+ * If @e coin_reference refers to an operation that generated
* an array of coins, this value determines which coin to pick.
*/
unsigned int coin_index;
/**
- * payto://-URL of the merchant's bank account.
+ * Wire details of who is depositing -- this would be merchant
+ * wire details in a normal scenario.
*/
json_t *wire_details;
@@ -66,7 +71,8 @@ struct DepositState
struct GNUNET_TIME_Relative refund_deadline;
/**
- * Set (by the interpreter) to a fresh private key.
+ * Set (by the interpreter) to a fresh private key. This
+ * key will be used to sign the deposit request.
*/
struct TALER_MerchantPrivateKeyP merchant_priv;
@@ -92,16 +98,15 @@ struct DepositState
};
/**
- * Function called with the result of a /deposit operation.
+ * Callback to analyze the /deposit response, just used to
+ * check if the response code is acceptable.
*
- * @param cls closure with the interpreter state
- * @param http_status HTTP response code, #MHD_HTTP_OK (200) for
- * successful deposit; 0 if the exchange's reply is bogus
- * (fails to follow the protocol)
- * @param ec taler-specific error code, #TALER_EC_NONE on success
- * @param exchange_pub public key the exchange used for signing
- * @param obj the received JSON reply, should be kept as proof
- * (and, in case of errors, be forwarded to the customer)
+ * @param cls closure.
+ * @param http_status HTTP response code.
+ * @param ec taler-specific error code.
+ * @param exchange_pub public key of the exchange,
+ * used for signing the response.
+ * @param obj raw response from the exchange.
*/
static void
deposit_cb (void *cls,
@@ -130,9 +135,9 @@ deposit_cb (void *cls,
/**
* Run the command.
*
- * @param cls closure, typically a #struct WireState.
- * @param cmd the command to execute, a /wire one.
- * @param i the interpreter state.
+ * @param cls closure.
+ * @param cmd the command to execute.
+ * @param is the interpreter state.
*/
static void
deposit_run (void *cls,
@@ -252,9 +257,10 @@ deposit_run (void *cls,
dr.purpose.purpose = htonl
(TALER_SIGNATURE_WALLET_COIN_DEPOSIT);
dr.h_contract_terms = h_contract_terms;
- GNUNET_assert (GNUNET_OK ==
- TALER_JSON_wire_signature_hash (ds->wire_details,
- &dr.h_wire));
+ GNUNET_assert
+ (GNUNET_OK ==
+ TALER_JSON_wire_signature_hash (ds->wire_details,
+ &dr.h_wire));
dr.timestamp = GNUNET_TIME_absolute_hton (timestamp);
dr.refund_deadline = GNUNET_TIME_absolute_hton
(refund_deadline);
@@ -295,7 +301,8 @@ deposit_run (void *cls,
/**
- * Cleanup the state.
+ * Free the state of a "deposit" CMD, and possibly cancel a
+ * pending operation thereof.
*
* @param cls closure, typically a #struct WireState.
* @param cmd the command which is being cleaned up.
@@ -322,16 +329,16 @@ deposit_cleanup (void *cls,
/**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer internal data from a "deposit" CMD, to other commands.
*
- * @param cls closure
- * @param ret[out] result (could be anything)
- * @param trait name of the trait
+ * @param cls closure.
+ * @param ret[out] result (could be anything).
+ * @param trait name of the trait.
* @param selector more detailed information about which object
* to return in case there were multiple generated
- * by the command
- * @return #GNUNET_OK on success
+ * by the command.
+ *
+ * @return #GNUNET_OK on success.
*/
static int
deposit_traits (void *cls,
@@ -378,26 +385,25 @@ deposit_traits (void *cls,
}
/**
- * Create a deposit command.
+ * Create a "deposit" command.
*
- * @param label command label
- * @param exchange exchange connection
+ * @param label command label.
+ * @param exchange exchange connection.
* @param coin_reference reference to any operation that can
- * provide a coin
+ * provide a coin.
* @param coin_index if @a withdraw_reference offers an array of
* coins, this parameter selects which one in that array.
* This value is currently ignored, as only one-coin
* withdrawals are implemented.
- * @param wire_details JSON details of the wire account of the merchant
performing the
- * deposit, reference is captured by this command
+ * @param wire_details wire details associated with the "deposit"
+ * request.
* @param contract_terms contract terms to be signed over by the
- * coin
- * @param refund_deadline refund deadline, zero means 'no refunds'
- * @param amount how much is going to be deposited
- * @param expected_response_code which HTTP status code we expect
- * in the response
+ * coin.
+ * @param refund_deadline refund deadline, zero means 'no refunds'.
+ * @param amount how much is going to be deposited.
+ * @param expected_response_code expected HTTP response code.
*
- * @return the deposit command to be run by the interpreter
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_deposit
diff --git a/src/exchange-lib/testing_api_cmd_fakebank_transfer.c
b/src/exchange-lib/testing_api_cmd_fakebank_transfer.c
index 0b0734b..5cf2c4a 100644
--- a/src/exchange-lib/testing_api_cmd_fakebank_transfer.c
+++ b/src/exchange-lib/testing_api_cmd_fakebank_transfer.c
@@ -40,36 +40,32 @@ struct FakebankTransferState
{
/**
- * Label to another admin_add_incoming command if we
- * should deposit into an existing reserve, NULL if
- * a fresh reserve should be created.
+ * Label of any command that can trait-offer a reserve priv.
*/
const char *reserve_reference;
/**
- * String describing the amount to add to the reserve.
+ * Wire transfer amount.
*/
struct TALER_Amount amount;
/**
- * Wire transfer subject. NULL to use public key corresponding
- * to @e reserve_priv or @e reserve_reference. Should only be
- * set manually to test invalid wire transfer subjects.
+ * Wire transfer subject.
*/
const char *subject;
/**
- * URL to use for the bank.
+ * Base URL of the bank serving the request.
*/
const char *bank_url;
/**
- * Sender (debit) account number.
+ * Money sender account number.
*/
uint64_t debit_account_no;
/**
- * Receiver (credit) account number.
+ * Money receiver account number.
*/
uint64_t credit_account_no;
@@ -85,7 +81,7 @@ struct FakebankTransferState
/**
* Set (by the interpreter) to the reserve's private key
- * we used to fill the reserve.
+ * we used to make a wire transfer subject line with.
*/
struct TALER_ReservePrivateKeyP reserve_priv;
@@ -95,7 +91,7 @@ struct FakebankTransferState
struct TALER_BANK_AdminAddIncomingHandle *aih;
/**
- * Interpreter state while command is running.
+ * Interpreter state.
*/
struct TALER_TESTING_Interpreter *is;
@@ -105,7 +101,7 @@ struct FakebankTransferState
uint64_t serial_id;
/**
- * Exchange URL. FIXME: explaing this data purpose.
+ * Exchange URL. FIXME: explaing is needed.
*/
const char *exchange_url;
@@ -117,16 +113,17 @@ struct FakebankTransferState
/**
* Configuration filename. Used to get the tip reserve key
- * filename, used to obtain a public key to write in the
- * transfer subject.
+ * filename (used to obtain a public key to write in the
+ * transfer subject).
*/
const char *config_filename;
};
/**
- * Function called upon completion of our /admin/add/incoming
- * request.
+ * This callback will process the fakebank response to the wire
+ * transfer. It just checks whether the HTTP response code is
+ * acceptable.
*
* @param cls closure with the interpreter state
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for
@@ -160,14 +157,11 @@ add_incoming_cb (void *cls,
/**
- * Runs the command. Note that upon return, the interpreter
- * will not automatically run the next command, as the command
- * may continue asynchronously in other scheduler tasks. Thus,
- * the command must ensure to eventually call
- * #TALER_TESTING_interpreter_next() or
- * #TALER_TESTING_interpreter_fail().
+ * Run the "fakebank transfer" CMD.
*
- * @param is interpreter state
+ * @param cls closure.
+ * @param cmd CMD being run.
+ * @param is interpreter state.
*/
static void
fakebank_transfer_run (void *cls,
@@ -234,13 +228,15 @@ fakebank_transfer_run (void *cls,
"instance-%s",
fts->instance);
if (GNUNET_OK !=
- GNUNET_CONFIGURATION_get_value_filename (cfg,
- section,
-
"TIP_RESERVE_PRIV_FILENAME",
- &keys))
+ GNUNET_CONFIGURATION_get_value_filename
+ (cfg,
+ section,
+ "TIP_RESERVE_PRIV_FILENAME",
+ &keys))
{
GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
- "Configuration fails to specify reserve private key
filename in section %s\n",
+ "Configuration fails to specify reserve"
+ " private key filename in section %s\n",
section);
GNUNET_free (section);
TALER_TESTING_interpreter_fail (is);
@@ -249,10 +245,11 @@ fakebank_transfer_run (void *cls,
priv = GNUNET_CRYPTO_eddsa_key_create_from_file (keys);
if (NULL == priv)
{
- GNUNET_log_config_invalid (GNUNET_ERROR_TYPE_ERROR,
- section,
- "TIP_RESERVE_PRIV_FILENAME",
- "Failed to read private key");
+ GNUNET_log_config_invalid
+ (GNUNET_ERROR_TYPE_ERROR,
+ section,
+ "TIP_RESERVE_PRIV_FILENAME",
+ "Failed to read private key");
GNUNET_free (keys);
GNUNET_free (section);
TALER_TESTING_interpreter_fail (is);
@@ -305,10 +302,11 @@ fakebank_transfer_run (void *cls,
/**
- * Clean up after the command. Run during forced termination
- * (CTRL-C) or test failure or test success.
+ * Free the state of a "fakebank transfer" CMD, and possibly
+ * cancel a pending operation thereof.
*
* @param cls closure
+ * @param cmd current CMD being cleaned up.
*/
static void
fakebank_transfer_cleanup (void *cls,
@@ -328,16 +326,17 @@ fakebank_transfer_cleanup (void *cls,
/**
- * Extract information from a command that is useful for other
+ * Offer internal data from a "fakebank transfer" CMD to other
* commands.
*
- * @param cls closure
- * @param ret[out] result (could be anything)
- * @param trait name of the trait
+ * @param cls closure.
+ * @param ret[out] result (could be anything).
+ * @param trait name of the trait.
* @param selector more detailed information about which object
* to return in case there were multiple generated
- * by the command
- * @return #GNUNET_OK on success
+ * by the command.
+ *
+ * @return #GNUNET_OK on success.
*/
static int
fakebank_transfer_traits (void *cls,
@@ -366,20 +365,39 @@ fakebank_transfer_traits (void *cls,
index);
}
-
/**
- * Create fakebank_transfer command.
+ * Create fakebank_transfer command, the subject line will be
+ * derived from a randomly created reserve priv. Note that that
+ * reserve priv will then be offered as trait.
*
+ * @param label command label.
+ * @param amount amount to transfer.
+ * @param bank_url base URL of the bank that implements this
+ * wire transer. For simplicity, both credit and debit
+ * bank account exist at the same bank.
+ * @param debit_account_no which account (expressed as a number)
+ * gives money.
+ * @param credit_account_no which account (expressed as a number)
+ * receives money.
+ * @param auth_username username identifying the @a
+ * debit_account_no at the bank.
+ * @param auth_password password for @a auth_username.
+ * @param exchange_url which exchange is involved in this transfer.
+ * This data is used for tracking purposes (FIXME: explain
+ * _how_).
+ *
+ * @return the command.
*/
struct TALER_TESTING_Command
-TALER_TESTING_cmd_fakebank_transfer (const char *label,
- const char *amount,
- const char *bank_url,
- uint64_t debit_account_no,
- uint64_t credit_account_no,
- const char *auth_username,
- const char *auth_password,
- const char *exchange_url)
+TALER_TESTING_cmd_fakebank_transfer
+ (const char *label,
+ const char *amount,
+ const char *bank_url,
+ uint64_t debit_account_no,
+ uint64_t credit_account_no,
+ const char *auth_username,
+ const char *auth_password,
+ const char *exchange_url)
{
struct TALER_TESTING_Command cmd;
struct FakebankTransferState *fts;
@@ -409,10 +427,29 @@ TALER_TESTING_cmd_fakebank_transfer (const char *label,
return cmd;
}
-
/**
- * Create fakebank_transfer command with custom subject.
+ * Create "fakebank transfer" CMD, letting the caller specifying
+ * the subject line.
+ *
+ * @param label command label.
+ * @param amount amount to transfer.
+ * @param bank_url base URL of the bank that implements this
+ * wire transer. For simplicity, both credit and debit
+ * bank account exist at the same bank.
+ * @param debit_account_no which account (expressed as a number)
+ * gives money.
+ * @param credit_account_no which account (expressed as a number)
+ * receives money.
+ *
+ * @param auth_username username identifying the @a
+ * debit_account_no at the bank.
+ * @param auth_password password for @a auth_username.
+ * @param subject wire transfer's subject line.
+ * @param exchange_url which exchange is involved in this transfer.
+ * This data is used for tracking purposes (FIXME: explain
+ * _how_).
*
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_fakebank_transfer_with_subject
@@ -457,8 +494,27 @@ TALER_TESTING_cmd_fakebank_transfer_with_subject
/**
- * Create fakebank_transfer command with custom subject.
+ * Create "fakebank transfer" CMD, letting the caller specify
+ * a reference to a command that can offer a reserve private key.
+ * This private key will then be used to construct the subject line
+ * of the wire transfer.
*
+ * @param label command label.
+ * @param amount the amount to transfer.
+ * @param bank_url base URL of the bank running the transfer.
+ * @param debit_account_no which account (expressed as a number)
+ * gives money.
+ * @param credit_account_no which account (expressed as a number)
+ * receives money.
+ * @param auth_username username identifying the @a
+ * debit_account_no at the bank.
+ * @param auth_password password for @a auth_username.
+ * @param ref reference to a command that can offer a reserve
+ * private key.
+ * @param exchange_url the exchage involved in the transfer,
+ * tipically receiving the money in order to fuel a reserve.
+ *
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_fakebank_transfer_with_ref
@@ -503,8 +559,35 @@ TALER_TESTING_cmd_fakebank_transfer_with_ref
/**
- * Create fakebank_transfer command with custom subject.
+ * Create "fakebank transfer" CMD, letting the caller specifying
+ * the merchant instance. This version is useful when a tip
+ * reserve should be topped up, in fact the interpreter will need
+ * the "tipping instance" in order to get the instance public key
+ * and make a wire transfer subject out of it.
+ *
+ * @param label command label.
+ * @param amount amount to transfer.
+ * @param bank_url base URL of the bank that implements this
+ * wire transer. For simplicity, both credit and debit
+ * bank account exist at the same bank.
+ * @param debit_account_no which account (expressed as a number)
+ * gives money.
+ * @param credit_account_no which account (expressed as a number)
+ * receives money.
*
+ * @param auth_username username identifying the @a
+ * debit_account_no at the bank.
+ * @param auth_password password for @a auth_username.
+ * @param instance the instance that runs the tipping. Under this
+ * instance, the configuration file will provide the private
+ * key of the tipping reserve. This data will then used to
+ * construct the wire transfer subject line.
+ * @param exchange_url which exchange is involved in this transfer.
+ * This data is used for tracking purposes (FIXME: explain
+ * _how_).
+ * @param config_filename configuration file to use.
+ *
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_fakebank_transfer_with_instance
@@ -549,5 +632,4 @@ TALER_TESTING_cmd_fakebank_transfer_with_instance
return cmd;
}
-
/* end of testing_api_cmd_fakebank_transfer.c */
diff --git a/src/exchange-lib/testing_api_cmd_refund.c
b/src/exchange-lib/testing_api_cmd_refund.c
index ed3bd7c..caf5dcf 100644
--- a/src/exchange-lib/testing_api_cmd_refund.c
+++ b/src/exchange-lib/testing_api_cmd_refund.c
@@ -30,6 +30,10 @@
#include "exchange_api_handle.h"
#include "taler_testing_lib.h"
+
+/**
+ * State for a "refund" CMD.
+ */
struct RefundState
{
/**
@@ -53,8 +57,7 @@ struct RefundState
const char *coin_reference;
/**
- * Refund transaction identifier. Left un-initialized in the
- * old test-suite. What's the best way to init it?
+ * Refund transaction identifier.
*/
uint64_t refund_transaction_id;
@@ -76,17 +79,15 @@ struct RefundState
/**
- * Check the result for the refund request.
+ * Check the result for the refund request, just check if the
+ * response code is acceptable.
*
* @param cls closure
- * @param http_status HTTP response code, #MHD_HTTP_OK (200) for
- * successful deposit; 0 if the exchange's reply is bogus
- * (fails to follow the protocol).
- * @param ec taler-specific error code, #TALER_EC_NONE on success
- * @param exchange_pub public key the exchange used for signing @a
- * obj
- * @param obj the received JSON reply, should be kept as proof
- * (and, in particular, be forwarded to the customer)
+ * @param http_status HTTP response code.
+ * @param ec taler-specific error code.
+ * @param exchange_pub public key the exchange
+ * used for signing @a obj.
+ * @param obj response object.
*/
static void
refund_cb (void *cls,
@@ -130,9 +131,9 @@ refund_cb (void *cls,
/**
* Run the command.
*
- * @param cls closure, typically a #struct WireState.
- * @param cmd the command to execute, a /wire one.
- * @param i the interpreter state.
+ * @param cls closure.
+ * @param cmd the command to execute.
+ * @param is the interpreter state.
*/
void
refund_run (void *cls,
@@ -241,9 +242,10 @@ refund_run (void *cls,
/**
- * Cleanup the state.
+ * Free the state from a "refund" CMD, and possibly cancel
+ * a pending operation thereof.
*
- * @param cls closure, typically a #struct WireState.
+ * @param cls closure.
* @param cmd the command which is being cleaned up.
*/
void
@@ -265,14 +267,16 @@ refund_cleanup (void *cls,
}
/**
- * Create a /refund test command.
+ * Create a "refund" command.
*
- * @param label command label
- * @param expected_response_code expected HTTP status code
- * @param refund_amount the amount to ask a refund for
- * @param refund_fee expected refund fee
+ * @param label command label.
+ * @param expected_response_code expected HTTP status code.
+ * @param refund_amount the amount to ask a refund for.
+ * @param refund_fee expected refund fee.
* @param coin_reference reference to a command that can
* provide a coin to be refunded.
+ *
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_refund (const char *label,
@@ -300,15 +304,19 @@ TALER_TESTING_cmd_refund (const char *label,
}
/**
- * Create a /refund test command, allows to specify refund
- * transaction id. Mainly used to create conflicting requests.
+ * Create a "refund" command, allow to specify refund transaction
+ * id. Mainly used to create conflicting requests.
*
- * @param label command label
- * @param expected_response_code expected HTTP status code
- * @param refund_amount the amount to ask a refund for
- * @param refund_fee expected refund fee
+ * @param label command label.
+ * @param expected_response_code expected HTTP status code.
+ * @param refund_amount the amount to ask a refund for.
+ * @param refund_fee expected refund fee.
* @param coin_reference reference to a command that can
* provide a coin to be refunded.
+ * @param refund_transaction_id transaction id to use
+ * in the request.
+ *
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_refund_with_id
diff --git a/src/exchange-lib/testing_api_cmd_signal.c
b/src/exchange-lib/testing_api_cmd_signal.c
index cf07f05..b9487cd 100644
--- a/src/exchange-lib/testing_api_cmd_signal.c
+++ b/src/exchange-lib/testing_api_cmd_signal.c
@@ -27,6 +27,10 @@
#include "exchange_api_handle.h"
#include "taler_testing_lib.h"
+
+/**
+ * State for a "signal" CMD.
+ */
struct SignalState
{
/**
@@ -38,15 +42,13 @@ struct SignalState
* The signal to send to the process.
*/
int signal;
-
};
-
/**
* Run the command.
*
- * @param cls closure, typically a #struct SignalState.
- * @param cmd the command to execute, a /wire one.
+ * @param cls closure.
+ * @param cmd the command to execute.
* @param is the interpreter state.
*/
static void
@@ -67,9 +69,9 @@ signal_run (void *cls,
/**
- * Cleanup the state.
+ * Cleanup the state from a "signal" CMD.
*
- * @param cls closure, typically a #struct SignalState.
+ * @param cls closure.
* @param cmd the command which is being cleaned up.
*/
static void
@@ -83,10 +85,11 @@ signal_cleanup (void *cls,
/**
- * Send a signal to a process.
+ * Create a "signal" CMD.
*
- * @param process handle to the process
- * @param signal signal to send
+ * @param label command label.
+ * @param process handle to the process to signal.
+ * @param signal signal to send.
*
* @return the command.
*/
diff --git a/src/exchange-lib/testing_api_cmd_status.c
b/src/exchange-lib/testing_api_cmd_status.c
index 2107b75..1e5f671 100644
--- a/src/exchange-lib/testing_api_cmd_status.c
+++ b/src/exchange-lib/testing_api_cmd_status.c
@@ -27,6 +27,10 @@
#include "exchange_api_handle.h"
#include "taler_testing_lib.h"
+
+/**
+ * State for a "status" CMD.
+ */
struct StatusState
{
/**
@@ -36,7 +40,7 @@ struct StatusState
const char *reserve_reference;
/**
- * Handle to a /reserve/status operation.
+ * Handle to the "reserve status" operation.
*/
struct TALER_EXCHANGE_ReserveStatusHandle *rsh;
@@ -51,7 +55,7 @@ struct StatusState
unsigned int expected_response_code;
/**
- * Handle to the exchange.
+ * Connection handle to the exchange.
*/
struct TALER_EXCHANGE_Handle *exchange;
@@ -63,19 +67,16 @@ struct StatusState
/**
- * Check exchange returned expected values.
+ * Check that the reserve balance and HTTP response code are
+ * both acceptable.
*
- * @param cls closure
- * @param http_status HTTP response code, #MHD_HTTP_OK (200) for
- * successful status request 0 if the exchange's reply is
- * bogus (fails to follow the protocol)
- * @param ec taler-specific error code, #TALER_EC_NONE on success
- * @param[in] json original response in JSON format (useful only
- * for diagnostics)
- * @param balance current balance in the reserve, NULL on error
+ * @param cls closure.
+ * @param http_status HTTP response code.
+ * @param ec taler-specific error code.
+ * @param balance current balance in the reserve, NULL on error.
* @param history_length number of entries in the transaction
- * history, 0 on error
- * @param history detailed transaction history, NULL on error
+ * history, 0 on error.
+ * @param history detailed transaction history, NULL on error.
*/
static void
reserve_status_cb
@@ -136,9 +137,9 @@ reserve_status_cb
/**
* Run the command.
*
- * @param cls closure, typically a #struct WireState.
- * @param cmd the command to execute, a /wire one.
- * @param i the interpreter state.
+ * @param cls closure.
+ * @param cmd the command being executed.
+ * @param is the interpreter state.
*/
static void
status_run (void *cls,
@@ -185,9 +186,10 @@ status_run (void *cls,
/**
- * Cleanup the state.
+ * Cleanup the state from a "reserve status" CMD, and possibly
+ * cancel a pending operation thereof.
*
- * @param cls closure, typically a #struct WireState.
+ * @param cls closure.
* @param cmd the command which is being cleaned up.
*/
static void
@@ -210,15 +212,15 @@ status_cleanup (void *cls,
/**
- * Create a /reserve/status command.
+ * Create a "reserve status" command.
*
* @param label the command label.
* @param exchange the exchange to connect to.
* @param reserve_reference reference to the reserve to check.
- * @param expected_balance balance expected to be at the referenced reserve.
+ * @param expected_balance expected balance for the reserve.
* @param expected_response_code expected HTTP response code.
*
- * @return the command to be executed by the interpreter.
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_status (const char *label,
diff --git a/src/exchange-lib/testing_api_cmd_track.c
b/src/exchange-lib/testing_api_cmd_track.c
index d4f9805..8d9f9ed 100644
--- a/src/exchange-lib/testing_api_cmd_track.c
+++ b/src/exchange-lib/testing_api_cmd_track.c
@@ -18,29 +18,30 @@
*/
/**
- * @file exchange/testing_api_cmd_status.c
- * @brief Implement the /reserve/status test command.
+ * @file exchange/testing_api_cmd_track.c
+ * @brief Implement the testing CMDs for the /track operations.
* @author Marcello Stanisci
*/
-
#include "platform.h"
#include "taler_json_lib.h"
#include <gnunet/gnunet_curl_lib.h>
#include "exchange_api_handle.h"
#include "taler_testing_lib.h"
+/**
+ * State for a "track transaction" CMD.
+ */
struct TrackTransactionState
{
/**
- * Which #OC_CHECK_BANK_TRANSFER wtid should this match? NULL
- * for none.
+ * If non NULL, will provide a WTID to be compared against
+ * the one returned by the "track transaction" operation.
*/
const char *bank_transfer_reference;
/**
- * Wire transfer identifier, set if #MHD_HTTP_OK was the
- * response code.
+ * The WTID associated by the transaction being tracked.
*/
struct TALER_WireTransferIdentifierRawP wtid;
@@ -51,17 +52,18 @@ struct TrackTransactionState
/**
* Reference to any operation that can provide a transaction.
- * Tipically a /deposit operation.
+ * Will be the transaction to track.
*/
const char *transaction_reference;
/**
- * Index of the coin involved in the transaction.
+ * Index of the coin involved in the transaction. Recall:
+ * at the exchange, the tracking is done _per coin_.
*/
unsigned int coin_index;
/**
- * Handle to the deposit wtid request.
+ * Handle to the "track transaction" pending operation.
*/
struct TALER_EXCHANGE_TrackTransactionHandle *tth;
@@ -76,11 +78,15 @@ struct TrackTransactionState
struct TALER_TESTING_Interpreter *is;
};
+
+/**
+ * State for a "track transfer" CMD.
+ */
struct TrackTransferState
{
/**
- * Expected amount for this WTID.
+ * Expected amount for the WTID being tracked.
*/
const char *expected_total_amount;
@@ -96,31 +102,38 @@ struct TrackTransferState
/**
* Reference to any operation that can provide a WTID.
+ * Will be the WTID to track.
*/
const char *wtid_reference;
/**
* Reference to any operation that can provide wire details.
+ * Those wire details will then be matched against the credit
+ * bank account of the tracked WTID. This way we can test that
+ * a wire transfer paid back one particular bank account.
*/
const char *wire_details_reference;
/**
* Reference to any operation that can provide an amount.
+ * This way we can check that the transferred amount matches
+ * our expectations.
*/
const char *total_amount_reference;
/**
- * Index to the WTID to pick.
+ * Index to the WTID to pick, in case @a wtid_reference has
+ * many on offer.
*/
unsigned int index;
/**
- * Handle to the deposit wtid request.
+ * Handle to a pending "track transfer" operation.
*/
struct TALER_EXCHANGE_TrackTransferHandle *tth;
/**
- * Handle to the exchange.
+ * Connection handle to the exchange.
*/
struct TALER_EXCHANGE_Handle *exchange;
@@ -132,24 +145,25 @@ struct TrackTransferState
/**
- * Function called with detailed wire transfer data.
+ * Checks what is returned by the "track transaction" operation.
+ * Checks that the HTTP response code is acceptable, and - if the
+ * right reference is non NULL - that the wire transfer subject
+ * line matches our expectations.
*
- * @param cls closure
- * @param http_status HTTP status code we got, 0 on exchange
- * protocol violation
- * @param ec taler-specific error code, #TALER_EC_NONE on success
- * @param exchange_pub public key the exchange used for signing
+ * @param cls closure.
+ * @param http_status HTTP status code we got.
+ * @param ec taler-specific error code.
* @param json original json reply (may include signatures, those
- * have then been validated already)
- * @param wtid wire transfer identifier used by the exchange, NULL
- * if exchange did not yet execute the transaction
+ * have then been validated already).
+ * @param wtid wire transfer identifier, NULL if exchange did not
+ * execute the transaction yet.
* @param execution_time actual or planned execution time for the
- * wire transfer
+ * wire transfer.
* @param coin_contribution contribution to the @a total_amount of
- * the deposited coin (may be NULL)
+ * the deposited coin (can be NULL).
* @param total_amount total amount of the wire transfer, or NULL
* if the exchange could not provide any @a wtid (set only
- * if @a http_status is #MHD_HTTP_OK)
+ * if @a http_status is #MHD_HTTP_OK).
*/
static void
deposit_wtid_cb
@@ -186,8 +200,10 @@ deposit_wtid_cb
const struct TALER_TESTING_Command *bank_transfer_cmd;
char *ws;
+ /* _this_ wire transfer subject line. */
ws = GNUNET_STRINGS_data_to_string_alloc (wtid,
sizeof (*wtid));
+
bank_transfer_cmd = TALER_TESTING_interpreter_lookup_command
(is, tts->bank_transfer_reference);
@@ -198,6 +214,7 @@ deposit_wtid_cb
return;
}
+ /* expected wire transfer subject line. */
const char *transfer_subject;
if (GNUNET_OK != TALER_TESTING_get_trait_transfer_subject
@@ -207,7 +224,8 @@ deposit_wtid_cb
TALER_TESTING_interpreter_fail (is);
return;
}
-
+
+ /* Compare that expected and gotten subjects match. */
if (0 != strcmp (ws, transfer_subject))
{
GNUNET_break (0);
@@ -235,8 +253,8 @@ deposit_wtid_cb
/**
* Run the command.
*
- * @param cls closure, typically a #struct WireState.
- * @param cmd the command to execute, a /track/transaction one.
+ * @param cls closure.
+ * @param cmd the command to execute.
* @param is the interpreter state.
*/
void
@@ -335,9 +353,10 @@ track_transaction_run (void *cls,
}
/**
- * Cleanup the state.
+ * Cleanup the state from a "track transaction" CMD, and possibly
+ * cancel a operation thereof.
*
- * @param cls closure, typically a #struct WireState.
+ * @param cls closure.
* @param cmd the command which is being cleaned up.
*/
void
@@ -361,16 +380,16 @@ track_transaction_cleanup
/**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer internal data from a "track transaction" CMD.
*
- * @param cls closure
- * @param ret[out] result (could be anything)
- * @param trait name of the trait
+ * @param cls closure.
+ * @param ret[out] result (could be anything).
+ * @param trait name of the trait.
* @param selector more detailed information about which object
* to return in case there were multiple generated
- * by the command
- * @return #GNUNET_OK on success
+ * by the command.
+ *
+ * @return #GNUNET_OK on success.
*/
static int
track_transaction_traits (void *cls,
@@ -392,18 +411,19 @@ track_transaction_traits (void *cls,
}
/**
- * Create a /track/transaction command.
+ * Create a "track transaction" command.
*
* @param label the command label.
* @param exchange the exchange to connect to.
- * @param transaction_reference reference to a deposit operation.
- * @param coin_index index of the coin involved in the transaction
+ * @param transaction_reference reference to a deposit operation,
+ * will be used to get the input data for the track.
+ * @param coin_index index of the coin involved in the transaction.
* @param expected_response_code expected HTTP response code.
- * @param bank_transfer_reference which #OC_CHECK_BANK_TRANSFER
- * wtid should this match? NULL
- * for none
+ * @param bank_transfer_reference reference to a command that
+ * can offer a WTID so as to check that against what WTID
+ * the tracked operation has. Set as NULL if not needed.
*
- * @return the command to be executed by the interpreter.
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_track_transaction
@@ -431,11 +451,11 @@ TALER_TESTING_cmd_track_transaction
cmd.traits = &track_transaction_traits;
return cmd;
-
}
/**
- * Cleanup the state.
+ * Cleanup the state for a "track transfer" CMD, and possibly
+ * cancel a pending operation thereof.
*
* @param cls closure.
* @param cmd the command which is being cleaned up.
@@ -461,28 +481,28 @@ track_transfer_cleanup (void *cls,
}
/**
- * Function called with detailed wire transfer data, including all
- * of the coin transactions that were combined into the wire
- * transfer.
+ * Check whether the HTTP response code from a "track transfer"
+ * operation is acceptable, and all other values like total amount,
+ * wire fees and hashed wire details as well.
*
- * @param cls closure
- * @param http_status HTTP status code we got, 0 on exchange
- * protocol violation
- * @param ec taler-specific error code, #TALER_EC_NONE on success
+ * @param cls closure.
+ * @param http_status HTTP status code we got.
+ * @param ec taler-specific error code.
* @param exchange_pub public key the exchange used for signing
+ * the response.
* @param json original json reply (may include signatures, those
- * have then been validated already)
+ * have then been validated already).
* @param h_wire hash of the wire transfer address the transfer
- * went to, or NULL on error
+ * went to, or NULL on error.
* @param execution_time time when the exchange claims to have
- * performed the wire transfer
+ * performed the wire transfer.
* @param total_amount total amount of the wire transfer, or NULL
* if the exchange could not provide any @a wtid (set only
- * if @a http_status is #MHD_HTTP_OK)
- * @param wire_fee wire fee that was charged by the exchange
- * @param details_length length of the @a details array
+ * if @a http_status is "200 OK").
+ * @param wire_fee wire fee that was charged by the exchange.
+ * @param details_length length of the @a details array.
* @param details array with details about the combined
- * transactions
+ * transactions.
*/
static void
track_transfer_cb
@@ -524,7 +544,6 @@ track_transfer_cb
"Expected amount and fee not specified, "
"likely to segfault...\n");
-
switch (http_status)
{
case MHD_HTTP_OK:
@@ -571,6 +590,7 @@ track_transfer_cb
return;
}
+ /* FIXME: this block does nothing. Remove? */
wtid_cmd = TALER_TESTING_interpreter_lookup_command
(is, tts->wtid_reference);
@@ -612,9 +632,10 @@ track_transfer_cb
return;
}
- GNUNET_assert (GNUNET_OK ==
- TALER_JSON_wire_signature_hash (wire_details,
- &h_wire_details));
+ GNUNET_assert
+ (GNUNET_OK == TALER_JSON_wire_signature_hash
+ (wire_details,
+ &h_wire_details));
if (0 != memcmp (&h_wire_details,
h_wire,
@@ -674,7 +695,7 @@ track_transfer_cb
* Run the command.
*
* @param cls closure.
- * @param cmd the command to execute, a /track/transfer one.
+ * @param cmd the command under execution.
* @param is the interpreter state.
*/
void
@@ -683,7 +704,6 @@ track_transfer_run (void *cls,
struct TALER_TESTING_Interpreter *is)
{
/* looking for a wtid to track .. */
-
struct TrackTransferState *tts = cls;
struct TALER_WireTransferIdentifierRawP wtid;
struct TALER_WireTransferIdentifierRawP *wtid_ptr;
@@ -721,23 +741,26 @@ track_transfer_run (void *cls,
wtid_ptr,
&track_transfer_cb,
tts);
-
GNUNET_assert (NULL != tts->tth);
}
/**
- * Make a /track/transfer command, expecting the transfer
- * not being done (yet).
+ * Make a "track transfer" CMD where no "expected"-arguments,
+ * except the HTTP response code, are given. The best use case
+ * is when what matters to check is the HTTP response code, e.g.
+ * when a bogus WTID was passed.
*
* @param label the command label
- * @param exchange connection to the exchange
+ * @param exchange connection to the exchange.
* @param wtid_reference reference to any command which can provide
- * a wtid
- * @param index in case there are multiple wtid offered, this
- * parameter selects a particular one
- * @param expected_response_code expected HTTP response code
+ * a wtid. If NULL is given, then a all zeroed WTID is
+ * used that will at 99.9999% probability NOT match any
+ * existing WTID known to the exchange.
+ * @param index index number of the WTID to track, in case there
+ * are multiple on offer.
+ * @param expected_response_code expected HTTP response code.
*
- * @return the command
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_track_transfer_empty
@@ -766,18 +789,18 @@ TALER_TESTING_cmd_track_transfer_empty
}
/**
- * Make a /track/transfer command, specifying which amount and
+ * Make a "track transfer" command, specifying which amount and
* wire fee are expected.
*
- * @param label the command label
- * @param exchange connection to the exchange
+ * @param label the command label.
+ * @param exchange connection to the exchange.
* @param wtid_reference reference to any command which can provide
- * a wtid
- * @param index in case there are multiple wtid offered, this
- * parameter selects a particular one
- * @param expected_response_code expected HTTP response code
- * @param expected_amount how much money we expect being
- * moved with this wire-transfer.
+ * a wtid. Will be the one tracked.
+ * @param index in case there are multiple WTID offered, this
+ * parameter selects a particular one.
+ * @param expected_response_code expected HTTP response code.
+ * @param expected_amount how much money we expect being moved
+ * with this wire-transfer.
* @param expected_wire_fee expected wire fee.
*
* @return the command
@@ -811,3 +834,5 @@ TALER_TESTING_cmd_track_transfer
return cmd;
}
+
+/* end of testing_api_cmd_track.c */
diff --git a/src/exchange-lib/testing_api_cmd_wire.c
b/src/exchange-lib/testing_api_cmd_wire.c
index cf8304e..c403f6a 100644
--- a/src/exchange-lib/testing_api_cmd_wire.c
+++ b/src/exchange-lib/testing_api_cmd_wire.c
@@ -30,6 +30,10 @@
#include "taler_wire_lib.h"
#include "taler_testing_lib.h"
+
+/**
+ * State for a "wire" CMD.
+ */
struct WireState
{
@@ -39,7 +43,7 @@ struct WireState
struct TALER_EXCHANGE_WireHandle *wh;
/**
- * Which wire-method we expect are offered by the exchange.
+ * Which wire-method we expect is offered by the exchange.
*/
const char *expected_method;
@@ -72,16 +76,16 @@ struct WireState
/**
- * Callbacks called with the result(s) of a wire format inquiry
- * request to the exchange.
+ * Check whether the HTTP response code is acceptable, that
+ * the expected wire method is offered by the exchange, and
+ * that the wire fee is acceptable too.
*
- * @param cls closure with the interpreter state
- * @param http_status HTTP response code, #MHD_HTTP_OK (200)
- * for successful request; 0 if the exchange's
- * reply is bogus (fails to follow the protocol)
- * @param ec taler-specific error code, #TALER_EC_NONE on success
- * @param accounts_len length of the @a accounts array
- * @param accounts list of wire accounts of the exchange, NULL on error
+ * @param cls closure.
+ * @param http_status HTTP response code.
+ * @param ec taler-specific error code.
+ * @param accounts_len length of the @a accounts array.
+ * @param accounts list of wire accounts of the exchange,
+ * NULL on error.
*/
static void
wire_cb (void *cls,
@@ -91,7 +95,8 @@ wire_cb (void *cls,
const struct TALER_EXCHANGE_WireAccount *accounts)
{
struct WireState *ws = cls;
- struct TALER_TESTING_Command *cmd = &ws->is->commands[ws->is->ip];
+ struct TALER_TESTING_Command *cmd = \
+ &ws->is->commands[ws->is->ip];
struct TALER_Amount expected_fee;
ws->wh = NULL;
@@ -115,23 +120,25 @@ wire_cb (void *cls,
ws->method_found = GNUNET_OK;
if (NULL != ws->expected_fee)
{
- GNUNET_assert (GNUNET_OK ==
- TALER_string_to_amount (ws->expected_fee,
- &expected_fee));
- for (const struct TALER_EXCHANGE_WireAggregateFees *waf =
accounts[i].fees;
+ GNUNET_assert
+ (GNUNET_OK ==
+ TALER_string_to_amount (ws->expected_fee,
+ &expected_fee));
+ const struct TALER_EXCHANGE_WireAggregateFees *waf;
+ for (waf = accounts[i].fees;
NULL != waf;
waf = waf->next)
{
if (0 != TALER_amount_cmp (&waf->wire_fee,
&expected_fee))
- {
- GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
- "Wire fee missmatch to command %s\n",
- cmd->label);
- TALER_TESTING_interpreter_fail (ws->is);
- GNUNET_free (method);
- return;
- }
+ {
+ GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
+ "Wire fee missmatch to command %s\n",
+ cmd->label);
+ TALER_TESTING_interpreter_fail (ws->is);
+ GNUNET_free (method);
+ return;
+ }
}
}
}
@@ -153,14 +160,14 @@ wire_cb (void *cls,
/**
* Run the command.
*
- * @param cls closure, typically a #struct WireState.
- * @param cmd the command to execute, a /wire one.
- * @param i the interpreter state.
+ * @param cls closure.
+ * @param cmd the command to execute.
+ * @param is the interpreter state.
*/
void
wire_run (void *cls,
const struct TALER_TESTING_Command *cmd,
- struct TALER_TESTING_Interpreter *i)
+ struct TALER_TESTING_Interpreter *is)
{
struct WireState *ws = cls;
ws->is = i;
@@ -171,9 +178,10 @@ wire_run (void *cls,
/**
- * Cleanup the state.
+ * Cleanup the state of a "wire" CMD, and possibly cancel a
+ * pending operation thereof.
*
- * @param cls closure, typically a #struct WireState.
+ * @param cls closure.
* @param cmd the command which is being cleaned up.
*/
void
@@ -195,7 +203,7 @@ wire_cleanup (void *cls,
}
/**
- * Create a /wire command.
+ * Create a "wire" command.
*
* @param label the command label.
* @param exchange the exchange to connect to.
@@ -205,7 +213,7 @@ wire_cleanup (void *cls,
* @param expected_response_code the HTTP response the exchange
* should return.
*
- * @return the command to be executed by the interpreter.
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_wire (const char *label,
--
To stop receiving notification emails like this one, please contact
address@hidden
- [GNUnet-SVN] [taler-exchange] branch master updated (f7deeac -> 027da0f),
gnunet <=
- [GNUnet-SVN] [taler-exchange] 02/07: Commenting the "deposit" CMD., gnunet, 2018/05/28
- [GNUnet-SVN] [taler-exchange] 07/07: Commenting the "wire" CMD., gnunet, 2018/05/28
- [GNUnet-SVN] [taler-exchange] 05/07: Commenting the "reserve status" CMD., gnunet, 2018/05/28
- [GNUnet-SVN] [taler-exchange] 01/07: Commenting "fakebank transfer" CMDs, gnunet, 2018/05/28
- [GNUnet-SVN] [taler-exchange] 06/07: Commenting the "track"(s) CMDs., gnunet, 2018/05/28
- [GNUnet-SVN] [taler-exchange] 04/07: Commenting the "signal" CMD., gnunet, 2018/05/28
- [GNUnet-SVN] [taler-exchange] 03/07: Commenting the "refund" CMD., gnunet, 2018/05/28