[GNUnet-SVN] [taler-merchant-frontend-examples] branch master updated: fixing the php tutorial as to have the "contract" word adapted to the new terminology. "Advanced topics" is still obsolete.

[gnunet]

This is an automated email from the git hooks/post-receive script.

marcello pushed a commit to branch master
in repository merchant-frontend-examples.

The following commit(s) were added to refs/heads/master by this push:
     new 28918ae  fixing the php tutorial as to have the "contract" word 
adapted to the new terminology. "Advanced topics" is still obsolete.
28918ae is described below

commit 28918aebfae40ae3bebf7eb05ddfb732caa785f5
Author: Marcello Stanisci <address@hidden>
AuthorDate: Tue Mar 28 15:57:21 2017 +0200

    fixing the php tutorial as to have the "contract" word
    adapted to the new terminology. "Advanced topics" is still
    obsolete.
---
 php/doc/tutorial.texi  | 124 +++++++++++++++++++++++++------------------------
 php/generate-order.php |   4 +-
 php/history.js         |  18 ++++---
 php/history.php        |  10 ++--
 php/order.php          |   4 +-
 php/pay.php            |   8 ++++
 6 files changed, 92 insertions(+), 76 deletions(-)

diff --git a/php/doc/tutorial.texi b/php/doc/tutorial.texi
index 70fd52c..63213f0 100644
--- a/php/doc/tutorial.texi
+++ b/php/doc/tutorial.texi
@@ -246,7 +246,7 @@ A minimalistic @code{donate.php} implementation is shown 
below (in PHP):
 @end smallexample
 
 Given this response, the Taler wallet will fetch the proposal from
address@hidden/generate-contract.php} and display it to the user.
address@hidden/generate-order.php} and display it to the user.
 
 If the wallet is not present, the HTML body will be shown and the
 Taler headers and the 402 status code ought to be ignored by the
@@ -276,27 +276,27 @@ The following code generate a order about donating 1 
KUDOS to the
 
 @cindex contract
 @smallexample
-// php/contract.php
address@hidden ../contract.php
+// php/order.php
address@hidden ../order.php
 @end smallexample
 
 
 @section Signing and returning the proposal
 
-The server-side handler for @code{/generate-contract.php} has to call
+The server-side handler for @code{/generate-order.php} has to call
 @code{make_order} and then POST the result to the backend at
 @code{/proposal}.  By POSTing the order to the backend we get a
 cryptographic signature over its contents.  The result is then
 returned to the wallet.
 
-A simple @code{/generate-contract.php} handler may thus look like this:
+A simple @code{/generate-order.php} handler may thus look like this:
 
 @cindex signature
 @cindex backend
 @cindex order
 @smallexample
-// php/generate-contract.php
address@hidden ../generate-contract.php
+// php/generate-order.php
address@hidden ../generate-order.php
 @end smallexample
 
 @c FIXME: improve example to do this right?
@@ -336,21 +336,17 @@ fulfillment page must thus use the HTTP session state to 
detect if the
 payment has been performed already, and if not request payment from
 the wallet.
 
-For our example, we include in the URI of the fulfillment page the
-information which is needed to allow the page to determine which
-contract the user is trying to access.
-Thus, the fulfillment URL for our example looks like the following:@*
+For our example, the fulfillment URL will contain the order id of
+the donation, like in the following example:
 
 @smallexample
-https://shop.com/fulfillment.php? \
-order_id=<ORDER_ID>&timestamp=<ORDERTIMESTAMP>
+https://shop.com/fulfillment.php?order_id=<ORDER_ID>
 @end smallexample
 
-The fulfillment handler at @code{/fulfillment.php}
-will use this information to check if the user has already
-paid, and if so confirm the donation.  If the user has not yet
-paid, it will instead return another ``402 Payment Required''
-header, requesting the wallet to pay:
+The fulfillment handler at @code{/fulfillment.php} will use this information
+to check if the user has already paid, and if so confirm the donation.
+If the user has not yet paid, it will instead return another ``402 Payment
+Required'' header, requesting the wallet to pay:
 
 @smallexample
 // php/fulfillment.php
