chronos-ruby 1.1.2 → 1.1.4

data/lib/chronos/deploy/configuration.rb

@@ -0,0 +1,96 @@
+require "yaml"
+require "uri"
+require "chronos/deploy/error"
+
+module Chronos
+  module Deploy
+    # @responsibility Validate and resolve public options, canonical ENV and legacy aliases.
+    # Resolves explicit CLI configuration without booting an application or agent.
+    class Configuration
+      FIELDS = %w(project_id project_key host environment service_name deploy_id revision version).freeze
+      ALIASES = {"environment" => "DEPLOY_ENVIRONMENT", "service_name" => "SERVICE_NAME",
+                 "deploy_id" => "DEPLOY_ID", "revision" => "GIT_SHA", "version" => "APP_VERSION"}.freeze
+      HOST_ERROR = "Host must be an absolute HTTPS URL without credentials, query or fragment.".freeze
+
+      def self.read(options, env)
+        root = File.realpath(File.expand_path(options[:root] || Dir.pwd))
+        public_values = read_public(root)
+        values = FIELDS.each_with_object({}) do |field, result|
+          result[field] = resolve(field, options, env, public_values)
+        end
+        values["host"] ||= "https://chronosmonitor.com.br"
+        validate_host!(values["host"])
+        values
+      rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES
+        raise Error, "Configuration root or file is unavailable; check --root and permissions."
+      end
+
+      def self.read_public(root)
+        path = File.join(root, "config/chronos-deploy.yml")
+        if File.symlink?(File.join(root, "config")) || File.symlink?(path)
+          raise Error, "Configuration path must not contain symlinks."
+        end
+        return {} unless File.exist?(path)
+        raise Error, "Public configuration must be a regular file." unless File.file?(path)
+        raise Error, "Public configuration exceeds 64 KiB." if File.size(path) > 65_536
+
+        parsed = YAML.safe_load(File.read(path))
+        values = parsed.nil? ? {} : parsed
+        raise ArgumentError unless values.is_a?(Hash) && (values.keys - (FIELDS - ["project_key"])).empty?
+
+        values.each_value { |value| validate_text!(value) }
+        values
+      end
+
+      def self.resolve(field, options, env, public_values)
+        prefix = %w(revision version).include?(field) ? "CHRONOS_DEPLOY_" : "CHRONOS_"
+        primary = env["#{prefix}#{field.upcase}"]
+        alternate = env[ALIASES[field]] if ALIASES[field]
+        if primary && alternate && primary != alternate
+          raise Error, "Conflicting canonical and alias environment variables; keep only one source."
+        end
+
+        value = options[field.to_sym] || primary || alternate || public_values[field]
+        validate_text!(value)
+        value
+      end
+
+      def self.validate_text!(value)
+        raise ArgumentError unless value.nil? || value.is_a?(String)
+        return if value.nil?
+        return if value.valid_encoding? && value.encoding.ascii_compatible? && !value.match(/[[:cntrl:]]/)
+
+        raise Error, "Configuration values must be text without control characters."
+      end
+
+      def self.validate_host!(host)
+        uri = URI.parse(host)
+        valid = uri.scheme == "https" && uri.host && !uri.userinfo && !uri.query && !uri.fragment
+        raise Error, HOST_ERROR unless valid
+      rescue URI::InvalidURIError
+        raise Error, HOST_ERROR
+      end
+
+      def self.validate!(values, command)
+        required = %w(project_id project_key environment)
+        required << "deploy_id" if command != "verify"
+        missing = required.select { |field| values[field].to_s.strip.empty? }
+        raise Error.new("Supply the required configuration fields.", :missing_fields => missing) unless missing.empty?
+
+        validate_release!(values) unless command == "verify"
+        %w(environment service_name deploy_id revision version).each do |field|
+          if values[field] && values[field].bytesize > 128
+            raise Error, "Deployment metadata exceeds the 128-byte protocol limit."
+          end
+        end
+        true
+      end
+
+      def self.validate_release!(values)
+        return unless values["revision"].to_s.strip.empty? && values["version"].to_s.strip.empty?
+
+        raise Error, "Supply the revision or version of the published artifact."
+      end
+    end
+  end
+end

data/lib/chronos/deploy/error.rb

@@ -0,0 +1,14 @@
+module Chronos
+  module Deploy
+    # @responsibility Carry static actionable errors and allowlisted diagnostics without raw input.
+    # Messages must be static: never interpolate input or exception messages.
+    class Error < StandardError
+      attr_reader :details
+
+      def initialize(message, details = {})
+        super(message)
+        @details = details
+      end
+    end
+  end
+end

