commit 4df238a6568e6da97df0eb9c03877c3fc50dbfe8
parent 4117b2c8b7878dbdecac159a0e916c88d19c264f
Author: Christian Grothoff <christian@grothoff.org>
Date: Wed, 26 Nov 2025 21:04:28 +0100
revise DD76
Diffstat:
1 file changed, 19 insertions(+), 27 deletions(-)
diff --git a/design-documents/076-paywall-proxy.rst b/design-documents/076-paywall-proxy.rst
@@ -18,7 +18,8 @@ Requirements
============
* Must withstand high traffic from bots, requests before a payment happened
- must be *very* cheap.
+ must be *very* cheap, both in terms of response generation and database
+ interaction.
Proposed Solution
=================
@@ -34,24 +35,25 @@ Architecture
Steps:
* Browser visits git.taler.net
-* paivana-httpd checks for a signed cookie
+* paivana-httpd checks for a Paivana cookie
- * If cookie is set and valid request is reverse-proxied to upstream. *Stop.*
+ * If cookie is set and valid, the request is reverse-proxied to upstream. *Stop.*
* Otherwise, a paywall page is rendered, continue.
-* The browser (rendering the paywall page) generates a random session ID via JS.
-* Based on this session ID, a ``taler://pay-template/{mechant_backend}/{template_id}?session_id={session_id}``
+* The browser (rendering the paywall page) generates a random paivana ID via JS.
+* Based on this paivana ID, a ``taler://pay-template/{paivana_backend}/.well-known/paivana/{template_id}?paivana_id={paivana_id}``
URI is generated and rendered as a QR code and link.
-* The browser long-polls on a new ``{merchant_backend}/sessions/{session_id}``
- endpoint that returns when an order with the given session ID has been paid
- for (regardless of the order ID, which is not known at this point).
-* A wallet now needs to instantiate the pay template and pay for the resulting order.
-* Once the long-poller has returned, the paywall makes a ``GET`` fetch request to
- ``{paivana_backend}/paivana-paid/{session_id}``. Paivana checks the payment
- status with the merchant backend. If the payment has succeeded, it returns
- an HTTP response that sets a cookie. The browser reloads the page.
-
-Cookie: The session cookie is computed as ``exp_timestamp || H(client_ip || session_id || exp_timestamp)``
+* The browser long-polls on a ``{paivana_backend}/.well-known/pavivana/paivanas/{paivana_id}``
+ endpoint that returns when an order with the given paivana ID has been paid
+ for (regardless of the order ID, which is not known to the browser).
+* A wallet now needs to instantiate the pay template and pay for the resulting order
+ by talking to the Paivana backend which proxies the requests to the merchant backend
+ and in the process learns the order ID and the payment status change.
+ paivana-httpd may also implement the required subset of the merchant backend itself in the future.
+* When the long-poller returns and the payment has succeeded, the
+ HTTP response sets the Paivana cookie. The browser reloads the page.
+
+The Paivana Cookie is computed as ``exp_timestamp || H(client_ip || paivana_id || paivana_server_secret || exp_timestamp)``.
Problems:
@@ -60,17 +62,11 @@ Problems:
* Solution A: Don't care, unlikely to happen in the first place.
* Solution B: Rate-limit template instantiation on a per-IP basis.
-* The long-polling might overwhelm the merchant
-
- * Should paivana-httpd instead reverse-proxy the long-polling
- to allow rate-limiting the long-polling?
-
Implementation:
-* Merchant needs new endpoint to long-poll on ``session_id``
-* Merchant needs to support template instantiation with ``session_id``.
+* Paivana needs to support extended template instantiation with a ``paivana_id``.
* Paivana component needs to be specified / implemented
-* Wallet-core needs support for a ``session_id`` in pay templates.
+* Wallet-core needs support for a ``paivana_id`` in pay templates.
Test Plan
@@ -95,7 +91,3 @@ Drawbacks
Discussion / Q&A
================
-
-* Do we introduce a new type of session_id for this or can/should we reuse
- the existing session_id feature?
-
