raises 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf7a8c31ce5ed40e110b57671dee77d76cc712059ba386c64fed29f3e9da31ad
-  data.tar.gz: 12e7e56ce32e4c3cbeea11912f7de8e765ee0cf44636a99bd963e8b2796c510f
+  metadata.gz: 826d161b194d0bb9f3d3b1e00f3326dc986da4efb420e9ae1c8ff0dccf59708e
+  data.tar.gz: b0b9b1dbe0e03571e0585c6982e59091495337e14118765a0ff1274427a1b956
 SHA512:
-  metadata.gz: 3ca5937ee49e66bafd8c7dc6d25ca55999d35ebc2f336f75d9206f3a1dccc4570b70c62f4d3169021b305d790941586df216ade5d4257c090b8c9223b09a7f1f
-  data.tar.gz: 95e0bac19718d9f1f0ab67856425c31180f7207c72e0e2fc1cb64d0727c3c446a1cf7dcbaf9adfa33c7c00f8c446b64f7563d58a1cb70af899008b1d90cb256f
+  metadata.gz: ee447f476885abbda2516cbe5b92600b824b879507954f23c8f276225adb718f78652f2cc53bf79e1bf55fe11a6203bad9519b4adffbbcb64e4eae20ca9b653a
+  data.tar.gz: 15d056b1826db28175a104359215f1a3eebd7497358a8c260057b0811e5a3758bef330c9412372393f7de077a81ea7741bcd8a82a20a9e0f2a0e0898c14c6098

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.3.0
+
+- Add `Raises.notify` for informational, warning, and error-level events.
+- Preserve event and exception routes in the optional disk spool.
+- Keep informational events separate from exception grouping and GitHub issues.
+
+## 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

@@ -8,6 +8,21 @@ gem "raises"
 
 Set `RAISES_TOKEN` to the ingestion credential created for the project. Production errors are reported to `https://raises.dev` automatically through `Rails.error`. Set `RAISES_REPORT=1` to exercise the integration outside production.
 
+Send a one-off operational notice without raising an exception:
+
+```ruby
+Raises.notify(
+  "Import finished",
+  level: :info,
+  source: "nightly-import",
+  context: { imported: 412, skipped: 3 }
+)
+```
+
+Valid levels are `:info`, `:warning`, and `:error`. Notices are retained and delivered to configured outbound integrations, but they do not create error groups, acknowledgements, or GitHub issues.
+
 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 payloads should survive a deploy. Raises stores event or exception 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 payloads 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,50 @@
+# 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(payload, path: "v1/notices")
+      item = { "path" => path, "payload" => payload }
+      response = @post.call(path, payload)
+      return true unless response.respond_to?(:code)
+      return true if response.is_a?(Net::HTTPSuccess) || response.code.to_i.between?(200, 299)
+
+      response_accepted?(item, response.code.to_i)
+    rescue StandardError => e
+      exception_accepted?(item || { "path" => path, "payload" => payload }, e)
+    end
+
+    private
+
+    def response_accepted?(item, status)
+      if retryable_status?(status) && @spool&.enqueue(item)
+        @warn.call("raises queued notice after HTTP #{status}")
+        true
+      else
+        @warn.call("raises rejected notice: HTTP #{status}")
+        false
+      end
+    end
+
+    def exception_accepted?(item, error)
+      if @spool&.enqueue(item)
+        @warn.call("raises queued notice after #{error.class}")
+        true
+      else
+        @warn.call("raises subscriber failed: #{error.class}: #{error.message}")
+        false
+      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)
     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(item)
+      accepted = @storage.store(item) == :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("path"), envelope.fetch("payload"))
+      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,140 @@
+# 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(item)
+      prepare
+      raw = JSON.generate(
+        "version" => 2,
+        "attempts" => 0,
+        "next_attempt_at" => @now.call.to_f,
+        "path" => item.fetch("path"),
+        "payload" => item.fetch("payload")
+      )
+      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["path"].is_a?(String) && envelope["payload"].is_a?(Hash)
+
+      if envelope.is_a?(Hash) && envelope["notice"].is_a?(Hash)
+        envelope["version"] = 2
+        envelope["path"] = "v1/notices"
+        envelope["payload"] = envelope.delete("notice")
+        return envelope
+      end
+
+      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

@@ -5,10 +5,21 @@ require "net/http"
 require "uri"
 
 module Raises
+  # Rails.error integration and explicit application notices share one delivery path.
+  # rubocop:disable Metrics/ClassLength
   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 +33,55 @@ module Raises
         request: request_from(context)
       }
 
-      post(notice)
+      @delivery.call(notice, path: "v1/notices")
     rescue StandardError => e
       warn("raises subscriber failed: #{e.class}: #{e.message}")
+      false
+    end
+
+    def notify(message, level: :info, context: {}, source: nil)
+      message = message.to_s.strip
+      level = level.to_s
+      validate_event!(message, level, context, source)
+      return false unless report?
+
+      start
+      event = {
+        env: env_name,
+        revision: revision,
+        level: level,
+        message: message,
+        source: source,
+        context: json_safe(context)
+      }
+      @delivery.call(event, path: "v1/events")
+    rescue ArgumentError
+      raise
+    rescue StandardError => e
+      warn("raises notify failed: #{e.class}: #{e.message}")
+      false
     end
 
     private
 
+    def validate_event!(message, level, context, source)
+      raise ArgumentError, "message is required" if message.empty?
+      raise ArgumentError, "message is too long" if message.length > 2_000
+      raise ArgumentError, "level must be info, warning, or error" unless %w[info warning error].include?(level)
+      raise ArgumentError, "source is too long" if source.to_s.length > 120
+      raise ArgumentError, "context must be a hash" unless context.respond_to?(:each_pair)
+    end
+
+    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"
@@ -113,8 +166,8 @@ module Raises
       end
     end
 
-    def post(notice)
-      uri = URI.join(url.end_with?("/") ? url : "#{url}/", "v1/notices")
+    def post(path, payload)
+      uri = URI.join(url.end_with?("/") ? url : "#{url}/", path)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == "https"
       http.open_timeout = timeout("RAISES_OPEN_TIMEOUT", 1)
@@ -123,10 +176,8 @@ module Raises
       request["Authorization"] = "Bearer #{token}"
       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
+      request.body = JSON.generate(payload)
+      http.request(request)
     end
 
     def timeout(name, fallback)
@@ -136,4 +187,5 @@ module Raises
       fallback
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/raises/version.rb

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

data/lib/raises.rb

@@ -1,8 +1,20 @@
 # 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)
 
 module Raises
+  class << self
+    def notify(message, level: :info, context: {}, source: nil)
+      subscriber.notify(message, level: level, context: context, source: source)
+    end
+
+    def subscriber
+      @subscriber ||= Subscriber.new.start
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raises
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.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