taler-twister-service(1)

24.121. taler-twister-service(1)#

24.121.1. Name#

taler-twister-service - fault-injecting HTTP proxy for GNU Taler tests

24.121.2. Synopsis#

24.121.3. 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.

24.121.4. 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:

[twister]
SERVE = tcp
HTTP_PORT = 8888
DESTINATION_BASE_URL = http://localhost:8080
UNIXPATH = /tmp/taler-service-twister.sock

24.121.5. See Also#

taler-twister(1), taler-unified-setup(1).

24.121.6. Bugs#

Report bugs by using https://bugs.taler.net or by sending electronic mail to <taler@gnu.org>.