nats_pubsub 1.0.0

data/lib/nats_pubsub/publisher/publish_result.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  # Immutable value object representing the result of a publish operation.
+  # Provides structured feedback instead of boolean returns, improving debuggability.
+  #
+  # @example Successful publish
+  #   result = publisher.publish_to_topic('notifications', { text: 'Hello' })
+  #   if result.success?
+  #     puts "Published with event_id: #{result.event_id}"
+  #   end
+  #
+  # @example Failed publish
+  #   result = publisher.publish_to_topic('invalid', { })
+  #   unless result.success?
+  #     puts "Failed: #{result.reason} - #{result.details}"
+  #   end
+  #
+  # @attr_reader success [Boolean] Whether publish succeeded
+  # @attr_reader event_id [String, nil] Event ID if successful
+  # @attr_reader subject [String, nil] NATS subject published to
+  # @attr_reader reason [Symbol, nil] Failure reason if unsuccessful
+  # @attr_reader details [String, nil] Detailed error message if unsuccessful
+  # @attr_reader error [Exception, nil] Original exception if available
+  class PublishResult
+    attr_reader :success, :event_id, :subject, :reason, :details, :error
+
+    # Create a successful publish result
+    #
+    # @param event_id [String] Event identifier
+    # @param subject [String] NATS subject
+    # @return [PublishResult] Success result
+    def self.success(event_id:, subject:)
+      new(success: true, event_id: event_id, subject: subject)
+    end
+
+    # Create a failed publish result
+    #
+    # @param reason [Symbol] Failure reason (:validation_error, :io_error, :timeout, etc.)
+    # @param details [String] Detailed error message
+    # @param subject [String, nil] NATS subject if known
+    # @param error [Exception, nil] Original exception
+    # @return [PublishResult] Failure result
+    def self.failure(reason:, details:, subject: nil, error: nil)
+      new(success: false, reason: reason, details: details, subject: subject, error: error)
+    end
+
+    # Initialize a PublishResult
+    #
+    # @param success [Boolean] Success flag
+    # @param event_id [String, nil] Event ID
+    # @param subject [String, nil] NATS subject
+    # @param reason [Symbol, nil] Failure reason
+    # @param details [String, nil] Error details
+    # @param error [Exception, nil] Original exception
+    def initialize(success:, event_id: nil, subject: nil, reason: nil, details: nil, error: nil)
+      @success = success
+      @event_id = event_id
+      @subject = subject
+      @reason = reason
+      @details = details
+      @error = error
+      freeze
+    end
+
+    # Check if publish was successful
+    #
+    # @return [Boolean] True if successful
+    def success?
+      @success
+    end
+
+    # Check if publish failed
+    #
+    # @return [Boolean] True if failed
+    def failure?
+      !@success
+    end
+
+    # Check if failure was due to validation error
+    #
+    # @return [Boolean] True if validation error
+    def validation_error?
+      @reason == :validation_error
+    end
+
+    # Check if failure was due to IO/network error
+    #
+    # @return [Boolean] True if IO error
+    def io_error?
+      @reason == :io_error
+    end
+
+    # Check if failure was due to timeout
+    #
+    # @return [Boolean] True if timeout
+    def timeout?
+      @reason == :timeout
+    end
+
+    # Get error message (for backward compatibility)
+    #
+    # @return [String, nil] Error message or nil if successful
+    def error_message
+      @details
+    end
+
+    # Convert to hash
+    #
+    # @return [Hash] Result as hash
+    def to_h
+      {
+        success: @success,
+        event_id: @event_id,
+        subject: @subject,
+        reason: @reason,
+        details: @details
+      }.compact
+    end
+
+    # String representation
+    #
+    # @return [String] Result description
+    def to_s
+      if success?
+        "PublishResult(success, event_id=#{@event_id}, subject=#{@subject})"
+      else
+        "PublishResult(failure, reason=#{@reason}, details=#{@details})"
+      end
+    end
+
+    # Inspect representation
+    #
+    # @return [String] Detailed inspection
+    def inspect
+      "#<PublishResult #{success? ? 'success' : 'failure'} #{to_h.inspect}>"
+    end
+
+    # For backward compatibility - acts like boolean in conditionals
+    #
+    # @return [Boolean] Success status
+    def to_bool
+      @success
+    end
+
+    # Allow result to be used in boolean contexts
+    alias to_boolean to_bool
+  end
+end

