typed_operation 0.4.2 → 1.0.0.beta2

data/lib/generators/templates/operation.rb

@@ -4,14 +4,17 @@
 module <%= namespace_name %>
   class <%= name %> < ::ApplicationOperation
     # Replace with implementation...
-    param :required_param, String
-    param :an_optional_param, Integer, convert: true, allow_nil: true
+    positional_param :required_positional_param, String
+    param :required_named_param, String
+    param :an_optional_param, Integer, optional: true do |value|
+     value.to_i
+    end
 
     def prepare
       # Prepare...
     end
 
-    def call
+    def perform
       # Perform...
       "Hello World!"
     end
@@ -20,14 +23,17 @@ end
 <% else %>
 class <%= name %> < ::ApplicationOperation
   # Replace with implementation...
-  param :required_param, String
-  param :an_optional_param, Integer, convert: true, allow_nil: true
+  positional_param :required_positional_param, String
+  param :required_named_param, String
+  param :an_optional_param, Integer, optional: true do |value|
+    value.to_i
+  end
 
   def prepare
     # Prepare...
   end
 
-  def call
+  def perform
     # Perform...
     "Hello World!"
   end

data/lib/generators/typed_operation/install/USAGE

@@ -12,6 +12,7 @@ rails generate typed_operation:install
 Options:
 --------
 --dry_monads: if specified the ApplicationOperation will include dry-monads Result and Do notation.
+--action_policy: if specified the ApplicationOperation will include action_policy authorization integration.
 
 Example:
 --------

data/lib/generators/typed_operation/install/install_generator.rb

@@ -6,6 +6,7 @@ module TypedOperation
   module Install
     class InstallGenerator < Rails::Generators::Base
       class_option :dry_monads, type: :boolean, default: false
+      class_option :action_policy, type: :boolean, default: false
 
       source_root File.expand_path("templates", __dir__)
 
@@ -18,6 +19,10 @@ module TypedOperation
       def include_dry_monads?
         options[:dry_monads]
       end
+
+      def include_action_policy?
+        options[:action_policy]
+      end
     end
   end
 end

data/lib/generators/typed_operation/install/templates/application_operation.rb

@@ -1,14 +1,36 @@
 # frozen_string_literal: true
 
 class ApplicationOperation < ::TypedOperation::Base
+<% if include_action_policy? -%>
+  include TypedOperation::ActionPolicyAuth
+
+<% end -%>
 <% if include_dry_monads? -%>
-  include Dry::Monads[:result, :do]
+  include Dry::Monads[:result]
+  include Dry::Monads::Do.for(:perform)
 
+  # Helper to execute then unwrap a successful result or raise an exception
   def call!
     call.value!
   end
 
 <% end -%>
   # Other common parameters & methods for Operations of this application...
-  # ...
+  # Some examples:
+  #
+  #   def self.operation_key
+  #     name.underscore.to_sym
+  #   end
+  #
+  #   def operation_key
+  #     self.class.operation_key
+  #   end
+  #
+  #   # Translation and localization
+  #
+  #   def translate(key, **)
+  #     key = "operations.#{operation_key}.#{key}" if key.start_with?(".")
+  #     I18n.t(key, **)
+  #   end
+  #   alias_method :t, :translate
 end

