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  * @author Aaron Schulz
  44  * @since 1.23
  45  */
  46 class VirtualRESTServiceClient {
  47         /** @var MultiHttpClient */
  48         protected $http;
  49         /** @var Array Map of (prefix => VirtualRESTService) */
  50         protected $instances = array();
  51
  52         const VALID_MOUNT_REGEX = '#^/[0-9a-z]+/([0-9a-z]+/)*$#';
  53
  54         /**
  55          * @param MultiHttpClient $http
  56          */
  57         public function __construct( MultiHttpClient $http ) {
  58                 $this->http = $http;
  59         }
  60
  61         /**
  62          * Map a prefix to service handler
  63          *
  64          * @param string $prefix Virtual path
  65          * @param VirtualRESTService $instance
  66          */
  67         public function mount( $prefix, VirtualRESTService $instance ) {
  68                 if ( !preg_match( self::VALID_MOUNT_REGEX, $prefix ) ) {
  69                         throw new UnexpectedValueException( "Invalid service mount point '$prefix'." );
  70                 } elseif ( isset( $this->instances[$prefix] ) ) {
  71                         throw new UnexpectedValueException( "A service is already mounted on '$prefix'." );
  72                 }
  73                 $this->instances[$prefix] = $instance;
  74         }
  75
  76         /**
  77          * Unmap a prefix to service handler
  78          *
  79          * @param string $prefix Virtual path
  80          */
  81         public function unmount( $prefix ) {
  82                 if ( !preg_match( self::VALID_MOUNT_REGEX, $prefix ) ) {
  83                         throw new UnexpectedValueException( "Invalid service mount point '$prefix'." );
  84                 } elseif ( !isset( $this->instances[$prefix] ) ) {
  85                         throw new UnexpectedValueException( "No service is mounted on '$prefix'." );
  86                 }
  87                 unset( $this->instances[$prefix] );
  88         }
  89
  90         /**
  91          * Get the prefix and service that a virtual path is serviced by
  92          *
  93          * @param string $path
  94          * @return array (prefix,VirtualRESTService) or (null,null) if none found
  95          */
  96         public function getMountAndService( $path ) {
  97                 $cmpFunc = function( $a, $b ) {
  98                         $al = substr_count( $a, '/' );
  99                         $bl = substr_count( $b, '/' );
 100                         if ( $al === $bl ) {
 101                                 return 0; // should not actually happen
 102                         }
 103                         return ( $al < $bl ) ? 1 : -1; // largest prefix first
 104                 };
 105
 106                 $matches = array(); // matching prefixes (mount points)
 107                 foreach ( $this->instances as $prefix => $service ) {
 108                         if ( strpos( $path, $prefix ) === 0 ) {
 109                                 $matches[] = $prefix;
 110                         }
 111                 }
 112                 usort( $matches, $cmpFunc );
 113
 114                 // Return the most specific prefix and corresponding service
 115                 return isset( $matches[0] )
 116                         ? array( $matches[0], $this->instances[$matches[0]] )
 117                         : array( null, null );
 118         }
 119
 120         /**
 121          * Execute a virtual HTTP(S) request
 122          *
 123          * This method returns a response map of:
 124          *   - code    : HTTP response code or 0 if there was a serious cURL error
 125          *   - reason  : HTTP response reason (empty if there was a serious cURL error)
 126          *   - headers : <header name/value associative array>
 127          *   - body    : HTTP response body or resource (if "stream" was set)
 128          *   - err     : Any cURL error string
 129          * The map also stores integer-indexed copies of these values. This lets callers do:
 130          *      <code>
 131          *              list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $client->run( $req );
 132          *  </code>
 133          * @param array $req Virtual HTTP request maps
 134          * @return array Response array for request
 135          */
 136         public function run( array $req ) {
 137                 $responses = $this->runMulti( array( $req ) );
 138                 return $responses[0];
 139         }
 140
 141         /**
 142          * Execute a set of virtual HTTP(S) requests concurrently
 143          *
 144          * A map of requests keys to response maps is returned. Each response map has:
 145          *   - code    : HTTP response code or 0 if there was a serious cURL error
 146          *   - reason  : HTTP response reason (empty if there was a serious cURL error)
 147          *   - headers : <header name/value associative array>
 148          *   - body    : HTTP response body or resource (if "stream" was set)
 149          *   - err     : Any cURL error string
 150          * The map also stores integer-indexed copies of these values. This lets callers do:
 151          *      <code>
 152          *              list( $rcode, $rdesc, $rhdrs, $rbody, $rerr ) = $responses[0];
 153          *  </code>
 154          *
 155          * @param array $reqs Map of Virtual HTTP request maps
 156          * @return array $reqs Map of corresponding response values with the same keys/order
 157          */
 158         public function runMulti( array $reqs ) {
 159                 foreach ( $reqs as $index => &$req ) {
 160                         if ( isset( $req[0] ) ) {
 161                                 $req['method'] = $req[0]; // short-form
 162                                 unset( $req[0] );
 163                         }
 164                         if ( isset( $req[1] ) ) {
 165                                 $req['url'] = $req[1]; // short-form
 166                                 unset( $req[1] );
 167                         }
 168                         $req['chain'] = array(); // chain or list of replaced requests
 169                 }
 170                 unset( $req ); // don't assign over this by accident
 171
 172                 $curUniqueId = 0;
 173                 $armoredIndexMap = array(); // (original index => new index)
 174
 175                 $doneReqs = array(); // (index => request)
 176                 $executeReqs = array(); // (index => request)
 177                 $replaceReqsByService = array(); // (prefix => index => request)
 178                 $origPending = array(); // (index => 1) for original requests
 179
 180                 foreach ( $reqs as $origIndex => $req ) {
 181                         // Re-index keys to consecutive integers (they will be swapped back later)
 182                         $index = $curUniqueId++;
 183                         $armoredIndexMap[$origIndex] = $index;
 184                         $origPending[$index] = 1;
 185                         if ( preg_match( '#^(http|ftp)s?://#', $req['url'] ) ) {
 186                                 // Absolute FTP/HTTP(S) URL, run it as normal
 187                                 $executeReqs[$index] = $req;
 188                         } else {
 189                                 // Must be a virtual HTTP URL; resolve it
 190                                 list( $prefix, $service ) = $this->getMountAndService( $req['url'] );
 191                                 if ( !$service ) {
 192                                         throw new UnexpectedValueException( "Path '{$req['url']}' has no service." );
 193                                 }
 194                                 // Set the URL to the mount-relative portion
 195                                 $req['url'] = substr( $req['url'], strlen( $prefix ) );
 196                                 $replaceReqsByService[$prefix][$index] = $req;
 197                         }
 198                 }
 199
 200                 // Function to get IDs that won't collide with keys in $armoredIndexMap
 201                 $idFunc = function() use ( &$curUniqueId ) {
 202                         return $curUniqueId++;
 203                 };
 204
 205                 $rounds = 0;
 206                 do {
 207                         if ( ++$rounds > 5 ) { // sanity
 208                                 throw new Exception( "Too many replacement rounds detected. Aborting." );
 209                         }
 210                         // Resolve the virtual URLs valid and qualified HTTP(S) URLs
 211                         // and add any required authentication headers for the backend.
 212                         // Services can also replace requests with new ones, either to
 213                         // defer the original or to set a proxy response to the original.
 214                         $newReplaceReqsByService = array();
 215                         foreach ( $replaceReqsByService as $prefix => $servReqs ) {
 216                                 $service = $this->instances[$prefix];
 217                                 foreach ( $service->onRequests( $servReqs, $idFunc ) as $index => $req ) {
 218                                         // Services use unique IDs for replacement requests
 219                                         if ( isset( $servReqs[$index] ) || isset( $origPending[$index] ) ) {
 220                                                 // A current or original request which was not modified
 221                                         } else {
 222                                                 // Replacement requests with pre-set responses should not execute
 223                                                 $newReplaceReqsByService[$prefix][$index] = $req;
 224                                         }
 225                                         if ( isset( $req['response'] ) ) {
 226                                                 // Replacement requests with pre-set responses should not execute
 227                                                 unset( $executeReqs[$index] );
 228                                                 unset( $origPending[$index] );
 229                                                 $doneReqs[$index] = $req;
 230                                         } else {
 231                                                 // Original or mangled request included
 232                                                 $executeReqs[$index] = $req;
 233                                         }
 234                                 }
 235                         }
 236                         // Update index of requests to inspect for replacement
 237                         $replaceReqsByService = $newReplaceReqsByService;
 238                         // Run the actual work HTTP requests
 239                         foreach ( $this->http->runMulti( $executeReqs ) as $index => $ranReq ) {
 240                                 $doneReqs[$index] = $ranReq;
 241                                 unset( $origPending[$index] );
 242                         }
 243                         $executeReqs = array();
 244                         // Services can also replace requests with new ones, either to
 245                         // defer the original or to set a proxy response to the original.
 246                         // Any replacement requests executed above will need to be replaced
 247                         // with new requests (eventually the original). The responses can be
 248                         // forced instead of having the request sent over the wire.
 249                         $newReplaceReqsByService = array();
 250                         foreach ( $replaceReqsByService as $prefix => $servReqs ) {
 251                                 $service = $this->instances[$prefix];
 252                                 // Only the request copies stored in $doneReqs actually have the response
 253                                 $servReqs = array_intersect_key( $doneReqs, $servReqs );
 254                                 foreach ( $service->onResponses( $servReqs, $idFunc ) as $index => $req ) {
 255                                         // Services use unique IDs for replacement requests
 256                                         if ( isset( $servReqs[$index] ) || isset( $origPending[$index] ) ) {
 257                                                 // A current or original request which was not modified
 258                                         } else {
 259                                                 // Replacement requests with pre-set responses should not execute
 260                                                 $newReplaceReqsByService[$prefix][$index] = $req;
 261                                         }
 262                                         if ( isset( $req['response'] ) ) {
 263                                                 // Replacement requests with pre-set responses should not execute
 264                                                 unset( $origPending[$index] );
 265                                                 $doneReqs[$index] = $req;
 266                                         } else {
 267                                                 // Update the request in case it was mangled
 268                                                 $executeReqs[$index] = $req;
 269                                         }
 270                                 }
 271                         }
 272                         // Update index of requests to inspect for replacement
 273                         $replaceReqsByService = $newReplaceReqsByService;
 274                 } while ( count( $origPending ) );
 275
 276                 $responses = array();
 277                 // Update $reqs to include 'response' and normalized request 'headers'.
 278                 // This maintains the original order of $reqs.
 279                 foreach ( $reqs as $origIndex => $req ) {
 280                         $index = $armoredIndexMap[$origIndex];
 281                         if ( !isset( $doneReqs[$index] ) ) {
 282                                 throw new UnexpectedValueException( "Response for request '$index' is NULL." );
 283                         }
 284                         $responses[$origIndex] = $doneReqs[$index]['response'];
 285                 }
 286
 287                 return $responses;
 288         }
 289 }