Help us shape the future of Go! Take the 2026 Go Developer Survey

orchestration

package
v0.3.2 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.