rdux 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb70d8633e88f42179223f60bfe5634273591875f0e3d104fb076128af8811ba
-  data.tar.gz: 375487c3f51b78803b9d610877edb5e5fcec70918e86e376cf2601188a9e4358
+  metadata.gz: 15cd57ce4ac093218d95c279b804de8b5d2bab76b4e81697252559a848fabbd3
+  data.tar.gz: 41c9436b74cd2bdf9bfc9ea877b8bb266463af5d5a10e20979c3135c4ed8e974
 SHA512:
-  metadata.gz: 4fbd330495ba4b140f828dc2e5184e27f4abd653c9e8d314d8a576c4612294c8baca8aceeeeccdab1e8be184a566544daaf1a75bc2dab2f1bba1801aab7f11cd
-  data.tar.gz: da3820133a5d277e1b5a20eee3876efb13e7cd434105585a3b2da5a014062072e17a77a93b35f35bb601d1f7d6c30dc4b930adb9e0f56e99aaeb358f1b9629e8
+  metadata.gz: f3cf61749ab041d56909e3b77430f9d59a9277b01af2741eb18479cebcc88f7c7569820f2e8d80b75235a2744eff39d908da6ef7d89d6ff120d68e19f29b1a3b
+  data.tar.gz: 63eb19f6a5ca7334ff82c074d48c5d35736f45689477ce731061fe8b984e9dc2aaf22c43d052e170138473016cf9aac824e06936d15c58dbcfaaa6cd5a265b48

data/README.md

@@ -1,54 +1,336 @@
-# Rdux
-Minimal take on event sourcing.
+# Rdux - A Minimal Event Sourcing Plugin for Rails
 
