symphony 0.10.0.pre20150904120928 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5ac532bca93f670d19204728d5d1cd1d1a887b02
-  data.tar.gz: 9d1ef778dd4d19414739b855cb242f650e15252f
+  metadata.gz: 865650ada7e172f5e4d85096e2dbe1c7bfa01d10
+  data.tar.gz: 9d73f8a431821fa56b641bc57a22b769d1bb6c33
 SHA512:
-  metadata.gz: c592497ebea87cdec1fc14dbb3a854d389fa70d293e148278fca8d7ee9e5e3d8790a3d3b760e30042bff48034f4837c8513b659bf5ccf06645341c51982b4844
-  data.tar.gz: e242316c2b893f106a7f1508ea735cade90f42d2fc208f9d11720eba123ad744cb660bbaa3f5060fd31bc8fde1434f06ed518597331686eaf3d01d17437fc983
+  metadata.gz: e809665983bb7d562c339ecbc21d329d5428eb56da39c5867873a8bf96564cd166bed96bb3e2f6d0ddaea4abf7af48587f480acdb3a8d4e5bf86d335b44d7f7b
+  data.tar.gz: f043bbfa1cbc1cd148744a8de5b9e962f508ce28942c86c00de1977cf101851bd6d4d08a572084b3b267de9c4293372348563b1cc05e6331c60755ba0b07e9c8

data/History.rdoc

@@ -1,3 +1,29 @@
+== v0.10.0 [2016-03-02] Michael Granger <ged@FaerieMUD.org>
+
+Enhancements:
+
+- Add a setting to tasks to force them to always rebind
+- Invert scaling logic to handle initial load
+
+
+== v0.9.2 [2015-07-07] Mahlon E. Smith <mahlon@martini.nu>
+
+Fixes:
+
+- Ensure the work callback's block returns the work() rval, instead of
+  the current time. This fixes Task acknowledgement.
+
+
+== v0.9.1 [2015-06-08] Michael Granger <ged@FaerieMUD.org>
+
+Fixes:
+
+- Make Symphony.tasks contain just the task names.
+  The Daemon will now load task classes on startup. This is so code can
+  depend on Symphony without loading every configured task anytime its
+  config loads.
+
+
 == v0.9.0 [2015-06-01] Michael Granger <ged@FaerieMUD.org>
 
 Improvements:

data/Rakefile

@@ -29,7 +29,7 @@ hoespec = Hoe.spec 'symphony' do |spec|
 	spec.dependency 'configurability', '~> 2.2'
 	spec.dependency 'loggability', '~> 0.10'
 	spec.dependency 'pluggability', '~> 0.4'
-	spec.dependency 'bunny', '~> 1.5'
+	spec.dependency 'bunny', '~> 2.0'
 	spec.dependency 'sysexits', '~> 1.1'
 	spec.dependency 'yajl-ruby', '~> 1.2'
 	spec.dependency 'msgpack', '~> 0.5'

data/USAGE.rdoc

@@ -52,12 +52,12 @@ were connecting to a virtual host called '/test', wanted to log all
 messages to STDERR at a level of 'debug', and had an exchange called
 'symphony' (the default):
 
-	amqp:
-		broker_uri: amqp://USERNAME:PASSWORD@example.com:5672/%2Ftest
-		exchange: symphony
+    amqp:
+        broker_uri: amqp://USERNAME:PASSWORD@example.com:5672/%2Ftest
+        exchange: symphony
 
-	logging:
-		symphony: debug STDERR (color)
+    logging:
+        symphony: debug STDERR (color)
 
 
 Symphony won't create the exchange for you, it is expected to
@@ -78,26 +78,26 @@ calling #run on the class itself.
 
 == The Simplest Task
 
