commit 5381e5b7c1bca94618c3679e98b6bbcbc1251ff3
parent 5ec27b75c8ac9411d9f0ea8eddbe8b4238d52fd7
Author: Christian Grothoff <christian@grothoff.org>
Date: Wed, 5 Aug 2026 21:35:02 +0200
cross-reference paivana with merchant handbooks, and clarify handling of trailing '/'
Diffstat:
3 files changed, 23 insertions(+), 4 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -1445,8 +1445,10 @@ open or deferred.
interface TemplateContractPaivana {
- // Regular expression over URLs for which
- // this template is valid.
+ // POSIX extended regular expression over URLs for which
+ // this template is valid. Matched against the absolute
+ // URL, and anchored: it must match that URL in its
+ // entirety, not merely occur within it.
// Optional, if not given all URLs are accepted.
// Since protocol **v25**.
website_regex?: string;
@@ -1455,6 +1457,15 @@ open or deferred.
choices: TemplateOrderChoice[];
}
+ The backend only stores ``website_regex``; it is the paywall proxy
+ reading these templates that evaluates it. ``paivana-httpd`` matches
+ it against the **absolute** URL of the request (``BASE_URL`` or the
+ scheme and ``Host`` of the request, followed by the path) and anchors
+ it, so an expression written against the path alone, or meant as a
+ substring rule, will not apply. See :ref:`Paivana-Templates` in the
+ :doc:`Paivana operator manual <../taler-paivana-manual>` for the
+ matching rules and worked examples.
+
If exactly one of the ``choices`` of a Paivana template has
``editable_amount`` set, the template may also carry an ``amount`` in its
``editable_defaults`` to tell the user interface to offer a single amount
diff --git a/frags/paivana-httpd-manual.rst b/frags/paivana-httpd-manual.rst
@@ -520,7 +520,11 @@ also enables some required logic in the merchant backend. The
matched against the request URL; ``.*`` covers everything. Each
entry in ``choices`` describes one way the client may pay and is an
:ts:type:`OrderChoice` object (so the paywall can also support
-the use of subscription tokens, discount coupons, etc.).
+the use of subscription tokens, discount coupons, etc.). The
+contract as a whole is the :ts:type:`TemplateContractPaivana` object
+of the :ref:`merchant backend API <merchant-api>`, which stores
+``website_regex`` but leaves its interpretation to ``paivana-httpd``
+— that is, to the rules below.
Two properties of the matching are easy to get wrong, and both make
the difference between a template that applies and one that silently
diff --git a/manpages/paivana.conf.5.rst b/manpages/paivana.conf.5.rst
@@ -109,10 +109,14 @@ TRUSTED_PROXIES6
BASE_URL
Our own Base URL, used if we cannot learn our own base
URL from "Host" or other HTTP headers. Optional but recommended.
+ Write it with a trailing '/', as usual; the trailing slashes are
+ removed before the request path is appended, so the resulting
+ URL never contains a doubled '/'.
DESTINATION_BASE_URL
Base URL of the target HTTP server we forward requests to once
- they have passed the paywall check.
+ they have passed the paywall check. As with BASE_URL, trailing
+ slashes are removed before the request path is appended.
DESTINATION_UNIXPATH
Unix domain socket to connect to when forwarding requests.
