Module: Operandi::CallbackDsl

Included in:
Base
Defined in:
lib/operandi/callbacks.rb

Overview

Class methods for registering callbacks. Extend this module in your service class to get callback DSL methods.

Examples:

class MyService < Operandi::Base
  before_service_run :setup
  after_service_run :cleanup
end

Instance Method Summary collapse

Instance Method Details

#after_service_run(method_name = nil) {|service| ... } ⇒ void

This method returns an undefined value.

Registers a callback to run after the service completes (regardless of success/failure).

Examples:

With method name

after_service_run :cleanup

With block

after_service_run { |service| Rails.logger.info("Done!") }

Parameters:

  • method_name (Symbol, nil) (defaults to: nil) —

    name of the instance method to call

Yields:

  • (service) —

    block to execute if no method name provided

Yield Parameters:

Raises:

  • (ArgumentError) —

    if neither method name nor block is provided



250
251
252
 
# File 'lib/operandi/callbacks.rb', line 250

def after_service_run(method_name = nil, &)
  register_callback(:after_service_run, method_name, &)
end

#after_step_run(method_name = nil) {|service, step_name| ... } ⇒ void

This method returns an undefined value.

Registers a callback to run after each step executes.

Examples:

With method name

after_step_run :log_step_complete

With block

after_step_run { |service, step_name| puts "Finished #{step_name}" }

Parameters:

  • method_name (Symbol, nil) (defaults to: nil) —

    name of the instance method to call

Yields:

  • (service, step_name) —

    block to execute if no method name provided

Yield Parameters:

  • service (Operandi::Base) —

    the service instance

  • step_name (Symbol) —

    the name of the step that just ran

Raises:

  • (ArgumentError) —

    if neither method name nor block is provided



139
140
141
 
# File 'lib/operandi/callbacks.rb', line 139

def after_step_run(method_name = nil, &)
  register_callback(:after_step_run, method_name, &)
end

#all_callbacks_for(event) ⇒ Array<Symbol, Proc>

Get all callbacks for an event including inherited ones.

Parameters:

  • event (Symbol) —

    the callback event name

Returns:

  • (Array<Symbol, Proc>) —

    all callbacks for this event



322
323
324
325
326
327
328
329
330
 
# File 'lib/operandi/callbacks.rb', line 322

def all_callbacks_for(event)
  if superclass.respond_to?(:all_callbacks_for)
    inherited = superclass.all_callbacks_for(event)
  else
    inherited = []
  end

  inherited + callbacks_for(event)
end

#around_service_run(method_name = nil) {|service| ... } ⇒ void

This method returns an undefined value.

Registers an around callback that wraps the entire service execution. The callback must yield to execute the service.

Examples:

With method name

around_service_run :with_timing

def with_timing(service)
  start = Time.now
  yield
  puts "Took #{Time.now - start}s"
end

Parameters:

  • method_name (Symbol, nil) (defaults to: nil) —

    name of the instance method to call

Yields:

  • (service) —

    block to execute if no method name provided

Yield Parameters:

Raises:

  • (ArgumentError) —

    if neither method name nor block is provided



271
272
273
 
# File 'lib/operandi/callbacks.rb', line 271

def around_service_run(method_name = nil, &)
  register_callback(:around_service_run, method_name, &)
end

#around_step_run(method_name = nil) {|service, step_name| ... } ⇒ void

This method returns an undefined value.

Registers an around callback that wraps each step execution. The callback must yield to execute the step.

Examples:

With method name

around_step_run :with_step_timing

def with_step_timing(service, step_name)
  start = Time.now
  yield
  puts "#{step_name} took #{Time.now - start}s"
end

Parameters:

  • method_name (Symbol, nil) (defaults to: nil) —

    name of the instance method to call

Yields:

  • (service, step_name) —

    block to execute if no method name provided

Yield Parameters:

  • service (Operandi::Base) —

    the service instance

  • step_name (Symbol) —

    the name of the step being wrapped

Raises:

  • (ArgumentError) —

    if neither method name nor block is provided



161
162
163
 
# File 'lib/operandi/callbacks.rb', line 161

def around_step_run(method_name = nil, &)
  register_callback(:around_step_run, method_name, &)
end

#before_service_run(method_name = nil) {|service| ... } ⇒ void

This method returns an undefined value.

Registers a callback to run before the service starts executing.

Examples:

With method name

before_service_run :log_start

With block

before_service_run { |service| Rails.logger.info("Starting #{service.class.name}") }

Parameters:

  • method_name (Symbol, nil) (defaults to: nil) —

    name of the instance method to call

Yields:

  • (service) —

    block to execute if no method name provided

Yield Parameters:

Raises:

  • (ArgumentError) —

    if neither method name nor block is provided



233
234
235
 
# File 'lib/operandi/callbacks.rb', line 233

def before_service_run(method_name = nil, &)
  register_callback(:before_service_run, method_name, &)
end

#before_step_run(method_name = nil) {|service, step_name| ... } ⇒ void

This method returns an undefined value.

Registers a callback to run before each step executes.

Examples:

With method name

before_step_run :log_step_start

With block

