goodsorcery 0.1.0

data/lib/goodsorcery/reported_mark.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  # Marks exception objects once reported, so the same object reaching
+  # several integrations (middleware, Rails.error, Sidekiq) is sent once.
+  module ReportedMark
+    IVAR = :@__goodsorcery_reported
+
+    def self.reported?(exception)
+      exception.instance_variable_defined?(IVAR)
+    end
+
+    def self.mark(exception)
+      exception.instance_variable_set(IVAR, true) unless exception.frozen?
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/goodsorcery/sanitizer.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  # Turns app data into JSON-safe values within the server's limits
+  # (INGEST_API.md "Limits"): nesting depth, array and object sizes, string
+  # lengths. Unknown objects become strings; structs become hashes so their
+  # keys are filtered too. The result shares no mutable objects with the app.
+  class Sanitizer
+    TRUNCATED = "[truncated]"
+
+    def initialize(max_depth: 6, max_items: 50, max_keys: 100, max_string: 4_096)
+      @max_depth = max_depth
+      @max_items = max_items
+      @max_keys = max_keys
+      @max_string = max_string
+    end
+
+    def sanitize(value, depth = 1)
+      case value
+      when Hash then sanitize_hash(value, depth)
+      when Array then sanitize_array(value, depth)
+      when String then Text.limit(value, @max_string)
+      when Symbol then Text.limit(value.name, @max_string)
+      when Integer, true, false, nil then value
+      else sanitize_object(value, depth)
+      end
+    end
+
+    private
+
+    def sanitize_hash(hash, depth)
+      return TRUNCATED if depth > @max_depth
+
+      hash.first(@max_keys).to_h do |key, value|
+        [Text.limit(key, 200), sanitize(value, depth + 1)]
+      end
+    end
+
+    def sanitize_array(array, depth)
+      return TRUNCATED if depth > @max_depth
+
+      array.first(@max_items).map { |item| sanitize(item, depth + 1) }
+    end
+
+    def sanitize_object(value, depth)
+      return value if value.is_a?(Float) && value.finite?
+      return value.utc.iso8601(3) if value.is_a?(Time)
+      return sanitize_collection(value, depth) if collection?(value)
+
+      Text.limit(Text.safe_to_s(value), @max_string)
+    end
+
+    # Objects whose to_s would print their fields (OpenStruct's is its
+    # inspect) become hashes or arrays, so their keys are filtered too.
+    def collection?(value)
+      structured?(value) || value.respond_to?(:to_unsafe_h) || value.is_a?(::Set)
+    end
+
+    def structured?(value)
+      value.is_a?(Struct) || (defined?(::Data) && value.is_a?(::Data)) ||
+        (defined?(::OpenStruct) && value.is_a?(::OpenStruct)) # rubocop:disable Style/OpenStructUse
+    end
+
+    def sanitize_collection(value, depth)
+      return sanitize_array(value.to_a, depth) if value.is_a?(::Set)
+      return sanitize_hash(value.to_unsafe_h, depth) if value.respond_to?(:to_unsafe_h)
+
+      sanitize_hash(value.to_h, depth)
+    end
+  end
+end

