Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
17.07% covered (danger)
17.07%
14 / 82
19.05% covered (danger)
19.05%
4 / 21
CRAP
0.00% covered (danger)
0.00%
0 / 1
BagOStuff
17.28% covered (danger)
17.28%
14 / 81
19.05% covered (danger)
19.05%
4 / 21
1243.53
0.00% covered (danger)
0.00%
0 / 1
 __construct
83.33% covered (warning)
83.33%
5 / 6
0.00% covered (danger)
0.00%
0 / 1
2.02
 setLogger
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 getLogger
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 getWithSetCallback
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 1
20
 get
n/a
0 / 0
n/a
0 / 0
0
 set
n/a
0 / 0
n/a
0 / 0
0
 delete
n/a
0 / 0
n/a
0 / 0
0
 add
n/a
0 / 0
n/a
0 / 0
0
 merge
n/a
0 / 0
n/a
0 / 0
0
 changeTTL
n/a
0 / 0
n/a
0 / 0
0
 lock
n/a
0 / 0
n/a
0 / 0
0
 unlock
n/a
0 / 0
n/a
0 / 0
0
 getScopedLock
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 1
12
 deleteObjectsExpiringBefore
n/a
0 / 0
n/a
0 / 0
0
 getMulti
n/a
0 / 0
n/a
0 / 0
0
 setMulti
n/a
0 / 0
n/a
0 / 0
0
 deleteMulti
n/a
0 / 0
n/a
0 / 0
0
 changeTTLMulti
n/a
0 / 0
n/a
0 / 0
0
 incrWithInit
n/a
0 / 0
n/a
0 / 0
0
 watchErrors
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 getLastError
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
6
 clearLastError
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
 setLastError
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
 makeGlobalKey
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 makeKey
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 isKeyGlobal
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 getQoS
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 getSegmentationSize
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
 getSegmentedValueMaxSize
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
2
 fieldHasFlags
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 mergeFlagMaps
0.00% covered (danger)
0.00%
0 / 7
0.00% covered (danger)
0.00%
0 / 1
20
 makeKeyInternal
83.33% covered (warning)
83.33%
5 / 6
0.00% covered (danger)
0.00%
0 / 1
3.04
 requireConvertGenericKey
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
2
 convertGenericKey
0.00% covered (danger)
0.00%
0 / 7
0.00% covered (danger)
0.00%
0 / 1
12
 proxyCall
0.00% covered (danger)
0.00%
0 / 25
0.00% covered (danger)
0.00%
0 / 1
90
 getCurrentTime
n/a
0 / 0
n/a
0 / 0
2
 setMockTime
