jetstream_bridge 7.1.3 → 7.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 960c62e2e115e43f9e9f850adda06a2fd9337a72ad0eb09f1b0e99be53b4b0c3
-  data.tar.gz: 011f110e84e31b9fbc69c388c34d4c1be47bba2bb44ba4c5a1f5ce8318aa7e8a
+  metadata.gz: c558d8852741ad943ccc0028d906690da3495114a144f14319e61ee00bf5fb1e
+  data.tar.gz: 86aafa9188755f32a71de67b356f99911585c166bbc93450454677330c46f1ae
 SHA512:
-  metadata.gz: 89233b76d7cf91b0977e78ec9b08fc12ddec28361da16db0fe84ea573e36fd49491515809ecd8ae1de583869974e5a123808dee98366bf0ce0ec6acd52e64402
-  data.tar.gz: 3e15d5f11c6407af7bd76cd11ac1978bd6fe663d9f72fb08e3f284f7138f8bc12454b3a46f0e3341d8f3c4132e4849e040a09b296708cef1ea16b63659aacf68
+  metadata.gz: 41f0d7e69e12f60d901e1fef56752bf26d2809e317b63ddbc45eeac1126855ea11b601347f5faed749e1ea04fa612746e84f3ac0173361d5bc22874c5eb186ee
+  data.tar.gz: 69e8caf822d7591a4e34a94c9bbdf000509d0261e09ac19e49ea402061735d433709e0d2e2328eee8979c6300f6bbe3f7a8055de0097f79d97ffae4d1bb5af72

data/CHANGELOG.md

@@ -5,6 +5,13 @@ 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).
 
+## [7.1.4] - 2026-02-13
+
+### Fixed
+
+- **Documentation accuracy** - Fixed ~20 inaccuracies in `docs/` where method names, parameters, and examples had drifted from the source.
+- **YARD inline docs** - Added `@param`, `@return`, `@raise` tags across all public API surfaces.
+
 ## [7.1.3] - 2026-02-13
 
 ### Fixed

data/docs/API.md

@@ -34,7 +34,6 @@ JetstreamBridge.configure do |config|
   config.use_dlq    = true   # Dead letter queue for poison messages
 
   # Consumer settings
-  config.durable_name = "#{app_name}-workers"
   config.max_deliver  = 5     # Max delivery attempts
   config.ack_wait     = "30s" # Time to wait for ACK
   config.backoff      = ["1s", "5s", "15s", "30s", "60s"]
@@ -51,7 +50,7 @@ end
 
 ### `JetstreamBridge.config`
 
-Returns the current configuration object (read-only).
+Returns the current configuration object, creating a default instance if needed.
 
 ```ruby
 stream_name = JetstreamBridge.config.stream_name
@@ -67,6 +66,8 @@ Explicitly start the connection and provision topology (if `auto_provision=true`
 JetstreamBridge.startup!
 ```
 
+**Raises:** `ConfigurationError`, `ConnectionError`
+
 **Note:** Rails applications auto-start after initialization. Non-Rails apps should call this manually or rely on auto-connect on first publish/subscribe.
 
 ### `JetstreamBridge.shutdown!`
@@ -79,7 +80,7 @@ JetstreamBridge.shutdown!
 
 ### `JetstreamBridge.reset!`
 
-Reset all internal state (for testing).
+Reset all internal state (for testing). Also resets consumer signal handlers.
 
 ```ruby
 JetstreamBridge.reset!
@@ -95,14 +96,12 @@ Publish an event to the destination app.
 JetstreamBridge.publish(
   event_type: "user.created",     # Required
   resource_type: "user",          # Required
-  resource_id: user.id,           # Optional
   payload: { id: user.id, email: user.email },
-  headers: { correlation_id: "..." },  # Optional
   event_id: "custom-uuid"         # Optional (auto-generated)
 )
 ```
 
-**Returns:** `JetstreamBridge::PublishResult`
+**Returns:** `Models::PublishResult`
 
 **With Outbox:**
 
@@ -131,11 +130,11 @@ Publish multiple events efficiently.
 ```ruby
 results = JetstreamBridge.publish_batch do |batch|
   users.each do |user|
-    batch.publish(event_type: "user.created", resource_type: "user", payload: user)
+    batch.add(event_type: "user.created", resource_type: "user", payload: user)
   end
 end
 
-puts "Published: #{results.success_count}, Failed: #{results.failure_count}"
+puts "Published: #{results.successful_count}, Failed: #{results.failed_count}"
 ```
 
 ## Consuming
@@ -155,8 +154,8 @@ end
 
 ```ruby
 consumer = JetstreamBridge::Consumer.new(
-  batch_size: 10,           # Process up to 10 messages at once
-  error_handler: ->(error, event) { logger.error(error) }
+  durable_name: "my-consumer",  # Override default durable name
+  batch_size: 10                # Process up to 10 messages at once
 ) do |event|
   # ...
 end
@@ -184,14 +183,13 @@ The event object passed to your handler:
 
 ```ruby
 event.event_id       # => "evt_123"
-event.event_type     # => "user.created"
+event.type           # => "user.created"
 event.resource_type  # => "user"
 event.resource_id    # => "456"
-event.payload        # => { "id" => 456, "email" => "..." }
-event.headers        # => { "correlation_id" => "..." }
+event.payload        # => PayloadAccessor (supports method-style: event.payload.email)
 event.subject        # => "source_app.sync.my_app"
 event.stream         # => "jetstream-bridge-stream"
-event.seq            # => 123
+event.sequence       # => 123
 event.deliveries     # => 1
 ```
 
@@ -255,13 +253,18 @@ Get comprehensive health status.
 ```ruby
 health = JetstreamBridge.health_check
 
