anway 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 334855b00a1b57308782f76328e3d72d2339169713022fe5cc5421961a4acfc9
+  data.tar.gz: d63ddc5085f28acc3d00174f77632f3f2a95a6c827b4d901629496ccfc0251a0
+SHA512:
+  metadata.gz: 56e3d4d168da46531849c13c713e85483d624336fd30f42eace765adbbce119c8c97e09072375e5373410750e5cded72a315eda6d6b917bb137ab57a887aa09a
+  data.tar.gz: a97fb1df5b38f972d9165fbc9eee86045abec79b5ec543684cb008dbee60f1ec0c222e7a39d7ea99ffdf3b72c80687f1747f79c5f9ebf70d76c9b0be04486bf2

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Thadeu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,146 @@
+# anway-ruby
+
+Ruby and Rails client and worker for [Anway](https://github.com/thadeu/anway). Ruby 3.4 or later. Rails 8.1 for the Rails integration.
+
+```ruby
+gem 'anway'
+```
+
+The server address comes from `ANWAY_URL`, for example `tcp://:password@localhost:7419`. Use `tcp+tls://` for TLS.
+
+## Worker
+
+```ruby
+class WelcomeJob
+  include Anway::Worker
+
+  job_type 'email.send'
+  job_options queue: 'mailers', retry: 5
+
+  def perform(address)
+    # ...
+  end
+end
+
+WelcomeJob.perform_async('a@b.com')
+WelcomeJob.perform_in(300, 'a@b.com')
+WelcomeJob.set(queue: 'low').perform_async('a@b.com')
+```
+
+- `job_type` is optional. The default is the class name. Use a name when a worker in another language runs the job.
+- `job_options` accepts `queue`, `retry`, `reserve_for`, `backtrace`, and `custom`, such as `custom: { unique_for: 600 }`.
+- Args must be JSON types with string hash keys. Symbols, times, and objects raise `ArgumentError`.
+- Delivery is at least once, so jobs must be idempotent.
+
+To send a job that a worker in any language runs:
+
+```ruby
+Anway.push('image.resize', [42], queue: 'media')
+```
+
+## Rails
+
+```ruby
+config.active_job.queue_adapter = :anway
+```
+
+- Existing ActiveJob classes work. Each one runs in the Rails reloader.
+- In a database transaction, a push waits for the commit, and a rollback cancels it. This also applies to `perform_async`.
+- A job with `retry_on` keeps ActiveJob attempts, and its final error goes to the dead set.
+- A job with no `retry_on` uses server retries.
+
+Tasks in `recurring.yml` and jobs that wait in Solid Queue do not move automatically. Move recurring tasks to the server cron, and drain the old queue first.
+
+## Process
+
+```bash
+bundle exec anway -q critical,mailers,default -c 10
+```
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `-q`, `--queues` | Queues of the job classes, and `default` | Queues in order, as `name` or `name:weight` |
+| `-c`, `--concurrency` | `10` | Job threads |
+| `-t`, `--timeout` | `25` | Seconds for jobs to finish at a stop |
+| `-r`, `--require` | `config/environment.rb` | File that loads the jobs. Required outside Rails. |
+| `-C`, `--config` | `config/anway.yml` | YAML config file |
+| `-e`, `--environment` | `RAILS_ENV`, `APP_ENV` | Environment section of the YAML file |
+| `-l`, `--label` | None | Worker label |
+| `-v`, `--verbose` | Off | Debug logs |
+| `-V`, `--version` | | Print the version |
+
+```yaml
+concurrency: <%= ENV.fetch('WORKER_THREADS', 10) %>
+timeout: 25
+queues:
+  - [critical, 4]
+  - [mailers, 2]
+  - [default, 1]
+
+production:
+  concurrency: 20
+```
+
+Flags have priority over the environment section, and the environment section has priority over top-level keys. A list without weights uses strict order.
+
+| Signal | Effect |
+|---|---|
+| `TERM`, `INT` | Stop |
+| `TSTP` | Quiet: stop fetching and stay alive |
+| `TTIN` | Write thread data to the log |
+
+Exit codes: `0` for a normal stop, `1` for a boot failure, `2` for a usage error.
+
+At a stop, jobs get `--timeout` seconds to finish. Then `Anway::Shutdown` is raised in them, and they get 5 seconds to return. The process then fails jobs that still run and stops. Set the container stop timeout above 30 seconds.
+
+Keep the database pool at the concurrency value or more. A job queue with no worker has no error, and its jobs wait.
+
+## Tests in your app
+
+```ruby
+require 'anway/testing'
+
+Anway::Testing.fake!
+WelcomeJob.perform_async('a@b.com')
+Anway::Testing.jobs.size
+Anway::Testing.drain
+
+Anway::Testing.inline!
+```
+
+## Client
+
+`Anway::Client` has the operations of [anway-go](https://github.com/thadeu/anway-go), in snake_case. It is safe for threads and for forks.
+
+```ruby
+client = Anway::Client.new('tcp://localhost:7419')
+client.push(Anway::Job.new('email.send', ['a@b.com']))
+```
+
+The error kinds are `Anway::NotUnique`, `Anway::Closed`, `Anway::ServerError`, and `Anway::ConnectionError`. A failed call does not resend.
+
+## Configuration
+
+```ruby
+Anway.configure do |config|
+  config.pool_size = 8
+  config.timeout = 10
+  config.tls = { ca_file: 'ca.pem' }
+  config.use MyMiddleware.new
+  config.on_error { |error, job| report(error, job) }
+end
+```
+
+Middleware has `call(job)` and yields. The first one added is the outermost.
+
+## Tests
+
+```bash
+SERVER_BIN=/path/to/anway bundle exec rspec
+```
+
+The specs map to the [conformance scenarios](https://github.com/thadeu/anway/blob/main/conformance/scenarios.md).
+
+## License
+
+MIT

data/exe/anway

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'anway/cli'
+
+exit Anway::CLI.new(ARGV).run

data/lib/active_job/queue_adapters/anway_adapter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'active_job'
+require 'anway'
+
+module Anway
+  # Runs serialized ActiveJob payloads.
+  class ActiveJobWrapper
+    include Anway::Worker
+
+    job_type 'ActiveJob'
+
+    def perform(data)
+      ActiveJob::Base.execute(data)
+    end
+  end
+
+  # Records the use of retry_on, because rescue_handlers also holds rescue_from.
+  module ActiveJobRetries
+    def retry_on(...)
+      self.anway_retry_on = true
+
+      super
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_job) do
+  class_attribute :anway_retry_on, default: false
+  singleton_class.prepend(Anway::ActiveJobRetries)
+end
+
+module ActiveJob
+  module QueueAdapters
+    class AnwayAdapter < AbstractAdapter
+      BACKTRACE = 30
+      DEAD_SET = -1
+
+      def enqueue(job)
+        push(job, {})
+      end
+
+      def enqueue_at(job, timestamp)
+        push(job, { at: Time.at(timestamp) })
+      end
+
+      private
+
+      # Each push has a new id. A retry_on attempt keeps its job_id while the
+      # first attempt is still reserved, and the server rejects a repeated id.
+      def push(job, options)
+        options = options.merge(queue: job.queue_name, backtrace: BACKTRACE)
+
+        # retry_on owns the attempts, so its final error goes to the dead set.
+        options[:retry] = DEAD_SET if job.class.anway_retry_on
+
+        pushed = Anway::Job.new('ActiveJob', [job.serialize.as_json], **options)
+
+        job.provider_job_id = pushed.jid
+
+        Anway.enqueue(pushed)
+      end
+    end
+  end
+end

data/lib/anway/cli.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'optparse'
+require 'yaml'
+
+# The Railtie registers only when Rails loads before the gem.
+begin
+  require 'rails'
+rescue LoadError
+  nil
+end
+
+require 'anway'
+
+module Anway
+  # bundle exec anway -q critical,mailers:2,default -c 10
+  class CLI
+    EXIT_OK = 0
+    EXIT_BOOT = 1
+    EXIT_USAGE = 2
+    DEFAULTS = { concurrency: 10, timeout: 25, labels: [] }.freeze
+    DEFAULT_CONFIG = 'config/anway.yml'
+    RAILS_ENTRY = 'config/environment.rb'
+
+    def initialize(argv)
+      $stdout.sync = true
+
+      @argv = argv.dup
+      @flags = {}
+    end
+
+    def run
+      return EXIT_OK if parse == :done
+
+      boot
+      start
+      EXIT_OK
+    rescue OptionParser::ParseError, ArgumentError => e
+      warn("anway: #{e.message}")
+
+      EXIT_USAGE
+    rescue Error, ScriptError, StandardError => e
+      warn("anway: #{e.class}: #{e.message}")
+
+      EXIT_BOOT
+    end
+
+    private
+
+    def parse
+      parser.parse!(@argv)
+
+      raise ArgumentError, "unexpected argument: #{@argv.first}" unless @argv.empty?
+
+      @flags[:done] ? :done : nil
+    end
+
+    def parser
+      OptionParser.new do |options|
+        options.banner = 'Usage: anway [options]'
+
+        options.on('-q', '--queues LIST', 'Queues in order, as name or name:weight') do |list|
+          @flags[:queues] = list.split(',').map { |entry| entry.split(':') }
+        end
+
+        options.on('-c', '--concurrency N', Integer, 'Number of job threads') { |n| @flags[:concurrency] = n }
+        options.on('-t', '--timeout N', Float, 'Seconds for jobs to finish at stop') { |n| @flags[:timeout] = n }
+        options.on('-r', '--require PATH', 'File that loads the jobs') { |path| @flags[:require] = path }
+        options.on('-C', '--config PATH', 'YAML config file') { |path| @flags[:config] = path }
+        options.on('-e', '--environment NAME', 'Environment name') { |name| @flags[:environment] = name }
+        options.on('-l', '--label NAME', 'Worker label') { |name| (@flags[:labels] ||= []) << name }
+        options.on('-v', '--verbose', 'Debug logs') { @flags[:verbose] = true }
+
+        options.on('-V', '--version', 'Print the version') do
+          puts "anway #{VERSION}"
+
+          @flags[:done] = true
+        end
+
+        options.on('-h', '--help', 'Print this help') do
+          puts options
+
+          @flags[:done] = true
+        end
+      end
+    end
+
+    def boot
+      environment = @flags[:environment] || ENV['RAILS_ENV'] || ENV['APP_ENV'] || 'development'
+
+      ENV['RAILS_ENV'] ||= environment
+      ENV['APP_ENV'] ||= environment
+
+      @options = DEFAULTS.merge(file_options(environment)).merge(@flags)
+
+      load_app
+
+      Anway.config.logger.level = Logger::DEBUG if @options[:verbose]
+
+      check_database_pool
+    end
+
+    def file_options(environment)
+      path = @flags[:config] || DEFAULT_CONFIG
+
+      unless File.exist?(path)
+        raise ArgumentError, "config file not found: #{path}" if @flags[:config]
+
+        return {}
+      end
+
+      content = YAML.safe_load(ERB.new(File.read(path)).result, aliases: true) || {}
+      section = content.fetch(environment, {})
+      common = content.reject { |_key, value| value.is_a?(Hash) }
+
+      common.merge(section).transform_keys(&:to_sym)
+    end
+
+    def load_app
+      path = @options[:require]
+      path ||= RAILS_ENTRY if File.exist?(RAILS_ENTRY)
+
+      raise ArgumentError, 'use -r to load the jobs outside Rails' unless path
+
+      require File.expand_path(path)
+
+      Rails.application.eager_load! if defined?(Rails) && Rails.application
+    end
+
+    def check_database_pool
+      return unless defined?(ActiveRecord::Base) && ActiveRecord::Base.connected?
+
+      size = ActiveRecord::Base.connection_pool.size
+
+      return if size >= @options[:concurrency]
+
+      Anway.config.logger.warn("database pool #{size} is smaller than concurrency #{@options[:concurrency]}")
+    end
+
+    def start
+      runner = Runner.new(
+        queues: queues,
+        concurrency: @options[:concurrency],
+        timeout: @options[:timeout],
+        labels: @options[:labels]
+      )
+
+      trap_signals(runner)
+      runner.run
+    end
+
+    def trap_signals(runner)
+      %w[TERM INT].each { |name| Signal.trap(name) { runner.stop } }
+
+      Signal.trap('TSTP') { runner.quiet }
+      Signal.trap('TTIN') { runner.dump }
+    end
+
+    # Without a list, the worker uses the queues of its job classes.
+    def queues
+      return @options[:queues] if @options[:queues]
+
+      names = Worker.classes.map { |klass| klass.job_options[:queue]&.to_s }
+      names.concat(active_job_queues)
+
+      [*names.compact, 'default'].uniq
+    end
+
+    def active_job_queues
+      return [] unless defined?(ActiveJob::Base)
+
+      ActiveJob::Base.descendants.map(&:queue_name).grep(String)
+    end
+  end
+end

data/lib/anway/client.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+module Anway
+  # Same operations as the anway-go client. It is safe for concurrent use.
+  class Client
+    DEFAULT_URL = 'tcp://127.0.0.1:7419'
+    DEFAULT_PORT = 7419
+    FETCH_WAIT = 2
+
+    Endpoint = Data.define(:host, :port, :password, :tls)
+
+    # A blank URL uses ANWAY_URL, then the local default.
+    def initialize(url = nil, pool_size: 8, timeout: 10, tls: nil, wid: nil, labels: [])
+      @endpoint = parse_url(url || ENV.fetch('ANWAY_URL', nil) || DEFAULT_URL)
+      @timeout = timeout
+      @wid = wid
+
+      @pool = Pool.new(pool_size) do
+        Connection.new(@endpoint, timeout: timeout, tls: tls, wid: wid, labels: labels)
+      end
+    end
+
+    def close
+      @pool.close
+    end
+
+    # Raises NotUnique when a unique lock blocks the job.
+    def push(job)
+      call('PUSH', job.to_h)
+
+      job.jid
+    end
+
+    # Returns the next job, or nil when no job arrives in about 2 seconds.
+    def fetch(*queues)
+      reply = call('FETCH', queues.join(' '), wait: FETCH_WAIT)
+
+      reply && Job.from_hash(JSON.parse(reply))
+    end
+
+    def ack(jid)
+      call('ACK', { jid: jid })
+
+      true
+    end
+
+    def fail(jid, errtype:, message:, backtrace: [])
+      call('FAIL', { jid: jid, errtype: errtype, message: message, backtrace: backtrace })
+
+      true
+    end
+
+    # Returns nil, "quiet", or "terminate".
+    def beat(current_state = nil)
+      reply = call('BEAT', { wid: @wid, current_state: current_state }.compact)
+
+      reply == 'OK' ? nil : JSON.parse(reply)['state']
+    end
+
+    def info
+      JSON.parse(call('INFO'))
+    end
+
+    def queue_sizes
+      info.dig('faktory', 'queues') || {}
+    end
+
+    def pause_queues(*queues)
+      queue_command('PAUSE', queues)
+    end
+
+    def resume_queues(*queues)
+      queue_command('RESUME', queues)
+    end
+
+    def remove_queues(*queues)
+      queue_command('REMOVE', queues)
+    end
+
+    # The command is "kill", "discard", "requeue", or "clear".
+    # The target is "retries", "scheduled", or "dead".
+    def mutate(command, target, jobtype: nil, jids: nil, regexp: nil)
+      filter = { jobtype: jobtype, jids: jids, regexp: regexp }.compact
+
+      call('MUTATE', { cmd: command, target: target, filter: filter })
+
+      true
+    end
+
+    def batch_new(success: nil, complete: nil, parent_bid: nil, description: nil)
+      definition = {
+        success: success&.to_h, complete: complete&.to_h, parent_bid: parent_bid, description: description
+      }.compact
+
+      call('BATCH', "NEW #{JSON.generate(definition)}")
+    end
+
+    def batch_open(bid)
+      call('BATCH', "OPEN #{bid}")
+
+      true
+    end
+
+    def batch_commit(bid)
+      call('BATCH', "COMMIT #{bid}")
+
+      true
+    end
+
+    def batch_status(bid)
+      JSON.parse(call('BATCH', "STATUS #{bid}"))
+    end
+
+    def track_get(jid)
+      JSON.parse(call('TRACK', "GET #{jid}"))
+    end
+
+    def track_set(jid, percent: nil, desc: nil, reserve_until: nil)
+      update = { jid: jid, percent: percent, desc: desc, reserve_until: reserve_until&.to_time&.utc&.iso8601(9) }
+
+      call('TRACK', "SET #{JSON.generate(update.compact)}")
+
+      true
+    end
+
+    private
+
+    def queue_command(action, queues)
+      call('QUEUE', "#{action} #{queues.join(' ')}")
+
+      true
+    end
+
+    def call(verb, argument = nil, wait: 0)
+      @pool.with(timeout: @timeout) { |connection| connection.command(verb, argument, wait: wait) }
+    end
+
+    def parse_url(url)
+      uri = URI.parse(url)
+
+      raise ArgumentError, "unsupported scheme: #{uri.scheme}" unless %w[tcp tcp+tls].include?(uri.scheme)
+
+      password = uri.password && URI.decode_www_form_component(uri.password)
+
+      Endpoint.new(host: uri.hostname, port: uri.port || DEFAULT_PORT, password: password, tls: uri.scheme == 'tcp+tls')
+    end
+  end
+end

data/lib/anway/configuration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Anway
+  class Configuration
+    attr_accessor :url, :pool_size, :timeout, :tls, :logger, :push_wrapper, :reloader
+    attr_reader :middleware, :error_handlers
+
+    def initialize
+      @url = nil
+      @pool_size = 8
+      @timeout = 10
+      @tls = nil
+      @logger = Logger.new($stdout, level: Logger::INFO)
+      @push_wrapper = ->(&block) { block.call }
+      @reloader = ->(&block) { block.call }
+      @middleware = []
+      @error_handlers = []
+    end
+
+    # The first middleware added is the outermost. An object has `call(job)`
+    # and yields to run the next one.
+    def use(middleware)
+      @middleware << middleware
+    end
+
+    def on_error(&block)
+      @error_handlers << block
+    end
+  end
+end