jetstream_bridge 4.2.0 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40f09bd9d0341dd242cbd29f7eaa4c848d180886f4e11c76ca97fca5f312e8d9
-  data.tar.gz: e2d8d22a90787f7824953c4d869ecc57e8eaebcd6948ed18a45033684dc45ce5
+  metadata.gz: 7f8e7cce25c596230a2d068e4f3aca0bfdc7d5156c9fb724e34f094e97d8909f
+  data.tar.gz: 21c66a2c19cf8e6d49017efd53dd53f7d1ae2654bac2b0df3e9f6b8d137e11e9
 SHA512:
-  metadata.gz: 0bdc25b39ba3fdd08c70795f2db348c2155951af8a88d5acbca55eac6a36850ffaa4b9cc103e8a9774080aa798ba871792a7d9604f79ef94734164b7b9bbc9f3
-  data.tar.gz: 54f528ac27f9031adbc794e4d31d7ba0d88f241dec379e063592b80a51a67cc0f3a9bb9af640a28d7d810de4686b17093ca79b3576ed48aa0198639f42fb1782
+  metadata.gz: 312c184a87c6d2b70e711c666b74f2a79a4c9d9afc29faf53776f46a906eab83e6ed2103d68e9f12e09cdb8b082c078f405769eeb13630adf998f9a498f82793
+  data.tar.gz: caeca3948e682aefb27f3de0617fba8d2558edb2c4a798ad732f16463a23a1bf586295918cb8a91cfddfef25b3b6b3df049a9ab84986b377f4da4f91080c9d67

data/CHANGELOG.md

@@ -5,6 +5,66 @@ 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.4.0] - 2025-11-24
+
+### Changed
+
+- **RTT Measurement** - Enhanced NATS round-trip time measurement with fallback support
+  - Added automatic unit normalization (seconds to milliseconds) for RTT values
+  - Implemented fallback RTT measurement using `flush` for NATS clients without native `rtt` method
+  - Supports both nats-pure and other NATS client implementations
+  - Better compatibility across different NATS client versions
+
+- **Rails Integration** - Improved Rake task detection reliability
+  - Changed from `defined?(::Rake)` check to `$PROGRAM_NAME` inspection
+  - More reliable detection of Rake execution context
+  - Prevents false positives when Rake is loaded but not executing
+
+### Fixed
+
+- **Test Coverage** - Comprehensive test suite improvements
+  - Added complete test coverage for Rails integration lifecycle methods
+  - Added tests for test helper matchers (`have_published`, `be_publish_success`, `be_publish_failure`)
+  - Added tests for fixture builders (`sample_event`, `sample_events`, `event`)
+  - Added test for RTT fallback behavior when client lacks `rtt` method
+  - Added spec file for `bridge_helpers` module
+
+## [4.3.0] - 2025-11-24
+
+### Added
+
+- **Connection Diagnostics** - Exposed reconnection error tracking for health checks
+  - `last_reconnect_error` and `last_reconnect_error_at` now publicly accessible
+  - Enables better monitoring and diagnostics of connection issues
+  - Added test coverage for diagnostic accessor visibility
+
+### Changed
+
+- **Connection Lifecycle** - Improved topology management during startup
+  - `startup!` now explicitly ensures topology is created during initialization
+  - `connect_and_ensure_stream!` properly ensures topology after connecting
+  - `fetch_stream_info` now ensures connection is established before querying
+  - More reliable initialization sequence for non-Rails applications
+
+- **Rails Integration** - Changed console autostart behavior
+  - Rails console now autostarts JetStream Bridge by default (previously skipped)
+  - Simplified autostart logic by removing console detection as skip condition
+  - Autostart remains disabled only for rake tasks (unless forced with `JETSTREAM_BRIDGE_FORCE_AUTOSTART`)
+  - Better developer experience in Rails console for immediate testing
+
+- **Documentation** - Clarified connection initialization behavior
+  - Added notes explaining that `configure` only sets options and does not connect
+  - Documented when connection actually occurs (Rails: after initialization; non-Rails: call `startup!`)
+  - Improved explanation of `lazy_connect` behavior in Rails environments
+  - Added guidance for non-Rails applications to call `startup!` explicitly
+
+### Fixed
+
+- **Test Coverage** - Added missing test scenarios
+  - Added tests for topology ensuring in `startup!` and `connect_and_ensure_stream!`
+  - Added tests for connection initialization in `stream_info`
+  - Updated Rails integration specs to reflect new console behavior
+
 ## [4.2.0] - 2025-11-24
 
 ### Added

data/README.md

@@ -54,6 +54,10 @@ JetstreamBridge.configure do |config|
   config.use_inbox  = true
   config.use_dlq    = true
 end
