goodsorcery 0.1.0

data/lib/goodsorcery/delivery/active_job_queue.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Delivery
+    # Enqueues GoodSorcery::DeliveryJob with the filtered event as a JSON
+    # string. Falls back to the background thread when ActiveJob is not loaded
+    # or enqueueing raises. Note: the event is stored in the job backend.
+    class ActiveJobQueue
+      def initialize(serializer:, queue_name:, log:, &fallback_builder)
+        @serializer = serializer
+        @queue_name = queue_name
+        @log = log
+        @fallback_builder = fallback_builder
+        @fallback = nil
+        @lock = Mutex.new
+      end
+
+      def deliver(event)
+        job = DeliveryJobLoader.job_class
+        return deliver_in_background(event, "ActiveJob is not loaded") unless job
+
+        json = @serializer.dump(event)
+        return false unless json
+
+        return true if enqueued?(job.set(queue: @queue_name).perform_later(json))
+
+        deliver_in_background(event, "GoodSorcery::DeliveryJob was not enqueued")
+      rescue StandardError => e
+        deliver_in_background(event, "enqueueing GoodSorcery::DeliveryJob failed (#{e.class})")
+      end
+
+      def flush(timeout = 5)
+        @fallback ? @fallback.flush(timeout) : true
+      end
+
+      def shutdown(timeout = 5)
+        @fallback ? @fallback.shutdown(timeout) : true
+      end
+
+      private
+
+      # perform_later returns false when a callback aborted the enqueue or
+      # the adapter raised ActiveJob::EnqueueError.
+      def enqueued?(job)
+        return false unless job
+
+        job.respond_to?(:successfully_enqueued?) ? job.successfully_enqueued? != false : true
+      end
+
+      def deliver_in_background(event, reason)
+        @log.warn_every(:active_job_fallback, 60, "#{reason}; delivering in the background thread instead")
+        fallback.deliver(event)
+      end
+
+      def fallback
+        @fallback || @lock.synchronize { @fallback ||= @fallback_builder.call }
+      end
+    end
+
+    # Defines GoodSorcery::DeliveryJob on first use, once ActiveJob is loaded.
+    module DeliveryJobLoader
+      def self.job_class
+        return GoodSorcery::DeliveryJob if GoodSorcery.const_defined?(:DeliveryJob, false)
+        return nil unless defined?(::ActiveJob::Base)
+
+        require_relative "../delivery_job"
+        GoodSorcery::DeliveryJob
+      end
+    end
+  end
+end

