logstruct 0.0.1 → 0.0.2.pre.rc1

data/lib/log_struct/enums/event.rb

@@ -0,0 +1,48 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  # Define log event types as an enum
+  class Event < T::Enum
+    enums do
+      # Plain log messages
+      Log = new(:log)
+
+      # Request events
+      Request = new(:request)
+
+      # Job events
+      Enqueue = new(:enqueue)
+      Schedule = new(:schedule)
+      Start = new(:start)
+      Finish = new(:finish)
+
+      # File storage events (ActiveStorage, Shrine, CarrierWave, etc.)
+      Upload = new(:upload)
+      Download = new(:download)
+      Delete = new(:delete)
+      Metadata = new(:metadata)
+      Exist = new(:exist)
+      Stream = new(:stream)
+      Url = new(:url)
+
+      # Email events
+      Delivery = new(:delivery)
+      Delivered = new(:delivered)
+
+      # Security events
+      IPSpoof = new(:ip_spoof)
+      CSRFViolation = new(:csrf_violation)
+      BlockedHost = new(:blocked_host)
+
+      # Database events
+      Database = new(:database)
+
+      # Error events
+      Error = new(:error)
+
+      # Fallback
+      Unknown = new(:unknown)
+    end
+  end
+end

data/lib/log_struct/enums/level.rb

@@ -0,0 +1,66 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "logger"
+
+module LogStruct
+  # Define log levels as an enum
+  class Level < T::Enum
+    extend T::Sig
+
+    enums do
+      # Standard log levels
+      Debug = new(:debug)
+      Info = new(:info)
+      Warn = new(:warn)
+      Error = new(:error)
+      Fatal = new(:fatal)
+      Unknown = new(:unknown)
+    end
+
+    # Convert a Level to the corresponding Logger integer constant
+    sig { returns(Integer) }
+    def to_severity_int
+      case serialize
+      when :debug then ::Logger::DEBUG
+      when :info then ::Logger::INFO
+      when :warn then ::Logger::WARN
+      when :error then ::Logger::ERROR
+      when :fatal then ::Logger::FATAL
+      else ::Logger::UNKNOWN
+      end
+    end
+
+    # Convert a string or integer severity to a Level
+    sig { params(severity: T.any(String, Symbol, Integer, NilClass)).returns(Level) }
+    def self.from_severity(severity)
+      return Unknown if severity.nil?
+      return from_severity_int(severity) if severity.is_a?(Integer)
+      from_severity_sym(severity.downcase.to_sym)
+    end
+
+    sig { params(severity: Symbol).returns(Level) }
+    def self.from_severity_sym(severity)
+      case severity.to_s.downcase.to_sym
+      when :debug then Debug
+      when :info then Info
+      when :warn then Warn
+      when :error then Error
+      when :fatal then Fatal
+      else Unknown
+      end
+    end
+
+    sig { params(severity: Integer).returns(Level) }
+    def self.from_severity_int(severity)
+      case severity
+      when ::Logger::DEBUG then Debug
+      when ::Logger::INFO then Info
+      when ::Logger::WARN then Warn
+      when ::Logger::ERROR then Error
+      when ::Logger::FATAL then Fatal
+      else Unknown
+      end
+    end
+  end
+end

data/lib/log_struct/enums/source.rb

@@ -0,0 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  # Combined Source class that unifies log and error sources
+  class Source < T::Enum
+    enums do
+      # Error sources
+      TypeChecking = new(:type_checking) # For type checking errors (Sorbet)
+      LogStruct = new(:logstruct) # Errors from LogStruct itself
+      Security = new(:security) # Security-related events
+
+      # Application sources
+      Rails = new(:rails) # For request-related logs/errors
+      Job = new(:job) # ActiveJob logs/errors
+      Storage = new(:storage) # ActiveStorage logs/errors
+      Mailer = new(:mailer) # ActionMailer logs/errors
+      App = new(:app) # General application logs/errors
+
+      # Third-party gem sources
+      Shrine = new(:shrine)
+      CarrierWave = new(:carrierwave)
+      Sidekiq = new(:sidekiq)
+    end
+  end
+end

data/lib/log_struct/enums.rb

@@ -0,0 +1,9 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Require all enums in this directory
+require_relative "enums/error_handling_mode"
+require_relative "enums/error_reporter"
+require_relative "enums/event"
+require_relative "enums/level"
+require_relative "enums/source"

data/lib/log_struct/formatter.rb

