nats_pubsub 1.0.0

data/lib/nats_pubsub/middleware/structured_logging.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative '../core/structured_logger'
+
+module NatsPubsub
+  module Middleware
+    # Structured logging middleware for message processing
+    # Logs with consistent JSON format and correlation IDs
+    class StructuredLogging
+      def initialize(logger: nil)
+        @logger = logger || Core::LoggerFactory.create_from_config(NatsPubsub.config)
+      end
+
+      def call(subscriber, payload, metadata)
+        start_time = Time.now
+        context = build_log_context(subscriber, payload, metadata)
+
+        logger.with_context(context).info('Processing message started')
+
+        begin
+          yield
+
+          elapsed_ms = ((Time.now - start_time) * 1000).round(2)
+          logger.with_context(context).info('Processing message completed', {
+            elapsed_ms: elapsed_ms,
+            status: 'success'
+          })
+        rescue StandardError => e
+          elapsed_ms = ((Time.now - start_time) * 1000).round(2)
+          logger.with_context(context).error('Processing message failed', {
+            elapsed_ms: elapsed_ms,
+            status: 'error',
+            error_class: e.class.name,
+            error_message: e.message,
+            backtrace: e.backtrace&.first(5)
+          })
+          raise
+        end
+      end
+
+      private
+
+      attr_reader :logger
+
+      def build_log_context(subscriber, payload, metadata)
+        {
+          subscriber: subscriber.class.name,
+          event_id: metadata[:event_id],
+          trace_id: metadata[:trace_id],
+          subject: metadata[:subject],
+          topic: metadata[:topic],
+          delivery_count: metadata[:deliveries] || 1
+        }.compact
+      end
+    end
+  end
+end

data/lib/nats_pubsub/models/event_model.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'oj'
+
+module NatsPubsub
+  # Shared behavior for ActiveRecord-based event models (Inbox/Outbox)
+  # Provides safe column checking, common validations, and payload handling
+  module EventModel
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(InstanceMethods)
+    end
+
+    module ClassMethods
+      # Safe column presence check that never boots a connection during class load.
+      # rubocop:disable Naming/PredicateNames
+      def has_column?(name)
+        return false unless ar_connected?
+
+        connection.schema_cache.columns_hash(table_name).key?(name.to_s)
+      rescue ActiveRecord::ConnectionNotEstablished, ActiveRecord::NoDatabaseError
+        false
+      end
+      # rubocop:enable Naming/PredicateNames
+
+      def ar_connected?
+        ActiveRecord::Base.connected? && connection_pool.active_connection?
+      rescue StandardError
+        false
+      end
+    end
+
+    module InstanceMethods
+      # Parse and return payload as a Hash
+      # Handles String (JSON), Hash, and objects with as_json
+      def payload_hash
+        v = self[:payload]
+        case v
+        when String
+          begin
+            Oj.load(v, mode: :strict)
+          rescue Oj::Error
+            {}
+          end
+        when Hash then v
+        else
+          v.respond_to?(:as_json) ? v.as_json : {}
+        end
+      end
+    end
+
+    # Create a shim class when ActiveRecord is not available
+    # @param class_name [String] Name of the class (e.g., 'InboxEvent')
+    # @param feature_name [String] Feature name for error message (e.g., 'Inbox')
+    def self.create_shim(class_name, feature_name)
+      Class.new do
+        class << self
+          define_method(:method_missing) do |method_name, *_args, &_block|
+            raise(
+              "#{feature_name} requires ActiveRecord (tried to call ##{method_name}). " \
+              "Enable `use_#{feature_name.downcase}` only in apps with ActiveRecord, or add " \
+              '`gem "activerecord"` to your Gemfile.'
+            )
+          end
+
+          def respond_to_missing?(_method_name, _include_private = false)
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nats_pubsub/models/inbox_event.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative 'event_model'
+
+begin
+  require 'active_record'
+rescue LoadError
+  # No-op; shim defined below.
+end
+
+module NatsPubsub
+  if defined?(ActiveRecord::Base)
+    class InboxEvent < ActiveRecord::Base
+      include EventModel
+
+      self.table_name = 'nats_pubsub_inbox'
+
+      # ---- Scopes for common queries ----
+      scope :received, -> { where(status: 'received') if has_column?(:status) }
+      scope :processing, -> { where(status: 'processing') if has_column?(:status) }
+      scope :processed, -> { where(status: 'processed') if has_column?(:status) }
+      scope :failed, -> { where(status: 'failed') if has_column?(:status) }
+      scope :unprocessed, -> { where(status: %w[received failed]) if has_column?(:status) }
+
+      scope :ready_to_process, lambda {
+        return none unless has_column?(:status)
+
+        where(status: 'received')
+          .order(:received_at)
+      }
+
+      scope :with_errors, lambda {
+        return none unless has_column?(:last_error)
+
+        where.not(last_error: nil)
+      }
+
+      scope :by_delivery_count, lambda { |count|
+        return none unless has_column?(:deliveries)
+
+        where(deliveries: count)
+      }
+
+      scope :for_cleanup, lambda { |retention_period = 30.days.ago|
+        return none unless has_column?(:status) && has_column?(:processed_at)
+
+        where(status: 'processed')
+          .where('processed_at < ?', retention_period)
+      }
+
+      scope :by_subject, ->(pattern) { where('subject LIKE ?', pattern) if has_column?(:subject) }
+      scope :recent, -> { order(received_at: :desc) if has_column?(:received_at) }
+      scope :oldest_first, -> { order(received_at: :asc) if has_column?(:received_at) }
+
+      # ---- Validations (NO with_options; guard everything with procs) ----
+
+      # Preferred dedupe key
+      validates :event_id,
+                presence: true,
+                uniqueness: true,
+                if: -> { self.class.has_column?(:event_id) }
+
+      # Fallback to (stream, stream_seq) when event_id column not present
+      validates :stream_seq,
+                presence: true,
+                if: -> { !self.class.has_column?(:event_id) && self.class.has_column?(:stream_seq) }
+
+      validates :stream_seq,
+                uniqueness: { scope: :stream },
+                if: lambda {
+                  !self.class.has_column?(:event_id) &&
+                    self.class.has_column?(:stream_seq) &&
+                    self.class.has_column?(:stream)
+                }
+
+      validates :stream_seq,
+                uniqueness: true,
+                if: lambda {
+                  !self.class.has_column?(:event_id) &&
+                    self.class.has_column?(:stream_seq) &&
+                    !self.class.has_column?(:stream)
+                }
+
+      validates :subject,
+                presence: true,
+                if: -> { self.class.has_column?(:subject) }
+
+      # ---- Defaults that do not require schema at load time ----
+      before_validation do
+        self.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 ----
+      def processed?
+        if self.class.has_column?(:processed_at)
+          processed_at.present?
+        elsif self.class.has_column?(:status)
+          status == 'processed'
+        else
+          false
+        end
+      end
+    end
+  else
+    # Shim: loud failure if AR isn't present but someone calls the model.
+    InboxEvent = EventModel.create_shim('InboxEvent', 'Inbox')
+  end
+end

