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

Jabber-RPC-HTTPgate documentation Contained in the Jabber-RPC-HTTPgate distribution.

Index

Code Index:

NAME

Top

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

SYNOPSIS

Top

  use Jabber::RPC::HTTPgate;

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

  $gw->start;

DESCRIPTION

Top

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.

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 resource part of the gateway's endpoint JID.

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 path part of the URL used in the call by the traditional client.

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:

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.

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.

3 HTTP responder

This represents a web server on which an XML-RPC responder is present.

4 HTTP requester

This represents a traditional HTTP-based XML-RPC requester.

5 Jabber-RPC responder (component)

This is a Jabber-RPC responder that has been attached to the Jabber backbone as a component. It responds to XML-RPC encoded requests carried in <iq/> packets.

6 Jabber-RPC responder (client)

This is a Jabber-RPC responder that is connected to Jabber via the JSM (Jabber Session Manager) as a client. It also responds to XML-RPC encoded requests carried in <iq/> packets.

7 JSM component

This doesn't have anything to do with Jabber-RPC per se, it's just that Jabber clients connect via the JSM.

8 Jabber-RPC requester

This is a Jabber-RPC requester, in the form of a Jabber client, connected via the JSM.

Some examples

1 Jabber-RPC client makes request directed to an HTTP-based responder.

