From 2cb6eb73ff23ac5bcd8b975e7d73bb0cb83524a9 Mon Sep 17 00:00:00 2001 From: Alex Laird Date: Mon, 25 Nov 2024 17:44:48 -0600 Subject: [PATCH 1/3] Documentation improvements with local proxy example. --- CHANGELOG.md | 4 ++++ README.md | 11 +++++++++++ docs/index.rst | 11 +++++++++++ hookee/cli.py | 40 ++++++++++++++++++++-------------------- 4 files changed, 46 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f56ad22..ba07fe3 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 89f885d..bd8da7c 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,17 @@ here we are customizing the response body from `/webhook` using the `--response` hookee --response "Ok" --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 "Ok" --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 diff --git a/docs/index.rst b/docs/index.rst index a29b036..9057c88 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -63,6 +63,17 @@ here we are customizing the response body from ``/webhook`` using the ``--respon hookee --response "Ok" --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 `_, +`Envoy `_, 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 "Ok" --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 diff --git a/hookee/cli.py b/hookee/cli.py index 9870026..4e7984d 100644 --- a/hookee/cli.py +++ b/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. From 6ec5e6b3e3710486668f159880f64a833ecb5c72 Mon Sep 17 00:00:00 2001 From: Alex Laird Date: Mon, 25 Nov 2024 17:46:06 -0600 Subject: [PATCH 2/3] Fix typo in docs. --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 9057c88..c6a0706 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -130,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 From 51d949091c2aa5d8a574c7404c45c182b0fe50be Mon Sep 17 00:00:00 2001 From: Alex Laird Date: Mon, 25 Nov 2024 17:52:42 -0600 Subject: [PATCH 3/3] Update SECURITY.md --- SECURITY.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index b6aaa6a..cb8967e 100644 --- a/SECURITY.md +++ b/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