nats_worker 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 93b89424e0d096a2be58cd427a15fada391ab6666f21a628203e18c5af882cc0
+  data.tar.gz: d6252f84c3191eb33dc4f88d8423b5d272c7254d2585d6d7e61bb8875e0febe6
+SHA512:
+  metadata.gz: 75ab5a6630f6954ab17d333abb0c936359762646076047cb8435cbbe5e31ab593aeac500ec712fcc80a10ecc9ea55e087c9bff431bc13b427e8faa3807b93a7c
+  data.tar.gz: 7ef758ee93578d624bcc67ba7826383d4f00b740f9070ce2f7bc9bb179da65acaf36e60c4e312264dd03820d6bad37bb1fae3e994a6ab924dc41f3494f4f3a54

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandr Prokopenko
+
+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,116 @@
+# nats_worker
+
+Minimal Sneakers-like worker framework for **NATS JetStream**, powered by
+[`nats-pure`](https://github.com/nats-io/nats-pure.rb). Designed to drop into
+a Rails app: put workers in `app/workers`, run them via `bin/nats_worker` or
+a rake task.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "nats_worker"
+```
+
+## Usage
+
+```ruby
+# app/workers/order_worker.rb
+class OrderWorker
+  include NatsWorker::Worker
+
+  from_stream "ORDERS",
+    subject:  "orders.>",
+    durable:  "order_worker",
+    threads:  2,
+    fetch:    10,
+    ack_wait: 30
+
+  def work(msg)
+    payload = JSON.parse(msg.data)
+    Order.create!(payload)
+    # Auto-ack on success, auto-nak on raised exception.
+    # You can still call `ack!(msg)`, `nack!(msg)`, `term!(msg)` manually.
+  end
+end
+```
+
+### Configuration
+
+```ruby
+# config/initializers/nats_worker.rb
+NatsWorker.configure do |c|
+  c.servers      = ENV.fetch("NATS_URL", "nats://127.0.0.1:4222").split(",")
+  c.nats_options = { name: "my-app", reconnect_time_wait: 1 }
+  c.logger       = Rails.logger
+  c.default_threads       = 1
+  c.default_fetch_size    = 10
+  c.default_fetch_timeout = 5
+  c.default_ack_wait      = 30
+  c.shutdown_timeout      = 25
+end
+```
+
+### Running
+
+Run all registered workers:
+
+```sh
+bundle exec nats_worker
+# or
+bundle exec rake nats_worker:work
+```
+
+Run a subset (works with both):
+
+```sh
+WORKERS=OrderWorker,PaymentWorker bundle exec nats_worker
+WORKERS=OrderWorker bundle exec rake nats_worker:work
+```
+
+Outside of Rails, point at a custom boot file:
+
+```sh
+bundle exec nats_worker -r ./my_app.rb -w OrderWorker
+```
+
+### Ack semantics
+
+* `work` returns normally → message is **acked**.
+* `work` raises → message is **nak'd** (re-delivered subject to `ack_wait`).
+* You may call `ack!(msg)` / `nack!(msg)` / `term!(msg)` explicitly; double-ack
+  is harmless.
+
+### Signals
+
+`SIGINT` / `SIGTERM` trigger graceful shutdown: the runner stops fetching new
+batches, lets in-flight `work` calls finish (up to `shutdown_timeout` seconds),
+drains the NATS connection and exits.
+
+## License
+
+MIT
+
+## Tests
+
+Unit tests:
+
+```sh
+bundle exec rspec spec/worker_spec.rb
+```
+
+End-to-end tests run against a live NATS server with JetStream enabled. The
+provided devcontainer (`.devcontainer/`) brings one up alongside the app
+container, exposing it as `nats:4222`. To run them:
+
+```sh
+# from the host:
+cd .devcontainer && docker compose -p nats_worker up -d
+docker exec -e NATS_URL=nats://nats:4222 nats_worker-app-1 \
+  bash -c "cd /workspaces/nats-worker && bundle exec rspec"
+```
+
+If `NATS_URL` does not point at a reachable server, e2e specs are auto-skipped
+(the `:integration` tag is filtered out).
+

data/bin/nats_worker

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "nats_worker"
+require "nats_worker/cli"
+
+NatsWorker::CLI.start(ARGV)

data/lib/nats_worker/cli.rb

@@ -0,0 +1,69 @@
+require "optparse"
+
+module NatsWorker
+  # Parses ARGV for `bin/nats_worker` and the rake task, loads the Rails
+  # environment when present, resolves which worker classes to run and
+  # hands them off to NatsWorker::Runner.
+  class CLI
+    def self.start(argv = ARGV)
+      new(argv).run
+    end
+
+    def initialize(argv)
+      @argv    = argv.dup
+      @options = { workers: nil, require: nil }
+    end
+
+    def run
+      parse!
+      boot_app
+      runner_classes = resolve_workers
+      Runner.new(runner_classes).run
+    end
+
+    private
+
+    def parse!
+      OptionParser.new do |o|
+        o.banner = "Usage: nats_worker [options]"
+        o.on("-w", "--workers W1,W2", Array, "Worker class names to run") { |v| @options[:workers] = v }
+        o.on("-r", "--require PATH", String, "Require a file before starting") { |v| @options[:require] = v }
+        o.on("-h", "--help") { puts o; exit 0 }
+        o.on("-v", "--version") { puts "nats_worker #{NatsWorker::VERSION}"; exit 0 }
+      end.parse!(@argv)
+
+      env_workers = ENV["WORKERS"]
+      @options[:workers] ||= env_workers.split(",").map(&:strip).reject(&:empty?) if env_workers && !env_workers.empty?
+    end
+
+    def boot_app
+      if @options[:require]
+        require File.expand_path(@options[:require])
+        return
+      end
+
+      env_path = File.expand_path("config/environment.rb")
+      if File.exist?(env_path)
+        ENV["RAILS_ENV"] ||= ENV["RACK_ENV"] || "development"
+        require env_path
+        Rails.application.eager_load! if defined?(Rails) && Rails.respond_to?(:application)
+      else
+        require "nats_worker"
+      end
+    end
+
+    def resolve_workers
+      if @options[:workers]
+        @options[:workers].map { |name| constantize(name) }
+      else
+        NatsWorker.workers
+      end
+    end
+
+    def constantize(name)
+      Object.const_get(name)
+    rescue NameError => e
+      raise NatsWorker::Error, "Unknown worker class #{name.inspect}: #{e.message}"
+    end
+  end
+end

data/lib/nats_worker/configuration.rb

@@ -0,0 +1,22 @@
+require "logger"
+
+module NatsWorker
+  class Configuration
+    attr_accessor :servers, :nats_options, :logger,
+                  :default_fetch_size, :default_fetch_timeout,
+                  :default_threads, :default_ack_wait,
+                  :shutdown_timeout
+
+    def initialize
+      @servers               = ENV.fetch("NATS_URL", "nats://127.0.0.1:4222").split(",")
+      @nats_options          = {}
+      @logger                = Logger.new($stdout)
+      @logger.level          = Logger::INFO
+      @default_fetch_size    = 10
+      @default_fetch_timeout = 5
+      @default_threads       = 1
+      @default_ack_wait      = 30
+      @shutdown_timeout      = 25
+    end
+  end
+end

data/lib/nats_worker/railtie.rb

@@ -0,0 +1,18 @@
+require "rails/railtie"
+
+module NatsWorker
+  class Railtie < ::Rails::Railtie
+    railtie_name :nats_worker
+
+    rake_tasks do
+      load File.expand_path("tasks.rake", __dir__)
+    end
+
+    # Make sure app/workers is autoloaded by Rails (it usually is via the
+    # default app autoload paths, but we add it explicitly to be safe).
+    initializer "nats_worker.autoload" do |app|
+      workers_path = app.root.join("app", "workers")
+      app.config.autoload_paths << workers_path.to_s if workers_path.exist?
+    end
+  end
+end

data/lib/nats_worker/runner.rb

@@ -0,0 +1,145 @@
+require "nats/client"
+
+module NatsWorker
+  # Runs one or more worker classes: opens a NATS connection, creates
+  # JetStream pull subscriptions and dispatches incoming messages to
+  # each worker's #work method.
+  class Runner
+    def initialize(worker_classes, config: NatsWorker.configuration)
+      @worker_classes = Array(worker_classes)
+      @config         = config
+      @logger         = config.logger
+      @threads        = []
+      @stopping       = false
+      @nats           = nil
+    end
+
+    def run
+      raise NatsWorker::Error, "no workers to run" if @worker_classes.empty?
+
+      install_signal_handlers
+      connect!
+
+      @worker_classes.each { |klass| start_worker(klass) }
+
+      @logger.info("[nats_worker] running #{@worker_classes.size} worker(s); pid=#{Process.pid}")
+      wait_for_shutdown
+    end
+
+    def stop
+      return if @stopping
+
+      @stopping = true
+      @logger.info("[nats_worker] shutting down...")
+    end
+
+    private
+
+    def install_signal_handlers
+      %w[INT TERM].each do |sig|
+        trap(sig) { stop }
+      end
+    end
+
+    def connect!
+      opts = { servers: @config.servers }.merge(@config.nats_options || {})
+      @nats = NATS.connect(**opts)
+      @logger.info("[nats_worker] connected to NATS: #{@config.servers.join(',')}")
+    end
+
+    def start_worker(klass)
+      sub_cfg  = klass.nats_subscription
+      threads  = sub_cfg[:threads]       || @config.default_threads
+      instance = klass.new
+
+      threads.times do |i|
+        @threads << Thread.new do
+          Thread.current.name = "#{klass.name}##{i}" rescue nil
+          run_pull_loop(instance, klass, sub_cfg)
+        end
+      end
+    end
+
+    def run_pull_loop(instance, klass, sub_cfg)
+      js  = @nats.jetstream
+      sub = subscribe(js, sub_cfg)
+
+      fetch_size    = sub_cfg[:fetch]         || @config.default_fetch_size
+      fetch_timeout = sub_cfg[:fetch_timeout] || @config.default_fetch_timeout
+
+      until @stopping
+        begin
+          msgs = sub.fetch(fetch_size, timeout: fetch_timeout)
+        rescue NATS::IO::Timeout
+          next
+        rescue StandardError => e
+          @logger.error("[#{klass.name}] fetch error: #{e.class}: #{e.message}")
+          sleep 1
+          next
+        end
+
+        msgs.each do |msg|
+          break if @stopping
+          dispatch(instance, klass, msg)
+        end
+      end
+    rescue StandardError => e
+      @logger.error("[#{klass.name}] fatal: #{e.class}: #{e.message}\n#{e.backtrace.first(10).join("\n")}")
+    end
+
+    def subscribe(js, sub_cfg)
+      subject = sub_cfg[:subject] || ">"
+      ensure_consumer(js, sub_cfg, subject)
+      js.pull_subscribe(subject, sub_cfg[:durable], stream: sub_cfg[:stream])
+    end
+
+    def ensure_consumer(js, sub_cfg, subject)
+      js.consumer_info(sub_cfg[:stream], sub_cfg[:durable])
+    rescue NATS::JetStream::Error::NotFound
+      ack_wait = sub_cfg[:ack_wait] || @config.default_ack_wait
+      cfg = {
+        durable_name:   sub_cfg[:durable],
+        ack_policy:     "explicit",
+        ack_wait:       ack_wait * 1_000_000_000,
+        filter_subject: subject
+      }.merge(sub_cfg[:consumer_config] || {})
+      js.add_consumer(sub_cfg[:stream], NATS::JetStream::API::ConsumerConfig.new(**cfg))
+    end
+
+    def dispatch(instance, klass, msg)
+      instance.work(msg)
+      safe_ack(msg)
+    rescue StandardError => e
+      @logger.error("[#{klass.name}] work error: #{e.class}: #{e.message}")
+      begin
+        msg.nak
+      rescue StandardError => nak_err
+        @logger.error("[#{klass.name}] nak failed: #{nak_err.class}: #{nak_err.message}")
+      end
+    end
+
+    def safe_ack(msg)
+      msg.ack
+    rescue NATS::JetStream::Error::MsgAlreadyAckd
+      # User already acked manually — fine.
+    rescue StandardError => e
+      @logger.warn("[nats_worker] ack failed: #{e.class}: #{e.message}")
+    end
+
+    def wait_for_shutdown
+      sleep 0.5 until @stopping
+      deadline = Time.now + @config.shutdown_timeout
+      @threads.each do |t|
+        remaining = deadline - Time.now
+        t.join(remaining.positive? ? remaining : 0)
+      end
+      @threads.select(&:alive?).each(&:kill)
+      @nats&.drain
+    rescue StandardError => e
+      @logger.error("[nats_worker] shutdown error: #{e.class}: #{e.message}")
+    ensure
+      @nats&.close rescue nil
+      @logger.info("[nats_worker] stopped")
+    end
+  end
+end

data/lib/nats_worker/tasks.rake

@@ -0,0 +1,11 @@
+require "nats_worker/cli"
+
+namespace :nats_worker do
+  desc "Run NATS JetStream workers (use WORKERS=Foo,Bar to limit)"
+  task work: :environment do
+    Rails.application.eager_load! if defined?(Rails)
+    argv = []
+    argv += ["--workers", ENV["WORKERS"]] if ENV["WORKERS"] && !ENV["WORKERS"].empty?
+    NatsWorker::CLI.start(argv)
+  end
+end

data/lib/nats_worker/version.rb

@@ -0,0 +1,3 @@
+module NatsWorker
+  VERSION = "0.1.0".freeze
+end

data/lib/nats_worker/worker.rb

@@ -0,0 +1,78 @@
+module NatsWorker
+  # Mix in to make a class a NATS JetStream worker.
+  #
+  # Example:
+  #   class OrderWorker
+  #     include NatsWorker::Worker
+  #
+  #     from_stream "ORDERS",
+  #       subject:  "orders.>",
+  #       durable:  "order_worker",
+  #       threads:  2,
+  #       fetch:    10,
+  #       ack_wait: 30
+  #
+  #     def work(msg)
+  #       payload = JSON.parse(msg.data)
+  #       # ... do something ...
+  #     end
+  #   end
+  module Worker
+    def self.included(base)
+      base.extend(ClassMethods)
+      NatsWorker.register(base)
+    end
+
+    # The framework auto-acks on success and nacks on exception, but workers
+    # may call these explicitly if they want finer control.
+    def ack!(msg);  msg.ack;  end
+    def nack!(msg); msg.nak;  end
+    def term!(msg); msg.term; end
+
+    def logger
+      NatsWorker.logger
+    end
+
+    module ClassMethods
+      # Subscription configuration for this worker.
+      #
+      # @param stream [String] JetStream stream name (required)
+      # @param subject [String] subject filter (defaults to ">" inside the stream)
+      # @param durable [String] durable consumer name (defaults to class name underscored)
+      # @param threads [Integer] number of pull-loop threads
+      # @param fetch [Integer] batch size for each pull
+      # @param fetch_timeout [Integer] seconds to wait for a batch
+      # @param ack_wait [Integer] consumer ack_wait in seconds
+      # @param consumer_config [Hash] extra fields merged into the consumer config
+      def from_stream(stream, subject: nil, durable: nil, threads: nil,
+                      fetch: nil, fetch_timeout: nil, ack_wait: nil,
+                      consumer_config: {})
+        @nats_subscription = {
+          stream:          stream,
+          subject:         subject,
+          durable:         durable || default_durable_name,
+          threads:         threads,
+          fetch:           fetch,
+          fetch_timeout:   fetch_timeout,
+          ack_wait:        ack_wait,
+          consumer_config: consumer_config
+        }
+      end
+
+      def nats_subscription
+        @nats_subscription or raise NatsWorker::Error,
+          "#{name} did not declare from_stream(...)"
+      end
+
+      private
+
+      def default_durable_name
+        n = name.to_s.gsub("::", "/")
+        n.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+         .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+         .tr("/", "_")
+         .downcase
+      end
+    end
+  end
+end

data/lib/nats_worker.rb

@@ -0,0 +1,35 @@
+require "logger"
+
+require "nats_worker/version"
+require "nats_worker/configuration"
+require "nats_worker/worker"
+require "nats_worker/runner"
+
+module NatsWorker
+  class Error < StandardError; end
+
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def logger
+      configuration.logger
+    end
+
+    # Registry of worker classes that included NatsWorker::Worker.
+    def workers
+      @workers ||= []
+    end
+
+    def register(worker_class)
+      workers << worker_class unless workers.include?(worker_class)
+    end
+  end
+end
+
+require "nats_worker/railtie" if defined?(Rails::Railtie)

data/nats_worker.gemspec

@@ -0,0 +1,21 @@
+Gem::Specification.new do |s|
+  s.name        = "nats_worker"
+  s.version     = "0.1.0"
+  s.summary     = "Minimal worker framework for NATS JetStream"
+  s.description = "Drop-in workers for Rails (app/workers) that consume NATS JetStream " \
+                  "streams via pull-based subscriptions, using nats-pure."
+  s.authors     = ["nats_worker contributors"]
+  s.license     = "MIT"
+  s.required_ruby_version = ">= 2.7"
+
+  s.files = Dir["lib/**/*", "bin/*", "README.md", "LICENSE", "nats_worker.gemspec"]
+  s.bindir      = "bin"
+  s.executables = ["nats_worker"]
+  s.require_paths = ["lib"]
+
+  s.add_dependency "nats-pure", ">= 2.3"
+  s.add_dependency "concurrent-ruby", ">= 1.1"
+
+  s.add_development_dependency "rspec", "~> 3.12"
+  s.add_development_dependency "rake", "~> 13.0"
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: nats_worker
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- nats_worker contributors
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nats-pure
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Drop-in workers for Rails (app/workers) that consume NATS JetStream streams
+  via pull-based subscriptions, using nats-pure.
+email:
+executables:
+- nats_worker
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/nats_worker
+- lib/nats_worker.rb
+- lib/nats_worker/cli.rb
+- lib/nats_worker/configuration.rb
+- lib/nats_worker/railtie.rb
+- lib/nats_worker/runner.rb
+- lib/nats_worker/tasks.rake
+- lib/nats_worker/version.rb
+- lib/nats_worker/worker.rb
+- nats_worker.gemspec
+homepage:
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Minimal worker framework for NATS JetStream
+test_files: []