raises 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf7a8c31ce5ed40e110b57671dee77d76cc712059ba386c64fed29f3e9da31ad
-  data.tar.gz: 12e7e56ce32e4c3cbeea11912f7de8e765ee0cf44636a99bd963e8b2796c510f
+  metadata.gz: cd2351828d8eeb04e0af96c88322c369dcd2ecd158384d7e80543cede4153646
+  data.tar.gz: 85e43d1fa7d393159c8bb54fc99898863fc5afd7369f680486e8947d74412c1a
 SHA512:
-  metadata.gz: 3ca5937ee49e66bafd8c7dc6d25ca55999d35ebc2f336f75d9206f3a1dccc4570b70c62f4d3169021b305d790941586df216ade5d4257c090b8c9223b09a7f1f
-  data.tar.gz: 95e0bac19718d9f1f0ab67856425c31180f7207c72e0e2fc1cb64d0727c3c446a1cf7dcbaf9adfa33c7c00f8c446b64f7563d58a1cb70af899008b1d90cb256f
+  metadata.gz: f10b1aa6748ccf6848f9b2ceccb479c1d4a6182b44350318cffd93bab4e70f152613fe66520c1c6cc9d600e912b36eb0abc4ba4b5e0072cca6356e6cdf8676ba
+  data.tar.gz: 5ba3f6610cce1de92879f3599180d630e38b8183a5ea357ad1e1b9e8d918d7199fdf48bda4fedf9152f93492fec65c576db6404779160d85d2e8cba1413bb532

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.0
+
+- Add opt-in, bounded disk spooling through `RAISES_SPOOL_DIR`.
+- Retry transient delivery failures safely across Rails processes and restarts.
+- Keep ingestion credentials out of spool files.
+
 ## 0.1.0
 
 - Initial Rails 7.1+ `Rails.error` subscriber.

data/README.md

@@ -10,4 +10,6 @@ Set `RAISES_TOKEN` to the ingestion credential created for the project. Producti
 
 Optional settings are `RAISES_URL`, `RAISES_ENV`, `RAISES_REVISION`, `RAISES_OPEN_TIMEOUT`, and `RAISES_READ_TIMEOUT`.
 
+Set `RAISES_SPOOL_DIR` to add restart-safe, disk-backed delivery retries. The directory must be on persistent storage if notices should survive a deploy. Raises stores notice JSON there with private permissions, never stores the ingestion token, retries network errors, HTTP 408/429, and 5xx responses, and bounds the spool at 1,000 notices or 100 MB. Leave it unset to preserve synchronous best-effort delivery.
+
 The reporter fails open: network or serialization failures never replace the application exception. Rails filtered parameters are included; headers, raw bodies, query strings, and the request object are not.

data/lib/raises/delivery.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module Raises
+  class Delivery
+    def initialize(post:, spool:, warn:)
+      @post = post
+      @spool = spool
+      @warn = warn
+    end
+
+    def call(notice)
+      response = @post.call(notice)
+      return response unless response.respond_to?(:code)
+      return response if response.is_a?(Net::HTTPSuccess)
+
+      handle_response(notice, response.code.to_i)
+      response
+    rescue StandardError => e
+      handle_exception(notice, e)
+      nil
+    end
+
+    private
+
+    def handle_response(notice, status)
+      if retryable_status?(status) && @spool&.enqueue(notice)
+        @warn.call("raises queued notice after HTTP #{status}")
+      else
+        @warn.call("raises rejected notice: HTTP #{status}")
+      end
+    end
+
+    def handle_exception(notice, error)
+      if @spool&.enqueue(notice)
+        @warn.call("raises queued notice after #{error.class}")
+      else
+        @warn.call("raises subscriber failed: #{error.class}: #{error.message}")
+      end
+    end
+
+    def retryable_status?(status)
+      status == 408 || status == 429 || status >= 500
+    end
+  end
+end

data/lib/raises/railtie.rb

@@ -3,7 +3,7 @@
 module Raises
   class Railtie < Rails::Railtie
     initializer "raises.subscribe" do
-      Rails.error.subscribe(Raises::Subscriber.new)
+      Rails.error.subscribe(Raises::Subscriber.new.start)
     end
   end
 end

data/lib/raises/spool.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "spool_storage"
+
+module Raises
+  class Spool
+    RETRYABLE_STATUS = [408, 429].freeze
+
+    def initialize(directory, deliver:, warn:, **options)
+      @deliver = deliver
+      @warn = warn
+      @now = options.fetch(:now, -> { Time.now })
+      @random = options.fetch(:random, Random.new)
+      @start_on_enqueue = options.fetch(:start_on_enqueue, true)
+      @storage = SpoolStorage.new(directory, warn: warn, now: @now)
+      reset_process_state
+    end
+
+    def start
+      reset_process_state if @pid != Process.pid
+      @mutex.synchronize do
+        return if @thread&.alive?
+
+        @thread = Thread.new { run }
+        @thread.name = "raises-spool" if @thread.respond_to?(:name=)
+        @thread.report_on_exception = false
+      end
+    end
+
+    def stop
+      return if @pid != Process.pid
+
+      thread = @mutex.synchronize do
+        @stopping = true
+        @condition.broadcast
+        @thread
+      end
+      thread&.join(1)
+    end
+
+    def enqueue(notice)
+      accepted = @storage.store(notice) == :stored
+      if accepted
+        start if @start_on_enqueue
+        wake if @start_on_enqueue
+      else
+        @warn.call("raises spool is full; notice was not queued")
+      end
+      accepted
+    rescue StandardError => e
+      @warn.call("raises could not queue notice: #{e.class}: #{e.message}")
+      false
+    end
+
+    def drain_once(limit: 20)
+      @storage.each_due(limit: limit) do |path, envelope|
+        deliver(path, envelope)
+      end
+    end
+
+    private
+
+    def reset_process_state
+      @pid = Process.pid
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @thread = nil
+      @stopping = false
+    end
+
+    def deliver(path, envelope)
+      response = @deliver.call(envelope.fetch("notice"))
+      status = response_code(response)
+      if status.between?(200, 299)
+        @storage.delete(path)
+      elsif retryable_status?(status)
+        reschedule(path, envelope, retry_after(response))
+      else
+        @storage.delete(path)
+        @warn.call("raises rejected queued notice: HTTP #{status}")
+      end
+    rescue StandardError => e
+      reschedule(path, envelope)
+      @warn.call("raises queued notice retry failed: #{e.class}: #{e.message}")
+    end
+
+    def response_code(response)
+      Integer(response.respond_to?(:code) ? response.code : response)
+    rescue ArgumentError, TypeError
+      500
+    end
+
+    def retryable_status?(status)
+      RETRYABLE_STATUS.include?(status) || status >= 500
+    end
+
+    def retry_after(response)
+      return unless response.respond_to?(:[])
+
+      seconds = Integer(response["Retry-After"], exception: false)
+      seconds&.clamp(1, 3_600)
+    end
+
+    def reschedule(path, envelope, requested_delay = nil)
+      attempts = envelope.fetch("attempts", 0).to_i + 1
+      base = [2**[attempts, 8].min, 300].min
+      delay = requested_delay || (base + (@random.rand * base * 0.2))
+      envelope["attempts"] = attempts
+      envelope["next_attempt_at"] = @now.call.to_f + delay
+      @storage.rewrite(path, envelope)
+    end
+
+    def run
+      loop do
+        drain_once
+        @mutex.synchronize do
+          break if @stopping
+
+          @condition.wait(@mutex, 5)
+          break if @stopping
+        end
+      end
+    rescue StandardError => e
+      @warn.call("raises spool worker stopped: #{e.class}: #{e.message}")
+    end
+
+    def wake
+      return if @pid != Process.pid
+
+      @mutex.synchronize { @condition.broadcast }
+    end
+  end
+end