-	#!/usr/bin/env ruby
-	
-	require 'symphony'
-	
-	class Test < Symphony::Task
-		
-		# Process all events
-		subscribe_to '#'
-		
-		def work( payload, metadata )
-			puts "I received an event: %p with a payload of %p" % [
-				metadata[ :delivery_info ][ :routing_key ],
-				payload
-			]
-			return true
-		end
-	end
-	
-	Symphony.load_config( 'etc/config.yml' )
-	Test.run
+    #!/usr/bin/env ruby
+    
+    require 'symphony'
+    
+    class Test < Symphony::Task
+        
+        # Process all events
+        subscribe_to '#'
+        
+        def work( payload, metadata )
+            puts "I received an event: %p with a payload of %p" % [
+                metadata[ :delivery_info ][ :routing_key ],
+                payload
+            ]
+            return true
+        end
+    end
+    
+    Symphony.load_config( 'etc/config.yml' )
+    Test.run
 
 
 The only requirement is the 'subscribe_to' clause, which indicates what
@@ -107,10 +107,10 @@ In practice, you'll likely want to be more discerning.  You can specify
 as many comma separated topics as you like for a given task, as well as
 use AMQP wildcard characters.
 
-	# Subscribe to hypothetical creation events for all types,
-	# and deletion events for users.
-	#
-	subscribe_to '#.create, 'users.delete'
+    # Subscribe to hypothetical creation events for all types,
+    # and deletion events for users.
+    #
+    subscribe_to '#.create, 'users.delete'
 
 In this fashion, you can decide to have many separate (and optionally
 distributed) tasks that only respond to a small subset of possible
@@ -126,44 +126,43 @@ workers will receive roughly equal numbers of matching events.
 
 == An Aside on Queues and Binding Behavior
 
-A task will automatically create an auto-delete queue for itself with a
-sane (but configurable) name, along with subscription bindings, ONLY if
-the queue didn't previously exist.  The auto-delete flag ensures that
-when the last worker disconnects, the queue is automatically removed
-from the AMQP broker, setting everything back to the state it was before
-a Symphony worker ever connected.
+By default, a task will automatically create an auto-delete queue for itself
+with a sane (but configurable) name, along with subscription bindings, ONLY if
+the queue didn't previously exist. The auto-delete flag ensures that when the
+last worker disconnects, the queue is automatically removed from the AMQP
+broker, setting everything back to the state it was before a Symphony worker
+ever connected.
 
-Along the same logic as the initial exchange creation, if a matching
-queue exists already for a task name (an automatically generated or
-manually specified name with the 'queue_name' option), then a binding is
-NOT created.  Symphony is 'hands off' for anything server side that
-already exists, so you can enforce specific behaviors, and know that
-Symphony won't fiddle with them.
+Along the same logic as the initial exchange creation, if a matching queue
+exists already for a task name (an automatically generated or manually
+specified name with the 'queue_name' option), then a binding is NOT created by
+default. Symphony defaults to being "hands off" for anything server side that
+already exists, so you can enforce specific behaviors, and know that Symphony
+won't fiddle with them.
 
-This can be confusing if you've created a queue manually for a task,
-and didn't also manually create a binding for the topic key.  There are
-some advanced routing cases where you'll want to set up queues yourself,
-rather than let Symphony automatically create and remove them,
-we'll talk more on that later.
+This can be confusing if you've created a queue manually for a task, and didn't
+also manually create a binding for the topic key. There are some advanced
+routing cases where you'll want to set up queues yourself, rather than let
+Symphony automatically create and remove them, or rebind existing queues on
+startup; we'll talk more on that later.
 
 
 == Return Values
 
-By default, a Task is configured to tell AMQP when it has completed its
-job.  It does this by returning +true+ from the #work method.  When AMQP
-sees the job was completed, the message is considered "delivered", and
-its lifetime is at an end.  If instead, the task returns an explicit
-+false+, the message is retried, potentially on a different task worker.
+By default, a Task is configured to tell AMQP when it has completed its job. It
+does this by returning +true+ from the #work method. When AMQP sees the job was
+completed, the message is considered "delivered", and its lifetime is at an
+end. If instead, the task returns an explicit +false+, the message is retried,
+potentially on a different task worker.
 
