Helper class for mitigating DB replication lag in order to provide "session consistency". More...

Inheritance diagram for Wikimedia\Rdbms\ChronologyProtector:

Collaboration diagram for Wikimedia\Rdbms\ChronologyProtector:

[legend]

Public Member Functions
	__construct (BagOStuff $store, array $client, $posIndex, $secret='')

	applySessionReplicationPosition (ILoadBalancer $lb)
	Apply the "session consistency" DB replication position to a new ILoadBalancer. More...

	getClientId ()

	getTouched (ILoadBalancer $lb)
	Get the UNIX timestamp when the client last touched the DB, if they did so recently. More...

	setEnabled ( $enabled)

	setLogger (LoggerInterface $logger)

	setMockTime (&$time)

	setWaitEnabled ( $enabled)

	shutdown (&$cpIndex=null)
	Save any remarked "session consistency" DB replication positions to persistent storage. More...

	stageSessionReplicationPosition (ILoadBalancer $lb)
	Update the "session consistency" DB replication position for an end-of-life ILoadBalancer. More...

Public Attributes
const	POSITION_COOKIE_TTL = 10
	Seconds to store position write index cookies (safely less than POSITION_STORE_TTL) More...

Protected Member Functions
	getCurrentTime ()

	getStartupSessionPositions ()

	getStartupSessionTimestamps ()

	lazyStartup ()
	Load the stored DB replication positions and touch timestamps for the client. More...

	mergePositions ( $storedValue, array $shutdownPositions, array $shutdownTimestamps, &$cpIndex=null)
	Merge the new DB replication positions with the currently stored ones (highest wins) More...

Protected Attributes
string	$clientId
	Hash of client parameters. More...

string[]	$clientLogInfo
	Map of client information fields for logging. More...

bool	$enabled = true
	Whether reading/writing session consistency replication positions is enabled. More...

string	$key
	Storage key name. More...

LoggerInterface	$logger

bool	$positionWaitsEnabled = true
	Whether waiting on DB servers to reach replication positions is enabled. More...

array< string, DBMasterPos >	$shutdownPositionsByMaster = []
	Map of (DB master name => position) More...

array< string, float >	$shutdownTimestampsByCluster = []
	Map of (DB cluster name => UNIX timestamp) More...

array< string, DBMasterPos >	$startupPositionsByMaster = []
	Map of (DB master name => position) More...

float null	$startupTimestamp
	UNIX timestamp when the client data was loaded. More...

array< string, float >	$startupTimestampsByCluster = []
	Map of (DB cluster name => UNIX timestamp) More...

BagOStuff	$store

int null	$waitForPosIndex
	Expected minimum index of the last write to the position store. More...

Private Attributes
float null	$wallClockOverride

const	FLD_POSITIONS = 'positions'

const	FLD_TIMESTAMPS = 'timestamps'

const	FLD_WRITE_INDEX = 'writeIndex'

const	LOCK_TIMEOUT = 3
	Lock timeout to use for key updates. More...

const	LOCK_TTL = 6
	Lock expiry to use for key updates. More...

const	POSITION_INDEX_WAIT_TIMEOUT = 5
	Max seconds to wait for positions write indexes to appear (e.g. More...

const	POSITION_STORE_TTL = 60
	Seconds to store replication positions. More...

Detailed Description

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]].

Definition at line 41 of file ChronologyProtector.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\Rdbms\ChronologyProtector::__construct	(	BagOStuff	$store,
		array	$client,
			$posIndex,
			$secret = `''`
	)

Parameters

BagOStuff	$store
array	$client	Map of (ip: <IP>, agent: <user-agent> [, clientId: <hash>] )
int \| null	$posIndex	Write counter index
string	$secret	Secret string for HMAC hashing [optional]

Since: 1.27

Definition at line 98 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$store, and BagOStuff\makeGlobalKey().

Member Function Documentation

◆ applySessionReplicationPosition()

Wikimedia\Rdbms\ChronologyProtector::applySessionReplicationPosition ( ILoadBalancer $lb )

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 to that position by delaying execution. The delay may timeout and allow stale data if no non-lagged replica DBs are available.

