snare-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bae212201b35791154f89443bdc6f115fd6e51bdf77c4b5fc66b1d8b525c762a
+  data.tar.gz: e9849e728c5dd643d299d131f06d496927fe771c2ffe65786dd9b88f323d35b9
+SHA512:
+  metadata.gz: a0ddb5a5f715e53209f855a6795203f5f5c13973538d0f652154cadcd78122ef0a01793f25d52c1dd1f7937ef78c4591ddd143d2e5afe84f2039494d20dd822b
+  data.tar.gz: 5c46bdeab23cce0c8a572ec25af2d0d56936402b218d248a5aaab0af3a58c7a0feeed7e6095518f0c316ce46d9831a3c5c12580b162ec1b0fdcb7dbb6392ca47

data/README.md

@@ -0,0 +1,68 @@
+# snare-sdk
+
+Ruby SDK for [Snare](https://snare.dev) — captures unhandled exceptions and
+manually-reported errors, batches them, and reports them to your Snare
+project.
+
+## Install
+
+Not yet published to RubyGems. In this repo, add to a `Gemfile`:
+
+```ruby
+gem "snare-sdk", path: "packages/sdk-ruby"
+```
+
+## Usage
+
+```ruby
+require "snare"
+
+Snare.init(project_id: "proj_abc123", api_key: "snare_sdk_...", api_base: "https://intake.snare.dev")
+
+begin
+  risky_call
+rescue => e
+  Snare.capture_exception(e)
+end
+```
+
+- `Snare.init(project_id:, api_key:, api_base: "https://intake.snare.dev")`
+  registers crash-capture handling and starts the batching queue. Safe to
+  call more than once — each call re-initializes cleanly.
+- `Snare.capture_exception(exception)` reports an exception from your own
+  `rescue` blocks. `exception` defaults to `$!`, so it can also be called
+  bare from inside a live `rescue` block: `rescue => e; Snare.capture_exception; end`.
+- `Snare.flush` forces immediate delivery of whatever is currently queued —
+  useful in a graceful-shutdown hook.
+
+Events are batched and flushed after 5 events are queued, or 10 seconds
+after the oldest queued event, whichever comes first. Delivery is
+best-effort and silent: a dropped batch (network error, timeout, non-2xx
+response) never raises into your application.
+
+## Known limitation: background threads
+
+Unhandled exceptions are captured via an `at_exit` hook that checks `$!`,
+the same approach Sentry's own Ruby SDK uses. This only catches exceptions
+that propagate all the way to the top of the **main** thread.
+
+It will **not** automatically catch an exception that kills a background
+`Thread` — Ruby raises those silently by default (unless
+`Thread.report_on_exception` is set), and there's no clean, generic hook to
+intercept them. If you spawn background threads and want their exceptions
+reported, call `Snare.capture_exception` yourself inside a `rescue` in that
+thread's body.
+
+## Development
+
+```
+ruby packages/sdk-ruby/verify_capture.rb
+```
+
+runs the verify script — every line should print `PASS`.
+
+## Non-goals (v1)
+
+Publishing to RubyGems; Rails-specific middleware/railtie integration;
+automatically capturing exceptions that kill background threads;
+console/log capture.

data/lib/snare/capture.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Snare
+  # Pure event-building logic — mirrors packages/sdk/src/capture.ts. Kept free
+  # of any I/O so it's testable without a live queue/transport.
+  module Capture
+    PLATFORM = "ruby"
+
+    # Must stay in sync with services/intake/src/routes/telemetry.ts's
+    # capturedEventSchema (message.max(2000), stack.max(20_000)) — the server
+    # rejects the ENTIRE batch with a 400 if any single event exceeds these
+    # caps, and the transport never inspects the response status, so an
+    # un-truncated field here means silently dropped error reports.
+    MESSAGE_MAX_LENGTH = 2000
+    STACK_MAX_LENGTH = 20_000
+
+    module_function
+
+    # Per the wire protocol (docs/snare-multi-language-sdk-wire-protocol.md,
+    # Section 1): no url/userAgent keys for non-browser platforms, platform
+    # is always the literal "ruby", and consoleLog is a required key (nil is
+    # fine — console/log capture is optional for v1).
+    def build_captured_event(exception:, now:, console_log: nil)
+      event = {
+        message: exception.message.to_s[0, MESSAGE_MAX_LENGTH],
+        timestamp: now,
+        console_log: console_log,
+        platform: PLATFORM,
+      }
+
+      stack = exception.backtrace&.join("\n")
+      event[:stack] = stack[0, STACK_MAX_LENGTH] if stack
+
+      event
+    end
+  end
+end

data/lib/snare/queue.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Snare
+  # A small, dependency-free, thread-safe batching queue — mirrors
+  # packages/sdk/src/queue.ts. Flushes on flush_size events queued, or
+  # flush_interval seconds elapsed since the OLDEST queued event (the timer
+  # is armed once, when the queue transitions from empty to non-empty, and
+  # cancelled whenever the queue empties out).
+  #
+  # Unlike the JS SDK's single-threaded browser environment, Ruby apps
+  # (Rails, Sidekiq workers) are commonly multi-threaded, so every mutation
+  # of the internal array is guarded by a Mutex.
+  class Queue
+    def initialize(flush_size:, flush_interval:, &on_flush)
+      @flush_size = flush_size
+      @flush_interval = flush_interval
+      @on_flush = on_flush
+      @mutex = Mutex.new
+      @queue = []
+      @timer_thread = nil
+    end
+
+    def enqueue(event)
+      batch = nil
+      @mutex.synchronize do
+        @queue << event
+        start_timer if @queue.length == 1
+        batch = take_and_clear if @queue.length >= @flush_size
+      end
+      @on_flush.call(batch) if batch
+    end
+
+    # Forces a flush now (calls on_flush) if anything is queued. A no-op on
+    # an empty queue.
+    def flush
+      batch = @mutex.synchronize { take_and_clear if @queue.any? }
+      @on_flush.call(batch) if batch
+    end
+
+    # Clears the queue and cancels the pending timer WITHOUT calling
+    # on_flush — for callers that want to deliver the drained events
+    # themselves via a different path.
+    def drain
+      @mutex.synchronize { take_and_clear }
+    end
+
+    private
+
+    # Must be called while holding @mutex.
+    def take_and_clear
+      batch = @queue
+      @queue = []
+      cancel_timer
+      batch
+    end
+
+    def start_timer
+      @timer_thread = Thread.new do
+        sleep @flush_interval
+        flush
+      end
+    end
+
+    # Must be called while holding @mutex. Never kills the current thread —
+    # when the timer thread's own sleep completes and it calls flush(),
+    # cancel_timer runs on that same thread; Thread#kill on the thread
+    # executing it terminates immediately and would never return control to
+    # flush()'s caller.
+    def cancel_timer
+      @timer_thread.kill if @timer_thread && @timer_thread != Thread.current
+      @timer_thread = nil
+    end
+  end
+end

data/lib/snare/transport.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Snare
+  # HTTP delivery — mirrors packages/sdk/src/transport.ts. The API key rides
+  # in the JSON body, never a header (docs/snare-multi-language-sdk-wire-protocol.md,
+  # Section 1) — every language SDK follows the same envelope regardless of
+  # what's idiomatic for that language's HTTP client.
+  module Transport
+    module_function
+
+    # Never raises into the host application — network errors, timeouts, and
+    # non-2xx responses are all best-effort, silent failures. A dropped
+    # telemetry batch must never surface as an error in the host app.
+    def send_batch(api_base:, project_id:, api_key:, events:)
+      return if events.empty?
+
+      uri = URI.parse("#{api_base.chomp("/")}/telemetry/#{project_id}/events")
+      body = JSON.generate(build_body(api_key, events))
+
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 5, read_timeout: 5) do |http|
+        request = Net::HTTP::Post.new(uri.request_uri, { "content-type" => "application/json" })
+        request.body = body
+        http.request(request)
+      end
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def build_body(api_key, events)
+      { apiKey: api_key, events: events.map { |event| to_wire_format(event) } }
+    end
+
+    # Converts an internal (snake_case) event hash to the fixed camelCase
+    # wire shape (docs/snare-multi-language-sdk-wire-protocol.md, Section 1).
+    def to_wire_format(event)
+      wire = {
+        message: event[:message],
+        timestamp: event[:timestamp],
+        consoleLog: event[:console_log],
+        platform: event[:platform],
+      }
+      wire[:stack] = event[:stack] if event.key?(:stack)
+      wire
+    end
+  end
+end

