pgbus 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 903778ddd22823971fc4d9d888d10b657597c542e49d365fb7ad1863167d4f6c
-  data.tar.gz: f652a6675bfbc206d4ab3d43a44a704fbdd0247f57cae1252ef310772ec6e1bd
+  metadata.gz: bb5b86968b21bebedf9b33d6d69338b86f7dfb5304b5efa714b270bc8128fa10
+  data.tar.gz: f5d6118149ebcd7c7f773ab399fbdc97079883dd895339c5918c156fc416bbfe
 SHA512:
-  metadata.gz: 15fcf091f8b8de0823ff2a6f807fcb9fb3339700994221ded4dcbf22c942f01a636e0eaa53d6be9b44544113a281bf15d299e146b32b30b2e604b8fdd4c36447
-  data.tar.gz: 885ca1ccbdf1f65a83dde14cdc25fd6c9f63993c0692c1c6b088696d27b593bd3a81d27d7f5bc5fccb5a368882af51e8bd1c0b4bfbc0bba27a8ca567bf297405
+  metadata.gz: 7649ee8dfd9d9ff155e510c014a28fb070d79357d34ed4e8a8c0369c502c90b806d01775a0b01f480709fa9399d7ecc3edddb7d4e092813d42014d412833d9ce
+  data.tar.gz: 756c31dd3fd970dca11c78cbb17af8b74e798cd42e3782b9993e4081982cc340a1224b6c0b829c259ea6d13abcec035510c2b4e0e6b8c39f73a34b1b9cd2bc48

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.5.1] - 2026-04-08
+
+### Fixed
+
+- **Capsule DSL: anonymous duplicate capsules are now allowed.** Configurations like `c.workers = "*: 3; *: 3; *: 3; *: 3; *: 3"` (the legacy YAML pattern of 5 forks × 3 threads, all reading every queue) were rejected at boot in 0.5.0 with `Pgbus::Configuration::CapsuleDSL::ParseError: wildcard '*' appears in two capsules`. PGMQ tolerates multiple processes reading the same queue natively (`FOR UPDATE SKIP LOCKED`), and this is the canonical way to scale CPU parallelism across forks, so the rejection was wrong.
+
+  The fix introduces a "named vs anonymous" distinction:
+
+  - The string DSL parser is now purely syntactic — it no longer enforces overlap rules.
+  - `Pgbus::Configuration#workers=` auto-assigns `:name` only to capsules whose first queue would yield a *unique* name AND is not the bare wildcard. Wildcards stay anonymous; collision-prone first-queues stay anonymous.
+  - `Pgbus::Configuration#validate_no_queue_overlap!` (called by `c.capsule :name, ...`) now only checks against existing **named** capsules. Anonymous capsules can overlap freely with each other and with named capsules.
+  - Net result: `"*: 3; *: 3; *: 3"` produces 3 anonymous capsules (3 forks), `"critical: 5; default: 10"` produces 2 named capsules (CLI `--capsule critical` still works), and named-vs-named overlap is still rejected as before.
+
+  No changes required to user configuration — legacy YAML patterns and the modern DSL both work as documented.
+
 ## [Unreleased]
 
 ### Breaking Changes

data/lib/pgbus/configuration/capsule_dsl.rb

@@ -62,9 +62,12 @@ module Pgbus
         validate_input_type!
         validate_input_not_empty!
 
-        capsules = split_capsules(@input).map { |segment| parse_capsule(segment) }
-        validate_no_duplicate_queues_across_capsules!(capsules)
-        capsules
+        # Pure tokenization: split, parse each capsule, return them in order.
+        # Cross-capsule overlap rules live in Pgbus::Configuration#workers=
+        # because they depend on whether the resulting capsules are named or
+        # anonymous, and naming is a Configuration concern (not a parser one).
+        # Within-capsule duplicate-queue checks still happen in parse_capsule.
+        split_capsules(@input).map { |segment| parse_capsule(segment) }
       end
 
       private
@@ -168,23 +171,6 @@ module Pgbus
           seen[q] = true
         end
       end
-
-      def validate_no_duplicate_queues_across_capsules!(capsules)
-        return if capsules.size < 2
-
-        seen = {}
-        capsules.each_with_index do |capsule, idx|
-          capsule[:queues].each do |q|
-            if seen[q]
-              label = (q == WILDCARD ? "wildcard '*'" : "queue #{q.inspect}")
-              raise ParseError,
-                    "#{label} appears in two capsules (positions #{seen[q]} and #{idx + 1}) " \
-                    "in #{@input.inspect} — each queue can only be assigned to one capsule"
-            end
-            seen[q] = idx + 1
-          end
-        end
-      end
     end
   end
 end

data/lib/pgbus/configuration.rb

@@ -230,12 +230,34 @@ module Pgbus
     #            dispatcher-only processes).
     #
     # Raises ArgumentError for any other type.
