hubbado-sequence 0.3.0

data/lib/hubbado/sequence/result.rb

@@ -0,0 +1,83 @@
+module Hubbado
+  module Sequence
+    class Result
+      FRAMEWORK_I18N_SCOPE = "sequence.errors".freeze
+
+      attr_reader :ctx
+      attr_reader :error
+      attr_reader :trail
+      attr_reader :i18n_scope
+
+      def self.ok(ctx, trail: [], i18n_scope: nil)
+        new(:ok, ctx, error: nil, trail: trail, i18n_scope: i18n_scope)
+      end
+
+      def self.fail(ctx, error:, trail: [], i18n_scope: nil)
+        unless error.is_a?(Hash) && error[:code]
+          raise ArgumentError, "Result.fail requires error: { code: ... }"
+        end
+
+        new(:fail, ctx, error: error, trail: trail, i18n_scope: i18n_scope)
+      end
+
+      def initialize(status, ctx, error:, trail:, i18n_scope:)
+        @status = status
+        @ctx = ctx
+        @error = error
+        @trail = trail
+        @i18n_scope = i18n_scope
+      end
+
+      def ok?
+        @status == :ok
+      end
+
+      def failure?
+        @status == :fail
+      end
+
+      def with_trail(trail)
+        self.class.new(@status, @ctx, error: @error, trail: trail, i18n_scope: @i18n_scope)
+      end
+
+      def with_i18n_scope(scope)
+        return self unless @i18n_scope.nil?
+
+        self.class.new(@status, @ctx, error: @error, trail: @trail, i18n_scope: scope)
+      end
+
+      def message
+        return nil if ok?
+
+        translation = translate_with_chain
+        return translation if translation
+
+        @error[:message] || humanize_code
+      end
+
+      private
+
+      def translate_with_chain
+        scopes = []
+        scopes << @error[:i18n_scope] if @error[:i18n_scope]
+        scopes << @i18n_scope if @i18n_scope
+        scopes << FRAMEWORK_I18N_SCOPE
+        scopes.uniq!
+
+        key = @error[:i18n_key] || @error[:code]
+        args = @error[:i18n_args] || {}
+
+        scopes.each do |scope|
+          translated = ::I18n.t("#{scope}.#{key}", default: nil, **args)
+          return translated unless translated.nil?
+        end
+
+        nil
+      end
+
+      def humanize_code
+        @error[:code].to_s.tr("_", " ").capitalize
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/run_sequence.rb

@@ -0,0 +1,26 @@
+module Hubbado
+  module Sequence
+    # Mixed into controllers (or other top-level boundaries that cannot take
+    # injected dependencies because their lifecycle is owned by the framework).
+    # Wraps Runner so the calling site reads `run_sequence SomeSeq do |r| ... end`
+    # while a single `sequencer_arguments` override handles per-host kwargs
+    # injection (current_user, params, etc.).
+    module RunSequence
+      def run_sequence(sequencer_class, **kwargs, &block)
+        sequence_runner.(sequencer_class, **sequencer_arguments(kwargs), &block)
+      end
+
+      # Override in the host (controller, job) to inject defaults like
+      # current_user without forcing every call site to pass them.
+      def sequencer_arguments(kwargs)
+        kwargs
+      end
+
+      private
+
+      def sequence_runner
+        @sequence_runner ||= Runner.new
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/runner.rb

