tasker-rb 0.1.3-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8ed4ebd9912ca9a7b20f052991f07c260be1809876e1727b7a0e36ec5d8d6c52
+  data.tar.gz: b1f6d776dbb3e03ca2c488d7d611ecba12c689e265036edcbe206a6718c9feb1
+SHA512:
+  metadata.gz: 7253ebf0a02c9888fe2b0f23a380fba34d3ec43145496df714b390ec95050f0fede2b01220e72972d4329f270f213aa8bedb8f1df38506a81274c3f973ce1ae2
+  data.tar.gz: 8ee494e98a9a38c12aa51aae18bdfc7f1b7287cce9f6eaaf7674ead230a2fbec44401b091e702172737658c9e1799a819ae34ce2814311a59eb1347fdb2c8185

data/README.md

@@ -0,0 +1,55 @@
+# Tasker Core Ruby Bindings
+
+Ruby FFI bindings for the high-performance Tasker Core Rust orchestration engine.
+
+## Status
+
+Production ready. Ruby FFI bindings provide full step handler execution via Magnus.
+
+## Development Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Compile the Rust extension (requires Ruby dev environment)
+rake compile
+
+# Run tests
+rake spec
+
+# Full development setup
+rake setup
+```
+
+## Architecture
+
+This gem follows the **delegation-based architecture**:
+
+```
+Rails Engine ↔ tasker-core-rb (FFI) ↔ tasker-core (Performance Core)
+```
+
+- **Rails**: Business logic and step execution
+- **Rust**: High-performance orchestration and dependency resolution
+- **Ruby Bindings**: Safe FFI bridge between the two
+
+## Performance Targets
+
+- **10-100x faster** dependency resolution vs PostgreSQL functions
+- **<1ms FFI overhead** per orchestration call
+- **>10k events/sec** cross-language event processing
+
+## Requirements
+
+- **Ruby**: 3.0+ with development headers
+- **Rust**: 1.70+ with magnus dependencies
+- **PostgreSQL**: 12+ for database operations
+
+## Contributing
+
+This is part of the larger tasker-systems monorepo. See the main project documentation for development guidelines and contribution instructions.
+
+---
+
+🦀 **Built with Rust + Magnus for maximum performance and safety**

data/lib/tasker_core/batch_processing/batch_aggregation_scenario.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  module BatchProcessing
+    # Ruby equivalent of Rust's BatchAggregationScenario
+    #
+    # Detects whether a batchable step created batch workers or returned NoBatches outcome.
+    # Uses DependencyResultsWrapper to access parent step results.
+    #
+    # This helper distinguishes two scenarios:
+    # - **NoBatches**: Batchable step returned NoBatches outcome, only placeholder worker exists
+    # - **WithBatches**: Batchable step created real batch workers for parallel processing
+    #
+    # @example Detecting aggregation scenario
+    #   scenario = BatchAggregationScenario.detect(
+    #     sequence_step,
+    #     'analyze_dataset',
+    #     'process_batch_'
+    #   )
+    #
+    #   if scenario.no_batches?
+    #     # Handle NoBatches scenario - use batchable result directly
+    #     return scenario.batchable_result
+    #   else
+    #     # Handle WithBatches scenario - aggregate worker results
+    #     total = scenario.batch_results.values.sum
+    #     return { total: total, worker_count: scenario.worker_count }
+    #   end
+    class BatchAggregationScenario
+      attr_reader :type, :batchable_result, :batch_results, :worker_count
+
+      # Detect aggregation scenario from step dependencies
+      #
+      # @param dependency_results [DependencyResultsWrapper] Dependency results wrapper
+      # @param batchable_step_name [String] Name of the batchable step
+      # @param batch_worker_prefix [String] Prefix for batch worker step names
+      # @return [BatchAggregationScenario] Detected scenario
+      def self.detect(dependency_results, batchable_step_name, batch_worker_prefix)
+        # dependency_results is already a DependencyResultsWrapper - pass it directly
+        new(dependency_results, batchable_step_name, batch_worker_prefix)
+      end
+
+      # Initialize aggregation scenario
+      #
+      # @param dependency_results [DependencyResultsWrapper] Dependency results wrapper
+      # @param batchable_step_name [String] Name of the batchable step
+      # @param batch_worker_prefix [String] Prefix for batch worker step names
+      def initialize(dependency_results, batchable_step_name, batch_worker_prefix)
+        # Get the batchable step result (extract the 'result' field)
+        @batchable_result = dependency_results.get_results(batchable_step_name)
+
+        # Find all batch worker results by prefix matching (extract 'result' field from each)
+        @batch_results = {}
+        dependency_results.each_key do |step_name|
+          if step_name.start_with?(batch_worker_prefix)
+            @batch_results[step_name] = dependency_results.get_results(step_name)
+          end
+        end
+
+        # Determine scenario type based on batch worker count
+        if @batch_results.empty?
+          @type = :no_batches
+          @worker_count = 0
+        else
+          @type = :with_batches
+          @worker_count = @batch_results.size
+        end
+      end
+
+      # Check if scenario is NoBatches
+      #
+      # @return [Boolean] True if batchable step returned NoBatches outcome
+      def no_batches?
+        @type == :no_batches
+      end
+
+      # Check if scenario is WithBatches
+      #
+      # @return [Boolean] True if batch workers were created
+      def with_batches?
+        @type == :with_batches
+      end
+    end
+  end
+end

data/lib/tasker_core/batch_processing/batch_worker_context.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  module BatchProcessing
+    # Ruby equivalent of Rust's BatchWorkerContext
+    #
+    # Extracts cursor config from workflow_step.inputs via WorkflowStepWrapper.
+    # This mirrors the Rust implementation which deserializes BatchWorkerInputs
+    # from the workflow_step.inputs field.
+    #
+    # @example Checking if worker is no-op
+    #   context = BatchWorkerContext.from_step_data(sequence_step)
+    #   if context.no_op?
+    #     # Handle placeholder worker for NoBatches scenario
+    #     return success_result(message: 'No-op worker completed')
+    #   end
+    #
+    # @example Accessing cursor configuration
+    #   context = BatchWorkerContext.from_step_data(sequence_step)
+    #   start = context.start_cursor  # => 0
+    #   end_pos = context.end_cursor  # => 1000
+    #   batch_id = context.batch_id     # => "001"
+    #
+    # == Cursor Flexibility
+    #
+    # Cursors are intentionally flexible to support diverse business logic scenarios.
+    # The system validates numeric cursors when both values are integers, but cursors
+    # can also be alphanumeric strings, timestamps, UUIDs, or any comparable type that
+    # makes sense for your data partitioning strategy.
+    #
+    # With great power comes great responsibility: ensure your cursor implementation
+    # matches your data source's capabilities and that your handler logic correctly
+    # interprets the cursor boundaries.
+    #
+    # @example Numeric cursors (validated for ordering)
+    #   cursor: {
+    #     batch_id: '001',
+    #     start_cursor: 0,      # Integer cursors are validated
+    #     end_cursor: 1000
+    #   }
+    #
+    # @example Alphanumeric cursors (developer responsibility)
+    #   cursor: {
+    #     batch_id: '002',
+    #     start_cursor: 'A',    # String cursors for alphabetical ranges
+    #     end_cursor: 'M'
+    #   }
+    #
+    # @example UUID-based cursors (developer responsibility)
+    #   cursor: {
+    #     batch_id: '003',
+    #     start_cursor: '00000000-0000-0000-0000-000000000000',
+    #     end_cursor: '88888888-8888-8888-8888-888888888888'
+    #   }
+    #
+    # @example Timestamp cursors (developer responsibility)
+    #   cursor: {
+    #     batch_id: '004',
+    #     start_cursor: '2024-01-01T00:00:00Z',
+    #     end_cursor: '2024-01-31T23:59:59Z'
+    #   }
+    class BatchWorkerContext
+      attr_reader :cursor, :batch_metadata, :is_no_op, :checkpoint
+
+      # Extract context from WorkflowStepWrapper
+      #
+      # @param workflow_step [WorkflowStepWrapper] Workflow step wrapper
+      # @return [BatchWorkerContext] Extracted context
+      def self.from_step_data(workflow_step)
+        new(workflow_step)
+      end
+
+      # Initialize batch worker context from workflow step
+      #
+      # Reads BatchWorkerInputs from workflow_step.inputs (instance data)
+      # not from step_definition.handler.initialization (template data).
+      #
+      # @param workflow_step [WorkflowStepWrapper] Workflow step wrapper
+      def initialize(workflow_step)
+        # Access inputs via WorkflowStepWrapper
+        # Use ActiveSupport deep_symbolize_keys for clean key access
+        inputs = (workflow_step.inputs || {}).deep_symbolize_keys
+
+        @is_no_op = inputs[:is_no_op] == true
+
+        # TAS-125: Extract checkpoint data from workflow step
+        # Checkpoint contains persisted progress from previous yields
+        # Use with_indifferent_access for flexible string/symbol key access
+        @checkpoint = (workflow_step.checkpoint || {}).with_indifferent_access
+
+        if @is_no_op
+          # Placeholder worker - minimal context
+          @cursor = {}
+          @batch_metadata = {}
+        else
+          @cursor = inputs[:cursor] || {}
+          @batch_metadata = inputs[:batch_metadata] || {}
+
+          validate_cursor!
+        end
+      end
+
+      # Get the starting cursor in the dataset (inclusive)
+      #
+      # @return [Integer] Starting cursor position
+      def start_cursor
+        cursor[:start_cursor].to_i
+      end
+
+      # Get the ending cursor in the dataset (exclusive)
+      #
+      # @return [Integer] Ending cursor position
+      def end_cursor
+        cursor[:end_cursor].to_i
+      end
+
+      # Get the batch identifier
+      #
+      # @return [String] Batch ID (e.g., "001", "002", "000" for no-op)
+      def batch_id
+        cursor[:batch_id] || 'unknown'
+      end
+
+      # Check if this is a no-op/placeholder worker
+      #
+      # @return [Boolean] True if this worker should skip processing
+      def no_op?
+        @is_no_op
+      end
+
+      # TAS-125: Get checkpoint cursor from previous yield
+      #
+      # When a handler yields a checkpoint, the cursor position is persisted.
+      # On re-dispatch, this returns that cursor position to resume from.
+      #
+      # @return [Integer, String, Hash, nil] Last persisted cursor position, or nil if no checkpoint
+      #
+      # @example Resume from checkpoint
+      #   start = batch_ctx.checkpoint_cursor || batch_ctx.start_cursor
+      def checkpoint_cursor
+        checkpoint[:cursor]
+      end
+
+      # TAS-125: Get accumulated results from previous checkpoint yield
+      #
+      # When a handler yields a checkpoint with accumulated_results, those
+      # partial aggregations are persisted. On re-dispatch, this returns
+      # them so the handler can continue accumulating.
+      #
+      # @return [Hash, nil] Partial aggregations from previous yields
+      #
+      # @example Continue accumulating totals
+      #   accumulated = batch_ctx.accumulated_results || { 'total' => 0 }
+      #   accumulated['total'] += item.value
+      def accumulated_results
+        checkpoint[:accumulated_results]
+      end
+
+      # TAS-125: Check if checkpoint exists
+      #
+      # Use this to determine if this is a fresh execution or a resumption
+      # from a previous checkpoint yield.
+      #
+      # @return [Boolean] True if checkpoint data exists
+      #
+      # @example Conditional initialization
+      #   if batch_ctx.has_checkpoint?
+      #     # Resuming from previous checkpoint
+      #     start = batch_ctx.checkpoint_cursor
+      #   else
+      #     # Fresh start
+      #     start = batch_ctx.start_cursor
+      #   end
+      def has_checkpoint?
+        checkpoint.present? && checkpoint[:cursor].present?
+      end
+
+      # TAS-125: Get items processed count from checkpoint
+      #
+      # Returns the cumulative count of items processed across all yields.
+      #
+      # @return [Integer] Items processed so far, or 0 if no checkpoint
+      def checkpoint_items_processed
+        checkpoint[:items_processed] || 0
+      end
+
+      private
+
+      # Validate cursor configuration for real workers
+      #
+      # @raise [ArgumentError] If cursor configuration is invalid
+      def validate_cursor!
+        return if @is_no_op
+
+        raise ArgumentError, 'Missing cursor configuration' if cursor.empty?
+        raise ArgumentError, 'Missing batch_id' unless cursor[:batch_id]
+        raise ArgumentError, 'Missing start_cursor' unless cursor.key?(:start_cursor)
+        raise ArgumentError, 'Missing end_cursor' unless cursor.key?(:end_cursor)
+
+        # Extract cursor values for validation
+        start_val = cursor[:start_cursor]
+        end_val = cursor[:end_cursor]
+
+        # Validate numeric cursors if they're integers
+        # (supports both integer and other types like timestamps/UUIDs)
+        return unless start_val.is_a?(Integer) || end_val.is_a?(Integer)
+
+        # If one is integer, both should be integers
+        unless start_val.is_a?(Integer) && end_val.is_a?(Integer)
+          raise ArgumentError,
+                "Mixed cursor types not allowed: start=#{start_val.class}, end=#{end_val.class}"
+        end
+
+        # Validate non-negative values
+        if start_val.negative?
+          raise ArgumentError,
+                "start_cursor must be non-negative, got #{start_val}"
+        end
+        if end_val.negative?
+          raise ArgumentError,
+                "end_cursor must be non-negative, got #{end_val}"
+        end
+
+        # Validate logical ordering
+        if start_val > end_val
+          raise ArgumentError,
+                "start_cursor (#{start_val}) must be <= end_cursor (#{end_val})"
+        end
+
+        # Warn about zero-length ranges (likely a bug)
+        return unless start_val == end_val
+
+        warn "WARNING: Zero-length cursor range (#{start_val} == #{end_val}) " \
+             "- worker will process no data. batch_id=#{cursor[:batch_id]}"
+      end
+    end
+  end
+end