chronos-ruby 0.1.0.pre.2

data/lib/chronos/core/backtrace_parser.rb

@@ -0,0 +1,74 @@
+module Chronos
+  module Core
+    # Parses CRuby and common JRuby backtrace lines without rejecting unknown input.
+    #
+    # @responsibility Convert backtrace strings into bounded structured frames.
+    # @motivation Give the SaaS stable fields for display and grouping.
+    # @limits It does not read source files or collect code hunks.
+    # @collaborators NoticeBuilder.
+    # @thread_safety Stateless and safe to reuse between threads.
+    # @compatibility CRuby 2.2.10 through 2.6 and common JRuby line formats.
+    # @example
+    #   parser.call(["app/job.rb:12:in `call'"])
+    # @performance Linear in the number of frames, capped by max_frames.
+    class BacktraceParser
+      DEFAULT_MAX_FRAMES = 200
+
+      def initialize(root_directory, max_frames = DEFAULT_MAX_FRAMES)
+        @root_directory = expand_root(root_directory)
+        @max_frames = max_frames
+      end
+
+      def call(lines)
+        Array(lines).first(@max_frames).map { |line| parse(line) }
+      end
+
+      private
+
+      def parse(line)
+        text = safe_string(line)
+        match = text.match(/\A(.+?):(\d+)(?::in [`'](.*)['`])?\z/)
+        return unknown_frame(text) unless match
+
+        file = normalize_file(match[1])
+        {
+          "file" => file,
+          "line" => match[2].to_i,
+          "function" => match[3],
+          "in_app" => in_app?(file)
+        }
+      rescue StandardError
+        unknown_frame(safe_string(line))
+      end
+
+      def unknown_frame(line)
+        {"file" => line, "line" => nil, "function" => nil, "in_app" => false}
+      end
+
+      def normalize_file(file)
+        return file unless @root_directory && file.start_with?(@root_directory + File::SEPARATOR)
+
+        file[(@root_directory.length + 1)..-1]
+      end
+
+      def in_app?(file)
+        return false unless @root_directory
+        return true unless file.start_with?(File::SEPARATOR)
+
+        file.start_with?(@root_directory + File::SEPARATOR)
+      end
+
+      def expand_root(root)
+        root && File.expand_path(root.to_s)
+      rescue StandardError
+        nil
+      end
+
+      def safe_string(value)
+        value.to_s
+      rescue StandardError
+        "<unreadable backtrace>"
+      end
+    end
+  end
+end

data/lib/chronos/core/exception_cause_collector.rb

@@ -0,0 +1,63 @@
+module Chronos
+  module Core
+    # Collects a bounded exception cause chain with cycle protection.
+    #
+    # @responsibility Normalize nested Exception#cause values.
+    # @motivation Preserve root-cause information without unbounded traversal.
+    # @limits It records class and message only; each cause backtrace is handled elsewhere.
+    # @collaborators NoticeBuilder.
+    # @thread_safety Uses only call-local state.
+    # @compatibility Feature-detects Exception#cause for legacy runtimes.
+    # @example
+    #   collector.call(exception)
+    # @performance Constant memory bounded by max_depth.
+    class ExceptionCauseCollector
+      DEFAULT_MAX_DEPTH = 10
+
+      def initialize(max_depth = DEFAULT_MAX_DEPTH)
+        @max_depth = max_depth
+      end
+
+      def call(exception)
+        causes = []
+        seen = {}
+        current = exception
+
+        @max_depth.times do
+          break unless current.respond_to?(:cause)
+          current = safe_cause(current)
+          break unless current
+          break if seen[current.object_id]
+
+          seen[current.object_id] = true
+          causes << {
+            "class" => safe_class_name(current),
+            "message" => safe_message(current)
+          }
+        end
+
+        causes
+      end
+
+      private
+
+      def safe_cause(exception)
+        exception.cause
+      rescue StandardError
+        nil
+      end
+
+      def safe_class_name(exception)
+        exception.class.name.to_s
+      rescue StandardError
+        "Exception"
+      end
+
+      def safe_message(exception)
+        exception.message.to_s
+      rescue StandardError
+        "<unreadable exception message>"
+      end
+    end
+  end
+end

