rust_on_background 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d02d4e6d02e8cd7bc23d630c36fe81cca4ad224d34f5e03a5fb418f06bac6edf
+  data.tar.gz: 010bd6fd680da034fcead075f2c85cb7e243a823b00f0d1877926eea20af973a
+SHA512:
+  metadata.gz: ad6725af3e3e3cda056251d51e09680c38587ffa4d4e88c2aea442669c55b2a51b90fcd3df4d3ee5867fd5e1862f2a60f95c0d48a1e4a30ebdc1fbccfc7192cf
+  data.tar.gz: d66d46c7032f3d0955e0a0ceafc499422d87c8d55599dafd61e50de346da0e1813cfb2d04df31b56a1f1a547b3ecad6fbb0ec75055a0fab495b2498cc6511a6e

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-03-13
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 QuarkXZ
+
+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,338 @@
+# RustOnBackground
+
+Run background jobs in Rust. Run a few commands and you're all set up - just scaffold and write Rust. [Jump to quick start](#quick-start)
+
+```ruby
+# Rails: enqueue a job
+RustOnBackground.perform("send_email", user_id: 123, template: "welcome")
+
+# Schedule for later
+RustOnBackground.perform_at(1.hour.from_now, "cleanup", batch_size: 100)
+```
+
+## Features
+
+- Rails generators for instant setup, very easy
+- Auto-detects database adapter (MySQL, PostgreSQL, SQLite) from your database.yml config
+- Scaffolding: Auto-generates Rust structs from ActiveRecord models (You can do just partial scaffold only to create the structs from schema)
+- Multiple queues with configurable worker counts
+- Scheduled jobs with `perform_at`
+- Environment-specific configs (`config.development.toml`, `config.production.toml`)
+- Automatic retries with configurable retry count
+- Rake tasks for everything: `build`, `start`, `stop`, `restart`, `status`, `rebuild`
+
+## Requirements
+
+- Ruby 2.5+
+- Rails 5.0+
+- Redis 4.0+
+- Rust 1.70+ ([install](https://rustup.rs))
+
+## Quick Start
+
+Add to your Gemfile:
+
+```ruby
+gem "rust_on_background"
+```
+
+Run bundle install:
+
+```bash
+bundle install
+```
+
+This creates the Rust project structure at `app/jobs/rust/` and detects your database configuration automatically:
+
+```bash
+rails generate rust_on_background:install
+```
+
+
+```bash
+# Create a job (generates app/jobs/rust/src/jobs/send_email.rs)
+rails generate rust_on_background:job send_email user_id:integer message:string
+
+# Build
+rake rust_on_background:build
+
+# Start workers
+rake rust_on_background:start
+
+# Enqueue from Rails
+RustOnBackground.perform("send_email", user_id: 1, message: "welcome")
+```
+
+## Project Structure
+
+After installation, your Rails app will have:
+
+```
+app/jobs/rust/
+├── Cargo.toml                    # Rust dependencies (add crates here)
+├── config.development.toml       # Dev config (auto-generated)
+├── config.production.toml        # Create this for production
+└── src/
+    ├── main.rs                   # Don't need to touch this
+    ├── worker.rs                 # Don't need to touch this
+    ├── scheduler.rs              # Don't need to touch this
+    └── jobs/                     # YOUR CODE GOES HERE
+        ├── mod.rs                # Auto-updated by generator, this is basically a controller for the jobs(scaffolding creates the action for you in here)
+        └── send_email.rs         # Example job file
+```
+
+## Configuration
+
+Environment-specific config files in `app/jobs/rust/`:
+
+```toml
+# config.development.toml
+
+[database]
+url = "mysql://root@localhost/myapp_development"
+
+[redis]
+url = "redis://127.0.0.1:6379"
+
+[logging]
+path = "log/development.log" # can leave empty for no logs
+
+# Define your queues
+[[queues]]
+name = "default"
+workers = 4
+
+[[queues]]
+name = "emails"
+workers = 2
+
+# Scheduler settings (optional)
+# [scheduler]
+# poll_interval_ms = 1000
+# batch_size = 100
+```
+
+## Generating Jobs
+
+### Basic job
+
+```bash
+rails generate rust_on_background:job cleanup
+```
+
+### Job with typed arguments
+
+```bash
+rails generate rust_on_background:job send_email user_id:integer template:string urgent:boolean
+```
+
+Generates:
+
+```rust
+#[derive(Debug, Deserialize)]
+struct Args {
+    user_id: i64,
+    template: String,
+    urgent: bool,
+}
+
+pub async fn run(args: &serde_json::Value, _database_url: &str) -> JobResult {
+    let args: Args = serde_json::from_value(args.clone())?;
+    // Your logic here
+    JobResult::Success
+}
+```
+
+### Job with ActiveRecord model
+
+```bash
+rails generate rust_on_background:job process_order order:Order
+```
+
+The generator reads your model's columns from the database and creates a matching Rust struct:
+
+```rust
+#[derive(Debug, Deserialize)]
+struct Order {
+    id: i64,
+    user_id: i64,
+    total: f64,
+    status: String,
+    created_at: String,
+    updated_at: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct Args {
+    order: Order,
+}
+```
+
+## Enqueuing Jobs
+
+### Immediate execution
+
+```ruby
+RustOnBackground.perform("job_name", arg1: "value", arg2: 123) # (default queue if not specified)
+```
+
+### With specific queue
+
+```ruby
+RustOnBackground.perform("send_email", queue: "emails", user_id: 1)
+```
+
+### With retry count
+
+```ruby
+RustOnBackground.perform("flaky_job", retry_count: 5, data: "...")
+```
+
+### Scheduled execution
+
+```ruby
+# Run in 1 hour
+RustOnBackground.perform_at(1.hour.from_now, "cleanup")
+
+# Run at specific time
+RustOnBackground.perform_at(Date.tomorrow.noon, "daily_report")
+
+# With all options
+RustOnBackground.perform_at(
+  30.minutes.from_now,
+  "send_reminder",
+  queue: "emails",
+  retry_count: 3,
+  user_id: 123
+)
+```
+
+## Supported Types
+
+| Ruby/Rails Type | Rust Type |
+|-----------------|-----------|
+| `string`, `text` | `String` |
+| `integer`, `bigint` | `i64` |
+| `float`, `decimal` | `f64` |
+| `boolean` | `bool` |
+| `array`, `set` | `Vec<serde_json::Value>` |
+| `hash`, `json`, `jsonb` | `serde_json::Value` |
+| `date`, `datetime`, `time` | `String` |
+| `uuid` | `String` |
+| `binary`, `blob` | `Vec<u8>` |
+| ActiveRecord model | Auto-generated struct |
+
+## Rake Tasks
+
+```bash
+# Build the Rust binary
+rake rust_on_background:build
+
+# Start all workers
+rake rust_on_background:start
+
+# Start specific queue
+rake rust_on_background:start[emails]
+
+# Stop all workers
+rake rust_on_background:stop
+
+# Stop specific queue
+rake rust_on_background:stop[emails]
+
+# Restart workers
+rake rust_on_background:restart
+
+# Stop, rebuild, and start - for example when doing a deploy
+rake rust_on_background:rebuild
+
+# Check status
+rake rust_on_background:status
+
+# Start scheduler (run ONE instance per Redis db)
+rake rust_on_background:scheduler:start
+
+# Stop scheduler
+rake rust_on_background:scheduler:stop
+```
+
+## Writing Job Logic
+
+Jobs are in `app/jobs/rust/src/jobs/`. Each job is a Rust module with a `run` function:
+
+```rust
+use serde::Deserialize;
+use crate::worker::JobResult;
+
+#[derive(Debug, Deserialize)]
+struct Args {
+    user_id: i64,
+    message: String,
+}
+
+pub async fn run(args: &serde_json::Value, database_url: &str) -> JobResult {
+    // Parse args
+    let args: Args = match serde_json::from_value(args.clone()) {
+        Ok(a) => a,
+        Err(e) => return JobResult::Failed(format!("Invalid args: {}", e)),
+    };
+
+    // Your logic here
+    tracing::info!("Processing user {}", args.user_id);
+
+    // Return result
+    JobResult::Success
+    // or: JobResult::Retry("temporary failure".to_string())
+    // or: JobResult::Failed("permanent failure".to_string())
+}
+```
+
+### Database access
+
+The `database_url` parameter gives you direct access to your Rails database:
+
+```rust
+use sqlx::mysql::MySqlPool;
+
+pub async fn run(args: &serde_json::Value, database_url: &str) -> JobResult {
+    let pool = MySqlPool::connect(database_url).await?;
+
+    let users: Vec<User> = sqlx::query_as("SELECT * FROM users WHERE active = ?")
+        .bind(true)
+        .fetch_all(&pool)
+        .await?;
+
+    JobResult::Success
+}
+```
+
+### HTTP callbacks to Rails (example)
+
+If you need to notify Rails when a job completes, you can use any HTTP client. Example with `reqwest`:
+
+```rust
+pub async fn run(args: &serde_json::Value, _database_url: &str) -> JobResult {
+    // Do work...
+
+    // Notify Rails
+    reqwest::Client::new()
+        .post("http://localhost:3000/webhooks/job_complete")
+        .json(&serde_json::json!({ "job": "my_job", "status": "done" }))
+        .send()
+        .await?;
+
+    JobResult::Success
+}
+```
+
+## Production Deployment
+
+1. Create `app/jobs/rust/config.production.toml` with production database/Redis URLs
+2. `rake rust_on_background:rebuild` (stops workers, builds, starts workers)
+3. `rake rust_on_background:scheduler:start`
+
+Workers run as background processes with PID files in `tmp/pids/`.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/lib/generators/install/install_generator.rb

@@ -0,0 +1,174 @@
+require "rails/generators"
+require "yaml"
+require "erb"
+
+module RustOnBackground
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a basic structure inside of your project"
+
+      def create_rust_jobs_dir
+        empty_directory "app/jobs/rust"
+        empty_directory "app/jobs/rust/src"
+        empty_directory "app/jobs/rust/src/jobs"
+      end
+
+      def copy_cargo_toml
+        @db_adapter = detect_database_adapter
+        @db_feature = database_feature_for(@db_adapter)
+        template "Cargo.toml.erb", "app/jobs/rust/Cargo.toml"
+      end
+
+      def copy_rust_source_files
+        copy_file "main.rs", "app/jobs/rust/src/main.rs"
+        copy_file "worker.rs", "app/jobs/rust/src/worker.rs"
+        copy_file "scheduler.rs", "app/jobs/rust/src/scheduler.rs"
+        copy_file "jobs/mod.rs", "app/jobs/rust/src/jobs/mod.rs"
+      end
+
+      def create_config_file
+        @database_url = build_database_url
+        template "config.toml.erb", "app/jobs/rust/config.#{Rails.env}.toml"
+      end
+
+      def create_rake_tasks
+        copy_file "rust_on_background.rake", "lib/tasks/rust_on_background.rake"
+      end
+
+      def update_gitignore
+        gitignore_path = Rails.root.join(".gitignore")
+        return unless File.exist?(gitignore_path)
+
+        content = File.read(gitignore_path)
+        return if content.include?("rust_on_background")
+
+        append_to_file ".gitignore", <<~GITIGNORE
+
+          # rust_on_background
+          /app/jobs/rust/target
+          /app/jobs/rust/Cargo.lock
+        GITIGNORE
+
+        say "Updated .gitignore with rust_on_background /app/jobs/rust/target and /app/jobs/rust/Cargo.lock", :green
+      end
+
+      def show_post_install_message
+        say ""
+        say "Rust jobs created successfully!", :green
+        say ""
+        say "Configuration:"
+        say "  Database: Using config/database.yml (#{detect_database_adapter})"
+        say "  Config: app/jobs/rust/config.#{Rails.env}.toml"
+        say ""
+        say "Next steps:"
+        say "  1. Review app/jobs/rust/config.#{Rails.env}.toml"
+        say "  2. Generate a file for some job, example: rails generate rust_on_background:job import_big_xlsx filepath:string"
+        say "  3. Write the logic in the job file you created somewhere at: app/jobs/rust/src/jobs/import_big_xlsx.rs"
+        say "  4. Call it from somewhere in your app RustOnBackground.perform('import_big_xlsx', filepath: '/path/to/file.xlsx')"
+        say "  5. Compile: rake rust_on_background:build"
+        say "  6. Start the background jobs: rake rust_on_background:start"
+        say ""
+        say "All rake tasks available:"
+        say "  rake rust_on_background:build"
+        say "  rake rust_on_background:start                # start all queues"
+        say "  rake rust_on_background:start[queue_name]    # start specific queue"
+        say "  rake rust_on_background:stop                 # stop all queues"
+        say "  rake rust_on_background:stop[queue_name]     # stop specific queue"
+        say "  rake rust_on_background:restart"
+        say "  rake rust_on_background:rebuild              # stop, build, start"
+        say "  rake rust_on_background:status"
+        say "  rake rust_on_background:scheduler:start      # start scheduler (one per Redis)"
+        say "  rake rust_on_background:scheduler:stop       # stop scheduler"
+        say ""
+        say "Environment-specific configs:"
+        say "  config.development.toml, config.production.toml, config.test.toml"
+        say ""
+      end
+
+      private
+
+      def detect_database_adapter
+        config = database_config
+        config["adapter"] || config[:adapter] || "mysql2"
+      end
+
+      def database_config
+        db_config_path = Rails.root.join("config", "database.yml")
+        yaml_content = ERB.new(File.read(db_config_path)).result
+
+        config = if YAML.method(:safe_load).parameters.any? { |type, name| name == :aliases }
+          YAML.safe_load(yaml_content, aliases: true, permitted_classes: [Symbol])
+        else
+          YAML.safe_load(yaml_content, [Symbol], [], true)
+        end
+
+        env = Rails.env || "development"
+        config[env] || config["default"] || {}
+      end
+
+      def build_database_url
+        config = database_config
+
+        # Use url key if present
+        return config["url"] || config[:url] if config["url"] || config[:url]
+
+        url_adapter = database_feature_for(detect_database_adapter)
+        database = config["database"] || config[:database]
+        raise RustOnBackground::Error, "Missing database name" unless database
+
+        case url_adapter
+        when "sqlite"
+          "sqlite://#{database}"
+        when "mysql"
+          build_mysql_url(config, database)
+        when "postgres"
+          build_postgres_url(config, database)
+        else
+          raise RustOnBackground::Error, "Unsupported database adapter: #{url_adapter}"
+        end
+      end
+
+      def build_mysql_url(config, database)
+        socket = config["socket"] || config[:socket]
+        host = config["host"] || config[:host] || (socket ? "localhost" : nil)
+        raise RustOnBackground::Error, "Missing database host (and no socket configured)" unless host
+
+        username = config["username"] || config[:username] || "root"
+        password = config["password"] || config[:password]
+        port = config["port"] || config[:port]
+
+        auth = password ? "#{username}:#{password}" : username
+        port_str = port ? ":#{port}" : ""
+        socket_str = socket ? "?socket=#{socket}" : ""
+
+        "mysql://#{auth}@#{host}#{port_str}/#{database}#{socket_str}"
+      end
+
+      def build_postgres_url(config, database)
+        host = config["host"] || config[:host] || "localhost"
+        username = config["username"] || config[:username] || config["user"] || config[:user] || "postgres"
+        password = config["password"] || config[:password]
+        port = config["port"] || config[:port] || 5432
+
+        auth = password ? "#{username}:#{password}" : username
+
+        "postgres://#{auth}@#{host}:#{port}/#{database}"
+      end
+
+      def database_feature_for(adapter)
+        case adapter
+        when "mysql2", "mysql", "trilogy"
+          "mysql"
+        when "postgresql", "postgres", "postgis"
+          "postgres"
+        when "sqlite3", "sqlite"
+          "sqlite"
+        else
+          "mysql"
+        end
+      end
+    end
+  end
+end

data/lib/generators/install/templates/Cargo.toml.erb

@@ -0,0 +1,20 @@
+[package]
+name = "rust_on_background"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+# Core dependencies
+tokio = { version = "1", features = ["full"] }
+redis = { version = "0.25", features = ["tokio-comp"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+toml = "0.8"
+sqlx = { version = "0.7", features = ["runtime-tokio", "<%= @db_feature %>"] }
+thiserror = "1"
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+clap = { version = "4", features = ["derive"] }
+
+# Custom dependencies below:
+# example: calamine = "0.24"

data/lib/generators/install/templates/config.toml.erb

@@ -0,0 +1,40 @@
+# !!! Remember to create config.production.toml for production !!!
+
+# Database connection (used by jobs that need DB access)
+# Examples:
+#   url = "mysql://user:pass@127.0.0.1/myapp"
+#   url = "postgres://user:pass@127.0.0.1:5432/myapp"
+#   url = "sqlite://db/production.sqlite3"
+[database]
+url = "<%= @database_url %>"
+
+# Redis connection (job queue)
+# Examples:
+#   url = "redis://127.0.0.1:6379"
+#   url = "redis://:password@127.0.0.1:6379/0"
+[redis]
+url = "<%= @redis_url || "redis://127.0.0.1:6379" %>"
+
+# Logging configuration
+# path: relative to Rails root, or absolute path starting with /
+# Leave empty to disable logging: path = ""
+[logging]
+path = "log/<%= Rails.env %>.log"
+
+# Queue definitions
+# name: queue name (matches RustOnBackground.perform(..., queue: "name"))
+# workers: number of worker threads for this queue
+[[queues]]
+name = "default"
+workers = 4
+
+# [[queues]]
+# name = "emails"
+# workers = 2
+
+# Scheduler configuration
+# The scheduler moves jobs from the schedule to their target queues when due
+# Run only ONE scheduler instance per Redis database
+# [scheduler]
+# poll_interval_ms = 1000
+# batch_size = 100

data/lib/generators/install/templates/jobs/mod.rs

@@ -0,0 +1,20 @@
+// This file is like a Rails controller for background jobs
+// This file routes incoming jobs to their handlers.
+//
+// When you run "rails g rust_on_background:job my_job", it automatically:
+//   1. Creates a new job file: jobs/my_job.rs
+//   2. Adds "pub mod my_job;" below
+//   3. Adds a match case for this job in the dispatch function
+//      Check readMe for more please.
+
+use crate::worker::{Job, JobResult};
+
+#[allow(unused_variables)]
+pub async fn dispatch(job: &Job, database_url: &str) -> JobResult {
+    match job.job.as_str() {
+        unknown => {
+            tracing::warn!("Unknown job type: {}", unknown);
+            JobResult::Failed(format!("Unknown job type: {}", unknown))
+        }
+    }
+}