rails_ops 1.0.0.beta1

data/lib/rails_ops/mixins/policies.rb

@@ -0,0 +1,42 @@
+# Mixin for the {RailsOps::Operation} class that provides *policies*. Policies
+# are simple blocks of code that run at specific places in your operation and
+# can be used to check conditions such as params or permissions. Policies are
+# inherited to subclasses of operations.
+module RailsOps::Mixins::Policies
+  extend ActiveSupport::Concern
+
+  POLICY_CHAIN_KEYS = [:on_init, :before_perform, :after_perform].freeze
+
+  included do
+    class_attribute :_policy_chains
+    self._policy_chains = Hash[POLICY_CHAIN_KEYS.map { |key| [key, [].freeze] }]
+  end
+
+  module ClassMethods
+    # Register a new policy block that will be executed in the given `chain`.
+    # The policy block will be executed in the operation's instance context.
+    def policy(chain = :before_perform, &block)
+      unless POLICY_CHAIN_KEYS.include?(chain)
+        fail "Unknown policy chain #{chain.inspect}, available are #{POLICY_CHAIN_KEYS.inspect}."
+      end
+
+      self._policy_chains = _policy_chains.dup
+      _policy_chains[chain] += [block]
+    end
+
+    # Returns all registered validation blocks for this operation class.
+    def policies_for(chain)
+      unless POLICY_CHAIN_KEYS.include?(chain)
+        fail "Unknown policy chain #{chain.inspect}, available are #{POLICY_CHAIN_KEYS.inspect}."
+      end
+
+      return _policy_chains[chain]
+    end
+  end
+
+  def run_policies(chain)
+    self.class.policies_for(chain).each do |block|
+      instance_eval(&block)
+    end
+  end
+end

data/lib/rails_ops/mixins/require_context.rb

@@ -0,0 +1,33 @@
+# Mixin for the {RailsOps::Operation} class that provides *require_context*.
+module RailsOps::Mixins::RequireContext
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    # This DSL method allows you to make sure that a context is provided to your
+    # operation. If used, it will fail at operation instantiation if no context
+    # is provided. By providing one or more `attributes`, you can optionally
+    # specify which context attributes need to be present (not nil).
+    #
+    # This can be useful to fail early if you're going to be accessing e.g.
+    # `context.user` and `context.session`. In this case, you can specify:
+    #
+    # ```ruby
+    # class MyOp < RailsOps::Operation
+    #   require_context :user, :session
+    # end
+    # ```
+    #
+    # @param args [Array<Symbol>] Specify which context attributes need to be
+    #   present
+    def require_context(*attributes)
+      policy :on_init do
+        attributes.each do |attribute|
+          if context.attributes[attribute.to_s].nil?
+            fail RailsOps::Exceptions::MissingContextAttribute,
+                 "This operation requires the context attribute #{attribute.inspect} to be present."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_ops/mixins/routes.rb

@@ -0,0 +1,35 @@
+module RailsOps::Mixins::Routes
+  extend ActiveSupport::Concern
+
+  # This class can't be defined at load time of this file as `Rails.application`
+  # would not exist at this point in time. Instead, we're creating and caching
+  # this class on the first call. This is not thread-safe, but the worst case is
+  # that this is performed more than once.
+  def self.container_class
+    @container ||= Class.new do
+      include Rails.application.routes.url_helpers
+
+      attr_reader :url_options
+
+      def initialize(url_options)
+        @url_options = url_options
+      end
+    end
+  end
+
+  # Returns an object that responds to all URL helper methods using the
+  # `url_options` provided with the operation's context. If no URL options are
+  # given, this method will raise an exception.
+  def routes
+    unless @routes
+      if context.url_options.nil?
+        fail RailsOps::Exceptions::RoutingNotAvailable,
+             'Can not access routes helpers, no url_options given in context.'
+      end
+
+      @routes = RailsOps::Mixins::Routes.container_class.new(context.url_options)
+    end
+
+    return @routes
+  end
+end

data/lib/rails_ops/mixins/schema_validation.rb

