logstruct 0.0.1 → 0.0.2.pre.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dff0c6b2f4200e2699a4a62c6770ab74daeb3e334cd19864900302d8304fd66
-  data.tar.gz: 9ae935a538a100f2b86dd75b2ef6678875b9cd9cf3590f22eb70b367e28a61be
+  metadata.gz: 3ce0ec5e8973926358ab0282f61945eb85bbaead27060a16b00e85685b2b83f2
+  data.tar.gz: d5146c601563992a8b426f8bcfea1db40d631995c7e16d7a771e98b78010c2ce
 SHA512:
-  metadata.gz: 4d1500f3e9be588f0deaf313895721741c1e0b04e5ad57560c21f6f1df09796c399c7f73ce60b0f30889056d3c97cf27c0015fcdfc8abefedd6b89d4a45b6f11
-  data.tar.gz: '0855b2fc13820466bd95f4dde5d27ad9c6d3babdc29277615533ae519998bea79c81260217ccd3f6ed7801d6da86837ea6475496a52421befcf90b00c4d30b6c'
+  metadata.gz: 0e30c656d03a93056e85e750189277007c05737f123d0b576b9f600f75a9b48dd3ff45fdf82e3990a8b9541793dd6402013f8bf982f0addc8f1191dcc4a32fe0
+  data.tar.gz: fe24218d1771ff69ecf9a4d2fd8901aed19472ee02c38e2e14f87d0c0c3293887492b1e038f79e0985d4be6350a402c544db4bf28cf718a4a8229e61dd98f6e8

data/CHANGELOG.md

@@ -1,8 +1,32 @@
 # Changelog
 
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [0.0.1] - 2025-03-04
 
 ### Added
 