@@ -0,0 +1,184 @@
+module Hubbado
+  module Sequence
+    # Invokes a sequencer and dispatches its Result to outcome blocks. Forgetting
+    # to handle a serious failure raises rather than silently swallowing it.
+    # Usable as a configurable dependency wherever a sequencer Result needs
+    # branch-style handling.
+    class Runner
+      configure :run_sequence
+
+      def self.build
+        new
+      end
+
+      def call(sequencer_class, **kwargs, &block)
+        result = sequencer_class.(**kwargs)
+
+        dispatch = Dispatch.new(sequencer_class, result)
+        block.call(dispatch) if block_given?
+
+        dispatch.enforce_safety_nets!
+
+        dispatch.returned
+      end
+
+      class Dispatch
+        include Hubbado::Log::Dependency
+
+        attr_reader :returned, :result, :sequencer_class
+
+        def initialize(sequencer_class, result)
+          @sequencer_class = sequencer_class
+          @result = result
+          @handled = false
+        end
+
+        def success
+          return unless @result.ok?
+          execute { yield(@result.ctx) }
+          logger.info("Sequencer #{@sequencer_class.name} succeeded: #{trail_summary}")
+        end
+
+        def policy_failed
+          return unless code == :forbidden
+          execute { yield(@result.ctx) }
+          logger.info("Sequencer #{@sequencer_class.name} policy failed at #{step_label} (#{code}): #{trail_summary}")
+        end
+
+        def not_found
+          return unless code == :not_found
+          execute { yield(@result.ctx) }
+          logger.info("Sequencer #{@sequencer_class.name} not found at #{step_label}: #{trail_summary}")
+        end
+
+        def validation_failed
+          return unless code == :validation_failed
+          execute { yield(@result.ctx) }
+          logger.info("Sequencer #{@sequencer_class.name} validation failed at #{step_label}: #{trail_summary}")
+        end
+
+        # otherwise deliberately does not catch policy denials or not_found —
+        # those have their own required handlers.
+        def otherwise
+          return if @result.ok?
+          return if code == :forbidden
+          return if code == :not_found
+          return if @handled
+
+          execute { yield(@result.ctx) }
+          logger.info("Sequencer #{@sequencer_class.name} failed at #{step_label} (#{code}): #{trail_summary}")
+        end
+
+        def code
+          @result.error&.[](:code)
+        end
+
+        def handled?
+          @result.ok? || @handled
+        end
+
+        def enforce_safety_nets!
+          return if handled?
+
+          log_unhandled
+
+          case code
+          when :forbidden
+            raise Errors::Unauthorized.new(
+              "#{@sequencer_class.name} denied: #{@result.message}",
+              @result
+            )
+          when :not_found
+            raise Errors::NotFound, "#{@sequencer_class.name} reported not_found"
+          else
+            raise Errors::Failed, "#{@sequencer_class.name} failed (#{code}): #{@result.message}"
+          end
+        end
+
+        def log_unhandled
+          logger.error("Sequencer #{@sequencer_class.name} failed unhandled at #{step_label} (#{code}): #{trail_summary}")
+        end
+
+        private
+
+        def execute
+          @handled = true
+          @returned = yield
+        end
+
+        def trail_summary
+          @result.trail.empty? ? "(no steps)" : @result.trail.map(&:to_s).join(" → ")
+        end
+
+        def step_label
+          step = @result.error && @result.error[:step]
+          step ? step.inspect : "(unknown step)"
+        end
+      end
+
+      module Substitute
+        include RecordInvocation
+
+        def succeed_with(**ctx_writes)
+          @configured_outcome = { kind: :success, ctx_writes: ctx_writes }
+          self
+        end
+
+        def policy_failure(**error_attrs)
+          configure_failure(:forbidden, error_attrs)
+        end
+
+        def not_found(**error_attrs)
+          configure_failure(:not_found, error_attrs)
+        end
+
+        def validation_failure(**error_attrs)
+          configure_failure(:validation_failed, error_attrs)
+        end
+
+        def other_error(code:, **error_attrs)
+          configure_failure(code, error_attrs)
+        end
+
+        def ran_with?(sequencer_class, **expected_kwargs)
+          records.any? do |invocation|
+            next false unless invocation.method_name == :call
+            next false unless invocation.arguments[:sequencer_class] == sequencer_class
+
+            captured = invocation.arguments[:kwargs] || {}
+            expected_kwargs.all? { |key, value| captured[key] == value }
+          end
+        end
+
+        record def call(sequencer_class, **kwargs, &block)
+          dispatch = Dispatch.new(sequencer_class, build_result)
+          block.call(dispatch) if block_given?
+          dispatch.enforce_safety_nets!
+          dispatch.returned
+        end
+
+        private
+
+        def configure_failure(code, error_attrs)
+          @configured_outcome = {
+            kind: :failure,
+            error: { code: code, **error_attrs }
+          }
+          self
+        end
+
+        def build_result
+          outcome = @configured_outcome || { kind: :success, ctx_writes: {} }
+          ctx = Hubbado::Sequence::Ctx.new
+
+          if outcome[:kind] == :success
+            outcome[:ctx_writes].each { |key, value| ctx[key] = value }
+            Hubbado::Sequence::Result.ok(ctx)
+          else
+            Hubbado::Sequence::Result.fail(ctx, error: outcome[:error])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/sequencer.rb

