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,92 @@ env:
 on:
   - push
 
+permissions:
+  contents: read
+
 jobs:
+  conformance:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        driver: [sequel, activerecord]
+    env:
+      RIVER_CONFORMANCE_DATABASE_URL: postgres://postgres:postgres@127.0.0.1:5432/river_conformance?sslmode=disable
+      RIVER_CONFORMANCE_DRIVER: ${{ matrix.driver }}
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_DB: river_conformance
+          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: ${{ env.RUBY_VERSION }}
+          bundler-cache: true
+      - name: Read conformance reference revision
+        id: reference
+        run: |
+          ruby -rjson -e '
+            revision = JSON.parse(File.read("conformance/reference.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}") }
+          '
+      - uses: actions/checkout@v4
+        with:
+          repository: riverqueue/river
+          ref: ${{ steps.reference.outputs.revision }}
+          path: upstream/river
+          persist-credentials: false
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: upstream/river/go.mod
+          cache-dependency-path: upstream/river/**/go.sum
+      - name: Required insert-only conformance
+        run: make test/conformance/insert-only RIVER_PATH="$GITHUB_WORKSPACE/upstream/river"
+
+  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 +135,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 +157,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 +288,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

.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, SQLite, and YugabyteDB through ActiveRecord or Sequel. Includes workers, retries, cancellation, periodic and resumable jobs, job-persisted logging, 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,18 @@
 .DEFAULT_GOAL := help
 
+RIVER_PATH ?= ../river
+RIVERQUEUE_PRO_PATH ?= ../riverqueue-ruby-pro
+
+.PHONY: test/conformance/insert-only
+test/conformance/insert-only: ## Run the pinned Go insert-only contract against Ruby
+	RIVER_PATH="$(RIVER_PATH)" bundle exec ruby conformance/run.rb
+
+.PHONY: test/yugabyte
+test/yugabyte: ## Run both SQL adapters against a real Yugabyte database
+	@test -n "$(YUGABYTE_DATABASE_URL)" || { echo "Set YUGABYTE_DATABASE_URL to a disposable test database"; exit 1; }
+	cd driver/riverqueue-activerecord && TEST_DATABASE_URL="$(YUGABYTE_DATABASE_URL)" RIVER_YUGABYTE_TEST=1 RIVER_REQUIRE_DATABASES=1 RIVERQUEUE_ROOT_TEST_SUITE=1 bundle exec rspec spec/yugabyte_spec.rb
+	cd driver/riverqueue-sequel && TEST_DATABASE_URL="$(YUGABYTE_DATABASE_URL)" RIVER_YUGABYTE_TEST=1 RIVER_REQUIRE_DATABASES=1 RIVERQUEUE_ROOT_TEST_SUITE=1 bundle exec rspec spec/yugabyte_spec.rb
+
 # Looks at comments using ## on targets and uses them to produce a help output.
 .PHONY: help
 help: ALIGN=14
@@ -11,9 +24,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 [ -f "$(RIVERQUEUE_PRO_PATH)/riverqueue-pro.gemspec" ]; then $(MAKE) -C "$(RIVERQUEUE_PRO_PATH)" 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 +38,21 @@ 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 driver/riverqueue-redis ]; then cd driver/riverqueue-redis && bundle exec rspec; fi
+	@if [ -f "$(RIVERQUEUE_PRO_PATH)/riverqueue-pro.gemspec" ]; then $(MAKE) -C "$(RIVERQUEUE_PRO_PATH)" test; 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 [ -f "$(RIVERQUEUE_PRO_PATH)/riverqueue-pro.gemspec" ]; then $(MAKE) -C "$(RIVERQUEUE_PRO_PATH)" standardrb; 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 +69,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 [ -f "$(RIVERQUEUE_PRO_PATH)/riverqueue-pro.gemspec" ]; then $(MAKE) -C "$(RIVERQUEUE_PRO_PATH)" 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"