Merge pull request #7103 from ieQu1/doc-schema

docs: Add to the schema

.github/workflows/build_slim_packages.yaml

@@ -218,7 +218,7 @@ jobs:
         - emqx
         - emqx-enterprise
     runs-on: ubuntu-20.04
-    container: "ghcr.io/iequ1/emqx-schema-validate:0.2.1"
+    container: "ghcr.io/iequ1/emqx-schema-validate:0.2.2"
     steps:
     - uses: actions/download-artifact@v2
       name: Download schema dump

apps/emqx/etc/emqx.conf

@@ -1014,9 +1014,9 @@ broker {
   ## @doc broker.session_locking_strategy
   ## ValueType: local | one | quorum | all
   ##   - local: only lock the session locally on the current node
-  ##   - one: select only one remove node to lock the session
+  ##   - one: select only one remote node to lock the session
   ##   - quorum: select some nodes to lock the session
-  ##   - all: lock the session on all of the nodes in the cluster
+  ##   - all: lock the session on all the nodes in the cluster
   ## Default: quorum
   session_locking_strategy = quorum
 
@@ -1027,7 +1027,7 @@ broker {
   ##   - random: dispatch the message to a random selected subscriber
   ##   - round_robin: select the subscribers in a round-robin manner
   ##   - sticky: always use the last selected subscriber to dispatch,
-  ##     until the susbcriber disconnected.
+  ##     until the subscriber disconnects.
   ##   - hash: select the subscribers by the hash of clientIds
   ## Default: round_robin
   shared_subscription_strategy = round_robin
@@ -1158,7 +1158,7 @@ sysmon {
   ## Default: disabled
   vm.long_gc = disabled
 
-  ## Enable Long Schedule(ms) monitoring.
+  ## Enable Long Schedule monitoring.
   ##
   ## See: http://erlang.org/doc/man/erlang.html#system_monitor-2
   ##

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

@@ -107,8 +107,8 @@ fields(limiter_opts) ->
     [ {rate, sc(rate(), #{default => "infinity", desc => "The rate"})}
     , {burst, sc(burst_rate(),
                  #{default => "0/0s",
-                   desc => "The burst, This value is based on rate."
+                   desc => "The burst, This value is based on rate.<br/>
-                   " This value + rate = the maximum limit that can be achieved when limiter burst"
+ This value + rate = the maximum limit that can be achieved when limiter burst."
                   })}
     , {bucket, sc(map("bucket name", ref(bucket_opts)), #{desc => "Buckets config"})}
     ];
@@ -121,7 +121,7 @@ fields(bucket_opts) ->
     , {per_client, sc(ref(client_bucket),
                       #{default => #{},
                         desc => "The rate limit for each user of the bucket,"
-                        "this field is not required"
+                        " this field is not required"
                        })}
     ];
 

apps/emqx/src/emqx_schema.erl

@@ -905,7 +905,12 @@ fields("ws_opts") ->
         {"mqtt_path",
             sc(
                 string(),
-                #{default => "/mqtt"}
+                #{
+                    default => "/mqtt",
+                    desc =>
+                        "WebSocket's MQTT protocol path. So the address of\n"
+                        " EMQX Broker's WebSocket is: <code>ws://{ip}:{port}/mqtt</code>"
+                }
             )},
         {"mqtt_piggyback",
             sc(
@@ -915,52 +920,99 @@ fields("ws_opts") ->
         {"compress",
             sc(
                 boolean(),
-                #{default => false}
+                #{
+                    default => false,
+                    desc =>
+                        "If <code>true</code>, compress WebSocket messages using <code>zlib</code>.<br/>\n"
+                        " The configuration items under <code>deflate_opts</code> belong to the compression-related parameter configuration."
+                }
             )},
         {"idle_timeout",
             sc(
                 duration(),
-                #{default => "15s"}
+                #{
+                    default => "15s",
+                    desc =>
+                        "The idle time after the TCP connection is established <br/>\n"
+                        " If no packets are received within this time, the connection will be closed."
+                }
             )},
         {"max_frame_size",
             sc(
                 hoconsc:union([infinity, integer()]),
-                #{default => infinity}
+                #{
+                    default => infinity,
+                    desc => "The maximum length of a single MQTT packet."
+                }
             )},
         {"fail_if_no_subprotocol",
             sc(
                 boolean(),
-                #{default => true}
+                #{
+                    default => true,
+                    desc =>
+                        "If <code>true</code>, the server will return an error when\n"
+                        " the client does not carry the <code>Sec-WebSocket-Protocol</code> field.\n"
+                        " <br/>Note: WeChat applet needs to disable this verification."
+                }
             )},
         {"supported_subprotocols",
             sc(
                 comma_separated_list(),
-                #{default => "mqtt, mqtt-v3, mqtt-v3.1.1, mqtt-v5"}
+                #{
+                    default => "mqtt, mqtt-v3, mqtt-v3.1.1, mqtt-v5",
+                    desc => "Comma-separated list of supported subprotocols."
+                }
             )},
         {"check_origin_enable",
             sc(
                 boolean(),
-                #{default => false}
+                #{
+                    default => false,
+                    desc =>
+                        "If <code>true</code>, <code>origin</code> HTTP header will be\n"
+                        " validated against the list of allowed origins configured in <code>check_origins</code>\n"
+                        " parameter."
+                }
             )},
         {"allow_origin_absence",
             sc(
                 boolean(),
-                #{default => true}
+                #{
+                    default => true,
+                    desc =>
+                        "If <code>false</code> and <code>check_origin_enable</code> is\n"
+                        " <code>true</code>, the server will reject requests that don't have <code>origin</code>\n"
+                        " HTTP header."
+                }
             )},
         {"check_origins",
             sc(
                 hoconsc:array(binary()),
-                #{default => []}
+                #{
+                    default => [],
+                    desc => "List of allowed origins.<br/>See <code>check_origin_enable</code>."
+                }
             )},
         {"proxy_address_header",
             sc(
                 string(),
-                #{default => "x-forwarded-for"}
+                #{
+                    default => "x-forwarded-for",
+                    desc =>
+                        "HTTP header used to pass information about the client IP address.\n"
+                        " Relevant when the EMQX cluster is deployed behind a load-balancer."
+                }
             )},
         {"proxy_port_header",
             sc(
                 string(),
-                #{default => "x-forwarded-port"}
+                #{
+                    default => "x-forwarded-port",
+                    desc =>
+                        "HTTP header used to pass information about the client port.\n"
+                        " Relevant when the EMQX cluster is deployed behind a load-balancer."
+                }
             )},
         {"deflate_opts",
             sc(
@@ -973,52 +1025,79 @@ fields("tcp_opts") ->
         {"active_n",
             sc(
                 integer(),
-                #{default => 100}
+                #{
+                    default => 100,
+                    desc =>
+                        "Specify the {active, N} option for this Socket.<br/>\n"
+                        " See: https://erlang.org/doc/man/inet.html#setopts-2"
+                }
             )},
         {"backlog",
             sc(
                 integer(),
-                #{default => 1024}
+                #{
+                    default => 1024,
+                    desc =>
+                        "TCP backlog defines the maximum length that the queue of\n"
+                        " pending connections can grow to."
+                }
             )},
         {"send_timeout",
             sc(
                 duration(),
-                #{default => "15s"}
+                #{
+                    default => "15s",
+                    desc => "The TCP send timeout for the connections."
+                }
             )},
         {"send_timeout_close",
             sc(
                 boolean(),
-                #{default => true}
+                #{
+                    default => true,
+                    desc => "Close the connection if send timeout."
+                }
             )},
         {"recbuf",
             sc(
                 bytesize(),
-                #{}
+                #{desc => "The TCP receive buffer (OS kernel) for the connections."}
             )},
         {"sndbuf",
             sc(
                 bytesize(),
-                #{}
+                #{desc => "The TCP send buffer (OS kernel) for the connections."}
             )},
         {"buffer",
             sc(
                 bytesize(),
-                #{}
+                #{desc => "The size of the user-space buffer used by the driver."}
             )},
         {"high_watermark",
             sc(
                 bytesize(),
-                #{default => "1MB"}
+                #{
+                    default => "1MB",
+                    desc =>
+                        "The socket is set to a busy state when the amount of data queued internally\n"
+                        "  by the VM socket implementation reaches this limit."
+                }
             )},
         {"nodelay",
             sc(
                 boolean(),
-                #{default => false}
+                #{
+                    default => false,
+                    desc => "The TCP_NODELAY flag for the connections."
+                }
             )},
         {"reuseaddr",
             sc(
                 boolean(),
-                #{default => true}
+                #{
+                    default => true,
+                    desc => "The SO_REUSEADDR flag for the connections."
+                }
             )}
     ];
 fields("listener_ssl_opts") ->
