ParserOutputAccess.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Page;
 
use IBufferingStatsdDataFactory;
use InvalidArgumentException;
use MapCacheLRU;
use MediaWiki\Logger\Spi as LoggerSpi;
use MediaWiki\Parser\ParserCacheFactory;
use MediaWiki\Parser\ParserOutput;
use MediaWiki\Parser\Parsoid\PageBundleParserOutputConverter;
use MediaWiki\Parser\RevisionOutputCache;
use MediaWiki\PoolCounter\PoolCounterWork;
use MediaWiki\PoolCounter\PoolWorkArticleView;
use MediaWiki\PoolCounter\PoolWorkArticleViewCurrent;
use MediaWiki\PoolCounter\PoolWorkArticleViewOld;
use MediaWiki\Revision\RevisionLookup;
use MediaWiki\Revision\RevisionRecord;
use MediaWiki\Revision\RevisionRenderer;
use MediaWiki\Status\Status;
use MediaWiki\Title\TitleFormatter;
use ParserCache;
use ParserOptions;
use Wikimedia\Assert\Assert;
use Wikimedia\Parsoid\Parsoid;
use Wikimedia\Rdbms\ChronologyProtector;
use Wikimedia\Rdbms\ILBFactory;
 
class ParserOutputAccess {
 
    public const PARSOID_PCACHE_NAME = 'parsoid-' . ParserCacheFactory::DEFAULT_NAME;
 
    public const PARSOID_RCACHE_NAME = 'parsoid-' . ParserCacheFactory::DEFAULT_RCACHE_NAME;
 
    public const OPT_NO_CHECK_CACHE = 1;
 
    public const OPT_FORCE_PARSE = self::OPT_NO_CHECK_CACHE;
 
    public const OPT_NO_UPDATE_CACHE = 2;
 
    public const OPT_NO_AUDIENCE_CHECK = 4;
 
    public const OPT_NO_CACHE = self::OPT_NO_UPDATE_CACHE | self::OPT_NO_CHECK_CACHE;
 
    public const OPT_LINKS_UPDATE = 8;
 
    public const OPT_FOR_ARTICLE_VIEW = 16;
 
    public const OPT_IGNORE_PROFILE_VERSION = 128;
 
    private const CACHE_NONE = 'none';
 
    private const CACHE_PRIMARY = 'primary';
 
    private const CACHE_SECONDARY = 'secondary';
 
    private MapCacheLRU $localCache;
 
    private ParserCacheFactory $parserCacheFactory;
    private RevisionLookup $revisionLookup;
    private RevisionRenderer $revisionRenderer;
    private IBufferingStatsdDataFactory $statsDataFactory;
    private ILBFactory $lbFactory;
    private ChronologyProtector $chronologyProtector;
    private LoggerSpi $loggerSpi;
    private WikiPageFactory $wikiPageFactory;
    private TitleFormatter $titleFormatter;
 
    public function __construct(
        ParserCacheFactory $parserCacheFactory,
        RevisionLookup $revisionLookup,
        RevisionRenderer $revisionRenderer,
        IBufferingStatsdDataFactory $statsDataFactory,
        ILBFactory $lbFactory,
        ChronologyProtector $chronologyProtector,
        LoggerSpi $loggerSpi,
        WikiPageFactory $wikiPageFactory,
        TitleFormatter $titleFormatter
    ) {
        $this->parserCacheFactory = $parserCacheFactory;
        $this->revisionLookup = $revisionLookup;
        $this->revisionRenderer = $revisionRenderer;
        $this->statsDataFactory = $statsDataFactory;
        $this->lbFactory = $lbFactory;
        $this->chronologyProtector = $chronologyProtector;
        $this->loggerSpi = $loggerSpi;
        $this->wikiPageFactory = $wikiPageFactory;
        $this->titleFormatter = $titleFormatter;
 
        $this->localCache = new MapCacheLRU( 10 );
    }
 
