update docs with more examples/use-cases, add json schema

Author: eshaan7

README.md

@@ -6,22 +6,23 @@
 </a>
 [![flask-shell2http on pypi](https://img.shields.io/pypi/v/flask-shell2http)](https://pypi.org/project/Flask-Shell2HTTP/)
 
-A minimalist [Flask](https://github.com/pallets/flask) extension that serves as a REST API wrapper for python's subprocess API.
+A minimalist [Flask](https://github.com/pallets/flask) extension that serves as a RESTful/HTTP wrapper for python's subprocess API.
 
 - **Convert any command-line tool into a REST API service.**
-- Execute pre-defined shell commands asynchronously and securely via flask's endpoints.
+- Execute pre-defined shell commands asynchronously and securely via flask's endpoints with dynamic arguments, file upload, callback function capabilities.
 - Designed for binary to binary/HTTP communication, development, prototyping, remote control and [more](https://flask-shell2http.readthedocs.io/en/stable/Examples.html).
 
-Inspired by the work of awesome folks over at [msoap/shell2http](https://github.com/msoap/shell2http).
 
 ## Use Cases
 
 - Set a script that runs on a succesful POST request to an endpoint of your choice. See [Example code](examples/run_script.py).
 - Map a base command to an endpoint and pass dynamic arguments to it. See [Example code](examples/basic.py).
 - Can also process multiple uploaded files in one command. See [Example code](examples/multiple_files.py).
 - This is useful for internal docker-to-docker communications if you have different binaries distributed in micro-containers. See [real-life example](https://github.com/intelowlproject/IntelOwl/blob/develop/integrations/peframe/app.py).
-- You can define a callback function/ use signals to listen for process completion. See [Example code](examples/with_callback.py). Meybe want to intercept on completion and update the result ? See [Example code](examples/custom_save_fn.py)
-- Currently, all commands run asynchronously (default timeout is 3600 seconds), so result is not available directly. An option _may_ be provided for this in future release.
+- You can define a callback function/ use signals to listen for process completion. See [Example code](examples/with_callback.py). 
+ - Maybe want to pass some additional context to the callback function ? 
+ - Maybe intercept on completion and update the result ? See [Example code](examples/custom_save_fn.py)
+- Currently, all commands run asynchronously (default timeout is 3600 seconds), so result is not available directly. An option _may_ be provided for this in future releases for commands that return immediately.
 
 > Note: This extension is primarily meant for executing long-running
 > shell commands/scripts (like nmap, code-analysis' tools) in background from an HTTP request and getting the result at a later time.
@@ -35,7 +36,8 @@ from the [documentation](https://flask-shell2http.readthedocs.io/) to get starte
 
 I highly recommend the [Examples](https://flask-shell2http.readthedocs.io/en/stable/Examples.html) section.
 
-## Why?
+## Inspiration
 
 This was initially made to integrate various command-line tools easily with [Intel Owl](https://github.com/intelowlproject/IntelOwl), which I am working on as part of Google Summer of Code.
 
+The name was inspired by the awesome folks over at [msoap/shell2http](https://github.com/msoap/shell2http).

docs/source/Examples.md

@@ -7,4 +7,4 @@ I have created some example python scripts to demonstrate various use-cases. The
 - [multiple_files.py](https://github.com/Eshaan7/Flask-Shell2HTTP/blob/master/examples/multiple_files.py): Upload multiple files for a single command.
 - [with_callback.py](https://github.com/Eshaan7/Flask-Shell2HTTP/blob/master/examples/with_callback.py): Define a callback function that executes on command/process completion.
 - [with_signals.py](https://github.com/Eshaan7/Flask-Shell2HTTP/blob/master/examples/with_signals.py): Using [Flask Signals](https://flask.palletsprojects.com/en/1.1.x/signals/) as callback function.
-- [custom_save_fn.py](https://github.com/Eshaan7/Flask-Shell2HTTP/blob/master/examples/custom_save_fn.py): There may be cases where the process doesn't print result to standard output but to a file/database. This example shows how to intercept the future object after completion and update it's result attribute.
+- [custom_save_fn.py](https://github.com/Eshaan7/Flask-Shell2HTTP/blob/master/examples/custom_save_fn.py): There may be cases where the process doesn't print result to standard output but to a file/database. This example shows how to pass additional context to the callback function, intercept the future object after completion and update it's result attribute before it's ready to be consumed.

docs/source/Quickstart.md

@@ -27,7 +27,11 @@ app = Flask(__name__)
 executor = Executor(app)
 shell2http = Shell2HTTP(app=app, executor=executor, base_url_prefix="/commands/")
 
-shell2http.register_command(endpoint="saythis", command_name="echo", callback_fn=None)
+def my_callback_fn(context, future):
+  # additional user-defined callback function
+  print(context, future.result())
+
+shell2http.register_command(endpoint="saythis", command_name="echo", callback_fn=my_callback_fn)
 ```
 
 Run the application server with, `$ flask run -p 4000`.
@@ -53,11 +57,13 @@ print("Result:", resp.json())
 
 </details>
 
+> Note: You can see the JSON schema for the POST request [here](https://github.com/Eshaan7/Flask-Shell2HTTP/blob/master/post-request-schema.json).
+
 returns JSON,
 
 ```json
 {
-   "key": "ddbe0a94847c",
+   "key": "ddbe0a94",
    "result_url": "http://localhost:4000/commands/saythis?key=ddbe0a94",
    "status": "running"
 }

docs/source/index.rst

@@ -5,22 +5,22 @@ Welcome to Flask-Shell2HTTP!
 .. image:: https://img.shields.io/lgtm/grade/python/g/Eshaan7/Flask-Shell2HTTP.svg?logo=lgtm&logoWidth=18
 .. image:: https://img.shields.io/pypi/v/flask-shell2http
 
-A minimalist Flask_ extension that serves as a REST API wrapper for python's subprocess API.
+A minimalist Flask_ extension that serves as a RESTful/HTTP wrapper for python's subprocess API.
 
 - **Convert any command-line tool into a REST API service.**
 - Execute shell commands asynchronously and safely via flask's endpoints.
-
-Inspired by the work of awesome folks over at shell2http_.
+- Designed for binary to binary/HTTP communication, development, prototyping, remote control and more.
 
 .. _Flask: https://github.com/pallets/flask
-.. _shell2http: https://github.com/msoap/shell2http
 
 **Use Cases:**
 
 - Set a script that runs on a succesful POST request to an endpoint of your choice.
 - Map a base command to an endpoint and pass dynamic arguments to it.
 - Can also process multiple uploaded files in one command.
-- Currently, all commands are run asynchronously, so result is not available directly. An option would be provided for this in future release.
+- This is useful for internal docker-to-docker communications if you have different binaries distributed in micro-containers.
+- You can define a callback function/ use signals to listen for process completion.
+- Currently, all commands run asynchronously (default timeout is 3600 seconds), so result is not available directly. An option _may_ be provided for this in future release.
 
    `Note: This extension is primarily meant for executing long-running 
    shell commands/scripts (like nmap, code-analysis' tools) in background from an HTTP request and getting the result at a later time.`

post-request-schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "type": "object",
+  "title": "The POST request schema",
+  "default": {},
+  "examples": [
+    {
+      "args": ["hello", "world"],
+      "timeout": 60,
+      "callback_context": {
+        "read_result_from": "/path/to/saved/file",
+        "force_success": true
+      }
+    }
+  ],
+  "required": [],
+  "properties": {
+    "args": {
+      "type": "array",
+      "title": "Arguments that will be appended to the base command",
+      "default": [],
+      "examples": [
+        ["hello", "world"],
+        ["@inputfile", "@someotherfile"]
+      ]
+    },
+    "timeout": {
+      "type": "integer",
+      "title": "subprocess timeout in seconds",
+      "description": "Maximum timeout after which subprocess fails if not already complete.",
+      "default": 3600
+    },
+    "callback_context": {
+      "type": "object",
+      "title": "Additional context for user defined callback function",
+      "description": "This object will be passed as the first argument of user-defined callback function",
+      "default": {},
+      "examples": [
+        {
+          "read_result_from": "/path/to/saved/file",
+          "force_success": true
+        }
+      ]
+    }
+  }
+}