stealth 0.9.1

data/lib/stealth/controller.rb

@@ -0,0 +1,190 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+module Stealth
+  class Controller
+
+    include ActiveSupport::Callbacks
+
+    define_callbacks :action
+
+    attr_reader :current_message, :current_user_id, :current_flow,
+                :current_service, :flow_controller
+
+    def initialize(service_message:, current_flow: nil)
+      @current_message = service_message
+      @current_service = service_message.service
+      @current_user_id = service_message.sender_id
+      @current_flow = current_flow
+    end
+
+    def has_location?
+      current_message.location.present?
+    end
+
+    def has_attachments?
+      current_message.attachments.present?
+    end
+
+    def route
+      raise(Stealth::Errors::ControllerRoutingNotImplemented, "Please implement `route` method in BotController.")
+    end
+
+    def send_replies
+      service_reply = Stealth::ServiceReply.new(
+        recipient_id: current_user_id,
+        yaml_reply: action_replies,
+        context: binding
+      )
+
+      for reply in service_reply.replies do
+        handler = reply_handler.new(
+          recipient_id: current_user_id,
+          reply: reply
+        )
+
+        translated_reply = handler.send(reply.reply_type)
+        client = service_client.new(reply: translated_reply)
+        client.transmit
+
+        # If this was a 'delay' type of reply, let's respect the delay
+        if reply.reply_type == 'delay'
+          begin
+            sleep_duration = Float(reply["duration"])
+            sleep(sleep_duration)
+          rescue ArgumentError, TypeError
+            raise(ArgumentError, 'Invalid duration specified. Duration must be a float.')
+          end
+        end
+      end
+    end
+
+    def flow_controller
+      @flow_controller = begin
+        flow_controller = [current_session.flow_string.pluralize, 'controller'].join('_').classify.constantize
+        flow_controller.new(
+          service_message: @current_message,
+          current_flow: current_flow
+        )
+      end
+    end
+
+    def current_session
+      @current_session ||= Stealth::Session.new(user_id: current_user_id)
+    end
+
+    def action(action: nil)
+      run_callbacks :action do
+        action ||= current_session.state_string
+        flow_controller.send(action)
+      end
+    end
+
+    def step_to(session: nil, flow: nil, state: nil)
+      flow, state = get_flow_and_state(session: session, flow: flow, state: state)
+      step(flow: flow, state: state)
+    end
+
+    def update_session_to(session: nil, flow: nil, state: nil)
+      flow, state = get_flow_and_state(session: session, flow: flow, state: state)
+      update_session(flow: flow, state: state)
+    end
+
+    def step_to_next
+      flow, state = get_next_state
+      step(flow: flow, state: state)
+    end
+
+    def update_session_to_next
+      flow, state = get_next_state
+      update_session(flow: flow, state: state)
+    end
+
+    def self.before_action(*args, &block)
+      set_callback(:action, :before, *args, &block)
+    end
+
+    def self.around_action(*args, &block)
+      set_callback(:action, :around, *args, &block)
+    end
+
+    def self.after_action(*args, &block)
+      set_callback(:action, :after, *args, &block)
+    end
+
+    private
+
+      def reply_handler
+        begin
+          Kernel.const_get("Stealth::Services::#{current_service.capitalize}::ReplyHandler")
+        rescue NameError
+          raise(Stealth::Errors::ServiceNotRecognized, "The service '#{current_service}' was not recognized.")
+        end
+      end
+
+      def service_client
+        begin
+          Kernel.const_get("Stealth::Services::#{current_service.capitalize}::Client")
+        rescue NameError
+          raise(Stealth::Errors::ServiceNotRecognized, "The service '#{current_service}' was not recognized.")
+        end
+      end
+
+      def replies_folder
+        current_session.flow_string.underscore.pluralize
+      end
+
+      def action_replies
+        File.read(File.join(Stealth.root, 'bot', 'replies', replies_folder, "#{current_session.state_string}.yml"))
+      end
+
+      def update_session(flow:, state:)
+        @current_session = Stealth::Session.new(user_id: current_user_id)
+        @current_session.set(flow: flow, state: state)
+      end
+
+      def step(flow:, state:)
+        update_session(flow: flow, state: state)
+        @current_flow = current_session.flow
+
+        action(action: state)
+      end
+
+      def get_flow_and_state(session: nil, flow: nil, state: nil)
+        if session.nil? && flow.nil? && state.nil?
+          raise(ArgumentError, "A session, flow, or state must be specified.")
+        end
+
+        if session.present?
+          return session.flow_string, session.state_string
+        end
+
+        if flow.present?
+          if state.blank?
+            flow_klass = [flow, 'flow'].join('_').classify.constantize
+            state = flow_klass.flow_spec.states.keys.first
+          end
+
+          return flow, state
+        end
+
+        if state.present?
+          return current_session.flow_string, state
+        end
+      end
+
+      def get_next_state
+        current_state_index = current_session.flow.states.index(current_session.state_string.to_sym)
+        next_state = current_session.flow.states[current_state_index + 1]
+        if next_state.nil?
+          raise(
+            Stealth::Errors::InvalidStateTransitions,
+            "The next state after #{current_session.state_string} has not yet been defined."
+          )
+        end
+
+        return current_session.flow_string, next_state
+      end
+
+  end
+end

