scheduler

package
v0.1.9 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package scheduler owns the durable per-session scheduled-task list and the interval contract the model-facing scheduler Tools share.

The store follows the plan store's private-file discipline: a private subdirectory of the session's own state directory, mode 0700 with a 0600 file, an atomic replace, a bounded size, and a versioned schema. The firing loop belongs to the Coding Runtime; this package owns only the record, the interval, and the store.

Index

Constants

View Source
const (

	// DefaultMaxBytes bounds the task file. The list is small and is always read
	// whole, so a damaged file cannot force an unbounded allocation.
	DefaultMaxBytes int64 = 1 << 20
)

The store's private-file contract, matching the plan store's discipline.

View Source
const MinimumIntervalSeconds int64 = 60

MinimumIntervalSeconds is the floor every parsed interval is raised to.

Variables

View Source
var (
	// ErrInvalid identifies a refused scheduler request.
	ErrInvalid = errors.New("coding scheduler: invalid request")
	// ErrUnsafe identifies a filesystem object or record that violates the
	// private-store contract.
	ErrUnsafe = errors.New("coding scheduler: unsafe scheduler store")
	// ErrUnsupported means the platform cannot provide the required guarantees.
	ErrUnsupported = errors.New("coding scheduler: unsupported platform")
	// ErrTaskNotFound means no scheduled task carries the requested id.
	ErrTaskNotFound = errors.New("coding scheduler: no scheduled task with that id")
)
View Source
var ErrInvalidInterval = errors.New("coding scheduler: invalid interval")

ErrInvalidInterval identifies an interval string this package refuses.

Functions

func IntervalHuman

func IntervalHuman(seconds int64) string

IntervalHuman renders seconds as the reference's human form: "every 5 minutes", "every 1 hour", "every 2 days", "every 45 seconds".

func NextFireAfter

func NextFireAfter(next time.Time, interval time.Duration, now time.Time) time.Time

NextFireAfter returns the first scheduled time strictly after now, advancing from the task's own next fire so the schedule keeps its phase. A next fire already in the past is skipped forward to the next future occurrence rather than replayed, so an overdue task fires once instead of once per missed interval.

func ParseInterval

func ParseInterval(value string) (int64, error)

ParseInterval parses an interval of the form "<digits><s|m|h|d>" into seconds, tolerating surrounding whitespace. An empty value, a zero value, an unknown suffix, or a product that overflows is refused; a value below the 60-second floor is raised to it.

Types

type CreateRequest

type CreateRequest struct {
	Prompt          string
	IntervalSeconds int64
	Recurring       bool
	Durable         bool
	FireImmediately bool
}

CreateRequest is one task to add.

type Options

type Options struct {
	// Now returns the current time; nil uses time.Now.
	Now func() time.Time
	// After returns a channel that receives one value once the duration
	// elapses; nil uses time.After. It is the loop's timer seam, so a test can
	// advance time and observe a fire instead of waiting an interval.
	After func(time.Duration) <-chan time.Time
	// MaxBytes bounds the task file; zero uses DefaultMaxBytes.
	MaxBytes int64
}

Options configure one session's scheduler store and its firing loop.

type Store

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

Store owns one session's durable scheduled-task list. It is the single owner: the Tools, the firing loop, and the surfaces all read and write it, and it decides what a restart keeps — a durable task is reloaded, a session-only one is dropped.

func NewStoreAt

func NewStoreAt(directory, sessionID string, options Options) (*Store, error)

NewStoreAt opens (creating when needed) the private scheduler directory under the session's own state directory. It does not read the task file; call Load to reload the durable tasks.

func (*Store) Advance

func (s *Store) Advance(ctx context.Context, id string, nextFireAt time.Time) error

Advance moves one task's next fire without recording a child, for a fire that could not start one. The task stays scheduled and nothing is reported.

func (*Store) Create

func (s *Store) Create(ctx context.Context, request CreateRequest) (Task, error)

Create adds one task and returns it. A fire_immediately task is due at once; every other task waits one interval.

func (*Store) Delete

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

Delete removes one task. An unknown id reports false rather than an error.

func (*Store) Dir

func (s *Store) Dir() string

Dir returns the private scheduler directory.

func (*Store) List

func (s *Store) List(ctx context.Context) ([]Task, error)

List returns the tasks in creation order.

func (*Store) Load

func (s *Store) Load(ctx context.Context) error

Load reads the durable tasks and drops every session-only task, so a restart keeps only what was marked durable. A missing file is an empty list.

func (*Store) Now

func (s *Store) Now() time.Time

Now returns the store's current time, so the firing loop and the Tools share one clock.

func (*Store) RecordFire

func (s *Store) RecordFire(
	ctx context.Context,
	id string,
	childID string,
	firedAt time.Time,
	nextFireAt time.Time,
) (Task, error)

RecordFire records the child one fire started and advances the schedule in the same durable write. A task that fires is removed when it is not recurring, and the removal is durable before the fire is reported, so a restart cannot fire it twice.

func (*Store) SessionID

func (s *Store) SessionID() string

SessionID returns the owning session identity.

func (*Store) Update

func (s *Store) Update(ctx context.Context, id string, patch UpdateRequest) (Task, error)

Update patches one task in place: a given field replaces the stored one and an omitted field stays. An interval change re-anchors the schedule from the task's last fire so the phase survives, and an unknown id is refused.

type Task

type Task struct {
	ID           string    `json:"id"`
	Prompt       string    `json:"prompt"`
	IntervalSecs int64     `json:"interval_seconds"`
	Recurring    bool      `json:"recurring"`
	Durable      bool      `json:"durable"`
	CreatedAt    time.Time `json:"created_at"`
	// LastFiredAt is zero until the first fire.
	LastFiredAt time.Time `json:"last_fired_at,omitzero"`
	// NextFireAt is the authoritative schedule. A fire advances it from its own
	// previous value, so the phase survives a late or a skipped fire.
	NextFireAt time.Time `json:"next_fire_at"`
	// LastChildID is the child the task's last fire started. The next fire is
	// skipped while that child still runs.
	LastChildID string `json:"last_child_id,omitempty"`
}

Task is one durable scheduled task. Every task pips records is recurring: a scheduled task keeps firing until it is deleted.

func (Task) Interval

func (t Task) Interval() time.Duration

Interval returns the task's interval as a duration.

type UpdateRequest

type UpdateRequest struct {
	Prompt          *string
	IntervalSeconds *int64
}

UpdateRequest patches one task in place. A nil field is left unchanged.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL