cron

type ConcurrencyPolicy string

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

type DefaultScheduleProvider interface {
	// DefaultSchedule returns the schedule to seed.
	DefaultSchedule() ScheduleSpec
}

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

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

type Execution struct {
	// RunID is the journal record's identifier, for run-scoped correlation.
	// A Recover re-fire is a fresh run with a fresh RunID.
	RunID string
	// ScheduleID and ScheduleName identify the schedule that fired.
	ScheduleID   string
	ScheduleName string
	// JobName is the handler's own registered name.
	JobName string
	// ScheduledAt is the logical fire time; a catch-up fire executes later
	// than it.
	ScheduledAt time.Time
	// Params is the schedule's params column, verbatim.
	Params json.RawMessage
}

type Job interface {
	// ID returns the job's unique identifier as a string.
	ID() string
	// LastRun returns the time when the job was last executed.
	LastRun() (time.Time, error)
	// Name returns the human-readable name assigned to the job.
	Name() string
	// NextRun returns the time when the job is next scheduled to run.
	NextRun() (time.Time, error)
	// NextRuns returns the specified number of future scheduled run times.
	NextRuns(count int) ([]time.Time, error)
	// RunNow executes the job immediately without affecting its regular schedule.
	// This respects all job and scheduler limits and may affect future scheduling
	// if the job has run limits configured.
	RunNow() error
	// Tags returns the list of tags associated with the job for grouping and filtering.
	Tags() []string
}

type JobDefinition interface {
	// contains filtered or unexported methods
}

type JobDescriptorOption func(*jobDescriptor)

type JobHandler interface {
	// Name uniquely identifies the job.
	Name() string
	// Execute runs one fire. The context carries cancellation (graceful
	// shutdown, per-run timeout); a returned error journals the run as
	// failed.
	Execute(ctx context.Context, execution Execution) error
}

type JobHandlerOption func(*jobHandlerConfig)

type MisfirePolicy string

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

type Run struct {
	orm.BaseModel `bun:"table:crn_run,alias:cr"`
	orm.CreationAuditedModel

	ScheduleID   string `json:"scheduleId" bun:"schedule_id"`
	ScheduleName string `json:"scheduleName" bun:"schedule_name"`
	JobName      string `json:"jobName" bun:"job_name"`

	// ScheduledAtUnixMs is the logical fire time; a catch-up fire starts later
	// than it. It is deliberately not unique: manual and recovery fires may
	// legitimately share one instant.
	ScheduledAtUnixMs int64 `json:"scheduledAtUnixMs" bun:"scheduled_at_unix_ms"`
	ClaimedAtUnixMs   int64 `json:"claimedAtUnixMs" bun:"claimed_at_unix_ms"`

	Status RunStatus `json:"status" bun:"status"`

	// NodeID identifies the executing node; empty on rows that never
	// executed (missed, skipped).
	NodeID string `json:"nodeId" bun:"node_id"`

	StartedAtUnixMs  *int64 `json:"startedAtUnixMs,omitempty" bun:"started_at_unix_ms"`
	FinishedAtUnixMs *int64 `json:"finishedAtUnixMs,omitempty" bun:"finished_at_unix_ms"`
	DurationMs       int64  `json:"durationMs" bun:"duration_ms"`

	// HeartbeatAtUnixMs is the executor's liveness signal, renewed while the
	// run executes; a stale heartbeat turns the run abandoned.
	HeartbeatAtUnixMs *int64 `json:"heartbeatAtUnixMs,omitempty" bun:"heartbeat_at_unix_ms"`

	// Error is the failure message, truncated; empty on success.
	Error string `json:"error,omitempty" bun:"error"`

	// MissedCount is the number of occurrences a missed row covers.
	MissedCount int `json:"missedCount,omitempty" bun:"missed_count"`
}

type RunAbandonedEvent struct {
	RunID        string `json:"runId"`
	ScheduleName string `json:"scheduleName"`
	JobName      string `json:"jobName"`
	// ScheduledAtUnixMs is the run's logical fire time.
	ScheduledAtUnixMs int64 `json:"scheduledAtUnixMs"`
	// NodeID identifies the node that stopped heartbeating.
	NodeID string `json:"nodeId"`
}

type RunFailedEvent struct {
	RunID        string `json:"runId"`
	ScheduleName string `json:"scheduleName"`
	JobName      string `json:"jobName"`
	// ScheduledAtUnixMs is the run's logical fire time.
	ScheduledAtUnixMs int64 `json:"scheduledAtUnixMs"`
	// NodeID identifies the node that executed the run.
	NodeID string `json:"nodeId"`
	// Error is the journaled failure message.
	Error string `json:"error"`
}