+
+# Note: configure only sets options; it does not connect. In Rails the Railtie
+# starts the bridge after initialization. In non-Rails apps call
+# `JetstreamBridge.startup!` (or rely on auto-connect on first publish/subscribe).
 ```
 
 Publish:

data/docs/GETTING_STARTED.md

@@ -52,9 +52,14 @@ JetstreamBridge.configure do |config|
   config.ack_wait    = "30s"
   config.backoff     = %w[1s 5s 15s 30s 60s]
 end
+
+# Note: `configure` only sets options; it does not connect. Rails will start
+# JetstreamBridge after initialization via the Railtie. For non-Rails or custom
+# boot flows, call `JetstreamBridge.startup!` (or rely on auto-connect on first
+# publish/subscribe).
 ```
 
-Rails autostart can be disabled for rake/console by `config.lazy_connect = true` or `JETSTREAM_BRIDGE_DISABLE_AUTOSTART=1`; it will connect on first publish/subscribe.
+Rails autostart runs after initialization (including in console). You can opt out for rake tasks or other tooling with `config.lazy_connect = true` or `JETSTREAM_BRIDGE_DISABLE_AUTOSTART=1`; it will then connect on first publish/subscribe.
 
 ## Publish
 

data/lib/jetstream_bridge/core/bridge_helpers.rb

@@ -37,7 +37,12 @@ module JetstreamBridge
       end
 
       def fetch_stream_info
+        # Ensure we have an active connection before querying stream info
+        connect_if_needed!
+
         jts = Connection.jetstream
+        raise ConnectionNotEstablishedError, 'NATS connection not established' unless jts
+
         info = jts.stream_info(config.stream_name)
 
         # Handle both object-style and hash-style access for compatibility
@@ -61,11 +66,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)
+        return nil unless nc
+
+        # Prefer native RTT API when available (e.g., new NATS clients)
+        if nc.respond_to?(:rtt)
+          rtt_value = normalize_ms(nc.rtt)
+          return rtt_value if rtt_value
+        end
+
+        # Fallback for clients without #rtt (nats-pure): measure ping/pong via flush
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        nc.flush(1)
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+        normalize_ms(duration)
       rescue StandardError => e
         Logging.warn(
           "Failed to measure NATS RTT: #{e.class} #{e.message}",
@@ -74,6 +88,16 @@ module JetstreamBridge
         nil
       end
 
+      def normalize_ms(value)
+        return nil if value.nil?
+        return nil unless value.respond_to?(:to_f)
+
+        numeric = value.to_f
+        # Heuristic: sub-1 values are likely seconds; convert them to ms for reporting
+        ms = numeric < 1 ? numeric * 1000 : numeric
+        ms.round(2)
+      end
+
       def assign_config_option!(cfg, key, val)
         setter = :"#{key}="
         raise ArgumentError, "Unknown configuration option: #{key}" unless cfg.respond_to?(setter)

data/lib/jetstream_bridge/core/connection.rb

@@ -135,6 +135,9 @@ module JetstreamBridge
     # @return [Time, nil] timestamp when connection was established
     attr_reader :connected_at
 
+    # Last reconnection error metadata (exposed for health checks/diagnostics)
+    attr_reader :last_reconnect_error, :last_reconnect_error_at
+
     # Get current connection state
     #
     # @return [Symbol] Current connection state (see State module)
@@ -429,10 +432,6 @@ module JetstreamBridge
       @last_health_check = Time.now.to_i
     end
 
-    # Get last reconnection error for diagnostics
-    # @return [StandardError, nil] Last error during reconnection
-    attr_reader :last_reconnect_error, :last_reconnect_error_at
-
     # Expose for class-level helpers (not part of public API)
     attr_reader :nc
 

data/lib/jetstream_bridge/rails/integration.rb

@@ -71,13 +71,12 @@ module JetstreamBridge
 
         JetstreamBridge.config.lazy_connect ||
           env_disables_autostart? ||
-          skip_autostart_for_rails_tooling?
+          rake_task?
       end
 
       def autostart_skip_reason
         return 'lazy_connect enabled' if JetstreamBridge.config.lazy_connect
         return 'JETSTREAM_BRIDGE_DISABLE_AUTOSTART set' if env_disables_autostart?
-        return 'Rails console' if rails_console?
         return 'rake task' if rake_task?
 
         'unknown'
@@ -134,11 +133,7 @@ module JetstreamBridge
       end
 
       def rake_task?
-        !!defined?(::Rake) || File.basename($PROGRAM_NAME) == 'rake'
-      end
-
-      def skip_autostart_for_rails_tooling?
-        rails_console? || rake_task?
+        File.basename($PROGRAM_NAME) == 'rake'
       end
 
       def active_logger

data/lib/jetstream_bridge/version.rb

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

data/lib/jetstream_bridge.rb

@@ -133,14 +133,13 @@ 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
@@ -202,7 +201,9 @@ module JetstreamBridge
     # @return [Object] JetStream context
     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

metadata

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