change_requests 0.2.0 → 0.2.2

data/lib/change_requests/authorization/callable.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Authorization
+    # Wraps the host-supplied policy of §9.2:
+    #
+    #   config.authorization = ->(actor:, request:, stage:, action:) {
+    #     Pundit.policy!(actor, request).public_send("#{action}?")
+    #   }
+    #
+    # `Configuration#authorization=` wraps a bare callable in this, so a host writes the lambda and
+    # the gem still has one object answering `allows?`.
+    #
+    # The quorum is the gem's unit of eligibility; a host policy is written against the request, so
+    # the request and the stage are resolved from the quorum rather than asked for again.
+    class Callable
+      attr_reader :policy
+
+      def initialize(policy)
+        @policy = policy
+      end
+
+      def allows?(actor:, quorum:, action: :approve)
+        stage = quorum.stage
+
+        !!policy.call(actor: actor, request: stage.change_request, stage: stage, action: action)
+      end
+    end
+  end
+end

data/lib/change_requests/authorization/permissions.rb

@@ -2,8 +2,73 @@
 
 module ChangeRequests
   module Authorization
+    # The default policy: does this actor satisfy this quorum's eligibility rows (§5.3, §9.2)?
+    #
+    # Written once. M9c re-expresses the identical predicate as the SQL of
+    # `Request.awaiting_approval_from`, so "the button is enabled" and "it appears in my inbox"
+    # cannot drift apart.
     class Permissions
-      # M1b-2 adds allows?(actor:, quorum:). Exists now so config.authorization has its default.
+      # `action` is ignored here - eligibility is the same question whichever command asks it. It
+      # exists because Authorization::Callable hands it on to the host's own policy.
+      def allows?(actor:, quorum:, action: :approve) # rubocop:disable Lint/UnusedMethodArgument
+        type = registered_type(actor)
+
+        return false unless type.may_approve
+
+        named_approver?(actor, quorum) || satisfies_permission_rows?(actor, type, quorum)
+      end
+
+      private
+
+      # Raises UnknownActorType for a class that is not registered: the registry is the allowlist,
+      # and an unregistered class cannot enter the system through any path (§9.1).
+      def registered_type(actor)
+        name = actor.class.name
+        type = ChangeRequests.config.actor_types[name]
+
+        return type if type
+
+        fail UnknownActorType,
+             "#{name} is not a registered actor type. " \
+             "Register it with `config.actor_type \"#{name}\"`."
+      end
+
+      def named_approver?(actor, quorum)
+        quorum.eligible_actors.any? do |row|
+          row.actor_type == actor.class.name && row.actor_id == actor.id.to_s
+        end
+      end
+
+      def satisfies_permission_rows?(actor, type, quorum)
+        rows = quorum.permissions.to_a
+
+        # "all of nothing" is vacuously true, which would let a quorum that only names its approvers
+        # admit everyone. A quorum with no rows grants eligibility to nobody by permission.
+        return false if rows.empty?
+
+        held    = permissions_of(actor, type)
+        matched = rows.select { |row| row_matches?(row, actor, held) }
+
+        quorum.all_match? ? matched.size == rows.size : matched.any?
+      end
+
+      # The 2x2 of §5.3. A row constraining neither axis matches nobody: "constrains nothing" is a
+      # bug the model and the CHECK both refuse, never a wildcard.
+      def row_matches?(row, actor, held)
+        return false if row.permission.nil? && row.actor_type.nil?
+
+        (row.permission.nil? || held.include?(row.permission)) &&
+          (row.actor_type.nil? || row.actor_type == actor.class.name)
+      end
+
+      # Through the actor type's own lambda, never through a method on the actor: User and Admin may
+      # derive their permissions completely differently and still be compared against one stage
+      # definition (§9.2).
+      def permissions_of(actor, type)
+        return [] if type.permissions.nil?
+
+        Array(type.permissions.call(actor)).map(&:to_s)
+      end
     end
   end
 end

