fractor 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e02a928040e2df09a69eda8ffa10367d5e698868a44643912a747a99b27111fa
-  data.tar.gz: e02247543fd89c0856ac6ce8e18c538ef32c5e1f82bce856b666b7db51b49d26
+  metadata.gz: 22b2448a14f44c78c6b4970d9529aa9e88257ff63423be18e57dd87290f5247b
+  data.tar.gz: 27a514ab149f2115e5e53fe0c4a3199d09adeb355789ce21ff85ab93b8cb1891
 SHA512:
-  metadata.gz: 8b664bc5b52225acc157a3f37a1ae97a6a621c08398d2de6b7759a03aceb1bb356d7242da173d6f16f331e0433ab29b60b067250b57422ab5d3c9bed2a284cc5
-  data.tar.gz: 26fa65f4a034857688d3fd45f0702eed50a9c07262107e4a43b1da0d77656988137a5242c661e03ef571aa35cfb1ed11a9e48b7fa17f626e74eb5ab71111a3d8
+  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 06:39:26 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,47 +11,19 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'fractor.gemspec'
 
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'spec/fractor/main_loop_handler3_spec.rb'
-    - 'spec/fractor/main_loop_handler4_spec.rb'
-    - 'spec/fractor/supervisor_shutdown_spec.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleAlignWith.
-# SupportedStylesAlignWith: either, start_of_block, start_of_line
-Layout/BlockAlignment:
-  Exclude:
-    - 'spec/fractor/main_loop_handler3_spec.rb'
-    - 'spec/fractor/main_loop_handler4_spec.rb'
-
-# Offense count: 455
+# 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: 4
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'spec/fractor/main_loop_handler3_spec.rb'
-    - 'spec/fractor/main_loop_handler4_spec.rb'
-    - 'spec/fractor/supervisor_shutdown_spec.rb'
-
 # Offense count: 1
 Lint/BinaryOperatorWithIdenticalOperands:
   Exclude:
     - 'spec/fractor/priority_work_spec.rb'
 
-# Offense count: 14
+# Offense count: 20
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
 Lint/ConstantDefinitionInBlock:
@@ -60,7 +32,10 @@ Lint/ConstantDefinitionInBlock:
     - 'spec/examples/performance_monitoring_spec.rb'
     - 'spec/examples/priority_work_example_spec.rb'
     - 'spec/fractor/integration_spec.rb'
+    - 'spec/fractor/persistent_work_queue_spec.rb'
+    - 'spec/fractor/result_cache_spec.rb'
     - 'spec/fractor/work_spec.rb'
+    - 'spec/fractor/work_timeout_spec.rb'
     - 'spec/fractor/worker_timeout_spec.rb'
     - 'spec/fractor/workflow/execution_strategy_spec.rb'
 
@@ -77,10 +52,11 @@ Lint/HashCompareByIdentity:
     - 'lib/fractor/work_distribution_manager.rb'
     - 'spec/fractor/work_distribution_manager_spec.rb'
 
-# Offense count: 1
+# Offense count: 4
 # Configuration parameters: AllowedParentClasses.
 Lint/MissingSuper:
   Exclude:
+    - 'lib/fractor/queue_persister.rb'
     - 'spec/fractor/wrapped_ractor3_spec.rb'
 
 # Offense count: 5
@@ -91,7 +67,7 @@ Lint/RescueException:
     - 'lib/fractor/wrapped_ractor3.rb'
     - 'lib/fractor/wrapped_ractor4.rb'
 
-# Offense count: 4
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
 # NotImplementedExceptions: NotImplementedError
@@ -99,9 +75,14 @@ Lint/UnusedMethodArgument:
   Exclude:
     - 'lib/fractor/workflow.rb'
     - 'lib/fractor/wrapped_ractor3.rb'
-    - 'spec/fractor/wrapped_ractor3_spec.rb'
 
-# Offense count: 88
+# 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
@@ -110,24 +91,24 @@ Metrics/AbcSize:
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 105
+  Max: 110
 
-# Offense count: 61
+# Offense count: 64
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 142
+# Offense count: 155
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 117
+  Max: 122
 
-# Offense count: 9
+# Offense count: 10
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 9
 
-# Offense count: 46
+# Offense count: 50
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -151,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'
 
@@ -185,21 +163,12 @@ RSpec/ContextWording:
     - 'spec/fractor/supervisor_spec.rb'
     - 'spec/fractor_spec.rb'
 
-# Offense count: 27
+# Offense count: 29
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
 
-# Offense count: 3
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: SkipBlocks, EnforcedStyle, OnlyStaticConstants.
-# SupportedStyles: described_class, explicit
-RSpec/DescribedClass:
-  Exclude:
-    - 'spec/fractor/worker_spec.rb'
-    - 'spec/fractor/worker_timeout_spec.rb'
-
-# Offense count: 510
+# Offense count: 549
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 47
@@ -246,18 +215,21 @@ RSpec/InstanceVariable:
     - 'spec/examples/workflow/dead_letter_queue_workflow_spec.rb'
     - 'spec/fractor/integration_spec.rb'
 
-# Offense count: 16
+# Offense count: 22
 RSpec/LeakyConstantDeclaration:
   Exclude:
     - 'spec/examples/error_reporting_spec.rb'
     - 'spec/examples/performance_monitoring_spec.rb'
     - 'spec/examples/priority_work_example_spec.rb'
     - 'spec/fractor/integration_spec.rb'
+    - 'spec/fractor/persistent_work_queue_spec.rb'
+    - 'spec/fractor/result_cache_spec.rb'
     - 'spec/fractor/work_spec.rb'
+    - 'spec/fractor/work_timeout_spec.rb'
     - '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:
