use BagOStuff;
/**
- * Class for ensuring a consistent ordering of events as seen by the user, despite replication.
+ * Helper class for mitigating DB replication lag in order to provide "session consistency"
+ *
+ * This helps to ensure a consistent ordering of events as seen by an client
+ *
* Kind of like Hawking's [[Chronology Protection Agency]].
*/
class ChronologyProtector implements LoggerAwareInterface {
if ( isset( $client['clientId'] ) ) {
$this->clientId = $client['clientId'];
} else {
- $this->clientId = strlen( $secret )
+ $this->clientId = ( $secret != '' )
? hash_hmac( 'md5', $client['ip'] . "\n" . $client['agent'], $secret )
: md5( $client['ip'] . "\n" . $client['agent'] );
}
}
/**
- * Initialise a ILoadBalancer to give it appropriate chronology protection.
+ * Apply the "session consistency" DB replication position to a new ILoadBalancer
*
- * If the stash has a previous master position recorded, this will try to
- * make sure that the next query to a replica DB of that master will see changes up
+ * If the stash has a previous master position recorded, this will try to make
+ * sure that the next query to a replica DB of that master will see changes up
* to that position by delaying execution. The delay may timeout and allow stale
* data if no non-lagged replica DBs are available.
*
+ * This method should only be called from LBFactory.
+ *
* @param ILoadBalancer $lb
* @return void
*/
- public function initLB( ILoadBalancer $lb ) {
- if ( !$this->enabled || $lb->getServerCount() <= 1 ) {
- return; // non-replicated setup or disabled
+ public function applySessionReplicationPosition( ILoadBalancer $lb ) {
+ if ( !$this->enabled ) {
+ return; // disabled
}
- $this->initPositions();
-
$masterName = $lb->getServerName( $lb->getWriterIndex() );
- if (
- isset( $this->startupPositions[$masterName] ) &&
- $this->startupPositions[$masterName] instanceof DBMasterPos
- ) {
- $pos = $this->startupPositions[$masterName];
- $this->logger->debug( __METHOD__ . ": LB for '$masterName' set to pos $pos\n" );
+ $startupPositions = $this->getStartupMasterPositions();
+
+ $pos = $startupPositions[$masterName] ?? null;
+ if ( $pos instanceof DBMasterPos ) {
+ $this->logger->debug( __METHOD__ . ": pos for DB '$masterName' set to '$pos'\n" );
$lb->waitFor( $pos );
}
}
/**
- * Notify the ChronologyProtector that the ILoadBalancer is about to shut
- * down. Saves replication positions.
+ * Save the "session consistency" DB replication position for an end-of-life ILoadBalancer
+ *
+ * This saves the replication position of the master DB if this request made writes to it.
+ *
+ * This method should only be called from LBFactory.
*
* @param ILoadBalancer $lb
* @return void
*/
- public function shutdownLB( ILoadBalancer $lb ) {
+ public function storeSessionReplicationPosition( ILoadBalancer $lb ) {
if ( !$this->enabled ) {
- return; // not enabled
+ return; // disabled
} elseif ( !$lb->hasOrMadeRecentMasterChanges( INF ) ) {
// Only save the position if writes have been done on the connection
return;
}
if ( $this->shutdownPositions === [] ) {
+ $this->logger->debug( __METHOD__ . ": no master positions to save\n" );
+
return []; // nothing to save
}
- $this->logger->debug( __METHOD__ . ": saving master pos for " .
+ $this->logger->debug(
+ __METHOD__ . ": saving master pos for " .
implode( ', ', array_keys( $this->shutdownPositions ) ) . "\n"
);
/**
* Load in previous master positions for the client
*/
- protected function initPositions() {
+ protected function getStartupMasterPositions() {
if ( $this->initialized ) {
- return;
+ return $this->startupPositions;
}
$this->initialized = true;
+ $this->logger->debug( __METHOD__ . ": client ID is {$this->clientId} (read)\n" );
+
if ( $this->wait ) {
// If there is an expectation to see master positions from a certain write
// index or higher, then block until it appears, or until a timeout is reached.
$this->startupPositions = [];
$this->logger->debug( __METHOD__ . ": key is {$this->key} (unread)\n" );
}
+
+ return $this->startupPositions;
}
/**
[
'ip' => $this->requestInfo['IPAddress'],
'agent' => $this->requestInfo['UserAgent'],
- 'clientId' => $this->requestInfo['ChronologyClientId']
+ 'clientId' => $this->requestInfo['ChronologyClientId'] ?: null
],
$this->requestInfo['ChronologyPositionIndex'],
$this->secret
) {
// Record all the master positions needed
$this->forEachLB( function ( ILoadBalancer $lb ) use ( $cp ) {
- $cp->shutdownLB( $lb );
+ $cp->storeSessionReplicationPosition( $lb );
} );
// Write them to the persistent stash. Try to do something useful by running $work
// while ChronologyProtector waits for the stash write to replicate to all DCs.
'chronologyCallback' => function ( ILoadBalancer $lb ) {
// Defer ChronologyProtector construction in case setRequestInfo() ends up
// being called later (but before the first connection attempt) (T192611)
- $this->getChronologyProtector()->initLB( $lb );
+ $this->getChronologyProtector()->applySessionReplicationPosition( $lb );
},
'roundStage' => $initStage
];
$mockDB2->expects( $this->exactly( 1 ) )->method( 'lastDoneWrites' );
// Nothing to wait for on first HTTP request start
- $cp->initLB( $lb1 );
- $cp->initLB( $lb2 );
+ $cp->applySessionReplicationPosition( $lb1 );
+ $cp->applySessionReplicationPosition( $lb2 );
// Record positions in stash on first HTTP request end
- $cp->shutdownLB( $lb1 );
- $cp->shutdownLB( $lb2 );
+ $cp->storeSessionReplicationPosition( $lb1 );
+ $cp->storeSessionReplicationPosition( $lb2 );
$cpIndex = null;
$cp->shutdown( null, 'sync', $cpIndex );
);
// Wait for last positions to be reached on second HTTP request start
- $cp->initLB( $lb1 );
- $cp->initLB( $lb2 );
+ $cp->applySessionReplicationPosition( $lb1 );
+ $cp->applySessionReplicationPosition( $lb2 );
// Shutdown (nothing to record)
- $cp->shutdownLB( $lb1 );
- $cp->shutdownLB( $lb2 );
+ $cp->storeSessionReplicationPosition( $lb1 );
+ $cp->storeSessionReplicationPosition( $lb2 );
$cpIndex = null;
$cp->shutdown( null, 'sync', $cpIndex );
--- /dev/null
+<?php
+
+/**
+ * Holds tests for ChronologyProtector abstract MediaWiki class.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ */
+
+use Wikimedia\Rdbms\ChronologyProtector;
+
+/**
+ * @group Database
+ * @covers \Wikimedia\Rdbms\ChronologyProtector::__construct
+ * @covers \Wikimedia\Rdbms\ChronologyProtector::getClientId
+ */
+class ChronologyProtectorTest extends PHPUnit\Framework\TestCase {
+ /**
+ * @dataProvider clientIdProvider
+ * @param array $client
+ * @param string $secret
+ * @param string $expectedId
+ */
+ public function testClientId( array $client, $secret, $expectedId ) {
+ $bag = new HashBagOStuff();
+ $cp = new ChronologyProtector( $bag, $client, null, $secret );
+
+ $this->assertEquals( $expectedId, $cp->getClientId() );
+ }
+
+ public function clientIdProvider() {
+ return [
+ [
+ [
+ 'ip' => '127.0.0.1',
+ 'agent' => "Totally-Not-FireFox"
+ ],
+ '',
+ '45e93a9c215c031d38b7c42d8e4700ca',
+ ],
+ [
+ [
+ 'ip' => '127.0.0.7',
+ 'agent' => "Totally-Not-FireFox"
+ ],
+ '',
+ 'b1d604117b51746c35c3df9f293c84dc'
+ ],
+ [
+ [
+ 'ip' => '127.0.0.1',
+ 'agent' => "Totally-FireFox"
+ ],
+ '',
+ '731b4e06a65e2346b497fc811571c4d7'
+ ],
+ [
+ [
+ 'ip' => '127.0.0.1',
+ 'agent' => "Totally-Not-FireFox"
+ ],
+ 'secret',
+ 'defff51ded73cd901253d874c9b2077d'
+ ]
+ ];
+ }
+}