smart_message 0.0.1

data/lib/smart_message/base.rb

@@ -0,0 +1,284 @@
+# lib/smart_message/base.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'securerandom'   # STDLIB
+
+require_relative './wrapper.rb'
+
+module SmartMessage
+  # The foundation class for the smart message
+  class Base < Hashie::Dash
+
+    # Supports multi-level plugins for transport, serializer and logger.
+    # Plugins can be made at the class level and at the instance level.
+    @@transport   = nil
+    @@serializer  = nil
+    @@logger      = nil
+
+    include Hashie::Extensions::Dash::PropertyTranslation
+
+    include Hashie::Extensions::Coercion
+    include Hashie::Extensions::DeepMerge
+    include Hashie::Extensions::IgnoreUndeclared
+    include Hashie::Extensions::IndifferentAccess
+    include Hashie::Extensions::MergeInitializer
+    include Hashie::Extensions::MethodAccess
+
+    # Common attrubutes for all messages
+    # TODO: Need to change the SmartMessage::Header into a
+    #       smartMessage::Wrapper concept where the message
+    #       content is serialized into an element in the wrapper
+    #       where the wrapper contains header/routing information
+    #       in addition to the serialized message data.
+    property :_sm_header
+
+    # Constructor for a messsage definition that allows the
+    # setting of initial values.
+    def initialize(**props, &block)
+      # instance-level over ride of class plugins
+      @transport   = nil
+      @serializer  = nil
+      @logger      = nil
+
+      attributes = {
+        _sm_header: SmartMessage::Header.new(
+          uuid:           SecureRandom.uuid,
+          message_class:  self.class.to_s,
+          published_at:   2,
+          publisher_pid:  3
+        )
+      }.merge(props)
+
+      super(attributes, &block)
+    end
+
+
+    ###################################################
+    ## Common instance methods
+
+    # SMELL: How does the transport know how to decode a message before
+    #        it knows the message class?  We need a wrapper around
+    #        the entire message in a known serialization.  That
+    #        wrapper would contain two properties: _sm_header and
+    #        _sm_payload
+
+    # NOTE: to publish a message it must first be encoded using a
+    #       serializer.  The receive a subscribed to message it must
+    #       be decoded via a serializer from the transport to be processed.
+    def encode
+      raise Errors::SerializerNotConfigured if serializer_missing?
+
+      serializer.encode(self)
+    end
+
+
+    # NOTE: you publish instances; but, you subscribe/unsubscribe at
+    #       the class-level
+    def publish
+      # TODO: move all of the _sm_ property processes into the wrapper
+      _sm_header.published_at   = Time.now
+      _sm_header.publisher_pid  = Process.pid
+
+      payload = encode
+
+      raise Errors::TransportNotConfigured if transport_missing?
+      transport.publish(_sm_header, payload)
+
+      SS.add(_sm_header.message_class, 'publish')
+      SS.get(_sm_header.message_class, 'publish')
+    end # def publish
+
+
+
+    #########################################################
+    ## instance-level configuration
+
+    # Configure the plugins for transport, serializer and logger
+    def config(&block)
+      instance_eval(&block) if block_given?
+    end
+
+
+    #########################################################
+    ## instance-level transport configuration
+
+    def transport(klass_or_instance = nil)
+      klass_or_instance.nil? ? @transport || @@transport : @transport = klass_or_instance
+    end
+
+    def transport_configured?;  !transport.nil?;   end
+    def transport_missing?;      transport.nil?;   end
+    def reset_transport;        @transport = nil;  end
+
+
+    #########################################################
+    ## instance-level logger configuration
+
+    def logger(klass_or_instance = nil)
+      klass_or_instance.nil? ? @logger || @@logger : @logger = klass_or_instance
+    end
+
+    def logger_configured?;     !logger.nil?; end
+    def logger_missing?;         logger.nil?; end
+    def reset_logger;           @logger = nil;  end
+
+
+    #########################################################
+    ## instance-level serializer configuration
+
+    def serializer(klass_or_instance = nil)
+      klass_or_instance.nil? ? @serializer || @@serializer : @serializer = klass_or_instance
+    end
+
+    def serializer_configured?; !serializer.nil?;   end
+    def serializer_missing?;     serializer.nil?;   end
+    def reset_serializer;       @serializer = nil;  end
+
+
+    #########################################################
+    ## instance-level utility methods
+
+    # return this class' name as a string
+    def whoami
+      self.class.to_s
+    end
+
+
+    # returns a collection of class Set that consists of
+    # the symbolized values of the property names of the message
+    # without the injected '_sm_' properties that support
+    # the behind-the-sceens operations of SmartMessage.
+    def fields
+      to_h.keys
+          .reject{|key| key.start_with?('_sm_')}
+          .map{|key| key.to_sym}
+          .to_set
+    end
+
+
+    ###########################################################
+    ## class methods
+
+    class << self
+
+      #########################################################
+      ## class-level configuration
+
+      def config(&block)
+        class_eval(&block) if block_given?
+      end
+
+
+      #########################################################
+      ## class-level transport configuration
+
+      def transport(klass_or_instance = nil)
+        klass_or_instance.nil? ? @@transport : @@transport = klass_or_instance
+      end
+
+      def transport_configured?;  !transport.nil?;   end
+      def transport_missing?;      transport.nil?;   end
+      def reset_transport;       @@transport = nil;  end
+
+
+      #########################################################
+      ## class-level logger configuration
+
+      def logger(klass_or_instance = nil)
+        klass_or_instance.nil? ? @@logger : @@logger = klass_or_instance
+      end
+
+      def logger_configured?;     !logger.nil?;   end
+      def logger_missing?;         logger.nil?;   end
+      def reset_logger;          @@logger = nil;  end
+
+
+      #########################################################
+      ## class-level serializer configuration
+
+      def serializer(klass_or_instance = nil)
+        klass_or_instance.nil? ? @@serializer : @@serializer = klass_or_instance
+      end
+
+      def serializer_configured?; !serializer.nil?;   end
+      def serializer_missing?;     serializer.nil?;   end
+      def reset_serializer;      @@serializer = nil;  end
+
+
+      #########################################################
+      ## class-level subscription management via the transport
+
+      # Add this message class to the transport's catalog of
+      # subscribed messages.  If the transport is missing, raise
+      # an exception.
+      def subscribe(process_method = nil)
+        message_class   = whoami
+        process_method  = message_class + '.process' if process_method.nil?
+
+        # TODO: Add proper logging here
+
+        raise Errors::TransportNotConfigured if transport_missing?
+        transport.subscribe(message_class, process_method)
+      end
+
+
+      # Remove this process_method for this message class from the
+      # subscribers list.
+      def unsubscribe(process_method = nil)
+        message_class   = whoami
+        process_method  = message_class + '.process' if process_method.nil?
+        # TODO: Add proper logging here
+
+        transport.unsubscribe(message_class, process_method) if transport_configured?
+      end
+
+
+      # Remove this message class and all of its processing methods
+      # from the subscribers list.
+      def unsubscribe!
+        message_class   = whoami
+
+        # TODO: Add proper logging here
+
+        transport.unsubscribe!(message_class) if transport_configured?
+      end
+
+
+
+      #########################################################
+      ## class-level utility methods
+
+      # return this class' name as a string
+      def whoami
+        ancestors.first.to_s
+      end
+
+      # Return a Set of symbols representing each defined property of
+      # this message class.
+      def fields
+        @properties.dup.delete_if{|item| item.to_s.start_with?('_sm_')}
+      end
+
+      ###################################################
+      ## Business Logic resides in the #process method.
+
+      # When a transport receives a subscribed to message it
+      # creates an instance of the message and then calls
+      # the process method on that instance.
+      #
+      # It is expected that SmartMessage classes over ride
+      # the SmartMessage::Base#process method with appropriate
+      # business logic to handle the received message content.
+      def process(message_instance)
+        raise Errors::NotImplemented
+      end
+
+    end # class << self
+  end # class Base
+end # module SmartMessage
+
+require_relative 'header'
+require_relative 'transport'
+require_relative 'serializer'
+require_relative 'logger'

