includes/libs/objectcache/RedisBagOStuff.php

   1 <?php
   2 /**
   3  * Object caching using Redis (http://redis.io/).
   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  */
  22
  23 /**
  24  * Redis-based caching module for redis server >= 2.6.12 and phpredis >= 2.2.4
  25  *
  26  * @see https://github.com/phpredis/phpredis/blob/d310ed7c8/Changelog.md
  27  * @note Avoid use of Redis::MULTI transactions for twemproxy support
  28  *
  29  * @ingroup Cache
  30  * @ingroup Redis
  31  * @phan-file-suppress PhanTypeComparisonFromArray It's unclear whether exec() can return false
  32  */
  33 class RedisBagOStuff extends MediumSpecificBagOStuff {
  34         /** @var RedisConnectionPool */
  35         protected $redisPool;
  36         /** @var array List of server names */
  37         protected $servers;
  38         /** @var array Map of (tag => server name) */
  39         protected $serverTagMap;
  40         /** @var bool */
  41         protected $automaticFailover;
  42
  43         /**
  44          * Construct a RedisBagOStuff object. Parameters are:
  45          *
  46          *   - servers: An array of server names. A server name may be a hostname,
  47          *     a hostname/port combination or the absolute path of a UNIX socket.
  48          *     If a hostname is specified but no port, the standard port number
  49          *     6379 will be used. Arrays keys can be used to specify the tag to
  50          *     hash on in place of the host/port. Required.
  51          *
  52          *   - connectTimeout: The timeout for new connections, in seconds. Optional,
  53          *     default is 1 second.
  54          *
  55          *   - persistent: Set this to true to allow connections to persist across
  56          *     multiple web requests. False by default.
  57          *
  58          *   - password: The authentication password, will be sent to Redis in
  59          *     clear text. Optional, if it is unspecified, no AUTH command will be
  60          *     sent.
  61          *
  62          *   - automaticFailover: If this is false, then each key will be mapped to
  63          *     a single server, and if that server is down, any requests for that key
  64          *     will fail. If this is true, a connection failure will cause the client
  65          *     to immediately try the next server in the list (as determined by a
  66          *     consistent hashing algorithm). True by default. This has the
  67          *     potential to create consistency issues if a server is slow enough to
  68          *     flap, for example if it is in swap death.
  69          * @param array $params
  70          */
  71         function __construct( $params ) {
  72                 parent::__construct( $params );
  73                 $redisConf = [ 'serializer' => 'none' ]; // manage that in this class
  74                 foreach ( [ 'connectTimeout', 'persistent', 'password' ] as $opt ) {
  75                         if ( isset( $params[$opt] ) ) {
  76                                 $redisConf[$opt] = $params[$opt];
  77                         }
  78                 }
  79                 $this->redisPool = RedisConnectionPool::singleton( $redisConf );
  80
  81                 $this->servers = $params['servers'];
  82                 foreach ( $this->servers as $key => $server ) {
  83                         $this->serverTagMap[is_int( $key ) ? $server : $key] = $server;
  84                 }
  85
  86                 $this->automaticFailover = $params['automaticFailover'] ?? true;
  87
  88                 $this->attrMap[self::ATTR_SYNCWRITES] = self::QOS_SYNCWRITES_NONE;
  89         }
  90
  91         protected function doGet( $key, $flags = 0, &$casToken = null ) {
  92                 $casToken = null;
  93
  94                 $conn = $this->getConnection( $key );
  95                 if ( !$conn ) {
  96                         return false;
  97                 }
  98
  99                 $e = null;
 100                 try {
 101                         $value = $conn->get( $key );
 102                         $casToken = $value;
 103                         $result = $this->unserialize( $value );
 104                 } catch ( RedisException $e ) {
 105                         $result = false;
 106                         $this->handleException( $conn, $e );
 107                 }
 108
 109                 $this->logRequest( 'get', $key, $conn->getServer(), $e );
 110
 111                 return $result;
 112         }
 113
 114         protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) {
 115                 $conn = $this->getConnection( $key );
 116                 if ( !$conn ) {
 117                         return false;
 118                 }
 119
 120                 $ttl = $this->getExpirationAsTTL( $exptime );
 121
 122                 $e = null;
 123                 try {
 124                         if ( $ttl ) {
 125                                 $result = $conn->setex( $key, $ttl, $this->serialize( $value ) );
 126                         } else {
 127                                 $result = $conn->set( $key, $this->serialize( $value ) );
 128                         }
 129                 } catch ( RedisException $e ) {
 130                         $result = false;
 131                         $this->handleException( $conn, $e );
 132                 }
 133
 134                 $this->logRequest( 'set', $key, $conn->getServer(), $e );
 135
 136                 return $result;
 137         }
 138
 139         protected function doDelete( $key, $flags = 0 ) {
 140                 $conn = $this->getConnection( $key );
 141                 if ( !$conn ) {
 142                         return false;
 143                 }
 144
 145                 $e = null;
 146                 try {
 147                         // Note that redis does not return false if the key was not there
 148                         $result = ( $conn->del( $key ) !== false );
 149                 } catch ( RedisException $e ) {
 150                         $result = false;
 151                         $this->handleException( $conn, $e );
 152                 }
 153
 154                 $this->logRequest( 'delete', $key, $conn->getServer(), $e );
 155
 156                 return $result;
 157         }
 158
 159         protected function doGetMulti( array $keys, $flags = 0 ) {
 160                 /** @var RedisConnRef[]|Redis[] $conns */
 161                 $conns = [];
 162                 $batches = [];
 163                 foreach ( $keys as $key ) {
 164                         $conn = $this->getConnection( $key );
 165                         if ( $conn ) {
 166                                 $server = $conn->getServer();
 167                                 $conns[$server] = $conn;
 168                                 $batches[$server][] = $key;
 169                         }
 170                 }
 171
 172                 $result = [];
 173                 foreach ( $batches as $server => $batchKeys ) {
 174                         $conn = $conns[$server];
 175
 176                         $e = null;
 177                         try {
 178                                 // Avoid mget() to reduce CPU hogging from a single request
 179                                 $conn->multi( Redis::PIPELINE );
 180                                 foreach ( $batchKeys as $key ) {
 181                                         $conn->get( $key );
 182                                 }
 183                                 $batchResult = $conn->exec();
 184                                 if ( $batchResult === false ) {
 185                                         $this->logRequest( 'get', implode( ',', $batchKeys ), $server, true );
 186                                         continue;
 187                                 }
 188
 189                                 foreach ( $batchResult as $i => $value ) {
 190                                         if ( $value !== false ) {
 191                                                 $result[$batchKeys[$i]] = $this->unserialize( $value );
 192                                         }
 193                                 }
 194                         } catch ( RedisException $e ) {
 195                                 $this->handleException( $conn, $e );
 196                         }
 197
 198                         $this->logRequest( 'get', implode( ',', $batchKeys ), $server, $e );
 199                 }
 200
 201                 return $result;
 202         }
 203
 204         protected function doSetMulti( array $data, $exptime = 0, $flags = 0 ) {
 205                 /** @var RedisConnRef[]|Redis[] $conns */
 206                 $conns = [];
 207                 $batches = [];
 208                 foreach ( $data as $key => $value ) {
 209                         $conn = $this->getConnection( $key );
 210                         if ( $conn ) {
 211                                 $server = $conn->getServer();
 212                                 $conns[$server] = $conn;
 213                                 $batches[$server][] = $key;
 214                         }
 215                 }
 216
 217                 $ttl = $this->getExpirationAsTTL( $exptime );
 218                 $op = $ttl ? 'setex' : 'set';
 219
 220                 $result = true;
 221                 foreach ( $batches as $server => $batchKeys ) {
 222                         $conn = $conns[$server];
 223
 224                         $e = null;
 225                         try {
 226                                 // Avoid mset() to reduce CPU hogging from a single request
 227                                 $conn->multi( Redis::PIPELINE );
 228                                 foreach ( $batchKeys as $key ) {
 229                                         if ( $ttl ) {
 230                                                 $conn->setex( $key, $ttl, $this->serialize( $data[$key] ) );
 231                                         } else {
 232                                                 $conn->set( $key, $this->serialize( $data[$key] ) );
 233                                         }
 234                                 }
 235                                 $batchResult = $conn->exec();
 236                                 if ( $batchResult === false ) {
 237                                         $this->logRequest( $op, implode( ',', $batchKeys ), $server, true );
 238                                         continue;
 239                                 }
 240                                 $result = $result && !in_array( false, $batchResult, true );
 241                         } catch ( RedisException $e ) {
 242                                 $this->handleException( $conn, $e );
 243                                 $result = false;
 244                         }
 245
 246                         $this->logRequest( $op, implode( ',', $batchKeys ), $server, $e );
 247                 }
 248
 249                 return $result;
 250         }
 251
 252         protected function doDeleteMulti( array $keys, $flags = 0 ) {
 253                 /** @var RedisConnRef[]|Redis[] $conns */
 254                 $conns = [];
 255                 $batches = [];
 256                 foreach ( $keys as $key ) {
 257                         $conn = $this->getConnection( $key );
 258                         if ( $conn ) {
 259                                 $server = $conn->getServer();
 260                                 $conns[$server] = $conn;
 261                                 $batches[$server][] = $key;
 262                         }
 263                 }
 264
 265                 $result = true;
 266                 foreach ( $batches as $server => $batchKeys ) {
 267                         $conn = $conns[$server];
 268
 269                         $e = null;
 270                         try {
 271                                 // Avoid delete() with array to reduce CPU hogging from a single request
 272                                 $conn->multi( Redis::PIPELINE );
 273                                 foreach ( $batchKeys as $key ) {
 274                                         $conn->del( $key );
 275                                 }
 276                                 $batchResult = $conn->exec();
 277                                 if ( $batchResult === false ) {
 278                                         $this->logRequest( 'delete', implode( ',', $batchKeys ), $server, true );
 279                                         continue;
 280                                 }
 281                                 // Note that redis does not return false if the key was not there
 282                                 $result = $result && !in_array( false, $batchResult, true );
 283                         } catch ( RedisException $e ) {
 284                                 $this->handleException( $conn, $e );
 285                                 $result = false;
 286                         }
 287
 288                         $this->logRequest( 'delete', implode( ',', $batchKeys ), $server, $e );
 289                 }
 290
 291                 return $result;
 292         }
 293
 294         public function changeTTLMulti( array $keys, $exptime, $flags = 0 ) {
 295                 /** @var RedisConnRef[]|Redis[] $conns */
 296                 $conns = [];
 297                 $batches = [];
 298                 foreach ( $keys as $key ) {
 299                         $conn = $this->getConnection( $key );
 300                         if ( $conn ) {
 301                                 $server = $conn->getServer();
 302                                 $conns[$server] = $conn;
 303                                 $batches[$server][] = $key;
 304                         }
 305                 }
 306
 307                 $relative = $this->isRelativeExpiration( $exptime );
 308                 $op = ( $exptime == self::TTL_INDEFINITE )
 309                         ? 'persist'
 310                         : ( $relative ? 'expire' : 'expireAt' );
 311
 312                 $result = true;
 313                 foreach ( $batches as $server => $batchKeys ) {
 314                         $conn = $conns[$server];
 315
 316                         $e = null;
 317                         try {
 318                                 $conn->multi( Redis::PIPELINE );
 319                                 foreach ( $batchKeys as $key ) {
 320                                         if ( $exptime == self::TTL_INDEFINITE ) {
 321                                                 $conn->persist( $key );
 322                                         } elseif ( $relative ) {
 323                                                 $conn->expire( $key, $this->getExpirationAsTTL( $exptime ) );
 324                                         } else {
 325                                                 $conn->expireAt( $key, $this->getExpirationAsTimestamp( $exptime ) );
 326                                         }
 327                                 }
 328                                 $batchResult = $conn->exec();
 329                                 if ( $batchResult === false ) {
 330                                         $this->logRequest( $op, implode( ',', $batchKeys ), $server, true );
 331                                         continue;
 332                                 }
 333                                 $result = in_array( false, $batchResult, true ) ? false : $result;
 334                         } catch ( RedisException $e ) {
 335                                 $this->handleException( $conn, $e );
 336                                 $result = false;
 337                         }
 338
 339                         $this->logRequest( $op, implode( ',', $batchKeys ), $server, $e );
 340                 }
 341
 342                 return $result;
 343         }
 344
 345         protected function doAdd( $key, $value, $expiry = 0, $flags = 0 ) {
 346                 $conn = $this->getConnection( $key );
 347                 if ( !$conn ) {
 348                         return false;
 349                 }
 350
 351                 $ttl = $this->getExpirationAsTTL( $expiry );
 352                 try {
 353                         $result = $conn->set(
 354                                 $key,
 355                                 $this->serialize( $value ),
 356                                 $ttl ? [ 'nx', 'ex' => $ttl ] : [ 'nx' ]
 357                         );
 358                 } catch ( RedisException $e ) {
 359                         $result = false;
 360                         $this->handleException( $conn, $e );
 361                 }
 362
 363                 $this->logRequest( 'add', $key, $conn->getServer(), $result );
 364
 365                 return $result;
 366         }
 367
 368         public function incr( $key, $value = 1, $flags = 0 ) {
 369                 $conn = $this->getConnection( $key );
 370                 if ( !$conn ) {
 371                         return false;
 372                 }
 373
 374                 try {
 375                         if ( !$conn->exists( $key ) ) {
 376                                 return false;
 377                         }
 378                         // @FIXME: on races, the key may have a 0 TTL
 379                         $result = $conn->incrBy( $key, $value );
 380                 } catch ( RedisException $e ) {
 381                         $result = false;
 382                         $this->handleException( $conn, $e );
 383                 }
 384
 385                 $this->logRequest( 'incr', $key, $conn->getServer(), $result );
 386
 387                 return $result;
 388         }
 389
 390         public function decr( $key, $value = 1, $flags = 0 ) {
 391                 $conn = $this->getConnection( $key );
 392                 if ( !$conn ) {
 393                         return false;
 394                 }
 395
 396                 try {
 397                         if ( !$conn->exists( $key ) ) {
 398                                 return false;
 399                         }
 400                         // @FIXME: on races, the key may have a 0 TTL
 401                         $result = $conn->decrBy( $key, $value );
 402                 } catch ( RedisException $e ) {
 403                         $result = false;
 404                         $this->handleException( $conn, $e );
 405                 }
 406
 407                 $this->logRequest( 'decr', $key, $conn->getServer(), $result );
 408
 409                 return $result;
 410         }
 411
 412         protected function doChangeTTL( $key, $exptime, $flags ) {
 413                 $conn = $this->getConnection( $key );
 414                 if ( !$conn ) {
 415                         return false;
 416                 }
 417
 418                 $relative = $this->isRelativeExpiration( $exptime );
 419                 try {
 420                         if ( $exptime == self::TTL_INDEFINITE ) {
 421                                 $result = $conn->persist( $key );
 422                                 $this->logRequest( 'persist', $key, $conn->getServer(), $result );
 423                         } elseif ( $relative ) {
 424                                 $result = $conn->expire( $key, $this->getExpirationAsTTL( $exptime ) );
 425                                 $this->logRequest( 'expire', $key, $conn->getServer(), $result );
 426                         } else {
 427                                 $result = $conn->expireAt( $key, $this->getExpirationAsTimestamp( $exptime ) );
 428                                 $this->logRequest( 'expireAt', $key, $conn->getServer(), $result );
 429                         }
 430                 } catch ( RedisException $e ) {
 431                         $result = false;
 432                         $this->handleException( $conn, $e );
 433                 }
 434
 435                 return $result;
 436         }
 437
 438         /**
 439          * @param string $key
 440          * @return RedisConnRef|Redis|null Redis handle wrapper for the key or null on failure
 441          */
 442         protected function getConnection( $key ) {
 443                 $candidates = array_keys( $this->serverTagMap );
 444
 445                 if ( count( $this->servers ) > 1 ) {
 446                         ArrayUtils::consistentHashSort( $candidates, $key, '/' );
 447                         if ( !$this->automaticFailover ) {
 448                                 $candidates = array_slice( $candidates, 0, 1 );
 449                         }
 450                 }
 451
 452                 while ( ( $tag = array_shift( $candidates ) ) !== null ) {
 453                         $server = $this->serverTagMap[$tag];
 454                         $conn = $this->redisPool->getConnection( $server, $this->logger );
 455                         if ( !$conn ) {
 456                                 continue;
 457                         }
 458
 459                         // If automatic failover is enabled, check that the server's link
 460                         // to its master (if any) is up -- but only if there are other
 461                         // viable candidates left to consider. Also, getMasterLinkStatus()
 462                         // does not work with twemproxy, though $candidates will be empty
 463                         // by now in such cases.
 464                         if ( $this->automaticFailover && $candidates ) {
 465                                 try {
 466                                         /** @var string[] $info */
 467                                         $info = $conn->info();
 468                                         if ( ( $info['master_link_status'] ?? null ) === 'down' ) {
 469                                                 // If the master cannot be reached, fail-over to the next server.
 470                                                 // If masters are in data-center A, and replica DBs in data-center B,
 471                                                 // this helps avoid the case were fail-over happens in A but not
 472                                                 // to the corresponding server in B (e.g. read/write mismatch).
 473                                                 continue;
 474                                         }
 475                                 } catch ( RedisException $e ) {
 476                                         // Server is not accepting commands
 477                                         $this->redisPool->handleError( $conn, $e );
 478                                         continue;
 479                                 }
 480                         }
 481
 482                         return $conn;
 483                 }
 484
 485                 $this->setLastError( BagOStuff::ERR_UNREACHABLE );
 486
 487                 return null;
 488         }
 489
 490         /**
 491          * Log a fatal error
 492          * @param string $msg
 493          */
 494         protected function logError( $msg ) {
 495                 $this->logger->error( "Redis error: $msg" );
 496         }
 497
 498         /**
 499          * The redis extension throws an exception in response to various read, write
 500          * and protocol errors. Sometimes it also closes the connection, sometimes
 501          * not. The safest response for us is to explicitly destroy the connection
 502          * object and let it be reopened during the next request.
 503          * @param RedisConnRef $conn
 504          * @param RedisException $e
 505          */
 506         protected function handleException( RedisConnRef $conn, RedisException $e ) {
 507                 $this->setLastError( BagOStuff::ERR_UNEXPECTED );
 508                 $this->redisPool->handleError( $conn, $e );
 509         }
 510
 511         /**
 512          * Send information about a single request to the debug log
 513          * @param string $op
 514          * @param string $keys
 515          * @param string $server
 516          * @param Exception|bool|null $e
 517          */
 518         public function logRequest( $op, $keys, $server, $e = null ) {
 519                 $this->debug( "$op($keys) on $server: " . ( $e ? "failure" : "success" ) );
 520         }
 521 }