task

package
v1.20.0-beta.16 Latest Latest
Warning

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

 Go to latest Published: Oct 4, 2026 License: MPL-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package task tracks detached background work so its status can be polled independently of the CLI invocation that started it.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrCanceled  = errors.New("canceled")
	ErrAbandoned = errors.New("worker exited without recording a result")
)

Functions

func WorkerProcessName 

func WorkerProcessName(id string) string

WorkerProcessName returns the background-process name a detached task's worker is registered under.

Types

type CreateOptions 

type CreateOptions struct {
	Command     string
	WorkspaceID string
}

CreateOptions labels a task at creation time for later listing.

type State 

type State struct {
	ID                     string              `json:"id"`
	Command                string              `json:"command,omitempty"`
	WorkspaceID            string              `json:"workspaceId,omitempty"`
	Status                 Status              `json:"status"`
	Phase                  string              `json:"phase,omitempty"`
	Step                   string              `json:"step,omitempty"`
	OperationID            string              `json:"operationId,omitempty"`
	ParentOperationID      string              `json:"parentOperationId,omitempty"`
	DurationMs             int64               `json:"durationMs,omitempty"`
	Error                  string              `json:"error,omitempty"`
	ErrorCode              string              `json:"errorCode,omitempty"`
	ErrorHint              string              `json:"errorHint,omitempty"`
	ErrorContext           map[string]string   `json:"errorContext,omitempty"`
	Result                 *config.Result      `json:"result,omitempty"`
	PID                    int                 `json:"pid,omitempty"`
	ProcessTreeIdentity    string              `json:"processTreeIdentity,omitempty"`
	Process                *command.ProcessRef `json:"process,omitempty"`
	ProcessCleanupComplete bool                `json:"processCleanupComplete,omitempty"`
	CancelRequested        bool                `json:"cancelRequested,omitempty"`
	LaunchPending          bool                `json:"launchPending,omitempty"`
	StartedAt              time.Time           `json:"startedAt"`
	UpdatedAt              time.Time           `json:"updatedAt"`
}

State is the JSON snapshot persisted for a task. PID names the OS process doing the work, distinct from whatever process is merely polling this state.

func (*State) Canceled added in v1.20.0 

func (s *State) Canceled() bool

func (*State) NeedsCanceledWorkerCleanup added in v1.20.0 

func (s *State) NeedsCanceledWorkerCleanup() bool

NeedsCanceledWorkerCleanup includes records written by versions that marked cancellation complete before the worker tree was actually terminated.

func (*State) NeedsExitedWorkerCleanup added in v1.20.0 

func (s *State) NeedsExitedWorkerCleanup() bool

NeedsExitedWorkerCleanup identifies abandoned tasks whose saved tree has not yet been checked. Other terminal tasks completed their own teardown.

func (*State) ProcessReference added in v1.20.0 

func (s *State) ProcessReference() (command.ProcessRef, bool)

type Status 

type Status string
const (
	StatusPending   Status = "pending"
	StatusRunning   Status = "running"
	StatusSucceeded Status = "succeeded"
	StatusFailed    Status = "failed"
)

func (Status) Terminal 

func (s Status) Terminal() bool

type Store 

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

Store persists task state as one JSON file per task under dir.

func NewStore 

func NewStore() (*Store, error)

func NewStoreAt 

func NewStoreAt(dir string) (*Store, error)

func (*Store) Abandoned 

func (s *Store) Abandoned(state *State) bool

Abandoned reports whether a non-terminal task's worker is gone.

func (*Store) ActiveForWorkspace added in v1.20.0 

func (s *Store) ActiveForWorkspace(workspaceID, command string) ([]*State, error)

ActiveForWorkspace returns non-terminal tasks for a workspace, newest first.

func (*Store) CleanupCanceledWorkerTree added in v1.20.0 

func (s *Store) CleanupCanceledWorkerTree(ctx context.Context, id string) error

CleanupCanceledWorkerTree handles records that were marked canceled before their worker tree was terminated. A successful termination of an identityless tree is sufficient only while the worker lock proves it was still live.

func (*Store) CleanupExitedWorkerTree added in v1.20.0 

