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  *      ],
  42  *      'extendedErrorBodyFields' => [ 'type', 'title', 'detail', 'instance' ]
  43  * );
  44  * $wgSessionCacheType = 'sessions';
  45  * @endcode
  46  */
  47 class RESTBagOStuff extends MediumSpecificBagOStuff {
  48         /**
  49          * Default connection timeout in seconds. The kernel retransmits the SYN
  50          * packet after 1 second, so 1.2 seconds allows for 1 retransmit without
  51          * permanent failure.
  52          */
  53         const DEFAULT_CONN_TIMEOUT = 1.2;
  54
  55         /**
  56          * Default request timeout
  57          */
  58         const DEFAULT_REQ_TIMEOUT = 3.0;
  59
  60         /**
  61          * @var MultiHttpClient
  62          */
  63         private $client;
  64
  65         /**
  66          * REST URL to use for storage.
  67          * @var string
  68          */
  69         private $url;
  70
  71         /**
  72          * @var array http parameters: readHeaders, writeHeaders, deleteHeaders, writeMethod
  73          */
  74         private $httpParams;
  75
  76         /**
  77          * @var array additional body fields to log on error, if possible
  78          */
  79         private $extendedErrorBodyFields;
  80
  81         public function __construct( $params ) {
  82                 $params['segmentationSize'] = $params['segmentationSize'] ?? INF;
  83                 if ( empty( $params['url'] ) ) {
  84                         throw new InvalidArgumentException( 'URL parameter is required' );
  85                 }
  86
  87                 if ( empty( $params['client'] ) ) {
  88                         // Pass through some params to the HTTP client.
  89                         $clientParams = [
  90                                 'connTimeout' => $params['connTimeout'] ?? self::DEFAULT_CONN_TIMEOUT,
  91                                 'reqTimeout' => $params['reqTimeout'] ?? self::DEFAULT_REQ_TIMEOUT,
  92                         ];
  93                         foreach ( [ 'caBundlePath', 'proxy' ] as $key ) {
  94                                 if ( isset( $params[$key] ) ) {
  95                                         $clientParams[$key] = $params[$key];
  96                                 }
  97                         }
  98                         $this->client = new MultiHttpClient( $clientParams );
  99                 } else {
 100                         $this->client = $params['client'];
 101                 }
 102
 103                 $this->httpParams['writeMethod'] = $params['httpParams']['writeMethod'] ?? 'PUT';
 104                 $this->httpParams['readHeaders'] = $params['httpParams']['readHeaders'] ?? [];
 105                 $this->httpParams['writeHeaders'] = $params['httpParams']['writeHeaders'] ?? [];
 106                 $this->httpParams['deleteHeaders'] = $params['httpParams']['deleteHeaders'] ?? [];
 107                 $this->extendedErrorBodyFields = $params['extendedErrorBodyFields'] ?? [];
 108
 109                 // The parent constructor calls setLogger() which sets the logger in $this->client
 110                 parent::__construct( $params );
 111
 112                 // Make sure URL ends with /
 113                 $this->url = rtrim( $params['url'], '/' ) . '/';
 114
 115                 // Default config, R+W > N; no locks on reads though; writes go straight to state-machine
 116                 $this->attrMap[self::ATTR_SYNCWRITES] = self::QOS_SYNCWRITES_QC;
 117         }
 118
 119         public function setLogger( LoggerInterface $logger ) {
 120                 parent::setLogger( $logger );
 121                 $this->client->setLogger( $logger );
 122         }
 123
 124         protected function doGet( $key, $flags = 0, &$casToken = null ) {
 125                 $casToken = null;
 126
 127                 $req = [
 128                         'method' => 'GET',
 129                         'url' => $this->url . rawurlencode( $key ),
 130                         'headers' => $this->httpParams['readHeaders'],
 131                 ];
 132
 133                 list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $this->client->run( $req );
 134                 if ( $rcode === 200 ) {
 135                         if ( is_string( $rbody ) ) {
 136                                 $value = $this->decodeBody( $rbody );
 137                                 /// @FIXME: use some kind of hash or UUID header as CAS token
 138                                 $casToken = ( $value !== false ) ? $rbody : null;
 139
 140                                 return $value;
 141                         }
 142                         return false;
 143                 }
 144                 if ( $rcode === 0 || ( $rcode >= 400 && $rcode != 404 ) ) {
 145                         return $this->handleError( "Failed to fetch $key", $rcode, $rerr, $rhdrs, $rbody );
 146                 }
 147                 return false;
 148         }
 149
 150         protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) {
 151                 // @TODO: respect WRITE_SYNC (e.g. EACH_QUORUM)
 152                 // @TODO: respect $exptime
 153                 $req = [
 154                         'method' => $this->httpParams['writeMethod'],
 155                         'url' => $this->url . rawurlencode( $key ),
 156                         'body' => $this->encodeBody( $value ),
 157                         'headers' => $this->httpParams['writeHeaders'],
 158                 ];
 159
 160                 list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $this->client->run( $req );
 161                 if ( $rcode === 200 || $rcode === 201 || $rcode === 204 ) {
 162                         return true;
 163                 }
 164                 return $this->handleError( "Failed to store $key", $rcode, $rerr, $rhdrs, $rbody );
 165         }
 166
 167         public function add( $key, $value, $exptime = 0, $flags = 0 ) {
 168                 // @TODO: make this atomic
 169                 if ( $this->get( $key ) === false ) {
 170                         return $this->set( $key, $value, $exptime, $flags );
 171                 }
 172
 173                 return false; // key already set
 174         }
 175
 176         protected function doDelete( $key, $flags = 0 ) {
 177                 // @TODO: respect WRITE_SYNC (e.g. EACH_QUORUM)
 178                 $req = [
 179                         'method' => 'DELETE',
 180                         'url' => $this->url . rawurlencode( $key ),
 181                         'headers' => $this->httpParams['deleteHeaders'],
 182                 ];
 183
 184                 list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $this->client->run( $req );
 185                 if ( in_array( $rcode, [ 200, 204, 205, 404, 410 ] ) ) {
 186                         return true;
 187                 }
 188                 return $this->handleError( "Failed to delete $key", $rcode, $rerr, $rhdrs, $rbody );
 189         }
 190
 191         public function incr( $key, $value = 1 ) {
 192                 // @TODO: make this atomic
 193                 $n = $this->get( $key, self::READ_LATEST );
 194                 if ( $this->isInteger( $n ) ) { // key exists?
 195                         $n = max( $n + intval( $value ), 0 );
 196                         // @TODO: respect $exptime
 197                         return $this->set( $key, $n ) ? $n : false;
 198                 }
 199
 200                 return false;
 201         }
 202
 203         /**
 204          * Processes the response body.
 205          *
 206          * @param string $body request body to process
 207          * @return mixed|bool the processed body, or false on error
 208          */
 209         private function decodeBody( $body ) {
 210                 $value = json_decode( $body, true );
 211                 return ( json_last_error() === JSON_ERROR_NONE ) ? $value : false;
 212         }
 213
 214         /**
 215          * Prepares the request body (the "value" portion of our key/value store) for transmission.
 216          *
 217          * @param string $body request body to prepare
 218          * @return string the prepared body, or an empty string on error
 219          * @throws LogicException
 220          */
 221         private function encodeBody( $body ) {
 222                 $value = json_encode( $body );
 223                 if ( $value === false ) {
 224                         throw new InvalidArgumentException( __METHOD__ . ": body could not be encoded." );
 225                 }
 226                 return $value;
 227         }
 228
 229         /**
 230          * Handle storage error
 231          * @param string $msg Error message
 232          * @param int $rcode Error code from client
 233          * @param string $rerr Error message from client
 234          * @param array $rhdrs Response headers
 235          * @param string $rbody Error body from client (if any)
 236          * @return false
 237          */
 238         protected function handleError( $msg, $rcode, $rerr, $rhdrs, $rbody ) {
 239                 $message = "$msg : ({code}) {error}";
 240                 $context = [
 241                         'code' => $rcode,
 242                         'error' => $rerr
 243                 ];
 244
 245                 if ( $this->extendedErrorBodyFields !== [] ) {
 246                         $body = $this->decodeBody( $rbody );
 247                         if ( $body ) {
 248                                 $extraFields = '';
 249                                 foreach ( $this->extendedErrorBodyFields as $field ) {
 250                                         if ( isset( $body[$field] ) ) {
 251                                                 $extraFields .= " : ({$field}) {$body[$field]}";
 252                                         }
 253                                 }
 254                                 if ( $extraFields !== '' ) {
 255                                         $message .= " {extra_fields}";
 256                                         $context['extra_fields'] = $extraFields;
 257                                 }
 258                         }
 259                 }
 260
 261                 $this->logger->error( $message, $context );
 262                 $this->setLastError( $rcode === 0 ? self::ERR_UNREACHABLE : self::ERR_UNEXPECTED );
 263                 return false;
 264         }
 265 }