@@ -0,0 +1,25 @@
+# Mixin for the {RailsOps::Operation} class that provides a simple way of
+# validation the params hash against a specific schema. It internally uses
+# policies for running the validations (see {RailsOps::Mixins::Policies}).
+module RailsOps::Mixins::SchemaValidation
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    # Creates a policy to validate the params hash against the given schema. See
+    # {Schemacop::Validator} for more information on how schemas are built.
+    #
+    # Using `policy_chain`, you can control when the validation is performed.
+    # Per default, validation is done before performing the operation.
+    #
+    # @param *args [Array] Parameters to pass at schema initialization
+    # @param policy_chain [Symbol] The policy chain to perform the schema validation in
+    # @yield Block to pass at schema initialization
+    def schema(*args, policy_chain: :before_perform, &block)
+      full_schema = Schemacop::Schema.new(*args, &block)
+
+      policy policy_chain do
+        full_schema.validate!(params)
+      end
+    end
+  end
+end

data/lib/rails_ops/mixins/sub_ops.rb

@@ -0,0 +1,35 @@
+# Mixin for the {RailsOps::Operation} class that provides a simple way of
+# running arbitrary operations within operations, automatically passing a
+# modified version of the current operation's context to them.
+module RailsOps::Mixins::SubOps
+  extend ActiveSupport::Concern
+
+  # Instantiates and returns a new operation of the given class and
+  # automatically passes a modified version of the current operation's context
+  # to it. For one-line runs of operations please use {run_sub!} or {run_sub}
+  # which internally use this method.
+  def sub_op(op, params = {})
+    new_context = context.spawn(self)
+    return op.new(new_context, params)
+  end
+
+  # Operation-equivalent of controller method 'run!': Instantiates and runs the
+  # given operation class. See {sub_op} for more details on how instantiation
+  # and context modification is done.
+  def run_sub!(klass, params = {})
+    op = sub_op(klass, params)
+
+    begin
+      return op.run!
+    rescue op.validation_errors => e
+      fail RailsOps::Exceptions::SubOpValidationFailed, e
+    end
+  end
+
+  # Operation-equivalent of controller method 'run': Instantiates and runs the
+  # given operation class. See {sub_op} for more details on how instantiation
+  # and context modification is done.
+  def run_sub(op, params = {})
+    sub_op(op, params).run
+  end
+end

data/lib/rails_ops/model_casting.rb

@@ -0,0 +1,17 @@
+module RailsOps::ModelCasting
+  def self.cast(model)
+    if model.class.respond_to?(:extended_record_base_class)
+      return ActiveType.cast(model, model.class.extended_record_base_class)
+    else
+      return model
+    end
+  end
+
+  def self.original_class_for(model_class)
+    if model_class.respond_to?(:extended_record_base_class)
+      return model_class.extended_record_base_class
+    else
+      return model_class
+    end
+  end
+end

data/lib/rails_ops/model_mixins.rb

@@ -0,0 +1,12 @@
+# A collection of mixins that are useful when using models in operations.
+module RailsOps::ModelMixins
+  extend ActiveSupport::Concern
+
+  included do
+    include ArExtension            # Provides correct behaviour of model_name when extending AR objects.
+    include ParentOp               # Provides parent_op accessor.
+    include ProtectedAttributes    # Provides attr_accessible and attr_protected.
+    include VirtualAttributes      # Provides virtual attributes functionality.
+    include VirtualHasOne          # Provides virtual_has_one.
+  end
+end

data/lib/rails_ops/model_mixins/ar_extension.rb

@@ -0,0 +1,20 @@
+# When extending an ActiveRecord::Base model class, you can mix this module
+# into the extending class to make it behave like it was the original one
+# in terms of it's model_name identity.
+#
+# Note that you have to mix this in directly into the first class inheriting
+# from your real model class.
+module RailsOps::ModelMixins::ArExtension
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :extended_record_base_class
+    self.extended_record_base_class = superclass
+  end
+
+  module ClassMethods
+    def model_name
+      (extended_record_base_class || superclass).model_name
+    end
+  end
+end

data/lib/rails_ops/model_mixins/parent_op.rb

