NatsWork::Client

Job dispatching client for the NatsWork distributed job processing system.

Installation

Add to your application's Gemfile:

gem 'natswork-client'

And execute:

$ bundle install

Configuration

NatsWork::Client.configure do |config|
  config.nats_url = ENV['NATS_URL'] || 'nats://localhost:4222'
  config.default_timeout = 30.0
  config.logger = Rails.logger
end

Usage

Defining Jobs

Jobs are defined as classes that include NatsWork::Job:

class ProcessPaymentJob < NatsWork::Job
  queue 'payments'
  retries 3
  timeout 30

  def perform(order_id, amount)
    order = Order.find(order_id)
    PaymentService.charge(order, amount)
  end
end

Dispatching Jobs

Asynchronous Execution

Fire-and-forget job execution:

# Basic async dispatch
ProcessPaymentJob.perform_async(order.id, 99.99)

# With options
ProcessPaymentJob.perform_in(5.minutes, order.id, 99.99)
ProcessPaymentJob.perform_at(Time.now + 1.hour, order.id, 99.99)

Synchronous Execution

Wait for job completion and get result:

# Wait for result with timeout
result = ProcessPaymentJob.perform_sync(order.id, 99.99, timeout: 10.0)

# Handle timeout
begin
  result = ProcessPaymentJob.perform_sync(order.id, 99.99, timeout: 5.0)
rescue NatsWork::TimeoutError => e
  Rails.logger.error "Job timed out: #{e.message}"
end

Advanced Features

Job Options

class CustomJob < NatsWork::Job
  # Routing
  queue 'critical'

  # Retries
  retries 5
  retry_backoff :exponential

  # Timeout
  timeout 60

  # Unique jobs
  unique_for 1.hour

  def perform(*)
    # Job logic
  end
end

Middleware

Add custom middleware for cross-cutting concerns:

class LoggingMiddleware
  def call(job, message)
    Rails.logger.info "Dispatching #{job.class.name}"
    yield
  ensure
    Rails.logger.info "Dispatched #{job.class.name}"
  end
end

NatsWork::Client.configure do |config|
  config.client_middleware do |chain|
    chain.add LoggingMiddleware
  end
end

Callbacks

class NotificationJob < NatsWork::Job
  before_enqueue :validate_recipient
  after_enqueue :log_dispatch

  def perform(recipient_id, message)
    # Send notification
  end

  private

  def validate_recipient
    # Validation logic
  end

  def log_dispatch
    Rails.logger.info "Notification queued"
  end
end

Rails Integration

Generators

# Generate a new job
rails generate natswork:job ProcessOrder

# Generate configuration
rails generate natswork:install

ActiveJob Adapter

Use NatsWork as an ActiveJob backend:

# config/application.rb
config.active_job.queue_adapter = :natswork

Auto-loading

Jobs in app/jobs are automatically loaded in Rails.

Testing

# In your test helper
require 'natswork/testing'

# Inline mode - jobs run immediately
NatsWork::Testing.inline! do
  ProcessPaymentJob.perform_async(order.id, 99.99)
  # Job has already completed
end

# Fake mode - jobs are stored for assertions
NatsWork::Testing.fake! do
  ProcessPaymentJob.perform_async(order.id, 99.99)

  expect(ProcessPaymentJob).to have_enqueued_job(order.id, 99.99)
end

API Reference

See the API documentation for detailed class and method documentation.

Contributing

Bug reports and pull requests are welcome at https://github.com/yourusername/natswork.

License

MIT License