operations 0.0.1 → 0.6.2

data/lib/operations/components/idempotency.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "operations/components/prechecks"
+
+# Contains logic to handle idempotency checks.
+#
+# Idempotency checks are used to skip operation execution in
+# certain conditions.
+#
+# An idempotency check returns a Result monad. If it returns
+# a Failure, the operation body is skipped but the operation
+# is considered successful. The value or failure will be merged
+# to the result context in order to enrich it (the failure should
+# contain something that operation body would return normally
+# to mimic a proper operation call result).
+#
+# Component logs the failed check with `error_reporter`.
+class Operations::Components::Idempotency < Operations::Components::Prechecks
+  def call(params, context)
+    failure, failed_check = process_callables(params, context)
+
+    if failure
+      new_result = result(
+        params: params,
+        context: context.merge(failure.failure)
+      )
+
+      report_failure(new_result, failed_check)
+
+      Failure(new_result)
+    else
+      Success(result(
+        params: params,
+        context: context
+      ))
+    end
+  end
+
+  private
+
+  def process_callables(params, context)
+    failed_check = nil
+    failure = nil
+
+    callable.each do |entry|
+      result = entry.call(params, **context)
+
+      case result
+      when Failure
+        failed_check = entry
+        failure = result
+        break
+      when Success
+        next
+      else
+        raise "Unrecognized result of an idempotency check. Expected Result monad, got #{result.class}"
+      end
+    end
+
+    [failure, failed_check]
+  end
+
+  def report_failure(result, failed_check)
+    info_reporter&.call(
+      "Idempotency check failed",
+      result: result.as_json(include_command: true),
+      failed_check: failed_check.inspect
+    )
+  end
+end

data/lib/operations/components/on_failure.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "operations/components/callback"
+
+# `on_failure` callbacks are called if a command have failed on a stage
+# other than the operation itself or contract. I.e. on policies/preconditions.
+class Operations::Components::OnFailure < Operations::Components::Callback
+  def call(operation_result)
+    callback_context = operation_result.context.merge(operation_failure: operation_result.errors.to_h)
+    results = callable.map do |entry|
+      call_entry(entry, operation_result, **callback_context)
+    end
+
+    maybe_report_failure(:on_failure, operation_result.merge(on_failure: results))
+  end
+end

data/lib/operations/components/on_success.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "operations/components/callback"
+
+# `on_success` callbacks are called when command was successful and implemented
+# to be executed outside the outermost DB transcation (this is configurable
+# but by default AfterCommitEverywhere gem is used).
+# It there is a wrapping transaction (in cases when command is called inside
+# of another command), the inner command result will have empty `on_success`
+# component (since the callbacks will happen when the wparring command is finished).
+class Operations::Components::OnSuccess < Operations::Components::Callback
+  option :after_commit, type: Operations::Types.Interface(:call)
+
+  def call(operation_result)
+    callback_result = after_commit.call do
+      call_entries(operation_result)
+    end
+
+    if callback_result.is_a?(Operations::Result)
+      callback_result
+    else
+      operation_result
+    end
+  end
+
+  private
+
+  def call_entries(operation_result)
+    results = callable.map do |entry|
+      call_entry(entry, operation_result, **operation_result.context)
+    end
+
+    maybe_report_failure(:on_success, operation_result.merge(on_success: results))
+  end
+end

data/lib/operations/components/operation.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "operations/components/base"
+
+# Wraps operation component call to adapt to the further processing.
+class Operations::Components::Operation < Operations::Components::Base
+  PARAMS_FIRST_SIGNATURES = [[:params], [:_params], [:_]].freeze
+
+  def call(params, context)
+    arg_names = call_args(callable, types: %i[req opt])
+
+    operation_result = if PARAMS_FIRST_SIGNATURES.include?(arg_names)
+      callable.call(params, **context)
+    else
+      context_args = context.values_at(*arg_names)
+      callable.call(*context_args, **params)
+    end
+
+    extended_result(operation_result, params: params, context: context)
+  end
+
+  private
+
+  def extended_result(operation_result, params:, context:)
+    result = result(params: params, context: context)
+
+    if operation_result.failure?
+      result.merge(errors: errors(normalize_failure(operation_result.failure)))
+    elsif operation_result.value!.is_a?(Hash)
+      result.merge(context: context.merge(operation_result.value!))
+    elsif operation_result.value!.is_a?(Dry::Monads::Unit)
+      result
+    else
+      raise "Unexpected operation body result. Expected Hash, got #{operation_result.value!.class}"
+    end
+  end
+end

