hubbado-sequence 0.3.0

data/lib/hubbado/sequence/controls/policy.rb

@@ -0,0 +1,48 @@
+module Hubbado
+  module Sequence
+    module Controls
+      module Policy
+        # Minimal stand-in for a hubbado-policy::Result so we don't take a hard
+        # dependency on the policy gem from these controls.
+        class PolicyResult
+          attr_reader :reason
+
+          def initialize(permitted, reason)
+            @permitted = permitted
+            @reason = reason
+          end
+
+          def permitted?; @permitted; end
+          def denied?; !@permitted; end
+        end
+
+        def self.example_class(decision: :permit, action: :update)
+          Class.new do
+            attr_reader :user, :record
+
+            define_singleton_method(:default_decision) { decision }
+            define_singleton_method(:default_action) { action }
+
+            def self.build(user, record)
+              new(user, record)
+            end
+
+            def initialize(user, record)
+              @user = user
+              @record = record
+            end
+
+            define_method(action) do
+              decision = self.class.default_decision
+              if decision == :permit
+                PolicyResult.new(true, :permitted)
+              else
+                PolicyResult.new(false, :not_owner)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/controls.rb

@@ -0,0 +1,3 @@
+require "hubbado/sequence/controls/model"
+require "hubbado/sequence/controls/contract"
+require "hubbado/sequence/controls/policy"

data/lib/hubbado/sequence/ctx.rb

@@ -0,0 +1,19 @@
+module Hubbado
+  module Sequence
+    class Ctx < Hash
+      def self.build(initial = {})
+        ctx = new
+        ctx.merge!(initial)
+        ctx
+      end
+
+      def [](key)
+        unless key?(key)
+          raise KeyError, "key not found: #{key.inspect}"
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/errors.rb

@@ -0,0 +1,16 @@
+module Hubbado
+  module Sequence
+    module Errors
+      Failed = Class.new(StandardError)
+      NotFound = Class.new(StandardError)
+      Unauthorized = Class.new(StandardError) do
+        attr_reader :result
+
+        def initialize(message = nil, result = nil)
+          super(message)
+          @result = result
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/macros/contract/build.rb

@@ -0,0 +1,48 @@
+# Works with Reform contracts. Wraps a model in a contract class and writes the instance to ctx[:contract].
+module Hubbado
+  module Sequence
+    module Macros
+      module Contract
+        class Build
+          configure :build_contract
+
+          def self.build
+            new
+          end
+
+          def call(ctx, contract_class, attr_name = nil)
+            model = attr_name && Path.resolve(ctx, attr_name)
+            ctx[:contract] = contract_class.new(model)
+            Result.ok(ctx)
+          end
+
+          module Substitute
+            include ::RecordInvocation
+
+            def succeed_with(contract)
+              @return_value = contract
+              @configured_success = true
+              self
+            end
+
+            def fail_with(**error_attrs)
+              @configured_error = error_attrs
+              self
+            end
+
+            record def call(ctx, contract_class, attr_name = nil)
+              return Result.fail(ctx, error: @configured_error) if @configured_error
+
+              ctx[:contract] = @return_value if @configured_success
+              Result.ok(ctx)
+            end
+
+            def built?(**kwargs)
+              invoked?(:call, **kwargs)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/macros/contract/deserialize.rb

@@ -0,0 +1,43 @@
+# Works with Reform contracts. Calls contract.deserialize with params sourced from ctx; no-op when the path is absent.
+module Hubbado
+  module Sequence
+    module Macros
+      module Contract
+        class Deserialize
+          configure :deserialize_to_contract
+
+          def self.build
+            new
+          end
+
+          def call(ctx, from:)
+            params = Path.resolve(ctx, from, missing: :nil)
+
+            ctx[:contract].deserialize(params) if params
+
+            Result.ok(ctx)
+          end
+
+          module Substitute
+            include ::RecordInvocation
+
+            def fail_with(**error_attrs)
+              @configured_error = error_attrs
+              self
+            end
+
+            record def call(ctx, from:)
+              return Result.fail(ctx, error: @configured_error) if @configured_error
+
+              Result.ok(ctx)
+            end
+
+            def deserialized?(**kwargs)
+              invoked?(:call, **kwargs)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/macros/contract/persist.rb

