broadcast 0.1.0

data/.gitignore

@@ -0,0 +1,9 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+sandbox
+*.log
+coverage
+bin
+.rspec

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem 'rspec'
+  gem 'rcov'
+
+  platforms :mri_18 do
+    gem "ruby-debug"
+  end
+
+  platforms :mri_19 do
+    gem "ruby-debug19"
+  end
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011 Marcin Bunsch, Future Simple Inc.
+
+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.markdown

@@ -0,0 +1,212 @@
+Broadcast
+=========
+
+A broadcasting microframework making publishing of messages to different services easy and DRY.
+
+Use Cases
+------------
+
+Possible use cases include:
+
+- publishing a update on your product Twitter feed
+- notifying coworkers on Jabber of a deployment when it happens
+- sending update on company IRC when a signup in your startup app happens
+- publishing daily statistics to Yammer
+- sending an email and a Jabber update when a specific threshold is reached (like number of users)
+
+Installation
+------------
+
+Broadcast is in alpha state, so it's not pushed to RubyGems yet.
+
+You can install it by adding the following line to your Gemfile:
+
+    gem 'broadcast', :git => 'git://github.com/futuresimple/broadcast.git'
+
+and running
+
+    bundle install
+
+Usage
+-----
+
+Broadcast has 2 main classes: Medium and Message (hat tip to Marshall McLuhan).
+
+**Broadcast::Medium** is the service the message will be sent to, and **Broadcast::Message** is, well, the message.
+
+The first thing you need to do is to configure the desired Media. For example, to configure jabber, put something like this in some configuration file (e.g. a Rails initializer):
+
+```ruby
+  Broadcast.setup do |config|
+    config.jabber { |jabber|
+      jabber.username       = 'foo@foo.com'
+      jabber.password       = 'mypass'
+      jabber.recipients     = 'mike@foo.com'
+    }
+  end
+```
+
+Now to send a message, you need to define Message class, like this:
+
+```ruby
+  class Poke < Broadcast::Message
+    medium :jabber
+
+    def body
+      "Poke!"
+    end
+  end
+```
+
+When you're ready, just instantiate the Message class and call #publish:
+
+```ruby
+  Poke.new.publish
+```
+
+Delayed::Job
+------------
+
+Broadcast plays nicely with Delayed::Job. For example to publish a message in a delayed job, simply change the above example to:
+
+```ruby
+  Poke.new.delay.publish
+```
+
+
+Media
+-----
+
+Broadcast currently ships with support for following Media:
+
+### Jabber
+
+Broadcast::Medium::Jabber is based on the xmpp4r gem.
+
+#### Example setup
+
+```ruby
+  Broadcast.setup do |config|
+    config.jabber { |jabber|
+      jabber.username       = 'myaccount@gmail.com'
+      jabber.password       = 'mypass'
+      jabber.recipients     = 'mike@foo.com'
+    }
+  end
+```
+
+### Email
+
+Broadcast::Medium::Email is based on the mail gem.
+
+#### Example setup
+
+This is an example setup with smtp delivery method with Gmail
+
+```ruby
+  Broadcast.setup do |config|
+    config.email { |email|
+      email.recipients       = ['foo@moo.com']
+      email.delivery_method  = :smtp
+      email.delivery_options = {
+        :address              => "smtp.gmail.com",
+        :port                 => 587,
+        :domain               => 'your.host.name',
+        :user_name            => '<username>',
+        :password             => '<password>',
+        :authentication       => 'plain',
+        :enable_starttls_auto => true
+      }
+    }
+  end
+```
+
+### Twitter
+
+Broadcast::Medium::Twitter is based on the oauth gem.
+In order to use it, you will need a application registered on Twitter.
+
+When you have it, run rake broadcast:authorize:twitter, which will help you get all the required keys and tokens.
+
+#### Example setup
+
+```ruby
+  Broadcast.setup do |config|
+    config.twitter { |twitter|
+      twitter.consumer_key    = 'consumerkey'
+      twitter.consumer_secret = 'consumersecret'
+      twitter.access_token    = 'accesstoken'
+      twitter.access_secret   = 'accesssecret'
+    }
+  end
+```
+
+### Yammer
+
+Broadcast::Medium::Yammer is based on the oauth gem.
+In order to use it, you will need a application registered on Yammer.
+
+When you have it, run rake broadcast:authorize:yammer, which will help you get all the required keys and tokens.
+
+#### Example setup
+
+```ruby
+  Broadcast.setup do |config|
+    config.twitter { |yammer|
+      yammer.consumer_key    = 'consumerkey'
+      yammer.consumer_secret = 'consumersecret'
+      yammer.access_token    = 'accesstoken'
+      yammer.access_secret   = 'accesssecret'
+    }
+  end
+```
+
+### Log
+
+Broadcast::Medium::Log is a simple writer to a log file
+
+#### Example setup
+
+```ruby
+  Broadcast.setup do |config|
+    config.log.file = 'log/broadcast.log'
+  end
+```
+
+### Campfire
+
+Broadcast::Medium::Campfire is based on the broach gem.
+
+#### Example setup
+
+```ruby
+  Broadcast.setup do |config|
+    config.campfire { |campfire|
+      campfire.subdomain = 'myaccount'
+      campfire.token     = 'token'
+      campfire.room      = 'My Room'
+    }
+  end
+```
+
+### Irc
+
+Broadcast::Medium::Irc employs the shout-bot gem.
+
+#### Example setup
+
+```ruby
+  Broadcast.setup do |config|
+    config.irc { |irc|
+      irc.username = 'myusername',
+      irc.server = 'irc.freenode.net',
+      irc.port = '6667',
+      irc.channel = 'mychannel',
+    }
+  end
+```
+
+Copyright
+---------
+
+Copyright (c) 2011 Marcin Bunsch, Future Simple Inc. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,35 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+begin
+
+  require 'rspec'
+  require "rspec/core/rake_task"
+
+  desc "Run all examples"
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    t.rspec_path = 'bin/rspec'
+    t.rspec_opts = %w[--color]
+    t.verbose = false
+  end
+
+  namespace :spec do
+    task :cleanup do
+      rm_rf 'coverage.data'
+    end
+
+    RSpec::Core::RakeTask.new :rcov do |t|
+      t.rcov = true
+      t.rcov_opts =  %[-Ilib -Ispec --exclude "gems/*,features"]
+      t.verbose = false
+    end
+
+  end
+
+rescue 
+  puts 'Could not load Broadcast RSpec Rake tasks'
+end