data/lib/nats_pubsub/models/model_codec_setup.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'oj'
+
+module NatsPubsub
+  module ModelCodecSetup
+    module_function
+
+    def apply!
+      return unless ar_connected?
+
+      [NatsPubsub::OutboxEvent, NatsPubsub::InboxEvent].each { |k| apply_to(k) }
+    end
+
+    def apply_to(klass)
+      return unless table_exists_safely?(klass)
+
+      %w[payload headers].each do |attr|
+        next unless column?(klass, attr)
+        next if json_column?(klass, attr) || already_serialized?(klass, attr)
+
+        klass.serialize attr.to_sym, coder: Oj
+      end
+    rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished, ActiveRecord::NoDatabaseError
+      # ignore when schema isn’t available yet
+    end
+
+    # --- helpers ---
+
+    def ar_connected?
+      ActiveRecord::Base.connected?
+    rescue StandardError
+      false
+    end
+
+    def table_exists_safely?(klass)
+      klass.table_exists?
+    rescue StandardError
+      false
+    end
+
+    def column?(klass, attr)
+      klass.columns_hash.key?(attr)
+    rescue StandardError
+      false
+    end
+
+    def json_column?(klass, attr)
+      sql = klass.columns_hash.fetch(attr).sql_type.to_s.downcase
+      sql.include?('json') # covers json & jsonb
+    rescue StandardError
+      false
+    end
+
+    def already_serialized?(klass, attr)
+      klass.attribute_types.fetch(attr, nil).is_a?(ActiveRecord::Type::Serialized)
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/nats_pubsub/models/model_utils.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'oj'
+
+module NatsPubsub
+  module ModelUtils
+    module_function
+
+    def constantize(name)
+      name.to_s.split('::').reduce(Object) { |m, c| m.const_get(c) }
+    end
+
+    def ar_class?(klass)
+      defined?(ActiveRecord::Base) && klass <= ActiveRecord::Base
+    end
+
+    # rubocop:disable Naming/PredicatePrefix
+    def has_columns?(klass, *cols)
+      return false unless ar_class?(klass)
+
+      cols.flatten.all? { |c| klass.column_names.include?(c.to_s) }
+    end
+    # rubocop:enable Naming/PredicatePrefix
+
+    def assign_known_attrs(record, attrs)
+      attrs.each do |k, v|
+        setter = :"#{k}="
+        record.public_send(setter, v) if record.respond_to?(setter)
+      end
+    end
+
+    # find_or_initialize_by on the first keyset whose columns exist; else new
+    def find_or_init_by_best(klass, *keysets)
+      keysets.each do |keys|
+        next if keys.nil? || keys.empty?
+        return klass.find_or_initialize_by(keys) if has_columns?(klass, keys.keys)
+      end
+      klass.new
+    end
+
+    def json_dump(obj)
+      return obj if obj.is_a?(String)
+
+      Oj.dump(obj, mode: :compat)
+    rescue Oj::Error, TypeError
+      obj.to_s
+    end
+
+    def json_load(str)
+      return str if str.is_a?(Hash)
+
+      Oj.load(str.to_s, mode: :strict)
+    rescue Oj::Error
+      {}
+    end
+  end
+end

