ParserCache.php

Go to the documentation of this file.

<?php
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\HookContainer\HookRunner;
use MediaWiki\Json\JsonCodec;
use MediaWiki\Page\PageRecord;
use MediaWiki\Page\WikiPageFactory;
use MediaWiki\Parser\ParserCacheMetadata;
use Psr\Log\LoggerInterface;
 
class ParserCache {
    public const USE_CURRENT_ONLY = 0;
 
    public const USE_EXPIRED = 1;
 
    public const USE_OUTDATED = 2;
 
    private const USE_ANYTHING = 3;
 
    private $name;
 
    private $cache;
 
    private $cacheEpoch;
 
    private $hookRunner;
 
    private $jsonCodec;
 
    private $stats;
 
    private $logger;
 
    private $titleFactory;
 
    private $wikiPageFactory;
 
    private $metadataProcCache;
 
    private $writeJson = false;
 
    private $readJson = false;
 
    public function __construct(
        string $name,
        BagOStuff $cache,
        string $cacheEpoch,
        HookContainer $hookContainer,
        JsonCodec $jsonCodec,
        IBufferingStatsdDataFactory $stats,
        LoggerInterface $logger,
        TitleFactory $titleFactory,
        WikiPageFactory $wikiPageFactory,
        $useJson = false
    ) {
        $this->name = $name;
        $this->cache = $cache;
        $this->cacheEpoch = $cacheEpoch;
        $this->hookRunner = new HookRunner( $hookContainer );
        $this->jsonCodec = $jsonCodec;
        $this->stats = $stats;
        $this->logger = $logger;
        $this->titleFactory = $titleFactory;
        $this->wikiPageFactory = $wikiPageFactory;
        $this->readJson = $useJson;
        $this->writeJson = $useJson;
        $this->metadataProcCache = new HashBagOStuff( [ 'maxKeys' => 2 ] );
    }
 
    public function deleteOptionsKey( PageRecord $page ) {
        $page->assertWiki( PageRecord::LOCAL );
        $key = $this->makeMetadataKey( $page );
        $this->metadataProcCache->delete( $key );
        $this->cache->delete( $key );
    }
 
    public function getDirty( PageRecord $page, $popts ) {
        $page->assertWiki( PageRecord::LOCAL );
        $value = $this->get( $page, $popts, true );
        return is_object( $value ) ? $value : false;
    }
 
    private function incrementStats( PageRecord $page, $metricSuffix ) {
        $wikiPage = $this->wikiPageFactory->newFromTitle( $page );
        $contentModel = str_replace( '.', '_', $wikiPage->getContentModel() );
        $metricSuffix = str_replace( '.', '_', $metricSuffix );
        $this->stats->increment( "{$this->name}.{$contentModel}.{$metricSuffix}" );
    }
 
    public function getMetadata(
        PageRecord $page,
        int $staleConstraint = self::USE_ANYTHING
    ): ?ParserCacheMetadata {
        $page->assertWiki( PageRecord::LOCAL );
 
        $pageKey = $this->makeMetadataKey( $page );
        $metadata = $this->metadataProcCache->get( $pageKey );
        if ( !$metadata ) {
            $metadata = $this->cache->get(
                $pageKey,
                BagOStuff::READ_VERIFIED
            );
        }
 
        if ( $metadata === false ) {
            $this->incrementStats( $page, "miss.absent.metadata" );
            $this->logger->debug( 'ParserOutput metadata cache miss', [ 'name' => $this->name ] );
            return null;
        }
 
        // NOTE: If the value wasn't serialized to JSON when being stored,
        //       we may already have a ParserOutput object here. This used
        //       to be the default behavior before 1.36. We need to retain
        //       support so we can handle cached objects after an update
        //       from an earlier revision.
        // NOTE: Support for reading string values from the cache must be
        //       deployed a while before starting to write JSON to the cache,
        //       in case we have to revert either change.
        if ( is_string( $metadata ) && $this->readJson ) {
            $metadata = $this->restoreFromJson( $metadata, $pageKey, CacheTime::class );
        }
 
        if ( !$metadata instanceof CacheTime ) {
            $this->incrementStats( $page, 'miss.unserialize' );
            return null;
        }
 
        if ( $this->checkExpired( $metadata, $page, $staleConstraint, 'metadata' ) ) {
            return null;
        }
 
        if ( $this->checkOutdated( $metadata, $page, $staleConstraint, 'metadata' ) ) {
            return null;
        }
 
        $this->logger->debug( 'Parser cache options found', [ 'name' => $this->name ] );
        return $metadata;
    }
 
    private function makeMetadataKey( PageRecord $page ): string {
        return $this->cache->makeKey( $this->name, 'idoptions', $page->getId( PageRecord::LOCAL ) );
    }
 