-## Usage
+<div align="center">
+
+  <div>
+    <img width="500px" src="docs/logo.webp">
+  </div>
+
+![GitHub](https://img.shields.io/github/license/artofcodelabs/rdux)
+![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/artofcodelabs/rdux)
+
+</div>
+
+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 performer) 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. `Rdux::FailedAction` retains the input data and processing results necessary for implementing custom mechanisms to retry failed actions.
+* **Exception Handling and Recovery** 👉 Rdux automatically creates a `Rdux::FailedAction` when an exception occurs during action execution. It retains the `up_payload` and allows you to capture additional data using `opts[:up_result]`, ensuring all necessary information is available for retrying the action.
+* **Metadata** 👉 Metadata can include the ID of the authenticated resource responsible for performing a given action, as well as resource IDs from external systems related to the action. This creates a clear audit trail of who executed each action and on whose behalf.
+* **Streams** 👉 Rdux enables the identification of action chains (streams) by utilizing resource IDs stored in metadata. This makes it easy to query and track related actions.
+
+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`).
 
-#### Dispatch action
+Definition:
+
+```ruby
+def dispatch(action, payload, opts = {}, meta: nil)
+
+alias perform dispatch
+```
+
+Arguments:
+
+* `action`: The name of the module or class (action performer) that processes the action. This is stored in the database as an instance of `Rdux::Action`, with its `name` attribute set to `action` (e.g., `Task::Create`).
+* `payload` (Hash): The input data passed as the first argument to the `call` or `up` method of the action performer. The data is sanitized and stored in the database before being processed by the action performer. During deserialization, the keys in the `payload` are converted to strings.
+* `opts` (Hash): Optional parameters passed as the second argument to the `call` or `up` method, if defined. This can help avoid redundant database queries (e.g., if you already have an ActiveRecord object available before calling `Rdux.perform`). A helper is available to facilitate this use case: `(opts[:ars] || {}).each { |k, v| payload["#{k}_id"] = v.id }`, where `:ars` represents ActiveRecord objects. Note that `opts` is not stored in the database, and the `payload` should be fully sufficient to perform an **action**. `opts` provides an optimization.
+* `meta` (Hash): Additional metadata stored in the database alongside the `action` and `payload`. The `stream` key is particularly useful for specifying the stream of actions used during reversions. For example, a `stream` can be constructed based on the owner of the 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)
+
+### 🕵️‍♀️ Processing an action
+
+Action in Rdux is processed by an action performer which is a Plain Old Ruby Object (PORO) that implements a class or instance method `call` or `up`.  
+This method must return a `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 a `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 performer’s `down` method during reversion (`down` method is called on `Rdux::Action`). It does not have to be defined if an action performer does not implement the `down` method. `down_payload` is saved in the DB.
+* `val` (Hash): Contains different returned data than `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 `Rdux.perform` is called, the `up_payload` is sanitized using `Rails.application.config.filter_parameters` before being saved to the database.  
+The action performer’s `up` or `call` method receives the unsanitized version.  
+Note that once the `up_payload` is sanitized, the `Rdux::Action` cannot be retried by calling the `#up` method.
+
+### 🗣️ Queries
+
+Most likely, it won't be necessary 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.
+
+One approach is to create a `perform` method that invokes either `Rdux.perform` or a query, depending on the presence of `action` or `query` keywords.  
+This method can also handle setting `meta` attributes, performing parameter validation, and more.
+
+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
+```
+
+### 🕵️ Indexing
+
+Depending on your use case, it’s recommended to create indices, especially when using PostgreSQL and querying JSONB columns.  
+Both `Rdux::Action` and `Rdux::FailedAction` are standard ActiveRecord models.  
+You can inherit from them and extend.
+
+Example:
+```ruby
+class Action < Rdux::Action
+  include Actionable
+end
 ```
 
-## Test
+### 🚑 Recovering from Exceptions
 
-### Setup
+Rdux creates a `Rdux::FailedAction` when an exception is raised during the execution of an action.  
+The `up_payload` is retained, but having only the input data is often not enough to retry an action.  
+It is crucial to capture data obtained during the action’s execution, up until the exception occurred.  
+This can be done by using `opts[:up_result]` to store all necessary data incrementally.  
+The assigned data will then be available as the `up_result` argument in the `Rdux::FailedAction`.
+
+Example:
+```ruby
+class CreditCard
+  class Charge
+    class << self
+      def call(payload, opts)
+        create_res = create(payload.slice('user_id', 'credit_card'), opts.slice(:user))
+        return create_res unless create_res.ok
+
+        opts[:up_result] = { credit_card_create_action_id: create_res.action.id }
+        charge_id = PaymentGateway.charge(create_res.val[:credit_card].token, payload['amount'])[:id]
+        if charge_id.nil?
+          Rdux::Result[ok: false, val: { errors: { base: 'Invalid credit card' } }, save: true,
+                       nested: [create_res]]
+        else
+          Rdux::Result[ok: true, val: { charge_id: }, nested: [create_res]]
+        end
+      end
+
+      private
+
+      def create(payload, opts)
+        res = Rdux.perform(Create, payload, opts)
+        return res if res.ok
+
+        Rdux::Result[ok: false, val: { errors: res.val[:errors] }, save: true, nested: [res]]
+      end
+    end
+  end
+end
+```
+
+## 👩🏽‍🔬 Testing
+
+### 💉 Setup
 
 ```bash
 $ cd test/dummy
@@ -57,12 +339,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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Rdux
-  class Action < ApplicationRecord
+  class Action < ActiveRecord::Base
     include Actionable
 
     attr_accessor :up_payload_unsanitized
@@ -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/app/models/rdux/failed_action.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Rdux
-  class FailedAction < ApplicationRecord
+  class FailedAction < ActiveRecord::Base
     include Actionable
 
     belongs_to :rdux_failed_action, optional: true, class_name: 'Rdux::FailedAction'

data/lib/rdux/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rdux
-  VERSION = '0.9.1'
+  VERSION = '0.11.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.11.0
 platform: ruby
 authors:
 - Zbigniew Humeniuk
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-08 00:00:00.000000000 Z
+date: 2025-03-12 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: []