Documentation
¶
Overview ¶
Package cron provides SQLite-backed scheduled task management for bc.
Cron jobs trigger agent prompts or shell commands on a 5-field cron schedule. The scheduler itself runs inside bcd; this package provides the storage layer and cron expression utilities used by both the CLI and the daemon.
Usage ¶
store, err := cron.Open("/path/to/workspace")
if err != nil {
return err
}
defer store.Close()
err = store.AddJob(ctx, &cron.Job{
Name: "daily-lint",
Schedule: "0 9 * * *",
AgentName: "qa-01",
Prompt: "Run make lint and report results",
Enabled: true,
})
Index ¶
- Constants
- func NextRun(expr string, from time.Time) (time.Time, error)
- func ValidateSchedule(expr string) error
- type Job
- type LogEntry
- type PostgresStore
- func (p *PostgresStore) AddJob(ctx context.Context, job *Job) error
- func (p *PostgresStore) Close() error
- func (p *PostgresStore) DeleteJob(ctx context.Context, name string) error
- func (p *PostgresStore) GetJob(ctx context.Context, name string) (*Job, error)
- func (p *PostgresStore) GetLogs(ctx context.Context, jobName string, last int) ([]*LogEntry, error)
- func (p *PostgresStore) InitSchema() error
- func (p *PostgresStore) ListJobs(ctx context.Context) ([]*Job, error)
- func (p *PostgresStore) RecordManualTrigger(ctx context.Context, name string) error
- func (p *PostgresStore) RecordRun(ctx context.Context, entry *LogEntry) error
- func (p *PostgresStore) SetEnabled(ctx context.Context, name string, enabled bool) error
- type Scheduler
- type Store
- func (s *Store) AddJob(ctx context.Context, job *Job) error
- func (s *Store) Close() error
- func (s *Store) DeleteJob(ctx context.Context, name string) error
- func (s *Store) GetJob(ctx context.Context, name string) (*Job, error)
- func (s *Store) GetLogs(ctx context.Context, jobName string, last int) ([]*LogEntry, error)
- func (s *Store) ListJobs(ctx context.Context) ([]*Job, error)
- func (s *Store) RecordManualTrigger(ctx context.Context, name string) error
- func (s *Store) RecordRun(ctx context.Context, entry *LogEntry) error
- func (s *Store) SetEnabled(ctx context.Context, name string, enabled bool) error
Constants ¶
const ( // DefaultPollInterval is how often the scheduler checks for due jobs. DefaultPollInterval = 30 * time.Second // DefaultJobTimeout is the maximum time a single job execution may take. DefaultJobTimeout = 5 * time.Minute )
Variables ¶
This section is empty.
Functions ¶
func NextRun ¶
NextRun returns the next time after `from` that matches the cron expression. Returns an error if the expression is invalid or no match is found within 4 years.
func ValidateSchedule ¶
ValidateSchedule validates a 5-field cron expression. Returns an error describing the problem, or nil if valid.
Types ¶
type Job ¶
type Job struct {
LastRun *time.Time `json:"last_run,omitempty"`
NextRun *time.Time `json:"next_run,omitempty"`
CreatedAt time.Time `json:"created_at"`
Name string `json:"name"`
Schedule string `json:"schedule"`
AgentName string `json:"agent_name,omitempty"`
Prompt string `json:"prompt,omitempty"`
Command string `json:"command,omitempty"`
RunCount int `json:"run_count"`
Enabled bool `json:"enabled"`
Running bool `json:"running"`
}
Job represents a scheduled cron task.
type LogEntry ¶
type LogEntry struct {
RunAt time.Time `json:"run_at"`
JobName string `json:"job_name"`
Status string `json:"status"` // success, failed, timeout
Output string `json:"output,omitempty"`
ID int64 `json:"id"`
DurationMS int64 `json:"duration_ms"`
CostUSD float64 `json:"cost_usd,omitempty"`
}
LogEntry records one execution of a cron job.
type PostgresStore ¶
type PostgresStore struct {
// contains filtered or unexported fields
}
PostgresStore provides Postgres-backed cron job storage.
func NewPostgresStore ¶
func NewPostgresStore(db *sql.DB) *PostgresStore
NewPostgresStore creates a PostgresStore from an existing *sql.DB connection.
func (*PostgresStore) AddJob ¶
func (p *PostgresStore) AddJob(ctx context.Context, job *Job) error
AddJob inserts a new cron job.
func (*PostgresStore) Close ¶
func (p *PostgresStore) Close() error
Close is a no-op — the shared DB is owned by the caller.
func (*PostgresStore) DeleteJob ¶
func (p *PostgresStore) DeleteJob(ctx context.Context, name string) error
DeleteJob removes a cron job and its logs by name.
func (*PostgresStore) InitSchema ¶
func (p *PostgresStore) InitSchema() error
InitSchema creates the cron tables in Postgres if they don't exist.
func (*PostgresStore) ListJobs ¶
func (p *PostgresStore) ListJobs(ctx context.Context) ([]*Job, error)
ListJobs returns all cron jobs ordered by name.
func (*PostgresStore) RecordManualTrigger ¶
func (p *PostgresStore) RecordManualTrigger(ctx context.Context, name string) error
RecordManualTrigger marks a job as manually triggered.
func (*PostgresStore) RecordRun ¶
func (p *PostgresStore) RecordRun(ctx context.Context, entry *LogEntry) error
RecordRun records a job execution result and updates run stats.
func (*PostgresStore) SetEnabled ¶
SetEnabled enables or disables a job. Recomputes next_run when enabling.
type Scheduler ¶
type Scheduler struct {
// contains filtered or unexported fields
}
Scheduler polls the cron store and executes due jobs in the background.
func NewScheduler ¶
NewScheduler creates a Scheduler that polls at DefaultPollInterval.
func NewSchedulerWithConfig ¶
func NewSchedulerWithConfig(store *Store, logDir string, pollIntervalSec, jobTimeoutSec int) *Scheduler
NewSchedulerWithConfig creates a Scheduler with configurable poll interval and job timeout. Zero values use defaults (30s poll, 5m timeout).
func (*Scheduler) LogFilePath ¶
LogFilePath returns the live log file path for a job.
func (*Scheduler) RunningJobs ¶
RunningJobs returns the names of all currently executing jobs.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a cron job store backed by SQLite or TimescaleDB (Postgres).
func Open ¶
Open opens the cron store using the shared workspace database. Returns an error if no shared database is available.
func OpenStore ¶
OpenStore opens the cron store using the shared workspace database. Uses the shared driver type to determine the backend (timescale or sqlite).
func (*Store) AddJob ¶
AddJob inserts a new cron job. Returns an error if the name already exists. Note: commands that kill the bcd process will terminate the cron scheduler itself. Use an external supervisor (systemd, launchd) for bcd restarts.
func (*Store) GetLogs ¶
GetLogs returns execution history for a job. If last > 0, limits to that many entries.
func (*Store) RecordManualTrigger ¶
RecordManualTrigger marks a job as manually triggered (updates last_run + next_run).
Source Files