taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

commit d2787b01e2f6047a14656b2ccad3833b1e619495
parent ac4d9ab35788e12d6b7bd517c41c149a89d45298
Author: Christian Grothoff <christian@grothoff.org>
Date:   Mon,  9 Nov 2026 21:07:57 +0100

add twister manpages

Diffstat:
Mconf.py | 14++++++++++++++
Amanpages/taler-twister-service.1.rst | 130+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Amanpages/taler-twister.1.rst | 164+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 308 insertions(+), 0 deletions(-)

diff --git a/conf.py b/conf.py @@ -1227,6 +1227,20 @@ man_pages = [ "GNU Taler contributors", 5, ), + ( + "manpages/taler-twister.1", + "taler-twister", + "arm the next fault injected by a taler-twister-service", + "GNU Taler contributors", + 1, + ), + ( + "manpages/taler-twister-service.1", + "taler-twister-service", + "fault-injecting HTTP proxy for GNU Taler tests", + "GNU Taler contributors", + 1, + ), ] # If true, show URL addresses after external links. diff --git a/manpages/taler-twister-service.1.rst b/manpages/taler-twister-service.1.rst @@ -0,0 +1,130 @@ +taler-twister-service(1) +######################## + +.. only:: html + + Name + ==== + + **taler-twister-service** - fault-injecting HTTP proxy for GNU Taler tests + + +Synopsis +======== + +**taler-twister-service** +[**-c** *FILENAME* | **--config=**\ ‌\ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--log=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-v** | **--version**] + + +Description +=========== + +**taler-twister-service** is an HTTP proxy that sits between a REST client +and the service under test. By default it forwards traffic transparently; +on command it mutates individual requests or responses, so that test code +can exercise the error handling paths that a correct peer never triggers. +It is used by the test suites of the GNU Taler exchange, merchant and bank +components. + +The proxy accepts requests on ``HTTP_PORT`` (or on a UNIX domain socket), +replays each of them against ``DESTINATION_BASE_URL``, and streams the +response back. Request and response bodies are pumped through libcurl +pause/resume callbacks, so large bodies are not buffered — except where a +mutation needs the whole body, which JSON mutations do. + +Alongside the proxy, the process runs a GNUnet IPC control socket. Each +control message queues *one* mutation, which is applied to the next request +or response forwarded and then consumed. Mutations are normally queued +with **taler-twister**; C test harnesses can queue them directly through +**libtalertwister**. + +The service does not usually need to be started by hand: GNUnet's ARM can +start it, and the Taler test harnesses launch it themselves. Note that it +is a *testing* tool — it offers no authentication on its proxy face, +happily corrupts the traffic it carries, and must not be exposed to an +untrusted network or placed in front of a production service. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ ‌\ *FILENAME* + Use the configuration and other resources for the twister + to operate from *FILENAME*. The same file must be passed to + **taler-twister** so that it reaches the right control socket. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--log=**\ \ *LOGLEVEL* + Configure logging to use *LOGLEVEL*. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Configure logging to write logs to *FILENAME*. + +**-v** \| **–version** + Print version information. + + +Configuration +============= + +All options are read from the “[twister]” section of the GNUnet +configuration file given with **-c**; without that option, the service +reads ``~/.config/twister.conf``. + +SERVE + Should the proxy face listen on a UNIX domain socket (set option to + ``unix``) or on a TCP socket (set option to ``tcp``)? Mandatory. + +HTTP_PORT + Port on which the proxy face listens, e.g. ``8888``. + Mandatory if ``SERVE`` is ``tcp``. + +SERVE_UNIXPATH + Which unix domain path should the proxy face bind to? + Mandatory if ``SERVE`` is ``unix``. + +SERVE_UNIXMODE + What should be the file access permissions, as an octal number, for + ``SERVE_UNIXPATH``? Mandatory if ``SERVE`` is ``unix``. + +DESTINATION_BASE_URL + Base URL of the upstream service requests are forwarded to. Mandatory, + and must *not* end with a slash. + +CHAOS_RATE + Percentage, between 0 and 100, of responses to be replaced by an HTTP 503 + “Service unavailable” regardless of any queued mutation. Defaults to + ``0``, that is, no chaos. Unlike the queued mutations, this is a + standing setting, read once at startup. + +PORT, HOSTNAME, UNIXPATH + Standard GNUnet service options describing where the *control* face + listens: a TCP port and bind address, a UNIX domain socket path, or both. + +A minimal configuration putting the proxy on port 8888 in front of a +service on port 8080: + +.. code-block:: ini + + [twister] + SERVE = tcp + HTTP_PORT = 8888 + DESTINATION_BASE_URL = http://localhost:8080 + UNIXPATH = /tmp/taler-service-twister.sock + + +See Also +======== + +taler-twister(1), taler-unified-setup(1). + + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-twister.1.rst b/manpages/taler-twister.1.rst @@ -0,0 +1,164 @@ +taler-twister(1) +################ + +.. only:: html + + Name + ==== + + **taler-twister** - arm the next fault injected by a taler-twister-service + + +Synopsis +======== + +**taler-twister** +[**-a** | **--checkalive**] +[**-c** *FILENAME* | **--config=**\ ‌\ *FILENAME*] +[**-d** *PATH* | **--deleteobject=**\ \ *PATH*] +[**-F** *PATH* | **--flip-ul=**\ \ *PATH*] +[**-f** *PATH* | **--flip-dl=**\ \ *PATH*] +[**-H** *HEADER* | **--modify-header-dl=**\ \ *HEADER*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--log=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-M** | **--malform**] +[**-m** *PATH* | **--modify-dl=**\ \ *PATH*] +[**-r** *STATUS* | **--responsecode=**\ \ *STATUS*] +[**-U** | **--malformupload**] +[**-V** *VALUE* | **--value=**\ \ *VALUE*] +[**-v** | **--version**] +[**-X** *PATH* | **--modify-ul=**\ \ *PATH*] + + +Description +=========== + +**taler-twister** is a command-line tool to arm the next fault injected by +a running **taler-twister-service**, the fault-injecting HTTP proxy used +by the GNU Taler test suites. + +Each invocation connects to a running service over its GNUnet IPC socket, +queues the mutations named by the options given, waits for the service to +acknowledge them and exits. A queued mutation applies to the *next* +request or response the proxy forwards, and is consumed by it; a test +script therefore invokes **taler-twister** once before every HTTP request +whose handling it wants to break. Several options may be combined in one +invocation, each queueing its own mutation. + +The service to talk to is selected by the configuration file: pass the +*same* **-c** option that the service was started with, so that both agree +on the control socket. + +Mutations are either *download* scoped, altering the response travelling +from the upstream service back to the client, or *upload* scoped, altering +the request travelling from the client to the upstream service. + +Options taking a *PATH* address a position inside a JSON body in +object-dotted notation: field names and array indices are separated by +dots, so ``f1.f2.0`` denotes the string ``x`` in ``{"f1":{"f2":["x"]}}``. +Any such mutation forces the affected body to be buffered in full and +re-serialized; bodies sent with ``Content-Encoding: deflate`` are +transparently inflated first, so that paths resolve against the +decompressed JSON. + +Its options are as follows: + +**-a** \| **--checkalive** + Do not queue any mutation, only check that the service accepts IPC + connections. Exits with status 0 if the connection succeeded. This is + what test harnesses use to wait for a freshly launched service. + +**-c** *FILENAME* \| **--config=**\ ‌\ *FILENAME* + Use the configuration and other resources for the twister + to operate from *FILENAME*. + +**-d** *PATH* \| **--deleteobject=**\ \ *PATH* + Delete the JSON object at *PATH* from the next response. + +**-F** *PATH* \| **--flip-ul=**\ \ *PATH* + Flip a random character of the *string* at *PATH* in the next request. + The field must be a JSON string. + +**-f** *PATH* \| **--flip-dl=**\ \ *PATH* + Flip a random character of the *string* at *PATH* in the next response. + The field must be a JSON string. + +**-H** *HEADER* \| **--modify-header-dl=**\ \ *HEADER* + Replace the value of the HTTP response header *HEADER* in the next + response. Requires **--value**. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--log=**\ \ *LOGLEVEL* + Configure logging to use *LOGLEVEL*. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Configure logging to write logs to *FILENAME*. + +**-M** \| **--malform** + Truncate the next response at a random position. + +**-m** *PATH* \| **--modify-dl=**\ \ *PATH* + Set the JSON value at *PATH* in the next response. Requires + **--value**. + +**-r** *STATUS* \| **--responsecode=**\ \ *STATUS* + Replace the HTTP status code of the next response with *STATUS*. + +**-U** \| **--malformupload** + Truncate the next request at a random position. + +**-V** *VALUE* \| **--value=**\ \ *VALUE* + The new value for **--modify-dl**, **--modify-ul** or + **--modify-header-dl**. Note that *VALUE* is always set as a JSON + string, except for the literals ``true`` and ``false``; numbers cannot + be injected as JSON numbers in this version. + +**-v** \| **–version** + Print version information. + +**-X** *PATH* \| **--modify-ul=**\ \ *PATH* + Set the JSON value at *PATH* in the next request. Requires + **--value**. + + +Exit Status +=========== + +0 if every queued mutation was acknowledged (or, with **--checkalive**, if +the service could be reached), 3 if the command line could not be parsed, +and 1 otherwise, in particular if the service is not running or rejected a +mutation. + + +Examples +======== + +Make the next proxied response come back as HTTP 500: + +.. code-block:: console + + $ taler-twister -c twister.conf -r 500 + +Remove the ``signature`` field from the ``deposit`` object of the next +response, and corrupt one character of the next uploaded ``coin_pub`` +field: + +.. code-block:: console + + $ taler-twister -c twister.conf -d deposit.signature -F coin_pub + + +See Also +======== + +taler-twister-service(1), taler-unified-setup(1). + + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>.