fractor 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b4ea06ce5fb4dc056cd294dcadeac07cca24610a0b995e5f910b3ef0075e0ea
-  data.tar.gz: 1adc8b962143e4713259b18c5545ab39ee0a62b11db5880b0389ff64449a27b8
+  metadata.gz: 22b2448a14f44c78c6b4970d9529aa9e88257ff63423be18e57dd87290f5247b
+  data.tar.gz: 27a514ab149f2115e5e53fe0c4a3199d09adeb355789ce21ff85ab93b8cb1891
 SHA512:
-  metadata.gz: 31800cb4767762f1bdd1fec315cda164fd5effb3fd72bb327b4a30788ac41b2b2cd0ec3bcf2548e82fe69ccf97150007222e81c875bcb5f78c01d4e28162ef03
-  data.tar.gz: 728316725154c5fde32f2bb8fb6ab584b26814ad463af43c4928a333083ed34e6d66dc781c6edad82128644f0f6b6197c31303aa6353ec586aeaa81212dd911d
+  metadata.gz: 2da27fec2e527d266dc85e3fc29fd646740e76c8b9e77a5c6171bd79fa6054f4a0bae79fc72d99aa4ca683a5fcf5a9f079aeef35123ce4e25de846948ba9a991
+  data.tar.gz: 7d01bbb10b527954f8afdb1dd9e9e8858342a71fddf3734bbc178a4ab0c227e9b69ee4f336b3f37016a17da4ea1e69c1dc65a48fa31de73cef6469bf413e851e

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-01-22 09:15:54 UTC using RuboCop version 1.82.1.
+# on 2026-01-27 14:55:44 UTC using RuboCop version 1.82.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,80 +11,13 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'fractor.gemspec'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'lib/fractor/queue_persister.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_element, with_fixed_indentation
-Layout/ArrayAlignment:
-  Exclude:
-    - 'lib/fractor/queue_persister.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: IndentationWidth.
-Layout/AssignmentIndentation:
-  Exclude:
-    - 'lib/fractor/queue_persister.rb'
-    - 'lib/fractor/result_cache.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Layout/ClosingParenthesisIndentation:
-  Exclude:
-    - 'spec/fractor/persistent_work_queue_spec.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: consistent, consistent_relative_to_receiver, special_for_inner_method_call, special_for_inner_method_call_in_parentheses
-Layout/FirstArgumentIndentation:
-  Exclude:
-    - 'spec/fractor/persistent_work_queue_spec.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
-# SupportedHashRocketStyles: key, separator, table
-# SupportedColonStyles: key, separator, table
-# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
-Layout/HashAlignment:
-  Exclude:
-    - 'spec/fractor/persistent_work_queue_spec.rb'
-    - 'spec/fractor/work_timeout_spec.rb'
-
-# Offense count: 470
+# Offense count: 498
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: symmetrical, new_line, same_line
-Layout/MultilineMethodCallBraceLayout:
-  Exclude:
-    - 'spec/fractor/persistent_work_queue_spec.rb'
-
-# Offense count: 6
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'lib/fractor/queue_persister.rb'
-    - 'lib/fractor/result_cache.rb'
-    - 'spec/fractor/persistent_work_queue_spec.rb'
-    - 'spec/fractor/work_timeout_spec.rb'
-
 # Offense count: 1
 Lint/BinaryOperatorWithIdenticalOperands:
   Exclude:
@@ -143,7 +76,13 @@ Lint/UnusedMethodArgument:
     - 'lib/fractor/workflow.rb'
     - 'lib/fractor/wrapped_ractor3.rb'
 
-# Offense count: 89
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Lint/UselessAssignment:
+  Exclude:
+    - 'lib/fractor/wrapped_ractor.rb'
+
+# Offense count: 92
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -159,17 +98,17 @@ Metrics/BlockLength:
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 149
+# Offense count: 155
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 122
 
-# Offense count: 9
+# Offense count: 10
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 9
 
-# Offense count: 49
+# Offense count: 50
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -193,17 +132,14 @@ Naming/PredicatePrefix:
     - '../../../.cache/rubocop_cache/spec/**/*'
     - 'spec/support/workflow_helpers.rb'
 
