rdux 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbb84ff27b098d28ad7395b590852b257851825cef51837d01a48c353e2b528e
-  data.tar.gz: b6bab2fc5e8685bf8ec774e1b3c76e8b533fe0f5e3cbe85d44564f4f04067202
+  metadata.gz: 15cd57ce4ac093218d95c279b804de8b5d2bab76b4e81697252559a848fabbd3
+  data.tar.gz: 41c9436b74cd2bdf9bfc9ea877b8bb266463af5d5a10e20979c3135c4ed8e974
 SHA512:
-  metadata.gz: bc9bd6c320bbbfe0f058234dee3c4729d64aa2a56d0568f26e896fc1fd9a63116a43d8e2634dc68995cb5f4fadb1cc6b30fdeabeee486e67aeedc3eb6e3c9294
-  data.tar.gz: 86eabdd326c7d46a3654b43f7e06faf79c4af7e00122ce25dda9b49ae1307df7436e536199c7ed31b4d6bdd08b9652abc3e7430eb18b72e936d5845b232b3467
+  metadata.gz: f3cf61749ab041d56909e3b77430f9d59a9277b01af2741eb18479cebcc88f7c7569820f2e8d80b75235a2744eff39d908da6ef7d89d6ff120d68e19f29b1a3b
+  data.tar.gz: 63eb19f6a5ca7334ff82c074d48c5d35736f45689477ce731061fe8b984e9dc2aaf22c43d052e170138473016cf9aac824e06936d15c58dbcfaaa6cd5a265b48

data/README.md

@@ -1,14 +1,26 @@
 # Rdux - A Minimal Event Sourcing Plugin for Rails
 
-![Logo](docs/logo.webp)
+<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) responsible for processing them, processing results, and additional metadata in the database.
+* **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 or retried.
+* **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.
 
@@ -50,17 +62,17 @@ To dispatch an action using Rdux, use the `dispatch` method (aliased as `perform
 Definition:
 
 ```ruby
-def dispatch(action_name, payload, opts = {}, meta: nil)
+def dispatch(action, 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.
+* `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:
 
@@ -80,15 +92,15 @@ Rdux.perform(
 
 ![Flow Diagram](docs/flow.png)
 
-### 💪 Action
+### 🕵️‍♀️ Processing an 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`.  
+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 an `Rdux::Result`.
+* `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.
@@ -181,8 +193,8 @@ end
 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.
+* `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.
@@ -229,19 +241,19 @@ res.action.down
 
 ### 😷 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.
+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 needed to save a `Rdux::Action` for every request a Rails app receives.  
+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.
 
-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.
+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:
 
@@ -265,10 +277,9 @@ end
 
 ### 🕵️ Indexing
 
- Depending on your use case, create indices, especially when using PostgreSQL and querying based on JSONB columns.  
+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.  
-Depending on your use case, create indices, especially when using PostgreSQL and querying based on `JSONB` columns.  
+You can inherit from them and extend.
 
 Example:
 ```ruby
@@ -277,6 +288,46 @@ class Action < Rdux::Action
 end
 ```
 
+### 🚑 Recovering from Exceptions
+
+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

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

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.10.0'
+  VERSION = '0.11.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rdux
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Zbigniew Humeniuk
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-25 00:00:00.000000000 Z
+date: 2025-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails