alplus-ruby 0.1.0

data/lib/alplus/rack_middleware.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Alplus
+  # Rack middleware: captures any exception that propagates up through the
+  # app, then re-raises so the host's own error page / handler still runs
+  # unchanged. Installed automatically by the Rails railtie; usable directly
+  # in a plain Rack app (`use Alplus::RackMiddleware`).
+  #
+  # Also resets `Scope` to a fresh, empty one for the duration of the
+  # request (issue #17): a thread-pool server (Puma, Passenger) reuses OS
+  # threads across requests, so without this a `set_user`/`set_tag` call in
+  # request A would otherwise still be visible to request B if it happens
+  # to land on the same thread.
+  #
+  # Session lifecycle (issue #12): opens a fresh request-scoped `Session`
+  # (`Session.with_clean_session`, the same reused-thread guard as `Scope`
+  # above) and closes it (`Alplus.close_session`) once `@app.call` returns
+  # OR raises. Unlike `sdks/elixir/lib/alplus_sdk/plug.ex` (which cannot
+  # rescue a downstream plug's exception — see that module's moduledoc),
+  # Rack middleware genuinely wraps the rest of the stack in one method
+  # call, so `rescue`/`ensure` here is the complete, reliable crash signal:
+  # no separate telemetry hook is needed.
+  class RackMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      Scope.with_clean_scope { Session.with_clean_session { call_app(env) } }
+    end
+
+    private
+
+    def call_app(env)
+      attach_request_context(env)
+      @app.call(env)
+    rescue StandardError => e
+      # StandardError only, deliberately: SystemExit/SignalException/
+      # NoMemoryError are process-control exceptions, not app errors, and
+      # must propagate untouched. `mark_crashed` runs BEFORE
+      # `capture_exception` below: that call would otherwise mark the
+      # session merely `:errored` (any `"error"`-level capture does), and
+      # `:crashed` must win regardless of call order — `Session`'s
+      # severity ordering makes this safe either way.
+      Session.current&.mark_crashed
+      Alplus.capture_exception(e, mechanism: "rack.middleware")
+      raise
+    ensure
+      Alplus.close_session
+    end
+
+    # Response headers a triaging dev actually reads. Cookie and
+    # Authorization are deliberately absent — they are secrets, not
+    # diagnostics, and key-based scrubbing must not be the only line of
+    # defense against them.
+    HEADER_ALLOWLIST = {
+      "HTTP_USER_AGENT" => "User-Agent",
+      "HTTP_REFERER" => "Referer",
+      "HTTP_ACCEPT" => "Accept",
+      "CONTENT_TYPE" => "Content-Type",
+      "HTTP_X_REQUEST_ID" => "X-Request-Id"
+    }.freeze
+
+    # Serialized params beyond this are replaced by a truncation marker so
+    # one giant upload form cannot push the whole `contexts` object over
+    # `Envelope::MAX_CONTEXT_CHARS` (which would replace ALL contexts).
+    MAX_PARAMS_CHARS = 4_096
+
+    # Attaches `contexts.request` (method, url without query string, parsed
+    # params, allowlisted headers) to the request's fresh Scope, so every
+    # capture during this request carries it. Params go through the built-in
+    # `Scrubber` at capture time like any other context value. The raw query
+    # string is never attached: a raw string cannot be key-scrubbed; the
+    # parsed params hash can. Never raises — request context is diagnostics,
+    # not a reason to break the request.
+    def attach_request_context(env)
+      request = ::Rack::Request.new(env)
+
+      context = {
+        method: request.request_method,
+        url: "#{request.base_url}#{request.path}",
+        params: bounded_params(request),
+        headers: request_headers(env)
+      }.compact
+
+      Scope.current.set_context("request", context)
+    rescue StandardError
+      nil
+    end
+
+    def bounded_params(request)
+      params = query_params(request).merge(form_params(request))
+      return nil if params.empty?
+      return { "_truncated" => true } if JSON.generate(params).bytesize > MAX_PARAMS_CHARS
+
+      params
+    rescue StandardError
+      nil
+    end
+
+    def query_params(request)
+      request.GET || {}
+    rescue StandardError
+      {}
+    end
+
+    # Form-encoded bodies only; `Rack::Request#POST` rewinds the input, so
+    # the downstream app still reads the full body. A JSON body is not
+    # parsed here — parsing it would mean buffering and re-encoding the
+    # body on every request just in case an error happens later.
+    def form_params(request)
+      request.form_data? ? request.POST : {}
+    rescue StandardError
+      {}
+    end
+
+    def request_headers(env)
+      headers = HEADER_ALLOWLIST.each_with_object({}) do |(rack_key, header), out|
+        value = env[rack_key]
+        out[header] = value.to_s if value
+      end
+      headers.empty? ? nil : headers
+    end
+  end
+end

