pgmq-ruby 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6b6b3dcddd3785167a0fd8482fb0900f0d51c9c5cf68ddd23b60e84eb306012
-  data.tar.gz: 94604bf7c55a2bd62a63486278641c247b0a9d9cf3b50379d30ee0b7c8c840f4
+  metadata.gz: 5648229b33f490f7228d7f9b106fb40939632c6effff094d028d9f7dd5fc045a
+  data.tar.gz: 7a7d0ae6dd7ee59cf329093f4772e8cd8706e25be0e627defca60f3983e96084
 SHA512:
-  metadata.gz: 3ea99c27e92f96f137c9552985830949cdff6538409646ddf6b10e587c05c2b831c8c083570996ff2c0ffbefd09ae01fa84002e2ca9093f0a27ec6f7387a2b59
-  data.tar.gz: 437713bad4d37ff821487493097c6229b8c2069b260b74e587b3452f74508392b1dba7cf37ee3dd91c52143a4c147db373035351a8dc0d86f1d6cd70a4370d4d
+  metadata.gz: 5da9b67730f7c1b58af6be47c2364092988823b2c536e762ca56cc91bd5f27d2d678aef116373c7f0c62fec5037438f30ae0482979c0df3f9414aa3e5f41987a
+  data.tar.gz: 7c892fcc8d30d306670b7dd3fd3a3e3f70f573916b3e6526e0833a59acad85cdd44fcf830fd327ccba6608fe0e30eb072d2adc1bcb287ccc28c388e743cfd19e

data/.github/workflows/ci.yml

@@ -64,7 +64,7 @@ jobs:
         run: rm -f Gemfile.lock
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@ae195bbe749a7cef685ac729197124a48305c1cb # v1.276.0
+        uses: ruby/setup-ruby@90be1154f987f4dc0fe0dd0feedac9e473aa4ba8 # v1.286.0
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
@@ -102,57 +102,77 @@ jobs:
           GITHUB_COVERAGE: ${{ matrix.coverage }}
         run: bundle exec rspec
 
+      - name: Run examples
+        env:
+          PG_HOST: localhost
+          PG_PORT: 5433
+          PG_DATABASE: pgmq_test
+          PG_USER: postgres
+          PG_PASSWORD: postgres
+        run: bundle exec rake examples
+
   yard-lint:
     timeout-minutes: 5
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
+    env:
+      BUNDLE_GEMFILE: Gemfile.lint
     steps:
       - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
-      - name: Remove Gemfile.lock for Ruby 4.0
-        run: rm -f Gemfile.lock
       - name: Set up Ruby
-        uses: ruby/setup-ruby@ae195bbe749a7cef685ac729197124a48305c1cb # v1.276.0
+        uses: ruby/setup-ruby@90be1154f987f4dc0fe0dd0feedac9e473aa4ba8 # v1.286.0
         with:
           ruby-version: '4.0.0'
           bundler-cache: true
       - name: Run yard-lint
         run: bundle exec yard-lint lib/
 
-  coditsu:
+  rubocop:
     timeout-minutes: 5
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
+    env:
+      BUNDLE_GEMFILE: Gemfile.lint
     steps:
       - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
-      - name: Download Coditsu script
-        run: |
-          curl -sSL https://api.coditsu.io/run/ci -o coditsu_script.sh
-          chmod +x coditsu_script.sh
-      - name: Verify Coditsu script checksum
-        run: |
-          EXPECTED_SHA256="0aecc5aa010f53fca264548a41467a2b0a1208d750ce1da3e98a217304cacbbc"
-          ACTUAL_SHA256=$(sha256sum coditsu_script.sh | awk '{ print $1 }')
-          if [ "$ACTUAL_SHA256" != "$EXPECTED_SHA256" ]; then
-            echo "::error::Checksum verification failed. Expected $EXPECTED_SHA256 but got $ACTUAL_SHA256."
-            exit 1
-          fi
-      - name: Run Coditsu
-        run: ./coditsu_script.sh
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@90be1154f987f4dc0fe0dd0feedac9e473aa4ba8 # v1.286.0
+        with:
+          ruby-version: '4.0.0'
+          bundler-cache: true
+      - name: Run rubocop
+        run: bundle exec rubocop
+
+  lostconf:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 0
+      - name: Set up Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+      - name: Run lostconf
+        run: npx lostconf --fail-on-stale
 
   ci-success:
     name: CI Success
     runs-on: ubuntu-latest
     if: always()
     needs:
