better_service 1.0.0

data/lib/better_service/subscribers/stats_subscriber.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Subscribers
+    # StatsSubscriber - Built-in subscriber that collects service statistics
+    #
+    # This subscriber tracks execution metrics for all services:
+    # - Total executions
+    # - Success/failure counts
+    # - Average duration
+    # - Cache hit rate
+    #
+    # @example Enable in initializer
+    #   BetterService.configure do |config|
+    #     config.stats_subscriber_enabled = true
+    #   end
+    #
+    # @example Access statistics
+    #   BetterService::Subscribers::StatsSubscriber.stats
+    #   # => {
+    #   #   "ProductsIndexService" => {
+    #   #     executions: 150,
+    #   #     successes: 148,
+    #   #     failures: 2,
+    #   #     total_duration: 4500.0,
+    #   #     avg_duration: 30.0,
+    #   #     cache_hits: 120,
+    #   #     cache_misses: 30
+    #   #   }
+    #   # }
+    class StatsSubscriber
+      class << self
+        # Storage for service statistics
+        #
+        # @return [Hash] Statistics hash
+        attr_reader :stats
+
+        # Storage for ActiveSupport::Notifications subscriptions
+        #
+        # @return [Array<ActiveSupport::Notifications::Fanout::Subscriber>]
+        attr_reader :subscriptions
+
+        # Attach the subscriber to ActiveSupport::Notifications
+        #
+        # This method is called automatically when subscriber is enabled.
+        #
+        # @return [void]
+        def attach
+          reset!
+          @subscriptions ||= []
+          subscribe_to_service_events
+          subscribe_to_cache_events
+        end
+
+        # Reset all statistics
+        #
+        # Useful for testing or periodic reset in production.
+        #
+        # @return [void]
+        def reset!
+          # Unsubscribe from all existing subscriptions
+          if @subscriptions
+            @subscriptions.each do |subscription|
+              ActiveSupport::Notifications.unsubscribe(subscription)
+            end
+          end
+          @subscriptions = []
+          @stats = {}
+        end
+
+        # Get statistics for a specific service
+        #
+        # @param service_name [String] Name of service class
+        # @return [Hash, nil] Service statistics or nil if not found
+        def stats_for(service_name)
+          @stats[service_name]
+        end
+
+        # Get statistics summary across all services
+        #
+        # @return [Hash] Aggregated statistics
+        def summary
+          total_executions = @stats.values.sum { |s| s[:executions] }
+          total_successes = @stats.values.sum { |s| s[:successes] }
+          total_failures = @stats.values.sum { |s| s[:failures] }
+          total_duration = @stats.values.sum { |s| s[:total_duration] }
+          total_cache_hits = @stats.values.sum { |s| s[:cache_hits] }
+          total_cache_misses = @stats.values.sum { |s| s[:cache_misses] }
+
+          {
+            total_services: @stats.keys.size,
+            total_executions: total_executions,
+            total_successes: total_successes,
+            total_failures: total_failures,
+            success_rate: total_executions > 0 ? (total_successes.to_f / total_executions * 100).round(2) : 0,
+            avg_duration: total_executions > 0 ? (total_duration / total_executions).round(2) : 0,
+            cache_hit_rate: (total_cache_hits + total_cache_misses) > 0 ? (total_cache_hits.to_f / (total_cache_hits + total_cache_misses) * 100).round(2) : 0
+          }
+        end
+
+        private
+
+        # Subscribe to service lifecycle events
+        #
+        # @return [void]
+        def subscribe_to_service_events
+          @subscriptions << ActiveSupport::Notifications.subscribe("service.completed") do |name, start, finish, id, payload|
+            record_completion(payload)
+          end
+
+          @subscriptions << ActiveSupport::Notifications.subscribe("service.failed") do |name, start, finish, id, payload|
+            record_failure(payload)
+          end
+        end
+
+        # Subscribe to cache events
+        #
+        # @return [void]
+        def subscribe_to_cache_events
+          @subscriptions << ActiveSupport::Notifications.subscribe("cache.hit") do |name, start, finish, id, payload|
+            record_cache_hit(payload)
+          end
+
+          @subscriptions << ActiveSupport::Notifications.subscribe("cache.miss") do |name, start, finish, id, payload|
+            record_cache_miss(payload)
+          end
+        end
+
+        # Record service completion
+        #
+        # @param payload [Hash] Event payload
+        # @return [void]
+        def record_completion(payload)
+          service_name = payload[:service_name]
+          ensure_service_stats(service_name)
+
+          @stats[service_name][:executions] += 1
+          @stats[service_name][:successes] += 1
+          @stats[service_name][:total_duration] += payload[:duration]
+          @stats[service_name][:avg_duration] = (@stats[service_name][:total_duration] / @stats[service_name][:executions]).round(2)
+
+          # Record cache hit if present
+          if payload[:cache_hit]
+            @stats[service_name][:cache_hits] += 1
+          end
+        end
+
+        # Record service failure
+        #
+        # @param payload [Hash] Event payload
+        # @return [void]
+        def record_failure(payload)
+          service_name = payload[:service_name]
+          ensure_service_stats(service_name)
+
+          @stats[service_name][:executions] += 1
+          @stats[service_name][:failures] += 1
+          @stats[service_name][:total_duration] += payload[:duration]
+          @stats[service_name][:avg_duration] = (@stats[service_name][:total_duration] / @stats[service_name][:executions]).round(2)
+
+          # Track error types
+          error_class = payload[:error_class]
+          @stats[service_name][:errors][error_class] ||= 0
+          @stats[service_name][:errors][error_class] += 1
+        end
+
+        # Record cache hit
+        #
+        # @param payload [Hash] Event payload
+        # @return [void]
+        def record_cache_hit(payload)
+          service_name = payload[:service_name]
+          ensure_service_stats(service_name)
+
+          @stats[service_name][:cache_hits] += 1
+        end
+
+        # Record cache miss
+        #
+        # @param payload [Hash] Event payload
+        # @return [void]
+        def record_cache_miss(payload)
+          service_name = payload[:service_name]
+          ensure_service_stats(service_name)
+
+          @stats[service_name][:cache_misses] += 1
+        end
+
+        # Ensure service has stats entry
+        #
+        # @param service_name [String] Name of service class
+        # @return [void]
+        def ensure_service_stats(service_name)
+          @stats[service_name] ||= {
+            executions: 0,
+            successes: 0,
+            failures: 0,
+            total_duration: 0.0,
+            avg_duration: 0.0,
+            cache_hits: 0,
+            cache_misses: 0,
+            errors: {}
+          }
+        end
+      end
+    end
+  end
+end

