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