@@ -362,21 +358,28 @@ Here, this second 402 response contains the following 
Taler-specific
 headers:
 
 @table @code
address@hidden X-Taler-Contract-Hash
address@hidden X-Taler-Contract-Url
 @cindex X-Taler-Contract-Url
-FIXME
address@hidden X-Taler-Pay-Url
address@hidden X-Taler-Pay-Url
-This URL specifies where we expect the wallet to send the payment.
+The URL that generated the proposal that led to this payment.
+The wallet may need to reconstruct the proposal.
address@hidden X-Taler-Contract-Query
address@hidden X-Taler-Contract-Query
+The way the wallet should lookup for replayable payments.
+NOTE that for each payment done, the wallet stores the coins it
+spent for it in an internal database. And each set of used coins
+is associated to the fulfillment page where they have been spent.
+So whenever an already known fulfillment page requests a payment,
+the wallet will pick those coins it spent on that fulfillment
+page and resend them (therefore @emph{replaying} the payment).
+In other words, new coins are used only on unknown fulfillment
+pages.
 @item X-Taler-Offer-Url
 @cindex X-Taler-Offer-Url
-In case that the wallet does not know about this contract already,
+In case that the wallet does not know about this payment already,
 i.e. because a user shared the URL with another user, this tells the
 wallet where to go to retrieve a fresh offer.
address@hidden FIXME: do implement offer-URL properly for the tutorial!
 @end table
 
-
 @section Receiving payments via Taler
 
 The final next step for the frontend is to accept the payment from the
@@ -405,7 +408,6 @@ successful, the wallet will refresh the fulfillment page, 
this
 time receiving the message that the donation was successful.  If
 anything goes wrong, the wallet will handle the respective error.
 
-
 @node Back-office-integration
 @chapter Integration with the back office
 
@@ -417,6 +419,10 @@ communication with the Taler exchange for payment), and 
the term
 @emph{wire transfer} to refer to the exchange settling its accounts
 with the merchant.
 
+However, from the frontend's perspective, any transaction is denoted
+by the @emph{order id} contained in the proposal that led to the
+transaction.
+
 Given that Taler deals with microtransactions, not every customer
 payment processed with Taler will necessarily correspond to a wire
 transfer.  The Taler exchange may aggregate multiple payments from
@@ -436,11 +442,11 @@ Given this charge, the back office's main tasks are:
 
 @itemize
 @item
-Allow the back office operator to specify a transaction ID, and
-display the corresponding wire transfer identifiers
+Allow the back office operator to specify a order id, and display the
+corresponding wire transfer identifiers.
 @item
 Allow the back office operator to specify a wire transfer ID, and
-display all of the corresponding transaction IDs
+display all of the corresponding order ids.
 @item
 Allow the back office operator to obtain a list of all transactions.
 @end itemize
@@ -459,10 +465,10 @@ get the list of known transactions.  See below.
 @section Tracking a transaction
 
 The @code{track-transaction.php} script is now responsible for taking
