jetstream_bridge 4.1.0 → 4.2.0

data/lib/jetstream_bridge/rails/railtie.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'integration'
+
+module JetstreamBridge
+  # Rails integration for JetStream Bridge.
+  #
+  # This Railtie integrates JetStream Bridge with the Rails application lifecycle:
+  # - Configuration: Logger is configured early in the Rails boot process
+  # - Startup: Connection is established after user initializers load (explicit startup!)
+  # - Shutdown: Connection is closed when Rails shuts down (at_exit hook)
+  # - Restart: Puma/Unicorn workers get fresh connections on fork
+  #
+  class Railtie < ::Rails::Railtie
+    # Set up logger to use Rails.logger by default
+    # Note: This only configures the logger, does NOT establish connection
+    initializer 'jetstream_bridge.logger', before: :initialize_logger do
+      JetstreamBridge::Rails::Integration.configure_logger!
+    end
+
+    # Load ActiveRecord model tweaks after ActiveRecord is loaded
+    initializer 'jetstream_bridge.active_record', after: 'active_record.initialize_database' do
+      JetstreamBridge::Rails::Integration.attach_active_record_hooks!
+    end
+
+    # Establish connection after Rails initialization is complete
+    # This runs after all user initializers have loaded
+    config.after_initialize do
+      JetstreamBridge::Rails::Integration.boot_bridge!
+    end
+
+    # Add console helper methods
+    console do
+      ::Rails.logger.info "[JetStream Bridge] Loaded v#{JetstreamBridge::VERSION}"
+      ::Rails.logger.info '[JetStream Bridge] Console helpers available:'
+      ::Rails.logger.info '  JetstreamBridge.health_check     - Check connection status'
+      ::Rails.logger.info '  JetstreamBridge.stream_info      - View stream details'
+      ::Rails.logger.info '  JetstreamBridge.connected?       - Check if connected'
+      ::Rails.logger.info '  JetstreamBridge.shutdown!        - Gracefully disconnect'
+      ::Rails.logger.info '  JetstreamBridge.reconnect!       - Reconnect (useful after configuration changes)'
+    end
+
+    # Load rake tasks
+    rake_tasks do
+      load File.expand_path('../tasks/install.rake', __dir__)
+    end
+
+    # Add generators
+    generators do
+      require 'generators/jetstream_bridge/health_check/health_check_generator'
+    end
+  end
+end

data/lib/jetstream_bridge/rails.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Entry point for Rails-specific integration (lifecycle helpers + railtie)
+require_relative 'rails/integration'
+require_relative 'rails/railtie' if defined?(Rails::Railtie)

data/lib/jetstream_bridge/tasks/install.rake

@@ -85,7 +85,7 @@ namespace :jetstream_bridge do
     puts '[jetstream_bridge] Testing NATS connection...'
 
     begin
-      jts = JetstreamBridge.ensure_topology!
+      jts = JetstreamBridge.connect_and_ensure_stream!
       puts '✓ Successfully connected to NATS'
       puts '✓ JetStream is available'
       puts '✓ Stream topology ensured'

