next_station 0.1.0

data/TODO.txt

@@ -0,0 +1,6 @@
+DONE - Force return of state inside the defs
+DONE - Custom Error class for state not set: spec/contract/basic_flows/success_should_return_exception_if_no_success_key_spec.rb
+DONE - install rubocop?
+TODO - Raise exception if a step does not have a "def",
+TODO: - Should "state[:result]" be created by default when ".new"?
+DONE - " config.messages.backend = :i18n" In the validation section of the README is no valid dry-validation code.

data/examples/plugin_http_example.rb

@@ -0,0 +1,102 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require_relative '../lib/next_station'
+
+# --- The Plugin Definition ---
+module HttpClientPlugin
+  module ClassMethods
+    def self.extended(base)
+      base.extend Dry::Configurable
+      base.instance_eval do
+        setting :http_client do
+          setting :base_url, default: "https://example.com"
+          setting :timeout, default: 5
+        end
+      end
+    end
+  end
+
+  module InstanceMethods
+    def http_get(path)
+      uri = URI.parse(self.class.config.http_client.base_url)
+      uri = URI.join(uri, path)
+      
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+      http.read_timeout = self.class.config.http_client.timeout
+      
+      request = Net::HTTP::Get.new(uri)
+      http.request(request)
+    rescue StandardError => e
+      # In a real plugin, we would use error definitions, 
+      # but for this example, we'll return a minimal object
+      Struct.new(:code, :body).new("500", e.message)
+    end
+  end
+
+  module State
+    def response_received?
+      !self[:response].nil?
+    end
+
+    def last_response_code
+      self[:response]&.code
+    end
+  end
+end
+
+# Register the plugin manually for this standalone test
+NextStation::Plugins.register(:http_client, HttpClientPlugin)
+
+# --- The Operation Definition ---
+class FetchExamplePage < NextStation::Operation
+  plugin :http_client
+
+  # Configure the plugin
+  config.http_client.base_url = "https://www.example.com"
+  config.http_client.timeout = 10
+
+  # Tell NextStation where to find the result in the state
+  result_at :content_length
+
+  process do
+    step :call_api
+    step :process_response
+  end
+
+  def call_api(state)
+    publish_log :info, "Calling API with: #{self.class.config.http_client.base_url}"
+    response = http_get("/")
+    state[:response] = response
+    state
+  end
+
+  def process_response(state)
+    # Using the State extension defined in the plugin
+    if state.response_received? && state.last_response_code == "200"
+      publish_log :info, "Success! Response code: #{state.last_response_code}"
+      publish_log :info, "Body length: #{state[:response].body.length}"
+      # In NextStation, you just return the state (or a hash that will be merged into state)
+      # To signal success with data, the operation's result_key must match what we return or what's in state.
+      state[:content_length] = state[:response].body.length
+      state
+    else
+      puts "Failed! Response code: #{state.last_response_code || 'N/A'}"
+      # If we want to fail explicitly, we can use error! or just return something that isn't state/success
+      error!(type: :api_error, details: { message: "Response was #{state.last_response_code}" })
+    end
+  end
+end
+
+# --- Execution ---
+puts "Starting Operation..."
+result = FetchExamplePage.call
+
+puts "\nFinal Result: #{result.success? ? 'SUCCESS' : 'FAILURE'}"
+if result.success?
+  puts "Value: #{result.value.inspect}"
+else
+  puts "Error: #{result.error.inspect}"
+  puts "Details: #{result.error.details.inspect}" if result.error.respond_to?(:details)
+end

data/lib/next_station/config/errors.yml

