nats_pubsub 1.0.0

data/lib/generators/nats_pubsub/migrations/templates/create_nats_pubsub_outbox.rb.erb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+class CreateNatsPubsubOutbox < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  # Disable DDL transaction for concurrent index creation
+  disable_ddl_transaction!
+
+  def up
+    # Idempotency check - safe to run multiple times
+    return if table_exists?(:nats_pubsub_outbox)
+
+    create_table :nats_pubsub_outbox do |t|
+      t.string  :event_id, null: false
+      t.string  :subject,  null: false
+      t.jsonb   :payload,  null: false, default: {}
+      t.jsonb   :headers,  null: false, default: {}
+      t.string  :status,   null: false, default: 'pending'  # pending|publishing|sent|failed
+      t.integer :attempts, null: false, default: 0
+      t.text    :last_error
+      t.datetime :enqueued_at
+      t.datetime :sent_at
+      t.timestamps
+    end
+
+    # Add indexes concurrently to avoid table locks
+    add_index :nats_pubsub_outbox, :event_id,
+              unique: true,
+              algorithm: :concurrently,
+              if_not_exists: true
+
+    add_index :nats_pubsub_outbox, :status,
+              algorithm: :concurrently,
+              if_not_exists: true
+
+    # Composite index for common queries (status + created_at)
+    add_index :nats_pubsub_outbox, [:status, :created_at],
+              algorithm: :concurrently,
+              if_not_exists: true,
+              name: 'index_outbox_on_status_and_created'
+
+    # Composite index for status + enqueued_at queries
+    add_index :nats_pubsub_outbox, [:status, :enqueued_at],
+              algorithm: :concurrently,
+              if_not_exists: true,
+              name: 'index_outbox_on_status_and_enqueued'
+
+    # Partial index for sent events (for cleanup queries)
+    add_index :nats_pubsub_outbox, :sent_at,
+              where: "status = 'sent'",
+              algorithm: :concurrently,
+              if_not_exists: true,
+              name: 'index_outbox_sent_at'
+
+    # Partial index for stale publishing records
+    add_index :nats_pubsub_outbox, :updated_at,
+              where: "status = 'publishing'",
+              algorithm: :concurrently,
+              if_not_exists: true,
+              name: 'index_outbox_stale_publishing'
+
+    # GIN index for JSONB payload queries (PostgreSQL only)
+    if ActiveRecord::Base.connection.adapter_name.downcase.include?('postgres')
+      add_index :nats_pubsub_outbox, :payload,
+                using: :gin,
+                algorithm: :concurrently,
+                if_not_exists: true,
+                name: 'index_outbox_payload_gin'
+    end
+
+    # Database-level constraint for status values
+    execute <<-SQL
+      ALTER TABLE nats_pubsub_outbox
+      ADD CONSTRAINT check_outbox_status_values
+      CHECK (status IN ('pending', 'publishing', 'sent', 'failed'))
+    SQL
+  end
+
+  def down
+    # Safe rollback with checks
+    drop_table :nats_pubsub_outbox if table_exists?(:nats_pubsub_outbox)
+  end
+end