data/lib/goodsorcery/delivery/async.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Delivery
+    # The default delivery: a bounded in-memory queue drained in batches by
+    # one background thread ("goodsorcery-worker"). The thread starts on the
+    # first event and restarts in a forked child, which starts with an empty
+    # queue (the parent still owns the events it queued).
+    class Async
+      DEFAULTS = {
+        batch_size: 25, flush_interval: 2.0, max_queue_size: 1_000,
+        max_retries: 3, shutdown_timeout: 5, backoff: nil, sleeper: nil
+      }.freeze
+
+      def initialize(transport:, serializer:, log:, **settings)
+        @transport = transport
+        @serializer = serializer
+        @log = log
+        @settings = DEFAULTS.merge(settings)
+        @settings[:backoff] ||= Backoff.new
+        @lock = Mutex.new
+        @pid = Process.pid
+        @queue = new_queue
+        @thread = nil
+      end
+
+      def deliver(event)
+        ensure_worker
+        return true if @queue.push(event)
+
+        @log.warn_every(:queue_full, 60, "queue full (max_queue_size #{@settings[:max_queue_size]}); " \
+                                         "#{@queue.dropped} event(s) dropped so far")
+        false
+      end
+
+      # Waits until every queued event has been handled. => true when drained.
+      def flush(timeout = 5)
+        return true unless running?
+
+        @queue.wait_until_idle(timeout)
+      end
+
+      def shutdown(timeout = @settings[:shutdown_timeout])
+        thread, queue = @lock.synchronize { [@thread, @queue] }
+        return true unless thread&.alive? && @pid == Process.pid
+
+        drained = queue.wait_until_idle(timeout)
+        undelivered = queue.size
+        queue.close
+        thread.join(drained ? 1 : 0.1)
+        log_undelivered(undelivered) unless drained
+        drained
+      end
+
+      def dropped_count
+        @queue.dropped
+      end
+
+      def queue_size
+        @queue.size
+      end
+
+      def running?
+        @pid == Process.pid && @thread&.alive? ? true : false
+      end
+
+      private
+
+      def ensure_worker
+        return if running?
+
+        @lock.synchronize { start_worker unless running? }
+      end
+
+      def start_worker
+        if @pid != Process.pid
+          @pid = Process.pid
+          @queue = new_queue
+        end
+        @queue = new_queue if @queue.closed?
+        @thread = spawn_thread(build_worker)
+        ExitHook.install
+      end
+
+      def spawn_thread(worker)
+        thread = Thread.new do
+          Thread.current.report_on_exception = false
+          worker.run
+        end
+        thread.name = "goodsorcery-worker"
+        thread
+      end
+
+      def build_worker
+        Worker.new(queue: @queue, transport: @transport, serializer: @serializer, log: @log,
+                   settings: @settings.slice(:flush_interval, :max_retries, :backoff, :sleeper))
+      end
+
+      def new_queue
+        EventQueue.new(max_size: @settings[:max_queue_size], batch_size: @settings[:batch_size])
+      end
+
+      # Counted before the queue closes: once closed, the worker drops what is left.
+      def log_undelivered(count)
+        @log.warn("shutdown timed out with #{count} event(s) undelivered")
+      end
+    end
+
+    # Drains the queue when the process exits (registered once, on the first
+    # background delivery).
+    module ExitHook
+      @installed = false
+
+      def self.install
+        return if @installed
+
+        @installed = true
+        at_exit { GoodSorcery.shutdown }
+      end
+    end
+  end
+end

data/lib/goodsorcery/delivery/backoff.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Delivery
+    # Exponential backoff with jitter: about 1, 2, 4, 8 … seconds, capped at
+    # 60 s, each multiplied by a random factor between 0.5 and 1.
+    class Backoff
+      BASE = 1.0
+      MAX = 60.0
+
+      def initialize(random: Random.new)
+        @random = random
+      end
+
+      def delay(attempt)
+        [BASE * (2**attempt), MAX].min * (0.5 + (@random.rand * 0.5))
+      end
+    end
+  end
+end

data/lib/goodsorcery/delivery/custom.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Delivery
+    # Wraps an app-supplied delivery object. It must respond to
+    # deliver(event_hash) and may respond to flush(timeout) and shutdown(timeout).
+    class Custom
+      attr_reader :target
+
+      def initialize(target)
+        @target = target
+      end
+
+      def deliver(event)
+        @target.deliver(event)
+      end
+
+      def flush(timeout = 5)
+        @target.respond_to?(:flush) ? @target.flush(timeout) : true
+      end
+
+      def shutdown(timeout = 5)
+        @target.respond_to?(:shutdown) ? @target.shutdown(timeout) : true
+      end
+    end
+  end
+end

