<?php

namespace AIPT\Api\AutomationJobs\Interfaces;

use AIPT\Api\AutomationJobs\Models\AutomationJob;

/**
 * Job Scheduler Interface
 * 
 * Defines contract for job scheduling implementations
 * Following Interface Segregation and Dependency Inversion principles
 * 
 * @since 2.3.0
 */
interface JobSchedulerInterface {
    
    /**
     * Schedule a job for execution
     * 
     * @param AutomationJob $job Job to schedule
     * @return bool Success status
     * @throws \Exception On scheduling failure
     */
    public function scheduleJob(AutomationJob $job);
    
    /**
     * Unschedule a job
     * 
     * @param int $job_id Job ID to unschedule
     * @return bool Success status
     * @throws \Exception On unscheduling failure
     */
    public function unscheduleJob($job_id);
    
    /**
     * Reschedule a job with new configuration
     * 
     * @param AutomationJob $job Job to reschedule
     * @return bool Success status
     * @throws \Exception On rescheduling failure
     */
    public function rescheduleJob(AutomationJob $job);
    
    /**
     * Process pending jobs
     * 
     * @return int Number of jobs processed
     */
    public function processPendingJobs();
    
    /**
     * Monitor running jobs for timeouts and issues
     * 
     * @return int Number of jobs monitored
     */
    public function monitorRunningJobs();
    
    /**
     * Calculate next run time for a job
     * 
     * @param AutomationJob $job Job to calculate next run for
     * @return string|null Next run datetime or null if one-time job
     */
    public function calculateNextRun(AutomationJob $job);
    
    /**
     * Check if job should run now
     * 
     * @param AutomationJob $job Job to check
     * @return bool Whether job should run
     */
    public function shouldJobRun(AutomationJob $job);
    
    /**
     * Get jobs ready for execution
     * 
     * @param int $limit Maximum number of jobs to return
     * @return array Jobs ready for execution
     */
    public function getJobsReadyForExecution($limit = 10);
    
    /**
     * Handle job timeout
     * 
     * @param int $job_id Job ID that timed out
     * @return bool Success status
     */
    public function handleJobTimeout($job_id);
}
