chronos-ruby 0.9.0.pre.3 → 1.0.0

data/lib/chronos/adapters/net_http_transport.rb

@@ -22,6 +22,7 @@ module Chronos
     class NetHttpTransport
       EVENT_PATH = "/api/v1/events".freeze
       REMOTE_CONFIGURATION_HEADER = "X-Chronos-Remote-Configuration".freeze
+      RESPONSE_BODY_MAX_BYTES = 8192
 
       def initialize(config, logger = nil)
         @config = config
@@ -71,7 +72,11 @@ module Chronos
         request["Idempotency-Key"] = event.event_id
         request.body = request_body(event.body)
         request["Content-Encoding"] = "gzip" if @config.gzip
-        http.start { |connection| connection.request(request) }
+        http.start do |connection|
+          connection.request(request) do |response|
+            read_bounded_response(response)
+          end
+        end
       end
 
       def endpoint_uri
@@ -101,7 +106,7 @@ module Chronos
 
       def classify(response)
         code = response.code.to_i
-        options = {:status_code => code}
+        options = {:status_code => code, :response => parse_response(response)}
         if code >= 200 && code < 300
           options[:remote_configuration] = parse_remote_configuration(response)
           return Ports::TransportResult.new(:success, options)
@@ -116,6 +121,35 @@ module Chronos
         Ports::TransportResult.new(:client_error, options)
       end
 
+      def read_bounded_response(response)
+        body = ""
+        overflow = false
+        response.read_body do |chunk|
+          next if overflow
+
+          remaining = RESPONSE_BODY_MAX_BYTES - body.bytesize
+          if chunk.bytesize > remaining
+            overflow = true
+          else
+            body << chunk
+          end
+        end
+        response.instance_variable_set(:@chronos_response_body, overflow ? nil : body)
+      end
+
+      def parse_response(response)
+        content_type = response["Content-Type"].to_s.split(";", 2).first
+        return nil unless content_type == "application/json"
+
+        body = response.instance_variable_get(:@chronos_response_body)
+        return nil if body.nil? || body.empty?
+
+        parsed = JSON.parse(body)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError, EncodingError
+        nil
+      end
+
       def parse_remote_configuration(response)
         return nil unless @config.remote_configuration
 

data/lib/chronos/agent.rb

@@ -50,6 +50,24 @@ module Chronos
       @capture.call_sync(exception, context_for_capture(context))
     end
 
+    def verify_integration
+      @verification.call
+    rescue StandardError => error
+      @logger.warn("Chronos integration verification failed: #{error.class}")
+      Core::IntegrationVerificationResult.new(
+        :success => false,
+        :status => "verification_failed",
+        :credentials_valid => nil,
+        :event => {"id" => nil, "received" => false},
+        :receiver => {"name" => "chronos", "status" => "not_checked", "received_at" => nil},
+        :error => {
+          "code" => "verification_failed",
+          "message" => "Chronos integration verification failed locally.",
+          "guidance" => "Review the Chronos configuration and retry."
+        }
+      )
+    end
+
     def ignore_if(&block)
       @ignore_policy.add(&block)
     end
@@ -202,6 +220,9 @@ module Chronos
     def initialize_observability(options)
       @dependency_reporter = options[:dependency_reporter] || Application::DependencyReporter.new(@config)
       @deploy_normalizer = options[:deploy_normalizer] || Core::DeployNormalizer.new(@config)
+      @verification = options[:verification] || Application::VerifyIntegration.new(
+        @config, @delivery_pipeline, @logger
+      )
     end
 
     def build_context_store(strategy)

data/lib/chronos/application/delivery_pipeline.rb

@@ -42,13 +42,16 @@ module Chronos
       end
 
       def deliver_sync(event)
+        deliver_sync_result(event).success?
+      end
+
+      def deliver_sync_result(event)
         record_pre_delivery(event)
-        result = deliver_with_backlog(event)
-        result && result.success?
+        deliver_with_backlog(event)
       rescue StandardError => error
         diagnose(error)
         store_in_backlog(event)
