better_service 1.0.0

data/Rakefile

@@ -0,0 +1,15 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"].exclude(
+    "test/dummy/**/*",
+    "test/generators/**/*"
+  )
+  t.verbose = false
+end
+
+task default: :test

data/lib/better_service/cache_service.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module BetterService
+  # CacheService - Provides cache invalidation and management for BetterService
+  #
+  # This service handles cache invalidation based on contexts defined in
+  # the Cacheable concern. It provides methods to invalidate cache keys
+  # for specific users, contexts, or globally.
+  #
+  # @example Invalidate cache for a specific context and user
+  #   BetterService::CacheService.invalidate_for_context(current_user, "products")
+  #
+  # @example Invalidate cache globally for a context
+  #   BetterService::CacheService.invalidate_global("sidebar")
+  #
+  # @example Invalidate all cache for a user
+  #   BetterService::CacheService.invalidate_for_user(current_user)
+  class CacheService
+    class << self
+      # Invalidate cache for a specific context and user
+      #
+      # Deletes all cache keys that match the pattern for the given user and context.
+      # This is useful when data changes that affects a specific user's cached results.
+      #
+      # @param user [Object] The user whose cache should be invalidated
+      # @param context [String] The context name (e.g., "products", "sidebar")
+      # @param async [Boolean] Whether to perform invalidation asynchronously
+      # @return [Integer] Number of keys deleted (if supported by cache store)
+      #
+      # @example
+      #   # After creating a product, invalidate products cache for user
+      #   BetterService::CacheService.invalidate_for_context(user, "products")
+      def invalidate_for_context(user, context, async: false)
+        return 0 unless user && context && !context.to_s.strip.empty?
+
+        pattern = build_user_context_pattern(user, context)
+
+        if async
+          invalidate_async(pattern)
+          0
+        else
+          result = delete_matched(pattern)
+          # Ensure we return Integer, not Array
+          result.is_a?(Array) ? result.size : (result || 0)
+        end
+      end
+
+      # Invalidate cache globally for a context
+      #
+      # Deletes all cache keys for the given context across all users.
+      # This is useful when data changes that affects everyone (e.g., global settings).
+      #
+      # @param context [String] The context name
+      # @param async [Boolean] Whether to perform invalidation asynchronously
+      # @return [Integer] Number of keys deleted (if supported by cache store)
+      #
+      # @example
+      #   # After updating global sidebar settings
+      #   BetterService::CacheService.invalidate_global("sidebar")
+      def invalidate_global(context, async: false)
+        return 0 unless context && !context.to_s.strip.empty?
+
+        pattern = build_global_context_pattern(context)
+
+        if async
+          invalidate_async(pattern)
+          0
+        else
+          result = delete_matched(pattern)
+          # Ensure we return Integer, not Array
+          result.is_a?(Array) ? result.size : (result || 0)
+        end
+      end
+
+      # Invalidate all cache for a specific user
+      #
+      # Deletes all cache keys associated with the given user.
+      # This is useful when a user logs out or their permissions change.
+      #
+      # @param user [Object] The user whose cache should be invalidated
+      # @param async [Boolean] Whether to perform invalidation asynchronously
+      # @return [Integer] Number of keys deleted (if supported by cache store)
+      #
+      # @example
+      #   # After user role changes
+      #   BetterService::CacheService.invalidate_for_user(current_user)
+      def invalidate_for_user(user, async: false)
+        return 0 unless user
+
+        pattern = build_user_pattern(user)
+
+        if async
+          invalidate_async(pattern)
+          0
+        else
+          result = delete_matched(pattern)
+          # Ensure we return Integer, not Array
+          result.is_a?(Array) ? result.size : (result || 0)
+        end
+      end
+
+      # Invalidate specific cache key
+      #
+      # Deletes a single cache key. Useful when you know the exact key.
+      #
+      # @param key [String] The cache key to delete
+      # @return [Boolean] true if deleted, false otherwise
+      #
+      # @example
+      #   BetterService::CacheService.invalidate_key("products_index:user_123:abc123")
+      def invalidate_key(key)
+        return false unless key && !key.to_s.strip.empty?
+
+        Rails.cache.delete(key)
+        true
+      rescue ArgumentError
+        # Rails.cache.delete raises ArgumentError for invalid keys
+        false
+      end
+
+      # Clear all BetterService cache
+      #
+      # WARNING: This deletes ALL cache keys that match BetterService patterns.
+      # Use with caution, preferably only in development/testing.
+      #
+      # @return [Integer] Number of keys deleted (if supported by cache store)
+      #
+      # @example
+      #   # In test setup
+      #   BetterService::CacheService.clear_all
+      def clear_all
+        pattern = "*:user_*:*" # Match all BetterService cache keys
+        result = delete_matched(pattern)
+        # Ensure we return Integer, not Array
+        result.is_a?(Array) ? result.size : (result || 0)
+      end
+
+      # Fetch from cache with block
+      #
+      # Wrapper around Rails.cache.fetch with BetterService conventions.
+      # If the key exists, returns cached value. Otherwise, executes block,
+      # caches the result, and returns it.
+      #
+      # @param key [String] The cache key
+      # @param options [Hash] Options passed to Rails.cache.fetch
+      # @option options [Integer] :expires_in TTL in seconds
+      # @option options [Boolean] :force Force cache refresh
+      # @return [Object] The cached or computed value
+      #
+      # @example
+      #   result = BetterService::CacheService.fetch("my_key", expires_in: 1.hour) do
+      #     expensive_computation
+      #   end
+      def fetch(key, options = {}, &block)
+        Rails.cache.fetch(key, options, &block)
+      end
+
+      # Check if a key exists in cache
+      #
+      # @param key [String] The cache key to check
+      # @return [Boolean] true if key exists, false otherwise
+      def exist?(key)
+        return false unless key && !key.to_s.strip.empty?
+
+        Rails.cache.exist?(key)
+      end
+
+      # Get cache statistics
+      #
+      # Returns information about cache store and BetterService cache usage.
+      # Note: Detailed stats only available with certain cache stores (Redis).
+      #
+      # @return [Hash] Cache statistics
+      def stats
+        {
+          cache_store: Rails.cache.class.name,
+          supports_pattern_deletion: supports_delete_matched?,
+          supports_async: defined?(ActiveJob) ? true : false
+        }
+      end
+
+      private
+
+      # Build cache key pattern for user + context
+      #
+      # @param user [Object] User object with id
+      # @param context [String] Context name
+      # @return [String] Pattern like "*:user_123:*:products"
+      def build_user_context_pattern(user, context)
+        user_id = user.respond_to?(:id) ? user.id : user
+        "*:user_#{user_id}:*:#{context}"
+      end
+
+      # Build cache key pattern for global context
+      #
+      # @param context [String] Context name
+      # @return [String] Pattern like "*:#{context}"
+      def build_global_context_pattern(context)
+        "*:#{context}"
+      end
+
+      # Build cache key pattern for user (all contexts)
+      #
+      # @param user [Object] User object with id
+      # @return [String] Pattern like "*:user_123:*"
+      def build_user_pattern(user)
+        user_id = user.respond_to?(:id) ? user.id : user
+        "*:user_#{user_id}:*"
+      end
+
+      # Delete cache keys matching pattern
+      #
+      # Uses Rails.cache.delete_matched if supported by cache store.
+      # Falls back to no-op if not supported (e.g., MemoryStore).
+      #
+      # @param pattern [String] Pattern with wildcards
+      # @return [Integer] Number of keys deleted (0 if not supported)
+      def delete_matched(pattern)
+        if supports_delete_matched?
+          # Convert wildcard pattern to regex for Rails.cache.delete_matched
+          # Pattern like "*:user_123:*:products" becomes /.*:user_123:.*:products/
+          regex_pattern = convert_pattern_to_regex(pattern)
+          count = Rails.cache.delete_matched(regex_pattern)
+          log_invalidation(pattern, count)
+          count || 0
+        else
+          log_warning("Cache store #{Rails.cache.class.name} does not support pattern deletion")
+          0
+        end
+      end
+
+      # Convert wildcard pattern to Regexp
+      #
+      # @param pattern [String] Pattern with * wildcards
+      # @return [Regexp] Regexp for matching cache keys
+      def convert_pattern_to_regex(pattern)
+        return // unless pattern
+
+        # Escape special regex characters except *
+        escaped = Regexp.escape(pattern.to_s)
+        # Replace escaped \* with .* for regex matching
+        regex_string = escaped.gsub('\*', '.*')
+        Regexp.new(regex_string)
+      end
+
+      # Invalidate cache asynchronously using ActiveJob
+      #
+      # @param pattern [String] Pattern to invalidate
+      # @return [void]
+      def invalidate_async(pattern)
+        if defined?(ActiveJob)
+          CacheInvalidationJob.perform_later(pattern)
+          log_invalidation(pattern, "async")
+        else
+          # Fallback to synchronous if ActiveJob not available
+          delete_matched(pattern)
+        end
+      end
+
+      # Check if cache store supports delete_matched
+      #
+      # @return [Boolean]
+      def supports_delete_matched?
+        Rails.cache.respond_to?(:delete_matched)
+      end
+
+      # Log cache invalidation
+      #
+      # @param pattern [String] Pattern invalidated
+      # @param count [Integer, String] Number of keys or "async"
+      # @return [void]
+      def log_invalidation(pattern, count)
+        return unless defined?(Rails) && Rails.logger
+
+        if count == "async"
+          Rails.logger.info "[BetterService::CacheService] Async invalidation queued: #{pattern}"
+        else
+          Rails.logger.info "[BetterService::CacheService] Invalidated #{count} keys matching: #{pattern}"
+        end
+      end
+
+      # Log warning
+      #
+      # @param message [String] Warning message
+      # @return [void]
+      def log_warning(message)
+        return unless defined?(Rails) && Rails.logger
+
+        Rails.logger.warn "[BetterService::CacheService] #{message}"
+      end
+    end
+
+    # ActiveJob for async cache invalidation
+    #
+    # This job is only defined if ActiveJob is available.
+    # It allows cache invalidation to happen in the background.
+    if defined?(ActiveJob)
+      class CacheInvalidationJob < ActiveJob::Base
+        queue_as :default
+
+        # Perform cache invalidation
+        #
+        # @param pattern [String] Cache key pattern to invalidate
+        def perform(pattern)
+          BetterService::CacheService.send(:delete_matched, pattern)
+        end
+      end
+    end
+  end
+end

