Class: Servus::Events::Invocation

Inherits:
Object
  • Object
show all
Defined in:
lib/servus/events/invocation.rb

Overview

A normalized, executable representation of “call this service with these params.”

Routers return arrays of Invocation objects. The Bus collects them, deduplicates by #key (first wins), and calls #execute on each.

An Invocation separates identity (service + params) from *execution strategy* (async, queue, priority, etc.). The #key is derived only from the identity — two invocations that call the same service with the same params are considered duplicates regardless of their options.

Examples:

Sync invocation

Invocation.new(
  service: Rewards::Grant::Service,
  params:  { user_id: "abc-123" },
  options: {}
)

Async invocation with scheduling options

Invocation.new(
  service: Notifications::Send::Service,
  params:  { user_id: "abc-123" },
  options: { async: true, queue: :mailers, priority: 5 }
)

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(service:, params:, options: {}) ⇒ Invocation

Returns a new instance of Invocation.

Parameters:

  • service (Class) —

    the service class

  • params (Hash) —

    keyword arguments for the service

  • options (Hash) (defaults to: {}) —

    execution options



50
51
52
53
54
 
# File 'lib/servus/events/invocation.rb', line 50

def initialize(service:, params:, options: {})
  @service = service
  @params  = params
  @options = options
end

Instance Attribute Details

#options ⇒ Hash (readonly)

Returns execution options — async, queue, wait, wait_until, priority, job_options.

Returns:

  • (Hash) —

    execution options — async, queue, wait, wait_until, priority, job_options



45
46
47
 
# File 'lib/servus/events/invocation.rb', line 45

def options
  @options
end

#params ⇒ Hash (readonly)

Returns keyword arguments passed to the service.

Returns:

  • (Hash) —

    keyword arguments passed to the service



41
42
43
 
# File 'lib/servus/events/invocation.rb', line 41

def params
  @params
end

#service ⇒ Class (readonly)

Returns the service class to call (must respond to .call or .call_async).

Returns:

  • (Class) —

    the service class to call (must respond to .call or .call_async)



38
39
40
 
# File 'lib/servus/events/invocation.rb', line 38

def service
  @service
end

Instance Method Details

#execute ⇒ Servus::Support::Response, void

Executes the invocation.

Delegates to service.call for synchronous invocations or service.call_async for asynchronous ones. Async scheduling options (queue, wait, priority, etc.) are merged into the call_async kwargs.

Returns:



64
65
66
67
68
69
70
 
# File 'lib/servus/events/invocation.rb', line 64

def execute
  if options[:async]
    service.call_async(**params, **async_options)
  else
    service.call(**params)
  end
end

#key ⇒ String

A deterministic deduplication key derived from the service class and params. Two invocations with the same key are considered duplicates — the Bus keeps the first and skips the rest.

Options are intentionally excluded: identity is what to call, not how to call it.

Returns:

  • (String) —

    SHA-256 hex digest



80
81
82
 
# File 'lib/servus/events/invocation.rb', line 80

def key
  Digest::SHA256.hexdigest("#{service}:#{params.to_json}")
end