gaskit 0.1.0

data/lib/gaskit/configuration.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Gaskit
+  # Gaskit::Configuration holds global configuration for the Gaskit gem.
+  #
+  # It allows customization of logging behavior, including:
+  # - Log level (`log_level`)
+  # - Custom logger (`logger`)
+  # - Disabling logging entirely (`disable_logging`)
+  # - Structured or custom log formatting (`log_formatter`)
+  # - Debug mode (`debug`)
+  #
+  # @example Configuring Gaskit in an initializer
+  #   Gaskit.config do |c|
+  #     c.debug = true
+  #     c.disable_logging = false
+  #
+  #     c.context_provider = -> {
+  #       {
+  #         tenant_id: Current.tenant_id,
+  #         user_id: Current.user_id
+  #       }
+  #     }
+  #
+  #     # Optionally replace the logger
+  #     custom_logger = Logger.new("log/gaskit.log")
+  #     c.setup_logger(custom_logger, level: :info, formatter: ->(severity, time, _progname, msg) {
+  #       message, context = msg.is_a?(Array) ? msg : [msg, {}]
+  #       "[#{time.strftime('%Y-%m-%d %H:%M:%S')} #{severity}] #{message} (#{context.inspect})\n"
+  #     })
+  #   end
+  class Configuration
+    # @return [Boolean] Whether debug mode is enabled.
+    attr_accessor :debug
+
+    # @return [Boolean] Whether to completely suppress log output.
+    attr_accessor :disable_logging
+
+    # @return [Logger] The logger instance used internally by Gaskit.
+    attr_reader :logger
+
+    # @return[#call] A callable to apply a global context used for all log entries.
+    attr_reader :context_provider
+
+    # Initializes the configuration with default settings.
+    #
+    # The configuration includes:
+    # - Default environment set to `"development"`
+    # - Debug mode disabled
+    # - Logging to stdout
+    # - Default log level set to ::Logger::DEBUG
+    # - An empty base context hash
+    # - A new `ContractRegistry` instance for contract management
+    def initialize
+      @debug = false
+      @disable_logging = false
+      @context_provider = -> { {} }
+      @contract_registry = ContractRegistry.new
+
+      setup_logger
+    end
+
+    # Sets the logger, formatter, and level in one go.
+    #
+    # @param custom_logger [::Logger, nil] An optional custom logger.
+    # @param level [Symbol, Integer] Log level (e.g., :debug, Logger::WARN)
+    # @param formatter [Proc] Custom formatter for log entries.
+    def setup_logger(custom_logger = nil, level: :debug, formatter: nil)
+      @logger = custom_logger || ::Logger.new($stdout)
+
+      effective_formatter = formatter || @logger&.formatter || Gaskit::Logger.formatter(:pretty)
+      self.log_formatter = effective_formatter if effective_formatter.respond_to?(:call)
+      self.log_level = level
+    end
+
+    # Sets the logging level.
+    #
+    # @param level [Symbol, Integer] The log level (e.g., :info, :debug, or Logger::WARN).
+    # @raise [NameError] If the provided level is a symbol, and it does not map to a valid Logger constant.
+    def log_level=(level)
+      level = ::Logger.const_get(level.upcase) if level.is_a?(Symbol)
+      @logger.level = level
+    end
+
+    # Sets a custom log formatter.
+    #
+    # @param formatter [#call] A callable object that receives log arguments (severity, time, progname, msg).
+    # @raise [ArgumentError] If the provided formatter is not callable.
+    def log_formatter=(formatter)
+      raise ArgumentError, "Formatter must be callable" unless formatter.respond_to?(:call)
+
+      @logger.formatter = formatter
+    end
+
+    # Sets the global context provider used for all log entries.
+    #
+    # @param provider [#call] A proc or lambda returning a Hash of context values.
+    # @raise [ArgumentError] If the provided callable is not callable.
+    def context_provider=(provider)
+      raise ArgumentError, "Provider must be callable" unless provider.respond_to?(:call)
+
+      @context_provider = provider
+    end
+
+    # Registers a contract with a name and associated result class.
+    #
+    # @param name [Symbol, String] The name of the contract.
+    # @param result_class [Class] The class that represents the result for the contract.
+    # @param override [Boolean] Whether to override an existing contract (default: false).
+    # @raise [Gaskit::ContractError] If the contract is already registered and override is not allowed.
+    # @raise [Gaskit::ResultTypeError] If the result_class does not inherit from `Gaskit::OperationResult`.
+    # @return [void]
+    def register_contract(name, result_class, override: false)
+      @contract_registry.register(name, result_class, override: override)
+    end
+
+    # Fetches a registered contract's result class by its name.
+    #
+    # @param name [Symbol, String] The name of the contract.
+    # @return [Class] The result class associated with the contract.
+    # @raise [Gaskit::ContractError] If the contract is not registered.
+    def fetch_contract(name)
+      @contract_registry.fetch(name)
+    end
+
+    # Checks if a contract is registered.
+    #
+    # @param name [Symbol, String] The name of the contract.
+    # @return [Boolean] true if the contract is registered, otherwise false.
+    def contract_registered?(name)
+      @contract_registry.registered?(name)
+    end
+
+    # Lists all registered contracts.
+    #
+    # @return [Hash<Symbol, Class>] A hash of all registered contracts where keys are
+    #   contract names and values are their corresponding result classes.
+    def registered_contracts
+      @contract_registry.all
+    end
+  end
+end

