octorail 1.0.0

data/lib/octorail/dsl/wraps.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Octorail
+  module DSL
+    # wrap: run a group of steps inside a wrapper (transaction, lock, timeout, ...).
+    module Wraps
+      def wrap(wrapper, error: nil, &block)
+        check_not_abstract!("wrap #{wrapper.inspect}")
+        check_wrap!(wrapper, error, block)
+        location = declaration_location
+        nodes = collect_nodes(&block)
+        raise ArgumentError, "#{self}: wrap #{wrapper.inspect} has no steps" if nodes.empty?
+
+        current_nodes << Nodes::Wrap.new(wrapper:, nodes:, error:, location:)
+        invalidate!
+        nil
+      end
+
+      private
+
+      def check_wrap!(wrapper, error, block)
+        check_wrapper!(wrapper)
+        raise ArgumentError, "#{self}: wrap #{wrapper.inspect} needs a block with steps" unless block
+        return if error.nil? || error.is_a?(Symbol)
+
+        raise ArgumentError, "#{self}: wrap #{wrapper.inspect}: error: must be a Symbol, got #{error.inspect}"
+      end
+
+      def check_wrapper!(wrapper)
+        return check_name!(wrapper, "wrap") if wrapper.is_a?(Symbol)
+        if wrapper.is_a?(Class) && wrapper < Operation
+          raise ArgumentError, "#{self}: wrap #{wrapper}: is an operation; to run it as a step use nested #{wrapper}"
+        end
+        return if wrapper.respond_to?(:call)
+
+        raise ArgumentError, "#{self}: wrap: wrapper must be a method name (Symbol) or respond to .call, " \
+                             "got #{wrapper.inspect}"
+      end
+
+      # Steps declared inside a wrap block go into a buffer instead of the class's own list.
+      def collect_nodes
+        (@__octorail_nesting ||= []).push([])
+        yield
+        @__octorail_nesting.last
+      ensure
+        @__octorail_nesting.pop
+      end
+    end
+  end
+end

data/lib/octorail/dsl.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "dsl/steps"
+require_relative "dsl/outputs"
+require_relative "dsl/wraps"
+require_relative "dsl/nested"
+require_relative "dsl/switches"
+require_relative "dsl/settings"
+
+module Octorail
+  # Class-level DSL, extended into Operation. Only records declarations; compilation happens later.
+  # Each feature lives in its own module under dsl/.
+  module DSL
+    include Steps
+    include Outputs
+    include Wraps
+    include Nested
+    include Switches
+    include Settings
+
+    METHOD_NAME = /\A[a-z_][a-zA-Z0-9_]*[?!]?\z/
+    # Called bare in generated code, these would parse as syntax (`not(ctx)`, `defined?(ctx)`, `super`).
+    RUBY_KEYWORDS = %i[
+      __ENCODING__ __FILE__ __LINE__ alias and begin break case class def defined? do else elsif end ensure
+      false for if in module next nil not or redo rescue retry return self super then true undef unless
+      until when while yield
+    ].freeze
+    # Frames from the gem itself are skipped when looking for where a node was declared.
+    GEM_DIR = File.expand_path("..", __dir__)
+    LOCATION_FRAMES = 50
+
+    private
+
+    # An abstract operation holds shared methods and macros only; the flow is declared in the
+    # operations that inherit from it, so each shows its whole flow.
+    def check_not_abstract!(what)
+      return unless abstract?
+
+      raise ArgumentError, "#{self}: is abstract (shared methods and macros only), so it can't declare #{what}; " \
+                           "declare it in the operations that inherit from it"
+    end
+
+    # "path:line" of the DSL call outside the gem. When a macro declared it (a method called from
+    # the class body), also the class body line: "macros.rb:6 (via app/operations/x.rb:12)".
+    def declaration_location
+      frames = caller_locations(1, LOCATION_FRAMES).reject { |frame| path_of(frame).start_with?(GEM_DIR) }
+      return if frames.empty?
+
+      site = frames.first
+      body = frames.find { |frame| frame.label.to_s.start_with?("<class:", "<module:") }
+      return format_location(site) if body.nil? || body.equal?(site)
+
+      "#{format_location(site)} (via #{format_location(body)})"
+    end
+
+    def format_location(frame)
+      "#{path_of(frame).delete_prefix("#{Dir.pwd}/")}:#{frame.lineno}"
+    end
+
+    # absolute_path is nil for eval'd code; path then holds the file name given to eval.
+    def path_of(frame) = (frame.absolute_path || frame.path).to_s
+
+    def check_name!(name, kind)
+      unless name.is_a?(Symbol) && METHOD_NAME.match?(name)
+        raise ArgumentError, "#{self}: #{kind} name must be a Symbol method name, got #{name.inspect}"
+      end
+      return unless RUBY_KEYWORDS.include?(name)
+
+      raise ArgumentError, "#{self}: #{kind} #{name.inspect} is a Ruby keyword, pick another name"
+    end
+  end
+end

