Release v4.2.0

attaradev · attaradev · commit 3894f284a2c2 · 2025-11-24T00:51:14.000Z
diff --git a/.rubocop.yml b/.rubocop.yml
@@ -30,7 +30,7 @@ Style/FrozenStringLiteralComment:
 
 Style/StringLiterals:
   EnforcedStyle: single_quotes
-  ConsistentQuotesInMultiline: true
+  ConsistentQuotesInMultiline: false
 
 Style/SymbolArray:
   EnforcedStyle: brackets
@@ -80,6 +80,7 @@ Metrics/CyclomaticComplexity:
     - "lib/jetstream_bridge/test_helpers.rb" # Test helper with complex setup
     - "lib/jetstream_bridge/core/logging.rb" # URL sanitization with multiple branches
     - "lib/jetstream_bridge/consumer/inbox/inbox_message.rb" # NATS message parsing
+    - "lib/jetstream_bridge/consumer/inbox/inbox_processor.rb" # Inbox processing with multiple branches
     - "lib/jetstream_bridge/core/connection.rb" # Connection validation with multiple checks
     - "lib/jetstream_bridge/core/debug_helper.rb" # Stream info with compatibility checks
     - "lib/jetstream_bridge/test_helpers/mock_nats.rb" # Mock NATS implementation
@@ -99,6 +100,7 @@ Metrics/ModuleLength:
   Exclude:
     - "lib/jetstream_bridge.rb" # Main module with convenience methods
     - "lib/jetstream_bridge/core/debug_helper.rb" # Debug helper with stream info methods
+    - "lib/jetstream_bridge/rails/integration.rb" # Rails integration with autostart logic
 
 Metrics/ClassLength:
   Max: 200
@@ -124,6 +126,7 @@ Naming/PredicatePrefix:
   Enabled: true
   Exclude:
     - "lib/jetstream_bridge/test_helpers.rb" # RSpec matcher convention uses have_*
+    - "lib/jetstream_bridge/test_helpers/matchers.rb" # RSpec matcher convention uses have_*
     - "lib/jetstream_bridge/core/model_utils.rb" # ActiveRecord introspection uses has_*
     - "lib/jetstream_bridge/models/outbox_event.rb" # ActiveRecord introspection uses has_*
     - "lib/jetstream_bridge/models/inbox_event.rb" # ActiveRecord introspection uses has_*
@@ -164,6 +167,7 @@ Style/OpenStructUse:
   Enabled: true
   Exclude:
     - "lib/jetstream_bridge/test_helpers.rb" # Test doubles for NATS messages
+    - "lib/jetstream_bridge/test_helpers/integration_helpers.rb" # Test doubles for NATS messages
     - "lib/jetstream_bridge/test_helpers/mock_nats.rb" # Mock NATS message objects
 
 # ---------- Packaging / Gemspec ----------
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,56 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.2.0] - 2025-11-24
+
+### Added
+
+- **Modular Code Organization** - Restructured codebase with dedicated modules
+  - New `JetstreamBridge::Core` module for core utilities (connection, logging, model utils, helpers)
+  - New `JetstreamBridge::Rails` module for Rails-specific integration
+  - Improved separation of concerns and code discoverability
+  - Better namespace organization for future extensibility
+
+- **Enhanced Test Helpers** - Comprehensive testing utilities split into focused modules
+  - `JetstreamBridge::TestHelpers::Fixtures` - Convenient fixture generation for events and messages
+  - `JetstreamBridge::TestHelpers::IntegrationHelpers` - Full NATS message simulation for integration tests
+  - `JetstreamBridge::TestHelpers::Matchers` - RSpec matchers for event publishing assertions
+  - Improved test doubles with realistic NATS message structure
+  - Better support for testing event-driven Rails applications
+
+- **Getting Started Guide** - New comprehensive guide in `docs/GETTING_STARTED.md`
+  - Quick installation and setup instructions
+  - Publishing and consuming examples
+  - Rails integration patterns
+  - Links to advanced documentation
+
+### Changed
+
+- **Rails Integration** - Reorganized Rails-specific code
+  - Moved from single `lib/jetstream_bridge/railtie.rb` to dedicated `lib/jetstream_bridge/rails/` directory
+  - `JetstreamBridge::Rails::Railtie` - Rails lifecycle integration
+  - `JetstreamBridge::Rails::Integration` - Autostart logic and Rails environment detection
+  - Cleaner separation between gem core and Rails integration
+
+- **Documentation** - Restructured README for clarity
+  - Condensed README focusing on quick start and highlights
+  - Moved detailed guides to dedicated docs directory
+  - Improved navigation with links to specialized documentation
+  - More concise examples and clearer feature descriptions
+
+- **Gemspec** - Enhanced package configuration
+  - Added `docs/**/*.md` to distributed files
+  - Added `extra_rdoc_files` for better documentation
+  - Updated description to emphasize production-readiness
+
+### Fixed
+
+- **Code Quality** - Resolved all RuboCop style violations
+  - Fixed string literal consistency issues
+  - Improved code formatting and indentation
+  - Reduced complexity in conditional assignments
+  - Updated RuboCop configuration for new file structure
+
 ## [4.1.0] - 2025-11-23
 
 ### Added
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jetstream_bridge (4.1.0)
+    jetstream_bridge (4.2.0)
       activerecord (>= 7.1.5.2, < 8.0)
       activesupport (>= 7.1.5.2, < 8.0)
       mutex_m