-# Offense count: 9
+# Offense count: 6
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
 # AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
 Naming/VariableNumber:
   Exclude:
     - 'lib/fractor/error_statistics.rb'
-    - 'lib/fractor/main_loop_handler.rb'
     - 'lib/fractor/main_loop_handler4.rb'
-    - 'lib/fractor/supervisor.rb'
-    - 'lib/fractor/wrapped_ractor.rb'
     - 'spec/examples/error_reporting_spec.rb'
     - 'spec/fractor/workflow/retry_orchestrator_spec.rb'
 
@@ -227,12 +163,12 @@ RSpec/ContextWording:
     - 'spec/fractor/supervisor_spec.rb'
     - 'spec/fractor_spec.rb'
 
-# Offense count: 28
+# Offense count: 29
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
 
-# Offense count: 542
+# Offense count: 549
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 47
@@ -293,7 +229,7 @@ RSpec/LeakyConstantDeclaration:
     - 'spec/fractor/worker_timeout_spec.rb'
     - 'spec/fractor/workflow/execution_strategy_spec.rb'
 
-# Offense count: 19
+# Offense count: 24
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: have_received, receive
 RSpec/MessageSpies:
@@ -313,11 +249,11 @@ RSpec/MultipleDescribes:
     - 'spec/fractor/workflow/retry_config_spec.rb'
     - 'spec/fractor/workflow/retry_strategy_spec.rb'
 
-# Offense count: 635
+# Offense count: 636
 RSpec/MultipleExpectations:
   Max: 12
 
-# Offense count: 50
+# Offense count: 52
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 9
@@ -364,13 +300,6 @@ Security/MarshalLoad:
   Exclude:
     - 'lib/fractor/queue_persister.rb'
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-Style/MultilineIfModifier:
-  Exclude:
-    - 'lib/fractor/queue_persister.rb'
-    - 'lib/fractor/result_cache.rb'
-
 # Offense count: 1
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?
@@ -378,10 +307,18 @@ Style/OptionalBooleanParameter:
   Exclude:
     - 'lib/fractor/workflow/job.rb'
 
-# Offense count: 2
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowedMethods.
+# AllowedMethods: nonzero?
+Style/RedundantCondition:
+  Exclude:
+    - 'lib/fractor/supervisor.rb'
+
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleForMultiline.
 # SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
 Style/TrailingCommaInArguments:
   Exclude:
-    - 'spec/examples/workflow/retry_workflow_spec.rb'
+    - 'lib/fractor/supervisor.rb'

data/docs/ARCHITECTURE.md