data/lib/octorail/errors.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Octorail
+  # Every Octorail error is a mistake in code, not a business failure (those are failure results).
+  # Like NotImplementedError, they derive from ScriptError so that a bare `rescue` / `rescue
+  # StandardError` (a timeout wrapper, a controller, `retry_on StandardError`) can't swallow or
+  # retry them: they reach the top-level handler (Rails, Sidekiq, Sentry rescue Exception).
+  class Error < ScriptError; end
+
+  # Suffix for error messages about a declared node: where its step/wrap/nested line is.
+  def self.declared_at(node)
+    node&.location ? "\n  declared at #{node.location}" : ""
+  end
+
+  # Key lists in error messages: ":a, :b", or "none".
+  def self.key_list(keys)
+    keys.empty? ? "none" : keys.map(&:inspect).join(", ")
+  end
+
+  # Raised while compiling an operation: unsupported step signature, unknown step method, etc.
+  class CompileError < Error; end
+
+  # Raised at runtime when a step requires a keyword that ctx doesn't have.
+  class MissingKeyError < Error; end
+
+  # Raised when ctx holds a key that collides with a Result field.
+  class ReservedKeyError < Error; end
+
+  # Raised when an operation with declared outputs succeeds without setting one of them.
+  class MissingOutputError < Error; end
+
+  # Raised by `result[key]` when the operation declares outputs and `key` isn't one of them.
+  class UnknownOutputError < Error; end
+
+  # Raised when a switch decider returns a value that has no on(...) branch.
+  class UnknownBranchError < Error; end
+
+  # Raised when a step writes an instance variable: the operation instance is shared and frozen.
+  class FrozenOperationError < Error; end
+end

data/lib/octorail/invalidation.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Octorail
+  # Drops compiled code when what it was compiled from changes; extended into Operation.
+  # These hooks run at code load time only.
+  module Invalidation
+    # Drops the compiled code of this operation and its descendants; their next call recompiles.
+    def invalidate!
+      COMPILE_LOCK.synchronize do
+        # The next `call` sees no instance and compiles again.
+        @__octorail_instance = nil
+        subclasses.each(&:invalidate!)
+      end
+      self
+    end
+
+    def include(*)
+      super.tap { invalidate! }
+    end
+
+    def prepend(*)
+      super.tap { invalidate! }
+    end
+
+    private
+
+    def method_added(name)
+      super
+      step_method_changed(name)
+    end
+
+    def method_removed(name)
+      super
+      step_method_changed(name)
+    end
+
+    def method_undefined(name)
+      super
+      step_method_changed(name)
+    end
+
+    # A step method was (re)defined or removed: recompile every compiled operation that calls it.
+    def step_method_changed(name)
+      [self, *descendants].each do |operation|
+        operation.invalidate! if operation.compiled? && operation.step_method_names.include?(name)
+      end
+    end
+  end
+end

