path: root/modules-available/sysconfig/inc/configmodule.inc.php

<?php

/**
 * Base class for config modules
 */
abstract class ConfigModule
{

	/**
	 * @var ?array{'title': string,
	 * 'description': string,
	 * 'group': string,
	 * 'unique': bool,
	 * 'sortOrder': int,
	 * 'moduleClass': string,
	 * 'wizardClass': string}[] list of known module types
	 */
	private static $moduleTypes = null;

	private $moduleId = 0;
	private $moduleArchive = '';
	private $moduleTitle = '';
	private $moduleStatus = 'MISSING';
	/** @var int */
	private $dateline = 0;
	/** @var int */
	private $currentVersion = 0;
	/**
	 * @var false|array Data of module, false if not initialized
	 */
	protected $moduleData = false;
	
	/**
	 * Load all known config module types. This is done
	 * by including *.inc.php from inc/configmodule/. The
	 * files there should in turn call ConfigModule::registerModule()
	 * to register themselves.
	 */
	public static function loadDb()
	{
		if (self::$moduleTypes !== null)
			return;
		self::$moduleTypes = [];
		Module::isAvailable('sysconfig');
		foreach (glob(dirname(__FILE__) . '/configmodule/*.inc.php', GLOB_NOSORT) as $file) {
			require_once $file;
		}
	}

	/**
	 * Get all known config module types.
	 * @return  array{'title': string,
	 *  'description': string,
	 *  'group': string,
	 *  'unique': bool,
	 *  'sortOrder': int,
	 *  'moduleClass': string,
	 *  'wizardClass': string}[] list of known module types
	 * /
	 */
	public static function getList(): array
	{
		self::loadDb();
		return self::$moduleTypes;
	}

	/**
	 * Add a known configuration module. Every inc/configmodule/*.inc.php should call this.
	 *
	 * @param string $id Identifier for the module.
	 * 		The module class must be called ConfigModule_{$id}, the wizard start class {$id}_Start.
	 * 		The wizard's classes should be located in modules/sysconfig/addmodule_{$id_lowercase}.inc.php
	 * @param string $title Title of this module type
	 * @param string $description Description for this module type
	 * @param string $group Title for group this module type belongs to
	 * @param bool $unique Can only one such module be added to a config?
	 * @param int $sortOrder Lower comes first, alphabetical ordering otherwise
	 */
	public static function registerModule(string $id, string $title, string $description, string $group, bool $unique, int $sortOrder = 0): void
	{
		if (isset(self::$moduleTypes[$id])) {
			ErrorHandler::traceError("Config Module $id already registered!");
		}
		$moduleClass = 'ConfigModule_' . $id;
		$wizardClass = $id . '_Start';
		if (!class_exists($moduleClass)) {
			ErrorHandler::traceError("Class $moduleClass does not exist!");
		}
		if (!is_subclass_of($moduleClass, 'ConfigModule')) {
			ErrorHandler::traceError("$moduleClass does not have ConfigModule as its parent!");
		}
		self::$moduleTypes[$id] = array(
			'title' => $title,
			'description' => $description,
			'group' => $group,
			'unique' => $unique,
			'sortOrder' => $sortOrder,
			'moduleClass' => $moduleClass,
			'wizardClass' => $wizardClass
		);
	}

	/**
	 * Get fresh instance of ConfigModule subclass for given module type.
	 *
	 * @param string $moduleType name of module type
	 * @return ConfigModule module instance
	 */
	public static function getInstance(string $moduleType): ConfigModule
	{
		$ret = self::getInstanceOrNull($moduleType);
		if ($ret === null) {
			Message::addError('main.error-read', $moduleType . '.inc.php');
			Util::redirect('?do=sysconfig');
		}
		return $ret;
	}

	public static function getInstanceOrNull(string $moduleType): ?ConfigModule
	{
		self::loadDb();
		if (!isset(self::$moduleTypes[$moduleType])) {
			error_log('Unknown module type: ' . $moduleType);
			return null;
		}
		return new self::$moduleTypes[$moduleType]['moduleClass'];
	}

