condux 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72bffbeb8549e50c7defe4c9fb3d18c5eeecd3ca9d02704e05a8bc3733e5eed9
-  data.tar.gz: 41df087b35b4f1861384e0826e43b8adc7fe42d8c921c59df35339f54ed64ec6
+  metadata.gz: '095069e5d14a6e32c481494fb6927c19441f56cc0a9cdc9dd6311acd9ef7e7c9'
+  data.tar.gz: 1b3db61a8413e8fab802e39c13317b77c3418277b7f9a5b1c083b762cc64ba86
 SHA512:
-  metadata.gz: 97dd3d4ce440838f0e67fed077def7476d2fcd8a61c20e869dc8fc90372a1137575d30ac450c555f074f30133f428deecfa81da2dd370e8f4bedca13f9f2be46
-  data.tar.gz: 9fd4ce9a8f850b83bdec18d1d70f6539eab33b42aceb636db01689d354ce59fa9d74afa5ef391156df1ad7ae1d03a6b16a09d78611d95f27df437eeb6d656490
+  metadata.gz: 5b12b5ffdee576bb9879191e5ba68748ce9a7b9cb81843422ce10b567d15776616d156cfcc1de0b3b8afb1caef5fec53501316d8d8a44e960ad78aa8f45eef9c
+  data.tar.gz: 5ea29b8ae01b6f994d62b3b5af926d66a41878ae444f927fba82f05ab7d3cf03ab1f3c5db3e6a1ab8a158be2cfef7ec6132ac581f180d1f6859615260fbe5f37

data/README.md

@@ -57,6 +57,34 @@ 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
@@ -70,6 +98,12 @@ 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

data/lib/condux/client.rb

@@ -21,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/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

@@ -6,10 +6,24 @@ module Condux
   # 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 = {}
@@ -17,13 +31,43 @@ module Condux
     @breadcrumbs = []
 
     class << self
-      # Attach the signed-in user (id/email/username) to subsequent events; nil clears.
+      # 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)
-        @mutex.synchronize { @user = user&.transform_keys(&:to_s) }
+        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)
@@ -35,11 +79,18 @@ module Condux
 
       # 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 context.nil?
+          if value.nil?
             @contexts.delete(name.to_s)
           else
-            @contexts[name.to_s] = context.transform_keys(&:to_s)
+            @contexts[name.to_s] = value
           end
         end
       end
@@ -52,14 +103,27 @@ module Condux
         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).
+      # 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 = {}
@@ -70,15 +134,28 @@ module Condux
 
       # 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
-        @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
+        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

data/lib/condux.rb

@@ -24,11 +24,11 @@ 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)
+    def capture_exception(error, handled: true, request: nil, tags: nil)
       client = active_client
       return not_initialized unless client
 
-      client.capture_exception(error, handled: handled)
+      client.capture_exception(error, handled: handled, request: request, tags: tags)
     end
 
     # Report a bare message event at the given level (default info).
@@ -39,6 +39,12 @@ module Condux
       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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: condux
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Condux
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 2026-08-16 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).'