Routing API

Metronome allows for fully pluggable stanza routing via events.

I'll first give a basic compendium of what "Stanzas" are in Metronome, whenever a XML stanza is received by the server it'll be parsed and converted into a lua object entity to be easily altered or manipulated internally (see util.stanza).

After that each net-provider module (formally mod_c2s, mod_s2s, mod_bosh and mod_websockets) will fire one of the following global events:

  • route/process - Process a local or remote stanza then call route/post
  • route/post - Fire related stanza pre-events for outgoing stanza and events for incoming ones, or call route/local
  • route/local - Assert if stanzas are directed to internally handled hosts and call route/post in that case else call route/remote on the host (handled by mod_s2s)

These events fully replace core_process_stanza, core_post_stanza and core_route_stanza in Prosody.

route/process and route/local events callbacks will be passed two arguments the first being the origin session of the stanza and the second being the stanza object itself. Instead route/post will have a third boolean argument that specifies there's pre-events to perform if the stanza is an outgoing one.

Example lua code:

-- This processes a stanza before routing it locally or remotely
module:fire_global_event("route/process", origin, stanza);

For what regards, route/remote as said above it's a host event which is handled by mod_s2s, it's used to route a stanza to a remote entity directly without passing by internal routing functions, normally it's direct use by plugins is discouraged as long as you don't know what you're doing, either process or post or module:send() should be adopted instead.