jetstream_bridge 2.9.0 → 3.0.0

data/lib/jetstream_bridge/inbox_event.rb

@@ -15,6 +15,7 @@ module JetstreamBridge
 
       class << self
         # Safe column presence check that never boots a connection during class load.
+        # rubocop:disable Naming/PredicatePrefix
         def has_column?(name)
           return false unless ar_connected?
 
@@ -22,6 +23,7 @@ module JetstreamBridge
         rescue ActiveRecord::ConnectionNotEstablished, ActiveRecord::NoDatabaseError
           false
         end
+        # rubocop:enable Naming/PredicatePrefix
 
         def ar_connected?
           ActiveRecord::Base.connected? && connection_pool.active_connection?
@@ -66,9 +68,7 @@ module JetstreamBridge
       # ---- Defaults that do not require schema at load time ----
       before_validation do
         self.status ||= 'received' if self.class.has_column?(:status) && status.blank?
-        if self.class.has_column?(:received_at) && received_at.blank?
-          self.received_at ||= Time.now.utc
-        end
+        self.received_at ||= Time.now.utc if self.class.has_column?(:received_at) && received_at.blank?
       end
 
       # ---- Helpers ----
@@ -103,7 +103,7 @@ module JetstreamBridge
           raise_missing_ar!('Inbox', method_name)
         end
 
-        def respond_to_missing?(_m, _p = false)
+        def respond_to_missing?(_method_name, _include_private = false)
           false
         end
 