@@ -1048,37 +1127,56 @@ fields("deflate_opts") ->
         {"level",
             sc(
                 hoconsc:enum([none, default, best_compression, best_speed]),
-                #{}
+                #{desc => "Compression level."}
             )},
         {"mem_level",
             sc(
                 range(1, 9),
-                #{default => 8}
+                #{
+                    default => 8,
+                    desc =>
+                        "Specifies the size of the compression state.<br/>\n"
+                        " Lower values decrease memory usage per connection."
+                }
             )},
         {"strategy",
             sc(
                 hoconsc:enum([default, filtered, huffman_only, rle]),
-                #{}
+                #{desc => "Specifies the compression strategy."}
             )},
         {"server_context_takeover",
             sc(
                 hoconsc:enum([takeover, no_takeover]),
-                #{}
+                #{
+                    desc =>
+                        "Takeover means the compression state is retained\n"
+                        " between server messages."
+                }
             )},
         {"client_context_takeover",
             sc(
                 hoconsc:enum([takeover, no_takeover]),
-                #{}
+                #{
+                    desc =>
+                        "Takeover means the compression state is retained\n"
+                        " between client messages."
+                }
             )},
         {"server_max_window_bits",
             sc(
                 range(8, 15),
-                #{default => 15}
+                #{
+                    default => 15,
+                    desc => "Specifies the size of the compression context for the server."
+                }
             )},
         {"client_max_window_bits",
             sc(
                 range(8, 15),
-                #{default => 15}
+                #{
+                    default => 15,
+                    desc => "Specifies the size of the compression context for the client."
+                }
             )}
     ];
 fields("broker") ->
