jetstream_bridge 2.2.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4575d208da9591190342d3252b48f7dafa5d33519230700b23b2e2b6ff20555f
-  data.tar.gz: 35153c2cf70e7e446dfc4fb8ff2cdbe656d907d34d4769c2e9971ca10aebe766
+  metadata.gz: e0501a83858dfa54be16d6e9b9484564f3fc8e275f30473322e3f304501c2ca5
+  data.tar.gz: 6ea1b6fc4333c3e3e4cffb220669877c7271c4c54cab532a22f89e9f41ed5a51
 SHA512:
-  metadata.gz: eb6e2726cebd8d71092dcc34e1956e9e0bdcb598f41e26badd7dbd6376e778487ec5544470d6aee44b0312f3983aa5f74c717208f6b7208296853b0c2f49a4db
-  data.tar.gz: 53ba518040a3bb9a7883764621549cc794e8c84784f89c7c9c205de61cc662f748fd994587d6f1821ff8d110ae193b2d86b998c3dacc2127f8fd778e9e69606d
+  metadata.gz: a6d3749ffda0dc178218ae0e7a55ca45a93d129961fb127958699ef9fa88115814aa19954f1a38a81848de7ca678e86fbb1ba802efa00c9388da3ec444dce1e7
+  data.tar.gz: 3866b27b03ae500859f23cdc39bb6cd72b6e49eeefc8e0bf2e921a14097423e6439baf1ff8b45b08327331cbe387aabff3807fb139fb6f84614bd3b7b35894de

data/.idea/dictionaries/project.xml

@@ -11,6 +11,7 @@
       <w>psub</w>
       <w>sname</w>
       <w>softprops</w>
+      <w>workqueue</w>
     </words>
   </dictionary>
 </component>

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jetstream_bridge (2.2.1)
+    jetstream_bridge (2.3.0)
       activerecord (>= 6.0)
       activesupport (>= 6.0)
       nats-pure (~> 2.4)

data/README.md

