jetstream_bridge 2.10.0 → 3.0.1

data/lib/generators/jetstream_bridge/initializer/templates/jetstream_bridge.rb

@@ -1,27 +1,72 @@
 # frozen_string_literal: true
 
-# Jetstream Bridge configuration
+# JetstreamBridge configuration
+# See https://github.com/your-org/jetstream_bridge for full documentation
+#
+# This initializer configures the JetStream Bridge gem for Rails applications.
+# The gem provides reliable, production-ready message passing between services
+# using NATS JetStream with support for outbox/inbox patterns, DLQ, and more.
 JetstreamBridge.configure do |config|
-  # NATS Connection
-  config.nats_urls       = ENV.fetch('NATS_URLS', 'nats://localhost:4222')
-  config.env             = ENV.fetch('NATS_ENV',  Rails.env)
-  config.app_name        = ENV.fetch('APP_NAME',  Rails.application.class.module_parent_name.underscore)
-  config.destination_app = ENV.fetch('DESTINATION_APP', nil) # required for cross-app data sync
+  # ============================================================================
+  # NATS Connection Settings
+  # ============================================================================
+  # NATS server URLs (comma-separated for cluster)
+  config.nats_urls = ENV.fetch('NATS_URLS', 'nats://localhost:4222')
 
-  # Consumer Tuning
+  # Environment identifier (e.g., 'development', 'production')
+  # Used in stream names and subject routing
+  config.env = ENV.fetch('NATS_ENV', Rails.env)
+
+  # Application name (used in subject routing)
+  config.app_name = ENV.fetch('APP_NAME', Rails.application.class.module_parent_name.underscore)
+
+  # Destination app for cross-app sync (REQUIRED for publishing/consuming)
+  config.destination_app = ENV.fetch('DESTINATION_APP', nil)
+
+  # ============================================================================
+  # Consumer Settings
+  # ============================================================================
+  # Maximum delivery attempts before moving message to DLQ
   config.max_deliver = 5
-  config.ack_wait    = '30s'
-  config.backoff     = %w[1s 5s 15s 30s 60s]
 
+  # How long to wait for message acknowledgment
+  config.ack_wait = '30s'
+
+  # Exponential backoff delays between retry attempts
+  config.backoff = %w[1s 5s 15s 30s 60s]
+
+  # ============================================================================
   # Reliability Features
+  # ============================================================================
+  # Enable transactional outbox pattern for guaranteed message delivery
   config.use_outbox = false
-  config.use_inbox  = false
-  config.use_dlq    = true
 
-  # Models (override if you keep custom AR classes)
+  # Enable inbox pattern for exactly-once processing (idempotency)
+  config.use_inbox = false
+
+  # Enable Dead Letter Queue for failed messages
+  config.use_dlq = true
+
+  # ============================================================================
+  # Active Record Models
+  # ============================================================================
+  # Override these if you've created custom model classes
   config.outbox_model = 'JetstreamBridge::OutboxEvent'
-  config.inbox_model  = 'JetstreamBridge::InboxEvent'
+  config.inbox_model = 'JetstreamBridge::InboxEvent'
 
+  # ============================================================================
   # Logging
+  # ============================================================================
+  # Custom logger (defaults to Rails.logger if not set)
   # config.logger = Rails.logger
 end
+
+# Validate configuration (optional but recommended for development)
+# Uncomment to enable validation on Rails boot
+# begin
+#   JetstreamBridge.config.validate!
+#   Rails.logger.info "[JetStream Bridge] Configuration validated successfully"
+# rescue JetstreamBridge::ConfigurationError => e
+#   Rails.logger.error "[JetStream Bridge] Configuration error: #{e.message}"
+#   raise if Rails.env.production?
+# end

data/lib/generators/jetstream_bridge/migrations/templates/create_jetstream_inbox_events.rb.erb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class CreateJetstreamInboxEvents < ActiveRecord::Migration[7.0]
+class CreateJetstreamInboxEvents < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     create_table :jetstream_inbox_events do |t|
       t.string   :event_id                              # preferred dedupe key

