langrove 0.0.4.5 → 0.0.5.3

data/lib/langrove/adaptor/event_machine_adaptor.rb

@@ -0,0 +1,152 @@
+require 'eventmachine'
+
+module LanGrove
+  
+  module Adaptor
+    
+    class EventMachineAdaptor < Base
+
+      def stop
+        
+        #
+        # OVERRIDE
+        #
+        # Daemon has been called to stop
+        #
+
+      end
+
+      def reload
+
+        #
+        # OVERRIDE
+        # 
+        # Daemon has been called to HUP
+        #
+
+      end
+      
+      def initialize( root, config, deamon_name )
+        
+        super
+        
+      end
+
+      def validate_config
+
+        @type = :event_machine_adaptor
+        
+        @connect  = :tcp
+        @iface    = '127.0.0.1'
+        @port     = 12701
+
+        if @config
+
+          @iface    = @config[ :iface ] if @config.has_key? :iface
+          @port     = @config[ :port ]  if @config.has_key? :port
+          @connect  = @config[ :connect ].to_sym  if @config.has_key? :connect
+          @soc_opts = @config[ :socket_options ] if @config.has_key? :socket_options
+
+        end
+
+        unless @soc_opts.nil?
+
+          unless @soc_opts[ :tls_options ].nil?
+
+            validate_tls_options( @soc_opts[ :tls_options ] )
+
+          end
+
+        else
+
+          @soc_opts = {}
+
+        end
+
+        #
+        # Assign the call signature to eventmachine's
+        # TCP or UDP servers.
+        #
+        @em_server_type = case @connect
+
+          when :tcp
+
+            :start_server
+
+          when :udp
+
+            :open_datagram_socket
+
+          else
+
+            :start_server
+
+        end
+
+      end
+
+      
+      def stop_adaptor
+
+        stop
+
+      end
+
+      def reload_adaptor
+
+        reload
+
+      end
+
+      def validate_tls_options( options )
+
+        unless options[ :private_key_file ].nil?
+
+          options[ :private_key_file ] = path( options[ :private_key_file ] )
+
+        end
+
+        unless options[ :cert_chain_file ].nil?
+
+          options[ :cert_chain_file ] = path( options[ :cert_chain_file ] )
+
+        end
+
+      end
+      
+      def connector( params, &block )
+        
+        handler  = params[ :handler ]
+
+        handler_class = handler[:class]
+        handler_class = @demux.handler unless @demux.nil?
+
+        @logger.info "Starting listen at #{@connect} #{@iface}:#{@port}"
+        
+        EventMachine::send( 
+
+          @em_server_type, 
+          @iface, 
+          @port, 
+          handler_class, 
+          @soc_opts 
+
+        ) do |connected_handler|
+        
+          yield connected_handler if block
+          
+        end
+        
+      end
+
+      def path( partial )
+
+        return "#{DAEMON_ROOT}/#{partial}"
+
+      end
+
+    end
+    
+  end
+  
+end

data/lib/langrove/adaptor/query_adaptor.rb