data/lib/change_requests/commands/approve.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # Records one approver's decision and which quorums it counted toward (§7).
+    #
+    #   Commands::Approve.call(request:, actor: current_user, comment: "Checked with HR")
+    class Approve < Base
+      # §15.3: two concurrent approvals by the same actor race the unique index, and the loser must
+      # hear the same refusal the guard would have given, not a 500.
+      on_conflict NotApprovable, reason: :already_decided
+
+      def self.call(request:, actor:, comment: nil)
+        new(request: request, actor: actor, comment: comment).call
+      end
+
+      def perform
+        # Built once and asked twice: the reason it refuses and the quorums it links must come from
+        # one evaluation, not two (I7).
+        guard = Guards::Approve.new(request: request, actor: actor)
+        guard.check!
+
+        approval = record_decision
+        link(approval, guard.countable_quorums)
+        emit(:approved, body: comment, metadata: metadata_for(approval))
+
+        # Commands::EvaluateWorkflow is M1b-12. Until it lands nothing advances the stage.
+        request
+      end
+
+      private
+
+      def comment
+        options[:comment]
+      end
+
+      def record_decision
+        stage.approvals.create!(
+          change_request: request,
+          approver: actor,
+          decision: "approved",
+          comment: comment,
+          decided_at: Time.current
+        )
+      end
+
+      # Written at decision time and never re-derived, so a later role change cannot silently
+      # un-approve a request (§5.3).
+      def link(approval, quorums)
+        quorums.each { |quorum| approval.approval_quorums.create!(quorum: quorum) }
+      end
+
+      # The quorum key is omitted for a stage of one nameless quorum, because "which quorum" is not
+      # a meaningful question there (§5.9).
+      def metadata_for(approval)
+        metadata = { stage: stage.name }
+        names = approval.quorums.map(&:name).compact
+
+        metadata[:quorums] = names if names.any?
+
+        metadata
+      end
+
+      def stage
+        @stage ||= request.current_stage
+      end
+    end
+  end
+end

data/lib/change_requests/commands/base.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # Guard, mutate, emit - inside one lock (§7).
+    #
+    #   class Approve < Base
+    #     on_conflict NotApprovable, reason: :already_decided
+    #
+    #     def perform
+    #       Guards::Approve.new(request:, actor:).check!
+    #       ...
+    #     end
+    #   end
+    #
+    # Commands raise rather than returning a result object (§19.3), and never accept permissions
+    # from the caller: they take an actor, and the gem resolves that actor's permissions through
+    # their registered type (§7, §9).
+    class Base
+      # Which TransitionError a lost race becomes. Only a command that actually competes for a
+      # unique index declares one.
+      class_attribute :conflict_mapping, instance_accessor: false
+
+      attr_reader :request, :actor, :options
+
+      class << self
+        def call(request:, actor: nil, **)
+          new(request: request, actor: actor, **).call
+        end
+
+        def on_conflict(error_class, reason:)
+          self.conflict_mapping = { error_class: error_class, reason: reason }
+        end
+      end
+
+      def initialize(request:, actor: nil, **options)
+        @request = request
+        @actor   = actor
+        @options = options
+      end
+
+      # SELECT … FOR UPDATE, which reloads: a command reads the row it locked, never the object it
+      # was handed. Rails refuses to lock a record carrying unsaved changes, so a caller cannot lose
+      # an assignment it thought it was making.
+      def call
+        around_perform { perform }
+      rescue ActiveRecord::RecordNotUnique => e
+        refuse_conflict(e)
+      rescue ActiveRecord::StaleObjectError
+        raise StaleRequest, "Change request #{request.id} changed while this command was running."
+      end
+
+      def perform
+        fail NotImplementedError, "#{self.class.name} must implement #perform"
+      end
+
+      # Create overrides this: it has no row to lock until it has written one.
+      def around_perform(&)
+        request.with_lock(&)
+      end
+
+      # The single write path for events (§5.5), so the stamped columns are populated in one place.
+      # M10 hangs config.on_event and ActiveSupport::Notifications here.
+      def emit(kind, body: nil, metadata: {})
+        request.events.create!(
+          **event_actor,
+          kind: kind.to_s,
+          operation_version: event_operation_version,
+          body: body,
+          metadata: metadata,
+          occurred_at: Time.current
+        )
+      end
+
+      def config
+        ChangeRequests.config
+      end
+
+      # Resolved live, never from the columns on the row: those are audit data (§6.12).
+      def operation
+        ChangeRequests.operations[request.operation_key]
+      end
+
+      private
+
+      def event_actor
+        return Event::SYSTEM_ATTRIBUTES if actor.nil?
+
+        attributes = ChangeRequests.actor_attributes(actor)
+
+        { actor_type: attributes[:type], actor_id: attributes[:id], actor_label: attributes[:label] }
+      end
+
+      # The version in force when this transition happened, which is deliberately not the request's
+      # creation-time value. They diverge whenever a declaration changes during a request's life.
+      # The fallback covers the only events ever written without a live declaration - Comment, and
+      # the operation_undeclared cancellation reporting that very disappearance (§5.5, §5.11).
+      def event_operation_version
+        operation&.version || request.operation_version
+      end
+
+      # Never a 500 for a race the gem can lose (§15.3) - but an undeclared conflict is a bug to
+      # see, not a refusal to dress it up as.
+      def refuse_conflict(error)
+        mapping = self.class.conflict_mapping
+
+        fail error if mapping.nil?
+
+        fail mapping[:error_class].new(request: request, reason: mapping[:reason])
+      end
+    end
+  end
+end

