MediaWiki  master
RESTBagOStuff.php
Go to the documentation of this file.
1 <?php
2 
3 use Psr\Log\LoggerInterface;
4 
91  private const DEFAULT_CONN_TIMEOUT = 1.2;
92 
96  private const DEFAULT_REQ_TIMEOUT = 3.0;
97 
101  private $client;
102 
107  private $url;
108 
113  private $httpParams;
114 
119  private $serializationType;
120 
125  private $hmacKey;
126 
130  private $extendedErrorBodyFields;
131 
132  public function __construct( $params ) {
133  $params['segmentationSize'] ??= INF;
134  if ( empty( $params['url'] ) ) {
135  throw new InvalidArgumentException( 'URL parameter is required' );
136  }
137 
138  if ( empty( $params['client'] ) ) {
139  // Pass through some params to the HTTP client.
140  $clientParams = [
141  'connTimeout' => $params['connTimeout'] ?? self::DEFAULT_CONN_TIMEOUT,
142  'reqTimeout' => $params['reqTimeout'] ?? self::DEFAULT_REQ_TIMEOUT,
143  ];
144  foreach ( [ 'caBundlePath', 'proxy' ] as $key ) {
145  if ( isset( $params[$key] ) ) {
146  $clientParams[$key] = $params[$key];
147  }
148  }
149  $this->client = new MultiHttpClient( $clientParams );
150  } else {
151  $this->client = $params['client'];
152  }
153 
154  $this->httpParams['writeMethod'] = $params['httpParams']['writeMethod'] ?? 'PUT';
155  $this->httpParams['readHeaders'] = $params['httpParams']['readHeaders'] ?? [];
156  $this->httpParams['writeHeaders'] = $params['httpParams']['writeHeaders'] ?? [];
157  $this->httpParams['deleteHeaders'] = $params['httpParams']['deleteHeaders'] ?? [];
158  $this->extendedErrorBodyFields = $params['extendedErrorBodyFields'] ?? [];
159  $this->serializationType = $params['serialization_type'] ?? 'PHP';
160  $this->hmacKey = $params['hmac_key'] ?? '';
161 
162  // The parent constructor calls setLogger() which sets the logger in $this->client
163  parent::__construct( $params );
164 
165  // Make sure URL ends with /
166  $this->url = rtrim( $params['url'], '/' ) . '/';
167 
169  }
170 
171  public function setLogger( LoggerInterface $logger ) {
172  parent::setLogger( $logger );
173  $this->client->setLogger( $logger );
174  }
175 
176  protected function doGet( $key, $flags = 0, &$casToken = null ) {
177  $getToken = ( $casToken === self::PASS_BY_REF );
178  $casToken = null;
179 
180  $req = [
181  'method' => 'GET',
182  'url' => $this->url . rawurlencode( $key ),
183  'headers' => $this->httpParams['readHeaders'],
184  ];
185 
186  $value = false;
187  $valueSize = false;
188  [ $rcode, $rdesc, $rhdrs, $rbody, $rerr ] = $this->client->run( $req );
189  if ( $rcode === 200 && is_string( $rbody ) ) {
190  $value = $this->decodeBody( $rbody );
191  $valueSize = strlen( $rbody );
192  // @FIXME: use some kind of hash or UUID header as CAS token
193  if ( $getToken && $value !== false ) {
194  $casToken = $rbody;
195  }
196  } elseif ( $rcode === 0 || ( $rcode >= 400 && $rcode != 404 ) ) {
197  $this->handleError( "Failed to fetch $key", $rcode, $rerr, $rhdrs, $rbody );
198  }
199 
200  $this->updateOpStats( self::METRIC_OP_GET, [ $key => [ 0, $valueSize ] ] );
201 
202  return $value;
203  }
204 
205  protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) {
206  $req = [
207  'method' => $this->httpParams['writeMethod'],
208  'url' => $this->url . rawurlencode( $key ),
209  'body' => $this->encodeBody( $value ),
210  'headers' => $this->httpParams['writeHeaders'],
211  ];
212 
213  [ $rcode, , $rhdrs, $rbody, $rerr ] = $this->client->run( $req );
214  $res = ( $rcode === 200 || $rcode === 201 || $rcode === 204 );
215  if ( !$res ) {
216  $this->handleError( "Failed to store $key", $rcode, $rerr, $rhdrs, $rbody );
217  }
218 
219  $this->updateOpStats( self::METRIC_OP_SET, [ $key => [ strlen( $rbody ), 0 ] ] );
220 
221  return $res;
222  }
223 
224  protected function doAdd( $key, $value, $exptime = 0, $flags = 0 ) {
225  // NOTE: This is non-atomic
226  if ( $this->get( $key ) === false ) {
227  return $this->set( $key, $value, $exptime, $flags );
228  }
229 
230  // key already set
231  return false;
232  }
233 
234  protected function doDelete( $key, $flags = 0 ) {
235  $req = [
236  'method' => 'DELETE',
237  'url' => $this->url . rawurlencode( $key ),
238  'headers' => $this->httpParams['deleteHeaders'],
239  ];
240 
241  [ $rcode, , $rhdrs, $rbody, $rerr ] = $this->client->run( $req );
242  $res = in_array( $rcode, [ 200, 204, 205, 404, 410 ] );
243  if ( !$res ) {
244  $this->handleError( "Failed to delete $key", $rcode, $rerr, $rhdrs, $rbody );
245  }
246 
247  $this->updateOpStats( self::METRIC_OP_DELETE, [ $key ] );
248 
249  return $res;
250  }
251 
252  public function incr( $key, $value = 1, $flags = 0 ) {
253  return $this->doIncr( $key, $value, $flags );
254  }
255 
256  public function decr( $key, $value = 1, $flags = 0 ) {
257  return $this->doIncr( $key, -$value, $flags );
258  }
259 
260  private function doIncr( $key, $value = 1, $flags = 0 ) {
261  // NOTE: This is non-atomic
262  $n = $this->get( $key, self::READ_LATEST );
263  // key exists?
264  if ( $this->isInteger( $n ) ) {
265  $n = max( $n + (int)$value, 0 );
266  return $this->set( $key, $n ) ? $n : false;
267  }
268 
269  return false;
270  }
271 
272  protected function doIncrWithInit( $key, $exptime, $step, $init, $flags ) {
273  // NOTE: This is non-atomic
274  $curValue = $this->doGet( $key );
275  if ( $curValue === false ) {
276  $newValue = $this->doSet( $key, $init, $exptime ) ? $init : false;
277  } elseif ( $this->isInteger( $curValue ) ) {
278  $sum = max( $curValue + $step, 0 );
279  $newValue = $this->doSet( $key, $sum, $exptime ) ? $sum : false;
280  } else {
281  $newValue = false;
282  }
283 
284  return $newValue;
285  }
286 
287  public function makeKeyInternal( $keyspace, $components ) {
288  return $this->genericKeyFromComponents( $keyspace, ...$components );
289  }
290 
291  protected function convertGenericKey( $key ) {
292  // short-circuit; already uses "generic" keys
293  return $key;
294  }
295 
302  private function decodeBody( $body ) {
303  $pieces = explode( '.', $body, 3 );
304  if ( count( $pieces ) !== 3 || $pieces[0] !== $this->serializationType ) {
305  return false;
306  }
307  [ , $hmac, $serialized ] = $pieces;
308  if ( $this->hmacKey !== '' ) {
309  $checkHmac = hash_hmac( 'sha256', $serialized, $this->hmacKey, true );
310  if ( !hash_equals( $checkHmac, base64_decode( $hmac ) ) ) {
311  return false;
312  }
313  }
314 
315  switch ( $this->serializationType ) {
316  case 'JSON':
317  $value = json_decode( $serialized, true );
318  return ( json_last_error() === JSON_ERROR_NONE ) ? $value : false;
319 
320  case 'PHP':
321  return unserialize( $serialized );
322 
323  default:
324  throw new \DomainException(
325  "Unknown serialization type: $this->serializationType"
326  );
327  }
328  }
329 
337  private function encodeBody( $body ) {
338  switch ( $this->serializationType ) {
339  case 'JSON':
340  $value = json_encode( $body );
341  if ( $value === false ) {
342  throw new InvalidArgumentException( __METHOD__ . ": body could not be encoded." );
343  }
344  break;
345 
346  case 'PHP':
347  $value = serialize( $body );
348  break;
349 
350  default:
351  throw new \DomainException(
352  "Unknown serialization type: $this->serializationType"
353  );
354  }
355 
356  if ( $this->hmacKey !== '' ) {
357  $hmac = base64_encode(
358  hash_hmac( 'sha256', $value, $this->hmacKey, true )
359  );
360  } else {
361  $hmac = '';
362  }
363  return $this->serializationType . '.' . $hmac . '.' . $value;
364  }
365 
375  protected function handleError( $msg, $rcode, $rerr, $rhdrs, $rbody ) {
376  $message = "$msg : ({code}) {error}";
377  $context = [
378  'code' => $rcode,
379  'error' => $rerr
380  ];
381 
382  if ( $this->extendedErrorBodyFields !== [] ) {
383  $body = $this->decodeBody( $rbody );
384  if ( $body ) {
385  $extraFields = '';
386  foreach ( $this->extendedErrorBodyFields as $field ) {
387  if ( isset( $body[$field] ) ) {
388  $extraFields .= " : ({$field}) {$body[$field]}";
389  }
390  }
391  if ( $extraFields !== '' ) {
392  $message .= " {extra_fields}";
393  $context['extra_fields'] = $extraFields;
394  }
395  }
396  }
397 
398  $this->logger->error( $message, $context );
399  $this->setLastError( $rcode === 0 ? self::ERR_UNREACHABLE : self::ERR_UNEXPECTED );
400  }
401 }
const READ_LATEST
Bitfield constants for get()/getMulti(); these are only advisory.
Definition: BagOStuff.php:116
setLastError( $error)
Set the "last error" registry due to a problem encountered during an attempted operation.
Definition: BagOStuff.php:529
genericKeyFromComponents(... $components)
At a minimum, there must be a keyspace and collection name component.
Definition: BagOStuff.php:703
LoggerInterface $logger
Definition: BagOStuff.php:89
string $keyspace
Default keyspace; used by makeKey()
Definition: BagOStuff.php:101
Storage medium specific cache for storing items (e.g.
const PASS_BY_REF
Idiom for doGet() to return extra information by reference.
updateOpStats(string $op, array $keyInfo)
isInteger( $value)
Check if a value is an integer.
Class to handle multiple HTTP requests.
Interface to key-value storage behind an HTTP server.
__construct( $params)
convertGenericKey( $key)
Convert a "generic" reversible cache key into one for this cache.
setLogger(LoggerInterface $logger)
decr( $key, $value=1, $flags=0)
Decrease stored value of $key by $value while preserving its TTL.
doSet( $key, $value, $exptime=0, $flags=0)
Set an item.
makeKeyInternal( $keyspace, $components)
Make a cache key for the given keyspace and components.
doIncrWithInit( $key, $exptime, $step, $init, $flags)
doAdd( $key, $value, $exptime=0, $flags=0)
Insert an item if it does not already exist.
doGet( $key, $flags=0, &$casToken=null)
Get an item.
doDelete( $key, $flags=0)
Delete an item.
incr( $key, $value=1, $flags=0)
Increase stored value of $key by $value while preserving its TTL.
handleError( $msg, $rcode, $rerr, $rhdrs, $rbody)
Handle storage error.
const ATTR_DURABILITY
Durability of writes; see QOS_DURABILITY_* (higher means stronger)
const QOS_DURABILITY_DISK
Data is saved to disk and writes do not usually block on fsync()
foreach( $res as $row) $serialized