brown 1.1.2 → 2.1.0

data/lib/brown/agent/amqp_message.rb

@@ -0,0 +1,42 @@
+# A message received from an AMQP broker.
+#
+# This is what you will get passed to you when you use
+# {Brown::Agent.amqp_listener} to point a shell-like at an exchange.  It
+# allows you to get the message itself, all of the message's metadata, and
+# also act on the message by acknowledging it so the broker can consider it
+# "delivered".
+#
+class Brown::Agent::AMQPMessage
+	# The raw body of the message.  No translation is done on what was sent,
+	# so any serialisation that might have been applied to the message will
+	# have to be undone manually.
+	#
+	# @return [String]
+	#
+	attr_reader :payload
+
+	# Create a new message.  The arguments are a straight copy of what you
+	# get yielded from `Bunny::Queue#subscribe`, or what gets returned from
+	# `Bunny::Queue#pop`.
+	#
+	# @param delivery_info [Bunny::DeliveryInfo, Bunny::GetResponse]
+	#
+	# @param properties [Bunny::MessageProperties]
+	#
+	# @param payload [String]
+	#
+	def initialize(delivery_info, properties, payload)
+		@delivery_info, @properties, @payload = delivery_info, properties, payload
+	end
+
+	# Acknowledge that this message has been processed.
+	#
+	# The broker needs to know that each message has been processed, before
+	# it will remove the message from the queue entirely.  It also won't send
+	# more than a certain number of messages at once, so until you ack a
+	# message, you won't get another one.
+	#
+	def ack
+		@delivery_info.channel.ack(@delivery_info.delivery_tag)
+	end
+end

data/lib/brown/agent/amqp_message_mock.rb

@@ -0,0 +1,28 @@
+#:nodoc:
+#
+# A mock form of the AMQPMessage class, only useful for testing.
+#
+#
+class Brown::Agent::AMQPMessageMock
+	attr_reader :payload
+
+	def initialize(payload:)
+		@payload = payload
+		@acked   = false
+	end
+
+	# Record an ack.
+	def ack
+		if @acked
+			raise RuntimeError,
+			      "Cannot ack a message twice"
+		end
+
+		@acked = true
+	end
+
+	# Check we acked.
+	def acked?
+		@acked
+	end
+end

data/lib/brown/agent/amqp_publisher.rb