diff --git a/jetstream_bridge.gemspec b/jetstream_bridge.gemspec
@@ -10,10 +10,10 @@ Gem::Specification.new do |spec|
 
   spec.summary     = 'Production-safe realtime data bridge using NATS JetStream'
   spec.description = <<~DESC.strip
-    Publisher/Consumer utilities for NATS JetStream with environment-scoped subjects,
-    overlap guards, DLQ routing, retries/backoff, and optional Inbox/Outbox patterns.
-    Includes health checks, auto-reconnection, graceful shutdown, and topology setup
-    helpers for production-safe operation.
+    Production-ready publishers/consumers for NATS JetStream with environment-scoped
+    subjects, overlap guards, DLQ routing, retries/backoff, and optional inbox/outbox
+    patterns. Includes health checks, auto-reconnection, graceful shutdown, topology
+    setup helpers, and Rails generators.
   DESC
 
   spec.license  = 'MIT'
@@ -39,11 +39,13 @@ Gem::Specification.new do |spec|
       'lib/**/*.rake',
       'lib/**/templates/**/*',
       'README.md',
+      'docs/**/*.md',
       'LICENSE',
       'CHANGELOG.md'
     ].select { |f| File.file?(f) }
   end
 
+  spec.extra_rdoc_files = ['README.md', 'CHANGELOG.md', 'docs/GETTING_STARTED.md']
   spec.require_paths = ['lib']
 
   # Runtime dependencies
diff --git a/lib/jetstream_bridge/consumer/inbox/inbox_repository.rb b/lib/jetstream_bridge/consumer/inbox/inbox_repository.rb
@@ -11,13 +11,13 @@ def initialize(klass)
     end
 
     def find_or_build(msg)
-      if ModelUtils.has_columns?(@klass, :event_id)
-        record = @klass.find_or_initialize_by(event_id: msg.event_id)
-      elsif ModelUtils.has_columns?(@klass, :stream_seq)
-        record = @klass.find_or_initialize_by(stream_seq: msg.seq)
-      else
-        record = @klass.new
-      end
+      record = if ModelUtils.has_columns?(@klass, :event_id)
+                 @klass.find_or_initialize_by(event_id: msg.event_id)
+               elsif ModelUtils.has_columns?(@klass, :stream_seq)
+                 @klass.find_or_initialize_by(stream_seq: msg.seq)
+               else
+                 @klass.new
+               end
 
       lock_record(record)
     end
diff --git a/lib/jetstream_bridge/consumer/message_processor.rb b/lib/jetstream_bridge/consumer/message_processor.rb
@@ -63,7 +63,7 @@ def initialize(jts, handler, dlq: nil, backoff: nil, middleware_chain: nil)
     end
 
     def handle_message(msg, auto_ack: true)
-      ctx   = MessageContext.build(msg)
+      ctx = MessageContext.build(msg)
       event, early_action = parse_message(msg, ctx)
       return apply_action(msg, early_action) if early_action && auto_ack
       return early_action if early_action
diff --git a/lib/jetstream_bridge/core/connection.rb b/lib/jetstream_bridge/core/connection.rb
@@ -450,9 +450,8 @@ def sanitize_urls(urls)
     def cleanup_connection!(close_nc: true)
       begin
         # Avoid touching RSpec doubles used in unit tests
-        unless defined?(RSpec::Mocks::Double) && @nc.is_a?(RSpec::Mocks::Double)
-          @nc.close if close_nc && @nc&.respond_to?(:close) && @nc.connected?
-        end
+        is_rspec_double = defined?(RSpec::Mocks::Double) && @nc.is_a?(RSpec::Mocks::Double)
+        @nc.close if !is_rspec_double && close_nc && @nc.respond_to?(:close) && @nc.connected?
       rescue StandardError
         # ignore cleanup errors
       end
diff --git a/lib/jetstream_bridge/models/inbox_event.rb b/lib/jetstream_bridge/models/inbox_event.rb
@@ -174,8 +174,8 @@ def respond_to_missing?(_method_name, _include_private = false)
         def raise_missing_ar!(which, method_name)
           raise(
             "#{which} requires ActiveRecord (tried to call ##{method_name}). " \
-            "Enable `use_inbox` only in apps with ActiveRecord, or add " \
-            "`gem \"activerecord\"` to your Gemfile."
+            'Enable `use_inbox` only in apps with ActiveRecord, or add ' \
+            '`gem "activerecord"` to your Gemfile.'
           )
         end
       end
diff --git a/lib/jetstream_bridge/models/outbox_event.rb b/lib/jetstream_bridge/models/outbox_event.rb
@@ -169,8 +169,8 @@ def respond_to_missing?(_method_name, _include_private = false)
         def raise_missing_ar!(which, method_name)
           raise(
             "#{which} requires ActiveRecord (tried to call ##{method_name}). " \
-            "Enable `use_outbox` only in apps with ActiveRecord, or add " \
-            "`gem \"activerecord\"` to your Gemfile."
+            'Enable `use_outbox` only in apps with ActiveRecord, or add ' \
+            '`gem "activerecord"` to your Gemfile.'
           )
         end
       end
diff --git a/lib/jetstream_bridge/rails.rb b/lib/jetstream_bridge/rails.rb
@@ -2,4 +2,4 @@
 
 # Entry point for Rails-specific integration (lifecycle helpers + railtie)
 require_relative 'rails/integration'
-require_relative 'rails/railtie' if defined?(::Rails::Railtie)
+require_relative 'rails/railtie' if defined?(Rails::Railtie)
diff --git a/lib/jetstream_bridge/rails/integration.rb b/lib/jetstream_bridge/rails/integration.rb
@@ -31,11 +31,10 @@ def boot_bridge!
         auto_enable_test_mode!
 
         if autostart_disabled?
-          Logging.info(
-            "Auto-start skipped (reason: #{autostart_skip_reason}; " \
-            'enable via lazy_connect=false, unset JETSTREAM_BRIDGE_DISABLE_AUTOSTART, or set JETSTREAM_BRIDGE_FORCE_AUTOSTART=1)',
-            tag: 'JetstreamBridge::Railtie'
-          )
+          message = "Auto-start skipped (reason: #{autostart_skip_reason}; " \
+                    'enable via lazy_connect=false, unset JETSTREAM_BRIDGE_DISABLE_AUTOSTART, ' \
+                    'or set JETSTREAM_BRIDGE_FORCE_AUTOSTART=1)'
+          Logging.info(message, tag: 'JetstreamBridge::Railtie')
           return
         end
 
@@ -85,7 +84,7 @@ def autostart_skip_reason
       end
 
       def env_disables_autostart?
