LinkCache.php

Go to the documentation of this file.

<?php
use MediaWiki\Linker\LinkTarget;
use MediaWiki\MediaWikiServices;
use MediaWiki\Page\PageIdentity;
use MediaWiki\Page\PageReference;
use MediaWiki\Page\PageStoreRecord;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Wikimedia\Rdbms\Database;
use Wikimedia\Rdbms\IDatabase;
use Wikimedia\Rdbms\ILoadBalancer;
 
class LinkCache implements LoggerAwareInterface {
    private $goodLinks;
    private $badLinks;
    private $wanCache;
 
    private $mForUpdate = false;
 
    private $titleFormatter;
 
    private $nsInfo;
 
    private $loadBalancer;
 
    private $logger;
 
    private const MAX_SIZE = 10000;
 
    public function __construct(
        TitleFormatter $titleFormatter,
        WANObjectCache $cache,
        NamespaceInfo $nsInfo = null,
        ILoadBalancer $loadBalancer = null
    ) {
        if ( !$nsInfo ) {
            wfDeprecated( __METHOD__ . ' with no NamespaceInfo argument', '1.34' );
            $nsInfo = MediaWikiServices::getInstance()->getNamespaceInfo();
        }
        $this->goodLinks = new MapCacheLRU( self::MAX_SIZE );
        $this->badLinks = new MapCacheLRU( self::MAX_SIZE );
        $this->wanCache = $cache;
        $this->titleFormatter = $titleFormatter;
        $this->nsInfo = $nsInfo;
        $this->loadBalancer = $loadBalancer;
        $this->logger = new NullLogger();
    }
 
    public function setLogger( LoggerInterface $logger ) {
        $this->logger = $logger;
    }
 
    public function forUpdate( $update = null ) {
        wfDeprecated( __METHOD__, '1.34' ); // hard deprecated since 1.37
        return wfSetVar( $this->mForUpdate, $update );
    }
 
    private function getCacheKey( $page, $passThrough = false ) {
        if ( is_string( $page ) ) {
            if ( $passThrough ) {
                return $page;
            } else {
                throw new InvalidArgumentException( 'They key may not be given as a string here' );
            }
        }
 
        if ( is_array( $page ) ) {
            $namespace = $page['page_namespace'];
            $dbkey = $page['page_title'];
            return strtr( $this->titleFormatter->formatTitle( $namespace, $dbkey ), ' ', '_' );
        }
 
        if ( $page instanceof PageReference && $page->getWikiId() !== PageReference::LOCAL ) {
            // No cross-wiki support yet. Perhaps LinkCache can become wiki-aware in the future.
            $this->logger->info(
                'cross-wiki page reference',
                [
                    'page-wiki' => $page->getWikiId(),
                    'page-reference' => $this->titleFormatter->getFullText( $page )
                ]
            );
            return null;
        }
 
        if ( $page instanceof PageIdentity && !$page->canExist() ) {
            // Non-proper page, perhaps a special page or interwiki link or relative section link.
            $this->logger->warning(
                'non-proper page reference: {page-reference}',
                [ 'page-reference' => $this->titleFormatter->getFullText( $page ) ]
            );
            return null;
        }
 
        if ( $page instanceof LinkTarget
            && ( $page->isExternal() || $page->getText() === '' || $page->getNamespace() < 0 )
        ) {
            // Interwiki link or relative section link. These do not have a page ID, so they
            // can neither be "good" nor "bad" in the sense of this class.
            $this->logger->warning(
                'link to non-proper page: {page-link}',
                [ 'page-link' => $this->titleFormatter->getFullText( $page ) ]
            );
            return null;
        }
 
        return $this->titleFormatter->getPrefixedDBkey( $page );
    }
 
    public function getGoodLinkID( $page ) {
        $key = $this->getCacheKey( $page, true );
 
        if ( $key === null ) {
            return 0;
        }
 
        [ $row ] = $this->goodLinks->get( $key );
 
        return $row ? (int)$row->page_id : 0;
    }
 
    public function getGoodLinkFieldObj( $page, string $field ) {
        $key = $this->getCacheKey( $page );
        if ( $key === null ) {
            return null;
        }
 
        if ( $this->isBadLink( $key ) ) {
            return null;
        }
 
        [ $row ] = $this->goodLinks->get( $key );
 
        if ( !$row ) {
            return null;
        }
 
        switch ( $field ) {
            case 'id':
                return intval( $row->page_id );
            case 'length':
                return intval( $row->page_len );
            case 'redirect':
                return intval( $row->page_is_redirect );
            case 'revision':
                return intval( $row->page_latest );
            case 'model':
                return !empty( $row->page_content_model )
                    ? strval( $row->page_content_model )
                    : null;
            case 'lang':
                return !empty( $row->page_lang )
                    ? strval( $row->page_lang )
                    : null;
            case 'restrictions':
                return !empty( $row->page_restrictions )
                    ? strval( $row->page_restrictions )
                    : null;
            default:
                throw new InvalidArgumentException( "Unknown field: $field" );
        }
    }
 
