octorail 1.0.0

data/lib/octorail/trace/rendering.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Octorail
+  class Trace
+    # Trace#to_s: the path as a tree.
+    #
+    #   Orders::Checkout  12.4 ms
+    #   ├── ✓ validate  0.1 ms
+    #   ├── switch flow_for → :admin
+    #   │   └── ✗ grant_all
+    #   └── failure error=:failure failed_step=:grant_all
+    class Rendering
+      MARKS = {
+        success: "✓", failure: "✗", ran: "·", recovered: "↺", not_recovered: "↺",
+        failed: "✗", raised: "!"
+      }.freeze
+      KINDS = { nested: "nested ", failure: "failure " }.freeze
+
+      def initialize(trace, lines = [])
+        @trace = trace
+        @lines = lines
+      end
+
+      def to_s
+        @lines << with_duration(@trace.root.name, @trace.duration)
+        render_body("")
+        "#{@lines.join("\n")}\n"
+      end
+
+      # The tree under the root line; also used for a trace carried in from a separate call.
+      def render_body(indent)
+        nodes = @trace.root.children
+        last = summary? ? nil : nodes.size - 1
+        nodes.each_with_index { |node, index| render(node, indent, index == last, []) }
+        @lines << "#{indent}└── #{summary}" if summary?
+      end
+
+      private
+
+      def render(node, indent, last, wraps)
+        @lines << "#{indent}#{branch_mark(last)}#{with_duration(label(node, wraps), node.duration)}"
+        render_children(node, indent + child_mark(last), node.type == :wrap ? [*wraps, node] : wraps)
+      end
+
+      def render_children(node, indent, wraps)
+        render_inner(node.inner, indent) if node.inner
+        node.children.each_with_index do |child, index|
+          render(child, indent, index == node.children.size - 1, wraps)
+        end
+      end
+
+      def branch_mark(last) = last ? "└── " : "├── "
+      def child_mark(last) = last ? "    " : "│   "
+
+      def render_inner(inner, indent)
+        @lines << "#{indent}└── #{with_duration(inner.root.name, inner.duration)}"
+        Rendering.new(inner, @lines).render_body("#{indent}    ")
+      end
+
+      def label(node, wraps)
+        case node.type
+        when :switch then "switch #{node.name}#{" → #{node.branch.inspect}" if node.taken?}#{suffix(node, wraps)}"
+        when :wrap then "wrap #{node.name} → #{wrap_result(node)}"
+        when :recover then "#{mark(node)} recover #{node.name} (#{node.outcome.to_s.tr("_", " ")})"
+        else plain_label(node, wraps)
+        end
+      end
+
+      def plain_label(node, wraps)
+        "#{mark(node)} #{KINDS[node.type]}#{node.name}#{suffix(node, wraps) unless node.type == :nested}"
+      end
+
+      def mark(node) = MARKS.fetch(node.outcome, "?")
+
+      def wrap_result(node)
+        node.outcome == :raised ? "raised" : node.value.inspect
+      end
+
+      def suffix(node, wraps = [])
+        case node.outcome
+        when :raised then " (raised #{(node.exception || @trace.exception).class}#{rescuer(wraps)})"
+        when :failed then " (left on failure)"
+        else ""
+        end
+      end
+
+      # A raise that didn't leave the call was rescued by the innermost enclosing wrap that ended normally.
+      def rescuer(wraps)
+        wrap = wraps.reverse.find { |node| node.outcome != :raised }
+        wrap ? ", rescued by #{wrap.name}" : ""
+      end
+
+      def summary?
+        @trace.exception || @trace.terminus
+      end
+
+      def summary
+        return "raised #{@trace.exception.class}: #{@trace.exception.message}" if @trace.exception
+
+        details = [("error=#{@trace.error.inspect}" if @trace.error),
+                   ("failed_step=#{@trace.failed_step.inspect}" if @trace.failed_step)].compact
+        [@trace.terminus, *details].join(" ")
+      end
+
+      def with_duration(text, seconds)
+        seconds ? "#{text}  #{Trace.ms(seconds)} ms" : text
+      end
+    end
+  end
+end

