rails_ops 1.7.3 → 1.7.5

data/README.md

@@ -2,8 +2,7 @@
 [![Rubocop check](https://github.com/sitrox/rails_ops/actions/workflows/rubocop.yml/badge.svg)](https://github.com/sitrox/rails_ops/actions/workflows/rubocop.yml)
 [![Gem Version](https://badge.fury.io/rb/rails_ops.svg)](https://badge.fury.io/rb/rails_ops)
 
-rails_ops
-=========
+# rails_ops
 
 This Gem introduces an additional service layer for Rails: *Operations*. An
 operation is in most cases a *business action* or *use case* and may or may not
@@ -18,8 +17,7 @@ To achieve this goal, this Gem provides the following building blocks:
 
 - A way of abstracting model classes for a specific business action.
 
-Requirements & Installation
----------------------------
+## Requirements & Installation
 
 ### Requirements
 
@@ -90,10 +88,9 @@ Requirements & Installation
 
    Taken from [this github issues comment](https://github.com/rails/rails/issues/40126#issuecomment-816275285).
 
-Operation Basics
-----------------
+## Operation Basics
 
-### Placing and naming operations
+### Placing and Naming Operations
 
 - Operations generally reside in `app/operations` and can be nested using
   various subdirectories. They're all inside of the `Operations` namespace.
@@ -110,7 +107,7 @@ Operation Basics
   `MoveToPosition` and so on. Do not name an operation something like
   `UserCreator` or `CreateUserOperation`.
 
-#### Heads-up: Correct namespacing
+#### Heads-up: Correct Namespacing
 
 As explained in the previous section, operations should be namespaced properly.
 Operations can either live within a module or within a class. In most cases,
@@ -160,7 +157,7 @@ Note that, when defining a namespace of which a segment is already known as a
   end
   ```
 
-### Basic operations
+### Basic Operations
 
 Every single operation follows a few basic principles:
 
@@ -186,7 +183,7 @@ class Operations::PrintHelloWorld < RailsOps::Operation
 end
 ```
 
-### Running operations manually
+### Running Operations Manually
 
 There are various ways of instantiating and running an operation. The most
 basic way is the following:
@@ -212,7 +209,7 @@ models or ActiveRecord models, `run` does not only catch the
 `ActiveRecord::RecordInvalid` exception but also every exception that derives
 from {RailsOps::Exceptions::ValidationFailed}.
 
-#### Catching custom exceptions in `run`
+#### Catching Custom Exceptions in `run`
 
 If you'd like to catch a custom exception if the operation is called using
 `run`, you can either derive this exception from
@@ -229,7 +226,7 @@ class Operations::PrintHelloWorld < RailsOps::Operation
 end
 ```
 
-### Returning data from operations
+### Returning Data from Operations
 
 All operations have the same call signatures: `run` always returns `true` or
 `false` while `run!` always returns the operation instance (which allows easy
@@ -248,10 +245,9 @@ end
 puts Operations::GenerateHelloWorld.run!(name: 'John Doe').result
 ```
 
-Params Handling
----------------
+## Params Handling
 
-## Passing params to operations
+### Passing Params to Operations
 
 Each single operation can take a `params` hash. Note that it does not have to be
 in any relation with `ActionController`'s params - it's just a plain ruby hash
@@ -268,7 +264,7 @@ If no params are given, an empty params hash will be used. If a
 `ActionController::Parameters` object is passed, it will be permitted using
 `permit!` and converted into a regular hash.
 
-## Accessing params
+### Accessing Params
 
 For accessing params within an operation, you can use `params` or `osparams`.
 While `params` directly returns the params hash, `osparams` converts them into
@@ -287,9 +283,9 @@ end
 Note that both `params` and `osparams` return independent, deep duplicates of
 the original `params` hash to the operation, so the hashes do not correspond.
 
-The hash accessed via `params` is a always `Object::HashWithIndifferentAccess`.
+The hash accessed via `params` is always an `Object::HashWithIndifferentAccess`.
 
-## Validating params
+### Validating Params
 
 You're strongly encouraged to perform a validation of the parameters passed to
 an operation, as unvalidated params pose a security threat. This can be done in several ways:
@@ -310,7 +306,7 @@ an operation, as unvalidated params pose a security threat. This can be done in
 
   This is the recommended way of performing basic params validation. Please see the next section *Schema best practices* for more information.
 
-  See documentation of the Gem `schemacop` for more information on how to
+  See documentation of the gem `schemacop` for more information on how to
   specify schemata.
 
 
@@ -332,7 +328,7 @@ an operation, as unvalidated params pose a security threat. This can be done in
 
 - Using a business model (see chapter *Model Operations*).
 
-### Schema best practices
+### Schema Best Practices
 
 As previously mentioned, using schema from the `schemacop` gem is the recommended way to validate params passed in to an operation. In general, it's recommended to use version 3 of schemacop, i.e. either use `schema3` to specify the schema, or set the default schema version to 3:
 
@@ -343,7 +339,7 @@ RailsOps.configure do |config|
 end
 ```
 
-#### Internal code
+#### Internal Code
 
 When writing a schema for an operation which is only used internally (e.g. called from another operation, or called from a part of the code where you control the params, e.g. a rake task), it's recommended to specify the types of all items, as this will catch any mismatched data. For example:
 
@@ -360,7 +356,7 @@ class Operations::PrintHelloWorldWithId < RailsOps::Operation
   end
 ```
 
-#### Called within controllers
+#### Called Within Controllers
 
 On the other hand, operations which are called within controllers (e.g. to encapsulate an update operation of a model) should not assume any types, and instead use model validations (if applicable) to validate the correctness of the data. In this case, the schema should only be used to filter the params. As such, it's recommended to use `obj` to specify params which are not strings, as this will allow anything (but only the specified values). An example would be:
 
@@ -381,7 +377,7 @@ end
 
 Validating that `age` is an integer and `is_active` then should be done with a validation in the `User` model, as this will also populate the model errors, which in turn will display the error in the form. If you were to validate the type of the data here, it would raise a `Schemacop::Exceptions::ValidationError` exception, which you would need to handle seperately.
 
-Finally, when additional, obsolete params are supplied, the schema validation would also fail. To have a similar behavious to the strong params from Rails, which drop non-whitelisted params without raising an exception, you can use the `ignore_obsolete_properties` option. This will simply ignore and drop any params which are not explicitly whitelisted:
+Finally, when additional, obsolete params are supplied, the schema validation would also fail. To have a similar behaviour to the strong params from Rails, which drop non-whitelisted params without raising an exception, you can use the `ignore_obsolete_properties` option. This will simply ignore and drop any params which are not explicitly whitelisted:
 
 ```ruby
 module Operations::User
@@ -398,9 +394,9 @@ module Operations::User
 end
 ```
 
-### Catching schema validation errors
+### Catching Schema Validation Errors
 
-When an operation is called from a controller (via the `run` or `run!` method) and a schema validation excaption occurs, the controller will respond with an empty body and a status code `400` (bad request). This behaviour is enabled by default, but can be disabled with the `rescue_validation_error_in_controller` config option:
+When an operation is called from a controller (via the `run` or `run!` method) and a schema validation exception occurs, the controller will respond with an empty body and a status code `400` (bad request). This behaviour is enabled by default, but can be disabled with the `rescue_validation_error_in_controller` config option:
 
 ```ruby
 # config/initializers/rails_ops.rb
@@ -413,8 +409,7 @@ Generally, this should be left enabled, as sending invalid data to the controlle
 
 Please note that this behaviour is disabled in development mode, as the full exception messages are useful for debugging purposes.
 
-Policies
---------
+## Policies
 
 Policies are nothing more than blocks of code that run either at operation
 instantiation or before / after execution of the `perform` method and can be
@@ -449,7 +444,7 @@ method. Use policies as much as possible though to keep things separated.
 The return value of the policies is discarded. If a policy needs to fail, raise
 an appropriate exception.
 
-### Policy chains
+### Policy Chains
 
 As mentioned above, policies can be executed at various points in your
 operation's lifecycle. This is possible using *policy chains*:
@@ -484,6 +479,17 @@ operation's lifecycle. This is possible using *policy chains*:
   its descendants. Policies in this chain run after nested model operations are
   performed before performing any nested model operations.
 
+- `:before_model_validation`
+
+  This only applies to operations deriving from `RailsOps::Operation::Model`
+  and its descendants. Policies in this chain run right before
+  `model.validate!` is called inside `perform_nested_model_ops!`. This is
+  the correct place for attribute cleanup and sanitization — for example,
+  nilling out attributes that are irrelevant based on another attribute's
+  value (e.g. role-dependent fields after a form reload). At this point
+  the model's attributes are already assigned, so you can inspect and
+  modify them before validation runs.
+
 - `:after_perform`
 
   Policies in this chain run immediately after the `perform` method is called.
@@ -521,8 +527,7 @@ It is also important to note, that this block is
 not guaranteed to be run first in the chain, if multiple blocks have set `:prepend_action` to true.
 
 
-Calling sub-operations
-----------------------
+## Calling Sub-Operations
 
 It is possible and encouraged to call operations within operations if necessary.
 As the basic principle is to create one operation per business action, there are
@@ -551,7 +556,7 @@ within the context that is automatically adapted and passed to the sub-operation
 and enables to maintain the complete call stack and allows to pass on context
 information such as the current user.
 
-### A note on validations
+### A Note on Validations
 
 As always when calling operations, you can decide whether an execution should
 raise an exception on validation errors or else just return `false` by using the
@@ -574,15 +579,14 @@ catches any validation errors and re-throws them as
 {RailsOps::Exceptions::SubOpValidationFailed} which is not caught by the
 surrounding op.
 
-Contexts
---------
+## Contexts
 
 Most operations make use of generic parameters like the current user or an
 authorization ability. Sure this could all be passed using the `params` hash,
 but as this would have to be done for every single operation call, it would be
 quite cumbersome.
 
-For this reason Rails Ops provides a feature called *Contexts*. Contexts are
+For this reason, Rails Ops provides a feature called *Contexts*. Contexts are
 simple instances of {RailsOps::Context} that may or may not be passed to
 operations. Contexts can include the following data:
 
@@ -625,7 +629,7 @@ operations. Contexts can include the following data:
   called by a hook (true) or by a regular method call (false). We will introduce
   hooks below.
 
-### Instantiating contexts
+### Instantiating Contexts
 
 Contexts behave like a traditional model object and can be instantiated in
 multiple ways:
@@ -638,7 +642,7 @@ context = Context.new
 context.user = current_user
 ```
 
-### Feeding contexts to operations
+### Feeding Contexts to Operations
 
 Contexts are assigned to operations via the operation's constructor:
 
@@ -664,8 +668,7 @@ the parent operation.
 This is called *context spawning* and is performed using the
 {RailsOps::Context.spawn} method.
 
-Hooks
------
+## Hooks
 
 In some cases, certain actions must be hooked in after execution of an
 operation. While this can certainly be done with sub-operations, it is not
@@ -684,7 +687,7 @@ specify which operations should be triggered after which operations. These
 operations are then automatically triggered after the original operation's
 `perform` (in the `run` method).
 
-### Defining hooks
+### Defining Hooks
 
 Hooks are defined in a file named `config/hookup.rb` in your local application.
 In development mode, this file is automatically reloaded on each request so
@@ -736,7 +739,7 @@ end
 In most cases though, situations like these should rather be handled by
 explicitly calling a sub-operation.
 
-### Hook parameters
+### Hook Parameters
 
 For each hook that is called, at set of parameters is passed to the respective
 operations. When calling events manually (see section *Events*), you can
@@ -756,7 +759,7 @@ hooks into the source operation and prepares the params specifically for the
 target operation, which is then called using a sub-operation or the hooking
 system.
 
-### Check if called via hook
+### Check if Called via Hook
 
 You can determine whether your operation has been (directly) called via a hook
 using the `called_via_hook` context method:
@@ -774,11 +777,10 @@ sub-operation is set to `false` again.
 ### Authorization
 
 Operations called via hooks perform normal authorization per default. You can
-turn this off by switching off the gobal option
+turn this off by switching off the global option
 `config.trigger_hookups_without_authorization`.
 
-Authorization
--------------
+## Authorization
 
 Rails Ops offers backend-agnostic authorization using so-called
 *authorization backends*.
@@ -787,7 +789,7 @@ Authorization basically happens by calling the method `authorize!` (or
 `authorize_only!`, more on that later) within an operation. What exactly this
 method does depends on the *authorization backend* specified.
 
-### Authorization backends
+### Authorization Backends
 
 Authorization backends are simple classes that supply the method `authorize!`.
 This method, besides the operation instance, can take any number of arguments
@@ -807,12 +809,12 @@ end
 
 RailsOps ships with the following backend:
 
-- `RailsOps::AutorizationBackend::Cancancan`
+- `RailsOps::AuthorizationBackend::CanCanCan`
 
-  Offers integration of the `cancancan` Gem (which is a fork of the `cancan`
-  Gem).
+  Offers integration of the `cancancan` gem (which is a fork of the `cancan`
+  gem).
 
-### Performing authorization
+### Performing Authorization
 
 Authorization is generally performed by calling `authorize!` in an operation.
 The arguments, along with the operation instance, are passed on to the
@@ -853,7 +855,7 @@ end
 
 See section *Policy chains* for more information.
 
-### Ensure that authorization has been performed
+### Ensure That Authorization Has Been Performed
 
 As it is a very common programming mistake to mistakenly omit calling
 authorization, Rails Ops offers a solution for making sure that authorization
@@ -887,7 +889,7 @@ end
 This method otherwise does exactly the same as `authorize!` (in fact, it's the
 underlying method used by it).
 
-### Param authorization
+### Param Authorization
 
 Using the static operation method `authorize_param`, you can perform additional
 authorization checks when specific params are passed to the operation. This
@@ -940,7 +942,7 @@ class Operations::User::Create < RailsOps::Operation::Model::Create
   authorize_param %i(user group_id), :assign_group_id
 ```
 
-### Disabling authorization
+### Disabling Authorization
 
 Sometimes you don't want a specific operation to perform authorization, or you
 don't want to perform any authorization at all.
@@ -1045,8 +1047,7 @@ Rails Ops offers multiple ways of disabling authorization:
   ```
 
 
-Model Operations
-----------------
+## Model Operations
 
 One of the key features of RailsOps is model operations. RailsOps provides
 multiple operation base classes which allow convenient manipulation of active
@@ -1059,7 +1060,7 @@ inherit from {RailsOps::Operation::Model} (which in turn inherits from
 The key principle behind these model classes is to associate *one model class*
 and *one model instance* with a particular operation.
 
-### Setting a model class
+### Setting a Model Class
 
 Using the static method `model`, you can assign a model class that is used in
 the scope of this operation.
@@ -1097,7 +1098,7 @@ class SomeOperation < RailsOps::Operation::Model
 end
 ```
 
-### Obtaining a model instance
+### Obtaining a Model Instance
 
 Model instances can be obtained using the *instance* method `model`, which is
 not to be confused with the *class* method of the same name. Other than the
@@ -1126,7 +1127,7 @@ If no cached instance is found, one is built using the instance method
 but only implemented in its subclasses. You can implement and override this
 method to your liking though.
 
-### Loading models
+### Loading Models
 
 Using the base operation class {RailsOps::Operation::Model::Load}, a model can
 be loaded. This is done by implementing the `build_model` mentioned above. In
@@ -1150,7 +1151,7 @@ order to load a model (in fact, it cannot be run unless you override the
 based on a model instance without actually performing any particular action such
 as updating a model.
 
-#### Specifying ID field
+#### Specifying ID Field
 
 Per default, the model instance is looked up using the field `id` and the ID
 obtained from the method params using `params[:id]`. However, you can customize
@@ -1205,9 +1206,9 @@ class Operations::User::Update < RailsOps::Operation::Model::Load
 end
 ```
 
-One caveat is, that shared locking is only supported for MySQl (MariaDB),
-Postgresql and Oracle DB databases, any other database will always use an
-exlusive lock.
+One caveat is that shared locking is only supported for MySQL (MariaDB),
+PostgreSQL and Oracle DB databases, any other database will always use an
+exclusive lock.
 
 You can also dynamically enable or disable locking by creating an instance
 method `lock_model_at_build?`:
@@ -1225,7 +1226,7 @@ class Operations::User::Update < RailsOps::Operation::Model::Load
 end
 ```
 
-### Creating models
+### Creating Models
 
 For creating models, you can use the base class
 {RailsOps::Operation::Model::Create}.
@@ -1255,7 +1256,7 @@ end
 As this base class is very minimalistic, it is recommended to fully read and
 comprehend its source code.
 
-#### Overriding the perform method
+#### Overriding the Perform Method
 
 While in many cases there is no need for overriding the `perform` method, this
 can be useful i.e. when assigning or altering properties manually:
@@ -1269,7 +1270,7 @@ def perform
 end
 ```
 
-### Updating models
+### Updating Models
 
 For updating models, you can use the base class
 {RailsOps::Operation::Model::Update} which is an extension of the `Load` base
@@ -1304,7 +1305,7 @@ comprehend its source code.
 As with `Create` operations, the `perform` method can be overwritten at your
 liking.
 
-### Destroying models
+### Destroying Models
 
 For destroying models, you can use the base class
 {RailsOps::Operation::Model::Destroy} which is an extension of the `Load` base
@@ -1326,9 +1327,9 @@ end
 As this base class is very minimalistic, it is recommended to fully read and
 comprehend its source code.
 
-### Including associated records
+### Including Associated Records
 
-Normaly, when inheriting from `RailsOps::Operation::Model::Load` (as well as from the
+Normally, when inheriting from `RailsOps::Operation::Model::Load` (as well as from the
 `Update` and the `Destroy` operations respectively), RailsOps only loads the instance
 of the model specified by the `id` parameter. In some cases, you'd want to eagerly load
 associations of the model, e.g. when you need to access associated records.
@@ -1354,7 +1355,7 @@ class Operations::User::Load < RailsOps::Operation::Model::Load
 end
 ```
 
-### Parameter extraction for create and update
+### Parameter Extraction for Create and Update
 
 As mentioned before, the `Create` and `Update` base classes provide an
 implementation of `build_model` that assigns parameters to a model.
@@ -1363,12 +1364,12 @@ The attributes are determined by the operation instance method
 `extract_attributes_from_params` - the name being self-explaining. See its
 source code for implementation details.
 
-### Model authorization
+### Model Authorization
 
 While you can use the standard `authorize!` method (see chapter *Authorization*)
 for authorizing models, RailsOps provides a more convenient integration.
 
-#### Basic authorization
+#### Basic Authorization
 
 Model authorization can be performed via the operation instance methods
 `authorize_model!` and `authorize_model_with_authorize_only!` (see chapter
@@ -1384,7 +1385,7 @@ methods instead of the basic authorization methods for authorizing models.
 If no model is given, the model authorization methods automatically obtain the
 model from the instance method `model`.
 
-#### Automatic authorization
+#### Automatic Authorization
 
 All model operation classes provide the operation instance method
 `model_authorization` which is automatically run at model instantiation (this is
@@ -1426,7 +1427,7 @@ end
 Note that using the different model base classes, this is already set to a
 sensible default. See the respective class' source code for details.
 
-#### Lazy model update authorization
+#### Lazy Model Update Authorization
 
 *Please note that using lazy model update authorization is deprecated any may
 be removed in a future release. See the changelog for instructions on how to
@@ -1449,7 +1450,7 @@ class Operations::User::Update < RailsOps::Operation::Model::Update
 end
 ```
 
-### Model nesting
+### Model Nesting
 
 Using active record, multiple nested models can be saved at once by using
 `accepts_nested_attributes_for`. While this is generally supported by RailsOps,
@@ -1477,7 +1478,6 @@ class Operations::Group::Create < RailsOps::Operation::Model::Create
   end
 
   model ::Group
-  nest_model_op :group, Operations::Group::Create
 end
 ```
 
@@ -1495,7 +1495,7 @@ class User
 end
 ```
 
-#### Param key
+#### Param Key
 
 When nesting a model operation, the sub operation is called automatically by
 RailsOps. For this purpose, it needs to know which `param_key` to use for
@@ -1510,7 +1510,7 @@ using the option `param_key`, e.g.:
 nest_model_op :group, Operations::Group::Create, param_key: :my_custom_key
 ```
 
-#### Custom parameters
+#### Custom Parameters
 
 In the above examples, all `group_attributes` are automatically passed to the
 sub operation. To customize this further, provide a block to the `nest_model_op`
@@ -1526,10 +1526,10 @@ This block receives the params hash as it would be passed to the sub operation
 and allows to modify it. The block's return value is then passed to the
 sub-operation. Do not change the params inplace but instead return a new hash.
 
-### Single-table inheritance
+### Single-Table Inheritance
 
 Model operations also support STI models (Single Table Inheritance). However,
-there is the caviat that if you do extend your model in the operation (e.g.
+there is the caveat that if you do extend your model in the operation (e.g.
 `model Animal do { ... }`), RailsOps automatically creates an anonymous subclass
 of the given class (e.g. `Animal`). Operations will always load / create models
 that are instances of this anonymous class.
@@ -1548,22 +1548,373 @@ class LoadAnimal < RailsOps::Operation::Model::Load
 end
 
 bird = Bird.create
-op_bird = LoadAnimal.new(id: bird.id)
+op = LoadAnimal.new(id: bird.id)
+
+bird.class        # => Bird (extending Animal)
+op.model.class    # => Anonymous class extending Animal, not Bird
+```
+
+## Record Extension and Virtual Records
+
+RailsOps provides powerful features for extending ActiveRecord models and
+creating virtual records without affecting your actual model classes. This is
+achieved through the use of ActiveType and anonymous class generation.
+
+### Virtual Models
+
+Virtual models are non-persisted models that behave like ActiveRecord models
+but exist only in memory. They're useful for:
+
+- Form objects that don't map directly to database tables
+- Temporary data structures for complex operations
+- Aggregating data from multiple sources
+
+RailsOps provides `RailsOps::VirtualModel` which extends `ActiveType::Object`:
+
+```ruby
+class Operations::Contact::Create < RailsOps::Operation::Model::Create
+  model do
+    # Virtual attributes
+    attribute :full_name, :string
+    attribute :email, :string
+    attribute :message, :text
+    attribute :newsletter_opt_in, :boolean, default: false
+
+    # Validations work just like regular models
+    validates :full_name, :email, :message, presence: true
+    validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+  end
+
+  def perform
+    # Process the virtual model data
+    ContactMailer.contact_form(
+      name: model.full_name,
+      email: model.email,
+      message: model.message
+    ).deliver_later
+
+    # Optionally subscribe to newsletter
+    if model.newsletter_opt_in
+      NewsletterService.subscribe(model.email)
+    end
+  end
+end
+```
+
+### Model Extension
+
+When you specify a model with a block in an operation, RailsOps creates an
+anonymous subclass that extends your model without modifying the original:
+
+```ruby
+class Operations::User::Import < RailsOps::Operation::Model::Create
+  model User do
+    # These changes only apply within this operation
+    attribute :import_source, :string
+    attribute :skip_notifications, :boolean, default: false
+
+    validates :import_source, presence: true
+
+    # Override methods
+    def name=(value)
+      super(value.strip.titleize)
+    end
+
+    # Add callbacks specific to this operation
+    before_save :normalize_phone_number
+
+    private
+
+    def normalize_phone_number
+      self.phone = PhoneNumberService.normalize(phone) if phone.present?
+    end
+  end
+
+  def perform
+    model.imported_at = Time.current
+    super
+
+    unless model.skip_notifications
+      UserMailer.welcome(model).deliver_later
+    end
+  end
+end
+```
+
+### Virtual Attributes
+
+Virtual attributes allow you to add non-persisted attributes to your models
+that behave like regular attributes:
+
+```ruby
+class Operations::Order::Checkout < RailsOps::Operation::Model::Update
+  model Order do
+    # Virtual attributes for checkout process
+    attribute :card_number, :string
+    attribute :card_cvv, :string
+    attribute :card_exp_month, :integer
+    attribute :card_exp_year, :integer
+    attribute :save_card, :boolean, default: false
+
+    # Validations for virtual attributes
+    validates :card_number, presence: true, length: { is: 16 }
+    validates :card_cvv, presence: true, length: { in: 3..4 }
+    validates :card_exp_month, inclusion: { in: 1..12 }
+    validates :card_exp_year, numericality: {
+      greater_than_or_equal_to: Date.current.year
+    }
+
+    # Virtual attribute for computed values
+    attribute :total_with_tax, :decimal
+
+    before_validation :calculate_total_with_tax
+
+    private
+
+    def calculate_total_with_tax
+      self.total_with_tax = total * (1 + tax_rate)
+    end
+  end
 
-bird.class    # => Class "Bird", extending "Animal"
-op_bird.class # => Anonymous class, extending "Animal", not "Bird"
+  def perform
+    # Process payment with virtual attributes
+    payment_result = PaymentGateway.charge(
+      amount: model.total_with_tax,
+      card_number: model.card_number,
+      cvv: model.card_cvv,
+      exp_month: model.card_exp_month,
+      exp_year: model.card_exp_year
+    )
+
+    if payment_result.success?
+      model.payment_id = payment_result.transaction_id
+      model.paid_at = Time.current
+      super # Save the order
+
+      # Optionally save card for future use
+      if model.save_card
+        CreatePaymentMethod.run!(
+          user: model.user,
+          token: payment_result.card_token
+        )
+      end
+    else
+      fail PaymentError, payment_result.error_message
+    end
+  end
+end
 ```
 
-Record extension and virtual records
-------------------------------------
+### Combining Real and Virtual Models
+
+You can create operations that work with both persisted and virtual data:
+
+```ruby
+class Operations::Report::Generate < RailsOps::Operation::Model
+  model do
+    attribute :start_date, :date
+    attribute :end_date, :date
+    attribute :include_archived, :boolean, default: false
+    attribute :format, :string, default: 'pdf'
+
+    validates :start_date, :end_date, presence: true
+    validate :end_date_after_start_date
+
+    private
+
+    def end_date_after_start_date
+      return unless start_date && end_date
+      errors.add(:end_date, 'must be after start date') if end_date < start_date
+    end
+  end
+
+  def perform
+    scope = Order.where(created_at: model.start_date..model.end_date)
+    scope = scope.includes(:archived) if model.include_archived
+
+    report_data = ReportBuilder.new(scope).generate
+
+    case model.format
+    when 'pdf'
+      ReportPdfGenerator.new(report_data).to_pdf
+    when 'csv'
+      ReportCsvGenerator.new(report_data).to_csv
+    else
+      report_data
+    end
+  end
+end
+```
+
+## Transactions
+
+When working with database operations, it's crucial to ensure data consistency
+using transactions, especially when multiple models are involved.
+
+### Transaction Behavior in Model Operations
 
+It's important to understand that RailsOps model operations do NOT automatically
+start any transactions.
 
-Transactions
-------------
+To ensure all operations succeed or fail together, you must explicitly wrap them
+in a transaction:
+
+```ruby
+class Operations::Order::Process < RailsOps::Operation::Model::Update
+  def perform
+    ActiveRecord::Base.transaction do
+      model.status = 'processing'
+      model.processed_at = Time.current
+      super # Saves the order
+
+      # Now if this fails, everything is rolled back
+      OrderItem.where(order: model).update_all(status: 'processing')
+      InventoryService.reserve_items(model.items)
+    end
+  end
+end
+```
+
+Typically though, transactions are opened on a higher level and outside of
+operations, e.g. in controller methods.
+
+### Rollback on Exception
+
+When using `run` (without bang), validation errors are caught and may not cause
+transaction rollback. The `with_rollback_on_exception` helper ensures that
+exceptions within its block are re-raised as `RollbackRequired`, which will
+cause a rollback even when using `run`:
+
+```ruby
+class Operations::User::ComplexUpdate < RailsOps::Operation::Model::Update
+  def perform
+    ActiveRecord::Base.transaction do
+      super # Saves the user
+
+      # Without with_rollback_on_exception, validation errors here won't
+      # roll back the transaction when the operation is called with run
+      with_rollback_on_exception do
+        model.profile.bio = params[:bio]
+        model.profile.save! # If this fails, transaction is rolled back
+
+        model.settings.notifications = params[:notifications]
+        model.settings.save! # If this fails, transaction is rolled back
+      end
+    end
+  end
+end
+
+class UsersController < ApplicationController
+  def update
+    ActiveRecord::Base.transaction do
+      if run Operations::User::ComplexUpdate
+        render json: { status: :success }
+      else
+        render json: { status: :validation_error }
+      end
+    end
+  end
+end
+```
+
+**Important**: `with_rollback_on_exception` only works within an existing
+transaction. It doesn't create a transaction - it just ensures exceptions
+cause rollback:
+
+```ruby
+class Operations::Order::Process < RailsOps::Operation::Model::Update
+  def perform
+    # PROBLEMATIC: Each save creates its own transaction
+    super # Order is saved and committed in its own transaction
+
+    with_rollback_on_exception do
+      model.line_items.each { |item| item.update!(status: 'processed') }
+    end
+  end
+end
+
+# CORRECT: Wrap in a transaction
+class Operations::Order::Process < RailsOps::Operation::Model::Update
+  def perform
+    ActiveRecord::Base.transaction do
+      super # Order is saved
+
+      with_rollback_on_exception do
+        model.line_items.each { |item| item.update!(status: 'processed') }
+      end
+    end
+  end
+end
+```
+
+### After Commit Callbacks
+
+When no explicit transaction is used, each `save!` opens and commits its own
+transaction. You can use Rails' after_commit callbacks in your model
+extensions for actions that should only run after successful database commits:
+
+```ruby
+# Using after_commit callbacks in model extension
+class Operations::User::Create < RailsOps::Operation::Model::Create
+  model User do
+    after_commit :send_notifications, on: :create
+
+    private
+
+    def send_notifications
+      UserMailer.welcome(self).deliver_later
+      CrmSyncJob.perform_later(self)
+    end
+  end
+end
+
+# Or handle it manually after the operation
+class Operations::Order::Complete < RailsOps::Operation::Model::Update
+  def perform
+    ActiveRecord::Base.transaction do
+      model.status = 'completed'
+      model.completed_at = Time.current
+      super
+    end
+
+    # This runs after the transaction commits successfully
+    # If there was an exception, we never get here
+    OrderMailer.completed(model).deliver_later
+  end
+end
+```
+
+**Note**: Be careful with after_commit callbacks when using transactions.
+They fire after each transaction commits, not after all nested transactions
+complete.
+
+### Important Notes on Transactions
+
+1. **Validation Errors**: When using `run` (without bang), validation errors
+   are caught and won't roll back the transaction. Use `run!` for
+   sub-operations to ensure transaction rollback on validation errors.
+
+2. **External Services**: Be careful when calling external services within
+   transactions. Long-running external calls can cause database locks:
+
+   ```ruby
+   def perform
+     ActiveRecord::Base.transaction do
+       model.save!
+
+       # DON'T: This could lock the database for a long time
+       # ExternalApi.slow_request(model)
+     end
+
+     # DO: Call external services after the transaction
+     ExternalApi.slow_request(model)
+   end
+   ```
 
+3. **Nested Transactions**: Rails uses savepoints for nested transactions,
+   which are fully supported by RailsOps operations.
 
-Controller Integration
-----------------------
+## Controller Integration
 
 While RailsOps certainly does not have to be used from a controller, it
 provides a mixin which extends controller classes with functionality that lets
@@ -1581,7 +1932,7 @@ class ApplicationController
 end
 ```
 
-### Basic usage
+### Basic Usage
 
 The basic concept behind controller integration is to instantiate and
 potentially run a single operation per request. Most of this guide refers to
@@ -1599,7 +1950,7 @@ class SomeController < ApplicationController
 end
 ```
 
-### Separating instantiation and execution
+### Separating Instantiation and Execution
 
 In the previous example, we instantiated and ran an operation in a single
 statement. While this might be feasible for some "fire-and-forget" controller
@@ -1647,12 +1998,12 @@ def update_username
 end
 ```
 
-### Checking for operations
+### Checking for Operations
 
 Using the method `op?`, you can check whether an operation has already been
 instantiated (using `op`).
 
-### Model shortcut
+### Model Shortcut
 
 RailsOps conveniently provides you with a `model` instance method, which is a
 shortcut for `op.model`. This is particularly useful since this is available as
@@ -1661,7 +2012,7 @@ a view helper method as well, see next section.
 You can check whether a model is available by using the `model?` method, which
 is available in both controllers and views.
 
-### View helper methods
+### View Helper Methods
 
 The following controller methods are automatically provided as helper methods
 which can be used in views:
@@ -1705,7 +2056,7 @@ You can also combine these two approaches:
 op SomeOperation, some_param: op_params.slice(:some_param, :some_other_param)
 ```
 
-### Authorization ensuring
+### Authorization Ensuring
 
 For security reasons, RailsOps automatically checks after each action whether
 authorization has been performed. This is to avoid serving an action's response
@@ -1733,7 +2084,7 @@ automatically created. The following fields are set automatically:
 - `session` (uses the `session` controller method)
 - `url_options` (uses the `url_options` controller method)
 
-### Multiple operations per request
+### Multiple Operations per Request
 
 RailsOps does not currently support calling multiple operations in a single
 controller action out-of-the-box. You need to instantiate and run it manually.
@@ -1741,11 +2092,9 @@ controller action out-of-the-box. You need to instantiate and run it manually.
 Another approach is to create a parent operation which calls multiple
 sub-operations, see section *Calling sub-operations* for more information.
 
-Operation Inheritance
----------------------
+## Operation Inheritance
 
-Generators
-----------
+## Generators
 
 RailsOps features a generator to easily create a structure for common CRUD-style
 constructs. The generator creates the CRUD operations, some empty view files, a
@@ -1833,8 +2182,7 @@ Of course, at this point, the operations will need some adaptions, especially th
 [parameter schemas](#validating-params), and the controllers need the logic for the
 success and failure cases, as this depends on your application.
 
-Lazy Load Hooks
----------------
+## Lazy Load Hooks
 
 RailsOps provides the following [Rails Lazy Load
 Hooks](https://api.rubyonrails.org/v7.1.3.4/classes/ActiveSupport/LazyLoadHooks.html):
@@ -1851,10 +2199,9 @@ Example usage:
 ActiveSupport.on_load(:rails_ops_op_model_create) { include MyMixin }
 ```
 
-Caveats
--------
+## Caveats
 
-### Eager loading in development mode
+### Eager Loading in Development Mode
 
 Eager loading operation classes containing models with nested models or
 operations can be very slow in performance. In production mode, the same process
@@ -1865,11 +2212,11 @@ setting in production mode though.
 
 ## Contributors
 
-This Gem is heavily inspired by the [trailblazer](http://trailblazer.to/) Gem
+This gem is heavily inspired by the [trailblazer](http://trailblazer.to/) gem
 which provides a wonderful, high-level architecture for Rails – beyond just
 operations. Be sure to check this out when trying to decide on an alternative
 Rails architecture.
 
 ## Copyright
 
-Copyright © 2017 - 2025 Sitrox. See `LICENSE` for further details.
+Copyright © 2017 - 2026 Sitrox. See `LICENSE` for further details.