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) 


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

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).



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

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) 


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

def middleware_registered?
  @middleware_registered == true
end

.register! ⇒ Object

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



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

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

.register_death_handler! ⇒ Object

Registers just the death handler (for exhausted retry reporting)



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

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)



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

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) 


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

def registered?
  @registered == true
end

.reset! ⇒ Object

Reset state (for testing)



141
142
143
144
145
146
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 141

def reset!
  @registered = false
  @middleware_registered = false
  @death_handler_registered = false
  @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) 


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

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:



106
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
 
# File 'lib/axn/async/adapters/sidekiq/auto_configure.rb', line 106

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) 


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

def validated?
  @validated == true
end