a311da0d87
For now, Kapow! treats .pow files as shell scripts, not executables. See https://github.com/BBVA/kapow/issues/62
120 lines
3.1 KiB
ReStructuredText
120 lines
3.1 KiB
ReStructuredText
Working with pow Files
|
|
======================
|
|
|
|
Starting *Kapow!* using a pow file
|
|
----------------------------------
|
|
|
|
A :file:`pow` file is just a :command:`bash` script, where you make calls to the
|
|
``kapow route`` command.
|
|
|
|
.. code-block:: console
|
|
:linenos:
|
|
|
|
$ kapow server example.pow
|
|
|
|
With the :file:`example.pow`:
|
|
|
|
.. code-block:: console
|
|
:linenos:
|
|
|
|
$ cat example.pow
|
|
#
|
|
# This is a simple example of a pow file
|
|
#
|
|
echo '[*] Starting my script'
|
|
|
|
# We add 2 Kapow! routes
|
|
kapow route add /my/route -c 'echo hello world | kapow set /response/body'
|
|
kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/body'
|
|
|
|
.. note::
|
|
|
|
*Kapow!* can be fully configured using just :file:`pow` files
|
|
|
|
|
|
Load More Than One pow File
|
|
---------------------------
|
|
|
|
You can load more than one :file:`pow` file at time. This can help you keep
|
|
your :file:`pow` files tidy.
|
|
|
|
.. code-block:: console
|
|
:linenos:
|
|
|
|
$ ls pow-files/
|
|
example-1.pow example-2.pow
|
|
$ kapow server <(cat pow-files/*.pow)
|
|
|
|
|
|
Writing Multiline pow Files
|
|
---------------------------
|
|
|
|
If you need to write more complex actions, you can leverage multiline commands:
|
|
|
|
.. code-block:: console
|
|
:linenos:
|
|
|
|
$ cat multiline.pow
|
|
kapow route add /log_and_stuff - <<-'EOF'
|
|
echo this is a quite long sentence and other stuff | tee log.txt | kapow set /response/body
|
|
cat log.txt | kapow set /response/body
|
|
EOF
|
|
|
|
.. warning::
|
|
|
|
Be aware of the **"-"** at the end of the ``kapow route add`` command.
|
|
It tells ``kapow route add`` to read commands from `stdin`.
|
|
|
|
.. warning::
|
|
|
|
If you want to learn more about multiline usage, see: `Here Doc
|
|
<https://en.wikipedia.org/wiki/Here_document>`_
|
|
|
|
|
|
Keeping Things Tidy
|
|
-------------------
|
|
|
|
Sometimes things grow, and keeping things tidy is the only way to mantain the
|
|
whole thing.
|
|
|
|
You can distribute your endpoints in several pow files. And you can keep the
|
|
whole thing documented in one html file, served with *Kapow!*.
|
|
|
|
.. code-block:: console
|
|
:linenos:
|
|
|
|
$ cat index.pow
|
|
kapow route add / - <<-'EOF'
|
|
cat howto.html | kapow set /response/body
|
|
EOF
|
|
|
|
source ./info_stuff.pow
|
|
source ./other_endpoints.pow
|
|
|
|
As you can see, the `pow` files can be imported into another `pow` file using
|
|
source. In fact, a `pow` file is just a regular shell script.
|
|
|
|
Debugging scripts
|
|
-----------------
|
|
|
|
Since *Kapow!* redirects the standard output and the standard error of the `pow`
|
|
file given on server startup to its own, you can leverage ``set -x`` to see the
|
|
commands that are being executed, and use that for debugging.
|
|
|
|
To support debugging user request executions, the server subcommand has a
|
|
``--debug`` option flag that prompts *Kapow!* to redirect both the script's
|
|
standard output and standard error to *Kapow!*'s standard output, so you can
|
|
leverage ``set -x`` the same way as with `pow` files.
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
$ cat withdebug.pow
|
|
kapow route add / - <<-'EOF'
|
|
set -x
|
|
echo "This will be seen in the log"
|
|
echo "Hi HTTP" | kapow set /response/body
|
|
EOF
|
|
|
|
$ kapow server --debug withdebug.pow
|