event_state 0.0.1

data/README.rdoc

@@ -0,0 +1,137 @@
+= event_state
+
+* http://github.com/jdleesmiller/event_state
+
+== SYNOPSIS
+
+A small embedded DSL for implementing stateful protocols in EventMachine using
+finite state machines. The protocol is specified in terms of _states_ and
+_messages_. The processing happens in the states, and the messages that can be
+sent or received from each state are declared by name using the DSL.
+
+Here's everyone's favorite example: an echo server. It starts in the
++:listening+ state, in which it can receive a +Noise+ message. It then
+transitions to the +:speaking+ state. After a short delay (+EM.add_timer+), it
+sends the noise back to the client, which causes it to transition back to the
+listening state.
+
+  class MessageEchoServer < EventState::ObjectMachine
+    Noise = Struct.new(:content)
+
+    protocol do
+      state :listening do
+        on_recv Noise, :speaking
+      end
+
+      state :speaking do
+        on_send Noise, :listening
+
+        on_enter do |noise|
+          EM.add_timer 0.5 do
+            send_message Noise.new(noise.content)
+          end
+        end
+      end
+    end
+  end
+
+In a picture (generated from the code above using
+{EventState::Machine.print_state_machine_dot}):
+
+http://github.com/jdleesmiller/event_state/raw/master/assets/echo.png
+
+Here the start state is indicated by a double circle, a blue arrow is a message
+that can be received, and a red arrow is a message that can be sent.
+
+The {EventState::ObjectMachine} base class extends {EventState::Machine}, which
+in turn extends <tt>EventMachine::Connection</tt>. +ObjectMachine+ handles
+serializing and deserializing the ruby objects using
+<tt>EventMachine::ObjectProtocol</tt>, and (by default) it uses the class of the
+message object as the message name. In this example, the message name is
++Noise+. +Machine+ provides the state machine DSL and the primitives for
+handling arbitrary kinds of messages.
+
+Here is the corresponding client and a demo showing how to run it:
+
+  class MessageEchoClient < EventState::ObjectMachine
+    Noise = MessageEchoServer::Noise
+
+    def initialize noises
+      super
+      @noises = noises
+    end
+
+    protocol do
+      state :speaking do
+        on_send Noise, :listening
+
+        on_enter do
+          if @noises.empty?
+            EM.stop
+          else
+            send_message MessageEchoServer::Noise.new(@noises.shift)
+          end
+        end
+      end
+
+      state :listening do
+        on_recv Noise, :speaking
+
+        on_enter do |noise|
+          puts "heard: #{noise.content}"
+        end
+      end
+    end
+
+    def self.demo
+      EM.run do
+        EM.start_server('localhost', 14159, MessageEchoServer)
+        EM.connect('localhost', 14159, MessageEchoClient, %w(foo bar baz))
+      end
+    end
+  end
+
+Output:
+  heard: foo
+  heard: bar
+  heard: baz
+
+== INSTALLATION
+
+Not yet released; will eventually be installable with:
+
+  gem install event_state
+
+== RELATED PROJECTS
+
+This library was inspired by http://slagyr.github.com/statemachine which
+provides a nice DSL for defining state machines but doesn't integrate directly
+with EventMachine. See also the http://www.complang.org/ragel state machine
+compiler and Zed Shaw's http://zedshaw.com/essays/ragel_state_charts.html blog
+post about it.
+
+== LICENSE
+
+(The MIT License)
+
+Copyright (c) 2011 John Lees-Miller
+
+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/lib/event_state/machine.rb

