pgbus 0.7.1 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c45dd364f341b6819b7901f583e058dbe761b375210e4162f19faf75917e3043
-  data.tar.gz: ed5ee189a3ff3d7fe0610deada3b2daba3726a2647d7762c58735e0771c9e0eb
+  metadata.gz: 8d07ecda9d90b73fa2ab8d9a34bf775b305bba9349dd5d49c99b587ea5b614bc
+  data.tar.gz: af072bf9e30ead0928db95896380384c49d8a49a59994864693aea80dd249bda
 SHA512:
-  metadata.gz: e28c032dc7b4f2cba37bd709c4a45030bcedd90274b86a1499d55dd4f4e255769e580983023602a42267b8728068a7eb11f7fdcbc8d12bd3efd83f35a50f241b
-  data.tar.gz: dc6d8d5d2e4feebbf7d940c173f53700549b5364c0e15df3f6afac1d72ecc6b1222127d85649016e9c6590e3c184eb9365da95c424a21a98be683862f4a24e67
+  metadata.gz: 49eccf16ff1d0dcdec75f111bda474b343f3cf154b14569d19138f1b666457d71482037e390f4faa7136e21ead14b32a8a9408d18256843992e83476424a333c
+  data.tar.gz: 0d78309574c68a90b59b276b7648ac17cd8c74f3dbedebbd3d6cabe70a062a4d879cac19da8b2ab6ac78584f671ec7eda1db37fa459ecd761b81f0cd5c81ded0

data/lib/pgbus/active_job/executor.rb

@@ -19,7 +19,11 @@ module Pgbus
 
       def execute(message, queue_name, source_queue: nil)
         execution_start = monotonic_now
+        tag = "msg_id=#{message.msg_id} queue=#{queue_name} read_ct=#{message.read_ct}"
+        Pgbus.logger.debug { "[Pgbus::Executor] start #{tag}" }
+
         payload = JSON.parse(message.message)
+        job_class = payload["job_class"]
         read_count = message.read_ct.to_i
 
         if read_count > config.max_retries
@@ -29,10 +33,9 @@ module Pgbus
           signal_batch_discarded(payload)
           Uniqueness.release_lock(Uniqueness.extract_key(payload))
           record_stat(payload, queue_name, "dead_lettered", execution_start, message: message)
+          Pgbus.logger.debug { "[Pgbus::Executor] dead_lettered #{tag} job_class=#{job_class}" }
           return :dead_lettered
         end
-
-        job_class = payload["job_class"]
         uniqueness_key = Uniqueness.extract_key(payload)
         uniqueness_strategy = Uniqueness.extract_strategy(payload)
 
@@ -53,28 +56,24 @@ module Pgbus
           end
         end
 
+        Pgbus.logger.debug { "[Pgbus::Executor] deserialized #{tag} job_class=#{job_class}" }
         job_succeeded = false
 
-        # Debug-level phase markers. Silent at INFO+, but invaluable when a
-        # fiber interrupt or connection issue loses control flow between phases
-        # (issue #126). Each line identifies msg_id + phase so the gap is
-        # visible in logs: "deserialized" without "archived" means the job
-        # ran but its message was never archived.
         msg_id = message.msg_id.to_i
         Instrumentation.instrument("pgbus.executor.execute", queue: queue_name, job_class: job_class) do
-          Pgbus.logger.debug { "[Pgbus] Executor phase=deserialize msg_id=#{msg_id} job=#{job_class}" }
           job = ::ActiveJob::Base.deserialize(payload)
-          Pgbus.logger.debug { "[Pgbus] Executor phase=perform msg_id=#{msg_id} job=#{job_class}" }
+          Pgbus.logger.debug { "[Pgbus::Executor] running #{tag} job_class=#{job_class}" }
           execute_job(job)
-          Pgbus.logger.debug { "[Pgbus] Executor phase=archive msg_id=#{msg_id} job=#{job_class}" }
+          Pgbus.logger.debug { "[Pgbus::Executor] perform_returned #{tag} job_class=#{job_class}" }
           archive_from(queue_name, msg_id, source_queue: source_queue)
+          Pgbus.logger.debug { "[Pgbus::Executor] archived #{tag} job_class=#{job_class}" }
           FailedEventRecorder.clear!(queue_name: queue_name, msg_id: msg_id)
           job_succeeded = true
