jetstream_bridge 4.1.0 → 4.3.0

data/lib/jetstream_bridge.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'jetstream_bridge/version'
-require_relative 'jetstream_bridge/core/config'
-require_relative 'jetstream_bridge/core/duration'
-require_relative 'jetstream_bridge/core/logging'
-require_relative 'jetstream_bridge/core/connection'
+require_relative 'jetstream_bridge/core'
 require_relative 'jetstream_bridge/publisher/publisher'
 require_relative 'jetstream_bridge/publisher/batch_publisher'
 require_relative 'jetstream_bridge/consumer/consumer'
@@ -12,8 +9,8 @@ require_relative 'jetstream_bridge/consumer/middleware'
 require_relative 'jetstream_bridge/models/publish_result'
 require_relative 'jetstream_bridge/models/event'
 
-# If you have a Railtie for tasks/eager-loading
-require_relative 'jetstream_bridge/railtie' if defined?(Rails::Railtie)
+# Rails-specific entry point (lifecycle helpers + Railtie)
+require_relative 'jetstream_bridge/rails' if defined?(Rails::Railtie)
 
 # Load gem-provided models from lib/
 require_relative 'jetstream_bridge/models/inbox_event'
@@ -34,7 +31,7 @@ require_relative 'jetstream_bridge/models/outbox_event'
 # - Graceful startup/shutdown lifecycle management
 #
 # @example Quick start
-#   # Configure (automatically starts connection)
+#   # Configure
 #   JetstreamBridge.configure do |config|
 #     config.nats_urls = "nats://localhost:4222"
 #     config.env = "development"
@@ -44,6 +41,9 @@ require_relative 'jetstream_bridge/models/outbox_event'
 #     config.use_inbox = true
 #   end
 #
+#   # Explicitly start connection (or use Rails railtie for automatic startup)
+#   JetstreamBridge.startup!
+#
 #   # Publish events
 #   JetstreamBridge.publish(
 #     event_type: "user.created",
@@ -66,17 +66,17 @@ require_relative 'jetstream_bridge/models/outbox_event'
 #
 module JetstreamBridge
   class << self
+    include Core::BridgeHelpers
+
     def config
       @config ||= Config.new
     end
 
-    # Configure JetStream Bridge settings and establish connection
-    #
-    # This method sets configuration and immediately establishes a connection
-    # to NATS, providing fail-fast behavior during application startup.
-    # If NATS is unavailable, the application will fail to start.
+    # Configure JetStream Bridge settings
     #
-    # Set config.lazy_connect = true to defer connection until first use.
+    # This method sets configuration WITHOUT automatically establishing a connection.
+    # Connection must be established explicitly via startup! or will be established
+    # automatically on first use (publish/subscribe) or via Rails railtie initialization.
     #
     # @example Basic configuration
     #   JetstreamBridge.configure do |config|
@@ -84,38 +84,29 @@ module JetstreamBridge
     #     config.app_name = "my_app"
     #     config.destination_app = "worker"
     #   end
+    #   JetstreamBridge.startup!  # Explicitly start connection
     #
     # @example With hash overrides
     #   JetstreamBridge.configure(env: 'production', app_name: 'my_app')
     #
-    # @example Lazy connection (defer until first use)
-    #   JetstreamBridge.configure do |config|
-    #     config.nats_urls = "nats://localhost:4222"
-    #     config.lazy_connect = true
-    #   end
-    #
     # @param overrides [Hash] Configuration key-value pairs to set
     # @yield [Config] Configuration object for block-based configuration
     # @return [Config] The configured instance
-    # @raise [ConnectionError] If connection to NATS fails (unless lazy_connect is true)
     def configure(overrides = {}, **extra_overrides)
       # Merge extra keyword arguments into overrides hash
       all_overrides = overrides.nil? ? extra_overrides : overrides.merge(extra_overrides)
 
       cfg = config
-      all_overrides.each { |k, v| assign!(cfg, k, v) } unless all_overrides.empty?
+      all_overrides.each { |k, v| assign_config_option!(cfg, k, v) } unless all_overrides.empty?
       yield(cfg) if block_given?
 
-      # Establish connection immediately for fail-fast behavior (unless lazy_connect is true)
-      startup! unless cfg.lazy_connect
-
       cfg
     end
 