@@ -0,0 +1,10 @@
+# This is automatically mixed into every model passed to an operation
+# and provides the :parent_op accessor that is set to the enclosing
+# operation's instance.
+module RailsOps::ModelMixins::ParentOp
+  extend ActiveSupport::Concern
+
+  included do
+    attr_accessor :parent_op
+  end
+end

data/lib/rails_ops/model_mixins/protected_attributes.rb

@@ -0,0 +1,78 @@
+# This mixin can be used with any Activemodel Model to allow mass assignment
+# security. This is a simpler implementation of Rails' former mass assignment
+# security functionality.
+#
+# Attribute protection is disabled per default. It can be enabled by either
+# calling `attr_protection true` or one of `attr_accessible` and
+# `attr_protected`.
+module RailsOps::ModelMixins::ProtectedAttributes
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :accessible_attributes
+    self.accessible_attributes = nil
+  end
+
+  # TODO: Document.
+  def assign_attributes_with_protection(attributes)
+    self.class._verify_protected_attributes!(attributes.dup)
+    assign_attributes(attributes)
+  end
+
+  module ClassMethods
+    # Returns whether attribute protection is enabled for this model.
+    def attr_protection?
+      !accessible_attributes.nil?
+    end
+
+    # Performs attribute protection verification (if enabled, see
+    # {attr_protection?}). If forbidden attributes are found, an
+    # {ActiveModel::ForbiddenAttributesError} exception is thrown.
+    def _verify_protected_attributes!(attributes) # :nodoc:
+      return unless attr_protection?
+
+      received_keys = attributes.keys.map(&:to_sym).to_set
+
+      disallowed_attributes = received_keys - accessible_attributes
+
+      if disallowed_attributes.any?
+        fail ActiveModel::ForbiddenAttributesError,
+             "The following attributes are forbidden to be assigned to #{model_name}: " \
+             "#{disallowed_attributes.to_a}, allowed are: #{accessible_attributes.to_a}."
+      end
+    end
+
+    # Specifically turn on or off attribute protection for this model (and
+    # models inheriting from it without overriding this setting).
+    #
+    # Note that attribute protection is turned on automatically when calling
+    # {attr_accessible} or {attr_protected}.
+    #
+    # If you're using this method to turn protection off, the list of accessible
+    # attributes is wiped. So if you re-enable it, no attributes will be
+    # accessible.
+    def attr_protection(enable)
+      if !enable
+        self.accessible_attributes = nil
+      elsif accessible_attributes.nil?
+        self.accessible_attributes = Set.new
+      end
+    end
+
+    # Specifies the given attribute(s) as accessible. This automatically turns
+    # on attribute protection for this model. This configuration is inherited to
+    # model inheriting from it.
+    def attr_accessible(*attributes)
+      attr_protection true
+      self.accessible_attributes += attributes.map(&:to_sym)
+    end
+
+    # Specifies the given attribute(s) as protected. This automatically turns on
+    # attribute protection for this model. This configuration is inherited
+    # to models inheriting from it.
+    def attr_protected(*attributes)
+      attr_protection true
+      self.accessible_attributes -= attributes.map(&:to_sym)
+    end
+  end
+end

data/lib/rails_ops/model_mixins/virtual_attributes.rb

@@ -0,0 +1,24 @@
+module RailsOps::ModelMixins::VirtualAttributes
+  extend ActiveSupport::Concern
+
+  included do
+    include ActiveType::VirtualAttributes
+  end
+
+  # rubocop: disable Style/PredicateName
+  # TODO: Document this. Why is this necessary and not part of ActiveType?
+  def has_attribute?(name)
+    return true if self.class._has_virtual_column?(name)
+    return super
+  end
+  # rubocop: enable Style/PredicateName
+
+  # TODO: Document this. Why is this necessary and not part of ActiveType?
+  def column_for_attribute(name)
+    if self.class._has_virtual_column?(name)
+      return VirtualColumnWrapper.new(singleton_class._virtual_column(name))
+    else
+      super
+    end
+  end
+end

data/lib/rails_ops/model_mixins/virtual_attributes/virtual_column_wrapper.rb