@@ -0,0 +1,50 @@
+# Works with Reform contracts. Calls contract.save; fails with :persist_failed when save returns false.
+module Hubbado
+  module Sequence
+    module Macros
+      module Contract
+        class Persist
+          configure :persist
+
+          def self.build
+            new
+          end
+
+          def call(ctx)
+            contract = ctx[:contract]
+
+            if contract.save
+              Result.ok(ctx)
+            else
+              Result.fail(ctx, error: { code: :persist_failed })
+            end
+          end
+
+          module Substitute
+            include ::RecordInvocation
+
+            def succeed_with
+              @configured_success = true
+              self
+            end
+
+            def fail_with(**error_attrs)
+              @configured_error = error_attrs
+              self
+            end
+
+            record def call(ctx)
+              return Result.fail(ctx, error: @configured_error) if @configured_error
+
+              Result.ok(ctx)
+            end
+
+            def persisted?(**kwargs)
+              invoked?(:call, **kwargs)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/macros/contract/validate.rb

@@ -0,0 +1,53 @@
+# Works with Reform contracts. Validates the contract and checks errors; fails with :validation_failed when invalid.
+module Hubbado
+  module Sequence
+    module Macros
+      module Contract
+        class Validate
+          configure :validate
+
+          def self.build
+            new
+          end
+
+          def call(ctx, from: nil)
+            contract = ctx[:contract]
+            params = from ? Path.resolve(ctx, from) : {}
+
+            contract.validate(params)
+
+            if contract.errors.empty?
+              Result.ok(ctx)
+            else
+              Result.fail(ctx, error: { code: :validation_failed })
+            end
+          end
+
+          module Substitute
+            include ::RecordInvocation
+
+            def succeed_with
+              @configured_success = true
+              self
+            end
+
+            def fail_with(**error_attrs)
+              @configured_error = error_attrs
+              self
+            end
+
+            record def call(ctx, from: nil)
+              return Result.fail(ctx, error: @configured_error) if @configured_error
+
+              Result.ok(ctx)
+            end
+
+            def validated?(**kwargs)
+              invoked?(:call, **kwargs)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/macros/model/build.rb

@@ -0,0 +1,57 @@
+# Works with ActiveRecord models. Instantiates a new model record (with optional attributes) and writes it to ctx.
+module Hubbado
+  module Sequence
+    module Macros
+      module Model
+        class Build
+          configure :build_record
+
+          def self.build
+            new
+          end
+
+          def call(ctx, model, as:, attributes: nil)
+            ctx[as] =
+              if attributes.nil?
+                model.new
+              else
+                model.new(attributes)
+              end
+            Result.ok(ctx)
+          end
+
+          module Substitute
+            include ::RecordInvocation
+
+            def succeed_with(value)
+              @return_value = value
+              @configured_success = true
+              self
+            end
+
+            def fail_with(**error_attrs)
+              @configured_error = error_attrs
+              self
+            end
+
+            record def call(ctx, model, as:, attributes: nil)
+              unless model.respond_to?(:new)
+                raise ArgumentError,
+                  "Macros::Model::Build substitute: #{model} does not respond to :new"
+              end
+
+              return Result.fail(ctx, error: @configured_error) if @configured_error
+
+              ctx[as] = @return_value if @configured_success
+              Result.ok(ctx)
+            end
+
+            def built?(**kwargs)
+              invoked?(:call, **kwargs)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/macros/model/find.rb

