logstruct 0.0.1 → 0.0.2.pre.rc1

data/lib/log_struct/log/request.rb

@@ -0,0 +1,76 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "interfaces/common_fields"
+require_relative "interfaces/request_fields"
+require_relative "shared/serialize_common"
+require_relative "shared/add_request_fields"
+require_relative "../enums/source"
+require_relative "../enums/event"
+require_relative "../enums/level"
+require_relative "../log_keys"
+
+module LogStruct
+  module Log
+    # Request log entry for structured logging
+    class Request < T::Struct
+      extend T::Sig
+
+      include Interfaces::CommonFields
+      include Interfaces::RequestFields
+      include SerializeCommon
+      include AddRequestFields
+
+      RequestEvent = T.type_alias {
+        Event::Request
+      }
+
+      # Common fields
+      const :source, Source::Rails, default: T.let(Source::Rails, Source::Rails)
+      const :event, RequestEvent, default: T.let(Event::Request, RequestEvent)
+      const :timestamp, Time, factory: -> { Time.now }
+      const :level, Level, default: T.let(Level::Info, Level)
+
+      # Request-specific fields
+      # NOTE: `method` is a reserved word, so we use `http_method`
+      # prop while setting `method` in the serialized output
+      const :http_method, T.nilable(String), default: nil
+      const :path, T.nilable(String), default: nil
+      const :format, T.nilable(String), default: nil
+      const :controller, T.nilable(String), default: nil
+      const :action, T.nilable(String), default: nil
+      const :status, T.nilable(Integer), default: nil
+      const :duration, T.nilable(Float), default: nil
+      const :view, T.nilable(Float), default: nil
+      const :db, T.nilable(Float), default: nil
+      const :params, T.nilable(T::Hash[Symbol, T.untyped]), default: nil
+      const :source_ip, T.nilable(String), default: nil
+      const :user_agent, T.nilable(String), default: nil
+      const :referer, T.nilable(String), default: nil
+      const :request_id, 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_request_fields(hash)
+        hash[LOG_KEYS.fetch(:http_method)] = http_method if http_method
+        hash[LOG_KEYS.fetch(:path)] = path if path
+        hash[LOG_KEYS.fetch(:format)] = format if format
+        hash[LOG_KEYS.fetch(:controller)] = controller if controller
+        hash[LOG_KEYS.fetch(:action)] = action if action
+        hash[LOG_KEYS.fetch(:status)] = status if status
+        hash[LOG_KEYS.fetch(:duration)] = duration if duration
+        hash[LOG_KEYS.fetch(:view)] = view if view
+        hash[LOG_KEYS.fetch(:db)] = db if db
+        hash[LOG_KEYS.fetch(:params)] = params if params
+        hash[LOG_KEYS.fetch(:source_ip)] = source_ip if source_ip
+        hash[LOG_KEYS.fetch(:user_agent)] = user_agent if user_agent
+        hash[LOG_KEYS.fetch(:referer)] = referer if referer
+        hash[LOG_KEYS.fetch(:request_id)] = request_id if request_id
+
+        hash
+      end
+    end
+  end
+end

data/lib/log_struct/log/security.rb