type RunFilter struct {
	// ScheduleName matches runs of one schedule.
	ScheduleName string
	// JobName matches runs of one job.
	JobName string
	// Statuses matches any of the given statuses.
	Statuses []RunStatus
	// Since and Until bound the logical fire time (inclusive since,
	// exclusive until).
	Since *time.Time
	Until *time.Time
	// Limit caps the result; zero resolves to 100, the cap is 1000.
	Limit int
}

type RunStatus string

type Schedule struct {
	orm.BaseModel `bun:"table:crn_schedule,alias:cs"`
	orm.FullAuditedModel

	// Name uniquely identifies the schedule and is the management key.
	Name string `json:"name" bun:"name"`
	// JobName references the JobHandler that executes the fires.
	JobName string `json:"jobName" bun:"job_name"`

	Kind         TriggerKind `json:"kind" bun:"kind"`
	Expr         string      `json:"expr" bun:"expr"`
	Timezone     string      `json:"timezone" bun:"timezone"`
	EveryMs      int64       `json:"everyMs" bun:"every_ms"`
	FireAtUnixMs *int64      `json:"fireAtUnixMs,omitempty" bun:"fire_at_unix_ms"`

	// StartsAtUnixMs and EndsAtUnixMs bound the fire window; either may be nil.
	// StartsAtUnixMs also anchors the fixed-rate phase of interval triggers.
	StartsAtUnixMs *int64 `json:"startsAtUnixMs,omitempty" bun:"starts_at_unix_ms"`
	EndsAtUnixMs   *int64 `json:"endsAtUnixMs,omitempty" bun:"ends_at_unix_ms"`
	AnchorAtUnixMs int64  `json:"anchorAtUnixMs" bun:"anchor_at_unix_ms"`

	// Params is delivered verbatim to the handler on every run.
	Params json.RawMessage `json:"params,omitempty" bun:"params,type:jsonb,nullzero"`

	MisfirePolicy     MisfirePolicy     `json:"misfirePolicy" bun:"misfire_policy"`
	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy" bun:"concurrency_policy"`

	// Recover re-fires a run that did not complete: abandoned mid-execution
	// (its node stopped heartbeating) or canceled by graceful shutdown.
	// Recovery makes delivery at-least-once; the handler must be idempotent.
	//
	// The re-fire is immediate and unlimited: there is no backoff and no
	// attempt ceiling, so a job that reliably kills the node executing it
	// produces a cluster-wide retry loop. Enable it for work whose failure
	// mode is the node, not the job.
	Recover bool `json:"recover" bun:"recover"`

	// TimeoutMs bounds one run; zero inherits vef.cron.store.run_timeout.
	TimeoutMs int64 `json:"timeoutMs" bun:"timeout_ms"`

	// IsEnabled is operator-owned: Pause clears it, Resume restores it. The
	// engine only claims enabled schedules.
	IsEnabled bool `json:"isEnabled" bun:"is_enabled"`

	// NextFireAtUnixMs is the next due fire the engine will claim; nil when the
	// trigger yields no further occurrence. Pausing preserves the cursor
	// rather than clearing it — claiming filters on IsEnabled anyway, and
	// keeping it is what lets Resume hand the paused gap to the misfire
	// policy instead of silently dropping it.
	NextFireAtUnixMs *int64 `json:"nextFireAtUnixMs,omitempty" bun:"next_fire_at_unix_ms"`
	// LastFireAtUnixMs records the most recent claimed fire's logical time —
	// an occurrence that produced a run, including one journaled as skipped
	// because a previous run was still executing. Occurrences accounted as
	// missed (the misfire gap) never advance it, so a schedule idle through
	// downtime keeps the last time it actually reached the journal as a fire.
	LastFireAtUnixMs *int64 `json:"lastFireAtUnixMs,omitempty" bun:"last_fire_at_unix_ms"`
}

type ScheduleFilter struct {
	// JobName matches schedules of one job.
	JobName string
	// Enabled matches by enablement when non-nil.
	Enabled *bool
}