	private static function instanceFromDbRow(array $dbRow): ?ConfigModule
	{
		$instance = self::getInstanceOrNull($dbRow['moduletype']);
		if ($instance === null)
			return null;
		$instance->currentVersion = $dbRow['version'];
		$instance->moduleArchive = $dbRow['filepath'];
		$instance->moduleData = json_decode($dbRow['contents'], true);
		$instance->moduleId = $dbRow['moduleid'];
		$instance->moduleTitle = $dbRow['title'];
		$instance->moduleStatus = $dbRow['status'];
		$instance->dateline = $dbRow['dateline'];
		if ($instance->moduleVersion() > $instance->currentVersion) {
			$instance->markFailed();
		}
		return $instance;
	}

	/**
	 * Get module instance from id.
	 *
	 * @param int $moduleId module id to get
	 * @return ?ConfigModule The requested module from DB, or null on error
	 */
	public static function get(int $moduleId): ?ConfigModule
	{
		$ret = Database::queryFirst("SELECT moduleid, title, moduletype, filepath, contents, version, status, dateline FROM configtgz_module "
				. " WHERE moduleid = :moduleid LIMIT 1", array('moduleid' => $moduleId));
		if ($ret === false)
			return null;
		return self::instanceFromDbRow($ret);
	}

	/**
	 * Get module instances from module type.
	 *
	 * @param string $moduleType module type to get
	 * @return ?ConfigModule[] The requested modules from DB, or null on error
	 */
	public static function getAll(string $moduleType = null): ?array
	{
		if ($moduleType === null) {
			$ret = Database::simpleQuery("SELECT moduleid, title, moduletype, filepath, contents, version, status, dateline FROM configtgz_module");
		} else {
			$ret = Database::simpleQuery("SELECT moduleid, title, moduletype, filepath, contents, version, status, dateline FROM configtgz_module "
					. " WHERE moduletype = :moduletype", array('moduletype' => $moduleType));
		}
		if ($ret === false)
			return null;
		$list = array();
		foreach ($ret as $row) {
			$instance = self::instanceFromDbRow($row);
			if ($instance === null)
				continue;
			$list[] = $instance;
		}
		return $list;
	}

	/**
	 * Get the module version.
	 * 
	 * @return int module version
	 */
	protected abstract function moduleVersion(): int;

	/**
	 * Validate the module's configuration.
	 * 
	 * @return bool ok or not
	 */
	protected abstract function validateConfig(): bool;

	/**
	 * Set module specific data.
	 * 
	 * @param string $key key, name or id of data being set
	 * @param mixed $value Module specific data
	 * @return bool true if data was successfully set, false otherwise (i.e. invalid data being set)
	 */
	public abstract function setData(string $key, $value): bool;
	
	/**
	 * Get module specific data.
	 * Can be overridden by modules.
	 * 
	 * @param ?string $key key, name or id of data to get, or null to get the raw moduleData array
	 * @return mixed Module specific data
	 */
	public function getData(?string $key)
	{
		if ($key === null)
			return $this->moduleData;
		if (!is_array($this->moduleData) || !isset($this->moduleData[$key]))
			return null;
		return $this->moduleData[$key];
	}

	/**
	 * Module specific version of generate.
	 * 
	 * @param string $tgz File name of tgz module to write final output to
	 * @param string|null $parent Parent task of this task
	 * @return array|boolean true if generation is completed immediately,
	 * 		a task struct if some task needs to be run for generation,
	 * 		false on error
	 */
	protected abstract function generateInternal(string $tgz, ?string $parent);

	private function createFileName(): string
	{
		return CONFIG_TGZ_LIST_DIR . '/modules/'
			. $this->moduleType() . '_id-' . $this->moduleId . '__' . mt_rand() . '-' . time() . '.tgz';
	}