-If something within the task raises an exception, the default behavior
-is to permanently abort the task.  If you need different behavior,
-you'll need to catch the exception.  As the task author, you're in the
-best position to know if a failure state requires an immediate retry,
-or a permanent rejection.  If you'll be allowing message retries, you
-might also want to consider publishing messages with a maximum TTL, to
-avoid any situations that could cause jobs to loop infinitely.  (Default
-Max-TTL is an example of something that is settable when creating queues
-on the RabbitMQ server manually.)
+If something within the task raises an exception, the default behavior is to
+permanently abort the task. If you need different behavior, you'll need to
+catch the exception. As the task author, you're in the best position to know if
+a failure state requires an immediate retry, or a permanent rejection. If
+you'll be allowing message retries, you might also want to consider publishing
+messages with a maximum TTL, to avoid any situations that could cause jobs to
+loop infinitely. (Default Max-TTL is an example of something that is settable
+when creating queues on the RabbitMQ server manually.)
 
 
 = Task Options
@@ -176,7 +175,7 @@ considers a message as "delivered" the moment a consumer receives it.
 This can be useful for additional speed when processing non-important
 events.
 
-	acknowledge false   # (default: true)
+    acknowledge false   # (default: true)
 
 
 == Work Model
@@ -195,7 +194,7 @@ fresh process can take its place.  You can do all of your expensive work
 within the #work method, leaving the main "waiting for messages" loop as
 low-resource as possible.
 
-	work_model :oneshot  # (default:  :longlived)
+    work_model :oneshot  # (default:  :longlived)
 
 
 == Message Prefetch
@@ -208,7 +207,7 @@ trade off is that all prefetched message payloads are stored in memory
 until they are processed.  It's a good idea to keep this low if your
 payloads are large.
 
-	prefetch 100   # (default: 10)
+    prefetch 100   # (default: 10)
 
 Message prefetch is ignored (automatically set to 1) if the task's
 work_model is set to oneshot.
@@ -228,26 +227,46 @@ There is no default timeout.  If one is set, the default action is to
 act as an exception, which is a permanent rejection.  You can choose to
 retry instead:
 
-	# perform work for maximum 20 seconds, then stop and try
-	# again on another worker
-	#
-	timeout 20.0, :action => :retry
+    # perform work for maximum 20 seconds, then stop and try
+    # again on another worker
+    #
+    timeout 20.0, :action => :retry
+
 
 == Queue Name
 
 By default, Symphony will try and create a queue based on the Class
 name of the task.  You can override this per-task.
 
-	class Test < Symphony::Task
-		
-		# Process all events
-		subscribe_to '#'
-		
-		# I don't want to connect to a 'test' queue, lets make it interesting:
-		queue_name 'shazzzaaaam'
-			
-		def work( payload, metadata )
-		...
+    class Test < Symphony::Task
+        
+        # Process all events
+        subscribe_to '#'
+        
+        # I don't want to connect to a 'test' queue, lets make it interesting:
+        queue_name 'shazzzaaaam'
+            
+        def work( payload, metadata )
+        ...
+
+
+== Queue Persistence
+
+If you'd rather keep the Symphony queues around even when the workers aren't
+running (to, for example, queue up events for processing when they resume), you
+can tell a task to create a persistent queue instead of an auto-delete queue:
+
+    persistent true
+
+
+== Queue Re-binding
+
+If you want Symphony to re-bind a worker's queue when it starts up, you call tell it to with +always_rebind+:
+
+    always_rebind true
+
+Note that re-binding doesn't *unbind* from the existing pattern/s, so you'll 
+need to account for this in the Task's +work+ method.
 
 
 = Plugins
@@ -262,13 +281,13 @@ of a task worker to the log.  It shows processed message averages and
 resource consumption summaries at the "info" log level, and also changes
 the process name to display a total count and jobs per second rate.
 
-	require 'symphony/metrics'
+    require 'symphony/metrics'
 
-	class Test < Symphony::Task
-		prepend Symphony::Metrics
-		# ...
-	end
-		
+    class Test < Symphony::Task
+        prepend Symphony::Metrics
+        # ...
+    end
+        
 
 == Routing
 
