brown 1.1.2 → 2.1.0

data/README.md

@@ -0,0 +1,321 @@
+Brown is a "framework for autonomous agents".  That is, essentially, a
+high-falutin' way of saying that you can write some code to do some stuff.
+
+More precisely, Brown agents are (typically) small, standalone blocks of
+code (encapsulated in a single class) which wait for some stimuli, and then
+react to it.  Often, that stimuli is receiving a message (via an AMQP broker
+such as [RabbitMQ](http://rabbitmq.org/), however an agent can do anything
+it pleases (query a database, watch a filesystem, receive HTTP requests,
+whatever) to get stimuli to respond to.
+
+
+# Installation
+
+It's a gem:
+
+    gem install brown
+
+There's also the wonders of [the Gemfile](http://bundler.io):
+
+    gem 'brown'
+
+If you're the sturdy type that likes to run from git:
+
+    rake build; gem install pkg/brown-<whatever>.gem
+
+Or, if you've eschewed the convenience of Rubygems entirely, then you
+presumably know what to do already.
+
+
+# Usage
+
+To make something an agent, you simply create a subclass of `Brown::Agent`.
+You can then use a simple DSL to define "stimuli", each of which (when
+triggered) cause a new instance of the class to be instantiated and a method
+(specified by the stimulus) to be invoked in a separate thread.  You can do
+arbitrary things to detect stimuli, however there are a number of
+pre-defined stimuli you can use to do standard things, like run something
+periodically, or process a message on an AMQP queue.
+
+As a very simple example, say you wanted to print `foo` every five seconds.
+(Yes, you *could* do this in a loop, but humour me, would you?)  Using the
+built-in `every` stimuli, you could do it like this:
+
+    class FooTicker < Brown::Agent
+      every 5 do
+        puts "foo"
+      end
+    end
+
+    FooTicker.run
+
+To demonstrate that each trip of the timer runs in a separate thread, you
+could extend this a little:
+
+    class FooTicker < Brown::Agent
+      every 5 do
+        puts "#{self} is fooing in thread #{Thread.current}"
+      end
+    end
+
+    FooTicker.run
+
+Every five seconds, it should print out a different `FooTicker` and `Thread`
+object.
+
+To show you how `every` is implemented behind the scenes, we can implement
+this directly using the generic method, `stimulate`:
+
+    class FooTicker < Brown::Agent
+      stimulate :foo do |worker|
+        sleep 5
+        worker.call
+      end
+
+      def foo
+        puts "#{self} is fooing in thread #{Thread.current}"
+      end
+    end
+
+    FooTicker.run
+
+What a `stimulate` declaration says is, quite simply:
+
+ * Run this block over and over and over and over again
+ * When the block wants a worker to run, it should run `worker.call`
+ * I'll then create a new instance of the agent class, and call the method
+   name you passed to `stimulate` in a separate thread.
+
+You can pass arguments to the agent method call, by giving them to
+`worker.call`.
+
+
+## AMQP publishing / consumption
+
+Since message-based communication is a common pattern amongst cooperating
+groups of agents, Brown comes with some helpers to make using AMQP painless.
+
+Firstly, to publish a message, you need to declare a publisher, and then use
+it somewhere.  To declare a publisher, you use the `amqp_publisher` method:
+
+    class AmqpPublishingAgent < Brown::Agent
+      amqp_publisher :foo
+    end
+
+There are a number of options you can add to this call, to set the AMQP
+server URL, change the way that the AMQP exchange is declared, and a few
+other things.  For all the details on those, see the API docs for
+{Brown::Agent.amqp_publisher}.
+
+Once you have declared a publisher, you can send messages through it:
+
+    class AmqpPublishingAgent < Brown::Agent
+      amqp_publisher :foo, exchange_name: :foo, exchange_type: :fanout
+
+      every 5 do
+        foo.publish("FOO!")
+      end
+    end
+
+The above example will perform the extremely important task of sending a
+message containing the body `FOO!` every five seconds, forever.  Hopefully
+you can come up with some more practical uses for this functionality.
+
+
+### Consuming Messages
+
+Messages being received are just like any other stimulus: you give a block
+of code to run when a message is received.  In its simplest form, it looks
+like this:
+
+    class AmqpListenerAgent < Brown::Agent
+      amqp_listener :foo do |msg|
+        logger.info "Received message: #{msg.payload}"
+        msg.ack
+      end
+    end
+
+This example sets up a queue to receive messages send to the exchange `foo`,
+and then simply logs every message it receives.  Note the `msg.ack` call;
+this is important so that the broker knows that the message has been
+received and can send you another message.  If you forget to do this, you'll
+only ever receive one message.
+
+The `amqp_listener` method can take a *lot* of different options to
+customise how it works; you'll want to read {Brown::Agent.amqp_listener} to
+find out all about it.
+
+
+## Running agents on the command line
+
+The easiest way to run agents "in production" is to use the `brown` command.
+Simply pass a list of files which contain subclasses of `Brown::Agent`, and
+those classes will be run in individual threads, with automatic restarting.
+Convenient, huh?
+
+
+## Testing
+
+Brown comes with facilities to unit test all of your agents.  Since agents
+simply receive stimuli and act on them, testing is quite simple in
+principle, but the parallelism inherent in agents can make them hard to test
+without some extra helpers.
+
+To enable the additional testing helpers, you must `require
+'brown/test_helpers'` somewhere in your testing setup, before you define
+your agents.  This will add a bunch of extra methods, defined in
+{Brown::TestHelpers} to {Brown::Agent}, which you can then call to examine
+certain aspects of the agent (such as `memo?(name)` and
+`amqp_publisher?(name)`) as well as send stimuli to the agent and have it
+behave appropriately, which you can then make assertions about (either by
+examining the new state of the overall system, or through the use of
+mocks/spies).
+
+While full documentation for all of the helper methods are available in the
+YARD docs for {Brown::TestHelpers}, here are some specific tips for using
+them to test certain aspects of your agents in popular testing frameworks.
+
+
+### RSpec
+
+To test a directly declared stimulus, you don't need to do very much -- you
+can just instantiate the agent class and call the method you want:
+
+    class StimulationAgent < Brown::Agent
+      stimulate :foo do |worker|
+        # Something something
+        worker.call
+      end
+    end
+
+    describe StimulationAgent do
+      it "does something" do
+        subject.foo
+
+        expect(something).to eq(something_else)
+      end
+    end
+
+For memos, you can assert that an agent has a given memo quite easily:
+
+    class MemoAgent < Brown::Agent
+      memo :blargh do
+        "ohai"
+      end
+    end
+
+    describe MemoAgent do
+      it "has the memo" do
+        expect(MemoAgent).to have_memo(:blargh)
+      end
+    end
+
+Then, on top of that, you can assert the value is as you expected, because
+memos are accessable at the class level:
+
+    it "has the right value" do
+      expect(MemoAgent.blargh(:test)).to eq("ohai")
+    end
+
+Or even put it in a let:
+
+    context "value" do
+      let(:value) { MemoAgent.blargh(:test) }
+    end
+
+Note in the above examples that we passed the special value `:test` to the
+call to `.blargh`; that was to let it know that we're definitely testing it
+out.  Recall that, ordinarily, a memo that is declared "unsafe" can only be
+accessed inside a block passed to the memo method.  For testing purposes,
+rather than having to pass a block, we instead just pass in the special
+`:test` symbol and it'll let us get the value back.  Note that this won't
+work unless you have `require`d `'brown/test_helpers'` *before* you defined
+the agent class.
+
+Testing timers is pretty straightforward, too; just trigger away:
+
+    class TimerAgent < Brown::Agent
+      every 10 do
+        $stderr.puts "Tick tock"
+      end
+    end
+
+    describe TimerAgent do
+      it "goes off on time" do
+        expect($stderr).to receive(:info).with("Tick tock")
+
+        TimerAgent.trigger(10)
+      end
+    end
+
+It is pretty trivial to assert that some particular message was published
+via AMQP:
+
+    class PublishTimerAgent < Brown::Agent
+      amqp_publisher :time
+
+      every 86400 do
+        time.publish "One day more!"
+      end
+    end
+
+    describe PublishTimerAgent do
+      it "publishes to schedule" do
+        expect(PublishTimerAgent.time).to receive(:publish).with("One day more!")
+
+        PublishTimerAgent.trigger(86400)
+      end
+    end
+
+Testing what happens when a particular message gets received isn't much
+trickier:
+
+    class ReceiverAgent < Brown::Agent
+      amqp_listener "some_exchange" do |msg|
+        $stderr.puts "Message: #{msg.payload}"
+        msg.ack
+      end
+    end
+
+    describe ReceiverAgent do
+      it "receives the message OK" do
+        expect($stderr).to receive(:puts).with("Message: ohai!")
+
+        was_acked = ReceiverAgent.amqp_receive("some_exchange", "ohai!")
+        expect(was_acked).to be(true)
+      end
+    end
+
+
+### Minitest / other testing frameworks
+
+I don't have any examples for other testing frameworks, because I only use
+RSpec.  Contributions on this topic would be greatly appreciated.
+
+
+# Contributing
+
+Bug reports should be sent to the [Github issue
+tracker](https://github.com/mpalmer/brown/issues), or
+[e-mailed](mailto:theshed+brown@hezmatt.org).  Patches can be sent as a
+Github pull request, or [e-mailed](mailto:theshed+brown@hezmatt.org).
+
+
+# Licence
+
+Unless otherwise stated, everything in this repo is covered by the following
+copyright notice:
+
+    Copyright (C) 2015  Matt Palmer <matt@hezmatt.org>
+
+    This program is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License version 3, as
+    published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/bin/brown

@@ -1,31 +1,91 @@
+#!/usr/bin/env ruby
+
 # Run an agent.  Any agent.
 
 require 'envied'
+require 'logger'
 
 envied_config = (ENVied.config || ENVied::Configuration.new).tap do |cfg|
 	cfg.enable_defaults!
-	cfg.variable :BROWN_ACL_PATH
-	cfg.variable :RABBITMQ_SERVER
+	cfg.variable :AMQP_URL, :string, :default => "amqp://localhost"
 	cfg.variable :BROWN_LOG_LEVEL, :string, :default => "info"
 end
 
 ENVied.require(:default, :config => envied_config)
 
-# Trick smith-using agents into loving us -- since we have a `smith.rb` and
-# we should be the only thing in $LOAD_PATH at the moment, our version will
-# be loaded and the real smith will never darken our door.
-require 'smith'
-
-require *ARGV
+ARGV.each { |f| require f }
 
 agent_classes = ObjectSpace.each_object(Class).select do |k|
 	k != Brown::Agent and k.ancestors.include?(Brown::Agent)
 end
 
-Brown.start(:server_url => ENVied.RABBITMQ_SERVER,
-            :log_level  => ENVied.BROWN_LOG_LEVEL) do
+Brown::Agent.logger = Logger.new($stderr)
+Brown::Agent.logger.level = Logger.const_get(ENVied.BROWN_LOG_LEVEL.upcase.to_sym)
+Brown::Agent.logger.formatter = proc { |s,dt,n,msg| "#{$$} [#{s[0]}] #{msg}\n" }
+
+agents = ThreadGroup.new
+
+def stop_agents(agents)
+	agents.list.each do |th|
+		th[:agent_class] && th[:agent_class].stop
+	end
+end
+
+Signal.trap("INT") do
+	$stderr.puts "Received SIGINT; stopping agents and exiting"
+	stop_agents(agents)
+end
+Signal.trap("TERM") do
+	$stderr.puts "Received SIGTERM; stopping agents and exiting"
+	stop_agents(agents)
+end
+Signal.trap("HUP", "IGNORE")
+Signal.trap("USR1") do
+	Brown::Agent.more_log_detail
+	$stderr.puts "Log level now #{Logger::SEV_LABEL[Brown::Agent.logger.level]}"
+end
+Signal.trap("USR2") do
+	Brown::Agent.less_log_detail
+	$stderr.puts "Log level now #{Logger::SEV_LABEL[Brown::Agent.logger.level]}"
+end
+
+Brown::Agent.logger.info { "Brown starting up..." }
+
+agent_classes.each do |klass|
+	th = Thread.new(klass) do |klass|
+		klass.run
+		Thread[:agent_class] = klass
+	end
+
+	agents.add(th)
+
+	Brown::Agent.logger.info { "Started agent #{klass}" }
+end
+
+loop do
+	sleep 1
+
+	agents.list.each do |th|
+		unless th.alive?
+			begin
+				th.join
+			rescue Exception => ex
+				Brown::Agent.logger.fatal { "Agent #{th[:agent_class]} crashed: #{ex.message} (#{ex.class})" }
+				Brown::Agent.logger.info { ex.backtrace.map { |l| "  #{l}" }.join("\n") }
+			else
+				Brown::Agent.logger.warn "Agent #{th[:agent_class]} terminated itself"
+			end
+			klass = th[:agent_class]
+			th[:agent_class] = nil
+
+			Brown::Agent.logger.info { "Re-starting #{klass} agent" }
 
-	Brown::ACLLoader.load_all(ENVied.BROWN_ACL_PATH.split(":"))
+			th = Thread.new(klass) do |klass|
+				klass.run
+				Thread[:agent_class] = klass
+			end
 
-	agent_classes.each { |k| k.new.run }
+			agents.add(th)
+		end
+	end
 end

data/brown.gemspec

@@ -1,30 +1,40 @@
-require "git-version-bump"
+begin
+	require 'git-version-bump'
+rescue LoadError
+	nil
+end
 
 Gem::Specification.new do |s|
-	s.name    = "brown"
-	s.version = GVB.version
-	s.date    = GVB.date
-
-	s.summary = "Run individual smith agents directly from the command line"
+	s.name = "brown"
 
-	s.licenses = ["GPL-3"]
+	s.version = GVB.version rescue "0.0.0.1.NOGVB"
+	s.date =    GVB.date    rescue Time.now.strftime("%Y-%m-%d")
 
-	s.authors = ["Richard Heycock", "Matt Palmer"]
+	s.platform = Gem::Platform::RUBY
 
-	s.files = `git ls-files -z`.split("\0")
-	s.executables = %w{brown}
+	s.summary  = "Autonomous agent framework"
 
-	s.has_rdoc = false
+	s.authors  = ["Matt Palmer"]
+	s.email    = ["theshed+brown@hezmatt.org"]
+	s.homepage = "http://theshed.hezmatt.org/brown"
 
-	s.add_runtime_dependency "amqp",            "~> 1.4"
-	s.add_runtime_dependency "envied",          "~> 0.8"
-	s.add_runtime_dependency "eventmachine-le", "~> 1.0"
-	s.add_runtime_dependency "extlib",          "~> 0.9"
-	s.add_runtime_dependency "murmurhash3",     "~> 0.1"
-	s.add_runtime_dependency "protobuf",        "~> 3.0"
+	s.files = `git ls-files -z`.split("\0").reject { |f| f =~ /^(G|spec|Rakefile)/ }
+	s.executables = %w{brown}
 
-	s.add_development_dependency "bundler"
-	s.add_development_dependency "github-release"
-	s.add_development_dependency "git-version-bump", "~> 0.10"
-	s.add_development_dependency "rake",             "~> 10.4", ">= 10.4.2"
+	s.required_ruby_version = ">= 2.1.0"
+
+	s.add_runtime_dependency "bunny", "~> 1.7"
+	s.add_runtime_dependency "envied", "~> 0.8"
+
+	s.add_development_dependency 'bundler'
+	s.add_development_dependency 'github-release'
+	s.add_development_dependency 'guard-spork'
+	s.add_development_dependency 'guard-rspec'
+	s.add_development_dependency 'pry-byebug'
+	s.add_development_dependency 'rake', '~> 10.4', '>= 10.4.2'
+	# Needed for guard
+	s.add_development_dependency 'rb-inotify', '~> 0.9'
+	s.add_development_dependency 'redcarpet'
+	s.add_development_dependency 'rspec'
+	s.add_development_dependency 'yard'
 end