data/lib/octorail/nodes/nested.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Octorail
+  module Nodes
+    # Another operation run as a step on the same ctx (`nested Billing::Charge`).
+    Nested = Data.define(:operation, :error, :fail_fast, :location)
+
+    class Nested
+      def initialize(operation:, error: nil, fail_fast: false, location: nil)
+        super
+      end
+
+      def type = :nested
+
+      def children = []
+    end
+  end
+end

data/lib/octorail/nodes/step.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Octorail
+  module Nodes
+    # A declared step. `type` is :step, :pass or :failure; `name` is the instance method to call;
+    # `recover` (failure only): a truthy result returns to the success track;
+    # `location` is where it was declared ("path:line"), for error messages.
+    Step = Data.define(:type, :name, :error, :fail_fast, :recover, :location)
+
+    class Step
+      def initialize(type:, name:, error: nil, fail_fast: false, recover: false, location: nil) # rubocop:disable Metrics/ParameterLists
+        super
+      end
+
+      def children = []
+
+      def failure? = type == :failure
+    end
+  end
+end

data/lib/octorail/nodes/switch.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Octorail
+  module Nodes
+    # A fork: `decider` is the instance method whose result (a Symbol) picks the branch to run.
+    Switch = Data.define(:decider, :branches, :location)
+
+    class Switch
+      def initialize(decider:, branches:, location: nil)
+        super
+      end
+
+      def name = decider
+
+      def type = :switch
+
+      def children = branches.flat_map(&:nodes)
+
+      def keys = branches.flat_map(&:keys)
+    end
+
+    # One `on(:a, :b) { ... }` of a switch.
+    Branch = Data.define(:keys, :nodes)
+  end
+end

data/lib/octorail/nodes/wrap.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Octorail
+  module Nodes
+    # A group of nodes run inside `wrapper`: an operation method name (Symbol) or an object
+    # responding to `.call(ctx) { }`. The wrapper yields to run the nodes (the block returns
+    # true/false) and its own return value decides whether the wrap succeeded.
+    Wrap = Data.define(:wrapper, :nodes, :error, :location)
+
+    class Wrap
+      def initialize(wrapper:, nodes:, error: nil, location: nil)
+        super
+      end
+
+      # Used as failed_step when the wrapper itself fails without a step failing inside.
+      def name = wrapper.is_a?(Symbol) ? wrapper : nil
+
+      def type = :wrap
+
+      def children = nodes
+
+      # Steps and nested operations inside, at any depth, in declaration order.
+      def steps = Nodes.leaves(nodes)
+    end
+  end
+end

data/lib/octorail/nodes.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "nodes/step"
+require_relative "nodes/wrap"
+require_relative "nodes/nested"
+require_relative "nodes/switch"
+
+module Octorail
+  # What the DSL records and the compiler reads. Wrap and Switch hold other nodes (`children`).
+  module Nodes
+    # Every node in `nodes` and inside them, depth-first, in declaration order.
+    def self.walk(nodes)
+      nodes.flat_map { |node| [node, *walk(node.children)] }
+    end
+
+    # Nodes that run something themselves (a step method or a nested operation), not containers.
+    def self.leaves(nodes)
+      walk(nodes).select { |node| node.is_a?(Step) || node.is_a?(Nested) }
+    end
+  end
+end