data/lib/generators/jetstream_bridge/migrations/templates/create_jetstream_outbox_events.rb.erb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class CreateJetstreamOutboxEvents < ActiveRecord::Migration[7.0]
+class CreateJetstreamOutboxEvents < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     create_table :jetstream_outbox_events do |t|
       t.string  :event_id, null: false

data/lib/jetstream_bridge/consumer/consumer.rb

@@ -27,7 +27,8 @@ module JetstreamBridge
       @durable       = durable_name || JetstreamBridge.config.durable_name
       @idle_backoff  = IDLE_SLEEP_SECS
       @running       = true
-      @jts           = Connection.connect!
+      @shutdown_requested = false
+      @jts = Connection.connect!
 
       ensure_destination!
 
@@ -36,6 +37,7 @@ module JetstreamBridge
       @inbox_proc = InboxProcessor.new(@processor) if JetstreamBridge.config.use_inbox
 
       ensure_subscription!
+      setup_signal_handlers
     end
 
     def run!
@@ -47,11 +49,17 @@ module JetstreamBridge
         processed = process_batch
         idle_sleep(processed)
       end
+
+      # Drain in-flight messages before exiting
+      drain_inflight_messages if @shutdown_requested
+      Logging.info("Consumer #{@durable} stopped gracefully", tag: 'JetstreamBridge::Consumer')
     end
 
     # Allow external callers to stop a long-running loop gracefully.
     def stop!
+      @shutdown_requested = true
       @running = false
+      Logging.info("Consumer #{@durable} shutdown requested", tag: 'JetstreamBridge::Consumer')
     end
 
     private
@@ -138,5 +146,38 @@ module JetstreamBridge
         @idle_backoff = IDLE_SLEEP_SECS
       end
     end
+
+    def setup_signal_handlers
+      %w[INT TERM].each do |sig|
+        Signal.trap(sig) do
+          Logging.info("Received #{sig}, stopping consumer...", tag: 'JetstreamBridge::Consumer')
+          stop!
+        end
+      end
+    rescue ArgumentError => e
+      # Signal handlers may not be available in all environments (e.g., threads)
+      Logging.debug("Could not set up signal handlers: #{e.message}", tag: 'JetstreamBridge::Consumer')
+    end
+
+    def drain_inflight_messages
+      return unless @psub
+
+      Logging.info('Draining in-flight messages...', tag: 'JetstreamBridge::Consumer')
+      # Process any pending messages with a short timeout
+      5.times do
+        msgs = @psub.fetch(@batch_size, timeout: 1)
+        break if msgs.nil? || msgs.empty?
+
+        msgs.each { |m| process_one(m) }
+      rescue NATS::Timeout, NATS::IO::Timeout
+        break
+      rescue StandardError => e
+        Logging.warn("Error draining messages: #{e.class} #{e.message}", tag: 'JetstreamBridge::Consumer')
+        break
+      end
+      Logging.info('Drain complete', tag: 'JetstreamBridge::Consumer')
+    rescue StandardError => e
+      Logging.error("Drain failed: #{e.class} #{e.message}", tag: 'JetstreamBridge::Consumer')
+    end
   end
 end

data/lib/jetstream_bridge/consumer/dlq_publisher.rb

@@ -11,17 +11,20 @@ module JetstreamBridge
     end
 
     # Sends original payload to DLQ with explanatory headers/context
+    # @return [Boolean] true if published successfully, false otherwise
     def publish(msg, ctx, reason:, error_class:, error_message:)
-      return unless JetstreamBridge.config.use_dlq
+      return true unless JetstreamBridge.config.use_dlq
 
       envelope = build_envelope(ctx, reason, error_class, error_message)
       headers  = build_headers(msg.header, reason, ctx.deliveries, envelope)
       @jts.publish(JetstreamBridge.config.dlq_subject, msg.data, header: headers)
+      true
     rescue StandardError => e
       Logging.error(
         "DLQ publish failed event_id=#{ctx.event_id}: #{e.class} #{e.message}",
         tag: 'JetstreamBridge::Consumer'
       )
