Sutto-marvin 0.2.1 → 0.2.2

data/README.textile

@@ -1,183 +1,105 @@
 h1. Marvin
 
-Marvin is a simple IRC Framework for Rails suitable for building things
-such as simple IRC bots. Extracted from real use - we'd originally used
-a heavily modified version of MatzBot - it's been built to service a
-particular need.
+Marvin is a ruby irc framework / library built on top of event machine.
+It's been build from scratch to be evented - you build "handlers" which
+are called whenever an event occurs.
 
-h2. Background
-
-The library is designed to be event driven in that it:
-  
-  # Uses the EventMachine library for all network connections
-  # It uses an architecture based on event listeners - called 'handlers'
-
-It's been heavily influenced by rack in terms of design, making it easy
-to do things like chain handlers, write your own functionality and most
-of all making it easy to implement.
+A single client instance can handle multiple IRC connections (and will
+automatically reconnect in the case that a connection is lost). Distributed
+support (e.g. 1 client => multiple handler backends) is built in out of
+the box on top of DRb.
 
 h2. Getting Started
 
-The easiest way to get started with Marvin is by installing the Marvin gem. To
-do this, make sure Github is added to your gem sources (and you are using
-rubygems >= 1.2.0) (by default, substitute username for Sutto):
+Starting out with Marvin is simple. You can either go the "edge" route -
+cloning from the GitHub repository (in this case, [here](http://github.com/sutto/marvin))
+and then running the following:
 
-  $ gem sources -a http://gems.github.com 
-  $ sudo gem install username-marvin
-  
+  $ rake gemspec
+  $ gem build marvin.gemspec
+  $ sudo gem install marvin.gem
 
-Once you have installed the gem, you should have access to the "marvin" command:
+Or, for a generally more stable release you can install it from the GitHub gem
+server (requiring Rubygems >= 1.2.0 with the GitHub sources added), by running
+the following:
 
-  $ marvin --help
+  $ sudo gem install Sutto-marvin
   
-You can create a new marvin folder:
+Installing the gem will make available a new executable - "+marvin+" - which is
+used as an easy way to do a variety of tasks. To get started, you can create
+a project located at given path using the following command:
 
-  $ marvin create my_marvin_project
+  $ marvin create path-to-my-bot
   
-Then simply edit your settings in the +config/settings.yml+
-
-  default:
-    name: Marvin
-    use_logging: false
-    datastore_location: tmp/datastore.json
-  development:
-    user: MarvinBot
-    name: MarvinBot
-    nick:  Marvin
-
-You can use the defaults or configure it. The datastore location
-specifies a relative path where a simple json-backed key value
-store will store persistent information for your client (if chosen).
-Once that's been done, you'll want to setup some connections by editing
-+config/connections.yml+, using the following format:
-
-  "server-address":
-    post: 6667 # Defaults to 6667
-    channels:
-      - "#marvin-testing"
-      - "#relayrelay"
-    nicks:
-      - List
-      - Of
-      - Alternative
-      - Nicks
-  "another-server-address":
-    post: 6667 # Defaults to 6667
-    channels:
-      - "#helloworld"
-
-Which will let marvin connect to multiple servers - autojoining the specific rooms.
-Next, to get started you can simply type:
-
-  $ ./script/client
-
-The bot should join the specified channel and will respond to some simple
-commands by default:
-
-  *YourName*: MarvinBot3000: hello
-  *MarvinBot3000*: YourName: Hola!
+Once that's done, you'll have a blank slate loaded with the default marvin handlers -
++HelloWorld+ (which will respond to any addressed "hello"'s) and an empty debug handler
+which you can use for generic debugging. To run the new app, you can use either of the
+following:
+
+  $ cd path-to-my-bot && script/client
   
-As defined in handlers/hello_world.rb
+or, alternatively,
 
-h2. Thanks
+  $ marvin client path-to-my-bot
+  
+There are a couple of options available for the client (as well as the marvin library),
+Each of which can be found by appending the "--help" option to the command.
 
-Thanks goes out to the following people / projects:
+Once your client has been started (assuming the name wasn't taken / it could connect),
+simply join the chat room your bot was instructed to join and say the following (substiting
+BotNick for the nick name your bot connected with):
 
-* Jeff Rafter - contributed code and doc changes, now one of the co-developers.
-* epitron / halogrium - For the ragel state machine used in Marvin::Parsers::RagelParser
-* The creator of Ruby-IRCD - the server component is heavily influenced by / part derivative of said work.
-
-h2. Marvin::Base - A handler starting point
-
-The first, Marvin::Base provides a base set of methods (e.g. say,
-reply etc etc.) which make writing a client easier. You can simply
-inherit from Marvin::Base, write some logic and then use the class
-method on_event to define responses to events. The passed in meta
-data for each event is then usable via options.attribute_name - an
-openstruct version of the details. e.g.
-
-  class NinjaStuff < Marvin::Base
-    on_event :incoming_message do
-      do_something
-    end
-    def do_something
-      reply options.message # Will echo back the message
-    end
-  end
-    
-Or the like. Also, the halt! method can be called in any subclass to
-halt the handler callback chain.
-
-You also get access to the class method +on_numeric+ which makes
-it relatively easy to respond to a specific numeric reply.
-
-h2. Marvin::CommandHandler - Ridiculously easy Bots
-
-With Marvin::CommandHandler, you get to define seriously
-simple classes which can act as a simple bot. It takes
-great inspiration from "MatzBot":http://github.com/defunkt/matzbot/tree/master
-to make it as easy as possible to make a simple bot
-
-To write a CommandHandler, you simply create a subclass
-(ala ActiveRecord::Base), define a few methods and then
-just use the "exposes" class method. e.g.
-
-  class MySecondExample < Marvin::CommandHandler
-    exposes :hello
-    def hello(data)
-      reply "Hello!"
-    end
-  end
-    
-Where data is an array of parameters. exposed methods will be called
-when they match the following pattern:
-
-  Botname: *exposed-method* *space-seperated-list-meaning-data*
+  BotNick: hello
   
-i.e., the above handler could be called in IRC as such:
+Or even easier, by PM'ing the bot with:
 
-  YourBotsName: hello
-  
-or, even easier, by PM'ing the bot with:
-  
   hello
+  
+Assuming all went well, your bot should reply back with something akin to (where YourNick)
+if the nickname you connected with):
 
-h2. Marvin::MiddleMan - Introducing middleware
+  YourNick: Hola from process with pid 12342
 
-Marvin::MiddleMan lets you insert middleware between handlers
-and you're client - letting you do things such as translating
-all messages on the fly. It's build to be extensible and is
-relatively simple to use. On any Marvin::Base subclass (baring
-the MiddleMan itself), using a middle man is easy - you simply
-call the register! class method with an option argument. e.g:
+h2. Distributed Bots
 
-  HelloWorld.register! Marvin::MiddleMan
+One of the relatively unique features of Marvin is the ability to write bots
+which use DRb and Rinda which can grow with relative ease.
 
-h2. Marvin::DataStore - A dead simple persistent hash store
+It's important to keep in mind that keeping state is discouraged in this case
+as it can not be ensured that clients are still active or that you will always
+get messages from the same client.
 
-Want to save data between when you stop and start your IRC
-Client? With Marvin, it's really, really simple - Marvin::DataStore
-offers a simple syntax for persistent data stores.
+For a start, take a look at the default +config/setup.rb+ file which contains
+an example of registering handlers on a distributed client as well as setting
+up the distributed handler which needs to be setup on the main client.
 
-New datastores can be created with Marvin::DataStore.new("global-store-key").
-From there, you have a hash to do whatever the hell you want. Just
-make sure the data you store is JSON-serializable.
+By default, the messages will be dispatched to the first discovered tuple
+space (using Rinda::RingFinger) and will be of the format:
 
-When you start - stop a server (via Marvin::Loader.run! and Marvin::Loader.stop!)
-you're data will be loaded from and written to disk accordingly.
+  [:marvin_format, :your_namespace, :message_name, {:message => "options"}, client_reference]
+  
+You can change the namespace (which defaults to +:default+) by setting +Marvin::Settings.distributed_namespace+
 
-If you're inside a Marvin::Base subclass it's even easier. You can get a cattr_access
-style accessor for free - just use the "uses_datastore" method. e.g:
+Running a distributed client requires three things:
 
-  class X < Marvin::Base
-    uses_datastore "datastore-global-key", :something
-  end
-  
-Then, self.something will point to the data store - letting you do
-things like:
+* 1 Ring server instance (+script/ring_server+ or +marvin ring_server+ or +marvin rs+)
+* 1+ Client instances (+script/client+ or +marvin client+ or +marvin cl+)
+* 1+ Distributed Client instances (+script/distributed_client+ or +marvin distributed_client+ or +marvin dc+)
 
-  def hello(data)
-    (self.something[from] ||= 0) += 1
-  end
-  
-which will persist the count between each session.
+Each of which takes the default options of:
+* -v - Be verbose and print to STDOUT if not daemonized
+* -level=something - set level, defaults to info
+* -d - daemonize the process
+* -k - kill all daemonized instances of this specific kind
+
+h2. Example Bots
+
+Coming soon.
+
+h2. Thanks
+
+Thanks go to:
+
+* Jeff Rafter - contributed code and doc changes, now one of the co-developers.
+* epitron / halogrium - For the ragel state machine used in Marvin::Parsers::RagelParser
+* The creator of Ruby-IRCD - the server component is heavily influenced by / part derivative of said work.

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-patch: 1
+patch: 2
 major: 0
 minor: 2

data/bin/marvin

@@ -75,7 +75,8 @@ class Marvin < Thor
   end
   
   desc "distributed_client [PATH]", "starts a distributed client from the given location"
-  method_options :verbose => :boolean, :daemon => :boolean, :level => :optional, :kill => :boolean
+  method_options :verbose => :boolean, :daemon => :boolean, :level => :optional,
+                 :kill => :boolean, :nodes => :numeric
   def distributed_client(path = ".")
     @dest = File.expand_path(path)
     start_script(:distributed_client)
@@ -124,7 +125,21 @@ class Marvin < Thor
       extra_args << "-v" if options[:verbose]
       extra_args << "-d" if options[:daemon]
       extra_args << "--level=#{options[:level]}" if options[:level]
-      Dir.chdir(@dest) { exec("script/#{name}", *extra_args) }
+      if options[:daemon] && options[:nodes]
+        nodes = options[:nodes]
+      else
+        nodes = 1
+      end
+      Dir.chdir(@dest) do
+        # Lets you start a number of different processes.
+        # uses system if there are more than 1 nodes, exec
+        # otherwise.
+        if nodes > 1
+          nodes.times { system("script/#{name}", *extra_args) }
+        else
+          exec("script/#{name}", *extra_args)
+        end
+      end
     else
       STDOUT.puts "Woop! #{@dest.gsub(" ", "\\ ")} isn't a marvin app."
     end

data/config/setup.rb

@@ -4,6 +4,9 @@
 # any connections are created
 Marvin::Loader.before_run do
   
+  # Want a non-default namespace? Choose something simple
+  # Marvin::Settings.distributed_namespace = :some_namespace
+  
   # E.G.
   # MyHandler.register! (Marvin::Base subclass) or
   # Marvin::Settings.default_client.register_handler my_handler (a handler instance)

data/lib/marvin/base.rb

@@ -76,6 +76,9 @@ module Marvin
       end
       
       def uses_datastore(datastore_name, local_name)
+        if Marvin::Loader.type == :distributed_client
+          Marvin::Logger.warn "Using datastores inside of a distributed client is a bad idea, mmmkay?"
+        end
         cattr_accessor local_name.to_sym
         self.send("#{local_name}=", Marvin::DataStore.new(datastore_name))
         rescue Exception => e

data/lib/marvin/distributed/dispatch_handler.rb

@@ -46,7 +46,7 @@ module Marvin
       # TODO: Improve it to dump messages to disk at a predefined limit.
       def dispatch(name, options)
         options[:dispatched_at] ||= Time.now
-        tuple = [:marvin_event, name, options, self.client]
+        tuple = [:marvin_event, Marvin::Settings.distributed_namespace, name, options, self.client]
         begin
           (@queued_messages ||= []) << tuple
           if self.ring_server.nil?

data/lib/marvin/distributed/drb_client.rb

@@ -62,8 +62,8 @@ module Marvin
           while !self.stopped
             begin
               unless self.ring_server.blank?
-                event = self.ring_server.take([:marvin_event, nil, nil, nil], 5)
-                dispatch(*event[1..-1]) unless event.blank?
+                event = self.ring_server.take([:marvin_event, Marvin::Settings.distributed_namespace, nil, nil, nil], 2)
+                dispatch(*event[2..-1]) unless event.blank?
               end
             rescue
               # Reset the ring server on event of connection refused etc.

data/lib/marvin/distributed/ring_server.rb

@@ -12,10 +12,10 @@ module Marvin
       def initialize
         self.tuple_space = Rinda::TupleSpace.new
         if Marvin::Settings.log_level == :debug
-          observer = self.tuple_space.notify('write', [:marvin_event, nil, nil, nil])
+          observer = self.tuple_space.notify('write', [:marvin_event, Marvin::Settings.distributed_namespace, nil, nil, nil])
           Thread.start do
             observer.each do |i|
-              event_name, args = i[1][1..2]
+              event_name, args = i[1][2..3]
               Marvin::Logger.logger.debug "Marvin event added - #{event_name.inspect} w/ #{args.inspect}"
             end
           end

data/lib/marvin/settings.rb

@@ -4,7 +4,7 @@ require 'eventmachine'
 module Marvin
   class Settings
     
-    cattr_accessor :environment, :configuration, :is_setup, :default_client,
+    cattr_accessor :environment, :configuration, :is_setup, :default_client, :distributed_namespace,
                    :handler_folder, :default_parser, :log_level, :verbose, :daemon
                    
     self.verbose   = false
@@ -26,6 +26,10 @@ module Marvin
         self.setup!(options)
       end
       
+      def distributed_namespace
+        @@distributed_namespace ||= :default
+      end
+      
       def setup!(options = {})
         self.environment ||= "development"
         self.configuration = {}

data/lib/marvin/status.rb

@@ -39,18 +39,18 @@ module Marvin
           begin
             rs = Rinda::RingFinger.finger.lookup_ring(3)
             STDOUT.puts " Ring Server:        #{rs.__drburi}"
-            items = rs.read_all([:marvin_event, nil, nil, nil])
+            items = rs.read_all([:marvin_event, Marvin::Settings.distributed_namespace, nil, nil, nil])
             STDOUT.puts " Unprocessed Items:  #{items.size}"
             STDOUT.puts ""
             unless items.empty?
-              start_time = items.first[2][:dispatched_at]
+              start_time = items.first[3][:dispatched_at]
               STDOUT.puts  " Earliest Item:     #{start_time ? start_time.strftime("%I:%M%p %d/%m/%y") : "Never"}"
-              end_time   = items.last[2][:dispatched_at]
+              end_time   = items.last[3][:dispatched_at]
               STDOUT.puts  " Latest Item:       #{end_time ? end_time.strftime("%I:%M%p %d/%m/%y") : "Never"}"
               mapping = {}
               items.each do |i|
-                mapping[i[1].inspect] ||= 0
-                mapping[i[1].inspect] += 1
+                mapping[i[2].inspect] ||= 0
+                mapping[i[2].inspect] += 1
               end
               width = mapping.keys.map { |k| k.length }.max
               STDOUT.puts ""

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: Sutto-marvin
 version: !ruby/object:Gem::Version 
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors: 
 - Darcy Laycock
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-12-05 00:00:00 -08:00
+date: 2008-12-07 00:00:00 -08:00
 default_executable: marvin
 dependencies: 
 - !ruby/object:Gem::Dependency