domain

type Fn func(ctrl FnControl) error

type FnControl interface {
	// SaveData stores arbitrary key-value pairs generated during the execution of a job.
	// This data can later be accessed for monitoring, logging, or analysis.
	SaveData(data map[string]interface{})

	// GetData returns a copy of the job's current saved runtime data.
	//
	// This method allows the job to access the latest key-value pairs previously stored via SaveData.
	// It can be used inside the main function (Fn) or any lifecycle hook (OnStart, OnSuccess, etc.).
	//
	// Returns:
	//   - map[string]interface{}: A snapshot of the user-defined runtime data.
	GetData() map[string]interface{}

	// Context returns the job's execution context.
	// It is canceled when the job is stopped, times out, or the pool is shut down.
	Context() context.Context

	// PauseChan returns a channel that is used to signal when the job should pause.
	// The job implementation is expected to read from this channel and enter a paused state when needed.
	PauseChan() <-chan struct{}

	// ResumeChan returns a channel that signals when a paused job should resume execution.
	// The job should wait on this channel to continue processing after a pause.
	ResumeChan() <-chan struct{}
}

type Hook struct {
	// Fn is the function to be executed during the lifecycle stage.
	// It receives the current FnControl and an optional error for handling error in OnError hook (if applicable).
	// It should return an error if the hook fails.
	Fn func(ctrl FnControl, err error) error

	// IgnoreError determines whether hook execution errors should be ignored.
	// If true, the job will proceed even if the hook fails.
	// If false, the job will halt and treat the hook error as fatal.
	IgnoreError bool
}

type HookError struct {
	// OnStart captures errors raised by the OnStart hook.
	OnStart error

	// OnStop captures errors raised by the OnStop hook.
	OnStop error

	// OnError captures errors raised by the OnError hook,
	// which is typically executed after a failed job function.
	OnError error

	// OnSuccess captures errors raised by the OnSuccess hook,
	// which is called after the job function completes successfully.
	OnSuccess error

	// OnPause captures errors raised by the OnPause hook,
	// which is triggered when the job is paused manually.
	OnPause error

	// OnResume captures errors raised by the OnResume hook,
	// which is triggered when a paused job is resumed.
	OnResume error

	// Finally captures errors raised by the Finally hook,
	// which always runs after execution, regardless of outcome.
	Finally error
}

type Hooks struct {
	// OnStart is executed right before the job's main function (Fn) begins execution.
	// Returning an error from OnStart prevents the job from running.
	OnStart Hook

	// OnStop is executed when a running job receives a stop signal.
	// It allows for graceful termination, cleanup, or state preservation before stopping the job completely.
	OnStop Hook

	// OnError is executed whenever the job's main function (Fn) encounters an error.
	// This hook provides an opportunity for error handling, logging, notifications, or triggering recovery actions.
	OnError Hook

	// OnSuccess is executed immediately after successful completion of the job's main function (Fn).
	// If OnSuccess returns an error, the job's final status will reflect the failure of this hook.
	OnSuccess Hook

	// OnPause is triggered when a job transitions into a paused state.
	// It can be used for resource management, state tracking, or logging.
	// If OnPause returns an error, the job's final status will reflect the failure of this hook.
	OnPause Hook

	// OnResume is executed when a paused job is resumed.
	// It allows reinitializing resources or state restoration required for the continuation of job execution.
	// If OnResume returns an error, the job's final status will reflect the failure of this hook.
	OnResume Hook

	// Finally is always executed after job completion, regardless of success, error, or any interruptions.
	// Ideal for guaranteed cleanup operations, final resource releases, or logging outcomes.
	// If Finally returns an error, it overrides previous results and marks the job's final status as Error.
	Finally Hook
}

type Interval struct {
	// Time specifies the duration between consecutive executions of the job.
	// For example, an interval of 1 hour executes the job every hour.
	// If Time is set, CronExpr must be empty.
	Time time.Duration

	// CronExpr specifies a cron expression that defines precise scheduling times (e.g., "0 0 * * *" for daily execution at midnight).
	// Supports standard cron syntax with minute, hour, day-of-month, month, and day-of-week fields.
	// If CronExpr is set, Time must be zero.
	CronExpr string
}

type Job interface {
	// GetMetadata returns the job's configuration metadata.
	GetMetadata() JobDTO

	// SetTimeout sets the max allowed job execution time; 0 disables timeout tracking.
	SetTimeout(timeout time.Duration)

	// GetStatus returns the current execution status of the job.
	GetStatus() JobStatus

	// SetStatus forcefully sets the job's current status.
	SetStatus(status JobStatus)

	TrySetStatus(allowed []JobStatus, status JobStatus) bool
	// UpdateState partially updates the job's state with non-zero fields from the provided DTO.
	UpdateState(state StateDTO)

	GetState() *StateDTO

	// GetNextRun calculates and returns the next scheduled execution time for the job.
	GetNextRun() time.Time

	// ProcessStart marks the job's state as "Running", initializing execution metrics and metadata.
	ProcessStart()

	// ProcessRun monitors the job during execution, checking for timeout conditions.
	// Returns ErrJobTimeout if the job exceeds its configured timeout.
	ProcessRun() error

	// ProcessEnd finalizes the job state after execution completes, recording metrics and handling errors.
	ProcessEnd(status JobStatus, err error)

	// ProcessError performs retry logic and updates the job state in case of failure.
	ProcessError() error

	// CanExecute checks if the job meets conditions required to start execution immediately.
	// Returns an error indicating why execution is not allowed, or nil if eligible.
	CanExecute() error

	// Execute performs the job's main execution logic, handling internal lifecycle hooks and error handling.
	Execute() error

	// Stop forcibly stops job execution and updates its state accordingly.
	Stop() error

	// Pause attempts to pause job execution with a specified timeout.
	Pause(timeout time.Duration) error

	// Resume resumes execution of a paused job, if applicable.
	Resume(ctx context.Context) error

	// LockJob acquires exclusive execution access to the job if it is available.
	LockJob() bool

	// UnlockJob releases exclusive execution access to the job.
	UnlockJob()
}

