nats_pubsub 1.0.0

data/lib/nats_pubsub/core/subject.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  # Immutable value object representing a NATS subject.
+  # Provides validation, normalization, and pattern matching for NATS subjects.
+  #
+  # NATS subjects are dot-separated strings that support wildcards:
+  # - '*' matches exactly one token
+  # - '>' matches one or more tokens (only valid at end)
+  #
+  # @example Creating a subject
+  #   subject = Subject.new('production.myapp.users.created')
+  #   subject.tokens # => ['production', 'myapp', 'users', 'created']
+  #
+  # @example Pattern matching
+  #   pattern = Subject.new('production.*.users.*')
+  #   pattern.matches?('production.myapp.users.created') # => true
+  #
+  # @example Wildcard subjects
+  #   wildcard = Subject.new('production.myapp.>')
+  #   wildcard.wildcard? # => true
+  #   wildcard.matches?('production.myapp.users.created') # => true
+  class Subject
+    attr_reader :value, :tokens
+
+    # NATS subject constraints
+    MAX_LENGTH = 255
+    VALID_PATTERN = /\A[a-zA-Z0-9_.*>-]+(\.[a-zA-Z0-9_.*>-]+)*\z/
+
+    # Initialize a new Subject
+    #
+    # @param value [String, Subject] Subject string or another Subject
+    # @raise [ArgumentError] if subject is invalid
+    def initialize(value)
+      @value = value.is_a?(Subject) ? value.value : value.to_s
+      validate!
+      @tokens = @value.split('.')
+      freeze
+    end
+
+    # Build subject from domain, resource, and action
+    #
+    # @param env [String] Environment name
+    # @param app_name [String] Application name
+    # @param domain [String] Domain name
+    # @param resource [String] Resource type
+    # @param action [String] Action performed
+    # @return [Subject] New subject instance
+    def self.from_event(env:, app_name:, domain:, resource:, action:)
+      new("#{env}.#{app_name}.#{domain}.#{resource}.#{action}")
+    end
+
+    # Build subject for topic
+    #
+    # @param env [String] Environment name
+    # @param app_name [String] Application name
+    # @param topic [String] Topic name
+    # @return [Subject] New subject instance
+    def self.from_topic(env:, app_name:, topic:)
+      normalized_topic = normalize_topic(topic)
+      new("#{env}.#{app_name}.#{normalized_topic}")
+    end
+
+    # Normalize topic name for use in subjects
+    # Preserves dots for hierarchical topics and NATS wildcards
+    #
+    # @param topic [String] Topic name
+    # @return [String] Normalized topic name
+    def self.normalize_topic(topic)
+      topic.to_s.downcase.gsub(/[^a-z0-9_.>*-]/, '_')
+    end
+
+    # Check if subject contains wildcards
+    #
+    # @return [Boolean] True if contains * or >
+    def wildcard?
+      @value.include?('*') || @value.include?('>')
+    end
+
+    # Check if subject contains tail wildcard (>)
+    #
+    # @return [Boolean] True if ends with >
+    def tail_wildcard?
+      @value.end_with?('.>')
+    end
+
+    # Check if this subject/pattern matches another subject
+    # Note: Requires SubjectMatcher to be loaded
+    #
+    # @param other [String, Subject] Subject to match against
+    # @return [Boolean] True if matches
+    def matches?(other)
+      require_relative '../topology/subject_matcher' unless defined?(NatsPubsub::SubjectMatcher)
+      other_subject = other.is_a?(Subject) ? other : Subject.new(other)
+      SubjectMatcher.match?(@value, other_subject.value)
+    end
+
+    # Check if two subjects overlap (both could match the same message)
+    # Note: Requires SubjectMatcher to be loaded
+    #
+    # @param other [String, Subject] Subject to check overlap with
+    # @return [Boolean] True if subjects overlap
+    def overlaps?(other)
+      require_relative '../topology/subject_matcher' unless defined?(NatsPubsub::SubjectMatcher)
+      other_subject = other.is_a?(Subject) ? other : Subject.new(other)
+      SubjectMatcher.overlap?(@value, other_subject.value)
+    end
+
+    # Get the number of tokens in the subject
+    #
+    # @return [Integer] Token count
+    def token_count
+      @tokens.size
+    end
+
+    # Check if subject is empty
+    #
+    # @return [Boolean] True if empty
+    def empty?
+      @value.empty?
+    end
+
+    # String representation
+    #
+    # @return [String] Subject value
+    def to_s
+      @value
+    end
+
+    # Equality comparison
+    #
+    # @param other [Object] Object to compare
+    # @return [Boolean] True if equal
+    def ==(other)
+      case other
+      when Subject
+        @value == other.value
+      when String
+        @value == other
+      else
+        false
+      end
+    end
+
+    alias eql? ==
+
+    # Hash code for use in hash tables
+    #
+    # @return [Integer] Hash code
+    def hash
+      @value.hash
+    end
+
+    # Inspect representation
+    #
+    # @return [String] Inspection string
+    def inspect
+      "#<Subject:#{@value}>"
+    end
+
+    private
+
+    # Validate subject format
+    #
+    # @raise [ArgumentError] if invalid
+    def validate!
+      raise ArgumentError, 'Subject cannot be nil' if @value.nil?
+      raise ArgumentError, 'Subject cannot be empty' if @value.empty?
+      raise ArgumentError, "Subject too long (max #{MAX_LENGTH} chars)" if @value.length > MAX_LENGTH
+      raise ArgumentError, "Invalid subject format: #{@value}" unless @value =~ VALID_PATTERN
+      validate_wildcard_placement!
+    end
+
+    # Validate wildcard placement rules
+    #
+    # @raise [ArgumentError] if wildcard placement is invalid
+    def validate_wildcard_placement!
+      # '>' can only appear at the end
+      if @value.include?('>')
+        raise ArgumentError, "Wildcard '>' must be at the end of subject" unless @value.end_with?('.>')
+        raise ArgumentError, "Subject cannot contain multiple '>' wildcards" if @value.count('>') > 1
+      end
+    end
+  end
+end