data/lib/gaskit/contract_registry.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "core"
+
+module Gaskit
+  # Represents a registry for managing contracts and their result classes
+  #
+  # This class allows registering contracts with associated result classes,
+  # checking if they are registered, and fetching them for use.
+  # It also includes validation to ensure result classes adhere to the expected base class.
+  class ContractRegistry
+    class << self
+      # Verifies that the given class is a subclass of `Gaskit::BaseResult`
+      #
+      # @param result_class [Class] The class to verify
+      # @raise [Gaskit::ResultTypeError] if the class does not inherit from `Gaskit::BaseResult`
+      def verify_result_class!(result_class)
+        raise Gaskit::ResultTypeError, result_class unless result_class <= Gaskit::OperationResult
+      end
+    end
+
+    # Initializes a new instance of `ContractRegistry`
+    #
+    # Sets up the internal hash for storing contracts.
+    def initialize
+      @contracts = {}
+    end
+
+    # Registers a contract with an associated result class
+    #
+    # @param name [Symbol, String] The name of the contract
+    # @param result_class [Class] The class that represents the result for the contract
+    # @param override [Boolean] Whether to override an existing registration (default: false)
+    # @raise [Gaskit::ContractError] if the contract is already registered and override is not allowed
+    # @raise [Gaskit::ResultTypeError] if the result_class does not inherit from `Gaskit::BaseResult`
+    # @return [void]
+    def register(name, result_class, override: false)
+      name = name.to_sym
+      raise Gaskit::ContractError, "Contract #{name} already registered" if @contracts.key?(name) && !override
+
+      ContractRegistry.verify_result_class!(result_class)
+      @contracts[name] = result_class.freeze
+
+      Gaskit.configuration.logger.debug { "[Gaskit] Registered contract #{name}" } if Gaskit.debug?
+    end
+
+    # Checks if a contract is registered
+    #
+    # @param name [Symbol, String] The name of the contract
+    # @return [Boolean] true if the contract is registered, otherwise false
+    def registered?(name)
+      @contracts.key?(name.to_sym)
+    end
+
+    # Fetches a registered contract's result class
+    #
+    # @param name [Symbol, String] The name of the contract
+    # @return [Class] The result class for the contract
+    # @raise [Gaskit::ContractError] if the contract is not registered
+    def fetch(name)
+      @contracts.fetch(name.to_sym) do
+        raise Gaskit::ContractError, "Contract #{name} not registered, register it with " \
+                                     "Gaskit.configuration.register_contract(name, result_class)"
+      end
+    end
+
+    # Returns a duplicate of all registered contracts
+    #
+    # @return [Hash<Symbol, Class>] A hash of all registered contracts where keys are
+    #   contract names and values are their corresponding result classes
+    def all
+      @contracts.dup
+    end
+  end
+end

data/lib/gaskit/core.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "contract_registry"
+
+module Gaskit
+  class << self
+    # Configures the Gaskit system.
+    #
+    # This yields the configuration instance, allowing you to modify settings such as logger,
+    # global context, log level, and formatting.
+    #
+    # @yieldparam [Gaskit::Configuration] configuration
+    # @return [void]
+    def config
+      yield(configuration)
+    end
+
+    # Retrieves the global Gaskit configuration.
+    #
+    # @return [Gaskit::Configuration] the configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Returns configuration.debug.
+    #
+    # @return [Boolean] `true` is Gaskit is set to debug, `false` otherwise.
+    def debug?
+      Gaskit.configuration.debug
+    end
+
+    # Registers a new operation contract.
+    #
+    # @param name [Symbol, String] Contract name
+    # @param result_class [Class<Gaskit::OperationResult>] Result class for the operation
+    def register_contract(name, result_class, override: false)
+      configuration.register_contract(name, result_class, override: override)
+    end
+
+    # Fetches the result and exit classes for the given contract name.
+    #
+    # @param name [Symbol, String]
+    # @return [Class]
+    def fetch_contract(name)
+      configuration.fetch_contract(name)
+    end
+
+    # Returns whether the contract is registered.
+    #
+    # @param name [Symbol, String]
+    # @return [Boolean]
+    def contract_registered?(name)
+      configuration.contract_registered?(name)
+    end
+
+    # Returns all registered contracts.
+    #
+    # @return [Hash{Symbol=>Hash}]
+    def registered_contracts
+      configuration.registered_contracts
+    end
+  end
+end

