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

data/lib/chronos/integrations/job_payload.rb

@@ -0,0 +1,72 @@
+module Chronos
+  module Integrations
+    # Builds bounded job metadata before the shared privacy serializer runs.
+    #
+    # @responsibility Limit job arguments, tags, strings, containers, and nesting.
+    # @motivation Worker payloads are application-controlled and may be very large.
+    # @limits It limits values but deliberately leaves redaction to Core::Sanitizer.
+    # @collaborators Sidekiq middleware and the Chronos telemetry pipeline.
+    # @thread_safety Instances keep no mutable state and may be shared.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   JobPayload.new.arguments(["account-1"])
+    # @errors Unreadable values become bounded class-name placeholders.
+    # @performance Traversal is capped by argument, collection, depth, and string limits.
+    class JobPayload
+      MAX_ARGUMENTS = 20
+      MAX_COLLECTION_ITEMS = 20
+      MAX_DEPTH = 4
+      MAX_STRING_BYTES = 512
+
+      def arguments(values)
+        source = values.is_a?(Array) ? values : []
+        [source.first(MAX_ARGUMENTS).map { |value| limit(value, 0) }, source.length > MAX_ARGUMENTS]
+      rescue StandardError
+        [[], true]
+      end
+
+      def tags(values)
+        Array(values).first(MAX_COLLECTION_ITEMS).map { |value| limit_string(value.to_s) }
+      rescue StandardError
+        []
+      end
+
+      private
+
+      def limit(value, depth)
+        return "[TRUNCATED]" if depth >= MAX_DEPTH
+
+        case value
+        when Hash
+          limit_hash(value, depth)
+        when Array
+          value.first(MAX_COLLECTION_ITEMS).map { |child| limit(child, depth + 1) }
+        when String
+          limit_string(value)
+        when NilClass, TrueClass, FalseClass, Numeric
+          value
+        else
+          limit_string(value.to_s)
+        end
+      rescue StandardError
+        "[UNREADABLE]"
+      end
+
+      def limit_hash(value, depth)
+        result = {}
+        value.to_a.first(MAX_COLLECTION_ITEMS).each do |key, child|
+          result[limit_string(key.to_s)] = limit(child, depth + 1)
+        end
+        result
+      end
+
+      def limit_string(value)
+        return value if value.bytesize <= MAX_STRING_BYTES
+
+        value.byteslice(0, MAX_STRING_BYTES) + "[TRUNCATED]"
+      rescue StandardError
+        "[UNREADABLE]"
+      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/sidekiq.rb