data/lib/better_service/concerns/instrumentation.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module BetterService
+  # Instrumentation - Provides automatic event publishing for service execution
+  #
+  # This concern automatically publishes ActiveSupport::Notifications events
+  # during the service lifecycle, enabling monitoring, metrics, and observability.
+  #
+  # Events published:
+  # - service.started - When service execution begins
+  # - service.completed - When service completes successfully
+  # - service.failed - When service raises an exception
+  # - cache.hit - When cache lookup returns cached data
+  # - cache.miss - When cache lookup requires fresh computation
+  #
+  # @example Subscribe to all service events
+  #   ActiveSupport::Notifications.subscribe("service.completed") do |name, start, finish, id, payload|
+  #     puts "#{payload[:service_name]} took #{payload[:duration]}ms"
+  #   end
+  #
+  # @example Subscribe to specific service
+  #   ActiveSupport::Notifications.subscribe("service.completed") do |name, start, finish, id, payload|
+  #     if payload[:service_name] == "ProductsIndexService"
+  #       DataDog.histogram("products.index.duration", payload[:duration])
+  #     end
+  #   end
+  module Concerns
+    module Instrumentation
+      extend ActiveSupport::Concern
+
+      # Hook into prepend to wrap call method
+      #
+      # This is called when the concern is prepended to a class.
+      def self.prepended(base)
+        # Always wrap call method
+        base.class_eval do
+            # Save original call method
+            alias_method :call_without_instrumentation, :call
+
+            # Define new call method with instrumentation
+            define_method(:call) do
+              return call_without_instrumentation unless instrumentation_enabled?
+
+              service_name = self.class.name
+              user_id = extract_user_id_from_instance
+
+              # Publish service.started event
+              payload = build_start_payload(service_name, user_id)
+              ActiveSupport::Notifications.instrument("service.started", payload)
+
+              # Execute the service
+              start_time = Time.current
+
+              begin
+                result = call_without_instrumentation
+                duration = ((Time.current - start_time) * 1000).round(2) # milliseconds
+
+                # Publish service.completed event
+                completion_payload = build_completion_payload(
+                  service_name, user_id, result, duration
+                )
+                ActiveSupport::Notifications.instrument("service.completed", completion_payload)
+
+                result
+              rescue => error
+                duration = ((Time.current - start_time) * 1000).round(2)
+
+                # Extract original error if wrapped in ExecutionError
+                original_error = error.respond_to?(:original_error) && error.original_error ? error.original_error : error
+
+                # Publish service.failed event
+                failure_payload = build_failure_payload(
+                  service_name, user_id, original_error, duration
+                )
+                ActiveSupport::Notifications.instrument("service.failed", failure_payload)
+
+                # Re-raise the error (don't swallow it)
+                raise
+              end
+            end
+          end
+      end
+
+      # Check if instrumentation is enabled for this service
+      #
+      # @return [Boolean]
+      def instrumentation_enabled?
+        return false unless BetterService.configuration.instrumentation_enabled
+
+        excluded = BetterService.configuration.instrumentation_excluded_services
+        full_name = self.class.name
+
+        # Check exact match or if excluded name matches the end of full name
+        !excluded.any? { |excluded_name| full_name == excluded_name || full_name.end_with?("::#{excluded_name}") }
+      end
+
+      # Extract user ID from service instance
+      #
+      # @return [Integer, String, nil]
+      def extract_user_id_from_instance
+        return nil unless respond_to?(:user, true)
+
+        user = send(:user)
+        return nil unless user
+
+        user.respond_to?(:id) ? user.id : user
+      end
+
+      # Build payload for service.started event
+      #
+      # @param service_name [String] Name of service class
+      # @param user_id [Integer, String, nil] User ID
+      # @return [Hash] Event payload
+      def build_start_payload(service_name, user_id)
+        payload = {
+          service_name: service_name,
+          user_id: user_id,
+          timestamp: Time.current.iso8601
+        }
+
+        # Include params if configured and available
+        if BetterService.configuration.instrumentation_include_args && respond_to?(:params, true)
+          payload[:params] = send(:params)
+        end
+
+        payload
+      end
+
+      # Build payload for service.completed event
+      #
+      # @param service_name [String] Name of service class
+      # @param user_id [Integer, String, nil] User ID
+      # @param result [Object] Service result
+      # @param duration [Float] Execution duration in milliseconds
+      # @return [Hash] Event payload
+      def build_completion_payload(service_name, user_id, result, duration)
+        payload = {
+          service_name: service_name,
+          user_id: user_id,
+          duration: duration,
+          timestamp: Time.current.iso8601,
+          success: true
+        }
+
+        # Include params if configured and available
+        if BetterService.configuration.instrumentation_include_args && respond_to?(:params, true)
+          payload[:params] = send(:params)
+        end
+
+        # Include result if configured
+        if BetterService.configuration.instrumentation_include_result
+          payload[:result] = result
+        end
+
+        # Include cache metadata if available
+        if result.is_a?(Hash)
+          if result.key?(:cache_hit)
+            payload[:cache_hit] = result[:cache_hit]
+          end
+          if result.key?(:cache_key)
+            payload[:cache_key] = result[:cache_key]
+          end
+        end
+
+        payload
+      end
+
+      # Build payload for service.failed event
+      #
+      # @param service_name [String] Name of service class
+      # @param user_id [Integer, String, nil] User ID
+      # @param error [Exception] The error that was raised
+      # @param duration [Float] Execution duration in milliseconds
+      # @return [Hash] Event payload
+      def build_failure_payload(service_name, user_id, error, duration)
+        payload = {
+          service_name: service_name,
+          user_id: user_id,
+          duration: duration,
+          timestamp: Time.current.iso8601,
+          success: false,
+          error_class: error.class.name,
+          error_message: error.message
+        }
+
+        # Include params if configured and available
+        if BetterService.configuration.instrumentation_include_args && respond_to?(:params, true)
+          payload[:params] = send(:params)
+        end
+
+        # Include backtrace (first 5 lines) for debugging
+        if error.backtrace
+          payload[:error_backtrace] = error.backtrace.first(5)
+        end
+
+        payload
+      end
+
+      # Publish cache hit event
+      #
+      # Called from Cacheable concern when cache lookup succeeds.
+      #
+      # @param cache_key [String] The cache key that was hit
+      # @param context [String] Cache context (e.g., "products")
+      # @return [void]
+      def publish_cache_hit(cache_key, context = nil)
+        return unless instrumentation_enabled?
+
+        payload = {
+          service_name: self.class.name,
+          event_type: "cache_hit",
+          cache_key: cache_key,
+          context: context,
+          timestamp: Time.current.iso8601
+        }
+
+        ActiveSupport::Notifications.instrument("cache.hit", payload)
+      end
+
+      # Publish cache miss event
+      #
+      # Called from Cacheable concern when cache lookup fails.
+      #
+      # @param cache_key [String] The cache key that missed
+      # @param context [String] Cache context (e.g., "products")
+      # @return [void]
+      def publish_cache_miss(cache_key, context = nil)
+        return unless instrumentation_enabled?
+
+        payload = {
+          service_name: self.class.name,
+          event_type: "cache_miss",
+          cache_key: cache_key,
+          context: context,
+          timestamp: Time.current.iso8601
+        }
+
+        ActiveSupport::Notifications.instrument("cache.miss", payload)
+      end
+    end
+  end
+end

