LinkCache.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Page;
 
use InvalidArgumentException;
use MediaWiki\MainConfigNames;
use MediaWiki\MediaWikiServices;
use MediaWiki\Title\NamespaceInfo;
use MediaWiki\Title\Title;
use MediaWiki\Title\TitleFormatter;
use MediaWiki\Title\TitleValue;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use stdClass;
use Wikimedia\MapCacheLRU\MapCacheLRU;
use Wikimedia\ObjectCache\WANObjectCache;
use Wikimedia\Parsoid\Core\LinkTarget;
use Wikimedia\Rdbms\Database;
use Wikimedia\Rdbms\IDBAccessObject;
use Wikimedia\Rdbms\ILoadBalancer;
use Wikimedia\Rdbms\IReadableDatabase;
use Wikimedia\Timestamp\TimestampFormat as TS;
 
class LinkCache implements LoggerAwareInterface {
    private $entries;
    private $wanCache;
    private $titleFormatter;
    private $nsInfo;
    private $loadBalancer;
    private $logger;
 
    private const MAX_SIZE = 10000;
 
    private const ROW = 0;
    private const FLAGS = 1;
 
    public function __construct(
        TitleFormatter $titleFormatter,
        WANObjectCache $cache,
        NamespaceInfo $nsInfo,
        ?ILoadBalancer $loadBalancer = null
    ) {
        $this->entries = 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 ): void {
        $this->logger = $logger;
    }
 
    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;
        }
 
        $entry = $this->entries->get( $key );
        if ( !$entry ) {
            return 0;
        }
 
        $row = $entry[self::ROW];
 
        return $row ? (int)$row->page_id : 0;
    }
 
    public function getGoodLinkFieldObj( $page, string $field ) {
        $key = $this->getCacheKey( $page );
        if ( $key === null ) {
            return null;
        }
 
        $entry = $this->entries->get( $key );
        if ( !$entry ) {
            return null;
        }
 
        $row = $entry[self::ROW];
        if ( !$row ) {
            return null;
        }
 
        switch ( $field ) {
            case 'id':
                return (int)$row->page_id;
            case 'length':
                return (int)$row->page_len;
            case 'redirect':
                return (int)$row->page_is_redirect;
            case 'revision':
                return (int)$row->page_latest;
            case 'model':
                return !empty( $row->page_content_model )
                    ? (string)$row->page_content_model
                    : null;
            case 'lang':
                return !empty( $row->page_lang )
                    ? (string)$row->page_lang
                    : null;
            default:
                throw new InvalidArgumentException( "Unknown field: $field" );
        }
    }
 
    public function isBadLink( $page ) {
        $key = $this->getCacheKey( $page, true );
        if ( $key === null ) {
            return false;
        }
 
        $entry = $this->entries->get( $key );
 
        return ( $entry && !$entry[self::ROW] );
    }
 
    public function addGoodLinkObjFromRow(
        $page,
        stdClass $row,
        int $queryFlags = IDBAccessObject::READ_NORMAL
    ) {
        $key = $this->getCacheKey( $page );
        if ( $key === null ) {
            return;
        }
 
        foreach ( self::getSelectFields() as $field ) {
            if ( !property_exists( $row, $field ) ) {
                throw new InvalidArgumentException( "Missing field: $field" );
            }
        }
 
        $this->entries->set( $key, [ self::ROW => $row, self::FLAGS => $queryFlags ] );
    }
 
    public function addBadLinkObj( $page, int $queryFlags = IDBAccessObject::READ_NORMAL ) {
        $key = $this->getCacheKey( $page );
        if ( $key === null ) {
            return;
        }
 
        $this->entries->set( $key, [ self::ROW => null, self::FLAGS => $queryFlags ] );
    }
 
    public function clearBadLink( $page ) {
        $key = $this->getCacheKey( $page, true );
        if ( $key === null ) {
            return;
        }
 
        $entry = $this->entries->get( $key );
        if ( $entry && !$entry[self::ROW] ) {
            $this->entries->clear( $key );
        }
    }
 
    public function clearLink( $page ) {
        $key = $this->getCacheKey( $page );
        if ( $key !== null ) {
            $this->entries->clear( $key );
        }
    }
 
    public static function getSelectFields() {
        $pageLanguageUseDB = MediaWikiServices::getInstance()->getMainConfig()
            ->get( MainConfigNames::PageLanguageUseDB );
 
        $fields = array_merge(
            PageStoreRecord::REQUIRED_FIELDS,
            [
                'page_len',
                '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 {
        $callerShouldAddGoodLink = false;
 
        $key = $this->getCacheKey( $link );
        if ( $key === null ) {
            return [ $callerShouldAddGoodLink, null ];
        }
 
        $ns = $link->getNamespace();
        $dbkey = $link->getDBkey();
 
        $entry = $this->entries->get( $key );
        if ( $entry && $entry[self::FLAGS] >= $queryFlags ) {
            return [ $callerShouldAddGoodLink, $entry[self::ROW] ?: null ];
        }
 
        if ( !$fetchCallback ) {
            return [ $callerShouldAddGoodLink, null ];
        }
 
        $callerShouldAddGoodLink = true;
 
        $wanCacheKey = $this->getPersistentCacheKey( $link );
        if ( $wanCacheKey !== null && !( $queryFlags & IDBAccessObject::READ_LATEST ) ) {
            // Some pages are often transcluded heavily, so use persistent caching
            $row = $this->wanCache->getWithSetCallback(
                $wanCacheKey,
                WANObjectCache::TTL_DAY,
                function ( $curValue, &$ttl, array &$setOpts ) use ( $fetchCallback, $ns, $dbkey ) {
                    $dbr = $this->loadBalancer->getConnection( 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.
            if ( ( $queryFlags & IDBAccessObject::READ_LATEST ) == IDBAccessObject::READ_LATEST ) {
                $dbr = $this->loadBalancer->getConnection( DB_PRIMARY );
            } else {
                $dbr = $this->loadBalancer->getConnection( DB_REPLICA );
            }
            $options = [];
            if ( ( $queryFlags & IDBAccessObject::READ_EXCLUSIVE ) == IDBAccessObject::READ_EXCLUSIVE ) {
                $options[] = 'FOR UPDATE';
            } elseif ( ( $queryFlags & IDBAccessObject::READ_LOCKING ) == IDBAccessObject::READ_LOCKING ) {
                $options[] = 'LOCK IN SHARE MODE';
            }
            $row = $fetchCallback( $dbr, $ns, $dbkey, $options );
        }
 
        return [ $callerShouldAddGoodLink, $row ?: null ];
    }
 
    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 ) {
                    // a field is missing from $row; maybe we used a cache?; invalidate it and try again
                    $this->invalidateTitle( $link );
                    [ , $row ] = $this->getGoodLinkRowInternal(
                        $link,
                        $fetchCallback,
                        $queryFlags
                    );
                    $this->addGoodLinkObjFromRow( $link, $row, $queryFlags );
                }
            }
        } else {
            $this->addBadLinkObj( $link );
        }
 
        return $row ?: null;
    }
 
    private function getPersistentCacheKey( $page ) {
        // if no key can be derived, the page isn't cacheable
        if ( $this->getCacheKey( $page ) === null || !$this->usePersistentCache( $page ) ) {
            return null;
        }
        return $this->wanCache->makeKey( 'page', $page->getNamespace(), sha1( $page->getDBkey() ) );
    }
 
    private function usePersistentCache( $pageOrNamespace ) {
        $ns = is_int( $pageOrNamespace ) ? $pageOrNamespace : $pageOrNamespace->getNamespace();
 
        if ( in_array( $ns, [ NS_TEMPLATE, NS_FILE, NS_CATEGORY, NS_MEDIAWIKI ] ) ||
            ( !is_int( $pageOrNamespace ) &&
                ( str_ends_with( $pageOrNamespace->getDBkey(), '.css' ) ||
                    str_ends_with( $pageOrNamespace->getDBkey(), '.js' ) ) ) ) {
            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( IReadableDatabase $db, int $ns, string $dbkey, $options = [] ) {
        $queryBuilder = $db->newSelectQueryBuilder()
            ->select( self::getSelectFields() )
            ->from( 'page' )
            ->where( [ 'page_namespace' => $ns, 'page_title' => $dbkey ] )
            ->options( $options );
 
        return $queryBuilder->caller( __METHOD__ )->fetchRow();
    }
 
    public function executeBatch( array $pages, $fname ) {
        $pageObject = [];
        $result = [];
 
        foreach ( $pages as $page ) {
            $title = Title::newFromText( $page );
            if ( $title ) {
                $cacheKey = $this->getPersistentCacheKey( $title );
                $pageObject[$cacheKey] = $title;
            }
        }
 
        $rows = $this->wanCache->getMulti( array_keys( $pageObject ) );
        foreach ( $rows as $key => $row ) {
            if ( $row ) {
                $title = TitleValue::tryNew( (int)$row->page_namespace, $row->page_title );
                $this->addGoodLinkObjFromRow( $title, $row );
            } else {
                $this->addBadLinkObj( $pageObject[$key] );
            }
            unset( $pageObject[$key] );
        }
 
        $linkBatchFactory = MediaWikiServices::getInstance()->getLinkBatchFactory();
 
        if ( count( $pageObject ) > 0 ) {
            $linkBatch = $linkBatchFactory->newLinkBatch( array_values( $pageObject ) );
            $linkBatch->setCaller( $fname );
            $result = $linkBatch->doQuery();
            $linkBatch->doGenderQuery();
        }
 
        foreach ( $result as $row ) {
            $title = TitleValue::tryNew( (int)$row->page_namespace, $row->page_title );
            $cacheKey = $this->getPersistentCacheKey( $title );
            $this->addGoodLinkObjFromRow( $title, $row );
            $pageObject[$cacheKey] = $row;
        }
 
        foreach ( $pageObject as $key => $row ) {
            if ( !$row instanceof Title ) {
                $this->wanCache->set( $key, $row, WANObjectCache::TTL_DAY );
            } else {
                $this->wanCache->set( $key, null, WANObjectCache::TTL_DAY );
                $this->addBadLinkObj( $row );
            }
        }
    }
 
    public function invalidateTitle( $page ) {
        // for use by ResourceLoader Wikimodule
        $wanCacheKey = $this->getPersistentCacheKey( $page );
        if ( $wanCacheKey !== null ) {
            $this->wanCache->delete( $wanCacheKey );
        }
 
        $this->clearLink( $page );
    }
 
    public function clear() {
        $this->entries->clear();
    }
}
 
class_alias( LinkCache::class, 'LinkCache' );
 
class_alias( LinkCache::class, 'MediaWiki\Cache\LinkCache' );