logstruct 0.0.1 → 0.0.2.pre.rc1

data/lib/log_struct/integrations/active_storage.rb

@@ -0,0 +1,94 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../enums/source"
+require_relative "../enums/event"
+require_relative "../log/active_storage"
+
+module LogStruct
+  module Integrations
+    # Integration for ActiveStorage structured logging
+    module ActiveStorage
+      extend T::Sig
+      extend IntegrationInterface
+
+      # Set up ActiveStorage structured logging
+      sig { override.params(config: LogStruct::Configuration).returns(T.nilable(T::Boolean)) }
+      def self.setup(config)
+        return nil unless defined?(::ActiveStorage)
+        return nil unless config.enabled
+        return nil unless config.integrations.enable_activestorage
+
+        # Subscribe to all ActiveStorage service events
+        ::ActiveSupport::Notifications.subscribe(/service_.*\.active_storage/) do |*args|
+          process_active_storage_event(::ActiveSupport::Notifications::Event.new(*args), config)
+        end
+
+        true
+      end
+
+      private_class_method
+
+      # Process ActiveStorage events and create structured logs
+      sig { params(event: ActiveSupport::Notifications::Event, config: LogStruct::Configuration).void }
+      def self.process_active_storage_event(event, config)
+        return unless config.enabled
+        return unless config.integrations.enable_activestorage
+
+        # Extract key information from the event
+        event_name = event.name.sub(/\.active_storage$/, "")
+        service_name = event.payload[:service]
+        duration = event.duration
+
+        # Map service events to log event types
+        event_type = case event_name
+        when "service_upload"
+          Event::Upload
+        when "service_download"
+          Event::Download
+        when "service_delete"
+          Event::Delete
+        when "service_delete_prefixed"
+          Event::Delete
+        when "service_exist"
+          Event::Exist
+        when "service_url"
+          Event::Url
+        when "service_download_chunk"
+          Event::Download
+        when "service_stream"
+          Event::Stream
+        when "service_update_metadata"
+          Event::Metadata
+        else
+          Event::Unknown
+        end
+
+        # Map the event name to an operation
+        operation = event_name.sub(/^service_/, "").to_sym
+
+        # Create structured log event specific to ActiveStorage
+        log_data = Log::ActiveStorage.new(
+          event: event_type,
+          operation: operation,
+          storage: service_name.to_s,
+          file_id: event.payload[:key].to_s,
+          checksum: event.payload[:checksum].to_s,
+          duration: duration,
+          # Add other fields where available
+          metadata: event.payload[:metadata],
+          exist: event.payload[:exist],
+          url: event.payload[:url],
+          filename: event.payload[:filename],
+          mime_type: event.payload[:content_type],
+          size: event.payload[:byte_size],
+          prefix: event.payload[:prefix],
+          range: event.payload[:range]
+        )
+
+        # Log structured data
+        LogStruct.info(log_data)
+      end
+    end
+  end
+end

data/lib/log_struct/integrations/carrierwave.rb

