jetstream_bridge 2.9.0 → 3.0.0

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
@@ -123,9 +133,7 @@ module JetstreamBridge
 
         # Retention is immutable; warn if different and do not include on update.
         have_ret = info.config.retention.to_s.downcase
-        if have_ret != RETENTION
-          StreamSupport.log_retention_mismatch(name, have: have_ret, want: RETENTION)
-        end
+        StreamSupport.log_retention_mismatch(name, have: have_ret, want: RETENTION) if have_ret != RETENTION
 
         # Storage can be updated; do it without passing retention.
         have_storage = info.config.storage.to_s.downcase

data/lib/jetstream_bridge/topology/subject_matcher.rb

@@ -48,20 +48,30 @@ module JetstreamBridge
       while ai < a_parts.length && bi < b_parts.length
         at = a_parts[ai]
         bt = b_parts[bi]
-        return true if at == '>' || bt == '>'
-        return false unless at == bt || at == '*' || bt == '*'
+        return true if tail?(at, bt)
+        return false unless token_match?(at, bt)
 
         ai += 1
         bi += 1
       end
 
-      # If any side still has a '>' remaining, it can absorb the other's remainder
-      a_tail = a_parts[ai..] || []
-      b_tail = b_parts[bi..] || []
+      tail_overlap?(a_parts[ai..], b_parts[bi..])
+    end
+
+    def tail?(a_token, b_token)
+      a_token == '>' || b_token == '>'
+    end
+
+    def token_match?(a_token, b_token)
+      a_token == b_token || a_token == '*' || b_token == '*'
+    end
+
+    def tail_overlap?(a_tail, b_tail)
+      a_tail ||= []
+      b_tail ||= []
       return true if a_tail.include?('>') || b_tail.include?('>')
 
-      # Otherwise they overlap only if both consumed exactly
-      ai == a_parts.length && bi == b_parts.length
+      a_tail.empty? && b_tail.empty?
     end
   end
 end

data/lib/jetstream_bridge/topology/topology.rb

@@ -14,7 +14,7 @@ module JetstreamBridge
 
       Logging.info(
         "Subjects ready: producer=#{cfg.source_subject}, consumer=#{cfg.destination_subject}. " \
-          "Counterpart publishes on #{cfg.destination_subject} and subscribes on #{cfg.source_subject}.",
+        "Counterpart publishes on #{cfg.destination_subject} and subscribes on #{cfg.source_subject}.",
         tag: 'JetstreamBridge::Topology'
       )
     end

data/lib/jetstream_bridge/version.rb

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

data/lib/jetstream_bridge.rb

@@ -15,7 +15,6 @@ require_relative 'jetstream_bridge/railtie' if defined?(Rails::Railtie)
 require_relative 'jetstream_bridge/inbox_event'
 require_relative 'jetstream_bridge/outbox_event'
 
-
 # JetstreamBridge main module.
 module JetstreamBridge
   class << self
@@ -54,15 +53,73 @@ module JetstreamBridge
       Connection.jetstream
     end
 
-    # @deprecated Use {ensure_topology!} instead. This method will be removed
-    #   in a future version.
-    def ensure_topology?
-      Logging.warn('ensure_topology? is deprecated; use ensure_topology! instead', tag: 'JetstreamBridge')
-      !!ensure_topology!
+    # 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.9.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Mike Attara
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-25 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
@@ -83,23 +121,26 @@ files:
 - lib/generators/jetstream_bridge/migrations/templates/create_jetstream_inbox_events.rb.erb
 - lib/generators/jetstream_bridge/migrations/templates/create_jetstream_outbox_events.rb.erb
 - lib/jetstream_bridge.rb
-- lib/jetstream_bridge/consumer/backoff_strategy.rb
 - lib/jetstream_bridge/consumer/consumer.rb
-- lib/jetstream_bridge/consumer/consumer_config.rb
 - lib/jetstream_bridge/consumer/dlq_publisher.rb
 - lib/jetstream_bridge/consumer/inbox/inbox_message.rb
 - lib/jetstream_bridge/consumer/inbox/inbox_processor.rb
 - lib/jetstream_bridge/consumer/inbox/inbox_repository.rb
-- lib/jetstream_bridge/consumer/message_context.rb
 - lib/jetstream_bridge/consumer/message_processor.rb
 - 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
@@ -119,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:
@@ -129,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: []

data/lib/jetstream_bridge/consumer/backoff_strategy.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module JetstreamBridge
-  class BackoffStrategy
-    TRANSIENT_ERRORS = [Timeout::Error, IOError].freeze
-    MAX_EXPONENT     = 6
-    MAX_DELAY        = 60
-    MIN_DELAY        = 1
-
-    # Returns a bounded delay in seconds
-    def delay(deliveries, error)
-      base = transient?(error) ? 0.5 : 2.0
-      power = [deliveries - 1, MAX_EXPONENT].min
-      raw = (base * (2**power)).to_i
-      raw.clamp(MIN_DELAY, MAX_DELAY)
-    end
-
-    private
-
-    def transient?(error)
-      TRANSIENT_ERRORS.any? { |k| error.is_a?(k) }
-    end
-  end
-end

data/lib/jetstream_bridge/consumer/consumer_config.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-require_relative '../core/duration'
-require_relative '../core/config'
-require_relative '../core/logging'
-
-module JetstreamBridge
-  # Consumer configuration helpers.
-  module ConsumerConfig
-    module_function
-
-    # Complete consumer config (pre-provisioned durable, pull mode).
-    def consumer_config(durable, filter_subject)
-      {
-        durable_name: durable,
-        filter_subject: filter_subject,
-        ack_policy: 'explicit',
-        deliver_policy: 'all',
-        max_deliver: JetstreamBridge.config.max_deliver,
-        ack_wait: Duration.to_millis(JetstreamBridge.config.ack_wait),
-        backoff: Array(JetstreamBridge.config.backoff)
-          .map { |d| Duration.to_millis(d) }
-      }
-    end
-  end
-end

data/lib/jetstream_bridge/consumer/message_context.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-require 'securerandom'
-
-module JetstreamBridge
-  # Immutable per-message metadata
-  MessageContext = Struct.new(
-    :event_id, :deliveries, :subject, :seq, :consumer, :stream,
-    keyword_init: true
-  ) do
-    def self.build(msg)
-      new(
-        event_id: msg.header&.[]('nats-msg-id') || SecureRandom.uuid,
-        deliveries: msg.metadata&.num_delivered.to_i,
-        subject: msg.subject,
-        seq: msg.metadata&.sequence,
-        consumer: msg.metadata&.consumer,
-        stream: msg.metadata&.stream
-      )
-    end
-  end
-end