pgbus 0.23.2 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae461d658279ccfb2b4d1f6a9518ff278637c48beb703556363be63207273e1d
-  data.tar.gz: 5cc7d7fed584a4d05564f184262f8f298384683498b448e79f87efc45f72fbe5
+  metadata.gz: d4d5cae2b9bd98099c3a64a88d9671f66b60dcc108d826095d5d97b9fafde703
+  data.tar.gz: 8c6533b41dc54cdca5f344718c3280059e1f930269ddfcf75f65426efb08a14e
 SHA512:
-  metadata.gz: 10d5c9068040692f84b8aefb60d864bdfa9b35160fe3d733b66de36aeffe93653c50ab792f8603523cda3b4646974af6f0961e039a4ae7fc57e2f7ebe575f37c
-  data.tar.gz: 7797c3f4134d55036e0678faf4cb3fe0cb1724e0bd6ac3c2c0d70c10a70a2b35a54fb987ae8c7caa46193ccdaf0e92f934bf86065daed179edc4aa67e2876fe8
+  metadata.gz: 80f77818760dd8c1290808ea1fa62ef42c7b5fb9490e65f93766648df2e769a152bcdbf8e9362edc878f08177dde4230e632ffdaebbb46139099255ffa2db8b5
+  data.tar.gz: 332be03140b01225aba67f96e57842459c57c103ed0578c7d4a4d446209250bc77d27563268c1b7773d6b1d844a115e2bae7676fc385fb1e8695d846621bb1af

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.24.0] - 2026-11-11
+
+### Added
+
+- **`Pgbus::Client#unbind_topic` and `Registry#prune_stale_bindings!`: a narrowed subscription can drop its old topic binding (issue #657).** A subscriber queue is named after its handler, so narrowing a handler's subscription (from `"#"` to `"order.created"`, say) bound the new pattern on the same queue and left the old `pgmq.topic_bindings` row: every publish only the old pattern matched still wrote a message into that queue, which the consumer archived as unrouted, and the only way out was raw SQL against the pgmq schema. `Client#unbind_topic(pattern, queue_name)` removes one binding from a logical queue name (prefixed as `#bind_topic` does, with the same stale-connection retry) and returns `true`, or `false` when there was none; it never creates the queue. `Client#topic_patterns(queue_name)` lists the patterns bound to a queue. `Pgbus::EventBus::Registry.instance.prune_stale_bindings!` binds each registered subscriber queue's declared patterns first, so a queue is never left without a binding, then unbinds every other pattern on it, and returns `{ queue_name => [removed patterns] }` for the queues it changed (`{}` on a second run). Queues with no subscriber registered in the process are not touched, so run it with every subscriber registered: a pattern only an unloaded subscriber declares counts as stale. Queues are compared by their physical name, so a Symbol `queue_name:` and two spellings that name one table (`"Audit-Q"`, `"audit_q"`) count as one queue and keep each other's patterns; the result is keyed by the first registered spelling. `queue_names:` (logical names, not the prefixed ones `#event_queue_names` returns) limits it to the named queues, `queue_names: []` prunes nothing, and a name no registered subscriber uses raises `ArgumentError` before anything changes, so a typo or a process without the handlers loaded cannot strip a live queue; a removed handler's queue is cleaned up with `Client#topic_patterns` and `Client#unbind_topic`. `setup_all!` does not call it: during a rolling deploy a process still on the old release owns the old pattern, so run it as an explicit step (a deploy task, a rake task) once every process runs the new subscriptions. Refs #657.
+
+## [0.23.2] - 2026-11-06
+
 ### Fixed
 
 - **A `<pgbus-stream-source>` moved in the DOM resumes from the last durable id it received, so it no longer replays and re-applies frames it already applied (issue #644).** `connectedCallback` reset the resume cursor from the `since-id` attribute on every connect, and `since-id` is the render-time watermark, never updated afterwards. An element disconnected and reconnected as the same instance (Turbo Drive carrying a `data-turbo-permanent` element into the next page's body, or app code calling `appendChild` / `replaceWith` / `insertBefore` on it) reconnected with `?since=<render-time watermark>`, the server replayed every durable frame since the page rendered, and each `replace` / `update` ran again over whatever the target had become since. The element now keeps the cursor it earned on the same `src`: a connect sends `?since=` with the greater of that cursor and `since-id` (both durable msg_ids of one stream, compared as `BigInt`; when only one parses as an integer, that one), so a re-render that carries a newer watermark still wins. A cursor earned on another `src` (the element was re-pointed) is dropped and `since-id` is used alone. The old connection's read loop now stops on its own abort signal, checked between the frames of one network chunk too, so a `pgbus:message` listener that moves the element mid-chunk no longer has the rest of that chunk delivered by both the old loop and the new connection's replay. The first connect is unchanged, and an ephemeral frame still never moves the cursor (issue #621). The workaround of writing `since-id` from a `pgbus:message` listener is no longer needed. No new API. Refs #644.

data/lib/pgbus/client.rb

@@ -1098,6 +1098,25 @@ module Pgbus
       end
     end
 
+    # Removes the +pattern+ binding from the logical +queue_name+ (issue #657).
+    # True when a binding was removed, false when there was none. Never creates
+    # the queue.
+    def unbind_topic(pattern, queue_name)
+      full_name = config.queue_name(queue_name)
+      with_stale_connection_retry do
+        synchronized { @pgmq.unbind_topic(pattern, full_name) }
+      end
+    end
+
+    # The patterns bound to the logical +queue_name+ in pgmq.topic_bindings
+    # (issue #657).
+    def topic_patterns(queue_name)
+      full_name = config.queue_name(queue_name)
+      with_stale_connection_retry do
+        synchronized { @pgmq.list_topic_bindings(queue_name: full_name).map { |binding| binding[:pattern] } }
+      end
+    end
+
     def publish_to_topic(routing_key, payload, headers: nil, delay: 0)
       with_stale_connection_retry do
         synchronized do

data/lib/pgbus/event_bus/registry.rb

@@ -62,6 +62,40 @@ module Pgbus
         end
       end
 
+      # Makes each subscriber queue's pgmq.topic_bindings equal to the patterns
+      # registered for it (issue #657). A subscriber queue is named after its
+      # handler, so narrowing a subscription ("#" → "order.created") binds the
+      # new pattern on the same queue and leaves the old row, which keeps
+      # copying events the consumer archives as unrouted.
+      #
+      # For every registered queue (or only +queue_names+, logical names, not
+      # the prefixed ones #event_queue_names returns): bind the patterns its
+      # subscribers declare first, so the queue is never left without a
+      # binding, then unbind every other pattern bound to it. Run it with every
+      # subscriber registered: a pattern only an unloaded subscriber declares
+      # counts as stale. +queue_names: []+ prunes nothing; a name no registered
+      # subscriber uses raises ArgumentError before anything changes (a typo, a
+      # prefixed name or a process without the handlers loaded would otherwise
+      # strip a live queue). A removed handler's queue is cleaned up with
+      # Pgbus.client.topic_patterns and Pgbus.client.unbind_topic.
+      #
+      # Returns { queue_name => [removed patterns] } for the queues it changed;
+      # a second run returns {}.
+      #
+      # Deliberately not part of setup_all!: during a rolling deploy a process
+      # still on the old release owns the old pattern, so pruning is an explicit
+      # step to run once every process runs the new subscriptions.
+      def prune_stale_bindings!(queue_names: nil)
+        declared = declared_bindings
+        targets = queue_names.nil? ? declared.keys : physical_targets(queue_names, declared)
+
+        targets.each_with_object({}) do |physical, removed|
+          queue_name, patterns = declared.fetch(physical)
+          stale = prune_queue_bindings(queue_name, patterns)
+          removed[queue_name] = stale unless stale.empty?
+        end
+      end
+
       # Subscribers a message read from +queue_name+ must be dispatched to
       # (issue #469). Every subscriber gets its own queue, so a topic with N
       # matching subscribers produces N queue copies of each event; selecting by
@@ -133,6 +167,49 @@ module Pgbus
 
       private
 
+      # { physical queue name => [logical name, declared patterns] }. Keyed by
+      # the physical name so a Symbol and a String, or two spellings
+      # QueueNameValidator folds to one table ("Audit-Q", "audit_q"), count as
+      # one queue; the logical name is the first registered spelling.
+      def declared_bindings
+        subscribers = @mutex.synchronize { @subscribers.dup }
+        subscribers.each_with_object({}) do |subscriber, declared|
+          physical = Pgbus.configuration.queue_name(subscriber.queue_name)
+          entry = declared[physical] ||= [subscriber.queue_name.to_s, []]
+          entry[1] |= [subscriber.pattern]
+        end
+      end
+
+      # The physical names of +queue_names+; raises before any change when one
+      # names no registered subscriber queue.
+      def physical_targets(queue_names, declared)
+        targets = queue_names.to_h { |name| [name, Pgbus.configuration.queue_name(name)] }
+        unknown = targets.reject { |_name, physical| declared.key?(physical) }.keys
+        unless unknown.empty?
+          raise ArgumentError, "No event subscriber is registered on queue(s) #{unknown.join(", ")}; " \
+                               "prune_stale_bindings! takes logical subscriber queue names"
+        end
+
+        targets.values.uniq
+      end
+
+      # Binds +patterns+ to +queue_name+, unbinds every other pattern bound to
+      # it, and returns the patterns this call removed (one another process
+      # removed first is not reported).
+      def prune_queue_bindings(queue_name, patterns)
+        client = Pgbus.client
+        patterns.each { |pattern| client.bind_topic(pattern, queue_name) }
+
+        stale = client.topic_patterns(queue_name) - patterns
+        removed = stale.select { |pattern| client.unbind_topic(pattern, queue_name) }
+        unless removed.empty?
+          Pgbus.logger.info do
+            "[Pgbus] Unbound stale topic patterns #{removed.inspect} from event queue #{queue_name}"
+          end
+        end
+        removed
+      end
+
       # True when running inside a rake schema/asset task, where setup_all!(safe:)
       # should skip rather than open a connection. Delegates to the shared,
       # public detector (issue #409) so there is a single implementation.

data/lib/pgbus/version.rb

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

data/sig/pgbus/client.rbs

@@ -71,7 +71,9 @@ module Pgbus
     def streams_swap_stats: () -> untyped
     def synchronizing?: () -> bool
     def target_queue: (untyped queue_name, ?untyped priority) -> untyped
+    def topic_patterns: (untyped queue_name) -> Array[String]
     def transaction: () ?{ (*untyped) -> untyped } -> untyped
+    def unbind_topic: (untyped pattern, untyped queue_name) -> bool
     def uniqueness_keys_present: (untyped lock_keys) -> untyped
     def update_notify_insert: (untyped queue_name, throttle_interval_ms: untyped) -> untyped
     def verify_connection!: () -> untyped

metadata

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