3 use Psr\Log\LoggerInterface
;
6 * Interface to key-value storage behind an HTTP server.
8 * Uses URL of the form "baseURL/{KEY}" to store, fetch, and delete values.
10 * E.g., when base URL is `/sessions/v1`, then the store would do:
12 * `PUT /sessions/v1/12345758`
16 * `GET /sessions/v1/12345758`
20 * `DELETE /sessions/v1/12345758`
22 * Minimal generic configuration:
25 * $wgObjectCaches['sessions'] = array(
26 * 'class' => 'RESTBagOStuff',
27 * 'url' => 'http://localhost:7231/wikimedia.org/somepath/'
31 * Configuration for Kask (session storage):
33 * $wgObjectCaches['sessions'] = array(
34 * 'class' => 'RESTBagOStuff',
35 * 'url' => 'https://kaskhost:1234/sessions/v1/',
37 * 'readHeaders' => [],
38 * 'writeHeaders' => [ 'content-type' => 'application/octet-stream' ],
39 * 'deleteHeaders' => [],
40 * 'writeMethod' => 'POST',
41 * 'serialization_type' => 'JSON',
43 * 'extendedErrorBodyFields' => [ 'type', 'title', 'detail', 'instance' ]
45 * $wgSessionCacheType = 'sessions';
48 class RESTBagOStuff
extends MediumSpecificBagOStuff
{
50 * Default connection timeout in seconds. The kernel retransmits the SYN
51 * packet after 1 second, so 1.2 seconds allows for 1 retransmit without
54 const DEFAULT_CONN_TIMEOUT
= 1.2;
57 * Default request timeout
59 const DEFAULT_REQ_TIMEOUT
= 3.0;
62 * @var MultiHttpClient
67 * REST URL to use for storage.
73 * @var array http parameters: readHeaders, writeHeaders, deleteHeaders, writeMethod
78 * Optional serialization type to use. Allowed values: "PHP", "JSON", or "legacy".
79 * "legacy" is PHP serialization with no serialization type tagging or hmac protection.
81 * @deprecated since 1.34, the "legacy" value will be removed in 1.35.
82 * Use either "PHP" or "JSON".
84 private $serializationType;
87 * Optional HMAC Key for protecting the serialized blob. If omitted, or if serializationType
88 * is "legacy", then no protection is done
94 * @var array additional body fields to log on error, if possible
96 private $extendedErrorBodyFields;
98 public function __construct( $params ) {
99 $params['segmentationSize'] = $params['segmentationSize'] ?? INF
;
100 if ( empty( $params['url'] ) ) {
101 throw new InvalidArgumentException( 'URL parameter is required' );
104 if ( empty( $params['client'] ) ) {
105 // Pass through some params to the HTTP client.
107 'connTimeout' => $params['connTimeout'] ?? self
::DEFAULT_CONN_TIMEOUT
,
108 'reqTimeout' => $params['reqTimeout'] ?? self
::DEFAULT_REQ_TIMEOUT
,
110 foreach ( [ 'caBundlePath', 'proxy' ] as $key ) {
111 if ( isset( $params[$key] ) ) {
112 $clientParams[$key] = $params[$key];
115 $this->client
= new MultiHttpClient( $clientParams );
117 $this->client
= $params['client'];
120 $this->httpParams
['writeMethod'] = $params['httpParams']['writeMethod'] ??
'PUT';
121 $this->httpParams
['readHeaders'] = $params['httpParams']['readHeaders'] ??
[];
122 $this->httpParams
['writeHeaders'] = $params['httpParams']['writeHeaders'] ??
[];
123 $this->httpParams
['deleteHeaders'] = $params['httpParams']['deleteHeaders'] ??
[];
124 $this->extendedErrorBodyFields
= $params['extendedErrorBodyFields'] ??
[];
125 $this->serializationType
= $params['serialization_type'] ??
'legacy';
126 $this->hmacKey
= $params['hmac_key'] ??
'';
128 // The parent constructor calls setLogger() which sets the logger in $this->client
129 parent
::__construct( $params );
131 // Make sure URL ends with /
132 $this->url
= rtrim( $params['url'], '/' ) . '/';
134 // Default config, R+W > N; no locks on reads though; writes go straight to state-machine
135 $this->attrMap
[self
::ATTR_SYNCWRITES
] = self
::QOS_SYNCWRITES_QC
;
138 public function setLogger( LoggerInterface
$logger ) {
139 parent
::setLogger( $logger );
140 $this->client
->setLogger( $logger );
143 protected function doGet( $key, $flags = 0, &$casToken = null ) {
148 'url' => $this->url
. rawurlencode( $key ),
149 'headers' => $this->httpParams
['readHeaders'],
152 list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $this->client
->run( $req );
153 if ( $rcode === 200 ) {
154 if ( is_string( $rbody ) ) {
155 $value = $this->decodeBody( $rbody );
156 /// @FIXME: use some kind of hash or UUID header as CAS token
157 $casToken = ( $value !== false ) ?
$rbody : null;
163 if ( $rcode === 0 ||
( $rcode >= 400 && $rcode != 404 ) ) {
164 return $this->handleError( "Failed to fetch $key", $rcode, $rerr, $rhdrs, $rbody );
169 protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) {
170 // @TODO: respect WRITE_SYNC (e.g. EACH_QUORUM)
171 // @TODO: respect $exptime
173 'method' => $this->httpParams
['writeMethod'],
174 'url' => $this->url
. rawurlencode( $key ),
175 'body' => $this->encodeBody( $value ),
176 'headers' => $this->httpParams
['writeHeaders'],
179 list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $this->client
->run( $req );
180 if ( $rcode === 200 ||
$rcode === 201 ||
$rcode === 204 ) {
183 return $this->handleError( "Failed to store $key", $rcode, $rerr, $rhdrs, $rbody );
186 protected function doAdd( $key, $value, $exptime = 0, $flags = 0 ) {
187 // @TODO: make this atomic
188 if ( $this->get( $key ) === false ) {
189 return $this->set( $key, $value, $exptime, $flags );
192 return false; // key already set
195 protected function doDelete( $key, $flags = 0 ) {
196 // @TODO: respect WRITE_SYNC (e.g. EACH_QUORUM)
198 'method' => 'DELETE',
199 'url' => $this->url
. rawurlencode( $key ),
200 'headers' => $this->httpParams
['deleteHeaders'],
203 list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $this->client
->run( $req );
204 if ( in_array( $rcode, [ 200, 204, 205, 404, 410 ] ) ) {
207 return $this->handleError( "Failed to delete $key", $rcode, $rerr, $rhdrs, $rbody );
210 public function incr( $key, $value = 1, $flags = 0 ) {
211 // @TODO: make this atomic
212 $n = $this->get( $key, self
::READ_LATEST
);
213 if ( $this->isInteger( $n ) ) { // key exists?
214 $n = max( $n +
(int)$value, 0 );
215 // @TODO: respect $exptime
216 return $this->set( $key, $n ) ?
$n : false;
222 public function decr( $key, $value = 1, $flags = 0 ) {
223 return $this->incr( $key, -$value, $flags );
227 * Processes the response body.
229 * @param string $body request body to process
230 * @return mixed|bool the processed body, or false on error
232 private function decodeBody( $body ) {
233 if ( $this->serializationType
=== 'legacy' ) {
236 $pieces = explode( '.', $body, 3 );
237 if ( count( $pieces ) !== 3 ||
$pieces[0] !== $this->serializationType
) {
240 list( , $hmac, $serialized ) = $pieces;
241 if ( $this->hmacKey
!== '' ) {
242 $checkHmac = hash_hmac( 'sha256', $serialized, $this->hmacKey
, true );
243 if ( !hash_equals( $checkHmac, base64_decode( $hmac ) ) ) {
249 switch ( $this->serializationType
) {
251 $value = json_decode( $serialized, true );
252 return ( json_last_error() === JSON_ERROR_NONE
) ?
$value : false;
256 return unserialize( $serialized );
259 throw new \
DomainException(
260 "Unknown serialization type: $this->serializationType"
266 * Prepares the request body (the "value" portion of our key/value store) for transmission.
268 * @param string $body request body to prepare
269 * @return string the prepared body
270 * @throws LogicException
272 private function encodeBody( $body ) {
273 switch ( $this->serializationType
) {
275 $value = json_encode( $body );
276 if ( $value === false ) {
277 throw new InvalidArgumentException( __METHOD__
. ": body could not be encoded." );
283 $value = serialize( $body );
287 throw new \
DomainException(
288 "Unknown serialization type: $this->serializationType"
292 if ( $this->serializationType
!== 'legacy' ) {
293 if ( $this->hmacKey
!== '' ) {
294 $hmac = base64_encode(
295 hash_hmac( 'sha256', $value, $this->hmacKey
, true )
300 $value = $this->serializationType
. '.' . $hmac . '.' . $value;
307 * Handle storage error
308 * @param string $msg Error message
309 * @param int $rcode Error code from client
310 * @param string $rerr Error message from client
311 * @param array $rhdrs Response headers
312 * @param string $rbody Error body from client (if any)
315 protected function handleError( $msg, $rcode, $rerr, $rhdrs, $rbody ) {
316 $message = "$msg : ({code}) {error}";
322 if ( $this->extendedErrorBodyFields
!== [] ) {
323 $body = $this->decodeBody( $rbody );
326 foreach ( $this->extendedErrorBodyFields
as $field ) {
327 if ( isset( $body[$field] ) ) {
328 $extraFields .= " : ({$field}) {$body[$field]}";
331 if ( $extraFields !== '' ) {
332 $message .= " {extra_fields}";
333 $context['extra_fields'] = $extraFields;
338 $this->logger
->error( $message, $context );
339 $this->setLastError( $rcode === 0 ? self
::ERR_UNREACHABLE
: self
::ERR_UNEXPECTED
);