jetstream_bridge 3.0.2 → 4.0.0

data/lib/jetstream_bridge/core/config_preset.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module JetstreamBridge
+  # Configuration presets for common scenarios
+  module ConfigPreset
+    # Development preset: minimal features for fast local development
+    #
+    # @param config [Config] Configuration object to apply preset to
+    def self.development(config)
+      config.use_outbox = false
+      config.use_inbox = false
+      config.use_dlq = false
+      config.max_deliver = 3
+      config.ack_wait = '10s'
+      config.backoff = %w[1s 2s 5s]
+    end
+
+    # Test preset: similar to development but with synchronous behavior
+    #
+    # @param config [Config] Configuration object to apply preset to
+    def self.test(config)
+      config.use_outbox = false
+      config.use_inbox = false
+      config.use_dlq = false
+      config.max_deliver = 2
+      config.ack_wait = '5s'
+      config.backoff = %w[0.1s 0.5s]
+    end
+
+    # Production preset: all reliability features enabled
+    #
+    # @param config [Config] Configuration object to apply preset to
+    def self.production(config)
+      config.use_outbox = true
+      config.use_inbox = true
+      config.use_dlq = true
+      config.max_deliver = 5
+      config.ack_wait = '30s'
+      config.backoff = %w[1s 5s 15s 30s 60s]
+    end
+
+    # Staging preset: production-like but with faster retries
+    #
+    # @param config [Config] Configuration object to apply preset to
+    def self.staging(config)
+      config.use_outbox = true
+      config.use_inbox = true
+      config.use_dlq = true
+      config.max_deliver = 3
+      config.ack_wait = '15s'
+      config.backoff = %w[1s 5s 15s]
+    end
+
+    # High throughput preset: optimized for volume over reliability
+    #
+    # @param config [Config] Configuration object to apply preset to
+    def self.high_throughput(config)
+      config.use_outbox = false # Skip DB writes
+      config.use_inbox = false # Skip deduplication
+      config.use_dlq = true # But keep DLQ for visibility
+      config.max_deliver = 3
+      config.ack_wait = '10s'
+      config.backoff = %w[1s 2s 5s]
+    end
+
+    # Maximum reliability preset: every safety feature enabled
+    #
+    # @param config [Config] Configuration object to apply preset to
+    def self.maximum_reliability(config)
+      config.use_outbox = true
+      config.use_inbox = true
+      config.use_dlq = true
+      config.max_deliver = 10
+      config.ack_wait = '60s'
+      config.backoff = %w[1s 5s 15s 30s 60s 120s 300s 600s 1200s 1800s]
+    end
+
+    # Get available preset names
+    #
+    # @return [Array<Symbol>] List of available preset names
+    def self.available_presets
+      [:development, :test, :production, :staging, :high_throughput, :maximum_reliability]
+    end
+
+    # Apply a preset by name
+    #
+    # @param config [Config] Configuration object
+    # @param preset_name [Symbol, String] Name of preset to apply
+    # @raise [ArgumentError] If preset name is unknown
+    def self.apply(config, preset_name)
+      preset_method = preset_name.to_sym
+      unless available_presets.include?(preset_method)
+        raise ArgumentError, "Unknown preset: #{preset_name}. Available: #{available_presets.join(', ')}"
+      end
+
+      public_send(preset_method, config)
+    end
+  end
+end

data/lib/jetstream_bridge/core/connection.rb

@@ -81,7 +81,10 @@ module JetstreamBridge
     # 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?
+      return false unless @nc&.connected?
+      return false unless @jts
+
+      jetstream_healthy?
     end
 
     # Public API for getting connection timestamp
@@ -141,7 +144,7 @@ module JetstreamBridge
       # Create JetStream context
       @jts = @nc.jetstream
 
-      # --- Compatibility shim: ensure JetStream responds to #nc for older/newer clients ---
+      # Ensure JetStream responds to #nc
       return if @jts.respond_to?(:nc)
 
       nc_ref = @nc

data/lib/jetstream_bridge/core/connection_factory.rb

@@ -89,7 +89,7 @@ module JetstreamBridge
         def create_jetstream(client)
           jts = client.jetstream
 
-          # Ensure JetStream responds to #nc for compatibility
+          # Ensure JetStream responds to #nc
           jts.define_singleton_method(:nc) { client } unless jts.respond_to?(:nc)
 
           jts

data/lib/jetstream_bridge/core/duration.rb

@@ -5,17 +5,14 @@
 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.
+  # Uses auto-detection heuristic by default: integers <1000 are treated as
+  # seconds, >=1000 as milliseconds. Strings with unit suffixes are supported
+  # (e.g., "30s", "500ms", "1h").
   #
   # Examples:
-  #   Duration.to_millis(30)                        #=> 30000   (auto)
-  #   Duration.to_millis(1500)                      #=> 1500    (auto)
-  #   Duration.to_millis("1500")                    #=> 1500    (auto)
-  #   Duration.to_millis(1500, default_unit: :s)    #=> 1_500_000
+  #   Duration.to_millis(2)                         #=> 2000 (auto: seconds)
+  #   Duration.to_millis(1500)                      #=> 1500 (auto: milliseconds)
+  #   Duration.to_millis(30, default_unit: :s)      #=> 30000
   #   Duration.to_millis("30s")                     #=> 30000
   #   Duration.to_millis("500ms")                   #=> 500
   #   Duration.to_millis("250us")                   #=> 0
@@ -43,8 +40,9 @@ module JetstreamBridge
     module_function
 
     # default_unit:
-    #   :auto (heuristic: int<1000 -> seconds, >=1000 -> ms)
-    #   :ns, :us, :ms, :s, :m, :h, :d (explicit)
+    #   :auto (default: heuristic - <1000 => seconds, >=1000 => milliseconds)
+    #   :ms (explicit milliseconds)
+    #   :ns, :us, :s, :m, :h, :d (explicit units)
     def to_millis(val, default_unit: :auto)
       case val
       when Integer then int_to_ms(val, default_unit: default_unit)
@@ -69,20 +67,7 @@ module JetstreamBridge
     # --- internal helpers ---
 
     def int_to_ms(num, default_unit:)
-      case default_unit
-      when :auto
-        # Preserve existing heuristic for compatibility but log deprecation warning
-        if defined?(Logging) && num.positive? && num < 1_000
-          Logging.debug(
-            "Duration :auto heuristic treating #{num} as seconds. " \
-            "Consider specifying default_unit: :s or :ms for clarity.",
-            tag: 'JetstreamBridge::Duration'
-          )
-        end
-        num >= 1_000 ? num : num * 1_000
-      else
-        coerce_numeric_to_ms(num.to_f, default_unit)
-      end
+      coerce_numeric_to_ms(num.to_f, default_unit)
     end
 
     def float_to_ms(flt, default_unit:)
@@ -104,17 +89,16 @@ module JetstreamBridge
     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
+      # Handle :auto unit with heuristic: <1000 => seconds, >=1000 => milliseconds
+      if unit == :auto
+        return (num < 1000 ? num * 1_000 : num).round
       end
+
+      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

data/lib/jetstream_bridge/errors.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 
 module JetstreamBridge
-  # Base error for all JetStream Bridge errors
-  class Error < StandardError; end
+  # Base error for all JetStream Bridge errors with context support
+  class Error < StandardError
+    attr_reader :context
+
+    def initialize(message = nil, context: {})
+      super(message)
+      @context = context.freeze
+    end
+  end
 
   # Configuration errors
   class ConfigurationError < Error; end
@@ -14,13 +21,47 @@ module JetstreamBridge
   class ConnectionNotEstablishedError < ConnectionError; end
   class HealthCheckFailedError < ConnectionError; end
 
-  # Publisher errors
-  class PublishError < Error; end
+  # Publisher errors with enriched context
+  class PublishError < Error
+    attr_reader :event_id, :subject
+
+    def initialize(message = nil, event_id: nil, subject: nil, context: {})
+      @event_id = event_id
+      @subject = subject
+      super(message, context: context.merge(event_id: event_id, subject: subject).compact)
+    end
+  end
+
   class PublishFailedError < PublishError; end
   class OutboxError < PublishError; end
 
-  # Consumer errors
-  class ConsumerError < Error; end
+  class BatchPublishError < PublishError
+    attr_reader :failed_events, :successful_count
+
+    def initialize(message = nil, failed_events: [], successful_count: 0, context: {})
+      @failed_events = failed_events
+      @successful_count = successful_count
+      super(
+        message,
+        context: context.merge(
+          failed_count: failed_events.size,
+          successful_count: successful_count
+        )
+      )
+    end
+  end
+
+  # Consumer errors with delivery context
+  class ConsumerError < Error
+    attr_reader :event_id, :deliveries
+
+    def initialize(message = nil, event_id: nil, deliveries: nil, context: {})
+      @event_id = event_id
+      @deliveries = deliveries
+      super(message, context: context.merge(event_id: event_id, deliveries: deliveries).compact)
+    end
+  end
+
   class HandlerError < ConsumerError; end
   class InboxError < ConsumerError; end
 
