diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html index 82859f0..0c206d2 100644 --- a/docs/source/_templates/layout.html +++ b/docs/source/_templates/layout.html @@ -1,6 +1,6 @@ {% extends "!layout.html" %} {% block menu %} - Welcome to Kapow! + Welcome to Kapow! {{ super() }} {% endblock %} diff --git a/docs/source/concepts/interfaces.rst b/docs/source/concepts/interfaces.rst index d09c92d..6b5d2d3 100644 --- a/docs/source/concepts/interfaces.rst +++ b/docs/source/concepts/interfaces.rst @@ -1,5 +1,5 @@ -Kapow! HTTP Interfaces -====================== +*Kapow!* HTTP Interfaces +======================== `kapow server` sets up three HTTP server interfaces, each with a distinct and clear purpose. diff --git a/docs/source/concepts/philosophy.rst b/docs/source/concepts/philosophy.rst index d6b9731..7eb4c0b 100644 --- a/docs/source/concepts/philosophy.rst +++ b/docs/source/concepts/philosophy.rst @@ -13,7 +13,7 @@ Single Static Binary Shell Agnostic -------------- -- Kapow! knows nothing, and makes no assumptions, about the shell you are using. +- *Kapow!* knows nothing, and makes no assumptions, about the shell you are using. It only spawns executables. - You are free to implement a client to the Data API directly if you are so @@ -23,9 +23,9 @@ Shell Agnostic Not a Silver Bullet ------------------- -You should not use Kapow! if your project requires complex business logic. +You should not use *Kapow!* if your project requires complex business logic. If you try to encode business logic in a shell script, you will **deeply** regret it. -Kapow! is designed for automating simple stuff. +*Kapow!* is designed for automating simple stuff. diff --git a/docs/source/concepts/resource_tree.rst b/docs/source/concepts/resource_tree.rst index 5611b93..94b31d2 100644 --- a/docs/source/concepts/resource_tree.rst +++ b/docs/source/concepts/resource_tree.rst @@ -1,7 +1,7 @@ -The `Kapow!` Resource Tree +The *Kapow!* Resource Tree ========================== -This is the model that Kapow! uses to expose the internals of the user request +This is the model that *Kapow!* uses to expose the internals of the user request being serviced. diff --git a/docs/source/concepts/route_matching.rst b/docs/source/concepts/route_matching.rst index c77d75b..dd3562d 100644 --- a/docs/source/concepts/route_matching.rst +++ b/docs/source/concepts/route_matching.rst @@ -1,7 +1,7 @@ Route Matching ============== -Kapow! maintains a route table with a list of routes as provided by the user, +*Kapow!* maintains a route table with a list of routes as provided by the user, and uses it to determine which handler should an incoming request be dispatched to. diff --git a/docs/source/concepts/routes.rst b/docs/source/concepts/routes.rst index d262ffd..66f3f84 100644 --- a/docs/source/concepts/routes.rst +++ b/docs/source/concepts/routes.rst @@ -1,10 +1,10 @@ Routes ====== -A Kapow! route specifies the matching criteria for an incoming request on +A *Kapow!* route specifies the matching criteria for an incoming request on the `User HTTP Interface`, and the details to handle it. -Kapow! implements a *route table* where all routes reside. +*Kapow!* implements a *route table* where all routes reside. A route can be set like this: @@ -39,7 +39,7 @@ Uniquely identifies each route. It is used for instance by ``kapow route remove .. note:: - The current implementation of Kapow! autogenerates a `UUID` for this field. + The current implementation of *Kapow!* autogenerates a `UUID` for this field. In the future the use will be able to specify a custom value. @@ -61,7 +61,7 @@ It can contain regex placeholders for easily capturing fragments of the path. In the route shown above, a request with a URL ``/register/joe`` would match, assigning `joe` to the placeholder ``username``. -Kapow! leverages Gorilla Mux for managing routes. For the full story, see +*Kapow!* leverages Gorilla Mux for managing routes. For the full story, see https://github.com/gorilla/mux#examples @@ -115,7 +115,7 @@ incantation to be executed: Matching Algorithm ------------------ -`Kapow!` leverages Gorilla Mux for this task. You can see the gory details in +`*Kapow!*` leverages Gorilla Mux for this task. You can see the gory details in their documentation. diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst index b692487..1b037bc 100644 --- a/docs/source/examples/index.rst +++ b/docs/source/examples/index.rst @@ -5,7 +5,7 @@ A ``.pow`` file is just a ``bash`` script, where you make calls to the ``kapow r command. -**Starting Kapow! using a .pow file** +**Starting** *Kapow!* **using a .pow file** .. code-block:: console :linenos: @@ -29,7 +29,7 @@ With the example.pow: .. note:: - **Kapow!** can be fully configured using just ``.pow`` files + *Kapow!* can be fully configured using just ``.pow`` files Load More Than One ``.pow`` File @@ -122,7 +122,7 @@ Calling route: Listing Routes ++++++++++++++ -You can list the active routes in the **Kapow!** server. +You can list the active routes in the *Kapow!* server. .. _examples_listing_routes: @@ -151,7 +151,7 @@ Or, if you want human-readable output, you can use :samp:`jq`: .. note:: - **Kapow!** has an `HTTP` admin interface, by default listening at **localhost:8081** + *Kapow!* has an `HTTP` admin interface, by default listening at **localhost:8081** Deleting Routes @@ -253,7 +253,7 @@ Modify JSON by Using Shell Commands **Example 1** -In this example our **Kapow!** service will receive a JSON value with an incorrect +In this example our *Kapow!* service will receive a JSON value with an incorrect date, then our ``.pow`` file will fix it and return the correct value to the user. .. code-block:: console @@ -312,7 +312,7 @@ Upload Files **Example 1** -Uploading a file using **Kapow!** is very simple: +Uploading a file using *Kapow!* is very simple: .. code-block:: console :linenos: @@ -485,7 +485,7 @@ In this example we'll redirect our users to Google: How to Execute Two Processes in Parallel ++++++++++++++++++++++++++++++++++++++++ -We want to :samp:`ping` two machines parallel. **Kapow!** gets IPs from query +We want to :samp:`ping` two machines parallel. *Kapow!* gets IPs from query params: .. code-block:: console @@ -508,7 +508,7 @@ Calling with ``curl``: Manage Cookies ++++++++++++++ -If you track down some user state, **Kapow!** allows you manage Request/Response +If you track down some user state, *Kapow!* allows you manage Request/Response Cookies. In the next example we'll set a cookie: diff --git a/docs/source/index.rst b/docs/source/index.rst index f78955b..c9bbfe6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,5 +1,5 @@ -Welcome to Kapow! -================= +Welcome to *Kapow!* +=================== .. image:: https://circleci.com/gh/BBVA/kapow/tree/master.svg?style=svg :target: https://circleci.com/gh/BBVA/kapow/tree/master @@ -13,11 +13,11 @@ Welcome to Kapow! **If you can script it, you can HTTP it** -What's Kapow! -============= +What's *Kapow!* +=============== Think of that **software** that you need but **only runs in the command - line**. **Kapow!** lets you **wrap it into an HTTP API without writing a + line**. *Kapow!* lets you **wrap it into an HTTP API without writing a single line of code**. .. image:: _static/kapow-quick-overview.png @@ -26,20 +26,20 @@ What's Kapow! Want to know more? Check the :doc:`the_project/quickstart` section for a longer explanation of - what **Kapow!** does. + what *Kapow!* does. Authors ======= - **Kapow!** is being developed by the + *Kapow!* is being developed by the `BBVA-Labs Security team `_. License ======= - **Kapow!** is Open Source Software and available under the + *Kapow!* is Open Source Software and available under the `Apache 2 license `_. diff --git a/docs/source/the_project/install_and_configure.rst b/docs/source/the_project/install_and_configure.rst index 9993fae..0de1c9a 100644 --- a/docs/source/the_project/install_and_configure.rst +++ b/docs/source/the_project/install_and_configure.rst @@ -1,8 +1,8 @@ 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 choose from several +*Kapow!* has a reference implementation in ``Go`` that is under active development +right now. If you want to start using *Kapow!* you can choose from several options. @@ -12,7 +12,7 @@ Download and Install a Binary Binaries for several platforms are available from the `releases `_ section, visit the latest release page and download the binary corresponding to the platfom and -architecture you want to install **Kapow!** in. +architecture you want to install *Kapow!* in. Linux @@ -36,19 +36,19 @@ Install the package with go get ------------------------------- If you already have `installed and configured `_ -the ``go`` runtime in the host where you want to run **Kapow!**, simply run: +the ``go`` runtime in the host where you want to run *Kapow!*, simply run: .. code-block:: bash $ go get -u github.com/BBVA/kapow -Include Kapow! in your Container Image --------------------------------------- +Include *Kapow!* in your Container Image +---------------------------------------- -If you want to include **Kapow!** in a ``Docker`` image you can add the binary +If you want to include *Kapow!* in a ``Docker`` image you can add the binary directly from the releases section. Following is an example ``Dockerfile`` that -includes **Kapow!**. +includes *Kapow!*. .. code-block:: dockerfile @@ -74,4 +74,4 @@ After building the image you can run the container with: $ docker run --rm -i -p 8080:8080 -v $(pwd)/whatever.pow:/opt/whatever.pow kapow:latest server /opt/whatever.pow With the `-v` parameter we map a local file into the container's filesystem so -we can use it to configure our **Kapow!** server on startup. +we can use it to configure our *Kapow!* server on startup. diff --git a/docs/source/the_project/quickstart.rst b/docs/source/the_project/quickstart.rst index e49fd73..390ca5f 100644 --- a/docs/source/the_project/quickstart.rst +++ b/docs/source/the_project/quickstart.rst @@ -1,7 +1,7 @@ Quick Start Guide ================= -We'll explain a simple example to help you understand what **Kapow!** can do and +We'll explain a simple example to help you understand what *Kapow!* can do and why it is so awesome :-). @@ -75,17 +75,17 @@ Reasons: 2. Need to spend time (and time is money, see reason #1) -Using Kapow! (spoiler: it's the winner!) -++++++++++++++++++++++++++++++++++++++++ +Using *Kapow!* (spoiler: it's the winner!) +++++++++++++++++++++++++++++++++++++++++++ -Ok, let's analyze **Kapow!** and check if it is compatible with our constraints: +Ok, let's analyze *Kapow!* and check if it is compatible with our constraints: -1. **Kapow!** is Open Source, so **it's also free as in beer**. +1. *Kapow!* is Open Source, so **it's also free as in beer**. 2. By using kapow! we don't need to code our own solution, so we **don't have to waste time**. -3. By using Kapow! we can run any command in the :samp:`External Host` limiting the command parameters, so **it's safe**. -4. By using Kapow! we can launch any system command as an HTTP API easily, so **we don't need to grant login access to anybody to** :samp:`External Host`. +3. By using *Kapow!* we can run any command in the :samp:`External Host` limiting the command parameters, so **it's safe**. +4. By using *Kapow!* we can launch any system command as an HTTP API easily, so **we don't need to grant login access to anybody to** :samp:`External Host`. -Conclusion: **Kapow! is the best choice.** +Conclusion: *Kapow!* **is the best choice.** Reasons: It satisfies all of our requirements. @@ -99,13 +99,13 @@ In order to get our example :ref:`Scenario ` working we need t Install Kapow! ++++++++++++++ -Follow :doc:`Install Kapow! ` instructions. +Follow :doc:`Install *Kapow!* ` instructions. Write a ``ping.pow`` File +++++++++++++++++++++++++ -Kapow! uses plain text files (called ``POW`` files) so you can define the +*Kapow!* uses plain text files (called ``POW`` files) so you can define the endpoints you want to expose the system command with. For our example we need a file like this: @@ -116,8 +116,8 @@ file like this: Explanation: -1. :samp:`kapow route add /ping` - adds a new HTTP API endpoint at :samp:`/ping` path in the Kapow! server. You have to use `GET` method to invoke the endpoint. -2. :samp:`-c` - after this parameter we write the system command that **Kapow!** will run each time the endpoint is invoked. +1. :samp:`kapow route add /ping` - adds a new HTTP API endpoint at :samp:`/ping` path in the *Kapow!* server. You have to use `GET` method to invoke the endpoint. +2. :samp:`-c` - after this parameter we write the system command that *Kapow!* will run each time the endpoint is invoked. 3. :samp:`ping -c 1 10.10.10.100` - sends 1 ping package to the host *10.10.10.100*, i.e. :samp:`Internal Host`. 4. :samp:`| kapow set /response/body` - writes the output of `ping` to the body of the response, so you can see it. @@ -150,12 +150,12 @@ et voilà ! Under the Hood ++++++++++++++ -To understand what's happening under the hood with **Kapow!** let's see the +To understand what's happening under the hood with *Kapow!* let's see the following diagram: .. image:: /_static/sequence.png :align: center :width: 80% -As you can see, **Kapow!** provides the necessary *magic* to turn a **system +As you can see, *Kapow!* provides the necessary *magic* to turn a **system command** into an ``HTTP API``. diff --git a/docs/source/the_project/security.rst b/docs/source/the_project/security.rst index e0bdc5a..83dfcec 100644 --- a/docs/source/the_project/security.rst +++ b/docs/source/the_project/security.rst @@ -4,7 +4,7 @@ Security Concerns Special care has to be taken when using parameters provided by the user when composing command line invocations. -Sanitizing user input is not a new problem, but in the case of **Kapow!**, we +Sanitizing user input is not a new problem, but in the case of *Kapow!*, we have to take into account also the way that the shell parses its arguments, as well as the way the command itself interprets them, in order to get it right. @@ -81,6 +81,6 @@ Let's see how we can handle this particular case: .. note:: - Since this is critical for keeping your Kapow! services secure, we are working + Since this is critical for keeping your *Kapow!* services secure, we are working on a way to make this more transparent and safe, while at the same time keeping it Kapowy. diff --git a/docs/source/tutorial/index.rst b/docs/source/tutorial/index.rst index a826677..98aa4f5 100644 --- a/docs/source/tutorial/index.rst +++ b/docs/source/tutorial/index.rst @@ -1,13 +1,13 @@ -Kapow! Tutorial -=============== +*Kapow!* Tutorial +================= - This tutorial will allow you to grow slowly in the knowledge of Kapow!. It + This tutorial will allow you to grow slowly in the knowledge of *Kapow!*. It tells you the story of a senior ops guy just arrived to his new job in a small company. He'll face different challenges of increasing difficulty, but with - the help of his experienced senior mate and Kapow! he will be able to satisfy + the help of his experienced senior mate and *Kapow!* he will be able to satisfy all the requierements. You just only need to follow the steps and execute the code shown in the - tutorial to learn the Kapow! way of doing. + tutorial to learn the *Kapow!* way of doing. Have a nice trip to Kapow! diff --git a/docs/source/tutorial/tutorial01.rst b/docs/source/tutorial/tutorial01.rst index b098cad..635dafc 100644 --- a/docs/source/tutorial/tutorial01.rst +++ b/docs/source/tutorial/tutorial01.rst @@ -78,7 +78,7 @@ Backup that Database! Ok then, let's try on your laptop first. - First of all you have to follow the `installation instructions `_. + First of all you have to follow the `installation instructions `_. **Junior** @@ -88,9 +88,9 @@ Backup that Database! **Senior** Don't worry it is pretty easy. Basically we will provide an HTTP - endpoint managed by Kapow! at the **Corporate Server**; when the + endpoint managed by *Kapow!* at the **Corporate Server**; when the project team wants to perform a backup they only need to call the - endpoint and Kapow! will call the backup script. + endpoint and *Kapow!* will call the backup script. **Junior** @@ -145,7 +145,7 @@ Backup that Database! $ cat backup.pow kapow route add -X PUT /db/backup -e ./backup_db.sh - And then you can start Kapow! with it: + And then you can start *Kapow!* with it: .. code-block:: console diff --git a/docs/source/tutorial/tutorial02.rst b/docs/source/tutorial/tutorial02.rst index d93f761..5dab36c 100644 --- a/docs/source/tutorial/tutorial02.rst +++ b/docs/source/tutorial/tutorial02.rst @@ -11,7 +11,7 @@ What we've done? **Junior** - Makes sense. Do you think that Kapow! can help with this? I feel that this is + Makes sense. Do you think that *Kapow!* can help with this? I feel that this is the way to do it. **Senior** @@ -47,7 +47,7 @@ What we've done? **Senior** Looks good to me, clean and simple, and it is a very good idea to use ``GET`` - here as it wont change anything in the server. Restart Kapow! and try it. + here as it wont change anything in the server. Restart *Kapow!* and try it. **Junior** diff --git a/docs/source/tutorial/tutorial03.rst b/docs/source/tutorial/tutorial03.rst index d254b7a..68934a1 100644 --- a/docs/source/tutorial/tutorial03.rst +++ b/docs/source/tutorial/tutorial03.rst @@ -19,9 +19,9 @@ We need to filter **Senior** By sure, but in addition to some good shell plumbing we're going to squeeze - Kapow!'s superpowers a litle bit more to get a really good solution. + *Kapow!*'s superpowers a litle bit more to get a really good solution. - Can you take a look at Kapow!'s documentation to see if something can be done? + Can you take a look at *Kapow!*'s documentation to see if something can be done? **Junior** @@ -31,7 +31,7 @@ We need to filter **Senior** - Sounds great! How we have lived without Kapow! all this time? + Sounds great! How we have lived without *Kapow!* all this time? As they requested, we can offer them with a parameter to filter the registers they want to pick and another parameter to limit the output size in lines. diff --git a/docs/source/tutorial/tutorial04.rst b/docs/source/tutorial/tutorial04.rst index 7b777ba..5b1f879 100644 --- a/docs/source/tutorial/tutorial04.rst +++ b/docs/source/tutorial/tutorial04.rst @@ -27,7 +27,7 @@ I Need My Report We prepare a report with some statistics about the load of our servers. This way we know when we have to buy another one. - + **Junior** I see this company scales just like Google. @@ -58,7 +58,7 @@ I Need My Report **Junior** - Well, I guess we can make a Kapow! endpoint to let her see all this + Well, I guess we can make a *Kapow!* endpoint to let her see all this information from the browser. This way she doesn't need to waste any time asking us. @@ -102,7 +102,7 @@ I Need My Report Memory: ... the output of `free -m` ... ================================================================================ - ... and so on ... + ... and so on ... **Junior** @@ -136,13 +136,13 @@ I Need My Report more than one line here EOF - + The shell will put the data between the first ``EOF`` and the second ``EOF`` as the ``stdin`` of the ``cat`` process. **Junior** - If I want to use this with Kapow! I have to make it read the script + If I want to use this with *Kapow!* I have to make it read the script from ``stdin``. To do this I know that I have to put a ``-`` at the end. diff --git a/docs/source/tutorial/tutorial05.rst b/docs/source/tutorial/tutorial05.rst index dd15a96..55bb4b9 100644 --- a/docs/source/tutorial/tutorial05.rst +++ b/docs/source/tutorial/tutorial05.rst @@ -85,7 +85,7 @@ Sharing the Stats **Junior** - Let's use it then! + Let's use it then! How can we generate a JSON document with ``jq``? @@ -157,7 +157,7 @@ Sharing the Stats EOF What do you think? - + **Senior** You forgot one more thing. @@ -196,9 +196,9 @@ Sharing the Stats Just a couple of details. 1. You have to set the headers **before** the body. This is because the body - can be so big that Kapow! is forced to start sending it out. + can be so big that *Kapow!* is forced to start sending it out. 2. In cases where you want to set a small piece of data (like the header) is - better to not use the ``stdin``. Kapow! provides a secondary syntax for these + better to not use the ``stdin``. *Kapow!* provides a secondary syntax for these cases: .. code-block:: console