logstruct 0.0.1 → 0.0.2.pre.rc1

data/lib/log_struct/log/active_job.rb

@@ -0,0 +1,64 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "interfaces/common_fields"
+require_relative "interfaces/additional_data_field"
+require_relative "shared/serialize_common"
+require_relative "shared/merge_additional_data_fields"
+require_relative "../enums/source"
+require_relative "../enums/event"
+require_relative "../enums/level"
+require_relative "../log_keys"
+
+module LogStruct
+  module Log
+    # ActiveJob log entry for structured logging
+    class ActiveJob < T::Struct
+      extend T::Sig
+
+      include Interfaces::CommonFields
+      include Interfaces::AdditionalDataField
+      include SerializeCommon
+      include MergeAdditionalDataFields
+
+      ActiveJobEvent = T.type_alias {
+        T.any(
+          Event::Enqueue,
+          Event::Schedule,
+          Event::Start,
+          Event::Finish
+        )
+      }
+
+      # Common fields
+      const :source, Source::Job, default: T.let(Source::Job, Source::Job)
+      const :event, ActiveJobEvent
+      const :timestamp, Time, factory: -> { Time.now }
+      const :level, Level, default: T.let(Level::Info, Level)
+
+      # Job-specific fields
+      const :job_id, T.nilable(String), default: nil
+      const :job_class, T.nilable(String), default: nil
+      const :queue_name, T.nilable(String), default: nil
+      const :arguments, T.nilable(T::Array[T.untyped]), default: nil
+      const :duration, T.nilable(Float), default: nil
+      const :additional_data, T::Hash[Symbol, T.untyped], default: {}
+
+      # Convert the log entry to a hash for serialization
+      sig { override.params(strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
+      def serialize(strict = true)
+        hash = serialize_common(strict)
+        merge_additional_data_fields(hash)
+
+        # Add job-specific fields if they're present
+        hash[LOG_KEYS.fetch(:job_id)] = job_id if job_id
+        hash[LOG_KEYS.fetch(:job_class)] = job_class if job_class
+        hash[LOG_KEYS.fetch(:queue_name)] = queue_name if queue_name
+        hash[LOG_KEYS.fetch(:arguments)] = arguments if arguments
+        hash[LOG_KEYS.fetch(:duration)] = duration if duration
+
+        hash
+      end
+    end
+  end
+end

data/lib/log_struct/log/active_storage.rb

@@ -0,0 +1,78 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "interfaces/common_fields"
+require_relative "shared/serialize_common"
+require_relative "../enums/source"
+require_relative "../enums/event"
+require_relative "../enums/level"
+
+module LogStruct
+  module Log
+    # ActiveStorage log entry for structured logging
+    class ActiveStorage < T::Struct
+      extend T::Sig
+
+      include Interfaces::CommonFields
+      include SerializeCommon
+
+      # Define valid event types for ActiveStorage
+      ActiveStorageEvent = T.type_alias {
+        T.any(
+          Event::Upload,
+          Event::Download,
+          Event::Delete,
+          Event::Metadata,
+          Event::Exist,
+          Event::Stream,
+          Event::Url,
+          Event::Unknown
+        )
+      }
+
+      # Common fields
+      const :source, Source::Storage, default: T.let(Source::Storage, Source::Storage)
+      const :event, ActiveStorageEvent
+      const :timestamp, Time, factory: -> { Time.now }
+      const :level, Level, default: T.let(Level::Info, Level)
+
+      # ActiveStorage-specific fields
+      const :operation, T.nilable(Symbol), default: nil
+      const :storage, T.nilable(String), default: nil
+      const :file_id, T.nilable(String), default: nil
+      const :filename, T.nilable(String), default: nil
+      const :mime_type, T.nilable(String), default: nil
+      const :size, T.nilable(Integer), default: nil
+      const :metadata, T.nilable(T::Hash[String, T.untyped]), default: nil
+      const :duration, T.nilable(Float), default: nil
+      const :checksum, T.nilable(String), default: nil
+      const :exist, T.nilable(T::Boolean), default: nil
+      const :url, T.nilable(String), default: nil
+      const :prefix, T.nilable(String), default: nil
+      const :range, T.nilable(String), default: nil
+
+      # Convert the log entry to a hash for serialization
+      sig { override.params(strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
+      def serialize(strict = true)
+        hash = serialize_common(strict)
+
+        # Add ActiveStorage-specific fields - only include non-nil values
+        hash[LOG_KEYS.fetch(:operation)] = operation if operation
+        hash[LOG_KEYS.fetch(:storage)] = storage if storage
+        hash[LOG_KEYS.fetch(:file_id)] = file_id if file_id
+        hash[LOG_KEYS.fetch(:filename)] = filename if filename
+        hash[LOG_KEYS.fetch(:mime_type)] = mime_type if mime_type
+        hash[LOG_KEYS.fetch(:size)] = size if size
+        hash[LOG_KEYS.fetch(:metadata)] = metadata if metadata
+        hash[LOG_KEYS.fetch(:duration)] = duration if duration
+        hash[LOG_KEYS.fetch(:checksum)] = checksum if checksum
+        hash[LOG_KEYS.fetch(:exist)] = exist if !exist.nil?
+        hash[LOG_KEYS.fetch(:url)] = url if url
+        hash[LOG_KEYS.fetch(:prefix)] = prefix if prefix
+        hash[LOG_KEYS.fetch(:range)] = range if range
+
+        hash
+      end
+    end
+  end
+end

data/lib/log_struct/log/carrierwave.rb

@@ -0,0 +1,82 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "interfaces/common_fields"
+require_relative "interfaces/additional_data_field"
+require_relative "shared/serialize_common"
+require_relative "shared/merge_additional_data_fields"
+require_relative "../enums/source"
+require_relative "../enums/event"
+require_relative "../enums/level"
+require_relative "../log_keys"
+
+module LogStruct
+  module Log
+    # CarrierWave log entry for structured logging
+    class CarrierWave < T::Struct
+      extend T::Sig
+
+      include Interfaces::CommonFields
+      include Interfaces::AdditionalDataField
+      include SerializeCommon
+      include MergeAdditionalDataFields
+
+      CarrierWaveEvent = T.type_alias {
+        T.any(
+          Event::Upload,
+          Event::Download,
+          Event::Delete,
+          Event::Metadata,
+          Event::Exist,
+          Event::Unknown
+        )
+      }
+
+      # Common fields
+      const :source, Source::CarrierWave, default: T.let(Source::CarrierWave, Source::CarrierWave)
+      const :event, CarrierWaveEvent
+      const :timestamp, Time, factory: -> { Time.now }
+      const :level, Level, default: T.let(Level::Info, Level)
+
+      # File-specific fields
+      const :operation, T.nilable(Symbol), default: nil
+      const :storage, T.nilable(String), default: nil
+      const :file_id, T.nilable(String), default: nil
+      const :filename, T.nilable(String), default: nil
+      const :mime_type, T.nilable(String), default: nil
+      const :size, T.nilable(Integer), default: nil
+      const :metadata, T.nilable(T::Hash[String, T.untyped]), default: nil
+      const :duration, T.nilable(Float), default: nil
+
+      # CarrierWave-specific fields
+      const :uploader, T.nilable(String), default: nil
+      const :model, T.nilable(String), default: nil
+      const :mount_point, T.nilable(String), default: nil
+      const :additional_data, T::Hash[Symbol, T.untyped], default: {}
+
+      # Convert the log entry to a hash for serialization
+      sig { override.params(strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
+      def serialize(strict = true)
+        hash = serialize_common(strict)
+        merge_additional_data_fields(hash)
+
+        # Add file-specific fields if they're present
+        hash[LOG_KEYS.fetch(:storage)] = storage if storage
+        hash[LOG_KEYS.fetch(:operation)] = operation if operation
+        hash[LOG_KEYS.fetch(:file_id)] = file_id if file_id
+        hash[LOG_KEYS.fetch(:filename)] = filename if filename
+        hash[LOG_KEYS.fetch(:mime_type)] = mime_type if mime_type
+        hash[LOG_KEYS.fetch(:size)] = size if size
+        hash[LOG_KEYS.fetch(:metadata)] = metadata if metadata
+        hash[LOG_KEYS.fetch(:duration)] = duration if duration
+
+        # Add CarrierWave-specific fields if they're present
+        hash[LOG_KEYS.fetch(:uploader)] = uploader if uploader
+        hash[LOG_KEYS.fetch(:model)] = model if model
+        hash[LOG_KEYS.fetch(:mount_point)] = mount_point if mount_point
+
+        hash
+      end
+    end
+  end
+end

data/lib/log_struct/log/error.rb

@@ -0,0 +1,76 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "interfaces/common_fields"
+require_relative "interfaces/additional_data_field"
+require_relative "interfaces/message_field"
+require_relative "shared/serialize_common"
+require_relative "shared/merge_additional_data_fields"
+require_relative "../enums/source"
+require_relative "../enums/event"
+require_relative "../enums/level"
+require_relative "../log_keys"
+
+module LogStruct
+  module Log
+    # Exception log entry for Ruby exceptions with class, message, and backtrace
+    class Error < T::Struct
+      extend T::Sig
+
+      include Interfaces::CommonFields
+      include Interfaces::AdditionalDataField
+      include Interfaces::MessageField
+      include MergeAdditionalDataFields
+
+      ErrorEvent = T.type_alias {
+        Event::Error
+      }
+
+      # Common fields
+      const :source, Source # Used by all sources, should not have a default.
+      const :event, ErrorEvent, default: T.let(Event::Error, ErrorEvent)
+      const :timestamp, Time, factory: -> { Time.now }
+      const :level, Level, default: T.let(Level::Error, Level)
+
+      # Exception-specific fields
+      const :err_class, T.class_of(StandardError)
+      const :message, String
+      const :backtrace, T.nilable(T::Array[String]), default: nil
+      const :additional_data, T::Hash[Symbol, T.untyped], default: {}
+
+      # Convert the log entry to a hash for serialization
+      sig { override.params(strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
+      def serialize(strict = true)
+        hash = serialize_common(strict)
+        merge_additional_data_fields(hash)
+
+        # Add exception-specific fields
+        hash[LOG_KEYS.fetch(:err_class)] = err_class.name
+        hash[LOG_KEYS.fetch(:message)] = message
+        if backtrace.is_a?(Array) && backtrace&.any?
+          hash[LOG_KEYS.fetch(:backtrace)] = backtrace&.first(10)
+        end
+
+        hash
+      end
+
+      # Create an Error log from a Ruby StandardError
+      sig {
+        params(
+          source: Source,
+          ex: StandardError,
+          additional_data: T::Hash[Symbol, T.untyped]
+        ).returns(Log::Error)
+      }
+      def self.from_exception(source, ex, additional_data = {})
+        new(
+          source: source,
+          message: ex.message,
+          err_class: ex.class,
+          backtrace: ex.backtrace,
+          additional_data: additional_data
+        )
+      end
+    end
+  end
+end

data/lib/log_struct/log/good_job.rb

@@ -0,0 +1,151 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "interfaces/common_fields"
+require_relative "interfaces/additional_data_field"
+require_relative "shared/serialize_common"
+require_relative "shared/merge_additional_data_fields"
+require_relative "../enums/source"
+require_relative "../enums/event"
+require_relative "../enums/level"
+require_relative "../log_keys"
+
+module LogStruct
+  module Log
+    # GoodJob log entry for structured logging
+    #
+    # GoodJob is a PostgreSQL-based ActiveJob backend that provides reliable,
+    # scalable job processing for Rails applications. This log class captures
+    # GoodJob-specific events including job execution, database operations,
+    # error handling, and performance metrics.
+    #
+    # ## Key Features Logged:
+    # - Job execution lifecycle (enqueue, start, finish, retry)
+    # - Database-backed job persistence events
+    # - Error handling and retry logic
+    # - Job batching and bulk operations
+    # - Performance metrics and timing data
+    # - Thread and process information
+    #
+    # ## Usage Examples:
+    #
+    # ```ruby
+    # # Job execution logging
+    # LogStruct::Log::GoodJob.new(
+    #   event: Event::Start,
+    #   job_id: "job_123",
+    #   job_class: "UserNotificationJob",
+    #   queue_name: "default",
+    #   execution_time: 1.5
+    # )
+    #
+    # # Error logging
+    # LogStruct::Log::GoodJob.new(
+    #   event: Event::Error,
+    #   job_id: "job_123",
+    #   error_class: "StandardError",
+    #   error_message: "Connection failed"
+    # )
+    # ```
+    class GoodJob < T::Struct
+      extend T::Sig
+
+      include Interfaces::CommonFields
+      include Interfaces::AdditionalDataField
+      include SerializeCommon
+      include MergeAdditionalDataFields
+
+      # Valid event types for GoodJob operations
+      GoodJobEvent = T.type_alias {
+        T.any(
+          Event::Log,         # General logging
+          Event::Enqueue,     # Job queued
+          Event::Start,       # Job execution started
+          Event::Finish,      # Job completed successfully
+          Event::Error,       # Job failed with error
+          Event::Schedule     # Job scheduled for future execution
+        )
+      }
+
+      # Common fields
+      const :source, Source::Job, default: T.let(Source::Job, Source::Job)
+      const :event, GoodJobEvent
+      const :timestamp, Time, factory: -> { Time.now }
+      const :level, Level, default: T.let(Level::Info, Level)
+
+      # Job identification fields
+      const :job_id, T.nilable(String), default: nil
+      const :job_class, T.nilable(String), default: nil
+      const :queue_name, T.nilable(String), default: nil
+      const :batch_id, T.nilable(String), default: nil
+      const :job_label, T.nilable(String), default: nil
+
+      # Job execution context
+      const :arguments, T.nilable(T::Array[T.untyped]), default: nil
+      const :executions, T.nilable(Integer), default: nil
+      const :exception_executions, T.nilable(Integer), default: nil
+      const :execution_time, T.nilable(Float), default: nil
+      const :scheduled_at, T.nilable(Time), default: nil
+
+      # Error information
+      const :error_class, T.nilable(String), default: nil
+      const :error_message, T.nilable(String), default: nil
+      const :error_backtrace, T.nilable(T::Array[String]), default: nil
+
+      # GoodJob-specific metadata
+      const :process_id, T.nilable(Integer), default: nil
+      const :thread_id, T.nilable(String), default: nil
+      const :priority, T.nilable(Integer), default: nil
+      const :cron_key, T.nilable(String), default: nil
+      const :database_connection_name, T.nilable(String), default: nil
+
+      # Performance and metrics
+      const :wait_time, T.nilable(Float), default: nil
+      const :run_time, T.nilable(Float), default: nil
+      const :finished_at, T.nilable(Time), default: nil
+
+      # Additional contextual data
+      const :additional_data, T::Hash[Symbol, T.untyped], default: {}
+
+      # Convert the log entry to a hash for serialization
+      sig { override.params(strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
+      def serialize(strict = true)
+        hash = serialize_common(strict)
+        merge_additional_data_fields(hash)
+
+        # Add job identification fields
+        hash[LOG_KEYS.fetch(:job_id)] = job_id if job_id
+        hash[LOG_KEYS.fetch(:job_class)] = job_class if job_class
+        hash[LOG_KEYS.fetch(:queue_name)] = queue_name if queue_name
+        hash[:batch_id] = batch_id if batch_id
+        hash[:job_label] = job_label if job_label
+
+        # Add execution context
+        hash[LOG_KEYS.fetch(:arguments)] = arguments if arguments
+        hash[:executions] = executions if executions
+        hash[:exception_executions] = exception_executions if exception_executions
+        hash[:execution_time] = execution_time if execution_time
+        hash[:scheduled_at] = scheduled_at&.iso8601 if scheduled_at
+
+        # Add error information
+        hash[LOG_KEYS.fetch(:err_class)] = error_class if error_class
+        hash[:error_message] = error_message if error_message
+        hash[LOG_KEYS.fetch(:backtrace)] = error_backtrace if error_backtrace
+
+        # Add GoodJob-specific metadata
+        hash[LOG_KEYS.fetch(:process_id)] = process_id if process_id
+        hash[LOG_KEYS.fetch(:thread_id)] = thread_id if thread_id
+        hash[:priority] = priority if priority
+        hash[:cron_key] = cron_key if cron_key
+        hash[:database_connection_name] = database_connection_name if database_connection_name
+
+        # Add performance metrics
+        hash[:wait_time] = wait_time if wait_time
+        hash[:run_time] = run_time if run_time
+        hash[:finished_at] = finished_at&.iso8601 if finished_at
+
+        hash
+      end
+    end
+  end
+end

data/lib/log_struct/log/interfaces/additional_data_field.rb

@@ -0,0 +1,20 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  module Log
+    module Interfaces
+      # Common interface for logs that include an additional_data field
+      module AdditionalDataField
+        extend T::Sig
+        extend T::Helpers
+
+        interface!
+
+        # Additional data field for extra context
+        sig { abstract.returns(T::Hash[Symbol, T.untyped]) }
+        def additional_data; end
+      end
+    end
+  end
+end

data/lib/log_struct/log/interfaces/common_fields.rb

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../../enums/source"
+require_relative "../../enums/event"
+require_relative "../../enums/level"
+
+module LogStruct
+  module Log
+    module Interfaces
+      # Common interface that all log entry types must implement
+      module CommonFields
+        extend T::Sig
+        extend T::Helpers
+
+        interface!
+
+        # The source of the log entry (JSON property: src)
+        sig { abstract.returns(Source) }
+        def source; end
+
+        # The event type of the log entry (JSON property: evt)
+        sig { abstract.returns(Event) }
+        def event; end
+
+        # The log level (JSON property: lvl)
+        sig { abstract.returns(Level) }
+        def level; end
+
+        # The timestamp of the log entry (JSON property: ts)
+        sig { abstract.returns(Time) }
+        def timestamp; end
+
+        # All logs must define a custom serialize method
+        # If the class is a T::Struct that responds to serialize then we can be sure
+        # we're getting symbols as keys and don't need to call #serialize.deep_symbolize_keys
+        sig { abstract.params(strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
+        def serialize(strict = true); end
+      end
+    end
+  end
+end

data/lib/log_struct/log/interfaces/message_field.rb

@@ -0,0 +1,20 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  module Log
+    module Interfaces
+      # Common interface for logs that include a message field
+      module MessageField
+        extend T::Sig
+        extend T::Helpers
+
+        interface!
+
+        # Message field
+        sig { abstract.returns(T.nilable(String)) }
+        def message; end
+      end
+    end
+  end
+end

data/lib/log_struct/log/interfaces/request_fields.rb

@@ -0,0 +1,36 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  module Log
+    module Interfaces
+      # Common interface for request-related fields
+      # Used by both Request and Security logs
+      module RequestFields
+        extend T::Sig
+        extend T::Helpers
+
+        interface!
+
+        # Common request fields
+        sig { abstract.returns(T.nilable(String)) }
+        def path; end
+
+        sig { abstract.returns(T.nilable(String)) }
+        def http_method; end
+
+        sig { abstract.returns(T.nilable(String)) }
+        def source_ip; end
+
+        sig { abstract.returns(T.nilable(String)) }
+        def user_agent; end
+
+        sig { abstract.returns(T.nilable(String)) }
+        def referer; end
+
+        sig { abstract.returns(T.nilable(String)) }
+        def request_id; end
+      end
+    end
+  end
+end

data/lib/log_struct/log/plain.rb

@@ -0,0 +1,53 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "interfaces/common_fields"
+require_relative "interfaces/additional_data_field"
+require_relative "shared/serialize_common"
+require_relative "shared/merge_additional_data_fields"
+require_relative "../enums/source"
+require_relative "../enums/event"
+require_relative "../enums/level"
+require_relative "../log_keys"
+
+module LogStruct
+  module Log
+    # Plain log entry for structured logging
+    class Plain < T::Struct
+      extend T::Sig
+
+      include Interfaces::CommonFields
+      include Interfaces::AdditionalDataField
+      include SerializeCommon
+      include MergeAdditionalDataFields
+
+      PlainEvent = T.type_alias {
+        Event::Log
+      }
+
+      # Common fields
+      const :source, Source, default: T.let(Source::App, Source)
+      const :event, PlainEvent, default: T.let(Event::Log, PlainEvent)
+      const :level, Level, default: T.let(Level::Info, Level)
+      const :timestamp, Time, factory: -> { Time.now }
+
+      # Plain log messages can be any type (String, Number, Array, Hash, etc.)
+      # Developers might do something like Rails.logger.info(123) or Rails.logger.info(@variable)
+      # when debugging, or gems might send all kinds of random stuff to the logger.
+      # We don't want to crash with a type error in any of these cases.
+      const :message, T.untyped # rubocop:disable Sorbet/ForbidUntypedStructProps
+
+      # Allow people to submit additional data
+      const :additional_data, T::Hash[Symbol, T.untyped], default: {}
+
+      # Convert the log entry to a hash for serialization
+      sig { override.params(strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
+      def serialize(strict = true)
+        hash = serialize_common(strict)
+        merge_additional_data_fields(hash)
+        hash[LOG_KEYS.fetch(:message)] = message
+        hash
+      end
+    end
+  end
+end