Definition at line 161 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ILoadBalancer\getClusterName(), Wikimedia\Rdbms\ILoadBalancer\getServerName(), Wikimedia\Rdbms\ChronologyProtector\getStartupSessionPositions(), Wikimedia\Rdbms\ILoadBalancer\getWriterIndex(), and Wikimedia\Rdbms\ILoadBalancer\waitFor().

◆ getClientId()

Wikimedia\Rdbms\ChronologyProtector::getClientId ( )

Returns: string Client ID hash

Since: 1.32

Definition at line 128 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$clientId.

Referenced by Wikimedia\Rdbms\LBFactory\shutdown().

◆ getCurrentTime()

Wikimedia\Rdbms\ChronologyProtector::getCurrentTime ( )

protected

Definition at line 452 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$wallClockOverride.

Referenced by Wikimedia\Rdbms\ChronologyProtector\lazyStartup(), and Wikimedia\Rdbms\ChronologyProtector\stageSessionReplicationPosition().

◆ getStartupSessionPositions()

Wikimedia\Rdbms\ChronologyProtector::getStartupSessionPositions ( )

protected

Returns: array<string,DBMasterPos>

Definition at line 307 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$startupPositionsByMaster, and Wikimedia\Rdbms\ChronologyProtector\lazyStartup().

Referenced by Wikimedia\Rdbms\ChronologyProtector\applySessionReplicationPosition().

◆ getStartupSessionTimestamps()

Wikimedia\Rdbms\ChronologyProtector::getStartupSessionTimestamps ( )

protected

Returns: array<string,float>

Definition at line 316 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$startupTimestampsByCluster, and Wikimedia\Rdbms\ChronologyProtector\lazyStartup().

Referenced by Wikimedia\Rdbms\ChronologyProtector\getTouched().

◆ getTouched()

Wikimedia\Rdbms\ChronologyProtector::getTouched ( ILoadBalancer $lb )

Get the UNIX timestamp when the client last touched the DB, if they did so recently.

Definition at line 278 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ILoadBalancer\getClusterName(), and Wikimedia\Rdbms\ChronologyProtector\getStartupSessionTimestamps().

◆ lazyStartup()

Wikimedia\Rdbms\ChronologyProtector::lazyStartup ( )

protected

Load the stored DB replication positions and touch timestamps for the client.

Returns: void

Definition at line 327 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\FLD_POSITIONS, Wikimedia\Rdbms\ChronologyProtector\FLD_TIMESTAMPS, Wikimedia\Rdbms\ChronologyProtector\FLD_WRITE_INDEX, Wikimedia\Rdbms\ChronologyProtector\getCurrentTime(), and Wikimedia\Rdbms\ChronologyProtector\POSITION_INDEX_WAIT_TIMEOUT.

Referenced by Wikimedia\Rdbms\ChronologyProtector\getStartupSessionPositions(), and Wikimedia\Rdbms\ChronologyProtector\getStartupSessionTimestamps().

◆ mergePositions()

Wikimedia\Rdbms\ChronologyProtector::mergePositions	(		$storedValue,
		array	$shutdownPositions,
		array	$shutdownTimestamps,
		&	$cpIndex = `null`
	)

protected

Merge the new DB replication positions with the currently stored ones (highest wins)

Parameters

	array<string,mixed>\|false	$storedValue Current DB replication position data
	array<string,DBMasterPos>	$shutdownPositions New DB replication positions
	array<string,float>	$shutdownTimestamps New DB post-commit shutdown timestamps
int \| null	&$cpIndex	New position write index

Returns: array<string,mixed> Combined DB replication position data

Definition at line 407 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\FLD_POSITIONS, Wikimedia\Rdbms\ChronologyProtector\FLD_TIMESTAMPS, and Wikimedia\Rdbms\ChronologyProtector\FLD_WRITE_INDEX.

Referenced by Wikimedia\Rdbms\ChronologyProtector\shutdown().

◆ setEnabled()

Wikimedia\Rdbms\ChronologyProtector::setEnabled ( $enabled )

Parameters

bool $enabled Whether reading/writing session replication positions is enabled

Since: 1.27

Definition at line 136 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$enabled.

◆ setLogger()

Wikimedia\Rdbms\ChronologyProtector::setLogger ( LoggerInterface $logger )

Definition at line 120 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$logger.