@@ -277,22 +296,22 @@ in the #work method, and instead links individual units of work to
 separate #on declarations.  This makes tasks that are designed to
 receive multiple message topics much easier to maintain and test.
 
-	require 'symphony/routing'
-
-	class Test < Symphony::Task
-		include Symphony::Routing
-		
-		on 'users.create', 'workstation.create' do |payload, metadata|
-			puts "A user or workstation wants to be created!"
-			# ...
-			return true
-		end
-		
-		on 'users.delete' do |payload, metadata|
-			puts "A user wants to be deleted!"
-			return true
-		end
-	end
+    require 'symphony/routing'
+
+    class Test < Symphony::Task
+        include Symphony::Routing
+        
+        on 'users.create', 'workstation.create' do |payload, metadata|
+            puts "A user or workstation wants to be created!"
+            # ...
+            return true
+        end
+        
+        on 'users.delete' do |payload, metadata|
+            puts "A user wants to be deleted!"
+            return true
+        end
+    end
 
 The #on method accepts the same syntax as the 'subscribe_to' option.  In
 fact, if you're using the routing plugin, it removes the requirement of
@@ -300,6 +319,10 @@ fact, if you're using the routing plugin, it removes the requirement of
 match multiple times for a message will be executed in top down order.
 It will only return true (signalling success) if all blocks return true.
 
+This plugin enables +always_rebind+ on your task when it's included so
+that adding a routing pattern will be reflected in the bindings of persistent
+queues.
+
 
 = Publishing messages
 
@@ -311,7 +334,7 @@ If you want to publish or republish from within Symphony, you can
 get a reference to the exchange object Symphony is binding to via
 the Symphony::Queue class:
 
