jetstream_bridge 5.1.0 → 7.0.1

data/lib/jetstream_bridge/provisioner.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
+require 'logger'
 require_relative 'topology/topology'
 require_relative 'consumer/subscription_manager'
 require_relative 'core/logging'
 require_relative 'core/config'
 require_relative 'core/connection'
+require_relative 'core/consumer_mode_resolver'
 
 module JetstreamBridge
   # Dedicated provisioning orchestrator to keep connection concerns separate.
@@ -13,52 +15,145 @@ module JetstreamBridge
   # deploy-time with admin credentials or during runtime when auto_provision
   # is enabled.
   class Provisioner
+    class << self
+      # Provision both directions (A->B and B->A) with shared defaults.
+      #
+      # @param app_a [String] First app name
+      # @param app_b [String] Second app name
+      # @param stream_name [String] Stream used for both directions
+      # @param nats_url [String] NATS connection URL
+      # @param logger [Logger] Logger used for progress output
+      # @param shared_config [Hash] Additional config applied to both directions
+      # @param consumer_modes [Hash,nil] Per-app consumer modes { 'system_a' => :pull, 'system_b' => :push }
+      # @param consumer_mode [Symbol] Legacy/shared consumer mode for both directions (overridden by consumer_modes)
+      #
+      # @return [void]
+      def provision_bidirectional!(
+        app_a:,
+        app_b:,
+        stream_name: 'sync-stream',
+        nats_url: ENV.fetch('NATS_URL', 'nats://nats:4222'),
+        logger: Logger.new($stdout),
+        consumer_modes: nil,
+        consumer_mode: :pull,
+        **shared_config
+      )
+        modes = build_consumer_mode_map(app_a, app_b, consumer_modes, consumer_mode)
+
+        [
+          { app_name: app_a, destination_app: app_b },
+          { app_name: app_b, destination_app: app_a }
+        ].each do |direction|
+          direction_mode = modes[direction[:app_name]] || consumer_mode
+          logger&.info "Provisioning #{direction[:app_name]} -> #{direction[:destination_app]}"
+          configure_direction(
+            direction,
+            stream_name: stream_name,
+            nats_url: nats_url,
+            logger: logger,
+            consumer_mode: direction_mode,
+            shared_config: shared_config
+          )
+
+          begin
+            JetstreamBridge.startup!
+            new.provision!
+          ensure
+            JetstreamBridge.shutdown!
+          end
+        end
+      end
+
+      def build_consumer_mode_map(app_a, app_b, consumer_modes, fallback_mode)
+        app_a_key = app_a.to_s
+        app_b_key = app_b.to_s
+        normalized_fallback = ConsumerModeResolver.normalize(fallback_mode)
+
+        if consumer_modes
+          normalized = consumer_modes.transform_keys(&:to_s).transform_values do |v|
+            ConsumerModeResolver.normalize(v)
+          end
+          normalized[app_a_key] ||= normalized_fallback
+          normalized[app_b_key] ||= normalized_fallback
+          return normalized
+        end
+
+        {
+          app_a_key => ConsumerModeResolver.resolve(app_name: app_a_key, fallback: normalized_fallback),
+          app_b_key => ConsumerModeResolver.resolve(app_name: app_b_key, fallback: normalized_fallback)
+        }
+      end
+      private :build_consumer_mode_map
+
+      def configure_direction(direction, stream_name:, nats_url:, logger:, consumer_mode:, shared_config:)
+        JetstreamBridge.configure do |cfg|
+          cfg.nats_urls = nats_url
+          cfg.app_name = direction[:app_name]
+          cfg.destination_app = direction[:destination_app]
+          cfg.stream_name = stream_name
+          cfg.auto_provision = true
+          cfg.use_outbox = false
+          cfg.use_inbox = false
+          cfg.logger = logger if logger
+          cfg.consumer_mode = consumer_mode
+
+          shared_config.each do |key, value|
+            next if key.to_sym == :consumer_mode
+
+            setter = "#{key}="
+            cfg.public_send(setter, value) if cfg.respond_to?(setter)
+          end
+        end
+      end
+      private :configure_direction
+    end
+
     def initialize(config: JetstreamBridge.config)
       @config = config
     end
 
-    # Ensure stream (and optionally consumer) exist with desired config.
+    # Provision stream (and optionally consumer) with desired config.
     #
     # @param jts [Object, nil] Existing JetStream context (optional)
-    # @param ensure_consumer [Boolean] Whether to create/align the consumer too
+    # @param provision_consumer [Boolean] Whether to create/align the consumer too
     # @return [Object] JetStream context used for provisioning
-    def ensure!(jts: nil, ensure_consumer: true)
+    def provision!(jts: nil, provision_consumer: true)
       js = jts || Connection.connect!(verify_js: true)
 
