Interface to key-value storage behind an HTTP server. More...

Inheritance diagram for RESTBagOStuff:

[legend]

Collaboration diagram for RESTBagOStuff:

[legend]

Public Member Functions
	__construct ( $params)

	decr ( $key, $value=1, $flags=0)
	Decrease stored value of $key by $value while preserving its TTL.

	incr ( $key, $value=1, $flags=0)
	Increase stored value of $key by $value while preserving its TTL.

	setLogger (LoggerInterface $logger)

Public Member Functions inherited from MediumSpecificBagOStuff
	__construct (array $params=[])

	add ( $key, $value, $exptime=0, $flags=0)
	Insert an item if it does not already exist.

	addBusyCallback (callable $workCallback)
	Let a callback be run to avoid wasting time on special blocking calls.

	changeTTL ( $key, $exptime=0, $flags=0)
	Change the expiration on a key if it exists.

	changeTTLMulti (array $keys, $exptime, $flags=0)
	Change the expiration of multiple keys that exist.

	clearLastError ()
	Clear the "last error" registry.

	delete ( $key, $flags=0)
	Delete an item.

	deleteMulti (array $keys, $flags=0)
	Batch deletion.

	deleteObjectsExpiringBefore ( $timestamp, callable $progress=null, $limit=INF)
	Delete all objects expiring before a certain date.

	get ( $key, $flags=0)
	Get an item with the given key.

	getLastError ()
	Get the "last error" registered; clearLastError() should be called manually.

	getMulti (array $keys, $flags=0)
	Get an associative array containing the item for each of the keys that have items.

	getQoS ( $flag)

	getSegmentationSize ()

	getSegmentedValueMaxSize ()

	incrWithInit ( $key, $exptime, $value=1, $init=null, $flags=0)
	Increase the value of the given key (no TTL change) if it exists or create it otherwise.

	lock ( $key, $timeout=6, $expiry=6, $rclass='')
	Acquire an advisory lock on a key string.

	makeGlobalKey ( $class,... $components)
	Make a global cache key.

	makeKey ( $class,... $components)
	Make a cache key, scoped to this instance's keyspace.

	makeKeyInternal ( $keyspace, $args)
	Construct a cache key.

	merge ( $key, callable $callback, $exptime=0, $attempts=10, $flags=0)
	Merge changes into the existing cache value (possibly creating a new one)

	set ( $key, $value, $exptime=0, $flags=0)
	Set an item.

	setMulti (array $data, $exptime=0, $flags=0)
	Batch insertion/replace.

	unlock ( $key)
	Release an advisory lock on a key string.

Public Member Functions inherited from BagOStuff
	getCurrentTime ()

	getScopedLock ( $key, $timeout=6, $expiry=30, $rclass='')
	Get a lightweight exclusive self-unlocking lock.

	getWithSetCallback ( $key, $ttl, $callback, $flags=0)
	Get an item with the given key, regenerating and setting it if not found.

	setDebug ( $enabled)

	setMockTime (&$time)

Public Attributes
const	DEFAULT_CONN_TIMEOUT = 1.2
	Default connection timeout in seconds.

const	DEFAULT_REQ_TIMEOUT = 3.0
	Default request timeout.

Public Attributes inherited from BagOStuff
const	READ_LATEST = 1
	Bitfield constants for get()/getMulti(); these are only advisory.

const	READ_VERIFIED = 2

const	WRITE_ALLOW_SEGMENTS = 16

const	WRITE_BACKGROUND = 64

const	WRITE_CACHE_ONLY = 8

const	WRITE_PRUNE_SEGMENTS = 32

const	WRITE_SYNC = 4
	Bitfield constants for set()/merge(); these are only advisory.

Public Attributes inherited from IExpiringStore
const	ATTR_EMULATION = 1

const	ATTR_SYNCWRITES = 2

const	ERR_NO_RESPONSE = 1

const	ERR_NONE = 0

const	ERR_UNEXPECTED = 3

const	ERR_UNREACHABLE = 2

const	QOS_EMULATION_SQL = 1

const	QOS_SYNCWRITES_BE = 2

const	QOS_SYNCWRITES_NONE = 1

const	QOS_SYNCWRITES_QC = 3

