wiki.techinc.nl/includes/Rest/Handler/Helper/RevisionContentHelper.php

<?php

namespace MediaWiki\Rest\Handler\Helper;

use MediaWiki\MainConfigNames;
use MediaWiki\Page\ExistingPageRecord;
use MediaWiki\Rest\Handler;
use MediaWiki\Rest\LocalizedHttpException;
use MediaWiki\Rest\ResponseInterface;
use MediaWiki\Revision\RevisionRecord;
use MediaWiki\Revision\SlotRecord;
use Wikimedia\Message\MessageValue;
use Wikimedia\ParamValidator\ParamValidator;

/**
 * @internal for use by core REST infrastructure
 */
class RevisionContentHelper extends PageContentHelper {

	/**
	 * @return int|null The ID of the target revision
	 */
	public function getRevisionId(): ?int {
		return isset( $this->parameters['id'] ) ? (int)$this->parameters['id'] : null;
	}

	/**
	 * @return string|null title text or null if unable to retrieve title
	 */
	public function getTitleText(): ?string {
		$revision = $this->getTargetRevision();
		return $revision
			? $this->titleFormatter->getPrefixedText( $revision->getPageAsLinkTarget() )
			: null;
	}

	/**
	 * @return ExistingPageRecord|null
	 */
	public function getPage(): ?ExistingPageRecord {
		$revision = $this->getTargetRevision();
		return $revision ? $this->pageLookup->getPageByReference( $revision->getPage() ) : null;
	}

	/**
	 * @return RevisionRecord|null latest revision or null if unable to retrieve revision
	 */
	public function getTargetRevision(): ?RevisionRecord {
		if ( $this->targetRevision === false ) {
			$revId = $this->getRevisionId();
			if ( $revId ) {
				$this->targetRevision = $this->revisionLookup->getRevisionById( $revId );
			} else {
				$this->targetRevision = null;
			}
		}
		return $this->targetRevision;
	}

	/**
	 * @return bool
	 */
	public function isAccessible(): bool {
		if ( !parent::isAccessible() ) {
			return false;
		}

		$revision = $this->getTargetRevision();

		// TODO: allow authorized users to see suppressed content. Set cache control accordingly.

		if ( !$revision ||
			!$revision->audienceCan( RevisionRecord::DELETED_TEXT, RevisionRecord::FOR_PUBLIC )
		) {
			return false;
		}

		return true;
	}

	/**
	 * @return bool
	 */
	public function hasContent(): bool {
		return (bool)$this->getTargetRevision();
	}

	public function setCacheControl( ResponseInterface $response, int $expiry = null ) {
		$revision = $this->getTargetRevision();

		if ( $revision && $revision->getVisibility() !== 0 ) {
			// The revision is not public, so it's not cacheable!
			return;
		}

		parent::setCacheControl( $response, $expiry );
	}

	/**
	 * @return array
	 */
	public function constructMetadata(): array {
		$page = $this->getPage();
		$revision = $this->getTargetRevision();

		$mainSlot = $revision->getSlot( SlotRecord::MAIN, RevisionRecord::RAW );

		$metadata = [
			'id' => $revision->getId(),
			'size' => $revision->getSize(),
			'minor' => $revision->isMinor(),
			'timestamp' => wfTimestampOrNull( TS_ISO_8601, $revision->getTimestamp() ),
			'content_model' => $mainSlot->getModel(),
			'page' => [
				'id' => $page->getId(),
				// @phan-suppress-next-line PhanTypeMismatchArgumentNullable
				'key' => $this->titleFormatter->getPrefixedDBkey( $page ),
				// @phan-suppress-next-line PhanTypeMismatchArgumentNullable
				'title' => $this->titleFormatter->getPrefixedText( $page ),
			],
			'license' => [
				'url' => $this->options->get( MainConfigNames::RightsUrl ),
				'title' => $this->options->get( MainConfigNames::RightsText )
			],
		];

		$revUser = $revision->getUser( RevisionRecord::FOR_THIS_USER, $this->authority );
		if ( $revUser ) {
			$metadata['user'] = [
				'id' => $revUser->isRegistered() ? $revUser->getId() : null,
				'name' => $revUser->getName()
			];
		} else {
			$metadata['user'] = null;
		}

		$comment = $revision->getComment( RevisionRecord::FOR_THIS_USER, $this->authority );
		$metadata['comment'] = $comment ? $comment->text : null;

		// @phan-suppress-next-line PhanTypeMismatchArgumentNullable
		$parent = $this->revisionLookup->getPreviousRevision( $revision );
		if ( $parent ) {
			$metadata['delta'] = $revision->getSize() - $parent->getSize();
		} else {
			$metadata['delta'] = null;
		}

		// FIXME: test fall fields
		return $metadata;
	}

