Stream Handler

Blather was built to work as a standalone DSL or to be included in another project to allow easy access to an XMPP connection. At the heart of this is the Stream Handler.

The Stream Handler is a subclass of EventMachine::Connection and so acts as the gateway to the wire. The stream should be started using either Blather::Stream::Client.start or Blather::Stream::Component.start. From here the Stream Handler will start the connection to the server.

Client Connection

XMPP requires a client connection authenticate via SASL. Then bind to a resource and establish a session. This is all handled automatically by the Stream Handler.

Blather supports three types of SASL authentication: Digest-MD5, Plain, and Anonymous. The stream will try each authentication type in turn until one is successful or there is nothing left to try. Anonymous will be used automatically if the stream is sent a JID with an empty node (note it must be empty, not nil).

If the stream is given a JID without a resource it will request one from the server and send it back (via client.jid=) if a resource is successfully bound.

Once the session has been established the Stream Handler will call client.post_init to notify the client that the stream is ready to go.

Component Connection

An XMPP Component connection is much simpler to establish. It requires a handshake with a shared secret between the component and the server. Once the handshake has been successfully completed client.post_init will be called to notify the component that the stream is ready.