data/lib/alplus/rails_error_subscriber.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Alplus
+  # Rails 7+ error reporter subscriber (`Rails.error.subscribe`). Forwards
+  # only HANDLED reports (`Rails.error.handle`/`Rails.error.record`, or any
+  # library that reports through `Rails.error`) — an UNHANDLED exception
+  # already reaches `Alplus::RackMiddleware` (installed directly around the
+  # app, inside `ActionDispatch::ShowExceptions`) as it propagates up the
+  # middleware stack. Subscribing to `handled: false` here too would
+  # double-report the same exception on Rails versions that also route
+  # unhandled request exceptions through the error reporter.
+  class RailsErrorSubscriber
+    def report(error, handled:, severity:, context:, source: nil)
+      return unless handled
+
+      Alplus.capture_exception(error, level: severity_to_level(severity), context: context, mechanism: "rails.error_reporter")
+    end
+
+    private
+
+    def severity_to_level(severity)
+      { error: "error", warning: "warning", info: "info" }.fetch(severity, "error").to_s
+    end
+  end
+end

data/lib/alplus/railtie.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "rails_error_subscriber"
+require_relative "notifications_subscriber"
+
+module Alplus
+  # Installs `Alplus::RackMiddleware` and auto-detects the app root from
+  # Rails config, so a Rails app gets automatic unhandled-exception capture
+  # with zero explicit wiring beyond setting the ingest key (issue #14
+  # story 2/12).
+  #
+  # Middleware position matters, and there are TWO exception renderers to
+  # get inside of, not one:
+  #
+  #   * `ActionDispatch::ShowExceptions` (outer) renders the public error
+  #     page in production.
+  #   * `ActionDispatch::DebugExceptions` (inner, closer to the app) renders
+  #     the developer error page in development — and, crucially, it does
+  #     NOT re-raise. In development it rescues the exception and returns the
+  #     debug page, so any middleware OUTSIDE it never sees the exception.
+  #
+  # Inserting after `ShowExceptions` (the original fix) works in production
+  # — there `DebugExceptions` re-raises and our middleware, sitting between
+  # the two, catches the re-raised exception. But in DEVELOPMENT
+  # `DebugExceptions` swallows first, so unhandled web errors were lost
+  # (verified against a real Rails 8 app, 2026-08-17).
+  #
+  # `insert_after ActionDispatch::DebugExceptions` places `RackMiddleware`
+  # inside BOTH renderers — the innermost exception boundary, matching
+  # `Sentry::Rails::CaptureExceptions`. The app's exception now reaches our
+  # `rescue`/re-raise before either renderer runs, in every environment.
+  class Railtie < ::Rails::Railtie
+    initializer "alplus.configure" do |app|
+      config = Alplus.configuration
+      config.app_dirs = [::Rails.root.to_s] if config.app_dirs.empty? && ::Rails.respond_to?(:root) && ::Rails.root
+
+      if defined?(::ActionDispatch::DebugExceptions) && app.middleware.respond_to?(:insert_after)
+        app.middleware.insert_after ::ActionDispatch::DebugExceptions, Alplus::RackMiddleware
+      else
+        app.middleware.insert 0, Alplus::RackMiddleware
+      end
+
+      if ::Rails.respond_to?(:error) && ::Rails.error.respond_to?(:subscribe)
+        ::Rails.error.subscribe(Alplus::RailsErrorSubscriber.new)
+      end
+
+      Alplus::NotificationsSubscriber.install!
+
+      # Log-line breadcrumbs (issue #47). `config.after_initialize` rather
+      # than here: `Rails.logger` is finalized (BroadcastLogger assembled,
+      # taggers applied) only after the framework initializers run.
+      app.config.after_initialize do
+        Alplus::LoggerBreadcrumbs.attach(::Rails.logger) if ::Rails.logger
+      end
+
+      # Install the optional job integrations HERE, not at gem-require time
+      # in `alplus.rb`. By the time this initializer runs, Bundler has
+      # loaded every gem and Rails has booted its frameworks, so require
+      # order no longer matters. In a real Rails app `ActiveJob::Base`
+      # autoloads only after boot, so the `defined?` check in `alplus.rb`
+      # is false when the gem loads and would silently skip the install.
+      #
+      # `install!` is idempotent, so overlapping with `alplus.rb`'s
+      # non-Rails fallback path is safe.
+      if defined?(::Sidekiq)
+        require_relative "sidekiq"
+        Alplus::Sidekiq.install!
+      end
+
+      if defined?(::ActiveSupport) && ::ActiveSupport.respond_to?(:on_load)
+        # Fires whenever `ActiveJob::Base` loads, regardless of gem require
+        # order relative to `alplus`.
+        ::ActiveSupport.on_load(:active_job) do
+          require_relative "active_job"
+          Alplus::ActiveJob.install!
+        end
+      end
+    end
+  end
+end