data/lib/smart_message/dispatcher.rb

@@ -0,0 +1,146 @@
+# lib/smart_message/dispatcher.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module SmartMessage
+
+  # The disoatcher routes incoming messages to all of the methods that
+  # have been subscribed to the message.
+  class Dispatcher
+
+    # TODO: setup forwardable for some @router_pool methods
+
+    def initialize
+      @subscribers = Hash.new(Array.new)
+      @router_pool = Concurrent::CachedThreadPool.new
+      at_exit do
+        print "Shuttingdown down the dispatcher's @router_pool ..."
+        @router_pool.shutdown
+        while @router_pool.shuttingdown?
+          print '.'
+          sleep 1
+        end
+        puts " done."
+      end
+    end
+
+
+    def what_can_i_do?
+      # TODO: Return pool methods list for debugging
+      @router_pool.methods.sort
+    end
+
+
+    def status
+      # TODO: Return proper status hash
+      {
+        scheduled_task_count: @router_pool.scheduled_task_count,
+        completed_task_count: @router_pool.completed_task_count,
+        queue_length: @router_pool.queue_length,
+        length: @router_pool.length,
+        running: @router_pool.running?
+      }
+    rescue NoMethodError
+      what_can_i_do?
+    end
+
+
+    def pool
+      @router_pool.instance_variable_get('@pool'.to_sym)
+    end
+
+    def scheduled_task_count
+      @router_pool.scheduled_task_count
+    end
+
+    def worker_task_completed
+      @router_pool.worker_task_completed
+    end
+
+    def completed_task_count
+      @router_pool.completed_task_count
+    end
+
+    def queue_length
+      @router_pool.queue_length
+    end
+
+
+    def  current_length
+      @router_pool.length
+    end
+
+
+    def running?
+      @router_pool.running?
+    end
+
+
+    def subscribers
+      @subscribers
+    end
+
+
+    def add(message_class, process_method_as_string)
+      klass = String(message_class)
+      unless @subscribers[klass].include? process_method_as_string
+        @subscribers[klass] += [process_method_as_string]
+      end
+    end
+
+
+    # drop a processer from a subscribed message
+    def drop(message_class, process_method_as_string)
+      @subscribers[String(message_class)].delete process_method_as_string
+    end
+
+
+    # drop all processer from a subscribed message
+    def drop_all(message_class)
+      @subscribers.delete String(message_class)
+    end
+
+
+    # complete reset all subscriptions
+    def drop_all!
+      @subscribers = Hash.new(Array.new)
+    end
+
+
+    # message_header is of class SmartMessage::Header
+    # message_payload is a string buffer that is a serialized
+    # SmartMessage
+    def route(message_header, message_payload)
+      message_klass = message_header.message_class
+      return nil if @subscribers[message_klass].empty?
+      @subscribers[message_klass].each do |message_processor|
+        SS.add(message_klass, message_processor, 'routed' )
+        @router_pool.post do
+          parts         = message_processor.split('.')
+          target_klass  = parts[0]
+          class_method  = parts[1]
+          begin
+            target_klass.constantize
+                        .method(class_method)
+                        .call(message_header, message_payload)
+          rescue Exception => e
+            # TODO: Add proper exception logging
+            # Exception details: #{e.message}
+            # Processor: #{message_processor}
+            puts "Error processing message: #{e.message}" if $DEBUG
+          end
+        end
+      end
+    end
+
+
+    #######################################################
+    ## Class methods
+
+    class << self
+      # TODO: may want a class-level config method
+    end # class << self
+  end # class Dispatcher
+end # module SmartMessage