data/lib/jetstream_bridge/test_helpers/fixtures.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module JetstreamBridge
+  module TestHelpers
+    # Common fixtures for quickly building events in specs.
+    module Fixtures
+      module_function
+
+      # Build a user.created event
+      def user_created_event(attrs = {})
+        JetstreamBridge::TestHelpers.build_jetstream_event(
+          event_type: 'user.created',
+          payload: {
+            id: attrs[:id] || 1,
+            email: attrs[:email] || 'test@example.com',
+            name: attrs[:name] || 'Test User'
+          }.merge(attrs[:payload] || {})
+        )
+      end
+
+      # Build multiple sample events
+      def sample_events(count = 3, type: 'test.event')
+        Array.new(count) do |i|
+          JetstreamBridge::TestHelpers.build_jetstream_event(
+            event_type: type,
+            payload: { id: i + 1, sequence: i }
+          )
+        end
+      end
+
+      # Build a generic event with custom attributes
+      def event(event_type:, payload: {}, **attrs)
+        JetstreamBridge::TestHelpers.build_jetstream_event(
+          event_type: event_type,
+          payload: payload,
+          **attrs
+        )
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/test_helpers/integration_helpers.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module JetstreamBridge
+  module TestHelpers
+    # Integration helpers to exercise the mock NATS storage end-to-end.
+    module IntegrationHelpers
+      # Publish an event and wait for it to appear in mock storage
+      #
+      # @param event_attrs [Hash] Event attributes to publish
+      # @param timeout [Integer] Maximum seconds to wait
+      # @return [Models::PublishResult] Publish result
+      # @raise [Timeout::Error] If event doesn't appear within timeout
+      def publish_and_wait(timeout: 1, **event_attrs)
+        result = JetstreamBridge.publish(**event_attrs)
+
+        deadline = Time.now + timeout
+        until Time.now > deadline
+          storage = JetstreamBridge::TestHelpers.mock_storage
+          break if storage.messages.any? { |m| m[:header]['nats-msg-id'] == result.event_id }
+
+          sleep 0.01
+        end
+
+        result
+      end
+
+      # Consume events from mock storage
+      #
+      # @param batch_size [Integer] Number of events to consume
+      # @yield [event] Block to handle each event
+      # @return [Array<Hash>] Consumed events
+      def consume_events(batch_size: 10, &handler)
+        storage = JetstreamBridge::TestHelpers.mock_storage
+        messages = storage.messages.first(batch_size)
+
+        messages.each do |msg|
+          event = JetstreamBridge::Models::Event.from_nats_message(
+            OpenStruct.new(
+              subject: msg[:subject],
+              data: msg[:data],
+              header: msg[:header],
+              metadata: OpenStruct.new(
+                sequence: OpenStruct.new(stream: msg[:sequence]),
+                num_delivered: msg[:delivery_count],
+                stream: 'test-stream',
+                consumer: 'test-consumer'
+              )
+            )
+          )
+
+          handler&.call(event)
+          JetstreamBridge::TestHelpers.record_consumed_event(event.to_h)
+        end
+
+        JetstreamBridge::TestHelpers.consumed_events
+      end
+
+      # Wait for a specific number of messages in mock storage
+      #
+      # @param count [Integer] Expected message count
+      # @param timeout [Integer] Maximum seconds to wait
+      # @return [Boolean] true if count reached, false if timeout
+      def wait_for_messages(count, timeout: 2)
+        deadline = Time.now + timeout
+        storage = JetstreamBridge::TestHelpers.mock_storage
+
+        until Time.now > deadline
+          return true if storage.messages.size >= count
+
+          sleep 0.01
+        end
+
+        false
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/test_helpers/matchers.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module JetstreamBridge
+  module TestHelpers
+    # RSpec matchers for asserting publish outcomes and captured events.
+    module Matchers
+      # Matcher for checking if an event was published
+      #
+      # @param event_type [String] Event type to match
+      # @param payload [Hash] Optional payload attributes to match
+      # @return [HavePublished] Matcher instance
+      def have_published(event_type:, payload: {})
+        HavePublished.new(event_type, payload)
+      end
+
+      # Matcher implementation for have_published
+      class HavePublished
+        def initialize(event_type, payload_attributes)
+          @event_type = event_type
+          @payload_attributes = payload_attributes
+        end
+
+        def matches?(_actual)
+          TestHelpers.published_events.any? do |event|
+            matches_event_type?(event) && matches_payload?(event)
+          end
+        end
+
+        def failure_message
+          "expected to have published event_type: #{@event_type.inspect} " \
+            "with payload: #{@payload_attributes.inspect}\n" \
+            "but found events: #{TestHelpers.published_events.map { |e| e['event_type'] }.inspect}"
+        end
+
+        def failure_message_when_negated
+          "expected not to have published event_type: #{@event_type.inspect} " \
+            "with payload: #{@payload_attributes.inspect}"
+        end
+
+        private
+
+        def matches_event_type?(event)
+          event['event_type'] == @event_type || event[:event_type] == @event_type
+        end
+
+        def matches_payload?(event)
+          payload = event['payload'] || event[:payload] || {}
+          @payload_attributes.all? do |key, value|
+            payload_value = payload[key.to_s] || payload[key.to_sym]
+            if value.is_a?(RSpec::Matchers::BuiltIn::BaseMatcher)
+              value.matches?(payload)
+            else
+              payload_value == value
+            end
+          end
+        end
+      end
+
+      # Matcher for checking publish result success
+      def be_publish_success
+        BePublishSuccess.new
+      end
+
+      class BePublishSuccess
+        def matches?(actual)
+          actual.respond_to?(:success?) && actual.success?
+        end
+
+        def failure_message
+          'expected PublishResult to be successful but it failed'
+        end
+
+        def failure_message_when_negated
+          'expected PublishResult to not be successful but it was'
+        end
+      end
+
+      # Matcher for checking publish result failure
+      def be_publish_failure
+        BePublishFailure.new
+      end
+
+      class BePublishFailure
+        def matches?(actual)
+          actual.respond_to?(:failure?) && actual.failure?
+        end
+
+        def failure_message
+          'expected PublishResult to be a failure but it succeeded'
+        end
+
+        def failure_message_when_negated
+          'expected PublishResult to not be a failure but it was'
+        end
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/test_helpers.rb