data/lib/jetstream_bridge/models/event_envelope.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module JetstreamBridge
+  module Models
+    # Value object representing an event envelope
+    class EventEnvelope
+      SCHEMA_VERSION = 1
+
+      attr_reader :event_id, :schema_version, :event_type, :producer,
+                  :resource_type, :resource_id, :occurred_at, :trace_id, :payload
+
+      def initialize(
+        resource_type:,
+        event_type:,
+        payload:,
+        event_id: nil,
+        occurred_at: nil,
+        trace_id: nil,
+        producer: nil,
+        resource_id: nil
+      )
+        @event_id = event_id || SecureRandom.uuid
+        @schema_version = SCHEMA_VERSION
+        @event_type = event_type.to_s
+        @producer = producer || JetstreamBridge.config.app_name
+        @resource_type = resource_type.to_s
+        @resource_id = resource_id || extract_resource_id(payload)
+        @occurred_at = parse_occurred_at(occurred_at)
+        @trace_id = trace_id || SecureRandom.hex(8)
+        @payload = deep_freeze(payload)
+
+        validate!
+        freeze
+      end
+
+      # Convert to hash for serialization
+      def to_h
+        hash = {
+          event_id: @event_id,
+          schema_version: @schema_version,
+          event_type: @event_type,
+          producer: @producer,
+          resource_type: @resource_type,
+          occurred_at: format_time(@occurred_at),
+          payload: @payload
+        }
+
+        # Only include optional fields if they have values
+        hash[:resource_id] = @resource_id if @resource_id && !@resource_id.to_s.empty?
+        hash[:trace_id] = @trace_id if @trace_id && !@trace_id.to_s.empty?
+
+        hash
+      end
+
+      # Create from hash
+      def self.from_h(hash)
+        new(
+          event_id: hash['event_id'] || hash[:event_id],
+          event_type: hash['event_type'] || hash[:event_type],
+          producer: hash['producer'] || hash[:producer],
+          resource_type: hash['resource_type'] || hash[:resource_type],
+          resource_id: hash['resource_id'] || hash[:resource_id],
+          occurred_at: parse_time(hash['occurred_at'] || hash[:occurred_at]),
+          trace_id: hash['trace_id'] || hash[:trace_id],
+          payload: hash['payload'] || hash[:payload] || {}
+        )
+      end
+
+      def ==(other)
+        other.is_a?(EventEnvelope) && event_id == other.event_id
+      end
+
+      alias eql? ==
+
+      def hash
+        event_id.hash
+      end
+
+      private
+
+      def extract_resource_id(payload)
+        return '' unless payload.respond_to?(:[])
+
+        (payload['id'] || payload[:id]).to_s
+      end
+
+      def validate!
+        raise ArgumentError, 'event_type cannot be blank' if @event_type.empty?
+        raise ArgumentError, 'resource_type cannot be blank' if @resource_type.empty?
+        raise ArgumentError, 'payload cannot be nil' if @payload.nil?
+      end
+
+      def parse_occurred_at(value)
+        return Time.now.utc if value.nil?
+        return value if value.is_a?(Time)
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        Time.now.utc
+      end
+
+      def format_time(time)
+        time.is_a?(Time) ? time.iso8601 : time.to_s
+      end
+
+      def deep_freeze(obj)
+        case obj
+        when Hash
+          obj.each { |k, v| deep_freeze(k); deep_freeze(v) }
+          obj.freeze
+        when Array
+          obj.each { |item| deep_freeze(item) }
+          obj.freeze
+        else
+          obj.freeze if obj.respond_to?(:freeze)
+        end
+        obj
+      end
+
+      def self.parse_time(value)
+        return value if value.is_a?(Time)
+        return Time.now.utc if value.nil?
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        Time.now.utc
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/models/subject.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module JetstreamBridge
+  module Models
+    # Value object representing a NATS subject
+    class Subject
+      WILDCARD_SINGLE = '*'
+      WILDCARD_MULTI = '>'
+      SEPARATOR = '.'
+      INVALID_CHARS = /[#{Regexp.escape(WILDCARD_SINGLE + WILDCARD_MULTI + SEPARATOR)}]/.freeze
+
+      attr_reader :value, :tokens
+
+      def initialize(value)
+        @value = value.to_s
+        @tokens = @value.split(SEPARATOR)
+        validate!
+        @value.freeze
+        @tokens.freeze
+        freeze
+      end
+
+      # Factory methods
+      def self.source(env:, app_name:, dest:)
+        new("#{env}.#{app_name}.sync.#{dest}")
+      end
+
+      def self.destination(env:, source:, app_name:)
+        new("#{env}.#{source}.sync.#{app_name}")
+      end
+
+      def self.dlq(env:)
+        new("#{env}.sync.dlq")
+      end
+
+      # Check if this subject matches a pattern
+      def matches?(pattern)
+        SubjectMatcher.match?(pattern.to_s, @value)
+      end
+
+      # Check if this subject overlaps with another
+      def overlaps?(other)
+        SubjectMatcher.overlap?(@value, other.to_s)
+      end
+
+      # Check if covered by any pattern in a list
+      def covered_by?(patterns)
+        SubjectMatcher.covered?(Array(patterns).map(&:to_s), @value)
+      end
+
+      def to_s
+        @value
+      end
+
+      def ==(other)
+        other.is_a?(Subject) ? @value == other.value : @value == other.to_s
+      end
+
+      alias eql? ==
+
+      def hash
+        @value.hash
+      end
+
+      # Validate a component (env, app_name, etc.) for use in subjects
+      def self.validate_component!(value, name)
+        str = value.to_s
+        if str.match?(INVALID_CHARS)
+          raise ArgumentError,
+                "#{name} cannot contain NATS wildcards (#{SEPARATOR}, #{WILDCARD_SINGLE}, #{WILDCARD_MULTI}): #{value.inspect}"
+        end
+        raise ArgumentError, "#{name} cannot be empty" if str.strip.empty?
+
+        true
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, 'Subject cannot be empty' if @value.empty?
+        raise ArgumentError, 'Subject cannot contain only separators' if @tokens.all?(&:empty?)
+        raise ArgumentError, 'Subject has invalid format (contains spaces or special characters)' if @value.match?(/\s/)
+      end
+
+      # Lazy-load SubjectMatcher to avoid circular dependency
+      def self.subject_matcher
+        require_relative '../topology/subject_matcher' unless defined?(JetstreamBridge::SubjectMatcher)
+        JetstreamBridge::SubjectMatcher
+      end
+
+      SubjectMatcher = subject_matcher
+    end
+  end
+end

data/lib/jetstream_bridge/outbox_event.rb

@@ -15,6 +15,7 @@ module JetstreamBridge
 
       class << self
         # Safe column presence check that never boots a connection during class load.
+        # rubocop:disable Naming/PredicatePrefix
         def has_column?(name)
           return false unless ar_connected?
 
@@ -22,6 +23,7 @@ module JetstreamBridge
         rescue ActiveRecord::ConnectionNotEstablished, ActiveRecord::NoDatabaseError
           false
         end
+        # rubocop:enable Naming/PredicatePrefix
 
         def ar_connected?
           # Avoid creating a connection; rescue if pool isn't set yet.
@@ -111,7 +113,7 @@ module JetstreamBridge
           raise_missing_ar!('Outbox', method_name)
         end
 
-        def respond_to_missing?(_m, _p = false)
+        def respond_to_missing?(_method_name, _include_private = false)
           false
         end
 

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