Merge pull request #11911 from lafirest/fix/limiter_doc

fix(limiter): simplify the descriptions for fields of the limiter

apps/emqx/src/emqx_limiter/src/emqx_limiter_schema.erl

@@ -33,7 +33,7 @@
     desc/1,
     types/0,
     short_paths/0,
-    short_paths_fields/1
+    short_paths_fields/0
 ]).
 
 -define(KILOBYTE, 1024).
@@ -103,11 +103,11 @@ roots() ->
     ].
 
 fields(limiter) ->
-    short_paths_fields(?MODULE, ?IMPORTANCE_HIDDEN) ++
+    short_paths_fields(?IMPORTANCE_HIDDEN) ++
         [
             {Type,
                 ?HOCON(?R_REF(node_opts), #{
-                    desc => ?DESC(Type),
+                    desc => deprecated_desc(Type),
                     importance => ?IMPORTANCE_HIDDEN,
                     required => {false, recursively},
                     aliases => alias_of_type(Type)
@@ -120,7 +120,7 @@ fields(limiter) ->
                 ?HOCON(
                     ?R_REF(client_fields),
                     #{
-                        desc => ?DESC(client),
+                        desc => deprecated_desc(client),
                         importance => ?IMPORTANCE_HIDDEN,
                         required => {false, recursively},
                         deprecated => {since, "5.0.25"}
@@ -129,10 +129,10 @@ fields(limiter) ->
         ];
 fields(node_opts) ->
     [
-        {rate, ?HOCON(rate(), #{desc => ?DESC(rate), default => <<"infinity">>})},
+        {rate, ?HOCON(rate(), #{desc => deprecated_desc(rate), default => <<"infinity">>})},
         {burst,
             ?HOCON(burst_rate(), #{
-                desc => ?DESC(burst),
+                desc => deprecated_desc(burst),
                 default => <<"0">>
             })}
     ];
@@ -142,11 +142,12 @@ fields(bucket_opts) ->
     fields_of_bucket(<<"infinity">>);
 fields(client_opts) ->
     [
-        {rate, ?HOCON(rate(), #{default => <<"infinity">>, desc => ?DESC(rate)})},
+        {rate, ?HOCON(rate(), #{default => <<"infinity">>, desc => deprecated_desc(rate)})},
         {initial,
             ?HOCON(initial(), #{
                 default => <<"0">>,
-                desc => ?DESC(initial),
+
+                desc => deprecated_desc(initial),
                 importance => ?IMPORTANCE_HIDDEN
             })},
         %% low_watermark add for emqx_channel and emqx_session
@@ -157,14 +158,14 @@ fields(client_opts) ->
             ?HOCON(
                 initial(),
                 #{
-                    desc => ?DESC(low_watermark),
+                    desc => deprecated_desc(low_watermark),
                     default => <<"0">>,
                     importance => ?IMPORTANCE_HIDDEN
                 }
             )},
         {burst,
             ?HOCON(burst(), #{
-                desc => ?DESC(burst),
+                desc => deprecated_desc(burst),
                 default => <<"0">>,
                 importance => ?IMPORTANCE_HIDDEN,
                 aliases => [capacity]
@@ -173,7 +174,7 @@ fields(client_opts) ->
             ?HOCON(
                 boolean(),
                 #{
-                    desc => ?DESC(divisible),
+                    desc => deprecated_desc(divisible),
                     default => true,
                     importance => ?IMPORTANCE_HIDDEN
                 }
@@ -182,7 +183,7 @@ fields(client_opts) ->
             ?HOCON(
                 emqx_schema:timeout_duration(),
                 #{
-                    desc => ?DESC(max_retry_time),
+                    desc => deprecated_desc(max_retry_time),
                     default => <<"1h">>,
                     importance => ?IMPORTANCE_HIDDEN
                 }
@@ -191,7 +192,7 @@ fields(client_opts) ->
             ?HOCON(
                 failure_strategy(),
                 #{
-                    desc => ?DESC(failure_strategy),
+                    desc => deprecated_desc(failure_strategy),
                     default => force,
                     importance => ?IMPORTANCE_HIDDEN
                 }
@@ -204,14 +205,14 @@ fields(listener_client_fields) ->
 fields(Type) ->
     simple_bucket_field(Type).
 
-short_paths_fields(DesModule) ->
+short_paths_fields() ->
-    short_paths_fields(DesModule, ?DEFAULT_IMPORTANCE).
+    short_paths_fields(?DEFAULT_IMPORTANCE).
 
-short_paths_fields(DesModule, Importance) ->
+short_paths_fields(Importance) ->
     [
         {Name,
             ?HOCON(rate(), #{
-                desc => ?DESC(DesModule, Name),
+                desc => ?DESC(Name),
                 required => false,
                 importance => Importance,
                 example => Example
@@ -381,7 +382,7 @@ simple_bucket_field(Type) when is_atom(Type) ->
                 ?HOCON(
                     ?R_REF(?MODULE, client_opts),
                     #{
-                        desc => ?DESC(client),
+                        desc => deprecated_desc(client),
                         required => {false, recursively},
                         importance => importance_of_type(Type),
                         aliases => alias_of_type(Type)
@@ -394,7 +395,7 @@ composite_bucket_fields(Types, ClientRef) ->
     [
         {Type,
             ?HOCON(?R_REF(?MODULE, bucket_opts), #{
-                desc => ?DESC(?MODULE, Type),
+                desc => deprecated_desc(Type),
                 required => {false, recursively},
                 importance => importance_of_type(Type),
                 aliases => alias_of_type(Type)
@@ -406,7 +407,7 @@ composite_bucket_fields(Types, ClientRef) ->
                 ?HOCON(
                     ?R_REF(?MODULE, ClientRef),
                     #{
-                        desc => ?DESC(client),
+                        desc => deprecated_desc(client),
                         required => {false, recursively}
                     }
                 )}
@@ -414,10 +415,10 @@ composite_bucket_fields(Types, ClientRef) ->
 
 fields_of_bucket(Default) ->
     [
-        {rate, ?HOCON(rate(), #{desc => ?DESC(rate), default => Default})},
+        {rate, ?HOCON(rate(), #{desc => deprecated_desc(rate), default => Default})},
         {burst,
             ?HOCON(burst(), #{
-                desc => ?DESC(burst),
+                desc => deprecated_desc(burst),
                 default => <<"0">>,
                 importance => ?IMPORTANCE_HIDDEN,
                 aliases => [capacity]
@@ -425,7 +426,7 @@ fields_of_bucket(Default) ->
         {initial,
             ?HOCON(initial(), #{
                 default => <<"0">>,
-                desc => ?DESC(initial),
+                desc => deprecated_desc(initial),
                 importance => ?IMPORTANCE_HIDDEN
             })}
     ].
@@ -434,7 +435,7 @@ client_fields(Types) ->
     [
         {Type,
             ?HOCON(?R_REF(client_opts), #{
-                desc => ?DESC(Type),
+                desc => deprecated_desc(Type),
                 required => false,
                 importance => importance_of_type(Type),
                 aliases => alias_of_type(Type)
@@ -457,3 +458,6 @@ alias_of_type(bytes) ->
     [bytes_in];
 alias_of_type(_) ->
     [].
+
+deprecated_desc(_Field) ->
+    <<"Deprecated since v5.0.25">>.

apps/emqx/src/emqx_schema.erl

@@ -1849,7 +1849,7 @@ base_listener(Bind) ->
                     default => true
                 }
             )}
-    ] ++ emqx_limiter_schema:short_paths_fields(?MODULE).
+    ] ++ emqx_limiter_schema:short_paths_fields().
 
 desc("persistent_session_store") ->
     "Settings for message persistence.";

rel/i18n/emqx_limiter_schema.hocon

@@ -2,114 +2,33 @@ emqx_limiter_schema {
 
 max_conn_rate.desc:
 """Maximum connection rate.<br/>
-This is used to limit the connection rate for this node,
+This is used to limit the connection rate for this node.
-once the limit is reached, new connections will be deferred or refused"""
+Once the limit is reached, new connections will be deferred or refused.<br/>
+For example:<br/>
+- <code>1000/s</code> :: Only accepts 1000 connections per second<br/>
+- <code>1000/10s</code> :: Only accepts 1000 connections every 10 seconds"""
 max_conn_rate.label:
 """Maximum Connection Rate"""
 
 messages_rate.desc:
 """Messages publish rate.<br/>
-This is used to limit the inbound message numbers for this node,
+This is used to limit the inbound message numbers for this node.
-once the limit is reached, the restricted client will slow down and even be hung for a while."""
+Once the limit is reached, the restricted client will slow down and even be hung for a while.<br/>
+For example:<br/>
+- <code>500/s</code> :: Only the first 500 messages are sent per second and other messages are buffered.<br/>
+- <code>500/10s</code> :: Only the first 500 messages are sent even 10 second and other messages are buffered."""
 messages_rate.label:
 """Messages Publish Rate"""
 
 bytes_rate.desc:
 """Data publish rate.<br/>
-This is used to limit the inbound bytes rate for this node,
+This is used to limit the inbound bytes rate for this node.
-once the limit is reached, the restricted client will slow down and even be hung for a while."""
+Once the limit is reached, the restricted client will slow down and even be hung for a while.<br/>
+The unit of the bytes could be:KB MB GB.<br/>
+For example:<br/>
+- <code>500KB/s</code> :: Only the first 500 kilobytes are sent per second and other messages are buffered.<br/>
+- <code>500MB/10s</code> :: Only the first 500 megabytes are sent even 10 second and other messages are buffered."""
 bytes_rate.label:
 """Data Publish Rate"""
 
-bucket_cfg.desc:
-"""Bucket Configs"""
-
-bucket_cfg.label:
-"""Buckets"""
-
-burst.desc:
-"""The burst, This value is based on rate.<br/>
- This value + rate = the maximum limit that can be achieved when limiter burst."""
-
-burst.label:
-"""Burst"""
-
-bytes.desc:
-"""The `bytes` limiter.
-This is used to limit the inbound bytes rate for this EMQX node.
-Once the limit is reached, the restricted client will be slow down even be hung for a while."""
-
-bytes.label:
-"""Bytes"""
-
-client.desc:
-"""The rate limit for each user of the bucket"""
-
-client.label:
-"""Per Client"""
-
-connection.desc:
-"""The connection limiter.
-This is used to limit the connection rate for this EMQX node.
-Once the limit is reached, new connections will be refused"""
-
-connection.label:
-"""Connection"""
-
-divisible.desc:
-"""Is it possible to split the number of requested tokens?"""
-
-divisible.label:
-"""Divisible"""
-
-failure_strategy.desc:
-"""The strategy when all the retries failed."""
-
-failure_strategy.label:
-"""Failure Strategy"""
-
-initial.desc:
-"""The initial number of tokens for this bucket."""
-
-initial.label:
-"""Initial"""
-
-internal.desc:
-"""Limiter for EMQX internal app."""
-
-low_watermark.desc:
-"""If the remaining tokens are lower than this value,
-the check/consume will succeed, but it will be forced to wait for a short period of time."""
-
-low_watermark.label:
-"""Low Watermark"""
-
-max_retry_time.desc:
-"""The maximum retry time when acquire failed."""
-
-max_retry_time.label:
-"""Max Retry Time"""
-
-message_routing.desc:
-"""The message routing limiter.
-This is used to limit the forwarding rate for this EMQX node.
-Once the limit is reached, new publish will be refused"""
-
-message_routing.label:
-"""Message Routing"""
-
-messages.desc:
-"""The `messages` limiter.
-This is used to limit the inbound message numbers for this EMQX node
-Once the limit is reached, the restricted client will be slow down even be hung for a while."""
-
-messages.label:
-"""Messages"""
-
-rate.desc:
-"""Rate for this bucket."""
-
-rate.label:
-"""Rate"""
-
 }

rel/i18n/emqx_schema.hocon

@@ -1039,27 +1039,6 @@ base_listener_limiter.desc:
 base_listener_limiter.label:
 """Type of the rate limit."""
 
-max_conn_rate.desc:
-"""Maximum connection rate.<br/>
-This is used to limit the connection rate for this listener,
-once the limit is reached, new connections will be deferred or refused"""
-max_conn_rate.label:
-"""Maximum Connection Rate"""
-
-messages_rate.desc:
-"""Messages publish rate.<br/>
-This is used to limit the inbound message numbers for each client connected to this listener,
-once the limit is reached, the restricted client will slow down and even be hung for a while."""
-messages_rate.label:
-"""Messages Publish Rate"""
-
-bytes_rate.desc:
-"""Data publish rate.<br/>
-This is used to limit the inbound bytes rate for each client connected to this listener,
-once the limit is reached, the restricted client will slow down and even be hung for a while."""
-bytes_rate.label:
-"""Data Publish Rate"""
-
 persistent_session_store_backend.desc:
 """Database management system used to store information about persistent sessions and messages.
 - `builtin`: Use the embedded database (mria)"""