jetstream_bridge 2.10.0 → 3.0.0

data/lib/jetstream_bridge/publisher/outbox_repository.rb

@@ -11,52 +11,71 @@ module JetstreamBridge
     end
 
     def find_or_build(event_id)
-      ModelUtils.find_or_init_by_best(
+      record = ModelUtils.find_or_init_by_best(
         @klass,
         { event_id: event_id },
         { dedup_key: event_id } # fallback if app uses a different unique column
       )
+
+      # Lock the row to prevent concurrent processing
+      if record.persisted? && !record.new_record? && record.respond_to?(:lock!)
+        begin
+          record.lock!
+        rescue ActiveRecord::RecordNotFound
+          # Record was deleted between find and lock, create new
+          record = @klass.new
+        end
+      end
+
+      record
     end
 
     def already_sent?(record)
-      record.respond_to?(:sent_at) && record.sent_at
+      (record.respond_to?(:sent_at) && record.sent_at) ||
+        (record.respond_to?(:status) && record.status == 'sent')
     end
 
     def persist_pre(record, subject, envelope)
-      now      = Time.now.utc
-      event_id = envelope['event_id'].to_s
+      ActiveRecord::Base.transaction do
+        now      = Time.now.utc
+        event_id = envelope['event_id'].to_s
 
-      attrs = {
-        event_id: event_id,
-        subject: subject,
-        payload: ModelUtils.json_dump(envelope),
-        headers: ModelUtils.json_dump({ 'nats-msg-id' => event_id }),
-        status: 'publishing',
-        last_error: nil
-      }
-      attrs[:attempts] = 1 + (record.attempts || 0) if record.respond_to?(:attempts)
-      attrs[:enqueued_at] = (record.enqueued_at || now) if record.respond_to?(:enqueued_at)
-      attrs[:updated_at] = now if record.respond_to?(:updated_at)
+        attrs = {
+          event_id: event_id,
+          subject: subject,
+          payload: ModelUtils.json_dump(envelope),
+          headers: ModelUtils.json_dump({ 'nats-msg-id' => event_id }),
+          status: 'publishing',
+          last_error: nil
+        }
+        attrs[:attempts] = 1 + (record.attempts || 0) if record.respond_to?(:attempts)
+        attrs[:enqueued_at] = (record.enqueued_at || now) if record.respond_to?(:enqueued_at)
+        attrs[:updated_at] = now if record.respond_to?(:updated_at)
 
-      ModelUtils.assign_known_attrs(record, attrs)
-      record.save!
+        ModelUtils.assign_known_attrs(record, attrs)
+        record.save!
+      end
     end
 
     def persist_success(record)
-      now = Time.now.utc
-      attrs = { status: 'sent' }
-      attrs[:sent_at] = now if record.respond_to?(:sent_at)
-      attrs[:updated_at] = now if record.respond_to?(:updated_at)
-      ModelUtils.assign_known_attrs(record, attrs)
-      record.save!
+      ActiveRecord::Base.transaction do
+        now = Time.now.utc
+        attrs = { status: 'sent' }
+        attrs[:sent_at] = now if record.respond_to?(:sent_at)
+        attrs[:updated_at] = now if record.respond_to?(:updated_at)
+        ModelUtils.assign_known_attrs(record, attrs)
+        record.save!
+      end
     end
 
     def persist_failure(record, message)
-      now = Time.now.utc
-      attrs = { status: 'failed', last_error: message }
-      attrs[:updated_at] = now if record.respond_to?(:updated_at)
-      ModelUtils.assign_known_attrs(record, attrs)
-      record.save!
+      ActiveRecord::Base.transaction do
+        now = Time.now.utc
+        attrs = { status: 'failed', last_error: message }
+        attrs[:updated_at] = now if record.respond_to?(:updated_at)
+        ModelUtils.assign_known_attrs(record, attrs)
+        record.save!
+      end
     end
 
     def persist_exception(record, error)

data/lib/jetstream_bridge/publisher/publisher.rb

@@ -6,22 +6,15 @@ require_relative '../core/connection'
 require_relative '../core/logging'
 require_relative '../core/config'
 require_relative '../core/model_utils'
+require_relative '../core/retry_strategy'
 require_relative 'outbox_repository'
 
 module JetstreamBridge
   # Publishes to "{env}.{app}.sync.{dest}".
   class Publisher
-    DEFAULT_RETRIES = 2
-    RETRY_BACKOFFS  = [0.25, 1.0].freeze
-
-    TRANSIENT_ERRORS = begin
-      errs = [NATS::IO::Timeout, NATS::IO::Error]
-      errs << NATS::IO::SocketTimeoutError if defined?(NATS::IO::SocketTimeoutError)
-      errs.freeze
-    end
-
-    def initialize
+    def initialize(retry_strategy: nil)
       @jts = Connection.connect!
+      @retry_strategy = retry_strategy || PublisherRetryStrategy.new
     end
 
     # @return [Boolean]
@@ -33,7 +26,7 @@ module JetstreamBridge
       if JetstreamBridge.config.use_outbox
         publish_via_outbox(subject, envelope)
       else
-        with_retries { do_publish?(subject, envelope) }
+        with_retries { publish_to_nats(subject, envelope) }
       end
     rescue StandardError => e
       log_error(false, e)
@@ -47,7 +40,7 @@ module JetstreamBridge
       raise ArgumentError, 'destination_app must be configured'
     end
 
-    def do_publish?(subject, envelope)
+    def publish_to_nats(subject, envelope)
       headers = { 'nats-msg-id' => envelope['event_id'] }
 
       ack = @jts.publish(subject, Oj.dump(envelope, mode: :compat), header: headers)
@@ -76,7 +69,7 @@ module JetstreamBridge
           "Outbox model #{klass} is not an ActiveRecord model; publishing directly.",
           tag: 'JetstreamBridge::Publisher'
         )