-    # Configure with a preset and establish connection
+    # Configure with a preset
     #
-    # This method applies a configuration preset and immediately establishes
-    # a connection to NATS, providing fail-fast behavior.
+    # This method applies a configuration preset. Connection must be
+    # established separately via startup! or via Rails railtie.
     #
     # @example
     #   JetstreamBridge.configure_for(:production) do |config|
@@ -123,11 +114,11 @@ module JetstreamBridge
     #     config.app_name = "my_app"
     #     config.destination_app = "worker"
     #   end
+    #   JetstreamBridge.startup!  # Explicitly start connection
     #
     # @param preset [Symbol] Preset name (:development, :test, :production, etc.)
     # @yield [Config] Configuration object
     # @return [Config] Configured instance
-    # @raise [ConnectionError] If connection to NATS fails
     def configure_for(preset)
       configure do |cfg|
         cfg.apply_preset(preset)
@@ -142,18 +133,37 @@ module JetstreamBridge
 
     # Initialize the JetStream Bridge connection and topology
     #
-    # This method is called automatically by `configure`, but can be called
-    # explicitly if needed. It's idempotent and safe to call multiple times.
+    # This method can be called explicitly if needed. It's idempotent and safe to call multiple times.
     #
     # @return [void]
     def startup!
       return if @connection_initialized
 
-      Connection.connect!
+      connect_and_ensure_stream!
       @connection_initialized = true
       Logging.info('JetStream Bridge started successfully', tag: 'JetstreamBridge')
     end
 
+    # Reconnect to NATS
+    #
+    # Closes existing connection and establishes a new one. Useful for:
+    # - Forking web servers (Puma, Unicorn) after worker boot
+    # - Recovering from connection issues
+    # - Configuration changes that require reconnection
+    #
+    # @example In Puma configuration (config/puma.rb)
+    #   on_worker_boot do
+    #     JetstreamBridge.reconnect! if defined?(JetstreamBridge)
+    #   end
+    #
+    # @return [void]
+    # @raise [ConnectionError] If unable to reconnect to NATS
+    def reconnect!
+      Logging.info('Reconnecting to NATS...', tag: 'JetstreamBridge')
+      shutdown! if @connection_initialized
+      startup!
+    end
+
     # Gracefully shutdown the JetStream Bridge connection
     #
     # Closes the NATS connection and cleans up resources. Should be called
@@ -189,9 +199,16 @@ module JetstreamBridge
     # Establishes a connection and ensures stream topology.
     #
     # @return [Object] JetStream context
-    def ensure_topology!
+    def connect_and_ensure_stream!
       Connection.connect!
-      Connection.jetstream
+      jts = Connection.jetstream
+      Topology.ensure!(jts)
+      jts
+    end
+
+    # Backwards-compatible alias for the previous method name
+    def ensure_topology!
+      connect_and_ensure_stream!
     end
 
     # Active health check for monitoring and readiness probes
@@ -283,6 +300,8 @@ module JetstreamBridge
 
     # Convenience method to publish events
     #
+    # Automatically establishes connection on first use if not already connected.
+    #
     # Supports three usage patterns:
     #
     # 1. Structured parameters (recommended):
@@ -310,6 +329,7 @@ module JetstreamBridge
     #     logger.error("Publish failed: #{result.error}")
     #   end
     def publish(event_or_hash = nil, resource_type: nil, event_type: nil, payload: nil, subject: nil, **)
+      connect_if_needed!
       publisher = Publisher.new
       publisher.publish(event_or_hash, resource_type: resource_type, event_type: event_type, payload: payload,
                                        subject: subject, **)
@@ -354,6 +374,8 @@ module JetstreamBridge
 
     # Convenience method to start consuming messages
     #
+    # Automatically establishes connection on first use if not already connected.
+    #
     # Supports two usage patterns:
     #
     # 1. With a block (recommended):
@@ -380,6 +402,7 @@ module JetstreamBridge
     # @yield [event] Yields Models::Event object to block
     # @return [Consumer, Thread] Consumer instance or Thread if run: true
     def subscribe(handler = nil, run: false, durable_name: nil, batch_size: nil, &block)
+      connect_if_needed!
       handler ||= block
       raise ArgumentError, 'Handler or block required' unless handler
 
