bumbleworks 0.0.4

data/doc/TERMS.md

@@ -0,0 +1,9 @@
+Process Definitions - a map of the assembly line, which dictates where the activities, gateways, events, etc. will be encountered by the product.
+Process Instances - a trip through the assembly line, taken by a single product
+Activities - actions performed by factory workers or robots on the product - carving, painting, cleaning, filling, soldering, etc.
+Gateways - decision points on where the product should go, when the assembly line branches (e.g. larger widgets go to the Big Widget Cleaning Station, smaller ones go to the Small Widget Cleaning Station)
+Message Events, Schedules - pausing the line for a shift change or lunch break, waiting at a certain stage until a needed part has been delivered, etc.
+Workitem/Payload - the Product
+Worker - turning on the power to the Conveyor Belt
+Workflow Engine - the Factory
+  This is an abstract term that encompasses all of the above.  It's a term that's often used in comparison with a "state machine."

data/lib/bumbleworks.rb

@@ -0,0 +1,123 @@
+require "forwardable"
+require "bumbleworks/version"
+require "bumbleworks/configuration"
+require "bumbleworks/support"
+require "bumbleworks/process_definition"
+require "bumbleworks/task"
+require "bumbleworks/participant_registration"
+require "bumbleworks/ruote"
+require "bumbleworks/hash_storage"
+
+module Bumbleworks
+  class UnsupportedMode < StandardError; end
+  class UndefinedSetting < StandardError; end
+  class InvalidSetting < StandardError; end
+
+  class << self
+    extend Forwardable
+    attr_accessor :env
+
+    Configuration.defined_settings.each do |setting|
+      def_delegators :configuration, setting, "#{setting.to_s}="
+    end
+
+    def_delegators Bumbleworks::Ruote, :dashboard, :start_worker!
+    def_delegator Bumbleworks::ProcessDefinition, :define, :define_process
+
+    # @public
+    # Returns the global configuration, or initializes a new
+    # configuration object if it doesn't exist yet.
+    def configuration
+      @configuration ||= begin
+        configuration = Bumbleworks::Configuration.new
+        configuration.add_storage_adapter(Bumbleworks::HashStorage)
+        if defined?(Bumbleworks::Redis::Adapter) && Bumbleworks::Redis::Adapter.auto_register?
+          configuration.add_storage_adapter(Bumbleworks::Redis::Adapter)
+        end
+        if defined?(Bumbleworks::Sequel::Adapter) && Bumbleworks::Sequel::Adapter.auto_register?
+          configuration.add_storage_adapter(Bumbleworks::Sequel::Adapter)
+        end
+        configuration
+      end
+    end
+
+    # @public
+    # Yields the global configurtion to a block.
+    # @yield [configuration] global configuration
+    #
+    # @example
+    #   Bumbleworks.configure do |c|
+    #     c.root = 'path/to/ruote/assets'
+    #   end
+    # @see Bumbleworks::Configuration
+    def configure(&block)
+      unless block
+        raise ArgumentError.new("You tried to .configure without a block!")
+      end
+      yield configuration
+    end
+
+    # @public
+    # Same as .configure, but clears all existing configuration
+    # settings first.
+    # @yield [configuration] global configuration
+    # @see Bumbleworks.configure
+    def configure!(&block)
+      @configuration = nil
+      configure(&block)
+    end
+
+    # @public
+    # Accepts a block for registering participants which
+    # is envoked when start! is called. Notice that a
+    # 'catchall' storage participant is always added to
+    # the end of the list (unless it is defined in the block).
+    #
+    # @example
+    #   Bumbleworks.register_participants do
+    #     painter PainterClass
+    #     builder BuilderClass
+    #     plumber PlumberClass
+    #   end
+    def register_participants(&block)
+      @participant_block = block
+    end
+
+    # @public
+    # Starts a Ruote engine, sets up the storage and registers participants
+    # and process_definitions with the Ruote engine.
+    def start!
+      autoload_and_register_participants
+      load_process_definitions
+    end
+
+    # @public
+    # Resets Bumbleworks - clears configuration and setup variables, and
+    # shuts down the dashboard.
+    def reset!
+      @configuration = nil
+      @participant_block = nil
+      @registered_process_definitions = nil
+      Bumbleworks::Ruote.reset!
+    end
+
+    # @public
+    # Launches the workflow engine with the specified process name.
+    # The process_definiton_name should already be registered with
+    # Bumbleworks.
+    def launch!(process_definition_name, options = {})
+      Bumbleworks::Ruote.launch(process_definition_name, options)
+    end
+
+  private
+
+    def autoload_and_register_participants
+      Bumbleworks::ParticipantRegistration.autoload_all
+      Bumbleworks::Ruote.register_participants(&@participant_block)
+    end
+
+    def load_process_definitions
+      Bumbleworks::ProcessDefinition.create_all_from_directory!(definitions_directory)
+    end
+  end
+end

