jetstream_bridge 3.0.2 → 4.0.0

data/lib/jetstream_bridge.rb

@@ -6,16 +6,59 @@ require_relative 'jetstream_bridge/core/duration'
 require_relative 'jetstream_bridge/core/logging'
 require_relative 'jetstream_bridge/core/connection'
 require_relative 'jetstream_bridge/publisher/publisher'
+require_relative 'jetstream_bridge/publisher/batch_publisher'
 require_relative 'jetstream_bridge/consumer/consumer'
+require_relative 'jetstream_bridge/consumer/middleware'
+require_relative 'jetstream_bridge/models/publish_result'
+require_relative 'jetstream_bridge/models/event'
 
 # If you have a Railtie for tasks/eager-loading
 require_relative 'jetstream_bridge/railtie' if defined?(Rails::Railtie)
 
 # Load gem-provided models from lib/
-require_relative 'jetstream_bridge/inbox_event'
-require_relative 'jetstream_bridge/outbox_event'
+require_relative 'jetstream_bridge/models/inbox_event'
+require_relative 'jetstream_bridge/models/outbox_event'
 
-# JetstreamBridge main module.
+# JetStream Bridge - Production-safe realtime data bridge using NATS JetStream.
+#
+# JetStream Bridge provides a reliable, production-ready way to publish and consume
+# events using NATS JetStream with features like:
+#
+# - Transactional Outbox pattern for guaranteed event publishing
+# - Idempotent Inbox pattern for exactly-once message processing
+# - Dead Letter Queue (DLQ) for poison message handling
+# - Automatic stream provisioning and overlap detection
+# - Built-in health checks and monitoring
+# - Middleware support for cross-cutting concerns
+# - Rails integration with generators and migrations
+#
+# @example Quick start
+#   # Configure
+#   JetstreamBridge.configure do |config|
+#     config.nats_urls = "nats://localhost:4222"
+#     config.env = "development"
+#     config.app_name = "my_app"
+#     config.destination_app = "other_app"
+#     config.use_outbox = true
+#     config.use_inbox = true
+#   end
+#
+#   # Publish events
+#   JetstreamBridge.publish(
+#     event_type: "user.created",
+#     payload: { id: 1, email: "ada@example.com" }
+#   )
+#
+#   # Consume events
+#   JetstreamBridge.subscribe do |event|
+#     puts "Received: #{event.type} - #{event.payload.to_h}"
+#   end.run!
+#
+# @see Publisher For publishing events
+# @see Consumer For consuming events
+# @see Config For configuration options
+# @see TestHelpers For testing utilities
+#
 module JetstreamBridge
   class << self
     def config
@@ -29,6 +72,25 @@ module JetstreamBridge
       cfg
     end
 
+    # Configure with a preset
+    #
+    # @example
+    #   JetstreamBridge.configure_for(:production) do |config|
+    #     config.nats_urls = ENV["NATS_URLS"]
+    #     config.app_name = "my_app"
+    #     config.destination_app = "worker"
+    #   end
+    #
+    # @param preset [Symbol] Preset name (:development, :test, :production, etc.)
+    # @yield [Config] Configuration object
+    # @return [Config] Configured instance
+    def configure_for(preset)
+      configure do |cfg|
+        cfg.apply_preset(preset)
+        yield(cfg) if block_given?
+      end
+    end
+
     def reset!
       @config = nil
     end
@@ -101,6 +163,119 @@ module JetstreamBridge
       fetch_stream_info
     end
 
