Use commands in WebAdmin to generate page content

badlop commented 1 month ago

This PR adds several features, all of them related to WebAdmin usage of commands.

New `make_command` functions to easily generate HTML content

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.

The purpose of this PR is to use all those commands to generate HTML content in the ejabberd WebAdmin: instead of writing again erlang code to perform those operations, and then write code to format it and display as HTML... let's have some frontend functions (make_command family) to call the command and generate the HTML content.

Use the new `make_command` functions in many WebAdmin pages

I've converted most of the ejabberd WebAdmin to the make_command feature. It works perfectly for me using a small server and also a backup of an old server with 5000 registered accounts and 10 years of history.

With that new feature, writting content for WebAdmin is much easier if a command already exists, so I've also added many more pages to WebAdmin using other existing commands.

When this code is tested with greater and varied databases, I imagine some problems could appear:

webadmin crashing and displaying empty page when there is some non-latin formatted data
inefficient page generation when large amount of data

There are still a few pages not yet updated.

Configuration requirements

Most WebAdmin pages use commands to generate the content, and access to those commands can be restricted using the api_permissions toplevel option.

The default ejabberd.yml configuration file already defines "admin access" that allows access from loopback IP address and accounts in the admin ACL to execute all commands except stop and start.

Now ejabberd_web_admin is another valid command frontend that can be specified in the from section. You can define fine-grained restrictions for accounts in WebAdmin, for example:

api_permissions:
  "webadmin commands":
    from:
      - ejabberd_web_admin
    who: admin
    what:
      - "*"
      - "![tag:oauth]"

Hook changes

There are several changes in webadmin hooks that now provide the whole HTTP request instead of only some of its elements.

You can update your code easily, see:

webadmin_page_node: instead of Path, Query and Lang, gets Request

-webadmin_page_node(Acc, Node, Path, Query, Lang) ->
+webadmin_page_node(Acc, Node, #request{path = Path, q = Query, lang = Lang}) ->

webadmin_page_hostnode: instead of Path, Query and Lang gets Request

-webadmin_page_hostnode(Acc, Host, Node, Path, Query, Lang) ->
+webadmin_page_hostnode(Acc, Host, Node, #request{path = Path, q = Query, lang = Lang}) ->

webadmin_user: instead of just the Lang, gets the whole Request

-webadmin_user(Acc, User, Server, Lang) ->
+webadmin_user(Acc, User, Server, #request{lang = Lang}) ->

webadmin_menu_hostuser: new hook added:

+webadmin_menu_hostuser(Acc, Host, Username, Lang) ->

webadmin_page_hostuser: new hook added:

+webadmin_page_hostuser(Acc, Host, Username, Request) ->

`internal` command tag and `any` argument/result

During the development of this feature, I noticed the necessity to define some commands that will be used by WebAdmin (or maybe also by other ejabberd code), but should NOT be accessed by command frontends (like ejabberdctl, mod_http_api, ejabberd_xmlrpc).

Such commands are identified because they have the internal tag.

Those commands can use any arbitrarily-formatted arguments/results, defined as any in the command.

`make format` and `indent`

I use Vim, it indents erlang code correctly, but sometimes I modify code and forget to reindent it.

The new make format uses https://github.com/AdRoll/rebar3_format to format and indent files, with those restrictions:

Only formats a file if it contains a line with this string, and formats only starting in that line:
```
%% @format-begin
```
Formatting can be disabled later in the file by adding another line that contains
```
%% @format-end
```
Furthermore, it is later possible to enable formatting again in the same file, in case there is another piece of the file that should be automatically formatted.

Alternatively, it is possible to indent files using Emacs, it also replaces tabs with blankspaces and removes ending spaces. The new make indent indents the lines between:

%% @indent-begin
...
%% @indent-end

TODO

General to-do tasks:

[ ] ejabberd Docs: Update WebAdmin page explaning to administrators how to configure permissions
[ ] ejabberd Docs: Update WebAdmin page explaining to developers how to write new pages
[x] Update modules in ejabberd-contrib to support the new hooks
[ ] Update modules in ejabberd-contrib to benefit from the new make_command feature

Some pages are not yet updated to use the proper commands. Instead, the existing code has been included in internal commands in the meantime:

[x] http://localhost:5280/admin/server/localhost/shared-roster/
[x] http://localhost:5280/admin/node/ejabberd@localhost/contrib/
[x] http://localhost:5280/admin/server/localhost/muc/
[x] http://localhost:5280/admin/node/ejabberd@localhost/db/
[x] http://localhost:5280/admin/muc/
[x] This is too complex and will not be converted into command: http://localhost:5280/admin/server/localhost/last-activity/

coveralls commented 1 month ago

coverage: 32.249% (+0.6%) from 31.673% when pulling 9f86361fed10571af7b375aa6acb24040aac5ec1 on badlop:webadmin-commands into 7ba9f2e4e8c56cf109395b6cfa15466d02053ec0 on processone:master.

coveralls commented 4 weeks ago

coverage: 32.184% (+0.5%) from 31.673% when pulling 1012151cdf9c65f92d2781d87dc553eb16e461e1 on badlop:webadmin-commands into 7ba9f2e4e8c56cf109395b6cfa15466d02053ec0 on processone:master.

coveralls commented 4 weeks ago

coverage: 32.187% (+0.5%) from 31.673% when pulling 7a3d757819e03b5777852a66b5cf3f7374d73945 on badlop:webadmin-commands into 7ba9f2e4e8c56cf109395b6cfa15466d02053ec0 on processone:master.