-- Initial release to secure name on RubyGems.org
-- Basic LogStruct module with version constant
+- Pushed empty gem to RubyGems to secure the name
+
+## [0.0.2-rc1] - 2025-09-05
+
+### Added
+
+- Unified GitHub Actions workflow to release RubyGem and sync/tag the Terraform provider; dry-run support for safe validation
+- Provider catalog export script and automated provider CI (build/vet/test)
+- Terraform docs page with quickstart, recipes, and provider README link
+- API design doc (typed vs. untyped) planned; initial philosophy captured
+- Coverage threshold gate (>= 80%) in CI; additional tests to lift coverage
+- Release helper: scripts/create_release_tag.sh (creates annotated tag from version.rb)
+
+### Changed
+
+- ActionMailer callbacks patched for Rails 7.0; event logging + metadata collection tested
+- Provider CloudWatch filter builder refactored for testability; key lookups aligned with exported catalog (event/source)
+
+### Fixed
+
+- Pre-commit hooks reporting; cspell dictionary updated; TypeScript import fixes in site

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DocSpring Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,67 @@
+# LogStruct
+
+Adds JSON structured logging to any Rails app. Simply add the gem to your Gemfile and add an initializer to configure it. By default, your Rails app prints JSON logs to STDOUT (or to the configured destination when `RAILS_LOG_TO_STDOUT` is set). They're easy to search and filter, you can turn them into metrics and alerts, and they're great for building dashboards in CloudWatch, Grafana, or Datadog.
+
+We support all your other favorite gems too, like Sidekiq, Sentry, and Shrine. (And if not, please open a PR!)
+
+## Features
+
+- JSON logging enabled by default in production and test environments
+- ActionMailer integration for email delivery logging
+- ActiveJob integration for job execution logging
+- Sidekiq integration for background job logging
+- Shrine integration for file upload logging
+- Error handling and reporting
+- Metadata collection for rich context
+- Lograge integration for structured request logging
+- Sensitive data scrubbing for strings (inspired by the Logstop gem)
+- Host authorization logging for security violations
+- Rack middleware for enhanced error logging
+- ActionMailer delivery callbacks for Rails 7.0.x (backported from Rails 7.1)
+- Type checking with Sorbet and RBS annotations
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'logstruct'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install logstruct
+```
+
+## Configuration and Initialization
+
+LogStruct is designed to be highly opinionated and work out of the box with minimal configuration.
+
+Please see the [documentation](https://logstruct.com/docs/configuration/) for configuration options.
+
+### Important Notes on Integration
+
+Once initialized, the gem automatically includes its modules into the appropriate base classes:
+
+- `ActiveSupport::TaggedLogging` is patched to support both Hashes and Strings
+- `ActionMailer::Base` includes error handling and event logging modules
+- We configure `Lograge` for request logging
+- A Rack middleware is inserted to catch and log errors, including security violations (IP spoofing, CSRF, blocked hosts, etc.)
+- Structured logging is set up for ActiveJob, Sidekiq, Shrine, etc.
+- Rails `config.filter_parameters` are merged into LogStruct's filters and then cleared (to avoid double filtering). Configure sensitive keys via `LogStruct.config.filters`.
+- When `RAILS_LOG_TO_STDOUT` is set, we log to STDOUT only. Otherwise, we log to STDOUT by default without adding a file appender to avoid duplicate logs.
+
+## Documentation
+
+Please see the [documentation](https://logstruct.com/docs) for more details. (All code examples are type-checked and tested, and it's harder to keep a README up to date.)
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

data/lib/log_struct/concerns/configuration.rb

@@ -0,0 +1,93 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../configuration"
+
+module LogStruct
+  module Concerns
+    # Concern for handling errors according to configured modes
+    module Configuration
+      module ClassMethods
+        extend T::Sig
+
+        sig { params(block: T.proc.params(config: LogStruct::Configuration).void).void }
+        def configure(&block)
+          yield(config)
+        end
+
+        sig { returns(LogStruct::Configuration) }
+        def config
+          LogStruct::Configuration.instance
+        end
+
+        # (Can't use alias_method since this module is extended into LogStruct)
+        sig { returns(LogStruct::Configuration) }
+        def configuration
+          config
+        end
+
+        # Setter method to replace the configuration (for testing purposes)
+        sig { params(config: LogStruct::Configuration).void }
+        def configuration=(config)
+          LogStruct::Configuration.set_instance(config)
+        end
+
+        sig { returns(T::Boolean) }
+        def enabled?
+          config.enabled
+        end
+
+        sig { void }
+        def set_enabled_from_rails_env!
+          # Set enabled based on current Rails environment and the LOGSTRUCT_ENABLED env var.
+          # Precedence:
+          # 1. Check if LOGSTRUCT_ENABLED env var is defined
+          #    - Sets enabled=true only when value is "true"
+          #    - Sets enabled=false when value is "false" (or any non-"true")
+          # 2. Otherwise, check if current Rails environment is in enabled_environments
+          # 3. Otherwise, leave as config.enabled (defaults to true)
+
+          # Then check if LOGSTRUCT_ENABLED env var is set
+          config.enabled = if ENV["LOGSTRUCT_ENABLED"]
+            # Override to true only if env var is "true"
+            ENV["LOGSTRUCT_ENABLED"] == "true"
+          else
+            config.enabled_environments.include?(::Rails.env.to_sym)
+          end
+        end
+
+        sig { returns(T::Boolean) }
+        def is_local?
+          config.local_environments.include?(::Rails.env.to_sym)
+        end
+
+        sig { returns(T::Boolean) }
+        def is_production?
+          !is_local?
+        end
+
+        sig { void }
+        def merge_rails_filter_parameters!
+          return unless ::Rails.application.config.respond_to?(:filter_parameters)
+
+          rails_filter_params = ::Rails.application.config.filter_parameters
+          return unless rails_filter_params.is_a?(Array)
+
+          # Convert all Rails filter parameters to symbols and merge with our filter keys
+          converted_params = rails_filter_params.map do |param|
+            param.respond_to?(:to_sym) ? param.to_sym : param
+          end
+
+          # Add Rails filter parameters to our filter keys
+          config.filters.filter_keys += converted_params
+
+          # Ensure no duplicates
+          config.filters.filter_keys.uniq!
+
+          # Clear Rails filter parameters since we've incorporated them
+          ::Rails.application.config.filter_parameters.clear
+        end
+      end
+    end
+  end
+end

data/lib/log_struct/concerns/error_handling.rb

@@ -0,0 +1,94 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  module Concerns
+    # Concern for handling errors according to configured modes
+    module ErrorHandling
+      module ClassMethods
+        extend T::Sig
+        extend T::Helpers
+
+        # Needed for raise
+        requires_ancestor { Module }
+
+        # Get the error handling mode for a given source
+        sig { params(source: Source).returns(ErrorHandlingMode) }
+        def error_handling_mode_for(source)
+          config = LogStruct.config
+
+          # Use a case statement for type-safety
+          case source
+          when Source::TypeChecking
+            config.error_handling_modes.type_checking_errors
+          when Source::LogStruct
+            config.error_handling_modes.logstruct_errors
+          when Source::Security
+            config.error_handling_modes.security_errors
+          when Source::Rails, Source::App, Source::Job, Source::Storage, Source::Mailer,
+               Source::Shrine, Source::CarrierWave, Source::Sidekiq
+            config.error_handling_modes.standard_errors
+          else
+            # Ensures the case statement is exhaustive
+            T.absurd(source)
+          end
+        end
+
+        # Log an errors with structured data
+        sig { params(error: StandardError, source: Source, context: T.nilable(T::Hash[Symbol, T.untyped])).void }
+        def log_error(error, source:, context: nil)
+          # Create structured log entry
+          error_log = Log::Error.from_exception(
+            source,
+            error,
+            context || {}
+          )
+          LogStruct.error(error_log)
+        end
+
+        # Report an error using the configured handler or MultiErrorReporter
+        sig { params(error: StandardError, source: Source, context: T.nilable(T::Hash[Symbol, T.untyped])).void }
+        def log_and_report_error(error, source:, context: nil)
+          log_error(error, source: source, context: context)
+          error_handler = LogStruct.config.error_reporting_handler
+          if error_handler
+            # Use the configured handler
+            error_handler.call(error, context, source)
+          else
+            # Fall back to MultiErrorReporter (detects Sentry, Bugsnag, etc.)
+            LogStruct::MultiErrorReporter.report_error(error, context || {})
+          end
+        end
+
+        # Handle an error according to the configured error handling mode (log, report, raise, etc)
+        sig { params(error: StandardError, source: Source, context: T.nilable(T::Hash[Symbol, T.untyped])).void }
+        def handle_exception(error, source:, context: nil)
+          mode = error_handling_mode_for(source)
+
+          # Log / report in production, raise locally (dev/test)
+          if mode == ErrorHandlingMode::LogProduction || mode == ErrorHandlingMode::ReportProduction
+            raise(error) if !LogStruct.is_production?
+          end
+
+          case mode
+          when ErrorHandlingMode::Ignore
+            # Do nothing
+
+          when ErrorHandlingMode::Raise
+            raise(error)
+
+          when ErrorHandlingMode::Log, ErrorHandlingMode::LogProduction
+            log_error(error, source: source, context: context)
+
+          when ErrorHandlingMode::Report, ErrorHandlingMode::ReportProduction
+            log_and_report_error(error, source: source, context: context)
+
+          else
+            # Ensures the case statement is exhaustive
+            T.absurd(mode)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/log_struct/concerns/logging.rb

@@ -0,0 +1,45 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../log"
+
+module LogStruct
+  module Concerns
+    # Concern for handling errors according to configured modes
+    module Logging
+      module ClassMethods
+        extend T::Sig
+
+        # Log a log struct at debug level
+        sig { params(log: Log::Interfaces::CommonFields).void }
+        def debug(log)
+          Rails.logger.debug(log)
+        end
+
+        # Log a log struct at info level
+        sig { params(log: Log::Interfaces::CommonFields).void }
+        def info(log)
+          Rails.logger.info(log)
+        end
+
+        # Log a log struct at warn level
+        sig { params(log: Log::Interfaces::CommonFields).void }
+        def warn(log)
+          Rails.logger.warn(log)
+        end
+
+        # Log a log struct at error level
+        sig { params(log: Log::Interfaces::CommonFields).void }
+        def error(log)
+          Rails.logger.error(log)
+        end
+
+        # Log a log struct at fatal level
+        sig { params(log: Log::Interfaces::CommonFields).void }
+        def fatal(log)
+          Rails.logger.fatal(log)
+        end
+      end
+    end
+  end
+end

data/lib/log_struct/config_struct/error_handling_modes.rb

@@ -0,0 +1,25 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  module ConfigStruct
+    class ErrorHandlingModes < T::Struct
+      include Sorbet::SerializeSymbolKeys
+
+      # How to handle different types of errors
+      # Modes:
+      # - Ignore - Ignore the error
+      # - Log - Log the error
+      # - Report - Log and report to error tracking service (but don't crash)
+      # - LogProduction - Log error in production, raise locally (dev/test)
+      # - ReportProduction - Report error in production, raise locally (dev/test)
+      # - Raise - Always raise the error
+
+      # Configurable error handling categories
+      prop :type_checking_errors, ErrorHandlingMode, default: ErrorHandlingMode::LogProduction
+      prop :logstruct_errors, ErrorHandlingMode, default: ErrorHandlingMode::LogProduction
+      prop :security_errors, ErrorHandlingMode, default: ErrorHandlingMode::Report
+      prop :standard_errors, ErrorHandlingMode, default: ErrorHandlingMode::Raise
+    end
+  end
+end

data/lib/log_struct/config_struct/filters.rb

@@ -0,0 +1,80 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  module ConfigStruct
+    class Filters < T::Struct
+      include Sorbet::SerializeSymbolKeys
+
+      # Keys that should be filtered in nested structures such as request params and job arguments.
+      # Filtered data includes information about Hashes and Arrays.
+      #
+      # { _filtered: {
+      #     _class: "Hash",                # Class of the filtered value
+      #     _bytes: 1234,                  # Length of JSON string in bytes
+      #     _keys_count: 3,                # Number of keys in the hash
+      #     _keys: [:key1, :key2, :key3],  # First 10 keys in the hash
+      #   }
+      # }
+      #
+      # Default: [:password, :password_confirmation, :pass, :pw, :token, :secret,
+      #           :credentials, :creds, :auth, :authentication, :authorization]
+      #
+      prop :filter_keys,
+        T::Array[Symbol],
+        factory: -> {
+          %i[
+            password password_confirmation pass pw token secret
+            credentials auth authentication authorization
+            credit_card ssn social_security
+          ]
+        }
+
+      # Keys where string values should include an SHA256 hash.
+      # Useful for tracing emails across requests (e.g. sign in, sign up) while protecting privacy.
+      # Default: [:email, :email_address]
+      prop :filter_keys_with_hashes,
+        T::Array[Symbol],
+        factory: -> { %i[email email_address] }
+
+      # Hash salt for SHA256 hashing (typically used for email addresses)
+      # Used for both param filters and string scrubbing
+      # Default: "l0g5t0p"
+      prop :hash_salt, String, default: "l0g5t0p"
+
+      # Hash length for SHA256 hashing (typically used for email addresses)
+      # Used for both param filters and string scrubbing
+      # Default: 12
+      prop :hash_length, Integer, default: 12
+
+      # Filter email addresses. Also controls email filtering for the ActionMailer integration
+      # (to, from, recipient fields, etc.)
+      # Default: true
+      prop :email_addresses, T::Boolean, default: true
+
+      # Filter URL passwords
+      # Default: true
+      prop :url_passwords, T::Boolean, default: true
+
+      # Filter credit card numbers
+      # Default: true
+      prop :credit_card_numbers, T::Boolean, default: true
+
+      # Filter phone numbers
+      # Default: true
+      prop :phone_numbers, T::Boolean, default: true
+
+      # Filter social security numbers
+      # Default: true
+      prop :ssns, T::Boolean, default: true
+
+      # Filter IP addresses
+      # Default: false
+      prop :ip_addresses, T::Boolean, default: false
+
+      # Filter MAC addresses
+      # Default: false
+      prop :mac_addresses, T::Boolean, default: false
+    end
+  end
+end

data/lib/log_struct/config_struct/integrations.rb

@@ -0,0 +1,89 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module LogStruct
+  module ConfigStruct
+    class Integrations < T::Struct
+      include Sorbet::SerializeSymbolKeys
+
+      # Enable or disable Sorbet error handler integration
+      # Default: true
+      prop :enable_sorbet_error_handlers, T::Boolean, default: true
+
+      # Enable or disable Lograge integration
+      # Default: true
+      prop :enable_lograge, T::Boolean, default: true
+
+      # Custom options for Lograge
+      # Default: nil
+      prop :lograge_custom_options, T.nilable(Handlers::LogrageCustomOptions), default: nil
+
+      # Enable or disable ActionMailer integration
+      # Default: true
+      prop :enable_actionmailer, T::Boolean, default: true
+
+      # Enable or disable host authorization logging
+      # Default: true
+      prop :enable_host_authorization, T::Boolean, default: true
+
+      # Enable or disable ActiveJob integration
+      # Default: true
+      prop :enable_activejob, T::Boolean, default: true
+
+      # Enable or disable Rack middleware
+      # Default: true
+      prop :enable_rack_error_handler, T::Boolean, default: true
+
+      # Enable or disable Sidekiq integration
+      # Default: true
+      prop :enable_sidekiq, T::Boolean, default: true
+
+      # Enable or disable Shrine integration
+      # Default: true
+      prop :enable_shrine, T::Boolean, default: true
+
+      # Enable or disable ActiveStorage integration
+      # Default: true
+      prop :enable_activestorage, T::Boolean, default: true
+
+      # Enable or disable CarrierWave integration
+      # Default: true
+      prop :enable_carrierwave, T::Boolean, default: true
+
+      # Enable or disable GoodJob integration
+      # Default: true
+      prop :enable_goodjob, T::Boolean, default: true
+
+      # Enable SemanticLogger integration for high-performance logging
+      # Default: true
+      prop :enable_semantic_logger, T::Boolean, default: true
+
+      # Enable colored JSON output in development
+      # Default: true
+      prop :enable_color_output, T::Boolean, default: true
+
+      # Color configuration for JSON output
+      # Default: nil (uses SemanticLogger defaults)
+      prop :color_map, T.nilable(T::Hash[Symbol, Symbol]), default: nil
+
+      # Filter noisy loggers (ActionView, etc.)
+      # Default: false
+      prop :filter_noisy_loggers, T::Boolean, default: false
+
+      # Enable SQL query logging through ActiveRecord instrumentation
+      # Default: false (can be resource intensive)
+      prop :enable_sql_logging, T::Boolean, default: false
+
+      # Only log SQL queries slower than this threshold (in milliseconds)
+      # Set to 0 or nil to log all queries
+      # Default: 100.0 (log queries taking >100ms)
+      prop :sql_slow_query_threshold, T.nilable(Float), default: 100.0
+
+      # Include bind parameters in SQL logs (disable in production for security)
+      # Default: true in development/test, false in production
+      prop :sql_log_bind_params, T::Boolean, factory: -> { !defined?(::Rails) || !::Rails.respond_to?(:env) || !::Rails.env.production? }
+    end
+  end
+end

data/lib/log_struct/configuration.rb

@@ -0,0 +1,59 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "handlers"
+require_relative "config_struct/error_handling_modes"
+require_relative "config_struct/integrations"
+require_relative "config_struct/filters"
+
+module LogStruct
+  # Core configuration class that provides a type-safe API
+  class Configuration < T::Struct
+    extend T::Sig
+
+    include Sorbet::SerializeSymbolKeys
+
+    # -------------------------------------------------------------------------------------
+    # Props
+    # -------------------------------------------------------------------------------------
+
+    prop :enabled, T::Boolean, default: true
+    prop :enabled_environments, T::Array[Symbol], factory: -> { [:test, :production] }
+    prop :local_environments, T::Array[Symbol], factory: -> { [:development, :test] }
+    const :integrations, ConfigStruct::Integrations, factory: -> { ConfigStruct::Integrations.new }
+    const :filters, ConfigStruct::Filters, factory: -> { ConfigStruct::Filters.new }
+
+    # Custom log scrubbing handler for any additional string scrubbing
+    # Default: nil
+    prop :string_scrubbing_handler, T.nilable(Handlers::StringScrubber)
+
+    # Custom handler for error reporting
+    # Default: Errors are handled by MultiErrorReporter
+    # (auto-detects Sentry, Bugsnag, Rollbar, Honeybadger, etc.)
+    prop :error_reporting_handler, T.nilable(Handlers::ErrorReporter), default: nil
+
+    # How to handle errors from various sources
+    const :error_handling_modes,
+      ConfigStruct::ErrorHandlingModes,
+      factory: -> {
+        ConfigStruct::ErrorHandlingModes.new
+      }
+
+    # -------------------------------------------------------------------------------------
+    # Class Methods
+    # -------------------------------------------------------------------------------------
+
+    # Class‐instance variable
+    @instance = T.let(nil, T.nilable(Configuration))
+
+    sig { returns(Configuration) }
+    def self.instance
+      @instance ||= T.let(Configuration.new, T.nilable(Configuration))
+    end
+
+    sig { params(config: Configuration).void }
+    def self.set_instance(config)
+      @instance = config
+    end
+  end
+end

data/lib/log_struct/enums/error_handling_mode.rb

@@ -0,0 +1,22 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  # Enum for error handling modes
+  class ErrorHandlingMode < T::Enum
+    enums do
+      # Always ignore the error
+      Ignore = new(:ignore)
+      # Always log the error
+      Log = new(:log)
+      # Always report to tracking service and continue
+      Report = new(:report)
+      # Log in production, raise locally (dev/test)
+      LogProduction = new(:log_production)
+      # Report in production, raise locally (dev/test)
+      ReportProduction = new(:report_production)
+      # Always raise regardless of environment
+      Raise = new(:raise)
+    end
+  end
+end

data/lib/log_struct/enums/error_reporter.rb

@@ -0,0 +1,14 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LogStruct
+  class ErrorReporter < T::Enum
+    enums do
+      RailsLogger = new(:rails_logger)
+      Sentry = new(:sentry)
+      Bugsnag = new(:bugsnag)
+      Rollbar = new(:rollbar)
+      Honeybadger = new(:honeybadger)
+    end
+  end
+end