data/lib/octorail/trace.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Octorail
+  # The path one traced call took through an operation (docs/tracing.md). Built by the traced
+  # variant of the generated code: every step, wrap, switch and nested operation becomes a Node.
+  # Holds names, outcomes, branch keys and durations only, never ctx values.
+  class Trace
+    LEVELS = %i[off path profile].freeze
+
+    # One traced node. Containers (wrap, switch, nested, the operation itself) hold child nodes.
+    class Node
+      NONE = [].freeze
+      private_constant :NONE
+
+      # `value`: true / false only, what the node returned taken as a condition (never the object
+      # itself: it may hold ctx data, and must not stop the exception carrying the trace from
+      # being serialized). `exception`: what a step raised. `inner`: the trace of a separate
+      # traced operation that step called, carried in by the exception.
+      attr_reader :type, :name, :value, :branch, :duration, :exception, :inner
+
+      def initialize(type, name, profile)
+        @type = type
+        @name = name
+        @profile = profile
+        @started = Process.clock_gettime(Process::CLOCK_MONOTONIC) if profile
+      end
+
+      # Generated code for a step call: `trace.run(:step, :charge) { charge(ctx) }`.
+      # A raise is recorded on the step's own node, even if a wrapper rescues it later.
+      def run(type, name)
+        node = start(type, name)
+        value = yield
+        node.close(value)
+        value
+      rescue ::Exception => e # rubocop:disable Lint/RescueException
+        node&.raised(e)
+        raise
+      end
+
+      # Generated code for a container: `__tw1 = trace.start(:wrap, "Transaction")`, then `done`.
+      def start(type, name)
+        node = Node.new(type, name, @profile)
+        (@children ||= []) << node
+        node
+      end
+
+      # Only containers get an array: steps are leaves.
+      def children = @children || NONE
+
+      # Records what the node returned and passes it through unchanged.
+      def done(node, value)
+        node.close(value)
+        value
+      end
+
+      # The switch decider's result: recorded, then passed through to `case`.
+      def taken(value)
+        @taken = true
+        @branch = value
+        value
+      end
+
+      # False when the switch decider raised.
+      def taken? = @taken == true
+
+      # Children still open were left by a failure exit (`next false` in a wrap, a nested
+      # operation's `return`): they end here, not when the whole call ends.
+      def close(value)
+        return if closed?
+
+        @children&.each { |child| child.close_open(:failed) }
+        @closed = true
+        @value = value ? true : false
+        @duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started if @profile
+      end
+
+      def raised(exception)
+        @exception = exception
+        @inner = exception.octorail_trace if exception.respond_to?(:octorail_trace)
+        @outcome = :raised
+        close(nil)
+      end
+
+      def closed? = @closed == true
+
+      # Nodes still open when the call ended were left early: by a failure exit (`failed`) or by an
+      # exception (`raised`, only for the innermost open path).
+      def close_open(outcome)
+        children.each { |child| child.close_open(outcome) }
+        return if closed?
+
+        @outcome = outcome
+        close(nil)
+      end
+
+      def outcome
+        @outcome || OUTCOMES.fetch(type).call(self)
+      end
+
+      OUTCOMES = {
+        step: ->(node) { node.value ? :success : :failure },
+        pass: ->(_node) { :ran },
+        failure: ->(_node) { :ran },
+        recover: ->(node) { node.value ? :recovered : :not_recovered },
+        wrap: ->(node) { node.value ? :success : :failure },
+        nested: ->(node) { node.value ? :success : :failure },
+        switch: ->(_node) { :success }
+      }.freeze
+      private_constant :OUTCOMES
+
+      def to_h
+        hash = { type:, name:, outcome:, **details }
+        hash[:duration_ms] = Trace.ms(duration) if duration
+        hash[:nodes] = children.map(&:to_h) unless children.empty?
+        hash
+      end
+
+      private
+
+      def details
+        { branch: (branch if type == :switch && taken?), exception: exception&.class&.name, trace: inner&.to_h }
+          .compact
+      end
+    end
+
+    # Attached to an exception that left a traced call: `e.octorail_trace`.
+    module TracedException
+      attr_accessor :octorail_trace
+    end
+
+    def self.ms(seconds) = (seconds * 1000).round(3)
+
+    attr_reader :level, :root, :terminus, :error, :failed_step, :exception
+
+    # The operation's name, not the class: a trace holds no objects (see Node#value).
+    def initialize(operation, level)
+      @level = level
+      @root = Node.new(:operation, operation.name || operation.inspect, level == :profile)
+    end
+
+    def operation = root.name
+
+    def profile? = level == :profile
+
+    def duration = root.duration
+
+    # The call returned: close what is still open (left by a failure exit) and attach to the result.
+    def finish(result)
+      @terminus = result.terminus
+      @error = result.error
+      @failed_step = result.failed_step
+      root.close_open(:failed)
+      result.instance_variable_set(:@trace, self)
+      result
+    end
+
+    # The call raised: the open nodes are the path to where it happened. A trace the exception
+    # already carries (from a separate traced call inside a step) moves under that step's node.
+    def fail(exception)
+      @exception = exception
+      root.close_open(:raised)
+      return if exception.frozen?
+
+      exception.extend(TracedException)
+      exception.octorail_trace = self
+    end
+
+    def to_h
+      {
+        operation: root.name, level:, terminus:, error:, failed_step:,
+        exception: exception&.class&.name, duration_ms: duration && Trace.ms(duration),
+        nodes: root.children.map(&:to_h)
+      }.compact
+    end
+
+    def to_s = Rendering.new(self).to_s
+
+    def inspect = "#<#{self.class} #{operation} #{exception ? "raised #{exception.class}" : terminus}>"
+  end
+end
+
+require_relative "trace/rendering"