-health[:status]           # => "healthy" | "unhealthy"
-health[:connected]        # => true/false
-health[:stream_exists]    # => true/false
-health[:messages]         # => 123
-health[:consumers]        # => 2
-health[:nats_rtt_ms]      # => 1.2
-health[:version]          # => "7.0.0"
+health[:healthy]                            # => true/false
+health[:connection][:state]                 # => :connected
+health[:connection][:connected]             # => true/false
+health[:connection][:connected_at]          # => "2025-01-01T00:00:00Z"
+health[:stream][:exists]                    # => true/false
+health[:stream][:name]                      # => "jetstream-bridge-stream"
+health[:stream][:subjects]                  # => ["app.sync.worker"]
+health[:stream][:messages]                  # => 123
+health[:performance][:nats_rtt_ms]          # => 1.2
+health[:performance][:health_check_duration_ms] # => 45.2
+health[:config]                             # => { app_name:, stream_name:, ... }
+health[:version]                            # => "7.0.0"
 ```
 
 ### `JetstreamBridge.stream_info`
@@ -280,18 +283,6 @@ info[:last_seq]           # => 1000
 info[:consumer_count]     # => 2
 ```
 
-### `JetstreamBridge.connection_info`
-
-Get NATS connection details.
-
-```ruby
-info = JetstreamBridge.connection_info
-
-info[:connected]          # => true
-info[:servers]            # => ["nats://localhost:4222"]
-info[:connected_at]       # => 2024-01-29 12:00:00 UTC
-```
-
 ## Models
 
 ### `JetstreamBridge::OutboxEvent`
@@ -383,17 +374,23 @@ rescue JetstreamBridge::StreamNotFoundError => e
 end
 ```
 
-### Custom Error Handler
+### Custom Error Handling (Middleware)
 
 ```ruby
-consumer = JetstreamBridge::Consumer.new(
-  error_handler: lambda { |error, event|
-    logger.error("Failed to process event #{event.event_id}: #{error.message}")
-    Sentry.capture_exception(error, extra: { event_id: event.event_id })
-  }
-) do |event|
+class SentryErrorMiddleware
+  def call(event)
+    yield
+  rescue StandardError => e
+    logger.error("Failed to process event #{event.event_id}: #{e.message}")
+    Sentry.capture_exception(e, extra: { event_id: event.event_id })
+    raise  # Re-raise so the consumer can NAK/DLQ as appropriate
+  end
+end
+
+consumer = JetstreamBridge::Consumer.new do |event|
   # Process event
 end
+consumer.use(SentryErrorMiddleware.new)
 ```
 
 ## Testing

data/docs/ARCHITECTURE.md

@@ -68,12 +68,11 @@ Thread-safe singleton managing NATS connections:
 
 **Key Methods:**
 
-- `Connection.instance` - Get singleton connection
-- `connection.connect!` - Establish NATS connection
-- `connection.nats` - Access raw NATS client
-- `connection.jetstream` - Access JetStream context
-- `connection.healthy?` - Check connection health
-- `connection.reconnect!` - Force reconnection
+- `Connection.connect!` - Thread-safe connection establishment (class-level)
+- `Connection.nc` - Access raw NATS client (class-level)
+- `Connection.jetstream` - Access JetStream context (class-level)
+- `connection.connected?` - Check connection health (cached, 30s TTL)
+- `connection.state` - Get current state (:disconnected, :connecting, :connected, :reconnecting, :failed)
 
 ### Publisher (`lib/jetstream_bridge/publisher/publisher.rb`)
 
@@ -104,9 +103,9 @@ JetstreamBridge.publish(
   "resource_type": "user",
   "resource_id": "1",
   "payload": { "id": 1, "email": "user@example.com" },
-  "produced_at": "2024-01-01T00:00:00Z",
+  "occurred_at": "2024-01-01T00:00:00Z",
   "producer": "api",
-  "schema_version": "1.0",
+  "schema_version": 1,
   "trace_id": "trace-uuid"
 }
 ```
@@ -836,16 +835,16 @@ end
 
 ```ruby
 class CustomErrorHandler
-  def call(event, next_middleware)
-    next_middleware.call(event)
+  def call(event)
+    yield
   rescue CustomRetryableError => e
-    # Return ActionResult with custom delay
-    JetstreamBridge::Consumer::ActionResult.new(:nak, delay: 10)
+    # Re-raise to let the consumer NAK with backoff
+    raise
   rescue CustomPermanentError => e
     # Log and move to DLQ
     logger.error("Permanent error: #{e.message}")
     publish_to_custom_dlq(event, e)
-    JetstreamBridge::Consumer::ActionResult.new(:ack)
+    # Don't re-raise — consumer will ACK
   end
 end
 
@@ -858,19 +857,27 @@ consumer.use(CustomErrorHandler.new)
 
 ### Connection Singleton
 
-**Thread-safe initialization:**
+**Thread-safe initialization (Singleton + class-level mutex):**
 
 ```ruby
-@@connection_lock = Mutex.new
+class Connection
+  include Singleton
 
-def self.instance
-  return @@connection if @@connection
+  @@connection_lock = Mutex.new
 
-  @@connection_lock.synchronize do
-    @@connection ||= new
-  end
+  class << self
+    def connect!(verify_js: nil)
+      @@connection_lock.synchronize { instance.connect!(verify_js: verify_js) }
+    end
+
+    def nc
+      instance.__send__(:nc)
+    end
 
-  @@connection
+    def jetstream
+      instance.__send__(:jetstream)
+    end
+  end
 end
 ```
 
@@ -991,28 +998,30 @@ health = JetstreamBridge.health_check(skip_cache: false)
 {
   healthy: true,
   connection: {
-    status: "connected",
-    servers: ["nats://localhost:4222"],
-    connected_at: "2024-01-01T00:00:00Z"
+    state: :connected,
+    connected: true,
+    connected_at: "2025-01-01T00:00:00Z"
+  },
+  stream: {
+    exists: true,
+    name: "jetstream-bridge-stream",
+    subjects: ["app.sync.worker"],
+    messages: 1523
   },
-  jetstream: {
-    streams: 1,
-    consumers: 2,
-    memory_bytes: 104857600,
-    storage_bytes: 1073741824
+  performance: {
+    nats_rtt_ms: 2.5,
+    health_check_duration_ms: 45.2
   },
   config: {
-    stream_name: "jetstream-bridge-stream",
     app_name: "api",
     destination_app: "worker",
+    stream_name: "jetstream-bridge-stream",
+    auto_provision: true,
     use_outbox: true,
     use_inbox: true,
     use_dlq: true
   },
-  performance: {
-    message_processing_time_ms: 45.2,
-    last_health_check_ms: 12.5
-  }
+  version: "7.0.0"
 }
 ```
 