    private function shouldUseCache(
        PageRecord $page,
        ?RevisionRecord $rev
    ) {
        if ( $rev && !$rev->getId() ) {
            // The revision isn't from the database, so the output can't safely be cached.
            return self::CACHE_NONE;
        }
 
        // NOTE: Keep in sync with ParserWikiPage::shouldCheckParserCache().
        // NOTE: when we allow caching of old revisions in the future,
        //       we must not allow caching of deleted revisions.
 
        $wikiPage = $this->wikiPageFactory->newFromTitle( $page );
        if ( !$page->exists() || !$wikiPage->getContentHandler()->isParserCacheSupported() ) {
            return self::CACHE_NONE;
        }
 
        $isOld = $rev && $rev->getId() !== $page->getLatest();
        if ( !$isOld ) {
            return self::CACHE_PRIMARY;
        }
 
        if ( !$rev->audienceCan( RevisionRecord::DELETED_TEXT, RevisionRecord::FOR_PUBLIC ) ) {
            // deleted/suppressed revision
            return self::CACHE_NONE;
        }
 
        return self::CACHE_SECONDARY;
    }
 
    public function getCachedParserOutput(
        PageRecord $page,
        ParserOptions $parserOptions,
        ?RevisionRecord $revision = null,
        int $options = 0
    ): ?ParserOutput {
        $isOld = $revision && $revision->getId() !== $page->getLatest();
        $useCache = $this->shouldUseCache( $page, $revision );
        $primaryCache = $this->getPrimaryCache( $parserOptions );
        $classCacheKey = $primaryCache->makeParserOutputKey( $page, $parserOptions );
 
        if ( $useCache === self::CACHE_PRIMARY ) {
            if ( $this->localCache->hasField( $classCacheKey, $page->getLatest() ) && !$isOld ) {
                return $this->localCache->getField( $classCacheKey, $page->getLatest() );
            }
            $output = $primaryCache->get( $page, $parserOptions );
        } elseif ( $useCache === self::CACHE_SECONDARY && $revision ) {
            $secondaryCache = $this->getSecondaryCache( $parserOptions );
            $output = $secondaryCache->get( $revision, $parserOptions );
        } else {
            $output = null;
        }
 
        $notHitReason = 'miss';
        if (
            $output && !( $options & self::OPT_IGNORE_PROFILE_VERSION ) &&
            $parserOptions->getUseParsoid()
        ) {
            $pageBundleData = $output->getExtensionData(
                PageBundleParserOutputConverter::PARSOID_PAGE_BUNDLE_KEY
            );
            // T333606: Force a reparse if the version coming from cache is not the default
            $cachedVersion = $pageBundleData['version'] ?? null;
            if (
                $cachedVersion !== null && // T325137: BadContentModel, no sense in reparsing
                $cachedVersion !== Parsoid::defaultHTMLVersion()
            ) {
                $notHitReason = 'obsolete';
                $output = null;
            }
        }
 
        if ( $output && !$isOld ) {
            $this->localCache->setField( $classCacheKey, $page->getLatest(), $output );
        }
 
        if ( $output ) {
            $this->statsDataFactory->increment( "ParserOutputAccess.Cache.$useCache.hit" );
        } else {
            $this->statsDataFactory->increment( "ParserOutputAccess.Cache.$useCache.$notHitReason" );
        }
 
        return $output ?: null; // convert false to null
    }
 