    public function makeParserOutputKey(
        PageRecord $page,
        ParserOptions $options,
        array $usedOptions = null
    ): string {
        $usedOptions = $usedOptions ?? ParserOptions::allCacheVaryingOptions();
        // idhash seem to mean 'page id' + 'rendering hash' (r3710)
        $pageid = $page->getId( PageRecord::LOCAL );
        $title = $this->titleFactory->castFromPageIdentity( $page );
        $hash = $options->optionsHash( $usedOptions, $title );
        // Before T263581 ParserCache was split between normal page views
        // and action=parse. -0 is left in the key to avoid invalidating the entire
        // cache when removing the cache split.
        return $this->cache->makeKey( $this->name, 'idhash', "{$pageid}-0!{$hash}" );
    }
 
    public function get( PageRecord $page, $popts, $useOutdated = false ) {
        $page->assertWiki( PageRecord::LOCAL );
 
        if ( !$page->exists() ) {
            $this->incrementStats( $page, 'miss.nonexistent' );
            return false;
        }
 
        if ( $page->isRedirect() ) {
            // It's a redirect now
            $this->incrementStats( $page, 'miss.redirect' );
            return false;
        }
 
        $staleConstraint = $useOutdated ? self::USE_OUTDATED : self::USE_CURRENT_ONLY;
        $parserOutputMetadata = $this->getMetadata( $page, $staleConstraint );
        if ( !$parserOutputMetadata ) {
            return false;
        }
 
        if ( !$popts->isSafeToCache( $parserOutputMetadata->getUsedOptions() ) ) {
            $this->incrementStats( $page, 'miss.unsafe' );
            return false;
        }
 
        $parserOutputKey = $this->makeParserOutputKey(
            $page,
            $popts,
            $parserOutputMetadata->getUsedOptions()
        );
 
        $value = $this->cache->get( $parserOutputKey, BagOStuff::READ_VERIFIED );
        if ( $value === false ) {
            $this->incrementStats( $page, "miss.absent" );
            $this->logger->debug( 'ParserOutput cache miss', [ 'name' => $this->name ] );
            return false;
        }
 
        // NOTE: If the value wasn't serialized to JSON when being stored,
        //       we may already have a ParserOutput object here. This used
        //       to be the default behavior before 1.36. We need to retain
        //       support so we can handle cached objects after an update
        //       from an earlier revision.
        // NOTE: Support for reading string values from the cache must be
        //       deployed a while before starting to write JSON to the cache,
        //       in case we have to revert either change.
        if ( is_string( $value ) && $this->readJson ) {
            $value = $this->restoreFromJson( $value, $parserOutputKey, ParserOutput::class );
        }
 
        if ( !$value instanceof ParserOutput ) {
            $this->incrementStats( $page, 'miss.unserialize' );
            return false;
        }
 
        if ( $this->checkExpired( $value, $page, $staleConstraint, 'output' ) ) {
            return false;
        }
 
        if ( $this->checkOutdated( $value, $page, $staleConstraint, 'output' ) ) {
            return false;
        }
 
        $wikiPage = $this->wikiPageFactory->newFromTitle( $page );
        if ( $this->hookRunner->onRejectParserCacheValue( $value, $wikiPage, $popts ) === false ) {
            $this->incrementStats( $page, 'miss.rejected' );
            $this->logger->debug( 'key valid, but rejected by RejectParserCacheValue hook handler',
                [ 'name' => $this->name ] );
            return false;
        }
 
        $this->logger->debug( 'ParserOutput cache found', [ 'name' => $this->name ] );
        $this->incrementStats( $page, 'hit' );
        return $value;
    }
 
