From 2b97800c8b8c527cfeb8de8051de0d38954f9f6d Mon Sep 17 00:00:00 2001 From: firest Date: Thu, 9 Nov 2023 15:38:34 +0800 Subject: [PATCH] fix(limiter): simplify the descriptions for fields of the limiter --- .../emqx_limiter/src/emqx_limiter_schema.erl | 52 ++++---- apps/emqx/src/emqx_schema.erl | 2 +- rel/i18n/emqx_limiter_schema.hocon | 113 +++--------------- rel/i18n/emqx_schema.hocon | 21 ---- 4 files changed, 45 insertions(+), 143 deletions(-) diff --git a/apps/emqx/src/emqx_limiter/src/emqx_limiter_schema.erl b/apps/emqx/src/emqx_limiter/src/emqx_limiter_schema.erl index 802b29837..2dd4aa241 100644 --- a/apps/emqx/src/emqx_limiter/src/emqx_limiter_schema.erl +++ b/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(DesModule, ?DEFAULT_IMPORTANCE). +short_paths_fields() -> + 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">>. diff --git a/apps/emqx/src/emqx_schema.erl b/apps/emqx/src/emqx_schema.erl index 804a3a04c..3848e77b4 100644 --- a/apps/emqx/src/emqx_schema.erl +++ b/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."; diff --git a/rel/i18n/emqx_limiter_schema.hocon b/rel/i18n/emqx_limiter_schema.hocon index b2958ce90..1a0ed5273 100644 --- a/rel/i18n/emqx_limiter_schema.hocon +++ b/rel/i18n/emqx_limiter_schema.hocon @@ -2,114 +2,33 @@ emqx_limiter_schema { max_conn_rate.desc: """Maximum connection rate.
-This is used to limit the connection rate for this node, -once the limit is reached, new connections will be deferred or refused""" +This is used to limit the connection rate for this node. +Once the limit is reached, new connections will be deferred or refused.
+For example:
+- 1000/s :: Only accepts 1000 connections per second
+- 1000/10s :: Only accepts 1000 connections every 10 seconds""" max_conn_rate.label: """Maximum Connection Rate""" messages_rate.desc: """Messages publish rate.
-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.""" +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.
+For example:
+- 500/s :: Only the first 500 messages are sent per second and other messages are buffered.
+- 500/10s :: 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.
-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.""" +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.
+The unit of the bytes could be:KB MB GB.
+For example:
+- 500KB/s :: Only the first 500 kilobytes are sent per second and other messages are buffered.
+- 500MB/10s :: 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.
- 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""" - } diff --git a/rel/i18n/emqx_schema.hocon b/rel/i18n/emqx_schema.hocon index 9ed579994..e1d086197 100644 --- a/rel/i18n/emqx_schema.hocon +++ b/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.
-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.
-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.
-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)"""