activefunction 0.3.5 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 291381221a57e279bfad4dddf88cbeb3695a83e2b4882960b1255304e01a78db
-  data.tar.gz: 8a2a8d432700fff63717b76198bc032986bc2c6656e7eb9dbf034f78552bcb29
+  metadata.gz: 777be794ab7e9eb091472b8f886b0b8da55c338c6c617afb9ee95acc9a946cba
+  data.tar.gz: faf687684919e61cd2bb9a2b8217f029945971898ae4469593f166d7ab34508a
 SHA512:
-  metadata.gz: 70f3d994a4703b373f91a4df21e0b02a424f0a049a391caf04558ffbcebd80546a3f6683fce5c5a66111336d0827aaa2049ce4b5fbafa64fa7720e13278cf2b7
-  data.tar.gz: fc0bd5b0c69e64147e7d1729c179c5ef44a931733b9b71b3adec4aa623a7f01f50d70553c7bd58ade6080c2f4e8dab52d2716ebea0b042556296a17d61276e0c
+  metadata.gz: 20bb5768a3dcf00582d6f32b99c600c51a9e83c9e5b7ef78ecf81c7e560d63f7d83ea02005d01ef19cd4e2a87a5161f47627e7c305c45d2c18dab6744cd5134a
+  data.tar.gz: 7e866bc6a9fe14cd56b8f08985a2a83ce10e57c54560e54e3c954116508638dc0128878d0dc6b2d16f7c8c2c11775ba2681515a58229632bc752e20b76fd79dd

data/CHANGELOG.md

@@ -46,4 +46,13 @@
 
 - Start gem restructuring for modularizaition
 - Introduce `activefunction-core` gem with RubyNext integration
- 
+
+# [0.4.0] - 2024-01-11
+
+- Replace `ActiveFunction::Functions::Callbacks` with `ActiveFunctionCore::Plugins::Hooks`
+- Introduce Plugin system
+- Global refactoring
+
+# [0.4.1] - 2024-01-14
+
+- YARD Doc Added

data/README.md

@@ -1,146 +1,259 @@
 # ActiveFunction
