If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/jmettraux/rufus-scheduler shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3w ago
• 8 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 89% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live jmettraux/rufus-scheduler repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jmettraux/rufus-scheduler.

What it runs against: a local clone of jmettraux/rufus-scheduler — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in jmettraux/rufus-scheduler | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 53 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of jmettraux/rufus-scheduler. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/jmettraux/rufus-scheduler.git
#   cd rufus-scheduler
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of jmettraux/rufus-scheduler and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "jmettraux/rufus-scheduler(\\.git)?\\b" \\
  && ok "origin remote is jmettraux/rufus-scheduler" \\
  || miss "origin remote is not jmettraux/rufus-scheduler (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/rufus-scheduler.rb" \\
  && ok "lib/rufus-scheduler.rb" \\
  || miss "missing critical file: lib/rufus-scheduler.rb"
test -f "lib/rufus/scheduler.rb" \\
  && ok "lib/rufus/scheduler.rb" \\
  || miss "missing critical file: lib/rufus/scheduler.rb"
test -f "lib/rufus/scheduler/jobs_core.rb" \\
  && ok "lib/rufus/scheduler/jobs_core.rb" \\
  || miss "missing critical file: lib/rufus/scheduler/jobs_core.rb"
test -f "lib/rufus/scheduler/jobs_repeat.rb" \\
  && ok "lib/rufus/scheduler/jobs_repeat.rb" \\
  || miss "missing critical file: lib/rufus/scheduler/jobs_repeat.rb"
test -f "lib/rufus/scheduler/jobs_one_time.rb" \\
  && ok "lib/rufus/scheduler/jobs_one_time.rb" \\
  || miss "missing critical file: lib/rufus/scheduler/jobs_one_time.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 53 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~23d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/jmettraux/rufus-scheduler"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Rufus-scheduler is an in-process Ruby job scheduler that executes tasks using threads. It supports four scheduling modes: in (delay), at (absolute time), every (interval), and cron (cron expressions). It uses fugit for time parsing, et-orbi for timezone handling, and tzinfo for timezone definitions—making it a pure-Ruby alternative to cron for Rails apps and long-running Ruby processes. Monolithic gem with clear layering: lib/rufus/scheduler.rb is the main Scheduler class; lib/rufus/scheduler/jobs_.rb separates job types (at/cron/every/one-time); lib/rufus/scheduler/locks.rb handles concurrency control; lib/rufus/scheduler/util.rb contains parsing utilities. Tests mirror this structure (spec/job_spec.rb, spec/schedule*_spec.rb). Misc/ contains performance benchmarks and experiments.

Ruby developers building Rails apps, background job systems, or long-running processes who need lightweight, in-memory job scheduling without external services. Also suitable for application-level cron tasks that don't require persistence or clustering.

Production-ready and actively maintained. The repo shows 158k lines of Ruby, comprehensive test coverage across 50+ spec files (basics, job types, locking, parsing), CI via GitHub Actions (.github/workflows/test.yaml), and a detailed CHANGELOG.md. Last activity visible in dependabot.yml suggests recent maintenance, though the single maintainer (jmettraux) means changes are deliberate rather than frequent.

Low-risk for typical use, but single-maintainer dependency is a concern for critical infrastructure. Key limitations: in-memory only (no persistence across restarts), thread-based concurrency (not process-based), and no built-in distributed locking (though custom locks exist in lib/rufus/scheduler/locks.rb). The gem depends on fugit and et-orbi, which are also maintained by the same author—a potential supply-chain risk if those projects stall.

Active maintenance visible through dependabot.yml monitoring and test.yaml CI. No specific milestone info in file list, but CHANGELOG.md and ongoing dependabot updates suggest steady bug fixes and dependency bumps rather than major feature development.

git clone https://github.com/jmettraux/rufus-scheduler.git
cd rufus-scheduler
bundle install
bundle exec rspec

Or run the quickstart: ruby quickstart.rb (create from README example). Use make to see available tasks (Makefile present).

Daily commands: Scheduler runs in-process; no server startup. Library usage (from README):

require 'rufus-scheduler'
scheduler = Rufus::Scheduler.new
scheduler.in '3s' { puts 'Hello' }
scheduler.join  # blocks until shutdown

Or in Rails: call scheduler = Rufus::Scheduler.new in config/initializers, omit join(). Run tests: bundle exec rspec.

