prosody-modules
7c77058a1ac5
mod_compat_roles/README.markdown
Software / code / prosody-modules
Comparison
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 |
| child | 4984:fc6a618bfe4e |
comparison
equal
deleted
inserted
replaced
| 4982:8a4b17e2e984 | 4983:7c77058a1ac5 |
|---|---|
| 1 --- | |
| 2 labels: | |
| 3 - Stage-Alpha | |
| 4 summary: 'Compatibility layer for Prosody's future roles API' | |
| 5 ... | |
| 6 | |
| 7 Introduction | |
| 8 ============ | |
| 9 | |
| 10 This module provides compatibility with Prosody's new role and permissions | |
| 11 system. It aims to run on Prosody 0.11 and 0.12, providing a limited version | |
| 12 of the new API backed by is_admin() (which is not going to be present in trunk | |
| 13 and future Prosody versions). | |
| 14 | |
| 15 It is designed for use by modules which want to be compatible with Prosody | |
| 16 versions with and without the new permissions API. | |
| 17 | |
| 18 Configuration | |
| 19 ============= | |
| 20 | |
| 21 There is no configuration. | |
| 22 | |
| 23 Usage (for developers) | |
| 24 ====================== | |
| 25 | |
| 26 If you are a module developer, and want your module to work with Prosody trunk | |
| 27 and future releases, you should avoid the `usermanager.is_admin()` function. | |
| 28 | |
| 29 Instead, depend on this module: | |
| 30 | |
| 31 ``` | |
| 32 module:depends("compat_roles") | |
| 33 ``` | |
| 34 | |
| 35 Then use `module:may()` instead: | |
| 36 | |
| 37 ``` | |
| 38 if module:may(":do-something") then | |
| 39 -- Blah | |
| 40 end | |
| 41 ``` | |
| 42 | |
| 43 For more information on the new role/permissions API, check Prosody's | |
| 44 developer documentation at https://prosody.im/doc/developers/permissions | |
| 45 | |
| 46 Compatibility | |
| 47 ============= | |
| 48 | |
| 49 Requires Prosody 0.11 or 0.12. |
