diff options
| -rw-r--r-- | angelsharkd/README.md | 4 | ||||
| -rw-r--r-- | angelsharkd/src/routes/extensions/README.md | 17 | ||||
| -rw-r--r-- | angelsharkd/src/routes/extensions/simple_search/README.md | 80 | ||||
| -rw-r--r-- | angelsharkd/src/routes/extensions/simple_search/types.rs | 1 |
4 files changed, 90 insertions, 12 deletions
diff --git a/angelsharkd/README.md b/angelsharkd/README.md index 405a039..8315c74 100644 --- a/angelsharkd/README.md +++ b/angelsharkd/README.md @@ -80,8 +80,8 @@ Response Template: Here are some examples. ```json -POST / - ossi[ +POST /ossi + [ { "acms": ["CM01"], "command": "list stat 17571230000" 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(); |