131 lines
5.0 KiB
Markdown
131 lines
5.0 KiB
Markdown
10-SECOND PROPOSAL
|
|
===================
|
|
|
|
*kapow* is a specialized language for marrying the **web** and the **shell**.
|
|
|
|
|
|
DESCRIPTION
|
|
===========
|
|
|
|
The **web** and the **shell** are two different beasts, both packed with history.
|
|
|
|
There are some concepts in HTTP and the shell that **resemble each other**.
|
|
|
|
```
|
|
+------------------------+-------------------------+
|
|
| HTTP | SHELL |
|
|
+--------------+------------------------+-------------------------+
|
|
| Input | POST form-encoding | Command line parameters |
|
|
| Parameters | GET parameters | Environment variables |
|
|
| | Headers | |
|
|
| | Serialized body (JSON) | |
|
|
+--------------+------------------------+-------------------------+
|
|
| Data Streams | Response/Request Body | Stdin/Stdout/Stderr |
|
|
| | Websocket | Input/Output files |
|
|
| | Uploaded files | |
|
|
+--------------+------------------------+-------------------------+
|
|
| Control | Status codes | Signals |
|
|
| | HTTP Methods | |
|
|
+--------------+------------------------+-------------------------+
|
|
```
|
|
|
|
Any tool designed to give an HTTP interface to an existing shell command **must map concepts of boths**. For example:
|
|
|
|
- "GET parameters" to "Command line parameters"
|
|
- "Headers" to "Environment variables"
|
|
- "Stdout" to "Response body"
|
|
|
|
*kapow* is not opinionated about the different ways you can map both worlds. Instead it provides a concise language used to express the mapping and a set of common defaults.
|
|
|
|
|
|
Why not tool...?
|
|
----------------
|
|
|
|
All the alternatives we found are **rigid** about how they match between HTTP and shell concepts.
|
|
|
|
* [shell2http](https://github.com/msoap/shell2http): HTTP-server to execute shell commands. Designed for development, prototyping or remote control. Settings through two command line arguments, path and shell command.
|
|
* [websocketd](https://github.com/joewalnes/websocketd): Turn any program that uses STDIN/STDOUT into a WebSocket server. Like inetd, but for WebSockets.
|
|
* [webhook](https://github.com/adnanh/webhook): webhook is a lightweight incoming webhook server to run shell commands.
|
|
* [gotty](https://github.com/yudai/gotty): GoTTY is a simple command line tool that turns your CLI tools into web applications. (For interactive commands only)
|
|
|
|
Tools with a rigid matching **can't evade** *[impedance mismatch](https://haacked.com/archive/2004/06/15/impedance-mismatch.aspx/)*. Resulting is an easy-to-use software, convenient in some scenarios but incapable in others.
|
|
|
|
|
|
Why not my good-old programming language...?
|
|
--------------------------------------------
|
|
|
|
* Boilerplate
|
|
* Custom code = More bugs
|
|
* Security issues (Command injection, etc)
|
|
* Dependency on developers
|
|
* "A programming language is low level when its programs require attention to the irrelevant" Alan Perlis
|
|
|
|
*kapow* aims to be halfway from one of the mentioned tools and a general programming language. A limited scripting language. Think of *awk*, 20 years later, for HTTP.
|
|
|
|
|
|
Example
|
|
-------
|
|
|
|
Imagine you want to improve your monitoring system to be able to check if a WiFi in a remote building is working. Suppose you already have a wireless capable linux server on that building.
|
|
|
|
What about exposing a wifi scan as a service?
|
|
|
|
```
|
|
$ iwlist scan | grep 'ESSID:"BBVA"'
|
|
```
|
|
|
|
The above command will list the visible WiFI networks and filter for the one we are interested in (**BBVA**); exiting with code **0** when found and **1** otherwise.
|
|
|
|
We want to signal the WiFI status with a meaningful HTTP status code: 200 for UP and 503 for DOWN.
|
|
|
|
So the only thing our service has to do is translate from the **command's exit code** to a meaningful **HTTP status code**.
|
|
|
|
Our *kapow* program (monitor.pow) should look **something like** this:
|
|
|
|
```
|
|
/monitor/wifi =
|
|
$(iwlist scan | grep 'ESSID:"BBVA')
|
|
| 0 = status 200 # OK
|
|
| 1 = status 503 # Service Unavailable
|
|
```
|
|
|
|
With this code, the user can run the service with:
|
|
|
|
```
|
|
$ kapow monitor.pow
|
|
```
|
|
And then:
|
|
|
|
1. *kapow* will open a port with an HTTP server serving the URI **/monitor/wifi**.
|
|
2. When requested `curl http://<server>/monitor/wifi`. The command is executed resulting in a WiFI scan.
|
|
3. The command's **exit code** is translated to an HTTP **status code** and returned.
|
|
|
|
USE CASES OR VALUE
|
|
==================
|
|
|
|
* Reuse 40+ years of existing computer programs as microservices (nanoservices?).
|
|
* Expose command line only tools as services. Eliminating the need of interactive SSH sessions.
|
|
* Fine-grained access control to CLI based on options/parameters
|
|
|
|
|
|
REQUIRED SKILLS
|
|
===============
|
|
|
|
- Knowledge of HTTP and the command line.
|
|
- Programming.
|
|
- Low-level stuff...
|
|
|
|
|
|
ESTIMATION
|
|
==========
|
|
|
|
- 2 weeks
|
|
|
|
|
|
OUTPUT
|
|
======
|
|
|
|
- A collection of **concrete** use cases, 5 to 10.
|
|
- A DSL design (over paper) to implement the use cases.
|
|
- A working **dirty** proof of concept.
|