The Jabber-RPC requester (#8) connects to Jabber via the JSM and creates an XML-RPC encoded request and stores it as the query payload of an IQ packet. The namespace qualifying the query payload is jabber:iq:rpc. Normally, if the request were to to go a Jabber-RPC responder, the JID of that responder (e.g. jrpc.localhost/jrpc-server) would be specified in the 'to' attribute of the IQ packet. But in this case, we want to send the request to an HTTP responder (#3), so we go through the gateway - the HTTPgate component (#3).

The address of the HTTP responder is a URL, e.g.:

  http://localhost:8000/RPC2

So we need to specify this URL somewhere - and we specify it in the resource part of the HTTPgate component's JID. So if the HTTPgate component's basic JID is jrpchttp.localhost, then we specify 

  jrpchttp.localhost/http://localhost:8000/RPC2

as the target JID.

2 HTTP-based requester makes request directed to a Jabber-RPC responder.

The HTTP requester (#4) formulates an XML-RPC encoded request and sends it to the http component (#2). What's the basic URL of the http component? Well, you specify a port in the component instance definition in the jabber.xml configuration file, like this:

  <service id="http">
    <load><http>./http/http.so</http></load>
    <http xmlns="jabber:config:http">
      <listen port="5281">
        <map to="jrpchttp.localhost"/>
      </listen>
      <timeout>60</timeout>
      <dnsrv>http-dns</dnsrv>
    </http>
  </service>

See the README in the http component tarball for more info.

So the basic URL of the http component is e.g.:

  http://localhost:5281

While we need to specify a URL when we call a HTTP-based XML-RPC responder from Jabber, this time we need to specify a JID when calling a Jabber-based XML-RPC responder from HTTP. What we do is extend the URL by specifying JID as the path, like this:

  http://localhost:5281/jrpc@localhost/jrpc-server

In this example, the Jabber-RPC responder is connected to Jabber as a client, not a component - you can tell this from the JID by the existence of an @ sign (user@hostname - users (their sessions) are managed by the JSM).

Setting it all up

You need three components to get this working in both directions; the HTTPgate component itself, the http component, and a helper DNS resolver component for when the http component wants to make outgoing HTTP requests. Setting up the latter two components are described in the http component's README. (The helper DNS resolver is identified in the example above by the <dnsrv/> tag).

In the HTTPgate's instantiation call, e.g.:

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

there are three arguments required.

server

This argument specifies the host and port to which the HTTPgate component will connect. You will need a corresponding component instance definition in your jabber.xml configuration file that looks like this:

  <service id='jrpchttp.localhost'>
    <accept>
      <ip>127.0.0.1</ip>
      <secret>secret</secret>
      <port>5701</port>
    </accept>
  </service>
identauth

This is the identity and secret for the component, separated by a colon. The identity refers to the value of the 'id' attribute in the component instance definition, and the secret refers to the value of the <secret/> tag.

httpcomp

This is used to specify the name of the http component, and refers to the value of the 'id' attribute in the http component's instance definition in jabber.xml - see earlier for an example of this.

VERSION

Top

early

AUTHOR

Top

DJ Adams

SEE ALSO

Top

Jabber::RPC, Jabber::Connection

Jabber-RPC-HTTPgate documentation Contained in the Jabber-RPC-HTTPgate distribution. 
# 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 $


package Jabber::RPC::HTTPgate;

use strict;
use URI;
use Jabber::Connection;
use Jabber::NS qw(:all);

use vars qw($VERSION);

$VERSION = '0.01';

sub new {

  my $class = shift;
  my %args = @_;
  my $self = {};
  
  $self->{server} = $args{server};
  $self->{httpcomp} = $args{httpcomp};
  ($self->{id}, $self->{pass}) = split(':', $args{identauth});

  $self->{iq_requests} = { id => 1 };

  $self->{c} = new Jabber::Connection(
    server    => $self->{server},
    localname => $self->{id},
    ns        => NS_ACCEPT,
    log       => 1,
  );

  $self->{c}->register_handler('iq',    sub { $self->_reflect(@_) }      );
  $self->{c}->register_handler('iq',    sub { $self->_relay_result(@_) } );
  $self->{c}->register_handler('route', sub { $self->_handle_http(@_) }  );

  $self->{nf} = new Jabber::NodeFactory;

  $self->{c}->connect or die "Oops: ".$self->{c}->lastError;
  $self->{c}->auth($self->{pass});

  bless $self => $class;
  return $self;

}

sub start {

  my $self = shift;
  $self->{c}->start;

}



sub _reflect {

  my $self = shift;
  my $node = shift;

  # Ignore irrelevant packets. What we want is
  # an IQ-set with a jabber:iq:rpc qualified NS
  return unless $node->attr('type') eq IQ_SET
            and my $query = $node->getTag('query', NS_RPC);

  my $request = $query->getTag('methodCall')->toStr;
# my $request = $node->getTag('query', NS_RPC)->getTag('methodCall')->toStr;

  # We need to create a route packet to the http component
  # that looks like this:
  # 
  # <route type='request' to='http' from='id@component'>
  #   <http type='post' to='www.server.com' port='80' path='/RPC2'>
  #     <body>
  #     the payload
  #     </body>
  #   </http>
  # </route>

  # Store the request addresses
  # (we want to refer to this in handle_response())
  $self->{iq_requests}->{++$self->{iq_requests}->{id}} = {
                                 'from' => $node->attr('from'),
                                 'to'   => $node->attr('to'),
                                 'id'   => $node->attr('id'),
                               };

  my $route = $self->{nf}->newNode('route');
  $route->attr('type', 'request');
  $route->attr('to', $self->{httpcomp});
  $route->attr('from', join('@', $self->{iq_requests}->{id}, $self->{id}));

  # Resource should contain the URL
  my (undef, undef, $r) = _parseJID($node->attr('to'));

  # Split up URL
  my $uri = new URI($r);

  my $http = $route->insertTag('http');
  $http->attr('type', 'post');
  $http->attr('to', $uri->host);
  $http->attr('port', $uri->port) if $uri->port;
  $http->attr('path', $uri->path) if $uri->path;

  # Insert the payload
  $http->insertTag('body')->rawdata($request);

  # Send it along to the http component
  $self->{c}->send($route);

}


sub _relay_result {

  my $self = shift;

  # Relaying the result of a JRPC IQ, via the http
  # component. We need to generate a routed packet
  # that looks like this:
  #
  # <route type="result" to="hashid@http">
  #  <http status="123 Foo">
  #   <head Abc="def"/>
  #   <body>my content</body>
  #  </http>
  # </route>

  my $node = shift;

  # Ignore irrelevant packets. What we
  # want is an IQ result with a NS_JRPC-qualified <query/>
  return unless ($node->attr('type') eq IQ_RESULT
             or $node->attr('type') eq IQ_ERROR)
            and my $query = $node->getTag('query', NS_RPC);
  
  # The resource on the 'to' is the http id
  # to send back to
  (undef, undef, my $httpid) = _parseJID($node->attr('to')); 

  # Create route to send HTTP result back
  my $route = $self->{nf}->newNode('route');
  $route->attr('type', 'result');
  $route->attr('to', $httpid);
  $route->attr('from', $self->{id});

  # Add http element
  my $http = $route->insertTag('http');

  # We need to reflect any IQ-related error
  # (e.g. 502 Internal Timeout) - how ...? 
  # As the HTTP status? Hmmm.
  if ($node->attr('type') eq IQ_ERROR) {
    my $error = $node->getTag('error');
    $http->attr('status', join(' ', $error->attr('code'), $error->data));
  }
  else {
    $http->attr('status', '200 OK');
  }

  # Copy the payload from the IQ
  my $payload = $query->getTag('')->toStr; # usually methodResponse but will
                                           # be methodCall when type='error'

  # Add some headers
  my $header;
  $header = $http->insertTag('head');
  $header->attr('Content-type', 'text/xml');
  $header = $http->insertTag('head');
  $header->attr('Content-length', length($payload));

  $http->insertTag('body')->rawdata($payload);

  $self->{c}->send($route);

}


sub _handle_http {

  my $self = shift;
  my $node = shift;

  # Ignore everything except from the http component
  my (undef, $sending_host, undef) = _parseJID($node->attr('from'));
  return unless $sending_host eq $self->{httpcomp};

  # Either it's a request or a result:
  # A request: an incoming HTTP call to be reflected
  #            to a Jabber-component/client based responder
  # A result:  the result of our making an HTTP call in 
  #            a Jabber-to-HTTP reflection

  if ($node->attr('type') eq 'request') { $self->_handle_http_request($node) }
  if ($node->attr('type') eq 'result')  { $self->_handle_http_result($node) }

  return;

}

sub _handle_http_request {

  my $self = shift;
  my $node = shift;

  # Request will look like this:
  # <route type="request" to="component" from="hashid@http">
  #  <http type="post" path="/foo.xml">
  #   <head header="val"/>
  #   <body var="val">foo</body>
  #  </http>
  # </route>

  my $http = $node->getTag('http');

  # Ignore non-POST requests
  return unless $http->attr('type') eq 'post';

  # Get path - this is the JID of the Jabber-RPC responder
  my $jid = $http->attr('path');
  $jid =~ s|^\/||;  # must remove initial slash
  
  # Get the payload
  my $payload = $http->getTag('body')->getTag('methodCall')->toStr;

  # Construct the request IQ 
  my $iq = $self->{nf}->newNode('iq');
  $iq->attr('type', IQ_SET);
  $iq->attr('from', join('/', $self->{id}, $node->attr('from')));
  $iq->attr('to', $jid);
  $iq->insertTag('query', NS_RPC)->rawdata($payload);

  $self->{c}->send($iq);

}


sub _handle_http_result {

  my $self = shift;
  my $node = shift;

  # Set up response
  my $response = $self->{nf}->newNode('iq');

  # Get the key for our request hash - it's in
  # the user part of the JID
  my ($u, undef, undef) = _parseJID($node->attr('to'));

  # Address the response
  $response->attr('to', $self->{iq_requests}->{$u}->{from});
  $response->attr('from', $self->{iq_requests}->{$u}->{to});

  # Respond with the id from the request
  $response->attr('id', $self->{iq_requests}->{$u}->{id});
  
  # Reflect the type (result|error) from the route
  # into the returning IQ
  $response->attr('type', $node->attr('type'));
  if ($response->attr('type') eq IQ_ERROR) {
    my $error = $response->insertTag('error');
    $error->attr('code', '502');
    $error->data('Remote Server Error');
  }

  # Transfer the payload from the result to our IQ
  # (If it's an error, the HTTP component returns the
  # original payload. This is nice.)
  my $query = $response->insertTag('query', NS_RPC);
  my $payload = $node->getTag('http')->getTag('body')->getTag('');
  $query->rawdata($payload->toStr);

  $self->{c}->send($response);

}


sub _parseJID {

  my $jid = shift;
  my ($user, $host, $resource, $rest);

  # Is there a username part? (an @ before any /)
  if ($jid =~ m[^[^\/]+@]) {
    ($user, $rest) = split("@", $jid, 2);
  }
  else {
    $rest = $jid;
  }

  ($host, $resource) = split('/', $rest, 2);

  return ($user, $host, $resource);

}


1;