orchestration

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 15, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MaxEvents        = 512
	MaxEventLogBytes = 256 * 1024
	MaxReplayLimit   = 200
)
View Source 
const (
	MaxRuns          = 256
	MaxRunTasks      = 128
	MaxRunGates      = 16
	MinLeaseDuration = 5 * time.Second
	MaxLeaseDuration = 30 * time.Minute
)
View Source 
const (
	MaxResultSummary = 8192
	MaxReason        = 1024
)
View Source 
const MaxTasks = 1000

Variables

View Source 
var (
	ErrNotFound  = errors.New("task not found")
	ErrConflict  = errors.New("task state conflict")
	ErrForbidden = errors.New("task mutation forbidden")
	ErrInvalid   = errors.New("invalid task")
)
View Source 
var (
	ErrLeaseConflict = errors.New("run lease conflict")
)
View Source 
var ErrReplayGap = errors.New("orchestration event gap")

Functions

func ValidRunID 

func ValidRunID(id string) bool

func ValidTaskID 

func ValidTaskID(id string) bool

Types

type ApprovalGate 

type ApprovalGate struct {
	ID         string         `json:"id"`
	Operation  OperationClass `json:"operation"`
	State      GateState      `json:"state"`
	Generation uint64         `json:"generation"`
	ExpiresAt  time.Time      `json:"expires_at"`
	ApprovedBy string         `json:"approved_by,omitempty"`
	ApprovedAt *time.Time     `json:"approved_at,omitempty"`
}

type Artifact 

type Artifact struct {
	Kind  string `json:"kind"`
	Value string `json:"value"`
}

type Capabilities 

type Capabilities struct{ Sender, Target string }

type CreateRequest 

type CreateRequest struct {
	ParentID, IdempotencyKey, RunID               string
	FromSessionID, TargetSessionID, TargetProfile string
	DeadlineAt                                    *time.Time
	SenderCapability                              string
}

type CreateRunRequest 

type CreateRunRequest struct {
	IdempotencyKey string
	GoalRef        string
	TaskIDs        []string
	Dependencies   map[string][]string
	Coordinator    string
	LeaseDuration  time.Duration
	GateOperations []OperationClass
}

type Event 

type Event struct {
	Seq        uint64    `json:"seq"`
	Type       string    `json:"type"`
	EntityType string    `json:"entity_type"`
	EntityID   string    `json:"entity_id"`
	OccurredAt time.Time `json:"occurred_at"`
	State      string    `json:"state,omitempty"`
	Reason     string    `json:"reason,omitempty"`
}

type GateState 

type GateState string
const (
	GatePending  GateState = "pending"
	GateApproved GateState = "approved"
	GateRejected GateState = "rejected"
)

type Lease 

type Lease struct {
	Coordinator string    `json:"coordinator"`
	Generation  uint64    `json:"generation"`
	ExpiresAt   time.Time `json:"expires_at"`
}

type OperationClass 

type OperationClass string
const (
	OperationMerge  OperationClass = "merge"
	OperationPush   OperationClass = "push"
	OperationDelete OperationClass = "delete"
)

type Replay 

type Replay struct {
	Events         []Event `json:"events"`
	NextCursor     uint64  `json:"next_cursor"`
	SnapshotCursor uint64  `json:"snapshot_cursor,omitempty"`
	Gap            bool    `json:"gap,omitempty"`
}

type Run 

type Run struct {
	ID              string              `json:"id"`
	IdempotencyKey  string              `json:"idempotency_key,omitempty"`
	GoalRef         string              `json:"goal_ref"`
	TaskIDs         []string            `json:"task_ids,omitempty"`
	Dependencies    map[string][]string `json:"dependencies,omitempty"`
	CurrentTaskID   string              `json:"current_task_id,omitempty"`
	LastAckedTaskID string              `json:"last_acked_task_id,omitempty"`
	State           RunState            `json:"state"`
	Reason          string              `json:"reason,omitempty"`
	Owner           string              `json:"owner"`
	Lease           Lease               `json:"lease"`
	RetryCount      int                 `json:"retry_count"`
	Gates           []ApprovalGate      `json:"gates,omitempty"`
	CreatedAt       time.Time           `json:"created_at"`
	UpdatedAt       time.Time           `json:"updated_at"`
}

type RunState 

type RunState string
const (
	RunRunning   RunState = "running"
	RunBlocked   RunState = "blocked"
	RunCompleted RunState = "completed"
	RunFailed    RunState = "failed"
	RunCancelled RunState = "cancelled"
)

type Store 

type Store struct {
	// contains filtered or unexported fields
}

func NewStore 

func NewStore(path string) (*Store, error)

func (*Store) Acknowledge 

func (s *Store) Acknowledge(id, actor string) (Task, error)

func (*Store) AcknowledgeAuthorized 

