REST and CLI API for domains

big_tests/tests/service_domain_db_SUITE.erl

@@ -5,6 +5,7 @@
 
 -compile(export_all).
 -import(distributed_helper, [mim/0, mim2/0, require_rpc_nodes/1, rpc/4]).
+-import(ejabberdctl_helper, [ejabberdctl/3]).
 
 suite() ->
     require_rpc_nodes([mim, mim2]).
@@ -52,7 +53,27 @@ db_cases() -> [
      db_inserted_from_one_node_while_service_disabled_on_another,
      db_reinserted_from_one_node_while_service_disabled_on_another,
      db_out_of_sync_crashes_node,
-     db_initial_load_crashes_node
+     db_initial_load_crashes_node,
+     cli_can_insert_domain,
+     cli_can_disable_domain,
+     cli_can_enable_domain,
+     cli_can_delete_domain,
+     cli_cannot_delete_domain_without_correct_type,
+     cli_cannot_insert_domain_twice_with_the_another_host_type,
+     cli_cannot_insert_domain_with_unknown_host_type,
+     cli_cannot_enable_missing_domain,
+     cli_cannot_disable_missing_domain,
+     rest_can_insert_domain,
+     rest_can_disable_domain,
+     rest_can_delete_domain,
+     rest_cannot_delete_domain_without_correct_type,
+     rest_delete_missing_domain,
+     rest_cannot_insert_domain_twice_with_the_another_host_type,
+     rest_cannot_insert_domain_with_unknown_host_type,
+     rest_cannot_enable_missing_domain,
+     rest_cannot_disable_missing_domain,
+     rest_can_enable_domain,
+     rest_can_select_domain
     ].
 
 -define(APPS, [inets, crypto, ssl, ranch, cowlib, cowboy]).
@@ -71,7 +92,8 @@ init_per_suite(Config) ->
     prepare_erase(mim()),
     prepare_erase(mim2()),
     erase_database(mim()),
-    escalus:init_per_suite([{mim_conf1, Conf1}, {mim_conf2, Conf2}|Config]).
+    Config1 = ejabberd_node_utils:init(mim(), Config),
+    escalus:init_per_suite([{mim_conf1, Conf1}, {mim_conf2, Conf2}|Config1]).
 
 store_conf(Node) ->
     Loaded = rpc(Node, mongoose_service, is_loaded, [service_domain_db]),
@@ -412,6 +434,116 @@ db_out_of_sync_crashes_node(_) ->
     true = rpc(mim(), meck, num_calls, [mongoose_domain_utils, halt_node, 1]) > 0,
     ok.
 
