jetstream_bridge 4.0.2 → 4.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa4616ea064fcf04741b61ed07981980f47944e4cae10624605e5b5aed990990
-  data.tar.gz: 5eacc8c962149d70e1b6b8dc05588fd6b568dbc6112cbf04eaa70895d0d3969f
+  metadata.gz: 3d2af28b3492eb97a04b9337390f71f90786321baf7c50f3f49de3a2cbe1b5c3
+  data.tar.gz: 3746cb676e9739a087c295488d85b51a6acec82c4ffca81027726cf33a9ada53
 SHA512:
-  metadata.gz: 16f82dca9bc584f85b01ec9fc5934980c2ffd6be87a8eaa8691af5fb8902ce7c737eaf5ee638d41b0a62396870f4d51d9b0684015a959893b4c9c2677b6ae84b
-  data.tar.gz: db6b1268c39dfe997ad95f805c9a2553655e75cb2004cc78c1ed09968797ce7a9668a1e6bbe24fa1c98877b5bb9986cce21e4da7212297a947b2c554e30fb876
+  metadata.gz: 91cff40e1f076eaee83bf937d10cbbcaaaf0e311fabb347e3ae757d7e7bd0645bcea338cd222cbfcb9d42c37deefd88076d618af2185572ca4cdeb4fa85dea27
+  data.tar.gz: 5fc680881fb91c550b8f6561babfd2227a3a9e263d3c07f1bd89a0de61fd835a8bf74b0731603384a16f078b401f22afbdbf31e94d62bac88ed1473f8c0aa15b

data/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.4] - 2025-11-23
+
+### Fixed
+
+- **NATS Compatibility** - Fix connection failure with nats-pure 2.5.0
+  - Handle both object-style and hash-style access for stream_info responses
+  - Fixes "undefined method 'streams' for Hash" error during connection establishment
+  - Adds compatibility checks using `respond_to?` for config and state attributes
+  - Updated 4 files: jetstream_bridge.rb, topology/stream.rb, topology/overlap_guard.rb, debug_helper.rb
+  - Maintains backward compatibility with older nats-pure versions
+
+## [4.0.3] - 2025-11-23
+
+### Added
+
+- **Connection Validation** - Comprehensive NATS URL validation on initialization
+  - Validates URL format, scheme (nats/nats+tls), host presence, and port range (1-65535)
+  - Verifies NATS connection established after connect
+  - Verifies JetStream availability with account info check
+  - Helpful error messages for common misconfigurations
+  - All validation errors include specific guidance for fixes
+
+- **Connection Logging** - Detailed logging throughout connection lifecycle
+  - Debug logs for URL validation progress and verification steps
+  - Info logs for successful validation and JetStream stats (streams, consumers, memory, storage)
+  - Error logs for all validation failures with specific details
+  - Automatic credential sanitization in all log messages
+  - Human-readable resource usage formatting (bytes to KB/MB/GB)
+
+### Fixed
+
+- **Health Check** - Fixed `healthy` field returning `nil` instead of `false` when disconnected
+  - Changed `stream_info[:exists]` to `stream_info&.fetch(:exists, false)` for proper nil handling
+  - Ensures boolean values always returned for monitoring systems
+
+### Changed
+
+- **Code Organization** - Moved all inline RuboCop rules to centralized `.rubocop.yml`
+  - Removed inline comments from 5 files (logging.rb, model_utils.rb, inbox_event.rb, outbox_event.rb, inbox_message.rb)
+  - Added exclusions to `.rubocop.yml` for metrics and naming rules
+  - Cleaner codebase with all style exceptions in one location
+
 ## [4.0.2] - 2025-11-23
 
 ### Fixed

data/lib/jetstream_bridge/consumer/inbox/inbox_message.rb

@@ -8,7 +8,6 @@ module JetstreamBridge
   class InboxMessage
     attr_reader :msg, :seq, :deliveries, :stream, :subject, :headers, :body, :raw, :event_id, :now
 
-    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def self.from_nats(msg)
       meta       = (msg.respond_to?(:metadata) && msg.metadata) || nil
       seq        = meta.respond_to?(:stream_sequence) ? meta.stream_sequence : nil
@@ -33,9 +32,7 @@ module JetstreamBridge
 
       new(msg, seq, deliveries, stream, subject, headers, body, raw, id, Time.now.utc, consumer)
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
-    # rubocop:disable Metrics/ParameterLists
     def initialize(msg, seq, deliveries, stream, subject, headers, body, raw, event_id, now, consumer = nil)
       @msg        = msg
       @seq        = seq
