smart_message 0.0.8 → 0.0.10

data/lib/smart_message/logger.rb

@@ -2,14 +2,22 @@
 # encoding: utf-8
 # frozen_string_literal: true
 
-module SmartMessage::Logger
-  # Logger module provides logging capabilities for SmartMessage
-  # The Default logger automatically uses Rails.logger if available,
-  # otherwise falls back to a standard Ruby Logger
-end # module SmartMessage::Logger
-
-# Load the base class first
 require_relative 'logger/base'
-
-# Load the default logger implementation
 require_relative 'logger/default'
+require_relative 'logger/lumberjack'
+
+module SmartMessage
+  module Logger
+    class << self
+      # Global default logger instance
+      def default
+        @default ||= Lumberjack.new
+      end
+
+      # Set the default logger
+      def default=(logger)
+        @default = logger
+      end
+    end
+  end
+end

data/lib/smart_message/messaging.rb

@@ -0,0 +1,100 @@
+# lib/smart_message/messaging.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+module SmartMessage
+  # Messaging module for SmartMessage::Base
+  # Handles message encoding and publishing operations
+  module Messaging
+    # 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
+
+    # Convert message to hash with _sm_header and _sm_payload structure
+    # This is the foundation for wrapper architecture
+    def to_h
+      # Update header with serializer info before converting
+      _sm_header.serializer = serializer.class.to_s if serializer_configured?
+      
+      {
+        :_sm_header => header_hash_with_symbols,
+        :_sm_payload => payload_hash_with_symbols
+      }
+    end
+
+
+    # NOTE: you publish instances; but, you subscribe/unsubscribe at
+    #       the class-level
+    def publish
+      begin
+        # Validate the complete message before publishing (now uses overridden validate!)
+        validate!
+        
+        # Update header with current publication info
+        _sm_header.published_at   = Time.now
+        _sm_header.publisher_pid  = Process.pid
+        _sm_header.serializer     = serializer.class.to_s if serializer_configured?
+
+        # Single-tier serialization: serialize entire message with designated serializer
+        serialized_message = encode
+        
+        raise Errors::TransportNotConfigured if transport_missing?
+        
+        # Transport receives the message class name (for channel routing) and serialized message
+        (self.class.logger || SmartMessage::Logger.default).debug { "[SmartMessage::Messaging] About to call transport.publish" }
+        transport.publish(_sm_header.message_class, serialized_message)
+        (self.class.logger || SmartMessage::Logger.default).debug { "[SmartMessage::Messaging] transport.publish completed" }
+        
+        # Log the message publish
+        (self.class.logger || SmartMessage::Logger.default).info { "[SmartMessage] Published: #{self.class.name} via #{transport.class.name.split('::').last}" }
+
+        SS.add(_sm_header.message_class, 'publish')
+        SS.get(_sm_header.message_class, 'publish')
+      rescue => e
+        (self.class.logger || SmartMessage::Logger.default).error { "[SmartMessage] Error in message publishing: #{e.class.name} - #{e.message}" }
+        raise
+      end
+    end # def publish
+
+    private
+
+    # Convert header to hash with symbol keys
+    def header_hash_with_symbols
+      _sm_header.to_hash.transform_keys(&:to_sym)
+    end
+    
+    # Extract all non-header properties into a hash with symbol keys
+    # Performs deep symbolization on nested structures
+    def payload_hash_with_symbols
+      self.class.properties.each_with_object({}) do |prop, hash|
+        next if prop == :_sm_header
+        hash[prop.to_sym] = deep_symbolize_keys(self[prop])
+      end
+    end
+
+    # Recursively convert all string keys to symbols in nested hashes and arrays
+    def deep_symbolize_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(key, value), result|
+          result[key.to_sym] = deep_symbolize_keys(value)
+        end
+      when Array
+        obj.map { |item| deep_symbolize_keys(item) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/smart_message/plugins.rb

@@ -0,0 +1,132 @@
+# lib/smart_message/plugins.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+module SmartMessage
+  # Plugin configuration module for SmartMessage::Base
+  # Handles transport, serializer, and logger configuration at both
+  # class and instance levels
+  module Plugins
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_eval do
+        # Class-level plugin storage
+        class_variable_set(:@@transport, nil) unless class_variable_defined?(:@@transport)
+        class_variable_set(:@@serializer, nil) unless class_variable_defined?(:@@serializer)
+        class_variable_set(:@@logger, nil) unless class_variable_defined?(:@@logger)
+      end
+    end
+
+    #########################################################
+    ## 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)
+      if klass_or_instance.nil?
+        # Return instance transport, class transport, or global configuration
+        @transport || self.class.class_variable_get(:@@transport) || SmartMessage::Transport.default
+      else
+        @transport = klass_or_instance
+      end
+    end
+
+    def transport_configured?;  !transport_missing?;   end
+    def transport_missing?
+      # Check if transport is explicitly configured (without fallback to defaults)
+      @transport.nil? && 
+        (self.class.class_variable_get(:@@transport) rescue nil).nil?
+    end
+    def reset_transport;        @transport = nil;  end
+
+
+    #########################################################
+    ## instance-level serializer configuration
+
+    def serializer(klass_or_instance = nil)
+      if klass_or_instance.nil?
+        # Return instance serializer, class serializer, or global configuration
+        @serializer || self.class.class_variable_get(:@@serializer) || SmartMessage::Serializer.default
+      else
+        @serializer = klass_or_instance
+      end
+    end
+
+    def serializer_configured?; !serializer_missing?;   end
+    def serializer_missing?
+      # Check if serializer is explicitly configured (without fallback to defaults)
+      @serializer.nil? && 
+        (self.class.class_variable_get(:@@serializer) rescue nil).nil?
+    end
+    def reset_serializer;       @serializer = nil;  end
+
+    module ClassMethods
+      #########################################################
+      ## class-level configuration
+
+      def config(&block)
+        class_eval(&block) if block_given?
+      end
+
+      #########################################################
+      ## class-level transport configuration
+
+      def transport(klass_or_instance = nil)
+        if klass_or_instance.nil?
+          # Return class-level transport or fall back to global configuration
+          class_variable_get(:@@transport) || SmartMessage::Transport.default
+        else
+          class_variable_set(:@@transport, klass_or_instance)
+        end
+      end
+
+      def transport_configured?;  !transport_missing?;   end
+      def transport_missing?
+        # Check if class-level transport is explicitly configured (without fallback to defaults)
+        (class_variable_get(:@@transport) rescue nil).nil?
+      end
+      def reset_transport;       class_variable_set(:@@transport, nil);  end
+
+      #########################################################
+      ## class-level logger configuration
+
+      def logger(klass_or_instance = nil)
+        if klass_or_instance.nil?
+          # Return class-level logger or fall back to global configuration
+          class_variable_get(:@@logger) || SmartMessage::Logger.default
+        else
+          class_variable_set(:@@logger, klass_or_instance)
+        end
+      end
+
+      def logger_configured?;     !logger.nil?;   end
+      def logger_missing?;         logger.nil?;   end
+      def reset_logger;          class_variable_set(:@@logger, nil);  end
+
+      #########################################################
+      ## class-level serializer configuration
+
+      def serializer(klass_or_instance = nil)
+        if klass_or_instance.nil?
+          # Return class-level serializer or fall back to global configuration
+          class_variable_get(:@@serializer) || SmartMessage::Serializer.default
+        else
+          class_variable_set(:@@serializer, klass_or_instance)
+        end
+      end
+
+      def serializer_configured?; !serializer_missing?;   end
+      def serializer_missing?
+        # Check if class-level serializer is explicitly configured (without fallback to defaults)
+        (class_variable_get(:@@serializer) rescue nil).nil?
+      end
+      def reset_serializer;      class_variable_set(:@@serializer, nil);  end
+    end
+  end
+end

data/lib/smart_message/serializer/base.rb

@@ -2,6 +2,7 @@
 # encoding: utf-8
 # frozen_string_literal: true
 
+require 'json'  # STDLIB
 require_relative '../circuit_breaker'
 
 module SmartMessage::Serializer
@@ -12,7 +13,20 @@ module SmartMessage::Serializer
     # provide basic configuration
     def initialize
       configure_serializer_circuit_breakers
+      
+      logger.debug { "[SmartMessage::Serializer::#{self.class.name.split('::').last}] Initialized" }
+    rescue => e
+      logger&.error { "[SmartMessage] Error in serializer initialization: #{e.class.name} - #{e.message}" }
+      raise
+    end
+    
+    private
+    
+    def logger
+      @logger ||= SmartMessage::Logger.default
     end
+    
+    public
 
     def encode(message_instance)
       circuit(:serializer).wrap do
@@ -39,10 +53,16 @@ module SmartMessage::Serializer
         raise
       end
     end
+    
+    private
 
     # Template methods for actual serialization (implement in subclasses)
     def do_encode(message_instance)
-      raise ::SmartMessage::Errors::NotImplemented
+      # Default implementation: serialize only the payload portion for wrapper architecture
+      # Subclasses can override this for specific serialization formats
+      message_hash = message_instance.to_h
+      payload_portion = message_hash[:_sm_payload]
+      ::JSON.generate(payload_portion)
     end
 
     def do_decode(payload)
@@ -81,13 +101,10 @@ module SmartMessage::Serializer
 
     # Handle serializer circuit breaker fallback
     def handle_serializer_fallback(fallback_result, operation, data)
-      if $DEBUG
-        puts "Serializer circuit breaker activated: #{self.class.name}"
-        puts "Operation: #{operation}"
-        puts "Error: #{fallback_result[:circuit_breaker][:error]}"
-      end
-      
-      # TODO: Integrate with structured logging when implemented
+      # Integrate with structured logging
+      logger.error { "[SmartMessage::Serializer] Circuit breaker activated: #{self.class.name}" }
+      logger.error { "[SmartMessage::Serializer] Operation: #{operation}" }
+      logger.error { "[SmartMessage::Serializer] Error: #{fallback_result[:circuit_breaker][:error]}" }
       
       # Return the fallback result
       fallback_result

data/lib/smart_message/serializer/json.rb

@@ -5,11 +5,12 @@
 require 'json'  # STDLIB
 
 module SmartMessage::Serializer
-  class JSON < Base
+  class Json < Base
     def do_encode(message_instance)
-      # TODO: is this the right place to insert an automated-invisible
-      #       message header?
-      message_instance.to_json
+      # Single-tier serialization: serialize the complete message structure
+      # This includes both header and payload for full message reconstruction
+      message_hash = message_instance.to_h
+      ::JSON.generate(message_hash)
     end
 
     def do_decode(payload)

data/lib/smart_message/subscription.rb

@@ -0,0 +1,196 @@
+# lib/smart_message/subscription.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'securerandom'   # STDLIB
+
+module SmartMessage
+  # Subscription management module for SmartMessage::Base
+  # Handles subscribe/unsubscribe operations and proc handler management
+  module Subscription
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_eval do
+        # Registry for proc-based message handlers
+        class_variable_set(:@@proc_handlers, {}) unless class_variable_defined?(:@@proc_handlers)
+      end
+    end
+
+    module ClassMethods
+      #########################################################
+      ## proc handler management
+
+      # Register a proc handler and return a unique identifier for it
+      # @param message_class [String] The message class name
+      # @param handler_proc [Proc] The proc to register
+      # @return [String] Unique identifier for this handler
+      def register_proc_handler(message_class, handler_proc)
+        handler_id = "#{message_class}.proc_#{SecureRandom.hex(8)}"
+        class_variable_get(:@@proc_handlers)[handler_id] = handler_proc
+        handler_id
+      end
+
+      # Call a registered proc handler
+      # @param handler_id [String] The handler identifier
+      # @param wrapper [SmartMessage::Wrapper::Base] The message wrapper
+      def call_proc_handler(handler_id, wrapper)
+        handler_proc = class_variable_get(:@@proc_handlers)[handler_id]
+        return unless handler_proc
+
+        handler_proc.call(wrapper)
+      end
+
+      # Remove a proc handler from the registry
+      # @param handler_id [String] The handler identifier to remove
+      def unregister_proc_handler(handler_id)
+        class_variable_get(:@@proc_handlers).delete(handler_id)
+      end
+
+      # Check if a handler ID refers to a proc handler
+      # @param handler_id [String] The handler identifier
+      # @return [Boolean] True if this is a proc handler
+      def proc_handler?(handler_id)
+        class_variable_get(:@@proc_handlers).key?(handler_id)
+      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.
+      #
+      # @param process_method [String, Proc, nil] The processing method:
+      #   - String: Method name like "MyService.handle_message" 
+      #   - Proc: A proc/lambda that accepts (message_header, message_payload)
+      #   - nil: Uses default "MessageClass.process" method
+      # @param broadcast [Boolean, nil] Filter for broadcast messages (to: nil)
+      # @param to [String, Array, nil] Filter for messages directed to specific entities
+      # @param from [String, Array, nil] Filter for messages from specific entities
+      # @param block [Proc] Alternative way to pass a processing block
+      # @return [String] The identifier used for this subscription
+      #
+      # @example Using default handler 
+      #   MyMessage.subscribe
+      #
+      # @example Using custom method name with filtering
+      #   MyMessage.subscribe("MyService.handle_message", from: ['order-service'])
+      #
+      # @example Using a block with broadcast filtering
+      #   MyMessage.subscribe(broadcast: true) do |header, payload|
+      #     data = JSON.parse(payload)
+      #     puts "Received broadcast: #{data}"
+      #   end
+      #
+      # @example Entity-specific filtering (receives only messages from payment service)
+      #   MyMessage.subscribe("OrderService.process", from: ['payment'])
+      #
+      # @example Explicit to filter 
+      #   MyMessage.subscribe("AdminService.handle", to: 'admin', broadcast: false)
+      def subscribe(process_method = nil, broadcast: nil, to: nil, from: nil, &block)
+        message_class = whoami
+        
+        # Handle different parameter types
+        if block_given?
+          # Block was passed - use it as the handler
+          handler_proc = block
+          process_method = register_proc_handler(message_class, handler_proc)
+        elsif process_method.respond_to?(:call)
+          # Proc/lambda was passed as first parameter
+          handler_proc = process_method
+          process_method = register_proc_handler(message_class, handler_proc)
+        elsif process_method.nil?
+          # Use default handler
+          process_method = message_class + '.process'
+        end
+        # If process_method is a String, use it as-is
+
+        # Subscriber identity is derived from the process method (handler)
+        # This ensures each handler gets its own DDQ scope per message class
+        
+        # Normalize string filters to arrays
+        to_filter = normalize_filter_value(to)
+        from_filter = normalize_filter_value(from)
+        
+        # Create filter options (no explicit subscriber identity needed)
+        filter_options = {
+          broadcast: broadcast,
+          to: to_filter,
+          from: from_filter
+        }
+
+        # Add proper logging
+        logger = SmartMessage::Logger.default
+        
+        begin
+          raise Errors::TransportNotConfigured if transport_missing?
+          transport.subscribe(message_class, process_method, filter_options)
+          
+          # Log successful subscription
+          handler_desc = block_given? || process_method.respond_to?(:call) ? " with block/proc handler" : ""
+          logger.info { "[SmartMessage] Subscribed: #{self.name}#{handler_desc}" }
+          logger.debug { "[SmartMessage::Subscription] Subscribed #{message_class} with filters: #{filter_options}" }
+          
+          process_method
+        rescue => e
+          logger.error { "[SmartMessage] Error in message subscription: #{e.class.name} - #{e.message}" }
+          raise
+        end
+      end
+
+      # Remove this process_method for this message class from the
+      # subscribers list.
+      # @param process_method [String, nil] The processing method identifier to remove
+      #   - String: Method name like "MyService.handle_message" or proc handler ID
+      #   - nil: Uses default "MessageClass.process" method
+      def unsubscribe(process_method = nil)
+        message_class   = whoami
+        process_method  = message_class + '.process' if process_method.nil?
+        # Add proper logging
+        logger = SmartMessage::Logger.default
+        
+        begin
+          if transport_configured?
+            transport.unsubscribe(message_class, process_method)
+            
+            # If this was a proc handler, clean it up from the registry
+            if proc_handler?(process_method)
+              unregister_proc_handler(process_method)
+            end
+            
+            # Log successful unsubscription
+            logger.info { "[SmartMessage] Unsubscribed: #{self.name}" }
+            logger.debug { "[SmartMessage::Subscription] Unsubscribed #{message_class} from #{process_method}" }
+          end
+        rescue => e
+          logger.error { "[SmartMessage] Error in message unsubscription: #{e.class.name} - #{e.message}" }
+          raise
+        end
+      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
+
+      ###################################################
+      ## 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
+  end
+end