data/lib/gaskit/error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Gaskit
+  class Error < StandardError; end
+
+  class ContractError < Error; end
+
+  # Raised when an operation contract supplies an incorrect result type.
+  class ResultTypeError < Error
+    # @param [Class] klazz The class that failed the type check.
+    def initialize(klazz)
+      message = "Expected result class to inherit from Gaskit::BaseResult, got: #{klazz}"
+      super(message)
+    end
+  end
+end

data/lib/gaskit/flow.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "core"
+require_relative "flow_result"
+require_relative "helpers"
+
+module Gaskit
+  # Base class for defining and executing multi-step operation pipelines
+  #
+  # @example Inline (block-based) flow
+  #   result = Gaskit::Flow.call(1, 2, context: {}) do
+  #     step AddOp
+  #     step MultOp, multiplier: 2
+  #   end
+  #
+  # @example Class-based flow
+  #   class MyFlow < Gaskit::Flow
+  #     step AddOp
+  #     step MultOp, multiplier: 1.5
+  #   end
+  #
+  #   result = MyFlow.call(5, 5, context: { request_id: "abc123" })
+  class Flow
+    class << self
+      # Inherited hook to initialize step DSL
+      #
+      # @param subclass [Class] The subclass inheriting from Flow
+      # @return [void]
+      def inherited(subclass)
+        subclass.instance_variable_set(:@defined_steps, [])
+        super
+      end
+
+      # Returns defined steps for the flow class
+      #
+      # @return [Array<Array>] An array of [operation, args, kwargs] tuples
+      def defined_steps
+        @defined_steps ||= []
+      end
+
+      # Adds a step to the flow
+      #
+      # @param operation [Class<Gaskit::Operation>] The operation class
+      # @param args [Array] Positional arguments for the step
+      # @param context [Hash] Optional context overrides
+      # @param kwargs [Hash] Keyword arguments for the step
+      # @return [void]
+      def step(operation, *args, context: {}, **kwargs)
+        kwargs = kwargs.merge(context: context)
+        defined_steps << [operation, args, kwargs]
+      end
+
+      # Executes the flow with soft-failure handling
+      #
+      # @param args [Array] Positional arguments for the first step
+      # @param context [Hash] Shared context across all steps
+      # @param kwargs [Hash] Keyword arguments for the first step
+      # @return [FlowResult]
+      def call(*args, context: {}, **kwargs, &block)
+        invoke(false, context, *args, **kwargs, &block)
+      end
+
+      # Executes the flow with hard-failure handling (raises on unhandled errors)
+      #
+      # @param args [Array] Positional arguments for the first step
+      # @param context [Hash] Shared context across all steps
+      # @param kwargs [Hash] Keyword arguments for the first step
+      # @return [FlowResult]
+      def call!(*args, context: {}, **kwargs, &block)
+        invoke(true, context, *args, **kwargs, &block)
+      end
+
+      private
+
+      # Internal flow initializer
+      def invoke(raise_on_failure, context, *args, **kwargs, &block)
+        flow = new(raise_on_failure, context, [args, kwargs])
+        flow.execute(&block)
+      end
+    end
+
+    # @return [Hash] Execution context
+    attr_reader :context
+
+    # @return [Gaskit::OperationResult] Most recent result
+    attr_reader :result
+
+    # @return [Array<Hash>] List of step metadata
+    attr_reader :steps
+
+    # Executes a single step of the flow
+    #
+    # @param operation [Class<Gaskit::Operation>]
+    # @param args [Array] Additional positional arguments
+    # @param context [Hash] Step-local context
+    # @param kwargs [Hash] Additional keyword arguments
+    # @return [void]
+    def step(operation, *args, context: {}, **kwargs, &block)
+      raise ArgumentError, "Operation must be a subclass of Gaskit::Operation" unless operation <= Gaskit::Operation
+
+      return if result&.early_exit?
+
+      kwargs = kwargs.merge(context: context)
+      @result = execute_step(operation, *args, **kwargs, &block)
+      @steps << compile_step_entry(operation, *args, **kwargs)
+
+      update_input(result)
+    end
+
+    # Executes the flow either via block or pre-defined DSL
+    #
+    # @return [FlowResult]
+    def execute(&block)
+      duration, = Gaskit::Helpers.time_execution do
+        if block_given?
+          instance_eval(&block)
+        else
+          self.class.defined_steps.each { |(op, args, kwargs)| step(op, *args, **kwargs) }
+        end
+
+        result
+      end
+
+      FlowResult.new(@result, @steps, duration: duration, context: @context)
+    end
+
+    private
+
+    # Initializes a flow instance
+    #
+    # @param raise_on_failure [Boolean] Whether to raise on unexpected errors
+    # @param context [Hash] Flow context
+    # @param input [Array] Initial args/kwargs input bundle
+    def initialize(raise_on_failure, context, input)
+      @raise_on_failure = raise_on_failure
+      @context = apply_context(context)
+      @input = input
+      @steps = []
+      @result = nil
+    end
+
+    # Applies global context, if set, from Gaskit.configuration.context_provider
+    # and injects the `gaskit_flow` key to indicate to operations they are a part
+    # of a flow.
+    #
+    # @param context [Hash] The context provided directly to the Flow.
+    # @return [Hash] The fully applied context Hash.
+    def apply_context(context)
+      default_context = Gaskit.configuration.context_provider.call
+      context = default_context.merge(
+        gaskit_flow: { id: SecureRandom.uuid, name: self.class.name },
+        **context
+      )
+
+      Helpers.deep_compact(context)
+    end
+
+    # Executes a single operation step and handles errors
+    #
+    # @param operation [Class<Gaskit::Operation>]
+    # @param kwargs [Hash] Merged args/kwargs/context
+    # @return [Gaskit::OperationResult]
+    def execute_step(operation, **kwargs, &block)
+      input_args, input_kwargs = @input
+      kwargs = (input_kwargs || {}).merge(kwargs).merge(context: @context)
+
+      return operation.call!(*input_args, **kwargs, &block) if @raise_on_failure
+
+      operation.call(*input_args, **kwargs, &block)
+    rescue StandardError => e
+      raise e if @raise_on_failure
+
+      result_class = operation.class.result_class
+      result_class.new(false, nil, e, duration: 0.0, context: @context)
+    end
+
+    # Logs a step’s full input and output
+    #
+    # @param operation [Class]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Hash] Step metadata
+    def compile_step_entry(operation, *args, **kwargs)
+      args, kwargs = step_input(*args, **kwargs)
+
+      {
+        operation: operation,
+        args: args,
+        kwargs: kwargs,
+        result: result.to_h
+      }
+    end
+
+    # Combines current flow input with explicit args for logging
+    #
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Array<Array, Hash>]
+    def step_input(*args, **kwargs)
+      input_args, input_kwargs = @input
+      args = (input_args || []).concat(args)
+      kwargs = input_kwargs.merge(kwargs)
+
+      [args, kwargs]
+    end
+
+    # Set the input used to call the next operation. Do not set input if the result
+    # is a failure or has a nil value.
+    #
+    # @param result [Gaskit::OperationResult] The result of the operation.
+    # @return [void]
+    def update_input(result)
+      return if result&.failure? || result&.value.nil?
+
+      @input =
+        case result.value
+        when Array
+          [result.value, {}]
+        when Hash
+          [[], result.value]
+        else
+          [[result.value], {}]
+        end
+    end
+  end
+end