data/broadcast.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "broadcast/version"
+
+Gem::Specification.new do |s|
+  s.name        = "broadcast"
+  s.version     = Broadcast::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Marcin Bunsch"]
+  s.email       = ["marcin@futuresimple.com"]
+  s.homepage    = "http://github.com/futuresimple/broadcast"
+  s.summary     = %q{A broadcasting microframework making publishing of messages to different services easy}
+  s.description = %q{A broadcasting microframework making publishing of messages to different services easy}
+
+  s.add_dependency 'hashie'
+
+  # 'Externalable' dependencies
+  s.add_dependency 'oauth'
+  s.add_dependency 'xmpp4r'
+  s.add_dependency 'mail'
+  s.add_dependency 'broach'
+  s.add_dependency 'shout-bot'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/broadcast/config.rb

@@ -0,0 +1,20 @@
+class Broadcast::Config
+
+  # Allow usage of namespaces in config
+  def method_missing(meth, *args, &block)
+    @namespaces ||= {}
+    stringified = meth.to_s
+    if stringified[-1].chr == '=' and args.first
+      key = stringified[0..-2].to_sym
+      @namespaces[key] = args.first
+    elsif block
+      key = stringified[0..-1].to_sym
+      @namespaces[key] ||= Hashie::Mash.new
+      block.call(@namespaces[key])
+    else
+      key = stringified[0..-1].to_sym
+      @namespaces[key] ||= Hashie::Mash.new
+    end
+  end
+
+end

data/lib/broadcast/media/campfire.rb

@@ -0,0 +1,10 @@
+require 'broach'
+
+class Broadcast::Medium::Campfire < Broadcast::Medium::Oauth
+
+  def publish(message)
+    Broach.settings = { 'account' => options.subdomain, 'token' => options.token, 'use_ssl' => true }
+    Broach.speak(options.room, message.body)
+  end
+
+end

data/lib/broadcast/media/email.rb

