cdc-parallel 0.2.2 → 0.2.4

data/lib/cdc/parallel/result_collector.rb

@@ -2,22 +2,58 @@
 
 module CDC
   module Parallel
-    # Normalizes values returned by workers.
+    # Converts raw worker responses into `CDC::Core::ProcessorResult` objects.
+    #
+    # Ractors cannot freely share arbitrary mutable Ruby objects. Worker
+    # responses must therefore be normalized into shareable payloads before they
+    # cross back to the caller. `ResultCollector` owns that small translation
+    # boundary.
+    #
+    # The worker side uses {worker_success} and {worker_failure}. The caller side
+    # uses {normalize} to convert those payloads into the public result contract.
+    #
+    # @example Normalizing a processor return value
+    #   response = CDC::Parallel::ResultCollector.worker_success(value)
+    #   result = CDC::Parallel::ResultCollector.normalize(response)
+    #
+    # @example Normalizing a worker exception
+    #   response = CDC::Parallel::ResultCollector.worker_failure(error)
+    #   result = CDC::Parallel::ResultCollector.normalize(response)
+    #   result.failure? #=> true
+    #
+    # @api public
     class ResultCollector
+      # Internal marker used to identify serialized worker failures.
+      #
+      # @return [Symbol]
       FAILURE_MARKER = :__cdc_parallel_failure__
 
       # Build a shareable success payload that can safely cross a Ractor boundary.
       #
+      # If the processor already returned a `CDC::Core::ProcessorResult`, that
+      # result is preserved. Any other shareable value will later be wrapped in a
+      # success result by {normalize}.
+      #
       # @param value [Object]
+      #   Processor return value.
+      # @raise [Ractor::Error]
+      #   Raised by Ruby when the value cannot be made shareable.
       # @return [Object]
+      #   Shareable success payload.
       def self.worker_success(value)
         ::Ractor.make_shareable(value)
       end
 
       # Build a shareable failure payload that can safely cross a Ractor boundary.
       #
+      # Exceptions themselves are not used as the cross-Ractor payload. Instead,
+      # the class name, message, and backtrace are serialized into a simple hash
+      # that can be reconstructed as a {ProcessorExecutionError} by {normalize}.
+      #
       # @param error [Exception]
+      #   Exception raised inside a worker Ractor.
       # @return [Hash]
