includes/libs/rdbms/lbfactory/LBFactory.php

   1 <?php
   2 /**
   3  * Generator and manager of database load balancing objects
   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  * @ingroup Database
  22  */
  23
  24 use Psr\Log\LoggerInterface;
  25
  26 /**
  27  * An interface for generating database load balancers
  28  * @ingroup Database
  29  */
  30 abstract class LBFactory {
  31         /** @var ChronologyProtector */
  32         protected $chronProt;
  33         /** @var object|string Class name or object With profileIn/profileOut methods */
  34         protected $profiler;
  35         /** @var TransactionProfiler */
  36         protected $trxProfiler;
  37         /** @var LoggerInterface */
  38         protected $replLogger;
  39         /** @var LoggerInterface */
  40         protected $connLogger;
  41         /** @var LoggerInterface */
  42         protected $queryLogger;
  43         /** @var LoggerInterface */
  44         protected $perfLogger;
  45         /** @var callable Error logger */
  46         protected $errorLogger;
  47         /** @var BagOStuff */
  48         protected $srvCache;
  49         /** @var BagOStuff */
  50         protected $memCache;
  51         /** @var WANObjectCache */
  52         protected $wanCache;
  53
  54         /** @var DatabaseDomain Local domain */
  55         protected $localDomain;
  56         /** @var string Local hostname of the app server */
  57         protected $hostname;
  58         /** @var array Web request information about the client */
  59         protected $requestInfo;
  60
  61         /** @var mixed */
  62         protected $ticket;
  63         /** @var string|bool String if a requested DBO_TRX transaction round is active */
  64         protected $trxRoundId = false;
  65         /** @var string|bool Reason all LBs are read-only or false if not */
  66         protected $readOnlyReason = false;
  67         /** @var callable[] */
  68         protected $replicationWaitCallbacks = [];
  69
  70         /** @var bool Whether this PHP instance is for a CLI script */
  71         protected $cliMode;
  72         /** @var string Agent name for query profiling */
  73         protected $agent;
  74
  75         const SHUTDOWN_NO_CHRONPROT = 0; // don't save DB positions at all
  76         const SHUTDOWN_CHRONPROT_ASYNC = 1; // save DB positions, but don't wait on remote DCs
  77         const SHUTDOWN_CHRONPROT_SYNC = 2; // save DB positions, waiting on all DCs
  78
  79         private static $loggerFields =
  80                 [ 'replLogger', 'connLogger', 'queryLogger', 'perfLogger' ];
  81
  82         /**
  83          * Construct a manager of ILoadBalancer objects
  84          *
  85          * Sub-classes will extend the required keys in $conf with additional parameters
  86          *
  87          * @param $conf $params Array with keys:
  88          *  - localDomain: A DatabaseDomain or domain ID string.
  89          *  - readOnlyReason : Reason the master DB is read-only if so [optional]
  90          *  - srvCache : BagOStuff object for server cache [optional]
  91          *  - memCache : BagOStuff object for cluster memory cache [optional]
  92          *  - wanCache : WANObjectCache object [optional]
  93          *  - hostname : The name of the current server [optional]
  94          *  - cliMode: Whether the execution context is a CLI script. [optional]
  95          *  - profiler : Class name or instance with profileIn()/profileOut() methods. [optional]
  96          *  - trxProfiler: TransactionProfiler instance. [optional]
  97          *  - replLogger: PSR-3 logger instance. [optional]
  98          *  - connLogger: PSR-3 logger instance. [optional]
  99          *  - queryLogger: PSR-3 logger instance. [optional]
 100          *  - perfLogger: PSR-3 logger instance. [optional]
 101          *  - errorLogger : Callback that takes an Exception and logs it. [optional]
 102          * @throws InvalidArgumentException
 103          */
 104         public function __construct( array $conf ) {
 105                 $this->localDomain = isset( $conf['localDomain'] )
 106                         ? DatabaseDomain::newFromId( $conf['localDomain'] )
 107                         : DatabaseDomain::newUnspecified();
 108
 109                 if ( isset( $conf['readOnlyReason'] ) && is_string( $conf['readOnlyReason'] ) ) {
 110                         $this->readOnlyReason = $conf['readOnlyReason'];
 111                 }
 112
 113                 $this->srvCache = isset( $conf['srvCache'] ) ? $conf['srvCache'] : new EmptyBagOStuff();
 114                 $this->memCache = isset( $conf['memCache'] ) ? $conf['memCache'] : new EmptyBagOStuff();
 115                 $this->wanCache = isset( $conf['wanCache'] )
 116                         ? $conf['wanCache']
 117                         : WANObjectCache::newEmpty();
 118
 119                 foreach ( self::$loggerFields as $key ) {
 120                         $this->$key = isset( $conf[$key] ) ? $conf[$key] : new \Psr\Log\NullLogger();
 121                 }
 122                 $this->errorLogger = isset( $conf['errorLogger'] )
 123                         ? $conf['errorLogger']
 124                         : function ( Exception $e ) {
 125                                 trigger_error( E_WARNING, get_class( $e ) . ': ' . $e->getMessage() );
 126                         };
 127
 128                 $this->profiler = isset( $params['profiler'] ) ? $params['profiler'] : null;
 129                 $this->trxProfiler = isset( $conf['trxProfiler'] )
 130                         ? $conf['trxProfiler']
 131                         : new TransactionProfiler();
 132
 133                 $this->requestInfo = [
 134                         'IPAddress' => isset( $_SERVER[ 'REMOTE_ADDR' ] ) ? $_SERVER[ 'REMOTE_ADDR' ] : '',
 135                         'UserAgent' => isset( $_SERVER['HTTP_USER_AGENT'] ) ? $_SERVER['HTTP_USER_AGENT'] : '',
 136                         'ChronologyProtection' => 'true'
 137                 ];
 138
 139                 $this->cliMode = isset( $params['cliMode'] ) ? $params['cliMode'] : PHP_SAPI === 'cli';
 140                 $this->hostname = isset( $conf['hostname'] ) ? $conf['hostname'] : gethostname();
 141                 $this->agent = isset( $params['agent'] ) ? $params['agent'] : '';
 142
 143                 $this->ticket = mt_rand();
 144         }
 145
 146         /**
 147          * Disables all load balancers. All connections are closed, and any attempt to
 148          * open a new connection will result in a DBAccessError.
 149          * @see ILoadBalancer::disable()
 150          */
 151         public function destroy() {
 152                 $this->shutdown( self::SHUTDOWN_NO_CHRONPROT );
 153                 $this->forEachLBCallMethod( 'disable' );
 154         }
 155
 156         /**
 157          * Create a new load balancer object. The resulting object will be untracked,
 158          * not chronology-protected, and the caller is responsible for cleaning it up.
 159          *
 160          * This method is for only advanced usage and callers should almost always use
 161          * getMainLB() instead. This method can be useful when a table is used as a key/value
 162          * store. In that cases, one might want to query it in autocommit mode (DBO_TRX off)
 163          * but still use DBO_TRX transaction rounds on other tables.
 164          *
 165          * @param bool|string $domain Domain ID, or false for the current domain
 166          * @return ILoadBalancer
 167          */
 168         abstract public function newMainLB( $domain = false );
 169
 170         /**
 171          * Get a cached (tracked) load balancer object.
 172          *
 173          * @param bool|string $domain Domain ID, or false for the current domain
 174          * @return ILoadBalancer
 175          */
 176         abstract public function getMainLB( $domain = false );
 177
 178         /**
 179          * Create a new load balancer for external storage. The resulting object will be
 180          * untracked, not chronology-protected, and the caller is responsible for
 181          * cleaning it up.
 182          *
 183          * This method is for only advanced usage and callers should almost always use
 184          * getExternalLB() instead. This method can be useful when a table is used as a
 185          * key/value store. In that cases, one might want to query it in autocommit mode
 186          * (DBO_TRX off) but still use DBO_TRX transaction rounds on other tables.
 187          *
 188          * @param string $cluster External storage cluster, or false for core
 189          * @param bool|string $domain Domain ID, or false for the current domain
 190          * @return ILoadBalancer
 191          */
 192         abstract public function newExternalLB( $cluster, $domain = false );
 193
 194         /**
 195          * Get a cached (tracked) load balancer for external storage
 196          *
 197          * @param string $cluster External storage cluster, or false for core
 198          * @param bool|string $domain Domain ID, or false for the current domain
 199          * @return ILoadBalancer
 200          */
 201         abstract public function getExternalLB( $cluster, $domain = false );
 202
 203         /**
 204          * Execute a function for each tracked load balancer
 205          * The callback is called with the load balancer as the first parameter,
 206          * and $params passed as the subsequent parameters.
 207          *
 208          * @param callable $callback
 209          * @param array $params
 210          */
 211         abstract public function forEachLB( $callback, array $params = [] );
 212
 213         /**
 214          * Prepare all tracked load balancers for shutdown
 215          * @param integer $mode One of the class SHUTDOWN_* constants
 216          * @param callable|null $workCallback Work to mask ChronologyProtector writes
 217          */
 218         public function shutdown(
 219                 $mode = self::SHUTDOWN_CHRONPROT_SYNC, callable $workCallback = null
 220         ) {
 221                 $chronProt = $this->getChronologyProtector();
 222                 if ( $mode === self::SHUTDOWN_CHRONPROT_SYNC ) {
 223                         $this->shutdownChronologyProtector( $chronProt, $workCallback, 'sync' );
 224                 } elseif ( $mode === self::SHUTDOWN_CHRONPROT_ASYNC ) {
 225                         $this->shutdownChronologyProtector( $chronProt, null, 'async' );
 226                 }
 227
 228                 $this->commitMasterChanges( __METHOD__ ); // sanity
 229         }
 230
 231         /**
 232          * Call a method of each tracked load balancer
 233          *
 234          * @param string $methodName
 235          * @param array $args
 236          */
 237         protected function forEachLBCallMethod( $methodName, array $args = [] ) {
 238                 $this->forEachLB(
 239                         function ( ILoadBalancer $loadBalancer, $methodName, array $args ) {
 240                                 call_user_func_array( [ $loadBalancer, $methodName ], $args );
 241                         },
 242                         [ $methodName, $args ]
 243                 );
 244         }
 245
 246         /**
 247          * Commit all replica DB transactions so as to flush any REPEATABLE-READ or SSI snapshot
 248          *
 249          * @param string $fname Caller name
 250          * @since 1.28
 251          */
 252         public function flushReplicaSnapshots( $fname = __METHOD__ ) {
 253                 $this->forEachLBCallMethod( 'flushReplicaSnapshots', [ $fname ] );
 254         }
 255
 256         /**
 257          * Commit on all connections. Done for two reasons:
 258          * 1. To commit changes to the masters.
 259          * 2. To release the snapshot on all connections, master and replica DB.
 260          * @param string $fname Caller name
 261          * @param array $options Options map:
 262          *   - maxWriteDuration: abort if more than this much time was spent in write queries
 263          */
 264         public function commitAll( $fname = __METHOD__, array $options = [] ) {
 265                 $this->commitMasterChanges( $fname, $options );
 266                 $this->forEachLBCallMethod( 'commitAll', [ $fname ] );
 267         }
 268
 269         /**
 270          * Flush any master transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set)
 271          *
 272          * The DBO_TRX setting will be reverted to the default in each of these methods:
 273          *   - commitMasterChanges()
 274          *   - rollbackMasterChanges()
 275          *   - commitAll()
 276          *
 277          * This allows for custom transaction rounds from any outer transaction scope.
 278          *
 279          * @param string $fname
 280          * @throws DBTransactionError
 281          * @since 1.28
 282          */
 283         public function beginMasterChanges( $fname = __METHOD__ ) {
 284                 if ( $this->trxRoundId !== false ) {
 285                         throw new DBTransactionError(
 286                                 null,
 287                                 "$fname: transaction round '{$this->trxRoundId}' already started."
 288                         );
 289                 }
 290                 $this->trxRoundId = $fname;
 291                 // Set DBO_TRX flags on all appropriate DBs
 292                 $this->forEachLBCallMethod( 'beginMasterChanges', [ $fname ] );
 293         }
 294
 295         /**
 296          * Commit changes on all master connections
 297          * @param string $fname Caller name
 298          * @param array $options Options map:
 299          *   - maxWriteDuration: abort if more than this much time was spent in write queries
 300          * @throws Exception
 301          */
 302         public function commitMasterChanges( $fname = __METHOD__, array $options = [] ) {
 303                 if ( $this->trxRoundId !== false && $this->trxRoundId !== $fname ) {
 304                         throw new DBTransactionError(
 305                                 null,
 306                                 "$fname: transaction round '{$this->trxRoundId}' still running."
 307                         );
 308                 }
 309                 // Run pre-commit callbacks and suppress post-commit callbacks, aborting on failure
 310                 $this->forEachLBCallMethod( 'finalizeMasterChanges' );
 311                 $this->trxRoundId = false;
 312                 // Perform pre-commit checks, aborting on failure
 313                 $this->forEachLBCallMethod( 'approveMasterChanges', [ $options ] );
 314                 // Log the DBs and methods involved in multi-DB transactions
 315                 $this->logIfMultiDbTransaction();
 316                 // Actually perform the commit on all master DB connections and revert DBO_TRX
 317                 $this->forEachLBCallMethod( 'commitMasterChanges', [ $fname ] );
 318                 // Run all post-commit callbacks
 319                 /** @var Exception $e */
 320                 $e = null; // first callback exception
 321                 $this->forEachLB( function ( ILoadBalancer $lb ) use ( &$e ) {
 322                         $ex = $lb->runMasterPostTrxCallbacks( IDatabase::TRIGGER_COMMIT );
 323                         $e = $e ?: $ex;
 324                 } );
 325                 // Commit any dangling DBO_TRX transactions from callbacks on one DB to another DB
 326                 $this->forEachLBCallMethod( 'commitMasterChanges', [ $fname ] );
 327                 // Throw any last post-commit callback error
 328                 if ( $e instanceof Exception ) {
 329                         throw $e;
 330                 }
 331         }
 332
 333         /**
 334          * Rollback changes on all master connections
 335          * @param string $fname Caller name
 336          * @since 1.23
 337          */
 338         public function rollbackMasterChanges( $fname = __METHOD__ ) {
 339                 $this->trxRoundId = false;
 340                 $this->forEachLBCallMethod( 'suppressTransactionEndCallbacks' );
 341                 $this->forEachLBCallMethod( 'rollbackMasterChanges', [ $fname ] );
 342                 // Run all post-rollback callbacks
 343                 $this->forEachLB( function ( ILoadBalancer $lb ) {
 344                         $lb->runMasterPostTrxCallbacks( IDatabase::TRIGGER_ROLLBACK );
 345                 } );
 346         }
 347
 348         /**
 349          * Log query info if multi DB transactions are going to be committed now
 350          */
 351         private function logIfMultiDbTransaction() {
 352                 $callersByDB = [];
 353                 $this->forEachLB( function ( ILoadBalancer $lb ) use ( &$callersByDB ) {
 354                         $masterName = $lb->getServerName( $lb->getWriterIndex() );
 355                         $callers = $lb->pendingMasterChangeCallers();
 356                         if ( $callers ) {
 357                                 $callersByDB[$masterName] = $callers;
 358                         }
 359                 } );
 360
 361                 if ( count( $callersByDB ) >= 2 ) {
 362                         $dbs = implode( ', ', array_keys( $callersByDB ) );
 363                         $msg = "Multi-DB transaction [{$dbs}]:\n";
 364                         foreach ( $callersByDB as $db => $callers ) {
 365                                 $msg .= "$db: " . implode( '; ', $callers ) . "\n";
 366                         }
 367                         $this->queryLogger->info( $msg );
 368                 }
 369         }
 370
 371         /**
 372          * Determine if any master connection has pending changes
 373          * @return bool
 374          * @since 1.23
 375          */
 376         public function hasMasterChanges() {
 377                 $ret = false;
 378                 $this->forEachLB( function ( ILoadBalancer $lb ) use ( &$ret ) {
 379                         $ret = $ret || $lb->hasMasterChanges();
 380                 } );
 381
 382                 return $ret;
 383         }
 384
 385         /**
 386          * Detemine if any lagged replica DB connection was used
 387          * @return bool
 388          * @since 1.28
 389          */
 390         public function laggedReplicaUsed() {
 391                 $ret = false;
 392                 $this->forEachLB( function ( ILoadBalancer $lb ) use ( &$ret ) {
 393                         $ret = $ret || $lb->laggedReplicaUsed();
 394                 } );
 395
 396                 return $ret;
 397         }
 398
 399         /**
 400          * Determine if any master connection has pending/written changes from this request
 401          * @param float $age How many seconds ago is "recent" [defaults to LB lag wait timeout]
 402          * @return bool
 403          * @since 1.27
 404          */
 405         public function hasOrMadeRecentMasterChanges( $age = null ) {
 406                 $ret = false;
 407                 $this->forEachLB( function ( ILoadBalancer $lb ) use ( $age, &$ret ) {
 408                         $ret = $ret || $lb->hasOrMadeRecentMasterChanges( $age );
 409                 } );
 410                 return $ret;
 411         }
 412
 413         /**
 414          * Waits for the replica DBs to catch up to the current master position
 415          *
 416          * Use this when updating very large numbers of rows, as in maintenance scripts,
 417          * to avoid causing too much lag. Of course, this is a no-op if there are no replica DBs.
 418          *
 419          * By default this waits on all DB clusters actually used in this request.
 420          * This makes sense when lag being waiting on is caused by the code that does this check.
 421          * In that case, setting "ifWritesSince" can avoid the overhead of waiting for clusters
 422          * that were not changed since the last wait check. To forcefully wait on a specific cluster
 423          * for a given domain, use the 'domain' parameter. To forcefully wait on an "external" cluster,
 424          * use the "cluster" parameter.
 425          *
 426          * Never call this function after a large DB write that is *still* in a transaction.
 427          * It only makes sense to call this after the possible lag inducing changes were committed.
 428          *
 429          * @param array $opts Optional fields that include:
 430          *   - domain : wait on the load balancer DBs that handles the given domain ID
 431          *   - cluster : wait on the given external load balancer DBs
 432          *   - timeout : Max wait time. Default: ~60 seconds
 433          *   - ifWritesSince: Only wait if writes were done since this UNIX timestamp
 434          * @throws DBReplicationWaitError If a timeout or error occured waiting on a DB cluster
 435          * @since 1.27
 436          */
 437         public function waitForReplication( array $opts = [] ) {
 438                 $opts += [
 439                         'domain' => false,
 440                         'cluster' => false,
 441                         'timeout' => 60,
 442                         'ifWritesSince' => null
 443                 ];
 444
 445                 if ( $opts['domain'] === false && isset( $opts['wiki'] ) ) {
 446                         $opts['domain'] = $opts['wiki']; // b/c
 447                 }
 448
 449                 // Figure out which clusters need to be checked
 450                 /** @var ILoadBalancer[] $lbs */
 451                 $lbs = [];
 452                 if ( $opts['cluster'] !== false ) {
 453                         $lbs[] = $this->getExternalLB( $opts['cluster'] );
 454                 } elseif ( $opts['domain'] !== false ) {
 455                         $lbs[] = $this->getMainLB( $opts['domain'] );
 456                 } else {
 457                         $this->forEachLB( function ( ILoadBalancer $lb ) use ( &$lbs ) {
 458                                 $lbs[] = $lb;
 459                         } );
 460                         if ( !$lbs ) {
 461                                 return; // nothing actually used
 462                         }
 463                 }
 464
 465                 // Get all the master positions of applicable DBs right now.
 466                 // This can be faster since waiting on one cluster reduces the
 467                 // time needed to wait on the next clusters.
 468                 $masterPositions = array_fill( 0, count( $lbs ), false );
 469                 foreach ( $lbs as $i => $lb ) {
 470                         if ( $lb->getServerCount() <= 1 ) {
 471                                 // Bug 27975 - Don't try to wait for replica DBs if there are none
 472                                 // Prevents permission error when getting master position
 473                                 continue;
 474                         } elseif ( $opts['ifWritesSince']
 475                                 && $lb->lastMasterChangeTimestamp() < $opts['ifWritesSince']
 476                         ) {
 477                                 continue; // no writes since the last wait
 478                         }
 479                         $masterPositions[$i] = $lb->getMasterPos();
 480                 }
 481
 482                 // Run any listener callbacks *after* getting the DB positions. The more
 483                 // time spent in the callbacks, the less time is spent in waitForAll().
 484                 foreach ( $this->replicationWaitCallbacks as $callback ) {
 485                         $callback();
 486                 }
 487
 488                 $failed = [];
 489                 foreach ( $lbs as $i => $lb ) {
 490                         if ( $masterPositions[$i] ) {
 491                                 // The DBMS may not support getMasterPos()
 492                                 if ( !$lb->waitForAll( $masterPositions[$i], $opts['timeout'] ) ) {
 493                                         $failed[] = $lb->getServerName( $lb->getWriterIndex() );
 494                                 }
 495                         }
 496                 }
 497
 498                 if ( $failed ) {
 499                         throw new DBReplicationWaitError(
 500                                 "Could not wait for replica DBs to catch up to " .
 501                                 implode( ', ', $failed )
 502                         );
 503                 }
 504         }
 505
 506         /**
 507          * Add a callback to be run in every call to waitForReplication() before waiting
 508          *
 509          * Callbacks must clear any transactions that they start
 510          *
 511          * @param string $name Callback name
 512          * @param callable|null $callback Use null to unset a callback
 513          * @since 1.28
 514          */
 515         public function setWaitForReplicationListener( $name, callable $callback = null ) {
 516                 if ( $callback ) {
 517                         $this->replicationWaitCallbacks[$name] = $callback;
 518                 } else {
 519                         unset( $this->replicationWaitCallbacks[$name] );
 520                 }
 521         }
 522
 523         /**
 524          * Get a token asserting that no transaction writes are active
 525          *
 526          * @param string $fname Caller name (e.g. __METHOD__)
 527          * @return mixed A value to pass to commitAndWaitForReplication()
 528          * @since 1.28
 529          */
 530         public function getEmptyTransactionTicket( $fname ) {
 531                 if ( $this->hasMasterChanges() ) {
 532                         $this->queryLogger->error( __METHOD__ . ": $fname does not have outer scope.\n" .
 533                                 ( new RuntimeException() )->getTraceAsString() );
 534
 535                         return null;
 536                 }
 537
 538                 return $this->ticket;
 539         }
 540
 541         /**
 542          * Convenience method for safely running commitMasterChanges()/waitForReplication()
 543          *
 544          * This will commit and wait unless $ticket indicates it is unsafe to do so
 545          *
 546          * @param string $fname Caller name (e.g. __METHOD__)
 547          * @param mixed $ticket Result of getEmptyTransactionTicket()
 548          * @param array $opts Options to waitForReplication()
 549          * @throws DBReplicationWaitError
 550          * @since 1.28
 551          */
 552         public function commitAndWaitForReplication( $fname, $ticket, array $opts = [] ) {
 553                 if ( $ticket !== $this->ticket ) {
 554                         $this->perfLogger->error( __METHOD__ . ": $fname does not have outer scope.\n" .
 555                                 ( new RuntimeException() )->getTraceAsString() );
 556
 557                         return;
 558                 }
 559
 560                 // The transaction owner and any caller with the empty transaction ticket can commit
 561                 // so that getEmptyTransactionTicket() callers don't risk seeing DBTransactionError.
 562                 if ( $this->trxRoundId !== false && $fname !== $this->trxRoundId ) {
 563                         $this->queryLogger->info( "$fname: committing on behalf of {$this->trxRoundId}." );
 564                         $fnameEffective = $this->trxRoundId;
 565                 } else {
 566                         $fnameEffective = $fname;
 567                 }
 568
 569                 $this->commitMasterChanges( $fnameEffective );
 570                 $this->waitForReplication( $opts );
 571                 // If a nested caller committed on behalf of $fname, start another empty $fname
 572                 // transaction, leaving the caller with the same empty transaction state as before.
 573                 if ( $fnameEffective !== $fname ) {
 574                         $this->beginMasterChanges( $fnameEffective );
 575                 }
 576         }
 577
 578         /**
 579          * @param string $dbName DB master name (e.g. "db1052")
 580          * @return float|bool UNIX timestamp when client last touched the DB or false if not recent
 581          * @since 1.28
 582          */
 583         public function getChronologyProtectorTouched( $dbName ) {
 584                 return $this->getChronologyProtector()->getTouched( $dbName );
 585         }
 586
 587         /**
 588          * Disable the ChronologyProtector for all load balancers
 589          *
 590          * This can be called at the start of special API entry points
 591          *
 592          * @since 1.27
 593          */
 594         public function disableChronologyProtection() {
 595                 $this->getChronologyProtector()->setEnabled( false );
 596         }
 597
 598         /**
 599          * @return ChronologyProtector
 600          */
 601         protected function getChronologyProtector() {
 602                 if ( $this->chronProt ) {
 603                         return $this->chronProt;
 604                 }
 605
 606                 $this->chronProt = new ChronologyProtector(
 607                         $this->memCache,
 608                         [
 609                                 'ip' => $this->requestInfo['IPAddress'],
 610                                 'agent' => $this->requestInfo['UserAgent'],
 611                         ],
 612                         isset( $_GET['cpPosTime'] ) ? $_GET['cpPosTime'] : null
 613                 );
 614                 $this->chronProt->setLogger( $this->replLogger );
 615
 616                 if ( $this->cliMode ) {
 617                         $this->chronProt->setEnabled( false );
 618                 } elseif ( $this->requestInfo['ChronologyProtection'] === 'false' ) {
 619                         // Request opted out of using position wait logic. This is useful for requests
 620                         // done by the job queue or background ETL that do not have a meaningful session.
 621                         $this->chronProt->setWaitEnabled( false );
 622                 }
 623
 624                 $this->replLogger->debug( __METHOD__ . ': using request info ' .
 625                         json_encode( $this->requestInfo, JSON_PRETTY_PRINT ) );
 626
 627                 return $this->chronProt;
 628         }
 629
 630         /**
 631          * Get and record all of the staged DB positions into persistent memory storage
 632          *
 633          * @param ChronologyProtector $cp
 634          * @param callable|null $workCallback Work to do instead of waiting on syncing positions
 635          * @param string $mode One of (sync, async); whether to wait on remote datacenters
 636          */
 637         protected function shutdownChronologyProtector(
 638                 ChronologyProtector $cp, $workCallback, $mode
 639         ) {
 640                 // Record all the master positions needed
 641                 $this->forEachLB( function ( ILoadBalancer $lb ) use ( $cp ) {
 642                         $cp->shutdownLB( $lb );
 643                 } );
 644                 // Write them to the persistent stash. Try to do something useful by running $work
 645                 // while ChronologyProtector waits for the stash write to replicate to all DCs.
 646                 $unsavedPositions = $cp->shutdown( $workCallback, $mode );
 647                 if ( $unsavedPositions && $workCallback ) {
 648                         // Invoke callback in case it did not cache the result yet
 649                         $workCallback(); // work now to block for less time in waitForAll()
 650                 }
 651                 // If the positions failed to write to the stash, at least wait on local datacenter
 652                 // replica DBs to catch up before responding. Even if there are several DCs, this increases
 653                 // the chance that the user will see their own changes immediately afterwards. As long
 654                 // as the sticky DC cookie applies (same domain), this is not even an issue.
 655                 $this->forEachLB( function ( ILoadBalancer $lb ) use ( $unsavedPositions ) {
 656                         $masterName = $lb->getServerName( $lb->getWriterIndex() );
 657                         if ( isset( $unsavedPositions[$masterName] ) ) {
 658                                 $lb->waitForAll( $unsavedPositions[$masterName] );
 659                         }
 660                 } );
 661         }
 662
 663         /**
 664          * Base parameters to LoadBalancer::__construct()
 665          * @return array
 666          */
 667         final protected function baseLoadBalancerParams() {
 668                 return [
 669                         'localDomain' => $this->localDomain,
 670                         'readOnlyReason' => $this->readOnlyReason,
 671                         'srvCache' => $this->srvCache,
 672                         'wanCache' => $this->wanCache,
 673                         'profiler' => $this->profiler,
 674                         'trxProfiler' => $this->trxProfiler,
 675                         'queryLogger' => $this->queryLogger,
 676                         'connLogger' => $this->connLogger,
 677                         'replLogger' => $this->replLogger,
 678                         'errorLogger' => $this->errorLogger,
 679                         'hostname' => $this->hostname,
 680                         'cliMode' => $this->cliMode,
 681                         'agent' => $this->agent
 682                 ];
 683         }
 684
 685         /**
 686          * @param ILoadBalancer $lb
 687          */
 688         protected function initLoadBalancer( ILoadBalancer $lb ) {
 689                 if ( $this->trxRoundId !== false ) {
 690                         $lb->beginMasterChanges( $this->trxRoundId ); // set DBO_TRX
 691                 }
 692         }
 693
 694         /**
 695          * Set a new table prefix for the existing local domain ID for testing
 696          *
 697          * @param string $prefix
 698          * @since 1.28
 699          */
 700         public function setDomainPrefix( $prefix ) {
 701                 $this->localDomain = new DatabaseDomain(
 702                         $this->localDomain->getDatabase(),
 703                         null,
 704                         $prefix
 705                 );
 706
 707                 $this->forEachLB( function( ILoadBalancer $lb ) use ( $prefix ) {
 708                         $lb->setDomainPrefix( $prefix );
 709                 } );
 710         }
 711
 712         /**
 713          * Close all open database connections on all open load balancers.
 714          * @since 1.28
 715          */
 716         public function closeAll() {
 717                 $this->forEachLBCallMethod( 'closeAll', [] );
 718         }
 719
 720         /**
 721          * @param string $agent Agent name for query profiling
 722          * @since 1.28
 723          */
 724         public function setAgentName( $agent ) {
 725                 $this->agent = $agent;
 726         }
 727
 728         /**
 729          * Append ?cpPosTime parameter to a URL for ChronologyProtector purposes if needed
 730          *
 731          * Note that unlike cookies, this works accross domains
 732          *
 733          * @param string $url
 734          * @param float $time UNIX timestamp just before shutdown() was called
 735          * @return string
 736          * @since 1.28
 737          */
 738         public function appendPreShutdownTimeAsQuery( $url, $time ) {
 739                 $usedCluster = 0;
 740                 $this->forEachLB( function ( ILoadBalancer $lb ) use ( &$usedCluster ) {
 741                         $usedCluster |= ( $lb->getServerCount() > 1 );
 742                 } );
 743
 744                 if ( !$usedCluster ) {
 745                         return $url; // no master/replica clusters touched
 746                 }
 747
 748                 return strpos( $url, '?' ) === false ? "$url?cpPosTime=$time" : "$url&cpPosTime=$time";
 749         }
 750
 751         /**
 752          * @param array $info Map of fields, including:
 753          *   - IPAddress : IP address
 754          *   - UserAgent : User-Agent HTTP header
 755          *   - ChronologyProtection : cookie/header value specifying ChronologyProtector usage
 756          * @since 1.28
 757          */
 758         public function setRequestInfo( array $info ) {
 759                 $this->requestInfo = $info + $this->requestInfo;
 760         }
 761
 762         function __destruct() {
 763                 $this->destroy();
 764         }
 765 }