-        false
+        Ports::TransportResult.new(:network_error, :error => error.class.name)
       end
 
       # WorkerPool delivery entry point. Events were counted when accepted into the queue.

data/lib/chronos/application/verify_integration.rb

@@ -0,0 +1,262 @@
+require "securerandom"
+
+module Chronos
+  module Application
+    # Sends and verifies one synthetic exception against the configured Chronos receiver.
+    #
+    # @responsibility Build an identified test notice, deliver it synchronously, and validate its acknowledgement.
+    # @motivation Verify credentials and end-to-end ingestion without mistaking an empty 2xx for confirmation.
+    # @limits It exposes only allowlisted project/receiver fields and never returns raw server responses.
+    # @collaborators NoticeBuilder, PayloadSerializer, DeliveryPipeline, and IntegrationVerificationResult.
+    # @thread_safety Calls allocate independent IDs and immutable results; collaborators synchronize delivery.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails.
+    # @example
+    #   result = verifier.call
+    #   result.success? #=> true or false
+    # @errors Network, protocol, configuration, and receiver failures become structured results.
+    # @performance Performs one bounded synchronous verification plus configured bounded retries.
+    class VerifyIntegration
+      SCHEMA_VERSION = "1.0".freeze
+      VERIFICATION_KIND = "integration_verification".freeze
+      VERIFICATION_TAG = "chronos-integration-verification".freeze
+
+      def initialize(config, delivery_pipeline, logger = nil, options = {})
+        @config = config
+        @delivery_pipeline = delivery_pipeline
+        @logger = logger || Internal::SafeLogger.new(config.logger)
+        @uuid_generator = options[:uuid_generator] || proc { SecureRandom.uuid }
+        @notice_builder = options[:notice_builder] || Core::NoticeBuilder.new(config)
+        @serializer = options[:serializer] || Core::PayloadSerializer.new(
+          config,
+          nil,
+          :max_payload_size => proc { @delivery_pipeline.max_payload_size }
+        )
+      end
+
+      def call
+        verification_id = bounded(@uuid_generator.call, 128)
+        return local_failure("configuration_invalid", verification_id, configuration_guidance) unless configured?
+
+        event = build_event(verification_id)
+        transport_result = @delivery_pipeline.deliver_sync_result(event)
+        classify(transport_result, verification_id, event.event_id)
+      rescue StandardError => error
+        @logger.warn("Chronos integration verification failed: #{error.class}")
+        local_failure("verification_failed", verification_id, "Review the Chronos configuration and retry.")
+      end
+
+      private
+
+      def configured?
+        !@config.project_id.to_s.empty? && !@config.project_key.to_s.empty? && !@config.host.to_s.empty?
+      end
+
+      def build_event(verification_id)
+        marker = {
+          "schema_version" => SCHEMA_VERSION,
+          "verification_id" => verification_id,
+          "kind" => VERIFICATION_KIND,
+          "test" => true
+        }
+        notice = @notice_builder.call(
+          IntegrationVerificationError.new("Chronos integration verification test"),
+          :severity => "info",
+          :context => {"integration_verification" => marker},
+          :tags => [VERIFICATION_TAG],
+          :fingerprint => VERIFICATION_TAG
+        )
+        @serializer.call(notice)
+      end
+
+      def classify(result, verification_id, event_id)
+        return classify_success(result.response, verification_id, event_id) if result.success?
+        if inactive_response?(result, verification_id, event_id)
+          return project_inactive(result.response, verification_id, event_id)
+        end
+        return invalid_credentials(verification_id, event_id) if [401, 403].include?(result.status_code)
+        return rate_limited(verification_id, event_id) if result.status == :rate_limited
+        return receiver_unavailable(verification_id, event_id) if unavailable?(result)
+        return receiver_internal_error(verification_id, event_id) if result.status == :server_error
+
+        request_rejected(verification_id, event_id)
+      end
+
+      def classify_success(response, verification_id, event_id)
+        unless valid_acknowledgement?(response, verification_id, event_id)
+          return failure("invalid_response", verification_id, event_id,
+                         :receiver_status => "reachable",
+                         :message => "Chronos returned a response outside the verification contract.",
+                         :guidance => "Update Chronos to the integration verification response v1 contract.")
+        end
+
+        Core::IntegrationVerificationResult.new(
+          :success => true,
+          :status => "verified",
+          :verification_id => verification_id,
+          :credentials_valid => true,
+          :event => {"id" => event_id, "received" => true},
+          :project => safe_project(response["project"]),
+          :receiver => safe_receiver(response["receiver"]),
+          :error => nil
+        )
+      end
+
+      def valid_acknowledgement?(response, verification_id, event_id)
+        valid_response_structure?(response) &&
+          acknowledgement_matches?(response, verification_id, event_id) &&
+          active_project?(response["project"]) && operational_receiver?(response["receiver"])
+      end
+
+      def valid_response_structure?(response)
+        exact_keys?(response, %w(
+                      schema_version success status verification_id credentials_valid event_received
+                      event project receiver error
+                    )) &&
+          exact_keys?(response["event"], %w(id)) &&
+          exact_keys?(response["project"], %w(id name status environment)) &&
+          exact_keys?(response["receiver"], %w(name status received_at))
+      end
+
+      def acknowledgement_matches?(response, verification_id, event_id)
+        response["schema_version"] == SCHEMA_VERSION && response["verification_id"] == verification_id &&
+          response["status"] == "accepted" && response["success"] == true &&
+          response["credentials_valid"] == true && response["event_received"] == true &&
+          hash_value(response["event"])["id"] == event_id && response["error"].nil?
+      end
+
+      def active_project?(project)
+        hash_value(project)["id"] == @config.project_id.to_s && hash_value(project)["status"] == "active"
+      end
+
+      def operational_receiver?(receiver)
+        hash_value(receiver)["status"] == "operational"
+      end
+
+      def inactive_response?(result, verification_id, event_id)
+        response = result.response
+        result.status_code == 403 && valid_response_structure?(response) &&
+          inactive_state?(response) && inactive_correlation?(response, verification_id, event_id)
+      end
+
+      def inactive_state?(response)
+        response["schema_version"] == SCHEMA_VERSION && response["success"] == false &&
+          response["status"] == "project_inactive" && response["credentials_valid"] == true &&
+          response["event_received"] == false && hash_value(response["project"])["status"] == "inactive" &&
+          valid_error?(response["error"])
+      end
+
+      def inactive_correlation?(response, verification_id, event_id)
+        response["verification_id"] == verification_id && hash_value(response["event"])["id"] == event_id &&
+          hash_value(response["project"])["id"] == @config.project_id.to_s
+      end
+
+      def valid_error?(error)
+        exact_keys?(error, %w(code message guidance)) && error["code"] == "project_inactive"
+      end
+
+      def project_inactive(response, verification_id, event_id)
+        failure("project_inactive", verification_id, event_id,
+                :credentials_valid => true, :receiver_status => "reachable",
+                :message => "The Chronos project is inactive and did not accept the verification event.",
+                :guidance => "Activate the project in Chronos or select an active project, then retry.",
+                :project => safe_project(response["project"]))
+      end
+
+      def invalid_credentials(verification_id, event_id)
+        failure("invalid_credentials", verification_id, event_id,
+                :credentials_valid => false, :receiver_status => "reachable",
+                :message => "Chronos rejected the project credentials.",
+                :guidance => "Create an active project API key, then confirm project_id and project_key.")
+      end
+
+      def rate_limited(verification_id, event_id)
+        failure("rate_limited", verification_id, event_id,
+                :receiver_status => "reachable",
+                :message => "Chronos temporarily rate limited the verification request.",
+                :guidance => "Wait before retrying and review the project ingestion limits.")
+      end
+
+      def receiver_internal_error(verification_id, event_id)
+        failure("receiver_internal_error", verification_id, event_id,
+                :receiver_status => "error",
+                :message => "Chronos encountered an internal error while processing the verification.",
+                :guidance => "Retry later or contact the Chronos operator with the verification_id.")
+      end
+
+      def receiver_unavailable(verification_id, event_id)
+        failure("receiver_unavailable", verification_id, event_id,
+                :receiver_status => "unavailable",
+                :message => "The Chronos receiver is unavailable or could not be reached.",
+                :guidance => "Check the host, DNS, TLS, network access, and Chronos service status.")
+      end
+
+      def request_rejected(verification_id, event_id)
+        failure("request_rejected", verification_id, event_id,
+                :receiver_status => "reachable",
+                :message => "Chronos rejected the integration verification request.",
+                :guidance => "Confirm that the gem and Chronos support the verification v1 contract.")
+      end
+
+      def unavailable?(result)
+        [:network_error, :request_timeout, :circuit_open].include?(result.status) ||
+          [502, 503, 504].include?(result.status_code)
+      end
+
+      def failure(status, verification_id, event_id, options = {})
+        Core::IntegrationVerificationResult.new(
+          :success => false,
+          :status => status,
+          :verification_id => verification_id,
+          :credentials_valid => options[:credentials_valid],
+          :event => {"id" => event_id, "received" => false},
+          :project => options[:project],
+          :receiver => {"name" => "chronos", "status" => options[:receiver_status], "received_at" => nil},
+          :error => {"code" => status, "message" => options[:message], "guidance" => options[:guidance]}
+        )
+      end
+
+      def local_failure(status, verification_id, guidance)
+        failure(status, verification_id, nil,
+                :receiver_status => "not_checked",
+                :message => "Chronos integration verification could not be started.",
+                :guidance => guidance)
+      end
+
+      def configuration_guidance
+        "Configure a non-empty project_id, project_key, and HTTPS host before running verification."
+      end
+
+      def safe_project(value)
+        safe_fields(value, "id" => 128, "name" => 128, "status" => 32, "environment" => 128)
+      end
+
+      def safe_receiver(value)
+        safe_fields(value, "name" => 64, "status" => 32, "received_at" => 64)
+      end
+
+      def safe_fields(value, fields)
+        source = hash_value(value)
+        fields.each_with_object({}) do |(name, limit), result|
+          result[name] = source[name].nil? ? nil : bounded(source[name], limit)
+        end
+      end
+
+      def hash_value(value)
+        value.is_a?(Hash) ? value : {}
+      end
+
+      def exact_keys?(value, keys)
+        value.is_a?(Hash) && value.keys.sort == keys.sort
+      end
+
+      def bounded(value, limit)
+        text = value.to_s.encode("UTF-8", :invalid => :replace, :undef => :replace, :replace => "?")
+        return text if text.bytesize <= limit
+
+        text.byteslice(0, limit).to_s.encode("UTF-8", :invalid => :replace, :undef => :replace, :replace => "?")
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end

data/lib/chronos/core/integration_verification_result.rb

@@ -0,0 +1,108 @@
+require "json"
+
+module Chronos
+  module Core
+    # Immutable result returned by an explicit Chronos integration verification.
+    #
+    # @responsibility Expose a bounded, JSON-safe verification outcome to Ruby and Rake callers.
+    # @motivation Report credential, receiver, and acknowledgement state without exposing raw responses.
+    # @limits It never includes project keys, response bodies, stack traces, or receiver internals.
+    # @collaborators VerifyIntegration and Chronos::RakeTasks.
+    # @thread_safety The object and all nested values are immutable after construction.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails.
+    # @example
+    #   result = Chronos.verify_integration
+    #   puts result.to_json
+    # @errors Invalid input is normalized to safe empty values.
+    # @performance Construction visits only the small allowlisted verification response.
+    class IntegrationVerificationResult
+      SCHEMA_VERSION = "1.0".freeze
+
+      attr_reader :status, :verification_id, :credentials_valid, :event,
+                  :project, :receiver, :error
+
+      def initialize(attributes = {})
+        @success = attributes[:success] == true
+        @status = safe_string(attributes[:status], 64)
+        @verification_id = optional_string(attributes[:verification_id], 128)
+        @credentials_valid = boolean_or_nil(attributes[:credentials_valid])
+        @event = immutable_copy(hash_value(attributes[:event]))
+        @project = optional_hash(attributes[:project])
+        @receiver = optional_hash(attributes[:receiver])
+        @error = optional_hash(attributes[:error])
+        freeze
+      end
+
+      def success?
+        @success
+      end
+
+      def to_h
+        {
+          "schema_version" => SCHEMA_VERSION,
+          "success" => success?,
+          "status" => status,
+          "verification_id" => verification_id,
+          "credentials_valid" => credentials_valid,
+          "event_received" => event["received"] == true,
+          "event" => event,
+          "project" => project,
+          "receiver" => receiver,
+          "error" => error
+        }
+      end
+
+      def to_json(*arguments)
+        JSON.generate(to_h, *arguments)
+      end
+
+      private
+
+      def optional_hash(value)
+        value.is_a?(Hash) ? immutable_copy(value) : nil
+      end
+
+      def hash_value(value)
+        value.is_a?(Hash) ? value : {}
+      end
+
+      def boolean_or_nil(value)
+        [true, false].include?(value) ? value : nil
+      end
+
+      def optional_string(value, limit)
+        return nil if value.nil?
+
+        safe_string(value, limit)
+      end
+
+      def safe_string(value, limit)
+        text = value.is_a?(String) || value.is_a?(Symbol) ? value.to_s : ""
+        text = text.encode("UTF-8", :invalid => :replace, :undef => :replace, :replace => "?")
+        return text if text.bytesize <= limit
+
+        text.byteslice(0, limit).to_s.encode("UTF-8", :invalid => :replace, :undef => :replace, :replace => "?")
+      rescue StandardError
+        ""
+      end
+
+      def immutable_copy(value)
+        copy = case value
+               when Hash
+                 value.each_with_object({}) do |(key, child), result|
+                   result[safe_string(key, 64)] = immutable_copy(child)
+                 end
+               when Array
+                 value.first(20).map { |child| immutable_copy(child) }
+               when String
+                 safe_string(value, 512)
+               when NilClass, TrueClass, FalseClass, Numeric
+                 value
+               else
+                 ""
+               end
+        copy.freeze
+      end
+    end
+  end
+end

