bugwatch-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 94f9c2ad3792e673573fa9fe2d517d4b9eb591fb2f1bacb18d231c41c7c46d9c
+  data.tar.gz: b1d6325a16b22c9b4770be9d9e1d49f2df71e1f7ce5462fbe94856f859467dbc
+SHA512:
+  metadata.gz: a2aec0365f97d36f3a4abce0ec72097b0f0b5ae5773e803cf950868885c9d5c7eb271555a0ebaf17151128ede1b67f708521ba7cfeddaeea15f6968402d8499e
+  data.tar.gz: 7547ca8e2cf31b869463bbdbafd75408a932bd5df955379ee5fe7c247f9ab06e4b7e38a14e87a4ba4cd68c1bf94f3fd9fe8e1d2019430b780f3a66a9f624a422

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ROOMY AI LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+# Bugwatch Ruby SDK
+
+Official Ruby SDK for Bugwatch error tracking. Stdlib only — zero runtime dependencies.
+
+## Install
+
+```ruby
+gem 'bugwatch-sdk', '~> 0.1'
+# or from source:
+gem 'bugwatch-sdk', github: 'roomylabs/bugwatch-ruby'
+```
+
+## Quick start
+
+```ruby
+require "bugwatch"
+
+Bugwatch.init(
+  "https://bw-YOUR_KEY@bugwatch-api.loadmindx.com/api/22",
+  environment: "production",
+  release: "1.0.0",
+)
+
+# Capture the active exception.
+begin
+  1 / 0
+rescue ZeroDivisionError => e
+  Bugwatch.capture_exception(e)
+end
+
+# Capture a message.
+Bugwatch.capture_message("Payment confirmed", level: "info")
+
+# Wait for async sends (short-lived scripts).
+Bugwatch.flush
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `init(dsn, environment:, release:, debug:, send_default_pii:, allow_http:)` | Initialize the SDK (HTTPS enforced; `allow_http` is dev-only) |
+| `capture_exception(exc = $!, level:, tags:, user:)` | Report an exception (defaults to `$!` inside rescue) |
+| `capture_message(message, level:, tags:, user:)` | Report a message (`debug info warning error fatal`) |
+| `configure_scope { \|scope\| ... }` | Set global tags / user / breadcrumbs / context |
+| `flush(timeout: 5.0)` | Wait for in-flight sends; returns `true` when done |
+
+## Scope
+
+```ruby
+Bugwatch.configure_scope do |scope|
+  scope.set_tag("tenant", "acme")
+  scope.set_user("id" => 42, "name" => "Grace")   # email/ip stripped (PII)
+  scope.add_breadcrumb("clicked checkout", category: "ui")
+end
+```
+
+## Rack middleware (Rails, Sinatra…)
+
+```ruby
+# config/application.rb (Rails) or `use Bugwatch::RackMiddleware` (Sinatra)
+require "bugwatch"
+config.middleware.insert_before 0, Bugwatch::RackMiddleware
+```
+
+Captures unhandled exceptions with request context (URL, method, headers — sensitive headers stripped).
+
+## Behavior
+
+- Sends are **async** (background threads, max 50 in flight); call `flush` in short-lived scripts
+- **HTTPS enforced** — `http://` DSNs raise unless `allow_http: true`
+- **PII stripped by default** — `email`, `username`, `ip_address` removed from user; `Cookie`/`Authorization` headers removed from request context
+- Breadcrumbs capped at 100; failures never crash the host app
+- DSN format: `https://<public_key>@<host>/api/<project_id>` (the project's ingest key — Settings → API keys)

data/lib/bugwatch/client.rb

@@ -0,0 +1,84 @@
+require "time"
+
+module Bugwatch
+  module Client
+    MAX_THREADS = 50
+
+    module_function
+
+    def payload(event_id:, level:, message:, culprit:, exception:, user:, tags:)
+      cfg = Bugwatch.config
+      scope = cfg[:scope].snapshot
+      p = {
+        "event_id" => event_id,
+        "timestamp" => Time.now.utc.iso8601,
+        "level" => level.to_s,
+        "message" => message,
+        "culprit" => culprit,
+        "environment" => cfg[:environment],
+        "release" => cfg[:release],
+        "platform" => "ruby",
+      }
+      p["exception"] = exception if exception
+      merged_user = user || scope[:user]
+      p["user"] = Dsn.strip_pii_user(merged_user) if merged_user
+      merged_tags = scope[:tags].merge(tags || {})
+      p["tags"] = merged_tags unless merged_tags.empty?
+      p["breadcrumbs"] = scope[:breadcrumbs] unless scope[:breadcrumbs].empty?
+      req = scope[:context]["request"]
+      if req
+        req = cfg[:send_default_pii] ? req : Dsn.strip_pii_request(req)
+        p["request"] = req
+      end
+      p
+    end
+
+    def send(payload)
+      cfg = Bugwatch.config
+      thread = Thread.new do
+        post(cfg[:store_url], cfg[:public_key], payload)
+      end
+      thread.report_on_exception = false
+      pool << thread
+      prune_pool
+      true
+    end
+
+    def flush(timeout = 5.0)
+      deadline = Time.now + timeout
+      pool.dup.each { |t| t.join([0.01, deadline - Time.now].max) while Time.now < deadline && !t.join(0.05) }
+      pool.dup.each(&:join) if Time.now < deadline
+      pool.clear
+      true
+    end
+
+    def pool
+      @pool ||= []
+    end
+
+    def prune_pool
+      pool.reject! { |t| !t.alive? }
+      pool.shift while pool.size > MAX_THREADS
+    end
+
+    def post(store_url, public_key, payload)
+      uri = URI.parse(store_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 5
+      http.read_timeout = 5
+      req = Net::HTTP::Post.new(uri.request_uri)
+      req["Content-Type"] = "application/json"
+      req["X-Bugwatch-Key"] = public_key
+      req["User-Agent"] = USER_AGENT
+      req.body = JSON.generate(payload)
+      http.request(req)
+    rescue StandardError => e
+      warn("bugwatch: send failed: #{e.message}") if Bugwatch.config[:debug]
+    end
+
+    def warn(msg)
+      $stderr.puts(msg)
+    end
+  end
+end

data/lib/bugwatch/dsn.rb

@@ -0,0 +1,69 @@
+module Bugwatch
+  module Dsn
+    PII_KEYS = %w[email username ip_address ip].freeze
+    SENSITIVE_HEADERS = %w[cookie authorization x-bugwatch-key set-cookie].freeze
+
+    module_function
+
+    def parse(dsn, allow_http: false)
+      raise Error, "DSN must be a non-empty string" unless dsn.is_a?(String) && !dsn.strip.empty?
+      uri = URI.parse(dsn.strip)
+      unless %w[http https].include?(uri.scheme)
+        raise Error, "Invalid DSN scheme: expected https (got #{uri.scheme.inspect})"
+      end
+      if uri.scheme == "http" && !allow_http
+        raise Error, "HTTP DSN refused. Use https:// (allow_http=True is dev-only)"
+      end
+      raise Error, "DSN missing public key before '@'" unless uri.userinfo && !uri.userinfo.empty?
+      raise Error, "DSN missing host" unless uri.host
+      segments = uri.path.split("/").reject(&:empty?)
+      project_id =
+        if segments.size >= 2 && segments[0].downcase == "api"
+          segments[1]
+        else
+          segments[0]
+        end
+      raise Error, "DSN missing project_id in path" if project_id.nil? || project_id.empty?
+      base = "#{uri.scheme}://#{uri.host}#{uri.port == uri.default_port ? '' : ":#{uri.port}"}"
+      { public_key: uri.userinfo, base_url: base, project_id: project_id,
+        store_url: "#{base}/api/#{project_id}/store/" }
+    rescue URI::InvalidURIError, URI::Error
+      raise Error, "Invalid DSN: #{dsn.inspect}"
+    end
+
+    def exception_payload(exc)
+      return nil unless exc
+      frames = (exc.backtrace || []).first(50).map do |line|
+        file, lineno, fn = line.split(":", 3)
+        { "filename" => file.to_s, "lineno" => (lineno.to_i rescue 0),
+          "function" => (fn ? fn.split(":in ").last.to_s : nil) }.compact
+      end
+      { "type" => exc.class.name.to_s, "value" => exc.message.to_s,
+        "stacktrace" => { "frames" => frames } }
+    end
+
+    def culprit_from(exc)
+      first = (exc.backtrace || []).first
+      return nil unless first
+      file, lineno, = first.split(":", 3)
+      "#{File.basename(file.to_s)}:#{lineno}"
+    rescue StandardError
+      nil
+    end
+
+    def strip_pii_user(user)
+      return nil unless user.is_a?(Hash)
+      user.reject { |k, _| PII_KEYS.include?(k.to_s.downcase) }
+    end
+
+    def strip_pii_request(req)
+      return req unless req.is_a?(Hash)
+      out = req.dup
+      headers = out["headers"]
+      if headers.is_a?(Hash)
+        out["headers"] = headers.reject { |k, _| SENSITIVE_HEADERS.include?(k.to_s.downcase) }
+      end
+      out
+    end
+  end
+end

data/lib/bugwatch/integration.rb

@@ -0,0 +1,28 @@
+module Bugwatch
+  # Rack middleware: captures unhandled exceptions from any Rack app
+  # (Rails, Sinatra, etc.) and reports them to Bugwatch.
+  class RackMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      @app.call(env)
+    rescue Exception => e
+      begin
+        scope = Bugwatch.initialized? ? Bugwatch.config[:scope] : nil
+        if scope
+          scope.set_context("request" => {
+            "url" => "#{env['rack.url_scheme']}://#{env['HTTP_HOST']}#{env['REQUEST_PATH']}",
+            "method" => env["REQUEST_METHOD"],
+            "headers" => env.select { |k, _| k.to_s.start_with?("HTTP_") },
+          })
+        end
+        Bugwatch.capture_exception(e)
+      ensure
+        scope&.set_context("request" => nil)
+        raise e
+      end
+    end
+  end
+end

data/lib/bugwatch/version.rb

@@ -0,0 +1,4 @@
+module Bugwatch
+  VERSION = "0.1.0".freeze
+  USER_AGENT = "Bugwatch-Ruby/#{VERSION}".freeze
+end

data/lib/bugwatch.rb

@@ -0,0 +1,121 @@
+require "json"
+require "net/http"
+require "uri"
+require "securerandom"
+require "thread"
+
+require_relative "bugwatch/version"
+require_relative "bugwatch/dsn"
+require_relative "bugwatch/client"
+require_relative "bugwatch/integration"
+
+module Bugwatch
+  class Error < StandardError; end
+
+  LEVELS = %w[debug info warning error fatal].freeze
+  DEFAULT_LEVEL = "error"
+
+  class << self
+    def init(dsn, environment: "production", release: nil, debug: false,
+             send_default_pii: false, allow_http: false)
+      cfg = Dsn.parse(dsn, allow_http: allow_http)
+      @config = {
+        store_url: cfg[:store_url], public_key: cfg[:public_key],
+        project_id: cfg[:project_id], environment: environment.to_s,
+        release: release, debug: !!debug, send_default_pii: !!send_default_pii,
+        scope: Scope.new
+      }
+      true
+    end
+
+    def config
+      @config or raise Error, "Bugwatch.init must be called before use"
+    end
+
+    def initialized?
+      !!@config
+    end
+
+    def capture_exception(exc = $!, level: DEFAULT_LEVEL, tags: nil, user: nil)
+      return nil unless initialized?
+      exc ||= $ERROR_INFO
+      return nil unless exc.is_a?(Exception)
+      event_id = SecureRandom.uuid.delete("-")
+      payload = Client.payload(
+        event_id: event_id, level: level, message: "#{exc.class}: #{exc.message}",
+        culprit: Dsn.culprit_from(exc),
+        exception: Dsn.exception_payload(exc),
+        user: user, tags: tags
+      )
+      Client.send(payload)
+      event_id
+    end
+
+    def capture_message(message, level: "info", tags: nil, user: nil)
+      return nil unless initialized?
+      event_id = SecureRandom.uuid.delete("-")
+      payload = Client.payload(
+        event_id: event_id, level: level, message: message.to_s,
+        culprit: nil, exception: nil, user: user, tags: tags
+      )
+      Client.send(payload)
+      event_id
+    end
+
+    def configure_scope
+      yield config[:scope] if block_given?
+    end
+
+    def flush(timeout: 5.0)
+      Client.flush(timeout)
+    end
+  end
+
+  class Scope
+    attr_reader :tags, :user, :breadcrumbs, :context
+
+    def initialize
+      @tags = {}
+      @user = nil
+      @breadcrumbs = []
+      @context = {}
+      @lock = Mutex.new
+    end
+
+    def set_user(user)
+      @lock.synchronize { @user = Dsn.strip_pii_user(user) }
+    end
+
+    def set_tag(key, value)
+      @lock.synchronize { @tags[key.to_s] = value.to_s }
+    end
+
+    def set_context(context)
+      @lock.synchronize { @context.merge!(context) }
+    end
+
+    def add_breadcrumb(message, category: nil, level: "info", data: nil)
+      crumb = { "timestamp" => Time.now.utc.iso8601, "message" => message.to_s,
+                "level" => level.to_s }
+      crumb["category"] = category if category
+      crumb["data"] = data if data
+      @lock.synchronize do
+        @breadcrumbs << crumb
+        @breadcrumbs.shift if @breadcrumbs.size > 100
+      end
+    end
+
+    def snapshot
+      @lock.synchronize do
+        { tags: @tags.dup, user: @user && @user.dup,
+          breadcrumbs: @breadcrumbs.map(&:dup), context: deep_dup(@context) }
+      end
+    end
+
+    private
+
+    def deep_dup(h)
+      h.each_with_object({}) { |(k, v), acc| acc[k] = v.is_a?(Hash) ? deep_dup(v) : v }
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: bugwatch-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ROOMY AI LLC
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Capture exceptions and messages from Ruby apps to Bugwatch. Stdlib only.
+email:
+- billing@roomylabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/bugwatch.rb
+- lib/bugwatch/client.rb
+- lib/bugwatch/dsn.rb
+- lib/bugwatch/integration.rb
+- lib/bugwatch/version.rb
+homepage: https://bugwatch.roomylabs.com
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+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: 3.4.20
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for Bugwatch error tracking
+test_files: []