scheduler

type EmptyRequest struct{}

type Job interface {
	// Execute performs the job's work using the provided context.
	// Return error to mark execution as failed (will be logged and recorded in metrics per FR-020).
	// Panic will be recovered, logged with stack trace, and marked as failed per FR-021.
	// Jobs SHOULD respect context cancellation (check ctx.Done()) for graceful shutdown per FR-024.
	Execute(ctx JobContext) error
}

type JobContext interface {
	context.Context // Embed stdlib context for cancellation, deadlines, values, and trace context

	// JobID returns the unique identifier for this job (as registered via JobRegistrar)
	JobID() string

	// TriggerType returns how this job was triggered: "scheduled" or "manual"
	// "scheduled" = automatic execution based on schedule
	// "manual" = triggered via POST /_sys/job/:jobId
	TriggerType() string

	// Logger returns the framework logger with job-specific fields pre-populated
	// (jobID, trigger type). Use this for all job logging per FR-020.
	Logger() logger.Logger

	// DB returns the database interface (may be nil if not configured in ModuleDeps)
	DB() types.Interface

	// Messaging returns the messaging client (may be nil if not configured in ModuleDeps)
	Messaging() messaging.Client

	// Config returns the application configuration
	Config() *config.Config
}

type JobIDParam struct {
	JobID string `param:"jobId" validate:"required"`
}

type JobListResponse struct {
	Data []*JobMetadata         `json:"data"`
	Meta map[string]interface{} `json:"meta"`
}

type JobMetadata struct {
	// JobID is the unique identifier provided during registration
	JobID string `json:"jobId"`

	// ScheduleType identifies the scheduling pattern (fixed-rate, daily, weekly, hourly, monthly)
	ScheduleType string `json:"scheduleType"`

	// CronExpression is a cron-style representation of the schedule (e.g., "0 3 * * *" for daily at 3 AM)
	// Generated from ScheduleConfiguration per data-model.md
	CronExpression string `json:"cronExpression"`

	// HumanReadable is a user-friendly description (e.g., "Every Monday at 2:00 AM", "Every 30 minutes")
	HumanReadable string `json:"humanReadable"`

	// NextExecutionTime is when the job will execute next (nil if not yet scheduled)
	NextExecutionTime *time.Time `json:"nextExecutionTime,omitempty"`

	// LastExecutionTime is when the job last executed (nil if never run)
	LastExecutionTime *time.Time `json:"lastExecutionTime,omitempty"`

	// LastExecutionStatus is the status of the last execution: "success" or "failure" (nil if never run)
	// Note: skipped triggers do not update last execution status.
	LastExecutionStatus string `json:"lastExecutionStatus,omitempty"`

	// TotalExecutions is the total number of times the job has been triggered (scheduled + manual)
	TotalExecutions int64 `json:"totalExecutions"`

	// SuccessCount is the number of executions that completed without error
	SuccessCount int64 `json:"successCount"`

	// FailureCount is the number of executions that returned error or panicked
	FailureCount int64 `json:"failureCount"`

	// SkippedCount is the number of triggers skipped due to already-running instance (overlapping prevention per FR-026)
	SkippedCount int64 `json:"skippedCount"`
	// contains filtered or unexported fields
}

type JobTriggerData struct {
	JobID   string `json:"jobId"`
	Trigger string `json:"trigger"`
	Message string `json:"message"`
}

type JobTriggerResponse struct {
	Data JobTriggerData         `json:"data"`
	Meta map[string]interface{} `json:"meta"`
}

type ScheduleConfiguration struct {
	Type ScheduleType

	// FixedRate fields
	Interval time.Duration // Used when Type == ScheduleTypeFixedRate

	// Time-based fields (daily, weekly, monthly, hourly)
	Hour   int // 0-23 (used for daily, weekly, monthly)
	Minute int // 0-59 (used for all time-based schedules)

	// WeeklyAt field
	DayOfWeek time.Weekday // Sunday-Saturday

	// MonthlyAt field
	DayOfMonth int // 1-31

	// Timezone (nil = system local time per ASSUME-001)
	// For MVP, this is always nil (local time).
	// Future enhancement: allow explicit timezone specification.
	Timezone *time.Location
}

type ScheduleType string

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

type ValidationError struct {
	Field   string // The field that failed validation (e.g., "hour", "minute", "interval")
	Message string // Description of what's wrong (e.g., "must be 0-23")
	Action  string // Optional: Actionable guidance (e.g., "Choose a value between 0 and 23")
	Err     error  // Optional: Wrapped sentinel error for errors.Is checking
}