    public function getParserOutput(
        PageRecord $page,
        ParserOptions $parserOptions,
        ?RevisionRecord $revision = null,
        int $options = 0
    ): Status {
        $error = $this->checkPreconditions( $page, $revision, $options );
        if ( $error ) {
            $this->statsDataFactory->increment( "ParserOutputAccess.Case.error" );
            return $error;
        }
 
        $isOld = $revision && $revision->getId() !== $page->getLatest();
        if ( $isOld ) {
            $this->statsDataFactory->increment( 'ParserOutputAccess.Case.old' );
        } else {
            $this->statsDataFactory->increment( 'ParserOutputAccess.Case.current' );
        }
 
        if ( !( $options & self::OPT_NO_CHECK_CACHE ) ) {
            $output = $this->getCachedParserOutput( $page, $parserOptions, $revision );
            if ( $output ) {
                return Status::newGood( $output );
            }
        }
 
        if ( !$revision ) {
            $revId = $page->getLatest();
            $revision = $revId ? $this->revisionLookup->getRevisionById( $revId ) : null;
 
            if ( !$revision ) {
                $this->statsDataFactory->increment( "ParserOutputAccess.Status.norev" );
                return Status::newFatal( 'missing-revision', $revId );
            }
        }
 
        if ( $options & self::OPT_FOR_ARTICLE_VIEW ) {
            $work = $this->newPoolWorkArticleView( $page, $parserOptions, $revision, $options );
            $status = $work->execute();
        } else {
            $status = $this->renderRevision( $page, $parserOptions, $revision, $options );
        }
 
        $output = $status->getValue();
        Assert::postcondition( $output || !$status->isOK(), 'Inconsistent status' );
 
        if ( $output && !$isOld ) {
            $primaryCache = $this->getPrimaryCache( $parserOptions );
            $classCacheKey = $primaryCache->makeParserOutputKey( $page, $parserOptions );
            $this->localCache->setField( $classCacheKey, $page->getLatest(), $output );
        }
 
        if ( $status->isGood() ) {
            $this->statsDataFactory->increment( 'ParserOutputAccess.Status.good' );
        } elseif ( $status->isOK() ) {
            $this->statsDataFactory->increment( 'ParserOutputAccess.Status.ok' );
        } else {
            $this->statsDataFactory->increment( 'ParserOutputAccess.Status.error' );
        }
 
        return $status;
    }
 
    private function renderRevision(
        PageRecord $page,
        ParserOptions $parserOptions,
        RevisionRecord $revision,
        int $options
    ): Status {
        $this->statsDataFactory->increment( 'ParserOutputAccess.PoolWork.None' );
 
        $renderedRev = $this->revisionRenderer->getRenderedRevision(
            $revision,
            $parserOptions,
            null,
            [ 'audience' => RevisionRecord::RAW ]
        );
 
        $output = $renderedRev->getRevisionParserOutput();
 
        if ( !( $options & self::OPT_NO_UPDATE_CACHE ) && $output->isCacheable() ) {
            $useCache = $this->shouldUseCache( $page, $revision );
 
            if ( $useCache === self::CACHE_PRIMARY ) {
                $primaryCache = $this->getPrimaryCache( $parserOptions );
                $primaryCache->save( $output, $page, $parserOptions );
            } elseif ( $useCache === self::CACHE_SECONDARY ) {
                $secondaryCache = $this->getSecondaryCache( $parserOptions );
                $secondaryCache->save( $output, $revision, $parserOptions );
            }
        }
 
        if ( $options & self::OPT_LINKS_UPDATE ) {
            $this->wikiPageFactory->newFromTitle( $page )
                ->triggerOpportunisticLinksUpdate( $output );
        }
 
        return Status::newGood( $output );
    }
 
