condux 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3db626d815c96cf4115cb51ea7fc2fa076b14b06f90c8b3d4732694810a00aef
-  data.tar.gz: e819143aff9c172bafea74fc17b2a7a2012657cab8f3fca06f3981d20d45b879
+  metadata.gz: ba08155338fd7b32dbe552dadae5337c73090f5f6a57fb0dcee5de53e9f47708
+  data.tar.gz: 04ef85c7632b4f681765972446f279f072bd9b4415be3c4261675f8819b2e84b
 SHA512:
-  metadata.gz: b7697052843054cbbdf929fb9cfa6671b0c0489e2dec35c162c62f57fed5249532c4713d36811db506ec9463ca106d90354174dd97818690f25a6d22ea2f0f2c
-  data.tar.gz: ad5d223a15da543bbcf903b4bbab2b899c3712f9f8859b5f94f84c5fa226f92512d2a15d71d20b7b57a6f1368fb786efcd3365256810914d1d20f13504e9b817
+  metadata.gz: bfbce466a5f5de39b2e9f1ed77a22f952d84b799a5dd548d7f16012d22b3c103f4bd2c1ed8bb1cad4d8683eabc98cc2666dd4f7b947c852dc0bea515cdfa8153
+  data.tar.gz: 8d28840828532b66eabf40de397cc54a58e9e2d745355e0d14babb032958ee409ede759455abf5255a94e5df74731e1cba9dc6be3c45c88287f7c8633d873830

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,83 @@ 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.
+
+### In a server, scope one request at a time
+
+Those calls are **process wide** by default, which is right for facts about the deployment and wrong for
+facts about one request: Puma serves requests concurrently, so a bare `set_user` in a controller can
+attach that user to a different request's error. That is worse than reporting no user, because it is
+confidently wrong.
+
+`Condux.request_scope` isolates it. Anything set inside belongs to that request alone, layered over the
+process-wide values:
+
+```ruby
+Condux.request_scope do
+  Condux.set_user({ "id" => current_user.id }) # this request only
+  process(job)
+end
+```
+
+**The Rack middleware below does this for you**, so a `set_user` in a Rails controller is already
+isolated. Call it directly around background jobs, which have the same problem. It uses
+`Thread.current[]`, which is fiber-local in Ruby, so it isolates Puma's threads and Falcon's fibers
+alike.
+
+Detail belonging to a single event can skip the scope entirely:
+
+```ruby
+Condux.capture_exception(error, request: { "url" => "/api/sync" }, tags: { "job" => "nightly" })
+```
+
+## 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.
+
+**On Rails use `config.middleware.use`, and nothing else.** `use` appends, which puts the middleware at
+the bottom of the stack, inside `ActionDispatch::ShowExceptions`. That position is why it works:
+`ShowExceptions` catches a controller exception and turns it into a 500, so anything above it never sees
+the exception and reports nothing, with no error to tell you. `insert_before`, `insert_after` and
+`unshift` all move it above and break it silently.
+
 ## 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.
@@ -20,23 +21,32 @@ module Condux
       @clock = clock || -> { Time.now }
     end
 
-    def capture_exception(error, handled: true)
-      dispatch(level: Level::ERROR, exception: EventPayload.exception(error, handled: handled))
+    # +request+ (url/method/query_string) and +tags+ describe this one event. They are passed here
+    # rather than set on the scope because scope state outlives the call: on a server handling requests
+    # concurrently, request detail set ambiently attaches to whichever event is captured next, which may
+    # belong to a different request.
+    def capture_exception(error, handled: true, request: nil, tags: nil)
+      dispatch(level: Level::ERROR, exception: EventPayload.exception(error, handled: handled),
+               request: request, tags: tags)
     end
 
-    def capture_message(message, level)
-      dispatch(level: level, message: message)
+    def capture_message(message, level, request: nil, tags: nil)
+      dispatch(level: level, message: message, request: request, tags: tags)
     end
 
     private
 
