view mod_delegation/README.markdown @ 4249:64aa1d9d70ac

mod_rest: Catch and log errors in callback promise chain From the code it looks like it should be possible to reply to an error stanza, but it did not. Turns out I was saved by my local developer mode module which throws errors if an attempt is made to create an errror reply to an error stanza. However nothing collects this error from the promise, so all I got was confusion.
author Kim Alvefur <zash@zash.se>
date Sun, 15 Nov 2020 16:25:49 +0100
parents ea6b5321db50
children 679f1834dbdb
line wrap: on
line source

---
labels:
- 'Stage-Beta'
summary: 'XEP-0355 (Namespace Delegation) implementation'
...

Introduction
============

Namespace Delegation is an extension which allows server to delegate
some features handling to an entity/component. Typical use case is an
external PEP service, but it can be used more generally when your
preferred server lack one internal feature and you found an external
component which can do it.

Details
=======

You can have all the details by reading the
[XEP-0355](http://xmpp.org/extensions/xep-0355.html). Only the admin
mode is implemented so far.

Usage
=====

To use the module, like usual add **"delegation"** to your
modules\_enabled. Note that if you use it with a local component, you
also need to activate the module in your component section:

    modules_enabled = {
            [...]

            "delegation";
    }

    [...]

    Component "youcomponent.yourdomain.tld"
        component_secret = "yourpassword"
        modules_enabled = {"delegation"}

then specify delegated namespaces **in your host section** like that:

    VirtualHost "yourdomain.tld"

        delegations = {
            ["urn:xmpp:mam:0"] = {
                filtering = {"node"};
                jid = "pubsub.yourdomain.tld";
            },
            ["http://jabber.org/protocol/pubsub"] = {
                jid = "pubsub.yourdomain.tld";
            },
        }

Here all MAM requests with a "node" attribute (i.e. all MAM pubsub
request) will be delegated to pubsub.yourdomain.tld. Similarly, all
pubsub request to the host (i.e. the PEP requests) will be delegated to
pubsub.yourdomain.tld.

**/!\ Be extra careful when you give a delegation to an entity/component,
it's a powerful access, only do it if you absoly trust the
component/entity, and you know where the software is coming from**

Configuration
=============

The configuration is done with a table which map delegated namespace to
namespace data. Namespace data MUST have a **jid** (in the form **jid =
"delegated@domain.tld"**) and MAY have an additional **filtering**
array. If filtering is present, request with attributes in the array
will be delegated, other will be treated normally (i.e. by Prosody).

If your are not a developper, the delegated namespace(s)/attribute(s)
are most probably specified with the external component/entity you want
to use.

The pseudo-namespace `http://jabber.org/protocol/disco#items:*` is used
to delegate remaining disco#items (i.e. items nodes not already handled
by Prosody itself).

Compatibility
=============

If you use it with Prosody 0.9 and a component, you need to patch
core/mod\_component.lua to fire a new signal. To do it, copy the
following patch in a, for example, /tmp/component.patch file:

    diff --git a/plugins/mod_component.lua b/plugins/mod_component.lua
    --- a/plugins/mod_component.lua
    +++ b/plugins/mod_component.lua
    @@ -85,6 +85,7 @@
                    session.type = "component";
                    module:log("info", "External component successfully authenticated");
                    session.send(st.stanza("handshake"));
    +               module:fire_event("component-authenticated", { session = session });

                    return true;
            end

Then, at the root of prosody, enter:

`patch -p1 < /tmp/component.patch`

  ----- ----------------------------------------------------
  0.10  Works
  0.9   Need a patched core/mod\_component.lua (see above)
  ----- ----------------------------------------------------

Note
====

This module is often used with mod\_privilege (c.f. XEP for more
details)