chronos-ruby 0.4.0.pre.1 → 0.5.0.pre.1

data/lib/chronos/configuration/validation.rb

@@ -0,0 +1,122 @@
+module Chronos
+  module Internal
+    # Shared validation predicates for mutable Chronos configuration.
+    #
+    # @responsibility Validate resilience, privacy, context, Rails, and endpoint settings.
+    # @motivation Keep Configuration focused on option storage and snapshot creation.
+    # @limits It is mixed into Configuration and is not a public extension API.
+    # @collaborators Chronos::Configuration values.
+    # @thread_safety Validation reads one configuration instance without shared state.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @errors Invalid values become messages; malformed URLs are contained.
+    module ConfigurationValidation
+      private
+
+      def resilience_errors
+        retry_errors + backlog_and_circuit_errors + remote_policy_errors
+      end
+
+      def retry_errors
+        errors = []
+        errors << "max_retries must be a non-negative integer" unless non_negative_integer?(max_retries)
+        errors << "retry_base_interval must be greater than zero" unless positive_number?(retry_base_interval)
+        errors << "retry_max_interval must be greater than zero" unless positive_number?(retry_max_interval)
+        if positive_number?(retry_base_interval) && positive_number?(retry_max_interval) &&
+           retry_max_interval < retry_base_interval
+          errors << "retry_max_interval must be greater than or equal to retry_base_interval"
+        end
+        errors << "retry_jitter must be between zero and one" unless rate?(retry_jitter)
+        errors
+      end
+
+      def backlog_and_circuit_errors
+        errors = []
+        errors << "backlog_size must be a non-negative integer" unless non_negative_integer?(backlog_size)
+        unless positive_integer?(circuit_failure_threshold)
+          errors << "circuit_failure_threshold must be a positive integer"
+        end
+        errors << "circuit_reset_timeout must be greater than zero" unless positive_number?(circuit_reset_timeout)
+        errors
+      end
+
+      def remote_policy_errors
+        errors = []
+        errors << "remote_configuration must be true or false" unless [true, false].include?(remote_configuration)
+        errors << "remote_config_max_bytes must be a positive integer" unless positive_integer?(remote_config_max_bytes)
+        errors << "sampling_rate must be between zero and one" unless rate?(sampling_rate)
+        unless enabled_event_types.is_a?(Array) && enabled_event_types.all? { |value| value.is_a?(String) }
+          errors << "enabled_event_types must contain only String values"
+        end
+        errors << "max_remote_send_interval must be greater than zero" unless positive_number?(max_remote_send_interval)
+        errors
+      end
+
+      def privacy_errors
+        errors = []
+        errors << "blocklist_keys must be an array" unless blocklist_keys.is_a?(Array)
+        errors << "allowlist_keys must be an array" unless allowlist_keys.is_a?(Array)
+        errors << "hash_keys must be an array" unless hash_keys.is_a?(Array)
+        errors.concat(matcher_errors("blocklist_keys", blocklist_keys))
+        errors.concat(matcher_errors("allowlist_keys", allowlist_keys))
+        errors.concat(matcher_errors("hash_keys", hash_keys))
+        errors.concat(filter_errors)
+        errors.concat(anonymization_errors)
+        errors
+      end
+
+      def context_errors
+        errors = []
+        unless context_store == :thread_local || compatible_context_store?
+          errors << "context_store must be :thread_local or implement get, set, clear, and with_context"
+        end
+        errors << "breadcrumb_capacity must be a positive integer" unless positive_integer?(breadcrumb_capacity)
+        unless breadcrumb_max_bytes.is_a?(Integer) && breadcrumb_max_bytes >= 128
+          errors << "breadcrumb_max_bytes must be an integer greater than or equal to 128"
+        end
+        rails_boolean_errors.each { |error| errors << error }
+        errors
+      end
+
+      def compatible_context_store?
+        self.class::CONTEXT_STORE_METHODS.all? { |method_name| context_store.respond_to?(method_name) }
+      end
+
+      def rails_boolean_errors
+        names = [:rails_enabled, :rails_capture_in_console, :rails_capture_in_test, :rails_capture_user_agent]
+        names.reject { |name| [true, false].include?(public_send(name)) }.map do |name|
+          "#{name} must be true or false"
+        end
+      end
+
+      def filter_errors
+        return ["filters must be an array"] unless filters.is_a?(Array)
+        return [] if filters.all? { |filter| filter.respond_to?(:call) }
+
+        ["filters must contain only callable objects"]
+      end
+
+      def anonymization_errors
+        [true, false].include?(anonymize_ip) ? [] : ["anonymize_ip must be true or false"]
+      end
+
+      def matcher_errors(name, values)
+        return [] unless values.is_a?(Array)
+        return [] if values.all? { |value| value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Regexp) }
+
+        ["#{name} must contain only String, Symbol, or Regexp values"]
+      end
+
+      def host_errors
+        return ["host is required"] if blank?(host)
+
+        uri = URI.parse(host.to_s)
+        return ["host must be an absolute HTTP or HTTPS URL"] unless uri.host && %w(http https).include?(uri.scheme)
+        return ["host must use HTTPS unless ssl_verify is explicitly disabled"] if uri.scheme != "https" && ssl_verify
+
+        []
+      rescue URI::InvalidURIError
+        ["host must be a valid URL"]
+      end
+    end
+  end
+end