data/lib/bumbleworks/configuration.rb

@@ -0,0 +1,182 @@
+module Bumbleworks
+  # Stores configruation information
+  #
+  # Configruation inforamtion is loaded from a configuration block defined within
+  # the client application.
+  #
+  # @example Standard settings
+  #   Bumbleworks.configure do |c|
+  #     c.definitions_directory = '/path/to/ruote/definitions/directory'
+  #     c.storage = Redis.new(:host => '127.0.0.1', :db => 0, :thread_safe => true)
+  #     # ...
+  #   end
+  #
+  class Configuration
+    attr_reader :storage_adapters
+
+    class << self
+      def define_setting(name)
+        defined_settings << name
+        attr_accessor name
+      end
+
+      def defined_settings
+        @defined_settings ||= []
+      end
+    end
+
+
+    # Path to the root folder where Bumbleworks assets can be found.
+    # This includes the following structure:
+    #   /lib
+    #     /process_definitions
+    #   /participants
+    #   /app/participants
+    #
+    # default: non, must be specified
+    # Exceptions: raises Bumbleworks::UndefinedSetting if not defined by the client
+    #
+    define_setting :root
+
+    # Path to the folder which holds the ruote definition files. Bumbleworks
+    # will autoload all definition files by recursively traversing the directory
+    # tree under this folder. No specific loading order is guranteed
+    #
+    # default: ${Bumbleworks.root}/lib/process_definitions
+    define_setting :definitions_directory
+
+    # Path to the folder which holds the ruote participant files. Bumbleworks
+    # will autoload all participant files by recursively traversing the directory
+    # tree under this folder. No specific loading order is guranteed
+    #
+    # Bumbleworks will guarantee that these files are autoloaded before registration
+    # of participants.
+    #
+    # default: ${Bumbleworks.root}/participants then ${Bumbleworks.root}/app/participants
+    define_setting :participants_directory
+
+    # Bumbelworks requires a dedicated key-value storage for process information.  Two
+    # storage solutions are currently supported: Redis and Sequel.  You can set the storage
+    # as follows:
+    #
+    # @Exammple: Redis
+    #   Bumbleworks.storage = Redis.new(:host => '127.0.0.1', :db => 0, :thread_safe => true)
+    #
+    # @Example: Sequel with Postgres db
+    #   Bumbleworks.storage = Sequel.connect('postgres://user:password@host:port/database_name')
+    #
+    define_setting :storage
+
+    # By default, a worker will NOT be started when the storage is initialized;
+    # this is the recommended practice since workers should be instantiated in
+    # their own threads, and multiple workers (even on different hosts) can run
+    # simultaneously.  However, if you want a worker to start up immediately
+    # (useful for testing or development), set autostart_worker to true.
+    #
+    # default: false
+    define_setting :autostart_worker
+
+    def initialize
+      @storage_adapters = []
+    end
+
+    # Path where Bumbleworks will look for ruote process defintiions to load.
+    # The path can be relative or absolute.  Relative paths are
+    # relative to Bumbleworks.root.
+    #
+    def definitions_directory
+      @definitions_folder ||= default_definition_directory
+    end
+
+    # Path where Bumbleworks will look for ruote participants to load.
+    # The path can be relative or absolute.  Relative paths are
+    # relative to Bumbleworks.root.
+    #
+    def participants_directory
+      @participants_folder ||= default_participant_directory
+    end
+
+    # Root folder where bumbleworks looks for ruote assets (participants,
+    # process_definitions, ..etc.)  The root path must be absolute.
+    # It can be defined throguh a configuration block:
+    #   Bumbleworks.configure {|c| c.root = '/somewhere'}
+    #
+    # Or directly:
+    #   Bumbleworks.root = '/somewhere/else/'
+    #
+    # If the root is not defined, Bumbleworks will use the root of known
+    # frameworks (Rails, Sinatra and Rory).  Otherwise, it will raise an
+    # error if not defined.
+    #
+    def root
+      @root ||= case
+      when defined?(Rails) then Rails.root
+      when defined?(Rory) then Rory.root
+      when defined?(Sinatra::Application) then Sinatra::Application.root
+      else
+        raise UndefinedSetting.new("Bumbleworks.root must be set") unless @root
+      end
+    end
+
+    # Whether or not we should start a worker when initializing the dashboard
+    # and storage.  Only returns true if set explicitly to true.
+    #
+    def autostart_worker
+      @autostart_worker == true
+    end
+
+    # Add a storage adapter to the set of possible adapters.  Takes an object
+    # that responds to `driver`, `use?(storage)`, and `display_name`.
+    #
+    def add_storage_adapter(storage_adapter)
+      raise ArgumentError, "#{storage_adapter} is not a Bumbleworks storage adapter" unless
+        storage_adapter.respond_to?(:driver) &&
+        storage_adapter.respond_to?(:use?) &&
+        storage_adapter.respond_to?(:display_name)
+
+      @storage_adapters << storage_adapter
+      @storage_adapters
+    end
+
+    # Clears all memoize variables and configuration settings
+    #
+    def clear!
+      defined_settings.each {|setting| instance_variable_set("@#{setting}", nil)}
+      @storage_adapters = []
+      @definitions_folder = @participants_folder = nil
+    end
+
+    private
+    def defined_settings
+      self.class.defined_settings
+    end
+
+    def default_definition_directory
+      default_folders = ['lib/process_definitions']
+      find_folder(default_folders, @definitions_directory, "Definitions folder not found")
+    end
+
+    def default_participant_directory
+      default_folders = ['participants', 'app/participants']
+      find_folder(default_folders, @participants_directory, "Participants folder not found")
+    end
+
+    def find_folder(default_directories, defined_directory, message)
+      # use defined directory structure if defined
+      if defined_directory
+        defined_directory = File.join(root, defined_directory) unless defined_directory[0] == '/'
+      end
+
+      # next look in default directory structure
+      defined_directory ||= default_directories.detect do |default_folder|
+        folder = File.join(root, default_folder)
+        next unless File.directory?(folder)
+        break folder
+      end
+
+      return defined_directory if File.directory?(defined_directory.to_s)
+
+      raise Bumbleworks::InvalidSetting, "#{message}: #{defined_directory}"
+    end
+  end
+end