+      #   Shareable serialized failure payload.
       def self.worker_failure(error)
         ::Ractor.make_shareable(
           {
@@ -29,9 +65,14 @@ module CDC
         )
       end
 
-      # Normalize a worker return value into a ProcessorResult.
+      # Normalize a worker return value into a `CDC::Core::ProcessorResult`.
+      #
+      # Failure payloads become failed processor results containing a
+      # {ProcessorExecutionError}. Existing processor results are returned
+      # unchanged. Other values are wrapped in a successful processor result.
       #
       # @param value [Object]
+      #   Raw worker response.
       # @return [CDC::Core::ProcessorResult]
       def self.normalize(value)
         if worker_failure?(value)
@@ -49,6 +90,12 @@ module CDC
         end
       end
 
+      # Return whether a value is a serialized worker failure payload.
+      #
+      # @param value [Object]
+      #   Raw worker response.
+      # @return [Boolean]
+      # @api private
       def self.worker_failure?(value)
         value.is_a?(Hash) && value[:type] == FAILURE_MARKER
       end

data/lib/cdc/parallel/router.rb

@@ -2,10 +2,32 @@
 
 module CDC
   module Parallel
-    # Routes supported CDC objects to the correct runtime pool.
+    # Routes normalized `cdc-core` work items to the matching parallel runtime
+    # primitive.
+    #
+    # `Router` is deliberately small. It does not inspect source-specific
+    # payloads, apply filters, decode database values, or decide scheduling
+    # policy. Its responsibility is only to look at the already-normalized
+    # `cdc-core` object shape and forward it to the pool that knows how to
+    # process that shape.
+    #
+    # @example Routing a single event
+    #   router.process(change_event)
+    #
+    # @example Routing a transaction envelope
+    #   router.process(transaction_envelope)
+    #
+    # @see CDC::Parallel::ProcessorPool
+    # @see CDC::Parallel::TransactionPool
+    # @api public
     class Router
+      # Create a router for event and transaction work items.
+      #
       # @param processor_pool [ProcessorPool]
+      #   Pool used for individual `CDC::Core::ChangeEvent` objects.
       # @param transaction_pool [TransactionPool]
+      #   Pool used for `CDC::Core::TransactionEnvelope` objects.
+      # @return [void]
       def initialize(processor_pool:, transaction_pool:)
         @processor_pool = processor_pool
         @transaction_pool = transaction_pool
@@ -14,6 +36,9 @@ module CDC
       # Process a supported CDC work item.
       #
       # @param item [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope]
+      #   Normalized CDC work item.
+      # @raise [UnsupportedWorkItemError]
+      #   Raised when the item is not a supported `cdc-core` work item shape.
       # @return [CDC::Core::ProcessorResult]
       def process(item)
         case item

data/lib/cdc/parallel/runtime.rb

@@ -2,22 +2,101 @@
 
 module CDC
   module Parallel
-    # High-level Ractor runtime facade for cdc-core processors.
+    # High-level Ractor runtime facade for `cdc-core` processors.
+    #
+    # `Runtime` is the primary public entry point for applications that want to
+    # execute normalized CDC work items with `cdc-parallel`. It wires together a
+    # {ProcessorPool}, a {TransactionPool}, and a {Router} so callers can submit
+    # either a single `CDC::Core::ChangeEvent` or a
+    # `CDC::Core::TransactionEnvelope` through one object.
+    #
+    # Use this class when you want the default cdc-parallel behavior:
+    #
+    # * validate that the processor declared `ractor_safe!`
+    # * boot a fixed set of worker Ractors
+    # * route events and transaction envelopes to the right pool
+    # * return `CDC::Core::ProcessorResult` objects
+    # * shut down all worker resources together
+    #
+    # @example Processing a change event
+    #   runtime = CDC::Parallel::Runtime.new(
+    #     processor: AnalyticsProcessor.new,
+    #     size: 4,
+    #     timeout: 5
+    #   )
+    #
+    #   result = runtime.process(change_event)
+    #   result.success? #=> true
+    #
+    #   runtime.shutdown
+    #
+    # @example Processing a transaction envelope
+    #   result = runtime.process_transaction(transaction)
+    #
+    # @note `Runtime` is an execution facade, not a source adapter. It expects
+    #   work that has already been normalized into `cdc-core` primitives.
+    # @see CDC::Parallel::ProcessorPool
+    # @see CDC::Parallel::TransactionPool
+    # @see CDC::Parallel::Router
+    # @api public
     class Runtime
+      # Create a runtime with event and transaction pools.
+      #
       # @param processor [CDC::Core::Processor]
+      #   Ractor-safe processor used for both event and transaction processing.
       # @param size [Integer]
-      # @param timeout [Float, nil]
+      #   Number of worker Ractors per internal pool.
+      # @param timeout [Numeric, nil]
+      #   Optional timeout in seconds for result collection and shutdown waits.
+      # @param supervision [Boolean]
+      #   Whether worker Ractors should be respawned after unexpected death.
+      # @param max_respawns [Integer]
+      #   Maximum crash count inside `respawn_window` before a worker slot enters
+      #   cooldown.
+      # @param respawn_window [Numeric]
+      #   Time window, in seconds, used by the crash-loop circuit breaker.
+      # @param respawn_cooldown [Numeric]
+      #   Cooldown, in seconds, before a crash-looping slot is revived again.
+      # @raise [UnsafeProcessorError]
+      #   Raised when the processor class has not declared `ractor_safe!`.
+      # @raise [ArgumentError]
+      #   Raised when size or timeout is invalid.
       # @return [void]
-      def initialize(processor:, size: Etc.nprocessors, timeout: nil)
-        @processor_pool = ProcessorPool.new(processor:, size:, timeout:)
-        @transaction_pool = TransactionPool.new(processor:, size:, timeout:)
+      def initialize(
+        processor:,
+        size: Etc.nprocessors,
+        timeout: nil,
+        supervision: true,
+        max_respawns: 3,
+        respawn_window: 60,
+        respawn_cooldown: 5
+      )
+        @processor = processor
+        @processor.start
+
+        pool_options = build_pool_options(
+          processor:, size:, timeout:, supervision:,
+          max_respawns:, respawn_window:, respawn_cooldown:
+        )
+
+        @processor_pool = ProcessorPool.new(**pool_options)
+        @transaction_pool = TransactionPool.new(**pool_options)
         @router = Router.new(processor_pool: @processor_pool, transaction_pool: @transaction_pool)
         @shutdown = false
       end
 
-      # Process a ChangeEvent or TransactionEnvelope.
+      # Process a supported normalized CDC work item.
+      #
+      # Supported items are `CDC::Core::ChangeEvent` and
+      # `CDC::Core::TransactionEnvelope`. Unsupported objects raise
+      # {UnsupportedWorkItemError} from the router.
       #
       # @param item [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope]
+      #   Normalized CDC work item.
+      # @raise [ShutdownError]
+      #   Raised when called after {#shutdown}.
+      # @raise [UnsupportedWorkItemError]
+      #   Raised for objects that are not supported CDC work item shapes.
       # @return [CDC::Core::ProcessorResult]
       def process(item)
         raise ShutdownError, "runtime has been shut down" if @shutdown
@@ -25,7 +104,11 @@ module CDC
         @router.process(item)
       end
 
-      # Alias for transaction-oriented processing.
+      # Process a transaction envelope.
+      #
+      # This method is a readability alias for transaction-oriented call sites.
+      # It delegates to {#process}, so it has the same validation, shutdown, and
+      # result behavior.
       #
       # @param transaction [CDC::Core::TransactionEnvelope]
       # @return [CDC::Core::ProcessorResult]
@@ -35,6 +118,11 @@ module CDC
 
       # Shut down all runtime resources.
       #
+      # Shutdown is idempotent and cascades to the internal event and transaction
+      # pools. The processor's `flush` and `stop` lifecycle hooks are called once
+      # after all pools have been drained. After shutdown, {#process} raises
+      # {ShutdownError}.
+      #
       # @return [void]
       def shutdown
         return if @shutdown
@@ -42,6 +130,46 @@ module CDC
         @shutdown = true
         @processor_pool.shutdown
         @transaction_pool.shutdown
+        @processor.flush
+        @processor.stop
+      end
+
+      private
+
+      # Build keyword arguments shared by the event and transaction pools.
+      #
+      # The runtime owns the processor lifecycle, so internal pools receive
+      # `manage_lifecycle: false` to avoid duplicate `start`, `flush`, or `stop`
+      # calls for the same processor instance.
+      #
+      # @param processor [CDC::Core::Processor]
+      # @param size [Integer]
+      # @param timeout [Numeric, nil]
+      # @param supervision [Boolean]
+      # @param max_respawns [Integer]
+      # @param respawn_window [Numeric]
+      # @param respawn_cooldown [Numeric]
+      # @return [Hash]
+      # @api private
+      def build_pool_options(
+        processor:,
+        size:,
+        timeout:,
+        supervision:,
+        max_respawns:,
+        respawn_window:,
+        respawn_cooldown:
+      )
+        {
+          processor:,
+          size:,
+          timeout:,
+          supervision:,
+          max_respawns:,
+          respawn_window:,
+          respawn_cooldown:,
+          manage_lifecycle: false
+        }
       end
     end
   end

data/lib/cdc/parallel/transaction_pool.rb

@@ -2,30 +2,112 @@
 
 module CDC
   module Parallel
-    # Processes a TransactionEnvelope as a single ordering-preserving unit.
+    # Processes a `CDC::Core::TransactionEnvelope` as one transaction-oriented
+    # work unit.
+    #
+    # `TransactionPool` uses {ProcessorPool} to process the events inside an
+    # envelope and then collapses the event-level results into one
+    # `CDC::Core::ProcessorResult` for the whole transaction.
+    #
+    # This class preserves the transaction boundary at the API level: callers
+    # submit a transaction envelope and receive a single success or failure
+    # result. Event results inside the transaction are still produced by the
+    # configured processor and are returned as the success value when every event
+    # succeeds.
+    #
+    # @example Processing a transaction envelope
+    #   pool = CDC::Parallel::TransactionPool.new(
+    #     processor: AuditProcessor.new,
+    #     size: 4
+    #   )
+    #
+    #   result = pool.process(transaction)
+    #   result.success? #=> true
+    #
+    # @note This class preserves the transaction as a result boundary. More
+    #   advanced ordering, checkpointing, retry, and atomic sink semantics belong
+    #   to higher-level runtime/sink contracts.
+    # @see CDC::Parallel::ProcessorPool
+    # @api public
     class TransactionPool
+      # Create a transaction pool.
+      #
       # @param processor [CDC::Core::Processor]
+      #   Ractor-safe processor used for each event inside the transaction.
       # @param size [Integer]
-      # @param timeout [Float, nil]
-      def initialize(processor:, size: Etc.nprocessors, timeout: nil)
-        @processor_pool = ProcessorPool.new(processor:, size:, timeout:)
+      #   Number of worker Ractors in the underlying processor pool.
+      # @param timeout [Numeric, nil]
+      #   Optional timeout in seconds for result collection and shutdown waits.
+      # @param supervision [Boolean]
+      #   Whether worker Ractors should be respawned after unexpected death.
+      # @param max_respawns [Integer]
+      #   Maximum crash count inside `respawn_window` before a worker slot enters
+      #   cooldown.
+      # @param respawn_window [Numeric]
+      #   Time window, in seconds, used by the crash-loop circuit breaker.
+      # @param respawn_cooldown [Numeric]
+      #   Cooldown, in seconds, before a crash-looping slot is revived again.
+      # @param manage_lifecycle [Boolean]
+      #   When `true` (default), the pool calls `processor.start` during
+      #   initialization and `processor.flush` + `processor.stop` during shutdown.
+      #   Set to `false` when a higher-level runtime owns the processor lifecycle.
+      # @raise [UnsafeProcessorError]
+      #   Raised when the processor class has not declared `ractor_safe!`.
+      # @return [void]
+      def initialize(
+        processor:,
+        size: Etc.nprocessors,
+        timeout: nil,
+        supervision: true,
+        max_respawns: 3,
+        respawn_window: 60,
+        respawn_cooldown: 5,
+        manage_lifecycle: true
+      )
+        @processor_pool = ProcessorPool.new(
+          processor:,
+          size:,
+          timeout:,
+          supervision:,
+          max_respawns:,
+          respawn_window:,
+          respawn_cooldown:,
+          manage_lifecycle:
+        )
       end
 
       # Process all events inside a transaction envelope.
       #
+      # The returned result is successful only when every event result succeeds.
+      # If any event fails, the transaction result is a failure using the first
+      # failure error and the complete event-result list as context.
+      #
       # @param transaction [CDC::Core::TransactionEnvelope]
+      #   Transaction envelope whose `events` will be processed.
       # @return [CDC::Core::ProcessorResult]
+      #   Success containing the ordered event results, or failure containing the
+      #   first event error.
       def process(transaction)
         results = @processor_pool.process_many(transaction.events).freeze
         failure = results.find(&:failure?)
 
-        return CDC::Core::ProcessorResult.failure(failure.error, event: results) if failure
+        if failure
+          error = failure.error || ProcessorExecutionError.new(
+            original_class: "CDC::Core::ProcessorResult",
+            original_message: "failed processor result did not include an error"
+          )
+
+          return CDC::Core::ProcessorResult.failure(error, event: results)
+        end
 
         CDC::Core::ProcessorResult.success(results)
       end
 
       # Shut down worker resources.
       #
+      # Delegates to the underlying {ProcessorPool}. Shutdown is idempotent
+      # because the underlying pool is idempotent.
+      #
       # @return [void]
       def shutdown
         @processor_pool.shutdown

data/lib/cdc/parallel/version.rb

@@ -3,6 +3,11 @@
 module CDC
   module Parallel
     # Current cdc-parallel version.
-    VERSION = "0.2.2"
+    #
+    # This constant is used by RubyGems and by applications that need to inspect
+    # the loaded runtime version at boot time.
+    #
+    # @return [String]
+    VERSION = "0.2.4"
   end
 end

data/lib/cdc/parallel.rb

@@ -12,8 +12,46 @@ require_relative "parallel/transaction_pool"
 require_relative "parallel/router"
 require_relative "parallel/runtime"
 
+# Namespace for Change Data Capture ecosystem components.
+#
+# The `cdc-parallel` gem adds the {CDC::Parallel} runtime namespace under
+# this shared ecosystem root.
+#
+# @api public
 module CDC
-  # Optional parallel Change Data Capture runtime for cdc-core processors.
+  # Optional parallel Change Data Capture runtime for `cdc-core` processors.
+  #
+  # `CDC::Parallel` is the CPU-bound execution layer of the CDC Ecosystem. It
+  # consumes work items that have already been normalized into `cdc-core`
+  # vocabulary objects and executes Ractor-safe processors across pre-warmed
+  # worker Ractors.
+  #
+  # The namespace intentionally avoids `CDC::Ractor` so it does not collide with
+  # Ruby's core `::Ractor` constant.
+  #
+  # ## Boundary
+  #
+  # `cdc-parallel` does not connect to PostgreSQL, parse `pgoutput`, decode
+  # values, normalize source payloads, or persist sink data. Those concerns live
+  # upstream in `pgoutput-*` libraries, source adapters, and downstream sinks.
+  #
+  # ## Main entry points
+  #
+  # * {CDC::Parallel::Runtime} - high-level facade for events and transactions
+  # * {CDC::Parallel::ProcessorPool} - low-level Ractor worker pool
+  # * {CDC::Parallel::TransactionPool} - transaction-envelope wrapper
+  # * {CDC::Parallel::Router} - work item router
+  #
+  # @example
+  #   runtime = CDC::Parallel::Runtime.new(
+  #     processor: AnalyticsProcessor.new,
+  #     size: 4
+  #   )
+  #
+  #   result = runtime.process(change_event)
+  #   runtime.shutdown
+  #
+  # @api public
   module Parallel
   end
 end

data/sig/cdc/parallel/configuration.rbs

@@ -1,8 +1,20 @@
 module CDC
   module Parallel
+    # Private Data superclass used to keep YARD documentation stable for Configuration.
+    class ConfigurationData < Data
+      attr_reader size: Integer
+      attr_reader timeout: Numeric?
+    end
+
     # Immutable configuration for Ractor runtimes.
-    class Configuration
-      def initialize: (?size: untyped, ?timeout: untyped?) -> void
+    class Configuration < ConfigurationData
+      attr_reader size: Integer
+
+      attr_reader timeout: Numeric?
+
+      def self.new: (?size: Integer, ?timeout: Numeric?) -> instance
+
+      def initialize: (?size: Integer, ?timeout: Numeric?) -> void
     end
   end
 end

data/sig/cdc/parallel/errors.rbs

@@ -18,19 +18,19 @@ module CDC
 
     # Raised when processor execution fails inside a worker Ractor.
     class ProcessorExecutionError < Error
-      @original_class: untyped
+      @original_class: String
 
-      @original_message: untyped
+      @original_message: String
 
-      @original_backtrace: untyped
+      @original_backtrace: Array[String]
 
-      attr_reader original_class: untyped
+      attr_reader original_class: String
 
-      attr_reader original_message: untyped
+      attr_reader original_message: String
 
-      attr_reader original_backtrace: untyped
+      attr_reader original_backtrace: Array[String]
 
-      def initialize: (original_class: untyped, original_message: untyped, ?original_backtrace: untyped) -> void
+      def initialize: (original_class: String?, original_message: String, ?original_backtrace: Array[String]) -> void
     end
 
     # Raised when a worker does not return a result before timeout.