New mod_adhoc_api and related improvements

[badlop]

Update 2025-03-10

• mod_adhoc_api: New option default_version to set API version
• mod_adhoc_api: Replace more arguments from examples
• mod_muc_admin: Fix backwards support of , separator
• Release notes: Add example CURL call to create_room_with_opts
• Release notes: Mention that mod_adhoc_api works with Psi and Psi+ too

---

ejabberd includes mod_configure, which allows to execute 20 commands using a XMPP client with ad-hoc command support. Some of those ad-hoc commands are described in XEP-0133 and others are specifically designed for ejabberd.

On the other hand, we have around 200 API commands that are perfectly documented and accessible from multiple methods (HTTP, XMLRPC, command line and WebAdmin) thanks to the different frontends... so it makes sense to write another frontend that allows to execute all those API commands using a XMPP client with ad-hoc command support.

This PR adds mod_adhoc_api, a new ejabberd module that allows to execute API commands using XEP-0050 (Ad-Hoc Commands). It includes documentation and some test cases.

This PR also includes several improvements in ejabberd required for that feature.

This is a draft text that could be included in the ejabberd release notes:

---

New option access in mod_configure

mod_configure always had support to configure what accounts can access its features: using the configure access rule. The name of that access rule was hard-coded, being configure. Now, thanks to the new option access, that can be configured.

mod_http_api returns sorted list elements

When mod_http_api returns a list of elements, now those elements are sorted alphabetically. If it is a list of tuples, the tuples are sorted alphabetically by the first element in that tuple.

Notice that the new module mod_adhoc_api uses internally mod_http_api to format the API command arguments and result, this means that mod_adhoc_api benefits from this feature too.

New API commands to change mnesia table storage

There are two new API commands: mnesia_list_tables and mnesia_table_change_storage.

In fact those commands were already implemented since ejabberd 24.06, but they were tagged as internal as they were only used by WebAdmin. Now they are available for any API frontend, including mod_adhoc_api.

New mod_adhoc_api module

You may remember this paragraph from the ejabberd 24.06 release notes:

ejabberd already has around 200 commands to perform many administrative tasks, both to get information about the server and its status, and also to perform operations with side-effects. Those commands have its input and output parameters clearly described, and also documented.

Almost a year ago, ejabberd WebAdmin got support to execute all those 200 API commands... and now your XMPP client can execute them too!

The new mod_adhoc_api ejabberd module allows to execute all the ejabberd API commands using a XMPP client that supports XEP-0050 Ad-Hoc Commands and XEP-0030 Service Discovery.

Simply add this module to modules, setup api_permissions to grant some account permission to execute some command, or tags of commands, or all commands. Reload the ejabberd configuration and login with your client to that account.

Now you can execute the same commands in the command line, using ReST, in the WebAdmin, and in your XMPP client!

This feature has been tested with Gajim, Psi, Psi+ and Tkabber. Conversejs allows to list and execute the commands, but doesn't show the result to the user.

create_room_with_opts API command separators

One of the arguments accepted by the create_room_with_opts API command is a list of room options, expressed as tuples of option name and option value. And some room option values are also list of tuples! This is the case of affiliations and subscribers.

That is not a problem for API frontends that accept structured arguments like mod_http_api and ejabberd_xmlrpc. But this is a problem in ejabberdctl, WebAdmin and mod_adhoc_api, because they don't use structured arguments, and instead separate list elements with , and tuple elements with :. In that case, a list of tuples of list of tuples cannot be parsed correctly if all them use the same separators.

Solution: when using the create_room_with_opts command to set affiliations and subscribers options:

• list elements were separated with , and now should be with ;
• tuple elements were separated with : and now should be with =

All the previous separators are still supported for backwards compatibility, but please use the new recommended separators, specially if using ejabberdctl, WebAdmin, and mod_adhoc_api.

Let's see side by side the old and the new recommended syntax:

affiliations:owner:user1@localhost,member:user2@localhost
affiliations:owner=user1@localhost;member=user2@localhost

In a practical example, instead of this (which didn't work at all):

ejabberdctl \
  create_room_with_opts \
  room_old_separators \
  conference.localhost \
  localhost \
  "persistent:true,affiliations:owner:user1@localhost,member:user2@localhost"

please use:

ejabberdctl \
  create_room_with_opts \
  room_new_separators \
  conference.localhost \
  localhost \
  "persistent:true,affiliations:owner=user1@localhost;member=user2@localhost"

Notice that both the old and new separators are supported by create_room_with_opts. For example, let's use curl to query mod_http_api:

curl -k -X POST -H "Content-type: application/json" \
     "http://localhost:5280/api/create_room_with_opts" \
     -d '{"name": "room_old_separators",
          "service": "conference.localhost",
          "host": "localhost",
          "options": [
           {"name": "persistent",
            "value": "true"},
           {"name": "affiliations",
            "value": "owner:user1@localhost,member:user2@localhost"}
          ]
         }'

curl -k -X POST -H "Content-type: application/json" \
     "http://localhost:5280/api/create_room_with_opts" \
     -d '{"name": "room_new_separators",
          "service": "conference.localhost",
          "host": "localhost",
          "options": [
           {"name": "persistent",
            "value": "true"},
           {"name": "affiliations",
            "value": "owner=user1@localhost;member=user2@localhost"}
          ]
         }'

[coveralls]

coverage: 33.772% (+0.3%) from 33.487%
when pulling 9bf2d6c on badlop:adhoc_api
into 53dea7b on processone:master.

[Neustradamus]

@badlop: Very good job, happy to see these improvements!