data/lib/goodsorcery/delivery/event_queue.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Delivery
+    # A bounded queue between the app's threads and the delivery worker.
+    # push never blocks: when the queue is full the event is dropped and
+    # counted. The worker takes batches and reports when each is done, so
+    # wait_until_idle can tell when everything queued has been handled.
+    class EventQueue
+      attr_reader :dropped
+
+      def initialize(max_size:, batch_size:)
+        @max_size = max_size
+        @batch_size = batch_size
+        @items = []
+        @in_flight = 0
+        @dropped = 0
+        @closed = false
+        @flushing = false
+        @mutex = Mutex.new
+        @arrived = ConditionVariable.new
+        @idle = ConditionVariable.new
+        @wakeup = ConditionVariable.new
+      end
+
+      def push(event)
+        @mutex.synchronize do
+          next reject if @closed || @items.size >= @max_size
+
+          @items << event
+          @arrived.signal if @items.size == 1 || @items.size >= @batch_size
+          true
+        end
+      end
+
+      # Waits until a batch is due: batch_size events queued, +interval+
+      # seconds since the first one arrived, a flush, or close. Returns []
+      # once the queue is closed and empty.
+      def take_batch(interval)
+        @mutex.synchronize do
+          @arrived.wait(@mutex) while @items.empty? && !@closed
+          wait_for_full_batch(interval)
+          batch = @items.shift(@batch_size)
+          @in_flight = batch.size
+          batch
+        end
+      end
+
+      def batch_done
+        @mutex.synchronize do
+          @in_flight = 0
+          @flushing = false if @items.empty?
+          @idle.broadcast if idle?
+        end
+      end
+
+      def wait_until_idle(timeout)
+        deadline = Clock.now + timeout
+        @mutex.synchronize do
+          @flushing = true
+          @arrived.signal
+          wait_on(@idle, deadline) until idle? || Clock.now >= deadline
+          @flushing = false if idle?
+          idle?
+        end
+      end
+
+      # Sleeps for +seconds+ unless the queue is closed first.
+      def pause(seconds)
+        deadline = Clock.now + seconds
+        @mutex.synchronize do
+          wait_on(@wakeup, deadline) until @closed || Clock.now >= deadline
+        end
+      end
+
+      def close
+        @mutex.synchronize do
+          @closed = true
+          [@arrived, @wakeup, @idle].each(&:broadcast)
+        end
+      end
+
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+
+      def size
+        @mutex.synchronize { @items.size + @in_flight }
+      end
+
+      private
+
+      def reject
+        @dropped += 1
+        false
+      end
+
+      def idle?
+        @items.empty? && @in_flight.zero?
+      end
+
+      def wait_for_full_batch(interval)
+        deadline = Clock.now + interval
+        wait_on(@arrived, deadline) until batch_due? || Clock.now >= deadline
+      end
+
+      def batch_due?
+        @items.size >= @batch_size || @closed || @flushing
+      end
+
+      def wait_on(condition, deadline)
+        remaining = deadline - Clock.now
+        condition.wait(@mutex, remaining) if remaining.positive?
+      end
+    end
+
+    # Monotonic seconds.
+    module Clock
+      def self.now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/goodsorcery/delivery/sync.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Delivery
+    # Sends each event immediately, in the calling thread. For scripts, rake
+    # tasks, serverless functions and debugging.
+    class Sync
+      def initialize(transport:, serializer:, log:)
+        @transport = transport
+        @serializer = serializer
+        @log = log
+      end
+
+      def deliver(event)
+        json = @serializer.dump(event)
+        return false unless json
+
+        result = @transport.post_event(json)
+        @log.warn_every(:sync_failed, 60, "could not deliver an event (#{result.description})") if result.retry_later?
+        result.success?
+      end
+
+      def flush(_timeout = nil) = true
+      def shutdown(_timeout = nil) = true
+    end
+  end
+end

data/lib/goodsorcery/delivery/test.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Delivery
+    # Keeps events in memory for app test suites (GoodSorcery.test_events).
+    # Never touches the network.
+    class Test
+      def initialize
+        @events = []
+        @mutex = Mutex.new
+      end
+
+      def deliver(event)
+        @mutex.synchronize { @events << event }
+        true
+      end
+
+      def events
+        @mutex.synchronize { @events.dup }
+      end
+
+      def clear
+        @mutex.synchronize { @events.clear }
+      end
+
+      def flush(_timeout = nil) = true
+      def shutdown(_timeout = nil) = true
+    end
+  end
+end