data/lib/better_service/concerns/serviceable/authorizable.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Concerns
+    module Serviceable
+      # Authorizable adds authorization support to services.
+    #
+    # Use the `authorize_with` DSL to define authorization logic that runs
+    # BEFORE the search phase (fail fast principle).
+    #
+    # The authorization block has access to:
+    # - user: The current user object
+    # - params: The validated parameters
+    #
+    # If authorization fails (block returns false/nil), the service stops
+    # immediately and raises AuthorizationError with code :unauthorized.
+    #
+    # Example:
+    #   class Product::UpdateService < BetterService::UpdateService
+    #     authorize_with do
+    #       user.admin? || product_belongs_to_user?
+    #     end
+    #
+    #     def product_belongs_to_user?
+    #       Product.find(params[:id]).user_id == user.id
+    #     end
+    #   end
+    #
+    # Works with any authorization library (Pundit, CanCanCan, custom):
+    #
+    #   # Pundit style
+    #   authorize_with do
+    #     ProductPolicy.new(user, resource).update?
+    #   end
+    #
+    #   # CanCanCan style
+    #   authorize_with do
+    #     Ability.new(user).can?(:update, :product)
+    #   end
+    #
+    #   # Custom logic
+    #   authorize_with do
+    #     user.has_role?(:editor) && params[:status] != 'published'
+    #   end
+    module Authorizable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_authorize_block, default: nil
+      end
+
+      class_methods do
+        # Define authorization logic that runs before search phase.
+        #
+        # @yield Block that returns true/false for authorization check
+        # @return [void]
+        #
+        # @example Simple role check
+        #   authorize_with do
+        #     user.admin?
+        #   end
+        #
+        # @example Resource ownership check
+        #   authorize_with do
+        #     resource = Product.find(params[:id])
+        #     resource.user_id == user.id
+        #   end
+        #
+        # @example With Pundit
+        #   authorize_with do
+        #     ProductPolicy.new(user, Product.find(params[:id])).update?
+        #   end
+        def authorize_with(&block)
+          self._authorize_block = block
+        end
+      end
+
+      # Execute authorization check if defined.
+      #
+      # Runs the authorization block defined with `authorize_with`.
+      # Has access to user and params.
+      #
+      # @raise [Errors::Runtime::AuthorizationError] If authorization fails
+      # @return [void]
+      def authorize!
+        return unless self.class._authorize_block
+
+        authorized = instance_exec(&self.class._authorize_block)
+
+        return if authorized
+
+        # Raise AuthorizationError instead of returning hash
+        raise Errors::Runtime::AuthorizationError.new(
+          "Not authorized to perform this action",
+          code: ErrorCodes::UNAUTHORIZED,
+          context: {
+            service: self.class.name,
+            user: user&.id || "nil",
+            params: @params
+          }
+        )
+      end
+    end
+    end
+  end
+end