@@ -49,7 +46,6 @@ module JetstreamBridge
       @now        = now
       @consumer   = consumer
     end
-    # rubocop:enable Metrics/ParameterLists
 
     def body_for_store
       body.empty? ? raw : body

data/lib/jetstream_bridge/core/connection.rb

@@ -34,6 +34,8 @@ module JetstreamBridge
       connect_timeout: 5
     }.freeze
 
+    VALID_NATS_SCHEMES = %w[nats nats+tls].freeze
+
     class << self
       # Thread-safe delegator to the singleton instance.
       # Returns a live JetStream context.
@@ -106,11 +108,14 @@ module JetstreamBridge
     end
 
     def nats_servers
-      JetstreamBridge.config.nats_urls
-                     .to_s
-                     .split(',')
-                     .map(&:strip)
-                     .reject(&:empty?)
+      servers = JetstreamBridge.config.nats_urls
+                               .to_s
+                               .split(',')
+                               .map(&:strip)
+                               .reject(&:empty?)
+
+      validate_nats_urls!(servers)
+      servers
     end
 
     def establish_connection(servers)
@@ -141,9 +146,15 @@ module JetstreamBridge
 
       @nc.connect({ servers: servers }.merge(DEFAULT_CONN_OPTS))
 
+      # Verify connection is established
+      verify_connection!
+
       # Create JetStream context
       @jts = @nc.jetstream
 
+      # Verify JetStream is available
+      verify_jetstream!
+
       # Ensure JetStream responds to #nc
       return if @jts.respond_to?(:nc)
 
@@ -151,6 +162,129 @@ module JetstreamBridge
       @jts.define_singleton_method(:nc) { nc_ref }
     end
 
+    def validate_nats_urls!(servers)
+      Logging.debug(
+        "Validating #{servers.size} NATS URL(s): #{sanitize_urls(servers).join(', ')}",
+        tag: 'JetstreamBridge::Connection'
+      )
+
+      servers.each do |url|
+        # Check for basic URL format (scheme://host)
+        unless url.include?('://')
+          Logging.error(
+            "Invalid URL format (missing scheme): #{url}",
+            tag: 'JetstreamBridge::Connection'
+          )
+          raise ConnectionError, "Invalid NATS URL format: #{url}. Expected format: nats://host:port"
+        end
+
+        uri = URI.parse(url)
+
+        # Validate scheme
+        scheme = uri.scheme&.downcase
+        unless VALID_NATS_SCHEMES.include?(scheme)
+          Logging.error(
+            "Invalid URL scheme '#{uri.scheme}': #{Logging.sanitize_url(url)}",
+            tag: 'JetstreamBridge::Connection'
+          )
+          raise ConnectionError, "Invalid NATS URL scheme '#{uri.scheme}' in: #{url}. Expected 'nats' or 'nats+tls'"
+        end
+
+        # Validate host is present
+        if uri.host.nil? || uri.host.empty?
+          Logging.error(
+            "Missing host in URL: #{Logging.sanitize_url(url)}",
+            tag: 'JetstreamBridge::Connection'
+          )
+          raise ConnectionError, "Invalid NATS URL - missing host: #{url}"
+        end
+
+        # Validate port if present
+        if uri.port && (uri.port < 1 || uri.port > 65_535)
+          Logging.error(
+            "Invalid port #{uri.port} in URL: #{Logging.sanitize_url(url)}",
+            tag: 'JetstreamBridge::Connection'
+          )
+          raise ConnectionError, "Invalid NATS URL - port must be 1-65535: #{url}"
+        end
+
+        Logging.debug(
+          "URL validated: #{Logging.sanitize_url(url)}",
+          tag: 'JetstreamBridge::Connection'
+        )
+      rescue URI::InvalidURIError => e
+        Logging.error(
+          "Malformed URL: #{url} (#{e.message})",
+          tag: 'JetstreamBridge::Connection'
+        )
+        raise ConnectionError, "Invalid NATS URL format: #{url} (#{e.message})"
+      end
+
+      Logging.info(
+        'All NATS URLs validated successfully',
+        tag: 'JetstreamBridge::Connection'
+      )
+    end
+
+    def verify_connection!
+      Logging.debug(
+        'Verifying NATS connection...',
+        tag: 'JetstreamBridge::Connection'
+      )
+
+      unless @nc.connected?
+        Logging.error(
+          'NATS connection verification failed - client not connected',
+          tag: 'JetstreamBridge::Connection'
+        )
+        raise ConnectionError, 'Failed to establish connection to NATS server(s)'
+      end
+
+      Logging.info(
+        'NATS connection verified successfully',
+        tag: 'JetstreamBridge::Connection'
+      )
+    end
+
+    def verify_jetstream!
+      Logging.debug(
+        'Verifying JetStream availability...',
+        tag: 'JetstreamBridge::Connection'
+      )
+
+      # Verify JetStream is enabled by checking account info
+      account_info = @jts.account_info
+
+      Logging.info(
+        "JetStream verified - Streams: #{account_info.streams}, " \
+        "Consumers: #{account_info.consumers}, " \
+        "Memory: #{format_bytes(account_info.memory)}, " \
+        "Storage: #{format_bytes(account_info.storage)}",
+        tag: 'JetstreamBridge::Connection'
+      )
+    rescue NATS::IO::NoRespondersError
+      Logging.error(
+        'JetStream not available - no responders (JetStream not enabled)',
+        tag: 'JetstreamBridge::Connection'
+      )
+      raise ConnectionError, 'JetStream not enabled on NATS server. Please enable JetStream with -js flag'
+    rescue StandardError => e
+      Logging.error(
+        "JetStream verification failed: #{e.class} - #{e.message}",
+        tag: 'JetstreamBridge::Connection'
+      )
+      raise ConnectionError, "JetStream verification failed: #{e.message}"
+    end
+
+    def format_bytes(bytes)
+      return 'N/A' if bytes.nil? || bytes.zero?
+
+      units = %w[B KB MB GB TB]
+      exp = (Math.log(bytes) / Math.log(1024)).to_i
+      exp = [exp, units.length - 1].min
+      "#{(bytes / (1024.0**exp)).round(2)} #{units[exp]}"
+    end
+
     def refresh_jetstream_context
       @jts = @nc.jetstream
       nc_ref = @nc

