Class: X402::SettlementWorker

Inherits:
Object
  • Object
show all
Defined in:
lib/x402/settlement_worker.rb

Overview

Background thread that broadcasts transactions to ARC with exponential backoff retry. Uses Ruby stdlib Thread + Queue (zero dependencies).

Any object responding to +#enqueue(tx_binary)+ satisfies the pluggable worker interface expected by PayGateway's async settlement path.

Examples:

With failure callback

worker = X402::SettlementWorker.new(
  arc_client: arc,
  on_failure: ->(tx_binary, error) { logger.error("Settlement failed: #{error}") }
)

Constant Summary collapse

ACCEPTABLE_STATUSES = 
%w[SEEN_ON_NETWORK ANNOUNCED_TO_NETWORK MINED].freeze
DEFAULT_MAX_QUEUE = 
1000

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(arc_client:, max_retries: 5, max_queue: DEFAULT_MAX_QUEUE, on_failure: nil) ⇒ SettlementWorker

Returns a new instance of SettlementWorker.

Parameters:

  • arc_client (#broadcast) —

    ARC client for broadcasting

  • max_retries (Integer) (defaults to: 5) —

    retry attempts before giving up (default 5)

  • max_queue (Integer) (defaults to: DEFAULT_MAX_QUEUE) —

    maximum queued transactions (default 1000). Raises +X402::VerificationError+ (503) when full.

  • on_failure (#call, nil) (defaults to: nil) —

    callback invoked with +(tx_binary, error)+ when all retries are exhausted. Default nil (silent drop).



27
28
29
30
31
32
33
34
35
 
# File 'lib/x402/settlement_worker.rb', line 27

def initialize(arc_client:, max_retries: 5, max_queue: DEFAULT_MAX_QUEUE, on_failure: nil)
  @arc_client = arc_client
  @max_retries = max_retries
  @max_queue = max_queue
  @on_failure = on_failure
  @queue = Queue.new
  @thread = nil
  @mutex = Mutex.new
end

Instance Attribute Details

#max_queue ⇒ Object (readonly)

Returns the value of attribute max_queue.



19
20
21
 
# File 'lib/x402/settlement_worker.rb', line 19

def max_queue
  @max_queue
end

#max_retries ⇒ Object (readonly)

Returns the value of attribute max_retries.



19
20
21
 
# File 'lib/x402/settlement_worker.rb', line 19

def max_retries
  @max_retries
end

Instance Method Details

#enqueue(tx_binary) ⇒ Object

Enqueue a transaction for background broadcast.

Parameters:

  • tx_binary (String) —

    raw transaction bytes

Raises:



41
42
43
44
45
46
 
# File 'lib/x402/settlement_worker.rb', line 41

def enqueue(tx_binary)
  raise VerificationError.new("settlement queue full — try again later", status: 503) if @queue.size >= @max_queue

  ensure_thread_running
  @queue.push(tx_binary)
end

#stop ⇒ void

This method returns an undefined value.

Drain the queue and stop the background thread. Safe to call when no thread has started (no-op).



52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/x402/settlement_worker.rb', line 52

def stop
  thread_to_join = nil
  @mutex.synchronize do
    return unless @thread&.alive?

    @queue.push(:shutdown)
    thread_to_join = @thread
    @thread = nil
  end
  thread_to_join&.join
end