MediaWiki  master
VirtualRESTServiceClient.php
Go to the documentation of this file.
1 <?php
48  private $http;
50  private $instances = [];
51 
52  private const VALID_MOUNT_REGEX = '#^/[0-9a-z]+/([0-9a-z]+/)*$#';
53 
57  public function __construct( MultiHttpClient $http ) {
58  $this->http = $http;
59  }
60 
71  public function mount( $prefix, $instance ) {
72  if ( !preg_match( self::VALID_MOUNT_REGEX, $prefix ) ) {
73  throw new UnexpectedValueException( "Invalid service mount point '$prefix'." );
74  } elseif ( isset( $this->instances[$prefix] ) ) {
75  throw new UnexpectedValueException( "A service is already mounted on '$prefix'." );
76  }
77  if ( !( $instance instanceof VirtualRESTService ) ) {
78  if ( !isset( $instance['class'] ) || !isset( $instance['config'] ) ) {
79  throw new UnexpectedValueException( "Missing 'class' or 'config' ('$prefix')." );
80  }
81  }
82  $this->instances[$prefix] = $instance;
83  }
84 
90  public function unmount( $prefix ) {
91  if ( !preg_match( self::VALID_MOUNT_REGEX, $prefix ) ) {
92  throw new UnexpectedValueException( "Invalid service mount point '$prefix'." );
93  } elseif ( !isset( $this->instances[$prefix] ) ) {
94  throw new UnexpectedValueException( "No service is mounted on '$prefix'." );
95  }
96  unset( $this->instances[$prefix] );
97  }
98 
105  public function getMountAndService( $path ) {
106  $cmpFunc = static function ( $a, $b ) {
107  $al = substr_count( $a, '/' );
108  $bl = substr_count( $b, '/' );
109  return $bl <=> $al; // largest prefix first
110  };
111 
112  $matches = []; // matching prefixes (mount points)
113  foreach ( $this->instances as $prefix => $unused ) {
114  if ( strpos( $path, $prefix ) === 0 ) {
115  $matches[] = $prefix;
116  }
117  }
118  usort( $matches, $cmpFunc );
119 
120  // Return the most specific prefix and corresponding service
121  return $matches
122  ? [ $matches[0], $this->getInstance( $matches[0] ) ]
123  : [ null, null ];
124  }
125 
142  public function run( array $req ) {
143  return $this->runMulti( [ $req ] )[0];
144  }
145 
164  public function runMulti( array $reqs ) {
165  foreach ( $reqs as $index => &$req ) {
166  if ( isset( $req[0] ) ) {
167  $req['method'] = $req[0]; // short-form
168  unset( $req[0] );
169  }
170  if ( isset( $req[1] ) ) {
171  $req['url'] = $req[1]; // short-form
172  unset( $req[1] );
173  }
174  $req['chain'] = []; // chain or list of replaced requests
175  }
176  unset( $req ); // don't assign over this by accident
177 
178  $curUniqueId = 0;
179  $armoredIndexMap = []; // (original index => new index)
180 
181  $doneReqs = []; // (index => request)
182  $executeReqs = []; // (index => request)
183  $replaceReqsByService = []; // (prefix => index => request)
184  $origPending = []; // (index => 1) for original requests
185 
186  foreach ( $reqs as $origIndex => $req ) {
187  // Re-index keys to consecutive integers (they will be swapped back later)
188  $index = $curUniqueId++;
189  $armoredIndexMap[$origIndex] = $index;
190  $origPending[$index] = 1;
191  if ( preg_match( '#^(http|ftp)s?://#', $req['url'] ) ) {
192  // Absolute FTP/HTTP(S) URL, run it as normal
193  $executeReqs[$index] = $req;
194  } else {
195  // Must be a virtual HTTP URL; resolve it
196  [ $prefix, $service ] = $this->getMountAndService( $req['url'] );
197  if ( !$service ) {
198  throw new UnexpectedValueException( "Path '{$req['url']}' has no service." );
199  }
200  // Set the URL to the mount-relative portion
201  $req['url'] = substr( $req['url'], strlen( $prefix ) );
202  $replaceReqsByService[$prefix][$index] = $req;
203  }
204  }
205 
206  // Function to get IDs that won't collide with keys in $armoredIndexMap
207  $idFunc = static function () use ( &$curUniqueId ) {
208  return $curUniqueId++;
209  };
210 
211  $rounds = 0;
212  do {
213  if ( ++$rounds > 5 ) {
214  throw new Exception( "Too many replacement rounds detected. Aborting." );
215  }
216  // Track requests executed this round that have a prefix/service.
217  // Note that this also includes requests where 'response' was forced.
218  $checkReqIndexesByPrefix = [];
219  // Resolve the virtual URLs valid and qualified HTTP(S) URLs
220  // and add any required authentication headers for the backend.
221  // Services can also replace requests with new ones, either to
222  // defer the original or to set a proxy response to the original.
223  $newReplaceReqsByService = [];
224  foreach ( $replaceReqsByService as $prefix => $servReqs ) {
225  $service = $this->getInstance( $prefix );
226  foreach ( $service->onRequests( $servReqs, $idFunc ) as $index => $req ) {
227  // Services use unique IDs for replacement requests
228  if ( isset( $servReqs[$index] ) || isset( $origPending[$index] ) ) {
229  // A current or original request which was not modified
230  } else {
231  // Replacement request that will convert to original requests
232  $newReplaceReqsByService[$prefix][$index] = $req;
233  }
234  if ( isset( $req['response'] ) ) {
235  // Replacement requests with pre-set responses should not execute
236  unset( $executeReqs[$index] );
237  unset( $origPending[$index] );
238  $doneReqs[$index] = $req;
239  } else {
240  // Original or mangled request included
241  $executeReqs[$index] = $req;
242  }
243  $checkReqIndexesByPrefix[$prefix][$index] = 1;
244  }
245  }
246 
247  // MultiHttpClient::runMulti opts
248  $opts = [];
249 
250  foreach ( $executeReqs as $index => &$req ) {
251  // Expand protocol-relative URLs
252  if ( preg_match( '#^//#', $req['url'] ) ) {
253  $req['url'] = wfExpandUrl( $req['url'], PROTO_CURRENT );
254  }
255 
256  // Try to find a suitable timeout
257  //
258  // MultiHttpClient::runMulti opts is not per request,
259  // so pick the shortest one
260  if (
261  isset( $req['reqTimeout'] ) &&
262  ( !isset( $opts['reqTimeout'] ) ||
263  $req['reqTimeout'] < $opts['reqTimeout'] )
264  ) {
265  $opts['reqTimeout'] = $req['reqTimeout'];
266  }
267  }
268 
269  // Run the actual work HTTP requests
270  foreach ( $this->http->runMulti( $executeReqs, $opts ) as $index => $ranReq ) {
271  $doneReqs[$index] = $ranReq;
272  unset( $origPending[$index] );
273  }
274  $executeReqs = [];
275  // Services can also replace requests with new ones, either to
276  // defer the original or to set a proxy response to the original.
277  // Any replacement requests executed above will need to be replaced
278  // with new requests (eventually the original). The responses can be
279  // forced by setting 'response' rather than actually be sent over the wire.
280  $newReplaceReqsByService = [];
281  foreach ( $checkReqIndexesByPrefix as $prefix => $servReqIndexes ) {
282  $service = $this->getInstance( $prefix );
283  // $doneReqs actually has the requests (with 'response' set)
284  $servReqs = array_intersect_key( $doneReqs, $servReqIndexes );
285  foreach ( $service->onResponses( $servReqs, $idFunc ) as $index => $req ) {
286  // Services use unique IDs for replacement requests
287  if ( isset( $servReqs[$index] ) || isset( $origPending[$index] ) ) {
288  // A current or original request which was not modified
289  } else {
290  // Replacement requests with pre-set responses should not execute
291  $newReplaceReqsByService[$prefix][$index] = $req;
292  }
293  if ( isset( $req['response'] ) ) {
294  // Replacement requests with pre-set responses should not execute
295  unset( $origPending[$index] );
296  $doneReqs[$index] = $req;
297  } else {
298  // Update the request in case it was mangled
299  $executeReqs[$index] = $req;
300  }
301  }
302  }
303  // Update index of requests to inspect for replacement
304  $replaceReqsByService = $newReplaceReqsByService;
305  } while ( count( $origPending ) );
306 
307  $responses = [];
308  // Update $reqs to include 'response' and normalized request 'headers'.
309  // This maintains the original order of $reqs.
310  foreach ( $reqs as $origIndex => $req ) {
311  $index = $armoredIndexMap[$origIndex];
312  if ( !isset( $doneReqs[$index] ) ) {
313  throw new UnexpectedValueException( "Response for request '$index' is NULL." );
314  }
315  $responses[$origIndex] = $doneReqs[$index]['response'];
316  }
317 
318  return $responses;
319  }
320 
325  private function getInstance( $prefix ) {
326  if ( !isset( $this->instances[$prefix] ) ) {
327  throw new RuntimeException( "No service registered at prefix '{$prefix}'." );
328  }
329 
330  if ( !( $this->instances[$prefix] instanceof VirtualRESTService ) ) {
331  $config = $this->instances[$prefix]['config'];
332  $class = $this->instances[$prefix]['class'];
333  $service = new $class( $config );
334  if ( !( $service instanceof VirtualRESTService ) ) {
335  throw new UnexpectedValueException( "Registered service has the wrong class." );
336  }
337  $this->instances[$prefix] = $service;
338  }
339 
340  return $this->instances[$prefix];
341  }
342 }
const PROTO_CURRENT
Definition: Defines.php:196
wfExpandUrl( $url, $defaultProto=PROTO_CURRENT)
Expand a potentially local URL to a fully-qualified URL using $wgServer (or one of its alternatives).
$matches
Class to handle multiple HTTP requests.
Virtual HTTP service client loosely styled after a Virtual File System.
mount( $prefix, $instance)
Map a prefix to service handler.
unmount( $prefix)
Unmap a prefix to service handler.
run(array $req)
Execute a virtual HTTP(S) request.
runMulti(array $reqs)
Execute a set of virtual HTTP(S) requests concurrently.
__construct(MultiHttpClient $http)
getMountAndService( $path)
Get the prefix and service that a virtual path is serviced by.
Virtual HTTP service instance that can be mounted on to a VirtualRESTService.