data/lib/chronos/configuration.rb

@@ -1,4 +1,5 @@
 require "uri"
+require "chronos/configuration/validation"
 
 module Chronos
   # Mutable configuration used only while the Chronos agent is being set up.
@@ -19,6 +20,7 @@ module Chronos
   #   config.host = 'https://chronos.example.com'
   #   snapshot = config.snapshot
   class Configuration
+    include Internal::ConfigurationValidation
     DEFAULT_BLOCKLIST_KEYS = %w(
       password password_confirmation passwd secret api_key apikey authorization
       token access_token refresh_token private_key client_secret cookie set-cookie
@@ -37,7 +39,8 @@ module Chronos
       :backlog_size, :circuit_failure_threshold, :circuit_reset_timeout,
       :remote_configuration, :remote_config_max_bytes, :sampling_rate,
       :enabled_event_types, :max_remote_send_interval, :context_store,
-      :breadcrumb_capacity, :breadcrumb_max_bytes
+      :breadcrumb_capacity, :breadcrumb_max_bytes, :rails_enabled,
+      :rails_capture_in_console, :rails_capture_in_test, :rails_capture_user_agent
     ].freeze
 
     attr_accessor(*ATTRIBUTES)
@@ -46,6 +49,7 @@ module Chronos
       initialize_core_defaults
       initialize_privacy_defaults
       initialize_resilience_defaults
+      initialize_rails_defaults
     end
 
     def snapshot
@@ -105,6 +109,13 @@ module Chronos
       @breadcrumb_max_bytes = 2048
     end
 
+    def initialize_rails_defaults
+      @rails_enabled = true
+      @rails_capture_in_console = false
+      @rails_capture_in_test = false
+      @rails_capture_user_agent = false
+    end
+
     def initialize_privacy_defaults
       @blocklist_keys = DEFAULT_BLOCKLIST_KEYS.dup
       @allowlist_keys = []
@@ -124,55 +135,10 @@ module Chronos
       @remote_configuration = true
       @remote_config_max_bytes = 4096
       @sampling_rate = 1.0
-      @enabled_event_types = ["exception"]
+      @enabled_event_types = ["exception", "request", "query", "job", "cache"]
       @max_remote_send_interval = 60.0
     end
 
-    def resilience_errors
-      errors = []
-      errors.concat(retry_errors)
-      errors.concat(backlog_and_circuit_errors)
-      errors.concat(remote_policy_errors)
-      errors
-    end
-
-    def retry_errors
-      errors = []
-      errors << "max_retries must be a non-negative integer" unless non_negative_integer?(max_retries)
-      errors << "retry_base_interval must be greater than zero" unless positive_number?(retry_base_interval)
-      errors << "retry_max_interval must be greater than zero" unless positive_number?(retry_max_interval)
-      if positive_number?(retry_base_interval) && positive_number?(retry_max_interval) &&
-         retry_max_interval < retry_base_interval
-        errors << "retry_max_interval must be greater than or equal to retry_base_interval"
-      end
-      errors << "retry_jitter must be between zero and one" unless rate?(retry_jitter)
-      errors
-    end
-
-    def backlog_and_circuit_errors
-      errors = []
-      errors << "backlog_size must be a non-negative integer" unless non_negative_integer?(backlog_size)
-      unless positive_integer?(circuit_failure_threshold)
-        errors << "circuit_failure_threshold must be a positive integer"
-      end
-      errors << "circuit_reset_timeout must be greater than zero" unless positive_number?(circuit_reset_timeout)
-      errors
-    end
-
-    def remote_policy_errors
-      errors = []
-      unless [true, false].include?(remote_configuration)
-        errors << "remote_configuration must be true or false"
-      end
-      errors << "remote_config_max_bytes must be a positive integer" unless positive_integer?(remote_config_max_bytes)
-      errors << "sampling_rate must be between zero and one" unless rate?(sampling_rate)
-      unless enabled_event_types.is_a?(Array) && enabled_event_types.all? { |value| value.is_a?(String) }
-        errors << "enabled_event_types must contain only String values"
-      end
-      errors << "max_remote_send_interval must be greater than zero" unless positive_number?(max_remote_send_interval)
-      errors
-    end
-
     def to_hash
       ATTRIBUTES.each_with_object({}) do |attribute, values|
         value = public_send(attribute)
@@ -180,53 +146,6 @@ module Chronos
       end
     end
 
-    def privacy_errors
-      errors = []
-      errors << "blocklist_keys must be an array" unless blocklist_keys.is_a?(Array)
-      errors << "allowlist_keys must be an array" unless allowlist_keys.is_a?(Array)
-      errors << "hash_keys must be an array" unless hash_keys.is_a?(Array)
-      errors.concat(matcher_errors("blocklist_keys", blocklist_keys))
-      errors.concat(matcher_errors("allowlist_keys", allowlist_keys))
-      errors.concat(matcher_errors("hash_keys", hash_keys))
-      errors.concat(filter_errors)
-      errors.concat(anonymization_errors)
-      errors
-    end
-
-    def context_errors
-      errors = []
-      unless context_store == :thread_local || CONTEXT_STORE_METHODS.all? do |method_name|
-        context_store.respond_to?(method_name)
-      end
-        errors << "context_store must be :thread_local or implement get, set, clear, and with_context"
-      end
-      errors << "breadcrumb_capacity must be a positive integer" unless positive_integer?(breadcrumb_capacity)
-      unless breadcrumb_max_bytes.is_a?(Integer) && breadcrumb_max_bytes >= 128
-        errors << "breadcrumb_max_bytes must be an integer greater than or equal to 128"
-      end
-      errors
-    end
-
-    def filter_errors
-      return ["filters must be an array"] unless filters.is_a?(Array)
-      return [] if filters.all? { |filter| filter.respond_to?(:call) }
-
-      ["filters must contain only callable objects"]
-    end
-
-    def anonymization_errors
-      return [] if anonymize_ip == true || anonymize_ip == false
-
-      ["anonymize_ip must be true or false"]
-    end
-
-    def matcher_errors(name, values)
-      return [] unless values.is_a?(Array)
-      return [] if values.all? { |value| value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Regexp) }
-
-      ["#{name} must contain only String, Symbol, or Regexp values"]
-    end
-
     def deep_copy(value)
       case value
       when Hash
@@ -240,18 +159,6 @@ module Chronos
       end
     end
 
-    def host_errors
-      return ["host is required"] if blank?(host)
-
-      uri = URI.parse(host.to_s)
-      return ["host must be an absolute HTTP or HTTPS URL"] unless uri.host && %w(http https).include?(uri.scheme)
-      return ["host must use HTTPS unless ssl_verify is explicitly disabled"] if uri.scheme != "https" && ssl_verify
-
-      []
-    rescue URI::InvalidURIError
-      ["host must be a valid URL"]
-    end
-
     def blank?(value)
       value.nil? || value.to_s.strip.empty?
     end
@@ -271,52 +178,7 @@ module Chronos
     def rate?(value)
       value.is_a?(Numeric) && value >= 0.0 && value <= 1.0
     end
-
-    # Immutable configuration shared by all runtime components.
-    #
-    # @responsibility Expose validated settings without mutable containers.
-    # @motivation Keep capture behavior stable while multiple threads run.
-    # @limits It cannot be edited after creation.
-    # @thread_safety Safe to share between threads after construction.
-    # @compatibility Ruby 2.2.10 through Ruby 2.6.
-    class Snapshot
-      attr_reader(*ATTRIBUTES)
-
-      def initialize(values)
-        ATTRIBUTES.each do |attribute|
-          value = values[attribute]
-          deep_freeze(value)
-          instance_variable_set("@#{attribute}", value)
-        end
-        freeze
-      end
-
-      def enabled_for_environment?
-        enabled && !ignored_environments.map(&:to_s).include?(environment.to_s)
-      end
-
-      private
-
-      def deep_freeze(value)
-        return value if value.respond_to?(:call) || context_store?(value)
-
-        case value
-        when Hash
-          value.each do |key, child|
-            deep_freeze(key)
-            deep_freeze(child)
-          end
-        when Array
-          value.each { |child| deep_freeze(child) }
-        end
-        value.freeze
-      end
-
-      def context_store?(value)
-        CONTEXT_STORE_METHODS.all? { |method_name| value.respond_to?(method_name) }
-      rescue StandardError
-        false
-      end
-    end
   end
 end
+
+require "chronos/configuration/snapshot"

data/lib/chronos/core/telemetry_event.rb

@@ -0,0 +1,106 @@
+require "securerandom"
+require "time"
+
+module Chronos
+  module Core
+    # Immutable framework telemetry event normalized to the Chronos v1 envelope.
+    #
+    # @responsibility Carry a bounded event type, timestamp, context, and payload.
+    # @motivation Let integrations report metrics without depending on exception notices.
+    # @limits It does not sanitize, serialize, enqueue, or deliver itself.
+    # @collaborators TelemetrySerializer and framework integrations.
+    # @thread_safety Immutable after construction and safe to share.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   event = Chronos::Core::TelemetryEvent.new("request", {"duration_ms" => 12.0})
+    # @errors Unsupported types raise ArgumentError during construction.
+    # @performance Construction is linear in supplied context and payload size.
+    class TelemetryEvent
+      TYPES = %w(request query job cache).freeze
+
+      attr_reader :event_id, :event_type, :timestamp, :context, :payload
+
+      def initialize(event_type, payload = {}, context = {}, options = {})
+        type = event_type.to_s
+        raise ArgumentError, "unsupported telemetry event type" unless TYPES.include?(type)
+
+        clock = options[:clock] || proc { Time.now }
+        @event_id = (options[:event_id] || SecureRandom.uuid).to_s.freeze
+        @event_type = type.freeze
+        @timestamp = clock.call.utc.iso8601(6).freeze
+        @context = deep_freeze(context.is_a?(Hash) ? context : {})
+        @payload = deep_freeze(payload.is_a?(Hash) ? payload : {})
+        freeze
+      end
+
+      private
+
+      def deep_freeze(value)
+        if value.is_a?(Hash)
+          value.each do |key, child|
+            deep_freeze(key)
+            deep_freeze(child)
+          end
+        elsif value.is_a?(Array)
+          value.each { |child| deep_freeze(child) }
+        end
+        value.freeze
+      end
+    end
+
+    # Serializes framework telemetry into the common Chronos event envelope.
+    #
+    # @responsibility Sanitize telemetry, normalize JSON primitives, and enforce payload size.
+    # @motivation Give Rails subscribers the same privacy and delivery boundary as exceptions.
+    # @limits It accepts only TelemetryEvent values and does not perform delivery.
+    # @collaborators TelemetryEvent, Sanitizer, SafeSerializer, RuntimeInfo, and SerializedEvent.
+    # @thread_safety Stateless apart from immutable configuration.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   serialized = serializer.call(event)
+    # @errors Oversized events raise Chronos::Error and are contained by CaptureTelemetry.
+    # @performance Traversal and output bytes are bounded by existing serializer budgets.
+    class TelemetrySerializer
+      def initialize(config, clock = nil, options = {})
+        @config = config
+        @clock = clock || proc { Time.now }
+        @sanitizer = options[:sanitizer] || Sanitizer.new(config)
+        @safe_serializer = options[:safe_serializer] || SafeSerializer.new
+        @max_payload_size = options[:max_payload_size] || proc { @config.max_payload_size }
+        @runtime_info = RuntimeInfo.new
+      end
+
+      def call(event)
+        raise ArgumentError, "event must be a TelemetryEvent" unless event.is_a?(TelemetryEvent)
+
+        envelope = @safe_serializer.call(@sanitizer.call(build_envelope(event)))
+        body = JSON.generate(envelope)
+        body = JSON.generate(compact_envelope(envelope)) if body.bytesize > @max_payload_size.call
+        raise Error, "event exceeds max_payload_size" if body.bytesize > @max_payload_size.call
+
+        SerializedEvent.new(event.event_id, body)
+      end
+
+      private
+
+      def build_envelope(event)
+        runtime = @runtime_info.call
+        {
+          "schema_version" => "1.0", "event_id" => event.event_id,
+          "event_type" => event.event_type, "occurred_at" => event.timestamp,
+          "sent_at" => @clock.call.utc.iso8601(6), "project_key" => @config.project_id,
+          "environment" => @config.environment,
+          "service" => {"name" => @config.service_name, "version" => @config.app_version,
+                        "instance_id" => runtime[:host]},
+          "runtime" => runtime[:runtime], "context" => event.context, "payload" => event.payload
+        }
+      end
+
+      def compact_envelope(envelope)
+        envelope["context"] = {"_truncated" => true}
+        envelope["payload"] = {"_truncated" => true}
+        envelope
+      end
+    end
+  end
+end

data/lib/chronos/integrations/rack/middleware.rb

@@ -47,7 +47,11 @@ module Chronos
         end
 
         def notify_safely(error, context)
-          @notifier.notify(error, context)
+          if @notifier.respond_to?(:notify_once)
+            @notifier.notify_once(error, context)
+          else
+            @notifier.notify(error, context)
+          end
         rescue StandardError
           false
         end

data/lib/chronos/integrations.rb

@@ -5,6 +5,6 @@ module Chronos
   # @motivation Keep framework loading optional for plain Ruby applications.
   # @limits Integrations may depend only on documented public agent behavior.
   # @thread_safety Each integration documents its own guarantees.
-  # @compatibility Version 0.4 supports Rack protocol behavior on Ruby 2.2.10 through 2.6.
+  # @compatibility Version 0.5 supports Rack protocol behavior on Ruby 2.2.10 through 2.6.
   module Integrations; end
 end

data/lib/chronos/rails/installer.rb

@@ -0,0 +1,70 @@
+module Chronos
+  module Rails
+    # Installs Rails middleware and subscribers exactly once per application.
+    #
+    # @responsibility Apply feature-detected integration hooks after Rails initializers load.
+    # @motivation Centralize version-neutral installation outside Railtie DSL code.
+    # @limits It does not configure credentials or depend on private Rails APIs.
+    # @collaborators Rails application middleware, NotificationsSubscriber, and Chronos facade.
+    # @thread_safety A mutex protects the per-application installation registry.
+    # @compatibility Rails 4.2 through Rails 5.2 without Zeitwerk.
+    # @example
+    #   Chronos::Rails::Installer.new.install(Rails.application)
+    # @errors Missing optional Rails capabilities return false without affecting boot.
+    # @performance Installation is one-time; request work is delegated to bounded integrations.
+    class Installer
+      @mutex = Mutex.new
+      @applications = {}
+
+      class << self
+        attr_reader :mutex, :applications
+      end
+
+      def initialize(notifier = Chronos, subscriber = nil)
+        @notifier = notifier
+        @subscriber = subscriber || NotificationsSubscriber.new(notifier)
+      end
+
+      def install(application)
+        options = @notifier.rails_integration_options(environment, console?)
+        return false unless options[:enabled]
+
+        self.class.mutex.synchronize do
+          return false if self.class.applications[application.object_id]
+
+          install_middleware(application, options)
+          @subscriber.install
+          self.class.applications[application.object_id] = true
+        end
+        true
+      rescue StandardError
+        false
+      end
+
+      def rails_version
+        defined?(::Rails) && ::Rails.respond_to?(:version) ? ::Rails.version.to_s : "unknown"
+      end
+
+      private
+
+      def install_middleware(application, options)
+        middleware = application.config.middleware
+        return false unless middleware.respond_to?(:use)
+
+        middleware.use(
+          Chronos::Integrations::Rack::Middleware,
+          :include_user_agent => options[:include_user_agent]
+        )
+        true
+      end
+
+      def environment
+        defined?(::Rails) && ::Rails.respond_to?(:env) ? ::Rails.env.to_s : nil
+      end
+
+      def console?
+        defined?(::Rails::Console)
+      end
+    end
+  end
+end