prosody-hg: core/moduleapi.lua history

Merge 13.0->trunk

Wed, 29 Apr 2026 17:12:59 +0100

Merge 13.0->trunk

Merge 0.12->13.0

Wed, 29 Apr 2026 17:12:11 +0100

Merge 0.12->13.0

moduleapi: Use multitable add/remove instead of set

Fri, 17 Apr 2026 17:39:06 +0100

moduleapi: Use multitable add/remove instead of set

multitable:set() does not clear intermediate keys when setting the last one to
nil. This meant that the event_handlers multitable for every module was not
properly cleaning up the object and event name from the table when calling
:unhook_object_event().

This combined badly with e.g. mod_bookmarks, which uses this extensively to
add/remove hooks dynamically for mod_pep services. The multitable kept a
reference to every mod_pep service object ever created, causing a memory leak.

The multitable:remove() function clears intermediate keys when they are empty,
so we've switched to using that now.

Merge 13.0->trunk

Fri, 17 Apr 2026 17:47:01 +0100

Merge 13.0->trunk

moduleapi: Use multitable add/remove instead of set

Fri, 17 Apr 2026 17:39:06 +0100

Merge 13.0->trunk

Wed, 11 Mar 2026 16:59:10 +0100

Merge 13.0->trunk

core.moduleapi: Use default value when enum option has incorrect value

Wed, 11 Mar 2026 16:53:48 +0100

core.moduleapi: Use default value when enum option has incorrect value

Is an error without consequences even an error?

core.moduleapi: Fix :context() called from a global module

Wed, 05 Nov 2025 16:19:50 +0100

core.moduleapi: Fix :context() called from a global module

Because `is_global` defaults to nil, it passes trough the metatabele to
the calling module, so a host context retrieved from a global module
would have the .global flag be true. This causes trouble with the code
retrieving the hostname in `module:http_url()`, so `http:list()` in the
shell would produce host URLs like `https://*:5281/`

moduleapi: Fix traceback when no host passed to :context() (thanks Menel, riau)

Thu, 03 Jul 2025 10:59:17 +0100

moduleapi: Fix traceback when no host passed to :context() (thanks Menel, riau)

I don't particularly like this, but it seems to be depended on and I don't
plan to break the API at this time.

moduleapi: :hook(): don't silently fall back to global events when host unknown

Fri, 27 Jun 2025 11:12:50 +0100

moduleapi: :hook(): don't silently fall back to global events when host unknown

This code will throw an error instead, but it's a situation that shouldn't
happen (especially now :context() rejects unknown hosts).

Related to #605