-    def dispatch(level:, message: nil, exception: nil)
+    def dispatch(level:, message: nil, exception: nil, request: nil, tags: nil)
       event = {
         "event_id" => SecureRandom.hex(16), # 32 lowercase hex, the Sentry event_id shape
         "timestamp" => @clock.call.to_f,    # epoch seconds, the store convention
         "platform" => "ruby",
         "level" => level,
-      }
+      }.merge(Scope.fields)
+      event["request"] = request if request && !request.empty?
+      # Merged over the ambient tags rather than replacing them, so a per-event tag cannot silently drop
+      # the deployment-wide ones.
+      event["tags"] = (event["tags"] || {}).merge(tags) if tags && !tags.empty?
       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/rack.rb

@@ -13,16 +13,46 @@ module Condux
     #
     #   # Rails (config/application.rb)
     #   config.middleware.use "Condux::Rack::CaptureExceptions"
+    #
+    # ON RAILS, USE `config.middleware.use` AND NOTHING ELSE.
+    #
+    # `use` APPENDS, which puts this at the very bottom of the stack, inside ActionDispatch's
+    # ShowExceptions and DebugExceptions. That position is the whole reason it works: those two catch a
+    # controller exception and turn it into a 500, so anything above them never sees the exception at
+    # all and would report nothing, silently. Verified against a real Rails app, where this lands at
+    # position 21 with ShowExceptions at 9.
+    #
+    # So `insert_before`, `insert_after` or `unshift` will move it above them and it will stop reporting
+    # with no error to tell you. A future Rails release reordering its own stack could do the same, which
+    # is why the position is pinned by a test rather than only described here.
     class CaptureExceptions
       def initialize(app)
         @app = app
       end
 
       def call(env)
-        @app.call(env)
-      rescue StandardError => e # report anything the app raises, then re-raise
-        Condux.capture_exception(e, handled: false)
-        raise
+        # A scope per request, so a set_user in a controller belongs to that request and cannot attach to
+        # a concurrent one. Puma reuses threads, which is exactly why this has to be scoped rather than
+        # left to process state.
+        Condux.request_scope do
+          @app.call(env)
+        rescue StandardError => e # report anything the app raises, then re-raise
+          Condux.capture_exception(e, handled: false, request: self.class.request_fields(env))
+          raise
+        end
+      end
+
+      # The request, in the Sentry store shape the relay parses.
+      #
+      # Deliberately only the path, method and query string. Rack puts headers in HTTP_* keys, including
+      # HTTP_COOKIE and HTTP_AUTHORIZATION; the relay scrubs sensitive keys at ingest, but not sending
+      # credentials at all is the stronger guarantee.
+      def self.request_fields(env)
+        {
+          "url" => env["PATH_INFO"],
+          "method" => env["REQUEST_METHOD"],
+          "query_string" => env["QUERY_STRING"]
+        }.reject { |_key, value| value.nil? || value.empty? }
       end
     end
   end

data/lib/condux/scope.rb

