From 8fdd1eac96dcf565f85798bb2ae7ac9fc560210a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9sar=20Gallego=20Rodr=C3=ADguez?= Date: Mon, 13 May 2019 11:52:42 +0200 Subject: [PATCH] Add rationale to spec --- spec/README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 78 insertions(+), 7 deletions(-) diff --git a/spec/README.md b/spec/README.md index 6b6df8f..f1ec53b 100644 --- a/spec/README.md +++ b/spec/README.md @@ -1,17 +1,85 @@ -# The Name of the Game +# Kapow! + +Why is it named Kapow!. You can pronounce it and it is short and +meaningless... like every good UNIX command ;-) + +TODO: Too hard to jump + +## Rationale + +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 | Exit Codes | + +--------------+------------------------+-------------------------+ +``` + +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...? -# The Game of the Name -MAYBE: (ref to TeXbook) +All the alternatives we found are **rigid** about how they match between HTTP +and shell concepts. -Kapow! +* [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) +* [shell-microservice-exposer](https://github.com/jaimevalero/shell-microservice-exposer): + Expose your own scripts as a cool microservice API dockerizing it. -KAPOW! +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. -kapow -TODO: Rationale/Purpose/Why? TODO: Definition TODO: Intro to Architecture @@ -23,6 +91,9 @@ TODO: Intro to Architecture ## Test Suite Notes +The test suite is located on [blebleble] directory. +You can run it... + # Framework ## Commands