Class: Tasker::StepHandler::Api

Inherits:
Base
  • Object
show all
Includes:
Concerns::EventPublisher
Defined in:
lib/tasker/step_handler/api.rb

Overview

Handles API-based workflow steps by making HTTP requests and processing responses with backoff/retry support

Examples:

Creating a custom API step handler

class MyApiHandler < Tasker::StepHandler::Api
  def process(task, sequence, step)
    connection.post('/endpoint', task.context)
  end
end

Using error types for better retry control

class MyApiHandler < Tasker::StepHandler::Api
  def process(task, sequence, step)
    response = connection.post('/endpoint', task.context)

    case response.status
    when 400, 422
      # Client errors - don't retry, these are permanent failures
      raise Tasker::PermanentError.new(
        "Invalid request: #{response.body}",
        error_code: 'VALIDATION_ERROR'
      )
    when 429
      # Rate limited - retry with server-suggested delay
      retry_after = response.headers['retry-after']&.to_i || 60
      raise Tasker::RetryableError.new(
        "Rate limited by API",
        retry_after: retry_after
      )
    when 500..599
      # Server errors - let Tasker's exponential backoff handle retry timing
      raise Tasker::RetryableError.new(
        "Server error: #{response.status}",
        context: { status: response.status, endpoint: '/endpoint' }
      )
    end

    response
  end
end

Defined Under Namespace

Classes: Config

Constant Summary

Constants included from Concerns::StructuredLogging

Concerns::StructuredLogging::CORRELATION_ID_KEY

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Concerns::EventPublisher

#infer_step_event_type_from_state, #publish_custom_event, #publish_no_viable_steps, #publish_step_backoff, #publish_step_before_handle, #publish_step_cancelled, #publish_step_completed, #publish_step_event_for_context, #publish_step_failed, #publish_step_retry_requested, #publish_step_started, #publish_steps_execution_completed, #publish_steps_execution_started, #publish_task_completed, #publish_task_enqueue, #publish_task_failed, #publish_task_finalization_completed, #publish_task_finalization_started, #publish_task_pending_transition, #publish_task_reenqueue_delayed, #publish_task_reenqueue_failed, #publish_task_reenqueue_requested, #publish_task_reenqueue_started, #publish_task_retry_requested, #publish_task_started, #publish_viable_steps_discovered, #publish_workflow_state_unclear, #publish_workflow_step_completed, #publish_workflow_task_started

Methods inherited from Base

custom_event_configuration

Methods included from Concerns::StructuredLogging

#correlation_id, #correlation_id=, #log_exception, #log_orchestration_event, #log_performance_event, #log_step_event, #log_structured, #log_task_event, #with_correlation_id

Constructor Details

#initialize(config: Config.new) {|Faraday::Connection| ... } ⇒ Api

Creates a new API step handler

Parameters:

  • config (Config) (defaults to: Config.new) —

    The configuration for this handler

Yields:

  • (Faraday::Connection) —

    Optional block for configuring the Faraday connection



128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/tasker/step_handler/api.rb', line 128

def initialize(config: Config.new, &connection_block)
  super(config: config)

  # Initialize orchestration components
  @response_processor = Tasker::Orchestration::ResponseProcessor.new
  @backoff_calculator = Tasker::Orchestration::BackoffCalculator.new(config: config)
  @connection_builder = Tasker::Orchestration::ConnectionBuilder.new

  # Build connection using orchestration component
  @connection = @connection_builder.build_connection(config, &connection_block)
end

Instance Attribute Details

#config ⇒ Config (readonly)

Returns The configuration for this API handler.

Returns:

  • (Config) —

    The configuration for this API handler



59
60
61
 
# File 'lib/tasker/step_handler/api.rb', line 59

def config
  @config
end

#connection ⇒ Faraday::Connection (readonly)

Returns The Faraday connection for making HTTP requests.

Returns:

  • (Faraday::Connection) —

    The Faraday connection for making HTTP requests



56
57
58
 
# File 'lib/tasker/step_handler/api.rb', line 56

def connection
  @connection
end

Instance Method Details

#handle(task, sequence, step) ⇒ void

This method returns an undefined value.

Framework coordination method for API step handlers

⚠️ NEVER OVERRIDE THIS METHOD - Framework-only code This method coordinates the API-specific workflow around the developer's process() method

Parameters:



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/tasker/step_handler/api.rb', line 149

def handle(task, sequence, step)
  # Publish step started event
  publish_step_started(step)

  # Fire the before_handle event for compatibility (matches base class pattern)
  publish_step_before_handle(step)

  begin
    response = execute_api_workflow(task, sequence, step)
    publish_step_completed(step)
    response
  rescue StandardError => e
    handle_execution_error(step, e)
    raise
  end
end

#process(task, sequence, step) ⇒ Faraday::Response, Hash

Developer extension point for API step handlers

✅ IMPLEMENT THIS METHOD: This is your extension point for API business logic

This is where you implement your specific HTTP request logic. Use the provided connection object to make requests and return the response.

The framework will automatically:

  • Publish step_started before calling this method
  • Handle response processing, error detection, and backoff
  • Publish step_completed after this method succeeds
  • Publish step_failed if this method raises an exception

Examples: def process(task, sequence, step) user_id = task.context['user_id'] connection.get("/users/#user_id") end

def process(task, sequence, step) connection.post('/orders', task.context) end

Parameters:

Returns:

  • (Faraday::Response, Hash) —

    The API response

Raises:

  • (NotImplementedError) 


193
194
195
 
# File 'lib/tasker/step_handler/api.rb', line 193

def process(task, sequence, step)
  raise NotImplementedError, 'API step handler subclasses must implement the process method to make HTTP requests'
end