data/lib/nats_pubsub/publisher/publisher.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'oj'
+require_relative '../core/connection'
+require_relative '../core/logging'
+require_relative '../core/config'
+require_relative '../core/retry_strategy'
+require_relative '../models/model_utils'
+require_relative 'envelope_builder'
+require_relative 'outbox_repository'
+require_relative 'outbox_publisher'
+require_relative 'publish_result'
+require_relative 'publish_argument_parser'
+
+module NatsPubsub
+  # Publisher for PubSub events
+  # Provides a unified interface for publishing messages using either topics or domain/resource/action patterns
+  class Publisher
+    DEFAULT_RETRIES = 2
+
+    def initialize
+      @jts = Connection.connect!
+    end
+
+    # Publish a message using one of the supported patterns:
+    # 1. Topic-based: publish(topic, message, **opts) or publish(topic:, message:, **opts)
+    # 2. Domain/resource/action: publish(domain:, resource:, action:, payload:, **opts)
+    # 3. Multi-topic: publish(topics:, message:, **opts)
+    #
+    # @return [PublishResult] Result object with success status and details
+    #
+    # @example Topic-based (positional)
+    #   result = publisher.publish('orders.created', { order_id: '123' })
+    #
+    # @example Topic-based (keyword)
+    #   result = publisher.publish(topic: 'orders.created', message: { order_id: '123' })
+    #
+    # @example Domain/resource/action
+    #   result = publisher.publish(domain: 'orders', resource: 'order', action: 'created', payload: { id: '123' })
+    #
+    # @example Multi-topic
+    #   result = publisher.publish(topics: ['orders.created', 'notifications.sent'], message: { id: '123' })
+    def publish(*args, **kwargs)
+      parse_result = PublishArgumentParser.parse(*args, **kwargs)
+      parse_result.call(self)
+    end
+
+    # Publish to a single topic (internal method)
+    def publish_to_topic(topic, message, **options)
+      subject = EnvelopeBuilder.build_subject(topic)
+      envelope = EnvelopeBuilder.build_topic_envelope(topic, message, options)
+      event_id = envelope['event_id']
+
+      if NatsPubsub.config.use_outbox
+        OutboxPublisher.publish(
+          subject: subject,
+          envelope: envelope,
+          event_id: event_id
+        ) { with_retries { do_publish(subject, envelope, event_id) } }
+      else
+        with_retries { do_publish(subject, envelope, event_id) }
+      end
+    rescue StandardError => e
+      log_error(subject, event_id, e)
+    end
+
+    # Publish using domain/resource/action pattern (internal method)
+    def publish_event(domain, resource, action, payload, **options)
+      topic = "#{domain}.#{resource}.#{action}"
+      subject = EnvelopeBuilder.build_subject(topic)
+      envelope = EnvelopeBuilder.build_event_envelope(domain, resource, action, payload, options)
+      event_id = envelope['event_id']
+
+      if NatsPubsub.config.use_outbox
+        OutboxPublisher.publish(
+          subject: subject,
+          envelope: envelope,
+          event_id: event_id
+        ) { with_retries { do_publish(subject, envelope, event_id) } }
+      else
+        with_retries { do_publish(subject, envelope, event_id) }
+      end
+    rescue StandardError => e
+      log_error(subject, event_id, e)
+    end
+
+    # Publish to multiple topics (internal method)
+    def publish_to_topics(topics, message, **options)
+      results = {}
+      topics.each do |topic|
+        results[topic] = publish_to_topic(topic, message, **options)
+      end
+      results
+    end
+
+    private
+
+    def do_publish(subject, envelope, event_id)
+      headers = { 'nats-msg-id' => event_id }
+
+      ack = @jts.publish(subject, Oj.dump(envelope, mode: :compat), header: headers)
+      duplicate = ack.respond_to?(:duplicate?) && ack.duplicate?
+      msg = "Published #{subject} event_id=#{event_id}"
+      msg += ' (duplicate)' if duplicate
+
+      Logging.info(msg, tag: 'NatsPubsub::Publisher')
+
+      if ack.respond_to?(:error) && ack.error
+        Logging.error(
+          "Publish ack error: #{ack.error}",
+          tag: 'NatsPubsub::Publisher'
+        )
+        return PublishResult.failure(
+          reason: :publish_error,
+          details: "NATS ack error: #{ack.error}",
+          subject: subject,
+          error: ack.error
+        )
+      end
+
+      PublishResult.success(event_id: event_id, subject: subject)
+    end
+
+
+    # Retry only on transient NATS IO errors using RetryStrategy
+    def with_retries(retries = DEFAULT_RETRIES)
+      result = RetryStrategy.execute(retries: retries, operation_name: 'Publish') do
+        yield
+      end
+      result
+    rescue StandardError => e
+      # Return failure result for retry errors
+      subject = e.respond_to?(:subject) ? e.subject : 'unknown'
+      event_id = e.respond_to?(:event_id) ? e.event_id : 'unknown'
+      PublishResult.failure(
+        reason: :io_error,
+        details: "Retries exhausted: #{e.class} - #{e.message}",
+        subject: subject,
+        error: e
+      )
+    end
+
+    def log_error(subject, event_id, exc)
+      Logging.error(
+        "Publish failed: #{exc.class} #{exc.message}",
+        tag: 'NatsPubsub::Publisher'
+      )
+      PublishResult.failure(
+        reason: :exception,
+        details: "#{exc.class}: #{exc.message}",
+        subject: subject,
+        error: exc
+      )
+    end
+  end
+end

