Action Messenger – Instant Messaging made simple

Action Messenger is a framework for designing and testing application components which both send and receive instant messages. It was heavily based on Action Mailer which does the same thing for email.

Installation

Installation is as usual: either install from the gem or drop into the 'vendor' directory of your Rails application. Somewhere (probably in 'config/environment.rb') you will want to add the following:

require 'action_messenger'

Configuring the messenger

Configuration of messengers works in a similar fashion to configuration of databases in Active Record. The default location of the configuration file is 'config/messenger.yml'.

The simplest configuration is to use a single messenger.

default:
  type: xmpp4r
  jid: user@example.com/resource
  password: secret

Multiple messengers can be defined in this fashion, however most applications should only need one, and by default the messenger named 'default' is the one which is used.

The configuration file can contain ERB fragments too, in case more complicated decisions need to be made when configuring the messenger.

Sending messages

The following is the simplest example of a class able to send a message:

class AlarmClock < ActionMessenger::Base
  def wake_up(user)
    recipients user
    body       'Wake up!'
  end
end

As with Action Mailer, sending or creating a message does not involve calling your method directly:

AlarmClock.create_wake_up("someone@example.com") # => Message object for unit tests
AlarmClock.send_wake_up("someone@example.com")   # sends the message

Receiving messages

To receive messages, implement a public instance method called receive that takes an ActionMessenger::Message object as its single parameter. They also need to register to receive messages by calling receives_messages on the class.

A simple example:

class MessageLogger < ActionMessenger::Base
  receives_messages

  def receive(message)
    MessageLogEntry.create(:sender => message.from
                           :body   => message.body)
  end
end

This will work as you expect if you are using FastCGI, Mongrel or some other method of running the server that doesn't run Ruby once per invocation (notably, CGI will not work.) If you use a cluster of FastCGI or Mongrel instances, you may need to make the resources unique for each one. If this becomes a problem it can be simplified in a future version.

Dependencies

At present, the only dependency is XMPP4R, and this dependency is currently included in this bundle. XMPP4R is licenced under the Ruby licence; a copy of this licence can be found in vendor/xmpp4r/LICENSE.

License

Action Messenger is released under the MIT license. A copy of this licence can be found in the file named COPYING.

Support

The homepage is currently at: trypticon.org/software/actionmessenger/

Contact details can be found at the homepage.

Action Messenger is currently extremely experimental software, and there is no guarantee that it will be stable in the near future. However, if people do find bugs I will endeavour to fix them, and I am accepting feature requests that aren't already listed on the homepage.