includes/resourceloader/MessageBlobStore.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  * @author Roan Kattouw
  20  * @author Trevor Parscal
  21  */
  22
  23 use MediaWiki\MediaWikiServices;
  24 use Psr\Log\LoggerAwareInterface;
  25 use Psr\Log\LoggerInterface;
  26 use Psr\Log\NullLogger;
  27 use Wikimedia\Rdbms\Database;
  28
  29 /**
  30  * This class generates message blobs for use by ResourceLoader.
  31  *
  32  * A message blob is a JSON object containing the interface messages for a
  33  * certain module in a certain language.
  34  *
  35  * @ingroup ResourceLoader
  36  * @since 1.17
  37  */
  38 class MessageBlobStore implements LoggerAwareInterface {
  39
  40         /* @var ResourceLoader */
  41         private $resourceloader;
  42
  43         /**
  44          * @var LoggerInterface
  45          */
  46         protected $logger;
  47
  48         /**
  49          * @var WANObjectCache
  50          */
  51         protected $wanCache;
  52
  53         /**
  54          * @param ResourceLoader $rl
  55          * @param LoggerInterface|null $logger
  56          */
  57         public function __construct( ResourceLoader $rl, LoggerInterface $logger = null ) {
  58                 $this->resourceloader = $rl;
  59                 $this->logger = $logger ?: new NullLogger();
  60
  61                 // NOTE: when changing this assignment, make sure the code in the instantiator for
  62                 // LocalisationCache which calls MessageBlobStore::clearGlobalCacheEntry() uses the
  63                 // same cache object.
  64                 $this->wanCache = MediaWikiServices::getInstance()->getMainWANObjectCache();
  65         }
  66
  67         /**
  68          * @since 1.27
  69          * @param LoggerInterface $logger
  70          */
  71         public function setLogger( LoggerInterface $logger ) {
  72                 $this->logger = $logger;
  73         }
  74
  75         /**
  76          * Get the message blob for a module
  77          *
  78          * @since 1.27
  79          * @param ResourceLoaderModule $module
  80          * @param string $lang Language code
  81          * @return string JSON
  82          */
  83         public function getBlob( ResourceLoaderModule $module, $lang ) {
  84                 $blobs = $this->getBlobs( [ $module->getName() => $module ], $lang );
  85                 return $blobs[$module->getName()];
  86         }
  87
  88         /**
  89          * Get the message blobs for a set of modules
  90          *
  91          * @since 1.27
  92          * @param ResourceLoaderModule[] $modules Array of module objects keyed by name
  93          * @param string $lang Language code
  94          * @return array An array mapping module names to message blobs
  95          */
  96         public function getBlobs( array $modules, $lang ) {
  97                 // Each cache key for a message blob by module name and language code also has a generic
  98                 // check key without language code. This is used to invalidate any and all language subkeys
  99                 // that exist for a module from the updateMessage() method.
 100                 $cache = $this->wanCache;
 101                 $checkKeys = [
 102                         // Global check key, see clear()
 103                         $cache->makeGlobalKey( __CLASS__ )
 104                 ];
 105                 $cacheKeys = [];
 106                 foreach ( $modules as $name => $module ) {
 107                         $cacheKey = $this->makeCacheKey( $module, $lang );
 108                         $cacheKeys[$name] = $cacheKey;
 109                         // Per-module check key, see updateMessage()
 110                         $checkKeys[$cacheKey][] = $cache->makeKey( __CLASS__, $name );
 111                 }
 112                 $curTTLs = [];
 113                 $result = $cache->getMulti( array_values( $cacheKeys ), $curTTLs, $checkKeys );
 114
 115                 $blobs = [];
 116                 foreach ( $modules as $name => $module ) {
 117                         $key = $cacheKeys[$name];
 118                         if ( !isset( $result[$key] ) || $curTTLs[$key] === null || $curTTLs[$key] < 0 ) {
 119                                 $blobs[$name] = $this->recacheMessageBlob( $key, $module, $lang );
 120                         } else {
 121                                 // Use unexpired cache
 122                                 $blobs[$name] = $result[$key];
 123                         }
 124                 }
 125                 return $blobs;
 126         }
 127
 128         /**
 129          * @since 1.27
 130          * @param ResourceLoaderModule $module
 131          * @param string $lang
 132          * @return string Cache key
 133          */
 134         private function makeCacheKey( ResourceLoaderModule $module, $lang ) {
 135                 $messages = array_values( array_unique( $module->getMessages() ) );
 136                 sort( $messages );
 137                 return $this->wanCache->makeKey( __CLASS__, $module->getName(), $lang,
 138                         md5( json_encode( $messages ) )
 139                 );
 140         }
 141
 142         /**
 143          * @since 1.27
 144          * @param string $cacheKey
 145          * @param ResourceLoaderModule $module
 146          * @param string $lang
 147          * @return string JSON blob
 148          */
 149         protected function recacheMessageBlob( $cacheKey, ResourceLoaderModule $module, $lang ) {
 150                 $blob = $this->generateMessageBlob( $module, $lang );
 151                 $cache = $this->wanCache;
 152                 $cache->set( $cacheKey, $blob,
 153                         // Add part of a day to TTL to avoid all modules expiring at once
 154                         $cache::TTL_WEEK + mt_rand( 0, $cache::TTL_DAY ),
 155                         Database::getCacheSetOptions( wfGetDB( DB_REPLICA ) )
 156                 );
 157                 return $blob;
 158         }
 159
 160         /**
 161          * Invalidate cache keys for modules using this message key.
 162          * Called by MessageCache when a message has changed.
 163          *
 164          * @param string $key Message key
 165          */
 166         public function updateMessage( $key ) {
 167                 $moduleNames = $this->getResourceLoader()->getModulesByMessage( $key );
 168                 foreach ( $moduleNames as $moduleName ) {
 169                         // Uses a holdoff to account for database replica DB lag (for MessageCache)
 170                         $this->wanCache->touchCheckKey( $this->wanCache->makeKey( __CLASS__, $moduleName ) );
 171                 }
 172         }
 173
 174         /**
 175          * Invalidate cache keys for all known modules.
 176          */
 177         public function clear() {
 178                 self::clearGlobalCacheEntry( $this->wanCache );
 179         }
 180
 181         /**
 182          * Invalidate cache keys for all known modules.
 183          *
 184          * Called by LocalisationCache after cache is regenerated.
 185          *
 186          * @param WANObjectCache $cache
 187          */
 188         public static function clearGlobalCacheEntry( WANObjectCache $cache ) {
 189                 // Disable hold-off because:
 190                 // - LocalisationCache is populated by messages on-disk and don't have DB lag,
 191                 //   thus there is no need for hold off. We only clear it after new localisation
 192                 //   updates are known to be deployed to all servers.
 193                 // - This global check key invalidates message blobs for all modules for all wikis
 194                 //   in cache contexts (e.g. languages, skins). Setting a hold-off on this key could
 195                 //   cause a cache stampede since no values would be stored for several seconds.
 196                 $cache->touchCheckKey( $cache->makeGlobalKey( __CLASS__ ), $cache::HOLDOFF_TTL_NONE );
 197         }
 198
 199         /**
 200          * @since 1.27
 201          * @return ResourceLoader
 202          */
 203         protected function getResourceLoader() {
 204                 return $this->resourceloader;
 205         }
 206
 207         /**
 208          * @since 1.27
 209          * @param string $key Message key
 210          * @param string $lang Language code
 211          * @return string|null
 212          */
 213         protected function fetchMessage( $key, $lang ) {
 214                 $message = wfMessage( $key )->inLanguage( $lang );
 215                 if ( !$message->exists() ) {
 216                         $this->logger->warning( 'Failed to find {messageKey} ({lang})', [
 217                                 'messageKey' => $key,
 218                                 'lang' => $lang,
 219                         ] );
 220                         $value = null;
 221                 } else {
 222                         $value = $message->plain();
 223                 }
 224                 return $value;
 225         }
 226
 227         /**
 228          * Generate the message blob for a given module in a given language.
 229          *
 230          * @param ResourceLoaderModule $module
 231          * @param string $lang Language code
 232          * @return string JSON blob
 233          */
 234         private function generateMessageBlob( ResourceLoaderModule $module, $lang ) {
 235                 $messages = [];
 236                 foreach ( $module->getMessages() as $key ) {
 237                         $value = $this->fetchMessage( $key, $lang );
 238                         if ( $value !== null ) {
 239                                 $messages[$key] = $value;
 240                         }
 241                 }
 242
 243                 $json = FormatJson::encode( (object)$messages, false, FormatJson::UTF8_OK );
 244                 // @codeCoverageIgnoreStart
 245                 if ( $json === false ) {
 246                         $this->logger->warning( 'Failed to encode message blob for {module} ({lang})', [
 247                                 'module' => $module->getName(),
 248                                 'lang' => $lang,
 249                         ] );
 250                         $json = '{}';
 251                 }
 252                 // codeCoverageIgnoreEnd
 253                 return $json;
 254         }
 255 }