data/lib/goodsorcery/scope.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  # What is known about the current unit of work (a request, a job): context,
+  # user, tags, transaction, request, job and breadcrumbs. Each thread (and
+  # fiber) has its own scope. Hashes are replaced rather than mutated, so a
+  # saved copy stays valid.
+  #
+  # An integration that opens a scope can leave an +enricher+ (an object
+  # responding to +enrich(scope)+) that fills in details only worth computing
+  # when an error is actually reported: the request, the job section, the
+  # user, the transaction.
+  class Scope
+    STORAGE_KEY = :__goodsorcery_scope
+
+    attr_reader :context, :tags, :breadcrumbs
+    attr_accessor :user, :transaction, :request, :request_env, :job, :enricher
+
+    def self.current
+      Thread.current[STORAGE_KEY] ||= new
+    end
+
+    # The scope an integration opened for the current request, job or channel
+    # action (GoodSorcery.with_scope), or nil outside one.
+    def self.unit_of_work
+      scope = Thread.current[STORAGE_KEY]
+      scope&.unit_of_work? ? scope : nil
+    end
+
+    def self.current=(scope)
+      Thread.current[STORAGE_KEY] = scope
+    end
+
+    def self.clear
+      Thread.current[STORAGE_KEY] = nil
+    end
+
+    def initialize(unit_of_work: false)
+      @context = {}
+      @tags = {}
+      @user = nil
+      @breadcrumbs = Breadcrumbs.new
+      @unit_of_work = unit_of_work
+    end
+
+    def unit_of_work?
+      @unit_of_work
+    end
+
+    # Runs the enricher once; later reports reuse what it filled in.
+    def enrich
+      enricher = @enricher
+      return unless enricher
+
+      @enricher = nil
+      enricher.enrich(self)
+    end
+
+    def merge_context(hash)
+      @context = @context.merge(hash) if hash.is_a?(Hash)
+      @context
+    end
+
+    # Merges +hash+ into the context for the duration of the block.
+    def with_context(hash)
+      previous = @context
+      merge_context(hash)
+      yield
+    ensure
+      @context = previous
+    end
+
+    def merge_tags(hash)
+      @tags = @tags.merge(hash) if hash.is_a?(Hash)
+      @tags
+    end
+
+    def add_breadcrumb(crumb, limit)
+      @breadcrumbs.add(crumb, limit)
+    end
+  end
+
+  # A ring buffer of the most recent breadcrumbs in a scope.
+  class Breadcrumbs
+    def initialize
+      @items = []
+    end
+
+    def add(crumb, limit)
+      @items << crumb
+      @items.shift(@items.size - limit) if @items.size > limit
+    end
+
+    def to_a
+      @items.dup
+    end
+
+    def size
+      @items.size
+    end
+
+    def clear
+      @items.clear
+    end
+  end
+end

data/lib/goodsorcery/status_report.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  # Prints "[goodsorcery]"-prefixed lines describing the setup, the verify
+  # result and the test event result. Shows the masked API key only.
+  class StatusReport
+    PREFIX = "[goodsorcery]"
+
+    def initialize(client, out: $stdout)
+      @client = client
+      @config = client.config
+      @out = out
+    end
+
+    def print_settings
+      say("endpoint:    #{@config.endpoint_label}")
+      say("environment: #{@config.environment} (#{enabled_label})")
+      say("delivery:    #{delivery_label}")
+      say("api key:     #{@config.masked_api_key}")
+    end
+
+    def print_verification
+      verification = @client.verify
+      say("verify:      #{verification.ok? ? "ok" : "FAILED"}, #{verification.message}")
+      verification.ok?
+    end
+
+    def print_test_event
+      outcome = TestEvent.new(@client).send_now
+      say("test event:  #{outcome.ok? ? "ok" : "FAILED"}, #{outcome.message}")
+      outcome.ok?
+    end
+
+    def say(line)
+      @out.puts("#{PREFIX} #{line}")
+    end
+
+    private
+
+    def enabled_label
+      state = @client.enabled? ? "reporting enabled" : "reporting disabled"
+      "#{state}: #{@client.disabled_reason}"
+    end
+
+    def delivery_label
+      delivery = @config.delivery
+      delivery.is_a?(Symbol) ? delivery.to_s : delivery.class.name.to_s
+    end
+  end
+end

data/lib/goodsorcery/tasks.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rake"
+require_relative "../goodsorcery"
+require_relative "status_report"
+require_relative "integrations/rake"
+
+module GoodSorcery
+  # Rake tasks: `require "goodsorcery/tasks"` in a Rakefile (Rails apps get
+  # them automatically). They load the app's :environment task when there is
+  # one. Requiring this file also reports exceptions that end a rake run
+  # (GoodSorcery::Integrations::Rake).
+  module Tasks
+    extend Rake::DSL
+
+    def self.load_environment
+      Rake::Task["environment"].invoke if Rake::Task.task_defined?("environment")
+    end
+
+    def self.verify(out: $stdout)
+      report = StatusReport.new(GoodSorcery.client, out: out)
+      report.print_settings
+      report.print_verification
+    end
+
+    def self.send_test_event(out: $stdout)
+      StatusReport.new(GoodSorcery.client, out: out).print_test_event
+    end
+
+    namespace :goodsorcery do
+      desc "Check the Good Sorcery endpoint and API key (sends nothing)"
+      task :verify do
+        GoodSorcery::Tasks.load_environment
+        abort("[goodsorcery] verification failed") unless GoodSorcery::Tasks.verify
+      end
+
+      desc "Send a test exception to Good Sorcery, in any environment"
+      task :test do
+        GoodSorcery::Tasks.load_environment
+        abort("[goodsorcery] test event failed") unless GoodSorcery::Tasks.send_test_event
+      end
+    end
+  end
+end
+
+GoodSorcery::Integrations::Rake.install