@@ -0,0 +1,467 @@
+module EventState
+  #
+  # Base class for state machines driven by +EventMachine+.
+  #
+  # This class provides a domain-specific language (DSL) for declaring the
+  # structure of the machine. See the {file:README} for examples and the general
+  # idea of how this works.
+  #
+  # If you are sending ruby objects as messages, see {ObjectMachine}; it handles
+  # serialization (using EventMachine's +ObjectProtocol+) and names messages
+  # according to their classes (but you can override this).
+  #
+  # If you have some other kind of messages, then you should subclass this class
+  # directly. Two methods are required:
+  # 1. Override EventMachine's +receive_data+ method to call
+  #    {#transition_on_recv} with the received message.
+  # 2. Override EventMachine's +send_data+ method to call {#transition_on_send}
+  #    with the message to be sent.
+  # Note that {#transition_on_recv} and {#transition_on_send} take a message
+  # _name_ as well as a message. You have to define the mapping from messages
+  # to message names so that the message names correspond with the transitions
+  # declared using the DSL ({on_send} and {on_recv} in particular).
+  #
+  class Machine < EventMachine::Connection
+    class << self
+      #
+      # Declare the protocol; pass a block to declare the {state}s.
+      #
+      # When the block terminates, this method declares any 'implicit' states
+      # that have been referenced by {on_send} or {on_recv} but that have not
+      # been declared with {state}. It also does some basic sanity checking.
+      #
+      # There can be multiple protocol blocks declared for one class; it is
+      # equivalent to moving all of the definitions to the same block.
+      #
+      # @yield [] declare the {state}s in the protocol
+      #
+      # @return [nil]
+      #
+      def protocol
+        raise "cannot nest protocol blocks" if defined?(@protocol) && @protocol
+
+        @start_state = nil unless defined?(@start_state)
+        @states = {}       unless defined?(@states)
+
+        @protocol = true
+        @state = nil
+        yield
+        @protocol = false
+
+        # add implicitly defined states to @states to avoid having to check for
+        # nil states while the machine is running
+        explicit_states = Set[*@states.keys]
+        all_states = Set[*@states.values.map {|state|
+          state.on_sends.values + state.on_recvs.values}.flatten]
+        implicit_states = all_states - explicit_states
+        implicit_states.each do |state_name|
+          @states[state_name] = State.new(state_name)
+        end
+      end
+
+      # 
+      # Exchange sends for receives and receives for sends in the +base+
+      # protocol, and clear all of the {on_enter} and {on_exit} handlers. It
+      # often happens that a server and a client follow protocols with the same
+      # states, but with sends and receives interchanged. This method is
+      # intended to help with this case. You can, for example, reverse a server
+      # and use the passed block to define new {on_enter} and {on_exit} handlers
+      # appropriate for the client.
+      #
+      # The start state is determined by the first state declared in the given
+      # block (not by the protocol being reversed).
+      #
+      # @param [Class] base
+      #
+      # @yield [] define {state}s new {on_enter} and {on_exit} handlers
+      #
+      # @return [nil]
+      #
+      def reverse_protocol base, &block
+        raise "cannot mirror if already have a protocol" if defined?(@protocol)
+
+        @states = Hash[base.states.map {|state_name, state|
+          new_state = EventState::State.new(state_name)
+          new_state.on_recvs = state.on_sends.dup
+          new_state.on_sends = state.on_recvs.dup
+          [state_name, new_state]
+        }]
+
+        protocol(&block)
+      end
+
+      #
+      # Declare a state; pass a block to configure the state using {on_enter},
+      # {on_send} and so on.
+      #
+      # By default, the machine's start state is the first state declared using
+      # this method.
+      #
+      # @yield [] configure the state
+      #
+      # @return [nil]
+      #
+      def state state_name
+        raise "must be called from within a protocol block" unless @protocol
+        raise "cannot nest calls to state" if @state
+
+        # create new state or edit exiting state
+        @state = @states[state_name] || State.new(state_name)
+
+        # configure this state 
+        yield
+
+        # need to know the start state
+        @start_state = @state unless @start_state
+
+        # index by name for easy lookup
+        @states[@state.name] = @state
+
+        # ensure that on_enter etc. aren't callable outside of a state block
+        @state = nil
+      end
+
+      #
+      # Register a block to be called after the machine enters the current
+      # {state}.
+      #
+      # The machine changes state in response to a message being sent or
+      # received, and you can register an {on_enter} handler that is specific
+      # to the message that caused the change. Or you can render a catch-all
+      # block that will be called if no more specific handler was found (see
+      # example below).
+      #
+      # If a catch-all +on_enter+ block is given for the {start_state}, it is
+      # called from EventMachine's +post_init+ method. In this case (and only
+      # this case), the message passed to the block is +nil+.
+      #
+      # @example
+      #   state :foo do
+      #     on_enter :my_message do |message|
+      #       # got here due to a :my_message message
+      #     end
+      #
+      #     on_enter do
+      #       # got here some other way
+      #     end
+      #   end
+      #
+      # @param [Array<Symbol>] message_names zero or more
+      #
+      # @yield [message]
+      #
+      # @yieldparam [Message, nil] message nil iff this is the start state and
+      #             the machine has just started up (called from +post_init+)
+      #
+      # @return [nil]
+      #
+      def on_enter *message_names, &block
+        raise "on_enter must be called from a state block" unless @state
+        if message_names == []
+          raise "on_enter block already given" if @state.default_on_enter
+          @state.default_on_enter = block
+        else
+          save_state_handlers('on_enter', @state.on_enters, message_names,block)
+        end
+        nil
+      end
+
+      #
+      # Register a block to be called after the machine exits the current
+      # {state}. See {on_enter} for more information.
+      #
+      # @param [Array<Symbol>] message_names zero or more
+      #
+      # @yield [message]
+      #
+      # @yieldparam [Message] message
+      #
+      # @return [nil]
+      #
+      def on_exit *message_names, &block
+        raise "on_exit must be called from a state block" unless @state
+        if message_names == []
+          raise "on_exit block already given" if @state.default_on_exit
+          @state.default_on_exit = block
+        else
+          save_state_handlers('on_exit', @state.on_exits, message_names, block)
+        end
+        nil
+      end
+
+      #
+      # Declare which state the machine transitions to when one of the given
+      # messages is sent in this {state}.
+      #
+      # @example
+      #   state :foo do
+      #     on_enter do
+      #       EM.defer proc { sleep 3 },
+      #                proc { send_message DoneMessage.new(42) }
+      #     end
+      #     on_send DoneMessage, :bar
+      #   end
+      #
+      # @param [Array<Symbol>] message_names one or more
+      #
+      # @param [Symbol] next_state_name
+      #
+      # @return [nil]
+      #
+      def on_send *message_names, next_state_name
+        raise "on_send must be called from a state block" unless @state
+        message_names.flatten.each do |name|
+          @state.on_sends[name] = next_state_name
+        end
+      end
+
+      #
+      # Called when EventMachine calls +unbind+ on the connection while it is in
+      # the current state. This may indicate that the connection has been closed
+      # or timed out. The default is to take no action.
+      #
+      # @yield [] called upon +unbind+
+      #
+      # @return [nil]
+      #
+      def on_unbind &block
+        raise "on_unbind must be called from a state block" unless @state
+        @state.on_unbind = block
+        nil
+      end
+
+      #
+      # Declare which state the machine transitions to when one of the given
+      # messages is received in this {state}. See {on_send} for more
+      # information.
+      #
+      # @param [Array<Symbol>] message_names one or more
+      #
+      # @param [Symbol] next_state_name
+      #
+      # @return [nil]
+      #
+      def on_recv *message_names, next_state_name
+        raise "on_recv must be called from a state block" unless @state
+        message_names.flatten.each do |name|
+          @state.on_recvs[name] = next_state_name
+        end
+      end
+
+      #
+      # @return [Hash<Symbol, State>] map from state names (ruby symbols) to
+      #         {State}s
+      #
+      attr_reader :states
+
+      #
+      # @return [State] the machine enters this state when a new connection is
+      #         established
+      #
+      attr_reader :start_state
+
+      #
+      # The complete list of transitions declared in the state machine (an edge
+      # list).
+      #
+      # @return [Array] each entry is of the form <tt>[state_name, [:send |
+      #         :recv, message_name], next_state_name]</tt>
+      #
+      def transitions
+        states.values.map{|state|
+          [[state.on_sends, :send], [state.on_recvs, :recv]].map {|pairs, kind|
+            pairs.map{|message, next_state_name|
+              [state.name, [kind, message], next_state_name]}}}.flatten(2)
+      end
+
+      #
+      # Print the state machine in dot (graphviz) format.
+      #
+      # By default, the 'send' edges are red and 'receive' edges are blue, and
+      # the start state is indicated by a double border.
+      #
+      # @param [Hash] opts extra options
+      #
+      # @option opts [IO] :io (StringIO.new) to print to
+      #
+      # @option opts [String] :graph_options ('') dot graph options
+      #
+      # @option opts [Proc] :message_name_transform transform message names
+      #
+      # @option opts [Proc] :state_name_form transform state names
+      #
+      # @option opts [String] :recv_edge_style ('color=blue')
+      #
+      # @option opts [String] :send_edge_style ('color=red')
+      #
+      # @return [IO] the +:io+ option
+      #
+      def print_state_machine_dot opts={}
+        io                     = opts[:io] || StringIO.new
+        graph_options          = opts[:graph_options] || ''
+        message_name_transform = opts[:message_name_transform] || proc {|x| x}
+        state_name_transform   = opts[:state_name_transform] || proc {|x| x}
+        recv_edge_style        = opts[:recv_edge_style] || 'color=blue'
+        send_edge_style        = opts[:send_edge_style] || 'color=red'
+
+        io.puts "digraph #{self.name.inspect} {\n  #{graph_options}"
+
+        io.puts "  #{start_state.name} [peripheries=2];" # double border
+        
+        transitions.each do |state_name, (kind, message_name), next_state_name|
+          s0 = state_name_transform.call(state_name)
+          s1 = state_name_transform.call(next_state_name)
+          label = message_name_transform.call(message_name)
+
+          style = case kind
+                  when :recv then
+                    "#{recv_edge_style},label=\"#{label}\""
+                  when :send then
+                    "#{send_edge_style},label=\"#{label}\""
+                  else 
+                    raise "unknown kind #{kind}"
+                  end
+          io.puts "  #{s0} -> #{s1} [#{style}];"
+        end
+        io.puts "}"
+
+        io
+      end
+
+      private
+
+      def save_state_handlers handler_type, handlers, message_names, block
+        message_names.flatten.each do |name|
+          raise "#{handler_type} already defined for #{name}" if handlers[name]
+          handlers[name] = block
+        end
+      end 
+    end
+
+    #
+    # Called by +EventMachine+ when a new connection has been established. This
+    # calls the +on_enter+ handler for the machine's start state with a +nil+
+    # message.
+    #
+    # Be sure to call +super+ if you override this method, or the +on_enter+
+    # handler for the start state will not be called.
+    #
+    # @return [nil]
+    #
+    def post_init
+      @state = self.class.start_state
+      @state.call_on_enter self, nil, nil
+      nil
+    end
+
+    #
+    # Called by +EventMachine+ when a connection is closed. This calls the
+    # {on_unbind} handler for the current state. 
+    #
+    # @return [nil]
+    #
+    def unbind
+      #puts "#{self.class} UNBIND"
+      handler = @state.on_unbind
+      self.instance_exec(&handler) if handler 
+      nil
+    end
+
+    #
+    # Move the state machine from its current state to the successor state that
+    # it should be in after receiving the given +message+, according to the
+    # protocol defined using the DSL.
+    #
+    # If the received message is not valid according to the protocol, then the
+    # protocol error handler is called (see {ProtocolError}). 
+    #
+    # The precise order of events is:
+    # 1. the +on_exit+ handler of the current state is called with +message+ 
+    # 2. the current state is set to the successor state
+    # 3. the +on_enter+ handler of the new current state is called with
+    #    +message+
+    #
+    # @param [Object] message_name the name for +message+; this is what relates
+    #        the message data to the transitions defined with {on_send}; must be
+    #        hashable and comparable by value; for example, a symbol, string,
+    #        number or class makes a good message name
+    #
+    # @param [Object] message received
+    #
+    # @return [nil]
+    #
+    def transition_on_recv message_name, message
+      #puts "#{self.class}: RECV #{message_name}"
+      # look up successor state
+      next_state_name = @state.on_recvs[message_name]
+
+      # if there is no registered successor state, it's a protocol error
+      if next_state_name.nil?
+        raise RecvProtocolError.new(self, @state.name, message_name, message)
+      else
+        transition message_name, message, next_state_name
+      end
+
+      nil
+    end
+
+    #
+    # Move the state machine from its current state to the successor state that
+    # it should be in after sending the given +message+, according to the
+    # protocol defined using the DSL.
+    #
+    # If the message to be sent is not valid according to the protocol, then the
+    # protocol error handler is called (see {ProtocolError}). If
+    # the message is valid, then the precise order of events is:
+    # 1. this method yields the message to the supplied block (if any); the
+    #    intention is that the block is used to actually send the message
+    # 2. the +on_exit+ handler of the current state is called with +message+ 
+    # 3. the current state is set to the successor state
+    # 4. the +on_enter+ handler of the new current state is called with
+    #    +message+
+    #
+    # @param [Object] message received
+    #
+    # @param [Object] message_name the name for +message+; this is what relates
+    #        the message data to the transitions defined with {on_send}; must be
+    #        hashable and comparable by value; for example, a symbol, string,
+    #        number or class makes a good message name
+    #
+    # @yield [message] should actually send the message, typically using
+    #        EventMachine's +send_data+ method
+    #
+    # @yieldparam [Object] message the same message passed to this method
+    #
+    # @return [nil]
+    #
+    def transition_on_send message_name, message
+      #puts "#{self.class}: SEND #{message_name}"
+      # look up successor state
+      next_state_name = @state.on_sends[message_name]
+
+      # if there is no registered successor state, it's a protocol error
+      if next_state_name.nil?
+        raise SendProtocolError.new(self, @state.name, message_name, message)
+      else
+        # let the caller send the message before we transition
+        yield message if block_given?
+        
+        transition message_name, message, next_state_name
+      end
+
+      nil
+    end
+
+    private
+    
+    #
+    # Update @state and call appropriate on_exit and on_enter handlers.
+    #
+    def transition message_name, message, next_state_name
+      @state.call_on_exit  self, message_name, message
+      @state = self.class.states[next_state_name]
+      @state.call_on_enter self, message_name, message
+    end
+  end
+end
+