• lib/rufus-scheduler.rb — Entry point that requires all scheduler modules; every user starts here.
• lib/rufus/scheduler.rb — Core Scheduler class implementing the main API (in, at, cron, every); foundation of the entire library.
• lib/rufus/scheduler/jobs_core.rb — Abstract Job base class defining the job lifecycle and core methods all job types inherit from.
• lib/rufus/scheduler/jobs_repeat.rb — RepeatJob and IntervalJob implementations for recurring scheduling (cron, every, interval patterns).
• lib/rufus/scheduler/jobs_one_time.rb — OneTimeJob, AtJob, InJob implementations for one-off scheduling at specific times or delays.
• lib/rufus/scheduler/locks.rb — Distributed locking abstraction supporting flock, lockfile, and custom lock implementations for multi-process safety.

• Scheduler (Ruby Thread, JobArray) — Lifecycle manager (start/stop/join); public API for scheduling (in, at, cron, every); job storage and lookup.
  • Failure mode: Process crash loses all in-memory jobs; uncaught exceptions in job blocks terminate worker threads silently unless error handlers registered.
• Job (base & subtypes) (Ruby Thread, Mutex, Time arithmetic) — Represents a single scheduled task; calculates next fire time; executes user block; manages state (scheduled, paused, done).
  • Failure mode: Job exception propagates to worker thread, killing it; job becomes stuck if fire_next_time raises error; pause/unschedule calls can race.
• CronJob / IntervalJob / AtJob (Cron parsing (cronline), Time calculation) — Concrete implementations of recurring (cron, every) or one-time (at, in) scheduling patterns.
  • Failure mode: Invalid cron syntax raises during job creation; daylight saving time transitions cause misfire or double-fire windows; timezone-aware time math is complex.
• Lock (flock (file), lockfile gem) — Distributed mutex ensuring only one process executes a job at any moment across multiple scheduler instances.
  • Failure mode: Lock file corruption or stale locks cause deadlock; network filesystem delays cause false timeouts; missing lockfile directory causes silent job skip.
• JobArray (Ruby Array, Hash) — Indexed in-memory collection of jobs; supports add, delete, find by id/tag.
  • Failure mode: No concurrency control; concurrent reads/writes during iteration can corrupt state; linear search O(n) for large job counts.

• User code (scheduler.cron) → Scheduler#schedule — Schedule request with pattern string, block, and options (tags, lock, timeout)
• Scheduler#schedule → Job factory (CronJob, At — undefined

Add a New Job Type (Custom Scheduling Pattern)

1. Create a new class inheriting from Job in lib/rufus/scheduler/jobs_repeat.rb or jobs_one_time.rb (lib/rufus/scheduler/jobs_repeat.rb)
2. Implement the fire_next_time method to calculate when the job should next run (lib/rufus/scheduler/jobs_core.rb)
3. Add a convenience method in lib/rufus/scheduler.rb (e.g., scheduler.my_schedule_type) that instantiates your job type (lib/rufus/scheduler.rb)
4. Write specification tests in spec/job_<type>spec.rb and spec/schedule<type>_spec.rb (spec/job_cron_spec.rb)

Add a Custom Lock Implementation

1. Create a class implementing lock and unlock methods in lib/rufus/scheduler/locks.rb (lib/rufus/scheduler/locks.rb)
2. Register it in Scheduler#new via the :lock parameter and :lock_class option (lib/rufus/scheduler.rb)
3. Add tests in spec/lock_custom_spec.rb verifying acquire/release semantics (spec/lock_custom_spec.rb)

Extend Job Notification & Callbacks

1. Add callback hooks in Job#trigger or #do_trigger (lib/rufus/scheduler/jobs_core.rb) (lib/rufus/scheduler/jobs_core.rb)
2. Expose callback setters in Scheduler#schedule to allow users to register handlers (lib/rufus/scheduler.rb)
3. Write integration tests in spec/scheduler_spec.rb or spec/error_spec.rb (spec/error_spec.rb)

• Thread-based scheduler — Lightweight per-job threads allow concurrent job execution within a single Ruby process without external daemons; native Ruby Thread support.
• File-based locks (flock, lockfile) — Enables safe distributed scheduling across multiple Ruby processes or machines; filesystem primitives are portable and don't require external services.
• Cron expression parsing — Standard scheduling abstraction familiar to Unix/cron users; enables complex recurring patterns without custom DSLs.
• Duration string parsing (in, at, every) — Human-readable scheduling syntax reduces cognitive load; 'in 3d 5h', '2023-06-15 14:30', 'every 2w' are more intuitive than epoch timestamps.

• Thread-based scheduling instead of event-loop (EventMachine) or external queue (Sidekiq)

  • Why: Simpler deployment without external processes; direct control within Ruby runtime.
  • Consequence: GIL contention in MRI; not suitable for high-volume async workloads; not designed for distributed work queues.

