reliable-msg 1.0.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2005 Assaf Arkin
+
+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,123 @@
+= Reliable Messaging for Ruby
+
+This package provides reliable messaging and persistent queues for
+building asynchronous applications in Ruby.
+
+This release provides the following features:
+
+* Simple API.
+
+* Transction processing.
+
+* Disk-based and MySQL message stores.
+
+* Best effort, repeated and once-only delivery semantics.
+
+* Priority queues, message expiration, dead-letter queue.
+
+* Message selectors.
+
+* Local and remote queue managers using DRb.
+
+
+== Download
+
+The latest version of Reliable Messaging can be found at
+
+* http://rubyforge.org/projects/reliable-msg/
+
+For more information (wiki, bug reports)
+
+* http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/RubyReliableMessaging
+
+
+== Installation
+
+You can download the sources directly, or install the GEM package
+(recommended) with
+
+  gem install --remote reliable-msg
+
+To create the configuration file and queues for use with the disk-based
+message store
+
+  queues install disk [<path>]
+
+The optional <tt>path</tt> argument specifies the directory in which
+queue index and messages are store. The default directory is
+<tt>queues</tt>.
+
+To create the configuration file and queues for use with the MySQL
+message store
+
+  queues install mysql <host> <user> <password> <database>
+         [--port <port>] [--socket <socket>] [--prefix <prefix>]
+
+You must have MySQL libraries installed in order to use this message
+store, either native MySQL libraries or the Rails pure-Ruby adapter.
+It uses the supplied connection properties and creates tables in your
+database using the specified prefix. The default prefix is
+<tt>reliable_msg_</tt>.
+
+For example
+
+  queues install mysql localhost my-db user secret
+
+=== Configuration file
+
+The installation process creates a configuration file
+(<tt>queues.cfg</tt>) located in the same directory as the library.
+You can specify a different location for the configuration file using
+the option <tt>-c</tt> of <tt>--config</tt>.
+
+When you use the queue manager, it looks for a specified configuration
+file, or if no configuration file is specified it looks for the
+<tt>queues.cfg</tt> file, first in the local directory and then in the
+installation directory. If no file exists, it will create a default one
+to use the disk-based message store.
+
+=== UUID state file
+
+Reliable messaging requires a UUID generator that is able to create
+universally unique identifiers. The UUID generator uses the
+<tt>uuid.state</tt> file to hold a unique machine identifier and a
+rolling sequence number.
+
+On the first usage, a <tt>uuid.state</tt> file is created in the
+installation directory. An existing state file will be used if one
+exists in the local directory or the installation directory.
+
+The unique machine identifier is obtained from one of the network
+card's MAC address on your machine, using either the +ipconfig+ or
++ifconfig+ commands. If no MAC address can be found, or you want to
+pick a specific MAC address, create a <tt>uuid.state</tt> file
+manually.
+
+
+== Simple Example
+
+Start the queue manager as a standalone server
+
+  queues manager start
+
+Use the queue API in your application
+
+  require 'reliable-msg'
+
+  queue = Queue.new 'my-queue'
+  queue.put obj
+  msg = queue.get
+  assert msg.object == obj
+
+Stop the queue manager
+
+  queues manager stop
+
+
+== License
+
+This package is licensed under the MIT license and/or the {Creative
+Commons Attribution-ShareAlike}[http://creativecommons.org/licenses/by-sa/2.5/legalcode].
+
+:include: MIT-LICENSE
+

data/Rakefile

@@ -0,0 +1,164 @@
+# Adapted from the rake Rakefile.
+
+require 'rubygems'
+Gem::manage_gems
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+
+desc "Default Task"
+task :default => [:tests, :rdoc]
+
+
+desc "Run test case for UUID generator"
+Rake::TestTask.new :test_uuid do |test|
+    test.verbose = true
+    test.test_files = ['test/test-uuid.rb']
+end
+desc "Run test case for Queue API generator"
+Rake::TestTask.new :test_queue do |test|
+    test.verbose = true
+    test.test_files = ['test/test-queue.rb']
+end
+desc "Run all test cases"
+Rake::TestTask.new :tests=>[:test_uuid, :test_queue] do |test|
+    test.verbose = true
+    test.test_files = []
+    #test.warning = true
+end
+
+
+# Create the documentation.
+Rake::RDocTask.new do |rdoc|
+    rdoc.main = "README"
+    rdoc.rdoc_files.include("README", "lib/**/*.rb")
+    rdoc.title = 'Reliable Messaging'
+end
+
+# Handle version number.
+class Version
+
+    PATTERN = /(\s*)VERSION.*(\d+\.\d+\.\d+)/
+
+    def initialize file, new_version
+        @file = file
+        @version = File.open @file, 'r' do |file|
+            version = nil
+            file.each_line do |line|
+                match = line.match PATTERN
+                if match
+                    version = match[2]
+                    break
+                end
+            end
+            version
+        end
+        fail "Can't determine version number" unless @version
+        @new_version = new_version || @version
+    end
+
+    def changed?
+        @version != @new_version
+    end
+
+    def number
+        @version
+    end
+
+    def next
+        @new_version
+    end
+
+    def update
+        puts "Updating to version #{@new_version}"
+        copy = "#{@file}.new"
+        open @file, "r" do |input|
+            open copy, "w" do |output|
+                input.each_line do |line|
+                    match = line.match PATTERN
+                    if match
+                        output.puts "#{match[1]}VERSION = '#{@new_version}'"
+                    else
+                        output.puts line
+                    end
+                end
+            end
+        end
+        mv copy, @file
+        @version = @new_version
+    end
+
+end
+version = Version.new 'lib/reliable-msg.rb', ENV['version']
+
+
+# Create the GEM package.
+gem_spec = Gem::Specification.new do |spec|
+    spec.name = 'reliable-msg'
+    spec.version = version.next
+    spec.summary = "Reliable messaging and persistent queues for building asynchronous applications in Ruby"
+    spec.description = <<-EOF
+        This package provides reliable messaging and persistent queues for
+        building asynchronous applications in Ruby.
+
+        It supports transaction processing, message selectors, priorities,
+        delivery semantics, remote queue managers, disk-based and MySQL message
+        stores and more.
+EOF
+    spec.author = "Assaf Arkin"
+    spec.email = "assaf@labnotes.org"
+    spec.homepage = "http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/RubyReliableMessaging"
+
+    spec.files = FileList["{bin,test,lib,docs}/**/*", "README", "MIT-LICENSE", "Rakefile"].to_a
+    spec.require_path = "lib"
+    spec.autorequire = 'reliable-msg.rb'
+    spec.bindir = "bin"
+    spec.executables = ["queues"]
+    spec.default_executable = "queues"
+    spec.requirements << "MySQL for database store, otherwise uses the file system"
+    spec.has_rdoc = true
+    spec.rdoc_options << '--main' << 'README' << '--title' <<  'Reliable Messaging for Ruby' << '--line-numbers'
+    spec.extra_rdoc_files = ["README"]
+end
+
+gem = Rake::GemPackageTask.new(gem_spec) do |pkg|
+    pkg.need_tar_gz = true
+    pkg.need_zip = true
+end
+
+
+desc "Look for TODO and FIXME tags in the code"
+task :todo do
+  FileList['**/*.rb'].egrep /#.*(FIXME|TODO|TBD)/
+end
+
+
+# --------------------------------------------------------------------
+# Creating a release
+
+desc "Make a new release"
+task :release => [:tests, :prerelease, :clobber, :update_version, :package] do
+    puts
+    puts "**************************************************************"
+    puts "* Release #{version.number} Complete."
+    puts "* Packages ready to upload."
+    puts "**************************************************************"
+    puts
+end
+
+task :prerelease do
+    if !version.changed? && ENV['reuse'] != version.number
+        fail "Current version is #{version.number}, must specify reuse=ver to reuse existing version"
+    end
+end
+
+task :update_version => [:prerelease] do
+    if !version.changed?
+        puts "No version change ... skipping version update"
+    else
+        version.update
+    end
+end
+
+

data/bin/queues

@@ -0,0 +1,8 @@
+begin
+  require 'reliable-msg'
+rescue LoadError
+  require 'rubygems'
+  require_gem 'reliable-msg'
+end
+ReliableMsg::CLI.new.run
+

data/lib/reliable-msg.rb

@@ -0,0 +1,12 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+module ReliableMsg
+
+    PACKAGE = "reliable-msg"
+    VERSION = '1.0.0'
+
+end
+
+require 'reliable-msg/queue'
+require 'reliable-msg/cli'

data/lib/reliable-msg/cli.rb

@@ -0,0 +1,170 @@
+#
+# = cli.rb - Reliable messaging command-line interface
+#
+# Author:: Assaf Arkin  assaf@labnotes.org
+# Documentation:: http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/RubyReliableMessaging
+# Copyright:: Copyright (c) 2005 Assaf Arkin
+# License:: MIT and/or Creative Commons Attribution-ShareAlike
+#
+#--
+# Changes:
+#++
+
+
+require 'drb'
+require 'optparse'
+require 'rdoc/usage'
+require 'reliable-msg/queue-manager'
+
+module ReliableMsg
+
+    class CLI #:nodoc:
+
+        USAGE = <<-EOF
+usage:  queues [-c config] command [args]
+
+To see list of available commands and options
+  queues help
+EOF
+
+        HELP = <<-EOF
+usage:  queues [-c config] command [args]
+
+Reliable messaging queue manager, version #{VERSION}
+
+Available commands:
+
+help
+  Display this help message.
+
+manager start
+  Start the queue manager as a standalone server
+
+manager stop
+  Stop a running queue manager.
+
+install disk [<path>]
+  Configure queue manager to use disk-based message store
+  using the specified directory. Uses 'queues' by default.
+
+install mysql <host> <username> <password> <database> [options]
+              [--port <port>] [--socket <socket>] [--prefix <prefix>]
+  Configure queue manager to use MySQL for message store,
+  using the specified connection properties. Updates database
+  schema.
+
+Options for install mysql are (defaults apply if missing):
+
+--port    Port to connect to
+--socket  Socket to connect to
+--prefix  Prefix for table names
+
+EOF
+
+        class InvalidUsage  < Exception
+        end
+
+        def initialize
+        end
+
+        def run
+            begin
+                config_file = nil
+                opts = OptionParser.new
+                opts.on("-c FILE", "--config FILE", String) { |value| config_file = value }
+                opts.on("-v", "--version") do
+                    puts "Reliable messaging queue manager, version #{VERSION}"
+                    exit
+                end
+                opts.on("-h", "--help") do
+                    puts HELP
+                    exit
+                end
+
+                args = opts.parse(ARGV)
+
+                raise InvalidUsage if args.length < 1
+                case args[0]
+                when 'help'
+                    puts HELP
+
+                when 'manager'
+                    case args[1]
+                    when 'start', nil
+                        manager = QueueManager.new({:config=>config_file})
+                        manager.start
+                        begin
+                            while manager.alive?
+                                sleep 3
+                            end
+                        rescue Interrupt
+                            manager.stop
+                        end
+                    when 'stop'
+                        if config_file
+                            config = Config.new config_file, nil
+                            unless config.load_no_create || config_file.nil?
+                                puts "Could not find configuration file #{config.path}"
+                                exit
+                            end
+                            drb = Config::DEFAULT_DRB
+                            drb.merge(config.drb) if config.drb
+                            drb_uri = "druby://localhost:#{drb['port']}"
+                        else
+                            drb_uri = Queue::DEFAULT_DRB
+                        end
+                        begin
+                            DRbObject.new(nil, drb_uri).stop
+                        rescue DRb::DRbConnError =>error
+                            puts "No queue manager at #{drb_uri}"
+                        end
+                    else
+                        raise InvalidUsage
+                    end
+
+                when 'install'
+                    config = Config.new config_file, nil
+                    case args[1]
+                    when 'disk'
+                        store = MessageStore::Disk.new({}, nil)
+                        config.store = store.configuration
+                        if config.create_if_none
+                            store.setup
+                            puts "Created queues configuration file: #{config.path}"
+                        else
+                            puts "Found existing queues configuration file: #{config.path}"
+                            puts "No changes made"
+                        end
+                    when 'mysql'
+                        host, username, password, database = args[2], args[3], args[4], args[5]
+                        raise InvalidUsage unless host && database && username && password
+                        conn = { "host"=>host, "username"=>username, "password"=>password, "database"=>database }
+                        store = MessageStore::MySQL.new(conn, nil)
+                        config.store = store.configuration
+                        if config.create_if_none
+                            puts "Created queues configuration file: #{config.path}"
+                            if store.setup
+                                puts "Created queue manager tables in database '#{database}'"
+                            end
+                        else
+                            puts "Found existing queues configuration file: #{config.path}"
+                            puts "No changes made"
+                        end
+                    else
+                        raise InvalidUsage
+                    end
+                else
+                    raise InvalidUsage
+                end
+            rescue InvalidUsage
+                puts USAGE
+            end
+        end
+
+    end
+
+end
+
+if __FILE__ == $0
+    ReliableMsg::CLI.new.run
+end