naijacloud-argus 0.1.0

data/lib/naijacloud/argus/scope.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module NaijaCloud
+  module Argus
+    # User, tags, contexts and breadcrumbs that are attached to the next event.
+    #
+    # There is one global scope, plus one per request or job: the Rack
+    # middleware and the ActiveJob hook open a scope around each unit of work,
+    # so `set_user` in one Puma thread never labels another thread's error.
+    # Outside a request, writes go to the global scope.
+    class Scope
+      attr_reader :tags, :contexts, :breadcrumbs
+      attr_accessor :user, :transaction, :request
+
+      def initialize(max_breadcrumbs = 100)
+        @max_breadcrumbs = max_breadcrumbs
+        @tags = {}
+        @contexts = {}
+        @breadcrumbs = []
+        @user = nil
+        @transaction = nil
+        @request = nil
+        @mutex = Mutex.new
+      end
+
+      def set_tag(key, value)
+        @mutex.synchronize { @tags[key.to_s] = value.to_s }
+      end
+
+      def set_context(name, ctx)
+        @mutex.synchronize { ctx.nil? ? @contexts.delete(name.to_s) : @contexts[name.to_s] = ctx }
+      end
+
+      def add_breadcrumb(crumb)
+        @mutex.synchronize do
+          @breadcrumbs << crumb
+          @breadcrumbs.shift(@breadcrumbs.length - @max_breadcrumbs) if @breadcrumbs.length > @max_breadcrumbs
+        end
+      end
+
+      # `transaction` may be a callable: the Rack middleware only learns the
+      # route after the router has run, which is after an error raised inside
+      # the app may already have been reported.
+      def snapshot
+        @mutex.synchronize do
+          t = @transaction
+          t = (t.call rescue nil) if t.respond_to?(:call) # rubocop:disable Style/RescueModifier
+          { user: @user, tags: @tags.dup, contexts: @contexts.dup, breadcrumbs: @breadcrumbs.dup,
+            transaction: t, request: @request }
+        end
+      end
+
+      def self.current
+        Thread.current[:naijacloud_argus_scope]
+      end
+
+      def self.with(scope)
+        prev = Thread.current[:naijacloud_argus_scope]
+        Thread.current[:naijacloud_argus_scope] = scope
+        yield scope
+      ensure
+        Thread.current[:naijacloud_argus_scope] = prev
+      end
+    end
+  end
+end