data/lib/nats_pubsub/instrumentation.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  # Instrumentation for NatsPubsub using ActiveSupport::Notifications
+  #
+  # Provides instrumentation hooks for monitoring and observability.
+  #
+  # @example Subscribe to all events
+  #   ActiveSupport::Notifications.subscribe(/nats_pubsub/) do |name, start, finish, id, payload|
+  #     duration = (finish - start) * 1000
+  #     puts "#{name}: #{duration}ms"
+  #   end
+  #
+  # @example Subscribe to specific events
+  #   ActiveSupport::Notifications.subscribe('nats_pubsub.publish') do |*args|
+  #     event = ActiveSupport::Notifications::Event.new(*args)
+  #     puts "Published: #{event.payload[:subject]} in #{event.duration}ms"
+  #   end
+  #
+  module Instrumentation
+    # Available instrumentation events:
+    #
+    # - nats_pubsub.publish - Message publishing
+    # - nats_pubsub.receive - Message reception
+    # - nats_pubsub.process - Message processing
+    # - nats_pubsub.subscribe - Subscription creation
+    # - nats_pubsub.health_check - Health check execution
+    # - nats_pubsub.outbox.enqueue - Outbox event enqueued
+    # - nats_pubsub.outbox.publish - Outbox event published
+    # - nats_pubsub.inbox.store - Inbox event stored
+    # - nats_pubsub.inbox.process - Inbox event processed
+    # - nats_pubsub.connection.connect - Connection established
+    # - nats_pubsub.connection.disconnect - Connection closed
+    # - nats_pubsub.error - Error occurred
+
+    class << self
+      # Check if ActiveSupport::Notifications is available
+      #
+      # @return [Boolean] True if available
+      def available?
+        defined?(ActiveSupport::Notifications)
+      end
+
+      # Instrument a block of code
+      #
+      # @param event [String] Event name (will be prefixed with 'nats_pubsub.')
+      # @param payload [Hash] Event payload
+      # @yield Block to instrument
+      # @return [Object] Block result
+      #
+      # @example
+      #   Instrumentation.instrument('publish', subject: 'users.created') do
+      #     # Publishing code
+      #   end
+      def instrument(event, payload = {}, &block)
+        return yield unless available?
+
+        ActiveSupport::Notifications.instrument("nats_pubsub.#{event}", payload, &block)
+      end
+
+      # Publish an instrumentation event without a block
+      #
+      # @param event [String] Event name (will be prefixed with 'nats_pubsub.')
+      # @param payload [Hash] Event payload
+      #
+      # @example
+      #   Instrumentation.publish('error', error: e, context: context)
+      def publish(event, payload = {})
+        return unless available?
+
+        ActiveSupport::Notifications.publish("nats_pubsub.#{event}", payload)
+      end
+
+      # Subscribe to instrumentation events
+      #
+      # @param pattern [String, Regexp] Event pattern to subscribe to
+      # @yield Block to execute for matching events
+      # @return [Object] Subscription handle
+      #
+      # @example Subscribe to all events
+      #   Instrumentation.subscribe(/nats_pubsub/) do |event|
+      #     puts "Event: #{event.name}, Duration: #{event.duration}ms"
+      #   end
+      #
+      # @example Subscribe to specific event
+      #   Instrumentation.subscribe('nats_pubsub.publish') do |event|
+      #     puts "Published: #{event.payload[:subject]}"
+      #   end
+      def subscribe(pattern = /nats_pubsub/, &block)
+        return unless available?
+
+        ActiveSupport::Notifications.subscribe(pattern) do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          block.call(event)
+        end
+      end
+
+      # Unsubscribe from instrumentation events
+      #
+      # @param subscriber [Object] Subscription handle
+      def unsubscribe(subscriber)
+        return unless available?
+
+        ActiveSupport::Notifications.unsubscribe(subscriber)
+      end
+    end
+
+    # Publishing instrumentation
+    module Publisher
+      # Instrument message publishing
+      #
+      # @param subject [String] NATS subject
+      # @param payload [Hash] Message payload
+      # @yield Block performing the publish
+      def self.instrument_publish(subject:, **payload, &block)
+        Instrumentation.instrument('publish', { subject: subject }.merge(payload), &block)
+      end
+
+      # Instrument outbox enqueuing
+      #
+      # @param event_id [String] Event ID
+      # @param subject [String] NATS subject
+      # @yield Block performing the enqueue
+      def self.instrument_outbox_enqueue(event_id:, subject:, &block)
+        Instrumentation.instrument('outbox.enqueue', event_id: event_id, subject: subject, &block)
+      end
+
+      # Instrument outbox publishing
+      #
+      # @param event_id [String] Event ID
+      # @param subject [String] NATS subject
+      # @yield Block performing the publish
+      def self.instrument_outbox_publish(event_id:, subject:, &block)
+        Instrumentation.instrument('outbox.publish', event_id: event_id, subject: subject, &block)
+      end
+    end
+
+    # Subscriber instrumentation
+    module Subscriber
+      # Instrument message reception
+      #
+      # @param subject [String] NATS subject
+      # @param event_id [String] Event ID
+      # @yield Block receiving the message
+      def self.instrument_receive(subject:, event_id:, &block)
+        Instrumentation.instrument('receive', subject: subject, event_id: event_id, &block)
+      end
+
+      # Instrument message processing
+      #
+      # @param subject [String] NATS subject
+      # @param event_id [String] Event ID
+      # @param subscriber [String] Subscriber class name
+      # @yield Block processing the message
+      def self.instrument_process(subject:, event_id:, subscriber:, &block)
+        Instrumentation.instrument(
+          'process',
+          subject: subject,
+          event_id: event_id,
+          subscriber: subscriber,
+          &block
+        )
+      end
+
+      # Instrument inbox storage
+      #
+      # @param event_id [String] Event ID
+      # @param subject [String] NATS subject
+      # @yield Block storing the event
+      def self.instrument_inbox_store(event_id:, subject:, &block)
+        Instrumentation.instrument('inbox.store', event_id: event_id, subject: subject, &block)
+      end
+
+      # Instrument inbox processing
+      #
+      # @param event_id [String] Event ID
+      # @param subject [String] NATS subject
+      # @yield Block processing the event
+      def self.instrument_inbox_process(event_id:, subject:, &block)
+        Instrumentation.instrument('inbox.process', event_id: event_id, subject: subject, &block)
+      end
+
+      # Instrument subscription creation
+      #
+      # @param subject [String] NATS subject pattern
+      # @param subscriber [String] Subscriber class name
+      def self.instrument_subscribe(subject:, subscriber:)
+        Instrumentation.publish('subscribe', subject: subject, subscriber: subscriber)
+      end
+    end
+
+    # Connection instrumentation
+    module Connection
+      # Instrument connection establishment
+      #
+      # @param urls [Array<String>] NATS server URLs
+      # @yield Block establishing connection
+      def self.instrument_connect(urls:, &block)
+        Instrumentation.instrument('connection.connect', urls: urls, &block)
+      end
+
+      # Instrument connection close
+      #
+      # @param urls [Array<String>] NATS server URLs
+      def self.instrument_disconnect(urls:)
+        Instrumentation.publish('connection.disconnect', urls: urls)
+      end
+    end
+
+    # Health check instrumentation
+    module HealthCheck
+      # Instrument health check execution
+      #
+      # @param type [Symbol] Health check type (:full, :quick)
+      # @yield Block performing health check
+      def self.instrument_check(type: :full, &block)
+        Instrumentation.instrument('health_check', type: type, &block)
+      end
+    end
+
+    # Error instrumentation
+    module Error
+      # Instrument error occurrence
+      #
+      # @param error [Exception] Error that occurred
+      # @param context [Hash] Error context
+      def self.instrument_error(error:, **context)
+        Instrumentation.publish(
+          'error',
+          {
+            error_class: error.class.name,
+            error_message: error.message,
+            backtrace: error.backtrace&.first(5)
+          }.merge(context)
+        )
+      end
+    end
+
+    # Metrics collector for instrumentation events
+    #
+    # Collects metrics from ActiveSupport::Notifications events.
+    #
+    # @example Basic usage
+    #   collector = NatsPubsub::Instrumentation::MetricsCollector.new
+    #   collector.start
+    #
+    #   # Later
+    #   metrics = collector.metrics
+    #   puts "Published: #{metrics[:publish][:count]}"
+    #
+    class MetricsCollector
+      attr_reader :metrics, :subscriber
+
+      def initialize
+        @metrics = Hash.new do |h, k|
+          h[k] = { count: 0, total_duration: 0.0, errors: 0 }
+        end
+        @subscriber = nil
+        @started_at = nil
+      end
+
+      # Start collecting metrics
+      def start
+        return unless Instrumentation.available?
+        return if @subscriber
+
+        @started_at = Time.now
+        @subscriber = Instrumentation.subscribe do |event|
+          record_event(event)
+        end
+      end
+
+      # Stop collecting metrics
+      def stop
+        return unless @subscriber
+
+        Instrumentation.unsubscribe(@subscriber)
+        @subscriber = nil
+      end
+
+      # Reset metrics
+      def reset
+        @metrics.clear
+        @started_at = Time.now
+      end
+
+      # Get metrics summary
+      #
+      # @return [Hash] Metrics summary
+      def summary
+        {
+          uptime: uptime,
+          events: @metrics.transform_values do |stats|
+            {
+              count: stats[:count],
+              total_duration_ms: stats[:total_duration].round(2),
+              avg_duration_ms: avg_duration(stats),
+              errors: stats[:errors]
+            }
+          end
+        }
+      end
+
+      private
+
+      def record_event(event)
+        name = event.name.sub('nats_pubsub.', '')
+
+        @metrics[name][:count] += 1
+        @metrics[name][:total_duration] += event.duration if event.duration
+        @metrics[name][:errors] += 1 if name.include?('error')
+      end
+
+      def avg_duration(stats)
+        return 0.0 if stats[:count].zero?
+
+        (stats[:total_duration] / stats[:count]).round(2)
+      end
+
+      def uptime
+        return 0.0 unless @started_at
+
+        Time.now - @started_at
+      end
+    end
+  end
+end

