diff --git a/doc/greet-json.rst b/doc/greet-json.rst new file mode 100644 index 0000000..76d851e --- /dev/null +++ b/doc/greet-json.rst @@ -0,0 +1,17 @@ +Working with JSON +================== + +Nowadays webservices are json based so making your script json aware is probably +a good chioce. In order to be able to extract data from and compose json +documents from a script you can use +`jq `_. + +In this example we extract the name field from the incomming json document in +order to generate a two attribute json response. + +.. code-block:: bash + + who=$(kapow get /request/body | jq -r .name) + kapow set /response/headers/Content-Type "application/json" + kapow set /response/status 200 + jq --arg greet "Hello" --arg value "${who:-World}" -n \{greet:\$greet\,to:\$value\} | kapow set /response/body diff --git a/doc/install-and-configure.rst b/doc/install-and-configure.rst new file mode 100644 index 0000000..28c95b7 --- /dev/null +++ b/doc/install-and-configure.rst @@ -0,0 +1,68 @@ +Installing Kapow! +================= + +Kapow! has a reference implementation in Go that is under active develpment +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 `) + +.. code-block:: bash + + go get -u github.com/BBVA/kapow + +Using Kapow! +============ + +Kapow! binary gives you both, a way to start the server and a command line +client to interact with it. + +Running the server +------------------ + +You start a Kapow! server by using the server command ``kapow server``. It +automatically binds the three HTTP modules when it starts: + +- The control server: Used to manage the user defined routes. It exposes the +control API and listens by default in the loopback interface at port 8081. You +can change this configurtation by ussing the +--control-bind : parameter. +- The data server: Allows access to the resources tree to the scripts triggered +by user's requests. It exposes the control API and listens by default in the +loopback interface at port 8082. You can change this configurtation by ussing +the --data-bind : parameter. +- The ``user server``: This server is the one that makes available to the +outside all the routes configured through the control server. It listens by +default in the port 8080 of all configured interfaces (0.0.0.0). You can change this +configurtation by ussing the --bind : parameter. + + + +********--------********--------********----------------********--------********--------******** + +You start a Kapow! server by using the server command ``kapow server``. You can +configure the listen address of the different modules by using the +corresponding parameters: + +- --control-bind :: Allows to manage the user +defined routes. Defaults to 'localhost:8081' (loopback interface). +- --data-bind :: Allows access to the resources +tree to the scripts triggered by user's requests. Defailts to 'localhost:8081' +(loopback interface). +- --bind :: Publishes the routes configured +through the control server to the outside world. Defaults to '0.0.0.0:8080' +(all configured host's interfaces.) + + +Managing routes +--------------- + +Kapow!'s route command allows us to manage the routes that we want to publish +to the outside world. In order to contact with the desired Kapow! server you +can use the ``--control-url`` command line parameter or the KAPOW_CONTROL_URL +environmental variable to set the correct value. + +In the same way the ``--data-url`` command line parameter or the KAPOW_DATA_URL +environmental variable will allow you to set to set the server listen address +when accesing the data server, although this case is less frequent. diff --git a/doc/upload.rst b/doc/upload.rst new file mode 100644 index 0000000..26e73ec --- /dev/null +++ b/doc/upload.rst @@ -0,0 +1,20 @@ +Upload a file +============= + +HTTP request allows us to send and receive files by using the Multipart standard. + +Kapow! allow us to handle files received in the request. In this example we +respond back with the line count of the file received in the request. + +.. code-block:: bash + + fname=$(kapow get /request/files/myfile/filename) + lcount=$(kapow get /request/files/myfile/content | wc -l) + kapow set /response/status 200 + echo "$fname has $lcount lines" | kapow set /response/body + +You can try this by using the following curl: + +.. code-block:: bash + + curl -F "myfile=@README.rst" http://localhost:8080/linecount diff --git a/internal/server/user/spawn/spawn.go b/internal/server/user/spawn/spawn.go index 50f4f4d..1f8140a 100644 --- a/internal/server/user/spawn/spawn.go +++ b/internal/server/user/spawn/spawn.go @@ -44,7 +44,7 @@ func Spawn(h *model.Handler, out io.Writer) error { if out != nil { cmd.Stdout = out } - cmd.Env = append(os.Environ(), "KAPOW_URL=http://localhost:8081") + cmd.Env = append(os.Environ(), "KAPOW_DATA_URL=http://localhost:8082") cmd.Env = append(cmd.Env, "KAPOW_HANDLER_ID="+h.ID) err = cmd.Run() diff --git a/internal/server/user/spawn/spawn_test.go b/internal/server/user/spawn/spawn_test.go index 721f1ba..4e8f359 100644 --- a/internal/server/user/spawn/spawn_test.go +++ b/internal/server/user/spawn/spawn_test.go @@ -104,8 +104,8 @@ func TestSpawnSetsKapowURLEnvVar(t *testing.T) { _ = Spawn(h, out) jldata := decodeJailLover(out.Bytes()) - if v, ok := jldata.Env["KAPOW_URL"]; !ok || v != "http://localhost:8081" { - t.Error("KAPOW_URL is not set properly") + if v, ok := jldata.Env["KAPOW_DATA_URL"]; !ok || v != "http://localhost:8082" { + t.Error("KAPOW_DATA_URL is not set properly") } }