@@ -0,0 +1,9 @@
+class RailsOps::ModelMixins::VirtualAttributes::VirtualColumnWrapper
+  def initialize(virtual_column)
+    @virtual_column = virtual_column
+  end
+
+  def type
+    @virtual_column.instance_variable_get(:@type_caster).instance_variable_get(:@type)
+  end
+end

data/lib/rails_ops/model_mixins/virtual_has_one.rb

@@ -0,0 +1,32 @@
+module RailsOps
+  module ModelMixins
+    module VirtualHasOne
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # TODO: Passing type Fixnum currently requires a monkey-patch of ActiveType.
+        # This would need to be changed when releasing this functionality as a Gem.
+        # See config/initializers/patch_active_type.rb and
+        # https://github.com/remofritzsche/active_type/commit/fb8c2cb4cccaaec
+        #
+        # TODO: Document.
+        def virtual_has_one(name, base_class, required: false, accessible: true, default: nil, type: Integer)
+          fk = "#{name}_id"
+          attribute fk, type, default: default
+
+          if required
+            validates fk, presence: true
+          end
+
+          if accessible
+            attr_accessible name, fk
+          end
+
+          belongs_to name, anonymous_class: base_class, foreign_key: fk, class_name: base_class.name
+
+          return reflect_on_association(name)
+        end
+      end
+    end
+  end
+end

data/lib/rails_ops/operation.rb