-          Pgbus.logger.debug { "[Pgbus] Executor phase=succeeded msg_id=#{msg_id} job=#{job_class}" }
         end
 
         instrument("pgbus.job_completed", queue: queue_name, job_class: job_class)
         record_stat(payload, queue_name, "success", execution_start, message: message)
+        Pgbus.logger.debug { "[Pgbus::Executor] done #{tag} job_class=#{job_class}" }
         :success
       rescue *FATAL_EXCEPTIONS
         # Process-fatal: propagate so the supervisor/OS can react.
@@ -88,6 +87,7 @@ module Pgbus
         handle_failure(message, queue_name, e, payload: payload)
         instrument("pgbus.job_failed", queue: queue_name, job_class: payload&.dig("job_class"), error: e.class.name)
         record_stat(payload, queue_name, "failed", execution_start, message: message)
+        Pgbus.logger.debug { "[Pgbus::Executor] failed #{tag} job_class=#{payload&.dig("job_class")} error=#{e.class}" }
         # Don't signal concurrency on transient failure — the job will be retried.
         # Semaphore is released only on success or dead-lettering.
         :failed

data/lib/pgbus/configuration.rb

@@ -85,6 +85,10 @@ module Pgbus
     # Requires a matching entry in config/database.yml under the "pgbus" key.
     attr_accessor :connects_to
 
+    # Zombie message detection — logs a warning when a message is redelivered
+    # (read_ct > 1) without any prior failure recorded in pgbus_failed_events.
+    attr_accessor :zombie_detection
+
     # Job stats
     attr_accessor :stats_enabled
     attr_reader :stats_retention # rubocop:disable Style/AccessorGrouping
@@ -99,7 +103,7 @@ module Pgbus
                   :streams_default_retention, :streams_retention, :streams_heartbeat_interval,
                   :streams_max_connections, :streams_idle_timeout, :streams_listen_health_check_ms,
                   :streams_write_deadline_ms, :streams_falcon_streaming_body,
-                  :streams_stats_enabled
+                  :streams_stats_enabled, :streams_test_mode
 
     def initialize
       @database_url = nil
@@ -160,6 +164,8 @@ module Pgbus
       @skip_recurring = false
       @recurring_execution_retention = 7 * 24 * 3600 # 7 days
 
+      @zombie_detection = true
+
       @stats_enabled = true
       @stats_retention = 30 * 24 * 3600 # 30 days
 
@@ -203,6 +209,7 @@ module Pgbus
       # gates pgbus_job_stats recording) on purpose — operators
       # usually want job stats on and stream stats off, or vice versa.
       @streams_stats_enabled = false
+      @streams_test_mode = false
     end
 
     def queue_name(name)

data/lib/pgbus/event_bus/publisher.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "time"
+
 module Pgbus
   module EventBus
     module Publisher
@@ -7,6 +9,27 @@ module Pgbus
 
       def publish(routing_key, payload, headers: nil, delay: 0)
         event_data = build_event_data(payload)
+
+        if defined?(Pgbus::Testing) && !Pgbus::Testing.disabled?
+          event = Pgbus::Event.new(
+            event_id: event_data["event_id"],
+            payload: event_data["payload"],
+            published_at: event_data["published_at"] ? Time.parse(event_data["published_at"]) : nil,
+            routing_key: routing_key,
+            headers: headers
+          )
+
+          Pgbus::Testing.store.push_event(event)
+
+          if Pgbus::Testing.inline? && delay.to_i <= 0
+            Pgbus::EventBus::Registry.instance.handlers_for(routing_key).each do |subscriber|
+              subscriber.handler_class.new.handle(event)
+            end
+          end
+
+          return event_data
+        end
+
         Pgbus.client.publish_to_topic(routing_key, event_data, headers: headers, delay: delay)
       end
 

data/lib/pgbus/failed_event_recorder.rb

@@ -35,6 +35,18 @@ module Pgbus
         ErrorReporter.report(e, { action: "record_failed_event", queue: queue_name, msg_id: msg_id })
       end
 
