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

doc: style fixes and links

Browse Source
This commit is contained in:
pancho horrillo
2019-12-13 15:08:02 +01:00
parent 08086ee66e
commit dea72cbe3a
10 changed files with 86 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/concepts/interfaces.rst
+15 -9
View File
@@ -5,29 +5,35 @@
clear purpose.
User Interface
--------------
.. _http-user-interface:
The `User HTTP Interface` is used to serve final user requests.
HTTP User Interface
-------------------
The `HTTP User Interface` is used to serve final user requests.
By default it binds to address ``0.0.0.0`` and port ``8080``, but that can be
changed via the ``--bind`` flag.
Control Interface
-----------------
.. _http-control-interface:
The `Control HTTP Interface` is used by the command ``kapow route`` to
HTTP Control Interface
----------------------
The `HTTP Control Interface` is used by the command ``kapow route`` to
administer the list of system routes.
By default it binds to address ``127.0.0.1`` and port ``8081``, but that can be
changed via the ``--control-bind`` flag.
Data Interface
--------------
.. _http-data-interface:
The `Data HTTP Interface` is used by the commands ``kapow get`` and ``kapow
HTTP Data Interface
-------------------
The `HTTP Data Interface` is used by the commands ``kapow get`` and ``kapow
set`` to exchange the data for a particular request.
By default it binds to address ``127.0.0.1`` and port ``8082``, but that can be
docs/source/concepts/request_life_cycle.rst
+4 -4
View File
@@ -2,7 +2,7 @@ Request Life Cycle
==================
This section describes the sequence of events happening for each request
answered by the `User HTTP Interface`.
answered by the `HTTP User Interface`.
.. image:: ../_static/request_life_cycle.png
@@ -10,7 +10,7 @@ answered by the `User HTTP Interface`.
1. request
----------
The user makes a request to the `User HTTP Interface`.
The user makes a request to the `HTTP User Interface`.
- The request is matched against the route table.
@@ -30,8 +30,8 @@ The spawned entrypoint is run with the following variables added to its
environment:
- :envvar:`KAPOW_HANDLER_ID`: Containing the `HANDLER_ID`
- :envvar:`KAPOW_DATAAPI_URL`: With the URL of the `Data HTTP Interface`
- :envvar:`KAPOW_CONTROLAPI_URL`: With the URL of the `Control HTTP Interface`
- :envvar:`KAPOW_DATAAPI_URL`: With the URL of the `HTTP Data Interface`
- :envvar:`KAPOW_CONTROLAPI_URL`: With the URL of the `HTTP Control Interface`
3. ``kapow set /response/body banana``
docs/source/concepts/routes.rst
+1 -1
View File
@@ -4,7 +4,7 @@ Routes
======
A *Kapow!* route specifies the matching criteria for an incoming request on
the `User HTTP Interface`, and the details to handle it.
the `HTTP User Interface`, and the details to handle it.
*Kapow!* implements a *route table* where all routes reside.
docs/source/examples/index.rst
+24 -19
View File
@@ -1,18 +1,19 @@
Using a pow File
++++++++++++++++
A ``pow`` file is just a ``bash`` script, where you make calls to the ``kapow route``
command.
A :file:`pow` file is just a :command:`bash` script, where you make calls to the
``kapow route`` command.
**Starting** *Kapow!* **using a** ``pow`` **file**
Starting *Kapow!* using a pow file
----------------------------------
.. code-block:: console
:linenos:
$ kapow server example.pow
With the ``example.pow``:
With the :file:`example.pow`:
.. code-block:: console
:linenos:
@@ -29,14 +30,14 @@ With the ``example.pow``:
.. note::
*Kapow!* can be fully configured using just ``pow`` files
*Kapow!* can be fully configured using just :file:`pow` files
Load More Than One pow File
+++++++++++++++++++++++++++
You can load more than one ``pow`` file at time. This can help you keep your
``pow`` files tidy.
You can load more than one :file:`pow` file at time. This can help you keep
your :file:`pow` files tidy.
.. code-block:: console
:linenos:
@@ -54,7 +55,8 @@ Add a New Route
Be aware that if you register more than one route with exactly the
same path, only the first route added will be used.
**GET route**
GET route
---------
Defining a route:
@@ -72,9 +74,10 @@ Calling route:
$ curl http://localhost:8080/my/route
hello world
**POST route**
POST route
----------
Defining route:
Defining a route:
.. code-block:: console
:linenos:
@@ -82,7 +85,7 @@ Defining route:
$ kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/body'
Calling route:
Calling a route:
.. code-block:: console
:linenos:
@@ -91,9 +94,10 @@ Calling route:
hello world
**Adding URL params**
Adding URL params
-----------------
Defining route:
Defining a route:
.. code-block:: console
:linenos:
@@ -101,7 +105,7 @@ Defining route:
$ kapow route add '/echo/{message}' -c 'kapow get /request/matches/message | kapow set /response/body'
Calling route:
Calling a route:
.. code-block:: console
:linenos:
@@ -115,7 +119,7 @@ Listing Routes
You can list the active routes in the *Kapow!* server.
.. _examples_listing_routes:
.. _listing-routes-example:
.. code-block:: console
:linenos:
@@ -142,16 +146,17 @@ Or, if you want human-readable output, you can use :program:`jq`:
.. note::
*Kapow!* has a `Control HTTP Interface`, bound by default to
``localhost:8081``
*Kapow!* has a :ref:`http-control-interface`, bound by default to
``localhost:8081``.
Deleting Routes
+++++++++++++++
You need the ID of a route to delete it.
Using the :ref:`listing routes example <examples_listing_routes>`, you can
obtain the ID of the route, and then delete it by typing:
Running the command used in the :ref:`listing routes example
<listing-routes-example>`, you can obtain the ID of the route, and then delete
it by typing:
.. code-block:: console
:linenos:
docs/source/the_project/security.rst
+1 -1
View File
@@ -55,7 +55,7 @@ makes this request:
Let's see what happens:
The command that will eventually be executed by ``bash`` is:
The command that will eventually be executed by :command:`bash` is:
.. code-block:: bash
docs/source/tutorial/tutorial01.rst
+23 -23
View File
@@ -1,9 +1,9 @@
Backup that Database!
=====================
Let's Backup that Database!
===========================
**Junior**
A Backup? Don't you have this kind of things already automated?
A Backup? Don't you have this kind of things already automated?
**Senior**
@@ -11,8 +11,8 @@ Backup that Database!
project team ask us for a backup every time a project is finished.
I've already prepared a script to do the task. Before executing it in
production, :download:`download it <./materials/backup_db.sh>` and test it in
your own machine.
production, why don't you :download:`download it <./materials/backup_db.sh>`
and test it in your laptop?
.. code-block:: console
@@ -23,7 +23,7 @@ Backup that Database!
(after a few minutes)
OK, done! When I executed it the output says:
OK, done! I just run it and I got this output:
.. code-block:: console
@@ -35,9 +35,9 @@ Backup that Database!
That's right. That script performed the backup and stored it into the
**Backup Server** and appended some information into the backup log file at
``/tmp/backup_db.log``.
:file:`/tmp/backup_db.log`.
Now you can ``ssh`` into the **Corporate Server** and make the real
Now you can :program:`ssh` into the **Corporate Server** and make the real
backup.
@@ -57,22 +57,21 @@ Backup that Database!
**Senior**
I am the only one allowed to ``ssh`` into the **Corporate Server**, for
I am the only one allowed to :program:`ssh` into the **Corporate Server**, for
obvious reasons.
**Junior**
Why do you need to ``ssh`` in the first place? Couldn't it be done without
``ssh``?
Why do you need to :program:`ssh` in the first place? Couldn't it be done
without :program:`ssh`?
**Senior**
Actually, it could be done with a promising new tool I've just found...
*Kapow!*
Is a tool that allows you to publish scripts as ``HTTP`` services. If we
use it here we can give them the ability to do the backup whenever
they want.
Is a tool that allows you to publish scripts as `HTTP` services. If we use it
here we can give them the ability to do the backup whenever they want.
**Junior**
@@ -92,10 +91,10 @@ 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 project
team wants to perform a backup they only need to call the endpoint and
*Kapow!* will call the backup script.
Don't worry, it is pretty easy. Basically we will provide an `HTTP` 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.
**Junior**
@@ -116,11 +115,11 @@ Backup that Database!
**Junior**
Done! But it doesn't do anything.
Done! But it doesn't seem to do anything...
**Senior**
Now you have the port ``8080`` open but don't have any endpoints defined.
Now you have the port ``8080`` open, but no endpoints have been defined yet.
To define our endpoint you have to run this in another terminal:
.. code-block:: console
@@ -140,7 +139,8 @@ Backup that Database!
Not at all. The creators of *Kapow!* have thought of everything. You can put
all your route definitions in a special script file and pass it to the server
on startup. They call those files `pow` files and they have ``.pow`` extension.
on startup. They call those files :file:`pow` files and they have
:file:`.pow` extension.
It should look something like:
@@ -180,11 +180,11 @@ Backup that Database!
**Junior**
Yay! I can see the log file at ``/tmp/backup_db.log``
Yay! I can see the log file at :file:`/tmp/backup_db.log`
**Senior**
That's great. I am going to install all this in the *Corporate Server* and
That's great. I am going to install all this in the **Corporate Server** and
forget about the old procedure.
That enough for your first day! Go home now and get some rest.
docs/source/tutorial/tutorial02.rst
+7 -7
View File
@@ -3,16 +3,16 @@ What have we done?
**Senior**
Ey, I come from seeing our project team mates. They're delighted with their
Hey, I come from seeing our project team mates. They're delighted with their
new toy, but they miss something.
I forgot to tell you that after the backup is run they need to review the log
file to check that all went OK.
file to check that everything went OK.
**Junior**
Makes sense. Do you think that *Kapow!* can help with this? I have the
feeling that this is the right way to do it...
feeling that this is the right way to go about it...
**Senior**
@@ -27,7 +27,7 @@ What have we done?
**Senior**
Yeah, the team is used to :command:`cat`` the log file contents to see what
Yeah, the team is used to :command:`cat` the log file contents to see what
happened in the last execution:
.. code-block:: console
@@ -38,7 +38,7 @@ What have we done?
**Junior**
Let me try add this to our ``pow`` file:
Let me try add this to our :file:`pow` file:
.. code-block:: console
@@ -47,7 +47,7 @@ What have we 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. Let's restart *Kapow!* and try it.
**Junior**
@@ -56,4 +56,4 @@ What have we done?
**Senior**
Agree. We are done for the day with this...
Agreed. And with this, I think we are done for the day...
docs/source/tutorial/tutorial03.rst
+1 -1
View File
@@ -53,7 +53,7 @@ We need to filter
| kapow set /response/body'
It looks a bit weird, but we'll have time to revise the style later. Please
make some tests on your laptop before we publish it on the *Corporate Server*.
make some tests on your laptop before we publish it on the **Corporate Server**.
Remember to send them an example URL with the parameters they can use to
filter and limit the amount of lines they get.
docs/source/tutorial/tutorial04.rst
+7 -5
View File
@@ -16,7 +16,7 @@ I Need my Report!
**Junior**
Oh. That sounds... fun. OK, tell me about this report.
Oh. That sounds... fun. OK, tell me about this report.
**Senior**
@@ -184,11 +184,11 @@ I Need my Report!
**Senior**
There is a better way. You can make use of another neat ``bash`` feature:
**group commands**.
There is a better way. You can make use of another neat :command:`bash`
feature: `command grouping`_.
Group commands allows you to execute several commands treating the
group as one single command.
Command grouping allows you to execute several commands treating the group as
one single command.
You can use this way:
@@ -226,3 +226,5 @@ I Need my Report!
You know me. Whatever it takes to avoid writing reports ;-)
(both chuckle).
.. _command grouping: https://www.gnu.org/software/bash/manual/html_node/Command-Grouping.html
docs/source/tutorial/tutorial05.rst
+3 -3
View File
@@ -64,7 +64,7 @@ Sharing the Stats
**Senior**
See it for yourself.
See for yourself.
.. code-block:: console
@@ -170,7 +170,7 @@ Sharing the Stats
**Senior**
You are right, but you are not using ``HTTP`` correctly. You have to set the
You are right, but you are not using `HTTP` correctly. You have to set the
``Content-Type`` header to let your client know the format of the data you are
outputting.
@@ -227,5 +227,5 @@ Sharing the Stats
**Senior**
That's perfect! Now, let's upload this to the *Corporate Server* and tell the
That's perfect! Now, let's upload this to the **Corporate Server** and tell the
frontend developer about it.