@@ -0,0 +1,258 @@
+require "securerandom"
+require "chronos/integrations/job_payload"
+
+module Chronos
+  module Integrations
+    # Optional Sidekiq 4/5 middleware integration for the legacy Chronos line.
+    #
+    # @responsibility Install client/server middleware and namespace worker telemetry.
+    # @motivation Sidekiq jobs need process-boundary context and failure capture.
+    # @limits It does not own Sidekiq lifecycle, Redis connections, retries, or threads.
+    # @collaborators Sidekiq public middleware configuration and Chronos facade.
+    # @thread_safety Installation is mutex-protected; middleware instances are stateless.
+    # @compatibility Sidekiq 4.x and 5.x; Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   Chronos::Integrations::Sidekiq.install
+    # @errors Missing Sidekiq or configuration failures return false.
+    # @performance Adds bounded payload normalization and two clock reads per performed job.
+    module Sidekiq
+      CONTEXT_KEY = "chronos".freeze
+      CONTEXT_SCHEMA_VERSION = "1.0".freeze
+
+      @mutex = Mutex.new
+      @installed = false
+
+      class << self
+        def install(sidekiq = nil, notifier = Chronos)
+          library = sidekiq || (::Sidekiq if defined?(::Sidekiq))
+          return false unless library
+
+          @mutex.synchronize do
+            return false if @installed
+
+            configure_client(library, notifier)
+            configure_server(library, notifier)
+            @installed = true
+          end
+          true
+        rescue StandardError
+          false
+        end
+
+        private
+
+        def configure_client(library, notifier)
+          return unless library.respond_to?(:configure_client)
+
+          library.configure_client do |config|
+            next unless config.respond_to?(:client_middleware)
+
+            config.client_middleware { |chain| chain.add(ClientMiddleware, :notifier => notifier) }
+          end
+        end
+
+        def configure_server(library, notifier)
+          return unless library.respond_to?(:configure_server)
+
+          library.configure_server do |config|
+            if config.respond_to?(:client_middleware)
+              config.client_middleware { |chain| chain.add(ClientMiddleware, :notifier => notifier) }
+            end
+            if config.respond_to?(:server_middleware)
+              config.server_middleware { |chain| chain.add(ServerMiddleware, :notifier => notifier) }
+            end
+          end
+        end
+      end
+
+      # Adds a small allowlisted Chronos context to the Sidekiq job envelope.
+      #
+      # @responsibility Propagate trace/request identifiers without modifying `args`.
+      # @motivation Client and server usually execute in different processes.
+      # @limits It does not capture arguments, enqueue errors, or application context fields.
+      # @collaborators Chronos propagation context and Sidekiq client middleware chain.
+      # @thread_safety Calls allocate their own hashes and may execute concurrently.
+      # @compatibility Sidekiq 4.x/5.x client middleware signature.
+      # @example
+      #   ClientMiddleware.new.call(MyWorker, job, "default") { push(job) }
+      # @errors Context failures are contained and the enqueue chain still runs.
+      # @performance Adds one bounded hash to the job payload; opens no connection or thread.
+      class ClientMiddleware
+        def initialize(options = {})
+          @notifier = options[:notifier] || Chronos
+          @clock = options[:clock] || proc { Time.now.to_f }
+        end
+
+        def call(_worker_class, job, _queue, _redis_pool = nil)
+          add_context(job)
+          yield
+        end
+
+        private
+
+        def add_context(job)
+          return unless job.is_a?(Hash)
+
+          context = propagation_context
+          context["trace_id"] = SecureRandom.uuid if context["trace_id"].to_s.empty?
+          job[CONTEXT_KEY] = {
+            "schema_version" => CONTEXT_SCHEMA_VERSION,
+            "enqueued_at" => @clock.call.to_f,
+            "context" => context
+          }
+        rescue StandardError
+          nil
+        end
+
+        def propagation_context
+          return {} unless @notifier.respond_to?(:propagation_context)
+
+          source = @notifier.propagation_context
+          return {} unless source.is_a?(Hash)
+
+          %w(trace_id request_id).each_with_object({}) do |key, result|
+            value = source[key] || source[key.to_sym]
+            result[key] = value.to_s unless value.to_s.empty?
+          end
+        end
+      end
+
+      # Captures Sidekiq execution timing and failures around the worker call.
+      #
+      # @responsibility Scope propagated context, emit one job event, notify failures once, and re-raise.
+      # @motivation Worker failures otherwise lose queue metadata and request correlation.
+      # @limits It does not change retry behavior, acknowledge jobs, or install global error handlers.
+      # @collaborators Chronos facade, JobPayload, and Sidekiq server middleware chain.
+      # @thread_safety Shared instances keep only immutable collaborators.
+      # @compatibility Sidekiq 4.x/5.x server middleware signature.
+      # @example
+      #   ServerMiddleware.new.call(worker, job, "default") { worker.perform }
+      # @errors The original worker exception is always re-raised after contained notification.
+      # @performance No per-job thread or connection; normalization has strict collection limits.
+      class ServerMiddleware
+        def initialize(options = {})
+          @notifier = options[:notifier] || Chronos
+          @clock = options[:clock] || proc { monotonic_time }
+          @wall_clock = options[:wall_clock] || proc { Time.now.to_f }
+          @limiter = options[:limiter] || JobPayload.new
+        end
+
+        def call(worker, job, queue)
+          started_at = @clock.call
+          payload = base_payload(worker, job, queue)
+          context = execution_context(job, payload)
+          @notifier.with_context(context) do
+            begin
+              result = yield
+              finish(payload, started_at, "completed")
+              result
+            rescue Exception => error # rubocop:disable Lint/RescueException
+              finish(payload, started_at, "failed", error)
+              notify_failure(error, payload)
+              raise
+            end
+          end
+        end
+
+        private
+
+        def base_payload(worker, job, queue)
+          source = job.is_a?(Hash) ? job : {}
+          arguments, truncated = @limiter.arguments(source["args"] || source[:args])
+          payload = {
+            "kind" => "sidekiq", "class" => worker_class(worker, source),
+            "queue" => (source["queue"] || source[:queue] || queue).to_s,
+            "jid" => (source["jid"] || source[:jid]).to_s,
+            "retry_count" => retry_count(source), "arguments" => arguments,
+            "arguments_truncated" => truncated, "tags" => tags(worker, source),
+            "queue_latency_ms" => queue_latency(source)
+          }
+          payload
+        end
+
+        def execution_context(job, payload)
+          metadata = job.is_a?(Hash) ? (job[CONTEXT_KEY] || job[CONTEXT_KEY.to_sym]) : nil
+          propagated = metadata.is_a?(Hash) ? (metadata["context"] || metadata[:context]) : nil
+          propagated = {} unless propagated.is_a?(Hash)
+          {
+            :context => propagated.merge("job" => job_context(payload)),
+            :__chronos_captured_exceptions => {}
+          }
+        end
+
+        def finish(payload, started_at, status, error = nil)
+          payload["duration_ms"] = [elapsed_ms(started_at), 0.0].max
+          payload["status"] = status
+          payload["error_class"] = error.class.name.to_s if error
+          @notifier.record_event("job", payload)
+        rescue StandardError
+          false
+        end
+
+        def notify_failure(error, payload)
+          context = {:context => {"job" => job_context(payload)},
+                     :parameters => {"arguments" => payload["arguments"]}, :tags => payload["tags"]}
+          if @notifier.respond_to?(:notify_once)
+            @notifier.notify_once(error, context)
+          else
+            @notifier.notify(error, context)
+          end
+        rescue StandardError
+          false
+        end
+
+        def job_context(payload)
+          %w(kind class queue jid retry_count queue_latency_ms duration_ms status).each_with_object({}) do |key, result|
+            result[key] = payload[key] unless payload[key].nil?
+          end
+        end
+
+        def worker_class(worker, job)
+          explicit = job["wrapped"] || job[:wrapped] || job["class"] || job[:class]
+          explicit = worker.class.name if explicit.to_s.empty? && worker
+          explicit.to_s
+        rescue StandardError
+          ""
+        end
+
+        def retry_count(job)
+          value = job["retry_count"] || job[:retry_count]
+          value.to_i < 0 ? 0 : value.to_i
+        end
+
+        def tags(worker, job)
+          values = job["tags"] || job[:tags]
+          if values.nil? && worker
+            owner = worker.is_a?(Class) ? worker : worker.class
+            options = owner.get_sidekiq_options if owner.respond_to?(:get_sidekiq_options)
+            values = options["tags"] || options[:tags] if options.is_a?(Hash)
+          end
+          @limiter.tags(values)
+        rescue StandardError
+          []
+        end
+
+        def queue_latency(job)
+          metadata = job[CONTEXT_KEY] || job[CONTEXT_KEY.to_sym]
+          enqueued_at = job["enqueued_at"] || job[:enqueued_at]
+          enqueued_at ||= metadata["enqueued_at"] || metadata[:enqueued_at] if metadata.is_a?(Hash)
+          return nil unless enqueued_at
+
+          [((@wall_clock.call.to_f - enqueued_at.to_f) * 1000.0).round(3), 0.0].max
+        rescue StandardError
+          nil
+        end
+
+        def elapsed_ms(started_at)
+          ((@clock.call - started_at) * 1000.0).round(3)
+        end
+
+        def monotonic_time
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        rescue StandardError
+          Time.now.to_f
+        end
+      end
+    end
+  end
+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/internal/worker_pool.rb