@@ -1086,27 +1184,57 @@ fields("broker") ->
         {"enable_session_registry",
             sc(
                 boolean(),
-                #{default => true}
+                #{
+                    default => true,
+                    desc => "Enable session registry"
+                }
             )},
         {"session_locking_strategy",
             sc(
                 hoconsc:enum([local, leader, quorum, all]),
-                #{default => quorum}
+                #{
+                    default => quorum,
+                    desc =>
+                        "Session locking strategy in a cluster.<br/>\n"
+                        " - `local`: only lock the session on the current node\n"
+                        " - `one`: select only one remote node to lock the session\n"
+                        " - `quorum`: select some nodes to lock the session\n"
+                        " - `all`: lock the session on all the nodes in the cluster"
+                }
             )},
         {"shared_subscription_strategy",
             sc(
                 hoconsc:enum([random, round_robin, sticky, hash_topic, hash_clientid]),
-                #{default => round_robin}
+                #{
+                    default => round_robin,
+                    desc =>
+                        "Dispatch strategy for shared subscription.<br/>\n"
+                        " - `random`: dispatch the message to a random selected subscriber\n"
+                        " - `round_robin`: select the subscribers in a round-robin manner\n"
+                        " - `sticky`: always use the last selected subscriber to dispatch,\n"
+                        "   until the subscriber disconnects.\n"
+                        " - `hash`: select the subscribers by the hash of `clientIds`"
+                }
             )},
         {"shared_dispatch_ack_enabled",
             sc(
                 boolean(),
-                #{default => false}
+                #{
+                    default => false,
+                    desc =>
+                        "Enable/disable shared dispatch acknowledgement for QoS1 and QoS2 messages.<br/>\n"
+                        " This should allow messages to be dispatched to a different subscriber in\n"
+                        " the group in case the picked (based on `shared_subscription_strategy`) subscriber\n"
+                        " is offline."
+                }
             )},
         {"route_batch_clean",
             sc(
                 boolean(),
-                #{default => true}
+                #{
+                    default => true,
+                    desc => "Enable batch clean for deleted routes."
+                }
             )},
         {"perf",
             sc(
@@ -1215,42 +1343,74 @@ fields("sysmon_vm") ->
         {"process_check_interval",
             sc(
                 duration(),
-                #{default => "30s"}
+                #{
+                    default => "30s",
+                    desc => "The time interval for the periodic process limit check."
+                }
             )},
         {"process_high_watermark",
             sc(
                 percent(),
-                #{default => "80%"}
+                #{
+                    default => "80%",
+                    desc =>
+                        "The threshold, as percentage of processes, for how many\n"
+                        " processes can simultaneously exist at the local node before the corresponding\n"
+                        " alarm is set."
+                }
             )},
         {"process_low_watermark",
             sc(
                 percent(),
-                #{default => "60%"}
+                #{
+                    default => "60%",
+                    desc =>
+                        "The threshold, as percentage of processes, for how many\n"
+                        " processes can simultaneously exist at the local node before the corresponding\n"
+                        " alarm is cleared."
+                }
             )},
         {"long_gc",
             sc(
                 hoconsc:union([disabled, duration()]),
-                #{}
+                #{
+                    desc =>
+                        "Enable Long GC monitoring.<br/>\n"
+                        " Notice: don't enable the monitor in production for:<br/>\n"
+                        " https://github.com/erlang/otp/blob/feb45017da36be78d4c5784d758ede619fa7bfd3/erts/emulator/beam/erl_gc.c#L421"
+                }
             )},
         {"long_schedule",
             sc(
                 hoconsc:union([disabled, duration()]),
-                #{default => "240ms"}
+                #{
+                    default => "240ms",
+                    desc => "Enable Long Schedule monitoring."
+                }
             )},
         {"large_heap",
             sc(
                 hoconsc:union([disabled, bytesize()]),
-                #{default => "32MB"}
+                #{
+                    default => "32MB",
+                    desc => "Enable Large Heap monitoring."
+                }
             )},
         {"busy_dist_port",
             sc(
                 boolean(),
-                #{default => true}
+                #{
+                    default => true,
+                    desc => "Enable Busy Distribution Port monitoring."
+                }
             )},
         {"busy_port",
             sc(
                 boolean(),
-                #{default => true}
+                #{
+                    default => true,
+                    desc => "Enable Busy Port monitoring."
+                }
             )}
     ];
 fields("sysmon_os") ->