data/lib/octorail/operation.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Octorail
+  # Guards compilation and invalidation; reentrant because compile_all! nests compile!.
+  COMPILE_LOCK = Monitor.new
+
+  class Operation
+    include Runtime
+    extend DSL
+    # Last: its `include` / `method_added` hooks expect the rest of the class to be defined.
+    extend Invalidation
+
+    class << self
+      # `call` and `nested_call` are defined once, here, and never redefined: each class reads its
+      # own compiled instance (nil until compiled or after invalidation). Redefining them per class
+      # would replace a test's stub of them and break it when the stub is restored.
+      def call(**input)
+        (@__octorail_instance || __octorail_compiled_instance).__octorail_entry(input)
+      end
+
+      # One call with a :profile trace, whatever the trace setting (console, tests).
+      def call_traced(**input)
+        (@__octorail_instance || __octorail_compiled_instance).__octorail_trace_call(input, :profile)
+      end
+
+      # Runs on the given ctx Hash itself (no copy): how `nested` calls an operation, and what
+      # a test stubs (or calls with a hand-built ctx) to fake or check a nested operation.
+      # `trace`: the outer trace's node, passed by a traced outer operation (docs/tracing.md);
+      # without it the plain variant runs, whatever this operation's own trace setting.
+      # `**nil`: `nested_call(id: 1)` (meant as `call`) is an ArgumentError, not a ctx Hash.
+      def nested_call(ctx, trace = nil, **nil)
+        raise ArgumentError, "#{self}.nested_call takes the ctx Hash, got #{ctx.inspect}" unless ctx.is_a?(Hash)
+        return (@__octorail_instance || __octorail_compiled_instance).__octorail_call(ctx) unless trace
+
+        __octorail_ensure_traced.__octorail_traced(ctx, trace)
+      end
+
+      # Marks a base class that holds shared methods and macros, not a flow: it can't declare steps,
+      # can't be called, and compile_all! skips it. Not inherited.
+      def abstract!
+        if steps.any? || outputs.any?
+          raise ArgumentError, "#{self}: abstract! must come before any declaration, and an abstract operation " \
+                               "can't inherit steps or outputs"
+        end
+
+        @__octorail_abstract = true
+        nil
+      end
+
+      def abstract? = equal?(Operation) || @__octorail_abstract == true
+
+      def compile!
+        COMPILE_LOCK.synchronize do
+          return self if compiled?
+          raise CompileError, "#{self}: is abstract, call an operation that inherits from it" if abstract?
+
+          install_compiled_code
+          install_traced_code unless setting(:trace) == :off # `call` itself runs the traced variant
+          # Set last: a non-nil instance is what makes `call` skip compilation.
+          @__octorail_instance = new.freeze
+        end
+        self
+      end
+
+      def compiled?
+        !@__octorail_instance.nil?
+      end
+
+      def descendants
+        subclasses.flat_map { |subclass| [subclass, *subclass.descendants] }
+      end
+
+      def to_ruby(traced: false)
+        Compiler.new(self, traced:).source
+      end
+
+      private
+
+      # First call (or first after invalidation): compile, then hand back the instance.
+      def __octorail_compiled_instance
+        compile!
+        @__octorail_instance
+      end
+
+      # Both variants are generated now, from the same nodes, so they share OctorailRefs; the traced
+      # one is installed only when needed (a traced setting, call_traced, a traced outer operation).
+      def install_compiled_code
+        define_result_class
+        traced = Compiler.new(self, traced: true)
+        @__octorail_traced_source = traced.source
+        @__octorail_traced_installed = false
+        define_refs_const(traced.anonymous_refs)
+        redefine_method(Compiler::METHOD_NAME, Compiler.new(self).source, "octorail-generated:#{self}")
+        install_entry
+      end
+
+      # With tracing on, `call` runs the traced variant (the trace level comes from the settings);
+      # off, `call` runs the plain method itself (an alias: no extra frame).
+      def install_entry
+        level = setting(:trace)
+        entry = Compiler::ENTRY_METHOD_NAME.to_sym
+        remove_method(entry) if method_defined?(entry, false)
+        return alias_method(entry, Compiler::METHOD_NAME) if level == :off
+
+        source = "def #{entry}(ctx) = __octorail_trace_call(ctx, #{level.inspect})\n"
+        class_eval(source, "octorail-entry:#{self}", 1)
+      end
+
+      def install_traced_code
+        redefine_method(Compiler::TRACED_METHOD_NAME, @__octorail_traced_source, "octorail-traced:#{self}")
+        @__octorail_traced_installed = true
+      end
+
+      # The compiled instance, with the traced variant installed.
+      def __octorail_ensure_traced
+        instance = @__octorail_instance || __octorail_compiled_instance
+        return instance if @__octorail_traced_installed
+
+        COMPILE_LOCK.synchronize { install_traced_code unless @__octorail_traced_installed }
+        instance
+      end
+
+      # Removed first so redefining doesn't warn under -w.
+      def redefine_method(name, source, file)
+        name = name.to_sym
+        remove_method(name) if method_defined?(name, false) || private_method_defined?(name, false)
+        class_eval(source, file, 1)
+      end
+
+      def define_refs_const(refs)
+        const = Compiler::REFS_CONST
+        remove_const(const) if const_defined?(const, false)
+        const_set(const, refs.freeze) if refs.any?
+      end
+
+      def define_result_class
+        const = Compiler::RESULT_CONST
+        remove_const(const) if const_defined?(const, false)
+        const_set(const, Result.with_outputs(outputs)) if outputs.any?
+      end
+    end
+  end
+end