@@ -0,0 +1,215 @@
+class RailsOps::Operation
+  include RailsOps::Mixins::Policies
+  include RailsOps::Mixins::SubOps
+  include RailsOps::Mixins::SchemaValidation
+  include RailsOps::Mixins::Authorization
+  include RailsOps::Mixins::RequireContext
+  include RailsOps::Mixins::LogSettings
+
+  WHITELISTED_BASE_CLASSES_FOR_PARAM_INSPECTION = [
+    ActiveRecord::Base,
+    String,
+    Integer,
+    Symbol
+  ].freeze
+
+  attr_reader :params
+  attr_reader :context
+
+  def self.run!(*args)
+    new(*args).run!
+  end
+
+  def self.run(*args)
+    new(*args).run
+  end
+
+  # Constructs a new operation instance with the given (optional) context and
+  # the given (optional) params. This is the only way of assigning context and
+  # params to an operation.
+  #
+  # If no context is provided, an empty context will be created.
+  #
+  # Note that, if provided, `params` must be a `Hash`. Other types such as
+  # `ActiveSupport::HashWithIndifferentAccess` or `ActionController::Parameters`
+  # are not supported.
+  #
+  # @param context [RailsOps::Context] Optional context
+  # @param params [Hash] Optional parameters hash
+  def initialize(context_or_params = {}, params = {})
+    # Handle parameter signature
+    if context_or_params.is_a?(RailsOps::Context)
+      context = context_or_params
+    elsif context_or_params.is_a?(Hash) || context_or_params.is_a?(ActionController::Parameters)
+      context = nil
+      params = context_or_params
+    end
+
+    @performed = false
+    @context = context || RailsOps::Context.new
+
+    # Convert ActionController::Parameters to a regular hash as we want to
+    # bypass Rails' strong parameters for operation use.
+    if params.is_a?(ActionController::Parameters)
+      params = params.permit!.to_h
+    end
+
+    # Remove web-specific param entries (such as `authenticity_token`)
+    @params = params.to_h.with_indifferent_access.except(
+      *ActionController::ParamsWrapper::EXCLUDE_PARAMETERS
+    )
+
+    run_policies :on_init
+  end
+
+  # Returns an array of exception classes that are considered as validation
+  # errors.
+  def validation_errors
+    [RailsOps::Exceptions::ValidationFailed, ActiveRecord::RecordInvalid]
+  end
+
+  # Returns a copy of the operation's params, wrapped in an OpenStruct object.
+  def osparams
+    @osparams ||= OpenStruct.new(params)
+  end
+
+  # Return a hash of parameters with all sensitive data replaced.
+  def filtered_params
+    f = ActionDispatch::Http::ParameterFilter.new(Rails.application.config.filter_parameters)
+    return f.filter(params)
+  end
+
+  # Runs the operation using {run!} but rescues certain exceptions. Returns
+  # `true` on success, otherwise `false`.
+  def run
+    run!
+    return true
+  rescue validation_errors
+    return false
+  end
+
+  # Runs the operation. This internally calls the {perform} method and can only
+  # be called once per operation instance. This is a bang method that raises at
+  # any validation exception.
+  def run!
+    ActiveSupport::Notifications.instrument('run.operation', operation: self) do
+      ::RailsOps::Profiler.profile(object_id, inspect) do
+        fail 'An operation can only be performed once.' if performed?
+        @performed = true
+        run_policies :before_perform
+        perform
+      end
+    end
+
+    trigger :after_run, after_run_trigger_params
+
+    return self
+  end
+
+  # Returns the contents of the operation as a nicely formatted string.
+  def inspect
+    inspection = self.class.name
+    if params
+      inspection << " (#{inspect_params(filtered_params)})"
+    end
+    return inspection
+  end
+
+  # Determines if the operation has been performed yet.
+  def performed?
+    @performed
+  end
+
+  # Fails with an exception if the operation has not been performed yet.
+  def check_performed!
+    fail 'Operation has not yet been perfomed.' unless performed?
+  end
+
+  protected
+
+  # This method actually performs the operation's logic and is called by {run}
+  # or {run!}. Never call this method directly. Overwrite this method for
+  # supplying operation logic.
+  def perform
+    fail NotImplementedError
+  end
+
+  # Determines a basic set of parameters that will be passed to the `after_run`
+  # event. This is empty per default and is meant to overridden by superclasses
+  # where necessary.
+  def after_run_trigger_params
+    {}
+  end
+
+  # Triggers an event of the given name using the given params using the
+  # {RailsOps::Hookup} functionality. Any potential operation called by this
+  # trigger will receive an operation context based on the context of the
+  # current operation, but with an updated `op_chain` and with the `params`
+  # supplied.
+  #
+  # @param [string] event The event name to trigger
+  # @param [hash] params The params to provide to any ops called by this trigger
+  def trigger(event, params = nil)
+    RailsOps.hookup.trigger(self, event, params)
+  end
+
+  # Yields the given block and rethrows any possible exception as a
+  # {RailsOps::Exceptions::RollbackRequired} exception.
+  #
+  # For illustration of potential use cases, consider the following example:
+  #
+  #     class User::Create < RailsOps::Operation::Model::Create
+  #       def perform
+  #         super # Saves the user
+  #
+  #         model.some_field = 'some value'
+  #         model.save! # Throws validation error
+  #       end
+  #     end
+  #
+  #     User::Create.run(user: { some: :values })
+  #
+  # Since this operation is run without the bang method, validation errors are
+  # caught and won't result in the transaction beeing rolled back. However, the
+  # `super` call already saved the user while the exception happens only at
+  # the manual call to `model.save!`. Thus the user will still be in the DB,
+  # despite the fact that the second update didn't run.
+  #
+  # The correct example would therefore be:
+  #
+  #     class User::Create < RailsOps::Operation::Model::Create
+  #       def perform
+  #         super # Saves the user
+  #
+  #         with_rollback_on_exception do
+  #           model.some_field = 'some value'
+  #           model.save! # Throws validation error
+  #         end
+  #       end
+  #     end
+  #
+  # This method is one possible solution for issue #28535. There might be a more
+  # elegant and transparent approach as explained in the issue.
+  def with_rollback_on_exception(&_block)
+    yield
+  rescue => e
+    fail RailsOps::Exceptions::RollbackRequired, e
+  end
+
+  # Returns the contents of the params as a nicely formatted string.
+  def inspect_params(params)
+    params.each do |key, value|
+      if value.is_a?(Hash)
+        inspect_params(value)
+      elsif WHITELISTED_BASE_CLASSES_FOR_PARAM_INSPECTION.any? { |klass| value.is_a?(klass) }
+        formatted_value = value
+      else
+        formatted_value = "#<#{value.class}>"
+      end
+
+      params[key] = formatted_value
+    end
+
+    return params.inspect
+  end
+end