@@ -0,0 +1,109 @@
+module Hubbado
+  module Sequence
+    module Sequencer
+      def self.included(cls)
+        cls.send(:include, ::Dependency)
+        cls.send(:include, ::Configure)
+        cls.extend(ClassMethods)
+
+        install_default_substitute(cls)
+      end
+
+      # Each sequencer gets a default `Substitute` module so it can be used as a
+      # dependency without bespoke test scaffolding. The user can reopen the
+      # module in their class body to add per-sequencer assertions; the defaults
+      # below are always available.
+      def self.install_default_substitute(cls)
+        return if cls.const_defined?(:Substitute, false)
+
+        cls.const_set(:Substitute, build_default_substitute_module)
+      end
+
+      def self.build_default_substitute_module
+        Module.new do
+          include ::RecordInvocation
+
+          def succeed_with(**ctx_writes)
+            @configured_writes = ctx_writes
+            self
+          end
+
+          def fail_with(**error_attrs)
+            @configured_error = error_attrs
+            self
+          end
+
+          record def call(ctx)
+            return ::Hubbado::Sequence::Result.fail(ctx, error: @configured_error) if @configured_error
+
+            if @configured_writes
+              @configured_writes.each { |k, v| ctx[k] = v }
+            end
+            ::Hubbado::Sequence::Result.ok(ctx)
+          end
+
+          def called?(**kwargs)
+            invoked?(:call, **kwargs)
+          end
+        end
+      end
+
+      module ClassMethods
+        # Bridge between the kwargs boundary (controllers and other top-level
+        # callers) and the ctx-passing convention used inside the framework.
+        # A caller can supply either an existing Ctx (the nested-sequencer case)
+        # or keyword arguments that become the initial ctx (the outermost case).
+        def call(ctx = nil, **kwargs)
+          if ctx.nil?
+            ctx = Ctx.build(kwargs)
+          elsif !kwargs.empty?
+            raise ArgumentError, "#{name}.() takes either a Ctx or keyword arguments, not both"
+          elsif !ctx.is_a?(Ctx)
+            ctx = Ctx.build(ctx)
+          end
+
+          build.call(ctx)
+        end
+
+        # Default factory: a sequencer with no configurable dependencies needs
+        # nothing more than `new`. Sequencers that have dependencies override
+        # `self.build` to run the corresponding `Macro.configure(instance, …)`
+        # calls.
+        def build
+          new
+        end
+
+        def i18n_scope
+          @i18n_scope ||= ::Casing::Underscore::String.(name).gsub('/', '.')
+        end
+      end
+
+      def i18n_scope
+        self.class.i18n_scope
+      end
+
+      def failure(ctx, **error_attrs)
+        Result.fail(ctx, error: error_attrs, i18n_scope: i18n_scope)
+      end
+
+      # Builds a Pipeline that auto-dispatches blockless `step(:foo)` calls to
+      # `self.foo(ctx)`. Use this inside a sequencer's `call` body in place of
+      # `Pipeline.(ctx)` whenever steps are local methods.
+      #
+      # Block form (`pipeline(ctx) { |p| ... }`) yields the pipeline, runs the
+      # block, and returns the final Result — no trailing `.result` needed. The
+      # non-block form returns the Pipeline so chained `.step(...)...result`
+      # calls still work.
+      def pipeline(ctx, &block)
+        pipe = Pipeline.new(ctx, dispatcher: self)
+
+        if block
+          block.call(pipe)
+          pipe.result
+        else
+          pipe
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/sequence.rb