@@ -393,69 +416,5 @@ module JetstreamBridge
         consumer
       end
     end
-
-    private
-
-    # Enforce rate limit on uncached health checks to prevent abuse
-    # Max 1 uncached request per 5 seconds per process
-    def enforce_health_check_rate_limit!
-      @health_check_mutex ||= Mutex.new
-      @health_check_mutex.synchronize do
-        now = Time.now
-        if @last_uncached_health_check
-          time_since = now - @last_uncached_health_check
-          if time_since < 5
-            raise HealthCheckFailedError,
-                  "Health check rate limit exceeded. Please wait #{(5 - time_since).ceil} second(s)"
-          end
-        end
-        @last_uncached_health_check = now
-      end
-    end
-
-    def fetch_stream_info
-      jts = Connection.jetstream
-      info = jts.stream_info(config.stream_name)
-
-      # Handle both object-style and hash-style access for compatibility
-      config_data = info.config
-      state_data = info.state
-      subjects = config_data.respond_to?(:subjects) ? config_data.subjects : config_data[:subjects]
-      messages = state_data.respond_to?(:messages) ? state_data.messages : state_data[:messages]
-
-      {
-        exists: true,
-        name: config.stream_name,
-        subjects: subjects,
-        messages: messages
-      }
-    rescue StandardError => e
-      {
-        exists: false,
-        name: config.stream_name,
-        error: "#{e.class}: #{e.message}"
-      }
-    end
-
-    def measure_nats_rtt
-      # Measure round-trip time using NATS RTT method
-      nc = Connection.nc
-      start = Time.now
-      nc.rtt
-      ((Time.now - start) * 1000).round(2)
-    rescue StandardError => e
-      Logging.warn(
-        "Failed to measure NATS RTT: #{e.class} #{e.message}",
-        tag: 'JetstreamBridge'
-      )
-      nil
-    end
-
-    def assign!(cfg, key, val)
-      setter = :"#{key}="
-      raise ArgumentError, "Unknown configuration option: #{key}" unless cfg.respond_to?(setter)
-
-      cfg.public_send(setter, val)
-    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jetstream_bridge
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.3.0
 platform: ruby
 authors:
 - Mike Attara
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-23 00:00:00.000000000 Z
+date: 2025-11-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -105,19 +105,25 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '4.0'
 description: |-
-  Publisher/Consumer utilities for NATS JetStream with environment-scoped subjects,
-  overlap guards, DLQ routing, retries/backoff, and optional Inbox/Outbox patterns.
-  Includes health checks, auto-reconnection, graceful shutdown, and topology setup
-  helpers for production-safe operation.
+  Production-ready publishers/consumers for NATS JetStream with environment-scoped
+  subjects, overlap guards, DLQ routing, retries/backoff, and optional inbox/outbox
+  patterns. Includes health checks, auto-reconnection, graceful shutdown, topology
+  setup helpers, and Rails generators.
 email:
 - mpyebattara@gmail.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
+- CHANGELOG.md
+- docs/GETTING_STARTED.md
 files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- docs/GETTING_STARTED.md
+- docs/PRODUCTION.md
+- docs/TESTING.md
 - lib/generators/jetstream_bridge/health_check/health_check_generator.rb
 - lib/generators/jetstream_bridge/health_check/templates/health_controller.rb
 - lib/generators/jetstream_bridge/initializer/initializer_generator.rb
@@ -135,6 +141,8 @@ files:
 - lib/jetstream_bridge/consumer/message_processor.rb
 - lib/jetstream_bridge/consumer/middleware.rb
 - lib/jetstream_bridge/consumer/subscription_manager.rb
+- lib/jetstream_bridge/core.rb
+- lib/jetstream_bridge/core/bridge_helpers.rb
 - lib/jetstream_bridge/core/config.rb
 - lib/jetstream_bridge/core/config_preset.rb
 - lib/jetstream_bridge/core/connection.rb
@@ -155,9 +163,14 @@ files:
 - lib/jetstream_bridge/publisher/batch_publisher.rb
 - lib/jetstream_bridge/publisher/outbox_repository.rb
 - lib/jetstream_bridge/publisher/publisher.rb