data/lib/operations/components/policies.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "operations/components/prechecks"
+
+# We are looking for the first policy failure to return because
+# it does not make sense to check for all policy failures. One is
+# more than enough to know that we are not allowed to call the operation.
+#
+# If policy returns `false` then generic `:unauthorized` error
+# code will be used. In case of `Failure` monad - the error code depends
+# on the failure internal value. It can be a String, Symbol or even
+# a Hash containing `:error` key.
+#
+# Successful policies return either `true` or `Success` monad.
+class Operations::Components::Policies < Operations::Components::Prechecks
+  def call(params, context)
+    first_failure = callable.lazy.filter_map do |entry|
+      result_failure(entry.call(**context), entry)
+    end.first
+
+    result(
+      params: params,
+      context: context,
+      errors: errors(normalize_failure([first_failure].compact))
+    )
+  end
+
+  private
+
+  def result_failure(result, entry)
+    case result
+    when true, Success
+      nil
+    when Failure
+      result.failure
+    when false
+      :unauthorized
+    else
+      raise "Unexpected policy result: #{result} for #{entry}"
+    end
+  end
+end

data/lib/operations/components/prechecks.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "operations/components/base"
+
+# Contains common logic for policies and preconditions.
+class Operations::Components::Prechecks < Operations::Components::Base
+  param :callable, type: Operations::Types::Array.of(Operations::Types.Interface(:call))
+
+  def callable?(context)
+    (required_context - context.keys).empty?
+  end
+
+  def required_context
+    @required_context ||= required_kwargs | context_keys
+  end
+
+  private
+
+  def context_keys
+    keys = callable.flat_map do |entry|
+      if entry.respond_to?(:context_key)
+        [entry.context_key]
+      elsif entry.respond_to?(:context_keys)
+        entry.context_keys
+      else
+        []
+      end
+    end
+
+    keys.map(&:to_sym)
+  end
+
+  def required_kwargs
+    callable.flat_map do |entry|
+      call_args(entry, types: %i[keyreq])
+    end.uniq
+  end
+end

data/lib/operations/components/preconditions.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "operations/components/prechecks"
+
+# We check all the precondition failures to return all the codes to
+# the user at once. This provides a better UX, user is able to fix
+# everything at once instead of getting messages one by one. This is
+# similar to the idea of validations.
+#
+# Precondition can return a Symbol - it will be used as an error code.
+# If String is returned - it will be used as a message itself. Please
+# avoid returning string, use i18n instead. Hash with `:error` key
+# will be also treated as a failure ans used accordingly. Also, `Failure`
+# monad gets unwrapped and the value follows the rules above. Also, it is
+# possible to return an array of failures.
+#
+# Successful preconditions returns either nil or an empty array or a
+# `Success` monad.
+class Operations::Components::Preconditions < Operations::Components::Prechecks
+  def call(params, context)
+    failures = callable.flat_map do |entry|
+      results = Array.wrap(entry.call(**context))
+      results.filter_map { |result| result_failure(result) }
+    end
+
+    result(
+      params: params,
+      context: context,
+      errors: errors(normalize_failure(failures))
+    )
+  end
+
+  private
+
+  def result_failure(result)
+    case result
+    when nil, Success
+      nil
+    when Failure
+      result.failure
+    else
+      result
+    end
+  end
+end

data/lib/operations/components.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# A namespace for operation component adapters
+module Operations::Components
+end

data/lib/operations/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+# The framework's configuration shared between all the commands.
+#
+# @see Operations.default_config
+class Operations::Configuration < Dry::Struct
+  schema schema.strict
+
+  attribute :info_reporter?, Operations::Types.Interface(:call).optional
+  attribute :error_reporter?, Operations::Types.Interface(:call).optional
+  attribute :transaction, Operations::Types.Interface(:call)
+  attribute :after_commit, Operations::Types.Interface(:call)
+end

data/lib/operations/contract/messages_resolver.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Patching the default messages resolver to append `:code` meta
+# to every message produced.
+class Operations::Contract::MessagesResolver < Dry::Validation::Messages::Resolver
+  def call(message:, meta: Dry::Schema::EMPTY_HASH, **rest)
+    meta = meta.merge(code: message) if message.is_a?(Symbol)
+
+    super(message: message, meta: meta, **rest)
+  end
+end