data/lib/octorail/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Octorail
+  VERSION = "1.0.0"
+end

data/lib/octorail.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "octorail/version"
+require_relative "octorail/errors"
+require_relative "octorail/result"
+require_relative "octorail/trace"
+require_relative "octorail/config"
+require_relative "octorail/nodes"
+require_relative "octorail/dsl"
+require_relative "octorail/compiler"
+require_relative "octorail/runtime"
+require_relative "octorail/invalidation"
+require_relative "octorail/operation"
+
+module Octorail
+  # Compiles every operation under `root` (all of them by default), so compile errors
+  # surface at boot or in CI instead of on the first call. Returns the compiled classes.
+  def self.compile_all!(root = Operation)
+    root.descendants.reject(&:abstract?).each(&:compile!)
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: octorail
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Dmytro Bereza
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Octorail provides a strict, Trailblazer-like railway DSL (step, pass,
+  failure, wrap, nested, switch, recover) that is compiled into a plain Ruby
+  method when the operation is first used, so a call costs about as much as
+  hand-written code. Optional tracing shows the path a call took.
+email:
+- dmitrybereza2001@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/octorail.rb
+- lib/octorail/compiler.rb
+- lib/octorail/compiler/code.rb
+- lib/octorail/compiler/nested_cycles.rb
+- lib/octorail/compiler/nested_emitter.rb
+- lib/octorail/compiler/recovery_emitter.rb
+- lib/octorail/compiler/scopes.rb
+- lib/octorail/compiler/signature.rb
+- lib/octorail/compiler/step_emitter.rb
+- lib/octorail/compiler/switch_emitter.rb
+- lib/octorail/compiler/tracing.rb
+- lib/octorail/compiler/wrap_emitter.rb
+- lib/octorail/config.rb
+- lib/octorail/dsl.rb
+- lib/octorail/dsl/nested.rb
+- lib/octorail/dsl/outputs.rb
+- lib/octorail/dsl/settings.rb
+- lib/octorail/dsl/steps.rb
+- lib/octorail/dsl/switches.rb
+- lib/octorail/dsl/wraps.rb
+- lib/octorail/errors.rb
+- lib/octorail/invalidation.rb
+- lib/octorail/nodes.rb
+- lib/octorail/nodes/nested.rb
+- lib/octorail/nodes/step.rb
+- lib/octorail/nodes/switch.rb
+- lib/octorail/nodes/wrap.rb
+- lib/octorail/operation.rb
+- lib/octorail/result.rb
+- lib/octorail/runtime.rb
+- lib/octorail/trace.rb
+- lib/octorail/trace/rendering.rb
+- lib/octorail/version.rb
+homepage: https://github.com/Octorail-team/octorail
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Octorail-team/octorail
+  changelog_uri: https://github.com/Octorail-team/octorail/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/Octorail-team/octorail/tree/main/docs
+  bug_tracker_uri: https://github.com/Octorail-team/octorail/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Lightweight railway-oriented operations compiled to plain Ruby at load time.
+test_files: []