Merge branch 'develop' of github.com:alexdlaird/hookee into develop

CHANGELOG.md

@@ -6,6 +6,10 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased](https://github.com/alexdlaird/hookee/compare/2.3.7...HEAD)
 
+### Added
+
+- Documentation improvements.
+
 ## [2.3.7](https://github.com/alexdlaird/hookee/compare/2.3.6...2.3.7) - 2024-11-21
 
 ### Added

README.md

@@ -47,6 +47,17 @@ here we are customizing the response body from `/webhook` using the `--response`
 hookee --response "<Response>Ok</Response>" --content-type application/xml
 ```
 
+`hookee` can also be started without a tunnel (removing the dependency on an Internet connection). Using the
+`--no-tunnel` flag only starts `hookee`'s server, allowing responses to be mocked locally. This can be particularly
+useful when service discovery is done through a proxy service (ex. [HAProxy](https://www.haproxy.org/),
+[Envoy](https://www.envoyproxy.io/), etc.), meaning we can tell `hookee` to start on the port of an expected downstream,
+thus intercepting requests to that service to provide our own responses in an isolated environment, very useful for
+rapid local development, cluster testing, and more.
+
+```sh
+hookee --no-tunnel --response "<Response>Ok</Response>" --content-type application/xml --default-route /some/route --port 19780
+```
+
 To see the ways `hookee` can be tweaked right from the console, view its documented args and commands like this:
 
 ```sh

SECURITY.md

@@ -4,8 +4,8 @@
 
 | Version | Supported          |
 |---------|--------------------|
-| 2.1.x   | :white_check_mark: |
-| < 2.1   | :x:                |
+| 2.3.x   | :white_check_mark: |
+| < 2.3   | :x:                |
 
 ## Reporting a Vulnerability
 

docs/index.rst

@@ -63,6 +63,17 @@ here we are customizing the response body from ``/webhook`` using the ``--respon
 
     hookee --response "<Response>Ok</Response>" --content-type application/xml
 
+``hookee`` can also be started without a tunnel (removing the dependency on an Internet connection). Using the
+``--no-tunnel`` flag only starts ``hookee``'s server, allowing responses to be mocked locally. This can be particularly
+useful when service discovery is done through a proxy service (ex. `HAProxy <https://www.haproxy.org/>`_,
+`Envoy <https://www.envoyproxy.io/>`_, etc.), meaning we can tell ``hookee`` to start on the port of an expected
+downstream, thus intercepting requests to that service to provide our own responses in an isolated environment,
+very useful for rapid local development, cluster testing, and more.
+
+.. code-block:: sh
+
+    hookee --no-tunnel --response "<Response>Ok</Response>" --content-type application/xml --default-route /some/route --port 19780
+
 To see the ways ``hookee`` can be tweaked right from the console, view its documented args and commands like this:
 
 .. code-block:: sh
@@ -119,7 +130,7 @@ From now on, these args are no longer necessary when starting ``hookee``:
 Customizing the Response
 ========================
 
-If we don't want to bother with building our own plugins, the response from ``/webhook`` and be customized right from
+If we don't want to bother with building our own plugins, the response from ``/webhook`` can be customized right from
 the command line with the ``--response`` arg.
 
 .. code-block:: sh

hookee/cli.py

@@ -3,43 +3,43 @@
 __copyright__ = "Copyright (c) 2020-2024 Alex Laird"
 __license__ = "MIT"
 
-import platform
-
 import click
+import platform
 
 from hookee import HookeeManager, __version__, pluginmanager
 
 
 @click.group(invoke_without_command=True)
 @click.pass_context
-@click.option("--port", type=int, help="The local port for the webserver and ngrok tunnel.")
-@click.option('--default-route', type=str, help="The URI regex to map to the default webhook.")
+@click.option("--port", type=int, help="[server] The local port for the webserver and ngrok tunnel.")
+@click.option('--default-route', type=str, help="[server] The URI regex to map to the default webhook.")
 @click.option('--no-tunnel', is_flag=True, default=False, help="Do not open an ngrok tunnel.")
-@click.option("--subdomain", help="The subdomain to use for ngrok endpoints.")
-@click.option("--region", type=click.Choice(["us", "eu", "ap", "au", "sa", "jp", "in"]),
-              help="The region to use for ngrok endpoints.")
-@click.option("--hostname", help="The hostname to use for ngrok endpoints.")
-@click.option("--auth", help="The basic auth to use for ngrok endpoints.")
-@click.option("--host-header", help="The \"Host\" header value to use for ngrok endpoints.")
 @click.option("--response", type=str,
-              help="Data to set for the response, overriding all body data from plugins and `--response-script`.")
+              help="[server] Data to set for the response, overriding all body data from plugins and "
+                   "`--response-script`.")
 @click.option("--content-type", type=str,
-              help="The \"Content-Type\" header to set when response body data is given with `--response`")
+              help="[server] The \"Content-Type\" header to set when response body data is given with `--response`")
 @click.option("--request-script", type=click.Path(exists=True),
-              help="A Python script whose `run(request)` method will be called by the default `/webhook` after all "
-                   "request plugins have run.")
+              help="[server] A Python script whose `run(request)` method will be called by the default `/webhook` "
+                   "after all request plugins have run.")
 @click.option("--response-script", type=click.Path(exists=True),
-              help="A Python script whose `run(request, response)` method will be called by the default `/webhook` "
-                   "after all response plugins have run.")
-@click.option("--auth-token", help="A valid ngrok auth token.")
+              help="[server] A Python script whose `run(request, response)` method will be called by the default "
+                   "`/webhook` after all response plugins have run.")
+@click.option("--subdomain", help="[tunnel] The subdomain to use for ngrok endpoints.")
+@click.option("--region", type=click.Choice(["us", "eu", "ap", "au", "sa", "jp", "in"]),
+              help="The region to use for ngrok endpoints.")
+@click.option("--hostname", help="[tunnel] The hostname to use for ngrok endpoints.")
+@click.option("--auth", help="[tunnel] The basic auth to use for ngrok endpoints.")
+@click.option("--host-header", help="[tunnel] The \"Host\" header value to use for ngrok endpoints.")
+@click.option("--auth-token", help="[tunnel] A valid ngrok auth token.")
 @click.option("--plugins-dir", type=click.Path(exists=True), help="The directory to scan for custom hookee plugins.")
 @click.option("--plugins", multiple=True, help="A list of hookee plugins to use.")
 @click.option('--version', is_flag=True, default=False, help="Display version information.")
 def hookee(ctx, **kwargs):
     """
-    hookee is a utility that provides command line webhooks, on demand! Dump useful request data to the
-    console, process requests and responses, customize response data, and configure hookee and its routes
-    further in any number of ways through custom plugins.
+    hookee is a utility that provides command line webhooks, on demand! Bind port to intercept requests,
+    dump request data to the console, process requests and responses, customize response data, and configure hookee and
+    its routes further in any number of ways through custom plugins.
 
     hookee can be started by using `hookee start` or simply hookee.