doc: rate_limit uses max_age, not max-age

[moonchen]

The rate_limit YAML parser reads max_age with an underscore, in three places:

• the queue node — plugins/experimental/rate_limit/limiter.h
• the ip-rep node — plugins/experimental/rate_limit/ip_reputation.cc
• the perma-block sub-node — same file

Every mention in the documentation spelled it max-age, including all three
worked examples. A configuration copied from the docs therefore left _max_age
at its default of 0 in each case, which silently disables queue expiry (the
expiry pass in sni_queue_cont() is gated on
max_age() > std::chrono::milliseconds::zero()) and both IP-reputation aging
paths.

This changes the documentation rather than the parser, so that configurations
which are inert today stay inert on upgrade instead of suddenly beginning to
expire queue entries or age out LRU entries with whatever value the operator
wrote.

The --maxage pparam description also referred to a max-age that matches
neither the option name nor the YAML key, so it now just says "maximum age".

max-age was the only key in the documentation that did not match the parser;
ip-rep and perma-block really are hyphenated in the code.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[JosiahWI]

This is great. Could you add a mention of the historical reason for the naming inconsistency to the documentation, so that future developers understand that naming it max-age could activate previously inert configurations?

[moonchen]

This is great. Could you add a mention of the historical reason for the naming inconsistency to the documentation, so that future developers understand that naming it max-age could activate previously inert configurations?

Added a note to the documentation as a separate commit.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (3)

doc/admin-guide/plugins/rate_limit.en.rst:96

• The --maxage option description says the value is in seconds, but the implementation parses it as milliseconds (see txn_limiter.cc where --maxage is stored as std::chrono::milliseconds). This should be corrected so operators don’t configure the wrong delay-queue expiry.

   An optional maximum age for how long a transaction can sit in the delay queue.
   The value (default 0) is the age in seconds.

doc/admin-guide/plugins/rate_limit.en.rst:217

• In the queue section, the sentences “The size is default to …” / “The max_age is …” are ungrammatical; they should read “defaults to” for clarity.

   The queue option can include a `size` and a `max_age` option. The size is
   default to ``UINT_MAX``, which is essentially unlimited. The max_age is
   default to ``0``, which means no age limit.

doc/admin-guide/plugins/rate_limit.en.rst:281

• The new note claims the code ignores max-age “in all versions” of the plugin, which is hard to substantiate from the current tree. Consider rephrasing to the verifiable behavior: the plugin expects max_age and ignores max-age.

   Note that this option was incorrectly documented as ``max-age`` with a hyphen in previous
   versions.  The code ignores ``max-age`` in all versions of this plugin.  We have chosen
   to keep the behavior the same and update the documentation, so that previously inert
   configurations don't activate unexpectedly with an upgrade.

[moonchen]

[approve ci rocky]

[moonchen]

[approve ci rocky]

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

doc/admin-guide/plugins/rate_limit.en.rst:286

• This paragraph claims the code ignores max-age in all versions of the plugin, which is hard to verify and could become incorrect if older versions behaved differently. Suggest rewording to describe the current parser behavior without asserting historical guarantees.

   Note that this option was incorrectly documented as ``max-age`` with a hyphen in previous
   versions.  The code ignores ``max-age`` in all versions of this plugin.  We have chosen
   to keep the behavior the same and update the documentation, so that previously inert
   configurations don't activate unexpectedly with an upgrade.

doc/admin-guide/plugins/rate_limit.en.rst:101

• The note about differing units uses an absolute/historical claim ("have always differed") and the phrase "rather than made consistent" is grammatically awkward. Consider wording this in terms of current behavior to avoid making unverifiable statements about past versions, and tighten the phrasing.

This issue also appears on line 283 of the same file.

   Note that the equivalent YAML setting, ``max_age`` under a ``queue`` node, is in
   seconds. The two configuration paths have always differed by a factor of 1000, so
   the units are documented here as they behave rather than made consistent, to avoid
   changing the expiry of existing configurations.

[moonchen]

[approve ci format rat docs freebsd]