data/lib/goodsorcery/test_event.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  # Raises, captures and synchronously sends a GoodSorcery::TestError,
+  # regardless of the environment check. Used by `goodsorcery:test` and the
+  # install check.
+  class TestEvent
+    MESSAGE = "Test error from goodsorcery-ruby: if you can see this, error reporting works."
+
+    Outcome = Struct.new(:ok, :event_id, :message) do
+      def ok? = ok
+    end
+
+    def initialize(client)
+      @client = client
+    end
+
+    def send_now
+      return Outcome.new(false, nil, "no API key configured") if @client.config.api_key.to_s.empty?
+
+      raise TestError, MESSAGE
+    rescue TestError => e
+      deliver(e)
+    end
+
+    private
+
+    def deliver(exception)
+      event = @client.prepare_event(exception, transaction: "goodsorcery:test",
+                                               tags: { "source" => "goodsorcery:test" })
+      return Outcome.new(false, nil, "the test event was dropped by before_send") unless event
+
+      json = @client.serializer.dump(event)
+      return Outcome.new(false, nil, "the test event could not be serialized") unless json
+
+      outcome_for(@client.transport.post_event(json), event)
+    end
+
+    def outcome_for(result, event)
+      return Outcome.new(false, nil, "the server answered #{result.description}") unless result.success?
+
+      id = result.event_id || event["event_id"]
+      Outcome.new(true, id, "sent test event #{id}")
+    end
+  end
+end

data/lib/goodsorcery/text.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  # String helpers: valid UTF-8, length caps, and copies the app can't mutate
+  # after the event was built.
+  module Text
+    module_function
+
+    def limit(value, max)
+      string = utf8(value.is_a?(String) ? value : value.to_s)
+      return string[0, max] if string.length > max
+
+      string.frozen? ? string : string.dup
+    end
+
+    def utf8(string)
+      return string if string.encoding == Encoding::UTF_8 && string.valid_encoding?
+
+      copy = string.dup
+      copy.force_encoding(Encoding::UTF_8) if copy.encoding == Encoding::BINARY
+      return copy.scrub if copy.encoding == Encoding::UTF_8
+
+      copy.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+    rescue EncodingError
+      string.dup.force_encoding(Encoding::UTF_8).scrub
+    end
+
+    # to_s that never raises.
+    def safe_to_s(object)
+      object.to_s
+    rescue StandardError
+      "#<#{object.class}>"
+    end
+  end
+end

data/lib/goodsorcery/transport/batch_chunks.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  class Transport
+    # Splits serialized events into batch request bodies of at most 100
+    # events and about 1.5 MiB of uncompressed JSON (the server accepts 2 MiB).
+    module BatchChunks
+      MAX_EVENTS = 100
+      MAX_BYTES = 1_572_864
+
+      module_function
+
+      def split(jsons)
+        chunks = []
+        current = []
+        bytes = 0
+        jsons.each do |json|
+          if full?(current, bytes, json)
+            chunks << current
+            current = []
+            bytes = 0
+          end
+          current << json
+          bytes += json.bytesize + 1
+        end
+        current.empty? ? chunks : chunks << current
+      end
+
+      def full?(chunk, bytes, json)
+        return false if chunk.empty?
+
+        chunk.size >= MAX_EVENTS || bytes + json.bytesize > MAX_BYTES
+      end
+
+      def body(chunk)
+        "{\"events\":[#{chunk.join(",")}]}"
+      end
+    end
+  end
+end