data/lib/alplus/retry.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Alplus
+  # Shared retry/backoff loop for both `Transport` (`POST /e/errors`) and
+  # `Heartbeat` (`POST /h/:token`) — issue #16 explicitly asks the two share
+  # this, unlike the JS SDK's `transport.ts`/`heartbeat.ts`, which duplicate
+  # it deliberately because heartbeat there already shipped and touching it
+  # was the higher-risk move. Both Ruby callers land in this change
+  # together, so that risk does not apply here.
+  #
+  # Constants (3 attempts, 500ms jittered exponential base, 30s Retry-After
+  # cap) mirror `packages/sdk/src/core/observe/transport.ts` byte-for-byte
+  # so all SDKs back off the same way against the same ingest endpoint.
+  module Retry
+    MAX_ATTEMPTS = 3
+    BACKOFF_BASE_SECONDS = 0.5
+    BACKOFF_JITTER = 0.5
+    MAX_RETRY_AFTER_SECONDS = 30
+    # 400 (malformed request) and 401/403 (bad/scopeless key) and 404
+    # (unrecognized route/token) can't be fixed by retrying.
+    PERMANENT_STATUSES = [400, 401, 403, 404].freeze
+
+    Result = Struct.new(:outcome, :response, :error, keyword_init: true) do
+      def sent?
+        outcome == :sent
+      end
+    end
+
+    module_function
+
+    # Calls the block up to `max_attempts` times (default `MAX_ATTEMPTS`).
+    # The block must return a `Net::HTTPResponse` or raise. Sleeps between
+    # attempts via `sleeper` (injectable so specs never wait on real
+    # wall-clock time). A 429's `Retry-After` is capped at
+    # `max_retry_after_seconds` (default `MAX_RETRY_AFTER_SECONDS`) —
+    # `Heartbeat` passes a much lower cap so a caller pinging synchronously
+    # can never be made to block anywhere near the server's full 30s cap.
+    # Never raises: a block error on the final attempt is captured on the
+    # returned `Result`, not re-raised.
+    def perform(sleeper: method(:sleep), max_attempts: MAX_ATTEMPTS, max_retry_after_seconds: MAX_RETRY_AFTER_SECONDS)
+      result = nil
+
+      max_attempts.times do |i|
+        attempt = i + 1
+        begin
+          response = yield(attempt)
+
+          if response.is_a?(Net::HTTPSuccess)
+            return Result.new(outcome: :sent, response: response)
+          end
+
+          code = response.code.to_i
+          if PERMANENT_STATUSES.include?(code)
+            return Result.new(outcome: :permanent, response: response)
+          end
+
+          result = Result.new(outcome: :exhausted, response: response)
+          unless attempt == max_attempts
+            sleeper.call(code == 429 ? (retry_after_seconds(response, max_retry_after_seconds) || backoff_seconds(attempt)) : backoff_seconds(attempt))
+          end
+        rescue StandardError => e
+          result = Result.new(outcome: :exhausted, error: e)
+          sleeper.call(backoff_seconds(attempt)) unless attempt == max_attempts
+        end
+      end
+
+      result
+    end
+
+    def backoff_seconds(attempt)
+      exponential = BACKOFF_BASE_SECONDS * (2**(attempt - 1))
+      jitter_factor = (1 - BACKOFF_JITTER) + (rand * 2 * BACKOFF_JITTER)
+      exponential * jitter_factor
+    end
+
+    def retry_after_seconds(response, max_seconds = MAX_RETRY_AFTER_SECONDS)
+      value = response["Retry-After"]
+      return nil if value.nil? || value.strip.empty?
+
+      seconds = Float(value, exception: false)
+      return nil if seconds.nil? || seconds.negative?
+
+      [seconds, max_seconds].min
+    end
+  end
+end