◆ setMockTime()

Wikimedia\Rdbms\ChronologyProtector::setMockTime ( & $time )

Definition at line 468 of file ChronologyProtector.php.

◆ setWaitEnabled()

Wikimedia\Rdbms\ChronologyProtector::setWaitEnabled ( $enabled )

Parameters

bool $enabled Whether session replication position wait barriers are enable

Since: 1.27

Definition at line 144 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$enabled.

◆ shutdown()

Wikimedia\Rdbms\ChronologyProtector::shutdown ( & $cpIndex = null )

Save any remarked "session consistency" DB replication positions to persistent storage.

Definition at line 221 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ChronologyProtector\$shutdownPositionsByMaster, and Wikimedia\Rdbms\ChronologyProtector\mergePositions().

Referenced by Wikimedia\Rdbms\LBFactory\shutdownChronologyProtector().

◆ stageSessionReplicationPosition()

Wikimedia\Rdbms\ChronologyProtector::stageSessionReplicationPosition ( ILoadBalancer $lb )

Update the "session consistency" DB replication position for an end-of-life ILoadBalancer.

This remarks the replication position of the master DB if this request made writes to it using the provided ILoadBalancer instance.

Definition at line 189 of file ChronologyProtector.php.

References Wikimedia\Rdbms\ILoadBalancer\getClusterName(), Wikimedia\Rdbms\ChronologyProtector\getCurrentTime(), Wikimedia\Rdbms\ILoadBalancer\getReplicaResumePos(), Wikimedia\Rdbms\ILoadBalancer\getServerName(), Wikimedia\Rdbms\ILoadBalancer\getWriterIndex(), Wikimedia\Rdbms\ILoadBalancer\hasOrMadeRecentMasterChanges(), and Wikimedia\Rdbms\ILoadBalancer\hasStreamingReplicaServers().

Referenced by Wikimedia\Rdbms\LBFactory\shutdownChronologyProtector().

Member Data Documentation

◆ $clientId

string Wikimedia\Rdbms\ChronologyProtector::$clientId

protected

Hash of client parameters.

Definition at line 50 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\getClientId().

◆ $clientLogInfo

string [] Wikimedia\Rdbms\ChronologyProtector::$clientLogInfo

protected

Map of client information fields for logging.

Definition at line 52 of file ChronologyProtector.php.

◆ $enabled

bool Wikimedia\Rdbms\ChronologyProtector::$enabled = true

protected

Whether reading/writing session consistency replication positions is enabled.

Definition at line 57 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\setEnabled(), and Wikimedia\Rdbms\ChronologyProtector\setWaitEnabled().

◆ $key

string Wikimedia\Rdbms\ChronologyProtector::$key

protected

Storage key name.

Definition at line 48 of file ChronologyProtector.php.

◆ $logger

LoggerInterface Wikimedia\Rdbms\ChronologyProtector::$logger

protected

Definition at line 45 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\setLogger().

◆ $positionWaitsEnabled

bool Wikimedia\Rdbms\ChronologyProtector::$positionWaitsEnabled = true

protected

Whether waiting on DB servers to reach replication positions is enabled.

Definition at line 59 of file ChronologyProtector.php.

◆ $shutdownPositionsByMaster

array<string,DBMasterPos> Wikimedia\Rdbms\ChronologyProtector::$shutdownPositionsByMaster = []

protected

Map of (DB master name => position)

Definition at line 66 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\shutdown().

◆ $shutdownTimestampsByCluster

array<string,float> Wikimedia\Rdbms\ChronologyProtector::$shutdownTimestampsByCluster = []

protected

Map of (DB cluster name => UNIX timestamp)

Definition at line 70 of file ChronologyProtector.php.

◆ $startupPositionsByMaster

array<string,DBMasterPos> Wikimedia\Rdbms\ChronologyProtector::$startupPositionsByMaster = []

protected

Map of (DB master name => position)

Definition at line 64 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\getStartupSessionPositions().

◆ $startupTimestamp

float null Wikimedia\Rdbms\ChronologyProtector::$startupTimestamp

protected

UNIX timestamp when the client data was loaded.

Definition at line 61 of file ChronologyProtector.php.

◆ $startupTimestampsByCluster