data/lib/typed_operation/action_policy_auth.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "action_policy"
+
+# An optional module to include in your operation to enable authorization via ActionPolicies
+module TypedOperation
+  class MissingAuthentication < StandardError; end
+
+  module ActionPolicyAuth
+    # Base class for any action policy classes used by operations
+    class OperationPolicy
+      include ActionPolicy::Policy::Core
+      include ActionPolicy::Policy::Authorization
+      include ActionPolicy::Policy::PreCheck
+      include ActionPolicy::Policy::Reasons
+      include ActionPolicy::Policy::Aliases
+      include ActionPolicy::Policy::Scoping
+      include ActionPolicy::Policy::Cache
+      include ActionPolicy::Policy::CachedApply
+    end
+
+    def self.included(base)
+      base.include ::ActionPolicy::Behaviour
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # Configure the operation to use ActionPolicy for authorization
+      def authorized_via(*via, with: nil, to: nil, record: nil, &auth_block)
+        # If a block is provided, you must not provide a policy class or method
+        raise ArgumentError, "You must not provide a policy class or method when using a block" if auth_block && (with || to)
+
+        parameters = positional_parameters + keyword_parameters
+        raise ArgumentError, "authorize_via must be called with a valid param name" unless via.all? { |param| parameters.include?(param) }
+        @_authorized_via_param = via
+
+        action_type_method = "#{action_type}?".to_sym if action_type
+        # If an method name is provided, use it
+        policy_method = to || action_type_method || raise(::TypedOperation::InvalidOperationError, "You must provide an action type or policy method name")
+        @_policy_method = policy_method
+        # If a policy class is provided, use it
+        @_policy_class = if with
+          with
+        elsif auth_block
+          policy_class = Class.new(OperationPolicy) do
+            authorize(*via)
+
+            define_method(policy_method, &auth_block)
+          end
+          const_set(:Policy, policy_class)
+          policy_class
+        else
+          raise ::TypedOperation::InvalidOperationError, "You must provide either a policy class or a block"
+        end
+
+        if record
+          unless parameters.include?(record) || method_defined?(record) || private_instance_methods.include?(record)
+            raise ArgumentError, "to_authorize must be called with a valid param or method name"
+          end
+          @_to_authorize_param = record
+        end
+
+        # Configure action policy to use the param named in via as the context when instantiating the policy
+        # ::ActionPolicy::Behaviour does not provide a authorize(*ids) method, so we have call once per param
+        via.each do |param|
+          authorize param
+        end
+      end
+
+      def action_type(type = nil)
+        @_action_type = type.to_sym if type
+        @_action_type
+      end
+
+      def operation_policy_method
+        @_policy_method
+      end
+
+      def operation_policy_class
+        @_policy_class
+      end
+
+      def operation_record_to_authorize
+        @_to_authorize_param
+      end
+
+      def checks_authorization?
+        !(@_authorized_via_param.nil? || @_authorized_via_param.empty?)
+      end
+
+      # You can use this on an operation base class to ensure and subclasses always enable authorization
+      def verify_authorized!
+        return if verify_authorized?
+        @_verify_authorized = true
+      end
+
+      def verify_authorized?
+        @_verify_authorized
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@_authorized_via_param, @_authorized_via_param)
+        subclass.instance_variable_set(:@_verify_authorized, @_verify_authorized)
+        subclass.instance_variable_set(:@_policy_class, @_policy_class)
+        subclass.instance_variable_set(:@_policy_method, @_policy_method)
+        subclass.instance_variable_set(:@_action_type, @_action_type)
+      end
+    end
+
+    private
+
+    # Redefine it as private
+    def execute_operation
+      if self.class.verify_authorized? && !self.class.checks_authorization?
+        raise ::TypedOperation::MissingAuthentication, "Operation #{self.class.name} must authorize. Remember to use `.authorize_via`"
+      end
+      operation_check_authorized! if self.class.checks_authorization?
+      super
+    end
+
+    def operation_check_authorized!
+      policy = self.class.operation_policy_class
+      raise "No Action Policy policy class provided, or no #{self.class.name}::Policy found for this action" unless policy
+      policy_method = self.class.operation_policy_method
+      raise "No policy method provided or action_type not set for #{self.class.name}" unless policy_method
+      # Record to authorize, if nil then action policy tries to work it out implicitly
+      record_to_authorize = send(self.class.operation_record_to_authorize) if self.class.operation_record_to_authorize
+
+      authorize! record_to_authorize, to: policy_method, with: policy
+    rescue ::ActionPolicy::Unauthorized => e
+      on_authorization_failure(e)
+      raise e
+    end
+
+    # A hook for subclasses to override to do something on an authorization failure
+    def on_authorization_failure(authorization_error)
+      # noop
+    end
+  end
+end

data/lib/typed_operation/base.rb

@@ -1,58 +1,13 @@
 # frozen_string_literal: true
 