data/lib/goodsorcery/transport/connection.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  class Transport
+    # One persistent (keep-alive) HTTP connection. A failed request closes it,
+    # so the next one reconnects. A request on a reused connection that the
+    # server already closed is retried once on a fresh connection; event
+    # POSTs are idempotent because the server deduplicates event_id.
+    #
+    # A connection opened before a fork belongs to the parent: the child
+    # drops it without closing it (closing would end the parent's TLS
+    # session) and opens its own.
+    class Connection
+      STALE_ERRORS = [EOFError, Errno::ECONNRESET, Errno::EPIPE, Errno::ECONNABORTED].freeze
+      KEEP_ALIVE_SECONDS = 15
+
+      def initialize(uri, open_timeout:, read_timeout:)
+        @uri = uri
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+        @http = nil
+        @pid = Process.pid
+      end
+
+      def request(request)
+        reused = @http&.started?
+        perform(request)
+      rescue *STALE_ERRORS
+        raise unless reused
+
+        perform(request)
+      end
+
+      # Sends one request on a short-lived connection.
+      def request_once(request)
+        http = build_http
+        http.start { |started| started.request(request) }
+      end
+
+      def close
+        forget_inherited_connection
+        @http&.finish if @http&.started?
+      rescue IOError, SystemCallError
+        nil
+      ensure
+        @http = nil
+      end
+
+      private
+
+      def perform(request)
+        http.request(request)
+      rescue StandardError
+        close
+        raise
+      end
+
+      def http
+        forget_inherited_connection
+        return @http if @http&.started?
+
+        @http = build_http
+        @http.start
+        @http
+      end
+
+      def forget_inherited_connection
+        return if @pid == Process.pid
+
+        @pid = Process.pid
+        @http = nil
+      end
+
+      def build_http
+        http = Net::HTTP.new(@uri.host, @uri.port)
+        http.use_ssl = @uri.scheme == "https"
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER if http.use_ssl?
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
+        http.write_timeout = @read_timeout
+        http.keep_alive_timeout = KEEP_ALIVE_SECONDS
+        http.max_retries = 0
+        http
+      end
+    end
+  end
+end

data/lib/goodsorcery/transport/result.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  class Transport
+    # The outcome of one request, classified for retry decisions:
+    #
+    # - success: 2xx
+    # - rejected: 400, 401, 413, 415, 422 and other 4xx (never retried)
+    # - not_found: 404 (an older server without the endpoint)
+    # - rate_limited: 429, with retry_after seconds
+    # - retryable: 5xx, 408, timeouts and connection errors
+    #
+    # +pending+ lists the serialized events still to send after a
+    # rate_limited or retryable batch result.
+    class Result
+      KINDS = %i[success rejected not_found rate_limited retryable].freeze
+
+      attr_reader :kind, :status, :retry_after, :error_class, :body, :pending
+
+      def self.from_response(response)
+        status = response.code.to_i
+        new(kind_for(status), status: status, body: ResponseBody.parse(response),
+                              retry_after: status == 429 ? RetryAfter.parse(response["Retry-After"]) : nil)
+      end
+
+      def self.from_error(error)
+        new(:retryable, error_class: error.class.name)
+      end
+
+      def self.kind_for(status)
+        return :success if (200..299).cover?(status)
+        return :not_found if status == 404
+        return :rate_limited if status == 429
+        return :retryable if status >= 500 || status == 408
+
+        :rejected
+      end
+
+      def initialize(kind, status: nil, body: nil, retry_after: nil, error_class: nil, pending: [])
+        @kind = kind
+        @status = status
+        @body = body || {}
+        @retry_after = retry_after
+        @error_class = error_class
+        @pending = pending
+      end
+
+      KINDS.each { |name| define_method(:"#{name}?") { @kind == name } }
+
+      def retry_later?
+        rate_limited? || retryable?
+      end
+
+      def with_pending(pending)
+        self.class.new(kind, status: status, body: body, retry_after: retry_after,
+                             error_class: error_class, pending: pending)
+      end
+
+      def event_id
+        body["id"]
+      end
+
+      # Status or error class only, never the body.
+      def description
+        status ? "HTTP #{status}" : error_class.to_s
+      end
+    end
+
+    # Parses small JSON response bodies; anything else becomes {}.
+    module ResponseBody
+      MAX_BYTES = 65_536
+
+      def self.parse(response)
+        text = response.body.to_s
+        return {} if text.empty? || text.bytesize > MAX_BYTES
+
+        parsed = JSON.parse(text)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        {}
+      end
+    end
+
+    # Reads a Retry-After header (seconds or an HTTP date), defaulting to 60 s.
+    module RetryAfter
+      DEFAULT = 60
+      RANGE = (1..3_600)
+
+      def self.parse(value, now: Time.now)
+        seconds = value.to_s.strip.match?(/\A\d+\z/) ? value.to_i : http_date_delay(value, now)
+        (seconds || DEFAULT).clamp(RANGE.min, RANGE.max)
+      end
+
+      def self.http_date_delay(value, now)
+        return nil if value.nil? || value.to_s.empty?
+
+        (Time.httpdate(value.to_s) - now).ceil
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end