data/lib/smart_message/errors.rb

@@ -0,0 +1,29 @@
+# smart_message/lib/smart_message/errors.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+module SmartMessage
+  module Errors
+    # A message can't be very smart if it does not know how to
+    # send and receive itself using a message transport
+    class TransportNotConfigured < RuntimeError; end
+
+    # A message can't be very smart if it does not know how to
+    # send and receive itself using a message transport
+    class TransportNotConfigured < RuntimeError; end
+
+    # A message can't be very smart if it does not know how to
+    # encode and decode itself using a message serializer
+    class SerializerNotConfigured < RuntimeError; end
+
+    # The functionality has not be implemented
+    class NotImplemented < RuntimeError; end
+
+    # A message was received to which there is no subscription
+    class ReceivedMessageNotSubscribed < RuntimeError; end
+
+    # A received message is of an unknown class
+    class UnknownMessageClass < RuntimeError; end
+
+  end
+end

data/lib/smart_message/header.rb

@@ -0,0 +1,20 @@
+# lib/smart_message/header.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+module SmartMessage
+  # Every smart message has a common header format that contains
+  # information used to support the dispatching of subscribed
+  # messages upon receipt from a transport.
+  class Header < Hashie::Dash
+    include Hashie::Extensions::IndifferentAccess
+    include Hashie::Extensions::MergeInitializer
+    include Hashie::Extensions::MethodAccess
+
+    # Common attributes of the smart message standard header
+    property :uuid
+    property :message_class
+    property :published_at
+    property :publisher_pid
+  end
+end

