gaskit 0.1.0

data/lib/gaskit/logger.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require "logger"
+require "json"
+require "time"
+require "English"
+
+require_relative "helpers"
+
+module Gaskit
+  # A logger class designed for structured logging with support for JSON, contextual data,
+  # and environment-aware formatting.
+  #
+  # This logger wraps a configurable `Logger` instance and supports:
+  #
+  # - Structured or human-readable log formatting
+  # - Inclusion of global and per-call context (with filtering of sensitive keys)
+  # - Support for custom log levels, formatters, and disabling output via `Gaskit.config`
+  #
+  # By default, logs are pretty-printed in development and JSON-formatted in production.
+  # These defaults can be overridden via configuration.
+  #
+  # @example Basic usage with default formatting
+  #   logger = Gaskit::Logger.new('MyOperation', context: { user_id: 42 })
+  #
+  #   logger.info("Operation started")
+  #   logger.debug(context: { details: "debug info" }) { "Deferred message" }
+  #
+  # @example Using logger within a class
+  #   class UserRepository
+  #     def self.logger
+  #       @logger ||= Gaskit::Logger.new(self)
+  #     end
+  #
+  #     def self.find(id)
+  #       logger.info("Looking up user", context: { user_id: id })
+  #     end
+  #   end
+  #
+  # @example Customizing the log formatter globally
+  #   Gaskit.config do |c|
+  #     c.log_formatter = ->(severity, time, _progname, msg) do
+  #       message, ctx = msg.is_a?(Array) ? msg : [msg, {}]
+  #       "[#{time.strftime('%T')}] #{severity}: #{message} #{ctx.to_json}\n"
+  #     end
+  #   end
+  #
+  # @example Configuring JSON or pretty formatters
+  #   Gaskit.config do |c|
+  #     c.setup_logger(Logger.new($stdout), formatter: Gaskit::Logger.formatter(:json))
+  #   end
+  #
+  #   # or
+  #
+  #   Gaskit.config do |c|
+  #     c.setup_logger(Logger.new($stdout), formatter: Gaskit::Logger.formatter(:pretty))
+  #   end
+  #
+  # @example Disabling logs entirely
+  #   Gaskit.config do |c|
+  #     c.disable_logging = true
+  #   end
+  #
+  # @see Gaskit::Configuration
+  class Logger
+    SENSITIVE_KEYS = %i[email ip_address password auth_token secret ssn jwt token].freeze
+
+    class << self
+      # Returns a built-in log formatter.
+      #
+      # Use this method to obtain either the JSON or pretty formatter for logs.
+      # This is useful when customizing the logger via `Gaskit.config`.
+      #
+      # @example Use JSON formatter
+      #   Gaskit.config do |c|
+      #     c.setup_logger(Logger.new($stdout), formatter: Gaskit::Logger.formatter(:json))
+      #   end
+      #
+      # @example Use pretty formatter
+      #   Gaskit.config do |c|
+      #     c.setup_logger(Logger.new($stdout), formatter: Gaskit::Logger.formatter(:pretty))
+      #   end
+      #
+      # @param formatter [Symbol] The formatter type to use (`:json` or `:pretty`)
+      # @return [Proc] A formatter proc suitable for use with `Logger#formatter`
+      # @raise [ArgumentError] If an unknown formatter symbol is provided
+      def formatter(formatter = :pretty)
+        case formatter
+        when :json
+          json_formatter
+        when :pretty
+          pretty_formatter
+        else
+          raise ArgumentError, "Invalid log formatter: #{formatter}"
+        end
+      end
+
+      # JSON formatter (for production or structured logs)
+      #
+      # @return [Proc] The formatter callable.
+      def json_formatter
+        lambda do |severity, time, _progname, msg|
+          message, context = extract_message_and_context(msg)
+
+          log_entry = {
+            timestamp: time.utc.iso8601,
+            level: severity.downcase,
+            class: context[:class],
+            message: message,
+            context: context&.reject { |k| k == :duration }
+          }.compact
+
+          log_entry[:duration] = context[:duration] if context&.key?(:duration)
+
+          "#{JSON.dump(log_entry)}\n"
+        end
+      end
+
+      # Pretty formatter (for dev logs)
+      #
+      # @return [Proc] The formatter callable.
+      def pretty_formatter
+        lambda do |severity, time, _progname, msg|
+          message, context = extract_message_and_context(msg)
+          context ||= {}
+
+          tags = %W[[#{time.utc.iso8601}] [#{severity}]]
+          tags << "[#{context[:class]}]" if context[:class]
+          tags += context.map { |k, v| "[#{k}=#{v}]" }
+
+          "#{tags.join(" ")} #{message}\n"
+        end
+      end
+
+      private
+
+      # Extracts the message and context from a log payload.
+      #
+      # @param msg [Object] The payload passed to the logger.
+      # @return [Array] An array with the message and context.
+      def extract_message_and_context(msg)
+        return [msg[0], msg[1]] if msg.is_a?(Array) && msg.size == 2
+
+        [msg.to_s, {}]
+      end
+    end
+
+    attr_reader :context
+
+    # Initializes a new logger instance.
+    #
+    # @param klass [Class] The name of the class being logged.
+    # @param context [Hash] Optional additional context to include in every log entry.
+    def initialize(klass, context: {})
+      @class_name = resolve_name(klass)
+      @context = apply_context(context)
+
+      @logger = Gaskit.configuration.logger || ::Logger.new($stdout)
+    rescue StandardError
+      ::Logger.new($stdout).error "Failed to initialize logger: #{$ERROR_INFO}"
+      @logger = ::Logger.new(nil) # fallback null logger
+    end
+
+    # Logs a debug-level message.
+    #
+    # @param message [String, nil] The log message (or provide it via the block parameter).
+    # @param context [Hash, nil] Additional context for this specific log entry.
+    # @yield Block for deferred log message computation.
+    def debug(message = nil, context: {}, &block)
+      log(:debug, message, context: context, &block)
+    end
+
+    # Logs an info-level message.
+    #
+    # @param message [String, nil] The log message (or provide it via the block parameter).
+    # @param context [Hash, nil] Additional context for this specific log entry.
+    # @yield Block for deferred log message computation.
+    def info(message = nil, context: {}, &block)
+      log(:info, message, context: context, &block)
+    end
+
+    # Logs a warning-level message.
+    #
+    # @param message [String, nil] The log message (or provide it via the block parameter).
+    # @param context [Hash, nil] Additional context for this specific log entry.
+    # @yield Block for deferred log message computation.
+    def warn(message = nil, context: {}, &block)
+      log(:warn, message, context: context, &block)
+    end
+
+    # Logs an error-level message.
+    #
+    # @param message [String, nil] The log message (or provide it via the block parameter).
+    # @param context [Hash, nil] Additional context for this specific log entry.
+    # @yield Block for deferred log message computation.
+    def error(message = nil, context: {}, &block)
+      log(:error, message, context: context, &block)
+    end
+
+    # Logs a message at the specified level.
+    #
+    # @param level [Symbol] The log level (e.g., :debug, :info).
+    # @param message [String, nil] The log message (or provide it via the block parameter).
+    # @param context [Hash, nil] Additional context for this specific log entry.
+    # @yield Block for deferred log message computation.
+    def log(level, message, context: {}, &block)
+      return if Gaskit.configuration.disable_logging
+
+      @logger.public_send(level) do
+        combined_context = filtered_context(@context.merge(context))
+        combined_context[:class] ||= @class_name
+
+        msg = message || block&.call
+
+        [msg, combined_context]
+      end
+    end
+
+    # Creates a new logger instance with additional merged context.
+    #
+    # @param extra_context [Hash] Additional context to include.
+    # @return [Gaskit::Logger] A new logger instance with the updated context.
+    def with_context(extra_context)
+      self.class.new(@class_name, context: @context.merge(extra_context))
+    end
+
+    private
+
+    # Resolves the class name provided when instantiating the logger.
+    #
+    # @return [String] The resolved class name.
+    def resolve_name(source)
+      case source
+      when String, Symbol
+        source.to_s
+      when Class
+        source.name
+      else
+        source.class.name
+      end
+    end
+
+    def apply_context(context)
+      default_context = Gaskit.configuration.context_provider.call
+      context = default_context.merge(context)
+
+      Helpers.deep_compact(context)
+    end
+
+    # Filters out sensitive values from the log context based on predefined keys.
+    #
+    # This method transforms all context keys to symbols and checks if each key is considered sensitive.
+    # If a key matches one of the predefined sensitive keys, its value is replaced with "[FILTERED]".
+    #
+    # @param context [Hash] The context hash to be filtered.
+    # @return [Hash] The filtered context hash with sensitive values masked.
+    def filtered_context(context)
+      filtered_context = context.transform_keys(&:to_sym).transform_values.with_index do |value, index|
+        key = context.keys[index].to_sym
+        sensitive_key?(key) ? "[FILTERED]" : value
+      end
+
+      Helpers.deep_compact(filtered_context)
+    end
+
+    # Determines if a given key is considered sensitive and should be masked in logs.
+    #
+    # @param key [Symbol, String] The key to evaluate.
+    # @return [Boolean] True if the key is sensitive and should be filtered; false otherwise.
+    def sensitive_key?(key)
+      SENSITIVE_KEYS.include?(key)
+    end
+  end
+end

data/lib/gaskit/operation.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require_relative "core"
+require_relative "operation_result"
+require_relative "operation_exit"
+require_relative "helpers"
+
+module Gaskit
+  # The Gaskit::Operation class defines a structured and extensible pattern for building application operations.
+  # It enforces consistent behavior across operations while supporting customization via contracts.
+  #
+  # # Features
+  # - Pluggable contracts via `use_contract`, allowing you to define or reference a `result` and
+  #   `early_exit` class.
+  # - A **contract** is a pairing of a result and early_exit class, either manually defined or registered
+  #   under a symbol.
+  # - Integrated duration tracking, structured logging, and early exits.
+  # - Supports `.call` (non-raising) and `.call!` (raising) styles.
+  #
+  # @example Using a registered contract
+  #   class MyOperation < Gaskit::Operation
+  #     use_contract :service
+  #
+  #     def call
+  #       # Do work
+  #       "done"
+  #     end
+  #   end
+  #
+  # @example Overriding only part of the contract
+  #   class MyCustomOp < Gaskit::Operation
+  #     use_contract :service, result: MyCustomResult
+  #
+  #     def call
+  #       exit(:unauthorized, "User not allowed") if unauthorized?
+  #       "okay"
+  #     end
+  #   end
+  #
+  # @example Fully manual contract
+  #   class ManualOp < Gaskit::Operation
+  #     use_contract result: MyResult, early_exit: MyExit
+  #
+  #     def call
+  #       do_work
+  #     end
+  #   end
+  #
+  #   result = ManualOp.call(context: { request_id: "abc123" })
+  #
+  # @abstract Subclass this and define `#call` or `#call!` to create a new operation.
+  class Operation
+    class << self
+      def result_class
+        return @result_class if defined?(@result_class) && @result_class
+        return superclass&.result_class if superclass.respond_to?(:result_class)
+
+        nil
+      end
+
+      # Defines the result and early exit classes for this operation.
+      # Can reference a named contract registered in `Gaskit::Registry`, override either part manually,
+      # or define both without using a named contract.
+      #
+      # @example Use a registered contract
+      #   use_contract :service
+      #
+      # @example Override only result class
+      #   use_contract :service, result: CustomResult
+      #
+      # @example Define both without using a contract name
+      #   use_contract result: CustomResult, early_exit: CustomExit
+      #
+      # @param contract [Symbol, nil] A registered contract name (e.g., `:service`)
+      # @param result [Class, nil] A class that inherits from `Gaskit::BaseResult`
+      # @raise [ArgumentError] if contract is not a symbol or unexpected args are passed
+      # @raise [ResultTypeError] if `result` is not a subclass of `Gaskit::BaseResult`
+      # @raise [EarlyExitTypeError] if `early_exit` is not a subclass of `Gaskit::BaseExit`
+      # @return [void]
+      def use_contract(contract = nil, result: nil)
+        if contract
+          raise ArgumentError, "use_contract must be called with a symbol or keyword args" unless contract.is_a?(Symbol)
+
+          result = Gaskit.fetch_contract(contract)
+        end
+
+        Gaskit::ContractRegistry.verify_result_class!(result)
+        @result_class = result
+      end
+
+      # Declares a symbolic error and message for use with `exit(:key)`
+      #
+      # @example
+      #   error :unauthorized, "You must be signed in", code: "AUTH-001"
+      #
+      # @param key [String, Symbol] The key used to declare the error.
+      # @param message [String] The error message.
+      # @param code [String, nil] Optional error code.
+      # @return [void]
+      def error(key, message, code: nil)
+        errors_registry[key.to_sym] = { message: message, code: code }
+      end
+
+      # Returns the error registry for the operation class
+      #
+      # @return [void]
+      def errors_registry
+        @errors_registry ||= {}
+      end
+
+      # Execute the operation without raising an exception on failure.
+      #
+      # @param [Array] args Positional arguments passed.
+      # @param [Hash] kwargs Keyword arguments passed (with optional :context).
+      # @yield [Block] Additional block logic to pass during the operation.
+      # @return [OperationResult] The result of the operation.
+      def call(*args, **kwargs, &block)
+        invoke(false, *args, **kwargs, &block)
+      end
+
+      # Execute the operation with raising an exception on failure.
+      #
+      # @param [Array] args Positional arguments passed.
+      # @param [Hash] kwargs Keyword arguments passed (with optional :context).
+      # @yield [Block] Additional block logic to pass during the operation.
+      # @return [OperationResult] The result of the operation.
+      def call!(*args, **kwargs, &block)
+        invoke(true, *args, **kwargs, &block)
+      end
+
+      private
+
+      # Core execution logic for operations, handling errors and timing.
+      #
+      # @param [Boolean] raise_on_failure Whether to raise exceptions on failure.
+      # @param [Array] args Positional arguments for the operation.
+      # @param [Hash] kwargs Keyword arguments, including optional :context.
+      # @yield [Block] Additional block logic during execution.
+      # @raise [NotImplementedError] If operation type is not set in subclasses.
+      # @return [OperationResult] The result of the operation.
+      def invoke(raise_on_failure, *args, **kwargs, &block)
+        unless result_class
+          raise NotImplementedError, "No result_class defined for #{name} or its ancestors. " \
+                                     "Did you forget to call `use_contract`?"
+        end
+
+        context = kwargs.delete(:context) || {}
+        operation = new(raise_on_failure, context: context)
+        duration, (result, error) = execute(operation, *args, **kwargs, &block)
+
+        operation.logger.debug(context: { duration: duration }) do
+          "Operation completed in #{duration} seconds"
+        end
+
+        result_class.new(error.nil?, result, error, duration: duration, context: context)
+      end
+
+      # Executes the operation logic and handles potential exceptions.
+      #
+      # @param [Gaskit::Operation] operation The instance of the current operation.
+      # @param [Array] args Positional arguments passed.
+      # @param [Hash] kwargs Keyword arguments passed.
+      # @yield [Block] Additional block for the operation.
+      # @return [Array] The execution duration, result, and error if any.
+      def execute(operation, *args, **kwargs, &block)
+        Helpers.time_execution do
+          [operation.call(*args, **kwargs, &block), nil]
+        rescue StandardError => e
+          if e.is_a?(Gaskit::OperationExit)
+            log_exit(operation, e)
+          else
+            log_exception(operation, e)
+            raise e if operation.raise_on_failure
+
+          end
+          [nil, e]
+        end
+      end
+
+      # Logs an early exit from the operation.
+      #
+      # @param [Gaskit::Operation] operation The operation instance.
+      # @param [StandardError] operation_exit The exit error raised.
+      # @return [void]
+      def log_exit(operation, operation_exit)
+        operation.logger.warn { "Exited early: #{operation_exit.key} – #{operation_exit.message}" }
+      end
+
+      # Logs any unhandled exception during the operation.
+      #
+      # @param [Gaskit::Operation] operation The operation instance.
+      # @param [Exception] exception The raised exception.
+      # @return [void]
+      def log_exception(operation, exception)
+        operation.logger.error { "[#{exception.class}] #{exception.message}" }
+        operation.logger.error { exception.backtrace&.join("\n") }
+      end
+
+      # @return [String] The name of the operation class (e.g., "MyOperation").
+      def operation_name
+        @operation_name ||= self.class.name.to_s
+      end
+    end
+
+    attr_reader :raise_on_failure, :context, :logger
+
+    # Initializes a new Gaskit::Operation instance.
+    #
+    # @param [Boolean] raise_on_failure Whether to raise exceptions on failure.
+    # @param [Hash] context Context data for the operation.
+    # @return [void]
+    def initialize(raise_on_failure, context: {})
+      @raise_on_failure = raise_on_failure
+      @context = apply_context(context)
+      @logger = Gaskit::Logger.new(self.class, context: @context)
+    end
+
+    # Applies global context, if set, from Gaskit.configuration.context_provider.
+    #
+    # @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
+      Helpers.deep_compact(default_context.merge(context))
+    end
+
+    # Executes the operation logic.
+    #
+    # @param [Array] args Positional arguments passed.
+    # @param [Hash] kwargs Keyword arguments passed.
+    # @return [void]
+    # @raise [NotImplementedError] Must be implemented by subclasses.
+    def call(*args, **kwargs)
+      raise NotImplementedError, "#{self.class.name} must implement `#call`"
+    end
+
+    # Terminates the operation early with a symbolic key.
+    #
+    # If the key was previously registered via `self.error`, it uses the declared message and code.
+    # Otherwise, it uses the key as the message.
+    #
+    # @param exit_key [Symbol] The symbolic reason for exiting.
+    # @param message [String, nil] Optional message override.
+    # @raise [OperationExit] always raises an instance with message and optional code
+    def exit(exit_key, message = nil)
+      exit_key = exit_key.to_sym
+      definition = self.class.errors_registry[exit_key]
+
+      if definition
+        message ||= definition[:message]
+        code = definition[:code]
+      end
+
+      raise OperationExit.new(exit_key, message, code: code)
+    end
+
+    # @see #exit
+    alias abort exit
+  end
+end

data/lib/gaskit/operation_exit.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Gaskit
+  # OperationExit is a custom exception representing an early exit from an operation.
+  #
+  # It communicates intent-based flow interruption (e.g., authorization failure, validation issue)
+  # and includes a symbolic `key`, optional `message`, and optional `code`.
+  #
+  # @example Raising an OperationExit with just a key
+  #   exit(:unauthorized)
+  #
+  # @example With a custom message and code
+  #   exit(:unauthorized, "Access denied", code: "AUTH-001")
+  #
+  # @example Handling OperationExit in a flow
+  #   begin
+  #     MyFlow.call!
+  #   rescue Gaskit::OperationExit => e
+  #     puts "Exited: #{e.key} - #{e.message} (#{e.code})"
+  #   end
+  class OperationExit < Gaskit::Error
+    # @return [Symbol, String] The symbolic or textual reason for the early exit
+    attr_reader :key
+
+    # @return [String, nil] Optional structured code (e.g., "AUTH-001")
+    attr_reader :code
+
+    # Initializes an OperationExit.
+    #
+    # @param key [Symbol, String] The symbolic exit key
+    # @param message [String, nil] A human-readable message (defaults to key if not provided)
+    # @param code [String, nil] A structured error code for analytics or debugging
+    def initialize(key, message = nil, code: nil)
+      super(message || key.to_s)
+      @key = key
+      @code = code
+    end
+  end
+end