@@ -0,0 +1,59 @@
+# Works with ActiveRecord models. Fetches a record by id from ctx and writes it to ctx; fails with :not_found on miss.
+module Hubbado
+  module Sequence
+    module Macros
+      module Model
+        class Find
+          configure :find
+
+          def self.build
+            new
+          end
+
+          def call(ctx, model, as:, id_key: %i[params id])
+            id = Path.resolve(ctx, id_key)
+            record = model.find_by(id: id)
+
+            if record
+              ctx[as] = record
+              Result.ok(ctx)
+            else
+              Result.fail(ctx, error: { code: :not_found })
+            end
+          end
+
+          module Substitute
+            include ::RecordInvocation
+
+            def succeed_with(value)
+              @return_value = value
+              @configured_success = true
+              self
+            end
+
+            def fail_with(**error_attrs)
+              @configured_error = error_attrs
+              self
+            end
+
+            record def call(ctx, model, as:, id_key: %i[params id])
+              unless model.respond_to?(:find_by)
+                raise ArgumentError,
+                  "Macros::Model::Find substitute: #{model} does not respond to :find_by"
+              end
+
+              return Result.fail(ctx, error: @configured_error) if @configured_error
+
+              ctx[as] = @return_value if @configured_success
+              Result.ok(ctx)
+            end
+
+            def fetched?(**kwargs)
+              invoked?(:call, **kwargs)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/macros/policy/check.rb

@@ -0,0 +1,65 @@
+# Works with hubbado-policy. Builds a policy instance and calls the action; fails with :forbidden when denied.
+module Hubbado
+  module Sequence
+    module Macros
+      module Policy
+        class Check
+          configure :check_policy
+
+          def self.build
+            new
+          end
+
+          def call(ctx, policy, record_key, action)
+            current_user = ctx[:current_user]
+            record = ctx[record_key]
+
+            policy_instance = policy.build(current_user, record)
+            policy_result = policy_instance.public_send(action)
+
+            if policy_result.permitted?
+              Result.ok(ctx)
+            else
+              Result.fail(
+                ctx,
+                error: {
+                  code: :forbidden,
+                  data: { policy: policy_instance, policy_result: policy_result }
+                }
+              )
+            end
+          end
+
+          module Substitute
+            include ::RecordInvocation
+
+            def succeed_with
+              @configured_success = true
+              self
+            end
+
+            def fail_with(**error_attrs)
+              @configured_error = error_attrs
+              self
+            end
+
+            record def call(ctx, policy, record_key, action)
+              unless policy.method_defined?(action)
+                raise ArgumentError,
+                  "Macros::Policy::Check substitute: #{policy} does not declare action :#{action}"
+              end
+
+              return Result.fail(ctx, error: @configured_error) if @configured_error
+
+              Result.ok(ctx)
+            end
+
+            def checked?(**kwargs)
+              invoked?(:call, **kwargs)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/path.rb

@@ -0,0 +1,35 @@
+module Hubbado
+  module Sequence
+    # Resolves a ctx path expressed as a single Symbol (one-key shorthand) or
+    # an Array of Symbols (nested fetch). Used by macros that need to read a
+    # value out of ctx at a configurable location.
+    #
+    # `missing:` selects how an absent key is reported:
+    #   :raise (default) — propagate KeyError. Right for Find/Validate/Build,
+    #                      where a missing path is a wiring bug or a not-found.
+    #   :nil             — return nil. Right for Deserialize, which runs ahead
+    #                      of validation and may legitimately encounter absent
+    #                      params (e.g. a fresh GET before the form is posted).
+    module Path
+      def self.resolve(ctx, path, missing: nil)
+        missing ||= :raise
+
+        unless %i[raise nil].include?(missing)
+          raise ArgumentError, "unknown missing policy: #{missing.inspect}"
+        end
+
+        if path.is_a?(Array) && path.empty?
+          raise ArgumentError, "path cannot be empty"
+        end
+
+        Array(path).reduce(ctx) do |acc, key|
+          if missing == :nil
+            acc.fetch(key) { return nil }
+          else
+            acc.fetch(key)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/sequence/pipeline.rb

@@ -0,0 +1,141 @@
+module Hubbado
+  module Sequence
+    class Pipeline
+      # `Pipeline.(ctx) { |p| ... }` is the block form: yields the pipeline,
+      # runs the block (so steps can be added in statement form), and returns
+      # the final Result. The non-block form returns the Pipeline so chained
+      # `.step(...)...result` calls still work.
+      def self.call(ctx = nil, **kwargs, &block)
+        if ctx.nil?
+          ctx = Ctx.build(kwargs)
+        elsif !kwargs.empty?
+          raise ArgumentError, "Pipeline.() takes either a Ctx or keyword arguments, not both"
+        elsif !ctx.is_a?(Ctx)
+          ctx = Ctx.build(ctx)
+        end
+
+        pipe = new(ctx)
+
+        if block
+          block.call(pipe)
+          pipe.result
+        else
+          pipe
+        end
+      end
+
+      def initialize(ctx, dispatcher: nil)
+        @ctx = ctx
+        @trail = []
+        @failed_result = nil
+        @dispatcher = dispatcher
+      end
+
+      # `step(:name) { |ctx| ... }` runs the block. `step(:name)` with no
+      # block dispatches to `dispatcher.send(name, ctx)` on the sequencer
+      # that built this pipeline (via the mixin's `pipeline(ctx)` helper).
+      # Block beats dispatch when both are available; raises if neither.
+      #
+      # Lenient return convention: a step is treated as successful unless it
+      # explicitly returns a failed `Result`. Any other return value (nil,
+      # false, a model, a hash, `Result.ok(...)`) is taken as success and the
+      # pipeline continues with the same `@ctx`. Only `Result.fail(...)` /
+      # `failure(ctx, code: ...)` short-circuits the pipeline.
+      def step(name, &block)
+        return self if @failed_result
+
+        return_value = invoke_step(name, block)
+
+        if return_value.is_a?(Result) && return_value.failure?
+          @failed_result = tag_failure(return_value, name)
+        else
+          @trail << name
+        end
+
+        self
+      end
+
+      # `invoke(:name, *args, **kwargs)` calls a declared dependency on the
+      # sequencer: gets the dependency via `dispatcher.send(name)` (the
+      # reader), then invokes it with `(ctx, *args, **kwargs)`. Same trail
+      # recording, failure short-circuiting, and lenient return convention as
+      # `step`.
+      #
+      # Use this for any declared dependency — macros (`Macros::Model::Find`)
+      # and nested sequencers (`Seqs::Present`) alike. Use `step` for local
+      # instance methods like `def deserialize_contract(ctx)`.
+      def invoke(name, *args, **kwargs)
+        return self if @failed_result
+
+        return_value = invoke_dependency(name, args, kwargs)
+
+        if return_value.is_a?(Result) && return_value.failure?
+          @failed_result = tag_failure(return_value, name)
+        else
+          @trail << name
+        end
+
+        self
+      end
+
+      def transaction(&block)
+        return self if @failed_result
+
+        if defined?(::ActiveRecord::Base)
+          ::ActiveRecord::Base.transaction do
+            yield(self)
+            raise ::ActiveRecord::Rollback if @failed_result
+          end
+        else
+          yield(self)
+        end
+
+        self
+      end
+
+      def result
+        if @failed_result
+          @failed_result
+        else
+          Result.ok(@ctx, trail: @trail.dup)
+        end
+      end
+
+      private
+
+      def invoke_step(name, block)
+        if block
+          block.call(@ctx)
+        elsif @dispatcher
+          unless @dispatcher.respond_to?(name, true)
+            raise NoMethodError,
+              "Pipeline step :#{name} expects #{@dispatcher.class.name} to define ##{name}, but it does not"
+          end
+          @dispatcher.send(name, @ctx)
+        else
+          raise ArgumentError,
+            "Pipeline step :#{name} needs either a block or a dispatcher (use the sequencer's `pipeline(ctx)` helper to enable auto-dispatch)"
+        end
+      end
+
+      def invoke_dependency(name, args, kwargs)
+        unless @dispatcher
+          raise ArgumentError,
+            "Pipeline#invoke :#{name} requires a dispatcher (use the sequencer's `pipeline(ctx)` helper)"
+        end
+
+        unless @dispatcher.respond_to?(name, true)
+          raise NoMethodError,
+            "Pipeline#invoke :#{name} expects #{@dispatcher.class.name} to declare a `dependency :#{name}, ...`"
+        end
+
+        @dispatcher.send(name).(@ctx, *args, **kwargs)
+      end
+
+      def tag_failure(result, step_name)
+        tagged_error = result.error.merge(step: step_name)
+        Result.fail(result.ctx, error: tagged_error, trail: @trail.dup, i18n_scope: result.i18n_scope)
+      end
+    end
+  end
+end