<?php
/**
 * PHP API for logging events.
 *
 * @file
 * @ingroup Extensions
 * @ingroup EventLogging
 *
 * @author Ori Livneh <ori@wikimedia.org>
 */

namespace MediaWiki\Extension\EventLogging;

use MediaWiki\Context\RequestContext;
use MediaWiki\Deferred\DeferredUpdates;
use MediaWiki\Extension\EventLogging\EventSubmitter\EventSubmitter;
use MediaWiki\Extension\EventLogging\Libs\JsonSchemaValidation\JsonSchemaException;
use MediaWiki\Extension\EventLogging\Libs\JsonSchemaValidation\JsonTreeRef;
use MediaWiki\Extension\EventLogging\MetricsPlatform\MetricsClientFactory;
use MediaWiki\Json\FormatJson;
use MediaWiki\Logger\LoggerFactory;
use MediaWiki\MediaWikiServices;
use Psr\Log\LoggerInterface;
use RuntimeException;
use Wikimedia\MetricsPlatform\MetricsClient;

class EventLogging {

	/**
	 * @var MetricsClient|null
	 */
	private static $metricsPlatformClient;

	/**
	 * Default logger.
	 *
	 * @internal
	 */
	public static function getLogger(): LoggerInterface {
		return LoggerFactory::getInstance( 'EventLogging' );
	}

	private static function getEventSubmitter(): EventSubmitter {
		return MediaWikiServices::getInstance()->get( 'EventLogging.EventSubmitter' );
	}

	/**
	 * Gets the singleton instance of the Metrics Platform Client (MPC).
	 *
	 * @see https://wikitech.wikimedia.org/wiki/Metrics_Platform
	 */
	public static function getMetricsPlatformClient(): MetricsClient {
		if ( !self::$metricsPlatformClient ) {
			/** @var MetricsClientFactory $metricsClientFactory */
			$metricsClientFactory =
				MediaWikiServices::getInstance()->getService( 'EventLogging.MetricsClientFactory' );

			self::$metricsPlatformClient = $metricsClientFactory->newMetricsClient( RequestContext::getMain() );
		}

		return self::$metricsPlatformClient;
	}

	/**
	 * Resets the Metrics Platform Client for testing purposes. See also the warning and note
	 * against {@link MediaWikiServices::resetServiceForTesting()}.
	 *
	 * @internal
	 *
	 * @throws RuntimeException If called outside a PHPUnit test
	 */
	public static function resetMetricsPlatformClient(): void {
		if ( !defined( 'MW_PHPUNIT_TEST' ) ) {
			throw new RuntimeException( __METHOD__ . ' may only be called during unit tests.' );
		}

		self::$metricsPlatformClient = null;
	}

	/**
	 * Submit an event according to the given stream's configuration.
	 *
	 * @param string $streamName
	 * @param array $event
	 * @param LoggerInterface|null $logger @deprecated since 1.40. All messages will be logged
	 *  via the `EventLogging.Logger` service
	 */
	public static function submit(
		string $streamName,
		array $event,
		?LoggerInterface $logger = null
	): void {
		if ( $logger ) {
			wfDeprecatedMsg( __METHOD__ . ': $logger parameter is deprecated', '1.40' );
		}

		self::getEventSubmitter()->submit( $streamName, $event );
	}

	/**
	 * Transfer small data asynchronously using an HTTP POST.
	 * This is meant to match the Navigator.sendBeacon() API.
	 *
	 * @see https://w3c.github.io/beacon/#sec-sendBeacon-method
	 * @param string $url
	 * @param array $data
	 * @return bool
	 * @deprecated use submit with new Event Platform based schemas.
	 */
	public static function sendBeacon( $url, array $data = [] ) {
		$fname = __METHOD__;
		$urlUtils = MediaWikiServices::getInstance()->getUrlUtils();
		$url = $urlUtils->expand( $url, PROTO_INTERNAL ) ?? '';
		DeferredUpdates::addCallableUpdate( static function () use ( $url, $data, $fname ) {
			$options = $data ? [ 'postData' => $data ] : [];
			return MediaWikiServices::getInstance()->getHttpRequestFactory()
				->post( $url, $options, $fname );
		} );

		return true;
	}

	/**
	 * Legacy EventLogging entrypoint.
	 *
	 * NOTE: For forwards compatibility with Event Platform schemas,
	 * we hijack the wgEventLoggingSchemas revision to encode the
	 * $schema URI. If the value for a schema defined in
	 * EventLoggingSchemas is a string, it is assumed
	 * to be an Event Platform $schema URI, not a MW revision id.
	 * In this case, the event will be POSTed to EventGate.
	 *
	 * @param string $schemaName Schema name.
	 * @param int $revId
	 *        revision ID of schema.  $schemasInfo[$schemaName] will override this.
	 * @param array $eventData
	 *        Map of event keys/vals.
	 *        This is the 'event' field, as provided by the caller,
	 *        not an encapsulated real event.
	 * @param int $options This parameter is deprecated and no longer used.
	 * @return bool Whether the event was logged.
	 * @deprecated use EventLogging::submit() with new Event Platform based schemas.
	 * @see https://wikitech.wikimedia.org/wiki/Event_Platform/Instrumentation_How_To#In_PHP
	 */
	public static function logEvent( $schemaName, $revId, $eventData, $options = 0 ) {
		$config = MediaWikiServices::getInstance()->getMainConfig();

		$eventLoggingConfig = Hooks::getEventLoggingConfig( $config );
		$schemasInfo = $eventLoggingConfig['schemasInfo'];
		$eventLoggingBaseUri = $eventLoggingConfig['baseUrl'];

		// Get the configured revision id or $schema URI
		// to use with events of a particular (legacy metawiki) EventLogging schema.
		// $schemasInfo[$schemaName] overrides passed in $revId.
		$revisionOrSchemaUri = $schemasInfo[$schemaName] ?? $revId ?? -1;

		// Encapsulate and other event meta data to eventData.
		$event = self::encapsulate(
			$schemaName,
			$revisionOrSchemaUri,
			$eventData
		);

		if ( isset( $event['$schema'] ) ) {
			// Assume that if $schema was set by self::encapsulate(), this
			// event should be POSTed to EventGate via EventServiceClient submit()
			self::submit( self::getLegacyStreamName( $schemaName ), $event );
			return true;
		} else {
			// Else this will be sent to the legacy eventlogging backend
			// via 'sendBeacon' by url encoding the json data into a query parameter.
			if ( !$eventLoggingBaseUri ) {
				return false;
			}

			$json = self::serializeEvent( $event );
			$url = $eventLoggingBaseUri . '?' . rawurlencode( $json ) . ';';

			return self::sendBeacon( $url );
		}
	}