data/lib/operations/contract.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Just a base contract with i18n set up and a bunch of useful macro.
+class Operations::Contract < Dry::Validation::Contract
+  option :message_resolver, default: -> { Operations::Contract::MessagesResolver.new(messages) }
+
+  # config.messages.backend = :i18n
+  config.messages.top_namespace = "operations"
+
+  def self.inherited(subclass)
+    super
+
+    return unless subclass.name
+
+    namespace = subclass.name.underscore.split("/")[0..-2].join("/")
+    subclass.config.messages.namespace = namespace
+  end
+
+  def self.prepend_rule(...)
+    rule(...)
+    rules.unshift(rules.pop)
+  end
+
+  def self.ensure_presence(context_key, field: "#{context_key}_id", optional: false)
+    rule do |context:|
+      next if context[context_key] || schema_error?(field)
+
+      if key?(field)
+        key(field).failure(:not_found)
+      elsif !optional
+        key(field).failure(:key?)
+      end
+    end
+  end
+
+  def call(input, **initial_context)
+    super(input, initial_context)
+  end
+end

data/lib/operations/convenience.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# This module helps to follow conventions. Work best with
+# {Operations::Command.build}
+#
+# Unders the hood it defines classes in accordance to the
+# nesting convenience. It is always possible to use this module
+# along with the manually crafted components if necessary.
+#
+# @example
+#
+#   class Namespace::OperationName
+#     extend Operations::Convenience
+#
+#     contract do
+#       params { ... }
+#       rule(...) { ... }
+#     end
+#
+#     policy do |current_user, **|
+#       current_user.is_a?(Superuser) && ...
+#     end
+#
+#     def call(context_value1, context_value2, **params)
+#       ...
+#     end
+#   end
+#
+# @see Operations::Command.build
+#
+# Also, if this class is used as a container to cache the command
+# instance under some name, this module will provide a method missing
+# to call the command with `#call!` method using the `#call` method
+# as an interface.
+#
+# @example
+#
+#   class Namespace::OperationName
+#     extend Operations::Convenience
+#
+#     def self.default
+#       Operations::Command.new(...)
+#     end
+#   end
+#
+#   # A normall command call
+#   Namespace::OperationName.default.call(...)
+#   # Raises exception in case of failure
+#   Namespace::OperationName.default.call!(...)
+#   # Acts exactly the same way as the previous one
+#   # but notice where the bang is.
+#   Namespace::OperationName.default!.call(...)
+#
+# This is especially convenient when you have a DSL that
+# expects some object responding to `#call` method but you want
+# to raise an exception. In this case you would just pass
+# `Namespace::OperationName.default!` into it.
+#
+module Operations::Convenience
+  def self.extended(mod)
+    mod.include Dry::Monads[:result]
+    mod.include Dry::Monads::Do.for(:call)
+    mod.extend Dry::Initializer
+  end
+
+  def method_missing(name, *args, **kwargs, &block)
+    name_without_suffix = name.to_s.delete_suffix("!").to_sym
+    if name.to_s.end_with?("!") && respond_to?(name_without_suffix)
+      public_send(name_without_suffix, *args, **kwargs, &block).method(:call!)
+    else
+      super
+    end
+  end
+
+  def respond_to_missing?(name, *)
+    (name.to_s.end_with?("!") && respond_to?(name.to_s.delete_suffix("!").to_sym)) || super
+  end
+
+  def contract(prefix = nil, from: OperationContract, &block)
+    contract = Class.new(from)
+    contract.config.messages.namespace = name.underscore
+    contract.class_eval(&block)
+    const_set("#{prefix.to_s.camelize}Contract", contract)
+  end
+
+  %w[policy precondition callback].each do |kind|
+    define_method kind do |prefix = nil, from: Object, &block|
+      raise ArgumentError.new("Please provide either a superclass or a block for #{kind}") unless from || block
+
+      klass = Class.new(from)
+
+      if from == Object
+        klass.extend(Dry::Initializer)
+        klass.include(Dry::Monads[:result])
+      end
+
+      klass.define_method(:call, &block) if block
+
+      const_set("#{prefix.to_s.camelize}#{kind.camelize}", klass)
+    end
+  end
+end