data/lib/gaskit/flow_result.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Gaskit
+  # Represents the result of a flow execution, including step-by-step trace
+  #
+  # @example Checking result and accessing steps
+  #   result = MyFlow.call(1, 2)
+  #   if result.success?
+  #     puts "Total: #{result.value}"
+  #   else
+  #     puts "Failed at: #{result.steps.last[:operation]}"
+  #   end
+  class FlowResult < OperationResult
+    # @return [Array<Hash>] A list of step data executed during the flow
+    attr_reader :steps
+
+    # Initializes a new FlowResult
+    #
+    # @param result [Gaskit::OperationResult] The final operation result
+    # @param steps [Array<Hash>] Step-by-step execution details
+    # @param duration [Float, String] Total flow duration
+    # @param context [Hash] Execution context
+    def initialize(result, steps, duration:, context: {})
+      super(
+        result.success?,
+        result.value,
+        result.error,
+        duration: duration,
+        context: context
+      )
+
+      @steps = steps
+    end
+  end
+end

data/lib/gaskit/helpers.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Gaskit
+  module Helpers
+    class << self
+      # Measures the time taken for execution.
+      #
+      # @yield The block containing the logic to time.
+      # @return [Array<Float, Object>] The duration and the result.
+      def time_execution
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = yield
+        duration = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time)
+
+        [format("%.6f", duration), result]
+      end
+
+      # Applies deep compat on the provided hash.
+      #
+      # @param hash [Hash] The original hash to compact.
+      # @return [Hash] The compacted hash.
+      def deep_compact(hash)
+        hash.each_with_object({}) do |(k, v), result|
+          compacted = v.is_a?(Hash) ? deep_compact(v) : v
+          result[k.to_sym] = compacted unless compacted.nil?
+        end
+      end
+    end
+  end
+end