view release on metacpan or  search on metacpan

lib/Jabber/RPC/HTTPgate.pm  view on Meta::CPAN

# Jabber-RPC: J-RPC/HTTP Gateway
# (experimental!)
# (c) DJ Adams 2001

# $Id: HTTPgate.pm,v 1.1.1.1 2001/10/14 20:47:51 dj Exp $

=head1 NAME

Jabber::RPC::HTTPgate - An HTTP gateway for Jabber-RPC / XML-RPC

=head1 SYNOPSIS

  use Jabber::RPC::HTTPgate;

  my $gw = new Jabber::RPC::HTTPgate(
    server    => 'myserver.org:5701',
    identauth => 'jrpchttp.localhost:secret',
    httpcomp  => 'http',
  );  

  $gw->start;

=head1 DESCRIPTION

Jabber::RPC::HTTPgate is an experimental gateway that provides
a conduit service between 'traditional' (HTTP-transported) 
XML-RPC encoded requests/responses and Jabber-RPC (XML-RPC
encoded requests/responses transported over Jabber).

The idea is that you can start a gateway, that connects as
a component to the backbone of a Jabber server, and it proxies
Jabber-RPC to HTTP-based XML-RPC endpoints, and vice versa.
That means that your Jabber-RPC client can not only make XML-RPC
encoded calls to a Jabber-RPC endpoint but also to a 'traditional'
HTTP-based XML-RPC endpoint. And it also means that your 
'traditional' HTTP-based XML-RPC client can make XML-RPC encoded
calls to a Jabber-RPC endpoint.

=head2 Jabber -> HTTP

When you create and start up a gateway, it listens for Jabber-RPC
calls, just like a normal Jabber-RPC responder. On receipt of such a
call, the gateway creates an HTTP request and sends this
request on to the HTTP-based XML-RPC endpoint. The response 
received back from this HTTP call is relayed back to the original
Jabber-RPC requester. 

While a Jabber-RPC endpoint address is a Jabber ID (JID), an 
traditional XML-RPC endpoint address is a URL. So all the Jabber-RPC
client needs to do is specify the URL in the I<resource> part of
the gateway's endpoint JID. 

=head2 HTTP -> Jabber

As well as listening for Jabber-RPC calls, a gateway will also 
service incoming HTTP requests that can be made to the HTTP
component that this gateway uses. The HTTP component (called
simply 'http') can be downloaded from the normal Jabber software
repository. 

On receipt of an HTTP request (passed to it by the HTTP component),
the gateway creates a Jabber-RPC request containing the XML-RPC
encoded payload, and sends it on to the Jabber-RPC responder 
endpoint. This endpoint is identified (via a JID) by the I<path>
part of the URL used in the call by the traditional client.

=head2 Diagram

Here's what it all looks like:


                     +---+   2-----------+            3-----------+
 Jabber backbone ----->  l   | http      |<-- HTTP -->| HTTP      |
                     l   l===| component |            | responder |        
     5-----------+   l   l +->           |<- HTTP -+  |           |
     | JabberRPC |   l   l | +-----------+         |  +-----------+
     | responder |===l   l |                       |         
     |(component)|<---+  l +---+                   |  4-----------+
     +-----------+   l|  l     | <route/>          |  | HTTP      |
                     l|<iq/> 3-v---------+         +->| requester |         
     6-----------+   l+----->| HTTPgate  |            |           |
     | JabberRPC |   l|  l===| component |            +-----------+
     | responder |   l| +--->|           |                   
     | (client)  |   l| |l   +-----------+
     +-----------+   l| |l                     
          ^          l| |l                     
          | <iq/>    l| |l                     
          v          l| |l                     
     7-----------+   l| |l                     
     | JSM       |<---+ |l                                   
     | component |===l  |l                                   
     |           |<-----+l                                   
     +-----------+ <iq/> l
          ^          l   l                                     
          | <iq/>    :   :
          v          +---+
     8-----------+   
     | JabberRPC |  
     | requester | 
     | (client)  |
     +-----------+  

The diagram shows all the possible components in the Jabber-RPC and
traditional HTTP-based XML-RPC world. Each box is numbered. Here are
the descriptions:

=over 4

=item 1 HTTPgate component

This is an instance of this module (HTTPgate.pm) and serves as a
gateway between HTTP-based and Jabber-based XML-RPC requests and
responses. On the one side it uses an http component (see #2) to
make and respond to HTTP calls, and on the other side it accepts
and generates <iq/> packets containing XML-RPC encoded payloads.

=item 2 http component

The HTTPgate component uses this http component to make and receive
HTTP calls. HTTP calls and responses are routed between the HTTPgate
component and this component via <route/>s. You need an http
component like this for HTTPgate to work; download the code from
http://download.jabber.org.