@@ -0,0 +1,149 @@
+en:
+  next_station_validations:
+    or: "or"
+    errors:
+      unexpected_key: "is not allowed"
+      array?: "must be an array"
+      empty?: "must be empty"
+      excludes?: "must not include %{value}"
+      excluded_from?:
+        arg:
+          default: "must not be one of: %{list}"
+          range: "must not be one of: %{list_left} - %{list_right}"
+      exclusion?: "must not be one of: %{list}"
+      eql?: "must be equal to %{left}"
+      not_eql?: "must not be equal to %{left}"
+      filled?: "must be filled"
+      format?: "is in invalid format"
+      number?: "must be a number"
+      odd?: "must be odd"
+      even?: "must be even"
+      gt?: "must be greater than %{num}"
+      gteq?: "must be greater than or equal to %{num}"
+      hash?: "must be a hash"
+      included_in?:
+        arg:
+          default: "must be one of: %{list}"
+          range: "must be one of: %{list_left} - %{list_right}"
+      inclusion?: "must be one of: %{list}"
+      includes?: "must include %{value}"
+      bool?: "must be boolean"
+      true?: "must be true"
+      false?: "must be false"
+      int?: "must be an integer"
+      float?: "must be a float"
+      decimal?: "must be a decimal"
+      date?: "must be a date"
+      date_time?: "must be a date time"
+      time?: "must be a time"
+      key?: "is missing"
+      attr?: "is missing"
+      lt?: "must be less than %{num}"
+      lteq?: "must be less than or equal to %{num}"
+      max_size?: "size cannot be greater than %{num}"
+      max_bytesize?: "bytesize cannot be greater than %{num}"
+      min_size?: "size cannot be less than %{num}"
+      min_bytesize?: "bytesize cannot be less than %{num}"
+      nil?: "cannot be defined"
+      str?: "must be a string"
+      type?: "must be %{type}"
+      respond_to?: "must respond to %{method}"
+      size?:
+        arg:
+          default: "size must be %{size}"
+          range: "size must be within %{size_left} - %{size_right}"
+        value:
+          string:
+            arg:
+              default: "length must be %{size}"
+              range: "length must be within %{size_left} - %{size_right}"
+      bytesize?:
+        arg:
+          default: "must be %{size} bytes long"
+          range: "must be within %{size_left} - %{size_right} bytes long"
+      uri?: "is not a valid URI"
+      uuid_v1?: "is not a valid UUID"
+      uuid_v2?: "is not a valid UUID"
+      uuid_v3?: "is not a valid UUID"
+      uuid_v4?: "is not a valid UUID"
+      uuid_v5?: "is not a valid UUID"
+      uuid_v6?: "is not a valid UUID"
+      uuid_v7?: "is not a valid UUID"
+      uuid_v8?: "is not a valid UUID"
+      not:
+        empty?: "cannot be empty"
+
+sp:
+  next_station_validations:
+    or: "o"
+    errors:
+      unexpected_key: "no está permitido"
+      array?: "debe ser un arreglo"
+      empty?: "debe estar vacío"
+      excludes?: "no debe incluir %{value}"
+      excluded_from?:
+        arg:
+          default: "no debe ser uno de: %{list}"
+          range: "no debe ser uno de: %{list_left} - %{list_right}"
+      exclusion?: "no debe ser uno de: %{list}"
+      eql?: "debe ser igual a %{left}"
+      not_eql?: "no debe ser igual a %{left}"
+      filled?: "debe estar lleno"
+      format?: "tiene un formato inválido"
+      number?: "debe ser un número"
+      odd?: "debe ser impar"
+      even?: "debe ser par"
+      gt?: "debe ser mayor que %{num}"
+      gteq?: "debe ser mayor o igual que %{num}"
+      hash?: "debe ser un hash"
+      included_in?:
+        arg:
+          default: "debe ser uno de: %{list}"
+          range: "debe ser uno de: %{list_left} - %{list_right}"
+      inclusion?: "debe ser uno de: %{list}"
+      includes?: "debe incluir %{value}"
+      bool?: "debe ser booleano"
+      true?: "debe ser verdadero"
+      false?: "debe ser falso"
+      int?: "debe ser un número entero"
+      float?: "debe ser un número flotante"
+      decimal?: "debe ser un número decimal"
+      date?: "debe ser una fecha"
+      date_time?: "debe ser una fecha y hora"
+      time?: "debe ser una hora"
+      key?: "está ausente"
+      attr?: "está ausente"
+      lt?: "debe ser menor que %{num}"
+      lteq?: "debe ser menor o igual que %{num}"
+      max_size?: "el tamaño no puede ser mayor que %{num}"
+      max_bytesize?: "el tamaño en bytes no puede ser mayor que %{num}"
+      min_size?: "el tamaño no puede ser menor que %{num}"
+      min_bytesize?: "el tamaño en bytes no puede ser menor que %{num}"
+      nil?: "no puede estar definido"
+      str?: "debe ser una cadena de texto"
+      type?: "debe ser %{type}"
+      respond_to?: "debe responder al método %{method}"
+      size?:
+        arg:
+          default: "el tamaño debe ser %{size}"
+          range: "el tamaño debe estar entre %{size_left} y %{size_right}"
+        value:
+          string:
+            arg:
+              default: "la longitud debe ser %{size}"
+              range: "la longitud debe estar entre %{size_left} y %{size_right}"
+      bytesize?:
+        arg:
+          default: "debe tener %{size} bytes de longitud"
+          range: "debe tener entre %{size_left} y %{size_right} bytes de longitud"
+      uri?: "no es un URI válido"
+      uuid_v1?: "no es un UUID válido"
+      uuid_v2?: "no es un UUID válido"
+      uuid_v3?: "no es un UUID válido"
+      uuid_v4?: "no es un UUID válido"
+      uuid_v5?: "no es un UUID válido"
+      uuid_v6?: "no es un UUID válido"
+      uuid_v7?: "no es un UUID válido"
+      uuid_v8?: "no es un UUID válido"
+      not:
+        empty?: "no puede estar vacío"