-require "vident/typed"
-require "vident/typed/attributes"
-
 module TypedOperation
-  class Base
-    include Vident::Typed::Attributes
-
-    class << self
-      def call(...)
-        new(...).call
-      end
-
-      def curry(**args)
-        PartiallyApplied.new(self, **args).curry
-      end
-      alias_method :[], :curry
-      alias_method :with, :curry
-
-      def to_proc
-        method(:call).to_proc
-      end
-
-      def operation_key
-        name.underscore.to_sym
-      end
-
-      # property are required by default, you can fall back to attribute or set allow_nil: true if you want optional
-      def param(name, signature = :any, **options, &converter)
-        attribute(name, signature, **{allow_nil: false}.merge(options), &converter)
-      end
-    end
-
-    def initialize(**attributes)
-      begin
-        prepare_attributes(attributes)
-      rescue ::Dry::Struct::Error => e
-        raise ParameterError, e.message
-      end
-      prepare if respond_to?(:prepare)
-    end
-
-    def call
-      raise InvalidOperationError, "You must implement #call"
-    end
-
-    def to_proc
-      method(:call).to_proc
-    end
-
-    private
-
-    def operation_key
-      self.class.operation_key
-    end
+  class Base < Literal::Struct
+    extend Operations::Introspection
+    extend Operations::Parameters
+    extend Operations::PartialApplication
+
+    include Operations::Lifecycle
+    include Operations::Callable
+    include Operations::Executable
   end
 end

data/lib/typed_operation/curried.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  class Curried
+    def initialize(operation_class, partial_operation = nil)
+      @operation_class = operation_class
+      @partial_operation = partial_operation || operation_class.with
+    end
+
+    def call(arg)
+      raise ArgumentError, "A prepared operation should not be curried" if @partial_operation.prepared?
+
+      next_partially_applied = if next_parameter_positional?
+        @partial_operation.with(arg)
+      else
+        @partial_operation.with(next_keyword_parameter => arg)
+      end
+      if next_partially_applied.prepared?
+        next_partially_applied.call
+      else
+        Curried.new(@operation_class, next_partially_applied)
+      end
+    end
+
+    def to_proc
+      method(:call).to_proc
+    end
+
+    private
+
+    def next_keyword_parameter
+      remaining = @operation_class.required_keyword_parameters - @partial_operation.keyword_args.keys
+      remaining.first
+    end
+
+    def next_parameter_positional?
+      @partial_operation.positional_args.size < @operation_class.required_positional_parameters.size
+    end
+  end
+end

data/lib/typed_operation/immutable_base.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  class ImmutableBase < Literal::Data
+    extend Operations::Introspection
+    extend Operations::Parameters
+    extend Operations::PartialApplication
+
+    include Operations::Lifecycle
+    include Operations::Callable
+    include Operations::Executable
+  end
+end

data/lib/typed_operation/operations/callable.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module Callable
+      def self.included(base)
+        base.extend(CallableMethods)
+      end
+
+      module CallableMethods
+        def call(...)
+          new(...).call
+        end
+
+        def to_proc
+          method(:call).to_proc
+        end
+      end
+
+      include CallableMethods
+    end
+  end
+end

