smart_message 0.0.3 → 0.0.5

data/lib/smart_message/base.rb

@@ -6,6 +6,7 @@ require 'securerandom'   # STDLIB
 
 require_relative './wrapper.rb'
 require_relative './property_descriptions.rb'
+require_relative './property_validations.rb'
 
 module SmartMessage
   # The foundation class for the smart message
@@ -19,16 +20,38 @@ module SmartMessage
     
     # Registry for proc-based message handlers
     @@proc_handlers = {}
+    
+    # Class-level version setting
+    class << self
+      attr_accessor :_version
+      
+      def version(v = nil)
+        if v.nil?
+          @_version || 1  # Default to version 1 if not set
+        else
+          @_version = v
+          
+          # Set up version validation for the header
+          # This ensures that the header version matches the expected class version
+          @expected_header_version = v
+        end
+      end
+      
+      def expected_header_version
+        @expected_header_version || 1
+      end
+    end
 
     include Hashie::Extensions::Dash::PropertyTranslation
 
     include SmartMessage::PropertyDescriptions
+    include SmartMessage::PropertyValidations
 
     include Hashie::Extensions::Coercion
     include Hashie::Extensions::DeepMerge
     include Hashie::Extensions::IgnoreUndeclared
     include Hashie::Extensions::IndifferentAccess
-    include Hashie::Extensions::MergeInitializer
+    # MergeInitializer interferes with required property validation - removed
     include Hashie::Extensions::MethodAccess
 
     # Common attrubutes for all messages
@@ -47,13 +70,28 @@ module SmartMessage
       @serializer  = nil
       @logger      = nil
 
+      # Create header with version validation specific to this message class
+      header = SmartMessage::Header.new(
+        uuid:           SecureRandom.uuid,
+        message_class:  self.class.to_s,
+        published_at:   Time.now,
+        publisher_pid:  Process.pid,
+        version:        self.class.version
+      )
+      
+      # Set up version validation to match the expected class version
+      expected_version = self.class.expected_header_version
+      header.singleton_class.class_eval do
+        define_method(:validate_version!) do
+          unless self.version == expected_version
+            raise SmartMessage::Errors::ValidationError, 
+              "Header version must be #{expected_version}, got: #{self.version}"
+          end
+        end
+      end
+      
       attributes = {
-        _sm_header: SmartMessage::Header.new(
-          uuid:           SecureRandom.uuid,
-          message_class:  self.class.to_s,
-          published_at:   2,
-          publisher_pid:  3
-        )
+        _sm_header: header
       }.merge(props)
 
       super(attributes, &block)
@@ -62,6 +100,57 @@ module SmartMessage
 
     ###################################################
     ## Common instance methods
+    
+    # Validate that the header version matches the expected version for this class
+    def validate_header_version!
+      expected = self.class.expected_header_version
+      actual = _sm_header.version
+      unless actual == expected
+        raise SmartMessage::Errors::ValidationError,
+          "#{self.class.name} expects version #{expected}, but header has version #{actual}"
+      end
+    end
+
+    # Override PropertyValidations validate! to include header and version validation
+    def validate!
+      # Validate message properties using PropertyValidations
+      super
+      
+      # Validate header properties
+      _sm_header.validate!
+      
+      # Validate header version matches expected class version  
+      validate_header_version!
+    end
+
+    # Override PropertyValidations validation_errors to include header errors
+    def validation_errors
+      errors = []
+      
+      # Get message property validation errors using PropertyValidations
+      errors.concat(super.map { |err| 
+        err.merge(source: 'message') 
+      })
+      
+      # Get header validation errors
+      errors.concat(_sm_header.validation_errors.map { |err| 
+        err.merge(source: 'header') 
+      })
+      
+      # Check version mismatch
+      expected = self.class.expected_header_version
+      actual = _sm_header.version
+      unless actual == expected
+        errors << {
+          property: :version,
+          value: actual,
+          message: "Expected version #{expected}, got: #{actual}",
+          source: 'version_mismatch'
+        }
+      end
+      
+      errors
+    end
 
     # SMELL: How does the transport know how to decode a message before
     #        it knows the message class?  We need a wrapper around
@@ -82,6 +171,9 @@ module SmartMessage
     # NOTE: you publish instances; but, you subscribe/unsubscribe at
     #       the class-level
     def publish
+      # Validate the complete message before publishing (now uses overridden validate!)
+      validate!
+      
       # TODO: move all of the _sm_ property processes into the wrapper
       _sm_header.published_at   = Time.now
       _sm_header.publisher_pid  = Process.pid
@@ -150,6 +242,11 @@ module SmartMessage
       self.class.to_s
     end
 
+    # return this class' description
+    def description
+      self.class.description
+    end
+
 
     # returns a collection of class Set that consists of
     # the symbolized values of the property names of the message
@@ -173,7 +270,7 @@ module SmartMessage
       
       def description(desc = nil)
         if desc.nil?
-          @description
+          @description || "#{self.name} is a SmartMessage"
         else
           @description = desc.to_s
         end

data/lib/smart_message/errors.rb

@@ -25,5 +25,8 @@ module SmartMessage
     # A received message is of an unknown class
     class UnknownMessageClass < RuntimeError; end
 
+    # A property validation failed
+    class ValidationError < RuntimeError; end
+
   end
 end

data/lib/smart_message/header.rb

@@ -2,19 +2,46 @@
 # encoding: utf-8
 # frozen_string_literal: true
 
+require_relative './property_descriptions'
+require_relative './property_validations'
+
 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
+    include SmartMessage::PropertyDescriptions
+    include SmartMessage::PropertyValidations
 
     # Common attributes of the smart message standard header
-    property :uuid
-    property :message_class
-    property :published_at
-    property :publisher_pid
+    property :uuid, 
+      required: true,
+      message: "UUID is required for message tracking and deduplication",
+      description: "Unique identifier for this specific message instance, used for tracking and deduplication"
+    
+    property :message_class, 
+      required: true,
+      message: "Message class is required to identify the message type",
+      description: "Fully qualified class name of the message type (e.g. 'OrderMessage', 'PaymentNotification')"
+    
+    property :published_at, 
+      required: true,
+      message: "Published timestamp is required for message ordering",
+      description: "Timestamp when the message was published by the sender, used for ordering and debugging"
+    
+    property :publisher_pid, 
+      required: true,
+      message: "Publisher process ID is required for debugging and traceability",
+      description: "Process ID of the publishing application, useful for debugging and tracing message origins"
+    
+    property :version, 
+      required: true, 
+      default: 1,
+      message: "Message version is required for schema compatibility",
+      description: "Schema version of the message format, used for schema evolution and compatibility checking",
+      validate: ->(v) { v.is_a?(Integer) && v > 0 },
+      validation_message: "Header version must be a positive integer"
   end
 end

data/lib/smart_message/logger/default.rb

@@ -0,0 +1,217 @@
+# lib/smart_message/logger/default.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'logger'
+require 'fileutils'
+require 'stringio'
+
+module SmartMessage
+  module Logger
+    # Default logger implementation for SmartMessage
+    # 
+    # This logger automatically detects and uses the best available logging option:
+    # - Rails.logger if running in a Rails application
+    # - Standard Ruby Logger writing to log/smart_message.log otherwise
+    #
+    # Usage:
+    #   # In your message class
+    #   config do
+    #     logger SmartMessage::Logger::Default.new
+    #   end
+    #
+    #   # Or with custom options
+    #   config do
+    #     logger SmartMessage::Logger::Default.new(
+    #       log_file: 'custom/path.log',    # File path
+    #       level: Logger::DEBUG
+    #     )
+    #   end
+    #
+    #   # To log to STDOUT instead of a file
+    #   config do
+    #     logger SmartMessage::Logger::Default.new(
+    #       log_file: STDOUT,               # STDOUT or STDERR
+    #       level: Logger::INFO
+    #     )
+    #   end
+    class Default < Base
+      attr_reader :logger, :log_file, :level
+      
+      def initialize(log_file: nil, level: nil)
+        @log_file = log_file || default_log_file
+        @level = level || default_log_level
+        
+        @logger = setup_logger
+      end
+      
+      # Message lifecycle logging methods
+      
+      def log_message_created(message)
+        logger.debug { "[SmartMessage] Created: #{message.class.name} - #{message_summary(message)}" }
+      end
+      
+      def log_message_published(message, transport)
+        logger.info { "[SmartMessage] Published: #{message.class.name} via #{transport.class.name.split('::').last}" }
+      end
+      
+      def log_message_received(message_class, payload)
+        logger.info { "[SmartMessage] Received: #{message_class.name} (#{payload.bytesize} bytes)" }
+      end
+      
+      def log_message_processed(message_class, result)
+        logger.info { "[SmartMessage] Processed: #{message_class.name} - #{truncate(result.to_s, 100)}" }
+      end
+      
+      def log_message_subscribe(message_class, handler = nil)
+        handler_desc = handler ? " with handler: #{handler}" : ""
+        logger.info { "[SmartMessage] Subscribed: #{message_class.name}#{handler_desc}" }
+      end
+      
+      def log_message_unsubscribe(message_class)
+        logger.info { "[SmartMessage] Unsubscribed: #{message_class.name}" }
+      end
+      
+      # Error logging
+      
+      def log_error(context, error)
+        logger.error { "[SmartMessage] Error in #{context}: #{error.class.name} - #{error.message}" }
+        logger.debug { "[SmartMessage] Backtrace:\n#{error.backtrace.join("\n")}" } if error.backtrace
+      end
+      
+      def log_warning(message)
+        logger.warn { "[SmartMessage] Warning: #{message}" }
+      end
+      
+      # General purpose logging methods matching Ruby's Logger interface
+      
+      def debug(message = nil, &block)
+        logger.debug(message, &block)
+      end
+      
+      def info(message = nil, &block)
+        logger.info(message, &block)
+      end
+      
+      def warn(message = nil, &block)
+        logger.warn(message, &block)
+      end
+      
+      def error(message = nil, &block)
+        logger.error(message, &block)
+      end
+      
+      def fatal(message = nil, &block)
+        logger.fatal(message, &block)
+      end
+      
+      private
+      
+      def setup_logger
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          # Use Rails logger if available
+          setup_rails_logger
+        else
+          # Use standard Ruby logger
+          setup_ruby_logger
+        end
+      end
+      
+      def setup_rails_logger
+        # Wrap Rails.logger to ensure our messages are properly tagged
+        RailsLoggerWrapper.new(Rails.logger, level: @level)
+      end
+      
+      def setup_ruby_logger
+        # Handle IO objects (STDOUT, STDERR) vs file paths
+        if @log_file.is_a?(IO) || @log_file.is_a?(StringIO)
+          # For STDOUT/STDERR, don't use rotation
+          ruby_logger = ::Logger.new(@log_file)
+        else
+          # For file paths, ensure directory exists and use rotation
+          FileUtils.mkdir_p(File.dirname(@log_file))
+          
+          ruby_logger = ::Logger.new(
+            @log_file,
+            10,           # Keep 10 old log files
+            10_485_760    # Rotate when file reaches 10MB
+          )
+        end
+        
+        ruby_logger.level = @level
+        
+        # Set a clean formatter
+        ruby_logger.formatter = proc do |severity, datetime, progname, msg|
+          timestamp = datetime.strftime('%Y-%m-%d %H:%M:%S.%3N')
+          "[#{timestamp}] #{severity.ljust(5)} -- : #{msg}\n"
+        end
+        
+        ruby_logger
+      end
+      
+      def default_log_file
+        if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+          Rails.root.join('log', 'smart_message.log').to_s
+        else
+          'log/smart_message.log'
+        end
+      end
+      
+      def default_log_level
+        if defined?(Rails) && Rails.respond_to?(:env)
+          case Rails.env
+          when 'production'
+            ::Logger::INFO
+          when 'test'
+            ::Logger::ERROR
+          else
+            ::Logger::DEBUG
+          end
+        else
+          # Default to INFO for non-Rails environments
+          ::Logger::INFO
+        end
+      end
+      
+      def message_summary(message)
+        # Create a brief summary of the message for logging
+        if message.respond_to?(:to_h)
+          data = message.to_h
+          # Remove internal header for cleaner logs
+          data.delete(:_sm_header)
+          data.delete('_sm_header')
+          truncate(data.inspect, 200)
+        else
+          truncate(message.inspect, 200)
+        end
+      end
+      
+      def truncate(string, max_length)
+        return string if string.length <= max_length
+        "#{string[0...max_length]}..."
+      end
+      
+      # Internal wrapper for Rails.logger to handle tagged logging
+      class RailsLoggerWrapper
+        def initialize(rails_logger, level: nil)
+          @rails_logger = rails_logger
+          @rails_logger.level = level if level
+        end
+        
+        def method_missing(method, *args, &block)
+          if @rails_logger.respond_to?(:tagged)
+            @rails_logger.tagged('SmartMessage') do
+              @rails_logger.send(method, *args, &block)
+            end
+          else
+            @rails_logger.send(method, *args, &block)
+          end
+        end
+        
+        def respond_to_missing?(method, include_private = false)
+          @rails_logger.respond_to?(method, include_private)
+        end
+      end
+    end
+  end
+end

data/lib/smart_message/logger.rb

@@ -3,5 +3,13 @@
 # frozen_string_literal: true
 
 module SmartMessage::Logger
-  # TODO: write this
+  # 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'

data/lib/smart_message/property_descriptions.rb

@@ -13,16 +13,17 @@ module SmartMessage
 
     module ClassMethods
       def property(property_name, options = {})
+        # Extract our custom option before passing to parent
         description = options.delete(:description)
         
-        # Store description if provided
+        # Call original property method first
+        super(property_name, options)
+        
+        # Then store description if provided
         if description
           @property_descriptions ||= {}
           @property_descriptions[property_name.to_sym] = description
         end
-        
-        # Call original property method
-        super(property_name, options)
       end
 
       def property_description(property_name)

data/lib/smart_message/property_validations.rb

