anway 0.1.1

data/lib/anway/runner.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Anway
+  # Runs jobs until stop, or until the server sends terminate.
+  #
+  # After quiet, the runner stops fetching and stays alive. At a stop, running
+  # jobs get `timeout` seconds to finish. Then Anway::Shutdown is raised in them,
+  # and they get `cancel_grace` seconds to return. Jobs that still run then fail.
+  class Runner
+    BEAT_INTERVAL = 15
+    ERROR_PAUSE = 1
+    EMPTY_FETCH_MINIMUM = 0.2
+    BACKTRACE_LINES = 30
+
+    attr_reader :wid
+
+    def initialize(queues: ['default'], concurrency: 10, timeout: 25, cancel_grace: 5,
+                   labels: [], beat_interval: BEAT_INTERVAL, url: nil, logger: Anway.config.logger)
+      @queues = Queues.new(queues)
+      @concurrency = concurrency
+      @timeout = timeout
+      @cancel_grace = cancel_grace
+      @beat_interval = beat_interval
+      @logger = logger
+      @wid = SecureRandom.hex(12)
+      @fetching = Thread::Queue.new
+      @stopped_beat = Thread::Queue.new
+      @events_reader, @events_writer = IO.pipe
+      @running = {}
+      @lock = Mutex.new
+
+      @client = Client.new(
+        url || Anway.config.url,
+        pool_size: concurrency + 1,
+        timeout: Anway.config.timeout,
+        tls: Anway.config.tls,
+        wid: @wid,
+        labels: ['ruby', *labels]
+      )
+    end
+
+    # Safe in a signal handler.
+    def stop
+      signal('s')
+    end
+
+    # Safe in a signal handler.
+    def quiet
+      signal('q')
+    end
+
+    # Safe in a signal handler.
+    def dump
+      signal('d')
+    end
+
+    def run
+      @client.beat
+
+      @processors = Array.new(@concurrency) { start_processor }
+
+      beat_thread = start_beat
+
+      @logger.info("anway started queues=#{@queues.names.join(',')} concurrency=#{@concurrency}")
+
+      wait_for_stop
+      shutdown
+
+      @stopped_beat.close
+      beat_thread.join
+    ensure
+      @client.close
+    end
+
+    private
+
+    def signal(letter)
+      @events_writer.write_nonblock(letter, exception: false)
+    end
+
+    def wait_for_stop
+      loop do
+        @events_reader.wait_readable
+
+        case @events_reader.read_nonblock(1)
+        when 's' then return
+        when 'q' then stop_fetching
+        when 'd' then dump_threads
+        end
+      end
+    end
+
+    def dump_threads
+      Thread.list.each { |thread| @logger.info("#{thread.inspect}\n#{thread.backtrace&.first(10)&.join("\n")}") }
+    end
+
+    def stop_fetching
+      @fetching.close
+    end
+
+    def fetching?
+      !@fetching.closed?
+    end
+
+    def pause(seconds)
+      @fetching.pop(timeout: seconds)
+    end
+
+    def start_beat
+      Thread.new do
+        state = nil
+
+        until @stopped_beat.closed?
+          @stopped_beat.pop(timeout: @beat_interval)
+
+          break if @stopped_beat.closed?
+
+          state = beat(state)
+        end
+      end
+    end
+
+    def beat(state)
+      case @client.beat(state)
+      when 'quiet'
+        quiet
+
+        'quiet'
+      when 'terminate'
+        stop
+
+        state
+      else
+        state
+      end
+    rescue Error => e
+      @logger.warn("beat failed: #{e.message}")
+
+      state
+    end
+
+    # Shutdown stays pending outside perform, so it cannot break a report.
+    def start_processor
+      Thread.new do
+        Thread.handle_interrupt(Shutdown => :never) { process_loop }
+      end
+    end
+
+    # A fetch in progress is not canceled, because its reply can hold a job.
+    def process_loop
+      while fetching?
+        started = monotonic
+        job = fetch_next
+
+        if job
+          process(job)
+        elsif monotonic - started < EMPTY_FETCH_MINIMUM
+          pause(EMPTY_FETCH_MINIMUM)
+        end
+      end
+    end
+
+    def fetch_next
+      @client.fetch(*@queues.order)
+    rescue Error => e
+      @logger.warn("fetch failed: #{e.message}")
+      pause(ERROR_PAUSE)
+
+      nil
+    end
+
+    def process(job)
+      @lock.synchronize { @running[job.jid] = { job: job, thread: Thread.current } }
+
+      error = perform(job)
+
+      return unless claim(job.jid)
+
+      report(job, error)
+    end
+
+    def perform(job)
+      Thread.handle_interrupt(Shutdown => :immediate) { Executor.call(job) }
+
+      nil
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      notify_error(e, job) unless e.is_a?(Shutdown)
+
+      e
+    end
+
+    def notify_error(error, job)
+      @logger.warn("job failed jid=#{job.jid} jobtype=#{job.type} error=#{error.class}: #{error.message}")
+
+      Anway.config.error_handlers.each { |handler| handler.call(error, job) }
+    rescue StandardError => e
+      @logger.error("error handler failed: #{e.message}")
+    end
+
+    def claim(jid)
+      @lock.synchronize { !@running.delete(jid).nil? }
+    end
+
+    def report(job, error)
+      if error
+        @client.fail(
+          job.jid,
+          errtype: error.class.name,
+          message: error.message,
+          backtrace: error.backtrace&.first(BACKTRACE_LINES) || []
+        )
+      else
+        @client.ack(job.jid)
+      end
+    rescue Error => e
+      @logger.warn("job report failed, the reservation will expire jid=#{job.jid}: #{e.message}")
+    end
+
+    def shutdown
+      stop_fetching if fetching?
+
+      return if join_processors(@timeout)
+
+      running.each { |entry| entry[:thread].raise(Shutdown, 'the worker is stopping') }
+
+      return if join_processors(@cancel_grace)
+
+      running.each { |entry| abandon(entry) }
+    end
+
+    def running
+      @lock.synchronize { @running.values }
+    end
+
+    def abandon(entry)
+      job = entry[:job]
+
+      return unless claim(job.jid)
+
+      @logger.warn("job did not stop jid=#{job.jid} jobtype=#{job.type}")
+
+      entry[:thread].kill
+
+      report(job, Shutdown.new('the worker stopped before the job finished'))
+    end
+
+    def join_processors(limit)
+      deadline = monotonic + limit
+
+      @processors.all? { |thread| thread.join([deadline - monotonic, 0].max) }
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/anway/testing.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'anway'
+
+module Anway
+  # Test modes for apps. No server is necessary.
+  #
+  #   Anway::Testing.fake!    keeps pushed jobs in a list
+  #   Anway::Testing.inline!  runs each job at push
+  #   Anway::Testing.disable! uses the real client
+  module Testing
+    @mode = nil
+    @jobs = []
+
+    class << self
+      attr_reader :jobs, :mode
+
+      def fake!
+        @mode = :fake
+      end
+
+      def inline!
+        @mode = :inline
+      end
+
+      def disable!
+        @mode = nil
+      end
+
+      def clear
+        @jobs.clear
+      end
+
+      def enqueue(job)
+        copy = Job.from_hash(JSON.parse(JSON.generate(job.to_h)))
+
+        @mode == :inline ? Executor.call(copy) : @jobs << copy
+
+        job.jid
+      end
+
+      # Runs and removes all fake jobs. Jobs that they push also run.
+      def drain
+        Executor.call(@jobs.shift) until @jobs.empty?
+      end
+    end
+  end
+end

