debugbundle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 57ff4962fe1910ae27c974401d207da7c6a1afc1d22f9a5951b93d4c338f1f65
+  data.tar.gz: cb7d91a8088df973a7a4b344c79799e348fb0cbccc0544eac5f898c458bb931b
+SHA512:
+  metadata.gz: 1eaccc22806e5bf4844d7a1820c52f67add73f63025f5023f664570ac64b4fb6ba46e62faeb2d6a8380c95bd7e1c7efd469cfbba4bb4de81613a4b4476305e40
+  data.tar.gz: 55ab0c5a6f38b356ad6a49d580fcf95ac68075f3d9633aabb136c70cd9c8d5f9908a0a38a83eb162cd1387d3ce4ca3edb979bb4b727430306facfda3dd50c145

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'json_schemer', '~> 2.4'
+  gem 'rack-test', '~> 2.1'
+  gem 'rails', '~> 7.1'
+  gem 'rake', '~> 13.2'
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.76', require: false
+  gem 'sidekiq', '~> 7.0', require: false
+  gem 'simplecov', '~> 0.22', require: false
+  gem 'webmock', '~> 3.25'
+end

data/Makefile

@@ -0,0 +1,43 @@
+SHELL := /bin/sh
+
+RUBY_IMAGE ?= ruby:3.4.2
+WORKDIR := /workspace
+BUNDLE_GEMFILE ?= Gemfile
+
+DOCKER_RUN = docker run --rm -t \
+	-v "$(PWD):$(WORKDIR)" \
+	-w "$(WORKDIR)" \
+	$(RUBY_IMAGE)
+
+BUNDLE_ENV = BUNDLE_GEMFILE="$(BUNDLE_GEMFILE)"
+
+.PHONY: bundle-install test lint build shell compat-rack compat-rails compat-sidekiq compat
+
+bundle-install:
+	$(DOCKER_RUN) sh -lc "$(BUNDLE_ENV) bundle config set path vendor/bundle && $(BUNDLE_ENV) bundle install"
+
+test:
+	$(DOCKER_RUN) sh -lc "$(BUNDLE_ENV) bundle config set path vendor/bundle && $(BUNDLE_ENV) bundle install && $(BUNDLE_ENV) bundle exec rspec"
+
+lint:
+	$(DOCKER_RUN) sh -lc "$(BUNDLE_ENV) bundle config set path vendor/bundle && $(BUNDLE_ENV) bundle install && $(BUNDLE_ENV) bundle exec rubocop"
+
+build:
+	$(DOCKER_RUN) sh -lc "$(BUNDLE_ENV) bundle config set path vendor/bundle && $(BUNDLE_ENV) bundle install && gem build debugbundle.gemspec"
+
+compat-rack:
+	docker run --rm -t -v "$(PWD):$(WORKDIR)" -w "$(WORKDIR)" ruby:3.1.6 sh -lc 'SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rack_2_2.gemfile" bundle config set path vendor/bundle && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rack_2_2.gemfile" bundle install && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rack_2_2.gemfile" bundle exec rspec spec/rack_integration_spec.rb spec/rack_middleware_spec.rb spec/relay_spec.rb'
+	docker run --rm -t -v "$(PWD):$(WORKDIR)" -w "$(WORKDIR)" ruby:3.4.2 sh -lc 'SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rack_3.gemfile" bundle config set path vendor/bundle && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rack_3.gemfile" bundle install && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rack_3.gemfile" bundle exec rspec spec/rack_integration_spec.rb spec/rack_middleware_spec.rb spec/relay_spec.rb'
+
+compat-rails:
+	docker run --rm -t -v "$(PWD):$(WORKDIR)" -w "$(WORKDIR)" ruby:3.1.6 sh -lc 'SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rails_7_0.gemfile" bundle config set path vendor/bundle && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rails_7_0.gemfile" bundle install && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rails_7_0.gemfile" bundle exec rspec spec/rails_relay_spec.rb spec/rails_railtie_spec.rb'
+	docker run --rm -t -v "$(PWD):$(WORKDIR)" -w "$(WORKDIR)" ruby:3.4.2 sh -lc 'SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rails_7_1.gemfile" bundle config set path vendor/bundle && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rails_7_1.gemfile" bundle install && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/rails_7_1.gemfile" bundle exec rspec spec/rails_relay_spec.rb spec/rails_railtie_spec.rb'
+
+compat-sidekiq:
+	docker run --rm -t -v "$(PWD):$(WORKDIR)" -w "$(WORKDIR)" ruby:3.2 sh -lc 'SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/sidekiq_7.gemfile" bundle config set path vendor/bundle && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/sidekiq_7.gemfile" bundle install && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/sidekiq_7.gemfile" bundle exec rspec spec/sidekiq_middleware_spec.rb spec/sidekiq_integration_spec.rb'
+	docker run --rm -t -v "$(PWD):$(WORKDIR)" -w "$(WORKDIR)" ruby:3.4.2 sh -lc 'SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/sidekiq_8.gemfile" bundle config set path vendor/bundle && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/sidekiq_8.gemfile" bundle install && SIMPLECOV_MINIMUM_COVERAGE=0 BUNDLE_GEMFILE="gemfiles/sidekiq_8.gemfile" bundle exec rspec spec/sidekiq_middleware_spec.rb spec/sidekiq_integration_spec.rb'
+
+compat: compat-rack compat-rails compat-sidekiq
+
+shell:
+	$(DOCKER_RUN) sh