@@ -0,0 +1,224 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "logger"
+require "active_support/core_ext/object/blank"
+require "json"
+require "globalid"
+require_relative "enums/source"
+require_relative "enums/event"
+require_relative "string_scrubber"
+require_relative "log"
+require_relative "param_filters"
+require_relative "multi_error_reporter"
+
+module LogStruct
+  class Formatter < ::Logger::Formatter
+    extend T::Sig
+
+    # Add current_tags method to support ActiveSupport::TaggedLogging
+    sig { returns(T::Array[String]) }
+    def current_tags
+      Thread.current[:activesupport_tagged_logging_tags] ||= []
+    end
+
+    # Add tagged method to support ActiveSupport::TaggedLogging
+    sig { params(tags: T::Array[String], blk: T.proc.params(formatter: Formatter).void).returns(T.untyped) }
+    def tagged(*tags, &blk)
+      new_tags = tags.flatten
+      current_tags.concat(new_tags) if new_tags.any?
+      yield self
+    ensure
+      current_tags.pop(new_tags.size) if new_tags&.any?
+    end
+
+    # Add clear_tags! method to support ActiveSupport::TaggedLogging
+    sig { void }
+    def clear_tags!
+      Thread.current[:activesupport_tagged_logging_tags] = []
+    end
+
+    sig { params(tags: T::Array[String]).returns(T.untyped) }
+    def push_tags(*tags)
+      current_tags.concat(tags)
+    end
+
+    sig { params(string: String).returns(String) }
+    def scrub_string(string)
+      # Use StringScrubber module to scrub sensitive information from strings
+      StringScrubber.scrub(string)
+    end
+
+    sig { params(arg: T.untyped, recursion_depth: Integer).returns(T.untyped) }
+    def process_values(arg, recursion_depth: 0)
+      # Prevent infinite recursion in case any args have circular references
+      # or are too deeply nested. Just return args.
+      return arg if recursion_depth > 20
+
+      case arg
+      when Hash
+        result = {}
+
+        # Process each key-value pair
+        arg.each do |key, value|
+          # Check if this key should be filtered at any depth
+          result[key] = if ParamFilters.should_filter_key?(key)
+            # Filter the value
+            {_filtered: ParamFilters.summarize_json_attribute(key, value)}
+          else
+            # Process the value normally
+            process_values(value, recursion_depth: recursion_depth + 1)
+          end
+        end
+
+        result
+      when Array
+        result = arg.map { |value| process_values(value, recursion_depth: recursion_depth + 1) }
+
+        # Filter large arrays, but don't truncate backtraces (arrays of strings that look like file:line)
+        if result.size > 10 && !looks_like_backtrace?(result)
+          result = result.take(10) + ["... and #{result.size - 10} more items"]
+        end
+        result
+      when GlobalID::Identification
+        begin
+          arg.to_global_id
+        rescue
+          begin
+            case arg
+            when ActiveRecord::Base
+              "#{arg.class}(##{arg.id})"
+            else
+              # For non-ActiveRecord objects that failed to_global_id, try to get a string representation
+              # If this also fails, we want to catch it and return the error placeholder
+              T.unsafe(arg).to_s
+            end
+          rescue => e
+            LogStruct.handle_exception(e, source: Source::LogStruct)
+            "[GLOBALID_ERROR]"
+          end
+        end
+      when Source, Event
+        arg.serialize
+      when String
+        scrub_string(arg)
+      when Time
+        arg.iso8601(3)
+      else
+        # Any other type (e.g. Symbol, Integer, Float, Boolean etc.)
+        arg
+      end
+    rescue => e
+      # Report error through LogStruct's framework
+      context = {
+        processor_method: "process_values",
+        value_type: arg.class.name,
+        recursion_depth: recursion_depth
+      }
+      LogStruct.handle_exception(e, source: Source::LogStruct, context: context)
+      arg
+    end
+
+    sig { params(log_value: T.untyped, time: Time).returns(T::Hash[Symbol, T.untyped]) }
+    def log_value_to_hash(log_value, time:)
+      case log_value
+      when Log::Interfaces::CommonFields
+        # Our log classes all implement a custom #serialize method that use symbol keys
+        log_value.serialize
+
+      when T::Struct
+        # Default T::Struct.serialize methods returns a hash with string keys, so convert them to symbols
+        log_value.serialize.deep_symbolize_keys
+
+      when Hash
+        # Use hash as is and convert string keys to symbols
+        log_value.dup.deep_symbolize_keys
+
+      else
+        # Create a Plain log with the message as a string and serialize it with symbol keys
+        # log_value can be literally anything: Integer, Float, Boolean, NilClass, etc.
+        log_message = case log_value
+        # Handle all the basic types without any further processing
+        when String, Symbol, TrueClass, FalseClass, NilClass, Array, Hash, Time, Numeric
+          log_value
+        else
+          # Handle the serialization of complex objects in a useful way:
+          #
+          # 1. For ActiveRecord models: Use as_json which includes attributes
+          # 2. For objects with custom as_json implementations: Use their implementation
+          # 3. For basic objects that only have ActiveSupport's as_json: Use to_s
+          begin
+            method_owner = log_value.method(:as_json).owner
+
+            # If it's ActiveRecord, ActiveModel, or a custom implementation, use as_json
+            if method_owner.to_s.include?("ActiveRecord") ||
+                method_owner.to_s.include?("ActiveModel") ||
+                method_owner.to_s.exclude?("ActiveSupport::CoreExtensions") &&
+                    method_owner.to_s.exclude?("Object")
+              log_value.as_json
+            else
+              # For plain objects with only the default ActiveSupport as_json
+              log_value.to_s
+            end
+          rescue => e
+            # Handle serialization errors
+            context = {
+              object_class: log_value.class.name,
+              object_inspect: log_value.inspect.truncate(100)
+            }
+            LogStruct.handle_exception(e, source: Source::LogStruct, context: context)
+
+            # Fall back to the string representation to ensure we continue processing
+            log_value.to_s
+          end
+        end
+
+        Log::Plain.new(
+          message: log_message,
+          timestamp: time
+        ).serialize
+      end
+    end
+
+    # Serializes Log (or string) into JSON
+    sig { params(severity: T.any(String, Symbol, Integer), time: Time, progname: T.nilable(String), log_value: T.untyped).returns(String) }
+    def call(severity, time, progname, log_value)
+      level_enum = Level.from_severity(severity)
+
+      data = log_value_to_hash(log_value, time: time)
+
+      # Filter params, scrub sensitive values, format ActiveJob GlobalID arguments
+      data = process_values(data)
+
+      # Add standard fields if not already present
+      data[:src] ||= Source::App
+      data[:evt] ||= Event::Log
+      data[:ts] ||= time.iso8601(3)
+      data[:lvl] = level_enum # Set level from severity parameter
+      data[:prog] = progname if progname.present?
+
+      generate_json(data)
+    end
+
+    # Output as JSON with a newline. We mock this method in tests so we can
+    # inspect the data right before it gets turned into a JSON string.
+    sig { params(data: T::Hash[T.untyped, T.untyped]).returns(String) }
+    def generate_json(data)
+      "#{data.to_json}\n"
+    end
+
+    # Check if an array looks like a backtrace (array of strings with file:line pattern)
+    sig { params(array: T::Array[T.untyped]).returns(T::Boolean) }
+    def looks_like_backtrace?(array)
+      return false if array.empty?
+
+      # Check if most elements look like backtrace lines (file.rb:123 or similar patterns)
+      backtrace_like_count = array.first(5).count do |element|
+        element.is_a?(String) && element.match?(/\A[^:\s]+:\d+/)
+      end
+
+      # If at least 3 out of the first 5 elements look like backtrace lines, treat as backtrace
+      backtrace_like_count >= 3
+    end
+  end
+end