    public function isBadLink( $page ) {
        $key = $this->getCacheKey( $page, true );
        if ( $key === null ) {
            return false;
        }
 
        return $this->badLinks->has( $key );
    }
 
    public function addGoodLinkObj( $id, $page, $len = -1, $redir = null,
        $revision = 0, $model = null, $lang = null
    ) {
        wfDeprecated( __METHOD__, '1.38' );
        $this->addGoodLinkObjFromRow( $page, (object)[
            'page_id' => (int)$id,
            'page_namespace' => $page->getNamespace(),
            'page_title' => $page->getDBkey(),
            'page_len' => (int)$len,
            'page_is_redirect' => (int)$redir,
            'page_latest' => (int)$revision,
            'page_content_model' => $model ? (string)$model : null,
            'page_lang' => $lang ? (string)$lang : null,
            'page_restrictions' => null,
            'page_is_new' => 0,
            'page_touched' => '',
        ] );
    }
 
    public function addGoodLinkObjFromRow(
        $page,
        stdClass $row,
        int $queryFlags = IDBAccessObject::READ_NORMAL
    ) {
        foreach ( self::getSelectFields() as $field ) {
            if ( !property_exists( $row, $field ) ) {
                throw new InvalidArgumentException( "Missing field: $field" );
            }
        }
 
        $key = $this->getCacheKey( $page );
        if ( $key === null ) {
            return;
        }
 
        $this->goodLinks->set( $key, [ $row, $queryFlags ] );
        $this->badLinks->clear( $key );
    }
 
    public function addBadLinkObj( $page ) {
        $key = $this->getCacheKey( $page );
        if ( $key !== null && !$this->isBadLink( $key ) ) {
            $this->badLinks->set( $key, 1 );
            $this->goodLinks->clear( $key );
        }
    }
 
    public function clearBadLink( $page ) {
        $key = $this->getCacheKey( $page, true );
 
        if ( $key !== null ) {
            $this->badLinks->clear( $key );
        }
    }
 
    public function clearLink( $page ) {
        $key = $this->getCacheKey( $page );
 
        if ( $key !== null ) {
            $this->badLinks->clear( $key );
            $this->goodLinks->clear( $key );
        }
    }
 
    public static function getSelectFields() {
        $pageLanguageUseDB = MediaWikiServices::getInstance()->getMainConfig()->get( 'PageLanguageUseDB' );
 
        $fields = array_merge(
            PageStoreRecord::REQUIRED_FIELDS,
            [
                'page_len',
                'page_restrictions',
                'page_content_model',
            ]
        );
 
        if ( $pageLanguageUseDB ) {
            $fields[] = 'page_lang';
        }
 
        return $fields;
    }
 
    public function addLinkObj( $page, int $queryFlags = IDBAccessObject::READ_NORMAL ) {
        $row = $this->getGoodLinkRow(
            $page->getNamespace(),
            $page->getDBkey(),
            [ $this, 'fetchPageRow' ],
            $queryFlags
        );
 
        return $row ? (int)$row->page_id : 0;
    }
 