data/lib/anway/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Anway
+  VERSION = '0.1.1'
+end

data/lib/anway/worker.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Anway
+  # Makes a class a job:
+  #
+  #   class WelcomeJob
+  #     include Anway::Worker
+  #
+  #     job_options queue: 'mailers', retry: 5
+  #
+  #     def perform(user_id); end
+  #   end
+  #
+  #   WelcomeJob.perform_async(42)
+  module Worker
+    DEFAULT_BACKTRACE = 30
+
+    @registry = {}
+    @lock = Mutex.new
+
+    class << self
+      def included(base)
+        base.extend(ClassMethods)
+
+        register(base) if base.name
+      end
+
+      def register(klass, old_type: nil)
+        @lock.synchronize do
+          @registry.delete(old_type) if old_type
+          @registry[klass.job_type] = klass
+        end
+      end
+
+      def classes
+        @lock.synchronize { @registry.values }
+      end
+
+      # Only registered classes run. The job type comes from the network, so it
+      # never becomes a constant lookup. The lookup by the class name below
+      # uses a registered name, and returns the newest class after a reload.
+      def find(type)
+        klass = @lock.synchronize { @registry[type] }
+
+        raise UnknownJob, "no handler for job type #{type.inspect}" unless klass
+
+        klass.name ? Object.const_get(klass.name) : klass
+      end
+    end
+
+    attr_accessor :job
+
+    def jid
+      job&.jid
+    end
+
+    # Updates the progress of a tracked job.
+    def track(percent: nil, desc: nil, reserve_until: nil)
+      Anway.client.track_set(jid, percent: percent, desc: desc, reserve_until: reserve_until)
+    end
+
+    module ClassMethods
+      def inherited(subclass)
+        super
+
+        Worker.register(subclass) if subclass.name
+      end
+
+      def job_type(name = nil)
+        return @job_type || self.name unless name
+
+        old_type = job_type
+        @job_type = name
+
+        Worker.register(self, old_type: old_type)
+      end
+
+      def job_options(options = nil)
+        inherited_options = superclass.respond_to?(:job_options) ? superclass.job_options : {}
+
+        @job_options = (@job_options || {}).merge(options) if options
+
+        inherited_options.merge(@job_options || {})
+      end
+
+      def perform_async(*args)
+        enqueue_with(args, {})
+      end
+
+      def perform_at(time, *args)
+        enqueue_with(args, { at: time })
+      end
+
+      def perform_in(seconds, *args)
+        enqueue_with(args, { at: Time.now + seconds.to_f })
+      end
+
+      # Changes the options for one push: WelcomeJob.set(queue: 'low').perform_async(1)
+      def set(**options)
+        Setter.new(self, options)
+      end
+
+      def enqueue_with(args, options)
+        Anway.enqueue(Job.new(job_type, args, backtrace: DEFAULT_BACKTRACE, **job_options, **options))
+      end
+    end
+
+    class Setter
+      def initialize(klass, options)
+        @klass = klass
+        @options = options
+      end
+
+      def perform_async(*args)
+        @klass.enqueue_with(args, @options)
+      end
+
+      def perform_at(time, *args)
+        @klass.enqueue_with(args, @options.merge(at: time))
+      end
+
+      def perform_in(seconds, *args)
+        @klass.enqueue_with(args, @options.merge(at: Time.now + seconds.to_f))
+      end
+    end
+  end
+end

