raises 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd2351828d8eeb04e0af96c88322c369dcd2ecd158384d7e80543cede4153646
-  data.tar.gz: 85e43d1fa7d393159c8bb54fc99898863fc5afd7369f680486e8947d74412c1a
+  metadata.gz: 826d161b194d0bb9f3d3b1e00f3326dc986da4efb420e9ae1c8ff0dccf59708e
+  data.tar.gz: b0b9b1dbe0e03571e0585c6982e59091495337e14118765a0ff1274427a1b956
 SHA512:
-  metadata.gz: f10b1aa6748ccf6848f9b2ceccb479c1d4a6182b44350318cffd93bab4e70f152613fe66520c1c6cc9d600e912b36eb0abc4ba4b5e0072cca6356e6cdf8676ba
-  data.tar.gz: 5ba3f6610cce1de92879f3599180d630e38b8183a5ea357ad1e1b9e8d918d7199fdf48bda4fedf9152f93492fec65c576db6404779160d85d2e8cba1413bb532
+  metadata.gz: ee447f476885abbda2516cbe5b92600b824b879507954f23c8f276225adb718f78652f2cc53bf79e1bf55fe11a6203bad9519b4adffbbcb64e4eae20ca9b653a
+  data.tar.gz: 15d056b1826db28175a104359215f1a3eebd7497358a8c260057b0811e5a3758bef330c9412372393f7de077a81ea7741bcd8a82a20a9e0f2a0e0898c14c6098

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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`.

data/README.md

@@ -8,8 +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 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.
+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

@@ -10,33 +10,36 @@ module Raises
       @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)
+    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)
 
-      handle_response(notice, response.code.to_i)
-      response
+      response_accepted?(item, response.code.to_i)
     rescue StandardError => e
-      handle_exception(notice, e)
-      nil
+      exception_accepted?(item || { "path" => path, "payload" => payload }, e)
     end
 
     private
 
-    def handle_response(notice, status)
-      if retryable_status?(status) && @spool&.enqueue(notice)
+    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 handle_exception(notice, error)
-      if @spool&.enqueue(notice)
+    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
 

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.start)
+      Rails.error.subscribe(Raises.subscriber)
     end
   end
 end

data/lib/raises/spool.rb

@@ -38,8 +38,8 @@ module Raises
       thread&.join(1)
     end
 
-    def enqueue(notice)
-      accepted = @storage.store(notice) == :stored
+    def enqueue(item)
+      accepted = @storage.store(item) == :stored
       if accepted
         start if @start_on_enqueue
         wake if @start_on_enqueue
@@ -69,7 +69,7 @@ module Raises
     end
 
     def deliver(path, envelope)
-      response = @deliver.call(envelope.fetch("notice"))
+      response = @deliver.call(envelope.fetch("path"), envelope.fetch("payload"))
       status = response_code(response)
       if status.between?(200, 299)
         @storage.delete(path)

data/lib/raises/spool_storage.rb

@@ -16,9 +16,15 @@ module Raises
       prepare
     end
 
-    def store(notice)
+    def store(item)
       prepare
-      raw = JSON.generate("version" => 1, "attempts" => 0, "next_attempt_at" => @now.call.to_f, "notice" => notice)
+      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)
 
@@ -107,7 +113,14 @@ module Raises
 
     def parse(raw, path)
       envelope = JSON.parse(raw)
-      return envelope if envelope.is_a?(Hash) && envelope["notice"].is_a?(Hash)
+      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

data/lib/raises/subscriber.rb

@@ -5,6 +5,8 @@ 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
@@ -31,13 +33,45 @@ module Raises
         request: request_from(context)
       }
 
-      @delivery.call(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?
@@ -132,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)
@@ -142,7 +176,7 @@ module Raises
       request["Authorization"] = "Bearer #{token}"
       request["Content-Type"] = "application/json"
       request["User-Agent"] = "raises-ruby/#{Raises::VERSION}"
-      request.body = JSON.generate(notice)
+      request.body = JSON.generate(payload)
       http.request(request)
     end
 
@@ -153,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.2.0"
+  VERSION = "0.3.0"
 end

data/lib/raises.rb

@@ -8,4 +8,13 @@ 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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Clayton Lengel-Zigich