data/lib/typed_operation/operations/executable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module Executable
+      def call
+        execute_operation
+      end
+
+      def execute_operation
+        before_execute_operation
+        retval = perform
+        after_execute_operation(retval)
+      end
+
+      def before_execute_operation
+        # noop
+      end
+
+      def after_execute_operation(retval)
+        retval
+      end
+
+      def perform
+        raise InvalidOperationError, "Operation #{self.class} does not implement #perform"
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/introspection.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    # Introspection methods
+    module Introspection
+      def positional_parameters
+        literal_properties.filter_map { |property| property.name if property.positional? }
+      end
+
+      def keyword_parameters
+        literal_properties.filter_map { |property| property.name if property.keyword? }
+      end
+
+      def required_parameters
+        literal_properties.filter { |property| property.required? }
+      end
+
+      def required_positional_parameters
+        required_parameters.filter_map { |property| property.name if property.positional? }
+      end
+
+      def required_keyword_parameters
+        required_parameters.filter_map { |property| property.name if property.keyword? }
+      end
+
+      def optional_positional_parameters
+        positional_parameters - required_positional_parameters
+      end
+
+      def optional_keyword_parameters
+        keyword_parameters - required_keyword_parameters
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/lifecycle.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module Lifecycle
+      # This is called by Literal on initialization of underlying Struct/Data
+      def after_initialize
+        prepare if respond_to?(:prepare)
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/parameters.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    # Method to define parameters for your operation.
+    module Parameters
+      # Override literal `prop` to prevent creating writers (Literal::Data does this by default)
+      def self.prop(name, type, kind = :keyword, reader: :public, writer: :public, default: nil)
+        super(name, type, kind, reader:, writer: false, default:)
+      end
+
+      # Parameter for keyword argument, or a positional argument if you use positional: true
+      # Required, but you can set a default or use optional: true if you want optional
+      def param(name, signature = :any, **options, &converter)
+        PropertyBuilder.new(self, name, signature, options).define(&converter)
+      end
+
+      # Alternative DSL
+
+      # Parameter for positional argument
+      def positional_param(name, signature = :any, **options, &converter)
+        param(name, signature, **options.merge(positional: true), &converter)
+      end
+
+      # Parameter for a keyword or named argument
+      def named_param(name, signature = :any, **options, &converter)
+        param(name, signature, **options.merge(positional: false), &converter)
+      end
+
+      # Wrap a type signature in a NilableType meaning it is optional to TypedOperation
+      def optional(type_signature)
+        Literal::Types::NilableType.new(type_signature)
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/partial_application.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module PartialApplication
+      def with(...)
+        PartiallyApplied.new(self, ...).with
+      end
+      alias_method :[], :with
+
+      def curry
+        Curried.new(self)
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/property_builder.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    class PropertyBuilder
+      def initialize(typed_operation, parameter_name, type_signature, options)
+        @typed_operation = typed_operation
+        @name = parameter_name
+        @signature = type_signature
+        @optional = options[:optional] # Wraps signature in NilableType
+        @positional = options[:positional] # Changes kind to positional
+        @reader = options[:reader] || :public
+        @default_key = options.key?(:default)
+        @default = options[:default]
+
+        prepare_type_signature_for_literal
+      end
+
+      def define(&converter)
+        # If nilable, then converter should not attempt to call the type converter block if the value is nil
+        coerce_by = if type_nilable? && converter
+          ->(v) { (v == Literal::Null || v.nil?) ? v : converter.call(v) }
+        else
+          converter
+        end
+        @typed_operation.prop(
+          @name,
+          @signature,
+          @positional ? :positional : :keyword,
+          default: default_value_for_literal,
+          reader: @reader,
+          &coerce_by
+        )
+      end
+
+      private
+
+      def prepare_type_signature_for_literal
+        @signature = Literal::Types::NilableType.new(@signature) if needs_to_be_nilable?
+        union_with_nil_to_support_nil_default
+        validate_positional_order_params! if @positional
+      end
+
+      # If already wrapped in a Nilable then don't wrap again
+      def needs_to_be_nilable?
+        @optional && !type_nilable?
+      end
+
+      def type_nilable?
+        @signature.is_a?(Literal::Types::NilableType)
+      end
+
+      def union_with_nil_to_support_nil_default
+        @signature = Literal::Types::UnionType.new(@signature, NilClass) if has_default_value_nil?
+      end
+
+      def has_default_value_nil?
+        default_provided? && @default.nil?
+      end
+
+      def validate_positional_order_params!
+        # Optional ones can always be added after required ones, or before any others, but required ones must be first
+        unless type_nilable? || @typed_operation.optional_positional_parameters.empty?
+          raise ParameterError, "Cannot define required positional parameter '#{@name}' after optional positional parameters"
+        end
+      end
+
+      def default_provided?
+        @default_key
+      end
+
+      def default_value_for_literal
+        if has_default_value_nil? || type_nilable?
+          -> {}
+        else
+          @default
+        end
+      end
+    end
+  end
+end