data/lib/event_state/object_machine.rb

@@ -0,0 +1,54 @@
+module EventState
+  #
+  # Base class for a machine in which the messages are ruby objects. See the
+  # {file:README} for examples.
+  #
+  class ObjectMachine < Machine
+    include EventMachine::P::ObjectProtocol
+
+    #
+    # Return the class of the message as the message name. You can override this
+    # method to provide your own mapping from messages to names.
+    #
+    # @param [Object] message
+    #
+    # @return [Object] must be hashable and comparable by value; for example, a
+    #         symbol, string, number or class makes a good message name
+    #
+    def message_name message
+      message.class
+    end
+
+    #
+    # Called by +EventMachine+ (actually, the +ObjectProtocol+) when a message
+    # is received; makes the appropriate transition.
+    #
+    # Note: if you want to receive non-messages as well, you should override
+    # this method in your subclass, and call +super+ only when a message is
+    # received.
+    #
+    # @param [Object] message received
+    #
+    # @return [nil]
+    #
+    def receive_object message
+      transition_on_recv message_name(message), message
+    end
+
+    #
+    # Call <tt>ObjectProtocol</tt>'s +send_object+ on the message and make the
+    # transition.
+    #
+    # @param [Object] message to be sent
+    #
+    # @return [nil]
+    #
+    def send_message message
+      raise "not on the reactor thread" unless EM.reactor_thread?
+      transition_on_send message_name(message), message do |msg|
+        send_object msg
+      end
+    end
+  end
+end
+