data/lib/log_struct/handlers.rb

@@ -0,0 +1,27 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  # Module for custom handlers used throughout the library
+  module Handlers
+    # Type for Lograge custom options
+    LogrageCustomOptions = T.type_alias {
+      T.proc.params(
+        event: ActiveSupport::Notifications::Event,
+        options: T::Hash[Symbol, T.untyped]
+      ).returns(T.untyped)
+    }
+
+    # Type for error reporting handlers
+    ErrorReporter = T.type_alias {
+      T.proc.params(
+        error: StandardError,
+        context: T.nilable(T::Hash[Symbol, T.untyped]),
+        source: Source
+      ).void
+    }
+
+    # Type for string scrubbing handlers
+    StringScrubber = T.type_alias { T.proc.params(string: String).returns(String) }
+  end
+end

data/lib/log_struct/hash_utils.rb

@@ -0,0 +1,21 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "digest"
+
+module LogStruct
+  # Utility module for hashing sensitive data
+  module HashUtils
+    class << self
+      extend T::Sig
+
+      # Create a hash of a string value for tracing while preserving privacy
+      sig { params(value: String).returns(String) }
+      def hash_value(value)
+        salt = LogStruct.config.filters.hash_salt
+        length = LogStruct.config.filters.hash_length
+        Digest::SHA256.hexdigest("#{salt}#{value}")[0...length] || "error"
+      end
+    end
+  end
+end

data/lib/log_struct/integrations/action_mailer/callbacks.rb

