taler-twister(1)

24.122. taler-twister(1)#

24.122.1. Name#

taler-twister - arm the next fault injected by a taler-twister-service

24.122.2. Synopsis#

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

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

24.122.5. Examples#

Make the next proxied response come back as HTTP 500:

$ 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:

$ taler-twister -c twister.conf -d deposit.signature -F coin_pub

24.122.6. See Also#

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

24.122.7. Bugs#

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