data/lib/stealth/dispatcher.rb

@@ -0,0 +1,48 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+module Stealth
+
+  # Responsible for coordinating incoming messages
+  #  1. Receives incoming request params
+  #  2. Initializes respective service request handler
+  #  3. Processes params through service request handler (might be async)
+  #  4. Inits base StealthController with state params returned from the service
+  #     request handler
+  #  5. Returns an HTTP response to be returned to the requestor
+  class Dispatcher
+
+    attr_reader :service, :params, :headers, :message_handler
+
+    def initialize(service:, params:, headers:)
+      @service = service
+      @params = params
+      @headers = headers
+      @message_handler = message_handler_klass.new(
+        params: params,
+        headers: headers
+      )
+    end
+
+    def coordinate
+      message_handler.coordinate
+    end
+
+    def process
+      service_message = message_handler.process
+      bot_controller = BotController.new(service_message: service_message)
+      bot_controller.route
+    end
+
+    private
+
+      def message_handler_klass
+        begin
+          Kernel.const_get("Stealth::Services::#{service.capitalize}::MessageHandler")
+        rescue NameError
+          raise(Stealth::Errors::ServiceNotRecognized, "The service '#{service}' was not recognized.")
+        end
+      end
+
+  end
+end

data/lib/stealth/errors.rb

@@ -0,0 +1,32 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+module Stealth
+  class Errors < StandardError
+
+    class ConfigurationError < Errors
+    end
+
+    class ReplyFormatNotSupported < Errors
+    end
+
+    class ServiceImpaired < Errors
+    end
+
+    class ServiceNotRecognized < Errors
+    end
+
+    class ControllerRoutingNotImplemented < Errors
+    end
+
+    class UndefinedVariable < Errors
+    end
+
+    class RedisNotConfigured < Errors
+    end
+
+    class InvalidStateTransition < Errors
+    end
+
+  end
+end

data/lib/stealth/flow/base.rb