data/lib/better_service/version.rb

@@ -0,0 +1,3 @@
+module BetterService
+  VERSION = "1.0.0"
+end

data/lib/better_service/workflows/base.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module BetterService
+  # Workflow - Base class for composing multiple services into a pipeline
+  #
+  # Workflows allow you to chain multiple services together with explicit
+  # data mapping, conditional execution, rollback support, and lifecycle hooks.
+  #
+  # Example:
+  #   class OrderPurchaseWorkflow < BetterService::Workflow
+  #     with_transaction true
+  #
+  #     before_workflow :validate_cart
+  #     after_workflow :clear_cart
+  #
+  #     step :create_order,
+  #          with: Order::CreateService,
+  #          input: ->(ctx) { { items: ctx.cart_items, total: ctx.total } }
+  #
+  #     step :charge_payment,
+  #          with: Payment::ChargeService,
+  #          input: ->(ctx) { { amount: ctx.order.total } },
+  #          rollback: ->(ctx) { Payment::RefundService.new(ctx.user, params: { charge_id: ctx.charge.id }).call }
+  #
+  #     step :send_email,
+  #          with: Email::ConfirmationService,
+  #          input: ->(ctx) { { order_id: ctx.order.id } },
+  #          optional: true,
+  #          if: ->(ctx) { ctx.user.notifications_enabled? }
+  #
+  #     private
+  #
+  #     def validate_cart(context)
+  #       context.fail!("Cart is empty") if context.cart_items.empty?
+  #     end
+  #
+  #     def clear_cart(context)
+  #       context.user.clear_cart! if context.success?
+  #     end
+  #   end
+  #
+  #   # Usage:
+  #   result = OrderPurchaseWorkflow.new(current_user, params: { cart_items: [...] }).call
+  #   if result[:success]
+  #     order = result[:context].order
+  #   else
+  #     errors = result[:errors]
+  #   end
+  module Workflows
+    class Base
+      include Concerns::Workflowable::Callbacks
+      include DSL
+      include TransactionSupport
+      include Execution
+      include RollbackSupport
+      include ResultBuilder
+
+      attr_reader :user, :params, :context
+
+    # Initialize a new workflow
+    #
+    # @param user [Object] The current user executing the workflow
+    # @param params [Hash] Parameters for the workflow
+    def initialize(user, params: {})
+      @user = user
+      @params = params
+      @context = Workflowable::Context.new(user, **params)
+      @executed_steps = []
+      @start_time = nil
+      @end_time = nil
+    end
+
+    # Main entry point - executes the workflow
+    #
+    # Runs before_workflow callbacks, executes the workflow (with or without
+    # transaction), and runs after_workflow callbacks. Tracks timing and
+    # ensures callbacks run even if execution fails.
+    #
+    # @return [Hash] Result hash with success status, context, and metadata
+    def call
+      @start_time = Time.current
+      @context.called!
+
+      # Run before_workflow callbacks
+      run_before_workflow_callbacks(@context)
+
+      # If callbacks failed the context, return early
+      if @context.failure?
+        @end_time = Time.current
+        return build_failure_result
+      end
+
+      # Execute workflow with or without transaction
+      if self.class._use_transaction
+        execute_with_transaction
+      else
+        execute_workflow
+      end
+    ensure
+      @end_time ||= Time.current
+      # Always run after_workflow callbacks
+      run_after_workflow_callbacks(@context) if @context.called?
+    end
+    end
+  end
+end

