snerdmq 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afc0a9b03631b02d3f9e17a6a998dde6e09620bb240c8f34c28c6c99593919d2
-  data.tar.gz: 874f0ab2ccc9b6335cbdf42ea1735aba9e2350df03dbb12b2f6113293a73524e
+  metadata.gz: 7b03b1fe8237e88a2fac994242af4955576569853c3794dbc49671644c506921
+  data.tar.gz: be2955f250acc99685168e2b5f9193faa5e9b8910fa5b7b209f3d027f96b7383
 SHA512:
-  metadata.gz: a54654999159b9985a6bb90930dcbdd54a917c95b0dc36ba85c4450b0ade16f93cf491fef47eafa1b6887f3ccd9f599ddc3574ff6b344ea3bd4937e53d53d4a8
-  data.tar.gz: be4656365456108a065abfe48fbde90e65102218eb46c591ba772c77aedeeb0b2498c04bb9ddd21ca996c3711ea40088672c03a9efdecafed0af303a6292380b
+  metadata.gz: 27ddbdaa2acb42240c500878c509affb9d32e7acf9e4ffac3679b2a80cb1039582420670cfc11092bceb872cf347c7ffc9436bef2346aada6a0dcaada070da7d
+  data.tar.gz: ebbe4b904bdd68cd8750aaa339cc29cffa32437431686b36ca69547c95abf831b3faed39d1987544e614044fc729bbcd78c98fb66f3b869f9be8880eb12a69bd

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Description
+Please include a summary of the change and which issue is fixed (if any). Please also include relevant motivation and context.
+
+## Type of Change
+Please check the options that are relevant.
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Performance improvement
+
+## Checklist
+- [ ] I have read the `CONTRIBUTING.md` document.
+- [ ] My code follows the style guidelines of this project.
+- [ ] I have performed a self-review of my own code.
+- [ ] I have commented my code, particularly in hard-to-understand areas.
+- [ ] I have made corresponding changes to the documentation.
+- [ ] I have added tests that prove my fix is effective or that my feature works.
+- [ ] New and existing unit tests pass locally with my changes.

data/.snerdata/tasks/tasks.log

@@ -1 +1,2 @@
 {"taskId":"ruby-job-1","retryCount":0,"maxRetries":3,"retryAfterHours":0.0,"retryAfterTime":"2026-08-14T09:43:50.902732Z","taskData":"{\"user_id\":\"ruby_master\",\"message\":\"matz\"}","taskType":"test_ruby_job"}
+{"taskId":"ruby-job-1","retryCount":0,"maxRetries":3,"retryAfterHours":0.0,"retryAfterTime":"2026-08-16T10:42:24.239760Z","taskData":"{\"user_id\":\"ruby_master\",\"message\":\"matz\"}","taskType":"test_ruby_job","executeAt":"2026-08-16T10:42:24.239760Z"}

data/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to SnerdMQ
+
+First off, thank you for considering contributing to SnerdMQ! It's people like you that make open-source software such a great community to learn, inspire, and create.
+
+## How to Contribute
+
+### 1. Fork and Clone
+We use the standard GitHub Fork and Pull Request workflow. 
+1. Click the "Fork" button in the top right corner of the repository.
+2. Clone your fork locally: `git clone https://github.com/YOUR_USERNAME/snerdmq-ruby.git`
+
+### 2. Branching Strategy
+Create a branch for your feature or bug fix:
+```bash
+git checkout -b feat/your-feature-name
+# or
+git checkout -b fix/your-bugfix-name
+```
+Never commit directly to the `main` or `master` branch of your fork.
+
+### 3. Making Changes
+- Ensure your code follows the existing conventions and paradigms in the repository.
+- Write clear, concise, and descriptive commit messages.
+- If you're fixing a bug, please add a test that catches the bug to ensure it doesn't happen again.
+- If you're adding a feature, please add appropriate tests and update the `README.md` if necessary.
+
+### 4. Submitting a Pull Request
+1. Push your branch to your fork: `git push origin your-branch-name`
+2. Go to the original SnerdMQ repository and click "Compare & pull request".
+3. Fill out the provided Pull Request template completely. Provide context, what you've changed, and how you tested it.
+4. Wait for a maintainer to review your code. We may request some changes before it can be merged!
+
+## Code of Conduct
+By participating in this project, you are expected to uphold a welcoming, respectful, and inclusive environment for everyone.

data/Gemfile.lock

