From: Willy Tarreau <w@1wt.eu>
Date: Fri, 9 Feb 2024 16:40:43 +0000 (+0100)
Subject: MINOR: cli/wait: make the wait command support a more detailed help message
X-Git-Tag: v3.0-dev3~7
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d8731c6680c6c67bbf7725ccbe3f8737f3981fe0;p=thirdparty%2Fhaproxy.git

MINOR: cli/wait: make the wait command support a more detailed help message

We'll want to add some waiting conditions, so let's support -h to show
the available list, and also print this usage on unknown options.
---

diff --git a/doc/management.txt b/doc/management.txt
index c5e5579d37..dfd8eee2f1 100644
--- a/doc/management.txt
+++ b/doc/management.txt
@@ -3997,12 +3997,13 @@ update ssl ocsp-response <certfile>
   local tree, its contents will be displayed on the standard output. The format
   is the same as the one described in "show ssl ocsp-response".
 
-wait <delay>
+wait { -h | <delay> }
   This simply waits for the requested delay before continuing. This can be used
   to collect metrics around a specific interval. The default unit for the delay
   is milliseconds, though other units are accepted if suffixed with the usual
-  timer units (s, m, h, d). When used with the 'socat' utility, do not forget
-  to extend socat's close timeout to cover the wait time.
+  timer units (us, ms, s, m, h, d). When used with the 'socat' utility, do not
+  forget to extend socat's close timeout to cover the wait time. Passing "-h"
+  as the first or second argument provides the command's usage.
   Example:
     $ socat -t20 /path/to/socket <<< "show activity; wait 10s; show activity"
 
diff --git a/src/cli.c b/src/cli.c
index acd5b8729e..7c88917a70 100644
--- a/src/cli.c
+++ b/src/cli.c
@@ -2027,8 +2027,28 @@ static int cli_parse_wait(char **args, char *payload, struct appctx *appctx, voi
 		return cli_err(appctx, "Expects a duration in milliseconds.\n");
 
 	err = parse_time_err(args[1], &wait_ms, TIME_UNIT_MS);
-	if (err || wait_ms < 1)
-		return cli_err(appctx, "Invalid duration.\n");
+	if (err || wait_ms < 1) {
+		/* in case -h is passed as the first option, continue to the next test */
+		if (strcmp(args[1], "-h") == 0)
+			args--;
+		else
+			return cli_err(appctx, "Invalid duration.\n");
+	}
+
+	if (*args[2]) {
+		/* show the command's help either upon request (-h) or error */
+		err = "Usage: wait {-h|<duration>} [condition [args...]]\n"
+			"  - '-h' displays this help\n"
+			"  - <duration> is the maximum wait time, optionally suffixed by the unit among\n"
+			"    'us', 'ms', 's', 'm', 'h', and 'd'. ; the default unit is milliseconds.\n"
+			"  - <condition> indicates what to wait for. By default, no events aborts the\n"
+			"    operation, which makes it reliably pause for the specified duration.\n";
+
+		if (strcmp(args[2], "-h") == 0)
+			return cli_msg(appctx, LOG_INFO, err);
+		else
+			return cli_err(appctx, err);
+	}
 
 	ctx->start = now_ms;
 	ctx->deadline = tick_add(now_ms, wait_ms);
@@ -3505,7 +3525,7 @@ static struct cli_kw_list cli_kws = {{ },{
 	{ { "show", "version", NULL },           "show version                            : show version of the current process",                     cli_parse_show_version, NULL, NULL, NULL, ACCESS_MASTER },
 	{ { "operator", NULL },                  "operator                                : lower the level of the current CLI session to operator",  cli_parse_set_lvl, NULL, NULL, NULL, ACCESS_MASTER},
 	{ { "user", NULL },                      "user                                    : lower the level of the current CLI session to user",      cli_parse_set_lvl, NULL, NULL, NULL, ACCESS_MASTER},
-	{ { "wait", NULL },                      "wait <ms>                               : wait the specified delay",                                cli_parse_wait, cli_io_handler_wait, cli_release_wait, NULL },
+	{ { "wait", NULL },                      "wait {-h|<delay_ms>}                    : wait the specified delay (-h to see usage)",              cli_parse_wait, cli_io_handler_wait, cli_release_wait, NULL },
 	{{},}
 }};