pgbus 0.7.2 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1a647a2e485cace147ca201861ff4613e9c14f72f8fd8be9060f64d6eccfff5
-  data.tar.gz: bf3ca37850d549c6e9ed86bedbad1d88f9a50462b86a2d8a09113de7c1227d0f
+  metadata.gz: 8d07ecda9d90b73fa2ab8d9a34bf775b305bba9349dd5d49c99b587ea5b614bc
+  data.tar.gz: af072bf9e30ead0928db95896380384c49d8a49a59994864693aea80dd249bda
 SHA512:
-  metadata.gz: b32dac214071005fa5974478f2cb8bd4d8a270efc3e6bc94141b74c28cebfea0dfa84e41ad9bf1ec2a10c8ab0d09ae08d0df989f0894b8d5cbc6a461698ecf5b
-  data.tar.gz: ea55e1a29e53e491063c34aaea3a643498d1567968e64833d9a38deef2bcd7a48dfb35e377601d347fa8e05e55a5647a77dbe958d9584fcdc8669a362ff253a8
+  metadata.gz: 49eccf16ff1d0dcdec75f111bda474b343f3cf154b14569d19138f1b666457d71482037e390f4faa7136e21ead14b32a8a9408d18256843992e83476424a333c
+  data.tar.gz: 0d78309574c68a90b59b276b7648ac17cd8c74f3dbedebbd3d6cabe70a062a4d879cac19da8b2ab6ac78584f671ec7eda1db37fa459ecd761b81f0cd5c81ded0

data/lib/pgbus/configuration.rb

@@ -103,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
@@ -209,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/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.2"
+  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.2
+  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