From edb91e2e4a2146cb2237741b9830db7d0b9626c3 Mon Sep 17 00:00:00 2001
From: ieQu1 <99872536+ieQu1@users.noreply.github.com>
Date: Wed, 30 Mar 2022 11:53:15 +0200
Subject: [PATCH] docs(schema): Add descriptions for authZ and connector
---
apps/emqx/src/emqx_schema.erl | 15 +++++++++---
.../src/emqx_authn_password_hashing.erl | 3 +++
apps/emqx_authn/src/emqx_authn_schema.erl | 10 +++++---
.../src/simple_authn/emqx_authn_mongodb.erl | 18 +++++++++++++++
apps/emqx_authz/src/emqx_authz_schema.erl | 23 +++++++++++--------
.../src/emqx_connector_mongo.erl | 14 ++++++++---
.../src/emqx_connector_schema_lib.erl | 8 ++++++-
7 files changed, 71 insertions(+), 20 deletions(-)
diff --git a/apps/emqx/src/emqx_schema.erl b/apps/emqx/src/emqx_schema.erl
index 072603b1e..8a91f2c06 100644
--- a/apps/emqx/src/emqx_schema.erl
+++ b/apps/emqx/src/emqx_schema.erl
@@ -339,17 +339,26 @@ fields("cache") ->
{"enable",
sc(
boolean(),
- #{default => true}
+ #{
+ default => true,
+ desc => "Enable or disable the authorization cache."
+ }
)},
{"max_size",
sc(
range(1, 1048576),
- #{default => 32}
+ #{
+ default => 32,
+ desc => "Maximum number of cached items."
+ }
)},
{"ttl",
sc(
duration(),
- #{default => "1m"}
+ #{
+ default => "1m",
+ desc => "Time to live for the cached data."
+ }
)}
];
fields("mqtt") ->
diff --git a/apps/emqx_authn/src/emqx_authn_password_hashing.erl b/apps/emqx_authn/src/emqx_authn_password_hashing.erl
index 7c9b0f247..7a3573ca9 100644
--- a/apps/emqx_authn/src/emqx_authn_password_hashing.erl
+++ b/apps/emqx_authn/src/emqx_authn_password_hashing.erl
@@ -73,14 +73,17 @@ fields(other_algorithms) ->
{salt_position, fun salt_position/1}].
salt_position(type) -> {enum, [prefix, suffix]};
+salt_position(desc) -> "Specifies whether the password salt is stored as a prefix or the suffix.";
salt_position(default) -> prefix;
salt_position(_) -> undefined.
salt_rounds(type) -> integer();
+salt_rounds(desc) -> "Cost factor for the bcrypt hash.";
salt_rounds(default) -> 10;
salt_rounds(_) -> undefined.
dk_length(type) -> integer();
+dk_length(desc) -> "Length of the derived key.";
dk_length(required) -> false;
dk_length(_) -> undefined.
diff --git a/apps/emqx_authn/src/emqx_authn_schema.erl b/apps/emqx_authn/src/emqx_authn_schema.erl
index 5a87957ad..b8f8dacfd 100644
--- a/apps/emqx_authn/src/emqx_authn_schema.erl
+++ b/apps/emqx_authn/src/emqx_authn_schema.erl
@@ -55,11 +55,15 @@ root_type() ->
mechanism(Name) ->
hoconsc:mk(hoconsc:enum([Name]),
- #{required => true}).
+ #{ required => true
+ , desc => "Authentication mechanism."
+ }).
backend(Name) ->
hoconsc:mk(hoconsc:enum([Name]),
- #{required => true}).
+ #{ required => true
+ , desc => "Backend type."
+ }).
fields("metrics_status_fields") ->
[ {"metrics", mk(ref(?MODULE, "metrics"), #{desc => "The metrics of the resource"})}
@@ -89,7 +93,7 @@ fields("node_metrics") ->
fields("node_status") ->
[ node_name()
- , {"status", mk(status(), #{})}
+ , {"status", mk(status(), #{desc => "Status of the node."})}
].
status() ->
diff --git a/apps/emqx_authn/src/simple_authn/emqx_authn_mongodb.erl b/apps/emqx_authn/src/simple_authn/emqx_authn_mongodb.erl
index c4433bbac..43ed029da 100644
--- a/apps/emqx_authn/src/simple_authn/emqx_authn_mongodb.erl
+++ b/apps/emqx_authn/src/simple_authn/emqx_authn_mongodb.erl
@@ -26,6 +26,7 @@
-export([ namespace/0
, roots/0
, fields/1
+ , desc/1
]).
-export([ refs/0
@@ -55,6 +56,15 @@ fields('replica-set') ->
fields('sharded-cluster') ->
common_fields() ++ emqx_connector_mongo:fields(sharded).
+desc(standalone) ->
+ "Configuration for a standalone MongoDB instance.";
+desc('replica-set') ->
+ "Configuration for a replica set.";
+desc('sharded-cluster') ->
+ "Configuration for a sharded cluster.";
+desc(_) ->
+ undefined.
+
common_fields() ->
[ {mechanism, emqx_authn_schema:mechanism('password_based')}
, {backend, emqx_authn_schema:backend(mongodb)}
@@ -67,19 +77,27 @@ common_fields() ->
] ++ emqx_authn_schema:common_fields().
collection(type) -> binary();
+collection(desc) -> "Collection used to store authentication data.";
collection(_) -> undefined.
selector(type) -> map();
+selector(desc) -> "Statement that is executed during the authentication process. "
+ "Commands can support following wildcards:\n"
+ " - `${username}`: substituted with client's username\n"
+ " - `${clientid}`: substituted with the clientid";
selector(_) -> undefined.
password_hash_field(type) -> binary();
+password_hash_field(desc) -> "Document field that contains password hash.";
password_hash_field(_) -> undefined.
salt_field(type) -> binary();
+salt_field(desc) -> "Document field that contains the password salt.";
salt_field(required) -> false;
salt_field(_) -> undefined.
is_superuser_field(type) -> binary();
+is_superuser_field(desc) -> "Document field that defines if the user has superuser privileges.";
is_superuser_field(required) -> false;
is_superuser_field(_) -> undefined.
diff --git a/apps/emqx_authz/src/emqx_authz_schema.erl b/apps/emqx_authz/src/emqx_authz_schema.erl
index a1a475563..8a46e8484 100644
--- a/apps/emqx_authz/src/emqx_authz_schema.erl
+++ b/apps/emqx_authz/src/emqx_authz_schema.erl
@@ -66,7 +66,7 @@ fields("authorization") ->
]),
default => [],
desc =>
-"""
+"
Authorization data sources.
An array of authorization (ACL) data providers.
It is designed as an array, not a hash-map, so the sources can be
@@ -84,7 +84,7 @@ the default action configured in 'authorization.no_match' is applied.
NOTE:
The source elements are identified by their 'type'.
It is NOT allowed to configure two or more sources of the same type.
-"""
+"
}
}
];
@@ -94,7 +94,7 @@ fields(file) ->
default => true}}
, {path, #{type => string(),
required => true,
- desc => """
+ desc => "
Path to the file which contains the ACL rules.
If the file provisioned before starting EMQX node,
it can be placed anywhere as long as EMQX has read access to it.
@@ -102,7 +102,7 @@ it can be placed anywhere as long as EMQX has read access to it.
In case the rule-set is created from EMQX dashboard or management API,
the file will be placed in `authz` subdirectory inside EMQX's `data_dir`,
and the new rules will override all rules from the old config file.
-"""
+"
}}
];
fields(http_get) ->
@@ -152,11 +152,12 @@ http_common_fields() ->
maps:from_list(connector_fields(http)))).
mongo_common_fields() ->
- [ {collection, #{type => atom()}}
- , {selector, #{type => map()}}
- , {type, #{type => mongodb}}
+ [ {collection, #{type => atom(), desc => "`MongoDB` collection containing the authorization data."}}
+ , {selector, #{type => map(), desc => "MQL query used to select the authorization record."}}
+ , {type, #{type => mongodb, desc => "Database backend."}}
, {enable, #{type => boolean(),
- default => true}}
+ default => true,
+ desc => "Enable or disable the backend."}}
].
validations() ->
@@ -244,6 +245,7 @@ union_array(Item) when is_list(Item) ->
query() ->
#{type => binary(),
+ desc => "",
validator => fun(S) ->
case size(S) > 0 of
true -> ok;
@@ -264,9 +266,10 @@ connector_fields(DB, Fields) ->
error:Reason ->
erlang:error(Reason)
end,
- [ {type, #{type => DB}}
+ [ {type, #{type => DB, desc => "Database backend."}}
, {enable, #{type => boolean(),
- default => true}}
+ default => true,
+ desc => "Enable or disable the backend."}}
] ++ erlang:apply(Mod, fields, [Fields]).
to_list(A) when is_atom(A) ->
diff --git a/apps/emqx_connector/src/emqx_connector_mongo.erl b/apps/emqx_connector/src/emqx_connector_mongo.erl
index 2dea3bcf7..90945e5b8 100644
--- a/apps/emqx_connector/src/emqx_connector_mongo.erl
+++ b/apps/emqx_connector/src/emqx_connector_mongo.erl
@@ -54,13 +54,15 @@ roots() ->
fields(single) ->
[ {mongo_type, #{type => single,
- default => single}}
+ default => single,
+ desc => "Standalone instance."}}
, {server, fun server/1}
, {w_mode, fun w_mode/1}
] ++ mongo_fields();
fields(rs) ->
[ {mongo_type, #{type => rs,
- default => rs}}
+ default => rs,
+ desc => "Replica set."}}
, {servers, fun servers/1}
, {w_mode, fun w_mode/1}
, {r_mode, fun r_mode/1}
@@ -68,7 +70,8 @@ fields(rs) ->
] ++ mongo_fields();
fields(sharded) ->
[ {mongo_type, #{type => sharded,
- default => sharded}}
+ default => sharded,
+ desc => "Sharded cluster."}}
, {servers, fun servers/1}
, {w_mode, fun w_mode/1}
] ++ mongo_fields();
@@ -306,22 +309,27 @@ servers(desc) -> ?SERVERS_DESC ++ server(desc);
servers(_) -> undefined.
w_mode(type) -> hoconsc:enum([unsafe, safe]);
+w_mode(desc) -> "Write mode.";
w_mode(default) -> unsafe;
w_mode(_) -> undefined.
r_mode(type) -> hoconsc:enum([master, slave_ok]);
+r_mode(desc) -> "Read mode.";
r_mode(default) -> master;
r_mode(_) -> undefined.
duration(type) -> emqx_schema:duration_ms();
+duration(desc) -> "Time interval, such as timeout or TTL.";
duration(required) -> false;
duration(_) -> undefined.
replica_set_name(type) -> binary();
+replica_set_name(desc) -> "Name of the replica set.";
replica_set_name(required) -> false;
replica_set_name(_) -> undefined.
srv_record(type) -> boolean();
+srv_record(desc) -> "Use DNS SRV record.";
srv_record(default) -> false;
srv_record(_) -> undefined.
diff --git a/apps/emqx_connector/src/emqx_connector_schema_lib.erl b/apps/emqx_connector/src/emqx_connector_schema_lib.erl
index 32ddcd518..7ad058e64 100644
--- a/apps/emqx_connector/src/emqx_connector_schema_lib.erl
+++ b/apps/emqx_connector/src/emqx_connector_schema_lib.erl
@@ -52,7 +52,8 @@ fields(_) -> [].
ssl_fields() ->
[ {ssl, #{type => hoconsc:ref(emqx_schema, ssl_client_opts),
- default => #{<<"enable">> => false}
+ default => #{<<"enable">> => false},
+ desc => "SSL connection settings."
}
}
].
@@ -66,24 +67,29 @@ relational_db_fields() ->
].
database(type) -> binary();
+database(desc) -> "Database name.";
database(required) -> true;
database(validator) -> [?NOT_EMPTY("the value of the field 'database' cannot be empty")];
database(_) -> undefined.
pool_size(type) -> integer();
+pool_size(desc) -> "Size of the connection pool.";
pool_size(default) -> 8;
pool_size(validator) -> [?MIN(1)];
pool_size(_) -> undefined.
username(type) -> binary();
+username(desc) -> "EMQX's username in the external database.";
username(required) -> false;
username(_) -> undefined.
password(type) -> binary();
+password(desc) -> "EMQX's password in the external database.";
password(required) -> false;
password(_) -> undefined.
auto_reconnect(type) -> boolean();
+auto_reconnect(desc) -> "Enable automatic reconnect to the database.";
auto_reconnect(default) -> true;
auto_reconnect(_) -> undefined.