includes/libs/virtualrest/VirtualRESTServiceClient.php

   1 <?php
   2 /**
   3  * Virtual HTTP service client
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  */
  22
  23 /**
  24  * Virtual HTTP service client loosely styled after a Virtual File System
  25  *
  26  * Services can be mounted on path prefixes so that virtual HTTP operations
  27  * against sub-paths will map to those services. Operations can actually be
  28  * done using HTTP messages over the wire or may simple be emulated locally.
  29  *
  30  * Virtual HTTP request maps are arrays that use the following format:
  31  *   - method   : GET/HEAD/PUT/POST/DELETE
  32  *   - url      : HTTP/HTTPS URL or virtual service path with a registered prefix
  33  *   - query    : <query parameter field/value associative array> (uses RFC 3986)
  34  *   - headers  : <header name/value associative array>
  35  *   - body     : source to get the HTTP request body from;
  36  *                this can simply be a string (always), a resource for
  37  *                PUT requests, and a field/value array for POST request;
  38  *                array bodies are encoded as multipart/form-data and strings
  39  *                use application/x-www-form-urlencoded (headers sent automatically)
  40  *   - stream   : resource to stream the HTTP response body to
  41  * Request maps can use integer index 0 instead of 'method' and 1 instead of 'url'.
  42  *
  43  * @since 1.23
  44  */
  45 class VirtualRESTServiceClient {
  46         /** @var MultiHttpClient */
  47         private $http;
  48         /** @var array Map of (prefix => VirtualRESTService|array) */
  49         private $instances = [];
  50
  51         const VALID_MOUNT_REGEX = '#^/[0-9a-z]+/([0-9a-z]+/)*$#';
  52
  53         /**
  54          * @param MultiHttpClient $http
  55          */
  56         public function __construct( MultiHttpClient $http ) {
  57                 $this->http = $http;
  58         }
  59
  60         /**
  61          * Map a prefix to service handler
  62          *
  63          * If $instance is in array, it must have these keys:
  64          *   - class : string; fully qualified VirtualRESTService class name
  65          *   - config : array; map of parameters that is the first __construct() argument
  66          *
  67          * @param string $prefix Virtual path
  68          * @param VirtualRESTService|array $instance Service or info to yield the service
  69          */
  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
  84         /**
  85          * Unmap a prefix to service handler
  86          *
  87          * @param string $prefix Virtual path
  88          */
  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
  98         /**
  99          * Get the prefix and service that a virtual path is serviced by
 100          *
 101          * @param string $path
 102          * @return array (prefix,VirtualRESTService) or (null,null) if none found
 103          */
 104         public function getMountAndService( $path ) {
 105                 $cmpFunc = function ( $a, $b ) {
 106                         $al = substr_count( $a, '/' );
 107                         $bl = substr_count( $b, '/' );
 108                         if ( $al === $bl ) {
 109                                 return 0; // should not actually happen
 110                         }
 111                         return ( $al < $bl ) ? 1 : -1; // largest prefix first
 112                 };
 113
 114                 $matches = []; // matching prefixes (mount points)
 115                 foreach ( $this->instances as $prefix => $unused ) {
 116                         if ( strpos( $path, $prefix ) === 0 ) {
 117                                 $matches[] = $prefix;
 118                         }
 119                 }
 120                 usort( $matches, $cmpFunc );
 121
 122                 // Return the most specific prefix and corresponding service
 123                 return $matches
 124                         ? [ $matches[0], $this->getInstance( $matches[0] ) ]
 125                         : [ null, null ];
 126         }
 127
 128         /**
 129          * Execute a virtual HTTP(S) request
 130          *
 131          * This method returns a response map of:
 132          *   - code    : HTTP response code or 0 if there was a serious cURL error
 133          *   - reason  : HTTP response reason (empty if there was a serious cURL error)
 134          *   - headers : <header name/value associative array>
 135          *   - body    : HTTP response body or resource (if "stream" was set)
 136          *   - error   : Any cURL error string
 137          * The map also stores integer-indexed copies of these values. This lets callers do:
 138          * @code
 139          *     list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $client->run( $req );
 140          * @endcode
 141          * @param array $req Virtual HTTP request maps
 142          * @return array Response array for request
 143          */
 144         public function run( array $req ) {
 145                 return $this->runMulti( [ $req ] )[0];
 146         }
 147
 148         /**
 149          * Execute a set of virtual HTTP(S) requests concurrently
 150          *
 151          * A map of requests keys to response maps is returned. Each response map has:
 152          *   - code    : HTTP response code or 0 if there was a serious cURL error
 153          *   - reason  : HTTP response reason (empty if there was a serious cURL error)
 154          *   - headers : <header name/value associative array>
 155          *   - body    : HTTP response body or resource (if "stream" was set)
 156          *   - error   : Any cURL error string
 157          * The map also stores integer-indexed copies of these values. This lets callers do:
 158          * @code
 159          *     list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $responses[0];
 160          * @endcode
 161          *
 162          * @param array $reqs Map of Virtual HTTP request maps
 163          * @return array $reqs Map of corresponding response values with the same keys/order
 164          * @throws Exception
 165          */
 166         public function runMulti( array $reqs ) {
 167                 foreach ( $reqs as $index => &$req ) {
 168                         if ( isset( $req[0] ) ) {
 169                                 $req['method'] = $req[0]; // short-form
 170                                 unset( $req[0] );
 171                         }
 172                         if ( isset( $req[1] ) ) {
 173                                 $req['url'] = $req[1]; // short-form
 174                                 unset( $req[1] );
 175                         }
 176                         $req['chain'] = []; // chain or list of replaced requests
 177                 }
 178                 unset( $req ); // don't assign over this by accident
 179
 180                 $curUniqueId = 0;
 181                 $armoredIndexMap = []; // (original index => new index)
 182
 183                 $doneReqs = []; // (index => request)
 184                 $executeReqs = []; // (index => request)
 185                 $replaceReqsByService = []; // (prefix => index => request)
 186                 $origPending = []; // (index => 1) for original requests
 187
 188                 foreach ( $reqs as $origIndex => $req ) {
 189                         // Re-index keys to consecutive integers (they will be swapped back later)
 190                         $index = $curUniqueId++;
 191                         $armoredIndexMap[$origIndex] = $index;
 192                         $origPending[$index] = 1;
 193                         if ( preg_match( '#^(http|ftp)s?://#', $req['url'] ) ) {
 194                                 // Absolute FTP/HTTP(S) URL, run it as normal
 195                                 $executeReqs[$index] = $req;
 196                         } else {
 197                                 // Must be a virtual HTTP URL; resolve it
 198                                 list( $prefix, $service ) = $this->getMountAndService( $req['url'] );
 199                                 if ( !$service ) {
 200                                         throw new UnexpectedValueException( "Path '{$req['url']}' has no service." );
 201                                 }
 202                                 // Set the URL to the mount-relative portion
 203                                 $req['url'] = substr( $req['url'], strlen( $prefix ) );
 204                                 $replaceReqsByService[$prefix][$index] = $req;
 205                         }
 206                 }
 207
 208                 // Function to get IDs that won't collide with keys in $armoredIndexMap
 209                 $idFunc = function () use ( &$curUniqueId ) {
 210                         return $curUniqueId++;
 211                 };
 212
 213                 $rounds = 0;
 214                 do {
 215                         if ( ++$rounds > 5 ) { // sanity
 216                                 throw new Exception( "Too many replacement rounds detected. Aborting." );
 217                         }
 218                         // Track requests executed this round that have a prefix/service.
 219                         // Note that this also includes requests where 'response' was forced.
 220                         $checkReqIndexesByPrefix = [];
 221                         // Resolve the virtual URLs valid and qualified HTTP(S) URLs
 222                         // and add any required authentication headers for the backend.
 223                         // Services can also replace requests with new ones, either to
 224                         // defer the original or to set a proxy response to the original.
 225                         $newReplaceReqsByService = [];
 226                         foreach ( $replaceReqsByService as $prefix => $servReqs ) {
 227                                 $service = $this->getInstance( $prefix );
 228                                 foreach ( $service->onRequests( $servReqs, $idFunc ) as $index => $req ) {
 229                                         // Services use unique IDs for replacement requests
 230                                         if ( isset( $servReqs[$index] ) || isset( $origPending[$index] ) ) {
 231                                                 // A current or original request which was not modified
 232                                         } else {
 233                                                 // Replacement request that will convert to original requests
 234                                                 $newReplaceReqsByService[$prefix][$index] = $req;
 235                                         }
 236                                         if ( isset( $req['response'] ) ) {
 237                                                 // Replacement requests with pre-set responses should not execute
 238                                                 unset( $executeReqs[$index] );
 239                                                 unset( $origPending[$index] );
 240                                                 $doneReqs[$index] = $req;
 241                                         } else {
 242                                                 // Original or mangled request included
 243                                                 $executeReqs[$index] = $req;
 244                                         }
 245                                         $checkReqIndexesByPrefix[$prefix][$index] = 1;
 246                                 }
 247                         }
 248                         // Run the actual work HTTP requests
 249                         foreach ( $this->http->runMulti( $executeReqs ) as $index => $ranReq ) {
 250                                 $doneReqs[$index] = $ranReq;
 251                                 unset( $origPending[$index] );
 252                         }
 253                         $executeReqs = [];
 254                         // Services can also replace requests with new ones, either to
 255                         // defer the original or to set a proxy response to the original.
 256                         // Any replacement requests executed above will need to be replaced
 257                         // with new requests (eventually the original). The responses can be
 258                         // forced by setting 'response' rather than actually be sent over the wire.
 259                         $newReplaceReqsByService = [];
 260                         foreach ( $checkReqIndexesByPrefix as $prefix => $servReqIndexes ) {
 261                                 $service = $this->getInstance( $prefix );
 262                                 // $doneReqs actually has the requests (with 'response' set)
 263                                 $servReqs = array_intersect_key( $doneReqs, $servReqIndexes );
 264                                 foreach ( $service->onResponses( $servReqs, $idFunc ) as $index => $req ) {
 265                                         // Services use unique IDs for replacement requests
 266                                         if ( isset( $servReqs[$index] ) || isset( $origPending[$index] ) ) {
 267                                                 // A current or original request which was not modified
 268                                         } else {
 269                                                 // Replacement requests with pre-set responses should not execute
 270                                                 $newReplaceReqsByService[$prefix][$index] = $req;
 271                                         }
 272                                         if ( isset( $req['response'] ) ) {
 273                                                 // Replacement requests with pre-set responses should not execute
 274                                                 unset( $origPending[$index] );
 275                                                 $doneReqs[$index] = $req;
 276                                         } else {
 277                                                 // Update the request in case it was mangled
 278                                                 $executeReqs[$index] = $req;
 279                                         }
 280                                 }
 281                         }
 282                         // Update index of requests to inspect for replacement
 283                         $replaceReqsByService = $newReplaceReqsByService;
 284                 } while ( count( $origPending ) );
 285
 286                 $responses = [];
 287                 // Update $reqs to include 'response' and normalized request 'headers'.
 288                 // This maintains the original order of $reqs.
 289                 foreach ( $reqs as $origIndex => $req ) {
 290                         $index = $armoredIndexMap[$origIndex];
 291                         if ( !isset( $doneReqs[$index] ) ) {
 292                                 throw new UnexpectedValueException( "Response for request '$index' is NULL." );
 293                         }
 294                         $responses[$origIndex] = $doneReqs[$index]['response'];
 295                 }
 296
 297                 return $responses;
 298         }
 299
 300         /**
 301          * @param string $prefix
 302          * @return VirtualRESTService
 303          */
 304         private function getInstance( $prefix ) {
 305                 if ( !isset( $this->instances[$prefix] ) ) {
 306                         throw new RuntimeException( "No service registered at prefix '{$prefix}'." );
 307                 }
 308
 309                 if ( !( $this->instances[$prefix] instanceof VirtualRESTService ) ) {
 310                         $config = $this->instances[$prefix]['config'];
 311                         $class = $this->instances[$prefix]['class'];
 312                         $service = new $class( $config );
 313                         if ( !( $service instanceof VirtualRESTService ) ) {
 314                                 throw new UnexpectedValueException( "Registered service has the wrong class." );
 315                         }
 316                         $this->instances[$prefix] = $service;
 317                 }
 318
 319                 return $this->instances[$prefix];
 320         }
 321 }