data/lib/operations/form/attribute.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# The main purpose is to infer attribute properties from the
+# related model. We need it to automate form rendering for the
+# legacy UI.
+class Operations::Form::Attribute
+  extend Dry::Initializer
+  include Dry::Equalizer(:name, :collection, :form, :model_name)
+
+  param :name, type: Operations::Types::Coercible::Symbol
+  option :collection, type: Operations::Types::Bool, optional: true, default: proc { false }
+  option :form, type: Operations::Types::Class, optional: true
+  option :model_name,
+    type: Operations::Types::String | Operations::Types.Instance(Class).constrained(lt: ActiveRecord::Base),
+    optional: true
+
+  def model_type
+    @model_type ||= owning_model.type_for_attribute(string_name) if model_name
+  end
+
+  def model_human_name(options = {})
+    owning_model.human_attribute_name(string_name, options) if model_name
+  end
+
+  def model_validators
+    @model_validators ||= model_name ? owning_model.validators_on(string_name) : []
+  end
+
+  def model_localized_attr_name(locale)
+    owning_model.localized_attr_name_for(string_name, locale) if model_name
+  end
+
+  private
+
+  def owning_model
+    @owning_model ||= model_name.is_a?(String) ? model_name.constantize : model_name
+  end
+
+  def string_name
+    @string_name ||= name.to_s
+  end
+end

data/lib/operations/form/builder.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# Traverses the passed {Dry::Schema::KeyMap} and generates
+# {Operations::Form} classes on the fly. Handles nested structures.
+#
+# @see Operations::Form
+class Operations::Form::Builder
+  extend Dry::Initializer
+
+  NESTED_ATTRIBUTES_SUFFIX = %r{_attributes\z}.freeze
+
+  option :base_class, Operations::Types::Instance(Class)
+
+  def build(key_map:, namespace:, class_name:, model_map:)
+    return namespace.const_get(class_name) if namespace && class_name && namespace.const_defined?(class_name)
+
+    traverse(key_map, namespace, class_name, model_map, [])
+  end
+
+  private
+
+  def traverse(key_map, namespace, class_name, model_map, path)
+    form = Class.new(base_class)
+    namespace.const_set(class_name, form) if namespace && class_name
+
+    key_map.each do |key|
+      key_path = path + [key.name]
+
+      case key
+      when Dry::Schema::Key::Array
+        nested_form = traverse(key.member, form, key.name.to_s.underscore.classify, model_map, key_path)
+        form.attribute(key.name, form: nested_form, collection: true, **model_name(key_path, model_map))
+      when Dry::Schema::Key::Hash
+        traverse_hash(form, key, model_map, path)
+      when Dry::Schema::Key
+        form.attribute(key.name, **model_name(key_path, model_map))
+      else
+        raise "Unknown key_map key: #{key.class}"
+      end
+    end
+
+    form
+  end
+
+  def traverse_hash(form, hash_key, model_map, path)
+    nested_attributes_suffix = hash_key.name.match?(NESTED_ATTRIBUTES_SUFFIX)
+    nested_attributes_collection = hash_key.members.all?(Dry::Schema::Key::Hash) &&
+      hash_key.members.map(&:members).uniq.size == 1
+
+    name, members, collection = specify_form_attributes(
+      hash_key,
+      nested_attributes_suffix,
+      nested_attributes_collection
+    )
+    form.define_method "#{hash_key.name}=", proc { |attributes| attributes } if nested_attributes_suffix
+
+    key_path = path + [name]
+    nested_form = traverse(members, form, name.underscore.camelize, model_map, key_path)
+    form.attribute(name, form: nested_form, collection: collection, **model_name(key_path, model_map))
+  end
+
+  def specify_form_attributes(hash_key, nested_attributes_suffix, nested_attributes_collection)
+    if nested_attributes_suffix && !nested_attributes_collection
+      [hash_key.name.gsub(NESTED_ATTRIBUTES_SUFFIX, ""), hash_key.members, false]
+    elsif nested_attributes_suffix && nested_attributes_collection
+      [hash_key.name.gsub(NESTED_ATTRIBUTES_SUFFIX, ""), hash_key.members.first.members, true]
+    else
+      [hash_key.name, hash_key.members, false]
+    end
+  end
+
+  def model_name(path, model_map)
+    _, model_name = model_map.find do |pathspec, _model|
+      path.size == pathspec.size && path.zip(pathspec).all? do |slug, pattern|
+        pattern.is_a?(Regexp) ? pattern.match?(slug) : slug == pattern
+      end
+    end
+
+    if model_name
+      { model_name: model_name }
+    else
+      {}
+    end
+  end
+end