mod_rest: Return specific errors from credential checks
This is a step towards returning details of what went wrong when
checking credentials, distinguishing missing, malformed, and wrong
credentials.
# Introduction
This module lets you programmatically subscribe to updates from a
[pubsub][xep0060] node, even if the pubsub service is remote.
## Example
``` {.lua}
module:depends("pubsub_subscription");
module:add_item("pubsub-subscription", {
service = "pubsub.example.com";
node = "otter_facts";
-- Callbacks:
on_subscribed = function()
module:log("info", "Otter facts incoming!");
end;
on_item = function(event)
module:log("info", "Random Otter Fact: %s", event.payload:get_text());
end;
});
```
## Usage
Ensure the module is loaded and add your subscription via the
`:add_item` API. The item table MUST have `service` and `node` fields
and SHOULD have one or more `on_<event>` callbacks.
The JID of the pubsub service is given in `service` (could also be the
JID of an user for advanced PEP usage) and the node is given in,
unsurprisingly, the `node` field.
The various `on_event` callback functions, if present, gets called when
new events are received. The most interesting would be `on_item`, which
receives incoming items. Available events are:
`on_subscribed`
: The subscription was successful, events may follow.
`on_unsubscribed`
: Subscription was removed successfully, this happens if the
subscription is removed, which you would normally never do.
`on_error`
: If there was an error subscribing to the pubsub service. Receives a
table with `type`, `condition`, `text`, and `extra` fields as
argument.
`on_item`
: An item publication, the payload itself available in the `payload`
field in the table provided as argument. The ID of the item can be
found in `item.attr.id`.
`on_retract`
: When an item gets retracted (removed by the publisher). The ID of
the item can be found in `item.attr.id` of the table argument..
`on_purge`
: All the items were removed by the publisher.
`on_delete`
: The entire pubsub node was removed from the pubsub service. No
subscription exists after this.
``` {.lua}
event_payload = {
-- Common prosody event entries:
stanza = util.stanza;
origin = util.session;
-- PubSub service details
service = "pubsub.example.com";
node = "otter_facts";
-- The pubsub event itself
item = util.stanza; -- <item/>
payload = util.stanza; -- actual payload, child of <item/>
}
```
# Compatibility
Should work with Prosody \>= 0.11.x