data/lib/goodsorcery/delivery/worker.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Delivery
+    # The loop run by the goodsorcery-worker thread: take a batch, serialize
+    # it, send it, retry 5xx/network failures with backoff and wait out 429s
+    # without spending a retry. It never raises and never reports its own
+    # errors as events.
+    class Worker
+      def initialize(queue:, transport:, serializer:, log:, settings:)
+        @queue = queue
+        @transport = transport
+        @serializer = serializer
+        @log = log
+        @flush_interval = settings.fetch(:flush_interval)
+        @max_retries = settings.fetch(:max_retries)
+        @backoff = settings.fetch(:backoff)
+        @sleeper = settings.fetch(:sleeper) || queue
+      end
+
+      def run
+        loop do
+          batch = @queue.take_batch(@flush_interval)
+          break if batch.empty?
+
+          deliver_batch(batch)
+        end
+      end
+
+      def deliver_batch(events)
+        jsons = events.filter_map { |event| @serializer.dump(event) }
+        send_with_retries(jsons)
+      rescue StandardError => e
+        @log.error("the delivery worker hit #{e.class}; #{events.size} event(s) dropped")
+      ensure
+        @queue.batch_done
+      end
+
+      private
+
+      def send_with_retries(jsons)
+        attempt = 0
+        until jsons.empty?
+          result = @transport.post_batch(jsons)
+          jsons = result.pending
+          attempt = wait_before_retry(result, attempt, jsons.size) unless jsons.empty?
+          break if attempt.nil?
+        end
+      end
+
+      # Returns the next attempt number, or nil to give up.
+      def wait_before_retry(result, attempt, count)
+        return give_up(result, count) if @queue.closed?
+
+        if result.rate_limited?
+          @sleeper.pause(result.retry_after)
+          return attempt
+        end
+        return give_up(result, count) if attempt >= @max_retries
+
+        @sleeper.pause(@backoff.delay(attempt))
+        attempt + 1
+      end
+
+      def give_up(result, count)
+        @log.warn_every(:delivery_failed, 60, "could not deliver #{count} event(s) (#{result.description}); dropped")
+        nil
+      end
+    end
+  end
+end

data/lib/goodsorcery/delivery.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "delivery/event_queue"
+require_relative "delivery/backoff"
+require_relative "delivery/worker"
+require_relative "delivery/async"
+require_relative "delivery/sync"
+require_relative "delivery/test"
+require_relative "delivery/custom"
+require_relative "delivery/active_job_queue"
+
+module GoodSorcery
+  # Delivery strategies (config.delivery). Each exposes deliver(event),
+  # flush(timeout) and shutdown(timeout).
+  module Delivery
+    def self.build(config, client)
+      case config.delivery
+      when :async then async(config, client.transport, client.serializer, client.log)
+      when :sync then Sync.new(transport: client.transport, serializer: client.serializer, log: client.log)
+      when :test then Test.new
+      when :active_job then active_job(config, client)
+      else Custom.new(config.delivery)
+      end
+    end
+
+    def self.async(config, transport, serializer, log)
+      Async.new(transport: transport, serializer: serializer, log: log,
+                batch_size: config.batch_size, flush_interval: config.flush_interval,
+                max_queue_size: config.max_queue_size, max_retries: config.max_retries,
+                shutdown_timeout: config.shutdown_timeout)
+    end
+
+    def self.active_job(config, client)
+      ActiveJobQueue.new(serializer: client.serializer, queue_name: config.active_job_queue, log: client.log) do
+        async(config, client.transport, client.serializer, client.log)
+      end
+    end
+  end
+end

data/lib/goodsorcery/delivery_job.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  # Sends one already-filtered event (a JSON string) synchronously. Retries
+  # 429/5xx/network failures with ActiveJob's retry_on. Any exception raised
+  # here is marked as reported first, so no integration reports it back to
+  # Good Sorcery (no recursion). The argument is captured error data, so
+  # Active Job never writes it to the log.
+  class DeliveryJob < ::ActiveJob::Base
+    WAIT = ::ActiveJob.gem_version >= Gem::Version.new("7.1") ? :polynomially_longer : :exponentially_longer
+
+    self.log_arguments = false
+    queue_as { GoodSorcery.configuration.active_job_queue }
+    retry_on GoodSorcery::RetryableDeliveryError, wait: WAIT, attempts: 5
+
+    def perform(event_json)
+      result = GoodSorcery.client.transport.post_event(event_json)
+      return unless result.retry_later?
+
+      raise GoodSorcery::RetryableDeliveryError, "event delivery failed (#{result.description})"
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      ReportedMark.mark(e)
+      raise
+    end
+  end
+end

