Module: Axn::Async::Adapters::Sidekiq::AutoConfigure

Defined in:
lib/axn/async/adapters/sidekiq/auto_configure.rb

Overview

Auto-configures Sidekiq server middleware and death handlers for Axn.

This is automatically called when you set Axn.config.async_exception_reporting to a mode other than :every_attempt. You can also call it manually:

Axn::Async::Adapters::Sidekiq::AutoConfigure.register!

Class Method Summary collapse

Class Method Details

.death_handler_registered? ⇒ Boolean

Returns:

  • (Boolean) 


28
29
30
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 28

def death_handler_registered?
  @death_handler_registered == true
end

.ensure_registered_for_current_config! ⇒ Object

Ensures middleware and death handler are registered for the current Axn.config.async_exception_reporting mode. Call when the Sidekiq adapter is included (e.g. via async :sidekiq or default async) so that default mode works without the app setting async_exception_reporting explicitly. Safe to call multiple times - register! is idempotent. No-ops when Sidekiq is a minimal stub (e.g. in unit tests without full Sidekiq).



52
53
54
55
56
57
58
59
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 52

def ensure_registered_for_current_config!
  return unless defined?(::Sidekiq) && ::Sidekiq.respond_to?(:configure_server)

  mode = Axn.config.async_exception_reporting
  return if mode == :every_attempt

  register!
end

.middleware_registered? ⇒ Boolean

Returns:

  • (Boolean) 


24
25
26
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 24

def middleware_registered?
  @middleware_registered == true
end

.register! ⇒ Object

Registers both middleware and death handler. Safe to call multiple times - will not duplicate registrations.



63
64
65
66
67
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 63

def register!
  register_middleware!
  register_death_handler!
  @registered = true
end

.register_death_handler! ⇒ Object

Registers just the death handler (for exhausted retry reporting)



90
91
92
93
94
95
96
97
98
99
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 90

def register_death_handler!
  return if death_handler_registered?
  return unless defined?(::Sidekiq)

  ::Sidekiq.configure_server do |config|
    config.death_handlers << DeathHandler unless config.death_handlers.include?(DeathHandler)
  end

  @death_handler_registered = true
end

.register_middleware! ⇒ Object

Registers just the middleware (for retry context tracking)



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 70

def register_middleware!
  return if middleware_registered?
  return unless defined?(::Sidekiq)

  ::Sidekiq.configure_server do |config|
    config.server_middleware do |chain|
      # Check if already added (in case of multiple configure_server calls)
      already_added = chain.any? do |entry|
        entry.klass == Middleware
      rescue StandardError
        false
      end
      chain.add Middleware unless already_added
    end
  end

  @middleware_registered = true
end

.registered? ⇒ Boolean

Returns:

  • (Boolean) 


20
21
22
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 20

def registered?
  @registered == true
end

.reset! ⇒ Object

Reset all state (for testing). Clears the registration flags along with the validation memo, so a spec that calls this can exercise register! again from a clean slate.



144
145
146
147
148
149
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 144

def reset!
  @registered = false
  @middleware_registered = false
  @death_handler_registered = false
  @validated = false
end

.reset_validation! ⇒ Object

Clears only the validation memo (for testing). @validated records that validate_configuration! already ran in this process, so clearing it makes validation re-run against a config that a spec just changed.

The registration flags stay put: register_middleware!/register_death_handler! install onto Sidekiq's actual global middleware chain and death-handler list once per process, and that installation cannot be undone or redone from here. Clearing the flags would make this in-memory record disagree with Sidekiq's real state — validate_configuration! would then read middleware_registered? as false and raise ConfigurationError even though the middleware is still installed.



161
162
163
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 161

def reset_validation!
  @validated = false
end

.skip_validation? ⇒ Boolean

Returns true if validation should be skipped. Skip when already validated, in Sidekiq test mode, or in a test environment.

Returns:

  • (Boolean) 


38
39
40
41
42
43
44
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 38

def skip_validation?
  return true if validated?
  return true if defined?(::Sidekiq::Testing) && ::Sidekiq::Testing.enabled?
  return true if ENV["RAILS_ENV"] == "test" || ENV["RACK_ENV"] == "test"

  false
end

.validate_configuration!(mode) ⇒ Object

Validates that required components are registered for the given config mode. Raises ConfigurationError with instructions if configuration is incomplete.

This is called once on first Sidekiq job execution to catch misconfiguration early. It checks whether register! was called, not whether Sidekiq has actually loaded the middleware (which happens when server starts).

Raises:



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 107

def validate_configuration!(mode)
  @validated = true
  return if mode == :every_attempt # No special requirements

  issues = []

  issues << "Sidekiq middleware not registered (required for retry context tracking)" unless middleware_registered?

  if %i[first_and_exhausted only_exhausted].include?(mode) && !death_handler_registered?
    issues << "Sidekiq death handler not registered (required for exhausted retry reporting)"
  end

  return if issues.empty?

  raise ConfigurationError, <<~MSG
    Axn async_exception_reporting is set to #{mode.inspect}, but Sidekiq is not fully configured:

    #{issues.map { |i| "  - #{i}" }.join("\n")}

    To fix, add this to your Sidekiq initializer (config/initializers/sidekiq.rb):

      Axn::Async::Adapters::Sidekiq::AutoConfigure.register!

    Or manually configure:

      Sidekiq.configure_server do |config|
        config.server_middleware do |chain|
          chain.add Axn::Async::Adapters::Sidekiq::Middleware
        end
        config.death_handlers << Axn::Async::Adapters::Sidekiq::DeathHandler
      end
  MSG
end

.validated? ⇒ Boolean

Returns:

  • (Boolean) 


32
33
34
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 32

def validated?
  @validated == true
end