docs: module readmes, sample config, main readme

4 files changed, 344 insertions, 6 deletions

diff --git a/README.md b/README.md
index 1b66410..21300aa 100644
--- a/README.md
+++ b/README.md
@@ -27,17 +27,17 @@ sure you're using (for example) `./angelsharkcli` for \*nix and
 ## Installation
 
 `angelsharkcli` is available as a prebuilt binary for many platforms in the
-GitHub releases. You may also build it from scratch with
+GitHub releases. To install `angelsharkcli` from source, use
 [`cargo`](https://rustup.rs):
 
-```sh
-cargo install --path angelsharkcli
+```
+cargo install --git https://github.com/adpllc/altruistic-angelshark.git angelsharkcli
 ```
 
-To build and install `angelsharkd`:
+To install `angelsharkd` from source:
 
-```sh
-cargo install --path angelsharkd
+```
+cargo install --git https://github.com/adpllc/altruistic-angelshark.git angelsharkd
 ```
 
 ## Quick Examples
diff --git a/angelsharkcli/README.md b/angelsharkcli/README.md
new file mode 100644
index 0000000..e314568
--- /dev/null
+++ b/angelsharkcli/README.md
@@ -0,0 +1,107 @@
+# `angelsharkcli`
+
+This program accepts OSSI-formatted commands as input and writes the results
+back out to the user. Input is read from STDIN, output is written to STDOUT (if
+printing is being used) and errors are written to STDERR.
+
+## Help
+
+```
+$ angelsharkcli -h
+Altruistic Angelshark CLI 0.1.0
+Adam T. Carpenter <adam.carpenter@adp.com>
+
+Reads STDIN and parses all lines as commands to be fed to one or more ACMs. When it reaches EOF, it stops parsing and
+starts executing the command(s) on the ACM(s). What it does with the output can be configured with subcommands and
+flags. If you like keeping your commands in a file, consider using the `<` to read it on STDIN. The default behavior is
+to run commands but print no output (for quick changes). Errors are printed on STDERR.
+
+USAGE:
+    angelsharkcli [OPTIONS] [SUBCOMMAND]
+
+FLAGS:
+    -h, --help       Prints help information
+    -V, --version    Prints version information
+
+OPTIONS:
+    -l, --login-file <config>    Set ACM login configuration file [default: ./asa.cfg]
+
+SUBCOMMANDS:
+    help     Prints this message or the help of the given subcommand(s)
+    man      Prints command manual pages via `ossim` term
+    print    Prints command output to STDOUT (or files) in a useful format
+    test     Prints parsed logins and inputs but does not run anything
+```
+
+## Input Syntax
+
+The input syntax loosely follows that of the OSSI protocol, with one slight
+modification to allow for ACM selection. One command is made up of multiple
+lines and the program accepts one or more commands. Every line begins with a
+single character (a, c, f, d, or t) with the following meanings.
+
+- `a` Signifies one or more ACM names to run the command on. Accepts multiple
+  values, either as tab-separated entries on the same line or as completely
+  separate lines, each of which must start with `a`.
+- `c` The command to be run. Only one of these per terminated body of input.
+  Shorthands are supported.
+- `f` Signifies one or more optional fields to be displayed or mutated. If you
+  want to limit the output of list or display commands to particular fields, you
+  can include them here. These are also used for change commands to specify
+  which fields of data are to be mutated. Accepts multiple values, either as
+  tab-sepaated entries on the same line or as completely separate lines, each of
+  which must start with `f`.
+- `d` Signifies one or more data entries to be inserted into provided fields for
+  a change command. Accepts multiple values, either as tab-separated entries on
+  the same line or as completely separate lines, each of which must start with
+  `d`.
+- `t` Is the terminator, and signifies the end of one command. Since you can
+  input many commands, use `t` on its own line to separate them. Every command
+  must end with a `t`, even if you're just sending one command.
+
+Example:
+
+```plain
+aCM01    CM02
+clist station
+f8003ff00
+t
+```
+
+Example with multiple fields and data insertion:
+
+```plain
+aCM01
+aCM02
+ccha stat 17571230000
+f8003ff00    0031ff00
+dCarpenter, Adam
+d1002
+t
+```
+
+## Login Configuration
+
+The program expects a file called 'asa.cfg' to be in the PWD at runtime. You can
+change the location and name of this file with the CLI options (invoke the
+program with `--help`). The syntax of this file is as follows:
+
+```plain
+<acm name> <username>:<password>@<address>:<port>
+...(repeated if desired for multiple ACMs)
+```
+
+The ACM name is a name you give to that login information to be provided in the
+input later. It can be anything (e.g. CM11). The username and password are known
+working credentials for that ACM. The address is the physical host or IP address
+for that ACM. The port is the SSH port directly into SAT. The default port, if
+none is provided, is 5022.
+
+You can download a [sample `asa.cfg.sample`](/asa.cfg.sample) to start with.
+
+Example:
+
+```plain
+CM01 myuser:p@$$w0rd@10.0.0.1:5022
+CM02 myuser:p@$$w0rd@10.0.0.2:5022
+```
diff --git a/angelsharkd/README.md b/angelsharkd/README.md
new file mode 100644
index 0000000..88471de
--- /dev/null
+++ b/angelsharkd/README.md
@@ -0,0 +1,230 @@
+# `angelsharkd`
+
+This program listens for HTTP connections. It accepts OSSI commands in JSON
+format and returns OSSI output in JSON format. Below are examples of how to use
+the available endpoints.
+
+## Endpoints
+
+- `GET /` greeting and version number
+- `POST /ossi` run OSSI commands
+
+## Running Commands via `POST /ossi`
+
+Runs provided command(s) on configured ACM(s) and returns the results.
+
+The input syntax loosely follows that of the Avaya OSSI protocol (with one
+slight modification to allow for ACM specification). For more information, read
+the team documentation on the protocol.
+
+Input is a JSON array of objects. Every one of those objects is a single command
+to be run. The fields of that object determine the properties of the OSSI
+command to be constructed. The fields are as follows:
+
+- `"acms"`: An array of one or more configured ACM names to run the command on.
+  Required.
+- `"command"`: A string representing the command to be run. Required.
+- `"fields"`: An array of field hex addresses. Optional. Used for shortening
+  output data entries or naming field data to be mutated.
+- `"datas"`: An array of strings. For change commands, there must be as many
+  `datas` as `fields`.
+
+Request Template:
+
+```json
+{
+    "acms": [
+        "<configured ACM name>",
+        ...
+    ],
+    "command": "<command to be run>",
+    "fields": [
+        "<optional field hex address>",
+        ...
+    ],
+    "datas": [
+        "<optional replacement data>",
+        ...
+    ]
+}
+```
+
+Output is a JSON array of results. It mostly mimics the request syntax although
+every element of the array is for a single command run on a single ACM. It also
+accounts for errors at the OSSI level. Every object has the following fields:
+
+- `"acm"`: The ACM the command was run on.
+- `"command"`: The command that was run.
+- `"fields"`: An array of field hex addresses ordinally corresponding to the
+  data entries.
+- `"datas"`: An array of arrays of strings. Every inner array is a single data
+  entry.
+- `"error"`: A string. Empty if there was no error. Populated if SAT failed to
+  run the command.
+
+Response Template:
+
+```json
+[
+    {
+        "acm": "<ACM command was run on>",
+        "command": "<command that was run>",
+        "fields": [
+            "<field hex address>",
+            ...
+        ],
+        "datas": [
+            [
+                "<entry data>",
+                ...
+            ],
+            ...
+        ],
+        "error": ""
+    }
+]
+```
+
+Here are some examples.
+
+`POST /ossi`
+
+```json
+[
+  {
+    "acms": ["CM01"],
+    "command": "list stat 17571230009"
+  }
+]
+```
+
+`200 OK`
+
+```json
+[
+  {
+    "acm": "CM01",
+    "command": "list stat 17571230009",
+    "fields": [
+      "8005ff00",
+      "8004ff00",
+      "8003ff00",
+      "0031ff00",
+      "8007ff00",
+      "8001ff00",
+      "0033ff00",
+      "4e22ff00",
+      "004fff00",
+      "700dff00",
+      "6a01ff00",
+      "0019ff00",
+      "ce2aff00",
+      "8002ff00",
+      "4a3bff00",
+      "0032ff00"
+    ],
+    "datas": [
+      [
+        "17571230000",
+        "S9999",
+        "Carpenter, Adam",
+        "1234",
+        "5678",
+        "5",
+        "",
+        "",
+        "1234",
+        "",
+        "no",
+        "",
+        "",
+        "1",
+        "1",
+        ""
+      ]
+    ],
+    "error": ""
+  }
+]
+```
+
+`POST /ossi`
+
+```json
+[
+  {
+    "acms": ["CM01"],
+    "command": "cha stat 17571230000",
+    "fields": ["8003ff00"],
+    "datas": ["Carpenter, Adam T."]
+  }
+]
+```
+
+`200 OK`
+
+```json
+[
+  {
+    "acm": "CM01",
+    "command": "cha stat 17571230009",
+    "fields": [],
+    "datas": [[]],
+    "error": ""
+  }
+]
+```
+
+### To Panic or Not to Panic (Query Strings)
+
+This endpoint accepts a single query string in the form of `?panicky=true`. By
+default, any execution errors are simply filtered out of the output. This
+ensures that the output is always valid OSSI JSON. If you would rather get an
+error response for any Angelshark-related errors (not SAT errors), you can set
+this parameter.
+
+More examples.
+
+`POST /ossi`
+
+```json
+[
+  {
+    "acms": ["CM01"],
+    "command": "list stat nonexistent"
+  }
+]
+```
+
+`200 OK`
+
+```json
+[]
+```
+
+`POST /ossi?panicky=true`
+
+```json
+[
+  {
+    "acms": ["CM01"],
+    "command": "list stat nonexistent"
+  }
+]
+```
+
+`500 Internal Server Error`
+
+```plain
+Unable to execute command -- ACM didn't feel like it today....
+```
+
+## Login Configuration
+
+See [`angelshark.toml.sample`](/samples/angelshark.toml.sample) to get an idea
+of how to configure `angelsharkd`.
+
+## Logging
+
+`angelsharkd` writes standard access logs to STDOUT every time it responds to a
+request. Inner `libangelshark` errors may be written to STDOUT.
diff --git a/asa.cfg.sample b/asa.cfg.sample
new file mode 100644
index 0000000..426471f
--- /dev/null
+++ b/asa.cfg.sample
@@ -0,0 +1 @@
+example  example_user:example_pass@192.168.1.1:5022
\ No newline at end of file