data/lib/smart_message/logger/base.rb

@@ -0,0 +1,8 @@
+# lib/smart_message/logger/base.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+module SmartMessage::Logger
+  class Base
+  end
+end # module SmartMessage::Logger

data/lib/smart_message/logger.rb

@@ -0,0 +1,7 @@
+# lib/smart_message/logger.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+module SmartMessage::Logger
+  # TODO: write this
+end # module SmartMessage::Logger

data/lib/smart_message/serializer/base.rb

@@ -0,0 +1,23 @@
+# lib/smart_message/serializer/base.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+module SmartMessage::Serializer
+  # the standard super class
+  class Base
+    # provide basic configuration
+    def initialize
+      # TODO: write this
+    end
+
+    def encode(message_instance)
+      # TODO: Add proper logging here
+      raise ::SmartMessage::Errors::NotImplemented
+    end
+
+    def decode(payload)
+      # TODO: Add proper logging here
+      raise ::SmartMessage::Errors::NotImplemented
+    end
+  end # class Base
+end # module SmartMessage::Serializer

data/lib/smart_message/serializer/json.rb

@@ -0,0 +1,22 @@
+# lib/smart_message/serializer/json.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'json'  # STDLIB
+
+module SmartMessage::Serializer
+  class JSON < Base
+    def encode(message_instance)
+      # TODO: is this the right place to insert an automated-invisible
+      #       message header?
+      message_instance.to_json
+    end
+
+    def decode(payload)
+      # TODO: so how do I know to which message class this payload
+      #       belongs?  The class needs to be in some kind of message
+      #       header.
+      ::JSON.parse payload
+    end
+  end # class JSON < Base
+end # module SmartMessage::Serializer

data/lib/smart_message/serializer.rb

@@ -0,0 +1,10 @@
+# lib/smart_message/serializer.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+require_relative 'serializer/base'
+require_relative 'serializer/json'
+
+module SmartMessage::Serializer
+  # Serializer module for message encoding/decoding
+end # module SmartMessage::Serializer

data/lib/smart_message/transport/base.rb

@@ -0,0 +1,85 @@
+# lib/smart_message/transport/base.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+module SmartMessage
+  module Transport
+    # Base class for all transport implementations
+    # This defines the standard interface that all transports must implement
+    class Base
+      attr_reader :options, :dispatcher
+
+      def initialize(**options)
+        @options = default_options.merge(options)
+        @dispatcher = options[:dispatcher] || SmartMessage::Dispatcher.new
+        configure
+      end
+
+      # Transport-specific configuration
+      def configure
+        # Override in subclasses for specific setup
+      end
+
+      # Default options for this transport
+      def default_options
+        {}
+      end
+
+      # Publish a message
+      # @param message_header [SmartMessage::Header] Message routing information
+      # @param message_payload [String] Serialized message content
+      def publish(message_header, message_payload)
+        raise NotImplementedError, 'Transport must implement #publish'
+      end
+
+      # Subscribe to a message class
+      # @param message_class [String] The message class name
+      # @param process_method [String] The processing method identifier
+      def subscribe(message_class, process_method)
+        @dispatcher.add(message_class, process_method)
+      end
+
+      # Unsubscribe from a specific message class and process method
+      # @param message_class [String] The message class name  
+      # @param process_method [String] The processing method identifier
+      def unsubscribe(message_class, process_method)
+        @dispatcher.drop(message_class, process_method)
+      end
+
+      # Unsubscribe from all process methods for a message class
+      # @param message_class [String] The message class name
+      def unsubscribe!(message_class)
+        @dispatcher.drop_all(message_class)
+      end
+
+      # Get current subscriptions
+      def subscribers
+        @dispatcher.subscribers
+      end
+
+      # Check if transport is connected/available
+      def connected?
+        true
+      end
+
+      # Connect to transport (if applicable)
+      def connect
+        # Override in subclasses if connection setup is needed
+      end
+
+      # Disconnect from transport (if applicable) 
+      def disconnect
+        # Override in subclasses if cleanup is needed
+      end
+
+      # Receive and route a message (called by transport implementations)
+      # @param message_header [SmartMessage::Header] Message routing information
+      # @param message_payload [String] Serialized message content
+      protected
+
+      def receive(message_header, message_payload)
+        @dispatcher.route(message_header, message_payload)
+      end
+    end
+  end
+end