data/lib/change_requests/commands/cancel.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # Calls the whole request off (§7.2).
+    #
+    #   Commands::Cancel.call(request:, actor: current_user, reason: "No longer needed")
+    #
+    # `canceled` is final. Unlike a rejection there is no stage-level counterpart and no cooldown:
+    # cancelling is not a decision on a step, it is the end of the request.
+    class Cancel < Base
+      def self.call(request:, actor:, reason:)
+        new(request: request, actor: actor, reason: reason).call
+      end
+
+      def perform
+        Guards::Cancel.new(request: request, actor: actor).check!
+        refuse_without_reason
+
+        # Emitted before the status changes, so the trail records the request as it was cancelled
+        # rather than as it ended up.
+        emit(:canceled, body: reason, metadata: { status: request.status })
+        request.update!(status: "canceled")
+
+        request
+      end
+
+      private
+
+      def reason
+        options[:reason]
+      end
+
+      # Authorization first, as in Reject: someone who may not cancel at all should not be told
+      # they merely forgot a sentence.
+      def refuse_without_reason
+        return if reason.present?
+
+        fail NotCancelable.new(request: request, reason: :reason_required)
+      end
+    end
+  end
+end

data/lib/change_requests/commands/comment.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # Leaves a note on a request, whatever state it is in (§7.2, §5.5).
+    #
+    #   Commands::Comment.call(request:, actor: current_user, body: "Waiting on legal")
+    #
+    # Writes an event and nothing else - no request column changes, so the terminal-state guard is
+    # never in its way and a `successful` or `canceled` request can still be annotated.
+    class Comment < Base
+      def self.call(request:, actor:, body:)
+        new(request: request, actor: actor, body: body).call
+      end
+
+      def perform
+        Guards::Comment.new(request: request, actor: actor).check!
+        refuse_without_body
+
+        # When no live declaration exists, emit stamps the request's creation-time
+        # operation_version - the only version there is to record (§5.5, §5.11).
+        emit(:commented, body: body)
+      end
+
+      private
+
+      def body
+        options[:body]
+      end
+
+      # An empty note is noise in a trail that can never be cleaned up. Authorization first, as in
+      # Reject and Cancel.
+      def refuse_without_body
+        return if body.present?
+
+        fail NotAuthorized.new(request: request, reason: :body_required)
+      end
+    end
+  end
+end