type ScheduleManager interface {
	// Create validates and persists a new schedule. The trigger must be
	// structurally sound and the job name registered on this node; a taken
	// name fails with ErrScheduleExists.
	Create(ctx context.Context, spec ScheduleSpec) (*Schedule, error)
	// Update reshapes the named schedule to the spec — including a rename
	// when the spec carries a different, untaken name. Trigger or window
	// changes recompute the next fire.
	Update(ctx context.Context, name string, spec ScheduleSpec) (*Schedule, error)
	// Delete removes the schedule. Journaled runs are kept — they carry the
	// schedule and job names denormalized.
	Delete(ctx context.Context, name string) error
	// Pause stops fire claiming until Resume; running fires are unaffected.
	Pause(ctx context.Context, name string) error
	// Resume re-enables the schedule. Occurrences missed while paused are
	// handled by the schedule's misfire policy: MisfireFireNow runs one
	// catch-up immediately, MisfireSkip waits for the next regular fire.
	Resume(ctx context.Context, name string) error
	// TriggerNow persists one independent immediate fire request (single node,
	// journaled, concurrency policy respected) without moving the regular
	// trigger cursor. A paused schedule fails with ErrScheduleDisabled.
	TriggerNow(ctx context.Context, name string) error
	// Get returns the named schedule, or ErrScheduleNotFound.
	Get(ctx context.Context, name string) (*Schedule, error)
	// List returns schedules matching the filter, ordered by name.
	List(ctx context.Context, filter ScheduleFilter) ([]Schedule, error)
	// ListRuns returns journal records matching the filter, newest first.
	ListRuns(ctx context.Context, filter RunFilter) ([]Run, error)
}

type ScheduleSpec struct {
	// Name uniquely identifies the schedule; on a seeded default schedule it
	// falls back to the job name.
	Name string `json:"name"`
	// JobName references the registered JobHandler to execute.
	JobName string `json:"jobName"`
	// Trigger declares when the schedule fires.
	Trigger TriggerSpec `json:"trigger"`
	// Params is JSON-marshaled and delivered to the handler on every run;
	// json.RawMessage passes through verbatim.
	Params any `json:"params,omitempty"`
	// StartsAt and EndsAt bound the fire window; either may be nil.
	StartsAt *time.Time `json:"startsAt,omitempty"`
	EndsAt   *time.Time `json:"endsAt,omitempty"`

	MisfirePolicy     MisfirePolicy     `json:"misfirePolicy,omitempty"`
	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`

	// Recover re-fires abandoned runs; see Schedule.Recover.
	Recover bool `json:"recover,omitempty"`
	// Timeout bounds one run and must be an exact whole-millisecond duration;
	// zero inherits vef.cron.store.run_timeout.
	Timeout time.Duration `json:"timeout,omitempty"`
	// Enabled sets the initial (or updated) enablement; nil means true.
	Enabled *bool `json:"enabled,omitempty"`
}

type Scheduler interface {
	// Jobs returns all jobs currently registered with the scheduler.
	Jobs() []Job
	// NewJob creates and registers a new job with the scheduler.
	// The job will be scheduled according to its definition when the scheduler is running.
	// If the task function accepts a context.Context as its first parameter,
	// the scheduler will provide cancellation support for graceful shutdown.
	NewJob(definition JobDefinition) (Job, error)
	// RemoveByTags removes all jobs that have any of the specified tags.
	RemoveByTags(tags ...string)
	// RemoveJob removes the job with the specified unique identifier.
	RemoveJob(id string) error
	// Start begins scheduling and executing jobs according to their definitions.
	// Jobs added to a running scheduler are scheduled immediately. This method is non-blocking.
	Start()
	// StopJobs stops the execution of all jobs without removing them from the scheduler.
	// Jobs can be restarted by calling Start() again.
	StopJobs() error
	// Update replaces an existing job's definition while preserving its unique identifier.
	// This allows for dynamic job reconfiguration without losing job history.
	Update(id string, definition JobDefinition) (Job, error)
	// JobsWaitingInQueue returns the number of jobs waiting in the execution queue.
	// This is only relevant when using LimitModeWait; otherwise it returns zero.
	JobsWaitingInQueue() int
}

type TriggerKind string

type TriggerSpec struct {
	// Kind selects the trigger semantics.
	Kind TriggerKind `json:"kind"`
	// Expr is the cron expression of a TriggerCron trigger; 5 or 6 fields
	// (leading seconds optional) and @-descriptors are accepted.
	Expr string `json:"expr,omitempty"`
	// Timezone is the IANA zone a TriggerCron expression is evaluated in;
	// empty resolves to DefaultTimezone.
	Timezone string `json:"timezone,omitempty"`
	// EveryMs is the fixed rate of a TriggerInterval trigger, in milliseconds.
	EveryMs int64 `json:"everyMs,omitempty"`
	// At is the single fire time of a TriggerOnce trigger.
	At *time.Time `json:"at,omitempty"`
}