@@ -0,0 +1,317 @@
+# Fractor Architecture
+
+This document provides architecture diagrams and descriptions of the Fractor framework's components.
+
+## Overview
+
+Fractor is a function-driven Ractors framework for Ruby that provides true parallelism using Ruby's Ractor feature with automatic work distribution across isolated workers.
+
+## High-Level Architecture
+
+```mermaid
+graph TB
+    subgraph "Application Layer"
+        Work[Work<br/>Immutable Input]
+        Worker[Worker<br/>Processing Logic]
+        WorkResult[WorkResult<br/>Success/Error Output]
+    end
+
+    subgraph "Orchestration Layer"
+        Supervisor[Supervisor<br/>Main Orchestrator]
+        ContinuousServer[ContinuousServer<br/>Long-Running Mode]
+        WorkflowExecutor[WorkflowExecutor<br/>Multi-Step Pipelines]
+    end
+
+    subgraph "Concurrency Layer"
+        WorkQueue[WorkQueue<br/>Thread-Safe Queue]
+        ResultAggregator[ResultAggregator<br/>Thread-Safe Results]
+        CallbackRegistry[CallbackRegistry<br/>Event Callbacks]
+        WrappedRactor[WrappedRactor<br/>Ractor Wrapper]
+        WorkDistributionManager[WorkDistributionManager<br/>Idle Worker Tracking]
+    end
+
+    subgraph "Ractor Layer"
+        Ractor1[Ractor 1]
+        Ractor2[Ractor 2]
+        Ractor3[Ractor 3]
+    end
+
+    Work --> Supervisor
+    Worker --> WorkflowExecutor
+    WorkResult --> ResultAggregator
+
+    Supervisor --> WorkQueue
+    Supervisor --> ResultAggregator
+    Supervisor --> CallbackRegistry
+    Supervisor --> WorkDistributionManager
+
+    ContinuousServer --> Supervisor
+
+    WorkflowExecutor --> Supervisor
+    WorkflowExecutor --> WorkQueue
+
+    WorkDistributionManager --> WrappedRactor
+    WrappedRactor --> Ractor1
+    WrappedRactor --> Ractor2
+    WrappedRactor --> Ractor3
+
+    Ractor1 --> Worker
+    Ractor2 --> Worker
+    Ractor3 --> Worker
+
+    style Work fill:#e1f5e1
+    style Worker fill:#e1f5e1
+    style WorkResult fill:#e1f5e1
+    style Supervisor fill:#e3f2fd
+    style ContinuousServer fill:#e3f2fd
+    style WorkflowExecutor fill:#e3f2fd
+    style WrappedRactor fill:#fff3e0
+    style Ractor1 fill:#fce4ec
+    style Ractor2 fill:#fce4ec
+    style Ractor3 fill:#fce4ec
+```
+
+## Component Relationships
+
+```mermaid
+graph LR
+    subgraph "User Code"
+        MyWork[MyWork < Work]
+        MyWorker[MyWorker < Worker]
+    end
+
+    subgraph "Fractor Core"
+        Supervisor[Supervisor]
+        Queue[WorkQueue]
+        Results[ResultAggregator]
+    end
+
+    subgraph "Worker Pool"
+        W1[Worker Ractor 1]
+        W2[Worker Ractor 2]
+        W3[Worker Ractor 3]
+    end
+
+    MyWork --> Supervisor
+    MyWorker --> Supervisor
+
+    Supervisor --> Queue
+    Queue --> W1
+    Queue --> W2
+    Queue --> W3
+
+    W1 --> Results
+    W2 --> Results
+    W3 --> Results
+
+    Results --> Supervisor
+    Supervisor --> MyWork
+```
+
+## Pipeline Mode Execution Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Supervisor
+    participant WorkQueue
+    participant Worker as Worker Ractor
+    participant Results
+    participant Callback as CallbackRegistry
+
+    User->>Supervisor: new(worker_pools: [...])
+    User->>Supervisor: add_work_items(items)
+    Supervisor->>WorkQueue: enqueue items
+    User->>Supervisor: run()
+
+    loop Main Loop
+        Supervisor->>WorkQueue: pop_batch()
+        WorkQueue-->>Supervisor: work items
+
+        Supervisor->>Worker: send work
+        Worker->>Worker: process(work)
+        Worker-->>Supervisor: WorkResult
+        Supervisor->>Results: add(result)
+
+        Supervisor->>Callback: process_work_callbacks()
+        Callback-->>Supervisor: new_work (optional)
+    end
+
+    Supervisor-->>User: results
+```
+
+## Continuous Mode Execution Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Server as ContinuousServer
+    participant Supervisor
+    participant Queue as WorkQueue
+    participant Callbacks as CallbackRegistry
+
+    User->>Server: new(worker_pools, work_queue)
+    Server->>Supervisor: new(continuous_mode: true)
+    Queue->>Supervisor: register_work_source()
+    Server->>Server: run()
+
+    loop Continuous Processing
+        Supervisor->>Callbacks: process_work_callbacks()
+        Callbacks-->>Supervisor: new work items
+        Supervisor->>Queue: enqueue new work
+        Note over Supervisor,Queue: Distribute to workers
+
+        Server->>Server: on_result callback
+        Server->>Server: on_error callback
+    end
+
+    User->>Server: stop() / Ctrl+C
+    Server->>Supervisor: stop()
+    Server-->>User: shutdown complete
+```
+
+## Workflow System Architecture
+
+```mermaid
+graph TB
+    subgraph "Workflow Definition"
+        DSL[Workflow DSL]
+        Builder[Workflow Builder]
+        Job[Job Definitions]
+    end
+
+    subgraph "Workflow Execution"
+        Executor[WorkflowExecutor]
+        Resolver[DependencyResolver<br/>Topological Sort]
+        Logger[WorkflowExecutionLogger]
+    end
+
+    subgraph "Execution Components"
+        JobExecutor[JobExecutor]
+        Retry[RetryOrchestrator]
+        Circuit[CircuitBreakerOrchestrator]
+        Fallback[FallbackJobHandler]
+        DLQ[DeadLetterQueue]
+    end
+
+    DSL --> Builder
+    Builder --> Job
+    Job --> Executor
+
+    Executor --> Resolver
+    Executor --> Logger
+    Executor --> JobExecutor
+
+    JobExecutor --> Retry
+    JobExecutor --> Circuit
+    JobExecutor --> Fallback
+    JobExecutor --> DLQ
+```
+
+## Ruby Version-Specific Architecture
+
+```mermaid
+graph LR
+    subgraph "Ruby 3.x"
+        R3Handler[MainLoopHandler]
+        R3Wrapped[WrappedRactor]
+        R3Method[Ractor.yield / Ractor.receive]
+    end
+
+    subgraph "Ruby 4.0+"
+        R4Handler[MainLoopHandler4]
+        R4Wrapped[WrappedRactor4]
+        R4Method[Ractor::Port / Ractor.select]
+    end
+
+    subgraph "Shared"
+        Supervisor[Supervisor]
+        Common[Common Components]
+    end
+
+    Supervisor --> R3Handler
+    Supervisor --> R4Handler
+
+    R3Handler --> R3Wrapped
+    R3Wrapped --> R3Method
+
+    R4Handler --> R4Wrapped
+    R4Wrapped --> R4Method
+
+    R3Handler --> Common
+    R4Handler --> Common
+```
+
+## Component Responsibilities
+
+### Application Layer
+
+| Component | Responsibility |
+|-----------|---------------|
+| **Work** | Immutable data container with input data |
+| **Worker** | Processing logic with `process(work)` method |
+| **WorkResult** | Contains success/failure status, result value, or error |
+
+### Orchestration Layer
+
+| Component | Responsibility |
+|-----------|---------------|
+| **Supervisor** | Main orchestrator for pipeline mode, manages worker lifecycle |
+| **ContinuousServer** | High-level wrapper for long-running services |
+| **WorkflowExecutor** | Orchestrates multi-step workflow executions |
+
+### Concurrency Layer
+
+| Component | Responsibility |
+|-----------|---------------|
+| **WorkQueue** | Thread-safe queue for work items |
+| **ResultAggregator** | Thread-safe result collection with event notifications |
+| **CallbackRegistry** | Manages work source and error callbacks |
+| **WrappedRactor** | Safe wrapper around Ruby Ractor with version-specific implementations |
+| **WorkDistributionManager** | Tracks idle workers and distributes work efficiently |
+
+### Ractor Layer
+
+| Component | Responsibility |
+|-----------|---------------|
+| **Ractor 1, 2, 3...** | Isolated Ruby Ractors containing Worker instances |
+| **Worker instances** | Each Ractor has its own Worker instance for processing |
+
+## Data Flow
+
+### Work Processing Flow
+
+```mermaid
+graph LR
+    A[User creates Work] --> B[Supervisor.add_work_item]
+    B --> C[WorkQueue]
+    C --> D[WorkDistributionManager]
+    D --> E[Idle Worker Ractor]
+    E --> F[Worker.process]
+    F --> G[WorkResult]
+    G --> H[ResultAggregator]
+    H --> I[User retrieves results]
+```
+
+### Error Handling Flow
+
+```mermaid
+graph LR
+    A[Worker.process raises error] --> B[WorkResult with error]
+    B --> C[ErrorReporter]
+    C --> D[ErrorStatistics]
+    C --> E[ErrorCallbacks]
+    E --> F[User error handler]
+    D --> G[ErrorReportGenerator]
+    G --> H[Formatted error output]
+```
+
+## Key Design Principles
+
+1. **Function-Driven**: Work is defined as input → processing → output
+2. **Message Passing**: Ractors communicate via messages, no shared state
+3. **Immutability**: Work objects are immutable, ensuring thread safety
+4. **Isolation**: Each Worker runs in its own Ractor with isolated memory
+5. **Scalability**: Automatically distribute work across available workers
+6. **Fault Tolerance**: Errors are captured without crashing other workers
+7. **Version Compatibility**: Separate implementations for Ruby 3.x and 4.0+