cron

package
v2.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// MinEveryInterval is the shortest interval a job may repeat at. Every run
	// of an agent-turn job is a model call, so a seconds-level schedule is a
	// cost and flooding risk rather than a feature.
	MinEveryInterval = time.Minute
	// MaxJobsPerChat bounds the jobs one chat (channel and recipient) may hold.
	MaxJobsPerChat = 50
	// MaxJobs bounds the whole store.
	MaxJobs = 500
	// DefaultJobTimeout bounds one run when no timeout is configured.
	DefaultJobTimeout = 10 * time.Minute
)

Variables

View Source 
var (
	// ErrJobNotFound is returned for an unknown job ID.
	ErrJobNotFound = errors.New("job not found")
	// ErrServiceStopped is returned by a service that was stopped: after a
	// reload its successor owns the store, and a late write would undo that
	// successor's changes.
	ErrServiceStopped = errors.New("cron service is stopped")
)

Functions

func DefaultStorePath 

func DefaultStorePath(home string) string

DefaultStorePath is where the cron store lives: <home>/state/cron/jobs.json, outside the workspace the agent's file tools can write.

func PauseJobTimeout 

func PauseJobTimeout(ctx context.Context) (resume func())

PauseJobTimeout stops counting the job timeout of the run ctx belongs to until the returned function is called: a run waiting for the owner's approval doesn't use up its time. Outside a job run it does nothing.

Types

type CronJob 

type CronJob struct {
	ID             string       `json:"id"`
	Name           string       `json:"name"`
	Enabled        bool         `json:"enabled"`
	Schedule       CronSchedule `json:"schedule"`
	Payload        CronPayload  `json:"payload"`
	State          CronJobState `json:"state"`
	CreatedAtMS    int64        `json:"createdAtMs"`
	UpdatedAtMS    int64        `json:"updatedAtMs"`
	DeleteAfterRun bool         `json:"deleteAfterRun"`
}

type CronJobState 

type CronJobState struct {
	NextRunAtMS *int64 `json:"nextRunAtMs,omitempty"`
	LastRunAtMS *int64 `json:"lastRunAtMs,omitempty"`
	LastStatus  string `json:"lastStatus,omitempty"`
	LastError   string `json:"lastError,omitempty"`
}

type CronPayload 

type CronPayload struct {
	Kind    string `json:"kind"`
	Message string `json:"message"`
	Command string `json:"command,omitempty"`
	Channel string `json:"channel,omitempty"`
	To      string `json:"to,omitempty"`
}

type CronSchedule 

type CronSchedule struct {
	Kind    string `json:"kind"`
	AtMS    *int64 `json:"atMs,omitempty"`
	EveryMS *int64 `json:"everyMs,omitempty"`
	Expr    string `json:"expr,omitempty"`
	TZ      string `json:"tz,omitempty"`
}

func (CronSchedule) Validate 

func (s CronSchedule) Validate() error

Validate reports why a schedule can't be used: an unknown kind, a missing or past time, an interval below MinEveryInterval, an invalid cron expression or time zone, or a cron expression that fires more than once a minute.

type CronService 

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

func NewCronService 

func NewCronService(storePath string, onJob JobHandler, opts ...Option) *CronService

func OpenCronService 

func OpenCronService(storePath string, onJob JobHandler, opts ...Option) (*CronService, error)

OpenCronService is NewCronService that reports a store it can't load.

func (*CronService) AddJob 

func (cs *CronService) AddJob(
	name string,
	schedule CronSchedule,
	message string,
	channel, to string,
	opts ...JobOption,
) (*CronJob, error)

func (*CronService) DeleteJob 

func (cs *CronService) DeleteJob(jobID string) (bool, error)

DeleteJob is RemoveJob that reports why nothing was removed.

func (*CronService) EnableJob 

func (cs *CronService) EnableJob(jobID string, enabled bool) *CronJob

func (*CronService) GetJob 

func (cs *CronService) GetJob(jobID string) (*CronJob, bool)

func (*CronService) ListJobs 

func (cs *CronService) ListJobs(includeDisabled bool) []CronJob

func (*CronService) Load 

func (cs *CronService) Load() error

func (*CronService) LoadErr 

func (cs *CronService) LoadErr() error

LoadErr reports why the store couldn't be loaded, or nil.

func (*CronService) RemoveJob 

func (cs *CronService) RemoveJob(jobID string) bool

func (*CronService) SetJobEnabled 

func (cs *CronService) SetJobEnabled(jobID string, enabled bool) (*CronJob, error)

SetJobEnabled is EnableJob that reports failures: an unknown job, a one-time job whose time has passed, or a store that can't be written.

func (*CronService) SetOnJob 

func (cs *CronService) SetOnJob(handler JobHandler)

func (*CronService) SetOnJobContext 

func (cs *CronService) SetOnJobContext(handler JobHandlerContext)

SetOnJobContext sets a handler that receives the job's context; it takes precedence over SetOnJob.

func (*CronService) Start 

func (cs *CronService) Start() error

func (*CronService) Status 

func (cs *CronService) Status() map[string]any

func (*CronService) Stop 

func (cs *CronService) Stop()

Stop ends scheduling and cancels running jobs. A stopped service never writes the store again.

func (*CronService) UpdateJob 

func (cs *CronService) UpdateJob(job *CronJob) error

type CronStore 

type CronStore struct {
	Version int       `json:"version"`
	Jobs    []CronJob `json:"jobs"`
}

type JobHandler 

type JobHandler func(job *CronJob) (string, error)

type JobHandlerContext 

type JobHandlerContext func(ctx context.Context, job *CronJob) (string, error)

JobHandlerContext runs a job with a context that carries the job timeout and is cancelled when the service stops.

type JobOption 

type JobOption func(*CronPayload)

JobOption sets an optional part of a job AddJob creates.

func WithCommand 

func WithCommand(command string) JobOption

WithCommand makes the job run command rather than an agent turn. The job is written with it at once, so it never runs, nor stays, without it.

type Option 

type Option func(*CronService)

Option configures a CronService.

func WithJobTimeout 

func WithJobTimeout(d time.Duration) Option

WithJobTimeout bounds one job run; zero or less keeps DefaultJobTimeout.

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.