MediaWiki REL1_34
RESTBagOStuff.php
Go to the documentation of this file.
1<?php
2
3use Psr\Log\LoggerInterface;
4
55
60
64 private $client;
65
70 private $url;
71
75 private $httpParams;
76
85
91 private $hmacKey;
92
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
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 );
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
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
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
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}
serialize()
const READ_LATEST
Bitfield constants for get()/getMulti(); these are only advisory.
Definition BagOStuff.php:79
LoggerInterface $logger
Definition BagOStuff.php:65
Storage medium specific cache for storing items (e.g.
isInteger( $value)
Check if a value is an integer.
setLastError( $err)
Set the "last error" registry.
Class to handle multiple HTTP requests.
Interface to key-value storage behind an HTTP server.
array $httpParams
http parameters: readHeaders, writeHeaders, deleteHeaders, writeMethod
__construct( $params)
string $serializationType
Optional serialization type to use.
setLogger(LoggerInterface $logger)
decr( $key, $value=1, $flags=0)
Decrease stored value of $key by $value while preserving its TTL.
const DEFAULT_CONN_TIMEOUT
Default connection timeout in seconds.
doSet( $key, $value, $exptime=0, $flags=0)
Set an item.
decodeBody( $body)
Processes the response body.
doAdd( $key, $value, $exptime=0, $flags=0)
Insert an item if it does not already exist.
const DEFAULT_REQ_TIMEOUT
Default request timeout.
doGet( $key, $flags=0, &$casToken=null)
doDelete( $key, $flags=0)
Delete an item.
array $extendedErrorBodyFields
additional body fields to log on error, if possible
incr( $key, $value=1, $flags=0)
Increase stored value of $key by $value while preserving its TTL.
string $hmacKey
Optional HMAC Key for protecting the serialized blob.
encodeBody( $body)
Prepares the request body (the "value" portion of our key/value store) for transmission.
handleError( $msg, $rcode, $rerr, $rhdrs, $rbody)
Handle storage error.
string $url
REST URL to use for storage.
MultiHttpClient $client
$context
Definition load.php:45
foreach( $res as $row) $serialized