	/**
	 *
	 * Converts the encapsulated event from an object to a string.
	 *
	 * @param array $event Encapsulated event
	 * @return string $json
	 */
	public static function serializeEvent( $event ) {
		$eventData = $event['event'];

		if ( count( $eventData ) === 0 ) {
			// Ensure empty events are serialized as '{}' and not '[]'.
			$eventData = (object)$eventData;
		}
		$event['event'] = $eventData;

		// To make the resultant JSON easily extracted from a row of
		// space-separated values, we replace literal spaces with unicode
		// escapes. This is permitted by the JSON specs.
		return str_replace( ' ', '\u0020', FormatJson::encode( $event ) );
	}

	/**
	 * Validates object against JSON Schema.
	 *
	 * @throws JsonSchemaException If the object fails to validate.
	 * @param array $object Object to be validated.
	 * @param array|null $schema Schema to validate against (default: JSON Schema).
	 * @return bool True.
	 */
	public static function schemaValidate( $object, $schema = null ) {
		if ( $schema === null ) {
			// Default to JSON Schema
			$json = file_get_contents( dirname( __DIR__ ) . '/schemas/schemaschema.json' );
			$schema = FormatJson::decode( $json, true );
		}

		// We depart from the JSON Schema specification in disallowing by default
		// additional event fields not mentioned in the schema.
		// See <https://bugzilla.wikimedia.org/show_bug.cgi?id=44454> and
		// <https://tools.ietf.org/html/draft-zyp-json-schema-03#section-5.4>.
		if ( !array_key_exists( 'additionalProperties', $schema ) ) {
			$schema[ 'additionalProperties' ] = false;
		}

		$root = new JsonTreeRef( $object );
		$root->attachSchema( $schema );
		return $root->validate();
	}

	/**
	 * Randomise inclusion based on population size and a session ID.
	 * @param int $populationSize Return true one in this many times. This is 1/samplingRate.
	 * @param string $sessionId Hexadecimal value, only the first 8 characters are used
	 * @return bool True if the event should be included (sampled in), false if not (sampled out)
	 */
	public static function sessionInSample( $populationSize, $sessionId ) {
		$decimal = (int)base_convert( substr( $sessionId, 0, 8 ), 16, 10 );
		return $decimal % $populationSize === 0;
	}

	/**
	 * This encapsulates the event data in a wrapper object with
	 * the default metadata for the current request.
	 *
	 * NOTE: for forwards compatibility with Event Platform schemas,
	 * we hijack the wgEventLoggingSchemas revision to encode the
	 * $schema URI. If the value for a schema defined in
	 * EventLoggingSchemas is a string, it is assumed
	 * to be an Event Platform $schema URI, not a MW revision id.
	 * In this case, the event will be prepared to be POSTed to EventGate.
	 *
	 * @param string $schemaName
	 * @param int|string $revisionOrSchemaUri
	 *        The revision id or a string $schema URI for use with Event Platform.
	 * @param array $eventData un-encapsulated event data
	 * @return array encapsulated event
	 */
	private static function encapsulate( $schemaName, $revisionOrSchemaUri, $eventData ) {
		global $wgDBname;

		$event = [
			'event'            => $eventData,
			'schema'           => $schemaName,
			'wiki'             => $wgDBname,
		];

		if ( isset( $_SERVER[ 'HTTP_HOST' ] ) ) {
			$event['webHost'] = $_SERVER['HTTP_HOST'];
		}

		if ( is_string( $revisionOrSchemaUri ) ) {
			$event['$schema'] = $revisionOrSchemaUri;
			// NOTE: `client_dt` is 'legacy' event time.  `dt` is the preferred event time field
			// and is set in EventServiceClient.
			$event['client_dt'] = wfTimestamp( TS_ISO_8601 );

			// Note: some fields will have defaults set by eventgate-wikimedia.
			// See:
			// - https://gerrit.wikimedia.org/r/plugins/gitiles/eventgate-wikimedia/+/refs/heads/master/eventgate-wikimedia.js#358
			// - https://wikitech.wikimedia.org/wiki/Event_Platform/Schemas/Guidelines#Automatically_populated_fields
		} else {
			$event['revision'] = $revisionOrSchemaUri;
			$event['userAgent'] = $_SERVER[ 'HTTP_USER_AGENT' ] ?? '';
		}

		return $event;
	}

	/**
	 * Prepend "eventlogging_" to the schema name to create a stream name for a migrated legacy
	 * schema.
	 *
	 * @param string $schemaName
	 * @return string
	 */
	private static function getLegacyStreamName( string $schemaName ): string {
		return "eventlogging_$schemaName";
	}

}

class_alias( EventLogging::class, 'EventLogging' );
