MediaWiki  1.34.0
RESTBagOStuff Class Reference

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

Inheritance diagram for RESTBagOStuff:
Collaboration diagram for RESTBagOStuff:

Public Member Functions

 __construct ( $params)
 
 decr ( $key, $value=1, $flags=0)
 Decrease stored value of $key by $value while preserving its TTL. More...
 
 incr ( $key, $value=1, $flags=0)
 Increase stored value of $key by $value while preserving its TTL. More...
 
 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. More...
 
 addBusyCallback (callable $workCallback)
 Let a callback be run to avoid wasting time on special blocking calls. More...
 
 changeTTL ( $key, $exptime=0, $flags=0)
 Change the expiration on a key if it exists. More...
 
 changeTTLMulti (array $keys, $exptime, $flags=0)
 Change the expiration of multiple keys that exist. More...
 
 clearLastError ()
 Clear the "last error" registry. More...
 
 delete ( $key, $flags=0)
 Delete an item. More...
 
 deleteMulti (array $keys, $flags=0)
 Batch deletion. More...
 
 deleteObjectsExpiringBefore ( $timestamp, callable $progress=null, $limit=INF)
 Delete all objects expiring before a certain date. More...
 
 get ( $key, $flags=0)
 Get an item with the given key. More...
 
 getLastError ()
 Get the "last error" registered; clearLastError() should be called manually. More...
 
 getMulti (array $keys, $flags=0)
 Get an associative array containing the item for each of the keys that have items. More...
 
 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. More...
 
 lock ( $key, $timeout=6, $expiry=6, $rclass='')
 Acquire an advisory lock on a key string. More...
 
 makeGlobalKey ( $class,... $components)
 Make a global cache key. More...
 
 makeKey ( $class,... $components)
 Make a cache key, scoped to this instance's keyspace. More...
 
 makeKeyInternal ( $keyspace, $args)
 Construct a cache key. More...
 
 merge ( $key, callable $callback, $exptime=0, $attempts=10, $flags=0)
 Merge changes into the existing cache value (possibly creating a new one) More...
 
 set ( $key, $value, $exptime=0, $flags=0)
 Set an item. More...
 
 setMulti (array $data, $exptime=0, $flags=0)
 Batch insertion/replace. More...
 
 unlock ( $key)
 Release an advisory lock on a key string. More...
 
- Public Member Functions inherited from BagOStuff
 getCurrentTime ()
 
 getScopedLock ( $key, $timeout=6, $expiry=30, $rclass='')
 Get a lightweight exclusive self-unlocking lock. More...
 
 getWithSetCallback ( $key, $ttl, $callback, $flags=0)
 Get an item with the given key, regenerating and setting it if not found. More...
 
 setDebug ( $enabled)
 
 setMockTime (&$time)
 

Public Attributes

const DEFAULT_CONN_TIMEOUT = 1.2
 Default connection timeout in seconds. More...
 
const DEFAULT_REQ_TIMEOUT = 3.0
 Default request timeout. More...
 
- Public Attributes inherited from BagOStuff
const READ_LATEST = 1
 Bitfield constants for get()/getMulti(); these are only advisory. More...
 
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. More...
 
- 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. More...
 
 doDelete ( $key, $flags=0)
 Delete an item. More...
 
 doGet ( $key, $flags=0, &$casToken=null)
 
 doSet ( $key, $value, $exptime=0, $flags=0)
 Set an item. More...
 
 handleError ( $msg, $rcode, $rerr, $rhdrs, $rbody)
 Handle storage error. More...
 
- Protected Member Functions inherited from MediumSpecificBagOStuff
 cas ( $casToken, $key, $value, $exptime=0, $flags=0)
 Check and set an item. More...
 
 debug ( $text)
 
 doCas ( $casToken, $key, $value, $exptime=0, $flags=0)
 Check and set an item. More...
 
 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. More...
 
 doSetMulti (array $data, $exptime=0, $flags=0)
 
 getExpirationAsTimestamp ( $exptime)
 Convert an optionally relative timestamp to an absolute time. More...
 
 getExpirationAsTTL ( $exptime)
 Convert an optionally absolute expiry time to a relative time. More...
 
 isInteger ( $value)
 Check if a value is an integer. More...
 
 isRelativeExpiration ( $exptime)
 
 makeValueOrSegmentList ( $key, $value, $exptime, $flags)
 Determine the entry (inline or segment list) to store under a key to save the value. More...
 
 mergeViaCas ( $key, callable $callback, $exptime, $attempts, $flags)
 
 resolveSegments ( $key, $mainValue)
 Get and reassemble the chunks of blob at the given key. More...
 
 serialize ( $value)
 
 setLastError ( $err)
 Set the "last error" registry. More...
 
 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. More...
 

Private Member Functions

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

Private Attributes

MultiHttpClient $client
 
array $extendedErrorBodyFields
 additional body fields to log on error, if possible More...
 
string $hmacKey
 Optional HMAC Key for protecting the serialized blob. More...
 
array $httpParams
 http parameters: readHeaders, writeHeaders, deleteHeaders, writeMethod More...
 
string $serializationType
 Optional serialization type to use. More...
 
string $url
 REST URL to use for storage. More...
 

Additional Inherited Members

- Protected Attributes inherited from MediumSpecificBagOStuff
callable[] $busyCallbacks = []
 
string $keyspace = 'local'
 
int $lastError = self::ERR_NONE
 ERR_* class constant. More...
 
array[] $locks = []
 Lock tracking. More...
 
int $segmentationSize
 Bytes; chunk size of segmented cache values. More...
 
int $segmentedValueMaxSize
 Bytes; maximum total size of a segmented cache value. More...
 
int $syncTimeout
 Seconds. More...
 
- Protected Attributes inherited from BagOStuff
callable null $asyncHandler
 
int[] $attrMap = []
 Map of (ATTR_* class constant => QOS_* class constant) More...
 
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)

Member Function Documentation

◆ decodeBody()

RESTBagOStuff::decodeBody (   $body)
private

Processes the response body.

Parameters
string$bodyrequest 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$valueValue to subtract from $key (default: 1) [optional]
int$flagsBit 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$flagsBitfield 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$flagsBitfield 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$flagsBitfield of BagOStuff::READ_* constants [optional]
mixed | null&$casTokenToken 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$exptimeEither an interval in seconds or a unix timestamp for expiry
int$flagsBitfield 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$bodyrequest body to prepare
Returns
string the prepared body
Exceptions
LogicException

Definition at line 272 of file RESTBagOStuff.php.

References MediumSpecificBagOStuff\serialize().

Referenced by doSet().

◆ handleError()

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

Handle storage error.

Parameters
string$msgError message
int$rcodeError code from client
string$rerrError message from client
array$rhdrsResponse headers
string$rbodyError body from client (if any)
Returns
false

Definition at line 315 of file RESTBagOStuff.php.

References $context, decodeBody(), 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$keyKey to increase
int$valueValue to add to $key (default: 1) [optional]
int$flagsBit 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:
$wgObjectCaches
$wgObjectCaches
Advanced object cache configuration.
Definition: DefaultSettings.php:2393
$wgSessionCacheType
$wgSessionCacheType
The cache type for storing session data.
Definition: DefaultSettings.php:2368