includes/libs/objectcache/WANObjectCacheReaper.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  * @ingroup Cache
  20  */
  21
  22 use Psr\Log\LoggerAwareInterface;
  23 use Psr\Log\LoggerInterface;
  24 use Psr\Log\NullLogger;
  25 use Wikimedia\ScopedCallback;
  26
  27 /**
  28  * Class for scanning through chronological, log-structured data or change logs
  29  * and locally purging cache keys related to entities that appear in this data.
  30  *
  31  * This is useful for repairing cache when purges are missed by using a reliable
  32  * stream, such as Kafka or a replicated MySQL table. Purge loss between datacenters
  33  * is expected to be more common than within them.
  34  *
  35  * @since 1.28
  36  */
  37 class WANObjectCacheReaper implements LoggerAwareInterface {
  38         /** @var WANObjectCache */
  39         protected $cache;
  40         /** @var BagOStuff */
  41         protected $store;
  42         /** @var callable */
  43         protected $logChunkCallback;
  44         /** @var callable */
  45         protected $keyListCallback;
  46         /** @var LoggerInterface */
  47         protected $logger;
  48
  49         /** @var string */
  50         protected $channel;
  51         /** @var int */
  52         protected $initialStartWindow;
  53
  54         /**
  55          * @param WANObjectCache $cache Cache to reap bad keys from
  56          * @param BagOStuff $store Cache to store positions use for locking
  57          * @param callable $logCallback Callback taking arguments:
  58          *          - The starting position as a UNIX timestamp
  59          *          - The starting unique ID used for breaking timestamp collisions or null
  60          *          - The ending position as a UNIX timestamp
  61          *          - The maximum number of results to return
  62          *        It returns a list of maps of (key: cache key, pos: UNIX timestamp, id: unique ID)
  63          *        for each key affected, with the corrosponding event timestamp/ID information.
  64          *        The events should be in ascending order, by (timestamp,id).
  65          * @param callable $keyCallback Callback taking arguments:
  66          *          - The WANObjectCache instance
  67          *          - An object from the event log
  68          *        It should return a list of WAN cache keys.
  69          *        The callback must fully duck-type test the object, since can be any model class.
  70          * @param array $params Additional options:
  71          *          - channel: the name of the update event stream.
  72          *          - initialStartWindow: seconds back in time to start if the position is lost.
  73          *            Default: 1 hour.
  74          *          - logger: an SPL monolog instance [optional]
  75          */
  76         public function __construct(
  77                 WANObjectCache $cache,
  78                 BagOStuff $store,
  79                 callable $logCallback,
  80                 callable $keyCallback,
  81                 array $params
  82         ) {
  83                 $this->cache = $cache;
  84                 $this->store = $store;
  85
  86                 $this->logChunkCallback = $logCallback;
  87                 $this->keyListCallback = $keyCallback;
  88                 if ( isset( $params['channel'] ) ) {
  89                         $this->channel = $params['channel'];
  90                 } else {
  91                         throw new UnexpectedValueException( "No channel specified." );
  92                 }
  93
  94                 $this->initialStartWindow = $params['initialStartWindow'] ?? 3600;
  95                 $this->logger = $params['logger'] ?? new NullLogger();
  96         }
  97
  98         public function setLogger( LoggerInterface $logger ) {
  99                 $this->logger = $logger;
 100         }
 101
 102         /**
 103          * Check and reap stale keys based on a chunk of events
 104          *
 105          * @param int $n Number of events
 106          * @return int Number of keys checked
 107          */
 108         final public function invoke( $n = 100 ) {
 109                 $posKey = $this->store->makeGlobalKey( 'WANCache', 'reaper', $this->channel );
 110                 $scopeLock = $this->store->getScopedLock( "$posKey:busy", 0 );
 111                 if ( !$scopeLock ) {
 112                         return 0;
 113                 }
 114
 115                 $now = time();
 116                 $status = $this->store->get( $posKey );
 117                 if ( !$status ) {
 118                         $status = [ 'pos' => $now - $this->initialStartWindow, 'id' => null ];
 119                 }
 120
 121                 // Get events for entities who's keys tombstones/hold-off should have expired by now
 122                 $events = call_user_func_array(
 123                         $this->logChunkCallback,
 124                         [ $status['pos'], $status['id'], $now - WANObjectCache::HOLDOFF_TTL - 1, $n ]
 125                 );
 126
 127                 $event = null;
 128                 $keyEvents = [];
 129                 foreach ( $events as $event ) {
 130                         $keys = call_user_func_array(
 131                                 $this->keyListCallback,
 132                                 [ $this->cache, $event['item'] ]
 133                         );
 134                         foreach ( $keys as $key ) {
 135                                 unset( $keyEvents[$key] ); // use only the latest per key
 136                                 $keyEvents[$key] = [
 137                                         'pos' => $event['pos'],
 138                                         'id' => $event['id']
 139                                 ];
 140                         }
 141                 }
 142
 143                 $purgeCount = 0;
 144                 $lastOkEvent = null;
 145                 foreach ( $keyEvents as $key => $keyEvent ) {
 146                         if ( !$this->cache->reap( $key, $keyEvent['pos'] ) ) {
 147                                 break;
 148                         }
 149                         ++$purgeCount;
 150                         $lastOkEvent = $event;
 151                 }
 152
 153                 if ( $lastOkEvent ) {
 154                         $ok = $this->store->merge(
 155                                 $posKey,
 156                                 function ( $bag, $key, $curValue ) use ( $lastOkEvent ) {
 157                                         if ( !$curValue ) {
 158                                                 // Use new position
 159                                         } else {
 160                                                 $curCoord = [ $curValue['pos'], $curValue['id'] ];
 161                                                 $newCoord = [ $lastOkEvent['pos'], $lastOkEvent['id'] ];
 162                                                 if ( $newCoord < $curCoord ) {
 163                                                         // Keep prior position instead of rolling it back
 164                                                         return $curValue;
 165                                                 }
 166                                         }
 167
 168                                         return [
 169                                                 'pos' => $lastOkEvent['pos'],
 170                                                 'id' => $lastOkEvent['id'],
 171                                                 'ctime' => $curValue ? $curValue['ctime'] : date( 'c' )
 172                                         ];
 173                                 },
 174                                 IExpiringStore::TTL_INDEFINITE
 175                         );
 176
 177                         $pos = $lastOkEvent['pos'];
 178                         $id = $lastOkEvent['id'];
 179                         if ( $ok ) {
 180                                 $this->logger->info( "Updated cache reap position ($pos, $id)." );
 181                         } else {
 182                                 $this->logger->error( "Could not update cache reap position ($pos, $id)." );
 183                         }
 184                 }
 185
 186                 ScopedCallback::consume( $scopeLock );
 187
 188                 return $purgeCount;
 189         }
 190
 191         /**
 192          * @return array|bool Returns (pos, id) map or false if not set
 193          */
 194         public function getState() {
 195                 $posKey = $this->store->makeGlobalKey( 'WANCache', 'reaper', $this->channel );
 196
 197                 return $this->store->get( $posKey );
 198         }
 199 }