-      ensure_stream!(jts: js)
-      ensure_consumer!(jts: js) if ensure_consumer
+      provision_stream!(jts: js)
+      provision_consumer!(jts: js) if provision_consumer
 
       Logging.info(
-        "Provisioned stream=#{@config.stream_name} consumer=#{@config.durable_name if ensure_consumer}",
+        "Provisioned stream=#{@config.stream_name} consumer=#{@config.durable_name if provision_consumer}",
         tag: 'JetstreamBridge::Provisioner'
       )
 
       js
     end
 
-    # Ensure stream only.
+    # Provision stream only.
     #
     # @param jts [Object, nil] Existing JetStream context (optional)
     # @return [Object] JetStream context used
-    def ensure_stream!(jts: nil)
+    def provision_stream!(jts: nil)
       js = jts || Connection.connect!(verify_js: true)
-      Topology.ensure!(js)
+      Topology.provision!(js)
       Logging.info(
-        "Stream ensured: #{@config.stream_name}",
+        "Stream provisioned: #{@config.stream_name}",
         tag: 'JetstreamBridge::Provisioner'
       )
       js
     end
 
-    # Ensure durable consumer only.
+    # Provision durable consumer only.
     #
     # @param jts [Object, nil] Existing JetStream context (optional)
     # @return [Object] JetStream context used
-    def ensure_consumer!(jts: nil)
+    def provision_consumer!(jts: nil)
       js = jts || Connection.connect!(verify_js: true)
       SubscriptionManager.new(js, @config.durable_name, @config).ensure_consumer!(force: true)
       Logging.info(
-        "Consumer ensured: #{@config.durable_name}",
+        "Consumer provisioned: #{@config.durable_name}",
         tag: 'JetstreamBridge::Provisioner'
       )
       js

data/lib/jetstream_bridge/publisher/outbox_repository.rb

@@ -35,29 +35,15 @@ module JetstreamBridge
         (record.respond_to?(:status) && record.status == 'sent')
     end
 
-    def persist_pre(record, subject, envelope)
+    def record_publish_attempt(record, subject, envelope)
       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 = build_publish_attrs(record, subject, envelope)
         ModelUtils.assign_known_attrs(record, attrs)
         record.save!
       end
     end
 
-    def persist_success(record)
+    def record_publish_success(record)
       ActiveRecord::Base.transaction do
         now = Time.now.utc
         attrs = { status: 'sent' }
@@ -68,7 +54,7 @@ module JetstreamBridge
       end
     end
 
-    def persist_failure(record, message)
+    def record_publish_failure(record, message)
       ActiveRecord::Base.transaction do
         now = Time.now.utc
         attrs = { status: 'failed', last_error: message }
@@ -78,13 +64,42 @@ module JetstreamBridge
       end
     end
 
-    def persist_exception(record, error)
+    def record_publish_exception(record, error)
       return unless record
 
-      persist_failure(record, "#{error.class}: #{error.message}")
+      record_publish_failure(record, "#{error.class}: #{error.message}")
     rescue StandardError => e
       Logging.warn("Failed to persist outbox failure: #{e.class}: #{e.message}",
                    tag: 'JetstreamBridge::Publisher')
     end
+
+    private
+
+    def build_publish_attrs(record, subject, envelope)
+      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,
+        resource_type: envelope['resource_type'],
+        resource_id: envelope['resource_id'],
+        event_type: envelope['type'] || envelope['event_type']
+      }
+
+      assign_optional_publish_attrs(record, attrs, now)
+      attrs
+    end
+
+    def assign_optional_publish_attrs(record, attrs, now)
+      attrs[:destination_app] = JetstreamBridge.config.destination_app if record.respond_to?(:destination_app=)
+      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)
+    end
   end
 end

data/lib/jetstream_bridge/publisher/publisher.rb

@@ -252,17 +252,17 @@ module JetstreamBridge
         )
       end
 
-      repo.persist_pre(record, subject, envelope)
+      repo.record_publish_attempt(record, subject, envelope)
 
       result = with_retries { publish_to_nats(subject, envelope) }
       if result.success?
-        repo.persist_success(record)
+        repo.record_publish_success(record)
       else
-        repo.persist_failure(record, result.error&.message || 'Publish failed')
+        repo.record_publish_failure(record, result.error&.message || 'Publish failed')
       end
       result
     rescue StandardError => e