data/lib/octorail/result.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Octorail
+  # A plain class rather than Data: Data.new always goes through a keyword Hash, which made
+  # building the result cost more than all the compiled steps together.
+  class Result
+    # Result fields that must not appear as ctx keys (`:errors` is reserved with a meaning).
+    RESERVED_CTX_KEYS = %i[success terminus error failed_step].freeze
+    # Keys `result[]` refuses to read from ctx: they have dedicated readers.
+    BUILTIN_KEYS = (RESERVED_CTX_KEYS + [:errors]).freeze
+
+    attr_reader :terminus, :ctx, :error, :failed_step
+    # The Trace of a traced call (docs/tracing.md), else nil. Not part of equality / to_h.
+    attr_reader :trace
+
+    def initialize(terminus, ctx, error = nil, failed_step = nil)
+      @terminus = terminus
+      @ctx = ctx
+      @error = error
+      @failed_step = failed_step
+    end
+
+    def success?
+      terminus == :success
+    end
+
+    def failure?
+      !success?
+    end
+
+    def errors
+      ctx[:errors] unless success?
+    end
+
+    def [](key)
+      if BUILTIN_KEYS.include?(key)
+        reader = key == :success ? "success?" : key
+        raise ReservedKeyError, "#{key.inspect} is a Result field, use result.#{reader}"
+      end
+
+      ctx[key]
+    end
+
+    def deconstruct_keys(keys)
+      check_reserved_keys!
+      return ctx.merge(builtin_fields) unless keys
+
+      pick(keys)
+    end
+
+    def to_h
+      { terminus:, ctx:, error:, failed_step: }
+    end
+
+    def ==(other)
+      other.instance_of?(self.class) && to_h == other.to_h
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, *to_h.values].hash
+    end
+
+    def inspect
+      "#<#{self.class.name || "Octorail::Result"} terminus=#{terminus.inspect} error=#{error.inspect} " \
+        "failed_step=#{failed_step.inspect} ctx=#{ctx.inspect}>"
+    end
+
+    # Builds the Result subclass for an operation with declared outputs:
+    # a reader per output, and `[]` / pattern matching limited to those outputs.
+    def self.with_outputs(outputs)
+      Class.new(self) do
+        const_set(:OUTPUTS, outputs.dup.freeze)
+        include Outputs
+
+        outputs.each do |name|
+          class_eval("def #{name} = ctx[#{name.inspect}]", __FILE__, __LINE__) # def model = ctx[:model]
+        end
+      end
+    end
+
+    # A key outside the declared outputs is a mistake (a typo, or reaching into the operation's
+    # internals), so `[]` and pattern matching both raise for it.
+    module Outputs
+      def [](key)
+        return super if BUILTIN_KEYS.include?(key)
+
+        check_output!(key)
+        super
+      end
+
+      # Outputs can't be named like Result fields and other ctx keys are hidden,
+      # so there is nothing to collide: no reserved-key check here.
+      def deconstruct_keys(keys)
+        return pick([*BUILTIN_KEYS, *self.class::OUTPUTS]) unless keys
+
+        keys.each { |key| check_output!(key) unless BUILTIN_KEYS.include?(key) }
+        pick(keys)
+      end
+
+      private
+
+      def check_output!(key)
+        outputs = self.class::OUTPUTS
+        return if outputs.include?(key)
+
+        raise UnknownOutputError, "#{key.inspect} is not an output (outputs: #{Octorail.key_list(outputs)}); " \
+                                  "use result.ctx[#{key.inspect}] to debug"
+      end
+    end
+
+    private
+
+    def pick(keys)
+      keys.each_with_object({}) do |key, hash|
+        case key
+        when :success then hash[key] = success?
+        when :terminus, :error, :errors, :failed_step then hash[key] = public_send(key)
+        else hash[key] = ctx[key] if ctx.key?(key)
+        end
+      end
+    end
+
+    def builtin_fields
+      { success: success?, terminus:, error:, errors:, failed_step: }
+    end
+
+    def check_reserved_keys!
+      clash = RESERVED_CTX_KEYS.select { |key| ctx.key?(key) }
+      return if clash.empty?
+
+      raise ReservedKeyError, "ctx keys #{Octorail.key_list(clash)} collide with Result fields; rename them"
+    end
+  end
+end

