rdux 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb70d8633e88f42179223f60bfe5634273591875f0e3d104fb076128af8811ba
-  data.tar.gz: 375487c3f51b78803b9d610877edb5e5fcec70918e86e376cf2601188a9e4358
+  metadata.gz: dbb84ff27b098d28ad7395b590852b257851825cef51837d01a48c353e2b528e
+  data.tar.gz: b6bab2fc5e8685bf8ec774e1b3c76e8b533fe0f5e3cbe85d44564f4f04067202
 SHA512:
-  metadata.gz: 4fbd330495ba4b140f828dc2e5184e27f4abd653c9e8d314d8a576c4612294c8baca8aceeeeccdab1e8be184a566544daaf1a75bc2dab2f1bba1801aab7f11cd
-  data.tar.gz: da3820133a5d277e1b5a20eee3876efb13e7cd434105585a3b2da5a014062072e17a77a93b35f35bb601d1f7d6c30dc4b930adb9e0f56e99aaeb358f1b9629e8
+  metadata.gz: bc9bd6c320bbbfe0f058234dee3c4729d64aa2a56d0568f26e896fc1fd9a63116a43d8e2634dc68995cb5f4fadb1cc6b30fdeabeee486e67aeedc3eb6e3c9294
+  data.tar.gz: 86eabdd326c7d46a3654b43f7e06faf79c4af7e00122ce25dda9b49ae1307df7436e536199c7ed31b4d6bdd08b9652abc3e7430eb18b72e936d5845b232b3467

data/README.md

@@ -1,54 +1,285 @@
-# Rdux
-Minimal take on event sourcing.
+# Rdux - A Minimal Event Sourcing Plugin for Rails
 
-## Usage
+![Logo](docs/logo.webp)
+
+Rdux is a lightweight, minimalistic Rails plugin designed to introduce event sourcing and audit logging capabilities to your Rails application. With Rdux, you can efficiently track and store the history of actions performed within your app, offering transparency and traceability for key processes.
+
+**Key Features**
+
+* **Audit Logging** 👉 Rdux stores sanitized input data, the name of module or class (action) responsible for processing them, processing results, and additional metadata in the database.
+* **Model Representation** 👉 Before action is executed it gets stored in the database through the `Rdux::Action` model. `Rdux::Action` is converted to the `Rdux::FailedAction` when it fails. These models can be nested, allowing for complex action structures.
+* **Revert and Retry** 👉 `Rdux::Action` can be reverted or retried.
+
+Rdux is designed to integrate seamlessly with your existing Rails application, offering a straightforward and powerful solution for managing and auditing key actions.
+
+## 📲 Instalation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rdux'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install rdux
+```
+
+Then install and run migrations:
 
 ```bash
 $ bin/rails rdux:install:migrations
 $ bin/rails db:migrate
 ```
 
-### Code structure
+⚠️ Note: Rdux uses `JSONB` datatype instead of `text` for Postgres.
+
+## 🎮 Usage
+
+### 🚛 Dispatching an action
+
+To dispatch an action using Rdux, use the `dispatch` method (aliased as `perform`).
+
+Definition:
+
+```ruby
+def dispatch(action_name, payload, opts = {}, meta: nil)
+
+alias perform dispatch
+```
+
+Arguments:
+
+* `action_name`: The name of the service, class, or module that will process the action. This is persisted as an instance of `Rdux::Action` in the database, with its `name` attribute set to `action_name`. The `action_name` should correspond to the class or module that implements the `call` or `up` method, referred to as "action" or “action performer.”
+* `payload` (Hash): The input data passed as the first argument to the `call` or `up` method of the action performer. This is sanitized and stored in the database before being processed. The keys in the `payload` are stringified during deserialization.
+* `opts` (Hash): Optional parameters passed as the second argument to the `call` or `up` method, if defined. This is useful when you want to avoid redundant database queries (e.g., if you already have an ActiveRecord object available). There is a helper that facitilates this use case. The implementation is clear enough IMO `(opts[:ars] || {}).each { |k, v| payload["#{k}_id"] = v.id }`. `:ars` means ActiveRecords. Note that `opts` is not stored in the database and `payload` should be fully sufficient to perform an **action**. `opts` provides an optimization.
+* `meta` (Hash): Additional metadata stored in the database alongside the `action_name` and `payload`. The `stream` key is particularly useful for scoping actions during reversions. For example, you can construct a `stream` based on the owner of action.
 
-#### Dispatch action
+Example:
 
 ```ruby
 Rdux.perform(
-  Activity::Stop,
-  { activity_id: current_activity.id },
-  { activity: current_activity },
+  Task::Create,
+  { task: { name: 'Foo bar baz' } },
+  { ars: { user: current_user } },
   meta: {
-    stream: { user_id: 123, context: 'foo' }, bar: 'baz'
+    stream: { user_id: current_user.id, context: 'foo' },
+    bar: 'baz'
   }
 )
 ```
 
-#### Return
+### 📈 Flow diagram
+
+![Flow Diagram](docs/flow.png)
+
+### 💪 Action
+
+An action in Rdux is a Plain Old Ruby Object (PORO) that implements a class or instance method `call` or `up`.  
+This method must return an `Rdux::Result` `struct`.  
+Optionally, an action can implement a class or instance method `down` to specify how to revert it.
+
+#### Action Structure:
+
+* `call` or `up` method: Accepts a required `payload` and an optional `opts` argument. This method processes the action and returns an `Rdux::Result`.
+* `down` method: Accepts the deserialized `down_payload` which is one of arguments of the `Rdux::Result` `struct` returned by the `up` method on success and saved in DB. `down` method can optionally accept the 2nd argument (Hash) which `:nested` key contains nested `Rdux::Action`s
+
+See [🚛 Dispatching an action](#-dispatching-an-action) section.
+
+Examples:
 
 ```ruby