@@ -24,6 +24,7 @@ module Chronos
         @mutex = Mutex.new
         @threads = []
         @active = 0
+        @pending = 0
         @closed = false
         @pid = Process.pid
       end
@@ -32,7 +33,9 @@ module Chronos
         prepare_after_fork
         return false if closed?
 
+        increment_pending
         accepted = @queue.push(event)
+        decrement_pending unless accepted
         ensure_started if accepted
         accepted
       end
@@ -42,7 +45,7 @@ module Chronos
         ensure_started unless @queue.empty?
         deadline = monotonic_time + timeout.to_f
         loop do
-          return true if @queue.empty? && active_count.zero?
+          return true if delivery_complete?
           return false if monotonic_time >= deadline
           sleep(POLL_INTERVAL)
         end
@@ -91,6 +94,7 @@ module Chronos
             @logger.warn("Chronos worker contained #{error.class}")
           ensure
             decrement_active
+            decrement_pending
           end
         end
       rescue StandardError => error
@@ -104,13 +108,14 @@ module Chronos
           @pid = Process.pid
           @threads = []
           @active = 0
+          @pending = @queue.size
         end
       end
 
       def flush_without_reopening(timeout)
         deadline = monotonic_time + timeout.to_f
         loop do
-          return true if @queue.empty? && active_count.zero?
+          return true if delivery_complete?
           return false if monotonic_time >= deadline
           sleep(POLL_INTERVAL)
         end