-      - coditsu
+      - rubocop
       - specs
       - yard-lint
+      - lostconf
     steps:
       - name: Check all jobs passed
         if: |

data/.github/workflows/push.yml

@@ -24,7 +24,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@ae195bbe749a7cef685ac729197124a48305c1cb # v1.276.0
+        uses: ruby/setup-ruby@90be1154f987f4dc0fe0dd0feedac9e473aa4ba8 # v1.286.0
         with:
           bundler-cache: false
 

data/.rspec

@@ -1 +1,2 @@
 --require spec_helper
+--exclude-pattern spec/integration/**/*

data/.rubocop.yml

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+plugins:
+  - rubocop-capybara
+  - rubocop-factory_bot
+  - rubocop-performance
+  - rubocop-rspec
+  - rubocop-rspec_rails
+
+inherit_gem:
+  standard: config/base.yml
+  standard-performance: config/base.yml
+  standard-rspec: config/base.yml
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.2
+  Include:
+    - "**/*.rb"
+    - "**/*.gemspec"
+    - "**/Gemfile"
+    - "**/Rakefile"
+    - Gemfile.lint
+
+# Disabled departments - not a Rails project, no Capybara/FactoryBot
+Capybara:
+  Enabled: false
+
+FactoryBot:
+  Enabled: false
+
+RSpecRails:
+  Enabled: false
+
+# Layout
+Layout/LineLength:
+  Max: 120
+
+Layout/SpaceInsideHashLiteralBraces:
+  EnforcedStyle: space
+
+# RSpec - exclude integration examples (they use ExampleHelper, not RSpec)
+RSpec:
+  Exclude:
+    - spec/integration/**/*
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/IndexedLet:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 20
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/NoExpectationExample:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  Enabled: false

data/.yard-lint.yml

@@ -7,12 +7,10 @@ AllValidators:
   - "--private"
   - "--protected"
   Exclude:
-  - "\\.git"
+  - .git/**/*
   - vendor/**/*
   - node_modules/**/*
   - spec/**/*
-  - test/**/*
-  - benchmark/**/*
   FailOnSeverity: convention
   RequiredCoverage: 100
 

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.5.0 (2026-02-24)
+
+### Breaking Changes
+- **[Breaking]** Remove `detach_archive(queue_name)` method. PGMQ 2.0 no longer requires archive table detachment as archive tables are no longer member objects. The server-side function was already a no-op in PGMQ 2.0+.
+- **[Breaking]** Rename `vt_offset:` parameter to `vt:` in `set_vt`, `set_vt_batch`, and `set_vt_multi` methods. The `vt:` parameter now accepts either an integer offset (seconds from now) or an absolute `Time` object for PGMQ v1.11.0+.
+
+### PGMQ v1.11.0 Features
+- **[Feature]** Add `last_read_at` field to `PGMQ::Message`. Returns the timestamp of the last read operation for the message, or nil if the message has never been read. This enables tracking when messages were last accessed (PGMQ v1.8.1+).
+- **[Feature]** Add Grouped Round-Robin reading for fair message processing:
+  - `read_grouped_rr(queue_name, vt:, qty:)` - Read messages in round-robin order across groups
+  - `read_grouped_rr_with_poll(queue_name, vt:, qty:, max_poll_seconds:, poll_interval_ms:)` - With long-polling
+
+  Messages are grouped by the first key in their JSON payload. This ensures fair processing
+  when multiple entities (users, orders, etc.) have messages in the queue, preventing any
+  single entity from monopolizing workers.
+- **[Feature]** Add Topic Routing support (AMQP-like patterns). New methods in `PGMQ::Client`:
+  - `bind_topic(pattern, queue_name)` - Bind a topic pattern to a queue
+  - `unbind_topic(pattern, queue_name)` - Remove a topic binding
+  - `produce_topic(routing_key, message, headers:, delay:)` - Send message via routing key
+  - `produce_batch_topic(routing_key, messages, headers:, delay:)` - Batch send via routing key
+  - `list_topic_bindings(queue_name:)` - List all topic bindings
+  - `test_routing(routing_key)` - Test which queues a routing key matches
+  - `validate_routing_key(routing_key)` - Validate a routing key
+  - `validate_topic_pattern(pattern)` - Validate a topic pattern
+
+  Topic patterns support wildcards: `*` (single word) and `#` (zero or more words).
+  Requires PGMQ v1.11.0+.
+
+### Testing
+- **[Feature]** Add Fiber Scheduler integration tests demonstrating compatibility with Ruby's Fiber Scheduler API and the `async` gem for concurrent I/O operations.
+
+### Infrastructure
+- **[Fix]** Update docker-compose.yml volume mount for PostgreSQL 18+ compatibility.
+- **[Change]** Replace Coditsu with StandardRB for code linting. This provides faster, more consistent linting using the community Ruby Style Guide.
+
 ## 0.4.0 (2025-12-26)
 
 ### Breaking Changes