@@ -0,0 +1,169 @@
+require 'bunny'
+
+# Publish messages to an AMQP exchange.
+#
+class Brown::Agent::AMQPPublisher
+	#:nodoc:
+	# Sentinel to detect that we've been sent the "default" value,
+	# since `nil` can, sometimes, be a valid value.
+	NoValue = Module.new
+
+	# The top-level exception class for all AMQPPublisher errors.
+	#
+	# If you want to just rescue *anything* untoward relating to an AMQP
+	# Publisher, then catch this.  If you happen to get an instance of this
+	# class, however, then something is wrong.  More wrong than what caused
+	# the exception in the first place, even.
+	#
+	class Error < StandardError; end
+
+	# Indicate a problem at the level of the AMQP broker.
+	#
+	# This could be an issue connecting (name resolution failure, network
+	# connectivity problem, etc), or an authentication or access control
+	# problem.  The message should indicate the exact problem.
+	#
+	class BrokerError < Error; end
+
+	# There has been a problem with the exchange itself.
+	#
+	class ExchangeError < Error; end
+
+	# Create a new AMQPPublisher.
+	#
+	# Setup an exchange in the AMQP broker, and allow the publishing of
+	# messages to that exchange.
+	#
+	# @param amqp_url [#to_s] the AMQP broker to connect to, specified as a
+	#   URL.  The scheme must be `amqp`.  Username and password should be
+	#   given in the standard fashion (`amqp://<user>:<pass>@<host>`).
+	#
+	#   The path portion of AMQP URLs is totes spesh; if you want to
+	#   connect to the default vhost (`/`) you either need to specify *no*
+	#   trailing slash (ie `amqp://hostname`) or percent-encode the `/`
+	#   vhost name (ie `amqp://hostname/%2F`).  Yes, this drives me nuts,
+	#   too.
+	#
+	# @param exchange_type [Symbol] the type of exchange to create or publish
+	#   to.  By default, the exchange is created as a *direct* exchange; this
+	#   routes messages to their destination queue(s) based on the
+	#   `routing_key` (set per-publisher or per-queue).  Other valid values
+	#   for this option are `:direct`, `:topic`, and `:headers`.
+	#
+	# @param exchange_name [#to_s] the name of the exchange to create or
+	#   publish to.  If not specified, then the "default" exchange is used,
+	#   which is a direct exchange that routes to a queue with the same name
+	#   as the routing key.
+	#
+	# @param routing_key [#to_s] The default "routing key" to attach to
+	#   all messages sent via this publisher.  This can also be set (or
+	#   overridden) on a per-message basis; see
+	#   {Brown::Agent::AMQPPublisher#publish}.  If set to `nil`, no routing
+	#   key will be set.
+	#
+	# @param message_type [#to_s] The default type for all messages sent via
+	#   this publisher.  This can also be set (or overridden) on a
+	#   per-message basis; see {Brown::Agent::AMQPPublisher#publish}.  If set
+	#   to `nil`, no message type will be set by default.
+	#
+	# @param logger [Logger] somewhere to log everything.
+	#
+	# @param amqp_opts [Hash] is a "catch-all" hash for any weird and
+	#   wonderful AMQP options you may wish to set by default for all
+	#   messages you send via this publisher.  There are quite a number of
+	#   rather esoteric options, which are not supported especially by
+	#   Brown::Agent::AMQPPublisher, but if you really need them, they're
+	#   here for you.  See [the relevant
+	#   documentation](http://www.rubydoc.info/gems/bunny/Bunny/Exchange#publish-instance_method)
+	#   for full details of every possible permutation.
+	#
+	# @raise [ArgumentError] if the parameters provided are problematic, such
+	#   as specifying an invalid exchange type or exchange name.
+	#
+	# @raise [Brown::Agent::AMQPPublisher::BrokerError] if the attempt to
+	#   connect to the broker fails, due to a lack of connection, or wrong
+	#   credentials.
+	#
+	# @raise [Brown::Agent::AMQPPublisher::ExchangeError] if the attempt to
+	#   create the exchange fails for some reason (such as the exchange
+	#   already existing with a different configuration).
+	#
+	def initialize(amqp_url:      "amqp://localhost",
+	               exchange_type: :direct,
+	               exchange_name: "",
+	               routing_key:   nil,
+	               message_type:  nil,
+	               logger:        Logger.new("/dev/null"),
+	               **amqp_opts
+	              )
+		begin
+			@amqp_session = Bunny.new(amqp_url, logger: logger)
+			@amqp_session.start
+		rescue Bunny::TCPConnectionFailed
+			raise BrokerError,
+			      "Failed to connect to #{amqp_url}"
+		rescue Bunny::PossibleAuthenticationFailureError
+			raise BrokerError,
+			      "Authentication failed for #{amqp_url}"
+		rescue StandardError => ex
+			raise Error,
+			      "Unknown error occured: #{ex.message} (#{ex.class})"
+		end
+
+		@amqp_channel = @amqp_session.create_channel
+
+		begin
+			@amqp_exchange = @amqp_channel.exchange(
+			                   exchange_name,
+			                   type: exchange_type,
+			                   durable: true
+			                 )
+		rescue Bunny::PreconditionFailed => ex
+			raise ExchangeError,
+			      "Failed to open exchange: #{ex.message}"
+		end
+
+		@message_defaults = {
+			:routing_key => routing_key,
+			:type        => message_type
+		}.merge(amqp_opts)
+
+		@channel_mutex = Mutex.new
+	end
+
+	# Publish a message to the exchange.
+	#
+	# @param payload [#to_s] the "body" of the message to send.
+	#
+	# @param type [#to_s] override the default message type set in the
+	#   publisher, just for this one message.
+	#
+	# @param routing_key [#to_s] override the default routing key set in the
+	#   publisher, just for this one message.
+	#
+	# @param amqp_opts [Hash] is a "catch-all" hash for any weird and
+	#   wonderful AMQP options you may wish to set.  There are quite a number
+	#   of rather esoteric options, which are not supported especially by
+	#   Brown::Agent::AMQPPublisher, but if you really need them, they're
+	#   here for you.  See [the relevant
+	#   documentation](http://www.rubydoc.info/gems/bunny/Bunny/Exchange#publish-instance_method)
+	#   for full details of every possible permutation.
+	#
+	def publish(payload, type: NoValue, routing_key: NoValue, **amqp_opts)
+		opts = @message_defaults.merge(
+		          {
+		            type:        type,
+		            routing_key: routing_key
+		          }.delete_if { |_,v| v == NoValue }
+		       ).delete_if { |_,v| v.nil? }.merge(amqp_opts)
+
+		if @amqp_exchange.name == "" and opts[:routing_key].nil?
+			raise ExchangeError,
+			      "Cannot send a message to the default exchange without a routing key"
+		end
+
+		@channel_mutex.synchronize do
+			@amqp_exchange.publish(payload, opts)
+		end
+	end
+end