@@ -1258,32 +1418,59 @@ fields("sysmon_os") ->
         {"cpu_check_interval",
             sc(
                 duration(),
-                #{default => "60s"}
+                #{
+                    default => "60s",
+                    desc => "The time interval for the periodic CPU check."
+                }
             )},
         {"cpu_high_watermark",
             sc(
                 percent(),
-                #{default => "80%"}
+                #{
+                    default => "80%",
+                    desc =>
+                        "The threshold, as percentage of system CPU load,\n"
+                        " for how much system cpu can be used before the corresponding alarm is set."
+                }
             )},
         {"cpu_low_watermark",
             sc(
                 percent(),
-                #{default => "60%"}
+                #{
+                    default => "60%",
+                    desc =>
+                        "The threshold, as percentage of system CPU load,\n"
+                        " for how much system cpu can be used before the corresponding alarm is cleared."
+                }
             )},
         {"mem_check_interval",
             sc(
                 hoconsc:union([disabled, duration()]),
-                #{default => "60s"}
+                #{
+                    default => "60s",
+                    desc => "The time interval for the periodic memory check."
+                }
             )},
         {"sysmem_high_watermark",
             sc(
                 percent(),
-                #{default => "70%"}
+                #{
+                    default => "70%",
+                    desc =>
+                        "The threshold, as percentage of system memory,\n"
+                        " for how much system memory can be allocated before the corresponding alarm is set."
+                }
             )},
         {"procmem_high_watermark",
             sc(
                 percent(),
-                #{default => "5%"}
+                #{
+                    default => "5%",
+                    desc =>
+                        "The threshold, as percentage of system memory,\n"
+                        " for how much system memory can be allocated by one Erlang process before\n"
+                        " the corresponding alarm is set."
+                }
             )}
     ];
 fields("sysmon_top") ->
