tools: Add unitctl CLI

* Pull in entire unit-rust-sdk project
  * not included: CLA, COC, License
  * not included: duplicate openapi spec
  * not included: CI workflows
  * not included: changelog tooling
  * not included: commitsar tooling
  * not included: OpenAPI Web UI feature
* update links in unitctl manpage
* remove IDE configuration from .gitignore
* rename Containerfile.debian to Dockerfile
* simplify call to uname
* keep Readmes and Makefiles to 80 character lines
* outline specifically how to build unitctl
  for any desired target, and where to then
  find the binary for use
* remove a section on the vision of the CLI
  which was superfluous given the state of
  completeness of the code and its use in
  unit
* remove out of date feature proposals from readme
* makefile: do not run when Rustup is not present
* bump mio version to latest
* generate openapi client library on demand
  * generate-openapi only runs when not present
  * generate-openapi now a dependency of binary build targets
  * deleted autogenerated code
  * reverted readme and Cargo document to autogenerated state
  * add additional build requirement to Readme

Co-developed-by: Elijah Zupancic <e.zupancic@f5.com>
Signed-off-by: Elijah Zupancic <e.zupancic@f5.com>
Signed-off-by: Ava Hahn <a.hahn@f5.com>
Reviewed-by: Andrew Clayton <a.clayton@nginx.com> # non rust stuff
[ tools/cli => tools/unitctl and subject tweak - Andrew ]
Signed-off-by: Andrew Clayton <a.clayton@nginx.com>

1 files changed, 134 insertions, 0 deletions

diff --git a/tools/unitctl/README.md b/tools/unitctl/README.md
new file mode 100644
index 00000000..7292cd86
--- /dev/null
+++ b/tools/unitctl/README.md
@@ -0,0 +1,134 @@
+# NGINX UNIT Rust SDK and CLI
+
+This project provides a Rust SDK interface to the
+[NGINX UNIT](https://unit.nginx.org/)
+[control API](https://unit.nginx.org/howto/source/#source-startup)
+and a CLI (`unitctl`) that exposes the functionality provided by the SDK.
+
+## Installation and Use
+In order to build and use `unitctl` one needs a working installation of Maven
+and Cargo. It is recommended to procure Cargo with Rustup. Rustup is packaged
+for use in many systems, but you can also find it at its
+[Official Site](https://rustup.rs/).
+
+With a working installation of Cargo it is advised to build unitctl with the
+provided makefile. The `list-targets` target will inform the user of what
+platforms are available to be built. One or more of these can then be run as
+their own makefile targets. Alternatively, all available binary targets can be
+built with `make all`. See the below example for illustration:
+
+```
+[ava@calliope cli]$ make list-targets
+x86_64-unknown-linux-gnu
+[ava@calliope cli]$ make x86_64-unknown-linux-gnu
+▶ building unitctl with flags [--quiet --release --bin unitctl --target x86_64-unknown-linux-gnu]
+[ava@calliope cli]$ file ./target/x86_64-unknown-linux-gnu/release/unitctl
+./target/x86_64-unknown-linux-gnu/release/unitctl: ELF 64-bit LSB pie executable,
+x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2,
+BuildID[sha1]=ef4b094ffd549b39a8cb27a7ba2cc0dbad87a3bc, for GNU/Linux 4.4.0,
+with debug_info, not stripped
+```
+
+As demonstrated in the example above, compiled binaries may be found in the
+targets folder, under the subdirectory corresponding to the build target
+desired.
+
+
+## Features (Current)
+
+### Consumes alternative configuration formats Like YAML and converts them
+### Syntactic highlighting of JSON output
+### Interpretation of UNIT errors with (arguably more) useful error messages
+
+### Lists all running UNIT processes and provides details about each process.
+```
+$ unitctl instances
+No socket path provided - attempting to detect from running instance
+unitd instance [pid: 79489, version: 1.32.0]:
+  Executable: /opt/unit/sbin/unitd
+  API control unix socket: unix:/opt/unit/control.unit.sock
+  Child processes ids: 79489, 79489
+  Runtime flags: --no-daemon
+  Configure options: --prefix=/opt/unit --user=elijah --group=elijah --openssl
+```
+
+### Lists active listeners from running UNIT processes
+```
+unitctl listeners
+No socket path provided - attempting to detect from running instance
+{
+  "127.0.0.1:8080": {
+    "pass": "routes"
+  }
+}
+```
+
+### Get the current status of NGINX UNIT processes
+```
+$ unitctl status -t yaml
+No socket path provided - attempting to detect from running instance
+connections:
+  accepted: 0
+  active: 0
+  idle: 0
+  closed: 0
+requests:
+  total: 0
+applications: {}
+```
+
+### Send arbitrary configuration payloads to UNIT
+```
+$ echo '{
+    "listeners": {
+        "127.0.0.1:8080": {
+            "pass": "routes"
+        }
+    },
+
+    "routes": [
+        {
+            "action": {
+                "share": "/www/data$uri"
+            }
+        }
+    ]
+}' | unitctl execute --http-method PUT --path /config -f -
+{
+  "success": "Reconfiguration done."
+}
+```
+
+### Edit current configuration in your favorite editor
+```
+$ unitctl edit
+[[EDITOR LOADS SHOWING CURRENT CONFIGURATION - USER EDITS AND SAVES]]
+
+{
+  "success": "Reconfiguration done."
+}
+```
+
+### Display interactive OpenAPI control panel
+```
+$ unitctl ui
+Starting UI server on http://127.0.0.1:3000/control-ui/
+Press Ctrl-C to stop the server
+```
+
+### Import configuration, certificates, and NJS modules from directory
+```
+$ unitctl import /opt/unit/config
+Imported /opt/unit/config/certificates/snake.pem -> /certificates/snake.pem
+Imported /opt/unit/config/hello.js -> /js_modules/hello.js
+Imported /opt/unit/config/put.json -> /config
+Imported 3 files
+```
+### Wait for socket to become available
+```
+$ unitctl --wait-timeout-seconds=3 --wait-max-tries=4 import /opt/unit/config`
+Waiting for 3s control socket to be available try 2/4...
+Waiting for 3s control socket to be available try 3/4...
+Waiting for 3s control socket to be available try 4/4...
+Timeout waiting for unit to start has been exceeded
+```
\ No newline at end of file