docs(schema): Add descriptions for authZ and connector

This commit is contained in:
ieQu1 2022-03-30 11:53:15 +02:00
parent 80cd1350a5
commit edb91e2e4a
7 changed files with 71 additions and 20 deletions

View File

@ -339,17 +339,26 @@ fields("cache") ->
{"enable", {"enable",
sc( sc(
boolean(), boolean(),
#{default => true} #{
default => true,
desc => "Enable or disable the authorization cache."
}
)}, )},
{"max_size", {"max_size",
sc( sc(
range(1, 1048576), range(1, 1048576),
#{default => 32} #{
default => 32,
desc => "Maximum number of cached items."
}
)}, )},
{"ttl", {"ttl",
sc( sc(
duration(), duration(),
#{default => "1m"} #{
default => "1m",
desc => "Time to live for the cached data."
}
)} )}
]; ];
fields("mqtt") -> fields("mqtt") ->

View File

@ -73,14 +73,17 @@ fields(other_algorithms) ->
{salt_position, fun salt_position/1}]. {salt_position, fun salt_position/1}].
salt_position(type) -> {enum, [prefix, suffix]}; 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(default) -> prefix;
salt_position(_) -> undefined. salt_position(_) -> undefined.
salt_rounds(type) -> integer(); salt_rounds(type) -> integer();
salt_rounds(desc) -> "Cost factor for the bcrypt hash.";
salt_rounds(default) -> 10; salt_rounds(default) -> 10;
salt_rounds(_) -> undefined. salt_rounds(_) -> undefined.
dk_length(type) -> integer(); dk_length(type) -> integer();
dk_length(desc) -> "Length of the derived key.";
dk_length(required) -> false; dk_length(required) -> false;
dk_length(_) -> undefined. dk_length(_) -> undefined.

View File