moduleapi: :context(): ensure requested host exists (fixes #605)

Fri, 27 Jun 2025 11:11:08 +0100

moduleapi: :context(): ensure requested host exists (fixes #605)

moduleapi: Allow soft dependencies via module:depends(mod, true)

Sun, 16 Feb 2025 13:29:07 +0000

moduleapi: Allow soft dependencies via module:depends(mod, true)

core.moduleapi: Include source modules when handling items

Wed, 08 Jan 2025 08:33:34 +0100

core.moduleapi: Include source modules when handling items

This improves consistency. Previously the 'source' field was only
provided in the original event when an item was added. It is used to
report the name of the module providing the item in a few places.

Also considered adding a new API to modulemanager returning a mapping
of items per module and then using that here.

Merge 0.12->trunk

Sun, 18 Aug 2024 17:01:47 +0200

Merge 0.12->trunk

core.moduleapi: Default labels to empty list to fix error if omitted

Sun, 18 Aug 2024 16:58:30 +0200

core.moduleapi: Default labels to empty list to fix error if omitted

In a host-scoped module in the `if is_scoped` clause the resulting
`array:append(nil)` call throws.

moduleapi: Log error message when ambiguous period spec is found in config

Thu, 30 Nov 2023 13:43:23 +0000

moduleapi: Log error message when ambiguous period spec is found in config

moduleapi: Rename :once() to :on_ready() for clarity

Thu, 30 Nov 2023 10:07:53 +0000

moduleapi: Rename :once() to :on_ready() for clarity

'Once' is ambiguous - once per what?

on_ready() executes its parameter when the module is loaded *and* the server
has finished starting.

moduleapi: may(): Support explicit actor_jid in context object

Tue, 07 Nov 2023 11:53:57 +0000

moduleapi: may(): Support explicit actor_jid in context object

core.moduleapi: Parse period min/max arguments

Sat, 22 Jul 2023 12:08:01 +0200

core.moduleapi: Parse period min/max arguments

Allows specifying them the same way as the default and in the config,
for consistency

core.moduleapi: Fix min/maxinteger fallback for Lua 5.2

Mon, 17 Jul 2023 02:32:47 +0200

core.moduleapi: Fix min/maxinteger fallback for Lua 5.2

Maybe these should live in util.mathcompat?

core.moduleapi: Add min/max range support to :get_option_period

Mon, 17 Jul 2023 00:37:44 +0200

core.moduleapi: Add min/max range support to :get_option_period

To match :get_option_number etc, specifying the allowed interval.

Default is essentially (0, inf].

moduleapi: Add :get_option_integer()

Mon, 17 Jul 2023 00:09:41 +0200

moduleapi: Add :get_option_integer()

Many options in Prosody that are treated as numbers don't make sense as
floats, e.g. sizes and limits measured in bytes.

Simplified implementation based on an earlier attempt dating back to 2020

core.moduleapi: Accept boolean false to disable period setting

Sun, 16 Jul 2023 21:04:42 +0200

core.moduleapi: Accept boolean false to disable period setting

core.moduleapi: Log error for unexpected types (booleans?) set as periods

Sun, 16 Jul 2023 21:02:24 +0200

core.moduleapi: Log error for unexpected types (booleans?) set as periods

core.moduleapi: Turn negative periods or "never" into infinity

Sun, 16 Jul 2023 21:01:31 +0200

core.moduleapi: Turn negative periods or "never" into infinity

As a way to signal that the periodic thing should be disabled, matching
existing mod_mam usage

core.moduleapi: Improve handling of different types in :get_option_period

Sun, 16 Jul 2023 20:59:27 +0200

core.moduleapi: Improve handling of different types in :get_option_period

Pass positive numbers trough unharmed, parse strings as periods, discard
anything else.

core.moduleapi: Add :get_option_period for parsing time intervals

Sun, 16 Jul 2023 19:49:12 +0200

core.moduleapi: Add :get_option_period for parsing time intervals

E.g. for use in mod_mam and others that take an amount of time before
some (usually cleanup) action is taken.

core.moduleapi: Allow specifying an acceptable range for number options

Tue, 05 Oct 2021 15:36:38 +0200

core.moduleapi: Allow specifying an acceptable range for number options

moduleapi: Add enum config option method

Sat, 16 Jan 2021 20:40:14 +0100

moduleapi: Add enum config option method

For when a setting has a few fixed values it can take

moduleapi: Add luacheck annotation to suppress warning about unused self

Sat, 01 Apr 2023 12:30:29 +0100

moduleapi: Add luacheck annotation to suppress warning about unused self

This is a convenience function, and there is currently no module-specific code
required to implement it. Not using 'self' is to be expected.

moduleapi: Add module:once() to execute a function after module load/startup

Sat, 01 Apr 2023 11:59:50 +0100

moduleapi: Add module:once() to execute a function after module load/startup

It is a common pattern for modules to do something like check for
prosody.start_time, and execute code immediately if it is present, or wait for
the server-started event if it isn't yet. For example, this allows you to run
code after all other modules/hosts have been loaded, that are going to be
loaded.

Such code can now be replaced with a simple call to this method.

moduleapi: Add 'peek' to :may() and new :could() helper to suppress logging

Sun, 26 Mar 2023 14:06:04 +0100

moduleapi: Add 'peek' to :may() and new :could() helper to suppress logging

The current method logs scary "access denied" messages on failure - this is
generally very useful when debugging access control stuff, but in some cases
the call is simply a check to see if someone *could* perform an action, even
if they haven't requested it yet. One example is determining whether to show
the user as an admin in disco.

The 'peek' parameter, if true, will suppress such logging.

The :could() method is just a simple helper that can make the calling code a
bit more readable (suggested by Zash).

moduleapi: may: Fail early if a local session has no role assigned

Sat, 25 Mar 2023 19:38:41 +0000

moduleapi: may: Fail early if a local session has no role assigned

We expect every session to explicitly have a role assigned. Falling back to
any kind of "default" role (even the user's default role) in the absence of
an explicit role could open up the possibility of accidental privilege
escalation.

core: Prefix module imports with prosody namespace

Fri, 17 Mar 2023 16:23:07 +0100

core: Prefix module imports with prosody namespace

core.moduleapi: Record reverse dependencies

Sun, 05 Mar 2023 14:07:08 +0100

core.moduleapi: Record reverse dependencies

Useful to know why a module was auto-loaded without having to dig trough
all other modules for the one that depends on it.

core.moduleapi: Fix passing variable to logging

Tue, 31 Jan 2023 07:48:21 +0100

core.moduleapi: Fix passing variable to logging

core.moduleapi: Check for local role-aware sessions before e.g. s2s

Mon, 29 Aug 2022 11:47:31 +0200

core.moduleapi: Check for local role-aware sessions before e.g. s2s

The condition checked for s2sin but not s2sout, so would have ignored
bidi-enabled s2sout sessions. Components as well.

mod_authz_internal, and more: New iteration of role API

Wed, 17 Aug 2022 16:38:53 +0100

mod_authz_internal, and more: New iteration of role API

These changes to the API (hopefully the last) introduce a cleaner separation
between the user's primary (default) role, and their secondary (optional)
roles.

To keep the code sane and reduce complexity, a data migration is needed for
people using stored roles in 0.12. This can be performed with

prosodyctl mod_authz_internal migrate

moduleapi: Stricter type check for actor in permission check

Wed, 20 Jul 2022 13:08:07 +0200

moduleapi: Stricter type check for actor in permission check

Non-table but truthy values would trigger "attempt to index a foo value"
on the next line otherwise

moduleapi: Remove redundant expansion of ':' prefix in permission names

Wed, 20 Jul 2022 13:07:04 +0200

moduleapi: Remove redundant expansion of ':' prefix in permission names

moduleapi: Distribute permissions set from global modules to all hosts

Wed, 20 Jul 2022 13:05:35 +0200

moduleapi: Distribute permissions set from global modules to all hosts

Roles and permissions will always happen in the context of a host.

Prevents error upon indexing since `hosts["*"] == nil`

core.moduleapi: Expand permission name ':' prefix earlier

Wed, 15 Jun 2022 23:04:17 +0200

core.moduleapi: Expand permission name ':' prefix earlier

Ensures it applies to the context as string case

Somehow this fixes everything

core.moduleapi: Fixup method name

Wed, 15 Jun 2022 23:03:15 +0200

core.moduleapi: Fixup method name

`get_user_role()` did not exist anywhere else.

MattJ said `get_user_default_role()` was indented

Switch to a new role-based authorization framework, removing is_admin()

Wed, 15 Jun 2022 12:15:01 +0100

Switch to a new role-based authorization framework, removing is_admin()

We began moving away from simple "is this user an admin?" permission checks
before 0.12, with the introduction of mod_authz_internal and the ability to
dynamically change the roles of individual users.

The approach in 0.12 still had various limitations however, and apart from
the introduction of roles other than "admin" and the ability to pull that info
from storage, not much actually changed.

This new framework shakes things up a lot, though aims to maintain the same
functionality and behaviour on the surface for a default Prosody
configuration. That is, if you don't take advantage of any of the new
features, you shouldn't notice any change.

The biggest change visible to developers is that usermanager.is_admin() (and
the auth provider is_admin() method) have been removed. Gone. Completely.

Permission checks should now be performed using a new module API method:

module:may(action_name, context)

This method accepts an action name, followed by either a JID (string) or
(preferably) a table containing 'origin'/'session' and 'stanza' fields (e.g.
the standard object passed to most events). It will return true if the action
should be permitted, or false/nil otherwise.

Modules should no longer perform permission checks based on the role name.
E.g. a lot of code previously checked if the user's role was prosody:admin
before permitting some action. Since many roles might now exist with similar
permissions, and the permissions of prosody:admin may be redefined
dynamically, it is no longer suitable to use this method for permission
checks. Use module:may().

If you start an action name with ':' (recommended) then the current module's
name will automatically be used as a prefix.

To define a new permission, use the new module API:

module:default_permission(role_name, action_name)
module:default_permissions(role_name, { action_name[, action_name...] })

This grants the specified role permission to execute the named action(s) by
default. This may be overridden via other mechanisms external to your module.

The built-in roles that developers should use are:

- prosody:user (normal user)
- prosody:admin (host admin)
- prosody:operator (global admin)

The new prosody:operator role is intended for server-wide actions (such as
shutting down Prosody).

Finally, all usage of is_admin() in modules has been fixed by this commit.
Some of these changes were trickier than others, but no change is expected to
break existing deployments.

EXCEPT: mod_auth_ldap no longer supports the ldap_admin_filter option. It's
very possible nobody is using this, but if someone is then we can later update
it to pull roles from LDAP somehow.

compat: Use table.pack (there since Lua 5.2) over our util.table

Mon, 11 Jul 2022 19:15:24 +0200

compat: Use table.pack (there since Lua 5.2) over our util.table

Added in d278a770eddc avoid having to deal with its absence in Lua 5.1.
No longer needed when Lua 5.1 support is dropped.

compat: Remove handling of Lua 5.1 location of 'unpack' function

Mon, 11 Jul 2022 19:07:38 +0200

compat: Remove handling of Lua 5.1 location of 'unpack' function

core.moduleapi: Fix 'global' property via :context() - #1748

Wed, 27 Apr 2022 17:18:46 +0200

core.moduleapi: Fix 'global' property via :context() - #1748

The 'global' property should reflect whether the module API instance
represents the global context or a VirtualHost or Component context.
However the module:context() method did not override this, leading the
property of the previous module shining trough, leading to bugs in code
relying on the 'global' property.

See also #1736

modulemanager, moduleapi: Switch to new pluginloader interface

Fri, 04 Feb 2022 14:11:46 +0000

modulemanager, moduleapi: Switch to new pluginloader interface

moduleapi: Support stripping of multi-word from module names

Wed, 22 Dec 2021 14:40:42 +0000

moduleapi: Support stripping of multi-word from module names

The goal is to allow module:provides("foo-bar") with a mod_foo_bar_ prefix
being stripped. It will break any existing modules that use a prefix and have
hyphens instead of underscores. No such modules are known.

mod_cron: Add a 'weekly' job frequency

Fri, 03 Dec 2021 09:05:41 +0100

mod_cron: Add a 'weekly' job frequency

core.moduleapi: Add API for adding daily or hourly tasks via mod_cron

Sun, 21 Nov 2021 18:13:21 +0100

core.moduleapi: Add API for adding daily or hourly tasks via mod_cron

mod_admin_shell: List collected metrics in module:info

Wed, 24 Nov 2021 20:03:38 +0100

mod_admin_shell: List collected metrics in module:info

Lets you know what to look for with stats:show()

core.moduleapi: Fix name of renamed API in log message

Thu, 18 Nov 2021 16:26:54 +0100

core.moduleapi: Fix name of renamed API in log message

hook_stanza was renamed hook_tag in 2012 in 2087d42f1e77
Why do we still have hook_stanza?

Why is this only a warning anyway?

core.moduleapi: Ensure module:send_iq() handler priority over mod_iq

Fri, 24 Sep 2021 20:26:21 +0200

core.moduleapi: Ensure module:send_iq() handler priority over mod_iq

To prevent a situation where you for whatever reason use a full JID that
is currently online and the response ends up routed there instead of the
module:send_iq() handlers.

core.moduleapi: Enable full JID origin queries with module:send_iq()

Fri, 24 Sep 2021 20:17:31 +0200

core.moduleapi: Enable full JID origin queries with module:send_iq()

Since we don't currently have hooks that includes type and id here, we
need to check those attributes in the handlers.

core.moduleapi: Filter out unrelated direct replies to module:send_iq

Fri, 24 Sep 2021 20:12:16 +0200

core.moduleapi: Filter out unrelated direct replies to module:send_iq

This is primarily something that happens with an internal query to
mod_mam, which calls origin.send() several times with results, leading
to the first such result being treated as the final response and
resolving the promise.

Now, these responses pass trough to the underlying origin.send(), where
they can be caught. Tricky but not impossible. For remote queries, it's
even trickier, you would likely need to bind a resource or similar.

Statistics: Rewrite statistics backends to use OpenMetrics

Sun, 18 Apr 2021 11:47:41 +0200

Statistics: Rewrite statistics backends to use OpenMetrics

The metric subsystem of Prosody has had some shortcomings from
the perspective of the current state-of-the-art in metric
observability.

The OpenMetrics standard [0] is a formalization of the data
model (and serialization format) of the well-known and
widely-used Prometheus [1] software stack.

The previous stats subsystem of Prosody did not map well to that
format (see e.g. [2] and [3]); the key reason is that it was
trying to do too much math on its own ([2]) while lacking
first-class support for "families" of metrics ([3]) and
structured metric metadata (despite the `extra` argument to
metrics, there was no standard way of representing common things
like "tags" or "labels").

Even though OpenMetrics has grown from the Prometheus world of
monitoring, it maps well to other popular monitoring stacks
such as:

- InfluxDB (labels can be mapped to tags and fields as necessary)
- Carbon/Graphite (labels can be attached to the metric name with
dot-separation)
- StatsD (see graphite when assuming that graphite is used as
backend, which is the default)

The util.statsd module has been ported to use the OpenMetrics
model as a proof of concept. An implementation which exposes
the util.statistics backend data as Prometheus metrics is
ready for publishing in prosody-modules (most likely as
mod_openmetrics_prometheus to avoid breaking existing 0.11
deployments).

At the same time, the previous measure()-based API had one major
advantage: It is really simple and easy to use without requiring
lots of knowledge about OpenMetrics or similar concepts. For that
reason as well as compatibility with existing code, it is preserved
and may even be extended in the future.

However, code relying on the `stats-updated` event as well as
`get_stats` from `statsmanager` will break because the data
model has changed completely; in case of `stats-updated`, the
code will simply not run (as the event was renamed in order
to avoid conflicts); the `get_stats` function has been removed
completely (so it will cause a traceback when it is attempted
to be used).

Note that the measure_*_event methods have been removed from
the module API. I was unable to find any uses or documentation
and thus deemed they should not be ported. Re-implementation is
possible when necessary.

[0]: https://openmetrics.io/
[1]: https://prometheus.io/
[2]: #959
[3]: #960

core.moduleapi: Return resource path from module:get_directory() (API BC)

Fri, 09 Oct 2020 16:37:15 +0200

core.moduleapi: Return resource path from module:get_directory() (API BC)

:get_directory has so far returned the base directory of the current
module source code. This has worked well so far to load resources which
tend to be included in the same directory, but with the plugin installer
using LuaRocks, extra resources (e.g. templates and other assets) these
are saved in a completely different directory.

In be73df6765b9 core.modulemanager gained some code for finding that
directory and saving it in module.resource_path but now the question is
how this should be reflected in the API.

A survey of community modules suggest the vast majority use the
:get_directory method for locating templates and other assets, rather
than the code (which would use module:require instead).

Therefore this commit changes :get_directory to return the resource_path
when available. This should work for most modules.

core.moduleapi: Use resource path for :load_resource()

Wed, 07 Oct 2020 16:10:51 +0200

core.moduleapi: Use resource path for :load_resource()

core.moduleapi: Allow passing a config table trough :measure

Fri, 04 Jan 2019 07:00:45 +0100

core.moduleapi: Allow passing a config table trough :measure