data/lib/goodsorcery/env_flag.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  # Reads boolean environment variables such as GOODSORCERY_ENABLED.
+  module EnvFlag
+    TRUE_VALUES = %w[1 true yes on].freeze
+    FALSE_VALUES = %w[0 false no off].freeze
+
+    # => true, false, or nil when the value is unset or unrecognised.
+    def self.parse(value)
+      normalized = value.to_s.strip.downcase
+      return true if TRUE_VALUES.include?(normalized)
+      return false if FALSE_VALUES.include?(normalized)
+
+      nil
+    end
+
+    # ENV[name] unless it is unset or blank.
+    def self.present(name)
+      value = ENV.fetch(name, nil)
+      value unless value.nil? || value.strip.empty?
+    end
+  end
+end

data/lib/goodsorcery/environment_gate.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  # Decides whether reporting is on for the configured environment
+  # (DESIGN.md 3.2) and explains why.
+  class EnvironmentGate
+    def initialize(config)
+      @config = config
+    end
+
+    # Checked on every report and breadcrumb, so it builds no strings.
+    def enabled?
+      explicit = @config.enabled
+      return explicit unless explicit.nil?
+
+      allow_list = @config.enabled_environments
+      return listed?(allow_list) if allow_list
+
+      !listed?(@config.disabled_environments)
+    end
+
+    def reason
+      decision.last
+    end
+
+    private
+
+    def decision
+      explicit = @config.enabled
+      return [explicit, "config.enabled (or GOODSORCERY_ENABLED) is #{explicit}"] unless explicit.nil?
+      return allow_list_decision if @config.enabled_environments
+
+      deny_list_decision
+    end
+
+    def allow_list_decision
+      included = names(@config.enabled_environments).include?(environment)
+      verb = included ? "is" : "is not"
+      [included, "environment #{environment.inspect} #{verb} in enabled_environments"]
+    end
+
+    def deny_list_decision
+      excluded = names(@config.disabled_environments).include?(environment)
+      verb = excluded ? "is" : "is not"
+      [!excluded, "environment #{environment.inspect} #{verb} in disabled_environments"]
+    end
+
+    def environment
+      @config.environment.to_s
+    end
+
+    def names(list)
+      Array(list).map(&:to_s)
+    end
+
+    def listed?(list)
+      name = environment
+      Array(list).any? { |entry| entry.to_s == name }
+    end
+  end
+end

data/lib/goodsorcery/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  # Base class for errors raised by the gem itself.
+  class Error < StandardError; end
+
+  # Raised (and rescued) by `goodsorcery:test` and the install check to send a
+  # realistic test exception.
+  class TestError < StandardError; end
+
+  # Raised by GoodSorcery::DeliveryJob so ActiveJob retries a delivery that
+  # failed with a 429, a 5xx or a network error.
+  class RetryableDeliveryError < Error; end
+end

data/lib/goodsorcery/event/breadcrumb.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Event
+    # Builds one breadcrumb, copying and capping its data when it is recorded
+    # so the scope never holds on to app objects.
+    module Breadcrumb
+      CATEGORIES = %w[request controller sql http cache log job custom].freeze
+      LEVELS = %w[debug info warning error].freeze
+      MAX_MESSAGE_LENGTH = 1_000
+      DATA_SANITIZER = Sanitizer.new(max_depth: 4, max_items: 20, max_keys: 20, max_string: 1_000)
+
+      module_function
+
+      def build(message, category: "custom", level: "info", data: nil, time: Time.now)
+        crumb = {
+          "timestamp" => Fields.timestamp(time),
+          "category" => choice(category, CATEGORIES, "custom"),
+          "level" => choice(Fields::LEVEL_ALIASES.fetch(level.to_s, level.to_s), LEVELS, "info"),
+          "message" => Text.limit(message, MAX_MESSAGE_LENGTH)
+        }
+        crumb["data"] = DATA_SANITIZER.sanitize(data) if data.is_a?(Hash) && !data.empty?
+        crumb
+      end
+
+      def choice(value, allowed, default)
+        name = value.to_s
+        allowed.include?(name) ? name : default
+      end
+    end
+  end
+end