@@ -138,6 +143,18 @@ module Chronos
         @mutex.synchronize { @active }
       end
 
+      def increment_pending
+        @mutex.synchronize { @pending += 1 }
+      end
+
+      def decrement_pending
+        @mutex.synchronize { @pending -= 1 }
+      end
+
+      def delivery_complete?
+        @mutex.synchronize { @pending.zero? && @active.zero? }
+      end
+
       def closed?
         @mutex.synchronize { @closed }
       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

data/lib/chronos/rails/notifications_subscriber.rb

@@ -0,0 +1,203 @@
+module Chronos
+  module Rails
+    # Converts public ActiveSupport notifications into bounded Chronos telemetry.
+    #
+    # @responsibility Subscribe once and normalize controller, view, SQL, mailer, job, and cache events.
+    # @motivation Support Rails 4.2 and 5.2 through feature detection and public notification APIs.
+    # @limits It never sends SQL text, bind values, cache keys, mail bodies, or job arguments.
+    # @collaborators ActiveSupport::Notifications and the Chronos facade.
+    # @thread_safety Subscription registry is mutex-protected; callbacks own their state.
+    # @compatibility ActiveSupport notification argument shapes from Rails 4.2 through 5.2.
+    # @example
+    #   Chronos::Rails::NotificationsSubscriber.new.install
+    # @errors Subscriber failures are contained and never escape into Rails.
+    # @performance Each notification builds a small allowlisted hash and queues asynchronously.
+    class NotificationsSubscriber
+      EVENTS = %w(
+        process_action.action_controller render_template.action_view sql.active_record
+        deliver.action_mailer perform.active_job cache_read.active_support
+        cache_write.active_support cache_fetch_hit.active_support
+      ).freeze
+
+      @mutex = Mutex.new
+      @installed_buses = {}
+
+      class << self
+        attr_reader :mutex, :installed_buses
+      end
+
+      def initialize(notifier = Chronos, notifications = nil)
+        @notifier = notifier
+        @notifications = notifications || active_support_notifications
+      end
+
+      def install
+        return false unless @notifications && @notifications.respond_to?(:subscribe)
+
+        self.class.mutex.synchronize do
+          return false if self.class.installed_buses[@notifications.object_id]
+
+          event_names.each { |name| subscribe(name) }
+          self.class.installed_buses[@notifications.object_id] = true
+        end
+        true
+      rescue StandardError
+        false
+      end
+
+      def handle(name, arguments)
+        event = notification_event(name, arguments)
+        dispatch(name, event[:payload], event[:duration_ms])
+      rescue StandardError
+        false
+      end
+
+      private
+
+      def active_support_notifications
+        return nil unless defined?(::ActiveSupport::Notifications)
+
+        ::ActiveSupport::Notifications
+      end
+
+      def subscribe(name)
+        @notifications.subscribe(name) { |*arguments| handle(name, arguments) }
+      end
+
+      def event_names
+        return EVENTS if defined?(::ActiveJob)
+
+        EVENTS.reject { |name| name == "perform.active_job" }
+      end
+
+      def notification_event(name, arguments)
+        candidate = arguments.first
+        if arguments.length == 1 && candidate.respond_to?(:payload)
+          return {:payload => hash(candidate.payload), :duration_ms => candidate.duration.to_f}
+        end
+
+        started_at = arguments[1]
+        finished_at = arguments[2]
+        {
+          :payload => hash(arguments[4]),
+          :duration_ms => duration_ms(started_at, finished_at),
+          :name => name
+        }
+      end
+
+      def dispatch(name, payload, duration)
+        case name
+        when "process_action.action_controller" then process_action(payload, duration)
+        when "render_template.action_view" then render_template(payload, duration)
+        when "sql.active_record" then sql(payload, duration)
+        when "deliver.action_mailer" then mailer(payload, duration)
+        when "perform.active_job" then active_job(payload, duration)
+        else cache(name, payload, duration)
+        end
+      end
+
+      def process_action(payload, duration)
+        capture_controller_exception(payload)
+        data = {
+          "kind" => "controller", "controller" => value(payload, :controller),
+          "action" => value(payload, :action), "status" => value(payload, :status).to_i,
+          "method" => value(payload, :method), "path" => query_free_path(value(payload, :path)),
+          "route" => route(payload),
+          "duration_ms" => duration, "parameters" => hash(value(payload, :params))
+        }
+        @notifier.record_event("request", data)
+      end
+
+      def render_template(payload, duration)
+        data = {
+          "kind" => "view", "template" => safe_basename(value(payload, :identifier)),
+          "duration_ms" => duration
+        }
+        @notifier.record_event("request", data)
+      end
+
+      def sql(payload, duration)
+        data = {
+          "name" => value(payload, :name).to_s, "cached" => value(payload, :cached) == true,
+          "duration_ms" => duration
+        }
+        @notifier.record_event("query", data)
+      end
+
+      def mailer(payload, duration)
+        data = {
+          "kind" => "mailer", "mailer" => value(payload, :mailer).to_s,
+          "action" => value(payload, :action).to_s, "duration_ms" => duration
+        }
+        @notifier.record_event("job", data)
+      end
+
+      def active_job(payload, duration)
+        job = value(payload, :job)
+        data = {
+          "kind" => "active_job", "class" => safe_class_name(job),
+          "queue" => safe_job_value(job, :queue_name), "duration_ms" => duration
+        }
+        @notifier.record_event("job", data)
+      end
+
+      def cache(name, payload, duration)
+        data = {
+          "operation" => name.split(".").first, "store" => value(payload, :store).to_s,
+          "hit" => value(payload, :hit), "duration_ms" => duration
+        }
+        @notifier.record_event("cache", data)
+      end
+
+      def capture_controller_exception(payload)
+        exception = value(payload, :exception_object)
+        details = value(payload, :exception)
+        exception ||= RuntimeError.new(Array(details).last.to_s) if details
+        @notifier.notify_once(exception, :parameters => hash(value(payload, :params))) if exception
+      end
+
+      def value(payload, key)
+        payload.key?(key) ? payload[key] : payload[key.to_s]
+      end
+
+      def hash(value)
+        value.is_a?(Hash) ? value : {}
+      end
+
+      def duration_ms(started_at, finished_at)
+        return 0.0 unless started_at && finished_at
+
+        ((finished_at.to_f - started_at.to_f) * 1000.0).round(3)
+      end
+
+      def query_free_path(path)
+        path.to_s.split("?", 2).first
+      end
+
+      def route(payload)
+        explicit = value(payload, :route)
+        return explicit.to_s unless explicit.to_s.empty?
+
+        [value(payload, :controller), value(payload, :action)].compact.join("#")
+      end
+
+      def safe_basename(identifier)
+        File.basename(identifier.to_s)
+      rescue StandardError
+        "<template>"
+      end
+
+      def safe_class_name(object)
+        object ? object.class.name.to_s : ""
+      rescue StandardError
+        "Object"
+      end
+
+      def safe_job_value(job, method_name)
+        job.respond_to?(method_name) ? job.public_send(method_name).to_s : ""
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end