data/lib/brown/agent/memo.rb

@@ -0,0 +1,64 @@
+#:nodoc:
+# A thread-safe agent "memo".
+#
+# This is the "behind the scenes" code that supports "agent memos", objects
+# which are shared across all instances of a given agent.
+#
+# All of the interesting documentation about how agent memos work is in
+# {Brown::Agent::ClassMethods.memo} and
+# {Brown::Agent::ClassMethods.safe_memo}.
+#
+class Brown::Agent::Memo
+	# Spawn a new memo.
+	#
+	# @param blk [Proc] the block to call to get the value of the memo.
+	#
+	# @param safe [Boolean] whether or not the value in the memo is
+	#   inherently thread-safe for access.  This should only be set when the
+	#   object cannot be changed, or when the object has its own locking to
+	#   protect against concurrent access.  The default is to mark the
+	#   memoised object as "unsafe", in which case all access to the variable
+	#   must be in a block, which is itself executed inside a mutex.
+	#
+	def initialize(blk, safe=false, test=false)
+		@blk         = blk
+		@value_mutex = Mutex.new
+		@attr_mutex  = Mutex.new
+		@safe        = safe
+		@test        = test
+	end
+
+	# Retrieve the value of the memo.
+	#
+	# @return [Object, nil] if called without a block, this will return
+	#   the object which is the value of the memo; otherwise, `nil`.
+	#
+	# @yield [Object] the object which is the value of the memo.
+	#
+	# @raise [RuntimeError] if called on an unsafe memo without passing a
+	#   block.
+	#
+	def value(test=nil)
+		if block_given?
+			@value_mutex.synchronize { yield cached_value }
+			nil
+		else
+			if @safe || (@test && test == :test)
+				cached_value
+			else
+				raise RuntimeError,
+				      "Access to unsafe agent variable prohibited"
+			end
+		end
+	end
+
+	private
+
+	# Retrieve or generate the cached value.
+	#
+	# @return [Object]
+	#
+	def cached_value
+		@attr_mutex.synchronize { @cached_value ||= @blk.call }
+	end
+end

data/lib/brown/agent/stimulus.rb

