/strophejs-plugin-rpc

Jabber-RPC Module

A strophe plugin for Jabber-RPC extension (XEP-0009).

See the XEP abstract :

This specification defines an XMPP protocol extension for transporting XML-RPC encoded requests and responses between two XMPP entities. The protocol supports all syntax and semantics of XML-RPC except that it uses XMPP instead of HTTP as the underlying transport.

This plugin does not aim at managing your flow of RPC. It is a simple helper to send and handle remote requests between two XMPP nodes.

Usage

Just link the rpc plugin below the strophe library in your HTML head section:

<head>
<!-- ... -->
<script type="text/javascript" src="strophe.min.js"></script>
<script type="text/javascript" src="strophe.rpc.js"></script>
<!-- ... -->
</head>

It's preferable to also use the service discovery plugin to respond correctly to disco#info requests. You can download it and add it as follow :

<head>
<!-- ... -->
<script type="text/javascript" src="strophe.min.js"></script>
<script type="text/javascript" src="strophe.disco.js"></script>
<script type="text/javascript" src="strophe.rpc.js"></script>
<!-- ... -->
</head>

API

The plugin prototype is accessible from the connection.rpc variable

Send an RPC

There are four functions to send RPC :

  • sendRequest(id, to, method, params)
    • method is the string name of the method to call
    • params is an array of parameters to send
  • sendResponse(id, to, result)
    • result is the object to send as the result of the request
  • sendError(id, to, code, message)
    • code is the number of the error
    • message is the message describing the error
  • sendXMLElement(id, to, xml)
    • xml is the XML Element that will be sent (whether it is properly formed or not)

The parameters id and to are respectively the id of the request and the the jid of the recipient.

Handle incoming RPCs

It is possible to handle incoming RPCs using the functions :

  • addRequestHandler
  • addResponseHandler
  • addXMLHandler

The handlers you pass to these functions take different parameters :

var responseHandler = function(id, from, result, error) {
	// error is a boolean
	// it is true if the response was an error message
	if (error === true) { ... }
	else { ... }
}
connection.rpc.addResponseHandler(responseHandler);

var requestHandler = function(id, from, method, parameters) { ... }
connection.rpc.addRequestHandler(requestHandler);

var xmlHandler = function(xml) { ... }
connection.rpc.addXMLHandler(xmlHandler)

Note that the parser of this module won't throw any exception. However result, method and parameters will be set as null if the incoming message is not XML-RPC compliant.

Whitelist

By default, this plugin will accept RPC from everyone. However, it is possible to use a whitelist of JID to filter incoming RPCs.

Use the function addJidToWhiteList to accept JIDs. Note that it is possible to use a wildcard for the node or the domain.

Examples :

connection.rpc.addJidToWhiteList("me@jabber.org");
connection.rpc.addJidToWhiteList(["*@jabber.org", "me@*"]);
connection.rpc.addJidToWhiteList("*@*");

Tests & specs

I use the node module buster for the tests. Install it and use it as follow :

$ npm install buster
$ buster server

Open a browser and navigate to http://localhost:1111 and capture the browser. Then you can run the tests:

$  buster test --browser