cmdx 1.9.1 → 1.10.1

data/lib/cmdx/configuration.rb

@@ -9,6 +9,9 @@ module CMDx
     # @rbs DEFAULT_BREAKPOINTS: Array[String]
     DEFAULT_BREAKPOINTS = %w[failed].freeze
 
+    # @rbs DEFAULT_ROLLPOINTS: Array[String]
+    DEFAULT_ROLLPOINTS = %w[failed].freeze
+
     # Returns the middleware registry for task execution.
     #
     # @return [MiddlewareRegistry] The middleware registry
@@ -110,6 +113,16 @@ module CMDx
     # @rbs @exception_handler: (Proc | nil)
     attr_accessor :exception_handler
 
+    # Returns the statuses that trigger a task execution rollback.
+    #
+    # @return [Array<String>] Array of status names that trigger rollback
+    #
+    # @example
+    #   config.rollback_on = ["failed", "skipped"]
+    #
+    # @rbs @rollback_on: Array[String]
+    attr_accessor :rollback_on
+
     # Initializes a new Configuration instance with default values.
     #
     # Creates new registry instances for middlewares, callbacks, coercions, and
@@ -131,6 +144,7 @@ module CMDx
 
       @task_breakpoints = DEFAULT_BREAKPOINTS
       @workflow_breakpoints = DEFAULT_BREAKPOINTS
+      @rollback_on = DEFAULT_ROLLPOINTS
 
       @backtrace = false
       @backtrace_cleaner = nil
@@ -162,6 +176,7 @@ module CMDx
         validators: @validators,
         task_breakpoints: @task_breakpoints,
         workflow_breakpoints: @workflow_breakpoints,
+        rollback_on: @rollback_on,
         backtrace: @backtrace,
         backtrace_cleaner: @backtrace_cleaner,
         exception_handler: @exception_handler,

data/lib/cmdx/executor.rb

@@ -118,15 +118,12 @@ module CMDx
     #
     # @return [Boolean] Whether execution should halt
     #
-    # @example
-    #   halt_execution?(fault_exception)
-    #
     # @rbs (Exception exception) -> bool
     def halt_execution?(exception)
-      breakpoints = task.class.settings[:breakpoints] || task.class.settings[:task_breakpoints]
-      breakpoints = Array(breakpoints).map(&:to_s).uniq
+      statuses = task.class.settings[:breakpoints] || task.class.settings[:task_breakpoints]
+      statuses = Array(statuses).map(&:to_s).uniq
 
-      breakpoints.include?(exception.result.status)
+      statuses.include?(exception.result.status)
     end
 
     # Determines if execution should be retried based on retry configuration.
@@ -135,9 +132,6 @@ module CMDx
     #
     # @return [Boolean] Whether execution should be retried
     #
-    # @example
-    #   retry_execution?(standard_error)
-    #
     # @rbs (Exception exception) -> bool
     def retry_execution?(exception)
       available_retries = (task.class.settings[:retries] || 0).to_i
@@ -157,7 +151,18 @@ module CMDx
         task.to_h.merge!(reason:, remaining_retries:)
       end
 
-      jitter = task.class.settings[:retry_jitter].to_f * current_retries
+      jitter = task.class.settings[:retry_jitter]
+      jitter =
+        if jitter.is_a?(Symbol)
+          task.send(jitter, current_retries)
+        elsif jitter.is_a?(Proc)
+          task.instance_exec(current_retries, &jitter)
+        elsif jitter.respond_to?(:call)
+          jitter.call(task, current_retries)
+        else
+          jitter.to_f * current_retries
+        end
+
       sleep(jitter) if jitter.positive?
 
       true
@@ -169,9 +174,6 @@ module CMDx
     #
     # @raise [Exception] The provided exception
     #
-    # @example
-    #   raise_exception(standard_error)
-    #
     # @rbs (Exception exception) -> void
     def raise_exception(exception)
       Chain.clear
@@ -195,13 +197,6 @@ module CMDx
 
     private
 
