view release on metacpan or  search on metacpan

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

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

=item 4 HTTP requester

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

=item 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.

=item 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.

=item 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. 

=item 8 Jabber-RPC requester

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

=head2 Some examples

=over 4

=item 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
I<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. 

=item 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 I<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).

=back

=head2 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.

=over 4

=item server

This argument specifies the host and port to which the
HTTPgate component will connect. You will need a corresponding