natswork-client 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 34b95584309b550018488327792c81595cc1c5a2483098001dc2daae636fad0e
+  data.tar.gz: 58607818cac88add344df5edd697bcc157bf187f6c49cd4b30ec1e6e29d1d89b
+SHA512:
+  metadata.gz: 5d5224d0a1cff03380b0d4913eadc547db7f7a1f58e758b7decfa3a4820348aaef50c8323b4a580a7f94016adbe63ec8ec5d3a03ab6e23410cf175200720c1c7
+  data.tar.gz: e52faff83deea12ff2a7a084b6b9fa2346779f4cbc859aacfd96f6a5ddc2b0d208a12bc36fa8add31cf9a1fe2209e3a63685e89b47d5ae730fd11501681f9cae

data/README.md

@@ -0,0 +1,201 @@
+# NatsWork::Client
+
+Job dispatching client for the NatsWork distributed job processing system.
+
+## Installation
+
+Add to your application's Gemfile:
+
+```ruby
+gem 'natswork-client'
+```
+
+And execute:
+
+    $ bundle install
+
+## Configuration
+
+```ruby
+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`:
+
+```ruby
+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:
+
+```ruby
+# 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:
+
+```ruby
+# 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
+
+```ruby
+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:
+
+```ruby
+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
+
+```ruby
+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
+
+```bash
+# Generate a new job
+rails generate natswork:job ProcessOrder
+
+# Generate configuration
+rails generate natswork:install
+```
+
+### ActiveJob Adapter
+
+Use NatsWork as an ActiveJob backend:
+
+```ruby
+# config/application.rb
+config.active_job.queue_adapter = :natswork
+```
+
+### Auto-loading
+
+Jobs in `app/jobs` are automatically loaded in Rails.
+
+## Testing
+
+```ruby
+# 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](https://rubydoc.info/gems/natswork-client) for detailed class and method documentation.
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/yourusername/natswork.
+
+## License
+
+MIT License

data/lib/active_job/queue_adapters/natswork_adapter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'active_job'
+require 'natswork/client'
+
+module ActiveJob
+  module QueueAdapters
+    class NatsworkAdapter
+      def enqueue(job)
+        NatsWork::Client.push(
+          job_class: job.class.name,
+          queue: job.queue_name || 'default',
+          arguments: job.serialize,
+          job_id: job.job_id,
+          metadata: {
+            'active_job' => true,
+            'priority' => job.priority,
+            'enqueued_at' => Time.now.iso8601
+          }
+        )
+      end
+
+      def enqueue_at(job, timestamp)
+        NatsWork::Client.perform_at(
+          Time.at(timestamp),
+          job_class: job.class.name,
+          queue: job.queue_name || 'default',
+          arguments: job.serialize,
+          job_id: job.job_id,
+          metadata: {
+            'active_job' => true,
+            'priority' => job.priority,
+            'scheduled_at' => Time.at(timestamp).iso8601
+          }
+        )
+      end
+
+      class << self
+        def enqueue(job)
+          new.enqueue(job)
+        end
+
+        def enqueue_at(job, timestamp)
+          new.enqueue_at(job, timestamp)
+        end
+      end
+    end
+  end
+end

data/lib/generators/natswork/install_generator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module Natswork
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc 'Installs NatsWork and creates configuration files'
+
+      source_root File.expand_path('templates', __dir__)
+
+      def create_initializer_file
+        template 'natswork.rb.erb', 'config/initializers/natswork.rb'
+      end
+
+      def create_config_file
+        template 'natswork.yml.erb', 'config/natswork.yml'
+      end
+
+      def add_natswork_to_application
+        environment do
+          <<~RUBY
+            # Configure ActiveJob to use NatsWork
+            config.active_job.queue_adapter = :natswork
+          RUBY
+        end
+      end
+
+      def create_jobs_directory
+        empty_directory 'app/jobs'
+      end
+
+      def display_post_install_message
+        readme 'POST_INSTALL' if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/natswork/job_generator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+require 'rails/generators/active_job/job_generator'
+
+module Natswork
+  module Generators
+    class JobGenerator < Rails::Generators::NamedBase
+      desc 'Creates a new NatsWork job class'
+
+      source_root File.expand_path('templates', __dir__)
+
+      argument :arguments, type: :array, default: [], banner: 'argument:type argument:type'
+
+      class_option :queue, type: :string, default: 'default', desc: 'Queue name for the job'
+      class_option :retries, type: :numeric, default: 3, desc: 'Number of retries'
+      class_option :timeout, type: :numeric, default: 30, desc: 'Job timeout in seconds'
+
+      def create_job_file
+        template 'job.rb.erb', File.join('app/jobs', class_path, "#{file_name}_job.rb")
+      end
+
+      def create_test_file
+        if Rails.application.config.generators.test_framework == :rspec
+          template 'job_spec.rb.erb', File.join('spec/jobs', class_path, "#{file_name}_job_spec.rb")
+        else
+          template 'job_test.rb.erb', File.join('test/jobs', class_path, "#{file_name}_job_test.rb")
+        end
+      end
+
+      private
+
+      def file_name
+        @file_name ||= name.underscore
+      end
+
+      def class_name
+        @class_name ||= name.camelize
+      end
+
+      def job_class_name
+        "#{class_name}Job"
+      end
+
+      def arguments_signature
+        arguments.map { |arg| arg.split(':').first }.join(', ')
+      end
+
+      def arguments_with_types
+        arguments.map do |arg|
+          name, type = arg.split(':')
+          type ? "#{name} # #{type}" : name
+        end.join(', ')
+      end
+    end
+  end
+end

data/lib/generators/natswork/templates/job.rb.erb

@@ -0,0 +1,21 @@
+class <%= job_class_name %> < NatsWork::Job
+  queue '<%= options[:queue] %>'
+  retries <%= options[:retries] %>
+  timeout <%= options[:timeout] %>
+  
+  def perform(<%= arguments_with_types %>)
+    # TODO: Implement your job logic here
+    <% if arguments.any? -%>
+    # Arguments available: <%= arguments_signature %>
+    <% end -%>
+    
+    # Example:
+    # process_data(<%= arguments_signature %>)
+    # send_notification
+    # update_records
+  end
+  
+  private
+  
+  # Add your helper methods here
+end

data/lib/generators/natswork/templates/job_spec.rb.erb

@@ -0,0 +1,49 @@
+require 'rails_helper'
+
+RSpec.describe <%= job_class_name %>, type: :job do
+  describe '#perform' do
+    <% if arguments.any? -%>
+    let(:job) { described_class.new }
+    <% arguments.each do |arg| -%>
+    <% name, type = arg.split(':') -%>
+    let(:<%= name %>) { <%= type == 'integer' ? '123' : type == 'string' ? "'test'" : 'nil' %> }
+    <% end -%>
+    
+    it 'performs the job successfully' do
+      expect {
+        job.perform(<%= arguments.map { |a| a.split(':').first }.join(', ') %>)
+      }.not_to raise_error
+    end
+    <% else -%>
+    it 'performs the job successfully' do
+      job = described_class.new
+      expect { job.perform }.not_to raise_error
+    end
+    <% end -%>
+  end
+  
+  describe 'job configuration' do
+    it 'uses the correct queue' do
+      expect(described_class.get_queue).to eq('<%= options[:queue] %>')
+    end
+    
+    it 'has the correct retry count' do
+      expect(described_class.get_retries).to eq(<%= options[:retries] %>)
+    end
+    
+    it 'has the correct timeout' do
+      expect(described_class.get_timeout).to eq(<%= options[:timeout] %>)
+    end
+  end
+  
+  describe '.perform_async' do
+    it 'enqueues the job' do
+      <% if arguments.any? -%>
+      job_id = described_class.perform_async(<%= arguments.map { |a| a.split(':').first }.join(', ') %>)
+      <% else -%>
+      job_id = described_class.perform_async
+      <% end -%>
+      expect(job_id).to be_present
+    end
+  end
+end

data/lib/generators/natswork/templates/natswork.rb.erb

@@ -0,0 +1,51 @@
+# NatsWork Configuration
+require 'natswork'
+
+NatsWork::Client.instance.configure do |config|
+  # NATS server connection
+  config.servers = ENV.fetch('NATSWORK_SERVERS', 'nats://localhost:4222').split(',')
+  
+  # Connection pool settings
+  config.pool_size = ENV.fetch('NATSWORK_POOL_SIZE', 5).to_i
+  config.pool_timeout = ENV.fetch('NATSWORK_POOL_TIMEOUT', 5).to_i
+  
+  # Job settings
+  config.max_retries = ENV.fetch('NATSWORK_MAX_RETRIES', 3).to_i
+  config.job_timeout = ENV.fetch('NATSWORK_JOB_TIMEOUT', 30).to_i
+  config.sync_timeout = ENV.fetch('NATSWORK_SYNC_TIMEOUT', 30).to_i
+  
+  # Namespace for NATS subjects
+  config.namespace = ENV.fetch('NATSWORK_NAMESPACE', Rails.env)
+  
+  # JetStream settings
+  config.use_jetstream = ENV.fetch('NATSWORK_USE_JETSTREAM', 'true') == 'true'
+  
+  # Logging
+  config.logger = Rails.logger
+  
+  # Authentication (optional)
+  # config.user = ENV['NATSWORK_USER']
+  # config.password = ENV['NATSWORK_PASSWORD']
+  # config.token = ENV['NATSWORK_TOKEN']
+end
+
+# Auto-load jobs from app/jobs in development
+if Rails.env.development?
+  Rails.application.config.to_prepare do
+    Dir[Rails.root.join('app/jobs/**/*_job.rb')].each { |f| require f }
+  end
+end
+
+# Register jobs with the registry
+Rails.application.config.after_initialize do
+  # Auto-discover and register all job classes
+  Dir[Rails.root.join('app/jobs/**/*_job.rb')].each do |file|
+    require file
+    class_name = File.basename(file, '.rb').camelize
+    job_class = class_name.safe_constantize
+    
+    if job_class && job_class < NatsWork::Job
+      Rails.logger.info "[NatsWork] Registered job: #{job_class.name}"
+    end
+  end
+end

data/lib/natswork/circuit_breaker.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module NatsWork
+  class CircuitBreakerError < Error; end
+  class CircuitOpenError < CircuitBreakerError; end
+
+  class CircuitBreaker
+    STATES = %i[closed open half_open].freeze
+
+    attr_reader :state, :failure_count, :last_failure_time
+
+    def initialize(options = {})
+      @failure_threshold = options[:failure_threshold] || 5
+      @success_threshold = options[:success_threshold] || 2
+      @timeout = options[:timeout] || 60
+      @reset_timeout = options[:reset_timeout] || 60
+
+      @state = :closed
+      @failure_count = 0
+      @success_count = 0
+      @last_failure_time = nil
+      @mutex = Mutex.new
+      @on_open = options[:on_open]
+      @on_close = options[:on_close]
+      @on_half_open = options[:on_half_open]
+    end
+
+    def call
+      @mutex.synchronize do
+        case @state
+        when :open
+          raise CircuitOpenError, 'Circuit breaker is open' unless can_attempt_reset?
+
+          transition_to(:half_open)
+
+        when :half_open
+          # Allow the attempt in half-open state
+        when :closed
+          # Allow the attempt in closed state
+        end
+      end
+
+      begin
+        result = yield
+        on_success
+        result
+      rescue StandardError => e
+        on_failure(e)
+        raise
+      end
+    end
+
+    def closed?
+      @state == :closed
+    end
+
+    def open?
+      @state == :open
+    end
+
+    def half_open?
+      @state == :half_open
+    end
+
+    def reset
+      @mutex.synchronize do
+        @failure_count = 0
+        @success_count = 0
+        @last_failure_time = nil
+        transition_to(:closed)
+      end
+    end
+
+    def trip
+      @mutex.synchronize do
+        transition_to(:open)
+      end
+    end
+
+    def stats
+      @mutex.synchronize do
+        {
+          state: @state,
+          failure_count: @failure_count,
+          success_count: @success_count,
+          last_failure_time: @last_failure_time,
+          time_until_retry: time_until_retry
+        }
+      end
+    end
+
+    private
+
+    def on_success
+      @mutex.synchronize do
+        case @state
+        when :half_open
+          @success_count += 1
+          if @success_count >= @success_threshold
+            @failure_count = 0
+            @success_count = 0
+            transition_to(:closed)
+          end
+        when :closed
+          @failure_count = 0 if @failure_count.positive?
+        end
+      end
+    end
+
+    def on_failure(_error)
+      @mutex.synchronize do
+        @last_failure_time = Time.now
+
+        case @state
+        when :half_open
+          @failure_count += 1
+          transition_to(:open)
+        when :closed
+          @failure_count += 1
+          transition_to(:open) if @failure_count >= @failure_threshold
+        end
+      end
+    end
+
+    def can_attempt_reset?
+      return false unless @last_failure_time
+
+      Time.now - @last_failure_time >= @reset_timeout
+    end
+
+    def time_until_retry
+      return 0 unless @last_failure_time && @state == :open
+
+      elapsed = Time.now - @last_failure_time
+      remaining = @reset_timeout - elapsed
+      remaining.positive? ? remaining : 0
+    end
+
+    def transition_to(new_state)
+      return if @state == new_state
+
+      @state = new_state
+      @success_count = 0 if new_state == :half_open
+
+      case new_state
+      when :open
+        @on_open&.call
+      when :closed
+        @on_close&.call
+      when :half_open
+        @on_half_open&.call
+      end
+    end
+  end
+
+  class CircuitBreakedConnection
+    attr_reader :connection, :circuit_breaker
+
+    def initialize(connection, circuit_breaker_options = {})
+      @connection = connection
+      @circuit_breaker = CircuitBreaker.new(circuit_breaker_options)
+    end
+
+    def connect
+      @circuit_breaker.call { @connection.connect }
+    end
+
+    def disconnect
+      @connection.disconnect
+    end
+
+    def connected?
+      @connection.connected?
+    end
+
+    def publish(subject, payload)
+      @circuit_breaker.call { @connection.publish(subject, payload) }
+    end
+
+    def subscribe(subject, opts = {}, &block)
+      @circuit_breaker.call { @connection.subscribe(subject, opts, &block) }
+    end
+
+    def request(subject, payload, opts = {})
+      @circuit_breaker.call { @connection.request(subject, payload, opts) }
+    end
+
+    def unsubscribe(sid)
+      @circuit_breaker.call { @connection.unsubscribe(sid) }
+    end
+
+    def with_connection(&block)
+      @circuit_breaker.call { @connection.with_connection(&block) }
+    end
+
+    def jetstream
+      @circuit_breaker.call { @connection.jetstream }
+    end
+
+    def stats
+      connection_stats = @connection.stats
+      connection_stats[:circuit_breaker] = @circuit_breaker.stats
+      connection_stats
+    end
+
+    def healthy?
+      @circuit_breaker.closed? && @connection.healthy?
+    end
+
+    def ping
+      @circuit_breaker.call { @connection.ping }
+    rescue CircuitOpenError
+      false
+    end
+
+    # Delegate callback methods
+    def on_reconnect(&block)
+      @connection.on_reconnect(&block)
+    end
+
+    def on_disconnect(&block)
+      @connection.on_disconnect(&block)
+    end
+
+    def on_error(&block)
+      @connection.on_error(&block)
+    end
+  end
+end