+cli_can_insert_domain(Config) ->
+    {"Added\n", 0} =
+        ejabberdctl("insert_domain", [<<"example.db">>, <<"type1">>], Config),
+    {ok, #{host_type := <<"type1">>, enabled := true}} =
+        select_domain(mim(), <<"example.db">>).
+
+cli_can_disable_domain(Config) ->
+    ejabberdctl("insert_domain", [<<"example.db">>, <<"type1">>], Config),
+    ejabberdctl("disable_domain", [<<"example.db">>], Config),
+    {ok, #{host_type := <<"type1">>, enabled := false}} =
+        select_domain(mim(), <<"example.db">>).
+
+cli_can_enable_domain(Config) ->
+    ejabberdctl("insert_domain", [<<"example.db">>, <<"type1">>], Config),
+    ejabberdctl("disable_domain", [<<"example.db">>], Config),
+    ejabberdctl("enable_domain", [<<"example.db">>], Config),
+    {ok, #{host_type := <<"type1">>, enabled := true}} =
+        select_domain(mim(), <<"example.db">>).
+
+cli_can_delete_domain(Config) ->
+    ejabberdctl("insert_domain", [<<"example.db">>, <<"type1">>], Config),
+    ejabberdctl("delete_domain", [<<"example.db">>, <<"type1">>], Config),
+    {error, not_found} = select_domain(mim(), <<"example.db">>).
+
+cli_cannot_delete_domain_without_correct_type(Config) ->
+    {"Added\n", 0} =
+        ejabberdctl("insert_domain", [<<"example.db">>, <<"type1">>], Config),
+    {"Error: \"wrong host type\"\n", 1} =
+        ejabberdctl("delete_domain", [<<"example.db">>, <<"type2">>], Config),
+    {ok, _} = select_domain(mim(), <<"example.db">>).
+
+cli_cannot_insert_domain_twice_with_the_another_host_type(Config) ->
+    {"Added\n", 0} =
+        ejabberdctl("insert_domain", [<<"example.db">>, <<"type1">>], Config),
+    {"Error: \"domain already exists\"\n", 1} =
+        ejabberdctl("insert_domain", [<<"example.db">>, <<"type2">>], Config).
+
+cli_cannot_insert_domain_with_unknown_host_type(Config) ->
+    {"Error: \"unknown host type\"\n", 1} =
+        ejabberdctl("insert_domain", [<<"example.db">>, <<"type6">>], Config).
+
+cli_cannot_enable_missing_domain(Config) ->
+    {"Error: \"domain not found\"\n", 1} =
+        ejabberdctl("enable_domain", [<<"example.db">>], Config).
+
+cli_cannot_disable_missing_domain(Config) ->
+    {"Error: \"domain not found\"\n", 1} =
+        ejabberdctl("disable_domain", [<<"example.db">>], Config).
+
+rest_can_insert_domain(Config) ->
+    {{<<"204">>, _}, _} =
+        rest_put_domain(<<"example.db">>, <<"type1">>),
+    {ok, #{host_type := <<"type1">>, enabled := true}} =
+        select_domain(mim(), <<"example.db">>).
+
+rest_can_disable_domain(Config) ->
+    rest_put_domain(<<"example.db">>, <<"type1">>),
+    rest_patch_enabled(<<"example.db">>, false),
+    {ok, #{host_type := <<"type1">>, enabled := false}} =
+        select_domain(mim(), <<"example.db">>).
+
+rest_can_delete_domain(Config) ->
+    rest_put_domain(<<"example.db">>, <<"type1">>),
+    {{<<"204">>, _}, _} =
+        rest_delete_domain(<<"example.db">>, <<"type1">>),
+    {error, not_found} = select_domain(mim(), <<"example.db">>).
+
+rest_cannot_delete_domain_without_correct_type(Config) ->
+    rest_put_domain(<<"example.db">>, <<"type1">>),
+    {{<<"403">>, <<"Forbidden">>},
+     {[{<<"what">>, <<"wrong host type">>}]}} =
+        rest_delete_domain(<<"example.db">>, <<"type2">>),
+    {ok, _} = select_domain(mim(), <<"example.db">>).
+
+rest_delete_missing_domain(Config) ->
+    {{<<"204">>, _}, _} =
+        rest_delete_domain(<<"example.db">>, <<"type1">>).
+
+rest_cannot_enable_missing_domain(Config) ->
+    {{<<"404">>, <<"Not Found">>},
+     {[{<<"what">>, <<"domain not found">>}]}} =
+        rest_patch_enabled(<<"example.db">>, true).
+
+rest_cannot_insert_domain_twice_with_the_another_host_type(Config) ->
+    rest_put_domain(<<"example.db">>, <<"type1">>),
+    {{<<"409">>, <<"Conflict">>}, {[{<<"what">>, <<"duplicate">>}]}} =
+        rest_put_domain(<<"example.db">>, <<"type2">>).
+
+rest_cannot_insert_domain_with_unknown_host_type(Config) ->
+    {{<<"403">>,<<"Forbidden">>}, {[{<<"what">>,<<"unknown host type">>}]}} =
+        rest_put_domain(<<"example.db">>, <<"type6">>).
+
+rest_cannot_disable_missing_domain(Config) ->
+    {{<<"404">>, <<"Not Found">>},
+     {[{<<"what">>, <<"domain not found">>}]}} =
+        rest_patch_enabled(<<"example.db">>, false).
+
+rest_can_enable_domain(Config) ->
+    rest_put_domain(<<"example.db">>, <<"type1">>),
+    rest_patch_enabled(<<"example.db">>, false),
+    rest_patch_enabled(<<"example.db">>, true),
+    {ok, #{host_type := <<"type1">>, enabled := true}} =
+        select_domain(mim(), <<"example.db">>).
+
+rest_can_select_domain(Config) ->
+    rest_put_domain(<<"example.db">>, <<"type1">>),
+    {{<<"200">>, <<"OK">>},
+     {[{<<"host_type">>, <<"type1">>}, {<<"enabled">>, true}]}} =
+        rest_select_domain(<<"example.db">>).
+
 %%--------------------------------------------------------------------
 %% Helpers
 %%--------------------------------------------------------------------
@@ -513,3 +645,22 @@ setup_meck(db_out_of_sync_crashes_node) ->
 
 teardown_meck() ->
     rpc(mim(), meck, unload, []).
+
+rest_patch_enabled(Domain, Enabled) ->
+    Params = #{enabled => Enabled},
+    rest_helper:make_request(#{ role => admin, method => <<"PATCH">>,
+                                path => <<"/domains/", Domain/binary>>,
+                                body => Params }).
+
+rest_put_domain(Domain, Type) ->
+    Params = #{host_type => Type},
+    rest_helper:putt(admin, <<"/domains/", Domain/binary>>, Params).
+
+rest_select_domain(Domain) ->
+    rest_helper:gett(admin, <<"/domains/", Domain/binary>>, #{}).
+
+rest_delete_domain(Domain, HostType) ->
+    Params = #{<<"host_type">> => HostType},
+    rest_helper:make_request(#{ role => admin, method => <<"DELETE">>,
+                                path => <<"/domains/", Domain/binary>>,
+                                body => Params }).

doc/developers-guide/domain_management.md

@@ -118,10 +118,120 @@ The number of seconds after an event must be deleted from the `domain_events` ta
 
 # REST API
 
-We must provide REST API for Add/Remove and Enable/Disable interfaces of the
-MongooseIM service described in the section above.
+Provides for adding/removing and enabling/disabling domains over HTTP.
 
-# Command Line Interfaces
+Implemented by `mongoose_domain_handler` module.
+
+Configuration example:
+
+```toml
+[[listen.http]]
+  ip_address = "127.0.0.1"
+  port = 8088
+  transport.num_acceptors = 10
+  transport.max_connections = 1024
+
+  [[listen.http.handlers.mongoose_domain_handler]]
+    host = "localhost"
+    path = "/api"
+```
+
+## Add domain
+
+```bash
+curl -v -X PUT "http://localhost:8088/api/domains/example.db" \
+    -H 'content-type: application/json' \
+    -d '{"host_type": "type1"}'
+```
+
+Result codes:
+
+* 204 - inserted.
+* 409 - domain already exists with a different host type.
+* 403 - DB service disabled.
+* 403 - unknown host type.
+* 500 - other errors.
+
+Example of the result body with a failure reason:
+
+```
+{"what":"unknown host type"}
+```
+
+Check the `src/domain/mongoose_domain_handler.erl` file for the exact values of the `what` field if needed.
+
+
+## Delete domain
+
+You must provide the domain's host type inside the body:
+
+```bash
+curl -v -X DELETE "http://localhost:8088/api/domains/example.db" \
+    -H 'content-type: application/json' \
+    -d '{"host_type": "type1"}'
+```
+
+Result codes:
+
+* 204 - the domain is removed or not found.
+* 403 - the domain is static.
+* 403 - the DB service is disabled.
+* 403 - the host type is wrong (does not match the host type in the database).
+* 403 - the host type is unknown.
+* 500 - other errors.
+
+
+## Enable/disable domain
+
+Provide `{"enabled": true}` as a body to enable a domain.
+Provide `{"enabled": false}` as a body to disable a domain.
+
+```bash
+curl -v -X PATCH "http://localhost:8088/api/domains/example.db" \
+    -H 'content-type: application/json' \
+    -d '{"enabled": true}'
+```
+
+Result codes:
+
+* 204 - updated.
+* 404 - domain not found;
+* 403 - domain is static;
+* 403 - service disabled.
+
+
+# Command Line Interface
+
+Implemented by `service_admin_extra_domain` module.
+
+Configuration example:
+
+```toml
+[services.service_admin_extra]
+  submods = ["node", "accounts", "sessions", "vcard", "gdpr", "upload",
+             "roster", "last", "private", "stanza", "stats", "domain"]
+```
 
-We must provide CLI for Add/Remove and Enable/Disable interfaces of MongooseIM
-service described in the section above.
+Add domain:
+
+```
+./mongooseimctl insert_domain domain host_type
+```
+
+Delete domain:
+
+```
+./mongooseimctl delete_domain domain host_type
+```
+
+Disable domain:
+
+```
+./mongooseimctl disable_domain domain
+```
+
+Enable domain:
+
+```
+./mongooseimctl enable_domain domain
+```

rel/files/mongooseim.toml

@@ -57,6 +57,9 @@
   [[listen.http.handlers.mongoose_api_admin]]
     host = "localhost"
     path = "/api"
+  [[listen.http.handlers.mongoose_domain_handler]]
+    host = "localhost"
+    path = "/api"
 
 [[listen.http]]
   {{#http_api_client_endpoint}}
@@ -199,7 +202,7 @@
 
 [services.service_admin_extra]
   submods = ["node", "accounts", "sessions", "vcard", "gdpr", "upload",
-             "roster", "last", "private", "stanza", "stats"]
+             "roster", "last", "private", "stanza", "stats", "domain"]
 
 [services.service_mongoose_system_metrics]
   initial_report = 300_000

src/admin_extra/service_admin_extra.erl

@@ -33,7 +33,7 @@
 -export([start/1, stop/0, config_spec/0]).
 
 -define(SUBMODS, [node, accounts, sessions, vcard, roster, last,
-                  private, stanza, stats, gdpr, upload
+                  private, stanza, stats, gdpr, upload, domain
                   %, srg %% Disabled until we add mod_shared_roster
                  ]).
 

src/domain/mongoose_domain_api.erl

@@ -46,8 +46,7 @@ delete_domain(Domain, HostType) ->
     end.
 
 -spec disable_domain(domain()) ->
-    ok | {error, not_found} | {error, static} | {error, duplicate}
-    | {error, service_disabled} | {error, unknown_host_type}.
+    ok | {error, not_found} | {error, static} | {error, service_disabled}.
 disable_domain(Domain) ->
     case mongoose_domain_core:is_static(Domain) of
         true ->
@@ -62,8 +61,7 @@ disable_domain(Domain) ->
     end.
 
 -spec enable_domain(domain()) ->
-    ok | {error, not_found} | {error, static} | {error, duplicate}
-    | {error, service_disabled} | {error, unknown_host_type}.
+    ok | {error, not_found} | {error, static} | {error, service_disabled}.
 enable_domain(Domain) ->
     case mongoose_domain_core:is_static(Domain) of
         true ->