Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
92.78% covered (success)
92.78%
90 / 97
50.00% covered (danger)
50.00%
4 / 8
CRAP
0.00% covered (danger)
0.00%
0 / 1
RevisionOutputCache
92.78% covered (success)
92.78%
90 / 97
50.00% covered (danger)
50.00%
4 / 8
27.27
0.00% covered (danger)
0.00%
0 / 1
 __construct
100.00% covered (success)
100.00%
8 / 8
100.00% covered (success)
100.00%
1 / 1
1
 incrementStats
100.00% covered (success)
100.00%
7 / 7
100.00% covered (success)
100.00%
1 / 1
3
 makeParserOutputKey
83.33% covered (warning)
83.33%
5 / 6
0.00% covered (danger)
0.00%
0 / 1
2.02
 makeParserOutputKeyOptionalRevId
0.00% covered (danger)
0.00%
0 / 4
0.00% covered (danger)
0.00%
0 / 1
2
 get
95.65% covered (success)
95.65%
22 / 23
0.00% covered (danger)
0.00%
0 / 1
6
 save
96.88% covered (success)
96.88%
31 / 32
0.00% covered (danger)
0.00%
0 / 1
10
 restoreFromJson
100.00% covered (success)
100.00%
9 / 9
100.00% covered (success)
100.00%
1 / 1
2
 encodeAsJson