-	exchange = Symphony::Queue.amqp_exchange
+    exchange = Symphony::Queue.amqp_exchange
 
 This is a Bunny object that you can interact with directly.  See the
 Bunny documentation[http://rubybunny.info/articles/exchanges.html] for
@@ -347,9 +370,9 @@ dead letter queue called '_failures', so all errors filter there without
 any further configuration.  New queues have the same policy applied
 automatically.
 
-	% rabbitmqctl list_policies
-	Listing policies ...
-	/     DLX     queues  ^[^_].* {"dead-letter-exchange":"_failures"}    0
+    % rabbitmqctl list_policies
+    Listing policies ...
+    /     DLX     queues  ^[^_].* {"dead-letter-exchange":"_failures"}    0
 
 There is an example task (symphony/lib/tasks/failure_logger.rb)
 that you're welcome to use as a foundation for your error reporting.

data/lib/symphony.rb

@@ -15,7 +15,7 @@ module Symphony
 	VERSION = '0.10.0'
 
 	# Version-control revision constant
-	REVISION = %q$Revision: ade5a2647590 $
+	REVISION = %q$Revision: 6e4811acb073 $
 
 
 	# The name of the environment variable to check for config file overrides

data/lib/symphony/queue.rb

@@ -142,29 +142,20 @@ class Symphony::Queue
 	end
 
 
-	### Return a queue configured for the specified +task_class+.
-	def self::for_task( task_class )
-		args = [
-			task_class.queue_name,
-			task_class.acknowledge,
-			task_class.consumer_tag,
-			task_class.routing_keys,
-			task_class.prefetch,
-			task_class.persistent
-		]
-		return new( *args )
-	end
-
+	##
+	# Syntactic sugar alias
+	singleton_method_alias :for_task, :new
 
 
-	### Create a new Queue with the specified configuration.
-	def initialize( name, acknowledge, consumer_tag, routing_keys, prefetch, persistent )
-		@name          = name
-		@acknowledge   = acknowledge
-		@consumer_tag  = consumer_tag
-		@routing_keys  = routing_keys
-		@prefetch      = prefetch
-		@persistent    = persistent
+	### Create a new Queue for the specified +task_class+.
+	def initialize( task_class )
+		@name          = task_class.queue_name
+		@acknowledge   = task_class.acknowledge
+		@consumer_tag  = task_class.consumer_tag
+		@routing_keys  = task_class.routing_keys
+		@prefetch      = task_class.prefetch
+		@persistent    = task_class.persistent
+		@always_rebind = task_class.always_rebind
 
 		@amqp_queue    = nil
 		@shutting_down = false
@@ -175,27 +166,39 @@ class Symphony::Queue
 	public
 	######
 
+	##
 	# The name of the queue
 	attr_reader :name
 
+	##
 	# Acknowledge mode
 	attr_reader :acknowledge
 
+	##
 	# The tag to use when setting up consumer
 	attr_reader :consumer_tag
 
+	##
 	# The Array of routing keys to use when binding the queue to the exchange
 	attr_reader :routing_keys
 
+	##
 	# The maximum number of un-acked messages to prefetch
 	attr_reader :prefetch
 
+	##
 	# Whether or not to create a persistent queue
 	attr_reader :persistent
 
+	##
+	# Whether or not to re-bind the queue to the exchange during setup
+	attr_predicate :always_rebind
+
+	##
 	# The underlying Bunny::Queue this object manages
 	attr_reader :amqp_queue
 
+	##
 	# The Bunny::Consumer that is dispatching messages for the queue.
 	attr_accessor :consumer
 
@@ -251,27 +254,32 @@ class Symphony::Queue
 	def create_amqp_queue( prefetch_count=DEFAULT_PREFETCH )
 		exchange = self.class.amqp_exchange
 		channel = self.class.amqp_channel
+		created_queue = false
+		queue         = nil
 
 		begin
 			queue = channel.queue( self.name, passive: true )
 			channel.prefetch( prefetch_count )
 			self.log.info "Using pre-existing queue: %s" % [ self.name ]
-			return queue
 		rescue Bunny::NotFound => err
-			self.log.info "%s; using an auto-delete queue instead." % [ err.message ]
+			self.log.info "%s; creating a new queue instead." % [ err.message ]
+			created_queue = true
 			channel = self.class.reset_amqp_channel
 			channel.prefetch( prefetch_count )
 
 			queue = channel.queue( self.name, auto_delete: !self.persistent )
+		end
+
+		if self.always_rebind? || created_queue
 			self.routing_keys.each do |key|
 				self.log.info "  binding queue %s to the %s exchange with topic key: %s" %
 					[ self.name, exchange.name, key ]
 				queue.bind( exchange, routing_key: key )
 			end
+		end
 
 			return queue
 		end
-	end
 
 
 	### Handle each subscribed message.

data/lib/symphony/routing.rb

@@ -21,6 +21,7 @@ module Symphony::Routing
 		mod.singleton_attr_accessor( :routes, :route_options )
 		mod.routes = Hash.new {|h,k| h[k] = [] }
 		mod.route_options = Hash.new {|h,k| h[k] = {} }
+		mod.always_rebind( true )
 	end
 
 

data/lib/symphony/task.rb

@@ -144,6 +144,20 @@ class Symphony::Task
 	class << self; alias_method :routing_keys, :subscribe_to ; end
 
 
+	### Get/set the "always re-bind" flag that causes the queue the task uses to always
+	### re-bind to its exchange when the task starts. The normal behavior is that the queue
+	### is only bound if it didn't already exist, which can mean that you'd need to destroy the
+	### queue to force it to rebind if you change a task's routing keys.
+	def self::always_rebind( new_setting=nil )
+		unless new_setting.nil?
+			self.log.info "%s forced re-binding." % [ new_setting ? "Enabled" : "Disabled" ]
+			@always_rebind = new_setting
+		end
+
+		return @always_rebind
+	end
+
+
 	### Enable or disable acknowledgements.
 	def self::acknowledge( new_setting=nil )
 		unless new_setting.nil?
@@ -231,7 +245,6 @@ class Symphony::Task
 
 
 
-
 	#
 	# Instance Methods
 	#
@@ -346,7 +359,8 @@ class Symphony::Task
 			end
 
 			self.last_worked = Time.now
-	end
+			rval
+		end
 
 		return rval
 	end

data/spec/symphony/queue_spec.rb

@@ -149,6 +149,24 @@ describe Symphony::Queue do
 		end
 
 
+		it "re-binds to an existing queue if the task specifies that it should always re-bind" do
+			testing_task_class.subscribe_to( 'floppy.rabbit.#' )
+			testing_task_class.always_rebind( true )
+			amqp_queue = double( "AMQP queue" )
+
+			expect( described_class.amqp_channel ).to receive( :queue ).
+				with( queue.name, passive: true ).
+				and_return( amqp_queue )
+			expect( described_class.amqp_channel ).to receive( :prefetch ).
+				with( Symphony::Queue::DEFAULT_PREFETCH )
+
+			expect( amqp_queue ).to receive( :bind ).
+				with( described_class.amqp_exchange, routing_key: 'floppy.rabbit.#' )
+
+			expect( queue.create_amqp_queue ).to be( amqp_queue )
+		end
+
+
 		it "subscribes to the message queue with a configured consumer to wait for messages" do
 			amqp_queue = double( "AMQP queue", name: 'a queue', channel: described_class.amqp_channel )
 			consumer = double( "Bunny consumer", channel: described_class.amqp_channel )

data/spec/symphony/routing_spec.rb

@@ -65,6 +65,11 @@ describe Symphony::Routing do
 	end
 
 
+	it "sets an including Task to always rebind so updates are applied to existing queues" do
+		expect( task_class.always_rebind ).to be_truthy
+	end
+
+
 	describe "route-matching" do
 
 		let( :task_class ) do

data/spec/symphony/task_spec.rb

@@ -164,6 +164,12 @@ describe Symphony::Task do
 		end
 
 
+		it "can specify that its queue should always rebind" do
+			task_class.always_rebind( true )
+			expect( task_class.always_rebind ).to be_truthy
+		end
+
+
 		context "an instance" do
 
 			let( :task_class ) do
@@ -245,7 +251,6 @@ describe Symphony::Task do
 		end
 
 
-
 		context "an instance with no #work method" do
 
 			let( :task ) { task_class.new(queue) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: symphony
 version: !ruby/object:Gem::Version
-  version: 0.10.0.pre20150904120928
+  version: 0.10.0
 platform: ruby
 authors:
 - Michael Granger
@@ -31,7 +31,7 @@ cert_chain:
   G8LHR7EjtPPmqCCunfyecJ6MmCNaiJCBxq2NYzyNmluPyHT8+0fuB5kccUVZm6CD
   xn3DzOkDE6NYbk8gC9rTsA==
   -----END CERTIFICATE-----
-date: 2015-09-04 00:00:00.000000000 Z
+date: 2016-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: configurability
@@ -81,14 +81,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: sysexits
   requirement: !ruby/object:Gem::Requirement
@@ -263,14 +263,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.13'
+        version: '3.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.13'
+        version: '3.14'
 description: |-
   Symphony is a subscription-based asynchronous job system. It
   allows you to define jobs that watch for lightweight events from a
@@ -356,12 +356,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: 2.0.3
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.7
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Symphony is a subscription-based asynchronous job system

metadata.gz.sig

@@ -1,3 +1,2 @@
-<hL�sS�ۄ=�����.����^E#��C2��闔�M�͵2�e�
-���f��N�q�E��M����p��Ck[MK�q��6'r�Vz�<�
v޿��5�O�v~�r`�����0,���nb
-�Hκ��jQ=�J��ha�c�	$.L�E�����u��`cw>���\�/�!H�y�c�B����XK!�:l������4��.qS�~vO�G�%.�;���#-�U���̝.�s��R��f�
T��lzU^���
+}HX��I�A���e��ҞNv����(<�����x
C���9�)���sμ+��mנ\'0�Ͱ�MUL_��}�bPd/i�� �{8&
+n�o���P����X3o�����Dj	�M}}BC�eemٿ�W�]���?�XѤ��g�h$��(+d�21�@�؋���;+w}��#a���l2���	���/���&��GV^9������02�6j