data/lib/change_requests/commands/create.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # Records the intent instead of running it, and freezes the approval policy onto the row (§7.2).
+    #
+    #   Commands::Create.call(
+    #     operation_key: "members.update_roles",
+    #     payload:       { member_id: 42, roles: %w(editor) },
+    #     requester:     current_admin,
+    #     tenant:        current_organization      # optional
+    #   )
+    #
+    # M2 wraps this as `ChangeRequests.request!`.
+    #
+    # The call is identical however elaborate the workflow is: thresholds, permissions and quorum
+    # structure come from the declaration, never from the caller (§6.12 point 3).
+    class Create < Base
+      attr_reader :operation_key, :requester, :payload, :tenant
+
+      def self.call(operation_key:, requester:, payload: {}, tenant: nil)
+        new(operation_key: operation_key, requester: requester, payload: payload, tenant: tenant).call
+      end
+
+      def initialize(operation_key:, requester:, payload: {}, tenant: nil)
+        super(request: nil, actor: requester)
+
+        @operation_key = operation_key.to_s
+        @requester     = requester
+        @payload       = payload
+        @tenant        = tenant
+      end
+
+      # Base's helper resolves the operation from the request, which does not exist yet.
+      def operation
+        ChangeRequests.operations[operation_key]
+      end
+
+      def perform
+        declaration = usable_operation
+        refuse_unless_may_request
+
+        @request = write_request(declaration)
+        materialise(declaration.workflow)
+        emit(:requested)
+
+        request
+      end
+
+      private
+
+      # The whole graph, or none of it.
+      def around_perform(&)
+        Record.transaction(&)
+      end
+
+      def usable_operation
+        declaration = operation
+
+        fail UnknownOperation, "No operation is declared for #{operation_key.inspect} (§5.11)." if declaration.nil?
+
+        refuse_incomplete(declaration)
+
+        declaration
+      end
+
+      # Both would otherwise surface as a NOT NULL violation or as a request that can never leave
+      # `pending`. M2's `verify!` catches them at boot; this is the backstop. Reported together,
+      # like Configuration#validate!: one call should fix one round of mistakes.
+      def refuse_incomplete(declaration)
+        problems = []
+
+        if declaration.service.blank?
+          problems << "it declares no service, so nothing could ever execute it - set `op.service`"
+        end
+
+        if declaration.workflow.empty?
+          problems << "it declares no approvals, so a request could never be approved - " \
+                      "declare `op.approvals`"
+        end
+
+        return if problems.empty?
+
+        fail ConfigurationError,
+             "Operation #{operation_key.inspect} cannot be requested (§6.4):\n- #{problems.join("\n- ")}"
+      end
+
+      # Which actions a given person may trigger is the host's own authorization question, answered
+      # before this call. The registry answers only which *classes* may raise a request (§19.4).
+      def refuse_unless_may_request
+        type = ChangeRequests.config.actor_types[requester.class.name]
+
+        # Unregistered classes are the allowlist's business, and actor_attributes raises for them.
+        return if type.nil? || type.may_request
+
+        fail NotAuthorized,
+             "#{requester.class.name} may not raise change requests. " \
+             "Set `t.may_request = true` on its registration (§9.1)."
+      end
+
+      def write_request(declaration)
+        Request.create!(
+          operation_key: declaration.key,
+          operation_version: declaration.version,
+          service: declaration.service,
+          method_name: declaration.method_name.to_s,
+          payload: validated_payload,
+          payload_labels: labels,
+          requester: requester,
+          tenant: tenant,
+          max_attempts: declaration.max_attempts,
+          expires_at: expires_at(declaration)
+        )
+      end
+
+      # The gem validates only that it is a JSON object; matching it to the target's signature is
+      # the host's responsibility (§6.12).
+      def validated_payload
+        return payload if payload.is_a?(Hash)
+
+        fail InvalidPayload,
+             "payload must be a JSON object, got #{payload.class}. It is dispatched as " \
+             "`**payload.symbolize_keys`, so its keys become the target's keyword arguments (§6.12)."
+      end
+
+      # Snapshotted so a request stays readable after the records the payload refers to are gone.
+      def labels
+        return {} if operation.payload_labels.nil?
+
+        operation.payload_labels.call(validated_payload).to_h.transform_keys(&:to_s)
+      end
+
+      def expires_at(declaration)
+        declaration.expires_in && (Time.current + declaration.expires_in)
+      end
+
+      # The frozen snapshot: editing the operation afterwards never reaches this request, and never
+      # leaves it wrongly approved or wrongly pending (§6.12 point 4).
+      def materialise(workflow)
+        workflow.stages.each do |described_stage|
+          stage = request.stages.create!(
+            position: described_stage.position,
+            name: described_stage.name.to_s,
+            satisfied_by: described_stage.satisfied_by.to_s
+          )
+
+          described_stage.quorums.each { |described| materialise_quorum(stage, described) }
+        end
+      end
+
+      def materialise_quorum(stage, described)
+        quorum = stage.quorums.create!(
+          position: described.position,
+          name: described.name&.to_s,
+          threshold: described.threshold,
+          permission_match: described.permission_match.to_s
+        )
+
+        described.permissions.each do |row|
+          quorum.permissions.create!(permission: row.permission, actor_type: row.actor_type)
+        end
+
+        # The declaration kept the actor objects as the host wrote them; this is where they resolve
+        # to (type, id), and where an unregistered class is refused (§9.1).
+        described.eligible_actors.each { |actor| quorum.eligible_actors.create!(actor: actor) }
+      end
+    end
+  end
+end

