pgmq-ruby 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53bd6f9c6cbc408bf96813d0fa19f16d753a52a52edc93f87db61444cb2cfbd8
-  data.tar.gz: ca1b41b82cf2cf4cde197e03309c516be9430b91f5c7ad06d0bdeea7f83b3812
+  metadata.gz: 5648229b33f490f7228d7f9b106fb40939632c6effff094d028d9f7dd5fc045a
+  data.tar.gz: 7a7d0ae6dd7ee59cf329093f4772e8cd8706e25be0e627defca60f3983e96084
 SHA512:
-  metadata.gz: 127cb4848ce4aae0929690794dbbe128bc8ed8449b28e41687f6268152005810378b7e63cabc9cde7bcbd66701a7b4a689cf864dee48e6196a6715df2e02ead4
-  data.tar.gz: 007c60255e9c87ba2e68765a4248319ac378677646739ac44b5f59db803a5effa27c36118e6f641d9f4145497309df11f1688080d72ca021f74c6139c88738f5
+  metadata.gz: 5da9b67730f7c1b58af6be47c2364092988823b2c536e762ca56cc91bd5f27d2d678aef116373c7f0c62fec5037438f30ae0482979c0df3f9414aa3e5f41987a
+  data.tar.gz: 7c892fcc8d30d306670b7dd3fd3a3e3f70f573916b3e6526e0833a59acad85cdd44fcf830fd327ccba6608fe0e30eb072d2adc1bcb287ccc28c388e743cfd19e

data/.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
       fail-fast: false
       matrix:
         ruby:
-          - '3.5.0-preview1'
+          - '4.0.0'
           - '3.4'
           - '3.3'
           - '3.2'
@@ -52,7 +52,7 @@ jobs:
           - 5433:5432
 
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
 
@@ -60,11 +60,11 @@ jobs:
         run: "[ -e $APT_DEPS ] || sudo apt-get install -y --no-install-recommends postgresql-client"
 
       - name: Remove Gemfile.lock for Ruby previews
-        if: contains(matrix.ruby, '3.5')
+        if: contains(matrix.ruby, '4.0')
         run: rm -f Gemfile.lock
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@d5126b9b3579e429dd52e51e68624dda2e05be25 # v1.267.0
+        uses: ruby/setup-ruby@90be1154f987f4dc0fe0dd0feedac9e473aa4ba8 # v1.286.0
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
@@ -102,55 +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@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
       - name: Set up Ruby
-        uses: ruby/setup-ruby@d5126b9b3579e429dd52e51e68624dda2e05be25 # v1.267.0
+        uses: ruby/setup-ruby@90be1154f987f4dc0fe0dd0feedac9e473aa4ba8 # v1.286.0
         with:
-          ruby-version: '3.4.7'
+          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@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - 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

@@ -19,12 +19,12 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@d5126b9b3579e429dd52e51e68624dda2e05be25 # v1.267.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/.ruby-version

@@ -1 +1 @@
-3.4.5
+4.0.0

data/.yard-lint.yml

@@ -3,166 +3,271 @@
 
 # Global settings for all validators
 AllValidators:
-  # YARD command-line options (applied to all validators by default)
   YardOptions:
-    - --private
-    - --protected
-
-  # Global file exclusion patterns
+  - "--private"
+  - "--protected"
   Exclude:
-    - '\.git'
-    - 'vendor/**/*'
-    - 'node_modules/**/*'
-    - 'spec/**/*'
-    - 'test/**/*'
-
-  # Exit code behavior (error, warning, convention, never)
-  FailOnSeverity: error
-
-  # Require 100% documentation coverage
+  - .git/**/*
+  - vendor/**/*
+  - node_modules/**/*
+  - spec/**/*
+  FailOnSeverity: convention
   RequiredCoverage: 100
 
 # Documentation validators
 Documentation/UndocumentedObjects:
-  Description: 'Checks for classes, modules, and methods without documentation.'
+  Description: Checks for classes, modules, and methods without documentation.
   Enabled: true
   Severity: error
   ExcludedMethods:
-    - 'initialize/0'  # Exclude parameter-less initialize
-    - '/^_/'          # Exclude private methods (by convention)
+  - initialize/0
+  - "/^_/"
 
 Documentation/UndocumentedMethodArguments:
-  Description: 'Checks for method parameters without @param tags.'
+  Description: Checks for method parameters without @param tags.
   Enabled: true
   Severity: error
 
 Documentation/UndocumentedBooleanMethods:
-  Description: 'Checks that question mark methods document their boolean return.'
+  Description: Checks that question mark methods document their boolean return.
   Enabled: true
   Severity: error
 
 Documentation/UndocumentedOptions:
-  Description: 'Detects methods with options hash parameters but no @option tags.'
+  Description: Detects methods with options hash parameters but no @option tags.
   Enabled: true
   Severity: error
 
 Documentation/MarkdownSyntax:
-  Description: 'Detects common markdown syntax errors in documentation.'
+  Description: Detects common markdown syntax errors in documentation.
   Enabled: true
   Severity: error
 
+Documentation/EmptyCommentLine:
+  Description: Detects empty comment lines at the start or end of documentation blocks.
+  Enabled: true
+  Severity: convention
+  EnabledPatterns:
+    Leading: true
+    Trailing: true
+
+Documentation/BlankLineBeforeDefinition:
+  Description: Detects blank lines between YARD documentation and method definition.
+  Enabled: true
+  Severity: convention
+  OrphanedSeverity: convention
+  EnabledPatterns:
+    SingleBlankLine: true
+    OrphanedDocs: true
+
 # Tags validators
 Tags/Order:
-  Description: 'Enforces consistent ordering of YARD tags.'
+  Description: Enforces consistent ordering of YARD tags.
   Enabled: true
   Severity: error
   EnforcedOrder:
-    - param
-    - option
-    - return
-    - raise
-    - example
+  - param
+  - option
+  - return
+  - raise
+  - example
 
 Tags/InvalidTypes:
-  Description: 'Validates type definitions in @param, @return, @option tags.'
+  Description: Validates type definitions in @param, @return, @option tags.
   Enabled: true
   Severity: error
   ValidatedTags:
-    - param
-    - option
-    - return
+  - param
+  - option
+  - return
 
 Tags/TypeSyntax:
-  Description: 'Validates YARD type syntax using YARD parser.'
+  Description: Validates YARD type syntax using YARD parser.
   Enabled: true
   Severity: error
   ValidatedTags:
-    - param
-    - option
-    - return
-    - yieldreturn
+  - param
+  - option
+  - return
+  - yieldreturn
 
 Tags/MeaninglessTag:
-  Description: 'Detects @param/@option tags on classes, modules, or constants.'
+  Description: Detects @param/@option tags on classes, modules, or constants.
   Enabled: true
   Severity: error
   CheckedTags:
-    - param
-    - option
+  - param
+  - option
   InvalidObjectTypes:
-    - class
-    - module
-    - constant
+  - class
+  - module
+  - constant
 
 Tags/CollectionType:
-  Description: 'Validates Hash collection syntax consistency.'
+  Description: Validates Hash collection syntax consistency.
   Enabled: true
   Severity: error
-  EnforcedStyle: long  # 'long' for Hash{K => V} (YARD standard), 'short' for {K => V}
+  EnforcedStyle: long
   ValidatedTags:
-    - param
-    - option
-    - return
-    - yieldreturn
+  - param
+  - option
+  - return
+  - yieldreturn
 
 Tags/TagTypePosition:
-  Description: 'Validates type annotation position in tags.'
+  Description: Validates type annotation position in tags.
   Enabled: true
   Severity: error
   CheckedTags:
-    - param
-    - option
-  # EnforcedStyle: 'type_after_name' (YARD standard: @param name [Type])
-  #                or 'type_first' (@param [Type] name)
+  - param
+  - option
   EnforcedStyle: type_after_name
 
 Tags/ApiTags:
-  Description: 'Enforces @api tags on public objects.'
-  Enabled: true
+  Description: Enforces @api tags on public objects.
+  Enabled: false
   Severity: error
   AllowedApis:
-    - public
-    - private
-    - internal
+  - public
+  - private
+  - internal
 
 Tags/OptionTags:
-  Description: 'Requires @option tags for methods with options parameters.'
+  Description: Requires @option tags for methods with options parameters.
   Enabled: true
   Severity: error
 
