<?php

namespace MediaWiki\Settings\Source;

use MediaWiki\Settings\Cache\CacheableSource;
use MediaWiki\Settings\SettingsBuilderException;
use MediaWiki\Settings\Source\Format\JsonFormat;
use MediaWiki\Settings\Source\Format\SettingsFormat;
use MediaWiki\Settings\Source\Format\YamlFormat;
use Stringable;
use UnexpectedValueException;
use Wikimedia\AtEase\AtEase;

/**
 * Settings loaded from a local file path.
 *
 * @since 1.38
 */
class FileSource implements Stringable, CacheableSource, SettingsIncludeLocator {
	private const BUILT_IN_FORMATS = [
		JsonFormat::class,
		YamlFormat::class,
	];

	/**
	 * Cache expiry TTL for file sources (24 hours).
	 *
	 * @see getExpiryTtl()
	 * @see CacheableSource::getExpiryTtl()
	 */
	private const EXPIRY_TTL = 60 * 60 * 24;

	/**
	 * Early expiry weight. This value influences the margin by which
	 * processes are selected to expire cached local-file settings early to
	 * avoid cache stampedes. Changes to this value are not likely to be
	 * necessary as time spent loading from local files should not have much
	 * variation and should already be well served by the default early expiry
	 * calculation.
	 *
	 * @see getExpiryWeight()
	 * @see CacheableSource::getExpiryWeight()
	 */
	private const EXPIRY_WEIGHT = 1.0;

	/**
	 * Format to use for reading the file, if given.
	 *
	 * @var ?SettingsFormat
	 */
	private $format;

	/**
	 * Path to local file.
	 * @var string
	 */
	private $path;

	/**
	 * Constructs a new FileSource for the given path and possibly a custom format
	 * to decode the contents. If no format is given, the built-in formats will be
	 * tried and the first one that supports the file extension will be used.
	 *
	 * Built-in formats:
	 *  - JsonFormat
	 *  - YamlFormat
	 *
	 * <code>
	 * <?php
	 * $source = new FileSource( 'my/settings.json' );
	 * $source->load();
	 * </code>
	 *
	 * While a specialized caller may want to pass a specialized format
	 *
	 * <code>
	 * <?php
	 * $source = new FileSource(
	 *     'my/settings.toml',
	 *     new TomlFormat()
	 * );
	 * $source->load();
	 * </code>
	 *
	 * @param string $path
	 * @param SettingsFormat|null $format
	 */
	public function __construct( string $path, ?SettingsFormat $format = null ) {
		$this->path = $path;
		$this->format = $format;
	}

	/**
	 * Disallow stale results from file sources in the case of load failure as
	 * failing to read from disk would be quite catastrophic and worthy of
	 * propagation.
	 *
	 * @return bool
	 */
	public function allowsStaleLoad(): bool {
		return false;
	}

	/**
	 * Loads contents from the file and decodes them using the first format
	 * to claim support for the file's extension.
	 *
	 * @throws SettingsBuilderException
	 * @return array
	 */
	public function load(): array {
		$ext = pathinfo( $this->path, PATHINFO_EXTENSION );

		// If there's only one format, don't bother to match the file
		// extension.
		if ( $this->format ) {
			return $this->readAndDecode( $this->format );
		}

		foreach ( self::BUILT_IN_FORMATS as $format ) {
			if ( call_user_func( [ $format, 'supportsFileExtension' ], $ext ) ) {
				return $this->readAndDecode( new $format() );
			}
		}

		throw new SettingsBuilderException(
			"None of the built-in formats are suitable for '{path}'",
			[
				'path' => $this->path,
			]
		);
	}

	/**
	 * The cache expiry TTL (in seconds) for this file source.
	 *
	 * @return int
	 */
	public function getExpiryTtl(): int {
		return self::EXPIRY_TTL;
	}

	/**
	 * Coefficient used in determining early expiration of cached settings to
	 * avoid stampedes.
	 *
	 * @return float
	 */
	public function getExpiryWeight(): float {
		return self::EXPIRY_WEIGHT;
	}

	/**
	 * Returns a hash key computed from the file's inode, size, and last
	 * modified timestamp.
	 *
	 * @return string
	 */
	public function getHashKey(): string {
		$stat = stat( $this->path );

		if ( $stat === false ) {
			throw new SettingsBuilderException(
				"Failed to stat file '{path}'",
				[ 'path' => $this->path ]
			);
		}

		return sprintf( '%x-%x-%x', $stat['ino'], $stat['size'], $stat['mtime'] );
	}

	/**
	 * Returns this file source as a string.
	 *
	 * @return string
	 */
	public function __toString(): string {
		return $this->path;
	}

	/**
	 * Reads and decodes the file contents using the given format.
	 *
	 * @param SettingsFormat $format
	 *
	 * @return array
	 * @throws SettingsBuilderException
	 */
	private function readAndDecode( SettingsFormat $format ): array {
		$contents = AtEase::quietCall( 'file_get_contents', $this->path );

		if ( $contents === false ) {
			if ( !is_readable( $this->path ) ) {
				throw new SettingsBuilderException(
					"File '{path}' is not readable",
					[ 'path' => $this->path ]
				);
			}

			if ( is_dir( $this->path ) ) {
				throw new SettingsBuilderException(
					"'{path}' is a directory, not a file",
					[ 'path' => $this->path ]
				);
			}

			throw new SettingsBuilderException(
				"Failed to read file '{path}'",
				[ 'path' => $this->path ]
			);
		}

		try {
			return $format->decode( $contents );
		} catch ( UnexpectedValueException $e ) {
			throw new SettingsBuilderException(
				"Failed to decode file '{path}': {message}",
				[
					'path' => $this->path,
					'message' => $e->getMessage()
				]
			);
		}
	}

	public function locateInclude( string $location ): string {
		return SettingsFileUtils::resolveRelativeLocation( $location, dirname( $this->path ) );
	}
}