Documentation
¶
Index ¶
- Variables
- func ValidateCron(expr string) error
- type AsyncConfig
- type DaemonConfig
- type Engine
- func (e *Engine) EvalSchedules()
- func (e *Engine) GetResult(id string) *TaskResult
- func (e *Engine) Healthz() bool
- func (e *Engine) RecentResults() []TaskResult
- func (e *Engine) RemoveResult(id string) bool
- func (e *Engine) Status() StatusResponse
- func (e *Engine) Submit(task Task) (string, error)
- func (e *Engine) SubmitDaemon(task Task, cfg DaemonConfig) (string, error)
- func (e *Engine) SubmitScheduled(task Task, sched ScheduleConfig) (string, error)
- type ScheduleConfig
- type StatusResponse
- type Task
- type TaskHandler
- type TaskResult
- type TaskStatus
- type TaskType
Constants ¶
This section is empty.
Variables ¶
var ErrBusy = errors.New("a task is already running")
ErrBusy is returned by Submit when a task is already running.
Functions ¶
func ValidateCron ¶
ValidateCron checks whether a cron expression is syntactically valid.
Types ¶
type AsyncConfig ¶ added in v0.0.17
type AsyncConfig struct {
Schedule *ScheduleConfig `json:"schedule,omitempty"`
Daemon *DaemonConfig `json:"daemon,omitempty"`
}
AsyncConfig describes asynchronous task execution. When set on a TaskResult the caller did not poll for completion — the engine owns the lifecycle. Exactly one field should be set.
type DaemonConfig ¶ added in v0.0.17
type DaemonConfig struct{}
DaemonConfig marks a task as long-running. The handler runs indefinitely; only an unrecoverable error produces a terminal status. The struct is intentionally minimal — future fields could include restart policy, health-check interval, etc.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine is the task executor. Immediate tasks are serialized through a channel with a TryLock gate. Scheduled tasks run in their own goroutines when their cron fires. Daemon tasks run indefinitely in dedicated goroutines. All three share the unified TaskResult model.
func NewEngine ¶
func NewEngine(ctx context.Context, handlers map[TaskType]TaskHandler) *Engine
NewEngine creates a new Engine and starts its worker loop. The engine runs until ctx is cancelled.
func (*Engine) EvalSchedules ¶
func (e *Engine) EvalSchedules()
EvalSchedules checks all scheduled tasks and fires any that are due. Scheduled tasks run in their own goroutines, bypassing the one-shot lock.
func (*Engine) GetResult ¶
func (e *Engine) GetResult(id string) *TaskResult
GetResult returns a task by ID (in-flight, completed, scheduled, or daemon), or nil.
func (*Engine) RecentResults ¶
func (e *Engine) RecentResults() []TaskResult
RecentResults returns the most recent task results (newest first), combining in-flight, completed one-shot results, scheduled tasks, and daemon tasks.
func (*Engine) RemoveResult ¶
RemoveResult removes a task by ID. For scheduled tasks this stops the schedule. For daemon tasks this cancels the goroutine's context. Returns true if found.
func (*Engine) Status ¶
func (e *Engine) Status() StatusResponse
Status returns the engine's current state.
func (*Engine) SubmitDaemon ¶ added in v0.0.17
func (e *Engine) SubmitDaemon(task Task, cfg DaemonConfig) (string, error)
SubmitDaemon starts a long-running daemon task in its own goroutine. The handler is expected to run indefinitely; a nil return is treated as unexpected completion and a non-nil return as a terminal failure. Daemon tasks bypass the one-shot lock.
func (*Engine) SubmitScheduled ¶
func (e *Engine) SubmitScheduled(task Task, sched ScheduleConfig) (string, error)
SubmitScheduled creates a scheduled task. Returns the task ID. Currently only cron schedules are supported; block-height scheduling is reserved for future use. The schedule is evaluated by EvalSchedules.
type ScheduleConfig ¶ added in v0.0.17
type ScheduleConfig struct {
Cron string `json:"cron,omitempty"`
BlockHeight *int64 `json:"blockHeight,omitempty"`
}
ScheduleConfig triggers a task on a recurring basis. Exactly one field should be set. Cron is supported today; BlockHeight is reserved for future use.
type StatusResponse ¶
type StatusResponse struct {
Status string `json:"status"`
}
StatusResponse is the shape returned by the status endpoint.
type TaskHandler ¶
TaskHandler executes a specific task type.
type TaskResult ¶
type TaskResult struct {
ID string `json:"id"`
Type string `json:"type"`
Status TaskStatus `json:"status"`
Params map[string]any `json:"params,omitempty"`
Async *AsyncConfig `json:"async,omitempty"`
Error string `json:"error,omitempty"`
SubmittedAt time.Time `json:"submittedAt"`
CompletedAt *time.Time `json:"completedAt,omitempty"`
NextRunAt *time.Time `json:"nextRunAt,omitempty"`
}
TaskResult records a task and its outcome. Immediate, scheduled, and daemon tasks share this model. The Async field indicates which async execution mode was used (nil = immediate one-shot).
type TaskStatus ¶ added in v0.0.15
type TaskStatus string
TaskStatus represents the lifecycle state of a task.
const ( TaskStatusRunning TaskStatus = "running" TaskStatusCompleted TaskStatus = "completed" TaskStatusFailed TaskStatus = "failed" )
type TaskType ¶
type TaskType string
TaskType identifies the kind of task to execute.
const ( TaskSnapshotRestore TaskType = "snapshot-restore" TaskDiscoverPeers TaskType = "discover-peers" TaskConfigPatch TaskType = "config-patch" TaskConfigApply TaskType = "config-apply" TaskConfigValidate TaskType = "config-validate" TaskConfigReload TaskType = "config-reload" TaskMarkReady TaskType = "mark-ready" TaskConfigureGenesis TaskType = "configure-genesis" TaskConfigureStateSync TaskType = "configure-state-sync" TaskSnapshotUpload TaskType = "snapshot-upload" TaskResultExport TaskType = "result-export" )
Source Files