pk-merb_messenger 0.0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Michael Klishin
+
+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.

data/README

@@ -0,0 +1,270 @@
+merb_messenger
+==============
+
+A plugin for the Merb framework that provides
+messaging and notifications functionality.
+
+The goal is to create a simple transport agnostic
+library that can be used for Jabber, Growl, HTTP,
+mail and other notifications with minimal effort
+in web controllers.
+
+Actors
+==============
+
+Core actors of this library are messaging controllers
+and transports. Messaging controllers are called
+from web controllers that handle incoming requests,
+render message templates, do messaging-related
+filtering and pass the result to transports to deliver.
+
+Note that messaging controllers share rendering and
+filtering code with Merb core's AbstractController so
+no wheel is invented.
+
+Transports and possible use cases
+=====================================
+
+What transports do is up to specific implementation:
+
+* Jabber transport will deliver messages over XMPP
+* AMQP transport will talk to AMQP broker like RabbitMQ or ZeroMQ
+* mail transport will use SMTP or sendmail to send emails
+* HTTP POST transport will post data over HTTP ("web hooks")
+* Specific HTTP transport may post to Facebook, Twitter, LiveJournal or whatever it may be
+* IRC transport will flood some IRC channel.
+* SMS transport will deliver SMS one way or another
+* XMP-RPC transport will call some WS-* deathstars
+* Some futuristic crazy transport will send Rubinius VM bytecode
+  over the wire to be executed on the other end
+
+
+How to use this prototype
+==============================
+
+Messaging controllers are used from web controllers
+(that handle requests) and can render templates,
+have filters and all that. Transports can be used
+directly in models and not supposed to render
+(at least at this point in evolution of merb messenger).
+
+Transports must be required explicitly at this point. Do it
+in init.rb or add config/messengers.rb and load it from init.rb,
+and require transport file there. This is because otherwise
+lazy loading can only be accomplished using Kernel#autoload
+which some people do not like (for instance, it is not thread
+safe in MRI).
+
+Say we have a group journal/blog and we want to be notified
+on updates using Jabber. Our web controller action may
+look like this:
+
+class Entries < Application
+  def create(entry)
+    @entry = Entry.new(entry)
+    if @entry.save
+      run_later do
+        JournalMessenger.dispatch(:create, self, :entry => @entry)
+      end
+      redirect url(:entries)
+    else
+      @entries = Entry.all
+      render :index
+    end
+  end
+end
+
+As you can see, messaging controller is explicitly called from web controller
+using dispatch method. That method takes an action as a symbol, web controller
+instance (to have access to request parameters and session) and a Hash of extra
+options you'd like to pass to it.
+
+Now lets look at our messenger:
+
+class JournalMessenger < Merb::MessagingController
+  delivery_options :lan_growl,
+                   :notification => "journal notification",
+                   :title        => "New journal entry posted"
+                   
+  delivery_options :remote,
+                   :title        => "New journal entry posted",
+                   :to           => ["app.notifications@jabber.org"],
+                   :message_type => :chat
+  
+  def create(options)
+    # render the template in app/messengers/views/journal/create.text.erb
+    body = render(:index)
+
+    # deliver using XMPP
+    # transport is called :remote
+    # in the application
+    deliver :remote,    :body => body
+    # deliver using Growl transport
+    # that is called :lan_growl across
+    # the app
+    deliver :lan_growl, :body => body
+  end
+end
+
+Every messenger action takes a hash of options that includes web controller
+parameters and additional options you passed on dispatch.
+
+Every messenger uses +deliver+ method to deliver notifications instantly
+and (in the future) +queue+ method to stack a notification in a queue to
+be delivered later. Queueing functionality will be 100% ORM agnostic.
+
+This plugin is all about connecting your web controllers and transports.
+It supposed to be generic. Because message transports are very
+different, it's up to particular transport what
+options delivery and queue methods would take.
+
+To eliminate the need to constantly duplicate some common options (like "from",
+"title" and similar), Merb messenger lets you set them up messenger-wide:
+
+  delivery_options :remote,
+                   :title        => "Journal event",
+                   :to           => ["app.notifications@jabber.org"],
+                   :message_type => :chat
+
+Above we say that all messages that go via transport called "remote"
+(that is XMPP transport in this example) use title "Journal event",
+delivered to "app.notifications@jabber.org" and use message type
+"chat".
+
++deliver+ method's options are merged with class-wide delivery options
+before they are passed on to transport. Obviously, former take
+precedence over the latter.
+
+Implementing transports
+========================
+
+Transport API is simple and may be as little work as implementing a
+single method, deliver. Some transports that need to establish connection and
+handle disconnection may add a few more methods: connect, reconnect, disconnect.
+Those providing queuing functionality may add queue method that acts as deliver
+but does not do immediate delivery.
+
+Here is a Jabber transport implementation that uses xmpp4r:
+require 'xmpp4r/client'
+
+module Merb
+  module Messenger
+    class Xmpp4rTransport
+      include ::Jabber
+
+      class_inheritable_accessor :_default_delivery_options
+      self._default_delivery_options = Mash.new(:message_type => :chat)
+
+      def self.delivery_options(options)
+        self._default_delivery_options = options
+      end
+
+      attr_reader :transport
+
+      def initialize(options)
+        @transport = Client.new(options[:jid])
+        @transport.connect
+        
+        @transport.auth(options[:password])
+      end
+
+      def connect
+        self.transport.connect
+      end
+
+      def disconnect
+        self.transport.close
+      end
+
+      def deliver(options = {})
+        options = _default_delivery_options.merge(options)
+        
+        m = Message.new(options[:to], options[:body])
+        
+        m.set_subject(options[:subject]) if options[:subject]
+        m.set_subject(options[:id])      if options[:id]
+        m.set_type(options[:message_type] || :normal)
+        
+        self.transport.send(m)
+      end
+    end
+  end
+end
+
+
+Setting transports up
+=======================
+
+Transports are usually set up before Merb loads your application
+classes, but it's obviously neither a requirement, nor a convention.
+It just makes messaging classes loaded before code that uses them loads.
+
+To set up a transport you use
+Merb::Messenger.setup_transport method that takes transport name
+(can be anything, pick how you'd like to address that transport in your
+application), transport type alias (:growl, :xmpp4r, can be anything people
+already written transports for) and a Hash of options.
+
+Since transports are so different by nature (Growl has host, port, password,
+notifications list and application name options, XMPP usually has jid, server,
+port, SASL/TLS options and password, smpt transport would have SMTP server
+settings, sendmail would have a sendmail path, etc), possible options are
+up to transport authors.
+
+Merb::BootLoader.before_app_loads do
+  Merb::Messenger.setup_transport(:lan_growl, :growl, {
+    :application   => "merbpack",
+    :notifications => ["journal_notification"]
+  })
+end
+
+You can use transports directly if you need to. For instance,
+you can set up a Jabber transport that's gonna notify you
+when Merb worker is shut down or restarted. This way you
+can be notified on crashes and application deployments.
+
+Here is an example:
+
+Merb::BootLoader.after_app_loads do
+  im = Merb::MessagingController.message_transport :lan_growl
+
+  im.deliver({
+    :title        => "MerbPack presence",
+    :body         => "MerbPack agent is back online",
+    :notification => "presence notification"
+  })
+end
+
+
+Merb::BootLoader.before_master_shutdown do
+  Merb.logger.info "MerbPack agent is going offline..."
+  im = Merb::MessagingController.message_transport :lan_growl
+
+  im.deliver({
+    :title        => "MerbPack presence",
+    :body         => "MerbPack agent is about to shut down",
+    :notification => "presence notification"
+  })
+end
+
+Merb::BootLoader.before_worker_shutdown do
+  Merb.logger.info "Shutting down worker..."
+
+  Merb::MessagingController.message_transport(:remote).disconnect
+end
+
+
+Here we use two transports named :lan_growl and :remote. First uses
+Growl transport in local area network, and second is a Jabber transport
+that sends XMPP notifications.
+
+We use them to notify people when application goes down and comes back
+up online.
+
+The Future
+===================
+
+Merb messenger will be part of Merb 1.1 in early 2009. The Holy Grails of
+this plugin is to provide simple generic interface for messaging of all
+kinds: from Jabber and mail notifications to talking to AMQP brokers
+like RabbitMQ or ZeroMQ, doing "web hooks" and so forth.

