Add fully functional Ruby client compatible with Go client

Here, try to do a full port of River to Ruby using a similar technique
to Rust through repeated refinement iterations.

I also had it try to go through each of River's features sections in the
docs and make sure we have equivalent Ruby functionality.

I changed a fair bit through manual inspection of the resulting APIs,
but there's still a reasonable possibility we'll notice more things and
want to make a few additional tweaks before fully committing.

I also have a full Pro implementation locally, but have left it out of
this change set. We'd ship this from a private gem server separately.

Author: brandur

.github/workflows/ci.yaml

@@ -23,7 +23,43 @@ env:
 on:
   - push
 
+permissions:
+  contents: read
+
 jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ env.RUBY_VERSION }}
+
+      - name: Read upstream River revision
+        id: river_revision
+        run: |
+          ruby -rjson -e '
+            revision = JSON.parse(File.read("migration/manifest.json")).fetch("revision")
+            abort "Invalid River revision" unless /\A[0-9a-f]{40}\z/.match?(revision)
+            File.open(ENV.fetch("GITHUB_OUTPUT"), "a") { |file| file.puts("revision=#{revision}") }
+          '
+
+      - name: Checkout upstream River
+        uses: actions/checkout@v4
+        with:
+          path: upstream/river
+          persist-credentials: false
+          ref: ${{ steps.river_revision.outputs.revision }}
+          repository: riverqueue/river
+
+      - name: Verify migrations
+        run: make verify RIVER_PATH="$GITHUB_WORKSPACE/upstream/river"
+
   gem_build:
     runs-on: ubuntu-latest
     timeout-minutes: 3
@@ -50,6 +86,10 @@ jobs:
         run: gem build riverqueue-sequel.gemspec
         working-directory: ./driver/riverqueue-sequel
 
+      - name: Build gem (riverqueue-rails)
+        run: gem build riverqueue-rails.gemspec
+        working-directory: ./rails/riverqueue-rails
+
   lint:
     runs-on: ubuntu-latest
     timeout-minutes: 3
@@ -68,6 +108,10 @@ jobs:
         run: bundle exec standardrb
         working-directory: .
 
+      - name: Frozen string literal comments
+        run: bundle exec rubocop --config .rubocop-frozen-string-literal.yaml --only Style/FrozenStringLiteralComment
+        working-directory: .
+
       - name: bundle install (riverqueue-activerecord)
         run: bundle install
         working-directory: ./driver/riverqueue-activerecord
@@ -195,3 +239,44 @@ jobs:
       - name: Rspec (riverqueue-sequel)
         run: bundle exec rspec
         working-directory: ./driver/riverqueue-sequel
+
+  rails:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    strategy:
+      matrix:
+        include:
+          - rails: "~> 7.2.0"
+            ruby: "3.2"
+          - rails: "~> 8.0.0"
+            ruby: "3.3"
+          - rails: "~> 8.1.0"
+            ruby: "4.0"
+    env:
+      BUNDLE_FROZEN: "false"
+      RAILS_VERSION: ${{ matrix.rails }}
+      RIVER_REQUIRE_DATABASES: "1"
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_DB: river_test
+          POSTGRES_PASSWORD: postgres
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 2s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - run: bundle install
+        working-directory: ./rails/riverqueue-rails
+      - run: bundle exec rspec
+        working-directory: ./rails/riverqueue-rails
+      - run: bundle exec standardrb
+        working-directory: ./rails/riverqueue-rails

.gitignore

@@ -1,3 +1,5 @@
 .DS_Store
 *.gem
+/benchmarks/
 coverage/
+/pro/

.rubocop-frozen-string-literal.yaml