data/lib/chronos/deploy/installer.rb

@@ -0,0 +1,65 @@
+require "chronos/deploy/error"
+require "chronos/deploy/providers"
+
+module Chronos
+  module Deploy
+    # @responsibility Generate provider fragments while preserving existing customer integrations.
+    # Explicit, idempotent generation of static fragments below a caller-selected root.
+    class Installer
+      PATHS = Providers::PATHS
+
+      def install(options)
+        raise Error, "Use --check without --force." if options[:force] && options[:check]
+
+        relative = PATHS[options[:provider]]
+        raise Error, "Choose a supported --provider; see chronos --help." unless relative
+
+        root = installation_root(options)
+        require "chronos/deploy/secure_directory"
+        SecureDirectory.with_root(root) do |directory|
+          install_into(directory, relative, options)
+        end
+      rescue Errno::EEXIST, Errno::EACCES, Errno::ENOTDIR, Errno::ELOOP
+        raise Error, "Integration destination is unavailable or changed; inspect it before retrying."
+      end
+
+      private
+
+      def install_into(directory, relative, options)
+        content = Providers.template(options[:provider])
+        existing = directory.with_parent(relative, false) { |parent, name| parent && parent.read(name) }
+        return "unchanged" if unchanged?(existing, relative, content, options)
+        raise Error, "Integration is missing; run install without --check." if options[:check]
+        return "would_write_#{relative}" if options[:dry_run]
+
+        directory.with_parent(relative, true) do |parent, name|
+          current = parent.read(name)
+          unless unchanged?(current, relative, content, options)
+            parent.write(name, content, options[:provider] == "kamal", options[:force])
+          end
+        end
+        "created_#{relative}; merge after successful publication; supply explicit published identity and revision"
+      end
+
+      def installation_root(options)
+        root = File.expand_path(options[:root] || Dir.pwd)
+        unless File.directory?(root) && !File.symlink?(root)
+          raise Error, "Installation root must be an existing directory, not a symlink."
+        end
+
+        root
+      end
+
+      def unchanged?(existing, relative, content, options)
+        return false if existing.nil?
+        return true if existing == content
+        return false if options[:force] && !options[:check]
+
+        proposed = content.lines.map { |line| "+#{line}" }.join
+        raise Error.new("Existing integration differs; merge the proposed template or explicitly use --force.",
+                        :path => relative,
+                        :diff => "--- existing (content withheld for privacy)\n+++ proposed\n#{proposed}")
+      end
+    end
+  end
+end

data/lib/chronos/deploy/providers.rb

