Merge remote-tracking branch 'origin/master' into feature-new-doc
This commit is contained in:
Roberto Abdelkader Martínez Pérez
-226
@@ -1,226 +0,0 @@
|
||||
# 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](https://github.com/BBVA/kapow/releases) section
|
||||
* Install the package with the `get` command (you need the Go runtime installed
|
||||
and [configured](https://golang.org/cmd/go/))
|
||||
```sh
|
||||
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](/spec#http-control-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](/spec#handlers) 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:
|
||||
```sh
|
||||
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:
|
||||
```sh
|
||||
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`:
|
||||
```sh
|
||||
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`
|
||||
```sh
|
||||
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](https://stedolan.github.io/jq/) to allow you to work with JSON
|
||||
from the command line. Check that it works with
|
||||
```sh
|
||||
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:
|
||||
```sh
|
||||
kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/body'
|
||||
```
|
||||
|
||||
then, you execute:
|
||||
```sh
|
||||
kapow server echo.pow
|
||||
```
|
||||
|
||||
and you can check that it works as intended with good ole’ `curl`:
|
||||
```sh
|
||||
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`
|
||||
```sh
|
||||
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](https://www.gnu.org/software/bash/manual/bash.html#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:
|
||||
```sh
|
||||
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`:
|
||||
```sh
|
||||
kapow server log-and-stuff.pow
|
||||
```
|
||||
|
||||
Yup. As simple as that. You can check it.
|
||||
```sh
|
||||
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:
|
||||
```sh
|
||||
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`:
|
||||
```sh
|
||||
kapow server log-and-stuff-callback.pow
|
||||
```
|
||||
|
||||
and finally check it.
|
||||
```sh
|
||||
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
|
||||
|
||||
```sh
|
||||
git clone https://github.com/BBVA/kapow.git
|
||||
```
|
||||
|
||||
|
||||
## Build the kapow! docker image
|
||||
|
||||
```sh
|
||||
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
|
||||
```sh
|
||||
docker run --rm -p 8080:8080 docker server example.pow
|
||||
```
|
||||
|
||||
|
||||
## Build a docker image for running the nmap example
|
||||
```sh
|
||||
cd /path/to/kapow/poc/examples/nmap; docker build -t kapow-nmap .
|
||||
```
|
||||
|
||||
|
||||
## Run kapow
|
||||
```sh
|
||||
docker run \
|
||||
-d \
|
||||
-p 8080:8080 \
|
||||
kapow-nmap
|
||||
```
|
||||
which will output something like this:
|
||||
```sh
|
||||
e7da20c7d9a39624b5c56157176764671e5d2d8f1bf306b3ede898d66fe3f4bf
|
||||
```
|
||||
|
||||
|
||||
## Test /list endpoint
|
||||
|
||||
In another terminal, try running:
|
||||
```sh
|
||||
curl http://localhost:8080/list/github.com
|
||||
```
|
||||
|
||||
which will respond something like:
|
||||
```sh
|
||||
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](/LICENSE).
|
||||
Reference in New Issue
Block a user