data/lib/better_service/workflows/dsl.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Workflows
+    # DSL - Provides class-level DSL methods for defining workflow steps
+    #
+    # This module adds the `step` and `with_transaction` class methods that
+    # allow declarative workflow definition using a clean DSL syntax.
+    module DSL
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_steps, default: []
+        class_attribute :_use_transaction, default: false
+      end
+
+      class_methods do
+        # DSL method to define a step in the workflow
+        #
+        # @param name [Symbol] Name of the step
+        # @param with [Class] Service class to execute
+        # @param input [Proc] Lambda to map context data to service params
+        # @param optional [Boolean] Whether step failure should stop the workflow
+        # @param if [Proc] Condition to determine if step should execute
+        # @param rollback [Proc] Block to execute if rollback is needed
+        #
+        # @example Define a workflow step
+        #   step :create_order,
+        #        with: Order::CreateService,
+        #        input: ->(ctx) { { items: ctx.cart_items } },
+        #        rollback: ->(ctx) { ctx.order.destroy! }
+        def step(name, with:, input: nil, optional: false, if: nil, rollback: nil)
+          step = Workflowable::Step.new(
+            name: name,
+            service_class: with,
+            input: input,
+            optional: optional,
+            condition: binding.local_variable_get(:if), # Use binding to get the 'if' keyword param
+            rollback: rollback
+          )
+
+          self._steps += [ step ]
+        end
+
+        # Enable or disable database transactions for the entire workflow
+        #
+        # @param enabled [Boolean] Whether to use transactions
+        #
+        # @example Enable transactions
+        #   class MyWorkflow < BetterService::Workflow
+        #     with_transaction true
+        #   end
+        def with_transaction(enabled)
+          self._use_transaction = enabled
+        end
+      end
+    end
+  end
+end