    private function getGoodLinkRowInternal(
        ?TitleValue $link,
        callable $fetchCallback = null,
        int $queryFlags = IDBAccessObject::READ_NORMAL
    ): array {
        $key = $link ? $this->getCacheKey( $link ) : null;
        if ( $key === null ) {
            return [ false, false ];
        }
 
        $ns = $link->getNamespace();
        $dbkey = $link->getDBkey();
        $callerShouldAddGoodLink = false;
 
        if ( $this->mForUpdate ) {
            $queryFlags |= IDBAccessObject::READ_LATEST;
        }
        $forUpdate = $queryFlags & IDBAccessObject::READ_LATEST;
 
        if ( !$forUpdate && $this->isBadLink( $key ) ) {
            return [ $callerShouldAddGoodLink, false ];
        }
 
        [ $row, $rowFlags ] = $this->goodLinks->get( $key );
        if ( $row && $rowFlags >= $queryFlags ) {
            return [ $callerShouldAddGoodLink, $row ];
        }
 
        if ( !$fetchCallback ) {
            return [ $callerShouldAddGoodLink, false ];
        }
 
        $callerShouldAddGoodLink = true;
        if ( $this->usePersistentCache( $ns ) && !$forUpdate ) {
            // Some pages are often transcluded heavily, so use persistent caching
            $wanCacheKey = $this->wanCache->makeKey( 'page', $ns, sha1( $dbkey ) );
 
            $row = $this->wanCache->getWithSetCallback(
                $wanCacheKey,
                WANObjectCache::TTL_DAY,
                function ( $curValue, &$ttl, array &$setOpts ) use ( $fetchCallback, $ns, $dbkey ) {
                    $dbr = $this->loadBalancer->getConnectionRef( ILoadBalancer::DB_REPLICA );
                    $setOpts += Database::getCacheSetOptions( $dbr );
 
                    $row = $fetchCallback( $dbr, $ns, $dbkey, [] );
                    $mtime = $row ? (int)wfTimestamp( TS_UNIX, $row->page_touched ) : false;
                    $ttl = $this->wanCache->adaptiveTTL( $mtime, $ttl );
 
                    return $row;
                }
            );
        } else {
            // No persistent caching needed, but we can still use the callback.
            [ $mode, $options ] = DBAccessObjectUtils::getDBOptions( $queryFlags );
            $dbr = $this->loadBalancer->getConnectionRef( $mode );
            $row = $fetchCallback( $dbr, $ns, $dbkey, $options );
        }
 
        return [ $callerShouldAddGoodLink, $row ];
    }
 
    public function getGoodLinkRow(
        int $ns,
        string $dbkey,
        callable $fetchCallback = null,
        int $queryFlags = IDBAccessObject::READ_NORMAL
    ): ?stdClass {
        $link = TitleValue::tryNew( $ns, $dbkey );
        if ( $link === null ) {
            return null;
        }
        [ $shouldAddGoodLink, $row ] = $this->getGoodLinkRowInternal(
            $link,
            $fetchCallback,
            $queryFlags
        );
 
        if ( $row ) {
            if ( $shouldAddGoodLink ) {
                try {
                    $this->addGoodLinkObjFromRow( $link, $row, $queryFlags );
                } catch ( InvalidArgumentException $e ) {
                    // a field is missing from $row; maybe we used a cache?; invalidate it and try again
                    $this->invalidateTitle( $link );
                    [ $shouldAddGoodLink, $row ] = $this->getGoodLinkRowInternal(
                        $link,
                        $fetchCallback,
                        $queryFlags
                    );
                    $this->addGoodLinkObjFromRow( $link, $row, $queryFlags );
                }
            }
        } else {
            $this->addBadLinkObj( $link );
        }
 
        return $row ?: null;
    }
 
    public function getMutableCacheKeys( WANObjectCache $cache, $page ) {
        $key = $this->getCacheKey( $page );
        // if no key can be derived, the page isn't cacheable
        if ( $key === null ) {
            return [];
        }
 
        if ( $this->usePersistentCache( $page ) ) {
            return [ $cache->makeKey( 'page', $page->getNamespace(), sha1( $page->getDBkey() ) ) ];
        }
 
        return [];
    }
 
    private function usePersistentCache( $pageOrNamespace ) {
        $ns = is_int( $pageOrNamespace ) ? $pageOrNamespace : $pageOrNamespace->getNamespace();
        if ( in_array( $ns, [ NS_TEMPLATE, NS_FILE, NS_CATEGORY, NS_MEDIAWIKI ] ) ) {
            return true;
        }
        // Focus on transcluded pages more than the main content
        if ( $this->nsInfo->isContent( $ns ) ) {
            return false;
        }
        // Non-talk extension namespaces (e.g. NS_MODULE)
        return ( $ns >= 100 && $this->nsInfo->isSubject( $ns ) );
    }
 
    private function fetchPageRow( IDatabase $db, int $ns, string $dbkey, $options = [] ) {
        $fields = self::getSelectFields();
        if ( $this->usePersistentCache( $ns ) ) {
            $fields[] = 'page_touched';
        }
 
        return $db->selectRow(
            'page',
            $fields,
            [ 'page_namespace' => $ns, 'page_title' => $dbkey ],
            __METHOD__,
            $options
        );
    }
 
    public function invalidateTitle( $page ) {
        if ( $this->usePersistentCache( $page ) ) {
            $cache = $this->wanCache;
            $cache->delete(
                $cache->makeKey( 'page', $page->getNamespace(), sha1( $page->getDBkey() ) )
            );
        }
 
        $this->clearLink( $page );
    }
 
    public function clear() {
        $this->goodLinks->clear();
        $this->badLinks->clear();
    }
 
}