n/a
0 / 0
n/a
0 / 0
1
1<?php
2/**
3 * Copyright © 2003-2004 Brooke Vibber <bvibber@wikimedia.org>
4 * https://www.mediawiki.org/
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License along
17 * with this program; if not, write to the Free Software Foundation, Inc.,
18 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19 * http://www.gnu.org/copyleft/gpl.html
20 *
21 * @file
22 * @ingroup Cache
23 */
24
25/**
26 * @defgroup Cache Cache
27 */
28
29namespace Wikimedia\ObjectCache;
30
31use InvalidArgumentException;
32use Psr\Log\LoggerAwareInterface;
33use Psr\Log\LoggerInterface;
34use Psr\Log\NullLogger;
35use Wikimedia\LightweightObjectStore\ExpirationAwareness;
36use Wikimedia\LightweightObjectStore\StorageAwareness;
37use Wikimedia\ScopedCallback;
38use Wikimedia\Stats\StatsFactory;
39
40/**
41 * Class representing a cache/ephemeral data store
42 *
43 * This interface is intended to be more or less compatible with the PHP memcached client.
44 *
45 * Class instances should be created with an intended access scope for the dataset, such as:
46 *   - a) A single PHP thread on a server (e.g. stored in a PHP variable)
47 *   - b) A single application server (e.g. stored in APC or sqlite)
48 *   - c) All application servers in datacenter (e.g. stored in memcached or mysql)
49 *   - d) All application servers in all datacenters (e.g. stored via mcrouter or dynomite)
50 *
51 * Callers should use the proper factory methods that yield BagOStuff instances. Site admins
52 * should make sure that the configuration for those factory methods match their access scope.
53 * BagOStuff subclasses have widely varying levels of support replication features within and
54 * among datacenters.
55 *
56 * Subclasses should override the default "segmentationSize" field with an appropriate value.
57 * The value should not be larger than what the backing store (by default) supports. It also
58 * should be roughly informed by common performance bottlenecks (e.g. values over a certain size
59 * having poor scalability). The same goes for the "segmentedValueMaxSize" member, which limits
60 * the maximum size and chunk count (indirectly) of values.
61 *
62 * A few notes about data consistency for BagOStuff instances:
63 *  - Read operation methods, e.g. get(), should be synchronous in the local datacenter.
64 *    When used with READ_LATEST, such operations should reflect any prior writes originating
65 *    from the local datacenter (e.g. by avoiding replica DBs or invoking quorom reads).
66 *  - Write operation methods, e.g. set(), should be synchronous in the local datacenter, with
67 *    asynchronous cross-datacenter replication. This replication can be either "best effort"
68 *    or eventually consistent. If the write succeeded, then any subsequent `get()` operations with
69 *    READ_LATEST, regardless of datacenter, should reflect the changes.
70 *  - Locking operation methods, e.g. lock(), unlock(), and getScopedLock(), should only apply
71 *    to the local datacenter.
72 *  - Any set of single-key write operation method calls originating from a single datacenter
73 *    should observe "best effort" linearizability.
74 *    In this context, "best effort" means that consistency holds as long as connectivity is
75 *    strong, network latency is low, and there are no relevant storage server failures.
76 *    Per https://en.wikipedia.org/wiki/PACELC_theorem, the store should act as a PA/EL
77 *    distributed system for these operations.
78 *
79 * @stable to extend
80 * @newable
81 * @ingroup Cache
82 */
83abstract class BagOStuff implements
84    ExpirationAwareness,
85    StorageAwareness,
86    IStoreKeyEncoder,
87    LoggerAwareInterface
88{
89    /** @var StatsFactory */
90    protected $stats;
91    /** @var LoggerInterface */
92    protected $logger;
93    /** @var callable|null */
94    protected $asyncHandler;
95    /** @var int[] Map of (BagOStuff:ATTR_* constant => BagOStuff:QOS_* constant) */
96    protected $attrMap = [];
97
98    /** @var string Default keyspace; used by makeKey() */
99    protected $keyspace;
100
101    /** @var int BagOStuff:ERR_* constant of the last error that occurred */
102    protected $lastError = self::ERR_NONE;
103    /** @var int Error event sequence number of the last error that occurred */
104    protected $lastErrorId = 0;
105
106    /** @var int Next sequence number to use for watch/error events */
107    protected static $nextErrorMonitorId = 1;
108
109    /** @var float|null */
110    private $wallClockOverride;
111
112    /** Bitfield constants for get()/getMulti(); these are only advisory */
113    /** If supported, avoid reading stale data due to replication */
114    public const READ_LATEST = 1;
115    /** Promise that the caller handles detection of staleness */
116    public const READ_VERIFIED = 2;
117
118    /** Bitfield constants for set()/merge(); these are only advisory */
119    /** Only change state of the in-memory cache */
120    public const WRITE_CACHE_ONLY = 8;
121    /** Allow partitioning of the value if it is a large string */
122    public const WRITE_ALLOW_SEGMENTS = 16;
123    /** Delete all the segments if the value is partitioned */
124    public const WRITE_PRUNE_SEGMENTS = 32;
125    /**
126     * If supported, do not block on write operation completion; instead, treat writes as
127     * succesful based on whether they could be buffered. When using this flag with methods
128     * that yield item values, the boolean "true" will be used as a placeholder. The next
129     * blocking operation (e.g. typical read) will trigger a flush of the operation buffer.
130     */
131    public const WRITE_BACKGROUND = 64;
132
133    /** Abort after the first merge conflict */
134    public const MAX_CONFLICTS_ONE = 1;
135
136    /** @var string Global keyspace; used by makeGlobalKey() */
137    protected const GLOBAL_KEYSPACE = 'global';
138    /** @var string Precomputed global cache key prefix (needs no encoding) */
139    protected const GLOBAL_PREFIX = 'global:';
140
141    /** @var int Item is a single cache key */
142    protected const ARG0_KEY = 0;
143    /** @var int Item is an array of cache keys */
144    protected const ARG0_KEYARR = 1;
145    /** @var int Item is an array indexed by cache keys */
146    protected const ARG0_KEYMAP = 2;
147    /** @var int Item does not involve any keys */
148    protected const ARG0_NONKEY = 3;
149
150    /** @var int Item is an array indexed by cache keys */
151    protected const RES_KEYMAP = 0;
152    /** @var int Item does not involve any keys */
153    protected const RES_NONKEY = 1;
154
155    /**
156     * @stable to call
157     *
158     * @param array $params Parameters include:
159     *   - keyspace: Keyspace to use for keys in makeKey(). [Default: "local"]
160     *   - asyncHandler: Callable to use for scheduling tasks after the web request ends.
161     *      In CLI mode, it should run the task immediately. [Default: null]
162     *   - stats: IStatsdDataFactory instance. [optional]
163     *   - logger: \Psr\Log\LoggerInterface instance. [optional]
164     *
165     * @phan-param array{keyspace?:string,logger?:\Psr\Log\LoggerInterface,asyncHandler?:callable} $params
166     */
167    public function __construct( array $params = [] ) {
168        $this->keyspace = $params['keyspace'] ?? 'local';
169        $this->stats = $params['stats'] ?? StatsFactory::newNull();
170        $this->setLogger( $params['logger'] ?? new NullLogger() );
171
172        $asyncHandler = $params['asyncHandler'] ?? null;
173        if ( is_callable( $asyncHandler ) ) {
174            $this->asyncHandler = $asyncHandler;
175        }
176    }
177
178    /**
179     * @param LoggerInterface $logger
180     *
181     * @return void
182     */
183    public function setLogger( LoggerInterface $logger ) {
184        $this->logger = $logger;
185    }
186
187    /**
188     * @since 1.35
189     * @return LoggerInterface
190     */
191    public function getLogger(): LoggerInterface {
192        return $this->logger;
193    }
194
195    /**
196     * Get an item, regenerating and setting it if not found
197     *
198     * The callback can take $exptime as argument by reference and modify it.
199     * Nothing is stored nor deleted if the callback returns false.
200     *
201     * @param string $key
202     * @param int $exptime Time-to-live (seconds)
203     * @param callable $callback Callback that derives the new value
204     * @param int $flags Bitfield of BagOStuff::READ_* or BagOStuff::WRITE_* constants [optional]
205     *
206     * @return mixed The cached value if found or the result of $callback otherwise
207     * @since 1.27
208     */
209    final public function getWithSetCallback( $key, $exptime, $callback, $flags = 0 ) {
210        $value = $this->get( $key, $flags );
211
212        if ( $value === false ) {
213            $value = $callback( $exptime );
214            if ( $value !== false && $exptime >= 0 ) {
215                $this->set( $key, $value, $exptime, $flags );
216            }
217        }
218
219        return $value;
220    }
221
222    /**
223     * Get an item
224     *
225     * If the key includes a deterministic input hash (e.g. the key can only have
226     * the correct value) or complete staleness checks are handled by the caller
227     * (e.g. nothing relies on the TTL), then the READ_VERIFIED flag should be set.
228     * This lets tiered backends know they can safely upgrade a cached value to
229     * higher tiers using standard TTLs.
230     *
231     * @param string $key
232     * @param int $flags Bitfield of BagOStuff::READ_* constants [optional]
233     *
234     * @return mixed Returns false on failure or if the item does not exist
235     */
236    abstract public function get( $key, $flags = 0 );
237
238    /**
239     * Set an item
240     *
241     * @param string $key
242     * @param mixed $value
243     * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
244     * @param int $flags Bitfield of BagOStuff::WRITE_* constants
245     *
246     * @return bool Success
247     */
248    abstract public function set( $key, $value, $exptime = 0, $flags = 0 );
249
250    /**
251     * Delete an item if it exists
252     *
253     * For large values written using WRITE_ALLOW_SEGMENTS, this only deletes the main
254     * segment list key unless WRITE_PRUNE_SEGMENTS is in the flags. While deleting the segment
255     * list key has the effect of functionally deleting the key, it leaves unused blobs in cache.
256     *
257     * @param string $key
258     * @param int $flags Bitfield of BagOStuff::WRITE_* constants
259     *
260     * @return bool Success (item deleted or not found)
261     */
262    abstract public function delete( $key, $flags = 0 );
263
264    /**
265     * Insert an item if it does not already exist
266     *
267     * @param string $key
268     * @param mixed $value
269     * @param int $exptime
270     * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
271     *
272     * @return bool Success (item created)
273     */
274    abstract public function add( $key, $value, $exptime = 0, $flags = 0 );
275
276    /**
277     * Merge changes into the existing cache value (possibly creating a new one)
278     *
279     * The callback function returns the new value given the current value
280     * (which will be false if not present), and takes the arguments:
281     * (this BagOStuff, cache key, current value, TTL).
282     * The TTL parameter is reference set to $exptime. It can be overridden in the callback.
283     * Nothing is stored nor deleted if the callback returns false.
284     *
285     * @param string $key
286     * @param callable $callback Callback method to be executed
287     * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
288     * @param int $attempts The amount of times to attempt a merge in case of failure
289     * @param int $flags Bitfield of BagOStuff::WRITE_* constants
290     *
291     * @return bool Success
292     * @throws InvalidArgumentException
293     */
294    abstract public function merge(
295        $key,
296        callable $callback,
297        $exptime = 0,
298        $attempts = 10,
299        $flags = 0
300    );
301
302    /**
303     * Change the expiration on an item
304     *
305     * If an expiry in the past is given then the key will immediately be expired
306     *
307     * For large values written using WRITE_ALLOW_SEGMENTS, this only changes the TTL of the
308     * main segment list key. While lowering the TTL of the segment list key has the effect of
309     * functionally lowering the TTL of the key, it might leave unused blobs in cache for longer.
310     * Raising the TTL of such keys is not effective, since the expiration of a single segment
311     * key effectively expires the entire value.
312     *
313     * @param string $key
314     * @param int $exptime TTL or UNIX timestamp
315     * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
316     *
317     * @return bool Success (item found and updated)
318     * @since 1.28
319     */
320    abstract public function changeTTL( $key, $exptime = 0, $flags = 0 );
321
322    /**
323     * Acquire an advisory lock on a key string, exclusive to the caller
324     *
325     * @param string $key
326     * @param int $timeout Lock wait timeout; 0 for non-blocking [optional]
327     * @param int $exptime Lock time-to-live in seconds; 1 day maximum [optional]
328     * @param string $rclass If this thread already holds the lock, and the lock was acquired
329     *  using the same value for this parameter, then return true and use reference counting so
330     *  that only the unlock() call from the outermost lock() caller actually releases the lock
331     *  (note that only the outermost time-to-live is used) [optional]
332     *
333     * @return bool Success
334     */
335    abstract public function lock( $key, $timeout = 6, $exptime = 6, $rclass = '' );
336
337    /**
338     * Release an advisory lock on a key string
339     *
340     * @param string $key
341     *
342     * @return bool Success
343     */
344    abstract public function unlock( $key );
345
346    /**
347     * Get a lightweight exclusive self-unlocking lock
348     *
349     * Note that the same lock cannot be acquired twice.
350     *
351     * This is useful for task de-duplication or to avoid obtrusive
352     * (though non-corrupting) DB errors like INSERT key conflicts
353     * or deadlocks when using LOCK IN SHARE MODE.
354     *
355     * @param string $key
356     * @param int $timeout Lock wait timeout; 0 for non-blocking [optional]
357     * @param int $exptime Lock time-to-live [optional]; 1 day maximum
358     * @param string $rclass Allow reentry if set and the current lock used this value
359     *
360     * @return ScopedCallback|null Returns null on failure
361     * @since 1.26
362     */
363    final public function getScopedLock( $key, $timeout = 6, $exptime = 30, $rclass = '' ) {
364        $exptime = min( $exptime ?: INF, self::TTL_DAY );
365
366        if ( !$this->lock( $key, $timeout, $exptime, $rclass ) ) {
367            return null;
368        }
369
370        return new ScopedCallback( function () use ( $key ) {
371            $this->unlock( $key );
372        } );
373    }
374
375    /**
376     * Delete all objects expiring before a certain date
377     *
378     * @param string|int $timestamp The reference date in MW or TS_UNIX format
379     * @param callable|null $progress Optional, a function which will be called
380     *     regularly during long-running operations with the percentage progress
381     *     as the first parameter. [optional]
382     * @param int|float $limit Maximum number of keys to delete [default: INF]
383     * @param string|null $tag Tag to purge a single shard only.
384     *  This is only supported when server tags are used in configuration.
385     *
386     * @return bool Success; false if unimplemented
387     */
388    abstract public function deleteObjectsExpiringBefore(
389        $timestamp,
390        callable $progress = null,
391        $limit = INF,
392        string $tag = null
393    );
394
395    /**
396     * Get a batch of items
397     *
398     * @param string[] $keys List of keys
399     * @param int $flags Bitfield; supports READ_LATEST [optional]
400     *
401     * @return mixed[] Map of (key => value) for existing keys
402     */
403    abstract public function getMulti( array $keys, $flags = 0 );
404
405    /**
406     * Set a batch of items
407     *
408     * This does not support WRITE_ALLOW_SEGMENTS to avoid excessive read I/O
409     *
410     * WRITE_BACKGROUND can be used for bulk insertion where the response is not vital
411     *
412     * @param mixed[] $valueByKey Map of (key => value)
413     * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
414     * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
415     *
416     * @return bool Success
417     * @since 1.24
418     */
419    abstract public function setMulti( array $valueByKey, $exptime = 0, $flags = 0 );
420
421    /**
422     * Delete a batch of items
423     *
424     * This does not support WRITE_ALLOW_SEGMENTS to avoid excessive read I/O
425     *
426     * WRITE_BACKGROUND can be used for bulk deletion where the response is not vital
427     *
428     * @param string[] $keys List of keys
429     * @param int $flags Bitfield of BagOStuff::WRITE_* constants
430     *
431     * @return bool Success (items deleted and/or not found)
432     * @since 1.33
433     */
434    abstract public function deleteMulti( array $keys, $flags = 0 );
435
436    /**
437     * Change the expiration of multiple items
438     *
439     * @see BagOStuff::changeTTL()
440     *
441     * @param string[] $keys List of keys
442     * @param int $exptime TTL or UNIX timestamp
443     * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
444     *
445     * @return bool Success (all items found and updated)
446     * @since 1.34
447     */
448    abstract public function changeTTLMulti( array $keys, $exptime, $flags = 0 );
449
450    /**
451     * Increase the value of the given key (no TTL change) if it exists or create it otherwise
452     *
453     * This will create the key with the value $init and TTL $exptime instead if not present.
454     * Callers should make sure that both ($init - $step) and $exptime are invariants for all
455     * operations to any given key. The value of $init should be at least that of $step.
456     *
457     * The new value is returned, except if the WRITE_BACKGROUND flag is given, in which case
458     * the handler may choose to return true to indicate that the operation has been dispatched.
459     *
460     * @param string $key Key built via makeKey() or makeGlobalKey()
461     * @param int $exptime Time-to-live (in seconds) or a UNIX timestamp expiration
462     * @param int $step Amount to increase the key value by [default: 1]
463     * @param int|null $init Value to initialize the key to if it does not exist [default: $step]
464     * @param int $flags Bit field of class WRITE_* constants [optional]
465     *
466     * @return int|bool New value (or true if asynchronous) on success; false on failure
467     * @since 1.24
468     */
469    abstract public function incrWithInit( $key, $exptime, $step = 1, $init = null, $flags = 0 );
470
471    /**
472     * Get a "watch point" token that can be used to get the "last error" to occur after now
473     *
474     * @return int A token to that can be used with getLastError()
475     * @since 1.38
476     */
477    public function watchErrors() {
478        return self::$nextErrorMonitorId++;
479    }
480
481    /**
482     * Get the "last error" registry
483     *
484     * The method should be invoked by a caller as part of the following pattern:
485     *   - The caller invokes watchErrors() to get a "since token"
486     *   - The caller invokes a sequence of cache operation methods
487     *   - The caller invokes getLastError() with the "since token"
488     *
489     * External callers can also invoke this method as part of the following pattern:
490     *   - The caller invokes clearLastError()
491     *   - The caller invokes a sequence of cache operation methods
492     *   - The caller invokes getLastError()
493     *
494     * @param int $watchPoint Only consider errors from after this "watch point" [optional]
495     *
496     * @return int BagOStuff:ERR_* constant for the "last error" registry
497     * @note Parameters added in 1.38: $watchPoint
498     * @since 1.23
499     */
500    public function getLastError( $watchPoint = 0 ) {
501        return ( $this->lastErrorId > $watchPoint ) ? $this->lastError : self::ERR_NONE;
502    }
503
504    /**
505     * Clear the "last error" registry
506     *
507     * @since 1.23
508     * @deprecated Since 1.38, hard deprecated in 1.43
509     */
510    public function clearLastError() {
511        wfDeprecated( __METHOD__, '1.38' );
512        $this->lastError = self::ERR_NONE;
513    }
514
515    /**
516     * Set the "last error" registry due to a problem encountered during an attempted operation
517     *
518     * @param int $error BagOStuff:ERR_* constant
519     *
520     * @since 1.23
521     */
522    protected function setLastError( $error ) {
523        $this->lastError = $error;
524        $this->lastErrorId = self::$nextErrorMonitorId++;
525    }
526
527    /**
528     * Make a cache key from the given components, in the "global" keyspace
529     *
530     * Global keys are shared with and visible to all sites hosted in the same
531     * infrastructure (e.g. cross-wiki within the same wiki farm). Others sites
532     * may read the stored value from their requests, and they must be able to
533     * correctly compute new values from their own request context.
534     *
535     * @see BagOStuff::makeKeyInternal
536     * @since 1.27
537     *
538     * @param string $keygroup Key group component, should be under 48 characters.
539     * @param string|int ...$components Additional, ordered, key components for entity IDs
540     *
541     * @return string Colon-separated, keyspace-prepended, ordered list of encoded components
542     */
543    public function makeGlobalKey( $keygroup, ...$components ) {
544        return $this->makeKeyInternal( self::GLOBAL_KEYSPACE, func_get_args() );
545    }
546
547    /**
548     * Make a cache key from the given components, in the default keyspace
549     *
550     * The default keyspace is unique to a given site. Subsequent web requests
551     * to the same site (e.g. local wiki, or same domain name) will interact
552     * with the same keyspace.
553     *
554     * Requests to other sites hosted on the same infrastructure (e.g. cross-wiki
555     * or cross-domain), have their own keyspace that naturally avoids conflicts.
556     *
557     * As caller you are responsible for:
558     * - Limit the key group (first component) to 48 characters
559     *
560     * Internally, the colon is used as delimiter (":"), and this is
561     * automatically escaped in supplied components to avoid ambiguity or
562     * key conflicts. BagOStuff subclasses are responsible for applying any
563     * additional escaping or limits as-needed before sending commands over
564     * the network.
565     *
566     * @see BagOStuff::makeKeyInternal
567     * @since 1.27
568     *
569     * @param string $keygroup Key group component, should be under 48 characters.
570     * @param string|int ...$components Additional, ordered, key components for entity IDs
571     *
572     * @return string Colon-separated, keyspace-prepended, ordered list of encoded components
573     */
574    public function makeKey( $keygroup, ...$components ) {
575        return $this->makeKeyInternal( $this->keyspace, func_get_args() );
576    }
577
578    /**
579     * Check whether a cache key is in the global keyspace
580     *
581     * @param string $key
582     *
583     * @return bool
584     * @since 1.35
585     */
586    public function isKeyGlobal( $key ) {
587        return str_starts_with( $key, self::GLOBAL_PREFIX );
588    }
589
590    /**
591     * @param int $flag BagOStuff::ATTR_* constant
592     *
593     * @return int BagOStuff:QOS_* constant
594     * @since 1.28
595     */
596    public function getQoS( $flag ) {
597        return $this->attrMap[$flag] ?? self::QOS_UNKNOWN;
598    }
599
600    /**
601     * @deprecated since 1.43, not used anywhere.
602     * @return int|float The chunk size, in bytes, of segmented objects (INF for no limit)
603     * @since 1.34
604     */
605    public function getSegmentationSize() {
606        wfDeprecated( __METHOD__, '1.43' );
607
608        return INF;
609    }
610
611    /**
612     * @deprecated since 1.43, not used anywhere.
613     * @return int|float Maximum total segmented object size in bytes (INF for no limit)
614     * @since 1.34
615     */
616    public function getSegmentedValueMaxSize() {
617        wfDeprecated( __METHOD__, '1.43' );
618
619        return INF;
620    }
621
622    /**
623     * @param int $field
624     * @param int $flags
625     *
626     * @return bool
627     * @since 1.34
628     */
629    final protected function fieldHasFlags( $field, $flags ) {
630        return ( ( $field & $flags ) === $flags );
631    }
632
633    /**
634     * Merge the flag maps of one or more BagOStuff objects into a "lowest common denominator" map
635     *
636     * @param BagOStuff[] $bags
637     *
638     * @return int[] Resulting flag map (class ATTR_* constant => class QOS_* constant)
639     */
640    final protected function mergeFlagMaps( array $bags ) {
641        $map = [];
642        foreach ( $bags as $bag ) {
643            foreach ( $bag->attrMap as $attr => $rank ) {
644                if ( isset( $map[$attr] ) ) {
645                    $map[$attr] = min( $map[$attr], $rank );
646                } else {
647                    $map[$attr] = $rank;
648                }
649            }
650        }
651
652        return $map;
653    }
654
655    /**
656     * Make a cache key for the given keyspace and components
657     *
658     * Subclasses may override this method in order to apply different escaping,
659     * or to deal with size constraints (such as MemcachedBagOStuff). For example
660     * by converting long components into hashes.
661     *
662     * If you override this method, you MUST override ::requireConvertGenericKey()
663     * to return true. This ensures that wrapping classes (e.g. MultiWriteBagOStuff)
664     * know to re-encode keys before calling read/write methods. See also ::proxyCall().
665     *
666     * @see BagOStuff::proxyCall
667     * @since 1.27
668     *
669     * @param string $keyspace
670     * @param string[]|int[] $components Key group and other components
671     *
672     * @return string
673     */
674    protected function makeKeyInternal( $keyspace, $components ) {
675        if ( count( $components ) < 1 ) {
676            throw new InvalidArgumentException( "Missing key group" );
677        }
678
679        $key = $keyspace;
680        foreach ( $components as $component ) {
681            // Escape delimiter (":") and escape ("%") characters
682            $key .= ':' . strtr( $component, [ '%' => '%25', ':' => '%3A' ] );
683        }
684
685        return $key;
686    }
687
688    /**
689     * Whether ::proxyCall() must re-encode cache keys before calling read/write methods.
690     *
691     * @stable to override
692     * @see BagOStuff::makeKeyInternal
693     * @see BagOStuff::proxyCall
694     * @since 1.41
695     * @return bool
696     */
697    protected function requireConvertGenericKey(): bool {
698        return false;
699    }
700
701    /**
702     * Convert a key from BagOStuff::makeKeyInternal into one for the current subclass
703     *
704     * @see BagOStuff::proxyCall
705     *
706     * @param string $key Result from BagOStuff::makeKeyInternal
707     *
708     * @return string Result from current subclass override of BagOStuff::makeKeyInternal
709     */
710    private function convertGenericKey( $key ) {
711        if ( !$this->requireConvertGenericKey() ) {
712            // If subclass doesn't overwrite makeKeyInternal, no re-encoding is needed.
713            return $key;
714        }
715
716        // Extract the components from a "generic" key formatted by BagOStuff::makeKeyInternal()
717        // Note that the order of each corresponding search/replace pair matters!
718        $components = str_replace( [ '%3A', '%25' ], [ ':', '%' ], explode( ':', $key ) );
719        if ( count( $components ) < 2 ) {
720            // Legacy key, not even formatted by makeKey()/makeGlobalKey(). Keep as-is.
721            return $key;
722        }
723
724        $keyspace = array_shift( $components );
725
726        return $this->makeKeyInternal( $keyspace, $components );
727    }
728
729    /**
730     * Call a method on behalf of wrapper BagOStuff instance
731     *
732     * The "wrapper" BagOStuff subclass that calls proxyCall() MUST NOT override
733     * the default makeKeyInternal() implementation, because proxyCall() needs
734     * to turn the "generic" key back into an array, and re-format it according
735     * to the backend-specific BagOStuff::makeKey implementation.
736     *
737     * For example, when using MultiWriteBagOStuff with Memcached as a backend,
738     * writes will go via MemcachedBagOStuff::proxyCall(), which then reformats
739     * the "generic" result of BagOStuff::makeKey (called as MultiWriteBagOStuff::makeKey)
740     * using MemcachedBagOStuff::makeKeyInternal.
741     *
742     * @param string $method Name of a non-final public method that reads/changes keys
743     * @param int $arg0Sig BagOStuff::ARG0_* constant describing argument 0
744     * @param int $resSig BagOStuff::RES_* constant describing the return value
745     * @param array $genericArgs Method arguments passed to the wrapper instance
746     * @param BagOStuff $wrapper The wrapper BagOStuff instance using this result
747     *
748     * @return mixed Method result with any keys remapped to "generic" keys
749     */
750    protected function proxyCall(
751        string $method,
752        int $arg0Sig,
753        int $resSig,
754        array $genericArgs,
755        BagOStuff $wrapper
756    ) {
757        // Get the corresponding store-specific cache keys...
758        $storeArgs = $genericArgs;
759        switch ( $arg0Sig ) {
760            case self::ARG0_KEY:
761                $storeArgs[0] = $this->convertGenericKey( $genericArgs[0] );
762                break;
763            case self::ARG0_KEYARR:
764                foreach ( $genericArgs[0] as $i => $genericKey ) {
765                    $storeArgs[0][$i] = $this->convertGenericKey( $genericKey );
766                }
767                break;
768            case self::ARG0_KEYMAP:
769                $storeArgs[0] = [];
770                foreach ( $genericArgs[0] as $genericKey => $v ) {
771                    $storeArgs[0][$this->convertGenericKey( $genericKey )] = $v;
772                }
773                break;
774        }
775
776        // Result of invoking the method with the corresponding store-specific cache keys
777        $watchPoint = $this->watchErrors();
778        $storeRes = $this->$method( ...$storeArgs );
779        $lastError = $this->getLastError( $watchPoint );
780        if ( $lastError !== self::ERR_NONE ) {
781            $wrapper->setLastError( $lastError );
782        }
783
784        // Convert any store-specific cache keys in the result back to generic cache keys
785        if ( $resSig === self::RES_KEYMAP ) {
786            // Map of (store-specific cache key => generic cache key)
787            $genericKeyByStoreKey = array_combine( $storeArgs[0], $genericArgs[0] );
788
789            $genericRes = [];
790            foreach ( $storeRes as $storeKey => $value ) {
791                $genericRes[$genericKeyByStoreKey[$storeKey]] = $value;
792            }
793        } else {
794            $genericRes = $storeRes;
795        }
796
797        return $genericRes;
798    }
799
800    /**
801     * @internal For testing only
802     * @return float UNIX timestamp
803     * @codeCoverageIgnore
804     */
805    public function getCurrentTime() {
806        return $this->wallClockOverride ?: microtime( true );
807    }
808
809    /**
810     * @internal For testing only
811     *
812     * @param float|null &$time Mock UNIX timestamp
813     *
814     * @codeCoverageIgnore
815     */
816    public function setMockTime( &$time ) {
817        $this->wallClockOverride =& $time;
818    }
819}
820
821/** @deprecated class alias since 1.43 */
822class_alias( BagOStuff::class, 'BagOStuff' );