data/lib/event_state/state.rb

@@ -0,0 +1,68 @@
+module EventState
+  #
+  # A state in a state machine. This class is for internal use; you will not
+  # usually need to use it directly.
+  #
+  # Note that the <tt>Proc</tt>s stored here are executed in the context of an
+  # instance of a subclass of {Machine}, rather than in the context in which
+  # they were defined.
+  #
+  # @attr [Symbol] name state name
+  #
+  # @attr [Hash<Symbol, Proc>] on_enters map from message names to handlers
+  #
+  # @attr [Proc, nil] default_on_enter called when the state is entered via a
+  #       message that does not have an associated handler in +on_enters+
+  #
+  # @attr [Hash<Symbol, Proc>] on_exits map from message names to handlers
+  #
+  # @attr [Proc, nil] default_on_exit called when the state is exited via a
+  #       message that does not have an associated handler in +on_exits+
+  #
+  # @attr [Hash<Symbol, Symbol>] on_sends map from message names to successor
+  #       state names
+  #
+  # @attr [Hash<Symbol, Symbol>] on_recvs map from message names to successor
+  #       state names
+  #
+  State = Struct.new(:name,
+    :on_enters, :default_on_enter,
+    :on_exits,  :default_on_exit,
+    :on_unbind, :on_sends,  :on_recvs) do
+    def initialize(*)
+      super
+      self.on_enters ||= {}
+      self.on_exits  ||= {}
+      self.on_sends  ||= {}
+      self.on_recvs  ||= {}
+    end
+
+    #
+    # @private
+    #
+    def call_on_enter context, message_name, message
+      call_state_handler context, on_enters, default_on_enter,
+        message_name, message
+    end
+
+    #
+    # @private
+    #
+    def call_on_exit context, message_name, message
+      call_state_handler context, on_exits, default_on_exit,
+        message_name, message
+    end
+
+    private
+
+    def call_state_handler context, handlers, default_handler,
+      message_name, message
+
+      # use message-specific handler if it exists; otherwise use the default
+      handler = handlers[message_name] || default_handler
+
+      # evaluate the block in the right context, namely the machine instance
+      context.instance_exec(message, &handler) if handler 
+    end
+  end
+end

