commit c14f9e36837958a471a8a8122b03cd18ae88f5b2
parent f1d757ab32672cc4a84cc8d832c84fc478695e76
Author: Marcello Stanisci <marcello.stanisci@inria.fr>
Date: Wed, 31 May 2017 15:00:09 +0200
explaining base URLs
Diffstat:
2 files changed, 48 insertions(+), 0 deletions(-)
diff --git a/php/doc/tutorial.texi b/php/doc/tutorial.texi
@@ -565,6 +565,7 @@ See below both parts:
* Taler contracts:: Building Taler contracts
* Inline proposals:: Snding proposals with the HTTP header
* The Fulfillment page:: The rationale behind the fulfillment page design
+* Normalized base URLs:: Format URLs are expected to be in Taler
@end menu
@c FIXME. Add section about including images (or extra files in general)
@@ -981,6 +982,26 @@ harm if the operator of instance `a' sees history entries related to instance `b
See @code{https://donations.demo.taler.net/}, which uses this functionality.
+@node Normalized base URLs
+@section Normalized base URLs
+
+Exchanges and merchants have a base URL for their service. This URL @b{must}
+be in a canonical form when it is stored (e.g. in the wallet's database) or
+transmitted (e.g. to a bank page).
+
+@itemize
+@item The URL must be absolute. This implies that the URL has a schema.
+@item The path component of the URL must end with a slash.
+@item The URL must not contain a fragment or query.
+@end itemize
+
+When a user enters a URL that is, technically, relative (such as "alice.example.com/exchange"), wallets
+*may* transform it into a canonical base URL ("http://alice.example.com/exchange/"). Other components *should not* accept
+URLs that are not canonical.
+
+Rationale: Joining non-canonical URLs with relative URLs (e.g. "exchange.example.com" with "reserve/status")
+results in different and slightly unexpected behavior in some URL handling libraries.
+Canonical URLs give more predictable results with standard URL joining.
@c **********************************************************
@c ******************* Appendices *************************
diff --git a/python/doc/tutorial.texi b/python/doc/tutorial.texi
@@ -55,6 +55,7 @@ Texts. A copy of the license is included in the section entitled
@menu
* Introduction:: What this tutorial is about
* Setting up a simple donation page:: How to set up a donation page
+* Advanced topics Detailed solutions to specific issues
Appendices
@@ -470,7 +471,33 @@ should be able to point your browser at @code{http://localhost:5000/}
and make a donation.
+@node Advanced topics
+@chapter Advanced topics
+@menu
+* Normalized base URLs:: Format URLs are expected to be in Taler
+@end menu
+
+@node Normalized base URLs
+@section Normalized base URLs
+
+Exchanges and merchants have a base URL for their service. This URL @b{must}
+be in a canonical form when it is stored (e.g. in the wallet's database) or
+transmitted (e.g. to a bank page).
+
+@itemize
+@item The URL must be absolute. This implies that the URL has a schema.
+@item The path component of the URL must end with a slash.
+@item The URL must not contain a fragment or query.
+@end itemize
+
+When a user enters a URL that is, technically, relative (such as "alice.example.com/exchange"), wallets
+*may* transform it into a canonical base URL ("http://alice.example.com/exchange/"). Other components *should not* accept
+URLs that are not canonical.
+
+Rationale: Joining non-canonical URLs with relative URLs (e.g. "exchange.example.com" with "reserve/status")
+results in different and slightly unexpected behavior in some URL handling libraries.
+Canonical URLs give more predictable results with standard URL joining.
@c **********************************************************
@c ******************* Appendices *************************