-Rdux::Result[true, { activity: activity }]
+# app/actions/task/create.rb
+
+class Task
+  class Create
+    def up(payload, opts)
+      user = opts.dig(:ars, :user) || User.find(payload['user_id'])
+      task = user.tasks.new(payload['task'])
+      if task.save
+        Rdux::Result[ok: true, down_payload: { user_id: user.id, task_id: task.id }, val: { task: }]
+      else
+        Rdux::Result[false, { errors: task.errors }]
+      end
+    end
+
+    def down(payload)
+      Delete.up(payload)
+    end
+  end
+end
 ```
 
-## Installation
-Add this line to your application's Gemfile:
+```ruby
+# app/actions/task/delete.rb
+
+class Task
+  module Delete
+    def self.up(payload)
+      user = User.find(payload['user_id'])
+      task = user.tasks.find(payload['task_id'])
+      task.destroy
+      Rdux::Result[true, { task: task.attributes }]
+    end
+  end
+end
+```
+
+#### Suggested Directory Structure:
+
+The location that is often used for entities like actions accross code bases is `app/services`.  
+This directory is de facto the bag of random objects.  
+I'd recomment to place actions inside `app/actions` for better organization and consistency.  
+Actions are consistent in terms of structure, input and output data.  
+They are good canditates to create a new layer in Rails apps.
+
+Structure:
+
+```
+.
+└── app/actions/
+    ├── activity/
+    │   ├── common/
+    │   │   └── fetch.rb
+    │   ├── create.rb
+    │   ├── stop.rb
+    │   └── switch.rb
+    ├── task/
+    │   ├── create.rb
+    │   └── delete.rb
+    └── misc/
+        └── create_attachment.rb
+```
+
+The [dedicated page about actions](docs/ACTIONS.md) contains more arguments in favor of actions.
+
+### ⛩️ Returned `struct` `Rdux::Result`
+
+Definition:
 
 ```ruby
