taler-docs

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

taler-twister-service.1.rst (4119B)


      1 taler-twister-service(1)
      2 ########################
      3 
      4 .. only:: html
      5 
      6    Name
      7    ====
      8 
      9    **taler-twister-service** - fault-injecting HTTP proxy for GNU Taler tests
     10 
     11 
     12 Synopsis
     13 ========
     14 
     15 **taler-twister-service**
     16 [**-c** *FILENAME* | **--config=**\ ‌\ *FILENAME*]
     17 [**-h** | **--help**]
     18 [**-L** *LOGLEVEL* | **--log=**\ \ *LOGLEVEL*]
     19 [**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*]
     20 [**-v** | **--version**]
     21 
     22 
     23 Description
     24 ===========
     25 
     26 **taler-twister-service** is an HTTP proxy that sits between a REST client
     27 and the service under test.  By default it forwards traffic transparently;
     28 on command it mutates individual requests or responses, so that test code
     29 can exercise the error handling paths that a correct peer never triggers.
     30 It is used by the test suites of the GNU Taler exchange, merchant and bank
     31 components.
     32 
     33 The proxy accepts requests on ``HTTP_PORT`` (or on a UNIX domain socket),
     34 replays each of them against ``DESTINATION_BASE_URL``, and streams the
     35 response back.  Request and response bodies are pumped through libcurl
     36 pause/resume callbacks, so large bodies are not buffered — except where a
     37 mutation needs the whole body, which JSON mutations do.
     38 
     39 Alongside the proxy, the process runs a GNUnet IPC control socket.  Each
     40 control message queues *one* mutation, which is applied to the next request
     41 or response forwarded and then consumed.  Mutations are normally queued
     42 with **taler-twister**; C test harnesses can queue them directly through
     43 **libtalertwister**.
     44 
     45 The service does not usually need to be started by hand: GNUnet's ARM can
     46 start it, and the Taler test harnesses launch it themselves.  Note that it
     47 is a *testing* tool — it offers no authentication on its proxy face,
     48 happily corrupts the traffic it carries, and must not be exposed to an
     49 untrusted network or placed in front of a production service.
     50 
     51 Its options are as follows:
     52 
     53 **-c** *FILENAME* \| **--config=**\ ‌\ *FILENAME*
     54    Use the configuration and other resources for the twister
     55    to operate from *FILENAME*.  The same file must be passed to
     56    **taler-twister** so that it reaches the right control socket.
     57 
     58 **-h** \| **--help**
     59    Print short help on options.
     60 
     61 **-L** *LOGLEVEL* \| **--log=**\ \ *LOGLEVEL*
     62    Configure logging to use *LOGLEVEL*.
     63 
     64 **-l** *FILENAME* \| **--logfile=**\ \ *FILENAME*
     65    Configure logging to write logs to *FILENAME*.
     66 
     67 **-v** \| **–version**
     68    Print version information.
     69 
     70 
     71 Configuration
     72 =============
     73 
     74 All options are read from the “[twister]” section of the GNUnet
     75 configuration file given with **-c**; without that option, the service
     76 reads ``~/.config/twister.conf``.
     77 
     78 SERVE
     79   Should the proxy face listen on a UNIX domain socket (set option to
     80   ``unix``) or on a TCP socket (set option to ``tcp``)?  Mandatory.
     81 
     82 HTTP_PORT
     83   Port on which the proxy face listens, e.g. ``8888``.
     84   Mandatory if ``SERVE`` is ``tcp``.
     85 
     86 SERVE_UNIXPATH
     87   Which unix domain path should the proxy face bind to?
     88   Mandatory if ``SERVE`` is ``unix``.
     89 
     90 SERVE_UNIXMODE
     91   What should be the file access permissions, as an octal number, for
     92   ``SERVE_UNIXPATH``?  Mandatory if ``SERVE`` is ``unix``.
     93 
     94 DESTINATION_BASE_URL
     95   Base URL of the upstream service requests are forwarded to.  Mandatory,
     96   and must *not* end with a slash.
     97 
     98 CHAOS_RATE
     99   Percentage, between 0 and 100, of responses to be replaced by an HTTP 503
    100   “Service unavailable” regardless of any queued mutation.  Defaults to
    101   ``0``, that is, no chaos.  Unlike the queued mutations, this is a
    102   standing setting, read once at startup.
    103 
    104 PORT, HOSTNAME, UNIXPATH
    105   Standard GNUnet service options describing where the *control* face
    106   listens: a TCP port and bind address, a UNIX domain socket path, or both.
    107 
    108 A minimal configuration putting the proxy on port 8888 in front of a
    109 service on port 8080:
    110 
    111 .. code-block:: ini
    112 
    113    [twister]
    114    SERVE = tcp
    115    HTTP_PORT = 8888
    116    DESTINATION_BASE_URL = http://localhost:8080
    117    UNIXPATH = /tmp/taler-service-twister.sock
    118 
    119 
    120 See Also
    121 ========
    122 
    123 taler-twister(1), taler-unified-setup(1).
    124 
    125 
    126 Bugs
    127 ====
    128 
    129 Report bugs by using https://bugs.taler.net or by sending electronic
    130 mail to <taler@gnu.org>.