+[![Build](https://github.com/DanilMaximov/activefunction/actions/workflows/build.yml/badge.svg)](DanilMaximov/activefunction/actions)
+[![Gem Version](https://badge.fury.io/rb/activefunction.svg)](https://badge.fury.io/rb/activefunction)
+[![RubyDoc](https://img.shields.io/badge/RubyDoc-Documentation-blue.svg)](https://rubydoc.info/gems/activefunction)
 
-rails/action_controller like gem which provides lightweight callbacks, strong parameters & rendering features. It's designed to be used with AWS Lambda functions, but can be also used with any Ruby application. 
 
-Implemented with some of ruby 3.x features, but also supports ruby 2.6.x thanks to [RubyNext](https://github.com/ruby-next/ruby-next) transpiler. Type safety achieved by RBS and [Steep](https://github.com/soutaro/steep).
+Playground gem for Ruby 3.2+ features initially designed to be used with FaaS (Function as a Service) computing instances. Inspired by aws-sdk v3 gem structure & rails/activesupport.
 
+## Features
 
+- **Ruby Version Compatibility:** Implemented with most of ruby 3.2+ features, BUT supports Ruby versions >= 2.6 through the use of the [RubyNext](https://github.com/ruby-next/ruby-next) transpiler. (CI'ed)
+- **Type Safety:** Achieves type safety through the use of RBS and [Steep](https://github.com/soutaro/steep). (CI'ed)
+  - Note: disabled due to the presence of Ruby::UnsupportedSyntax errors.
+- **Plugins System:** Provides a simple Plugin system (inspired by [Polishing Ruby Programming by Jeremy Evans](https://github.com/PacktPublishing/Polished-Ruby-Programming)) to load gem plugins as well as self-defined plugins.
+- **Gem Collection:** Provides a collection of gems designed to be used within ActiveFunction or standalone.
 
-## A Short Example
+# Gems
 
-Here's a simple example of a function that uses ActiveFunction:
+- [activefunction](/) - Main gem, provides rails/action-controller like API with callbacks, strong parameters and rendering under plugins.
+- [activefunction-core](/gems/activefunction-core/README.md) - Provides RubyNext integration and External Standalone Plugins
+- activefunction-orm - WIP (ORM around AWS PartiQL)
+
+## Quick Start
+
+Here's a simple example of a function that uses ActiveFunction(w/o plugins):
 
 ```ruby
-require 'active_function'
+require "active_function"
 
 class AppFunction < ActiveFunction::Base
-  def index 
-    render json: SomeTable.all
-  end 
+  def index
+    response_with_error if @request[:data].nil?
+
+    return if performed?
+
+    @response.body = @request[:data]
+  end
+
+  private def response_with_error
+    @response.status = 400
+    @response.commit!
+  end
 end
+
 ```
 
-Use `#process` method to proceed the request:
+The `#process` method is used to run the function.
+
+```ruby
+AppFunction.process(:index, {data: {id: 1}}) # => { 
+#   :statusCode => 200, 
+#   :headers => { }, 
+#   :body => {id: 1}"
+# }
+``` 
 
-```ruby 
-AppFunction.process(:index) # processes index action of AppFunction instance
+## Plugins
+
+ActiveFunction supports plugins which can be loaded by `ActiveFunction.config` method. Currently, there are 3 plugins available:
+  - [:callbacks](#callbacks) - provides `:before_action`, `:after_action` & `:set_callback` DSL with `:if`, `:unless` & `:only` options.
+  - [:strong_parameters](#strong-parameters) - provides strong parameters support via `#params` instance method around `@request` object.
+  - [:rendering](#rendering) - provides rendering support via `#render` instance method around `@response` object.
+
+## Configuration
+
+To configure ActiveFunction with plugins, use the `ActiveFunction.config` method.
+
+```ruby
+# config/initializers/active_function.rb
+require "active_function"
+
+ActiveFunction.config do
+  plugin :callbacks
+  plugin :strong_parameters
+  plugin :rendering
+end
 ```
-Also check extended [example](https://github.com/DanilMaximov/activefunction/tree/master/active_function_example)
-## Callbacks 
-ActiveFunction supports simple callbacks `:before` and `:after` which runs around provided action in `#process`. 
 
 ```ruby
+# app/functions/app_function.rb
 class AppFunction < ActiveFunction::Base
-  before_action :set_user 
-  after_action :log_response
-  
-  # some action ...
+  before_action :parse_user_data
 
-  private 
+  def index
+    render json: @user_data
+  end
 
-  def set_user 
-    @user = User.first
-  end 
+  private def parse_user_data = @user_data = params.require(:data).permit(:id, :name).to_h
+end
+
+AppFunction.process(:index, {data: { id: 1, name: 2}}) # => { 
+#   :statusCode => 200, 
+#   :headers => {"Content-Type"=>"application/json"}, 
+#   :body=>"{\"id\":1,\"name\":2}"
+# }
+```
+
+[See Plugins Docs](https://rubydoc.info/gems/activefunction/ActiveFunction#plugin-class_method) for more details.
+
+## Callbacks
+
+Simple callbacks engined by [ActiveFunctionCore::Plugins::Hooks](https://github.com/DanilMaximov/activefunction/tree/master/gems/activefunction-core#hooks) external plugin and provides `:before_action` and `:after_action` which runs around provided action in `#process`.
+
+```ruby
+require "active_function"
+
+ActiveFunction.config do
+  plugin :callbacks
+end
 
-  def log_response 
-    Logger.info @response 
+class AppFunction < ActiveFunction::Base
+  before_action :set_user
+  after_action :log_response
+
+  def index
+    # some actions ...
   end
+
+  private
+
+  def set_user     = @_user ||= User.find(@request[:id])
+  def log_response = Logger.info(@response)
 end
 ```
 
-Callbacks also can be user  with `only: Array[Symbol]` and `if: Symbol` options.
+### Callbacks options
+
+Supports default [ActiveFunctionCore::Plugins::Hooks::Hook::Callback options](https://github.com/DanilMaximov/activefunction/tree/master/gems/activefunction-core#options) `:if => Symbol` & `:unless => Symbol` options.
+
+Support custom defined in ActiveFunction::Function::Callbacks `only: Array[Symbol]` option.
 
 ```ruby
 class AppFunction < ActiveFunction::Base
   before_action :set_user, only: %i[show update destroy], if: :request_valid?
-  
+
   # some actions ...
-  
+
   private def request_valid? = true
 end
 ```
 
-Callbacks are inheritable so all callbacks calls will be inherited from base class
+### Defining Custom Callbacks
+
+External Plugin `ActiveFunctionCore::Plugins::Hooks` provides `:define_hooks_for` & `:set_callback_options` DSL to define custom callbacks & options.
+
 ```ruby
-class BaseFunction < ActiveFunction::Base
-  before_action :set_current_user
+class MessagingApp < ActiveFunction::Base
+  set_callback_options retries: ->(times, context:) { context.retry if context.retries < times }
+  define_hooks_for :retry
 
-  def set_current_user
-    @current_user = User.first
-  end 
-end
+  after_action :retry, if: :failed?, only: %i[send_message], retries: 3
+  after_retry :increment_retries
 
-class PostsFunction < BaseFunction
-  def index
-    render json: @current_user
+  def send_message
+    @response.status = 200 if SomeApi.send(@request[:message_content]).success?
+  end
+
+  def retry
+    @response.committed = false
+ 
+    process
   end
+
+  private def increment_retries = @response.body[:tries] += 1
+  private def failed? = @response.status != 200
+  private def retries = @response.body[:tries] ||= 0
 end
+
+MessagingApp.process(:send_message, { sender_name: "Alice", message_content: "How are you?" })
 ```
+
+[See Callbacks Doc](https://rubydoc.info/gems/activefunction/ActiveFunction/Functions/Callbacks) for more details.
+
 ## Strong Parameters
-ActiveFunction supports strong parameters which can be accessed by `#params` instance method. Strong parameters hash can be passed in `#process` as second argument.
 
-```ruby
-PostFunction.process(:index, data: { id: 1, name: "Pupa" })
-```
+ActiveFunction supports strong parameters which can be accessed by `#params` instance method.
+
+The `#params` method represents a Ruby 3.2 Data class that allows the manipulation of request parameters. It supports the following methods:
+
+- `[]`: Access parameters by key.
+- `permit`: Specify the allowed parameters.
+- `require`: Ensure the presence of a specific parameter.
+- `to_h`: Convert the parameters to a hash.
+
+Usage Example:
 
-Simple usage:
 ```ruby
+require "active_function"
+
+ActiveFunction.config do
+  plugin :strong_parameters
+end
+
 class PostsFunction < ActiveFunction::Base
-  def index 
-    render json: permitted_params
-  end 
+  def index
+    @response.body = permitted_params
+  end
 
   def permitted_params = params
     .require(:data)
     .permit(:id, :name)
     .to_h
-end 
+end
+
+PostFunction.process(:index, data: {id: 1, name: "Pupa"})
 ```
+
 Strong params supports nested attributes
-```ruby 
+```ruby
 params.permit(:id, :name, :address => [:city, :street])
 ```
 
+[See StrongParameters Doc](https://rubydoc.info/gems/activefunction/ActiveFunction/Functions/StrongParameters) for more details.
+
 ## Rendering
-ActiveFunction supports rendering of JSON. Rendering is obligatory for any function naction and can be done by `#render` method.
-```ruby
-class PostsFunction < ActiveFunction::Base
-  def index 
-    render json: { id: 1, name: "Pupa" }
-  end 
-end
-```
-default status code is 200, but it can be changed by `:status` option
+
+ActiveFunction supports rendering of JSON. The #render method is used for rendering responses. It accepts the following options:
+
+- `head`: Set response headers. Defaults to `{ "Content-Type" => "application/json" }`.
+- `json`: Set the response body with a JSON-like object. Defaults to `{}`.
+- `status`: Set the HTTP status code. Defaults to `200`.
+
+Additionally, the method automatically commits the response and JSONifies the body.
+
+Usage Example:
 ```ruby
-class PostsFunction < ActiveFunction::Base
-  def index 
-    render json: { id: 1, name: "Pupa" }, status: 201
-  end 
+require "active_function"
+
+ActiveFunction.config do
+  plugin :rendering
 end
-```
-Headers can be passed by `:headers` option. Default headers are `{"Content-Type" => "application/json"}`.
-```ruby
+
 class PostsFunction < ActiveFunction::Base
-  def index 
-    render json: { id: 1, name: "Pupa" }, headers: { "X-Request-Id" => "123" }
-  end 
+  def index
+    render json: {id: 1, name: "Pupa"}, status: 200, head: {"Some-Header" => "Some-Value"}
+  end
 end
+
+PostFunction.process(:index) # => { :statusCode=>200, :headers=> {"Content-Type"=>"application/json", "Some-Header" => "Some-Value"}, :body=>"{\"id\":1,\"name\":\"Pupa\"}"}
 ```
 
+[See Rendering Doc](https://rubydoc.info/gems/activefunction/ActiveFunction/Functions/Rendering) for more details.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'activefunction', git: "https://github.com/DanilMaximov/activefunction.git"
+gem "activefunction"
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rake test` to run the tests and `bin/rake steep` to run type checker. 
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rake test:all` to run the tests and `bin/rake steep` to run type checker.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 

data/lib/.rbnext/2.7/active_function/functions/strong_parameters.rb

@@ -3,54 +3,80 @@
 require "forwardable"
 
 module ActiveFunction
-  class ParameterMissingError < Error
-    MESSAGE_TEMPLATE = "Missing parameter: %s"
-
-    attr_reader :message
-
-    def initialize(param)
-      MESSAGE_TEMPLATE % param
-    end
-  end
+  module Functions
+    # Allows manipulations with {ActiveFunction::SuperBase#request} via {params} instance method and {Parameters} object.
+    #
+    # @example
+    #   require "active_function"
+    #
+    #   ActiveFunction.config do
+    #     plugin :strong_parameters
+    #   end
+    #
+    #   class PostsFunction < ActiveFunction::Base
+    #     def index
+    #       @response.body = permitted_params
+    #     end
+    #
+    #     def permitted_params
+    #       params.require(:data).permit(:id, :name).to_h
+    #     end
+    #   end
+    #
+    #   PostsFunction.process(:index, data: { id: 1, name: "Pupa" })
+    module StrongParameters
+      ActiveFunction.register_plugin :strong_parameters, self
 
-  class UnpermittedParameterError < Error
-    MESSAGE_TEMPLATE = "Unpermitted parameter: %s"
+      Error = Class.new(StandardError)
+      # The Parameters class encapsulates the parameter handling logic.
+      class Parameters < Data.define(:params, :permitted)
+        class ParameterMissingError < Error
+          MESSAGE_TEMPLATE = "Missing parameter: %s"
 
-    attr_reader :message
+          attr_reader :message
 
-    def initialize(param)
-      MESSAGE_TEMPLATE % param
-    end
-  end
+          def initialize(param)
+            MESSAGE_TEMPLATE % param
+          end
+        end
 
-  module Functions
-    module StrongParameters
-      def params
-        @_params ||= Parameters.new(@request)
-      end
+        class UnpermittedParameterError < Error
+          MESSAGE_TEMPLATE = "Unpermitted parameter: %s"
 
-      class Parameters
-        extend Forwardable
-        def_delegators :@parameters, :each, :map
-        include Enumerable
+          attr_reader :message
 
-        def initialize(parameters, permitted: false)
-          @parameters = parameters
-          @permitted  = permitted
+          def initialize(param)
+            MESSAGE_TEMPLATE % param
+          end
         end
 
+        protected :params
+
+        # Allows access to parameters by key.
+        #
+        # @param attribute [Symbol] The key of the parameter.
+        # @return [Parameters, Object] The value of the parameter.
         def [](attribute)
-          nested_attribute(parameters[attribute])
+          nested_attribute(params[attribute])
         end
 
+        # Requires the presence of a specific parameter.
+        #
+        # @param attribute [Symbol] The key of the required parameter.
+        # @return [Parameters, Object] The value of the required parameter.
+        # @raise [ParameterMissingError] if the required parameter is missing.
         def require(attribute)
-          value = self[attribute]
-
-          raise ParameterMissingError, attribute if value.nil?
-
-          value
+          if (value = self[attribute])
+            value
+          else
+            raise ParameterMissingError, attribute
+          end
         end
 
+        # Specifies the allowed parameters.
+        #
+        # @param attributes [Array<Symbol, Hash<Symbol, Array<Symbol>>>] The attributes to permit.
+        # @return [Parameters] A new instance with permitted parameters.
         def permit(*attributes)
           pparams = {}
 
@@ -60,28 +86,40 @@ module ActiveFunction
                 pparams[k] = process_nested(self[k], :permit, v)
               end
             else
-              next unless parameters.key?(attribute)
+              next unless params.key?(attribute)
 
               pparams[attribute] = self[attribute]
             end
           end
 
-          Parameters.new(pparams, permitted: true)
+          with(params: pparams, permitted: true)
         end
 
+        # Converts parameters to a hash.
+        #
+        # @return [Hash] The hash representation of the parameters.
+        # @raise [UnpermittedParameterError] if any parameters are unpermitted.
         def to_h
-          raise UnpermittedParameterError, parameters.keys unless @permitted
+          raise UnpermittedParameterError, params.keys unless permitted
 
-          parameters.transform_values { |_1| process_nested(_1, :to_h) }
+          params.transform_values { |_1| process_nested(_1, :to_h) }
+        end
+
+        def hash
+          @attributes.to_h.hash
+        end
+
+        def with(params:, permitted: false)
+          self.class.new(params, permitted)
         end
 
         private
 
         def nested_attribute(attribute)
           if attribute.is_a? Hash
-            Parameters.new(attribute)
+            with(params: attribute)
           elsif attribute.is_a?(Array) && attribute[0].is_a?(Hash)
-            attribute.map { |_1| Parameters.new(_1) }
+            attribute.map { |it| with(params: it) }
           else
             attribute
           end
@@ -96,8 +134,13 @@ module ActiveFunction
             attribute
           end
         end
+      end
 
-        attr_reader :parameters
+      # Return params object with {ActiveFunction::SuperBase#request}.
+      #
+      # @return [Parameters] instance of {Parameters} class.
+      def params
+        @_params ||= Parameters.new(@request, false)
       end
     end
   end

data/lib/.rbnext/3.0/active_function/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ActiveFunction
+  # Abstract base class with request processing logic.
+  class SuperBase
+    attr_reader :action_name, :request, :response
+
+    def initialize(action_name, request, response)
+      @action_name = action_name
+      @request     = request
+      @response    = response
+    end
+
+    # Executes specified @action_name instance method and returns Hash'ed response object
+    def dispatch
+      process(action_name)
+
+      @response.commit! unless performed?
+
+      @response.to_h
+    end
+
+    def process(action) ;  public_send(action); end
+
+    private def performed? ;  @response.committed?; end
+  end
+
+  # The main base class for defining functions using the ActiveFunction framework.
+  # Public methods of this class are considered as actions and be proceeded on {ActiveFunction::Base.process} call.
+  #
+  # @example
+  #   class MyFunction < ActiveFunction::Base
+  #      def index
+  #         if user = User.find(@request.dig(:data, :user, :id))
+  #             @response.body = user.to_h
+  #         else
+  #             @response.status = 404
+  #         end
+  #      end
+  #   end
+  class Base < SuperBase
+    Error = Class.new(StandardError)
+
+    # Processes specified action and returns Hash'ed {ActiveFunction::Functions::Response::Response} object.
+    #
+    # @example
+    #   MyFunction.process :index, { data: { user: { id: 1 } } } # => { statusCode: 200, body: { id: 1, name: "Pupa" }, headers: {} }
+    #
+    # @param [String, Symbol] action_name - name of method to call
+    # @param [Hash] request - request parameters.
+    # @param [Response] response - Functions::Response response object.
+    def self.process(action_name, request = {}, response = Response.new)
+      raise ArgumentError, "Action method #{action_name} is not defined" unless method_defined?(action_name)
+
+      new(action_name, request, response).dispatch
+    end
+  end
+end

data/lib/.rbnext/3.0/active_function/functions/response.rb

@@ -2,29 +2,48 @@
 
 module ActiveFunction
   module Functions
-    class Response
-      attr_accessor :status, :headers, :body
+    # The only required plugin for {ActiveFunction::Base} to work.
+    # Provides a simple {Response} object to manage response details.
+    #
+    # @example
+    #   response = Response.new.tap do |r|
+    #     r.body = "Hello World!"
+    #     r.headers = {"Content-Type" => "text/plain"}
+    #     r.commit!
+    #   end
+    #
+    #   response.performed? # => true
+    #   response.to_h # => { statusCode: 200, headers: { "Content-Type" => "text/plain" }, body: "Hello World!" }
+    module Response
+      ActiveFunction.register_plugin :response, self
 
-      def initialize(status: 200, headers: {}, body: nil)
-        @status     = status
-        @headers    = headers
-        @body       = body
-        @committed  = false
-      end
+      class Response < Struct.new(:status, :headers, :body, :committed)
+        # Initializes a new Response instance with default values.
+        #
+        # @param status [Integer] HTTP status code.
+        # @param headers [Hash] HTTP headers.
+        # @param body [Object] Response body.
+        # @param committed [Boolean] Indicates whether the response has been committed (default is false).
+        def initialize(status: 200, headers: {}, body: nil, committed: false) ;  super(status, headers, body, committed); end
 
-      def to_h
-        {
-          statusCode: status,
-          headers:    headers,
-          body:       body
-        }
-      end
+        # Converts the Response instance to a hash for JSON serialization.
+        #
+        # @return [Hash{statusCode: Integer, headers: Hash, body: Object}]
+        def to_h
+          {
+            statusCode: status,
+            headers: headers,
+            body: body
+          }
+        end
 
-      def commit!
-        @committed = true
-      end
+        # Marks the response as committed.
+        def commit!
+          self.committed = true
+        end
 
-      def committed? ;  @committed; end
+        alias_method :committed?, :committed
+      end
     end
   end
 end