@@ -0,0 +1,256 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+require 'stealth/flow/errors'
+require 'stealth/flow/specification'
+require 'stealth/flow/event_collection'
+require 'stealth/flow/event'
+require 'stealth/flow/state'
+
+module Stealth
+  module Flow
+
+    module ClassMethods
+      attr_reader :flow_spec
+
+      def flow(&specification)
+        assign_flow Specification.new(Hash.new, &specification)
+      end
+
+      private
+
+      # Creates the convinience methods like `my_transition!`
+      def assign_flow(specification_object)
+
+        # Merging two workflow specifications can **not** be done automically, so
+        # just make the latest specification win. Same for inheritance -
+        # definition in the subclass wins.
+        if respond_to? :inherited_flow_spec # undefine methods defined by the old flow_spec
+          inherited_flow_spec.states.values.each do |state|
+            state_name = state.name
+            module_eval do
+              undef_method "#{state_name}?"
+            end
+
+            state.events.flat.each do |event|
+              event_name = event.name
+              module_eval do
+                undef_method "#{event_name}!".to_sym
+                undef_method "can_#{event_name}?"
+              end
+            end
+          end
+        end
+
+        @flow_spec = specification_object
+        @flow_spec.states.values.each do |state|
+          state_name = state.name
+          module_eval do
+            define_method "#{state_name}?" do
+              state_name == current_state.name
+            end
+          end
+
+          state.events.flat.each do |event|
+            event_name = event.name
+            module_eval do
+              define_method "#{event_name}!".to_sym do |*args|
+                process_event!(event_name, *args)
+              end
+
+              define_method "can_#{event_name}?" do
+                return !!current_state.events.first_applicable(event_name, self)
+              end
+            end
+          end
+        end
+      end
+    end
+
+    module InstanceMethods
+      attr_accessor :flow_state, :user_id
+
+      def current_state
+        loaded_state = load_flow_state
+        res = spec.states[loaded_state.to_sym] if loaded_state
+        res || spec.initial_state
+      end
+
+      # Return true if the last transition was halted by one of the transition callbacks.
+      def halted?
+        @halted
+      end
+
+      # Return the reason of the last transition abort as set by the previous
+      # call of `halt` or `halt!` method.
+      def halted_because
+        @halted_because
+      end
+
+      def process_event!(name, *args)
+        event = current_state.events.first_applicable(name, self)
+        raise NoTransitionAllowed.new(
+          "There is no event #{name.to_sym} defined for the #{current_state} state") \
+          if event.nil?
+        @halted_because = nil
+        @halted = false
+
+        check_transition(event)
+
+        from = current_state
+        to = spec.states[event.transitions_to]
+
+        run_before_transition(from, to, name, *args)
+        return false if @halted
+
+        begin
+          return_value = run_action(event.action, *args) || run_action_callback(event.name, *args)
+        rescue StandardError => e
+          run_on_error(e, from, to, name, *args)
+        end
+
+        return false if @halted
+
+        run_on_transition(from, to, name, *args)
+
+        run_on_exit(from, to, name, *args)
+
+        transition_value = persist_flow_state(to.to_s)
+
+        run_on_entry(to, from, name, *args)
+
+        run_after_transition(from, to, name, *args)
+
+        return_value.nil? ? transition_value : return_value
+      end
+
+      def halt(reason = nil)
+        @halted_because = reason
+        @halted = true
+      end
+
+      def halt!(reason = nil)
+        @halted_because = reason
+        @halted = true
+        raise TransitionHalted.new(reason)
+      end
+
+      def spec
+        # check the singleton class first
+        class << self
+          return flow_spec if flow_spec
+        end
+
+        c = self.class
+        # using a simple loop instead of class_inheritable_accessor to avoid
+        # dependency on Rails' ActiveSupport
+        until c.flow_spec || !(c.include? Stealth::Flow)
+          c = c.superclass
+        end
+        c.flow_spec
+      end
+
+      def states
+        self.spec.states.keys
+      end
+
+      def init_state(state)
+        res = spec.states[state.to_sym] if state
+        @flow_state = res || spec.initial_state
+        self
+      end
+
+      private
+
+      def check_transition(event)
+        # Create a meaningful error message instead of
+        # "undefined method `on_entry' for nil:NilClass"
+        # Reported by Kyle Burton
+        if !spec.states[event.transitions_to]
+          raise StealthFlowError.new("Event[#{event.name}]'s " +
+              "transitions_to[#{event.transitions_to}] is not a declared state.")
+        end
+      end
+
+      def run_before_transition(from, to, event, *args)
+        instance_exec(from.name, to.name, event, *args, &spec.before_transition_proc) if spec.before_transition_proc
+      end
+
+      def run_on_error(error, from, to, event, *args)
+        if spec.on_error_proc
+          instance_exec(error, from.name, to.name, event, *args, &spec.on_error_proc)
+          halt(error.message)
+        else
+          raise error
+        end
+      end
+
+      def run_on_transition(from, to, event, *args)
+        instance_exec(from.name, to.name, event, *args, &spec.on_transition_proc) if spec.on_transition_proc
+      end
+
+      def run_after_transition(from, to, event, *args)
+        instance_exec(from.name, to.name, event, *args, &spec.after_transition_proc) if spec.after_transition_proc
+      end
+
+      def run_action(action, *args)
+        instance_exec(*args, &action) if action
+      end
+
+      def has_callback?(action)
+        # 1. public callback method or
+        # 2. protected method somewhere in the class hierarchy or
+        # 3. private in the immediate class (parent classes ignored)
+        action = action.to_sym
+        self.respond_to?(action) or
+          self.class.protected_method_defined?(action) or
+          self.private_methods(false).map(&:to_sym).include?(action)
+      end
+
+      def run_action_callback(action_name, *args)
+        action = action_name.to_sym
+        self.send(action, *args) if has_callback?(action)
+      end
+
+      def run_on_entry(state, prior_state, triggering_event, *args)
+        if state.on_entry
+          instance_exec(prior_state.name, triggering_event, *args, &state.on_entry)
+        else
+          hook_name = "on_#{state}_entry"
+          self.send(hook_name, prior_state, triggering_event, *args) if has_callback?(hook_name)
+        end
+      end
+
+      def run_on_exit(state, new_state, triggering_event, *args)
+        if state
+          if state.on_exit
+            instance_exec(new_state.name, triggering_event, *args, &state.on_exit)
+          else
+            hook_name = "on_#{state}_exit"
+            self.send(hook_name, new_state, triggering_event, *args) if has_callback?(hook_name)
+          end
+        end
+      end
+
+      def load_flow_state
+        @flow_state
+      end
+
+      def persist_flow_state(new_value)
+        @flow_state = new_value
+        if defined?($redis)
+          $redis.set(user_id, flow_and_state)
+        end
+      end
+
+      def flow_and_state
+        [self.class.to_s, current_state].join("->")
+      end
+    end
+
+    def self.included(klass)
+      klass.send :include, InstanceMethods
+      klass.extend ClassMethods
+    end
+  end
+end