data/lib/raises/spool_storage.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "securerandom"
+
+module Raises
+  class SpoolStorage
+    MAX_NOTICES = 1_000
+    MAX_BYTES = 100 * 1024 * 1024
+
+    def initialize(directory, warn:, now:)
+      @directory = File.expand_path(directory)
+      @warn = warn
+      @now = now
+      prepare
+    end
+
+    def store(notice)
+      prepare
+      raw = JSON.generate("version" => 1, "attempts" => 0, "next_attempt_at" => @now.call.to_f, "notice" => notice)
+      with_directory_lock do
+        return :full unless capacity_for?(raw)
+
+        atomic_write(File.join(@directory, filename), raw)
+      end
+      :stored
+    end
+
+    def each_due(limit:)
+      processed = 0
+      files.each do |path|
+        break if processed >= limit
+
+        File.open(path, File::RDWR) do |file|
+          next unless file.flock(File::LOCK_EX | File::LOCK_NB)
+
+          envelope = parse(file.read, path)
+          next unless envelope
+          next if envelope.fetch("next_attempt_at", 0).to_f > @now.call.to_f
+
+          processed += 1
+          yield path, envelope
+        end
+      rescue Errno::ENOENT
+        next
+      end
+      processed
+    end
+
+    def delete(path)
+      File.delete(path)
+    rescue Errno::ENOENT
+      nil
+    end
+
+    def rewrite(path, envelope)
+      atomic_write(path, JSON.generate(envelope))
+    end
+
+    private
+
+    def prepare
+      FileUtils.mkdir_p(@directory, mode: 0o700)
+      File.chmod(0o700, @directory)
+    end
+
+    def files
+      Dir.glob(File.join(@directory, "*.json"))
+    end
+
+    def capacity_for?(raw)
+      paths = files
+      return false if paths.length >= MAX_NOTICES
+
+      paths.sum { |path| file_size(path) } + raw.bytesize <= MAX_BYTES
+    end
+
+    def file_size(path)
+      File.size(path)
+    rescue Errno::ENOENT
+      0
+    end
+
+    def filename
+      format("%<time>020d-%<random>s.json", time: (@now.call.to_f * 1_000_000).to_i, random: SecureRandom.hex(8))
+    end
+
+    def with_directory_lock
+      File.open(File.join(@directory, ".lock"), File::WRONLY | File::CREAT, 0o600) do |lock|
+        lock.flock(File::LOCK_EX)
+        yield
+      end
+    end
+
+    def atomic_write(path, raw)
+      temporary = "#{path}.tmp-#{Process.pid}-#{SecureRandom.hex(4)}"
+      File.open(temporary, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+        file.write(raw)
+        file.flush
+        file.fsync
+      end
+      File.rename(temporary, path)
+    ensure
+      File.delete(temporary) if defined?(temporary) && File.exist?(temporary)
+    end
+
+    def parse(raw, path)
+      envelope = JSON.parse(raw)
+      return envelope if envelope.is_a?(Hash) && envelope["notice"].is_a?(Hash)
+
+      raise JSON::ParserError, "invalid envelope"
+    rescue JSON::ParserError, TypeError => e
+      quarantine(path)
+      @warn.call("raises quarantined corrupt spool entry: #{e.message}")
+      nil
+    end
+
+    def quarantine(path)
+      target = path.sub(/\.json\z/, ".corrupt")
+      File.rename(path, target)
+      File.chmod(0o600, target)
+    rescue Errno::ENOENT
+      nil
+    end
+  end
+end

data/lib/raises/subscriber.rb

@@ -6,9 +6,18 @@ require "uri"
 
 module Raises
   class Subscriber
+    def initialize
+      @spool = build_spool
+      @delivery = Delivery.new(post: method(:post), spool: @spool, warn: ->(message) { warn(message) })
+    end
+
+    def start = tap { @spool&.start }
+
     def report(error, handled:, severity:, context:, source: nil)
       return unless report?
 
+      start
+
       notice = {
         env: env_name,
         revision: revision,
@@ -22,13 +31,23 @@ module Raises
         request: request_from(context)
       }
 
-      post(notice)
+      @delivery.call(notice)
     rescue StandardError => e
       warn("raises subscriber failed: #{e.class}: #{e.message}")
     end
 
     private
 
+    def build_spool
+      directory = ENV["RAISES_SPOOL_DIR"].to_s
+      return if directory.empty?
+
+      Spool.new(directory, deliver: method(:post), warn: ->(message) { warn(message) })
+    rescue StandardError => e
+      warn("raises spool unavailable: #{e.class}: #{e.message}")
+      nil
+    end
+
     def report?
       return false if url.to_s.empty? || token.to_s.empty?
       return true if ENV["RAISES_REPORT"] == "1"
@@ -124,9 +143,7 @@ module Raises
       request["Content-Type"] = "application/json"
       request["User-Agent"] = "raises-ruby/#{Raises::VERSION}"
       request.body = JSON.generate(notice)
-      response = http.request(request)
-      warn("raises rejected notice: HTTP #{response.code}") unless response.is_a?(Net::HTTPSuccess)
-      response
+      http.request(request)
     end
 
     def timeout(name, fallback)

data/lib/raises/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Raises
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/raises.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require "raises/version"
+require "raises/spool_storage"
+require "raises/spool"
+require "raises/delivery"
 require "raises/subscriber"
 require "raises/railtie" if defined?(Rails::Railtie)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raises
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Clayton Lengel-Zigich
@@ -32,7 +32,10 @@ files:
 - LICENSE.txt
 - README.md
 - lib/raises.rb
+- lib/raises/delivery.rb
 - lib/raises/railtie.rb
+- lib/raises/spool.rb
+- lib/raises/spool_storage.rb
 - lib/raises/subscriber.rb
 - lib/raises/version.rb
 homepage: https://raises.dev