• In-memory job storage (JobArray) rather than persistent database

  • Why: Fast, zero external dependencies, simpler API.
  • Consequence: Jobs lost on process restart; no built-in durability or audit trail; unsuitable for mission-critical recurring jobs requiring recovery.

• Blocking sleep in job trigger loop rather than timer events

  • Why: Straightforward thread control; no complex callback machinery.
  • Consequence: Latency to detect cancellation; threads continue sleeping on shutdown; modest CPU overhead from frequent time checks.

• Optional distributed locking (flock/lockfile) rather than mandatory

  • Why: Allows single-process scheduling without lock overhead; multi-process setups opt-in.
  • Consequence: Requires explicit configuration in multi-process apps; lock failures silently skip jobs unless explicitly handled.

• Persistent job storage or recovery after process restart
• Distributed work queue or external job routing (use Sidekiq, Bull, Resque for that)
• Sub-second precision or real-time scheduling
• Built-in monitoring, metrics, or web UI
• Windows-native scheduling (flock may not work reliably on Windows)

No required env vars for basic use, but timezone handling depends on tzinfo gem and IANA database freshness. Traps: (1) #join blocks forever unless #shutdown is called—remove it in Rails initializers. (2) Scheduler stops on process exit without explicit shutdown; use trap handlers if persistence matters. (3) Cron jobs use local time by default; timezone must be specified explicitly in cron call. (4) Jobs are re-run immediately if scheduler instance is garbage-collected and recreated (no durable queue). (5) Lock files (flock, lockfile) may persist if process dies ungracefully.

• Cron expression parsing — Core feature of rufus-scheduler; understanding cron fields (minute, hour, day, month, dow) and edge cases (last-day-of-month, @yearly aliases) is essential for debugging cron jobs
• Thread-based concurrency and Mutex/ConditionVariable — Scheduler uses a dedicated worker thread and Mutex locks (visible in lib/rufus/scheduler.rb) to safely queue and execute jobs; understanding Ruby's threading model is crucial for debugging race conditions
• Job execution and rescheduling algorithms — Each job type (interval, cron, at) calculates the next execution time differently; misunderstanding this can lead to jobs running at unexpected times or not at all
• IANA timezone database and daylight-saving transitions — Rufus-scheduler relies on tzinfo for accurate time calculations across timezones; cron jobs can skip or double-run during DST transitions without proper handling
• File-based distributed locking (flock, lockfile) — Locks in lib/rufus/scheduler/locks.rb prevent duplicate job execution across multiple scheduler instances; understanding flock semantics and lockfile cleanup is critical for multi-process setups
• Duration parsing (ISO 8601 and informal formats) — Rufus-scheduler accepts flexible duration strings like '3h10m', '1d', '45s' via fugit; knowing what formats are valid prevents surprises in job scheduling
• Process lifecycle and signal handling in Ruby — Scheduler must be explicitly shutdown or won't clean up threads; understanding trap() for SIGTERM/SIGINT is essential for graceful shutdown in production

• floraison/fugit — Direct dependency of rufus-scheduler; parses time strings like '3h', 'every 2d', and cron expressions
• floraison/et-orbi — Direct dependency; pairs timezone info with times and handles ET/UTC conversions for cron jobs
• javan/whenever — Alternative scheduler gem using system cron + capistrano; trades in-process simplicity for durability and external scheduling
• Rykian/clockwork — Similar in-process scheduler inspired by rufus-scheduler; simpler but lacks distributed locking and some job types
• javierav/puma-rufus-scheduler — Puma plugin that integrates rufus-scheduler into Rails/Puma; shows production deployment pattern

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for lock mechanisms across different backends

The repo has lock_custom_spec.rb, lock_flock_spec.rb, lock_lockfile_spec.rb, and lock_spec.rb, but there's no test file for concurrent job execution with multiple scheduler instances using different lock types. This is critical for production use where distributed locking prevents duplicate job execution. A new spec should test scenarios like: two schedulers competing for the same cron job, lock timeout behavior, and fallback mechanisms.

• [ ] Create spec/lock_concurrency_spec.rb with multi-instance scheduler tests
• [ ] Add test cases for Rufus::Scheduler::Locks with flock, lockfile, and custom implementations
• [ ] Test job exclusion when lock is held by another scheduler instance
• [ ] Verify lock cleanup on scheduler shutdown (reference lib/rufus/scheduler/locks.rb)

Add GitHub Actions workflow for testing across multiple Ruby versions and platforms