data/lib/nats_pubsub/models/outbox_event.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative 'event_model'
+
+begin
+  require 'active_record'
+rescue LoadError
+  # No-op; shim defined below.
+end
+
+module NatsPubsub
+  if defined?(ActiveRecord::Base)
+    class OutboxEvent < ActiveRecord::Base
+      include EventModel
+
+      self.table_name = 'nats_pubsub_outbox'
+
+      # ---- Scopes for common queries ----
+      scope :pending, -> { where(status: 'pending') if has_column?(:status) }
+      scope :publishing, -> { where(status: 'publishing') if has_column?(:status) }
+      scope :sent, -> { where(status: 'sent') if has_column?(:status) }
+      scope :failed, -> { where(status: 'failed') if has_column?(:status) }
+      scope :unsent, -> { where(status: %w[pending failed]) if has_column?(:status) }
+
+      scope :ready_to_publish, lambda {
+        return none unless has_column?(:status) && has_column?(:enqueued_at)
+
+        where(status: %w[pending failed])
+          .where('enqueued_at <= ?', Time.current)
+          .order(:enqueued_at)
+      }
+
+      scope :stale_publishing, lambda { |threshold = 5.minutes.ago|
+        return none unless has_column?(:status) && has_column?(:updated_at)
+
+        where(status: 'publishing')
+          .where('updated_at < ?', threshold)
+      }
+
+      scope :for_cleanup, lambda { |retention_period = 7.days.ago|
+        return none unless has_column?(:status) && has_column?(:sent_at)
+
+        where(status: 'sent')
+          .where('sent_at < ?', retention_period)
+      }
+
+      scope :by_subject, ->(pattern) { where('subject LIKE ?', pattern) if has_column?(:subject) }
+      scope :recent, -> { order(created_at: :desc) }
+      scope :oldest_first, -> { order(created_at: :asc) }
+
+      # ---- Validations guarded by safe schema checks (no with_options) ----
+      validates :payload,
+                presence: true,
+                if: -> { self.class.has_column?(:payload) }
+
+      # Preferred path when event_id exists
+      validates :event_id,
+                presence: true,
+                uniqueness: true,
+                if: -> { self.class.has_column?(:event_id) }
+
+      # Fallback legacy fields when event_id is absent
+      validates :resource_type,
+                presence: true,
+                if: lambda {
+                  !self.class.has_column?(:event_id) && self.class.has_column?(:resource_type)
+                }
+
+      validates :resource_id,
+                presence: true,
+                if: lambda {
+                  !self.class.has_column?(:event_id) && self.class.has_column?(:resource_id)
+                }
+
+      validates :event_type,
+                presence: true,
+                if: -> { !self.class.has_column?(:event_id) && self.class.has_column?(:event_type) }
+
+      validates :subject,
+                presence: true,
+                if: -> { self.class.has_column?(:subject) }
+
+      validates :attempts,
+                numericality: { only_integer: true, greater_than_or_equal_to: 0 },
+                if: -> { self.class.has_column?(:attempts) }
+
+      # ---- Defaults that do not require schema at load time ----
+      before_validation do
+        now = Time.now.utc
+        self.status ||= 'pending' if self.class.has_column?(:status) && status.blank?
+        self.enqueued_at ||= now if self.class.has_column?(:enqueued_at) && enqueued_at.blank?
+        self.attempts = 0 if self.class.has_column?(:attempts) && attempts.nil?
+      end
+
+      # ---- Helpers ----
+      def mark_sent!
+        now = Time.now.utc
+        self.status  = 'sent' if self.class.has_column?(:status)
+        self.sent_at = now    if self.class.has_column?(:sent_at)
+        save!
+      end
+
+      def mark_failed!(err_msg)
+        self.status     = 'failed' if self.class.has_column?(:status)
+        self.last_error = err_msg  if self.class.has_column?(:last_error)
+        save!
+      end
+    end
+  else
+    # Shim: loud failure if AR isn't present but someone calls the model.
+    OutboxEvent = EventModel.create_shim('OutboxEvent', 'Outbox')
+  end
+end