@@ -0,0 +1,100 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  module Integrations
+    module ActionMailer
+      # Backport of the *_deliver callbacks from Rails 7.1
+      module Callbacks
+        extend T::Sig
+        extend ::ActiveSupport::Concern
+
+        # Track if we've already patched MessageDelivery
+        @patched_message_delivery = T.let(false, T::Boolean)
+
+        # We can't use included block with strict typing
+        # This will be handled by ActiveSupport::Concern at runtime
+        included do
+          include ::ActiveSupport::Callbacks
+          if defined?(::ActiveSupport) && ::ActiveSupport.gem_version >= Gem::Version.new("7.1.0")
+            define_callbacks :deliver, skip_after_callbacks_if_terminated: true
+          else
+            define_callbacks :deliver
+          end
+        end
+
+        # When this module is prepended (our integration uses prepend), ensure callbacks are defined
+        if respond_to?(:prepended)
+          prepended do
+            include ::ActiveSupport::Callbacks
+            if defined?(::ActiveSupport) && ::ActiveSupport.gem_version >= Gem::Version.new("7.1.0")
+              define_callbacks :deliver, skip_after_callbacks_if_terminated: true
+            else
+              define_callbacks :deliver
+            end
+          end
+        end
+
+        # Define class methods in a separate module
+        module ClassMethods
+          extend T::Sig
+
+          # Defines a callback that will get called right before the
+          # message is sent to the delivery method.
+          sig { params(filters: T.untyped, blk: T.nilable(T.proc.bind(T.untyped).void)).void }
+          def before_deliver(*filters, &blk)
+            # Use T.unsafe for splat arguments due to Sorbet limitation
+            T.unsafe(self).set_callback(:deliver, :before, *filters, &blk)
+          end
+
+          # Defines a callback that will get called right after the
+          # message's delivery method is finished.
+          sig { params(filters: T.untyped, blk: T.nilable(T.proc.bind(T.untyped).void)).void }
+          def after_deliver(*filters, &blk)
+            # Use T.unsafe for splat arguments due to Sorbet limitation
+            T.unsafe(self).set_callback(:deliver, :after, *filters, &blk)
+          end
+
+          # Defines a callback that will get called around the message's deliver method.
+          sig { params(filters: T.untyped, blk: T.nilable(T.proc.bind(T.untyped).params(arg0: T.untyped).void)).void }
+          def around_deliver(*filters, &blk)
+            # Use T.unsafe for splat arguments due to Sorbet limitation
+            T.unsafe(self).set_callback(:deliver, :around, *filters, &blk)
+          end
+        end
+
+        # Module to patch ActionMailer::MessageDelivery with callback support
+        module MessageDeliveryCallbacks
+          extend T::Sig
+
+          sig { returns(T.untyped) }
+          def deliver_now
+            processed_mailer.run_callbacks(:deliver) do
+              message.deliver
+            end
+          end
+
+          sig { returns(T.untyped) }
+          def deliver_now!
+            processed_mailer.run_callbacks(:deliver) do
+              message.deliver!
+            end
+          end
+        end
+
+        sig { returns(T::Boolean) }
+        def self.patch_message_delivery
+          # Return early if we've already patched
+          return true if @patched_message_delivery
+
+          # Prepend our module to add callback support to MessageDelivery
+          ::ActionMailer::MessageDelivery.prepend(MessageDeliveryCallbacks)
+
+          # Mark as patched so we don't do it again
+          @patched_message_delivery = true
+          true
+        end
+      end
+    end
+  end
+end

data/lib/log_struct/integrations/action_mailer/error_handling.rb

