Dark-Alex-17/kapow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: misc fixes and tweaks

Browse Source 
* doc/README.md:
  - Fix a couple of typos.
  - Fix spacing and shell quote style (for consistency with other markdown docs
  already in the tree).
  - Fix indent with spaces not tabs in heredocs with <<- style¹.
  - Fix shell example partially inserted twice.

* doc/*.pow:
  - Fix indent with spaces not tabs in heredocs with <<- style¹.

¹: See the last paragraph in
https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#Here-Documents

"If the redirection operator is ‘<<-’, then all leading tab characters
are stripped from input lines and the line containing delimiter. This allows
here-documents within shell scripts to be indented in a natural fashion."
This commit is contained in:
pancho horrillo
2019-10-31 18:49:48 +01:00
parent 0639b3af50
commit 28f0ae03d5
3 changed files with 109 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/README.md
+101 -122
View File
@@ -1,13 +1,13 @@
# Installing Kapow! # Installing Kapow!
Kapow! has a reference implementation in Go that is under active develpment right Kapow! has a reference implementation in Go that is under active development right
now. If you want to start using kapow you can: now. If you want to start using Kapow! you can:
* Download a binary (linux, at this moment) from our * Download a binary (linux, at this moment) from our
[releases](https://github.com/BBVA/kapow/releases) section [releases](https://github.com/BBVA/kapow/releases) section
* Install the package with the get command (you need the Go runtime installed * Install the package with the `get` command (you need the Go runtime installed
and [configured](https://golang.org/cmd/go/)) and [configured](https://golang.org/cmd/go/))
```Shell ```sh
go get -u github.com/BBVA/kapow go get -u github.com/BBVA/kapow
``` ```
@@ -15,93 +15,84 @@ and [configured](https://golang.org/cmd/go/))
Below are some examples on how to define and invoke routes in Kapow! Below are some examples on how to define and invoke routes in Kapow!
As you can see Kapow! binary is a server and a CLI that you can use to configure 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 a running server. The server exposes an [API](/spec#http-control-api) that you
can invoke directly if you want. can use directly if you want.
In order to get information from the request that fired the scrip execution and In order to get information from the request that fired the script execution and
to help you in composing the response, the server exposes to help you compose the response, the server exposes
some [resources](/spec#handlers) to interact with from the script. some [resources](/spec#handlers) to interact with from the script.
## The mandatory Hello World (for WWW fans) ## The mandatory Hello World (for WWW fans)
First you create a pow file named `greet.pow` with the following contents: First, you create a pow file named `greet.pow` with the following contents:
```sh
```Shell kapow route add /greet -c 'name=$(kapow get /request/params/name); echo Hello ${name:-World} | kapow set /response/body'
kapow route add /greet -c 'name=$(kapow get /request/params/name); echo Hello ${name:-World} | kapow set /response/body'
``` ```
note you have to escape as the command will run on a shell itself. Then, you note that you have to escape it as the command will run on a shell itself. Then, you
execute: execute:
```sh
```Shell kapow server greet.pow
kapow server greet.pow
``` ```
to start a Kapow! server exposing your service. Now you can check that it works to start a Kapow! server exposing your service. Now you can check that it works
as intended with good ole' ``curl``: as intended with good ole’ `curl`:
```sh
curl localhost:8080/greet
Hello World
```Shell curl localhost:8080/greet?name=friend
curl localhost:8080/greet Hello friend
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 If you want to work with JSON you can use this version of the pow
`greet-json.pow` `greet-json.pow`
```sh
```Shell 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'
kapow route add -X POST /greet -c '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 working with json that uses [jq](https://stedolan.github.io/jq/) to allow you to work with JSON
from the command line. Check that it works with 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" }
```Shell curl -X POST -H 'Content-Type: application/json' -d '' localhost:8080/greet
curl -X POST -H "Content-Type: application/json" -d '{"name": "friend"}' localhost:8080/greet {"name": "World"}
{"name": "friend" }
curl -X POST -H "Content-Type: application/json" -d '' localhost:8080/greet
{"name": "World"}
``` ```
## The mandatory Echo (for UNIX fans) ## The mandatory Echo (for UNIX fans)
First you create a pow file named `echo.pow` with the following contents: First, you create a pow file named `echo.pow` with the following contents:
```sh
```Shell kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/body'
kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/body'
``` ```
then, you execute: then, you execute:
```sh
```Shell kapow server echo.pow
kapow server echo.pow
``` ```
and you can check that it works as intended with good ole' `curl`: and you can check that it works as intended with good ole’ `curl`:
```sh
```Shell curl -X POST -d '1,2,3... testing' localhost:8080/echo
curl -X POST -d '1,2,3... testing' localhost:8080/echo 1, 2, 3, 4, 5, 6, 7, 8, 9, testing
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 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` you can use this version `echo-stream.pow`
```sh
```Shell kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/stream'
kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/stream'
``` ```
## The multiline fun ## The multiline fun
Unless you're a hardcore Perl hacker, you'll probably need to write your stuff 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 over more than one line in order to avoid the mess we saw on our JSON greet
version. version.
Don't worry, we need to write several lines, too. Bash, in its magnificent Don't worry, we need to write several lines, too. Bash, in its magnificent
@@ -109,28 +100,25 @@ UNIX® style, provides us with the
[here-documents](https://www.gnu.org/software/bash/manual/bash.html#Here-Documents) [here-documents](https://www.gnu.org/software/bash/manual/bash.html#Here-Documents)
mechanism that we can leverage precisely for this purpose. mechanism that we can leverage precisely for this purpose.
Imagine we want to return both the standard output and a generated file from a 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: command execution. Let's write a `log-and-stuff.pow` file with the following content:
```sh
```Shell kapow route add /log_and_stuff - <<-'EOF'
kapow route add /log_and_stuff - <<- 'EOF' echo this is a quite long sentence and other stuff | tee log.txt | kapow set /response/body
echo this is a quite long sentence and other stuff | tee log.txt | kapow set /response/body cat log.txt | kapow set /response/body
cat log.txt | kapow set /response/body EOF
EOF
``` ```
then we serve it with `kapow`: then we serve it with `kapow`:
```sh
```Shell kapow server log-and-stuff.pow
kapow server log-and-stuff.pow
``` ```
Yup. As simple as that. You can check it. Yup. As simple as that. You can check it.
```sh
```Shell curl localhost:8080/log_and_stuff
curl localhost:8080/log_and_stuff this is a quite long sentence and other stuff
this is a quite long sentence and other stuff this is a quite long sentence and other stuff
this is a quite long sentence and other stuff
``` ```
@@ -139,104 +127,95 @@ Yup. As simple as that. You can check it.
You can leverage all the power of the shell in your scripts and interact with 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 other systems by using all the available tools. Write a
`log-and-stuff-callback.pow` file with the following content: `log-and-stuff-callback.pow` file with the following content:
```sh
```Shell kapow route add /log_and_stuff - <<-'EOF'
kapow route add /log_and_stuff - <<- 'EOF' callback_url="$(kapow get /request/params/callback)"
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 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
echo sending to $callback_url | kapow set /response/body curl -X POST --data-binary @log.txt $callback_url | kapow set /response/body
curl -X POST --data-binary @log.txt $callback_url | kapow set /response/body EOF
EOF
``` ```
serve it with `kapow`: serve it with `kapow`:
```sh
```Shell kapow server log-and-stuff-callback.pow
kapow server log-and-stuff-callback.pow
``` ```
and finally check it. and finally check it.
```sh
```Shell curl localhost:8080/log_and_stuff?callback=nowhere.com
curl localhost:8080/log_and_stuff?callback=nowhere.com this is a quite long sentence and other stuff
this is a quite long sentence and other stuff sending to nowhere.com
sending to nowhere.com <html>
<html> <head><title>405 Not Allowed</title></head>
<head><title>405 Not Allowed</title></head> <body>
<body> <center><h1>405 Not Allowed</h1></center>
<center><h1>405 Not Allowed</h1></center> <hr><center>nginx</center>
<hr><center>nginx</center> </body>
</body> </html>
</html>
``` ```
You must be aware that you must have all the dependencies you use in your 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. scripts installed in the host that will run the Kapow! server.
In addition, a pow file can contain as much routes as you like so you can start 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 shoot. a server with several routes configured in one shot.
# Sample Docker usage # Sample Docker usage
## Clone the project ## Clone the project
```Shell ```sh
git clone https://github.com/BBVA/kapow.git git clone https://github.com/BBVA/kapow.git
``` ```
## Build the kapow! docker image ## Build the kapow! docker image
```Shell ```sh
make docker make docker
``` ```
Now you have a container image with all the above pow files copied in /tmp so Now you have a container image with all the above pow files copied in /tmp so
you can start each example by running you can start each example by running
```sh
```Shell docker run --rm -p 8080:8080 docker server example.pow
docker run --rm -p 8080:8080 docker server example.pow
``` ```
## Build a docker image for running the nmap example ## Build a docker image for running the nmap example
```sh
```Shell cd /path/to/kapow/poc/examples/nmap; docker build -t kapow-nmap .
cd /path/to/kapow/poc/examples/nmap; docker build -t kapow-nmap .
``` ```
## Run kapow ## Run kapow
```sh
```Shell docker run \
docker run \ -d \
-d \ -p 8080:8080 \
-p 8080:8080 \ kapow-nmap
kapow-nmap
``` ```
which will output something like this: which will output something like this:
```sh
```Shell e7da20c7d9a39624b5c56157176764671e5d2d8f1bf306b3ede898d66fe3f4bf
e7da20c7d9a39624b5c56157176764671e5d2d8f1bf306b3ede898d66fe3f4bf
``` ```
## Test /list endpoint ## Test /list endpoint
In another terminal, try running: In another terminal, try running:
```sh
```Shell curl http://localhost:8080/list/github.com
curl http://localhost:8080/list/github.com
``` ```
which will respond something like: which will respond something like:
```sh
```Shell Starting Nmap 7.70 ( https://nmap.org ) at 2019-05-10 14:01 UTC
Starting Nmap 7.70 ( https://nmap.org ) at 2019-05-10 14:01 UTC Nmap scan report for github.com (140.82.118.3)
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
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
Nmap done: 1 IP address (0 hosts up) scanned in 0.04 seconds
``` ```
et voilà ! et voilà !
doc/log-and-stuff-callback.pow
+5 -5
View File
@@ -1,6 +1,6 @@
kapow route add /log_and_stuff - <<- 'EOF' kapow route add /log_and_stuff - <<-'EOF'
callback_url=$(kapow get /request/params/callback) 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 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 echo sending to $callback_url | kapow set /response/body
curl -X POST --data-binary @log.txt $callback_url | kapow set /response/body curl -X POST --data-binary @log.txt $callback_url | kapow set /response/body
EOF EOF
doc/log-and-stuff.pow
+3 -3
View File
@@ -1,4 +1,4 @@
kapow route add /log_and_stuff - <<- 'EOF' kapow route add /log_and_stuff - <<-'EOF'
echo this is a quite long sentence and other stuff | tee log.txt | kapow set /response/body echo this is a quite long sentence and other stuff | tee log.txt | kapow set /response/body
cat log.txt | kapow set /response/body cat log.txt | kapow set /response/body
EOF EOF