data/lib/next_station/config.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'dry-configurable'
+require 'dry-monitor'
+require 'logger'
+require_relative 'environment'
+require_relative 'logging/formatters/json'
+require_relative 'logging/formatters/console'
+
+module NextStation
+  extend Dry::Configurable
+
+  # Define the environment
+  setting :environment, default: Environment.new, constructor: ->(v) {
+    if v.is_a?(String)
+      env = Environment.new
+      env.current = v
+      env
+    else
+      v
+    end
+  }
+
+  # Define the monitor
+  setting :monitor, default: (
+    monitor = Dry::Monitor::Notifications.new(:next_station)
+    monitor.register_event('operation.start')
+    monitor.register_event('operation.stop')
+    monitor.register_event('step.start')
+    monitor.register_event('step.stop')
+    monitor.register_event('step.retry')
+    monitor.register_event('log.custom')
+    monitor
+  )
+
+  # Define the default logger (STDOUT)
+  setting :logger, default: Logger.new($stdout)
+
+  # Enable/disable default logging subscribers
+  setting :logging_enabled, default: true
+
+  # Default logging level (:info, :debug)
+  setting :logging_level, default: :info
+end
+
+require_relative 'logging'
+
+# Automatically setup logging if enabled
+NextStation::Logging.setup! if NextStation.config.logging_enabled

data/lib/next_station/environment.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module NextStation
+  # Detects the current environment (e.g., development, production)
+  # based on a configurable set of environment variables.
+  class Environment
+    attr_accessor :env_vars, :production_names, :development_names
+    attr_writer :current
+
+    def initialize
+      # A list of common environment variables to check for the environment name.
+      @env_vars = %w[RAILS_ENV RACK_ENV APP_ENV RUBY_ENV]
+      
+      # Names that are considered to be a "production" environment.
+      @production_names = %w[production prod prd]
+      
+      # Names that are considered to be a "development" environment.
+      @development_names = %w[development dev]
+      
+      # Manually set environment name.
+      @current = nil
+    end
+
+    # Returns the current environment name. Defaults to 'development' if none is found.
+    # @return [String]
+    def current
+      @current || env_vars.map { |var| ENV[var] }.compact.first || 'development'
+    end
+
+    # Checks if the current environment is production.
+    # @return [Boolean]
+    def production?
+      production_names.include?(current)
+    end
+
+    # Checks if the current environment is development.
+    # @return [Boolean]
+    def development?
+      development_names.include?(current)
+    end
+  end
+end

data/lib/next_station/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module NextStation
+  class Errors
+    def self.inherited(subclass)
+      super
+      subclass.extend(SharedErrorsDSL)
+    end
+
+    module SharedErrorsDSL
+      def error_type(type, &block)
+        @dsl ||= NextStation::Operation::ErrorsDSL.new
+        @dsl.error_type(type, &block)
+      end
+
+      def definitions
+        @dsl&.definitions || {}
+      end
+    end
+  end
+end

data/lib/next_station/logging/formatters/console.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module NextStation
+  module Logging
+    module Formatter
+      class Console < Logger::Formatter
+        # ANSI color codes
+        SEVERITY_COLORS = {
+          "DEBUG" => "\e[36m", # cyan
+          "INFO"  => "\e[32m", # green
+          "WARN"  => "\e[33m", # yellow
+          "ERROR" => "\e[31m", # red
+          "FATAL" => "\e[35m"  # magenta
+        }.freeze
+
+        OPERATION_COLOR = "\e[34m" # blue
+        STEP_COLOR      = "\e[90m" # gray
+        RESET_COLOR     = "\e[0m"
+
+        def call(severity, datetime, _progname, msg)
+          msg = msg.is_a?(Hash) ? msg : { message: msg.to_s }
+
+          operation = msg[:operation]
+          step_name = msg[:step_name] ? "/#{msg[:step_name]}" : ""
+          payload   = msg[:payload] unless msg[:payload].to_h.empty?
+
+          sev  = "#{SEVERITY_COLORS[severity]}#{severity[0]}#{RESET_COLOR}"
+          op   = "#{OPERATION_COLOR}#{operation}#{RESET_COLOR}"
+          step = step_name.empty? ? "" : "#{STEP_COLOR}#{step_name}#{RESET_COLOR}"
+
+          "[#{sev}][#{datetime.strftime('%Y-%m-%d %H:%M:%S')}][#{op}#{step}] -- #{msg[:message]} #{payload}\n"
+        end
+      end
+    end
+  end
+end

