docs: module readmes, sample config, main readme

1 files changed, 230 insertions, 0 deletions

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.