@@ -265,21 +237,23 @@ RSpec/MessageSpies:
     - 'spec/fractor/main_loop_handler_spec.rb'
     - 'spec/fractor/shutdown_handler_spec.rb'
 
-# Offense count: 6
+# Offense count: 8
 RSpec/MultipleDescribes:
   Exclude:
     - 'spec/examples/workflow/simplified_workflow_spec.rb'
+    - 'spec/fractor/persistent_work_queue_spec.rb'
+    - 'spec/fractor/work_timeout_spec.rb'
     - 'spec/fractor/worker_timeout_spec.rb'
     - 'spec/fractor/workflow/dead_letter_queue_spec.rb'
     - 'spec/fractor/workflow/execution_strategy_spec.rb'
     - 'spec/fractor/workflow/retry_config_spec.rb'
     - 'spec/fractor/workflow/retry_strategy_spec.rb'
 
-# Offense count: 605
+# Offense count: 636
 RSpec/MultipleExpectations:
   Max: 12
 
-# Offense count: 50
+# Offense count: 52
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 9
@@ -321,9 +295,30 @@ Security/Eval:
   Exclude:
     - 'lib/fractor/cli.rb'
 
+# Offense count: 1
+Security/MarshalLoad:
+  Exclude:
+    - 'lib/fractor/queue_persister.rb'
+
 # Offense count: 1
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?
 Style/OptionalBooleanParameter:
   Exclude:
     - 'lib/fractor/workflow/job.rb'
+
+# 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:
+    - 'lib/fractor/supervisor.rb'

data/README.adoc

@@ -82,6 +82,143 @@ puts "Results: #{supervisor.results.results.map(&:result)}"
 # => Results: [2, 4, 6]
 ----
 
+=== Timeout Configuration
+
+Fractor supports flexible timeout configuration at three levels:
+
+[cols="1,2,4"]
+|===
+|Level |Syntax |Description
+
+|Global
+|`Fractor.configure`
+|Sets default timeout for all workers
+
+|Worker
+|`Worker.timeout` class method
+|Sets timeout for all work processed by a worker
+
+|Work item
+|`Work.new(input, timeout: N)`
+|Overrides worker timeout for specific work item
+|===
+
+[source,ruby]
+----
+# 1. Global default (optional)
+Fractor.configure do |config|
+  config.default_worker_timeout = 60  # 60 seconds
+end
+
+# 2. Worker-level timeout
+class FastWorker < Fractor::Worker
+  timeout 10  # 10 second timeout for this worker
+
+  def process(work)
+    Fractor::WorkResult.new(result: work.input * 2, work: work)
+  end
+end
+
+# 3. Per-work-item timeout (overrides worker timeout)
+class MyWork < Fractor::Work
+  def initialize(value, timeout: nil)
+    super({ value: value }, timeout: timeout)
+  end
+end
+
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [{ worker_class: FastWorker }]
+)
+
+# Mix work items with different timeouts
+fast_work = MyWork.new(1, timeout: 5)      # 5 seconds
+normal_work = MyWork.new(2)                 # uses worker's 10s timeout
+slow_work = MyWork.new(3, timeout: 30)     # 30 seconds
+
+supervisor.add_work_items([fast_work, normal_work, slow_work])
+supervisor.run
+----
+
+When a timeout occurs, the work item is marked as failed with `error_category: :timeout` and can be retried if using the workflow system.
+
+=== Queue Persistence
+
+For critical applications, work queues can be persisted to disk for crash recovery:
+
+[source,ruby]
+----
+# Create a persistent queue with automatic saving
+queue = Fractor::PersistentWorkQueue.new("data/queue.json")
+
+# Add work items - automatically saved
+queue << MyWork.new(data1)
+queue << MyWork.new(data2)
+
+# Use with ContinuousServer for crash recovery
+server = Fractor::ContinuousServer.new(
+  worker_pools: [{ worker_class: MyWorker }],
+  work_queue: queue
+)
+
+# Load any previous work items on startup
+queue.load
+
+server.run
+----
+
+Supported persistence formats:
+* **JSON** (default) - Human-readable, widely compatible
+* **YAML** - More readable than JSON
+* **Marshal** - Binary format, faster but Ruby-specific
+
+=== Result Caching
+
+For expensive, deterministic operations, Fractor provides a result cache to avoid redundant processing of identical work items:
+
+[source,ruby]
+----
+# Create a cache with TTL (time-to-live)
+cache = Fractor::ResultCache.new(ttl: 300)  # 5 minutes
+
+# Or with size limit
+cache = Fractor::ResultCache.new(max_size: 1000)
+
+# Or with memory limit
+cache = Fractor::ResultCache.new(max_memory: 1024 * 1024)  # 1MB
+
+# Use the cache
+result = cache.get(work) do
+  # This block only runs if work is not cached
+  expensive_operation(work)
+end
+
+# Check if work is cached
+if cache.has?(work)
+  puts "Result is cached!"
+end
+
+# Manual cache operations
+cache.set(work, result)           # Store a result
+cache.invalidate(work)            # Remove a cached result
+cache.clear                       # Remove all cached results
+
+# Get cache statistics
+stats = cache.stats
+puts "Cache hit rate: #{stats[:hit_rate]}%"
+----
+
+The cache generates consistent keys based on:
+* Work class name
+* Work input data
+* Work timeout (if set)
+
+This means identical work items with the same input and timeout will share cached results.
+
+Cache eviction policies:
+* **TTL** - Entries expire after a configured time
+* **LRU** - Least-recently-used entries are evicted when max_size is reached
+* **Memory-based** - Entries are evicted when max_memory is reached
+
 == Key features
 
 * *Function-driven*: Define processing logic by subclassing `Fractor::Worker`