You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@trafficserver.apache.org by "brbzull0 (via GitHub)" <gi...@apache.org> on 2026/10/19 12:51:59 UTC
[PR] ArgParser: honour -- in outer scans, scope state [trafficserver]
brbzull0 opened a new pull request, #13861:
URL: https://github.com/apache/trafficserver/pull/13861
Fixes #13746
Fixes #13648
## Problem
- #13746: every command scans the whole rest of the command line for its own options, and that scan did not honour `--`. A value spelled like a global option was taken as that option even after `--`: `traffic_ctl config set <rec> -- -f` failed with a usage error, and `traffic_ctl config set <rec> -- -h` printed the help and exited 0 without setting anything.
- #13648: the five file-scope variables holding the parser-wide state had external linkage, so libtscore exported them under generic names such as `description`, and a unit test that set a default command or reached the help path left that state behind for the next test.
## What this PR does
- The option scan skips `--` and the token after it, and leaves both to the option or command that owns them, which already honours the escape.
Tests: `Double dash keeps a value away from an outer command's options` in `test_ArgParser.cc`; `traffic_ctl_cold_config` runs 21-26.
- traffic_ctl's global `--watch` and `config reload`'s `--initial-wait` both declared `-w`. The global is read first and took it, so the documented `--initial-wait, -w` did not work. `-w` stays on `--watch`, as it behaves today, and `--initial-wait` is long-only.
Tests: `config_reload_directive_cli` Test 14 and the help check after it; `traffic_ctl_cold_config` runs 27-29.
- The `AddConfigReload` AuTest helper passed `-w`, which went to `--watch`. It now passes `--initial-wait` only when a test asks for one, so the tests keep the wait they ran with.
- The parser-wide state moves into an anonymous namespace, with a test-only `ArgParser::reset_global_state()`.
Tests: `reset_global_state clears every piece of parser-wide state`, `The default command retry replaces the failed pass's values`, and a link-time pin in `test_ArgParser.cc`: it defines globals of the same names, so exporting them again fails the link.
- Docs: `ArgParser.en.rst`, `traffic_ctl.en.rst`, `config-reload-ext.en.rst` and a note in `upgrading.en.rst`.
## Behaviour change
A `--` written directly before a global option now protects that token, which is what #13746 asks for: `traffic_ctl config set NAME -- -f` sets the record to `-f`. A line that relied on the global option taking the token after `--`, such as `traffic_ctl config set NAME -- -w 5 VAL`, is now refused.
## What this PR does not do
- An outer option taking a subcommand's option as its value (`traffic_ctl config reload -f -m`, #13597) is handled in a separate PR stacked on this one.
- Only the token right after `--` is kept away from the outer scans. A second token after it is still seen by them, as on master (`traffic_ctl config set -- REC -h` prints the help). That can be a follow-up if wanted.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ArgParser: honour -- in outer scans, scope state [trafficserver]
Posted by "brbzull0 (via GitHub)" <gi...@apache.org>.
brbzull0 commented on code in PR #13861:
URL: https://github.com/apache/trafficserver/pull/13861#discussion_r4326557060
##########
include/tscore/ArgParser.h:
##########
@@ -364,6 +364,14 @@ class ArgParser
// Enable test mode - makes do_exit() throw instead of calling exit() for unit testing
static void set_test_mode(bool test = true);
+ /** Clear the parser-wide state held at file scope in ArgParser.cc.
+
+ Test-only. A program builds one parser and never reuses the state, but a unit test binary
+ runs many parsers in sequence, and set_default_command() or Command::set_default() would
+ otherwise leak default_command into every later test.
+ */
+ static void reset_global_state();
Review Comment:
No change, as in https://github.com/apache/trafficserver/pull/13861#discussion_r4314314492: `reset_global_state()` is declared under the `protected:` label of `ArgParser` (the one above `do_exit()` and `set_test_mode()`), not public, and `tscore` headers are not installed; tests reach it through a derived `Access` struct.
##########
src/traffic_ctl/traffic_ctl.cc:
##########
@@ -173,8 +173,9 @@ main([[maybe_unused]] int argc, const char **argv)
.add_option("--data", "-d", "Inline config data (@file, @- for stdin, or yaml string)", "", MORE_THAN_ZERO_ARG_N, "")
.add_option("--directive", "-D", "Pass a reload directive to a config handler (format: config_key.directive_key=value)", "",
MORE_THAN_ZERO_ARG_N, "")
+ // No short form: -w is the global --watch.
.add_option(
- "--initial-wait", "-w",
+ "--initial-wait", "",
"Initial wait before first poll, giving the server time to schedule all handlers (seconds). Accepts fractional values", "", 1,
"2")
Review Comment:
No change, as in https://github.com/apache/trafficserver/pull/13861#discussion_r4314315542: `add_option` takes the short form as `std::string const &`, an empty string is never added to the short-option map, and `""` is how the other long-only options in this file are declared.
##########
src/tscore/ArgParser.cc:
##########
@@ -39,11 +44,23 @@ std::string default_command;
// by default return EX_USAGE(64) when usage is called.
// if -h or --help is called specifically, return 0
int usage_return_code = EX_USAGE;
+} // namespace
namespace ts
{
bool ArgParser::_test_mode = false;
+// protected method for testing
+/*static*/ void
+ArgParser::reset_global_state()
+{
+ global_usage.clear();
+ description.clear();
+ parser_program_name.clear();
+ default_command.clear();
+ usage_return_code = EX_USAGE;
+}
Review Comment:
No change: the declaration is in the `protected:` section of `ArgParser` in `include/tscore/ArgParser.h`, so the comment matches; see https://github.com/apache/trafficserver/pull/13861#discussion_r4314314492.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ArgParser: honour -- in outer scans, scope state [trafficserver]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #13861:
URL: https://github.com/apache/trafficserver/pull/13861#discussion_r4326467105
##########
include/tscore/ArgParser.h:
##########
@@ -364,6 +364,14 @@ class ArgParser
// Enable test mode - makes do_exit() throw instead of calling exit() for unit testing
static void set_test_mode(bool test = true);
+ /** Clear the parser-wide state held at file scope in ArgParser.cc.
+
+ Test-only. A program builds one parser and never reuses the state, but a unit test binary
+ runs many parsers in sequence, and set_default_command() or Command::set_default() would
+ otherwise leak default_command into every later test.
+ */
+ static void reset_global_state();
Review Comment:
This adds a new public API that is explicitly described as “Test-only”, which makes it callable by production code and part of the installed interface. Consider hiding it behind a build-time test macro (e.g., only available in unit-test builds), or making it non-public (private/protected) and exposing it to tests via a dedicated test hook/friend, so the public API surface remains production-focused.
##########
src/traffic_ctl/traffic_ctl.cc:
##########
@@ -173,8 +173,9 @@ main([[maybe_unused]] int argc, const char **argv)
.add_option("--data", "-d", "Inline config data (@file, @- for stdin, or yaml string)", "", MORE_THAN_ZERO_ARG_N, "")
.add_option("--directive", "-D", "Pass a reload directive to a config handler (format: config_key.directive_key=value)", "",
MORE_THAN_ZERO_ARG_N, "")
+ // No short form: -w is the global --watch.
.add_option(
- "--initial-wait", "-w",
+ "--initial-wait", "",
"Initial wait before first poll, giving the server time to schedule all handlers (seconds). Accepts fractional values", "", 1,
"2")
Review Comment:
Passing an empty string to represent “no short option” can be ambiguous depending on how `add_option` interprets the parameter (e.g., some implementations treat empty/invalid short options differently than an absent one). If `add_option` supports it, prefer an explicit ‘no short option’ value (such as `nullptr` or an overload without a short-form parameter) to make the intent unambiguous.
##########
src/tscore/ArgParser.cc:
##########
@@ -39,11 +44,23 @@ std::string default_command;
// by default return EX_USAGE(64) when usage is called.
// if -h or --help is called specifically, return 0
int usage_return_code = EX_USAGE;
+} // namespace
namespace ts
{
bool ArgParser::_test_mode = false;
+// protected method for testing
+/*static*/ void
+ArgParser::reset_global_state()
+{
+ global_usage.clear();
+ description.clear();
+ parser_program_name.clear();
+ default_command.clear();
+ usage_return_code = EX_USAGE;
+}
Review Comment:
The comment says this is a “protected method for testing”, but the declaration added in the header is public. Please either adjust the comment to match the actual access level or change the access level to match the intent, to avoid misleading future maintainers.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ArgParser: honour -- in outer scans, scope state [trafficserver]
Posted by "bryancall (via GitHub) via github" <gi...@trafficserver.apache.org>.
bryancall commented on PR #13861:
URL: https://github.com/apache/trafficserver/pull/13861#issuecomment-6553442654
[approve ci urtest clang-tidy]
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ArgParser: honour -- in outer scans, scope state [trafficserver]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #13861:
URL: https://github.com/apache/trafficserver/pull/13861#discussion_r4314279921
##########
src/tscore/unit_tests/test_ArgParser.cc:
##########
@@ -719,3 +723,250 @@ TEST_CASE("The variable only applies when every occurrence of a repeated option
REQUIRE(parsed.get("directive").size() == 0);
}
}
+
+namespace
+{
+// Parser-wide state lives at file scope in ArgParser.cc and outlives any one parser: a test
+// that reaches the help path leaves usage_return_code at 0 for every test after it, and a test
+// that sets a default command leaves that too. Clear it on the way in and on the way out.
+class ArgParserStateGuard
+{
+public:
+ ArgParserStateGuard() { reset(); }
+ ~ArgParserStateGuard() { reset(); }
+ static void
+ reset()
+ {
+ Access::reset_global_state();
+ }
+
+private:
+ struct Access : ts::ArgParser {
+ using ts::ArgParser::reset_global_state;
+ };
+};
+} // namespace
+
+// Link-time check that the parser-wide state stays internal to ArgParser.cc: were any of these
+// names exported from libtscore again, this binary would fail to link with duplicate symbols.
+std::string global_usage;
+std::string description;
+std::string parser_program_name;
+std::string default_command;
+int usage_return_code = 0;
Review Comment:
This link-time check intentionally introduces very generic externally-linked symbols (`description`, `default_command`, etc.). That can make the unit test binary more fragile if another test TU later introduces a same-named global for unrelated reasons (causing an unexpected duplicate-symbol failure). Consider isolating this check into a dedicated translation unit (so the intent is explicit and localized), or using a compiler-supported symbol alias/label technique to avoid reserving common identifiers across the whole test binary.
##########
src/tscore/ArgParser.cc:
##########
@@ -39,11 +44,23 @@ std::string default_command;
// by default return EX_USAGE(64) when usage is called.
// if -h or --help is called specifically, return 0
int usage_return_code = EX_USAGE;
+} // namespace
namespace ts
{
bool ArgParser::_test_mode = false;
+// protected method for testing
Review Comment:
The comment says this is a “protected method for testing”, but `reset_global_state()` is declared as a public API in the header. Please align intent and implementation: either (a) keep it public and update the comment (and tests can call `ts::ArgParser::reset_global_state()` directly), or (b) make it actually test-only (e.g., protected/private behind a test-only build flag) and keep the access shim.
##########
include/tscore/ArgParser.h:
##########
@@ -364,6 +364,14 @@ class ArgParser
// Enable test mode - makes do_exit() throw instead of calling exit() for unit testing
static void set_test_mode(bool test = true);
+ /** Clear the parser-wide state held at file scope in ArgParser.cc.
+
+ Test-only. A program builds one parser and never reuses the state, but a unit test binary
+ runs many parsers in sequence, and set_default() would otherwise leak default_command into
+ every later test.
Review Comment:
The comment references `set_default()`, but the API in this codebase appears to be `set_default_command(...)` (as used in the new unit tests). Please update the comment to use the correct function name to avoid misleading future readers.
##########
src/traffic_ctl/traffic_ctl.cc:
##########
@@ -173,8 +173,9 @@ main([[maybe_unused]] int argc, const char **argv)
.add_option("--data", "-d", "Inline config data (@file, @- for stdin, or yaml string)", "", MORE_THAN_ZERO_ARG_N, "")
.add_option("--directive", "-D", "Pass a reload directive to a config handler (format: config_key.directive_key=value)", "",
MORE_THAN_ZERO_ARG_N, "")
+ // No short form: -w is the global --watch.
.add_option(
- "--initial-wait", "-w",
+ "--initial-wait", "",
"Initial wait before first poll, giving the server time to schedule all handlers (seconds). Accepts fractional values", "", 1,
"2")
Review Comment:
Using an empty string to indicate “no short option” is less explicit than passing a null/absent value, and can be error-prone if `add_option` treats “non-null pointer” as “short option present”. If `add_option` supports it, prefer a `nullptr` (or a dedicated overload) for “no short form”, so this can’t accidentally register an empty/invalid short option.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ArgParser: honour -- in outer scans, scope state [trafficserver]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #13861:
URL: https://github.com/apache/trafficserver/pull/13861#discussion_r4334798972
##########
doc/appendices/command-line/traffic_ctl.en.rst:
##########
@@ -536,10 +536,14 @@ Display the current value of a configuration record.
$ traffic_ctl config reload -D myconfig.id=foo --monitor
$ traffic_ctl config reload -D myconfig.id=foo -d 'myconfig: {rules: [a]}'
- To pass a directive value that begins with ``-``, place ``--`` before it. Option
- recognition then stays off for the rest of the line, so every remaining token becomes
- a directive value and any option written afterwards is swallowed. Use
- ``--directive=-value`` instead when options still have to follow:
+ To pass a directive value that begins with ``-``, place ``--`` before it. Recognition of
+ ``config reload``'s own options then stays off for the rest of the line, so every
+ remaining token becomes a directive value and any of those options written afterwards
+ is swallowed. The global options (``--format``, ``--help``, ``--run-root``, ...) are
Review Comment:
Grammar issue: 'any of those options ... is swallowed' should be plural ('are swallowed') or rephrased ('will be swallowed'), since the subject is 'options'.
##########
include/tscore/ArgParser.h:
##########
@@ -364,6 +364,14 @@ class ArgParser
// Enable test mode - makes do_exit() throw instead of calling exit() for unit testing
static void set_test_mode(bool test = true);
+ /** Clear the parser-wide state held at file scope in ArgParser.cc.
+
+ Test-only. A program builds one parser and never reuses the state, but a unit test binary
+ runs many parsers in sequence, and set_default_command() or Command::set_default() would
+ otherwise leak default_command into every later test.
+ */
+ static void reset_global_state();
Review Comment:
This introduces a new public API entry point that is explicitly 'Test-only'. To keep the production API surface clean, consider making this `protected` (your unit tests already use a derived `Access` shim) and/or compiling it under a test-only build define so it isn't available to non-test consumers.
##########
src/traffic_ctl/traffic_ctl.cc:
##########
@@ -173,8 +173,9 @@ main([[maybe_unused]] int argc, const char **argv)
.add_option("--data", "-d", "Inline config data (@file, @- for stdin, or yaml string)", "", MORE_THAN_ZERO_ARG_N, "")
.add_option("--directive", "-D", "Pass a reload directive to a config handler (format: config_key.directive_key=value)", "",
MORE_THAN_ZERO_ARG_N, "")
+ // No short form: -w is the global --watch.
.add_option(
- "--initial-wait", "-w",
+ "--initial-wait", "",
"Initial wait before first poll, giving the server time to schedule all handlers (seconds). Accepts fractional values", "", 1,
"2")
Review Comment:
Passing an empty string as the short option can be interpreted differently than 'no short option' (e.g., some implementations test for nullptr, or assume a non-empty string starts with '-'). Prefer using a null pointer (if the overload supports it) or a dedicated long-only `add_option` overload to avoid malformed help text or unexpected parsing behavior.
##########
src/tscore/ArgParser.cc:
##########
@@ -799,6 +816,14 @@ ArgParser::Command::append_option_data(Arguments &ret, AP_StrVec &args, int inde
std::map<std::string, unsigned> check_map;
for (unsigned i = index; i < args.size(); i++) {
+ // A "--" escapes the token after it. That token belongs to an option or a command further
+ // down the line, which honours the escape itself in handle_args(); this scan covers the
+ // whole remaining command line, so without this it would still match the escaped token
+ // against this command's options. Leave both tokens in place for the owner.
+ if (args[i] == "--") {
+ ++i;
+ continue;
+ }
Review Comment:
Incrementing `i` inside a `for` loop that also increments `i` makes the control flow harder to reason about (and results in `i` advancing by 2 total). Consider rewriting this to advance explicitly (e.g., `i += 2` with a bounds check or using a `while` loop) so it's clearer that you're skipping exactly `--` and the next token and not relying on the loop increment side-effect.
##########
tests/uranium_tests/records/test_traffic_ctl_cold_config.py:
##########
@@ -176,3 +176,28 @@ def test_traffic_ctl_cold_config(ats_factory: ATSFactory) -> None:
_ats.environment["TS_RECORD_YAML"] = str(destination)
traffic_ctl("config", "set", "proxy.config.cache.limits.http.max_alts", "3", "-c", _ats=_ats)
assert yaml.safe_load(destination.read_text()) == {"records": {"cache": {"limits": {"http": {"max_alts": 3}}}}}
+
+ # A "--" is the way to pass a value that starts with '-'. The option scan of every enclosing
+ # command covers the whole rest of the command line, so the escape has to be honoured there
+ # too, or a value spelled like a global option (-f, -h) or like an option of config set itself
+ # (-t) is taken as that option instead of reaching the record. -h is the worse case: it prints
Review Comment:
Correct 'worse case' to 'worst case' in the comment.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ArgParser: honour -- in outer scans, scope state [trafficserver]
Posted by "brbzull0 (via GitHub)" <gi...@apache.org>.
brbzull0 commented on code in PR #13861:
URL: https://github.com/apache/trafficserver/pull/13861#discussion_r4334851823
##########
include/tscore/ArgParser.h:
##########
@@ -364,6 +364,14 @@ class ArgParser
// Enable test mode - makes do_exit() throw instead of calling exit() for unit testing
static void set_test_mode(bool test = true);
+ /** Clear the parser-wide state held at file scope in ArgParser.cc.
+
+ Test-only. A program builds one parser and never reuses the state, but a unit test binary
+ runs many parsers in sequence, and set_default_command() or Command::set_default() would
+ otherwise leak default_command into every later test.
+ */
+ static void reset_global_state();
Review Comment:
No change, as in https://github.com/apache/trafficserver/pull/13861#discussion_r4314314492: `reset_global_state()` is declared under the `protected:` label of `ArgParser`, and `tscore` headers are not installed; the tests reach it through the derived `Access` shim.
##########
src/traffic_ctl/traffic_ctl.cc:
##########
@@ -173,8 +173,9 @@ main([[maybe_unused]] int argc, const char **argv)
.add_option("--data", "-d", "Inline config data (@file, @- for stdin, or yaml string)", "", MORE_THAN_ZERO_ARG_N, "")
.add_option("--directive", "-D", "Pass a reload directive to a config handler (format: config_key.directive_key=value)", "",
MORE_THAN_ZERO_ARG_N, "")
+ // No short form: -w is the global --watch.
.add_option(
- "--initial-wait", "-w",
+ "--initial-wait", "",
"Initial wait before first poll, giving the server time to schedule all handlers (seconds). Accepts fractional values", "", 1,
"2")
Review Comment:
No change, as in https://github.com/apache/trafficserver/pull/13861#discussion_r4314315542: `add_option` takes the short form as `std::string const &`, an empty string is never added to the short-option map, and `""` is how the other long-only options in this file are declared.
##########
doc/appendices/command-line/traffic_ctl.en.rst:
##########
@@ -536,10 +536,14 @@ Display the current value of a configuration record.
$ traffic_ctl config reload -D myconfig.id=foo --monitor
$ traffic_ctl config reload -D myconfig.id=foo -d 'myconfig: {rules: [a]}'
- To pass a directive value that begins with ``-``, place ``--`` before it. Option
- recognition then stays off for the rest of the line, so every remaining token becomes
- a directive value and any option written afterwards is swallowed. Use
- ``--directive=-value`` instead when options still have to follow:
+ To pass a directive value that begins with ``-``, place ``--`` before it. Recognition of
+ ``config reload``'s own options then stays off for the rest of the line, so every
+ remaining token becomes a directive value and any of those options written afterwards
+ is swallowed. The global options (``--format``, ``--help``, ``--run-root``, ...) are
Review Comment:
Reworded to "any such option written afterwards is swallowed", in 38c6f4ed9c.
##########
src/tscore/ArgParser.cc:
##########
@@ -799,6 +816,14 @@ ArgParser::Command::append_option_data(Arguments &ret, AP_StrVec &args, int inde
std::map<std::string, unsigned> check_map;
for (unsigned i = index; i < args.size(); i++) {
+ // A "--" escapes the token after it. That token belongs to an option or a command further
+ // down the line, which honours the escape itself in handle_args(); this scan covers the
+ // whole remaining command line, so without this it would still match the escaped token
+ // against this command's options. Leave both tokens in place for the owner.
+ if (args[i] == "--") {
+ ++i;
+ continue;
+ }
Review Comment:
Kept the `++i; continue;`, which matches the escape handling in `handle_args()`, and the comment now says that this `++i` steps past the `--` and the loop increment past the escaped token, in 38c6f4ed9c.
##########
tests/uranium_tests/records/test_traffic_ctl_cold_config.py:
##########
@@ -176,3 +176,28 @@ def test_traffic_ctl_cold_config(ats_factory: ATSFactory) -> None:
_ats.environment["TS_RECORD_YAML"] = str(destination)
traffic_ctl("config", "set", "proxy.config.cache.limits.http.max_alts", "3", "-c", _ats=_ats)
assert yaml.safe_load(destination.read_text()) == {"records": {"cache": {"limits": {"http": {"max_alts": 3}}}}}
+
+ # A "--" is the way to pass a value that starts with '-'. The option scan of every enclosing
+ # command covers the whole rest of the command line, so the escape has to be honoured there
+ # too, or a value spelled like a global option (-f, -h) or like an option of config set itself
+ # (-t) is taken as that option instead of reaching the record. -h is the worse case: it prints
Review Comment:
Fixed to "worst case", in 38c6f4ed9c.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ArgParser: honour -- in outer scans, scope state [trafficserver]
Posted by "brbzull0 (via GitHub) via github" <gi...@trafficserver.apache.org>.
brbzull0 merged PR #13861:
URL: https://github.com/apache/trafficserver/pull/13861
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ArgParser: honour -- in outer scans, scope state [trafficserver]
Posted by "brbzull0 (via GitHub)" <gi...@apache.org>.
brbzull0 commented on code in PR #13861:
URL: https://github.com/apache/trafficserver/pull/13861#discussion_r4314314492
##########
src/tscore/ArgParser.cc:
##########
@@ -39,11 +44,23 @@ std::string default_command;
// by default return EX_USAGE(64) when usage is called.
// if -h or --help is called specifically, return 0
int usage_return_code = EX_USAGE;
+} // namespace
namespace ts
{
bool ArgParser::_test_mode = false;
+// protected method for testing
Review Comment:
No change: `reset_global_state()` is declared in the protected section of `ArgParser` in `include/tscore/ArgParser.h`, next to `do_exit()` and `set_test_mode()`, so the comment is accurate; the tests reach it through a derived `Access` struct.
##########
src/tscore/unit_tests/test_ArgParser.cc:
##########
@@ -719,3 +723,250 @@ TEST_CASE("The variable only applies when every occurrence of a repeated option
REQUIRE(parsed.get("directive").size() == 0);
}
}
+
+namespace
+{
+// Parser-wide state lives at file scope in ArgParser.cc and outlives any one parser: a test
+// that reaches the help path leaves usage_return_code at 0 for every test after it, and a test
+// that sets a default command leaves that too. Clear it on the way in and on the way out.
+class ArgParserStateGuard
+{
+public:
+ ArgParserStateGuard() { reset(); }
+ ~ArgParserStateGuard() { reset(); }
+ static void
+ reset()
+ {
+ Access::reset_global_state();
+ }
+
+private:
+ struct Access : ts::ArgParser {
+ using ts::ArgParser::reset_global_state;
+ };
+};
+} // namespace
+
+// Link-time check that the parser-wide state stays internal to ArgParser.cc: were any of these
+// names exported from libtscore again, this binary would fail to link with duplicate symbols.
+std::string global_usage;
+std::string description;
+std::string parser_program_name;
+std::string default_command;
+int usage_return_code = 0;
Review Comment:
No change: the check has to define exactly these names with external linkage in the same link as libtscore, so a separate translation unit in test_tscore would reserve the same names; a clash would show as a duplicate-symbol link error at these definitions, next to the comment explaining them.
##########
include/tscore/ArgParser.h:
##########
@@ -364,6 +364,14 @@ class ArgParser
// Enable test mode - makes do_exit() throw instead of calling exit() for unit testing
static void set_test_mode(bool test = true);
+ /** Clear the parser-wide state held at file scope in ArgParser.cc.
+
+ Test-only. A program builds one parser and never reuses the state, but a unit test binary
+ runs many parsers in sequence, and set_default() would otherwise leak default_command into
+ every later test.
Review Comment:
Both setters exist and both write `default_command` (`Command::set_default()` and `ArgParser::set_default_command()`); the comment now names both, in 41bdeee3ad.
##########
src/traffic_ctl/traffic_ctl.cc:
##########
@@ -173,8 +173,9 @@ main([[maybe_unused]] int argc, const char **argv)
.add_option("--data", "-d", "Inline config data (@file, @- for stdin, or yaml string)", "", MORE_THAN_ZERO_ARG_N, "")
.add_option("--directive", "-D", "Pass a reload directive to a config handler (format: config_key.directive_key=value)", "",
MORE_THAN_ZERO_ARG_N, "")
+ // No short form: -w is the global --watch.
.add_option(
- "--initial-wait", "-w",
+ "--initial-wait", "",
"Initial wait before first poll, giving the server time to schedule all handlers (seconds). Accepts fractional values", "", 1,
"2")
Review Comment:
No change: `add_option` takes the short form as `std::string const &`, so passing `nullptr` would be undefined behaviour; an empty string is never added to the short-option map, and it is how the other long-only options in this file are declared (`--run-root`, `--read-timeout-ms`, `--error-level`).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ArgParser: honour -- in outer scans, scope state [trafficserver]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #13861:
URL: https://github.com/apache/trafficserver/pull/13861#discussion_r4335001915
##########
src/tscore/unit_tests/test_ArgParser.cc:
##########
@@ -719,3 +723,255 @@ TEST_CASE("The variable only applies when every occurrence of a repeated option
REQUIRE(parsed.get("directive").size() == 0);
}
}
+
+namespace
+{
+// Parser-wide state lives at file scope in ArgParser.cc and outlives any one parser: a test
+// that reaches the help path leaves usage_return_code at 0 for every test after it, and a test
+// that sets a default command leaves that too. Clear it on the way in and on the way out.
+class ArgParserStateGuard
+{
+public:
+ ArgParserStateGuard() { reset(); }
+ ~ArgParserStateGuard() { reset(); }
+ static void
+ reset()
+ {
+ Access::reset_global_state();
+ }
+
+private:
+ struct Access : ts::ArgParser {
+ using ts::ArgParser::reset_global_state;
+ };
+};
+
+// Keeps the help and usage text that a parser prints out of the test output, and lets it be
+// checked. std::cout is put back however the scope ends.
+struct CoutCapture {
+ CoutCapture() = default;
+ CoutCapture(CoutCapture const &) = delete;
+ CoutCapture &operator=(CoutCapture const &) = delete;
+ ~CoutCapture() { std::cout.rdbuf(old); }
+
+ std::ostringstream buf;
+ std::streambuf *old = std::cout.rdbuf(buf.rdbuf());
+};
+} // namespace
+
+// Link-time check that the parser-wide state stays internal to ArgParser.cc: were any of these
+// names exported from libtscore again, this binary would fail to link with duplicate symbols.
+// That holds for the default static libtscore; with a shared one the link does not fail.
+std::string global_usage;
+std::string description;
+std::string parser_program_name;
+std::string default_command;
+int usage_return_code = 0;
+
+TEST_CASE("Double dash keeps a value away from an outer command's options", "[parse]")
Review Comment:
The “duplicate symbol” link-time pin can be defeated by dead-stripping/LTO/`--gc-sections` if these globals are not considered “used”, which would turn the check into a false negative on some toolchains/configurations. To make the check deterministic, consider forcing retention (e.g., compiler `used`/`retain` attribute or an explicit reference in a test that odr-uses each symbol).
##########
src/traffic_ctl/traffic_ctl.cc:
##########
@@ -173,8 +173,9 @@ main([[maybe_unused]] int argc, const char **argv)
.add_option("--data", "-d", "Inline config data (@file, @- for stdin, or yaml string)", "", MORE_THAN_ZERO_ARG_N, "")
.add_option("--directive", "-D", "Pass a reload directive to a config handler (format: config_key.directive_key=value)", "",
MORE_THAN_ZERO_ARG_N, "")
+ // No short form: -w is the global --watch.
.add_option(
- "--initial-wait", "-w",
+ "--initial-wait", "",
"Initial wait before first poll, giving the server time to schedule all handlers (seconds). Accepts fractional values", "", 1,
"2")
Review Comment:
Passing an empty string (`""`) as the “short option” argument is ambiguous and can be error-prone if `ArgParser` treats it as a real (but empty) option name or assumes the string is at least `"-x"` length in internal logic. If the API supports “no short option”, it’s safer/clearer to pass `nullptr` (or use an overload that omits the short form) rather than `""`.
##########
include/tscore/ArgParser.h:
##########
@@ -364,6 +364,14 @@ class ArgParser
// Enable test mode - makes do_exit() throw instead of calling exit() for unit testing
static void set_test_mode(bool test = true);
+ /** Clear the parser-wide state held at file scope in ArgParser.cc.
+
+ Test-only. A program builds one parser and never reuses the state, but a unit test binary
+ runs many parsers in sequence, and set_default_command() or Command::set_default() would
+ otherwise leak default_command into every later test.
+ */
+ static void reset_global_state();
Review Comment:
`reset_global_state()` is explicitly “Test-only” but is declared in a public header as part of the library API. That makes it easier for production code to depend on it (and creates an ABI/API surface you may not want to support long-term). Consider gating the declaration behind a test/build flag (e.g., only when building unit tests), moving it to a test-only header, or making it non-public (e.g., `protected`) and exposing it to tests via a friend/accessor pattern.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ArgParser: honour -- in outer scans, scope state [trafficserver]
Posted by "brbzull0 (via GitHub)" <gi...@apache.org>.
brbzull0 commented on code in PR #13861:
URL: https://github.com/apache/trafficserver/pull/13861#discussion_r4335011673
##########
include/tscore/ArgParser.h:
##########
@@ -364,6 +364,14 @@ class ArgParser
// Enable test mode - makes do_exit() throw instead of calling exit() for unit testing
static void set_test_mode(bool test = true);
+ /** Clear the parser-wide state held at file scope in ArgParser.cc.
+
+ Test-only. A program builds one parser and never reuses the state, but a unit test binary
+ runs many parsers in sequence, and set_default_command() or Command::set_default() would
+ otherwise leak default_command into every later test.
+ */
+ static void reset_global_state();
Review Comment:
No change, as in https://github.com/apache/trafficserver/pull/13861#discussion_r4314314492: `reset_global_state()` is declared under the `protected:` label of `ArgParser`, and `tscore` headers are not installed; the tests reach it through the derived `Access` shim.
##########
src/traffic_ctl/traffic_ctl.cc:
##########
@@ -173,8 +173,9 @@ main([[maybe_unused]] int argc, const char **argv)
.add_option("--data", "-d", "Inline config data (@file, @- for stdin, or yaml string)", "", MORE_THAN_ZERO_ARG_N, "")
.add_option("--directive", "-D", "Pass a reload directive to a config handler (format: config_key.directive_key=value)", "",
MORE_THAN_ZERO_ARG_N, "")
+ // No short form: -w is the global --watch.
.add_option(
- "--initial-wait", "-w",
+ "--initial-wait", "",
"Initial wait before first poll, giving the server time to schedule all handlers (seconds). Accepts fractional values", "", 1,
"2")
Review Comment:
No change, as in https://github.com/apache/trafficserver/pull/13861#discussion_r4314315542: `add_option` takes the short form as `std::string const &`, an empty string is never added to the short-option map, and `""` is how the other long-only options in this file are declared.
##########
src/tscore/unit_tests/test_ArgParser.cc:
##########
@@ -719,3 +723,255 @@ TEST_CASE("The variable only applies when every occurrence of a repeated option
REQUIRE(parsed.get("directive").size() == 0);
}
}
+
+namespace
+{
+// Parser-wide state lives at file scope in ArgParser.cc and outlives any one parser: a test
+// that reaches the help path leaves usage_return_code at 0 for every test after it, and a test
+// that sets a default command leaves that too. Clear it on the way in and on the way out.
+class ArgParserStateGuard
+{
+public:
+ ArgParserStateGuard() { reset(); }
+ ~ArgParserStateGuard() { reset(); }
+ static void
+ reset()
+ {
+ Access::reset_global_state();
+ }
+
+private:
+ struct Access : ts::ArgParser {
+ using ts::ArgParser::reset_global_state;
+ };
+};
+
+// Keeps the help and usage text that a parser prints out of the test output, and lets it be
+// checked. std::cout is put back however the scope ends.
+struct CoutCapture {
+ CoutCapture() = default;
+ CoutCapture(CoutCapture const &) = delete;
+ CoutCapture &operator=(CoutCapture const &) = delete;
+ ~CoutCapture() { std::cout.rdbuf(old); }
+
+ std::ostringstream buf;
+ std::streambuf *old = std::cout.rdbuf(buf.rdbuf());
+};
+} // namespace
+
+// Link-time check that the parser-wide state stays internal to ArgParser.cc: were any of these
+// names exported from libtscore again, this binary would fail to link with duplicate symbols.
+// That holds for the default static libtscore; with a shared one the link does not fail.
+std::string global_usage;
+std::string description;
+std::string parser_program_name;
+std::string default_command;
+int usage_return_code = 0;
+
+TEST_CASE("Double dash keeps a value away from an outer command's options", "[parse]")
Review Comment:
No change beyond ed8347ca4d, see https://github.com/apache/trafficserver/pull/13862#discussion_r4334878154: a plain link fails on the duplicates, and ATS links without dead stripping; under Apple ld's `-dead_strip` the duplicates become warnings even when the globals are kept alive by `used` or a reference, so the comment states that limit.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org