array<string,float> Wikimedia\Rdbms\ChronologyProtector::$startupTimestampsByCluster = []

protected

Map of (DB cluster name => UNIX timestamp)

Definition at line 68 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\getStartupSessionTimestamps().

◆ $store

BagOStuff Wikimedia\Rdbms\ChronologyProtector::$store

protected

Definition at line 43 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\__construct().

◆ $waitForPosIndex

int null Wikimedia\Rdbms\ChronologyProtector::$waitForPosIndex

protected

Expected minimum index of the last write to the position store.

Definition at line 54 of file ChronologyProtector.php.

◆ $wallClockOverride

float null Wikimedia\Rdbms\ChronologyProtector::$wallClockOverride

private

Definition at line 73 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\getCurrentTime().

◆ FLD_POSITIONS

const Wikimedia\Rdbms\ChronologyProtector::FLD_POSITIONS = 'positions'

private

Definition at line 87 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\lazyStartup(), and Wikimedia\Rdbms\ChronologyProtector\mergePositions().

◆ FLD_TIMESTAMPS

const Wikimedia\Rdbms\ChronologyProtector::FLD_TIMESTAMPS = 'timestamps'

private

Definition at line 88 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\lazyStartup(), and Wikimedia\Rdbms\ChronologyProtector\mergePositions().

◆ FLD_WRITE_INDEX

const Wikimedia\Rdbms\ChronologyProtector::FLD_WRITE_INDEX = 'writeIndex'

private

Definition at line 89 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\lazyStartup(), and Wikimedia\Rdbms\ChronologyProtector\mergePositions().

◆ LOCK_TIMEOUT

const Wikimedia\Rdbms\ChronologyProtector::LOCK_TIMEOUT = 3

private

Lock timeout to use for key updates.

Definition at line 83 of file ChronologyProtector.php.

◆ LOCK_TTL

const Wikimedia\Rdbms\ChronologyProtector::LOCK_TTL = 6

private

Lock expiry to use for key updates.

Definition at line 85 of file ChronologyProtector.php.

◆ POSITION_COOKIE_TTL

const Wikimedia\Rdbms\ChronologyProtector::POSITION_COOKIE_TTL = 10

Seconds to store position write index cookies (safely less than POSITION_STORE_TTL)

Definition at line 76 of file ChronologyProtector.php.

◆ POSITION_INDEX_WAIT_TIMEOUT

const Wikimedia\Rdbms\ChronologyProtector::POSITION_INDEX_WAIT_TIMEOUT = 5

private

Max seconds to wait for positions write indexes to appear (e.g.

replicate) in storage

Definition at line 80 of file ChronologyProtector.php.

Referenced by Wikimedia\Rdbms\ChronologyProtector\lazyStartup().

◆ POSITION_STORE_TTL

const Wikimedia\Rdbms\ChronologyProtector::POSITION_STORE_TTL = 60

private

Seconds to store replication positions.

Definition at line 78 of file ChronologyProtector.php.

The documentation for this class was generated from the following file:

includes/libs/rdbms/ChronologyProtector.php

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ applySessionReplicationPosition()

◆ getClientId()

◆ getCurrentTime()

◆ getStartupSessionPositions()

◆ getStartupSessionTimestamps()

◆ getTouched()

◆ lazyStartup()

◆ mergePositions()

◆ setEnabled()

◆ setLogger()

◆ setMockTime()

◆ setWaitEnabled()

◆ shutdown()

◆ stageSessionReplicationPosition()

Member Data Documentation

◆ $clientId

◆ $clientLogInfo

◆ $enabled

◆ $key

◆ $logger

◆ $positionWaitsEnabled

◆ $shutdownPositionsByMaster

◆ $shutdownTimestampsByCluster

◆ $startupPositionsByMaster

◆ $startupTimestamp

◆ $startupTimestampsByCluster

◆ $store

◆ $waitForPosIndex

◆ $wallClockOverride

◆ FLD_POSITIONS

◆ FLD_TIMESTAMPS

◆ FLD_WRITE_INDEX

◆ LOCK_TIMEOUT

◆ LOCK_TTL

◆ POSITION_COOKIE_TTL

◆ POSITION_INDEX_WAIT_TIMEOUT

◆ POSITION_STORE_TTL