data/lib/nats_pubsub/publisher/envelope_builder.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative '../core/config'
+require_relative '../core/subject'
+
+module NatsPubsub
+  # Service object responsible for building message envelopes.
+  # Extracted from Publisher to follow Single Responsibility Principle.
+  #
+  # Supports three envelope formats:
+  # 1. Event envelope (domain/resource/action pattern)
+  # 2. Topic envelope (topic-based messaging)
+  # 3. Legacy envelope (backward compatibility)
+  class EnvelopeBuilder
+    # Build envelope for domain/resource/action events
+    # More specific name makes it clear this builds an event envelope
+    #
+    # @param domain [String] Domain name (e.g., 'users', 'orders')
+    # @param resource [String] Resource type (e.g., 'user', 'order')
+    # @param action [String] Action performed (e.g., 'created', 'updated')
+    # @param payload [Hash] Event payload
+    # @param options [Hash] Additional options
+    # @return [Hash] Event envelope
+    def self.build_event_envelope(domain, resource, action, payload, options = {})
+      {
+        'event_id' => options[:event_id] || SecureRandom.uuid,
+        'schema_version' => 1,
+        'domain' => domain.to_s,
+        'resource' => resource.to_s,
+        'action' => action.to_s,
+        'producer' => NatsPubsub.config.app_name,
+        'resource_id' => extract_resource_id(payload),
+        'occurred_at' => format_timestamp(options[:occurred_at]),
+        'trace_id' => options[:trace_id] || SecureRandom.hex(8),
+        'payload' => payload
+      }
+    end
+
+    # Build envelope for topic-based messages
+    # More specific name makes it clear this builds a topic envelope
+    #
+    # @param topic [String] Topic name
+    # @param message [Hash] Message payload
+    # @param options [Hash] Additional options
+    # @return [Hash] Topic envelope
+    def self.build_topic_envelope(topic, message, options = {})
+      envelope = {
+        'event_id' => options[:event_id] || SecureRandom.uuid,
+        'schema_version' => 1,
+        'topic' => topic.to_s,
+        'message_type' => options[:message_type]&.to_s,
+        'producer' => NatsPubsub.config.app_name,
+        'occurred_at' => format_timestamp(options[:occurred_at]),
+        'trace_id' => options[:trace_id] || SecureRandom.hex(8),
+        'message' => message
+      }
+
+      # Add domain/resource/action fields if provided (for backward compatibility)
+      envelope['domain'] = options[:domain].to_s if options[:domain]
+      envelope['resource'] = options[:resource].to_s if options[:resource]
+      envelope['action'] = options[:action].to_s if options[:action]
+      envelope['resource_id'] = options[:resource_id].to_s if options[:resource_id]
+
+      envelope.compact
+    end
+
+    # Build NATS subject for topic
+    # Delegates to Subject class for centralized subject building logic
+    #
+    # @param topic [String] Topic name
+    # @return [String] NATS subject
+    def self.build_subject(topic)
+      Subject.from_topic(
+        env: NatsPubsub.config.env,
+        app_name: NatsPubsub.config.app_name,
+        topic: topic
+      ).to_s
+    end
+
+    # Extract resource ID from payload
+    #
+    # @param payload [Hash] Event payload
+    # @return [String] Resource ID
+    def self.extract_resource_id(payload)
+      (payload['id'] || payload[:id]).to_s
+    end
+    private_class_method :extract_resource_id
+
+    # Format timestamp to ISO8601
+    #
+    # @param timestamp [Time, nil] Timestamp
+    # @return [String] ISO8601 formatted timestamp
+    def self.format_timestamp(timestamp)
+      (timestamp || Time.now.utc).iso8601
+    end
+    private_class_method :format_timestamp
+  end
+end