Document dynamic domains #3242

gustawlippa · 2021-09-03T08:26:38Z

This PR documents the changes made for multi-tenancy.

The REST API page is updated with a Swagger example, however I am not so familiar with Swagger so it's rather rudimentary. It was not automatically generated as I wasn't sure how to do it (it seemed to require Trails which the domains handler didn't use).
mod_domain_isolation is documented.
Domain management file in the developers guide is updated as it has some information (like the CLI) that is useful. Some of the parts have been moved to more relevant sections of the documentation.
Outside the scope of this PR: Hooks documentation has to be updated not only to reflect multi-tenancy but also their recent updates (Hooks-and-handlers.md, hooks_description.md) - a ticket was created.
General changes everywhere in the documentation.
Some modules don't support dynamic domains, and their documentation is left as is.

Found with the help of the editor at: https://editor.swagger.io/

codecov · 2021-09-03T08:38:03Z

Codecov Report

Merging #3242 (b7baf52) into master (6cf4127) will increase coverage by 1.74%.
The diff coverage is n/a.

❗ Current head b7baf52 differs from pull request most recent head 098494b. Consider uploading reports for the commit 098494b to get more accurate results

@@            Coverage Diff             @@
##           master    #3242      +/-   ##
==========================================
+ Coverage   78.59%   80.34%   +1.74%     
==========================================
  Files         398      398              
  Lines       32534    32534              
==========================================
+ Hits        25571    26140     +569     
+ Misses       6963     6394     -569

Impacted Files	Coverage Δ
src/config/mongoose_config_spec.erl	`98.52% <ø> (ø)`
src/elasticsearch/mongoose_elasticsearch.erl	`76.92% <0.00%> (-7.70%)`	⬇️
...bal_distrib/mod_global_distrib_hosts_refresher.erl	`73.58% <0.00%> (-1.89%)`	⬇️
src/mam/mod_mam_elasticsearch_arch.erl	`85.08% <0.00%> (-1.76%)`	⬇️
src/ejabberd_s2s_out.erl	`61.95% <0.00%> (-0.46%)`	⬇️
src/mod_muc.erl	`74.88% <0.00%> (-0.23%)`	⬇️
src/mod_muc_log.erl	`77.88% <0.00%> (ø)`
src/ejabberd_c2s.erl	`89.28% <0.00%> (+0.07%)`	⬆️
src/pubsub/mod_pubsub_db_rdbms.erl	`95.34% <0.00%> (+0.25%)`	⬆️
src/ejabberd_sm.erl	`84.59% <0.00%> (+0.32%)`	⬆️
... and 23 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6cf4127...098494b. Read the comment docs.

Warning: Contains some suspicious JS usage.

mongoose-im · 2021-09-03T13:57:52Z

small_tests_24 / small_tests / b8ae568
Reports root / small

internal_mnesia_24 / internal_mnesia / b8ae568
Reports root/ big
OK: 1653 / Failed: 1 / User-skipped: 290 / Auto-skipped: 0

amp_big_SUITE:basic:notify_deliver_to_online_user_recipient_privacy_test

{error,
  {test_case_failed,
    {has_stanzas_but_shouldnt,
      {client,
        <<"alicE_notify_deliver_to_online_user_recipient_privacy_test_4.847396@localhost/res1">>,
        escalus_tcp,<0.2946.0>,
        [{event_manager,<0.2585.0>},
         {server,<<"localhost">>},
         {username,
           <<"alicE_notify_deliver_to_online_user_recipient_privacy_test_4.847396">>},
         {resource,<<"res1">>}],
        [{event_client,
           [{event_manager,<0.2585.0>},
            {server,<<"localhost">>},
            {username,
              <<"alicE_notify_deliver_to_online_user_recipient_privacy_test_4.847396">>},
            {resource,<<"res1">>}]},
         {resource,<<"res1">>},
         {username,
           <<"alicE_notify_deliver_to_online_user_recipient_privacy_test_4.847396">>},
         {server,<<"localhost">>},
         {host,<<"localhost">>},
         {port,5222},
         {auth,{escalus_auth,auth_plain}},
         {wspath,undefined},
         {username,
           <<"alicE_notify_deliver_to_online_user_recipient_privacy_test_4.847396">>},
         {server,<<"localhost">>},
         {password,<<"matygrysa">>},
         {stream_id,<<"158f3e14bdb629d9">>}]},
      [{xmlel,<<"stream:error">>,[],
         [{xmlel,<<"conflict">>,
            [{<<"xmlns">>,
            <<"urn:ietf:params:xml:ns:xmpp-streams">>}],
            []},
          {xmlel,<<"text">>,
            [{<<"xml:lang">>,<<"en">>},
             {<<"xmlns">>,
            <<"urn:ietf:params:xml:ns...

Report log

small_tests_22 / small_tests / b8ae568
Reports root / small

dynamic_domains_24 / pgsql_mnesia / b8ae568
Reports root/ big
OK: 1690 / Failed: 0 / User-skipped: 114 / Auto-skipped: 0

dynamic_domains_23 / pgsql_mnesia / b8ae568
Reports root/ big
OK: 1690 / Failed: 0 / User-skipped: 114 / Auto-skipped: 0

small_tests_23 / small_tests / b8ae568
Reports root / small

ldap_mnesia_24 / ldap_mnesia / b8ae568
Reports root/ big
OK: 1518 / Failed: 1 / User-skipped: 363 / Auto-skipped: 0

mod_event_pusher_rabbit_SUITE:group_chat_message_publish:group_chat_message_received_event_properly_formatted

{error,
  {{assertMatch,
     [{module,mod_event_pusher_rabbit_SUITE},
      {line,435},
      {expression,
        "get_decoded_message_from_rabbit ( AliceGroupChatMsgRecvRK )"},
      {pattern,
        "# { << \"from_user_id\" >> := BobRoomJID , << \"to_user_id\" >> := AliceFullJID , << \"message\" >> := Message }"},
      {value,
        #{<<"from_user_id">> => <<"muc_publish@muc.localhost">>,
        <<"message">> => <<>>,
        <<"to_user_id">> =>
          <<"alice_unnamed_69.299571@localhost/res1">>}}]},
   [{mod_event_pusher_rabbit_SUITE,
      '-group_chat_message_received_event_properly_formatted/1-fun-1-',3,
      [{file,
         "/home/circleci/app/big_tests/tests/mod_event_pusher_rabbit_SUITE.erl"},
       {line,435}]},
    {escalus_story,story,4,
      [{file,
         "/home/circleci/app/big_tests/_build/default/lib/escalus/src/escalus_story.erl"},
       {line,72}]},
    {test_server,ts_tc,3,[{file,"test_server.erl"},{line,1783}]},
    {test_server,run_test_case_eval1,6,
      [{file,"test_server.erl"},{line,1292}]},
    {test_server,run_test_case_eval,9,
      [{file,"test_server.erl"},{line,1224}]}]}}

Report log

ldap_mnesia_22 / ldap_mnesia / b8ae568
Reports root/ big
OK: 1515 / Failed: 0 / User-skipped: 363 / Auto-skipped: 0

pgsql_mnesia_22 / pgsql_mnesia / b8ae568
Reports root/ big
OK: 3090 / Failed: 0 / User-skipped: 184 / Auto-skipped: 0

ldap_mnesia_23 / ldap_mnesia / b8ae568
Reports root/ big
OK: 1515 / Failed: 0 / User-skipped: 363 / Auto-skipped: 0

pgsql_mnesia_24 / pgsql_mnesia / b8ae568
Reports root/ big
OK: 3090 / Failed: 0 / User-skipped: 184 / Auto-skipped: 0

mssql_mnesia_24 / odbc_mssql_mnesia / b8ae568
Reports root/ big
OK: 3090 / Failed: 0 / User-skipped: 184 / Auto-skipped: 0

mysql_redis_24 / mysql_redis / b8ae568
Reports root/ big
OK: 3073 / Failed: 0 / User-skipped: 201 / Auto-skipped: 0

elasticsearch_and_cassandra_24 / elasticsearch_and_cassandra_mnesia / b8ae568
Reports root/ big
OK: 1891 / Failed: 0 / User-skipped: 286 / Auto-skipped: 0

pgsql_mnesia_23 / pgsql_mnesia / b8ae568
Reports root/ big
OK: 3090 / Failed: 0 / User-skipped: 184 / Auto-skipped: 0

riak_mnesia_24 / riak_mnesia / b8ae568
Reports root/ big
OK: 1738 / Failed: 0 / User-skipped: 289 / Auto-skipped: 0

doc/advanced-configuration/Modules.md

mongoose-im · 2021-09-03T14:25:43Z

small_tests_24 / small_tests / b7baf52
Reports root / small

internal_mnesia_24 / internal_mnesia / b7baf52
Reports root/ big
OK: 1588 / Failed: 0 / User-skipped: 290 / Auto-skipped: 0

small_tests_22 / small_tests / b7baf52
Reports root / small

dynamic_domains_24 / pgsql_mnesia / b7baf52
Reports root/ big
OK: 1690 / Failed: 0 / User-skipped: 114 / Auto-skipped: 0

dynamic_domains_23 / pgsql_mnesia / b7baf52
Reports root/ big
OK: 1690 / Failed: 0 / User-skipped: 114 / Auto-skipped: 0

small_tests_23 / small_tests / b7baf52
Reports root / small

ldap_mnesia_24 / ldap_mnesia / b7baf52
Reports root/ big
OK: 1515 / Failed: 0 / User-skipped: 363 / Auto-skipped: 0

ldap_mnesia_23 / ldap_mnesia / b7baf52
Reports root/ big
OK: 1515 / Failed: 0 / User-skipped: 363 / Auto-skipped: 0

ldap_mnesia_22 / ldap_mnesia / b7baf52
Reports root/ big
OK: 1515 / Failed: 0 / User-skipped: 363 / Auto-skipped: 0

elasticsearch_and_cassandra_24 / elasticsearch_and_cassandra_mnesia / b7baf52
Reports root/ big
OK: 1891 / Failed: 0 / User-skipped: 286 / Auto-skipped: 0

pgsql_mnesia_22 / pgsql_mnesia / b7baf52
Reports root/ big
OK: 3090 / Failed: 0 / User-skipped: 184 / Auto-skipped: 0

pgsql_mnesia_24 / pgsql_mnesia / b7baf52
Reports root/ big
OK: 3090 / Failed: 0 / User-skipped: 184 / Auto-skipped: 0

pgsql_mnesia_23 / pgsql_mnesia / b7baf52
Reports root/ big
OK: 3090 / Failed: 0 / User-skipped: 184 / Auto-skipped: 0

mssql_mnesia_24 / odbc_mssql_mnesia / b7baf52
Reports root/ big
OK: 3099 / Failed: 3 / User-skipped: 184 / Auto-skipped: 0

carboncopy_SUITE:all:unavailable_resources_dont_get_carbons

{error,{{assertion_failed,assert_many,false,[is_presence,is_presence],[],[]},
    [{escalus_new_assert,assert_true,2,
               [{file,"/home/circleci/app/big_tests/_build/default/lib/escalus/src/escalus_new_assert.erl"},
                {line,84}]},
     {escalus_story,story,4,
            [{file,"/home/circleci/app/big_tests/_build/default/lib/escalus/src/escalus_story.erl"},
             {line,72}]},
     {test_server,ts_tc,3,[{file,"test_server.erl"},{line,1783}]},
     {test_server,run_test_case_eval1,6,
            [{file,"test_server.erl"},{line,1292}]},
     {test_server,run_test_case_eval,9,
            [{file,"test_server.erl"},{line,1224}]}]}}

Report log

carboncopy_SUITE:all:prop_forward_received_chat_messages

{error,
  {{assertEqual,
     [{module,carboncopy_SUITE},
      {line,277},
      {expression,
        "proper : quickcheck ( proper : conjunction ( [ { PropName , Property } ] ) , [ verbose , long_result , { numtests , 3 } ] )"},
      {expected,true},
      {value,
        [[{forward_received,
          [{5,<<"Now, fair Hippolyta, our nuptial hour">>}]}]]}]},
   [{carboncopy_SUITE,run_prop,2,
      [{file,"/home/circleci/app/big_tests/tests/carboncopy_SUITE.erl"},
       {line,277}]},
    {test_server,ts_tc,3,[{file,"test_server.erl"},{line,1783}]},
    {test_server,run_test_case_eval1,6,
      [{file,"test_server.erl"},{line,1292}]},
    {test_server,run_test_case_eval,9,
      [{file,"test_server.erl"},{line,1224}]}]}}

Report log

carboncopy_SUITE:all:prop_forward_sent_chat_messages

{error,
  {{assertEqual,
     [{module,carboncopy_SUITE},
      {line,277},
      {expression,
        "proper : quickcheck ( proper : conjunction ( [ { PropName , Property } ] ) , [ verbose , long_result , { numtests , 3 } ] )"},
      {expected,true},
      {value,
        [[{forward_sent,
          [{5,<<"Now, fair Hippolyta, our nuptial hour">>}]}]]}]},
   [{carboncopy_SUITE,run_prop,2,
      [{file,"/home/circleci/app/big_tests/tests/carboncopy_SUITE.erl"},
       {line,277}]},
    {test_server,ts_tc,3,[{file,"test_server.erl"},{line,1783}]},
    {test_server,run_test_case_eval1,6,
      [{file,"test_server.erl"},{line,1292}]},
    {test_server,run_test_case_eval,9,
      [{file,"test_server.erl"},{line,1224}]}]}}

Report log

riak_mnesia_24 / riak_mnesia / b7baf52
Reports root/ big
OK: 1738 / Failed: 0 / User-skipped: 289 / Auto-skipped: 0

mysql_redis_24 / mysql_redis / b7baf52
Reports root/ big
OK: 3082 / Failed: 2 / User-skipped: 201 / Auto-skipped: 0

mam_SUITE:rdbms_simple_prefs_cases:messages_filtered_when_prefs_default_policy_is_never

{error,{test_case_failed,"ASSERT EQUAL\n\tExpected []\n\tValue [ok]\n"}}

Report log

mod_event_pusher_rabbit_SUITE:group_chat_message_publish:group_chat_message_received_event_properly_formatted

{error,
  {{assertMatch,
     [{module,mod_event_pusher_rabbit_SUITE},
      {line,435},
      {expression,
        "get_decoded_message_from_rabbit ( AliceGroupChatMsgRecvRK )"},
      {pattern,
        "# { << \"from_user_id\" >> := BobRoomJID , << \"to_user_id\" >> := AliceFullJID , << \"message\" >> := Message }"},
      {value,
        #{<<"from_user_id">> => <<"muc_publish@muc.localhost">>,
        <<"message">> => <<>>,
        <<"to_user_id">> =>
          <<"alice_unnamed_37.137287@localhost/res1">>}}]},
   [{mod_event_pusher_rabbit_SUITE,
      '-group_chat_message_received_event_properly_formatted/1-fun-1-',3,
      [{file,
         "/home/circleci/app/big_tests/tests/mod_event_pusher_rabbit_SUITE.erl"},
       {line,435}]},
    {escalus_story,story,4,
      [{file,
         "/home/circleci/app/big_tests/_build/default/lib/escalus/src/escalus_story.erl"},
       {line,72}]},
    {test_server,ts_tc,3,[{file,"test_server.erl"},{line,1783}]},
    {test_server,run_test_case_eval1,6,
      [{file,"test_server.erl"},{line,1292}]},
    {test_server,run_test_case_eval,9,
      [{file,"test_server.erl"},{line,1224}]}]}}

Report log

chrzaszcz

Looks good! There are a few places where I added minor comments.

doc/advanced-configuration/general.md

doc/advanced-configuration/Modules.md

doc/developers-guide/Hooks-and-handlers.md

gustawlippa added 3 commits September 2, 2021 13:32

Fix a typo

f4c626c

Document dynamic domains

27f44fd

[skip-ci] Fix small issues with the Swagger file

f75d615

Found with the help of the editor at: https://editor.swagger.io/

This comment has been minimized.

Sign in to view

Add Swagger to dynamic domains REST API

d10530b

Warning: Contains some suspicious JS usage.

This comment has been minimized.

Sign in to view

[skip-ci] Update Host to HostType

cb359de

This comment has been minimized.

Sign in to view

[skip-ci] Document mod_domain_isolation

b8ae568

[skip-ci] Update the domain management requirements

b7baf52

gustawlippa marked this pull request as ready for review September 3, 2021 14:18

vkatsuba reviewed Sep 3, 2021

View reviewed changes

doc/advanced-configuration/Modules.md Outdated Show resolved Hide resolved

[skip ci] Add links to modules

5ed937a

chrzaszcz approved these changes Sep 6, 2021

View reviewed changes

doc/advanced-configuration/general.md Outdated Show resolved Hide resolved

doc/advanced-configuration/Modules.md Outdated Show resolved Hide resolved

doc/developers-guide/Hooks-and-handlers.md Outdated Show resolved Hide resolved

vkatsuba approved these changes Sep 6, 2021

View reviewed changes

[skip ci] Apply language review

098494b

vkatsuba merged commit b5d20dc into master Sep 6, 2021

vkatsuba deleted the doc-multi-tenancy branch September 6, 2021 08:35

Premwoik added this to the 5.0.0 milestone Oct 5, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document dynamic domains #3242

Document dynamic domains #3242

gustawlippa commented Sep 3, 2021 •

edited

This comment has been minimized.

codecov bot commented Sep 3, 2021 •

edited

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

mongoose-im commented Sep 3, 2021 •

edited

mongoose-im commented Sep 3, 2021 •

edited

chrzaszcz left a comment

Document dynamic domains #3242

Document dynamic domains #3242

Conversation

gustawlippa commented Sep 3, 2021 • edited

This comment has been minimized.

codecov bot commented Sep 3, 2021 • edited

Codecov Report

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

mongoose-im commented Sep 3, 2021 • edited

mongoose-im commented Sep 3, 2021 • edited

chrzaszcz left a comment

Choose a reason for hiding this comment

gustawlippa commented Sep 3, 2021 •

edited

codecov bot commented Sep 3, 2021 •

edited

mongoose-im commented Sep 3, 2021 •

edited

mongoose-im commented Sep 3, 2021 •

edited