const	QOS_SYNCWRITES_SS = 4

const	QOS_UNKNOWN = INF

const	TTL_DAY = 86400

const	TTL_HOUR = 3600

const	TTL_INDEFINITE = 0

const	TTL_MINUTE = 60

const	TTL_MONTH = 2592000

const	TTL_PROC_LONG = 30

const	TTL_PROC_SHORT = 3

const	TTL_SECOND = 1

const	TTL_WEEK = 604800

const	TTL_YEAR = 31536000

Protected Member Functions
	doAdd ( $key, $value, $exptime=0, $flags=0)
	Insert an item if it does not already exist.

	doDelete ( $key, $flags=0)
	Delete an item.

	doGet ( $key, $flags=0, &$casToken=null)

	doSet ( $key, $value, $exptime=0, $flags=0)
	Set an item.

	handleError ( $msg, $rcode, $rerr, $rhdrs, $rbody)
	Handle storage error.

Protected Member Functions inherited from MediumSpecificBagOStuff
	cas ( $casToken, $key, $value, $exptime=0, $flags=0)
	Check and set an item.

	debug ( $text)

	doCas ( $casToken, $key, $value, $exptime=0, $flags=0)
	Check and set an item.

	doChangeTTL ( $key, $exptime, $flags)

	doDeleteMulti (array $keys, $flags=0)

	doGetMulti (array $keys, $flags=0)
	Get an associative array containing the item for each of the keys that have items.

	doSetMulti (array $data, $exptime=0, $flags=0)

	getExpirationAsTimestamp ( $exptime)
	Convert an optionally relative timestamp to an absolute time.

	getExpirationAsTTL ( $exptime)
	Convert an optionally absolute expiry time to a relative time.

	isInteger ( $value)
	Check if a value is an integer.

	isRelativeExpiration ( $exptime)

	makeValueOrSegmentList ( $key, $value, $exptime, $flags)
	Determine the entry (inline or segment list) to store under a key to save the value.

	mergeViaCas ( $key, callable $callback, $exptime, $attempts, $flags)

	resolveSegments ( $key, $mainValue)
	Get and reassemble the chunks of blob at the given key.

	serialize ( $value)

	setLastError ( $err)
	Set the "last error" registry.

	unserialize ( $value)

Protected Member Functions inherited from BagOStuff
	fieldHasFlags ( $field, $flags)

	mergeFlagMaps (array $bags)
	Merge the flag maps of one or more BagOStuff objects into a "lowest common denominator" map.

Private Member Functions
	decodeBody ( $body)
	Processes the response body.

	encodeBody ( $body)
	Prepares the request body (the "value" portion of our key/value store) for transmission.

Private Attributes
MultiHttpClient	$client

array	$extendedErrorBodyFields
	additional body fields to log on error, if possible

string	$hmacKey
	Optional HMAC Key for protecting the serialized blob.

array	$httpParams
	http parameters: readHeaders, writeHeaders, deleteHeaders, writeMethod

string	$serializationType
	Optional serialization type to use.

string	$url
	REST URL to use for storage.

Additional Inherited Members
Protected Attributes inherited from MediumSpecificBagOStuff
callable[]	$busyCallbacks = []

string	$keyspace = 'local'

int	$lastError = self::ERR_NONE
	ERR_* class constant.

array[]	$locks = []
	Lock tracking.

int	$segmentationSize
	Bytes; chunk size of segmented cache values.

int	$segmentedValueMaxSize
	Bytes; maximum total size of a segmented cache value.

int	$syncTimeout
	Seconds.

Protected Attributes inherited from BagOStuff
callable null	$asyncHandler

int[]	$attrMap = []
	Map of (ATTR_* class constant => QOS_* class constant)

bool	$debugMode = false

LoggerInterface	$logger

Detailed Description

Interface to key-value storage behind an HTTP server.

Uses URL of the form "baseURL/{KEY}" to store, fetch, and delete values.

E.g., when base URL is /sessions/v1, then the store would do:

PUT /sessions/v1/12345758

and fetch would do:

GET /sessions/v1/12345758

delete would do:

DELETE /sessions/v1/12345758

Minimal generic configuration:

$wgObjectCaches['sessions'] = array(
 'class' => 'RESTBagOStuff',
 'url' => 'http://localhost:7231/wikimedia.org/somepath/'
);

Configuration for Kask (session storage):

$wgObjectCaches['sessions'] = array(
 'class' => 'RESTBagOStuff',
 'url' => 'https://kaskhost:1234/sessions/v1/',
 'httpParams' => [
    'readHeaders' => [],
    'writeHeaders' => [ 'content-type' => 'application/octet-stream' ],
    'deleteHeaders' => [],
    'writeMethod' => 'POST',
 ],
 'serialization_type' => 'JSON',
    'extendedErrorBodyFields' => [ 'type', 'title', 'detail', 'instance' ]
);
$wgSessionCacheType = 'sessions';

Definition at line 48 of file RESTBagOStuff.php.

Constructor & Destructor Documentation

◆ __construct()

RESTBagOStuff::__construct ( $params )

Definition at line 98 of file RESTBagOStuff.php.

References IExpiringStore\ATTR_SYNCWRITES, DEFAULT_CONN_TIMEOUT, DEFAULT_REQ_TIMEOUT, and IExpiringStore\QOS_SYNCWRITES_QC.

Member Function Documentation

◆ decodeBody()

RESTBagOStuff::decodeBody ( $body )

private

Processes the response body.

Parameters

string $body request body to process

Returns: mixed|bool the processed body, or false on error

Definition at line 232 of file RESTBagOStuff.php.

References $serialized, and MediumSpecificBagOStuff\unserialize().

Referenced by doGet(), and handleError().

◆ decr()

RESTBagOStuff::decr	(	$key,
		$value = `1`,
		$flags = `0`
	)

Decrease stored value of $key by $value while preserving its TTL.

Parameters

string	$key
int	$value	Value to subtract from $key (default: 1) [optional]
int	$flags	Bit field of class WRITE_* constants [optional]

Returns: int|bool New value or false on failure

Reimplemented from BagOStuff.

Definition at line 222 of file RESTBagOStuff.php.

References incr().

◆ doAdd()

RESTBagOStuff::doAdd	(	$key,
		$value,
		$exptime = `0`,
		$flags = `0`
	)

protected

Insert an item if it does not already exist.

Parameters

string	$key
mixed	$value
int	$exptime
int	$flags	Bitfield of BagOStuff::WRITE_* constants (since 1.33)

Returns: bool Success

Reimplemented from MediumSpecificBagOStuff.

Definition at line 186 of file RESTBagOStuff.php.

◆ doDelete()

RESTBagOStuff::doDelete	(	$key,
		$flags = `0`
	)

protected

Delete an item.

Parameters

string	$key
int	$flags	Bitfield of BagOStuff::WRITE_* constants

Returns: bool True if the item was deleted or not found, false on failure

Reimplemented from MediumSpecificBagOStuff.

Definition at line 195 of file RESTBagOStuff.php.

References handleError().

◆ doGet()

RESTBagOStuff::doGet	(		$key,
			$flags = `0`,
		&	$casToken = `null`
	)

protected

Parameters

string	$key
int	$flags	Bitfield of BagOStuff::READ_* constants [optional]
mixed \| null	&$casToken	Token to use for check-and-set comparisons

Returns: mixed Returns false on failure or if the item does not exist

Reimplemented from MediumSpecificBagOStuff.

Definition at line 143 of file RESTBagOStuff.php.

References decodeBody(), and handleError().

◆ doSet()

RESTBagOStuff::doSet	(	$key,
		$value,
		$exptime = `0`,
		$flags = `0`
	)

protected

Set an item.

Parameters

string	$key
mixed	$value
int	$exptime	Either an interval in seconds or a unix timestamp for expiry
int	$flags	Bitfield of BagOStuff::WRITE_* constants

Returns: bool Success

Reimplemented from MediumSpecificBagOStuff.

Definition at line 169 of file RESTBagOStuff.php.

References encodeBody(), and handleError().

◆ encodeBody()

RESTBagOStuff::encodeBody ( $body )

private

Prepares the request body (the "value" portion of our key/value store) for transmission.

Parameters

string $body request body to prepare

Returns: string the prepared body

