commit d2787b01e2f6047a14656b2ccad3833b1e619495
parent ac4d9ab35788e12d6b7bd517c41c149a89d45298
Author: Christian Grothoff <christian@grothoff.org>
Date: Mon, 9 Nov 2026 21:07:57 +0100
add twister manpages
Diffstat:
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>.