communicator 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,24 @@
+## MAC OS
+.DS_Store
+.bundle
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+db/*.sqlite*
+*.pid

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.8.7

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,44 @@
+PATH
+  remote: .
+  specs:
+    communicator (0.1.0)
+      activerecord (< 3.0.0)
+      httparty (>= 0.6.1)
+      json (>= 1.4.0)
+      sinatra (~> 1.1.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activerecord (2.3.10)
+      activesupport (= 2.3.10)
+    activesupport (2.3.10)
+    crack (0.1.8)
+    factory_girl (1.3.2)
+    httparty (0.6.1)
+      crack (= 0.1.8)
+    json (1.4.6)
+    rack (1.2.1)
+    rack-test (0.5.6)
+      rack (>= 1.0)
+    shoulda (2.10.3)
+    sinatra (1.1.0)
+      rack (~> 1.1)
+      tilt (~> 1.1)
+    sqlite3-ruby (1.3.2)
+    tilt (1.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (< 3.0.0)
+  bundler (>= 1.0.0)
+  communicator!
+  factory_girl (>= 1.2.3)
+  httparty (>= 0.6.1)
+  json (>= 1.4.0)
+  rack-test (>= 0.5.6)
+  shoulda (= 2.10.3)
+  sinatra (~> 1.1.0)
+  sqlite3-ruby (>= 1.3.0)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Capita Unternehmensberatung GmbH
+
+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.rdoc

@@ -0,0 +1,83 @@
+= communicator
+
+A simple communication layer to keep database records in sync between two
+Rails apps.
+
+== Setup
+
+Install in Rails apps with:
+
+  gem 'communicator'
+  $ bundle install
+  
+Import rake tasks in your Rails.root/Rakefile:
+
+  require 'communicator/tasks'
+  
+Set up the database tables for the messages by importing the corresponding
+migrations from the gem:
+
+  $ rake communicator:update_migrations
+  $ rake db:migrate
+  
+After doing these steps, you can proceed to configure either the server or client
+side as specified in the following subsections.
+  
+== Server side
+  
+On the server side, you can mount the server component in a Rails 2.3 app
+as a rack middleware inside environment.rb:
+
+  require 'communicator'
+  Communicator::Server.username = 'foo'
+  Communicator::Server.password = 'bar'
+  config.middleware.use 'Communicator::Server'
+
+It will then be mounted at /messages.json for GET and POST requests, requesting
+HTTP Basic Auth with the configured credentials.
+
+== Client side
+
+Tell the client the server url and port as well as the auth credentials inside
+your environment.rb:
+
+  require 'communicator'
+  Communicator::Client.username = 'test'
+  Communicator::Client.password = 'test'
+  Communicator::Client.base_uri 'localhost:3001'
+    
+When everything's fine, you should be able to push and pull using the client:
+
+  Communicator::Client.push
+  Communicator::Client.pull
+  
+== Active Record integration
+
+To keep models in sync, specify the model class (in underscored type) the local
+class receives updates from like this:
+
+  class Post < ActiveRecord::Base
+    receives_from :post
+  end
+
+Use the automatically added `publish` instance method on your models to push changes
+to the other side. They will be enqueued in the local `outbound_messages` table and
+will arrive at the other side when a client pulls or pushes.
+
+When an update is received from a remote side, the message will be stored in
+`inbound_messages` and the received changes will be applied to the local record,
+either updating existing or creating new records.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Capita Unternehmensberatung GmbH. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,100 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "communicator"
+    gem.summary = %Q{Data push/pull between apps with local inbound/outbound queue and easy publish/process interface}
+    gem.description = %Q{Data push/pull between apps with local inbound/outbound queue and easy publish/process interface}
+    gem.email = "christoph at olszowka de"
+    gem.homepage = "http://github.com/colszowka/communicator"
+    gem.authors = ["Christoph Olszowka"]
+    gem.add_dependency 'sinatra', "~> 1.1.0"
+    gem.add_dependency 'activerecord', "< 3.0.0"
+    gem.add_dependency 'httparty', '>= 0.6.1'
+    gem.add_dependency 'json', '>= 1.4.0'
+    
+    gem.add_development_dependency "shoulda", "2.10.3"
+    gem.add_development_dependency 'factory_girl', ">= 1.2.3"
+    gem.add_development_dependency 'rack-test', ">= 0.5.6"
+    gem.add_development_dependency 'bundler', ">= 1.0.0"
+    gem.add_development_dependency 'sqlite3-ruby', ">= 1.3.0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+
+
+namespace :db do
+  desc "Drop, create and migrate the test databases"
+  task :migrate do
+    require 'active_record'
+    # Drop existing db
+    system "rm db/*.sqlite3"
+    dev_null = File.new('/dev/null', 'w')
+    ActiveRecord::Base.logger = Logger.new(dev_null)
+    ActiveRecord::Migration.verbose = false
+  
+    # Create and migrate test databases for server and client
+    %w(test_client test_server).each do |db_name|
+      ActiveRecord::Base.establish_connection(:adapter => 'sqlite3', :database => "db/#{db_name}.sqlite3")
+      ActiveRecord::Migrator.migrate('db/migrate')
+      ActiveRecord::Migrator.migrate('test/migrate')
+    end
+  end
+end
+
+namespace :test_server do
+  desc "Starts the test server"
+  task :start do
+    Thread.new do
+      # Capture sinatra output (to hide it away...)
+      require "open3"
+      Open3.popen3("bundle exec rackup test/config.ru -p 20359 --pid=#{File.join(File.dirname(__FILE__), 'test', 'rack.pid')}")
+    end
+    sleep 2.0
+  
+    Kernel.at_exit do
+      Rake::Task["test_server:stop"].invoke
+    end
+  end
+
+  desc "Stops the test server"
+  task :stop do
+    begin
+      pid = File.read(File.join(File.dirname(__FILE__), 'test', 'rack.pid')).strip.chomp
+      `kill -s KILL #{pid}`
+      puts "Killed test server with PID #{pid}"
+    rescue => err
+      puts "Nothing to stop..."
+    end
+  end
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :test => :check_dependencies
+# Make sure database and test server are in place when tests start
+task :test => :"db:migrate"
+task :test => :"test_server:start"
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "communicator #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/communicator.gemspec

@@ -0,0 +1,106 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{communicator}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Christoph Olszowka"]
+  s.date = %q{2010-11-03}
+  s.description = %q{Data push/pull between apps with local inbound/outbound queue and easy publish/process interface}
+  s.email = %q{christoph at olszowka de}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     ".rvmrc",
+     "Gemfile",
+     "Gemfile.lock",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "communicator.gemspec",
+     "db/migrate/20101101075419_create_inbound_messages.rb",
+     "db/migrate/20101101075719_create_outbound_messages.rb",
+     "lib/communicator.rb",
+     "lib/communicator/active_record_integration.rb",
+     "lib/communicator/client.rb",
+     "lib/communicator/inbound_message.rb",
+     "lib/communicator/outbound_message.rb",
+     "lib/communicator/server.rb",
+     "lib/communicator/tasks.rb",
+     "test/config.ru",
+     "test/factories.rb",
+     "test/helper.rb",
+     "test/lib/post.rb",
+     "test/lib/test_server_database/inbound_message.rb",
+     "test/lib/test_server_database/outbound_message.rb",
+     "test/lib/test_server_database/post.rb",
+     "test/migrate/20101101093519_create_posts.rb",
+     "test/test_client.rb",
+     "test/test_message_models.rb",
+     "test/test_server.rb"
+  ]
+  s.homepage = %q{http://github.com/colszowka/communicator}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Data push/pull between apps with local inbound/outbound queue and easy publish/process interface}
+  s.test_files = [
+    "test/factories.rb",
+     "test/helper.rb",
+     "test/lib/post.rb",
+     "test/lib/test_server_database/inbound_message.rb",
+     "test/lib/test_server_database/outbound_message.rb",
+     "test/lib/test_server_database/post.rb",
+     "test/migrate/20101101093519_create_posts.rb",
+     "test/test_client.rb",
+     "test/test_message_models.rb",
+     "test/test_server.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<sinatra>, ["~> 1.1.0"])
+      s.add_runtime_dependency(%q<activerecord>, ["< 3.0.0"])
+      s.add_runtime_dependency(%q<httparty>, [">= 0.6.1"])
+      s.add_runtime_dependency(%q<json>, [">= 1.4.0"])
+      s.add_development_dependency(%q<shoulda>, ["= 2.10.3"])
+      s.add_development_dependency(%q<factory_girl>, [">= 1.2.3"])
+      s.add_development_dependency(%q<rack-test>, [">= 0.5.6"])
+      s.add_development_dependency(%q<bundler>, [">= 1.0.0"])
+      s.add_development_dependency(%q<sqlite3-ruby>, [">= 1.3.0"])
+    else
+      s.add_dependency(%q<sinatra>, ["~> 1.1.0"])
+      s.add_dependency(%q<activerecord>, ["< 3.0.0"])
+      s.add_dependency(%q<httparty>, [">= 0.6.1"])
+      s.add_dependency(%q<json>, [">= 1.4.0"])
+      s.add_dependency(%q<shoulda>, ["= 2.10.3"])
+      s.add_dependency(%q<factory_girl>, [">= 1.2.3"])
+      s.add_dependency(%q<rack-test>, [">= 0.5.6"])
+      s.add_dependency(%q<bundler>, [">= 1.0.0"])
+      s.add_dependency(%q<sqlite3-ruby>, [">= 1.3.0"])
+    end
+  else
+    s.add_dependency(%q<sinatra>, ["~> 1.1.0"])
+    s.add_dependency(%q<activerecord>, ["< 3.0.0"])
+    s.add_dependency(%q<httparty>, [">= 0.6.1"])
+    s.add_dependency(%q<json>, [">= 1.4.0"])
+    s.add_dependency(%q<shoulda>, ["= 2.10.3"])
+    s.add_dependency(%q<factory_girl>, [">= 1.2.3"])
+    s.add_dependency(%q<rack-test>, [">= 0.5.6"])
+    s.add_dependency(%q<bundler>, [">= 1.0.0"])
+    s.add_dependency(%q<sqlite3-ruby>, [">= 1.3.0"])
+  end
+end
+

data/db/migrate/20101101075419_create_inbound_messages.rb

@@ -0,0 +1,13 @@
+class CreateInboundMessages < ActiveRecord::Migration
+  def self.up
+    create_table :inbound_messages do |t|
+      t.text     :body, :null => false
+      t.datetime :processed_at, :default => nil
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :inbound_messages
+  end
+end

data/db/migrate/20101101075719_create_outbound_messages.rb

@@ -0,0 +1,13 @@
+class CreateOutboundMessages < ActiveRecord::Migration
+  def self.up
+    create_table :outbound_messages do |t|
+      t.text     :body, :null => false
+      t.datetime :delivered_at, :default => nil
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :outbound_messages
+  end
+end

data/lib/communicator/active_record_integration.rb

@@ -0,0 +1,42 @@
+# ActiveRecord hooks for Communicator
+module Communicator::ActiveRecordIntegration
+  module ClassMethods
+    # Class method to register as a communicator receiver
+    #
+    # Usage (assuming you expect messages from "post"):
+    #  class Post < ActiveRecord::Base
+    #    receives_from :post
+    #  end
+    #
+    def receives_from(source)
+      Communicator.register_receiver(self, source)
+    end
+  end
+  
+  # Instance methods that are to be mixed in to receiver classes
+  module InstanceMethods
+    # Instance variable to store whether this instance has been updated from remote message
+    attr_accessor :updated_from_message
+    
+    # Publishes this instance as an OutboundMessage with json representation as body
+    def publish
+      Communicator::OutboundMessage.create!(:body => {self.class.to_s.underscore => attributes}.to_json)
+    end
+    
+    # Processes the given message body by applying all contained attributes and their values
+    # and saving
+    def process_message(input)
+      # When the input is still json, parse it. Otherwise we're assuming it's already a demarshalled hash
+      input = JSON.parse(input) if input.kind_of?(String)
+      input.each do |attr_name, value|
+        self.send("#{attr_name}=", value)
+      end
+      self.updated_from_message = true
+      save!
+    end
+  end
+end
+
+# Include class methods into active record base
+ActiveRecord::Base.send :extend, Communicator::ActiveRecordIntegration::ClassMethods
+

data/lib/communicator/client.rb

@@ -0,0 +1,63 @@
+require 'httparty'
+class Communicator::Client
+  class ServerError < StandardError; end;
+  class AuthError < StandardError; end;
+  class InvalidStartingId < StandardError; end;
+
+  include HTTParty
+  
+  class << self
+    attr_writer :username, :password
+    # Return configured username for http auth basic or raise an error message if not configured
+    def username
+      @username || raise(Communicator::MissingCredentials.new("No Username specified for HTTP AUTH. Please configure using Communicator::Client.username='xyz'"))
+    end
+
+    # Return configured password for http auth basic or raise an error message if not configured    
+    def password
+      @password || raise(Communicator::MissingCredentials.new("No Password specified for HTTP AUTH. Please configure using Communicator::Client.password='xyz'"))
+    end
+    
+    # Helper for basic auth in httparty-expected format for request options
+    def credentials
+      {:username => username, :password => password}
+    end
+    
+    def pull
+      request = get('/messages.json', :query => {:from_id => Communicator::InboundMessage.last_id+1}, :basic_auth => credentials)
+      verify_response request.response
+      Communicator::InboundMessage.create_from_json_collection!(JSON.parse(request.parsed_response))
+      request
+    end
+  
+    def push(from_id=nil)
+      messages = Communicator::OutboundMessage.delivery_collection(from_id)
+      request = post("/messages.json", :body => messages.map(&:payload).to_json, :basic_auth => credentials)
+      verify_response request.response
+      # Everything went fine? Mark the messages as delivered
+      messages.each {|m| m.delivered! }
+      request
+    
+    # Retry when server sent a from_id expectation
+    rescue Communicator::Client::InvalidStartingId => err
+      unless from_id
+        push(request.response.body)
+      else
+        raise "Could not agree upon from_id with server!"
+      end
+    end
+    
+    def verify_response(response)
+      if response.kind_of?(Net::HTTPSuccess)
+        return true
+      elsif response.kind_of?(Net::HTTPUnauthorized) or response.kind_of?(Net::HTTPForbidden)
+        raise Communicator::Client::AuthError.new("Failed to authenticate!")
+      elsif response.kind_of?(Net::HTTPConflict)
+        raise Communicator::Client::InvalidStartingId.new("Expected from_id to begin with #{response.body.strip.chomp}")
+      elsif response.kind_of?(Net::HTTPServerError)
+        raise Communicator::Client::ServerError.new("Request failed with #{response.class}")
+      end
+    end
+  end
+
+end

data/lib/communicator/inbound_message.rb

@@ -0,0 +1,50 @@
+class Communicator::InboundMessage < ActiveRecord::Base
+  set_table_name 'inbound_messages'
+  
+  validates_presence_of :body
+  
+  named_scope :unpublished, :conditions => {:processed_at => nil}
+  default_scope :order => "id ASC"
+
+  # Process messages that have been stored locally successfully
+  after_create do |r|
+    r.process!
+  end
+  
+  # Creates an inbound message from a remote json hash
+  def self.create_from_json!(json_message)
+    inbound_msg = Communicator::InboundMessage.new(:body => json_message["body"])
+    inbound_msg.id = json_message["id"]
+    inbound_msg.save!
+    inbound_msg
+  end
+  
+  # Expects an already demarshalled collection array containing remote message data, which
+  # will then all be processed indivdually using create_from_json!
+  def self.create_from_json_collection!(json_messages)
+    json_messages.map {|json_message| create_from_json!(json_message) }
+  end
+  
+  # Find the last ID present locally
+  def self.last_id
+    count > 0 ? find(:first, :order => 'id DESC').id : 0
+  end
+  
+  # Checks whether the given id is properly in line with the local last id
+  # The check will only be actually performed when there are any locally stored inbound messages
+  def self.valid_next_id?(from_id)
+    Communicator::InboundMessage.count == 0 or from_id.to_i == Communicator::InboundMessage.last_id + 1
+  end
+  
+  def message_content
+    JSON.parse(body).with_indifferent_access
+  end
+  
+  # Figure out who is the receiver of this message and process the message
+  def process!
+    source, message = JSON.parse(body).first
+    Communicator.receiver_for(source).find_or_initialize_by_id(message["id"]).process_message(message)
+    self.processed_at = Time.now
+    self.save!
+  end
+end

data/lib/communicator/outbound_message.rb

@@ -0,0 +1,30 @@
+class Communicator::OutboundMessage < ActiveRecord::Base
+  set_table_name "outbound_messages"
+  validates_presence_of :body
+  
+  named_scope :undelivered, :conditions => {:delivered_at => nil}
+  default_scope :order => "id ASC"
+  
+  # Returns an array of all undelivered messages. If the optional id is given
+  # will instead start from that id, not taking care whether the messages have
+  # already been marked as delivered.
+  def self.delivery_collection(from_id=nil)
+    (from_id ? all(:conditions => ["id >= ?", from_id]) : undelivered)
+  end
+  
+  # Stripped down content hash for json delivery
+  def payload
+    {:id => id, :body => body}
+  end
+  
+  # Will return the JSON-parsed content of this message's body
+  def message_content
+    JSON.parse(body).with_indifferent_access
+  end
+  
+  # Set the delivered_at flag to NOW and save!
+  def delivered!
+    self.delivered_at = Time.now
+    self.save!
+  end
+end

data/lib/communicator/server.rb

@@ -0,0 +1,62 @@
+require 'sinatra'
+
+class Communicator::Server < Sinatra::Base
+  # Configuration parameters
+  class << self
+    attr_writer :username, :password
+    
+    # Return configured username for http auth basic or raise an error message if not configured
+    def username
+      @username || raise("No Username specified for HTTP AUTH. Please configure using Communicator::Server.username='xyz'")
+    end
+
+    # Return configured password for http auth basic or raise an error message if not configured    
+    def password
+      @password || raise("No Password specified for HTTP AUTH. Please configure using Communicator::Server.password='xyz'")
+    end
+  end
+  
+  use Rack::Auth::Basic do |username, password|
+    [username, password] == [Communicator::Server.username, Communicator::Server.password]
+  end
+  
+  # PULL
+  get '/messages.json' do
+    # Require from_id attribute
+    return [409, "Specify from_id!"] unless params[:from_id]
+    
+    # from_id is irrelevant when no messages are present
+    params[:from_id] = nil if Communicator::OutboundMessage.count == 0
+    
+    # Fetch the messages and build the json
+    messages = Communicator::OutboundMessage.delivery_collection(params[:from_id])
+    json = messages.map(&:payload).to_json
+    # Flag the messages as delivered
+    messages.each {|m| m.delivered! }
+    # Collect the message payloads and render them as json
+    [200, json]
+  end
+  
+  # PUSH
+  post '/messages.json' do
+    body = request.body.read.strip
+    # Make sure a message body is given!
+    return [409, "No data given"] if body.length < 2
+    # Parse json
+    json_messages = JSON.parse(body)
+    
+    # If no messages present, just return
+    return [202, "No data given"] unless json_messages.length > 0
+   
+    # Make sure the first id does directly follow the last one present locally - but only if we already have ANY messages
+    # On failure, render HTTPConflicht and expected from_id
+    return [409, (Communicator::InboundMessage.last_id + 1).to_s] unless Communicator::InboundMessage.valid_next_id?(json_messages.first["id"])
+    
+    # Everything's fine? Let's store messages!
+    Communicator::InboundMessage.create_from_json_collection!(json_messages)
+    
+    202 # ACCEPTED
+  end
+end
+
+require 'pp'