data/lib/anway.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative 'anway/version'
+require_relative 'anway/errors'
+require_relative 'anway/configuration'
+require_relative 'anway/job'
+require_relative 'anway/connection'
+require_relative 'anway/pool'
+require_relative 'anway/client'
+require_relative 'anway/worker'
+require_relative 'anway/executor'
+require_relative 'anway/queues'
+require_relative 'anway/runner'
+require_relative 'anway/railtie' if defined?(Rails::Railtie)
+
+module Anway
+  @lock = Mutex.new
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def client
+      @lock.synchronize do
+        @client ||= Client.new(
+          config.url, pool_size: config.pool_size, timeout: config.timeout, tls: config.tls
+        )
+      end
+    end
+
+    # Sends a job with no local class, for a worker in any language.
+    def push(type, args = [], **options)
+      enqueue(Job.new(type, args, **options))
+    end
+
+    # Inside a database transaction, the push waits for the commit.
+    def enqueue(job)
+      testing = const_defined?(:Testing) ? Testing : nil
+
+      return testing.enqueue(job) if testing&.mode
+
+      config.push_wrapper.call { client.push(job) }
+
+      job.jid
+    end
+
+    def reset!
+      @lock.synchronize do
+        @client&.close
+        @client = nil
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: anway
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Thadeu
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+executables:
+- anway
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/anway
+- lib/active_job/queue_adapters/anway_adapter.rb
+- lib/anway.rb
+- lib/anway/cli.rb
+- lib/anway/client.rb
+- lib/anway/configuration.rb
+- lib/anway/connection.rb
+- lib/anway/errors.rb
+- lib/anway/executor.rb
+- lib/anway/job.rb
+- lib/anway/pool.rb
+- lib/anway/queues.rb
+- lib/anway/railtie.rb
+- lib/anway/runner.rb
+- lib/anway/testing.rb
+- lib/anway/version.rb
+- lib/anway/worker.rb
+homepage: https://github.com/thadeu/anway-ruby
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Ruby and Rails client and worker for the Anway job server
+test_files: []