@@ -1,13 +1,29 @@
 PATH
   remote: .
   specs:
-    snerdmq (1.0.0)
+    snerdmq (0.3.0)
+      faye-websocket
+      puma
+      rack
 
 GEM
   remote: https://rubygems.org/
   specs:
+    base64 (0.1.1)
+    eventmachine (1.2.7)
+    faye-websocket (0.12.0)
+      eventmachine (>= 0.12.0)
+      websocket-driver (>= 0.8.0)
     minitest (5.27.0)
+    nio4r (2.7.5)
+    puma (8.0.2)
+      nio4r (~> 2.0)
+    rack (3.2.7)
     rake (13.4.2)
+    websocket-driver (0.8.2)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
 
 PLATFORMS
   arm64-darwin-24

data/README.md

@@ -1,6 +1,6 @@
 <div align="center">
   <img src="./assets/Designer-9.png" height="120" alt="SnerdMQ Ruby Logo" />
-  <h1>💎 SnerdMQ Ruby SDK v0.2.1</h1>
+  <h1>💎 SnerdMQ Ruby SDK v0.3.1</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)
@@ -8,7 +8,7 @@
 
 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.
 
-## ✨ v0.2.1 AI-Era Features
+## ✨ v0.3.1 AI Features
 - **Smart API Rate-Limiting**: Natively tracks `rate_limit_group` execution velocity to prevent 429 "Too Many Requests" API errors.
 - **Payload-Hashing Deduplication**: Automatically computes cryptographic hashes to drop duplicate tasks instantly.
 - **Dynamic Float Prioritization**: A native Binary Max-Heap bypasses standard FIFO rules for high urgency tasks.
@@ -16,13 +16,31 @@ This is the official Ruby SDK wrapper for **SnerdMQ**. It handles all JSON-RPC c
 - **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.
 
-### ⚙️ Advanced Task Configuration (v0.2.1)
+### ⚙️ Advanced Task Configuration (v0.3.1)
 To power complex AI workflows, tasks can now be configured with advanced orchestration parameters:
 
 * **`auto_dedupe` (`true/false`)**: If set to `true`, the daemon computes a cryptographic hash of the `task_type` and `data`. If an identical payload is currently sitting in the queue pending execution, this new task is silently dropped. Excellent for preventing duplicate generative AI requests from trigger-happy users!
 * **`urgency_score` (`Float`)**: A value (e.g. `0.99`) used to bypass the standard FIFO queue. SnerdMQ uses a true Binary Max-Heap to continually float tasks with the highest urgency score to the very front of the execution line. Standard tasks default to `0.0`.
 * **`rate_limit_group` (`String`)**: A custom string (e.g. `"openai_api"` or `"db_writes"`) that groups tasks together for backpressure control.
 * **`max_per_minute` (`Integer`)**: Used in conjunction with `rate_limit_group`. If the queue processes more tasks in this group than the allowed limit within a 60-second rolling window, further tasks in this group are temporarily paused. This natively prevents 429 "Too Many Requests" errors when bursting third-party APIs.
+* **`execute_at` (`String` | `Time`)**: A timestamp of when the job should be executed in the future.
+* **`cron` (`String`)**: A cron expression (e.g. `"0 * * * *"`) for recurring jobs. Shorthands like `"2h"` or `"10m"` are also supported.
+* **`webhook_url` (`String`)**: By providing a webhook URL, SnerdMQ will completely bypass your local Ruby blocks and dispatch the task payload via an HTTP POST request directly to the specified URL.
+* **`max_execution_seconds` (`Integer`)**: Optional hard timeout in seconds. If execution takes longer, it's marked as failed.
+
+### Note on Hard Timeouts (`max_execution_seconds`)
+When `max_execution_seconds` is provided, the Ruby SDK wraps the execution of your handler in a `Timeout.timeout` block. If the task takes longer than the timeout, a `Timeout::Error` is raised and the execution will be marked as failed. The background Rust daemon also enforces this timeout at the IPC level.
+
+### 🌐 HTTP Webhooks (Serverless Execution)
+You can configure a task to execute externally via an HTTP POST request. By setting a `webhook_url`, the internal background processor will skip any registered handlers (`queue.register_handler`) and directly invoke the HTTP endpoint.
+
+If the HTTP endpoint returns a non-200 status code, it triggers a retry. If it permanently fails (reaches `max_retries`), the Dead Letter Queue event is automatically fired via a final HTTP POST to the same `webhook_url` but with the header `X-SnerdMQ-Event: MaxRetriesReached`.
+
+### 🕒 Cron Jobs vs. Retryable Jobs
+When using the new scheduling features, it is important to understand the difference between Cron and Retry behaviors:
+> - **A Cron Job** is a *Repeatable Job* that executes again **only after a success**, on a fixed schedule.
+> - **A Retryable Job** is a *Recovery Job* that executes again **only after a failure**, attempting to recover using the `retry_after_hours` backoff.
+> - **Combined:** If a Cron Job fails, it temporarily uses `retry_after_hours` to retry until it recovers. Once it succeeds, it goes back to ticking on its standard cron schedule!
 
 ## 📦 Installation
 
