condux 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3db626d815c96cf4115cb51ea7fc2fa076b14b06f90c8b3d4732694810a00aef
-  data.tar.gz: e819143aff9c172bafea74fc17b2a7a2012657cab8f3fca06f3981d20d45b879
+  metadata.gz: 72bffbeb8549e50c7defe4c9fb3d18c5eeecd3ca9d02704e05a8bc3733e5eed9
+  data.tar.gz: 41df087b35b4f1861384e0826e43b8adc7fe42d8c921c59df35339f54ed64ec6
 SHA512:
-  metadata.gz: b7697052843054cbbdf929fb9cfa6671b0c0489e2dec35c162c62f57fed5249532c4713d36811db506ec9463ca106d90354174dd97818690f25a6d22ea2f0f2c
-  data.tar.gz: ad5d223a15da543bbcf903b4bbab2b899c3712f9f8859b5f94f84c5fa226f92512d2a15d71d20b7b57a6f1368fb786efcd3365256810914d1d20f13504e9b817
+  metadata.gz: 97dd3d4ce440838f0e67fed077def7476d2fcd8a61c20e869dc8fc90372a1137575d30ac450c555f074f30133f428deecfa81da2dd370e8f4bedca13f9f2be46
+  data.tar.gz: 9fd4ce9a8f850b83bdec18d1d70f6539eab33b42aceb636db01689d354ce59fa9d74afa5ef391156df1ad7ae1d03a6b16a09d78611d95f27df437eeb6d656490

data/README.md

@@ -4,7 +4,10 @@ Report errors from a Ruby app to a Condux relay. Emits the Sentry "store" wire s
 normalizes it exactly like an official Sentry SDK — point it at a project DSN and it works.
 
 Delivery is resilient (429 / 5xx / network failures retry with backoff, honoring `Retry-After`) and
-**never raises** — a failed send returns a `SendResult`, it does not crash the caller.
+**never raises** — a failed send returns a `SendResult`, it does not crash the caller. That holds even
+if `init` was never called: capture warns once and drops the event, because the Rack middleware below
+reports from inside a `rescue` and an SDK that raised there would replace your application's exception
+with its own. A malformed DSN is refused by `init` instead, where it is a developer-time mistake.
 
 ## Usage
 
@@ -28,10 +31,49 @@ end
 Condux.capture_message("cache miss storm", level: Condux::Level::WARNING)
 ```
 
+## Verify your setup
+
+Silence is what a broken error monitor and a healthy app look like from the outside, so prove the
+pipeline once:
+
+```bash
+CONDUX_DSN="https://<key>@ingest.condux.ai/<projectId>" bundle exec condux test-event
+```
+
+Exit code 0 means delivered (the message appears as an info-level issue), 1 means delivery failed and
+prints why, 2 means the DSN was missing or malformed.
+
+## Enrichment
+
+Attach the ambient facts triage always needs. Every subsequent event carries them, so nothing has to be
+threaded through capture calls:
+
+```ruby
+Condux.set_user({ "id" => "1042", "email" => "dev@example.com" }) # nil clears it (sign-out)
+Condux.set_tag("plan", "team")                                    # nil removes the tag
+Condux.set_context("job", { "queue" => "billing", "attempt" => 3 })
+Condux.add_breadcrumb("charge.started", category: "billing")
+```
+
+The breadcrumb trail keeps the most recent 30 entries. `Condux.clear_scope` resets everything.
+
+## Rack and Rails
+
+```ruby
+# config.ru
+require "condux/rack"
+use Condux::Rack::CaptureExceptions
+
+# Rails (config/application.rb)
+config.middleware.use "Condux::Rack::CaptureExceptions"
+```
+
+Uncaught exceptions are reported as unhandled and re-raised, so the app's own error handling still runs.
+
 ## Develop
 
 ```bash
-ruby -Ilib -Itest test/test_condux.rb
+for f in test/*.rb; do ruby -Ilib -Itest "$f"; done
 ```
 
 Zero runtime dependencies (standard library only). The transport, sleep, and clock are injectable

data/exe/condux

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "condux/test_event"
+
+exit Condux::TestEvent.run(ARGV)

data/lib/condux/client.rb

@@ -6,6 +6,7 @@ require_relative "level"
 require_relative "dsn"
 require_relative "event_payload"
 require_relative "event_transport"
+require_relative "scope"
 
 module Condux
   # A configured reporter. Cheap to hold for the process lifetime; safe for concurrent use.
@@ -36,7 +37,7 @@ module Condux
         "timestamp" => @clock.call.to_f,    # epoch seconds, the store convention
         "platform" => "ruby",
         "level" => level,
-      }
+      }.merge(Scope.fields)
       event["environment"] = @environment if @environment
       event["release"] = @release if @release
       event["message"] = message if message

data/lib/condux/dsn.rb

@@ -9,13 +9,14 @@ module Condux
 
     def self.parse(dsn)
       uri = URI(dsn)
-      if uri.user.nil? || uri.user.empty? || uri.host.nil?
+      project_id = uri.path.to_s.sub(%r{\A/}, "")
+      if uri.user.nil? || uri.user.empty? || uri.host.nil? || project_id.empty?
         raise ArgumentError, "Condux: DSN must be scheme://<key>@<host>/<projectId>"
       end
 
       endpoint = "#{uri.scheme}://#{uri.host}"
       endpoint += ":#{uri.port}" if uri.port && ![80, 443].include?(uri.port)
-      new(endpoint, uri.path.sub(%r{\A/}, ""), uri.user)
+      new(endpoint, project_id, uri.user)
     end
 
     def initialize(endpoint, project_id, public_key)

data/lib/condux/scope.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Condux
+  # Ambient event enrichment: who the user is, which tags and contexts apply, and the breadcrumb trail
+  # leading up to an error. Set once (or as the app's state changes) and every subsequent event carries
+  # it — the first triage questions ("which customer, which plan, what did they do last") answered
+  # without threading anything through capture calls. The relay already scrubs all of these at ingest
+  # and derives the pseudonymous users-affected key from the user fields.
+  module Scope
+    # Newest trail wins: a long-lived process drops the oldest crumbs rather than growing without bound.
+    MAX_BREADCRUMBS = 30
+
+    @mutex = Mutex.new
+    @user = nil
+    @tags = {}
+    @contexts = {}
+    @breadcrumbs = []
+
+    class << self
+      # Attach the signed-in user (id/email/username) to subsequent events; nil clears.
+      def user=(user)
+        @mutex.synchronize { @user = user&.transform_keys(&:to_s) }
+      end
+
+      # Attach a tag to subsequent events; a nil value removes it.
+      def set_tag(key, value)
+        @mutex.synchronize do
+          if value.nil?
+            @tags.delete(key.to_s)
+          else
+            @tags[key.to_s] = value
+          end
+        end
+      end
+
+      # Attach a named context object to subsequent events; nil removes it.
+      def set_context(name, context)
+        @mutex.synchronize do
+          if context.nil?
+            @contexts.delete(name.to_s)
+          else
+            @contexts[name.to_s] = context.transform_keys(&:to_s)
+          end
+        end
+      end
+
+      # Record a breadcrumb; the trail (newest last, capped) rides every subsequent event.
+      def add_breadcrumb(message, category: nil, level: nil, type: nil, data: nil, timestamp: nil)
+        crumb = { "message" => message, "timestamp" => timestamp || Time.now.to_f }
+        crumb["category"] = category if category
+        crumb["level"] = level if level
+        crumb["type"] = type if type
+        crumb["data"] = data if data
+
+        @mutex.synchronize do
+          @breadcrumbs << crumb
+          @breadcrumbs.shift while @breadcrumbs.length > MAX_BREADCRUMBS
+        end
+      end
+
+      # Reset all ambient state (tests, or a full sign-out).
+      def clear
+        @mutex.synchronize do
+          @user = nil
+          @tags = {}
+          @contexts = {}
+          @breadcrumbs = []
+        end
+      end
+
+      # The scope's contribution to an event, holding only the keys that are actually set so an
+      # unenriched event keeps its exact wire shape. Breadcrumbs use the Sentry {"values" => []} envelope.
+      def fields
+        @mutex.synchronize do
+          fields = {}
+          fields["user"] = @user.dup if @user
+          fields["tags"] = @tags.dup unless @tags.empty?
+          fields["contexts"] = @contexts.dup unless @contexts.empty?
+          fields["breadcrumbs"] = { "values" => @breadcrumbs.dup } unless @breadcrumbs.empty?
+          fields
+        end
+      end
+    end
+  end
+end

data/lib/condux/test_event.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../condux"
+
+module Condux
+  # `condux test-event` — prove the pipeline end to end.
+  #
+  # An error monitor's failure mode is silence, and silence looks exactly like health. This sends one
+  # info-level message through the real client and transport and reports the delivery outcome, so "did my
+  # DSN / network / relay work" is one command instead of waiting for a production error.
+  module TestEvent
+    USAGE = "Usage: condux test-event [--dsn <dsn>] [--message <text>]"
+
+    module_function
+
+    # Runs the command; returns the process exit code (0 delivered, 1 failed, 2 usage).
+    def run(argv, out: $stdout, err: $stderr)
+      command = argv.first
+      return usage(err, "unknown command '#{command}'") unless command == "test-event"
+
+      dsn = argument(argv, "--dsn") || ENV.fetch("CONDUX_DSN", nil)
+      return usage(err, "no DSN. Pass --dsn <dsn> or set CONDUX_DSN") if dsn.nil? || dsn.empty?
+
+      begin
+        Condux.init(dsn: dsn, environment: "condux-test")
+      rescue ArgumentError, URI::InvalidURIError => e
+        return usage(err, e.message)
+      end
+
+      report(Condux.capture_message(argument(argv, "--message") || "Condux test event"), out, err)
+    end
+
+    def report(result, out, err)
+      message_count = "#{result.attempts} attempt#{result.attempts == 1 ? "" : "s"}"
+      if result.ok
+        out.puts "Delivered (#{message_count}). Check your project's issues list; a test message " \
+                 "appears as an info-level issue."
+        return 0
+      end
+
+      err.puts "Delivery FAILED after #{message_count}: #{result.error || "relay answered #{result.status}"}. " \
+               "Check the DSN (Project settings -> DSN keys) and that the ingest host is reachable."
+      1
+    end
+
+    def argument(argv, name)
+      index = argv.index(name)
+      index && argv[index + 1]
+    end
+
+    def usage(err, reason)
+      err.puts "condux: #{reason}. #{USAGE}"
+      2
+    end
+  end
+end

data/lib/condux.rb

@@ -2,6 +2,7 @@
 
 require_relative "condux/level"
 require_relative "condux/send_result"
+require_relative "condux/scope"
 require_relative "condux/client"
 
 # Condux SDK for Ruby — report errors to a Condux relay.
@@ -13,7 +14,8 @@ require_relative "condux/client"
 # no real network or timers. Inspired by common SDK transports, implemented fresh.
 module Condux
   class << self
-    # Configure the SDK with a project DSN (and optional testing hooks).
+    # Configure the SDK with a project DSN (and optional testing hooks). Raises on a malformed DSN:
+    # setup runs once at developer time, so a typo is worth failing loudly for.
     def init(dsn:, environment: nil, release: nil, max_retries: Client::DEFAULT_MAX_RETRIES,
              transport: nil, sleep: nil, clock: nil)
       @client = Client.new(dsn: dsn, environment: environment, release: release,
@@ -23,20 +25,64 @@ module Condux
     # Report an exception as an error-level event, with its stack trace. Never raises on delivery failure.
     # Pass handled: false for an uncaught exception (a framework integration does this).
     def capture_exception(error, handled: true)
-      require_client.capture_exception(error, handled: handled)
+      client = active_client
+      return not_initialized unless client
+
+      client.capture_exception(error, handled: handled)
     end
 
     # Report a bare message event at the given level (default info).
     def capture_message(message, level: Level::INFO)
-      require_client.capture_message(message, level)
+      client = active_client
+      return not_initialized unless client
+
+      client.capture_message(message, level)
+    end
+
+    # Attach the signed-in user (id/email/username) to subsequent events; nil clears.
+    def set_user(user)
+      Scope.user = user
+    end
+
+    # Attach a tag to subsequent events; a nil value removes it.
+    def set_tag(key, value)
+      Scope.set_tag(key, value)
+    end
+
+    # Attach a named context object to subsequent events; nil removes it.
+    def set_context(name, context)
+      Scope.set_context(name, context)
+    end
+
+    # Record a breadcrumb; the trail (newest last, capped) rides every subsequent event.
+    def add_breadcrumb(message, category: nil, level: nil, type: nil, data: nil, timestamp: nil)
+      Scope.add_breadcrumb(message, category: category, level: level, type: type, data: data,
+                                    timestamp: timestamp)
+    end
+
+    # Reset all ambient enrichment (tests, or a full sign-out).
+    def clear_scope
+      Scope.clear
     end
 
     private
 
-    def require_client
-      raise "Condux not initialized — call Condux.init(dsn:) first" unless @client
+    # Reporting never raises — an error monitor that raises turns a handled error into an unhandled one in
+    # exactly the code path where someone is already dealing with a failure. The Rack middleware reports
+    # from inside a rescue, so raising here would replace the application's own exception with this one.
+    # Warn once and drop the event instead.
+    def active_client
+      return @client if @client
+
+      unless @warned_uninitialized
+        @warned_uninitialized = true
+        warn "Condux: capture called before Condux.init(dsn:); events are being dropped."
+      end
+      nil
+    end
 
-      @client
+    def not_initialized
+      SendResult.new(ok: false, attempts: 0, error: "not_initialized")
     end
   end
 end

metadata

@@ -1,24 +1,26 @@
 --- !ruby/object:Gem::Specification
 name: condux
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Condux
 autorequire:
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 2026-08-14 00:00:00.000000000 Z
 dependencies: []
 description: 'The Condux SDK for Ruby: report errors to a Condux relay with a resilient,
   never-raising transport. Zero runtime dependencies (standard library only).'
 email:
-executables: []
+executables:
+- condux
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- exe/condux
 - lib/condux.rb
 - lib/condux/client.rb
 - lib/condux/dsn.rb
@@ -26,7 +28,9 @@ files:
 - lib/condux/event_transport.rb
 - lib/condux/level.rb
 - lib/condux/rack.rb
+- lib/condux/scope.rb
 - lib/condux/send_result.rb
+- lib/condux/test_event.rb
 homepage: https://condux.ai
 licenses:
 - Apache-2.0