ParserCache.php

Go to the documentation of this file.

<?php
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\HookContainer\HookRunner;
use MediaWiki\Json\JsonCodec;
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 $writeJson = false;
 
    private $readJson = false;
 
    public function __construct(
        string $name,
        BagOStuff $cache,
        string $cacheEpoch,
        HookContainer $hookContainer,
        JsonCodec $jsonCodec,
        IBufferingStatsdDataFactory $stats,
        LoggerInterface $logger,
        $useJson = false
    ) {
        if ( !$cache instanceof EmptyBagOStuff && !$cache instanceof CachedBagOStuff ) {
            $cache = new CachedBagOStuff( $cache, [
                // Each ParserCache entry uses 2 keys, one for metadata and one for parser output.
                // So, cache at most 4 different parser outputs in memory. The number was chosen ad hoc.
                'maxKeys' => 8
            ] );
        }
        $this->name = $name;
        $this->cache = $cache;
        $this->cacheEpoch = $cacheEpoch;
        $this->hookRunner = new HookRunner( $hookContainer );
        $this->jsonCodec = $jsonCodec;
        $this->stats = $stats;
        $this->logger = $logger;
        $this->readJson = $useJson;
        $this->writeJson = $useJson;
    }
 
    public function deleteOptionsKey( WikiPage $wikiPage ) {
        $this->cache->delete( $this->makeMetadataKey( $wikiPage ) );
    }
 
    public function getETag( WikiPage $wikiPage, $popts ) {
        wfDeprecated( __METHOD__, '1.36' );
        return 'W/"' . $this->makeParserOutputKey( $wikiPage, $popts )
            . "--" . $wikiPage->getTouched() . '"';
    }
 
    public function getDirty( WikiPage $wikiPage, $popts ) {
        $value = $this->get( $wikiPage, $popts, true );
        return is_object( $value ) ? $value : false;
    }
 
    private function incrementStats( WikiPage $wikiPage, $metricSuffix ) {
        $contentModel = str_replace( '.', '_', $wikiPage->getContentModel() );
        $metricSuffix = str_replace( '.', '_', $metricSuffix );
        $this->stats->increment( "{$this->name}.{$contentModel}.{$metricSuffix}" );
    }
 
    public function getKey( WikiPage $wikiPage, $popts, $useOutdated = self::USE_ANYTHING ) {
        wfDeprecated( __METHOD__, '1.36' );
        if ( is_bool( $useOutdated ) ) {
            $useOutdated = $useOutdated ? self::USE_ANYTHING : self::USE_CURRENT_ONLY;
        }
 
        if ( $popts instanceof User ) {
            $this->logger->warning(
                "Use of outdated prototype ParserCache::getKey( &\$wikiPage, &\$user )\n"
            );
            $popts = ParserOptions::newFromUser( $popts );
        }
 
        $metadata = $this->getMetadata( $wikiPage, $useOutdated );
        if ( !$metadata ) {
            if ( $useOutdated < self::USE_ANYTHING ) {
                return false;
            }
            $usedOptions = ParserOptions::allCacheVaryingOptions();
        } else {
            $usedOptions = $metadata->getUsedOptions();
        }
 
        return $this->makeParserOutputKey( $wikiPage, $popts, $usedOptions );
    }
 
    public function getMetadata(
        WikiPage $wikiPage,
        int $staleConstraint = self::USE_ANYTHING
    ): ?ParserCacheMetadata {
        $pageKey = $this->makeMetadataKey( $wikiPage );
        $metadata = $this->cache->get(
            $pageKey,
            BagOStuff::READ_VERIFIED
        );
 
        // 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( $wikiPage, 'miss.unserialize' );
            return null;
        }
 
        if ( $this->checkExpired( $metadata, $wikiPage, $staleConstraint, 'metadata' ) ) {
            return null;
        }
 
        if ( $this->checkOutdated( $metadata, $wikiPage, $staleConstraint, 'metadata' ) ) {
            return null;
        }
 
        $this->logger->debug( 'Parser cache options found', [ 'name' => $this->name ] );
        return $metadata;
    }
 
    private function makeMetadataKey( WikiPage $wikiPage ): string {
        return $this->cache->makeKey( $this->name, 'idoptions', $wikiPage->getId() );
    }
 
    public function makeParserOutputKey(
        WikiPage $wikiPage,
        ParserOptions $options,
        array $usedOptions = null
    ): string {
        global $wgRequest;
        $usedOptions = $usedOptions ?? ParserOptions::allCacheVaryingOptions();
 
        // idhash seem to mean 'page id' + 'rendering hash' (r3710)
        $pageid = $wikiPage->getId();
        // TODO: remove the split T263581
        $renderkey = (int)( $wgRequest->getVal( 'action' ) == 'render' );
        $hash = $options->optionsHash( $usedOptions, $wikiPage->getTitle() );
 
        return $this->cache->makeKey( $this->name, 'idhash', "{$pageid}-{$renderkey}!{$hash}" );
    }
 
    public function get( WikiPage $wikiPage, $popts, $useOutdated = false ) {
        if ( !$wikiPage->checkTouched() ) {
            // It's a redirect now
            $this->incrementStats( $wikiPage, 'miss.redirect' );
            return false;
        }
 
        $staleConstraint = $useOutdated ? self::USE_OUTDATED : self::USE_CURRENT_ONLY;
        $parserOutputMetadata = $this->getMetadata( $wikiPage, $staleConstraint );
        if ( !$parserOutputMetadata ) {
            return false;
        }
 
        if ( !$popts->isSafeToCache( $parserOutputMetadata->getUsedOptions() ) ) {
            $this->incrementStats( $wikiPage, 'miss.unsafe' );
            return false;
        }
 
        $parserOutputKey = $this->makeParserOutputKey(
            $wikiPage,
            $popts,
            $parserOutputMetadata->getUsedOptions()
        );
 
        $value = $this->cache->get( $parserOutputKey, BagOStuff::READ_VERIFIED );
        if ( $value === false ) {
            $this->incrementStats( $wikiPage, "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( $wikiPage, 'miss.unserialize' );
            return false;
        }
 
        if ( $this->checkExpired( $value, $wikiPage, $staleConstraint, 'output' ) ) {
            return false;
        }
 
        if ( $this->checkOutdated( $value, $wikiPage, $staleConstraint, 'output' ) ) {
            return false;
        }
 
        if ( $this->hookRunner->onRejectParserCacheValue( $value, $wikiPage, $popts ) === false ) {
            $this->incrementStats( $wikiPage, '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( $wikiPage, 'hit' );
        return $value;
    }
 
    public function save(
        ParserOutput $parserOutput,
        WikiPage $wikiPage,
        $popts,
        $cacheTime = null,
        $revId = null
    ) {
        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( $wikiPage, '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( $wikiPage, 'save.uncacheable' );
            return;
        }
 
        if ( $this->cache instanceof EmptyBagOStuff ) {
            return;
        }
 
        $cacheTime = $cacheTime ?: wfTimestampNow();
        if ( !$revId ) {
            $revision = $wikiPage->getRevisionRecord();
            $revId = $revision ? $revision->getId() : null;
        }
 
        $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(
            $wikiPage,
            $popts,
            $metadata->getUsedOptions()
        );
 
        // Save the timestamp so that we don't have to load the revision row on view
        $parserOutput->setTimestamp( $wikiPage->getTimestamp() );
 
        $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( $wikiPage );
 
        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( $wikiPage, 'save.nonserializable' );
            return;
        }
 
        // Save the parser output
        $this->cache->set(
            $parserOutputKey,
            $parserOutputData,
            $expire,
            BagOStuff::WRITE_ALLOW_SEGMENTS
        );
 
        // ...and its pointer
        $this->cache->set( $pageKey, $metadataData, $expire );
 
        $this->hookRunner->onParserCacheSaveComplete(
            $this, $parserOutput, $wikiPage->getTitle(), $popts, $revId );
 
        $this->logger->debug( 'Saved in parser cache', [
            'name' => $this->name,
            'key' => $parserOutputKey,
            'cache_time' => $cacheTime,
            'rev_id' => $revId
        ] );
        $this->incrementStats( $wikiPage, 'save.success' );
    }
 
    public function getCacheStorage() {
        return $this->cache;
    }
 
    private function checkExpired(
        CacheTime $entry,
        WikiPage $wikiPage,
        int $staleConstraint,
        string $cacheTier
    ): bool {
        if ( $staleConstraint < self::USE_EXPIRED && $entry->expired( $wikiPage->getTouched() ) ) {
            $this->incrementStats( $wikiPage, "miss.expired" );
            $this->logger->debug( "{$cacheTier} key expired", [
                'name' => $this->name,
                'touched' => $wikiPage->getTouched(),
                'epoch' => $this->cacheEpoch,
                'cache_time' => $entry->getCacheTime()
            ] );
            return true;
        }
        return false;
    }
 
    private function checkOutdated(
        CacheTime $entry,
        WikiPage $wikiPage,
        int $staleConstraint,
        string $cacheTier
    ): bool {
        $latestRevId = $wikiPage->getLatest();
        if ( $staleConstraint < self::USE_OUTDATED && $entry->isDifferentRevision( $latestRevId ) ) {
            $this->incrementStats( $wikiPage, "miss.revid" );
            $this->logger->debug( "{$cacheTier} key is for an old revision", [
                'name' => $this->name,
                'rev_id' => $wikiPage->getLatest(),
                '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;
        }
    }
}