@@ -0,0 +1,22 @@
+require 'mail'
+
+class Broadcast::Medium::Email < Broadcast::Medium::Oauth
+
+  def publish(message)
+    recipients = options.recipients.is_a?(Array) ? options.recipients : [options.recipients]
+    options = self.options
+    recipients.compact.each do |recipient|
+      mail = Mail.new do
+         from    options.sender || message.class.to_s
+         to      recipient
+         subject message.subject || message.class.to_s
+         body    message.body
+      end
+      if options.delivery_method
+        mail.delivery_method options.delivery_method, options.delivery_options || {}
+      end
+      mail.deliver
+    end
+  end
+  
+end

data/lib/broadcast/media/irc.rb

@@ -0,0 +1,12 @@
+require 'shout-bot'
+
+class Broadcast::Medium::Irc < Broadcast::Medium::Oauth
+  def publish(message)
+    uri = "irc://#{options.username}"
+
+    uri += "@#{options.server}:#{options.port ? options.port : '6667'}"
+    uri += "/##{options.channel.to_s.gsub("#","") }"
+
+    ShoutBot.shout(uri) { |room| room.say message }
+  end
+end

data/lib/broadcast/media/jabber.rb

@@ -0,0 +1,33 @@
+require 'xmpp4r'
+
+class Broadcast::Medium::Jabber < Broadcast::Medium::Oauth
+
+  class Client
+
+    attr_accessor :client
+
+    def initialize(username, password, server = nil, port = 5222)
+      @jid    = Jabber::JID::new(username)
+      @client = Jabber::Client::new(@jid)
+      client.connect(server, port)
+      client.auth(password)
+    end
+
+    def deliver(recipient, body)
+      client.send Jabber::Message::new(recipient, body)
+    end
+
+  end
+
+  def jabber
+    @jabber ||= Client.new(options.username, options.password, options.server)
+  end
+
+  def publish(message)
+    recipients = options.recipients.is_a?(Array) ? options.recipients : [options.recipients]
+    recipients.compact.each do |recipient|
+      jabber.deliver(recipient, message.body)
+    end
+  end
+
+end

data/lib/broadcast/media/log.rb

@@ -0,0 +1,7 @@
+class Broadcast::Medium::Log < Broadcast::Medium
+
+  def publish(message)
+    Logger.new(options.file).info(message.body)
+  end
+
+end

data/lib/broadcast/media/oauth.rb

@@ -0,0 +1,43 @@
+require 'oauth'
+
+class Broadcast::Medium::Oauth < Broadcast::Medium
+
+  class << self
+    attr_accessor :site
+  end
+
+  def consumer
+    @consumer ||= OAuth::Consumer.new(options.consumer_key, options.consumer_secret, :site => self.class.site)
+  end
+
+  def token
+    @access_token ||= OAuth::AccessToken.new(consumer, options.access_token, options.access_secret)
+  end
+
+  def authorize
+    unless options.consumer_key
+      print "Enter consumer key: "
+      options.consumer_key = $stdin.gets.chomp
+    end
+    unless options.consumer_secret
+      print "Enter consumer secret: "
+      options.consumer_secret = $stdin.gets.chomp
+    end
+    request_token = consumer.get_request_token
+    puts "\nGo to this url and click 'Authorize' to get the token:"
+    puts request_token.authorize_url
+    print "\nEnter token: "
+    token = $stdin.gets.chomp
+
+    access_token  = request_token.get_access_token(:oauth_verifier => token)
+
+    puts "\nAuthorization complete! Put the following in your Broadcast configuration file:\n\n"
+    puts "Broadcast.setup do |config|\n\n"
+    puts "  config.#{namespace}.consumer_key     = '#{consumer.key}'"
+    puts "  config.#{namespace}.consumer_secret  = '#{consumer.key}'"
+    puts "  config.#{namespace}.access_token     = '#{access_token.token}'"
+    puts "  config.#{namespace}.access_secret    = '#{access_token.secret}'"
+    puts "\nend"
+  end
+
+end

data/lib/broadcast/media/twitter.rb

@@ -0,0 +1,9 @@
+class Broadcast::Medium::Twitter < Broadcast::Medium::Oauth
+
+  self.site = "http://api.twitter.com"
+
+  def publish(message)
+    token.post '/1/statuses/update.json', { :status => message.body }
+  end
+
+end

