XMPP4R
Introduction
XMPP4R is a XMPP/Jabber library for Ruby. Its goal is to provide a complete framework to develop Jabber-related applications or scripts in Ruby.
Features
- Fully object-oriented (well, it's Ruby ;)
- Aims at being XMPP compliant
- Threaded
- Well unit-tested and documented code
- Uses well-known and well-tested software like REXML, instead of reinventing the wheel
- Very easy to extend
- Released under Ruby's license, which is compatible with the GNU GPL via an explicit dual-licensing clause.
Current status
You can basically do everything you want with XMPP4R, especially if you are willing to hack some code in the library itself. All the base classes can be considered stable, and their interface shouldn't change in the future.
The features which are currently implemented are:
| Feature | 0.3 release | 0.3.1 release | 0.3.2 release | SVN |
|---|---|---|---|---|
| TLS support | Basic | Basic | Basic | Basic |
| SASL authentication | Basic | Basic & fixed | Basic & fixed | Basic & fixed |
| XMPP stanza processing | Present | Present & fixed | Fixed & enhanced | Fixed & enhanced |
| XMPP stanza id generating | Present | Present | Present | Present |
| JID processing | Rewritten | Rewritten | Rewritten | Rewritten |
| message processing | Complete | Complete | Complete | Complete |
| presence processing | Complete | Complete | Complete | Complete |
| iq processing | Present | Present | Present | Present |
| XMPP stanza error responses | Present | Present | Present | Present |
| Client SRV lookup capability | Present | Present | Present | Present |
| Client digest authentication | Complete | Complete | Complete | Complete |
| Component digest authentication | Complete | Complete | Complete | Complete |
| Roster protocol | Complete | Complete | Complete | Complete |
| Roster helper | Present | Present | Present | Present |
| vCard (JEP-0054) handling | Complete | Complete | Complete | Complete |
| vCard helper | Present | Present & fixed | Present & fixed | Present & fixed |
| Software Version (JEP-0092) protocol | Complete | Complete | Complete | Complete |
| Software Version (JEP-0092) helper | Complete | Complete | Complete | Complete |
| Service Discovery (JEP-0030) protocol | Complete | Complete | Complete | Complete |
| jabber:x namespaces support | Present | Present | Present | Present |
| Roster Item Exchange (JEP-0144) protocol | Present | Present | Present | Present |
| Delayed Delivery (JEP-0091) protocol | Present | Present | Present | Present |
| MUC (JEP-0045) protocol | Basic | Basic | Basic | Basic |
| Multi-User Chat helpers | Basic | Basic | Basic | Basic |
| Data Forms support | Basic | Basic | Basic | Basic |
| Stream Initiation (JEP-0095) support | Basic | Basic | Basic | Basic |
| SOCKS5 Bytestreams (JEP-0065) support | Basic | Basic | Basic | Basic |
| SOCKS5 Bytestreams helper | Basic | Improved | Improved | Improved |
| In-Band Bytestreams helper | Basic | Basic | Basic | Basic |
| File Transfer helper | Basic | Basic & fixed | Basic & fixed | Basic & fixed |
| Jabber RPC (JEP-0009) support | Basic | Basic | ||
| HTTP Binding (JEP-0124) support | Basic | Basic | ||
| Publish-Subscribe (JEP-0060) support | Experimental | Experimental |
A lot of examples are shipped with XMPP4R (see /usr/share/doc/xmpp4r/examples/ or /usr/local/share/doc/xmpp4r/examples/, depending on how you installed XMPP4R), including:
| Filename | Description |
|---|---|
| Basic examples | |
| basic/change_password.rb | Change the password of an account on the command-line |
| basic/client.rb | console-only jabber client |
| basic/component.rb | very basic jabber component |
| basic/echo_threaded.rb | Auto-responder that just repeats what you say to it. This version uses thread. |
| basic/echo_nonthreaded.rb | Auto-responder that just repeats what you say to it. This version waits for calls to process() to process messages. |
| basic/jabbersend.rb | Sends a message to a specified JID. |
| basic/mass_sender.rb | Sends a message to a list of JIDs. |
| basic/mucinfo.rb | Retrieve a list of rooms from a MUC component. |
| basic/mucsimplebot.rb | Demonstration of SimpleMUCClient usage. |
| basic/register.rb | Register a new user account on a server. |
| basic/remove_registration.rb | Remove registration on a server. |
| basic/roster.rb | Get a user's roster. |
| basic/rosterprint.rb | Print your roster by groups |
| basic/rosterrename.rb | Rename an item in your roster |
| basic/rosterwatch.rb | Demonstration of Roster and vCard helpers |
| basic/send_vcard.rb | Modify your vCard with command-line arguments |
| basic/versionbot.rb | A bot that get your contacts' jabber:iq:version. |
| More complex examples | |
| advanced/adventure/ | A MUC-based adventure game. |
| advanced/fileserve.rb | Bot accepting and initiating file-transfers |
| advanced/getonline.rb | Use admin superpowers to get the list of online users. |
| advanced/gtkmucclient.rb | Simple Multi-User Chat client with Gtk+ interface |
| advanced/migrate.rb | Help migrate from one JID to another. |
| advanced/minimuc.rb | A lightweight and very basic MUC implementation. |
| advanced/recvfile.rb | Receive files over file transfer |
| advanced/rosterdiscovery.rb | Expose your Roster using service discovery. |
| advanced/send_vcard.rb | Retrieve, print & send your vCard |
| advanced/sendfile.rb | Send a file over file transfer |
| advanced/shellmgr/ | Run shell commands over Jabber. |
| advanced/versionbot.rb | Ask online users for their version info |
| Buggy examples (they just need more attention ;) | |
| buggy/jabber2jabber/ | A Jabber to Jabber gateway. |
| buggy/jud.rb | A complete Jabber User Directory with MySQL support. |
| buggy/miniedgar_* | An edgar-like bot. |
Related Projects
Alternative Jabber libraries for Ruby
- Jabber4R (projet homepage at Rubyforge): Not maintained anymore. XMPP4R is slightly based on, but far more advanced than Jabber4R.
- Net::XMPP: was a Google SoC 2005 project by Yuki Mitsui (aka Silphire). He later contributed code to XMPP4R resulting in TLS & SASL support.
Libraries on top of XMPP4R
- Jabber::Simple: An extremely easy-to-use Jabber client library.
- Action Messenger: a Ruby on Rails convenience framework like Action Mailer, only for instant messaging.
Applications
- iBota is a plugin-capable bot using XMPP4R by Vojtech Vobr. A homepage doesn't exist yet, but you may browse or check out the source code.
- RbIRC-t is an IRC gateway based upon XMPP4R. It is already documented and has features, but needs some refactorization for more flexibility. It will be released once this has been done. RbIRC-t is hosted within XMPP4R: Source Browser & Repository.
- Jabberhole is for Jabber what MouseHole is for the Web. It serves as a connection proxy and loaded scripts may rewrite trespassing XMPP stanzas instead of web pages. It is experimental and old, but feel free to have fun with it: Source Browser & Repository.
- rabber was born out of the idea to have a Jabber client utilizing Gtk and XMPP4R. The project is still before its infancy due to lack of time and knowledge of Gtk. A SVN repository exists, contact Lars Strojny if you want to help.
- Jabber Disk is a very cool service, providing online file storage via Jabber. Look at the project homepage or just try it at disk.jabbim.cz.
Download
Releases are available here: http://download.gna.org/xmpp4r/.
Latest release: xmpp4r-0.3.2.tgz.
You can get the latest version from SVN using svn co svn://svn.gna.org/svn/xmpp4r/trunk/xmpp4r or download a daily snapshot from http://svn.gna.org/daily/xmpp4r-snapshot.tar.gz.
The source code is browseable here.
There's also a Debian package. We hope it will be included in Debian soon, but you can install it by putting deb http://download.gna.org/xmpp4r/debian ./ to you /etc/apt/sources.list and then apt-get install libxmpp4r-ruby
Installation Instructions
Untar the archive and run ./setup.rb
Developers
Mailing Lists
xmpp4r-devel at gna dot org is a mailing list for development and general discussion.
- xmpp4r-devel Info Page (to subscribe/unsubscribe, etc)
- xmpp4r-devel archives
SVN and CVS commits are sent to xmpp4r-commits at gna dot org. Discussion about them takes place on xmpp4r-devel.
- xmpp4r-commits Info Page (to subscribe/unsubscribe, etc)
- xmpp4r-commits archives
When reporting bugs, please provide as much information as possible:
- XMPP4R version or SVN revision
- Use Jabber::debug = true but remove any sensitive information
- Describe your environment (Ruby version, OS, server software)
- Cool hackers send test cases
(Sort of) Developer Documentation
Development takes place on the GNA project page. Don't hesitate to post feature requests, bugs or patches.
XMPP4R is written in Ruby. If you don't know this language yet, continue to ignore it. Learning it will make you realize what you missed until now, and you might run into severe problems (depression, etc).
Source code is browseable here.
You can get the source code from SVN using svn co svn://svn.gna.org/svn/xmpp4r/trunk/xmpp4r
The RDOC source code documentation is browseable here. It might not be update to date (but we try hard to make it be). You can generate your own using rake rdoc
Famundo Dev Blog has a series of introductionary articles about XMPP4R:
- Ruby and XMPP/Jabber - a Multi Posts Series, Part 1
- Ruby and XMPP/Jabber Part 2: Logging in and sending simple messages
- Ruby and XMPP/Jabber Part 3: Adding html to the messages
Another two-part Tutorial can be found at Ruby Fleebie:
A german tutorial is available at the BSD-Crew Wiki: Jabberbots mit XMPP4R