-      repo.persist_exception(record, e) if defined?(repo) && defined?(record)
+      repo.record_publish_exception(record, e) if defined?(repo) && defined?(record)
       Models::PublishResult.new(
         success: false,
         event_id: envelope['event_id'],

data/lib/jetstream_bridge/tasks/install.rake

@@ -113,12 +113,12 @@ namespace :jetstream_bridge do
 
     begin
       provision_enabled = JetstreamBridge.config.auto_provision
-      jts = JetstreamBridge.connect_and_ensure_stream!
+      jts = JetstreamBridge.connect_and_provision!
 
       if provision_enabled
         puts '✓ Successfully connected to NATS'
         puts '✓ JetStream is available'
-        puts '✓ Stream topology ensured'
+        puts '✓ Stream topology provisioned'
 
         # Check if we can get account info
         info = jts.account_info

data/lib/jetstream_bridge/topology/stream.rb

@@ -174,7 +174,12 @@ module JetstreamBridge
 
       # Only include mutable fields on update (subjects, storage). Never retention.
       def apply_update(jts, name, subjects, storage: nil)
-        params = { name: name, subjects: subjects }
+        # Fetch existing stream config to preserve retention
+        info = jts.stream_info(name)
+        config_data = info.config
+        existing_retention = config_data.respond_to?(:retention) ? config_data.retention : config_data[:retention]
+
+        params = { name: name, subjects: subjects, retention: existing_retention }
         params[:storage] = storage if storage
         jts.update_stream(**params)
       end

data/lib/jetstream_bridge/topology/topology.rb

@@ -6,7 +6,7 @@ require_relative 'stream'
 
 module JetstreamBridge
   class Topology
-    def self.ensure!(jts)
+    def self.provision!(jts)
       cfg = JetstreamBridge.config
       subjects = [cfg.source_subject, cfg.destination_subject]
       subjects << cfg.dlq_subject if cfg.use_dlq

data/lib/jetstream_bridge/version.rb

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

data/lib/jetstream_bridge.rb

@@ -129,6 +129,7 @@ module JetstreamBridge
     def reset!
       @config = nil
       @connection_initialized = false
+      Consumer.reset_signal_handlers! if defined?(Consumer)
     end
 
     # Initialize the JetStream Bridge connection and topology
@@ -140,7 +141,7 @@ module JetstreamBridge
       return if @connection_initialized
 
       config.validate!
-      connect_and_ensure_stream!
+      connect_and_provision!
       @connection_initialized = true
       Logging.info('JetStream Bridge started successfully', tag: 'JetstreamBridge')
     end
@@ -197,10 +198,10 @@ module JetstreamBridge
       config.use_dlq
     end
 
-    # Establishes a connection and ensures stream topology.
+    # Establishes a connection and provisions stream topology.
     #
     # @return [Object] JetStream context
-    def connect_and_ensure_stream!
+    def connect_and_provision!
       config.validate!
       provision = config.auto_provision
       Connection.connect!(verify_js: provision)
@@ -208,7 +209,7 @@ module JetstreamBridge
       raise ConnectionNotEstablishedError, 'JetStream connection not available' unless jts
 
       if provision
-        Provisioner.new(config: config).ensure_stream!(jts: jts)
+        Provisioner.new(config: config).provision_stream!(jts: jts)
       else
         Logging.info(
           'auto_provision=false: skipping stream provisioning and JetStream account_info. ' \
@@ -222,16 +223,11 @@ module JetstreamBridge
 
     # Provision stream/consumer using management credentials (out of band from runtime).
     #
-    # @param ensure_consumer [Boolean] Whether to create/align the consumer along with the stream.
+    # @param provision_consumer [Boolean] Whether to create/align the consumer along with the stream.
     # @return [Object] JetStream context
-    def provision!(ensure_consumer: true)
+    def provision!(provision_consumer: true)
       config.validate!
-      Provisioner.new(config: config).ensure!(ensure_consumer: ensure_consumer)
-    end
-
-    # Backwards-compatible alias for the previous method name
-    def ensure_topology!
-      connect_and_ensure_stream!
+      Provisioner.new(config: config).provision!(provision_consumer: provision_consumer)
     end
 
     # Active health check for monitoring and readiness probes

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jetstream_bridge
 version: !ruby/object:Gem::Version
-  version: 5.1.0
+  version: 7.0.1
 platform: ruby
 authors:
 - Mike Attara
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-28 00:00:00.000000000 Z
+date: 2026-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -121,6 +121,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- docs/API.md
 - docs/ARCHITECTURE.md
 - docs/GETTING_STARTED.md
 - docs/PRODUCTION.md
@@ -135,7 +136,10 @@ 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/config_helpers.rb
+- lib/jetstream_bridge/config_helpers/lifecycle.rb
 - lib/jetstream_bridge/consumer/consumer.rb
+- lib/jetstream_bridge/consumer/consumer_state.rb
 - lib/jetstream_bridge/consumer/dlq_publisher.rb
 - lib/jetstream_bridge/consumer/inbox/inbox_message.rb
 - lib/jetstream_bridge/consumer/inbox/inbox_processor.rb
@@ -150,6 +154,7 @@ files:
 - lib/jetstream_bridge/core/config_preset.rb
 - lib/jetstream_bridge/core/connection.rb
 - lib/jetstream_bridge/core/connection_factory.rb
+- lib/jetstream_bridge/core/consumer_mode_resolver.rb
 - lib/jetstream_bridge/core/debug_helper.rb
 - lib/jetstream_bridge/core/duration.rb
 - lib/jetstream_bridge/core/logging.rb