@@ -0,0 +1,10 @@
+AllCops:
+  NewCops: disable
+  Exclude:
+    - ".ruby-lsp/**/*"
+    - "**/coverage/**/*"
+    - "**/vendor/**/*"
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add a full Ruby client for River with Go-compatible job insertion and execution on PostgreSQL and SQLite through ActiveRecord or Sequel. Includes workers, retries, cancellation, periodic and resumable jobs, job administration, migration and worker CLIs, and testing helpers. Rails and Active Job integration is available through `riverqueue-rails`, with workflows, batches, sequences, concurrency controls, and other advanced features in the separately distributed `riverqueue-pro` gem. [PR #70](https://github.com/riverqueue/riverqueue-ruby/pull/70).
+
 ## [0.11.0] - 2026-09-02
 
 ### Added

Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 gemspec
@@ -9,9 +11,12 @@ end
 
 group :test do
   gem "debug"
+  gem "fugit", "~> 1.13", require: false
+  gem "minitest", require: false
   gem "pg"
   gem "rspec-core"
   gem "rspec-expectations"
+  gem "riverqueue-activerecord", path: "driver/riverqueue-activerecord"
   gem "riverqueue-sequel", path: "driver/riverqueue-sequel"
   gem "simplecov", require: false
   gem "sqlite3"

Gemfile.lock

@@ -2,16 +2,35 @@ PATH
   remote: .
   specs:
     riverqueue (0.11.0)
+      logger (> 0, < 1000)
+      optparse (> 0, < 1000)
+      securerandom (> 0, < 1000)
+      timeout (> 0, < 1000)
+
+PATH
+  remote: driver/riverqueue-activerecord
+  specs:
+    riverqueue-activerecord (0.11.0)
+      activerecord (> 0, < 1000)
+      activesupport (> 0, < 1000)
+      riverqueue (= 0.11.0)
 
 PATH
   remote: driver/riverqueue-sequel
   specs:
     riverqueue-sequel (0.11.0)
+      riverqueue (= 0.11.0)
       sequel (> 0, < 1000)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    activemodel (8.1.3)
+      activesupport (= 8.1.3)
+    activerecord (8.1.3)
+      activemodel (= 8.1.3)
+      activesupport (= 8.1.3)
+      timeout (>= 0.4.0)
     activesupport (8.1.3)
       base64
       bigdecimal
@@ -39,9 +58,14 @@ GEM
     docile (1.4.1)
     drb (2.2.3)
     erb (6.0.4)
+    et-orbi (1.4.2)
+      tzinfo
     ffi (1.17.4-arm64-darwin)
     ffi (1.17.4-x86_64-linux-gnu)
     fileutils (1.8.0)
+    fugit (1.13.0)
+      et-orbi (~> 1.4)
+      raabro (~> 1.4)
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
     io-console (0.8.2)
@@ -62,6 +86,7 @@ GEM
       drb (~> 2.0)
       prism (~> 1.5)
     mutex_m (0.3.0)
+    optparse (0.8.1)
     parallel (1.27.0)
     parser (3.3.11.1)
       ast (~> 2.4.1)
@@ -75,6 +100,7 @@ GEM
     psych (5.3.1)
       date
       stringio
+    raabro (1.5.0)
     racc (1.8.1)
     rainbow (3.1.1)
     rb-fsevent (0.11.2)
@@ -159,6 +185,7 @@ GEM
     strscan (3.1.7)
     terminal-table (4.0.0)
       unicode-display_width (>= 1.1.1, < 4)
+    timeout (0.6.1)
     tsort (0.2.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
@@ -173,8 +200,11 @@ PLATFORMS
 
 DEPENDENCIES
   debug
+  fugit (~> 1.13)
+  minitest
   pg
   riverqueue!
+  riverqueue-activerecord!
   riverqueue-sequel!
   rspec-core
   rspec-expectations
@@ -184,4 +214,4 @@ DEPENDENCIES
   steep
 
 BUNDLED WITH
-   2.6.7
+  4.0.9

Makefile

@@ -1,5 +1,7 @@
 .DEFAULT_GOAL := help
 
+RIVER_PATH ?= ../river
+
 # Looks at comments using ## on targets and uses them to produce a help output.
 .PHONY: help
 help: ALIGN=14
@@ -11,9 +13,11 @@ install: ## Run `bundle install` on gem and all subgems
 	bundle install
 	cd driver/riverqueue-activerecord && bundle install
 	cd driver/riverqueue-sequel && bundle install
+	cd rails/riverqueue-rails && bundle install
+	@if [ -d pro/riverqueue-pro ]; then cd pro/riverqueue-pro && bundle install; fi
 
 .PHONY: lint
-lint: standardrb ## Run linter (standardrb) on gem and all subgems
+lint: standardrb frozen-string-literals ## Run linters on gem and all subgems
 
 .PHONY: rspec
 rspec: spec
@@ -23,12 +27,20 @@ spec:
 	bundle exec rspec
 	cd driver/riverqueue-activerecord && bundle exec rspec
 	cd driver/riverqueue-sequel && bundle exec rspec
+	cd rails/riverqueue-rails && bundle exec rspec
+	@if [ -d pro/riverqueue-pro ]; then cd pro/riverqueue-pro && bundle exec rspec; fi
 
 .PHONY: standardrb
 standardrb:
 	bundle exec standardrb --fix
 	cd driver/riverqueue-activerecord && bundle exec standardrb --fix
 	cd driver/riverqueue-sequel && bundle exec standardrb --fix
+	cd rails/riverqueue-rails && bundle exec standardrb --fix
+	@if [ -d pro/riverqueue-pro ]; then cd pro/riverqueue-pro && bundle exec standardrb --fix; fi
+
+.PHONY: frozen-string-literals
+frozen-string-literals:
+	bundle exec rubocop --config .rubocop-frozen-string-literal.yaml --only Style/FrozenStringLiteralComment
 
 .PHONY: steep
 steep:
@@ -45,3 +57,9 @@ update: ## Run `bundle update` on gem and all subgems
 	bundle update
 	cd driver/riverqueue-activerecord && bundle update
 	cd driver/riverqueue-sequel && bundle update
+	cd rails/riverqueue-rails && bundle update
+	@if [ -d pro/riverqueue-pro ]; then cd pro/riverqueue-pro && bundle update; fi
+
+.PHONY: verify
+verify: ## Verify bundled migrations against RIVER_PATH (default ../river)
+	ruby scripts/sync_migrations.rb --check "$(RIVER_PATH)"

Steepfile

@@ -1,11 +1,18 @@
+# frozen_string_literal: true
+
 D = Steep::Diagnostic
 
 target :lib do
   check "lib"
 
   library "digest"
   library "json"
+  library "logger"
+  library "optparse"
+  library "securerandom"
+  library "socket"
   library "time"
+  library "timeout"
 
   signature "sig"