summaryrefslogtreecommitdiff
path: root/angelsharkd/src
diff options
context:
space:
mode:
authorCarpenter, Adam (CORP) <adam.carpenter@adp.com>2021-11-30 16:04:37 -0500
committerCarpenter, Adam (CORP) <adam.carpenter@adp.com>2021-11-30 16:04:37 -0500
commite18d0c1a4189d5278639a9b323ae3794118566bc (patch)
treea582caae4e8c0706041497fb16a2525a14002c2e /angelsharkd/src
parentcd9f750990166dfa9b9fc0276749be307e26d008 (diff)
downloadaltruistic-angelshark-e18d0c1a4189d5278639a9b323ae3794118566bc.tar.xz
altruistic-angelshark-e18d0c1a4189d5278639a9b323ae3794118566bc.zip
docs: updated readmes
Diffstat (limited to 'angelsharkd/src')
-rw-r--r--angelsharkd/src/routes/extensions/README.md17
-rw-r--r--angelsharkd/src/routes/extensions/simple_search/README.md80
-rw-r--r--angelsharkd/src/routes/extensions/simple_search/types.rs1
3 files changed, 88 insertions, 10 deletions
diff --git a/angelsharkd/src/routes/extensions/README.md b/angelsharkd/src/routes/extensions/README.md
index b9192fe..1aed1dd 100644
--- a/angelsharkd/src/routes/extensions/README.md
+++ b/angelsharkd/src/routes/extensions/README.md
@@ -1,12 +1,13 @@
# Angelshark Daemon Extensions
-This module aims to provide a simple way of extending Angelshark's basic functionality (running commands on the ACM) with additional HTTP endpoints that run one or more commands to achieve a basic business task.
+This module aims to provide a simple way of extending Angelshark's basic
+functionality (running commands on the ACM) with additional HTTP endpoints that
+run one or more commands to achieve a basic business task.
-For example, say you would like you, other users, or your own software to quickly search all extension-types for a keyword. This functionality is not in the base `angelsharkd`, but it can be easily implemented with the following steps:
+This functionality may not be desirable for all end users, and therefore is
+completely opt-in with feature flags. For example, at compile time, you can add
+`--features simple_search` to enable a given extension called `simple_search`.
-1. Accept a keyword from the client's request
-1. Download extension-type data from one or more ACMs
-1. Filter out extensions that do not match a given keyword
-1. Return the remaining, matching extensions to the client
-
-This functionality may not be desirable for all end users, and therefor is completely opt-in with feature flags. At compile time, you can add `--features simple_search` to enable a given extension called `simple_search`, for example.
+To add additional features, read `mod.rs` and `Cargo.toml` for `angelsharkd` to
+see how to conditionally incorporate your own warp HTTP filters into the
+project.
diff --git a/angelsharkd/src/routes/extensions/simple_search/README.md b/angelsharkd/src/routes/extensions/simple_search/README.md
index 527f686..c0df17a 100644
--- a/angelsharkd/src/routes/extensions/simple_search/README.md
+++ b/angelsharkd/src/routes/extensions/simple_search/README.md
@@ -1,3 +1,79 @@
-# Angelshark Simple Extension Search
+# Daemon Extension `simple_search`
-This extension implements very simple extension searching for end users. It allows for multi-keyword searches on a pre-downloaded collection of CM extension-type and station data. This data can be refreshed on-demand or periodically. Searches always return immediately, even when no data has been downloaded yet.
+This extension implements fast and simple extension searching for clients. Data
+to be searched is downloaded from configured ACMs as a "haystack." Clients pass
+a list of one or more "needles" to search for. Haystack entries matching all
+provided needles are returned.
+
+The haystack starts out empty. To trigger a download, use the `refresh`
+endpoint. Refreshes happen in the background, so clients always receive an
+immediate response. This means that clients will be searching on "stale" data
+(or on the first run, no data) until the refresh completes.
+
+There is no built-in scheduler for periodic haystack refreshes. It is
+recommended to use an external scheduler such as `cron(8)`.
+
+## Getting Started
+
+To enable this feature, compile `angelsharkd` with the `simple_search` flag:
+
+```sh
+cargo build --bin angelsharkd --features simple_search ...
+```
+
+This extension expects a single environment variable,
+`ANGELSHARKD_EXT_SEARCH_ACMS`, to be set at runtime. This var should be a list
+of ACM names from your `asa.cfg`. For example, if your `asa.cfg` is configured
+for ACMs named 01, 02, and 03, and you want to search over 01 and 03, run
+`angelsharkd` like this:
+
+```
+ANGELSHARKD_ADDR='127.0.0.1:3000' ANGELSHARKD_EXT_SEARCH_ACMS='01 03' angelsharkd
+```
+
+## `GET /extensions/search/refresh` Refresh Haystack
+
+`GET /extensions/search/refresh`
+
+```
+200 OK text/plain
+Refresh scheduled.
+```
+
+## `POST /extensions/search` Search Haystack
+
+The return type is the entire list of fields from the `list extension-type`
+command, the ROOM field from the `list station` command, and the configured name
+of the ACM the entry was found on.
+
+```json
+POST /extensions/search
+[
+ "carpenat"
+]
+```
+
+```json
+200 OK
+[
+ [
+ "17571230000",
+ "station-user",
+ "5",
+ "1",
+ "1005",
+ "Carpenter, Adam",
+ "2",
+ "",
+ "CM01",
+ "carpenat"
+ ],
+ ...
+]
+```
+
+## Logging
+
+The `refresh` endpoint always returns successfully. Any errors encountered
+during the refresh are logged as `ERROR`. Successful completed refreshes are
+logged as `INFO`.
diff --git a/angelsharkd/src/routes/extensions/simple_search/types.rs b/angelsharkd/src/routes/extensions/simple_search/types.rs
index 184b1a6..72156e5 100644
--- a/angelsharkd/src/routes/extensions/simple_search/types.rs
+++ b/angelsharkd/src/routes/extensions/simple_search/types.rs
@@ -60,6 +60,7 @@ impl Haystack {
/// Refreshes the haystack data by running relevant commands on a runner,
/// parsing the results, and updating the entries field with the fresh data.
/// TODO: Do we want simultaneous refreshes to be possible?
+ /// TODO: The entry generation could probably be simplified and the number of clones reduced.
pub fn refresh(&self) -> Result<(), Error> {
let mut runner = self.runner.to_owned();