func (s *Store) CleanupExitedWorkerTree(id string) error

CleanupExitedWorkerTree tears down any descendants a dead worker left behind. Claiming the worker lock proves no worker is running, so a saved reference that still points at live processes belongs to a crashed worker's tree.

func (*Store) Create 

func (s *Store) Create(opts CreateOptions) (*Task, error)

func (*Store) Delete 

func (s *Store) Delete(id string, force bool) error

Delete cleans any unfinished terminal process tree before removing its record. It rejects a non-terminal task unless force is set.

func (*Store) ForWorkspace added in v1.20.0 

func (s *Store) ForWorkspace(workspaceID, command string) ([]*State, error)

ForWorkspace returns matching tasks, newest first, without changing state.

func (*Store) Get 

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

func (*Store) List 

func (s *Store) List() ([]*State, error)

List returns every known task, most recently started first.

func (*Store) Open 

func (s *Store) Open(id string) *Task

Open returns a handle without reading the task's state.

func (*Store) ReconcileState added in v1.20.0 

func (s *Store) ReconcileState(state *State) *State

ReconcileState marks a task after its worker exits without a result. A requested cancellation completes cleanup here; an abandoned task's tree is cleaned up by the next workspace stop or delete.

func (*Store) ReconcileTask added in v1.20.0 

func (s *Store) ReconcileTask(ctx context.Context, id string) (*State, error)

ReconcileTask cleans up a task whose worker exited before recording its result, then records it as canceled or abandoned.

func (*Store) WaitForWorkerObservation added in v1.20.0 

func (s *Store) WaitForWorkerObservation(
	ctx context.Context,
	id string,
) (WorkerObservation, error)

WaitForWorkerObservation waits until process metadata is published, the task becomes terminal, or its worker lock becomes available.

type Task 

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

Task is a handle to a single background task, bound to the Store it was created in. Report may be called from multiple goroutines; each call serializes its own read-modify-write of the state file.

func (*Task) BeginLaunch added in v1.20.0 

func (t *Task) BeginLaunch() error

func (*Task) Cancel 

func (t *Task) Cancel() error

Cancel terminates the worker before recording cancellation. A termination failure leaves the task retryable.

func (*Task) CancelContext added in v1.20.0 

func (t *Task) CancelContext(ctx context.Context) error

func (*Task) Fail 

func (t *Task) Fail(err error) error

Fail preserves an existing terminal state, so the error a canceled worker reports on its way out doesn't mask ErrCanceled as the reason it stopped.

func (*Task) FinishLaunch added in v1.20.0 

func (t *Task) FinishLaunch() error

func (*Task) HoldWorkerLock 

func (t *Task) HoldWorkerLock() error

HoldWorkerLock claims this task's worker lock while its worker is active. Release it only when startup aborts before work begins.

Returns an error if another process already holds the lock, since that means a worker for this task is already running.

func (*Task) ID 

func (t *Task) ID() string

func (*Task) ReleaseWorkerLock added in v1.20.0 

func (t *Task) ReleaseWorkerLock() error

ReleaseWorkerLock releases the worker claim when startup aborts before work begins.

func (*Task) Reporter 

func (t *Task) Reporter() status.Reporter

func (*Task) SetPID 

func (t *Task) SetPID(pid int) error

SetPID reads legacy task state and tests that publish a worker after launch.

func (*Task) SetProcess added in v1.20.0 

func (t *Task) SetProcess(ref command.ProcessRef) error

func (*Task) SetWorkspaceID 

func (t *Task) SetWorkspaceID(id string) error

SetWorkspaceID corrects the task's workspace label to the resolved ID, which may differ from whatever label it was created with (e.g. a raw source string guessed before workspace resolution ran). client.Status looks tasks up by this label, so it must end up accurate.

func (*Task) Succeed 

func (t *Task) Succeed(result *config.Result) error

Succeed is a no-op once the task is terminal, so a worker that finishes concurrently with a Cancel can't overwrite the canceled state with success.

type WorkerObservation added in v1.20.0 

type WorkerObservation struct {
	State      *State
	WorkerGone bool
}

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.