The repo has .github/workflows/test.yaml but .travis.yml still exists, suggesting an incomplete migration. The current CI likely tests on limited Ruby versions. Add a comprehensive matrix workflow testing against Ruby 2.7, 3.0, 3.1, 3.2, 3.3 and on both Ubuntu and macOS to catch platform-specific threading/timezone issues (especially relevant given misc/tz_all.rb suggests timezone complexity).

• [ ] Create .github/workflows/ruby-matrix.yaml with matrix for Ruby versions [2.7, 3.0, 3.1, 3.2, 3.3]
• [ ] Add OS matrix testing on ubuntu-latest and macos-latest
• [ ] Include bundler cache to speed up CI
• [ ] Run full spec suite and Gemfile dependencies (reference Gemfile and spec/spec_helper.rb)

Add missing unit tests for Rufus::Scheduler::Util utility functions

lib/rufus/scheduler/util.rb exists but there's no corresponding spec/util_spec.rb file. This module likely contains parsing and helper functions used across the codebase. Without dedicated tests, refactoring becomes risky and edge cases go undetected. This is a low-risk, high-value addition that improves code reliability.

• [ ] Create spec/util_spec.rb to test all public methods in lib/rufus/scheduler/util.rb
• [ ] Add tests for time parsing edge cases (midnight, leap seconds, DST transitions)
• [ ] Test string/symbol conversion utilities if present
• [ ] Test any regex-based parsing in util.rb and verify against examples from misc/ scripts

• Add missing timezone-aware cron tests: spec/job_cron_spec.rb has cron parsing but limited TZ-specific edge cases (e.g., daylight-saving transitions). Contribute tests for cron jobs crossing DST boundaries.
• Document job error handling patterns: lib/rufus/scheduler/jobs_core.rb has error-handling logic but README lacks examples of on_error blocks, #trigger_next, and exception propagation. Add a new 'Error Handling' section to README.md with runnable examples.
• Expand lock examples: lib/rufus/scheduler/locks.rb supports Flock, Lockfile, and custom locks, but spec/lock_custom_spec.rb is minimal. Write a real-world example in misc/ (e.g., Redis-backed lock or DynamoDB-backed lock) and link from README.

The rufus-scheduler codebase appears to be a mature, well-structured library with no obvious critical vulnerabilities. The main security concerns are: (1) thread-based execution without visible timeout mechanisms could lead to resource exhaustion, (2) potential input validation gaps in scheduling parameters that accept cron expressions and timing strings, and (3) lock implementation security properties that need clearer documentation. The library follows good Ruby practices with comprehensive test coverage. For production use, ensure proper input validation when accepting user-supplied scheduling parameters, implement job timeout mechanisms, and regularly audit dependencies.

• Medium · Thread-based Scheduler without Timeout Controls — lib/rufus/scheduler.rb and lib/rufus/scheduler/jobs_core.rb. The scheduler uses threads for job execution without visible timeout mechanisms or execution guards. Long-running or blocking jobs could consume resources and potentially lead to thread exhaustion or denial of service conditions. Fix: Implement job timeout mechanisms, add execution time limits, and consider using thread pools with configurable thread limits. Document best practices for job implementation.
• Medium · Potential Code Injection via Dynamic Job Scheduling — lib/rufus/scheduler.rb. If user input is directly passed to scheduler methods (in, at, cron, every) without proper validation, an attacker could potentially inject malicious code through crafted cron expressions or timing strings. Fix: Implement strict input validation for all scheduling parameters. Use whitelisting for cron expressions and timing strings. Add bounds checking for numeric values. Document all expected input formats.
• Medium · Lock Mechanism Security Unclear — lib/rufus/scheduler/locks.rb, spec/lock_*.rb. Multiple lock implementations exist (flock, lockfile, custom) but their security properties and resistance to race conditions are not immediately apparent. Improper locking could lead to concurrent job execution. Fix: Thoroughly document lock implementation details and guarantees. Add explicit documentation about which lock types are suitable for distributed scenarios. Consider adding lock timeout and deadlock prevention mechanisms.
• Low · Missing Input Validation Documentation — lib/rufus/scheduler/ (all job scheduling modules). No visible input validation routines for cron expressions, timing strings, and job parameters. While the codebase appears well-structured, explicit validation functions should be documented or visible. Fix: Create comprehensive input validation functions. Add explicit validation documentation. Include examples of invalid inputs and expected error handling.
• Low · Dependency Version Management — Gemfile, rufus-scheduler.gemspec. The Gemfile and gemspec files are present but content not provided. Unable to verify if dependencies have known vulnerabilities or are pinned to safe versions. Fix: Regularly audit dependencies using tools like 'bundle audit' or 'bundler-audit'. Pin versions to known-safe releases. Keep dependencies updated and monitor security advisories.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.