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

doc: normalize style of Kapow!, to be shown italicized

Browse Source 
Co-authored-by: Roberto Abdelkader Martínez Pérez <robertomartinezp@gmail.com>
This commit is contained in:
pancho horrillo
2019-12-10 10:34:39 +01:00
parent 7dc1d5db21
commit bb4aa1a00f
17 changed files with 78 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/_templates/layout.html
+1 -1
View File
@@ -1,6 +1,6 @@
{% extends "!layout.html" %}
{% block menu %}
<a href="index.html">Welcome to Kapow!</a>
<a href="index.html">Welcome to <em>Kapow!</em></a>
{{ super() }}
{% endblock %}
docs/source/concepts/interfaces.rst
+2 -2
View File
@@ -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.
docs/source/concepts/philosophy.rst
+3 -3
View File
@@ -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.
docs/source/concepts/resource_tree.rst
+2 -2
View File
@@ -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.
docs/source/concepts/route_matching.rst
+1 -1
View File
@@ -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.
docs/source/concepts/routes.rst
+5 -5
View File
@@ -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.
docs/source/examples/index.rst
+8 -8
View File
@@ -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:
docs/source/index.rst
+8 -8
View File
@@ -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 <https://github.com/BBVA/kapow/blob/master/AUTHORS.rst>`_.
License
=======
**Kapow!** is Open Source Software and available under the
*Kapow!* is Open Source Software and available under the
`Apache 2 license <https://raw.githubusercontent.com/BBVA/kapow/master/LICENSE>`_.
docs/source/the_project/install_and_configure.rst
+9 -9
View File
@@ -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 <https://github.com/BBVA/kapow/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 <https://golang.org/cmd/go/>`_
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.
docs/source/the_project/quickstart.rst
+14 -14
View File
@@ -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 <quickstart_image>` working we need t
Install Kapow!
++++++++++++++
Follow :doc:`Install Kapow! <install_and_configure>` instructions.
Follow :doc:`Install *Kapow!* <install_and_configure>` 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``.
docs/source/the_project/security.rst
+2 -2
View File
@@ -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.
docs/source/tutorial/index.rst
+5 -5
View File
@@ -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!
docs/source/tutorial/tutorial01.rst
+4 -4
View File
@@ -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 </the_project/install_and_configure>`_.
First of all you have to follow the `installation instructions </the_project/install_and_configure>`_.
**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
docs/source/tutorial/tutorial02.rst
+2 -2
View File
@@ -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**
docs/source/tutorial/tutorial03.rst
+3 -3
View File
@@ -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.
docs/source/tutorial/tutorial04.rst
+5 -5
View File
@@ -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.
docs/source/tutorial/tutorial05.rst
+4 -4
View File
@@ -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