@@ -0,0 +1,271 @@
+module LanGrove
+  
+  module Adaptor
+    
+    class QueryAdaptor < LanGrove::Adaptor::EventMachineAdaptor
+      
+      #
+      # Used to periodically query a datasource, 
+      # Yields rows as handlers into the daemon's 
+      # event pipeline
+      # 
+
+      def stop
+        
+        #
+        # OVERRIDE
+        #
+        # Daemon has been called to stop
+        #
+
+      end
+
+      def reload
+
+        #
+        # OVERRIDE
+        # 
+        # Daemon has been called to HUP
+        #
+
+      end
+      
+      def validate_config
+        
+        #
+        # OVERRIDE
+        # 
+        # To validate implementation specific config
+        #
+        
+      end
+      
+      def connect
+        
+        #
+        # OVERRIDE
+        # 
+        # To connect to the DataSource
+        #
+        
+      end
+      
+      def running?
+        
+        #
+        # OVERRIDE
+        # 
+        # (optional)
+        # 
+        # Because the query may run asyncronously and 
+        # emply callbacks, this flag should be set so
+        # that it can be determined if a query is active
+        # in the background.
+        # 
+        # Only required if it is necessary to ensure that
+        # never more than 1 concurrent query is running.
+        # 
+        false
+        
+      end
+
+      def stop_adaptor
+
+        stop
+
+      end
+
+      def reload_adaptor
+
+        reload
+
+      end
+      
+      def query( &block )
+        
+        #
+        # OVERRIDE
+        #
+        # To perform the query and yield resulting 'rows'
+        # 
+        # - Should yield one hash of key/value pairs
+        #   per 'row'
+        # 
+        
+        raise LanGrove::PluginException.new( 
+        
+          "#{self.class}.query( ... ) - missing implementation."  
+          
+        )
+        
+      end
+      
+      
+      
+      def initialize( root, config, deamon_name )
+        
+        super
+        
+        #
+        # :run_interval: 
+        # 
+        #  A value in seconds between calling the query. 
+        #           
+        #  If the previous run is not finished a new run 
+        #  will not start if the running?() method is 
+        #  implemented.
+        #  
+        #  The run will be skipped and another :interval: 
+        #  period will pass before the next run is 
+        #  attempted.
+        # 
+        @run_interval = @config[:run_interval]
+        
+        
+        #
+        # :run_once: 
+        # 
+        #  If true will run the query only once and then 
+        #  exit the Daemon.
+        # 
+        @run_once = false
+        @run_once = @config[:run_once]
+        @done_once = false
+        
+        #
+        # :run_immediately: 
+        # 
+        #  If true (the default) will run the query at Daemon 
+        #  start. Otherwise the run will wait :interval: seconds
+        #  after daemon start.
+        # 
+        @run_immediately = @config[:run_immediately]
+        @run_immediately = true if @run_immediately.nil?
+        
+        
+        config_exception(
+        
+          "#{self.class} requires subconfig with :run_interval:"
+        
+        ) if (
+          
+          @run_interval.nil? or
+          not @run_interval.is_a?( Integer )
+          
+        )
+        
+        @query = @config[:query]
+        
+        config_exception(
+        
+          "#{self.class} requires :query: subconfig"
+        
+        ) if @query.nil?
+        
+        validate_config
+        
+        connect
+      
+      end
+     
+      def connector( params, &block )
+        
+        #
+        # Override Handler type if it
+        # is the default (Handler::Socket)
+        # 
+        # Does not override if the Handler 
+        # is user specified.
+        #
+        if params[:handler][:class] == LanGrove::Handler::Socket
+          
+          params[:handler][:class] = LanGrove::Handler::Base
+          
+        end
+        
+        if @run_immediately
+          
+          do_query( params, &block )
+          
+        end
+        
+        EM.add_periodic_timer( @run_interval ) do
+          
+          do_query( params, &block )
+          
+        end
+        
+      end
+      
+      def do_query( params, &block )
+          
+        if running?
+          
+          @logger.info "#{self.class} already running query"
+          
+          return
+          
+        end
+          
+        if @run_once and @done_once
+          
+          @logger.warn "#{self.class} set to :run_once:"
+          Process.kill( 'TERM', Process.pid )
+          return
+          
+        end
+        
+        #
+        # The query may be long blocking
+        # so defer to allow the reactor
+        # to proceed
+        #
+        operation = proc do
+          
+          query do |record|
+            
+            #
+            # Initialize a new Handler
+            #
+            handler = params[:handler][:class].new
+            
+            #
+            # Yield the handler into the daemon,
+            # this will traverse the assignment 
+            # pipeline resulting in the handler
+            # interacting with all configured
+            # server behaviours
+            #
+            yield handler if block
+            
+            #
+            # Pass the record in along the 'reveive'
+            # along with associated event triggers.
+            # 
+            # (For behaviours)
+            #
+            @root.trigger( handler, :handler, :receive )
+            
+            handler.receive( record )
+            
+            @root.trigger( handler, :handler, :after_receive )
+        
+          end
+          
+        end
+        
+        callback = proc do |result|
+          
+          @done_once = true
+          
+        end
+        
+        EM.defer( operation, callback )
+        
+      end
+     
+    end
+    
+  end
+
+end

data/lib/langrove/behaviour/README.md

