CoreFiles by mySites.guru
Task.php589 lines, 14,975 bytes, from Joomla_4.1.1-rc2-Release_Candidate-Full_Package.zip
Raw History Compare with 4.1.1-rc1
md5
264fae53444d662fb937049287037e2b
sha1
eb39e61df3c2ec61b633a6a01dfe04a3a64dd480
sha256
f973bb3d61f8f50f257fa8c6d75adbf1ab5f01181f367944f4b21bf2a4db5f91
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589
<?php
/**
 * @package     Joomla.Administrator
 * @subpackage  com_scheduler
 *
 * @copyright   (C) 2021 Open Source Matters, Inc. <https://www.joomla.org>
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */

namespace Joomla\Component\Scheduler\Administrator\Task;

// Restrict direct access
\defined('_JEXEC') or die;

use Joomla\CMS\Application\CMSApplication;
use Joomla\CMS\Component\ComponentHelper;
use Joomla\CMS\Event\AbstractEvent;
use Joomla\CMS\Factory;
use Joomla\CMS\Language\Text;
use Joomla\CMS\Log\Log;
use Joomla\CMS\Plugin\PluginHelper;
use Joomla\Component\Scheduler\Administrator\Event\ExecuteTaskEvent;
use Joomla\Component\Scheduler\Administrator\Helper\ExecRuleHelper;
use Joomla\Component\Scheduler\Administrator\Helper\SchedulerHelper;
use Joomla\Component\Scheduler\Administrator\Scheduler\Scheduler;
use Joomla\Component\Scheduler\Administrator\Table\TaskTable;
use Joomla\Database\DatabaseDriver;
use Joomla\Database\DatabaseInterface;
use Joomla\Database\ParameterType;
use Joomla\Registry\Registry;
use Joomla\Utilities\ArrayHelper;
use Psr\Log\InvalidArgumentException;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerAwareTrait;

/**
 * The Task class defines methods for the execution, logging and
 * related properties of Tasks as supported by `com_scheduler`,
 * a Task Scheduling component.
 *
 * @since 4.1.0
 */
class Task implements LoggerAwareInterface
{
	use LoggerAwareTrait;

	/**
	 * Enumerated state for enabled tasks.
	 *
	 * @since 4.1.0
	 */
	const STATE_ENABLED = 1;

	/**
	 * Enumerated state for disabled tasks.
	 *
	 * @since 4.1.0
	 */
	public const STATE_DISABLED = 0;

	/**
	 * Enumerated state for trashed tasks.
	 *
	 * @since 4.1.0
	 */
	public const STATE_TRASHED = -2;

	/**
	 * Map state enumerations to logical language adjectives.
	 *
	 * @since 4.1.0
	 */
	public const STATE_MAP = [
		self::STATE_TRASHED  => 'trashed',
		self::STATE_DISABLED => 'disabled',
		self::STATE_ENABLED  => 'enabled',
	];

	/**
	 * The task snapshot
	 *
	 * @var   array
	 * @since 4.1.0
	 */
	protected $snapshot = [];

	/**
	 * @var  Registry
	 * @since 4.1.0
	 */
	protected $taskRegistry;

	/**
	 * @var  string
	 * @since  4.1.0
	 */
	public $logCategory;

	/**
	 * @var  CMSApplication
	 * @since  4.1.0
	 */
	protected $app;

	/**
	 * @var  DatabaseInterface
	 * @since  4.1.0
	 */
	protected $db;

	/**
	 * Maps task exit codes to events which should be dispatched when the task finishes.
	 * 'NA' maps to the event for general task failures.
	 *
	 * @var  string[]
	 * @since  4.1.0
	 */
	protected const EVENTS_MAP = [
		Status::OK          => 'onTaskExecuteSuccess',
		Status::NO_ROUTINE  => 'onTaskRoutineNotFound',
		Status::WILL_RESUME => 'onTaskRoutineWillResume',
		'NA'                => 'onTaskExecuteFailure',
	];