@@ -75,7 +93,10 @@ queue.enqueue(
   rate_limit_group: "email_api",
   max_per_minute: 100,
   auto_dedupe: true,
-  urgency_score: 0.99
+  urgency_score: 0.99,
+  cron: "1h",
+  webhook_url: "https://api.example.com/webhook",
+  max_execution_seconds: 300
 )
 
 # Keep main thread alive

data/lib/snerdmq/queue.rb

@@ -1,5 +1,6 @@
 require 'json'
 require 'thread'
+require 'timeout'
 
 module Snerdmq
   class SnerdQueue
@@ -72,7 +73,7 @@ module Snerdmq
       end
     end
 
-    def enqueue(task_id:, task_type:, data:, max_retries: 3, retry_after_hours: 0.0, rate_limit_group: nil, max_per_minute: nil, auto_dedupe: false, urgency_score: nil)
+    def enqueue(task_id:, task_type:, data:, max_retries: 3, retry_after_hours: 0.0, rate_limit_group: nil, max_per_minute: nil, auto_dedupe: false, urgency_score: nil, execute_at: nil, cron: nil, webhook_url: nil, max_execution_seconds: nil)
       raise "[Snerd] Cannot enqueue task: Queue is not running. Call start_listening first." if @io.nil? || @shutting_down
       
       payload = {
@@ -88,6 +89,13 @@ module Snerdmq
       payload[:max_per_minute] = max_per_minute if max_per_minute
       payload[:auto_dedupe] = auto_dedupe if auto_dedupe
       payload[:urgency_score] = urgency_score if urgency_score
+      
+      if execute_at
+        payload[:execute_at] = execute_at.respond_to?(:iso8601) ? execute_at.iso8601 : execute_at.to_s
+      end
+      payload[:cron] = cron if cron
+      payload[:webhook_url] = webhook_url if webhook_url
+      payload[:max_execution_seconds] = max_execution_seconds if max_execution_seconds
 
       cond = ConditionVariable.new
       result = nil
@@ -208,6 +216,7 @@ module Snerdmq
     def handle_execute(msg)
       task_id = msg["task_id"]
       task_type = msg["task_type"]
+      max_execution_seconds = msg["max_execution_seconds"]
       
       raw_data = msg["task_data"]
       task_data = raw_data.is_a?(String) ? JSON.parse(raw_data) : raw_data
@@ -229,12 +238,25 @@ module Snerdmq
 
       begin
         Thread.current[:snerd_task_id] = task_id
-        handler.call(task_data)
+        if max_execution_seconds
+          Timeout.timeout(max_execution_seconds) do
+            handler.call(task_data)
+          end
+        else
+          handler.call(task_data)
+        end
         send_message({
           action: "result",
           task_id: task_id,
           status: "success"
         })
+      rescue Timeout::Error
+        send_message({
+          action: "result",
+          task_id: task_id,
+          status: "error",
+          error_msg: "Task execution timed out after #{max_execution_seconds} seconds"
+        })
       rescue => e
         send_message({
           action: "result",

data/snerdmq.gemspec

@@ -3,7 +3,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = "snerdmq"
-  spec.version       = "0.2.1"
+  spec.version       = "0.3.1"
   spec.authors       = ["Greyhands2"]
   spec.email         = ["developer@example.com"]
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: snerdmq
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - Greyhands2
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-15 00:00:00.000000000 Z
+date: 2026-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -103,8 +103,10 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/PULL_REQUEST_TEMPLATE.md"
 - ".gitignore"
 - ".snerdata/tasks/tasks.log"
+- CONTRIBUTING.md
 - Gemfile
 - Gemfile.lock
 - README.md