+      def exists?(queue_name:, msg_id:)
+        result = connection.select_value(
+          "SELECT 1 FROM pgbus_failed_events WHERE queue_name = $1 AND msg_id = $2 LIMIT 1",
+          "FailedEvent Exists",
+          [queue_name, msg_id.to_i]
+        )
+        !result.nil?
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] FailedEvent exists? check failed: #{e.class}: #{e.message}" }
+        false
+      end
+
       def clear!(queue_name:, msg_id:)
         connection.exec_delete(
           "DELETE FROM pgbus_failed_events WHERE queue_name = $1 AND msg_id = $2",

data/lib/pgbus/process/worker.rb

@@ -126,6 +126,7 @@ module Pgbus
 
         @rate_counter.increment(:dequeued, tagged_messages.size)
         tagged_messages.each do |queue_name, message, source_queue|
+          detect_zombie(queue_name, message)
           @in_flight.increment
           @pool.post { process_message(message, queue_name, source_queue: source_queue) }
         end
@@ -285,6 +286,21 @@ module Pgbus
         Pgbus.logger.error { "[Pgbus] Queue table missing: #{error.message}" }
       end
 
+      def detect_zombie(queue_name, message)
+        return unless config.zombie_detection
+        return unless message.read_ct.to_i > 1
+
+        return if FailedEventRecorder.exists?(queue_name: queue_name, msg_id: message.msg_id.to_i)
+
+        Pgbus.logger.warn do
+          "[Pgbus] Zombie message redelivered: queue=#{queue_name} msg_id=#{message.msg_id} " \
+            "read_ct=#{message.read_ct} — previous read did not record a failure. " \
+            "The worker may have crashed mid-execute or the executor silently dropped the job."
+        end
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] Zombie detection failed: #{e.class}: #{e.message}" }
+      end
+
       def check_recycle
         return unless @lifecycle.running? && recycle_needed?
 

data/lib/pgbus/testing/assertions.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Testing
+    # Framework-agnostic assertion helpers. Included by both RSpec and Minitest
+    # integrations. Can also be included directly in any test class.
+    #
+    #   include Pgbus::Testing::Assertions
+    #
+    #   assert_pgbus_published(count: 1, routing_key: "orders.created") do
+    #     Order.create!(...)
+    #   end
+    module Assertions
+      def pgbus_published_events(routing_key: nil)
+        Pgbus::Testing.store.events(routing_key: routing_key)
+      end
+
+      def assert_pgbus_published(count:, routing_key: nil)
+        before = pgbus_published_events(routing_key: routing_key).size
+        yield
+        after = pgbus_published_events(routing_key: routing_key).size
+        actual = after - before
+
+        return if actual == count
+
+        suffix = routing_key ? " matching #{routing_key.inspect}" : ""
+        raise_assertion("Expected #{count} event(s) published#{suffix}, got #{actual}")
+      end
+
+      def assert_no_pgbus_published(routing_key: nil)
+        before = pgbus_published_events(routing_key: routing_key).size
+        yield
+        after = pgbus_published_events(routing_key: routing_key).size
+        actual = after - before
+
+        return if actual.zero?
+
+        suffix = routing_key ? " matching #{routing_key.inspect}" : ""
+        raise_assertion("Expected no events published#{suffix}, got #{actual}")
+      end
+
+      # Execute the block, capturing events, then dispatch all captured events
+      # to their registered handlers.
+      def perform_published_events
+        yield
+        Pgbus::Testing.store.drain!
+      end
+
+      private
+
+      def raise_assertion(message)
+        # Use Minitest::Assertion if available, otherwise a generic RuntimeError
+        raise Minitest::Assertion, message if defined?(Minitest::Assertion)
+
+        raise message
+      end
+    end
+  end
+end

data/lib/pgbus/testing/minitest.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../testing"
+
+module Pgbus
+  module Testing
+    # Minitest integration for Pgbus test helpers.
+    #
+    # Include in your test_helper.rb:
+    #
+    #   require "pgbus/testing/minitest"
+    #
+    #   class ActiveSupport::TestCase
+    #     include Pgbus::Testing::MinitestHelpers
+    #   end
+    #
+    # This provides:
+    #   - Automatic fake mode + store clearing per test
+    #   - assert_pgbus_published / assert_no_pgbus_published
+    #   - perform_published_events
+    #   - pgbus_published_events
+    module MinitestHelpers
+      include Pgbus::Testing::Assertions
+
+      def before_setup
+        Pgbus::Testing.fake!
+        Pgbus::Testing.store.clear!
+        super
+      end
+    end
+  end
+end