data/lib/nats_pubsub/middleware/active_record.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  module Middleware
+    # Middleware that ensures ActiveRecord connections are properly managed
+    class ActiveRecord
+      def call(_subscriber, _payload, _metadata, &)
+        if defined?(::ActiveRecord::Base)
+          ::ActiveRecord::Base.connection_pool.with_connection(&)
+        else
+          yield
+        end
+      ensure
+        ::ActiveRecord::Base.clear_active_connections! if defined?(::ActiveRecord::Base)
+      end
+    end
+  end
+end

data/lib/nats_pubsub/middleware/chain.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  module Middleware
+    # Middleware chain for processing messages through multiple middleware layers.
+    # Similar to Rack middleware or Sidekiq middleware.
+    class Chain
+      def initialize
+        @entries = []
+      end
+
+      # Add middleware to the chain
+      #
+      # @param klass [Class] Middleware class
+      # @param args [Array] Arguments to pass to middleware constructor
+      # @param kwargs [Hash] Keyword arguments to pass to middleware constructor
+      def add(klass, *args, **kwargs)
+        @entries << [klass, args, kwargs]
+      end
+
+      # Remove middleware from the chain
+      #
+      # @param klass [Class] Middleware class to remove
+      def remove(klass)
+        @entries.delete_if { |(k, _, _)| k == klass }
+      end
+
+      # Clear all middleware
+      def clear
+        @entries.clear
+      end
+
+      # Check if chain is empty
+      #
+      # @return [Boolean]
+      def empty?
+        @entries.empty?
+      end
+
+      # Get count of middleware in chain
+      #
+      # @return [Integer]
+      def size
+        @entries.size
+      end
+
+      # Invoke the middleware chain
+      #
+      # @param subscriber [Object] Subscriber instance
+      # @param payload [Hash] Event payload
+      # @param metadata [Hash] Event metadata
+      # @yield Block to execute after all middleware
+      def invoke(subscriber, payload, metadata, &)
+        chain = build_chain
+        traverse(chain, subscriber, payload, metadata, &)
+      end
+
+      private
+
+      # Build middleware instances from entries
+      #
+      # @return [Array] Array of middleware instances
+      def build_chain
+        @entries.map do |(klass, args, kwargs)|
+          if kwargs.empty?
+            klass.new(*args)
+          else
+            klass.new(*args, **kwargs)
+          end
+        end
+      end
+
+      # Recursively traverse the middleware chain
+      #
+      # @param chain [Array] Remaining middleware in chain
+      # @param subscriber [Object] Subscriber instance
+      # @param payload [Hash] Event payload
+      # @param metadata [Hash] Event metadata
+      # @yield Block to execute at the end
+      def traverse(chain, subscriber, payload, metadata, &block)
+        if chain.empty?
+          yield
+        else
+          middleware = chain.shift
+          middleware.call(subscriber, payload, metadata) do
+            traverse(chain, subscriber, payload, metadata, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nats_pubsub/middleware/logging.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative '../core/logging'
+
+module NatsPubsub
+  module Middleware
+    # Middleware that logs message processing start and completion
+    class Logging
+      def call(subscriber, _payload, metadata)
+        start = Time.now
+
+        log_start(subscriber, metadata)
+
+        yield
+
+        elapsed = ((Time.now - start) * 1000).round(2)
+        log_complete(subscriber, metadata, elapsed)
+      rescue StandardError => e
+        elapsed = ((Time.now - start) * 1000).round(2)
+        log_error(subscriber, metadata, elapsed, e)
+        raise
+      end
+
+      private
+
+      def log_start(subscriber, metadata)
+        NatsPubsub::Logging.info(
+          "Processing #{metadata[:subject]} with #{subscriber.class.name} (attempt #{metadata[:deliveries]})",
+          tag: 'NatsPubsub::Middleware::Logging'
+        )
+      end
+
+      def log_complete(subscriber, _metadata, elapsed)
+        NatsPubsub::Logging.info(
+          "Completed #{subscriber.class.name} in #{elapsed}ms",
+          tag: 'NatsPubsub::Middleware::Logging'
+        )
+      end
+
+      def log_error(subscriber, _metadata, elapsed, error)
+        NatsPubsub::Logging.error(
+          "Failed #{subscriber.class.name} after #{elapsed}ms: #{error.class} #{error.message}",
+          tag: 'NatsPubsub::Middleware::Logging'
+        )
+      end
+    end
+  end
+end

data/lib/nats_pubsub/middleware/retry_logger.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../core/logging'
+
+module NatsPubsub
+  module Middleware
+    # Middleware that logs retry attempts
+    class RetryLogger
+      def call(subscriber, _payload, metadata)
+        if metadata[:deliveries] && metadata[:deliveries] > 1
+          max_deliver = NatsPubsub.config.max_deliver
+
+          NatsPubsub::Logging.warn(
+            "Retrying #{metadata[:subject]} with #{subscriber.class.name} " \
+            "(attempt #{metadata[:deliveries]}/#{max_deliver})",
+            tag: 'NatsPubsub::Middleware::RetryLogger'
+          )
+        end
+
+        yield
+      end
+    end
+  end
+end