@@ -0,0 +1,162 @@
+# 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.
+  # There are two layers, and the distinction is the whole point:
+  #
+  #   Process state, set at boot and shared by everything. Right for facts about the deployment.
+  #   A request scope, active only inside Scope.request. Right for facts about one request.
+  #
+  # Without the second, set_user in a Rails controller is a cross-request leak: Puma serves requests
+  # concurrently, so one request's user would attach to another request's error. That is worse than
+  # reporting no user, because it is confidently wrong and points an investigation at the wrong customer.
+  # The Rack middleware opens a scope per request, so a set_user in a controller stays in that request.
+  module Scope
+    # Newest trail wins: a long-lived process drops the oldest crumbs rather than growing without bound.
+    MAX_BREADCRUMBS = 30
+
+    # Thread.current[] is FIBER-local in Ruby, unlike thread_variable_get which is thread-local. Fiber
+    # local is what this wants: it isolates Puma's threads and also Falcon's fibers, where several
+    # requests share one thread and a thread-local would let them see each other's user.
+    STATE_KEY = :condux_request_scope
+
+    @mutex = Mutex.new
+    @user = nil
+    @tags = {}
+    @contexts = {}
+    @breadcrumbs = []
+
+    class << self
+      # Isolate enrichment to one request. Anything set inside is visible only to events captured
+      # inside. The Rack middleware wraps every request in this; call it directly around a background
+      # job, which has the same problem of many in flight at once.
+      def request
+        previous = Thread.current[STATE_KEY]
+        Thread.current[STATE_KEY] = { user: nil, tags: {}, contexts: {}, breadcrumbs: [] }
+        yield
+      ensure
+        # Always restore. Puma reuses threads, so state left behind is handed to the next request that
+        # worker picks up, which is the exact leak this exists to prevent. Restoring the previous value
+        # rather than clearing keeps nesting honest.
+        Thread.current[STATE_KEY] = previous
+      end
+
+      # Nil when no request is in flight, so writes fall through to process state and a boot-time
+      # set_tag behaves exactly as it did before request scopes existed.
+      def request_state
+        Thread.current[STATE_KEY]
+      end
+      # Attach the signed-in user (id/email/username) to subsequent events; nil clears. Inside a request
+      # scope this applies to that request alone; outside one it is process wide.
+      def user=(user)
+        value = user&.transform_keys(&:to_s)
+        state = request_state
+        return state[:user] = value if state
+
+        @mutex.synchronize { @user = value }
+      end
+
+      # Attach a tag to subsequent events; a nil value removes it.
+      def set_tag(key, value)
+        state = request_state
+        if state
+          value.nil? ? state[:tags].delete(key.to_s) : state[:tags][key.to_s] = value
+          return
+        end
+
+        @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)
+        value = context&.transform_keys(&:to_s)
+        state = request_state
+        if state
+          value.nil? ? state[:contexts].delete(name.to_s) : state[:contexts][name.to_s] = value
+          return
+        end
+
+        @mutex.synchronize do
+          if value.nil?
+            @contexts.delete(name.to_s)
+          else
+            @contexts[name.to_s] = value
+          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
+
+        state = request_state
+        if state
+          state[:breadcrumbs] << crumb
+          state[:breadcrumbs].shift while state[:breadcrumbs].length > MAX_BREADCRUMBS
+          return
+        end
+
+        @mutex.synchronize do
+          @breadcrumbs << crumb
+          @breadcrumbs.shift while @breadcrumbs.length > MAX_BREADCRUMBS
+        end
+      end
+
+      # Reset all ambient state (tests, or a full sign-out). Clears the request scope when one is active.
+      def clear
+        state = request_state
+        if state
+          state.replace(user: nil, tags: {}, contexts: {}, breadcrumbs: [])
+          return
+        end
+
+        @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.
+      #
+      # The request scope layers OVER the process state rather than replacing it, so a request keeps the
+      # deployment-wide tags while overriding the ones it sets itself.
+      def fields
+        state = request_state || {}
+        process = @mutex.synchronize do
+          { user: @user&.dup, tags: @tags.dup, contexts: @contexts.dup, breadcrumbs: @breadcrumbs.dup }
+        end
+
+        user = state[:user] || process[:user]
+        tags = process[:tags].merge(state[:tags] || {})
+        contexts = process[:contexts].merge(state[:contexts] || {})
+        # Concatenated, not merged: the trail is a sequence, and the process-level crumbs genuinely
+        # happened before the ones recorded during the request.
+        breadcrumbs = (process[:breadcrumbs] + (state[:breadcrumbs] || [])).last(MAX_BREADCRUMBS)
+
+        fields = {}
+        fields["user"] = user.dup if user
+        fields["tags"] = tags unless tags.empty?
+        fields["contexts"] = contexts unless contexts.empty?
+        fields["breadcrumbs"] = { "values" => breadcrumbs } unless breadcrumbs.empty?
+        fields
+      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,
@@ -22,21 +24,71 @@ 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)
+    def capture_exception(error, handled: true, request: nil, tags: nil)
+      client = active_client
+      return not_initialized unless client
+
+      client.capture_exception(error, handled: handled, request: request, tags: tags)
     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
+
+    # Isolate enrichment to one request, so a set_user inside it cannot attach to a concurrent request.
+    # The Rack middleware does this for every request; call it directly around a background job.
+    def request_scope(&block)
+      Scope.request(&block)
+    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.6
 platform: ruby
 authors:
 - Condux
 autorequire:
-bindir: bin
+bindir: exe
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 2026-08-15 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