data/lib/jetstream_bridge/core/debug_helper.rb

@@ -81,18 +81,7 @@ module JetstreamBridge
         cfg = JetstreamBridge.config
         info = jts.stream_info(cfg.stream_name)
 
-        {
-          name: cfg.stream_name,
-          exists: true,
-          subjects: info.config.subjects,
-          retention: info.config.retention,
-          storage: info.config.storage,
-          max_consumers: info.config.max_consumers,
-          messages: info.state.messages,
-          bytes: info.state.bytes,
-          first_seq: info.state.first_seq,
-          last_seq: info.state.last_seq
-        }
+        build_stream_info(cfg, info)
       rescue StandardError => e
         {
           name: JetstreamBridge.config.stream_name,
@@ -101,6 +90,29 @@ module JetstreamBridge
         }
       end
 
+      def build_stream_info(cfg, info)
+        # Handle both object-style and hash-style access for compatibility
+        config_data = info.config
+        state_data = info.state
+
+        {
+          name: cfg.stream_name,
+          exists: true,
+          subjects: safe_attr(config_data, :subjects),
+          retention: safe_attr(config_data, :retention),
+          storage: safe_attr(config_data, :storage),
+          max_consumers: safe_attr(config_data, :max_consumers),
+          messages: safe_attr(state_data, :messages),
+          bytes: safe_attr(state_data, :bytes),
+          first_seq: safe_attr(state_data, :first_seq),
+          last_seq: safe_attr(state_data, :last_seq)
+        }
+      end
+
+      def safe_attr(obj, attr)
+        obj.respond_to?(attr) ? obj.public_send(attr) : obj[attr]
+      end
+
       def log_hash(hash, indent: 0)
         prefix = ' ' * indent
         hash.each do |key, value|

data/lib/jetstream_bridge/core/logging.rb

@@ -40,7 +40,6 @@ module JetstreamBridge
       log(:error, msg, tag: tag)
     end
 
-    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def sanitize_url(url)
       uri = URI.parse(url)
       return url unless uri.user || uri.password
@@ -67,6 +66,5 @@ module JetstreamBridge
         "#{scheme}://#{masked}@"
       end
     end
-    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
   end
 end

data/lib/jetstream_bridge/core/model_utils.rb

@@ -14,13 +14,11 @@ module JetstreamBridge
       defined?(ActiveRecord::Base) && klass <= ActiveRecord::Base
     end
 
-    # rubocop:disable Naming/PredicatePrefix
     def has_columns?(klass, *cols)
       return false unless ar_class?(klass)
 
       cols.flatten.all? { |c| klass.column_names.include?(c.to_s) }
     end
-    # rubocop:enable Naming/PredicatePrefix
 
     def assign_known_attrs(record, attrs)
       attrs.each do |k, v|

data/lib/jetstream_bridge/models/inbox_event.rb

@@ -15,7 +15,6 @@ 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?
 
