*
* Uses URL of the form "baseURL/{KEY}" to store, fetch, and delete values.
*
- * E.g., when base URL is `/v1/sessions/`, then the store would do:
+ * E.g., when base URL is `/sessions/v1`, then the store would do:
*
- * `PUT /v1/sessions/12345758`
+ * `PUT /sessions/v1/12345758`
*
* and fetch would do:
*
- * `GET /v1/sessions/12345758`
+ * `GET /sessions/v1/12345758`
*
* delete would do:
*
- * `DELETE /v1/sessions/12345758`
+ * `DELETE /sessions/v1/12345758`
*
- * Configure with:
+ * Minimal generic configuration:
*
* @code
* $wgObjectCaches['sessions'] = array(
* 'class' => 'RESTBagOStuff',
- * 'url' => 'http://localhost:7231/wikimedia.org/v1/sessions/'
+ * 'url' => 'http://localhost:7231/wikimedia.org/somepath/'
* );
* @endcode
+ *
+ * Configuration for Kask (session storage):
+ * @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 BagOStuff {
+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
*/
private $url;
+ /**
+ * @var array http parameters: readHeaders, writeHeaders, deleteHeaders, writeMethod
+ */
+ private $httpParams;
+
+ /**
+ * Optional serialization type to use. Allowed values: "PHP", "JSON", or "legacy".
+ * "legacy" is PHP serialization with no serialization type tagging or hmac protection.
+ * @var string
+ * @deprecated since 1.34, the "legacy" value will be removed in 1.35.
+ * Use either "PHP" or "JSON".
+ */
+ private $serializationType;
+
+ /**
+ * Optional HMAC Key for protecting the serialized blob. If omitted, or if serializationType
+ * is "legacy", then 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'] = $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 = [
} 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'] ?? 'legacy';
+ $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'], '/' ) . '/';
+
// Default config, R+W > N; no locks on reads though; writes go straight to state-machine
$this->attrMap[self::ATTR_SYNCWRITES] = self::QOS_SYNCWRITES_QC;
}
$req = [
'method' => 'GET',
'url' => $this->url . rawurlencode( $key ),
+ 'headers' => $this->httpParams['readHeaders'],
];
list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $this->client->run( $req );
if ( $rcode === 200 ) {
if ( is_string( $rbody ) ) {
- $value = unserialize( $rbody );
+ $value = $this->decodeBody( $rbody );
/// @FIXME: use some kind of hash or UUID header as CAS token
$casToken = ( $value !== false ) ? $rbody : null;
return false;
}
if ( $rcode === 0 || ( $rcode >= 400 && $rcode != 404 ) ) {
- return $this->handleError( "Failed to fetch $key", $rcode, $rerr );
+ return $this->handleError( "Failed to fetch $key", $rcode, $rerr, $rhdrs, $rbody );
}
return false;
}
- public function set( $key, $value, $exptime = 0, $flags = 0 ) {
+ protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) {
// @TODO: respect WRITE_SYNC (e.g. EACH_QUORUM)
// @TODO: respect $exptime
$req = [
- 'method' => 'PUT',
+ 'method' => $this->httpParams['writeMethod'],
'url' => $this->url . rawurlencode( $key ),
- 'body' => serialize( $value )
+ 'body' => $this->encodeBody( $value ),
+ 'headers' => $this->httpParams['writeHeaders'],
];
+
list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $this->client->run( $req );
if ( $rcode === 200 || $rcode === 201 || $rcode === 204 ) {
return true;
}
- return $this->handleError( "Failed to store $key", $rcode, $rerr );
+ return $this->handleError( "Failed to store $key", $rcode, $rerr, $rhdrs, $rbody );
}
- public function add( $key, $value, $exptime = 0, $flags = 0 ) {
+ protected function doAdd( $key, $value, $exptime = 0, $flags = 0 ) {
// @TODO: make this atomic
if ( $this->get( $key ) === false ) {
return $this->set( $key, $value, $exptime, $flags );
return false; // key already set
}
- public function delete( $key, $flags = 0 ) {
+ protected function doDelete( $key, $flags = 0 ) {
// @TODO: respect WRITE_SYNC (e.g. EACH_QUORUM)
$req = [
'method' => 'DELETE',
'url' => $this->url . rawurlencode( $key ),
+ 'headers' => $this->httpParams['deleteHeaders'],
];
+
list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $this->client->run( $req );
if ( in_array( $rcode, [ 200, 204, 205, 404, 410 ] ) ) {
return true;
}
- return $this->handleError( "Failed to delete $key", $rcode, $rerr );
+ return $this->handleError( "Failed to delete $key", $rcode, $rerr, $rhdrs, $rbody );
}
- public function incr( $key, $value = 1 ) {
+ public function incr( $key, $value = 1, $flags = 0 ) {
// @TODO: make this atomic
$n = $this->get( $key, self::READ_LATEST );
if ( $this->isInteger( $n ) ) { // key exists?
- $n = max( $n + intval( $value ), 0 );
+ $n = max( $n + (int)$value, 0 );
// @TODO: respect $exptime
return $this->set( $key, $n ) ? $n : false;
}
return false;
}
+ public function decr( $key, $value = 1, $flags = 0 ) {
+ return $this->incr( $key, -$value, $flags );
+ }
+
+ /**
+ * 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 ) {
+ if ( $this->serializationType === 'legacy' ) {
+ $serialized = $body;
+ } else {
+ $pieces = explode( '.', $body, 3 );
+ if ( count( $pieces ) !== 3 || $pieces[0] !== $this->serializationType ) {
+ return false;
+ }
+ list( , $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':
+ case 'legacy':
+ 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
+ * @throws LogicException
+ */
+ 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':
+ case "legacy":
+ $value = serialize( $body );
+ break;
+
+ default:
+ throw new \DomainException(
+ "Unknown serialization type: $this->serializationType"
+ );
+ }
+
+ if ( $this->serializationType !== 'legacy' ) {
+ if ( $this->hmacKey !== '' ) {
+ $hmac = base64_encode(
+ hash_hmac( 'sha256', $value, $this->hmacKey, true )
+ );
+ } else {
+ $hmac = '';
+ }
+ $value = $this->serializationType . '.' . $hmac . '.' . $value;
+ }
+
+ return $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)
* @return false
*/
- protected function handleError( $msg, $rcode, $rerr ) {
- $this->logger->error( "$msg : ({code}) {error}", [
+ protected function handleError( $msg, $rcode, $rerr, $rhdrs, $rbody ) {
+ $message = "$msg : ({code}) {error}";
+ $context = [
'code' => $rcode,
'error' => $rerr
- ] );
+ ];
+
+ 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 );
return false;
}
dépôts / lhc / web / wiklou.git / blobdiff