kapow/doc

Installing Kapow!

Kapow! has a reference implementation in Go that is under active development right now. If you want to start using Kapow! you can:

• Download a binary (linux, at this moment) from our releases section
• Install the package with the get command (you need the Go runtime installed and configured)

go get -u github.com/BBVA/kapow

Examples

Below are some examples on how to define and invoke routes in Kapow!

As you will see kapow binary is both a server and a CLI that you can use to configure a running server. The server exposes an API that you can use directly if you want.

In order to get information from the request that fired the script execution and to help you compose the response, the server exposes some resources to interact with from the script.

The mandatory Hello World (for WWW fans)

First, you create a pow file named greet.pow with the following contents:

kapow route add /greet -c 'name=$(kapow get /request/params/name); echo Hello ${name:-World} | kapow set /response/body'

note that you have to escape it as the command will run on a shell itself. Then, you execute:

kapow server greet.pow

to start a Kapow! server exposing your service. Now you can check that it works as intended with good ole’ curl:

curl localhost:8080/greet
Hello World

curl localhost:8080/greet?name=friend
Hello friend

If you want to work with JSON you can use this version of the pow greet-json.pow

kapow route add -X POST /greet -c 'who=$(kapow get /request/body | jq -r .name); kapow set /response/status 201; jq --arg value "${who:-World}" -n \{name:\$value\} | kapow set /response/body'

that uses jq to allow you to work with JSON from the command line. Check that it works with

curl -X POST -H 'Content-Type: application/json' -d '{"name": "friend"}' localhost:8080/greet
{"name": "friend" }

curl -X POST -H 'Content-Type: application/json' -d '' localhost:8080/greet
{"name": "World"}

The mandatory Echo (for UNIX fans)

First, you create a pow file named echo.pow with the following contents:

kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/body'

then, you execute:

kapow server echo.pow

and you can check that it works as intended with good ole’ curl:

curl -X POST -d '1,2,3... testing' localhost:8080/echo
1, 2, 3, 4, 5, 6, 7, 8, 9, testing

If you send a big file and want to see the content back as a real-time stream you can use this version echo-stream.pow

kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/stream'

The multiline fun

Unless you're a hardcore Perl golfer, you'll probably need to write your stuff over more than one line in order to avoid the mess we saw on our JSON greet version.

Don't worry, we need to write several lines, too. Bash, in its magnificent UNIX® style, provides us with the here-documents mechanism that we can leverage precisely for this purpose.

Imagine that we want to return both the standard output and a generated file from a command execution. Let's write a log-and-stuff.pow file with the following content:

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

then we serve it with kapow:

kapow server log-and-stuff.pow

Yup. As simple as that. You can check it.

curl localhost:8080/log_and_stuff
this is a quite long sentence and other stuff
this is a quite long sentence and other stuff

Interact with other systems

You can leverage all the power of the shell in your scripts and interact with other systems by using all the available tools. Write a log-and-stuff-callback.pow file with the following content:

kapow route add /log_and_stuff - <<-'EOF'
	callback_url="$(kapow get /request/params/callback)"
	echo this is a quite long sentence and other stuff | tee log.txt | kapow set /response/body
	echo sending to $callback_url | kapow set /response/body
	curl -X POST --data-binary @log.txt $callback_url | kapow set /response/body
EOF

serve it with kapow:

kapow server log-and-stuff-callback.pow

and finally check it.

curl localhost:8080/log_and_stuff?callback=nowhere.com
this is a quite long sentence and other stuff
sending to nowhere.com
<html>
<head><title>405 Not Allowed</title></head>
<body>
<center><h1>405 Not Allowed</h1></center>
<hr><center>nginx</center>
</body>
</html>

You must be aware that you must have all the dependencies you use in your scripts installed in the host that will run the Kapow! server.

In addition, a pow file can contain as many routes as you like, so you can start a server with several routes configured in one shot.

Sample Docker usage

Clone the project

git clone https://github.com/BBVA/kapow.git

Build the kapow! docker image

make docker

Now you have a container image with all the above pow files copied in /tmp so you can start each example by running

docker run --rm -p 8080:8080 docker server example.pow

Build a docker image for running the nmap example

cd /path/to/kapow/poc/examples/nmap; docker build -t kapow-nmap .

Run kapow

docker run \
	-d \
	-p 8080:8080 \
	kapow-nmap

which will output something like this:

e7da20c7d9a39624b5c56157176764671e5d2d8f1bf306b3ede898d66fe3f4bf

Test /list endpoint

In another terminal, try running:

curl http://localhost:8080/list/github.com

which will respond something like:

Starting Nmap 7.70 ( https://nmap.org ) at 2019-05-10 14:01 UTC
Nmap scan report for github.com (140.82.118.3)
rDNS record for 140.82.118.3: lb-140-82-118-3-ams.github.com
Nmap done: 1 IP address (0 hosts up) scanned in 0.04 seconds

et voilà !

License

This project is distributed under the Apache License 2.0.