    public function save(
        ParserOutput $parserOutput,
        PageRecord $page,
        $popts,
        $cacheTime = null,
        $revId = null
    ) {
        $page->assertWiki( PageRecord::LOCAL );
 
        if ( !$parserOutput->hasText() ) {
            throw new InvalidArgumentException( 'Attempt to cache a ParserOutput with no text set!' );
        }
 
        $expire = $parserOutput->getCacheExpiry();
 
        if ( !$popts->isSafeToCache( $parserOutput->getUsedOptions() ) ) {
            $this->logger->debug(
                'Parser options are not safe to cache and has not been saved',
                [ 'name' => $this->name ]
            );
            $this->incrementStats( $page, 'save.unsafe' );
            return;
        }
 
        if ( $expire <= 0 ) {
            $this->logger->debug(
                'Parser output was marked as uncacheable and has not been saved',
                [ 'name' => $this->name ]
            );
            $this->incrementStats( $page, 'save.uncacheable' );
            return;
        }
 
        if ( $this->cache instanceof EmptyBagOStuff ) {
            return;
        }
 
        $cacheTime = $cacheTime ?: wfTimestampNow();
        $revId = $revId ?: $page->getLatest( PageRecord::LOCAL );
 
        $metadata = new CacheTime;
        $metadata->recordOptions( $parserOutput->getUsedOptions() );
        $metadata->updateCacheExpiry( $expire );
 
        $metadata->setCacheTime( $cacheTime );
        $parserOutput->setCacheTime( $cacheTime );
        $metadata->setCacheRevisionId( $revId );
        $parserOutput->setCacheRevisionId( $revId );
 
        $parserOutputKey = $this->makeParserOutputKey(
            $page,
            $popts,
            $metadata->getUsedOptions()
        );
 
        $msg = "Saved in parser cache with key $parserOutputKey" .
            " and timestamp $cacheTime" .
            " and revision id $revId.";
        if ( $this->writeJson ) {
            $msg .= " Serialized with JSON.";
        } else {
            $msg .= " Serialized with PHP.";
        }
        $parserOutput->addCacheMessage( $msg );
 
        $pageKey = $this->makeMetadataKey( $page );
 
        if ( $this->writeJson ) {
            $parserOutputData = $this->encodeAsJson( $parserOutput, $parserOutputKey );
            $metadataData = $this->encodeAsJson( $metadata, $pageKey );
        } else {
            // rely on implicit PHP serialization in the cache
            $parserOutputData = $parserOutput;
            $metadataData = $metadata;
        }
 
        if ( !$parserOutputData || !$metadataData ) {
            $this->logger->warning(
                'Parser output failed to serialize and was not saved',
                [ 'name' => $this->name ]
            );
            $this->incrementStats( $page, 'save.nonserializable' );
            return;
        }
 
        // Save the parser output
        $this->cache->set(
            $parserOutputKey,
            $parserOutputData,
            $expire,
            BagOStuff::WRITE_ALLOW_SEGMENTS
        );
 
        // ...and its pointer to the local cache.
        $this->metadataProcCache->set( $pageKey, $metadataData, $expire );
        // ...and to the global cache.
        $this->cache->set( $pageKey, $metadataData, $expire );
 
        $title = $this->titleFactory->castFromPageIdentity( $page );
        $this->hookRunner->onParserCacheSaveComplete( $this, $parserOutput, $title, $popts, $revId );
 
        $this->logger->debug( 'Saved in parser cache', [
            'name' => $this->name,
            'key' => $parserOutputKey,
            'cache_time' => $cacheTime,
            'rev_id' => $revId
        ] );
        $this->incrementStats( $page, 'save.success' );
    }
 
    public function getCacheStorage() {
        return $this->cache;
    }
 
    private function checkExpired(
        CacheTime $entry,
        PageRecord $page,
        int $staleConstraint,
        string $cacheTier
    ): bool {
        if ( $staleConstraint < self::USE_EXPIRED && $entry->expired( $page->getTouched() ) ) {
            $this->incrementStats( $page, "miss.expired" );
            $this->logger->debug( "{$cacheTier} key expired", [
                'name' => $this->name,
                'touched' => $page->getTouched(),
                'epoch' => $this->cacheEpoch,
                'cache_time' => $entry->getCacheTime()
            ] );
            return true;
        }
        return false;
    }
 
    private function checkOutdated(
        CacheTime $entry,
        PageRecord $page,
        int $staleConstraint,
        string $cacheTier
    ): bool {
        $latestRevId = $page->getLatest( PageRecord::LOCAL );
        if ( $staleConstraint < self::USE_OUTDATED && $entry->isDifferentRevision( $latestRevId ) ) {
            $this->incrementStats( $page, "miss.revid" );
            $this->logger->debug( "{$cacheTier} key is for an old revision", [
                'name' => $this->name,
                'rev_id' => $latestRevId,
                'cached_rev_id' => $entry->getCacheRevisionId()
            ] );
            return true;
        }
        return false;
    }
 
    public function setJsonSupport( bool $readJson, bool $writeJson ): void {
        $this->readJson = $readJson;
        $this->writeJson = $writeJson;
    }
 
    private function restoreFromJson( string $jsonData, string $key, string $expectedClass ) {
        try {
            $obj = $this->jsonCodec->unserialize( $jsonData, $expectedClass );
            return $obj;
        } catch ( InvalidArgumentException $e ) {
            $this->logger->error( "Unable to unserialize JSON", [
                'name' => $this->name,
                'cache_key' => $key,
                'message' => $e->getMessage()
            ] );
            return null;
        }
    }
 
    private function encodeAsJson( CacheTime $obj, string $key ) {
        try {
            return $this->jsonCodec->serialize( $obj );
        } catch ( InvalidArgumentException $e ) {
            $this->logger->error( "Unable to serialize JSON", [
                'name' => $this->name,
                'cache_key' => $key,
                'message' => $e->getMessage(),
            ] );
            return null;
        }
    }
}