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

Finish merge and recover README

Browse Source
This commit is contained in:
Roberto Abdelkader Martínez Pérez
2019-11-19 16:50:41 +01:00
parent 5462dd4323
commit 4492bfdf54
7 changed files with 126 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.rst
+126 -36
View File
@@ -1,44 +1,134 @@
Welcome to *Kapow!*
===================
.. image:: https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/f51eb40412bf09c8c800511d7bbe5634/kapow-1601675_480.png
:alt: Kapow!
.. image:: https://circleci.com/gh/BBVA/kapow/tree/master.svg?style=svg
:target: https://circleci.com/gh/BBVA/kapow/tree/master
.. image:: https://goreportcard.com/badge/github.com/bbva/kapow
:target: https://goreportcard.com/report/github.com/bbva/kapow
With *Kapow!* you can publish simple **shell scripts** as **HTTP services** easily.
*Kapow!* with an example
------------------------
**Goal**
We want users on the Internet to be able to ``ping`` an *Internal Host*
which is inside a private network.
.. image:: https://github.com/BBVA/kapow/raw/feature-new-doc/docs/source/_static/network.png
**Limitations**
- We can't allow users to log into any host.
- We need to have full control over the precise command is run as
well as the parameters used.
**Solution**
With a *Kapow!* one-liner you can allow your users to run a command inside
*External Host* through an HTTP call.
.. image:: https://github.com/BBVA/kapow/raw/feature-new-doc/docs/source/_static/sequence.png
This is the only line you'll need:
.. code-block:: bash
$ kapow route add /ping -c 'ping -c1 10.10.10.100 | kapow set /response/body'
**Kapow!** If you can script it, you can HTTP it.
.. todo::
CAVEAT EMPTOR
=============
Mention license and contributing
**Warning!!! Kapow!** is under **heavy development** and `specification </spec>`_;
the provided code is a Proof of Concept and the final version will not even
share programming language. Ye be warned.
What is it?
===========
Kapow! is an adapter between the world of Pure UNIX® Shell and a HTTP service.
Some tasks are more convenient in the shell, like cloud interactions, or some
administrative tools. On the other hand, some tasks are more convenient as a
service, like DevSecOps tooling.
Kapow! lies between these two worlds, making your life easier. Maybe you wonder
about how this kind of magic can happen; if you want to know the nitty-gritty
details, just read our `specification </spec>`_;. Or, if you want to know how
Kapow! can help you first, let's start with a common situation.
Think about that awesome command that you use every day, something very
familiar, like ``cloudx storage ls /backups``. Then someone asks you for an
specific backup, so you ``ssh`` into the host, execute your command, possibly
``grepping`` through its output, copy the result and send it back to him.
And that's fine... for the 100 first times.
Then you decide, let's use an API for this and generate an awesome web server
with it. So, you create a project, manage its dependencies, code the server,
parse the request, learn how to use the API, call the API and deploy it
somewhere. And that's fine... until you find yourself again in the same
situation with another awesome command.
The awesomeness of UNIX® commands is infinite, so you'll be in this situation
an infinite number of times! Instead, let's put Kapow! into action.
With Kapow! you just need to create a ``.pow`` file named ``backups.pow`` that
contains:
.. code-block:: sh
kapow route add /backups \
-c 'cloudx storage ls /backups | grep "$(kapow get /request/params/query)" | kapow set /response/body'
and execute it in the remote host with the command:
.. code-block:: sh
kapow server backups.pow
and that's it. Done. You have a web server that people can use to request
their backups every time they need only by invoking the URL
`http://remotehost/backups?query=project`
Do you like it? yes? Then let's start learning a little more, you can access
the `documentation </doc>`_; section to find installation instructions and some
examples.
How it was born
---------------
Some awesome history is coming.
Kapow! for the impatient
========================
When you need to **share** a ``command`` but **not** a complete remote ``ssh
access``, Kapow! will help you with the power of HTTP:
.. image:: https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/784a183fba3f24872dd97ee28e765922/Kapow!.png
:alt: Where Kapow! lives
Kapow! allows you to write a litte script that will **serve an executable as REST
service**. This script will let you define how to connect HTTP and the Shell
using Kapow!'s shell abstractions to the HTTP world. See it to believe:
.. image:: resources/kapow.gif?raw=true
:alt: Kapow! in action
Superpowers
-----------
Kapow! gives you:
* A very simple way to turn any shell **executable into an API**
* A **remote administration** API
* A way to define the integration in you own terms, obligations-free!
Curses
------
Kapow! can't help when:
-----------------------
* You need high throughput: Kapow! spawns a new executable for every HTTP call
* You must perform complex logic to attend the request: never use Kapow! if
your executables don't perform al least 90% of the hard work
* You are building a huge application
When it is your best friend:
--------------------------
* Easy command + Hard API = Kapow! to the rescue
* SSH for one command? Kapow! allows you to share only that command
* Remote instrumentation of several machines? Make it easy with Kapow!
The more you know
=================
If you want to know more, please follow our `documentation </doc>`_.
docs/source/cheatsheet.rst → docs/source/examples/index.rst
View File
docs/source/install.rst
-17
View File
@@ -1,17 +0,0 @@
Installation
============
Precompiled Binaries
--------------------
1. Get a precompiled static binary for your system from our `releases section <https://github.com/BBVA/kapow/releases/latest>`_.
2. Put it in your ``$PATH`` (Linux example):
.. code-block:: bash
sudo install kapow1.0.0-rc1_linux_amd64 /usr/bin/kapow
.. todo::
Describe all the options available.
docs/source/quickstart.rst
-27
View File
@@ -1,27 +0,0 @@
Quickstart Guide
================
Hello World! -- *Kapow!* style
------------------------------
In a shell, the traditional `Hello World!` program would be ``echo "Hello World!"``.
Let's publish it through HTTP using *Kapow!*
- First you need a *script file* with the route that will publish your command, lets's call the file ``greet.sh`` and should contain the following code:
.. code-block:: bash
kapow route add /greet -c 'echo "Hello World!" | kapow set /response/body'
- Start the *Kapow!* server with your script as an argument
.. code-block:: bash
kapow server greet.sh
- Finally check that all is working as intended:
.. image:: _static/browser.png
docs/source/setup/index.rst
View File
docs/source/theory/index.rst
View File
docs/source/tutorial.rst
-28
View File
@@ -1,28 +0,0 @@
.. todo::
Redo
Hello World! -- *Kapow!* style
------------------------------
In a shell, the traditional `Hello World!` program would be ``echo "Hello World!"``.
Let's publish it through HTTP using *Kapow!*
- First you need a *script file* with the route that will publish your command, lets's call the file ``greet.sh`` and should contain the following code:
.. code-block:: bash
kapow route add /greet -c 'echo "Hello World!" | kapow set /response/body'
- Start the *Kapow!* server with your script as an argument
.. code-block:: bash
kapow server greet.sh
- Finally check that all is working as intended:
.. image:: _static/browser.png