+    #
+    # NAMING SEMANTICS for the String form:
+    #
+    # The parser produces anonymous capsules (no :name). The setter then
+    # auto-assigns a :name to capsules whose first queue would yield a
+    # *unique* name across the parsed list AND is not the bare wildcard
+    # (`*`). Anything else stays anonymous.
+    #
+    #   "critical: 5; default: 10"  -> two NAMED capsules ("critical", "default")
+    #   "*: 5"                       -> one anonymous capsule (wildcard never names)
+    #   "*: 3; *: 3; *: 3"           -> three anonymous capsules — legal,
+    #                                   represents "3 forks all reading every
+    #                                   queue", restoring the legacy YAML
+    #                                   `5 × {queues: ["*"], threads: 3}` shape
+    #   "default: 5; default: 3"     -> two anonymous capsules — same logic
+    #
+    # The point of the carve-out is the legacy "I want N forks of the same
+    # worker pool" pattern: it must keep working since PGMQ tolerates it
+    # natively (multiple processes reading the same queue with FOR UPDATE
+    # SKIP LOCKED). The CLI's --capsule selector only matches NAMED
+    # capsules, so anonymous duplicates can't be ambiguously addressed.
     def workers=(value)
       @workers = case value
                  when nil
                    nil
                  when String
-                   CapsuleDSL.parse(value).map { |entry| entry.merge(name: entry[:queues].first.to_s) }
+                   parsed = CapsuleDSL.parse(value)
+                   assign_auto_names(parsed)
                  when Array
                    value
                  else
@@ -445,33 +467,58 @@ module Pgbus
       raw&.to_s
     end
 
-    # Validates that no queue in +new_queues+ would overlap with any
-    # existing capsule. The wildcard '*' counts as overlapping with EVERY
-    # other queue (and vice versa) because at runtime '*' is expanded to
-    # all known queues. Raises ArgumentError on overlap.
+    # Auto-assign :name to parsed capsules where the first queue token would
+    # yield a unique name and is not the bare wildcard. See the long comment
+    # on +workers=+ for the why. Returns the same array with :name merged in
+    # where applicable.
+    def assign_auto_names(parsed_capsules)
+      first_queue_counts = parsed_capsules.each_with_object(Hash.new(0)) do |capsule, h|
+        h[capsule[:queues].first] += 1
+      end
+
+      parsed_capsules.map do |capsule|
+        first = capsule[:queues].first
+        nameable = first != CapsuleDSL::WILDCARD && first_queue_counts[first] == 1
+        nameable ? capsule.merge(name: first.to_s) : capsule
+      end
+    end
+
+    # Validates that the new capsule (added via +c.capsule :name, ...+) does
+    # not overlap with any existing NAMED capsule. Anonymous capsules (parsed
+    # from the string DSL with auto-naming skipped, e.g. wildcards or
+    # would-collide first-queues) are intentionally invisible here — they
+    # represent "N forks of the same pool" and are allowed to overlap with
+    # each other and with named capsules.
+    #
+    # The wildcard '*' counts as overlapping with EVERY other queue (and
+    # vice versa) because at runtime '*' is expanded to all known queues.
+    # Raises ArgumentError on overlap.
     def validate_no_queue_overlap!(new_queues)
-      existing = (@workers || []).flat_map { |c| c[:queues] || c["queues"] || [] }
-      return if existing.empty?
+      existing_named = (@workers || []).select { |c| capsule_name(c) }
+      return if existing_named.empty?
+
+      existing_queues = existing_named.flat_map { |c| c[:queues] || c["queues"] || [] }
+      return if existing_queues.empty?
 
-      if existing.include?(CapsuleDSL::WILDCARD)
+      if existing_queues.include?(CapsuleDSL::WILDCARD)
         raise ArgumentError,
-              "an existing capsule already uses '*' (matches every queue) — " \
+              "an existing named capsule already uses '*' (matches every queue) — " \
               "the new capsule's queues #{new_queues.inspect} would overlap with it"
       end
 
       if new_queues.include?(CapsuleDSL::WILDCARD)
         raise ArgumentError,
-              "the new capsule uses '*' (matches every queue) but other capsules " \
-              "are already defined with queues #{existing.inspect} — " \
+              "the new capsule uses '*' (matches every queue) but other named capsules " \
+              "are already defined with queues #{existing_queues.inspect} — " \
               "the wildcard would overlap with all of them"
       end
 
-      conflict = new_queues.find { |q| existing.include?(q) }
+      conflict = new_queues.find { |q| existing_queues.include?(q) }
       return unless conflict
 
       raise ArgumentError,
-            "queue #{conflict.inspect} is already assigned to another capsule — " \
-            "each queue can only belong to one capsule"
+            "queue #{conflict.inspect} is already assigned to another named capsule — " \
+            "named capsules cannot share queues"
     end
 
     def sum_thread_counts(entries, default_threads:, group:)

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Mikael Henriksson