data/lib/alplus/scope.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Alplus
+  # Request-scoped ambient scope (issue #17): the server analog of the JS
+  # SDK's browser `withScope`. `Alplus.set_user`/`set_tag`/`set_context`/
+  # `add_breadcrumb` write to a scope that lives on `Thread.current`
+  # (fiber-local storage in Ruby -- see `Thread#[]`), so a value set once at
+  # the top of a request (`RackMiddleware`) applies to every capture inside
+  # that request without threading it through every call site, and never
+  # bleeds into a different request handled on a reused thread-pool thread.
+  class Scope
+    THREAD_KEY = :alplus_scope
+    private_constant :THREAD_KEY
+
+    # Server ceiling (`Envelope::SERVER_MAX_BREADCRUMBS`) -- kept as a
+    # literal here rather than requiring `envelope` first (`Scope` loads
+    # before `Envelope` in `alplus.rb`), and re-asserted by
+    # `Envelope.cap_breadcrumbs` regardless.
+    MAX_BREADCRUMBS = 100
+
+    class << self
+      # The current thread/fiber's scope, lazily created.
+      def current
+        Thread.current[THREAD_KEY] ||= new
+      end
+
+      # Replaces the current thread/fiber's scope with a fresh, empty one
+      # and yields; restores whatever scope (if any) was active before,
+      # even if the block raises. `RackMiddleware` wraps each request in
+      # this so scope set during request A never leaks into request B on a
+      # reused thread-pool thread.
+      def with_clean_scope
+        previous = Thread.current[THREAD_KEY]
+        Thread.current[THREAD_KEY] = new
+        yield
+      ensure
+        Thread.current[THREAD_KEY] = previous
+      end
+    end
+
+    attr_reader :user, :tags, :contexts, :breadcrumbs
+
+    def initialize
+      @user = nil
+      @tags = {}
+      @contexts = {}
+      @breadcrumbs = []
+    end
+
+    def set_user(user)
+      @user = user
+    end
+
+    def set_tag(key, value)
+      @tags[key.to_s] = value.to_s
+    end
+
+    def set_context(name, data)
+      @contexts[name.to_s] = data
+    end
+
+    # `breadcrumb` accepts the same keys as the wire shape
+    # (`message`/`category`/`level`/`data`/`ts`); `ts` defaults to now.
+    # Bounded ring buffer: the oldest breadcrumb is dropped once the buffer
+    # is at `MAX_BREADCRUMBS`.
+    def add_breadcrumb(message: nil, category: nil, level: nil, data: nil, ts: nil)
+      crumb = { message: message, category: category, level: level, data: data, ts: ts || Time.now.utc.iso8601 }.compact
+      @breadcrumbs << crumb
+      @breadcrumbs.shift while @breadcrumbs.length > MAX_BREADCRUMBS
+    end
+
+    # Immutable snapshot handed to `Client` at capture time — mirrors the
+    # JS SDK's `ScopeSnapshot` (`scope.ts`).
+    def snapshot
+      { user: @user, tags: @tags.dup, contexts: @contexts.dup, breadcrumbs: @breadcrumbs.dup }
+    end
+  end
+
+  # Merges an ambient `Scope#snapshot` with per-capture overrides. Mirrors
+  # `packages/sdk/src/core/observe/scope.ts`'s `mergeScope`: an explicit
+  # per-call `user:` wins outright over the ambient one; `tags`/`contexts`
+  # shallow-merge with the override's keys winning on collision;
+  # breadcrumbs concatenate (ambient trail first, then any one-off
+  # breadcrumbs passed for this one call).
+  #
+  # `user:` distinguishes "not given" from "explicitly `nil`" via the
+  # `Alplus::UNSET` sentinel default, mirroring the JS SDK's
+  # `overrides.user !== undefined` check: `Client` passes `Alplus::UNSET`
+  # through when its own `user:` param wasn't given by the caller, so a
+  # caller CAN pass `user: nil` to clear the ambient user for one capture
+  # rather than always falling back to it.
+  module ScopeMerge
+    module_function
+
+    def merge(ambient:, user:, tags:, contexts:, breadcrumbs:)
+      {
+        user: user.equal?(Alplus::UNSET) ? ambient[:user] : user,
+        tags: ambient[:tags].merge(tags || {}),
+        contexts: ambient[:contexts].merge(contexts || {}),
+        breadcrumbs: ambient[:breadcrumbs] + (breadcrumbs || [])
+      }
+    end
+  end
+end