@@ -1046,15 +1055,13 @@ ERROR [JetstreamBridge::Consumer] Unrecoverable error: ArgumentError
 
 ```ruby
 class MetricsMiddleware
-  def call(event, next_middleware)
+  def call(event)
     start = Time.now
-    result = next_middleware.call(event)
+    yield
     duration = Time.now - start
 
     StatsD.increment('jetstream.messages.processed')
     StatsD.histogram('jetstream.processing_time', duration)
-
-    result
   rescue => e
     StatsD.increment('jetstream.messages.failed', tags: ["error:#{e.class}"])
     raise

data/docs/PRODUCTION.md

@@ -117,11 +117,6 @@ Optimize consumer configuration based on your workload:
 
 ```ruby
 JetstreamBridge.configure do |config|
-  # Adjust batch size based on message processing time
-  # Larger = better throughput, smaller = lower latency
-  # Default: 25
-  config.batch_size = 50
-
   # Increase max_deliver for critical messages
   # Default: 5
   config.max_deliver = 10
@@ -134,6 +129,9 @@ JetstreamBridge.configure do |config|
   # Default: [1s, 5s, 15s, 30s, 60s]
   config.backoff = %w[2s 10s 30s 60s 120s]
 end
+
+# batch_size is a Consumer.new parameter, not a config attribute:
+consumer = JetstreamBridge::Consumer.new(handler, batch_size: 50)
 ```
 
 ### Consumer Best Practices

data/lib/jetstream_bridge/consumer/consumer.rb

@@ -59,6 +59,10 @@ module JetstreamBridge
     TimeoutMiddleware = ConsumerMiddleware::TimeoutMiddleware
 
     class << self
+      # Register a consumer instance to receive OS signal notifications (INT, TERM).
+      #
+      # @param consumer [Consumer] Consumer to register
+      # @return [void]
       def register_consumer_for_signals(consumer)
         signal_registry_mutex.synchronize do
           signal_consumers << consumer
@@ -66,10 +70,17 @@ module JetstreamBridge
         end
       end
 
+      # Remove a consumer from the signal registry.
+      #
+      # @param consumer [Consumer] Consumer to unregister
+      # @return [void]
       def unregister_consumer_for_signals(consumer)
         signal_registry_mutex.synchronize { signal_consumers.delete(consumer) }
       end
 
+      # Clear all registered consumers and reset signal handler state.
+      #
+      # @return [void]
       def reset_signal_handlers!
         signal_registry_mutex.synchronize { signal_consumers.clear }
         @signal_handlers_installed = false
@@ -141,13 +152,17 @@ module JetstreamBridge
     attr_reader :batch_size
     # @return [MiddlewareChain] Middleware chain for processing
     attr_reader :middleware_chain
-    # Expose grouped state objects for observability/testing
-    attr_reader :processing_state, :lifecycle_state, :connection_state
+    # @return [ProcessingState] Processing counters and backoff state
+    attr_reader :processing_state
+    # @return [LifecycleState] Lifecycle flags and timing
+    attr_reader :lifecycle_state
+    # @return [ConnectionState] Reconnection attempts and health check timing
+    attr_reader :connection_state
 
     # Initialize a new Consumer instance.
     #
     # @param handler [Proc, #call, nil] Message handler that processes events.
-    #   Must respond to #call(event) or #call(event, subject, deliveries).
+    #   Must respond to #call(event).
     # @param durable_name [String, nil] Optional durable consumer name override.
     #   Defaults to config.durable_name.
     # @param batch_size [Integer, nil] Number of messages to fetch per batch.

data/lib/jetstream_bridge/consumer/consumer_state.rb

@@ -2,10 +2,15 @@
 
 module JetstreamBridge
   class Consumer
-    # Tracks processing counters and backoff state.
+    # Tracks processing counters and idle-backoff state.
     class ProcessingState
-      attr_accessor :idle_backoff, :iterations
+      # @return [Float] Current idle backoff duration in seconds
+      attr_accessor :idle_backoff
+      # @return [Integer] Total number of processing loop iterations
+      attr_accessor :iterations
 
+      # @param idle_backoff [Float] Initial idle backoff duration (seconds)
+      # @param iterations [Integer] Starting iteration count
       def initialize(idle_backoff:, iterations: 0)
         @idle_backoff = idle_backoff
         @iterations = iterations
@@ -14,9 +19,18 @@ module JetstreamBridge
 
     # Tracks lifecycle flags and timing for the consumer.
     class LifecycleState
-      attr_accessor :running, :shutdown_requested, :signal_received, :signal_logged
+      # @return [Boolean] Whether the consumer loop should keep running
+      attr_accessor :running
+      # @return [Boolean] Whether a graceful shutdown has been requested
+      attr_accessor :shutdown_requested
+      # @return [String, nil] Signal name that triggered shutdown (e.g. "INT")
+      attr_accessor :signal_received
+      # @return [Boolean] Whether the signal receipt has been logged
+      attr_accessor :signal_logged
+      # @return [Time] When the consumer started
       attr_reader :start_time
 
+      # @param start_time [Time] Consumer start time (defaults to now)
       def initialize(start_time: Time.now)
         @running = true
         @shutdown_requested = false
@@ -25,16 +39,27 @@ module JetstreamBridge
         @start_time = start_time
       end
 
+      # Request a graceful shutdown.
+      #
+      # @return [void]
       def stop!
         @shutdown_requested = true
         @running = false
       end
 
+      # Record an OS signal and trigger shutdown.
+      #
+      # @param sig [String] Signal name (e.g. "INT", "TERM")
+      # @return [void]
       def signal!(sig)
         @signal_received = sig
         stop!
       end
 
+      # Calculate consumer uptime in seconds.
+      #
+      # @param now [Time] Current time
+      # @return [Float] Uptime in seconds
       def uptime(now = Time.now)
         now - @start_time
       end
@@ -42,14 +67,21 @@ module JetstreamBridge
 
     # Tracks reconnection attempts and health check timing.
     class ConnectionState
+      # @return [Integer] Number of consecutive reconnection attempts
       attr_accessor :reconnect_attempts
+      # @return [Time] When the last health check was performed
       attr_reader :last_health_check
 
+      # @param now [Time] Initial health check timestamp
       def initialize(now: Time.now)
         @reconnect_attempts = 0
         @last_health_check = now
       end
 
+      # Record that a health check was performed.
+      #
+      # @param now [Time] Timestamp of the health check
+      # @return [void]
       def mark_health_check(now = Time.now)
         @last_health_check = now
       end

data/lib/jetstream_bridge/consumer/message_processor.rb

@@ -8,11 +8,28 @@ require_relative 'dlq_publisher'
 require_relative 'middleware'
 
 module JetstreamBridge
-  # Immutable per-message metadata.
+  # Immutable per-message metadata extracted from a NATS message.
+  #
+  # @!attribute [r] event_id
+  #   @return [String] Event identifier (from nats-msg-id header or generated UUID)
+  # @!attribute [r] deliveries
+  #   @return [Integer] Number of delivery attempts
+  # @!attribute [r] subject
+  #   @return [String] NATS subject the message arrived on
+  # @!attribute [r] seq
+  #   @return [Integer, nil] Stream sequence number
+  # @!attribute [r] consumer
+  #   @return [String, nil] Consumer name
+  # @!attribute [r] stream
+  #   @return [String, nil] Stream name
   MessageContext = Struct.new(
     :event_id, :deliveries, :subject, :seq, :consumer, :stream,
     keyword_init: true
   ) do
+    # Build a MessageContext from a raw NATS message.
+    #
+    # @param msg [NATS::Msg] Raw NATS message
+    # @return [MessageContext]
     def self.build(msg)
       new(
         event_id: msg.header&.[]('nats-msg-id') || SecureRandom.uuid,
@@ -26,13 +43,21 @@ module JetstreamBridge
   end
 
   # Simple exponential backoff strategy for transient failures.
+  #
+  # Produces a bounded delay in seconds based on delivery count and error type.
+  # Transient errors (Timeout, IO) use a lower base for faster retries.
   class BackoffStrategy
+    # Error types considered transient (faster backoff)
     TRANSIENT_ERRORS = [Timeout::Error, IOError].freeze
     MAX_EXPONENT     = 6
     MAX_DELAY        = 60
     MIN_DELAY        = 1
 
-    # Returns a bounded delay in seconds
+    # Calculate delay for the next retry attempt.
+    #
+    # @param deliveries [Integer] Current delivery attempt number
+    # @param error [Exception] The error that triggered the retry
+    # @return [Integer] Delay in seconds, clamped between MIN_DELAY and MAX_DELAY
     def delay(deliveries, error)
       base = transient?(error) ? 0.5 : 2.0
       power = [deliveries - 1, MAX_EXPONENT].min
@@ -47,13 +72,35 @@ module JetstreamBridge
     end
   end
 
-  # Orchestrates parse → handler → ack/nak → DLQ
+  # Orchestrates the parse -> handler -> ack/nak -> DLQ pipeline for each message.
+  #
+  # Responsible for deserializing incoming NATS messages, running them through
+  # the middleware chain and handler, and deciding whether to ACK, NAK, or
+  # route to the dead letter queue.
   class MessageProcessor
+    # Error types that skip retry and go straight to DLQ
     UNRECOVERABLE_ERRORS = [ArgumentError, TypeError].freeze
+
+    # Result of processing a single message.
+    #
+    # @!attribute [r] action
+    #   @return [Symbol] :ack or :nak
+    # @!attribute [r] ctx
+    #   @return [MessageContext] Per-message metadata
+    # @!attribute [r] error
+    #   @return [Exception, nil] Error if processing failed
+    # @!attribute [r] delay
+    #   @return [Integer, nil] NAK delay in seconds
     ActionResult = Struct.new(:action, :ctx, :error, :delay, keyword_init: true)
 
+    # @return [ConsumerMiddleware::MiddlewareChain] Middleware chain
     attr_reader :middleware_chain
 
+    # @param jts [NATS::JetStream] JetStream context
+    # @param handler [#call] User-provided event handler
+    # @param dlq [DlqPublisher, nil] DLQ publisher (auto-created if nil)
+    # @param backoff [BackoffStrategy, nil] Backoff strategy (auto-created if nil)
+    # @param middleware_chain [ConsumerMiddleware::MiddlewareChain, nil] Middleware chain
     def initialize(jts, handler, dlq: nil, backoff: nil, middleware_chain: nil)
       @jts              = jts
       @handler          = handler
@@ -62,6 +109,11 @@ module JetstreamBridge
       @middleware_chain = middleware_chain || ConsumerMiddleware::MiddlewareChain.new
     end
 
+    # Process a single NATS message through the full pipeline.
+    #
+    # @param msg [NATS::Msg] Raw NATS message
+    # @param auto_ack [Boolean] Whether to automatically ACK/NAK the message
+    # @return [ActionResult] Result indicating the action taken
     def handle_message(msg, auto_ack: true)
       ctx = MessageContext.build(msg)
       event, early_action = parse_message(msg, ctx)

data/lib/jetstream_bridge/consumer/subscription_manager.rb

@@ -7,8 +7,14 @@ require_relative '../errors'
 require_relative 'pull_subscription_builder'
 
 module JetstreamBridge
-  # Encapsulates durable ensure + subscribe for a pull consumer.
+  # Manages durable consumer provisioning and subscription lifecycle.
+  #
+  # Encapsulates the ensure-consumer + subscribe flow for both pull and push
+  # consumer modes, with automatic fallback between modes.
   class SubscriptionManager
+    # @param jts [NATS::JetStream] JetStream context
+    # @param durable [String] Durable consumer name
+    # @param cfg [Config] Configuration instance
     def initialize(jts, durable, cfg = JetstreamBridge.config)
       @jts     = jts
       @durable = durable
@@ -28,7 +34,14 @@ module JetstreamBridge
       @desired_cfg
     end
 
-    # Ensure consumer exists; skips all JS.API calls when auto_provision is false.
+    # Ensure the durable consumer exists on the server.
+    #
+    # Skips all JetStream API calls when +auto_provision+ is false, assuming
+    # the consumer was pre-provisioned externally.
+    #
+    # @return [void]
+    # @raise [StreamNotFoundError] If the stream does not exist
+    # @raise [ConsumerProvisioningError] If consumer creation fails due to permissions
     def ensure_consumer!(**_options)
       unless @cfg.auto_provision
         Logging.info("Skipping consumer validation (auto_provision=false); assuming '#{@durable}' exists.",
@@ -126,6 +139,12 @@ module JetstreamBridge
     end
 
     # Bind a subscriber to the existing durable consumer.
+    #
+    # Automatically selects pull or push mode based on configuration, with
+    # fallback to the opposite mode if the primary subscription fails.
+    #
+    # @return [Object] NATS subscription handle (pull or push)
+    # @raise [ConnectionError] If neither subscription mode succeeds
     def subscribe!
       if @cfg.push_consumer?
         subscribe_push_with_fallback

data/lib/jetstream_bridge/core/config.rb

@@ -49,10 +49,10 @@ module JetstreamBridge
       PROCESSED = 'processed'
     end
 
-    # NATS server URL(s), comma-separated for multiple servers
+    # Destination application name for subject routing
     # @return [String]
     attr_accessor :destination_app
-    # NATS server URL(s)
+    # NATS server URL(s), comma-separated for multiple servers
     # @return [String]
     attr_accessor :nats_urls
     # JetStream stream name (required)
@@ -119,6 +119,12 @@ module JetstreamBridge
     # @return [String, nil]
     attr_accessor :push_consumer_group
 
+    # Initialize a new Config with sensible defaults.
+    #
+    # Reads initial values from environment variables when available
+    # (NATS_URLS, NATS_URL, JETSTREAM_STREAM_NAME, APP_NAME, DESTINATION_APP).
+    #
+    # @return [Config]
     def initialize
       @nats_urls       = ENV['NATS_URLS'] || ENV['NATS_URL'] || 'nats://localhost:4222'
       @stream_name     = ENV['JETSTREAM_STREAM_NAME'] || 'jetstream-bridge-stream'

data/lib/jetstream_bridge/core/connection.rb

@@ -60,22 +60,33 @@ module JetstreamBridge
       #
       # Safe to call from multiple threads - uses class-level mutex for synchronization.
       #
-      # @return [NATS::JetStream::JS] JetStream context
+      # @return [NATS::JetStream] JetStream context
       def connect!(verify_js: nil)
         @@connection_lock.synchronize { instance.connect!(verify_js: verify_js) }
       end
 
-      # Optional accessors if callers need raw handles
+      # Returns the raw NATS client from the singleton instance.
+      #
+      # @return [NATS::IO::Client, nil] The underlying NATS connection
       def nc
         instance.__send__(:nc)
       end
 
+      # Returns the JetStream context from the singleton instance.
+      #
+      # @return [NATS::JetStream, nil] JetStream context
+      # @raise [ConnectionNotEstablishedError] If JetStream context is unavailable
       def jetstream
         instance.__send__(:jetstream)
       end
     end
 
     # Idempotent: returns an existing, healthy JetStream context or establishes one.
+    #
+    # @param verify_js [Boolean, nil] Whether to verify JetStream availability via account_info.
+    #   Defaults to the value of {Config#auto_provision}.
+    # @return [NATS::JetStream] JetStream context
+    # @raise [ConnectionError] If unable to connect to NATS or JetStream
     def connect!(verify_js: nil)
       verify_js = config_auto_provision if verify_js.nil?
       # Check if already connected without acquiring mutex (for performance)

data/lib/jetstream_bridge/core/duration.rb

@@ -9,17 +9,20 @@ module JetstreamBridge
   # seconds, >=1000 as milliseconds. Strings with unit suffixes are supported
   # (e.g., "30s", "500ms", "1h").
   #
-  # Examples:
+  # @example Integer with auto-detection
   #   Duration.to_millis(2)                         #=> 2000 (auto: seconds)
   #   Duration.to_millis(1500)                      #=> 1500 (auto: milliseconds)
+  #
+  # @example Explicit units
   #   Duration.to_millis(30, default_unit: :s)      #=> 30000
+  #   Duration.to_millis(1_500_000_000, default_unit: :ns) #=> 1500
+  #
+  # @example String with suffix
   #   Duration.to_millis("30s")                     #=> 30000
   #   Duration.to_millis("500ms")                   #=> 500
-  #   Duration.to_millis("250us")                   #=> 0
   #   Duration.to_millis("1h")                      #=> 3_600_000
-  #   Duration.to_millis(1_500_000_000, default_unit: :ns) #=> 1500
   #
-  # Also:
+  # @example Normalizing a list
   #   Duration.normalize_list_to_millis(%w[1s 5s 15s]) #=> [1000, 5000, 15000]
   module Duration
     # multipliers to convert 1 unit into milliseconds
@@ -39,10 +42,14 @@ module JetstreamBridge
 
     module_function
 
-    # default_unit:
-    #   :auto (default: heuristic - <1000 => seconds, >=1000 => milliseconds)
-    #   :ms (explicit milliseconds)
-    #   :ns, :us, :s, :m, :h, :d (explicit units)
+    # Convert a duration value to milliseconds.
+    #
+    # @param val [Integer, Float, String] Duration value to convert
+    # @param default_unit [Symbol] Unit for bare numbers.
+    #   :auto (heuristic: <1000 => seconds, >=1000 => ms),
+    #   :ms, :ns, :us, :s, :m, :h, :d
+    # @return [Integer] Duration in milliseconds
+    # @raise [ArgumentError] If the value cannot be parsed
     def to_millis(val, default_unit: :auto)
       case val
       when Integer then int_to_ms(val, default_unit: default_unit)
@@ -57,6 +64,10 @@ module JetstreamBridge
     end
 
     # Normalize an array of durations into integer milliseconds.
+    #
+    # @param values [Array<Integer, Float, String>] Duration values
+    # @param default_unit [Symbol] Default unit for bare numbers
+    # @return [Array<Integer>] Durations in milliseconds
     def normalize_list_to_millis(values, default_unit: :auto)
       vals = Array(values)
       return [] if vals.empty?
@@ -69,6 +80,10 @@ module JetstreamBridge
     # Retains the nanosecond heuristic used in SubscriptionManager:
     # extremely large integers (>= 1_000_000_000) are treated as nanoseconds
     # when default_unit is :auto.
+    #
+    # @param val [Integer, Float, String, nil] Duration value (returns nil if nil)
+    # @param default_unit [Symbol] Default unit for bare numbers
+    # @return [Integer, nil] Duration in seconds (minimum 1), or nil if val is nil
     def to_seconds(val, default_unit: :auto)
       return nil if val.nil?
 
@@ -82,6 +97,10 @@ module JetstreamBridge
     end
 
     # Normalize an array of durations into integer seconds.
+    #
+    # @param values [Array<Integer, Float, String>] Duration values
+    # @param default_unit [Symbol] Default unit for bare numbers
+    # @return [Array<Integer>] Durations in seconds
     def normalize_list_to_seconds(values, default_unit: :auto)
       vals = Array(values)
       return [] if vals.empty?

data/lib/jetstream_bridge/core/logging.rb

@@ -9,33 +9,59 @@ module JetstreamBridge
   module Logging
     module_function
 
+    # Returns the active logger instance.
+    #
+    # Resolution order: configured logger, Rails.logger, STDOUT fallback.
+    #
+    # @return [Logger] Active logger
     def logger
       JetstreamBridge.config.logger ||
         (defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger) ||
         default_logger
     end
 
+    # Returns a default STDOUT logger, memoized for reuse.
+    #
+    # @return [Logger]
     def default_logger
       @default_logger ||= Logger.new($stdout)
     end
 
+    # Log a message at the given level with an optional tag prefix.
+    #
+    # @param level [Symbol] Log level (:debug, :info, :warn, :error)
+    # @param msg [String] Message to log
+    # @param tag [String, nil] Optional prefix (e.g. "JetstreamBridge::Consumer")
+    # @return [void]
     def log(level, msg, tag: nil)
       message = tag ? "[#{tag}] #{msg}" : msg
       logger.public_send(level, message)
     end
 
+    # @param msg [String] Message to log
+    # @param tag [String, nil] Optional prefix
+    # @return [void]
     def debug(msg, tag: nil)
       log(:debug, msg, tag: tag)
     end
 
+    # @param msg [String] Message to log
+    # @param tag [String, nil] Optional prefix
+    # @return [void]
     def info(msg, tag: nil)
       log(:info, msg, tag: tag)
     end
 
+    # @param msg [String] Message to log
+    # @param tag [String, nil] Optional prefix
+    # @return [void]
     def warn(msg, tag: nil)
       log(:warn, msg, tag: tag)
     end
 
+    # @param msg [String] Message to log
+    # @param tag [String, nil] Optional prefix
+    # @return [void]
     def error(msg, tag: nil)
       log(:error, msg, tag: tag)
     end

data/lib/jetstream_bridge/errors.rb

@@ -1,30 +1,50 @@
 # frozen_string_literal: true
 
 module JetstreamBridge
-  # Base error for all JetStream Bridge errors with context support
+  # Base error for all JetStream Bridge errors.
+  #
+  # Every error carries an optional +context+ hash for structured diagnostics.
   class Error < StandardError
+    # @return [Hash] Structured context for diagnostics
     attr_reader :context
 
+    # @param message [String, nil] Human-readable error message
+    # @param context [Hash] Arbitrary diagnostic context (frozen on assignment)
     def initialize(message = nil, context: {})
       super(message)
       @context = context.freeze
     end
   end
 
-  # Configuration errors
+  # Raised when configuration values are invalid or inconsistent.
   class ConfigurationError < Error; end
+
+  # Raised when a NATS subject contains invalid characters.
   class InvalidSubjectError < ConfigurationError; end
+
+  # Raised when a required configuration value is missing.
   class MissingConfigurationError < ConfigurationError; end
 
-  # Connection errors
+  # Raised when a NATS connection cannot be established or is lost.
   class ConnectionError < Error; end
+
+  # Raised when an operation requires a connection that has not been established.
   class ConnectionNotEstablishedError < ConnectionError; end
+
+  # Raised when a health check fails or is rate-limited.
   class HealthCheckFailedError < ConnectionError; end
 
-  # Publisher errors with enriched context
+  # Raised when an event fails to publish.
   class PublishError < Error
-    attr_reader :event_id, :subject
-
+    # @return [String, nil] Event ID that failed to publish
+    attr_reader :event_id
+    # @return [String, nil] NATS subject the publish was attempted on
+    attr_reader :subject
+
+    # @param message [String, nil] Human-readable error message
+    # @param event_id [String, nil] The event ID
+    # @param subject [String, nil] The NATS subject
+    # @param context [Hash] Additional diagnostic context
     def initialize(message = nil, event_id: nil, subject: nil, context: {})
       @event_id = event_id
       @subject = subject
@@ -32,12 +52,23 @@ module JetstreamBridge
     end
   end
 
+  # Raised when a publish operation fails after retries.
   class PublishFailedError < PublishError; end
+
+  # Raised when the outbox persistence layer encounters an error.
   class OutboxError < PublishError; end
 
+  # Raised when a batch publish has one or more failures.
   class BatchPublishError < PublishError
-    attr_reader :failed_events, :successful_count
-
+    # @return [Array<Hash>] Details of each failed event
+    attr_reader :failed_events
+    # @return [Integer] Number of events that published successfully
+    attr_reader :successful_count
+
+    # @param message [String, nil] Human-readable error message
+    # @param failed_events [Array<Hash>] Failed event details
+    # @param successful_count [Integer] Count of successful publishes
+    # @param context [Hash] Additional diagnostic context
     def initialize(message = nil, failed_events: [], successful_count: 0, context: {})
       @failed_events = failed_events
       @successful_count = successful_count
@@ -51,10 +82,17 @@ module JetstreamBridge
     end
   end
 
-  # Consumer errors with delivery context
+  # Raised when message consumption encounters an error.
   class ConsumerError < Error
-    attr_reader :event_id, :deliveries
-
+    # @return [String, nil] Event ID being processed
+    attr_reader :event_id
+    # @return [Integer, nil] Number of delivery attempts so far
+    attr_reader :deliveries
+
+    # @param message [String, nil] Human-readable error message
+    # @param event_id [String, nil] The event ID being consumed
+    # @param deliveries [Integer, nil] Delivery attempt count
+    # @param context [Hash] Additional diagnostic context
     def initialize(message = nil, event_id: nil, deliveries: nil, context: {})
       @event_id = event_id
       @deliveries = deliveries
@@ -62,24 +100,44 @@ module JetstreamBridge
     end
   end
 
+  # Raised when a user-provided handler raises during event processing.
   class HandlerError < ConsumerError; end
+
+  # Raised when the inbox deduplication layer encounters an error.
   class InboxError < ConsumerError; end
 
-  # Topology errors
+  # Raised when stream or consumer topology operations fail.
   class TopologyError < Error; end
+
+  # Raised when a JetStream consumer cannot be provisioned.
   class ConsumerProvisioningError < TopologyError; end
+
+  # Raised when the configured stream does not exist.
   class StreamNotFoundError < TopologyError; end
+
+  # Raised when subject filter patterns overlap between consumers.
   class SubjectOverlapError < TopologyError; end
+
+  # Raised when stream creation fails.
   class StreamCreationFailedError < TopologyError; end
 
-  # DLQ errors
+  # Raised when a DLQ operation fails.
   class DlqError < Error; end
+
+  # Raised when publishing a message to the dead letter queue fails.
   class DlqPublishFailedError < DlqError; end
 
-  # Retry errors
+  # Raised when all retry attempts have been exhausted.
   class RetryExhausted < Error
-    attr_reader :attempts, :original_error
-
+    # @return [Integer] Total number of attempts made
+    attr_reader :attempts
+    # @return [Exception, nil] The last error that triggered the retry
+    attr_reader :original_error
+
+    # @param message [String, nil] Human-readable error message (auto-generated if nil)
+    # @param attempts [Integer] Number of attempts made
+    # @param original_error [Exception, nil] The underlying error
+    # @param context [Hash] Additional diagnostic context
     def initialize(message = nil, attempts: 0, original_error: nil, context: {})
       @attempts = attempts
       @original_error = original_error

data/lib/jetstream_bridge/models/event.rb

@@ -15,7 +15,23 @@ module JetstreamBridge
     #     puts event.metadata.trace_id # "abc123"
     #   end
     class Event
-      # Metadata associated with message delivery
+      # Metadata associated with message delivery.
+      #
+      # Contains NATS-level delivery information such as the subject,
+      # delivery count, stream name, and sequence number.
+      #
+      # @!attribute [r] subject
+      #   @return [String] NATS subject the message was received on
+      # @!attribute [r] deliveries
+      #   @return [Integer] Number of delivery attempts
+      # @!attribute [r] stream
+      #   @return [String, nil] Stream name
+      # @!attribute [r] sequence
+      #   @return [Integer, nil] Message sequence number in the stream
+      # @!attribute [r] consumer
+      #   @return [String, nil] Consumer name
+      # @!attribute [r] timestamp
+      #   @return [Time] When the metadata was captured
       Metadata = Struct.new(
         :subject,
         :deliveries,
@@ -37,8 +53,15 @@ module JetstreamBridge
         end
       end
 
-      # Payload accessor with method-style access
+      # Wraps a Hash payload to allow method-style access to its keys.
+      #
+      # @example
+      #   accessor = PayloadAccessor.new("user_id" => 42)
+      #   accessor.user_id  #=> 42
+      #   accessor["user_id"]  #=> 42
+      #   accessor.to_h  #=> {"user_id" => 42}
       class PayloadAccessor
+        # @param payload [Hash] Raw payload hash
         def initialize(payload)
           @payload = payload.is_a?(Hash) ? payload.transform_keys(&:to_s) : {}
         end
@@ -68,6 +91,15 @@ module JetstreamBridge
         alias to_hash to_h
       end
 
+      # @return [String] Unique event identifier
+      # @return [String] Event type (e.g. "user.created")
+      # @return [String] Resource type (e.g. "user")
+      # @return [String] Resource identifier
+      # @return [String] Name of the producing application
+      # @return [Time, nil] When the event occurred
+      # @return [String] Distributed trace identifier
+      # @return [Integer] Envelope schema version
+      # @return [Metadata] Message delivery metadata
       attr_reader :event_id, :type, :resource_type, :resource_id,
                   :producer, :occurred_at, :trace_id, :schema_version,
                   :metadata

data/lib/jetstream_bridge/models/event_envelope.rb

@@ -5,13 +5,37 @@ require 'time'
 
 module JetstreamBridge
   module Models
-    # Value object representing an event envelope
+    # Immutable value object representing an event envelope.
+    #
+    # Encapsulates all fields of a JetStream Bridge event and freezes itself
+    # (including the payload) after construction for thread-safety.
     class EventEnvelope
+      # Current envelope schema version
       SCHEMA_VERSION = 1
 
+      # @return [String] Unique event identifier (UUID)
+      # @return [Integer] Envelope schema version
+      # @return [String] Event type (e.g. "created", "updated")
+      # @return [String] Name of the producing application
+      # @return [String] Resource type (e.g. "user", "order")
+      # @return [String] Resource identifier extracted from payload
+      # @return [Time] When the event occurred
+      # @return [String] Distributed trace identifier
+      # @return [Hash] Frozen event payload
       attr_reader :event_id, :schema_version, :event_type, :producer,
                   :resource_type, :resource_id, :occurred_at, :trace_id, :payload
 
+      # Build a new EventEnvelope.
+      #
+      # @param resource_type [String] Resource type (e.g. "user")
+      # @param event_type [String] Event type (e.g. "created")
+      # @param payload [Hash] Event payload data
+      # @param event_id [String, nil] Custom event ID (auto-generated UUID if nil)
+      # @param occurred_at [Time, String, nil] Event timestamp (defaults to now)
+      # @param trace_id [String, nil] Distributed trace ID (auto-generated if nil)
+      # @param producer [String, nil] Producer app name (defaults to config.app_name)
+      # @param resource_id [String, nil] Resource ID (extracted from payload if nil)
+      # @raise [ArgumentError] If required fields are blank
       def initialize(
         resource_type:,
         event_type:,
@@ -36,7 +60,9 @@ module JetstreamBridge
         freeze
       end
 
-      # Convert to hash for serialization
+      # Convert to hash for serialization.
+      #
+      # @return [Hash] Envelope fields as a symbol-keyed hash
       def to_h
         hash = {
           event_id: @event_id,
@@ -55,7 +81,10 @@ module JetstreamBridge
         hash
       end
 
-      # Create from hash
+      # Reconstruct an EventEnvelope from a hash (e.g. deserialized JSON).
+      #
+      # @param hash [Hash] String- or symbol-keyed envelope data
+      # @return [EventEnvelope]
       def self.from_h(hash)
         new(
           event_id: hash['event_id'] || hash[:event_id],

data/lib/jetstream_bridge/publisher/batch_publisher.rb

@@ -96,6 +96,8 @@ module JetstreamBridge
       alias to_hash to_h
     end
 
+    # @param publisher [Publisher, nil] Publisher instance to use for each event.
+    #   Defaults to a new {Publisher} instance.
     def initialize(publisher = nil)
       @publisher = publisher || Publisher.new
       @events = []
@@ -156,6 +158,9 @@ module JetstreamBridge
     alias count size
     alias length size
 
+    # Whether the batch has no queued events.
+    #
+    # @return [Boolean]
     def empty?
       @events.empty?
     end

data/lib/jetstream_bridge/publisher/publisher.rb

@@ -76,11 +76,11 @@ module JetstreamBridge
     #   - occurred_at [Time, String] Event timestamp (defaults to current time)
     #
     # @return [Models::PublishResult] Result object containing:
-    #   - success [Boolean] Whether publish succeeded
+    #   - success? [Boolean] Whether publish succeeded
     #   - event_id [String] The published event ID
     #   - subject [String] NATS subject used
     #   - error [Exception, nil] Error if publish failed
-    #   - duplicate [Boolean] Whether NATS detected as duplicate
+    #   - duplicate? [Boolean] Whether NATS detected as duplicate
     #
     # @raise [ArgumentError] If required parameters are missing or invalid
     #

data/lib/jetstream_bridge/version.rb

@@ -4,5 +4,5 @@
 #
 # Version constant for the gem.
 module JetstreamBridge
-  VERSION = '7.1.3'
+  VERSION = '7.1.4'
 end

data/lib/jetstream_bridge.rb

@@ -68,6 +68,9 @@ module JetstreamBridge
   class << self
     include Core::BridgeHelpers
 
+    # Returns the current configuration, creating a default instance if needed.
+    #
+    # @return [Config] The current configuration object
     def config
       @config ||= Config.new
     end
@@ -90,6 +93,7 @@ module JetstreamBridge
     #   JetstreamBridge.configure(app_name: 'my_app')
     #
     # @param overrides [Hash] Configuration key-value pairs to set
+    # @param extra_overrides [Hash] Additional keyword arguments merged into overrides
     # @yield [Config] Configuration object for block-based configuration
     # @return [Config] The configured instance
     def configure(overrides = {}, **extra_overrides)
@@ -126,6 +130,12 @@ module JetstreamBridge
       end
     end
 
+    # Reset all configuration and connection state.
+    #
+    # Clears the config singleton and marks the connection as uninitialized.
+    # Primarily used in tests to restore a clean slate between examples.
+    #
+    # @return [void]
     def reset!
       @config = nil
       @connection_initialized = false
@@ -137,6 +147,8 @@ module JetstreamBridge
     # This method can be called explicitly if needed. It's idempotent and safe to call multiple times.
     #
     # @return [void]
+    # @raise [ConfigurationError] If configuration validation fails
+    # @raise [ConnectionError] If unable to connect to NATS
     def startup!
       return if @connection_initialized
 
@@ -186,14 +198,23 @@ module JetstreamBridge
       end
     end
 
+    # Whether the transactional outbox pattern is enabled.
+    #
+    # @return [Boolean]
     def use_outbox?
       config.use_outbox
     end
 
+    # Whether the idempotent inbox pattern is enabled.
+    #
+    # @return [Boolean]
     def use_inbox?
       config.use_inbox
     end
 
+    # Whether the dead letter queue is enabled.
+    #
+    # @return [Boolean]
     def use_dlq?
       config.use_dlq
     end
@@ -311,7 +332,8 @@ module JetstreamBridge
     # @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)
+    # @param kwargs [Hash] Additional keyword arguments forwarded to Publisher#publish
+    #   (event_id, occurred_at, trace_id)
     # @return [Models::PublishResult] Result object with success status and metadata
     #
     # @example Check result status

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jetstream_bridge
 version: !ruby/object:Gem::Version
-  version: 7.1.3
+  version: 7.1.4
 platform: ruby
 authors:
 - Mike Attara