func (s *Store) AcknowledgeAuthorized(id, actor, capability string) (Task, error)

func (*Store) ApproveRun 

func (s *Store) ApproveRun(id, gateID, actor string, gateGeneration, leaseGeneration uint64, ttl time.Duration, approve bool) (Run, error)

func (*Store) BindTarget 

func (s *Store) BindTarget(id, target string) (Task, error)

func (*Store) Cancel 

func (s *Store) Cancel(id, actor string) (Task, error)

func (*Store) CancelAuthorized 

func (s *Store) CancelAuthorized(id, actor, capability string) (Task, error)

func (*Store) CancelRun 

func (s *Store) CancelRun(id, coordinator string, generation uint64) (Run, error)

func (*Store) Create 

func (s *Store) Create(req CreateRequest) (Task, bool, error)

func (*Store) CreateAuthorized 

func (s *Store) CreateAuthorized(req CreateRequest) (Task, Capabilities, bool, error)

func (*Store) CreateRun 

func (s *Store) CreateRun(req CreateRunRequest) (Run, bool, error)

func (*Store) Expire 

func (s *Store) Expire(now time.Time) ([]Task, error)

Expire fails unfinished tasks whose caller-supplied deadline elapsed.

func (*Store) FailQueued 

func (s *Store) FailQueued(id, reason string) (Task, error)

func (*Store) Get 

func (s *Store) Get(id string) (Task, error)

func (*Store) GetRun 

func (s *Store) GetRun(id string) (Run, error)

func (*Store) HealthError 

func (s *Store) HealthError() error

func (*Store) List 

func (s *Store) List() []Task

func (*Store) ListRuns 

func (s *Store) ListRuns() []Run

func (*Store) PublishRunState 

func (s *Store) PublishRunState(sessionID, state, reason string) error

func (*Store) PublishRunStateRemoved 

func (s *Store) PublishRunStateRemoved(sessionID string) error

func (*Store) ReconcileRuns 

func (s *Store) ReconcileRuns(now time.Time) ([]Run, error)

func (*Store) ReplayEvents 

func (s *Store) ReplayEvents(since uint64, limit int) (Replay, error)

func (*Store) ResumeRun 

func (s *Store) ResumeRun(id, coordinator string, generation uint64, leaseDuration time.Duration) (Run, error)

func (*Store) SetResult 

func (s *Store) SetResult(id, actor, summary string, artifacts []Artifact, failed bool) (Task, error)

func (*Store) SetResultAuthorized 

func (s *Store) SetResultAuthorized(id, actor, capability, summary string, artifacts []Artifact, failed bool) (Task, error)

func (*Store) Transition 

func (s *Store) Transition(id, actor string, to TaskState, reason string) (Task, error)

func (*Store) TransitionAuthorized 

func (s *Store) TransitionAuthorized(id, actor, capability string, to TaskState, reason string) (Task, error)

func (*Store) TransitionSystem 

func (s *Store) TransitionSystem(id string, to TaskState, reason string) (Task, error)

TransitionSystem records delivery-system outcomes. It is intentionally separate from actor-authorized transitions so REST callers cannot acquire server authority by omitting an actor.

func (*Store) WaitEvents 

func (s *Store) WaitEvents(ctx context.Context, since uint64, limit int, wait time.Duration) (Replay, error)

type Task 

type Task struct {
	ID                   string     `json:"id"`
	ParentID             string     `json:"parent_id,omitempty"`
	IdempotencyKey       string     `json:"idempotency_key,omitempty"`
	RunID                string     `json:"run_id,omitempty"`
	FromSessionID        string     `json:"from_session_id"`
	TargetSessionID      string     `json:"target_session_id,omitempty"`
	TargetProfile        string     `json:"target_profile,omitempty"`
	State                TaskState  `json:"state"`
	CreatedAt            time.Time  `json:"created_at"`
	UpdatedAt            time.Time  `json:"updated_at"`
	DeadlineAt           *time.Time `json:"deadline_at,omitempty"`
	ResultSummary        string     `json:"result_summary,omitempty"`
	Artifacts            []Artifact `json:"artifacts,omitempty"`
	Reason               string     `json:"reason,omitempty"`
	AcknowledgedAt       *time.Time `json:"acknowledged_at,omitempty"`
	SenderCapabilityHash string     `json:"sender_capability_hash,omitempty"`
	TargetCapabilityHash string     `json:"target_capability_hash,omitempty"`
}

type TaskState 

type TaskState string
const (
	TaskQueued    TaskState = "queued"
	TaskDelivered TaskState = "delivered"
	TaskWorking   TaskState = "working"
	TaskBlocked   TaskState = "blocked"
	TaskCompleted TaskState = "completed"
	TaskFailed    TaskState = "failed"
	TaskCancelled TaskState = "cancelled"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.