-    # Lazy loaded repeator instance to handle retries.
-    #
-    # @rbs () -> untyped
-    def repeator
-      @repeator ||= Repeator.new(task)
-    end
-
     # Performs pre-execution tasks including validation and attribute verification.
     #
     # @rbs () -> void
@@ -244,7 +239,7 @@ module CMDx
       invoke_callbacks(:on_bad) if task.result.bad?
     end
 
-    # Finalizes execution by freezing the task and logging results.
+    # Finalizes execution by freezing the task, logging results, and rolling back work.
     #
     # @rbs () -> Result
     def finalize_execution!
@@ -253,6 +248,8 @@ module CMDx
 
       freeze_execution!
       clear_chain!
+
+      rollback_execution!
     end
 
     # Logs the execution result at the configured log level.
@@ -309,5 +306,18 @@ module CMDx
       Chain.clear
     end
 
+    # Rolls back the work of a task.
+    #
+    # @rbs () -> void
+    def rollback_execution!
+      return unless task.respond_to?(:rollback)
+
+      statuses = task.class.settings[:rollback_on]
+      statuses = Array(statuses).map(&:to_s).uniq
+      return unless statuses.include?(task.result.status)
+
+      task.rollback
+    end
+
   end
 end

data/lib/cmdx/version.rb

@@ -5,6 +5,6 @@ module CMDx
   # @return [String] the version of the CMDx gem
   #
   # @rbs return: String
-  VERSION = "1.9.1"
+  VERSION = "1.10.1"
 
 end

data/mkdocs.yml

@@ -1,9 +1,9 @@
 # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
 
 site_name: CMDx
-site_url: https://drexed.github.io/cmdx/
-site_description: Build business logic that's powerful, predictable, and chaos-free.
+site_description: Build business logic that's powerful, predictable, and maintainable.
 site_author: drexed
+site_url: https://drexed.github.io/cmdx/
 repo_name: drexed/cmdx
 repo_url: https://github.com/drexed/cmdx
 edit_uri: edit/main/docs/
@@ -43,25 +43,27 @@ theme:
         icon: material/brightness-4
         name: Switch to system preference
   features:
+    - content.code.annotate
+    - content.code.copy
+    - content.tabs.link
+    - content.tooltips
     - navigation.footer
     - navigation.instant
     - navigation.instant.prefetch
     - navigation.instant.progress
-    - navigation.tracking
-    - navigation.sections
     - navigation.expand
     - navigation.path
+    - navigation.sections
     - navigation.top
+    - navigation.tracking
+    - search.highlight
     - search.share
     - search.suggest
-    - search.highlight
-    - content.code.copy
-    - content.code.annotate
-    - content.tabs.link
-    - content.tooltips
 
 markdown_extensions:
   - admonition
+  - attr_list
+  - md_in_html
   - pymdownx.details
   - pymdownx.superfences
   - pymdownx.highlight:
@@ -73,17 +75,56 @@ markdown_extensions:
   - pymdownx.tabbed:
       alternate_style: true
   - tables
-  - attr_list
-  - md_in_html
   - toc:
       permalink: true
 
 plugins:
   - search
