BagOStuff.php

Go to the documentation of this file.

<?php
namespace Wikimedia\ObjectCache;
 
use InvalidArgumentException;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Wikimedia\LightweightObjectStore\ExpirationAwareness;
use Wikimedia\ScopedCallback;
use Wikimedia\Stats\StatsFactory;
 
abstract class BagOStuff implements
    ExpirationAwareness,
    IStoreKeyEncoder,
    LoggerAwareInterface
{
    protected $stats;
    protected $logger;
    protected $asyncHandler;
    protected $attrMap = [];
 
    protected $keyspace;
 
    protected $lastError = self::ERR_NONE;
    protected $lastErrorId = 0;
 
    protected static $nextErrorMonitorId = 1;
 
    private $wallClockOverride;
 
    public const ERR_NONE = 0;
    public const ERR_NO_RESPONSE = 1;
    public const ERR_UNREACHABLE = 2;
    public const ERR_UNEXPECTED = 3;
 
    public const ATTR_DURABILITY = 2;
    public const QOS_DURABILITY_NONE = 1;
    public const QOS_DURABILITY_SCRIPT = 2;
    public const QOS_DURABILITY_SERVICE = 3;
    public const QOS_DURABILITY_DISK = 4;
    public const QOS_DURABILITY_RDBMS = 5;
    public const QOS_UNKNOWN = INF;
 
    public const READ_LATEST = 1;
    public const READ_VERIFIED = 2;
 
    public const WRITE_CACHE_ONLY = 8;
    public const WRITE_ALLOW_SEGMENTS = 16;
 
    public const WRITE_BACKGROUND = 64;
 
    public const MAX_CONFLICTS_ONE = 1;
 
    protected const GLOBAL_KEYSPACE = 'global';
    protected const GLOBAL_PREFIX = 'global:';
 
    protected const ARG0_KEY = 0;
    protected const ARG0_KEYARR = 1;
    protected const ARG0_KEYMAP = 2;
    protected const ARG0_NONKEY = 3;
 
    protected const RES_KEYMAP = 0;
    protected const RES_NONKEY = 1;
 
    public function __construct( array $params = [] ) {
        $this->keyspace = $params['keyspace'] ?? 'local';
        $this->stats = $params['stats'] ?? StatsFactory::newNull();
        $this->setLogger( $params['logger'] ?? new NullLogger() );
 
        $asyncHandler = $params['asyncHandler'] ?? null;
        if ( is_callable( $asyncHandler ) ) {
            $this->asyncHandler = $asyncHandler;
        }
    }
 
    public function setLogger( LoggerInterface $logger ): void {
        $this->logger = $logger;
    }
 
    public function getLogger(): LoggerInterface {
        return $this->logger;
    }
 
    final public function getWithSetCallback( $key, $exptime, $callback, $flags = 0 ) {
        $value = $this->get( $key, $flags );
 
        if ( $value === false ) {
            $value = $callback( $exptime );
            if ( $value !== false && $exptime >= 0 ) {
                $this->set( $key, $value, $exptime, $flags );
            }
        }
 
        return $value;
    }
 
    abstract public function get( $key, $flags = 0 );
 
    abstract public function set( $key, $value, $exptime = 0, $flags = 0 );
 
    abstract public function delete( $key, $flags = 0 );
 
    abstract public function add( $key, $value, $exptime = 0, $flags = 0 );
 
    abstract public function merge(
        $key,
        callable $callback,
        $exptime = 0,
        $attempts = 10,
        $flags = 0
    );
 
    abstract public function changeTTL( $key, $exptime = 0, $flags = 0 );
 
    abstract public function lock( $key, $timeout = 6, $exptime = 6, $rclass = '' );
 
    abstract public function unlock( $key );
 
    final public function getScopedLock( $key, $timeout = 6, $exptime = 30, $rclass = '' ) {
        $exptime = min( $exptime ?: INF, self::TTL_DAY );
 
        if ( !$this->lock( $key, $timeout, $exptime, $rclass ) ) {
            return null;
        }
 
        return new ScopedCallback( function () use ( $key ) {
            $this->unlock( $key );
        } );
    }
 
    abstract public function deleteObjectsExpiringBefore(
        $timestamp,
        ?callable $progress = null,
        $limit = INF,
        ?string $tag = null
    );
 
    abstract public function getMulti( array $keys, $flags = 0 );
 
    abstract public function setMulti( array $valueByKey, $exptime = 0, $flags = 0 );
 
    abstract public function deleteMulti( array $keys, $flags = 0 );
 
    abstract public function changeTTLMulti( array $keys, $exptime, $flags = 0 );
 
    abstract public function incrWithInit( $key, $exptime, $step = 1, $init = null, $flags = 0 );
 
    public function watchErrors() {
        return self::$nextErrorMonitorId++;
    }
 
    public function getLastError( $watchPoint = 0 ) {
        return ( $this->lastErrorId > $watchPoint ) ? $this->lastError : self::ERR_NONE;
    }
 
    protected function setLastError( $error ) {
        $this->lastError = $error;
        $this->lastErrorId = self::$nextErrorMonitorId++;
    }
 
    public function makeGlobalKey( $keygroup, ...$components ) {
        return $this->makeKeyInternal( self::GLOBAL_KEYSPACE, func_get_args() );
    }
 
    public function makeKey( $keygroup, ...$components ) {
        return $this->makeKeyInternal( $this->keyspace, func_get_args() );
    }
 
    public function isKeyGlobal( $key ) {
        return str_starts_with( $key, self::GLOBAL_PREFIX );
    }
 
    public function getQoS( $flag ) {
        return $this->attrMap[$flag] ?? self::QOS_UNKNOWN;
    }
 
    public function getSegmentationSize() {
        wfDeprecated( __METHOD__, '1.43' );
 
        return INF;
    }
 
    public function getSegmentedValueMaxSize() {
        wfDeprecated( __METHOD__, '1.43' );
 
        return INF;
    }
 
    final protected function fieldHasFlags( $field, $flags ) {
        return ( ( $field & $flags ) === $flags );
    }
 
    final protected function mergeFlagMaps( array $bags ) {
        $map = [];
        foreach ( $bags as $bag ) {
            foreach ( $bag->attrMap as $attr => $rank ) {
                if ( isset( $map[$attr] ) ) {
                    $map[$attr] = min( $map[$attr], $rank );
                } else {
                    $map[$attr] = $rank;
                }
            }
        }
 
        return $map;
    }
 
    protected function makeKeyInternal( $keyspace, $components ) {
        if ( count( $components ) < 1 ) {
            throw new InvalidArgumentException( "Missing key group" );
        }
 
        $key = $keyspace;
        foreach ( $components as $component ) {
            // Escape delimiter (":") and escape ("%") characters
            $key .= ':' . strtr( $component ?? '', [ '%' => '%25', ':' => '%3A' ] );
        }
 
        return $key;
    }
 
    protected function makeFallbackKey( string $key, int $maxLength ) {
        if ( strlen( $key ) > $maxLength ) {
            // Components are "<0=keyspace>:<1=keygroup>:<others...>"
            $components = str_replace( [ '%3A', '%25' ], [ ':', '%' ], explode( ':', $key ) );
            if ( count( $components ) < 2 ) {
                throw new InvalidArgumentException( 'Key lacks keyspace' );
            }
 
            // Prefer to preserve the keygroup for statistics.
            // Try "mywiki:mykeygroup:#<64-char hash>"
            // This gives 138 chars (205-64-3) for the keyspace and keygroup.
            $hash = hash( 'sha256', $key );
            $key = $components[0] . ':' . $components[1] . ':#' . $hash;
            if ( strlen( $key ) > $maxLength ) {
                // Try "mywiki:BagOStuff-long-key:##<64-char hash>"
                // Might be legacy code that passes a long string as the key without a keygroup.
                $key = $components[0] . ':BagOStuff-long-key:##' . $hash;
            }
        }
 
        return $key;
    }
 
    protected function requireConvertGenericKey(): bool {
        return false;
    }
 
    private function convertGenericKey( $key ) {
        if ( !$this->requireConvertGenericKey() ) {
            // If subclass doesn't overwrite makeKeyInternal, no re-encoding is needed.
            return $key;
        }
 
        // Extract the components from a "generic" key formatted by BagOStuff::makeKeyInternal()
        // Note that the order of each corresponding search/replace pair matters!
        $components = str_replace( [ '%3A', '%25' ], [ ':', '%' ], explode( ':', $key ) );
        if ( count( $components ) < 2 ) {
            // Legacy key, not even formatted by makeKey()/makeGlobalKey(). Keep as-is.
            return $key;
        }
 
        $keyspace = array_shift( $components );
 
        return $this->makeKeyInternal( $keyspace, $components );
    }
 
    protected function proxyCall(
        string $method,
        int $arg0Sig,
        int $resSig,
        array $genericArgs,
        BagOStuff $wrapper
    ) {
        // Get the corresponding store-specific cache keys...
        $storeArgs = $genericArgs;
        switch ( $arg0Sig ) {
            case self::ARG0_KEY:
                $storeArgs[0] = $this->convertGenericKey( $genericArgs[0] );
                break;
            case self::ARG0_KEYARR:
                foreach ( $genericArgs[0] as $i => $genericKey ) {
                    $storeArgs[0][$i] = $this->convertGenericKey( $genericKey );
                }
                break;
            case self::ARG0_KEYMAP:
                $storeArgs[0] = [];
                foreach ( $genericArgs[0] as $genericKey => $v ) {
                    $storeArgs[0][$this->convertGenericKey( $genericKey )] = $v;
                }
                break;
        }
 
        // Result of invoking the method with the corresponding store-specific cache keys
        $watchPoint = $this->watchErrors();
        $storeRes = $this->$method( ...$storeArgs );
        $lastError = $this->getLastError( $watchPoint );
        if ( $lastError !== self::ERR_NONE ) {
            $wrapper->setLastError( $lastError );
        }
 
        // Convert any store-specific cache keys in the result back to generic cache keys
        if ( $resSig === self::RES_KEYMAP ) {
            // Map of (store-specific cache key => generic cache key)
            $genericKeyByStoreKey = array_combine( $storeArgs[0], $genericArgs[0] );
 
            $genericRes = [];
            foreach ( $storeRes as $storeKey => $value ) {
                $genericRes[$genericKeyByStoreKey[$storeKey]] = $value;
            }
        } else {
            $genericRes = $storeRes;
        }
 
        return $genericRes;
    }
 
    public function getCurrentTime() {
        return $this->wallClockOverride ?: microtime( true );
    }
 
    public function setMockTime( &$time ) {
        $this->wallClockOverride =& $time;
    }
}
 
class_alias( BagOStuff::class, 'BagOStuff' );