@@ -0,0 +1,80 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "interfaces/common_fields"
+require_relative "interfaces/additional_data_field"
+require_relative "interfaces/message_field"
+require_relative "interfaces/request_fields"
+require_relative "shared/add_request_fields"
+require_relative "shared/merge_additional_data_fields"
+require_relative "shared/serialize_common"
+require_relative "../enums/event"
+require_relative "../enums/level"
+require_relative "../enums/source"
+require_relative "../log_keys"
+
+module LogStruct
+  module Log
+    # Security log entry for structured logging of security-related events
+    class Security < T::Struct
+      extend T::Sig
+
+      include Interfaces::CommonFields
+      include Interfaces::AdditionalDataField
+      include Interfaces::MessageField
+      include Interfaces::RequestFields
+      include SerializeCommon
+      include AddRequestFields
+      include MergeAdditionalDataFields
+
+      SecurityEvent = T.type_alias {
+        T.any(
+          Event::IPSpoof,
+          Event::CSRFViolation,
+          Event::BlockedHost
+        )
+      }
+
+      # Common fields
+      const :source, Source::Security, default: T.let(Source::Security, Source::Security)
+      const :event, SecurityEvent
+      const :timestamp, Time, factory: -> { Time.now }
+      const :level, Level, default: T.let(Level::Error, Level)
+
+      # Security-specific fields
+      const :message, T.nilable(String), default: nil
+      const :blocked_host, T.nilable(String), default: nil
+      const :blocked_hosts, T.nilable(T::Array[String]), default: nil
+      const :client_ip, T.nilable(String), default: nil
+      const :x_forwarded_for, T.nilable(String), default: nil
+
+      # Additional data (merged into hash)
+      const :additional_data, T::Hash[Symbol, T.untyped], default: {}
+
+      # Common request fields
+      const :path, T.nilable(String), default: nil
+      const :http_method, T.nilable(String), default: nil, name: "method"
+      const :source_ip, T.nilable(String), default: nil
+      const :user_agent, T.nilable(String), default: nil
+      const :referer, T.nilable(String), default: nil
+      const :request_id, 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_request_fields(hash)
+        merge_additional_data_fields(hash)
+
+        # Add security-specific fields
+        hash[LOG_KEYS.fetch(:message)] = message if message
+        hash[LOG_KEYS.fetch(:blocked_host)] = blocked_host if blocked_host
+        hash[LOG_KEYS.fetch(:blocked_hosts)] = blocked_hosts if blocked_hosts
+        hash[LOG_KEYS.fetch(:client_ip)] = client_ip if client_ip
+        hash[LOG_KEYS.fetch(:x_forwarded_for)] = x_forwarded_for if x_forwarded_for
+
+        hash
+      end
+    end
+  end
+end

data/lib/log_struct/log/shared/add_request_fields.rb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../../log_keys"
+require_relative "../interfaces/request_fields"
+
+module LogStruct
+  module Log
+    # Common log serialization method
+    module AddRequestFields
+      extend T::Sig
+      extend T::Helpers
+
+      requires_ancestor { Interfaces::RequestFields }
+
+      # Helper method to serialize request fields
+      sig { params(hash: T::Hash[Symbol, T.untyped]).void }
+      def add_request_fields(hash)
+        # Add request-specific fields if they're present
+        hash[LOG_KEYS.fetch(:path)] = path if path
+        hash[LOG_KEYS.fetch(:http_method)] = http_method if http_method # Use `method` in JSON
+        hash[LOG_KEYS.fetch(:source_ip)] = source_ip if source_ip
+        hash[LOG_KEYS.fetch(:user_agent)] = user_agent if user_agent
+        hash[LOG_KEYS.fetch(:referer)] = referer if referer
+        hash[LOG_KEYS.fetch(:request_id)] = request_id if request_id
+      end
+    end
+  end
+end

data/lib/log_struct/log/shared/merge_additional_data_fields.rb

@@ -0,0 +1,28 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../../log_keys"
+require_relative "../interfaces/additional_data_field"
+require_relative "serialize_common"
+
+module LogStruct
+  module Log
+    # Helper module for merging additional data into serialized logs
+    module MergeAdditionalDataFields
+      extend T::Sig
+      extend T::Helpers
+
+      include SerializeCommon
+
+      requires_ancestor { T::Struct }
+      requires_ancestor { Interfaces::AdditionalDataField }
+
+      sig { params(hash: T::Hash[Symbol, T.untyped]).void }
+      def merge_additional_data_fields(hash)
+        additional_data.each do |key, value|
+          hash[key.to_sym] = value
+        end
+      end
+    end
+  end
+end

data/lib/log_struct/log/shared/serialize_common.rb

