Mercurial > prosody-modules
diff mod_compat_roles/README.markdown @ 4983:7c77058a1ac5
mod_compat_roles: New module providing compat shim for trunk's new role API
The new role API is translated to is_admin() calls on older versions. On newer
versions (which have the role API) this module does nothing.
It allows modules to drop their use of is_admin() (which is not available in
trunk) and switch to the new role API, while remaining compatible with
previous Prosody versions.
| author | Matthew Wild <mwild1@gmail.com> |
|---|---|
| date | Thu, 11 Aug 2022 17:49:33 +0100 |
| parents | |
| children | fc6a618bfe4e |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_compat_roles/README.markdown Thu Aug 11 17:49:33 2022 +0100 @@ -0,0 +1,49 @@ +--- +labels: +- Stage-Alpha +summary: 'Compatibility layer for Prosody's future roles API' +... + +Introduction +============ + +This module provides compatibility with Prosody's new role and permissions +system. It aims to run on Prosody 0.11 and 0.12, providing a limited version +of the new API backed by is_admin() (which is not going to be present in trunk +and future Prosody versions). + +It is designed for use by modules which want to be compatible with Prosody +versions with and without the new permissions API. + +Configuration +============= + +There is no configuration. + +Usage (for developers) +====================== + +If you are a module developer, and want your module to work with Prosody trunk +and future releases, you should avoid the `usermanager.is_admin()` function. + +Instead, depend on this module: + +``` +module:depends("compat_roles") +``` + +Then use `module:may()` instead: + +``` +if module:may(":do-something") then + -- Blah +end +``` + +For more information on the new role/permissions API, check Prosody's +developer documentation at https://prosody.im/doc/developers/permissions + +Compatibility +============= + +Requires Prosody 0.11 or 0.12.