data/lib/stealth/flow/errors.rb

@@ -0,0 +1,25 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+module Stealth
+  module Flow
+    class Error < StandardError; end
+
+    class TransitionHalted < Error
+
+      attr_reader :halted_because
+
+      def initialize(msg = nil)
+        @halted_because = msg
+        super msg
+      end
+
+    end
+
+    class NoTransitionAllowed < Error; end
+
+    class StealthFlowError < Error; end
+
+    class StealthFlowDefinitionError < Error; end
+  end
+end

data/lib/stealth/flow/event.rb

@@ -0,0 +1,43 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+module Stealth
+  module Flow
+    class Event
+
+      attr_accessor :name, :transitions_to, :meta, :action, :condition
+
+      def initialize(name, transitions_to, condition = nil, meta = {}, &action)
+        @name = name
+        @transitions_to = transitions_to.to_sym
+        @meta = meta
+        @action = action
+        @condition = if condition.nil? || condition.is_a?(Symbol) || condition.respond_to?(:call)
+                       condition
+                     else
+                       raise TypeError, 'condition must be nil, an instance method name symbol or a callable (eg. a proc or lambda)'
+                     end
+      end
+
+      def condition_applicable?(object)
+        if condition
+          if condition.is_a?(Symbol)
+            object.send(condition)
+          else
+            condition.call(object)
+          end
+        else
+          true
+        end
+      end
+
+      def draw(graph, from_state)
+        graph.add_edges(from_state.name.to_s, transitions_to.to_s, meta.merge(:label => to_s))
+      end
+
+      def to_s
+        @name.to_s
+      end
+    end
+  end
+end

data/lib/stealth/flow/event_collection.rb

@@ -0,0 +1,41 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+module Stealth
+  module Flow
+    class EventCollection < Hash
+
+      def [](name)
+        super name.to_sym # Normalize to symbol
+      end
+
+      def push(name, event)
+        key = name.to_sym
+        self[key] ||= []
+        self[key] << event
+      end
+
+      def flat
+        self.values.flatten.uniq do |event|
+          [:name, :transitions_to, :meta, :action].map { |m| event.send(m) }
+        end
+      end
+
+      def include?(name_or_obj)
+        case name_or_obj
+        when Event
+          flat.include? name_or_obj
+        else
+          !(self[name_or_obj].nil?)
+        end
+      end
+
+      def first_applicable(name, object_context)
+        (self[name] || []).detect do |event|
+          event.condition_applicable?(object_context) && event
+        end
+      end
+
+    end
+  end
+end

data/lib/stealth/flow/specification.rb

@@ -0,0 +1,67 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+module Stealth
+  module Flow
+    class Specification
+      attr_accessor :states, :initial_state, :meta,
+        :on_transition_proc, :before_transition_proc, :after_transition_proc, :on_error_proc
+
+      def initialize(meta = {}, &specification)
+        @states = Hash.new
+        @meta = meta
+        instance_eval(&specification)
+      end
+
+      def state_names
+        states.keys
+      end
+
+      private
+
+      def state(name, meta = {:meta => {}}, &events_and_etc)
+        # meta[:meta] to keep the API consistent..., gah
+        new_state = Stealth::Flow::State.new(name, self, meta[:meta])
+        @initial_state = new_state if @states.empty?
+        @states[name.to_sym] = new_state
+        @scoped_state = new_state
+        instance_eval(&events_and_etc) if events_and_etc
+      end
+
+      def event(name, args = {}, &action)
+        target = args[:transitions_to] || args[:transition_to]
+        condition = args[:if]
+        raise StealthFlowDefinitionError.new(
+          "missing ':transitions_to' in workflow event definition for '#{name}'") \
+          if target.nil?
+        @scoped_state.events.push(
+          name, Stealth::Flow::Event.new(name, target, condition, (args[:meta] or {}), &action)
+        )
+      end
+
+      def on_entry(&proc)
+        @scoped_state.on_entry = proc
+      end
+
+      def on_exit(&proc)
+        @scoped_state.on_exit = proc
+      end
+
+      def after_transition(&proc)
+        @after_transition_proc = proc
+      end
+
+      def before_transition(&proc)
+        @before_transition_proc = proc
+      end
+
+      def on_transition(&proc)
+        @on_transition_proc = proc
+      end
+
+      def on_error(&proc)
+        @on_error_proc = proc
+      end
+    end
+  end
+end