@@ -0,0 +1,111 @@
+# typed: strict
+# frozen_string_literal: true
+
+begin
+  require "carrierwave"
+rescue LoadError
+  # CarrierWave gem is not available, integration will be skipped
+end
+
+module LogStruct
+  module Integrations
+    # CarrierWave integration for structured logging
+    module CarrierWave
+      extend T::Sig
+      extend IntegrationInterface
+
+      # Set up CarrierWave structured logging
+      sig { override.params(config: LogStruct::Configuration).returns(T.nilable(T::Boolean)) }
+      def self.setup(config)
+        return nil unless defined?(::CarrierWave)
+        return nil unless config.enabled
+        return nil unless config.integrations.enable_carrierwave
+
+        # Patch CarrierWave to add logging
+        ::CarrierWave::Uploader::Base.prepend(LoggingMethods)
+
+        true
+      end
+
+      # Methods to add logging to CarrierWave operations
+      module LoggingMethods
+        extend T::Sig
+        extend T::Helpers
+        requires_ancestor { ::CarrierWave::Uploader::Base }
+
+        # Log file storage operations
+        sig { params(args: T.untyped).returns(T.untyped) }
+        def store!(*args)
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          result = super
+          duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+          # Extract file information
+          file_size = file.size if file.respond_to?(:size)
+          {
+            identifier: identifier,
+            filename: file.filename,
+            content_type: file.content_type,
+            size: file_size,
+            store_path: store_path,
+            extension: file.extension
+          }
+
+          # Log the store operation with structured data
+          log_data = Log::CarrierWave.new(
+            source: Source::CarrierWave,
+            event: Event::Upload,
+            duration: duration * 1000.0, # Convert to ms
+            model: model.class.name,
+            uploader: self.class.name,
+            storage: storage.class.name,
+            mount_point: mounted_as.to_s,
+            filename: file.filename,
+            mime_type: file.content_type,
+            size: file_size,
+            file_id: identifier,
+            additional_data: {
+              version: version_name.to_s,
+              store_path: store_path,
+              extension: file.extension
+            }
+          )
+
+          ::Rails.logger.info(log_data)
+          result
+        end
+
+        # Log file retrieve operations
+        sig { params(identifier: T.untyped, args: T.untyped).returns(T.untyped) }
+        def retrieve_from_store!(identifier, *args)
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          result = super
+          duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+          # Extract file information if available
+          file_size = file.size if file&.respond_to?(:size)
+
+          # Log the retrieve operation with structured data
+          log_data = Log::CarrierWave.new(
+            source: Source::CarrierWave,
+            event: Event::Download,
+            duration: duration * 1000.0, # Convert to ms
+            uploader: self.class.name,
+            storage: storage.class.name,
+            mount_point: mounted_as.to_s,
+            file_id: identifier,
+            filename: file&.filename,
+            mime_type: file&.content_type,
+            size: file_size,
+            additional_data: {
+              version: version_name.to_s
+            }
+          )
+
+          ::Rails.logger.info(log_data)
+          result
+        end
+      end
+    end
+  end
+end

data/lib/log_struct/integrations/good_job/log_subscriber.rb