data/lib/chronos/core/notice.rb

@@ -0,0 +1,53 @@
+module Chronos
+  module Core
+    # Immutable value object containing a normalized Ruby exception.
+    #
+    # @responsibility Carry exception and diagnostic context through the pipeline.
+    # @motivation Keep transport details separate from exception normalization.
+    # @limits It does not sanitize, serialize, enqueue, or send itself.
+    # @collaborators NoticeBuilder and PayloadSerializer.
+    # @thread_safety Immutable after construction and safe to share.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails.
+    # @example
+    #   notice.exception_class #=> "RuntimeError"
+    # @performance Construction is linear in backtrace and context size.
+    class Notice
+      ATTRIBUTES = [
+        :event_id, :exception_class, :message, :backtrace, :causes,
+        :severity, :timestamp, :context, :parameters, :session, :user,
+        :environment, :runtime, :versions, :host, :process, :thread,
+        :tags, :fingerprint
+      ].freeze
+
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(attributes)
+        ATTRIBUTES.each do |attribute|
+          instance_variable_set("@#{attribute}", deep_freeze(attributes[attribute]))
+        end
+        freeze
+      end
+
+      def to_h
+        ATTRIBUTES.each_with_object({}) do |attribute, result|
+          result[attribute] = public_send(attribute)
+        end
+      end
+
+      private
+
+      def deep_freeze(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
+    end
+  end
+end

data/lib/chronos/core/notice_builder.rb

@@ -0,0 +1,83 @@
+require "securerandom"
+require "time"
+
+module Chronos
+  module Core
+    # Normalizes an Exception and caller context into a Notice.
+    #
+    # @responsibility Coordinate backtrace, causes, runtime, and caller-provided fields.
+    # @motivation Isolate Ruby runtime behavior from delivery code.
+    # @limits It does not serialize, enqueue, or perform HTTP.
+    # @collaborators BacktraceParser, ExceptionCauseCollector, RuntimeInfo, and Notice.
+    # @thread_safety Collaborators are stateless and the builder keeps no call state.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   notice = builder.call(RuntimeError.new("failed"), :tags => ["billing"])
+    # @performance Linear in backtrace and supplied context size.
+    class NoticeBuilder
+      def initialize(config, clock = nil)
+        @config = config
+        @clock = clock || proc { Time.now }
+        @backtrace_parser = BacktraceParser.new(config.root_directory)
+        @cause_collector = ExceptionCauseCollector.new
+        @runtime_info = RuntimeInfo.new
+      end
+
+      def call(exception, context = {})
+        raise ArgumentError, "exception must be an Exception" unless exception.is_a?(Exception)
+
+        context = {} unless context.is_a?(Hash)
+        runtime = @runtime_info.call
+        Notice.new(
+          :event_id => SecureRandom.uuid,
+          :exception_class => safe_class_name(exception),
+          :message => safe_message(exception),
+          :backtrace => @backtrace_parser.call(exception.backtrace),
+          :causes => @cause_collector.call(exception),
+          :severity => value(context, :severity) || "error",
+          :timestamp => @clock.call.utc.iso8601(6),
+          :context => value(context, :context) || context_without_reserved_keys(context),
+          :parameters => value(context, :parameters) || {},
+          :session => value(context, :session) || {},
+          :user => value(context, :user) || {},
+          :environment => @config.environment,
+          :runtime => runtime[:runtime],
+          :versions => {"agent" => Chronos::VERSION, "application" => @config.app_version},
+          :host => runtime[:host],
+          :process => runtime[:process],
+          :thread => runtime[:thread],
+          :tags => Array(value(context, :tags)),
+          :fingerprint => value(context, :fingerprint)
+        )
+      end
+
+      private
+
+      RESERVED_KEYS = [:severity, :context, :parameters, :session, :user, :tags, :fingerprint].freeze
+
+      def value(hash, key)
+        hash.key?(key) ? hash[key] : hash[key.to_s]
+      end
+
+      def context_without_reserved_keys(context)
+        context.each_with_object({}) do |(key, child), result|
+          result[key] = child unless RESERVED_KEYS.include?(key.to_sym)
+        end
+      rescue StandardError
+        {}
+      end
+
+      def safe_class_name(exception)
+        exception.class.name.to_s
+      rescue StandardError
+        "Exception"
+      end
+
+      def safe_message(exception)
+        exception.message.to_s
+      rescue StandardError
+        "<unreadable exception message>"
+      end
+    end
+  end
+end

data/lib/chronos/core/payload_serializer.rb

@@ -0,0 +1,165 @@
+require "json"
+require "time"
+
+module Chronos
+  module Core
+    # Serialized event ready for transport.
+    #
+    # @responsibility Keep an event ID next to its JSON body.
+    # @motivation Allow transports to set idempotency headers without reparsing JSON.
+    # @limits It contains no retry or HTTP behavior.
+    # @thread_safety Immutable after construction.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    class SerializedEvent
+      attr_reader :event_id, :body
+
+      def initialize(event_id, body)
+        @event_id = event_id.to_s.freeze
+        @body = body.to_s.freeze
+        freeze
+      end
+
+      def bytesize
+        body.bytesize
+      end
+    end
+
+    # Converts a Notice into the versioned Chronos JSON envelope.
+    #
+    # @responsibility Normalize values to JSON primitives and enforce size limits.
+    # @motivation Prevent arbitrary application objects or invalid encodings from breaking capture.
+    # @limits Version 0.1 applies structural limits, not the advanced privacy rules from 0.2.
+    # @collaborators Notice and SerializedEvent.
+    # @thread_safety Stateless apart from immutable configuration.
+    # @compatibility Uses the JSON standard library available on Ruby 2.2.10.
+    # @example
+    #   event = serializer.call(notice)
+    #   event.body #=> "{...}"
+    # @errors Serialization failures are handled by CaptureException.
+    # @performance Linear in payload size with bounded depth and collection sizes.
+    class PayloadSerializer
+      MAX_DEPTH = 10
+      MAX_KEYS = 100
+      MAX_ITEMS = 100
+      MAX_STRING_BYTES = 8192
+
+      def initialize(config, clock = nil)
+        @config = config
+        @clock = clock || proc { Time.now }
+      end
+
+      def call(notice)
+        envelope = build_envelope(notice)
+        body = JSON.generate(envelope)
+        body = JSON.generate(compact_envelope(envelope)) if body.bytesize > @config.max_payload_size
+        raise Error, "event exceeds max_payload_size" if body.bytesize > @config.max_payload_size
+
+        SerializedEvent.new(notice.event_id, body)
+      end
+
+      private
+
+      def build_envelope(notice)
+        {
+          "schema_version" => "1.0",
+          "event_id" => notice.event_id,
+          "event_type" => "exception",
+          "occurred_at" => notice.timestamp,
+          "sent_at" => @clock.call.utc.iso8601(6),
+          "project_key" => safe_string(@config.project_id),
+          "environment" => safe_string(notice.environment),
+          "service" => {
+            "name" => safe_string(@config.service_name),
+            "version" => safe_string(@config.app_version),
+            "instance_id" => safe_string(notice.host)
+          },
+          "runtime" => normalize(notice.runtime, 0),
+          "context" => normalize(notice.context, 0),
+          "payload" => payload(notice)
+        }
+      end
+
+      def payload(notice)
+        normalize({
+                    "exception" => {
+                      "class" => notice.exception_class,
+                      "message" => notice.message,
+                      "backtrace" => notice.backtrace,
+                      "causes" => notice.causes
+                    },
+                    "severity" => notice.severity,
+                    "parameters" => notice.parameters,
+                    "session" => notice.session,
+                    "user" => notice.user,
+                    "versions" => notice.versions,
+                    "host" => notice.host,
+                    "process" => notice.process,
+                    "thread" => notice.thread,
+                    "tags" => notice.tags,
+                    "fingerprint" => notice.fingerprint
+                  }, 0)
+      end
+
+      def compact_envelope(envelope)
+        payload = envelope["payload"]
+        exception = payload["exception"]
+        exception["message"] = truncate_string(exception["message"], 1024)
+        exception["backtrace"] = Array(exception["backtrace"]).first(20)
+        payload["parameters"] = {"_truncated" => true}
+        payload["session"] = {"_truncated" => true}
+        payload["user"] = {"_truncated" => true}
+        envelope["context"] = {"_truncated" => true}
+        envelope
+      end
+
+      def normalize(value, depth)
+        return "<maximum depth reached>" if depth >= MAX_DEPTH
+
+        case value
+        when nil, true, false, Integer
+          value
+        when Float
+          value.finite? ? value : value.to_s
+        when String, Symbol
+          truncate_string(safe_string(value), MAX_STRING_BYTES)
+        when Array
+          value.first(MAX_ITEMS).map { |child| normalize(child, depth + 1) }
+        when Hash
+          normalize_hash(value, depth)
+        else
+          "<#{safe_class_name(value)}>"
+        end
+      rescue StandardError
+        "<unserializable value>"
+      end
+
+      def normalize_hash(value, depth)
+        result = {}
+        value.to_a.first(MAX_KEYS).each do |key, child|
+          result[truncate_string(safe_string(key), 256)] = normalize(child, depth + 1)
+        end
+        result
+      end
+
+      def safe_string(value)
+        return nil if value.nil?
+
+        value.to_s.encode("UTF-8", :invalid => :replace, :undef => :replace, :replace => "�")
+      rescue StandardError
+        "<unreadable value>"
+      end
+
+      def truncate_string(value, limit)
+        return value if value.nil? || value.bytesize <= limit
+
+        value.byteslice(0, limit).to_s.encode("UTF-8", :invalid => :replace, :undef => :replace, :replace => "�") + "…"
+      end
+
+      def safe_class_name(value)
+        value.class.name.to_s
+      rescue StandardError
+        "Object"
+      end
+    end
+  end
+end

data/lib/chronos/core/runtime_info.rb

@@ -0,0 +1,42 @@
+require "socket"
+
+module Chronos
+  module Core
+    # Collects low-cost runtime identifiers for an event.
+    #
+    # @responsibility Report Ruby, platform, process, thread, and optional host data.
+    # @motivation Provide enough environment context for diagnosis and grouping.
+    # @limits It does not enumerate environment variables, gems, or machine secrets.
+    # @thread_safety Stateless; all returned hashes are new objects.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6 and feature-detected engines.
+    # @example
+    #   Chronos::Core::RuntimeInfo.new.call
+    # @performance Uses constant-time runtime lookups and one hostname lookup.
+    class RuntimeInfo
+      def call
+        {
+          :runtime => {
+            "ruby_version" => RUBY_VERSION,
+            "ruby_engine" => ruby_engine,
+            "platform" => RUBY_PLATFORM
+          },
+          :host => safe_hostname,
+          :process => {"pid" => Process.pid},
+          :thread => {"id" => Thread.current.object_id.to_s}
+        }
+      end
+
+      private
+
+      def ruby_engine
+        defined?(RUBY_ENGINE) ? RUBY_ENGINE : "ruby"
+      end
+
+      def safe_hostname
+        Socket.gethostname.to_s
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/chronos/core.rb

@@ -0,0 +1,10 @@
+module Chronos
+  # Framework-independent domain values and normalization services.
+  #
+  # @responsibility Model and normalize Chronos events.
+  # @motivation Keep runtime data independent from delivery mechanisms.
+  # @limits Does not depend on Rails, Rack, Sidekiq, or Net::HTTP.
+  # @thread_safety Components are immutable or stateless unless documented otherwise.
+  # @compatibility Ruby 2.2.10 through Ruby 2.6.
+  module Core; end
+end

data/lib/chronos/errors.rb

@@ -0,0 +1,24 @@
+module Chronos
+  # Base error raised by explicit Chronos setup operations.
+  #
+  # @responsibility Provide a common ancestor for errors callers may handle.
+  # @motivation Separate agent setup failures from application failures.
+  # @limits Runtime capture and delivery errors never escape through this class.
+  # @thread_safety Error instances are not shared by the agent.
+  # @compatibility Ruby 2.2.10 and newer legacy runtimes.
+  # @example
+  #   rescue Chronos::Error => error
+  #     warn error.message
+  class Error < StandardError; end
+
+  # Raised when a configuration cannot produce a valid immutable snapshot.
+  #
+  # @responsibility Report all invalid configuration fields before agent startup.
+  # @motivation Fail early during explicit setup instead of failing in requests.
+  # @limits It is not used for transport or event errors.
+  # @thread_safety Instances are immutable after construction by convention.
+  # @compatibility Ruby 2.2.10 and newer legacy runtimes.
+  # @example
+  #   Chronos.configure { |config| config.project_key = nil }
+  class ConfigurationError < Error; end
+end

data/lib/chronos/internal/bounded_queue.rb

@@ -0,0 +1,79 @@
+module Chronos
+  module Internal
+    # Thread-safe queue with fixed capacity and non-blocking producer behavior.
+    #
+    # @responsibility Accept events up to a limit and count accepted and dropped items.
+    # @motivation Prevent telemetry bursts from growing application memory indefinitely.
+    # @limits Version 0.1 drops the newest item when full and does not persist to disk.
+    # @collaborators WorkerPool.
+    # @thread_safety Mutex and condition variable protect all mutable state.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6 and fork-aware callers.
+    # @example
+    #   queue.push(event) #=> true or false
+    # @performance Push is constant-time and never waits for free capacity.
+    class BoundedQueue
+      attr_reader :capacity
+
+      def initialize(capacity)
+        raise ArgumentError, "capacity must be positive" unless capacity.is_a?(Integer) && capacity > 0
+
+        @capacity = capacity
+        @items = []
+        @accepted = 0
+        @dropped = 0
+        @closed = false
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+      end
+
+      def push(item)
+        @mutex.synchronize do
+          return false if @closed
+          if @items.length >= @capacity
+            @dropped += 1
+            return false
+          end
+
+          @items << item
+          @accepted += 1
+          @condition.signal
+          true
+        end
+      end
+
+      def pop(timeout = nil)
+        @mutex.synchronize do
+          @condition.wait(@mutex, timeout) while @items.empty? && !@closed && timeout.nil?
+          @condition.wait(@mutex, timeout) if @items.empty? && !@closed && timeout
+          @items.shift
+        end
+      end
+
+      def close
+        @mutex.synchronize do
+          @closed = true
+          @condition.broadcast
+        end
+        true
+      end
+
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+
+      def empty?
+        @mutex.synchronize { @items.empty? }
+      end
+
+      def size
+        @mutex.synchronize { @items.size }
+      end
+
+      def stats
+        @mutex.synchronize do
+          {:size => @items.size, :capacity => capacity, :accepted => @accepted, :dropped => @dropped}
+        end
+      end
+    end
+  end
+end

data/lib/chronos/internal/safe_logger.rb

@@ -0,0 +1,55 @@
+module Chronos
+  module Internal
+    # Protects the host application from logger failures and recursive diagnostics.
+    #
+    # @responsibility Emit bounded internal messages through a configured logger.
+    # @motivation Diagnostics must never become a new application failure.
+    # @limits It does not store logs or include credentials and payloads.
+    # @thread_safety Uses a mutex for recursion protection across threads.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   logger.warn("transport failed")
+    class SafeLogger
+      MAX_MESSAGE_BYTES = 1024
+
+      def initialize(logger)
+        @logger = logger
+        @mutex = Mutex.new
+        @logging = false
+      end
+
+      def debug(message)
+        write(:debug, message)
+      end
+
+      def warn(message)
+        write(:warn, message)
+      end
+
+      private
+
+      def write(level, message)
+        return unless @logger && @logger.respond_to?(level)
+
+        allowed = @mutex.synchronize do
+          next false if @logging
+          @logging = true
+        end
+        return unless allowed
+
+        @logger.public_send(level, bounded(message))
+      rescue StandardError
+        nil
+      ensure
+        @mutex.synchronize { @logging = false } if allowed
+      end
+
+      def bounded(message)
+        text = message.to_s
+        text.bytesize > MAX_MESSAGE_BYTES ? text.byteslice(0, MAX_MESSAGE_BYTES) : text
+      rescue StandardError
+        "Chronos internal diagnostic unavailable"
+      end
+    end
+  end
+end