data/lib/better_service/workflows/execution.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Workflows
+    # Execution - Core workflow execution engine
+    #
+    # This module handles the sequential execution of workflow steps,
+    # error handling, and step tracking.
+    module Execution
+      private
+
+      # Execute workflow steps sequentially
+      #
+      # Iterates through all defined steps, executing each with around_step callbacks.
+      # Tracks executed and skipped steps. Handles step failures by rolling back
+      # previously executed steps and raising appropriate errors.
+      #
+      # @return [Hash] Success or failure result
+      # @raise [Errors::Workflowable::Runtime::StepExecutionError] If a step fails
+      # @raise [Errors::Workflowable::Runtime::WorkflowExecutionError] If workflow execution fails
+      def execute_workflow
+        steps_executed = []
+        steps_skipped = []
+
+        self.class._steps.each do |step|
+          # Execute step with around_step callbacks
+          result = nil
+          run_around_step_callbacks(step, @context) do
+            result = step.call(@context, @user, @params)
+          end
+
+          # Track skipped steps
+          if result[:skipped]
+            steps_skipped << step.name
+            next
+          end
+
+          # If step failed and it's not optional, stop and rollback
+          if result[:success] == false && !result[:optional_failure]
+            # With Pure Exception Pattern, all failures raise exceptions
+            rollback_steps
+
+            raise Errors::Workflowable::Runtime::StepExecutionError.new(
+              "Step #{step.name} failed: #{result[:error] || result[:message]}",
+              code: ErrorCodes::STEP_FAILED,
+              context: {
+                workflow: self.class.name,
+                step: step.name,
+                steps_executed: steps_executed,
+                errors: result[:errors] || {}
+              }
+            )
+          end
+
+          # Track successful execution
+          @executed_steps << step
+          steps_executed << step.name
+        end
+
+        # All steps succeeded
+        @end_time = Time.current
+        build_success_result(
+          steps_executed: steps_executed,
+          steps_skipped: steps_skipped
+        )
+      rescue Errors::Workflowable::Runtime::StepExecutionError
+        # Step error already raised, just re-raise
+        raise
+      rescue StandardError => e
+        # Unexpected error during workflow execution
+        rollback_steps
+
+        Rails.logger.error "Workflow error: #{e.message}" if defined?(Rails)
+        Rails.logger.error e.backtrace.join("\n") if defined?(Rails)
+
+        raise Errors::Workflowable::Runtime::WorkflowExecutionError.new(
+          "Workflow execution failed: #{e.message}",
+          code: ErrorCodes::WORKFLOW_FAILED,
+          original_error: e,
+          context: {
+            workflow: self.class.name,
+            steps_executed: steps_executed,
+            steps_skipped: steps_skipped
+          }
+        )
+      end
+    end
+  end
+end

data/lib/better_service/workflows/result_builder.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Workflows
+    # ResultBuilder - Handles construction of success and failure result hashes
+    #
+    # This module provides methods for building consistent result structures
+    # for workflow execution, including metadata tracking and duration measurement.
+    module ResultBuilder
+      private
+
+      # Build success result
+      #
+      # @param steps_executed [Array<Symbol>] Names of steps that were executed
+      # @param steps_skipped [Array<Symbol>] Names of steps that were skipped
+      # @return [Hash] Success result with context and metadata
+      def build_success_result(steps_executed: [], steps_skipped: [])
+        {
+          success: true,
+          message: "Workflow completed successfully",
+          context: @context,
+          metadata: {
+            workflow: self.class.name,
+            steps_executed: steps_executed,
+            steps_skipped: steps_skipped,
+            duration_ms: duration_ms
+          }
+        }
+      end
+
+      # Build failure result
+      #
+      # @param message [String, nil] Error message
+      # @param errors [Hash] Error details
+      # @param failed_step [Symbol, nil] Name of the step that failed
+      # @param steps_executed [Array<Symbol>] Names of steps that were executed before failure
+      # @param steps_skipped [Array<Symbol>] Names of steps that were skipped
+      # @return [Hash] Failure result with error details and metadata
+      def build_failure_result(message: nil, errors: {}, failed_step: nil, steps_executed: [], steps_skipped: [])
+        result = {
+          success: false,
+          error: message || @context.errors[:message] || "Workflow failed",
+          errors: errors.any? ? errors : @context.errors,
+          context: @context,
+          metadata: {
+            workflow: self.class.name,
+            failed_step: failed_step,
+            steps_executed: steps_executed,
+            steps_skipped: steps_skipped,
+            duration_ms: duration_ms
+          }
+        }
+
+        result[:metadata].delete(:failed_step) if failed_step.nil?
+        result
+      end
+
+      # Calculate duration in milliseconds
+      #
+      # @return [Float, nil] Duration in milliseconds or nil if not available
+      def duration_ms
+        return nil unless @start_time && @end_time
+        (((@end_time - @start_time) * 1000).round(2))
+      end
+    end
+  end
+end

