diff --git a/docs/source/concepts/interfaces.rst b/docs/source/concepts/interfaces.rst index 7a6bd51..b84eac1 100644 --- a/docs/source/concepts/interfaces.rst +++ b/docs/source/concepts/interfaces.rst @@ -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 diff --git a/docs/source/concepts/request_life_cycle.rst b/docs/source/concepts/request_life_cycle.rst index 8703cc3..bd02b04 100644 --- a/docs/source/concepts/request_life_cycle.rst +++ b/docs/source/concepts/request_life_cycle.rst @@ -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`` diff --git a/docs/source/concepts/routes.rst b/docs/source/concepts/routes.rst index dcdfac8..4f438bc 100644 --- a/docs/source/concepts/routes.rst +++ b/docs/source/concepts/routes.rst @@ -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. diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst index d19d829..ae00a2d 100644 --- a/docs/source/examples/index.rst +++ b/docs/source/examples/index.rst @@ -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 `, you can -obtain the ID of the route, and then delete it by typing: +Running the command used in the :ref:`listing routes example +`, you can obtain the ID of the route, and then delete +it by typing: .. code-block:: console :linenos: diff --git a/docs/source/the_project/security.rst b/docs/source/the_project/security.rst index 4cab781..3de3159 100644 --- a/docs/source/the_project/security.rst +++ b/docs/source/the_project/security.rst @@ -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 diff --git a/docs/source/tutorial/tutorial01.rst b/docs/source/tutorial/tutorial01.rst index 2a1beb8..434772b 100644 --- a/docs/source/tutorial/tutorial01.rst +++ b/docs/source/tutorial/tutorial01.rst @@ -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. diff --git a/docs/source/tutorial/tutorial02.rst b/docs/source/tutorial/tutorial02.rst index 66e530f..732834c 100644 --- a/docs/source/tutorial/tutorial02.rst +++ b/docs/source/tutorial/tutorial02.rst @@ -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... diff --git a/docs/source/tutorial/tutorial03.rst b/docs/source/tutorial/tutorial03.rst index 2e6ed99..465d064 100644 --- a/docs/source/tutorial/tutorial03.rst +++ b/docs/source/tutorial/tutorial03.rst @@ -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. diff --git a/docs/source/tutorial/tutorial04.rst b/docs/source/tutorial/tutorial04.rst index ceb6137..b8a7c68 100644 --- a/docs/source/tutorial/tutorial04.rst +++ b/docs/source/tutorial/tutorial04.rst @@ -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 diff --git a/docs/source/tutorial/tutorial05.rst b/docs/source/tutorial/tutorial05.rst index 7afb051..409c878 100644 --- a/docs/source/tutorial/tutorial05.rst +++ b/docs/source/tutorial/tutorial05.rst @@ -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.