-gem 'rdux'
+module Rdux
+  Result = Struct.new(:ok, :down_payload, :val, :up_result, :save, :after_save, :nested, :action) do
+    def val
+      self[:val] || down_payload
+    end
+
+    def save_failed?
+      ok == false && save
+    end
+  end
+end
 ```
 
-And then execute:
-```bash
-$ bundle
+Arguments:
+
+* `ok` (Boolean): Indicates whether the action was successful. If `true`, the `Rdux::Action` is persisted in the database.
+* `down_payload` (Hash): Passed to the action’s `down` method during reversion (`down` method is called on `Rdux::Action`). It does not have to be defined if an action does not implement the `down` method. `down_payload` is saved in the DB.
+* `val` (Hash): Contains any additional data to return besides down_payload.
+* `up_result` (Hash): Stores data related to the action’s execution, such as created record IDs, DB changes, responses from 3rd parties, etc.
+* `save` (Boolean): If `true` and `ok` is `false`, the action is saved as a `Rdux::FailedAction`.
+* `after_save` (Proc): Called just before the `dispatch` method returns the `Rdux::Result` with `Rdux::Action` or `Rdux::FailedAction` as an argument.
+* `nested` (Array of `Rdux::Result`): `Rdux::Action` can be connected with other `rdux_actions`. `Rdux::FailedAction` can be connected with other `rdux_actions` and `rdux_failed_actions`. To establish an association, a given action must `Rdux.dispatch` other actions in the `up` or `call` method and add the returned by the `dispatch` value (`Rdux::Result`) to the `:nested` array
+* `action`: Rdux assigns `Rdux::Action` or `Rdux::FailedAction` to this argument
+
+### ⏮️ Reverting an Action
+
+To revert an action, call the `down` method on the persisted in DB `Rdux::Action` instance.  
+The `Rdux::Action` must have a `down_payload` defined and the action (action performer) must have the `down` method implemented.
+
+![Revert action](docs/down.png)
+
+The `down_at` attribute is set upon successful reversion. Actions cannot be reverted if there are newer, unreverted actions in the same stream (if defined) or in general. See `meta` in [🚛 Dispatching an action](#-dispatching-an-action) section.
+
+### 🗿 Data model
+
+```ruby
+payload = {
+  task: { 'name' => 'Foo bar baz' },
+  user_id: 159163583
+}
+
+res = Rdux.dispatch(Task::Create, payload)
+
+res.action
+# #<Rdux::Action:0x000000011c4d8e98
+#   id: 1,
+#   name: "Task::Create",
+#   up_payload: {"task"=>{"name"=>"Foo bar baz"}, "user_id"=>159163583},
+#   down_payload: {"task_id"=>207620945},
+#   down_at: nil,
+#   up_payload_sanitized: false,
+#   up_result: nil,
+#   meta: {},
+#   stream_hash: nil,
+#   rdux_action_id: nil,
+#   rdux_failed_action_id: nil,
+#   created_at: Fri, 28 Jun 2024 21:35:36.838898000 UTC +00:00,
+#   updated_at: Fri, 28 Jun 2024 21:35:36.839728000 UTC +00:00>>
+
+res.action.down
 ```
 
-Or install it yourself as:
-```bash
-$ gem install rdux
+### 😷 Sanitization
+
+When calling `Rdux.perform`, the `up_payload` is sanitized using `Rails.application.config.filter_parameters` before saving to the database.  
+The action’s `up` or `call` method receives the unsanitized version.  
+Note that if the `up_payload` is sanitized, the `Rdux::Action` cannot be retried via calling the `#up` method.
+
+### 🗣️ Queries
+
+Most likely, it won't be needed to save a `Rdux::Action` for every request a Rails app receives.  
+The suggested approach is to save `Rdux::Action`s for Create, Update, and Delete (CUD) operations.  
+This approach organically creates a new layer - queries in addition to actions.  
+Thus, it is required to call `Rdux.perform` only for actions.
+
+An example approach is to create the `perform` method that calls `Rdux.perform` or a query depending on the presence of `action` or `query` keywords.  
+This method can set `meta` attributes, fulfill params validation, etc.
+
+Example:
+
+```ruby
+class TasksController < ApiController
+  def show
+    perform(
+      query: Task::Show,
+      payload: { id: params[:id] }
+    )
+  end
+
+  def create
+    perform(
+      action: Task::Create,
+      payload: create_task_params
+    )
+  end
+end
 ```
 
-## Test
+### 🕵️ Indexing
 
-### Setup
+ Depending on your use case, create indices, especially when using PostgreSQL and querying based on JSONB columns.  
+Both `Rdux::Action` and `Rdux::FailedAction` are standard ActiveRecord models.  
+You can inherit from them and extend.  
+Depending on your use case, create indices, especially when using PostgreSQL and querying based on `JSONB` columns.  
+
+Example:
+```ruby
+class Action < Rdux::Action
+  include Actionable
+end
+```
+
+## 👩🏽‍🔬 Testing
+
+### 💉 Setup
 
 ```bash
 $ cd test/dummy
@@ -57,12 +288,17 @@ $ DB=all bin/rails db:prepare
 $ cd ../..
 ```
 
-### Run tests
+### 🧪 Run tests
 
 ```bash
 $ DB=postgres bin/rails test
 $ DB=sqlite bin/rails test
 ```
 
-## License
+## 📄 License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 👨‍🏭 Author
+
+Zbigniew Humeniuk from [Art of Code](https://artofcode.co)

data/app/models/rdux/action.rb

@@ -63,15 +63,15 @@ module Rdux
       return if performer.nil?
 
       if opts.any? || performer.method(meth).arity.abs == 2
-        performer.public_send(meth, payload, opts.merge(action: self))
+        performer.public_send(meth, payload, opts.merge!(action: self))
       else
         performer.public_send(meth, payload)
       end
     end
 
     def build_opts
+      nested = rdux_actions.order(:created_at)
       {}.tap do |h|
-        nested = rdux_actions.order(:created_at)
         h[:nested] = nested if nested.any?
       end
     end

data/lib/rdux/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rdux
-  VERSION = '0.9.1'
+  VERSION = '0.10.0'
 end

data/lib/rdux.rb

@@ -13,6 +13,7 @@ module Rdux
       sanitize(action)
       action.save!
       res = call_call_or_up_on_action(action, opts)
+      res.up_result ||= opts[:up_result]
       assign_and_persist(res, action)
       res.after_save&.call(res.action)
       res
@@ -31,7 +32,7 @@ module Rdux
 
       action.up(opts)
     rescue StandardError => e
-      handle_exception(e, action)
+      handle_exception(e, action, opts[:up_result])
     end
 
     def no_down(res)
@@ -80,14 +81,13 @@ module Rdux
       action.up_payload = up_payload_sanitized
     end
 
-    def handle_exception(exc, action)
+    def handle_exception(exc, action, up_result)
       failed_action = action.to_failed_action
-      failed_action.up_result = {
-        'Exception' => {
-          class: exc.class.name,
-          message: exc.message
-        }
-      }
+      failed_action.up_result ||= up_result || {}
+      failed_action.up_result.merge!({ 'Exception' => {
+                                       class: exc.class.name,
+                                       message: exc.message
+                                     } })
       failed_action.save!
       action.destroy
       raise exc

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rdux
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: ruby
 authors:
 - Zbigniew Humeniuk
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-08 00:00:00.000000000 Z
+date: 2024-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -36,59 +36,60 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.5.4
+        version: 1.5.8
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.5.4
+        version: 1.5.8
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.59.0
+        version: 1.66.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.59.0
+        version: 1.66.1
 - !ruby/object:Gem::Dependency
   name: rubocop-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.23.1
+        version: 2.26.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.23.1
+        version: 2.26.0
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.7.0
+        version: 2.1.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.7.0
-description: |
-  Write apps that are easy to test.
-  It makes it easy to trace when, where, why, and how your application's state changed.
+        version: 2.1.0
+description: "Rdux is a lightweight, minimalistic Rails plugin designed to introduce
+  event sourcing and audit logging capabilities to your Rails application. \nWith
+  Rdux, you can efficiently track and store the history of actions performed within
+  your app, offering transparency and traceability for key processes.\n"
 email:
 - hello@artofcode.co
 executables: []
@@ -128,8 +129,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
-summary: Rdux adds a new layer to Rails apps - actions.
+summary: A Minimal Event Sourcing Plugin for Rails
 test_files: []