jetstream_bridge 2.2.1 → 2.4.0

data/lib/jetstream_bridge/core/duration.rb

@@ -4,43 +4,105 @@
 #
 module JetstreamBridge
   # Utility for parsing human-friendly durations into milliseconds.
+  #
+  # Defaults to an :auto heuristic for Integer/Float values to preserve
+  # backward compatibility:
+  #   - Integers < 1000 are treated as seconds (e.g., 30 -> 30_000ms)
+  #   - Integers >= 1000 are treated as milliseconds (e.g., 1500 -> 1500ms)
+  # Prefer setting `default_unit:` to :s or :ms for unambiguous behavior.
+  #
   # Examples:
-  #   Duration.to_millis(30)       #=> 30000
-  #   Duration.to_millis("30s")    #=> 30000
-  #   Duration.to_millis("500ms")  #=> 500
-  #   Duration.to_millis(0.5)      #=> 500
+  #   Duration.to_millis(30)                        #=> 30000   (auto)
+  #   Duration.to_millis(1500)                      #=> 1500    (auto)
+  #   Duration.to_millis(1500, default_unit: :s)    #=> 1_500_000
+  #   Duration.to_millis("30s")                     #=> 30000
+  #   Duration.to_millis("500ms")                   #=> 500
+  #   Duration.to_millis("250us")                   #=> 0
+  #   Duration.to_millis("1h")                      #=> 3_600_000
+  #   Duration.to_millis(1_500_000_000, default_unit: :ns) #=> 1500
+  #
+  # Also:
+  #   Duration.normalize_list_to_millis(%w[1s 5s 15s]) #=> [1000, 5000, 15000]
   module Duration
-    MULTIPLIER = { 'ms' => 1, 's' => 1_000, 'm' => 60_000, 'h' => 3_600_000 }.freeze
-    NUMBER_RE  = /\A\d+\z/.freeze
-    TOKEN_RE   = /\A(\d+(?:\.\d+)?)\s*(ms|s|m|h)\z/i.freeze
+    # multipliers to convert 1 unit into milliseconds
+    MULTIPLIER_MS = {
+      'ns' => 1.0e-6,     # nanoseconds to ms
+      'us' => 1.0e-3,     # microseconds to ms
+      'µs' => 1.0e-3,     # alt microseconds symbol
+      'ms' => 1,          # milliseconds to ms
+      's' => 1_000,       # seconds to ms
+      'm' => 60_000,      # minutes to ms
+      'h' => 3_600_000,   # hours to ms
+      'd' => 86_400_000   # days to ms
+    }.freeze
+
+    NUMBER_RE = /\A\d[\d_]*\z/.freeze
+    TOKEN_RE  = /\A(\d[\d_]*(?:\.\d+)?)\s*(ns|us|µs|ms|s|m|h|d)\z/i.freeze
 
     module_function
 
-    def to_millis(val)
-      return int_to_ms(val) if val.is_a?(Integer)
-      return float_to_ms(val) if val.is_a?(Float)
-      return string_to_ms(val) if val.is_a?(String)
-      return float_to_ms(val.to_f) if val.respond_to?(:to_f)
+    # default_unit:
+    #   :auto (heuristic: int<1000 -> seconds, >=1000 -> ms)
+    #   :ns, :us, :ms, :s, :m, :h, :d (explicit)
+    def to_millis(val, default_unit: :auto)
+      case val
+      when Integer then int_to_ms(val, default_unit: default_unit)
+      when Float   then float_to_ms(val, default_unit: default_unit)
+      when String  then string_to_ms(val, default_unit: default_unit == :auto ? :s : default_unit)
+      else
+        raise ArgumentError, "invalid duration type: #{val.class}" unless val.respond_to?(:to_f)
+
+        float_to_ms(val.to_f, default_unit: default_unit)
+
+      end
+    end
 
-      raise ArgumentError, "invalid duration type: #{val.class}"
+    # Normalize an array of durations into integer milliseconds.
+    def normalize_list_to_millis(values, default_unit: :auto)
+      Array(values).map { |v| to_millis(v, default_unit: default_unit) }
     end
 
-    def int_to_ms(i)
-      i >= 1_000 ? i : i * 1_000
+    # --- internal helpers ---
+
+    def int_to_ms(num, default_unit:)
+      case default_unit
+      when :auto
+        # Preserve existing heuristic for compatibility
+        i >= 1_000 ? num : num * 1_000
+      else
+        coerce_numeric_to_ms(i.to_f, default_unit)
+      end
     end
 
-    def float_to_ms(f)
-      (f * 1_000).round
+    def float_to_ms(flt, default_unit:)
+      coerce_numeric_to_ms(flt, default_unit)
     end
 
-    def string_to_ms(str)
+    def string_to_ms(str, default_unit:)
       s = str.strip
-      return int_to_ms(s.to_i) if NUMBER_RE.match?(s)
+      # Plain number string => use default_unit explicitly (not heuristic)
+      return coerce_numeric_to_ms(s.delete('_').to_f, default_unit) if NUMBER_RE.match?(s)
 
       m = TOKEN_RE.match(s)
       raise ArgumentError, "invalid duration: #{str.inspect}" unless m
 
-      (m[1].to_f * MULTIPLIER.fetch(m[2].downcase)).round
+      num   = m[1].delete('_').to_f
+      unit  = m[2].downcase
+      (num * MULTIPLIER_MS.fetch(unit)).round
+    end
+
+    def coerce_numeric_to_ms(num, unit)
+      case unit
+      when :auto
+        # For floats, :auto treats as seconds (common developer intent)
+        (num * 1_000).round
+      else
+        u = unit.to_s
+        mult = MULTIPLIER_MS[u]
+        raise ArgumentError, "invalid unit for default_unit: #{unit.inspect}" unless mult
+
+        (num * mult).round
+      end
     end
   end
 end

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.4.0'
 end

data/lib/jetstream_bridge.rb

@@ -46,7 +46,7 @@ module JetstreamBridge
       config.use_dlq
     end
 
-    def ensure_topology!
+    def ensure_topology?
       Connection.connect!
       true
     end

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: jetstream_bridge
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.4.0
 platform: ruby
 authors:
 - Mike Attara
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-20 00:00:00.000000000 Z
+date: 2025-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: activerecord
+  name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -25,7 +25,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '6.0'
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -53,33 +53,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.4'
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: oj
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '3.16'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
-- !ruby/object:Gem::Dependency
-  name: bundler-audit
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.9.1
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.9.1
+        version: '3.16'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -150,6 +136,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.1
 description: |-
   Publisher/Consumer utilities for NATS JetStream with environment-scoped subjects,
   overlap guards, DLQ routing, retries/backoff, and optional Inbox/Outbox patterns.
@@ -160,20 +160,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/release.yml"
-- ".gitignore"
-- ".idea/.gitignore"
-- ".idea/dictionaries/project.xml"
-- ".idea/jetstream_bridge.iml"
-- ".idea/misc.xml"
-- ".idea/modules.xml"
-- ".idea/vcs.xml"
-- ".rubocop.yml"
-- Gemfile
-- Gemfile.lock
-- LICENSE
-- README.md
-- jetstream_bridge.gemspec
 - 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
@@ -181,11 +167,14 @@ 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