-        value = ENV['JETSTREAM_BRIDGE_DISABLE_AUTOSTART']
+        value = ENV.fetch('JETSTREAM_BRIDGE_DISABLE_AUTOSTART', nil)
         return false if value.nil?
 
         normalized = value.to_s.strip.downcase
@@ -95,7 +94,7 @@ def env_disables_autostart?
       end
 
       def force_autostart?
-        value = ENV['JETSTREAM_BRIDGE_FORCE_AUTOSTART']
+        value = ENV.fetch('JETSTREAM_BRIDGE_FORCE_AUTOSTART', nil)
         return false if value.nil?
 
         normalized = value.to_s.strip.downcase
diff --git a/lib/jetstream_bridge/test_helpers.rb b/lib/jetstream_bridge/test_helpers.rb
@@ -232,7 +232,6 @@ def trigger_jetstream_event(event, handler = nil)
       TestHelpers.record_consumed_event(event.to_h) if TestHelpers.test_mode?
       handler.call(event)
     end
-
   end
 end
 
diff --git a/lib/jetstream_bridge/topology/stream.rb b/lib/jetstream_bridge/topology/stream.rb
@@ -79,7 +79,7 @@ def log_config_updated(name, storage:)
     def log_retention_mismatch(name, have:, want:)
       Logging.warn(
         "Stream #{name} retention mismatch (have=#{have.inspect}, want=#{want.inspect}). " \
-        "Retention is immutable; skipping retention change.",
+        'Retention is immutable; skipping retention change.',
         tag: 'JetstreamBridge::Stream'
       )
     end
diff --git a/lib/jetstream_bridge/version.rb b/lib/jetstream_bridge/version.rb
@@ -4,5 +4,5 @@
 #
 # Version constant for the gem.
 module JetstreamBridge
-  VERSION = '4.1.0'
+  VERSION = '4.2.0'
 end
diff --git a/spec/consumer/subscription_manager_spec.rb b/spec/consumer/subscription_manager_spec.rb
@@ -75,13 +75,13 @@
       expect(manager.desired_consumer_cfg[:max_deliver]).to eq(5)
     end
 
-      it 'converts ack_wait to seconds' do
-        expect(manager.desired_consumer_cfg[:ack_wait]).to eq(30)
-      end
+    it 'converts ack_wait to seconds' do
+      expect(manager.desired_consumer_cfg[:ack_wait]).to eq(30)
+    end
 
-      it 'converts backoff array to seconds' do
-        expect(manager.desired_consumer_cfg[:backoff]).to eq([1, 5, 10])
-      end
+    it 'converts backoff array to seconds' do
+      expect(manager.desired_consumer_cfg[:backoff]).to eq([1, 5, 10])
+    end
   end
 
   describe '#ensure_consumer!' do
@@ -281,8 +281,8 @@
             ack_policy: 'explicit',
             deliver_policy: 'all',
             max_deliver: 5,
-            ack_wait: 30 * ::NATS::NANOSECONDS,
-            backoff: [1, 5].map { |s| s * ::NATS::NANOSECONDS }
+            ack_wait: 30 * NATS::NANOSECONDS,
+            backoff: [1, 5].map { |s| s * NATS::NANOSECONDS }
           },
           delivered: { consumer_seq: 0, stream_seq: 0, last_active: created_at },
           ack_floor: { consumer_seq: 0, stream_seq: 0, last_active: created_at },
diff --git a/spec/rails/integration_spec.rb b/spec/rails/integration_spec.rb
@@ -12,8 +12,8 @@
 
   around do |example|
     original_env = {
-      disable: ENV['JETSTREAM_BRIDGE_DISABLE_AUTOSTART'],
-      force: ENV['JETSTREAM_BRIDGE_FORCE_AUTOSTART']
+      disable: ENV.fetch('JETSTREAM_BRIDGE_DISABLE_AUTOSTART', nil),
+      force: ENV.fetch('JETSTREAM_BRIDGE_FORCE_AUTOSTART', nil)
     }
     example.run
     ENV['JETSTREAM_BRIDGE_DISABLE_AUTOSTART'] = original_env[:disable]
