jetstream_bridge 5.1.0 → 7.0.0

data/lib/jetstream_bridge/consumer/subscription_manager.rb

@@ -51,50 +51,37 @@ module JetstreamBridge
     def subscribe_without_verification!
       # Manually create a pull subscription without calling consumer_info
       # This bypasses the permission check in nats-pure's pull_subscribe
-      nc = resolve_nc
-
-      return build_pull_subscription(nc) if nc.respond_to?(:new_inbox) && nc.respond_to?(:subscribe)
-
-      # Fallback for environments (mocks/tests) where low-level NATS client is unavailable.
-      if @jts.respond_to?(:pull_subscribe)
-        Logging.info(
-          "Using pull_subscribe fallback for consumer #{@durable} (stream=#{stream_name})",
-          tag: 'JetstreamBridge::Consumer'
-        )
-        return @jts.pull_subscribe(filter_subject, @durable, stream: stream_name)
-      end
-
-      raise JetstreamBridge::ConnectionError,
-            'Unable to create subscription without verification: NATS client not available'
+      create_subscription_with_fallback(
+        description: "pull subscription for consumer #{@durable} (stream=#{stream_name})",
+        primary_check: ->(nc) { nc.respond_to?(:new_inbox) && nc.respond_to?(:subscribe) },
+        primary_action: ->(nc) { build_pull_subscription(nc) },
+        fallback_name: :pull_subscribe,
+        fallback_available: -> { @jts.respond_to?(:pull_subscribe) },
+        fallback_action: -> { @jts.pull_subscribe(filter_subject, @durable, stream: stream_name) }
+      )
     end
 
     def subscribe_push!
       # Push consumers deliver messages directly to a subscription subject
       # No JetStream API calls needed - just subscribe to the delivery subject
-      nc = resolve_nc
       delivery_subject = @cfg.push_delivery_subject
 
-      if nc.respond_to?(:subscribe)
-        sub = nc.subscribe(delivery_subject)
-        Logging.info(
-          "Created push subscription for consumer #{@durable} " \
-          "(stream=#{stream_name}, delivery=#{delivery_subject})",
-          tag: 'JetstreamBridge::Consumer'
-        )
-        return sub
-      end
-
-      # Fallback for test environments
-      if @jts.respond_to?(:subscribe)
-        Logging.info(
-          "Using JetStream subscribe fallback for push consumer #{@durable} (stream=#{stream_name})",
-          tag: 'JetstreamBridge::Consumer'
-        )
-        return @jts.subscribe(delivery_subject)
-      end
-
-      raise JetstreamBridge::ConnectionError,
-            'Unable to create push subscription: NATS client not available'
+      create_subscription_with_fallback(
+        description: "push subscription for consumer #{@durable} (stream=#{stream_name}, delivery=#{delivery_subject})",
+        primary_check: ->(nc) { nc.respond_to?(:subscribe) },
+        primary_action: lambda do |nc|
+          sub = nc.subscribe(delivery_subject)
+          Logging.info(
+            "Created push subscription for consumer #{@durable} " \
+            "(stream=#{stream_name}, delivery=#{delivery_subject})",
+            tag: 'JetstreamBridge::Consumer'
+          )
+          sub
+        end,
+        fallback_name: :subscribe,
+        fallback_available: -> { @jts.respond_to?(:subscribe) },
+        fallback_action: -> { @jts.subscribe(delivery_subject) }
+      )
     end
 
     private
@@ -107,8 +94,8 @@ module JetstreamBridge
         deliver_policy: 'all',
         max_deliver: JetstreamBridge.config.max_deliver,
         # JetStream expects seconds (the client multiplies by nanoseconds).
-        ack_wait: duration_to_seconds(JetstreamBridge.config.ack_wait),
-        backoff: Array(JetstreamBridge.config.backoff).map { |d| duration_to_seconds(d) }
+        ack_wait: Duration.to_seconds(JetstreamBridge.config.ack_wait),
+        backoff: Duration.normalize_list_to_seconds(JetstreamBridge.config.backoff)
       }
 
       # Add deliver_subject for push consumers
@@ -125,73 +112,6 @@ module JetstreamBridge
       )
     end
 
-    # ---- cfg access/normalization (struct-like or hash-like) ----
-
-    def get(cfg, key)
-      cfg.respond_to?(key) ? cfg.public_send(key) : cfg[key]
-    end
-
-    def sval(cfg, key)
-      v = get(cfg, key)
-      v = v.to_s if v.is_a?(Symbol)
-      v&.to_s&.downcase
-    end
-
-    def ival(cfg, key)
-      v = get(cfg, key)
-      v.to_i
-    end
-
-    # Normalize duration-like field to **milliseconds** (Integer).
-    # Accepts:
-    # - Strings:"500ms""30s" "2m", "1h", "250us", "100ns"
-    # - Integers/Floats:
-    #     * Server may return large integers in **nanoseconds** → detect and convert.
-    #     * Otherwise, we delegate to Duration.to_millis (heuristic/explicit).
-    def d_secs(cfg, key)
-      raw = get(cfg, key)
-      duration_to_seconds(raw)
-    end
-
-    # Normalize array of durations to integer milliseconds.
-    def darr_secs(cfg, key)
-      raw = get(cfg, key)
-      Array(raw).map { |d| duration_to_seconds(d) }
-    end
-
-    # ---- duration coercion ----
-
-    def duration_to_seconds(val)
-      return nil if val.nil?
-
-      case val
-      when Integer
-        # Heuristic: extremely large integers are likely **nanoseconds** from server
-        # (e.g., 30s => 30_000_000_000 ns). Convert ns → seconds.
-        return (val / 1_000_000_000.0).round if val >= 1_000_000_000
-
-        # otherwise rely on Duration’s :auto heuristic (int <1000 => seconds, >=1000 => ms)
-        millis = Duration.to_millis(val, default_unit: :auto)
-        seconds_from_millis(millis)
-      when Float
-        millis = Duration.to_millis(val, default_unit: :auto)
-        seconds_from_millis(millis)
-      when String
-        # Strings include unit (ns/us/ms/s/m/h/d) handled by Duration
-        millis = Duration.to_millis(val) # default_unit ignored when unit given
-        seconds_from_millis(millis)
-      else
-        return duration_to_seconds(val.to_f) if val.respond_to?(:to_f)
-
-        raise ArgumentError, "invalid duration: #{val.inspect}"
-      end
-    end
-
-    def seconds_from_millis(millis)
-      # Always round up to avoid zero-second waits when sub-second durations are provided.
-      [(millis / 1000.0).ceil, 1].max
-    end
-
     def log_runtime_skip
       Logging.info(
         "Skipping consumer provisioning/verification for #{@durable} at runtime to avoid JetStream API usage. " \
@@ -213,5 +133,23 @@ module JetstreamBridge
       builder = PullSubscriptionBuilder.new(@jts, @durable, stream_name, filter_subject)
       builder.build(nats_client)
     end
+
+    def create_subscription_with_fallback(description:, primary_check:, primary_action:, fallback_name:,
+                                          fallback_available:, fallback_action:)
+      nc = resolve_nc
+
+      return primary_action.call(nc) if nc && primary_check.call(nc)
+
+      if fallback_available.call
+        Logging.info(
+          "Using #{fallback_name} fallback for #{description}",
+          tag: 'JetstreamBridge::Consumer'
+        )
+        return fallback_action.call
+      end
+
+      raise JetstreamBridge::ConnectionError,
+            "Unable to create #{description}: NATS client not available"
+    end
   end
 end

data/lib/jetstream_bridge/core/connection.rb

@@ -304,7 +304,7 @@ module JetstreamBridge
       if verify_js
         verify_jetstream!
         if config_auto_provision
-          Topology.ensure!(@jts)
+          Topology.provision!(@jts)
           Logging.info(
             'Topology ensured after connection (auto_provision=true).',
             tag: 'JetstreamBridge::Connection'
@@ -461,7 +461,7 @@ module JetstreamBridge
 
       # Re-ensure topology after reconnect when allowed
       if config_auto_provision
-        Topology.ensure!(@jts)
+        Topology.provision!(@jts)
       else
         Logging.info(
           'Skipping topology provisioning after reconnect (auto_provision=false).',

data/lib/jetstream_bridge/core/duration.rb

@@ -64,6 +64,31 @@ module JetstreamBridge
       vals.map { |v| to_millis(v, default_unit: default_unit) }
     end
 
+    # Convert duration-like value to seconds (rounding up, min 1s).
+    #
+    # Retains the nanosecond heuristic used in SubscriptionManager:
+    # extremely large integers (>= 1_000_000_000) are treated as nanoseconds
+    # when default_unit is :auto.
+    def to_seconds(val, default_unit: :auto)
+      return nil if val.nil?
+
+      millis = if val.is_a?(Integer) && default_unit == :auto && val >= 1_000_000_000
+                 to_millis(val, default_unit: :ns)
+               else
+                 to_millis(val, default_unit: default_unit)
+               end
+
+      seconds_from_millis(millis)
+    end
+
+    # Normalize an array of durations into integer seconds.
+    def normalize_list_to_seconds(values, default_unit: :auto)
+      vals = Array(values)
+      return [] if vals.empty?
+
+      vals.map { |v| to_seconds(v, default_unit: default_unit) }
+    end
+
     # --- internal helpers ---
 
     def int_to_ms(num, default_unit:)
@@ -100,5 +125,10 @@ module JetstreamBridge
 
       (num * mult).round
     end
+
+    def seconds_from_millis(millis)
+      # Always round up to avoid zero-second waits when sub-second durations are provided.
+      [(millis / 1000.0).ceil, 1].max
+    end
   end
 end

data/lib/jetstream_bridge/models/inbox_event.rb

@@ -11,7 +11,7 @@ end
 module JetstreamBridge
   if defined?(ActiveRecord::Base)
     class InboxEvent < ActiveRecord::Base
-      self.table_name = 'jetstream_inbox_events'
+      self.table_name = 'jetstream_bridge_inbox_events'
 
       class << self
         # Safe column presence check that never boots a connection during class load.

data/lib/jetstream_bridge/models/outbox_event.rb

@@ -11,7 +11,7 @@ end
 module JetstreamBridge
   if defined?(ActiveRecord::Base)
     class OutboxEvent < ActiveRecord::Base
-      self.table_name = 'jetstream_outbox_events'
+      self.table_name = 'jetstream_bridge_outbox_events'
 
       class << self
         # Safe column presence check that never boots a connection during class load.

data/lib/jetstream_bridge/provisioner.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'logger'
 require_relative 'topology/topology'
 require_relative 'consumer/subscription_manager'
 require_relative 'core/logging'
@@ -13,52 +14,107 @@ 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
+      #
+      # @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),
+        **shared_config
+      )
+        [
+          { app_name: app_a, destination_app: app_b },
+          { app_name: app_b, destination_app: app_a }
+        ].each do |direction|
+          logger&.info "Provisioning #{direction[:app_name]} -> #{direction[:destination_app]}"
+          configure_direction(direction, stream_name, nats_url, logger, shared_config)
+
+          begin
+            JetstreamBridge.startup!
+            new.provision!
+          ensure
+            JetstreamBridge.shutdown!
+          end
+        end
+      end
+
+      def configure_direction(direction, stream_name, nats_url, logger, 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
+
+          shared_config.each do |key, value|
+            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.0'
 end

data/lib/jetstream_bridge.rb

@@ -140,7 +140,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 +197,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 +208,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 +222,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.0
 platform: ruby
 authors:
 - Mike Attara
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-28 00:00:00.000000000 Z
+date: 2026-01-30 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,9 @@ 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/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