[Catalyst-dev] RFC - Catalyst::Engine::XMPP2

[Daniel Ruoso]

Hi,

After Catalyst::Controller::SOAP having support for WSDL, my next step
is working to support XMPP as an engine, so I can deploy Web Services
using the XMPP protocol, that allows me other choreographies than simple
request-response. I can have things like;


 A ---req----> B ---broadcast -----> C
 ^                      |----------> D
 |                      \----------> E ---------\
 \-----------------req-------------- F <--req---/  


Where A might be an agent that interacts with the user interface that
needs to be notified when an operation deep in the choreografy is
realized.

So, this is the proposed implementation (actually the documentation for
the proposed implementation) of a XMPP engine. The name of the module is
XMPP2 because it uses the Net::XMPP2 module.

___


NAME
Catalyst::Engine::XMPP2 - Net::XMPP2::Connection Catalyst Engine


________________________________________________________________________
SYNOPSIS
MyApp->config->{xmpp} =
   {
    username => "abc",
    domain => "jabber.org",
    password => "foo",
    override_host => "myserver",
    override_port => 5722
   };
  MyApp->run();


________________________________________________________________________
DESCRIPTION
This engine enables you to deploy a Catalyst application that can be
accessed using the XMPP protocol. This is done by a mapping of each XMPP
stanza to a HTTP Request, using the Catalyst::Engine::Embeddable as a
base.


________________________________________________________________________
Semantics mapping
One important thing to realise is that the XMPP semantics are
considerably different than the HTTP semantics, that way, a set of
mappings must be done.


Request-Response
        
        Usually, an HTTP application implements only Request-Response
        semantics for every action. That is not always true for the XMPP
        protocol. In fact, the only stanza that implements this
        semantics is the <iq/> stanza.
        
        That way, when receiving <message/> or <presence/> stanzas, the
        response will be ignored on success. If the response is a
        failure (400 or 500), an error response will be sent. If wanting
        to send an explicit message, that should be done explicitly.
        
        When receiving <iq/> stanzas, the response will be sent back as
        the action processing returns, independent of the response
        status.
        
        In any way, the attributes of the stanza root element will be
        translated as HTTP Headers with the ``XMPP_Stanza_'' prefix.
        
SCRIPT_NAME
        
        This is the most relevant aspect of this mapping. As XMPP
        doesn't have a URI definition for each stanza, that means that
        there's no proper way of dispatching a message to a given
        controller action in Catalyst.
        
        What this mapping does is, at the beggining, creating several
        connections to the server, providing different resource
        identifiers based on the Path actions registered in the
        application.
        
        This have two important side-effects to realize:
        
        A Catalyst XMPP application can only use 'Path' actions, because
        that is the only DispatchType that have a static mapping of the
        available actions. Other DispatchTypes, like Chained or Index,
        depends on the current request to find out which action to
        dispatch. This doesn't forbid the use of the other DispatchTypes
        for internal forward and dispatch, but the only really public
        actions will be the ones seen by the 'Path' DispatchType.
        
        You have to keep in mind that the resources will be
        pre-advertised, and that for each public path action, you will
        have a public jabber id, and, at least by now, a separated
        connection to the server, so it's probably a good idea to do a
        carefull planning of which actions to make public.
        
Content-Type
        
        XMPP has no support for MIME types. Every message is, by
        definition, a XML document. So every request will have the
        ``application/xml'' MIME type. If the response content-type is
        also ``application/xml'', it will be written as raw into the
        XMPP stream. This will allow SOAP responses, for instance, to be
        sent as in XEP-0072.
        
        On the other hand, if the content type is of some other type, it
        will be sent as encoded string inside a <body> tag, as described
        by XMPP RFC3921, this way, interaction with regular IM clients
        should be natural.
        
Scalability
        
        At this point, this engine is single-threaded, which means that
        it will block in each operation, and, therefore it cannot handle
        more than one request at a time. At the time of this writing,
        two options are available to solve this problem:
        
        The first would be to turn this engine into a pre-fork server
        that would keep pipes to every child and dispatch the requests
        to them, while keeping a single control thread for the XMPP
        connections.
        
        The other option would be to implement a balancer server that
        would accept several connections for the same JID and connect
        only once for each JID, dispatching a message sent to some JID
        among each of the candidate connections.
        
        The second option is probably a better idea, as the handling of
        that number of connections could be implemented in C, for
        instance, and using low-level OS operations, like libevent for
        linux, making it easier to scale in several machines.
        


________________________________________________________________________
USAGE
The 'xmpp' configuration key expects a hashref that will be sent to
Net::XMPP2::Connection->new dereferenced. It's important to notice,
however, that setting ``jid'' or ``resource'' in this hash has no effect
as this values will be set according to the Action-Resource mapping.


---


daniel