data/lib/generators/nats_pubsub/subscriber/subscriber_generator.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module NatsPubsub
+  module Generators
+    # Subscriber generator that creates a new NatsPubsub subscriber class
+    #
+    # Usage:
+    #   rails generate nats_pubsub:subscriber NAME [topic1 topic2...] [options]
+    #
+    # Examples:
+    #   rails generate nats_pubsub:subscriber UserNotification
+    #   rails generate nats_pubsub:subscriber OrderProcessor orders.order
+    #   rails generate nats_pubsub:subscriber EmailHandler notifications.email --wildcard
+    #   rails generate nats_pubsub:subscriber AuditLogger --topics=audit.user audit.order
+    #
+    # Options:
+    #   --topics=one two three        Specify topics to subscribe to
+    #   --wildcard                    Use wildcard subscription (topic.>)
+    #   --skip-test                   Skip test file generation
+    #
+    # This will create:
+    #   app/subscribers/user_notification_subscriber.rb
+    #   spec/subscribers/user_notification_subscriber_spec.rb (if RSpec is detected)
+    #
+    # The generated subscriber will:
+    #   - Include NatsPubsub::Subscriber module
+    #   - Subscribe to specified topics
+    #   - Implement handle method stub
+    #   - Include error handling example
+    class SubscriberGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+      desc 'Creates a NatsPubsub subscriber class'
+
+      argument :topics_list, type: :array, default: [], banner: 'topic1 topic2...'
+
+      class_option :topics, type: :array, default: [],
+                            desc: 'Topics to subscribe to (alternative to positional args)'
+      class_option :wildcard, type: :boolean, default: false,
+                              desc: 'Use wildcard subscription (topic.>)'
+      class_option :skip_test, type: :boolean, default: false,
+                               desc: 'Skip test file generation'
+
+      def create_subscriber_file
+        template 'subscriber.rb.tt', File.join('app/subscribers', class_path, "#{file_name}_subscriber.rb")
+        say_status :created, "app/subscribers/#{file_name}_subscriber.rb", :green
+      rescue StandardError => e
+        say_status :error, "Failed to create subscriber: #{e.message}", :red
+        raise
+      end
+
+      def create_test_file
+        return if options[:skip_test]
+
+        if rspec_detected?
+          create_rspec_file
+        elsif test_unit_detected?
+          create_test_unit_file
+        else
+          say_status :skipped, 'No test framework detected', :yellow
+        end
+      rescue StandardError => e
+        say_status :error, "Failed to create test: #{e.message}", :red
+        # Don't raise - test generation failure shouldn't stop subscriber creation
+      end
+
+      private
+
+      def create_rspec_file
+        template 'subscriber_spec.rb.tt',
+                 File.join('spec/subscribers', class_path, "#{file_name}_subscriber_spec.rb")
+        say_status :created, "spec/subscribers/#{file_name}_subscriber_spec.rb", :green
+      end
+
+      def create_test_unit_file
+        template 'subscriber_test.rb.tt',
+                 File.join('test/subscribers', class_path, "#{file_name}_subscriber_test.rb")
+        say_status :created, "test/subscribers/#{file_name}_subscriber_test.rb", :green
+      end
+
+      def rspec_detected?
+        File.exist?(File.join(destination_root, 'spec', 'spec_helper.rb')) ||
+          File.exist?(File.join(destination_root, 'spec', 'rails_helper.rb'))
+      end
+
+      def test_unit_detected?
+        File.exist?(File.join(destination_root, 'test', 'test_helper.rb'))
+      end
+
+      # Get all topics from both positional args and --topics option
+      def all_topics
+        combined = topics_list + options[:topics]
+        combined.empty? ? default_topics : combined.uniq
+      end
+
+      # Default topics based on subscriber name
+      def default_topics
+        [file_name.pluralize.tr('_', '.')]
+      end
+
+      # Check if using wildcard subscription
+      def use_wildcard?
+        options[:wildcard]
+      end
+
+      # Generate subscription code
+      def subscription_code
+        if all_topics.empty?
+          "  # subscribe_to 'your.topic'\n  # subscribe_to_wildcard 'your.topic'"
+        elsif use_wildcard?
+          all_topics.map { |topic| "  subscribe_to_wildcard '#{topic}'" }.join("\n")
+        else
+          all_topics.map { |topic| "  subscribe_to '#{topic}'" }.join("\n")
+        end
+      end
+
+      # Generate example topic for comments
+      def example_topic
+        all_topics.first || 'your.topic'
+      end
+
+      # Check if subscriber name ends with 'Subscriber'
+      def needs_subscriber_suffix?
+        !class_name.end_with?('Subscriber')
+      end
+
+      # Get correct class name with Subscriber suffix
+      def subscriber_class_name
+        needs_subscriber_suffix? ? "#{class_name}Subscriber" : class_name
+      end
+
+      # Get correct file name
+      def subscriber_file_name
+        needs_subscriber_suffix? ? "#{file_name}_subscriber" : file_name
+      end
+    end
+  end
+end

data/lib/generators/nats_pubsub/subscriber/templates/subscriber.rb.tt

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+# <%= subscriber_class_name %> handles messages from NATS topics
+#
+# This subscriber listens to the following topic(s):
+<% all_topics.each do |topic| -%>
+#   - <%= topic %><%= use_wildcard? ? '.>' : '' %>
+<% end -%>
+#
+# Message format:
+#   {
+#     "event_id": "uuid",
+#     "domain": "domain_name",
+#     "resource": "resource_name",
+#     "action": "action_name",
+#     "data": { ... }
+#   }
+#
+# Context includes:
+#   - event_id: Unique event identifier
+#   - trace_id: Distributed tracing ID
+#   - deliveries: Number of delivery attempts
+#   - topic: The topic this message was published to
+#   - subject: Full NATS subject (env.app.domain.resource.action)
+class <%= subscriber_class_name %>
+  include NatsPubsub::Subscriber
+
+  # Subscribe to topics
+<%= subscription_code %>
+
+  # Configure JetStream options (optional)
+  # jetstream_options retry: 5, ack_wait: 30, max_deliver: 5
+
+  # Handle incoming messages
+  #
+  # @param message [Hash] The message payload
+  # @param context [NatsPubsub::Core::MessageContext] Message context
+  # @return [void]
+  #
+  # @example
+  #   {
+  #     "event_id" => "uuid",
+  #     "domain" => "<%= example_topic.split('.').first %>",
+  #     "resource" => "<%= example_topic.split('.')[1] || 'resource' %>",
+  #     "action" => "created",
+  #     "data" => { "id" => 1, "name" => "Example" }
+  #   }
+  def handle(message, context)
+    logger.info "Processing message: event_id=#{context.event_id} topic=#{context.topic}"
+
+    # Extract data from message
+    data = message['data'] || message
+    event_id = message['event_id']
+    action = message['action']
+
+    # TODO: Implement your message processing logic here
+    # Example:
+    # case action
+    # when 'created'
+    #   handle_created(data, context)
+    # when 'updated'
+    #   handle_updated(data, context)
+    # when 'deleted'
+    #   handle_deleted(data, context)
+    # else
+    #   logger.warn "Unknown action: #{action}"
+    # end
+
+    logger.info "Successfully processed: event_id=#{context.event_id}"
+  rescue StandardError => e
+    logger.error "Failed to process message: #{e.class}: #{e.message}"
+    logger.error e.backtrace.join("\n")
+    raise # Re-raise to trigger retry/DLQ logic
+  end
+
+  # Optional: Custom error handling
+  #
+  # Return an error action to control how errors are handled:
+  #   - NatsPubsub::Core::ErrorAction::RETRY   - Retry the message (default)
+  #   - NatsPubsub::Core::ErrorAction::DISCARD - Discard the message
+  #   - NatsPubsub::Core::ErrorAction::DLQ     - Send to dead letter queue
+  #
+  # @param error_context [NatsPubsub::Core::ErrorContext] Error context
+  # @return [Symbol] Error action
+  #
+  # @example
+  #   def on_error(error_context)
+  #     case error_context.error
+  #     when ActiveRecord::RecordNotFound
+  #       NatsPubsub::Core::ErrorAction::DISCARD
+  #     when Timeout::Error
+  #       NatsPubsub::Core::ErrorAction::RETRY
+  #     else
+  #       NatsPubsub::Core::ErrorAction::DLQ
+  #     end
+  #   end
+  # def on_error(error_context)
+  #   super
+  # end
+
+  private
+
+  # Example helper methods for different actions
+  # Uncomment and implement as needed
+
+  # def handle_created(data, context)
+  #   # Handle created events
+  # end
+
+  # def handle_updated(data, context)
+  #   # Handle updated events
+  # end
+
+  # def handle_deleted(data, context)
+  #   # Handle deleted events
+  # end
+end

data/lib/generators/nats_pubsub/subscriber/templates/subscriber_spec.rb.tt

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe <%= subscriber_class_name %>, nats_fake: true do
+  subject(:subscriber) { described_class.new }
+
+  describe '.all_subscriptions' do
+    it 'subscribes to correct topics' do
+<% all_topics.each do |topic| -%>
+      expect(described_class.all_subscriptions).to include(
+        hash_including(topic: '<%= topic %>')
+      )
+<% end -%>
+    end
+  end
+
+  describe '#handle' do
+    let(:event_id) { SecureRandom.uuid }
+    let(:trace_id) { SecureRandom.uuid }
+    let(:context) do
+      NatsPubsub::Core::MessageContext.new(
+        event_id: event_id,
+        trace_id: trace_id,
+        topic: '<%= example_topic %>',
+        subject: 'test.app.<%= example_topic %>',
+        deliveries: 1,
+        timestamp: Time.current
+      )
+    end
+
+    context 'with valid message' do
+      let(:message) do
+        {
+          'event_id' => event_id,
+          'domain' => '<%= example_topic.split('.').first %>',
+          'resource' => '<%= example_topic.split('.')[1] || 'resource' %>',
+          'action' => 'created',
+          'data' => {
+            'id' => 1,
+            'name' => 'Test <%= class_name %>'
+          }
+        }
+      end
+
+      it 'processes the message successfully' do
+        expect { subscriber.handle(message, context) }.not_to raise_error
+      end
+
+      it 'logs processing information' do
+        allow(Rails.logger).to receive(:info)
+
+        subscriber.handle(message, context)
+
+        expect(Rails.logger).to have_received(:info)
+          .with(/Processing message: event_id=#{event_id}/)
+      end
+
+      # TODO: Add specific assertions for your business logic
+      # it 'creates the expected record' do
+      #   expect { subscriber.handle(message, context) }
+      #     .to change { YourModel.count }.by(1)
+      # end
+    end
+
+    context 'with invalid message' do
+      let(:message) { {} }
+
+      it 'handles missing data gracefully' do
+        # TODO: Implement based on your error handling strategy
+        # expect { subscriber.handle(message, context) }.not_to raise_error
+        # OR
+        # expect { subscriber.handle(message, context) }.to raise_error(StandardError)
+      end
+    end
+
+    context 'when processing fails' do
+      let(:message) do
+        {
+          'event_id' => event_id,
+          'action' => 'created',
+          'data' => { 'id' => 1 }
+        }
+      end
+
+      before do
+        # Simulate a processing failure
+        # allow(YourService).to receive(:call).and_raise(StandardError, 'Processing failed')
+      end
+
+      it 'logs the error' do
+        # TODO: Implement based on your error handling
+        # allow(Rails.logger).to receive(:error)
+        # expect { subscriber.handle(message, context) }.to raise_error(StandardError)
+        # expect(Rails.logger).to have_received(:error)
+      end
+    end
+  end
+
+  # Optional: Test custom error handling
+  # describe '#on_error' do
+  #   let(:error_context) do
+  #     NatsPubsub::Core::ErrorContext.new(
+  #       error: StandardError.new('Test error'),
+  #       message: {},
+  #       context: double(event_id: 'test-id'),
+  #       attempts: 1
+  #     )
+  #   end
+  #
+  #   it 'returns appropriate error action' do
+  #     result = subscriber.on_error(error_context)
+  #     expect(result).to eq(NatsPubsub::Core::ErrorAction::RETRY)
+  #   end
+  # end
+end

data/lib/generators/nats_pubsub/subscriber/templates/subscriber_test.rb.tt

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class <%= subscriber_class_name %>Test < ActiveSupport::TestCase
+  def setup
+    @subscriber = <%= subscriber_class_name %>.new
+    @event_id = SecureRandom.uuid
+    @trace_id = SecureRandom.uuid
+    @context = NatsPubsub::Core::MessageContext.new(
+      event_id: @event_id,
+      trace_id: @trace_id,
+      topic: '<%= example_topic %>',
+      subject: 'test.app.<%= example_topic %>',
+      deliveries: 1,
+      timestamp: Time.current
+    )
+
+    # Enable fake mode for testing
+    NatsPubsub::Testing.fake!
+  end
+
+  def teardown
+    NatsPubsub::Testing.clear!
+  end
+
+  test 'subscribes to correct topics' do
+    subscriptions = <%= subscriber_class_name %>.all_subscriptions
+<% all_topics.each do |topic| -%>
+    assert_includes subscriptions.map { |s| s[:topic] }, '<%= topic %>'
+<% end -%>
+  end
+
+  test 'processes valid message successfully' do
+    message = {
+      'event_id' => @event_id,
+      'domain' => '<%= example_topic.split('.').first %>',
+      'resource' => '<%= example_topic.split('.')[1] || 'resource' %>',
+      'action' => 'created',
+      'data' => {
+        'id' => 1,
+        'name' => 'Test <%= class_name %>'
+      }
+    }
+
+    assert_nothing_raised do
+      @subscriber.handle(message, @context)
+    end
+  end
+
+  test 'logs processing information' do
+    message = {
+      'event_id' => @event_id,
+      'action' => 'created',
+      'data' => { 'id' => 1 }
+    }
+
+    Rails.logger.expects(:info).with(regexp_matches(/Processing message/))
+    @subscriber.handle(message, @context)
+  end
+
+  # TODO: Add specific test cases for your business logic
+  # test 'creates expected record' do
+  #   message = {
+  #     'event_id' => @event_id,
+  #     'action' => 'created',
+  #     'data' => { 'id' => 1, 'name' => 'Test' }
+  #   }
+  #
+  #   assert_difference 'YourModel.count', 1 do
+  #     @subscriber.handle(message, @context)
+  #   end
+  # end
+
+  test 'handles missing data' do
+    message = {}
+
+    # TODO: Implement based on your error handling strategy
+    # assert_nothing_raised do
+    #   @subscriber.handle(message, @context)
+    # end
+    # OR
+    # assert_raises StandardError do
+    #   @subscriber.handle(message, @context)
+    # end
+  end
+
+  test 'logs errors when processing fails' do
+    message = {
+      'event_id' => @event_id,
+      'action' => 'created',
+      'data' => { 'id' => 1 }
+    }
+
+    # Simulate a processing failure
+    # YourService.stubs(:call).raises(StandardError, 'Processing failed')
+
+    # TODO: Implement based on your error handling
+    # Rails.logger.expects(:error).at_least_once
+    # assert_raises StandardError do
+    #   @subscriber.handle(message, @context)
+    # end
+  end
+
+  # Optional: Test custom error handling
+  # test 'returns appropriate error action' do
+  #   error_context = NatsPubsub::Core::ErrorContext.new(
+  #     error: StandardError.new('Test error'),
+  #     message: {},
+  #     context: stub(event_id: 'test-id'),
+  #     attempts: 1
+  #   )
+  #
+  #   result = @subscriber.on_error(error_context)
+  #   assert_equal NatsPubsub::Core::ErrorAction::RETRY, result
+  # end
+end