@@ -0,0 +1,228 @@
+# typed: strict
+# frozen_string_literal: true
+
+begin
+  require "active_support/log_subscriber"
+rescue LoadError
+  # ActiveSupport is not available, log subscriber will be skipped
+end
+
+require_relative "../../log/good_job"
+require_relative "../../enums/event"
+require_relative "../../enums/level"
+
+module LogStruct
+  module Integrations
+    module GoodJob
+      # LogSubscriber for GoodJob ActiveSupport notifications
+      #
+      # This subscriber captures GoodJob's ActiveSupport notifications and converts
+      # them into structured LogStruct::Log::GoodJob entries. It provides detailed
+      # logging for job lifecycle events, performance metrics, and error tracking.
+      #
+      # ## Supported Events:
+      # - job.enqueue - Job queued for execution
+      # - job.start - Job execution started
+      # - job.finish - Job completed successfully
+      # - job.error - Job failed with error
+      # - job.retry - Job retry initiated
+      # - job.schedule - Job scheduled for future execution
+      #
+      # ## Event Data Captured:
+      # - Job identification (ID, class, queue)
+      # - Execution context (arguments, priority, scheduled time)
+      # - Performance metrics (execution time, wait time)
+      # - Error information (class, message, backtrace)
+      # - Process and thread information
+      class LogSubscriber < ::ActiveSupport::LogSubscriber
+        extend T::Sig
+
+        # Job enqueued event
+        sig { params(event: T.untyped).void }
+        def enqueue(event)
+          job_data = extract_job_data(event)
+
+          log_entry = LogStruct::Log::GoodJob.new(
+            event: Event::Enqueue,
+            level: Level::Info,
+            job_id: job_data[:job_id],
+            job_class: job_data[:job_class],
+            queue_name: job_data[:queue_name],
+            arguments: job_data[:arguments],
+            scheduled_at: job_data[:scheduled_at],
+            priority: job_data[:priority],
+            execution_time: event.duration,
+            additional_data: {
+              enqueue_caller: job_data[:caller_location]
+            }
+          )
+
+          logger.info(log_entry)
+        end
+
+        # Job execution started event
+        sig { params(event: T.untyped).void }
+        def start(event)
+          job_data = extract_job_data(event)
+
+          log_entry = LogStruct::Log::GoodJob.new(
+            event: Event::Start,
+            level: Level::Info,
+            job_id: job_data[:job_id],
+            job_class: job_data[:job_class],
+            queue_name: job_data[:queue_name],
+            arguments: job_data[:arguments],
+            executions: job_data[:executions],
+            wait_time: job_data[:wait_time],
+            scheduled_at: job_data[:scheduled_at],
+            process_id: ::Process.pid,
+            thread_id: Thread.current.object_id.to_s(36)
+          )
+
+          logger.info(log_entry)
+        end
+
+        # Job completed successfully event
+        sig { params(event: T.untyped).void }
+        def finish(event)
+          job_data = extract_job_data(event)
+
+          log_entry = LogStruct::Log::GoodJob.new(
+            event: Event::Finish,
+            level: Level::Info,
+            job_id: job_data[:job_id],
+            job_class: job_data[:job_class],
+            queue_name: job_data[:queue_name],
+            executions: job_data[:executions],
+            run_time: event.duration,
+            finished_at: Time.now,
+            process_id: ::Process.pid,
+            thread_id: Thread.current.object_id.to_s(36),
+            additional_data: {
+              result: job_data[:result]
+            }
+          )
+
+          logger.info(log_entry)
+        end
+
+        # Job failed with error event
+        sig { params(event: T.untyped).void }
+        def error(event)
+          job_data = extract_job_data(event)
+
+          log_entry = LogStruct::Log::GoodJob.new(
+            event: Event::Error,
+            level: Level::Error,
+            job_id: job_data[:job_id],
+            job_class: job_data[:job_class],
+            queue_name: job_data[:queue_name],
+            executions: job_data[:executions],
+            exception_executions: job_data[:exception_executions],
+            error_class: job_data[:error_class],
+            error_message: job_data[:error_message],
+            error_backtrace: job_data[:error_backtrace],
+            run_time: event.duration,
+            process_id: ::Process.pid,
+            thread_id: Thread.current.object_id.to_s(36)
+          )
+
+          logger.error(log_entry)
+        end
+
+        # Job scheduled for future execution event
+        sig { params(event: T.untyped).void }
+        def schedule(event)
+          job_data = extract_job_data(event)
+
+          log_entry = LogStruct::Log::GoodJob.new(
+            event: Event::Schedule,
+            level: Level::Info,
+            job_id: job_data[:job_id],
+            job_class: job_data[:job_class],
+            queue_name: job_data[:queue_name],
+            arguments: job_data[:arguments],
+            scheduled_at: job_data[:scheduled_at],
+            priority: job_data[:priority],
+            cron_key: job_data[:cron_key],
+            execution_time: event.duration
+          )
+
+          logger.info(log_entry)
+        end
+
+        private
+
+        # Extract job data from ActiveSupport event payload
+        sig { params(event: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+        def extract_job_data(event)
+          payload = event.payload || {}
+          job = payload[:job]
+          execution = payload[:execution] || payload[:good_job_execution]
+          exception = payload[:exception] || payload[:error]
+
+          data = {}
+
+          # Basic job information
+          if job
+            data[:job_id] = job.job_id if job.respond_to?(:job_id)
+            data[:job_class] = job.job_class if job.respond_to?(:job_class)
+            data[:queue_name] = job.queue_name if job.respond_to?(:queue_name)
+            data[:arguments] = job.arguments if job.respond_to?(:arguments)
+            data[:priority] = job.priority if job.respond_to?(:priority)
+            data[:scheduled_at] = job.scheduled_at if job.respond_to?(:scheduled_at)
+            data[:cron_key] = job.cron_key if job.respond_to?(:cron_key)
+            data[:caller_location] = job.enqueue_caller_location if job.respond_to?(:enqueue_caller_location)
+          end
+
+          # Execution-specific information
+          if execution
+            data[:executions] = execution.executions if execution.respond_to?(:executions)
+            data[:exception_executions] = execution.exception_executions if execution.respond_to?(:exception_executions)
+            # Use existing wait_time if available, otherwise calculate it
+            if execution.respond_to?(:wait_time) && execution.wait_time
+              data[:wait_time] = execution.wait_time
+            elsif execution.respond_to?(:created_at)
+              data[:wait_time] = calculate_wait_time(execution)
+            end
+            data[:batch_id] = execution.batch_id if execution.respond_to?(:batch_id)
+            data[:cron_key] ||= execution.cron_key if execution.respond_to?(:cron_key)
+          end
+
+          # Error information
+          if exception
+            data[:error_class] = exception.class.name
+            data[:error_message] = exception.message
+            data[:error_backtrace] = exception.backtrace&.first(20) # Limit backtrace size
+          end
+
+          # Result information
+          data[:result] = payload[:result] if payload.key?(:result)
+
+          data
+        end
+
+        # Calculate wait time from job creation to execution start
+        sig { params(execution: T.untyped).returns(T.nilable(Float)) }
+        def calculate_wait_time(execution)
+          return nil unless execution.respond_to?(:created_at)
+          return nil unless execution.respond_to?(:performed_at)
+          return nil unless execution.created_at && execution.performed_at
+
+          (execution.performed_at - execution.created_at).to_f
+        rescue
+          # Return nil if calculation fails
+          nil
+        end
+
+        # Get the appropriate logger for GoodJob events
+        sig { returns(T.untyped) }
+        def logger
+          # Always use Rails.logger - in production it will be configured by the integration setup,
+          # in tests it will be set up by the test harness
+          Rails.logger
+        end
+      end
+    end
+  end
+end

data/lib/log_struct/integrations/good_job/logger.rb

@@ -0,0 +1,73 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../../semantic_logger/logger"
+require_relative "../../log/good_job"
+require_relative "../../enums/source"
+
+module LogStruct
+  module Integrations
+    module GoodJob
+      # Custom Logger for GoodJob that creates LogStruct::Log::GoodJob entries
+      #
+      # This logger extends LogStruct's SemanticLogger to provide optimal logging
+      # performance while creating structured log entries specifically for GoodJob
+      # operations and events.
+      #
+      # ## Benefits:
+      # - High-performance logging with SemanticLogger backend
+      # - Structured GoodJob-specific log entries
+      # - Automatic job context capture
+      # - Thread and process information
+      # - Performance metrics and timing data
+      #
+      # ## Usage:
+      # This logger is automatically configured when the GoodJob integration
+      # is enabled. It replaces GoodJob.logger to provide structured logging
+      # for all GoodJob operations.
+      class Logger < LogStruct::SemanticLogger::Logger
+        extend T::Sig
+
+        # Override log methods to create GoodJob-specific log structs
+        %i[debug info warn error fatal].each do |level|
+          define_method(level) do |message = nil, payload = nil, &block|
+            # Extract basic job context from thread-local variables
+            job_context = {}
+
+            if Thread.current[:good_job_execution]
+              execution = Thread.current[:good_job_execution]
+              if execution.respond_to?(:job_id)
+                job_context[:job_id] = execution.job_id
+                job_context[:job_class] = execution.job_class if execution.respond_to?(:job_class)
+                job_context[:queue_name] = execution.queue_name if execution.respond_to?(:queue_name)
+                job_context[:executions] = execution.executions if execution.respond_to?(:executions)
+                job_context[:scheduled_at] = execution.scheduled_at if execution.respond_to?(:scheduled_at)
+                job_context[:priority] = execution.priority if execution.respond_to?(:priority)
+              end
+            end
+
+            # Create a GoodJob log struct with the context
+            log_struct = Log::GoodJob.new(
+              event: Event::Log,
+              level: LogStruct::Level.from_severity(level.to_s.upcase),
+              process_id: ::Process.pid,
+              thread_id: Thread.current.object_id.to_s(36),
+              job_id: job_context[:job_id],
+              job_class: job_context[:job_class],
+              queue_name: job_context[:queue_name],
+              executions: job_context[:executions],
+              scheduled_at: job_context[:scheduled_at],
+              priority: job_context[:priority],
+              additional_data: {
+                message: message || (block ? block.call : "")
+              }
+            )
+
+            # Pass the struct to SemanticLogger
+            super(log_struct, payload, &nil)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/log_struct/integrations/good_job.rb

@@ -0,0 +1,111 @@
+# typed: strict
+# frozen_string_literal: true
+
+begin
+  require "good_job"
+rescue LoadError
+  # GoodJob gem is not available, integration will be skipped
+end
+
+require_relative "good_job/logger" if defined?(::GoodJob)
+require_relative "good_job/log_subscriber" if defined?(::GoodJob)
+
+module LogStruct
+  module Integrations
+    # GoodJob integration for structured logging
+    #
+    # GoodJob is a PostgreSQL-based ActiveJob backend that provides reliable,
+    # scalable job processing for Rails applications. This integration provides
+    # structured logging for all GoodJob operations.
+    #
+    # ## Features:
+    # - Structured logging for job execution lifecycle
+    # - Error tracking and retry logging
+    # - Performance metrics and timing data
+    # - Database operation logging
+    # - Thread and process tracking
+    # - Custom GoodJob logger with LogStruct formatting
+    #
+    # ## Integration Points:
+    # - Replaces GoodJob.logger with LogStruct-compatible logger
+    # - Subscribes to GoodJob's ActiveSupport notifications
+    # - Captures job execution events, errors, and performance metrics
+    # - Logs database operations and connection information
+    #
+    # ## Configuration:
+    # The integration is automatically enabled when GoodJob is detected and
+    # LogStruct configuration allows it. It can be disabled by setting:
+    #
+    # ```ruby
+    # config.integrations.enable_goodjob = false
+    # ```
+    module GoodJob
+      extend T::Sig
+      extend IntegrationInterface
+
+      # Set up GoodJob structured logging
+      #
+      # This method configures GoodJob to use LogStruct's structured logging
+      # by replacing the default logger and subscribing to job events.
+      #
+      # @param config [LogStruct::Configuration] The LogStruct configuration
+      # @return [Boolean, nil] Returns true if setup was successful, nil if skipped
+      sig { override.params(config: LogStruct::Configuration).returns(T.nilable(T::Boolean)) }
+      def self.setup(config)
+        return nil unless defined?(::GoodJob)
+        return nil unless config.enabled
+        return nil unless config.integrations.enable_goodjob
+
+        # Replace GoodJob's logger with our structured logger
+        configure_logger
+
+        # Subscribe to GoodJob's ActiveSupport notifications
+        subscribe_to_notifications
+
+        true
+      end
+
+      # Configure GoodJob to use LogStruct's structured logger
+      sig { void }
+      def self.configure_logger
+        return unless defined?(::GoodJob)
+
+        # Use direct reference to avoid const_get - GoodJob is guaranteed to be defined here
+        goodjob_module = T.unsafe(GoodJob)
+
+        # Replace GoodJob.logger with our structured logger if GoodJob is available
+        if goodjob_module.respond_to?(:logger=)
+          goodjob_module.logger = LogStruct::Integrations::GoodJob::Logger.new("GoodJob")
+        end
+
+        # Configure error handling for thread errors if GoodJob supports it
+        if goodjob_module.respond_to?(:on_thread_error=)
+          goodjob_module.on_thread_error = ->(exception) do
+            # Log the error using our structured format
+            log_entry = LogStruct::Log::GoodJob.new(
+              event: Event::Error,
+              level: Level::Error,
+              error_class: exception.class.name,
+              error_message: exception.message,
+              error_backtrace: exception.backtrace
+            )
+
+            goodjob_module.logger.error(log_entry)
+          end
+        end
+      end
+
+      # Subscribe to GoodJob's ActiveSupport notifications
+      sig { void }
+      def self.subscribe_to_notifications
+        return unless defined?(::GoodJob)
+
+        # Subscribe to our custom log subscriber for GoodJob events
+        LogStruct::Integrations::GoodJob::LogSubscriber.attach_to :good_job
+      end
+
+      private_class_method :configure_logger
+      private_class_method :subscribe_to_notifications
+    end
+  end
+end

data/lib/log_struct/integrations/host_authorization.rb

@@ -0,0 +1,81 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "action_dispatch/middleware/host_authorization"
+require_relative "../enums/event"
+
+module LogStruct
+  module Integrations
+    # Host Authorization integration for structured logging of blocked hosts
+    module HostAuthorization
+      extend T::Sig
+      extend IntegrationInterface
+
+      RESPONSE_HTML = T.let(
+        "<html><head><title>Blocked Host</title></head><body>" \
+        "<h1>Blocked Host</h1>" \
+        "<p>This host is not permitted to access this application.</p>" \
+        "<p>If you are the administrator, check your configuration.</p>" \
+        "</body></html>",
+        String
+      )
+      RESPONSE_HEADERS = T.let(
+        {
+          "Content-Type" => "text/html",
+          "Content-Length" => RESPONSE_HTML.bytesize.to_s
+        }.freeze,
+        T::Hash[String, String]
+      )
+      FORBIDDEN_STATUS = T.let(403, Integer)
+
+      # Set up host authorization logging
+      sig { override.params(config: LogStruct::Configuration).returns(T.nilable(T::Boolean)) }
+      def self.setup(config)
+        return nil unless config.enabled
+        return nil unless config.integrations.enable_host_authorization
+
+        # Define the response app as a separate variable to fix block alignment
+        response_app = lambda do |env|
+          request = ::ActionDispatch::Request.new(env)
+          # Include the blocked hosts app configuration in the log entry
+          # This can be helpful later when reviewing logs.
+          blocked_hosts = env["action_dispatch.blocked_hosts"]
+
+          # Create a security error to be handled
+          blocked_host_error = ::ActionController::BadRequest.new(
+            "Blocked host detected: #{request.host}"
+          )
+
+          # Create request context hash
+          context = {
+            blocked_host: request.host,
+            client_ip: request.ip,
+            x_forwarded_for: request.x_forwarded_for,
+            http_method: request.method,
+            path: request.path,
+            user_agent: request.user_agent,
+            allowed_hosts: blocked_hosts.allowed_hosts,
+            allow_ip_hosts: blocked_hosts.allow_ip_hosts
+          }
+
+          # Handle error according to configured mode (log, report, raise)
+          LogStruct.handle_exception(
+            blocked_host_error,
+            source: Source::Security,
+            context: context
+          )
+
+          # Use pre-defined headers and response if we are only logging or reporting
+          [FORBIDDEN_STATUS, RESPONSE_HEADERS, [RESPONSE_HTML]]
+        end
+
+        # Replace the default HostAuthorization app with our custom app for logging
+        Rails.application.config.host_authorization = {
+          response_app: response_app
+        }
+
+        true
+      end
+    end
+  end
+end