@@ -2,6 +2,9 @@
 
 require 'securerandom'
 require_relative 'test_helpers/mock_nats'
+require_relative 'test_helpers/matchers'
+require_relative 'test_helpers/fixtures'
+require_relative 'test_helpers/integration_helpers'
 
 module JetstreamBridge
   # Test helpers for easier testing of JetStream Bridge integrations
@@ -210,6 +213,7 @@ module JetstreamBridge
         }
       )
     end
+    module_function :build_jetstream_event
 
     # Simulate triggering an event to a consumer
     #
@@ -228,265 +232,6 @@ module JetstreamBridge
       TestHelpers.record_consumed_event(event.to_h) if TestHelpers.test_mode?
       handler.call(event)
     end
-
-    # RSpec matchers module
-    #
-    # @example Include in RSpec
-    #   RSpec.configure do |config|
-    #     config.include JetstreamBridge::TestHelpers
-    #     config.include JetstreamBridge::TestHelpers::Matchers
-    #   end
-    #
-    module Matchers
-      # Matcher for checking if an event was published
-      #
-      # @param event_type [String] Event type to match
-      # @param payload [Hash] Optional payload attributes to match
-      # @return [HavePublished] Matcher instance
-      #
-      # @example
-      #   expect(JetstreamBridge).to have_published(
-      #     event_type: "user.created",
-      #     payload: { id: 1 }
-      #   )
-      #
-      def have_published(event_type:, payload: {})
-        HavePublished.new(event_type, payload)
-      end
-
-      # Matcher implementation for have_published
-      class HavePublished
-        def initialize(event_type, payload_attributes)
-          @event_type = event_type
-          @payload_attributes = payload_attributes
-        end
-
-        def matches?(_actual)
-          TestHelpers.published_events.any? do |event|
-            matches_event_type?(event) && matches_payload?(event)
-          end
-        end
-
-        def failure_message
-          "expected to have published event_type: #{@event_type.inspect} " \
-            "with payload: #{@payload_attributes.inspect}\n" \
-            "but found events: #{TestHelpers.published_events.map { |e| e['event_type'] }.inspect}"
-        end
-
-        def failure_message_when_negated
-          "expected not to have published event_type: #{@event_type.inspect} " \
-            "with payload: #{@payload_attributes.inspect}"
-        end
-
-        private
-
-        def matches_event_type?(event)
-          event['event_type'] == @event_type || event[:event_type] == @event_type
-        end
-
-        def matches_payload?(event)
-          payload = event['payload'] || event[:payload] || {}
-          @payload_attributes.all? do |key, value|
-            payload_value = payload[key.to_s] || payload[key.to_sym]
-            if value.is_a?(RSpec::Matchers::BuiltIn::BaseMatcher)
-              value.matches?(payload)
-            else
-              payload_value == value
-            end
-          end
-        end
-      end
-
-      # Matcher for checking publish result
-      #
-      # @example
-      #   result = JetstreamBridge.publish(...)
-      #   expect(result).to be_publish_success
-      #
-      def be_publish_success
-        BePublishSuccess.new
-      end
-
-      # Matcher implementation for be_publish_success
-      class BePublishSuccess
-        def matches?(actual)
-          actual.respond_to?(:success?) && actual.success?
-        end
-
-        def failure_message
-          'expected PublishResult to be successful but it failed'
-        end
-
-        def failure_message_when_negated
-          'expected PublishResult to not be successful but it was'
-        end
-      end
-
-      # Matcher for checking publish failure
-      #
-      # @example
-      #   result = JetstreamBridge.publish(...)
-      #   expect(result).to be_publish_failure
-      #
-      def be_publish_failure
-        BePublishFailure.new
-      end
-
-      # Matcher implementation for be_publish_failure
-      class BePublishFailure
-        def matches?(actual)
-          actual.respond_to?(:failure?) && actual.failure?
-        end
-
-        def failure_message
-          'expected PublishResult to be a failure but it succeeded'
-        end
-
-        def failure_message_when_negated
-          'expected PublishResult to not be a failure but it was'
-        end
-      end
-    end
-
-    # Test fixtures for common event scenarios
-    #
-    # @example Create a user.created event
-    #   event = JetstreamBridge::TestHelpers::Fixtures.user_created_event(id: 123)
-    #
-    module Fixtures
-      # Build a user.created event
-      #
-      # @param attrs [Hash] Event attributes
-      # @option attrs [Integer] :id User ID
-      # @option attrs [String] :email User email
-      # @option attrs [String] :name User name
-      # @option attrs [Hash] :payload Additional payload data
-      # @return [Models::Event] Event object
-      def self.user_created_event(attrs = {})
-        build_jetstream_event(
-          event_type: 'user.created',
-          payload: {
-            id: attrs[:id] || 1,
-            email: attrs[:email] || 'test@example.com',
-            name: attrs[:name] || 'Test User'
-          }.merge(attrs[:payload] || {})
-        )
-      end
-
-      # Build multiple sample events
-      #
-      # @param count [Integer] Number of events to create
-      # @param type [String] Event type
-      # @return [Array<Models::Event>] Array of event objects
-      def self.sample_events(count = 3, type: 'test.event')
-        Array.new(count) do |i|
-          build_jetstream_event(
-            event_type: type,
-            payload: { id: i + 1, sequence: i }
-          )
-        end
-      end
-
-      # Build a generic event with custom attributes
-      #
-      # @param event_type [String] Event type
-      # @param payload [Hash] Event payload
-      # @param attrs [Hash] Additional event attributes
-      # @return [Models::Event] Event object
-      def self.event(event_type:, payload: {}, **attrs)
-        build_jetstream_event(
-          event_type: event_type,
-          payload: payload,
-          **attrs
-        )
-      end
-
-      # Helper method to build events
-      # @private
-      def self.build_jetstream_event(event_type:, payload:, event_id: nil, trace_id: nil, occurred_at: nil, **metadata)
-        # Delegate to main module method to avoid duplication
-        TestHelpers.build_jetstream_event(
-          event_type: event_type,
-          payload: payload,
-          event_id: event_id,
-          trace_id: trace_id,
-          occurred_at: occurred_at,
-          **metadata
-        )
-      end
-    end
-
-    # Integration test helpers for end-to-end testing
-    module IntegrationHelpers
-      # Publish an event and wait for it to appear in mock storage
-      #
-      # @param event_attrs [Hash] Event attributes to publish
-      # @param timeout [Integer] Maximum seconds to wait
-      # @return [Models::PublishResult] Publish result
-      # @raise [Timeout::Error] If event doesn't appear within timeout
-      def publish_and_wait(event_attrs, timeout: 1)
-        result = JetstreamBridge.publish(**event_attrs)
-
-        deadline = Time.now + timeout
-        until Time.now > deadline
-          storage = JetstreamBridge::TestHelpers.mock_storage
-          break if storage.messages.any? { |m| m[:header]['nats-msg-id'] == result.event_id }
-
-          sleep 0.01
-        end
-
-        result
-      end
-
-      # Consume events from mock storage
-      #
-      # @param batch_size [Integer] Number of events to consume
-      # @yield [event] Block to handle each event
-      # @return [Array<Hash>] Consumed events
-      def consume_events(batch_size: 10, &handler)
-        storage = JetstreamBridge::TestHelpers.mock_storage
-        messages = storage.messages.first(batch_size)
-
-        messages.each do |msg|
-          event = JetstreamBridge::Models::Event.from_nats_message(
-            OpenStruct.new(
-              subject: msg[:subject],
-              data: msg[:data],
-              header: msg[:header],
-              metadata: OpenStruct.new(
-                sequence: OpenStruct.new(stream: msg[:sequence]),
-                num_delivered: msg[:delivery_count],
-                stream: 'test-stream',
-                consumer: 'test-consumer'
-              )
-            )
-          )
-
-          handler&.call(event)
-          JetstreamBridge::TestHelpers.record_consumed_event(event.to_h)
-        end
-
-        JetstreamBridge::TestHelpers.consumed_events
-      end
-
-      # Wait for a specific number of messages in mock storage
-      #
-      # @param count [Integer] Expected message count
-      # @param timeout [Integer] Maximum seconds to wait
-      # @return [Boolean] true if count reached, false if timeout
-      def wait_for_messages(count, timeout: 2)
-        deadline = Time.now + timeout
-        storage = JetstreamBridge::TestHelpers.mock_storage
-
-        until Time.now > deadline
-          return true if storage.messages.size >= count
-
-          sleep 0.01
-        end
-
-        false
-      end
-    end
   end
 end
 

data/lib/jetstream_bridge/topology/stream.rb

@@ -79,7 +79,7 @@ module JetstreamBridge
     def log_retention_mismatch(name, have:, want:)
       Logging.warn(
         "Stream #{name} retention mismatch (have=#{have.inspect}, want=#{want.inspect}). " \
-        "Retention is immutable; skipping retention change.",
+        'Retention is immutable; skipping retention change.',
         tag: 'JetstreamBridge::Stream'
       )
     end

data/lib/jetstream_bridge/version.rb

@@ -4,5 +4,5 @@
 #
 # Version constant for the gem.
 module JetstreamBridge
-  VERSION = '4.1.0'
+  VERSION = '4.2.0'
 end