Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
71.83% covered (warning)
71.83%
102 / 142
62.07% covered (warning)
62.07%
18 / 29
CRAP
0.00% covered (danger)
0.00%
0 / 1
LinksUpdate
71.83% covered (warning)
71.83%
102 / 142
62.07% covered (warning)
62.07%
18 / 29
90.26
0.00% covered (danger)
0.00%
0 / 1
 __construct
100.00% covered (success)
100.00%
19 / 19
100.00% covered (success)
100.00%
1 / 1
1
 setTransactionTicket
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
1
 setMoveDetails
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 doUpdate
62.07% covered (warning)
62.07%
18 / 29
0.00% covered (danger)
0.00%
0 / 1
7.96
 acquirePageLock
45.45% covered (danger)
45.45%
5 / 11
0.00% covered (danger)
0.00%
0 / 1
2.65
 doIncrementalUpdate
100.00% covered (success)
100.00%
5 / 5
100.00% covered (success)
100.00%
1 / 1
3
 queueRecursiveJobs
54.55% covered (warning)
54.55%
12 / 22
0.00% covered (danger)
0.00%
0 / 1
5.50
 queueRecursiveJobsForTable
81.25% covered (warning)
81.25%
13 / 16
0.00% covered (danger)
0.00%
0 / 1
3.06
 setStrictTestMode
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 getTitle
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 getPageId
0.00% covered (danger)
0.00%
0 / 3
0.00% covered (danger)
0.00%
0 / 1
6
 getParserOutput
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 setRevisionRecord
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
1
 getRevisionRecord
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 setTriggeringUser
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 getTriggeringUser
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 getPageLinksTable
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 getExternalLinksTable
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 getPagePropsTable
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 getAddedExternalLinks
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 getRemovedExternalLinks
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 getAddedProperties
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 getRemovedProperties
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 getPageReferenceIterator
60.00% covered (warning)
60.00%
3 / 5
0.00% covered (danger)
0.00%
0 / 1
2.26
 getPageReferenceArray
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 updateLinksTimestamp
100.00% covered (success)
100.00%
9 / 9
100.00% covered (success)
100.00%
1 / 1
2
 getDB
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
1
 isRecursive
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 getTransactionRoundRequirement
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
1<?php
2/**
3 * Updater for link tracking tables after a page edit.
4 *
5 * @license GPL-2.0-or-later
6 * @file
7 */
8
9namespace MediaWiki\Deferred\LinksUpdate;
10
11use InvalidArgumentException;
12use MediaWiki\Cache\BacklinkCache;
13use MediaWiki\DB\WriteDuplicator;
14use MediaWiki\Deferred\AutoCommitUpdate;
15use MediaWiki\Deferred\DataUpdate;
16use MediaWiki\Deferred\DeferredUpdates;
17use MediaWiki\Deferred\TransactionRoundAwareUpdate;
18use MediaWiki\HookContainer\ProtectedHookAccessorTrait;
19use MediaWiki\JobQueue\Job;
20use MediaWiki\JobQueue\Jobs\RefreshLinksJob;
21use MediaWiki\Logger\LoggerFactory;
22use MediaWiki\MainConfigNames;
23use MediaWiki\MediaWikiServices;
24use MediaWiki\Page\PageIdentity;
25use MediaWiki\Page\PageReference;
26use MediaWiki\Page\PageReferenceValue;
27use MediaWiki\Parser\ParserOutput;
28use MediaWiki\Revision\RevisionRecord;
29use MediaWiki\Title\Title;
30use MediaWiki\User\UserIdentity;
31use RuntimeException;
32use Wikimedia\Rdbms\IConnectionProvider;
33use Wikimedia\Rdbms\IDatabase;
34use Wikimedia\Rdbms\IDBAccessObject;
35use Wikimedia\ScopedCallback;
36
37/**
38 * Class the manages updates of *_link tables as well as similar extension-managed tables
39 *
40 * @note LinksUpdate is managed by DeferredUpdates::execute(). Do not run this in a transaction.
41 *
42 * See docs/deferred.txt
43 */
44class LinksUpdate extends DataUpdate implements TransactionRoundAwareUpdate {
45    use ProtectedHookAccessorTrait;
46
47    /** @var int Page ID of the article linked from */
48    protected $mId;
49
50    /** @var Title Title object of the article linked from */
51    protected $mTitle;
52
53    /** @var ParserOutput */
54    protected $mParserOutput;
55
56    /** @var bool Whether to queue jobs for recursive updates */
57    protected $mRecursive;
58
59    /** @var bool Whether the page's redirect target may have changed in the latest revision */
60    protected $mMaybeRedirectChanged;
61
62    /** @var RevisionRecord Revision for which this update has been triggered */
63    private $mRevisionRecord;
64
65    /**
66     * @var UserIdentity|null
67     */
68    private $user;
69
70    /** @var IDatabase */
71    private $db;
72
73    /** @var LinksTableGroup */
74    private $tableFactory;
75
76    private IConnectionProvider $dbProvider;
77    private WriteDuplicator $linkWriteDuplicator;
78
79    /**
80     * @param PageIdentity $page The page we're updating
81     * @param ParserOutput $parserOutput Output from a full parse of this page
82     * @param bool $recursive Queue jobs for recursive updates?
83     * @param bool $maybeRedirectChanged True if the page's redirect target may have changed in the
84     *   latest revision. If false, this is used as a hint to skip some unnecessary updates.
85     */
86    public function __construct(
87        PageIdentity $page,
88        ParserOutput $parserOutput,
89        $recursive = true,
90        $maybeRedirectChanged = true
91    ) {
92        parent::__construct();
93
94        $this->mTitle = Title::newFromPageIdentity( $page );
95        $this->mParserOutput = $parserOutput;
96        $this->mRecursive = $recursive;
97        $this->mMaybeRedirectChanged = $maybeRedirectChanged;
98
99        $services = MediaWikiServices::getInstance();
100        $config = $services->getMainConfig();
101        $this->tableFactory = new LinksTableGroup(
102            $services->getObjectFactory(),
103            $services->getDBLoadBalancerFactory(),
104            $services->getCollationFactory(),
105            $page,
106            $services->getLinkTargetLookup(),
107            $config->get( MainConfigNames::UpdateRowsPerQuery ),
108            $config->get( MainConfigNames::TempCategoryCollations )
109        );
110        // TODO: this does not have to be called in LinksDeletionUpdate
111        $this->tableFactory->setParserOutput( $parserOutput );
112        $this->dbProvider = $services->getDBLoadBalancerFactory();
113        $this->linkWriteDuplicator = $services->getLinkWriteDuplicator();
114    }
115
116    /** @inheritDoc */
117    public function setTransactionTicket( $ticket ) {
118        parent::setTransactionTicket( $ticket );
119        $this->tableFactory->setTransactionTicket( $ticket );
120    }
121
122    /**
123     * Notify LinksUpdate that a move has just been completed and set the
124     * original title
125     */
126    public function setMoveDetails( PageReference $oldPage ) {
127        $this->tableFactory->setMoveDetails( $oldPage );
128    }
129
130    /**
131     * Update link tables with outgoing links from an updated article
132     *
133     * @note this is managed by DeferredUpdates::execute(). Do not run this in a transaction.
134     */
135    public function doUpdate() {
136        if ( !$this->mId ) {
137            // NOTE: subclasses may initialize mId directly!
138            $this->mId = $this->mTitle->getArticleID( IDBAccessObject::READ_LATEST );
139        }
140
141        if ( !$this->mId ) {
142            // Probably due to concurrent deletion or renaming of the page
143            $logger = LoggerFactory::getInstance( 'SecondaryDataUpdate' );
144            $logger->warning(
145                'LinksUpdate: The Title object yields no ID. Perhaps the page was deleted?',
146                [
147                    'page_title' => $this->mTitle->getPrefixedDBkey(),
148                    'cause_action' => $this->getCauseAction(),
149                    'cause_agent' => $this->getCauseAgent()
150                ]
151            );
152
153            // nothing to do
154            return;
155        }
156
157        // Do any setup that needs to be done prior to acquiring the lock
158        // Calling getAll() here has the side-effect of calling
159        // LinksUpdateBatch::setParserOutput() on all subclasses, allowing
160        // those methods to also do pre-lock operations.
161        foreach ( $this->tableFactory->getAll() as $table ) {
162            $table->beforeLock();
163        }
164
165        if ( $this->ticket ) {
166            // Make sure all links update threads see the changes of each other.
167            // This handles the case when updates have to batched into several COMMITs.
168            $scopedLock = self::acquirePageLock( $this->mId );
169            if ( !$scopedLock ) {
170                throw new RuntimeException( "Could not acquire lock for page ID '{$this->mId}'." );
171            }
172        }
173
174        $this->getHookRunner()->onLinksUpdate( $this );
175        $this->doIncrementalUpdate();
176
177        // Commit and release the lock (if set)
178        ScopedCallback::consume( $scopedLock );
179        // Run post-commit hook handlers without DBO_TRX
180        DeferredUpdates::addUpdate( new AutoCommitUpdate(
181            $this->getDB(),
182            __METHOD__,
183            function () {
184                $this->getHookRunner()->onLinksUpdateComplete( $this, $this->ticket );
185            }
186        ) );
187    }
188
189    /**
190     * Acquire a session-level lock for performing link table updates for a page on a DB
191     *
192     * @param int $pageId
193     * @param string $why One of (job, atomicity)
194     * @internal
195     */
196    #[\NoDiscard]
197    public static function acquirePageLock( $pageId, $why = 'atomicity' ): ?ScopedCallback {
198        $key = "LinksUpdate:$why:pageid:$pageId";
199        $lockManager = MediaWikiServices::getInstance()->getLockManager();
200        $unlocker = $lockManager->scopedLock( $key, 1 );
201        if ( !$unlocker ) {
202            $logger = LoggerFactory::getInstance( 'SecondaryDataUpdate' );
203            $logger->info( "Could not acquire lock '{key}' for page ID '{page_id}'.", [
204                'key' => $key,
205                'page_id' => $pageId,
206            ] );
207            return null;
208        }
209        return $unlocker;
210    }
211
212    protected function doIncrementalUpdate() {
213        foreach ( $this->tableFactory->getAll() as $table ) {
214            $table->update();
215        }
216
217        # Refresh links of all pages including this page
218        # This will be in a separate transaction
219        if ( $this->mRecursive ) {
220            $this->queueRecursiveJobs();
221        }
222
223        # Update the links table freshness for this title
224        $this->updateLinksTimestamp();
225    }
226
227    /**
228     * Queue recursive jobs for this page
229     *
230     * Which means do LinksUpdate on all pages that include the current page,
231     * using the job queue.
232     */
233    protected function queueRecursiveJobs() {
234        $services = MediaWikiServices::getInstance();
235        $backlinkCache = $services->getBacklinkCacheFactory()
236            ->getBacklinkCache( $this->mTitle );
237        $action = $this->getCauseAction();
238        $agent = $this->getCauseAgent();
239
240        self::queueRecursiveJobsForTable(
241            $this->mTitle, 'templatelinks', $action, $agent, $backlinkCache
242        );
243        if ( $this->mMaybeRedirectChanged && $this->mTitle->getNamespace() === NS_FILE ) {
244            // Process imagelinks in case the redirect target has changed
245            self::queueRecursiveJobsForTable(
246                $this->mTitle, 'imagelinks', $action, $agent, $backlinkCache
247            );
248        }
249
250        // Get jobs for cascade-protected backlinks for a high priority queue.
251        // If meta-templates change to using a new template, the new template
252        // should be implicitly protected as soon as possible, if applicable.
253        // These jobs duplicate a subset of the above ones, but can run sooner.
254        // Which ever runs first generally no-ops the other one.
255        $jobs = [];
256        foreach ( $backlinkCache->getCascadeProtectedLinkPages() as $page ) {
257            $jobs[] = RefreshLinksJob::newPrioritized(
258                $page,
259                [
260                    'causeAction' => $action,
261                    'causeAgent' => $agent
262                ]
263            );
264        }
265        $services->getJobQueueGroup()->push( $jobs );
266    }
267
268    /**
269     * Queue a RefreshLinks job for any table.
270     *
271     * @param PageIdentity $page Page to do job for
272     * @param string $table Table to use (e.g. 'templatelinks')
273     * @param string $action Triggering action
274     * @param string $userName Triggering user name
275     * @param BacklinkCache|null $backlinkCache
276     */
277    public static function queueRecursiveJobsForTable(
278        PageIdentity $page, $table, $action = 'LinksUpdate', $userName = 'unknown', ?BacklinkCache $backlinkCache = null
279    ) {
280        $title = Title::newFromPageIdentity( $page );
281        if ( !$backlinkCache ) {
282            wfDeprecatedMsg( __METHOD__ . " needs a BacklinkCache object, null passed", '1.37' );
283            $backlinkCache = MediaWikiServices::getInstance()->getBacklinkCacheFactory()
284                ->getBacklinkCache( $title );
285        }
286        if ( $backlinkCache->hasLinks( $table ) ) {
287            $job = new RefreshLinksJob(
288                $title,
289                [
290                    'table' => $table,
291                    'recursive' => true,
292                ] + Job::newRootJobParams( // "overall" refresh links job info
293                    "refreshlinks:{$table}:{$title->getPrefixedText()}"
294                ) + [ 'causeAction' => $action, 'causeAgent' => $userName ]
295            );
296
297            MediaWikiServices::getInstance()->getJobQueueGroup()->push( $job );
298        }
299    }
300
301    /**
302     * Omit conflict resolution options from the insert query so that testing
303     * can confirm that the incremental update logic was correct.
304     *
305     * @param bool $mode
306     */
307    public function setStrictTestMode( $mode = true ) {
308        $this->tableFactory->setStrictTestMode( $mode );
309    }
310
311    /**
312     * Return the title object of the page being updated
313     * @return Title
314     */
315    public function getTitle() {
316        return $this->mTitle;
317    }
318
319    /**
320     * Get the page_id of the page being updated
321     *
322     * @since 1.38
323     * @return int
324     */
325    public function getPageId() {
326        if ( $this->mId ) {
327            return $this->mId;
328        } else {
329            return $this->mTitle->getArticleID();
330        }
331    }
332
333    /**
334     * Returns parser output
335     * @since 1.19
336     * @return ParserOutput
337     */
338    public function getParserOutput() {
339        return $this->mParserOutput;
340    }
341
342    /**
343     * Set the RevisionRecord corresponding to this LinksUpdate
344     *
345     * @since 1.35
346     * @param RevisionRecord $revisionRecord
347     */
348    public function setRevisionRecord( RevisionRecord $revisionRecord ) {
349        $this->mRevisionRecord = $revisionRecord;
350        $this->tableFactory->setRevision( $revisionRecord );
351    }
352
353    /**
354     * @since 1.35
355     * @return RevisionRecord|null
356     */
357    public function getRevisionRecord() {
358        return $this->mRevisionRecord;
359    }
360
361    /**
362     * Set the user who triggered this LinksUpdate
363     *
364     * @since 1.27
365     * @param UserIdentity $user
366     */
367    public function setTriggeringUser( UserIdentity $user ) {
368        $this->user = $user;
369    }
370
371    /**
372     * Get the user who triggered this LinksUpdate
373     *
374     * @since 1.27
375     * @return UserIdentity|null
376     */
377    public function getTriggeringUser(): ?UserIdentity {
378        return $this->user;
379    }
380
381    protected function getPageLinksTable(): PageLinksTable {
382        // @phan-suppress-next-line PhanTypeMismatchReturnSuperType
383        return $this->tableFactory->get( 'pagelinks' );
384    }
385
386    protected function getExternalLinksTable(): ExternalLinksTable {
387        // @phan-suppress-next-line PhanTypeMismatchReturnSuperType
388        return $this->tableFactory->get( 'externallinks' );
389    }
390
391    protected function getPagePropsTable(): PagePropsTable {
392        // @phan-suppress-next-line PhanTypeMismatchReturnSuperType
393        return $this->tableFactory->get( 'page_props' );
394    }
395
396    /**
397     * Fetch external links added by this LinksUpdate. Only available after
398     * the update is complete.
399     * @since 1.33
400     * @return null|array Array of Strings
401     */
402    public function getAddedExternalLinks() {
403        return $this->getExternalLinksTable()->getStringArray( LinksTable::INSERTED );
404    }
405
406    /**
407     * Fetch external links removed by this LinksUpdate. Only available after
408     * the update is complete.
409     * @since 1.33
410     * @return null|string[]
411     */
412    public function getRemovedExternalLinks() {
413        return $this->getExternalLinksTable()->getStringArray( LinksTable::DELETED );
414    }
415
416    /**
417     * Fetch page properties added by this LinksUpdate.
418     * Only available after the update is complete.
419     * @since 1.28
420     * @return array<string,string>
421     */
422    public function getAddedProperties() {
423        return $this->getPagePropsTable()->getAssocArray( LinksTable::INSERTED );
424    }
425
426    /**
427     * Fetch page properties removed by this LinksUpdate.
428     * Only available after the update is complete.
429     * @since 1.28
430     * @return array<string,string>
431     */
432    public function getRemovedProperties() {
433        return $this->getPagePropsTable()->getAssocArray( LinksTable::DELETED );
434    }
435
436    /**
437     * Get an iterator over PageReferenceValue objects corresponding to a given set
438     * type in a given table.
439     *
440     * @since 1.38
441     * @param string $tableName The name of any table that links to local titles
442     * @param int $setType One of:
443     *   - LinksTable::INSERTED: The inserted links
444     *   - LinksTable::DELETED: The deleted links
445     *   - LinksTable::CHANGED: Both the inserted and deleted links
446     *   - LinksTable::OLD: The old set of links, loaded before the update
447     *   - LinksTable::NEW: The new set of links from the ParserOutput
448     * @return iterable<PageReferenceValue>
449     */
450    public function getPageReferenceIterator( $tableName, $setType ) {
451        $table = $this->tableFactory->get( $tableName );
452        if ( $table instanceof TitleLinksTable ) {
453            return $table->getPageReferenceIterator( $setType );
454        } else {
455            throw new InvalidArgumentException(
456                __METHOD__ . ": $tableName does not have a list of titles" );
457        }
458    }
459
460    /**
461     * Same as getPageReferenceIterator() but converted to an array for convenience
462     * (at the expense of additional time and memory usage)
463     *
464     * @since 1.38
465     * @param string $tableName
466     * @param int $setType
467     * @return PageReferenceValue[]
468     */
469    public function getPageReferenceArray( $tableName, $setType ) {
470        return iterator_to_array( $this->getPageReferenceIterator( $tableName, $setType ) );
471    }
472
473    /**
474     * Update links table freshness
475     */
476    protected function updateLinksTimestamp() {
477        if ( $this->mId ) {
478            // The link updates made here only reflect the freshness of the parser output
479            $timestamp = $this->mParserOutput->getCacheTime();
480            $update = $this->getDB()->newUpdateQueryBuilder()
481                ->update( 'page' )
482                ->set( [ 'page_links_updated' => $this->getDB()->timestamp( $timestamp ) ] )
483                ->where( [ 'page_id' => $this->mId ] )
484                ->caller( __METHOD__ );
485            $update->execute();
486
487            $this->linkWriteDuplicator->duplicate( $update );
488        }
489    }
490
491    /**
492     * @return IDatabase
493     */
494    protected function getDB() {
495        $this->db ??= $this->dbProvider->getPrimaryDatabase();
496        return $this->db;
497    }
498
499    /**
500     * Whether or not this LinksUpdate will also update pages which transclude the
501     * current page or otherwise depend on it.
502     *
503     * @return bool
504     */
505    public function isRecursive() {
506        return $this->mRecursive;
507    }
508
509    /** @inheritDoc */
510    public function getTransactionRoundRequirement() {
511        return self::TRX_ROUND_ABSENT;
512    }
513}