Exceptions

LogicException

Definition at line 272 of file RESTBagOStuff.php.

References serialize().

Referenced by doSet().

◆ handleError()

RESTBagOStuff::handleError	(	$msg,
		$rcode,
		$rerr,
		$rhdrs,
		$rbody
	)

protected

Handle storage error.

Parameters

string	$msg	Error message
int	$rcode	Error code from client
string	$rerr	Error message from client
array	$rhdrs	Response headers
string	$rbody	Error body from client (if any)

Returns: false

Definition at line 315 of file RESTBagOStuff.php.

References $context, decodeBody(), IExpiringStore\ERR_UNEXPECTED, and MediumSpecificBagOStuff\setLastError().

Referenced by doDelete(), doGet(), and doSet().

◆ incr()

RESTBagOStuff::incr	(	$key,
		$value = `1`,
		$flags = `0`
	)

Increase stored value of $key by $value while preserving its TTL.

Parameters

string	$key	Key to increase
int	$value	Value to add to $key (default: 1) [optional]
int	$flags	Bit field of class WRITE_* constants [optional]

Returns: int|bool New value or false on failure

Reimplemented from BagOStuff.

Definition at line 210 of file RESTBagOStuff.php.

References MediumSpecificBagOStuff\isInteger(), and BagOStuff\READ_LATEST.

Referenced by decr().

◆ setLogger()

RESTBagOStuff::setLogger ( LoggerInterface $logger )

Parameters

LoggerInterface $logger

Returns: void

Reimplemented from BagOStuff.

Definition at line 138 of file RESTBagOStuff.php.

References BagOStuff\$logger.

Member Data Documentation

◆ $client

MultiHttpClient RESTBagOStuff::$client

private

Definition at line 64 of file RESTBagOStuff.php.

◆ $extendedErrorBodyFields

array RESTBagOStuff::$extendedErrorBodyFields

private

additional body fields to log on error, if possible

Definition at line 96 of file RESTBagOStuff.php.

◆ $hmacKey

string RESTBagOStuff::$hmacKey

private

Optional HMAC Key for protecting the serialized blob.

If omitted, or if serializationType is "legacy", then no protection is done

Definition at line 91 of file RESTBagOStuff.php.

◆ $httpParams

array RESTBagOStuff::$httpParams

private

http parameters: readHeaders, writeHeaders, deleteHeaders, writeMethod

Definition at line 75 of file RESTBagOStuff.php.

◆ $serializationType

string RESTBagOStuff::$serializationType

private

Optional serialization type to use.

Allowed values: "PHP", "JSON", or "legacy". "legacy" is PHP serialization with no serialization type tagging or hmac protection.

Deprecated:: since 1.34, the "legacy" value will be removed in 1.35. Use either "PHP" or "JSON".

Definition at line 84 of file RESTBagOStuff.php.

◆ $url

string RESTBagOStuff::$url

private

REST URL to use for storage.

Definition at line 70 of file RESTBagOStuff.php.

◆ DEFAULT_CONN_TIMEOUT

const RESTBagOStuff::DEFAULT_CONN_TIMEOUT = 1.2

Default connection timeout in seconds.

The kernel retransmits the SYN packet after 1 second, so 1.2 seconds allows for 1 retransmit without permanent failure.

Definition at line 54 of file RESTBagOStuff.php.

Referenced by __construct().

◆ DEFAULT_REQ_TIMEOUT

const RESTBagOStuff::DEFAULT_REQ_TIMEOUT = 3.0

Default request timeout.

Definition at line 59 of file RESTBagOStuff.php.

Referenced by __construct().

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

includes/libs/objectcache/RESTBagOStuff.php

Public Member Functions

Public Attributes

Protected Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ decodeBody()

◆ decr()

◆ doAdd()

◆ doDelete()

◆ doGet()

◆ doSet()

◆ encodeBody()

◆ handleError()

◆ incr()

◆ setLogger()

Member Data Documentation

◆ $client

◆ $extendedErrorBodyFields

◆ $hmacKey

◆ $httpParams

◆ $serializationType

◆ $url

◆ DEFAULT_CONN_TIMEOUT

◆ DEFAULT_REQ_TIMEOUT