+      false
     end
 
     private

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'oj'
+require 'securerandom'
 
 module JetstreamBridge
   # Immutable value object for a single NATS message.
@@ -27,7 +28,8 @@ module JetstreamBridge
       end
 
       id = (headers['nats-msg-id'] || body['event_id']).to_s.strip
-      id = "seq:#{seq}" if id.empty?
+      id = "seq:#{seq}" if id.empty? && seq
+      id = SecureRandom.uuid if id.to_s.empty?
 
       new(msg, seq, deliveries, stream, subject, headers, body, raw, id, Time.now.utc, consumer)
     end

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

@@ -25,45 +25,51 @@ module JetstreamBridge
     end
 
     def persist_pre(record, msg)
-      attrs = {
-        event_id: msg.event_id,
-        subject: msg.subject,
-        payload: ModelUtils.json_dump(msg.body_for_store),
-        headers: ModelUtils.json_dump(msg.headers),
-        stream: msg.stream,
-        stream_seq: msg.seq,
-        deliveries: msg.deliveries,
-        status: 'processing',
-        last_error: nil,
-        received_at: record.respond_to?(:received_at) ? (record.received_at || msg.now) : nil,
-        updated_at: record.respond_to?(:updated_at) ? msg.now : nil
-      }
-      ModelUtils.assign_known_attrs(record, attrs)
-      record.save!
+      ActiveRecord::Base.transaction do
+        attrs = {
+          event_id: msg.event_id,
+          subject: msg.subject,
+          payload: ModelUtils.json_dump(msg.body_for_store),
+          headers: ModelUtils.json_dump(msg.headers),
+          stream: msg.stream,
+          stream_seq: msg.seq,
+          deliveries: msg.deliveries,
+          status: 'processing',
+          last_error: nil,
+          received_at: record.respond_to?(:received_at) ? (record.received_at || msg.now) : nil,
+          updated_at: record.respond_to?(:updated_at) ? msg.now : nil
+        }
+        ModelUtils.assign_known_attrs(record, attrs)
+        record.save!
+      end
     end
 
     def persist_post(record)
-      now = Time.now.utc
-      attrs = {
-        status: 'processed',
-        processed_at: record.respond_to?(:processed_at) ? now : nil,
-        updated_at: record.respond_to?(:updated_at) ? now : nil
-      }
-      ModelUtils.assign_known_attrs(record, attrs)
-      record.save!
+      ActiveRecord::Base.transaction do
+        now = Time.now.utc
+        attrs = {
+          status: 'processed',
+          processed_at: record.respond_to?(:processed_at) ? now : nil,
+          updated_at: record.respond_to?(:updated_at) ? now : nil
+        }
+        ModelUtils.assign_known_attrs(record, attrs)
+        record.save!
+      end
     end
 
     def persist_failure(record, error)
       return unless record
 
-      now = Time.now.utc
-      attrs = {
-        status: 'failed',
-        last_error: "#{error.class}: #{error.message}",
-        updated_at: record.respond_to?(:updated_at) ? now : nil
-      }
-      ModelUtils.assign_known_attrs(record, attrs)
-      record.save!
+      ActiveRecord::Base.transaction do
+        now = Time.now.utc
+        attrs = {
+          status: 'failed',
+          last_error: "#{error.class}: #{error.message}",
+          updated_at: record.respond_to?(:updated_at) ? now : nil
+        }
+        ModelUtils.assign_known_attrs(record, attrs)
+        record.save!
+      end
     rescue StandardError => e
       Logging.warn("Failed to persist inbox failure: #{e.class}: #{e.message}",
                    tag: 'JetstreamBridge::Consumer')

data/lib/jetstream_bridge/consumer/message_processor.rb

@@ -63,12 +63,13 @@ module JetstreamBridge
 
       process_event(msg, event, ctx)
     rescue StandardError => e