100.00% covered (success)
100.00%
8 / 8
100.00% covered (success)
100.00%
1 / 1
2
1<?php
2/**
3 * Cache for outputs of the PHP parser
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
19 *
20 * @file
21 * @ingroup Cache Parser
22 */
23
24namespace MediaWiki\Parser;
25
26use CacheTime;
27use InvalidArgumentException;
28use JsonException;
29use MediaWiki\Json\JsonCodec;
30use MediaWiki\Revision\RevisionRecord;
31use MediaWiki\Utils\MWTimestamp;
32use ParserOptions;
33use Psr\Log\LoggerInterface;
34use WANObjectCache;
35use Wikimedia\Stats\StatsFactory;
36use Wikimedia\UUID\GlobalIdGenerator;
37
38/**
39 * Cache for ParserOutput objects.
40 * The cache is split per ParserOptions.
41 *
42 * @since 1.36
43 * @ingroup Cache Parser
44 */
45class RevisionOutputCache {
46
47    /** @var string The name of this cache. Used as a root of the cache key. */
48    private $name;
49
50    /** @var WANObjectCache */
51    private $cache;
52
53    /**
54     * Anything cached prior to this is invalidated
55     *
56     * @var string
57     */
58    private $cacheEpoch;
59
60    /**
61     * Expiry time for cache entries.
62     *
63     * @var int
64     */
65    private $cacheExpiry;
66
67    /** @var JsonCodec */
68    private $jsonCodec;
69
70    /** @var StatsFactory */
71    private $stats;
72
73    /** @var LoggerInterface */
74    private $logger;
75
76    private GlobalIdGenerator $globalIdGenerator;
77
78    /**
79     * @param string $name
80     * @param WANObjectCache $cache
81     * @param int $cacheExpiry Expiry for ParserOutput in $cache.
82     * @param string $cacheEpoch Anything before this timestamp is invalidated
83     * @param JsonCodec $jsonCodec
84     * @param StatsFactory $stats
85     * @param LoggerInterface $logger
86     * @param GlobalIdGenerator $globalIdGenerator
87     */
88    public function __construct(
89        string $name,
90        WANObjectCache $cache,
91        int $cacheExpiry,
92        string $cacheEpoch,
93        JsonCodec $jsonCodec,
94        StatsFactory $stats,
95        LoggerInterface $logger,
96        GlobalIdGenerator $globalIdGenerator
97    ) {
98        $this->name = $name;
99        $this->cache = $cache;
100        $this->cacheExpiry = $cacheExpiry;
101        $this->cacheEpoch = $cacheEpoch;
102        $this->jsonCodec = $jsonCodec;
103        $this->stats = $stats;
104        $this->logger = $logger;
105        $this->globalIdGenerator = $globalIdGenerator;
106    }
107
108    /**
109     * @param string $status e.g. hit, miss etc.
110     * @param string|null $reason
111     */
112    private function incrementStats( string $status, string $reason = null ) {
113        $metricSuffix = $reason ? "{$status}_{$reason}" : $status;
114
115        $this->stats->getCounter( 'RevisionOutputCache_operation_total' )
116            ->setLabel( 'name', $this->name )
117            ->setLabel( 'status', $status )
118            ->setLabel( 'reason', $reason ?: 'n/a' )
119            ->copyToStatsdAt( "RevisionOutputCache.{$this->name}.{$metricSuffix}" )
120            ->increment();
121    }
122
123    /**
124     * Get a key that will be used by this cache to store the content
125     * for a given page considering the given options and the array of
126     * used options.
127     *
128     * If there is a possibility the revision does not have a revision id, use
129     * makeParserOutputKeyOptionalRevId() instead.
130     *
131     * @warning The exact format of the key is considered internal and is subject
132     * to change, thus should not be used as storage or long-term caching key.
133     * This is intended to be used for logging or keying something transient.
134     *
135     * @param RevisionRecord $revision
136     * @param ParserOptions $options
137     * @param array|null $usedOptions currently ignored
138     * @return string
139     * @internal
140     */
141    public function makeParserOutputKey(
142        RevisionRecord $revision,
143        ParserOptions $options,
144        array $usedOptions = null
145    ): string {
146        $usedOptions = ParserOptions::allCacheVaryingOptions();
147
148        $revId = $revision->getId();
149        if ( !$revId ) {
150            // If RevId is null, this would probably be unsafe to use as a cache key.
151            throw new InvalidArgumentException( "Revision must have an id number" );
152        }
153        $hash = $options->optionsHash( $usedOptions );
154        return $this->cache->makeKey( $this->name, $revId, $hash );
155    }
156
157    /**
158     * Get a key that will be used for locks or pool counter
159     *
160     * Similar to makeParserOutputKey except the revision id might be null,
161     * in which case it is unsafe to cache, but still needs a key for things like
162     * poolcounter.
163     *
164     * @warning The exact format of the key is considered internal and is subject
165     * to change, thus should not be used as storage or long-term caching key.
166     * This is intended to be used for logging or keying something transient.
167     *
168     * @param RevisionRecord $revision
169     * @param ParserOptions $options
170     * @param array|null $usedOptions currently ignored
171     * @return string
172     * @internal
173     */
174    public function makeParserOutputKeyOptionalRevId(
175        RevisionRecord $revision,
176        ParserOptions $options,
177        array $usedOptions = null
178    ): string {
179        $usedOptions = ParserOptions::allCacheVaryingOptions();
180
181        // revId may be null.
182        $revId = (string)$revision->getId();
183        $hash = $options->optionsHash( $usedOptions );
184        return $this->cache->makeKey( $this->name, $revId, $hash );
185    }
186
187    /**
188     * Retrieve the ParserOutput from cache.
189     * false if not found or outdated.
190     *
191     * @param RevisionRecord $revision
192     * @param ParserOptions $parserOptions
193     *
194     * @return ParserOutput|false False on failure
195     */
196    public function get( RevisionRecord $revision, ParserOptions $parserOptions ) {
197        if ( $this->cacheExpiry <= 0 ) {
198            // disabled
199            return false;
200        }
201
202        if ( !$parserOptions->isSafeToCache() ) {
203            $this->incrementStats( 'miss', 'unsafe' );
204            return false;
205        }
206
207        $cacheKey = $this->makeParserOutputKey( $revision, $parserOptions );
208        $json = $this->cache->get( $cacheKey );
209
210        if ( $json === false ) {
211            $this->incrementStats( 'miss', 'absent' );
212            return false;
213        }
214
215        $output = $this->restoreFromJson( $json, $cacheKey, ParserOutput::class );
216        if ( $output === null ) {
217            $this->incrementStats( 'miss', 'unserialize' );
218            return false;
219        }
220
221        $cacheTime = (int)MWTimestamp::convert( TS_UNIX, $output->getCacheTime() );
222        $expiryTime = (int)MWTimestamp::convert( TS_UNIX, $this->cacheEpoch );
223        $expiryTime = max( $expiryTime, (int)MWTimestamp::now( TS_UNIX ) - $this->cacheExpiry );
224
225        if ( $cacheTime < $expiryTime ) {
226            $this->incrementStats( 'miss', 'expired' );
227            return false;
228        }
229
230        $this->logger->debug( 'old-revision cache hit' );
231        $this->incrementStats( 'hit' );
232        return $output;
233    }
234
235    /**
236     * @param ParserOutput $output
237     * @param RevisionRecord $revision
238     * @param ParserOptions $parserOptions
239     * @param string|null $cacheTime TS_MW timestamp when the output was generated
240     */
241    public function save(
242        ParserOutput $output,
243        RevisionRecord $revision,
244        ParserOptions $parserOptions,
245        string $cacheTime = null
246    ) {
247        if ( !$output->hasText() ) {
248            throw new InvalidArgumentException( 'Attempt to cache a ParserOutput with no text set!' );
249        }
250
251        if ( $this->cacheExpiry <= 0 ) {
252            // disabled
253            return;
254        }
255
256        $cacheKey = $this->makeParserOutputKey( $revision, $parserOptions );
257
258        // Ensure cache properties are set in the ParserOutput
259        // T350538: These should be turned into assertions that the
260        // properties are already present (and the $cacheTime argument
261        // removed).
262        if ( $cacheTime ) {
263            $output->setCacheTime( $cacheTime );
264        } else {
265            $cacheTime = $output->getCacheTime();
266        }
267        if ( !$output->getCacheRevisionId() ) {
268            $output->setCacheRevisionId( $revision->getId() );
269        }
270        if ( !$output->getRenderId() ) {
271            $output->setRenderId( $this->globalIdGenerator->newUUIDv1() );
272        }
273        if ( !$output->getRevisionTimestamp() ) {
274            $output->setRevisionTimestamp( $revision->getTimestamp() );
275        }
276
277        $msg = "Saved in RevisionOutputCache with key $cacheKey" .
278            " and timestamp $cacheTime" .
279            " and revision id {$revision->getId()}.";
280
281        $output->addCacheMessage( $msg );
282
283        // The ParserOutput might be dynamic and have been marked uncacheable by the parser.
284        $output->updateCacheExpiry( $this->cacheExpiry );
285
286        $expiry = $output->getCacheExpiry();
287        if ( $expiry <= 0 ) {
288            $this->incrementStats( 'save', 'uncacheable' );
289            return;
290        }
291
292        if ( !$parserOptions->isSafeToCache() ) {
293            $this->incrementStats( 'save', 'unsafe' );
294            return;
295        }
296
297        $json = $this->encodeAsJson( $output, $cacheKey );
298        if ( $json === null ) {
299            $this->incrementStats( 'save', 'nonserializable' );
300            return;
301        }
302
303        $this->cache->set( $cacheKey, $json, $expiry );
304        $this->incrementStats( 'save', 'success' );
305    }
306
307    /**
308     * @param string $jsonData
309     * @param string $key
310     * @param string $expectedClass
311     * @return CacheTime|ParserOutput|null
312     */
313    private function restoreFromJson( string $jsonData, string $key, string $expectedClass ) {
314        try {
315            /** @var CacheTime $obj */
316            $obj = $this->jsonCodec->deserialize( $jsonData, $expectedClass );
317            return $obj;
318        } catch ( JsonException $e ) {
319            $this->logger->error( 'Unable to deserialize JSON', [
320                'name' => $this->name,
321                'cache_key' => $key,
322                'message' => $e->getMessage()
323            ] );
324            return null;
325        }
326    }
327
328    /**
329     * @param CacheTime $obj
330     * @param string $key
331     * @return string|null
332     */
333    private function encodeAsJson( CacheTime $obj, string $key ) {
334        try {
335            return $this->jsonCodec->serialize( $obj );
336        } catch ( JsonException $e ) {
337            $this->logger->error( 'Unable to serialize JSON', [
338                'name' => $this->name,
339                'cache_key' => $key,
340                'message' => $e->getMessage(),
341            ] );
342            return null;
343        }
344    }
345}