@@ -0,0 +1,143 @@
+# A single stimulus group in a Brown Agent.
+#
+# This is all the behind-the-scenes plumbing that's required to make the
+# trickiness of stimuli work correctly.  In general, if you're a Brown user
+# and you ever need to do anything with anything in here, something has gone
+# terribly, terribly wrong somewhere.
+#
+class Brown::Agent::Stimulus
+	# The name of the method to call when the stimulus is triggered.
+	#
+	# @return [String]
+	#
+	attr_reader :method_name
+
+	# The chunk of code to call over and over again to listen for the stimulus.
+	#
+	# @return [Proc]
+	#
+	attr_reader :stimuli_proc
+
+	# The class to instantiate to process a stimulus.
+	#
+	# @return [Class]
+	#
+	attr_reader :agent_class
+
+	# Create a new stimulus.
+	#
+	# @param method_name [String] The method to call on an instance of
+	#   `agent_class` to process a single stimulus event.
+	#
+	# @param stimuli_proc [Proc] What to call over and over again to listen
+	#   for new stimulus events.
+	#
+	# @param agent_class [Class] The class to instantiate when processing
+	#   stimulus events.
+	#
+	# @param logger [Logger] Where to log things to for this stimulus.
+	#   If left as the default, no logging will be done.
+	#
+	def initialize(method_name:, stimuli_proc:, agent_class:, logger: Logger.new("/dev/null"))
+		@method_name  = method_name
+		@stimuli_proc = stimuli_proc
+		@agent_class  = agent_class
+		@thread_group = ThreadGroup.new
+		@logger       = logger
+	end
+
+	# Fire off the stimulus listener.
+	#
+	# @param once [Symbol, NilClass] Ordinarily, when the stimulus is run, it
+	#   just keeps going forever (or until stopped, at least).  If you just
+	#   want to run the stimulus listener proc once, and then return, you can
+	#   pass the special symbol `:once` here.
+	#
+	def run(once = nil)
+		if once == :once
+			stimuli_proc.call(->(*args) { process(*args) })
+		else
+			@runner_thread = Thread.current
+			begin
+				while @runner_thread
+					begin
+						stimuli_proc.call(method(:spawn_worker))
+					rescue Brown::StopSignal, Brown::FinishSignal
+						raise
+					rescue Exception => ex
+						log_failure("Stimuli listener", ex)
+					end
+				end
+			rescue Brown::StopSignal
+				stop
+			rescue Brown::FinishSignal
+				finish
+			rescue Exception => ex
+				log_failure("Stimuli runner", ex)
+			end
+		end
+	end
+
+	# Signal the stimulus to immediately shut down everything.
+	#
+	# This will cause all stimulus processing threads to be terminated
+	# immediately.  You probably want to use {#finish} instead, normally.
+	#
+	def stop
+		@thread_group.list.each do |th|
+			th.raise Brown::StopSignal.new("stimulus thread_group")
+		end
+
+		finish
+	end
+
+	# Stop the stimulus listener, and wait gracefull for all currently
+	# in-progress stimuli processing to finish before returning.
+	#
+	def finish
+		if @runner_thread and @runner_thread != Thread.current
+			@runner_thread.raise(Brown::StopSignal.new("stimulus loop"))
+		end
+		@runner_thread = nil
+
+		@thread_group.list.each { |th| th.join }
+	end
+
+	private
+
+	# Process a single stimulus event.
+	#
+	def process(*args)
+		instance = agent_class.new
+
+		if instance.method(method_name).arity == 0
+			instance.__send__(method_name)
+		else
+			instance.__send__(method_name, *args)
+		end
+	end
+
+	# Fire off a new thread to process a single stimulus event.
+	#
+	def spawn_worker(*args)
+		@thread_group.add(
+			Thread.new(args) do |args|
+				begin
+					process(*args)
+				rescue Brown::StopSignal, Brown::FinishSignal
+					# We're OK with this; the thread will now
+					# quietly die.
+				rescue Exception => ex
+					log_failure("Stimulus worker", ex)
+				end
+			end
+		)
+	end
+
+	# Standard log formatting for caught exceptions.
+	#
+	def log_failure(what, ex)
+		@logger.error { "#{what} failed: #{ex.message} (#{ex.class})" }
+		@logger.info  { ex.backtrace.map { |l| "    #{l}" }.join("\n") }
+	end
+end