@@ -0,0 +1,141 @@
+# lib/smart_message/property_validations.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+module SmartMessage
+  module PropertyValidations
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_eval do
+        @property_validators = {}
+      end
+    end
+
+    module ClassMethods
+      def property(property_name, options = {})
+        # Extract our custom options before passing to Hashie::Dash
+        # Note: Hashie's 'message' option only works with 'required', so we use 'validation_message'
+        validator = options.delete(:validate)
+        validation_message = options.delete(:validation_message)
+
+        # Call original property method first
+        super(property_name, options)
+
+        # Then store validator if provided
+        if validator
+          @property_validators ||= {}
+          @property_validators[property_name.to_sym] = {
+            validator: validator,
+            message: validation_message || "Validation failed for property '#{property_name}'"
+          }
+
+          # Note: We don't override setter methods since they may conflict with Hashie::Dash
+          # Instead, validation happens during validate! calls
+        end
+      end
+
+      def property_validator(property_name)
+        @property_validators&.[](property_name.to_sym)
+      end
+
+      def property_validators
+        @property_validators&.dup || {}
+      end
+
+      def validated_properties
+        @property_validators&.keys || []
+      end
+
+      # Validate all properties with validators
+      def validate_all(instance)
+        validated_properties.each do |property_name|
+          validator_info = property_validator(property_name)
+          next unless validator_info
+
+          value = instance.send(property_name)
+          validator = validator_info[:validator]
+          error_message = validator_info[:message]
+
+          # Skip validation if value is nil and property is not required
+          next if value.nil? && !instance.class.required_properties.include?(property_name)
+
+          # Perform validation
+          is_valid = case validator
+                     when Proc
+                       instance.instance_exec(value, &validator)
+                     when Symbol
+                       instance.send(validator, value)
+                     when Regexp
+                       !!(value.to_s =~ validator)
+                     when Class
+                       value.is_a?(validator)
+                     when Array
+                       validator.include?(value)
+                     when Range
+                       validator.include?(value)
+                     else
+                       value == validator
+                     end
+
+          unless is_valid
+            raise SmartMessage::Errors::ValidationError, "#{instance.class.name}##{property_name}: #{error_message}"
+          end
+        end
+        true
+      end
+    end
+
+    # Instance methods
+    def validate!
+      self.class.validate_all(self)
+    end
+
+    def valid?
+      validate!
+      true
+    rescue SmartMessage::Errors::ValidationError
+      false
+    end
+
+    def validation_errors
+      errors = []
+      self.class.validated_properties.each do |property_name|
+        validator_info = self.class.property_validator(property_name)
+        next unless validator_info
+
+        value = send(property_name)
+        validator = validator_info[:validator]
+
+        # Skip validation if value is nil and property is not required
+        next if value.nil? && !self.class.required_properties.include?(property_name)
+
+        # Perform validation
+        is_valid = case validator
+                   when Proc
+                     instance_exec(value, &validator)
+                   when Symbol
+                     send(validator, value)
+                   when Regexp
+                     !!(value.to_s =~ validator)
+                   when Class
+                     value.is_a?(validator)
+                   when Array
+                     validator.include?(value)
+                   when Range
+                     validator.include?(value)
+                   else
+                     value == validator
+                   end
+
+        unless is_valid
+          errors << {
+            property: property_name,
+            value: value,
+            message: validator_info[:message]
+          }
+        end
+      end
+      errors
+    end
+  end
+end

data/lib/smart_message/version.rb

@@ -3,5 +3,5 @@
 # frozen_string_literal: true
 
 module SmartMessage
-  VERSION = "0.0.3"
+  VERSION = '0.0.5'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smart_message
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -204,17 +204,21 @@ files:
 - docs/examples.md
 - docs/getting-started.md
 - docs/ideas_to_think_about.md
+- docs/logging.md
 - docs/message_processing.md
 - docs/proc_handlers_summary.md
 - docs/properties.md
 - docs/serializers.md
 - docs/transports.md
 - docs/troubleshooting.md
+- examples/.gitignore
 - examples/01_point_to_point_orders.rb
 - examples/02_publish_subscribe_events.rb
 - examples/03_many_to_many_chat.rb
 - examples/04_redis_smart_home_iot.rb
 - examples/05_proc_handlers.rb
+- examples/06_custom_logger_example.rb
+- examples/07_error_handling_scenarios.rb
 - examples/README.md
 - examples/smart_home_iot_dataflow.md
 - examples/tmux_chat/README.md
@@ -233,7 +237,9 @@ files:
 - lib/smart_message/header.rb
 - lib/smart_message/logger.rb
 - lib/smart_message/logger/base.rb
+- lib/smart_message/logger/default.rb
 - lib/smart_message/property_descriptions.rb
+- lib/smart_message/property_validations.rb
 - lib/smart_message/serializer.rb
 - lib/smart_message/serializer/base.rb
 - lib/smart_message/serializer/json.rb