data/lib/next_station/logging/formatters/json.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'json'
+
+module NextStation
+  module Logging
+    module Formatter
+      # A custom logger formatter that outputs log entries as JSON objects.
+      #
+      # This formatter is designed to work with the standard `Logger` class.
+      # It structures log messages into a JSON format that includes severity, timestamp,
+      # process ID, and structured data from the operation. It also automatically
+      # includes OpenTelemetry trace and span IDs if the `opentelemetry-sdk` is present.
+      class Json < Logger::Formatter
+        # Avoid repeated defined? calls in a hot path
+        OTEL_AVAILABLE = defined?(::OpenTelemetry::Trace)
+
+        # Formats the log entry into a JSON string.
+        #
+        # @param severity [String] The log severity (e.g., 'INFO', 'WARN').
+        # @param time [Time] The timestamp of the log event.
+        # @param _progname [String] The program name (unused).
+        # @param msg [String, Hash] The log message. If a Hash, it is treated as
+        #   structured data with keys like `:message`, `:payload`, and `:operation`.
+        #   If a String, it becomes the value of the `:message` key.
+        # @return [String] The formatted log entry as a JSON string, terminated
+        #   with a newline character.
+        def call(severity, time, _progname, msg)
+          data = msg.is_a?(Hash) ? msg : { message: msg.to_s }
+
+          log_entry = {
+            level: severity,
+            time: time.utc.strftime('%Y-%m-%dT%H:%M:%S.%6N'),
+            pid: Process.pid,
+            origin: build_origin(data),
+            message: data[:message]
+          }
+
+          add_payload_to_log_entry(log_entry, data) if data[:payload]
+
+          add_otel_context(log_entry) if OTEL_AVAILABLE
+
+          # Compact the hash to remove nil values and ensure a newline
+          JSON.generate(log_entry.compact) << "\n"
+        end
+
+        private
+
+        # Adds the payload to the log entry if it is not empty.
+        def add_payload_to_log_entry(log_entry, data)
+          return unless data[:payload]
+
+          log_entry[:payload] = data[:payload] unless data[:payload].empty?
+        end
+
+        # Constructs the origin hash, returning nil if no origin data is present.
+        # This prevents an empty "origin": {} from appearing in the logs.
+        def build_origin(data)
+          origin = {}
+          origin[:operation] = data[:operation] if data[:operation]
+          origin[:event] = data[:event_kind] if data[:event_kind]
+          origin[:step_name] = data[:step_name] if data[:step_name]
+          origin[:step_attempt] = data[:step_attempt] if data[:step_attempt]
+
+          origin.empty? ? nil : origin
+        end
+
+        # Adds OpenTelemetry trace and span IDs to the log entry if available.
+        def add_otel_context(log_entry)
+          context = ::OpenTelemetry::Trace.current_span.context
+          if context.valid?
+            log_entry[:trace_id] = context.hex_trace_id
+            log_entry[:span_id] = context.hex_span_id
+          end
+        end
+      end
+    end
+  end
+end