data/README.md

@@ -0,0 +1,168 @@
+# debugbundle
+
+Ruby SDK for DebugBundle.
+
+Use this gem to capture Ruby backend exceptions, request metadata, structured logs, runtime context, probe data, and browser relay traffic. It supports a singleton facade plus instance clients for Rack, Rails, Sidekiq, and explicit Ruby instrumentation.
+
+## Installation
+
+```ruby
+gem "debugbundle"
+```
+
+## Quick start
+
+```ruby
+require "debugbundle"
+
+DebugBundle.init(
+	project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
+	service: "checkout-api",
+	environment: ENV.fetch("APP_ENV", "production")
+)
+
+DebugBundle.capture_logger(Logger.new($stdout))
+```
+
+`DebugBundle.init(...)` arms best-effort process exception capture automatically through `at_exit` and thread exception hooks.
+
+Capture handled exceptions, messages, requests, and probes explicitly:
+
+```ruby
+begin
+	perform_checkout
+rescue => error
+	DebugBundle.capture_exception(error, context: { order_id: 123 })
+end
+
+DebugBundle.capture_log("payment retry failed", level: :warning, context: { order_id: 123 })
+DebugBundle.capture_message("worker started", level: :info)
+DebugBundle.probe("checkout.tax", { region: "us-east-1" })
+DebugBundle.flush
+```
+
+## Framework integrations
+
+| Surface | Integration |
+| --- | --- |
+| Rack | `DebugBundle::Rack::Middleware` |
+| Rails | Railtie bootstrap, Rack middleware, and auto-mounted relay route |
+| Sidekiq | `DebugBundle::Sidekiq::ServerMiddleware` |
+| Ruby Logger | `DebugBundle.capture_logger(logger)` |
+| Semantic Logger | `DebugBundle.capture_semantic_logger` |
+| Browser relay | `DebugBundle::Relay::Handler` or `DebugBundle::Rack::RelayMiddleware` |
+
+## Browser relay
+
+Ruby backends can receive browser events at `POST /debugbundle/browser` through the relay handler.
+
+Rails applications can let the Railtie append that route automatically, or override it with:
+
+- `config.debugbundle.relay_enabled = false` to disable automatic mounting
+- `config.debugbundle.relay_path = "/debugbundle/browser"` to change the mounted path
+- `config.debugbundle.relay_allowed_origins = ["https://app.example.com"]` to pin allowed origins
+- `config.debugbundle.relay_rate_limit_per_minute = 120` to adjust per-IP relay throttling
+- `config.debugbundle.relay_rate_limit_store = Rails.cache` to share relay throttling across processes
+- `config.debugbundle.relay_handler = custom_handler` to supply a custom relay handler
+
+The relay:
+
+- validates same-origin requests by default
+- enforces `Content-Type: application/json`
+- caps request bodies at 256 KB
+- strips browser-supplied credentials and trust-sensitive fields
+- preserves browser correlation fields such as `trace_id`
+- supports local-only event writes and connected durable forwarding
+
+## Remote probes
+
+Probe buffers stay local and flush on captured exceptions by default. Paid-tier projects can also activate probes for immediate `probe_event` shipping through the polled remote config.
+
+For one-off request diagnostics, the Ruby SDK also accepts signed trigger tokens:
+
+- header: `X-DebugBundle-Probe-Trigger: dbundle_probe_...`
+- query parameter: `?_debug_probe=dbundle_probe_...`
+
+Matching probes still stay in the local ring buffer, but the triggered request also emits standalone `probe_event` records immediately when the token is valid.
+
+## Configuration
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `project_token` | required | Write-only DebugBundle project token. |
+| `service` | `ruby-service` | Service name used in event envelopes. |
+| `environment` | `development` | Runtime environment. |
+| `endpoint` | `https://api.debugbundle.com/v1/events` | Connected ingestion endpoint. |
+| `enabled` | `true` | Disable all capture without removing instrumentation. |
+| `project_mode` | `connected` | `connected` or `local_only`. |
+| `local_events_dir` | `.debugbundle/local/events` | Local event file destination. |
+| `spool_dir` | `.debugbundle/local/browser-relay-spool` | Relay durable spool destination. |
+| `redact_fields` | `[]` | Additional sensitive field names merged with built-in redaction defaults. Rails `filter_parameters` are added automatically. |
+| `batch_size` | `25` | Max events per flush batch. |
+| `flush_interval` | `5` | Flush interval in seconds. |
+| `sample_rate` | `1.0` | Fraction of events kept before transport. |
+| `log_level` | `warning` | Minimum captured log severity. |
+| `relay_enabled` | `true` | Enable relay handling when using the Rails helper surface. |
+| `relay_rate_limit_per_minute` | `60` | Per-IP rate limit for browser relay requests. |
+| `relay_durable_write` | `true` | Write relay batches to the local spool before connected forwarding. |
+| `max_probe_labels` | `50` | Max distinct probe labels kept in memory. |
+| `max_probe_entries_per_label` | `10` | Max entries retained per probe label. |
+| `probe_flush_on_error` | `true` | Attach probe buffers to captured exceptions. |
+| `probes_poll_interval` | `60` | Remote config poll interval in seconds. |
+
+## Safety defaults
+
+- SDK failures are isolated from host application failures.
+- Sensitive values are redacted before buffering or transport.
+- Rails `filter_parameters` are merged into redaction automatically.
+- Duplicate event storms are suppressed locally.
+- Request headers use an allowlist by default.
+- Local file writes use owner-only permissions.
+- `development`, `local`, and `test` environments write local event files by default.
+- Browser relay requests cannot smuggle server-side credentials.
+
+## Examples
+
+- Rack app: [examples/rack_app.rb](examples/rack_app.rb)
+- Rails initializer: [examples/rails_initializer.rb](examples/rails_initializer.rb)
+- Sidekiq server setup: [examples/sidekiq_initializer.rb](examples/sidekiq_initializer.rb)
+
+## Local development
+
+The project defaults to Docker-backed commands:
+
+```sh
+make bundle-install
+make test
+make compat
+make lint
+make build
+```
+
+Compatibility lanes are also exercised in CI for Rails 7.0 and 7.1, Rack 2.2 and 3.x, and Sidekiq 7.x and 8.x.
+
+## Release
+
+The repository ships a GitHub Actions release workflow at `.github/workflows/release.yml`.
+
+- Push a `v*` tag or run the workflow manually with a `version` input.
+- Configure the `RUBYGEMS_API_KEY` repository secret before enabling publish.
+- The workflow runs lint, tests, gem build, local smoke install, GitHub release creation, RubyGems publish, and a published-gem smoke install.
+
+## Supported targets
+
+- Ruby 3.1+
+- Rails 7.0+
+- Rack 2.2+
+- Sidekiq 7.x+
+
+## Documentation
+
+- Ruby SDK docs: https://debugbundle.com/docs/sdks/ruby
+- SDK overview: https://debugbundle.com/docs/sdks
+- Browser relay: https://debugbundle.com/docs/sdks/browser-relay
+- Repository: https://github.com/debugbundle/debugbundle-ruby
+
+## License
+
+AGPL-3.0-only. See LICENSE.

data/debugbundle.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/debugbundle/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'debugbundle'
+  spec.version = DebugBundle::VERSION
+  spec.authors = ['DebugBundle']
+  spec.email = ['support@debugbundle.com']
+
+  spec.summary = 'DebugBundle SDK for Ruby'
+  spec.description = 'Production-ready error, request, log, and probe capture for Ruby services.'
+  spec.homepage = 'https://debugbundle.com/docs/sdks/ruby'
+  spec.license = 'AGPL-3.0-only'
+  spec.required_ruby_version = '>= 3.1'
+
+  spec.metadata = {
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => 'https://github.com/debugbundle/debugbundle-ruby',
+    'changelog_uri' => 'https://github.com/debugbundle/debugbundle-ruby/blob/main/CHANGELOG.md',
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files = Dir.glob('{lib,spec}/**/*') + %w[Gemfile Makefile README.md debugbundle.gemspec]
+  spec.bindir = 'exe'
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'base64', '~> 0.2'
+  spec.add_dependency 'logger', '~> 1.6'
+end