type JobDTO struct {
	// ID is a required unique identifier for the job.
	ID string

	// Name is an optional human-readable label for the job.
	// If omitted, it defaults to the value of ID.
	Name string

	// Fn is the function that encapsulates the job's execution logic.
	// It receives a FnControl object that provides control over execution flow and data storage.
	Fn Fn

	// Interval specifies the time delay between consecutive executions.
	// If set to 0, the job runs only once.
	Interval Interval

	// Timeout defines the maximum duration allowed for a single execution of the job.
	// If exceeded, the job will be terminated.
	Timeout time.Duration

	// StartAt defines the earliest point in time the job is allowed to run.
	// Jobs scheduled before this timestamp will remain in Waiting state.
	StartAt time.Time

	// EndAt defines the latest point in time the job is allowed to run.
	// Jobs scheduled after this timestamp will be considered expired and marked as Stopped.
	EndAt time.Time

	// Retry specifies retry behavior in case of job execution failure.
	Retry Retry

	// Hooks defines callback functions triggered at key lifecycle events
	// such as OnStart, OnSuccess, OnError, OnStop, etc.
	Hooks Hooks
}

type JobStatus string

type Monitoring interface {
	// SaveMetrics stores execution metrics derived from a job's execution state (StateDTO).
	//
	// Implementations typically capture metrics like execution timestamps, duration,
	// final status, encountered errors, and user-defined runtime metadata.
	//
	// Parameters:
	//   - dto: StateDTO instance containing the job's execution details and metadata.
	SaveMetrics(dto StateDTO)

	// GetMetrics retrieves all stored execution metrics.
	//
	// Returns:
	//   - A map keyed by JobID, where each entry contains the StateDTO representing
	//     execution metrics for a specific job.
	GetMetrics() map[string]interface{}
}

type Pool struct {
	// IdleTimeout specifies the duration after which a job that remains idle
	// (not executed or scheduled for immediate execution) will be marked as inactive.
	// This helps optimize resource usage and prevents accumulation of stale tasks.
	IdleTimeout time.Duration

	// MaxWorkers sets the maximum number of concurrent workers allowed to execute jobs simultaneously.
	// Higher values can improve throughput for CPU-bound or I/O-bound tasks, but might consume more system resources.
	MaxWorkers int

	// CheckInterval defines how frequently the pool checks for jobs that are ready for execution or require status updates.
	// Short intervals result in more responsive job execution at the expense of slightly increased CPU utilization.
	CheckInterval time.Duration
}

type Retry struct {
	// Active specifies whether retrying is enabled for the job.
	Active bool

	// Count is the number of allowed retry attempts before marking the job as failed.
	// Each time a job fails, this counter decreases. When it reaches zero, the job stops retrying.
	Count int

	// ResetOnSuccess determines whether the retry counter should be reset after a successful execution.
	// If true, a successful execution resets the retry count to its initial value.
	ResetOnSuccess bool
}

type StateDTO struct {
	// JobID is the unique identifier of the job to which this state belongs.
	JobID string

	// StartAt is the timestamp marking when the job execution began.
	// It is zero if the job has not started yet.
	StartAt time.Time

	// EndAt is the timestamp marking when the job finished execution.
	// It is zero if the job is currently running or has not yet started.
	EndAt time.Time

	// Error captures errors encountered during job execution or in lifecycle hooks.
	// If no errors occurred, this field remains empty.
	Error StateError

	// Status indicates the current execution state of the job (e.g., Waiting, Running, Completed, Error).
	Status JobStatus

	// ExecutionTime is the duration in nanoseconds that the job took to complete.
	// It is zero if the job hasn't completed or hasn't started yet.
	ExecutionTime int64

	// Data holds user-defined key-value pairs collected during job execution.
	// This is commonly used for computed results, metrics, or side-channel information.
	Data map[string]interface{}

	// Success tracks how many times the job has completed successfully.
	Success int

	// Failure tracks how many times the job has failed.
	Failure int

	// NextRun indicates the estimated time of the next scheduled execution.
	// For one-time jobs, this will remain zero after execution.
	NextRun time.Time
}

type StateError struct {
	// JobError is the error returned by the main job function (Fn), if any.
	JobError error

	// HookError captures individual errors raised by lifecycle hooks.
	HookError
}