@@ -34,6 +75,17 @@ module JetstreamBridge
   class DlqError < Error; end
   class DlqPublishFailedError < DlqError; end
 
-  # Retry errors (already defined in retry_strategy.rb)
-  # class RetryExhausted < Error; end
+  # Retry errors
+  class RetryExhausted < Error
+    attr_reader :attempts, :original_error
+
+    def initialize(message = nil, attempts: 0, original_error: nil, context: {})
+      @attempts = attempts
+      @original_error = original_error
+      super(
+        message || "Failed after #{attempts} attempts: #{original_error&.message}",
+        context: context.merge(attempts: attempts).compact
+      )
+    end
+  end
 end

data/lib/jetstream_bridge/models/event.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module JetstreamBridge
+  module Models
+    # Structured event object provided to consumers
+    #
+    # @example Accessing event data in consumer
+    #   JetstreamBridge.subscribe do |event|
+    #     puts event.type              # "user.created"
+    #     puts event.payload.id        # 123
+    #     puts event.resource_type     # "user"
+    #     puts event.deliveries        # 1
+    #     puts event.metadata.trace_id # "abc123"
+    #   end
+    class Event
+      # Metadata associated with message delivery
+      Metadata = Struct.new(
+        :subject,
+        :deliveries,
+        :stream,
+        :sequence,
+        :consumer,
+        :timestamp,
+        keyword_init: true
+      ) do
+        def to_h
+          {
+            subject: subject,
+            deliveries: deliveries,
+            stream: stream,
+            sequence: sequence,
+            consumer: consumer,
+            timestamp: timestamp
+          }.compact
+        end
+      end
+
+      # Payload accessor with method-style access
+      class PayloadAccessor
+        def initialize(payload)
+          @payload = payload.is_a?(Hash) ? payload.transform_keys(&:to_s) : {}
+        end
+
+        def method_missing(method_name, *args)
+          return @payload[method_name.to_s] if args.empty? && @payload.key?(method_name.to_s)
+
+          super
+        end
+
+        def respond_to_missing?(method_name, _include_private = false)
+          @payload.key?(method_name.to_s) || super
+        end
+
+        def [](key)
+          @payload[key.to_s]
+        end
+
+        def dig(*keys)
+          @payload.dig(*keys.map(&:to_s))
+        end
+
+        def to_h
+          @payload
+        end
+
+        alias to_hash to_h
+      end
+
+      attr_reader :event_id, :type, :resource_type, :resource_id,
+                  :producer, :occurred_at, :trace_id, :schema_version,
+                  :metadata
+
+      # @param envelope [Hash] The raw event envelope
+      # @param metadata [Hash] Message delivery metadata
+      def initialize(envelope, metadata: {})
+        envelope = envelope.transform_keys(&:to_s) if envelope.respond_to?(:transform_keys)
+
+        @event_id = envelope['event_id']
+        @type = envelope['event_type']
+        @resource_type = envelope['resource_type']
+        @resource_id = envelope['resource_id']
+        @producer = envelope['producer']
+        @schema_version = envelope['schema_version'] || 1
+        @trace_id = envelope['trace_id']
+
+        @occurred_at = parse_time(envelope['occurred_at'])
+        @payload = PayloadAccessor.new(envelope['payload'] || {})
+        @metadata = build_metadata(metadata)
+        @raw_envelope = envelope
+
+        freeze
+      end
+
+      # Access payload with method-style syntax
+      #
+      # @example
+      #   event.payload.user_id  # Same as event.payload["user_id"]
+      #   event.payload.to_h     # Get raw payload hash
+      attr_reader :payload
+
+      # Get raw envelope hash
+      #
+      # @return [Hash] The original envelope
+      def to_envelope
+        @raw_envelope
+      end
+
+      # Get hash representation
+      #
+      # @return [Hash] Event as hash
+      def to_h
+        {
+          event_id: @event_id,
+          type: @type,
+          resource_type: @resource_type,
+          resource_id: @resource_id,
+          producer: @producer,
+          occurred_at: @occurred_at&.iso8601,
+          trace_id: @trace_id,
+          schema_version: @schema_version,
+          payload: @payload.to_h,
+          metadata: @metadata.to_h
+        }
+      end
+
+      alias to_hash to_h
+
+      # Number of times this message has been delivered
+      #
+      # @return [Integer] Delivery count
+      def deliveries
+        @metadata.deliveries || 1
+      end
+
+      # Subject this message was received on
+      #
+      # @return [String] NATS subject
+      def subject
+        @metadata.subject
+      end
+
+      # Stream this message came from
+      #
+      # @return [String, nil] Stream name
+      def stream
+        @metadata.stream
+      end
+
+      # Message sequence number in the stream
+      #
+      # @return [Integer, nil] Sequence number
+      def sequence
+        @metadata.sequence
+      end
+
+      def inspect
+        "#<#{self.class.name} id=#{@event_id} type=#{@type} deliveries=#{deliveries}>"
+      end
+
+      # Support hash-like access for backwards compatibility
+      def [](key)
+        case key.to_s
+        when 'event_id' then @event_id
+        when 'event_type' then @type
+        when 'resource_type' then @resource_type
+        when 'resource_id' then @resource_id
+        when 'producer' then @producer
+        when 'occurred_at' then @occurred_at&.iso8601
+        when 'trace_id' then @trace_id
+        when 'schema_version' then @schema_version
+        when 'payload' then @payload.to_h
+        else
+          @raw_envelope[key.to_s]
+        end
+      end
+
+      private
+
+      def build_metadata(meta)
+        Metadata.new(
+          subject: meta[:subject] || meta['subject'],
+          deliveries: meta[:deliveries] || meta['deliveries'] || 1,
+          stream: meta[:stream] || meta['stream'],
+          sequence: meta[:sequence] || meta['sequence'],
+          consumer: meta[:consumer] || meta['consumer'],
+          timestamp: Time.now.utc
+        )
+      end
+
+      def parse_time(value)
+        return nil if value.nil?
+        return value if value.is_a?(Time)
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/jetstream_bridge/{inbox_event.rb → models/inbox_event.rb}