-        return with_retries { do_publish?(subject, envelope) }
+        return with_retries { publish_to_nats(subject, envelope) }
       end
 
       repo     = OutboxRepository.new(klass)
@@ -93,7 +86,7 @@ module JetstreamBridge
 
       repo.persist_pre(record, subject, envelope)
 
-      ok = with_retries { do_publish?(subject, envelope) }
+      ok = with_retries { publish_to_nats(subject, envelope) }
       ok ? repo.persist_success(record) : repo.persist_failure(record, 'Publish returned false')
       ok
     rescue StandardError => e
@@ -102,27 +95,11 @@ module JetstreamBridge
     end
     # ---- /Outbox path ----
 
-    # Retry only on transient NATS IO errors
-    def with_retries(retries = DEFAULT_RETRIES)
-      attempts = 0
-      begin
-        yield
-      rescue *TRANSIENT_ERRORS => e
-        attempts += 1
-        return log_error(false, e) if attempts > retries
-
-        backoff(attempts, e)
-        retry
-      end
-    end
-
-    def backoff(attempts, error)
-      delay = RETRY_BACKOFFS[attempts - 1] || RETRY_BACKOFFS.last
-      Logging.warn(
-        "Publish retry #{attempts} after #{error.class}: #{error.message}",
-        tag: 'JetstreamBridge::Publisher'
-      )
-      sleep delay
+    # Retry using strategy pattern
+    def with_retries
+      @retry_strategy.execute(context: 'Publisher') { yield }
+    rescue RetryStrategy::RetryExhausted => e
+      log_error(false, e)
     end
 
     def log_error(val, exc)

data/lib/jetstream_bridge/railtie.rb

@@ -1,17 +1,51 @@
 # frozen_string_literal: true
 
 require_relative 'core/model_codec_setup'
+require_relative 'core/logging'
 
 module JetstreamBridge
   class Railtie < ::Rails::Railtie
-    initializer 'jetstream_bridge.defer_model_tweaks' do
+    # Set up logger to use Rails.logger by default
+    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 in development/test
+    initializer 'jetstream_bridge.validate_config', after: :load_config_initializers do |app|
+      if Rails.env.development? || Rails.env.test?
+        app.config.after_initialize do
+          begin
+            JetstreamBridge.config.validate! if JetstreamBridge.config.destination_app
+          rescue JetstreamBridge::ConfigurationError => e
+            Rails.logger.warn "[JetStream Bridge] Configuration warning: #{e.message}"
+          end
+        end
+      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"
+    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/tasks/install.rake

@@ -7,4 +7,103 @@ namespace :jetstream_bridge do
     Rails::Generators.invoke('jetstream_bridge:install', [], behavior: :invoke, destination_root: Rails.root.to_s)
     puts '[jetstream_bridge] Done.'
   end
+
+  desc 'Check health and connection status'
+  task health: :environment do
+    require 'json'
+
+    puts '=' * 70
+    puts 'JetStream Bridge Health Check'
+    puts '=' * 70
+
+    health = JetstreamBridge.health_check
+
+    puts "\nStatus: #{health[:healthy] ? '✓ HEALTHY' : '✗ UNHEALTHY'}"
+    puts "NATS Connected: #{health[:nats_connected] ? 'Yes' : 'No'}"
+    puts "Connected At: #{health[:connected_at] || 'N/A'}"
+    puts "Version: #{health[:version]}"
+
+    if health[:stream]
+      puts "\nStream:"
+      puts "  Name: #{health[:stream][:name]}"
+      puts "  Exists: #{health[:stream][:exists] ? 'Yes' : 'No'}"
+      if health[:stream][:subjects]
+        puts "  Subjects: #{health[:stream][:subjects].join(', ')}"
+        puts "  Messages: #{health[:stream][:messages]}"
+      end
+      puts "  Error: #{health[:stream][:error]}" if health[:stream][:error]
+    end
+
+    if health[:config]
+      puts "\nConfiguration:"
+      puts "  Environment: #{health[:config][:env]}"
+      puts "  App Name: #{health[:config][:app_name]}"
+      puts "  Destination: #{health[:config][:destination_app] || 'NOT SET'}"
+      puts "  Outbox: #{health[:config][:use_outbox] ? 'Enabled' : 'Disabled'}"
+      puts "  Inbox: #{health[:config][:use_inbox] ? 'Enabled' : 'Disabled'}"
+      puts "  DLQ: #{health[:config][:use_dlq] ? 'Enabled' : 'Disabled'}"
+    end
+
+    if health[:error]
+      puts "\n#{' ERROR '.center(70, '=')}"
+      puts health[:error]
+    end
+
+    puts '=' * 70
+
+    exit(health[:healthy] ? 0 : 1)
+  end
+
+  desc 'Validate configuration'
+  task validate: :environment do
+    puts '[jetstream_bridge] Validating configuration...'
+
+    begin
+      JetstreamBridge.config.validate!
+      puts '✓ Configuration is valid'
+      puts "\nCurrent settings:"
+      puts "  Environment: #{JetstreamBridge.config.env}"
+      puts "  App Name: #{JetstreamBridge.config.app_name}"
+      puts "  Destination: #{JetstreamBridge.config.destination_app}"
+      puts "  Stream: #{JetstreamBridge.config.stream_name}"
+      puts "  Source Subject: #{JetstreamBridge.config.source_subject}"
+      puts "  Destination Subject: #{JetstreamBridge.config.destination_subject}"
+      exit 0
+    rescue JetstreamBridge::ConfigurationError => e
+      puts "✗ Configuration error: #{e.message}"
+      exit 1
+    end
+  end
+
+  desc 'Show debug information'
+  task debug: :environment do
+    JetstreamBridge::DebugHelper.debug_info
+  end
+
+  desc 'Test connection to NATS'
+  task test_connection: :environment do
+    puts '[jetstream_bridge] Testing NATS connection...'
+
+    begin
+      jts = JetstreamBridge.ensure_topology!
+      puts '✓ Successfully connected to NATS'
+      puts "✓ JetStream is available"
+      puts "✓ Stream topology ensured"
+
+      # Check if we can get account info
+      info = jts.account_info
+      puts "\nAccount Info:"
+      puts "  Memory: #{info.memory}"
+      puts "  Storage: #{info.storage}"
+      puts "  Streams: #{info.streams}"
+      puts "  Consumers: #{info.consumers}"
+
+      exit 0
+    rescue StandardError => e
+      puts "✗ Connection failed: #{e.message}"
+      puts "\nBacktrace:" if ENV['VERBOSE']
+      puts e.backtrace.first(10).map { |line| "  #{line}" }.join("\n") if ENV['VERBOSE']
+      exit 1
+    end
+  end
 end

data/lib/jetstream_bridge/topology/overlap_guard.rb

@@ -55,11 +55,25 @@ module JetstreamBridge
       def list_stream_names(jts)
         names  = []
         offset = 0
+        max_iterations = 100 # Safety limit to prevent infinite loops
+        iterations = 0
+
         loop do
+          iterations += 1
+          if iterations > max_iterations
+            Logging.warn(
+              "Stream listing exceeded max iterations (#{max_iterations}), returning #{names.size} streams",
+              tag: 'JetstreamBridge::OverlapGuard'
+            )
+            break
+          end
+
           resp  = js_api_request(jts, '$JS.API.STREAM.NAMES', { offset: offset })
           batch = Array(resp['streams']).filter_map { |h| h['name'] }
           names.concat(batch)
-          break if names.size >= resp['total'].to_i || batch.empty?
+          total = resp['total'].to_i
+
+          break if names.size >= total || batch.empty?
 
           offset = names.size
         end

data/lib/jetstream_bridge/topology/stream.rb

@@ -96,17 +96,27 @@ module JetstreamBridge
         raise ArgumentError, 'subjects must not be empty' if desired.empty?
 
         attempts = 0
+        max_attempts = 3
+        backoffs = [0.05, 0.2, 0.5]
+
         begin
           info = safe_stream_info(jts, name)
           info ? ensure_update(jts, name, info, desired) : ensure_create(jts, name, desired)
         rescue NATS::JetStream::Error => e
-          if StreamSupport.overlap_error?(e) && (attempts += 1) <= 1
-            Logging.warn("Overlap race while ensuring #{name}; retrying once...", tag: 'JetstreamBridge::Stream')
-            sleep(0.05)
+          if StreamSupport.overlap_error?(e) && (attempts += 1) <= max_attempts
+            backoff = backoffs[attempts - 1] || backoffs.last
+            Logging.warn(
+              "Overlap race while ensuring #{name}; retry #{attempts}/#{max_attempts} after #{backoff}s...",
+              tag: 'JetstreamBridge::Stream'
+            )
+            sleep(backoff)
             retry
           elsif StreamSupport.overlap_error?(e)
-            Logging.warn("Overlap persists ensuring #{name}; leaving unchanged. err=#{e.message.inspect}",
-                         tag: 'JetstreamBridge::Stream')
+            Logging.warn(
+              "Overlap persists ensuring #{name} after #{attempts} attempts; leaving unchanged. " \
+              "err=#{e.message.inspect}",
+              tag: 'JetstreamBridge::Stream'
+            )
             nil
           else
             raise

data/lib/jetstream_bridge/version.rb

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

data/lib/jetstream_bridge.rb

@@ -53,8 +53,73 @@ module JetstreamBridge
       Connection.jetstream
     end
 