data/lib/alplus/scrubber.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Alplus
+  # Default PII scrubbing applied to every captured item BEFORE
+  # `config.before_send` runs (mirrors Sentry's built-in data scrubber).
+  # Deep-walks `context`/`contexts`/`tags`/`user` (nested hashes and
+  # arrays) and replaces any value whose key matches `config.scrub_fields`
+  # (case-insensitive substring match, so `"user_password"` is caught by
+  # the `"password"` entry) with `"[FILTERED]"`.
+  #
+  # Runs against the already-built wire item hash (post `Envelope.*_item`),
+  # not the raw call-site args -- one scrub point regardless of whether the
+  # value came from an explicit `context:`/`tags:`/`user:` argument or the
+  # ambient `Scope`.
+  module Scrubber
+    DEFAULT_SCRUB_FIELDS = %w[
+      password passwd secret token authorization api_key apikey
+      access_token cookie csrf ssn credit_card card_number
+    ].freeze
+
+    REDACTED = "[FILTERED]"
+    # `breadcrumbs` is included so structured secrets in a crumb's `data`
+    # hash (and any secret-keyed value an integration adds) are redacted.
+    # A crumb's free-text `message` is NOT value-scrubbed -- key-based
+    # scrubbing cannot see into an arbitrary string, same as Sentry. Do
+    # not put a raw secret in a breadcrumb message.
+    SCRUBBED_KEYS = %i[context contexts tags user breadcrumbs].freeze
+
+    module_function
+
+    # Returns a new item hash with sensitive values redacted. Never raises:
+    # an internal error returns the item unscrubbed rather than drop a real
+    # event over a scrubbing bug -- capture must not be less reliable than
+    # scrubbing is broken.
+    def scrub(item, fields)
+      return item if fields.nil? || fields.empty?
+
+      normalized_fields = fields.map { |f| f.to_s.downcase }
+      scrubbed = SCRUBBED_KEYS.each_with_object({}) do |key, out|
+        next unless item.key?(key)
+
+        out[key] = deep_scrub(item[key], normalized_fields)
+      end
+      item.merge(scrubbed)
+    rescue StandardError
+      item
+    end
+
+    def deep_scrub(value, fields)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, val), out|
+          out[key] = sensitive_key?(key, fields) ? REDACTED : deep_scrub(val, fields)
+        end
+      when Array
+        value.map { |v| deep_scrub(v, fields) }
+      else
+        value
+      end
+    end
+
+    def sensitive_key?(key, fields)
+      normalized_key = key.to_s.downcase
+      fields.any? { |field| normalized_key.include?(field) }
+    end
+  end
+end

