Code Coverage |
||||||||||
Lines |
Functions and Methods |
Classes and Traits |
||||||||
Total | |
92.78% |
90 / 97 |
|
50.00% |
4 / 8 |
CRAP | |
0.00% |
0 / 1 |
RevisionOutputCache | |
92.78% |
90 / 97 |
|
50.00% |
4 / 8 |
27.27 | |
0.00% |
0 / 1 |
__construct | |
100.00% |
8 / 8 |
|
100.00% |
1 / 1 |
1 | |||
incrementStats | |
100.00% |
7 / 7 |
|
100.00% |
1 / 1 |
3 | |||
makeParserOutputKey | |
83.33% |
5 / 6 |
|
0.00% |
0 / 1 |
2.02 | |||
makeParserOutputKeyOptionalRevId | |
0.00% |
0 / 4 |
|
0.00% |
0 / 1 |
2 | |||
get | |
95.65% |
22 / 23 |
|
0.00% |
0 / 1 |
6 | |||
save | |
96.88% |
31 / 32 |
|
0.00% |
0 / 1 |
10 | |||
restoreFromJson | |
100.00% |
9 / 9 |
|
100.00% |
1 / 1 |
2 | |||
encodeAsJson | |
100.00% |
8 / 8 |
|
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 | |
24 | namespace MediaWiki\Parser; |
25 | |
26 | use CacheTime; |
27 | use InvalidArgumentException; |
28 | use JsonException; |
29 | use MediaWiki\Json\JsonCodec; |
30 | use MediaWiki\Revision\RevisionRecord; |
31 | use MediaWiki\Utils\MWTimestamp; |
32 | use ParserOptions; |
33 | use Psr\Log\LoggerInterface; |
34 | use WANObjectCache; |
35 | use Wikimedia\Stats\StatsFactory; |
36 | use 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 | */ |
45 | class 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->unserialize( $jsonData, $expectedClass ); |
317 | return $obj; |
318 | } catch ( JsonException $e ) { |
319 | $this->logger->error( 'Unable to unserialize 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 | } |