+  - llmstxt:
+      markdown_description: >-
+        CMDx is a Ruby framework for building maintainable, observable business logic through composable command/service objects.
+        It brings structure, consistency, and powerful developer tools to your business processes.
+      full_output: llms-full.txt
+      sections:
+        "Getting Started":
+          - index.md: CMDx framework overview, installation, quick examples, and core concepts
+          - getting_started.md: Task setup and framework fundamentals (CERO pattern)
+          - configuration.md: Comprehensive guide to CMDx configuration
+        Basics:
+          - basics/setup.md: Task structure, inheritance, and basic setup requirements
+          - basics/execution.md: Task execution methods (execute vs execute!), error handling, and control flow
+          - basics/context.md: Context object for data sharing, input/output management, and attribute access
+          - basics/chain.md: Execution chain tracking for related tasks within threads
+        Interruptions:
+          - interruptions/halt.md: Intentional task interruption using skip! and fail! methods
+          - interruptions/faults.md: Fault exceptions (SkipFault, FailFault) raised by execute! with rich context
+          - interruptions/exceptions.md: Exception handling differences between execute and execute! methods
+        Outcomes:
+          - outcomes/result.md: Result objects exposing execution state, status, context, and metadata
+          - outcomes/states.md: Execution lifecycle states (initialized, executing, complete, interrupted)
+          - outcomes/statuses.md: Business outcome statuses (success, skipped, failed) and transitions
+        Attributes:
+          - attributes/definitions.md: Attribute declarations (required/optional), validation, and type coercion
+          - attributes/naming.md: Customizing accessor method names with prefixes and suffixes
+          - attributes/coercions.md: Automatic type conversion for inputs (string to integer, date parsing, etc.)
+          - attributes/validations.md: Input validation rules (presence, length, format, numeric, inclusion, exclusion)
+          - attributes/defaults.md: Default values for optional attributes (static, dynamic, callable)
+          - attributes/transformations.md: Value transformation after coercion but before validation
+        Features:
+          - callbacks.md: Execution lifecycle callbacks (before_execution, on_success, on_failure, etc.)
+          - middlewares.md: Cross-cutting concerns wrapping task execution (authentication, caching, timeouts)
+          - logging.md: Structured logging with multiple formatters (JSON, KeyValue, Logstash, Line, Raw)
+          - internationalization.md: Multi-language support for error messages and validations (90+ locales)
+          - retries.md: Automatic retry functionality for transient failures with jitter and selective retries
+          - deprecation.md: Managing deprecated tasks with logging, warnings, or execution prevention
+          - workflows.md: Composing multiple tasks into sequential pipelines with conditional execution
+        More:
+          - tips_and_tricks.md: Best practices, patterns, and techniques for maintainable CMDx applications
 
 nav:
   - Home: index.md
   - Getting Started: getting_started.md
+  - Configuration: configuration.md
   - Basics:
     - Setup: basics/setup.md
     - Execution: basics/execution.md
@@ -104,13 +145,20 @@ nav:
     - Validations: attributes/validations.md
     - Defaults: attributes/defaults.md
     - Transformations: attributes/transformations.md
-  - Callbacks: callbacks.md
-  - Middlewares: middlewares.md
-  - Logging: logging.md
-  - Internationalization: internationalization.md
-  - Deprecation: deprecation.md
-  - Workflows: workflows.md
-  - Tips and Tricks: tips_and_tricks.md
+  - Features:
+    - Callbacks: callbacks.md
+    - Middlewares: middlewares.md
+    - Logging: logging.md
+    - Internationalization: internationalization.md
+    - Retries: retries.md
+    - Deprecation: deprecation.md
+    - Workflows: workflows.md
+  - More:
+    - Tips and Tricks: tips_and_tricks.md
+  - References:
+    - API YARDocs: https://drexed.github.io/cmdx/api/index.html
+    - llms.txt: https://drexed.github.io/cmdx/llms.txt
+    - llms-full.txt: https://drexed.github.io/cmdx/llms-full.txt
 
 extra:
   generator: false

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 1.9.1
+  version: 1.10.1
 platform: ruby
 authors:
 - Juan Gomez
@@ -191,6 +191,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: CMDx is a framework for building maintainable business processes.
 email:
 - drexed@users.noreply.github.com
@@ -208,10 +222,10 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
-- LLM.md
 - README.md
 - Rakefile
 - docs/.DS_Store
@@ -228,6 +242,7 @@ files:
 - docs/basics/execution.md
 - docs/basics/setup.md
 - docs/callbacks.md
+- docs/configuration.md
 - docs/deprecation.md
 - docs/getting_started.md
 - docs/index.md
@@ -240,11 +255,14 @@ files:
 - docs/outcomes/result.md
 - docs/outcomes/states.md
 - docs/outcomes/statuses.md
+- docs/retries.md
 - docs/stylesheets/extra.css
 - docs/tips_and_tricks.md
 - docs/workflows.md
 - examples/active_record_query_tagging.md
 - examples/paper_trail_whatdunnit.md
+- examples/sidekiq_async_execution.md
+- examples/stoplight_circuit_breaker.md
 - lib/cmdx.rb
 - lib/cmdx/.DS_Store
 - lib/cmdx/attribute.rb