core.rostermanager

The roster manager manages users rosters and the state of their contacts. It implements the part of RFC6162 that define rosters.

Since the roster encodes information that is connected to the rosters of other users, it is part of a graph. This graph is a global self-correcting data structure.

The roster object

The roster is represented by a data structure that looks something like this:

roster = {
    [false] = {
        version = 123,
        pending = {}
    },
    ["friend@example.com"] = {
        subscription = "both",
        nick = "My Friend",
        groups = {
            ["Friends"] = true
        }
    }
}

It is a map of JIDs to a table of information about each contact, which has a nickname, subscription state and roster groups that the local user added them to.

Storage

load_roster(username, host) --> roster
save_roster(username, host, roster, jid)

These handle loading roster from, and storing to the configured persistent storage. The roster is transparently cached in memory as long as the corresponding user is connected.

load_roster("user", "example.com") returns the roster object for username@example.com, either by loading from storage or from prosody.bare_sessions["username@example"].roster.

All methods

TODO Write about what these do.

load_roster(username, host) --> roster
save_roster(username, host, roster, jid)
add_to_roster(session, jid, item)
remove_from_roster(session, jid)
roster_push(username, host, jid)
process_inbound_subscription_approval(username, host, jid)
process_inbound_subscription_cancellation(username, host, jid)
process_inbound_unsubscribe(username, host, jid)
is_contact_subscribed(username, host, jid)
is_user_subscribed(username, host, jid)
is_contact_pending_in(username, host, jid)
set_contact_pending_in(username, host, jid)
is_contact_pending_out(username, host, jid)
set_contact_pending_out(username, host, jid)
unsubscribe(username, host, jid)
subscribed(username, host, jid)
unsubscribed(username, host, jid)
process_outbound_subscription_request(username, host, jid)