includes/libs/objectcache/RESTBagOStuff.php
<?php
namespace Wikimedia\ObjectCache;
use InvalidArgumentException;
use Psr\Log\LoggerInterface;
use Wikimedia\Http\MultiHttpClient;
/**
* Store key-value data via an HTTP service.
*
* ### Important caveats
*
* This interface is currently an incomplete BagOStuff implementation,
* supported only for use with MediaWiki features that accept a dedicated
* cache type to use for a narrow set of cache keys that share the same
* key expiry and replication requirements, and where the key-value server
* in question is statically configured with domain knowledge of said
* key expiry and replication requirements.
*
* Specifically, RESTBagOStuff has the following limitations:
*
* - The expiry parameter is ignored in methods like `set()`.
*
* There is not currently an agreed protocol for sending this to a
* server. This class is written for use with MediaWiki\Session\SessionManager
* and Kask/Cassanda at WMF, which does not expose a customizable expiry.
*
* As such, it is not recommended to use RESTBagOStuff to back a general
* purpose cache type (such as MediaWiki's main cache, or main stash).
* Instead, it is only supported toMediaWiki features where a cache type can
* be pointed for a narrow set of keys that naturally share the same TTL
* anyway, or where the feature behaves correctly even if the logical expiry
* is longer than specified (e.g. immutable keys, or value verification)
*
* - Most methods are non-atomic.
*
* The class should only be used for get, set, and delete operations.
* Advanced methods like `incr()`, `add()` and `lock()` do exist but
* inherit a native and best-effort implementation based on get+set.
* These should not be relied upon.
*
* ### Backend requirements
*
* The HTTP server will receive requests for URLs like `{baseURL}/{KEY}`. It
* must implement the GET, PUT and DELETE methods.
*
* E.g., when the base URL is `/sessions/v1`, then `set()` will:
*
* `PUT /sessions/v1/mykeyhere`
*
* and `get()` would do:
*
* `GET /sessions/v1/mykeyhere`
*
* and `delete()` would do:
*
* `DELETE /sessions/v1/mykeyhere`
*
* ### Example configuration
*
* Minimal generic configuration:
*
* @code
* $wgObjectCaches['sessions'] = array(
* 'class' => 'RESTBagOStuff',
* 'url' => 'http://localhost:7231/example/'
* );
* @endcode
*
*
* Configuration for [Kask](https://www.mediawiki.org/wiki/Kask) session store:
* @code
* $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';
* @endcode
*/
class RESTBagOStuff extends MediumSpecificBagOStuff {
/**
* 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.
*/
private const DEFAULT_CONN_TIMEOUT = 1.2;
/**
* Default request timeout
*/
private const DEFAULT_REQ_TIMEOUT = 3.0;
/**
* @var MultiHttpClient
*/
private $client;
/**
* REST URL to use for storage.
*
* @var string
*/
private $url;
/**
* HTTP parameters: readHeaders, writeHeaders, deleteHeaders, writeMethod.
*
* @var array
*/
private $httpParams;
/**
* Optional serialization type to use. Allowed values: "PHP", "JSON".
*
* @var string
*/
private $serializationType;
/**
* Optional HMAC Key for protecting the serialized blob. If omitted no protection is done
*
* @var string
*/
private $hmacKey;
/**
* @var array additional body fields to log on error, if possible
*/
private $extendedErrorBodyFields;
public function __construct( $params ) {
$params['segmentationSize'] ??= INF;
if ( empty( $params['url'] ) ) {
throw new InvalidArgumentException( 'URL parameter is required' );
}
if ( empty( $params['client'] ) ) {
// Pass through some params to the HTTP client.
$clientParams = [
'connTimeout' => $params['connTimeout'] ?? self::DEFAULT_CONN_TIMEOUT,
'reqTimeout' => $params['reqTimeout'] ?? self::DEFAULT_REQ_TIMEOUT,
];
foreach ( [ 'caBundlePath', 'proxy', 'telemetry' ] as $key ) {
if ( isset( $params[$key] ) ) {
$clientParams[$key] = $params[$key];
}
}
$this->client = new MultiHttpClient( $clientParams );
} else {
$this->client = $params['client'];
}
$this->httpParams['writeMethod'] = $params['httpParams']['writeMethod'] ?? 'PUT';
$this->httpParams['readHeaders'] = $params['httpParams']['readHeaders'] ?? [];
$this->httpParams['writeHeaders'] = $params['httpParams']['writeHeaders'] ?? [];
$this->httpParams['deleteHeaders'] = $params['httpParams']['deleteHeaders'] ?? [];
$this->extendedErrorBodyFields = $params['extendedErrorBodyFields'] ?? [];
$this->serializationType = $params['serialization_type'] ?? 'PHP';
$this->hmacKey = $params['hmac_key'] ?? '';
// The parent constructor calls setLogger() which sets the logger in $this->client
parent::__construct( $params );
// Make sure URL ends with /
$this->url = rtrim( $params['url'], '/' ) . '/';
$this->attrMap[self::ATTR_DURABILITY] = self::QOS_DURABILITY_DISK;
}
public function setLogger( LoggerInterface $logger ) {
parent::setLogger( $logger );
$this->client->setLogger( $logger );
}
protected function doGet( $key, $flags = 0, &$casToken = null ) {
$getToken = ( $casToken === self::PASS_BY_REF );
$casToken = null;
$req = [
'method' => 'GET',
'url' => $this->url . rawurlencode( $key ),
'headers' => $this->httpParams['readHeaders'],
];
$value = false;
$valueSize = false;
[ $rcode, , $rhdrs, $rbody, $rerr ] = $this->client->run( $req );
if ( $rcode === 200 && is_string( $rbody ) ) {
$value = $this->decodeBody( $rbody );
$valueSize = strlen( $rbody );
// @FIXME: use some kind of hash or UUID header as CAS token
if ( $getToken && $value !== false ) {
$casToken = $rbody;
}
} elseif ( $rcode === 0 || ( $rcode >= 400 && $rcode != 404 ) ) {
$this->handleError( 'Failed to fetch {cacheKey}', $rcode, $rerr, $rhdrs, $rbody,
[ 'cacheKey' => $key ] );
}
$this->updateOpStats( self::METRIC_OP_GET, [ $key => [ 0, $valueSize ] ] );
return $value;
}
protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) {
$req = [
'method' => $this->httpParams['writeMethod'],
'url' => $this->url . rawurlencode( $key ),
'body' => $this->encodeBody( $value ),
'headers' => $this->httpParams['writeHeaders'],
];
[ $rcode, , $rhdrs, $rbody, $rerr ] = $this->client->run( $req );
$res = ( $rcode === 200 || $rcode === 201 || $rcode === 204 );
if ( !$res ) {
$this->handleError( 'Failed to store {cacheKey}', $rcode, $rerr, $rhdrs, $rbody,
[ 'cacheKey' => $key ] );
}
$this->updateOpStats( self::METRIC_OP_SET, [ $key => [ strlen( $rbody ), 0 ] ] );
return $res;
}
protected function doAdd( $key, $value, $exptime = 0, $flags = 0 ) {
// NOTE: This is non-atomic
if ( $this->get( $key ) === false ) {
return $this->set( $key, $value, $exptime, $flags );
}
// key already set
return false;
}
protected function doDelete( $key, $flags = 0 ) {
$req = [
'method' => 'DELETE',
'url' => $this->url . rawurlencode( $key ),
'headers' => $this->httpParams['deleteHeaders'],
];
[ $rcode, , $rhdrs, $rbody, $rerr ] = $this->client->run( $req );
$res = in_array( $rcode, [ 200, 204, 205, 404, 410 ] );
if ( !$res ) {
$this->handleError( 'Failed to delete {cacheKey}', $rcode, $rerr, $rhdrs, $rbody,
[ 'cacheKey' => $key ] );
}
$this->updateOpStats( self::METRIC_OP_DELETE, [ $key ] );
return $res;
}
protected function doIncrWithInit( $key, $exptime, $step, $init, $flags ) {
// NOTE: This is non-atomic
$curValue = $this->doGet( $key );
if ( $curValue === false ) {
$newValue = $this->doSet( $key, $init, $exptime ) ? $init : false;
} elseif ( $this->isInteger( $curValue ) ) {
$sum = max( $curValue + $step, 0 );
$newValue = $this->doSet( $key, $sum, $exptime ) ? $sum : false;
} else {
$newValue = false;
}
return $newValue;
}
/**
* Processes the response body.
*
* @param string $body request body to process
*
* @return mixed|bool the processed body, or false on error
*/
private function decodeBody( $body ) {
$pieces = explode( '.', $body, 3 );
if ( count( $pieces ) !== 3 || $pieces[0] !== $this->serializationType ) {
return false;
}
[ , $hmac, $serialized ] = $pieces;
if ( $this->hmacKey !== '' ) {
$checkHmac = hash_hmac( 'sha256', $serialized, $this->hmacKey, true );
if ( !hash_equals( $checkHmac, base64_decode( $hmac ) ) ) {
return false;
}
}
switch ( $this->serializationType ) {
case 'JSON':
$value = json_decode( $serialized, true );
return ( json_last_error() === JSON_ERROR_NONE ) ? $value : false;
case 'PHP':
return unserialize( $serialized );
default:
throw new \DomainException(
"Unknown serialization type: $this->serializationType"
);
}
}
/**
* Prepares the request body (the "value" portion of our key/value store) for transmission.
*
* @param string $body request body to prepare
*
* @return string the prepared body
*/
private function encodeBody( $body ) {
switch ( $this->serializationType ) {
case 'JSON':
$value = json_encode( $body );
if ( $value === false ) {
throw new InvalidArgumentException( __METHOD__ . ": body could not be encoded." );
}
break;
case 'PHP':
$value = serialize( $body );
break;
default:
throw new \DomainException(
"Unknown serialization type: $this->serializationType"
);
}
if ( $this->hmacKey !== '' ) {
$hmac = base64_encode(
hash_hmac( 'sha256', $value, $this->hmacKey, true )
);
} else {
$hmac = '';
}
return $this->serializationType . '.' . $hmac . '.' . $value;
}
/**
* Handle storage error
*
* @param string $msg Error message
* @param int $rcode Error code from client
* @param string $rerr Error message from client
* @param array $rhdrs Response headers
* @param string $rbody Error body from client (if any)
* @param array $context Error context for PSR-3 logging
*/
protected function handleError( $msg, $rcode, $rerr, $rhdrs, $rbody, $context = [] ) {
$message = "$msg : ({code}) {error}";
$context = [
'code' => $rcode,
'error' => $rerr
] + $context;
if ( $this->extendedErrorBodyFields !== [] ) {
$body = $this->decodeBody( $rbody );
if ( $body ) {
$extraFields = '';
foreach ( $this->extendedErrorBodyFields as $field ) {
if ( isset( $body[$field] ) ) {
$extraFields .= " : ({$field}) {$body[$field]}";
}
}
if ( $extraFields !== '' ) {
$message .= " {extra_fields}";
$context['extra_fields'] = $extraFields;
}
}
}
$this->logger->error( $message, $context );
$this->setLastError( $rcode === 0 ? self::ERR_UNREACHABLE : self::ERR_UNEXPECTED );
}
}
/** @deprecated class alias since 1.43 */
class_alias( RESTBagOStuff::class, 'RESTBagOStuff' );