feat(ruby): Ruby client (pgque gem)

[dlt]

Summary

• Adds clients/ruby/ — a first-party Ruby client (pgque gem) with full parity with the Python client, including the experimental cooperative-consumers API.
• Wires up a ruby-client-tests CI job mirroring python-client-tests (Postgres 18 in Docker, build pgque via transform.sh, install, then bundle exec rake test + gem build smoke).
• Updates the parity matrix in clients/README.md and adds a Ruby section to the top-level README under "Client libraries".

The gem name is pgque (matches the project; same convention as the TypeScript package on npm). Module is Pgque. Required Ruby is >= 3.1. Driver: the pg gem.

Surface

Area	What's in
Lifecycle	Pgque.connect(dsn, autocommit:) — block form auto-closes; Pgque::Client.new(raw_pg_conn) for shared connections. close is idempotent and a no-op for external connections.
Producer	client.send(queue, payload, type:) accepts Hash/Array/String/nil/Pgque::Event; picks 2-arg vs. 3-arg pgque.send SQL based on type. client.send_batch(queue, type, payloads) returns IDs in input order.
Consumer primitives	client.receive(queue, consumer, max_messages=100) → [Pgque::Message]; client.ack(batch_id) → rowcount (1 ok, 0 stale); client.nack(batch_id, msg, retry_after:, reason:); client.force_next_tick(queue).
Errors	Pgque::Error base; Pgque::ConnectionError / QueueNotFound / BatchNotFound / ConsumerNotFound. SQL errors are wrapped by message-text matching, mirroring the Python wrapper.
Pgque::Consumer	Block-based handler registration (`consumer.on("type") {
Cooperative consumers	subscribe_subconsumer, unsubscribe_subconsumer(batch_handling:), receive_coop(max_messages:, dead_interval:), touch_subconsumer. Constructor validates dead_interval requires subconsumer. Marked experimental in source comments and READMEs.

Tests

59 runs / 146 assertions, all green locally against Postgres 18 with pgque.sql installed.

```
clients/ruby/test/
├── test_connect.rb # 6 tests (ports test_connect.py)
├── test_send.rb # 13 tests (test_send.py)
├── test_receive.rb # 6 tests (test_receive.py)
├── test_nack.rb # 3 tests (test_nack.py)
├── test_smoke.rb # 1 test (test_smoke.py)
├── test_consumer.rb # 19 tests (test_consumer.py — 4 unit + 15 integration)
├── test_consumer_listen_stop.rb # 2 tests (test_consumer_listen_stop.py)
├── test_coop.rb # 9 tests (test_coop.py)
├── test_concurrency.rb # 1 test (test_concurrency.py)
└── test_transaction_visibility.rb # 2 tests (test_transaction_visibility.py)
```

Tests run red/green TDD against a real Postgres (no SQL mocking), gated on PGQUE_TEST_DSN. Unit-style cases that don't need a real DB use a small FakeConn in-class to capture the SQL form, and Pgque::Client.stub :new, ... to assert the consumer's poll loop forwards max_messages correctly.

Test plan

• Local: `cd clients/ruby && bundle install && PGQUE_TEST_DSN=… bundle exec rake test` — 59 passed.
• CI: the new ruby-client-tests job needs to go green on this PR.
• `gem build clients/ruby/pgque.gemspec` smoke (also covered in CI).
• Manual review of the parity matrix update in clients/README.md and the Ruby snippet in the top-level README.

Out of scope (explicit follow-ups)

• Roadmap row toggle for "Ruby library" — happy to flip on request.

Commit history

18 commits on the branch, organised TDD-style:

• 1 scaffold + first connect test
• 5 incremental connect tests (one per test, red→green)
• 7 incremental send tests (same pattern)
• 1 batched commit each for: receive/ack/nack/Message/force_next_tick + remaining test_send + test_receive/smoke/nack; full Consumer + LISTEN/NOTIFY tests; cooperative consumers; concurrency + tx-visibility regressions; CI; docs

🤖 Generated with Claude Code

[NikolayS]

REV Code Review Report

• PR: NikolayS/pgque#234 — Ruby client (pgque gem)
• Reviewed head: 9727982
• Scope: Ruby client, docs, tests, packaging, release workflow
• CI: no checks reported on feat/ruby-client

BLOCKING ISSUES (4)

HIGH .github/workflows/release-ruby.yml:102-107, clients/ruby/Rakefile:1-11 — RubyGems publish job calls missing rake release

rubygems/release-gem@v1 runs Bundler's release path (bundle exec rake release), but clients/ruby/Rakefile only defines test and default.

Evidence from review:

rake aborted!
Don't know how to build task 'release'

Fix: add Bundler gem tasks:

require "bundler/gem_tasks"

or replace rubygems/release-gem with an explicit OIDC-compatible publish path that does not require rake release.

---

HIGH clients/ruby/lib/pgque/consumer.rb:67-74, clients/ruby/lib/pgque/consumer.rb:223-224 — signal trap calls mutex-backed setter

The SIGTERM/SIGINT handler calls self.running = false; that setter enters Mutex#synchronize. Ruby signal trap context cannot safely call mutex synchronization and can raise:

ThreadError: can't be called from trap context

Fix: keep the trap async-signal-safe for Ruby: flip a simple instance variable directly (@running = false) or use a wakeup mechanism handled outside the trap. Do not call Logger, Mutex#synchronize, or other blocking code from Signal.trap.

---

HIGH .github/workflows/release-ruby.yml:81-83 — publish job lacks contents: write if using Bundler release

The workflow grants:

permissions:
  contents: read
  id-token: write

Bundler's rake release pushes a git release tag, so this path requires contents: write per the action/Bundler release model.

Fix: either grant:

permissions:
  contents: write
  id-token: write

or avoid rake release/tag pushing entirely and publish the built gem explicitly.

---

MEDIUM clients/ruby/lib/pgque/consumer.rb:61-100 — Consumer#start leaves running? true after startup/runtime failures

start sets self.running = true, but the outer ensure only restores signal handlers and logs. If PG.connect, LISTEN, poll_once, or SQL execution raises, the consumer exits while running? can remain true.

Fix: set running false in the outer ensure before logging stopped, while still avoiding the mutex-backed setter from signal trap context.

NON-BLOCKING / HARDENING (3)

MEDIUM .github/workflows/release-ruby.yml:88-103 — release job uses mutable action tags while holding RubyGems OIDC publish power

The publish job grants id-token: write, then uses mutable tags:

• actions/checkout@v4
• ruby/setup-ruby@v1
• rubygems/release-gem@v1

The protected rubygems environment helps, but after approval a compromised/moved action tag can mint the trusted-publishing token and publish a malicious gem.

Suggestion: pin release-job actions to full commit SHAs, especially rubygems/release-gem, and manage updates via Dependabot/Renovate.

---

MEDIUM clients/ruby/README.md:8-36, README.md:410-431 — Ruby quickstart is not self-complete

Repo guidance expects install/quickstart docs to include install command, ticker setup or explicit skip path, and role grants. Ruby README has install + grants, but no ticker setup/skip guidance; the root Ruby snippet creates a consumer without showing queue/consumer registration or ticker requirements.

Suggestion: add one short runnable setup path covering schema install, queue/consumer registration or pgque.subscribe, grants, and either pg_cron ticker setup or an explicit manual ticker note.

---

LOW README.md:336 — root README uses non-Ruby prerelease spelling for Ruby

Root README says all clients are published at v0.2.0-rc.1, but RubyGems version is 0.2.0.rc.1; Ruby release docs explicitly warn against hyphenated prerelease strings.

Suggestion: call out Ruby separately (0.2.0.rc.1) or avoid one shared version literal for all ecosystems.

NOTES

• The latest rename from Consumer#set_running to private running= is Ruby-valid; the problem is not the setter syntax, it's calling the mutex-backed setter from the signal trap.
• Ruby client SQL usage looked sane in reviewed paths: exec_params and identifier escaping are used where it matters.
• Local review evidence included Ruby syntax checks, gem build/temp install, and reproduced rake release failure. Full Ruby test suite was not run in this environment because bundle is not installed.

---

REV-assisted review (fallback multi-agent review; Claude Code REV was blocked locally by API key auth).