data/lib/better_service/workflows/rollback_support.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Workflows
+    # RollbackSupport - Handles rollback of executed steps when workflow fails
+    #
+    # This module provides the rollback mechanism that executes step rollback
+    # blocks in reverse order when a workflow execution fails.
+    module RollbackSupport
+      private
+
+      # Rollback all executed steps in reverse order
+      #
+      # Iterates through executed steps in reverse and calls their rollback method.
+      # If any rollback fails, raises a RollbackError with context about which
+      # step failed and what steps were executed.
+      #
+      # @raise [Errors::Workflowable::Runtime::RollbackError] If any rollback fails
+      # @return [void]
+      def rollback_steps
+        @executed_steps.reverse_each do |step|
+          begin
+            step.rollback(@context)
+          rescue StandardError => e
+            # Rollback failure is serious - raise exception
+            Rails.logger.error "Rollback failed for step #{step.name}: #{e.message}" if defined?(Rails)
+            Rails.logger.error e.backtrace.join("\n") if defined?(Rails)
+
+            raise Errors::Workflowable::Runtime::RollbackError.new(
+              "Rollback failed for step #{step.name}: #{e.message}",
+              code: ErrorCodes::ROLLBACK_FAILED,
+              original_error: e,
+              context: {
+                workflow: self.class.name,
+                step: step.name,
+                executed_steps: @executed_steps.map(&:name)
+              }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_service/workflows/transaction_support.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Workflows
+    # TransactionSupport - Handles database transaction wrapping for workflows
+    #
+    # This module provides the ability to execute workflows within a database
+    # transaction, with automatic rollback on failure.
+    module TransactionSupport
+      private
+
+      # Execute workflow with transaction wrapper
+      #
+      # Wraps the workflow execution in an ActiveRecord transaction. If the
+      # workflow fails (returns success: false), triggers a rollback.
+      #
+      # @return [Hash] Result from execute_workflow
+      def execute_with_transaction
+        result = nil
+        ActiveRecord::Base.transaction do
+          result = execute_workflow
+          # If workflow failed, raise to trigger rollback
+          raise ActiveRecord::Rollback if result[:success] == false
+        end
+        result
+      rescue ActiveRecord::Rollback
+        # Rollback was triggered, result already contains failure
+        result
+      end
+    end
+  end
+end

data/lib/better_service.rb

@@ -0,0 +1,28 @@
+require "better_service/version"
+require "better_service/railtie"
+require "better_service/configuration"
+require "better_service/errors/better_service_error"
+require "better_service/cache_service"
+require "better_service/concerns/instrumentation"
+require "better_service/subscribers/log_subscriber"
+require "better_service/subscribers/stats_subscriber"
+require "better_service/services/base"
+require "better_service/services/index_service"
+require "better_service/services/show_service"
+require "better_service/services/create_service"
+require "better_service/services/update_service"
+require "better_service/services/destroy_service"
+require "better_service/services/action_service"
+require "better_service/concerns/workflowable/context"
+require "better_service/concerns/workflowable/step"
+require "better_service/concerns/workflowable/callbacks"
+require "better_service/workflows/result_builder"
+require "better_service/workflows/rollback_support"
+require "better_service/workflows/transaction_support"
+require "better_service/workflows/dsl"
+require "better_service/workflows/execution"
+require "better_service/workflows/base"
+
+module BetterService
+  # Your code goes here...
+end

data/lib/generators/serviceable/action_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Serviceable
+  module Generators
+    class ActionGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      argument :action_name, type: :string, desc: "The action name (e.g., accept, reject, publish)"
+
+      desc "Generate an Action service for custom state transitions"
+
+      def create_service_file
+        template "action_service.rb.tt", File.join("app/services", class_path, "#{file_name}/#{action_name}_service.rb")
+      end
+
+      def create_test_file
+        template "service_test.rb.tt", File.join("test/services", class_path, "#{file_name}/#{action_name}_service_test.rb")
+      end
+
+      private
+
+      def service_class_name
+        "#{class_name}::#{action_name.camelize}Service"
+      end
+    end
+  end
+end