	/**
	 * Constructor for {@see Task}.
	 *
	 * @param   object  $record  A task from {@see TaskTable}.
	 *
	 * @since 4.1.0
	 * @throws \Exception
	 */
	public function __construct(object $record)
	{
		// Workaround because Registry dumps private properties otherwise.
		$taskOption     = $record->taskOption;
		$record->params = json_decode($record->params, true);

		$this->taskRegistry = new Registry($record);

		$this->set('taskOption', $taskOption);
		$this->app = Factory::getApplication();
		$this->db  = Factory::getContainer()->get(DatabaseDriver::class);
		$this->setLogger(Log::createDelegatedLogger());
		$this->logCategory = 'task' . $this->get('id');

		if ($this->get('params.individual_log'))
		{
			$logFile = $this->get('params.log_file') ?? 'task_' . $this->get('id') . '.log.php';

			$options['text_entry_format'] = '{DATE}	{TIME}	{PRIORITY}	{MESSAGE}';
			$options['text_file']         = $logFile;
			Log::addLogger($options, Log::ALL, [$this->logCategory]);
		}
	}

	/**
	 * Get the task as a data object that can be stored back in the database.
	 * ! This method should be removed or changed as part of a better API implementation for the driver.
	 *
	 * @return object
	 *
	 * @since 4.1.0
	 */
	public function getRecord(): object
	{
		// ! Probably, an array instead
		$recObject = $this->taskRegistry->toObject();

		$recObject->cron_rules = (array) $recObject->cron_rules;

		return $recObject;
	}

	/**
	 * Execute the task.
	 *
	 * @return boolean  True if success
	 *
	 * @since 4.1.0
	 * @throws \Exception
	 */
	public function run(): bool
	{
		/**
		 * We try to acquire the lock here, only if we don't already have one.
		 * We do this, so we can support two ways of running tasks:
		 *   1. Directly through {@see Scheduler}, which optimises acquiring a lock while fetching from the task queue.
		 *   2. Running a task without a pre-acquired lock.
		 * ! This needs some more thought, for whether it should be allowed or if the single-query optimisation
		 *   should be used everywhere, although it doesn't make sense in the context of fetching
		 *   a task when it doesn't need to be run. This might be solved if we force a re-fetch
		 *   with the lock or do it here ourselves (using acquireLock as a proxy to the model's
		 *   getter).
		 */
		if ($this->get('locked') === null)
		{
			$this->acquireLock();
		}

		// Exit early if task routine is not available
		if (!SchedulerHelper::getTaskOptions()->findOption($this->get('type')))
		{
			$this->snapshot['status'] = Status::NO_ROUTINE;
			$this->skipExecution();
			$this->dispatchExitEvent();

			return $this->isSuccess();
		}

		$this->snapshot['status']      = Status::RUNNING;
		$this->snapshot['taskStart']   = $this->snapshot['taskStart'] ?? microtime(true);
		$this->snapshot['netDuration'] = 0;

		/** @var ExecuteTaskEvent $event */
		$event = AbstractEvent::create(
			'onExecuteTask',
			[
				'eventClass'      => ExecuteTaskEvent::class,
				'subject'         => $this,
				'routineId'       => $this->get('type'),
				'langConstPrefix' => $this->get('taskOption')->langConstPrefix,
				'params'          => $this->get('params'),
			]
		);

		PluginHelper::importPlugin('task');

		try
		{
			$this->app->getDispatcher()->dispatch('onExecuteTask', $event);
		}
		catch (\Exception $e)
		{
			// Suppress the exception for now, we'll throw it again once it's safe
			$this->log(Text::sprintf('COM_SCHEDULER_TASK_ROUTINE_EXCEPTION', $e->getMessage()), 'error');
			$this->snapshot['exception'] = $e;
			$this->snapshot['status'] = Status::KNOCKOUT;
		}

		$resultSnapshot = $event->getResultSnapshot();

		$this->snapshot['taskEnd']     = microtime(true);
		$this->snapshot['netDuration'] = $this->snapshot['taskEnd'] - $this->snapshot['taskStart'];
		$this->snapshot                = array_merge($this->snapshot, $resultSnapshot);

		// @todo make the ExecRuleHelper usage less ugly, perhaps it should be composed into Task
		// Update object state.
		$this->set('last_execution', Factory::getDate('@' . (int) $this->snapshot['taskStart'])->toSql());
		$this->set('last_exit_code', $this->snapshot['status']);

		if ($this->snapshot['status'] !== Status::WILL_RESUME)
		{
			$this->set('next_execution', (new ExecRuleHelper($this->taskRegistry->toObject()))->nextExec());
			$this->set('times_executed', $this->get('times_executed') + 1);
		}
		else
		{
			/**
			 * Resumable tasks need special handling.
			 *
			 * They are rescheduled as soon as possible to let their next step to be executed without
			 * a very large temporal gap to the previous step.
			 *
			 * Moreover, the times executed does NOT increase for each step. It will increase once,
			 * after the last step, when they return Status::OK.
			 */
			$this->set('next_execution', Factory::getDate('now', 'UTC')->sub(new \DateInterval('PT1M'))->toSql());
		}

		// The only acceptable "successful" statuses are either clean exit or resuming execution.
		if (!in_array($this->snapshot['status'], [Status::WILL_RESUME, Status::OK]))
		{
			$this->set('times_failed', $this->get('times_failed') + 1);
		}

		if (!$this->releaseLock())
		{
			$this->snapshot['status'] = Status::NO_RELEASE;
		}

		$this->dispatchExitEvent();

		if (!empty($this->snapshot['exception']))
		{
			throw $this->snapshot['exception'];
		}

		return $this->isSuccess();
	}