data/lib/broadcast/media/yammer.rb

@@ -0,0 +1,9 @@
+class Broadcast::Medium::Yammer < Broadcast::Medium::Oauth
+
+  self.site = "https://www.yammer.com"
+
+  def publish(message)
+    token.post '/api/v1/messages.json', { :body => message.body }
+  end
+
+end

data/lib/broadcast/medium.rb

@@ -0,0 +1,27 @@
+class Broadcast::Medium
+
+  # Set up autoload for the media
+  Dir.glob(File.join(Broadcast::ROOT, 'broadcast', 'media', '*')).each do |file|
+    name = File.basename(file).split('.').first
+    autoload name.capitalize.to_sym, file
+  end
+
+  def initialize(options = {})
+    # load in the configuration from Broadcast setup
+    @options = Broadcast.configuration.send(namespace) || Hashie::Mash.new
+    # Override the configuration using the supplied options
+    @options = @options.merge(options)
+  end
+
+  def namespace
+    @namespace ||= self.class.name.split('::').last.downcase.to_sym
+  end
+
+  def options
+    @options
+  end
+
+  def publish(message)
+  end
+
+end

data/lib/broadcast/message.rb

@@ -0,0 +1,33 @@
+class Broadcast::Message
+
+  attr_accessor :options
+  class << self
+    attr_accessor :media
+    def medium(name, options = {})
+      self.media ||= []
+      self.media.push({ :name => name, :options => options })
+    end
+  end
+
+  def initialize(options = {})
+    @options = Hashie::Mash.new(options)
+  end
+
+  def publish
+    (self.class.media || []).each do |medium|
+      begin
+        Broadcast::Medium.const_get(medium[:name].to_s.downcase.capitalize).new(medium[:options]).publish(self)
+      rescue
+        Broadcast.logger.error "Publishing of #{self.class.name} to #{medium[:name]} failed:\n#{$!}"
+      end
+    end
+  end
+
+  def subject
+  end
+
+  def body
+    ""
+  end
+
+end

data/lib/broadcast/railtie.rb

@@ -0,0 +1,11 @@
+require 'rails/railtie'
+
+class Broadcast
+
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load 'broadcast/tasks/broadcast.rake'
+    end
+  end
+
+end

data/lib/broadcast/tasks/broadcast.rake

@@ -0,0 +1,19 @@
+namespace "broadcast" do
+    
+  namespace "authorize" do
+  
+    desc "Authorize Broadcast with Yammer and get access token information"
+    task "yammer" do
+      require 'broadcast'
+      Broadcast::Medium::Yammer.new.authorize
+    end
+
+    desc "Authorize Broadcast with Twitter and get access token information"
+    task "twitter" do
+      require 'broadcast'
+      Broadcast::Medium::Twitter.new.authorize
+    end
+  
+  end
+  
+end

data/lib/broadcast/version.rb

@@ -0,0 +1,5 @@
+class Broadcast
+
+  VERSION = "0.1.0"
+
+end

data/lib/broadcast.rb

@@ -0,0 +1,34 @@
+require 'logger'
+require 'hashie'
+
+class Broadcast
+
+  ROOT    = File.dirname(__FILE__)
+
+  class << self
+    attr_accessor :logger
+    attr_accessor :configuration
+  end
+
+  # Basic configuration object
+  require 'broadcast/config'
+  self.configuration = Broadcast::Config.new
+
+  # Default
+  self.logger = Logger.new($stdout)
+
+  def self.publish(type, options = {})
+    name = type.to_s.strip.split("_").collect(&:capitalize).join('')
+    message = Broadcast::Message.const_get(name).new
+    message.publish
+    message
+  end
+
+  def self.setup(&block)
+    block.call(self.configuration)
+  end
+
+end
+
+require 'broadcast/medium'
+require 'broadcast/message'

data/spec/lib/broadcast/media/campfire_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+describe Broadcast::Medium::Campfire do
+
+  describe '#publish' do
+
+    before do
+      @medium  = Broadcast::Medium::Campfire.new
+      @message = Broadcast::Message::SpecWithContent.new
+    end
+
+    it "should send a post request to the campfire API with the message body" do
+      Broach.should_receive(:speak).with("My Room", 'message')
+      @medium.publish(@message)
+    end
+
+  end
+
+end