@@ -23,7 +22,6 @@ module JetstreamBridge
         rescue ActiveRecord::ConnectionNotEstablished, ActiveRecord::NoDatabaseError
           false
         end
-        # rubocop:enable Naming/PredicatePrefix
 
         def ar_connected?
           ActiveRecord::Base.connected? && connection_pool.active_connection?

data/lib/jetstream_bridge/models/outbox_event.rb

@@ -15,7 +15,6 @@ 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?
 
@@ -23,7 +22,6 @@ 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.

data/lib/jetstream_bridge/topology/overlap_guard.rb

@@ -48,7 +48,10 @@ module JetstreamBridge
       def list_streams_with_subjects(jts)
         list_stream_names(jts).map do |name|
           info = jts.stream_info(name)
-          { name: name, subjects: Array(info.config.subjects || []) }
+          # Handle both object-style and hash-style access for compatibility
+          config_data = info.config
+          subjects = config_data.respond_to?(:subjects) ? config_data.subjects : config_data[:subjects]
+          { name: name, subjects: Array(subjects || []) }
         end
       end
 

data/lib/jetstream_bridge/topology/stream.rb

@@ -127,11 +127,15 @@ module JetstreamBridge
       private
 
       def ensure_update(jts, name, info, desired_subjects)
-        existing = StreamSupport.normalize_subjects(info.config.subjects || [])
+        # Handle both object-style and hash-style access for compatibility
+        config_data = info.config
+        subjects = config_data.respond_to?(:subjects) ? config_data.subjects : config_data[:subjects]
+        existing = StreamSupport.normalize_subjects(subjects || [])
         to_add   = StreamSupport.missing_subjects(existing, desired_subjects)
 
         # Retention is immutable; if different, skip all updates to avoid 10052 error.
-        have_ret = info.config.retention.to_s.downcase
+        retention = config_data.respond_to?(:retention) ? config_data.retention : config_data[:retention]
+        have_ret = retention.to_s.downcase
         if have_ret != RETENTION
           StreamSupport.log_retention_mismatch(name, have: have_ret, want: RETENTION)
           return
@@ -140,7 +144,8 @@ module JetstreamBridge
         add_subjects(jts, name, existing, to_add) if to_add.any?
 
         # Storage can be updated; do it without passing retention.
-        have_storage = info.config.storage.to_s.downcase
+        storage = config_data.respond_to?(:storage) ? config_data.storage : config_data[:storage]
+        have_storage = storage.to_s.downcase
         if have_storage != STORAGE
           apply_update(jts, name, existing, storage: STORAGE)
           StreamSupport.log_config_updated(name, storage: STORAGE)

data/lib/jetstream_bridge/version.rb

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

data/lib/jetstream_bridge.rb

@@ -115,21 +115,39 @@ module JetstreamBridge
       Connection.jetstream
     end
 
-    # Health check for monitoring and readiness probes
+    # Active health check for monitoring and readiness probes
+    #
+    # Performs actual operations to verify system health:
+    # - Checks NATS connection (active: calls account_info API)
+    # - Verifies stream exists and is accessible (active: queries stream info)
+    # - Tests NATS round-trip communication (active: RTT measurement)
     #
     # @return [Hash] Health status including NATS connection, stream, and version
     def health_check
+      start_time = Time.now
       conn_instance = Connection.instance
+
+      # Active check: calls @jts.account_info internally
       connected = conn_instance.connected?
       connected_at = conn_instance.connected_at
 
+      # Active check: queries actual stream from NATS server
       stream_info = fetch_stream_info if connected
 
+      # Active check: measure NATS round-trip time
+      rtt_ms = measure_nats_rtt if connected
+
+      health_check_duration_ms = ((Time.now - start_time) * 1000).round(2)
+
       {
-        healthy: connected && stream_info[:exists],
+        healthy: connected && stream_info&.fetch(:exists, false),
         nats_connected: connected,
         connected_at: connected_at&.iso8601,
         stream: stream_info,
+        performance: {
+          nats_rtt_ms: rtt_ms,
+          health_check_duration_ms: health_check_duration_ms
+        },
         config: {
           env: config.env,
           app_name: config.app_name,
@@ -281,11 +299,18 @@ module JetstreamBridge
     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: info.config.subjects,
-        messages: info.state.messages
+        subjects: subjects,
+        messages: messages
       }
     rescue StandardError => e
       {
@@ -295,6 +320,20 @@ module JetstreamBridge
       }
     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)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jetstream_bridge
 version: !ruby/object:Gem::Version
-  version: 4.0.2
+  version: 4.0.4
 platform: ruby
 authors:
 - Mike Attara