+Tags/ExampleSyntax:
+  Description: Validates Ruby syntax in @example tags.
+  Enabled: true
+  Severity: warning
+
+Tags/RedundantParamDescription:
+  Description: Detects meaningless parameter descriptions that add no value.
+  Enabled: true
+  Severity: convention
+  CheckedTags:
+  - param
+  - option
+  Articles:
+  - The
+  - the
+  - A
+  - a
+  - An
+  - an
+  MaxRedundantWords: 6
+  GenericTerms:
+  - object
+  - instance
+  - value
+  - data
+  - item
+  - element
+  EnabledPatterns:
+    ArticleParam: true
+    PossessiveParam: true
+    TypeRestatement: true
+    ParamToVerb: true
+    IdPattern: true
+    DirectionalDate: true
+    TypeGeneric: true
+
+Tags/InformalNotation:
+  Description: Detects informal tag notation patterns like "Note:" instead of @note.
+  Enabled: true
+  Severity: warning
+  CaseSensitive: false
+  RequireStartOfLine: true
+  Patterns:
+    Note: "@note"
+    Todo: "@todo"
+    TODO: "@todo"
+    FIXME: "@todo"
+    See: "@see"
+    See also: "@see"
+    Warning: "@deprecated"
+    Deprecated: "@deprecated"
+    Author: "@author"
+    Version: "@version"
+    Since: "@since"
+    Returns: "@return"
+    Raises: "@raise"
+    Example: "@example"
+
+Tags/NonAsciiType:
+  Description: Detects non-ASCII characters in type annotations.
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+  - param
+  - option
+  - return
+  - yieldreturn
+  - yieldparam
+
+Tags/TagGroupSeparator:
+  Description: Enforces blank line separators between different YARD tag groups.
+  Enabled: false
+  Severity: convention
+  TagGroups:
+    param:
+    - param
+    - option
+    return:
+    - return
+    error:
+    - raise
+    - throws
+    example:
+    - example
+    meta:
+    - see
+    - note
+    - todo
+    - deprecated
+    - since
+    - version
+    - api
+    yield:
+    - yield
+    - yieldparam
+    - yieldreturn
+  RequireAfterDescription: false
+
 # Warnings validators - catches YARD parser errors
 Warnings/UnknownTag:
-  Description: 'Detects unknown YARD tags.'
+  Description: Detects unknown YARD tags.
   Enabled: true
   Severity: error
 
 Warnings/UnknownDirective:
-  Description: 'Detects unknown YARD directives.'
+  Description: Detects unknown YARD directives.
   Enabled: true
   Severity: error
 
 Warnings/InvalidTagFormat:
-  Description: 'Detects malformed tag syntax.'
+  Description: Detects malformed tag syntax.
   Enabled: true
   Severity: error
 
 Warnings/InvalidDirectiveFormat:
-  Description: 'Detects malformed directive syntax.'
+  Description: Detects malformed directive syntax.
   Enabled: true
   Severity: error
 
 Warnings/DuplicatedParameterName:
-  Description: 'Detects duplicate @param tags.'
+  Description: Detects duplicate @param tags.
   Enabled: true
   Severity: error
 
 Warnings/UnknownParameterName:
-  Description: 'Detects @param tags for non-existent parameters.'
+  Description: Detects @param tags for non-existent parameters.
   Enabled: true
   Severity: error
 
 # Semantic validators
 Semantic/AbstractMethods:
-  Description: 'Ensures @abstract methods do not have real implementations.'
+  Description: Ensures @abstract methods do not have real implementations.
   Enabled: true
   Severity: error

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 # 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
+- **[Breaking]** Rename `send` to `produce` and `send_batch` to `produce_batch`. This avoids shadowing Ruby's built-in `Object#send` method which caused confusion and required workarounds (e.g., using `__send__`). The new names also align better with the producer/consumer terminology used in message queue systems.
+
+### Queue Management
+- [Enhancement] `create`, `create_partitioned`, and `create_unlogged` now return `true` if the queue was newly created, `false` if it already existed. This provides clearer feedback and aligns with the Rust PGMQ client behavior.
+
+### Message Operations
+- **[Feature]** Add `headers:` parameter to `produce(queue_name, message, headers:, delay:)` for message metadata (routing, tracing, correlation IDs).
+- **[Feature]** Add `headers:` parameter to `produce_batch(queue_name, messages, headers:, delay:)` for batch message metadata.
+- **[Feature]** Introduce `pop_batch(queue_name, qty)` for atomic batch pop (read + delete) operations.
+- **[Feature]** Introduce `set_vt_batch(queue_name, msg_ids, vt_offset:)` for batch visibility timeout updates.
+- **[Feature]** Introduce `set_vt_multi(updates_hash, vt_offset:)` for updating visibility timeouts across multiple queues atomically.
+
+### Notifications
+- **[Feature]** Introduce `enable_notify_insert(queue_name, throttle_interval_ms:)` for PostgreSQL LISTEN/NOTIFY support.
+- **[Feature]** Introduce `disable_notify_insert(queue_name)` to disable notifications.
+
+### Compatibility
+- [Enhancement] Add Ruby 4.0.0 support with full CI testing.
+
 ## 0.3.0 (2025-11-14)
 
 Initial release of pgmq-ruby - a low-level Ruby client for PGMQ (PostgreSQL Message Queue).