	public function allowDownload(): bool
	{
		return false;
	}

	public function needRebuild(): bool
	{
		return $this->moduleStatus !== 'OK' || $this->currentVersion < $this->moduleVersion();
	}
	
	/**
	 * Get module id (in db)
	 *
	 * @return int id
	 */
	public final function id(): int
	{
		return $this->moduleId;
	}
	
	/**
	 * Get module title.
	 */
	public final function title(): string
	{
		return $this->moduleTitle;
	}
	
	/**
	 * Get module archive file name.
	 *
	 * @return string tgz file absolute path
	 */
	public final function archive(): string
	{
		return $this->moduleArchive;
	}

	public final function status(): string
	{
		return $this->moduleStatus;
	}

	public final function currentVersion(): int
	{
		return $this->currentVersion;
	}
	
	/**
	 * Get the module type.
	 *
	 * @return string module type
	 */
	public final function moduleType(): string
	{
		// Yes, need to pass $this, otherwise we get ConfigModule, the base class this function is part of
		$name = get_class($this);
		// ConfigModule_*
		if (!preg_match('/^ConfigModule_(\w+)$/', $name, $out))
			ErrorHandler::traceError('ConfigModule::moduleType: get_class($this) returned "' . $name . '"');
		return $out[1];
	}

	/**
	 * Insert this config module into DB. Only
	 * valid if the object was created using the creating constructor,
	 * not if the instance was created using a database entry (static get method).
	 * 
	 * @param string $title display name of the module
	 * @return boolean true if inserted successfully, false if module config is invalid
	 */
	public final function insert(string $title): bool
	{
		if ($this->moduleId !== 0)
			ErrorHandler::traceError('ConfigModule::insert called when moduleId != 0');
		if (!$this->validateConfig())
			return false;
		$this->moduleTitle = $title;
		// Insert
		Database::exec("INSERT INTO configtgz_module (title, moduletype, filepath, contents, version, status, dateline) "
			. " VALUES (:title, :type, '', :contents, :version, :status, :now)", array(
			'title' => $title,
			'type' => $this->moduleType(),
			'contents' => json_encode($this->moduleData),
			'version' => 0,
			'status' => 'MISSING',
			'now' => time(),
		));
		$this->moduleId = Database::lastInsertId();
		if (!is_numeric($this->moduleId))
			ErrorHandler::traceError('Inserting new config module into DB did not yield a numeric insert id');
		$this->moduleArchive = $this->createFileName();
		Database::exec("UPDATE configtgz_module SET filepath = :path WHERE moduleid = :moduleid LIMIT 1", array(
			'path' => $this->moduleArchive,
			'moduleid' => $this->moduleId
		));
		return true;
	}
	
	/**
	 * Update the given module in database. This will not regenerate
	 * the module's tgz.
	 *
	 * @return boolean true on success, false otherwise
	 */
	public final function update(string $title = ''): bool
	{
		if ($this->moduleId === 0)
			ErrorHandler::traceError('ConfigModule::update called when moduleId == 0');
		if (!empty($title)) {
			$this->moduleTitle = $title;
		}
		if (!$this->validateConfig())
			return false;
		// Update
		Database::exec("UPDATE configtgz_module SET title = :title, contents = :contents, status = :status, dateline = :now "
			. " WHERE moduleid = :moduleid LIMIT 1", array(
			'moduleid' => $this->moduleId,
			'title' => $this->moduleTitle,
			'contents' => json_encode($this->moduleData),
			'status' => 'OUTDATED',
			'now' => time(),
		));
		$this->moduleStatus = 'OUTDATED';
		return true;
	}