data/lib/next_station/logging/subscribers/base.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module NextStation
+  module Logging
+    module Subscribers
+      # @api private
+      class Base
+        # Map levels to their numeric priority for comparison.
+        LEVELS = {
+          debug: 0,
+          info: 1,
+          warn: 2,
+          error: 3,
+          fatal: 4,
+          unknown: 5
+        }.freeze
+
+        # Subscribes a new instance to the monitor.
+        # @param monitor [Dry::Monitor::Notifications]
+        def self.subscribe(monitor)
+          new.subscribe(monitor)
+        end
+
+        # Subscribes to the event(s) in the monitor.
+        # @param monitor [Dry::Monitor::Notifications]
+        def subscribe(monitor)
+          raise NotImplementedError
+        end
+
+        protected
+
+        # Default log level if none is provided in the event.
+        # @return [Symbol]
+        def default_level
+          :info
+        end
+
+        # Logs the event data to the configured logger.
+        # @param event [Dry::Monitor::Event]
+        # @param level [Symbol, nil] Explicit level, or derived from event/default.
+        # @param extra_data [Hash] Additional data to merge into the log entry.
+        def log_event(event, level: nil, extra_data: {})
+          # Add this check to respect `config.logging_enabled = false`
+          return unless NextStation.config.logging_enabled
+
+          event_data = event.to_h
+          log_level = level || event_data.delete(:level) || default_level
+
+          # Filter by logging_level
+          return unless level_sufficient?(log_level)
+
+          # Merge data while preserving the original event data
+          payload = event_data.merge(extra_data)
+
+          # We pass the whole hash. The Formatter will pick what it needs.
+          NextStation.config.logger.send(log_level, payload)
+        end
+
+        private
+
+        # @param log_level [Symbol] The level of the current log event.
+        # @return [Boolean] True if the log level is equal or higher than configured.
+        def level_sufficient?(log_level)
+          configured_level = NextStation.config.logging_level
+          LEVELS.fetch(log_level, 1) >= LEVELS.fetch(configured_level, 1)
+        end
+      end
+    end
+  end
+end

data/lib/next_station/logging/subscribers/custom.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module NextStation
+  module Logging
+    module Subscribers
+      # Subscriber for custom log events manually triggered.
+      # @api private
+      class Custom < Base
+        # @param monitor [Dry::Monitor::Notifications]
+        def subscribe(monitor)
+          monitor.subscribe('log.custom') { |event| on_custom(event) }
+        end
+
+        # @param event [Dry::Monitor::Event]
+        def on_custom(event)
+          log_event(event, extra_data: {
+            event_kind: 'log.custom'
+          })
+        end
+      end
+    end
+  end
+end

data/lib/next_station/logging/subscribers/operation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module NextStation
+  module Logging
+    module Subscribers
+      # Subscriber for operation lifecycle events.
+      # @api private
+      class Operation < Base
+        # @param monitor [Dry::Monitor::Notifications]
+        def subscribe(monitor)
+          monitor.subscribe('operation.start') { |event| on_start(event) }
+          monitor.subscribe('operation.stop') { |event| on_stop(event) }
+        end
+
+        # @param event [Dry::Monitor::Event]
+        def on_start(event)
+          log_event(event, extra_data: {
+            message: "Started operation: #{event[:operation]}",
+            event_kind: 'operation.start'
+          })
+        end
+
+        # @param event [Dry::Monitor::Event]
+        def on_stop(event)
+          result_status = event[:result].success? ? 'success' : 'failure'
+          
+          log_event(event, extra_data: {
+            message: "completed operation: #{event[:operation]} with #{result_status}",
+            event_kind: 'operation.stop',
+            payload: {
+              duration: event[:duration],
+              result: result_status
+            }
+          })
+        end
+      end
+    end
+  end
+end

data/lib/next_station/logging/subscribers/step.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module NextStation
+  module Logging
+    module Subscribers
+      # Subscriber for step lifecycle events.
+      # @api private
+      class Step < Base
+        # @param monitor [Dry::Monitor::Notifications]
+        def subscribe(monitor)
+          monitor.subscribe('step.start') { |event| on_start(event) }
+          monitor.subscribe('step.stop') { |event| on_stop(event) }
+          monitor.subscribe('step.retry') { |event| on_retry(event) }
+        end
+
+        # @param event [Dry::Monitor::Event]
+        def on_start(event)
+          log_event(event, level: :debug, extra_data: {
+            message: "Started step: #{event[:step]} in #{event[:operation]}",
+            event_kind: 'step.start',
+            step_name: event[:step],
+            operation: event[:operation]
+          })
+        end
+
+        # @param event [Dry::Monitor::Event]
+        def on_stop(event)
+          log_event(event, level: :debug, extra_data: {
+            message: "Completed step: #{event[:step]} in #{event[:operation]}",
+            event_kind: 'step.stop',
+            step_name: event[:step],
+            operation: event[:operation],
+            payload: {
+              duration: event[:duration]
+            }
+          })
+        end
+
+        # @param event [Dry::Monitor::Event]
+        def on_retry(event)
+          log_event(event, level: :warn, extra_data: {
+            message: "Retrying step: #{event[:step]} (attempt #{event[:attempt]})",
+            event_kind: 'step.retry',
+            step_name: event[:step],
+            operation: event[:operation],
+            step_attempt: event[:attempt]
+          })
+        end
+      end
+    end
+  end
+end