@@ -1451,27 +1638,57 @@ base_listener() ->
         {"bind",
             sc(
                 hoconsc:union([ip_port(), integer()]),
-                #{required => true}
+                #{
+                    required => true,
+                    desc => "IP address and port for the listening socket."
+                }
             )},
         {"acceptors",
             sc(
                 integer(),
-                #{default => 16}
+                #{
+                    default => 16,
+                    desc => "The size of the listener's receiving pool."
+                }
             )},
         {"max_connections",
             sc(
                 hoconsc:union([infinity, integer()]),
-                #{default => infinity}
+                #{
+                    default => infinity,
+                    desc => "The maximum number of concurrent connections allowed by the listener."
+                }
             )},
         {"mountpoint",
             sc(
                 binary(),
-                #{default => <<>>}
+                #{
+                    default => <<>>,
+                    desc =>
+                        "When publishing or subscribing, prefix all topics with a mountpoint string.\n"
+                        " The prefixed string will be removed from the topic name when the message\n"
+                        " is delivered to the subscriber. The mountpoint is a way that users can use\n"
+                        " to implement isolation of message routing between different listeners.\n"
+                        " For example if a client A subscribes to `t` with `listeners.tcp.<name>.mountpoint`\n"
+                        " set to `some_tenant`, then the client actually subscribes to the topic\n"
+                        " `some_tenant/t`. Similarly, if another client B (connected to the same listener\n"
+                        " as the client A) sends a message to topic `t`, the message is routed\n"
+                        " to all the clients subscribed `some_tenant/t`, so client A will receive the\n"
+                        " message, with topic name `t`.<br/>\n"
+                        " Set to `\"\"` to disable the feature.<br/>\n"
+                        "\n"
+                        " Variables in mountpoint string:\n"
+                        " - <code>${clientid}</code>: clientid\n"
+                        " - <code>${username}</code>: username"
+                }
             )},
         {"zone",
             sc(
                 atom(),
-                #{default => 'default'}
+                #{
+                    default => 'default',
+                    desc => "The configuration zone to which the listener belongs."
+                }
             )},
         {"limiter",
             sc(map("ratelimit's type", emqx_limiter_schema:bucket_name()), #{default => #{}})}

apps/emqx_conf/src/emqx_conf_schema.erl

@@ -626,7 +626,9 @@ fields("log") ->
     , {"error_logger",
        sc(atom(),
           #{mapping => "kernel.error_logger",
-            default => silent})}
+            default => silent,
+            desc => "Deprecated."
+           })}
     ];
 
 fields("console_handler") ->

apps/emqx_dashboard/src/emqx_dashboard_schema.erl

@@ -49,22 +49,39 @@ fields("http") ->
         hoconsc:enum([http, https]),
         #{ desc => "HTTP/HTTPS protocol."
          , required => true
-         , default => http})}
+         , default => http
+         })}
     , {"bind", fun bind/1}
     , {"num_acceptors", sc(
         integer(),
         #{ default => 4
-         , desc => "Socket acceptor pool for TCP protocols."
+         , desc => "Socket acceptor pool size for TCP protocols."
          })}
-    , {"max_connections", sc(integer(), #{default => 512})}
+    , {"max_connections",
-    , {"backlog", sc(
+       sc(integer(),
-        integer(),
+          #{ default => 512
-        #{ default => 1024
+           , desc => "Maximum number of simultaneous connections."
-         , desc => "Defines the maximum length that the queue of pending connections can grow to."
+           })}
-        })}
+    , {"backlog",
-    , {"send_timeout", sc(emqx_schema:duration(), #{default => "5s"})}
+       sc(integer(),
-    , {"inet6", sc(boolean(), #{default => false})}
+          #{ default => 1024
-    , {"ipv6_v6only", sc(boolean(), #{default => false})}
+           , desc => "Defines the maximum length that the queue of pending connections can grow to."
+           })}
+    , {"send_timeout",
+       sc(emqx_schema:duration(),
+          #{ default => "5s"
+           , desc => "Send timeout for the socket."
+           })}
+    , {"inet6",
+       sc(boolean(),
+          #{ default => false
+           , desc => "Sets up the listener for IPv6."
+           })}
+    , {"ipv6_v6only",
+       sc(boolean(),
+          #{ default => false
+           , desc => "Disable IPv4-to-IPv6 mapping for the listener."
+           })}
     ];
 
 fields("https") ->
@@ -81,6 +98,7 @@ bind(_) -> undefined.
 default_username(type) -> string();
 default_username(default) -> "admin";
 default_username(required) -> true;
+default_username(desc) -> "The default username of the automatically created dashboard user.";
 default_username(_) -> undefined.
 
 default_password(type) -> string();

apps/emqx_modules/src/emqx_modules_schema.erl

@@ -126,12 +126,10 @@ fields("event_message") ->
     #{
         fields => Fields,
         desc =>
-            ""
-            "\n"
             "Enable/Disable system event messages.\n"
-            "The messages are published to '$event' prefixed topics.\n"
+            "The messages are published to <code>$event</code> prefixed topics.\n"
             "For example, if `client_disconnected` is set to `true`,\n"
-            "a message is published to `$event/client_connected` topic\n"
+            "a message is published to <code>$event/client_connected</code> topic\n"
             "whenever a client is connected.\n"
             ""
     };