	/**
	 * Generate the module's tgz, don't wait for completion.
	 * Updating the database etc. will happen later through a callback.
	 *
	 * @param boolean $deleteOnError if true, the db entry will be deleted if generation failed
	 * @param string|null $parent Parent task of this task
	 * @param int $timeoutMs maximum time in milliseconds we wait for completion
	 * @return string|boolean task id if deferred generation was started,
	 * 		true if generation succeeded (without using a task or within $timeoutMs)
	 * 		false on error
	 */
	public final function generate(bool $deleteOnError, string $parent = NULL, int $timeoutMs = 0)
	{
		if ($this->moduleId === 0 || empty($this->moduleTitle))
			ErrorHandler::traceError('ConfigModule::generateAsync called on uninitialized/uninserted module!');
		$tmpTgz = '/tmp/bwlp-id-' . $this->moduleId . '_' . mt_rand() . '_' . time() . '.tgz';
		$ret = $this->generateInternal($tmpTgz, $parent);
		// Wait for generation if requested
		if ($timeoutMs > 0 && isset($ret['id']) && !Taskmanager::isFinished($ret))
			$ret = Taskmanager::waitComplete($ret, $timeoutMs);
		if ($ret === true || (isset($ret['statusCode']) && $ret['statusCode'] === Taskmanager::TASK_FINISHED)) {
			// Already Finished
			if (file_exists($this->moduleArchive) && !file_exists($tmpTgz))
				$tmpTgz = false; // If generateInternal succeeded and there's no tmpTgz, it means the file didn't have to be updated
			return $this->markUpdated($tmpTgz);
		}
		if (!is_array($ret) || !isset($ret['id']) || Taskmanager::isFailed($ret)) {
			if (is_array($ret)) // Failed
				Taskmanager::addErrorMessage($ret);
			if ($deleteOnError)
				$this->delete();
			else
				$this->markFailed();
			return false;
		}
		// Still running, add callback
		TaskmanagerCallback::addCallback($ret, 'cbConfModCreated', array(
			'moduleid' => $this->moduleId,
			'deleteOnError' => $deleteOnError,
			'tmpTgz' => $tmpTgz
		));
		return $ret['id'];
	}

	/**
	 * Delete the module.
	 */
	public final function delete(): void
	{
		if ($this->moduleId === 0)
			ErrorHandler::traceError('ConfigModule::delete called with invalid module id!');
		$ret = Database::exec("DELETE FROM configtgz_module WHERE moduleid = :moduleid LIMIT 1", array(
				'moduleid' => $this->moduleId
			), true) !== false;
		if ($ret !== false) {
			if ($this->moduleArchive)
				Taskmanager::submit('DeleteFile', array('file' => $this->moduleArchive), true);
			$this->moduleId = 0;
			$this->moduleData = false;
			$this->moduleTitle = false;
			$this->moduleArchive = false;
		}
	}

	/**
	 * @param ?string $tmpTgz new tar archive to use for this module, or null if the old one is still valid
	 */
	private function markUpdated(?string $tmpTgz): bool
	{
		if ($this->moduleId === 0)
			ErrorHandler::traceError('ConfigModule::markUpdated called with invalid module id!');
		if ($this->moduleArchive === null)
			$this->moduleArchive = $this->createFileName();
		// Move file
		if ($tmpTgz === null) {
			if (!file_exists($this->moduleArchive)) {
				EventLog::failure('ConfigModule::markUpdated for "' . $this->moduleTitle . '" called with no tmpTgz and no existing tgz!');
				$this->markFailed();
				return false;
			}
		} elseif (!file_exists($tmpTgz)) {
			EventLog::warning('ConfigModule::markUpdated for tmpTgz="' . $this->moduleTitle . '" called which doesn\'t exist. Doing nothing.');
			return true;
		} else {
			$task = Taskmanager::submit('MoveFile', array(
					'source' => $tmpTgz,
					'destination' => $this->moduleArchive
			));
			$task = Taskmanager::waitComplete($task, 5000);
			if (Taskmanager::isFailed($task) || !Taskmanager::isFinished($task)) {
				if (!API && !AJAX) {
					Taskmanager::addErrorMessage($task);
				} else {
					EventLog::failure('Could not move ' . $tmpTgz . ' to ' . $this->moduleArchive . ' while generating "' . $this->moduleTitle . '"', print_r($task, true));
				}
				$this->markFailed();
				return false;
			}
		}
		// Update DB entry
		$retval = Database::exec("UPDATE configtgz_module SET filepath = :filename, version = :version, status = 'OK' WHERE moduleid = :id LIMIT 1", array(
				'id' => $this->moduleId,
				'filename' => $this->moduleArchive,
				'version' => $this->moduleVersion()
			)) !== false;
		// Update related config.tgzs
		$configs = ConfigTgz::getAllForModule($this->moduleId);
		foreach ($configs as $config) {
			$config->markOutdated();
			$config->generate();
		}
		return $retval;
	}