    private function checkPreconditions(
        PageRecord $page,
        ?RevisionRecord $revision = null,
        int $options = 0
    ): ?Status {
        if ( !$page->exists() ) {
            return Status::newFatal( 'nopagetext' );
        }
 
        if ( !( $options & self::OPT_NO_UPDATE_CACHE ) && $revision && !$revision->getId() ) {
            throw new InvalidArgumentException(
                'The revision does not have a known ID. Use OPT_NO_CACHE.'
            );
        }
 
        if ( $revision && $revision->getPageId() !== $page->getId() ) {
            throw new InvalidArgumentException(
                'The revision does not belong to the given page.'
            );
        }
 
        if ( $revision && !( $options & self::OPT_NO_AUDIENCE_CHECK ) ) {
            // NOTE: If per-user checks are desired, the caller should perform them and
            //       then set OPT_NO_AUDIENCE_CHECK if they passed.
            if ( !$revision->audienceCan( RevisionRecord::DELETED_TEXT, RevisionRecord::FOR_PUBLIC ) ) {
                return Status::newFatal(
                    'missing-revision-permission',
                    $revision->getId(),
                    $revision->getTimestamp(),
                    $this->titleFormatter->getPrefixedDBkey( $page )
                );
            }
        }
 
        return null;
    }
 
    protected function newPoolWorkArticleView(
        PageRecord $page,
        ParserOptions $parserOptions,
        RevisionRecord $revision,
        int $options
    ): PoolCounterWork {
        $useCache = $this->shouldUseCache( $page, $revision );
 
        switch ( $useCache ) {
            case self::CACHE_PRIMARY:
                $this->statsDataFactory->increment( 'ParserOutputAccess.PoolWork.Current' );
                $primaryCache = $this->getPrimaryCache( $parserOptions );
                $parserCacheMetadata = $primaryCache->getMetadata( $page );
                $cacheKey = $primaryCache->makeParserOutputKey( $page, $parserOptions,
                    $parserCacheMetadata ? $parserCacheMetadata->getUsedOptions() : null
                );
 
                $workKey = $cacheKey . ':revid:' . $revision->getId();
 
                return new PoolWorkArticleViewCurrent(
                    $workKey,
                    $page,
                    $revision,
                    $parserOptions,
                    $this->revisionRenderer,
                    $primaryCache,
                    $this->lbFactory,
                    $this->chronologyProtector,
                    $this->loggerSpi,
                    $this->wikiPageFactory,
                    !( $options & self::OPT_NO_UPDATE_CACHE ),
                    (bool)( $options & self::OPT_LINKS_UPDATE )
                );
 
            case self::CACHE_SECONDARY:
                $this->statsDataFactory->increment( 'ParserOutputAccess.PoolWork.Old' );
                $secondaryCache = $this->getSecondaryCache( $parserOptions );
                $workKey = $secondaryCache->makeParserOutputKey( $revision, $parserOptions );
                return new PoolWorkArticleViewOld(
                    $workKey,
                    $secondaryCache,
                    $revision,
                    $parserOptions,
                    $this->revisionRenderer,
                    $this->loggerSpi
                );
 
            default:
                $this->statsDataFactory->increment( 'ParserOutputAccess.PoolWork.Uncached' );
                $secondaryCache = $this->getSecondaryCache( $parserOptions );
                $workKey = $secondaryCache->makeParserOutputKeyOptionalRevId( $revision, $parserOptions );
                return new PoolWorkArticleView(
                    $workKey,
                    $revision,
                    $parserOptions,
                    $this->revisionRenderer,
                    $this->loggerSpi
                );
        }
 
        // unreachable
    }
 
    private function getPrimaryCache( ParserOptions $pOpts ): ParserCache {
        if ( $pOpts->getUseParsoid() ) {
            return $this->parserCacheFactory->getParserCache(
                self::PARSOID_PCACHE_NAME
            );
        }
 
        return $this->parserCacheFactory->getParserCache(
            ParserCacheFactory::DEFAULT_NAME
        );
    }
 
    private function getSecondaryCache( ParserOptions $pOpts ): RevisionOutputCache {
        if ( $pOpts->getUseParsoid() ) {
            return $this->parserCacheFactory->getRevisionOutputCache(
                self::PARSOID_RCACHE_NAME
            );
        }
 
        return $this->parserCacheFactory->getRevisionOutputCache(
            ParserCacheFactory::DEFAULT_RCACHE_NAME
        );
    }
 
}