-- lib/jetstream_bridge/railtie.rb
+- lib/jetstream_bridge/rails.rb
+- lib/jetstream_bridge/rails/integration.rb
+- lib/jetstream_bridge/rails/railtie.rb
 - lib/jetstream_bridge/tasks/install.rake
 - lib/jetstream_bridge/test_helpers.rb
+- lib/jetstream_bridge/test_helpers/fixtures.rb
+- lib/jetstream_bridge/test_helpers/integration_helpers.rb
+- lib/jetstream_bridge/test_helpers/matchers.rb
 - lib/jetstream_bridge/test_helpers/mock_nats.rb
 - lib/jetstream_bridge/topology/overlap_guard.rb
 - lib/jetstream_bridge/topology/stream.rb

data/lib/jetstream_bridge/railtie.rb

@@ -1,91 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'core/model_codec_setup'
-require_relative 'core/logging'
-
-module JetstreamBridge
-  # Rails integration for JetStream Bridge.
-  #
-  # This Railtie integrates JetStream Bridge with the Rails application lifecycle:
-  # - Startup: Connection is established when Rails initializers run (via configure)
-  # - 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: configure() will call startup! which establishes the connection
-    initializer 'jetstream_bridge.logger', before: :initialize_logger do
-      JetstreamBridge.configure do |config|
-        config.logger ||= Rails.logger if defined?(Rails.logger)
-      end
-    end
-
-    # Load ActiveRecord model tweaks after ActiveRecord is loaded
-    initializer 'jetstream_bridge.active_record', after: 'active_record.initialize_database' do
-      ActiveSupport.on_load(:active_record) do
-        ActiveSupport::Reloader.to_prepare { JetstreamBridge::ModelCodecSetup.apply! }
-      end
-    end
-
-    # Validate configuration and setup environment-specific behavior
-    initializer 'jetstream_bridge.setup', after: :load_config_initializers do |app|
-      app.config.after_initialize do
-        # Validate configuration in development/test
-        if Rails.env.development? || Rails.env.test?
-          begin
-            JetstreamBridge.config.validate! if JetstreamBridge.config.destination_app
-          rescue JetstreamBridge::ConfigurationError => e
-            Rails.logger.warn "[JetStream Bridge] Configuration warning: #{e.message}"
-          end
-        end
-
-        # Auto-enable test mode in test environment if NATS_URLS not set
-        if Rails.env.test? && ENV['NATS_URLS'].blank? && !(defined?(JetstreamBridge::TestHelpers) &&
-                 JetstreamBridge::TestHelpers.respond_to?(:test_mode?) &&
-                 JetstreamBridge::TestHelpers.test_mode?)
-          Rails.logger.info '[JetStream Bridge] Auto-enabling test mode (NATS_URLS not set)'
-          require_relative 'test_helpers'
-          JetstreamBridge::TestHelpers.enable_test_mode!
-        end
-
-        # Log helpful connection info in development
-        if Rails.env.development? && JetstreamBridge.connected?
-          conn_state = JetstreamBridge::Connection.instance.state
-          Rails.logger.info "[JetStream Bridge] Connection state: #{conn_state}"
-          Rails.logger.info "[JetStream Bridge] Connected to: #{JetstreamBridge.config.nats_urls}"
-          Rails.logger.info "[JetStream Bridge] Stream: #{JetstreamBridge.config.stream_name}"
-          Rails.logger.info "[JetStream Bridge] Publishing to: #{JetstreamBridge.config.source_subject}"
-          Rails.logger.info "[JetStream Bridge] Consuming from: #{JetstreamBridge.config.destination_subject}"
-        end
-      rescue StandardError => e
-        # Don't fail app initialization for logging errors
-        Rails.logger.debug "[JetStream Bridge] Setup logging skipped: #{e.message}"
-      end
-    end
-
-    # Register shutdown hook for graceful cleanup
-    # This runs when Rails shuts down (Ctrl+C, SIGTERM, etc.)
-    config.after_initialize do
-      at_exit do
-        JetstreamBridge.shutdown!
-      end
-    end
-
-    # Add console helper methods
-    console do
-      Rails.logger.info "[JetStream Bridge] Loaded v#{JetstreamBridge::VERSION}"
-      Rails.logger.info '[JetStream Bridge] Use JetstreamBridge.health_check to check status'
-      Rails.logger.info '[JetStream Bridge] Use JetstreamBridge.shutdown! to gracefully disconnect'
-    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