	/**
	 * Get the task execution snapshot.
	 * ! Access locations will need updates once a more robust Snapshot container is implemented.
	 *
	 * @return array
	 *
	 * @since 4.1.0
	 */
	public function getContent(): array
	{
		return $this->snapshot;
	}

	/**
	 * Acquire a pseudo-lock on the task record.
	 * ! At the moment, this method is not used anywhere as task locks are already
	 *   acquired when they're fetched. As such this method is not functional and should
	 *   not be reviewed until it is updated.
	 *
	 * @return boolean
	 *
	 * @since 4.1.0
	 * @throws \Exception
	 */
	public function acquireLock(): bool
	{
		$db    = $this->db;
		$query = $db->getQuery(true);
		$id    = $this->get('id');
		$now   = Factory::getDate('now', 'GMT');

		$timeout          = ComponentHelper::getParams('com_scheduler')->get('timeout', 300);
		$timeout          = new \DateInterval(sprintf('PT%dS', $timeout));
		$timeoutThreshold = (clone $now)->sub($timeout)->toSql();
		$now              = $now->toSql();

		// @todo update or remove this method
		$query->update($db->qn('#__scheduler_tasks'))
			->set('locked = :now')
			->where($db->qn('id') . ' = :taskId')
			->extendWhere(
				'AND',
				[
					$db->qn('locked') . ' < :threshold',
					$db->qn('locked') . 'IS NULL',
				],
				'OR'
			)
			->bind(':taskId', $id, ParameterType::INTEGER)
			->bind(':now', $now)
			->bind(':threshold', $timeoutThreshold);

		try
		{
			$db->lockTable('#__scheduler_tasks');
			$db->setQuery($query)->execute();
		}
		catch (\RuntimeException $e)
		{
			return false;
		}
		finally
		{
			$db->unlockTables();
		}

		if ($db->getAffectedRows() === 0)
		{
			return false;
		}

		$this->set('locked', $now);

		return true;
	}

	/**
	 * Remove the pseudo-lock and optionally update the task record.
	 *
	 * @param   bool  $update  If true, the record is updated with the snapshot
	 *
	 * @return boolean
	 *
	 * @since 4.1.0
	 * @throws \Exception
	 */
	public function releaseLock(bool $update = true): bool
	{
		$db    = $this->db;
		$query = $db->getQuery(true);
		$id    = $this->get('id');

		$query->update($db->qn('#__scheduler_tasks', 't'))
			->set('locked = NULL')
			->where($db->qn('id') . ' = :taskId')
			->where($db->qn('locked') . ' IS NOT NULL')
			->bind(':taskId', $id, ParameterType::INTEGER);

		if ($update)
		{
			$exitCode      = $this->get('last_exit_code');
			$lastExec      = $this->get('last_execution');
			$nextExec      = $this->get('next_execution');
			$timesFailed   = $this->get('times_failed');
			$timesExecuted = $this->get('times_executed');

			$query->set(
				[
					'last_exit_code = :exitCode',
					'last_execution = :lastExec',
					'next_execution = :nextExec',
					'times_executed = :times_executed',
					'times_failed = :times_failed',
				]
			)
				->bind(':exitCode', $exitCode, ParameterType::INTEGER)
				->bind(':lastExec', $lastExec)
				->bind(':nextExec', $nextExec)
				->bind(':times_executed', $timesExecuted)
				->bind(':times_failed', $timesFailed);
		}

		try
		{
			$db->setQuery($query)->execute();
		}
		catch (\RuntimeException $e)
		{
			return false;
		}

		if (!$db->getAffectedRows())
		{
			return false;
		}

		$this->set('locked', null);

		return true;
	}

	/**
	 * @param   string  $message   Log message
	 * @param   string  $priority  Log level, defaults to 'info'
	 *
	 * @return  void
	 *
	 * @since 4.1.0
	 * @throws InvalidArgumentException
	 */
	public function log(string $message, string $priority = 'info'): void
	{
		$this->logger->log($priority, $message, ['category' => $this->logCategory]);
	}

	/**
	 * Advance the task entry's next calculated execution, effectively skipping the current execution.
	 *
	 * @return void
	 *
	 * @since 4.1.0
	 * @throws \Exception
	 */
	public function skipExecution(): void
	{
		$db    = $this->db;
		$query = $db->getQuery(true);

		$id       = $this->get('id');
		$nextExec = (new ExecRuleHelper($this->taskRegistry->toObject()))->nextExec(true, true);

		$query->update($db->qn('#__scheduler_tasks', 't'))
			->set('t.next_execution = :nextExec')
			->where('t.id = :id')
			->bind(':nextExec', $nextExec)
			->bind(':id', $id);

		try
		{
			$db->setQuery($query)->execute();
		}
		catch (\RuntimeException $e)
		{
		}

		$this->set('next_execution', $nextExec);
	}

	/**
	 * Handles task exit (dispatch event).
	 *
	 * @return void
	 *
	 * @since 4.1.0
	 *
	 * @throws \UnexpectedValueException|\BadMethodCallException
	 */
	protected function dispatchExitEvent(): void
	{
		$exitCode  = $this->snapshot['status'] ?? 'NA';
		$eventName = self::EVENTS_MAP[$exitCode] ?? self::EVENTS_MAP['NA'];

		$event = AbstractEvent::create(
			$eventName,
			[
				'subject' => $this,
			]
		);

		$this->app->getDispatcher()->dispatch($eventName, $event);
	}

	/**
	 * Was the task successful?
	 *
	 * @return boolean  True if the task was successful.
	 * @since 4.1.0
	 */
	public function isSuccess(): bool
	{
		return in_array(($this->snapshot['status'] ?? null), [Status::OK, Status::WILL_RESUME]);
	}

	/**
	 * Set a task property. This method is a proxy to {@see Registry::set()}.
	 *
	 * @param   string   $path       Registry path of the task property.
	 * @param   mixed    $value      The value to set to the property.
	 * @param   ?string  $separator  The key separator.
	 *
	 * @return mixed|null
	 *
	 * @since 4.1.0
	 */
	protected function set(string $path, $value, string $separator = null)
	{
		return $this->taskRegistry->set($path, $value, $separator);
	}

	/**
	 * Get a task property. This method is a proxy to {@see Registry::get()}.
	 *
	 * @param   string  $path     Registry path of the task property.
	 * @param   mixed   $default  Default property to return, if the actual value is null.
	 *
	 * @return mixed  The task property.
	 *
	 * @since 4.1.0
	 */
	public function get(string $path, $default = null)
	{
		return $this->taskRegistry->get($path, $default);
	}

	/**
	 * Static method to determine whether an enumerated task state (as a string) is valid.
	 *
	 * @param   string  $state  The task state (enumerated, as a string).
	 *
	 * @return boolean
	 *
	 * @since 4.1.0
	 */
	public static function isValidState(string $state): bool
	{
		if (!is_numeric($state))
		{
			return false;
		}

		// Takes care of interpreting as float/int
		$state = $state + 0;

		return ArrayHelper::getValue(self::STATE_MAP, $state) !== null;
	}

	/**
	 * Static method to determine whether a task id is valid. Note that this does not
	 * validate ids against the database, but only verifies that an id may exist.
	 *
	 * @param   string  $id  The task id (as a string).
	 *
	 * @return boolean
	 *
	 * @since 4.1.0
	 */
	public static function isValidId(string $id): bool
	{
		$id = is_numeric($id) ? ($id + 0) : $id;

		if (!\is_int($id) || $id <= 0)
		{
			return false;
		}

		return true;
	}
}

The same content is in 15 releases, Joomla 4.1.1-rc2 to 4.2.0-beta2. See them all, or every version of this file.