	/**
	 * Returns an OpenAPI schema object describing the structure of the response.
	 * @return array
	 */
	public function getResponseBodySchema() {
		// TODO: we need to reference a re-usable "user" type. The license structure should also be re-usable.
		return [
			'description' => 'revision meta-data',
			'required' => [
				'id', 'size', 'delta', 'comment', 'minor', 'timestamp', 'content_model', 'page', 'license'
			],
			'properties' => [
				'id' => [
					'type' => 'integer',
					'description' => 'Revision id',
				],
				'size' => [
					'type' => 'integer',
					'description' => 'The size of the revision, in no particular measure.',
				],
				'delta' => [
					'type' => 'integer',
					'nullable' => true,
					'description' => 'The difference in size compared to the previous revision.',
				],
				'comment' => [
					'type' => 'string',
					'nullable' => true,
					'description' => 'The comment the author associated with the revision',
				],
				'minor' => [
					'type' => 'boolean',
					'description' => 'Whether the author of the revision conidered it minor.',
				],
				'timestamp' => [
					'type' => 'string',
					'format' => 'date-time',
				],
				'content_model' => [
					'type' => 'string',
					'format' => 'mw-content-model',
				],
				'page' => [
					'description' => 'the page the revision belongs to',
					'required' => [ 'id', 'key', 'title' ],
					'properties' => [
						'id' => [
							'type' => 'integer',
							'description' => 'the page ID',
						],
						'key' => [
							'type' => 'string',
							'format' => 'mw-title',
							'description' => 'the page title in URL form (unencoded)',
						],
						'title' => [
							'type' => 'string',
							'format' => 'mw-title',
							'description' => 'the page title in human readable form',
						],
					]
				],
				'license' => [
					'description' => 'license information for the revision content',
					'required' => [ 'url', 'title' ],
					'properties' => [
						'url' => [
							'type' => 'string',
							'format' => 'url',
						],
						'title' => [
							'type' => 'string',
							'description' => 'the name of the license',
						],
					]
				],
			]
		];
	}

	/**
	 * @return array[]
	 */
	public function getParamSettings(): array {
		return [
			'id' => [
				Handler::PARAM_SOURCE => 'path',
				ParamValidator::PARAM_TYPE => 'integer',
				ParamValidator::PARAM_REQUIRED => true,
			],
		];
	}

	/**
	 * @throws LocalizedHttpException if the content is not accessible
	 */
	public function checkAccess() {
		$revId = $this->getRevisionId() ?? '';

		if ( !$this->hasContent() ) {
			throw new LocalizedHttpException(
				MessageValue::new( 'rest-nonexistent-revision' )->plaintextParams( $revId ),
				404
			);
		}

		// @phan-suppress-next-line PhanTypeMismatchArgumentNullable Validated by hasContent
		if ( !$this->isAccessible() || !$this->authority->authorizeRead( 'read', $this->getPageIdentity() ) ) {
			throw new LocalizedHttpException(
				MessageValue::new( 'rest-permission-denied-revision' )->plaintextParams( $revId ),
				403
			);
		}
	}

}