+    # Convenience method to publish events
+    #
+    # Supports three usage patterns:
+    #
+    # 1. Structured parameters (recommended):
+    #    JetstreamBridge.publish(resource_type: 'user', event_type: 'created', payload: { id: 1, name: 'Ada' })
+    #
+    # 2. Simplified hash (infers resource_type from event_type):
+    #    JetstreamBridge.publish(event_type: 'user.created', payload: { id: 1, name: 'Ada' })
+    #
+    # 3. Complete envelope (advanced):
+    #    JetstreamBridge.publish({ event_type: 'created', resource_type: 'user', payload: {...}, event_id: '...' })
+    #
+    # @param event_or_hash [Hash, nil] Event hash or first positional argument
+    # @param resource_type [String, nil] Resource type (e.g., 'user', 'order')
+    # @param event_type [String, nil] Event type (e.g., 'created', 'updated', 'user.created')
+    # @param payload [Hash, nil] Event payload data
+    # @param subject [String, nil] Optional subject override
+    # @param options [Hash] Additional options (event_id, occurred_at, trace_id)
+    # @return [Models::PublishResult] Result object with success status and metadata
+    #
+    # @example Check result status
+    #   result = JetstreamBridge.publish(event_type: "user.created", payload: { id: 1 })
+    #   if result.success?
+    #     puts "Published event #{result.event_id}"
+    #   else
+    #     logger.error("Publish failed: #{result.error}")
+    #   end
+    def publish(event_or_hash = nil, resource_type: nil, event_type: nil, payload: nil, subject: nil, **)
+      publisher = Publisher.new
+      publisher.publish(event_or_hash, resource_type: resource_type, event_type: event_type, payload: payload,
+                                       subject: subject, **)
+    end
+
+    # Publish variant that raises on error
+    #
+    # @example
+    #   JetstreamBridge.publish!(event_type: "user.created", payload: { id: 1 })
+    #   # Raises PublishError if publishing fails
+    #
+    # @param (see #publish)
+    # @return [Models::PublishResult] Result object
+    # @raise [PublishError] If publishing fails
+    def publish!(...)
+      result = publish(...)
+      if result.failure?
+        raise PublishError.new(result.error&.message, event_id: result.event_id,
+                                                      subject: result.subject)
+      end
+
+      result
+    end
+
+    # Batch publish multiple events efficiently
+    #
+    # @example
+    #   results = JetstreamBridge.publish_batch do |batch|
+    #     users.each do |user|
+    #       batch.add(event_type: "user.created", payload: { id: user.id })
+    #     end
+    #   end
+    #   puts "Success: #{results.successful_count}, Failed: #{results.failed_count}"
+    #
+    # @yield [BatchPublisher] Batch publisher instance
+    # @return [BatchPublisher::BatchResult] Result with success/failure counts
+    def publish_batch
+      batch = BatchPublisher.new
+      yield(batch) if block_given?
+      batch.publish
+    end
+
+    # Convenience method to start consuming messages
+    #
+    # Supports two usage patterns:
+    #
+    # 1. With a block (recommended):
+    #    consumer = JetstreamBridge.subscribe do |event|
+    #      puts "Received: #{event.type} on #{event.subject} (attempt #{event.deliveries})"
+    #    end
+    #    consumer.run!
+    #
+    # 2. With auto-run (returns Thread):
+    #    thread = JetstreamBridge.subscribe(run: true) do |event|
+    #      puts "Received: #{event.type}"
+    #    end
+    #    thread.join # Wait for consumer to finish
+    #
+    # 3. With a handler object:
+    #    handler = ->(event) { puts event.type }
+    #    consumer = JetstreamBridge.subscribe(handler)
+    #    consumer.run!
+    #
+    # @param handler [Proc, #call, nil] Message handler (optional if block given)
+    # @param run [Boolean] If true, automatically runs consumer in a background thread
+    # @param durable_name [String, nil] Optional durable consumer name override
+    # @param batch_size [Integer, nil] Optional batch size override
+    # @yield [event] Yields Models::Event object to block
+    # @return [Consumer, Thread] Consumer instance or Thread if run: true
+    def subscribe(handler = nil, run: false, durable_name: nil, batch_size: nil, &block)
+      handler ||= block
+      raise ArgumentError, 'Handler or block required' unless handler
+
+      consumer = Consumer.new(handler, durable_name: durable_name, batch_size: batch_size)
+
+      if run
+        thread = Thread.new { consumer.run! }
+        thread.abort_on_exception = true
+        thread
+      else
+        consumer
+      end
+    end
+
     private
 
     def fetch_stream_info

data/lib/tasks/yard.rake

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new(:yard) do |t|
+    t.files = ['lib/**/*.rb']
+    t.options = ['--markup', 'markdown', '--readme', 'README.md']
+    t.stats_options = ['--list-undoc']
+  end
+
+  desc 'Generate YARD documentation and display stats'
+  task 'yard:stats' do
+    sh 'bundle exec yard stats --list-undoc'
+  end
+rescue LoadError
+  # YARD not available
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jetstream_bridge
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 4.0.0
 platform: ruby
 authors:
 - Mike Attara
@@ -127,8 +127,10 @@ files:
 - lib/jetstream_bridge/consumer/inbox/inbox_processor.rb
 - lib/jetstream_bridge/consumer/inbox/inbox_repository.rb
 - lib/jetstream_bridge/consumer/message_processor.rb
+- lib/jetstream_bridge/consumer/middleware.rb
 - lib/jetstream_bridge/consumer/subscription_manager.rb
 - lib/jetstream_bridge/core/config.rb
+- lib/jetstream_bridge/core/config_preset.rb
 - lib/jetstream_bridge/core/connection.rb
 - lib/jetstream_bridge/core/connection_factory.rb
 - lib/jetstream_bridge/core/debug_helper.rb
@@ -138,19 +140,24 @@ files:
 - lib/jetstream_bridge/core/model_utils.rb
 - lib/jetstream_bridge/core/retry_strategy.rb
 - lib/jetstream_bridge/errors.rb
-- lib/jetstream_bridge/inbox_event.rb
+- lib/jetstream_bridge/models/event.rb
 - lib/jetstream_bridge/models/event_envelope.rb
+- lib/jetstream_bridge/models/inbox_event.rb
+- lib/jetstream_bridge/models/outbox_event.rb
+- lib/jetstream_bridge/models/publish_result.rb
 - lib/jetstream_bridge/models/subject.rb
-- lib/jetstream_bridge/outbox_event.rb
+- lib/jetstream_bridge/publisher/batch_publisher.rb
 - lib/jetstream_bridge/publisher/outbox_repository.rb
 - lib/jetstream_bridge/publisher/publisher.rb
 - lib/jetstream_bridge/railtie.rb
 - lib/jetstream_bridge/tasks/install.rake
+- lib/jetstream_bridge/test_helpers.rb
 - lib/jetstream_bridge/topology/overlap_guard.rb
 - lib/jetstream_bridge/topology/stream.rb
 - lib/jetstream_bridge/topology/subject_matcher.rb
 - lib/jetstream_bridge/topology/topology.rb
 - lib/jetstream_bridge/version.rb
+- lib/tasks/yard.rake
 homepage: https://github.com/attaradev/jetstream_bridge
 licenses:
 - MIT
@@ -158,7 +165,7 @@ metadata:
   homepage_uri: https://github.com/attaradev/jetstream_bridge
   source_code_uri: https://github.com/attaradev/jetstream_bridge
   changelog_uri: https://github.com/attaradev/jetstream_bridge/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/attaradev/jetstream_bridge#readme
+  documentation_uri: https://rubydoc.info/gems/jetstream_bridge
   bug_tracker_uri: https://github.com/attaradev/jetstream_bridge/issues
   rubygems_mfa_required: 'true'
   allowed_push_host: https://rubygems.org