includes/libs/objectcache/RESTBagOStuff.php

   1 <?php
   2
   3 use Psr\Log\LoggerInterface;
   4
   5 /**
   6  * Interface to key-value storage behind an HTTP server.
   7  *
   8  * Uses URL of the form "baseURL/{KEY}" to store, fetch, and delete values.
   9  *
  10  * E.g., when base URL is `/sessions/v1`, then the store would do:
  11  *
  12  * `PUT /sessions/v1/12345758`
  13  *
  14  * and fetch would do:
  15  *
  16  * `GET /sessions/v1/12345758`
  17  *
  18  * delete would do:
  19  *
  20  * `DELETE /sessions/v1/12345758`
  21  *
  22  * Minimal generic configuration:
  23  *
  24  * @code
  25  * $wgObjectCaches['sessions'] = array(
  26  *      'class' => 'RESTBagOStuff',
  27  *      'url' => 'http://localhost:7231/wikimedia.org/somepath/'
  28  * );
  29  * @endcode
  30  *
  31  * Configuration for Kask (session storage):
  32  * @code
  33  * $wgObjectCaches['sessions'] = array(
  34  *      'class' => 'RESTBagOStuff',
  35  *      'url' => 'https://kaskhost:1234/sessions/v1/',
  36  *      'httpParams' => [
  37  *              'readHeaders' => [],
  38  *              'writeHeaders' => [ 'content-type' => 'application/octet-stream' ],
  39  *              'deleteHeaders' => [],
  40  *              'writeMethod' => 'POST',
  41  *              'serialization_type' => 'JSON',
  42  *      ],
  43  *      'extendedErrorBodyFields' => [ 'type', 'title', 'detail', 'instance' ]
  44  * );
  45  * $wgSessionCacheType = 'sessions';
  46  * @endcode
  47  */
  48 class RESTBagOStuff extends MediumSpecificBagOStuff {
  49         /**
  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
  52          * permanent failure.
  53          */
  54         const DEFAULT_CONN_TIMEOUT = 1.2;
  55
  56         /**
  57          * Default request timeout
  58          */
  59         const DEFAULT_REQ_TIMEOUT = 3.0;
  60
  61         /**
  62          * @var MultiHttpClient
  63          */
  64         private $client;
  65
  66         /**
  67          * REST URL to use for storage.
  68          * @var string
  69          */
  70         private $url;
  71
  72         /**
  73          * @var array http parameters: readHeaders, writeHeaders, deleteHeaders, writeMethod
  74          */
  75         private $httpParams;
  76
  77         /**
  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.
  80          * @var string
  81          * @deprecated since 1.34, the "legacy" value will be removed in 1.35.
  82          *   Use either "PHP" or "JSON".
  83          */
  84         private $serializationType;
  85
  86         /**
  87          * Optional HMAC Key for protecting the serialized blob. If omitted, or if serializationType
  88          * is "legacy", then no protection is done
  89          * @var string
  90          */
  91         private $hmacKey;
  92
  93         /**
  94          * @var array additional body fields to log on error, if possible
  95          */
  96         private $extendedErrorBodyFields;
  97
  98         public function __construct( $params ) {
  99                 $params['segmentationSize'] = $params['segmentationSize'] ?? INF;
 100                 if ( empty( $params['url'] ) ) {
 101                         throw new InvalidArgumentException( 'URL parameter is required' );
 102                 }
 103
 104                 if ( empty( $params['client'] ) ) {
 105                         // Pass through some params to the HTTP client.
 106                         $clientParams = [
 107                                 'connTimeout' => $params['connTimeout'] ?? self::DEFAULT_CONN_TIMEOUT,
 108                                 'reqTimeout' => $params['reqTimeout'] ?? self::DEFAULT_REQ_TIMEOUT,
 109                         ];
 110                         foreach ( [ 'caBundlePath', 'proxy' ] as $key ) {
 111                                 if ( isset( $params[$key] ) ) {
 112                                         $clientParams[$key] = $params[$key];
 113                                 }
 114                         }
 115                         $this->client = new MultiHttpClient( $clientParams );
 116                 } else {
 117                         $this->client = $params['client'];
 118                 }
 119
 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'] ?? '';
 127
 128                 // The parent constructor calls setLogger() which sets the logger in $this->client
 129                 parent::__construct( $params );
 130
 131                 // Make sure URL ends with /
 132                 $this->url = rtrim( $params['url'], '/' ) . '/';
 133
 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;
 136         }
 137
 138         public function setLogger( LoggerInterface $logger ) {
 139                 parent::setLogger( $logger );
 140                 $this->client->setLogger( $logger );
 141         }
 142
 143         protected function doGet( $key, $flags = 0, &$casToken = null ) {
 144                 $casToken = null;
 145
 146                 $req = [
 147                         'method' => 'GET',
 148                         'url' => $this->url . rawurlencode( $key ),
 149                         'headers' => $this->httpParams['readHeaders'],
 150                 ];
 151
 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;
 158
 159                                 return $value;
 160                         }
 161                         return false;
 162                 }
 163                 if ( $rcode === 0 || ( $rcode >= 400 && $rcode != 404 ) ) {
 164                         return $this->handleError( "Failed to fetch $key", $rcode, $rerr, $rhdrs, $rbody );
 165                 }
 166                 return false;
 167         }
 168
 169         protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) {
 170                 // @TODO: respect WRITE_SYNC (e.g. EACH_QUORUM)
 171                 // @TODO: respect $exptime
 172                 $req = [
 173                         'method' => $this->httpParams['writeMethod'],
 174                         'url' => $this->url . rawurlencode( $key ),
 175                         'body' => $this->encodeBody( $value ),
 176                         'headers' => $this->httpParams['writeHeaders'],
 177                 ];
 178
 179                 list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $this->client->run( $req );
 180                 if ( $rcode === 200 || $rcode === 201 || $rcode === 204 ) {
 181                         return true;
 182                 }
 183                 return $this->handleError( "Failed to store $key", $rcode, $rerr, $rhdrs, $rbody );
 184         }
 185
 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 );
 190                 }
 191
 192                 return false; // key already set
 193         }
 194
 195         protected function doDelete( $key, $flags = 0 ) {
 196                 // @TODO: respect WRITE_SYNC (e.g. EACH_QUORUM)
 197                 $req = [
 198                         'method' => 'DELETE',
 199                         'url' => $this->url . rawurlencode( $key ),
 200                         'headers' => $this->httpParams['deleteHeaders'],
 201                 ];
 202
 203                 list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $this->client->run( $req );
 204                 if ( in_array( $rcode, [ 200, 204, 205, 404, 410 ] ) ) {
 205                         return true;
 206                 }
 207                 return $this->handleError( "Failed to delete $key", $rcode, $rerr, $rhdrs, $rbody );
 208         }
 209
 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;
 217                 }
 218
 219                 return false;
 220         }
 221
 222         public function decr( $key, $value = 1, $flags = 0 ) {
 223                 return $this->incr( $key, -$value, $flags );
 224         }
 225
 226         /**
 227          * Processes the response body.
 228          *
 229          * @param string $body request body to process
 230          * @return mixed|bool the processed body, or false on error
 231          */
 232         private function decodeBody( $body ) {
 233                 if ( $this->serializationType === 'legacy' ) {
 234                         $serialized = $body;
 235                 } else {
 236                         $pieces = explode( '.', $body, 3 );
 237                         if ( count( $pieces ) !== 3 || $pieces[0] !== $this->serializationType ) {
 238                                 return false;
 239                         }
 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 ) ) ) {
 244                                         return false;
 245                                 }
 246                         }
 247                 }
 248
 249                 switch ( $this->serializationType ) {
 250                         case 'JSON':
 251                                 $value = json_decode( $serialized, true );
 252                                 return ( json_last_error() === JSON_ERROR_NONE ) ? $value : false;
 253
 254                         case 'PHP':
 255                         case 'legacy':
 256                                 return unserialize( $serialized );
 257
 258                         default:
 259                                 throw new \DomainException(
 260                                         "Unknown serialization type: $this->serializationType"
 261                                 );
 262                 }
 263         }
 264
 265         /**
 266          * Prepares the request body (the "value" portion of our key/value store) for transmission.
 267          *
 268          * @param string $body request body to prepare
 269          * @return string the prepared body
 270          * @throws LogicException
 271          */
 272         private function encodeBody( $body ) {
 273                 switch ( $this->serializationType ) {
 274                         case 'JSON':
 275                                 $value = json_encode( $body );
 276                                 if ( $value === false ) {
 277                                         throw new InvalidArgumentException( __METHOD__ . ": body could not be encoded." );
 278                                 }
 279                                 break;
 280
 281                         case 'PHP':
 282                         case "legacy":
 283                                 $value = serialize( $body );
 284                                 break;
 285
 286                         default:
 287                                 throw new \DomainException(
 288                                         "Unknown serialization type: $this->serializationType"
 289                                 );
 290                 }
 291
 292                 if ( $this->serializationType !== 'legacy' ) {
 293                         if ( $this->hmacKey !== '' ) {
 294                                 $hmac = base64_encode(
 295                                         hash_hmac( 'sha256', $value, $this->hmacKey, true )
 296                                 );
 297                         } else {
 298                                 $hmac = '';
 299                         }
 300                         $value = $this->serializationType . '.' . $hmac . '.' . $value;
 301                 }
 302
 303                 return $value;
 304         }
 305
 306         /**
 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)
 313          * @return false
 314          */
 315         protected function handleError( $msg, $rcode, $rerr, $rhdrs, $rbody ) {
 316                 $message = "$msg : ({code}) {error}";
 317                 $context = [
 318                         'code' => $rcode,
 319                         'error' => $rerr
 320                 ];
 321
 322                 if ( $this->extendedErrorBodyFields !== [] ) {
 323                         $body = $this->decodeBody( $rbody );
 324                         if ( $body ) {
 325                                 $extraFields = '';
 326                                 foreach ( $this->extendedErrorBodyFields as $field ) {
 327                                         if ( isset( $body[$field] ) ) {
 328                                                 $extraFields .= " : ({$field}) {$body[$field]}";
 329                                         }
 330                                 }
 331                                 if ( $extraFields !== '' ) {
 332                                         $message .= " {extra_fields}";
 333                                         $context['extra_fields'] = $extraFields;
 334                                 }
 335                         }
 336                 }
 337
 338                 $this->logger->error( $message, $context );
 339                 $this->setLastError( $rcode === 0 ? self::ERR_UNREACHABLE : self::ERR_UNEXPECTED );
 340                 return false;
 341         }
 342 }