data/CLAUDE.md

@@ -0,0 +1,310 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+PGMQ-Ruby is a **low-level Ruby client** for PGMQ (PostgreSQL Message Queue), analogous to how rdkafka-ruby relates to Kafka. It provides direct 1:1 wrappers for PGMQ SQL functions as a thin transport layer.
+
+This is **NOT** a full job processing framework. Framework features (instrumentation, job processing, Rails ActiveJob, retry strategies, monitoring integrations) belong in the planned `pgmq-framework` gem.
+
+**Key Design Principles:**
+- Thin wrapper around PGMQ SQL functions (low-level primitives only)
+- Thread-safe connection pooling (transport layer)
+- PostgreSQL transaction support (database primitive, not framework abstraction)
+- Framework-agnostic (works with Rails, Sinatra, plain Ruby)
+- Minimal dependencies (only `pg` and `connection_pool`)
+- No instrumentation/observability layer (framework concern)
+
+## Development Commands
+
+### Testing
+
+```bash
+# Start PostgreSQL with PGMQ extension (required for tests)
+docker compose up -d
+
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/unit/client_spec.rb
+
+# Run integration tests only
+bundle exec rspec spec/integration
+
+# Run single test by line number
+bundle exec rspec spec/unit/client_spec.rb:42
+```
+
+**Important:** PostgreSQL runs on port **5433** locally (see docker-compose.yml) to avoid conflicts with system PostgreSQL. Tests use this port automatically.
+
+### Code Quality
+
+```bash
+# Run tests
+bundle exec rspec
+```
+
+
+### Interactive Development
+
+```bash
+# Start IRB console with PGMQ loaded
+bundle exec bin/console
+
+# Console automatically connects to test database at localhost:5433
+```
+
+## Architecture
+
+### Core Components
+
+1. **PGMQ::Client** (`lib/pgmq/client.rb`)
+   - Main interface for all PGMQ operations (modular architecture, ~130 lines)
+   - Delegates connection management to PGMQ::Connection
+   - Validates queue names (48 char max, PostgreSQL identifier rules)
+   - Composed of 8 functional modules for separation of concerns:
+     - **Transaction** (`lib/pgmq/transaction.rb`) - PostgreSQL transaction support
+     - **QueueManagement** (`lib/pgmq/client/queue_management.rb`) - Queue lifecycle (create, drop, list)
+     - **Producer** (`lib/pgmq/client/producer.rb`) - Message sending operations
+     - **Consumer** (`lib/pgmq/client/consumer.rb`) - Single-queue reading operations
+     - **MultiQueue** (`lib/pgmq/client/multi_queue.rb`) - Multi-queue operations (UNION ALL)
+     - **MessageLifecycle** (`lib/pgmq/client/message_lifecycle.rb`) - Message state transitions (pop, delete, archive, set_vt)
+     - **Maintenance** (`lib/pgmq/client/maintenance.rb`) - Queue maintenance (purge, notifications)
+     - **Metrics** (`lib/pgmq/client/metrics.rb`) - Monitoring and metrics
+   - Benefits: Each module can be tested independently, easier maintenance, clear separation of concerns
+   - Pattern inspired by Waterdrop's modular client architecture
+
+2. **PGMQ::Connection** (`lib/pgmq/connection.rb`)
+   - Thread-safe connection pooling using `connection_pool` gem
+   - Supports multiple connection strategies:
+     - Connection strings: `postgres://user:pass@host/db`
+     - Hash parameters: `{ host:, port:, dbname:, user:, password: }`
+     - Callables (for Rails): `-> { ActiveRecord::Base.connection.raw_connection }`
+   - Auto-reconnect on connection failures (configurable)
+   - Connection health checks before use
+   - Note: Connection parameters are required - users should manage ENV variables themselves using `ENV.fetch`
+
+3. **PGMQ::Transaction** (`lib/pgmq/transaction.rb`)
+   - Low-level PostgreSQL transaction support (database primitive)
+   - Wraps PostgreSQL's native transactions (NOT a framework abstraction)
+   - Analogous to rdkafka-ruby providing Kafka transaction support
+   - Mixin providing `client.transaction do |txn|` support
+   - Enables atomic operations across multiple queues
+   - Rolls back automatically on errors
+
+4. **Models**
+   - **PGMQ::Message** - Represents queue messages with `msg_id`, `message` (raw JSONB), `read_ct`, `enqueued_at`, `vt`, `queue_name` (for multi-queue ops)
+   - **PGMQ::Metrics** - Queue metrics (length, age, total messages)
+   - **PGMQ::QueueMetadata** - Queue information (name, creation time)
+
+### Connection Pooling Details
+
+- Default pool size: 5 connections
+- Default timeout: 5 seconds
+- Fiber-aware (works with Ruby 3.0+ Fiber Scheduler)
+- Auto-reconnect enabled by default (can be disabled)
+- Connection health verified before each use (if auto-reconnect enabled)
+
+### Error Hierarchy
+
+```
+PGMQ::Errors::BaseError (StandardError)
+├── PGMQ::Errors::ConnectionError
+├── PGMQ::Errors::QueueNotFoundError
+├── PGMQ::Errors::MessageNotFoundError
+├── PGMQ::Errors::SerializationError
+├── PGMQ::Errors::ConfigurationError
+└── PGMQ::Errors::InvalidQueueNameError
+```
+
+### Queue Name Validation
+
+- Maximum 48 characters (PGMQ limitation for table prefixes)
+- Must start with letter or underscore
+- Only letters, digits, underscores allowed
+- Case-sensitive
+- Validated in `Client#validate_queue_name!`
+
+### Modular Architecture Pattern
+
+The Client class follows Waterdrop's modular architecture pattern for better maintainability:
+
+**Structure:**
+- Small core `Client` class (~130 lines) that includes functional modules
+- Each module focuses on a single domain area (queue management, producer, consumer, etc.)
+- Modules access parent class helpers (`validate_queue_name!`, `with_connection`)
+- Complete backward compatibility - no API changes
+
+**Benefits:**
+- **Testability**: Each module can be tested independently
+- **Maintainability**: Smaller files, clearer boundaries (largest file ~210 lines)
+- **Discoverability**: Logical grouping makes finding methods easier
+- **Extensibility**: New modules can be added without bloating the core class
+
+**Module Organization:**
+1. Transaction support (existing mixin)
+2. Queue lifecycle operations (create, drop, list)
+3. Message production (sending)
+4. Single-queue consumption (reading)
+5. Multi-queue operations (efficient polling across queues)
+6. Message lifecycle (pop, delete, archive, visibility timeout)
+7. Maintenance operations (purge, detach archive)
+8. Metrics and monitoring
+
+All modules are automatically loaded via Zeitwerk.
+
+## Common Patterns
+
+### Client Initialization
+
+```ruby
+# Connection string (preferred)
+client = PGMQ::Client.new('postgres://localhost:5433/pgmq_test')
+
+# Connection hash
+client = PGMQ::Client.new(
+  host: 'localhost',
+  port: 5433,
+  dbname: 'pgmq_test',
+  user: 'postgres',
+  password: 'postgres'
+)
+
+# Connection hash using ENV variables (user manages ENV themselves)
+client = PGMQ::Client.new(
+  host: ENV.fetch('PG_HOST', 'localhost'),
+  port: ENV.fetch('PG_PORT', 5432).to_i,
+  dbname: ENV.fetch('PG_DATABASE', 'pgmq'),
+  user: ENV.fetch('PG_USER', 'postgres'),
+  password: ENV.fetch('PG_PASSWORD', 'postgres')
+)
+
+# Rails integration (reuses Rails connection pool)
+client = PGMQ::Client.new(-> { ActiveRecord::Base.connection.raw_connection })
+
+# Custom pool configuration
+client = PGMQ::Client.new(
+  'postgres://localhost/db',
+  pool_size: 10,
+  pool_timeout: 10,
+  auto_reconnect: false
+)
+```
+
+### Transaction Pattern
+
+```ruby
+# Atomic operations across queues
+client.transaction do |txn|
+  msg = txn.read('pending', vt: 30)
+  if msg
+    txn.produce('processed', msg.payload)
+    txn.delete('pending', msg.msg_id)
+  end
+end
+```
+
+### Long Polling Pattern
+
+```ruby
+# Efficient message consumption
+loop do
+  msg = client.read_with_poll('orders',
+    vt: 30,
+    max_poll_seconds: 5,
+    poll_interval_ms: 100
+  )
+  break unless msg
+
+  process(msg)
+  client.delete('orders', msg.msg_id)
+end
+```
+
+## Testing Guidelines
+
+### Test Structure
+
+- **Unit tests** (`spec/unit/`) - Test classes in isolation, mock database
+- **Integration tests** (`spec/integration/`) - Test full workflow with real PostgreSQL
+
+### Test Helpers
+
+Located in `spec/support/database_helpers.rb`:
+- Database cleanup between tests
+- Connection helpers
+- Common test utilities
+
+### Coverage Requirements
+
+- Minimum overall coverage: 80%
+- Minimum per-file coverage: 70%
+- SimpleCov configured in `spec/spec_helper.rb`
+
+### Writing Tests
+
+- Use descriptive test names
+- Follow AAA pattern (Arrange, Act, Assert)
+- Mock external dependencies in unit tests
+- Use real database for integration tests
+- Clean up queues in `after` blocks
+
+## Code Style
+
+- Ruby 3.2+ syntax
+- Frozen string literals (`# frozen_string_literal: true`)
+- Max line length: 120 characters (except specs/gemspec)
+- YARD documentation for public methods
+- Single quotes for strings (unless interpolation needed)
+
+## CI/CD
+
+GitHub Actions workflows in `.github/workflows/`:
+- **ci.yml** - Runs RSpec on all Ruby versions (3.2, 3.3, 3.4, 3.5)
+- **push.yml** - Additional checks on push
+
+## Dependencies
+
+**Runtime:**
+- `pg` (~> 1.5) - PostgreSQL adapter
+- `connection_pool` (~> 2.4) - Thread-safe connection pooling
+
+**Development:**
+- `rspec` - Testing framework
+- `simplecov` - Code coverage
+- `pry` / `pry-byebug` - Debugging tools
+
+
+## Version Information
+
+- Minimum Ruby: 3.2.0
+- Supported PostgreSQL: 14-18 with PGMQ extension
+- License: LGPL-3.0
+
+## Important Files
+
+### Core Library Structure
+- `lib/pgmq/client.rb` - Main public API (~130 lines, includes all modules)
+- `lib/pgmq/client/` - Client functional modules directory:
+  - `queue_management.rb` - Queue lifecycle operations (~100 lines)
+  - `producer.rb` - Message sending (~70 lines)
+  - `consumer.rb` - Single-queue reading (~140 lines)
+  - `multi_queue.rb` - Multi-queue operations (~200 lines)
+  - `message_lifecycle.rb` - Message state transitions (~210 lines)
+  - `maintenance.rb` - Queue maintenance (~30 lines)
+  - `metrics.rb` - Monitoring (~40 lines)
+- `lib/pgmq/connection.rb` - Connection pooling and management
+- `lib/pgmq/transaction.rb` - Transaction support
+- `lib/pgmq/message.rb` - Message model (Data class)
+- `lib/pgmq/metrics.rb` - Metrics model
+- `lib/pgmq/queue_metadata.rb` - Queue metadata model
+
+### Documentation & Testing
+- `spec/spec_helper.rb` - RSpec configuration + SimpleCov setup
+- `spec/integration/` - Integration tests with real PostgreSQL
+- `spec/unit/` - Unit tests for individual components
+- `DEVELOPMENT.md` - Comprehensive development documentation
+- `README.md` - User-facing documentation with all API examples
+- `CLAUDE.md` - AI assistant guidance (this file)

data/Gemfile

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 gemspec
 
 group :development, :test do
-  gem 'rake'
-  gem 'rspec'
-  gem 'yard-lint'
+  gem "rake"
+  gem "rspec"
+  gem "async", "~> 2.6" # Fiber Scheduler for concurrent I/O testing
 end
 
 group :test do
-  gem 'simplecov', require: false
+  gem "simplecov", require: false
 end

data/Gemfile.lint

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Documentation linting
+gem "yard-lint"
+
+# Code style (StandardRB via RuboCop)
+gem "standard"
+gem "standard-performance"
+gem "rubocop-performance"
+gem "rubocop-rspec"
+gem "standard-rspec"
+gem "rubocop-capybara"
+gem "rubocop-factory_bot"
+gem "rubocop-rspec_rails"