interactor

Documentation

Overview

Package interactor defines the human-task boundary between the engine and an embedder (ADR-020): the pluggable TaskDistributor the engine announces parked UserTasks to, the TaskInfo/TaskView it hands across that boundary, the TaskCompletion event a completed task rides back on, and the HumanTask capability a UserTask node exposes so the engine can authorize and validate it.

Index

• type HumanTask
• type TaskCompletion
  • func NewTaskCompletion(outputs []data.Data) *TaskCompletion
  • func (c *TaskCompletion) GetItemsList() []*data.ItemDefinition
  • func (c *TaskCompletion) Outputs() []data.Data
  • func (c *TaskCompletion) Type() flow.EventTrigger
• type TaskDistributor
  • func NopDistributor() TaskDistributor
• type TaskInfo
• type TaskRef
• type TaskView

Types

type HumanTask

type HumanTask interface {
	foundation.Identifyer

	// Authorize reports whether actor may read/complete the task, resolving the
	// task's assignment triad against src via eng (ADR-020 §2.5). A nil error
	// means authorized; a non-nil error is a non-terminal denial.
	Authorize(
		ctx context.Context,
		actor hi.Actor,
		src data.Source,
		eng expression.Engine,
	) error

	// ValidateOutputs checks submitted outputs against the task's output spec.
	ValidateOutputs(outputs []data.Data) error

	// Renderers returns the task's form/field descriptions (for a TaskView).
	Renderers() []hi.Renderer

	// Roles returns the task's declared resource roles (for a TaskInfo).
	Roles() []*hi.ResourceRole

	// Outputs returns the task's output specification.
	Outputs() []*bpmncommon.ResourceParameter

	// Properties returns the task's properties (e.g. a FORM_ID convention),
	// carried self-describing in a TaskView's data.
	Properties() []*data.Property
}

HumanTask is the capability a UserTask node exposes to the engine so the loop can recognize it as a task that must park for human completion, announce it, authorize an acting Actor, and validate submitted outputs (ADR-020). The engine type-asserts a node to HumanTask; the node also implements eventproc.EventProcessor to receive the completion.

type TaskCompletion

type TaskCompletion struct {
	foundation.BaseElement
	// contains filtered or unexported fields
}

TaskCompletion is the synthetic event a completed UserTask rides back into the instance loop: it implements flow.EventDefinition, so it flows through the parked track's event channel exactly like a message payload, and it carries the validated outputs the UserTask binds to scope on resume (ADR-020 §2.1). It never reaches the EventHub or correlation, so its Type is an internal sentinel and it exposes no ItemDefinitions — the outputs travel via Outputs.

func NewTaskCompletion

func NewTaskCompletion(outputs []data.Data) *TaskCompletion

NewTaskCompletion builds a completion event carrying the validated outputs. Its base element (a fresh id, unused for routing) cannot fail to build, so the constructor does not return an error.

func (*TaskCompletion) GetItemsList

func (c *TaskCompletion) GetItemsList() []*data.ItemDefinition

GetItemsList returns nil — a completion carries its data via Outputs, not ItemDefinitions.

func (*TaskCompletion) Outputs

func (c *TaskCompletion) Outputs() []data.Data

Outputs returns the validated outputs the UserTask binds to scope on resume.

func (*TaskCompletion) Type

func (c *TaskCompletion) Type() flow.EventTrigger

Type returns the internal completion sentinel.

type TaskDistributor

type TaskDistributor interface {
	// Distribute announces a parked UserTask as available for human work.
	Distribute(ctx context.Context, task TaskInfo) error

	// Withdraw retracts a task that is no longer completable — it was completed,
	// or its activity was canceled (e.g. an interrupting boundary event fired).
	Withdraw(ctx context.Context, taskID string) error
}

TaskDistributor is the embedder-provided boundary that surfaces human tasks (ADR-020 §2.2), injected into the engine like MessageBroker or Clock. The engine calls it to announce a newly parked UserTask and to retract one that is no longer completable; it does NOT drive execution — the human acts through the engine's Take/Complete entry points, which the engine authorizes.

func NopDistributor

func NopDistributor() TaskDistributor

NopDistributor returns the no-op TaskDistributor used as the engine default.

type TaskInfo

type TaskInfo struct {
	TaskRef
	Roles []*hi.ResourceRole
}

TaskInfo is the announcement handed to a TaskDistributor when a UserTask becomes available — before any authorization — so it carries identity plus the roles that may claim it (for inbox routing/filtering) and deliberately NO task data: instance variables must not reach the distributor before an authorized Take (ADR-020 §2.8).

type TaskRef

type TaskRef struct {
	TaskID     string
	InstanceID string
	NodeID     string
	ProcessID  string
}

TaskRef identifies a parked human task across the engine boundary. It is embedded in both the pre-authorization announcement (TaskInfo) and the post-authorization snapshot (TaskView), so the identity is declared once (ADR-020 §2.8).

type TaskView

type TaskView struct {
	TaskRef
	Renderers []hi.Renderer
	Data      []data.Data
}

TaskView is the authorized snapshot returned by Take: the renderers to build the UI and the self-describing data (task inputs plus properties such as a FORM_ID convention). It is produced only after the acting Actor passes authorization, so — unlike TaskInfo — it carries the task's data.