data/lib/alplus/session.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Alplus
+  # Request-scoped session-health tracker for AL+ Observe's crash-free
+  # sessions metric (issue #12). One request = one session, Sentry
+  # "request-mode" style: `Alplus::RackMiddleware` opens it, this class
+  # accumulates its outcome as the request runs, and the middleware closes
+  # it once `@app.call` returns (or raises).
+  #
+  # State lives on `Thread.current`, exactly like `Scope` and for the same
+  # reason: a thread-pool server (Puma, Passenger) reuses OS threads across
+  # requests, so this must be reset per request rather than shared.
+  #
+  # Three outcomes, in ascending severity, matching
+  # ARCHITECTURE.md's decision #2 (Sentry-aligned):
+  #
+  #   * `:healthy` -- the request completed with no captured error.
+  #   * `:errored` -- the request captured a handled error (any
+  #     `Alplus.capture_exception`/`capture_message` at level
+  #     `"error"`/`"fatal"`).
+  #   * `:crashed` -- the request raised an exception that propagated,
+  #     unhandled, up through `RackMiddleware`. Only this state counts
+  #     against crash-free sessions.
+  #
+  # Severity only ever increases within one request: `mark_errored` is a
+  # no-op once `mark_crashed` has run (`RackMiddleware`'s rescue calls
+  # `Alplus.capture_exception` for the crash itself, which would otherwise
+  # downgrade the outcome back to `:errored`).
+  class Session
+    THREAD_KEY = :alplus_session
+    private_constant :THREAD_KEY
+
+    SEVERITY = { healthy: 0, errored: 1, crashed: 2 }.freeze
+    private_constant :SEVERITY
+
+    class << self
+      # The current thread/fiber's session, or `nil` if none was started
+      # (e.g. outside `RackMiddleware`, such as a background job).
+      def current
+        Thread.current[THREAD_KEY]
+      end
+
+      # Replaces the current thread's session with a fresh one and yields;
+      # restores whatever session (if any) was active before, even if the
+      # block raises. `RackMiddleware` wraps each request in this so a
+      # session from request A never leaks into request B on a reused
+      # thread-pool thread.
+      def with_clean_session
+        previous = Thread.current[THREAD_KEY]
+        Thread.current[THREAD_KEY] = new
+        yield
+      ensure
+        Thread.current[THREAD_KEY] = previous
+      end
+    end
+
+    attr_reader :id, :status, :started_at
+
+    def initialize
+      @id = Id.generate_session_id
+      @status = :healthy
+      @started_at = Time.now.utc
+    end
+
+    # Marks the session `:errored`, unless it is already `:crashed`.
+    def mark_errored
+      bump(:errored)
+    end
+
+    # Marks the session `:crashed`. Terminal: never downgraded within one request.
+    def mark_crashed
+      bump(:crashed)
+    end
+
+    private
+
+    def bump(new_status)
+      @status = new_status if SEVERITY.fetch(new_status) > SEVERITY.fetch(@status)
+    end
+  end
+end

data/lib/alplus/sidekiq.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Alplus
+  # Optional Sidekiq integration. Namespaced under `Alplus::Sidekiq` (not
+  # top-level) so this file never collides with the real `::Sidekiq`
+  # constant it wraps -- `ErrorHandler` below refers to it explicitly via
+  # `::Sidekiq` wherever the ambiguity would otherwise resolve to
+  # `Alplus::Sidekiq` instead.
+  #
+  # This whole file is safe to load unconditionally (it defines classes,
+  # nothing more) -- `alplus.rb` only `require_relative`s it when
+  # `defined?(::Sidekiq)` is already true, and `install!` itself re-checks
+  # that guard, so a host app that never loads the `sidekiq` gem never
+  # pays for or activates any of this. The gem's runtime dependency list
+  # stays empty either way (`sidekiq` is never `require`d from here).
+  module Sidekiq
+    # Sidekiq server middleware: captures a job's raised exception with
+    # job context (class, queue, scrubbed args), then RE-RAISES so
+    # Sidekiq's own retry/dead-set handling still runs unchanged -- this
+    # is an observer, not an error handler that swallows failures.
+    class ErrorHandler
+      def call(worker, job, queue)
+        yield
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        capture(worker, job, queue, e)
+        raise
+      end
+
+      private
+
+      def capture(worker, job, queue, exception)
+        Alplus.capture_exception(
+          exception,
+          mechanism: "sidekiq",
+          contexts: { job: job_context(worker, job, queue) }
+        )
+      rescue StandardError
+        nil
+      end
+
+      def job_context(worker, job, queue)
+        {
+          class: job["class"] || job["wrapped"] || worker.class.name,
+          queue: queue || job["queue"],
+          jid: job["jid"],
+          args: Scrubber.deep_scrub(job["args"], Alplus.configuration.scrub_fields.map { |f| f.to_s.downcase })
+        }.compact
+      end
+    end
+
+    class << self
+      # Idempotent: installs `ErrorHandler` onto Sidekiq's server
+      # middleware chain exactly once per process, even if called more
+      # than once (e.g. re-evaluated in a reloading dev environment).
+      def install!
+        return if @installed
+        return unless defined?(::Sidekiq) && ::Sidekiq.respond_to?(:configure_server)
+
+        ::Sidekiq.configure_server do |config|
+          next unless config.respond_to?(:server_middleware)
+
+          config.server_middleware do |chain|
+            chain.add Alplus::Sidekiq::ErrorHandler unless chain.exists?(Alplus::Sidekiq::ErrorHandler)
+          end
+        end
+        @installed = true
+      end
+
+      # Test-only: lets a spec re-drive `install!`. Not called by
+      # production code.
+      def reset!
+        @installed = false
+      end
+    end
+  end
+end