data/lib/pgbus/testing/rspec.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "../testing"
+
+RSpec::Matchers.define :have_published_event do |expected_routing_key|
+  supports_block_expectations
+
+  chain(:with_payload) { |payload| @expected_payload = payload }
+  chain(:with_headers) { |headers| @expected_headers = headers }
+  chain(:exactly)      { |count|   @expected_count = count }
+
+  match do |block|
+    @before = Pgbus::Testing.store.events(routing_key: expected_routing_key).dup
+    block.call
+    @after = Pgbus::Testing.store.events(routing_key: expected_routing_key)
+    @new_events = @after - @before
+
+    return false if @new_events.empty?
+
+    if @expected_payload
+      @new_events = @new_events.select { |e| values_match?(@expected_payload, e.payload) }
+      return false if @new_events.empty?
+    end
+
+    if @expected_headers
+      @new_events = @new_events.select { |e| values_match?(@expected_headers, e.headers) }
+      return false if @new_events.empty?
+    end
+
+    return false if @expected_count && @new_events.size != @expected_count
+
+    true
+  end
+
+  match_when_negated do |block|
+    @before = Pgbus::Testing.store.events(routing_key: expected_routing_key).dup
+    block.call
+    @after = Pgbus::Testing.store.events(routing_key: expected_routing_key)
+    @new_events = @after - @before
+
+    @new_events = @new_events.select { |e| values_match?(@expected_payload, e.payload) } if @expected_payload
+
+    @new_events = @new_events.select { |e| values_match?(@expected_headers, e.headers) } if @expected_headers
+
+    if @expected_count
+      @new_events.size != @expected_count
+    else
+      @new_events.empty?
+    end
+  end
+
+  failure_message do
+    parts = ["expected block to publish a #{expected_routing_key.inspect} event"]
+    parts << "with payload #{@expected_payload.inspect}" if @expected_payload
+    parts << "with headers #{@expected_headers.inspect}" if @expected_headers
+    parts << "exactly #{@expected_count} time(s)" if @expected_count
+
+    published = @new_events&.size || 0
+    parts << "but #{published} matching event(s) were published"
+
+    if published.positive? && @expected_payload
+      actual_payloads = @after.map(&:payload)
+      parts << "actual payloads: #{actual_payloads.inspect}"
+    end
+
+    parts.join(", ")
+  end
+
+  failure_message_when_negated do
+    "expected block not to publish a #{expected_routing_key.inspect} event, but #{@new_events.size} were published"
+  end
+end
+
+RSpec.configure do |config|
+  config.include Pgbus::Testing::Assertions
+end