data/Rakefile

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+
+require 'merb-core'
+require 'merb-core/tasks/merb'
+
+GEM_NAME    = "merb_messenger"
+GEM_VERSION = "0.0.1"
+AUTHOR      = "Michael Klishin"
+EMAIL       = "michael@novemberain.com"
+HOMEPAGE    = "http://merbivore.com/"
+SUMMARY     = "Merb plugin that provides messaging/notifications functionality: from email and XMPP to AMPQ and beyond."
+
+spec = Gem::Specification.new do |s|
+  s.rubyforge_project = 'merb'
+  s.name              = GEM_NAME
+  s.version           = GEM_VERSION
+  s.platform          = Gem::Platform::RUBY
+  s.has_rdoc          = false
+  s.extra_rdoc_files  = ["README", "LICENSE", 'TODO']
+  s.summary           = SUMMARY
+  s.description       = SUMMARY
+  s.author            = AUTHOR
+  s.email             = EMAIL
+  s.homepage          = HOMEPAGE
+  s.add_dependency('merb-core', '>= 1.1')
+  s.require_path      = 'lib'
+  s.files             = %w(LICENSE README Rakefile TODO) + Dir.glob("{lib,spec}/**/*")
+  
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "install the plugin as a gem"
+task :install do
+  Merb::RakeHelper.install(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Uninstall the gem"
+task :uninstall do
+  Merb::RakeHelper.uninstall(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Create a gemspec file"
+task :gemspec do
+  File.open("#{GEM_NAME}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end

data/TODO

@@ -0,0 +1,9 @@
+* Finally put spec suite I have online.
+* Add more spec examples.
+* Add event more spec examples.
+* F*cking spec examples!!
+* Mail transport.
+* HTTP transport (should use Tony Arcieri's FastHTTP library).
+* Queueing functionality for existing transports.
+* AMQP integration.
+* Extensions for RPC, WS-* deathstars and the rest of existing ecosystem.

data/lib/merb_messenger.rb

@@ -0,0 +1,43 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+# make sure we're running inside Merb
+if defined?(Merb::Plugins)
+  # Register path for messengers under app/messengers
+  Merb.push_path(:messenger, Merb.root / "app"/ "messengers")
+  
+  require "merb_messenger/messaging_controller"
+  require "merb_messenger/messaging_mixin"
+  
+  module Merb
+    module Messenger
+      @@test_deliveries = Hash.new([])
+
+      def self.clean_test_deliveries!
+        @@test_deliveries = Hash.new([])
+      end
+      
+      def self.test_deliveries
+        @@test_deliveries
+      end
+
+      def setup_transport(name, type, options)
+        begin
+          # Try to load custom Transports from project/merb/merb_messenger/transports
+          require Merb.root / 'merb' / 'merb_messenger' / 'transports' / type.to_s
+        rescue LoadError => e
+          # Try to load bundled Transports
+          require "merb_messenger/transports/#{type.to_s}"
+        end
+        
+        ::Merb::MessagingController.message_transport(name, type, options)
+      end
+
+      module_function :setup_transport
+    end
+  end
+
+  Merb::Plugins.config[:merb_messenger] = {
+  }
+    
+  Merb::Plugins.add_rakefiles "merb_messenger/merbtasks"
+end

data/lib/merb_messenger/merbtasks.rb

@@ -0,0 +1,6 @@
+namespace :merb_messenger do
+  desc "Do something for merb_messenger"
+  task :default do
+    puts "merb_messenger doesn't do anything"
+  end
+end

data/lib/merb_messenger/messaging_controller.rb

@@ -0,0 +1,106 @@
+module Merb
+  class MessagingController < AbstractController
+    #include Merb::Messenger::Transport
+    
+    attr_reader :params, :web_controller
+    
+    class_inheritable_accessor :_message_transports, :_default_delivery_options
+    
+    self._message_transports       = Mash.new
+    self._default_delivery_options = Mash.new
+    
+    cattr_accessor :_subclasses
+    self._subclasses = Set.new
+    
+    
+    render_options :format => :text    
+    
+    def self.subclasses_list
+      _subclasses
+    end
+    
+    def _template_location(action, type = :text, controller = controller_name)
+      "#{controller}/#{action}.#{type}"
+    end
+    
+    def _absolute_template_location(template, type)
+      template.match(/\.#{type.to_s.escape_regexp}$/) ? template : "#{template}.#{type}"
+    end
+    
+    def self.inherited(klass)
+      _subclasses << klass.to_s
+      super
+      
+      klass._template_root ||= Merb.dir_for(:messenger) / "views"
+    end
+    
+    
+    def self.dispatch(message, web_controller, options = {}, msg_options = {})
+      self.new(web_controller, options).__send__(message, msg_options)
+    end
+    
+    def self.message_transport(name = :default, type = nil, options = nil)
+      return self._message_transports[name] if type.blank?
+      
+      klass = Merb::Messenger.const_get("#{type.to_s.camel_case}Transport")
+      t     = klass.new(options)
+      self._message_transports[name] = t
+    end
+    
+    def self.delivery_options(name = :default, value = nil)
+      return self._default_delivery_options[name] unless value
+      self._default_delivery_options[name] = value
+    end
+    
+    
+    
+    def initialize(web_controller, opts = {})
+      @web_controller = web_controller
+      @params         = Mash.new(@web_controller.params.dup)
+      
+      @params.merge!(opts) unless opts.blank?
+      super
+      
+      @content_type   = @web_controller.content_type
+    end
+    
+    def transport
+      self.class._transport
+    end
+    
+    def deliver(client = :default, options = {})
+      opts = (self._default_delivery_options[client] || {}).
+            merge(self.params).
+            merge(options)
+      
+      [opts[:to]].flatten.each do |to|
+        self._message_transports[client].deliver(opts.merge(:to => to))
+      end
+    end
+    
+    def session
+      self.web_controller.request.session rescue {}
+    end
+
+    def request
+      self.web_controller.request
+    end
+    
+    # Mimic the behavior of absolute_url in AbstractController
+    # but use @web_controller.request
+    def url(name, *args)
+      return web_controller.url(name, *args) if web_controller
+      super
+    end
+
+    alias_method :relative_url, :url
+
+    # Mimic the behavior of absolute_url in AbstractController
+    # but use @web_controller.request
+    def absolute_url(name, *args)
+      return web_controller.absolute_url(name, *args) if web_controller
+      super
+    end    
+    
+  end
+end

data/lib/merb_messenger/messaging_mixin.rb

@@ -0,0 +1,7 @@
+module Merb
+  module MessagingMixin
+    
+    
+    
+  end
+end

data/lib/merb_messenger/transports/growl.rb

@@ -0,0 +1,32 @@
+require 'ruby-growl'
+
+module Merb
+  module Messenger
+    class GrowlTransport  
+      class_inheritable_accessor :_default_delivery_options
+      self._default_delivery_options = Mash.new
+
+      def self.delivery_options(options)
+        self._default_delivery_options = options
+      end
+
+      attr_reader :transport
+
+      def initialize(options)
+        @transport = ::Growl.new(options[:host], options[:application], options[:notifications])
+      end
+
+      def connect
+      end
+
+      def disconnect
+      end
+
+      def deliver(options = {})
+        options = _default_delivery_options.merge(options)
+
+        self.transport.notify(options[:notification], options[:title], options[:body])
+      end    
+    end
+  end
+end

data/lib/merb_messenger/transports/mailfactory.rb

@@ -0,0 +1,92 @@
+module Merb
+  module Messenger
+    class MailTransport
+      attr_reader :delivery_strategy, :composition_strategy
+
+      class_inheritable_accessor :_default_delivery_options
+      self._default_delivery_options = Mash.new(:message_type => :chat)
+
+      def self.delivery_options(options)
+        self._default_delivery_options = options
+      end
+
+      def initialize(options)
+        @delivery_strategy    = options[:deliver_with] || :sendmail
+        @composition_strategy = options[:compose_with] || :mailfactory
+      end
+
+      def deliver(options = {})
+        options = _default_delivery_options.merge(options)
+
+        email = case self.composition_strategy
+                when :mailfactory then compose_with_mailfactory(options)
+                when :tmail       then compose_with_tmail(options)
+                when Proc         then self.composition_strategy.call(options)
+                when Class        then compose_with_custom_strategy(options)
+                else
+                  self.send "compose_with_#{self.composition_strategy}"
+                end
+
+        case self.delivery_strategy
+        when :sendmail, :send_mail      then deliver_with_sendmail(email, options)
+        when :smtp, :netsmtp, :net_smtp then deliver_with_smtp(email, options)
+        when Proc                       then self.delivery_strategy.call(email, options)
+        when Class                      then deliver_with_custom_strategy(email, options)
+        else
+          self.send "deliver_with_#{self.delivery_strategy}"
+        end
+      end
+
+      protected
+
+      def compose_with_mailfactory(options)
+        email         = MailFactory.new
+        email.from    = options[:from]
+
+        [options[:reply_to] || []].flatten.each do |address|
+          email.add_header "Reply-To", address
+        end
+        [options[:to] || []].flatten.each do |address|
+          email.add_header "To", address
+        end
+        [options[:cc] || []].flatten.each do |address|
+          email.add_header "Cc", address
+        end
+
+        email.subject = options[:subject] if options[:subject]
+        email.text    = options[:text]    if options[:text]
+        email.html    = options[:html]    if options[:html]
+
+        email
+      end
+
+      def compose_with_tmail(options)
+        # TODO
+      end
+
+      def compose_with_custom_strategy(options)
+        # TODO
+      end
+
+      def deliver_with_sendmail(email, options)
+        if Merb.testing?
+          Merb::Messenger.test_deliveries[:email].push email
+        else
+          recepients = [options[:to] || []].flatten.join(',')
+          Merb.logger.info! "Sending email with sendmail #{recepients}"
+          IO.popen("sendmail #{recepients}", 'w+') do |sendmail|
+            sendmail.puts email.to_s
+          end
+        end
+      end # deliver_with_sendmail
+
+      def deliver_with_smtp(email, options)
+        # TODO
+      end
+
+      def deliver_with_custom_strategy(email, options)
+        # TODO
+      end # deliver_with_custom_strategy
+    end
+  end
+end

data/lib/merb_messenger/transports/xmpp4r.rb

@@ -0,0 +1,45 @@
+require 'xmpp4r/client'
+
+module Merb
+  module Messenger
+    class Xmpp4rTransport
+      include ::Jabber
+
+      class_inheritable_accessor :_default_delivery_options
+      self._default_delivery_options = Mash.new(:message_type => :chat)
+
+      def self.delivery_options(options)
+        self._default_delivery_options = options
+      end
+
+      attr_reader :transport
+
+      def initialize(options)
+        @transport = Client.new(options[:jid])
+        @transport.connect
+        
+        @transport.auth(options[:password])
+      end
+
+      def connect
+        self.transport.connect
+      end
+
+      def disconnect
+        self.transport.close
+      end
+
+      def deliver(options = {})
+        options = _default_delivery_options.merge(options)
+        
+        m = Message.new(options[:to], options[:body])
+        
+        m.set_subject(options[:subject]) if options[:subject]
+        m.set_subject(options[:id])      if options[:id]
+        m.set_type(options[:message_type] || :normal)
+        
+        self.transport.send(m)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: pk-merb_messenger
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Michael Klishin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-15 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: merb-core
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "1.1"
+    version: 
+description: "Merb plugin that provides messaging/notifications functionality: from email and XMPP to AMPQ and beyond."
+email: michael@novemberain.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- LICENSE
+- TODO
+files: 
+- LICENSE
+- README
+- Rakefile
+- TODO
+- lib/merb_messenger
+- lib/merb_messenger/merbtasks.rb
+- lib/merb_messenger/messaging_controller.rb
+- lib/merb_messenger/messaging_mixin.rb
+- lib/merb_messenger/transports
+- lib/merb_messenger/transports/growl.rb
+- lib/merb_messenger/transports/mailfactory.rb
+- lib/merb_messenger/transports/xmpp4r.rb
+- lib/merb_messenger.rb
+has_rdoc: false
+homepage: http://merbivore.com/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: merb
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 3
+summary: "Merb plugin that provides messaging/notifications functionality: from email and XMPP to AMPQ and beyond."
+test_files: []
+