@ -55,11 +55,15 @@ root_type() ->
mechanism(Name) -> mechanism(Name) ->
hoconsc:mk(hoconsc:enum([Name]), hoconsc:mk(hoconsc:enum([Name]),
#{required => true}). #{ required => true
, desc => "Authentication mechanism."
}).
backend(Name) -> backend(Name) ->
hoconsc:mk(hoconsc:enum([Name]), hoconsc:mk(hoconsc:enum([Name]),
#{required => true}). #{ required => true
, desc => "Backend type."
}).
fields("metrics_status_fields") -> fields("metrics_status_fields") ->
[ {"metrics", mk(ref(?MODULE, "metrics"), #{desc => "The metrics of the resource"})} [ {"metrics", mk(ref(?MODULE, "metrics"), #{desc => "The metrics of the resource"})}
@ -89,7 +93,7 @@ fields("node_metrics") ->
fields("node_status") -> fields("node_status") ->
[ node_name() [ node_name()
, {"status", mk(status(), #{})} , {"status", mk(status(), #{desc => "Status of the node."})}
]. ].
status() -> status() ->

View File

@ -26,6 +26,7 @@
-export([ namespace/0 -export([ namespace/0
, roots/0 , roots/0
, fields/1 , fields/1
, desc/1
]). ]).
-export([ refs/0 -export([ refs/0
@ -55,6 +56,15 @@ fields('replica-set') ->
fields('sharded-cluster') -> fields('sharded-cluster') ->
common_fields() ++ emqx_connector_mongo:fields(sharded). 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() -> common_fields() ->
[ {mechanism, emqx_authn_schema:mechanism('password_based')} [ {mechanism, emqx_authn_schema:mechanism('password_based')}
, {backend, emqx_authn_schema:backend(mongodb)} , {backend, emqx_authn_schema:backend(mongodb)}
@ -67,19 +77,27 @@ common_fields() ->
] ++ emqx_authn_schema:common_fields(). ] ++ emqx_authn_schema:common_fields().
collection(type) -> binary(); collection(type) -> binary();
collection(desc) -> "Collection used to store authentication data.";
collection(_) -> undefined. collection(_) -> undefined.
selector(type) -> map(); 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. selector(_) -> undefined.
password_hash_field(type) -> binary(); password_hash_field(type) -> binary();
password_hash_field(desc) -> "Document field that contains password hash.";
password_hash_field(_) -> undefined. password_hash_field(_) -> undefined.
salt_field(type) -> binary(); salt_field(type) -> binary();
salt_field(desc) -> "Document field that contains the password salt.";
salt_field(required) -> false; salt_field(required) -> false;
salt_field(_) -> undefined. salt_field(_) -> undefined.
is_superuser_field(type) -> binary(); 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(required) -> false;
is_superuser_field(_) -> undefined. is_superuser_field(_) -> undefined.

View File

@ -66,7 +66,7 @@ fields("authorization") ->
]), ]),
default => [], default => [],
desc => desc =>
""" "
Authorization data sources.<br> Authorization data sources.<br>
An array of authorization (ACL) data providers. An array of authorization (ACL) data providers.
It is designed as an array, not a hash-map, so the sources can be 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.<br>
NOTE: NOTE:
The source elements are identified by their 'type'. The source elements are identified by their 'type'.
It is NOT allowed to configure two or more sources of the same type. It is NOT allowed to configure two or more sources of the same type.
""" "
} }
} }
]; ];
@ -94,7 +94,7 @@ fields(file) ->
default => true}} default => true}}
, {path, #{type => string(), , {path, #{type => string(),
required => true, required => true,
desc => """ desc => "
Path to the file which contains the ACL rules.<br> Path to the file which contains the ACL rules.<br>
If the file provisioned before starting EMQX node, If the file provisioned before starting EMQX node,
it can be placed anywhere as long as EMQX has read access to it. 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, 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`, 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. and the new rules will override all rules from the old config file.
""" "
}} }}
]; ];
fields(http_get) -> fields(http_get) ->
@ -152,11 +152,12 @@ http_common_fields() ->
maps:from_list(connector_fields(http)))). maps:from_list(connector_fields(http)))).
mongo_common_fields() -> mongo_common_fields() ->
[ {collection, #{type => atom()}} [ {collection, #{type => atom(), desc => "`MongoDB` collection containing the authorization data."}}
, {selector, #{type => map()}} , {selector, #{type => map(), desc => "MQL query used to select the authorization record."}}
, {type, #{type => mongodb}} , {type, #{type => mongodb, desc => "Database backend."}}
, {enable, #{type => boolean(), , {enable, #{type => boolean(),
default => true}} default => true,
desc => "Enable or disable the backend."}}
]. ].
validations() -> validations() ->
@ -244,6 +245,7 @@ union_array(Item) when is_list(Item) ->
query() -> query() ->
#{type => binary(), #{type => binary(),
desc => "",
validator => fun(S) -> validator => fun(S) ->
case size(S) > 0 of case size(S) > 0 of
true -> ok; true -> ok;
@ -264,9 +266,10 @@ connector_fields(DB, Fields) ->
error:Reason -> error:Reason ->
erlang:error(Reason) erlang:error(Reason)
end, end,
[ {type, #{type => DB}} [ {type, #{type => DB, desc => "Database backend."}}
, {enable, #{type => boolean(), , {enable, #{type => boolean(),
default => true}} default => true,
desc => "Enable or disable the backend."}}
] ++ erlang:apply(Mod, fields, [Fields]). ] ++ erlang:apply(Mod, fields, [Fields]).
to_list(A) when is_atom(A) -> to_list(A) when is_atom(A) ->

View File