@@ -0,0 +1,36 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../../log_keys"
+require_relative "../interfaces/common_fields"
+
+module LogStruct
+  module Log
+    # Common log serialization method
+    module SerializeCommon
+      extend T::Sig
+      extend T::Helpers
+
+      requires_ancestor { Interfaces::CommonFields }
+
+      # Convert the log entry to a hash for serialization.
+      # (strict param is unused, but need same signature as default T::Struct.serialize)
+      sig { params(strict: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
+      def serialize_common(strict = true)
+        {
+          LOG_KEYS.fetch(:source) => source.serialize.to_s,
+          LOG_KEYS.fetch(:event) => event.serialize.to_s,
+          LOG_KEYS.fetch(:level) => level.serialize.to_s,
+          LOG_KEYS.fetch(:timestamp) => timestamp.iso8601(3)
+        }
+      end
+
+      # Override as_json to use our custom serialize method instead of default T::Struct serialization
+      sig { params(options: T.untyped).returns(T::Hash[String, T.untyped]) }
+      def as_json(options = nil)
+        # Convert symbol keys to strings for JSON
+        serialize.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/log_struct/log/shrine.rb

@@ -0,0 +1,70 @@
+# 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
+    # Shrine log entry for structured logging
+    class Shrine < T::Struct
+      extend T::Sig
+
+      include Interfaces::CommonFields
+      include Interfaces::AdditionalDataField
+      include SerializeCommon
+      include MergeAdditionalDataFields
+
+      ShrineEvent = T.type_alias {
+        T.any(
+          Event::Upload,
+          Event::Download,
+          Event::Delete,
+          Event::Metadata,
+          Event::Exist,
+          Event::Unknown
+        )
+      }
+
+      # Common fields
+      const :source, Source::Shrine, default: T.let(Source::Shrine, Source::Shrine)
+      const :event, ShrineEvent
+      const :timestamp, Time, factory: -> { Time.now }
+      const :level, Level, default: T.let(Level::Info, Level)
+
+      # Shrine-specific fields
+      const :storage, T.nilable(String), default: nil
+      const :location, T.nilable(String), default: nil
+      const :upload_options, T.nilable(T::Hash[Symbol, T.untyped]), default: nil
+      const :download_options, T.nilable(T::Hash[Symbol, T.untyped]), default: nil
+      const :options, T.nilable(T::Hash[Symbol, T.untyped]), default: nil
+      const :uploader, T.nilable(String), 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 Shrine-specific fields if they're present
+        hash[LOG_KEYS.fetch(:storage)] = storage if storage
+        hash[LOG_KEYS.fetch(:location)] = location if location
+        hash[LOG_KEYS.fetch(:upload_options)] = upload_options if upload_options
+        hash[LOG_KEYS.fetch(:download_options)] = download_options if download_options
+        hash[LOG_KEYS.fetch(:options)] = options if options
+        hash[LOG_KEYS.fetch(:uploader)] = uploader if uploader
+        hash[LOG_KEYS.fetch(:duration)] = duration if duration
+
+        hash
+      end
+    end
+  end
+end

data/lib/log_struct/log/sidekiq.rb

@@ -0,0 +1,50 @@
+# 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"
+require_relative "../log_keys"
+
+module LogStruct
+  module Log
+    # Sidekiq log entry for structured logging
+    class Sidekiq < T::Struct
+      extend T::Sig
+
+      include Interfaces::CommonFields
+      include SerializeCommon
+
+      # Define valid event types for Sidekiq (currently only Log is used)
+      SidekiqEvent = T.type_alias { Event::Log }
+
+      # Common fields
+      const :source, Source::Sidekiq, default: T.let(Source::Sidekiq, Source::Sidekiq)
+      const :event, SidekiqEvent, default: T.let(Event::Log, SidekiqEvent)
+      const :timestamp, Time, factory: -> { Time.now }
+      const :level, Level, default: T.let(Level::Info, Level)
+
+      # Sidekiq-specific fields
+      const :process_id, T.nilable(Integer), default: nil
+      const :thread_id, T.nilable(T.any(Integer, String)), default: nil
+      const :message, T.nilable(String), default: nil
+      const :context, T.nilable(T::Hash[Symbol, T.untyped]), 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 Sidekiq-specific fields if they're present
+        hash[LOG_KEYS.fetch(:message)] = message if message
+        hash[LOG_KEYS.fetch(:context)] = context if context
+        hash[LOG_KEYS.fetch(:process_id)] = process_id if process_id
+        hash[LOG_KEYS.fetch(:thread_id)] = thread_id if thread_id
+
+        hash
+      end
+    end
+  end
+end

data/lib/log_struct/log/sql.rb

@@ -0,0 +1,126 @@
+# 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"
+
+module LogStruct
+  module Log
+    # SQL Query Log Structure
+    #
+    # Captures detailed information about SQL queries executed through ActiveRecord.
+    # This provides structured logging for database operations, including:
+    # - Query text and operation name
+    # - Execution timing and performance metrics
+    # - Row counts and connection information
+    # - Safely filtered bind parameters
+    #
+    # ## Use Cases:
+    # - Development debugging of N+1 queries
+    # - Production performance monitoring
+    # - Database query analysis and optimization
+    # - Audit trails for data access patterns
+    #
+    # ## Security:
+    # - SQL queries are safe (always parameterized with ?)
+    # - Bind parameters are filtered through LogStruct's param filters
+    # - Sensitive data like passwords, tokens are automatically scrubbed
+    #
+    # ## Example Usage:
+    #
+    # ```ruby
+    # # Automatically captured when SQL query integration is enabled
+    # LogStruct.config.integrations.enable_sql_logging = true
+    #
+    # # Manual logging (rare)
+    # sql_log = LogStruct::Log::SQL.new(
+    #   message: "User lookup query",
+    #   sql: "SELECT * FROM users WHERE id = ?",
+    #   name: "User Load",
+    #   duration: 2.3,
+    #   row_count: 1,
+    #   bind_params: [123]
+    # )
+    # LogStruct.info(sql_log)
+    # ```
+    class SQL < T::Struct
+      extend T::Sig
+      include Interfaces::CommonFields
+      include Interfaces::AdditionalDataField
+      include SerializeCommon
+      include MergeAdditionalDataFields
+
+      SQLEvent = T.type_alias {
+        Event::Database
+      }
+
+      # Common fields
+      const :source, Source, default: T.let(Source::App, Source)
+      const :event, SQLEvent, default: T.let(Event::Database, SQLEvent)
+      const :level, Level, default: T.let(Level::Info, Level)
+      const :timestamp, Time, factory: -> { Time.now }
+      const :message, String
+
+      # The SQL query that was executed (parameterized, safe to log)
+      const :sql, String
+
+      # The name of the database operation (e.g., "User Load", "Post Create")
+      const :name, String
+
+      # Duration of the query execution in milliseconds
+      const :duration, Float
+
+      # Number of rows affected or returned by the query
+      const :row_count, T.nilable(Integer)
+
+      # Database connection information (adapter name)
+      const :connection_adapter, T.nilable(String)
+
+      # Filtered bind parameters (sensitive data removed)
+      const :bind_params, T.nilable(T::Array[T.untyped])
+
+      # Database name (if available)
+      const :database_name, T.nilable(String)
+
+      # Connection pool size information (for monitoring)
+      const :connection_pool_size, T.nilable(Integer)
+
+      # Active connection count (for monitoring)
+      const :active_connections, T.nilable(Integer)
+
+      # SQL operation type (SELECT, INSERT, UPDATE, DELETE, etc.)
+      const :operation_type, T.nilable(String)
+
+      # Table names involved in the query (extracted from SQL)
+      const :table_names, T.nilable(T::Array[String])
+
+      # Allow additional custom 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 SQL-specific fields using LOG_KEYS mapping for consistency
+        hash[LOG_KEYS.fetch(:message)] = message
+        hash[LOG_KEYS.fetch(:sql)] = sql
+        hash[LOG_KEYS.fetch(:name)] = name
+        hash[LOG_KEYS.fetch(:duration)] = duration
+        hash[LOG_KEYS.fetch(:row_count)] = row_count
+        hash[LOG_KEYS.fetch(:connection_adapter)] = connection_adapter
+        hash[LOG_KEYS.fetch(:bind_params)] = bind_params
+        hash[LOG_KEYS.fetch(:database_name)] = database_name
+        hash[LOG_KEYS.fetch(:connection_pool_size)] = connection_pool_size
+        hash[LOG_KEYS.fetch(:active_connections)] = active_connections
+        hash[LOG_KEYS.fetch(:operation_type)] = operation_type
+        hash[LOG_KEYS.fetch(:table_names)] = table_names
+
+        hash
+      end
+    end
+  end
+end

data/lib/log_struct/log.rb

@@ -0,0 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Common Enums
+require_relative "enums/source"
+require_relative "enums/event"
+require_relative "enums/level"
+
+# Log Structs
+require_relative "log/carrierwave"
+require_relative "log/action_mailer"
+require_relative "log/active_storage"
+require_relative "log/active_job"
+require_relative "log/error"
+require_relative "log/good_job"
+require_relative "log/plain"
+require_relative "log/request"
+require_relative "log/security"
+require_relative "log/shrine"
+require_relative "log/sidekiq"
+require_relative "log/sql"
+
+module LogStruct
+  # Type aliases for all possible log types
+  # This should be updated whenever a new log type is added
+  # (Can't use sealed! unless we want to put everything in one giant file.)
+  LogClassType = T.type_alias do
+    T.any(
+      T.class_of(LogStruct::Log::CarrierWave),
+      T.class_of(LogStruct::Log::ActionMailer),
+      T.class_of(LogStruct::Log::ActiveStorage),
+      T.class_of(LogStruct::Log::ActiveJob),
+      T.class_of(LogStruct::Log::Error),
+      T.class_of(LogStruct::Log::GoodJob),
+      T.class_of(LogStruct::Log::Plain),
+      T.class_of(LogStruct::Log::Request),
+      T.class_of(LogStruct::Log::Security),
+      T.class_of(LogStruct::Log::Shrine),
+      T.class_of(LogStruct::Log::Sidekiq),
+      T.class_of(LogStruct::Log::SQL)
+    )
+  end
+end

data/lib/log_struct/log_keys.rb

@@ -0,0 +1,102 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  # Define a mapping of property names to JSON keys
+  LOG_KEYS = T.let({
+    # Ruby struct property name => JSON key name
+
+    # Shared fields
+    source: :src,
+    event: :evt,
+    timestamp: :ts,
+    level: :lvl,
+
+    # Common fields
+    message: :msg,
+    data: :data,
+
+    # Request-related fields
+    path: :path,
+    http_method: :method, # Use `http_method` because `method` is a reserved word
+    source_ip: :source_ip,
+    user_agent: :user_agent,
+    referer: :referer,
+    request_id: :request_id,
+
+    # HTTP-specific fields
+    format: :format,
+    controller: :controller,
+    action: :action,
+    status: :status,
+    duration: :duration,
+    view: :view,
+    db: :db,
+    params: :params,
+
+    # Security-specific fields
+    blocked_host: :blocked_host,
+    blocked_hosts: :blocked_hosts,
+    client_ip: :client_ip,
+    x_forwarded_for: :x_forwarded_for,
+
+    # Email-specific fields
+    to: :to,
+    from: :from,
+    subject: :subject,
+
+    # Error fields
+    err_class: :err_class,
+    backtrace: :backtrace,
+
+    # Job-specific fields
+    job_id: :job_id,
+    job_class: :job_class,
+    queue_name: :queue_name,
+    arguments: :arguments,
+    retry_count: :retry_count,
+
+    # Sidekiq-specific fields
+    process_id: :pid,
+    thread_id: :tid,
+    context: :ctx,
+
+    # Storage-specific fields (ActiveStorage)
+    checksum: :checksum,
+    exist: :exist,
+    url: :url,
+    prefix: :prefix,
+    range: :range,
+
+    # Storage-specific fields (Shrine)
+    storage: :storage,
+    operation: :op,
+    file_id: :file_id,
+    filename: :filename,
+    mime_type: :mime_type,
+    size: :size,
+    metadata: :metadata,
+    location: :location,
+    upload_options: :upload_opts,
+    download_options: :download_opts,
+    options: :opts,
+    uploader: :uploader,
+
+    # CarrierWave-specific fields
+    model: :model,
+    mount_point: :mount_point,
+
+    # SQL-specific fields
+    sql: :sql,
+    name: :name,
+    row_count: :row_count,
+    connection_adapter: :connection_adapter,
+    bind_params: :bind_params,
+    database_name: :database_name,
+    connection_pool_size: :connection_pool_size,
+    active_connections: :active_connections,
+    operation_type: :operation_type,
+    table_names: :table_names
+  }.freeze,
+    T::Hash[Symbol, Symbol])
+end

data/lib/log_struct/monkey_patches/active_support/tagged_logging/formatter.rb

@@ -0,0 +1,36 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "active_support/tagged_logging"
+
+# Monkey-patch ActiveSupport::TaggedLogging::Formatter to support hash inputs
+# This allows us to pass structured data to the logger and have tags incorporated
+# directly into the hash instead of being prepended as strings
+module ActiveSupport
+  module TaggedLogging
+    module FormatterExtension
+      extend T::Sig
+      extend T::Helpers
+      requires_ancestor { ::ActiveSupport::TaggedLogging::Formatter }
+
+      # Override the call method to support hash input/output, and wrap
+      # plain strings in a Hash under a `msg` key.
+      # The data is then passed to our custom log formatter that transforms it
+      # into a JSON string before logging.
+      sig { params(severity: T.any(String, Symbol), time: Time, progname: T.untyped, data: T.untyped).returns(String) }
+      def call(severity, time, progname, data)
+        # Convert data to a hash if it's not already one
+        data = {message: data.to_s} unless data.is_a?(Hash)
+
+        # Add current tags to the hash if present
+        tags = current_tags
+        data[:tags] = tags if tags.present?
+
+        # Call the original formatter with our enhanced data
+        super
+      end
+    end
+  end
+end
+
+ActiveSupport::TaggedLogging::Formatter.prepend(ActiveSupport::TaggedLogging::FormatterExtension)