snerdmq 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a66bf4a4c973c7d263b27734aa0daff33fa3f098b7faec5b05c0a10dd6baa773
+  data.tar.gz: '02592325c65fe165bb87f20ec34a4b34601f16b677dc9fb15f1942239150a1df'
+SHA512:
+  metadata.gz: 931dbad342f26fa5cbe24542de79cd5f740973a06e2b214be4d4274ba1ebfd5d79921d02db6365df01dcc6f64d3fc2aa4d98ae8d466aaae3945da7c51f9ce52d
+  data.tar.gz: 7c636234b92c48b47f9c82f3b6fde858a3fd19be8328935f5bf2067107a88f5f3dc07c5cb72b74def125491b21cbd92aef58a49c3bd9b86296269f482f834ebc

data/.gitignore

@@ -0,0 +1,13 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+/bin/snerdmq*
+!/bin/snerdmq-install

data/.snerdata/tasks/tasks.log

@@ -0,0 +1 @@
+{"taskId":"ruby-job-1","retryCount":0,"maxRetries":3,"retryAfterHours":0.0,"retryAfterTime":"2026-08-12T15:48:11.816678Z","taskData":"{\"user_id\":\"ruby_master\",\"message\":\"matz\"}","taskType":"test_ruby_job"}

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,22 @@
+PATH
+  remote: .
+  specs:
+    snerdmq (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (5.27.0)
+    rake (13.4.2)
+
+PLATFORMS
+  arm64-darwin-24
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  snerdmq!
+
+BUNDLED WITH
+   2.4.10

data/README.md

@@ -0,0 +1,85 @@
+<div align="center">
+  <h1>💎 SnerdMQ Ruby SDK</h1>
+  <p>A zero-config, C-speed background job queue for Ruby. Ditch Redis and Sidekiq for lightweight, persistent background jobs.</p>
+
+  [![Gem Version](https://badge.fury.io/rb/snerdmq.svg)](https://badge.fury.io/rb/snerdmq)
+</div>
+
+This is the official Ruby SDK wrapper for **SnerdMQ**. It handles all JSON-RPC communication and `IO.popen` orchestration so you can write lightning-fast background jobs without managing any external databases like Redis or Postgres.
+
+## ✨ Features
+- **Ditch Sidekiq & Redis**: Gives your Ruby apps persistent state, automatic retries, and dead-letter queues right out of the box with zero external infrastructure.
+- **Zero Rust Required**: Our gem installation script automatically downloads the pre-compiled C-speed Rust binary for your OS.
+- **Thread Safe**: Uses native Ruby `Thread`s and `Mutex` locks to orchestrate I/O without blocking your main event loop.
+
+## 📦 Installation
+
+Installing the SDK is a simple two-step process:
+
+**1. Install the gem:**
+```bash
+gem install snerdmq
+# Or add `gem 'snerdmq'` to your Gemfile
+```
+
+**2. Download the Rust Engine:**
+Run this script from your terminal immediately after installing the gem. It will fetch the correct highly-optimized SnerdMQ binary for your operating system (macOS/Linux/Windows) and place it securely inside the gem installation directory:
+```bash
+snerdmq-install
+```
+
+---
+
+## ⚡ Quickstart
+
+Using the SDK is incredibly simple. Initialize the queue, register your handler blocks, and start listening!
+
+```ruby
+require 'snerdmq'
+
+# 1. Initialize the daemon in the background
+queue = Snerdmq::SnerdQueue.new
+
+# 2. Register your background job logic using a standard block
+queue.register_handler("send_email") do |data|
+  to = data["to"]
+  subject = data["subject"]
+  puts "Sending email to #{to} with subject: #{subject}..."
+  
+  # Raise an exception here to automatically trigger SnerdMQ's retry logic!
+end
+
+# 3. Start the non-blocking Thread listeners
+queue.start_listening
+puts "SnerdMQ Ruby SDK is listening for jobs..."
+
+# 4. Enqueue a job from anywhere in your codebase
+queue.enqueue(
+  task_id: "email-123",
+  task_type: "send_email",
+  data: { "to" => "john@wick.com", "subject" => "Continental Update" },
+  max_retries: 3,
+  retry_after_hours: 0.0
+)
+
+# Keep main thread alive
+sleep
+```
+
+---
+
+## 🌍 Advanced: Distributed Scaling
+
+By default, the SDK spins up the Rust daemon which writes the queue to a local file (`.snerdata/tasks/tasks.log`). 
+
+If you have multiple Ruby microservices (or Rails instances) running behind a load balancer and want them to share the exact same queue, simply mount a **Shared Network Drive** (like AWS EFS or NFS) to all of your servers and pass the shared path:
+
+```ruby
+require 'snerdmq'
+
+# All of your Ruby servers point to the exact same shared file!
+# SnerdMQ's native OS file-locking guarantees zero data corruption.
+queue = Snerdmq::SnerdQueue.new(storage_path: "/mnt/aws-efs-shared-drive/snerd_tasks.log")
+```
+
+*Built with ❤️ for John Wick tier engineering.*

data/Rakefile

@@ -0,0 +1,9 @@
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+task default: :test

data/bin/snerdmq-install

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+
+require 'net/http'
+require 'uri'
+require 'fileutils'
+require 'rbconfig'
+
+REPO = "greyhands2/snerdmq"
+VERSION = "v0.1.1"
+
+# Determine OS and Architecture
+host_os = RbConfig::CONFIG['host_os']
+host_cpu = RbConfig::CONFIG['host_cpu']
+
+platform = case host_os
+           when /darwin|mac os/
+             'macos'
+           when /linux/
+             'linux'
+           when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+             'windows'
+           else
+             puts "[Snerd] Unsupported OS: #{host_os}"
+             exit 1
+           end
+
+architecture = case host_cpu
+               when /x86_64|amd64/
+                 'x64'
+               when /arm64|aarch64/
+                 'arm64'
+               else
+                 puts "[Snerd] Unsupported Architecture: #{host_cpu}"
+                 exit 1
+               end
+
+extension = platform == 'windows' ? '.exe' : ''
+binary_name = "snerdmq-#{platform}-#{architecture}#{extension}"
+
+download_url = "https://github.com/#{REPO}/releases/download/#{VERSION}/#{binary_name}"
+
+# In Ruby, gems are installed in a global read-only directory. 
+# It's best to download the binary into the gem's `bin` directory so it ships alongside the library.
+dest_dir = File.expand_path(__dir__)
+dest_path = File.join(dest_dir, "snerdmq#{extension}")
+
+puts "[Snerd] Downloading pre-compiled engine from GitHub: #{binary_name}..."
+
+uri = URI.parse(download_url)
+response = Net::HTTP.get_response(uri)
+
+if response.is_a?(Net::HTTPRedirection)
+  uri = URI.parse(response['location'])
+  response = Net::HTTP.get_response(uri)
+end
+
+if response.code == '404'
+  puts "\n[Snerd] WARN: Binary not found at #{download_url}"
+  puts "[Snerd] (This is expected if you haven't published a GitHub Release yet)"
+  puts "[Snerd] Please provide binary_path manually when initializing SnerdQueue.\n"
+  exit 0
+elsif response.code != '200'
+  puts "[Snerd] Failed to download binary: HTTP #{response.code}"
+  exit 1
+end
+
+File.open(dest_path, "wb") do |file|
+  file.write(response.body)
+end
+
+FileUtils.chmod(0755, dest_path)
+
+puts "[Snerd] Successfully installed Snerd Engine to #{dest_path}!"

data/lib/snerdmq/queue.rb

@@ -0,0 +1,161 @@
+require 'json'
+require 'thread'
+
+module Snerdmq
+  class SnerdQueue
+    def initialize(binary_path: nil, storage_path: nil)
+      @binary_path = binary_path
+      @storage_path = storage_path
+      
+      if @binary_path.nil?
+        ext = RbConfig::CONFIG['host_os'].match?(/mswin|msys|mingw|cygwin|bccwin|wince|emc/) ? '.exe' : ''
+        # Assume the binary was downloaded into the gem's bin/ directory via snerdmq-install
+        @binary_path = File.expand_path("../../bin/snerdmq#{ext}", __dir__)
+      end
+
+      unless File.exist?(@binary_path)
+        raise "[Snerd] Binary not found at #{@binary_path}. Ensure it is compiled or run 'snerdmq-install'."
+      end
+
+      @handlers = {}
+      @handlers_mutex = Mutex.new
+      
+      @stdin_mutex = Mutex.new
+      @shutting_down = false
+      @io = nil
+      @listener_thread = nil
+    end
+
+    def register_handler(task_type, &block)
+      @handlers_mutex.synchronize do
+        @handlers[task_type] = block
+      end
+
+      if @io && !@shutting_down
+        send_message({
+          action: "register",
+          task_type: task_type
+        })
+      end
+    end
+
+    def start_listening
+      args = []
+      args << @storage_path if @storage_path
+
+      # Open a bidirectional pipe to the Rust daemon
+      @io = IO.popen([@binary_path] + args, "r+")
+
+      # Re-register all existing handlers
+      @handlers_mutex.synchronize do
+        @handlers.keys.each do |task_type|
+          send_message({
+            action: "register",
+            task_type: task_type
+          })
+        end
+      end
+
+      @listener_thread = Thread.new do
+        listen_to_stdout
+      end
+    end
+
+    def enqueue(task_id:, task_type:, data:, max_retries: 3, retry_after_hours: 0.0)
+      raise "[Snerd] Cannot enqueue task: Queue is not running. Call start_listening first." if @io.nil? || @shutting_down
+      
+      send_message({
+        action: "enqueue",
+        task_id: task_id,
+        task_type: task_type,
+        task_data: data.to_json,
+        max_retries: max_retries,
+        retry_after_hours: retry_after_hours
+      })
+    end
+
+    def shutdown
+      @shutting_down = true
+      begin
+        Process.kill("TERM", @io.pid) if @io && @io.pid
+      rescue Errno::ESRCH, Errno::ECHILD
+        # Process already dead
+      end
+      
+      @listener_thread.join(2) if @listener_thread
+      @io.close if @io && !@io.closed?
+    end
+
+    private
+
+    def send_message(msg)
+      @stdin_mutex.synchronize do
+        return if @shutting_down || @io.nil? || @io.closed?
+        @io.puts(msg.to_json)
+        @io.flush
+      end
+    rescue Errno::EPIPE
+      # Broken pipe if the daemon died unexpectedly
+    end
+
+    def listen_to_stdout
+      @io.each_line do |line|
+        next if line.strip.empty?
+
+        begin
+          msg = JSON.parse(line)
+          
+          if msg["action"] == "execute"
+            # Execute in a short-lived thread so we don't block the stdout listener loop
+            Thread.new { handle_execute(msg) }
+          elsif msg["action"] == "max_retries_reached"
+            warn "[Snerd] Dead Letter Queue: Task #{msg['task_id']} (#{msg['task_type']}) permanently failed."
+          end
+        rescue JSON::ParserError
+          # Ignore malformed stdout lines
+        end
+      end
+    rescue IOError, Errno::EPIPE
+      # Normal when shutting down
+    end
+
+    def handle_execute(msg)
+      task_id = msg["task_id"]
+      task_type = msg["task_type"]
+      
+      raw_data = msg["task_data"]
+      task_data = raw_data.is_a?(String) ? JSON.parse(raw_data) : raw_data
+
+      handler = nil
+      @handlers_mutex.synchronize do
+        handler = @handlers[task_type]
+      end
+
+      unless handler
+        send_message({
+          action: "result",
+          task_id: task_id,
+          status: "error",
+          error_msg: "No handler registered."
+        })
+        return
+      end
+
+      begin
+        handler.call(task_data)
+        send_message({
+          action: "result",
+          task_id: task_id,
+          status: "success"
+        })
+      rescue => e
+        send_message({
+          action: "result",
+          task_id: task_id,
+          status: "error",
+          error_msg: e.message
+        })
+      end
+    end
+  end
+end

data/lib/snerdmq.rb

@@ -0,0 +1,5 @@
+require_relative "snerdmq/queue"
+
+module Snerdmq
+  class Error < StandardError; end
+end

data/snerdmq.gemspec

@@ -0,0 +1,25 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.name          = "snerdmq"
+  spec.version       = "1.0.0"
+  spec.authors       = ["Greyhands2"]
+  spec.email         = ["developer@example.com"]
+
+  spec.summary       = "A zero-config, persistent background job queue for Ruby."
+  spec.description   = "The official Ruby SDK for the SnerdMQ Rust daemon. Execute robust, lightning-fast background jobs without Redis."
+  spec.homepage      = "https://github.com/greyhands2/snerdmq-ruby"
+  spec.license       = "MIT"
+
+  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "bin"
+  spec.executables   = ["snerdmq-install"]
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: snerdmq
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Greyhands2
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: The official Ruby SDK for the SnerdMQ Rust daemon. Execute robust, lightning-fast
+  background jobs without Redis.
+email:
+- developer@example.com
+executables:
+- snerdmq-install
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".snerdata/tasks/tasks.log"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- bin/snerdmq-install
+- lib/snerdmq.rb
+- lib/snerdmq/queue.rb
+- snerdmq.gemspec
+homepage: https://github.com/greyhands2/snerdmq-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: A zero-config, persistent background job queue for Ruby.
+test_files: []