-the Taler transaction ID given by the user in the @code{tid} field,
-and using it to issue a @code{/track/transaction} request to the
-backend, see
address@hidden://api.taler.net/api-merchant.html#get--track-transaction}.
+all the URL query parameter and use them on the @code{/track/transaction}
+request to the backend, see 
@url{http://api.taler.net/api-merchant.html#get--track-transaction}.
+The parameters are the @emph{order_id} and the @emph{instance} (see 
@ref{Instances})
+of this merchant.
 Note that the backend may then request this information from the
 exchange, or retrieve it from its own cache if it has already obtained
 it.  The backend will also check signatures from the exchange, persist
@@ -476,12 +482,12 @@ its facts in an inconsistent manner.
 
 If the backend returned an HTTP status code @code{202} (Accepted),
 this means that the exchange simply did not yet perform the wire
-transfer. This is usually the case before @var{pay_deadline} as the exchange
-is waiting for additional opportunities to aggregate transactions.
+transfer. This is usually the case before @var{pay_deadline}, as the
+exchange is waiting for additional opportunities to aggregate transactions.
 In this case, we tell the user when to retry this operation later.
 
 In the @code{foreach} loop, we construct the list of all the
-wire transfers which paid back transaction @code{tid}.  For
+wire transfers which paid back transaction @emph{order_id}.  For
 simplicity, the list will report only two values: the wire transfer
 identifier and the date when the transfer occurred. Nonetheless,
 the data returned by the backend contains more information that
@@ -504,7 +510,7 @@ In the usual case where everything went fine, we first 
output the
 amount that was supposed to have been transfered under the given
 @code{wtid}, and when it was performed (according to the exchange).
 Finally, in the @code{foreach} loop, we construct the list of the
-transaction IDs paid by the wire transfer:
+order ids paid by the wire transfer:
 
 @smallexample
 @verbatiminclude ../track-transfer.php
@@ -514,44 +520,40 @@ transaction IDs paid by the wire transfer:
 @node History
 @section Listing all transactions
 
-In order to track transactions, transaction IDs are needed as input.
+In order to track transactions, order ids are needed as input.
 To that purpose, the frontend needs to make a HTTP GET request to
address@hidden/history?date=<TIMESTAMP>}, which is offered by the backend.
-The returned data lists all the transactions from @emph{<TIMESTAMP>}
-to now.
address@hidden/history}, which is offered by the backend.
+
+The returned data lists the transactions from the youngest back to
+the oldest.
 
-Our example frontend, implements this feature by orchestrating two
+The @code{/history} API is actually more rich, as it offers the way
+to skim results based on time or on index, but that goes beyond the
+scope of this tutorial.
+
+Our example frontend implements this feature by orchestrating two
 parts:
 
 @itemize
address@hidden The @code{/history.php?days=<DAYSAGO>} script, whose @code{days}
-      parameter specifies to retrieve transactions timestamped at most
-      @emph{<DAYSAGO>} days ago.
-      The script will then translate @emph{<DAYSAGO>} in a timestamp,
-      and issue the call to backend's @code{/history?date=<TIMESTAMP>}.
-      The data it receives from the backend is finally returned in JSON
-      format to the browser.
-
 @item A JavaScript function, imported within @code{backoffice.html},
-      that issues the HTTP GET to @code{/history.php?days=<DAYSAGO>}
+      that issues the HTTP GET to @code{/history.php?instance=tutorial}
       and modifies the current page by adding a table showing the result.
address@hidden The @code{history.php} script, which is in charge of serving the 
request
+      coming from the JavaScript. Its task is to relay that request to the
+      backend, and echo the result back.
 @end itemize
 
 See below both parts:
 
 @smallexample
-// ../history.php
address@hidden ../history.php
address@hidden smallexample
-
address@hidden
 // ../history.js
 @verbatiminclude ../history.js
 @end smallexample
 
-Please note that because of the ``instances'' mechanism, and the use of the
-default backend, the list of transactions may include entries related to other
-frontends, see @ref{Instances}.
address@hidden
+// ../history.php
address@hidden ../history.php
address@hidden smallexample
 
 @node Advanced topics
 @chapter Advanced topics
@@ -859,7 +861,7 @@ Thus our homepage can now look as follows
 @end smallexample
 
 @code{donate-js.html} is now in charge of calling @code{offerContractFrom} 
-passing the contract URL to it, which is @code{"/generate-contract.php"} in
+passing the contract URL to it, which is @code{"/generate-order.php"} in
 our example.  See below.
 
 @smallexample
diff --git a/php/generate-order.php b/php/generate-order.php
index 017780f..9b86a20 100644
--- a/php/generate-order.php
+++ b/php/generate-order.php
@@ -8,8 +8,6 @@
   $order_id = "tutorial-" . dechex(rand(0,99999999)) . date("-H_i_s");
   session_start();
   $_SESSION["order_id"] = $order_id;
