Skip to content
This repository

Essential XMPP middleware for Node.js.

branch: master

Merge pull request #8 from Daniel15/patch-1

Add link to Entity Capabilities middleware
latest commit 7f091d3948
Jared Hanson authored
README.md

Junction

Junction is an extensible XMPP middleware layer for Node. Highly scalable applications can be constructed by assembling sets of "plugins" known as middleware and filters. Middleware process incoming stanzas, while filters process outgoing stanzas.

This architecture has been proven effective by Connect, which provides HTTP middleware. Junction adopts this approach, repurposing it for use in XMPP, allowing XMPP applications to be built quickly and easily, while harnessing the powerful patterns familiar to Node.js developers.

Installation

$ npm install junction

Usage

Create an Application

To create a new application, simply invoke junction(). Use the built in message and presence parsing middleware to parse common stanzas.

var app = junction()
  .use(junction.messageParser())
  .use(junction.presenceParser());

Handle Stanzas

Use additional middleware to define your application's behavior. In this example, the built in message middleware is used to handle chat messages. Anytime a message is received, we send a greeting and echo the message body.

app.use(junction.message(function(handler) {
  handler.on('chat', function(stanza) {
    var msg = new Message(stanza.from);
    msg.c('body', {}).t('Hello ' + stanza.from + '!\n\n' +
                        'You said: ' + stanza.body);
    stanza.connection.send(msg);
  });
}));

Junction provides bundled middleware to handle core XMPP functionality. Additional middleware and higher-level frameworks are available as separate modules.

Trailing Middleware

Conclude the app by using the typical trailing middleware:

app.use(junction.serviceUnavailable())
   .use(junction.errorHandler());

serviceUnavailable middleware responds with a service-unavailable stanza error when other XMPP entities send the application a request that it doesn't support. This is recommended for well-behaved XMPP applications.

errorHandler middleware will respond with stanza errors when the application encounters an error condition.

These middleware should be used last in the stack, ensuring that other middleware take priority.

Connect to XMPP Network

With the app configured, connect to the XMPP network.

app.connect({ jid: 'user@jabber.org', password: 's3cr3t' }).on('online', function() {
  console.log('connected as: ' + this.jid);
  this.send(new Presence());
});

Junction uses node-xmpp for the underlying connection, allowing apps to connect as clients, components, or any other supported connection type.

Frameworks

At its core, XMPP is a protocol that allows structured data to be exchanged in real-time between entities on the network. While typically used for instant messaging and presence, numerous XMPP extension protocols (known as XEPs) are available which make XMPP broadly applicable to non-IM applications.

These XEPs build on XMPP's core, while defining their own higher-level semantics. Junction-based frameworks implement support for these extensions, building on essential middleware and enhancing it with tooling designed to support development of applications making use of the XEP.

Framework Description
Disco Service Discovery (XEP-0030) framework.
PubSub Publish-Subscribe (XEP-0060) framework.

Middleware

Additional middleware is available to parse non-core extension elements commonly found in stanzas. Some middleware implement complete support for simple XEPs that don't justify the need for a full-fledged framework.

Middleware Description
junction-attention Attention (XEP-0224) middleware.
junction-delay Delayed Delivery (XEP-0203) middleware.
junction-lastactivity Last Activity (XEP-0012) middleware.
junction-legacy-delay Legacy Delayed Delivery (XEP-0091) middleware.
junction-legacy-time Legacy Entity Time (XEP-0090) middleware.
junction-nickname User Nickname (XEP-0172) middleware.
junction-ping XMPP Ping (XEP-0199) middleware.
junction-softwareversion Software Version (XEP-0092) middleware.
junction-time Entity Time (XEP-0202) middleware.
junction-caps Entity Capabilities (XEP-0115) middleware.

Tests

$ npm install --dev
$ make test

Build Status

Credits

License

(The MIT License)

Copyright (c) 2011 Jared Hanson

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Something went wrong with that request. Please try again.