data/lib/naijacloud/argus/scrub.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module NaijaCloud
+  module Argus
+    # Privacy defaults (spec §7). Ingest applies the same rules again on
+    # arrival; the SDK does not rely on that, because a value that never leaves
+    # the process cannot leak in transit or in a proxy's log.
+    module Scrub
+      FILTERED = "[Filtered]"
+
+      CONTAINS = %w[
+        password passwd secret token apikey accesskey authorization credential
+        cookie privatekey cardnumber creditcard bvn cvv cvc sessionid
+        sessiontoken signature
+      ].freeze
+      EXACT = %w[auth pwd pin otp session card sid].freeze
+
+      CARD = /\b(?:\d[ -]?){12,18}\d\b/.freeze
+      CREDENTIAL = %r{\b(bearer|basic|token)\s+[A-Za-z0-9._~+/=-]{8,}}i.freeze
+      JWT = /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b/.freeze
+      KV = /\b([a-z0-9_-]*(?:password|passwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|credential|bvn|cvv)[a-z0-9_-]*)(\s*[:=]\s*)(["']?)([^"'\s,;&})]+)/i.freeze
+
+      MAX_DEPTH = 8
+
+      module_function
+
+      # Whether a field's value should be filtered: lowercased with `-`, `_`
+      # and spaces removed, it contains or equals one of the listed words.
+      def sensitive_key?(key)
+        n = key.to_s.downcase.delete("-_ ")
+        EXACT.include?(n) || CONTAINS.any? { |c| n.include?(c) }
+      end
+
+      # Filters card numbers, credentials, JWTs and sensitive key=value pairs
+      # inside a string.
+      def scrub_string(str)
+        return str if str.nil? || str.empty?
+
+        str = str.dup.force_encoding(Encoding::UTF_8)
+        str = str.scrub("?") unless str.valid_encoding?
+        str
+          .gsub(CARD) { |m| card?(m.delete(" -")) ? FILTERED : m }
+          .gsub(CREDENTIAL) { "#{Regexp.last_match(1)} #{FILTERED}" }
+          .gsub(JWT, FILTERED)
+          .gsub(KV) { "#{Regexp.last_match(1)}#{Regexp.last_match(2)}#{Regexp.last_match(3)}#{FILTERED}" }
+      end
+
+      # Deep-scrubs a JSON-like value into a new one. Hash keys become strings.
+      # Cycles and anything nested deeper than 8 are cut rather than followed,
+      # so a self-referencing object cannot hang the request that reports it.
+      def scrub(value, depth = 0, seen = {})
+        case value
+        when String then scrub_string(value)
+        when Symbol then scrub_string(value.to_s)
+        when nil, true, false, Integer then value
+        when Float then value.finite? ? value : value.to_s
+        when Hash, Array
+          return "[…]" if depth > MAX_DEPTH || seen.key?(value.object_id)
+
+          seen[value.object_id] = true
+          out = if value.is_a?(Array)
+                  value.map { |v| scrub(v, depth + 1, seen) }
+                else
+                  value.each_with_object({}) do |(k, v), acc|
+                    acc[k.to_s] = sensitive_key?(k) && !blank?(v) ? FILTERED : scrub(v, depth + 1, seen)
+                  end
+                end
+          seen.delete(value.object_id)
+          out
+        else
+          scrub_string(safe_to_s(value))
+        end
+      end
+
+      # Removes the query string and fragment from a URL (spec §7).
+      def strip_query(url)
+        url = url.to_s
+        i = url.index(/[?#]/)
+        i ? url[0, i] : url
+      end
+
+      def card?(digits)
+        return false unless digits.length.between?(13, 19)
+
+        sum = 0
+        digits.reverse.each_char.with_index do |ch, i|
+          d = ch.ord - 48
+          if i.odd?
+            d *= 2
+            d -= 9 if d > 9
+          end
+          sum += d
+        end
+        (sum % 10).zero?
+      end
+
+      def blank?(value)
+        value.nil? || value == ""
+      end
+
+      def safe_to_s(value)
+        value.to_s
+      rescue StandardError
+        "#<#{value.class}>"
+      end
+    end
+  end
+end

data/lib/naijacloud/argus/span.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module NaijaCloud
+  module Argus
+    # A unit of work in a trace. Finish it once.
+    class Span
+      KIND_INTERNAL = 1
+      KIND_SERVER = 2
+      KIND_CLIENT = 3
+
+      TRACEPARENT = /\A00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})\z/.freeze
+
+      attr_reader :trace_id, :span_id, :parent_span_id, :kind, :start_time, :attributes
+      attr_accessor :name
+
+      # Parses a W3C traceparent header into `{trace_id:, span_id:, sampled:}`.
+      def self.parse_traceparent(header)
+        m = header && TRACEPARENT.match(header.to_s.strip)
+        return nil if m.nil? || m[1] =~ /\A0+\z/ || m[2] =~ /\A0+\z/
+
+        { trace_id: m[1], span_id: m[2], sampled: (m[3].to_i(16) & 1) == 1 }
+      end
+
+      # The span in progress on this thread (or fiber), if any.
+      def self.current
+        Thread.current[:naijacloud_argus_span]
+      end
+
+      # Runs the block with span as the current one.
+      def self.with(span)
+        prev = Thread.current[:naijacloud_argus_span]
+        Thread.current[:naijacloud_argus_span] = span
+        yield
+      ensure
+        Thread.current[:naijacloud_argus_span] = prev
+      end
+
+      def initialize(client, name, kind: KIND_INTERNAL, parent: nil, attributes: nil)
+        @client = client
+        @name = name.to_s
+        @kind = kind
+        @attributes = attributes ? attributes.dup : {}
+        @trace_id = parent ? parent[:trace_id] : SecureRandom.hex(16)
+        @parent_span_id = parent && parent[:span_id]
+        @span_id = SecureRandom.hex(8)
+        @sampled = parent ? parent[:sampled] : (client ? client.sample_trace? : false)
+        @start_time = Time.now.to_f
+        @finished = false
+      end
+
+      def sampled?
+        @sampled
+      end
+
+      # Whether finishing this span sends anything.
+      def recording?
+        @sampled && !@client.nil?
+      end
+
+      def set_attribute(key, value)
+        @attributes[key.to_s] = value
+        self
+      end
+
+      def set_attributes(hash)
+        hash.each { |k, v| set_attribute(k, v) }
+        self
+      end
+
+      # The W3C traceparent for an outgoing request, so the service it calls
+      # continues this trace.
+      def traceparent
+        "00-#{@trace_id}-#{@span_id}-#{@sampled ? '01' : '00'}"
+      end
+
+      # Ends the span. Pass the error (or a message) when the work failed.
+      def finish(error = nil)
+        return self if @finished
+
+        @finished = true
+        return self unless recording?
+
+        message = case error
+                  when nil, false then nil
+                  when Exception then "#{error.class}: #{error.message}"
+                  else error.to_s
+                  end
+        @client.record_span(
+          trace_id: @trace_id, span_id: @span_id, parent_span_id: @parent_span_id,
+          name: @name, kind: @kind, start: @start_time, end: Time.now.to_f,
+          error: message, attributes: @attributes,
+        )
+        self
+      rescue StandardError
+        self
+      end
+
+      def finished?
+        @finished
+      end
+
+      def inspect
+        "#<NaijaCloud::Argus::Span #{@name.inspect} trace=#{@trace_id} span=#{@span_id}>"
+      end
+    end
+  end
+end

data/lib/naijacloud/argus/stack.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module NaijaCloud
+  module Argus
+    # Turns a Ruby backtrace into Sentry frames, oldest first (spec §4).
+    class Stack
+      # "path:12:in `meth'" (Ruby < 3.4) and "path:12:in 'Klass#meth'" (3.4+).
+      LINE = /\A(.+?):(\d+)(?::in [`'](.*)')?\z/.freeze
+      CONTEXT_LINES = 5
+      MAX_FRAMES = 250
+      MAX_FILE_BYTES = 1 << 20
+      CACHE_SIZE = 64
+
+      def initialize(project_root: nil, context_lines: true)
+        @root = project_root && File.expand_path(project_root.to_s)
+        @context_lines = context_lines
+        @cache = {}
+        @mutex = Mutex.new
+        @library_paths = library_paths
+      end
+
+      attr_reader :root
+
+      def frames(exception)
+        lines = exception.backtrace
+        return [] if lines.nil? || lines.empty?
+
+        lines.first(MAX_FRAMES).reverse.filter_map { |line| frame(line) }
+      end
+
+      private
+
+      def frame(line)
+        m = LINE.match(line.to_s)
+        return nil unless m
+
+        abs = m[1]
+        lineno = m[2].to_i
+        fn = m[3]
+        f = { abs_path: abs, filename: relative(abs), lineno: lineno, in_app: in_app?(abs) }
+        f[:function] = fn.sub(/\A(?:block|rescue|ensure)(?: \(\d+ levels\))? in /, "") if fn && !fn.empty?
+        add_context(f, abs, lineno) if @context_lines && f[:in_app]
+        f
+      end
+
+      def relative(abs)
+        return abs.delete_prefix("#{@root}/") if @root && abs.start_with?("#{@root}/")
+
+        gem_path = abs[%r{/gems/([^/]+/.+)\z}, 1]
+        gem_path || abs
+      end
+
+      def in_app?(abs)
+        return false if abs.start_with?("<internal:", "<main>") || abs.include?("/gems/") || abs.include?("/vendor/bundle/")
+        return false if @library_paths.any? { |p| abs.start_with?(p) }
+        return abs.start_with?("#{@root}/") if @root
+
+        true
+      end
+
+      def library_paths
+        paths = [RbConfig::CONFIG["rubylibdir"], RbConfig::CONFIG["rubyarchdir"]]
+        paths.concat(Gem.path) if defined?(Gem)
+        paths.compact.map { |p| File.expand_path(p) }.uniq
+      rescue StandardError
+        []
+      end
+
+      def add_context(frame, path, lineno)
+        src = source(path)
+        return unless src && lineno.positive? && lineno <= src.length
+
+        i = lineno - 1
+        frame[:pre_context] = src[[0, i - CONTEXT_LINES].max...i]
+        frame[:context_line] = src[i]
+        frame[:post_context] = src[(i + 1)..(i + CONTEXT_LINES)] || []
+      end
+
+      # Source files are read once, capped in size, and the cache is bounded,
+      # so a deep stack in a hot error path costs a hash lookup, not disk I/O.
+      def source(path)
+        @mutex.synchronize do
+          return @cache[path] if @cache.key?(path)
+
+          @cache.shift if @cache.size >= CACHE_SIZE
+          @cache[path] = read_source(path)
+        end
+      end
+
+      def read_source(path)
+        return nil unless File.file?(path) && File.size(path) <= MAX_FILE_BYTES
+
+        File.readlines(path, chomp: true).map { |l| l.length > 500 ? "#{l[0, 500]}…" : l }
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end