easyop 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c77d9aa5925ea30b3de85fc74618f355ee3498223f79d6184cda21e95574b8d
-  data.tar.gz: 8bd775d8fa095a50b46aafeedec78f2046d54005b6316a1f22ae02b5657c361c
+  metadata.gz: 2b880af1b623158d3acfac130198bd96ce8c268195fd073554283738a880a45a
+  data.tar.gz: 0c4f5554b456ac252b13734d0964155e2a80909e81946e28f89c529cc60f9081
 SHA512:
-  metadata.gz: a01be26e27050c1569f85ee610043ca42268c75054355c4faf230b65599354d9a824b07955f4f13cda25672681d1c934bbeaec15d89be2cfd8ad55681dd29511
-  data.tar.gz: 41d8d5bf9ca01e02146764678c343eac787c2d5445670caa9e8c1a0f0b60ff26b57906f2fb4abd16b7e59d05b05fe65a1400cff4458934df0110bf1af10f5d3a
+  metadata.gz: c408d6d42a357ba1a6df4da21e13a7b0498d36fa4252e86c68aff289e8843d94d056c430f654f023e6d801ee650fc1bc4c400cb6d058a6b209129e1fbda644fd
+  data.tar.gz: e89087c84c8fbc77abe96b6713a144dd34b78c2cfd35066f28a14e37516f0e7ae8b0f0cbbcfe0ca9eb9de646c7890552b64d7d2848c9976ff6f51637531a4a8a

data/CHANGELOG.md

@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.4] — 2026-04-14
+
+### Added
+
+- **Flow-tracing forwarding in `Easyop::Flow`** — `CallBehavior#call` now automatically sets the `__recording_parent_*` ctx keys before running steps, so every child operation's log entry carries the flow class as its `parent_operation_name` and `parent_reference_id`. This works even when Recording is not installed on the flow class itself (bare `include Easyop::Flow`). When Recording IS installed (recommended: inherit from ApplicationOperation and add `transactional false`), the flow appears in the log as the root entry and RunWrapper handles the ctx setup — no double-setup occurs.
+
+  ```ruby
+  # Bare flow — Recording on steps only; flow itself is not recorded but
+  # steps correctly show parent_operation_name: "Flows::Checkout"
+  class Flows::Checkout
+    include Easyop::Flow
+    flow Orders::CreateOrder, Orders::ProcessPayment
+  end
+
+  # Recommended — flow is recorded as root, steps as children:
+  class Flows::Checkout < ApplicationOperation
+    include Easyop::Flow
+    transactional false   # steps manage their own transactions
+    flow Orders::CreateOrder, Orders::ProcessPayment
+  end
+  ```
+
+  Result in operation_logs:
+  ```
+  Flows::Checkout         root=aaa  ref=bbb  parent=nil
+    Orders::CreateOrder   root=aaa  ref=ccc  parent=Flows::Checkout/bbb
+    Orders::ProcessPayment root=aaa  ref=ddd  parent=Flows::Checkout/bbb
+  ```
+
+- **`record_result` DSL for `Easyop::Plugins::Recording`** — selectively persist ctx output data into a new optional `result_data :text` column (stored as JSON). Supports three forms:
+
+  ```ruby
+  # Attrs form — one or more ctx keys
+  record_result attrs: :invoice_id
+  record_result attrs: [:invoice_id, :total]
+
+  # Block form — custom extraction
+  record_result { |ctx| { total: ctx.total, items: ctx.items.count } }
+
+  # Symbol form — delegates to a private instance method
+  record_result :build_result
+  ```
+
+  Plugin-level default (inherited by all subclasses):
+  ```ruby
+  plugin Easyop::Plugins::Recording, model: OperationLog, record_result: { attrs: :metadata }
+  ```
+
+  Class-level `record_result` overrides the plugin-level default. Missing ctx keys produce `nil` (no error). ActiveRecord objects are serialized as `{ id:, class: }`. Serialization errors are swallowed. The `result_data` column is silently skipped when absent from the model table — fully backward-compatible.
+
+### Fixed
+
+- **`Easyop::Schema` type-mismatch warning suppressed when `$VERBOSE` is `nil`** — `warn` is a no-op in Ruby when `$VERBOSE` is `nil` (e.g. when running under certain test setups or with `-W0`). Changed to `$stderr.puts` so the `[EasyOp]` type-mismatch message always reaches stderr regardless of Ruby's verbosity flag.
+
+- **`Easyop::Schema` spec `strict_types` contamination across examples** — Setting `strict_types = true` inside an example without a corresponding teardown left the global config dirty for later examples. Added `after(:each) { Easyop.reset_config! }` at the top-level `RSpec.describe` so every example begins with a clean configuration.
+
+- **`Easyop::Plugins::Instrumentation` flaky duration assertion** — The `:duration` payload is computed as `(elapsed_ms).round(2)`, which rounds to `0.0` for operations completing in under 0.005 ms. Relaxed the spec assertion from `be > 0` to `be >= 0` to reflect that a rounded-to-zero duration is a valid measurement, not an error.
+
 ## [0.1.3] — 2026-04-14
 
 ### Added
@@ -200,5 +258,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `examples/easyop_test_app/` — full Rails 8 blog application demonstrating all features in real-world code
 - `examples/usage.rb` — 13 runnable plain-Ruby examples
 
-[Unreleased]: https://github.com/pniemczyk/easyop/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com/pniemczyk/easyop/compare/v0.1.4...HEAD
+[0.1.4]: https://github.com/pniemczyk/easyop/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/pniemczyk/easyop/compare/v0.1.2...v0.1.3

data/README.md

@@ -428,6 +428,39 @@ class FullCheckout
 end
 ```
 
+### Recording plugin integration — full call-tree tracing
+
+When step operations have the Recording plugin installed, `Easyop::Flow` automatically forwards the parent-tracing ctx so every step's log entry shows the flow as its `parent_operation_name`. All steps and the flow share the same `root_reference_id`.
+
+**Bare flow** (Recording only on steps — flow is NOT recorded itself, but steps carry correct parent info):
+
+```ruby
+class ProcessCheckout
+  include Easyop::Flow
+  flow ValidateCart, ChargePayment, CreateOrder
+end
+```
+
+**Recommended** — inherit from your recorded base class so the **flow itself appears in operation_logs** as the tree root. Add `transactional false` so step-level transactions aren't shadowed by an outer one:
+
+```ruby
+class ProcessCheckout < ApplicationOperation
+  include Easyop::Flow
+  transactional false   # EasyOp handles rollback; each step owns its transaction
+
+  flow ValidateCart, ChargePayment, CreateOrder
+end
+```
+
+Result in `operation_logs`:
+
+```
+ProcessCheckout    root=aaa  ref=bbb  parent=nil
+  ValidateCart     root=aaa  ref=ccc  parent=ProcessCheckout/bbb
+  ChargePayment    root=aaa  ref=ddd  parent=ProcessCheckout/bbb
+  CreateOrder      root=aaa  ref=eee  parent=ProcessCheckout/bbb
+```
+
 ---
 
 ## `prepare` — Pre-registered Callbacks
@@ -613,6 +646,7 @@ end
 |---|---|---|
 | `model:` | required | ActiveRecord class to write logs into |
 | `record_params:` | `true` | Set `false` to skip serializing ctx params |
+| `record_result:` | `nil` | Plugin-level default for result capture (Hash/Proc/Symbol — see below) |
 
 **Required model columns:**
 
@@ -627,8 +661,91 @@ create_table :operation_logs do |t|
 end
 ```
 