data/lib/chronos/errors.rb

@@ -21,4 +21,15 @@ module Chronos
   # @example
   #   Chronos.configure { |config| config.project_key = nil }
   class ConfigurationError < Error; end
+
+  # Synthetic exception sent only by an explicit integration verification.
+  #
+  # @responsibility Give verification notices a stable, recognizable exception class.
+  # @motivation Let the Chronos receiver distinguish an integration check from an application failure.
+  # @limits It is never raised into the host application and carries no application data.
+  # @thread_safety A fresh instance is created for each verification.
+  # @compatibility Ruby 2.2.10 and newer legacy runtimes.
+  # @example
+  #   Chronos.verify_integration
+  class IntegrationVerificationError < Error; end
 end

data/lib/chronos/ports/transport.rb

@@ -8,7 +8,7 @@ module Chronos
     # @thread_safety Immutable after construction.
     # @compatibility Ruby 2.2.10 through Ruby 2.6.
     class TransportResult
-      attr_reader :status, :status_code, :retry_after, :error, :remote_configuration
+      attr_reader :status, :status_code, :retry_after, :error, :remote_configuration, :response
 
       def initialize(status, options = {})
         @status = status
@@ -16,6 +16,7 @@ module Chronos
         @retry_after = options[:retry_after]
         @error = options[:error]
         @remote_configuration = options[:remote_configuration]