before_step_run { |service, step_name| puts "Starting #{step_name}" }

Parameters:

  • method_name (Symbol, nil) (defaults to: nil) —

    name of the instance method to call

Yields:

  • (service, step_name) —

    block to execute if no method name provided

Yield Parameters:

  • service (Operandi::Base) —

    the service instance

  • step_name (Symbol) —

    the name of the step about to run

Raises:

  • (ArgumentError) —

    if neither method name nor block is provided



121
122
123
 
# File 'lib/operandi/callbacks.rb', line 121

def before_step_run(method_name = nil, &)
  register_callback(:before_step_run, method_name, &)
end

#callbacks_for(event) ⇒ Array<Symbol, Proc>

Get callbacks defined in this class for a specific event.

Parameters:

  • event (Symbol) —

    the callback event name

Returns:

  • (Array<Symbol, Proc>) —

    callbacks for this event



313
314
315
316
 
# File 'lib/operandi/callbacks.rb', line 313

def callbacks_for(event)
  @callbacks ||= {}
  @callbacks[event] ||= []
end

#on_service_failure(method_name = nil) {|service| ... } ⇒ void

This method returns an undefined value.

Registers a callback to run when the service completes with errors.

Examples:

With method name

on_service_failure :log_error

With block

on_service_failure { |service| Rails.logger.error(service.errors.full_messages) }

Parameters:

  • method_name (Symbol, nil) (defaults to: nil) —

    name of the instance method to call

Yields:

  • (service) —

    block to execute if no method name provided

Yield Parameters:

Raises:

  • (ArgumentError) —

    if neither method name nor block is provided



305
306
307
 
# File 'lib/operandi/callbacks.rb', line 305

def on_service_failure(method_name = nil, &)
  register_callback(:on_service_failure, method_name, &)
end

#on_service_success(method_name = nil) {|service| ... } ⇒ void

This method returns an undefined value.

Registers a callback to run when the service completes successfully (without errors).

Examples:

With method name

on_service_success :send_notification

With block

on_service_success { |service| NotificationMailer.success(service.user).deliver_later }

Parameters:

  • method_name (Symbol, nil) (defaults to: nil) —

    name of the instance method to call

Yields:

  • (service) —

    block to execute if no method name provided

Yield Parameters:

Raises:

  • (ArgumentError) —

    if neither method name nor block is provided



288
289
290
 
# File 'lib/operandi/callbacks.rb', line 288

def on_service_success(method_name = nil, &)
  register_callback(:on_service_success, method_name, &)
end

#on_step_crash(method_name = nil) {|service, step_name, exception| ... } ⇒ void

This method returns an undefined value.

Registers a callback to run when a step raises an exception.

Examples:

With method name

on_step_crash :report_crash

With block

on_step_crash { |service, step_name, error| Sentry.capture_exception(error) }

Parameters:

  • method_name (Symbol, nil) (defaults to: nil) —

    name of the instance method to call

Yields:

  • (service, step_name, exception) —

    block to execute if no method name provided

Yield Parameters:

  • service (Operandi::Base) —

    the service instance

  • step_name (Symbol) —

    the name of the crashed step

  • exception (Exception) —

    the exception that was raised

Raises:

  • (ArgumentError) —

    if neither method name nor block is provided



216
217
218
 
# File 'lib/operandi/callbacks.rb', line 216

def on_step_crash(method_name = nil, &)
  register_callback(:on_step_crash, method_name, &)
end

#on_step_failure(method_name = nil) {|service, step_name| ... } ⇒ void

This method returns an undefined value.

Registers a callback to run when a step fails (adds errors).

Examples:

With method name

on_step_failure :handle_step_error

With block

on_step_failure { |service, step_name| Rails.logger.error("Step #{step_name} failed") }

Parameters:

  • method_name (Symbol, nil) (defaults to: nil) —

    name of the instance method to call

Yields:

  • (service, step_name) —

    block to execute if no method name provided

Yield Parameters:

  • service (Operandi::Base) —

    the service instance

  • step_name (Symbol) —

    the name of the failed step

Raises:

  • (ArgumentError) —

    if neither method name nor block is provided



197
198
199
 
# File 'lib/operandi/callbacks.rb', line 197

def on_step_failure(method_name = nil, &)
  register_callback(:on_step_failure, method_name, &)
end

#on_step_success(method_name = nil) {|service, step_name| ... } ⇒ void

This method returns an undefined value.

Registers a callback to run when a step completes successfully (without adding errors).

Examples:

With method name

on_step_success :track_step_success

With block

on_step_success { |service, step_name| Analytics.track("step.success", step: step_name) }

Parameters:

  • method_name (Symbol, nil) (defaults to: nil) —

    name of the instance method to call

Yields:

  • (service, step_name) —

    block to execute if no method name provided

Yield Parameters:

  • service (Operandi::Base) —

    the service instance

  • step_name (Symbol) —

    the name of the successful step

Raises:

  • (ArgumentError) —

    if neither method name nor block is provided



179
180
181
 
# File 'lib/operandi/callbacks.rb', line 179

def on_step_success(method_name = nil, &)
  register_callback(:on_step_success, method_name, &)
end