@@ -0,0 +1,30 @@
+require "i18n"
+require "casing"
+require "configure"; Configure.activate
+require "dependency"; Dependency.activate
+require "hubbado/log"
+require "record_invocation"
+require "template_method"; TemplateMethod.activate
+
+I18n.load_path += Dir[File.expand_path("../../config/locales", __dir__) + "/*.yml"]
+
+module Hubbado
+  module Sequence
+  end
+end
+
+require "hubbado/sequence/ctx"
+require "hubbado/sequence/path"
+require "hubbado/sequence/result"
+require "hubbado/sequence/pipeline"
+require "hubbado/sequence/sequencer"
+require "hubbado/sequence/macros/model/find"
+require "hubbado/sequence/macros/model/build"
+require "hubbado/sequence/macros/contract/build"
+require "hubbado/sequence/macros/contract/deserialize"
+require "hubbado/sequence/macros/contract/validate"
+require "hubbado/sequence/macros/contract/persist"
+require "hubbado/sequence/macros/policy/check"
+require "hubbado/sequence/errors"
+require "hubbado/sequence/runner"
+require "hubbado/sequence/run_sequence"

metadata

@@ -0,0 +1,227 @@
+--- !ruby/object:Gem::Specification
+name: hubbado-sequence
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Hubbado Devs
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: evt-casing
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: evt-configure
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: evt-dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: evt-record_invocation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: evt-template_method
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: hubbado-log
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: hubbado-style
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: test_bench
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Sequencer takes input, runs a sequence of steps, and returns a Result
+  indicating success or failure plus the working context that was built up during
+  execution.
+email:
+- devs@hubbado.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- config/locales/en.yml
+- hubbado-sequence.gemspec
+- lib/hubbado/sequence.rb
+- lib/hubbado/sequence/controls.rb
+- lib/hubbado/sequence/controls/contract.rb
+- lib/hubbado/sequence/controls/model.rb
+- lib/hubbado/sequence/controls/policy.rb
+- lib/hubbado/sequence/ctx.rb
+- lib/hubbado/sequence/errors.rb
+- lib/hubbado/sequence/macros/contract/build.rb
+- lib/hubbado/sequence/macros/contract/deserialize.rb
+- lib/hubbado/sequence/macros/contract/persist.rb
+- lib/hubbado/sequence/macros/contract/validate.rb
+- lib/hubbado/sequence/macros/model/build.rb
+- lib/hubbado/sequence/macros/model/find.rb
+- lib/hubbado/sequence/macros/policy/check.rb
+- lib/hubbado/sequence/path.rb
+- lib/hubbado/sequence/pipeline.rb
+- lib/hubbado/sequence/result.rb
+- lib/hubbado/sequence/run_sequence.rb
+- lib/hubbado/sequence/runner.rb
+- lib/hubbado/sequence/sequencer.rb
+homepage: https://github.com/hubbado/hubbado-sequence
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hubbado/hubbado-sequence
+  source_code_uri: https://github.com/hubbado/hubbado-sequence
+  changelog_uri: https://github.com/hubbado/hubbado-sequence/blob/master/CHANGELOG.md
+post_install_message:
+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.5.22
+signing_key:
+specification_version: 4
+summary: A small framework for orchestrating units of business behaviour
+test_files: []