+        @response = deep_freeze(options[:response])
         freeze
       end
 
@@ -26,6 +27,22 @@ module Chronos
       def retryable?
         [:request_timeout, :rate_limited, :server_error, :network_error].include?(status)
       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
+      rescue StandardError
+        nil
+      end
     end
 
     # Conceptual transport port implemented by delivery adapters.

data/lib/chronos/rails/railtie.rb

@@ -16,6 +16,11 @@ module Chronos
       initializer "chronos.install", :after => :load_config_initializers do |application|
         Chronos::Rails::Installer.new.install(application)
       end
+
+      rake_tasks do
+        require "chronos/rake_tasks"
+        Chronos::RakeTasks.install(:load_environment => true)
+      end
     end
   end
 end

data/lib/chronos/rake_tasks.rb

@@ -0,0 +1,41 @@
+require "json"
+require "rake"
+require "chronos"
+
+module Chronos
+  # Installs explicit Rake commands supplied by the Chronos gem.
+  #
+  # @responsibility Register the integration verification task with deterministic JSON output.
+  # @motivation Give Rails and plain Ruby operators one repeatable end-to-end credential check.
+  # @limits It never reads environment variables, prints credentials, or modifies application data.
+  # @collaborators Rake and Chronos.verify_integration.
+  # @thread_safety Installation checks the process-global Rake registry and is intended for boot time.
+  # @compatibility Rake versions compatible with Ruby 2.2.10 through Ruby 2.6.
+  # @example
+  #   require "chronos/rake_tasks"
+  #   Chronos::RakeTasks.install
+  # @errors Verification failures produce JSON and a nonzero process status.
+  # @performance The task performs one explicit synchronous verification when invoked.
+  module RakeTasks
+    extend ::Rake::DSL
+
+    TASK_NAME = "chronos:verify_integration".freeze
+
+    def self.install(options = {})
+      return false if ::Rake::Task.task_defined?(TASK_NAME)
+
+      output = options[:output] || $stdout
+      exiter = options[:exit] || proc { |status| exit(status) }
+      load_environment = options[:load_environment] || ::Rake::Task.task_defined?("environment")
+      prerequisites = load_environment ? ["environment"] : []
+
+      desc "Send an identified fake error and verify Chronos credentials and ingestion"
+      task TASK_NAME => prerequisites do
+        result = Chronos.verify_integration
+        output.puts(JSON.generate(result.to_h))
+        exiter.call(1) unless result.success?
+      end
+      true
+    end
+  end
+end

