zammad/lib/sequencer/state.rb

# Copyright (C) 2012-2024 Zammad Foundation, https://zammad-foundation.org/

class Sequencer::State
  include ::Mixin::RailsLogger
  include ::Mixin::StartFinishLogger

  def initialize(sequence, parameters: {}, expecting: nil)
    @index        = -1
    @units        = sequence.units
    @result_index = @units.count
    @values       = {}

    initialize_attributes(sequence.units)
    initialize_parameters(parameters)
    initialize_expectations(expecting || sequence.expecting)
  end

  # Stores a value for the given attribute. Value can be a regular object
  # or the result of a given code block.
  # The attribute gets validated against the .provides list of attributes.
  # In the case than an attribute gets provided that is not declared to
  # be provided an exception will be raised.
  #
  # @param [Symbol] attribute the attribute for which the value gets provided.
  # @param [Object] value the value that should get stored for the given attribute.
  # @yield [] executes the given block and takes the result as the value.
  # @yieldreturn [Object] the value for the given attribute.
  #
  # @example
  #  state.provide(:sum, 3)
  #
  # @example
  #  state.provide(:sum) do
  #    some_value = ...
  #    some_value * 3
  #  end
  #
  # @raise [RuntimeError] if the attribute is not provideable from the calling Unit
  #
  # @return [nil]
  def provide(attribute, value = nil)
    if provideable?(attribute)
      value = yield if block_given?
      set(attribute, value)
    else
      value = "UNEXECUTED BLOCK: #{caller(1..1).first}" if block_given?
      unprovideable_setter(attribute, value)
    end
  end

  # Returns the value of the given attribute.
  # The attribute gets validated against the .uses and .optionals
  # lists of attributes. In the case that an attribute gets used
  # that is not declared to be used or optional, an exception
  # gets raised.
  #
  # @param [Symbol] attribute the attribute for which the value is requested.
  #
  # @example
  #  state.use(:answer)
  #  #=> 42
  #
  # @raise [RuntimeError] if the attribute is not useable from the calling Unit
  #
  # @return [nil]
  def use(attribute)
    if useable?(attribute)
      get(attribute)
    else
      unaccessable_getter(attribute)
    end
  end

  # Returns the value of the given attribute.
  # The attribute DOES NOT get validated against the .uses list of attributes.
  # Use this method only in edge cases and prefer .optional macro and state.use otherwise.
  #
  # @param [Symbol] attribute the attribute for which the value is requested.
  #
  # @example
  #  state.optional(:answer)
  #  #=> 42
  #
  # @example
  #  state.optional(:unknown)
  #  #=> nil
  #
  # @return [Object, nil]
  def optional(attribute)
    return get(attribute) if @attributes.known?(attribute)

    logger.public_send(log_level[:optional]) { "Access to unknown optional attribute '#{attribute}'." }
    nil
  end

  # Checks if a value for the given attribute is provided.
  # The attribute DOES NOT get validated against the .uses list of attributes.
  # Use this method only in edge cases and prefer .optional macro and state.use otherwise.
  #
  # @param [Symbol] attribute the attribute which should get checked.
  #
  # @example
  #  state.provided?(:answer)
  #  #=> true
  #
  # @example
  #  state.provided?(:unknown)
  #  #=> false
  #
  # @return [Boolean]
  def provided?(attribute)
    optional(attribute) != nil
  end

  # Unsets the value for the given attribute.
  # The attribute gets validated against the .uses list of attributes.
  # In the case than an attribute gets unset that is not declared
  # to be used an exception will be raised.
  #
  # @param [Symbol] attribute the attribute for which the value gets unset.
  #
  # @example
  #  state.unset(:answer)
  #
  # @raise [RuntimeError] if the attribute is not useable from the calling Unit
  #
  # @return [nil]
  def unset(attribute)
    value = nil
    if useable?(attribute)
      set(attribute, value)
    else
      unprovideable_setter(attribute, value)
    end
  end

  # Handles state processing of the next Unit in the Sequence while executing
  # the given block. After the Unit is processed the state will get cleaned up
  # and no longer needed attribute values will get discarded.
  #
  # @yield [] executes the given block and handles the state changes before and afterwards.
  #
  # @example
  #  state.process do
  #   unit.process
  #  end
  #
  # @return [nil]
  def process
    @index += 1
    yield
    cleanup
  end

  # Handles state processing of the next Unit in the Sequence while executing
  # the given block. After the Unit is processed the state will get cleaned up
  # and no longer needed attribute values will get discarded.
  #
  # @example
  #  state.to_h
  #  #=> {"ssl_verify"=>true, "host"=>"192...", ...}
  #
  # @return [Hash{Symbol => Object}]
  def to_h
    available.index_with { |identifier| @values[identifier] }
  end

  private

  def available
    @attributes.select do |_identifier, attribute|
      @index.between?(attribute.from, attribute.till)
    end.keys
  end

  def unit(index = nil)
    @units[index || @index]
  end

  def provideable?(attribute)
    unit.provides.include?(attribute)
  end

  def useable?(attribute)
    return true if unit.uses.include?(attribute)

    unit.optional.include?(attribute)
  end

  def set(attribute, value)
    logger.public_send(log_level[:set]) { "Setting '#{attribute}' value (#{value.class.name}): #{value.inspect}" }
    @values[attribute] = value
  end

  def get(attribute)
    value = @values[attribute]
    logger.public_send(log_level[:get]) { "Getting '#{attribute}' value (#{value.class.name}): #{value.inspect}" }
    value
  end

  def unprovideable_setter(attribute, value)
    message = "Unprovideable attribute '#{attribute}' set with value (#{value.class.name}): #{value.inspect}"
    logger.error(message)
    raise message
  end

  def unaccessable_getter(attribute)
    message = "Unaccessable getter used for attribute '#{attribute}'"
    logger.error(message)
    raise message
  end

  def initialize_attributes(units)
    log_start_finish(log_level[:attribute_initialization][:start_finish], 'Attributes lifespan initialization') do
      @attributes = Sequencer::Units::Attributes.new(units.declarations)
      logger.public_send(log_level[:attribute_initialization][:attributes]) { "Attributes lifespan: #{@attributes.inspect}" }
    end
  end

  def initialize_parameters(parameters)
    logger.public_send(log_level[:parameter_initialization][:parameters]) { "Initializing Sequencer::State with initial parameters: #{parameters.inspect}" }

    log_start_finish(log_level[:parameter_initialization][:start_finish], 'Attribute value provisioning check and initialization') do

      @attributes.each do |identifier, attribute|

        if !attribute.will_be_used?
          logger.public_send(log_level[:parameter_initialization][:unused]) { "Attribute '#{identifier}' is provided by Unit(s) but never used." }
          next
        end

        init_param    = parameters.key?(identifier)
        provided_attr = attribute.will_be_provided?

        if !init_param && !provided_attr
          next if attribute.optional?

          message = "Attribute '#{identifier}' is used in Unit '#{unit(attribute.to).name}' (index: #{attribute.to}) but is not provided or given via initial parameters."
          logger.error(message)
          raise message
        end

        # skip if attribute is provided by an Unit but not
        # an initial parameter
        next if !init_param

        # update 'from' lifespan information for attribute
        # since it's provided via the initial parameter
        attribute.from = @index

        # set initial value
        set(identifier, parameters[identifier])
      end
    end
  end

  def initialize_expectations(expected_attributes)
    expected_attributes.each do |identifier|
      logger.public_send(log_level[:expectations_initialization]) { "Adding attribute '#{identifier}' to the list of expected result attributes." }
      @attributes[identifier].to = @result_index
    end
  end

  def cleanup
    log_start_finish(log_level[:cleanup][:start_finish], "State cleanup of Unit #{unit.name} (index: #{@index})") do

      @attributes.delete_if do |identifier, attribute|
        remove = !attribute.will_be_used?
        remove ||= attribute.till <= @index
        if remove && attribute.will_be_used?
          logger.public_send(log_level[:cleanup][:remove]) { "Removing unneeded attribute '#{identifier}': #{@values[identifier].inspect}" }
        end
        remove
      end
    end
  end

  def log_level
    @log_level ||= Sequencer.log_level_for(:state)
  end
end