data/lib/snare.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "snare/capture"
+require "snare/queue"
+require "snare/transport"
+
+# Snare error-monitoring SDK. See README.md for usage.
+module Snare
+  DEFAULT_API_BASE = "https://intake.snare.dev"
+  FLUSH_SIZE = 5
+  FLUSH_INTERVAL_SECONDS = 10
+
+  class << self
+    # Registers the at_exit crash-capture handler and starts the batching
+    # queue. Keyword arguments, idiomatic Ruby. Safe to call more than once —
+    # each call re-initializes cleanly, discarding anything queued under the
+    # previous configuration rather than flushing it to stale settings.
+    def init(project_id:, api_key:, api_base: DEFAULT_API_BASE)
+      @project_id = project_id
+      @api_key = api_key
+      @api_base = api_base
+
+      @queue&.drain
+
+      @queue = Snare::Queue.new(flush_size: FLUSH_SIZE, flush_interval: FLUSH_INTERVAL_SECONDS) do |events|
+        Snare::Transport.send_batch(api_base: @api_base, project_id: @project_id, api_key: @api_key, events: events)
+      end
+
+      register_at_exit_hook
+      nil
+    end
+
+    # For the host app's own rescue blocks. `exception` defaults to `$!` (the
+    # exception actively propagating in a live rescue block) so this can also
+    # be called bare from inside one — a nice-to-have since Ruby has no
+    # equivalent of Python's ambient sys.exc_info() idiom.
+    def capture_exception(exception = $!)
+      unless @queue
+        warn "[snare-sdk] Snare.capture_exception called before Snare.init"
+        return nil
+      end
+      unless exception
+        warn "[snare-sdk] Snare.capture_exception called with no exception and no active $!"
+        return nil
+      end
+
+      @queue.enqueue(Snare::Capture.build_captured_event(exception: exception, now: (Time.now.to_f * 1000).to_i))
+      nil
+    end
+
+    # Forces immediate delivery of whatever is queued. Used by the at_exit
+    # hook (at_exit runs right before process death — a background timer
+    # can't be relied on to fire after that point) and available for a host
+    # app to call explicitly, e.g. in a graceful-shutdown handler.
+    def flush
+      @queue&.flush
+      nil
+    end
+
+    private
+
+    # Ruby has no global hook as clean as Python's sys.excepthook. `at_exit`
+    # checking `$!` (set during an abnormal exit) is the standard approach —
+    # the same one Sentry's own Ruby SDK uses. This only catches exceptions
+    # that propagate to the top of the MAIN thread: Ruby raises an exception
+    # that kills a background Thread silently by default (unless
+    # Thread.report_on_exception is set), with no clean generic hook to
+    # intercept it — an explicitly documented gap for v1, see README.md.
+    def register_at_exit_hook
+      return if @at_exit_registered
+
+      @at_exit_registered = true
+      at_exit do
+        if $!
+          capture_exception($!)
+          flush
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,42 @@
+--- !ruby/object:Gem::Specification
+name: snare-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Snare
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Captures unhandled exceptions and manually-reported errors and reports
+  them to Snare (https://snare.dev).
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/snare.rb
+- lib/snare/capture.rb
+- lib/snare/queue.rb
+- lib/snare/transport.rb
+licenses: []
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Snare error-monitoring SDK for Ruby
+test_files: []