data/lib/event_state/version.rb

@@ -0,0 +1,10 @@
+module EventState
+  # Major version number.
+  VERSION_MAJOR = 0
+  # Minor version number.
+  VERSION_MINOR = 0
+  # Patch number.
+  VERSION_PATCH = 1
+  # Version string.
+  VERSION = [VERSION_MAJOR, VERSION_MINOR, VERSION_PATCH].join('.')
+end

data/lib/event_state.rb

@@ -0,0 +1,78 @@
+require 'eventmachine'
+
+require 'event_state/version'
+require 'event_state/state'
+require 'event_state/machine'
+require 'event_state/object_machine'
+
+#
+# See the {file:README} for details.
+#
+module EventState
+
+  #
+  # Base class for {SendProtocolError} and {RecvProtocolError}.
+  #
+  # You can catch these errors by registering a block with
+  # <tt>EventMachine.error_handler</tt>.
+  #
+  class ProtocolError < RuntimeError
+    def initialize machine, state_name, action, message_name, data
+      @machine, @state_name, @action, @message_name, @data =
+        machine, state_name, action, message_name, data
+    end
+
+    #
+    # @return [Machine] the machine that raised the error
+    #
+    attr_reader :machine
+
+    #
+    # @return [Symbol] the name of the state in which the error occurred
+    #
+    attr_reader :state_name
+
+    #
+    # @return [:recv, :send] whether the error occurred on a send or a receive
+    #
+    attr_reader :action
+
+    #
+    # @return [Object] the name of the message sent or received
+    #
+    attr_reader :message_name
+
+    #
+    # @return [Object] the message / data sent or received
+    #
+    attr_reader :data
+
+    #
+    # @return [String]
+    #
+    def inspect
+      "#<#{self.class}: for #{machine.class} in"\
+        " #{state_name.inspect} state: #{action} #{message_name}>"
+    end
+  end
+
+  #
+  # Error raised by {Machine} when a message that is invalid according to the
+  # machine's protocol is sent.
+  #
+  class SendProtocolError < ProtocolError
+    def initialize machine, state_name, message_name, data
+      super machine, state_name, :send, message_name, data
+    end
+  end
+
+  #
+  # Error raised by {Machine} when a message that is invalid according to the
+  # machine's protocol is received.
+  #
+  class RecvProtocolError < ProtocolError
+    def initialize machine, state_name, message_name, data
+      super machine, state_name, :recv, message_name, data
+    end
+  end
+end