+      backtrace = e.backtrace&.first(5)&.join("\n  ")
       Logging.error(
         "Processor crashed event_id=#{ctx&.event_id} subject=#{ctx&.subject} seq=#{ctx&.seq} " \
-        "deliveries=#{ctx&.deliveries} err=#{e.class}: #{e.message}",
+        "deliveries=#{ctx&.deliveries} err=#{e.class}: #{e.message}\n  #{backtrace}",
         tag: 'JetstreamBridge::Consumer'
       )
-      safe_nak(msg)
+      safe_nak(msg, ctx, e)
     end
 
     private
@@ -77,14 +78,22 @@ module JetstreamBridge
       data = msg.data
       Oj.load(data, mode: :strict)
     rescue Oj::ParseError => e
-      @dlq.publish(msg, ctx,
-                   reason: 'malformed_json', error_class: e.class.name, error_message: e.message)
-      msg.ack
-      Logging.warn(
-        "Malformed JSON → DLQ event_id=#{ctx.event_id} subject=#{ctx.subject} " \
-        "seq=#{ctx.seq} deliveries=#{ctx.deliveries}: #{e.message}",
-        tag: 'JetstreamBridge::Consumer'
-      )
+      dlq_success = @dlq.publish(msg, ctx,
+                                 reason: 'malformed_json', error_class: e.class.name, error_message: e.message)
+      if dlq_success
+        msg.ack
+        Logging.warn(
+          "Malformed JSON → DLQ event_id=#{ctx.event_id} subject=#{ctx.subject} " \
+          "seq=#{ctx.seq} deliveries=#{ctx.deliveries}: #{e.message}",
+          tag: 'JetstreamBridge::Consumer'
+        )
+      else
+        safe_nak(msg, ctx, e)
+        Logging.error(
+          "Malformed JSON, DLQ publish failed, NAKing event_id=#{ctx.event_id}",
+          tag: 'JetstreamBridge::Consumer'
+        )
+      end
       nil
     end
 
@@ -96,14 +105,22 @@ module JetstreamBridge
         tag: 'JetstreamBridge::Consumer'
       )
     rescue *UNRECOVERABLE_ERRORS => e
-      @dlq.publish(msg, ctx,
-                   reason: 'unrecoverable', error_class: e.class.name, error_message: e.message)
-      msg.ack
-      Logging.warn(
-        "DLQ (unrecoverable) event_id=#{ctx.event_id} subject=#{ctx.subject} " \
-        "seq=#{ctx.seq} deliveries=#{ctx.deliveries} err=#{e.class}: #{e.message}",
-        tag: 'JetstreamBridge::Consumer'
-      )
+      dlq_success = @dlq.publish(msg, ctx,
+                                 reason: 'unrecoverable', error_class: e.class.name, error_message: e.message)
+      if dlq_success
+        msg.ack
+        Logging.warn(
+          "DLQ (unrecoverable) event_id=#{ctx.event_id} subject=#{ctx.subject} " \
+          "seq=#{ctx.seq} deliveries=#{ctx.deliveries} err=#{e.class}: #{e.message}",
+          tag: 'JetstreamBridge::Consumer'
+        )
+      else
+        safe_nak(msg, ctx, e)
+        Logging.error(
+          "Unrecoverable error, DLQ publish failed, NAKing event_id=#{ctx.event_id}",
+          tag: 'JetstreamBridge::Consumer'
+        )
+      end
     rescue StandardError => e
       ack_or_nak(msg, ctx, e)
     end
@@ -111,14 +128,28 @@ module JetstreamBridge
     def ack_or_nak(msg, ctx, error)
       max_deliver = JetstreamBridge.config.max_deliver.to_i
       if ctx.deliveries >= max_deliver