@@ -23,7 +23,7 @@ Includes durable consumers, backpressure, retries, **DLQ**, optional **Inbox/Out
 
 ```ruby
 # Gemfile
-gem "jetstream_bridge", "~> 2.0"
+gem "jetstream_bridge", "~> 2.3"
 ```
 
 ```bash
@@ -191,7 +191,7 @@ publisher.publish(
 If **Outbox** is enabled, the publish call:
 
 * Upserts an outbox row by `event_id`
-* Publishes with `Nats-Msg-Id` (idempotent)
+* Publishes with `nats-msg-id` (idempotent)
 * Marks status `sent` or records `failed` with `last_error`
 
 ---

data/lib/jetstream_bridge/consumer/consumer.rb

@@ -13,7 +13,7 @@ require_relative 'subscription_manager'
 require_relative 'inbox/inbox_processor'
 
 module JetstreamBridge
-  # Subscribes to "{env}.{dest}.sync.{app}" and processes messages.
+  # Subscribes to destination subject and processes messages via a pull durable.
   class Consumer
     DEFAULT_BATCH_SIZE = 25
     FETCH_TIMEOUT_SECS = 5
@@ -29,7 +29,7 @@ module JetstreamBridge
 
       @sub_mgr = SubscriptionManager.new(@jts, @durable, JetstreamBridge.config)
       @sub_mgr.ensure_consumer!
-      @psub       = @sub_mgr.subscribe!
+      @psub = @sub_mgr.subscribe!
 
       @processor  = MessageProcessor.new(@jts, @handler)
       @inbox_proc = InboxProcessor.new(@processor) if JetstreamBridge.config.use_inbox
@@ -71,24 +71,28 @@ module JetstreamBridge
       msgs.sum { |m| process_one(m) }
     end
 
-    def process_one(m)
+    def process_one(msg)
       if @inbox_proc
-        @inbox_proc.process(m) ? 1 : 0
+        @inbox_proc.process(msg) ? 1 : 0
       else
-        @processor.handle_message(m)
+        @processor.handle_message(msg)
         1
       end
     end
 
     def handle_js_error(e)
       if recoverable_consumer_error?(e)
-        Logging.warn("Recovering subscription after error: #{e.class} #{e.message}",
-                     tag: 'JetstreamBridge::Consumer')
+        Logging.warn(
+          "Recovering subscription after error: #{e.class} #{e.message}",
+          tag: 'JetstreamBridge::Consumer'
+        )
         @sub_mgr.ensure_consumer!
         @psub = @sub_mgr.subscribe!
       else
-        Logging.error("Fetch failed: #{e.class} #{e.message}",
-                      tag: 'JetstreamBridge::Consumer')
+        Logging.error(
+          "Fetch failed: #{e.class} #{e.message}",
+          tag: 'JetstreamBridge::Consumer'
+        )
       end
       0
     end

data/lib/jetstream_bridge/consumer/consumer_config.rb

@@ -9,23 +9,17 @@ module JetstreamBridge
   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
-
-    def subscribe_config
-      {
-        ack_policy: 'explicit',
-        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) }
+        backoff: Array(JetstreamBridge.config.backoff)
+          .map { |d| Duration.to_millis(d) }
       }
     end
   end

data/lib/jetstream_bridge/consumer/message_processor.rb

@@ -5,16 +5,16 @@ require 'securerandom'
 require_relative '../core/logging'
 
 module JetstreamBridge
-  # Handles parse → handler → ack / nak → DLQ
+  # Handles parse → handler → ack / nak → DLQ.
   class MessageProcessor
     def initialize(jts, handler)
-      @jts = jts
+      @jts     = jts
       @handler = handler
     end
 
     def handle_message(msg)
       deliveries = msg.metadata&.num_delivered.to_i
-      event_id   = msg.header&.[]('Nats-Msg-Id') || SecureRandom.uuid
+      event_id   = msg.header&.[]('nats-msg-id') || SecureRandom.uuid
       event      = parse_message(msg, event_id)
       return unless event
 
@@ -28,28 +28,34 @@ module JetstreamBridge
     rescue JSON::ParserError => e
       publish_to_dlq!(msg)
       msg.ack
-      Logging.warn("Malformed JSON to DLQ event_id=#{event_id}: #{e.message}",
-                   tag: 'JetstreamBridge::Consumer')
+      Logging.warn(
+        "Malformed JSON to DLQ event_id=#{event_id}: #{e.message}",
+        tag: 'JetstreamBridge::Consumer'
+      )
       nil
     end
 
-    def process_event(msg, event, deliveries, event_id)
+    def process_event(msg, event, deliveries, _event_id)
       @handler.call(event, msg.subject, deliveries)
       msg.ack
     rescue StandardError => e
-      ack_or_nak(msg, deliveries, event_id, e)
+      ack_or_nak(msg, deliveries, e)
     end
 
-    def ack_or_nak(msg, deliveries, event_id, error)
+    def ack_or_nak(msg, deliveries, error)
       if deliveries >= JetstreamBridge.config.max_deliver.to_i
         publish_to_dlq!(msg)
         msg.ack
-        Logging.warn("Sent to DLQ after max_deliver event_id=#{event_id} err=#{error.message}",
-                     tag: 'JetstreamBridge::Consumer')
+        Logging.warn(
+          "Sent to DLQ after max_deliver err=#{error.message}",
+          tag: 'JetstreamBridge::Consumer'
+        )
       else
         msg.nak
-        Logging.warn("NAK event_id=#{event_id} deliveries=#{deliveries} err=#{error.message}",
-                     tag: 'JetstreamBridge::Consumer')
+        Logging.warn(
+          "NAK deliveries=#{deliveries} err=#{error.message}",
+          tag: 'JetstreamBridge::Consumer'
+        )
       end
     end
 
@@ -58,8 +64,10 @@ module JetstreamBridge
 
       @jts.publish(JetstreamBridge.config.dlq_subject, msg.data, header: msg.header)
     rescue StandardError => e
-      Logging.error("DLQ publish failed: #{e.class} #{e.message}",
-                    tag: 'JetstreamBridge::Consumer')
+      Logging.error(
+        "DLQ publish failed: #{e.class} #{e.message}",
+        tag: 'JetstreamBridge::Consumer'
+      )
     end
   end
 end

data/lib/jetstream_bridge/consumer/subscription_manager.rb

@@ -4,7 +4,7 @@ require_relative '../core/logging'
 require_relative '../consumer/consumer_config'
 
 module JetstreamBridge
-  # Encapsulates durable ensure + subscribe for a consumer.
+  # Encapsulates durable ensure + subscribe for a pull consumer.
   class SubscriptionManager
     def initialize(jts, durable, cfg = JetstreamBridge.config)
       @jts     = jts
@@ -27,17 +27,18 @@ module JetstreamBridge
     def ensure_consumer!
       info = consumer_info_or_nil
       return create_consumer! unless info
-      return log_consumer_ok if consumer_matches?(info)
+      return log_consumer_ok if consumer_matches?(info, desired_consumer_cfg)
 
       recreate_consumer!
     end
 
+    # Bind a pull subscriber to the existing durable.
     def subscribe!
       @jts.pull_subscribe(
         filter_subject,
         @durable,
         stream: stream_name,
-        config: ConsumerConfig.subscribe_config
+        config: desired_consumer_cfg
       )
     end
 
@@ -49,16 +50,31 @@ module JetstreamBridge
       nil
     end
 
-    def consumer_matches?(info)
-      cfg  = info.config
-      have = (cfg.respond_to?(:filter_subject) ? cfg.filter_subject : cfg[:filter_subject]).to_s
-      want = desired_consumer_cfg[:filter_subject].to_s
-      have == want
+    def consumer_matches?(info, want)
+      cfg = info.config
+      have = {
+        filter_subject: val(cfg, :filter_subject),
+        ack_policy: val(cfg, :ack_policy),
+        deliver_policy: val(cfg, :deliver_policy),
+        max_deliver: int_val(cfg, :max_deliver),
+        ack_wait: int_val(cfg, :ack_wait),
+        backoff: arr_int(cfg, :backoff)
+      }
+      want_cmp = {
+        filter_subject: want[:filter_subject].to_s,
+        ack_policy: want[:ack_policy].to_s,
+        deliver_policy: want[:deliver_policy].to_s,
+        max_deliver: want[:max_deliver].to_i,
+        ack_wait: want[:ack_wait].to_i,
+        backoff: Array(want[:backoff]).map(&:to_i)
+      }
+      have == want_cmp
     end
 
     def recreate_consumer!
       Logging.warn(
-        "Consumer #{@durable} exists with mismatched config; recreating (filter=#{filter_subject})",
+        "Consumer #{@durable} exists with mismatched config; " \
+        "recreating (filter=#{filter_subject})",
         tag: 'JetstreamBridge::Consumer'
       )
       safe_delete_consumer
@@ -67,26 +83,42 @@ module JetstreamBridge
 
     def create_consumer!
       @jts.add_consumer(stream_name, **desired_consumer_cfg)
-      Logging.info("Created consumer #{@durable} (filter=#{filter_subject})",
-                   tag: 'JetstreamBridge::Consumer')
+      Logging.info(
+        "Created consumer #{@durable} (filter=#{filter_subject})",
+        tag: 'JetstreamBridge::Consumer'
+      )
     end
 
     def log_consumer_ok
-      Logging.info("Consumer #{@durable} exists with desired config.",
-                   tag: 'JetstreamBridge::Consumer')
+      Logging.info(
+        "Consumer #{@durable} exists with desired config.",
+        tag: 'JetstreamBridge::Consumer'
+      )
     end
 
     def safe_delete_consumer
       @jts.delete_consumer(stream_name, @durable)
     rescue NATS::JetStream::Error => e
-      Logging.warn("Delete consumer #{@durable} ignored: #{e.class} #{e.message}",
-                   tag: 'JetstreamBridge::Consumer')
+      Logging.warn(
+        "Delete consumer #{@durable} ignored: #{e.class} #{e.message}",
+        tag: 'JetstreamBridge::Consumer'
+      )
     end
 
-    def consumer_mismatch?(info, desired_cfg)
-      cfg = info.config
-      (cfg.respond_to?(:filter_subject) ? cfg.filter_subject.to_s : cfg[:filter_subject].to_s) !=
-        desired_cfg[:filter_subject].to_s
+    # ---- cfg helpers (client may return struct-like or hash-like objects) ----
+
+    def val(cfg, key)
+      (cfg.respond_to?(key) ? cfg.public_send(key) : cfg[key])&.to_s
+    end
+
+    def int_val(cfg, key)
+      v = cfg.respond_to?(key) ? cfg.public_send(key) : cfg[key]
+      v.to_i
+    end
+
+    def arr_int(cfg, key)
+      v = cfg.respond_to?(key) ? cfg.public_send(key) : cfg[key]
+      Array(v).map(&:to_i)
     end
   end
 end

data/lib/jetstream_bridge/core/connection.rb

@@ -48,9 +48,8 @@ module JetstreamBridge
       establish_connection(servers)
 
       Logging.info(
-        "Connected to NATS (#{servers.size} server#{unless servers.size == 1
-                                                      's'
-                                                    end}): #{sanitize_urls(servers).join(', ')}",
+        "Connected to NATS (#{servers.size} server#{'s' unless servers.size == 1}): " \
+        "#{sanitize_urls(servers).join(', ')}",
         tag: 'JetstreamBridge::Connection'
       )
 
@@ -82,14 +81,10 @@ module JetstreamBridge
       @jts = @nc.jetstream
 
       # --- Compatibility shim: ensure JetStream responds to #nc for older/newer clients ---
-      # Some versions of the NATS Ruby client don't expose nc on the JetStream object.
-      # We attach a singleton method, so code expecting `js.nc` continues to work.
       return if @jts.respond_to?(:nc)
 
       nc_ref = @nc
       @jts.define_singleton_method(:nc) { nc_ref }
-
-      # ------------------------------------------------------------------------------------
     end
 
     # Expose for class-level helpers (not part of public API)

data/lib/jetstream_bridge/publisher/publisher.rb

@@ -49,9 +49,12 @@ module JetstreamBridge
 
     def do_publish?(subject, envelope)
       headers = { 'nats-msg-id' => envelope['event_id'] }
+
       @jts.publish(subject, JSON.generate(envelope), header: headers)
-      Logging.info("Published #{subject} event_id=#{envelope['event_id']}",
-                   tag: 'JetstreamBridge::Publisher')
+      Logging.info(
+        "Published #{subject} event_id=#{envelope['event_id']}",
+        tag: 'JetstreamBridge::Publisher'
+      )
       true
     end
 
@@ -60,8 +63,10 @@ module JetstreamBridge
       klass = ModelUtils.constantize(JetstreamBridge.config.outbox_model)
 
       unless ModelUtils.ar_class?(klass)
-        Logging.warn("Outbox model #{klass} is not an ActiveRecord model; publishing directly.",
-                     tag: 'JetstreamBridge::Publisher')
+        Logging.warn(
+          "Outbox model #{klass} is not an ActiveRecord model; publishing directly.",
+          tag: 'JetstreamBridge::Publisher'
+        )
         return with_retries { do_publish?(subject, envelope) }
       end
 
@@ -70,8 +75,10 @@ module JetstreamBridge
       record   = repo.find_or_build(event_id)
 
       if repo.already_sent?(record)
-        Logging.info("Outbox already sent event_id=#{event_id}; skipping publish.",
-                     tag: 'JetstreamBridge::Publisher')
+        Logging.info(
+          "Outbox already sent event_id=#{event_id}; skipping publish.",
+          tag: 'JetstreamBridge::Publisher'
+        )
         return true
       end
 
@@ -102,14 +109,18 @@ module JetstreamBridge
 
     def backoff(attempts, error)
       delay = RETRY_BACKOFFS[attempts - 1] || RETRY_BACKOFFS.last
-      Logging.warn("Publish retry #{attempts} after #{error.class}: #{error.message}",
-                   tag: 'JetstreamBridge::Publisher')
+      Logging.warn(
+        "Publish retry #{attempts} after #{error.class}: #{error.message}",
+        tag: 'JetstreamBridge::Publisher'
+      )
       sleep delay
     end
 
     def log_error(val, exc)
-      Logging.error("Publish failed: #{exc.class} #{exc.message}",
-                    tag: 'JetstreamBridge::Publisher')
+      Logging.error(
+        "Publish failed: #{exc.class} #{exc.message}",
+        tag: 'JetstreamBridge::Publisher'
+      )
       val
     end
 

data/lib/jetstream_bridge/topology/stream.rb

@@ -5,11 +5,82 @@ require_relative 'overlap_guard'
 require_relative 'subject_matcher'
 
 module JetstreamBridge
-  # Ensures a stream exists and adds only subjects that are not already covered.
+  module StreamSupport
+    module_function
+
+    def normalize_subjects(list)
+      Array(list).flatten.compact.map!(&:to_s).reject(&:empty?).uniq
+    end
+
+    def missing_subjects(existing, desired)
+      desired.reject { |d| SubjectMatcher.covered?(existing, d) }
+    end
+
+    def stream_not_found?(error)
+      msg = error.message.to_s
+      msg =~ /stream\s+not\s+found/i || msg =~ /\b404\b/
+    end
+
+    def overlap_error?(error)
+      msg = error.message.to_s
+      msg =~ /subjects?\s+overlap/i || msg =~ /\berr_code=10065\b/ || msg =~ /\b400\b/
+    end
+
+    # ---- Logging ----
+    def log_already_covered(name)
+      Logging.info(
+        "Stream #{name} exists; subjects and config already covered.",
+        tag: 'JetstreamBridge::Stream'
+      )
+    end
+
+    def log_all_blocked(name, blocked)
+      if blocked.any?
+        Logging.warn(
+          "Stream #{name}: all missing subjects belong to other streams; unchanged. " \
+          "blocked=#{blocked.inspect}",
+          tag: 'JetstreamBridge::Stream'
+        )
+      else
+        Logging.info("Stream #{name} exists; nothing to add.", tag: 'JetstreamBridge::Stream')
+      end
+    end
+
+    def log_updated(name, added, blocked)
+      msg = "Updated stream #{name}; added subjects=#{added.inspect}"
+      msg += " (skipped overlapped=#{blocked.inspect})" if blocked.any?
+      Logging.info(msg, tag: 'JetstreamBridge::Stream')
+    end
+
+    def log_not_created(name, blocked)
+      Logging.warn(
+        "Not creating stream #{name}: all desired subjects belong to other streams. " \
+        "blocked=#{blocked.inspect}",
+        tag: 'JetstreamBridge::Stream'
+      )
+    end
+
+    def log_created(name, allowed, blocked, retention, storage)
+      msg = [
+        "Created stream #{name}",
+        "subjects=#{allowed.inspect}",
+        "retention=#{retention.inspect}",
+        "storage=#{storage.inspect}"
+      ].join(' ')
+      msg += " (skipped overlapped=#{blocked.inspect})" if blocked.any?
+      Logging.info(msg, tag: 'JetstreamBridge::Stream')
+    end
+  end
+
+  # Ensures a stream exists and updates only uncovered subjects, using work-queue semantics:
+  # Persist with zero consumers; delete after the first ack (retention: 'workqueue').
   class Stream
+    RETENTION = 'workqueue'
+    STORAGE   = 'file'
+
     class << self
       def ensure!(jts, name, subjects)
-        desired = normalize_subjects(subjects)
+        desired = StreamSupport.normalize_subjects(subjects)
         raise ArgumentError, 'subjects must not be empty' if desired.empty?
 
         attempts = 0
@@ -17,14 +88,18 @@ module JetstreamBridge
           info = safe_stream_info(jts, name)
           info ? ensure_update(jts, name, info, desired) : ensure_create(jts, name, desired)
         rescue NATS::JetStream::Error => e
-          if overlap_error?(e) && (attempts += 1) <= 1
-            Logging.warn("Overlap race while ensuring #{name}; retrying once...", tag: 'JetstreamBridge::Stream')
+          if StreamSupport.overlap_error?(e) && (attempts += 1) <= 1
+            Logging.warn(
+              "Overlap race while ensuring #{name}; retrying once...",
+              tag: 'JetstreamBridge::Stream'
+            )
             sleep(0.05)
             retry
-          elsif overlap_error?(e)
+          elsif StreamSupport.overlap_error?(e)
             Logging.warn(
               "Overlap persists ensuring #{name}; leaving unchanged. err=#{e.message.inspect}",
-              tag: 'JetstreamBridge::Stream')
+              tag: 'JetstreamBridge::Stream'
+            )
             nil
           else
             raise
@@ -34,95 +109,77 @@ module JetstreamBridge
 
       private
 
-      # ---------- Update existing stream ----------
-
-      def ensure_update(jts, name, info, desired)
-        existing = normalize_subjects(info.config.subjects || [])
-        to_add   = missing_subjects(existing, desired)
-        return log_already_covered(name) if to_add.empty?
-
-        allowed, blocked = OverlapGuard.partition_allowed(jts, name, to_add)
-        return log_all_blocked(name, blocked) if allowed.empty?
-
-        target = (existing + allowed).uniq
-        OverlapGuard.check!(jts, name, target)
-        jts.update_stream(name: name, subjects: target)
-        log_updated(name, allowed, blocked)
-      end
+      # ---- keep ensure_update small (<=20 lines, lower ABC) ----
+      def ensure_update(jts, name, info, desired_subjects)
+        existing = StreamSupport.normalize_subjects(info.config.subjects || [])
+        to_add   = StreamSupport.missing_subjects(existing, desired_subjects)
 
-      # ---------- Create new stream ----------
+        return add_subjects(jts, name, existing, to_add) if to_add.any?
 
-      def ensure_create(jts, name, desired)
-        allowed, blocked = OverlapGuard.partition_allowed(jts, name, desired)
-        return log_not_created(name, blocked) if allowed.empty?
+        if config_needs_update?(info)
+          apply_update(jts, name, existing)
+          return log_config_updated(name)
+        end
 
-        jts.add_stream(name: name, subjects: allowed, retention: 'interest', storage: 'file')
-        log_created(name, allowed, blocked)
+        StreamSupport.log_already_covered(name)
       end
 
-      # ---------- Helpers ----------
-
-      def safe_stream_info(jts, name)
-        jts.stream_info(name)
-      rescue NATS::JetStream::Error => e
-        return nil if stream_not_found?(e)
-        raise
-      end
-
-      def missing_subjects(existing, desired)
-        desired.reject { |d| SubjectMatcher.covered?(existing, d) }
-      end
+      # ---- tiny helpers extracted to reduce ABC ----
+      def add_subjects(jts, name, existing, to_add)
+        allowed, blocked = OverlapGuard.partition_allowed(jts, name, to_add)
+        return StreamSupport.log_all_blocked(name, blocked) if allowed.empty?
 
-      def normalize_subjects(list)
-        Array(list).flatten.compact.map!(&:to_s).reject(&:empty?).uniq
+        target = merge_subjects(existing, allowed)
+        OverlapGuard.check!(jts, name, target)
+        apply_update(jts, name, target)
+        StreamSupport.log_updated(name, allowed, blocked)
       end
 
-      def stream_not_found?(error)
-        msg = error.message.to_s
-        msg =~ /stream\s+not\s+found/i || msg =~ /\b404\b/
+      def merge_subjects(existing, allowed)
+        (existing + allowed).uniq
       end
 
-      def overlap_error?(error)
-        msg = error.message.to_s
-        msg =~ /subjects?\s+overlap/i || msg =~ /\berr_code=10065\b/ || msg =~ /\bstatus_code=400\b/
+      def config_needs_update?(info)
+        info.config.retention.to_s.downcase != RETENTION ||
+          info.config.storage.to_s.downcase != STORAGE
       end
 
-      # ---------- Logging wrappers ----------
-
-      def log_already_covered(name)
-        Logging.info("Stream #{name} exists; subjects already covered.", tag: 'JetstreamBridge::Stream')
+      def apply_update(jts, name, subjects)
+        jts.update_stream(
+          name: name,
+          subjects: subjects,
+          retention: RETENTION,
+          storage: STORAGE
+        )
       end
 
-      def log_all_blocked(name, blocked)
-        if blocked.any?
-          Logging.warn(
-            "Stream #{name}: all missing subjects are owned by other streams; leaving unchanged. " \
-            "blocked=#{blocked.inspect}",
-            tag: 'JetstreamBridge::Stream'
-          )
-        else
-          Logging.info("Stream #{name} exists; nothing to add.", tag: 'JetstreamBridge::Stream')
-        end
+      def log_config_updated(name)
+        Logging.info(
+          "Updated stream #{name} config; retention=#{RETENTION.inspect} " \
+          "storage=#{STORAGE.inspect}",
+          tag: 'JetstreamBridge::Stream'
+        )
       end
 
-      def log_updated(name, added, blocked)
-        msg = "Updated stream #{name}; added subjects=#{added.inspect}"
-        msg += " (skipped overlapped=#{blocked.inspect})" if blocked.any?
-        Logging.info(msg, tag: 'JetstreamBridge::Stream')
-      end
+      def ensure_create(jts, name, desired_subjects)
+        allowed, blocked = OverlapGuard.partition_allowed(jts, name, desired_subjects)
+        return StreamSupport.log_not_created(name, blocked) if allowed.empty?
 
-      def log_not_created(name, blocked)
-        Logging.warn(
-          "Not creating stream #{name}: all desired subjects are owned by other streams. " \
-          "blocked=#{blocked.inspect}",
-          tag: 'JetstreamBridge::Stream'
+        jts.add_stream(
+          name: name,
+          subjects: allowed,
+          retention: RETENTION,
+          storage: STORAGE
         )
+        StreamSupport.log_created(name, allowed, blocked, RETENTION, STORAGE)
       end
 
-      def log_created(name, allowed, blocked)
-        msg = "Created stream #{name} subjects=#{allowed.inspect}"
-        msg += " (skipped overlapped=#{blocked.inspect})" if blocked.any?
-        Logging.info(msg, tag: 'JetstreamBridge::Stream')
+      def safe_stream_info(jts, name)
+        jts.stream_info(name)
+      rescue NATS::JetStream::Error => e
+        return nil if StreamSupport.stream_not_found?(e)
+
+        raise
       end
     end
   end

data/lib/jetstream_bridge/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jetstream_bridge
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.3.0
 platform: ruby
 authors:
 - Mike Attara
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-20 00:00:00.000000000 Z
+date: 2025-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord