Module: CMDx::Middlewares::Correlate

Extended by:
Correlate
Included in:
Correlate
Defined in:
lib/cmdx/middlewares/correlate.rb

Overview

Middleware for correlating task executions with unique identifiers.

The Correlate middleware provides thread-safe correlation ID management for tracking task execution flows across different operations. It automatically generates correlation IDs when none are provided and stores them in task result metadata for traceability.

Constant Summary collapse

THREAD_KEY = 
:cmdx_correlate

Instance Method Summary collapse

Instance Method Details

#call(task, **options) { ... } ⇒ Object

Middleware entry point that applies correlation ID logic to task execution.

Evaluates the condition from options and applies correlation ID handling if enabled. Generates or retrieves correlation IDs based on the :id option and stores them in task result metadata.

Examples:

Basic usage with automatic ID generation

Correlate.call(task, &block)

Use custom correlation ID

Correlate.call(task, id: "custom-123", &block)

Use task method for ID

Correlate.call(task, id: :correlation_id, &block)

Use proc for dynamic ID generation

Correlate.call(task, id: -> { "dynamic-#{Time.now.to_i}" }, &block)

Conditional correlation

Correlate.call(task, if: :enable_correlation, &block)

Parameters:

  • task (Task) —

    The task being executed

  • options (Hash) —

    Configuration options for correlation

Options Hash (**options):

  • :id (Symbol, Proc, Object, nil) —

    The correlation ID source

  • :if (Symbol, Proc, Object, nil) —

    Condition to enable correlation

  • :unless (Symbol, Proc, Object, nil) —

    Condition to disable correlation

Yields:

  • The task execution block

Returns:

  • (Object) —

    The result of task execution



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/cmdx/middlewares/correlate.rb', line 106

def call(task, **options, &)
  return yield unless Utils::Condition.evaluate(task, options)

  correlation_id = task.result.metadata[:correlation_id] ||=
    id ||
    case callable = options[:id]
    when Symbol then task.send(callable)
    when Proc then task.instance_eval(&callable)
    else
      if callable.respond_to?(:call)
        callable.call(task)
      else
        callable || id || Identifier.generate
      end
    end

  use(correlation_id, &)
end

#clear ⇒ nil

Clears the current correlation ID from thread-local storage.

Examples:

Clear correlation ID

Correlate.clear

Returns:

  • (nil) —

    Always returns nil



51
52
53
 
# File 'lib/cmdx/middlewares/correlate.rb', line 51

def clear
  Thread.current[THREAD_KEY] = nil
end

#id ⇒ String?

Retrieves the current correlation ID from thread-local storage.

Examples:

Get current correlation ID

Correlate.id # => "550e8400-e29b-41d4-a716-446655440000"

Returns:

  • (String, nil) —

    The current correlation ID or nil if not set



26
27
28
 
# File 'lib/cmdx/middlewares/correlate.rb', line 26

def id
  Thread.current[THREAD_KEY]
end

#id=(id) ⇒ String

Sets the correlation ID in thread-local storage.

Examples:

Set correlation ID

Correlate.id = "abc-123-def"

Parameters:

  • id (String) —

    The correlation ID to set

Returns:

  • (String) —

    The set correlation ID



39
40
41
 
# File 'lib/cmdx/middlewares/correlate.rb', line 39

def id=(id)
  Thread.current[THREAD_KEY] = id
end

#use(new_id) { ... } ⇒ Object

Temporarily uses a new correlation ID for the duration of a block. Restores the previous ID after the block completes, even if an error occurs.

Examples:

Use temporary correlation ID

Correlate.use("temp-id") do
  # Operations here use "temp-id"
  perform_operation
end
# Previous ID is restored

Parameters:

  • new_id (String) —

    The correlation ID to use temporarily

Yields:

  • The block to execute with the new correlation ID

Returns:

  • (Object) —

    The result of the yielded block



70
71
72
73
74
75
76
 
# File 'lib/cmdx/middlewares/correlate.rb', line 70

def use(new_id)
  old_id = id
  self.id = new_id
  yield
ensure
  self.id = old_id
end