data/lib/change_requests/commands/expire.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # The clock closing a request nobody acted on (§7.2, §8).
+    #
+    #   Commands::Expire.call(request:)
+    #
+    # No actor: `emit` stamps `SYSTEM_ACTOR` rather than a NULL, so "who did this" is answerable for
+    # every row and no presenter branches on nil (§5.5, §19.15).
+    #
+    # This is the transition only. `Maintenance.expire_stale!`, which sweeps
+    # `Request.expired_candidates` on a schedule, is M3b.
+    class Expire < Base
+      def perform
+        Guards::Expire.new(request: request, actor: actor).check!
+
+        # Emitted before the status changes, so the trail records what expired rather than what it
+        # became - which is `expired` for every one of these rows.
+        emit(:expired, metadata: { status: request.status, expires_at: request.expires_at })
+        request.update!(status: "expired")
+
+        request
+      end
+    end
+  end
+end

data/lib/change_requests/commands/reject.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # Rejection is a stop, not a count (§7.1).
+    #
+    #   Commands::Reject.call(request:, actor: current_user, reason: "Wrong member")
+    #
+    # One rejection from any eligible approver, or from the requester, rejects the whole request.
+    # Rejection thresholds are deliberately not modelled.
+    #
+    # `config.only_record_rejections = true` records the decision and the event without
+    # short-circuiting: the workflow continues, and the rejector has spent their decision on that
+    # stage - the unique index is what guarantees they cannot later approve it.
+    class Reject < Base
+      on_conflict NotRejectable, reason: :already_decided
+
+      def self.call(request:, actor:, reason:)
+        new(request: request, actor: actor, reason: reason).call
+      end
+
+      def perform
+        Guards::Reject.new(request: request, actor: actor).check!
+        refuse_without_reason
+
+        record_decision
+        emit(:rejected, body: reason, metadata: metadata)
+
+        stop unless config.only_record_rejections
+
+        # Commands::EvaluateWorkflow is M1b-12, and only the recorded-only branch would call it.
+        request
+      end
+
+      private
+
+      def reason
+        options[:reason]
+      end
+
+      # Authorization first: someone who may not reject at all should not be told they merely
+      # forgot a sentence.
+      def refuse_without_reason
+        return if reason.present?
+
+        fail NotRejectable.new(request: request, reason: :reason_required)
+      end
+
+      # Written in both branches, so change_request_approvals stays the complete record of who
+      # decided what on each stage and the unique index behaves identically either way (Q26).
+      def record_decision
+        stage.approvals.create!(
+          change_request: request,
+          approver: actor,
+          decision: "rejected",
+          comment: reason,
+          decided_at: Time.current
+        )
+      end
+
+      # Whether the workflow continued is the fact an audit asks about first, and it depends on a
+      # config flag that may since have been changed.
+      def metadata
+        { stage: stage.name, recorded_only: config.only_record_rejections }
+      end
+
+      def stop
+        stage.update!(status: "rejected")
+        request.update!(status: "rejected")
+      end
+
+      def stage
+        @stage ||= request.current_stage
+      end
+    end
+  end
+end

data/lib/change_requests/commands/unapprove.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # Takes one actor's decision back (§7.1).
+    #
+    #   Commands::Unapprove.call(request:, actor: current_user)
+    #
+    # The row goes; the trail does not. `Event` is append-only, so the `approved` event stays beside
+    # the `unapproved` one and the timeline records both decisions (§5.5).
+    class Unapprove < Base
+      def self.call(request:, actor:)
+        new(request: request, actor: actor).call
+      end
+
+      def perform
+        guard = Guards::Unapprove.new(request: request, actor: actor)
+        guard.check!
+
+        decision = guard.decision
+        # Read before the row goes: the links are gone a line later.
+        metadata = metadata_for(decision)
+
+        # Deleting the approval is what removes its quorum links: ApprovalQuorum is Immutable, so
+        # `decision.quorums.destroy_all` - the obvious code - raises ReadOnlyRecord. The
+        # association carries no `dependent:`, and the database cascades (Q15).
+        decision.destroy!
+
+        emit(:unapproved, metadata: metadata)
+
+        # Commands::EvaluateWorkflow is M1b-12. Until it lands nothing re-counts the stage.
+        request
+      end
+
+      private
+
+      # Names what was retracted and where. Without it, a request that gained and lost the same
+      # approval twice would leave two indistinguishable pairs in the timeline (§5.9).
+      def metadata_for(decision)
+        metadata = { stage: decision.stage.name, decision: decision.decision }
+        names = decision.quorums.map(&:name).compact
+
+        metadata[:quorums] = names if names.any?
+
+        metadata
+      end
+    end
+  end
+end