+    # Health check for monitoring and readiness probes
+    #
+    # @return [Hash] Health status including NATS connection, stream, and version
+    def health_check
+      conn_instance = Connection.instance
+      connected = conn_instance.connected?
+      connected_at = conn_instance.connected_at
+
+      stream_info = fetch_stream_info if connected
+
+      {
+        healthy: connected && stream_info[:exists],
+        nats_connected: connected,
+        connected_at: connected_at&.iso8601,
+        stream: stream_info,
+        config: {
+          env: config.env,
+          app_name: config.app_name,
+          destination_app: config.destination_app,
+          use_outbox: config.use_outbox,
+          use_inbox: config.use_inbox,
+          use_dlq: config.use_dlq
+        },
+        version: JetstreamBridge::VERSION
+      }
+    rescue StandardError => e
+      {
+        healthy: false,
+        error: "#{e.class}: #{e.message}"
+      }
+    end
+
+    # Check if connected to NATS
+    #
+    # @return [Boolean] true if connected and healthy
+    def connected?
+      Connection.instance.connected?
+    rescue StandardError
+      false
+    end
+
+    # Get stream information for the configured stream
+    #
+    # @return [Hash] Stream information including subjects and message count
+    def stream_info
+      fetch_stream_info
+    end
+
     private
 
+    def fetch_stream_info
+      jts = Connection.jetstream
+      info = jts.stream_info(config.stream_name)
+      {
+        exists: true,
+        name: config.stream_name,
+        subjects: info.config.subjects,
+        messages: info.state.messages
+      }
+    rescue StandardError => e
+      {
+        exists: false,
+        name: config.stream_name,
+        error: "#{e.class}: #{e.message}"
+      }
+    end
+
     def assign!(cfg, key, val)
       setter = :"#{key}="
       raise ArgumentError, "Unknown configuration option: #{key}" unless cfg.respond_to?(setter)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jetstream_bridge
 version: !ruby/object:Gem::Version
-  version: 2.10.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Mike Attara
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-26 00:00:00.000000000 Z
+date: 2025-11-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -17,6 +17,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -24,6 +27,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -31,6 +37,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -38,6 +47,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: nats-pure
   requirement: !ruby/object:Gem::Requirement
@@ -59,6 +71,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.16'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -66,16 +81,39 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.16'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: mutex_m
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |-
   Publisher/Consumer utilities for NATS JetStream with environment-scoped subjects,
   overlap guards, DLQ routing, retries/backoff, and optional Inbox/Outbox patterns.
-  Includes topology setup helpers for production-safe operation.
+  Includes health checks, auto-reconnection, graceful shutdown, and topology setup
+  helpers for production-safe operation.
 email:
 - mpyebattara@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
+- README.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
 - lib/generators/jetstream_bridge/initializer/templates/jetstream_bridge.rb
 - lib/generators/jetstream_bridge/install/install_generator.rb
@@ -92,11 +130,17 @@ files:
 - lib/jetstream_bridge/consumer/subscription_manager.rb
 - lib/jetstream_bridge/core/config.rb
 - lib/jetstream_bridge/core/connection.rb
+- lib/jetstream_bridge/core/connection_factory.rb
+- lib/jetstream_bridge/core/debug_helper.rb
 - lib/jetstream_bridge/core/duration.rb
 - lib/jetstream_bridge/core/logging.rb
 - lib/jetstream_bridge/core/model_codec_setup.rb
 - lib/jetstream_bridge/core/model_utils.rb
+- lib/jetstream_bridge/core/retry_strategy.rb
+- lib/jetstream_bridge/errors.rb
 - lib/jetstream_bridge/inbox_event.rb
+- lib/jetstream_bridge/models/event_envelope.rb
+- lib/jetstream_bridge/models/subject.rb
 - lib/jetstream_bridge/outbox_event.rb
 - lib/jetstream_bridge/publisher/outbox_repository.rb
 - lib/jetstream_bridge/publisher/publisher.rb
@@ -116,8 +160,8 @@ metadata:
   changelog_uri: https://github.com/attaradev/jetstream_bridge/blob/main/CHANGELOG.md
   documentation_uri: https://github.com/attaradev/jetstream_bridge#readme
   bug_tracker_uri: https://github.com/attaradev/jetstream_bridge/issues
-  github_repo: ssh://github.com/attaradev/jetstream_bridge
   rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -126,15 +170,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.3.0
+      version: '0'
 requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: Reliable realtime bridge over NATS JetStream for Rails/Ruby apps
+summary: Production-safe realtime data bridge using NATS JetStream
 test_files: []