data/lib/bumbleworks/hash_storage.rb

@@ -0,0 +1,13 @@
+require 'bumbleworks/storage_adapter'
+
+module Bumbleworks
+  class HashStorage < Bumbleworks::StorageAdapter
+    def self.driver
+      ::Ruote::HashStorage
+    end
+
+    def self.display_name
+      'Hash'
+    end
+  end
+end

data/lib/bumbleworks/participant_registration.rb

@@ -0,0 +1,19 @@
+module Bumbleworks
+  class ParticipantRegistration
+    class << self
+      # @public
+      # Autoload all participant classes defined in files in the
+      # participants_directory.  The symbol for autoload comes from the
+      # camelized version of the filename, so this method is dependent on
+      # following that convention.  For example, file `goat_challenge.rb`
+      # should define `GoatChallenge`.
+      #
+      def autoload_all(options = {})
+        options[:directory] ||= Bumbleworks.participants_directory
+        Bumbleworks::Support.all_files(options[:directory], :camelize => true) do |path, name|
+          Object.autoload name.to_sym, path
+        end
+      end
+    end
+  end
+end

data/lib/bumbleworks/process_definition.rb

@@ -0,0 +1,143 @@
+require "bumbleworks/tree_builder"
+
+module Bumbleworks
+  class ProcessDefinition
+    class NotFound < StandardError; end
+    class FileNotFound < StandardError; end
+    class Invalid < StandardError; end
+
+    attr_reader :name, :definition, :tree
+
+    # @public
+    # Initialize a new ProcessDefinition, supplying a name (required), and
+    # definition or a tree (one of which is required).  The definition should
+    # be a string with a Bumbleworks.define_process block, and the tree should
+    # be an actual Ruote tree.
+    #
+    def initialize(opts = {})
+      @name = opts[:name]
+      @definition = opts[:definition]
+      @tree = opts[:tree]
+    end
+
+    # @public
+    # Validates the ProcessDefinition by checking existence and uniqueness of
+    # name, existence of one of definition or tree, and validity of definition.
+    # Raises a Bumbleworks::ProcessDefinition::Invalid exception if errors are
+    # found, otherwise returns true
+    #
+    def validate!
+      errors = []
+      errors << "Name must be specified" unless @name
+      errors << "Definition or tree must be specified" unless @definition || @tree
+      errors << "Name is not unique" if Bumbleworks.dashboard.variables[@name]
+      begin
+        build_tree!
+      rescue Invalid
+        errors << "Definition is not a valid process definition"
+      end
+      raise Invalid, "Validation failed: #{errors.join(', ')}" unless errors.empty?
+      true
+    end
+
+    # @public
+    # Validates first, then adds the tree (builds it if necessary) to the
+    # dashboard's variables.
+    #
+    def save!
+      validate!
+      Bumbleworks.dashboard.variables[@name] = @tree || build_tree!
+      self
+    end
+
+    # @public
+    # Uses the TreeBuilder to construct a tree from the given definition.
+    # Captures any tree building exceptions and reraises them as
+    # Bumbleworks::ProcessDefinition::Invalid exceptions.
+    #
+    def build_tree!
+      return nil unless @definition
+      @tree = Bumbleworks::TreeBuilder.new(
+        :name => name, :definition => definition
+      ).build!
+    rescue Bumbleworks::TreeBuilder::InvalidTree => e
+      raise Invalid, e.message
+    end
+
+    # @public
+    # A definition can be loaded directly from a file (this is the easiest way
+    # to do it, after the .create_all_from_directory! method).  Simply reads
+    # the file at the given path, and set this instance's definition to the
+    # contents of that file.
+    #
+    def load_definition_from_file(path)
+      if File.exists?(path)
+        @definition = File.read(path)
+      else
+        raise FileNotFound, "No file found at #{path}"
+      end
+    end
+
+    class << self
+      # @public
+      # Given a key, will instantiate a new ProcessDefinition populated with the
+      # tree found in the dashboard variables at that key.  If the key isn't
+      # found, an exception is thrown.
+      #
+      def find_by_name(search_key)
+        if saved_tree = Bumbleworks.dashboard.variables[search_key]
+          new(:name => search_key, :tree => saved_tree)
+        else
+          raise NotFound, "No definition by the name of \"#{search_key}\" has been registered yet"
+        end
+      end
+
+      # @public
+      # This method provides a way to define a process definition directly,
+      # without having to create it as a string definition or a tree.  It takes
+      # a block identical to Ruote.define's block, normalizes the definition's
+      # name, and `#create!`s a ProcessDefinition with the resulting tree.
+      #
+      def define(*args, &block)
+        tree_builder = Bumbleworks::TreeBuilder.from_definition(*args, &block)
+        tree_builder.build!
+        create!(:tree => tree_builder.tree, :name => tree_builder.name)
+      end
+
+      # @public
+      # Instantiates a new ProcessDefinition, then `#save`s it.
+      #
+      def create!(opts)
+        pdef = new(opts)
+        pdef.save!
+        pdef
+      end
+
+      # @public
+      # For every *.rb file in the given directory (recursive), creates a new
+      # ProcessDefinition, reading the file's contents for the definition
+      # string.  If the :skip_invalid option is specified, all invalid
+      # definitions are skipped, and everything else is loaded.  Otherwise, the
+      # first invalid definition found triggers a rollback and raises the
+      # exception.
+      #
+      def create_all_from_directory!(directory, opts = {})
+        added_names = []
+        Bumbleworks::Support.all_files(directory) do |path, basename|
+          puts "Registering process definition #{basename} from file #{path}" if opts[:verbose] == true
+          begin
+            create!(:name => basename, :definition => File.read(path))
+            added_names << basename
+          rescue Invalid
+            raise unless opts[:skip_invalid] == true
+          end
+        end
+      rescue Invalid
+        added_names.each do |name|
+          Bumbleworks.dashboard.variables[name] = nil
+        end
+        raise
+      end
+    end
+  end
+end