-        @dlq.publish(msg, ctx,
-                     reason: 'max_deliver_exceeded', error_class: error.class.name, error_message: error.message)
-        msg.ack
-        Logging.warn(
-          "DLQ (max_deliver) event_id=#{ctx.event_id} subject=#{ctx.subject} " \
-          "seq=#{ctx.seq} deliveries=#{ctx.deliveries} err=#{error.class}: #{error.message}",
-          tag: 'JetstreamBridge::Consumer'
-        )
+        # Only ACK if DLQ publish succeeds
+        dlq_success = @dlq.publish(msg, ctx,
+                                   reason: 'max_deliver_exceeded',
+                                   error_class: error.class.name,
+                                   error_message: error.message)
+
+        if dlq_success
+          msg.ack
+          Logging.warn(
+            "DLQ (max_deliver) event_id=#{ctx.event_id} subject=#{ctx.subject} " \
+            "seq=#{ctx.seq} deliveries=#{ctx.deliveries} err=#{error.class}: #{error.message}",
+            tag: 'JetstreamBridge::Consumer'
+          )
+        else
+          # NAK to retry DLQ publish
+          safe_nak(msg, ctx, error)
+          Logging.error(
+            "DLQ publish failed at max_deliver, NAKing event_id=#{ctx.event_id} " \
+            "seq=#{ctx.seq} deliveries=#{ctx.deliveries}",
+            tag: 'JetstreamBridge::Consumer'
+          )
+        end
       else
         safe_nak(msg, ctx, error)
         Logging.warn(
@@ -129,11 +160,14 @@ module JetstreamBridge
       end
     end
 
-    def safe_nak(msg, ctx = nil, _error = nil)
-      # If your NATS client supports delayed NAKs, uncomment:
-      # delay = @backoff.delay(ctx&.deliveries.to_i, error) if ctx
-      # msg.nak(next_delivery_delay: delay)
-      msg.nak
+    def safe_nak(msg, ctx = nil, error = nil)
+      # Use backoff strategy with error context if available
+      if ctx && error && msg.respond_to?(:nak_with_delay)
+        delay = @backoff.delay(ctx.deliveries.to_i, error)
+        msg.nak_with_delay(delay)
+      else
+        msg.nak
+      end
     rescue StandardError => e
       Logging.error(
         "Failed to NAK event_id=#{ctx&.event_id} deliveries=#{ctx&.deliveries}: " \

data/lib/jetstream_bridge/core/config.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../errors'
+
 module JetstreamBridge
   class Config
     attr_accessor :destination_app, :nats_urls, :env, :app_name,
@@ -34,20 +36,53 @@ module JetstreamBridge
     # Producer publishes to:   {env}.{app}.sync.{dest}
     # Consumer subscribes to:  {env}.{dest}.sync.{app}
     def source_subject
+      validate_subject_component!(env, 'env')
+      validate_subject_component!(app_name, 'app_name')
+      validate_subject_component!(destination_app, 'destination_app')
       "#{env}.#{app_name}.sync.#{destination_app}"
     end
 
     def destination_subject
+      validate_subject_component!(env, 'env')
+      validate_subject_component!(app_name, 'app_name')
+      validate_subject_component!(destination_app, 'destination_app')
       "#{env}.#{destination_app}.sync.#{app_name}"
     end
 
     # DLQ
     def dlq_subject
+      validate_subject_component!(env, 'env')
       "#{env}.sync.dlq"
     end
 
     def durable_name
       "#{env}-#{app_name}-workers"
     end
+
+    # Validate configuration settings
+    def validate!
+      errors = []
+      errors << 'destination_app is required' if destination_app.to_s.strip.empty?
+      errors << 'nats_urls is required' if nats_urls.to_s.strip.empty?
+      errors << 'env is required' if env.to_s.strip.empty?
+      errors << 'app_name is required' if app_name.to_s.strip.empty?
+      errors << 'max_deliver must be >= 1' if max_deliver.to_i < 1
+      errors << 'backoff must be an array' unless backoff.is_a?(Array)
+      errors << 'backoff must not be empty' if backoff.is_a?(Array) && backoff.empty?
+
+      raise ConfigurationError, "Configuration errors: #{errors.join(', ')}" if errors.any?
+
+      true
+    end
+
+    private
+
+    def validate_subject_component!(value, name)
+      str = value.to_s
+      if str.match?(/[.*>]/)
+        raise InvalidSubjectError, "#{name} cannot contain NATS wildcards (., *, >): #{value.inspect}"
+      end
+      raise MissingConfigurationError, "#{name} cannot be empty" if str.strip.empty?
+    end
   end
 end

data/lib/jetstream_bridge/core/connection.rb

@@ -9,7 +9,21 @@ require_relative 'config'
 require_relative '../topology/topology'
 
 module JetstreamBridge
-  # Singleton connection to NATS.
+  # Singleton connection to NATS with thread-safe initialization.
+  #
+  # This class manages a single NATS connection for the entire application,
+  # ensuring thread-safe access in multi-threaded environments like Rails
+  # with Puma or Sidekiq.
+  #
+  # Thread Safety:
+  # - Connection initialization is synchronized with a mutex
+  # - The singleton pattern ensures only one connection instance exists
+  # - Safe to call from multiple threads/workers simultaneously
+  #
+  # Example:
+  #   # Safe from any thread
+  #   jts = JetstreamBridge::Connection.connect!
+  #   jts.publish(...)
   class Connection
     include Singleton
 
@@ -23,6 +37,10 @@ module JetstreamBridge
     class << self
       # Thread-safe delegator to the singleton instance.
       # Returns a live JetStream context.
+      #
+      # Safe to call from multiple threads - uses mutex for synchronization.
+      #
+      # @return [NATS::JetStream::JS] JetStream context
       def connect!
         @__mutex ||= Mutex.new
         @__mutex.synchronize { instance.connect! }
@@ -56,13 +74,32 @@ module JetstreamBridge
       # Ensure topology (streams, subjects, overlap guard, etc.)
       Topology.ensure!(@jts)
 
+      @connected_at = Time.now.utc
       @jts
     end
 
+    # Public API for checking connection status
+    # @return [Boolean] true if NATS client is connected and JetStream is healthy
+    def connected?
+      @nc&.connected? && @jts && jetstream_healthy?
+    end
+
+    # Public API for getting connection timestamp
+    # @return [Time, nil] timestamp when connection was established
+    attr_reader :connected_at
+
     private
 
-    def connected?
-      @nc&.connected?
+    def jetstream_healthy?
+      # Verify JetStream responds to simple API call
+      @jts.account_info
+      true
+    rescue StandardError => e
+      Logging.warn(
+        "JetStream health check failed: #{e.class} #{e.message}",
+        tag: 'JetstreamBridge::Connection'
+      )
+      false
     end
 
     def nats_servers
@@ -75,6 +112,30 @@ module JetstreamBridge
 
     def establish_connection(servers)
       @nc = NATS::IO::Client.new
+
+      # Setup reconnect handler to refresh JetStream context
+      @nc.on_reconnect do
+        Logging.info(
+          'NATS reconnected, refreshing JetStream context',
+          tag: 'JetstreamBridge::Connection'
+        )
+        refresh_jetstream_context
+      end
+
+      @nc.on_disconnect do |reason|
+        Logging.warn(
+          "NATS disconnected: #{reason}",
+          tag: 'JetstreamBridge::Connection'
+        )
+      end
+
+      @nc.on_error do |err|
+        Logging.error(
+          "NATS error: #{err}",
+          tag: 'JetstreamBridge::Connection'
+        )
+      end
+
       @nc.connect({ servers: servers }.merge(DEFAULT_CONN_OPTS))
 
       # Create JetStream context
@@ -87,6 +148,20 @@ module JetstreamBridge
       @jts.define_singleton_method(:nc) { nc_ref }
     end
 
+    def refresh_jetstream_context
+      @jts = @nc.jetstream
+      nc_ref = @nc
+      @jts.define_singleton_method(:nc) { nc_ref } unless @jts.respond_to?(:nc)
+
+      # Re-ensure topology after reconnect
+      Topology.ensure!(@jts)
+    rescue StandardError => e
+      Logging.error(
+        "Failed to refresh JetStream context: #{e.class} #{e.message}",
+        tag: 'JetstreamBridge::Connection'
+      )
+    end
+
     # Expose for class-level helpers (not part of public API)
     attr_reader :nc