@@ -0,0 +1,173 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  module Integrations
+    module ActionMailer
+      # Handles error handling for ActionMailer
+      #
+      # IMPORTANT LIMITATIONS:
+      # 1. This module must be included BEFORE users define rescue_from handlers
+      #    to ensure proper handler precedence (user handlers are checked first)
+      # 2. Rails rescue_from handlers don't bubble to parent class handlers after reraise
+      # 3. Handler order matters: Rails checks rescue_from handlers in reverse declaration order
+      module ErrorHandling
+        extend T::Sig
+        extend ActiveSupport::Concern
+
+        # NOTE: rescue_from handlers are checked in reverse order of declaration.
+        # We want LogStruct handlers to be checked AFTER user handlers (lower priority),
+        # so we need to add them BEFORE user handlers are declared.
+
+        # This will be called when the module is included/prepended
+        sig { params(base: T.untyped).void }
+        def self.install_handler(base)
+          # Only add the handler once per class
+          return if base.instance_variable_get(:@_logstruct_handler_installed)
+
+          # Add our handler FIRST so it has lower priority than user handlers
+          base.rescue_from StandardError, with: :log_and_reraise_error
+
+          # Mark as installed to prevent duplicates
+          base.instance_variable_set(:@_logstruct_handler_installed, true)
+        end
+
+        included do
+          LogStruct::Integrations::ActionMailer::ErrorHandling.install_handler(self)
+        end
+
+        # Also support prepended (used by tests and manual setup)
+        sig { params(base: T.untyped).void }
+        def self.prepended(base)
+          install_handler(base)
+        end
+
+        protected
+
+        # Just log the error without reporting or retrying
+        sig { params(ex: StandardError).void }
+        def log_and_ignore_error(ex)
+          log_email_delivery_error(ex, notify: false, report: false, reraise: false)
+        end
+
+        # Log and report to error service, but doesn't reraise.
+        sig { params(ex: StandardError).void }
+        def log_and_report_error(ex)
+          log_email_delivery_error(ex, notify: false, report: true, reraise: false)
+        end
+
+        # Log, report to error service, and reraise for retry
+        sig { params(ex: StandardError).void }
+        def log_and_reraise_error(ex)
+          log_email_delivery_error(ex, notify: false, report: true, reraise: true)
+        end
+
+        private
+
+        # Handle an error from a mailer
+        sig { params(mailer: T.untyped, error: StandardError, message: String).void }
+        def log_structured_error(mailer, error, message)
+          # Create a structured exception log with context
+          context = {
+            mailer_class: mailer.class.to_s,
+            mailer_action: mailer.respond_to?(:action_name) ? mailer.action_name : nil,
+            message: message
+          }
+
+          # Create the structured exception log
+          exception_data = Log::Error.from_exception(
+            Source::Mailer,
+            error,
+            context
+          )
+
+          # Log the structured error
+          LogStruct.error(exception_data)
+        end
+
+        # Log when email delivery fails
+        sig { params(error: StandardError, notify: T::Boolean, report: T::Boolean, reraise: T::Boolean).void }
+        def log_email_delivery_error(error, notify: false, report: true, reraise: true)
+          # Generate appropriate error message
+          message = error_message_for(error, reraise)
+
+          # Use structured error logging
+          log_structured_error(self, error, message)
+
+          # Handle notifications and reporting
+          handle_error_notifications(error, notify, report, reraise)
+        end
+
+        # Generate appropriate error message based on error handling strategy
+        sig { params(error: StandardError, reraise: T::Boolean).returns(String) }
+        def error_message_for(error, reraise)
+          if reraise
+            "#{error.class}: Email delivery error, will retry. Recipients: #{recipients(error)}"
+          else
+            "#{error.class}: Cannot send email to #{recipients(error)}"
+          end
+        end
+
+        # Handle error notifications, reporting, and reraising
+        sig { params(error: StandardError, notify: T::Boolean, report: T::Boolean, reraise: T::Boolean).void }
+        def handle_error_notifications(error, notify, report, reraise)
+          # Log a notification event if requested
+          log_notification_event(error) if notify
+
+          # Report to error reporting service if requested
+          if report
+            context = {
+              mailer_class: self.class.to_s,
+              mailer_action: respond_to?(:action_name) ? action_name : nil,
+              recipients: recipients(error)
+            }
+
+            # Create an exception log for structured logging
+            exception_data = Log::Error.from_exception(
+              Source::Mailer,
+              error,
+              context
+            )
+
+            # Log the exception with structured data
+            LogStruct.error(exception_data)
+
+            # Call the error handler
+            LogStruct.handle_exception(error, source: Source::Mailer, context: context)
+          end
+
+          # Re-raise the error if requested
+          Kernel.raise error if reraise
+        end
+
+        # Log a notification event that can be picked up by external systems
+        sig { params(error: StandardError).void }
+        def log_notification_event(error)
+          # Create an error log data object
+          exception_data = Log::Error.from_exception(
+            Source::Mailer,
+            error,
+            {
+              mailer: self.class,
+              action: action_name,
+              recipients: recipients(error)
+            }
+          )
+
+          # Log the error at info level since it's not a critical error
+          LogStruct.info(exception_data)
+        end
+
+        sig { params(error: StandardError).returns(String) }
+        def recipients(error)
+          # Extract recipient info if available
+          if error.respond_to?(:recipients) && T.unsafe(error).recipients.present?
+            T.unsafe(error).recipients.join(", ")
+          else
+            "unknown"
+          end
+        end
+      end
+    end
+  end
+end