data/test/event_state/event_state_test.rb

@@ -0,0 +1,359 @@
+require 'event_state'
+require 'test/unit'
+
+# load example machines
+require 'event_state/ex_echo'
+require 'event_state/ex_readme'
+require 'event_state/ex_secret'
+
+# give more helpful errors
+Thread.abort_on_exception = true
+
+class TestEventState < Test::Unit::TestCase
+  include EventState
+
+  DEFAULT_HOST = 'localhost'
+  DEFAULT_PORT = 14159
+
+  def run_server_and_client server_class, client_class, opts={}, &block
+    host = opts[:host] || DEFAULT_HOST
+    port = opts[:port] || DEFAULT_PORT
+    server_args = opts[:server_args] || []
+    client_args = opts[:client_args] || []
+
+    client = nil
+    EM.run do
+      EM.error_handler do |e|
+        puts "EM ERROR: #{e.inspect}"
+        puts e.backtrace
+      end
+      EventMachine.start_server(host, port, server_class, *server_args)
+      client = EventMachine.connect(host, port, client_class,
+                                    *client_args, &block)
+    end
+    client
+  end
+
+  def run_echo_test client_class
+    server_log = []
+    recorder = run_server_and_client(LoggingEchoServer, client_class,
+      server_args: [server_log],
+      client_args: [%w(foo bar baz), []]).recorder
+
+    assert_equal [
+      "entering listening state", # on_enter called on the start state
+      "exiting listening state",  # when a message is received
+      "speaking foo",             # the first noise
+      "exiting speaking state",   # sent echo to client
+      "entering listening state", # now listening for next noise
+      "exiting listening state",  # ...
+      "speaking bar",
+      "exiting speaking state",
+      "entering listening state",
+      "exiting listening state",
+      "speaking baz",
+      "exiting speaking state",
+      "entering listening state"], server_log
+  end
+  
+  def test_echo_basic
+    assert_equal %w(foo bar baz), 
+      run_server_and_client(EchoServer, EchoClient,
+        client_args: [%w(foo bar baz), []]).recorder
+  end
+
+  def test_delayed_echo
+    assert_equal %w(foo bar baz), 
+      run_server_and_client(DelayedEchoServer, EchoClient,
+        server_args: [0.5],
+        client_args: [%w(foo bar baz), []]).recorder
+  end
+
+  def test_echo_with_object_protocol_client
+    run_echo_test ObjectProtocolEchoClient
+  end
+
+  def test_echo_with_event_state_client
+    run_echo_test EchoClient
+  end
+
+  def test_secret_server
+    run_server_and_client(TopSecretServer, TopSecretClient)
+  end
+
+  def test_print_state_machine_dot
+    dot = EchoClient.print_state_machine_dot(:graph_options => 'rankdir=LR;')
+    assert_equal <<DOT, dot.string
+digraph "EventState::EchoClient" {
+  rankdir=LR;
+  speaking [peripheries=2];
+  speaking -> listening [color=red,label="String"];
+  listening -> speaking [color=blue,label="String"];
+}
+DOT
+  end
+
+  class TestDSLBasic < EventState::Machine; end
+
+  def test_dsl_basic
+    #
+    # check that we get the transitions right for this simple DSL
+    #
+    trans = nil
+    TestDSLBasic.class_eval do
+      protocol do
+        state :foo do
+          on_recv :hello, :bar
+        end
+        state :bar do 
+          on_recv :good_bye, :foo
+        end
+      end
+      trans = transitions
+    end
+
+    assert_equal [
+      [:foo, [:recv, :hello], :bar],
+      [:bar, [:recv, :good_bye], :foo]], trans
+  end
+
+  class TestDSLNoNestedProtocols < EventState::Machine; end
+
+  def test_dsl_no_nested_states
+    #
+    # nested protocol blocks are illegal
+    #
+    assert_raises(RuntimeError) {
+      TestDSLNoNestedProtocols.class_eval do
+        protocol do
+          protocol do
+          end
+        end
+      end
+    }
+  end
+
+  class TestDSLNoNestedStates < EventState::Machine; end
+
+  def test_dsl_no_nested_states
+    #
+    # nested state blocks are illegal
+    #
+    assert_raises(RuntimeError) {
+      TestDSLNoNestedStates.class_eval do
+        protocol do
+          state :foo do
+            state :bar do
+            end
+          end
+        end
+      end
+    }
+  end
+
+  class TestDSLImplicitState < EventState::Machine; end
+
+  def test_dsl_implicit_state
+    #
+    # if a state is referenced in an on_send or on_recv but is not declared with
+    # state, the protocol method should add it to @states when it terminates
+    #
+    inner_states = nil
+    outer_states = nil
+    TestDSLImplicitState.class_eval do
+      protocol do
+        state :foo do
+          on_send :bar, :baz
+        end
+        inner_states = states.dup
+      end
+      outer_states = states.dup
+    end
+    assert_nil inner_states[:baz]
+    assert_kind_of EventState::State, outer_states[:baz]
+  end
+
+  class TestDelayClient < EventState::ObjectMachine
+    def initialize log, delays
+      super
+      @log = log
+      @delays = delays
+    end
+
+    protocol do
+      state :foo do
+        on_send String, :bar
+        on_enter do
+          EM.defer proc {
+            @log << "sleeping in foo"
+            sleep @delays.shift
+            @log << "finished sleep in foo"
+          }, proc {
+            send_message 'awake!'
+          }
+        end
+        on_unbind do
+          @log << "unbound in foo"
+        end
+      end
+
+      state :bar do
+        on_enter do
+          EM.defer proc {
+            @log << "sleeping in bar"
+            sleep @delays.shift
+            @log << "finished sleep in bar"
+          }, proc {
+            close_connection
+          }
+        end
+        on_unbind do
+          @log << "unbound in bar"
+        end
+      end
+    end
+  end
+
+  class TestUnbindServer < EventState::ObjectMachine
+    def initialize log, timeout
+      super
+      @log = log
+      @timeout = timeout
+    end
+    protocol do
+      state :foo do
+        on_enter do
+          @log << "entered foo"
+          self.comm_inactivity_timeout = @timeout
+        end
+        on_unbind do
+          @log << "unbound in foo"
+          EM.stop
+        end
+
+        on_recv String, :bar
+      end
+      state :bar do
+        on_enter do
+          @log << "entered bar"
+        end
+        on_unbind do
+          @log << "unbound in bar"
+          EM.stop
+        end
+      end
+    end
+  end
+
+  def test_unbind_on_timeout
+    #
+    # first, set delays so that we time out in the first server state (foo)
+    # 
+    server_log = []
+    client_log = []
+    run_server_and_client(TestUnbindServer, TestDelayClient,
+                          server_args: [server_log,  1],
+                          client_args: [client_log, [2,2]])
+    assert_equal [
+      "entered foo",
+      "unbound in foo"], server_log
+
+    # the client log isn't entirely deterministic; depends on threading
+    assert_equal "sleeping in foo", client_log.first
+
+    #
+    # next, set delays so that we time out in the second server state (bar)
+    #
+    server_log = []
+    client_log = []
+    run_server_and_client(TestUnbindServer, TestDelayClient,
+                          server_args: [server_log,  1],
+                          client_args: [client_log, [0.5,2]])
+    assert_equal [
+      "entered foo",
+      "entered bar",
+      "unbound in bar"], server_log
+    assert_equal [
+      "sleeping in foo",
+      "finished sleep in foo",
+      "sleeping in bar",
+      "unbound in bar"], client_log
+  end
+
+  def test_readme_example
+    MessageEchoClient.demo
+  end
+
+  class TestProtocolErrorSend < EventState::ObjectMachine
+    protocol do
+      state :foo do
+        on_send String, :bar
+        on_enter do
+          send_message 42
+        end
+      end
+    end
+  end
+
+  def test_protocol_error_on_send
+    #
+    # TestProtocolErrorSend sends an integer instead of a string; this should
+    # cause an error on the server side; the server doesn't shut down; it just
+    # calls the EM error_handler
+    #
+    error = nil
+    EM.run do
+      EM.error_handler do |e|
+        # we get a ConnectionNotBound error from the client, too
+        error = e if !error
+        EM.stop
+      end
+      EM.start_server DEFAULT_HOST, DEFAULT_PORT, TestProtocolErrorSend 
+      EM.connect DEFAULT_HOST, DEFAULT_PORT do
+        # just want to force the server to init
+      end
+    end
+
+    assert_kind_of SendProtocolError, error
+    assert_kind_of TestProtocolErrorSend, error.machine
+    assert_equal   :foo, error.state_name
+    assert_equal   :send, error.action
+    assert_equal   Fixnum, error.message_name
+    assert_equal   42, error.data
+  end
+
+  class TestProtocolErrorClient < EventState::ObjectMachine
+    protocol do
+      state :foo do
+        on_send Fixnum, :bar
+        on_enter do
+          send_message 42
+        end
+      end
+    end
+  end
+
+  def test_protocol_error_on_recv
+    #
+    # the EchoServer expects a String, but TestProtocolErrorClient gives it an
+    # integer; this causes a protocol error
+    #
+    error = nil
+    EM.run do
+      EM.error_handler do |e|
+        error = e
+        EM.stop
+      end
+      EM.start_server DEFAULT_HOST, DEFAULT_PORT, EchoServer 
+      EM.connect DEFAULT_HOST, DEFAULT_PORT, TestProtocolErrorClient
+    end
+
+    assert_kind_of RecvProtocolError, error
+    assert_kind_of EchoServer, error.machine
+    assert_equal   :listening, error.state_name
+    assert_equal   :recv, error.action
+    assert_equal   Fixnum, error.message_name
+    assert_equal   42, error.data
+  end
+end
+

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: event_state
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- John Lees-Miller
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-11-30 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: eventmachine
+  requirement: &80005190 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.12.10
+  type: :runtime
+  prerelease: false
+  version_requirements: *80005190
+- !ruby/object:Gem::Dependency
+  name: gemma
+  requirement: &80004940 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *80004940
+description: A small embedded DSL for implementing stateful protocols in EventMachine
+  using finite state machines.
+email:
+- jdleesmiller@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.rdoc
+files:
+- lib/event_state/version.rb
+- lib/event_state/object_machine.rb
+- lib/event_state/state.rb
+- lib/event_state/machine.rb
+- lib/event_state.rb
+- README.rdoc
+- test/event_state/event_state_test.rb
+homepage: http://github.com/jdleesmiller/event_state
+licenses: []
+post_install_message: 
+rdoc_options:
+- --main
+- README.rdoc
+- --title
+- event_state-0.0.1 Documentation
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 304276877
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 304276877
+requirements: []
+rubyforge_project: event_state
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: StateMachines for EventMachines.
+test_files:
+- test/event_state/event_state_test.rb