@@ -0,0 +1,170 @@
+<pre>
+
+  #
+  #  behave |verb| ~ a present tense behad
+  # 
+  #  eg. The ability to sing was being had,
+  # 
+  #      By this one time,
+  # 
+  #      At band camp.
+  #
+
+</pre>
+ 
+LanGrove::Behaviour::Base
+=========================
+
+Defines the interface between the Daemon's [Primary Components](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove#primary-components) and the [Plugins](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/plugin) that perform the Behaviour specified actions upon them.
+
+Behaviour Triggers
+------------------
+
+Behaviours are assigned to action at configurable trigger points in each Daemon module's life cycle.
+
+### [Server](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/server) Triggers
+
+* :server_start
+* :server_stop
+* :server_reload
+
+### [Handler](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/handler) Triggers
+
+* :handler_start
+* :handler_stop
+* :handler_reload
+* :handler_connect
+* :handler_after_connect
+* :handler_disconnect
+* :handler_after_disconnect
+* :handler_first_message
+* :hander_receive
+* :handler_after_receive
+* :handler_error
+
+### [Adaptor](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/adaptor) Triggers
+
+* none
+
+### [Protocol](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/protocol) Triggers
+
+* none
+
+
+Function
+--------
+
+* Behaviour triggers fire via the [Daemon Root](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/root) module.
+* The triggers are called by the Module undergoing the associated event.
+* The call carries reference to the Module
+* The listening behaviour passes the Module reference onward to the [Plugin](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/plugin) configured to perform the action.
+
+
+Configuration
+=============
+
+* Behaviours are assigned to triggers in the :server: subconfig branch.
+* Behaviours are assigned a [Plugin](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/plugin)
+
+
+Behaviours
+----------
+
+### Persistable
+
+Requires a [Persistor](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/plugin#persistor) Plugin
+
+Creates the ability to store and fetch the contents of the [Handler's Capsule](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/handler#the-capsule)
+
+<pre>
+
+:plugins:
+  :save_my_handler_state:
+    :class: ...
+    ...
+    ...
+
+:daemons:
+  :my_daemon
+    ...
+    ...
+    :server:
+      :behaviours:
+        :persistable:
+          :plugin: :save_my_handler_state
+          :at:
+            :handler_after_receive:
+            :handler_disconnect:
+    ...
+    ...
+
+</pre>
+
+
+### Preloadable
+
+Requires a [Persistor](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/plugin#persistor) Plugin
+
+Currently only works with a [Multiplexing Socket Handler](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/handler#socket-multiplexer)
+
+Creates the ability to fetch all previously persisted [Handler Capsules](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/handler#the-capsule) ahead of goind to listen on the socket.
+
+<pre>
+
+:plugins:
+  :my_persistor:
+    :class: ...
+    ...
+    ...
+
+:daemons:
+  :my_daemon
+    ...
+    :handler:
+      :class: SocketMultiplexer
+      :proxy_by: :unique_thing
+      :proxy_to:
+        :handler:
+          :class: ...
+
+    ...
+    :server:
+      :behaviours:
+        
+        #
+        # acts on the nested handler
+        # to store each handler after a modification
+        #
+        :persistable:
+          :plugin: :my_persistor
+          :at:
+            :handler_afer_receive
+        
+        # 
+        # acts on the multiplexer
+        # to reload all handler's state at daemon start 
+        #
+        :preloadable:
+          :plugin: :my_persistor
+          :at:
+            :multiplexer_start:
+    ...
+    ...
+
+</pre>
+
+
+### Enqueueable
+
+
+Requires an [Enqueuer](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/plugin#enqueuer) Plugin
+
+Enqueues a Job onto a specified Queue with the [Handler's Capsule](https://github.com/cluetechnologies/langrove-enterprise/tree/master/lib/langrove/handler#the-capsule) as payload.
+
+
+
+<pre>
+
+  ...pending: config...
+
+</pre>

data/lib/langrove/behaviour/assessable.rb

@@ -0,0 +1,63 @@
+ASSESSABLE_VERSION = 0
+
+module LanGrove
+  
+  module Behaviour
+    
+    class Assessable < Base
+   
+      #
+      # Assessable provides a second persistance for a 'previous' capsule, 
+      # with a built in DELTA detector.
+      # 
+      
+      def initialize( root, config, name )
+        
+        @requires = {
+          
+          #
+          # The Assessor plugin should contain an embedded Persistor plugin.
+          #
+          :assessor => {
+            
+            :actions => [
+              
+              #
+              # Assessor should implement:
+              # 
+              # (In addition to having access to store() and fetch() from
+              #  the nested Persistor)
+              #
+              # <Plugin>.assess( handler )
+              #
+              # - Should use the handler.key to collect from a 
+              #   second persistance the 'previous' capsule 
+              #   contents and - upon comparison with the supplied
+              #   handler.capsule (the latest)
+              # 
+              #   -- emit Notifications on each DELTA
+              #   -- store the new capsule as the 'new previous'
+              # 
+              # - Success assumed.
+              # 
+              # - (on failure) Should THROW
+              #
+              :assess
+              
+            ],
+            
+            :version => ASSESSABLE_VERSION
+            
+          }
+          
+        } if @requires.nil?
+        
+        super
+      
+      end
+      
+    end
+    
+  end
+  
+end

data/lib/langrove/behaviour/base.rb

@@ -0,0 +1,16 @@
+module LanGrove
+
+  module Behaviour
+
+  end
+
+end
+
+require 'langrove/behaviour/behaviour_base'
+
+require 'langrove/behaviour/persistable'
+require 'langrove/behaviour/enqueueable'
+require 'langrove/behaviour/preloadable'
+require 'langrove/behaviour/assessable'
+require 'langrove/behaviour/notifiable'
+#require 'langrove/behaviour/terminatable'