+**Optional flow-tracing columns:**
+
+Add these columns to reconstruct the full call tree when nested flows run. They are populated automatically when present — missing columns are silently skipped (backward-compatible):
+
+```ruby
+add_column :operation_logs, :root_reference_id,     :string
+add_column :operation_logs, :reference_id,          :string
+add_column :operation_logs, :parent_operation_name, :string
+add_column :operation_logs, :parent_reference_id,   :string
+
+add_index :operation_logs, :root_reference_id
+add_index :operation_logs, :reference_id, unique: true
+add_index :operation_logs, :parent_reference_id
+```
+
+All operations triggered by a single top-level call share the same `root_reference_id`. The `parent_operation_name` and `parent_reference_id` columns link each operation to its direct caller. `Easyop::Flow` automatically forwards these ctx keys to child steps — see the [Flow section](#flow--composing-operations) for how to make the flow itself appear as the tree root. Example (flow with nested steps):
+
+```
+FullCheckout      root=aaa  ref=bbb  parent=nil
+  AuthAndValidate root=aaa  ref=ccc  parent=FullCheckout/bbb
+    AuthUser      root=aaa  ref=ddd  parent=AuthAndValidate/ccc
+  ProcessPayment  root=aaa  ref=eee  parent=FullCheckout/bbb
+```
+
+Useful model helpers:
+
+```ruby
+scope :for_tree, ->(id) { where(root_reference_id: id).order(:performed_at) }
+def root?; parent_reference_id.nil?; end
+
+# Fetch the entire execution tree for one top-level call:
+root_log = OperationLog.find_by(operation_name: "FullCheckout", parent_reference_id: nil)
+OperationLog.for_tree(root_log.root_reference_id)
+```
+
 The plugin automatically scrubs these keys from `params_data` before persisting: `:password`, `:password_confirmation`, `:token`, `:secret`, `:api_key`. ActiveRecord objects are serialized as `{ id:, class: }` rather than their full representation.
 
+**`record_result` DSL — capture output data:**
+
+Add an optional `result_data :text` column to persist selected ctx values after the operation runs:
+
+```ruby
+add_column :operation_logs, :result_data, :text  # stored as JSON
+```
+
+Then declare what to record using the `record_result` DSL (three forms):
+
+```ruby
+# Attrs form — one or more ctx keys
+class PlaceOrder < ApplicationOperation
+  record_result attrs: :order_id
+end
+
+class ProcessPayment < ApplicationOperation
+  record_result attrs: [:charge_id, :amount_cents]
+end
+
+# Block form — custom extraction
+class GenerateReport < ApplicationOperation
+  record_result { |ctx| { rows: ctx.rows.count, format: ctx.format } }
+end
+
+# Symbol form — delegates to a private instance method
+class BuildInvoice < ApplicationOperation
+  record_result :build_result
+
+  private
+
+  def build_result
+    { invoice_id: ctx.invoice.id, total: ctx.total }
+  end
+end
+```
+
+Set a plugin-level default inherited by all subclasses:
+
+```ruby
+plugin Easyop::Plugins::Recording, model: OperationLog,
+       record_result: { attrs: :metadata }
+# or: record_result: ->(ctx) { { id: ctx.record_id } }
+# or: record_result: :build_result
+```
+
+Class-level `record_result` overrides the plugin-level default. Missing ctx keys produce `nil` — no error. The `result_data` column is silently skipped when absent from the model table — fully backward-compatible.
+
 **Opt out per class:**
 
 ```ruby

data/lib/easyop/flow.rb

@@ -1,3 +1,5 @@
+require 'securerandom'
+
 module Easyop
   # Compose a sequence of operations that share a single ctx.
   #
@@ -11,6 +13,27 @@ module Easyop
   #     flow ValidateCart, ChargeCard, CreateOrder, NotifyUser
   #   end
   #
+  # ## Recording plugin integration (flow tracing)
+  #
+  # When steps have the Recording plugin installed, `CallBehavior#call` forwards
+  # the parent ctx keys so every step log entry shows the flow as its parent:
+  #
+  #   # Bare flow — flow itself is not recorded but steps see it as parent:
+  #   class ProcessOrder
+  #     include Easyop::Flow
+  #     flow ValidateCart, ChargeCard
+  #   end
+  #
+  # For full tree reconstruction (flow appears in operation_logs as the root
+  # entry) inherit from your recorded base class and opt out of the transaction
+  # so step-level transactions are not shadowed by an outer one:
+  #
+  #   class ProcessOrder < ApplicationOperation
+  #     include Easyop::Flow
+  #     transactional false   # EasyOp handles rollback; steps own their transactions
+  #     flow ValidateCart, ChargeCard
+  #   end
+  #
   #   result = ProcessOrder.call(user: user, cart: cart)
   #   result.on_success { |ctx| redirect_to order_path(ctx.order) }
   #   result.on_failure { |ctx| flash[:alert] = ctx.error }
@@ -31,6 +54,25 @@ module Easyop
     # otherwise place Operation earlier in the ancestor chain than Flow itself).
     module CallBehavior
       def call
+        # ── Flow-tracing forwarding for the Recording plugin ──────────────────
+        # When Recording is NOT installed on this flow class (i.e. the flow does
+        # not inherit from a base operation that has Recording), set the
+        # __recording_parent_* ctx keys manually so every step operation knows
+        # this flow is its parent.  When Recording IS installed on the flow (its
+        # RunWrapper runs before `call` is reached), it has already set up the
+        # parent context correctly — we detect that via _recording_enabled? and
+        # skip to avoid a conflict.  If Recording is not used at all, these ctx
+        # keys are unused and ignored.
+        _flow_tracing = self.class.name &&
+                        !self.class.respond_to?(:_recording_enabled?)
+        if _flow_tracing
+          ctx[:__recording_root_reference_id]     ||= SecureRandom.uuid
+          _prev_parent_name                         = ctx[:__recording_parent_operation_name]
+          _prev_parent_id                           = ctx[:__recording_parent_reference_id]
+          ctx[:__recording_parent_operation_name]   = self.class.name
+          ctx[:__recording_parent_reference_id]     = SecureRandom.uuid
+        end
+
         pending_guard = nil
 
         self.class._flow_steps.each do |step|
@@ -56,6 +98,12 @@ module Easyop
       rescue Ctx::Failure
         ctx.rollback!
         raise
+      ensure
+        # Restore parent context so any caller above this flow sees the right parent.
+        if _flow_tracing
+          ctx[:__recording_parent_operation_name] = _prev_parent_name
+          ctx[:__recording_parent_reference_id]   = _prev_parent_id
+        end
       end
     end
 

data/lib/easyop/plugins/recording.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 module Easyop
   module Plugins
     # Records operation executions to a database model.
@@ -18,6 +20,15 @@ module Easyop
     #   duration_ms     :float
     #   performed_at    :datetime, null: false
     #
+    # Optional flow-tracing columns:
+    #   root_reference_id     :string   # shared across entire execution tree
+    #   reference_id          :string   # unique to this operation execution
+    #   parent_operation_name :string   # class name of the direct parent
+    #   parent_reference_id   :string   # reference_id of the direct parent
+    #
+    # Optional result column:
+    #   result_data           :text     # stored as JSON — selected ctx keys after call
+    #
     # Opt out per operation class:
     #   class MyOp < ApplicationOperation
     #     recording false
@@ -26,15 +37,24 @@ module Easyop
     # Options:
     #   model:         (required) ActiveRecord class
     #   record_params: true       pass false to skip params serialization
+    #   record_result: nil        configure result capture at plugin level (Hash/Proc/Symbol)
     module Recording
       # Sensitive keys scrubbed from params_data before persisting.
       SCRUBBED_KEYS = %i[password password_confirmation token secret api_key].freeze
 
-      def self.install(base, model:, record_params: true, **_options)
+      # Internal ctx keys used for flow tracing — excluded from params_data.
+      INTERNAL_CTX_KEYS = %i[
+        __recording_root_reference_id
+        __recording_parent_operation_name
+        __recording_parent_reference_id
+      ].freeze
+
+      def self.install(base, model:, record_params: true, record_result: nil, **_options)
         base.extend(ClassMethods)
         base.prepend(RunWrapper)
-        base.instance_variable_set(:@_recording_model,        model)
-        base.instance_variable_set(:@_recording_record_params, record_params)
+        base.instance_variable_set(:@_recording_model,         model)
+        base.instance_variable_set(:@_recording_record_params,  record_params)
+        base.instance_variable_set(:@_recording_record_result,  record_result)
       end
 
       module ClassMethods
@@ -62,6 +82,33 @@ module Easyop
             true
           end
         end
+
+        # DSL for capturing result data after the operation runs.
+        # Three forms:
+        #   record_result attrs: :key           # one or more ctx keys
+        #   record_result { |ctx| { k: ctx.k } } # block
+        #   record_result :build_result         # private instance method name
+        def record_result(value = nil, attrs: nil, &block)
+          @_recording_record_result = if block
+            block
+          elsif attrs
+            { attrs: attrs }
+          elsif value.is_a?(Symbol)
+            value
+          else
+            value
+          end
+        end
+
+        def _recording_record_result_config
+          if instance_variable_defined?(:@_recording_record_result)
+            @_recording_record_result
+          elsif superclass.respond_to?(:_recording_record_result_config)
+            superclass._recording_record_result_config
+          else
+            nil
+          end
+        end
       end
 
       module RunWrapper
@@ -70,6 +117,23 @@ module Easyop
           return super unless (model = self.class._recording_model)
           return super unless self.class.name # skip anonymous classes
 
+          # -- Flow tracing --
+          # Each operation gets its own reference_id. The root_reference_id is
+          # shared across the entire execution tree via ctx (set once, inherited).
+          reference_id      = SecureRandom.uuid
+          root_reference_id = ctx[:__recording_root_reference_id] ||= SecureRandom.uuid
+
+          # Read current parent context — these become THIS operation's parent fields.
+          parent_operation_name = ctx[:__recording_parent_operation_name]
+          parent_reference_id   = ctx[:__recording_parent_reference_id]
+
+          # Set THIS operation as the parent for any children that run inside super.
+          # Save the previous values so we can restore them after (for siblings).
+          prev_parent_name = parent_operation_name
+          prev_parent_id   = parent_reference_id
+          ctx[:__recording_parent_operation_name] = self.class.name
+          ctx[:__recording_parent_reference_id]   = reference_id
+
           start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           super
         ensure
@@ -78,22 +142,37 @@ module Easyop
           # branch the tap block would be skipped and failures inside flows would
           # never be persisted.
           if start
+            # Restore parent context so sibling steps see the correct parent.
+            ctx[:__recording_parent_operation_name] = prev_parent_name
+            ctx[:__recording_parent_reference_id]   = prev_parent_id
+
             ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
-            _recording_persist!(ctx, model, ms)
+            _recording_persist!(ctx, model, ms,
+              root_reference_id:     root_reference_id,
+              reference_id:          reference_id,
+              parent_operation_name: parent_operation_name,
+              parent_reference_id:   parent_reference_id)
           end
         end
 
         private
 
-        def _recording_persist!(ctx, model, duration_ms)
+        def _recording_persist!(ctx, model, duration_ms,
+                                root_reference_id: nil, reference_id: nil,
+                                parent_operation_name: nil, parent_reference_id: nil)
           attrs = {
-            operation_name: self.class.name,
-            success:        ctx.success?,
-            error_message:  ctx.error,
-            performed_at:   Time.current,
-            duration_ms:    duration_ms
+            operation_name:        self.class.name,
+            success:               ctx.success?,
+            error_message:         ctx.error,
+            performed_at:          Time.current,
+            duration_ms:           duration_ms,
+            root_reference_id:     root_reference_id,
+            reference_id:          reference_id,
+            parent_operation_name: parent_operation_name,
+            parent_reference_id:   parent_reference_id
           }
           attrs[:params_data] = _recording_safe_params(ctx) if self.class._recording_record_params?
+          attrs[:result_data] = _recording_safe_result(ctx) if self.class._recording_record_result_config
 
           # Only write columns the model actually has
           safe = attrs.select { |k, _| model.column_names.include?(k.to_s) }
@@ -104,13 +183,35 @@ module Easyop
 
         def _recording_safe_params(ctx)
           ctx.to_h
-             .except(*SCRUBBED_KEYS)
+             .except(*SCRUBBED_KEYS, *INTERNAL_CTX_KEYS)
              .transform_values { |v| v.is_a?(ActiveRecord::Base) ? { id: v.id, class: v.class.name } : v }
              .to_json
         rescue
           nil
         end
 
+        def _recording_safe_result(ctx)
+          config = self.class._recording_record_result_config
+          return nil unless config
+
+          raw = case config
+                when Hash
+                  keys = Array(config[:attrs])
+                  keys.each_with_object({}) { |k, h| h[k] = ctx[k] }
+                when Proc
+                  config.call(ctx)
+                when Symbol
+                  send(config)
+                end
+
+          return nil unless raw.is_a?(Hash)
+
+          raw.transform_values { |v| v.is_a?(ActiveRecord::Base) ? { id: v.id, class: v.class.name } : v }
+             .to_json
+        rescue
+          nil
+        end
+
         def _recording_warn(err)
           return unless defined?(Rails) && Rails.respond_to?(:logger)
           Rails.logger.warn "[EasyOp::Recording] Failed to record #{self.class.name}: #{err.message}"

data/lib/easyop/schema.rb

@@ -161,7 +161,7 @@ module Easyop
       if Easyop.config.strict_types
         ctx.fail!(error: msg, errors: ctx.errors.merge(field.name => msg))
       else
-        warn "[Easyop] #{msg}"
+        $stderr.puts "[Easyop] #{msg}"
       end
     end
   end

data/lib/easyop/version.rb

@@ -1,3 +1,3 @@
 module Easyop
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easyop
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Pawel Niemczyk