@@ -0,0 +1,50 @@
+module Chronos
+  module Deploy
+    # Static integration fragments never interpolate customer input or credentials.
+    module Providers
+      PATHS = {
+        "kamal" => ".kamal/hooks/post-deploy",
+        "capistrano" => "lib/capistrano/tasks/chronos_deploy.rake",
+        "github-actions" => "config/chronos/deploy/github-actions.steps.yml",
+        "gitlab-ci" => "config/chronos/deploy/gitlab-ci.job.yml",
+        "jenkins" => "config/chronos/deploy/jenkins.post.groovy",
+        "azure-devops" => "config/chronos/deploy/azure-pipelines.steps.yml"
+      }.freeze
+      COMMAND = "bundle exec chronos deploy notify --on-error=warn".freeze
+      MARKER = "# Chronos deploy template v1; credentials from environment only.\n".freeze
+      INSTRUCTIONS = "# Supply CHRONOS_DEPLOY_ID and CHRONOS_DEPLOY_REVISION/VERSION " \
+                     "from the actual publication.\n".freeze
+      CAPISTRANO = <<-'RUBY'.freeze
+      # Do not also load chronos/capistrano. Runs locally once after publication.
+      namespace :chronos_cli do
+        task :notify do
+          if Rake::Task.task_defined?("chronos:notify_deploy")
+            raise "Remove the duplicate chronos/capistrano integration"
+          end
+          system("bundle", "exec", "chronos", "deploy", "notify", "--on-error=warn")
+        end
+      end
+      after "deploy:published", "chronos_cli:notify"
+      RUBY
+      BODIES = {
+        "kamal" => "exec #{COMMAND}\n",
+        "capistrano" => CAPISTRANO,
+        "github-actions" => "# Merge into the real job after successful publication.\n" \
+                            "- name: Notify Chronos\n  run: #{COMMAND}\n",
+        "gitlab-ci" => "# Merge script into the successful deployment job; preserve artifact outputs.\n" \
+                       ".chronos_deploy_notification:\n  script:\n    - #{COMMAND}\n",
+        "jenkins" => "// Merge into existing post { success { ... } }; export actual publication outputs.\n" \
+                     "sh '#{COMMAND}'\n",
+        "azure-devops" => "# Merge after successful publication in the same job.\n" \
+                          "- script: #{COMMAND}\n  displayName: Notify Chronos\n  condition: succeeded()\n"
+      }.freeze
+
+      def self.template(provider)
+        comments = MARKER + INSTRUCTIONS
+        comments = comments.gsub(/^#/, "//") if provider == "jenkins"
+        shebang = provider == "kamal" ? "#!/bin/sh\n" : ""
+        shebang + comments + BODIES.fetch(provider)
+      end
+    end
+  end
+end

data/lib/chronos/deploy/runner.rb

@@ -0,0 +1,44 @@
+require "logger"
+require "chronos"
+require "chronos/deploy/configuration"
+
+module Chronos
+  module Deploy
+    # @responsibility Execute the existing deploy or receipt API with bounded transport and guaranteed close.
+    # One explicit operation through the existing agent, always closed on exit.
+    class Runner
+      def call(command, values, timeout)
+        Configuration.validate!(values, command)
+        begin
+          configure(values, timeout, command)
+          outcome = if command == "verify"
+                      Chronos.verify_integration
+                    else
+                      Chronos.notify_deploy({:deploy_id => values["deploy_id"], :revision => values["revision"],
+                                             :version => values["version"]}, timeout)
+                    end
+        ensure
+          closed = Chronos.close(timeout)
+        end
+        command == "notify" ? outcome == true && closed != false : outcome
+      end
+
+      private
+
+      def configure(values, timeout, command)
+        Chronos.configure do |config|
+          values.each do |key, value|
+            attribute = key == "version" ? "app_version" : key
+            config.public_send("#{attribute}=", value) unless value.nil?
+          end
+          config.logger = Logger.new(File::NULL)
+          config.timeout = timeout
+          config.open_timeout = timeout
+          config.max_retries = 0
+          config.backlog_size = 0
+          config.dependency_reporting = false if command == "verify"
+        end
+      end
+    end
+  end
+end

data/lib/chronos/deploy/secure_directory.rb

@@ -0,0 +1,125 @@
+require "fiddle/import"
+require "securerandom"
+require "chronos/deploy/error"
+
+module Chronos
+  module Deploy
+    # @responsibility Anchor installer reads and writes to directory descriptors without following symlinks.
+    # POSIX openat/mkdirat/linkat/renameat prevent parent-path replacement from redirecting writes.
+    class SecureDirectory
+      # Fixed POSIX entry points; no shell, dynamic symbol names, or user-provided native code.
+      module Native
+        extend Fiddle::Importer
+        dlload Fiddle::Handle::DEFAULT
+        extern "int openat(int, const char*, int, unsigned int)"
+        extern "int mkdirat(int, const char*, unsigned int)"
+        extern "int linkat(int, const char*, int, const char*, int)"
+        extern "int renameat(int, const char*, int, const char*)"
+        extern "int unlinkat(int, const char*, int)"
+      end
+
+      def self.with_root(root)
+        raise Error, "Secure installation requires POSIX no-follow support." unless File.const_defined?(:NOFOLLOW)
+
+        handle = File.open(root, File::RDONLY | File::NOFOLLOW | File::NONBLOCK)
+        raise Error, "Installation root must be a directory." unless handle.stat.directory?
+
+        yield new(handle)
+      ensure
+        handle.close if handle && !handle.closed?
+      end
+
+      def with_parent(relative, create)
+        handles = []
+        current = self
+        parts = relative.split("/")
+        parts[0...-1].each do |part|
+          child = current.directory(part, create)
+          return yield(nil, parts.last) unless child
+
+          handles << child
+          current = self.class.new(child)
+        end
+        yield current, parts.last
+      ensure
+        handles.reverse_each(&:close)
+      end
+
+      def initialize(handle)
+        @handle = handle
+      end
+
+      def directory(name, create)
+        file = open_file(name, File::RDONLY | File::NONBLOCK)
+        if file.nil? && create
+          status = Native.mkdirat(@handle.fileno, name, 0o755)
+          check!(status) unless status.zero? || Fiddle.last_error == Errno::EEXIST::Errno
+          file = open_file(name, File::RDONLY | File::NONBLOCK)
+        end
+        return nil unless file
+        return file if file.stat.directory?
+
+        file.close
+        raise Error, "Installation parent must be a directory."
+      end
+
+      def read(name)
+        file = open_file(name, File::RDONLY | File::NONBLOCK)
+        return nil unless file
+
+        begin
+          raise Error, "Integration must be a regular file of at most 64 KiB." unless file.stat.file?
+
+          content = file.read(65_537) || ""
+          raise Error, "Integration must be a regular file of at most 64 KiB." if content.bytesize > 65_536
+
+          content
+        ensure
+          file.close
+        end
+      end
+
+      def write(name, content, executable, force)
+        temporary = ".chronos-deploy-#{SecureRandom.hex(16)}"
+        file = open_file(temporary, File::WRONLY | File::CREAT | File::EXCL, 0o600)
+        raise Error, "Installation directory is unavailable." unless file
+
+        begin
+          file.write(content)
+          file.chmod(executable ? 0o755 : 0o644)
+          file.close
+          if force
+            check!(Native.renameat(@handle.fileno, temporary, @handle.fileno, name))
+          else
+            check!(Native.linkat(@handle.fileno, temporary, @handle.fileno, name, 0))
+          end
+        ensure
+          file.close unless file.closed?
+          Native.unlinkat(@handle.fileno, temporary, 0)
+        end
+      end
+
+      private
+
+      def open_file(name, flags, mode = 0)
+        if name.empty? || name.include?("/") || name.include?("\0") || %w(. ..).include?(name)
+          raise Error, "Unsafe installation path component."
+        end
+
+        descriptor = Native.openat(@handle.fileno, name, flags | File::NOFOLLOW, mode)
+        return nil if descriptor < 0 && Fiddle.last_error == Errno::ENOENT::Errno
+
+        check!(descriptor)
+        file = File.for_fd(descriptor, (flags & File::WRONLY).zero? ? "r" : "w")
+        file.close_on_exec = true
+        file
+      end
+
+      def check!(status)
+        return status if status >= 0
+
+        raise Error, "Installation path changed, contains a symlink, or is unavailable; inspect it before retrying."
+      end
+    end
+  end
+end

data/lib/chronos/rails/active_record_query_inspector.rb

@@ -1,4 +1,5 @@
 require "json"
+require "chronos/core/sql_lexer"
 
 module Chronos
   module Rails
@@ -63,10 +64,7 @@ module Chronos
         return false unless connection
         return false unless (query["operation"] || query[:operation]).to_s == "SELECT"
         return false if table(query).empty?
-        return false unless raw_sql.to_s.lstrip =~ /\ASELECT\b/i
-
-        normalized = (query["normalized_query"] || query[:normalized_query]).to_s
-        normalized.sub(/;\s*\z/, "") !~ /;/
+        Core::SqlLexer.new(raw_sql, adapter_name(connection)).single_select?
       end
 
       def indexes(connection, table_name)

data/lib/chronos/rake_tasks.rb

@@ -7,7 +7,7 @@ module Chronos
   #
   # @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.
+  # @limits Deploy reads explicit CLI ENV; verification uses the configured agent. Neither prints credentials.
   # @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.
@@ -22,6 +22,7 @@ module Chronos
     TASK_NAME = "chronos:verify_integration".freeze
 
     def self.install(options = {})
+      install_deploy(options)
       return false if ::Rake::Task.task_defined?(TASK_NAME)
 
       output = options[:output] || $stdout
@@ -37,5 +38,16 @@ module Chronos
       end
       true
     end
+
+    def self.install_deploy(options)
+      return if ::Rake::Task.task_defined?("chronos:deploy")
+
+      task "chronos:deploy" do
+        require "chronos/cli"
+        status = Chronos::CLI.new(options[:output] || $stdout, options[:env] || ENV).run(["deploy", "notify"])
+        (options[:exit] || proc { |code| exit(code) }).call(status) unless status.zero?
+      end
+    end
+    private_class_method :install_deploy
   end
 end

data/lib/chronos/version.rb

@@ -1,4 +1,4 @@
 module Chronos
   # Current version of the legacy Chronos Ruby agent.
-  VERSION = "1.1.2".freeze
+  VERSION = "1.1.4".freeze
 end

data/lib/generators/chronos/deploy/install/install_generator.rb

@@ -0,0 +1,26 @@
+require "rails/generators"
+require "chronos/deploy/installer"
+
+module Chronos
+  module Generators
+    module Deploy
+      # @responsibility Delegate explicit Rails generation to the shared deploy installer.
+      # Rails adapter for the same explicit installer used by the CLI.
+      class InstallGenerator < ::Rails::Generators::Base
+        namespace "chronos:deploy:install"
+        class_option :provider, :type => :string, :required => true
+        class_option :dry_run, :type => :boolean, :default => false
+        class_option :check, :type => :boolean, :default => false
+        class_option :force, :type => :boolean, :default => false
+
+        def install_deploy
+          result = Chronos::Deploy::Installer.new.install(
+            :root => destination_root, :provider => options[:provider],
+            :dry_run => options[:dry_run], :check => options[:check], :force => options[:force]
+          )
+          say result
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chronos-ruby
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.4
 platform: ruby
 authors:
 - Antonio Jefferson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
+date: 2026-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -44,6 +44,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 12.3.3
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 5.10.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 5.10.3
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -86,11 +100,15 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 1.19.2
-description: Base do cliente Chronos para excecoes, telemetria e observabilidade em
-  aplicacoes Ruby legadas.
+description: Cliente oficial do Chronos para capturar e enviar exceções, métricas
+  e dados de telemetria de aplicações Ruby e Rails. A gem centraliza sinais de observabilidade
+  para facilitar o monitoramento, a análise de desempenho e o diagnóstico de falhas
+  no Chronos Monitor. Conheça a plataforma oficial de recebimento e visualização dos
+  dados em https://chronosmonitor.com.br.
 email:
 - antoniojeferson96@gmail.com
-executables: []
+executables:
+- chronos
 extensions: []
 extra_rdoc_files: []
 files:
@@ -126,12 +144,15 @@ files:
 - docs/adr/ADR-017-deploy-events-and-correlation.md
 - docs/adr/ADR-018-pre-1.0-hardening.md
 - docs/adr/ADR-019-bounded-query-diagnostics.md
+- docs/adr/legacy-deploy-cli.md
 - docs/architecture.md
 - docs/compatibility.md
 - docs/configuration.md
 - docs/data-collected.md
+- docs/deploy-cli.md
 - docs/deprecation-policy.md
 - docs/examples/plain-ruby.md
+- docs/legacy-test-environment.md
 - docs/migration-from-airbrake.md
 - docs/modules/active-job.md
 - docs/modules/apm-aggregation.md
@@ -167,9 +188,12 @@ files:
 - docs/release-1.0-readiness.md
 - docs/release-1.1-readiness.md
 - docs/release-1.1.2-readiness.md
+- docs/release-1.1.3-readiness.md
+- docs/release-1.1.4-readiness.md
 - docs/security-review.md
 - docs/semver.md
 - docs/troubleshooting.md
+- exe/chronos
 - lib/chronos.rb
 - lib/chronos/adapters.rb
 - lib/chronos/adapters/net_http_transport.rb
@@ -188,12 +212,14 @@ files:
 - lib/chronos/application/retry_policy.rb
 - lib/chronos/application/verify_integration.rb
 - lib/chronos/capistrano.rb
+- lib/chronos/cli.rb
 - lib/chronos/configuration.rb
 - lib/chronos/configuration/apm_validation.rb
 - lib/chronos/configuration/snapshot.rb
 - lib/chronos/configuration/validation.rb
 - lib/chronos/core.rb
 - lib/chronos/core/backtrace_parser.rb
+- lib/chronos/core/bounded_copy.rb
 - lib/chronos/core/breadcrumb.rb
 - lib/chronos/core/cache_normalizer.rb
 - lib/chronos/core/correlation_context.rb
@@ -208,9 +234,16 @@ files:
 - lib/chronos/core/safe_serializer.rb
 - lib/chronos/core/sanitizer.rb
 - lib/chronos/core/sensitive_value_filter.rb
+- lib/chronos/core/sql_lexer.rb
 - lib/chronos/core/sql_normalizer.rb
 - lib/chronos/core/sql_query_analyzer.rb
 - lib/chronos/core/telemetry_event.rb
+- lib/chronos/deploy/configuration.rb
+- lib/chronos/deploy/error.rb
+- lib/chronos/deploy/installer.rb
+- lib/chronos/deploy/providers.rb
+- lib/chronos/deploy/runner.rb
+- lib/chronos/deploy/secure_directory.rb
 - lib/chronos/errors.rb
 - lib/chronos/integrations.rb
 - lib/chronos/integrations/active_job.rb
@@ -241,6 +274,7 @@ files:
 - lib/chronos/ruby/version.rb
 - lib/chronos/sidekiq.rb
 - lib/chronos/version.rb
+- lib/generators/chronos/deploy/install/install_generator.rb
 - lib/generators/chronos/install/install_generator.rb
 - lib/generators/chronos/install/templates/chronos.rb
 homepage: https://github.com/antoniojefferson/chronos-ruby
@@ -272,5 +306,5 @@ requirements: []
 rubygems_version: 3.4.22
 signing_key:
 specification_version: 4
-summary: Cliente Ruby para captura de eventos do Chronos
+summary: Monitoramento de exceções, métricas e telemetria para Ruby e Rails
 test_files: []