@ -54,13 +54,15 @@ roots() ->
fields(single) -> fields(single) ->
[ {mongo_type, #{type => single, [ {mongo_type, #{type => single,
default => single}} default => single,
desc => "Standalone instance."}}
, {server, fun server/1} , {server, fun server/1}
, {w_mode, fun w_mode/1} , {w_mode, fun w_mode/1}
] ++ mongo_fields(); ] ++ mongo_fields();
fields(rs) -> fields(rs) ->
[ {mongo_type, #{type => rs, [ {mongo_type, #{type => rs,
default => rs}} default => rs,
desc => "Replica set."}}
, {servers, fun servers/1} , {servers, fun servers/1}
, {w_mode, fun w_mode/1} , {w_mode, fun w_mode/1}
, {r_mode, fun r_mode/1} , {r_mode, fun r_mode/1}
@ -68,7 +70,8 @@ fields(rs) ->
] ++ mongo_fields(); ] ++ mongo_fields();
fields(sharded) -> fields(sharded) ->
[ {mongo_type, #{type => sharded, [ {mongo_type, #{type => sharded,
default => sharded}} default => sharded,
desc => "Sharded cluster."}}
, {servers, fun servers/1} , {servers, fun servers/1}
, {w_mode, fun w_mode/1} , {w_mode, fun w_mode/1}
] ++ mongo_fields(); ] ++ mongo_fields();
@ -306,22 +309,27 @@ servers(desc) -> ?SERVERS_DESC ++ server(desc);
servers(_) -> undefined. servers(_) -> undefined.
w_mode(type) -> hoconsc:enum([unsafe, safe]); w_mode(type) -> hoconsc:enum([unsafe, safe]);
w_mode(desc) -> "Write mode.";
w_mode(default) -> unsafe; w_mode(default) -> unsafe;
w_mode(_) -> undefined. w_mode(_) -> undefined.
r_mode(type) -> hoconsc:enum([master, slave_ok]); r_mode(type) -> hoconsc:enum([master, slave_ok]);
r_mode(desc) -> "Read mode.";
r_mode(default) -> master; r_mode(default) -> master;
r_mode(_) -> undefined. r_mode(_) -> undefined.
duration(type) -> emqx_schema:duration_ms(); duration(type) -> emqx_schema:duration_ms();
duration(desc) -> "Time interval, such as timeout or TTL.";
duration(required) -> false; duration(required) -> false;
duration(_) -> undefined. duration(_) -> undefined.
replica_set_name(type) -> binary(); replica_set_name(type) -> binary();
replica_set_name(desc) -> "Name of the replica set.";
replica_set_name(required) -> false; replica_set_name(required) -> false;
replica_set_name(_) -> undefined. replica_set_name(_) -> undefined.
srv_record(type) -> boolean(); srv_record(type) -> boolean();
srv_record(desc) -> "Use DNS SRV record.";
srv_record(default) -> false; srv_record(default) -> false;
srv_record(_) -> undefined. srv_record(_) -> undefined.

View File

@ -52,7 +52,8 @@ fields(_) -> [].
ssl_fields() -> ssl_fields() ->
[ {ssl, #{type => hoconsc:ref(emqx_schema, ssl_client_opts), [ {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(type) -> binary();
database(desc) -> "Database name.";
database(required) -> true; database(required) -> true;
database(validator) -> [?NOT_EMPTY("the value of the field 'database' cannot be empty")]; database(validator) -> [?NOT_EMPTY("the value of the field 'database' cannot be empty")];
database(_) -> undefined. database(_) -> undefined.
pool_size(type) -> integer(); pool_size(type) -> integer();
pool_size(desc) -> "Size of the connection pool.";
pool_size(default) -> 8; pool_size(default) -> 8;
pool_size(validator) -> [?MIN(1)]; pool_size(validator) -> [?MIN(1)];
pool_size(_) -> undefined. pool_size(_) -> undefined.
username(type) -> binary(); username(type) -> binary();
username(desc) -> "EMQX's username in the external database.";
username(required) -> false; username(required) -> false;
username(_) -> undefined. username(_) -> undefined.
password(type) -> binary(); password(type) -> binary();
password(desc) -> "EMQX's password in the external database.";
password(required) -> false; password(required) -> false;
password(_) -> undefined. password(_) -> undefined.
auto_reconnect(type) -> boolean(); auto_reconnect(type) -> boolean();
auto_reconnect(desc) -> "Enable automatic reconnect to the database.";
auto_reconnect(default) -> true; auto_reconnect(default) -> true;
auto_reconnect(_) -> undefined. auto_reconnect(_) -> undefined.