data/lib/nats_pubsub/rails/health_endpoint.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  module Rails
+    # Rails helper for NatsPubsub health check endpoints
+    #
+    # Provides easy integration with Rails routing and controllers.
+    #
+    # @example Rails routes
+    #   # config/routes.rb
+    #   require 'nats_pubsub/rails/health_endpoint'
+    #
+    #   Rails.application.routes.draw do
+    #     mount NatsPubsub::Rails::HealthEndpoint => '/nats-health'
+    #
+    #     # Or use individual endpoints
+    #     get '/health/nats', to: NatsPubsub::Rails::HealthEndpoint.full_check
+    #     get '/health/nats/quick', to: NatsPubsub::Rails::HealthEndpoint.quick_check
+    #     get '/health/nats/liveness', to: NatsPubsub::Rails::HealthEndpoint.liveness
+    #     get '/health/nats/readiness', to: NatsPubsub::Rails::HealthEndpoint.readiness
+    #   end
+    #
+    # @example Controller action
+    #   class HealthController < ApplicationController
+    #     def nats
+    #       render json: NatsPubsub::Rails::HealthEndpoint.check_health
+    #     end
+    #   end
+    #
+    class HealthEndpoint
+      # Rack application for health check endpoints
+      #
+      # Supports multiple endpoints:
+      # - GET / - Full health check
+      # - GET /quick - Quick connection check
+      # - GET /liveness - Liveness probe (always returns 200 if app is running)
+      # - GET /readiness - Readiness probe (checks if ready to accept traffic)
+      #
+      # @param env [Hash] Rack environment
+      # @return [Array] Rack response [status, headers, body]
+      def self.call(env)
+        request = ::Rack::Request.new(env)
+
+        case request.path_info
+        when '/', ''
+          full_check.call(env)
+        when '/quick'
+          quick_check.call(env)
+        when '/liveness'
+          liveness.call(env)
+        when '/readiness'
+          readiness.call(env)
+        else
+          not_found
+        end
+      end
+
+      # Full health check endpoint
+      #
+      # @return [Proc] Rack endpoint
+      def self.full_check
+        lambda do |_env|
+          result = Core::HealthCheck.check
+          status_code = http_status_for_health(result)
+
+          [
+            status_code,
+            { 'Content-Type' => 'application/json' },
+            [result.to_json]
+          ]
+        end
+      end
+
+      # Quick health check endpoint (connection only)
+      #
+      # @return [Proc] Rack endpoint
+      def self.quick_check
+        lambda do |_env|
+          result = Core::HealthCheck.quick_check
+          status_code = result.healthy? ? 200 : 503
+
+          [
+            status_code,
+            { 'Content-Type' => 'application/json' },
+            [result.to_json]
+          ]
+        end
+      end
+
+      # Liveness probe endpoint (Kubernetes-style)
+      #
+      # Always returns 200 if the application is running.
+      # Used to determine if the application should be restarted.
+      #
+      # @return [Proc] Rack endpoint
+      def self.liveness
+        lambda do |_env|
+          response = {
+            status: 'alive',
+            timestamp: Time.now.iso8601
+          }
+
+          [
+            200,
+            { 'Content-Type' => 'application/json' },
+            [response.to_json]
+          ]
+        end
+      end
+
+      # Readiness probe endpoint (Kubernetes-style)
+      #
+      # Returns 200 if the application is ready to accept traffic.
+      # Checks NATS connection and basic connectivity.
+      #
+      # @return [Proc] Rack endpoint
+      def self.readiness
+        lambda do |_env|
+          result = Core::HealthCheck.quick_check
+
+          response = {
+            status: result.healthy? ? 'ready' : 'not_ready',
+            healthy: result.healthy?,
+            components: result.components,
+            timestamp: Time.now.iso8601
+          }
+
+          status_code = result.healthy? ? 200 : 503
+
+          [
+            status_code,
+            { 'Content-Type' => 'application/json' },
+            [response.to_json]
+          ]
+        end
+      end
+
+      # Check health and return hash (for controller use)
+      #
+      # @return [Hash] Health check result
+      def self.check_health
+        Core::HealthCheck.check.to_h
+      end
+
+      # Check quick health and return hash (for controller use)
+      #
+      # @return [Hash] Quick health check result
+      def self.quick_health
+        Core::HealthCheck.quick_check.to_h
+      end
+
+      # Helper for Rails controller
+      #
+      # @example
+      #   class HealthController < ApplicationController
+      #     include NatsPubsub::Rails::HealthEndpoint::ControllerHelper
+      #
+      #     def nats
+      #       render_nats_health
+      #     end
+      #
+      #     def nats_quick
+      #       render_nats_health_quick
+      #     end
+      #   end
+      module ControllerHelper
+        # Render full health check
+        def render_nats_health
+          result = Core::HealthCheck.check
+          status_code = HealthEndpoint.http_status_for_health(result)
+
+          render json: result.to_h, status: status_code
+        end
+
+        # Render quick health check
+        def render_nats_health_quick
+          result = Core::HealthCheck.quick_check
+          status_code = result.healthy? ? 200 : 503
+
+          render json: result.to_h, status: status_code
+        end
+
+        # Render liveness check
+        def render_nats_liveness
+          render json: {
+            status: 'alive',
+            timestamp: Time.now.iso8601
+          }, status: 200
+        end
+
+        # Render readiness check
+        def render_nats_readiness
+          result = Core::HealthCheck.quick_check
+
+          render json: {
+            status: result.healthy? ? 'ready' : 'not_ready',
+            healthy: result.healthy?,
+            components: result.components,
+            timestamp: Time.now.iso8601
+          }, status: (result.healthy? ? 200 : 503)
+        end
+      end
+
+      class << self
+        # Determine HTTP status code from health result
+        #
+        # @param result [Core::HealthCheck::Result] Health check result
+        # @return [Integer] HTTP status code
+        def http_status_for_health(result)
+          case result.status
+          when :healthy
+            200
+          when :degraded
+            200 # Return 200 for degraded but still functional
+          when :unhealthy
+            503
+          else
+            503
+          end
+        end
+
+        private
+
+        def not_found
+          response = {
+            error: 'Not Found',
+            available_paths: ['/', '/quick', '/liveness', '/readiness']
+          }
+
+          [
+            404,
+            { 'Content-Type' => 'application/json' },
+            [response.to_json]
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/nats_pubsub/railtie.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'models/model_codec_setup'
+
+module NatsPubsub
+  class Railtie < ::Rails::Railtie
+    # Configuration before Rails initialization
+    config.before_configuration do
+      # Set default configuration from environment
+      NatsPubsub.configure do |config|
+        config.env = ENV.fetch('RAILS_ENV', 'development')
+        config.app_name = Rails.application.class.module_parent_name.underscore
+      end
+    end
+
+    # Model codec setup after ActiveRecord loads
+    initializer 'nats_pubsub.defer_model_tweaks', after: :active_record do
+      ActiveSupport.on_load(:active_record) do
+        ActiveSupport::Reloader.to_prepare do
+          NatsPubsub::ModelCodecSetup.apply!
+        end
+      end
+    end
+
+    # Validate configuration after initialization
+    initializer 'nats_pubsub.validate_config', after: :load_config_initializers do
+      Rails.application.config.after_initialize do
+        next unless NatsPubsub.configuration
+
+        begin
+          NatsPubsub.configuration.validate!
+        rescue NatsPubsub::ConfigurationError => e
+          Rails.logger.warn "[NatsPubsub] Configuration warning: #{e.message}"
+        end
+      end
+    end
+
+    # Auto-discover subscribers in development
+    initializer 'nats_pubsub.auto_discover_subscribers' do
+      Rails.application.config.to_prepare do
+        if Rails.env.development? || Rails.env.test?
+          NatsPubsub::Subscribers::Registry.instance.discover_subscribers!
+        end
+      end
+    end
+
+    # Load rake tasks
+    rake_tasks do
+      load File.expand_path('tasks/install.rake', __dir__)
+    end
+  end
+end

data/lib/nats_pubsub/subscribers/dlq_handler.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'oj'
+require 'time'
+require 'base64'
+require_relative '../core/logging'
+require_relative '../core/config'
+
+module NatsPubsub
+  module Subscribers
+    class DlqHandler
+      def initialize(jts)
+        @jts = jts
+      end
+
+      # Publishes failed message to Dead Letter Queue with explanatory headers/context
+      #
+      # @param msg [NATS::Msg] NATS message object
+      # @param ctx [MessageContext] Message context
+      # @param error_context [ErrorContext] Error context with failure details
+      # @return [Boolean] True if published successfully, false otherwise
+      def publish_to_dlq(msg, ctx, error_context:)
+        unless NatsPubsub.config.use_dlq
+          Logging.warn("DLQ disabled; skipping publish for event_id=#{ctx.event_id}", tag: 'NatsPubsub::Subscribers::DlqHandler')
+          return false
+        end
+
+        raw_base64 = Base64.strict_encode64(msg.data.to_s)
+        envelope = build_envelope(ctx, error_context, raw_base64)
+        headers  = build_headers(msg.header, error_context.reason, ctx.deliveries, envelope)
+        @jts.publish(NatsPubsub.config.dlq_subject, msg.data, header: headers)
+        true
+      rescue StandardError => e
+        Logging.error(
+          "DLQ publish failed event_id=#{ctx.event_id}: #{e.class} #{e.message}",
+          tag: 'NatsPubsub::Subscribers::DlqHandler'
+        )
+        false
+      end
+
+      private
+
+      def build_envelope(ctx, error_context, raw_base64)
+        {
+          event_id: ctx.event_id,
+          reason: error_context.reason,
+          error_class: error_context.error_class,
+          error_message: error_context.error_message,
+          deliveries: ctx.deliveries,
+          original_subject: ctx.subject,
+          sequence: ctx.seq,
+          consumer: ctx.consumer,
+          stream: ctx.stream,
+          published_at: Time.now.utc.iso8601,
+          raw_base64: raw_base64
+        }
+      end
+
+      def build_headers(original_headers, reason, deliveries, envelope)
+        headers = (original_headers || {}).dup
+        headers['x-dead-letter'] = 'true'
+        headers['x-dlq-reason']  = reason
+        headers['x-deliveries']  = deliveries.to_s
+        headers['x-dlq-context'] = Oj.dump(envelope, mode: :compat)
+        headers
+      end
+    end
+  end
+end