data/lib/chronos/version.rb

@@ -1,4 +1,4 @@
 module Chronos
   # Current version of the legacy Chronos Ruby agent.
-  VERSION = "0.9.0.pre.3".freeze
+  VERSION = "1.0.0".freeze
 end

data/lib/chronos.rb

@@ -7,6 +7,7 @@ require "chronos/ports"
 require "chronos/adapters"
 require "chronos/internal"
 require "chronos/core/notice"
+require "chronos/core/integration_verification_result"
 require "chronos/core/backtrace_parser"
 require "chronos/core/exception_cause_collector"
 require "chronos/core/runtime_info"
@@ -36,6 +37,7 @@ require "chronos/application/remote_configuration"
 require "chronos/application/ignore_policy"
 require "chronos/application/delivery_pipeline"
 require "chronos/application/capture_exception"
+require "chronos/application/verify_integration"
 require "chronos/application/apm_error_classifier"
 require "chronos/application/apm_aggregator"
 require "chronos/application/dependency_reporter"
@@ -95,6 +97,21 @@ module Chronos # rubocop:disable Metrics/ModuleLength
       false
     end
 
+    def verify_integration
+      agent = current_agent
+      return agent.verify_integration if agent
+
+      verification_failure(
+        "not_configured", "Chronos is not configured.",
+        "Run Chronos.configure before verifying the integration."
+      )
+    rescue StandardError
+      verification_failure(
+        "verification_failed", "Chronos integration verification failed locally.",
+        "Review the Chronos configuration and retry."
+      )
+    end
+
     def with_context(context = {})
       agent = current_agent
       return yield unless agent
@@ -186,6 +203,15 @@ module Chronos # rubocop:disable Metrics/ModuleLength
     def current_agent
       @mutex.synchronize { @agent }
     end
+
+    def verification_failure(status, message, guidance)
+      Core::IntegrationVerificationResult.new(
+        :success => false, :status => status, :credentials_valid => nil,
+        :event => {"id" => nil, "received" => false},
+        :receiver => {"name" => "chronos", "status" => "not_checked", "received_at" => nil},
+        :error => {"code" => status, "message" => message, "guidance" => guidance}
+      )
+    end
   end
 end