	private function markFailed(): void
	{
		if ($this->moduleId === 0)
			ErrorHandler::traceError('ConfigModule::markFailed called with invalid module id!');
		if ($this->moduleArchive === '') {
			$this->moduleArchive = $this->createFileName();
		}
		if (!file_exists($this->moduleArchive)) {
			$status = 'MISSING';
		} else {
			$status = 'OUTDATED';
		}
		Database::exec("UPDATE configtgz_module SET filepath = :filename, status = :status WHERE moduleid = :id LIMIT 1", array(
				'id' => $this->moduleId,
				'filename' => $this->moduleArchive,
				'status' => $status
			));
	}

	public function dateline_s(): string
	{
		return Util::prettyTime($this->dateline);
	}

	################# Callbacks ##############

	/**
	 * Event callback for when the server ip changed.
	 * Override this if you need to handle this, otherwise
	 * the base implementation does nothing.
	 */
	public function event_serverIpChanged(): void
	{
		// Do::Nothing()
	}

	##################### STATIC CALLBACKS #####################

	/**
	 * Will be called if the server's IP address changes. The event will be propagated
	 * to all config module classes so action can be taken if appropriate.
	 */
	public static function serverIpChanged(): void
	{
		self::loadDb();
		foreach (self::getAll() ?? [] as $mod) {
			$mod->event_serverIpChanged();
		}
	}

	/**
	 * Called when (re)generating a config module failed, so we can
	 * update the status in the DB and add a server log entry.
	 *
	 * @param array $args contains 'moduleid' and optionally 'deleteOnError'
	 */
	public static function generateFailed(array $task, array $args): void
	{
		if (!isset($args['moduleid']) || !is_numeric($args['moduleid'])) {
			EventLog::warning('Ignoring generateFailed event as it has no moduleid assigned.');
			return;
		}
		$module = self::get($args['moduleid']);
		if ($module === null) {
			EventLog::warning('generateFailed callback for module id ' . $args['moduleid'] . ', but no instance could be generated.');
			return;
		}
		$error = '';
		if (!empty($task['data']['error'])) {
			$error .= $task['data']['error'] . "\n\n";
		}
		if (!empty($task['data']['messages'])) {
			$error .= $task['data']['messages'] . "\n\n";
		}
		if (empty($error)) {
			$error = json_encode($task, JSON_PRETTY_PRINT);
		}
		EventLog::failure("Generating module '" . $module->moduleTitle . "' failed.", $error);
		if ($args['deleteOnError'] ?? false) {
			$module->delete();
		} else {
			$module->markFailed();
		}
	}

	/**
	 * (Re)generating a config module succeeded. Update db entry.
	 *
	 * @param array $args contains 'moduleid' and optionally 'tmpTgz'
	 */
	public static function generateSucceeded(array $args): void
	{
		if (!isset($args['moduleid']) || !is_numeric($args['moduleid'])) {
			EventLog::warning('Ignoring generateSucceeded event as it has no moduleid assigned.');
			return;
		}
		$module = self::get($args['moduleid']);
		if ($module === null) {
			EventLog::warning('generateSucceeded callback for module id ' . $args['moduleid'] . ', but no instance could be generated.');
			return;
		}
		$module->markUpdated($args['tmpTgz'] ?? null);
	}

}