@@ -67,21 +67,79 @@ module JetstreamBridge
 
       # ---- Defaults that do not require schema at load time ----
       before_validation do
-        self.status ||= 'received' if self.class.has_column?(:status) && status.blank?
+        self.status ||= JetstreamBridge::Config::Status::RECEIVED if self.class.has_column?(:status) && status.blank?
         self.received_at ||= Time.now.utc if self.class.has_column?(:received_at) && received_at.blank?
       end
 
-      # ---- Helpers ----
+      # ---- Query Scopes ----
+      scope :received, -> { where(status: JetstreamBridge::Config::Status::RECEIVED) if has_column?(:status) }
+      scope :processing, -> { where(status: JetstreamBridge::Config::Status::PROCESSING) if has_column?(:status) }
+      scope :processed, -> { where(status: JetstreamBridge::Config::Status::PROCESSED) if has_column?(:status) }
+      scope :failed, -> { where(status: JetstreamBridge::Config::Status::FAILED) if has_column?(:status) }
+      scope :by_subject, lambda { |subject|
+        where(subject: subject) if has_column?(:subject)
+      }
+      scope :by_stream, lambda { |stream|
+        where(stream: stream) if has_column?(:stream)
+      }
+      scope :recent, lambda { |limit = 100|
+        order(received_at: :desc).limit(limit) if has_column?(:received_at)
+      }
+      scope :unprocessed, lambda {
+        where.not(status: JetstreamBridge::Config::Status::PROCESSED) if has_column?(:status)
+      }
+
+      # ---- Class Methods ----
+      class << self
+        # Clean up old processed events
+        #
+        # @param older_than [ActiveSupport::Duration] Age threshold
+        # @return [Integer] Number of records deleted
+        def cleanup_processed(older_than: 30.days)
+          return 0 unless has_column?(:status) && has_column?(:processed_at)
+
+          processed.where('processed_at < ?', older_than.ago).delete_all
+        end
+
+        # Get processing statistics
+        #
+        # @return [Hash] Statistics hash
+        def processing_stats
+          return {} unless has_column?(:status)
+
+          {
+            total: count,
+            processed: processed.count,
+            failed: failed.count,
+            pending: unprocessed.count
+          }
+        end
+      end
+
+      # ---- Instance Methods ----
       def processed?
         if self.class.has_column?(:processed_at)
           processed_at.present?
         elsif self.class.has_column?(:status)
-          status == 'processed'
+          status == JetstreamBridge::Config::Status::PROCESSED
         else
           false
         end
       end
 
+      def mark_processed!
+        now = Time.now.utc
+        self.status = JetstreamBridge::Config::Status::PROCESSED if self.class.has_column?(:status)
+        self.processed_at = now if self.class.has_column?(:processed_at)
+        save!
+      end
+
+      def mark_failed!(err_msg)
+        self.status = JetstreamBridge::Config::Status::FAILED if self.class.has_column?(:status)
+        self.last_error = err_msg if self.class.has_column?(:last_error)
+        save!
+      end
+
       def payload_hash
         v = self[:payload]
         case v