data/lib/pgbus/testing.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "pgbus"
+
+module Pgbus
+  # Test helpers for Pgbus EventBus. Opt-in via explicit require — never
+  # autoloaded by Zeitwerk so this code never leaks into production.
+  #
+  #   require "pgbus/testing"          # core only
+  #   require "pgbus/testing/rspec"    # RSpec matchers + auto-config
+  #   require "pgbus/testing/minitest" # Minitest assertions
+  #
+  # Three modes:
+  #   :fake     — capture published events in an in-memory store (default for tests)
+  #   :inline   — capture AND immediately dispatch to matching handlers
+  #   :disabled — pass through to the real publisher (production behavior)
+  module Testing
+    MODES = %i[fake inline disabled].freeze
+    MODE_KEY = :__pgbus_test_mode
+
+    # Thread-safe in-memory store for events captured in fake/inline mode.
+    class EventStore
+      def initialize
+        @mutex = Mutex.new
+        @events = []
+      end
+
+      def push_event(event)
+        @mutex.synchronize { @events << event }
+      end
+
+      def events(routing_key: nil)
+        @mutex.synchronize do
+          result = @events.dup
+          result = result.select { |e| e.routing_key == routing_key } if routing_key
+          result
+        end
+      end
+
+      def size
+        @mutex.synchronize { @events.size }
+      end
+
+      def clear!
+        @mutex.synchronize { @events.clear }
+      end
+
+      # Dispatch all stored events to their matching handlers, then clear.
+      # Events are removed one at a time after successful dispatch so that
+      # a handler exception leaves unprocessed events in the store.
+      def drain!
+        loop do
+          event = @mutex.synchronize { @events.first }
+          break unless event
+
+          Pgbus::EventBus::Registry.instance.handlers_for(event.routing_key).each do |subscriber|
+            subscriber.handler_class.new.handle(event)
+          end
+
+          @mutex.synchronize { @events.shift }
+        end
+      end
+    end
+
+    # Eagerly initialize the store so concurrent access never races on creation.
+    @store = EventStore.new
+
+    class << self
+      def mode!(mode, &block)
+        raise ArgumentError, "Unknown mode: #{mode}. Valid modes: #{MODES.join(", ")}" unless MODES.include?(mode)
+
+        sync_streams_test_mode!(mode)
+
+        unless block
+          Thread.main[MODE_KEY] = mode
+          return
+        end
+
+        old = Thread.current[MODE_KEY]
+        Thread.current[MODE_KEY] = mode
+        yield
+      ensure
+        if block
+          Thread.current[MODE_KEY] = old
+          sync_streams_test_mode!(old || :disabled)
+        end
+      end
+
+      def mode
+        Thread.current[MODE_KEY] || Thread.main[MODE_KEY] || :disabled
+      end
+
+      def fake!(&) = mode!(:fake, &)
+      def inline!(&) = mode!(:inline, &)
+      def disabled!(&) = mode!(:disabled, &)
+
+      def fake?     = mode == :fake
+      def inline?   = mode == :inline
+      def disabled? = mode == :disabled
+
+      attr_reader :store
+
+      private
+
+      # When entering fake/inline mode, enable streams_test_mode to prevent
+      # rack.hijack from spawning background threads that acquire DB
+      # connections outside the test transaction (see issue #133). When
+      # returning to :disabled mode, restore the previous setting.
+      def sync_streams_test_mode!(mode)
+        return unless defined?(Pgbus.configuration)
+
+        if mode == :disabled
+          Pgbus.configuration.streams_test_mode = false
+          Pgbus::Web::Streamer.reset! if defined?(Pgbus::Web::Streamer)
+        else
+          Pgbus.configuration.streams_test_mode = true
+        end
+      end
+    end
+  end
+end
+
+require_relative "testing/assertions"

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/stream_app.rb

@@ -62,6 +62,8 @@ module Pgbus
         cursor = parse_cursor(env, request)
         return bad_request("invalid cursor: #{cursor}") if cursor.is_a?(String)
 
+        return test_mode_stub if config.streams_test_mode
+
         return over_capacity if streamer.registry.size >= config.streams_max_connections
 
         if config.streams_falcon_streaming_body
@@ -210,6 +212,11 @@ module Pgbus
       def server_error
         [500, { "content-type" => "text/plain" }, ["pgbus: internal error"]]
       end
+
+      def test_mode_stub
+        body = ": pgbus test mode — connection accepted, no polling\n\n"
+        [200, sse_headers, [body]]
+      end
     end
   end
 end

data/lib/pgbus.rb

@@ -39,6 +39,7 @@ module Pgbus
         )
         loader.ignore("#{__dir__}/generators")
         loader.ignore("#{__dir__}/active_job")
+        loader.ignore("#{__dir__}/pgbus/testing")
         # lib/puma/plugin/pgbus_streams.rb is a Puma plugin — it's required
         # explicitly by the user from config/puma.rb via `plugin :pgbus_streams`.
         # Without this ignore, Zeitwerk scans lib/puma/ under the pgbus loader

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.3
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -308,6 +308,10 @@ files:
 - lib/pgbus/streams/turbo_broadcastable.rb
 - lib/pgbus/streams/turbo_stream_override.rb
 - lib/pgbus/streams/watermark_cache_middleware.rb
+- lib/pgbus/testing.rb
+- lib/pgbus/testing/assertions.rb
+- lib/pgbus/testing/minitest.rb
+- lib/pgbus/testing/rspec.rb
 - lib/pgbus/uniqueness.rb
 - lib/pgbus/version.rb
 - lib/pgbus/web/authentication.rb