-  // this variable is the JSON of a contract proposal,
-  // see https://api.taler.net/api-merchant.html#post--contract
   if(!isset($_GET["nonce"]))
     return build_error(array("body" => null),
                        "no nonce given",
@@ -23,7 +21,7 @@
   http_response_code($response["status_code"]);
   if (200 != $response["status_code"]) {
     echo build_error($response,
-                     "Failed to generate contract",
+                     "Failed to generate proposal",
                      $response['status_code']);
     return;
   }
diff --git a/php/history.js b/php/history.js
index 50629f6..c92b8db 100644
--- a/php/history.js
+++ b/php/history.js
@@ -1,17 +1,15 @@
 var FRACTION = 100000000;
 
-/**
- * Stringify amounts
- */
+// Stringify amounts. Take a {value: x, fraction: y, currency: "Z"}
+// and return a "a.b Z" form.
 function parse_amount(amount){
   var v = amount.value + (amount.fraction/FRACTION);
   return v + " " + amount.currency;
 }
 
-/**
- * Parse Taler date ("/Date(TIMESTAMP)/") string
- */
-  function get_date(date){
+// Parse Taler date ("/Date(TIMESTAMP)/") string and
+// return a JavaScript Date object.
+function get_date(date){
   var split = date.match(/Date\((.*)\)/);
   var seconds;
   if(isNaN(seconds = Number(split[1]))){
@@ -24,7 +22,12 @@ function parse_amount(amount){
 }
 
 
+// Perform the call to /history.php?instance=tutorial.
+// It also takes care of cleaning/filling the table showing
+// the results.
 function submit_history(){
+
+  // Clean the table showing old results
   var table = document.getElementById("history");
   /* We don't want to kill the first child */
   for (var i = 2; i < table.childNodes.length; i++)
@@ -48,6 +51,7 @@ function submit_history(){
       if(0 == history.length){
         table.innerHTML = "<p>No transaction was that young!</p>"; 
       }
+      // Fill the table with fresh results
       for (var i=0; i<history.length; i++){
        var entry = history[i];
         var tr = document.createElement("tr");
diff --git a/php/history.php b/php/history.php
index 360e695..d8f975d 100644
--- a/php/history.php
+++ b/php/history.php
@@ -1,15 +1,19 @@
 <?php
   
-  include 'helpers.php';
-  include 'backend.php';
-  include 'error.php';
+  include "helpers.php";
+  include "backend.php";
+  include "error.php";
 
+  // Just relay the request we got from the JavaScript
   $response = get_to_backend("/history", $_GET);
+
   if (200 != $response["status_code"]){
     echo build_error($response,
                      "Backend error",
                      $response["status_code"]);
     return;
   }
+
+  // Give the response "verbatim" back.
   echo $response["body"];
 ?>
diff --git a/php/order.php b/php/order.php
index bc6d824..32ffa16 100644
--- a/php/order.php
+++ b/php/order.php
@@ -7,7 +7,7 @@
   function make_order($nonce,
                       $order_id,
                       $now){
-    $contract
+    $order
       = array(
         'nonce' => $nonce,
         'amount' =>
@@ -76,6 +76,6 @@
                           'street' => 'test street 2',
                           'street number' => 202)
                 ));
-    return array ('order' => $contract);
+    return array ('order' => $order);
   }
 ?>
diff --git a/php/pay.php b/php/pay.php
index 921cc70..fd9dcee 100644
--- a/php/pay.php
+++ b/php/pay.php
@@ -14,6 +14,14 @@
 
   $response = post_to_backend("/pay", $body);
   $proposal_data = json_decode($response["body"])->proposal_data;
+  /**
+   * NOTE: the order id is fetched from the data returned by the
+   * backend. This information is then shown in the final page from
+   * the fulfillment URL. This way, if a malicious wallet sends a
+   * old deposit permission for a new donation, then the user can
+   * still detect that, since the old order id would be shown on
+   * the fulfillment page.
+   */
   $_SESSION["order_id"] = $proposal_data->order_id;
   http_response_code($response["status_code"]);
 

-- 
To stop receiving notification emails like this one, please contact
address@hidden