From 25d836b453948676735928851b5cb1679be0ccc4 Mon Sep 17 00:00:00 2001
From: "Carpenter, Adam (CORP)" <Adam.Carpenter@adp.com>
Date: Tue, 12 Oct 2021 15:18:45 -0400
Subject: docs: readme for angelsharkd

---
 angelsharkd/README.md | 68 +++++++++++++++++++++++++++++++--------------------
 1 file changed, 42 insertions(+), 26 deletions(-)

(limited to 'angelsharkd/README.md')

diff --git a/angelsharkd/README.md b/angelsharkd/README.md
index 88471de..15cffd3 100644
--- a/angelsharkd/README.md
+++ b/angelsharkd/README.md
@@ -1,15 +1,12 @@
 # `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.
+This program listens for HTTP requests. 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 /`: Current Running Version
 
-- `GET /` greeting and version number
-- `POST /ossi` run OSSI commands
-
-## Running Commands via `POST /ossi`
+## `POST /ossi` Run OSSI Command(s)
 
 Runs provided command(s) on configured ACM(s) and returns the results.
 
@@ -175,23 +172,20 @@ Here are some examples.
 ]
 ```
 
-### 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.
+### `?panicky=true` Query Parameter for Error Handling
 
-More examples.
+This endpoint accepts a 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.
 
 `POST /ossi`
 
 ```json
 [
   {
-    "acms": ["CM01"],
-    "command": "list stat nonexistent"
+    "acms": ["fake"],
+    "command": "list stat"
   }
 ]
 ```
@@ -207,24 +201,46 @@ More examples.
 ```json
 [
   {
-    "acms": ["CM01"],
-    "command": "list stat nonexistent"
+    "acms": ["fake"],
+    "command": "list stat"
   }
 ]
 ```
 
 `500 Internal Server Error`
 
-```plain
-Unable to execute command -- ACM didn't feel like it today....
+```json
+{
+  "reason": "Failed to open TCP stream to host. Make sure the config is correct and the host is otherwise reachable."
+}
 ```
 
+### `?no_cache=true` Query Parameter to Disable Caching
+
+By default, all responses are stored in a timed cache for thirty minutes. If you
+wish to bypass the cache (such as to validate the results of a recent change
+command), you can pass `?no_cache=true` as a query string parameter.
+
+Query parameters may be combined (ex. `?no_cache=true&panicky=true`).
+
+## Configuration
+
+`angelsharkd` can be configured with a variety of environment variables set at
+runtime.
+
+- `ANGELSHARKD_ORIGIN`: origin for CORS preflight requests. This is required in
+  release (not debug) mode.
+- `ANGELSHARKD_DEBUG`: enables debug mode. Extra logs will be written out and
+  CORS will be turned off.
+- `ANGELSHARKD_LOGINS`: override ACM logins file from `./asa.cfg`.
+- `ANGELSHARKD_ADDR`: override socket address to listen on. Takes the format
+  `127.0.0.1:8080`.
+
 ## Login Configuration
 
-See [`angelshark.toml.sample`](/samples/angelshark.toml.sample) to get an idea
-of how to configure `angelsharkd`.
+TODO:
 
 ## Logging
 
-`angelsharkd` writes standard access logs to STDOUT every time it responds to a
-request. Inner `libangelshark` errors may be written to STDOUT.
+`angelsharkd` continuously writes logs to STDERR. In debug mode, additional,
+potentially sensitive information is also logged, including request parameters.
-- 
cgit v1.2.3