data/lib/octorail/runtime.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Octorail
+  # Private instance helpers that generated code calls on the failure paths.
+  module Runtime
+    # A traced call: runs the traced variant into a new Trace, attaches it to the result, or to the
+    # exception that left the call (then re-raised as is).
+    def __octorail_trace_call(ctx, level)
+      self.class.__send__(:__octorail_ensure_traced)
+      trace = Trace.new(self.class, level)
+      trace.finish(__octorail_traced(ctx, trace.root))
+    rescue ::Exception => e # rubocop:disable Lint/RescueException
+      trace&.fail(e)
+      raise
+    end
+
+    private
+
+    # Called from generated code on FrozenError: only an ivar write on this very instance is ours to explain.
+    def __octorail_frozen!(error)
+      raise error unless error.receiver.equal?(self)
+
+      raise FrozenOperationError, "#{self.class}: a step tried to set an instance variable, but operations " \
+                                  "are stateless (one frozen instance is shared by all calls). " \
+                                  "Store data in ctx, pass dependencies through ctx with keyword defaults."
+    end
+
+    # Called from generated code when an operation succeeds without a declared output.
+    def __octorail_missing_output(name, ctx)
+      raise MissingOutputError, "#{self.class}: succeeded without setting output #{name.inspect} " \
+                                "(ctx keys: #{Octorail.key_list(ctx.keys)})"
+    end
+
+    # Called from generated code when a switch decider returns a value with no branch.
+    # `index`: the switch's position in method_nodes (the declaration is looked up only here).
+    def __octorail_unknown_branch(index, value)
+      node = self.class.method_nodes.fetch(index)
+      raise UnknownBranchError, "#{self.class}: switch #{node.decider.inspect} returned #{value.inspect}, " \
+                                "branches: #{Octorail.key_list(node.keys)}#{Octorail.declared_at(node)}"
+    end
+
+    # Called from generated code when a step's required keyword is absent from ctx.
+    # `index`: the step's position in method_nodes, as for __octorail_unknown_branch;
+    # the step's name is passed too, only so that the generated code reads well.
+    def __octorail_missing_key(index, key, ctx, _step = nil)
+      node = self.class.method_nodes.fetch(index)
+      raise MissingKeyError, "#{self.class}: #{node.type} #{node.name.inspect} requires #{key.inspect}, " \
+                             "but ctx has no #{key.inspect} (ctx keys: #{Octorail.key_list(ctx.keys)})" \
+                             "#{Octorail.declared_at(node)}"
+    end
+  end
+end